@pellux/goodvibes-tui 1.19.6 → 1.20.0

package/src/runtime/recovery-prompt.ts

@@ -0,0 +1,312 @@
+/**
+ * recovery-prompt.ts — the startup "a recovery snapshot exists, do you want
+ * it?" flow.
+ *
+ * A crash-recovery snapshot used to get one sentence in the boot resume
+ * notice, which left the operator to read it and retype a command — and for a
+ * session that crashed before its first clean save, there was no command that
+ * reached the snapshot at all, so the sentence was a dead end. This module
+ * replaces that with an explicit two-step ask:
+ *
+ *   1. "Resume it?"  [Resume] [Not now]
+ *   2. on decline:   "Remove this recovery point?"  [Keep] [Remove]
+ *
+ * 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.
+ *   - 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.
+ *   - Those facts live in a row's `detail`, never in the modal title. The
+ *     selection overlay truncates its title to the box width
+ *     (selection-modal-overlay.ts) but wraps `detail` onto as many lines as it
+ *     needs with no cap, so detail is the only place long copy is guaranteed
+ *     to be shown in full. Titles here stay short enough to survive a narrow
+ *     terminal intact.
+ *   - A snapshot whose session still has a live pid marker is not offered at
+ *     all: another terminal is refreshing it right now, so it is not an
+ *     orphaned crash and resuming it here would fork that instance's live
+ *     state.
+ *   - Escape is not an answer. Dismissing either modal leaves the snapshot
+ *     exactly where it is; only "Remove" deletes anything.
+ *   - The destructive row is never the one Enter is already sitting on. Both
+ *     modals open on their harmless first row, so answering either of them
+ *     without reading keeps the snapshot.
+ *   - Keep (or a dismissal) stays quiet for the rest of the run. The snapshot
+ *     is offered again on the next launch, not again in this one.
+ */
+import { statSync } from 'node:fs';
+import { checkRecoveryFile, checkRecoveryForSession, consumeRecovery, removeRecoveryPoint } from '@/runtime/index.ts';
+import type { RecoveryFileInfo, SessionSurface } from '@/runtime/index.ts';
+import { checkSessionLiveness } from './session-liveness-marker.ts';
+import type { SelectionItem, SelectionResult } from '../input/selection-modal.ts';
+
+/** How the offer ended. Returned so startup wiring (and tests) can assert the real outcome. */
+export type RecoveryPromptOutcome =
+  | 'none' // no snapshot, or one that belongs to a still-live session
+  | 'resumed' // user chose Resume and the snapshot was applied
+  | 'resume-failed' // user chose Resume but the snapshot could not be loaded
+  | 'removed' // user declined and chose Remove
+  | 'kept'; // user declined and chose Keep, or dismissed a modal
+
+/** Open a selection modal and resolve with the chosen item id (null on dismissal). */
+export type SelectionOpener = (
+  title: string,
+  items: SelectionItem[],
+  opts: { preSelectId?: string; allowSearch?: boolean; primaryVerbLabel?: string } | undefined,
+  callback: (result: SelectionResult | null) => void,
+) => void;
+
+export interface RecoveryPromptDeps {
+  readonly surface: SessionSurface;
+  /** The shell's selection-modal opener. Absent in headless hosts — the flow then does nothing at all. */
+  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.
+   */
+  readonly applySnapshot: (payload: { readonly snapshot: Record<string, unknown>; readonly sessionId: string }) => number;
+  /** One-line honest receipt into the transcript. */
+  readonly receipt: (line: string) => void;
+  readonly render: () => void;
+  /** Injectable for tests. Defaults to the real wall clock. */
+  readonly now?: () => number;
+  /** Injectable for tests. Defaults to statSync on the surface's own recovery file. */
+  readonly snapshotBytes?: (sessionId: string) => number | null;
+  /**
+   * When set, offer THIS session's snapshot specifically (via
+   * `checkRecoveryForSession`) instead of the newest snapshot across every
+   * session (`checkRecoveryFile`). Used by the `--continue` / bare `--resume`
+   * pre-resume check (cli/tui-startup.ts): resuming a named session straight
+   * from its durable store would silently drop the tail of messages held only
+   * in a snapshot newer than that store — the same rule `checkRecoveryFile`
+   * uses, just scoped to the one session being resumed instead of "whichever
+   * session has the newest snapshot".
+   */
+  readonly targetSessionId?: string;
+}
+
+// ─── Honest fact formatting ─────────────────────────────────────────────────
+
+/** Human-readable age of a snapshot. Coarse on purpose — the exact second is not a fact worth claiming. */
+export function formatSnapshotAge(ageMs: number): string {
+  if (ageMs < 0) return 'just now';
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+/** Compact byte size. Only ever called with a size we actually read off disk. */
+export function formatSnapshotSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** Short, fixed modal titles. Kept well inside the narrowest box width so neither is ever truncated. */
+export const RECOVERY_OFFER_TITLE = 'Recovery snapshot found';
+export const RECOVERY_RETIRE_TITLE = 'Remove recovery point?';
+
+/**
+ * The facts line shown in the modal. Only includes what is genuinely known:
+ * the session id and age are always available from `checkRecoveryFile`; the
+ * title appears only when the snapshot carries a non-empty one; the size
+ * appears only when the file could be stat'd.
+ */
+export function describeRecoverySnapshot(
+  info: RecoveryFileInfo,
+  facts: { readonly nowMs: number; readonly bytes: number | null },
+): string {
+  const parts = [`session ${info.sessionId}`, formatSnapshotAge(facts.nowMs - info.timestamp)];
+  if (info.title && info.title.trim()) parts.push(`"${info.title.trim()}"`);
+  if (facts.bytes !== null) parts.push(formatSnapshotSize(facts.bytes));
+  return parts.join(' · ');
+}
+
+/**
+ * The offer modal's rows. The snapshot's facts ride on the Resume row's
+ * `detail` — both because that is where they are decision-relevant ("this is
+ * what you would be loading") and because `detail` is the only field the
+ * selection overlay wraps rather than truncates, so the full description
+ * survives any terminal width.
+ */
+export function buildRecoveryOfferItems(facts: string): SelectionItem[] {
+  return [
+    {
+      id: 'resume',
+      label: 'Resume it',
+      detail: `Loads ${facts} into this session. The recovery point is deleted once it loads.`,
+      primaryAction: 'select',
+    },
+    {
+      id: 'not-now',
+      label: 'Not now',
+      detail: 'Start fresh. You will be asked whether to keep or remove the recovery point.',
+      primaryAction: 'select',
+    },
+  ];
+}
+
+/**
+ * The follow-up modal's rows, shown only after an explicit decline. Restates
+ * which snapshot is at stake.
+ *
+ * Keep comes first, and so is what a blind Enter lands on. This modal is the
+ * one place in the flow where a keypress can destroy a conversation, and it
+ * appears unrequested at boot, so the row under the cursor has to be the one
+ * that costs nothing: pressing Enter without reading leaves the snapshot on
+ * disk to be offered again. Deleting it takes a deliberate move down first.
+ */
+export function buildRecoveryRetireItems(facts: string): SelectionItem[] {
+  return [
+    {
+      id: 'keep',
+      label: 'Keep it',
+      detail: 'Leave the recovery point on disk. It will be offered again the next time this workspace opens.',
+      primaryAction: 'select',
+    },
+    {
+      id: 'remove',
+      label: 'Remove it',
+      detail: `Deletes the recovery point for ${facts}. The conversation it holds cannot be recovered afterwards.`,
+      primaryAction: 'select',
+    },
+  ];
+}
+
+// ─── Flow ───────────────────────────────────────────────────────────────────
+
+function ask(open: SelectionOpener, title: string, items: SelectionItem[]): Promise<string | null> {
+  return new Promise((resolve) => {
+    open(title, items, { allowSearch: false, primaryVerbLabel: 'Choose' }, (result) => {
+      resolve(result?.item.id ?? null);
+    });
+  });
+}
+
+function defaultSnapshotBytes(surface: SessionSurface, sessionId: string): number | null {
+  try {
+    return statSync(surface.recoveryFile(sessionId)).size;
+  } catch {
+    // The snapshot may have come from the SDK's legacy dual-read location,
+    // which this path cannot address. Report no size rather than a wrong one.
+    return null;
+  }
+}
+
+/**
+ * Snapshots the user has already answered about (Keep or dismissal) during
+ * this process's lifetime. Two offer paths exist in one boot — the targeted
+ * pre-resume check for `--continue`/`--resume` and the general startup offer —
+ * and both can find the same snapshot; an answer given to either binds both,
+ * so "stays quiet for the rest of the run" holds across the pair. Resume and
+ * Remove retire the file itself, so only the declined cases need remembering.
+ */
+const answeredThisRun = new Set<string>();
+
+/** Test seam: a fresh process has no answered offers. */
+export function resetAnsweredRecoveryOffersForTest(): void {
+  answeredThisRun.clear();
+}
+
+/**
+ * Run the startup recovery offer. Resolves once the user has answered (or
+ * once it is established that there is nothing to ask about). Never throws:
+ * a failure anywhere in here must not take a boot down.
+ */
+export async function offerRecoverySnapshot(deps: RecoveryPromptDeps): Promise<RecoveryPromptOutcome> {
+  try {
+    const info = deps.targetSessionId !== undefined
+      ? checkRecoveryForSession(deps.surface, deps.targetSessionId)
+      : checkRecoveryFile({ surface: deps.surface });
+    if (!info) return 'none';
+    // Already answered about this snapshot earlier in this same run (the
+    // targeted --continue offer and the general startup offer can both find
+    // it). The earlier answer stands; don't ask twice.
+    if (answeredThisRun.has(info.sessionId)) return 'kept';
+    // Another terminal is actively refreshing this snapshot — it is that
+    // instance's live state, not an orphaned crash.
+    if (checkSessionLiveness(deps.surface, info.sessionId).live) return 'none';
+    const open = deps.openSelection;
+    if (!open) return 'none';
+
+    const nowMs = deps.now?.() ?? Date.now();
+    const bytes = deps.snapshotBytes ? deps.snapshotBytes(info.sessionId) : defaultSnapshotBytes(deps.surface, info.sessionId);
+    const facts = describeRecoverySnapshot(info, { nowMs, bytes });
+
+    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.');
+        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.render();
+      return 'resumed';
+    }
+
+    if (answer !== 'not-now') {
+      // Dismissed rather than answered. Nothing is deleted and nothing is
+      // asked again this run.
+      answeredThisRun.add(info.sessionId);
+      return 'kept';
+    }
+
+    const retire = await ask(open, RECOVERY_RETIRE_TITLE, buildRecoveryRetireItems(facts));
+    if (retire === 'remove') {
+      const { removed } = removeRecoveryPoint(deps.surface, info.sessionId);
+      deps.receipt(removed
+        ? `Recovery point removed (session ${info.sessionId}).`
+        : `No recovery point was found to remove (session ${info.sessionId}).`);
+      deps.render();
+      return 'removed';
+    }
+
+    answeredThisRun.add(info.sessionId);
+    deps.receipt(`Recovery point kept (session ${info.sessionId}) — it will be offered again next launch.`);
+    deps.render();
+    return 'kept';
+  } catch {
+    // Best-effort by construction: a recovery offer that fails must leave the
+    // snapshot untouched and the boot unharmed.
+    return 'none';
+  }
+}
+
+// ─── Startup wiring ─────────────────────────────────────────────────────────
+
+/**
+ * Raise the recovery offer once the shell is up.
+ *
+ * Deliberately fire-and-forget and deliberately AFTER the first render: the
+ * modal is drawn by the render loop, so asking before a frame exists would
+ * mean a question nobody can see, and awaiting it would hold the terminal
+ * blank while the user was expected to answer. Scheduled on a macrotask so
+ * the caller's own initial render has completed first.
+ *
+ * Every failure mode here ends with the snapshot untouched: `offerRecoverySnapshot`
+ * swallows its own errors, and this wrapper adds a catch for the scheduling
+ * boundary.
+ */
+export function scheduleRecoveryOffer(deps: RecoveryPromptDeps): void {
+  setTimeout(() => {
+    void offerRecoverySnapshot(deps).catch(() => {
+      // Best-effort: a failed offer must never take the shell down.
+    });
+  }, 0).unref?.();
+}

package/src/runtime/resume-notice.ts

@@ -10,13 +10,16 @@
  * what real state exists and how to reach it.
  *
  * Honesty constraints (verified against the actual runtime, not assumed):
- *   - There is no bare `/resume` command and no `/sessions` command (a
- *     pre-existing typo already lives in the splash's own hint at
- *     utils/splash-lines.ts — out of scope here, splash stays byte-identical).
- *     The real, working command is `/session resume <id|name>` — it always
- *     requires an explicit target. So this notice advertises
- *     `/session resume <id>` with the real last-session id substituted in,
- *     never a bare `/resume`.
+ *   - `/resume` and `/sessions` both exist and both work: `/resume`
+ *     (session.ts) opens a zero-typing picker over saved sessions when
+ *     called bare, and resumes directly when given an id/name; `/sessions`
+ *     (session-content.ts) forwards a `resume <id>` subcommand to the same
+ *     `/session resume` path. All three spellings — `/resume <id>`,
+ *     `/session resume <id>`, `/sessions resume <id>` — reach the identical
+ *     resume routine. This notice leads with the zero-typing picker
+ *     (`/resume`) and keeps the direct, exact-id form (`/session resume
+ *     <id>`) as a secondary hint, for the case of already knowing which
+ *     session to reach for.
  *   - `/checkpoints` works with zero arguments and behaves correctly at any
  *     checkpoint count (including zero) — advertised whenever the checkpoint
  *     manager is available in this session.
@@ -27,19 +30,15 @@
  *   - Every clause is independently gated on real data: a claim about
  *     checkpoints/chain history is only made when that data is known; "no
  *     chain history" means no chain clause is printed, not a fabricated one.
- *   - A live recovery snapshot (the SDK's checkRecoveryFile — a separate
- *     on-disk file from the session store, written every 60s while a session
- *     runs) is reported whenever one exists, but the specific
- *     `/session resume <id>` restore command is only advertised when that
- *     exact session id is ALSO loadable through the session manager
- *     (verified with a real load attempt, not assumed). A snapshot whose
- *     session never completed a full turn has no working command that
- *     reaches it yet — reported honestly without one, rather than
- *     advertising a command that would fail. This module never auto-applies
- *     the snapshot itself; restoring it is always the user's explicit call.
+ *   - A live crash-recovery snapshot is NOT this notice's business any more.
+ *     It used to get a clause here, which meant an operator's only route back
+ *     to a crashed session was reading a sentence and retyping a command. It
+ *     is now an explicit ask-then-retire modal raised right after first
+ *     render — see runtime/recovery-prompt.ts. Keeping a passive clause here
+ *     as well would announce the same snapshot twice.
  */
 
-import { checkRecoveryFile, readLastSessionPointer } from '@/runtime/index.ts';
+import { readLastSessionPointer, type SessionSurface } from '@/runtime/index.ts';
 import type { WrfcChain } from '@pellux/goodvibes-sdk/platform/agents';
 import type { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
 import type { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
@@ -100,19 +99,6 @@ export interface ResumeNoticeFacts {
   readonly lastChainOutcome: ChainOutcome | null;
   /** Whether /recall (memory) is wired up in this session. */
   readonly memoryAvailable: boolean;
-  /**
-   * A live recovery snapshot on disk (newer than the last clean save), if
-   * any — the SDK's checkRecoveryFile, written periodically while a session
-   * runs and left behind by one that never reached a clean save (a crash is
-   * one cause; a second TUI still running in the same workspace is another —
-   * this module has no liveness check, so it never claims a crash happened,
-   * only that a snapshot exists). `resumable` is true only when that exact
-   * session id is also loadable through the session manager, i.e.
-   * `/session resume <id>` genuinely reaches it; false means the snapshot
-   * exists but nothing reaches it yet (e.g. a crash during its very first
-   * turn, before any full save). Null when there is no live snapshot at all.
-   */
-  readonly recoverySnapshot: { readonly sessionId: string; readonly resumable: boolean } | null;
 }
 
 function plural(n: number, word: string): string {
@@ -130,10 +116,8 @@ export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
   const checkpointCount = facts.checkpointCount ?? 0;
   const hasCheckpoints = checkpointsKnown && checkpointCount > 0;
   const hasChainHistory = facts.lastChainOutcome !== null;
-  const recovery = facts.recoverySnapshot;
-  const hasRecovery = recovery !== null;
 
-  if (!hasSession && !hasCheckpoints && !hasChainHistory && !hasRecovery) return null;
+  if (!hasSession && !hasCheckpoints && !hasChainHistory) return null;
 
   const summary: string[] = [];
   if (hasSession) summary.push(plural(facts.turnCount!, 'turn'));
@@ -142,24 +126,16 @@ export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
   // without one) — never guessed when the manager is unavailable.
   if (checkpointsKnown && (hasSession || hasCheckpoints)) summary.push(plural(checkpointCount, 'checkpoint'));
   if (hasChainHistory) summary.push(`last chain: ${facts.lastChainOutcome}`);
-  // Reported whenever a live snapshot exists, independent of whether a
-  // restore command can be advertised for it (see the hint below).
-  if (hasRecovery) summary.push('recovery snapshot found');
 
   const lead = hasSession ? 'Previous session found' : 'Workspace history found';
   let notice = `${lead}: ${summary.join(', ')}`;
 
   const hints: string[] = [];
-  // No bare `/resume` exists — /session resume always requires a target.
-  if (hasSession) hints.push(`/session resume ${facts.lastSessionId} to continue`);
+  // Lead with the zero-typing picker (/resume), keep the direct exact-id
+  // form as a secondary hint — see the header doc for why both are honest.
+  if (hasSession) hints.push(`/resume to continue (or /session resume ${facts.lastSessionId} directly)`);
   if (hasCheckpoints) hints.push('/checkpoints to browse');
   if (facts.memoryAvailable) hints.push('/recall for memory');
-  // Only advertise the recovery snapshot's restore command when it is
-  // verified-resumable AND names a session other than the one already
-  // hinted above — otherwise this would just repeat the same command.
-  if (hasRecovery && recovery!.resumable && recovery!.sessionId !== facts.lastSessionId) {
-    hints.push(`/session resume ${recovery!.sessionId} to restore it`);
-  }
   if (hints.length > 0) notice += ` — ${hints.join(' · ')}`;
 
   return notice;
@@ -168,10 +144,8 @@ export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
 // ─── Fact gathering (I/O) ────────────────────────────────────────────────────
 
 export interface ResumeNoticeDeps {
-  readonly workingDirectory: string;
-  readonly homeDirectory: string;
-  /** Surface root used by session persistence — the TUI always uses 'tui'. */
-  readonly surfaceRoot: string;
+  /** The app's declare-once session-storage handle — the same one the runtime writes the pointer through. */
+  readonly surface: SessionSurface;
   /** Only `load()` is needed — kept narrow for testability. */
   readonly sessionManager: Pick<SessionManager, 'load'>;
   /** Undefined when checkpoints are not wired up in this session at all. Only `list()` is needed. */
@@ -191,12 +165,8 @@ export interface ResumeNoticeDeps {
  * session file is missing/corrupt — never a claim about a session that
  * cannot actually be resumed.
  */
-function readLastSessionTurns(deps: Pick<ResumeNoticeDeps, 'workingDirectory' | 'homeDirectory' | 'surfaceRoot' | 'sessionManager'>): { turnCount: number; lastSessionId: string } | null {
-  const lastSessionId = readLastSessionPointer({
-    workingDirectory: deps.workingDirectory,
-    homeDirectory: deps.homeDirectory,
-    surfaceRoot: deps.surfaceRoot,
-  });
+function readLastSessionTurns(deps: Pick<ResumeNoticeDeps, 'surface' | 'sessionManager'>): { turnCount: number; lastSessionId: string } | null {
+  const lastSessionId = readLastSessionPointer({ surface: deps.surface });
   if (!lastSessionId) return null;
   try {
     const { messages } = deps.sessionManager.load(lastSessionId);
@@ -209,36 +179,6 @@ function readLastSessionTurns(deps: Pick<ResumeNoticeDeps, 'workingDirectory' |
   }
 }
 
-/**
- * Whether a live recovery snapshot exists, and whether its exact
- * session id is also resumable through the real `/session resume <id>` path.
- * A real load attempt (not a guess) decides resumability: `sessionManager`
- * and `checkRecoveryFile`'s recovery directory are genuinely separate
- * on-disk stores (see resume-notice.ts's header doc), so a snapshot whose
- * session never completed a full turn will not be in the session store yet.
- * Returns null when there is no live snapshot at all.
- */
-function readRecoverySnapshot(
-  deps: Pick<ResumeNoticeDeps, 'workingDirectory' | 'homeDirectory' | 'sessionManager'>,
-): { sessionId: string; resumable: boolean } | null {
-  // No surfaceRoot: the recovery file lives in the SHARED .goodvibes/recovery
-  // directory, the same way main.ts's writeRecoveryFile call and the SDK's
-  // own getContinuitySnapshot() read it — unlike the session store /
-  // last-session pointer above, which IS scoped to surfaceRoot 'tui'.
-  const info = checkRecoveryFile({
-    workingDirectory: deps.workingDirectory,
-    homeDirectory: deps.homeDirectory,
-  });
-  if (!info) return null;
-  let resumable = true;
-  try {
-    deps.sessionManager.load(info.sessionId);
-  } catch {
-    resumable = false;
-  }
-  return { sessionId: info.sessionId, resumable };
-}
-
 async function readCheckpointCount(mgr: ResumeNoticeDeps['checkpointManager']): Promise<number | null> {
   if (!mgr) return null;
   try {
@@ -253,18 +193,14 @@ async function readCheckpointCount(mgr: ResumeNoticeDeps['checkpointManager']):
 /**
  * Gather real facts from disk/services and, if there is anything to report,
  * print ONE compact system message via `deps.router.high`. No-op (and no
- * message) when there is no prior session, no checkpoints, no chain history,
- * and no live recovery snapshot — a fresh working directory stays
- * quiet. This is the ONLY thing a live recovery snapshot does at
- * startup: it never mutates the conversation, never touches the journal, and
- * never deletes the snapshot file — restoring it is always the user's
- * explicit call (via the advertised /session resume <id>, when one exists).
+ * message) when there is no prior session, no checkpoints, and no chain
+ * history — a fresh working directory stays quiet. Nothing here ever mutates
+ * the conversation: this is a report, not a restore.
  */
 export async function announceResumeState(deps: ResumeNoticeDeps): Promise<void> {
   const session = readLastSessionTurns(deps);
   const checkpointCount = await readCheckpointCount(deps.checkpointManager);
   const lastChain = mostRecentChain(deps.chainHistory);
-  const recoverySnapshot = readRecoverySnapshot(deps);
 
   const notice = buildResumeNotice({
     turnCount: session?.turnCount ?? null,
@@ -272,7 +208,6 @@ export async function announceResumeState(deps: ResumeNoticeDeps): Promise<void>
     checkpointCount,
     lastChainOutcome: lastChain ? describeChainOutcome(lastChain) : null,
     memoryAvailable: deps.memoryAvailable,
-    recoverySnapshot,
   });
 
   if (notice) deps.router.high(notice);

package/src/runtime/services.ts

@@ -37,7 +37,9 @@ import {
   type RuntimeEventBus, DistributedRuntimeManager, RemoteRunnerRegistry, RemoteSupervisor, IntegrationHelperService,
   IdempotencyStore, ComponentHealthMonitor, WorktreeRegistry, SandboxSessionRegistry, createShellPathService,
   type ShellPathService, type FeatureFlagManager, createFeatureFlagManager, PolicyRuntimeState,
+  type SessionSurface,
 } from '@/runtime/index.ts';
+import { createSessionStorageServices } from './session-storage-services.ts';
 import { VoiceProviderRegistry, VoiceService, ensureBuiltinVoiceProviders } from '@pellux/goodvibes-sdk/platform/voice';
 import { CacheRegistry, PauseController, type MemoryGovernor } from '@pellux/goodvibes-sdk/platform/runtime/memory';
 import { wireMemoryGovernance } from './memory-governance-services.ts';
@@ -63,7 +65,7 @@ import { type ArchivableProcessRegistry } from '@pellux/goodvibes-sdk/platform/r
 import { createFleetServices } from './fleet-services.ts';
 import { createWorkstreamServices, type OrchestrationEngine, type WorkstreamCommandService } from './workstream-services.ts';
 import { wireFleetNeedsInputPush } from './fleet-needs-input-push.ts';
-import { codeIndexDbPath, createCodeIndexServices, isCodeInjectionSettingEnabled } from './code-index-services.ts';
+import { codeIndexDbPath, createCodeIndexServices, createStoreRerooter, isCodeInjectionSettingEnabled } from './code-index-services.ts';
 import type { WorkPlanStore } from '../work-plans/work-plan-store.ts';
 import { registerDaemonHandlers, type DaemonHandlerSurfaces } from '../daemon/handlers/index.ts';
 import type { HandlerContext, HandlerLogger } from '../daemon/handlers/context.ts';
@@ -99,6 +101,8 @@ export interface RuntimeServicesOptions {
 export interface RuntimeServices {
   readonly workingDirectory: string;
   readonly homeDirectory: string;
+  /** The declare-once session-storage handle every session reader and writer threads through — see session-storage-services.ts. */
+  readonly surface: SessionSurface;
   readonly shellPaths: ShellPathService;
   readonly configManager: ConfigManager;
   readonly featureFlags: FeatureFlagManager;
@@ -231,6 +235,8 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     workingDirectory,
     homeDirectory,
   });
+  // Built before anything that touches session state — see session-storage-services.ts.
+  const { surface, sessionManager } = createSessionStorageServices({ workingDirectory, homeDirectory });
   const workspaceTrustManager = new WorkspaceTrustManager({ shellPaths });
   const configManager = options.configManager;
   const featureFlags = options.featureFlags ?? createFeatureFlagManager();
@@ -318,9 +324,8 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   });
   const profileManager = new ProfileManager(shellPaths.resolveUserPath('tui', 'profiles'));
   const bookmarkManager = new BookmarkManager(shellPaths.resolveUserPath('tui', 'bookmarks'));
-  const sessionManager = new SessionManager(workingDirectory, { surfaceRoot: 'tui' });
   const sessionOrchestration = new CrossSessionTaskRegistry(
-    shellPaths.resolveProjectPath('tui', 'sessions', 'task-graph.json'),
+    join(surface.sessionsDir, 'task-graph.json'),
   );
   const hookActivityTracker = new HookActivityTracker();
   const watcherRegistry = new WatcherRegistry({
@@ -564,7 +569,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // Store snapshots + durable remembered-approval rules + the live credential
   // chain, mirroring the SDK composition — see durability-services.ts.
   const { storeSnapshotScheduler, userPermissionRuleStore } = createDurabilityServices({
-    configManager, secretsManager, providerRegistry, memoryDbPath, codeIndexDbPath: codeIndexDbPath(workingDirectory), workingDirectory, surfaceRoot: 'tui', homeDirectory, shellPaths, // + retention-sweep roots & live config watch (mirrors the SDK)
+    configManager, secretsManager, providerRegistry, memoryDbPath, codeIndexDbPath: codeIndexDbPath(workingDirectory), surface, shellPaths, // + retention-sweep roots & live config watch (mirrors the SDK)
   });
   const codeInjectionOrchestratorDeps = { codeIndex: codeIndexStore, isCodeInjectionSettingEnabled: () => isCodeInjectionSettingEnabled(configManager), codeIndexReindexScheduler }; // Code-injection seam (agent here; main via orchestrator-core-services.ts)
   const { processRegistry } = createFleetServices({ // Shared archive-aware fleet registry (+ daemon observed rows) — see fleet-services.ts
@@ -578,7 +583,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     observeExternalAgents: options.observeExternalAgents, providerRegistry, // observeExternalAgents is daemon-side only
   });
   const modeManager = new ModeManager(); const fileUndoManager = new FileUndoManager();
-  const workspaceCheckpointManager = createWorkspaceCheckpointing({ workspaceRoot: workingDirectory, runtimeBus: options.runtimeBus, configManager });
+  const workspaceCheckpointManager = createWorkspaceCheckpointing({ workspaceRoot: workingDirectory, surface, runtimeBus: options.runtimeBus, configManager });
   // memory-consolidation honors governor backpressure: it ticks only when idle
   // AND the 'memory-consolidation' job is not paused AND expensive work is
   // admitted (mirrors the SDK's own createRuntimeServices idle gate).
@@ -610,8 +615,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // Terminal-shell wrapper over the SDK registerGatewayVerbGroups (gateway-verbs.ts); checkin.*/fleet-needs-input/pairing.* register only when their deps are present. memoryGovernor lights up ops.memory.get; voiceSetup lights up voice.local.status/install.
   attachWsOnlyGatewayVerbHandlers(gatewayMethods, { processRegistry, workspaceCheckpointManager, conversationRewindPort: createSessionConversationRewindPort(), sessionBroker, secretsManager, stepUpService, approvalBroker, requestApproval: (input) => approvalBroker.requestApproval(input), watcherRegistry, userPermissionRuleStore, shellPaths, configManager, runtimeStore: options.runtimeStore, channelDeliveryRouter, providerRegistry, automationManager, sessionLister: sessionBroker, sessionIntake: sessionBroker, workingDirectory, memoryRegistry, pairingTokens, sessionLiveTurnControls, powerManager, memoryGovernor, voiceSetup, relayAvailable: () => configManager.get('relay.enabled') === true, pairingWebOrigin: () => resolvePairingWebOrigin(configManager).origin, ...wireFleetNeedsInputPush({ registry: processRegistry, runtimeBus: options.runtimeBus, sessionBroker }) });
   const integrationHelpers = new IntegrationHelperService({
-    workingDirectory,
-    homeDirectory,
+    surface, // surface-scoped: continuity's recovery-file check must read the SAME paths the app writes with, not the unscoped legacy pair.
     runtimeStore: options.runtimeStore,
     runtimeBus: options.runtimeBus,
     configManager,
@@ -636,7 +640,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // Exec stuck on a terminal prompt rides the approval broker; the typed answer feeds the continuing run. Built once and shared (like localhostFetchApproval) so the tool registry AND every setDependencies site — incl. the post-clobber rewire in bootstrap-core — install the SAME handler; otherwise a wholesale replace drops it and interactive prompts hang.
   const execPromptAnswerHandler = buildExecPromptAnswerHandler({ requestApproval: (input) => approvalBroker.requestApproval(input) });
   agentOrchestrator.setDependencies({
-    surfaceRoot: 'tui',
+    surfaceRoot: surface.surfaceRoot,
     execPromptAnswerHandler,
     localhostFetchApproval,
     fileCache,
@@ -678,6 +682,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   return {
     workingDirectory,
     homeDirectory,
+    surface,
     shellPaths,
     workspaceTrustManager,
     configManager,
@@ -785,13 +790,6 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     fileUndoManager,
     workspaceCheckpointManager,
     integrationHelpers,
-    async rerootStores(newWorkingDir: string): Promise<void> {
-      // The memory store is the home-scoped canonical cross-surface store and
-      // deliberately does NOT reroot per-project (that would re-silo memory back
-      // into per-project stores). Only working-tree-bound stores (code index,
-      // project index) reroot.
-      await codeIndexStore.reroot(newWorkingDir, codeIndexDbPath(newWorkingDir));
-      await projectIndex.reroot(newWorkingDir);
-    },
+    rerootStores: createStoreRerooter({ codeIndexStore, projectIndex }),
   };
 }