REPORT — phase6-supervisor-implementer
STEP: phase6-supervisor — Phase 6: the external supervisor (the phase's main missing piece)
REV: 307aaa0f4a150be5e7c5556e3517f77699d62243   FINAL: 90b54a15692f34faa49fb5802af1f3d74f32c8ad
CHANGED: scripts/supervise_run.py (new file, mode 100644) — the external supervisor: launches exactly one child as the literal command `sys.executable scripts/smoke_run.py --json` with the inherited environment (every `ORCHESTRATOR_*` variable the operator sets passes through unchanged — the supervisor adds none and redacts none, so the recorded authorisation and the provider credential ride the same environment into both heads and the secret never touches the supervisor's own output), owns the child's wall-clock deadline (`--budget`, seconds), and on controller death — the child killed at the deadline, lost (no JSON document on stdout), or exited nonzero — reaps the child, kills the whole process tree (`start_new_session` at launch, `killpg` on expiry, so sandboxed grandchildren die with the child), and drives the recorded recovery exactly once (`sys.executable scripts/smoke_run.py --resume` under the same environment, the run's recorded authorisation — the supervisor never invents one). stdout carries exactly one JSON document (`workdir`, `code`, `timed_out`, `recovered`, `child_wall_seconds`) with narration on stderr; the supervisor exits 0 only when the child exited 0 with a document and no recovery ran, otherwise the child's code (or 1 when the child produced none); misuse — a missing workdir, an unparsable budget, or a `--resume` that itself fails — exits nonzero with the reason on stderr and no JSON document claimed as success. The supervisor never writes the workdir, the stores, or the ledger itself: every effect on trial state goes through the two recorded subprocess heads. The child discipline is `scripts/stress_run.py`'s (`run_child`/`ChildResult`/the deadline bound) plus the recorded `--resume` recovery — no daemon, no heartbeat protocol, no credential re-issuance beyond what `--resume` already does, no new event type.
CHANGED: tests/test_phase6_supervisor.py (new file) — nine pins, every child a fixture script the test owns (a `scripts/smoke_run.py` head placed at the working directory the supervisor launches the recorded head from), no committed module touched: the killed child (sleeps past a short budget) is reaped, marked `timed_out`, and the supervisor exits nonzero with the single document carrying `timed_out: true`; the lost child (exits nonzero with no document) drives exactly one `--resume` under the same environment — observed through the fixture's recorded invocation, asserting the full `ORCHESTRATOR_*` environment equality and that the secret never touches the supervisor's output — with `recovered: true`; the clean child (exits 0 with a document) drives no recovery and exits 0 with `recovered: false`; a child that exits 0 without a document is lost (recovery once, supervisor exits 1); a nonzero child with a document still drives recovery (document carries the recovery's code, supervisor exits the child's code); the deadline kill reaches the whole tree (a grandchild sleep is reaped by PID, no sandbox-availability skip — the pin runs the supervisor's own process-group kill, never a sandboxed workload); and the three misuse shapes (missing workdir, unparsable budget, failing `--resume`) fail closed.
VERIFIED: scripts/check-tests --fast — 972 passed, 106 deselected in 73.24s (0:01:13), exit 0 (REV's 963 passed, 106 deselected plus this step's 9 new pins).
VERIFIED: .venv/bin/python -m pytest tests/test_phase6_supervisor.py — 9 passed in 4.88s, exit 0.
VERIFIED: .venv/bin/python -m pytest tests/test_axis2_robustness.py -m "not slow" — 17 passed, 4 deselected in 5.38s, exit 0 (the same 17 passed, 4 deselected as REV: the spend-settle and lock pins are untouched, because the step touches no committed module).
VERIFIED: .venv/bin/python -m pytest tests/test_phase3_project_oracle.py — 5 passed in 246.75s (0:04:06), exit 0.
VERIFIED: scripts/check-static — exit 0. The gated `ruff check --select BLE001,S110 src/orchestrator` prints "All checks passed!"; the advisory run prints "Found 104 errors." (unchanged from REV's 104 — the two new files add no advisory finding).
VERIFIED: scripts/check-docs — exit 0. Prints "376 Total (in 910ms) 174 Unique 376 OK 0 Errors" (the gate's own printed line at FINAL; the counts are unchanged from REV's 376/174/376/0).
VERIFIED: scripts/check-scope 307aaa0f4a150be5e7c5556e3517f77699d62243 90b54a15692f34faa49fb5802af1f3d74f32c8ad docs/research/phase6-supervisor-brief.md — exit 0. Prints `claimed: scripts/supervise_run.py tests/test_phase6_supervisor.py`, `tripped: none`, `scope: ok (3 path(s) in 307aaa0f4a150be5e7c5556e3517f77699d62243..90b54a15692f34faa49fb5802af1f3d74f32c8ad)` (the third path is the brief itself, added under `docs/research/` at 427e9ec and allowed implicitly).
VERIFIED: the red evidence at REV — a worktree at `307aaa0f4a150be5e7c5556e3517f77699d62243` (where `scripts/supervise_run.py` does not exist) with the new module copied in uncommitted, run from the worktree as `.venv/bin/python -m pytest tests/test_phase6_supervisor.py`: exit 2, `collected 0 items / 1 error`, `ERROR collecting tests/test_phase6_supervisor.py … tests/test_phase6_supervisor.py:60: in <module> import supervise_run E ModuleNotFoundError: No module named 'supervise_run'`, `Interrupted: 1 error during collection`. The module cannot collect at REV because the supervisor it imports is absent — red evidence of absence, not a regression (rule 6: the pins are new, so no committed battery can show them red-then-green).
NOT VERIFIED: the full `scripts/check-tests` (no `--fast`): this brief's ACCEPTANCE names the `--fast` form, and `--fast` selects exactly the full non-slow suite (972 passed, 106 deselected — the 106 deselected are the slow-marked end-to-end experiment tests). The work commit's pre-commit hook additionally re-ran that same non-slow suite as its own gate before the commit landed (its serial phase printed "31 passed in 11.41s"; the commit landed only because the hook passed), so the full-suite shape is covered twice over; the `--slow` battery is not this step's acceptance.
FINDINGS:
  F1 | SEVERITY: P2 | ORIGIN: BRIEF | STATE: fixed
  The brief names the child command as the literal `sys.executable scripts/smoke_run.py --json` and allows exactly two supervisor-only settings (the wall-clock budget and the workdir), while its pin design requires that "every child is a fixture script" — for a fixture child to be launched, the child's path must be resolvable by the test. The one reading consistent with all three: the child is launched by its literal relative path, resolved against the supervisor's working directory — the repository root under the documented invocation form (`python3 scripts/supervise_run.py …`), and a fixture root under the pins.
  FIXED: no regression test — a committed brief's prose has none; the reading taken is the only one that keeps the brief's GOAL, its "two supervisor-only settings", and its pin design simultaneously true (a path resolved from the supervisor script's own location would make the pins' fixture children unlaunchable without a third setting the brief does not allow). Named per the brief's own instruction ("If exactly one reading is consistent, take it and file a FINDING with ORIGIN: BRIEF that names the reading you took").
  F2 | SEVERITY: P2 | ORIGIN: BRIEF | STATE: fixed
  The exit rule's parenthetical — "otherwise it exits the child's code (or 1 when the child produced none)" — is ambiguous: "produced none" can name no exit code (the killed child) or no JSON document (the lost child). Read as "no exit code", a child that exits 0 without a document would make the supervisor exit 0, contradicting the same sentence's "exits 0 only when the child exited 0 with a document and no recovery ran"; the one consistent reading is "produced no JSON document", under which the killed child and the exit-0-without-a-document child both exit 1 and a nonzero child propagates its code.
  FIXED: no regression test — a committed brief's prose has none; the reading is pinned by `test_child_exiting_zero_without_a_document_is_lost` (the exit-0-without-a-document child drives the recovery once and the supervisor exits 1) and `test_killed_child_is_reaped_marked_timed_out_and_drives_recovery` (the killed child exits nonzero with `timed_out: true`), and the nonzero propagation by `test_lost_child_drives_the_recovery_head_once_under_the_same_environment` (exit 3, the child's code) and `test_nonzero_child_with_a_document_still_drives_recovery` (exit 5, the child's code).
  F3 | SEVERITY: P2 | ORIGIN: BRIEF | STATE: fixed
  The misuse clause — "a `--resume` that itself fails is a nonzero exit with the reason on stderr and no JSON document claimed as success" — admits two fail-closed readings: print the document carrying the recovery's nonzero code, or print no document at all. The reading taken is the uniform one: all three misuse shapes (a missing workdir, an unparsable budget, a failing `--resume`) exit nonzero with the reason on stderr and no JSON document on stdout — the strongest fail-closed form, and the one the missing-workdir pin's "no success document" states.
  FIXED: no regression test — a committed brief's prose has none; the reading is pinned by `test_failing_recovery_fails_closed` (a failing `--resume` exits nonzero with the reason on stderr and an empty stdout) and `test_missing_workdir_fails_closed` (a missing workdir exits nonzero with an empty stdout).
SHAPES: three shapes the suite does not build, each probed live against the real recorded head (the pins drive fixture children by the brief's design — "without running a real trial" — so no committed pin launches the real `scripts/smoke_run.py` through the supervisor; the sandbox is available in this environment, so no fail-closed skip applies):
  1. The documented form, clean drive — `python3 scripts/supervise_run.py --budget 900` from the repository root with the scripted environment (`ORCHESTRATOR_WORKDIR=evidence/phase6-probe-clean ORCHESTRATOR_OWNER=phase6-probe ORCHESTRATOR_CAP=500 ORCHESTRATOR_AUTHORIZED_AT=2026-01-01T00:00:00Z ORCHESTRATOR_AUTH_METHOD=phase6-live-probe ORCHESTRATOR_REQUIRE_CONFORMANCE=0 ORCHESTRATOR_SEEDS=1001`): the real head ran the four-arm comparison (4 trials, all `CORRECT_ACCEPTANCE`), stdout was the single document `{"workdir": "evidence/phase6-probe-clean", "code": 0, "timed_out": false, "recovered": false, "child_wall_seconds": 16.757}`, stderr carried the recorded head's narration (cap worksheet, preflight, results) plus `[supervise] child exit=0 wall=16.76s timed_out=False`, exit 0 in 16.8s.
  2. Controller death, real head — the same command with `--budget 14` (workdir `evidence/phase6-probe-killed2`): the child was killed at the deadline mid-comparison (`[supervise] child exit=None wall=14.00s timed_out=True`), the recorded `--resume` ran once under the same environment and settled the in-flight reservation (`EXP-FIXED_ONE_LEVEL-1001: recovered 1 attempt(s)`, `EXP-FIXED_ONE_LEVEL-1001: spend settled at 6.0 (RECOVERED)`), stdout was `{"workdir": "evidence/phase6-probe-killed2", "code": 0, "timed_out": true, "recovered": true, "child_wall_seconds": 14.005}`, exit 1 (the killed child produced no code), and the workdir's ledger closes with `in_flight: {}` (EXP-DIRECT-1001 `CORRECT_ACCEPTANCE` 1.0, EXP-FIXED_ONE_LEVEL-1001 `RECOVERED` 6.0) — controller death left no unrecorded effects.
  3. Fail-closed recovery, real head — the same command with `--budget 12` (workdir `evidence/phase6-probe-killed`): the deadline landed during oracle calibration, before any trial store existed, so the recorded `--resume` found `no trials directory to resume` and exited 1, and the supervisor failed closed: exit 1, the reason on stderr (`error: the recorded recovery (--resume) failed with exit code 1; the workdir evidence/phase6-probe-killed is not settled`), and an empty stdout (no JSON document).
TRIPPED: none
PROPOSED ROWS: none
METHOD FRICTION: none
INHERITED:
none — the received INHERITED is the brief's clean block ("INHERITED: none — nothing carried into this step"); F1-F3 are fixed, not carried. Nothing came in, nothing is open, and nothing is carried forward.
