From 7ddf62efb6308beafc7d346b2e1003f7358dad93 Mon Sep 17 00:00:00 2001
From: Drew Stone <drewstone329@gmail.com>
Date: Sat, 1 Aug 2026 01:50:38 -0600
Subject: [PATCH 1/2] feat(tui): host the supervisor run view where the run
 layout is written
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The terminal view over live supervisor runs lived in the loops repo, where it
carried its own hand-joined copy of the on-disk layout:

    [join(root, '.agent', 'supervisor'), join(root, '.loops', 'supervisor')]

agent-runtime owns and exports that contract, and agent-runtime is what WRITES
the state the view renders. A reader versioning independently of its writer
drifts; keeping the two in one package makes drift impossible by construction.

Moved verbatim except where a hand-joined path became a call into the contract:

  src/tui/top-model.ts  read the layout into a TopSnapshot, render an ANSI frame
  src/tui/top-app.ts    keypress/mouse loop, steer and cancel controls
  src/tui/bin.ts        agent-runtime-top [root] [--once] [--no-color]

Three fixes fall out of consuming the contract rather than copying it:

- The view read only `journal.jsonl`, the retired bare-event file. This repo's
  own `createFileRunContext` writes `spawn-journal.jsonl`, so the view showed
  zero workers for every current run. Both names are read, newest first.
- Worker tails are keyed by file stem, which the writer puts through
  `safeWorkerFile`; a label that stem alters never found its own events.
- `<label>.inbox.ndjson` was read as if it were a control-event log.

Steers go through `writeWorkerSteer` — the snapshot already carries the label
the layout keys inboxes by, so no id-to-label resolution sits in between.

run-layout gains the accessors the view needs so it never joins a path itself:
`legacySupervisorRunsRoot` (enumerating pre-rename runs), `supervisorWorkersDir`,
`workerControlLogFile`. The layout doc already named those files; nothing
exported them. The existing writers now use them too.

Zero new dependencies: raw ANSI and node:readline, as before.

Proof: a real `createSupervisor().run` journalled by `createFileRunContext`,
then `node dist/tui/bin.js <root> --once` renders its three workers, token
bars, latency histogram, and the steer appended by `writeWorkerSteer`.
---
 README.md                           |    2 +
 docs/api/README.md                  |    1 +
 docs/api/primitive-catalog.md       |   20 +-
 docs/api/runtime.md                 |   77 ++
 docs/api/tui.md                     |  719 ++++++++++++++++
 package.json                        |    8 +-
 scripts/gen-primitive-catalog.mjs   |    1 +
 src/runtime/index.ts                |    3 +
 src/runtime/supervise/run-layout.ts |   33 +-
 src/tui/bin.ts                      |   17 +
 src/tui/index.ts                    |   40 +
 src/tui/top-app.ts                  |  415 ++++++++++
 src/tui/top-model.ts                | 1175 +++++++++++++++++++++++++++
 tests/tui/top-model.test.ts         |  447 ++++++++++
 tsdown.config.ts                    |    2 +
 typedoc.json                        |    6 +-
 vitest.config.ts                    |    4 +
 17 files changed, 2960 insertions(+), 10 deletions(-)
 create mode 100644 docs/api/tui.md
 create mode 100644 src/tui/bin.ts
 create mode 100644 src/tui/index.ts
 create mode 100644 src/tui/top-app.ts
 create mode 100644 src/tui/top-model.ts
 create mode 100644 tests/tui/top-model.test.ts

diff --git a/README.md b/README.md
index eb31294d..e0e47cb6 100644
--- a/README.md
+++ b/README.md
@@ -451,6 +451,8 @@ The general-purpose pieces, by import path. Every export with its one-line summa
 | Conversations + durability | Multi-turn two-agent sessions with SQL-backed resume (D1/pg/sqlite/libSQL adapters) | `/conversation` |
 | Training/eval adapter | Package the same runtime program as a PrimeIntellect Verifiers environment; import its traces back | `/primeintellect` |
 
+| Watching live runs | A terminal view of every supervisor run in a workspace — workers, spend, tokens, latency, plus steer and cancel (`agent-runtime-top`) | `/tui` |
+
 Remaining subpaths: `/agent`, `/profiles`, `/platform`, `/analyst-loop`, `/environment-provider`, `/testing` (validated fixture records for consumer tests).
 
 ## Examples
diff --git a/docs/api/README.md b/docs/api/README.md
index c930d421..94ec3d41 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -22,3 +22,4 @@
 - [runtime](runtime.md)
 - [testing](testing.md)
 - [tool-loop](tool-loop.md)
+- [tui](tui.md)
diff --git a/docs/api/primitive-catalog.md b/docs/api/primitive-catalog.md
index 15bed704..060abe41 100644
--- a/docs/api/primitive-catalog.md
+++ b/docs/api/primitive-catalog.md
@@ -508,7 +508,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 166 exports.
 
 ### Execution kernel — recursive atom, supervision, executors, round-synchronous loop
 
-Import from `@tangle-network/agent-runtime/kernel` — 685 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 688 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -604,6 +604,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 685 exports.
 | `jjWorkspace` | function | A jj-backed `Workspace` (Jujutsu, colocated with git for the durable remote). |
 | `leaderboard` | function | Aggregate a fleet of records into the ranked, multi-axis report. Pure — no IO, deterministic. |
 | `legacySupervisorRunDir` | function | Where a pre-rename writer put the same run (`<root>/.loops/supervisor/<id>`). Readers that must |
+| `legacySupervisorRunsRoot` | function | The pre-rename runs root (`<root>/.loops/supervisor`). Only readers that ENUMERATE historical |
 | `loadSpawnForest` | function | Load every journal tree owned by one recursive supervision run and flatten its nodes/events. |
 | `localSandboxClient` | function | A same-host `SandboxClient` adapter with no process isolation. Local MCP is |
 | `localShell` | function | Host-process `Shell`: run a command via `execFile`, resolving `{ stdout, stderr, code }` (never throws on non-zero exit). |
@@ -697,6 +698,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 685 exports.
 | `supervisorInstructions` | function | The supervisor SKILL — the how-to the supervisor reads (its system prompt). THE optimizable |
 | `supervisorRunDir` | function | The run directory every artifact of one supervisor run lives under. |
 | `supervisorRunsRoot` | function | The root every supervisor run of one workspace lives under. |
+| `supervisorWorkersDir` | function | The directory holding every per-worker file of one run (inboxes and control-event logs). |
 | `timerAt` | function | Build a `timer` spec from a DURATION. The instant is resolved once, at arm time — a resumed |
 | `trajectoryReport` | function | Reconstruct the whole spawn tree for `root` with per-node + rolled-up `Spend`. Reads the |
 | `validateWaitSpec` | function | Structural validation, independent of the run. Returns null when the spec is usable. |
@@ -706,6 +708,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 685 exports.
 | `watchTrace` | function | Subscribe to a `TraceSource` and run the streaming detectors over its live spans. Returns an |
 | `widen` | function | `widen(spec)` — the streaming spawn-on-completion driver. Spawns the seed lineages, then REACTS |
 | `withUntrackedArtifacts` | function | Wrap a `Workspace` so every `materialize` (the per-worker `git clone` inside |
+| `workerControlLogFile` | function | The best-effort control-event log for one worker (`workers/<label>.ndjson`) — delivery |
 | `workerFromBackend` | function | Build the worker seam from a backend (WHERE workers run) + an optional completion oracle (the |
 | `workerInboxFile` | function | The durable inbox file for one worker of one run. |
 | `workerInboxFileFromEventDir` | function | Same, addressed from an already-known run directory (the reader's usual entry point). |
@@ -1408,6 +1411,21 @@ Import from `@tangle-network/agent-runtime/mcp` — 207 exports.
 
 **Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AnalystRegistry`, `CappedDelegationTrace`, `CoderOutput`, `CoderReview`, `CoordinationToolsOptions`, `CreateKbGateOptions`, `CreateMemoryToolServerOptions`, `CreateWorktreeOptions`, `DelegateCodeArgs`, `DelegateCodeResult`, `DelegateFeedbackArgs`, `DelegateFeedbackHandlerOptions`, `DelegateFeedbackResult`, `DelegateHandlerOptions`, `DelegateResearchArgs`, `DelegateResearchConfig`, `DelegateResearchResult`, `DelegateRunCtx`, `DelegateUiAuditArgs`, `DelegateUiAuditConfig`, `DelegateUiAuditHandlerOptions`, `DelegateUiAuditResult`, `DelegationError`, `DelegationExecutor`, `DelegationFeedbackSnapshot`, `DelegationHistoryArgs`, `DelegationHistoryEntry`, `DelegationHistoryHandlerOptions`, `DelegationHistoryResult`, `DelegationProgress`, `DelegationResumeContext`, `DelegationRunContext`, `DelegationStatusArgs`, `DelegationStatusHandlerOptions`, `DelegationStatusResult`, `DelegationStore`, `DelegationTaskQueueOptions`, `DelegationTraceCaps`, `DetachedSessionDelegateOptions`, `DetachedTurn`, `DetachedTurnResumeDriverOptions`, `DetectExecutorArgs`, `DiffOptions`, `DiffResult`, `FactCandidate`, `FactJudge`, `FactJudgeVerdict`, `FeedbackEvent`, `FeedbackRating`, `FeedbackRefersTo`, `FeedbackStore`, `FileDelegationStoreOptions`, `FleetWorkspaceExecutorOptions`, `InProcessExecutorDescribePlacement`, `InProcessExecutorOptions`, `KbGateResult`, `LocalHarnessResult`, `McpServer`, `McpServerOptions`, `Question`, `QuestionOption`, `QuestionRecord`, `RemoveWorktreeOptions`, `RunDetachedTurnOptions`, `RunLocalHarnessOptions`, `SettleDetachedCoderTurnOptions`, `SiblingSandboxExecutorOptions`, `StdioToolServer`, `StdioToolServerOptions`, `SubmitInput`, `SubmitOutput`, `TraceContext`, `WorktreeHandle`, `CoderDelegate`, `DelegationProfile`, `DelegationStatus`, `DetachedWinnerSelection`, `MakeWorkerAgent`, `QuestionDecision`, `QuestionLevel`, `QuestionPolicy`, `QuestionUrgency`, `ResearchSource`, `StdioToolDescriptor`, `UiAuditLensFilter`.
 
+### Supervisor TUI — live terminal view over the on-disk run layout
+
+Import from `@tangle-network/agent-runtime/tui` — 18 exports.
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `loadTopSnapshot` | function | Read every supervisor run under one workspace into a single point-in-time snapshot. |
+| `renderTopFrame` | function | Render one snapshot to an ANSI frame. Use this when nothing needs to be clickable. |
+| `renderTopFrameWithLayout` | function | Render one snapshot, returning the frame together with the row→entity map a mouse click resolves |
+| `renderTopOnce` | function | Render exactly one frame and return it. This is the non-interactive path — `--once`, a pipe, a |
+| `runTopApp` | function | Run the TUI. With a TTY on both ends and no `--once` this takes over the terminal until `q`; |
+| `TopSnapshot` | interface | The read side of the supervisor-run TUI: turn the on-disk run layout into one `TopSnapshot`, and |
+
+**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `BudgetStats`, `Distribution`, `RenderedTopFrame`, `RenderOptions`, `RenderTarget`, `SpendStats`, `SupervisorBase`, `SupervisorTotals`, `SupervisorView`, `TopAppOptions`, `WorkerView`, `TopJournalEvent`.
+
 ## 2. agent-eval — substrate primitives to REUSE
 
 The scoring/measurement/judge substrate. **Do NOT re-implement a judge, an authenticity check, a verifier, a statistics routine, a profile-matrix runner, or usage extraction** — import them from here. The category→subpath mapping is curated; the symbols are generated.
diff --git a/docs/api/runtime.md b/docs/api/runtime.md
index 2580eff3..37ccbede 100644
--- a/docs/api/runtime.md
+++ b/docs/api/runtime.md
@@ -11716,6 +11716,12 @@ Stable, caller-owned cli-bridge session id for harness-side resume. Defaults
 Per-resume-turn inference cap before the worker settles on its last output.
  Mirrors `routerToolsInlineExecutor.maxTurns`; default 200 (runaway backstop).
 
+##### activityWindow?
+
+> `optional` **activityWindow?**: `number`
+
+Newest-last activity window `progress()` reports. Default 12 (matches `PiSeam`).
+
 ***
 
 ### ProviderSeam
@@ -13896,6 +13902,16 @@ False when the call was observed but its original arguments were unavailable.
 
 > `readonly` `optional` **status?**: `"error"` \| `"ok"`
 
+##### statusCaptured?
+
+> `readonly` `optional` **statusCaptured?**: `boolean`
+
+False when the source observed the call being MADE but never observed it finishing — so no
+outcome is knowable, not even by default. Some wires (cli-bridge's OpenAI-shaped `tool_calls`
+deltas) report the model's DECISION to call a tool and never report the call's result at all.
+Without this marker such a call would project as `status: 'ok'` and be counted as a success in
+every downstream error-rate read. Set it and the span carries NO status, which is the truth.
+
 ##### result?
 
 > `readonly` `optional` **result?**: `unknown`
@@ -23557,6 +23573,25 @@ here anymore.
 
 ***
 
+### legacySupervisorRunsRoot()
+
+> **legacySupervisorRunsRoot**(`rootDir`): `string`
+
+The pre-rename runs root (`<root>/.loops/supervisor`). Only readers that ENUMERATE historical
+runs need this — the per-id form is [legacySupervisorRunDir](#legacysupervisorrundir). Nothing writes here.
+
+#### Parameters
+
+##### rootDir
+
+`string`
+
+#### Returns
+
+`string`
+
+***
+
 ### safeWorkerFile()
 
 > **safeWorkerFile**(`label`): `string`
@@ -23575,6 +23610,24 @@ A worker label reduced to a safe filename stem. Empty labels get a stable fallba
 
 ***
 
+### supervisorWorkersDir()
+
+> **supervisorWorkersDir**(`eventDir`): `string`
+
+The directory holding every per-worker file of one run (inboxes and control-event logs).
+
+#### Parameters
+
+##### eventDir
+
+`string`
+
+#### Returns
+
+`string`
+
+***
+
 ### workerInboxFile()
 
 > **workerInboxFile**(`rootDir`, `supervisorId`, `worker`): `string`
@@ -23623,6 +23676,30 @@ Same, addressed from an already-known run directory (the reader's usual entry po
 
 ***
 
+### workerControlLogFile()
+
+> **workerControlLogFile**(`eventDir`, `worker`): `string`
+
+The best-effort control-event log for one worker (`workers/<label>.ndjson`) — delivery
+bookkeeping for steers, plus whatever lifecycle events a writer chooses to append. Distinct from
+the inbox: the inbox is the durable down-leg queue, this is the record of what happened to it.
+
+#### Parameters
+
+##### eventDir
+
+`string`
+
+##### worker
+
+`string`
+
+#### Returns
+
+`string`
+
+***
+
 ### writeWorkerSteer()
 
 > **writeWorkerSteer**(`rootDir`, `supervisorId`, `worker`, `message`, `source?`): `object`
diff --git a/docs/api/tui.md b/docs/api/tui.md
new file mode 100644
index 00000000..a5b7b62e
--- /dev/null
+++ b/docs/api/tui.md
@@ -0,0 +1,719 @@
+[**@tangle-network/agent-runtime**](README.md)
+
+***
+
+[@tangle-network/agent-runtime](README.md) / tui
+
+# tui
+
+## Interfaces
+
+### TopAppOptions
+
+**`Experimental`**
+
+How the app was invoked. Defaults read `process.argv` / `process.cwd()`.
+
+#### Properties
+
+##### argv?
+
+> `readonly` `optional` **argv?**: readonly `string`[]
+
+**`Experimental`**
+
+##### cwd?
+
+> `readonly` `optional` **cwd?**: `string`
+
+**`Experimental`**
+
+***
+
+### TopSnapshot
+
+#### Properties
+
+##### root
+
+> `readonly` **root**: `string`
+
+##### generatedAt
+
+> `readonly` **generatedAt**: `number`
+
+##### supervisors
+
+> `readonly` **supervisors**: [`SupervisorView`](#supervisorview)[]
+
+***
+
+### SupervisorBase
+
+#### Extended by
+
+- [`SupervisorView`](#supervisorview)
+
+#### Properties
+
+##### id
+
+> `readonly` **id**: `string`
+
+##### status
+
+> `readonly` **status**: `string`
+
+##### task
+
+> `readonly` **task**: `string`
+
+##### workspaceDir
+
+> `readonly` **workspaceDir**: `string`
+
+##### budget
+
+> `readonly` **budget**: `number`
+
+##### verifyCmd?
+
+> `readonly` `optional` **verifyCmd?**: `string`
+
+##### workerModel?
+
+> `readonly` `optional` **workerModel?**: `string`
+
+##### driverModel?
+
+> `readonly` `optional` **driverModel?**: `string`
+
+##### verdict?
+
+> `readonly` `optional` **verdict?**: `string`
+
+##### progress?
+
+> `readonly` `optional` **progress?**: `string`
+
+##### startedAt?
+
+> `readonly` `optional` **startedAt?**: `string`
+
+##### completedAt?
+
+> `readonly` `optional` **completedAt?**: `string`
+
+##### maxSandboxes?
+
+> `readonly` `optional` **maxSandboxes?**: `number`
+
+##### maxLifetimeSeconds?
+
+> `readonly` `optional` **maxLifetimeSeconds?**: `number`
+
+##### idleTimeoutSeconds?
+
+> `readonly` `optional` **idleTimeoutSeconds?**: `number`
+
+##### maxUsd?
+
+> `readonly` `optional` **maxUsd?**: `number`
+
+##### maxDepth?
+
+> `readonly` `optional` **maxDepth?**: `number`
+
+***
+
+### SupervisorView
+
+#### Extends
+
+- [`SupervisorBase`](#supervisorbase)
+
+#### Properties
+
+##### id
+
+> `readonly` **id**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`id`](#id)
+
+##### status
+
+> `readonly` **status**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`status`](#status)
+
+##### task
+
+> `readonly` **task**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`task`](#task)
+
+##### workspaceDir
+
+> `readonly` **workspaceDir**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`workspaceDir`](#workspacedir)
+
+##### budget
+
+> `readonly` **budget**: `number`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`budget`](#budget)
+
+##### verifyCmd?
+
+> `readonly` `optional` **verifyCmd?**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`verifyCmd`](#verifycmd)
+
+##### workerModel?
+
+> `readonly` `optional` **workerModel?**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`workerModel`](#workermodel)
+
+##### driverModel?
+
+> `readonly` `optional` **driverModel?**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`driverModel`](#drivermodel)
+
+##### verdict?
+
+> `readonly` `optional` **verdict?**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`verdict`](#verdict)
+
+##### progress?
+
+> `readonly` `optional` **progress?**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`progress`](#progress)
+
+##### startedAt?
+
+> `readonly` `optional` **startedAt?**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`startedAt`](#startedat)
+
+##### completedAt?
+
+> `readonly` `optional` **completedAt?**: `string`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`completedAt`](#completedat)
+
+##### maxSandboxes?
+
+> `readonly` `optional` **maxSandboxes?**: `number`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`maxSandboxes`](#maxsandboxes)
+
+##### maxLifetimeSeconds?
+
+> `readonly` `optional` **maxLifetimeSeconds?**: `number`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`maxLifetimeSeconds`](#maxlifetimeseconds)
+
+##### idleTimeoutSeconds?
+
+> `readonly` `optional` **idleTimeoutSeconds?**: `number`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`idleTimeoutSeconds`](#idletimeoutseconds)
+
+##### maxUsd?
+
+> `readonly` `optional` **maxUsd?**: `number`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`maxUsd`](#maxusd)
+
+##### maxDepth?
+
+> `readonly` `optional` **maxDepth?**: `number`
+
+###### Inherited from
+
+[`SupervisorBase`](#supervisorbase).[`maxDepth`](#maxdepth)
+
+##### stateDir
+
+> `readonly` **stateDir**: `string`
+
+##### resultSpentUsd?
+
+> `readonly` `optional` **resultSpentUsd?**: `number`
+
+##### resultSpentTokens?
+
+> `readonly` `optional` **resultSpentTokens?**: `number`
+
+##### workers
+
+> `readonly` **workers**: [`WorkerView`](#workerview)[]
+
+##### progressTail
+
+> `readonly` **progressTail**: `string`[]
+
+##### journalTail
+
+> `readonly` **journalTail**: [`TopJournalEvent`](#topjournalevent)[]
+
+##### driverSpend
+
+> `readonly` **driverSpend**: [`SpendStats`](#spendstats)
+
+##### totals
+
+> `readonly` **totals**: [`SupervisorTotals`](#supervisortotals)
+
+***
+
+### WorkerView
+
+#### Properties
+
+##### id
+
+> `readonly` **id**: `string`
+
+##### label
+
+> `readonly` **label**: `string`
+
+##### cwd?
+
+> `readonly` `optional` **cwd?**: `string`
+
+##### eventFile?
+
+> `readonly` `optional` **eventFile?**: `string`
+
+##### parent?
+
+> `readonly` `optional` **parent?**: `string`
+
+##### runtime?
+
+> `readonly` `optional` **runtime?**: `string`
+
+##### status
+
+> `readonly` **status**: `"done"` \| `"down"` \| `"running"` \| `"cancelled"`
+
+##### verdict?
+
+> `readonly` `optional` **verdict?**: `string`
+
+##### infra?
+
+> `readonly` `optional` **infra?**: `boolean`
+
+##### startedAt?
+
+> `readonly` `optional` **startedAt?**: `string`
+
+##### endedAt?
+
+> `readonly` `optional` **endedAt?**: `string`
+
+##### latencyMs
+
+> `readonly` **latencyMs**: `number`
+
+##### budget?
+
+> `readonly` `optional` **budget?**: [`BudgetStats`](#budgetstats)
+
+##### spend
+
+> `readonly` **spend**: [`SpendStats`](#spendstats)
+
+##### metered
+
+> `readonly` **metered**: [`SpendStats`](#spendstats)
+
+##### liveTail
+
+> `readonly` **liveTail**: `string`[]
+
+##### outRef?
+
+> `readonly` `optional` **outRef?**: `string`
+
+##### reason?
+
+> `readonly` `optional` **reason?**: `string`
+
+***
+
+### SupervisorTotals
+
+#### Properties
+
+##### workers
+
+> `readonly` **workers**: `number`
+
+##### running
+
+> `readonly` **running**: `number`
+
+##### done
+
+> `readonly` **done**: `number`
+
+##### down
+
+> `readonly` **down**: `number`
+
+##### cancelled
+
+> `readonly` **cancelled**: `number`
+
+##### inFlight
+
+> `readonly` **inFlight**: `number`
+
+##### settled
+
+> `readonly` **settled**: `number`
+
+##### tokensInput
+
+> `readonly` **tokensInput**: `number`
+
+##### tokensOutput
+
+> `readonly` **tokensOutput**: `number`
+
+##### tokensTotal
+
+> `readonly` **tokensTotal**: `number`
+
+##### usd
+
+> `readonly` **usd**: `number`
+
+##### latencyMs
+
+> `readonly` **latencyMs**: `number`
+
+##### workerLatency
+
+> `readonly` **workerLatency**: [`Distribution`](#distribution)
+
+***
+
+### Distribution
+
+#### Properties
+
+##### n
+
+> `readonly` **n**: `number`
+
+##### min
+
+> `readonly` **min**: `number`
+
+##### median
+
+> `readonly` **median**: `number`
+
+##### p90
+
+> `readonly` **p90**: `number`
+
+##### max
+
+> `readonly` **max**: `number`
+
+***
+
+### BudgetStats
+
+#### Properties
+
+##### maxIterations?
+
+> `readonly` `optional` **maxIterations?**: `number`
+
+##### maxTokens?
+
+> `readonly` `optional` **maxTokens?**: `number`
+
+##### maxUsd?
+
+> `readonly` `optional` **maxUsd?**: `number`
+
+***
+
+### SpendStats
+
+#### Properties
+
+##### iterations
+
+> `readonly` **iterations**: `number`
+
+##### tokensInput
+
+> `readonly` **tokensInput**: `number`
+
+##### tokensOutput
+
+> `readonly` **tokensOutput**: `number`
+
+##### usd
+
+> `readonly` **usd**: `number`
+
+##### ms
+
+> `readonly` **ms**: `number`
+
+***
+
+### RenderOptions
+
+#### Properties
+
+##### width?
+
+> `readonly` `optional` **width?**: `number`
+
+##### height?
+
+> `readonly` `optional` **height?**: `number`
+
+##### color?
+
+> `readonly` `optional` **color?**: `boolean`
+
+##### selectedSupervisorId?
+
+> `readonly` `optional` **selectedSupervisorId?**: `string`
+
+##### selectedWorkerId?
+
+> `readonly` `optional` **selectedWorkerId?**: `string`
+
+##### focus?
+
+> `readonly` `optional` **focus?**: `"supervisors"` \| `"workers"`
+
+##### mode?
+
+> `readonly` `optional` **mode?**: `"log"` \| `"overview"` \| `"detail"`
+
+##### notice?
+
+> `readonly` `optional` **notice?**: `string`
+
+##### steerInput?
+
+> `readonly` `optional` **steerInput?**: `object`
+
+###### active
+
+> `readonly` **active**: `boolean`
+
+###### value
+
+> `readonly` **value**: `string`
+
+###### workerLabel?
+
+> `readonly` `optional` **workerLabel?**: `string`
+
+***
+
+### RenderTarget
+
+#### Properties
+
+##### row
+
+> `readonly` **row**: `number`
+
+##### kind
+
+> `readonly` **kind**: `"worker"` \| `"supervisor"`
+
+##### id
+
+> `readonly` **id**: `string`
+
+##### supervisorId?
+
+> `readonly` `optional` **supervisorId?**: `string`
+
+***
+
+### RenderedTopFrame
+
+#### Properties
+
+##### frame
+
+> `readonly` **frame**: `string`
+
+##### targets
+
+> `readonly` **targets**: [`RenderTarget`](#rendertarget)[]
+
+## Type Aliases
+
+### TopJournalEvent
+
+> **TopJournalEvent** = \{ `kind`: `"spawned"`; `id`: `string`; `parent?`: `string`; `label?`: `string`; `budget?`: `unknown`; `runtime?`: `string`; `seq?`: `number`; `at?`: `string`; \} \| \{ `kind`: `"settled"`; `id`: `string`; `status?`: `string`; `outRef?`: `string`; `verdict?`: `unknown`; `spent?`: `unknown`; `infra?`: `boolean`; `seq?`: `number`; `at?`: `string`; \} \| \{ `kind`: `"cancelled"`; `id`: `string`; `reason?`: `string`; `seq?`: `number`; `at?`: `string`; \} \| \{ `kind`: `"metered"`; `id`: `string`; `spend?`: `unknown`; `seq?`: `number`; `at?`: `string`; \}
+
+## Functions
+
+### renderTopOnce()
+
+> **renderTopOnce**(`options?`): `string`
+
+**`Experimental`**
+
+Render exactly one frame and return it. This is the non-interactive path — `--once`, a pipe, a
+test — so it never touches raw mode, the alternate screen, or `process.exit`.
+
+#### Parameters
+
+##### options?
+
+[`TopAppOptions`](#topappoptions) = `{}`
+
+#### Returns
+
+`string`
+
+***
+
+### runTopApp()
+
+> **runTopApp**(`options?`): `void`
+
+**`Experimental`**
+
+Run the TUI. With a TTY on both ends and no `--once` this takes over the terminal until `q`;
+otherwise it writes a single frame to stdout and returns.
+
+#### Parameters
+
+##### options?
+
+[`TopAppOptions`](#topappoptions) = `{}`
+
+#### Returns
+
+`void`
+
+***
+
+### loadTopSnapshot()
+
+> **loadTopSnapshot**(`rootDir`, `now?`): [`TopSnapshot`](#topsnapshot)
+
+Read every supervisor run under one workspace into a single point-in-time snapshot.
+
+Pure with respect to the process: it only reads, and every unreadable or half-written file is
+skipped rather than thrown on — an operator view must survive a writer mid-append. `now` is
+injectable so elapsed time is deterministic under test.
+
+#### Parameters
+
+##### rootDir
+
+`string`
+
+##### now?
+
+`number` = `...`
+
+#### Returns
+
+[`TopSnapshot`](#topsnapshot)
+
+***
+
+### renderTopFrame()
+
+> **renderTopFrame**(`snapshot`, `options?`): `string`
+
+Render one snapshot to an ANSI frame. Use this when nothing needs to be clickable.
+
+#### Parameters
+
+##### snapshot
+
+[`TopSnapshot`](#topsnapshot)
+
+##### options?
+
+[`RenderOptions`](#renderoptions) = `{}`
+
+#### Returns
+
+`string`
+
+***
+
+### renderTopFrameWithLayout()
+
+> **renderTopFrameWithLayout**(`snapshot`, `options?`): [`RenderedTopFrame`](#renderedtopframe)
+
+Render one snapshot, returning the frame together with the row→entity map a mouse click resolves
+against. The layout is the only thing that knows which row is which run or worker, so emitting it
+alongside the text is what keeps click handling out of the renderer.
+
+#### Parameters
+
+##### snapshot
+
+[`TopSnapshot`](#topsnapshot)
+
+##### options?
+
+[`RenderOptions`](#renderoptions) = `{}`
+
+#### Returns
+
+[`RenderedTopFrame`](#renderedtopframe)
diff --git a/package.json b/package.json
index 6db0dced..4f23a16c 100644
--- a/package.json
+++ b/package.json
@@ -93,12 +93,18 @@
       "types": "./dist/mcp/index.d.ts",
       "import": "./dist/mcp/index.js",
       "default": "./dist/mcp/index.js"
+    },
+    "./tui": {
+      "types": "./dist/tui/index.d.ts",
+      "import": "./dist/tui/index.js",
+      "default": "./dist/tui/index.js"
     }
   },
   "bin": {
     "agent-runtime-mcp": "./dist/mcp/bin.js",
     "agent-runtime-memory-mcp": "./dist/mcp/memory-bin.js",
-    "agent-runtime-loop": "./dist/loop-runner-bin.js"
+    "agent-runtime-loop": "./dist/loop-runner-bin.js",
+    "agent-runtime-top": "./dist/tui/bin.js"
   },
   "files": [
     "dist",
diff --git a/scripts/gen-primitive-catalog.mjs b/scripts/gen-primitive-catalog.mjs
index 5693687f..843ddaee 100644
--- a/scripts/gen-primitive-catalog.mjs
+++ b/scripts/gen-primitive-catalog.mjs
@@ -77,6 +77,7 @@ const ownSurfaceLabels = {
   './candidate-execution': 'Candidate execution — immutable prepare, run, grade, and receipt',
   './testing': 'Testing fixtures — validated Runtime wire records',
   './mcp': 'MCP servers — delegate / coordination / detached-session',
+  './tui': 'Supervisor TUI — live terminal view over the on-disk run layout',
 }
 // SUBSTRATE surface (agent-eval): the curated category -> exports-map subpath map. These
 // are the reuse surfaces the canonical doc points agents at; the SYMBOLS under each are
diff --git a/src/runtime/index.ts b/src/runtime/index.ts
index 9ad84e47..5fa78690 100644
--- a/src/runtime/index.ts
+++ b/src/runtime/index.ts
@@ -669,11 +669,14 @@ export {
 // writer contract is published alongside its reader.
 export {
   legacySupervisorRunDir,
+  legacySupervisorRunsRoot,
   readWorkerSteerRequests,
   safeWorkerFile,
   supervisorRunDir,
   supervisorRunsRoot,
+  supervisorWorkersDir,
   type WorkerSteerRequest,
+  workerControlLogFile,
   workerInboxFile,
   workerInboxFileFromEventDir,
   writeWorkerSteer,
diff --git a/src/runtime/supervise/run-layout.ts b/src/runtime/supervise/run-layout.ts
index 366c26d6..e2f985b1 100644
--- a/src/runtime/supervise/run-layout.ts
+++ b/src/runtime/supervise/run-layout.ts
@@ -64,7 +64,15 @@ export function supervisorRunDir(rootDir: string, id: string): string {
  * here anymore.
  */
 export function legacySupervisorRunDir(rootDir: string, id: string): string {
-  return join(resolve(rootDir), '.loops', 'supervisor', id)
+  return join(legacySupervisorRunsRoot(rootDir), id)
+}
+
+/**
+ * The pre-rename runs root (`<root>/.loops/supervisor`). Only readers that ENUMERATE historical
+ * runs need this — the per-id form is {@link legacySupervisorRunDir}. Nothing writes here.
+ */
+export function legacySupervisorRunsRoot(rootDir: string): string {
+  return join(resolve(rootDir), '.loops', 'supervisor')
 }
 
 /** A worker label reduced to a safe filename stem. Empty labels get a stable fallback. */
@@ -73,6 +81,11 @@ export function safeWorkerFile(label: string): string {
   return safe.length > 0 ? safe : 'worker'
 }
 
+/** The directory holding every per-worker file of one run (inboxes and control-event logs). */
+export function supervisorWorkersDir(eventDir: string): string {
+  return join(eventDir, 'workers')
+}
+
 /** The durable inbox file for one worker of one run. */
 export function workerInboxFile(rootDir: string, supervisorId: string, worker: string): string {
   return workerInboxFileFromEventDir(supervisorRunDir(rootDir, supervisorId), worker)
@@ -80,7 +93,16 @@ export function workerInboxFile(rootDir: string, supervisorId: string, worker: s
 
 /** Same, addressed from an already-known run directory (the reader's usual entry point). */
 export function workerInboxFileFromEventDir(eventDir: string, worker: string): string {
-  return join(eventDir, 'workers', `${safeWorkerFile(worker)}.inbox.ndjson`)
+  return join(supervisorWorkersDir(eventDir), `${safeWorkerFile(worker)}.inbox.ndjson`)
+}
+
+/**
+ * The best-effort control-event log for one worker (`workers/<label>.ndjson`) — delivery
+ * bookkeeping for steers, plus whatever lifecycle events a writer chooses to append. Distinct from
+ * the inbox: the inbox is the durable down-leg queue, this is the record of what happened to it.
+ */
+export function workerControlLogFile(eventDir: string, worker: string): string {
+  return join(supervisorWorkersDir(eventDir), `${safeWorkerFile(worker)}.ndjson`)
 }
 
 /**
@@ -99,7 +121,7 @@ export function writeWorkerSteer(
   const trimmed = message.trim()
   if (!trimmed) throw new Error('steer message is empty')
   const dir = supervisorRunDir(rootDir, supervisorId)
-  mkdirSync(join(dir, 'workers'), { recursive: true })
+  mkdirSync(supervisorWorkersDir(dir), { recursive: true })
   const request: WorkerSteerRequest = {
     id: randomUUID(),
     at: new Date().toISOString(),
@@ -151,10 +173,9 @@ function appendWorkerControlEvent(
   event: Record<string, unknown>,
 ): void {
   try {
-    const workersDir = join(eventDir, 'workers')
-    mkdirSync(workersDir, { recursive: true })
+    mkdirSync(supervisorWorkersDir(eventDir), { recursive: true })
     appendFileSync(
-      join(workersDir, `${safeWorkerFile(label)}.ndjson`),
+      workerControlLogFile(eventDir, label),
       `${JSON.stringify({ at: new Date().toISOString(), label, ...event })}\n`,
       'utf8',
     )
diff --git a/src/tui/bin.ts b/src/tui/bin.ts
new file mode 100644
index 00000000..85b2ac75
--- /dev/null
+++ b/src/tui/bin.ts
@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+/**
+ * `agent-runtime-top` — watch the supervisor runs of one workspace.
+ *
+ *   agent-runtime-top [root] [--once] [--no-color] [--detail] [--log]
+ *
+ * `root` is the workspace whose `.agent/supervisor/` runs are shown; it defaults to the current
+ * directory. With a TTY on both ends the view refreshes every second and takes the keys it prints
+ * in its header; otherwise (a pipe, `--once`) it writes one frame and exits.
+ *
+ * @experimental
+ */
+
+import { runTopApp } from './top-app'
+
+runTopApp()
diff --git a/src/tui/index.ts b/src/tui/index.ts
new file mode 100644
index 00000000..a1d0f5bf
--- /dev/null
+++ b/src/tui/index.ts
@@ -0,0 +1,40 @@
+/**
+ * `@tangle-network/agent-runtime/tui` — the terminal view over live supervisor runs.
+ *
+ * A read-only renderer plus two write-back controls, over the same `<root>/.agent/supervisor/<id>`
+ * layout `../runtime/supervise/run-layout` defines. It ships here rather than as its own package
+ * because the runtime is what WRITES the state it renders: a separately-versioned viewer would
+ * drift from the layout it reads, which is the exact failure a client and server versioning
+ * independently produces.
+ *
+ * Zero third-party dependencies — raw ANSI and `node:readline` keypresses, nothing else.
+ *
+ * ```ts
+ * import { loadTopSnapshot, renderTopFrame } from '@tangle-network/agent-runtime/tui'
+ *
+ * process.stdout.write(renderTopFrame(loadTopSnapshot(process.cwd()), { width: 132 }))
+ * ```
+ *
+ * The runnable form is the `agent-runtime-top` bin: `agent-runtime-top <root> [--once] [--no-color]`.
+ *
+ * @experimental
+ */
+
+export { renderTopOnce, runTopApp, type TopAppOptions } from './top-app'
+export {
+  type BudgetStats,
+  type Distribution,
+  loadTopSnapshot,
+  type RenderedTopFrame,
+  type RenderOptions,
+  type RenderTarget,
+  renderTopFrame,
+  renderTopFrameWithLayout,
+  type SpendStats,
+  type SupervisorBase,
+  type SupervisorTotals,
+  type SupervisorView,
+  type TopJournalEvent,
+  type TopSnapshot,
+  type WorkerView,
+} from './top-model'
diff --git a/src/tui/top-app.ts b/src/tui/top-app.ts
new file mode 100644
index 00000000..9820192f
--- /dev/null
+++ b/src/tui/top-app.ts
@@ -0,0 +1,415 @@
+/**
+ * The interactive side of the supervisor-run TUI: a keypress/mouse loop over the frames
+ * `./top-model` renders, plus the two operator controls that write back to the run — steer a live
+ * worker, and request cancellation of a run.
+ *
+ * Both controls go through the owned run layout: steers via `writeWorkerSteer` (the durable inbox
+ * append), cancellation via a file inside the run directory the snapshot reported. Nothing here
+ * joins a path from the workspace root.
+ *
+ * Extracted from the `loops` repo (`src/top.ts`). The module-level singletons are the origin's
+ * shape and are kept: this drives one terminal, and `runTopApp` is its one entry point.
+ *
+ * @experimental
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { emitKeypressEvents } from 'node:readline'
+import { writeWorkerSteer } from '../runtime/supervise/run-layout'
+import {
+  loadTopSnapshot,
+  type RenderTarget,
+  renderTopFrameWithLayout,
+  type TopSnapshot,
+} from './top-model'
+
+interface UiState {
+  root: string
+  color: boolean
+  focus: 'supervisors' | 'workers'
+  mode: 'overview' | 'detail' | 'log'
+  selectedSupervisorId: string | undefined
+  selectedWorkerId: string | undefined
+  notice: string | undefined
+  steerInput: {
+    active: boolean
+    value: string
+  }
+}
+
+/** @experimental How the app was invoked. Defaults read `process.argv` / `process.cwd()`. */
+export interface TopAppOptions {
+  readonly argv?: readonly string[]
+  readonly cwd?: string
+}
+
+let state: UiState = initialState([], process.cwd())
+let snapshot: TopSnapshot = { root: state.root, generatedAt: 0, supervisors: [] }
+let targets: RenderTarget[] = []
+let timer: NodeJS.Timeout | undefined
+
+/**
+ * Render exactly one frame and return it. This is the non-interactive path — `--once`, a pipe, a
+ * test — so it never touches raw mode, the alternate screen, or `process.exit`.
+ */
+export function renderTopOnce(options: TopAppOptions = {}): string {
+  const args = [...(options.argv ?? process.argv.slice(2))]
+  state = initialState(args, options.cwd ?? process.cwd())
+  snapshot = loadTopSnapshot(state.root)
+  clampSelection()
+  return renderTopFrameWithLayout(snapshot, {
+    color: state.color,
+    width: process.stdout.columns ?? 128,
+    focus: state.focus,
+    mode: state.mode,
+    ...(state.selectedSupervisorId ? { selectedSupervisorId: state.selectedSupervisorId } : {}),
+    ...(state.selectedWorkerId ? { selectedWorkerId: state.selectedWorkerId } : {}),
+    steerInput: renderSteerInputState(),
+  }).frame
+}
+
+/**
+ * Run the TUI. With a TTY on both ends and no `--once` this takes over the terminal until `q`;
+ * otherwise it writes a single frame to stdout and returns.
+ */
+export function runTopApp(options: TopAppOptions = {}): void {
+  const args = [...(options.argv ?? process.argv.slice(2))]
+  if (!process.stdout.isTTY || !process.stdin.isTTY || args.includes('--once')) {
+    process.stdout.write(renderTopOnce(options))
+    return
+  }
+  state = initialState(args, options.cwd ?? process.cwd())
+  snapshot = loadTopSnapshot(state.root)
+  start()
+}
+
+function initialState(args: readonly string[], cwd: string): UiState {
+  const rootArg = args.find((arg) => !arg.startsWith('-'))
+  return {
+    root: resolve(rootArg ?? cwd),
+    color: Boolean(process.stdout.isTTY) && !args.includes('--no-color'),
+    focus: args.includes('--detail') ? 'workers' : 'supervisors',
+    mode: args.includes('--log') ? 'log' : args.includes('--detail') ? 'detail' : 'overview',
+    selectedSupervisorId: undefined,
+    selectedWorkerId: undefined,
+    notice: undefined,
+    steerInput: { active: false, value: '' },
+  }
+}
+
+function start(): void {
+  process.stdout.write('\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h')
+  emitKeypressEvents(process.stdin)
+  process.stdin.setRawMode(true)
+  process.stdin.resume()
+  process.stdin.on('keypress', onKey)
+  process.stdin.on('data', onData)
+  process.on('SIGINT', stop)
+  draw()
+  timer = setInterval(draw, 1000)
+}
+
+function stop(): void {
+  if (timer) clearInterval(timer)
+  process.stdin.setRawMode(false)
+  process.stdout.write('\x1b[?1000l\x1b[?1006l\x1b[?25h\x1b[?1049l')
+  process.exit(0)
+}
+
+function pauseUi(): void {
+  if (timer) {
+    clearInterval(timer)
+    timer = undefined
+  }
+  process.stdin.setRawMode(false)
+  process.stdin.pause()
+  process.stdout.write('\x1b[?1000l\x1b[?1006l\x1b[?25h\x1b[?1049l')
+}
+
+function resumeUi(): void {
+  process.stdout.write('\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h')
+  process.stdin.setRawMode(true)
+  process.stdin.resume()
+  draw()
+  timer = setInterval(draw, 1000)
+}
+
+function draw(): void {
+  snapshot = loadTopSnapshot(state.root)
+  clampSelection()
+  const rendered = renderTopFrameWithLayout(snapshot, {
+    width: process.stdout.columns ?? 128,
+    height: process.stdout.rows ?? 42,
+    color: state.color,
+    focus: state.focus,
+    mode: state.mode,
+    ...(state.notice ? { notice: state.notice } : {}),
+    ...(state.selectedSupervisorId ? { selectedSupervisorId: state.selectedSupervisorId } : {}),
+    ...(state.selectedWorkerId ? { selectedWorkerId: state.selectedWorkerId } : {}),
+    steerInput: renderSteerInputState(),
+  })
+  targets = rendered.targets
+  process.stdout.write(`\x1b[2J\x1b[H${rendered.frame}`)
+}
+
+function onKey(str: string, key: { name?: string; ctrl?: boolean }): void {
+  state.notice = undefined
+  if (key.ctrl && key.name === 'c') stop()
+  if (state.steerInput.active) {
+    handleSteerInput(str, key)
+    draw()
+    return
+  }
+  if (key.name === 'q' || key.name === 'escape') stop()
+  if (key.name === 'tab') {
+    state.focus = state.focus === 'supervisors' ? 'workers' : 'supervisors'
+  } else if (key.name === 'up') {
+    moveSelection(-1)
+  } else if (key.name === 'down') {
+    moveSelection(1)
+  } else if (key.name === 'left') {
+    moveSupervisor(-1)
+  } else if (key.name === 'right') {
+    moveSupervisor(1)
+  } else if (key.name === 'return') {
+    state.mode = 'detail'
+    state.focus = 'workers'
+  } else if (key.name === 'o') {
+    state.mode = 'overview'
+  } else if (key.name === 'l') {
+    state.mode = 'log'
+  } else if (key.name === 's') {
+    startSteerInput()
+  } else if (key.name === 'a') {
+    state.mode = 'detail'
+    openWorkerShell()
+  } else if (key.name === 'c') {
+    requestCancel()
+  }
+  draw()
+}
+
+function handleSteerInput(str: string, key: { name?: string; ctrl?: boolean }): void {
+  if (key.name === 'escape') {
+    state.steerInput = { active: false, value: '' }
+    return
+  }
+  if (key.name === 'return') {
+    submitSteerInput()
+    return
+  }
+  if (key.name === 'backspace') {
+    state.steerInput.value = state.steerInput.value.slice(0, -1)
+    return
+  }
+  if (key.ctrl && key.name === 'u') {
+    state.steerInput.value = ''
+    return
+  }
+  if (
+    key.ctrl ||
+    key.name === 'tab' ||
+    key.name === 'up' ||
+    key.name === 'down' ||
+    key.name === 'left' ||
+    key.name === 'right'
+  ) {
+    return
+  }
+  if (!str || str === '\r' || str === '\n') return
+  if ([...str].every((char) => char >= ' ' && char !== '\x7f')) state.steerInput.value += str
+}
+
+function onData(data: Buffer): void {
+  const click = parseMouse(data.toString('utf8'))
+  if (!click) return
+  const target = targets.find((candidate) => candidate.row === click.row)
+  if (!target) return
+  state.notice = undefined
+  if (target.kind === 'supervisor') {
+    state.focus = 'supervisors'
+    state.selectedSupervisorId = target.id
+    state.selectedWorkerId = undefined
+  } else {
+    state.focus = 'workers'
+    state.mode = 'detail'
+    state.selectedSupervisorId = target.supervisorId
+    state.selectedWorkerId = target.id
+  }
+  draw()
+}
+
+function startSteerInput(): void {
+  state.mode = 'detail'
+  state.focus = 'workers'
+  if (!selectedSupervisor()) {
+    state.notice = 'no supervisor selected'
+    return
+  }
+  if (!selectedWorker()) {
+    state.notice = 'no worker selected'
+    return
+  }
+  state.steerInput = { active: true, value: '' }
+}
+
+function submitSteerInput(): void {
+  const supervisor = selectedSupervisor()
+  const worker = selectedWorker()
+  const message = state.steerInput.value
+  state.steerInput = { active: false, value: '' }
+  if (!supervisor) {
+    state.notice = 'no supervisor selected'
+    return
+  }
+  if (!worker) {
+    state.notice = 'no worker selected'
+    return
+  }
+  try {
+    // The snapshot already carries the worker LABEL the layout keys inboxes by, so this is the
+    // direct durable append with no id-to-label resolution step in between.
+    const written = writeWorkerSteer(state.root, supervisor.id, worker.label, message, 'human')
+    state.notice = `steer queued for ${supervisor.id}/${written.worker}`
+  } catch (err) {
+    state.notice = `steer failed: ${err instanceof Error ? err.message : String(err)}`
+  }
+}
+
+function parseMouse(raw: string): { col: number; row: number } | undefined {
+  // ESC is the literal first byte of an SGR mouse report; matching the control character IS the
+  // parse, so the control-character rule does not apply to a terminal escape decoder.
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: SGR mouse reports begin with ESC
+  const match = /\x1b\[<(\d+);(\d+);(\d+)([mM])/.exec(raw)
+  if (match?.[4] !== 'M') return undefined
+  const col = Number(match[2])
+  const row = Number(match[3])
+  if (!Number.isFinite(col) || !Number.isFinite(row)) return undefined
+  return { col: col - 1, row: row - 1 }
+}
+
+function moveSelection(delta: number): void {
+  if (state.focus === 'supervisors') {
+    moveSupervisor(delta)
+    return
+  }
+  const supervisor = selectedSupervisor()
+  if (!supervisor || supervisor.workers.length === 0) return
+  const current = Math.max(
+    0,
+    supervisor.workers.findIndex((worker) => worker.id === state.selectedWorkerId),
+  )
+  const next = wrap(current + delta, supervisor.workers.length)
+  const worker = supervisor.workers[next]
+  if (worker) state.selectedWorkerId = worker.id
+}
+
+function moveSupervisor(delta: number): void {
+  if (snapshot.supervisors.length === 0) return
+  const current = Math.max(
+    0,
+    snapshot.supervisors.findIndex((supervisor) => supervisor.id === state.selectedSupervisorId),
+  )
+  const next = wrap(current + delta, snapshot.supervisors.length)
+  const supervisor = snapshot.supervisors[next]
+  if (!supervisor) return
+  state.selectedSupervisorId = supervisor.id
+  state.selectedWorkerId = supervisor.workers[0]?.id
+}
+
+function clampSelection(): void {
+  if (snapshot.supervisors.length === 0) {
+    state.selectedSupervisorId = undefined
+    state.selectedWorkerId = undefined
+    return
+  }
+  const supervisor = selectedSupervisor() ?? snapshot.supervisors[0]
+  if (!supervisor) return
+  state.selectedSupervisorId = supervisor.id
+  const worker =
+    supervisor.workers.find((candidate) => candidate.id === state.selectedWorkerId) ??
+    supervisor.workers[0]
+  state.selectedWorkerId = worker?.id
+}
+
+function selectedSupervisor(): TopSnapshot['supervisors'][number] | undefined {
+  return snapshot.supervisors.find((supervisor) => supervisor.id === state.selectedSupervisorId)
+}
+
+function selectedWorker(): TopSnapshot['supervisors'][number]['workers'][number] | undefined {
+  const supervisor = selectedSupervisor()
+  return supervisor?.workers.find((worker) => worker.id === state.selectedWorkerId)
+}
+
+function renderSteerInputState(): { active: boolean; value: string; workerLabel?: string } {
+  const worker = selectedWorker()
+  return {
+    active: state.steerInput.active,
+    value: state.steerInput.value,
+    ...(worker?.label ? { workerLabel: worker.label } : {}),
+  }
+}
+
+function openWorkerShell(): void {
+  const worker = selectedWorker()
+  if (!worker?.cwd) {
+    state.notice = 'no worker worktree recorded yet'
+    return
+  }
+  if (!existsSync(worker.cwd)) {
+    state.notice = `worker worktree is gone: ${worker.cwd}`
+    return
+  }
+  const shell = process.env.SHELL ?? '/bin/bash'
+  state.notice = `returned from ${worker.label}`
+  pauseUi()
+  spawnSync(shell, [], {
+    cwd: worker.cwd,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      AGENT_SUPERVISOR_ROOT: state.root,
+      AGENT_SUPERVISOR_ID: state.selectedSupervisorId ?? '',
+      AGENT_WORKER_ID: worker.id,
+      AGENT_WORKER_LABEL: worker.label,
+    },
+  })
+  resumeUi()
+}
+
+function requestCancel(): void {
+  const supervisor = selectedSupervisor()
+  if (!supervisor) {
+    state.notice = 'no supervisor selected'
+    return
+  }
+  if (supervisor.status !== 'running') {
+    state.notice = `${supervisor.id} is ${supervisor.status}; no cancel request written`
+    return
+  }
+  try {
+    mkdirSync(supervisor.stateDir, { recursive: true })
+    writeFileSync(
+      join(supervisor.stateDir, 'cancel.request.json'),
+      `${JSON.stringify(
+        {
+          at: new Date().toISOString(),
+          source: 'agent-runtime-top',
+          reason: 'operator requested cancel from TUI',
+        },
+        null,
+        2,
+      )}\n`,
+      'utf8',
+    )
+    state.notice = `cancel requested for ${supervisor.id}`
+  } catch (err) {
+    state.notice = `cancel request failed: ${err instanceof Error ? err.message : String(err)}`
+  }
+}
+
+function wrap(value: number, size: number): number {
+  return ((value % size) + size) % size
+}
diff --git a/src/tui/top-model.ts b/src/tui/top-model.ts
new file mode 100644
index 00000000..f5db9b7c
--- /dev/null
+++ b/src/tui/top-model.ts
@@ -0,0 +1,1175 @@
+/**
+ * The read side of the supervisor-run TUI: turn the on-disk run layout into one `TopSnapshot`, and
+ * render that snapshot to an ANSI frame.
+ *
+ * This module never derives a run path itself. Every directory and per-worker file it reads comes
+ * from `../runtime/supervise/run-layout` — the same module the writers use — so the reader cannot
+ * drift from the layout the way an independently-versioned copy of the contract would.
+ *
+ * Extracted from the `loops` repo (`src/top-model.ts`), which held a hand-joined copy of the
+ * layout. Rendering is deliberately unchanged: raw ANSI, zero dependencies.
+ *
+ * @experimental
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import {
+  legacySupervisorRunsRoot,
+  safeWorkerFile,
+  supervisorRunsRoot,
+  supervisorWorkersDir,
+} from '../runtime/supervise/run-layout'
+
+export interface TopSnapshot {
+  readonly root: string
+  readonly generatedAt: number
+  readonly supervisors: SupervisorView[]
+}
+
+export interface SupervisorBase {
+  readonly id: string
+  readonly status: string
+  readonly task: string
+  readonly workspaceDir: string
+  readonly budget: number
+  readonly verifyCmd?: string
+  readonly workerModel?: string
+  readonly driverModel?: string
+  readonly verdict?: string
+  readonly progress?: string
+  readonly startedAt?: string
+  readonly completedAt?: string
+  readonly maxSandboxes?: number
+  readonly maxLifetimeSeconds?: number
+  readonly idleTimeoutSeconds?: number
+  readonly maxUsd?: number
+  readonly maxDepth?: number
+}
+
+export interface SupervisorView extends SupervisorBase {
+  readonly stateDir: string
+  readonly resultSpentUsd?: number
+  readonly resultSpentTokens?: number
+  readonly workers: WorkerView[]
+  readonly progressTail: string[]
+  readonly journalTail: TopJournalEvent[]
+  readonly driverSpend: SpendStats
+  readonly totals: SupervisorTotals
+}
+
+export interface WorkerView {
+  readonly id: string
+  readonly label: string
+  readonly cwd?: string
+  readonly eventFile?: string
+  readonly parent?: string
+  readonly runtime?: string
+  readonly status: 'running' | 'done' | 'down' | 'cancelled'
+  readonly verdict?: string
+  readonly infra?: boolean
+  readonly startedAt?: string
+  readonly endedAt?: string
+  readonly latencyMs: number
+  readonly budget?: BudgetStats
+  readonly spend: SpendStats
+  readonly metered: SpendStats
+  readonly liveTail: string[]
+  readonly outRef?: string
+  readonly reason?: string
+}
+
+export interface SupervisorTotals {
+  readonly workers: number
+  readonly running: number
+  readonly done: number
+  readonly down: number
+  readonly cancelled: number
+  readonly inFlight: number
+  readonly settled: number
+  readonly tokensInput: number
+  readonly tokensOutput: number
+  readonly tokensTotal: number
+  readonly usd: number
+  readonly latencyMs: number
+  readonly workerLatency: Distribution
+}
+
+export interface Distribution {
+  readonly n: number
+  readonly min: number
+  readonly median: number
+  readonly p90: number
+  readonly max: number
+}
+
+export interface BudgetStats {
+  readonly maxIterations?: number
+  readonly maxTokens?: number
+  readonly maxUsd?: number
+}
+
+export interface SpendStats {
+  readonly iterations: number
+  readonly tokensInput: number
+  readonly tokensOutput: number
+  readonly usd: number
+  readonly ms: number
+}
+
+export type TopJournalEvent =
+  | {
+      readonly kind: 'spawned'
+      readonly id: string
+      readonly parent?: string
+      readonly label?: string
+      readonly budget?: unknown
+      readonly runtime?: string
+      readonly seq?: number
+      readonly at?: string
+    }
+  | {
+      readonly kind: 'settled'
+      readonly id: string
+      readonly status?: string
+      readonly outRef?: string
+      readonly verdict?: unknown
+      readonly spent?: unknown
+      readonly infra?: boolean
+      readonly seq?: number
+      readonly at?: string
+    }
+  | {
+      readonly kind: 'cancelled'
+      readonly id: string
+      readonly reason?: string
+      readonly seq?: number
+      readonly at?: string
+    }
+  | {
+      readonly kind: 'metered'
+      readonly id: string
+      readonly spend?: unknown
+      readonly seq?: number
+      readonly at?: string
+    }
+
+interface SupervisorState extends SupervisorBase {
+  readonly result?: {
+    readonly spentUsd?: number
+    readonly spentTokens?: number
+  }
+}
+
+interface MutableWorker {
+  id: string
+  label: string
+  cwd?: string
+  eventFile?: string
+  parent?: string
+  runtime?: string
+  status: 'running' | 'done' | 'down' | 'cancelled'
+  verdict?: string
+  infra?: boolean
+  startedAt?: string
+  endedAt?: string
+  budget?: BudgetStats
+  spend: SpendStats
+  metered: SpendStats
+  liveTail: string[]
+  outRef?: string
+  reason?: string
+}
+
+interface WorkerEventTail {
+  readonly file: string
+  readonly lines: string[]
+  readonly cwd?: string
+}
+
+export interface RenderOptions {
+  readonly width?: number
+  readonly height?: number
+  readonly color?: boolean
+  readonly selectedSupervisorId?: string
+  readonly selectedWorkerId?: string
+  readonly focus?: 'supervisors' | 'workers'
+  readonly mode?: 'overview' | 'detail' | 'log'
+  readonly notice?: string
+  readonly steerInput?: {
+    readonly active: boolean
+    readonly value: string
+    readonly workerLabel?: string
+  }
+}
+
+export interface RenderTarget {
+  readonly row: number
+  readonly kind: 'supervisor' | 'worker'
+  readonly id: string
+  readonly supervisorId?: string
+}
+
+export interface RenderedTopFrame {
+  readonly frame: string
+  readonly targets: RenderTarget[]
+}
+
+const emptySpend: SpendStats = { iterations: 0, tokensInput: 0, tokensOutput: 0, usd: 0, ms: 0 }
+// Width accounting depends on stripping SGR sequences, which begin with a literal ESC. Matching
+// the control character is the point of an ANSI-aware renderer, not an accident.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: SGR sequences begin with ESC
+const ansiPattern = /\x1b\[[0-9;?]*[ -/]*[@-~]/g
+
+const colors = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  inverse: '\x1b[7m',
+}
+
+/**
+ * Read every supervisor run under one workspace into a single point-in-time snapshot.
+ *
+ * Pure with respect to the process: it only reads, and every unreadable or half-written file is
+ * skipped rather than thrown on — an operator view must survive a writer mid-append. `now` is
+ * injectable so elapsed time is deterministic under test.
+ */
+export function loadTopSnapshot(rootDir: string, now = Date.now()): TopSnapshot {
+  const root = resolve(rootDir)
+  // `.loops` is the pre-rename state dir; runs already on disk there stay visible.
+  const supervisors = [supervisorRunsRoot(root), legacySupervisorRunsRoot(root)]
+    .filter((runsRoot) => existsSync(runsRoot))
+    .flatMap((runsRoot) =>
+      readdirSync(runsRoot)
+        .filter((entry) => isDirectory(join(runsRoot, entry)))
+        .map((entry) => {
+          const dir = join(runsRoot, entry)
+          const state = readJson<Partial<SupervisorState>>(join(dir, 'state.json'))
+          if (!isSupervisorState(state)) return undefined
+          const events = readJournal(dir)
+          const progressTail = readTail(join(dir, 'progress.ndjson'), 8)
+          const workerEvents = readWorkerEventTails(supervisorWorkersDir(dir), 8)
+          return buildSupervisorView(state, dir, events, progressTail, now, workerEvents)
+        }),
+    )
+    .filter((view): view is SupervisorView => view !== undefined)
+    .sort((a, b) => String(b.startedAt ?? '').localeCompare(String(a.startedAt ?? '')))
+
+  return { root, generatedAt: now, supervisors }
+}
+
+/**
+ * The journal file a run dir actually carries. `createFileRunContext` — this repo's own durable
+ * writer — names it `spawn-journal.jsonl`; `journal.jsonl` is the retired bare-event file older
+ * runs left behind. First existing name wins; a reader that knew only the retired name would show
+ * zero workers for every current run.
+ */
+const journalFileNames = ['spawn-journal.jsonl', 'journal.jsonl'] as const
+
+function readJournal(eventDir: string): TopJournalEvent[] {
+  const file = journalFileNames
+    .map((name) => join(eventDir, name))
+    .find((candidate) => existsSync(candidate))
+  if (!file) return []
+  const out: TopJournalEvent[] = []
+  let raw = ''
+  try {
+    raw = readFileSync(file, 'utf8')
+  } catch {
+    return out
+  }
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    try {
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>
+      const event = (parsed.event ?? parsed) as Record<string, unknown>
+      if (isSpawnEvent(event)) out.push(event)
+    } catch {
+      // Corrupt journal lines should not take down the operator view.
+    }
+  }
+  return out
+}
+
+function buildSupervisorView(
+  state: SupervisorState,
+  stateDir: string,
+  events: readonly TopJournalEvent[],
+  progressTail: readonly string[],
+  now: number,
+  workerEventTails = new Map<string, WorkerEventTail>(),
+): SupervisorView {
+  const workers = new Map<string, MutableWorker>()
+  let driverSpend = emptySpend
+
+  for (const event of events) {
+    if (event.kind === 'spawned') {
+      if (event.id === state.id || (!event.parent && event.label === 'root')) continue
+      const worker = ensureWorker(workers, event.id, event.label ?? event.id)
+      worker.label = event.label ?? worker.label
+      if (event.parent) worker.parent = event.parent
+      if (event.runtime) worker.runtime = event.runtime
+      worker.status = 'running'
+      if (event.at) worker.startedAt = event.at
+      const budget = parseBudget(event.budget)
+      if (budget) worker.budget = budget
+      continue
+    }
+
+    if (event.kind === 'settled') {
+      if (event.id === state.id) continue
+      const worker = ensureWorker(workers, event.id, event.id)
+      worker.status = event.status === 'down' ? 'down' : 'done'
+      if (event.at) worker.endedAt = event.at
+      if (event.outRef) worker.outRef = event.outRef
+      if (event.infra !== undefined) worker.infra = event.infra
+      const verdict = describeVerdict(event.verdict)
+      if (verdict) worker.verdict = verdict
+      worker.spend = addSpend(worker.spend, parseSpend(event.spent))
+      continue
+    }
+
+    if (event.kind === 'cancelled') {
+      if (event.id === state.id) continue
+      const worker = ensureWorker(workers, event.id, event.id)
+      worker.status = 'cancelled'
+      if (event.at) worker.endedAt = event.at
+      if (event.reason) worker.reason = event.reason
+      continue
+    }
+
+    if (event.kind === 'metered') {
+      const spend = parseSpend(event.spend)
+      if (event.id === state.id) {
+        driverSpend = addSpend(driverSpend, spend)
+      } else {
+        const worker = ensureWorker(workers, event.id, event.id)
+        worker.metered = addSpend(worker.metered, spend)
+      }
+    }
+  }
+
+  const workerViews = [...workers.values()]
+    .map((worker) => {
+      // Tails are keyed by file stem, which the writer put through `safeWorkerFile`; a label
+      // carrying characters that stem strips would otherwise never find its own events.
+      const tail =
+        workerEventTails.get(worker.label) ??
+        workerEventTails.get(safeWorkerFile(worker.label)) ??
+        workerEventTails.get(worker.id)
+      worker.liveTail = tail?.lines ?? []
+      if (tail?.cwd) worker.cwd = tail.cwd
+      if (tail?.file) worker.eventFile = tail.file
+      return finalizeWorker(worker, now)
+    })
+    .sort((a, b) => compareWorker(a, b))
+
+  const totals = supervisorTotals(state, workerViews, driverSpend, now)
+  return {
+    id: state.id,
+    stateDir,
+    status: state.status,
+    task: state.task,
+    workspaceDir: state.workspaceDir,
+    budget: state.budget,
+    ...(state.verifyCmd ? { verifyCmd: state.verifyCmd } : {}),
+    ...(state.workerModel ? { workerModel: state.workerModel } : {}),
+    ...(state.driverModel ? { driverModel: state.driverModel } : {}),
+    ...(state.verdict ? { verdict: state.verdict } : {}),
+    ...(state.progress ? { progress: state.progress } : {}),
+    ...(state.startedAt ? { startedAt: state.startedAt } : {}),
+    ...(state.completedAt ? { completedAt: state.completedAt } : {}),
+    ...(state.maxSandboxes !== undefined ? { maxSandboxes: state.maxSandboxes } : {}),
+    ...(state.maxLifetimeSeconds !== undefined
+      ? { maxLifetimeSeconds: state.maxLifetimeSeconds }
+      : {}),
+    ...(state.idleTimeoutSeconds !== undefined
+      ? { idleTimeoutSeconds: state.idleTimeoutSeconds }
+      : {}),
+    ...(state.maxUsd !== undefined ? { maxUsd: state.maxUsd } : {}),
+    ...(state.maxDepth !== undefined ? { maxDepth: state.maxDepth } : {}),
+    ...(state.result?.spentUsd !== undefined ? { resultSpentUsd: state.result.spentUsd } : {}),
+    ...(state.result?.spentTokens !== undefined
+      ? { resultSpentTokens: state.result.spentTokens }
+      : {}),
+    workers: workerViews,
+    progressTail: [...progressTail],
+    journalTail: events.slice(-12),
+    driverSpend,
+    totals,
+  }
+}
+
+/** Render one snapshot to an ANSI frame. Use this when nothing needs to be clickable. */
+export function renderTopFrame(snapshot: TopSnapshot, options: RenderOptions = {}): string {
+  return renderTopFrameWithLayout(snapshot, options).frame
+}
+
+/**
+ * Render one snapshot, returning the frame together with the row→entity map a mouse click resolves
+ * against. The layout is the only thing that knows which row is which run or worker, so emitting it
+ * alongside the text is what keeps click handling out of the renderer.
+ */
+export function renderTopFrameWithLayout(
+  snapshot: TopSnapshot,
+  options: RenderOptions = {},
+): RenderedTopFrame {
+  const width = Math.max(88, options.width ?? 128)
+  const height = Math.max(24, options.height ?? 42)
+  const color = options.color ?? false
+  const focus = options.focus ?? 'supervisors'
+  const mode = options.mode ?? 'overview'
+  const selectedSupervisor = selectSupervisor(snapshot, options.selectedSupervisorId)
+  const selectedWorker = selectedSupervisor
+    ? selectWorker(selectedSupervisor, options.selectedWorkerId)
+    : undefined
+  const targets: RenderTarget[] = []
+  const lines: string[] = []
+
+  const push = (line = '', target?: Omit<RenderTarget, 'row'>) => {
+    if (lines.length >= height) return
+    if (target) targets.push({ row: lines.length, ...target })
+    lines.push(fitAnsi(line, width))
+  }
+
+  const aggregate = aggregateSnapshot(snapshot)
+  push(
+    `${paint('SUPERVISOR TOP', 'bold', color)} ${paint(snapshot.root, 'dim', color)}  ` +
+      `runs ${aggregate.supervisors}  workers ${aggregate.workers}  live ${aggregate.running}  ` +
+      `done ${aggregate.done}  down ${aggregate.down}  ` +
+      `${formatMoney(aggregate.usd)}  tok ${formatTokens(aggregate.tokensInput)}/${formatTokens(aggregate.tokensOutput)}`,
+  )
+  push(
+    `${paint('keys', 'dim', color)} up/down select  left/right run  tab focus  enter detail  o overview  l log  s steer  a shell  c cancel  mouse  q quit`,
+  )
+  if (options.notice) push(paint(options.notice, 'yellow', color))
+  if (options.steerInput?.active) push(renderSteerInput(options.steerInput, width, color))
+  push(rule(width, color))
+
+  if (snapshot.supervisors.length === 0) {
+    push(paint('NO SUPERVISORS', 'yellow', color))
+    push(`No run state under ${supervisorRunsRoot(snapshot.root)}`)
+    push(
+      `A run appears here once its driver writes state.json; re-point with: agent-runtime-top <root>`,
+    )
+    return { frame: `${lines.join('\n')}\n`, targets }
+  }
+
+  push(sectionTitle('SUPERVISORS', focus === 'supervisors', color))
+  push(
+    `  id                    status       workers       spend        tok in/out       latency      task`,
+  )
+  for (const supervisor of snapshot.supervisors.slice(0, 9)) {
+    const selected = supervisor.id === selectedSupervisor?.id
+    const status = statusText(supervisor.status, color)
+    const pointer = selected ? paint('>', 'cyan', color) : ' '
+    const rowFocus = selected && focus === 'supervisors' ? 'inverse' : undefined
+    const workerSummary = `${supervisor.totals.running}/${supervisor.totals.workers} live`
+    const task = compact(supervisor.task, 34)
+    const line =
+      `${pointer} ${pad(supervisor.id, 21)} ${pad(status, 12)} ${pad(workerSummary, 13)} ` +
+      `${pad(formatMoney(supervisor.totals.usd), 12)} ` +
+      `${pad(`${formatTokens(supervisor.totals.tokensInput)}/${formatTokens(supervisor.totals.tokensOutput)}`, 16)} ` +
+      `${pad(formatDuration(supervisor.totals.latencyMs), 12)} ${task}`
+    push(rowFocus ? paint(line, rowFocus, color) : line, { kind: 'supervisor', id: supervisor.id })
+  }
+
+  if (!selectedSupervisor) return { frame: `${lines.join('\n')}\n`, targets }
+
+  push()
+  push(sectionTitle(`WORKERS ${selectedSupervisor.id}`, focus === 'workers', color))
+  push(
+    `  id           state        runtime    latency      cost        tok in/out       score     detail`,
+  )
+  for (const worker of selectedSupervisor.workers.slice(0, 12)) {
+    const selected = worker.id === selectedWorker?.id
+    const pointer = selected ? paint('>', 'cyan', color) : ' '
+    const rowFocus = selected && focus === 'workers' ? 'inverse' : undefined
+    const score = worker.verdict ?? (worker.status === 'done' ? 'done' : worker.status)
+    const detail = worker.reason ?? worker.outRef ?? worker.parent ?? ''
+    const spend = totalSpend(worker)
+    const line =
+      `${pointer} ${pad(worker.label, 12)} ${pad(statusText(worker.status, color), 12)} ` +
+      `${pad(worker.runtime ?? '-', 10)} ${pad(formatDuration(worker.latencyMs), 12)} ` +
+      `${pad(formatMoney(spend.usd), 11)} ` +
+      `${pad(`${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}`, 16)} ` +
+      `${pad(compact(score, 9), 10)} ${compact(detail, 30)}`
+    push(rowFocus ? paint(line, rowFocus, color) : line, {
+      kind: 'worker',
+      id: worker.id,
+      supervisorId: selectedSupervisor.id,
+    })
+  }
+  if (selectedSupervisor.workers.length === 0) push('  no workers spawned yet')
+
+  push()
+  push(sectionTitle('OBSERVABILITY', false, color))
+  for (const line of renderStatusBars(selectedSupervisor, width, color)) push(line)
+  push()
+  for (const line of renderCostBars(selectedSupervisor, width, color)) push(line)
+  push()
+  for (const line of renderTokenBars(selectedSupervisor, width, color)) push(line)
+  push()
+  for (const line of renderLatencyHistogram(selectedSupervisor, width, color)) push(line)
+
+  push()
+  if (mode === 'log') {
+    push(sectionTitle('JOURNAL TAIL', false, color))
+    for (const line of renderJournalTail(selectedSupervisor, width, color)) push(line)
+  } else {
+    push(sectionTitle(mode === 'detail' ? 'DETAIL' : 'RUN SUMMARY', false, color))
+    for (const line of renderDetail(selectedSupervisor, selectedWorker, mode, width, color))
+      push(line)
+  }
+
+  return { frame: `${lines.join('\n')}\n`, targets }
+}
+
+function ensureWorker(
+  workers: Map<string, MutableWorker>,
+  id: string,
+  label: string,
+): MutableWorker {
+  const existing = workers.get(id)
+  if (existing) return existing
+  const created: MutableWorker = {
+    id,
+    label,
+    status: 'running',
+    spend: emptySpend,
+    metered: emptySpend,
+    liveTail: [],
+  }
+  workers.set(id, created)
+  return created
+}
+
+function finalizeWorker(worker: MutableWorker, now: number): WorkerView {
+  const startMs = parseTime(worker.startedAt)
+  const endMs = parseTime(worker.endedAt) ?? (worker.status === 'running' ? now : startMs)
+  const latencyMs = startMs !== undefined && endMs !== undefined ? Math.max(0, endMs - startMs) : 0
+  return {
+    id: worker.id,
+    label: worker.label,
+    ...(worker.cwd ? { cwd: worker.cwd } : {}),
+    ...(worker.eventFile ? { eventFile: worker.eventFile } : {}),
+    ...(worker.parent ? { parent: worker.parent } : {}),
+    ...(worker.runtime ? { runtime: worker.runtime } : {}),
+    status: worker.status,
+    ...(worker.verdict ? { verdict: worker.verdict } : {}),
+    ...(worker.infra !== undefined ? { infra: worker.infra } : {}),
+    ...(worker.startedAt ? { startedAt: worker.startedAt } : {}),
+    ...(worker.endedAt ? { endedAt: worker.endedAt } : {}),
+    latencyMs,
+    ...(worker.budget ? { budget: worker.budget } : {}),
+    spend: worker.spend,
+    metered: worker.metered,
+    liveTail: worker.liveTail,
+    ...(worker.outRef ? { outRef: worker.outRef } : {}),
+    ...(worker.reason ? { reason: worker.reason } : {}),
+  }
+}
+
+function supervisorTotals(
+  state: SupervisorState,
+  workers: readonly WorkerView[],
+  driverSpend: SpendStats,
+  now: number,
+): SupervisorTotals {
+  const workerSpends = workers.map(totalSpend)
+  const tokenInput = sum(workerSpends.map((spend) => spend.tokensInput)) + driverSpend.tokensInput
+  const tokenOutput =
+    sum(workerSpends.map((spend) => spend.tokensOutput)) + driverSpend.tokensOutput
+  const computedUsd = sum(workerSpends.map((spend) => spend.usd)) + driverSpend.usd
+  const usd = computedUsd > 0 ? computedUsd : (state.result?.spentUsd ?? 0)
+  const started = parseTime(state.startedAt)
+  const completed = parseTime(state.completedAt)
+  const latencyMs = started !== undefined ? Math.max(0, (completed ?? now) - started) : 0
+  const latencies = workers.map((worker) => worker.latencyMs).filter((ms) => ms > 0)
+  return {
+    workers: workers.length,
+    running: workers.filter((worker) => worker.status === 'running').length,
+    done: workers.filter((worker) => worker.status === 'done').length,
+    down: workers.filter((worker) => worker.status === 'down').length,
+    cancelled: workers.filter((worker) => worker.status === 'cancelled').length,
+    inFlight: workers.filter((worker) => worker.status === 'running').length,
+    settled: workers.filter((worker) => worker.status !== 'running').length,
+    tokensInput: tokenInput,
+    tokensOutput: tokenOutput,
+    tokensTotal: tokenInput + tokenOutput,
+    usd,
+    latencyMs,
+    workerLatency: distribution(latencies),
+  }
+}
+
+function aggregateSnapshot(snapshot: TopSnapshot): {
+  supervisors: number
+  workers: number
+  running: number
+  done: number
+  down: number
+  usd: number
+  tokensInput: number
+  tokensOutput: number
+} {
+  return {
+    supervisors: snapshot.supervisors.length,
+    workers: sum(snapshot.supervisors.map((supervisor) => supervisor.totals.workers)),
+    running: sum(snapshot.supervisors.map((supervisor) => supervisor.totals.running)),
+    done: sum(snapshot.supervisors.map((supervisor) => supervisor.totals.done)),
+    down: sum(snapshot.supervisors.map((supervisor) => supervisor.totals.down)),
+    usd: sum(snapshot.supervisors.map((supervisor) => supervisor.totals.usd)),
+    tokensInput: sum(snapshot.supervisors.map((supervisor) => supervisor.totals.tokensInput)),
+    tokensOutput: sum(snapshot.supervisors.map((supervisor) => supervisor.totals.tokensOutput)),
+  }
+}
+
+function compareWorker(a: WorkerView, b: WorkerView): number {
+  const aStart = parseTime(a.startedAt) ?? 0
+  const bStart = parseTime(b.startedAt) ?? 0
+  if (a.status === 'running' && b.status !== 'running') return -1
+  if (b.status === 'running' && a.status !== 'running') return 1
+  return aStart - bStart || a.label.localeCompare(b.label)
+}
+
+function totalSpend(worker: WorkerView): SpendStats {
+  return addSpend(worker.spend, worker.metered)
+}
+
+function addSpend(a: SpendStats, b: SpendStats): SpendStats {
+  return {
+    iterations: a.iterations + b.iterations,
+    tokensInput: a.tokensInput + b.tokensInput,
+    tokensOutput: a.tokensOutput + b.tokensOutput,
+    usd: a.usd + b.usd,
+    ms: a.ms + b.ms,
+  }
+}
+
+function parseSpend(value: unknown): SpendStats {
+  if (!isRecord(value)) return emptySpend
+  const tokens = isRecord(value.tokens) ? value.tokens : {}
+  return {
+    iterations: numberValue(value.iterations),
+    tokensInput: numberValue(tokens.input),
+    tokensOutput: numberValue(tokens.output),
+    usd: numberValue(value.usd),
+    ms: numberValue(value.ms),
+  }
+}
+
+function parseBudget(value: unknown): BudgetStats | undefined {
+  if (!isRecord(value)) return undefined
+  const budget: BudgetStats = {
+    ...(typeof value.maxIterations === 'number' ? { maxIterations: value.maxIterations } : {}),
+    ...(typeof value.maxTokens === 'number' ? { maxTokens: value.maxTokens } : {}),
+    ...(typeof value.maxUsd === 'number' ? { maxUsd: value.maxUsd } : {}),
+  }
+  return Object.keys(budget).length ? budget : undefined
+}
+
+function describeVerdict(value: unknown): string | undefined {
+  if (!isRecord(value)) return undefined
+  if (typeof value.valid === 'boolean') return value.valid ? 'valid' : 'invalid'
+  if (typeof value.score === 'number') return `score ${value.score.toFixed(2)}`
+  return undefined
+}
+
+function distribution(values: readonly number[]): Distribution {
+  if (values.length === 0) return { n: 0, min: 0, median: 0, p90: 0, max: 0 }
+  const sorted = [...values].sort((a, b) => a - b)
+  return {
+    n: sorted.length,
+    min: sorted[0] ?? 0,
+    median: percentile(sorted, 0.5),
+    p90: percentile(sorted, 0.9),
+    max: sorted[sorted.length - 1] ?? 0,
+  }
+}
+
+function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return 0
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1))
+  return sorted[idx] ?? 0
+}
+
+function renderStatusBars(supervisor: SupervisorView, width: number, color: boolean): string[] {
+  const total = Math.max(1, supervisor.totals.workers)
+  const barWidth = Math.max(12, Math.min(28, width - 58))
+  return [
+    `status  ` +
+      `${pad('running', 9)} ${bar(supervisor.totals.running, total, barWidth, '#', color, 'yellow')} ${supervisor.totals.running}` +
+      `   ${pad('done', 5)} ${bar(supervisor.totals.done, total, barWidth, '#', color, 'green')} ${supervisor.totals.done}` +
+      `   ${pad('down', 5)} ${bar(supervisor.totals.down, total, barWidth, '#', color, 'red')} ${supervisor.totals.down}`,
+  ]
+}
+
+function renderCostBars(supervisor: SupervisorView, width: number, color: boolean): string[] {
+  const workers = supervisor.workers
+    .map((worker) => ({ worker, spend: totalSpend(worker) }))
+    .sort((a, b) => b.spend.usd - a.spend.usd)
+    .slice(0, 6)
+  const maxUsd = Math.max(
+    0.000001,
+    ...workers.map((row) => row.spend.usd),
+    supervisor.driverSpend.usd,
+  )
+  const out = [
+    `cost   total ${formatMoney(supervisor.totals.usd)}  driver ${formatMoney(supervisor.driverSpend.usd)}`,
+  ]
+  const barWidth = Math.max(18, Math.min(46, width - 38))
+  for (const row of workers) {
+    out.push(
+      `  ${pad(row.worker.label, 12)} ${bar(row.spend.usd, maxUsd, barWidth, '$', color, 'magenta')} ${formatMoney(row.spend.usd)}`,
+    )
+  }
+  if (workers.length === 0) out.push('  no worker cost yet')
+  return out
+}
+
+function renderTokenBars(supervisor: SupervisorView, width: number, color: boolean): string[] {
+  const rows = supervisor.workers
+    .map((worker) => ({
+      worker,
+      spend: totalSpend(worker),
+      total: totalSpend(worker).tokensInput + totalSpend(worker).tokensOutput,
+    }))
+    .sort((a, b) => b.total - a.total)
+    .slice(0, 6)
+  const maxTokens = Math.max(
+    1,
+    ...rows.map((row) => row.total),
+    supervisor.driverSpend.tokensInput + supervisor.driverSpend.tokensOutput,
+  )
+  const out = [
+    `tokens total in ${formatTokens(supervisor.totals.tokensInput)} / out ${formatTokens(supervisor.totals.tokensOutput)}  ` +
+      `driver ${formatTokens(supervisor.driverSpend.tokensInput)}/${formatTokens(supervisor.driverSpend.tokensOutput)}`,
+  ]
+  const barWidth = Math.max(18, Math.min(46, width - 44))
+  for (const row of rows) {
+    out.push(
+      `  ${pad(row.worker.label, 12)} ${stackedTokenBar(row.spend.tokensInput, row.spend.tokensOutput, maxTokens, barWidth, color)} ` +
+        `${formatTokens(row.spend.tokensInput)}/${formatTokens(row.spend.tokensOutput)}`,
+    )
+  }
+  if (rows.length === 0) out.push('  no worker tokens yet')
+  return out
+}
+
+function renderLatencyHistogram(
+  supervisor: SupervisorView,
+  width: number,
+  color: boolean,
+): string[] {
+  const values = supervisor.workers.map((worker) => worker.latencyMs).filter((value) => value > 0)
+  const summary = supervisor.totals.workerLatency
+  const out = [
+    `latency n=${summary.n}  min ${formatDuration(summary.min)}  p50 ${formatDuration(summary.median)}  ` +
+      `p90 ${formatDuration(summary.p90)}  max ${formatDuration(summary.max)}`,
+  ]
+  if (values.length === 0) {
+    out.push('  no latency samples yet')
+    return out
+  }
+  const bins = histogram(values, 6)
+  const maxCount = Math.max(1, ...bins.map((bin) => bin.count))
+  const barWidth = Math.max(18, Math.min(48, width - 34))
+  for (const bin of bins) {
+    out.push(
+      `  ${pad(`${formatDuration(bin.min)}-${formatDuration(bin.max)}`, 15)} ` +
+        `${bar(bin.count, maxCount, barWidth, '#', color, 'blue')} ${bin.count}`,
+    )
+  }
+  return out
+}
+
+function renderDetail(
+  supervisor: SupervisorView,
+  worker: WorkerView | undefined,
+  mode: 'overview' | 'detail' | 'log',
+  width: number,
+  color: boolean,
+): string[] {
+  if (mode === 'detail' && worker) {
+    const spend = totalSpend(worker)
+    return [
+      `worker ${paint(worker.label, 'bold', color)} (${worker.id})  ${statusText(worker.status, color)}  latency ${formatDuration(worker.latencyMs)}`,
+      `tokens in/out ${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}  cost ${formatMoney(spend.usd)}  iterations ${spend.iterations}`,
+      `parent ${worker.parent ?? '-'}  runtime ${worker.runtime ?? '-'}  out ${worker.outRef ?? '-'}${worker.infra ? '  infra' : ''}`,
+      `cwd ${compact(worker.cwd ?? '-', width - 5)}`,
+      `events ${compact(worker.eventFile ?? '-', width - 8)}`,
+      ...(worker.reason ? [`reason ${compact(worker.reason, width - 7)}`] : []),
+      ...renderWorkerTail(worker, width, color),
+    ]
+  }
+
+  const caps = [
+    supervisor.maxSandboxes !== undefined ? `boxes ${supervisor.maxSandboxes}` : undefined,
+    supervisor.maxUsd !== undefined ? `max ${formatMoney(supervisor.maxUsd)}` : undefined,
+    supervisor.maxDepth !== undefined ? `depth ${supervisor.maxDepth}` : undefined,
+    supervisor.maxLifetimeSeconds !== undefined
+      ? `ttl ${supervisor.maxLifetimeSeconds}s`
+      : undefined,
+  ].filter((value): value is string => value !== undefined)
+  return [
+    `task ${compact(supervisor.task, width - 7)}`,
+    `workspace ${compact(supervisor.workspaceDir, width - 12)}`,
+    `verify ${compact(supervisor.verifyCmd ?? '-', width - 9)}`,
+    `models worker ${supervisor.workerModel ?? '-'} / driver ${supervisor.driverModel ?? '-'}  caps ${caps.join(' | ') || '-'}`,
+    `progress ${compact(supervisor.progress ?? supervisor.verdict ?? supervisor.status, width - 10)}`,
+  ]
+}
+
+function renderJournalTail(supervisor: SupervisorView, width: number, color: boolean): string[] {
+  if (supervisor.journalTail.length === 0) return ['  no journal events yet']
+  return supervisor.journalTail.map((event) => {
+    const at = event.at ? formatClock(event.at) : '--:--:--'
+    if (event.kind === 'spawned')
+      return `  ${at} ${paint('spawn', 'yellow', color)}  ${pad(event.label ?? event.id, 16)} ${event.id}`
+    if (event.kind === 'settled') {
+      const spend = parseSpend(event.spent)
+      return `  ${at} ${statusText(event.status ?? 'settled', color)} ${pad(event.id, 18)} ${formatMoney(spend.usd)} ${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}`
+    }
+    if (event.kind === 'metered') {
+      const spend = parseSpend(event.spend)
+      return `  ${at} ${paint('meter', 'cyan', color)}  ${pad(event.id, 18)} ${formatMoney(spend.usd)} ${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}`
+    }
+    return `  ${at} ${paint('cancel', 'red', color)} ${pad(event.id, 18)} ${compact(event.reason ?? '', width - 32)}`
+  })
+}
+
+function renderWorkerTail(worker: WorkerView, width: number, color: boolean): string[] {
+  if (worker.liveTail.length === 0) return ['live events: none recorded yet']
+  return [
+    'live events:',
+    ...worker.liveTail
+      .slice(-5)
+      .map((line) => `  ${paint(compact(formatWorkerEvent(line), width - 2), 'dim', color)}`),
+  ]
+}
+
+function renderSteerInput(
+  input: NonNullable<RenderOptions['steerInput']>,
+  width: number,
+  color: boolean,
+): string {
+  const target = input.workerLabel ?? '-'
+  const value = compact(input.value, Math.max(10, width - target.length - 14))
+  return `${paint('steer', 'cyan', color)} ${target} > ${value}${paint('_', 'inverse', color)}`
+}
+
+function formatWorkerEvent(line: string): string {
+  try {
+    const parsed = JSON.parse(line) as Record<string, unknown>
+    const at = typeof parsed.at === 'string' ? formatClock(parsed.at) : '--:--:--'
+    const kind = typeof parsed.kind === 'string' ? parsed.kind : 'event'
+    if (kind === 'progress')
+      return `${at} progress iter ${numberValue(parsed.iteration)} ${String(parsed.phase ?? '')}`
+    if (kind === 'started') return `${at} started ${String(parsed.cwd ?? '')}`
+    if (kind === 'message') {
+      const state = parsed.queued === true ? 'queued' : 'sent'
+      const source =
+        typeof parsed.source === 'string' && parsed.source.length > 0 ? `${parsed.source} ` : ''
+      const message =
+        typeof parsed.message === 'string' && parsed.message.length > 0 ? ` ${parsed.message}` : ''
+      return `${at} ${source}steer ${state} delivered=${String(parsed.delivered)}${message}`
+    }
+    if (kind === 'verify') {
+      return `${at} verify passed=${String(parsed.passed)} exit=${String(parsed.exitCode ?? '-')}${evidenceSnippet(parsed.outputTail, 160)}`
+    }
+    if (kind === 'finished') {
+      const branch = typeof parsed.branch === 'string' ? ` branch=${parsed.branch}` : ''
+      const files = typeof parsed.filesChanged === 'number' ? ` files=${parsed.filesChanged}` : ''
+      const tests =
+        typeof parsed.testPassed === 'boolean' ? ` tests=${String(parsed.testPassed)}` : ''
+      return `${at} finished passed=${String(parsed.passed)} patchBytes=${numberValue(parsed.patchBytes)}${files}${tests}${branch}${evidenceSnippet(parsed.evidence, 220)}`
+    }
+    if (kind === 'error') return `${at} error ${String(parsed.error ?? '')}`
+    return `${at} ${kind}`
+  } catch {
+    return line
+  }
+}
+
+/** One-line the settle evidence / verify tail a worker event carries so the
+ *  failure is legible in the tail view (the full block stays in the ndjson). */
+function evidenceSnippet(value: unknown, max: number): string {
+  if (typeof value !== 'string') return ''
+  const oneLine = value.replace(/\s+/g, ' ').trim()
+  return oneLine ? ` :: ${compact(oneLine, max)}` : ''
+}
+
+function histogram(
+  values: readonly number[],
+  count: number,
+): Array<{ min: number; max: number; count: number }> {
+  const min = Math.min(...values)
+  const max = Math.max(...values)
+  if (min === max) return [{ min, max, count: values.length }]
+  const step = (max - min) / count
+  return Array.from({ length: count }, (_, index) => {
+    const low = min + step * index
+    const high = index === count - 1 ? max : min + step * (index + 1)
+    const binCount = values.filter(
+      (value) => value >= low && (index === count - 1 ? value <= high : value < high),
+    ).length
+    return { min: low, max: high, count: binCount }
+  }).filter((bin) => bin.count > 0)
+}
+
+function bar(
+  value: number,
+  max: number,
+  width: number,
+  ch: string,
+  color: boolean,
+  colorName: keyof typeof colors,
+): string {
+  const filled = Math.max(0, Math.min(width, Math.round((value / Math.max(max, 0.000001)) * width)))
+  const text = ch.repeat(filled).padEnd(width, '.')
+  return paint(text, colorName, color)
+}
+
+function stackedTokenBar(
+  input: number,
+  output: number,
+  max: number,
+  width: number,
+  color: boolean,
+): string {
+  const inputWidth = Math.round((input / Math.max(max, 1)) * width)
+  const outputWidth = Math.round((output / Math.max(max, 1)) * width)
+  const clippedInput = Math.min(width, inputWidth)
+  const clippedOutput = Math.min(width - clippedInput, outputWidth)
+  const rest = Math.max(0, width - clippedInput - clippedOutput)
+  return `${paint('#'.repeat(clippedInput), 'cyan', color)}${paint('+'.repeat(clippedOutput), 'green', color)}${'.'.repeat(rest)}`
+}
+
+function sectionTitle(title: string, focused: boolean, color: boolean): string {
+  const text = focused ? `[${title}]` : title
+  return paint(text, focused ? 'cyan' : 'bold', color)
+}
+
+function statusText(status: string, color: boolean): string {
+  if (['completed', 'done', 'delivered', 'valid'].includes(status))
+    return paint(status.toUpperCase(), 'green', color)
+  if (['failed', 'down', 'cancelled', 'invalid', 'error'].includes(status))
+    return paint(status.toUpperCase(), 'red', color)
+  if (['running', 'spawned', 'settled'].includes(status))
+    return paint(status.toUpperCase(), 'yellow', color)
+  return paint(status.toUpperCase(), 'white', color)
+}
+
+function selectSupervisor(
+  snapshot: TopSnapshot,
+  requested: string | undefined,
+): SupervisorView | undefined {
+  if (requested) {
+    const found = snapshot.supervisors.find((supervisor) => supervisor.id === requested)
+    if (found) return found
+  }
+  return snapshot.supervisors[0]
+}
+
+function selectWorker(
+  supervisor: SupervisorView,
+  requested: string | undefined,
+): WorkerView | undefined {
+  if (requested) {
+    const found = supervisor.workers.find((worker) => worker.id === requested)
+    if (found) return found
+  }
+  return supervisor.workers[0]
+}
+
+function readTail(file: string, maxLines: number): string[] {
+  if (!existsSync(file)) return []
+  try {
+    const lines = readFileSync(file, 'utf8').trim().split('\n').filter(Boolean)
+    return lines.slice(-maxLines)
+  } catch {
+    return []
+  }
+}
+
+function readWorkerEventTails(dir: string, maxLines: number): Map<string, WorkerEventTail> {
+  const out = new Map<string, WorkerEventTail>()
+  if (!existsSync(dir)) return out
+  for (const entry of readdirSync(dir)) {
+    // `<label>.inbox.ndjson` is the down-leg steer queue, not this worker's control-event log.
+    if (!entry.endsWith('.ndjson') || entry.endsWith('.inbox.ndjson')) continue
+    const label = entry.slice(0, -'.ndjson'.length)
+    const file = join(dir, entry)
+    const lines = readTail(file, maxLines)
+    const cwd = workerCwd(lines)
+    out.set(label, { file, lines, ...(cwd ? { cwd } : {}) })
+  }
+  return out
+}
+
+function workerCwd(lines: readonly string[]): string | undefined {
+  for (const line of [...lines].reverse()) {
+    try {
+      const parsed = JSON.parse(line) as Record<string, unknown>
+      if (parsed.kind === 'started' && typeof parsed.cwd === 'string' && parsed.cwd.trim())
+        return parsed.cwd
+    } catch {
+      // Corrupt worker events are rendered raw in the detail tail.
+    }
+  }
+  return undefined
+}
+
+function readJson<T>(file: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as T
+  } catch {
+    return undefined
+  }
+}
+
+function isSupervisorState(value: Partial<SupervisorState> | undefined): value is SupervisorState {
+  return (
+    value !== undefined &&
+    typeof value.id === 'string' &&
+    typeof value.status === 'string' &&
+    typeof value.task === 'string' &&
+    typeof value.workspaceDir === 'string' &&
+    typeof value.budget === 'number'
+  )
+}
+
+function isSpawnEvent(value: Record<string, unknown>): value is TopJournalEvent {
+  return (
+    (value.kind === 'spawned' && typeof value.id === 'string') ||
+    (value.kind === 'settled' && typeof value.id === 'string') ||
+    (value.kind === 'cancelled' && typeof value.id === 'string') ||
+    (value.kind === 'metered' && typeof value.id === 'string')
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+function parseTime(value: string | undefined): number | undefined {
+  if (!value) return undefined
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+function sum(values: readonly number[]): number {
+  return values.reduce((total, value) => total + value, 0)
+}
+
+function formatClock(value: string): string {
+  const parsed = parseTime(value)
+  if (parsed === undefined) return '--:--:--'
+  return new Date(parsed).toISOString().slice(11, 19)
+}
+
+function formatMoney(value: number): string {
+  if (value === 0) return '$0'
+  if (Math.abs(value) < 0.01) return `$${value.toFixed(4)}`
+  return `$${value.toFixed(2)}`
+}
+
+function formatTokens(value: number): string {
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}m`
+  if (value >= 1_000) return `${(value / 1_000).toFixed(1)}k`
+  return `${Math.round(value)}`
+}
+
+function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return '0s'
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  const seconds = ms / 1000
+  if (seconds < 60) return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`
+  const minutes = seconds / 60
+  if (minutes < 60) return `${minutes.toFixed(minutes < 10 ? 1 : 0)}m`
+  return `${(minutes / 60).toFixed(1)}h`
+}
+
+function compact(value: string, width: number): string {
+  if (width <= 1) return ''
+  if (value.length <= width) return value
+  return `${value.slice(0, width - 1)}~`
+}
+
+function pad(value: string, width: number): string {
+  const visible = visibleLength(value)
+  if (visible >= width) return fitAnsi(value, width)
+  return `${value}${' '.repeat(width - visible)}`
+}
+
+function rule(width: number, color: boolean): string {
+  return paint('-'.repeat(width), 'dim', color)
+}
+
+function paint(
+  value: string,
+  colorName: keyof typeof colors | undefined,
+  enabled: boolean,
+): string {
+  if (!enabled || !colorName) return value
+  return `${colors[colorName]}${value}${colors.reset}`
+}
+
+function visibleLength(value: string): number {
+  return stripAnsi(value).length
+}
+
+function stripAnsi(value: string): string {
+  return value.replace(ansiPattern, '')
+}
+
+function fitAnsi(value: string, width: number): string {
+  if (visibleLength(value) <= width) return value
+  let out = ''
+  let visible = 0
+  for (let i = 0; i < value.length; i += 1) {
+    const ch = value[i]
+    if (ch === '\x1b') {
+      const rest = value.slice(i)
+      // An escape sequence must be copied whole and counted as zero visible columns; truncating
+      // inside one would emit a half-sequence the terminal interprets against the next line.
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: SGR sequences begin with ESC
+      const match = /^\x1b\[[0-9;?]*[ -/]*[@-~]/.exec(rest)
+      if (match) {
+        out += match[0]
+        i += match[0].length - 1
+        continue
+      }
+    }
+    if (visible >= width - 1) {
+      out += '~'
+      break
+    }
+    out += ch
+    visible += 1
+  }
+  if (out.includes('\x1b[') && !out.endsWith(colors.reset)) out += colors.reset
+  return out
+}
diff --git a/tests/tui/top-model.test.ts b/tests/tui/top-model.test.ts
new file mode 100644
index 00000000..9eb5c09b
--- /dev/null
+++ b/tests/tui/top-model.test.ts
@@ -0,0 +1,447 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { FileSpawnJournal } from '../../src/durable/spawn-journal'
+import {
+  legacySupervisorRunDir,
+  readWorkerSteerRequests,
+  safeWorkerFile,
+  supervisorRunDir,
+  workerControlLogFile,
+  writeWorkerSteer,
+} from '../../src/runtime/supervise/run-layout'
+import { loadTopSnapshot, renderTopFrame, renderTopFrameWithLayout } from '../../src/tui/top-model'
+
+describe('supervisor top model', () => {
+  const roots: string[] = []
+
+  afterEach(() => {
+    for (const root of roots) rmSync(root, { recursive: true, force: true })
+    roots.length = 0
+  })
+
+  it('renders workers, status, token bars, cost bars, and latency histograms from the journal', () => {
+    const root = fixtureRoot()
+    const dir = supervisorRunDir(root, 'sup-1-rich')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'state.json'),
+      JSON.stringify(
+        {
+          id: 'sup-1-rich',
+          status: 'running',
+          task: 'ship the interactive TUI',
+          workspaceDir: '/repo',
+          budget: 4,
+          verifyCmd: 'pnpm test',
+          workerModel: 'deepseek-v4-flash',
+          driverModel: 'deepseek-v4-flash',
+          startedAt: '2026-06-28T10:00:00.000Z',
+          maxSandboxes: 4,
+          maxLifetimeSeconds: 1200,
+          maxUsd: 5,
+          maxDepth: 4,
+        },
+        null,
+        2,
+      ),
+    )
+    writeFileSync(
+      join(dir, 'journal.jsonl'),
+      [
+        '{corrupt',
+        JSON.stringify({
+          kind: 'spawned',
+          id: 'sup-1-rich',
+          label: 'root',
+          budget: { maxIterations: 16 },
+          runtime: 'inline',
+          seq: 0,
+          at: '2026-06-28T10:00:00.000Z',
+        }),
+        JSON.stringify({
+          kind: 'metered',
+          id: 'sup-1-rich',
+          spend: { iterations: 1, tokens: { input: 300, output: 90 }, usd: 0.003, ms: 1200 },
+          seq: 1,
+          at: '2026-06-28T10:00:01.000Z',
+        }),
+        JSON.stringify({
+          kind: 'spawned',
+          id: 'sup-1-rich:s1',
+          parent: 'sup-1-rich',
+          label: 'w-0',
+          budget: { maxIterations: 2, maxTokens: 8000 },
+          runtime: 'inline',
+          seq: 2,
+          at: '2026-06-28T10:00:02.000Z',
+        }),
+        JSON.stringify({
+          kind: 'spawned',
+          id: 'sup-1-rich:s2',
+          parent: 'sup-1-rich',
+          label: 'w-1',
+          budget: { maxIterations: 2, maxTokens: 8000 },
+          runtime: 'inline',
+          seq: 3,
+          at: '2026-06-28T10:00:08.000Z',
+        }),
+        JSON.stringify({
+          kind: 'settled',
+          id: 'sup-1-rich:s1',
+          status: 'done',
+          outRef: 'sha256:ok',
+          verdict: { valid: true, score: 1 },
+          spent: { iterations: 1, tokens: { input: 1200, output: 640 }, usd: 0.021, ms: 0 },
+          seq: 4,
+          at: '2026-06-28T10:00:32.000Z',
+        }),
+        JSON.stringify({
+          kind: 'settled',
+          id: 'sup-1-rich:s2',
+          status: 'down',
+          infra: false,
+          spent: { iterations: 1, tokens: { input: 900, output: 210 }, usd: 0.013, ms: 0 },
+          seq: 5,
+          at: '2026-06-28T10:01:08.000Z',
+        }),
+      ].join('\n'),
+    )
+    mkdirSync(join(dir, 'workers'))
+    writeFileSync(
+      workerControlLogFile(dir, 'w-0'),
+      [
+        JSON.stringify({
+          at: '2026-06-28T10:00:03.000Z',
+          label: 'w-0',
+          kind: 'started',
+          cwd: '/tmp/worktree',
+        }),
+        JSON.stringify({
+          at: '2026-06-28T10:00:04.000Z',
+          label: 'w-0',
+          kind: 'message',
+          source: 'human',
+          message: 'try the narrow fix',
+          queued: true,
+          delivered: false,
+        }),
+        JSON.stringify({
+          at: '2026-06-28T10:00:05.000Z',
+          label: 'w-0',
+          kind: 'message',
+          source: 'human',
+          message: 'try the narrow fix',
+          queued: false,
+          delivered: true,
+        }),
+        JSON.stringify({
+          at: '2026-06-28T10:00:18.000Z',
+          label: 'w-0',
+          kind: 'progress',
+          iteration: 1,
+          phase: 'editing',
+        }),
+        JSON.stringify({
+          at: '2026-06-28T10:00:30.000Z',
+          label: 'w-0',
+          kind: 'verify',
+          backend: 'bridge-worktree',
+          passed: true,
+          exitCode: 0,
+        }),
+        JSON.stringify({
+          at: '2026-06-28T10:00:31.000Z',
+          label: 'w-0',
+          kind: 'finished',
+          backend: 'bridge-worktree',
+          passed: true,
+          branch: 'delegate/sup-1-rich-w-0',
+          patchBytes: 512,
+          filesChanged: 2,
+          testPassed: true,
+        }),
+      ].join('\n'),
+    )
+
+    const snapshot = loadTopSnapshot(root, Date.parse('2026-06-28T10:01:20.000Z'))
+    expect(snapshot.supervisors).toHaveLength(1)
+    const supervisor = snapshot.supervisors[0]
+    expect(supervisor?.totals.workers).toBe(2)
+    expect(supervisor?.stateDir).toBe(dir)
+    expect(supervisor?.totals.tokensInput).toBe(2400)
+    expect(supervisor?.totals.tokensOutput).toBe(940)
+    expect(supervisor?.totals.down).toBe(1)
+    expect(supervisor?.totals.workerLatency.n).toBe(2)
+    const worker = supervisor?.workers.find((candidate) => candidate.label === 'w-0')
+    expect(worker?.cwd).toBe('/tmp/worktree')
+    expect(worker?.eventFile).toBe(workerControlLogFile(dir, 'w-0'))
+
+    const frame = renderTopFrame(snapshot, {
+      color: false,
+      width: 132,
+      height: 48,
+      selectedSupervisorId: 'sup-1-rich',
+      selectedWorkerId: 'sup-1-rich:s1',
+      focus: 'workers',
+      mode: 'detail',
+      steerInput: { active: true, value: 'please inspect the TUI input path', workerLabel: 'w-0' },
+    })
+
+    expect(frame).toContain('SUPERVISORS')
+    expect(frame).toContain('WORKERS sup-1-rich')
+    expect(frame).toContain('OBSERVABILITY')
+    expect(frame).toContain('cost   total $0.04')
+    expect(frame).toContain('tokens total in 2.4k / out 940')
+    expect(frame).toContain('latency n=2')
+    expect(frame).toContain('w-0')
+    expect(frame).toContain('w-1')
+    expect(frame).toContain('valid')
+    expect(frame).toContain('cwd /tmp/worktree')
+    expect(frame).toContain('events ')
+    expect(frame).toContain('live events:')
+    expect(frame).toContain('steer w-0 > please inspect the TUI input path_')
+    expect(frame).toContain('human steer queued delivered=false try the narrow fix')
+    expect(frame).toContain('human steer sent delivered=true try the narrow fix')
+    expect(frame).toContain('progress iter 1 editing')
+    expect(frame).toContain('verify passed=true exit=0')
+    expect(frame).toContain('files=2 tests=true branch=delegate/sup-1-rich-w-0')
+  })
+
+  it('calibrates the observability eval: weak frame scores low, rich frame scores high', () => {
+    const root = fixtureRoot()
+    const dir = supervisorRunDir(root, 'sup-2-eval')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'state.json'),
+      JSON.stringify({
+        id: 'sup-2-eval',
+        status: 'completed',
+        verdict: 'delivered',
+        task: 'observable run',
+        workspaceDir: '/repo',
+        budget: 3,
+        startedAt: '2026-06-28T10:00:00.000Z',
+        completedAt: '2026-06-28T10:02:00.000Z',
+      }),
+    )
+    writeFileSync(
+      join(dir, 'journal.jsonl'),
+      [
+        JSON.stringify({
+          kind: 'spawned',
+          id: 'sup-2-eval:s1',
+          parent: 'sup-2-eval',
+          label: 'worker-a',
+          runtime: 'inline',
+          seq: 1,
+          at: '2026-06-28T10:00:05.000Z',
+        }),
+        JSON.stringify({
+          kind: 'settled',
+          id: 'sup-2-eval:s1',
+          status: 'done',
+          verdict: { valid: true },
+          spent: { iterations: 1, tokens: { input: 1000, output: 500 }, usd: 0.02, ms: 0 },
+          seq: 2,
+          at: '2026-06-28T10:01:05.000Z',
+        }),
+      ].join('\n'),
+    )
+
+    const weak = 'SUPERVISORS\n(none)\n'
+    const rich = renderTopFrame(loadTopSnapshot(root), { color: false, width: 128, height: 42 })
+
+    expect(observabilityScore(weak)).toBeLessThan(30)
+    expect(observabilityScore(rich)).toBeGreaterThan(70)
+  })
+
+  it('returns row targets for mouse selection, and keeps pre-rename .loops runs visible', () => {
+    const root = fixtureRoot()
+    // Deliberately a pre-rename .loops run: legacy runs stay visible in the top view.
+    const dir = legacySupervisorRunDir(root, 'sup-3-click')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'state.json'),
+      JSON.stringify({
+        id: 'sup-3-click',
+        status: 'running',
+        task: 'click me',
+        workspaceDir: '/repo',
+        budget: 1,
+      }),
+    )
+    writeFileSync(
+      join(dir, 'journal.jsonl'),
+      JSON.stringify({
+        kind: 'spawned',
+        id: 'sup-3-click:s1',
+        parent: 'sup-3-click',
+        label: 'w-click',
+        runtime: 'inline',
+        seq: 1,
+        at: '2026-06-28T10:00:00.000Z',
+      }),
+    )
+
+    const snapshot = loadTopSnapshot(root)
+    expect(snapshot.supervisors.map((supervisor) => supervisor.id)).toEqual(['sup-3-click'])
+    expect(snapshot.supervisors[0]?.stateDir).toBe(dir)
+
+    const rendered = renderTopFrameWithLayout(snapshot, { color: false, width: 120, height: 36 })
+
+    expect(
+      rendered.targets.some(
+        (target) => target.kind === 'supervisor' && target.id === 'sup-3-click',
+      ),
+    ).toBe(true)
+    expect(
+      rendered.targets.some((target) => target.kind === 'worker' && target.id === 'sup-3-click:s1'),
+    ).toBe(true)
+  })
+
+  it('shows a run whose journal the durable FileSpawnJournal wrote', async () => {
+    const root = fixtureRoot()
+    const dir = supervisorRunDir(root, 'sup-4-durable')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'state.json'),
+      JSON.stringify({
+        id: 'sup-4-durable',
+        status: 'running',
+        task: 'durable journal run',
+        workspaceDir: '/repo',
+        budget: 2,
+        startedAt: '2026-06-28T10:00:00.000Z',
+      }),
+    )
+
+    // The exact file `createFileRunContext(dir)` binds, written by the exact class it binds — so a
+    // reader that only knew the retired `journal.jsonl` name fails this test.
+    const journal = new FileSpawnJournal(join(dir, 'spawn-journal.jsonl'))
+    await journal.beginTree('sup-4-durable', '2026-06-28T10:00:00.000Z')
+    await journal.appendEvent('sup-4-durable', {
+      kind: 'spawned',
+      id: 'sup-4-durable:s1',
+      parent: 'sup-4-durable',
+      label: 'w-durable',
+      budget: { maxIterations: 2 },
+      runtime: 'inline',
+      seq: 1,
+      at: '2026-06-28T10:00:02.000Z',
+    })
+    await journal.appendEvent('sup-4-durable', {
+      kind: 'settled',
+      id: 'sup-4-durable:s1',
+      status: 'done',
+      verdict: { valid: true },
+      spent: { iterations: 1, tokens: { input: 700, output: 300 }, usd: 0.05, ms: 0 },
+      seq: 2,
+      at: '2026-06-28T10:00:40.000Z',
+    })
+
+    const snapshot = loadTopSnapshot(root, Date.parse('2026-06-28T10:01:00.000Z'))
+    const supervisor = snapshot.supervisors[0]
+    expect(supervisor?.totals.workers).toBe(1)
+    expect(supervisor?.totals.done).toBe(1)
+    expect(supervisor?.totals.tokensInput).toBe(700)
+    expect(supervisor?.workers[0]?.verdict).toBe('valid')
+
+    const frame = renderTopFrame(snapshot, { color: false, width: 128, height: 42 })
+    expect(frame).toContain('w-durable')
+    expect(frame).toContain('cost   total $0.05')
+  })
+
+  it('reads back the control-event log that writeWorkerSteer produced, sanitised label included', () => {
+    const root = fixtureRoot()
+    const dir = supervisorRunDir(root, 'sup-5-steer')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'state.json'),
+      JSON.stringify({
+        id: 'sup-5-steer',
+        status: 'running',
+        task: 'steer round trip',
+        workspaceDir: '/repo',
+        budget: 1,
+        startedAt: '2026-06-28T10:00:00.000Z',
+      }),
+    )
+    // A label whose filename stem differs from the label itself; the reader must still join them.
+    const label = 'feat/w 0'
+    expect(safeWorkerFile(label)).not.toBe(label)
+    writeFileSync(
+      join(dir, 'journal.jsonl'),
+      JSON.stringify({
+        kind: 'spawned',
+        id: 'sup-5-steer:s1',
+        parent: 'sup-5-steer',
+        label,
+        runtime: 'inline',
+        seq: 1,
+        at: '2026-06-28T10:00:01.000Z',
+      }),
+    )
+
+    const written = writeWorkerSteer(root, 'sup-5-steer', label, 'narrow the diff', 'human')
+    expect(written.file).toBe(join(dir, 'workers', `${safeWorkerFile(label)}.inbox.ndjson`))
+    expect(readWorkerSteerRequests(dir, label).map((request) => request.message)).toEqual([
+      'narrow the diff',
+    ])
+
+    const snapshot = loadTopSnapshot(root, Date.parse('2026-06-28T10:00:30.000Z'))
+    const worker = snapshot.supervisors[0]?.workers[0]
+    expect(worker?.label).toBe(label)
+    expect(worker?.eventFile).toBe(workerControlLogFile(dir, label))
+    // The inbox file lives in the same directory and must NOT be mistaken for a control log.
+    expect(worker?.liveTail.length).toBe(1)
+    expect(worker?.liveTail[0]).toContain('narrow the diff')
+
+    const frame = renderTopFrame(snapshot, {
+      color: false,
+      width: 132,
+      height: 48,
+      selectedWorkerId: 'sup-5-steer:s1',
+      focus: 'workers',
+      mode: 'detail',
+    })
+    expect(frame).toContain('human steer queued delivered=false narrow the diff')
+    // The inbox line itself is not a control event and must not surface as one.
+    expect(readFileSync(written.file, 'utf8')).toContain('narrow the diff')
+  })
+
+  it('reports no supervisors for a workspace with no run state', () => {
+    const root = fixtureRoot()
+    const snapshot = loadTopSnapshot(root)
+    expect(snapshot.supervisors).toEqual([])
+    const frame = renderTopFrame(snapshot, { color: false, width: 120, height: 30 })
+    expect(frame).toContain('NO SUPERVISORS')
+    expect(frame).toContain(join(root, '.agent', 'supervisor'))
+  })
+
+  function fixtureRoot(): string {
+    const root = mkdtempSync(join(tmpdir(), 'agent-runtime-top-'))
+    roots.push(root)
+    return root
+  }
+})
+
+function observabilityScore(frame: string): number {
+  const checks = [
+    /SUPERVISORS/,
+    /WORKERS/,
+    /OBSERVABILITY/,
+    /status/,
+    /cost\s+total/,
+    /tokens total in/,
+    /latency n=/,
+    /tok in\/out/,
+    /\$0\.\d/,
+    /worker/,
+    /valid|done|delivered/i,
+    /keys .*a shell.*c cancel.*mouse/,
+  ]
+  const hits = checks.filter((check) => check.test(frame)).length
+  return (hits / checks.length) * 100
+}
diff --git a/tsdown.config.ts b/tsdown.config.ts
index cbd7ab79..f1c88ae1 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -21,6 +21,8 @@ export default defineConfig({
     'mcp/bin': 'src/mcp/bin.ts',
     'mcp/memory-bin': 'src/mcp/memory-bin.ts',
     'loop-runner-bin': 'src/loop-runner-bin.ts',
+    'tui/index': 'src/tui/index.ts',
+    'tui/bin': 'src/tui/bin.ts',
   },
   format: ['esm'],
   dts: {
diff --git a/typedoc.json b/typedoc.json
index 5d82c958..50c4880a 100644
--- a/typedoc.json
+++ b/typedoc.json
@@ -16,7 +16,8 @@
     "src/primeintellect/index.ts",
     "src/candidate-execution/index.ts",
     "src/testing/index.ts",
-    "src/mcp/index.ts"
+    "src/mcp/index.ts",
+    "src/tui/index.ts"
   ],
   "entryPointStrategy": "resolve",
   "tsconfig": "./tsconfig.json",
@@ -35,7 +36,8 @@
     "**/tests/**",
     "**/examples/**",
     "src/mcp/bin.ts",
-    "src/loop-runner-bin.ts"
+    "src/loop-runner-bin.ts",
+    "src/tui/bin.ts"
   ],
   "disableSources": true,
   "hideGenerator": true,
diff --git a/vitest.config.ts b/vitest.config.ts
index 4602714a..a30f2dfa 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -16,6 +16,10 @@ export default defineConfig({
         find: /^@tangle-network\/agent-runtime\/testing$/,
         replacement: resolve(__dirname, 'src/testing/index.ts'),
       },
+      {
+        find: /^@tangle-network\/agent-runtime\/tui$/,
+        replacement: resolve(__dirname, 'src/tui/index.ts'),
+      },
     ],
   },
   test: {

From 79bc444c8b927e57899e83a2b42c7931df378624 Mon Sep 17 00:00:00 2001
From: Drew Stone <drewstone329@gmail.com>
Date: Sat, 1 Aug 2026 02:03:17 -0600
Subject: [PATCH 2/2] fix(tui): stop minting a phantom worker when the journal
 root id differs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

state.json and the spawn journal have different producers and their ids
need not agree: the journal's root is the runtime's runId, which defaults
to a value unrelated to the supervisor id the state file records.

Only the spawned branch carried a second guard for that. The metered,
settled, and cancelled branches checked state.id alone, so every driver
event minted a worker named for the runId — one that never settles, sorts
first as RUNNING so it is the default-selected row, holds the driver's
spend where the driver's own totals then read zero, and captures steers
into an inbox nothing reads.

The journal's root is now recovered from its own parentless root spawn and
either id counts as root in all four branches. The regression pins the
mismatch case the original proof was constructed to avoid.
---
 src/tui/top-model.ts        | 18 ++++++++++++----
 tests/tui/top-model.test.ts | 42 +++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/src/tui/top-model.ts b/src/tui/top-model.ts
index f5db9b7c..c06a6b74 100644
--- a/src/tui/top-model.ts
+++ b/src/tui/top-model.ts
@@ -310,10 +310,20 @@ function buildSupervisorView(
 ): SupervisorView {
   const workers = new Map<string, MutableWorker>()
   let driverSpend = emptySpend
+  // `state.json` and the spawn journal are written by DIFFERENT producers, and their ids need not
+  // agree: the journal's root is the runtime's `runId`, which defaults to a literal unrelated to
+  // the supervisor id the state file records. Recover the journal's own root from its parentless
+  // root spawn, and treat EITHER id as the root everywhere. Checking only `state.id` — which the
+  // metered/settled/cancelled branches used to do — manufactures a phantom worker named after the
+  // runId that never settles, sorts first as RUNNING, and silently captures every steer and cancel.
+  const journalRootId = events.find(
+    (event) => event.kind === 'spawned' && !event.parent && event.label === 'root',
+  )?.id
+  const isRoot = (id: string): boolean => id === state.id || id === journalRootId
 
   for (const event of events) {
     if (event.kind === 'spawned') {
-      if (event.id === state.id || (!event.parent && event.label === 'root')) continue
+      if (isRoot(event.id) || (!event.parent && event.label === 'root')) continue
       const worker = ensureWorker(workers, event.id, event.label ?? event.id)
       worker.label = event.label ?? worker.label
       if (event.parent) worker.parent = event.parent
@@ -326,7 +336,7 @@ function buildSupervisorView(
     }
 
     if (event.kind === 'settled') {
-      if (event.id === state.id) continue
+      if (isRoot(event.id)) continue
       const worker = ensureWorker(workers, event.id, event.id)
       worker.status = event.status === 'down' ? 'down' : 'done'
       if (event.at) worker.endedAt = event.at
@@ -339,7 +349,7 @@ function buildSupervisorView(
     }
 
     if (event.kind === 'cancelled') {
-      if (event.id === state.id) continue
+      if (isRoot(event.id)) continue
       const worker = ensureWorker(workers, event.id, event.id)
       worker.status = 'cancelled'
       if (event.at) worker.endedAt = event.at
@@ -349,7 +359,7 @@ function buildSupervisorView(
 
     if (event.kind === 'metered') {
       const spend = parseSpend(event.spend)
-      if (event.id === state.id) {
+      if (isRoot(event.id)) {
         driverSpend = addSpend(driverSpend, spend)
       } else {
         const worker = ensureWorker(workers, event.id, event.id)
diff --git a/tests/tui/top-model.test.ts b/tests/tui/top-model.test.ts
index 9eb5c09b..46fc4c11 100644
--- a/tests/tui/top-model.test.ts
+++ b/tests/tui/top-model.test.ts
@@ -21,6 +21,48 @@ describe('supervisor top model', () => {
     roots.length = 0
   })
 
+  it('does not manufacture a worker when the journal root id differs from state.json', () => {
+    // state.json and the journal have different producers: the journal's root is the runtime's
+    // `runId`, which defaults to a value unrelated to the supervisor id. A guard that only knows
+    // state.id lets every driver metered/settled event mint a phantom worker named for the runId —
+    // one that never settles, sorts first as RUNNING, and captures steers nothing will read.
+    const root = fixtureRoot()
+    const dir = supervisorRunDir(root, 'sup-mismatch')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'state.json'),
+      JSON.stringify({
+        id: 'sup-mismatch',
+        status: 'running',
+        task: 'root ids disagree',
+        workspaceDir: '/repo',
+        budget: 2,
+      }),
+    )
+    writeFileSync(
+      join(dir, 'spawn-journal.jsonl'),
+      `${[
+        JSON.stringify({ kind: 'spawned', id: 'supervise', label: 'root', at: 1 }),
+        JSON.stringify({
+          kind: 'metered',
+          id: 'supervise',
+          usd: 0.03,
+          tokensIn: 300,
+          tokensOut: 150,
+          at: 2,
+        }),
+        JSON.stringify({ kind: 'spawned', id: 'w-0', parent: 'supervise', label: 'w-0', at: 3 }),
+        JSON.stringify({ kind: 'settled', id: 'w-0', at: 4 }),
+      ].join('\n')}\n`,
+    )
+
+    const snapshot = loadTopSnapshot(root)
+    const view = snapshot.supervisors[0]!
+    expect(view.workers.map((w) => w.id)).toEqual(['w-0'])
+    // The driver's spend belongs to the driver, not to a fabricated worker row.
+    expect(view.workers.some((w) => w.id === 'supervise')).toBe(false)
+  })
+
   it('renders workers, status, token bars, cost bars, and latency histograms from the journal', () => {
     const root = fixtureRoot()
     const dir = supervisorRunDir(root, 'sup-1-rich')