@pellux/goodvibes-tui 2.0.14 → 2.0.16

package/src/panels/fleet-panel.ts

@@ -1,12 +1,12 @@
 // ---------------------------------------------------------------------------
 // fleet-panel.ts
 //
-// — FleetPanel: the live unified observability tree. Renders the
+//, FleetPanel: the live unified observability tree. Renders the
 // registered process fleet (agents incl. WRFC roles, WRFC chains/subtasks,
 // workflow-tool FSMs, watchers, background processes) as a depth-first tree
 // with a selected-row detail region. Session tabs (Part C): Enter on an
 // attachable node (agent/wrfc-chain) opens a tab with that process's
-// transcript/member summary — see fleet-tabs.ts + fleet-transcript.ts. This
+// transcript/member summary, see fleet-tabs.ts + fleet-transcript.ts. This
 // file owns input dispatch and layout; fleet-deep-link.ts owns the
 // cross-panel jump target (item 4).
 // ---------------------------------------------------------------------------
@@ -53,14 +53,14 @@ const C = DEFAULT_PANEL_PALETTE;
 export interface FleetActionCallbacks {
   /** Graceful interruption (AgentManager.cancel / trigger-schedule disable, via the registry). */
   readonly interrupt: (id: string) => boolean;
-  /** Re-arm a `paused` node (disabled trigger/schedule or automation job) — interrupt()'s inverse. Honest false when not paused / non-resumable. */
+  /** Re-arm a `paused` node (disabled trigger/schedule or automation job), interrupt()'s inverse. Honest false when not paused / non-resumable. */
   readonly resume: (id: string) => boolean;
   /** Hard stop, optionally cascading to killable descendants. Returns the node ids acted on. */
   readonly kill: (id: string, opts: { readonly cascade: boolean }) => readonly string[];
   /**
-   * Fetch an agent's conversation history — live (running) or
+   * Fetch an agent's conversation history, live (running) or
    * frozen (just-completed, still in the SDK's retention ring). Empty array
-   * means "unavailable" (evicted, or never registered) — FleetPanel degrades
+   * means "unavailable" (evicted, or never registered), FleetPanel degrades
    * to the on-disk ledger fallback in that case, never fabricating content.
    */
   readonly getConversationSnapshot: (agentId: string) => readonly ConversationMessageSnapshot[];
@@ -69,7 +69,7 @@ export interface FleetActionCallbacks {
   /**
    * Queue a human message for a live in-process agent (or a
    * wrfc-subtask's current live member agent), delivered at the target's
-   * next turn boundary — never mid-token. Honest refusal
+   * next turn boundary, never mid-token. Honest refusal
    * (`{queued:false,reason}`) for anything that cannot take mid-run input
    * (terminal nodes, non-agent kinds, the wrfc-chain coordinator itself).
    */
@@ -112,7 +112,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     actions: Partial<FleetActionCallbacks> = {},
     private readonly configManager: ConfigManager | null = null,
     // The waiting-on-human acts (pick / conflict / discard). Null in a runtime
-    // with no daemon gateway wired — those keys then fall through honestly.
+    // with no daemon gateway wired, those keys then fall through honestly.
     private readonly acts: FleetActs | null = null,
     // The ACP spawn affordance ('n' hosts a discovered third-party agent); null with no gateway wired.
     private readonly spawn: FleetSpawn | null = null,
@@ -128,7 +128,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       this.markDirty();
     });
     // The honest "the agent actually consumed this steer at
-    // its turn boundary" signal — see fleet-tabs.ts's SteerBadgeStatus doc.
+    // its turn boundary" signal, see fleet-tabs.ts's SteerBadgeStatus doc.
     // A read-model without a runtimeBus dep never invokes this (graceful
     // no-op), same degrade as steer()/steerable without a messageBus dep.
     this.unsubConsumed = readModel.subscribeConsumed((event) => {
@@ -184,7 +184,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
   }
 
   /**
-   * True while the steer composer on the active tab is open —
+   * True while the steer composer on the active tab is open,
    * every character of a burst (paste, or several fast-typed chars in one
    * stdin chunk) must land in the draft one at a time rather than being
    * routed away as panel hotkeys or exploded to the main composer. See
@@ -231,21 +231,21 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
 
   protected override getEmptyStateMessage(): string {
     return this.viewMode === 'archived'
-      ? ' Archive is empty — press a on a finished process (or A for all) to move it here.'
+      ? ' Archive is empty: press a on a finished process (or A for all) to move it here.'
       : ' No processes tracked yet.';
   }
 
   /**
    * (cross-restart honesty): a restart starts from an empty `AgentManager` Map
    * (no bridge from a prior registry), so a completed process from a previous
-   * session can never reappear here — a real, permanent limitation, documented
+   * session can never reappear here, a real, permanent limitation, documented
    * rather than implying "nothing has ever run" or that a restart brings it back.
    */
   protected override getEmptyStateActions(): Array<{ command: string; summary: string }> {
     return [
       {
         command: 'previous sessions',
-        summary: "not shown here — this list resets on TUI restart; each agent's .goodvibes/tui/sessions/<id>.jsonl event log still persists on disk",
+        summary: "not shown here: this list resets on TUI restart; each agent's .goodvibes/tui/sessions/<id>.jsonl event log still persists on disk",
       },
     ];
   }
@@ -281,7 +281,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
    * Re-locate `selectedNodeId` in the current snapshot and repoint
    * `selectedIndex` at it, so the selection follows a specific process across
    * adds/removes/reorders instead of drifting onto whatever row occupies the old
-   * index. When the anchored node is gone (pruned) — or no anchor exists yet —
+   * index. When the anchored node is gone (pruned), or no anchor exists yet,
    * falls back to clampSelection() (nearest valid index) and re-anchors there.
    */
   private reanchorSelection(): void {
@@ -308,7 +308,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     if (idx < 0) { this.setError('node no longer present.'); return; }
     // A successful reveal must be VISIBLE: with a session tab active, render()
     // routes to the tab view and the selection change would be silently
-    // swallowed (batch refutation finding 1) — return to the tree first
+    // swallowed (batch refutation finding 1), return to the tree first
     // (tabs kept; only the active view switches).
     this.tabsState = { tabs: this.tabsState.tabs, activeTabIndex: 0 };
     this.clearError(); this.selectedIndex = idx; this.selectedNodeId = target.id; this.markDirty();
@@ -394,7 +394,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     // Once the steer composer is open on the active tab, it
     // owns EVERY key (same full-priority-while-composing contract as
     // git-panel.ts's commitMessage entry) until Enter (submit) or Esc
-    // (cancel) — a burst/paste and single hotkeys like 'j'/'s'/'[' all land
+    // (cancel), a burst/paste and single hotkeys like 'j'/'s'/'[' all land
     // in the draft, never as tree/tab navigation (focus rule).
     const composingTab = activeFleetTab(this.tabsState);
     if (composingTab && composingTab.steerDraft !== null) {
@@ -402,9 +402,9 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     }
 
     // Tab switching works from ANY view (root tree or an attached tab) once
-    // at least one tab is open — [ / ] step through Tree, tab 1, tab 2, ...
+    // at least one tab is open, [ / ] step through Tree, tab 1, tab 2, ...
     // Ctrl+X detach is handled by interceptPanelClose(), not handleInput (it
-    // must win a global-shortcut race — see that method's doc comment).
+    // must win a global-shortcut race, see that method's doc comment).
     if ((key === '[' || key === ']') && this.tabsState.tabs.length > 0) {
       this.tabsState = stepFleetTab(this.tabsState, key === ']' ? 1 : -1);
       this.markDirty();
@@ -422,7 +422,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       if (key === 's') {
         return this.tryOpenSteerDraft(activeFleetTab(this.tabsState)!);
       }
-      // A session tab is focused — the tree isn't visible, so tree-only keys
+      // A session tab is focused, the tree isn't visible, so tree-only keys
       // (navigate/i/K/f/Enter) don't apply here.
       return false;
     }
@@ -477,7 +477,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       // Guard: only consume on a real, non-terminal node (cockpit-panel.ts
       // precedent) so the key falls through when there is nothing to act on.
       if (!selected || isTerminalProcessState(selected.node.state)) return false;
-      // Not every kind can be interrupted (only 'agent' nodes ever are — see
+      // Not every kind can be interrupted (only 'agent' nodes ever are, see
       // the SDK's fleet adapters: schedule/trigger/watcher/workflow/
       // wrfc-chain/wrfc-subtask/background-process all report
       // capabilities.interruptible: false unconditionally). Consume the key
@@ -495,7 +495,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
 
     if (key === 'K') {
       if (!selected || isTerminalProcessState(selected.node.state)) return false;
-      // Observed foreign agents have killable:false — the refusal below reads
+      // Observed foreign agents have killable:false, the refusal below reads
       // honestly; goodvibes only observes them, so stop is never offered.
       if (!selected.node.capabilities.killable) {
         this.setError(`${selected.node.kind} does not support kill.`);
@@ -541,7 +541,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     }
 
     if (key === 's') {
-      // An earlier replay fix: 's' from the TREE was silently dead — steering
+      // An earlier replay fix: 's' from the TREE was silently dead, steering
       // required an undiscoverable Enter-attach first. Attach-and-steer in
       // one press for a steerable node; honest refusal otherwise.
       if (!selected) return false;
@@ -550,10 +550,10 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       // acts.handleTreeKey above (opens the composer in the row's detail), so it
       // never reaches this attach path.
       // Closure replay note: a node that FINISHED in the hint→keypress race
-      // window must say so — "does not support steer" is misleading for an
+      // window must say so, "does not support steer" is misleading for an
       // agent whose only problem is being done.
       if (isTerminalProcessState(node.state)) {
-        this.setError(`${node.kind} already finished — nothing to steer.`);
+        this.setError(`${node.kind} already finished: nothing to steer.`);
         return true;
       }
       if (!node.capabilities.steerable || !isAttachableFleetKind(node.kind)) {
@@ -571,14 +571,14 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
   }
 
   /**
-   * The `s` gate — mirrors the i/K capability-gating template
+   * The `s` gate, mirrors the i/K capability-gating template
    * exactly (guard on the live node existing, non-terminal, and the specific
    * capability; consume the key and say so rather than silently no-op-ing).
    */
   private tryOpenSteerDraft(tab: FleetTab): boolean {
     const node = this.findLiveNode(tab.nodeId);
     if (!node || isTerminalProcessState(node.state)) {
-      this.setError(`${node?.kind ?? tab.kind} already finished — nothing to steer.`);
+      this.setError(`${node?.kind ?? tab.kind} already finished: nothing to steer.`);
       return true;
     }
     if (!node.capabilities.steerable) {
@@ -590,7 +590,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     return true;
   }
 
-  /** Dispatch for the open steer composer — mirrors git-panel.ts's handleCommitMessageInput. */
+  /** Dispatch for the open steer composer, mirrors git-panel.ts's handleCommitMessageInput. */
   private handleSteerInput(tab: FleetTab, key: string): boolean {
     if (isPanelSearchCancel(key)) {
       tab.steerDraft = null;
@@ -617,7 +617,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       return true;
     }
     // Ordinary typing AND a pasted multi-line block's line-break characters
-    // (delivered one at a time through the same burst pipeline — see
+    // (delivered one at a time through the same burst pipeline, see
     // isCapturingTextBurst) both flow through appendSteerText, which
     // normalizes \r/\n to a collapsed space instead of corrupting the
     // one-line field or silently dropping the content.
@@ -658,7 +658,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     return renderFleetRowLine(row, width, stopping, blocked, this.steerBadgeForNode(row.node.id), C);
   }
 
-  /** A node's steer badge, looked up via its attached tab (if any) — null when the node has no tab or no active/recent steer. */
+  /** A node's steer badge, looked up via its attached tab (if any), null when the node has no tab or no active/recent steer. */
   private steerBadgeForNode(nodeId: string): SteerBadge | null {
     return this.tabsState.tabs.find((t) => t.nodeId === nodeId)?.steerBadge ?? null;
   }
@@ -686,7 +686,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     const snapshotRows = this.readModel.getSnapshot().rows;
     const liveNode = snapshotRows.find((row) => row.node.id === tab.nodeId)?.node ?? null;
     // The steer composer only ever applies to 'agent' tabs
-    // (wrfc-chain has no conversation loop of its own — see
+    // (wrfc-chain has no conversation loop of its own, see
     // fleet-tabs.ts's FleetAttachableKind doc); the live-node lookup is
     // shared with the isTerminal computation below either way.
     const canSteer = liveNode !== null && !isTerminalProcessState(liveNode.state) && liveNode.capabilities.steerable;
@@ -714,7 +714,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       ));
     } else if (tab.steerBadge && !this.stopTracker.isStopping(tab.nodeId)) {
       // A queued-steer promise ("delivers on its next turn") must not render
-      // while a stop is in flight for this node — there may be no next turn
+      // while a stop is in flight for this node, there may be no next turn
       // (refutation finding 4). The badge reconciles to dropped/consumed once
       // the node's terminal state lands.
       composerLines.push(renderSteerBadgeLine(tab.steerBadge, width, palette, liveNode?.label));
@@ -756,7 +756,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       ...(stripLine ? [{ lines: [stripLine] }] : []),
       { lines: contentLines },
     ];
-    return buildPanelWorkspace(width, height, { title: `Fleet — ${tab.label}`, sections, footerLines, palette });
+    return buildPanelWorkspace(width, height, { title: `Fleet: ${tab.label}`, sections, footerLines, palette });
   }
 
   private renderTreeView(width: number, height: number): Line[] {
@@ -768,7 +768,7 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
       footer.push(...this.renderDetail(selected, width));
     }
 
-    // Capability-gated tree hints — only advertise i/K/p when the selected node
+    // Capability-gated tree hints, only advertise i/K/p when the selected node
     // can actually accept them (most kinds are never interruptible; nothing is
     // killable once terminal), incl. the d2 state-dependent p pause/resume chip.
     // Mirrors the handleInput guards above. See buildFleetTreeHints (fleet-stop.ts).
@@ -777,13 +777,13 @@ export class FleetPanel extends ScrollableListPanel<FleetTreeRow> {
     const blockedCount = this.readModel.getSnapshot().blockedNodeIds.length;
     const hints = buildFleetTreeHints(selected?.node, this.follow, this.tabsState.tabs.length > 0, this.viewMode, blockedCount);
 
-    // Tab strip renders only when tabs exist — omitting it entirely with no
+    // Tab strip renders only when tabs exist, omitting it entirely with no
     // tabs attached keeps the pre-session-tab root-tree rendering byte-identical.
     const stripLine = renderFleetTabStrip(this.tabsState, width);
     const header = stripLine ? [stripLine] : undefined;
 
     return this.renderList(width, height, {
-      title: this.viewMode === 'archived' ? 'Fleet — Archived' : 'Fleet',
+      title: this.viewMode === 'archived' ? 'Fleet: Archived' : 'Fleet',
       header,
       footer,
       hints,

package/src/panels/fleet-read-model.ts

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // fleet-read-model.ts
 //
-// (Fleet tree panel) — pure, testable read-model over the SDK's live
+// (Fleet tree panel), pure, testable read-model over the SDK's live
 // process registry (@pellux/goodvibes-sdk/platform/runtime/fleet, landed on
 // SDK main as). No BasePanel/rendering dependency: this module owns the
 // flat ProcessNode[] -> tree transformation, the honest cost/token
@@ -12,14 +12,14 @@
 //     FleetRegistryNode/FleetRegistry adapter pair. The real
 //     createProcessRegistry() ProcessNode already carries elapsedMs,
 //     usage, costUsd, costState, and currentActivity directly, so no
-//     adapter layer is needed here — this module consumes ProcessNode
+//     adapter layer is needed here, this module consumes ProcessNode
 //     straight from the registry and only owns the tree-walk + aggregate
 //     + presentation-mapping logic the SDK does not provide.
 //   - Tree-walk shape (connectors, cycle guard, leftover pass) is ported
 //     from renderer/process-modal.ts's appendAgentSubtree/
 //     appendAgentGroupEntries, generalized from AgentRecord to ProcessNode
 //     and from WRFC-role ordering to plain startedAt ordering (ProcessNode
-//     has no role concept — parentId alone expresses the hierarchy, and the
+//     has no role concept, parentId alone expresses the hierarchy, and the
 //     SDK guarantees every parentId either resolves or the node is a root).
 //   - Cost/token honesty mirrors agent-inspector-shared.ts's
 //     hasReportedUsage convention: an all-zero-but-present usage object is
@@ -65,8 +65,8 @@ export interface FleetSnapshot {
   /** Count of nodes in an actively-working state (see isRunningProcessState). */
   readonly runningCount: number;
   /**
-   * Ids of the nodes that are "blocked on me" — waiting on a user approval or
-   * user input right now (see isBlockedOnUserState) — in display (row) order.
+   * Ids of the nodes that are "blocked on me", waiting on a user approval or
+   * user input right now (see isBlockedOnUserState), in display (row) order.
    * This is a DERIVED view over the same node states the rows already carry,
    * never a second source of truth: the panel reads it to badge/jump, it is
    * not a store. Empty when nothing is waiting on the operator.
@@ -76,20 +76,20 @@ export interface FleetSnapshot {
 }
 
 // ---------------------------------------------------------------------------
-// State classification — glyph/tone mapping (pure, unit-testable)
+// State classification, glyph/tone mapping (pure, unit-testable)
 // ---------------------------------------------------------------------------
 
 export type FleetStateTone = 'active' | 'success' | 'failure' | 'warn' | 'muted';
 
 // Design ruling: this is a DIFFERENT table from the SDK presentation
-// contract's STATE_GLYPHS (@pellux/goodvibes-sdk/platform/presentation) — that
+// contract's STATE_GLYPHS (@pellux/goodvibes-sdk/platform/presentation), that
 // one is a 4-state semantic alias (good/warn/bad/info) shared by the TUI and
 // agent renderers; this one is a 12-state ProcessNode taxonomy specific to the
 // Fleet tree panel (thinking/executing-tool/awaiting-approval/streaming/
 // stalled/retrying/done/failed/killed/interrupted/idle/queued/paused), and no
 // other surface (checked: the agent has no fleet-panel renderer) consumes it
 // today. Per the presentation-parity brief, a table only moves to the SDK
-// contract when 2+ surfaces need it — this one stays TUI-renderer-local.
+// contract when 2+ surfaces need it, this one stays TUI-renderer-local.
 const STATE_GLYPHS: Record<ProcessState, string> = {
   thinking: '◔',
   'executing-tool': '●',
@@ -100,7 +100,7 @@ const STATE_GLYPHS: Record<ProcessState, string> = {
   done: '✓',
   failed: '✗',
   killed: '⊘',
-  // A distinct TERMINAL outcome from 'killed' —
+  // A distinct TERMINAL outcome from 'killed',
   // both come from AgentManager.cancel(), but a graceful interrupt request
   // ('the operator asked nicely') is display-distinguishable from a hard
   // kill. '◌' verified free against every other glyph in this table.
@@ -108,7 +108,7 @@ const STATE_GLYPHS: Record<ProcessState, string> = {
   idle: '·',
   queued: '…',
   // SDK behavior: schedules/triggers/automation jobs report 'paused' when
-  // disabled (previously mislabeled 'killed'). NOT terminal — resumable via
+  // disabled (previously mislabeled 'killed'). NOT terminal, resumable via
   // ProcessRegistry.resume() (the full pause/resume UI lives in
   // fleet-stop.ts). '❚' verified free against every other glyph in this table.
   paused: '❚',
@@ -124,7 +124,7 @@ const STATE_TONES: Record<ProcessState, FleetStateTone> = {
   done: 'success',
   failed: 'failure',
   killed: 'muted',
-  // 'warn' (amber), not 'muted' like killed — an interrupt is a deliberate
+  // 'warn' (amber), not 'muted' like killed, an interrupt is a deliberate
   // operator action worth noticing, not a passive/neutral outcome.
   interrupted: 'warn',
   idle: 'muted',
@@ -133,13 +133,13 @@ const STATE_TONES: Record<ProcessState, FleetStateTone> = {
   paused: 'muted',
 };
 
-/** Terminal states — interrupt/kill are not offered; not counted as running. */
+/** Terminal states, interrupt/kill are not offered; not counted as running. */
 const TERMINAL_STATES = new Set<ProcessState>(['done', 'failed', 'killed', 'interrupted']);
 
 /**
  * States that mean "this node is waiting on ME right now" via the state field
  * alone. The registry now also publishes the canonical `needsAttention`
- * projection (reason 'approval' | 'input' — see fleetNodeAttention below),
+ * projection (reason 'approval' | 'input', see fleetNodeAttention below),
  * which every surface prefers; this set remains only as the fallback mapping
  * for nodes without the projection, so nothing regresses on older registries.
  */
@@ -164,16 +164,16 @@ const KIND_TAGS: Record<ProcessKind, string> = {
   phase: 'phase',
   'work-item': 'item',
   // The repo source-tree code index (adapters/code-index.ts).
-  // A single leaf node — never a rollup of other flat-list nodes (see
-  // ROLLUP_KINDS below) — so no other list in this module needs updating.
+  // A single leaf node, never a rollup of other flat-list nodes (see
+  // ROLLUP_KINDS below), so no other list in this module needs updating.
   'code-index': 'index',
   // A hosted third-party coding agent (Claude Code / Codex / opencode) spawned
-  // over ACP (adapters/acp-host.ts). A plain leaf row — steer/stop/attention
+  // over ACP (adapters/acp-host.ts). A plain leaf row, steer/stop/attention
   // ride on its node capabilities and the SDK's needsAttention projection, so
   // this glyph/label is the only read-model special-casing it needs.
   'acp-agent': 'acp',
   // An externally-launched foreign coding agent (Claude Code / Codex / opencode)
-  // that goodvibes did NOT spawn — observed read-only from OS signals. The row's
+  // that goodvibes did NOT spawn, observed read-only from OS signals. The row's
   // first job is visibility ("it's in claude or codex"); it is never counted in
   // any our-fleet count, never carries a stop affordance, and steer is drill-in
   // only. See ObservedProcess handling in fleet-panel-format.ts.
@@ -200,14 +200,14 @@ export function isRunningProcessState(state: ProcessState): boolean {
   return RUNNING_STATES.has(state);
 }
 
-/** True when a node is waiting on a user approval or user input right now — "blocked on me". */
+/** True when a node is waiting on a user approval or user input right now, "blocked on me". */
 export function isBlockedOnUserState(state: ProcessState): boolean {
   return BLOCKED_ON_USER_STATES.has(state);
 }
 
 /**
  * The node's waiting-on-human classification, preferring the SDK's canonical
- * `needsAttention` projection (reason 'approval' | 'input' — broader than the
+ * `needsAttention` projection (reason 'approval' | 'input', broader than the
  * awaiting-approval state alone: it also covers a session waiting on user
  * input). Falls back to the state-derived mapping for registries that predate
  * the projection, so nothing regresses. This is THE membership every
@@ -228,11 +228,11 @@ export function isBlockedOnUserNode(node: ProcessNode): boolean {
  * The literal badge text for a waiting-on-human node, by reason. Every reason
  * is a first-class member of the ONE waiting-on-human state class (same ⚑
  * glyph, same jump key, same count) but names WHY in its own words:
- *   - 'approval' — a tool call is held for an approve/deny decision.
- *   - 'input'    — the node is otherwise blocked on operator input.
- *   - 'pick'     — a best-of-N attempt group is ready and only a human's
+ *   - 'approval', a tool call is held for an approve/deny decision.
+ *   - 'input'   , the node is otherwise blocked on operator input.
+ *   - 'pick'    , a best-of-N attempt group is ready and only a human's
  *                  winner pick advances it.
- *   - 'conflict' — a merge conflict needs a human resolution before the work
+ *   - 'conflict', a merge conflict needs a human resolution before the work
  *                  can land.
  * The pick/conflict wording is deliberately DISTINCT from the bare
  * 'blocked on you' so an operator reads the required act, not just the state.
@@ -248,7 +248,7 @@ export function fleetAttentionText(attention: ProcessAttention): string {
 }
 
 /**
- * The stall marker for a row — 'quiet Nm' (or 'quiet NhMm' past an hour),
+ * The stall marker for a row, 'quiet Nm' (or 'quiet NhMm' past an hour),
  * derived from the read-model's stall tell (pure timestamp comparison on the
  * registry side; a live node whose last observable output is older than the
  * threshold). Null when the node is not stalled-quiet.
@@ -290,12 +290,12 @@ export function hasFleetCost(costUsd: number | null | undefined, costState: Proc
 }
 
 // ---------------------------------------------------------------------------
-// Tree builder — pure, testable (ported tree-walk shape from process-modal.ts)
+// Tree builder, pure, testable (ported tree-walk shape from process-modal.ts)
 // ---------------------------------------------------------------------------
 
 /**
  * Sibling comparator. `blockedSubtree` is the set of node ids whose own subtree
- * contains a node blocked on the user (see collectBlockedSubtrees) — those
+ * contains a node blocked on the user (see collectBlockedSubtrees), those
  * siblings sort to the TOP of their level so a blocked node (and the family
  * that leads to it) floats up the tree, at every depth, without breaking the
  * parent/child structure. Ties fall back to startedAt then id, unchanged.
@@ -367,7 +367,7 @@ function appendSubtree(
 
 /**
  * Flatten a ProcessNode[] into a stable depth-first FleetTreeRow[] list.
- * Root-level rows (depth 0) carry an empty treePrefix (multi-root forest —
+ * Root-level rows (depth 0) carry an empty treePrefix (multi-root forest,
  * each top-level process family renders without a connector to its
  * unrelated siblings); connectors appear starting at depth 1. Defensive
  * cycle guard: a self-referencing or looping parentId chain is walked once
@@ -391,7 +391,7 @@ export function buildFleetRows(nodes: readonly ProcessNode[]): FleetTreeRow[] {
   }
 
   // Blocked-on-user nodes (and the families that lead to them) float to the top
-  // at every level — see makeCompareNodes / collectBlockedSubtrees. Derived from
+  // at every level, see makeCompareNodes / collectBlockedSubtrees. Derived from
   // the live node states on this same pass; never a stored flag.
   const blockedSubtree = collectBlockedSubtrees(nodes, childrenByParent);
   const compare = makeCompareNodes(blockedSubtree);
@@ -416,11 +416,11 @@ export function buildFleetRows(nodes: readonly ProcessNode[]): FleetTreeRow[] {
 /**
  * Kinds whose usage/costUsd (and, for 'running', whose derived state) are the
  * SDK's OWN rollup of *other* nodes that ALSO appear individually in the flat
- * list — summing across every flat node would therefore double-count them.
+ * list, summing across every flat node would therefore double-count them.
  * Per registry.ts assemble() + wrfc.ts adaptChain/adaptSubtask:
  *   - 'wrfc-chain': usage/costUsd = sum over the chain's member agents
  *     (chain.allAgentIds minus the owner) via adaptChain's aggregateCost/
- *     sumUsage — those member agents are pushed onto the flat node list as
+ *     sumUsage, those member agents are pushed onto the flat node list as
  *     their own 'agent' nodes too. The chain's derived ProcessState ('running'
  *     while any phase is active) likewise just mirrors its members' states.
  *   - 'wrfc-subtask': never carries usage/cost (adaptSubtask always sets
@@ -431,32 +431,32 @@ export function buildFleetRows(nodes: readonly ProcessNode[]): FleetTreeRow[] {
  *     nonzero cost/token reading (defense in depth against a future adapter
  *     change, not load-bearing).
  *
- * Orchestration-engine additions — verified against adapters/orchestration.ts:
+ * Orchestration-engine additions, verified against adapters/orchestration.ts:
  *   - 'workstream': adaptWorkstream SUMS every work-item's usage/costUsd
  *     exactly once (sumWorkItemUsage/aggregateWorkItemCost), the same
- *     "rollup of nodes that also appear individually" shape as adaptChain —
+ *     "rollup of nodes that also appear individually" shape as adaptChain,
  *     each work item ALSO appears as its own 'work-item' node in the flat
  *     list, so summing over every flat node would double-count. Its derived
  *     state likewise mirrors its items' states, so it is excluded from
  *     runningCount for the same non-double-counting reason as 'wrfc-chain'.
  *   - 'phase': adaptPhase reports NO usage/cost (mirrors adaptSubtask's
- *     "report nothing" choice exactly — usage: undefined, costUsd: null,
+ *     "report nothing" choice exactly, usage: undefined, costUsd: null,
  *     costState: 'unpriced') and its 'running' state mirrors whichever
  *     work-item currently occupies it. Same defense-in-depth inclusion as
  *     'wrfc-subtask': never contributes today, excluded anyway in case a
  *     future adapter change gives it one.
  *   - 'work-item' is deliberately NOT in this set: unlike a phase, a work
  *     item carries its OWN direct usage/cost (item.usage, cumulative across
- *     every phase it has visited) — it is the leaf contributor, the
+ *     every phase it has visited), it is the leaf contributor, the
  *     'wrfc-subtask'-for-capabilities analogue but the 'agent'-for-usage
  *     analogue. Excluding it would silently zero out real cost/token totals.
  *
- * 'code-index' is deliberately NOT in this set either —
+ * 'code-index' is deliberately NOT in this set either,
  * adaptCodeIndex yields exactly one standalone ProcessNode per registry
  * (never a parent whose children ALSO appear individually in the flat
  * list), so it is a leaf like 'agent'/'work-item', not a grouping construct.
  * It reports no usage/cost (an index build has no LLM turn), so it never
- * contributes to totalCost/totalTokens regardless — its running state DOES
+ * contributes to totalCost/totalTokens regardless, its running state DOES
  * count toward runningCount while building, which is correct: it is a real,
  * distinct unit of work, not an arithmetic sum of other rows.
  */
@@ -465,11 +465,11 @@ const ROLLUP_KINDS = new Set<ProcessKind>(['wrfc-chain', 'wrfc-subtask', 'workst
 /**
  * True for the WRFC owner agent's node specifically: an 'agent'-kind node
  * whose source AgentRecord has wrfcRole === 'owner'. The owner runs no LLM
- * turn itself — at chain completion the SDK backfills owner.usage from
+ * turn itself, at chain completion the SDK backfills owner.usage from
  * aggregateChainUsage(chain) (wrfc-controller.ts completeOwnerAgent), which
  * is the SAME phase-children total already carried by the chain node AND by
  * each phase-child agent's own node. Detected via the opaque `raw` field
- * (the AgentRecord) since ProcessNode itself has no wrfcRole — this is the
+ * (the AgentRecord) since ProcessNode itself has no wrfcRole, this is the
  * one place fleet-read-model reaches into `raw` for aggregation honesty
  * rather than drill-down display.
  */
@@ -483,7 +483,7 @@ function isWrfcOwnerAgentNode(node: ProcessNode): boolean {
  * Nodes whose usage/costUsd would double-count against other nodes already
  * in the same flat list (see ROLLUP_KINDS / isWrfcOwnerAgentNode above).
  * Excluded from totalCost/totalTokens. NOT excluded from runningCount by
- * this predicate alone — see isFleetRunningLeaf.
+ * this predicate alone, see isFleetRunningLeaf.
  */
 function isFleetAggregateRollupNode(node: ProcessNode): boolean {
   return ROLLUP_KINDS.has(node.kind) || isWrfcOwnerAgentNode(node);
@@ -492,14 +492,14 @@ function isFleetAggregateRollupNode(node: ProcessNode): boolean {
 /**
  * Nodes that count toward runningCount. Excludes ROLLUP_KINDS (a running
  * wrfc-chain/wrfc-subtask reflects the very same unit of work as its running
- * member agent, which is already counted) but — unlike the cost/token
- * exclusion above — does NOT exclude the WRFC owner agent: the owner is a
+ * member agent, which is already counted) but, unlike the cost/token
+ * exclusion above, does NOT exclude the WRFC owner agent: the owner is a
  * real, distinct supervising process (not an arithmetic sum of other rows),
  * so counting it as "running" alongside its phase children is not a double
  * count in the way summing its rolled-up usage/cost would be.
  */
 function isFleetRunningLeaf(node: ProcessNode): boolean {
-  // Observed foreign agents are NEVER counted in our own fleet counts — they
+  // Observed foreign agents are NEVER counted in our own fleet counts, they
   // are externally-launched sessions goodvibes only watches, not work it runs.
   return node.kind !== 'observed-external' && !ROLLUP_KINDS.has(node.kind) && isRunningProcessState(node.state);
 }
@@ -535,7 +535,7 @@ export function buildFleetSnapshot(nodes: readonly ProcessNode[], capturedAt: nu
 }
 
 /**
- * The fleet's honest leaf cost total — the SAME figure as
+ * The fleet's honest leaf cost total, the SAME figure as
  * FleetSnapshot.totalCost, but computed in one pass WITHOUT building the display
  * rows, for cheap per-frame use (the always-visible footer). Excludes rollup
  * aggregates (chain/subtask/workstream/phase) AND the WRFC owner (its usage is a
@@ -555,7 +555,7 @@ export function fleetLeafCostTotal(nodes: readonly ProcessNode[]): number | null
 
 /**
  * The fleet cost figure for the always-visible footer: fleetLeafCostTotal over a
- * fresh registry query, but ONLY while a fleet is live — the idle single-session
+ * fresh registry query, but ONLY while a fleet is live, the idle single-session
  * path must never pay the aggregate-on-read query() scan. Query failures degrade to
  * null (honest "no fleet cost"), never a throw into the render loop.
  */
@@ -569,7 +569,7 @@ export function footerFleetCost(queryNodes: () => readonly ProcessNode[], hasLiv
 }
 
 // ---------------------------------------------------------------------------
-// Read-model — two-factory shape (live / static), mirrors cockpit-read-model.ts
+// Read-model, two-factory shape (live / static), mirrors cockpit-read-model.ts
 // ---------------------------------------------------------------------------
 
 /** Payload of a `COMMUNICATION_CONSUMED` runtime-bus event, narrowed for FleetReadModel consumers. */
@@ -598,7 +598,7 @@ export interface FleetReadModel {
    * Queue a human message for a live in-process agent (or a
    * wrfc-subtask's current live member), delivered at its next turn
    * boundary. Honest refusal (`{queued:false,reason}`) for anything that
-   * cannot take mid-run input — see ProcessRegistry.steer's doc comment.
+   * cannot take mid-run input, see ProcessRegistry.steer's doc comment.
    */
   steer(id: string, text: string): SteerResult;
   /**
@@ -606,7 +606,7 @@ export interface FleetReadModel {
    * steer at its turn boundary" signal (COMMUNICATION_CONSUMED on the
    * runtime bus's 'communication' domain). Returns an unsubscribe function.
    * A read-model constructed without a runtimeBus (e.g. the static factory,
-   * or a test double) never invokes the listener — graceful no-op, matching
+   * or a test double) never invokes the listener, graceful no-op, matching
    * the steer()/steerable degrade-without-a-dep convention.
    */
   subscribeConsumed(listener: (event: SteerConsumedEvent) => void): () => void;
@@ -630,7 +630,7 @@ export type FleetRegistryLike = Pick<ProcessRegistry, 'query' | 'subscribe' | 'i
 
 /**
  * Create a live FleetReadModel backed by the SDK's ProcessRegistry.
- * `runtimeBus` is optional (narrowed to just `onDomain`) — without it,
+ * `runtimeBus` is optional (narrowed to just `onDomain`), without it,
  * `subscribeConsumed` degrades to a no-op, same shape as the registry's own
  * messageBus-optional degrade for steer()/steerable.
  */
@@ -685,7 +685,7 @@ export function createFleetReadModel(
   };
 }
 
-/** Create a static FleetReadModel for tests/goldens — no live registry, no timers. */
+/** Create a static FleetReadModel for tests/goldens, no live registry, no timers. */
 export function createStaticFleetReadModel(snapshot: FleetSnapshot): FleetReadModel {
   return {
     getSnapshot: () => snapshot,