REVIEW BRIEF — phase6-supervisor (Phase 6: the external supervisor — the phase's main missing piece)
REV: 307aaa0f4a150be5e7c5556e3517f77699d62243
FINAL: 90b54a15692f34faa49fb5802af1f3d74f32c8ad
REVIEW ACCEPTANCE: scripts/check-scope 307aaa0f4a150be5e7c5556e3517f77699d62243 90b54a15692f34faa49fb5802af1f3d74f32c8ad docs/research/phase6-supervisor-brief.md
FOCUS: the supervisor contract above all — does the killed child die as a tree (`start_new_session` at launch, `killpg` on expiry, grandchild reaped), does the lost/nonzero child drive exactly one recorded `--resume` under the run's own environment, does the clean child drive none, is the single JSON document the only stdout with narration on stderr, does misuse fail closed, and is the red evidence the REV collection failure of the new module (absence, not regression); are F1/F2/F3 each the one consistent reading; is the `IN SCOPE` line plain with scope green; are the docs figures the gate's own printed lines (rule 14); and does the step touch only the two new files with every committed battery green and no committed test edit.
SEVERITY SCALE: P0 blocks the step; P1 is serious; P2 is minor.
QUESTIONS TO ATTACK:

  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).

  1. F1's one-reading claim. The brief allows exactly two supervisor-only settings and requires every child to be a fixture script. Verify in `scripts/supervise_run.py` that the child is launched as the literal relative path `scripts/smoke_run.py` resolved against the working directory (no third setting, no path derived from the supervisor script's location), and that the pins launch fixture children by running the supervisor with `cwd` at the fixture root. If a second consistent reading exists, the finding is not one-reading and the step returns to planning. Mutant: resolve the child path against the supervisor script's own directory instead of the working directory — which pin goes red, and on which member?

  2. F2's exit-rule reading. Re-drive the four exit faces at FINAL and check the supervisor's exit code in each: killed child exits 1, exit-0-without-a-document exits 1 with exactly one recovery, nonzero child propagates its code (3, 5). Is there any face where the supervisor exits 0 while a recovery ran, or exits a code the brief's rule does not produce? Then attack the `code` field's meaning: on a nonzero child with a successful recovery the document carries the recovery's code (0) while the supervisor exits the child's code — is that what the brief's `"code": <child-or-recovery code>` promises on every face, or does a `code: 0` document beside a nonzero exit mislead? Mutant: exit the supervisor with the document's `code` instead of the child's code on the nonzero face — which pin goes red, and on which member?

  3. F3's uniform no-document misuse. Re-drive the three misuse shapes at FINAL: missing workdir, unparsable budget, failing `--resume` — each exits nonzero with the reason on stderr and an empty stdout. Is there any misuse shape that prints a JSON document, or any failing `--resume` that leaves a half-printed document? Mutant: print the document carrying the recovery's nonzero code on the failing-`--resume` face — which pin goes red, and on which member?

  4. The supervisor contract live at FINAL — the one question. Drive the faces through the supervisor as subprocesses: (a) killed — a sleeping child past a short budget is reaped, marked `timed_out`, the whole process tree dies (`start_new_session` at launch, `killpg` on expiry — a grandchild sleep is reaped by PID), exactly one recorded `--resume` runs, nonzero exit; (b) lost/nonzero — exactly one `--resume` under the same environment (the full `ORCHESTRATOR_*` set unchanged, the secret never on the supervisor's own output), supervisor exits the child's code; (c) clean — exit 0 with a document, no recovery subprocess; (d) single-document shape — stdout is exactly one JSON document, narration on stderr. Report each guarantee as falsified-with-reproducer or attacked-and-not-falsified with the method. Then the red evidence: reproduce the REV collection failure of the new module (the supervisor absent) and adjudicate it absence, not regression — no committed battery can show these pins red-then-green. File a finding per falsified class.

  5. The report's forms and counts (J-class). `FINAL` is the work commit `90b54a15692f34faa49fb5802af1f3d74f32c8ad`, never the report commit `9afb8a3` — verify rather than taking the report's word. Re-run the brief's ACCEPTANCE lines at FINAL (fast suite 972/106, the 9-passed supervisor module, the 17-passed axis2 non-slow battery, the oracle module, static gated `BLE001,S110` clean with advisory `Found 104 errors.` unchanged, docs printed line with 0 errors — every figure the gate's own printed line, rule 14, never the REV line quoted in CONTEXT); `TRIPPED: none` matches check-scope's `tripped:` line and REVIEW ACCEPTANCE is green run first. `git diff 307aaa0f4a150be5e7c5556e3517f77699d62243 90b54a15692f34faa49fb5802af1f3d74f32c8ad --stat` touches only the two new files plus the brief (no committed test edit — verify). `SHAPES`' three real-head faces read against rule 7: the pins drive fixture children by design, so adjudicate whether the three live real-head probes (clean drive, controller-death with the ledger closing `in_flight` empty, fail-closed pre-store recovery) are properly listed unbuilt shapes rather than buried. `INHERITED`'s `none` against the received set (the brief's clean block; F1–F3 fixed-not-carried). Every field of the report present and filled, nothing outside the template added. Standing battery: `scripts/check-tests` (your full run — record it in `VERIFIED`).

--- BEGIN BRIEF UNDER REVIEW (copy of docs/research/phase6-supervisor-brief.md; the committed file is authoritative) ---
IMPLEMENTER BRIEF — phase6-supervisor (Phase 6: the external supervisor — the phase's main missing piece)

GOAL: Long unattended runs stop depending on the controller process staying alive: an external
supervisor launches one `scripts/smoke_run.py` run as its child, owns the child's wall-clock
deadline, and on controller death (child killed, child lost, or child exit without a settled
workdir) reaps the child, kills the whole process tree, and drives the recorded recovery path
(`--resume` under the run's recorded authorisation) so every trial settles and no spend
reservation is left in flight. The Phase 6 missing piece is delivered in the smallest slice
that fails closed: the supervisor is `scripts/stress_run.py`'s existing child discipline
(`run_child`/`ChildResult`/`check_deadlines_bound`) plus the recorded `--resume` recovery — no
new daemon, no heartbeat protocol, no credential re-issuance beyond what `--resume` already does
(R05), and no new event type.

CONTEXT: Phase 5 is delivered and its chain is closed (the exit-gate step's review leaves
nothing open: `INHERITED: none` in both reports; `docs/record.md`'s Phase 6 baseline row reads
15 rows / Fixed 32 / Red 12; no OWNER ruling names the next brief). The current phase is Phase
6 (`docs/self-host.md`'s Operational Envelope): bounded 429 backoff landed with Axis 2, the
provider key is read from the environment, the experiment cap is wired, and the status names
the external supervisor as the main missing piece. The self-host invariant it serves is
`docs/self-host.md:236` ("An external supervisor exists before unattended long runs; controller
death cannot leave unrecorded effects"). The seams exist and are pinned: the child discipline
is `scripts/stress_run.py:run_child` (subprocess with `timeout=workload.wall_budget`, kill on
expiry, `ChildResult` with `timed_out`) plus `check_deadlines_bound`; the recovery entry is
`scripts/smoke_run.py:resume`/`_resume_locked` (`Controller.recover` per trial store, then the
in-flight reservation settled `RECOVERED` under the recorded authorisation); the spend
invariant is the axis2 pin battery (`ledger["in_flight"] == {}` with committed == actuals).
Gates measured at REV `307aaa0f4a150be5e7c5556e3517f77699d62243` (this step's base, clean tree):
`scripts/check-tests --fast` prints `963 passed, 106 deselected in 69.07s (0:01:09)`;
`scripts/check-docs` prints `376 Total (in 753ms) 174 Unique 376 OK 0 Errors`;
`scripts/check-static` exits 0 with the advisory line `Found 104 errors.`;
`tests/test_axis2_robustness.py` non-slow prints `17 passed, 4 deselected`. No
`docs/residuals.md` trigger glob matches this brief's IN SCOPE (the `PILOT-R*` triggers name
`planning_pilot.py`, `controller.py`, `reducer.py`, `decomposition.py`, `model.py`, and
`derive_obligations.py`; the store is byte-verified against `docs/residuals.md` before this
brief's commit, rule 2).

INHERITED:

From `docs/research/phase5-exit-gate-implementer.md`, its `INHERITED` block verbatim:

  INHERITED:
  none — the received INHERITED is the fixes-9 review's clean block (nothing carried, FFR-4/`DIVERGENCES CLOSED: document amended (b68be80…)` closed at the fixes-9 closeout). F1 is fixed, not carried (FINDINGS, F1). Nothing came in, nothing is open, and nothing is carried forward.

From `docs/research/phase5-exit-gate-review.md`, its `INHERITED` block verbatim:

  INHERITED:
  nothing came in and nothing is open after this review. The received set is the fixes-9 review's clean block (FFR-4 closed by this step's brief text, FRK-1 fixed at `ca9a25a`, FFR-1/FFR-2/FFR-3 closed by the fixes-8 brief's text, F41 closed at the fixes-7 closeout) and nothing was carried in it; F1 is filed `fixed` by the implementer and its close form is adjudicated above, so it rides nowhere; the `ProtocolViolation` carry adjudicated in question 1 rides on a green committed pin and owes no future action; and this review's F2 is a defect in an already-committed report, which the form closes as `recorded in the review that filed it` rather than carrying. No residual row rides (rule 3: `tripped: none`).

The copied blocks carry nothing open; nothing is carried forward.

IN SCOPE: scripts/supervise_run.py, tests/test_phase6_supervisor.py

RESIDUALS:

none — rule 3 selection for this brief's `IN SCOPE`: no `docs/residuals.md` trigger glob matches
`scripts/supervise_run.py` or `tests/test_phase6_supervisor.py` (see CONTEXT). No residual row
rides, so the residual half of `scripts/check-scope` has nothing to carry here and it prints
`tripped: none` — the line your report's `TRIPPED` field copies.

OUT OF SCOPE:
- Editing this brief file (`docs/research/phase6-supervisor-brief.md`). A committed brief is never modified; a re-cut is a new file.
- `scripts/smoke_run.py` in full: the run and `--resume` recovery it drives are delivered and pinned; the supervisor calls them as subprocesses and edits neither. If recovery needs a code change, stop and report `IN SCOPE` as insufficient.
- `scripts/stress_run.py` in full: its child discipline is the pattern the supervisor follows, not a seam the supervisor edits. If the discipline needs a change, stop and report `IN SCOPE` as insufficient.
- `src/orchestrator/controller.py`, the store, the experiment harness, `src/orchestrator/secrets.py`, `src/orchestrator/spend.py`: no controller, store, credential, or ledger change rides here. No new event type, no `docs/tables/*` change and no table regeneration, no `docs/event-catalogue.md` change.
- `docs/self-host.md`, `docs/residuals.md`, `docs/record.md`, `docs/method.md`, `docs/templates/`: the status edit, if any is owed, rides a later step; this step delivers the supervisor.
- Every committed test module — `tests/test_run_entry.py`, `tests/test_axis2_robustness.py`, `tests/test_smoke_run_client.py`, and every other committed module are read-only here. No committed test file is edited. If a pin would have to change for acceptance to pass, stop and report `IN SCOPE` as insufficient.
- `tests/open_defects.yaml` and the registry's meta-tests: no registration rides (a `test_review_*` probe that lands red rides in the new module only if the red is the step's own finding with its next brief named; no `test_bug_*` name — the open-defect registry would then own it).
- The controller stack, `experiment_target.build_target`, `schemas.py`.
- Registry and control files: `tests/counterexamples.yaml`, `tests/guard_mutation_matrix.yaml`, `tests/fixture_fidelity.yaml`, `tests/verifier_registry.yaml`, `tests/spend_paths.yaml`, `tests/invariants.py`, `tests/helpers.py`, `pytest.ini`, tool configuration.
- No new dependencies, no tooling configuration, no reformatting. No new exception class and no `*Executor`/`*ModelClient` class or provider-registry registration.

ACCEPTANCE: Commands (run every one and paste what each prints into `VERIFIED`; expected result is green, exit 0, for each):

    scripts/check-tests --fast
    .venv/bin/python -m pytest tests/test_phase6_supervisor.py
    .venv/bin/python -m pytest tests/test_axis2_robustness.py -m "not slow"
    .venv/bin/python -m pytest tests/test_phase3_project_oracle.py
    scripts/check-static
    scripts/check-docs
    scripts/check-scope 307aaa0f4a150be5e7c5556e3517f77699d62243 <FINAL> docs/research/phase6-supervisor-brief.md

Every `pytest` line names `.venv/bin/python -m pytest` deliberately (F17's carried correction: the bare `pytest`
on PATH has no `pytest-timeout` and `pytest.ini`'s `strict_config = true` rejects it on this host — run these
lines exactly as written and claim them under these names). The axis2 non-slow line is the supervisor's
invariant battery (`17 passed, 4 deselected` at REV — the spend-settle and lock pins it must not regress).
The oracle line rides because this brief adds a file under `scripts/` (rule: a brief that adds a file under
`tests/` or `scripts/` also names `pytest tests/test_phase3_project_oracle.py`). The docs gate is expected
green with 0 errors — and every count figure you write in `VERIFIED` is the gate's own printed line, never
the REV line quoted in this brief's CONTEXT and never recomputed from memory (rule 14, the F41 class). The
scope line is expected green, exit 0, printing `tripped: none` (and the `claimed:` line the parser prints).
`REV` below names the step's base — the parent of this brief commit — and is not claimed to be `FINAL`'s
parent (F4's lesson).

The supervisor (`scripts/supervise_run.py`, new file; mode 100644; run only as `python3
scripts/supervise_run.py …` — no bare-head form is documented and none is pinned):
- Takes the run's environment through (every `ORCHESTRATOR_*` variable the operator sets passes to the
  child unchanged; the supervisor adds none and redacts none — the secret never touches the
  supervisor's own output) plus two supervisor-only settings: a wall-clock budget in seconds and the
  workdir the child runs in (read from the same `ORCHESTRATOR_WORKDIR` the child uses, so supervisor
  and child cannot disagree about which workdir the recovery reads).
- Launches exactly one child: `sys.executable scripts/smoke_run.py --json` with the inherited
  environment, capturing stdout/stderr, with `timeout=<budget>`. On child exit (any code), the
  supervisor reaps it and reports its exit code, its wall seconds, and whether the deadline killed
  it. On `subprocess.TimeoutExpired` the supervisor kills the whole process tree (the child and
  everything it started — `start_new_session` at launch so the kill reaches sandboxed
  grandchildren, `killpg` on expiry), reaps, and marks the run `timed_out`.
- After a killed, lost (no JSON document on stdout), or nonzero-exit child, the supervisor drives
  the recorded recovery exactly once as a second subprocess: `sys.executable scripts/smoke_run.py
  --resume` under the same environment (the run's recorded authorisation — the supervisor never
  invents one). After a clean child exit (exit 0 with a JSON document), no recovery runs.
- Prints exactly one JSON document on stdout (narration goes to stderr): `{"workdir": …,
  "code": <child-or-recovery code>, "timed_out": <bool>, "recovered": <bool>,
  "child_wall_seconds": <float>}`. The supervisor exits 0 only when the child exited 0 with a
  document and no recovery ran; otherwise it exits the child's code (or 1 when the child produced
  none). The supervisor never writes the workdir, the stores, or the ledger itself — every effect
  on trial state goes through the two recorded subprocess heads.
- Fails closed on misuse: a missing workdir, an unparsable budget, or a `--resume` that itself
  fails is a nonzero exit with the reason on stderr and no JSON document claimed as success.

The pins (`tests/test_phase6_supervisor.py`, new file): the module pins the supervisor's
controller-death contract without running a real trial — every child is a fixture script or a
`scripts/smoke_run.py` head against a stub the test owns, and no committed module is touched:
- 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`.
- 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`.
- 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`.
- The kill reaches the whole tree: a fixture child that spawns a grandchild sleep is launched
  through the supervisor's session/kill path, and after expiry no grandchild survives (reaped by
  PID, fail-closed skip when the sandbox is unavailable is forbidden — this pin runs the
  supervisor's own process-group kill, never a sandboxed workload).
- Misuse fails closed: a missing workdir exits nonzero with no success document.

Red evidence: the killed-child pin is the step's red — it must fail at REV (no supervisor
exists: `scripts/supervise_run.py` absent, so the import fails). Run the new module at REV and
record the collection failure verbatim; it is red evidence of absence, not a regression (rule 6:
no regression test is opened or closed here — the pins are new, so no committed battery can show
them red-then-green).

Maintained unchanged (no new test owed; green in the battery lines): the axis2 non-slow battery
(the spend-settle, lock, and deadline pins), the fast suite, and the oracle module — all green at
`FINAL`, none edited; the supervisor touches no controller, store, credential, or ledger surface,
so every surface outside the two new files is undisturbed.

REV: 307aaa0f4a150be5e7c5556e3517f77699d62243
CLOSE OUT: yes
DIVERGENCES: none
REVIEW: one session — the supervisor contract above all: does the killed child die as a tree
(`start_new_session` at launch, `killpg` on expiry, grandchild reaped), does the lost/nonzero
child drive exactly one recorded `--resume` under the run's own environment, does the clean child
drive none, is the single JSON document the only stdout with narration on stderr, does misuse fail
closed, and is the red evidence the REV collection failure of the new module (absence, not
regression); is the `IN SCOPE` line plain with scope green; are the docs figures the gate's own
printed lines (rule 14); and does the step touch only the two new files with every committed
battery green and no committed test edit. Whether anything remains open after this step is the
loop's exit input — report findings and let the planner decide (cycle step 5).

You implement one brief. You do not plan, re-scope, or decide what the work is. Read every file
in IN SCOPE before editing it; if what you find contradicts the brief, report that instead of
guessing. Modify only what IN SCOPE names. If you find uncommitted changes in the tree, stop and say
so. Stop and report rather than improvise when IN SCOPE is
insufficient, the brief contradicts the code, you have already failed twice at this goal, or the
requirement is ambiguous and no single reading is consistent with the rest of the brief. If exactly
one reading is consistent, take it and file a FINDING with ORIGIN: BRIEF that names the reading you
took. No new dependencies, no tooling configuration, no reformatting. Run every ACCEPTANCE command;
fix what is in scope and report what is not.

A defect in the brief is a FINDING, never METHOD FRICTION. METHOD FRICTION is only for the method and
its templates: any place you deviated from them, found them ambiguous, or found them silent. Report
friction you worked around — that is the section the method learns from.

Commit your own work. When ACCEPTANCE passes, commit the files you changed, and only those, in one
commit whose message ends with the trailer `Actor: IMPLEMENTER`. That commit's full sha is FINAL.
Then append docs/templates/report.txt verbatim, fill it in, write it to
docs/research/<phase>-<subject>-implementer.md, and commit it in a second commit with the same
trailer. Do not amend the first commit to add the report: FINAL must not change after the report
names it. If you cannot commit, stop and say so; do not leave work uncommitted for someone else to
commit.
--- END BRIEF UNDER REVIEW ---

You did not write this code and you will not fix it; a finding is output, not an action. The step's
decision is the planner's (cycle step 5): report findings, never decisions. The commits under review
carry the trailer `Actor: IMPLEMENTER`; if your session wrote any of them, stop and say so. Run
REVIEW ACCEPTANCE first: it is the method's only gated check. The ACCEPTANCE lines inside the brief
under review are the implementer's; re-run them to verify the delivery, and run `scripts/check-tests`
as your standing battery — the full suite is your falsification ground — recording both in `VERIFIED`.
The embedded brief is a convenience copy: if the
standalone file it names differs, file a FINDING with ORIGIN: BRIEF and review against the committed
file.

You may create new test files to prove a finding, and modify nothing else. If a failing test would
need registering in tests/open_defects.yaml, say so in the report and leave the registration to the
next implementer brief rather than editing that file; the registry owns test_bug_* pins only, and a
test_review_* probe rides red until absorbed. Read pre-images with git show <rev>:..., not
the implementation's account of them. Run every mutant on a scratch copy of the tree, and diff each
mutant against git show <rev>:... before trusting its result. Attempt to falsify the brief, not only
the code: a finding that the brief was wrong is a finding, and so is a defect the implementer filed
only as friction. Answer every item under QUESTIONS TO ATTACK. Answers live in the form's fields —
a finding in FINDINGS, a measurement in VERIFIED/SHAPES. An added review's QUESTIONS TO
ATTACK come only from the implementer's report — never from another review's findings. Enumerate
the shapes you probed that
the existing suite does not build, as a list; zero with a stated reason is legitimate. Report each
guarantee as falsified-with-reproducer or attacked-and-not-falsified with the method.

Commit your own work: your new test files and your report, together, in one commit whose message
ends with the trailer `Actor: REVIEWER`. Append docs/templates/report.txt verbatim, fill it in, and
write it to docs/research/<phase>-<subject>-review.md. If you cannot commit, stop and say so.
