@pellux/goodvibes-tui 1.19.6 → 1.20.1

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/stream-event-wiring.ts

@@ -2,6 +2,8 @@ import type { UiRuntimeEvents } from '@/runtime/index.ts';
 import { createStreamStallWatchdog } from './stream-stall-watchdog.ts';
 import { buildRoutingChip } from './model-routing-chip.ts';
 import { formatUserFacingErrorLine } from './format-user-error.ts';
+import { classifyProviderSetup } from '../providers/provider-classification.ts';
+import type { FailoverTurnState } from './active-model-identity.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 /**
@@ -101,6 +103,14 @@ interface FailoverOptimizer {
 interface StreamSystemMessageRouter {
   high(message: string): void;
   low(message: string): void;
+  /**
+   * Unconditional conversation delivery (see system-message-router.ts). Used
+   * for provider-switch notices: which backend serves a turn — and therefore
+   * who bills for it — is never ambient chatter that a routing preference or
+   * the noise gate may filter out. Optional so bare test doubles that supply
+   * only high/low still type-check; announce() below falls back to high().
+   */
+  userReceipt?(message: string): void;
 }
 
 /**
@@ -166,8 +176,15 @@ export interface WireStreamEventMetricsOptions {
    * Callback the caller provides to re-submit the last user turn on a
    * different provider after a successful failover switch.  Called only when
    * the optimizer is enabled and a viable next provider exists in the chain.
+   *
+   * The re-submission rolls the conversation back to its pre-submission
+   * message count, which deletes everything the failed turn added — including
+   * a failover notice appended before the call. So the notice is passed IN
+   * rather than emitted before: the caller re-posts it after its rollback, and
+   * it survives to be read. Implementations that do not roll back may ignore
+   * the argument, but must then post the notice themselves.
    */
-  readonly retryTurn?: () => void;
+  readonly retryTurn?: (notice?: string) => void;
   /**
    * Optional cost catalog for attaching per-1M-token cost information to
    * the failover notice.  When provided and both models have non-zero pricing,
@@ -189,6 +206,22 @@ export interface WireStreamEventMetricsOptions {
    * callers omit it.
    */
   readonly stallThresholdMs?: number | undefined;
+  /**
+   * Shared holder for the live failover record (core/active-model-identity.ts).
+   * Set when failover switches the registry off the user's configured
+   * selection, cleared once serving is restored to it. The render frame reads
+   * the same object, so the header and footer describe the switch while it is
+   * in effect. Omitted by unit tests that only exercise notice content.
+   */
+  readonly failoverState?: FailoverTurnState;
+  /**
+   * The user's configured model selection (config `provider.model`) as a
+   * registry key. Read at the moment of a failover switch so the turn-end
+   * restore targets what the user actually chose — not whatever the registry
+   * happened to hold. Without it, failover still works but no restore or
+   * divergence marker is possible, so both are skipped rather than guessed at.
+   */
+  readonly getConfiguredRegistryKey?: () => string | undefined;
 }
 
 /** Result of wireStreamEventMetrics. */
@@ -196,10 +229,12 @@ export interface WireStreamEventMetricsResult {
   /** Unsubscribe functions; push into the parent unsubs array for cleanup on exit. */
   readonly unsubs: ReadonlyArray<() => void>;
   /**
-   * Clear the per-turn failover visited-provider set.
-   * Call this on every new user submission so the visited set does not bleed
-   * across independent turns (the set is also cleared automatically on
-   * TURN_COMPLETED, but a new submission may arrive before TURN_COMPLETED fires).
+   * Clear the per-turn failover visited-provider set AND restore the user's
+   * configured model selection if a failover left serving somewhere else.
+   * Call this on every new user submission so neither the visited set nor a
+   * per-turn provider switch bleeds across independent turns (both are also
+   * handled on TURN_COMPLETED/TURN_CANCEL, but a new submission may arrive
+   * before either fires).
    */
   readonly clearFailoverVisited: () => void;
   /**
@@ -253,6 +288,33 @@ function buildCostDeltaSuffix(
   return ` [cost/1M: input ${fmt(fromCost.input)}→${fmt(toCost.input)}, output ${fmt(fromCost.output)}→${fmt(toCost.output)}]`;
 }
 
+/**
+ * Build the billing-class segment of a failover notice, e.g.
+ * ` [billing: API key → Subscription — billing class changed]`.
+ *
+ * This path is NOT the synthetic provider's tier-isolated failover, which is
+ * where the documented "free, paid and subscription tiers never mix" contract
+ * lives (docs/providers-and-routing.md:77-128, enforced in the SDK's
+ * synthetic.ts by CanonicalModel.tier). The optimizer chain consumed here
+ * carries no tier metadata at all — its nodes are
+ * `{ position, providerId, modelId, capable, explanation }` and `explanation`
+ * describes functional capability (streaming, tool calling, context size),
+ * never billing. So the switch cannot be constrained by a tier it cannot see;
+ * what it CAN do is say out loud which billing class it moved to, so a user
+ * who does not want their subscription spent on an automatic retry can object
+ * and turn the optimizer off.
+ *
+ * Classification comes from providers/provider-classification.ts, which is
+ * honest about ignorance: an unrecognised provider id reports "Unknown" rather
+ * than being quietly assumed safe.
+ */
+function buildBillingSuffix(fromProviderId: string, toProviderId: string): string {
+  const from = classifyProviderSetup({ providerId: fromProviderId }).setupLabel;
+  const to = classifyProviderSetup({ providerId: toProviderId }).setupLabel;
+  const changed = from !== to ? ' — billing class changed' : '';
+  return ` [billing: ${from} → ${to}${changed}]`;
+}
+
 /**
  * Wire STREAM_* and TOOL_* runtime events to the provided StreamMetrics object
  * and install the stream-stall watchdog.  The caller owns the metrics object
@@ -273,11 +335,73 @@ export function wireStreamEventMetrics(
   const {
     events, metrics, orchestrator, providerRegistry,
     systemMessageRouter, render, providerOptimizer, retryTurn, costLookup,
-    isApprovalPending, stallThresholdMs,
+    isApprovalPending, stallThresholdMs, failoverState, getConfiguredRegistryKey,
   } = options;
 
   const unsubs: Array<() => void> = [];
 
+  /**
+   * Deliver a provider-switch notice to the conversation unconditionally.
+   * Prefers the router's userReceipt channel, which skips the noise gate and
+   * the ui.operationalMessages routing target entirely, so the line cannot be
+   * filtered away by a preference and is treated as real content even while
+   * the splash still owns the screen. Falls back to high() for bare doubles.
+   */
+  const announce = (message: string): void => {
+    if (systemMessageRouter.userReceipt) systemMessageRouter.userReceipt(message);
+    else systemMessageRouter.high(message);
+  };
+
+  /**
+   * Put serving back on the user's configured selection after a failed-over
+   * turn ends.
+   *
+   * Failover is per-turn recovery, not a permanent re-selection. Without this,
+   * the one setCurrentModel() call that rescued a single failed turn stayed in
+   * force for the rest of the session: every later turn ran on the fallback
+   * backend while nothing in the session state or the footer had changed to
+   * say so. The user's configured selection is authoritative, so the NEXT turn
+   * starts from it again. If that backend is still unhealthy, the normal
+   * per-turn failover handles it again — visibly, with a fresh notice — which
+   * is exactly the behaviour a sticky override was hiding.
+   *
+   * The record is kept (not cleared) when the restore itself fails, so the
+   * header and footer keep reporting the real serving backend rather than
+   * claiming a revert that did not happen.
+   */
+  /**
+   * The registry key the restore below is switching back to, held only across
+   * that one setCurrentModel call. The MODEL_CHANGED listener reads it to keep
+   * the routing chip quiet for this change: the chip's copy is "reason
+   * unknown", which would be false here — the reason is known and the
+   * `[Failover] Restored …` line states it.
+   */
+  let pendingRestoreKey: string | null = null;
+
+  const restoreConfiguredSelection = (): void => {
+    const record = failoverState?.current();
+    if (!record || !failoverState) return;
+    if (providerRegistry.getCurrentModel().registryKey === record.configuredRegistryKey) {
+      failoverState.clear();
+      return;
+    }
+    try {
+      pendingRestoreKey = record.configuredRegistryKey;
+      providerRegistry.setCurrentModel(record.configuredRegistryKey);
+      failoverState.clear();
+      announce(`[Failover] Restored ${record.configuredRegistryKey} for the next turn.`);
+    } catch (restoreErr) {
+      pendingRestoreKey = null;
+      logger.debug('failover restore failed', {
+        configuredRegistryKey: record.configuredRegistryKey, error: String(restoreErr),
+      });
+      announce(
+        `[Failover] Could not switch back to ${record.configuredRegistryKey}; still serving ${record.servingRegistryKey}.`,
+      );
+    }
+    render();
+  };
+
   unsubs.push(events.turns.on('STREAM_START', () => {
     metrics.startTime = Date.now();
     metrics.deltaCount = 0;
@@ -318,8 +442,20 @@ export function wireStreamEventMetrics(
   // (caller clears via clearFailoverVisited(), wired in main.ts).
   const failoverVisited = new Set<string>();
 
+  // Both terminal turn outcomes end the failover's authority over the
+  // registry: a completed turn got its answer, a cancelled one will not.
+  // (TURN_COMPLETED and TURN_ERROR are mutually exclusive per turn in the SDK
+  // — TURN_COMPLETED is emitted only on the success path in
+  // orchestrator-turn-helpers, TURN_ERROR only from the orchestrator's catch —
+  // so restoring here can never undo a switch whose retry has not run yet.)
   unsubs.push(events.turns.on('TURN_COMPLETED', () => {
     failoverVisited.clear();
+    restoreConfiguredSelection();
+  }));
+
+  unsubs.push(events.turns.on('TURN_CANCEL', () => {
+    failoverVisited.clear();
+    restoreConfiguredSelection();
   }));
 
   // Routing chip (never-silent model change): every MODEL_CHANGED that is not
@@ -330,6 +466,11 @@ export function wireStreamEventMetrics(
   // Degrade gracefully when a bare test double omits the providers feed.
   if (events.providers) {
     unsubs.push(events.providers.on('MODEL_CHANGED', (change) => {
+      // Listeners run synchronously inside setCurrentModel, so this reads the
+      // restore flag before anything else can touch it.
+      const wasRestore = pendingRestoreKey !== null && change.registryKey === pendingRestoreKey;
+      pendingRestoreKey = null;
+      if (wasRestore) return;
       queueMicrotask(() => {
         const chip = buildRoutingChip(change, providerOptimizer?.fallbackLog ?? [], Date.now());
         if (chip === null) return;
@@ -373,30 +514,45 @@ export function wireStreamEventMetrics(
         try {
           providerRegistry.setCurrentModel(toRegistryKey);
         } catch (switchErr) {
-          // Switch failed — fall through to honest error display.
+          // Switch failed — fall through to honest error display. This ends the
+          // turn, so an EARLIER hop's switch (if this is a second failover
+          // within the same turn) loses its authority here just as it would on
+          // any other terminal outcome.
           logger.debug('failover setCurrentModel failed', { toRegistryKey, error: String(switchErr) });
           systemMessageRouter.high(`[Error] ${errorClass}`);
+          restoreConfiguredSelection();
           render();
           return;
         }
         // Record the selected provider as visited before the retry fires so
         // a subsequent TURN_ERROR from that provider also skips it.
         failoverVisited.add(next.providerId);
+        // Remember the user's configured selection so the turn-end restore
+        // targets it, and so both shell surfaces can name it while the switch
+        // is in force. Sticky across a second hop within the same turn.
+        const configuredRegistryKey = getConfiguredRegistryKey?.();
+        if (configuredRegistryKey) {
+          failoverState?.begin({ configuredRegistryKey, servingRegistryKey: toRegistryKey });
+        }
         providerOptimizer.recordFallbackTransition(fromProvider, next.providerId, errorClass);
         const costSuffix = buildCostDeltaSuffix(costLookup, fromRegistryKey, toRegistryKey);
-        systemMessageRouter.high(
-          `[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})${costSuffix}`,
-        );
+        const billingSuffix = buildBillingSuffix(fromProvider, next.providerId);
+        // Re-submit the last user turn on the new provider, handing the notice
+        // to retryTurn so it outlives that call's transcript rollback (see the
+        // retryTurn option doc). Emitting it here instead would delete it.
+        retryTurn(`[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})${billingSuffix}${costSuffix}`);
         render();
-        // Re-submit the last user turn on the new provider.
-        retryTurn();
         return;
       }
 
       // Chain exhausted — all capable candidates have been visited or none exist.
-      systemMessageRouter.high(
+      // The turn is over, so any switch made earlier in it loses its authority:
+      // restore the configured selection before surfacing the error, or the
+      // user's next turn would silently start on the last fallback tried.
+      announce(
         `[Failover] Chain exhausted — no alternative provider available. Original error: ${formatUserFacingErrorLine(errVal)}`,
       );
+      restoreConfiguredSelection();
       notifyErrorSurfaced(true);
       render();
       return;
@@ -494,7 +650,11 @@ export function wireStreamEventMetrics(
   function notifyErrorSurfaced(exhausted: boolean) { _errorSurfacedCb?.(exhausted); }
   return {
     unsubs,
-    clearFailoverVisited: () => failoverVisited.clear(),
+    // A new user submission is also a turn boundary: restore here too, so a
+    // turn that ended without any terminal event (an aborted stream that
+    // emitted neither TURN_COMPLETED nor TURN_CANCEL) still cannot leave the
+    // next turn silently pinned to a fallback backend.
+    clearFailoverVisited: () => { failoverVisited.clear(); restoreConfiguredSelection(); },
     onErrorSurfaced: (cb: (exhausted: boolean) => void) => { _errorSurfacedCb = cb; },
   };
 }

package/src/core/system-message-router.ts

@@ -224,6 +224,28 @@ export class SystemMessageRouter {
   wrfc(message: string, priority: SystemMessagePriority = 'high'): void {
     this.routeTypedSystemMessage(message, priority, 'wrfc');
   }
+
+  /**
+   * Route a message that must reach the conversation unconditionally. Skips
+   * the noise gate and the configured routing target, and marks the message
+   * `isUserReceipt` so the splash check in
+   * ConversationManager.rebuildHistory() treats it as real visible content —
+   * otherwise it would be invisible while the splash still owns the screen.
+   *
+   * Two callers qualify today:
+   *   - a receipt for an explicit user action at this shell (answering the
+   *     startup recovery modal's Resume/Keep/Remove choice): the answer to a
+   *     question the user was just asked, never ambient chatter;
+   *   - an automatic provider failover switch (stream-event-wiring.ts):
+   *     which backend serves a turn decides who bills for it, so it must not
+   *     be filterable by a routing preference. `[Failover]` is also in
+   *     FORCE_CONVERSATION_PREFIXES, but that list is a per-prefix opt-in
+   *     applied AFTER the noise gate; this channel is the structural
+   *     guarantee rather than a second string match.
+   */
+  userReceipt(message: string): void {
+    this.conversation.addTypedSystemMessage(message, classifySystemMessageKind(message), { isUserReceipt: true });
+  }
 }
 
 // ---------------------------------------------------------------------------

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();