[SDK/Factories] Stop the factory guide inviting an invented limit (#2353)

* [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>

* docs(factories): fix limit fallback and approval claims in Resource limits

Address review feedback on the Resource limits section:

- "an omitted limit leaves that dimension unbounded" contradicted the
  documented `maxConcurrentSubagents` -> `maxTotalSubagents` fallback in
  factory-patterns.md. Note the exception so a declared total cap is not
  read as leaving concurrency unbounded.
- "the run still needs an approval" is only true for the model-initiated
  `run_factory` path. SDK-initiated `run` and `resume` do not request
  permission (src/factory.ts:292, and the Run and resume section says the
  same), so qualify the claim instead of promising SDK callers a safeguard
  that does not exist.

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

---------

Co-authored-by: examon <examon@users.noreply.github.com>
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, except that an omitted `maxConcurrentSubagents` falls back to `maxTotalSubagents`, so a declared total cap also bounds concurrency.
+
+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 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 of a model-initiated run: `run_factory` requests permission first, and that prompt shows the effective limits. SDK-initiated `run` and `resume` do not request permission, so an SDK caller that wants a ceiling sets it deliberately, from the cost it already knows.
+
+```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");