[SDK/Factories] Stop the factory guide inviting an invented limit

Both guide documents are served verbatim to the model by the
factories_manage "guide" operation, and read literally they tell it to pick
a resource ceiling for a factory whose cost it cannot estimate.

factories.md opened on a defineFactory sample with all four ceilings filled
in, which teaches the numbers as much as the syntax, and the Scaling section
of factory-patterns.md answered "there is no built-in concurrency cap" with
"so declare one before fanning out widely". A guessed ceiling does not make
a run safer: it stops a healthy run partway with factory_limit_reached,
after that run has already taken the user's approval and spent credits, and
the caller then raises the ceiling a step at a time.

Drop limits from the opening sample and document the declaration syntax in
the Resource limits section instead, where the rule sits next to it. State
that a ceiling comes from real knowledge of the cost or from the user, and
that omitting limits does not remove oversight, since a run still needs an
approval whose prompt shows the effective limits. Redirect the Scaling
remedy from declaring a cap to bounding the fan-out with the factory's own
counters.

The API documentation is unchanged: every limit keeps its own description,
and limits stay declarable for an author who does know the cost profile.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: examon

nodejs/docs/factories.md

@@ -23,12 +23,6 @@ const reviewChanged = defineFactory({
                 files: { type: "array", items: { type: "string" } },
             },
         },
-        limits: {
-            maxConcurrentSubagents: 3,
-            maxTotalSubagents: 10,
-            timeoutSeconds: 90.5,
-            maxAiCredits: 5,
-        },
     },
     run: async (ctx) => {
         ctx.phase("Review");
@@ -121,7 +115,14 @@ See [factory-patterns.md](./factory-patterns.md) for composable orchestration pa
 
 ## Resource limits
 
-Limits may be declared in `meta.limits` and overridden per invocation. All limits must be positive when present.
+Limits may be declared in `meta.limits` and overridden per invocation. Every limit is optional and must be positive when present; an omitted limit leaves that dimension unbounded.
+
+Set a ceiling only from real knowledge of what the factory costs, or because the user named one. A guessed ceiling does not make a run safer: it stops a healthy run partway with `factory_limit_reached`, after that run has already taken the user's approval and spent credits. An agent authoring or invoking a factory on the user's behalf has no basis for estimating a number, so it should leave `limits` unset and bound the work with the factory's own counters instead. Omitting limits does not remove oversight, because the run still needs an approval and that prompt shows the effective limits first.
+
+```js
+// Only when the cost profile is known, or the user asked for this ceiling.
+limits: { maxTotalSubagents: 10 },
+```
 
 - `maxConcurrentSubagents`: Positive integer concurrent-subagent cap. Additional subagents wait in a queue. Queueing applies backpressure and does not fail the run.
 - `maxTotalSubagents`: Positive integer cumulative admission cap. An attempted subagent beyond the cap ends the attempt with failure kind `maxTotalSubagents`.

nodejs/docs/factory-patterns.md

@@ -189,6 +189,6 @@ Compose these freely.
 
 Match the orchestration to what was asked. A quick check wants a couple of subagents and single-vote verification; a request to be thorough or comprehensive wants a larger finder pool, a three-to-five vote adversarial pass, and a synthesis stage.
 
-There is no in-script budget object. Scale with your own counters, as in the loop patterns above, and treat the declared limits as the safety ceiling rather than the control mechanism. Only `agent()` spawns are throttled, by `maxConcurrentSubagents` falling back to `maxTotalSubagents`; with neither declared there is no built-in concurrency cap, so declare one before fanning out widely. `parallel` itself is `Promise.all`, so non-agent work in a thunk runs fully concurrently regardless.
+There is no in-script budget object. Scale with your own counters, as in the loop patterns above, and treat any declared limits as the safety ceiling rather than the control mechanism. Only `agent()` spawns are throttled, by `maxConcurrentSubagents` falling back to `maxTotalSubagents`; with neither declared there is no built-in concurrency cap, so bound a wide fan-out with the factory's own counters. Do not invent a ceiling to compensate, and see [Resource limits](./factories.md#resource-limits) for when declaring one is appropriate. `parallel` itself is `Promise.all`, so non-agent work in a thunk runs fully concurrently regardless.
 
 These patterns are not exhaustive. Compose novel harnesses — tournament brackets, self-repair loops, staged escalation — when the task calls for it.

nodejs/test/factory.test.ts

@@ -403,6 +403,34 @@ describe("factories", () => {
         expect(generatedRpc).toContain("timeoutSeconds?: number;");
     });
 
+    // A guessed ceiling does not make a run safer: it stops a healthy run partway
+    // with `factory_limit_reached`, after that run has already taken the user's
+    // approval and spent credits. Both documents are handed to the model verbatim
+    // by the `factories_manage` guide, so neither may read as an invitation to
+    // invent one.
+    it("documents limits as opt-in rather than inviting an invented ceiling", () => {
+        const guide = readFileSync(new URL("../docs/factories.md", import.meta.url), "utf8");
+        const patterns = readFileSync(
+            new URL("../docs/factory-patterns.md", import.meta.url),
+            "utf8"
+        );
+
+        expect(guide).toContain(
+            "Set a ceiling only from real knowledge of what the factory costs, or because the user named one"
+        );
+        expect(guide).toContain("no basis for estimating a number");
+
+        // The opening `defineFactory` sample is the shape an author copies. Filling
+        // all four ceilings in there taught the numbers as much as the syntax.
+        const openingSample = guide.slice(0, guide.indexOf("## Declaring an argument shape"));
+        expect(openingSample).not.toContain("limits: {");
+
+        // The Scaling section used to answer "there is no built-in concurrency cap"
+        // with "so declare one before fanning out widely".
+        expect(patterns).not.toContain("declare one before fanning out widely");
+        expect(patterns).toContain("bound a wide fan-out with the factory's own counters");
+    });
+
     it("documents factory invocation and list paging behavior accurately", () => {
         const guide = readFileSync(new URL("../docs/factories.md", import.meta.url), "utf8");
         const publicApi = readFileSync(new URL("../src/factory.ts", import.meta.url), "utf8");