claude-dev-env 8.52.0 → 8.52.1

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

@@ -25,3 +25,15 @@ PROCESS_TREE_KILL_TIMEOUT_SECONDS: int = 10
 Gates the kill command alone. Each caller sets its own bound on the drain that
 follows the kill.
 """
+
+PROCESS_TREE_EXIT_WAIT_SECONDS: float = 2.0
+"""Seconds ``terminate_process_tree`` waits for the signalled POSIX group to exit.
+
+A SIGKILL takes effect when the kernel next schedules each target, so a
+descendant can still run for a moment after ``killpg`` returns. The wait ends
+as soon as no group member is still running; the bound applies only when a
+member survived the signal.
+"""
+
+PROCESS_TREE_EXIT_POLL_SECONDS: float = 0.01
+"""Pause between checks for running members of the signalled process group."""

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

@@ -25,6 +25,7 @@ import os
 import signal
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 _config_directory = str(Path(__file__).resolve().parent / "config")
@@ -32,6 +33,8 @@ 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_EXIT_POLL_SECONDS,
+    PROCESS_TREE_EXIT_WAIT_SECONDS,
     PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     WINDOWS_TASKKILL_COMMAND,
     WINDOWS_TASKKILL_FORCE_FLAG,
@@ -126,19 +129,103 @@ def terminate_process_tree(process: subprocess.Popen[str]) -> None:
         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
+        grandchild still running   ok:  returns once the POSIX group has exited
 
     Falls back to ``Popen.kill()`` when the direct child survives the tree kill,
-    so the caller never waits on a live process.
+    so the caller never waits on a live process. On POSIX it then waits, bounded
+    by ``PROCESS_TREE_EXIT_WAIT_SECONDS``, until no group member is running, so
+    a descendant cannot touch files after this call returns.
 
     Args:
         process: The process whose tree is ended.
     """
     if process.poll() is not None:
         return
+    process_group_identifier = _posix_process_group(process.pid)
     kill_process_tree_by_identifier(process.pid)
-    if process.poll() is not None:
-        return
+    if process.poll() is None:
+        try:
+            process.kill()
+        except ProcessLookupError:
+            pass
+    if process_group_identifier is not None:
+        _wait_for_process_group_exit(process, process_group_identifier)
+
+
+def _posix_process_group(process_identifier: int) -> int | None:
+    if sys.platform == "win32":
+        return None
     try:
-        process.kill()
-    except ProcessLookupError:
-        return
+        return os.getpgid(process_identifier)
+    except OSError:
+        return None
+
+
+def _wait_for_process_group_exit(
+    process: subprocess.Popen[str], process_group_identifier: int
+) -> None:
+    """Block until no member of the signalled group is still running, bounded.
+
+    ``killpg`` returns once the signal is queued, and each target dies only when
+    the kernel next schedules it. A grandchild preempted inside a system call
+    finishes that call first, so it can still truncate or write a file after
+    the caller has moved on. Waiting here keeps that work inside the call.
+    """
+    deadline = time.monotonic() + PROCESS_TREE_EXIT_WAIT_SECONDS
+    while running_process_group_members(process, process_group_identifier):
+        if time.monotonic() >= deadline:
+            return
+        time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+
+
+def running_process_group_members(
+    process: subprocess.Popen[str], process_group_identifier: int
+) -> list[int]:
+    """List the process ids in a POSIX group that have not exited yet.
+
+    Reads ``/proc`` where it exists, which tells a running member from a zombie
+    waiting on its reaper. Elsewhere it reaps the direct child and asks the
+    kernel whether the group still has any member.
+
+    Args:
+        process: The direct child that leads the group.
+        process_group_identifier: The group the direct child leads.
+
+    Returns:
+        Process ids still running, or an empty list once the group has exited.
+    """
+    if sys.platform == "win32":
+        return []
+    proc_directory = Path("/proc")
+    if proc_directory.is_dir():
+        return _running_members_from_proc(proc_directory, process_group_identifier)
+    try:
+        process.wait(timeout=PROCESS_TREE_EXIT_POLL_SECONDS)
+    except subprocess.TimeoutExpired:
+        return [process.pid]
+    try:
+        os.killpg(process_group_identifier, 0)
+    except OSError:
+        return []
+    return [process_group_identifier]
+
+
+def _running_members_from_proc(
+    proc_directory: Path, process_group_identifier: int
+) -> list[int]:
+    all_running: list[int] = []
+    for each_entry in proc_directory.iterdir():
+        if not each_entry.name.isdigit():
+            continue
+        try:
+            stat_text = (each_entry / "stat").read_text(
+                encoding="ascii", errors="replace"
+            )
+        except OSError:
+            continue
+        state, _parent_identifier, group_identifier, *_later_fields = stat_text.rsplit(
+            ")", 1
+        )[1].split()
+        if int(group_identifier) == process_group_identifier and state != "Z":
+            all_running.append(int(each_entry.name))
+    return all_running

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

@@ -7,9 +7,12 @@ the taskkill argv it builds, the failures it swallows, and the
 
 from __future__ import annotations
 
+import os
 import subprocess
 import sys
+import time
 from pathlib import Path
+from typing import cast
 
 import pytest
 
@@ -23,6 +26,8 @@ from process_tree_kill import (  # noqa: E402
     terminate_process_tree,
 )
 from process_tree_scripts_constants.process_tree_kill_constants import (  # noqa: E402
+    PROCESS_TREE_EXIT_POLL_SECONDS,
+    PROCESS_TREE_EXIT_WAIT_SECONDS,
     PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     WINDOWS_TASKKILL_COMMAND,
     WINDOWS_TASKKILL_FORCE_FLAG,
@@ -276,3 +281,147 @@ def test_new_session_is_requested_off_windows_only(
 
     _install_windows_platform(monkeypatch)
     assert process_tree_kill.should_start_new_session() is False
+
+
+def _install_posix_group_wait(
+    monkeypatch: pytest.MonkeyPatch, all_member_snapshots: list[list[int]]
+) -> list[float]:
+    """Script what the group wait sees after the kill, and record each pause.
+
+    The last snapshot repeats once the list runs dry, so a never-empty script
+    models a group that outlives the deadline.
+    """
+    all_sleeps: list[float] = []
+    remaining_snapshots = list(all_member_snapshots)
+
+    def scripted_members(process: object, process_group_identifier: int) -> list[int]:
+        del process, process_group_identifier
+        if len(remaining_snapshots) > 1:
+            return remaining_snapshots.pop(0)
+        return remaining_snapshots[0]
+
+    _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: None,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        process_tree_kill, "running_process_group_members", scripted_members
+    )
+    monkeypatch.setattr(process_tree_kill.time, "sleep", all_sleeps.append)
+    return all_sleeps
+
+
+def test_terminate_waits_until_no_group_member_is_running(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The POSIX kill returns only once the signalled group has emptied.
+
+    ::
+
+        members [7], [7], []  ok:   two pauses, then return
+        no wait               flag: a grandchild still inside a system call
+                                    writes after the caller has moved on
+    """
+    all_sleeps = _install_posix_group_wait(monkeypatch, [[7], [7], []])
+
+    terminate_process_tree(_as_popen(_FakeProcess([None, 0])))
+
+    assert all_sleeps == [PROCESS_TREE_EXIT_POLL_SECONDS] * 2
+
+
+def test_terminate_stops_waiting_at_the_exit_deadline(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A group member that survives the signal does not hold the caller forever."""
+    all_sleeps = _install_posix_group_wait(monkeypatch, [[7]])
+    clock = iter(
+        [0.0, 0.0, PROCESS_TREE_EXIT_WAIT_SECONDS / 2, PROCESS_TREE_EXIT_WAIT_SECONDS]
+    )
+    monkeypatch.setattr(process_tree_kill.time, "monotonic", lambda: next(clock))
+
+    terminate_process_tree(_as_popen(_FakeProcess([None, 0])))
+
+    assert all_sleeps == [PROCESS_TREE_EXIT_POLL_SECONDS] * 2
+
+
+def _as_popen(fake_process: _FakeProcess) -> subprocess.Popen[str]:
+    return cast("subprocess.Popen[str]", fake_process)
+
+
+def _group_led_by(process: subprocess.Popen[str]) -> int:
+    """Name the group a session-leading child owns; Windows has none, so its pid."""
+    if process_tree_kill.should_start_new_session():
+        return os.getpgid(process.pid)
+    return process.pid
+
+
+def test_running_members_leave_out_a_zombie() -> None:
+    """A member that died but awaits its reaper is not running.
+
+    ::
+
+        child sleeping               ok:   listed on POSIX, [] on Windows
+        child killed, not yet reaped ok:   dropped, so the wait ends
+    """
+    sleeper = subprocess.Popen(
+        [sys.executable, "-c", "import time; time.sleep(60)"],
+        start_new_session=process_tree_kill.should_start_new_session(),
+    )
+    group_identifier = _group_led_by(sleeper)
+    all_expected_running = (
+        [sleeper.pid] if process_tree_kill.should_start_new_session() else []
+    )
+    try:
+        assert (
+            process_tree_kill.running_process_group_members(sleeper, group_identifier)
+            == all_expected_running
+        )
+        sleeper.kill()
+        deadline = time.monotonic() + PROCESS_TREE_EXIT_WAIT_SECONDS
+        while process_tree_kill.running_process_group_members(
+            sleeper, group_identifier
+        ):
+            assert time.monotonic() < deadline, "the killed sleeper still counts"
+            time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+    finally:
+        sleeper.wait()
+
+
+def test_terminate_returns_with_the_grandchild_already_gone(tmp_path: Path) -> None:
+    """Right after the kill returns, no process in the child's group still runs."""
+    heartbeat_file = tmp_path / "heartbeat.txt"
+    grandchild_source = (
+        "import pathlib, sys\n"
+        "heartbeat = pathlib.Path(sys.argv[1])\n"
+        "while True:\n"
+        "    heartbeat.write_text('beat', encoding='utf-8')\n"
+    )
+    child_source = (
+        "import subprocess, sys, time\n"
+        "subprocess.Popen([sys.executable, '-c', sys.argv[1], sys.argv[2]])\n"
+        "time.sleep(60)\n"
+    )
+    child = subprocess.Popen(
+        [sys.executable, "-c", child_source, grandchild_source, str(heartbeat_file)],
+        start_new_session=process_tree_kill.should_start_new_session(),
+    )
+    group_identifier = _group_led_by(child)
+    while not heartbeat_file.exists():
+        time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+
+    terminate_process_tree(child)
+    still_running = process_tree_kill.running_process_group_members(
+        child, group_identifier
+    )
+    child.wait()
+
+    assert still_running == []

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.52.0",
+    "version": "8.52.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/account_broker_support.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import dataclasses
 import errno
+import importlib
 import json
 import os
 import shutil
@@ -63,6 +64,16 @@ from dev_env_scripts_constants.codex_account_constants import (
     WEEKLY_WINDOW_MINUTES,
 )
 from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
+from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+
+_shared_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
+    __file__,
+    all_environment=os.environ,
+)
+if str(_shared_process_tree_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_process_tree_scripts_directory))
+
+_process_tree_kill = importlib.import_module("process_tree_kill")
 
 
 def _read_list(path: Path) -> object:
@@ -492,21 +503,26 @@ def _run_captured_subprocess(all_argv: Sequence[str], **options: object) -> subp
     errors = str(options.get("errors") or "replace")
     stdin_bytes = options.get("input")
     with tempfile.TemporaryFile() as stdout_file, tempfile.TemporaryFile() as stderr_file:
-        completion = subprocess.run(
+        with subprocess.Popen(
             _resolve_command(all_argv),
-            input=stdin_bytes,
+            stdin=subprocess.PIPE if stdin_bytes is not None else None,
             stdout=stdout_file,
             stderr=stderr_file,
             env=options.get("env"),
             cwd=options.get("cwd"),
-            timeout=options.get("timeout"),
-            check=False,
-        )
+            start_new_session=_process_tree_kill.should_start_new_session(),
+        ) as process:
+            try:
+                process.communicate(input=stdin_bytes, timeout=options.get("timeout"))
+            except (subprocess.TimeoutExpired, KeyboardInterrupt):
+                _process_tree_kill.terminate_process_tree(process)
+                process.wait()
+                raise
         stdout_file.seek(0)
         stderr_file.seek(0)
         stdout = stdout_file.read().decode(encoding, errors).replace("\r\n", "\n").replace("\r", "\n")
         stderr = stderr_file.read().decode(encoding, errors).replace("\r\n", "\n").replace("\r", "\n")
-    return subprocess.CompletedProcess(list(all_argv), completion.returncode, stdout, stderr)
+    return subprocess.CompletedProcess(list(all_argv), process.returncode, stdout, stderr)
 
 
 subprocess_runner: SubprocessRunner = _run_captured_subprocess

package/scripts/test_account_broker_support.py

@@ -5,6 +5,8 @@ import json
 import os
 import shutil
 import subprocess
+import sys
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 from types import SimpleNamespace
@@ -222,16 +224,85 @@ def test_should_raise_windows_lock_error_other_than_contention(tmp_path: Path) -
     assert all_calls == [lock_descriptor]
 
 
-def test_should_launch_the_path_resolved_command_file(monkeypatch: pytest.MonkeyPatch) -> None:
-    resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
-    monkeypatch.setattr(shutil, "which", lambda name: resolved_command if name == "claude" else None)
+GRANDCHILD_HEARTBEAT_SCRIPT = (
+    "import pathlib, sys, time\n"
+    "heartbeat = pathlib.Path(sys.argv[1])\n"
+    "for each_beat in range(300):\n"
+    "    heartbeat.write_text(str(each_beat), encoding='utf-8')\n"
+    "    time.sleep(0.1)\n"
+)
+
+CHILD_SCRIPT = (
+    "import subprocess, sys, time\n"
+    "subprocess.Popen([sys.executable, '-c', sys.argv[1], sys.argv[2]])\n"
+    "time.sleep(60)\n"
+)
+
+
+def test_should_end_grandchildren_when_the_job_times_out(tmp_path: Path) -> None:
+    heartbeat_file = tmp_path / "heartbeat.txt"
+
+    with pytest.raises(subprocess.TimeoutExpired):
+        support._run_captured_subprocess(
+            [sys.executable, "-c", CHILD_SCRIPT, GRANDCHILD_HEARTBEAT_SCRIPT, str(heartbeat_file)],
+            timeout=5,
+        )
+
+    beat_after_timeout = heartbeat_file.read_text(encoding="utf-8")
+    time.sleep(0.5)
+    assert heartbeat_file.read_text(encoding="utf-8") == beat_after_timeout
+
+
+def test_should_end_grandchildren_when_the_broker_is_interrupted(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    heartbeat_file = tmp_path / "heartbeat.txt"
+    original_communicate = subprocess.Popen.communicate
+
+    def interrupted_communicate(process: subprocess.Popen[bytes], *args: object, **kwargs: object) -> object:
+        try:
+            return original_communicate(process, *args, timeout=5)
+        except subprocess.TimeoutExpired:
+            raise KeyboardInterrupt from None
+
+    monkeypatch.setattr(subprocess.Popen, "communicate", interrupted_communicate)
+
+    with pytest.raises(KeyboardInterrupt):
+        support._run_captured_subprocess(
+            [sys.executable, "-c", CHILD_SCRIPT, GRANDCHILD_HEARTBEAT_SCRIPT, str(heartbeat_file)],
+        )
+
+    beat_after_interrupt = heartbeat_file.read_text(encoding="utf-8")
+    time.sleep(0.5)
+    assert heartbeat_file.read_text(encoding="utf-8") == beat_after_interrupt
+
+
+def _record_launches(monkeypatch: pytest.MonkeyPatch) -> list[list[str]]:
     all_launched_argv: list[list[str]] = []
 
-    def fake_run(all_argv: list[str], **options: object) -> subprocess.CompletedProcess[bytes]:
-        all_launched_argv.append(list(all_argv))
-        return subprocess.CompletedProcess(all_argv, 0)
+    class FakeProcess:
+        returncode = 0
+
+        def __init__(self, all_argv: list[str], **options: object) -> None:
+            all_launched_argv.append(list(all_argv))
+
+        def __enter__(self) -> "FakeProcess":
+            return self
+
+        def __exit__(self, *exception_info: object) -> None:
+            return None
 
-    monkeypatch.setattr(support.subprocess, "run", fake_run)
+        def communicate(self, **options: object) -> tuple[None, None]:
+            return None, None
+
+    monkeypatch.setattr(support.subprocess, "Popen", FakeProcess)
+    return all_launched_argv
+
+
+def test_should_launch_the_path_resolved_command_file(monkeypatch: pytest.MonkeyPatch) -> None:
+    resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
+    monkeypatch.setattr(shutil, "which", lambda name: resolved_command if name == "claude" else None)
+    all_launched_argv = _record_launches(monkeypatch)
 
     completion = support.subprocess_runner(["claude", "-p"], input=b"", encoding="utf-8", errors="replace")
 
@@ -241,7 +312,7 @@ def test_should_launch_the_path_resolved_command_file(monkeypatch: pytest.Monkey
 
 def test_should_refuse_to_launch_a_bare_command_missing_from_path(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(shutil, "which", lambda name: None)
-    monkeypatch.setattr(support.subprocess, "run", lambda *arguments, **options: pytest.fail("a missing command ran"))
+    monkeypatch.setattr(support.subprocess, "Popen", lambda *arguments, **options: pytest.fail("a missing command ran"))
 
     with pytest.raises(FileNotFoundError) as raised:
         support.subprocess_runner(["claude", "-p"])
@@ -256,7 +327,7 @@ def test_should_refuse_a_batch_file_argument_that_cmd_would_parse(
 ) -> None:
     resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    monkeypatch.setattr(support.subprocess, "run", lambda *arguments, **options: pytest.fail("a batch file ran"))
+    monkeypatch.setattr(support.subprocess, "Popen", lambda *arguments, **options: pytest.fail("a batch file ran"))
 
     with pytest.raises(OSError) as raised:
         support.subprocess_runner(["claude", "-p", f"fix{metacharacter}test"])
@@ -269,7 +340,7 @@ def test_should_refuse_a_batch_file_argument_that_cmd_would_parse(
 def test_should_refuse_metacharacters_for_an_uppercase_bat_extension(monkeypatch: pytest.MonkeyPatch) -> None:
     resolved_command = r"C:\tools\CLAUDE.BAT"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    monkeypatch.setattr(support.subprocess, "run", lambda *arguments, **options: pytest.fail("a batch file ran"))
+    monkeypatch.setattr(support.subprocess, "Popen", lambda *arguments, **options: pytest.fail("a batch file ran"))
 
     with pytest.raises(OSError) as raised:
         support.subprocess_runner(["claude", "a & b"])
@@ -280,13 +351,7 @@ def test_should_refuse_metacharacters_for_an_uppercase_bat_extension(monkeypatch
 def test_should_launch_a_batch_file_with_flags_only(monkeypatch: pytest.MonkeyPatch) -> None:
     resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    all_launched_argv: list[list[str]] = []
-
-    def fake_run(all_argv: list[str], **options: object) -> subprocess.CompletedProcess[bytes]:
-        all_launched_argv.append(list(all_argv))
-        return subprocess.CompletedProcess(all_argv, 0)
-
-    monkeypatch.setattr(support.subprocess, "run", fake_run)
+    all_launched_argv = _record_launches(monkeypatch)
 
     support.subprocess_runner(["claude", "-p", "--output-format", "json", "--model", "opus"], input=b"a & b")
 
@@ -296,13 +361,7 @@ def test_should_launch_a_batch_file_with_flags_only(monkeypatch: pytest.MonkeyPa
 def test_should_pass_metacharacters_to_an_executable_unchanged(monkeypatch: pytest.MonkeyPatch) -> None:
     resolved_command = "/usr/local/bin/claude"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    all_launched_argv: list[list[str]] = []
-
-    def fake_run(all_argv: list[str], **options: object) -> subprocess.CompletedProcess[bytes]:
-        all_launched_argv.append(list(all_argv))
-        return subprocess.CompletedProcess(all_argv, 0)
-
-    monkeypatch.setattr(support.subprocess, "run", fake_run)
+    all_launched_argv = _record_launches(monkeypatch)
 
     support.subprocess_runner(["claude", "-p", 'say "a & b" | 100%!'])