@matt82198/aesop 0.3.2 → 0.4.0

package/driver/CLAUDE.md

@@ -1,150 +1,150 @@
 # driver/ — AgentDriver backend-portability seam
 
-**What**: the domain contract letting aesop's wave loop run on non-Claude backends
-(Codex, open models); the loop dispatches only through the `AgentDriver` interface.
-**Phases 1-3 shipped** (interface + reference adapter; Codex Chat Completions; wave bridge).
+**What**: the domain contract letting aesop's wave loop run on non-Claude backends; the loop dispatches only through the `AgentDriver` interface. **Phases 1-3 shipped**.
 
 ## Files
 
-- **agent_driver.py** — the `AgentDriver` ABC + capability/request/result
-  dataclasses. The contract. stdlib-only, no provider SDKs.
-- **claude_code_driver.py** — reference adapter (Claude Code parity). Thin +
-  documented: two ops are concrete Python, three are serviced by the harness.
-- **codex_driver.py** — Phase 2 IMPLEMENTATION: OpenAI Chat Completions HTTP
-  backend. Fully wired: dispatch_worker (file injection, JSON validation with
-  retry, full-file replacement), run_command (subprocess), worker_status
-  (in-memory registry), get_tokens_spent (aggregate usage). Transport injectable
-  for offline testing.
-- **openai_transport.py** — stdlib urllib transport for OpenAI Chat Completions
-  endpoint. Injectable seam so tests feed canned responses (FakeTransport) with
-  no API key or network.
-- **openai_compatible_driver.py** — OpenAI-compatible backend (Ollama, OpenRouter, etc.).
-- **verification_policy.py** — Maps verification tier -> orchestrator tuning (validate_all_json,
-  spot_check_frac, repair_cap, require_adversarial_review).
+- **agent_driver.py** — the `AgentDriver` ABC + capability/request/result dataclasses.
+  The contract. stdlib-only, no provider SDKs.
+- **claude_code_driver.py** — reference adapter (Claude Code parity): two ops concrete
+  Python, three serviced by the harness.
+- **codex_driver.py** — Phase 2: OpenAI Chat Completions HTTP backend: dispatch_worker (file
+  injection, JSON retry), run_command (own `command_timeout_s` knob, defaults to timeout_s), worker_status, get_tokens_spent. Transport injectable.
+- **proc_util.py** — `run_shell_bounded()`: shared run_command backing (RS-A F1/F7). Timeout
+  truly bounds wall-clock: child in own group/session; on expiry the WHOLE tree is killed
+  (taskkill /T /F Windows, killpg POSIX), exit 124 promptly, partial output preserved. Never
+  subprocess.run(shell=True, timeout=) — Windows kills only cmd.exe then re-blocks on the orphaned grandchild.
+- **openai_transport.py** — stdlib urllib transport for the OpenAI endpoint; injectable
+  seam (FakeTransport in tests: no API key or network).
+- **openai_compatible_driver.py** — OpenAI-compatible backend (Ollama, OpenRouter, etc.);
+  construct-time validate_base_url; key waiver only via loopback-validated is_local.
+- **verification_policy.py** — Maps verification tier -> orchestrator tuning (validate_all_json, spot_check_frac, repair_cap, require_adversarial_review).
 - **wave_loop.py** — the wave ENGINE: preflight ownership guard, parallel build,
-  bounded repair, adversarial review, per-repo batched git ship, recovery journal.
-- **wave_bridge.py** — Phase 3: bridges AgentDriver backends to wave manifest items.
-  build_manifest_item() enriches with verificationTier + model; dispatch_item() routes
-  by capability and decides green ONLY from test exit code (not model's say-so).
-- **backend_config.py** — Per-deployment model resolution (role → model id, API key/base URL).
-- **README.md** — the abstraction, the phased roadmap, the verification thesis.
-- **../tests/test_agent_driver.py** — the contract's test suite.
-- **../tests/test_codex_driver_e2e.py** — Phase 2 end-to-end offline tests
-  (FakeTransport, red-to-green verification, retry logic, ownership enforcement)
-  + gated live test (AESOP_CODEX_LIVE env var).
-- **../tests/test_wave_bridge.py** — Phase 3 offline e2e (honest green: exit 0 only).
-  no network). Tests: manifest building, routing, fail-safe, ownership enforcement,
-  headline test (red stub + FakeTransport fix + test pass -> ok=True).
+  bounded repair, per-repo batched git ship, recovery journal. HS-2 (live seat swap):
+  `run_wave(orchestrator_backend=...)` Phase 6 routes ONE final_catch decision per
+  test-VERIFIED item through a configured orchestrator seat (schema: decisions/
+  final_catch.schema.json): merge=approve; block=verified flipped False, not shipped,
+  journal rewritten, AND written files QUARANTINED (FILE paths only — empty/dot/directory
+  pathspecs rejected with per-file error records, no cross-item destruction; tracked ->
+  git checkout, untracked deleted ONLY on clean ls-files exit-1, ambiguous = error never
+  delete; globs `:(literal)`-neutralized; backslashes normalized; outside git = honest
+  skip, surfaced in Report.blocked); escalate/undetermined/DECISION_FAILED=ship with
+  honest record (crash-only degradation — a seat outage never fabricates or blocks).
+  None/null harness backend -> "deferred", byte-identical to pre-HS-2 (no key, no
+  backend constructed). Repair stays mechanical on both seats. orchestrator_review
+  carries verdict_counts, blocked_detail {slug,reason}, seat_tokens_spent and
+  gate_status ("degraded" when all decisions failed); after decisions the ceiling is
+  re-checked with driver+seat spend (abort_reason=cost_ceiling_exceeded_after_decisions;
+  an unmetered None driver spend never crashes — seat-only spend or ledger fallback) —
+  live-seat path only. RS3-W round-2 robustness: claim gate REAL + fail-CLOSED
+  (coordination reads EventStore streams, TTL expiry, stale-lease release by slug key;
+  claim errors SKIP — never claim-less dispatch/repair); journal entries
+  fingerprint-bound + atomic (reused slug never inherits stale verified state; torn
+  writes can't corrupt resume); resumed-verified items restore filesWritten and always
+  reach a terminal shipped record (honest no_changes no-op ship — no recovery livelock);
+  dup slugs rejected at preflight; executor failures recorded, green never vacuous;
+  Windows quoting doubles only quote-preceding backslashes. RS5 claim lifecycle:
+  wave-level instance id, ttl sized to the driver command timeout (10x, 1h floor — never
+  the 300s default a real build outlives); claim HELD across build -> repair -> ship,
+  released exactly once in run_wave's finally (every exit path); repair re-dispatch and
+  ship FENCED via current_holder (lost claim = honest claim_lost abort, never
+  double-ship; try_claim retracts on error, no phantom holder). Tests: test_wave_loop_rs3.
+- **wave_bridge.py** — Phase 3: bridges AgentDriver backends to wave manifest items
+  (build_manifest_item / dispatch_item; green ONLY from test exit code, see below).
+- **backend_config.py** — HS-1 unified two-seat config: `seats.worker` + `seats.orchestrator`
+  in aesop.config.json select BOTH seats from ONE block (legacy flat block parses but is
+  INERT in the scheduler default; seats.worker wins when both present). `build_driver()` =
+  worker seat (raw-dict paths run the loader's validation); `build_orchestrator_backend()`
+  = decision seat (absent/harness/claude → null `HarnessOrchestratorBackend`;
+  openai-compatible → configured backend). Guards: base_url SSRF check incl. time-bounded
+  DNS resolution; `is_local` pinned to loopback (key waiver keys off VALIDATED is_local,
+  never URL text); `api_key_env` allowlist-primary (SECRET/TOKEN/... fragments
+  hard-reject, other key-shaped names loud NOTICE). NO seats block = byte-identical to
+  today (no key needed).
+- **context_pack.py** — build_context_pack() reads ONLY allowlisted control files
+  (STATE.md, BUILDLOG.md, tracker.json, MEMORY.md, explicit brief: under repo/conductor
+  roots) — cardinal rule 4 in code. Size-bounded, deterministic truncation, manifest.
+- **orchestrator_backend.py** — OrchestratorBackend protocol: decide_call(prompt, schema)
+  → raw text. Real impl: OpenAICompatibleOrchestratorBackend (gpt-5 temperature fallback;
+  api_key_env + is_local dummy-key; validate_base_url in __init__). HarnessOrchestratorBackend
+  = null default seat (decide_call raises: the live harness IS the orchestrator). Fake for tests.
+- **orchestrator_driver.py** — OrchestratorDriver: structured verdicts via the
+  OrchestratorBackend protocol (no AgentDriver coupling).
+- **adjudication_gate.py** — increment 3 (conservative): two-tier escalation gate — cheaper
+  challenger decides; undetermined/low-conf/disallowed-type/content-seeded-spot-check calls
+  escalate to the incumbent (frontier). Never emits an unconfident verdict as final.
+- **decisions/** — Decision type schema registry (sibling lane owns schemas; absent = optional).
+- **../tests/** — test_agent_driver (contract), test_codex_driver_e2e (offline + gated
+  live), test_wave_bridge, test_orchestrator_driver, test_adjudication_gate,
+  test_hs2_swap_proof, test_hs2_block_gate, test_wave_loop_rs3 (round-2 robustness:
+  N1/N3/N4/N5/N6/N7/N10 — all offline). Details: tests/CLAUDE.md.
 
 ## The five operations (what the wave loop needs from ANY backend)
 
-1. `probe_capabilities() -> DriverCapabilities` — honest self-report (parallel?
-   filesystem? shell? structured output? worktree? cost tracking? accuracy? →
-   recommended verification tier). Read once; everything keys off it.
-2. `dispatch_worker(request) -> WorkerResult` — spawn ONE isolated worker over a
-   prompt + owned_files + workdir; the worker may read/write files, run a shell
-   command, and return a **structured** result (extent reported by the probe).
-3. `worker_status(worker_id) -> WorkerStatus` — liveness / stall detection for
-   the watchdog.
-4. `run_command(command, cwd, shell) -> CommandResult` — ORCHESTRATOR-side
-   command execution (tests, git, verification). Distinct from a worker shell.
-5. `resolve_model(role) -> str` — map an abstract role (`worker`/`setup`/
-   `verify`) to a concrete backend model id.
-
-Optional (non-abstract): `get_tokens_spent()`.
+1. `probe_capabilities() -> DriverCapabilities` — honest self-report (parallel? fs? shell? structured? worktree? cost? accuracy? → verification tier). Read once; everything keys off it.
+2. `dispatch_worker(request) -> WorkerResult` — spawn ONE isolated worker (prompt + owned_files + workdir); may read/write/run + return a **structured** result (extent per probe).
+3. `worker_status(worker_id) -> WorkerStatus` — liveness / stall detection for the watchdog.
+4. `run_command(command, cwd, shell) -> CommandResult` — ORCHESTRATOR-side exec (tests, git, verify). Distinct from a worker shell.
+5. `resolve_model(role) -> str` — map `worker`/`setup`/`verify` to a concrete backend model id. Optional (non-abstract): `get_tokens_spent()`.
 
 ## Invariants
 
-- The wave loop calls **only** `AgentDriver` methods — never `agent()`,
-  `parallel()`, Read/Write/Bash tools, or `budget.spent()` directly. That is
-  the seam.
-- `probe_capabilities()` must be **honest**. Defaults are conservative (no
-  native abilities, accuracy 0.0, tier 4) — optimism is opt-in, never default.
-- **Weaker workers → higher verification tier.** Lower `tool_use_accuracy`
-  raises `recommended_verification_tier`. Cheaper/weaker backends RAISE the
-  orchestrator's burden; they do not lower it.
-- Unknown roles in `resolve_model()` fall back to the worker model — a mis-typed
-  role can never silently escalate cost.
-- stdlib-only (`abc`, `dataclasses`, `typing`, `subprocess`), ASCII-only,
-  Windows + Linux safe. Concrete adapters own any provider SDK, not this layer.
-
-## Per-backend capability matrix (as encoded)
-
-| Capability            | claude-code  | codex (Phase 2)       |
-|-----------------------|:------------:|:---------------------:|
-| parallel_dispatch     | yes          | no (ext loop)         |
-| worker filesystem     | yes          | no (orch injects)      |
-| worker shell          | yes          | no (orch runs)         |
-| structured_output     | yes (~perfect)| yes (JSON schema)      |
-| worktree_isolation    | yes          | no (temp-dir)         |
-| native_cost_tracking  | yes          | yes (usage metadata)   |
-| tool_use_accuracy     | ~0.99        | ~0.92                 |
-| verification_tier     | 1            | 2                     |
-
-## Phase 2 Codex Implementation Details
+- The wave loop calls **only** `AgentDriver` methods — never `agent()`, `parallel()`,
+  Read/Write/Bash tools, or `budget.spent()` directly. That is the seam.
+- The orchestrator calls **only** `OrchestratorDriver.decide()`. Context packs are allowlist-only
+  (STATE.md, BUILDLOG.md, tracker.json, MEMORY.md, explicit brief); arbitrary reads raise
+  `ContextPackViolation` — **cardinal rule 4 in code**.
+- `probe_capabilities()` must be **honest**. Defaults conservative (no native abilities, accuracy 0.0, tier 4) — optimism is opt-in, never default.
+- **Weaker workers → higher verification tier.** Lower `tool_use_accuracy` raises `recommended_verification_tier`: cheaper backends RAISE the orchestrator's burden.
+- Unknown roles in `resolve_model()` fall back to the worker model — a mis-typed role can never silently escalate cost.
+- **Fail-safe verdicts**: `OrchestratorDriver.decide()` returns DECISION_FAILED after retries exhausted; never fabricates a passing verdict (never-green principle).
+- **AdjudicationGate safety invariant** (increment 3): the final verdict is EITHER a confident
+  challenger verdict OR the incumbent's; undetermined/DECISION_FAILED/low-confidence is NEVER final.
+- stdlib-only, ASCII-only, Windows + Linux safe. Concrete adapters own any provider SDK, not this layer.
+
+## Phase 2 (Codex) + Phase 3 (Bridge) Implementation Details
+
+Capability matrix (as encoded): claude-code = parallel, worker fs/shell, worktree isolation,
+native cost, accuracy ~0.99, tier 1; codex = none natively (orchestrator injects/runs; temp-dir;
+usage-metadata cost), accuracy ~0.92, tier 2. NOTE: ClaudeCodeDriver.get_tokens_spent() is None BY CONTRACT (cost_ceiling ledger fallback).
 
 Codex driver (Tier 2): injects file contents into prompt, calls OpenAI Chat Completions via injectable transport, validates JSON with bounded retry, enforces ownership. CRITICAL: Green = exit 0 only. Verification policy: tier 2 -> {validate_all_json:True, spot_check_frac:0.50, repair_cap:2, require_adversarial_review:True}. **P1 Security**: Default model map uses gpt-4o-mini (worker, supports json_schema); init-time guard rejects models lacking json_schema support unless `allow_unverified_models=True` (P1 gate: prevent gpt-3.5-turbo silent failures).
 
-## Phase 3 Bridge Implementation Details
-
-Connects AgentDriver backends to wave-flat-dispatch manifest items; verification
-tier is driven by backend capability, not config.
-
-**build_manifest_item(driver, item) -> dict**: enriches a backlog item with model
-(driver.resolve_model), verificationTier (probe), and the four policy knobs from
-verification_policy(caps) — RESOLVED ONCE, carried as literal manifest fields so the
-template cannot recompute/drift; tier-1/Claude path stays byte-identical (repairCap=1,
-requireAdversarialReview=false, spotCheckFrac=0.10, validateAllJson=false).
-
-**dispatch_item(driver, item) -> dict**:
-- Routes by worker_filesystem_access: True→{route:'harness'}; False→orchestrator-managed
-  (dispatch_worker + run_command test). Returns {route, ok, testExit, filesWritten, verified, ...}.
-- HONESTY: Green (ok=True) ONLY on test exit 0; never from model's done:true. No testCmd
-  → unverified (ok=False, verified=False, reason='no_test_command'): "no test" ≠ "verified."
-- Fail-safe: exception → ok=False, verified=False. Ownership at driver level.
-
-**Tests**: prove a non-Claude backend (Codex + FakeTransport) takes a RED unittest
-stub, applies a fix, runs the test, and returns ok=True ONLY because the test passed
-(exit 0). All offline, no API key, no network.
+**build_manifest_item(driver, item)**: enriches a backlog item with model, verificationTier,
+and the four verification_policy knobs — resolved ONCE as literal manifest fields (no
+recompute drift); Claude tier-1 path stays byte-identical. **dispatch_item(driver, item)**:
+routes by worker_filesystem_access. HONESTY: ok=True ONLY on test exit 0, never from the
+model's done:true; no testCmd -> ok/verified=False (reason='no_test_command'); exception ->
+fail-safe False. Ownership enforced at driver level. Offline tests prove Codex+FakeTransport
+takes a RED stub to green via real test exit 0.
 
 ## Wave Scheduler (WS3a Pilot) + GATE-1 Handoff Kit
 
 **wave_scheduler.py** — single-cycle backlog orchestration: intake up to N file-disjoint todo items from tracker.json (empty/missing ownsFiles REJECTED; paths normalized posix+casefold-on-Windows before overlap checks; required fields pre-validated) -> manifest via build_manifest_item (model + verificationTier from driver.probe) -> HALT + cost-ceiling gates (fail-CLOSED: module import failure or check exception = abort with honest Report, phase=gate_unavailable) -> run_wave (recovery journal + git ship) -> STOP before merge; Report JSON with per-item observability (GATE-1). After ship, selected items atomically marked in_progress in tracker (temp+os.replace; dry-run never mutates) so a second run cannot double-dispatch.
 
-**CLI** (GATE-1): `python driver/wave_scheduler.py --tracker <path> --max-items N --dry-run|--execute --driver claude|codex` (default: claude). For codex+execute, requires OPENAI_API_KEY env var; dry-run works without it.
-
-**Tests** (35+): disjoint/normalization/rejection, gate fail-closed, dry-run, GATE-1 per-item/driver/ceiling/codex tests; module-tmpdir hygiene; all TestCase.
+**CLI** (HS-1): `python driver/wave_scheduler.py --tracker <path> --max-items N --dry-run|--execute [--driver claude|codex] [--config <path>]`. Default: worker seat from aesop.config.json seats.worker ONLY (no seats block → claude; a bare legacy flat block stays inert — migrate to seats.worker) — the seats path also reaches openai-compatible; `--driver` OVERRIDES the config. Hosted seat + --execute requires the seat's api_key_env (is_local: none); dry-run never needs a key. HS-2: seats.orchestrator resolved by `resolve_orchestrator_backend()` (absent/harness/claude → None = live harness stays orchestrator; openai-compatible → live backend, same --execute key gate) and passed into run_wave; Report JSON shape is IDENTICAL either way (swap transparency — seat activity lives in run_wave's result: orchestrator_review + per-item final_catch, plus a stderr notice).
 
-**Invariants**: stdlib-only, ASCII, Windows+Linux safe (list-form subprocess); manifest items carry resolved policy knobs from verification_policy (no recompute drift); merge stays manual in the pilot.
+**Tests** (35+): disjoint/normalization/rejection, gate fail-closed, dry-run, GATE-1 per-item/driver/ceiling/codex tests; module-tmpdir hygiene; all TestCase. **Invariants**: stdlib-only, ASCII, Windows+Linux safe (list-form subprocess); manifest items carry resolved policy knobs from verification_policy (no recompute drift); merge stays manual in the pilot.
 
 ### REPORT-CONTRACT (GATE-1 Orchestrator Handoff)
 
-The scheduler emits a Report JSON consumed by the orchestrator to decide merge eligibility:
-```
-{
-  "phase": "dispatch"|"intake"|"halt"|"ceiling"|"gate_unavailable"|"manifest",
-  "wave_id": "<uuid>",
-  "items_selected": ["id1", "id2"],  // IDs selected for this wave
-  "items_shipped": [
-    { "slug": "feat/x", "backend": "claude-code|codex", "tier": 1|2|3|4, "verified": true|false (false = NOT PROVEN, not necessarily failed; tier null = no build record), "testExit": 0|1|null },
-    ...
-  ],
-  "merged": false, "tracker_update_attempted": true|absent, "tracker_unmapped_slugs": [..]|absent (LOUD -> success false),  // pilot always false (manual merge)
-  "success": true|false,
-  "timestamp": "<ISO8601>",
-  "branch": "<branch_name>",  // optional; set when ship succeeds
-  "sha": "<git_sha>",  // optional; set when ship succeeds
-  "halt_reason": "...",  // optional; set if halted
-  "ceiling_reason": "...",  // optional; ceiling exceeded before dispatch (abort-before-dispatch only)
-  "error": "..."  // optional; unexpected error
-}
-```
-Ceiling semantics: checked BEFORE run_wave dispatch (phase=ceiling, ceiling_reason populated). Mid-wave ceiling trips are run_wave's responsibility. items_shipped[] carries per-item observability: slug, backend (driver name), tier (verificationTier), verified (from test exit 0), testExit (test command exit code or null if not run).
+Scheduler emits a Report JSON the orchestrator uses for merge eligibility. Fields: phase
+(dispatch|intake|halt|ceiling|gate_unavailable|manifest), wave_id, items_selected[],
+items_shipped[] ({slug, backend, tier 1-4|null, verified — test-exit-0-only, false = NOT
+PROVEN, testExit}), merged (pilot: always false, manual merge), success, timestamp,
+branch/sha (set on ship), halt_reason/ceiling_reason/error (optional). Live seat ONLY
+(HS-2 block gate; default shape unchanged): blocked[] ({slug, reason, quarantine:
+clean|errors|skipped|unknown, + quarantine_errors / quarantine_skipped_reason —
+a failed quarantine means refused code may still be in the tree}; item also gets
+TERMINAL tracker status "blocked" — never re-selected) + orchestrator_gate {seat, model,
+decisions, verdict_counts, blocked, decision_failed, seat_tokens_spent, status
+active|degraded|no_decisions}; any block -> success false. Ceiling is checked
+BEFORE run_wave dispatch (phase=ceiling); mid-wave trips are run_wave's responsibility.
+Tracker sync: LOUD on unmapped slugs (tracker_unmapped_slugs -> success false). Full JSON
+shape lives in wave_scheduler.py's module docstring.
 
 ## Status
 
-- **Phase 1**: shipped. Interface + Claude reference adapter + contract tests.
-- **Phase 2**: shipped. Codex OpenAI Chat Completions implementation. Offline tests GREEN.
-- **Phase 3**: shipped. Wave bridge: driver → manifest, orchestrator-side dispatch.
-  Proves non-Claude backends drive items end-to-end with honest green (test exit 0 only).
-- **Wave Scheduler (WS3a) + GATE-1**: shipped. Single-cycle orchestration: intake → manifest → dispatch → report (manual merge). Per-item observability, driver injection (--driver claude|codex), ceiling semantics documented.
+Phases 1-3 + Wave Scheduler (WS3a/GATE-1) + HS-1 + HS-2 seat swap shipped (proof:
+bench/results/hs2-swap-proof-2026-07-25.md; merge manual in pilot) + RS3-W round-2
+robustness + RS5 claim lifecycle (see wave_loop.py bullet).

package/driver/README.md

@@ -225,7 +225,45 @@ switch backends without changing code. The configuration is **offline-safe**:
 building a driver requires no API key; keys are read from environment variables
 at call time during live dispatch.
 
-**Configuration schema** (backend block):
+**Unified two-seat config (0.4.0, HS-1)** — one namespaced block selects BOTH
+seats: `seats.worker` (the coding agents; same fields as the legacy block
+below, wins over it when both are present) and `seats.orchestrator` (the
+decision seat; `"harness"` = the live Claude Code session, the default;
+`"openai-compatible"` routes `OrchestratorDriver.decide()` to an API model
+with `model`/`base_url`/`api_key_env`/`is_local`):
+
+```json
+{
+  "seats": {
+    "worker": { "backend": "claude" },
+    "orchestrator": { "backend": "openai-compatible", "model": "gpt-4o-mini" }
+  }
+}
+```
+
+`build_driver(load_backend_config())` builds the worker seat;
+`build_orchestrator_backend(load_backend_config())` builds the orchestrator
+seat (returning the null `HarnessOrchestratorBackend` -- whose `decide_call`
+raises -- when the seat is absent or `harness`/`claude`). With **no** `seats`
+block, behavior is byte-identical to today: Claude Code worker + harness
+orchestrator, no OpenAI backend constructed, no key required -- and a bare
+legacy flat block (below) stays INERT in `wave_scheduler`'s default path
+(it was dead config before 0.4.0; migrate it to `seats.worker` to opt in).
+Consumers: `wave_scheduler.py` (worker seat from `seats.worker` only;
+`--driver` overrides) and the shadow adjudication tools (orchestrator seat;
+`--model` overrides).
+
+Guardrails: `base_url` is SSRF-checked (scheme, IP literals, AND
+DNS-resolved addresses; TTL-0 rebinding residual documented in
+`validate_base_url`), `is_local: true` requires a loopback `base_url`
+(localhost/127.0.0.1/::1 -- it disables the key requirement), and
+`api_key_env` must be an LLM-key-shaped name (`*_KEY`/`*_API_KEY`, no
+SECRET/TOKEN/... fragments) so a config cannot exfiltrate arbitrary env
+secrets as Bearer tokens.
+
+**Configuration schema** (legacy/flat worker block; parses + validates, honored
+by direct `build_driver()` callers, but inert in the scheduler default -- see
+above):
 ```json
 {
   "backend": "claude" | "codex" | "openai-compatible",
@@ -274,7 +312,7 @@ print(describe_backend(config))
 ```json
 {
   "backend": "codex",
-  "model": "gpt-3.5-turbo"
+  "model": "gpt-4o-mini"
 }
 ```
 - Requires `OPENAI_API_KEY` environment variable set