feat: raise the subagent timeout default and turn-budget ceiling

[bolichen97]

Problem

Two subagent limits cut work that was still making progress:

• Wall clock. _TIMEOUT_SECS was 30 minutes, so a long refactor, a full test-suite run, or a wide investigation was reaped mid-work. The partial result survives on disk, but the parent gets a timeout instead of an answer.
• Turn budget. SUBAGENT_MAX_TURNS_CEILING was 200, and it bounds both the load-time clamp on agent.subagent_max_turns and the per-spawn max_turns override. An operator who wanted more could not have it at any layer, config or per-call.

Change

• agent.subagent_timeout_secs default 1800 → 10800 (3 hours), with one owner: constants.SUBAGENT_TIMEOUT_SECS. The dataclass default, the loader fallback and subagent.py's _TIMEOUT_SECS all read it instead of restating the number.
• SUBAGENT_MAX_TURNS_CEILING 200 → 1000. The load-time clamp, the PUT /api/config/kirocrew gate and the dashboard number input follow it. SPAWN_RUN_SCHEMA / SPAWN_CONTINUE_SCHEMA now bound max_turns by that constant instead of restating 200.
• The MCP gateway's hard-wedge ceiling moves with the deadline it was sized against. HARD_WEDGE_CEILING_SECS was 2100.0 — literally "wait_max (1800s) + 5-min margin", tuned to the old subagent ceiling. A blocking spawn_sub_agents is in flight for as long as its slowest member runs, so at 3 hours the old ceiling recycled the backend under a caller whose work was healthy: the parent got backend gone while the subagent kept running detached and its result was stranded. It is now derived (SUBAGENT_TIMEOUT_SECS + 300) and pinned by a test that asserts the relationship rather than a literal.
• agent.subagent_timeout_secs joins _SECURITY_BOUNDED_FIELDS (60s..86400s, the max matching CHAT_TURN_TIMEOUT_MAX). It governs how long one subagent holds a concurrency slot, so with a 6x larger default an inflated on-disk value — a direct config.json edit by any same-uid process — is a resource-exhaustion vector rather than a preference. This closes the gap the first revision merely documented.
• Setting help and subagents.md name the remaining interaction: a blocking spawn_sub_agents call is still bounded by agent.chat_turn_timeout_secs (2 h default, 24 h max), so that has to be raised too when a batch must be awaited inside one turn. spawn_run is fire-and-forget and unaffected.
• One test fix that is not mine but failed on this PR: test_snapshot.py's fresh-gateway ordering test hooked "the first O_CREAT open anywhere" and so fired on whatever file the host happened to create first, queueing its delivery before the copy had taken the executor. The trigger is now anchored to the notifications destination, verified with a decoy-file negative control.

What is deliberately NOT changed

• Nothing is uncapped. The reaper still force-kills at the deadline, both knobs are clamped at load and rejected by the config API out of range, and subagent_auto_max (64), max_subagents and spawn_min_memory_gb are untouched.
• _WAVE_STUCK_SECS stays at 1800s. It is a lost-submission backstop that only fires once every registered member is already terminal, so it never cuts a live member. The spec prose calling it "symmetric with the per-agent hard ceiling" was the only thing that broke, and it is corrected.
• DIGEST_HOLD_SECS stays at 120s. Clamped to _TIMEOUT_SECS, so raising the ceiling only widens what an operator may opt into; the 120s latency trigger is what bounds straggler silence, and it is now the only thing between a hung member and 3 hours of quiet.

Review findings

Adjudicated rather than waved through:

• GPT 5.6 F1 (blocking) — UPHELD and fixed. The hard-wedge interaction above was real; backend.py's own comment named the 1800s sizing it was tuned to.
• GPT 5.6 F2 (non-blocking) — REBUTTED. It says "raise that too" is ineffective beyond an "independent 7200s maximum". 7200 is chat_turn_timeout_secs' default; CHAT_TURN_TIMEOUT_MAX is 86400, and the loader clamps to that, so raising it is effective up to 24 hours. The help text is accurate.
• First Principles — accepted. The three restated 10800 literals are now one owner, subagent.py's stale "(30 min)" comment is fixed, and the PR body claim that the dashboard input "already read the constant" was wrong and is gone.
• Design Review — accepted. subagent_timeout_secs is in the clamp table.
• UX Review — see the screenshot note below.

Why no screenshot: the only change under website/src/ outside the locale catalogs is the max attribute on the existing "Max turns per subagent" number input (200 → 1000) and the i18n KEY name beside it. A number input's max is not rendered text. The visible string ("… (1–1000). Default: 100.") lives entirely in website/src/i18n/locales/**, which this repo's own ux-review-required ruleset excludes from UX review — so there is no non-excluded rendered delta to photograph. No control is added, moved, resized or state-swapped, which the UX reviewer independently confirmed from the diff.

Verification

• Full pytest: 229 failures, none of them in the modules this diff touches (no config, subagent, mcp_gateway, validation or constants test file appears in the set). They are this host's standing families — PlatformCompositionError from an enterprise profile with no companion installed, and host-uid isolation checks — reproduced on a stashed clean tree in the previous round (85 failures across four of the worst-hit files alone). test_snapshot.py now passes in full.
• isort, flake8, mypy --platform linux (1301 files), the black / subprocess-encoding / sync-io-in-async diff-scoped gates, docs-lint.sh, scrub-lint.sh, check_harness_parity.py: clean.
• Frontend: tsc -b, eslint, vitest run --coverage (29435 passed), npm run i18n:check with and without I18N_BASE_REF — all 14 checks ok, en-XA.json regenerated through i18n:pseudo.
• config-baseline.json regenerated by its own script.

Pattern harvest

A constant whose comment states what it was sized against has a dependency the type system cannot see. HARD_WEDGE_CEILING_SECS = 2100.0 # wait_max (1800s) + 5-min margin was correct when written and became a data-loss bug the moment another file's number moved, because nothing linked the two.

Rule candidate: when a limit is derived from another limit, derive it in code from that limit's constant and pin the RELATIONSHIP in a test, rather than writing the arithmetic result with the derivation in a comment.

[github-actions]

UX Review (Fable 5) — ✅ PASS

UX-level review of 206794a86972eba52e902c60cf91a9a5e2d22ed8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Reconciliation complete. The blind read didn't run and no screenshots exist, but I verified independently (two-dot diff against the base tree) that this PR's entire frontend delta is one numeral inside an existing tooltip ("1–200" → "1–1000", updated consistently across all 13 locales) and the matching max attribute on the existing "Max turns per subagent" input — no control added, moved, re-labeled, or state-swapped, so there is no comprehension surface a blind read could test. The App.tsx/appNotificationBadges files in the three-dot diff are shared history with #9015, already in the base. Backend help copy (sections.py, subagents.md) matches the actual 7200s blocking-wait clamp in spawn.py, and both surfaces give the same actionable advice ("use spawn_run for longer work").

UX-Verdict: PASS

Only rendered delta is a bound numeral in an existing tooltip, consistent across all locales and true to the backend clamp; nothing new to comprehend.

Suggestions

• sections.py subagent_timeout_secs help: "0 uses the same default." has no referent — "same" as what? Replace with "0 uses the built-in default." (the old string resolved it with "(1800s)"; the new one drops the anchor).

[UX-REVIEWED] 206794a

[github-actions]

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 206794a86972eba52e902c60cf91a9a5e2d22ed8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Sound single-owner consolidation, but the wedge ceiling is sized against a premise the PR's own docs contradict, and one described fix has no code in the diff.

Watch

• Phantom description: the test_snapshot.py fix is not in this diff. The description details it ("anchored to the notifications destination, verified with a decoy-file negative control") and claims it "now passes in full", but the branch touches no snapshot test — either rebased out (the flake will still fail) or landed elsewhere; reconcile the description.
• The wedge-ceiling derivation contradicts this PR's own docs. subagents.md says a blocking spawn_sub_agents "collects for at most 2 hours regardless of that setting" (spawn.py:1041 clamps max_wait to 7200s), yet backend.py's new comment sizes HARD_WEDGE_CEILING_SECS on "in flight for as long as its slowest member runs." If the 7200s cap is the true longest legitimate request, the backstop widened 2100s→11100s when ~7500s suffices — a stuck-but-pinging backend now wedges every caller ~3h before recycle — and the comment/test pin a causal relationship that doesn't hold. Resolve which statement is true and size/document against that one.
• A hung (not failed) subagent now holds a concurrency slot 3h by default instead of 30min; stall detection flags but never reaps, so a few wedged members can exhaust the default pool for hours. Accepted trade, but worth a human eye.

[DESIGN-REVIEWED] 206794a

[github-actions]

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 206794a86972eba52e902c60cf91a9a5e2d22ed8 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All verification is complete. The single SubagentManager construction site (slack/gateway.py:8480) passes default_timeout=self._cfg.agent.subagent_timeout_secs, so the new clamp guards a key with a real runtime consumer; the described test_snapshot.py fix exists only on main (d7fb9c5, #9047), not in this diff; and mcp_tools/spawn.py:1041 hard-clamps the blocking wait to 7200s, which contradicts the PR body's F2 rebuttal but matches the help text the diff ships.

First-Principles-Verdict: CONCERNS

The resolve_prompt_timeout behavior change ships undeclared, and the PR body's account of what bounds a blocking spawn_sub_agents contradicts the help text the diff itself ships.

What this change ships

Intent: let subagents run long enough to finish real work without being reaped mid-progress — a limits ADDITION carrying one genuine FIX (the hard-wedge coupling).

1. Subagent deadline default 30 min → 3 h (wait_for + reaper) — justified
2. Turn-budget ceiling 200 → 1000 across load clamp, config API, spawn schemas, dashboard input — justified
3. MCP backend wedge-recycle now derived as subagent deadline + 5 min, pinned by relationship test — cause-level, justified
4. subagent_timeout_secs joins the load-time tamper clamp (60..86400, 0 sentinel kept) — justified (documented same-uid boundary; consumer: slack/gateway.py:8486)
5. Shared ACP transport wait now rises to cover the subagent deadline (acp/client.py) — undeclared
6. Timeout default owned once in constants.SUBAGENT_TIMEOUT_SECS (was 3 literals) — justified
7. Help text/docs explain the blocking-call 2 h cap vs spawn_run — justified
8. i18n key + 13 locale catalogs follow the 1–1000 tooltip — rides along (mechanical)
9. Described test_snapshot.py fix — not in this diff (already on main via fix(test): read the copy ordering before the worker is released #9047)

Watch

• configured = max(float(agent.chat_turn_timeout_secs), subagent) in resolve_prompt_timeout is a behavior change (an operator who lowered chat_turn_timeout_secs no longer bounds the transport wait below the subagent deadline) that appears nowhere in the description's Change list — declare it or a human never reviews it.
• The body's F2 rebuttal ("raising [chat_turn_timeout_secs] is effective up to 24 hours") and bullet "bounded by agent.chat_turn_timeout_secs … has to be raised too" contradict the shipped help ("collects for at most 2 hours whatever this is set to") and mcp_tools/spawn.py:1041, which clamps the blocking wait to min(7200, …). The shipped text is the correct one; the adjudication prose is wrong against the code.
• "One test fix … test_snapshot.py" describes work absent from this diff (it landed on main as d7fb9c5); verification claims should not cover changes the PR does not carry.

[FIRST-PRINCIPLES-REVIEWED] 206794a

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed 206794a86972eba52e902c60cf91a9a5e2d22ed8 — this comment is updated in place on each push.

Review details

The change is internally consistent: the manager normalizes the 0 sentinel to _TIMEOUT_SECS (gateway.py:8486 → __init__'s default_timeout if default_timeout > 0 else _TIMEOUT_SECS), matching resolve_prompt_timeout's float(...) or float(SUBAGENT_TIMEOUT_SECS); the load-time clamp preserves 0 and floors non-zero values; the wedge ceiling (11100s) sits above the 7200s blocking-spawn cap; the i18n rename is complete across all 13 locales with no orphan; and the prototype-pollution/isAppNavId hazards are closed at both the accumulator and the merged read. The discovery pass's "No candidates" holds under independent falsification, and I found no groundable Step-2 addition at the 80+ bar.

No findings.

[OPUS-REVIEWED] 206794a

Verdict parsed from the review's SHA-scoped output markers for commit 206794a86972eba52e902c60cf91a9a5e2d22ed8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 206794a86972eba52e902c60cf91a9a5e2d22ed8: <one-sentence reason>

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 206794a86972eba52e902c60cf91a9a5e2d22ed8 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/config/loader.py:1683 -- subagent_timeout_secs=-1 becomes the "0" sentinel, yielding 10800s instead of the documented 60s minimum -> Fix: preserve exact zero only; clamp all other values to SUBAGENT_TIMEOUT_MIN.
FINDING -- src/kiro_crew/mcp_gateway/backend.py:193 -- "raises ... re-opens that gap" contradicts the 7200s cap on blocking spawn_sub_agents calls -> Fix: describe the blocking tool’s capped wait as the binding limit.
[GPT-REVIEWED] 206794a

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 206794a86972eba52e902c60cf91a9a5e2d22ed8: <one-sentence reason>

[bolichen97]

Both GPT 5.6 findings on c082db3f5 are VERIFIED and fixed in 7ef091762. F2 also retracts my rebuttal from the previous round — that rebuttal was wrong.

F1 (blocking) — the 0 sentinel. Confirmed exactly as described. SubagentManager.__init__ normalizes 0 to _TIMEOUT_SECS, and the field's help text documents 0 as "use the default" — but the clamp table entry I added carried SUBAGENT_TIMEOUT_MIN as its floor, so _clamp_security_bounds and _safe_int both rewrote a documented sentinel to 60, handing a healthy subagent a one-minute deadline. Fixed the way max_subagents already handles its own 0 sentinel:

• the table floor is 0, so the generic range clamp leaves it alone;
• a new special case raises only a non-zero value below the floor up to it;
• the coercion site goes through _subagent_timeout_from, which bounds the value but preserves 0 — needed because the raw-dict clamp skips non-int values, so a numeric string "0" only meets a bound here.

Pinned by test_subagent_timeout_zero_sentinel_survives_the_clamp, which asserts both the int and numeric-string forms of 0 survive AND that 5 / "5" still clamp up to 60.

F2 (non-blocking) — I was wrong last round, you were right. I rebutted this by arguing that chat_turn_timeout_secs has a 86400 max so raising it is effective. That is true of the turn ceiling and irrelevant here: spawn_sub_agents has its own cap, independent of any config key — KIROCREW_SPAWN_SUB_AGENTS_MAX_WAIT, clamped max(60.0, min(7200.0, …)) in mcp_tools/spawn.py. A blocking collection therefore ends at 2 hours no matter what the subagent deadline or the turn ceiling say, and my help text was telling operators to raise a knob that cannot move it.

Corrected in both places it appeared. The setting help and subagents.md now say a blocking spawn_sub_agents collects for at most 2 hours regardless of this setting, name the env var and its own 7200s cap, and point at spawn_run (fire-and-forget, results arrive as completion events) for anything longer.

Local gates on 7ef091762: black / isort / flake8 / mypy --platform linux (1301 files) / docs-lint clean, config-baseline.json regenerated, and 618 tests across the config, subagent, validator and baseline modules pass.

[bolichen97]

GPT 5.6 F1 on 7ef091762 is VERIFIED and fixed in 6f49d32c7.

Traced it end to end and the mismatch is real on stock config: a subagent's outer deadline is SUBAGENT_TIMEOUT_SECS (10800), but _run_inner calls client.stream(msg) with no explicit timeout, so the transport wait resolves through resolve_prompt_timeout() -> prompt_timeout_for_ceiling(chat_turn_timeout_secs=7200) -> 7200. The transport cuts first and the failure surfaces as a transport error rather than the deadline the operator configured.

Fix, and why it is not the plumbing the finding suggested. Passing a per-call timeout down through client.stream would mean a new argument on the LLMProvider.stream ABC, i.e. new mechanism on the Kiro path for every harness. It is also not where the bug lives. resolve_prompt_timeout exists precisely to keep this ONE shared wait above the deadlines layered on top of it, and its own docstring already names subagents as a sharer — it just bounded against the turn ceiling alone. It now bounds against the LARGER of chat_turn_timeout_secs and subagent_timeout_secs (resolving the 0 sentinel the same way the manager does), so every prompt dispatch that shares the wait is covered, with no signature change anywhere.

Three tests added, and the invariant is pinned against the constant rather than a literal so raising either default cannot silently reopen it:

• the subagent term binds when it is the larger one (7200 ceiling + 10800 subagent -> 10800 + margin);
• the 0 sentinel resolves to SUBAGENT_TIMEOUT_SECS, not to an instantly-dead prompt;
• the shared wait strictly outlives the stock subagent deadline.

The existing turn-ceiling cases keep measuring the ceiling term alone: the fixture's subagent value defaults to the loader's own 60s floor, which never binds.

Same class as the two already fixed on this branch (the MCP gateway hard-wedge ceiling, and the blocking spawn_sub_agents cap the help text was wrong about). Local gates on 6f49d32c7: black / isort / flake8 / mypy --platform linux / docs-lint clean, 1489 tests across the ACP client, prompt-timeout, config, subagent and gateway-wedge modules pass.

[bolichen97]

Frontend Tests (3) went red on 6f49d32c7, and the cause is not in this PR's diff: main itself fails deadKeys.test.ts, and every pull request merge-tested against it inherits the failure.

Pinned it from the shard's own blob artifact (the job log is not readable while the run is in flight, but frontend-blob-3 is uploaded even for a failed shard):

AssertionError: 30 catalog keys are referenced nowhere (baseline 29).

Reproduced the ratchet's own scan on three trees to place the blame:

tree	dead keys
this branch alone, pre-rebase	29
origin/main alone	30
the merge CI actually tests	30

The extra key is pages.chatPage.dismiss_upload_error. Its last reference was the hand-rolled dismiss button in ChatPane, removed by #8859 (route error states through ErrorNotice, batch components-1); the key stayed behind in all 13 catalogs. So main has been sitting one over its own baseline since that merge, and the red lands on whoever opens the next PR.

Fixed by deletion, not by raising the baseline — the gate's own doctrine is ratchet DOWN, never up, and 30 -> 29 lands exactly on the existing BASELINE = 29, so the constant is untouched. The reference scan is authoritative here for the reason the test documents: dynamicKeys.test.ts forbids assembling a key at runtime, and a search finds no dynamic construction of this one.

Order mattered. The key is still LIVE on the pre-rebase branch (25 commits behind, so ChatPane still referenced it there) — deleting it first would have created a missing-key lookup. This is therefore rebased onto origin/main first, then the key removed, then en-XA.json regenerated through i18n:pseudo.

Verified on 24b455647: deadKeys.test.ts green at 29, all 14 i18n:check gates ok, tsc -b clean, plus the backend floor (black / isort / flake8 / mypy --platform linux / docs-lint, config-baseline.json regenerated, 772 tests across config, prompt-timeout, subagent, gateway-wedge, snapshot and validator).