claude-dev-env 2.3.0 → 2.5.0

package/skills/closeout/SKILL.md

@@ -2,8 +2,9 @@
 name: closeout
 description: >-
   Harvests session obstacles into GitHub issues backed by quoted evidence:
-  validates each draft with the user, dedupes against open and closed issues,
-  files children under a parent checklist, and prints a cloud handoff prompt.
+  validates each draft with the user, then delegates filing to the issue-tracker
+  agent (skill fallback), which dedupes against open and closed issues and files
+  each under an epic as a native sub-issue. Prints a cloud handoff prompt.
   Triggers: /closeout, close out this session, close out the session, file the
   session obstacles, session closeout, harvest session obstacles, end-of-session
   issue filing. Not session-log (vault journal) — closeout files issues and
@@ -12,18 +13,20 @@ description: >-
 
 # Closeout
 
-**Core principle:** At the end of a working session, turn the obstacles the session hit into user-approved GitHub issues — each backed by a quoted line — plus a computed cloud handoff prompt, never guessing, never filing without approval, never touching the host repo's live pipeline.
+**Core principle:** At the end of a working session, turn the obstacles the session hit into user-approved GitHub issues — each backed by a quoted line — then hand each approved draft to the issue-tracker for filing, and print a computed cloud handoff prompt. Closeout never guesses, never files without approval, and never touches the host repo's live pipeline.
+
+## The delegation boundary
+
+Closeout is the session-end entry point. It harvests obstacles, validates them with the user, and drafts one issue-candidate record per obstacle. The **issue-tracker** owns filing: dedup against open and closed issues, one epic per work-stream, native sub-issues, labels, and marker-delimited body sections. Closeout hands each approved record to the `issue-tracker` **agent** (primary), falling back to the `issue-tracker` **skill** when the agent is unavailable. Closeout-filed issues run the full tracker path — the same as any other tracked issue. Closeout builds no separate filing layer.
 
 ## Gotchas
 
 Highest-signal content. Append a bullet each time a run fails in a new way.
 
 - An obstacle stated from memory drifts. File only what the session can quote word for word — the actual error text, the exact command, the exact log line. A candidate that cannot be quoted goes under "Unverified candidates" for the user to judge, never into a filed issue as fact.
-- Skipping the confirmation gate files noise to a shared server that other people read. Every parent and child draft passes the AskUserQuestion gate before any write.
-- A body that leans on chat context reads as a puzzle to anyone who opens the issue cold. Write each body so a reader with zero session context acts on it: name the failure, the count, and the quoted line.
-- A `--body` string mangles backticks on GitHub — they land as literal `\``. Every `gh` create and comment uses `--body-file <path>`.
-- A dedupe search that skips closed issues re-files a twin the team already resolved. The search covers `--state all`.
-- A volatile path in an issue body breaks the moment the job scratch is cleaned. Keep temp dirs, worktrees, and `$CLAUDE_JOB_DIR` out of every body.
+- Skipping the confirmation gate files noise to a shared server that other people read. Every draft passes the AskUserQuestion gate before closeout hands it to the tracker.
+- A body that leans on chat context reads as a puzzle to anyone who opens the issue cold. Write each record so a reader with zero session context acts on it: name the failure, the count, and the quoted line.
+- A volatile path in an issue body breaks the moment the job scratch is cleaned. Keep temp dirs, worktrees, and `$CLAUDE_JOB_DIR` out of every record.
 
 ## When this skill applies
 
@@ -40,21 +43,18 @@ Triggers: `/closeout`, "close out this session", "file the session obstacles", "
 ## The process
 
 ```
-- [ ] Phase 1 — Harvest obstacles from the three sources; quote verbatim evidence
-- [ ] Phase 1 — Run the PII pass over every candidate
-- [ ] Phase 2 — Draft the parent + children set
-- [ ] Phase 2 — Confirmation gate: AskUserQuestion, file only on approval
-- [ ] Phase 3 — Dedupe each candidate against open and closed issues
-- [ ] Phase 4 — Route each issue to its repo
-- [ ] Phase 5 — File children, then the parent checklist
-- [ ] Phase 6 — Print the computed cloud handoff prompt in chat
+- [ ] Phase 1 — Harvest obstacles from the three sources; quote verbatim evidence; run the PII pass
+- [ ] Phase 2 — Draft one issue-candidate record per obstacle; confirmation gate via AskUserQuestion
+- [ ] Phase 3 — Route each candidate to its repo
+- [ ] Phase 4 — Hand each approved record to the issue-tracker; collect numbers and URLs
+- [ ] Phase 5 — Print the computed cloud handoff prompt in chat
 ```
 
 ### Track the phases on the task list
 
-At invocation, copy the six phases onto the session task list — one task each via TaskCreate: harvest, draft + user validation, dedupe, repo routing, filing, handoff prompt. Mark a task `in_progress` with TaskUpdate when its phase starts and `completed` when the phase finishes.
+At invocation, copy the five phases onto the session task list — one task each via TaskCreate: harvest, draft plus user validation, repo routing, tracker hand-off, handoff prompt. Mark a task `in_progress` with TaskUpdate when its phase starts and `completed` when the phase finishes.
 
-Hold one line on the filing task: never mark it `completed` while any planned issue is still uncreated. A filing phase that lands fewer issues than the approved set keeps the filing task open, with the missing issues named on it.
+Hold one line on the hand-off task: never mark it `completed` while any approved record has no issue number back from the tracker. A hand-off that lands fewer issues than the approved set keeps the task open, with the missing records named on it.
 
 ### Phase 1 — Harvest obstacles
 
@@ -68,36 +68,22 @@ An obstacle is a hook block, a gate that fired wrongly, a tool that failed, a fo
 
 **Non-negotiable evidence rule:** every filed issue quotes verbatim evidence captured this session — the actual error text, the exact command, the exact log line. An obstacle you cannot quote is dropped, or listed under a "Unverified candidates" section of the drafts for the user to decide. It is never filed as fact.
 
-**PII pass (runs on every run):** strip personal data from every issue body and from the handoff prompt — emails, real names, home paths, private hosts and IPs, account ids, tokens. The pass runs whether the target repo is public or private; repository visibility changes only how aggressive the redaction is (public repos get the strictest pass), never whether the pass runs. Checklist and swaps: [reference/pii-redaction-checklist.md](reference/pii-redaction-checklist.md).
+**PII pass (runs on every run):** strip personal data from every record and from the handoff prompt — emails, real names, home paths, private hosts and IPs, account ids, tokens. The pass runs whether the target repo is public or private; repository visibility changes only how aggressive the redaction is (public repos get the strictest pass), never whether the pass runs. Checklist and swaps: [reference/pii-redaction-checklist.md](reference/pii-redaction-checklist.md).
 
 ### Phase 2 — Draft and validate with the user
 
-Build the parent → children issue set as drafts. Body shapes and worked examples: [reference/issue-body-templates.md](reference/issue-body-templates.md).
+Build one **issue-candidate record** per obstacle, in the tracker's handoff shape: `kind`, `title`, `epic`, `summary`, `evidence`, `where`, `impact`, `proposed_fix`, `blocking`. Field meanings and a filled example: the issue-tracker skill's handoff schema (`skills/issue-tracker/reference/handoff-schema.md`). Group related obstacles under one `epic` label so the tracker files them as sub-issues of a shared epic.
 
 Then the **mandatory confirmation gate**. Present through AskUserQuestion:
 
-- Each drafted parent and child — title, target repo, one line of scope each.
+- Each drafted record — title, target repo, `epic`, one line of scope.
 - Any PII concern the pass found.
-- Any closed twin a dedupe search surfaced (see Phase 3), as a reopen/comment/file-new choice.
-
-Filing to GitHub is an irreversible write to a shared server that other people read. File only on explicit user approval. The user validates every finding before anything is posted.
-
-### Phase 3 — Dedupe
-
-Before filing each candidate, search open and closed issues on the target repo:
-
-```
-gh issue list --search "<terms>" --state all
-```
-
-- **Open twin exists** → comment on it, rather than filing a new issue.
-- **Closed twin exists** → do not silently file or comment. Surface it in the Phase 2 gate as "previously closed twin — reopen, comment, or file new" for the user to decide.
 
-`gh issue list` needs no pagination flags. If you show a `gh api` read of a paginated list endpoint anywhere, show `--paginate --slurp` piped to external `jq` — `gh`'s built-in `--jq` runs per page and gives wrong cross-page results.
+Filing to GitHub is an irreversible write to a shared server that other people read. Hand a record to the tracker only on explicit user approval. The user validates every finding before anything is posted.
 
-### Phase 4 — Repo routing
+### Phase 3 — Repo routing
 
-Route each issue by a deterministic rule:
+Route each candidate by a deterministic rule, and pass the resolved repo to the tracker:
 
 - The evidence names a file under the dev-env tree — `packages/claude-dev-env/hooks/`, `rules/`, `skills/`, `commands/`, `agents/`, `bin/`, or `docs/` — or an installed copy of those under `~/.claude/` (hooks, rules, skills, commands, agents) → file against **claude-dev-env**.
 - Otherwise → the **working repo**, read live:
@@ -106,17 +92,15 @@ Route each issue by a deterministic rule:
 gh repo view --json nameWithOwner
 ```
 
-- **Cross-repo case** — a hook shipped by repo B blocked work in repo A → file against **B** and reference A in the body.
+- **Cross-repo case** — a hook shipped by repo B blocked work in repo A → file against **B** and name A in the record.
 
-### Phase 5 — File
+### Phase 4 — Hand off to the issue-tracker
 
-File **children first**, then the parent. The parent body is a checklist of `- [ ] owner/repo#N` lines, one per child created.
+For each approved record, hand it to the `issue-tracker` **agent** (primary) with the resolved repo, one record per agent call. When the agent is unavailable, load the `issue-tracker` **skill** and run the same op inline. The tracker runs the full path for each record: dedup open and closed issues, find or create the epic, create the sub-issue, apply labels, attach the native sub-issue, and refresh the epic checklist. It returns the issue number and URL, which closeout collects for the handoff prompt.
 
-- Every `gh issue create` and `gh issue comment` uses `--body-file <path>`, never `--body`.
-- No volatile paths in any body: no temp dirs, no worktrees, no `$CLAUDE_JOB_DIR`, no `.claude-editor/jobs` or `.claude/worktrees` paths.
-- Bodies are self-contained and specific: the failure mode, the count, and the quoted line — not "improve error handling".
+A closed twin the tracker's dedup surfaces comes back for a reopen-or-file-new decision. Route that decision through the same AskUserQuestion gate before the tracker proceeds.
 
-### Phase 6 — Computed handoff prompt
+### Phase 5 — Computed handoff prompt
 
 Print **in chat** (not a file) a prompt the user pastes into a cloud session that opens PRs for the filed issues and drives them to convergence. Template and worked example: [reference/handoff-prompt-template.md](reference/handoff-prompt-template.md).
 
@@ -134,18 +118,17 @@ This skill runs inside a repo whose pipeline is live in production. Hold these l
 
 - It never runs that pipeline, never merges, never deploys, never syncs.
 - It never runs the host repo's automations.
-- It creates issues and comments and prints text. Nothing else.
+- It harvests obstacles, validates them, delegates filing to the tracker, and prints text. Nothing else.
 
 ## File index
 
 | File | Purpose |
 |------|---------|
-| `SKILL.md` | This hub — core principle, gotchas, refusal cases, six-phase process, boundaries |
-| `reference/issue-body-templates.md` | Parent and child issue body shapes with worked examples |
+| `SKILL.md` | This hub — core principle, delegation boundary, gotchas, refusal cases, five-phase process, boundaries |
 | `reference/pii-redaction-checklist.md` | The PII pass: categories, swaps, public-versus-private aggression |
 | `reference/handoff-prompt-template.md` | The computed cloud handoff prompt shape with a worked example |
 
 ## Folder map
 
-- `SKILL.md` — hub: principle, gotchas, refusal, six-phase process, boundaries.
-- `reference/` — issue body templates, PII redaction checklist, handoff prompt template.
+- `SKILL.md` — hub: principle, delegation boundary, gotchas, refusal, five-phase process, boundaries.
+- `reference/` — PII redaction checklist, handoff prompt template.

package/skills/codex-review/scripts/codex_review_scripts_constants/run_constants.py

@@ -24,6 +24,14 @@ OUTCOME_CLASS_COMPLETED = "completed"
 MISSING_BINARY_EXIT_CODE = 127
 TIMEOUT_EXIT_CODE = 124
 SUBPROCESS_DECODE_EXIT_CODE = 70
+CWD_KEYWORD = "cwd"
+CAPTURE_STREAMS_KEYWORD = "capture_output"
+TEXT_MODE_KEYWORD = "text"
+ENCODING_KEYWORD = "encoding"
+CHECK_KEYWORD = "check"
+TIMEOUT_KEYWORD = "timeout"
+ENVIRONMENT_KEYWORD = "env"
+PROCESS_TREE_KILL_TIMEOUT_SECONDS = 10
 SHAPE_FLAG_TOKEN_TAIL_PATTERN = r"(?![\w-])"
 JSONL_EVENT_TYPE_KEY = "type"
 JSONL_ENTRY_KEY = "item"

package/skills/codex-review/scripts/run_codex_review.py

@@ -18,6 +18,7 @@ import json
 import os
 import re
 import shutil
+import signal
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
@@ -27,15 +28,24 @@ from codex_review_scripts_constants.codex_usage_probe_constants import (
     WINDOWS_COMMAND_SHELL,
     WINDOWS_COMMAND_SHELL_RUN_FLAG,
     WINDOWS_OS_NAME,
+    WINDOWS_TASKKILL_COMMAND,
+    WINDOWS_TASKKILL_FORCE_FLAG,
+    WINDOWS_TASKKILL_PID_FLAG,
+    WINDOWS_TASKKILL_TREE_FLAG,
 )
 from codex_review_scripts_constants.run_constants import (
     ALL_SHAPE_PROBE_REQUIRED_FLAGS,
     BASE_TARGET_FLAG,
+    CAPTURE_STREAMS_KEYWORD,
+    CHECK_KEYWORD,
     CODEX_BINARY_NAME,
     CODEX_MODEL_PIN,
     COMMIT_TARGET_FLAG,
     CUSTOM_INSTRUCTIONS_PROMPT,
+    CWD_KEYWORD,
     DEFAULT_TIMEOUT_SECONDS,
+    ENCODING_KEYWORD,
+    ENVIRONMENT_KEYWORD,
     EXEC_SUBCOMMAND,
     HELP_FLAG,
     JSON_FLAG,
@@ -50,17 +60,239 @@ from codex_review_scripts_constants.run_constants import (
     MODEL_FLAG,
     OUTCOME_CLASS_CODEX_DOWN,
     OUTCOME_CLASS_COMPLETED,
+    PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     REVIEW_SUBCOMMAND,
     SHAPE_FLAG_TOKEN_TAIL_PATTERN,
     SUBPROCESS_DECODE_EXIT_CODE,
+    TEXT_MODE_KEYWORD,
     TIMEOUT_EXIT_CODE,
+    TIMEOUT_KEYWORD,
     UNCOMMITTED_TARGET_FLAG,
     UTF8_ENCODING,
     VERSION_FLAG,
     VERSION_PROBE_PATTERN,
 )
 
-codex_subprocess_runner = subprocess.run
+
+def _kill_windows_process_tree(process_identifier: int) -> None:
+    """Kill a Windows process and every descendant it started, by PID.
+
+    Swallows taskkill failures so the caller can fall back to ``Popen.kill()``
+    and a timed drain. A raised ``TimeoutExpired`` here would replace the
+    original review-timeout exception and skip that drain path.
+    """
+    try:
+        subprocess.run(
+            [
+                WINDOWS_TASKKILL_COMMAND,
+                WINDOWS_TASKKILL_TREE_FLAG,
+                WINDOWS_TASKKILL_FORCE_FLAG,
+                WINDOWS_TASKKILL_PID_FLAG,
+                str(process_identifier),
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            timeout=PROCESS_TREE_KILL_TIMEOUT_SECONDS,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return
+
+
+def _kill_posix_process_group(process_identifier: int) -> None:
+    """Kill a POSIX process group so no grandchild keeps the capture pipe open."""
+    try:
+        process_group_identifier = os.getpgid(process_identifier)
+        os.killpg(process_group_identifier, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        return
+
+
+def _terminate_process_tree(review_process: subprocess.Popen[str]) -> None:
+    """Kill the review process and every descendant it spawned.
+
+    Tree kill first (taskkill /T or killpg). When the direct child is still
+    alive after that, fall back to ``Popen.kill()`` so ``Popen.__exit__`` never
+    hits an unbounded wait on a surviving process.
+    """
+    if review_process.poll() is not None:
+        return
+    if os.name == WINDOWS_OS_NAME:
+        _kill_windows_process_tree(review_process.pid)
+    else:
+        _kill_posix_process_group(review_process.pid)
+    if review_process.poll() is not None:
+        return
+    try:
+        review_process.kill()
+    except ProcessLookupError:
+        return
+
+
+def _open_codex_popen(
+    all_arguments: list[str],
+    all_keyword_arguments: dict[str, object],
+) -> subprocess.Popen[str]:
+    """Start the codex process in its own session so its tree can be killed."""
+    should_capture = bool(all_keyword_arguments.get(CAPTURE_STREAMS_KEYWORD, False))
+    stream_target = subprocess.PIPE if should_capture else None
+    working_directory = all_keyword_arguments.get(CWD_KEYWORD)
+    stream_encoding = all_keyword_arguments.get(ENCODING_KEYWORD)
+    process_environment = all_keyword_arguments.get(ENVIRONMENT_KEYWORD)
+    return subprocess.Popen(
+        all_arguments,
+        cwd=working_directory if isinstance(working_directory, str) else None,
+        stdout=stream_target,
+        stderr=stream_target,
+        text=bool(all_keyword_arguments.get(TEXT_MODE_KEYWORD, False)),
+        encoding=stream_encoding if isinstance(stream_encoding, str) else None,
+        env=process_environment if isinstance(process_environment, dict) else None,
+        start_new_session=os.name != WINDOWS_OS_NAME,
+    )
+
+
+def _drain_process_after_tree_kill(
+    review_process: subprocess.Popen[str],
+) -> None:
+    """Join pipe reader threads after a tree kill; never block unbounded.
+
+    ::
+
+        kill tree -> communicate(grace)    ok: pipe EOF, threads join
+        kill incomplete, no drain          flag: Popen.__exit__ wait() hangs
+
+    Windows needs a post-kill ``communicate()`` so timed-out reader threads
+    join. Every platform needs a timed join so an incomplete tree kill cannot
+    leave ``Popen.__exit__`` waiting forever.
+    """
+    try:
+        review_process.communicate(timeout=PROCESS_TREE_KILL_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired:
+        try:
+            review_process.kill()
+        except ProcessLookupError:
+            pass
+        try:
+            review_process.communicate(timeout=PROCESS_TREE_KILL_TIMEOUT_SECONDS)
+        except subprocess.TimeoutExpired:
+            return
+
+
+def _communicate_with_tree_kill_on_timeout(
+    review_process: subprocess.Popen[str],
+    timeout_seconds: float | None,
+) -> tuple[str, str]:
+    """Drain the process; on timeout kill its whole tree, drain again, re-raise.
+
+    ::
+
+        codex -> codex.exe -> code-mode-host   grandchildren hold the stdout pipe
+        kill only the parent on timeout        drain waits for EOF, hangs
+        ok: kill the whole tree, then drain    pipe reaches EOF, timeout raised
+
+    Killing only the direct child on a timeout leaves grandchildren holding the
+    capture pipe open, so the drain read never reaches end-of-file and blocks
+    forever. Killing the entire tree and then draining with a grace timeout lets
+    the pipe reach end-of-file without an unbounded wait.
+    """
+    try:
+        return review_process.communicate(timeout=timeout_seconds)
+    except subprocess.TimeoutExpired:
+        _terminate_process_tree(review_process)
+        _drain_process_after_tree_kill(review_process)
+        raise
+
+
+def _completed_from_streams(
+    all_arguments: list[str],
+    review_return_code: int,
+    captured_stdout: str,
+    captured_stderr: str,
+    should_check: bool,
+) -> subprocess.CompletedProcess[str]:
+    """Wrap captured streams in a CompletedProcess, honoring the check flag."""
+    completed_process = subprocess.CompletedProcess(
+        all_arguments, review_return_code, captured_stdout, captured_stderr
+    )
+    if should_check:
+        completed_process.check_returncode()
+    return completed_process
+
+
+def _optional_timeout_seconds(requested_timeout: object) -> float | None:
+    """Return a numeric timeout as float, or None when it is not a number."""
+    if isinstance(requested_timeout, (int, float)):
+        return float(requested_timeout)
+    return None
+
+
+def _close_popen_streams(review_process: subprocess.Popen[str]) -> None:
+    """Close the child's stdio pipes without waiting for process exit."""
+    for each_stream in (review_process.stdout, review_process.stderr, review_process.stdin):
+        if each_stream is None:
+            continue
+        try:
+            each_stream.close()
+        except OSError:
+            pass
+
+
+def _reap_process_with_grace(review_process: subprocess.Popen[str]) -> None:
+    """Kill and wait with a grace timeout so cleanup never blocks unbounded.
+
+    ::
+
+        poll None after incomplete drain   ok: kill + wait(grace), then return
+        Popen.__exit__ wait() no timeout   flag: hang forever on surviving child
+
+    ``Popen`` as a context manager always ends in ``wait()`` with no timeout.
+    After a timed-out drain that still leaves the child alive, that wait would
+    hang. This path kills once more and bounds the reap.
+    """
+    if review_process.poll() is not None:
+        return
+    try:
+        review_process.kill()
+    except ProcessLookupError:
+        return
+    try:
+        review_process.wait(timeout=PROCESS_TREE_KILL_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired:
+        return
+
+
+def _run_codex_process(
+    all_arguments: list[str],
+    **all_keyword_arguments: object,
+) -> subprocess.CompletedProcess[str]:
+    """Run a codex process, killing its whole child tree on a timeout.
+
+    Mirrors the ``subprocess.run`` keyword arguments the review wrapper passes:
+    ``cwd``, ``capture_output``, ``text``, ``encoding``, ``check``, ``timeout``,
+    and ``env``. Avoids ``Popen`` as a context manager so a surviving child after
+    a timed-out drain cannot hang on an unbounded ``wait()``.
+    """
+    timeout_seconds = _optional_timeout_seconds(all_keyword_arguments.get(TIMEOUT_KEYWORD))
+    should_check = bool(all_keyword_arguments.get(CHECK_KEYWORD, False))
+    review_process = _open_codex_popen(all_arguments, all_keyword_arguments)
+    try:
+        captured_stdout, captured_stderr = _communicate_with_tree_kill_on_timeout(
+            review_process, timeout_seconds
+        )
+        review_return_code = review_process.returncode
+    finally:
+        _close_popen_streams(review_process)
+        _reap_process_with_grace(review_process)
+    return _completed_from_streams(
+        all_arguments,
+        review_return_code,
+        captured_stdout,
+        captured_stderr,
+        should_check,
+    )
+
+
+codex_subprocess_runner = _run_codex_process
 
 
 @dataclass(frozen=True)

package/skills/codex-review/scripts/test_run_codex_review.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import Callable
 
@@ -810,3 +811,191 @@ def test_resolve_prefix_falls_back_to_bare_name_when_absent(
     monkeypatch.setattr(wrapper.shutil, "which", lambda _name: None)
 
     assert wrapper._resolve_codex_command_prefix() == [CODEX_BINARY_NAME]
+
+
+def _is_process_running(process_identifier: int) -> bool:
+    if sys.platform == "win32":
+        process_listing = subprocess.run(
+            ["tasklist", "/FI", f"PID eq {process_identifier}"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return str(process_identifier) in process_listing.stdout
+    liveness_probe = subprocess.run(
+        ["kill", "-0", str(process_identifier)],
+        capture_output=True,
+        check=False,
+    )
+    return liveness_probe.returncode == 0
+
+
+def _wait_until_process_stops(
+    process_identifier: int, deadline_seconds: float
+) -> bool:
+    poll_interval_seconds = 0.5
+    deadline = time.monotonic() + deadline_seconds
+    while time.monotonic() < deadline:
+        if not _is_process_running(process_identifier):
+            return True
+        time.sleep(poll_interval_seconds)
+    return not _is_process_running(process_identifier)
+
+
+def _grandchild_spawn_source(grandchild_pid_path: Path, lifetime_seconds: int) -> str:
+    """Python source that spawns a grandchild and records its PID before sleeping.
+
+    ::
+
+        Popen(grandchild) -> write grandchild.pid -> sleep    grandchild holds pipe
+    """
+    return (
+        "import subprocess, sys, time, pathlib; "
+        "grandchild = subprocess.Popen([sys.executable, '-c', "
+        f"'import time; time.sleep({lifetime_seconds})']); "
+        f"pathlib.Path(r'{grandchild_pid_path}').write_text(str(grandchild.pid)); "
+        f"time.sleep({lifetime_seconds})"
+    )
+
+
+def test_run_command_kills_grandchild_tree_on_timeout_without_hanging(
+    tmp_path: Path,
+) -> None:
+    """The timeout kills the grandchild that inherited the capture pipe.
+
+    ::
+
+        middle -> grandchild, timeout at 2s    ok: grandchild PID stops running
+        kill only the middle child             flag: grandchild lives on 30s
+
+    A direct-child-only kill leaves the grandchild alive on POSIX, so asserting
+    the recorded grandchild PID stops running guards the regression in CI.
+    """
+    grandchild_lifetime_seconds = 30
+    review_timeout_seconds = 2
+    wall_clock_ceiling_seconds = 20
+    grandchild_pid_path = tmp_path / "grandchild.pid"
+    grandchild_source = _grandchild_spawn_source(
+        grandchild_pid_path, grandchild_lifetime_seconds
+    )
+    start_time = time.monotonic()
+    with pytest.raises(subprocess.TimeoutExpired):
+        wrapper._run_command(
+            [sys.executable, "-c", grandchild_source],
+            working_directory=tmp_path,
+            timeout_seconds=review_timeout_seconds,
+        )
+    assert time.monotonic() - start_time < wall_clock_ceiling_seconds
+    grandchild_identifier = int(grandchild_pid_path.read_text())
+    assert _wait_until_process_stops(grandchild_identifier, wall_clock_ceiling_seconds)
+
+
+def test_windows_process_tree_kill_builds_taskkill_argv(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The Windows kill path issues taskkill /T /F /PID for the given process id."""
+    target_process_identifier = 4242
+    recorded_argv: list[list[str]] = []
+
+    def record_argv(all_arguments: list[str], **_keywords: object) -> None:
+        recorded_argv.append(all_arguments)
+
+    monkeypatch.setattr(wrapper.subprocess, "run", record_argv)
+    wrapper._kill_windows_process_tree(target_process_identifier)
+
+    assert recorded_argv == [
+        ["taskkill", "/T", "/F", "/PID", str(target_process_identifier)]
+    ]
+
+
+def test_windows_process_tree_kill_swallows_taskkill_timeout(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A hung taskkill must not raise — caller falls back to Popen.kill + drain."""
+
+    def raise_taskkill_timeout(
+        _all_arguments: list[str], **_keywords: object
+    ) -> None:
+        raise subprocess.TimeoutExpired(cmd="taskkill", timeout=1)
+
+    monkeypatch.setattr(wrapper.subprocess, "run", raise_taskkill_timeout)
+    wrapper._kill_windows_process_tree(4242)
+
+
+def test_drain_joins_pipes_when_direct_kill_raises_process_lookup_error() -> None:
+    """Even when the process is already gone, drain still joins pipe readers."""
+    all_communicate_timeouts: list[float | None] = []
+
+    class _AlreadyDeadProcess:
+        def communicate(
+            self, timeout: float | None = None
+        ) -> tuple[str, str]:
+            all_communicate_timeouts.append(timeout)
+            if len(all_communicate_timeouts) == 1:
+                raise subprocess.TimeoutExpired(cmd="codex", timeout=timeout or 0)
+            return "", ""
+
+        def kill(self) -> None:
+            raise ProcessLookupError()
+
+    already_dead_process = _AlreadyDeadProcess()
+    wrapper._drain_process_after_tree_kill(
+        already_dead_process  # type: ignore[arg-type]  # duck-typed Popen stand-in
+    )
+    assert len(all_communicate_timeouts) == 2
+
+
+def test_reap_process_with_grace_bounds_wait_when_child_survives() -> None:
+    """Cleanup kills a surviving child and waits with a grace timeout, not forever."""
+    all_wait_timeouts: list[float | None] = []
+    all_kill_calls: list[bool] = []
+
+    class _SurvivingProcess:
+        def poll(self) -> int | None:
+            return None
+
+        def kill(self) -> None:
+            all_kill_calls.append(True)
+
+        def wait(self, timeout: float | None = None) -> int:
+            all_wait_timeouts.append(timeout)
+            raise subprocess.TimeoutExpired(cmd="codex", timeout=timeout or 0)
+
+    surviving_process = _SurvivingProcess()
+    wrapper._reap_process_with_grace(
+        surviving_process  # type: ignore[arg-type]  # duck-typed Popen stand-in
+    )
+    assert all_kill_calls == [True]
+    assert all_wait_timeouts == [wrapper.PROCESS_TREE_KILL_TIMEOUT_SECONDS]
+
+
+def test_run_command_surfaces_timeout_when_tree_kill_is_noop(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """An incomplete tree kill still raises TimeoutExpired inside a wall ceiling.
+
+    ::
+
+        terminate is a no-op, child sleeps 60s    ok: TimeoutExpired < 25s wall
+        no post-kill drain / fallback kill        flag: hang past ceiling on wait
+
+    The post-kill grace drain and direct-child kill fallback keep the caller
+    from blocking forever when taskkill/killpg leave the direct child alive.
+    """
+    review_timeout_seconds = 1
+    wall_clock_ceiling_seconds = 25
+    sleep_source = "import time; time.sleep(60)"
+
+    def leave_process_alive(_review_process: object) -> None:
+        return None
+
+    monkeypatch.setattr(wrapper, "_terminate_process_tree", leave_process_alive)
+    start_time = time.monotonic()
+    with pytest.raises(subprocess.TimeoutExpired):
+        wrapper._run_command(
+            [sys.executable, "-c", sleep_source],
+            working_directory=tmp_path,
+            timeout_seconds=review_timeout_seconds,
+        )
+    assert time.monotonic() - start_time < wall_clock_ceiling_seconds