@staix/agent-hub 0.12.10 → 0.12.12

package/CHANGELOG.md

@@ -4,6 +4,21 @@ Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the
 
 ## Unreleased
 
+## 0.12.12
+
+- Restore owned native cohorts when a study supervisor is interrupted: bounded orderly cancellation with signal-time verified child identity, restoration settled only when the marker and ledger agree, a bounded identity-checked fallback with explicit restoration-failure records, and the interrupted phase, cause and restoration status persisted before the incomplete exit. Grading never starts after interrupted generation, and no resume, root reuse or retry is added (#168).
+- Diagnose native sandbox probe failures with a bounded structured outcome: a fixed-enum, count-only probe trace bound to peer, session and setup window explains why the protected-file evidence predicate was not satisfied (agent behavior, tool event coverage or normalization, with unresolved causes explicitly unknown), exposed as the unavailable setup reason in serialized readiness. The #138 and #150 evidence predicates are unchanged and the safe view cannot carry paths, arguments, answers or arbitrary strings (#169).
+- Persist scalar progress for long native studies separately from the verified milestone phase: command kind, repeat ordinal, retained/planned committed-record counts, updated timestamp and verified child identity, with a bounded `status` command that reports stale, crashed, pid-reused and unreadable observations as explicit unknown/stalled and never advances a milestone from progress (#170).
+- Export an audited, versioned per-arm study summary (JSON, optional CSV) after the final audit: planned/scored/passed/unavailable/missing counts reconciled with the audited cells, setup and active medians with valid-completed and common-pair denominators, and native usage, relay usage and provider availability kept distinct. The summary is hash-bound to the manifest, audit, grades and ledger, refuses inconsistent bindings or unsealed studies, and is built allowlist-only so private row content cannot enter it (#171).
+
+## 0.12.11
+
+- End native benchmark attempts on terminal Pi or Qwen failures, retain the first failure cause at the final deadline tick, and gate peer-failure patches on active-window tree preservation (#160).
+- Validate ACP native counters without treating context occupancy as consumed tokens; record independent request usage and provider coverage with request-bound primary/fallback linkage (#161, #162).
+- Add `mlx.enabled=false` to omit local inference while preserving remote `hub/auto` fast/coding selection, with explicit launch/recovery conflict diagnostics (#163).
+- Separate exact native-response, primary-route and fallback verdicts in Pi smoke; add optional `--require-primary` (#164).
+- Add a durable, version-bound native study supervisor and scalar-only evidence audit; keep generation ahead of evaluation, refuse reused roots and preserve private artifacts (#165).
+
 ## 0.12.10
 
 - Preserve each Pi/Qwen peer's observed sandbox-probe result in v3 readiness; failed or missing native probes never synthesize a denial (#150).

package/README.md

@@ -182,3 +182,22 @@ Before upgrading an older hub, inspect the plan with the matching CLI.
 Incompatible or unverified processes are shown explicitly and are never killed by
 PID-name matching. See the [operations guide](docs/operations.md) and the
 [multi-project specification](docs/specs/2026-09-19-multi-project-design.md).
+
+## Agent instructions
+
+`AGENTS.md` holds what every agent session loads: commands, conventions,
+architecture and the rules that hold anywhere in the code. Rules that hold in one
+area (benchmarks, adapters, the bus, the local worker, models, the task board,
+budget, the daemon and recovery, tests) live in [`docs/agent-notes/`](docs/agent-notes/),
+and `AGENTS.md` names the paths that call for each note, so a session loads only
+the notes for what it edits (#158). Background behind some of those rules:
+
+- Benchmark trust entry: the review rounds of #115 kept finding paths that broke
+  the runner's settlement of the Claude trust entry.
+- Reply addressing: leaving `to` empty fanned a reply out to every peer, which is
+  what made one directed question cost every agent a turn.
+- Bun test hang: the stacks of two local hangs show a test timeout starting the next
+  test inside `Bun.spawnSync`'s own event loop (#115,
+  `docs/verification/2026-10-03-0.12.6.md`); minimal reproductions did not hang, so
+  the full trigger is not pinned down. On Bun 1.4.2 the next test still starts there
+  (#121, checked directly); the spin was not reproduced on demand on either version.

package/docs/agent-notes/adapters.md

@@ -0,0 +1,15 @@
+# Native adapters and spawned agents
+
+Scope: the Codex, ACP and Pi adapters and the Pi extension (turn `generation` and `activity` events), peer turn state, approvals, and the agent processes the hub spawns and stops. Read before editing `src/adapters/`, `src/pi/`, `src/hub/peers.ts`, `src/hub/child-process.ts`, `src/hub/lifecycle.ts` (shutdown deadline), `src/memory/capture.ts` (session end) or the process-tree stop in `scripts/benchmarks/teardown.ts`, or before adding a native peer.
+
+- Codex: the adapter never sends its own `initialize`. It is a proxy; hub requests use negative ids and their responses must not reach the TUI.
+- Codex 0.154.0 `agentMessage` items carry `text` and `phase` (not `content[]`); only the last non-`commentary` message of a turn is shared.
+- Approval titles are agent-written text shown to a person: the daemon escapes control characters, and write/edit/bash show what will be written or run.
+- An ACP permission request may carry no `rawInput` (Kimi 2.0.1): the arguments were on the earlier `tool_call` update, which `acp.ts` remembers by `toolCallId`. Kimi 2.1.1 sends no `rawInput` before the answer at all: the argument JSON streams as `content` text on `tool_call_update`, and only complete JSON counts. A payload that still cannot be resolved, or is too long to show whole (marked `[cut, N chars]`), withholds its `allow_always` option - never render a bare tool name as if it described the call.
+- Auto-approval covers the hub's own tools by exact `mcp__agent-hub__<name>` title and only ever picks `allow_once`. Identity comes from the permission request title or, when an agent titles the request with the argument JSON (Qwen), from the announced `tool_call` title bound to the call id and resolved against the session's configured MCP servers, never from payload text, a prefix or an unrelated display title. Never widen it to a prefix, and never set Kimi's session mode to `auto` or `yolo` instead: those approve everything.
+- Every agent the hub spawns (the Codex app-server, ACP agents such as Kimi, Pi) runs in its own process group and is stopped as one (`stopOwnedProcess(proc, { group: true })`, `trackGroup` after spawn): `codex` is a node launcher, and mid-turn its native app-server does not exit on SIGTERM within the grace period, so a SIGKILL to the launcher alone left the app-server running under init and holding the daemon alive (#113, #115). A new adapter that spawns an agent does the same.
+- To stop a process tree, freeze it (SIGSTOP) before reading what it contains, then SIGKILL, and call it done only when the table shows none of it (with no table at all, the stop can only ask the group itself, which cannot see groups below it). A process a read after the freeze shows for the first time is frozen and read again before anything is killed. A snapshot taken while the tree runs misses what it starts next: three review rounds of #113 found such a gap (groups of its own, an unreadable first read, a child started during the grace period).
+- Work that must survive `ahub kill` (claude-mem `session-end`) is awaited in `stop()`; fire-and-forget dies with the process.
+- A peer must set `busy` synchronously inside `deliver()`, otherwise the bus drains the next envelope into a running turn (Kimi answers `turn.agent_busy`).
+- A watchdog-cancelled turn still reports later. Anything a turn does on completion must check it is still the current turn (`turn` generation in `acp.ts`, `activeTurns` in `codex-appserver.ts`). A rejected prompt or abnormal prompt end reports through the adapter's `onTurnFailure` (same shape in `acp.ts` and `pi.ts`), even when ACP streamed partial text; a stale cancelled turn never reports it.
+- Native owner teardown must handle a lost shutdown acknowledgement using verified process identity. Pending launches must be revocable, and active tools/streaming output must count as watchdog activity.

package/docs/agent-notes/benchmarks.md

@@ -0,0 +1,8 @@
+# Benchmark runners
+
+Scope: the CooperBench runners, their fixtures, teardown and recovery. Read before editing `scripts/benchmarks/` or `test/benchmarks/`, or before running a benchmark.
+
+- Never auto-register Orca benchmark fixtures, including ad-hoc or copied runners; require an explicit pre-existing repo and exact worktree registration, and preserve fixture directories, Git state and benchmark evidence during cleanup.
+- The manifest-v3 Pi/Qwen CooperBench driver (`scripts/benchmarks/native-pi-qwen.ts`, #140) is headless and never touches Orca. Its pinned build is the effective one: each native's `--version` runs under the final isolation environment (Qwen inside its seatbelt profile with `QWEN_HOME` set; the PATH bootstrap lies about the managed build under isolation). Its protected-file probe counts only with structured denial evidence (a guard denial or a failed read tool call with EPERM/EACCES), never a model-written marker alone, and each peer's serialized `sandboxProbe` readiness reports only that peer's observed probe outcome (`denied` with its evidence, else explicit `failed`/`unknown`; #150), never a synthesized denial. Served-model evidence is each request's own journaled `RelayRequestRecord` (#139): a heartbeat-only or cancelled-before-identification record certifies nothing, and every identified record is evidence whatever its outcome; a confirmed mismatch on a request cancelled after identification fails the model gate. A backend's last-served label is never a request's evidence. Qwen's peer tool approval is the exact canonical `mcp__pilot-peer-bus__hub_send` through the adapter's #138 binding, never a title-prefix workaround.
+- The benchmark run's restoration state: `restoration.json` says `restored: false` from before the runner locks anything until it writes its outcome, and the recovery trusts `restored: true` only when `restoration-ledger.json` agrees (`unrestored` in `scripts/benchmarks/teardown.ts`). A run directory that is not restored is never reused: its locked modes would become the originals. A ledger from before 0.12.5 (no runner identity) owes its locks but, when `restoration.json` says `restored: true` or names a runner, keeps its trust entry as it was then (`owed`; with no `restoration.json`, its runner did not finish and the entry is owed too): the reuse check and the recovery read both through these two functions, never on their own (#120).
+- The benchmark runner's Claude trust entry: a write still `pending` in the runner's own process never landed, so it is `not_written` on every path (contained or not, its temp file removed or left), and neither the runner nor the recovery touches an entry then. Only a dead runner's `pending` leaves that question to the recovery, which takes back only an entry exactly as the runner would have written it, and none while the runner's temp file is still there (the rename never happened). `changed_concurrently` is the user's entry and is never taken back. The runner's settlement is `settleTrust` in `scripts/benchmarks/teardown.ts`, tested as a table: change it there, never inline.

package/docs/agent-notes/budget.md

@@ -0,0 +1,10 @@
+# Budget, pause and handoff
+
+Scope: quota readings, pause, handoff and resume, and the status line tee. Read before editing `src/hub/budget.ts`, `src/cli/statusline-tee.ts`, `src/hub/bus.ts`, `src/hub/delivery-journal.ts` or `src/hub/restart.ts` (pause persistence).
+
+- Budget: checkpoint first, pause second (a paused peer receives nothing). A handoff that fails is left unmarked so the next tick or hub run retries it; never record it as done.
+- A handoff needs somebody to hand over to: `canHandOff` is false right after a restart, when no peer is attached yet, and the handoff waits for a later tick instead of stripping tasks of their owner.
+- A reading has its own timestamp. Numbers that arrive through a file (`claude-usage.json`) carry the file's `at`; a window whose `resetsAt` has passed says nothing any more.
+- On resume the notice is published before the peer is released, so it leads the first delivery.
+- The coordinator only lifts its own pauses: `manualPaused` in the daemon keeps a `ahub pause` in place, and `ahub resume` refuses while a budget record is open.
+- The status line tee must never fail or slow the render: no throw, original command run with the same stdin, 5 s cap.

package/docs/agent-notes/bus.md

@@ -0,0 +1,13 @@
+# Bus, digests and replies
+
+Scope: delivery, digests and condensation, reply addressing, priority and limits. Read before editing `src/hub/bus.ts`, `src/hub/envelope.ts`, `src/hub/limits.ts`, `src/hub/delivery-journal.ts`, `src/hub/inference.ts` (digest condensation), or how an adapter addresses a reply or sets its priority.
+
+- A failed digest is retried one envelope at a time, so a poison envelope cannot take its neighbours down with it.
+- An `important` envelope being steered is not in the queue while the steer is in flight; queue it first and an idle transition delivers it twice.
+- `replyParent()` decides what a reply answers (highest hop, never the `hub` preface). Use it for deliveries and steers alike, or the hop cap can be reset.
+- What a peer is handed (`out`) and what it stands for (`originals`) differ once a delivery is condensed: the bus keeps both, registers `out` so `reply_to` resolves, puts the originals back on any failure (a thrown `deliver` or a later `onFailed`), and counts no attempt when the peer merely got busy while the delivery was prepared. A delivery with an `important` envelope is never condensed.
+- A condensed digest is sent by `digest`, not `hub`: `replyParent()` skips `hub` items, and a reply to a digest must keep the highest hop of what it replaced. On a failed delivery the bus puts back the originals, never the digest.
+- Limits admit what is sent: the envelope `newEnvelope` builds (a reply inherits its parent's sender, `digest` resolves to the originals, `capPriority` applies), never the raw `to` and priority. Admit first and build later, and implicit replies all count as broadcasts.
+- A reply is addressed, never broadcast. An adapter that answers a delivery passes `to: replyAudience(envs)`; anything else with an `inReplyTo` inherits that envelope's sender. Leaving `to` empty fans the message out to every peer.
+- `digest` is not a peer: addressing a reply at the envelopes the peer was handed sends it nowhere once a delivery was condensed. The bus resolves `digest` back through `lastDelivery.originals`; anything else that reads a reply's `to` has to do the same.
+- A hub-native peer (Pi, the local worker) does not get to call its own message `important`: `capPriority` caps it unless the delivery it answers held an `important` envelope addressed to it. Check the delivery, not `replyParent`, which ties on hop and takes the later item. Do not bypass it by setting `priority` in the adapter.

package/docs/agent-notes/daemon.md

@@ -0,0 +1,13 @@
+# Daemon, control protocol and recovery
+
+Scope: the control WS and its protocol, state files, the Claude channel's reconnect, `ahub setup`, git snapshots, upgrade and recovery. Read before editing `src/hub/daemon.ts`, `src/hub/control-client.ts`, `src/adapters/claude-channel.ts`, `src/hub/restart.ts`, `src/hub/recovery-store.ts`, `src/hub/snapshots.ts`, `src/hub/manager.ts`, `src/hub/lifecycle.ts`, `src/hub/crash.ts`, `src/cli/setup.ts`, `src/cli/upgrade*.ts`, `src/cli/terminal-recovery.ts`, `src/cli/recovery-package.ts` or `src/cli/facts-hook.ts`, or before adding a native peer.
+
+- The plugin bundle is installed apart from the daemon. Any change to a control WS message shape bumps `PROTOCOL` in `control-client.ts`.
+- `ahub setup` reads Claude Code's state from `--json` listings and takes one step at a time, re-reading after each; never match paths or names by substring.
+- A copy of the git index keeps the original's mtime (`snapshot()`): git's racy-entry check compares entries with the index file's time in whole seconds, and a fresh copy makes a same-size edit look clean.
+- State files that clients read (`status.json`, `control-token`) are written after the port is bound, and `status.json` via temp file + rename.
+- The channel's reconnect loop stops on closes a retry cannot fix (`TERMINAL_CLOSES` in `claude-channel.ts`); a new daemon close code that means "do not come back" belongs there, or two clients fight over it forever.
+- Close 4000 is the one close that ends on its own, so it is not in `TERMINAL_CLOSES`: the session stands by and reconnects only once `status.json` reports the peer offline and not `claiming`. Reconnecting blind would evict whoever holds the id now, and the two would trade it forever. `claim()` happens at hello and `attach()` only after the preface, so the peer reads as offline in between: the daemon writes the status file at the claim and the flag covers that window.
+- Adding a native peer requires testing the command emitted by the actual recovery driver, not only its inspection or launch helpers. Never let a generic non-Codex branch treat a new peer as Claude.
+- Cross-version recovery must use the authenticated source protocol for prepare/commit/abort and the target protocol after startup. Prove the transition against a real prior release before claiming compatibility.
+- A zero-turn Claude session has no transcript, so it can never be resumed: every identity gate that compares session ids (restore, coordinator verify, daemon readiness) must tolerate a fresh session while the transcript is absent and stay strict the moment one exists. The commit snapshot records `sessionPersisted` for the restored daemon, and snapshots too old to have it are re-derived from disk. Never treat "session id changed" as proof of a lost conversation without checking the transcript first.

package/docs/agent-notes/local-worker.md

@@ -0,0 +1,12 @@
+# Local worker and sandbox
+
+Scope: the hub-native local worker, its tools, path guard, denylist and seatbelt sandbox. Read before editing `src/adapters/local-worker.ts`, `src/local/`, `src/memory/capture.ts` or `src/hub/facts.ts` (both read the denylist).
+
+- Nothing the local worker executes may run outside `sandboxedExec`; a new tool that spawns a process goes through it, and a tool that touches a path goes through `guardPath`.
+- The sandbox denies home reads by default (toolchain dirs, the project and its real git dir excepted) and all network, loopback included: claude-mem and the Codex app-server listen on loopback without auth. Tests that bind a local port therefore fail when the worker runs them, also with `local.bash_network: true` (the egress proxy keeps loopback closed, and the proxy variables send a test's plain-HTTP `fetch` to the proxy, which refuses it); that is the intended trade-off, and `"direct"` is the switch until 0.13.0 removes it.
+- SBPL strings go through `sbplString` (the plain `"..."` form). In the raw `#"..."` form a backslash escapes nothing, so a `"` in a path ends the literal and the whole profile fails to parse.
+- One denylist, `src/local/deny.ts`: the path guard, the seatbelt profile and the memory filter all read it. Seatbelt sees absolute paths, so `local.deny` entries are anchored under the project root (a bare `private/` once denied all of `/private/var`).
+- `guardPath` walks with `lstat`: `existsSync` follows symlinks, so a dangling link looked like a new file and the write landed at its target.
+- git arguments never pass through `guardPath`; `gitArgsProblem` refuses absolute paths, `..`, `--no-index` and denylisted `rev:path` forms.
+- A worker turn builds its messages in a local array and joins the history only as a whole. Never push to `history` mid-turn: one tool call without its result poisons every later request.
+- After a tool with side effects ran, a failed turn is reported, never redelivered.

package/docs/agent-notes/models.md

@@ -0,0 +1,9 @@
+# Model relay, inference and gateway
+
+Scope: the model relay and its journal, the hub's own inference and its slots, OmniRoute and Switchyard. Read before editing `src/models/`, `src/hub/inference.ts`, `src/omniroute/` or `src/switchyard/`.
+
+- The model relay journals per-request identity (`RelayRequestRecord`): a request's served model comes only from its own gateway header, its own generation SSE event (#137 heartbeat classification), or the locally validated MLX configuration. A backend's mutable last-served label is never a request's evidence, HTTP 200 plus the requested alias identifies nothing, and a request cancelled before identification stays explicitly unidentified (`identified: false`, `outcome: "cancelled"`). Journal records carry no prompts, tools, keys or Access headers.
+- Inference is optional and fail-open: it returns its input or `undefined` on any failure and backs off, so a delivery never waits on a dead model twice. Its output is only ever capped text or a value checked against a closed list.
+- Secrets stay inside `OmniRoute`: never put the key or Access values in a log line, an error message, a return value or the generated Switchyard file (the key goes by env var name).
+- Switchyard's docs drift from the released binary. Any change to `switchyardToml` is checked with the real `switchyard-server --dry-run`, not only the stand-in in `test/fakes/`.
+- Shared inference slots must recover after a hub process dies, without evicting a live owner. Cancellation has to reach slot acquisition from the relay caller, not just exist in the helper signature.

package/docs/agent-notes/tasks.md

@@ -0,0 +1,7 @@
+# Task board and hub tools
+
+Scope: the task flow, assignment, the state machine and the hub's MCP tools. Read before editing `src/hub/tasks.ts`, `src/hub/board.ts`, `src/hub/routing.ts` or `src/hub/hub-tools.ts`.
+
+- Tool callers are models: MCP `inputSchema` is not enforced on the way in. Normalize at the boundary (`cleanRefs`) before anything reaches the board, and never throw after a board write.
+- `assign()` never defaults to the task's current owner, or a decline can only come back to the decliner.
+- The state machine allows `in_progress -> approved` only for classes without a reviewer; `review()` checks `in_review` itself.

package/docs/agent-notes/tests.md

@@ -0,0 +1,7 @@
+# Tests
+
+Scope: tests, fakes and the test gate. Read before adding or changing a test or fake under `test/`, or editing `scripts/check.sh` or `scripts/hang-watch.sh`.
+
+- Tests that are not about batching build the bus with `batchMs: 0`; with the default 15 s window a lone status envelope looks like a lost message.
+- In Bun 1.3.14 a test timeout that fires while `Bun.spawnSync` runs can start the next test inside spawnSync's own event loop, where another spawnSync then spins at full CPU for good (trigger not pinned down; see README). Bun 1.4.2 still runs the next test inside the outer spawnSync's event loop. `scripts/check.sh` runs tests with a 20 s timeout and under `scripts/hang-watch.sh`; a test that spawns and reads the process table gets a timeout of its own.
+- A child process gets a scrubbed environment, so test knobs for fakes travel in a wrapper script, not in `process.env`.

package/docs/cooperbench.md

@@ -95,6 +95,8 @@ The v3 driver supplies a trusted `expectedServedModels` map to the relay: `fixed
 
 Served-model evidence is per request, from the relay's journaled `RelayRequestRecord` (#139), not from a response wrapper: a completed request that was never identified fails the attempt's model gate (a heartbeat-only stream identifies nothing), an observed mismatch flags it, and a request cancelled before identification stays explicitly unidentified and never certifies another request. Qwen's peer tool is approved through the adapter's shipped tool-identity binding (#138): the announced `hub_send (pilot-peer-bus MCP Server)` title resolves to the canonical `mcp__pilot-peer-bus__hub_send`, the only name on the exact whitelist. The joint arm's MCP peer bus is the versioned `scripts/benchmarks/peer-bus-mcp.py`, pinned with the driver in `prepared.json` and `cohort.json` next to the candidate source pins (`src/adapters/pi.ts`, `src/adapters/acp.ts`, `src/models/relay.ts`).
 
+A required peer's terminal active-turn failure ends the whole attempt at once (#160), instead of waiting out the wall limit for an answer the failed peer cannot produce: in the fixed study two attempts idled 153 s and 193 s after Pi's 100-step ceiling before recording a wall-timeout. The driver latches the first failure either native's active-phase turn callback reports (Pi's and Qwen's `onTurnFailure`: a rejected prompt turn, or one that ended without normal completion, including partial ACP text), with the peer, the original failure class and the failure time preserved in the record's `peer_failure` field and beside the `active_end` event. The latch is fenced by phase and by generation: nothing before the active start latches (the setup probe's expected denied tool read is a tool error, never a terminal turn failure, and even a turn failure there does not end the attempt), and the end cause freezes at `active_end`, so a later stop or watchdog callback during teardown is recorded as a teardown event only and can never replace it. A joint attempt cancels both owned peers through the same owned-process teardown — a failed actor never leaves the other actor performing an undefined partial treatment — and no failure is ever silently reported as completed. A genuine wall limit with no latched failure stays `wall-timeout`/`timeout`. The preserved partial submission (the source tree at the end of the active window and its scoped patch) remains independently gradeable exactly when the existing setup, identity, metadata, source and teardown gates pass: `peer-failure` joins `completed` and `timeout` in the runner's graded end classes, and a flag beside it (modified metadata, an unverified tree) still makes the record an infrastructure error. Records from before #160 carry no `peer_failure` field and no peer-failure end class; the ledger and grader read them unchanged.
+
 Grading flows through the same official evaluator adapter and controls; a quality failure is never a retry selector and no evaluator feedback reaches the candidate agents during generation. Reports keep quality, model-identity and request-linkage coverage separate per arm, with unavailable attempts (failed, missing or unavailable) retained in the planned denominator, and name the usage units (Pi's incremental `onTokens` counter, Qwen's session `usage_update` running total — never added together) and the tool-surface difference (Pi's hub-moderated tools against Qwen's own seatbelted auto-edit tools). A native actor's usage is counted only in attempts where that actor participated (#152): every v3 grade row carries `native_participants`, the actors the attempt record shows actually started — the arm bounds the candidates (a solo-qwen attempt has no Pi peer), and among them a peer participated only once its readiness entry carries the sessionId its adapter reported after start. A peer that was constructed but never started (a setup failure: `elapsedMs` 0, no active start) is absent; its token counter's initial 0 is never read as a measurement. An absent actor reports zero known observations and a null total (`*_tokens_known: 0`, `*_tokens: null`), a participant whose native reading is missing stays unknown rather than zero, and a participant's genuinely observed 0 stays counted. The summary's `pi_participating`/`qwen_participating` fields give each coverage figure's participation denominator. Grade rows from before #152 carry no `native_participants`; the report takes their participants from the arm, which is exact for them: their `native_usage` was attached only to scored attempts, whose readiness gate had proved every required actor's session. A live cohort, the official Docker controls and a native readback of an attempt's records remain manual live legs requiring accounts and the pinned archives; they are not part of the checked-in tests.
 
 ## Coordination ledger
@@ -141,3 +143,80 @@ The fixed ten-pair sample is a convenience sample, not the full 652-pair suite.
 The optional `--codex-bin` selects an absolute native executable when PATH contains several Codex installations. Its reported version must match the manifest. Codex automatic memories and external agent memory import are disabled for the benchmark thread. Native usage totals include the unscored sandbox probe and are labelled as whole-session counters.
 
 `--setup-only` runs every selected arm through native readiness and read-denial probes without assigning feature work. Its cohort is marked as calibration and the grader refuses it. A zero-turn Claude session is bound through its verified Orca launch and then checked against native transcript session IDs after the probe. The instance-fenced metadata file enables the daemon's optional usage reader.
+
+## Independent usage and provider coverage (#161, #162)
+
+ACP's native cumulative counter accepts checked nonnegative finite totals (including measured zero) and input/output pairs. The pinned Qwen 0.24.7 ACP source emits `usage_update {used,size}` from context occupancy (`collectContextData`), which is recorded as an unsupported cumulative-counter shape with context counters only, never consumed tokens. `usage_update` and prompt-result observations expose only a bounded counter projection with a supported, unsupported or invalid shape verdict. Cumulative readings replace the native counter; they are never summed. A started Qwen session with no compatible reading remains `no-reading`.
+
+Relay `requestUsage` is an independent per-dispatch observation of OpenAI-shaped stream `usage` fields, including a final usage-only event after model identification. Missing fields make it partial; malformed readings remain invalid or unknown. This measurement never substitutes for, or adds to, a native session total. The relay records counters only when upstream supplies them, and does not claim billing or force an unsupported stream option.
+
+Provider provenance is currently `header` (`x-omniroute-provider`) or `none`; no generation event provider contract has been verified. Provider absence leaves model qualification unchanged. `request_observability` in grading and ledger exports independently reconciles provider known/missing denominators for completed, cancelled and failed dispatches, including cancelled-after-identification. Older records remain readable: their own provider value supplies legacy header coverage, while absent request counters stay unknown. Heartbeats and another request never fill a missing provider.
+
+The bounded live capability probe is `bun scripts/benchmarks/probe-qwen-usage.ts --qwen-package PINNED_PACKAGE --run NEW_PRIVATE_DIR --config-dir PROJECT`. It verifies Qwen 0.24.7 under the final seatbelt environment, uses host-owned OmniRoute authentication through a loopback relay, and saves only counter/source/availability projections. Use a fresh disposable directory; sealed historical unknowns remain unchanged.
+
+## Durable native v3 study supervision (#165)
+
+Use `scripts/benchmarks/study_supervisor.py` for a manifest-defined study. Choose a
+new directory under an existing private, durable parent outside this repository
+and the OS temporary directory. The supervisor atomically claims that directory;
+existing roots, including incomplete ones, are refused. It never retries a cell or
+resumes a cohort. Prior archives remain read-only.
+
+```sh
+python3 -B scripts/benchmarks/study_supervisor.py \
+  --manifest scripts/benchmarks/manifest-v3-pi-qwen.json \
+  --output "$STUDY_ROOT" --archives "$ARCHIVE_ROOT" \
+  --private-inputs "$PRIVATE_CASE_ROOT" --upstream-root "$UPSTREAM_ROOT" \
+  --probe-target "$PROTECTED_PROBE" --qwen-package "$QWEN_PACKAGE" \
+  --protect "$PRIOR_ARTIFACT_ROOT" --preflight-only
+```
+
+Repeat the command without `--preflight-only` to execute. Every required archive,
+upstream commit, prompt pin, native build, protected root, probe and cached
+Docker image must be available before fixture preparation. Use `--python` to
+select the evaluator Python environment with the upstream dependencies installed. Explicitly optional
+prior roots use `--optional-protect`; their presence or absence is recorded.
+For a bounded native lifecycle check, use a separate manifest with a declared
+small plan and `--plan` to select it; preserve all case/model/order/budget pins.
+`--generation-only` stops at restored generation, records outcome generation-only,
+and never grades or seals that root. The fixed study plan remains unchanged.
+Version mismatch fails unless `--bind-current-hub` explicitly changes only
+`hub_version` and `versions.hub`. Both original and runtime hashes, source
+identity, invocation, and preparation's archive-path additions are sealed in the
+private provenance file. Native versions are checked in isolation at preflight
+and rechecked by the existing driver in each arm's final environment.
+
+The phase order is claimed, prepared, generated, restored, graded, sealed. All
+repeat roots are freshly prepared, each generation runs sequentially, and all
+planned generations finish before any official controls or grading. Restoration
+markers, their ledgers, and live PID/start-time identities must agree before
+grading. Every retained cell also passes a grade-independent readback of its
+actual fixture metadata, guarded source diff, sealed baseline and native patch
+bytes/hash. This same gate runs before reporting restored generation with
+`--generation-only`; stored `metadata_clean` flags alone never qualify it.
+Scored cells add the grade/evaluation bindings to that native evidence chain. A failure preserves an incomplete private root and logs for inspection.
+The procedure uses the existing native driver, official grade/report commands,
+and pooled ledger, without Orca registration or toolchain tree copying.
+
+This entrypoint requires the evaluator service and images to be available. It
+never starts or stops a shared VM or service. An operator who explicitly starts a
+service must retain original-state and ownership evidence separately and restore
+only that owned service after proving no unrelated usage; otherwise restoration
+is deferred. Service ownership in this supervisor is recorded as require-existing.
+
+Audit historical repeat roots without changing them:
+
+```sh
+python3 -B scripts/benchmarks/study_audit.py \
+  --run "$STUDY_ROOT/r0" --run "$STUDY_ROOT/r1" \
+  --export "$NEW_SAFE_EXPORT"
+```
+
+The auditor reconstructs the exact matrix and checks restoration, request-based
+model gates, official controls, evaluation/patch bindings and owned live processes.
+It constructs its output from fixed scalar fields and hashes. Nested official
+test output, answers, native events, errors, provider identifiers and machine paths
+are never copied to stdout or the safe aggregate. Unknown usage remains null.
+Export creation is exclusive, so it cannot overwrite a historical artifact. The
+complete private logs, evidence hash index, and safe aggregate stay in the durable
+study root. A failed audit exits nonzero with a fixed error code and no raw error.

package/docs/operations.md

@@ -896,3 +896,31 @@ Pi exposes `hub/auto` for stage routing when available. Fixed `dgx/coding`, `dgx
 and `mlx/fast` aliases still pin the backend. Automatic MLX selection admits the complete
 input, tool schemas and requested output within the configured context window.
 Progress judgements suggest reassignment; they never change task ownership.
+
+## Disable local MLX while keeping remote auto routing
+
+`mlx.enabled` is an optional boolean and defaults to `true`, including legacy
+configurations. Operators without an available local service can set:
+
+```json
+{
+  "pi": { "enabled": true, "backend": "auto" },
+  "mlx": { "enabled": false }
+}
+```
+
+This removes `mlx/fast` from the relay inventory. `hub/auto` continues selecting
+`dgx/fast` for efficient work and `dgx/coding` for capable work. Neither a local
+probe nor a local startup occurs. `ahub models status` reports `disabled` and
+`ahub doctor` reports a successful disabled row without probing the endpoint.
+`models setup`, `start`, and `stop` are refused while disabled; shared Ollama
+continues under its existing owner.
+
+Migrate an earlier `pi.backend=dgx` workaround to `auto` explicitly. In a project
+routing file, remove `pi_backend="mlx"` pins to use `hub/auto`, or set `dgx` to
+keep a remote class pin. The hub refuses conflicting operator-written routing
+before startup, while inherited shipped MLX class defaults use `hub/auto` when
+the capability is absent. It never rewrites these settings. Explicit
+`--backend mlx`, `--model mlx/fast`, and recorded MLX recovery launches are
+refused before any local startup. Re-enable MLX or explicitly migrate the
+recorded launch before recovery.

package/docs/smoke.md

@@ -1130,3 +1130,32 @@ Compare Claude usage events against its explicit native session transcript, dedu
 by assistant message ID. Compare local usage events with actual successful provider
 response counters; absent counters remain unknown and model aliases remain separate
 from reported served-model provenance. Do not infer dollar spend from token counts.
+
+## Native Pi auto-route dispatch verdicts (#164)
+
+Run `bun scripts/smoke-pi-route.ts` for permissive connectivity, or add
+`--require-primary` to require a successful primary dispatch without fallback.
+`AHUB_SMOKE_PROJECT` selects the project configuration; the smoke creates a
+separate temporary Pi workspace, permits no tools and leaves existing hubs alone.
+The project `mlx.enabled = false` capability excludes local routing from this
+smoke as well as the daemon. The response must equal `PI_HUB_AUTO_OK` exactly.
+
+The JSON verdict separates `nativeResponse`, `primaryRoute`, `fallbackRoute` and
+`fallbackOccurred`. `choices` records routing intent. `dispatches` records actual
+upstream attempts, with dispatch IDs and `fallbackOfId` linking a fallback to its
+failed primary; model identification comes only from that dispatch's journal.
+Backend readiness, a selected tier and a previous model label cannot certify
+that a generation completed. Failure diagnostics contain only bounded categories
+and HTTP status; raw errors, URLs, headers and native answer text are omitted.
+
+For an unavailable MLX primary followed by a completed DGX fallback, expect
+`nativeResponse: passed`, `primaryRoute: failed`, `fallbackRoute: passed` and
+`fallbackOccurred: true`. Connectivity passes, but the local route failed.
+The same evidence fails with `--require-primary`. Primary-only completion reports
+`fallbackRoute: unknown`; a cancelled primary reports `primaryRoute: cancelled`.
+If both attempts fail, connectivity fails even if unrelated answer text contains
+the sentinel. Missing served-model evidence remains `identified: false`.
+
+Before recording live acceptance, run a bounded unavailable-local/healthy-remote
+leg and retain the sanitized JSON plus process cleanup confirmation. Fixture
+verdicts do not certify provider availability or a real local generation.

package/docs/specs/2026-09-19-agent-hub-design.md

@@ -383,8 +383,9 @@ inside a peer.
   rolling 5 h against `budget.kimi_tokens_5h` (off by default). Verified live on kimi
   2.0.1: one update per turn, payload `{"sessionUpdate":"usage_update","used":<tokens>,
   "size":<context window>}`; `used` is the session's context occupancy against `size`
-  (1M), not billed quota; the parser matches it through the `used` fallback and it grows
-  monotonically within a session (a compaction reads as a new session). `ahub budget set`
+  (1M), not billed quota. ACP records this shape as context occupancy diagnostics,
+  never as cumulative consumed tokens. Only validated cumulative totals or input/output
+  pairs feed native token readings; unsupported shapes remain unknown. `ahub budget set`
   feeds a reading by hand. `local` has no quota and is never paused.
 - Gate at `budget.gate` (default 0.9) on any fresh window; readings older than
   `budget.stale_min` are ignored. Checkpoint first, pause second: the peer gets one
@@ -1228,3 +1229,16 @@ upgrade sources; ordinary clients must use protocol 12 (13 from 0.12.4, with 12
 - `Tasks.splitObservations` reads one observation per hand-over to the peer with the profile it has now, across hub runs of the project (what happened from that hand-over up to and with the next one is that peer's: a decline or escalation away is its failure, never the next owner's), never the routed task itself, leaves out claims, types failures (failed check, changes requested, escalation, release, decline, unresolved integration), ends the work stage at the first done call (checks and integration are not work) and leaves the stages unknown for an accept recorded by the done itself. The `split` event carries the trace.
 - An overlap that forms or changes a cohort records a `split` event for the task, routed or named (a benchmark names every owner); `ahub route explain <id>` appends the trace as it would be now. Rerouting needs held-out evidence through #110 first.
 - 2026-10-03 (T3 calibration data, issue #109 amendment): every hand-over records the new owner's split profile on its history entry: the hub's version, the agent's version (Codex's from app-server's `initialize` answer, Claude Code's from its transcript rows) and the hook profile, which is the hub's own (the coordination mode: a turn-free project runs the facts hooks in Claude). Observations count for a prediction only with the peer's current profile; while a version is unknown there is no profile, and the prediction is unknown. The prediction calibration reads is the one recorded when routing chose the first owner (no single named candidate, no claim; not an escalation, budget relay or reassignment of work already begun) of a task that overlaps another owner's task not started yet (`where: "routing"`), and `route explain` prefers the same unstarted pair; cohort-time predictions stay in the log with `where: "cohort"` and are not calibration data. The user's and plugins' hooks are not seen by the hub (ponytail: read them from the native records as the benchmark ledger does), and only Claude and Codex report a version so far.
+
+### Optional local MLX capability (0.12.11)
+
+`mlx.enabled` is an optional boolean, defaulting to true. When false, the daemon
+omits local MLX relay capability while remote `hub/auto` retains fast/coding
+selection. Explicit MLX backend/model, project policy and recovery conflicts are
+refused before local startup. Model diagnostics report disabled without probing
+that endpoint. The switch never starts or stops shared Ollama.
+
+Relay native-session counters and per-dispatch transport usage are separate
+measurements. Request usage and provider availability are optional metadata,
+bound to their own dispatch IDs; provider absence does not change model
+qualification. Primary and fallback dispatches have independent outcomes.

package/docs/specs/2026-10-04-switchyard-source-port-design.md

@@ -293,7 +293,7 @@ related: 261004-review-agent-hub-switchyard-comparison.md, 261004-plan-agent-hub
   - `crates/libsy/src/prompts/*`, `crates/libsy-llm-client/src/{client,backend,run}.rs`(호출 정책).
   - 소스 분석 보고(조사 에이전트, 2026-10-04)와 주요 상수·공식의 직접 확인.
 - agent-hub(main `ab16c7b`)
-  - `src/adapters/local-worker.ts`(`call()`, `commit()`), `src/local/tools.ts`(도구 이름), `src/models/relay.ts`(`selectBackend`, 폴백), `src/hub/daemon.ts`(relay 시작, Pi 설정), `src/hub/inference.ts`, `src/hub/facts.ts`, `src/adapters/codex-appserver.ts`, `test/fakes/model-server.ts`, `docs/events.md`, `AGENTS.md`(inference·history·PII 규칙).
+  - `src/adapters/local-worker.ts`(`call()`, `commit()`), `src/local/tools.ts`(도구 이름), `src/models/relay.ts`(`selectBackend`, 폴백), `src/hub/daemon.ts`(relay 시작, Pi 설정), `src/hub/inference.ts`, `src/hub/facts.ts`, `src/adapters/codex-appserver.ts`, `test/fakes/model-server.ts`, `docs/events.md`, `AGENTS.md`(PII·PII turn 규칙), `docs/agent-notes/models.md`(inference 규칙), `docs/agent-notes/local-worker.md`(history 규칙).
   - 기본 설정: Pi `dgx_coding = "coding"`, `dgx_fast = "fast"`, MLX `qwen3.5:4b-mlx`(8k).
 
 ## Implementation contract (approved 2026-10-04)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.10",
+  "version": "0.12.12",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.12.10",
+  "version": "0.12.12",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15403,7 +15403,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.10",
+  version: "0.12.12",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/adapters/acp.ts

@@ -17,6 +17,40 @@ export interface PermissionRequest {
   tool?: string;
 }
 
+export interface ACPUsageDiagnostic {
+  source: "usage_update" | "prompt_result";
+  availability: "known" | "unsupported" | "invalid";
+  shape: "total" | "input-output" | "context-used" | "none";
+  contextUsed?: number;
+  contextCapacity?: number;
+  total?: number;
+}
+
+/** Counter-only projection: no source payload, text, tools or metadata escapes. */
+export function normalizeACPUsage(value: unknown, source: ACPUsageDiagnostic["source"] = "usage_update"): ACPUsageDiagnostic {
+  const unknown: ACPUsageDiagnostic = { source, availability: "unsupported", shape: "none" };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return unknown;
+  const raw = value as Record<string, unknown>;
+  const f = raw.usage && typeof raw.usage === "object" && !Array.isArray(raw.usage) ? raw.usage as Record<string, unknown> : raw;
+  const valid = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v >= 0;
+  for (const key of ["totalTokens", "total_tokens"]) {
+    if (f[key] === undefined) continue;
+    const shape = "total";
+    return valid(f[key]) ? { source, availability: "known", shape, total: f[key] } : { source, availability: "invalid", shape };
+  }
+  for (const [input, output] of [["inputTokens", "outputTokens"], ["input_tokens", "output_tokens"]]) {
+    if (f[input!] === undefined && f[output!] === undefined) continue;
+    const a = f[input!], b = f[output!];
+    return valid(a) && valid(b) && Number.isFinite(a + b) ? { source, availability: "known", shape: "input-output", total: a + b } : { source, availability: "invalid", shape: "input-output" };
+  }
+  if (f.used !== undefined) {
+    if (!valid(f.used) || !valid(f.size) || !Number.isSafeInteger(f.used) || !Number.isSafeInteger(f.size) || f.size <= 0) return { source, availability: "invalid", shape: "context-used" };
+    // Qwen 0.24.7 derives this from collectContextData: occupancy is not cumulative consumption.
+    return { source, availability: "unsupported", shape: "context-used", contextUsed: f.used, contextCapacity: f.size };
+  }
+  return unknown;
+}
+
 export interface AcpOptions {
   /** e.g. ["kimi", "acp"]. `opencode acp` fits the same adapter. */
   cmd: string[];
@@ -32,8 +66,12 @@ export interface AcpOptions {
   mcpServers?: { name: string; command: string; args: string[]; env: { name: string; value: string }[] }[];
   /** Appended to the standing instruction of the first delivery (role contract). */
   preamble?: string;
-  /** The session's running token total from `usage_update` (inferred shape: totalTokens, else input + output, else `used`). Cumulative, not a delta. */
+  /** The session's running token total from `usage_update` (checked totalTokens or input/output pair; `used` context occupancy is diagnostic only). Cumulative, not a delta. */
   onTokens?: (sessionTotal: number, sessionId: string) => void;
+  /** The prompt rejected or ended without normal completion, even when it streamed partial text.
+   *  Same shape as Pi's onTurnFailure; a stale cancelled turn never reports. */
+  onTurnFailure?: (envs: Envelope[], reason: string) => Promise<void> | void;
+  onUsageDiagnostic?: (observation: ACPUsageDiagnostic) => void;
   /** Resolve with an optionId, or undefined to cancel. Absent = every request is cancelled.
    *  A request whose payload could not be resolved is titled as such and carries no session-wide allow option. */
   onPermission?: (req: PermissionRequest) => Promise<string | undefined>;
@@ -146,9 +184,12 @@ export class AcpPeer extends BasePeer {
     prompt
       .then((result) => {
         if (turn !== this.turn) return; // superseded: these chunks belong to a later turn
+        this.observeUsage(result, "prompt_result");
         this.primed = true;
         const body = this.chunks.join("").trim();
         if (body) this.onMessage?.(body, { inReplyTo: replyParent(envs), to: replyAudience(envs) });
+        // Partial output cannot certify normal completion (#160).
+        if (result?.stopReason !== "end_turn") this.reportTurnFailure(envs, `ACP prompt ended without normal completion (${String(result?.stopReason ?? "unknown")})`);
         if (deliveryId && this.activeDeliveryId === deliveryId) {
           this.acceptDelivery();
           this.delivery({ id: deliveryId, state: result?.stopReason === "end_turn" ? "completed" : "needs_review", ...(result?.stopReason === "end_turn" ? {} : { reason: "ACP prompt ended without normal completion" }) });
@@ -156,6 +197,7 @@ export class AcpPeer extends BasePeer {
       })
       .catch((e: Error) => {
         this.opts.log?.(`[${this.id}] prompt failed: ${e.message}`);
+        if (turn === this.turn) this.reportTurnFailure(envs, e.message); // a watchdog-cancelled turn reports stale, never as this turn's failure
         if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
         else if (!deliveryId) this.onFailed?.(envs);
       })
@@ -165,6 +207,15 @@ export class AcpPeer extends BasePeer {
       });
   }
 
+  private reportTurnFailure(envs: Envelope[], reason: string): void {
+    try {
+      const result = this.opts.onTurnFailure?.(envs, reason);
+      if (result) void result.catch(() => this.opts.log?.("ACP failure handoff could not be completed"));
+    } catch {
+      this.opts.log?.("ACP failure handoff could not be completed");
+    }
+  }
+
   protected override onWatchdog(): void {
     const durable = !!this.activeDeliveryId;
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "ACP turn watchdog timeout" });
@@ -177,6 +228,12 @@ export class AcpPeer extends BasePeer {
     else super.onWatchdog();
   }
 
+  private observeUsage(value: unknown, source: ACPUsageDiagnostic["source"]): void {
+    const observation = normalizeACPUsage(value, source);
+    this.opts.onUsageDiagnostic?.(observation);
+    if (observation.availability === "known") this.opts.onTokens?.(observation.total!, this.sessionId);
+  }
+
   private acceptDelivery(): void {
     if (!this.activeDeliveryId || this.deliveryAccepted) return;
     this.deliveryAccepted = true;
@@ -222,12 +279,7 @@ export class AcpPeer extends BasePeer {
         if (u.status === "completed" || u.status === "failed") (this.toolInputs.delete(u.toolCallId), this.toolText.delete(u.toolCallId), this.toolTitles.delete(u.toolCallId));
         for (const map of [this.toolInputs, this.toolText, this.toolTitles]) while (map.size > TOOL_INPUT_CAP) map.delete(map.keys().next().value as string);
       }
-      else if (u?.sessionUpdate === "usage_update" && this.opts.onTokens) {
-        const f = { ...u, ...(typeof u.usage === "object" ? u.usage : {}) } as Record<string, unknown>;
-        const num = (k: string) => (typeof f[k] === "number" ? (f[k] as number) : 0);
-        const total = num("totalTokens") || num("total_tokens") || num("inputTokens") + num("outputTokens") || num("input_tokens") + num("output_tokens") || num("used");
-        if (total > 0) this.opts.onTokens(total, this.sessionId);
-      }
+      else if (u?.sessionUpdate === "usage_update") this.observeUsage(u, "usage_update");
     } else if (msg.method === "session/request_permission") {
       void this.answerPermission(msg);
     } else if (msg.method && msg.id !== undefined) {

package/src/cli/main.ts

@@ -571,6 +571,11 @@ const commands: Record<string, () => Promise<void> | void> = {
   models: async () => {
     const action = args[0] ?? "status";
     const configured = projectConfig().mlx;
+    if (configured.enabled === false) {
+      if (action === "status") return console.log(JSON.stringify({ state: "disabled", enabled: false }, null, 2));
+      if (["setup", "start", "stop"].includes(action)) fail("MLX is disabled by mlx.enabled=false; models commands do not manage shared Ollama");
+      fail("usage: ahub models setup|status|start|stop");
+    }
     const runtimeDir = configured.runtimeDir ? resolve(cwd, configured.runtimeDir) : join(homedir(), ".agenthub", "runtimes", "mlx");
     const modelPath = configured.modelPath ? resolve(cwd, configured.modelPath) : join(homedir(), ".agenthub", "models", "qwen3-8b-mlx");
     const mlxOptions = configured.provider === "ollama" ? configured : { ...configured, runtimeDir, modelPath };
@@ -953,8 +958,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     const sy = spawnSync(process.env.AGENTHUB_SWITCHYARD_BIN ?? "switchyard-server", ["--version"], { encoding: "utf8" });
     row(sy.status === 0 ? true : undefined, "switchyard", sy.status === 0 ? sy.stdout.trim() : "not installed: ahub local uses fixed_model on OmniRoute (cargo install --locked switchyard-server)");
     const mlxConfig = config.mlx;
-    const mlx = await inspectMlx({ ...mlxConfig, runtimeDir: mlxConfig.runtimeDir ? resolve(cwd, mlxConfig.runtimeDir) : undefined, modelPath: mlxConfig.modelPath ? resolve(cwd, mlxConfig.modelPath) : undefined });
-    row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
+    if (mlxConfig.enabled === false) row(true, "pi mlx", "disabled (mlx.enabled=false; local endpoint not probed)");
+    else {
+      const mlx = await inspectMlx({ ...mlxConfig, runtimeDir: mlxConfig.runtimeDir ? resolve(cwd, mlxConfig.runtimeDir) : undefined, modelPath: mlxConfig.modelPath ? resolve(cwd, mlxConfig.modelPath) : undefined });
+      row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
+    }
 
     const memory = new MemoryClient();
     const mem = await memory.health();

package/src/hub/daemon.ts

@@ -69,7 +69,7 @@ export interface HubConfig {
   inference: InferenceConfig;
   omniroute: OmniRouteConfig;
   pi: { enabled: boolean; auto_start: boolean; cmd: string[]; backend: "auto" | "dgx" | "mlx"; dgx_coding: string; dgx_fast: string; max_steps: number };
-  mlx: Pick<MlxOptions, "provider" | "host" | "runtimeDir" | "modelPath" | "port" | "model" | "sourceModel" | "contextWindow" | "maxInputTokens" | "maxTokens" | "maxConcurrency">;
+  mlx: { enabled: boolean } & Pick<MlxOptions, "provider" | "host" | "runtimeDir" | "modelPath" | "port" | "model" | "sourceModel" | "contextWindow" | "maxInputTokens" | "maxTokens" | "maxConcurrency">;
   /** `bash_network`: true is network through the egress proxy to `network_allow` (#65); "direct" is everything, until 0.13.0 (#83). */
   local: { deny: string[]; bash_network: boolean | "direct"; network_allow: string[]; max_steps: number; read_allow: string[] };
   /** Pending permission requests: how long they wait, and whether the desktop is told (issue #5). */
@@ -113,7 +113,7 @@ export const DEFAULT_CONFIG: HubConfig = {
   inference: DEFAULT_INFERENCE,
   omniroute: DEFAULT_OMNIROUTE,
   pi: { enabled: false, auto_start: false, cmd: ["pi"], backend: "auto", dgx_coding: "coding", dgx_fast: "fast", max_steps: 30 },
-  mlx: { provider: "ollama", model: "agenthub-fast-mlx:4b-8k", sourceModel: "qwen3.5:4b-mlx", contextWindow: 8192, maxInputTokens: 6000, maxTokens: 2048, maxConcurrency: 1 },
+  mlx: { enabled: true, provider: "ollama", model: "agenthub-fast-mlx:4b-8k", sourceModel: "qwen3.5:4b-mlx", contextWindow: 8192, maxInputTokens: 6000, maxTokens: 2048, maxConcurrency: 1 },
   local: { deny: [], bash_network: false, network_allow: DEFAULT_NETWORK_ALLOW, max_steps: 30, read_allow: [] },
   // Off here, so tests and a hub without a config file stay silent; a project's config defaults it on for macOS.
   approvals: { timeout_s: 120, notify: false },
@@ -166,11 +166,13 @@ export function loadConfig(cwd: string): HubConfig {
   }
   if (file.local?.bash_network === "direct") retired.push('local.bash_network "direct" (the open network) goes in 0.13.0: set it to true and list the hosts in local.network_allow');
   if (file.mlx != null && (typeof file.mlx !== "object" || Array.isArray(file.mlx))) throw new Error("mlx configuration must be an object");
+  if (file.mlx?.enabled !== undefined && typeof file.mlx.enabled !== "boolean") throw new Error("mlx.enabled must be a boolean");
   if (file.mlx?.provider !== undefined && !["ollama", "legacy"].includes(file.mlx.provider)) throw new Error("mlx.provider must be ollama or legacy");
   if (file.mlx?.provider === undefined && (file.mlx?.modelPath || file.mlx?.runtimeDir || file.mlx?.bin || file.mlx?.port)) {
     throw new Error("legacy MLX configuration requires explicit mlx.provider=legacy; migrate to provider=ollama to avoid Python serving");
   }
-  const mlx = { ...(file.mlx?.provider === "legacy" ? { provider: "legacy" as const, maxInputTokens: 16_000, maxTokens: 2048 } : DEFAULT_CONFIG.mlx), ...file.mlx };
+  const mlx = { ...(file.mlx?.provider === "legacy" ? { enabled: true, provider: "legacy" as const, maxInputTokens: 16_000, maxTokens: 2048 } : DEFAULT_CONFIG.mlx), ...file.mlx };
+  if (!mlx.enabled && file.pi?.backend === "mlx") throw new Error("Pi backend mlx conflicts with mlx.enabled=false");
   if (typeof mlx.runtimeDir === "string" && mlx.runtimeDir) mlx.runtimeDir = resolve(cwd, mlx.runtimeDir);
   if (typeof mlx.modelPath === "string" && mlx.modelPath) mlx.modelPath = resolve(cwd, mlx.modelPath);
   return {
@@ -200,6 +202,20 @@ export function loadConfig(cwd: string): HubConfig {
   };
 }
 
+/** Explicit launch choices are never replaced when the local capability is disabled. */
+export function mlxLaunchProblem(config: HubConfig, args: { backend?: unknown; model?: unknown }): string | undefined {
+  if (config.mlx.enabled !== false) return undefined;
+  if (args.backend === "mlx" || args.model === "mlx/fast") return "Pi MLX launch conflicts with mlx.enabled=false; select auto or a DGX alias";
+  return undefined;
+}
+
+/** Shipped defaults remain capability-aware; operator-written MLX pins require an explicit migration. */
+function disabledMlxPolicyProblem(config: HubConfig, cwd: string): string | undefined {
+  if (config.mlx.enabled !== false || !existsSync(join(cwd, ".agenthub", "routing.toml"))) return undefined;
+  const conflict = Object.entries(currentRouting(cwd).classes).find(([, policy]) => policy?.pi_backend === "mlx");
+  return conflict ? `routing.toml: [classes.${conflict[0]}] pi_backend=mlx conflicts with mlx.enabled=false; remove the pin for hub/auto or select dgx` : undefined;
+}
+
 export interface DaemonOptions {
   projectId?: string;
   instanceId?: string;
@@ -284,6 +300,8 @@ export async function startDaemon(opts: DaemonOptions) {
   let ready = false;
   try {
   const config = opts.config ?? loadConfig(opts.cwd);
+  const mlxConfigProblem = mlxLaunchProblem(config, config.pi) ?? disabledMlxPolicyProblem(config, opts.cwd);
+  if (mlxConfigProblem) throw new Error(mlxConfigProblem);
   mkdirSync(opts.stateDir, { recursive: true });
   const logFile = join(opts.stateDir, "hub.log");
   // The state dir can vanish under a running hub (issue #56): a log line must never take a handler down with it.
@@ -333,6 +351,13 @@ export async function startDaemon(opts: DaemonOptions) {
 
   // A session record left by a run that never shut down means it crashed (issue #37). A controlled restart has its own.
   const crashed = !recoveryOperation && !restartFilePresent ? readSessions(opts.stateDir) : undefined;
+  if (config.mlx.enabled === false) {
+    const launches = [...(restored?.peers ?? []).filter(peer => peer.id === "pi").map(peer => peer.launch), ...(crashed?.peers ?? []).filter(peer => peer.peer === "pi").map(peer => peer.meta.launch)];
+    for (const launch of launches) {
+      const problem = mlxLaunchProblem(config, (launch ?? {}) as { backend?: unknown; model?: unknown });
+      if (problem) throw new Error(`recorded Pi recovery: ${problem}`);
+    }
+  }
   // A controlled restart's source may have been cut short before it removed its record: this run is not a crash, and
   // a record left now would make the next ordinary start look like one.
   if (recoveryOperation || restartFilePresent) try { removeSessions(opts.stateDir); } catch { /* nothing to remove */ }
@@ -1516,6 +1541,8 @@ export async function startDaemon(opts: DaemonOptions) {
 
   async function startPeerBody(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean }, mute: (p: PeerAdapter) => void): Promise<Record<string, unknown>> {
     if (peer === "pi") {
+      const problem = mlxLaunchProblem(config, { backend: args.backend ?? config.pi.backend, model: args.model }) ?? disabledMlxPolicyProblem(config, opts.cwd);
+      if (problem) return { ok: false, error: problem };
       if (args.mode !== undefined && !["headless", "tui"].includes(args.mode)) return { ok: false, error: "invalid Pi mode" };
       if (args.backend !== undefined && !["auto", "dgx", "mlx"].includes(args.backend)) return { ok: false, error: "invalid Pi backend" };
       if (args.model !== undefined && !["dgx/coding", "dgx/fast", "mlx/fast"].includes(args.model)) return { ok: false, error: "unknown Pi model alias" };
@@ -1650,7 +1677,9 @@ export async function startDaemon(opts: DaemonOptions) {
       const mode = args.mode ?? "headless";
       const backend = args.backend ?? config.pi.backend;
       if (!["headless", "tui"].includes(mode) || !["auto", "dgx", "mlx"].includes(backend)) return { ok: false, error: "invalid Pi mode/backend" };
-      modelRelay ??= await startModelRelay({ omni, admitRequest: admitPiRequest, dgxMaxInputTokens: currentRouting(opts.cwd, log).pi.dgx_max_context_tokens, allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast }, mlx: config.mlx, mlxAlias: "mlx/fast", fallbackDGXAlias: "dgx/fast", enableHubAuto: true,
+      const problem = mlxLaunchProblem(config, { backend, model: args.model });
+      if (problem) return { ok: false, error: problem };
+      modelRelay ??= await startModelRelay({ omni, admitRequest: admitPiRequest, dgxMaxInputTokens: currentRouting(opts.cwd, log).pi.dgx_max_context_tokens, allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast }, mlx: config.mlx.enabled === false ? undefined : config.mlx, mlxAlias: "mlx/fast", fallbackDGXAlias: "dgx/fast", enableHubAuto: true,
         routeSessionKey: () => { const session = bus.peers.get("pi")?.recoveryMetadata?.().sessionId; return typeof session === "string" ? session : undefined; },
         onRoute: record => event({ type: "route", peer: "pi", ...record }),
       });
@@ -1673,7 +1702,7 @@ export async function startDaemon(opts: DaemonOptions) {
         model: args.model,
         sessionId: args.sessionId, sessionFile: args.sessionFile,
         admitBudget: async (envs, unit) => unit === "model_calls" ? [] : tasks.admitExecutionEnvelopes(envs, "pi", unit),
-        relay: { url: modelRelay.url, token: modelRelay.token, models: modelRelay.models.map((id) => ({ id, contextWindow: id.startsWith("mlx/") ? Math.min(routing.pi.mlx_max_context_tokens, config.mlx.provider === "ollama" ? (config.mlx.contextWindow ?? 8192) : routing.pi.mlx_max_context_tokens) : routing.pi.dgx_max_context_tokens, maxTokens: id === "hub/auto" ? Math.min(config.mlx.maxTokens ?? 2048, 8192) : id.startsWith("mlx/") ? (config.mlx.maxTokens ?? 2048) : 8192 })) },
+        relay: { url: modelRelay.url, token: modelRelay.token, models: modelRelay.models.map((id) => ({ id, contextWindow: id.startsWith("mlx/") ? Math.min(routing.pi.mlx_max_context_tokens, config.mlx.provider === "ollama" ? (config.mlx.contextWindow ?? 8192) : routing.pi.mlx_max_context_tokens) : routing.pi.dgx_max_context_tokens, maxTokens: id === "hub/auto" ? (config.mlx.enabled === false ? 8192 : Math.min(config.mlx.maxTokens ?? 2048, 8192)) : id.startsWith("mlx/") ? (config.mlx.maxTokens ?? 2048) : 8192 })) },
         tools: [...TOOL_SCHEMAS.map((t) => t.function), ...TASK_TOOLS.map((t) => ({ name: t.name, description: t.description, parameters: t.inputSchema }))],
         executeTool: async (name, raw, callId, sessionId, signal) => {
           if (signal?.aborted) return "error: turn cancelled before tool effects";
@@ -1709,7 +1738,12 @@ export async function startDaemon(opts: DaemonOptions) {
           const taskId = envs.find(env => env.refs?.task)?.refs?.task;
           const task = taskId ? board.get(Number(taskId)) : undefined;
           const policyBackend = task ? currentRouting(opts.cwd, log).classes[task.class]?.pi_backend : undefined;
-          if (policyBackend === "mlx") return "mlx/fast";
+          if (policyBackend === "mlx") {
+            if (config.mlx.enabled !== false) return "mlx/fast";
+            const problem = disabledMlxPolicyProblem(config, opts.cwd);
+            if (problem) throw new Error(problem);
+            return "hub/auto";
+          }
           if (policyBackend === "dgx") return task && ["bulk_edit", "test"].includes(task.class) ? "dgx/fast" : "dgx/coding";
           return "hub/auto";
         },

package/src/models/relay.ts

@@ -39,8 +39,20 @@ export interface ModelRelayStatus {
  *  `identitySource` says where the served-model label came from: the gateway response header, a
  *  generation SSE event (#137 classification: heartbeats never identify), or the locally validated
  *  MLX configuration. HTTP 200, the requested alias and a previous request's label never identify. */
+export interface RelayUsageObservation {
+  source: "openai-stream-usage";
+  completeness: "complete" | "partial";
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+}
+
 export interface RelayRequestRecord {
   id: string;
+  dispatchGroupId?: string;
+  fallbackOfId?: string;
+  failureClass?: "http" | "transport" | "startup" | "admission" | "cancelled";
+  httpStatus?: number;
   /** Admission timestamp (start of the upstream dispatch attempt), ISO. */
   at: string;
   /** Resolved backend alias (the requested route). */
@@ -49,6 +61,11 @@ export interface RelayRequestRecord {
   requestedModel?: string;
   /** Sanitized `x-omniroute-provider` header; absent stays unknown. */
   provider?: string;
+  providerSource?: "header" | "none";
+  providerAvailability?: "known" | "missing";
+  /** Independent transport counter, never a native session counter. */
+  requestUsage?: RelayUsageObservation;
+  usageAvailability?: "known" | "partial" | "missing" | "invalid";
   /** Observed served model; never read back from the backend's mutable last label. */
   actualModel?: string;
   identitySource: "header" | "stream" | "configured" | "none";
@@ -86,6 +103,9 @@ export interface ModelRelayOptions {
   mlxAlias?: string;
   mlxModel?: string;
   fallbackDGXAlias?: string;
+  /** Include explicit missing usage/provider metadata and dispatch groups, independently of observers.
+   *  Omission preserves the legacy absent-metadata journal schema. */
+  observeRequestMetadata?: boolean;
   /** Called exactly once per journaled request, at its terminal close, with a sanitized copy. */
   onRequest?: (record: RelayRequestRecord) => void;
 }
@@ -103,6 +123,7 @@ export interface ModelRelay {
 interface RequestJournalEntry {
   readonly record: RelayRequestRecord;
   identify(model: string, source: "header" | "stream" | "configured"): void;
+  usage(value: unknown): void;
   close(outcome: RelayRequestRecord["outcome"]): void;
 }
 
@@ -116,7 +137,24 @@ interface ActiveRequest {
 
 class ExecutionAdmissionError extends Error {}
 
-const safeHeader = (value: string | null): string | undefined => value && value.length < 256 ? value : undefined;
+const safeHeader = (value: string | null): string | undefined => value && value.length < 256 && !/\p{C}/u.test(value) ? value : undefined;
+
+export function normalizeRelayUsage(value: unknown): RelayUsageObservation | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const usage = value as Record<string, unknown>;
+  const fields = [["prompt_tokens", "promptTokens"], ["completion_tokens", "completionTokens"], ["total_tokens", "totalTokens"]] as const;
+  const result: RelayUsageObservation = { source: "openai-stream-usage", completeness: "partial" };
+  let count = 0;
+  for (const [input, output] of fields) {
+    if (usage[input] === undefined) continue;
+    const v = usage[input];
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0) return undefined;
+    result[output] = v; count++;
+  }
+  if (!count) return undefined;
+  if (count === 3) result.completeness = "complete";
+  return result;
+}
 
 function assertLoopback(host: string): void {
   const value = host.toLowerCase();
@@ -159,7 +197,7 @@ function isGenerationEvent(choices: unknown): boolean {
   });
 }
 
-function sseResponse(response: Response, release: () => void, onModel?: (model: string) => void, registerCancel?: (cancel: (reason?: unknown) => Promise<void>) => void, onClose?: (outcome: RelayRequestRecord["outcome"]) => void): Response {
+function sseResponse(response: Response, release: () => void, onModel?: (model: string) => void, registerCancel?: (cancel: (reason?: unknown) => Promise<void>) => void, onClose?: (outcome: RelayRequestRecord["outcome"]) => void, onUsage?: (value: unknown) => void): Response {
   if (!response.body) {
     release();
     onClose?.("failed");
@@ -172,22 +210,23 @@ function sseResponse(response: Response, release: () => void, onModel?: (model:
   registerCancel?.(cancel);
   let inspectBuffer = "";
   let inspectedModel = false;
+  const decoder = new TextDecoder();
   const inspect = (chunk: Uint8Array) => {
-    if (!onModel || inspectedModel) return;
-    inspectBuffer += new TextDecoder().decode(chunk);
+    if (!onUsage && (!onModel || inspectedModel)) return;
+    inspectBuffer += decoder.decode(chunk, { stream: true });
     if (inspectBuffer.length > 64_000) inspectBuffer = inspectBuffer.slice(-64_000);
     const lines = inspectBuffer.split(/\r?\n/);
     inspectBuffer = lines.pop() ?? "";
     for (const line of lines) {
       if (!line.startsWith("data:") || line.slice(5).trim() === "[DONE]") continue;
       try {
-        const value = JSON.parse(line.slice(5).trim()) as { model?: unknown; choices?: unknown[] };
+        const value = JSON.parse(line.slice(5).trim()) as { model?: unknown; choices?: unknown[]; usage?: unknown };
+        if (value.usage !== undefined && value.usage !== null) onUsage?.(value.usage);
         // Transport heartbeats are not model identity: a gateway keepalive can name a synthetic model on
         // an event with no generation activity (no choices, or only empty deltas without a finish reason).
-        if (typeof value.model === "string" && value.model.length < 256 && isGenerationEvent(value.choices)) {
+        if (!inspectedModel && typeof value.model === "string" && safeHeader(value.model) !== undefined && isGenerationEvent(value.choices)) {
           inspectedModel = true;
-          onModel(value.model);
-          return;
+          onModel?.(value.model);
         }
       } catch { /* incomplete or non-JSON SSE data */ }
     }
@@ -219,6 +258,8 @@ function sseResponse(response: Response, release: () => void, onModel?: (model:
   });
 }
 
+const copyRecord = (record: RelayRequestRecord): RelayRequestRecord => ({ ...record, ...(record.requestUsage ? { requestUsage: { ...record.requestUsage } } : {}) });
+
 export async function startModelRelay(options: ModelRelayOptions): Promise<ModelRelay> {
   const host = options.host ?? "127.0.0.1";
   assertLoopback(host);
@@ -238,12 +279,13 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
 
   // The record object is the generation fence: every update goes through this entry's own closure,
   // so interleaved requests for the same alias never write into each other's evidence.
-  const openRequestRecord = (alias: string): RequestJournalEntry => {
+  const openRequestRecord = (alias: string, dispatchGroupId: string): RequestJournalEntry => {
     const start = Date.now();
     const expectedServedModel = options.expectedServedModels?.[alias];
     const record: RelayRequestRecord = {
-      id: randomUUID(), at: new Date(start).toISOString(), alias,
+      id: randomUUID(), ...(options.observeRequestMetadata ? { dispatchGroupId } : {}), at: new Date(start).toISOString(), alias,
       identitySource: "none", role: "unknown", outcome: "completed", identified: false, durationMs: 0,
+      ...(options.observeRequestMetadata ? { providerSource: "none" as const, providerAvailability: "missing" as const, usageAvailability: "missing" as const } : {}),
     };
     let closed = false;
     const identify: RequestJournalEntry["identify"] = (model, source) => {
@@ -262,15 +304,25 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
       record.durationMs = Date.now() - start;
       const expectedModel = expectedServedModel ?? record.requestedModel;
       if (record.identified && expectedModel !== undefined && record.actualModel !== expectedModel) record.mismatch = true;
-      journal.push({ ...record });
+      journal.push(copyRecord(record));
       if (journal.length > JOURNAL_LIMIT) journal.shift();
       try {
         // An async hook fits the void signature: its rejection is handled too, never unobserved.
-        const notified = options.onRequest?.({ ...record }) as unknown;
+        const notified = options.onRequest?.(copyRecord(record)) as unknown;
         if (notified instanceof Promise) notified.catch(() => { /* a persistence hook must never break the relay */ });
       } catch { /* a persistence hook must never break the proxied stream it observes */ }
     };
-    return { record, identify, close };
+    const usage = (value: unknown) => {
+      if (closed) return;
+      record.providerSource ??= "none";
+      record.providerAvailability ??= "missing";
+      const observation = normalizeRelayUsage(value);
+      if (observation) {
+        record.requestUsage = observation;
+        record.usageAvailability = observation.completeness === "complete" ? "known" : "partial";
+      } else if (!record.requestUsage) record.usageAvailability = "invalid";
+    };
+    return { record, identify, usage, close };
   };
 
   const ensureMlxHandle = async (): Promise<MlxHandle> => (mlx ??= await (mlxStarting ??= ensureMlx(options.mlx).finally(() => { mlxStarting = undefined; })));
@@ -345,18 +397,25 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
       response = await fetch(`${base.replace(/\/$/, "")}/chat/completions`, { method: "POST", ...(isOllama ? { redirect: "error" as const } : {}), headers, body: JSON.stringify(bodyForUpstream(boundedRequest, model)), signal: AbortSignal.any([signal, AbortSignal.timeout(deadline)]) });
     } catch (error) {
       releaseOnce();
+      journalEntry.record.failureClass = "transport";
       setState(backend, { state: "error", lastError: error instanceof Error ? error.message.slice(0, 160) : "upstream request failed" });
       throw error;
     }
+    const provider = safeHeader(response.headers.get("x-omniroute-provider"));
+    if (provider) {
+      journalEntry.record.provider = provider;
+      journalEntry.record.providerSource = "header";
+      journalEntry.record.providerAvailability = "known";
+    }
     if (!response.ok) {
       releaseOnce();
+      journalEntry.record.failureClass = "http";
+      journalEntry.record.httpStatus = response.status;
       const message = `backend returned HTTP ${response.status}`;
       setState(backend, { state: "error", lastError: message });
       throw new Error(message);
     }
-    const provider = safeHeader(response.headers.get("x-omniroute-provider"));
     const actualModel = safeHeader(response.headers.get("x-model-router-selected-model"));
-    if (provider) journalEntry.record.provider = provider;
     if (actualModel) journalEntry.identify(actualModel, "header");
     else if (backend.kind === "mlx") journalEntry.identify(model, "configured");
     setState(backend, { state: "ready", requestedModel: request.model, active: activeByAlias.get(alias) ?? 0,
@@ -419,10 +478,23 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
         return Response.json({ error: "input exceeds the model context budget" }, { status: 400 });
       }
       const fallback = backend.kind === "mlx" && options.fallbackDGXAlias ? { kind: "dgx", alias: options.fallbackDGXAlias } as ModelBackend : undefined;
+      const dispatchGroupId = randomUUID();
+      let primaryDispatchId: string | undefined;
       const dispatch = async (selected: ModelBackend, body: RelayRequest) => {
-        const journalEntry = openRequestRecord(aliasOf(selected, mlxAlias));
+        const journalEntry = openRequestRecord(aliasOf(selected, mlxAlias), dispatchGroupId);
+        if (primaryDispatchId) {
+          journalEntry.record.fallbackOfId = primaryDispatchId;
+          journalEntry.record.dispatchGroupId = dispatchGroupId;
+        }
+        else primaryDispatchId = journalEntry.record.id;
         record.closeRecord = journalEntry.close;
-        const result = await upstream(body, selected, controller.signal, journalEntry);
+        let result: Awaited<ReturnType<typeof upstream>>;
+        try {
+          result = await upstream(body, selected, controller.signal, journalEntry);
+        } catch (error) {
+          journalEntry.record.failureClass ??= controller.signal.aborted ? "cancelled" : error instanceof ExecutionAdmissionError ? "admission" : "startup";
+          throw error;
+        }
         let released = false;
         const release = () => {
           if (released) return;
@@ -432,11 +504,12 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
           activeRequests.delete(record);
         };
         record.release = release;
-        return { result, release, journalEntry };
+        const onUsage = journalEntry.usage;
+        return { result, release, journalEntry, onUsage };
       };
       try {
-        const { result, release, journalEntry } = await dispatch(backend, body);
-        return sseResponse(result.response, release, result.onModel, (cancel) => { record.cancel = cancel; }, journalEntry.close);
+        const { result, release, journalEntry, onUsage } = await dispatch(backend, body);
+        return sseResponse(result.response, release, result.onModel, (cancel) => { record.cancel = cancel; }, journalEntry.close, onUsage);
       } catch (error) {
         record.closeRecord?.(controller.signal.aborted ? "cancelled" : "failed");
         if (!fallback || controller.signal.aborted || error instanceof ExecutionAdmissionError) {
@@ -445,8 +518,8 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
           return Response.json({ error: error instanceof Error ? error.message : "backend unavailable" }, { status: 502 });
         }
         try {
-          const { result, release, journalEntry } = await dispatch(fallback, { ...body, model: fallback.alias });
-          return sseResponse(result.response, release, result.onModel, (cancel) => { record.cancel = cancel; }, journalEntry.close);
+          const { result, release, journalEntry, onUsage } = await dispatch(fallback, { ...body, model: fallback.alias });
+          return sseResponse(result.response, release, result.onModel, (cancel) => { record.cancel = cancel; }, journalEntry.close, onUsage);
         } catch (fallbackError) {
           record.closeRecord?.(controller.signal.aborted ? "cancelled" : "failed");
           record.cleanup();
@@ -458,7 +531,7 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
   });
   const url = `http://${host}:${server.port}/v1`;
   const status = (): ModelRelayStatus => ({ url, models, backends: [...states.values()].map((value) => ({ ...value })) });
-  const requests = (): RelayRequestRecord[] => journal.map((record) => ({ ...record }));
+  const requests = (): RelayRequestRecord[] => journal.map(copyRecord);
   return { url, token, models, status, requests, close: async () => {
     const closing = [...activeRequests].map(async (request) => {
       // The relay-initiated cancellation closes the record first: the abort below settles the stream