# Architecture

## Controller

The v0.2 workflow model, append-only events, transition enforcement,
idempotent dispatcher, leases, retries, pause/gate behavior, and correction
loop remain unchanged. `LiveCodexWorkerAdapter` translates only Codex build
and correction jobs into the worker schema and preserves external thread IDs.

## Non-root worker

`WorkerSupervisor` refuses any UID except 1005 for a live run. Its registry
maps `live-codex-qualification` to the canonical isolated repository. Job
schema rejects unknown fields, job types, attempts, projects, oversized
instructions, noncanonical paths, and traversal.

Codex CLI 0.145.0 is launched with a fixed executable and argv:

- new work: `codex exec --json --output-schema … --output-last-message …
  --sandbox workspace-write -C <registered-workspace> <bounded-prompt>`;
- correction: `codex exec resume --json --output-schema …
  --output-last-message … <preserved-thread-id> <bounded-correction>`.

No shell interprets the arguments. The environment contains only fixed
`HOME`, `PATH`, and `LANG`. The supervisor creates a detached process group,
enforces timeout/output limits, and terminates the group on failure.

## Local boundary and persistence

`LocalWorkerBoundary` verifies an HMAC before parsing a strict envelope,
deduplicates idempotency keys, and audits accept/reject/duplicate decisions.
The optional daemon consumes fixed spool files in a mode-0700 state directory;
it has no network listener. Atomic write-validate-rename records preserve job
PID, thread ID, timing, heartbeat, exit, completion, and next action.
Exclusive `wx` lock files prevent concurrent project writers. Startup detects
unfinished records and marks them for deterministic requeue.

The development fallback remains credential-free. PostgreSQL mode remains
fail-closed and unprovisioned.
