@pellux/goodvibes-tui 1.19.6 → 1.20.1

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

package/src/runtime/session-resume-liveness-confirm.ts

@@ -0,0 +1,84 @@
+/**
+ * session-resume-liveness-confirm.ts — the "this session is open somewhere
+ * else" check for the session-browser / panel resume seam.
+ *
+ * `/session resume <id>` already refuses to resume a session whose liveness
+ * marker points at another running process, and tells the operator to re-run
+ * with `--force`. The panel seam had no such check at all: picking a session
+ * from the browser forked another terminal's live state with no warning. That
+ * seam has no argv to carry a `--force`, so it asks the same question as a
+ * modal instead.
+ *
+ * Semantics are unchanged from the text-command check and stay best-effort: a
+ * missing, stale, or unreadable marker means "we can't tell", and the resume
+ * proceeds exactly as it always did. The marker belonging to THIS process is
+ * ignored too — re-resuming the session already open here is not a fork.
+ */
+import { checkSessionLiveness } from './session-liveness-marker.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
+import type { SelectionItem, SelectionResult } from '../input/selection-modal.ts';
+
+export type LiveResumeSelectionOpener = (
+  title: string,
+  items: SelectionItem[],
+  opts: { preSelectId?: string; allowSearch?: boolean; primaryVerbLabel?: string } | undefined,
+  callback: (result: SelectionResult | null) => void,
+) => void;
+
+/**
+ * The confirm modal's title. Short by necessity: the selection overlay
+ * truncates its title to the box width (selection-modal-overlay.ts), so
+ * anything the operator must actually read — the pid, and what resuming would
+ * do — belongs in a row's `detail`, which that overlay wraps instead.
+ */
+export const LIVE_RESUME_CONFIRM_TITLE = 'Session open elsewhere';
+
+export function buildLiveResumeConfirmItems(pid: number): SelectionItem[] {
+  return [
+    {
+      id: 'resume',
+      label: 'Resume anyway',
+      detail: `This session appears open in another terminal (pid ${pid}); resuming will fork its live state. Both terminals would hold their own copy of the conversation from this point on.`,
+      primaryAction: 'select',
+    },
+    {
+      id: 'cancel',
+      label: 'Cancel',
+      detail: 'Leave the session to the terminal that already has it open.',
+      primaryAction: 'select',
+    },
+  ];
+}
+
+export interface ConfirmLiveResumeDeps {
+  readonly surface: SessionSurface;
+  /** Late-bound: the shell builds its selection opener after the resume handler exists. */
+  readonly openSelection: () => LiveResumeSelectionOpener | undefined;
+  /** Injectable for tests; defaults to this process's own pid. */
+  readonly selfPid?: number;
+}
+
+/**
+ * Resolve true when the resume should proceed. Proceeds without asking
+ * whenever the liveness signal says there is nothing to warn about, or when
+ * no selection surface exists to ask through (headless hosts keep the
+ * pre-existing behavior rather than silently refusing).
+ *
+ * A dismissed modal resolves false: the safe answer to an unanswered "should
+ * I fork another terminal's state?" is no.
+ */
+export async function confirmLiveResume(sessionId: string, deps: ConfirmLiveResumeDeps): Promise<boolean> {
+  const selfPid = deps.selfPid ?? process.pid;
+  const liveness = checkSessionLiveness(deps.surface, sessionId);
+  if (!liveness.live || liveness.pid === null || liveness.pid === selfPid) return true;
+  const open = deps.openSelection();
+  if (!open) return true;
+  return new Promise<boolean>((resolve) => {
+    open(
+      LIVE_RESUME_CONFIRM_TITLE,
+      buildLiveResumeConfirmItems(liveness.pid!),
+      { allowSearch: false, primaryVerbLabel: 'Choose' },
+      (result) => resolve(result?.item.id === 'resume'),
+    );
+  });
+}

package/src/runtime/session-storage-services.ts

@@ -0,0 +1,41 @@
+/**
+ * session-storage-services.ts — the declare-once storage handle and the
+ * session store built on it.
+ *
+ * Every path the app uses for session state (the sessions directory, the
+ * last-session pointer, crash-recovery snapshots, the checkpoint store, the
+ * transcript journal, the multi-instance liveness markers) derives from ONE
+ * `SessionSurface`, built here, once, at composition time.
+ *
+ * The reason it is one object rather than a scope argument repeated at each
+ * call site: when each site derived its own scope, they drifted. A resume
+ * wrote the last-session pointer with no scope at all — into the shared,
+ * unscoped `.goodvibes/` directory — while `--continue` and the boot notice
+ * read a scoped path under `.goodvibes/tui/`. Nothing errored; the pointer
+ * simply never existed where anyone looked. `createSessionSurface` also
+ * throws synchronously on a bad scope instead of silently resolving to the
+ * unscoped fallback on first use, so a mistake here fails at boot rather than
+ * six months later as missing state.
+ */
+import { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
+import { createSessionSurface, type SessionSurface } from '@/runtime/index.ts';
+import { GOODVIBES_TUI_SURFACE_ROOT } from '../config/surface.ts';
+
+export interface SessionStorageServices {
+  readonly surface: SessionSurface;
+  readonly sessionManager: SessionManager;
+}
+
+export function createSessionStorageServices(input: {
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+}): SessionStorageServices {
+  // Also performs the SDK's one-time migration of pre-surface state (pointer
+  // copy-forward, journal moves) into the scoped location.
+  const surface = createSessionSurface({
+    surfaceRoot: GOODVIBES_TUI_SURFACE_ROOT,
+    workingDirectory: input.workingDirectory,
+    homeDirectory: input.homeDirectory,
+  });
+  return { surface, sessionManager: new SessionManager(input.workingDirectory, { surface }) };
+}

package/src/runtime/workspace-checkpointing.ts

@@ -1,7 +1,7 @@
 import { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
 import { withCheckpointGuardSettings } from '../config/tui-extension-settings.ts';
 import type { ConfigManager } from '../config/index.ts';
-import type { RuntimeEventBus } from '@/runtime/index.ts';
+import type { RuntimeEventBus, SessionSurface } from '@/runtime/index.ts';
 
 /**
  * createWorkspaceCheckpointing — build the per-workspace checkpoint manager and
@@ -10,13 +10,21 @@ import type { RuntimeEventBus } from '@/runtime/index.ts';
  */
 export function createWorkspaceCheckpointing(opts: {
   workspaceRoot: string;
+  /**
+   * The app's declare-once storage handle. Passing it resolves the checkpoint
+   * git store to `surface.checkpointsDir` (`<workingDirectory>/.goodvibes/tui/
+   * checkpoints`) instead of the unscoped `<workspaceRoot>/.goodvibes/
+   * checkpoints` every product using this SDK would otherwise share. The SDK
+   * migrates an existing legacy store into the scoped location on first use.
+   */
+  surface: SessionSurface;
   runtimeBus: RuntimeEventBus;
   configManager: ConfigManager;
 }): WorkspaceCheckpointManager {
   // Checkpoint root-guard from the user's `checkpoints.*` config (docs/configuration.md;
   // inert until the platform SDK's checkpoint manager exposes the keys — see the reader's note).
   const manager = new WorkspaceCheckpointManager(
-    withCheckpointGuardSettings({ workspaceRoot: opts.workspaceRoot, runtimeBus: opts.runtimeBus }, opts.configManager),
+    withCheckpointGuardSettings({ workspaceRoot: opts.workspaceRoot, surface: opts.surface, runtimeBus: opts.runtimeBus }, opts.configManager),
   );
   // Fire-and-forget: subscriptions go live immediately if init() succeeds.
   // If it rejects, WorkspaceCheckpointManager caches that rejection on

package/src/shell/recovery-input-helpers.ts

@@ -24,11 +24,15 @@ export interface ErrorAffordanceDeps {
 /**
  * Handle one keypress while the error-retry affordance is active.
  * 'r' retries on the current provider when armed; 'm' opens the model
- * picker. Returns true when the key was consumed; any other key returns
- * false so the caller routes it as normal input.
+ * picker — also gated on armed, since switching models here only makes
+ * sense in service of the same retry this affordance is offering, not as a
+ * general-purpose model-picker shortcut. Returns true when the key was
+ * consumed; any other key (or 'm'/'r' while unarmed) returns false so the
+ * caller routes it as normal input.
  */
 export function handleErrorAffordanceKey(data: string, deps: ErrorAffordanceDeps): boolean {
-  if (data === 'r' && deps.retryArmed) {
+  if (!deps.retryArmed) return false;
+  if (data === 'r') {
     deps.retry();
     deps.render();
     return true;

package/src/shell/retry-affordance.ts

@@ -0,0 +1,123 @@
+/**
+ * retry-affordance.ts — the one-key retry/switch-model affordance shown
+ * right after a user-visible TURN_ERROR: 'r' re-submits on the current
+ * provider, 'm' opens the model picker, any other key disarms it silently.
+ *
+ * Rendered as a transient FOOTER status line (see retryAffordanceHint,
+ * wired into ShellFooterBuildOptions.retryHint in shell-surface.ts) rather
+ * than a permanent transcript message — it disappears the moment it's
+ * disarmed, instead of sitting in the scrollback claiming an affordance
+ * that no longer does anything. Extracted from main.ts to keep the
+ * entrypoint under the architecture line cap.
+ *
+ * The affordance is also time-bounded: arming starts a disarm timer so a
+ * stray 'r' hours later can never fire a real, paid retry against the
+ * provider. The timer's window is exactly what the footer hint's visibility
+ * implies — when it fires, the state disarms AND retryAffordanceHint(state)
+ * goes back to null in the same tick, so the key dies at the same moment
+ * the hint disappears.
+ */
+
+/** How long the affordance stays armed with no keypress before it silently expires. */
+export const RETRY_AFFORDANCE_WINDOW_MS = 60_000;
+
+/** Timer primitives injectable for tests, so arming doesn't require a real 60s wait. */
+export interface RetryAffordanceSchedule {
+  readonly setTimeout: (cb: () => void, ms: number) => ReturnType<typeof setTimeout>;
+  readonly clearTimeout: (handle: ReturnType<typeof setTimeout>) => void;
+}
+
+const REAL_SCHEDULE: RetryAffordanceSchedule = {
+  setTimeout: (cb, ms) => setTimeout(cb, ms),
+  clearTimeout: (handle) => clearTimeout(handle),
+};
+
+export interface RetryAffordanceState {
+  armed: boolean;
+  exhausted: boolean;
+  /** Internal: the pending disarm timer's handle, or null while unarmed. */
+  timer: ReturnType<typeof setTimeout> | null;
+  /** Internal: injected timer primitives — real setTimeout/clearTimeout in production. */
+  readonly schedule: RetryAffordanceSchedule;
+  /** Internal: the disarm window in ms. */
+  readonly windowMs: number;
+  /** Internal: invoked after the timer disarms the state, so the render loop can repaint the footer. */
+  readonly onExpire?: () => void;
+}
+
+export interface CreateRetryAffordanceStateOptions {
+  /** Overridable for tests; defaults to RETRY_AFFORDANCE_WINDOW_MS (60s). */
+  readonly windowMs?: number;
+  /** Overridable for tests so the disarm timer doesn't require a real 60s wait. */
+  readonly schedule?: RetryAffordanceSchedule;
+  /** Called once the window elapses with no keypress and the state has been disarmed — main.ts hooks this to its render loop so the footer hint clears the instant the key goes dead. */
+  readonly onExpire?: () => void;
+}
+
+export function createRetryAffordanceState(options: CreateRetryAffordanceStateOptions = {}): RetryAffordanceState {
+  return {
+    armed: false,
+    exhausted: false,
+    timer: null,
+    schedule: options.schedule ?? REAL_SCHEDULE,
+    windowMs: options.windowMs ?? RETRY_AFFORDANCE_WINDOW_MS,
+    onExpire: options.onExpire,
+  };
+}
+
+function clearPendingTimer(state: RetryAffordanceState): void {
+  if (state.timer !== null) {
+    state.schedule.clearTimeout(state.timer);
+    state.timer = null;
+  }
+}
+
+/** Arm the affordance — call only when a retry is actually possible (a live retryCtx).
+ *  Starts (or restarts, if already armed) the disarm timer. */
+export function armRetryAffordance(state: RetryAffordanceState, exhausted: boolean): void {
+  clearPendingTimer(state);
+  state.armed = true;
+  state.exhausted = exhausted;
+  const timer = state.schedule.setTimeout(() => {
+    state.timer = null;
+    state.armed = false;
+    state.onExpire?.();
+  }, state.windowMs);
+  // Never let this timer hold the process open — a background retry-window
+  // countdown is not a reason to keep the event loop alive.
+  (timer as unknown as { unref?: () => void }).unref?.();
+  state.timer = timer;
+}
+
+/** Disarm the affordance — any key other than the ones it recognizes disarms it,
+ *  and cancels the pending disarm timer so it never fires on a state that's
+ *  already been reset (or re-armed by a subsequent error). */
+export function disarmRetryAffordance(state: RetryAffordanceState): void {
+  clearPendingTimer(state);
+  state.armed = false;
+}
+
+/** The transient footer hint text while armed; null once disarmed. */
+export function retryAffordanceHint(state: RetryAffordanceState): string | null {
+  if (!state.armed) return null;
+  return state.exhausted
+    ? '[Retry] r retry same provider · m switch model'
+    : '[Retry] r retry · m switch model';
+}
+
+/** Arm the affordance whenever a user-visible error surfaces AND a retry is
+ *  actually possible — wired here (not inline in main.ts) to keep the
+ *  entrypoint under the architecture line cap. */
+export function wireRetryAffordanceOnError(
+  onErrorSurfaced: (cb: (exhausted: boolean) => void) => void,
+  state: RetryAffordanceState,
+  hasRetryCtx: () => boolean,
+  render: () => void,
+): void {
+  onErrorSurfaced((exhausted) => {
+    if (hasRetryCtx()) {
+      armRetryAffordance(state, exhausted);
+      render();
+    }
+  });
+}

package/src/shell/ui-openers.ts

@@ -369,6 +369,15 @@ export function wireShellUiOpeners(options: WireShellUiOpenersOptions): void {
     render();
   };
 
+  // Mirrors the Ctrl+F chord's own toggle exactly (handler-shortcuts.ts's
+  // 'search' case) — the transcript search overlay isn't tracked on the
+  // modal stack, so this doesn't call modalOpened either.
+  commandContext.openTranscriptSearch = () => {
+    if (input.searchManager.active) input.searchManager.close();
+    else input.searchManager.open();
+    render();
+  };
+
   commandContext.openShortcutsOverlay = () => {
     if (!input.shortcutsOverlayActive) input.modalOpened('shortcuts');
     input.shortcutsOverlayActive = !input.shortcutsOverlayActive;

package/src/utils/splash-lines.ts

@@ -85,7 +85,7 @@ export function getSplashLines(columns: number, opts: SplashOptions = {}): strin
 
   // Last-session resume pointer (readLastSessionPointer result), when recorded.
   if (opts.lastSessionId) {
-    lines.push(metaLine(`↩ resume last session — /sessions resume ${opts.lastSessionId}`, columns));
+    lines.push(metaLine(`↩ resume last session — /resume ${opts.lastSessionId}`, columns));
   }
 
   lines.push('');

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '1.19.6';
+let _version = '1.20.1';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   // Only trust a version read from OUR OWN package.json. A Bun single-file