Repository navigation
fix(windows): reclaim runtime trees after root exit - #12005
Conversation
|
Intent: Reclaim verified Windows agent/MCP descendant trees when their runtime root exits first, and preserve exact cleanup identity through a failed attempt until the existing maintenance path can finish. |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The quarantine's process-wide start refusal is stricter than its named harm — the 64-slot admission cap this same PR adds already bounds that debt. Not justified as shipped
What this change shipsInventory (10 items) — 8 justifiedIntent: Closing a Windows session must actually stop its agent/MCP children even when the root already exited, with the cleanup bookkeeping bounded — a FIX (reproduction described, native failing-on-base Windows tests added, PR #11935 linked).
The change has a few more minor differences (client reset refusing an unretired cleanup, sweep guards for pinned rows); list capped at 10, those fold into items 2 and 10. The deleted pin [FIRST-PRINCIPLES-REVIEWED] 67f12d2 |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify Windows CI shards are green on this head — backend batches 4–27 were not run locally, and the native capture test must execute, not skip. [DESIGN-REVIEWED] 67f12d2 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
|
|
|
|
Historical response: the GPT rerun replaced finding 60eee5df9fed in place on the same SHA. Retained below for context; this is not a disposition of the new retention-cap finding.
|
|
|
The author has approved adding a separate Windows cleanup-capacity admission budget to address eeb991b58a1d. New physical starts may be refused at saturation and resume after verified cleanup releases capacity. Existing owned handles must not be evicted, and existing pool size, RSS, timeout and resource Job settings stay unchanged. Implementation and regression verification are in progress; this records scope consent, not a review override or a claim that the blocker is fixed. |
|
The author has accepted manual handling for extreme descendant-budget overflow. Normal verified trees and transient failures keep automatic cleanup/retry. If observing a tree would exceed the bounded identity budget, preserve existing pins/tracking, mark cleanup unresolved, do not infer success or automatically refund that capacity, and refuse new Windows physical starts while manual handling is required. This is bookkeeping quarantine, NOT OS isolation or proof that unobserved descendants stopped. Existing pool/RSS/timeout/Job settings remain unchanged. This records scope consent, not a review override or completed repair. |
9639bee to
c22c148
Compare
c22c148 to
29eeeff
Compare
29eeeff to
da93ada
Compare
da93ada to
8418639
Compare
First Principles disposition —
|
First Principles disposition —
|
…e harness Four reds on the first push, each its own thing: - mypy: `policy` was read back out of `extra`, whose values are a mix of strings and counts, so it typed as the union where the outcome row wants a string. Bound to a local `str` and used at both sites. - `test_security_posture` omission guard: `tool_risk.py` calls a redactor and was classified as neither sink nor allowlisted. Registered as a SINK, not allowlisted, and the entry states why it differs from its own sibling `decisions/gate.py`: the gate SCANS the same request and refuses on a hit, emitting nothing, while this module scrubs and the scrubbed bytes are what leaves the machine. - cross-layer settings fixture: it held the card's one point EQUAL to the whole backend tuple, which only worked while the seam shipped one point. Now membership plus "and not the annotating point", which is what the test's own name and docstring already claimed -- membership alone would accept a card naming `tool.risk` as the live point and promising the switch changes a decision it does not touch. - locale style gates: the French strings used a plain space before double punctuation instead of U+202F, and the Bengali one used Bengali digits where that gate's ceiling counts Western. Both fixed in place. Also adds `website/scripts/capture-tool-risk-badge.mjs`, the sibling of `capture-decision-strip.mjs`, which is how the PR's screenshots are produced. It carries two guards it earned the hard way: `assertPaintable` refuses to photograph a row whose ancestor sits at computed opacity 0 (a collapsed turn wrapper reports perfectly correct layout numbers behind a blank rectangle), and the two badge clips are asserted distinct. Without them the harness wrote two byte-identical files under two correct names. Not touched, both main-side: the four `test_acp_runtime.py` failures on Backend Tests (Windows) (1), which the base commit #12005 introduced and two sibling PRs share, and the Python dependency audit line.
Problem / Motivation
On Windows, closing a session after its root process had already exited could leave the agent and MCP child processes running. The direct client returned early, and the shared runtime tried to stop a root that was already gone. Each repeat left more abandoned processes and memory behind. A follow-up review then showed the first fix's failure state was itself unbounded: a tree whose cleanup kept failing retained handles forever, and nothing stopped new trees from being admitted on top of that debt.
Why it matters
A dead root is not evidence that its children have stopped. A self-owned three-generation Python tree reproduced two surviving descendants after the previous cleanup paths returned. PR #11935 added simulated regression contracts, not native Windows reclamation. And a retry registry with no ceiling turns "we never lose an identity" into "we can never stop growing".
What changed (motivation -> approach -> change)
Closing a Windows session stops its children even if the root has exited. Cleanup keeps the original process identities, checks which children belong to that tree, and confirms they have stopped before reporting success. If cleanup fails, it keeps only the handles needed to retry, even after the session object is discarded; the existing maintenance tick retries those trees without letting a busy or refused tree block its peers, and retires tracking while the exact root handle still pins the incarnation.
On top of that, Windows cleanup bookkeeping is now bounded and admitted up front:
_WINDOWS_CLEANUP_ROOT_LIMIT(64) counts starting, live, failed and quarantined trees together, so simultaneous failures cannot exhaust the space needed to keep already-admitted roots. Only an empty failed-launch reservation or an exact-handle-verified retired tree is refunded.CreateProcessreturn, before CPython publishes the Popen handle or connects pipes. A failure after creation still publishes the owner for maintenance; a failure before creation refunds the empty reservation. Only the standard CPython Proactor subprocess implementation is admitted here; any other refuses before creation. The exact handle is recorded before the tree's identity is read, and that read runs onsubprocess_executor()rather than the starting loop, so a child that dies as it resumes cannot stall the loop serving every other session. Recording the handle first is what makes the hop safe: a cancellation during the read still leaves that child retained._WINDOWS_CLEANUP_IDENTITY_LIMIT(4096 exact objects per tree, root included) bounds retained handles, signalled identities and terminal-scan identities together; Toolhelp enumeration is bounded at_WINDOWS_CLEANUP_SNAPSHOT_LIMIT(65536) during the walk, not after allocating the whole table. Overflow is incomplete evidence, never an empty tree.manual-handling-requiredin this gateway process: it keeps its pins and tracking, is never refunded or retried, and new Windows physical starts are refused while any such mark exists. Other admitted trees keep draining. Ordinary transient failures without overflow still retry automatically.STILL_ACTIVEand an ordinary exit status, so a child returning it read back as running forever and no drain could reach a terminal scan. A zero-timeoutWaitForSingleObjectis now authoritative wherever the handle carriesSYNCHRONIZE; query-only callers, whose handles cannot be waited on, keep the exit-code reading.get_process_start_idpublishes itself as non-blocking, so its Windows arm asks the handle read for the creation half alone -- the whole identity -- with no liveness wait and no exit-FILETIMEpoll. Drain callers keep the exit bound and the poll.CreateProcess, published for maintenanceAn unfinished cleanup keeps enough identity to try again; a missing root cannot hide its children; and the bookkeeping that makes that promise now has a ceiling.
Backwards compatibility
Behavior change on Windows (intentional, maintainer-approved): three new refusal conditions exist that did not before.
WindowsCleanupCapacityError.The capture predicate reads private CPython shapes, so it is version-coupled, and the coupling is measured rather than assumed. The shipped coroutine was lifted out of
platform_compat.pyby AST and run unmodified on stock Windows CPython 3.12.10, 3.13.15 and 3.14.7 (official python.org amd64 builds, unpacked verbatim,sha256 d1f04d99...a2cfandd297e5ff...1f15): each one admitted the launch, spawned a real child, and captured that child's own pid, exact handle, reference-counted pin and(pid, 0)identity, while the same call on aSelectorEventLoopwas refused before creation in the same run. A later interpreter that reshapes those internals refuses tracked Windows starts instead of silently capturing nothing; re-running that measurement is the gate for adopting one, and its committed form istest/test_runtime_cleanup_windows.py::test_native_admission_and_owner_shutdown_refund_after_verified_drain, which spawns a real admitted tree through this capture on whichever interpreter is running. It runs on the Windows shards, so a minor that reshapes these internals turns adoption into a failing check rather than an archaeology exercise.Everything else is compatible for confirmed, owned trees: no configuration, dependency, credential, permission, timeout, pool size, RSS ceiling or Job limit changes; no new background timer or service; POSIX teardown and untracked Windows launches keep their original path. Windows cleanup failures are not success. An unreadable or missing original identity never authorizes killing a numeric PID. This is not gateway-crash recovery and cannot reconstruct an intermediary that disappeared before any handle observed it.
Tests
Implementation:
src/kiro_crew/platform_compat.py; integration:src/kiro_crew/acp/runtime.py,src/kiro_crew/acp/client.py,src/kiro_crew/session_pid.py,src/kiro_crew/sandbox.py(5 lines:create_subprocess_limitedaccepts an optional cleanup owner and, on Windows, routes an owned launch through the owned creation path; unowned launches are unchanged). The two existing stale-reap calls insrc/kiro_crew/apps/backend.pyalso consumekill_process_tree_pinned; they inherit exact-handle draining and same-process retry, not app-specific crash-durable retirement.New/changed tests:
test/test_windows_cleanup_capacity.py(new): concurrent reservation across threads/loops, capacity exhaustion refuses a new start without dropping existing handles, launch failure/cancel refunds only empty reservations, cancelled launch takes ownership of a returned child, refund after verified retirement, post-creation failure publishes the owner, identity/snapshot overflow -> sticky quarantine, quarantine excluded from retries and never reports success, non-Proactor loop refusal.test/test_windows_tree_reap.py(new): late-child discovery, final post-exit scans, unknown identities, unsuccessful draining, repeated cancellation, retained intermediary handles, duplicate attempts, busy-state fairness, failed metadata-write fairness, retirement while the root handle is still open (tests inspect handles, not PIDs or return codes).test/test_runtime_cleanup_windows.py(new, native): repeated three-generation teardown, root-first exit through shared runtime and direct client, synchronous fallback, independent child process groups, an unrelated surviving control, and a refused drain that survives owner-reference removal and completes through the real maintenance entry.test/test_pid_lifecycle.py: the synchronous Windows refusal contract moved out of the POSIX-only class; both an unpinnable identity and a failed drain must avoid pinned-root, unpinned-root and unpinned-tree fallback. Restoring the base implementation fails this at the forbidden root-only call.test/acp_launch_capture.py(test harness): the launch-goldens capture stubscreate_windows_cleanup_owned_processas a passthrough for both the client and runtime capture paths. Without it the harness's handle-lessMagicMockchild was classified as manual-handling debt and poisoned every later spawn in the same pytest worker (found by the local backend batch run, below). The admission is a collaborator with its own tests above, not a launch answer; production code did not change for this.Negative controls: restoring either old root-exit path fails at the surviving-descendant assertion without a teardown error; the owner-drop, metadata-fairness, creation-boundary and goldens-poisoning regressions each failed before their fix.
Not in this diff:
.github/black-baseline.txtis unchanged, sotest/test_app_backend_stale_reap.pystays listed. That file is not Black-clean at the repository's configuredline-length = 100(five pre-existing spans would be reformatted), while the two lambda signatures this change edits inside it already match Black output. The gate needs no new exemption here, and none of that unrelated formatting churn is carried.Local validation on this head (rebased onto
a4e397193, Windows Server 2025, Python 3.12):-n 0, one process per file): 493 passed / 370 skipped / 0 failed acrosstest_platform_compat,test_platform_compat_coverage,test_xdist_auto_cap,test_windows_cleanup_capacity,test_runtime_cleanup_windows(native),test_windows_tree_reap,test_acp_runtime_killandtest_acp_launch_goldens. Earlier heads of this branch additionally rantest_acp_runtime(425 + 1 xfail),test_acp_spawn_offload(24) andtest_runtime_cleanup_regression(5) green in the same serial shape.test_platform_compat_coverageskips itself on Windows by design (it simulates POSIX attributes that do not exist here and is coverage-measured on the ubuntu shards), so itsTestWindowsHandleIdentitycases were additionally executed on this host by calling them directly with a realMonkeyPatch: 14/14 pass, and strippingWaitForSingleObjectfrom the fake fails exactly the four cases that read liveness.kernel32fakes that drive_windows_process_handle_identitymust answerWaitForSingleObject; the coverage fake derives it from the exit code it already scripts (WAIT_TIMEOUT for live, WAIT_OBJECT_0 for exited) with an override so a test can script a handle that cannot be waited on, and two new cases pin the branches the fix introduced -- an exit status of 259 read as exited, and a query-only handle falling back to the exit code. Separately,test_xdist_auto_cap's two spawn-env tests mockasyncio.create_subprocess_exec, which the Windows owned-capture route does not go through, so they now also stub the capture seam to its POSIX pass-through; without it they attempted a real launch of the fixture's synthetic binary.python.exechild launches returning 0xC0000142 (STATUS_DLL_INIT_FAILED) intest_agent_home_isolation/test_agent_lifecycle_cyclesubprocess probes; batches 4-27 were not run locally. The gateway hosting this session runs in Windows Session 0 with a 768 KB non-interactive desktop heap, and concurrent console-child spawning from xdist workers exhausts it (the pytest re-run child andgit rev-parsedied with the same status). No host setting was changed. Remote CI's Linux/Windows/macOS backend shards are the coverage for those batches; one earlier batch-4 failure was a sandbox carve-out refusal caused by pytest's basetemp sitting under a masked scratch path, logic this PR does not touch.gpt-5.6-sol,claude-opus-4.8), each given the repository's own CI review contract. Both report no code findings; the Opus lane raised and then falsified three candidates itself (apreexec_fncrash on the Windows spawn, double-retirement in maintenance, a stranded drain after a cancelled kill). The GPT lane raised two documentation-accuracy findings, both verified true against the code and corrected in this commit:platform-compat.mdhad overclaimed that incomplete ancestry is always a refusal (a live grandchild whose only edge ran through an intermediary that exited before the first Toolhelp scan is invisible to the walk, so completeness is scoped to retained/observed members and that residue stays with the pre-existing orphan sweep), andacp-client.mdstill justified the POSIX-only escaped-child sweep bytaskkill /Twalking the tree, which this PR's_kill_processdoes not do on Windows. On a later head the CI GPT lane raised two blocking findings that were both upheld and both fixed here rather than rebutted: a PID-file sweep that retired rows still owned by a pending cleanup pin, and the identity read above running on the event loop. Each carries a regression test that fails when only the fix is neutralized.Manual verification
The native tests use real Windows kernel processes and pair each PID with its original creation FILETIME. They are Python stand-ins, not authenticated Kiro CLI/model turns. Assertions run before the independent fixture finalizer. No existing gateway or user session was restarted or terminated. Native macOS execution was not verified on this Windows host.
Related Issues
Follow-up to PR #11935. Windows counterpart to PR #11720, without absorbing its POSIX process-group implementation. Scope of the capacity admission and manual-handling quarantine was agreed on this PR after the GPT lane's
a-bound-bounds-every-field-it-retainsfinding.Pattern harvest
Rule candidate: review-prompt
Pattern: A dead root or successful termination call does not prove tree cleanup; exact identity ownership must survive failure, remain pinned through tracking retirement, and every retained-identity container needs a declared ceiling with a defined overflow behavior that never reports success.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)docs/system-specs/common/platform-compat.md, acp-client, app-kit-platform, security, session)