@pellux/goodvibes-tui 1.19.5 → 1.20.0

package/src/core/conversation-types.ts

@@ -11,8 +11,18 @@
 
 import type { BlockMeta as SdkBlockMeta } from '@pellux/goodvibes-sdk/platform/core';
 
-/** TUI extends the SDK BlockMeta with rendering position fields. */
-export interface BlockMeta extends SdkBlockMeta {
+/**
+ * TUI extends the SDK BlockMeta with rendering position fields, plus a
+ * TUI-only block type: 'tool_group' is the synthetic header block that folds
+ * a run of >=2 consecutive tool-result messages under one collapsible header
+ * (see conversation-tool-groups.ts). Defined as an intersection rather than
+ * `interface X extends SdkBlockMeta` because TypeScript requires an extending
+ * interface's members to be subtypes of the base interface's — widening the
+ * `type` union that way is a compile error. Omit + intersection adds the new
+ * variant without touching the SDK's published type.
+ */
+export type BlockMeta = Omit<SdkBlockMeta, 'type'> & {
+  type: SdkBlockMeta['type'] | 'tool_group';
   /** Index of this block (increments per renderable block). */
   blockIndex: number;
   /** First rendered line index in the history buffer. */
@@ -21,4 +31,21 @@ export interface BlockMeta extends SdkBlockMeta {
   lineCount: number;
   /** Stable key for collapse state persistence across rebuilds (e.g. msg_N). */
   collapseKey: string;
-}
+  /**
+   * Absolute message indexes of every member of a folded tool-result group
+   * (see conversation-tool-groups.ts). Present only on 'tool_group' blocks —
+   * lets /expand also open each member's own collapse key in the same pass,
+   * since a folded member pushes no BlockMeta of its own to toggle
+   * individually while the group stays collapsed.
+   */
+  groupMemberIndexes?: readonly number[];
+  /**
+   * The tool call's name, when this block renders a 'tool' result (or is the
+   * header of a 'tool_group' whose members share a run — the header carries
+   * the first member's name). Used to name the block honestly in action
+   * receipts (e.g. "tool result: exec") — see describeBlockForReceipt in
+   * handler-content-actions.ts. Undefined for non-tool block types and for
+   * standalone tool results with no recorded name.
+   */
+  toolName?: string;
+};

package/src/core/conversation.ts

@@ -644,6 +644,23 @@ export class ConversationManager extends SdkConversationManager {
     return nearest.blockIndex;
   }
 
+  /** First rendered line for message `absoluteIdx` (undefined if never
+   *  rendered). For a folded tool-group member this is the group's own
+   *  header line, not the following message's position — see
+   *  messageLineRegistry's doc. Flushes history if dirty. */
+  public getMessageLine(absoluteIdx: number): number | undefined {
+    this.flushHistory();
+    return this.messageLineRegistry[absoluteIdx];
+  }
+
+  /** Set a collapseKey's state directly, bypassing block lookup — needed for
+   *  a key with no BlockMeta yet (a folded tool-group member's own
+   *  `msg_<idx>` key only becomes a real block once its group expands). */
+  public setCollapsed(collapseKey: string, collapsed: boolean): void {
+    this.collapseState.set(collapseKey, collapsed);
+    this.markDirty();
+  }
+
   /** Returns a read-only view of the block registry for external consumers. */
   public getBlockRegistry(): readonly BlockMeta[] {
     return this.blockRegistry;

package/src/core/rewind-turn-anchors.ts

@@ -23,9 +23,8 @@
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+import type { SessionSurface } from '@/runtime/index.ts';
 
-const { getUserSessionsDir } = operations;
 
 /** One recorded turn boundary — the rewind coordinator's per-turn anchor. */
 export interface TurnAnchor {
@@ -87,18 +86,18 @@ export function clearTurnAnchors(sessionId: string): void {
 // --- Cross-resume persistence -------------------------------------------------
 //
 // The TUI mirrors the in-memory registry to a sidecar next to the session file.
-// Surface is always 'tui' (the sessions the TUI reads/writes live under the same
-// scoped directory), matching how the session JSONL itself is persisted.
-const ANCHOR_SIDECAR_SURFACE = 'tui';
+// The directory comes off the caller's SessionSurface (`surface.sessionsDir`),
+// the same handle the session JSONL itself is written through — so the sidecar
+// and its session can never end up in different directories.
 const ANCHOR_SIDECAR_VERSION = 1;
 
 /** Absolute path to a session's anchor sidecar, or null when inputs are unusable. */
-function anchorSidecarPath(sessionId: string, workingDirectory: string): string | null {
-  if (!sessionId || !workingDirectory) return null;
+function anchorSidecarPath(sessionId: string, surface: SessionSurface): string | null {
+  if (!sessionId || !surface.sessionsDir) return null;
   // A sessionId is a filename component; refuse anything with path separators so
   // a malformed id can never escape the sessions directory.
   if (/[\\/]/.test(sessionId)) return null;
-  return join(getUserSessionsDir(workingDirectory, ANCHOR_SIDECAR_SURFACE), `${sessionId}.anchors.json`);
+  return join(surface.sessionsDir, `${sessionId}.anchors.json`);
 }
 
 function isTurnAnchor(value: unknown): value is TurnAnchor {
@@ -118,13 +117,13 @@ function isTurnAnchor(value: unknown): value is TurnAnchor {
  * torn write must never break the turn that triggered it. Called after each
  * `recordTurnAnchor` at TURN_COMPLETED.
  */
-export function persistTurnAnchors(sessionId: string, workingDirectory: string): void {
-  const path = anchorSidecarPath(sessionId, workingDirectory);
+export function persistTurnAnchors(sessionId: string, surface: SessionSurface): void {
+  const path = anchorSidecarPath(sessionId, surface);
   if (!path) return;
   const list = registry.get(sessionId) ?? [];
   if (list.length === 0) return; // nothing to mirror yet
   try {
-    mkdirSync(getUserSessionsDir(workingDirectory, ANCHOR_SIDECAR_SURFACE), { recursive: true });
+    mkdirSync(surface.sessionsDir, { recursive: true });
     const payload = JSON.stringify({ version: ANCHOR_SIDECAR_VERSION, sessionId, anchors: list });
     const tmp = `${path}.tmp-${process.pid}`;
     writeFileSync(tmp, payload);
@@ -140,8 +139,8 @@ export function persistTurnAnchors(sessionId: string, workingDirectory: string):
  * unreadable). Idempotent via `recordTurnAnchor`'s per-turnId dedup, so a resume
  * that later re-records the same turn keeps a single entry.
  */
-export function restoreTurnAnchors(sessionId: string, workingDirectory: string): number {
-  const path = anchorSidecarPath(sessionId, workingDirectory);
+export function restoreTurnAnchors(sessionId: string, surface: SessionSurface): number {
+  const path = anchorSidecarPath(sessionId, surface);
   if (!path || !existsSync(path)) return 0;
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf8')) as { anchors?: unknown };

package/src/core/session-recovery.ts

@@ -8,14 +8,12 @@
  * it replays those records onto the live conversation and writes a fresh
  * snapshot so the gap is permanently closed.
  *
- * Seams (all three must call replayJournalForSession)
- * ────────────────────────────────────────────────────
+ * Seams (both must call replayJournalForSession)
+ * ───────────────────────────────────────────────
  * 1. CLI / command resume — session-workflow.ts, after `fromJSON` +
  *    `rebuildHistory` complete. Handles --continue, --resume, /session resume,
  *    and --fork.
- * 2. Ctrl+R crash recovery — blocking-input.ts, after `conversation.fromJSON`
- *    in the Ctrl+R branch. Handles SIGKILL-era recovery files.
- * 3. In-TUI panel resume — bootstrap-hook-bridge.ts
+ * 2. In-TUI panel resume — bootstrap-hook-bridge.ts
  *    `createResumeSessionHandler`, after `options.runtime.sessionId` is
  *    assigned. Handles the session browser / panel-driven resume.
  *
@@ -37,6 +35,7 @@
 import { journalPathFor, openTranscriptJournal, replayJournal } from './transcript-journal.ts';
 import type { ConversationManager } from './conversation.ts';
 import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+import type { SessionSurface } from '@/runtime/index.ts';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -147,9 +146,65 @@ export function replayJournalIntoConversation(
  */
 export function replayJournalForSession(
   options: Omit<ReplayIntoConversationOptions, 'journalPath'> & {
-    readonly homeDirectory: string;
+    readonly surface: SessionSurface;
   },
 ): ReplayIntoConversationResult {
-  const journalPath = journalPathFor(options.homeDirectory, options.sessionId);
+  const journalPath = journalPathFor(options.surface, options.sessionId);
   return replayJournalIntoConversation({ ...options, journalPath });
 }
+
+// ─── Prompted crash-snapshot restore ────────────────────────────────────────
+
+/** What a crash-recovery snapshot carries back from disk. */
+export interface RecoverySnapshotPayload {
+  readonly messages: Array<Record<string, unknown>>;
+  readonly title?: string | undefined;
+  readonly titleSource?: string | undefined;
+  readonly timestamp?: number | undefined;
+}
+
+export interface ApplyRecoverySnapshotResult {
+  /** Messages the conversation holds once the snapshot (plus any journal tail) is in place. */
+  readonly messageCount: number;
+  /** Journal records that post-dated the snapshot and were folded in on top of it. */
+  readonly journalReplay: ReplayIntoConversationResult;
+}
+
+/**
+ * Apply a crash-recovery snapshot the user explicitly asked to resume.
+ *
+ * This is deliberately the same sequence `resumeSessionCore` runs for a saved
+ * session — reset, fromJSON, rebuildHistory, then fold in any journal records
+ * newer than the snapshot — with one difference: the messages come from the
+ * recovery file the SDK just handed back (`consumeRecovery`) instead of the
+ * session store, because a session that crashed before its first clean save
+ * has no entry in the store to load. Nothing here decides WHETHER to restore;
+ * the caller has already asked the user (see runtime/recovery-prompt.ts).
+ */
+export function applyRecoverySnapshot(options: {
+  readonly snapshot: RecoverySnapshotPayload;
+  readonly sessionId: string;
+  readonly conversation: ConversationManager;
+  readonly surface: SessionSurface;
+  readonly persistSnapshot: (messages: ConversationMessageSnapshot[]) => void;
+}): ApplyRecoverySnapshotResult {
+  const { snapshot, sessionId, conversation, surface, persistSnapshot } = options;
+
+  conversation.resetAll();
+  conversation.fromJSON({
+    messages: snapshot.messages as never[],
+    title: snapshot.title,
+    titleSource: snapshot.titleSource as never,
+  });
+  conversation.rebuildHistory();
+
+  const journalReplay = replayJournalForSession({
+    surface,
+    sessionId,
+    snapshotTimestamp: snapshot.timestamp ?? 0,
+    conversation,
+    persistSnapshot,
+  });
+
+  return { messageCount: conversation.getMessageCount(), journalReplay };
+}

package/src/core/session-resume-core.ts

@@ -0,0 +1,206 @@
+/**
+ * session-resume-core.ts — the ONE resume routine both resume seams call.
+ *
+ * Two independent call sites used to duplicate (and diverge from) this
+ * sequence: `/session resume` (session-workflow.ts) and the panel/session-
+ * browser resume (bootstrap-hook-bridge.ts's `createResumeSessionHandler`).
+ * Divergences found by audit:
+ *   - the panel seam skipped `restoreTurnAnchors` (message-anchored /rewind
+ *     silently had no anchors after a panel resume)
+ *   - the panel seam skipped `conversation.resetAll()` before `fromJSON()`
+ *   - the panel seam skipped the `selectModel` reselection fallback (it set
+ *     `runtime.model` straight from the saved meta, never re-resolving
+ *     through the live provider registry)
+ *   - the panel seam duplicated the panel-reopen loop WITHOUT the
+ *     modal-redirect skip, so a MIGRATE-TO-MODAL id could pop a modal
+ *     mid-resume
+ *
+ * Both seams now call this module so those four behaviors (plus the
+ * panel-reopen-cap honesty note) are guaranteed identical by construction,
+ * not by copy-paste discipline between two files.
+ *
+ * Callers own everything ABOVE and AROUND this core sequence: printing or
+ * logging the outcome in their own idiom (`ctx.print` vs `conversation.log`),
+ * and any extra plumbing that only one seam performs (hookDispatcher.fire,
+ * sessionSpine.reopen, sharedSessionBroker.reopenSession,
+ * writeLastSessionPointer — all bootstrap-hook-bridge-only, pre-existing
+ * asymmetries out of this module's scope).
+ */
+import type { SessionManager, SessionMeta } from '@pellux/goodvibes-sdk/platform/sessions';
+import type { SessionSurface } from '@/runtime/index.ts';
+import type { ConversationManager } from './conversation.ts';
+import { restoreTurnAnchors } from './rewind-turn-anchors.ts';
+import { replayJournalForSession, type ReplayIntoConversationResult } from './session-recovery.ts';
+
+export interface SessionResumeRuntime {
+  sessionId: string;
+  model: string;
+  provider: string;
+}
+
+export interface SessionResumePanelManager {
+  open(id: string): unknown;
+  show(): void;
+  getModalRedirect(id: string): string | undefined;
+}
+
+export interface SessionResumeDeps {
+  readonly sessionManager: Pick<SessionManager, 'load' | 'save'>;
+  readonly conversation: ConversationManager;
+  readonly runtime: SessionResumeRuntime;
+  /**
+   * The app's declare-once session-storage handle. Both resume seams pass the
+   * SAME one the runtime writes through, so the anchor sidecar and the
+   * transcript journal this routine reads are guaranteed to be the files the
+   * live session actually wrote — the scope can no longer be re-guessed per
+   * seam.
+   */
+  readonly surface: SessionSurface;
+  readonly panelManager: SessionResumePanelManager;
+  /**
+   * Reselects the saved model through the live provider registry, falling
+   * back to the raw saved id on failure (a saved model may no longer exist
+   * locally). Omit to use the saved id directly without reselection.
+   */
+  readonly selectModel?: (model: string) => Promise<{ readonly registryKey: string; readonly providerId: string }>;
+  readonly hydrateSessionUsage?: () => void;
+  /**
+   * Deliberate cap on how many saved panels are reopened at once — resuming
+   * into a workspace crowded with every panel that happened to be open is
+   * its own kind of surprise. Overflow beyond the cap is reported in the
+   * outcome (`panels.notReopened`), never silently dropped. Defaults to 4.
+   */
+  readonly panelReopenLimit?: number;
+}
+
+export interface PanelReopenOutcome {
+  readonly reopened: readonly string[];
+  readonly movedToModal: readonly string[];
+  /** Saved panel ids beyond `panelReopenLimit` — not attempted, honestly reported (see /panels to open the rest). */
+  readonly notReopened: readonly string[];
+}
+
+export interface SessionResumeOutcome {
+  readonly meta: SessionMeta;
+  readonly resumedMessageCount: number;
+  readonly restoredAnchorCount: number;
+  readonly journalReplay: ReplayIntoConversationResult;
+  readonly panels: PanelReopenOutcome;
+}
+
+/**
+ * Exported so both session-workflow.ts's standalone `reopenPanelsFromReturnContext`
+ * (kept for its existing direct unit-test coverage — see
+ * session-workflow-panel-restore.test.ts) and `resumeSessionCore` below share
+ * the exact same default cap.
+ */
+export const DEFAULT_PANEL_REOPEN_LIMIT = 4;
+
+export function reopenPanelsWithModalSkip(
+  panelManager: SessionResumePanelManager,
+  openPanelIds: readonly string[] | undefined,
+  limit: number,
+): PanelReopenOutcome {
+  if (!openPanelIds || openPanelIds.length === 0) return { reopened: [], movedToModal: [], notReopened: [] };
+  const within = openPanelIds.slice(0, limit);
+  const overflow = openPanelIds.slice(limit);
+  const reopened: string[] = [];
+  const movedToModal: string[] = [];
+  for (const panelId of within) {
+    // A MIGRATE-TO-MODAL id has no panel to restore — a modal is not part of
+    // the saved panel layout. Skip it (don't pop a modal mid-resume) and note
+    // it once, rather than firing open() and revealing an empty workspace.
+    if (panelManager.getModalRedirect(panelId) !== undefined) {
+      movedToModal.push(panelId);
+      continue;
+    }
+    try {
+      panelManager.open(panelId);
+      reopened.push(panelId);
+    } catch {
+      // Ignore unknown or currently unavailable panel ids during resume.
+    }
+  }
+  if (reopened.length > 0) panelManager.show();
+  return { reopened, movedToModal, notReopened: overflow };
+}
+
+/**
+ * The canonical resume sequence: load, reset + restore the conversation,
+ * restore rewind anchors, replay any post-snapshot journal records, hydrate
+ * footer usage, reselect the model, and reopen saved panels (modal-redirect
+ * aware, cap honestly reported).
+ */
+export async function resumeSessionCore(sessionId: string, deps: SessionResumeDeps): Promise<SessionResumeOutcome> {
+  const { meta, messages } = deps.sessionManager.load(sessionId);
+
+  deps.conversation.resetAll();
+  deps.conversation.fromJSON({
+    messages: messages as never[],
+    title: meta.title,
+    titleSource: meta.titleSource,
+  });
+  deps.conversation.rebuildHistory();
+  deps.runtime.sessionId = sessionId;
+
+  // Restore this session's message-anchored rewind anchors from its sidecar
+  // so /rewind works identically before and after the resume — the in-memory
+  // registry is process-local, so a fresh process starts with none for the
+  // loaded session.
+  const restoredAnchorCount = restoreTurnAnchors(sessionId, deps.surface);
+
+  // Journal replay: recover turns that post-date the loaded snapshot.
+  const journalReplay = replayJournalForSession({
+    surface: deps.surface,
+    sessionId,
+    snapshotTimestamp: meta.timestamp ?? 0,
+    conversation: deps.conversation,
+    persistSnapshot: (replayedMessages) => {
+      deps.sessionManager.save(sessionId, replayedMessages as never[], {
+        title: deps.conversation.title || meta.title,
+        model: meta.model,
+        provider: meta.provider,
+        timestamp: Date.now(),
+        titleSource: meta.titleSource,
+        returnContext: meta.returnContext,
+        // Machinery: this write exists only to durably close the journal gap
+        // the replay just filled. The user's own save/fork/rename acts stamp
+        // 'user' at their own call sites (session-workflow.ts).
+        saveSource: 'auto',
+      });
+    },
+  });
+
+  // Hydrate the footer's token counters from the resumed (+ journal-replayed)
+  // history now, before the caller renders.
+  deps.hydrateSessionUsage?.();
+
+  if (meta.model) {
+    if (deps.selectModel) {
+      try {
+        const selected = await deps.selectModel(meta.model);
+        deps.runtime.model = selected.registryKey;
+        deps.runtime.provider = selected.providerId;
+      } catch {
+        deps.runtime.model = meta.model; // model may not exist locally
+      }
+    } else {
+      deps.runtime.model = meta.model;
+    }
+  }
+  if (meta.provider) deps.runtime.provider = meta.provider;
+
+  const panels = reopenPanelsWithModalSkip(
+    deps.panelManager,
+    meta.returnContext?.openPanels,
+    deps.panelReopenLimit ?? DEFAULT_PANEL_REOPEN_LIMIT,
+  );
+
+  return {
+    meta,
+    resumedMessageCount: deps.conversation.getMessageCount(),
+    restoredAnchorCount,
+    journalReplay,
+    panels,
+  };
+}

package/src/core/transcript-journal.ts

@@ -67,6 +67,7 @@ import {
 } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+import type { SessionSurface } from '@/runtime/index.ts';
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -128,6 +129,17 @@ export interface TranscriptJournal {
 
   /** Absolute path to the journal file. */
   readonly path: string;
+
+  /**
+   * Point this journal at a different session's file, resetting the sequence
+   * counter and initialization flag. Used when the session a journal was
+   * opened for is switched out from under it (e.g. `/session resume` or
+   * `/session fork` reassigning `runtime.sessionId`) — without this, the
+   * journal keeps appending the NEW session's records into the OLD session's
+   * file. Does not touch the old file on disk; it is simply no longer
+   * written to.
+   */
+  rebind(journalPath: string, sessionId: string): void;
 }
 
 // ─── Factory ────────────────────────────────────────────────────────────────
@@ -148,11 +160,15 @@ export function openTranscriptJournal(
 /**
  * Build the canonical journal path for a session.
  *
- * @param homeDirectory  The goodvibes home directory (e.g. ~/.goodvibes).
- * @param sessionId      The session identifier.
+ * Both the home directory and the scope segment come off the caller's
+ * SessionSurface, so the journal lands beside the sessions and recovery
+ * snapshots it fills gaps for rather than under a separately-spelled scope.
+ *
+ * @param surface    The app's declare-once session-storage handle.
+ * @param sessionId  The session identifier.
  */
-export function journalPathFor(homeDirectory: string, sessionId: string): string {
-  return join(homeDirectory, '.goodvibes', 'tui', `transcript-${sessionId}.journal`);
+export function journalPathFor(surface: SessionSurface, sessionId: string): string {
+  return join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot, `transcript-${sessionId}.journal`);
 }
 
 /**
@@ -248,8 +264,11 @@ export function replayJournal(
 // ─── Implementation ─────────────────────────────────────────────────────────
 
 class TranscriptJournalImpl implements TranscriptJournal {
-  readonly path: string;
-  private readonly _sessionId: string;
+  // Not `readonly` at the class level (unlike the public interface) so
+  // rebind() can repoint it; external callers only ever see it through the
+  // `TranscriptJournal` interface, which keeps it read-only for them.
+  path: string;
+  private _sessionId: string;
   private _seq = 0;
   private _initialised = false;
 
@@ -258,6 +277,13 @@ class TranscriptJournalImpl implements TranscriptJournal {
     this._sessionId = sessionId;
   }
 
+  rebind(journalPath: string, sessionId: string): void {
+    this.path = journalPath;
+    this._sessionId = sessionId;
+    this._seq = 0;
+    this._initialised = false;
+  }
+
   appendRecord(type: JournalEventType, messages: ConversationMessageSnapshot[]): void {
     try {
       this._ensureInitialised();

package/src/core/turn-event-wiring.ts

@@ -7,6 +7,7 @@ import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import type { HookDispatcher, HookPhase, HookCategory, HookEventPath } from '@pellux/goodvibes-sdk/platform/hooks';
 import type { ConversationManager } from './conversation.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
 import { journalPathFor, openTranscriptJournal, type TranscriptJournal } from './transcript-journal.ts';
 import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
 import { notifyCompletion } from '@pellux/goodvibes-sdk/platform/utils';
@@ -16,9 +17,6 @@ import { shouldFireAlert, FORCE_NOTIFY_DURATION_MS } from './alert-gating.ts';
 import { createBudgetBreachNotifier, type BudgetBreachNotifier } from './budget-breach-notifier.ts';
 import { readBudgetAlertUsd } from '../export/cost-utils.ts';
 
-/** Infer the options param of persistConversation to pick up SessionManager correctly. */
-type PersistOptions = NonNullable<Parameters<typeof persistConversation>[5]>;
-
 /** Minimal orchestrator surface required by turn-event wiring. */
 interface TurnOrchestrator {
   readonly lastInputTokens: number;
@@ -64,9 +62,14 @@ export interface WireTurnEventHandlersOptions {
   readonly providerRegistry: TurnProviderRegistry;
   readonly systemMessageRouter: TurnSystemMessageRouter;
   readonly hookDispatcher: HookDispatcher;
-  readonly workingDir: string;
-  readonly homeDirectory: string;
-  readonly sessionManager: PersistOptions['sessionManager'];
+  /**
+   * The app's declare-once session-storage handle. The turn snapshot, the
+   * last-session pointer it writes, the transcript journal, and the rewind
+   * anchor sidecar all resolve off this one handle — so the boot notice and
+   * `--continue`, which read through the same handle, land on the files this
+   * writer actually produced.
+   */
+  readonly surface: SessionSurface;
   readonly gitStatusProvider: { refresh(): Promise<unknown> };
   readonly lastGitInfoRef: { value: unknown };
   readonly buildSessionContinuityHints: () => Record<string, unknown>;
@@ -104,6 +107,32 @@ export interface WireTurnEventHandlersOptions {
   readonly _clock?: () => number;
 }
 
+/**
+ * Wrap a TranscriptJournal so every write first checks whether
+ * `runtime.sessionId` has moved on from the session the journal is currently
+ * bound to, rebinding to the new session's file when it has. See the
+ * `transcriptJournal` construction above for why this is necessary.
+ */
+function wrapJournalWithSessionRebind(
+  journal: TranscriptJournal,
+  surface: SessionSurface,
+  runtime: { readonly sessionId: string },
+): TranscriptJournal {
+  let boundSessionId = runtime.sessionId;
+  const ensureBoundToCurrentSession = (): void => {
+    if (runtime.sessionId !== boundSessionId) {
+      boundSessionId = runtime.sessionId;
+      journal.rebind(journalPathFor(surface, boundSessionId), boundSessionId);
+    }
+  };
+  return {
+    get path(): string { return journal.path; },
+    appendRecord: (type, messages) => { ensureBoundToCurrentSession(); journal.appendRecord(type, messages); },
+    rotate: () => { ensureBoundToCurrentSession(); journal.rotate(); },
+    rebind: (path, sessionId) => { boundSessionId = sessionId; journal.rebind(path, sessionId); },
+  };
+}
+
 export interface WireTurnEventHandlersResult {
   /** Trigger a git status refresh; may be called from external code after tool execution. */
   readonly refreshGit: () => void;
@@ -134,7 +163,7 @@ export function wireTurnEventHandlers(
 ): WireTurnEventHandlersResult {
   const {
     events, conversation, runtime, configManager, hookDispatcher, orchestrator, providerRegistry,
-    workingDir, homeDirectory, sessionManager, gitStatusProvider,
+    surface, gitStatusProvider,
     lastGitInfoRef, buildSessionContinuityHints, render, webhookNotifier, focusTracker,
     terminalNotifier, runtimeBus, systemMessageRouter,
     _clock = Date.now,
@@ -145,9 +174,19 @@ export function wireTurnEventHandlers(
 
   // Create the per-session transcript journal. Path mirrors recovery-file
   // convention (homeDirectory-scoped). Created lazily on first append.
-  const transcriptJournal: TranscriptJournal = openTranscriptJournal(
-    journalPathFor(homeDirectory, runtime.sessionId),
-    runtime.sessionId,
+  //
+  // `runtime` is the same MutableRuntimeState object /session resume and
+  // /session fork reassign `sessionId` on in place (session-workflow.ts,
+  // bootstrap-hook-bridge.ts), so a session switch is visible here just by
+  // re-reading `runtime.sessionId`. Wrapped so every write re-checks it and
+  // rebinds to the new session's file first — otherwise the journal opened
+  // for the OLD session keeps appending the NEW session's snapshots into the
+  // OLD session's file, and a later resume of the old session replays the
+  // wrong conversation.
+  const transcriptJournal: TranscriptJournal = wrapJournalWithSessionRebind(
+    openTranscriptJournal(journalPathFor(surface, runtime.sessionId), runtime.sessionId),
+    surface,
+    runtime,
   );
 
   // Track turn start time for long-task notification threshold.
@@ -210,7 +249,11 @@ export function wireTurnEventHandlers(
         runtime.model,
         runtime.provider,
         conversation.title || '',
-        { workingDirectory: workingDir, homeDirectory, sessionManager },
+        { surface },
+        // Turn-completion persistence is machinery, not a user act: stated
+        // explicitly so the retention sweep can tell it apart from a session
+        // the user asked to keep via /session save.
+        'auto',
       );
       hookDispatcher.fire({ path: 'Lifecycle:session:save' as HookEventPath, phase: 'Lifecycle' as HookPhase, category: 'session' as HookCategory, specific: 'save', sessionId: runtime.sessionId, timestamp: Date.now(), payload: { sessionId: runtime.sessionId } }).catch((err: unknown) => logger.debug('hook fire error', { error: summarizeError(err) }));
       // Snapshot succeeded — rotate the journal (gap-filler no longer needed).
@@ -238,7 +281,7 @@ export function wireTurnEventHandlers(
       });
       // Mirror the anchors to the session's sidecar so message-anchored /rewind
       // survives a resume (the in-memory registry alone is process-local).
-      persistTurnAnchors(runtime.sessionId, workingDir);
+      persistTurnAnchors(runtime.sessionId, surface);
     } catch { /* best-effort; a rewind-anchor miss must never break the turn */ }
     // Auto-compaction is owned by the SDK Orchestrator's post-turn maintenance
     // (handlePostTurnContextMaintenance), which runs on every turn against the

package/src/input/command-args-hint.ts

@@ -1,12 +1,21 @@
 import type { CommandRegistry } from './command-registry.ts';
+import { SESSION_SUBCOMMAND_ARG_HINTS } from './commands/session.ts';
 
+/**
+ * Per-command subcommand → argument-hint maps. `session`'s entries come
+ * straight from session.ts (SESSION_SUBCOMMAND_ARG_HINTS) — the same table
+ * the `/session` switch itself is built from — so the two can never drift
+ * apart; the others are hand-maintained here since they're small and their
+ * owning modules don't export an equivalent table. A drift test
+ * (src/test/input/command-args-hint.test.ts) checks every top-level key
+ * below resolves to a real registered command.
+ */
 const SUBCOMMAND_HINTS: Record<string, Record<string, string>> = {
-  session: { rename: '<name>', resume: '<id|name>', info: '<id>', export: '<id> [format]', search: '<query>', delete: '<id>' },
+  session: SESSION_SUBCOMMAND_ARG_HINTS,
   template: { save: '<name>', use: '<name> [args]', edit: '<name>', delete: '<name>' },
   secrets: { set: '<KEY> <value>', get: '<KEY>', delete: '<KEY>' },
   permissions: { tool: '<name> allow|prompt|deny' },
   config: { reset: '<key>' },
-  danger: {},
   plugin: { enable: '<name>', disable: '<name>', reload: '' },
 };