feat(tui): the supervisor TUI moves into the runtime that produces its state

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

docs/api/README.md

@@ -22,3 +22,4 @@
 - [runtime](runtime.md)
 - [testing](testing.md)
 - [tool-loop](tool-loop.md)
+- [tui](tui.md)

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.

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`