machine-driver

The dumb, tireless driver — Box 2 of The Machine (the deterministic control plane), the piece that was missing for code work. It is the deliberately-stupid loop that keeps work moving without a human pressing the button. It spends zero model tokens; the model only runs inside the worker step.

Part of Frontier Infra — sibling to AVL (view), AAR (proof), and Conductor (the Orchestrator-L1 ops template). machine-driver is the deterministic code-work driver: checkpoint/resume, per-task isolation, verify-by-result — pointed at repos instead of a help-desk queue.

Conformance to the six-box spec: see CONFORMANCE.md · contributing/agents: AGENTS.md.

The 5-part loop (all in driver.py)

1. State — goal.json on disk. The goal never lives only in a context window.
2. Driver — the while loop. Deterministic, no judgment, runs for days.
3. Worker — one fresh process per task (worker_cmd). The only place judgment is spent.
4. Verify — verify_cmd exit code is ground truth. Pass → done. Fail → re-queue (fresh attempt) → block and surface after max_attempts. It cannot silently skip.
5. Autonomy — mode: "propose" (leave the diff for review) or "commit" (proceed). Fail-closed to propose.

Run it for real

1. Copy goal.example.json → goal.json. Point repo at a real repo.
2. Set worker_cmd to the CLI or API-backed adapter you chose, e.g. agent-worker "{task}". The driver does not depend on a model vendor or harness.
3. Set verify_cmd to your ground truth, e.g. npm test (or the goal-contract gate, or cargo test, etc.).
4. Break the goal into a few small tasks (each one a fresh-context burst).
5. python3 driver.py goal.json. Watch it take a step, get verified, take the next.

Start in "propose". Turn the dial to "commit" one goal at a time, as the verifier earns your trust. That is Part 5 — a setting, not a rebuild.

Contract, proof, and L3 controls

goal.json carries deterministic control-plane blocks; none add a model token:

• contract (Box 0) — definition_of_done, acceptance_tests, immutable, autonomy_ceiling, proposed_by, ratified_by. The driver refuses to commit unless the contract is independently ratified (ratified_by != proposed_by) — the Council is the natural ratifier of the target; ground-truth tests stay the verifier. autonomy_ceiling: 0=propose, 1+=commit-allowed.
• budget (Box 5 governor) — max_worker_runs / max_wall_seconds. Breach → HALT + operator alert. This is the control the 131-duplicate incident lacked.
• operator_override (Governance Δ2) — a file or inline override can halt or lower autonomy mid-flight. The driver checks it before dispatch, after the worker, and again at the mutation gate; every effective override records override_effect_slo_seconds and emits an ACK-required alert.
• idempotency_store (Ops) — a persistent store rejects duplicate ACTIVE/DONE idempotency keys before a second worker side effect can run.
• runtime_health_manifest (Runtime Δ3) — python3 driver.py goal.json --monitor-once acts as the independent monitor, checking component staleness, registered anomaly detectors, and (when declared) four-layer workforce evidence.

The optional runtime_health_manifest.workforce_health contract consumes the canonical frontier.machine.health.v1 shape: top-level deployment_id / checked_at, then process, scheduler, execution, and governance layers whose checks arrays carry id, status, critical, reason_code when applicable, observed_at, stale_after_seconds, and summary. Deployment-specific probes produce the evidence; the stdlib driver performs only deterministic validation and reduction. Its precedence matches the bundled Frontier checker: halted > blocked > propose_only > degraded > pass. Missing/stale verifier evidence lowers to propose-only; critical unknowns and execution failures block; active override or pending ACK halts; a failed/stale non-critical check degrades without making can_mutate false. pass and degraded clear this health prerequisite only—the independent contract, verifier, and mutation gates still apply. A green process therefore cannot mask a dead scheduler, provider/auth failure, or dead gate.

Every loop transition appends to driver-log.jsonl, a hash-chained audit trail for dispatch/requeue/halt/verify events. Blocks, quarantine, budget halts, stale-health findings, duplicate-key blocks, and operator overrides also create durable pending_acks entries and fire the configured alert transport (TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID, with stdout as the local fallback).

Canonical signed AAR

The hash-chain in driver-log.jsonl is loop telemetry, not the proof layer. The proof layer is the org's own standard: a per-task, Ed25519-signed Agent Attestation Record (../agentcontrolplane, agentscontrolplane.org).

Two artifacts, split cleanly:

• driver-log.jsonl — the hash-chained loop audit (dispatch / requeue / halt / verify). Telemetry.
• aar/<task-id>.json — one canonical signed AAR per verified/contradicted task. Proof.

The verify step already produces L2-shaped material — verifier ≠ worker for free:

AAR field	from the driver
aar	"0.02"
subject	the worker — did:web:<org>:machine-driver
principal	the signing org — did:web:<org> (= sig.by)
task	{ "id": task.id, "claim": task.goal }
verdict	"verified" (verify exit 0) · "rejected" (non-zero)
ground_truth	"confirmed" (exit 0) · "contradicted" (non-zero)
reason	one line, e.g. "verify_cmd exited 0 against repo HEAD"
checks	[{ source: repo, query: verify_cmd, observed_at: now, response_sha256: sha256(verify_output), excerpt: tail }]
verifier	{ id: did:web:<org>:<verifier>, independence: "same_principal" } — id != subject ⇒ L2
issued	now()

Integration (driver stays pure-Python; shell out to our own signer):

1. Build the record from the verify result → write aar/<task-id>.json.
2. node ../agentcontrolplane/tools/aar.mjs sign aar/<task-id>.json --priv <key> → adds sig (Ed25519, JCS-canonical, sig.by = principal).
3. self-test: node ../agentcontrolplane/tools/aar.mjs verify aar/<task-id>.json → expect → conformance: L2.

New goal.json keys: aar_tool (path to aar.mjs), aar_priv (key path), subject, principal. If absent ⇒ skip AAR (still write driver-log.jsonl), so the driver runs keyless.

The one human-gated input (irreducibly yours): the signing identity + key. node ../agentcontrolplane/tools/aar.mjs keygen --did did:web:frontierinfra.org:machine-driver --out-priv secrets/machine-driver.jwk.json --out-did <domain>/.well-known/did.json, then publish did.json. The worker is replaceable; the principal is not.

Kit status: the current the-machine kit reports a Machine-L2 Instrumented static structural candidate, not a full conformance certificate. Static rows for Δ1/Δ2/Δ3, idempotency, signed AAR, and gate controls are backed by regression tests, but non-bypassability remains PARTIAL until a live bypass chaos probe is captured and attached. Live chaos/replay rows remain NOT-RUN in the kit output; see CONFORMANCE.md for the exact packet result and the path to true L3/L4.

Status / next (when fresh)

Hardened + smoke-tested: happy path emits signed AAR · governor halts + durable ACK alert · no-verifier ⇒ propose-only · duplicate idempotency key ⇒ one effect · operator override halts before dispatch or before mutation · hostile task IDs cannot inject shell commands into git commits · failed commits are logged as failures, not commits · unratified verified worker diff cannot commit · stale runtime health alerts from --monitor-once.

Next:

• Council = Box-0 ratifier — wire roundtable.sh to draft/ratify the contract before the first real run;
• feed tasks from GitHub Issues or another operator-owned work queue instead of a hand-written list;
• capture a dated live chaos/replay packet for Machine-L3 conformance;
• add stable deployment_id / scope_id to signed receipts for the L4 Frontier Infra row;
• keep task selection dumb (rules table only if ordering ever needs it — never a model in the loop).