@pellux/goodvibes-tui 1.27.0 → 2.0.1

package/src/runtime/path-shadow-startup.ts

@@ -1,243 +1,50 @@
 /**
- * path-shadow-startup.ts — the boot-time surfacing of "is this the build you
- * are actually reaching, and is it the current one".
+ * path-shadow-startup.ts — this terminal's boot-time reachability report.
  *
- * It wires the real host inputs (this process's executable, the real PATH,
- * existsSync/realpathSync, and a bounded `<path> --version` spawn) into the
- * pure scan in path-shadow.ts and the pure wording in reachability-notice.ts,
- * then prints the result through the same SystemMessageRouter the rest of
- * startup uses, at high priority, before the session gets going.
- *
- * Cost discipline, because this runs on every start:
- *   - the first scan is existence-only: no process is spawned while there is
- *     nothing to report, which is the overwhelmingly common case;
- *   - versions are probed only after a shadow has already been found, and
- *     only with `--version`, bounded by a short timeout;
- *   - the latest-release lookup only happens when it can actually change what
- *     the user should do: a package-managed or source install (which will
- *     never swap itself), or an install that has just been found unreachable.
- *     A healthy binary install has already been brought to the latest release
- *     by the launch auto-updater, so asking again would be a network round
- *     trip that can only confirm what just happened.
- *
- * Every failure is swallowed. A reachability check must never block or crash
- * boot.
+ * The check itself (the PATH scan, the `--version` probes, the cost discipline
+ * that keeps a healthy start free of spawns and network calls, and the wording)
+ * belongs to the platform. All this supplies is what only this product knows:
+ * which command name the shell resolves it by, which package a package-managed
+ * install would be upgraded through, which release lookup answers "what is
+ * current", and where the lines are printed.
  */
 
-import { spawnSync } from 'node:child_process';
-import { realpathSync, statSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
-import { detectInstallKind, fallbackUpdateCommand, type UpdateFetchLike } from './update-check.ts';
+import { announceReachability, boundedLatestRelease } from '@pellux/goodvibes-sdk/platform/runtime/operations';
+import type { UpdateFetchLike } from './update-check.ts';
 import { checkForUpdate } from '../input/commands/update-runtime.ts';
-import {
-  scanCommandShadows,
-  splitPathEntries,
-  type ShadowScanResult,
-} from './path-shadow.ts';
-import { buildReachabilityNotices, type ReachabilityNotice } from './reachability-notice.ts';
 import { VERSION } from '../version.ts';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
 
-/** The commands a goodvibes install places side by side in one directory. */
-export const INSTALLED_COMMANDS = ['goodvibes', 'goodvibes-daemon', 'goodvibes-agent'] as const;
-
-/** How long a `<path> --version` probe may take before it is abandoned. */
-const VERSION_PROBE_TIMEOUT_MS = 3000;
-/** How long the latest-release lookup may take before startup moves on without it. */
-const LATEST_LOOKUP_TIMEOUT_MS = 2500;
-
-function safeRealPath(path: string): string {
-  try {
-    return realpathSync(path);
-  } catch {
-    return path;
-  }
-}
-
-function isExecutableFile(path: string): boolean {
-  try {
-    const stats = statSync(path);
-    if (!stats.isFile()) return false;
-    // Any execute bit is enough: the shell searches for an executable file,
-    // and which bit applies depends on ownership we are not going to compute.
-    return (stats.mode & 0o111) !== 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Runs `<path> --version` and returns its first line. Never inherits stdio, so
- * a binary that tries to draw a terminal cannot disturb this one.
- */
-export function probeVersionLine(path: string): string | undefined {
-  try {
-    const result = spawnSync(path, ['--version'], {
-      timeout: VERSION_PROBE_TIMEOUT_MS,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      windowsHide: true,
-    });
-    if (result.error || typeof result.stdout !== 'string') return undefined;
-    return result.stdout.split('\n')[0];
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * The PATH directory that provides THIS running executable, which is the
- * position everything else is measured against.
- *
- * Preferred answer: the first PATH entry whose `<dir>/<command>` resolves,
- * through symlinks, to this same file. That is exactly "where the shell would
- * find me", and it is right for a linked package install as well as a
- * standalone binary.
- *
- * Fallback, for a standalone binary only: the directory the executable sits
- * in. That directory being absent from PATH is itself worth reporting — an
- * installed binary nobody can reach by name. For a package-managed install
- * the executable lives inside node_modules, which is never on PATH and never
- * meant to be, so there is nothing honest to say and the check stays silent.
- */
-export function resolveSelfDirectory(input: {
-  readonly execPath: string;
-  readonly command: string;
-  readonly pathEntries: readonly string[];
-  readonly realPath: (path: string) => string;
-  readonly isExecutableFile: (path: string) => boolean;
-}): string | undefined {
-  const self = input.realPath(input.execPath);
-  for (const directory of input.pathEntries) {
-    const candidate = join(directory, input.command);
-    if (!input.isExecutableFile(candidate)) continue;
-    if (input.realPath(candidate) === self) return directory;
-  }
-  if (detectInstallKind(input.execPath) === 'binary') return dirname(self);
-  return undefined;
-}
-
-/** Which of the installed commands actually sit in this directory. */
-function commandsPresentIn(directory: string, exists: (path: string) => boolean): string[] {
-  return INSTALLED_COMMANDS.filter((command) => exists(join(directory, command)));
-}
-
-export interface ReachabilityCheckResult {
-  readonly notices: readonly ReachabilityNotice[];
-  readonly scan?: ShadowScanResult | undefined;
-}
+/** The package a package-managed install of this terminal is upgraded through. */
+const TERMINAL_PACKAGE_NAME = '@pellux/goodvibes-tui';
 
-/**
- * The whole check, with the network lookup injected so tests never reach it.
- * Returns the notices to print; an empty list is the healthy case.
- */
-export async function runReachabilityCheck(input: {
-  readonly execPath: string;
-  readonly pathValue: string | undefined;
-  readonly homeDir: string;
-  readonly runningVersion: string;
-  readonly commandName?: string | undefined;
-  /** Resolves the newest released version, or undefined when it cannot be determined. */
-  readonly resolveLatest: () => Promise<string | undefined>;
-  // The host touches, injectable so a test drives a whole scenario with fake
-  // paths and never spawns anything. Production passes none of these.
-  readonly isExecutableFile?: ((path: string) => boolean) | undefined;
-  readonly realPath?: ((path: string) => string) | undefined;
-  readonly probeVersion?: ((path: string) => string | undefined) | undefined;
-}): Promise<ReachabilityCheckResult> {
-  const command = input.commandName ?? basename(input.execPath);
-  const pathEntries = splitPathEntries(input.pathValue);
-  const installKind = detectInstallKind(input.execPath);
-  const fileIsExecutable = input.isExecutableFile ?? isExecutableFile;
-  const resolvePath = input.realPath ?? safeRealPath;
-  const versionProbe = input.probeVersion ?? probeVersionLine;
+/** The command name the shell resolves this terminal by. */
+const TERMINAL_COMMAND_NAME = 'goodvibes';
 
-  // A source checkout is not an install: there is no maintained copy to be
-  // shadowed and no release to be behind.
-  if (installKind === 'source') return { notices: [] };
-
-  const selfDirectory = resolveSelfDirectory({
-    execPath: input.execPath,
-    command,
-    pathEntries,
-    realPath: resolvePath,
-    isExecutableFile: fileIsExecutable,
+/** The same release lookup `/update` uses — there is deliberately no second source of truth. */
+function resolveLatestRelease(): Promise<string | undefined> {
+  return boundedLatestRelease(async () => {
+    const result = await checkForUpdate(fetch as UpdateFetchLike, VERSION);
+    return result.latestTag;
   });
-  if (!selfDirectory) return { notices: [] };
-
-  const commands = commandsPresentIn(selfDirectory, fileIsExecutable);
-  const base = {
-    commands: commands.length > 0 ? commands : [command],
-    installDir: selfDirectory,
-    pathEntries,
-    homeDir: input.homeDir,
-    isExecutableFile: fileIsExecutable,
-    realPath: resolvePath,
-  };
-
-  // Existence-only first: nothing is spawned while there is nothing to report.
-  const cheapScan = scanCommandShadows(base);
-  const scan = cheapScan.hasProblem
-    ? scanCommandShadows({ ...base, probeVersion: versionProbe })
-    : cheapScan;
-
-  const latestVersion = scan.hasProblem || installKind !== 'binary'
-    ? await input.resolveLatest()
-    : undefined;
-
-  return {
-    scan,
-    notices: buildReachabilityNotices({
-      scan,
-      runningVersion: input.runningVersion,
-      latestVersion,
-      updateCommand: installKind === 'binary'
-        ? 'curl -fsSL https://goodvibes.sh/install.sh | sh'
-        : fallbackUpdateCommand(installKind),
-    }),
-  };
-}
-
-/** The real latest-release lookup, bounded so a slow network cannot hold up boot. */
-async function resolveLatestReleaseBounded(): Promise<string | undefined> {
-  try {
-    // The same release lookup /update uses — there is deliberately no second
-    // source of truth for what the latest version is.
-    const lookup = checkForUpdate(fetch as UpdateFetchLike, VERSION).then((result) => result.latestTag);
-    const timed = await Promise.race([
-      lookup,
-      new Promise<undefined>((resolve) => {
-        const timer = setTimeout(() => resolve(undefined), LATEST_LOOKUP_TIMEOUT_MS);
-        timer.unref?.();
-      }),
-    ]);
-    return timed ?? undefined;
-  } catch {
-    return undefined;
-  }
 }
 
 /**
  * Boot-time wiring. Prints one high-priority system message per line so the
  * report reads as prose rather than a single wrapped paragraph, and swallows
- * everything.
+ * everything — a reachability check must never block or crash boot.
  */
-export async function announceReachability(router: SystemMessageRouter): Promise<void> {
-  try {
-    const result = await runReachabilityCheck({
+export async function announceInstallReachability(router: SystemMessageRouter): Promise<void> {
+  await announceReachability(
+    {
       execPath: process.execPath,
       pathValue: process.env['PATH'],
       homeDir: process.env['HOME'] ?? '',
       runningVersion: VERSION,
-      commandName: 'goodvibes',
-      resolveLatest: resolveLatestReleaseBounded,
-    });
-    for (const notice of result.notices) {
-      for (const line of notice.lines) {
-        router.high(`[Install] ${line}`);
-      }
-    }
-  } catch {
-    // Best-effort — a reachability check must never block or crash boot.
-  }
+      commandName: TERMINAL_COMMAND_NAME,
+      packageName: TERMINAL_PACKAGE_NAME,
+      resolveLatest: resolveLatestRelease,
+    },
+    (line) => router.high(`[Install] ${line}`),
+  );
 }

package/src/runtime/power-keepawake-remote.ts

@@ -13,8 +13,9 @@
 // A single config subscriber carries ALL THREE toggle paths (/power, Alt+A, the
 // settings modal): each lands on the power.keepAwake config key — the local
 // PowerManager persists it on set, and the settings modal writes it directly —
-// so subscribing to that one key catches every origin. In the EMBEDDED topology
-// this is a no-op: the in-process manager already IS the daemon.
+// so subscribing to that one key catches every origin. When there is no adopted
+// external daemon (`isExternalDaemon()` false), this is a no-op: there is nothing
+// to forward to.
 // ---------------------------------------------------------------------------
 
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';

package/src/runtime/process-lifecycle.ts

@@ -22,10 +22,10 @@ import { existsSync } from 'node:fs';
 import { flushActivityLogSync, 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 { allowTerminalWrite } from '@pellux/goodvibes-terminal-shell/terminal-output-guard';
 import { buildPersistedSessionContext, deleteRecoveryFile } from '@/runtime/index.ts';
 import type { SessionSurface } from '@/runtime/index.ts';
-import { removeLivenessMarker } from './session-liveness-marker.ts';
+import { removeLivenessMarker } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { BootstrapContext } from './bootstrap.ts';
 import type { InputHandler } from '../input/handler.ts';
 import type { ConversationMessageSnapshot } from '../core/conversation.ts';

package/src/runtime/provider-fallback.ts

@@ -1,74 +1,18 @@
 /**
- * provider-fallback.ts — the pre-catalog fallback registration for the
- * configured model, extracted verbatim from services.ts (file-size hygiene):
- * before the model catalog cache has loaded, the configured provider:model is
- * registered with SDK family-aware context-window inference so the meter and
- * compaction denominator agree with the post-catalog window.
+ * provider-fallback.ts — boot-time model routability, the part the SDK does
+ * not cover.
+ *
+ * The pre-catalog fallback registration for the configured model
+ * (`ensureConfiguredModelIsRoutable`) is the SDK's own
+ * (`@pellux/goodvibes-sdk/platform/providers`) — this file only imports it for
+ * `ensureBootModelResolvable` below, which is NOT in the SDK: it is the
+ * boot-time custom-provider-readiness wrapper this app's boot path needs and
+ * the SDK's floor does not compose.
  */
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
-import {
-  inferFallbackContextWindow,
-  resolveReasoningEffortSpec,
-  type ModelDefinition,
-  type ProviderRegistry,
-} from '@pellux/goodvibes-sdk/platform/providers';
+import { ensureConfiguredModelIsRoutable, type ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
-function buildFallbackModelDefinition(provider: string, modelId: string): ModelDefinition {
-  const providerLower = provider.toLowerCase();
-  const isReasoningProvider = providerLower.includes('openai')
-    || providerLower.includes('anthropic')
-    || providerLower.includes('gemini')
-    || providerLower.includes('google');
-
-  return {
-    id: modelId,
-    provider,
-    registryKey: `${provider}:${modelId}`,
-    displayName: modelId,
-    description: 'Configured model available before the model catalog cache has loaded.',
-    capabilities: {
-      toolCalling: true,
-      codeEditing: true,
-      reasoning: isReasoningProvider,
-      multimodal: isReasoningProvider,
-    },
-    contextWindow: inferFallbackContextWindow(provider, modelId),
-    contextWindowProvenance: 'fallback',
-    selectable: true,
-    tier: 'standard',
-    // Which levels this model accepts is a property of the model, not of the
-    // provider it sits behind: the hardcoded four ('instant', 'low', 'medium',
-    // 'high') offered 'instant' to models that reject it and hid 'xhigh',
-    // 'max' and 'none' from models that accept them. The SDK resolver answers
-    // from the curated family table when the catalog has not loaded yet, and
-    // otherwise returns its own labelled best guess, which the adapters treat
-    // as "send nothing" rather than as verified levels.
-    ...(isReasoningProvider
-      ? { reasoningEffort: resolveReasoningEffortSpec({ modelId }) }
-      : {}),
-  };
-}
-
-export function ensureConfiguredModelIsRoutable(providerRegistry: ProviderRegistry, configManager: ConfigManager): void {
-  const configuredModel = String(configManager.get('provider.model') ?? '').trim();
-  if (!configuredModel.includes(':')) return;
-  if (providerRegistry.listModels().some((model) => model.registryKey === configuredModel)) return;
-
-  const [providerId, ...modelParts] = configuredModel.split(':');
-  const modelId = modelParts.join(':').trim();
-  if (!providerId || !modelId) return;
-
-  const provider = providerRegistry.tryGet(providerId);
-  if (!provider) return;
-
-  providerRegistry.registerRuntimeProvider({
-    provider,
-    replace: true,
-    models: [buildFallbackModelDefinition(providerId, modelId)],
-  });
-}
-
 /**
  * Boot-time custom-provider readiness. Custom providers register
  * asynchronously (services.ts fires initCustomProviders() without awaiting),

package/src/runtime/recovery-autosave.ts

@@ -14,7 +14,7 @@
  */
 import { buildPersistedSessionContext, writeRecoveryFile } from '@/runtime/index.ts';
 import type { SessionSurface } from '@/runtime/index.ts';
-import { writeLivenessMarker } from './session-liveness-marker.ts';
+import { writeLivenessMarker } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { ConversationManager, ConversationMessageSnapshot } from '../core/conversation.ts';
 
 export interface StartRecoveryAutosaveOptions {

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

@@ -8,21 +8,25 @@
  * 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.
+ *   - `runtime.sessionId` moves to the snapshot's session, once the restore has
+ *     actually happened. 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. It moves AFTER the apply
+ *     rather than before, so a refusal (nothing on disk, a damaged file) leaves
+ *     this boot on its own session instead of adopting one it never loaded.
+ *   - The conversation is rebuilt through the SDK's `applyRecoverySnapshot`,
+ *     which reads and retires the snapshot in one operation and runs the same
+ *     reset/fromJSON/rebuild + journal-replay sequence a normal resume runs.
+ *     This module supplies the live conversation, the persist callback and the
+ *     user's answer; nothing else about the restore is decided here.
  *   - 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 { applyRecoverySnapshot, confirmRecoveryRestore } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { RecoveryPromptDeps } from './recovery-prompt.ts';
 import type { ConversationManager, ConversationMessageSnapshot } from '../core/conversation.ts';
 import type { CommandContext } from '../input/command-registry.ts';
@@ -50,12 +54,10 @@ export function buildRecoveryOfferWiring(input: RecoveryOfferWiringInput): Recov
     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;
+    applySnapshot: ({ sessionId }) => {
       const persist = (messages: ConversationMessageSnapshot[]): void => {
         input.sessionManager.save(sessionId, messages as never[], {
-          title: input.conversation.title || payload.title || '',
+          title: input.conversation.title || '',
           model: input.runtime.model,
           provider: input.runtime.provider,
           timestamp: Date.now(),
@@ -65,25 +67,39 @@ export function buildRecoveryOfferWiring(input: RecoveryOfferWiringInput): Recov
           saveSource: 'user',
         });
       };
-      const { messageCount } = applyRecoverySnapshot({
-        snapshot: payload,
+      // The user picked "Resume it" in the offer modal — that answer, and
+      // nothing else, is what unlocks the restore.
+      const result = applyRecoverySnapshot({
         sessionId,
         conversation: input.conversation,
         surface: input.surface,
         persistSnapshot: persist,
+        confirmation: confirmRecoveryRestore(true)!,
       });
+      // A refusal leaves this boot exactly as it was: the fresh session id
+      // stands, nothing is persisted, and no last-session pointer is written.
+      // The prompt turns the refusal into a receipt.
+      if (!result.applied) return result;
+      // Now that the conversation really is the recovered one, the runtime
+      // moves to its session. The transcript journal rebinds on this field
+      // (turn-event-wiring.ts) and every later turn snapshot keys off it, so
+      // leaving it on the fresh boot session would write the restored
+      // conversation back under an id the user never asked for. Both the
+      // persist above and the one below name the session explicitly, so
+      // neither depends on this assignment having happened first.
+      input.runtime.sessionId = sessionId;
       // 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.
+      // file has just been retired by the read that loaded it, 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;
+      return result;
     },
   };
 }

package/src/runtime/recovery-prompt.ts

@@ -14,11 +14,14 @@
  * Rules this flow keeps:
  *   - Nothing is ever applied without the user picking Resume. There is no
  *     silent auto-restore path here, and this module never loads a snapshot
- *     just to look at it — `checkRecoveryFile` reports, `consumeRecovery`
- *     loads, and only the second one runs after an explicit yes.
- *   - The SDK's `consumeRecovery` is load-then-delete: the snapshot file is
- *     retired only after a successful load, so a failed read can never
- *     destroy state that was never actually recovered.
+ *     just to look at it — `checkRecoveryFile` reports, and only an explicit
+ *     yes reaches the code that opens the file.
+ *   - The SDK's `applyRecoverySnapshot` is what runs on that yes, and it will
+ *     not run without the confirmation token this flow hands it. It reads,
+ *     retires and applies in one operation, load-then-delete: the file is
+ *     retired only after a successful load, so a failed read can never destroy
+ *     state that was never actually recovered — and a successful load can
+ *     never leave a restored snapshot behind to be offered again.
  *   - Every fact shown is one we actually have (session id, snapshot age,
  *     title when the snapshot carries one, byte size when the file is where
  *     we can stat it). Nothing is estimated to fill the sentence out.
@@ -51,10 +54,11 @@
  *     decisions cannot quietly grow forever and nothing is deleted in silence.
  */
 import { statSync } from 'node:fs';
-import { checkRecoveryFile, checkRecoveryForSession, consumeRecovery, removeRecoveryPoint } from '@/runtime/index.ts';
+import { checkRecoveryFile, checkRecoveryForSession, removeRecoveryPoint } from '@/runtime/index.ts';
+import type { ApplyRecoverySnapshotResult } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { RecoveryFileInfo, SessionSurface } from '@/runtime/index.ts';
 import { isRecoveryRemovalRecorded, pruneRecoveryDecisions, recordRecoveryRemoval } from './recovery-decisions.ts';
-import { checkSessionLiveness } from './session-liveness-marker.ts';
+import { checkSessionLiveness } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { SelectionItem, SelectionResult } from '../input/selection-modal.ts';
 
 /** How the offer ended. Returned so startup wiring (and tests) can assert the real outcome. */
@@ -79,10 +83,16 @@ export interface RecoveryPromptDeps {
   readonly openSelection: SelectionOpener | undefined;
   /**
    * Apply an explicitly-accepted snapshot to the live conversation and report
-   * how many messages ended up in it. Supplied by the startup wiring so this
-   * module never reaches into conversation state itself.
+   * what happened. Supplied by the startup wiring so this module never reaches
+   * into conversation state itself.
+   *
+   * It takes a session id, not a loaded snapshot: reading the snapshot and
+   * retiring it are one operation in the SDK's `applyRecoverySnapshot`, so this
+   * flow cannot load one and then leave it behind. That is why "could not read
+   * it" arrives here as a refusal in the result rather than as a separate
+   * consume step this module runs first.
    */
-  readonly applySnapshot: (payload: { readonly snapshot: Record<string, unknown>; readonly sessionId: string }) => number;
+  readonly applySnapshot: (payload: { readonly sessionId: string }) => ApplyRecoverySnapshotResult;
   /** One-line honest receipt into the transcript. */
   readonly receipt: (line: string) => void;
   readonly render: () => void;
@@ -301,16 +311,20 @@ export async function offerRecoverySnapshot(deps: RecoveryPromptDeps): Promise<R
     const answer = await ask(open, RECOVERY_OFFER_TITLE, buildRecoveryOfferItems(facts));
 
     if (answer === 'resume') {
-      const { snapshot, consumed } = consumeRecovery(deps.surface, info.sessionId);
-      if (!snapshot || !consumed) {
-        // consumeRecovery leaves the file alone when the load fails, so the
-        // snapshot is still there to try again next launch. Say so.
-        deps.receipt('Recovery snapshot could not be read — it was left on disk and will be offered again next launch.');
+      const result = deps.applySnapshot({ sessionId: info.sessionId });
+      if (!result.applied) {
+        // Each refusal is a different fact and gets its own sentence, because
+        // "left on disk, try again next launch" and "the file was damaged and
+        // is gone" are not the same news.
+        deps.receipt(
+          result.refusal === 'no-snapshot'
+            ? 'Recovery snapshot could not be read — it was left on disk and will be offered again next launch.'
+            : `Recovery snapshot for session ${info.sessionId} could not be restored — the file was damaged, and reading it retired it. Nothing was changed in this session.`,
+        );
         deps.render();
         return 'resume-failed';
       }
-      const messageCount = deps.applySnapshot({ snapshot: snapshot as unknown as Record<string, unknown>, sessionId: info.sessionId });
-      deps.receipt(`Recovery snapshot restored: ${messageCount} message(s) from session ${info.sessionId}. The recovery point has been retired.`);
+      deps.receipt(`Recovery snapshot restored: ${result.messageCount} message(s) from session ${info.sessionId}. The recovery point has been retired.`);
       deps.render();
       return 'resumed';
     }