@pellux/goodvibes-tui 1.1.0 → 1.9.0

package/src/runtime/ui-services.ts

@@ -6,7 +6,7 @@ import { createUiReadModels, type UiReadModels, type UiReadModelOptions } from '
 import type { ForensicsRegistry } from '@/runtime/index.ts';
 import type { ControlPlaneRecentEvent } from '@pellux/goodvibes-sdk/platform/control-plane';
 import type { ApprovalBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
-import type { SharedSessionBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
+import { SessionUnionCache, type SessionReadFacade } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
 import type { ShellPathService } from '@/runtime/index.ts';
 import type { HostServiceStatus } from '@/runtime/index.ts';
 import type { SecretsManager } from '../config/secrets.ts';
@@ -39,7 +39,13 @@ export interface UiProviderServices {
 
 export interface UiSessionServices {
   readonly sessionManager: RuntimeServices['sessionManager'];
-  readonly sessionBroker: SharedSessionBroker;
+  /**
+   * The panel-facing session READ source is the cross-surface union
+   * facade, not the raw local broker — in adopted-daemon ('external') mode the
+   * local broker misses sessions hosted for other surfaces. Sync signature
+   * preserved; the facade's cache makes that honest (see session-union-cache.ts).
+   */
+  readonly sessionBroker: SessionReadFacade;
   readonly sessionOrchestration: RuntimeServices['sessionOrchestration'];
   readonly sessionMemoryStore: RuntimeServices['sessionMemoryStore'];
 }
@@ -55,6 +61,7 @@ export interface UiPlatformServices {
   readonly tokenAuditor: RuntimeServices['tokenAuditor'];
   readonly replayEngine: RuntimeServices['replayEngine'];
   readonly webhookNotifier: RuntimeServices['webhookNotifier'];
+  readonly focusTracker: RuntimeServices['focusTracker'];
   readonly policyRuntimeState: RuntimeServices['policyRuntimeState'];
   readonly externalServices?: {
     inspect(): {
@@ -64,6 +71,10 @@ export interface UiPlatformServices {
       readonly httpListenerPortInUse?: boolean;
       readonly daemonStatus?: HostServiceStatus;
       readonly httpListenerStatus?: HostServiceStatus;
+      // Honest session-spine posture for the footer segment, driven by
+      // the spine client's own live wire attempts (not the one-shot adopt probe).
+      readonly sessionSpineActive?: boolean;
+      readonly sessionSpineStatus?: 'unknown' | 'online' | 'offline';
     };
     restart(): Promise<{
       readonly daemonRunning: boolean;
@@ -101,6 +112,10 @@ export interface UiRuntimeSharedServices {
     readonly distributedRuntime: RuntimeServices['distributedRuntime'];
     readonly remoteRunnerRegistry: RuntimeServices['remoteRunnerRegistry'] & RemoteRunnerRegistry;
     readonly remoteSupervisor: RuntimeServices['remoteSupervisor'] & RemoteSupervisor;
+    /** W2.2: the shared live process registry backing the Fleet panel. */
+    readonly processRegistry: RuntimeServices['processRegistry'];
+    /** Wave-3 (W3.2): the shared runtime event bus — the Fleet panel subscribes to its 'communication' domain for the honest steer-consumed signal. */
+    readonly runtimeBus: RuntimeServices['runtimeBus'];
   };
 }
 
@@ -121,6 +136,12 @@ export interface UiRuntimeServices {
 export interface UiRuntimeServicesOptions extends UiReadModelOptions {
   readonly forensicsRegistry?: ForensicsRegistry;
   readonly getControlPlaneRecentEvents?: (limit: number) => readonly ControlPlaneRecentEvent[];
+  /**
+   * The shared session read facade constructed in bootstrap-core (so
+   * bootstrap.ts can drive its adopted-external/embedded/local mode). When omitted
+   * (test callers), a local-only passthrough facade over the broker is auto-created.
+   */
+  readonly sessionUnionCache?: SessionUnionCache;
 }
 
 export function createUiRuntimeServices(
@@ -152,7 +173,7 @@ export function createUiRuntimeServices(
     },
     sessions: {
       sessionManager: runtimeServices.sessionManager,
-      sessionBroker: runtimeServices.sessionBroker,
+      sessionBroker: options.sessionUnionCache ?? new SessionUnionCache({ local: runtimeServices.sessionBroker }),
       sessionOrchestration: runtimeServices.sessionOrchestration,
       sessionMemoryStore: runtimeServices.sessionMemoryStore,
     },
@@ -167,6 +188,7 @@ export function createUiRuntimeServices(
       tokenAuditor: runtimeServices.tokenAuditor,
       replayEngine: runtimeServices.replayEngine,
       webhookNotifier: runtimeServices.webhookNotifier,
+      focusTracker: runtimeServices.focusTracker,
       policyRuntimeState: runtimeServices.policyRuntimeState,
     },
     planning: {
@@ -183,6 +205,8 @@ export function createUiRuntimeServices(
       distributedRuntime: runtimeServices.distributedRuntime,
       remoteRunnerRegistry: runtimeServices.remoteRunnerRegistry,
       remoteSupervisor: runtimeServices.remoteSupervisor,
+      processRegistry: runtimeServices.processRegistry,
+      runtimeBus: runtimeServices.runtimeBus,
     },
     events: createUiRuntimeEvents(runtimeServices.runtimeBus),
     readModels: createUiReadModels(runtimeServices, options),

package/src/runtime/workstream-services.ts

@@ -0,0 +1,327 @@
+// ---------------------------------------------------------------------------
+// workstream-services.ts — Wave 4 (wo703)
+//
+// Constructs the TUI's OrchestrationEngine instance (@pellux/goodvibes-sdk/
+// platform/orchestration, landed on SDK main as wo701/W4.1) and a thin
+// command-facing facade around it. Extracted into its own module rather than
+// built inline in services.ts: services.ts sits at the architecture check's
+// 800-line cap (scripts/check-architecture.ts), so any new service gets its
+// own construction module and a single wiring call there (mirrors
+// createWorkflowServices's one-function-bundle shape).
+//
+// Why a facade, not the bare engine: createOrchestrationEngine() is a pure
+// construction call with no auto-start and NO concept of a not-yet-launched
+// "proposal" a human can review/edit before anything is spent — its only
+// creation entry point, createWorkstream(), immediately materializes a real,
+// ticking-eligible Workstream. The /workstream command module
+// (input/commands/workstream-runtime.ts) needs a create -> propose -> approve
+// -> launch flow (Pillar-3 doctrine: render the plan in the transcript before
+// spending anything, mirroring /plan's approve step). REALITY-WINS DIVERGENCE
+// from the wo703 design brief: the brief recommended an "engine-owned/
+// journal-backed" draft so `/workstream status` could re-render a pending
+// proposal after a restart; the real engine (verified against the linked SDK
+// build) exposes no pre-creation draft concept at all, so WorkstreamDraft
+// below is process-lifetime-only state, owned by this module's facade
+// instance (constructed once, threaded onto CommandContext) — never a
+// module-level ambient global. A draft that existed only in memory is lost on
+// restart, same as an unsent chat draft; that is a real, stated limitation,
+// not a bug.
+// ---------------------------------------------------------------------------
+
+import {
+  createOrchestrationEngine,
+  fromChainSpec,
+  fromPlanProposal,
+  type CreateWorkstreamInput,
+  type OrchestrationEngine,
+  type WorkstreamIsolation,
+} from '@pellux/goodvibes-sdk/platform/orchestration';
+export type { OrchestrationEngine } from '@pellux/goodvibes-sdk/platform/orchestration';
+import {
+  AdaptivePlanner,
+  decomposeGoal,
+  type DecompositionGate,
+  type DecompositionServiceConfig,
+  type DecomposeGoalResult,
+  type PlannerInputs,
+  type PlanProposal,
+} from '@pellux/goodvibes-sdk/platform/core';
+import { createAgentManagerDecompositionRunner } from '@pellux/goodvibes-sdk/platform/agents';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { AgentManager } from '@pellux/goodvibes-sdk/platform/tools';
+import type { RuntimeEventBus } from '@/runtime/index.ts';
+import { calcSessionCost, isModelPriced } from '../export/cost-utils.ts';
+
+export interface WorkstreamServicesDeps {
+  readonly agentManager: Pick<AgentManager, 'spawn' | 'getStatus' | 'cancel' | 'registerCancellationSignal' | 'releaseCancellationSignal'>;
+  readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
+  readonly adaptivePlanner: AdaptivePlanner;
+  readonly runtimeBus: RuntimeEventBus;
+  readonly projectRoot: string;
+}
+
+/**
+ * Honest provenance for how a draft's decomposition was produced. Derived from
+ * the SDK decomposition service's outcome so the draft render can state plainly
+ * whether a planning agent decomposed the goal, or the heuristic path did (and
+ * if so, why).
+ */
+export interface WorkstreamDraftProvenance {
+  readonly kind: 'agent' | 'heuristic-configured' | 'gate-declined' | 'fallback';
+  readonly itemCount: number;
+  readonly agentCostUsd?: number | undefined;
+  readonly agentTokens?: number | undefined;
+  readonly elapsedMs?: number | undefined;
+  readonly fallbackReason?: string | undefined;
+}
+
+/** A not-yet-launched /workstream proposal. See this file's header doc for why it lives here rather than on the engine. */
+export interface WorkstreamDraft {
+  readonly id: string;
+  task: string;
+  spec: CreateWorkstreamInput;
+  readonly gate: DecompositionGate;
+  /** The engine-agnostic decomposition proposal (model- or heuristic-produced). */
+  proposal: PlanProposal;
+  /** How that proposal came to be, for honest rendering. */
+  provenance: WorkstreamDraftProvenance;
+  approved: boolean;
+  readonly createdAt: number;
+}
+
+/** `ctx.session.workstreamEngine`'s real shape: the live engine plus the draft-proposal bookkeeping the engine itself has no concept of. */
+export interface WorkstreamCommandService {
+  readonly engine: OrchestrationEngine;
+  /** Spawn a bounded read-only planning agent to decompose the goal (with automatic heuristic fallback), then hold the draft. Async because the planning agent is real. `isolation` omitted ⇒ the engine's own default ('shared'); see CreateWorkstreamInput.isolation (SDK). */
+  proposeDraft(task: string, isolation?: WorkstreamIsolation): Promise<WorkstreamDraft>;
+  getDraft(id: string): WorkstreamDraft | undefined;
+  listDrafts(): WorkstreamDraft[];
+  /** Re-derive a held draft's spec + decomposition from a new task string. Clears any prior approval — an edit must be re-approved. `isolation` omitted ⇒ keeps the draft's current choice (an edit that only changes the task text must not silently reset isolation back to shared). */
+  editDraft(id: string, task: string, isolation?: WorkstreamIsolation): Promise<WorkstreamDraft | undefined>;
+  approveDraft(id: string): WorkstreamDraft | undefined;
+  removeDraft(id: string): boolean;
+  /** Materialize an approved draft into a real, running Workstream (engine.createWorkstream + start), then drop the draft. Null when the draft is missing or not approved. */
+  launchDraft(id: string): { workstreamId: string } | null;
+}
+
+export interface WorkstreamServices {
+  readonly orchestrationEngine: OrchestrationEngine;
+  readonly workstreamCommands: WorkstreamCommandService;
+}
+
+/**
+ * Placeholder planner inputs until a richer risk/latency signal is wired in.
+ * `/workstream create` is inherently a multi-step authoring surface, so
+ * isMultiStep is always true; the rest are neutral defaults that let
+ * AdaptivePlanner's real scoring run rather than short-circuiting it.
+ */
+function buildPlannerInputs(task: string): PlannerInputs {
+  return {
+    riskScore: 0.3,
+    latencyBudgetMs: Number.POSITIVE_INFINITY,
+    isMultiStep: true,
+    remoteAvailable: false,
+    backgroundEligible: false,
+    taskDescription: task,
+  };
+}
+
+/**
+ * Read the planner decomposition config (mode + bounds) from the config
+ * manager, defensively defaulting anything missing or invalid. Real config
+ * always supplies the DEFAULT_CONFIG values; these fallbacks matter only for a
+ * partially-stubbed config manager, and guarantee finite positive bounds so a
+ * planning-agent poll can never loop forever on a NaN deadline.
+ */
+function readDecompositionConfig(configManager: Pick<ConfigManager, 'get'>): DecompositionServiceConfig {
+  const num = (value: unknown, fallback: number): number =>
+    typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+  return {
+    mode: configManager.get('planner.decomposition') === 'heuristic' ? 'heuristic' : 'agent',
+    bounds: {
+      maxTurns: num(configManager.get('planner.maxTurns'), 6),
+      tokenCeiling: num(configManager.get('planner.tokenCeiling'), 120_000),
+      wallTimeoutMs: num(configManager.get('planner.wallTimeoutMs'), 60_000),
+    },
+  };
+}
+
+/** Honest cost estimator: prices the planning agent's tokens only when the
+ *  session's default model is one we actually have pricing for; otherwise the
+ *  render falls back to a raw token count. Never throws. */
+function makeCostEstimator(configManager: Pick<ConfigManager, 'get'>): (usage: { inputTokens: number; outputTokens: number; cacheReadTokens?: number | undefined; cacheWriteTokens?: number | undefined }) => number | undefined {
+  return (usage) => {
+    try {
+      const model = configManager.get('provider.model') as unknown as string | undefined;
+      if (!model || !isModelPriced(model)) return undefined;
+      return calcSessionCost(usage.inputTokens, usage.outputTokens, usage.cacheReadTokens ?? 0, usage.cacheWriteTokens ?? 0, model);
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+function toProvenance(result: DecomposeGoalResult): WorkstreamDraftProvenance {
+  const p = result.proposal;
+  const kind: WorkstreamDraftProvenance['kind'] =
+    result.outcome.kind === 'agent' ? 'agent'
+      : result.outcome.kind === 'heuristic-configured' ? 'heuristic-configured'
+        : result.outcome.kind === 'gate-declined' ? 'gate-declined'
+          : 'fallback';
+  return {
+    kind,
+    itemCount: p.workItems.length,
+    ...(p.agentCostUsd !== undefined ? { agentCostUsd: p.agentCostUsd } : {}),
+    ...(p.agentUsage ? { agentTokens: p.agentUsage.totalTokens } : {}),
+    ...(p.elapsedMs !== undefined ? { elapsedMs: p.elapsedMs } : {}),
+    ...(p.fallbackReason ? { fallbackReason: p.fallbackReason } : {}),
+  };
+}
+
+function createWorkstreamCommandService(
+  engine: OrchestrationEngine,
+  adaptivePlanner: AdaptivePlanner,
+  configManager: Pick<ConfigManager, 'get' | 'getCategory'>,
+  agentManager: Pick<AgentManager, 'spawn' | 'getStatus' | 'cancel'>,
+  projectRoot: string,
+): WorkstreamCommandService {
+  const drafts = new Map<string, WorkstreamDraft>();
+
+  /**
+   * Run the SDK decomposition service: it spawns a bounded, read-only planning
+   * agent (which surfaces in the fleet like any agent — kill/steer reach it,
+   * and a kill lands as a 'cancelled' fallback) and validates its structured
+   * output, or falls back to the heuristic single-item path on any failure.
+   * The returned proposal is engine-agnostic; the launchable `spec` is still
+   * derived by `buildSpec` (see below).
+   */
+  async function decompose(task: string): Promise<DecomposeGoalResult> {
+    const runner = createAgentManagerDecompositionRunner({ agentManager });
+    return decomposeGoal(
+      { goal: task, workingDir: projectRoot, constraints: {} },
+      adaptivePlanner,
+      buildPlannerInputs(task),
+      readDecompositionConfig(configManager),
+      runner,
+      { estimateCostUsd: makeCostEstimator(configManager) },
+    );
+  }
+
+  /**
+   * Derive the launchable CreateWorkstreamInput from the decomposition
+   * proposal (BIG-3 — the final stage of the WRFC→orchestration migration).
+   *
+   * THE BOUNDARY, stated honestly (and in the /workstream help + draft render):
+   *  - A genuinely MULTI-ITEM proposal (the planning agent decomposed the goal
+   *    into >1 work item) is assembled by the SDK's fromPlanProposal into the
+   *    REAL multi-item workstream: one engineer→review-phased item per proposal
+   *    item, inter-item dependencies preserved as scheduling constraints, and
+   *    workstream-level provenance carried. This is the plan the engine runs —
+   *    no flattening.
+   *  - A SINGLE-ITEM proposal (the heuristic single-item path, a gate-decline,
+   *    or an agent that honestly returned one item) keeps the fromChainSpec
+   *    COMPAT path: byte-for-byte the same engineer→review chain
+   *    WrfcController.createChain would start. A single item carries no
+   *    dependencies and no multi-item structure, so the proposal mapping would
+   *    add nothing — the compat path is the honest, unchanged choice.
+   *
+   * Earlier waves always took the compat path because no planning-agent-spawn
+   * pipeline existed to produce a real multi-item decomposition; BIG-2 landed
+   * that pipeline, so `result.proposal` can now be a real multi-item plan and
+   * this maps it faithfully. The rendered draft shows THIS spec, so the
+   * proposal preview and the launch are always the same plan.
+   */
+  function buildSpec(task: string, proposal: PlanProposal): CreateWorkstreamInput {
+    if (proposal.workItems.length > 1) {
+      return fromPlanProposal(proposal, configManager);
+    }
+    return fromChainSpec({ id: `item-${crypto.randomUUID().slice(0, 8)}`, task }, configManager);
+  }
+
+  return {
+    engine,
+    async proposeDraft(task: string, isolation?: WorkstreamIsolation): Promise<WorkstreamDraft> {
+      const result = await decompose(task);
+      const spec = buildSpec(task, result.proposal);
+      const draft: WorkstreamDraft = {
+        id: `wsd_${crypto.randomUUID().slice(0, 8)}`,
+        task,
+        spec: isolation ? { ...spec, isolation } : spec,
+        gate: result.gate,
+        proposal: result.proposal,
+        provenance: toProvenance(result),
+        approved: false,
+        createdAt: Date.now(),
+      };
+      drafts.set(draft.id, draft);
+      return draft;
+    },
+    getDraft: (id) => drafts.get(id),
+    listDrafts: () => Array.from(drafts.values()).sort((a, b) => a.createdAt - b.createdAt),
+    async editDraft(id, task, isolation) {
+      const draft = drafts.get(id);
+      if (!draft) return undefined;
+      const result = await decompose(task);
+      const nextIsolation = isolation ?? draft.spec.isolation;
+      draft.task = task;
+      draft.spec = { ...buildSpec(task, result.proposal), isolation: nextIsolation };
+      draft.proposal = result.proposal;
+      draft.provenance = toProvenance(result);
+      draft.approved = false;
+      return draft;
+    },
+    approveDraft(id) {
+      const draft = drafts.get(id);
+      if (!draft) return undefined;
+      draft.approved = true;
+      return draft;
+    },
+    removeDraft: (id) => drafts.delete(id),
+    launchDraft(id) {
+      const draft = drafts.get(id);
+      if (!draft || !draft.approved) return null;
+      const workstream = engine.createWorkstream(draft.spec);
+      engine.start(workstream.id);
+      drafts.delete(id);
+      return { workstreamId: workstream.id };
+    },
+  };
+}
+
+/**
+ * Constructs the TUI's OrchestrationEngine instance and its command-facing
+ * facade. `persist` and `createWorktree` are left at the engine's own
+ * defaults: journal-backed snapshots under .goodvibes/orchestration/ (so
+ * resumeAllFromDisk below has something to resume) and a plain
+ * AgentWorktree(projectRoot) for the (default) `shared`-isolation path.
+ * A draft's `isolation: 'worktree'` (see /workstream create --isolation
+ * worktree, input/commands/workstream-runtime.ts) opts a single workstream
+ * into the SDK's per-item git-worktree isolation (WorktreeIsolationManager,
+ * engine-side) instead — the engine, not this facade, owns that lifecycle.
+ */
+export function createWorkstreamServices(deps: WorkstreamServicesDeps): WorkstreamServices {
+  const orchestrationEngine = createOrchestrationEngine({
+    agentManager: deps.agentManager,
+    configManager: deps.configManager,
+    runtimeBus: deps.runtimeBus,
+    projectRoot: deps.projectRoot,
+    priceUsage: (model, usage) => {
+      const modelId = model ?? 'unknown';
+      if (!isModelPriced(modelId)) return null;
+      return calcSessionCost(usage.inputTokens, usage.outputTokens, usage.cacheReadTokens, usage.cacheWriteTokens, modelId);
+    },
+  });
+  // Honest resume: a prior process's still-in-flight workstreams pick back up
+  // (and reappear in the fleet tree) instead of silently vanishing on
+  // restart. Never throws — persistence.ts guards every read/parse and
+  // quarantines an unrecognized snapshot rather than propagating.
+  orchestrationEngine.resumeAllFromDisk();
+  const workstreamCommands = createWorkstreamCommandService(
+    orchestrationEngine,
+    deps.adaptivePlanner,
+    deps.configManager,
+    deps.agentManager,
+    deps.projectRoot,
+  );
+  return { orchestrationEngine, workstreamCommands };
+}

package/src/runtime/wrfc-persistence.ts

@@ -1,6 +1,8 @@
 /**
  * WRFC chain persistence — snapshot active chains to disk on every lifecycle
- * event so that a crash/restart can surface interrupted chains to the operator.
+ * event so that a crash/restart can surface interrupted chains to the operator,
+ * and so that terminal chains (passed/failed/cancelled) remain visible as
+ * bounded history rather than vanishing the moment they finish.
  *
  * Architecture
  * ─────────────
@@ -16,11 +18,27 @@
  *    row and can be resumed by the operator. The `interruptedChains` accessor
  *    additionally exposes the recovered set for inspection.
  *
- * 3. Snapshot lifecycle:
- *    - Terminal chains ('passed' | 'failed') are pruned from the snapshot
- *      after rehydration surfaces them.
- *    - A corrupt or version-mismatched snapshot is quarantined by renaming it
- *      to `<path>.unrecognized` — never a hard crash.
+ *    A chain that looked interrupted (non-terminal) in the old snapshot can be
+ *    reaped to terminal IN PLACE by `WrfcController.importChain` (Wave 6, wo-F:
+ *    no member agent survived the restart — see wrfc-controller.ts). This
+ *    module always re-checks `chain.state` AFTER the import call, never the
+ *    pre-import classification, so a reaped chain is treated as history, not
+ *    re-surfaced as interrupted and never re-imported again on a later restart.
+ *
+ * 3. Terminal-history retention (bounded, most-recently-completed first):
+ *    Previously, every terminal chain was pruned from the snapshot the moment
+ *    it was written or rehydrated — a killed/finished chain vanished from
+ *    wrfc-chains.json entirely, including across a restart, so nothing could
+ *    ever honestly report "last chain: <state>". Terminal chains are now
+ *    RETAINED, capped at MAX_TERMINAL_HISTORY (20) most-recently-completed,
+ *    both:
+ *      - across a live session, via an internal history cache that survives
+ *        even after WrfcController's own in-memory cleanup (60s after a
+ *        chain terminates) drops the chain from listChains(); and
+ *      - across a restart, via rehydrate() seeding that cache from whatever
+ *        was already terminal in the prior snapshot instead of discarding it.
+ *    A corrupt or version-mismatched snapshot is quarantined by renaming it
+ *    to `<path>.unrecognized` — never a hard crash.
  *
  * Snapshot path: `.goodvibes/tui/wrfc-chains.json`
  * Snapshot schema: `{ version: 1, writtenAt: number, chains: WrfcChain[] }`
@@ -37,6 +55,9 @@ import type { SystemMessageRouter } from '../core/system-message-router.ts';
 const SNAPSHOT_VERSION = 1;
 const DEBOUNCE_MS = 250;
 
+/** Bounded terminal-history retention: keep the most recent K chains, prune beyond. */
+const MAX_TERMINAL_HISTORY = 20;
+
 /** Terminal states — chains in these states will not be surfaced as interrupted. */
 const TERMINAL_STATES = new Set<WrfcState>(['passed', 'failed']);
 
@@ -45,6 +66,13 @@ function isNonTerminal(state: WrfcState): boolean {
   return !TERMINAL_STATES.has(state);
 }
 
+/** Sort by most-recently-completed first (falls back to createdAt for chains missing completedAt) and keep only the first `limit`. */
+function takeMostRecentTerminal(chains: readonly WrfcChain[], limit: number): WrfcChain[] {
+  return [...chains]
+    .sort((a, b) => (b.completedAt ?? b.createdAt ?? 0) - (a.completedAt ?? a.createdAt ?? 0))
+    .slice(0, limit);
+}
+
 // ─── Snapshot schema ─────────────────────────────────────────────────────────
 
 interface WrfcSnapshot {
@@ -90,9 +118,19 @@ export interface WrfcPersistence {
    */
   attach(runtimeBus: RuntimeEventBus): Array<() => void>;
 
+  /**
+   * All chains known after rehydrate(): the (re-checked, post-reap) interrupted
+   * set plus the bounded terminal-history cache seeded from the prior snapshot.
+   * Empty until rehydrate() is called. Consumers building a post-restart
+   * summary (e.g. the boot resume notice) read this instead of re-parsing the
+   * snapshot file themselves.
+   */
+  readonly knownChains: readonly WrfcChain[];
+
   /**
    * Read the snapshot from a previous process, surface any interrupted chains
-   * as system messages, and prune terminal chains from the snapshot on disk.
+   * as system messages, and retain terminal chains (bounded, most-recently-
+   * completed first) as on-disk history instead of pruning them.
    *
    * Must be called after the SystemMessageRouter is available.
    */
@@ -111,6 +149,14 @@ class WrfcPersistenceImpl implements WrfcPersistence {
 
   private _interruptedChains: WrfcChain[] = [];
   private _debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  /**
+   * Bounded terminal-history cache (most-recently-completed first once
+   * trimmed). Survives past WrfcController's own in-memory cleanup of
+   * terminated chains (60s after termination — see wrfc-controller.ts
+   * scheduleChainCleanup) so a chain that ages out of listChains() is not
+   * silently dropped from the persisted snapshot.
+   */
+  private _terminalHistory: WrfcChain[] = [];
 
   constructor(options: WrfcPersistenceOptions) {
     this.snapshotPath = options.snapshotPath;
@@ -122,6 +168,10 @@ class WrfcPersistenceImpl implements WrfcPersistence {
     return this._interruptedChains;
   }
 
+  get knownChains(): readonly WrfcChain[] {
+    return [...this._interruptedChains, ...this._terminalHistory];
+  }
+
   attach(runtimeBus: RuntimeEventBus): Array<() => void> {
     const schedule = (): void => this._scheduleSnapshot();
 
@@ -144,17 +194,40 @@ class WrfcPersistenceImpl implements WrfcPersistence {
     const snapshot = this._readSnapshot();
     if (!snapshot) return;
 
-    const interrupted = snapshot.chains.filter((c) => isNonTerminal(c.state));
-    this._interruptedChains = interrupted;
+    // Seed the bounded terminal-history cache from whatever was already
+    // terminal in the prior process's snapshot, so it survives this restart
+    // instead of being wiped (the old behaviour pruned every terminal chain
+    // unconditionally on every rehydrate).
+    const alreadyTerminal = snapshot.chains.filter((c) => !isNonTerminal(c.state));
+    this._terminalHistory = takeMostRecentTerminal(alreadyTerminal, MAX_TERMINAL_HISTORY);
 
-    const router = this.getSystemMessageRouter();
-    for (const chain of interrupted) {
+    const candidateInterrupted = snapshot.chains.filter((c) => isNonTerminal(c.state));
+    for (const chain of candidateInterrupted) {
       // Re-import so the chain reappears in the controller's in-memory map and
       // becomes selectable/resumable from the panel. On a fresh process start
       // the map is empty, so importChain (force=false) never clobbers a live
       // chain. The accessor is optional for read-only test doubles.
+      //
+      // NOTE: importChain may reap this chain to a terminal state IN PLACE
+      // (Wave 6, wo-F zombie-reap: no member agent survived the restart) —
+      // always read chain.state AFTER this call below, never the pre-import
+      // classification captured by candidateInterrupted.
       this.controller.importChain?.(chain);
+    }
+
+    // Re-partition after the reap check: a chain that looked interrupted
+    // before import may now be terminal. Only genuinely still-live chains are
+    // surfaced to the operator as interrupted; anything reaped just now joins
+    // history instead — it is done, not a resurrection candidate, and must
+    // never be handed to importChain again on a future restart (a chain only
+    // ever lands in candidateInterrupted while its persisted state is
+    // non-terminal; once it's history its state is terminal for good).
+    this._interruptedChains = candidateInterrupted.filter((c) => isNonTerminal(c.state));
+    const reapedJustNow = candidateInterrupted.filter((c) => !isNonTerminal(c.state));
+    for (const chain of reapedJustNow) this._upsertHistoryChain(chain);
 
+    const router = this.getSystemMessageRouter();
+    for (const chain of this._interruptedChains) {
       const msg =
         `[WRFC] Chain ${chain.id.slice(0, 12)} (${chain.task.slice(0, 60).trim()}) ` +
         `was interrupted by a restart — state was '${chain.state}' ` +
@@ -162,14 +235,19 @@ class WrfcPersistenceImpl implements WrfcPersistence {
       router?.wrfc(msg, 'high');
     }
 
-    // Prune terminal chains from the on-disk snapshot after surfacing.
-    if (snapshot.chains.length !== interrupted.length) {
-      const pruned: WrfcSnapshot = {
+    // Rewrite the snapshot only when something actually changed: a chain was
+    // reaped just now, or the history cap pruned an entry that was on disk.
+    // Terminal chains are RETAINED (bounded to MAX_TERMINAL_HISTORY, most
+    // recently completed first) instead of erased — post-restart surfaces
+    // (fleet, the resume notice, /wrfc history) need this to honestly report
+    // e.g. "last chain: cancelled".
+    if (reapedJustNow.length > 0 || alreadyTerminal.length !== this._terminalHistory.length) {
+      const rebuilt: WrfcSnapshot = {
         version: SNAPSHOT_VERSION,
         writtenAt: Date.now(),
-        chains: interrupted,
+        chains: [...this._interruptedChains, ...this._terminalHistory],
       };
-      this._writeSnapshot(pruned);
+      this._writeSnapshot(rebuilt);
     }
   }
 
@@ -194,14 +272,43 @@ class WrfcPersistenceImpl implements WrfcPersistence {
   }
 
   private _writeCurrentSnapshot(): void {
+    const live = this.controller.listChains();
+    this._recordTerminalHistory(live);
     const snapshot: WrfcSnapshot = {
       version: SNAPSHOT_VERSION,
       writtenAt: Date.now(),
-      chains: this.controller.listChains(),
+      chains: this._mergeWithHistory(live),
     };
     this._writeSnapshot(snapshot);
   }
 
+  /** Fold any terminal chains in a live listing into the bounded history cache, so they are not lost once WrfcController's own in-memory cleanup drops them from listChains(). */
+  private _recordTerminalHistory(chains: readonly WrfcChain[]): void {
+    for (const chain of chains) {
+      if (!isNonTerminal(chain.state)) this._upsertHistoryChain(chain);
+    }
+  }
+
+  /** Insert/replace `chain` in the terminal-history cache (by id), then trim to MAX_TERMINAL_HISTORY, most-recently-completed first. */
+  private _upsertHistoryChain(chain: WrfcChain): void {
+    const next = this._terminalHistory.filter((c) => c.id !== chain.id);
+    next.push(chain);
+    this._terminalHistory = takeMostRecentTerminal(next, MAX_TERMINAL_HISTORY);
+  }
+
+  /**
+   * Combine the live chains the controller is currently tracking with any
+   * historical terminal chains the live map has already forgotten (e.g. after
+   * WrfcController's own 60s in-memory cleanup) — so the persisted file never
+   * loses a terminal chain just because the live map stopped carrying it.
+   * Live entries win on id collision since they are always the freshest copy.
+   */
+  private _mergeWithHistory(live: readonly WrfcChain[]): WrfcChain[] {
+    const liveIds = new Set(live.map((c) => c.id));
+    const historyOnly = this._terminalHistory.filter((c) => !liveIds.has(c.id));
+    return [...live, ...historyOnly];
+  }
+
   private _writeSnapshot(snapshot: WrfcSnapshot): void {
     try {
       atomicWriteFileSync(this.snapshotPath, JSON.stringify(snapshot), { mkdirp: true });