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.
