<!-- informative -->

# Milestone-8 Handoff (context compaction)

> **DEMOTED (2026-09).** This is a historical context-compaction snapshot taken at revision `bc4f0bc` (558 tests). It is
> no longer the entry point: its state was superseded by the readiness remediation batches, the Phase 1 refactor and its
> [review](phase1-refactor-review.md), Axis 2 robustness, and the Axis 1 patch-producer capability
> ([design brief](axis1-patch-producer-design.md)) with the folded Axis 3 seed matrix. The forward plan is the
> [Self-hosting roadmap](../self-host.md); current state is the repository itself (704 tests). Read this only for the
> historical residuals and the paid-run archive locations it records.

Self-contained state as of the snapshot. It does not depend on any prior conversation.

## Snapshot

- Repo: this repository. Revision: `bc4f0bc` on `main`.
- Tests: **558 passed** (`scripts/check-tests`); static gate and docs gate green (`scripts/check-static`, `scripts/check-docs`).
- Counterexample registry: **23/23** readiness findings covered (`tests/counterexamples.yaml`).
- All independent adversarial gates returned **GO**: SPEND, EXECUTION, R08 evaluator isolation, MEASUREMENT, and the untrusted-model-reply boundary.

## Where things are

- Source: `src/orchestrator/` — controller/reducer/store/model (control plane), `sandbox.py`/`sandbox_launcher.py` (execution), `worktree.py` (Git import/verification), `model_adapter.py` (trusted model boundary), `experiment.py` (frozen harness), `oracle.py`, `observability.py`, `secrets.py`, `spend.py`.
- Runner: `scripts/smoke_run.py` — env-driven real/scripted smoke runner (`--probe`, `--inspect`, `--resume`, `--json`).
- Review/evidence docs: `docs/research/` (all briefs and adversarial reports); readiness report `docs/report-milestone8-readiness.md`.
- Run archives (git-ignored): `evidence/matrix`, `evidence/smoke-real3`, `evidence/smoke-real4`, `evidence/smoke-real5`.
- Local wrapper: `run.sh` (git-ignored; currently **contains a live API key** — see Residuals).

## What is done (terse)

- Readiness remediation Batches 1–6: SPEND (token ceilings, experiment-wide owner cap, paid-entry gate), EXECUTION (cancellation interruption, verified sandbox limits, single deadline), R08 evaluator isolation (collector + candidate child), R10 repair/terminal outcomes, R13 grade persistence/reconstruction, R14 derived-effect reconciliation, and the Batch 6 residuals. Each review finding has a permanent regression test.
- Real-model runs completed and archived (all four arms): acceptance, fail-closed, and indeterminate path classes.
- Reviewer briefs and reports for every gate are in `docs/research/`; treat them as the specification of the invariants that must not regress.

## Paid run results (all verified)

| Run (archive) | seeds | Outcome | Ledger |
| --- | --- | --- | --- |
| `evidence/smoke-real3` | 1001 | 4/4 `CORRECT_ACCEPTANCE` | committed 0.002847 USD |
| `evidence/smoke-real4` | 1003 `BUILD_FAILURE` | 4/4 `CORRECTLY_UNRESOLVED` (`INFEASIBLE`/terminal child, `REPLAN_REQUESTED`, `NODE_MARKED_INFEASIBLE`) | committed 0.001 USD |
| `evidence/smoke-real5` | 1004 `ORACLE_INFRASTRUCTURE` | 4/4 `INDETERMINATE` (run `ACCEPTANCE_CLAIMED`) | committed 0.0026 USD |
| `evidence/matrix` | 1001–1004 | 8 `CORRECT_ACCEPTANCE`, 4 `CORRECTLY_UNRESOLVED`, 4 `INDETERMINATE` | authorized 1800, committed **0.009393 USD** |

All runs: no credential bytes in stores, transcripts 0 errors, no unsettled reservations. Honest framing: these are transport/pricing/accounting runs over a **deterministic** target; the model contributed `SEMANTIC_EVALUATION` outputs, so they are **not** coding-capability measurements.

## How to run (`scripts/smoke_run.py`, env-driven)

Required: `ORCHESTRATOR_OWNER`, `ORCHESTRATOR_CAP` (monetary ceiling, `COST_UNITS`).
Real mode: `ORCHESTRATOR_MODE=real`, `ORCHESTRATOR_CONFIRM_REAL=yes`, `ORCHESTRATOR_PROVIDER_BASE_URL/MODEL/API_KEY`, `ORCHESTRATOR_PRICE_INPUT_PER_MTOK`, `ORCHESTRATOR_PRICE_OUTPUT_PER_MTOK`, `ORCHESTRATOR_PROVIDER_UNITS`.
Tokens: `ORCHESTRATOR_MAX_*_TOKENS` are the **per-call declared caps**; `ORCHESTRATOR_RUN_MAX_*_TOKENS` are the **per-trial aggregate ceilings** (do not conflate them).
Seeds: `ORCHESTRATOR_SEEDS=1001,1002,1003,1004` (or single `ORCHESTRATOR_SEED`). Each arm × each seed is a trial.
Cap formula: `cap >= trials x (ORCHESTRATOR_MODEL_COST + ORCHESTRATOR_PER_ATTEMPT_COMMITMENT)`, trials = 4 arms × seeds; 16 trials ⇒ `>= 1680`.
Debug: `ORCHESTRATOR_DEBUG_TRANSCRIPT=1` writes bounded, redacted prompt/reply lines to `<workdir>/debug/transcript.jsonl` (0600).
Output: `--json` prints one JSON document on stdout (narration to stderr); `--inspect` reads a workdir without running; `--probe` makes exactly one billable call.
An experiment workdir is bound to one authorization and its trials are never overwritten: use a **fresh workdir per authorization**; inspect or `--resume` an existing one.

## Known residuals (non-blocking unless stated)

- **Credential handling (do before long-lived use):** provider revocation POST is unauthenticated; the key lives in `run.sh` (rotate later, per owner); prefer an env/secret-manager source with a short TTL.
- **Accounting:** a reply that reports usage but fails to parse is settled conservatively (no recorded actual); exposure is bounded for a conforming provider.
- **Latent P3 (fixed):** untrusted `output_type` in oversized rejections is now bounded.
- **Client-reported usage** cannot be independently verified; a provider ignoring declared `max_tokens` can exceed the commitment (still bounded by the monetary cap).
- **Controller death** cannot run teardown; needs an external supervisor (deliberate scope).
- **Sleeping/expired credentials on restart** must be restored (`controller.restore_credentials`) or admission fails closed.

## Next plan (chosen)

### Axis 2 — Robustness/load stress (do first)

Goal: validate the operational envelope under real provider pressure before any long capability run.

Scope:
1. Parallelism: run several `scripts/smoke_run.py` processes concurrently, each with its own workdir/authorization (the per-workdir ledger is safe). Provoke rate limits/429s and slow responses.
2. Retries: raise `ORCHESTRATOR_MAX_MODEL_CALLS`/retry lineage so the bounded repair loop re-issues real calls; confirm each retry is a fresh attempt, is billed, and settles.
3. Hostile replies at scale: point at a local stub for the adversarial sweep (truncation, oversized, invalid verdict, drip, echo secret) while the real matrix runs in parallel; confirm nothing aborts the run and all failures are recorded and settled.
4. Provider faults: observe 429/5xx/timeout handling in the current client (it fails closed with no retry); decide whether to add bounded retry/backoff to the client.

Acceptance: no unhandled exception escapes a trial; no pass is produced by any hostile/oversized/malformed reply; deadlines bound every call; the ledger `committed` equals summed settled actuals with **zero** outstanding reservations after completion; transcripts show no truncation; no credential bytes in any store.

### Axis 1 — Model-produced implementation (capability; the real milestone-8 question)

Goal: measure the model at producing the implementation rather than relying on fixed deterministic commands.

Scope:
1. Introduce a patch-producing path: the model emits an `ARTEFACT` (unified diff or file set) for the node's scope; admit it through the existing trusted boundary, then apply it through the scope-gated worktree importer (`WorktreeManager`) instead of `_commands_for` writing solution files.
2. Keep the four arms, the frozen target, and the hidden oracle; grade the resulting tree with per-component hidden checks so partial progress is measurable (not just red).
3. Attribute cost per component/attempt; keep the experiment-wide cap and per-trial budgets.
4. Design a fair prompt and a bounded patch schema (size-capped, scope-validated; the reply-boundary guards already apply).
5. Expected: likely failure at first; make failure informative (per-component outcomes, retries, cost), and never relabel it as success.

Acceptance: the model (not the harness) produces the code; grading is from the hidden oracle over the produced tree; the run is reproducible per `(arm, seed)`; the result is reported with the disclosed unmeasured metrics and the honest caveat that the target is small.

### Axis 3 — Scale/seed matrix (optional, cheap)

Add seeds (mostly `NORMAL`) to widen the denominator; cap scales linearly. Fold into Axis 1 once the capability path exists.

## Invariants that must not regress

The adversarial reports in `docs/research/` define them. In brief: untrusted candidate/model input never reaches trusted execution except through validated boundaries; verification binds the committed object, not a working copy; failures fail closed and are recorded; accounting preserves reported usage; timeouts bound every call; recovery reconciles derived consequences idempotently; all run limits and the experiment-wide cap are enforced before spend.
