@pellux/goodvibes-tui 1.19.6 → 1.20.1

package/src/runtime/bootstrap.ts

@@ -25,11 +25,12 @@ import type { Compositor } from '../renderer/compositor.ts';
 import type { RuntimeContext, BootstrapOptions } from './context.ts';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
 import {
-  shutdownRuntime, fireSessionStart, saveSession, createTaskManager, OpsControlPlane, AcpTaskAdapter,
-  emitSessionReady, emitSessionStarted, loadLastConversation, writeLastSessionPointer,
+  shutdownRuntime, fireSessionStart, createTaskManager, OpsControlPlane, AcpTaskAdapter,
+  emitSessionReady, emitSessionStarted, loadLastConversation,
   scheduleBackgroundMcpDiscovery, startBackgroundProviderRegistration, restoreSavedModel, startExternalServices,
   type ExternalServicesHandle, type HostServiceStatus, createHttpTransport, createDeferredStartupCoordinator,
 } from '@/runtime/index.ts';
+import { bindWriteLastSessionPointerToSurface } from './session-pointer-surface.ts';
 import { foldLegacySpineStore, deriveSpineFooterStatus } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
 import { createTuiSpineTransport, type SpineSessionsClient } from './session-spine-transport.ts';
 import { syncMemorySpineToHostStatus, type MemorySpineActiveRef } from './memory-spine-transport.ts';
@@ -103,8 +104,6 @@ export type BootstrapContext = RuntimeContext & {
   loadLastConversation: () => { messages: Array<Record<string, unknown>> } | null;
   /** Write the last-session pointer file (used after session resume). */
   _writeLastSessionPointer: (sessionId: string) => void;
-  /** Save a conversation snapshot to disk. */
-  _saveSession: typeof saveSession;
   /** Retrieve pinned model IDs for the model picker. */
   _getPinned: () => Promise<string[]>;
   /** Retrieve configured provider IDs for the model picker. */
@@ -272,6 +271,12 @@ export async function bootstrapRuntime(
     ? new OpsControlPlane(opsTaskManager, runtimeBus, store, userSessionId)
     : undefined;
 
+  // One surface-bound pointer writer, shared by the resume seam below and the
+  // context's `_writeLastSessionPointer`. Both slots want a one-argument
+  // function; handing them the SDK's two-argument export directly is what
+  // silently stopped the pointer from ever being written (see
+  // session-pointer-surface.ts).
+  const writeSessionPointer = bindWriteLastSessionPointerToSurface(services.surface);
   const shell = createBootstrapShell({
     configManager,
     runtimeBus,
@@ -286,7 +291,7 @@ export async function bootstrapRuntime(
     onSessionIdChanged: (sessionId) => {
       runtimeSessionIdRef.value = sessionId;
     },
-    writeLastSessionPointer,
+    writeLastSessionPointer: writeSessionPointer,
     getControlPlaneRecentEvents: (limit) => controlPlaneRecentEventsRef.value(limit),
     toolRegistry,
     forensicsRegistry,
@@ -308,9 +313,7 @@ export async function bootstrapRuntime(
   // `void workspaceCheckpointManager.init().catch(() => {})` — local file I/O only,
   // resolves well before a human can react to the first rendered frame.
   void announceResumeState({
-    workingDirectory: services.workingDirectory,
-    homeDirectory: services.homeDirectory,
-    surfaceRoot: 'tui',
+    surface: services.surface,
     sessionManager: services.sessionManager,
     checkpointManager: services.workspaceCheckpointManager,
     chainHistory: wrfcPersistence.knownChains,
@@ -718,16 +721,8 @@ export async function bootstrapRuntime(
     orchestratorRefs,
     setRenderRequest,
     permissionPromptRef, trustPromptRef,
-    loadLastConversation: () => loadLastConversation({
-      workingDirectory: services.workingDirectory,
-      homeDirectory: services.homeDirectory,
-      sessionManager: services.sessionManager,
-    }),
-    _writeLastSessionPointer: (sessionId) => writeLastSessionPointer(sessionId, {
-      workingDirectory: services.workingDirectory,
-      homeDirectory: services.homeDirectory,
-    }),
-    _saveSession: saveSession,
+    loadLastConversation: () => loadLastConversation({ surface: services.surface }),
+    _writeLastSessionPointer: writeSessionPointer,
     _getPinned: () => services.favoritesStore.getPinned(),
     _getConfiguredProviderIds: () => services.providerRegistry.getConfiguredProviderIds(),
     commandRegistry,

package/src/runtime/code-index-services.ts

@@ -102,6 +102,25 @@ export function codeIndexDbPath(workingDirectory: string): string {
   return join(workingDirectory, '.goodvibes', 'tui', 'code-index.sqlite');
 }
 
+/**
+ * Build the runtime's `rerootStores` implementation — called by
+ * WorkspaceSwapManager after it has verified a new working directory.
+ *
+ * Only working-tree-bound stores move. The memory store is deliberately NOT
+ * rerooted: it is the home-scoped canonical cross-surface store, and moving
+ * it per project would re-silo memory back into the per-project stores that
+ * were consolidated away.
+ */
+export function createStoreRerooter(deps: {
+  readonly codeIndexStore: Pick<CodeIndexStore, 'reroot'>;
+  readonly projectIndex: { reroot(dir: string): Promise<unknown> };
+}): (newWorkingDir: string) => Promise<void> {
+  return async (newWorkingDir: string): Promise<void> => {
+    await deps.codeIndexStore.reroot(newWorkingDir, codeIndexDbPath(newWorkingDir));
+    await deps.projectIndex.reroot(newWorkingDir);
+  };
+}
+
 /**
  * Whether the code index's initial build should auto-start on construction.
  * Exported so /codebase status and the settings modal read the exact same

package/src/runtime/durability-services.ts

@@ -28,6 +28,7 @@ import { resolveMemoryVectorDbPath } from '@pellux/goodvibes-sdk/platform/state'
 import { StoreSnapshotScheduler } from '@pellux/goodvibes-sdk/platform/state/store-snapshots';
 import { UserPermissionRuleStore } from '@pellux/goodvibes-sdk/platform/permissions';
 import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { SessionSurface } from '@/runtime/index.ts';
 
 export interface DurabilityServicesInput {
   readonly configManager: {
@@ -39,10 +40,13 @@ export interface DurabilityServicesInput {
   readonly providerRegistry: { refreshProviderCredentials(): Promise<void> };
   readonly memoryDbPath: string;
   readonly codeIndexDbPath: string;
-  /** Retention-sweep roots (mirrors the SDK's own createRuntimeServices roots). */
-  readonly workingDirectory: string;
-  readonly surfaceRoot: string;
-  readonly homeDirectory: string;
+  /**
+   * The app's declare-once storage handle. The retention-sweep roots below
+   * are read straight off it rather than re-declared here, so the janitor can
+   * never sweep a different scope than the one sessions and recovery
+   * snapshots are actually written to.
+   */
+  readonly surface: SessionSurface;
   readonly shellPaths: { resolveUserPath(...segments: string[]): string };
 }
 
@@ -71,9 +75,9 @@ export function createDurabilityServices(input: DurabilityServicesInput): Durabi
   // swallows its own errors).
   operations.runStartupAppendOnlySweep(
     {
-      workingDirectory: input.workingDirectory,
-      surfaceRoot: input.surfaceRoot,
-      homeDirectory: input.homeDirectory,
+      workingDirectory: input.surface.workingDirectory,
+      surfaceRoot: input.surface.surfaceRoot,
+      homeDirectory: input.surface.homeDirectory,
       logDir: input.shellPaths.resolveUserPath('logs'),
       telemetryDir: input.shellPaths.resolveUserPath('telemetry'),
     },

package/src/runtime/index.ts

@@ -285,6 +285,18 @@ export const getRecoveryDir = operations.getRecoveryDir;
 export const getLastSessionPointerPath = operations.getLastSessionPointerPath;
 export const writeLastSessionPointer = operations.writeLastSessionPointer;
 export const readLastSessionPointer = operations.readLastSessionPointer;
+// The declare-once storage handle (platform/runtime/session-surface.ts) plus
+// the two prompted-recovery primitives that only accept it. Every session
+// path in this app derives from one surface built in runtime/services.ts.
+export const createSessionSurface = operations.createSessionSurface;
+export type SessionSurface = Operations.SessionSurface;
+export const consumeRecovery = operations.consumeRecovery;
+export const removeRecoveryPoint = operations.removeRecoveryPoint;
+// Probe for a NAMED session's live snapshot (per-session supersession — see
+// session-recovery.ts's header) without retiring anything. Backs the
+// --continue / --resume pre-resume check in cli/tui-startup.ts.
+export const checkRecoveryForSession = operations.checkRecoveryForSession;
+export type RecoveryFileInfo = Operations.RecoveryFileInfo;
 export const exportRemoteArtifactForAgent = operations.exportRemoteArtifactForAgent;
 export const importRemoteArtifact = operations.importRemoteArtifact;
 export const RemoteRunnerRegistry = operations.RemoteRunnerRegistry;

package/src/runtime/process-lifecycle.ts

@@ -18,15 +18,38 @@
  * are assigned later and read at exit time (injected as getters/setter). The
  * `unsubs` registry is shared by reference and drained on exit.
  */
+import { existsSync } from 'node:fs';
 import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { createTerminalLifecycle, TERMINAL_ESCAPES } from '@pellux/goodvibes-terminal-shell';
 import { formatUserFacingErrorLine } from '../core/format-user-error.ts';
 import { allowTerminalWrite } from './terminal-output-guard.ts';
 import { buildPersistedSessionContext, deleteRecoveryFile } from '@/runtime/index.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
+import { removeLivenessMarker } from './session-liveness-marker.ts';
 import type { BootstrapContext } from './bootstrap.ts';
 import type { InputHandler } from '../input/handler.ts';
 import type { ConversationMessageSnapshot } from '../core/conversation.ts';
 
+/** Shutdown grace period before the "saving session…" line prints. Below this, exit stays quiet. */
+const SAVE_NOTICE_AFTER_MS = 300;
+/** Hard shutdown timeout — matches the pre-existing race below (was previously an inline literal). */
+const SHUTDOWN_HARD_TIMEOUT_MS = 3000;
+
+/**
+ * Whether a recovery snapshot actually exists on disk for this session. The
+ * periodic autosave (see recovery-autosave.ts) only writes on a 60s tick and
+ * skips empty conversations entirely, so a session that dies sooner than that
+ * (or never had anything in it) has no snapshot at all — the exit receipt
+ * must not claim otherwise. Never throws: a stat failure just means "absent".
+ */
+function defaultRecoverySnapshotExists(surface: SessionSurface, sessionId: string): boolean {
+  try {
+    return existsSync(surface.recoveryFile(sessionId));
+  } catch {
+    return false;
+  }
+}
+
 /** ANSI escape sequences used by the synchronous terminal restore. */
 export interface ProcessLifecycleAnsi {
   readonly CLEAR_SCREEN: string;
@@ -59,6 +82,16 @@ export interface ProcessLifecycleDeps {
   readonly getRecoveryInterval: () => ReturnType<typeof setInterval> | null;
   readonly setRecoveryInterval: (value: ReturnType<typeof setInterval> | null) => void;
   readonly getStopSpokenOutputForExit: () => (() => void | Promise<void>) | null;
+  /** Overridable for tests; defaults to SAVE_NOTICE_AFTER_MS (300ms). */
+  readonly saveNoticeAfterMs?: number;
+  /** Overridable for tests; defaults to SHUTDOWN_HARD_TIMEOUT_MS (3000ms). */
+  readonly shutdownHardTimeoutMs?: number;
+  /**
+   * Overridable for tests; defaults to a real filesystem existence check
+   * (defaultRecoverySnapshotExists). Never throws — a stat failure reads as
+   * "absent" rather than taking the exit path down.
+   */
+  readonly recoverySnapshotExists?: (surface: SessionSurface, sessionId: string) => boolean;
 }
 
 export interface ProcessLifecycleHandlers {
@@ -95,6 +128,9 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
     getRecoveryInterval,
     setRecoveryInterval,
     getStopSpokenOutputForExit,
+    saveNoticeAfterMs = SAVE_NOTICE_AFTER_MS,
+    shutdownHardTimeoutMs = SHUTDOWN_HARD_TIMEOUT_MS,
+    recoverySnapshotExists = defaultRecoverySnapshotExists,
   } = deps;
 
   const sigintHandler = (): void => getInput().feed('\x03');
@@ -202,6 +238,12 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
     restoreTerminal();
     const snapshot = ctx.conversation.toJSON() as { messages: Array<ConversationMessageSnapshot>; timestamp?: number };
     let shutdownOk = false;
+    // Quiet exit stays quiet: only speak up if the save is taking a moment.
+    // The terminal is already restored above, so a plain stdout line lands on
+    // the shell prompt exactly like any other command's output would.
+    const saveNoticeTimer = setTimeout(() => {
+      try { stdout.write('saving session…\n'); } catch { /* best-effort */ }
+    }, saveNoticeAfterMs);
     try {
       // Race the graceful shutdown against a hard timeout — externalServices.stop() can hang
       // and we must still exit; deferredStartup.drain only budgets 100ms internally.
@@ -211,19 +253,38 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
         spokenOutputDrain,
         Promise.race([
           ctx.shutdown({ ...snapshot, ...buildPersistedSessionContext(snapshot.messages, ctx.conversation.getTitleSource(), buildSessionContinuityHints()) }).then(() => { shutdownOk = true; }),
-          new Promise<void>((resolve) => setTimeout(resolve, 3000)),
+          new Promise<void>((resolve) => setTimeout(resolve, shutdownHardTimeoutMs)),
         ]),
       ]);
     } catch (err) {
       logger.debug('ctx.shutdown error during exitApp (non-fatal)', { error: summarizeError(err) });
     }
+    clearTimeout(saveNoticeTimer);
     // Only remove the recovery fallback once the durable shutdown save actually completed,
     // so an interrupted or timed-out shutdown leaves the snapshot for the next launch.
     // Scoped to THIS session's id: without it, one session's clean exit wipes
     // every session's crash snapshot (the concurrent-session isolation bug).
     if (shutdownOk) {
-      deleteRecoveryFile({ homeDirectory: ctx.services.homeDirectory }, ctx.runtime.sessionId);
+      deleteRecoveryFile({ surface: ctx.services.surface }, ctx.runtime.sessionId);
+    } else {
+      // The hard timeout won the race — the durable save never confirmed, so
+      // whatever the periodic autosave last wrote (see recovery-autosave.ts)
+      // is deliberately kept above. But that autosave only ticks every 60s
+      // and skips empty conversations, so a session that dies sooner than
+      // that (or never had anything in it) has no snapshot to keep — check
+      // before claiming otherwise, since a silent exit here previously left
+      // no trace that anything was amiss.
+      const kept = recoverySnapshotExists(ctx.services.surface, ctx.runtime.sessionId);
+      const line = kept
+        ? 'exit before save completed — a recovery snapshot was kept for next launch\n'
+        : 'exit before save completed — no recovery snapshot had been written yet\n';
+      try { stdout.write(line); } catch { /* best-effort */ }
     }
+    // Best-effort, unconditional: this process is exiting either way, so its
+    // multi-instance liveness marker (see session-liveness-marker.ts) should
+    // stop claiming the session is live regardless of whether the durable
+    // save itself completed in time.
+    removeLivenessMarker(ctx.services.surface, ctx.runtime.sessionId);
     process.exit(0);
   };
 

package/src/runtime/recovery-autosave.ts

@@ -0,0 +1,48 @@
+/**
+ * recovery-autosave.ts — periodic recovery-file autosave + liveness-marker
+ * refresh, extracted out of main.ts to keep it under the architecture
+ * line-count gate.
+ *
+ * Two things happen on the same cadence (default 60s):
+ *   1. The existing crash-recovery snapshot write (writeRecoveryFile).
+ *   2. The liveness marker refresh (see session-liveness-marker.ts) that lets
+ *      a second instance tell "this session is open in another terminal
+ *      right now" from "this is an orphaned crash snapshot".
+ * The marker is also written once immediately (not just on the first tick of
+ * the interval) so a second instance checking soon after this one launches
+ * sees it promptly rather than waiting up to a minute.
+ */
+import { buildPersistedSessionContext, writeRecoveryFile } from '@/runtime/index.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
+import { writeLivenessMarker } from './session-liveness-marker.ts';
+import type { ConversationManager, ConversationMessageSnapshot } from '../core/conversation.ts';
+
+export interface StartRecoveryAutosaveOptions {
+  readonly conversation: ConversationManager;
+  readonly runtime: { readonly sessionId: string };
+  /**
+   * The app's declare-once session-storage handle. Both the snapshot and the
+   * liveness marker resolve off it, so the startup recovery offer — which
+   * reads through the same handle — looks in the directory this writer used.
+   */
+  readonly surface: SessionSurface;
+  readonly buildSessionContinuityHints: () => Parameters<typeof buildPersistedSessionContext>[2];
+  /** Overridable for tests. Defaults to 60s. */
+  readonly intervalMs?: number;
+}
+
+export function startRecoveryAutosave(options: StartRecoveryAutosaveOptions): ReturnType<typeof setInterval> {
+  const { conversation, runtime, surface, buildSessionContinuityHints, intervalMs = 60_000 } = options;
+  writeLivenessMarker(surface, runtime.sessionId);
+  return setInterval(() => {
+    const snapshot = conversation.toJSON() as { messages: Array<ConversationMessageSnapshot> };
+    const persisted = buildPersistedSessionContext(snapshot.messages, conversation.getTitleSource(), buildSessionContinuityHints());
+    writeRecoveryFile(
+      { ...snapshot, ...persisted },
+      runtime.sessionId,
+      conversation.title ?? '',
+      { surface },
+    );
+    writeLivenessMarker(surface, runtime.sessionId);
+  }, intervalMs);
+}

package/src/runtime/recovery-decisions.ts

@@ -0,0 +1,126 @@
+/**
+ * recovery-decisions.ts — a durable record of the recovery snapshots the user
+ * has already said "Remove" to.
+ *
+ * The defect this exists for: answering Remove deletes the snapshot file, and
+ * that was the whole memory of the decision. Anything that puts the file back
+ * — a session still running on an older build rewriting its snapshot every
+ * 60s, a restored backup, a synced directory — produced the same question
+ * again on the next launch, and again after the next removal, with no way for
+ * the user to make it stop. A decision the product forgets the instant it acts
+ * on it is not a decision the user gets to make.
+ *
+ * So Remove now writes a record that outlives the process, and a recorded
+ * snapshot found on disk again is deleted without asking. "Keep" is
+ * deliberately NOT recorded here: Keep means "leave it, ask me next launch",
+ * and recovery-prompt.ts's in-process set already holds it for the rest of the
+ * run.
+ *
+ * WHERE IT LIVES, and why not under `surface.stateDir`:
+ * `<homeDirectory>/.goodvibes/<surfaceRoot>/recovery-decisions.json` — home-
+ * anchored, matching session-liveness-marker.ts, and deliberately NOT the
+ * project-anchored `surface.stateDir`. The snapshots this defends against
+ * include the ones in the SDK's legacy shared recovery directory, which is
+ * itself home-anchored and shared by every project that ever used this
+ * surfaceRoot; the current build dual-reads it, so ONE such snapshot is
+ * offered at the launch of EVERY project. A project-scoped record could only
+ * ever silence one project at a time, which is the same nag wearing a
+ * different hat. Records are matched on session id alone; ids are unique, so
+ * a record made in one project cannot suppress a different snapshot in
+ * another. Each record still carries the workspace it was made in, so the file
+ * says plainly where the decision came from.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { SessionSurface } from '@/runtime/index.ts';
+
+/** One "the user removed this snapshot" decision. */
+export interface RecoveryRemovalRecord {
+  readonly sessionId: string;
+  /** The project the decision was made in. Provenance — matching is on sessionId alone. */
+  readonly workspace: string;
+  readonly removedAt: number;
+}
+
+/**
+ * Bounds on the ledger. It is append-mostly and never read by anything but
+ * the boot offer, so it stays small by construction; these are the guards
+ * against a pathological case, not a routine cleanup.
+ *
+ * Note what is deliberately NOT the pruning rule: "drop records whose snapshot
+ * file no longer exists". Every record in here describes a file that was just
+ * deleted, so that rule would empty the ledger immediately and reinstate the
+ * exact defect it was written to fix — the point is precisely to still
+ * remember once the file comes back. Age and count are the honest bounds.
+ */
+const MAX_RECORDS = 200;
+const RECORD_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+
+/** Absolute path to this surface's removal ledger. */
+export function recoveryDecisionsPathFor(surface: SessionSurface): string {
+  return join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot, 'recovery-decisions.json');
+}
+
+function isRecord(value: unknown): value is RecoveryRemovalRecord {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as Partial<RecoveryRemovalRecord>;
+  return typeof candidate.sessionId === 'string'
+    && candidate.sessionId.length > 0
+    && typeof candidate.workspace === 'string'
+    && typeof candidate.removedAt === 'number'
+    && Number.isFinite(candidate.removedAt);
+}
+
+/**
+ * Every removal decision still in force, oldest first. A missing, unreadable
+ * or malformed ledger reads as "no decisions recorded" rather than throwing:
+ * a corrupt file must not be able to take a boot down, and the worst outcome
+ * of losing it is that the user is asked once more.
+ */
+export function readRecoveryRemovals(surface: SessionSurface, nowMs: number = Date.now()): RecoveryRemovalRecord[] {
+  try {
+    const path = recoveryDecisionsPathFor(surface);
+    if (!existsSync(path)) return [];
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(isRecord).filter((record) => nowMs - record.removedAt < RECORD_TTL_MS);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Has the user already chosen Remove for this snapshot's session, in this or
+ * any earlier run?
+ */
+export function isRecoveryRemovalRecorded(surface: SessionSurface, sessionId: string, nowMs: number = Date.now()): boolean {
+  if (!sessionId.trim()) return false;
+  return readRecoveryRemovals(surface, nowMs).some((record) => record.sessionId === sessionId);
+}
+
+/**
+ * Record that the user chose Remove for `sessionId`. Idempotent — a repeat
+ * removal of a snapshot that came back refreshes the existing record's
+ * timestamp rather than adding a second one, so the ledger cannot grow by one
+ * entry per reappearance.
+ *
+ * Best-effort: a ledger that cannot be written must not break the removal the
+ * user actually asked for. The cost of a failed write is one more question on
+ * a future launch, which is exactly the behaviour that shipped before this
+ * file existed.
+ */
+export function recordRecoveryRemoval(surface: SessionSurface, sessionId: string, nowMs: number = Date.now()): void {
+  if (!sessionId.trim()) return;
+  try {
+    const kept = readRecoveryRemovals(surface, nowMs).filter((record) => record.sessionId !== sessionId);
+    kept.push({ sessionId, workspace: surface.workingDirectory, removedAt: nowMs });
+    // Oldest decisions fall off first; the newest are the ones a reappearing
+    // snapshot is most likely to match.
+    const bounded = kept.slice(-MAX_RECORDS);
+    const path = recoveryDecisionsPathFor(surface);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(bounded, null, 2) + '\n', { mode: 0o600 });
+  } catch {
+    // Best-effort by construction — see the doc comment above.
+  }
+}

package/src/runtime/recovery-offer-wiring.ts

@@ -0,0 +1,89 @@
+/**
+ * recovery-offer-wiring.ts — binds the startup recovery offer
+ * (runtime/recovery-prompt.ts) to this shell's live objects.
+ *
+ * Kept out of main.ts so the entrypoint stays under the architecture
+ * line-count gate, and kept out of recovery-prompt.ts so that module stays a
+ * pure flow with injectable edges (which is what makes it testable without a
+ * booted runtime).
+ *
+ * What accepting a snapshot actually does, and why each step is here:
+ *   - `runtime.sessionId` moves to the snapshot's session FIRST. The
+ *     transcript journal rebinds on that field (turn-event-wiring.ts), and
+ *     every later turn snapshot keys off it. Without this the restored
+ *     conversation would be written back under the fresh boot session id —
+ *     the recovery point would be gone and its content would live somewhere
+ *     the user never asked for.
+ *   - The conversation is rebuilt through core/session-recovery.ts's
+ *     `applyRecoverySnapshot`, which runs the same reset/fromJSON/rebuild +
+ *     journal-replay sequence a normal resume runs.
+ *   - The last-session pointer is written, so `--continue` on the next launch
+ *     reaches the session the user just recovered.
+ *   - Footer token counters are rehydrated from the restored history, so the
+ *     numbers on screen describe the conversation actually in memory.
+ */
+import { applyRecoverySnapshot, type RecoverySnapshotPayload } from '../core/session-recovery.ts';
+import type { RecoveryPromptDeps } from './recovery-prompt.ts';
+import type { ConversationManager, ConversationMessageSnapshot } from '../core/conversation.ts';
+import type { CommandContext } from '../input/command-registry.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
+import type { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
+
+export interface RecoveryOfferWiringInput {
+  readonly surface: SessionSurface;
+  readonly sessionManager: Pick<SessionManager, 'save'>;
+  readonly runtime: { sessionId: string; model: string; provider: string };
+  readonly conversation: ConversationManager;
+  readonly commandContext: Pick<CommandContext, 'openSelection'> & {
+    readonly session?: { readonly hydrateSessionUsage?: (() => void) | undefined } | undefined;
+  };
+  readonly writeLastSessionPointer: (sessionId: string) => void;
+  readonly receipt: (line: string) => void;
+  readonly render: () => void;
+}
+
+export function buildRecoveryOfferWiring(input: RecoveryOfferWiringInput): RecoveryPromptDeps {
+  return {
+    surface: input.surface,
+    // Read lazily: wireShellUiOpeners patches `openSelection` onto the command
+    // context after this wiring is built, and the offer runs later still.
+    get openSelection() { return input.commandContext.openSelection; },
+    receipt: input.receipt,
+    render: input.render,
+    applySnapshot: ({ snapshot, sessionId }) => {
+      input.runtime.sessionId = sessionId;
+      const payload = snapshot as unknown as RecoverySnapshotPayload;
+      const persist = (messages: ConversationMessageSnapshot[]): void => {
+        input.sessionManager.save(sessionId, messages as never[], {
+          title: input.conversation.title || payload.title || '',
+          model: input.runtime.model,
+          provider: input.runtime.provider,
+          timestamp: Date.now(),
+          // The user explicitly chose to recover this crashed session in the
+          // modal. Expiring it out from under them on a later retention sweep
+          // would undo the exact thing they just asked for.
+          saveSource: 'user',
+        });
+      };
+      const { messageCount } = applyRecoverySnapshot({
+        snapshot: payload,
+        sessionId,
+        conversation: input.conversation,
+        surface: input.surface,
+        persistSnapshot: persist,
+      });
+      // Unconditional, and the reason is the whole point of this feature: a
+      // crash-recovery snapshot is NOT a session-store entry. The snapshot
+      // file has just been retired by consumeRecovery, so until this write
+      // lands the recovered conversation exists only in memory — the pointer
+      // below would name a session nothing could load, and `/session resume
+      // <id>` would still not reach it. The gap-closure persist above only
+      // fires when the journal actually had records to replay, so it cannot
+      // be relied on for this.
+      persist(input.conversation.getMessageSnapshot() as ConversationMessageSnapshot[]);
+      input.writeLastSessionPointer(sessionId);
+      input.commandContext.session?.hydrateSessionUsage?.();
+      return messageCount;
+    },
+  };
+}