@pellux/goodvibes-tui 1.19.5 → 1.20.0

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

@@ -1,102 +1,17 @@
 /**
- * Helper factories for main()'s stdin fast-path and startup: the crash-recovery
- * snapshot persistence + panel-reopen callbacks, the SILENT auto-restore, and
- * the one-key error-retry affordance. Extracted from main.ts so the entrypoint
- * stays under the architecture line ceiling; main() wires these with its live
- * services.
+ * Helper factory for main()'s stdin fast-path: the one-key error-retry
+ * affordance. Extracted from main.ts so the entrypoint stays under the
+ * architecture line ceiling; main() wires this with its live services.
  *
- * Recovery is silent (owner ruling): there is no Ctrl+R prompt/banner and no
- * dismiss/preserve dance. At startup autoRestoreRecoverySession restores the
- * newest crash snapshot in place and emits a single one-line receipt. The old
- * `.preserved` sibling machinery is gone — a session's exit deletes only its
- * OWN snapshot (scoped by sessionId), so a concurrent session's snapshot is
- * never touched.
+ * The silent startup auto-restore that used to live here
+ * (autoRestoreRecoverySession, plus its createPersistRecoverySnapshot /
+ * createReopenRecoveryPanels factories) has been removed: state restores
+ * happen ONLY when the user explicitly asks (a CLI flag, a slash command, or
+ * a prompt), never automatically at bare launch (owner ruling). A live
+ * recovery snapshot is now surfaced, never applied, by the boot resume
+ * notice — see announceResumeState in runtime/resume-notice.ts.
  */
 
-import type { ConversationMessageSnapshot } from '../core/conversation.ts';
-import type { SessionSnapshot } from '@/runtime/index.ts';
-import { autoRestoreRecovery } from '@/runtime/index.ts';
-import { replayJournalForSession } from '../core/session-recovery.ts';
-
-export interface PersistRecoveryDeps {
-  readonly sessionManager: {
-    save(id: string, msgs: never[], meta: { title: string; model: string; provider: string; timestamp: number }): unknown;
-  };
-  readonly runtime: { readonly sessionId: string; readonly model: string; readonly provider: string };
-  readonly conversation: { readonly title?: string | null };
-}
-
-/** Persist a replayed/restored snapshot through the session manager. */
-export function createPersistRecoverySnapshot(deps: PersistRecoveryDeps): (msgs: ConversationMessageSnapshot[]) => void {
-  return (msgs) => void deps.sessionManager.save(deps.runtime.sessionId, msgs as never[], {
-    title: deps.conversation.title ?? '',
-    model: deps.runtime.model,
-    provider: deps.runtime.provider,
-    timestamp: Date.now(),
-  });
-}
-
-export interface ReopenPanelsDeps {
-  readonly panelManager: { open(id: string): void; show(): void };
-  readonly render: () => void;
-}
-
-/** Reopen the panels recorded in a restored session's return context (capped at 4). */
-export function createReopenRecoveryPanels(deps: ReopenPanelsDeps): (snapshot: SessionSnapshot) => void {
-  return (snapshot) => {
-    for (const panelId of (snapshot.returnContext?.openPanels ?? []).slice(0, 4)) {
-      try { deps.panelManager.open(panelId); } catch { /* unknown panel id */ }
-    }
-    if ((snapshot.returnContext?.openPanels?.length ?? 0) > 0) { deps.panelManager.show(); deps.render(); }
-  };
-}
-
-export interface AutoRestoreRecoveryDeps {
-  readonly workingDirectory: string;
-  readonly homeDirectory: string;
-  /** The live conversation to restore INTO (fromJSON applies the snapshot). */
-  readonly conversation: {
-    fromJSON(input: { messages: ConversationMessageSnapshot[]; title?: string; titleSource?: SessionSnapshot['titleSource'] }): void;
-  };
-  /** Persist the post-replay snapshot so the WAL gap is durably closed. */
-  readonly persistSnapshot: (msgs: ConversationMessageSnapshot[]) => void;
-  /** Reopen the restored session's panels. */
-  readonly reopenPanels: (snapshot: SessionSnapshot) => void;
-  /** Surface the one-line receipt (the only user-visible sign of a restore). */
-  readonly systemMessageRouter: { high(message: string): void };
-}
-
-/**
- * Silent crash-recovery restore at startup — no prompt, no banner. Loads the
- * newest crash snapshot (the SDK scopes the load AND the follow-up delete to
- * that snapshot's own session id), applies it to the live conversation, replays
- * any journal turns written after the snapshot, reopens its panels, and emits
- * the SDK's one-line receipt. Returns true when a session was restored, false
- * when there was nothing to restore.
- */
-export function autoRestoreRecoverySession(deps: AutoRestoreRecoveryDeps): boolean {
-  const result = autoRestoreRecovery({ workingDirectory: deps.workingDirectory, homeDirectory: deps.homeDirectory });
-  if (!result) return false;
-  const { snapshot, info, receipt } = result;
-  deps.conversation.fromJSON({
-    messages: snapshot.messages as ConversationMessageSnapshot[],
-    title: snapshot.title,
-    titleSource: snapshot.titleSource,
-  });
-  // Replay journal records that post-date the snapshot so turns written after
-  // the last recovery-file write (but before the crash) are not dropped.
-  replayJournalForSession({
-    homeDirectory: deps.homeDirectory,
-    sessionId: info.sessionId,
-    snapshotTimestamp: info.timestamp ?? 0,
-    conversation: deps.conversation as never,
-    persistSnapshot: deps.persistSnapshot,
-  });
-  deps.reopenPanels(snapshot);
-  deps.systemMessageRouter.high(`[Recovery] ${receipt}`);
-  return true;
-}
-
 export interface ErrorAffordanceDeps {
   /** True when the failover retry context is armed (a retry is actually possible). */
   readonly retryArmed: boolean;
@@ -109,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.5';
+let _version = '1.20.0';
 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