engineering-process 1.1.0__tar.gz → 1.1.2__tar.gz

{engineering_process-1.1.0/engineering_process.egg-info → engineering_process-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 1.1.0
+Version: 1.1.2
 Summary: A small agent-neutral engineering lifecycle with managed adoption
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process

{engineering_process-1.1.0 → engineering_process-1.1.2}/engineering_process/__init__.py

@@ -1,3 +1,3 @@
 """Agent-neutral engineering process."""
 
-VERSION = "1.1.0"
+VERSION = "1.1.2"

{engineering_process-1.1.0 → engineering_process-1.1.2}/engineering_process/_supervisor_posix.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from contextlib import suppress
 import ctypes
 import os
 from pathlib import Path
@@ -17,6 +18,8 @@ from .supervision import CleanupOutcome, NATURAL_DRAIN_GRACE_MILLISECONDS
 
 PR_SET_CHILD_SUBREAPER = 36
 RUN_ID_ENVIRONMENT_VARIABLE = "ENGINEERING_PROCESS_RUN_ID"
+PROCESS_TABLE_TIMEOUT_SECONDS = 10
+PROCESS_TABLE_OBSERVATION_INTERVAL_SECONDS = 0.05
 _SUBREAPER_ENABLED = False
 
 
@@ -31,39 +34,44 @@ def _enable_subreaper() -> None:
     _SUBREAPER_ENABLED = True
 
 
-def _process_table() -> dict[int, int]:
+def _ps_process_table() -> tuple[dict[int, int], str | None]:
+    try:
+        result = subprocess.run(
+            ["ps", "-axo", "pid=,ppid="],
+            stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+            timeout=PROCESS_TABLE_TIMEOUT_SECONDS, check=False, text=True,
+        )
+    except subprocess.TimeoutExpired:
+        return {}, f"process table snapshot timed out after {PROCESS_TABLE_TIMEOUT_SECONDS} seconds"
+    except OSError:
+        return {}, "process table snapshot could not start"
+    if result.returncode != 0:
+        return {}, f"process table snapshot exited with status {result.returncode}"
+    try:
+        rows = (line.split() for line in result.stdout.splitlines())
+        table = {int(pid): int(parent) for pid, parent in rows}
+    except (TypeError, ValueError):
+        return {}, "process table snapshot was malformed"
+    if os.getpid() not in table:
+        return {}, "process table snapshot was incomplete"
+    return table, None
+
+
+def _process_table() -> tuple[dict[int, int], str | None]:
     table: dict[int, int] = {}
     if Path("/proc").is_dir():
         for entry in Path("/proc").iterdir():
             if not entry.name.isdecimal():
                 continue
             try:
-                for line in (entry / "status").read_text(
-                    encoding="utf-8", errors="replace"
-                ).splitlines():
+                for line in (entry / "status").read_text(encoding="utf-8", errors="replace").splitlines():
                     if line.startswith("PPid:"):
                         table[int(entry.name)] = int(line.split()[1])
                         break
             except (OSError, ValueError, IndexError):
                 continue
-        return table
-    result = subprocess.run(
-        ["ps", "-axo", "pid=,ppid="],
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.DEVNULL,
-        timeout=2,
-        check=False,
-        text=True,
-    )
-    if result.returncode == 0:
-        for line in result.stdout.splitlines():
-            try:
-                pid, parent = (int(value) for value in line.split())
-            except (ValueError, TypeError):
-                continue
-            table[pid] = parent
-    return table
+        return table, None
+    return _ps_process_table()
 
 
 def _descendants(root: int, table: Mapping[int, int]) -> set[int]:
@@ -100,10 +108,8 @@ def _pid_alive(pid: int) -> bool:
         try:
             state = status.read_text(encoding="utf-8").rsplit(")", 1)[1].split()[0]
             if state == "Z":
-                try:
+                with suppress(OSError):
                     os.waitpid(pid, os.WNOHANG)
-                except OSError:
-                    pass
                 return False
         except (OSError, IndexError):
             pass
@@ -111,11 +117,9 @@ def _pid_alive(pid: int) -> bool:
 
 
 def _process_group_exists(process_group: int) -> bool:
-    try:
+    with suppress(OSError):
         while os.waitpid(-process_group, os.WNOHANG)[0]:
             pass
-    except OSError:
-        pass
     try:
         os.killpg(process_group, 0)
     except ProcessLookupError:
@@ -127,10 +131,8 @@ def _process_group_exists(process_group: int) -> bool:
 
 def _signal_processes(processes: set[int], signal_number: int) -> None:
     for pid in processes:
-        try:
+        with suppress(OSError):
             os.kill(pid, signal_number)
-        except OSError:
-            pass
 
 
 def _wait_for_process_group(process_group: int, timeout: float) -> bool:
@@ -145,20 +147,12 @@ def _wait_for_process_group(process_group: int, timeout: float) -> bool:
 def _terminate_group(process_group: int, grace_seconds: float) -> CleanupOutcome:
     if not _process_group_exists(process_group):
         return CleanupOutcome(bounded=True)
-    try:
+    with suppress(OSError):
         os.killpg(process_group, signal.SIGTERM)
-    except ProcessLookupError:
-        return CleanupOutcome(bounded=True, descendants_found=True)
-    except OSError:
-        pass
     if _wait_for_process_group(process_group, grace_seconds):
         return CleanupOutcome(bounded=True, descendants_found=True)
-    try:
+    with suppress(OSError):
         os.killpg(process_group, signal.SIGKILL)
-    except ProcessLookupError:
-        return CleanupOutcome(bounded=True, descendants_found=True)
-    except OSError:
-        pass
     bounded = _wait_for_process_group(process_group, grace_seconds)
     return CleanupOutcome(
         bounded=bounded,
@@ -167,10 +161,24 @@ def _terminate_group(process_group: int, grace_seconds: float) -> CleanupOutcome
     )
 
 
+def _terminate_root(process: subprocess.Popen[bytes], grace_seconds: float) -> bool:
+    for signal_number in (signal.SIGTERM, signal.SIGKILL):
+        with suppress(OSError):
+            os.killpg(process.pid, signal_number)
+        try:
+            process.wait(timeout=grace_seconds)
+            return True
+        except subprocess.TimeoutExpired:
+            pass
+    return False
+
+
 class PosixProcessSupervisor:
     def __init__(self) -> None:
         self._known_descendants: dict[int, set[int]] = {}
         self._run_ids: dict[int, str] = {}
+        self._last_observation: dict[int, float] = {}
+        self._observation_errors: dict[int, str] = {}
 
     def resolve_application(
         self,
@@ -234,37 +242,43 @@ class PosixProcessSupervisor:
         )
         self._known_descendants[process.pid] = set()
         self._run_ids[process.pid] = run_id
-        self.observe(process)
+        self._observation_errors.pop(process.pid, None)
+        self._observe(process, force=True)
         return process
 
-    def observe(self, process: subprocess.Popen[bytes]) -> None:
-        table = _process_table()
+    def _observe(self, process: subprocess.Popen[bytes], *, force: bool) -> None:
+        now = time.monotonic()
+        if not force and now - self._last_observation.get(process.pid, 0) < PROCESS_TABLE_OBSERVATION_INTERVAL_SECONDS:
+            return
+        table, error = _process_table()
+        self._last_observation[process.pid] = time.monotonic()
         known = self._known_descendants.setdefault(process.pid, set())
-        known.update(_descendants(process.pid, table))
-        run_id = self._run_ids.get(process.pid)
-        if sys.platform.startswith("linux") and run_id is not None:
-            adopted = {
-                pid
-                for pid, parent in table.items()
-                if (
-                    parent == os.getpid()
+        if error is not None:
+            self._observation_errors.setdefault(process.pid, error)
+        else:
+            known.update(_descendants(process.pid, table))
+            run_id = self._run_ids.get(process.pid)
+            if sys.platform.startswith("linux") and run_id is not None:
+                known.update(
+                    pid
+                    for pid, parent in table.items()
+                    if parent == os.getpid()
                     and pid != process.pid
                     and _has_run_id(pid, run_id)
                 )
-            }
-            known.update(adopted)
 
-    def _terminate_detached(
-        self,
-        process: subprocess.Popen[bytes],
-        grace_seconds: float,
-    ) -> CleanupOutcome:
-        self.observe(process)
+    def observe(self, process: subprocess.Popen[bytes]) -> None:
+        self._observe(process, force=False)
+
+    def _terminate_detached(self, process: subprocess.Popen[bytes], grace_seconds: float) -> CleanupOutcome:
+        self._observe(process, force=True)
         candidates = self._known_descendants.pop(process.pid, set())
         self._run_ids.pop(process.pid, None)
+        self._last_observation.pop(process.pid, None)
+        observation_error = self._observation_errors.pop(process.pid, None)
         live = {pid for pid in candidates if _pid_alive(pid)}
         if not live:
-            return CleanupOutcome(bounded=True)
+            return CleanupOutcome(bounded=observation_error is None, error=observation_error)
         _signal_processes(live, signal.SIGTERM)
         deadline = time.monotonic() + grace_seconds
         while time.monotonic() < deadline and any(_pid_alive(pid) for pid in live):
@@ -281,11 +295,16 @@ class PosixProcessSupervisor:
                 os.waitpid(pid, os.WNOHANG)
             except (ChildProcessError, OSError):
                 pass
-        bounded = not any(_pid_alive(pid) for pid in live)
+        descendants_bounded = not any(_pid_alive(pid) for pid in live)
+        error = observation_error or (
+            None
+            if descendants_bounded
+            else "detached descendants survived bounded termination"
+        )
         return CleanupOutcome(
-            bounded=bounded,
+            bounded=descendants_bounded and error is None,
             descendants_found=True,
-            error=None if bounded else "detached descendants survived bounded termination",
+            error=error,
         )
 
     def terminate(
@@ -294,34 +313,15 @@ class PosixProcessSupervisor:
         *,
         grace_seconds: float,
     ) -> CleanupOutcome:
-        self.observe(process)
-        try:
-            os.killpg(process.pid, signal.SIGTERM)
-        except ProcessLookupError:
-            pass
-        except OSError:
-            pass
-        try:
-            process.wait(timeout=grace_seconds)
-        except subprocess.TimeoutExpired:
-            try:
-                os.killpg(process.pid, signal.SIGKILL)
-            except ProcessLookupError:
-                pass
-            except OSError:
-                pass
-            try:
-                process.wait(timeout=grace_seconds)
-            except subprocess.TimeoutExpired:
-                detached = self._terminate_detached(process, grace_seconds)
-                return CleanupOutcome(
-                    bounded=False,
-                    descendants_found=detached.descendants_found,
-                    error=(
-                        "command root process survived bounded process-group termination"
-                        + (f"; {detached.error}" if detached.error else "")
-                    ),
-                )
+        self._observe(process, force=True)
+        if not _terminate_root(process, grace_seconds):
+            detached = self._terminate_detached(process, grace_seconds)
+            error = "command root process survived bounded process-group termination"
+            return CleanupOutcome(
+                bounded=False,
+                descendants_found=detached.descendants_found,
+                error=error + (f"; {detached.error}" if detached.error else ""),
+            )
         descendants = _terminate_group(process.pid, grace_seconds)
         detached = self._terminate_detached(process, grace_seconds)
         return CleanupOutcome(
@@ -342,7 +342,7 @@ class PosixProcessSupervisor:
         # alive, even after the original process has exited. Give descendants that
         # were synchronously asked to stop one short bounded interval to disappear
         # naturally before classifying them as abandoned background work.
-        self.observe(process)
+        self._observe(process, force=True)
         if not _process_group_exists(process.pid):
             return self._terminate_detached(process, grace_seconds)
         natural_drain_seconds = min(

{engineering_process-1.1.0 → engineering_process-1.1.2}/engineering_process/commands.py

@@ -155,6 +155,7 @@ def _run_check(project_root: Path, check: dict[str, Any]) -> dict[str, Any]:
             )
             descendants = descendants or cleanup.descendants_found
             cleanup_error = cleanup_error or cleanup.error
+            cleanup_error = cleanup_error or (None if cleanup.bounded else "unbounded cleanup")
     exit_code = process.returncode if process.returncode is not None else -1
 
     for reader in readers:
@@ -173,7 +174,6 @@ def _run_check(project_root: Path, check: dict[str, Any]) -> dict[str, Any]:
         exit_code == 0
         and not timed_out
         and not output_exceeded
-        and not descendants
         and not stream_failed
     )
     return {

{engineering_process-1.1.0 → engineering_process-1.1.2/engineering_process.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 1.1.0
+Version: 1.1.2
 Summary: A small agent-neutral engineering lifecycle with managed adoption
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process

{engineering_process-1.1.0 → engineering_process-1.1.2}/engineering_process.egg-info/SOURCES.txt

@@ -62,4 +62,5 @@ tests/test_lifecycle.py
 tests/test_publication_compat.py
 tests/test_release.py
 tests/test_repository.py
-tests/test_skills.py
+tests/test_skills.py
+tests/test_supervisor_posix.py

{engineering_process-1.1.0 → engineering_process-1.1.2}/process_assets/skills/verify-change/SKILL.md

@@ -11,9 +11,10 @@ profile through the lifecycle:
     processctl change verify --change-id ID --profile PROFILE
 
 Commands are exact argument arrays with timeouts. Do not substitute a different tool
-or narrower check when a required command fails. A command failure, timeout,
-surviving descendant, or tracked repository mutation is a failure and leaves the
-change in implementing.
+or narrower check when a required command fails. A command failure, timeout, output
+or stream failure, failed descendant cleanup, or tracked repository mutation is a
+failure and leaves the change in implementing. Successfully cleaned post-exit
+descendants remain recorded without replacing the foreground command result.
 
 The contract must already include conditional profiles required by affected enforced
 capabilities. Run those profiles exactly; do not run every planned production gate for

{engineering_process-1.1.0 → engineering_process-1.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "engineering-process"
-version = "1.1.0"
+version = "1.1.2"
 description = "A small agent-neutral engineering lifecycle with managed adoption"
 readme = "README.md"
 license = "MIT"

{engineering_process-1.1.0 → engineering_process-1.1.2}/tests/test_automation.py

@@ -7,6 +7,9 @@ import unittest
 
 
 ROOT = Path(__file__).resolve().parent.parent
+ACTIVE_PROCESS_PIN = re.compile(
+    r"^engineering-process==([^\s\\]+)\s*$", re.MULTILINE
+)
 
 
 class AutomationTests(unittest.TestCase):
@@ -141,11 +144,27 @@ class AutomationTests(unittest.TestCase):
         self.assertEqual("production", readiness["target"])
         self.assertEqual("production", readiness["stage"])
         self.assertEqual([{"id": "library-cli", "version": 1}], readiness["packs"])
-        self.assertIn("engineering-process==1.0.1", (ROOT / "requirements" / "process.in").read_text(encoding="utf-8"))
+        adopted = json.loads(
+            (ROOT / ".process" / "process.lock").read_text(encoding="utf-8")
+        )
+        requirements = (ROOT / "requirements" / "process.in").read_text(
+            encoding="utf-8"
+        )
+        self.assertEqual(
+            [adopted["process"]["version"]], ACTIVE_PROCESS_PIN.findall(requirements)
+        )
         workflow = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
         self.assertIn("processctl adoption check", workflow)
         self.assertIn("processctl doctor --project-root .", workflow)
 
+    def test_self_adoption_pin_parser_ignores_comments_and_prefix_collisions(self) -> None:
+        self.assertEqual(
+            ["1.0.10"], ACTIVE_PROCESS_PIN.findall("engineering-process==1.0.10\n")
+        )
+        self.assertEqual(
+            [], ACTIVE_PROCESS_PIN.findall("# engineering-process==1.0.1\n")
+        )
+
     def test_external_actions_are_immutably_pinned(self) -> None:
         for workflow in (ROOT / ".github" / "workflows").glob("*.yml"):
             for reference in re.findall(r"uses:\s*([^\s#]+)", workflow.read_text(encoding="utf-8")):

{engineering_process-1.1.0 → engineering_process-1.1.2}/tests/test_commands.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import ctypes
+import io
 import os
 from pathlib import Path
 import subprocess
@@ -7,8 +9,38 @@ import sys
 import tempfile
 import time
 import unittest
+from unittest.mock import Mock, patch
 
 from engineering_process.commands import run_check, run_profile
+from engineering_process.supervision import CleanupOutcome
+
+
+def windows_process_is_running(process_id: int) -> bool:
+    from ctypes import wintypes
+
+    synchronize = 0x00100000
+    wait_failed = 0xFFFFFFFF
+    wait_timeout = 0x00000102
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+    kernel32.WaitForSingleObject.restype = wintypes.DWORD
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+    handle = kernel32.OpenProcess(synchronize, False, process_id)
+    if not handle:
+        error = ctypes.get_last_error()
+        if error == 87:  # ERROR_INVALID_PARAMETER: the PID no longer exists.
+            return False
+        raise ctypes.WinError(error)
+    try:
+        result = kernel32.WaitForSingleObject(handle, 0)
+        if result == wait_failed:
+            raise ctypes.WinError(ctypes.get_last_error())
+        return result == wait_timeout
+    finally:
+        kernel32.CloseHandle(handle)
 
 
 class CommandTests(unittest.TestCase):
@@ -64,6 +96,27 @@ class CommandTests(unittest.TestCase):
         self.assertEqual("failed", report["status"])
         self.assertTrue(report["timedOut"])
 
+    def test_unbounded_cleanup_fails_without_an_adapter_error(self) -> None:
+        process = Mock(stdout=io.BytesIO(), stderr=io.BytesIO(), returncode=0)
+        process.poll.return_value = 0
+        supervisor = Mock()
+        supervisor.spawn.return_value = process
+        supervisor.finalize.return_value = CleanupOutcome(bounded=False)
+        with tempfile.TemporaryDirectory() as directory, patch(
+            "engineering_process.commands.process_supervisor",
+            return_value=supervisor,
+        ):
+            report = run_check(
+                Path(directory),
+                {
+                    "id": "unbounded-cleanup",
+                    "run": [sys.executable, "-c", "raise SystemExit(0)"],
+                    "timeoutSeconds": 10,
+                },
+            )
+        self.assertEqual("failed", report["status"])
+        self.assertTrue(report["streamFailed"])
+
     @unittest.skipUnless(
         sys.platform.startswith("linux"), "Linux subreaper ownership assertion"
     )
@@ -93,7 +146,7 @@ class CommandTests(unittest.TestCase):
             unrelated.wait(timeout=3)
 
     @unittest.skipIf(os.name == "nt", "POSIX process-group assertion")
-    def test_surviving_descendant_is_terminated_and_fails(self) -> None:
+    def test_surviving_descendant_is_terminated_after_success(self) -> None:
         script = (
             "import subprocess, sys; "
             "subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(30)']); "
@@ -108,7 +161,7 @@ class CommandTests(unittest.TestCase):
                     "timeoutSeconds": 10,
                 },
             )
-        self.assertEqual("failed", report["status"])
+        self.assertEqual("passed", report["status"])
         self.assertTrue(report["descendantsTerminated"])
 
     @unittest.skipUnless(
@@ -142,7 +195,7 @@ class CommandTests(unittest.TestCase):
     @unittest.skipUnless(
         sys.platform.startswith("linux"), "Linux subreaper containment assertion"
     )
-    def test_detached_descendant_is_terminated_and_fails(self) -> None:
+    def test_detached_descendant_is_terminated_after_success(self) -> None:
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
             pid_path = root / "child.pid"
@@ -166,12 +219,12 @@ class CommandTests(unittest.TestCase):
             deadline = time.monotonic() + 3
             while Path(f"/proc/{pid}").exists() and time.monotonic() < deadline:
                 time.sleep(0.02)
-        self.assertEqual("failed", report["status"])
+        self.assertEqual("passed", report["status"])
         self.assertTrue(report["descendantsTerminated"])
         self.assertFalse(Path(f"/proc/{pid}").exists())
 
     @unittest.skipUnless(os.name == "nt", "Windows Job Object containment assertion")
-    def test_windows_job_object_terminates_descendants(self) -> None:
+    def test_windows_job_object_terminates_descendants_after_success(self) -> None:
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
             pid_path = root / "child.pid"
@@ -189,8 +242,10 @@ class CommandTests(unittest.TestCase):
                     "timeoutSeconds": 10,
                 },
             )
-        self.assertEqual("failed", report["status"])
+            pid = int(pid_path.read_text(encoding="utf-8"))
+        self.assertEqual("passed", report["status"])
         self.assertTrue(report["descendantsTerminated"])
+        self.assertFalse(windows_process_is_running(pid))
 
 
 if __name__ == "__main__":

engineering_process-1.1.2/tests/test_supervisor_posix.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+from types import SimpleNamespace
+import unittest
+from unittest.mock import patch
+
+from engineering_process import _supervisor_posix as posix
+from engineering_process.commands import run_check
+
+
+class PosixSupervisorTests(unittest.TestCase):
+    def test_ps_snapshot_failures_are_sanitized_and_bounded(self) -> None:
+        cases = (
+            (
+                subprocess.TimeoutExpired(["ps"], posix.PROCESS_TABLE_TIMEOUT_SECONDS),
+                "process table snapshot timed out after 10 seconds",
+            ),
+            (OSError("sensitive host detail"), "process table snapshot could not start"),
+        )
+        for failure, expected in cases:
+            with self.subTest(expected=expected), patch.object(
+                posix.subprocess, "run", side_effect=failure
+            ) as run:
+                table, error = posix._ps_process_table()
+            self.assertEqual({}, table)
+            self.assertEqual(expected, error)
+            self.assertEqual(
+                posix.PROCESS_TABLE_TIMEOUT_SECONDS,
+                run.call_args.kwargs["timeout"],
+            )
+
+        result = SimpleNamespace(returncode=7, stdout="")
+        with patch.object(posix.subprocess, "run", return_value=result):
+            table, error = posix._ps_process_table()
+        self.assertEqual({}, table)
+        self.assertEqual("process table snapshot exited with status 7", error)
+
+        result = SimpleNamespace(returncode=0, stdout="not-a-process-table\n")
+        with patch.object(posix.subprocess, "run", return_value=result):
+            table, error = posix._ps_process_table()
+        self.assertEqual({}, table)
+        self.assertEqual("process table snapshot was malformed", error)
+
+        result = SimpleNamespace(
+            returncode=0,
+            stdout=f"{os.getpid()} 1\nmalformed-row\n",
+        )
+        with patch.object(posix.subprocess, "run", return_value=result):
+            table, error = posix._ps_process_table()
+        self.assertEqual({}, table)
+        self.assertEqual("process table snapshot was malformed", error)
+
+    def test_routine_observation_is_throttled_but_boundaries_are_forced(self) -> None:
+        supervisor = posix.PosixProcessSupervisor()
+        process = SimpleNamespace(pid=12345)
+        with (
+            patch.object(posix, "_process_table", return_value=({}, None)) as snapshot,
+            patch.object(
+                posix.time,
+                "monotonic",
+                side_effect=(1.0, 1.001, 1.01, 1.02, 1.021),
+            ),
+        ):
+            supervisor.observe(process)
+            supervisor.observe(process)
+            supervisor._observe(process, force=True)
+        self.assertEqual(2, snapshot.call_count)
+
+    def test_snapshot_failure_makes_detached_cleanup_fail_closed(self) -> None:
+        supervisor = posix.PosixProcessSupervisor()
+        process = SimpleNamespace(pid=12345)
+        supervisor._known_descendants[process.pid] = set()
+        supervisor._run_ids[process.pid] = "bounded-test-run"
+        with patch.object(
+            posix,
+            "_process_table",
+            return_value=({}, "process table snapshot timed out after 10 seconds"),
+        ):
+            outcome = supervisor._terminate_detached(process, grace_seconds=0)
+        self.assertFalse(outcome.bounded)
+        self.assertFalse(outcome.descendants_found)
+        self.assertEqual(
+            "process table snapshot timed out after 10 seconds", outcome.error
+        )
+
+    @unittest.skipIf(os.name == "nt", "POSIX cleanup result assertion")
+    def test_snapshot_failure_returns_a_failed_check_instead_of_escaping(self) -> None:
+        with tempfile.TemporaryDirectory() as directory, patch.object(
+            posix,
+            "_process_table",
+            return_value=({}, "process table snapshot timed out after 10 seconds"),
+        ):
+            report = run_check(
+                Path(directory),
+                {
+                    "id": "snapshot-failure",
+                    "run": [sys.executable, "-c", "raise SystemExit(0)"],
+                    "timeoutSeconds": 10,
+                },
+            )
+        self.assertEqual("failed", report["status"])
+        self.assertTrue(report["streamFailed"])
+        self.assertFalse(report["timedOut"])
+
+
+if __name__ == "__main__":
+    unittest.main()