Skip to content

fix(windows): settle a cancelled descendant scan before releasing its handles - #26113

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/23108-winproc-cancel-ownership
Oct 30, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/23108-winproc-cancel-ownership

Conversation

@dodgeblaster

@dodgeblaster dodgeblaster commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On Windows, a cancelled descendant-process scan no longer leaks the process handles it opened, and its caller no longer closes handles the scan is still reading.

platform_compat.descendant_termination_handles_async awaited loop.run_in_executor directly. Cancelling the await cancels only the asyncio future. A worker that has already started keeps running: it keeps reading the caller's root and retained handles and keeps opening exact handles for new descendants. Its result is then thrown away, so nobody closes those new handles. The caller is released at once, so it can close the root and retained handles while the worker still uses them.

There is a real caller that hits this: kiro_prerequisite_process._run_process cancels and joins its descendant tracker in finally, then closes its retained and root handles. The tracker can be waiting on a scan at that moment.

Why it matters

Every cancelled or timed-out prerequisite spawn on Windows can leak kernel process handles, which also pin the process objects they name. A long-running gateway keeps those for its whole life. Closing a handle under a running scan can also make the scan read a closed or reused handle value.

Not a goal

What changed (motivation → approach → change)

Symptom: a cancelled scan's new handles are never closed, and the borrowed handles can close under it. Root cause: a started executor job cannot be cancelled, but the wrapper let the cancellation through straight away and dropped the job's result.

The wrapper in src/kiro_crew/platform_compat_winproc.py now awaits the job through asyncio.shield. When it is cancelled it:

Step Why
Waits for the job to finish, absorbing repeated cancellations The borrowed root and retained handles stay in use until then
Closes every handle a successful job opened The cancelled caller never receives them, so no one else can
Closes nothing after a failed job The synchronous walk already closes what it opened before raising
Re-raises CancelledError The caller still sees its cancellation

An uncancelled call is unchanged: it returns the job's handles to the caller. This is the same settle-then-re-raise shape platform_compat_wintree already uses for its owned-tree drain.

Backwards compatibility

Compatible: the function's signature and its uncancelled result are unchanged; a cancelled call still raises CancelledError, only later (once the bounded scan settles).

Removes nothing: the change only adds a settle step on the cancellation path.

Tests

test/test_platform_compat_coverage_failure_paths.py::TestDescendantHandlesAsyncWindows drives the wrapper with an executor whose submit returns a future already marked running, then completes it by hand (synthetic handles, no real process):

  • a cancel (once, and three times) does not release the caller until the job settles, then closes exactly the job's new handles (never the root or retained ones) and raises CancelledError;
  • a cancel followed by a failing job closes nothing and still raises CancelledError;
  • an uncancelled call hands the job's handles to the caller and closes nothing.

Proof: PROVEN test/test_platform_compat_coverage_failure_paths.py::TestDescendantHandlesAsyncWindows::test_cancel_settles_the_worker_and_closes_its_new_handles[1], test/test_platform_compat_coverage_failure_paths.py::TestDescendantHandlesAsyncWindows::test_cancel_settles_the_worker_and_closes_its_new_handles[3], test/test_platform_compat_coverage_failure_paths.py::TestDescendantHandlesAsyncWindows::test_cancel_with_a_failing_worker_closes_nothing_and_still_cancels (head a07af6b)

Determinism: the class passed 20 repeats at -n0, the whole file 10 repeats at -n 4, and a shuffled node order. Local gates: related backend tests (792 passed), isort, flake8, mypy, semgrep rules on the diff, flake-pattern ratchet.

Manual verification

N/A for the unit path: the cancellation logic is plain asyncio and is exercised on Linux with a controlled executor. The real Win32 handle path (an actual cancelled prerequisite spawn on native Windows) is not exercised by CI; a hand test on Windows would confirm no handle growth after repeated cancelled spawns.

Related Issues

Fixes #23108

Sibling sweep

Swept: git grep -nE "run_in_executor(|to_thread(" -- src/kiro_crew/platform_compat*.py
Sibling: src/kiro_crew/platform_compat_kill.py:324 -- not affected -- returns a kill result, transfers no handle
Sibling: src/kiro_crew/platform_compat_kill.py:339 -- not affected -- returns a kill result, transfers no handle
Sibling: src/kiro_crew/platform_compat_wintree.py:312 -- not affected -- returns an identity tuple, the handle stays pinned in its cleanup state
Sibling: src/kiro_crew/platform_compat_wintree.py:657 -- not affected -- already shields and settles its drain before re-raising
Sibling: src/kiro_crew/platform_compat_runtime.py:291 -- not affected -- exit-time log drain, owns no handle

Pattern harvest

Rule candidate: review-prompt
Pattern: an await loop.run_in_executor(...) whose job opens resources the caller must close, or borrows resources the caller closes on cancellation, needs a shield-and-settle on CancelledError.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision a07af6bec48d7ff971632b923ea9fec677948dc4 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 30, 2026
@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of a07af6bec48d7ff971632b923ea9fec677948dc4 — 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 does not.

First-Principles-Verdict: PASS

Every item fixes the reported handle leak (#23108) at its cause, a started executor job that cannot be cancelled. The settle loop is a third copy of an existing shape: a note, not a blocker.

Notes

  • Item 1 — oversized: the new while not worker.done(): ... await asyncio.shield(worker) loop is a third copy of the shield, settle and re-raise loop. The other two are platform_compat_kill._run_cleanup_shielded (same layer) and dashboard/chat_utils_awaits.run_to_completion; I counted three for await asyncio.shield( inside a cancel-absorbing loop. Subtraction: replace the hand loop with one existing settle helper and keep only the closing of the cancelled job's handles here.

What this change ships

Inventory (3 items) — 3 justified

Intent: on Windows, cancelling a prerequisite spawn no longer leaks process handles or closes handles a scan is still reading. This is a FIX.

  1. A cancelled descendant scan on Windows now returns only after its worker finishes, so the caller's root and retained handles stay open until then — justified
  2. Handles opened by a cancelled scan that succeeded are now closed instead of dropped — justified
  3. Repeated cancellations while the scan finishes are absorbed, and one CancelledError is still raised — justified

[FIRST-PRINCIPLES-REVIEWED] a07af6b

Description read

[DESCRIPTION-READ] 9252d324524c31772b9f0f6dda1c15378c4c33866b803a18e73214c9d78ead58

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of a07af6bec48d7ff971632b923ea9fec677948dc4 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this is the repo's existing shield-and-settle pattern applied at the one site that hands back handle ownership, and the scan is bounded by the identity limit.

Notes

  • The cancellation logic is plain asyncio, and CI runs it on Linux by forcing IS_WINDOWS on. A hand test on native Windows (no handle growth after repeated cancelled spawns) would confirm the Win32 half the description names.

[DESIGN-REVIEWED] a07af6b

Description read

[DESCRIPTION-READ] 96edc73e041669c8b4eb8d5a8d04eb20b094886135b7b348f7edeb51d0ce2582

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a07af6b

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable a07af6bec48d7ff971632b923ea9fec677948dc4 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of a07af6bec48d7ff971632b923ea9fec677948dc4 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a07af6b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a07af6bec48d7ff971632b923ea9fec677948dc4 false-positive: <reason, 20 to 500 characters>

… handles

descendant_termination_handles_async awaited run_in_executor directly.
Cancelling that await cancels only the asyncio future: a worker already
running keeps reading the caller's root and retained handles and keeps
opening new descendant handles, whose result is then discarded. The
prerequisite-process supervisor cancels its tracker in `finally` and closes
those borrowed handles right after, so they could close under the worker,
and the worker's new handles leaked.

The wrapper now awaits the worker through asyncio.shield. On cancellation
it waits for the worker to settle (absorbing repeated cancellations), closes
every handle a successful worker opened, since the cancelled caller never
receives them, and re-raises. A failed worker has already closed what it
opened, so nothing more is closed.

Fixes #23108
@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 Oct 30, 2026
@dodgeblaster
dodgeblaster force-pushed the fix/23108-winproc-cancel-ownership branch from 7a5f9b8 to a07af6b Compare October 30, 2026 05:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 30, 2026
@dodgeblaster
dodgeblaster marked this pull request as ready for review October 30, 2026 14:59
@dodgeblaster
dodgeblaster requested review from a team and KiroCrewCaptain as code owners October 30, 2026 14:59
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 30, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

Approving.

The fix matches the mechanism: a started executor job cannot be cancelled, so the old wrapper released the caller while the worker still read the borrowed root and retained handles, and the handles the worker opened afterwards reached nobody. Shielding the future, settling it across repeated cancels, closing only a successful result's handles, and then re-raising closes both holes. Checking worker.cancelled() before worker.exception() also covers an executor shutdown that cancels the queued job.

The tests pin both halves. Removing the close loop fails both test_cancel_settles_the_worker_and_closes_its_new_handles cases ([] == [9001, 9002]), and dropping the settle loop fails those two plus test_cancel_with_a_failing_worker_closes_nothing_and_still_cancels on assert not task.done().

The added wait on cancel is one bounded scan, and it runs on the private spawn loop, not the gateway loop, so it costs nothing visible.

Follow-up (non-blocking): docs/system-specs/common/platform-compat.md documents descendant_termination_handles but not this cancellation contract of the async variant. One sentence there saying a cancelled call settles the scan, closes the handles it opened and then re-raises would keep the spec in step.

@iamwhatever

Copy link
Copy Markdown
Contributor

Holding for human review because the PR touches the Windows process-termination path. The code looks correct, and I found no defect.

Why HOLD: descendant_termination_handles_async collects the handles that kiro_prerequisite_process.py uses to terminate a prerequisite's process tree (kiro_prerequisite_process.py#L286-L295). This PR changes how that call behaves on cancellation and when its handles are closed (platform_compat_winproc.py#L609-L650). Process-killing paths are reserved for a human reviewer, and this is a behaviour change, not a mechanical move. The set of processes killed does not change. A maintainer approval clears it.

The fix matches the mechanism. A started executor job cannot be cancelled, so the old wrapper released the caller while the worker still read the borrowed handles, and the handles the worker opened afterwards were never closed. Shielding the future, settling it across repeated cancels, closing a successful result's handles and then re-raising closes both holes. worker.cancelled() is checked before worker.exception(), so an executor shutdown is handled.

Also for the reviewer: docs/system-specs/common/platform-compat.md does not describe the async variant's cancellation contract. Please add one sentence, or open an issue and link it.

AI findings judged non-blocking:

  • First Principles (Notes): the settle loop is a third copy of an existing shape. This is a refactor suggestion. The nearby helper _run_cleanup_shielded settles a coroutine and does not close a returned handle map.
  • Design Review (Notes): a hand test on native Windows would confirm the Win32 half. That is a test suggestion only. The Win32 scan itself is unchanged.

All checks on this head are green and the branch merges cleanly with main. I read the test source and CI; I did not run tests locally or on Windows.

Reviewed at a07af6b.

— crew-pr-reviewer (r136)

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 30, 2026 18:08

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (2 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: a cancelled Windows descendant scan settles its worker and closes the handles it opened; one module plus tests.

@KiroCrewCaptain
KiroCrewCaptain merged commit 813cb6a into main Oct 30, 2026
98 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/23108-winproc-cancel-ownership branch October 30, 2026 18:38
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Windows: cancelling descendant discovery loses newly opened process handles

4 participants