@pellux/goodvibes-tui 1.19.5 → 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,9 +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 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 { 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';
@@ -122,8 +131,9 @@ export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
   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');
   if (hints.length > 0) notice += ` — ${hints.join(' · ')}`;
@@ -134,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. */
@@ -157,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);
@@ -190,7 +194,8 @@ 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, and no chain
- * history — a fresh working directory stays quiet.
+ * 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);

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 }),
   };
 }

package/src/runtime/session-liveness-marker.ts

@@ -0,0 +1,120 @@
+/**
+ * session-liveness-marker.ts — best-effort "this session is open in another
+ * terminal" signal for multi-instance safety.
+ *
+ * Two independent TUI instances resuming or writing recovery snapshots for
+ * the SAME session can silently step on each other: one instance's periodic
+ * recovery write looks, to a second instance, indistinguishable from a
+ * genuine crash snapshot, and resuming a session another instance still has
+ * open forks its live state without warning.
+ *
+ * This module writes a small marker file (session id + pid), refreshed on
+ * the SAME 60s cadence as the existing recovery-file write (main.ts), so a
+ * second instance can do a best-effort liveness check before either warning
+ * about a stale-looking recovery snapshot or resuming a live session out
+ * from under its owner.
+ *
+ * Every check here is best-effort by design: a missing or stale marker never
+ * blocks anything — it just means "we can't tell, proceed as before". This is
+ * a convenience signal, not a lock.
+ *
+ * Location: <homeDirectory>/.goodvibes/<surfaceRoot>/liveness/<sessionId>.json.
+ * Both halves come off the caller's SessionSurface rather than being spelled
+ * out here, so the markers land under the same scope as the sessions and
+ * recovery snapshots they describe — mirrors the transcript-journal.ts
+ * convention (homeDirectory-scoped, under the surface's own directory).
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { SessionSurface } from '@/runtime/index.ts';
+
+export interface LivenessMarker {
+  readonly sessionId: string;
+  readonly pid: number;
+  readonly updatedAt: number;
+}
+
+/**
+ * A marker older than this is treated as stale even if its pid happens to
+ * still resolve to a running process (pid reuse after a crash) — the marker
+ * is refreshed every 60s (main.ts's recovery cadence), so anything past
+ * ~2.5x that cadence means the writer stopped refreshing it.
+ */
+export const LIVENESS_STALE_AFTER_MS = 150_000;
+
+/** Absolute path to a session's liveness marker file. */
+export function livenessMarkerPathFor(surface: SessionSurface, sessionId: string): string {
+  return join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot, 'liveness', `${sessionId}.json`);
+}
+
+/** Refresh (creating if needed) the liveness marker for this session/pid. Best-effort — never throws. */
+export function writeLivenessMarker(surface: SessionSurface, sessionId: string, pid: number = process.pid): void {
+  try {
+    const path = livenessMarkerPathFor(surface, sessionId);
+    mkdirSync(dirname(path), { recursive: true });
+    const marker: LivenessMarker = { sessionId, pid, updatedAt: Date.now() };
+    writeFileSync(path, JSON.stringify(marker), { mode: 0o600 });
+  } catch {
+    // Best-effort — a missed liveness refresh never blocks anything.
+  }
+}
+
+/** Best-effort removal on exit. Never throws. */
+export function removeLivenessMarker(surface: SessionSurface, sessionId: string): void {
+  try {
+    const path = livenessMarkerPathFor(surface, sessionId);
+    if (existsSync(path)) unlinkSync(path);
+  } catch {
+    // Best-effort.
+  }
+}
+
+function readLivenessMarker(surface: SessionSurface, sessionId: string): LivenessMarker | null {
+  try {
+    const path = livenessMarkerPathFor(surface, sessionId);
+    if (!existsSync(path)) return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<LivenessMarker>;
+    if (typeof parsed.sessionId !== 'string' || typeof parsed.pid !== 'number' || typeof parsed.updatedAt !== 'number') return null;
+    return { sessionId: parsed.sessionId, pid: parsed.pid, updatedAt: parsed.updatedAt };
+  } catch {
+    return null;
+  }
+}
+
+/** Best-effort check that a pid still refers to a running process. Injectable for tests. */
+export function isPidAlive(pid: number, kill: (pid: number, signal: 0) => void = process.kill.bind(process)): boolean {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH = no such process. Any other error (e.g. EPERM — exists but this
+    // process lacks permission to signal it) is treated as "still alive" —
+    // best-effort here means erring toward not silently dropping a real warning.
+    return (err as NodeJS.ErrnoException | undefined)?.code === 'EPERM';
+  }
+}
+
+export interface SessionLivenessCheck {
+  readonly live: boolean;
+  readonly pid: number | null;
+}
+
+/**
+ * Best-effort: is `sessionId` apparently open in another still-running
+ * process right now? A missing, stale (older than LIVENESS_STALE_AFTER_MS),
+ * or unreadable marker all resolve to `{ live: false, pid: null }` — never a
+ * throw, never a block on the caller.
+ */
+export function checkSessionLiveness(
+  surface: SessionSurface,
+  sessionId: string,
+  opts: { readonly now?: () => number; readonly isPidAliveFn?: typeof isPidAlive } = {},
+): SessionLivenessCheck {
+  const marker = readLivenessMarker(surface, sessionId);
+  if (!marker) return { live: false, pid: null };
+  const now = opts.now?.() ?? Date.now();
+  if (now - marker.updatedAt > LIVENESS_STALE_AFTER_MS) return { live: false, pid: null };
+  const aliveCheck = opts.isPidAliveFn ?? isPidAlive;
+  if (!aliveCheck(marker.pid)) return { live: false, pid: null };
+  return { live: true, pid: marker.pid };
+}

package/src/runtime/session-pointer-surface.ts

@@ -0,0 +1,22 @@
+import { writeLastSessionPointer } from '@/runtime/index.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
+
+/**
+ * Binds the SDK's two-argument `writeLastSessionPointer(sessionId, options?)`
+ * to one `SessionSurface`, returning a plain `(sessionId: string) => void`.
+ *
+ * Never pass the raw SDK function reference into a `(sessionId: string) =>
+ * void` slot. A function with an extra optional parameter is structurally
+ * assignable there, so it type-checks, but every downstream caller
+ * (bootstrap-shell.ts -> bootstrap-hook-bridge.ts's resume handler) invokes
+ * it with exactly one argument: `options` arrives as `undefined`, the legacy
+ * compat path's `requireWorkingDirectory(undefined)` throws, and
+ * `writeLastSessionPointer`'s own try/catch swallows that into a logged
+ * warning. The pointer file then silently never gets written after a resume,
+ * and the next launch's `--continue` / boot notice sees nothing. That was the
+ * live defect at bootstrap.ts's `createBootstrapShell({ writeLastSessionPointer })`
+ * call. See session-surface-pointer-journey.test.ts for the on-disk proof.
+ */
+export function bindWriteLastSessionPointerToSurface(surface: SessionSurface): (sessionId: string) => void {
+  return (sessionId: string): void => writeLastSessionPointer(sessionId, { surface });
+}