The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
ci(process): no new detached spawn outside spawn_owned without a reason
kshitijk4poord1cb5d5cbd85
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.ymlindex 603bb105e6e..dae0a98fffb 100644--- a/.github/workflows/lint.yml+++ b/.github/workflows/lint.yml@@ -247,6 +247,12 @@ jobs:- name: Forbid literal /tmp paths outside the baselinerun: python scripts/check_no_tmp_literals.py+ # A child in its own session/group (start_new_session, os.setsid/setpgid) does not die with+ # a SIGKILLed Hermes. Long-lived children start through process_identity.spawn_owned; a line+ # that must stay detached says why with `detached-spawn: ok — <why>`.+ - name: Forbid detached spawns outside the owned-child helper+ run: python scripts/check_detached_spawns.py+# config.yaml is hand-edited and commented; a PyYAML dump of it destroys every comment# (#92554, regressed repeatedly). All writers go through the hermes_cli.config writer seam.- name: Forbid config.yaml writers that bypass the comment-preserving writerdiff --git a/cron/scheduler.py b/cron/scheduler.pyindex 35b8c338215..70046c33eeb 100644--- a/cron/scheduler.py+++ b/cron/scheduler.py@@ -3735,6 +3735,7 @@ def _launch_external_cron_worker(job: dict) -> bool:stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=stderr_fd,+ # detached-spawn: ok — restart-safe cron worker, must survive a gateway restart (#101940)start_new_session=True,creationflags=windows_hide_flags(),)diff --git a/cron/scheduler_script.py b/cron/scheduler_script.pyindex 6ab2dce41aa..c0f529bca0c 100644--- a/cron/scheduler_script.py+++ b/cron/scheduler_script.py@@ -459,6 +459,7 @@ def _run_job_script(# or stderr raises UnicodeDecodeError in communicate() and fails the whole run,# discarding the output (#105582; the Windows branch decodes lossily per #45099).popen_kwargs: dict[str, Any] = {+ # detached-spawn: ok — awaited; cancel and timeout tree-kill the group"start_new_session": True,"errors": "replace",}diff --git a/gateway/run_shutdown.py b/gateway/run_shutdown.pyindex 6f187b62d14..db1786f7333 100644--- a/gateway/run_shutdown.py+++ b/gateway/run_shutdown.py@@ -1434,7 +1434,7 @@ class GatewayShutdownMixin(GatewaySessionEndMixin):# Break away from the parent CLI's job object or be reaped when the CLI exits; a job without# BREAKAWAY_OK rejects CREATE_BREAKAWAY_FROM_JOB (OSError) — retry once without the bit.try:- subprocess.Popen(watcher_argv, **popen_kwargs, **windows_detach_popen_kwargs())+ subprocess.Popen(watcher_argv, **popen_kwargs, **windows_detach_popen_kwargs()) # detached-spawn: ok — restart watcher, must outlive the gateway it restartsexcept OSError:try:subprocess.Popen(@@ -1478,7 +1478,7 @@ class GatewayShutdownMixin(GatewaySessionEndMixin):argv = [setsid_bin, "bash", "-lc", shell_cmd] if setsid_bin else ["bash", "-lc", shell_cmd]subprocess.Popen( # noqa: ASYNC220 -- fire-and-forget spawn; Popen returns immediately and callers need the Popen objectargv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,- env=GatewayShutdownMixin._restart_watcher_env(), start_new_session=True,+ env=GatewayShutdownMixin._restart_watcher_env(), start_new_session=True, # detached-spawn: ok — restart watcher, must outlive the gateway it restarts)def _wedged_agent_count(self) -> int:diff --git a/gateway/shutdown_forensics.py b/gateway/shutdown_forensics.pyindex b62644b6273..93c7d1777dd 100644--- a/gateway/shutdown_forensics.py+++ b/gateway/shutdown_forensics.py@@ -160,6 +160,7 @@ def spawn_async_diagnostic(log_path: Path, signal_name: str, *,try: # start_new_session: outlive systemd killing our cgroup (KillMode=control-group) to flushreturn subprocess.Popen([*bound, "bash", "-c", script], stdout=fd,+ # detached-spawn: ok — forensics dump runs while the gateway dies; bounded by timeout(1)stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL, start_new_session=True,close_fds=True).pidexcept OSError:diff --git a/gateway/slash_commands.py b/gateway/slash_commands.pyindex 00877b04f95..be09c2af8fb 100644--- a/gateway/slash_commands.py+++ b/gateway/slash_commands.py@@ -139,6 +139,7 @@ def _spawn_detached_update(hermes_cmd, output_path, exit_code_path) -> None:subprocess.Popen([sys.executable, "-c", _WINDOWS_UPDATE_HELPER, str(output_path), str(exit_code_path),sys.executable, "-m", "hermes_cli.main", "update", "--gateway"],+ # detached-spawn: ok — /update runs `hermes update`, which must outlive the gateway it restartsstdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, **windows_detach_popen_kwargs())returnhermes_cmd_str = " ".join(shlex.quote(part) for part in hermes_cmd)@@ -154,6 +155,7 @@ def _spawn_detached_update(hermes_cmd, output_path, exit_code_path) -> None:# calls os.setsid() in the child.setsid_bin = shutil.which("setsid")argv = [setsid_bin, "bash", "-c", update_cmd] if setsid_bin else ["bash", "-c", update_cmd]+ # detached-spawn: ok — /update runs `hermes update`, which must outlive the gateway it restartssubprocess.Popen(argv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)diff --git a/hermes_cli/_subprocess_compat.py b/hermes_cli/_subprocess_compat.pyindex 6da70a551f5..f92821494f2 100644--- a/hermes_cli/_subprocess_compat.py+++ b/hermes_cli/_subprocess_compat.py@@ -271,6 +271,7 @@ def windows_detach_popen_kwargs() -> dict:"""if IS_WINDOWS:return {"creationflags": windows_detach_flags()}+ # detached-spawn: ok — the detach helper itself; every call site is checked on its ownreturn {"start_new_session": True}diff --git a/hermes_cli/bundled_app.py b/hermes_cli/bundled_app.pyindex 9e83b1515b2..63f34c9b973 100644--- a/hermes_cli/bundled_app.py+++ b/hermes_cli/bundled_app.py@@ -174,6 +174,7 @@ def launch_detached(stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL,close_fds=True,+ # detached-spawn: ok — the desktop app launch, meant to outlive the CLI that opens it**windows_detach_popen_kwargs(),)return child.piddiff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.pyindex dc3378a6681..9d8c4b2262a 100644--- a/hermes_cli/config_defaults.py+++ b/hermes_cli/config_defaults.py@@ -1261,7 +1261,7 @@ DEFAULT_CONFIG = {# openWakeWord/pyopen-wakeword only: consecutive over-threshold frames to fire (higher = fewer# false triggers, more latency; 1 = single-frame)"confirmation_frames": 3,- "start_new_session": True, # fresh session on wake vs. continue the current one+ "start_new_session": True, # fresh session on wake vs. continue the current one (detached-spawn: ok — a config key)# sherpa only: listen for every wake-enabled profile's phrase and route to it"profile_routing": True,"openwakeword": {diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.pyindex 9a358d95d6b..dea06907184 100644--- a/hermes_cli/gateway.py+++ b/hermes_cli/gateway.py@@ -1177,13 +1177,13 @@ def _spawn_gateway_restart_watcher(old_pid: int, run_argv: list[str], *, host: bpopen_env = {"env": watcher_env} if watcher_env is not None else {}# Same detach for the watcher itself, so closing the terminal doesn't kill it.try:- subprocess.Popen(watcher_argv, **devnull, **popen_env, **windows_detach_popen_kwargs())+ subprocess.Popen(watcher_argv, **devnull, **popen_env, **windows_detach_popen_kwargs()) # detached-spawn: ok — restart watcher, must outlive the process that asked for the restartexcept OSError:# Parent job object rejected CREATE_BREAKAWAY_FROM_JOB; retry without it (Windows only —# ``start_new_session=True`` cannot raise OSError on POSIX).fallback_kwargs: dict = ({"creationflags": windows_detach_flags_without_breakaway()} if sys.platform == "win32"- else {"start_new_session": True}+ else {"start_new_session": True} # detached-spawn: ok — restart watcher, must outlive the process that asked for the restart)try:subprocess.Popen(watcher_argv, **devnull, **popen_env, **fallback_kwargs)diff --git a/hermes_cli/gateway_launchd.py b/hermes_cli/gateway_launchd.pyindex c6289e0e1b1..8a744bb7bca 100644--- a/hermes_cli/gateway_launchd.py+++ b/hermes_cli/gateway_launchd.py@@ -309,6 +309,7 @@ def _spawn_detached_gateway() -> bool:_timestamped_stderr_gateway_command(log_dir / "gateway.error.log"),stdin=subprocess.DEVNULL, stdout=out, stderr=subprocess.DEVNULL,env=child_env,+ # detached-spawn: ok — foreground-less gateway launch, a service meant to outlive the CLI**windows_detach_popen_kwargs(),)except OSError:diff --git a/hermes_cli/kanban_db_dispatch.py b/hermes_cli/kanban_db_dispatch.pyindex 3a37b9ebbf1..72a779c7c7a 100644--- a/hermes_cli/kanban_db_dispatch.py+++ b/hermes_cli/kanban_db_dispatch.py@@ -2882,7 +2882,7 @@ def _default_spawn(task: Task, workspace: str, *, board: Optional[str] = None) -stdout=log_f,stderr=subprocess.STDOUT,env=env,- start_new_session=True,+ start_new_session=True, # detached-spawn: ok — restart-safe kanban worker, must survive the dispatchercreationflags=subprocess.CREATE_NO_WINDOW if _kb._IS_WINDOWS else 0,)except FileNotFoundError:diff --git a/hermes_cli/main_dashboard.py b/hermes_cli/main_dashboard.pyindex 4567fb0fb95..71ab4891f4e 100644--- a/hermes_cli/main_dashboard.py+++ b/hermes_cli/main_dashboard.py@@ -443,6 +443,7 @@ def _respawn_dashboard_processes(commands: list[list[str]]) -> list[list[str]]:with open(log_path, "ab") as log_f:proc = subprocess.Popen(command, stdin=subprocess.DEVNULL, stdout=log_f, stderr=subprocess.STDOUT,+ # detached-spawn: ok — dashboard service launch, meant to outlive the CLI that starts itstart_new_session=True, close_fds=True)spawned.append((original, command, proc))except (OSError, ValueError) as exc:diff --git a/hermes_cli/update_cmd_posix_pause.py b/hermes_cli/update_cmd_posix_pause.pyindex db28b22781b..75d690139d4 100644--- a/hermes_cli/update_cmd_posix_pause.py+++ b/hermes_cli/update_cmd_posix_pause.py@@ -543,6 +543,7 @@ def _relaunch_bare(entry: dict) -> int:env.pop(leaked, None)with open(logs / "gateway-update-resume.log", "ab") as log:proc = subprocess.Popen(list(entry["argv"]), env=env, stdin=subprocess.DEVNULL, stdout=log,+ # detached-spawn: ok — resumes the paused gateway after an update; it must outlive the updaterstderr=subprocess.STDOUT, start_new_session=True, close_fds=True)deadline = time.monotonic() + _READY_TIMEOUT_Swhile time.monotonic() < deadline:diff --git a/hermes_cli/update_completion.py b/hermes_cli/update_completion.pyindex 73401c9b8fd..6afd43fbf4a 100644--- a/hermes_cli/update_completion.py+++ b/hermes_cli/update_completion.py@@ -91,6 +91,7 @@ def run_completion(request: dict) -> dict:# starts runs outside the job), so the lock is never free while it runs.proc = subprocess.Popen(command, cwd=root, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,+ # detached-spawn: ok — awaited; holds the checkout lock fd so an update finishes atomically even if this parent dies**({"start_new_session": True, "pass_fds": checkout_lock_fds(root)} if os.name == "posix" else{"creationflags": subprocess.CREATE_NO_WINDOW | CREATE_SUSPENDED}))decoder = codecs.getincrementaldecoder("utf-8")("replace")diff --git a/hermes_cli/update_custody.py b/hermes_cli/update_custody.pyindex 0f9422da881..1845ece8378 100644--- a/hermes_cli/update_custody.py+++ b/hermes_cli/update_custody.py@@ -362,6 +362,7 @@ def _owner_watch(pid: int):read_end, write_end = os.pipe() # non-inheritable: no other child keeps the owner's end opentry:watcher = subprocess.Popen([sys.executable, "-I", "-S", "-c", _OWNER_WATCH, str(pid)], stdin=read_end,+ # detached-spawn: ok — the owner-death watchdog itself: it must outlive the owner to kill the fetchstdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)except OSError as exc:os.close(write_end)diff --git a/hermes_cli/update_stage.py b/hermes_cli/update_stage.pyindex 23d20289176..1c1e2cd9987 100644--- a/hermes_cli/update_stage.py+++ b/hermes_cli/update_stage.py@@ -131,6 +131,7 @@ def ensure_panel(update_root: Path) -> None:subprocess.Popen(["/usr/bin/osascript", "-l", "JavaScript", str(panel), str(status_file())],stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,+ # detached-spawn: ok — update progress panel, self-exits on the terminal statestderr=subprocess.DEVNULL, start_new_session=True,)os.environ[UI_SPAWNED_ENV] = "1" # inherited: never spawn twice per chaindiff --git a/hermes_cli/web_server_gateway.py b/hermes_cli/web_server_gateway.pyindex 5bba58c233a..da0747e2f29 100644--- a/hermes_cli/web_server_gateway.py+++ b/hermes_cli/web_server_gateway.py@@ -543,6 +543,7 @@ def _spawn_hermes_action()proc = _popen(creationflags=windows_detach_flags_without_breakaway())else:+ # detached-spawn: ok — dashboard gateway start/restart actions, which must outlive the dashboardproc = _popen(start_new_session=True)except OSError as exc:# Without this the action log would hold only the started-header for a spawn that neverdiff --git a/scripts/check b/scripts/checkindex 8b0cba124ce..7ecf2a72260 100755--- a/scripts/check+++ b/scripts/check@@ -105,6 +105,7 @@ _GUARDS = {"footguns": ["scripts/check-windows-footguns.py", "--all"],"shebangs": ["scripts/check_bash_shebangs.py"],"no-tmp": ["scripts/check_no_tmp_literals.py"],+ "detached-spawns": ["scripts/check_detached_spawns.py"],"config-writers": ["scripts/check_config_yaml_writers.py"],"config-readers": ["scripts/check_config_yaml_readers.py"],"os-marker-fakes": ["scripts/ci/check_os_marker_fakes.py"],diff --git a/scripts/check_detached_spawns.py b/scripts/check_detached_spawns.pynew file mode 100644index 00000000000..0664efd2df8--- /dev/null+++ b/scripts/check_detached_spawns.py@@ -0,0 +1,184 @@+#!/usr/bin/env python3+"""Fail when production code starts a detached child outside the owned-child helper.++A child started in its own session/process group (``start_new_session=True``, ``os.setsid``,+``os.setpgid``/``os.setpgrp`` in a ``preexec_fn``) no longer dies with the Hermes process that+started it. When that process is SIGKILLed, OOM-killed or crashes, the child reparents to init+(or a ``systemd --user`` subreaper) and runs forever. Every long-lived child that should die with+its owner goes through ``hermes_cli.process_identity.spawn_owned`` (or hands its group to+``own_process_groups`` where something else spawned it), which registers the group with the+per-process owner-death supervisor.++Flags, in Python files of the production trees (tests, evals, scripts and nix checks excluded):++ start_new_session=True / start_new_session=<anything but False>, or a ``"start_new_session"``+ dict key with a non-False value+ any reference to os.setsid / os.setpgid / os.setpgrp (call or ``preexec_fn=os.setsid``)+ a call to ``windows_detach_popen_kwargs()`` (``start_new_session=True`` on POSIX)++Opt out of one line with ``detached-spawn: ok — <why>`` on that line or the line directly above+it. Legitimate reasons are the ones that stay valid after the owner dies: the child must OUTLIVE+its owner on purpose (an updater relaunching the gateway, a restart watcher, a detached service+launch), or the child is short-lived and awaited with a hard timeout that kills its group (the+group exists only so that kill reaches grandchildren).++``_BASELINE`` maps a file to a tolerated count of unmarked hits. It is empty: every detached+spawn site is on ``spawn_owned`` or marked with its reason. Keep it that way; an entry is a+temporary burn-down, and an overstated one is an advisory (``--strict-baseline`` fails on it).++Run: python scripts/check_detached_spawns.py [--all] [--print-baseline] [--strict-baseline] [paths...]+Exit 1 on any violation, 0 when clean.+"""+from __future__ import annotations++import argparse+import ast+import subprocess+import sys+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent+MARKER = "detached-spawn: ok"+# The helper itself: the one place a detached spawn is the point.+HELPER_FILES = {"hermes_cli/process_identity.py"}+SCAN_TREES = ("agent", "cron", "gateway", "hermes_cli", "plugins", "tools", "tui_gateway", "acp_adapter", "pm")+SCAN_ROOT_FILES = ("cli.py", "run_agent.py", "hermes_state.py", "utils.py", "hermes_constants.py")+SKIP_PARTS = {"tests", "__pycache__", "evals", "node_modules"}+_DETACH_OS_ATTRS = {"setsid", "setpgid", "setpgrp"}+# Helpers that return detaching Popen kwargs (``start_new_session=True`` on POSIX).+_DETACH_HELPERS = {"windows_detach_popen_kwargs"}+# Cheap text prefilter: only files mentioning one of these are parsed.+_NEEDLES = ("start_new_session", "setsid", "setpgid", "setpgrp", *_DETACH_HELPERS)+++def _is_false(node: ast.AST) -> bool:+ return isinstance(node, ast.Constant) and node.value in (False, None, 0)+++def _is_os_detach(node: ast.AST) -> bool:+ return (isinstance(node, ast.Attribute) and node.attr in _DETACH_OS_ATTRS+ and isinstance(node.value, ast.Name) and node.value.id == "os")+++def _is_detach_helper_call(node: ast.AST) -> bool:+ return isinstance(node, ast.Call) and (getattr(node.func, "id", None) in _DETACH_HELPERS+ or getattr(node.func, "attr", None) in _DETACH_HELPERS)+++def detach_lines(text: str) -> list[int]:+ """Line numbers of detached-spawn shapes in ``text`` (a Python module)."""+ if not any(needle in text for needle in _NEEDLES):+ return []+ try:+ tree = ast.parse(text)+ except (SyntaxError, ValueError):+ return []+ lines: set[int] = set()+ for node in ast.walk(tree):+ if isinstance(node, ast.keyword) and node.arg == "start_new_session" and not _is_false(node.value):+ lines.add(node.value.lineno)+ elif isinstance(node, ast.Dict):+ for key, value in zip(node.keys, node.values):+ if isinstance(key, ast.Constant) and key.value == "start_new_session" and not _is_false(value):+ lines.add(key.lineno)+ elif _is_os_detach(node) or _is_detach_helper_call(node):+ lines.add(node.lineno)+ return sorted(lines)+++def _marked(src_lines: list[str], lineno: int) -> bool:+ here = src_lines[lineno - 1] if lineno - 1 < len(src_lines) else ""+ above = src_lines[lineno - 2] if lineno >= 2 else ""+ return MARKER in here or MARKER in above+++def _tracked_files(root: Path) -> list[Path]:+ try:+ out = subprocess.run(["git", "-C", str(root), "ls-files", "-z", "--", *SCAN_TREES, *SCAN_ROOT_FILES],+ capture_output=True, text=True, check=True, stdin=subprocess.DEVNULL, timeout=60).stdout+ except (OSError, subprocess.SubprocessError):+ return []+ return [root / rel for rel in out.split("\0") if rel.endswith(".py")]+++def _in_scope(rel: str) -> bool:+ parts = Path(rel).parts+ return not (SKIP_PARTS & set(parts)) and not Path(rel).name.startswith("test_") and rel not in HELPER_FILES+++def scan(paths=None, root: Path | None = None) -> dict[str, list[tuple[int, str]]]:+ """Repo-relative path -> [(lineno, line)] of unmarked detached spawns."""+ root = (root or ROOT).resolve()+ hits: dict[str, list[tuple[int, str]]] = {}+ for path in (list(paths) if paths else _tracked_files(root)):+ path = Path(path).resolve()+ try:+ rel = path.relative_to(root).as_posix()+ except ValueError:+ rel = str(path)+ if path.suffix != ".py" or not _in_scope(rel):+ continue+ try:+ text = path.read_text(encoding="utf-8-sig", errors="ignore")+ except OSError:+ continue+ src = text.splitlines()+ found = [(n, src[n - 1]) for n in detach_lines(text) if not _marked(src, n)]+ if found:+ hits[rel] = found+ return hits+++# Files that spawned unmarked detached children when this check landed. Burn-down list:+# migrate to spawn_owned / own_process_groups, or mark the line with a reason, then drop the entry.+_BASELINE: dict[str, int] = {+}+++def _format_baseline(hits: dict[str, list]) -> str:+ body = "".join(f' "{rel}": {len(found)},\n' for rel, found in sorted(hits.items()))+ return "_BASELINE: dict[str, int] = {\n" + body + "}"+++def main(argv: list[str] | None = None) -> int:+ ap = argparse.ArgumentParser(description=(__doc__ or "").splitlines()[0])+ ap.add_argument("paths", nargs="*", help="files to check (default: the production trees)")+ ap.add_argument("--all", action="store_true", help="ignore _BASELINE; report every hit")+ ap.add_argument("--print-baseline", action="store_true", help="print a _BASELINE for the current tree")+ ap.add_argument("--strict-baseline", action="store_true", help="also fail when _BASELINE overstates a file")+ args = ap.parse_args(argv)++ hits = scan(args.paths or None)+ if args.print_baseline:+ print(_format_baseline(hits))+ return 0+ baseline = {} if (args.all or args.paths) else _BASELINE+ problems: list[str] = []+ advisories: list[str] = []+ for rel in sorted(hits):+ allowed = baseline.get(rel)+ if allowed is not None and len(hits[rel]) <= allowed:+ if len(hits[rel]) < allowed:+ advisories.append(f"{rel}: {len(hits[rel])} detached spawn(s) left, _BASELINE says {allowed}")+ continue+ problems.extend(f"{rel}:{n}: {line.strip()[:160]}" for n, line in hits[rel])+ advisories.extend(f"{rel}: listed in _BASELINE but clean (or gone)" for rel in sorted(baseline) if rel not in hits)+ if advisories:+ print("advisory — _BASELINE in scripts/check_detached_spawns.py is stale; regenerate it with "+ "--print-baseline (fewer hits than listed is progress, not a failure):")+ print("\n".join(" " + a for a in advisories))+ if args.strict_baseline:+ problems.extend(advisories)+ if not problems:+ print("no detached spawns outside the owned-child helper and the baseline")+ return 0+ print("\n".join(problems))+ print(f"\n{len(problems)} detached spawn(s) flagged. A child in its own session/group outlives a "+ "SIGKILLed Hermes. Start long-lived children with hermes_cli.process_identity.spawn_owned "+ "(or hand the group to own_process_groups), or mark a child that must outlive its owner / "+ f"is awaited with a group-killing timeout with `{MARKER} — <why>` (same line or the line above).")+ return 1+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tests/scripts/test_check_detached_spawns.py b/tests/scripts/test_check_detached_spawns.pynew file mode 100644index 00000000000..275b3bab421--- /dev/null+++ b/tests/scripts/test_check_detached_spawns.py@@ -0,0 +1,92 @@+"""scripts/check_detached_spawns.py: detached spawns outside spawn_owned are flagged unless marked."""++import importlib.util+import textwrap+from pathlib import Path++import pytest++SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "check_detached_spawns.py"+++def _load():+ spec = importlib.util.spec_from_file_location("check_detached_spawns", SCRIPT)+ mod = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(mod)+ return mod+++ "src",+ [+ "subprocess.Popen(argv, start_new_session=True)",+ "subprocess.Popen(argv, start_new_session=flag)",+ 'kwargs = {"start_new_session": True}',+ "subprocess.Popen(argv, preexec_fn=os.setsid)",+ "subprocess.Popen(argv, preexec_fn=lambda: os.setpgid(0, 0))",+ "os.setpgrp()",+ "subprocess.Popen(argv, **windows_detach_popen_kwargs())",+ "subprocess.Popen(argv, **_subprocess_compat.windows_detach_popen_kwargs())",+ ],+)+def test_detached_shapes_are_flagged(src):+ assert _load().detach_lines(src) == [1]+++ "src",+ [+ "subprocess.Popen(argv)",+ "subprocess.Popen(argv, start_new_session=False)",+ 'kwargs = {"start_new_session": False}',+ "spawn_owned(argv, purpose='x')",+ "# start_new_session=True in a comment",+ 'doc = "os.setsid in a string"',+ ],+)+def test_non_detached_shapes_are_not_flagged(src):+ assert _load().detach_lines(src) == []+++def test_marker_on_the_line_or_above_opts_out_and_nothing_else_does(tmp_path):+ mod = _load()+ pkg = tmp_path / "tools"+ pkg.mkdir()+ f = pkg / "x.py"+ f.write_text(textwrap.dedent("""\+ import os, subprocess+ subprocess.Popen(a, start_new_session=True) # detached-spawn: ok — awaited, group-killed+ # detached-spawn: ok — outlives its owner on purpose+ subprocess.Popen(b, start_new_session=True)+ # an unrelated comment+ subprocess.Popen(c, start_new_session=True)+ """), encoding="utf-8")+ hits = mod.scan([f], root=tmp_path)+ assert [n for n, _ in hits["tools/x.py"]] == [6]+++def test_tests_and_the_helper_are_out_of_scope(tmp_path):+ mod = _load()+ for rel in ("tests/tools/test_x.py", "tools/test_y.py", "hermes_cli/process_identity.py"):+ path = tmp_path / rel+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text("subprocess.Popen(a, start_new_session=True)\n", encoding="utf-8")+ assert mod.scan(list(tmp_path.rglob("*.py")), root=tmp_path) == {}+++def test_a_new_unmarked_spawn_fails_main_and_a_marked_one_passes(tmp_path, monkeypatch, capsys):+ mod = _load()+ f = tmp_path / "tools" / "new.py"+ f.parent.mkdir()+ f.write_text("subprocess.Popen(a, start_new_session=True)\n", encoding="utf-8")+ monkeypatch.setattr(mod, "ROOT", tmp_path)+ assert mod.main([str(f)]) == 1+ assert "tools/new.py:1" in capsys.readouterr().out+ f.write_text("subprocess.Popen(a, start_new_session=True) # detached-spawn: ok — test\n", encoding="utf-8")+ assert mod.main([str(f)]) == 0+++def test_the_repository_has_no_unmarked_detached_spawn():+ mod = _load()+ assert mod.scan() == {}, "a detached spawn outside spawn_owned lacks a `detached-spawn: ok — <why>` marker"+ assert mod._BASELINE == {}diff --git a/tests/scripts/test_code_health_cli.py b/tests/scripts/test_code_health_cli.pyindex 15617b16b72..39b0cea541b 100644--- a/tests/scripts/test_code_health_cli.py+++ b/tests/scripts/test_code_health_cli.py@@ -24,8 +24,8 @@ from scripts.code_health.config import ENFORCEMENTREPO = Path(__file__).resolve().parents[2]_GUARD_SCRIPTS = ("scripts/check-windows-footguns.py", "scripts/check_bash_shebangs.py",- "scripts/check_no_tmp_literals.py", "scripts/check_config_yaml_writers.py",- "scripts/check_config_yaml_readers.py",+ "scripts/check_no_tmp_literals.py", "scripts/check_detached_spawns.py",+ "scripts/check_config_yaml_writers.py", "scripts/check_config_yaml_readers.py","scripts/ci/check_os_marker_fakes.py", "scripts/check-case-collisions.py","scripts/ci/check_lazy_deps_imports.py", "scripts/ci/check_profile_archive_boundary.py","scripts/ci/check_agents_md_size.py", "scripts/ci/check_blob_size.py",diff --git a/tools/browser_use_cli.py b/tools/browser_use_cli.pyindex b280e9464ee..d8fae81c179 100644--- a/tools/browser_use_cli.py+++ b/tools/browser_use_cli.py@@ -556,6 +556,7 @@ def _group_popen_kwargs() -> dict:si.dwFlags |= subprocess.STARTF_USESHOWWINDOWreturn {"creationflags": windows_hide_flags() | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0),"startupinfo": si}+ # detached-spawn: ok — awaited CLI; a timeout kills its whole group (_run_cli_killing_process_group)return _quiet(_flags, {}, "Windows hide-flags unavailable") if os.name == "nt" else {"start_new_session": True}diff --git a/tools/file_operations_search.py b/tools/file_operations_search.pyindex aa64bc9633d..9ac19f443d3 100644--- a/tools/file_operations_search.py+++ b/tools/file_operations_search.py@@ -613,6 +613,7 @@ class SearchMixin:proc = subprocess.Popen(args, cwd=cwd, env=_make_run_env(self.env.env), stdin=subprocess.DEVNULL,stdout=subprocess.PIPE, stderr=subprocess.PIPE if merge_stderr else subprocess.DEVNULL,+ # detached-spawn: ok — awaited rg under a deadline; the group is killed on timeout or interruptstart_new_session=True)except OSError as exc:return ExecuteResult(stdout=f"rg: {exc}", exit_code=2)diff --git a/tools/wake_word.py b/tools/wake_word.pyindex 4db2cf658fd..f8e7478da8a 100644--- a/tools/wake_word.py+++ b/tools/wake_word.py@@ -77,6 +77,7 @@ class WakeWordInUse(RuntimeError):_DEFAULTS: dict[str, Any] = {"enabled": False, "surface": "auto", "input_device": None, "capture": "auto","provider": "auto", "phrase": "hey hermes", "sensitivity": 0.6,+ # detached-spawn: ok — not a spawn: the wake-word config key (fresh chat session on wake)"confirmation_frames": _DEFAULT_CONFIRMATION_FRAMES, "start_new_session": True,}diff --git a/tui_gateway/host_supervisor.py b/tui_gateway/host_supervisor.pyindex a1c619928a1..0900a16a7ca 100644--- a/tui_gateway/host_supervisor.py+++ b/tui_gateway/host_supervisor.py@@ -351,6 +351,7 @@ class HostSupervisor:proc = subprocess.Popen(self.argv, cwd=str(self.cwd), env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", bufsize=1,+ # detached-spawn: ok — compute host exits on its own parent-guard (compute_host._parent_guard_loop) and flushes sessions; a supervisor KILL could cut that flush shortstart_new_session=True)self._proc = procfor target, name in ((self._drain_stdout, "compute-host-stdout"),diff --git a/tui_gateway/methods_voice.py b/tui_gateway/methods_voice.pyindex fec946b5cf6..697c58838f0 100644--- a/tui_gateway/methods_voice.py+++ b/tui_gateway/methods_voice.py@@ -504,6 +504,7 @@ def _wake_detect_handler(transport, sid: str, phrase: str, new_session: bool):try:_emit("wake.detected", sid, {"phrase": matched_phrase or phrase, "profile": matched_profile or None,+ # detached-spawn: ok — not a spawn: a wake.detected event field"start_new_session": new_session})finally:reset_transport(token)