claude-dev-env 2.7.0 → 2.8.0

package/_shared/CLAUDE.md

@@ -8,6 +8,7 @@ Cross-cutting runtime assets shared by multiple skills. The PR-loop skills (`bug
 |---|---|
 | `pr-loop/` | Docs, scripts, and constants for the PR-loop workflow suite |
 | `advisor/` | Warm-advisor spawn-and-consult protocol for `team-advisor` and `orchestrator` |
+| `process-tree/` | One process-tree kill helper for every script that captures a spawned CLI's output |
 
 ## Install path
 

package/_shared/advisor/advisor-protocol.md

@@ -20,19 +20,19 @@ Use the **Model floor** ladder below (Fable → Opus → Sonnet → Haiku). Warm
 
 ### Third-party host
 
-A third-party (non-Claude) harness cannot spawn a Claude `session-advisor` through the Agent tool. Bind a **max-tier Claude advisor** through the shared CLI Claude-chain (account usage failover). Do **not** treat this third-party session as the advisor.
+A third-party (non-Claude) harness cannot spawn a Claude `session-advisor` through the Agent tool. Bind a **max-tier Claude advisor** through the shared CLI Claude-chain. Do **not** treat this third-party session as the advisor.
 
 1. Detect host profile first (this section).
 2. Set the advisor floor to **Opus** so the walk is `candidate_tiers = ["Fable", "Opus"]` with `own_tier = Opus`. The walk never drops to Sonnet or Haiku on a third-party host.
 3. **CLI bind (primary path):** for each candidate top-down, pipe a charter file into:
 
    ```
-   python "$HOME/.claude/scripts/claude_chain_runner.py" -- -p --model <alias> --effort <effort> --output-format json
+   python "$HOME/.claude/scripts/claude_chain_runner.py" --routing-mode ordered_account -- -p --model <alias> --effort <effort> --output-format json
    ```
 
-   Use `--model fable --effort high` on Fable; use `--model opus --effort max` on Opus. The chain runner probes weekly remaining via `claude_chain_usage` / the usage-pause OAuth probe, ranks accounts in `~/.claude/claude-chain.json` highest remaining first, and fails over only on a usage-limit signature.
-4. Stop at the first successful bind. Record `{tier, result: "cli"}` and set `selected_tier` to that tier. Persist `session_id` from the JSON events (any event carries it; reply text is the `type == "result"` event's `.result` field). Run every bind and every later consult with cwd set to the repo root the work is for — Claude sessions are project-scoped by working directory.
-5. **Fail closed:** when every candidate fails (chain exhausted or model unavailable), set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. Do **not** answer ENDORSE / CORRECTION / PLAN / STOP as this third-party session. Do **not** self-endorse.
+   Use `--model fable --effort high` on Fable; use `--model opus --effort max` on Opus. **Root advisor bind** uses `--routing-mode ordered_account`: the runner walks `~/.claude/claude-chain.json` in **config order** (primary launcher first, secondary next), and fails over to the next entry **only** on a usage-limit signature. Authentication, timeout, configuration, and other non-usage process errors stop immediately with `terminal_status=advisor_blocked` (exit code 4 on the CLI) — they do **not** fall through to the next launcher. General (non-root) chain calls keep the default `--routing-mode usage_ranked`, which probes weekly remaining via `claude_chain_usage` / the usage-pause OAuth probe and ranks highest remaining first.
+4. Stop at the first successful bind. Record `{tier, result: "cli"}` and set `selected_tier` to that tier. Persist `session_id` from the JSON events (any event carries it; the runner also surfaces it on `ChainInvocationOutcome.session_id`; reply text is the `type == "result"` event's `.result` field). Run every bind and every later consult with cwd set to the repo root the work is for — Claude sessions are project-scoped by working directory.
+5. **Fail closed:** when every candidate fails (chain exhausted, `advisor_blocked`, or model unavailable), set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. Do **not** answer ENDORSE / CORRECTION / PLAN / STOP as this third-party session. Do **not** self-endorse.
 6. Paste the **Third-party host** Advisor block into every executor spawn prompt — never the Claude SendMessage block. Executors report to the orchestrating session; that session consults the bound Claude CLI advisor and relays the four-signal reply.
 
 Resolve a third-party session's own model field with `resolve_cli_model_id("ThirdParty")` → `third-party` when a host model alias is required. The **advisor** bind uses Fable/Opus aliases only.
@@ -66,10 +66,11 @@ On a **Claude host**, the consuming skill's session walks the candidate tiers to
 - `model`: the short alias for that attempt's candidate tier via `resolve_cli_model_id` (or the alias table under CLI chain) — for example `opus`, not Title Case `Opus`. The floor is only the lower bound of the walk; the walk still tries stronger tiers first.
 - `name`: a name the session and every consumer will use to reach it (e.g. `team-advisor-agent`).
 - `run_in_background: true`.
+- `prompt`: the charter below. A **Fable**-tier attempt carries the exact token `FABLE-SPAWN-AUTHORIZED` in that prompt — `hooks/blocking/fable_spawn_gate.py` denies every `Agent` or `Task` spawn at `model: fable` whose prompt lacks that token. An attempt at any other tier needs no token.
 
 Stop at the first successful spawn. That attempt's tier is `selected_tier`; the warm agent lives at that tier for the rest of the session. If every candidate down to the floor fails, take the CLI fallback below.
 
-Charter (the spawn prompt): the agent's role — standing reviewer, never edits files or runs commands, only answers via SendMessage — the repo path, and the session's current goal in two or three sentences. State plainly:
+Charter (the spawn prompt): the agent's role — standing reviewer, never edits files or runs commands, only answers via SendMessage — the repo path, and the session's current goal in two or three sentences. On a Fable-tier attempt, include the exact token `FABLE-SPAWN-AUTHORIZED` as plain text in this prompt (substring match; the gate does not verify who placed it). State plainly:
 - Every consult carries: who is asking (name and assignment), what changed since their last consult, the live decision or question, and any load-bearing paths or excerpts.
 - Reply via SendMessage to whoever sent the consult, by name — never route a reply through the spawning session or "main." Many different consumers may reach this one agent; each reply goes back to its own sender.
 - Treat each consult on its own terms, keyed to the sender's stated assignment. Different consumers' consults will interleave in this one transcript — don't blend context across consumers unless a consult explicitly asks for that.
@@ -112,7 +113,7 @@ Each paragraph is self-contained — the executor receives only this text, not t
 
 The session that spawns the shared advisor owns its whole lifecycle — spawn, drift-respawn, and shutdown. Every other consumer (executors, or any other consulting session) only ever sends it messages; none of them spawn, respawn, or shut it down themselves. One shared advisor exists per orchestrated session, owned by the session that spawned it.
 
-**Re-spawn on drift.** If a reply shows the agent working from a stale picture, or the session pivots to an unrelated task, the owning session ends that agent and spawns a fresh one with a new charter, rather than forcing the old context to stretch across two different jobs.
+**Re-spawn on drift.** If a reply shows the agent working from a stale picture, or the session pivots to an unrelated task, the owning session ends that agent and spawns a fresh one with a new charter, rather than forcing the old context to stretch across two different jobs. A **Fable**-tier re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in that fresh prompt, as a Fable-tier warm-up attempt does.
 
 ### Third-party host
 
@@ -122,9 +123,18 @@ The orchestrating session owns the Claude CLI advisor bind for the whole run —
 
 ## CLI chain
 
-The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" -- <claude args...>`. It ranks accounts in `~/.claude/claude-chain.json` by weekly remaining (via `claude_chain_usage` / the usage-pause OAuth probe) and fails over to the next ranked binary only on a usage-limit signature, so a usage-limited first try still gets served.
+The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" [--routing-mode usage_ranked|ordered_account] -- <claude args...>`.
 
-**Third-party host:** this runner is the **primary** advisor bind and consult path (see **Host profiles → Third-party host**). Map each walk attempt to `--model <alias>` and the effort flags there. When the walk exhausts, fail closed.
+| Mode | Flag | Walk order | Failover |
+|---|---|---|---|
+| Usage-ranked (default) | `--routing-mode usage_ranked` or omit the flag | Highest weekly remaining first (`claude_chain_usage` / usage-pause OAuth probe) | Usage-limit signature only |
+| Ordered-account | `--routing-mode ordered_account` | Config list order in `~/.claude/claude-chain.json` | Usage-limit signature only; auth / timeout / config / other process errors → `advisor_blocked` |
+
+**Third-party host root advisor bind and consult:** use **ordered-account** mode (see **Host profiles → Third-party host**). Primary launcher from the chain config is tried first; a usage-limit result advances to the next config entry; any non-usage failure terminates as `advisor_blocked`. Persist `session_id` from a successful bind and pass it to `-p --resume <session_id> --output-format json` on later consults.
+
+**General chain calls** (non-root automation): keep the default usage-ranked mode so spare capacity on other accounts is preferred.
+
+**Third-party host:** this runner is the **primary** advisor bind and consult path. Map each walk attempt to `--model <alias>` and the effort flags there. When the walk exhausts or returns `advisor_blocked`, fail closed.
 
 **Claude host:** fall back to this runner when any of these holds, rather than on judgment call:
 - The Agent-tool spawn errors at every candidate tier down to the floor — the tool itself, not just the top tier, is unavailable.

package/_shared/pr-loop/audit-contract.md

@@ -22,7 +22,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
   "id": "loop<L>-<K>",
   "file": "path/relative/to/repo/root.py",
   "line": 123,
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
+  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q",
   "severity": "P0 | P1 | P2",
   "excerpt": "verbatim code snippet from the offending line(s)",
   "failure_mode": "one sentence describing what goes wrong and when",
@@ -38,7 +38,7 @@ Used when an audit investigates a category and does NOT find a bug. Bare "verifi
 
 ```json
 {
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
+  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q",
   "files_opened": ["file1.py", "file2.py"],
   "lines_quoted": [
     {"file": "file1.py", "line": 88, "text": "verbatim line content"}
@@ -108,7 +108,7 @@ Merge rules — applied whenever the LEAD combines findings from multiple source
 - **Zero secondary findings**: the primary set is trusted and the audit moves on.
 - **Malformed or non-parseable secondary output**: lead trusts the primary set and logs the event in `loop-<L>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
 
-For `/bugteam`, the single audit agent provides per-category coverage by walking all A–P rubrics in one invocation.
+For `/bugteam`, the single audit agent provides per-category coverage by walking all A–Q rubrics in one invocation.
 
 ## Post-fix self-audit
 
@@ -121,7 +121,7 @@ Sequence:
 3. Run `py_compile` (or language-equivalent) on each modified file.
 4. Compute `fix_diff` against pre-fix contents for the modified set.
 5. Run `_shared/pr-loop/scripts/code_rules_gate.py` with explicit paths for every modified file.
-6. Spawn a scoped audit of `fix_diff` with full A–P rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
+6. Spawn a scoped audit of `fix_diff` with full A–Q rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
 7. Read the previous loop's outcome XML (`<worktree_path>/.bugteam-pr<N>-loop<L-1>.outcomes.xml`) and obtain its total finding count. If this is the first loop (L <= 1) or the file does not exist, skip this comparison. Compute the post-fix total: previous total minus bugs fixed in this round plus new violations found in the post-fix audit (step 6). If the post-fix total exceeds the previous total, flag all new findings as same-loop fix-targets and revise. An increase in total findings across loop transitions is a regression.
 8. Any new findings become same-loop fix-targets. Internal iteration count increments by one.
 9. After 3 internal iterations with fresh findings each time, exit `stuck: post-fix audit not converging`.

package/_shared/pr-loop/precatch-rubric.md

@@ -54,7 +54,7 @@ The PR body and the diff describe the same change, both directions.
 ## Lane 5 — Adversarial audit
 
 The bug-audit lens runs the adversarial second pass the audit contract specifies
-(`~/.claude/_shared/pr-loop/audit-contract.md`): assume the first A-P pass missed
+(`~/.claude/_shared/pr-loop/audit-contract.md`): assume the first A-Q pass missed
 at least three P1 bugs, then find them.
 
 - Return new file:line findings for the bugs the first pass missed.
@@ -62,4 +62,4 @@ at least three P1 bugs, then find them.
   and why it holds.
 - A bare "nothing new" is not an acceptable result for this pass.
 - **Proof of absence:** a per-category adversarial-probe entry for each re-examined
-  A-P category with no new finding.
+  A-Q category with no new finding.

package/_shared/pr-loop/worker-spawn.md

@@ -73,10 +73,12 @@ plus the process exit code.
 
 `resolve_worker_spawn(...)` takes keyword-only arguments:
 `role`, `prompt_file`, `working_directory`, `timeout_seconds`,
-`is_claude_tier_enabled`, `run_state_directory`, `max_turns`.
+`is_claude_tier_enabled`, `run_state_directory`.
 `encode_spawn_outcome` turns a `SpawnOutcome` into the same JSON shape the CLI
 prints.
 
+The grok tier runs with no turn cap; `timeout_seconds` is its only bound.
+
 ## JSON result shape
 
 Stdout is one JSON object:

package/_shared/process-tree/CLAUDE.md

@@ -0,0 +1,41 @@
+# _shared/process-tree
+
+One home for ending a spawned process together with every descendant it
+started. Callers that capture a CLI's output import it so a grandchild can
+never outlive the run and hold the capture pipe open.
+
+## Consumers
+
+| Caller | Use |
+|---|---|
+| `scripts/grok_headless_runner.py` | Kills a timed-out worker's tree between drain attempts |
+| `skills/codex-review/scripts/run_codex_review.py` | Kills the review tree on timeout, then drains |
+| `skills/codex-review/scripts/codex_usage_probe.py` | Tears the app-server tree down after the rate-limits exchange |
+
+A skill script reaches this home the way the bugteam scripts reach
+`_shared/pr-loop/scripts`: it puts the directory on `sys.path` and imports by
+module name. `bin/install.mjs` copies `_shared` and `scripts` together, and
+every install group that carries a consumer carries `_shared`, so the import
+resolves in the repository and under `~/.claude` alike.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `scripts/process_tree_kill.py` | `terminate_process_tree` (poll, platform tree kill, re-poll, `Popen.kill()` fallback), `kill_process_tree_by_identifier`, and `should_start_new_session` for the matching `Popen` flag |
+| `scripts/test_process_tree_kill.py` | Behavioral tests for every public entry point here, each platform branch, each failure the helper swallows, and the `Popen.kill()` fallback |
+| `scripts/config/process_tree_scripts_constants/process_tree_kill_constants.py` | The taskkill command, its `/T`, `/F`, and `/PID` flags, and the bound on the kill command |
+| `scripts/pyproject.toml` | mypy configuration; `check.ps1` runs it under the `mypy-process-tree` label |
+
+## Platform guard
+
+Both the branch selector and the POSIX helper compare `sys.platform` against
+the literal `"win32"`. That literal is what mypy narrows on: behind a named
+constant, `os.getpgid`, `os.killpg`, and `signal.SIGKILL` fail type checking on
+Windows.
+
+## Pairing rule
+
+`os.killpg` signals a whole process group, so a child sharing the caller's
+group takes the caller down with it. Every `Popen` whose tree this module ends
+passes `start_new_session=should_start_new_session()`.

package/_shared/process-tree/scripts/config/process_tree_scripts_constants/__init__.py

@@ -0,0 +1 @@
+"""Named constants for the shared process-tree scripts."""

package/_shared/process-tree/scripts/config/process_tree_scripts_constants/process_tree_kill_constants.py

@@ -0,0 +1,27 @@
+"""Named constants for ``process_tree_kill.py``.
+
+Every caller that ends a child process and its descendants reads the taskkill
+command, its flags, and the bound on the kill command from here rather than
+embedding the values in its own module.
+"""
+
+from __future__ import annotations
+
+WINDOWS_TASKKILL_COMMAND: str = "taskkill"
+"""Windows command that ends a process by id."""
+
+WINDOWS_TASKKILL_TREE_FLAG: str = "/T"
+"""``taskkill`` flag that extends the kill to every descendant process."""
+
+WINDOWS_TASKKILL_FORCE_FLAG: str = "/F"
+"""``taskkill`` flag that forces termination rather than requesting it."""
+
+WINDOWS_TASKKILL_PID_FLAG: str = "/PID"
+"""``taskkill`` flag that names the target process id."""
+
+PROCESS_TREE_KILL_TIMEOUT_SECONDS: int = 10
+"""Seconds allowed for the tree-kill command itself before it is abandoned.
+
+Gates the kill command alone. Each caller sets its own bound on the drain that
+follows the kill.
+"""

package/_shared/process-tree/scripts/process_tree_kill.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""End a spawned process and every descendant it started.
+
+A CLI launched from a script often spawns its own children, and those
+grandchildren hold the capture pipe open. Killing the direct child alone leaves
+them running and the reading caller waiting on a pipe that never reaches
+end-of-file. This module ends the whole tree instead::
+
+    terminate_process_tree(process)   ok:   grandchildren die, pipes close
+    process.kill()                    flag: grandchildren outlive the parent
+
+Windows tears the tree down with ``taskkill /T``. POSIX signals the child's
+process group. The group signal reaches only the intended tree when the child
+leads its own session, so every caller pairs the two calls::
+
+    process = subprocess.Popen(
+        argv, start_new_session=should_start_new_session()
+    )
+    terminate_process_tree(process)
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+_config_directory = str(Path(__file__).resolve().parent / "config")
+if _config_directory not in sys.path:
+    sys.path.insert(0, _config_directory)
+
+from process_tree_scripts_constants.process_tree_kill_constants import (  # noqa: E402
+    PROCESS_TREE_KILL_TIMEOUT_SECONDS,
+    WINDOWS_TASKKILL_COMMAND,
+    WINDOWS_TASKKILL_FORCE_FLAG,
+    WINDOWS_TASKKILL_PID_FLAG,
+    WINDOWS_TASKKILL_TREE_FLAG,
+)
+
+process_tree_subprocess_run = subprocess.run
+
+
+def should_start_new_session() -> bool:
+    """Report whether a child should be launched as its own session leader.
+
+    POSIX ends a tree through ``os.killpg``, which signals every process in the
+    group. A child sharing the caller's group would take the caller down with
+    it, so the child leads a session of its own. Windows has no session flag
+    and ends the tree by process id, so the answer there is False.
+    """
+    return sys.platform != "win32"
+
+
+def _kill_windows_process_tree(process_identifier: int) -> None:
+    """End a Windows process and every descendant it started, by process id.
+
+    Swallows taskkill failures so the caller still falls back to
+    ``Popen.kill()`` and its own drain. A raised ``TimeoutExpired`` here would
+    replace the caller's original timeout exception and skip that fallback.
+    """
+    try:
+        process_tree_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:
+    """End a POSIX process group so no grandchild keeps the capture pipe open.
+
+    A process id that is already reaped, or one the caller may not signal,
+    raises ``OSError``; this swallows it and returns, so the caller falls back
+    to ``Popen.kill()``.
+
+    The leading literal ``sys.platform`` comparison is what lets mypy read the
+    rest of the body as POSIX-only. Under a named constant, ``os.getpgid``,
+    ``os.killpg``, and ``signal.SIGKILL`` fail type checking on Windows.
+    """
+    if sys.platform == "win32":
+        return
+    try:
+        process_group_identifier = os.getpgid(process_identifier)
+        os.killpg(process_group_identifier, signal.SIGKILL)
+    except OSError:
+        return
+
+
+def kill_process_tree_by_identifier(process_identifier: int) -> None:
+    """Issue the platform's tree kill for one process id, with no liveness check.
+
+    The platform test is written as a literal ``sys.platform`` comparison
+    because that is the form mypy narrows: under a named constant the
+    process-group calls in the POSIX branch fail type checking on Windows.
+
+    Args:
+        process_identifier: The process id whose tree is ended.
+    """
+    if sys.platform == "win32":
+        _kill_windows_process_tree(process_identifier)
+        return
+    _kill_posix_process_group(process_identifier)
+
+
+def terminate_process_tree(process: subprocess.Popen[str]) -> None:
+    """End a running process and every descendant it spawned.
+
+    ::
+
+        already exited             ok:  returns, nothing killed
+        tree kill takes            ok:  grandchildren die, pipes close
+        tree kill misses the child ok:  Popen.kill() ends the direct child
+        child exits mid-kill       ok:  the raised lookup error is swallowed
+
+    Falls back to ``Popen.kill()`` when the direct child survives the tree kill,
+    so the caller never waits on a live process.
+
+    Args:
+        process: The process whose tree is ended.
+    """
+    if process.poll() is not None:
+        return
+    kill_process_tree_by_identifier(process.pid)
+    if process.poll() is not None:
+        return
+    try:
+        process.kill()
+    except ProcessLookupError:
+        return

package/_shared/process-tree/scripts/pyproject.toml

@@ -0,0 +1,16 @@
+# mypy configuration for the shared process-tree scripts.
+#
+# Scoped separately from hooks/pyproject.toml so this shared home and the hooks
+# stay independent. check.ps1 invokes this via the mypy-process-tree tool label.
+
+[tool.mypy]
+mypy_path = ".:config"
+python_version = "3.13"
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+no_implicit_optional = true
+strict_equality = true
+exclude = [
+    "test_",
+]

package/_shared/process-tree/scripts/test_process_tree_kill.py

@@ -0,0 +1,278 @@
+"""Behavioral tests for the shared process-tree kill helper.
+
+Every test drives ``process_tree_kill`` itself: the platform branch it picks,
+the taskkill argv it builds, the failures it swallows, and the
+``Popen.kill()`` fallback it reaches when a tree kill leaves the child alive.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+import process_tree_kill  # noqa: E402
+from process_tree_kill import (  # noqa: E402
+    kill_process_tree_by_identifier,
+    terminate_process_tree,
+)
+from process_tree_scripts_constants.process_tree_kill_constants import (  # noqa: E402
+    PROCESS_TREE_KILL_TIMEOUT_SECONDS,
+    WINDOWS_TASKKILL_COMMAND,
+    WINDOWS_TASKKILL_FORCE_FLAG,
+    WINDOWS_TASKKILL_PID_FLAG,
+    WINDOWS_TASKKILL_TREE_FLAG,
+)
+
+FAKE_PROCESS_IDENTIFIER = 4242
+FAKE_PROCESS_GROUP_IDENTIFIER = 909
+WINDOWS_PLATFORM = "win32"
+POSIX_PLATFORM = "linux"
+FAKE_KILL_SIGNAL = 9
+
+
+class _FakeProcess:
+    """Stands in for ``subprocess.Popen`` with a scripted liveness sequence.
+
+    ``poll()`` returns each queued answer in turn, so a test names exactly what
+    the helper sees before the tree kill and after it.
+    """
+
+    def __init__(
+        self,
+        all_poll_results: list[int | None],
+        *,
+        kill_error: BaseException | None = None,
+    ) -> None:
+        self.pid = FAKE_PROCESS_IDENTIFIER
+        self._all_poll_results = list(all_poll_results)
+        self._kill_error = kill_error
+        self.kill_calls = 0
+
+    def poll(self) -> int | None:
+        if not self._all_poll_results:
+            return None
+        return self._all_poll_results.pop(0)
+
+    def kill(self) -> None:
+        self.kill_calls += 1
+        if self._kill_error is not None:
+            raise self._kill_error
+
+
+class _TreeKillRecorder:
+    """Stands in for ``subprocess.run`` so no real taskkill leaves the test."""
+
+    def __init__(self, raised_error: BaseException | None = None) -> None:
+        self.all_invocations: list[list[str]] = []
+        self.all_keyword_arguments: list[dict[str, object]] = []
+        self._raised_error = raised_error
+
+    def __call__(
+        self, invocation: list[str], **keyword_arguments: object
+    ) -> subprocess.CompletedProcess[str]:
+        self.all_invocations.append(list(invocation))
+        self.all_keyword_arguments.append(dict(keyword_arguments))
+        if self._raised_error is not None:
+            raise self._raised_error
+        return subprocess.CompletedProcess(args=invocation, returncode=0)
+
+
+def _install_windows_platform(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(process_tree_kill.sys, "platform", WINDOWS_PLATFORM)
+
+
+def _install_posix_platform(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(process_tree_kill.sys, "platform", POSIX_PLATFORM)
+    monkeypatch.setattr(
+        process_tree_kill.signal, "SIGKILL", FAKE_KILL_SIGNAL, raising=False
+    )
+
+
+def test_windows_tree_kill_issues_the_taskkill_tree_argv(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The Windows branch runs ``taskkill /T /F /PID <pid>`` under its timeout."""
+    tree_kill_recorder = _TreeKillRecorder()
+    _install_windows_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill, "process_tree_subprocess_run", tree_kill_recorder
+    )
+
+    kill_process_tree_by_identifier(FAKE_PROCESS_IDENTIFIER)
+
+    assert tree_kill_recorder.all_invocations == [
+        [
+            WINDOWS_TASKKILL_COMMAND,
+            WINDOWS_TASKKILL_TREE_FLAG,
+            WINDOWS_TASKKILL_FORCE_FLAG,
+            WINDOWS_TASKKILL_PID_FLAG,
+            str(FAKE_PROCESS_IDENTIFIER),
+        ]
+    ]
+    assert (
+        tree_kill_recorder.all_keyword_arguments[0].get("timeout")
+        == PROCESS_TREE_KILL_TIMEOUT_SECONDS
+    )
+
+
+@pytest.mark.parametrize(
+    "raised_error",
+    [
+        subprocess.TimeoutExpired(
+            cmd=[WINDOWS_TASKKILL_COMMAND], timeout=PROCESS_TREE_KILL_TIMEOUT_SECONDS
+        ),
+        OSError("taskkill is not on PATH"),
+    ],
+    ids=["taskkill_times_out", "taskkill_cannot_launch"],
+)
+def test_windows_tree_kill_swallows_a_failing_taskkill(
+    monkeypatch: pytest.MonkeyPatch, raised_error: BaseException
+) -> None:
+    """A taskkill that hangs or cannot launch leaves the caller free to fall back."""
+    _install_windows_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill,
+        "process_tree_subprocess_run",
+        _TreeKillRecorder(raised_error),
+    )
+
+    kill_process_tree_by_identifier(FAKE_PROCESS_IDENTIFIER)
+
+
+def test_posix_tree_kill_signals_the_whole_process_group(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The POSIX branch resolves the child's group and signals the group, not the pid."""
+    all_group_signals: list[tuple[int, int]] = []
+    _install_posix_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill.os,
+        "getpgid",
+        lambda process_identifier: FAKE_PROCESS_GROUP_IDENTIFIER,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        process_tree_kill.os,
+        "killpg",
+        lambda group_identifier, signal_number: all_group_signals.append(
+            (group_identifier, signal_number)
+        ),
+        raising=False,
+    )
+
+    kill_process_tree_by_identifier(FAKE_PROCESS_IDENTIFIER)
+
+    assert all_group_signals == [(FAKE_PROCESS_GROUP_IDENTIFIER, FAKE_KILL_SIGNAL)]
+
+
+def test_posix_tree_kill_swallows_an_already_reaped_process(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A pid already reaped raises OSError; the caller still gets its fallback."""
+
+    def raise_no_such_process(process_identifier: int) -> int:
+        del process_identifier
+        raise ProcessLookupError("no such process")
+
+    _install_posix_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill.os, "getpgid", raise_no_such_process, raising=False
+    )
+
+    kill_process_tree_by_identifier(FAKE_PROCESS_IDENTIFIER)
+
+
+def test_terminate_skips_a_process_that_already_exited(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """An exited process needs no kill, so neither the tree kill nor kill() runs."""
+    tree_kill_recorder = _TreeKillRecorder()
+    _install_windows_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill, "process_tree_subprocess_run", tree_kill_recorder
+    )
+    exited_process = _FakeProcess([0])
+
+    terminate_process_tree(exited_process)  # type: ignore[arg-type]
+
+    assert tree_kill_recorder.all_invocations == []
+    assert exited_process.kill_calls == 0
+
+
+def test_terminate_stops_after_a_tree_kill_that_took(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A tree kill that ends the child leaves no work for the kill() fallback."""
+    _install_windows_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill, "process_tree_subprocess_run", _TreeKillRecorder()
+    )
+    killed_process = _FakeProcess([None, 0])
+
+    terminate_process_tree(killed_process)  # type: ignore[arg-type]
+
+    assert killed_process.kill_calls == 0
+
+
+def test_terminate_falls_back_to_direct_kill_when_the_tree_kill_misses(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A child alive after the tree kill is killed directly, so no caller waits on it.
+
+    ::
+
+        taskkill raises, child still polls None  ok:   Popen.kill() runs
+        no fallback                              flag: Popen.__exit__ waits forever
+    """
+    _install_windows_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill,
+        "process_tree_subprocess_run",
+        _TreeKillRecorder(OSError("taskkill is not on PATH")),
+    )
+    surviving_process = _FakeProcess([None, None])
+
+    terminate_process_tree(surviving_process)  # type: ignore[arg-type]
+
+    assert surviving_process.kill_calls == 1
+
+
+def test_terminate_swallows_a_kill_on_a_process_that_just_exited(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A child that exits between the re-poll and the kill raises; the helper returns."""
+    _install_windows_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill, "process_tree_subprocess_run", _TreeKillRecorder()
+    )
+    racing_process = _FakeProcess(
+        [None, None], kill_error=ProcessLookupError("no such process")
+    )
+
+    terminate_process_tree(racing_process)  # type: ignore[arg-type]
+
+    assert racing_process.kill_calls == 1
+
+
+def test_new_session_is_requested_off_windows_only(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A POSIX child gets its own session so ``killpg`` never reaches the parent.
+
+    ::
+
+        posix    ok:   start_new_session True, child leads its own group
+        windows  flag: start_new_session unsupported, so False
+    """
+    _install_posix_platform(monkeypatch)
+    assert process_tree_kill.should_start_new_session() is True
+
+    _install_windows_platform(monkeypatch)
+    assert process_tree_kill.should_start_new_session() is False