@pellux/goodvibes-tui 0.20.3 → 0.22.0

package/src/runtime/onboarding/state.ts

@@ -1,5 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, statSync, unlinkSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { atomicWriteFileSync } from '@/config/atomic-write.ts';
+import { readVersioned } from '@/config/read-versioned.ts';
+
 import type {
   OnboardingAcknowledgementRuntimeState,
   OnboardingAcknowledgementTarget,
@@ -10,6 +13,24 @@ import type {
 
 const ONBOARDING_RUNTIME_STATE_FILE = 'onboarding-state.json';
 
+/**
+ * Lockfile serialisation for writeOnboardingAcknowledgementState.
+ *
+ * Mechanism: O_EXCL advisory lockfile in the same directory as the state file.
+ * This is the simplest correct approach for two same-host processes (daemon
+ * + TUI) that both run this read-modify-write path:
+ *
+ *   - Acquire: open(<statefile>.lock, O_CREAT|O_EXCL|O_WRONLY) — atomic on POSIX.
+ *   - Stale detection: if the lockfile mtime is >= LOCK_STALE_MS old, force-remove.
+ *   - Retry: up to LOCK_MAX_RETRIES rapid non-blocking attempts (no sleep — main-thread safe).
+ *   - Release: unlink the lockfile (best-effort on failure).
+ *
+ * O_EXCL was chosen over flock(2) because it works on all POSIX targets
+ * without requiring an open fd on the guarded file, and is Bun-compatible.
+ */
+const LOCK_MAX_RETRIES = 10;
+const LOCK_STALE_MS = 5_000;
+
 export interface OnboardingRuntimeStateRecord {
   readonly scope: OnboardingStateScope;
   readonly path: string;
@@ -37,30 +58,67 @@ function resolveStatePath(
     : shellPaths.resolveUserPath('tui', ONBOARDING_RUNTIME_STATE_FILE);
 }
 
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
+function isAcknowledgementTarget(value: string): value is OnboardingAcknowledgementTarget {
+  return value === 'providers' || value === 'subscriptions' || value === 'auth';
 }
 
-function isOnboardingMode(value: unknown): value is OnboardingAcknowledgementRuntimeState['mode'] {
-  return value === 'new' || value === 'edit' || value === 'reopen';
+function isRuntimeStatePayload(value: unknown): value is OnboardingAcknowledgementRuntimeState {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  if (v['version'] !== 1) return false;
+  if (typeof v['updatedAt'] !== 'number' || !Number.isFinite(v['updatedAt'] as number)) return false;
+  if (typeof v['source'] !== 'string') return false;
+  const mode = v['mode'];
+  if (mode !== undefined && mode !== 'new' && mode !== 'edit' && mode !== 'reopen') return false;
+  if (v['workspaceRoot'] !== undefined && typeof v['workspaceRoot'] !== 'string') return false;
+  if (typeof v['acknowledgements'] !== 'object' || v['acknowledgements'] === null) return false;
+
+  return Object.entries(v['acknowledgements'] as Record<string, unknown>).every(
+    ([key, entry]) => isAcknowledgementTarget(key) && typeof entry === 'boolean',
+  );
 }
 
-function isAcknowledgementTarget(value: string): value is OnboardingAcknowledgementTarget {
-  return value === 'providers' || value === 'subscriptions' || value === 'auth';
+// ─── Lock helpers ──────────────────────────────────────────────────────────────────
+
+function stateLockPath(statePath: string): string {
+  return `${statePath}.lock`;
 }
 
-function isRuntimeStatePayload(value: unknown): value is OnboardingAcknowledgementRuntimeState {
-  if (!isObject(value)) return false;
-  if (value.version !== 1) return false;
-  if (typeof value.updatedAt !== 'number' || !Number.isFinite(value.updatedAt)) return false;
-  if (typeof value.source !== 'string') return false;
-  if (value.mode !== undefined && !isOnboardingMode(value.mode)) return false;
-  if (value.workspaceRoot !== undefined && typeof value.workspaceRoot !== 'string') return false;
-  if (!isObject(value.acknowledgements)) return false;
-
-  return Object.entries(value.acknowledgements).every(([key, entry]) => isAcknowledgementTarget(key) && typeof entry === 'boolean');
+/**
+ * Attempt to acquire an O_EXCL advisory lock. Returns true if acquired.
+ * Stale locks (older than LOCK_STALE_MS) are forcibly removed before retry.
+ *
+ * Retries are non-blocking (no sleep between attempts) so this function is
+ * safe to call on the main thread. Each O_EXCL open is a single syscall;
+ * 10 rapid retries add negligible latency and are safe for a one-shot path.
+ */
+function acquireLock(lp: string): boolean {
+  for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
+    // Stale-lock takeover: if the lockfile is old enough, forcibly remove it.
+    try {
+      const st = statSync(lp);
+      if (Date.now() - st.mtimeMs >= LOCK_STALE_MS) {
+        try { unlinkSync(lp); } catch { /* another process may have beaten us */ }
+      }
+    } catch { /* lockfile does not exist — expected happy path */ }
+
+    try {
+      // 'wx' ≡ O_CREAT | O_EXCL | O_WRONLY — fails atomically if file exists.
+      const fd = openSync(lp, 'wx');
+      closeSync(fd);
+      return true;
+    } catch { /* file exists, held by another process */ }
+  }
+  return false;
+}
+
+/** Release the advisory lockfile (best-effort). */
+function releaseLock(lp: string): void {
+  try { unlinkSync(lp); } catch { /* best-effort */ }
 }
 
+// ─── Public API ────────────────────────────────────────────────────────────────────
+
 export function getOnboardingRuntimeStatePath(
   shellPaths: OnboardingShellPaths,
   scope: OnboardingStateScope = 'project',
@@ -73,42 +131,39 @@ export function readOnboardingRuntimeState(
   scope: OnboardingStateScope = 'project',
 ): OnboardingRuntimeStateRecord {
   const path = resolveStatePath(shellPaths, scope);
-  if (!existsSync(path)) {
+
+  const parsed = readVersioned<OnboardingAcknowledgementRuntimeState & { version: number }>(
+    path,
+    { currentVersion: 1, onUnknown: 'quarantine' },
+  );
+
+  if (parsed === null) {
+    // readVersioned returns null for: missing file, corrupt JSON, or
+    // unrecognised version (in which case it renames to <path>.unrecognized).
+    const nowExists = existsSync(path);
+    const quarantined = existsSync(`${path}.unrecognized`);
     return {
       scope,
       path,
-      exists: false,
+      exists: nowExists || quarantined,
       payload: null,
+      ...(quarantined
+        ? { parseError: 'Unrecognised or corrupt onboarding state file; quarantined.' }
+        : {}),
     };
   }
 
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
-    if (!isRuntimeStatePayload(parsed)) {
-      return {
-        scope,
-        path,
-        exists: true,
-        payload: null,
-        parseError: 'Invalid onboarding runtime state payload.',
-      };
-    }
-
-    return {
-      scope,
-      path,
-      exists: true,
-      payload: parsed,
-    };
-  } catch (error) {
+  if (!isRuntimeStatePayload(parsed)) {
     return {
       scope,
       path,
       exists: true,
       payload: null,
-      parseError: error instanceof Error ? error.message : String(error),
+      parseError: 'Invalid onboarding runtime state payload.',
     };
   }
+
+  return { scope, path, exists: true, payload: parsed };
 }
 
 export function writeOnboardingAcknowledgementState(
@@ -117,24 +172,47 @@ export function writeOnboardingAcknowledgementState(
 ): OnboardingRuntimeStateRecord {
   const scope = options.scope ?? 'project';
   const path = resolveStatePath(shellPaths, scope);
-  const existing = readOnboardingRuntimeState(shellPaths, scope);
-  const updatedAt = options.updatedAt ?? Date.now();
-  const payload: OnboardingAcknowledgementRuntimeState = {
-    version: 1,
-    updatedAt,
-    source: options.source,
-    ...(options.mode ? { mode: options.mode } : {}),
-    ...(options.workspaceRoot ?? shellPaths.workingDirectory
-      ? { workspaceRoot: options.workspaceRoot ?? shellPaths.workingDirectory }
-      : {}),
-    acknowledgements: {
-      ...(existing.payload?.acknowledgements ?? {}),
-      [options.target]: options.acknowledged,
-    },
-  };
+  const lp = stateLockPath(path);
 
+  // Ensure the parent directory exists before we try to create the lockfile.
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+
+  const acquired = acquireLock(lp);
+  if (!acquired) {
+    // Lock exhaustion: another process has held the lock for all LOCK_MAX_RETRIES
+    // attempts. Proceeding without the lock — the atomic write (rename) prevents
+    // torn files, but under true concurrent contention a concurrent read-modify-write
+    // may result in a lost-update (last writer wins). Surfaced here so it is
+    // detectable in logs rather than silently discarded.
+    console.warn(
+      '[goodvibes] onboarding-state: lock exhausted, proceeding without lock.',
+      { path, target: options.target, source: options.source },
+    );
+  }
+
+  try {
+    // Re-read (inside the lock when acquired; best-effort when degraded) to get
+    // the freshest acknowledgements state, eliminating the read-modify-write
+    // race between daemon and TUI under normal conditions.
+    const existing = readOnboardingRuntimeState(shellPaths, scope);
+    const updatedAt = options.updatedAt ?? Date.now();
+    const ws = options.workspaceRoot ?? shellPaths.workingDirectory;
+    const payload: OnboardingAcknowledgementRuntimeState = {
+      version: 1,
+      updatedAt,
+      source: options.source,
+      ...(options.mode ? { mode: options.mode } : {}),
+      ...(ws ? { workspaceRoot: ws } : {}),
+      acknowledgements: {
+        ...(existing.payload?.acknowledgements ?? {}),
+        [options.target]: options.acknowledged,
+      },
+    };
+
+    atomicWriteFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, { mkdirp: true });
+  } finally {
+    if (acquired) releaseLock(lp);
+  }
 
   return readOnboardingRuntimeState(shellPaths, scope);
 }

package/src/runtime/onboarding/types.ts

@@ -340,6 +340,26 @@ export interface OnboardingCheckMarkersState {
   readonly effective: OnboardingCheckMarkerState | null;
 }
 
+export interface WizardProgressPayload {
+  readonly version: 1;
+  readonly savedAt: number;
+  readonly mode: OnboardingMode;
+  readonly stepIndex: number;
+  /** Serialised Map<fieldId, boolean> entries */
+  readonly toggleState: ReadonlyArray<readonly [string, boolean]>;
+  /** Serialised Map<fieldId, string> entries */
+  readonly radioState: ReadonlyArray<readonly [string, string]>;
+  /** Serialised Map<fieldId, string> entries */
+  readonly textState: ReadonlyArray<readonly [string, string]>;
+}
+
+export interface WizardProgressState {
+  readonly path: string;
+  readonly exists: boolean;
+  readonly payload: WizardProgressPayload | null;
+  readonly parseError?: string;
+}
+
 export interface WriteOnboardingCheckMarkerOptions {
   readonly scope?: OnboardingStateScope;
   readonly checkedAt?: number;

package/src/runtime/services.ts

@@ -11,6 +11,7 @@ import { WatcherRegistry } from '@pellux/goodvibes-sdk/platform/watchers';
 import { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
 import {
   HomeGraphService,
+  GOODVIBES_AGENT_KNOWLEDGE_DB_FILE,
   HOME_GRAPH_KNOWLEDGE_EXTENSION,
   KnowledgeService,
   KnowledgeSemanticService,
@@ -77,6 +78,7 @@ import { ComponentHealthMonitor } from '@/runtime/index.ts';
 import { WorktreeRegistry } from '@/runtime/index.ts';
 import { SandboxSessionRegistry } from '@/runtime/index.ts';
 import { createShellPathService, type ShellPathService } from '@/runtime/index.ts';
+import { isFeatureFlagEnabled } from './surface-feature-flags.ts';
 import type { FeatureFlagManager } from '@/runtime/index.ts';
 import { createFeatureFlagManager } from '@/runtime/index.ts';
 import { PolicyRuntimeState } from '@/runtime/index.ts';
@@ -169,6 +171,7 @@ export interface RuntimeServices {
   readonly gatewayMethods: GatewayMethodCatalog;
   readonly artifactStore: ArtifactStore;
   readonly knowledgeService: KnowledgeService;
+  readonly agentKnowledgeService: KnowledgeService;
   readonly homeGraphService: HomeGraphService;
   readonly projectPlanningService: ProjectPlanningService;
   readonly projectPlanningProjectId: string;
@@ -419,6 +422,10 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     configManager,
     dbFileName: REGULAR_KNOWLEDGE_DB_FILE,
   });
+  const agentKnowledgeStore = new KnowledgeStore({
+    configManager,
+    dbFileName: GOODVIBES_AGENT_KNOWLEDGE_DB_FILE,
+  });
   const homeGraphKnowledgeStore = new KnowledgeStore({
     configManager,
     dbFileName: HOME_GRAPH_KNOWLEDGE_DB_FILE,
@@ -436,12 +443,22 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     maxLlmSourcesPerReindex: 3,
     objectProfiles: HOME_GRAPH_KNOWLEDGE_EXTENSION.objectProfiles,
   });
+  const agentKnowledgeSemanticService = new KnowledgeSemanticService(agentKnowledgeStore, {
+    llm: knowledgeSemanticLlm,
+    maxLlmSourcesPerReindex: 3,
+  });
   const knowledgeService = new KnowledgeService(knowledgeStore, artifactStore, undefined, {
     memoryRegistry,
     runtimeBus: options.runtimeBus,
     semanticService: knowledgeSemanticService,
   });
   knowledgeService.attachRuntimeBus(options.runtimeBus);
+  const agentKnowledgeService = new KnowledgeService(agentKnowledgeStore, artifactStore, undefined, {
+    memoryRegistry,
+    runtimeBus: options.runtimeBus,
+    semanticService: agentKnowledgeSemanticService,
+  });
+  agentKnowledgeService.attachRuntimeBus(options.runtimeBus);
   const homeGraphService = new HomeGraphService(homeGraphKnowledgeStore, artifactStore, {
     semanticService: homeGraphSemanticService,
   });
@@ -469,6 +486,10 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     searchService: webSearchService,
     ingestService: knowledgeService,
   }));
+  agentKnowledgeSemanticService.setGapRepairer(createWebKnowledgeGapRepairer({
+    searchService: webSearchService,
+    ingestService: agentKnowledgeService,
+  }));
   homeGraphSemanticService.setGapRepairer(createWebKnowledgeGapRepairer({
     searchService: webSearchService,
     ingestService: homeGraphService,
@@ -510,7 +531,11 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   const worktreeRegistry = new WorktreeRegistry(workingDirectory);
   const webhookNotifier = new WebhookNotifier();
   const replayEngine = new DeterministicReplayEngine(workingDirectory);
-  const providerOptimizer = new ProviderOptimizer(providerRegistry, providerCapabilityRegistry, false);
+  const providerOptimizer = new ProviderOptimizer(
+    providerRegistry,
+    providerCapabilityRegistry,
+    isFeatureFlagEnabled(configManager, 'provider-optimizer'),
+  );
   const sessionMemoryStore = new SessionMemoryStore();
   const sessionLineageTracker = new SessionLineageTracker();
   const sessionChangeTracker = new SessionChangeTracker();
@@ -600,6 +625,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     gatewayMethods,
     artifactStore,
     knowledgeService,
+    agentKnowledgeService,
     homeGraphService,
     projectPlanningService,
     projectPlanningProjectId,

package/src/runtime/wrfc-persistence.ts

@@ -0,0 +1,237 @@
+/**
+ * WRFC chain persistence — snapshot active chains to disk on every lifecycle
+ * event so that a crash/restart can surface interrupted chains to the operator.
+ *
+ * Architecture
+ * ─────────────
+ * 1. `createWrfcPersistence` subscribes to all 7 WORKFLOW_* events on the
+ *    runtimeBus. Each event schedules a trailing-debounced snapshot (250 ms)
+ *    so event bursts from a single state transition don't thrash disk.
+ *
+ * 2. `WrfcPersistence.rehydrate(router)` is called once on boot (after the
+ *    SystemMessageRouter is available). It reads the snapshot, identifies
+ *    chains that were in a non-terminal state at last write, and emits a
+ *    high-priority 'wrfc' system message per interrupted chain. The
+ *    `interruptedChains` accessor makes the data available for panel reads
+ *    without coupling this module to wrfc-panel.ts.
+ *
+ * 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.
+ *
+ * Snapshot path: `.goodvibes/tui/wrfc-chains.json`
+ * Snapshot schema: `{ version: 1, writtenAt: number, chains: WrfcChain[] }`
+ */
+
+import type { WrfcChain, WrfcState } from '@pellux/goodvibes-sdk/platform/agents';
+import type { RuntimeEventBus, WorkflowEvent } from '@/runtime/index.ts';
+import { atomicWriteFileSync } from '../config/atomic-write.ts';
+import { readVersioned } from '../config/read-versioned.ts';
+import type { SystemMessageRouter } from '../core/system-message-router.ts';
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const SNAPSHOT_VERSION = 1;
+const DEBOUNCE_MS = 250;
+
+/** Terminal states — chains in these states will not be surfaced as interrupted. */
+const TERMINAL_STATES = new Set<WrfcState>(['passed', 'failed']);
+
+/** Non-terminal (interruptible) states. */
+function isNonTerminal(state: WrfcState): boolean {
+  return !TERMINAL_STATES.has(state);
+}
+
+// ─── Snapshot schema ─────────────────────────────────────────────────────────
+
+interface WrfcSnapshot {
+  readonly version: number;
+  readonly writtenAt: number;
+  readonly chains: WrfcChain[];
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/** Subset of WrfcController needed by this module. */
+export interface WrfcControllerReader {
+  listChains(): WrfcChain[];
+}
+
+export interface WrfcPersistenceOptions {
+  /** Absolute path to the snapshot file, e.g. `.goodvibes/tui/wrfc-chains.json`. */
+  readonly snapshotPath: string;
+  /** Factory for the current SystemMessageRouter — may return null before it is wired. */
+  readonly getSystemMessageRouter: () => SystemMessageRouter | null;
+  /** WrfcController reader — only listChains() is needed. */
+  readonly controller: WrfcControllerReader;
+}
+
+export interface WrfcPersistence {
+  /**
+   * Chains from the previous process that were in a non-terminal state.
+   * Populated only after `rehydrate()` is called.
+   */
+  readonly interruptedChains: readonly WrfcChain[];
+
+  /**
+   * Subscribe to runtimeBus workflow events and start persisting snapshots.
+   * Returns an array of unsubscribe functions to be added to `runtimeUnsubs`.
+   */
+  attach(runtimeBus: RuntimeEventBus): Array<() => void>;
+
+  /**
+   * Read the snapshot from a previous process, surface any interrupted chains
+   * as system messages, and prune terminal chains from the snapshot on disk.
+   *
+   * Must be called after the SystemMessageRouter is available.
+   */
+  rehydrate(): void;
+
+  /** Flush any pending debounced snapshot immediately (used in tests). */
+  flush(): void;
+}
+
+// ─── Implementation ──────────────────────────────────────────────────────────
+
+class WrfcPersistenceImpl implements WrfcPersistence {
+  private readonly snapshotPath: string;
+  private readonly getSystemMessageRouter: () => SystemMessageRouter | null;
+  private readonly controller: WrfcControllerReader;
+
+  private _interruptedChains: WrfcChain[] = [];
+  private _debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(options: WrfcPersistenceOptions) {
+    this.snapshotPath = options.snapshotPath;
+    this.getSystemMessageRouter = options.getSystemMessageRouter;
+    this.controller = options.controller;
+  }
+
+  get interruptedChains(): readonly WrfcChain[] {
+    return this._interruptedChains;
+  }
+
+  attach(runtimeBus: RuntimeEventBus): Array<() => void> {
+    const schedule = (): void => this._scheduleSnapshot();
+
+    const events: WorkflowEvent['type'][] = [
+      'WORKFLOW_CHAIN_CREATED',
+      'WORKFLOW_STATE_CHANGED',
+      'WORKFLOW_REVIEW_COMPLETED',
+      'WORKFLOW_FIX_ATTEMPTED',
+      'WORKFLOW_GATE_RESULT',
+      'WORKFLOW_CHAIN_PASSED',
+      'WORKFLOW_CHAIN_FAILED',
+    ];
+
+    return events.map((eventType) =>
+      runtimeBus.on<Extract<WorkflowEvent, { type: typeof eventType }>>(eventType, schedule),
+    );
+  }
+
+  rehydrate(): void {
+    const snapshot = this._readSnapshot();
+    if (!snapshot) return;
+
+    const interrupted = snapshot.chains.filter((c) => isNonTerminal(c.state));
+    this._interruptedChains = interrupted;
+
+    const router = this.getSystemMessageRouter();
+    for (const chain of interrupted) {
+      const msg =
+        `[WRFC] Chain ${chain.id.slice(0, 12)} (${chain.task.slice(0, 60).trim()}) ` +
+        `was interrupted by a restart — state was '${chain.state}' ` +
+        `after ${chain.reviewCycles} review cycle${chain.reviewCycles !== 1 ? 's' : ''}`;
+      router?.wrfc(msg, 'high');
+    }
+
+    // Prune terminal chains from the on-disk snapshot after surfacing.
+    if (snapshot.chains.length !== interrupted.length) {
+      const pruned: WrfcSnapshot = {
+        version: SNAPSHOT_VERSION,
+        writtenAt: Date.now(),
+        chains: interrupted,
+      };
+      this._writeSnapshot(pruned);
+    }
+  }
+
+  flush(): void {
+    if (this._debounceTimer !== null) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+    this._writeCurrentSnapshot();
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  private _scheduleSnapshot(): void {
+    if (this._debounceTimer !== null) {
+      clearTimeout(this._debounceTimer);
+    }
+    this._debounceTimer = setTimeout(() => {
+      this._debounceTimer = null;
+      this._writeCurrentSnapshot();
+    }, DEBOUNCE_MS);
+  }
+
+  private _writeCurrentSnapshot(): void {
+    const snapshot: WrfcSnapshot = {
+      version: SNAPSHOT_VERSION,
+      writtenAt: Date.now(),
+      chains: this.controller.listChains(),
+    };
+    this._writeSnapshot(snapshot);
+  }
+
+  private _writeSnapshot(snapshot: WrfcSnapshot): void {
+    try {
+      atomicWriteFileSync(this.snapshotPath, JSON.stringify(snapshot), { mkdirp: true });
+    } catch {
+      // Best-effort — never crash the TUI over a persistence failure.
+    }
+  }
+
+  private _readSnapshot(): WrfcSnapshot | null {
+    // readVersioned handles: missing file → null, corrupt JSON → quarantine to
+    // .unrecognized, future/unrecognised version → quarantine, stepwise migration.
+    const raw = readVersioned<WrfcSnapshot & { version: number }>(
+      this.snapshotPath,
+      {
+        currentVersion: SNAPSHOT_VERSION,
+        // v0 → v1: pass through the data as-is (safety net only).
+        // NOTE: readVersioned does NOT coerce missing/non-numeric version fields to 0.
+        // Files without a version field are quarantined immediately. This migration
+        // only fires for files that explicitly contain `version: 0`.
+        migrations: {
+          0: (d) => ({ ...d, version: 1 }),
+        },
+        onUnknown: 'quarantine',
+      },
+    );
+    if (!raw) return null;
+
+    // Narrow the application-level fields that readVersioned does not validate.
+    if (typeof raw['writtenAt'] !== 'number' || !Array.isArray(raw['chains'])) {
+      return null;
+    }
+
+    return raw as WrfcSnapshot;
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create a WrfcPersistence instance.
+ *
+ * Call `persistence.attach(runtimeBus)` and push the returned unsubs into
+ * `runtimeUnsubs`. Call `persistence.rehydrate()` once the SystemMessageRouter
+ * is available.
+ */
+export function createWrfcPersistence(options: WrfcPersistenceOptions): WrfcPersistence {
+  return new WrfcPersistenceImpl(options);
+}

package/src/shell/blocking-input.ts

@@ -17,6 +17,15 @@ export type BlockingInputHandlerOptions = {
   render: () => void;
   loadRecoveryConversation: () => SessionSnapshot | null;
   deleteRecoveryFile: () => void;
+  /**
+   * Optional callback invoked after Ctrl+R restore to reopen panels captured in
+   * the recovery snapshot's returnContext. When provided (as wired in main.ts),
+   * the callback iterates snapshot.returnContext.openPanels and calls
+   * panelManager.open() for each entry, then panelManager.show() + render() to
+   * restore the panel posture from the recovered session. When omitted, panel
+   * posture is not restored.
+   */
+  reopenPanels?: (snapshot: SessionSnapshot) => void;
 };
 
 export type BlockingInputHandlerResult = {
@@ -38,6 +47,7 @@ export function handleBlockingShellInput(
     render,
     loadRecoveryConversation,
     deleteRecoveryFile,
+    reopenPanels,
   } = options;
 
   if (pendingPermission) {
@@ -71,12 +81,17 @@ export function handleBlockingShellInput(
     if (data === '\x12') {
       const recovery = loadRecoveryConversation();
       if (recovery) {
-        conversation.fromJSON({ messages: recovery.messages as Parameters<typeof conversation.fromJSON>[0]['messages'] });
+        conversation.fromJSON({
+          messages: recovery.messages as Parameters<typeof conversation.fromJSON>[0]['messages'],
+          title: recovery.title,
+          titleSource: recovery.titleSource,
+        });
+        reopenPanels?.(recovery);
         systemMessageRouter.high('[Recovery] Session restored.');
+        deleteRecoveryFile();
       } else {
         systemMessageRouter.high('[Recovery] Failed to restore saved data.');
       }
-      deleteRecoveryFile();
       render();
       return { handled: true, pendingPermission: null, recoveryPending: false };
     }
@@ -88,10 +103,10 @@ export function handleBlockingShellInput(
       return { handled: true, pendingPermission: null, recoveryPending: false };
     }
 
-    systemMessageRouter.high('[Recovery] Ignored saved session; starting a new prompt.');
-    deleteRecoveryFile();
+    // Stray key: leave the recovery prompt active so the user can still Ctrl+R or Esc.
+    systemMessageRouter.high('[Recovery] Ctrl+R to restore · Esc to discard');
     render();
-    return { handled: false, pendingPermission: null, recoveryPending: false };
+    return { handled: false, pendingPermission, recoveryPending: true };
   }
 
   return { handled: false, pendingPermission, recoveryPending };