Skip to content

fix(acp): amend the death summary on the Windows teardown too - #12260

Closed
iamwhatever wants to merge 1 commit into
mainfrom
fix/acp-windows-reap-amendment
Closed

iamwhatever wants to merge 1 commit into
mainfrom
fix/acp-windows-reap-amendment

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

The ask

Backend Tests (Windows) (1) is red on main's merge refs, with four failures in test/test_acp_runtime.py:

test_kill_amends_the_summary_once_the_reap_completes[False-WARNING]
test_kill_amends_the_summary_once_the_reap_completes[True-INFO]
test_reap_amendment_leaves_the_reason_untouched
test_reap_amendment_leaves_the_stderr_tail_untouched

each asserting [returncode=-15] and getting [returncode=<not reaped>]. Green on Linux and macOS, red on Windows, deterministic. It surfaced on #12245, whose diff touches nothing under src/kiro_crew/acp/.

Two PRs collided mid-air

AcpRuntime.kill() has two teardowns, and the reap amendment was wired onto one of them.

#12188's CI was green on Windows because its merge ref predated #12005. The two only meet after both merged.

The product defect

On Windows the early return fires first and the amendment never runs, so every Windows death reports <not reaped> about a process whose exit code it had just confirmed. The drain returns only once every member's exit is CONFIRMED — that is precisely what makes the root's status readable from the handle the caller still holds. The information was there and nothing read it.

It matters past one log line: the retained summary rides AcpProcessDied into a turn's error and a cron's last_error, which is the surface an operator diagnoses a killed runtime from.

Fix: one call, placed where the ladder places its own — after the drain, before the handle is dropped, and after the raise, because a drain that could not confirm has no status to claim and must keep the handle for maintenance to retry. _note_reaped_after_kill was already platform-neutral and idempotent (silent on None, silent once the label is no longer <not reaped>), so nothing else moves.

The test defect that let it ship

_neuter_kill_side_effects stubbed the drain as AsyncMock(return_value=True) — returning True without touching the handle, asserting a guarantee the real drain keeps and the stub did not. Every test reaching the Windows branch was judging the teardown against a drain that reaps nothing, which no production code can satisfy: the fix alone does not turn those four green, because their own stub is the blocker.

So the stub now awaits the handle, bounded, and a timeout is not an error — a test that pins a handle which never exits is describing a status that stays unknown, and <not reaped> is then the honest answer. That is what test_kill_keeps_the_label_when_no_status_ever_arrives asserts, and it keeps asserting it on both platforms now rather than by accident on one.

Coverage, so the two paths cannot drift again

The four existing tests only ever exercised the ladder on Linux and macOS. Three new tests pin IS_WINDOWS so the Windows branch runs on every host:

  • the amendment lands at both severities (expected=False → WARNING, expected=True → INFO);
  • a drain that returns without a readable code claims nothing;
  • a drain that reaps the root and then raises amends nothing and keeps the handle — the sharp case, since an amendment in a finally or before the raise would publish a status the teardown never confirmed.

Verification

Revert-verified from an in-memory snapshot, with the Windows branch forced on so the host runs what the Windows shard runs:

with the fix: exit=0 :: 8 passed
call removed: exit=1 :: 6 failed, 2 passed
restored:     exit=0 :: 8 passed
                                     -> LOAD-BEARING

No regression on the six ACP/Windows-teardown suites. This host carries a pre-existing cross-file TimeoutError red in the KAS-readiness tests, unrelated and present on the base:

tree result
origin/main (9dea438cfa) 54 failed, 471 passed
this branch 53 failed, 476 passed

One fewer failure, five more passing — the four new test cases plus the one the fix clears. test_acp_runtime.py run alone is green on both, with byte-identical failing sets.

Gates: check_comment_history.py, check_brand_name.py, check_subprocess_encoding.py, check_sync_io_in_async.py, check_loop_bound_locks.py, docs_lint.py all pass; black --check and flake8 clean on both files. No spec change owed — docs/system-specs/modules/acp-client.md does not describe the kill teardown's death summary.

Confirmed on real Windows

The harness above forces the branch on Linux; this PR's own CI runs it for real. All eight Windows backend shards are green, including shard 1 — the one that is red on every merge ref carrying both #12005 and #12188:

shard 1 2 3 4 5 6 7 8
result pass pass pass pass pass pass pass pass

Pattern harvest

Rule candidate: review-prompt

Pattern: a step appended to the end of one branch of a platform/mode split, where the other branch returns early. kill() splits on IS_WINDOWS; the Windows arm returns mid-function; a later change added a step at the end of the POSIX arm. Neither author was wrong in isolation and no test on the merged tree could see it, because the two landed in separate PRs whose CI never shared a tree. This is the same shape as the recurring "a correct guard wired at only some of its call sites" class, with a platform branch standing in for the call sites — so the reviewer prompt should ask, for any step added at the tail of a function that has an early return above it, which of the exits reach it and whether each one owes the step.

Rule candidate: semgrep

Pattern: a test double that returns a success sentinel without performing the side effect its real counterpart documents as its postcondition. _neuter_kill_side_effects stubbed terminate_windows_asyncio_tree as AsyncMock(return_value=True) while the real function's contract is "returns only once every member's exit is CONFIRMED". That stub is what made the four tests unsatisfiable on Windows: they asserted a status no implementation could produce under it, so the gap was invisible on the platforms CI is green on and the red, when it came, read as a product bug in whichever PR happened to surface it. A rule cannot read a docstring, but it can flag the narrow shape — AsyncMock(return_value=True) / MagicMock(return_value=True) substituted for a function whose name matches a reap, drain, flush, join or await-style verb — for a human to confirm the postcondition is honoured.

Not generalizable: the specific merge-order collision. #12188's CI predating #12005 is what CI on a merge ref is for, and it did catch this on the next PR through. The gap worth closing is the two above, not the ordering.

Why no screenshot: backend-only change to a process-teardown path. No user-visible surface renders differently; the one string it corrects reaches a reader through a log line and an error message, both shown verbatim above.

`AcpRuntime.kill()` has TWO teardowns. POSIX runs the signal ladder; Windows
runs the pinned-handle drain INSTEAD of that ladder and returns from `kill()`
on its own. The reap amendment -- the line that replaces the pre-signal
`[returncode=<not reaped>]` with the status the reap actually observed -- was
wired onto the ladder only.

So every Windows death reported `<not reaped>` about a process whose exit code
it had just confirmed. The drain returns only once every member's exit is
CONFIRMED, which is exactly what makes the root's status readable from the
handle the caller still holds, so the information was there and never read. It
matters past the log line: the summary rides `AcpProcessDied` into a turn's
error and a cron's `last_error`, which is the surface an operator diagnoses a
killed runtime from.

One call, placed where the ladder places its own -- after the drain, before the
handle is dropped, and AFTER the raise, because a drain that could not confirm
has no status to claim and must keep the handle for the retry.

The reason the gap shipped is a test one, and it is fixed here as well.
`_neuter_kill_side_effects` stubbed `terminate_windows_asyncio_tree` as an
`AsyncMock(return_value=True)` that never touches the handle -- asserting a
guarantee the real drain keeps and the stub did not. Every test reaching the
Windows branch was therefore judging the teardown against a drain that reaps
nothing, which no production code can satisfy. The stub now awaits the handle,
bounded, with a timeout that is not an error: a test pinning a handle that never
exits is describing a status that stays unknown, and `<not reaped>` is then the
honest answer.

That combination is what made the four existing reap-amendment tests pass on
Linux and macOS and fail on Windows. Three new tests close the coverage gap on
every host by pinning `IS_WINDOWS`: the amendment lands at both severities, a
drain that confirms no status claims none, and a drain that reaps the root but
raises amends nothing and keeps the handle.

Revert-verified: removing the one added call turns six of the eight red, and
restoring it returns them to green.
@iamwhatever
iamwhatever requested review from a team and patrigao September 20, 2026 09:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 20, 2026
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 06b5347e830cb481e2e09f275681d41f8e318958 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 06b5347

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

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Confirm the actual Windows CI shard goes green — local verification forced IS_WINDOWS on a POSIX host, a faithful but simulated run.

[DESIGN-REVIEWED] 06b5347

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 06b5347e830cb481e2e09f275681d41f8e318958 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 06b5347

Verdict parsed from the review's SHA-scoped output markers for commit 06b5347e830cb481e2e09f275681d41f8e318958.

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

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 06b5347e830cb481e2e09f275681d41f8e318958 — 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.

First-Principles-Verdict: PASS

Confirm the Windows CI shard itself goes green — the revert-verification forced IS_WINDOWS on a POSIX host, not the real shard.

The description's core premise checks out in-repo: terminate_windows_asyncio_tree ends with await process.wait() (src/kiro_crew/platform_compat.py:4336), so the returncode is readable exactly where the new call reads it, and the amendment call mirrors the POSIX ladder's own at src/kiro_crew/acp/runtime.py:3036. The stub rewrite is load-bearing for the fix, not a rider: the old AsyncMock(return_value=True) never set the handle's returncode, so the four red tests stay red without it.

Inventory (4 items) — 4 justified

Intent: make a killed runtime's death summary carry the exit code on Windows too, unwedging four red Windows CI tests on main — a FIX.

  1. Windows deaths now report the confirmed exit code instead of <not reaped> in the summary and log — justified
  2. The test stub for the Windows drain now reaps the handle like the real drain — justified
  3. Three new tests pin IS_WINDOWS so the Windows branch runs on every host — justified
  4. _note_reaped_after_kill's docstring now names both calling teardowns — justified

[FIRST-PRINCIPLES-REVIEWED] 06b5347

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 20, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

[operator: iamwhatever] Closing as superseded by #12269, which merged as 954fb69185 and is now main's tip. Full credit to @BoliChen — independent convergence on the same fix, and theirs landed.

The two are the same diagnosis and the same remedy, reached separately: record the reap inside the Windows branch before the handle is dropped, and make the shared kill double drain the way the real terminate_windows_asyncio_tree does, because a stub that returns without awaiting process.wait() hands the branch a process whose status is unreadable. Both of us verified it the same way, by forcing platform_compat.IS_WINDOWS and reverting one half at a time. Nothing here is worth keeping over what already landed.

It works: Backend Tests (Windows) (1) is green on #12245's current head, which is the merge ref that carried this red for three hours.

One thing in here that #12269 does not cover

Its failed-drain test raises without setting process.returncode:

async def _drain_fails(process):
    raise OSError("Windows tree tracking retirement did not complete")

returncode therefore stays None, and _note_reaped_after_kill(None) returns early on its own — so that test passes whether the amendment sits after the raise or before it. The placement is load-bearing and currently unpinned: an amendment moved into a finally, or one line earlier, would publish a status for a tree the drain could not vouch for, and no test would notice.

This PR's version reaps the root and then raises, which is the case that distinguishes them:

async def _drain_fails(process):
    # The root WAS reaped -- so the code is readable -- but the members could
    # not be confirmed, which is the case the real drain raises on. That
    # makes this test load-bearing: an amendment placed before the raise, or
    # in a finally, would publish this -15.
    process.returncode = -15
    raise OSError("handle drain incomplete")

plus assert rt._process is proc, since the same branch must keep the handle pinned for maintenance to retry.

Not reopening this PR for it and not smuggling it elsewhere — it is one test function against main, and it is written above for whoever wants it. Filing it that way rather than leaving it only in a closed branch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant