# SPDX-License-Identifier: AGPL-3.0-or-later
"""Pins for the phase 6 external supervisor (``scripts/supervise_run.py``).

The supervisor's controller-death contract, pinned without running a
real trial: every child is a fixture script — a ``scripts/smoke_run.py``
head the test owns, placed at the working directory the supervisor
launches the recorded head from — and no committed module is touched.

- ``test_killed_child_is_reaped_marked_timed_out_and_drives_recovery``:
  a killed child (a fixture child that sleeps past a short budget) is
  reaped, marked ``timed_out``, and the supervisor exits nonzero with
  the single JSON document carrying ``timed_out: true``.
- ``test_lost_child_drives_the_recovery_head_once_under_the_same_environment``:
  a lost child (a fixture child that exits nonzero with no JSON
  document) drives the recovery head once — the test observes the
  ``--resume`` subprocess launched with the same environment — and the
  supervisor's document carries ``recovered: true``.
- ``test_clean_child_drives_no_recovery_and_exits_zero``: a clean child
  (a fixture child that exits 0 with a JSON document) drives no
  recovery subprocess and the supervisor exits 0 with
  ``recovered: false``.
- ``test_child_exiting_zero_without_a_document_is_lost``: a child
  that exits 0 without a JSON document is lost — it drives the
  recovery head once and the supervisor exits 1 (the child
  produced no document, so there is no code to propagate).
- ``test_nonzero_child_with_a_document_still_drives_recovery``: a
  child that prints a JSON document and exits nonzero is still a
  controller death — the recovery head runs once, the document
  carries the recovery's code, and the supervisor exits the
  child's code.
- ``test_the_deadline_kill_reaches_the_tree_at_a_fixed_time_and_the_whole_surface_after_the_exit``:
  the kill reaches the whole tree two ways, in one drive (the brief's
  shapes are a list, not a test count): the in-group grandchild is
  dead a fixed time after the deadline, never merely "dead once the
  supervisor has exited" — a surviving one holds the output pipes
  open and delays that exit past its own sleep, so an after-the-exit
  measurement alone cannot tell a group kill from a lone child kill;
  and the grandchild that left the child's process group in its own
  session (the sandbox shape: out of the group, so the group kill
  alone misses it) is dead by the time the supervisor exits — no
  survivor after the exit. This pin runs the supervisor's own kill
  path, never a sandboxed workload, so no sandbox-availability gate
  applies and no skip is possible.
- ``test_the_deadline_kill_sweeps_a_racing_forker_to_quiescence``: the
  capture-window race (F9) — a fixture child forks a session-escaped
  sleeper every ~5ms across a short deadline, recording every forked PID.
  A single capture-then-signal misses the tail forks born after its
  /proc walk, and the group kill orphans them to init the moment it
  lands; the sweep loops capture-kill-sweep to quiescence, so no forked
  PID is alive after the supervisor exits.
- ``test_the_deadline_kill_reaches_a_session_escaped_forkers_tail_forks``:
  the session-escaped forker (F11) — the forker itself runs outside the
  frozen group (its own session, so the freeze cannot stop it), so it
  re-opens the capture window every pass and its final tail forks are
  adopted out of the tree when the sweep stops. Every forked PID is
  recorded; the container boundary holds every fork the child started,
  adopted or not, so no recorded PID is alive after the exit.
- ``test_the_deadline_kill_reaches_a_predecessor_exited_double_forked_sleeper``:
  the double-fork shape (F12) — a session-escaped middleman spawns a
  session-escaped sleeper, records its PID, and exits before the
  deadline, so the sleeper is already init's child at the first capture
  and lies outside any descendant walk's surface. The pin records the
  sleeper's PID and asserts it is dead after the exit.
- Both boundary pins ride on the supervisor's own boundary measurement
  (``supervise_run._container_boundary``): a supervisor without it (the
  step's REV) gets the pin's own assertion as the red, and an environment
  the measurement refuses (no cgroup v2 in ``mountinfo`` — the R08
  grading sandbox's fresh root mounts no ``/sys``) gets a skip, because
  there the boundary cannot exist and no kill surface reaches the shape
  at all. A skip is the measurement's answer, never an assumption about
  the host.
- ``test_the_deadline_drive_leaves_no_container_leaf``: the boundary's
  cleanup half (F19) — the leaf's removal is claimed by the supervisor
  docstring, but the delivered pins held only the kill's liveness; this
  pin holds the removal by diffing the boundary parent's leaf set around
  one escaped-forker deadline drive, so a ``_container_close``
  regression is the pin's red. It rides the same boundary-availability
  skip as the boundary pins.
- ``test_the_child_head_receives_the_whole_environment_and_runs_once``:
  the ``--json`` head runs exactly once and receives every
  ``ORCHESTRATOR_*`` variable unchanged — the supervisor adds none and
  redacts none, the provider credential included — on the clean face
  and on the controller-death face alike.
- ``test_missing_workdir_fails_closed``: misuse fails closed — a
  missing workdir exits nonzero with no success document.
- ``test_unparsable_budget_fails_closed`` and
  ``test_failing_recovery_fails_closed``: the remaining two misuse
  shapes — an unparsable budget and a ``--resume`` that itself fails —
  exit nonzero with the reason on stderr and no JSON document claimed
  as success.

The killed-child pin is the step's red: at REV no supervisor exists
(``scripts/supervise_run.py`` is absent), so this module's top-level
``import supervise_run`` fails and the module does not collect — red
evidence of absence, not a regression. The merged tree pin is the
fixes step's red: at that step's REV (``9b78d7a``) the supervisor's
expiry kill is one group kill, which cannot reach a grandchild in its
own session, so the pin's post-exit liveness assertion fails there —
and under the lone-child-kill mutant the pin's fixed-time assertion
fails at the in-group grandchild instead, with a surviving one
holding the pipes the exit would have waited on. The racing-fork pin
is the fixes-2 step's red (F9): at that step's REV the expiry kill is
one capture-then-signal, so the tail forks born after the /proc walk
are orphaned to init when the group kill lands and survive the exit —
the pin's post-exit forked-PID liveness assertion fails there. The
review's two probes land in this module: the group-kill observation
inside the merged tree pin's fixed-time member, the child-head
observation as its own pin — neither duplicated, both green at REV.
The two boundary pins are the boundary step's red (F11/F12): at REV
the sweep is capture-kill-sweep with no container boundary, so the
session-escaped forker's final tail forks and the predecessor-exited
sleeper survive the exit adopted out-of-tree — each pin's post-exit
liveness assertion fails there. The container boundary delivered in
that step (the child forked into its own cgroup v2 leaf; membership
fixed at fork and unchanged by reparenting) holds every fork the
child started, so both pins are green at FINAL; what the boundary
retires is the previous step's named reparented-orphan boundary — the
docstring below records which pin covers which shape. Where no cgroup
v2 delegation exists — the R08 grading sandbox's fresh root, which
mounts no ``/sys`` — the boundary cannot exist and both pins skip on
the supervisor's own measurement, because there no kill surface
reaches the out-of-group shapes and a red would be an environment
artifact rather than evidence. The leaf-cleanup pin is the cleanup
step's red (F19): green at FINAL, red under a ``_container_close``
that leaks — with the removal loop disabled, one leaf of the drive
stands under the boundary parent after the measurement window while
both boundary pins stay green over the same mutant (the unheld residue
the absorption closes).
"""

from __future__ import annotations

import contextlib
import glob
import json
import os
import signal
import subprocess
import sys
import time
from pathlib import Path

import pytest

import supervise_run

REPO_ROOT = Path(__file__).resolve().parents[1]
SUPERVISOR = Path(supervise_run.__file__).resolve()

# The container leaf prefix the supervisor's own boundary uses
# (``supervise_run.CONTAINER_PREFIX``): the leaf-cleanup pin lists the
# measured boundary parent for this prefix.
LEAF_PREFIX = "orchestrator-supervisor-"

# A provider credential the test owns: it rides the environment into
# both recorded heads unchanged, and must never touch the supervisor's
# own output.
SECRET = "phase6-supervisor-secret"

# The fixture child: a scripts/smoke_run.py head the test owns. The
# supervisor launches it as the recorded head (``--json``) or as the
# recovery head (``--resume``); the scenario comes from the
# environment, which the supervisor passes through unchanged.
FIXTURE_CHILD = '''\
import json
import os
import subprocess
import sys
import threading
import time

scenario = os.environ.get("PHASE6_FIXTURE", "clean")
marker_dir = os.environ.get("PHASE6_FIXTURE_DIR", "")


def record(name, payload):
    if marker_dir:
        with open(os.path.join(marker_dir, name), "a") as handle:
            handle.write(json.dumps(payload) + "\\n")


if "--resume" in sys.argv:
    # The recovery head: record the invocation — argv and the whole
    # ORCHESTRATOR_* environment — so the test can observe exactly one
    # --resume launched under the same environment.
    record("resume-invocations.jsonl", {
        "argv": sys.argv[1:],
        "env": {
            key: value
            for key, value in os.environ.items()
            if key.startswith("ORCHESTRATOR_")
        },
    })
    if scenario == "resume-fails":
        sys.exit(4)
    sys.exit(0)

# The --json head: record the launch — argv and the whole
# ORCHESTRATOR_* environment — so the test observes exactly one
# child launched under the run's own environment (the supervisor
# adds none and redacts none).
record("child-invocations.jsonl", {
    "argv": sys.argv[1:],
    "env": {
        key: value
        for key, value in os.environ.items()
        if key.startswith("ORCHESTRATOR_")
    },
})

if scenario == "sleep":
    time.sleep(60)
elif scenario in ("lost", "resume-fails"):
    print("fixture child: lost, no document", file=sys.stderr)
    sys.exit(3)
elif scenario == "empty":
    sys.exit(0)
elif scenario == "tree-both":
    # Both tree shapes in one drive. The in-group grandchild holds
    # the output pipes; the session-escaped grandchild — the sandbox
    # shape (its own session, so out of the child's process group
    # and invisible to the group kill alone; its output goes to the
    # void, as the sandbox's workloads write to files) — does not.
    grandchild = subprocess.Popen(
        [sys.executable, "-c", "import time; time.sleep(60)"],
    )
    record("grandchild.pid", {"pid": grandchild.pid})
    escaped = subprocess.Popen(
        [sys.executable, "-c", "import time; time.sleep(60)"],
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        start_new_session=True,
    )
    record("grandchild-escaped.pid", {"pid": escaped.pid})
    time.sleep(60)
elif scenario == "racing-fork":
    # A racing forker (F9): fork a session-escaped sleeper every ~5ms
    # across a short deadline, recording every forked PID. The tail
    # forks are born after any single /proc walk — and the group kill
    # orphans them to init the moment it lands — so a capture-then-signal
    # sweep leaves them alive; the sweep must loop capture-kill-sweep to
    # quiescence for every forked PID to be dead at the exit. The
    # deadline is short on purpose: the fork count is deadline-bounded,
    # so a few dozen sleepers is enough to race the window and stays
    # well inside a sandboxed run's process budget.
    def fork_loop():
        while True:
            try:
                sleeper = subprocess.Popen(
                    [sys.executable, "-c", "import time; time.sleep(60)"],
                    stdout=subprocess.DEVNULL,
                    stderr=subprocess.DEVNULL,
                    start_new_session=True,
                )
                record("forked.pid", {"pid": sleeper.pid})
            except OSError:
                pass
            time.sleep(0.005)
    _forker = threading.Thread(target=fork_loop, daemon=True)
    _forker.start()
    time.sleep(60)
elif scenario == "escaped-forker":
    # A session-escaped forker (F11): the forker itself runs outside the
    # frozen group (its own session, so the freeze cannot stop it) and
    # keeps forking across the sweep's passes — the forker re-opens the
    # capture window every pass, and its final tail forks are born after
    # the last capture and adopted out of the tree when the sweep stops.
    # Every forked PID is recorded; the pin asserts none survives the
    # exit.
    forker = (
        "import json, os, subprocess, sys, time\\n"
        "marker_dir = sys.argv[1]\\n"
        "while True:\\n"
        "    try:\\n"
        "        sleeper = subprocess.Popen(\\n"
        "            [sys.executable, '-c', 'import time; time.sleep(60)'],\\n"
        "            stdout=subprocess.DEVNULL,\\n"
        "            stderr=subprocess.DEVNULL,\\n"
        "            start_new_session=True)\\n"
        "        with open(os.path.join(marker_dir, 'forked.pid'), 'a') as handle:\\n"
        "            handle.write(json.dumps({'pid': sleeper.pid}) + '\\\\n')\\n"
        "    except OSError:\\n"
        "        pass\\n"
        "    time.sleep(0.005)\\n"
    )
    subprocess.Popen(
        [sys.executable, "-c", forker, marker_dir],
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        start_new_session=True,
    )
    time.sleep(60)
elif scenario == "double-fork":
    # A double-forking predecessor-exited shape (F12): a session-escaped
    # middleman spawns a session-escaped sleeper, records its PID, and
    # exits before the deadline — so the sleeper is already init's child
    # at the first capture and no descendant walk reaches it. The pin
    # records the sleeper's PID and asserts it is dead after the exit.
    middleman = (
        "import json, os, subprocess, sys\\n"
        "marker_dir = sys.argv[1]\\n"
        "sleeper = subprocess.Popen(\\n"
        "    [sys.executable, '-c', 'import time; time.sleep(60)'],\\n"
        "    stdout=subprocess.DEVNULL,\\n"
        "    stderr=subprocess.DEVNULL,\\n"
        "    start_new_session=True)\\n"
        "with open(os.path.join(marker_dir, 'sleeper.pid'), 'w') as handle:\\n"
        "    handle.write(json.dumps({'pid': sleeper.pid}) + '\\\\n')\\n"
    )
    subprocess.Popen(
        [sys.executable, "-c", middleman, marker_dir],
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        start_new_session=True,
    )
    time.sleep(60)
elif scenario == "failing-with-document":
    print(json.dumps(
        {"code": 5, "workdir": os.environ.get("ORCHESTRATOR_WORKDIR", "")}
    ))
    sys.exit(5)
else:
    print(json.dumps(
        {"code": 0, "workdir": os.environ.get("ORCHESTRATOR_WORKDIR", "")}
    ))
    sys.exit(0)
'''


def _write_fixture(root: Path) -> None:
    scripts = root / "scripts"
    scripts.mkdir(parents=True, exist_ok=True)
    (scripts / "smoke_run.py").write_text(FIXTURE_CHILD)


def _supervisor_env(root: Path, scenario: str) -> dict:
    """The supervisor's environment: the run's ORCHESTRATOR_* variables
    (the recorded authorisation and the provider credential) plus the
    fixture's own two settings, all passed through to the child and the
    recovery unchanged."""
    env = {
        key: value
        for key, value in os.environ.items()
        if not key.startswith("ORCHESTRATOR_")
    }
    env.update({
        "ORCHESTRATOR_WORKDIR": str(root / "workdir"),
        "ORCHESTRATOR_OWNER": "phase6-supervisor",
        "ORCHESTRATOR_CAP": "500",
        "ORCHESTRATOR_AUTHORIZED_AT": "2026-01-01T00:00:00Z",
        "ORCHESTRATOR_AUTH_METHOD": "phase6-pin",
        "ORCHESTRATOR_PROVIDER_API_KEY": SECRET,
        "PHASE6_FIXTURE": scenario,
        "PHASE6_FIXTURE_DIR": str(root),
    })
    return env


def _run_supervisor(root: Path, scenario: str, budget: str):
    _write_fixture(root)
    return subprocess.run(
        [sys.executable, str(SUPERVISOR), "--budget", budget],
        cwd=str(root),
        env=_supervisor_env(root, scenario),
        capture_output=True,
        text=True,
        timeout=120,
    )


def _single_document(stdout: str) -> dict:
    """The supervisor's stdout is exactly one JSON document."""
    lines = [line for line in stdout.splitlines() if line.strip()]
    assert len(lines) == 1, (
        f"expected exactly one JSON document on stdout, got: {stdout!r}"
    )
    return json.loads(lines[0])


def _boundary_available() -> bool:
    """Whether this environment can deliver the container boundary the
    two boundary pins ride on: the supervisor's own measurement — the
    unified mount and a writable parent ``cgroup.procs``. A supervisor
    without the measurement (the step's REV) cannot deliver the boundary
    either, and the pin then runs and fails on its own assertion: that
    is the step's red. An environment the measurement refuses (no cgroup
    v2 in ``mountinfo``, as inside the R08 grading sandbox's fresh root,
    which mounts no ``/sys`` at all) gets a skip, because there no kill
    surface — sweep or container — reaches the out-of-group shapes, and
    a red there would be an environment artifact rather than evidence."""
    measure = getattr(supervise_run, "_container_boundary", None)
    return measure is None or measure() is not None


def _boundary_leaves() -> set:
    """The container leaves standing under the measured boundary parent
    (empty when no delegation exists). The leaf-cleanup pin diffs this
    set around one drive, so concurrent suites' leaves are never its
    assertion."""
    parent = supervise_run._container_boundary()
    if parent is None:
        return set()
    return set(glob.glob(os.path.join(parent, LEAF_PREFIX + "*")))


def _pid_alive(pid: int) -> bool:
    """A PID survives only while it is a live (non-zombie) process."""
    try:
        os.kill(pid, 0)
    except ProcessLookupError:
        return False
    except PermissionError:
        return True
    try:
        with open(f"/proc/{pid}/stat") as handle:
            state = handle.read().rsplit(")", 1)[1].split()[0]
    except OSError:
        return False
    return state not in ("Z", "X", "x")


def _wait_until_dead(pid: int, timeout: float = 30.0) -> None:
    deadline = time.monotonic() + timeout
    while _pid_alive(pid):
        if time.monotonic() > deadline:
            raise AssertionError(
                f"PID {pid} still survives the supervisor's kill"
            )
        time.sleep(0.1)


def _wait_for_marker(path: Path, timeout: float = 30.0) -> None:
    deadline = time.monotonic() + timeout
    while not path.exists():
        if time.monotonic() > deadline:
            raise AssertionError(f"the fixture never wrote {path.name}")
        time.sleep(0.05)


def _kill_pid(pid: int) -> None:
    """Best-effort SIGKILL for a probe's cleanup path."""
    with contextlib.suppress(ProcessLookupError, PermissionError):
        os.kill(pid, signal.SIGKILL)


def test_killed_child_is_reaped_marked_timed_out_and_drives_recovery(tmp_path):
    """A killed child (a fixture child that sleeps past a short budget)
    is reaped, marked ``timed_out``, and the supervisor exits nonzero
    with the single JSON document carrying ``timed_out: true``."""
    completed = _run_supervisor(tmp_path, "sleep", "2")
    assert completed.returncode != 0, completed.stdout + completed.stderr
    document = _single_document(completed.stdout)
    assert document["timed_out"] is True
    assert document["recovered"] is True
    assert document["workdir"] == str(tmp_path / "workdir")
    assert document["code"] == 0, document  # the recovery's code
    wall = document["child_wall_seconds"]
    assert isinstance(wall, float)
    # Reaped at the 2s budget, not after the fixture's 60s sleep.
    assert 1.0 <= wall < 30.0, wall
    assert "killed at the 2s wall budget" in completed.stderr


def test_lost_child_drives_the_recovery_head_once_under_the_same_environment(tmp_path):
    """A lost child (a fixture child that exits nonzero with no JSON
    document) drives the recovery head once: the test observes the
    ``--resume`` subprocess launched with the same environment and the
    supervisor's document carrying ``recovered: true``."""
    completed = _run_supervisor(tmp_path, "lost", "30")
    assert completed.returncode == 3, completed.stderr  # the child's code
    document = _single_document(completed.stdout)
    assert document["recovered"] is True
    assert document["timed_out"] is False
    assert document["code"] == 0, document  # the recovery's code
    invocations = [
        json.loads(line)
        for line in (tmp_path / "resume-invocations.jsonl").read_text().splitlines()
        if line.strip()
    ]
    assert len(invocations) == 1, invocations  # exactly one --resume
    assert invocations[0]["argv"] == ["--resume"]
    # The same environment: every ORCHESTRATOR_* variable the supervisor
    # was given — the recorded authorisation and the provider credential —
    # reached the recovery unchanged.
    assert invocations[0]["env"] == {
        key: value
        for key, value in _supervisor_env(tmp_path, "lost").items()
        if key.startswith("ORCHESTRATOR_")
    }
    # The secret never touches the supervisor's own output.
    assert SECRET not in completed.stdout
    assert SECRET not in completed.stderr


def test_clean_child_drives_no_recovery_and_exits_zero(tmp_path):
    """A clean child (a fixture child that exits 0 with a JSON document)
    drives no recovery subprocess and the supervisor exits 0 with
    ``recovered: false``."""
    completed = _run_supervisor(tmp_path, "clean", "30")
    assert completed.returncode == 0, completed.stderr
    document = _single_document(completed.stdout)
    assert document["recovered"] is False
    assert document["timed_out"] is False
    assert document["code"] == 0
    assert document["workdir"] == str(tmp_path / "workdir")
    assert isinstance(document["child_wall_seconds"], float)
    assert not (tmp_path / "resume-invocations.jsonl").exists()


def test_child_exiting_zero_without_a_document_is_lost(tmp_path):
    """A child that exits 0 without a JSON document is lost:
    it drives the recovery head once, and the supervisor exits
    1 — the child produced no document, so there is no code to
    propagate."""
    completed = _run_supervisor(tmp_path, "empty", "30")
    assert completed.returncode == 1, completed.stderr
    document = _single_document(completed.stdout)
    assert document["recovered"] is True
    assert document["timed_out"] is False
    assert document["code"] == 0, document  # the recovery's code
    invocations = [
        json.loads(line)
        for line in (tmp_path / "resume-invocations.jsonl").read_text().splitlines()
        if line.strip()
    ]
    assert len(invocations) == 1, invocations  # exactly one --resume


def test_nonzero_child_with_a_document_still_drives_recovery(tmp_path):
    """A child that prints a JSON document and exits nonzero is
    still a controller death: the recovery head runs once, the
    supervisor's document carries the recovery's code, and the
    supervisor exits the child's code."""
    completed = _run_supervisor(tmp_path, "failing-with-document", "30")
    assert completed.returncode == 5, completed.stderr  # the child's code
    document = _single_document(completed.stdout)
    assert document["recovered"] is True
    assert document["timed_out"] is False
    assert document["code"] == 0, document  # the recovery's code
    invocations = [
        json.loads(line)
        for line in (tmp_path / "resume-invocations.jsonl").read_text().splitlines()
        if line.strip()
    ]
    assert len(invocations) == 1, invocations  # exactly one --resume


def test_the_deadline_kill_reaches_the_tree_at_a_fixed_time_and_the_whole_surface_after_the_exit(tmp_path):
    """The kill reaches the whole tree two ways, in one drive (the brief's
    shapes are a list, not a test count): the in-group grandchild is dead
    a fixed time after the deadline, never merely "dead once the
    supervisor has exited" — a surviving one holds the output pipes open
    and delays that exit past its own sleep, so an after-the-exit
    measurement alone cannot tell a group kill from a lone child kill;
    and the grandchild that left the child's process group in its own
    session (the sandbox shape: out of the group, so the group kill
    alone misses it) is dead by the time the supervisor exits — no
    survivor after the exit. This pin runs the supervisor's own kill
    path, never a sandboxed workload, so no sandbox-availability gate
    applies and no skip is possible."""
    _write_fixture(tmp_path)
    started = time.monotonic()
    supervisor = subprocess.Popen(
        [sys.executable, str(SUPERVISOR), "--budget", "2"],
        cwd=str(tmp_path),
        env=_supervisor_env(tmp_path, "tree-both"),
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
    )
    grandchild_pid = escaped_pid = None
    try:
        _wait_for_marker(tmp_path / "grandchild.pid")
        _wait_for_marker(tmp_path / "grandchild-escaped.pid")
        grandchild_pid = json.loads(
            (tmp_path / "grandchild.pid").read_text().strip()
        )["pid"]
        escaped_pid = json.loads(
            (tmp_path / "grandchild-escaped.pid").read_text().strip()
        )["pid"]
        # A fixed observation point: the 2s deadline plus slack that
        # covers the supervisor's startup and the kill sweep, both of
        # which complete in well under a second. Both grandchildren
        # sleep 60s, so they are alive here unless the kill reached
        # them — and the point stays fixed on purpose: a surviving
        # in-group grandchild has already closed the output pipes by
        # the time the exit is observable, so the exit is not a kill
        # witness.
        while time.monotonic() - started < 3.5:
            time.sleep(0.05)
        assert not _pid_alive(grandchild_pid), (
            f"grandchild {grandchild_pid} survives the deadline kill: the "
            "expiry kill does not reach the whole process group"
        )
        # The kill is done; the document and the post-exit surface are
        # observable.
        try:
            stdout, _ = supervisor.communicate(timeout=30)
        except subprocess.TimeoutExpired:
            supervisor.kill()
            stdout, _ = supervisor.communicate(timeout=30)
        document = _single_document(stdout)
        assert document["timed_out"] is True
        # No survivor after the exit: the session-escaped grandchild —
        # out of the child's process group, invisible to the group kill
        # alone — is dead by the time the supervisor exits.
        assert not _pid_alive(escaped_pid), (
            f"grandchild {escaped_pid} still survives the supervisor's "
            "kill: the expiry kill does not reach the whole process tree"
        )
    finally:
        if supervisor.poll() is None:
            supervisor.kill()
        if grandchild_pid is not None:
            _kill_pid(grandchild_pid)
        if escaped_pid is not None:
            _kill_pid(escaped_pid)
        try:
            supervisor.communicate(timeout=30)
        except subprocess.TimeoutExpired:
            supervisor.kill()
            supervisor.communicate(timeout=30)


def test_the_deadline_kill_sweeps_a_racing_forker_to_quiescence(tmp_path):
    """A racing forker — a fixture child that forks a session-escaped
    sleeper every ~5ms across the deadline, recording every forked PID —
    leaves no forked PID alive after the supervisor exits. A single
    capture-then-signal misses the tail forks born after its /proc walk
    (the F9 shape: the group kill orphans them to init the moment it
    lands), so the sweep must loop capture-kill-sweep to quiescence; the
    assertion is the forked-PID liveness after the exit."""
    completed = _run_supervisor(tmp_path, "racing-fork", "0.4")
    assert completed.returncode != 0, completed.stdout + completed.stderr
    document = _single_document(completed.stdout)
    assert document["timed_out"] is True
    forked = [
        json.loads(line)["pid"]
        for line in (tmp_path / "forked.pid").read_text().splitlines()
        if line.strip()
    ]
    assert forked, "the fixture forked no session-escaped sleeper"
    alive = [pid for pid in forked if _pid_alive(pid)]
    try:
        assert not alive, (
            f"{len(alive)} of {len(forked)} forked PIDs survive the "
            f"supervisor's exit: {alive[:8]} — the deadline kill does not "
            "sweep the racing forker to quiescence"
        )
    finally:
        for pid in forked:
            _kill_pid(pid)


@pytest.mark.timeout(120)
def test_the_deadline_kill_reaches_a_session_escaped_forkers_tail_forks(tmp_path):
    """A session-escaped forker — a fixture child whose forker itself
    runs session-escaped (outside the frozen group, the F11 shape) —
    forks a session-escaped sleeper every ~5ms across a short deadline,
    recording every forked PID. The freeze cannot stop a forker that
    left the group, so the forker re-opens the capture window every
    pass and its final tail forks are adopted out of the tree when the
    sweep stops; the container boundary holds every fork the child
    started, adopted or not, so the assertion is the forked-PID
    liveness after the exit."""
    if not _boundary_available():
        pytest.skip(
            "no cgroup v2 delegation here (no unified hierarchy in "
            "mountinfo, or no writable cgroup.procs above this "
            "process's cgroup): the container boundary cannot exist, so "
            "no kill surface reaches the shape — measured, not assumed"
        )
    completed = _run_supervisor(tmp_path, "escaped-forker", "0.4")
    assert completed.returncode != 0, completed.stdout + completed.stderr
    document = _single_document(completed.stdout)
    assert document["timed_out"] is True
    forked = [
        json.loads(line)["pid"]
        for line in (tmp_path / "forked.pid").read_text().splitlines()
        if line.strip()
    ]
    assert forked, "the fixture forked no session-escaped sleeper"
    alive = [pid for pid in forked if _pid_alive(pid)]
    try:
        assert not alive, (
            f"{len(alive)} of {len(forked)} forked PIDs survive the "
            f"supervisor's exit: {alive[:8]} — the deadline kill does not "
            "reach a session-escaped forker's tail forks"
        )
    finally:
        for pid in forked:
            _kill_pid(pid)


@pytest.mark.timeout(120)
def test_the_deadline_kill_reaches_a_predecessor_exited_double_forked_sleeper(tmp_path):
    """A double-forking predecessor-exited shape (F12): a session-escaped
    middleman spawns a session-escaped sleeper, records its PID, and
    exits before the deadline — so the sleeper is already init's child
    at the first capture and lies outside any descendant walk's
    surface. The pin records the sleeper's PID and asserts it is dead
    after the exit: the container boundary holds what the child forked,
    adopted or not."""
    if not _boundary_available():
        pytest.skip(
            "no cgroup v2 delegation here (no unified hierarchy in "
            "mountinfo, or no writable cgroup.procs above this "
            "process's cgroup): the container boundary cannot exist, so "
            "no kill surface reaches the shape — measured, not assumed"
        )
    completed = _run_supervisor(tmp_path, "double-fork", "2")
    assert completed.returncode != 0, completed.stdout + completed.stderr
    document = _single_document(completed.stdout)
    assert document["timed_out"] is True
    _wait_for_marker(tmp_path / "sleeper.pid")
    sleeper_pid = json.loads(
        (tmp_path / "sleeper.pid").read_text().strip()
    )["pid"]
    try:
        assert not _pid_alive(sleeper_pid), (
            f"sleeper {sleeper_pid} survives the supervisor's exit "
            "adopted out-of-tree: the expiry kill does not reach a "
            "predecessor-exited sleeper"
        )
    finally:
        _kill_pid(sleeper_pid)


@pytest.mark.timeout(120)
def test_the_deadline_drive_leaves_no_container_leaf(tmp_path):
    """The boundary's cleanup half (F19): the deadline drive's container
    leaf is gone after the supervisor exits. The supervisor's own
    ``_container_close`` bounded wait (20 retries, 50ms settle)
    completes before the exit, so a leaf that still stands after a fresh
    measurement window is a removal defect rather than asynchronous exit
    noise. The leaf set is diffed before and after the one drive, so
    concurrent suites' leaves are never this assertion's."""
    if not _boundary_available():
        pytest.skip(
            "no cgroup v2 delegation here (no unified hierarchy in "
            "mountinfo, or no writable cgroup.procs above this "
            "process's cgroup): the container boundary cannot exist, so "
            "the leaf cannot either — measured, not assumed"
        )
    before = _boundary_leaves()
    completed = _run_supervisor(tmp_path, "escaped-forker", "0.4")
    assert completed.returncode != 0, completed.stdout + completed.stderr
    document = _single_document(completed.stdout)
    assert document["timed_out"] is True
    deadline = time.monotonic() + 5.0
    remaining: set = set()
    while time.monotonic() < deadline:
        remaining = _boundary_leaves() - before
        if not remaining:
            break
        time.sleep(0.1)
    assert not remaining, (
        f"leaf(s) left standing after the deadline drive: {sorted(remaining)} "
        "— the delivered leaf-removal claim (`scripts/supervise_run.py:106`-`:107`) "
        "is unheld"
    )


def test_the_child_head_receives_the_whole_environment_and_runs_once(tmp_path):
    """The ``--json`` head runs exactly once and receives every
    ``ORCHESTRATOR_*`` variable unchanged — the supervisor adds none and
    redacts none, the provider credential included — on the clean face
    and on the controller-death face alike."""
    for scenario, expected_exit in (("clean", 0), ("lost", 3)):
        root = tmp_path / scenario
        completed = _run_supervisor(root, scenario, "30")
        assert completed.returncode == expected_exit, (
            scenario, completed.returncode, completed.stderr
        )
        launches = [
            json.loads(line)
            for line in (root / "child-invocations.jsonl").read_text().splitlines()
            if line.strip()
        ]
        assert len(launches) == 1, (scenario, launches)  # exactly one child
        assert launches[0]["argv"] == ["--json"], launches[0]["argv"]
        expected = {
            key: value
            for key, value in _supervisor_env(root, scenario).items()
            if key.startswith("ORCHESTRATOR_")
        }
        assert launches[0]["env"] == expected, (
            f"the child's environment is not the supervisor's on the {scenario} "
            "face: the run's ORCHESTRATOR_* set must reach the child unchanged"
        )
        # The secret never touches the supervisor's own output.
        assert SECRET not in completed.stdout, scenario
        assert SECRET not in completed.stderr, scenario


def test_missing_workdir_fails_closed(tmp_path):
    """Misuse fails closed: a missing workdir exits nonzero with no
    success document."""
    _write_fixture(tmp_path)
    env = _supervisor_env(tmp_path, "clean")
    del env["ORCHESTRATOR_WORKDIR"]
    completed = subprocess.run(
        [sys.executable, str(SUPERVISOR), "--budget", "30"],
        cwd=str(tmp_path),
        env=env,
        capture_output=True,
        text=True,
        timeout=60,
    )
    assert completed.returncode != 0
    assert completed.stdout.strip() == ""  # no success document
    assert "ORCHESTRATOR_WORKDIR" in completed.stderr  # the reason


def test_unparsable_budget_fails_closed(tmp_path):
    """Misuse fails closed: an unparsable budget exits nonzero with the
    reason on stderr and no JSON document."""
    _write_fixture(tmp_path)
    completed = subprocess.run(
        [sys.executable, str(SUPERVISOR), "--budget", "not-a-number"],
        cwd=str(tmp_path),
        env=_supervisor_env(tmp_path, "clean"),
        capture_output=True,
        text=True,
        timeout=60,
    )
    assert completed.returncode != 0
    assert completed.stdout.strip() == ""
    assert "budget" in completed.stderr


def test_failing_recovery_fails_closed(tmp_path):
    """Misuse fails closed: a ``--resume`` that itself fails is a
    nonzero exit with the reason on stderr and no JSON document
    claimed as success."""
    completed = _run_supervisor(tmp_path, "resume-fails", "30")
    assert completed.returncode != 0
    assert completed.stdout.strip() == ""  # no document claimed as success
    assert "recovery" in completed.stderr  # the reason
