Repository navigation
fix(subagent): cap concurrent startups, reset start clock at gate exit - #13890
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Re-run the wide (120+) fan-out on this head — the ~50% loss recovery is mechanism-tested, not yet field re-measured. [DESIGN-REVIEWED] 3c9ccd6 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Re-run the 120-item wave on this head: the fix's evidence is the author's own 2026-09-25 measurement, and no test reproduces the measured loss end-to-end. What this change shipsInventory (10 items) — 10 justifiedIntent: stop the startup watchdog from reaping healthy subagents in wide fan-outs by not charging gate-queue time and bounding the in-startup crowd — a FIX. Provenance is strong: base's own
Checked: the bound duplicates nothing — [FIRST-PRINCIPLES-REVIEWED] 3c9ccd6 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- src/kiro_crew/subagent_manager/run.py:1824 -- False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsApproved spawns that the user stops while parked are reported as a gateway admission failure. FINDING — src/kiro_crew/subagent_manager/admission/pump.py:902 — [OPUS-REVIEWED] 3c9ccd6 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
2ed219d to
b6acb08
Compare
b6acb08 to
302191a
Compare
302191a to
80d3395
Compare
9c41f66 to
40aaf77
Compare
40aaf77 to
e0902ee
Compare
A fan-out was bounded by two quantities: subagent_spawn_stagger_secs bounds the RATE of starts and _max_concurrent bounds the RUNNING population. Nothing bounded how many admitted agents were IN STARTUP at once, and the dedicated-process path charged its SessionStartGate queue time to the startup watchdog. On a 623-item fan-out, waves of 24-45 lost ~2% and a wave of 120 lost ~50%, every loss a healthy start recorded as "Failed to start within 120s". Gate clock on both paths: runtime.create_session fires on_gate_queued immediately before the wait for a SessionStartGate permit and on_gate_acquired at gate exit. _run_inner passes _gate_wait_mark(info) / _gate_exit_reset(info) into get_or_create (they ride the provider factory -- NAMED parameters in _acp -- into AcpProvider and from there into the process's own create_session) and _create_shared_session hands the same pair to the parent runtime. The mark stamps _gate_wait_started and the startup watchdog reads the clock as frozen at that moment; the reset clears it and restarts the clock. Invariant: the startup deadline measures time spent starting -- before the gate and with a permit held -- and never time queued for a permit, however long the queue. The wait is finite because every holder is on a running clock from acquisition and is reaped at the base deadline if session/new has not returned, the request has its own budget, and the gate keeps a collector-free headroom of permits. One definition per callback serves both paths. In-startup bound: _startup_cap() = 2 x session_start_concurrency, clamped to [1, cap] (so 1 rather than 0 at a cap of 0 -- the running cap pauses admission there). The bound is tied to the session-start gate and NOT to the running cap because the gate is the one resource every start in startup contends for: G permits serve G starts per round, so 2G (one round holding, one admitted to take over) is the smallest value that never idles the gate and admitting more buys no starts -- only a longer queue of idle admitted starts, whose queue time the frozen clock does not charge. A cap-sized bound (ceil(cap / 4) at cap 64 is 16 against 2 permits) queues seven rounds for two permits. There is no config key for the bound: 2G is both floor and ceiling of the useful range (below idles the gate, above adds only pre-permit wait), so an override could only make it worse, and agent.session_start_concurrency is already the operator's lever -- the bound tracks it. Earlier revisions of this branch used max(2 x G, ceil(cap / 4)) (16 at cap 64 against a 2-permit gate, seven rounds of pre-permit wait) and shipped the bound as agent.subagent_max_concurrent_startups with 0 = derive; both are dropped. The population the bound is checked against is the agents actually STARTING (_exec_started set, no PID / stream / turn) plus a ClaimPoint reservation not yet re-entered and registered. An agent parked at the spawn-approval prompt is NOT counted: it starts nothing, and counting it would let N unanswered prompts stall every spawn on the host, auto-approved ones from unrelated parents included. Its RELEASE is what is bounded, because a bulk trust/yolo grant resolves every pending prompt in one pass: _spawn_with_approval no longer goes straight to _run but awaits _admit_released_start, which appends a resident entry (_resume_id + _startup_release, so every unstarted-spawn scan already leaves it alone) to the EXISTING queue; the pump's first phase (_release_admitted_start, ahead of the capacity check since the run already holds its slot) meters one released start per pass under the same stagger and in-startup checks a fresh spawn faces and stamps the stagger clock; it answers "released" / "held" / "" and the pass continues on every answer, so a held release never withholds a resume grant. A start released while gateway admission is closed is refused, the same guard every registration in the admission package sits behind. A stop while waiting wakes the waiter with False and drops the entry. The watchdog keeps reaping only the executing population (a human prompt has no deadline). _should_stagger_queue gains a third clause and the drain pump holds its pick under the same test; spawns wait in the EXISTING queue. The queue wakes on a runtime PID or first stream (_note_startup_progress) and on the slot-release drain of every terminal, including the watchdog's reap of a wedged start. The watchdog deadline itself stays the fixed _startup_deadline. A pressure-aware deadline (base + base/8 per other agent in startup, 3x ceiling) was in an earlier revision of this branch and is withdrawn: the measurement above predates both changes here, so nothing shows a healthy start still missing the base deadline once queue time stops being charged and the crowd is bounded; and the term was not monotonic -- sampled at sweep time against now - _exec_started, which spans the whole crowded period, it shrank as the crowd drained and could reap at one sweep an agent the previous sweep had left inside its window. The reaper's warning keeps the in-startup population as diagnostics only.
… clock dynamic-subagent-sizing.md: describe the in-startup bound (2 x the session-start gate's width, clamped to [1, cap] so 1 at a cap of 0), say why it is gate-tied rather than cap-tied (the pre-permit wait the gate-exit reset cannot exclude) and why it has no config key (2G is floor and ceiling of the useful range; session_start_concurrency is the lever), correct the sentence that called the cap a startup count limit (it bounds the running population), and state the gate-clock invariant (the startup deadline never counts time queued for a permit: the clock freezes at gate entry and restarts at acquisition) and why the wait is finite. Record that the deadline stays fixed and why a pressure-aware one was withdrawn. subagent.md: the admission invariant (including why an approval-parked agent is NOT in the bounded population and how its release is metered through the pump, and why an unregistered reservation is), the dedicated-path gate-exit reset and the fixed-deadline invariant.
e0902ee to
3c9ccd6
Compare
|
Post-merge record: this landed while I was composing the write-up, so the verification below finished after it merged and the approve it was headed for would have gated nothing. Posting it as a record instead. Verdict had it still been open: approve. No blocking findings. The one real gap is a missing test, which is now a follow-up on Verified against source at this head, not the description
🟡 [Test coverage] Follow-up on
|
Supersedes #13762. It was opened at the same head
2ed219d8fdwith the identical diff; this PR has since moved tob6acb084da, where the pressure-aware deadline was withdrawn in response to the First Principles review (see Withdrawn below). That PR was raised from a fork, where it could not reach readiness:Backend Lint & Type Check (3.12)was killed withexit 143in itsblackstep (oom_kill 0) on fork PRs generally — reproduced on #13738 and #13737, not only on mine — and the four review lanes (GPT 5.6, Opus 5, Internal Content Scan, Security Scope) reported "could not run" /[scope-floor:unsettled]with no re-runnable workflow available. Zero code findings were outstanding when it was re-raised here; the one real finding (semgrep.kirocrew.mock-pid-allocatable) was fixed on this head.Problem / Motivation
A wide sub-agent fan-out loses a large share of its members to a false
Failed to start within 120s (no runtime launched, no turn produced)while the members are healthy and merely slow to start.Measured on a 623-item fan-out (2026-09-25), success rate by wave size:
Every loss in the 120-wave was reported as the startup-watchdog error above, and the losses clustered at task-list positions beyond the live concurrency cap.
Root cause, read from the code:
_should_stagger_queue_impl(subagent_manager/admission/pump.py) queues a spawn on exactly two conditions: no free slot, or a spawn started withinsubagent_spawn_stagger_secs. The stagger bounds the RATE of admissions._max_concurrentbounds the RUNNING population.model/reasoning_effortspawn is a dedicated process (~3-5s, ~400 MB); itssession/newthen queues behindSessionStartGate(agent.session_start_concurrency, default 2), so the gate serves 2 starts persession/newround-trip. The decisive mechanism is the mismatch between the ADMISSION rate and the gate's THROUGHPUT, not the stagger value. If one round-trip takes ~10-20s under provider throttling the gate serves ~0.1-0.2 starts/s; at the stock stagger of 0.25s (config/sections.py) admission delivers 4/s, at a 2.0s stagger 0.5/s. The queue at the gate grows either way, and the tail waits minutes._create_shared_session(shared-runtime path) passeson_gate_acquiredso_exec_startedis reset at gate exit and gate queue time is excluded; the dedicated path (get_or_create, which everymodel/reasoning_effortspawn takes -- exactly the measured waves) had no such callback. TheSessionStartGatebounds outstandingsession/newRPCs, not admission: agents were still admitted, still counted as running, still burning the deadline while parked at the gate._is_startup_stalled_impl) reaped at_startup_deadline(120s) measured from admission, so on the dedicated path the whole gate wait counted. A healthy start past 120s -> reaped -> recorded as a failure (terminal.py) -> the orchestrator re-dispatches -> more startup pressure -> more false reaps. That loop is the ~50%.The measured host did NOT run the stock stagger: its
config.jsonsetssubagent_spawn_stagger_secs: 2.0(andmax_subagents: 64), so admissions arrived every 2.0s and a cap of ~37 filled over ~74s -- and it still lost ~50% of a 120-wave. That is the stronger evidence: slowing admission down by 8x does not fix it, because a smaller stagger only makes the pile-up arrive faster; the admission/throughput mismatch and the charged gate wait are what create it. A stock install at 0.25s is worse.Why it matters
Anyone running a fan-out wider than the live cap on a host where starts are slow (model-pinned spawns, a busy session-start gate, provider throttling) loses roughly half the wave to a watchdog that was meant to catch wedged handshakes, and the retries the losses provoke keep the crowd that caused them alive. The failure text blames the run, so operators chase the provider instead of admission.
What changed (motivation → approach → change)
Two changes, each verified against the code before adding. A third (a pressure-aware watchdog deadline) was in an earlier revision of this PR and has been removed; see "Withdrawn" below.
0 -- the startup clock never counts time queued for a gate permit, on either path.
runtime.create_sessionfires two callbacks around itsSessionStartGatewait:on_gate_queuedimmediately before the wait for a permit begins, andon_gate_acquiredat gate EXIT with the queue wait.RunEventCoordinator._gate_wait_mark_impl(info)stamps_gate_wait_startedon the first, and while it is set_is_startup_stalledreads the start clock as frozen at that moment;_gate_exit_reset_impl(info)clears it and restarts the clock (_exec_started/last_activity, records_start_queue_wait_ms) on the second._create_shared_sessionhands the pair to the parent runtime'screate_sessiondirectly;_run_innerpasses both intoget_or_create, and they rideextra_factory_kwargsto the provider factory (config/loader.py_acp, where both are NAMED parameters -- the**_kwargscatch-all would otherwise swallow them silently), intoAcpProvider(on_gate_acquired=, on_gate_queued=), and from_start_kiro_runtime_implinto the dedicated process's ownruntime.create_session(...). Not passed toload_session: asession/loadresume takes no gate permit. Every other factory caller passes nothing and getsNone, whichcreate_sessiontreats as absent.Invariant enforced (GPT span=599ab81e58eb, "the startup cap does not bound pre-permit wait" -- correct, and this is the fix): the startup deadline measures time spent STARTING -- before the gate (a process spawn on the dedicated path) and with a permit held (
session/new) -- and never time queued for a permit, however long the queue. A start wedged before the gate is on a running clock and is reaped at the base deadline; a start queued at the gate is not reaped for waiting; a start wedged after its permit is reaped at the base deadline from gate exit. The earlier form of the argument ("the last waiter's pre-permit wait is one round, and a round is bounded by the deadline") does not hold and is gone from every docstring and doc: a holder's clock resets at acquisition, so asession/newtaking 119s is not reaped, the permit stays held, and a waiter's un-reset clock keeps accumulating -- a healthy waiter could be reaped exactly as it was about to be served. Freezing the waiter's clock removes the charge instead of trying to bound the round. The wait itself is finite without a deadline of its own: every permit holder is on a running clock from acquisition and is reaped at the base deadline if itssession/newhas not returned (_pidis set only aftercreate_sessionreturns), the request has its own budget (agent.session_start_timeout_secs), and the gate keeps a headroom of permits noStartCollectormay hold (collector_hold_ceiling).A -- bound the in-startup population (structural).
SubagentManager._startup_cap()bounds how many admitted agents may be in startup at once; there is no config key for it (see below)._should_stagger_queue_implgains a third clause:_startup_population() >= _startup_cap()queues the spawn exactly as a full cap does, and_drain_queue_sync_implholds its pick under the same test (after the resume grants -- a resume is not a start). No second queueing mechanism: the spawn waits in the existing queue / durable window._in_startup(info)mirrors the watchdog's own shape:_exec_startedset,turns == 0,_pid is None,_first_stream_started is None, not done / reaping._startup_population()also counts_startup_reservations: a durable-storeClaimPointreserved before its claim is awaited and registered only on the re-entry that skips the gate. A queued spawn is not in it (not registered until admitted), and neither is an agent PARKED at the spawn-approval prompt.2 × session_start_concurrency, clamped to[1, cap]-- tied to the session-start GATE, not to the running cap. The gate is the one resource every start in startup contends for:session/newruns underGpermits, so at mostGstarts make progress at any moment, and every other admitted start is a spawned process (dedicated path) or a claimed slot holding nothing but a place in the gate's queue. With change 0 the queue's length reaps nothing, so what the bound decides is how much of the running cap may sit in startup contending forGpermits at once.2Gis the smallest value that never idles the gate -- one round holding permits and one round already admitted to take them the moment they free -- and admitting more buys no starts, since the gate servesGper round however many are queued: it only lengthens the queue and grows the population of admitted-but-idle starts (each a live process on the dedicated path). A cap-derived term (max(2 × G, ceil(cap / 4)), say) would do exactly that: at cap 64 it admits 16 against a 2-permit gate, seven rounds queued for two permits. At the default gate width of 2 the bound is 4 at cap 8, 40 and 64 alike;capbelow 4; 1 at a cap of0(an adaptive squeeze -- the running cap, not this bound, pauses admission there).session_start_concurrencyisrestart=True, so it is captured at construction only; the bound tracks the gate that actually exists. It also coincides with the SessionManager's dedicated cold-start semaphore (_MAX_CONCURRENT_COLD_STARTS = 4).2Gis both the floor and the ceiling of the useful range: fewer than2Gidles the gate between rounds (no next round already admitted when the current one releases), and more than2Gbuys no starts -- the gate servesGper round however many are queued behind it -- only a longer queue of idle admitted starts. A knob could therefore only make the system worse, and the operator's real lever already exists:agent.session_start_concurrencysizes the gate, and the bound tracks it.config/sections.py,config/loader.py's agent block,config-baseline.jsonandconfiguration.mdare unchanged frommain;LIVE_CONFIG_PATHS/apply_limitsgain nothing (a cap change re-clamps the derived value)._startup_cap()'s docstring states this reason so the absence is explained, not silent._spawn_with_approvalused to go from approval straight to_run; a bulk grant (tool_approval:bulk_trust/bulk_yoloinchat_handlers.py) resolves EVERY pending prompt in one pass, so a whole wave admitted to park entered startup together. The previous head counted parked agents while parked; that closed the flood but self-inflicted the converse -- at the default bound of 4, four ignored prompts queued every other spawn on the host, auto-approved ones from unrelated parents included, with no load needed to trigger it. Now a parked agent consumes nothing (it is starting nothing), and its release re-enters through the pump:_spawn_with_approvalawaits_admit_released_start, which appends a resident entry to the EXISTING queue (_resume_id+_startup_release+ the waiter, so every unstarted-spawn scan -- queued-stop, refill census, eviction, continuation lookup -- already leaves it alone) and waits oninfo._start_release. The pump's first phase,_release_admitted_start, meters ONE released start per pass under the same stagger and_startup_population() >= _startup_cap()test a fresh spawn faces, stamps_last_spawn_ts, and re-arms at the stagger boundary. It answers"released","held"or""(none waiting) and the pass CONTINUES on every answer (Opus span=dff7a69117d0, correct: a phase that ended the pass on its hold withheld the resume grants andpick_window_indexfor as long as the bound stayed full): a resume waits on a lane slot, never on the startup bound or the stagger, so the grants run whether a start was released or is being held, and the fresh-spawn pick applies the same two checks itself. It runs before the capacity check (the run already holds its slot; at a full capany_slotis False and a released start would otherwise wait on itself) and before the resume grants (it is older than anything admitted after it); a start whose prompt resolves while gateway admission is closed is refused at release (spawn rejected: the gateway closed admission before this approved spawn could start) -- the sameadmission_closedguard every registration in the admission package sits behind, which is also what makes the released-start queue append the sixth registration site intest_update_check_install_aware.py's admission/census contract;pick_window_indexand the resume-first loop skip it, and it does not arm the child reserve. While it waits it is registered, holds its running slot and shows in its parent's queue depth; it joins_startup_populationonly when released. A stop or reap while waiting wakes it with False and drops its entry (_force_reapnames the state: "waiting to be admitted into startup after spawn approval"); a slow self-re-arming re-pump (_RELEASE_REPUMP_SECS, 1s) backs the edge-driven wake so a swallowed pump failure cannot strand it. The watchdog stays blind to parked and released-waiting agents (a human prompt has no deadline). Every other path into_run-- yolo,approval_mode="auto", parent trust,hooks.auto_approve_subagent_spawn,POST /api/spawn, the MCP tools,spawn_continue-- creates its run task insidespawn()immediately after the gate, so none had the hole; the cancel-recovery respawn re-runs an already-admitted run._force_reapsetsdone(which removes it from the population) and then takes the slot-release path interminal.py, which already calls_drain_queue(). The pump also wakes on the two non-terminal exits from startup -- a runtime PID and the first provider stream -- via_note_startup_progressfrom_run_inner(three call sites, at most twice per start; the first-stream site fires only on turn 0). A held drain arms no timer: every edge that frees a startup slot already pumps, so a timer would only poll for those same edges.Subagent queued (...)log line now carriesin_startup=n/capso a hold is diagnosable.Withdrawn -- a pressure-aware startup deadline. An earlier revision of this PR also made
_is_startup_stalled_implcompare againstbase + base/8 × (other agents in startup), capped at 3× the base. It is removed, for two reasons, both raised in review and both correct:otherswas sampled at SWEEP time but compared againstnow - _exec_started, which spans the whole crowded period, so the effective deadline SHRANK as the crowd drained: an agent inside a 225s window at one sweep could be reaped at the next under 120s. Removing the term dissolves the defect rather than patching it.The watchdog therefore compares against the fixed
_startup_deadline, exactly as onmain;terminal.pyis unchanged frommain. The reaper's warning now also names the in-startup population, as diagnostics only. If a future measurement WITH changes 0 and A in force shows healthy starts reaped at the base deadline, that measurement is the place to start a pressure term from -- and any such term must be latched per agent so a granted window can only grow.Not changed: the
_exec_startedkeying of the watchdog (documented as load-bearing) and the shared path's gate-exit reset semantics (only its definition moved)._start_sem(_MAX_CONCURRENT_COLD_STARTS = 4, the SessionManager's cold-start semaphore) is acquired BEFOREspawn()+create_sessionon the dedicated path, so gate exit is downstream of it and the reset covers that wait too.This is a defect fix in an existing mechanism (the watchdog reaping starts it was never meant to reap), not a product-shape change; the new key defaults to the derived bound and the derived bound leaves any cap ≤ 3 untouched.
Backwards compatibility
Compatible: no key is added, renamed, removed or narrowed -- the config schema,
config-baseline.jsonandconfiguration.mdare unchanged frommain.AcpProvider.__init__and the_acpfactory gain one optional keyword defaulting toNone; every existing caller is unchanged. The only observable difference is that a fan-out wider than the startup bound (4 at the default gate width) is admitted into startup one gate round at a time instead of piling in at once; admission throughput is unchanged, since the gate already served onlyGstarts per round. The startup deadline itself is unchanged.Tests
New
test/test_subagent_startup_pressure.py(42 tests); plus one intest_session_start_gate.py, a shape assertion foron_gate_queuedintest_headless_memory_recognition.py, andtest_update_check_install_aware.py's admission/census contract updated to six subagent registration sites (the sixth: the released-start queue append in_admit_released_start_impl, behind the sameadmission_closedguard):TestInStartupPredicate-- the predicate's shape; a queued or approval-parked agent is NOT in it (and the watchdog is blind to it); every way out of it (including a mid-run tool prompt);_startup_populationcounts only registered agents and honoursexclude;test_a_reservation_counts_until_its_info_is_registered(aClaimPointreservation holds the gate untilrelease_reservation).TestStartupCap-- the derivation table (test_derives_two_gate_rounds_clamped_to_the_cap, 8 cases incl. cap 0, cap 3, and cap 64 at gate widths 2 and 4),test_derived_bound_does_not_grow_with_the_cap(caps 8..128 all derive 4 at gate width 2),test_there_is_no_config_key_for_the_bound(no schema field, not inLIVE_CONFIG_PATHS, no manager setting;apply_limitsonly re-clamps).TestGateHoldsAtTheStartupCap(gate width 1, bound 2) --_should_stagger_queuereturns(True, True)while startup is full (held, slot still free), opens when one agent records a PID, and a reaped wedged agent no longer counts.test_ignored_prompts_do_not_block_an_unrelated_auto_approved_spawn-- through the REAL_spawn_with_approval(no yolo, no parent trust, no hook auto-approve; anon_spawn_approvalthat parks each prompt on a future): cap 8, gate width 1 (bound 2), FOUR prompted spawns nobody answers, then anapproval_mode="auto"spawn from another parent starts at once, and the bound still meters the auto path itself. Fails on the head that counted parked agents.test_bulk_approval_cannot_release_more_than_the_startup_cap-- same harness: four prompted spawns all park (population 0, four slots held); every pending prompt is resolved in one pass with trust flipped on, exactly as the bulk grant does -> two enter_run, two wait as_startup_releaseentries in the existing queue, each released on PID progress. Fails on the head with no metering (all four entered_runtogether).test_a_released_start_that_is_stopped_while_waiting_never_runs-- a released start reaped while waiting for the bound ends without a run and its entry is dropped.test_queue_holds_at_the_startup_cap_and_resumes_on_progress-- end to end throughspawn()with a_runthat enters startup and parks: cap 8, gate width 1 (bound 2), four spawns -> two start, two wait in the existing queue with six free slots; each PID admits the next.test_queue_drains_after_the_watchdog_reaps_a_wedged_start-- gate width 1 (bound 2), two wedged starts and a waiter:_force_reap(reason="startup_timeout")on one wedged start drains the queue and the waiter starts; the error names the 120s deadline.TestWatchdogIgnoresTheCrowd-- a lone wedged agent is reaped at the base deadline; four peers in startup buy a wedged agent no extra time; and the monotonicity invariant the withdrawn term violated: an agent inside its window at one sweep with peers present is still inside it at the next after every peer has left.test_reaper_sweep_reaps_at_the_base_deadline_under_a_crowd(one real_reaper_loopsweep with_REAPER_INTERVAL=0, two agents in startup): the one past the base deadline is reaped understartup_timeoutat +125s -- the point where the withdrawn term would have granted 135s -- while its within-deadline peer is left alone.TestGateExitResetIsOneDefinition-- the reset moves_exec_started/last_activityand records the wait; the watchdog measures from gate exit (200s queued + 100s starting is not stalled; wedged 120.5s after the permit IS reaped);test_the_clock_does_not_run_while_queued_for_a_permit(30s into its start, a run waits 400s for a permit and is not reaped; at acquisition the clock restarts from zero);test_a_start_wedged_before_the_gate_keeps_its_running_clock; the shared path'son_gate_queued/on_gate_acquiredare_gate_wait_mark's /_gate_exit_reset's.test_session_start_gate.py::test_gate_entry_callback_fires_before_the_wait_and_exit_after-- against the realAcpRuntime.create_sessionand a filled gate:on_gate_queuedfires while queued,on_gate_acquiredonly after a permit frees, thensession/newgoes out.test_a_held_release_does_not_starve_a_queued_resume-- gate width 1 (bound 2), two starts fill the bound, a third released from its prompt is held; a running worker yields its lane slot (yield_slot, rowrunning -> waiting_children) and requests a resume: the resume is granted on the same pass that holds the release. Fails on the head whose release phase ended the pass on a hold.TestDedicatedPathGateExitReset--test_run_inner_hands_get_or_create_the_gate_exit_reset(a model-pinned_run_innerpasses callableon_gate_acquiredANDon_gate_queuedintoget_or_create; the mark freezes and the reset restarts this run's clock);test_provider_factory_names_the_kwarg_and_forwards_it(both named in_acp, forwarded toAcpProvider,Nonewhen absent);test_acp_provider_forwards_the_reset_to_its_own_create_session(real_start_kiro_runtimeagainst a fake runtime:create_sessionreceives both callbacks,load_sessionis not used);test_a_provider_built_without_the_callback_passes_none.Removed with the withdrawn mechanism:
TestPressureAwareDeadline(5),TestWatchdogUnderPressure(4),test_force_reap_error_names_the_deadline_that_fired,test_reaper_sweep_records_the_fired_deadline_before_reaping.Unchanged and green:
test/test_subagent_startup_watchdog.py(all),test/test_subagent_coverage.py::TestStartupStall(managers withstartup_timeout=10) -- the watchdog's deadline arithmetic is untouched frommain.Ran locally: the whole
test_subagent*,test_taskq*,test_spawn*,test_overload*,test_session*,test_acp_provider*set (6050 passed) plus the config suites (test_config_baseline,test_config_loader,test_configuration_doc_defaults,test_config_schema,test_config_api,test_config_live,test_subagent_config_hot_reload,test_adaptive_startup_memory,test_admission_gate,test_fairness_lanes: 991 passed;test_headless_memory_recognition,test_session_start_gate,test_session_sharinggreen);black --check,isort --check-only,flake8,mypy src/kiro_crew/(no issues),scripts/docs_lint.py(passed),BRAND_BASE_REF=origin/main scripts/check_brand_name.py(clean),COMMENT_HISTORY_BASE_REF=origin/main scripts/check_comment_history.py(clean).Manual verification
N/A -- unit coverage sufficient: the admission hold, the wake edges, the reap-drain path and the deadline arithmetic are all exercised through the real manager, gate, pump and reaper loop; the measured numbers above are the field evidence this reproduces the mechanism of.
Related Issues
no linked issue: this was found by running the fan-out, not from a filed report, and the evidence is the measurement in Problem / Motivation above rather than a tracker item.
Pattern harvest
Rule candidate: review-prompt
Pattern: "a fixed timeout guarding a step whose duration scales with concurrent contenders (queue depth at a shared gate) -- start the clock after the contended wait and bound the contenders at admission; do not widen the timeout by a term sampled at check time, which is not monotonic and has no measurement behind it once the first two are in place".
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)src/kiro_crew/docs/dynamic-subagent-sizing.md(the sentence calling the cap "a startup count limit" corrected to a running-population bound; a section on the three bounds, when gate queue time stops being charged, and why the watchdog deadline stays fixed),docs/system-specs/modules/subagent.md(admission invariant, dedicated-path gate-exit reset, fixed-deadline invariant)