@pellux/goodvibes-tui 1.20.0 → 1.21.0

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

@@ -1,8 +1,15 @@
 import type { UiRuntimeEvents } from '@/runtime/index.ts';
 import { createStreamStallWatchdog } from './stream-stall-watchdog.ts';
-import { buildRoutingChip } from './model-routing-chip.ts';
+import { buildRoutingChip, FALLBACK_CORRELATION_WINDOW_MS } 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';
+import type { ReasoningEffortSpec } from '@pellux/goodvibes-sdk/platform/providers';
+import {
+  publishActiveEffortOptions,
+  remapEffortForServingModel,
+} from '../providers/reasoning-effort-surface.ts';
 
 /**
  * Live stream and tool-execution metrics maintained by wireStreamEventMetrics.
@@ -73,7 +80,20 @@ interface StreamOrchestrator {
 
 /** Minimal provider surface required for the stream stall watchdog and failover switching. */
 interface StreamProviderRegistry {
-  getCurrentModel(): { readonly provider: string; readonly registryKey?: string };
+  getCurrentModel(): {
+    readonly provider: string;
+    readonly registryKey?: string;
+    /**
+     * Model id, display name and reasoning-effort spec, all optional so a test
+     * double carrying only provider/registryKey still satisfies this surface.
+     * When the id is present the failover path can re-resolve the configured
+     * reasoning level against the model that is about to serve; when it is
+     * absent that step is skipped rather than guessed at.
+     */
+    readonly id?: string;
+    readonly displayName?: string;
+    readonly reasoningEffort?: ReasoningEffortSpec | undefined;
+  };
   setCurrentModel(registryKey: string): void;
 }
 
@@ -101,6 +121,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 +194,21 @@ 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.
+   *
+   * Returns whether the turn was actually re-submitted. False means there was
+   * nothing to retry (no pre-submission snapshot — the failed turn did not
+   * come from the composer) and the notice was NOT posted, so the caller must
+   * narrate the switch and surface the error itself rather than let a turn end
+   * in silence on a backend the user did not choose.
    */
-  readonly retryTurn?: () => void;
+  readonly retryTurn?: (notice?: string) => boolean;
   /**
    * 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 +230,31 @@ 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;
+  /**
+   * The user's configured reasoning level (config `provider.reasoningEffort`).
+   * Read at the moment of a failover switch so the level can be re-resolved
+   * against the model that is about to serve: a level the configured model
+   * offers may not exist on the fallback, and sending it unchanged is how a
+   * failover turns into a provider-side 400 the user cannot explain. Omitted
+   * means the re-resolution is skipped entirely, never guessed.
+   */
+  readonly getConfiguredReasoningEffort?: () => string | undefined;
 }
 
 /** Result of wireStreamEventMetrics. */
@@ -196,10 +262,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 +321,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 +368,149 @@ export function wireStreamEventMetrics(
   const {
     events, metrics, orchestrator, providerRegistry,
     systemMessageRouter, render, providerOptimizer, retryTurn, costLookup,
-    isApprovalPending, stallThresholdMs,
+    isApprovalPending, stallThresholdMs, failoverState, getConfiguredRegistryKey,
+    getConfiguredReasoningEffort,
   } = 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.
+   */
+  /**
+   * Registry keys THIS module switched to and narrated itself, with the time
+   * of the switch. The MODEL_CHANGED listener consumes an entry instead of
+   * emitting the generic routing chip, so neither half of a failover is
+   * narrated twice: the switch out is announced by `[Failover] from -> to
+   * (reason)` and the switch back by `[Failover] Restored …`, and a second
+   * line reading "(reason unknown)" for the same event would be both a
+   * duplicate and a lie — the reason is known in both cases.
+   *
+   * A timestamped map rather than a flag cleared around the setCurrentModel
+   * call, because MODEL_CHANGED does NOT arrive synchronously: the TUI reads
+   * it through the runtime event feed, which delivers after the emitting call
+   * has returned (observed live — a flag cleared in a finally block was always
+   * already null by the time the listener ran, and both failover halves got a
+   * duplicate chip). Entries expire on the same window the fallback-log
+   * correlation uses, so a switch whose event never arrives cannot silence an
+   * unrelated later change to the same model.
+   */
+  const selfNarratedSwitches = new Map<string, number>();
+
+  /**
+   * Run a registry switch this module narrates itself, with the chip suppressed
+   * for it. Returns the effort-remap sentence when the switch changed the level
+   * that goes on the wire, for the CALLER to place — see
+   * reconcileEffortWithServingModel for why it is not announced here.
+   */
+  const switchNarrated = (registryKey: string): string | undefined => {
+    selfNarratedSwitches.set(registryKey, Date.now());
+    try {
+      providerRegistry.setCurrentModel(registryKey);
+    } catch (err) {
+      selfNarratedSwitches.delete(registryKey); // no switch happened, nothing to suppress
+      throw err;
+    }
+    return reconcileEffortWithServingModel();
+  };
+
+  /**
+   * Re-resolve the REQUESTED reasoning level against whichever model is now
+   * serving, and hand back the sentence that says so when it had to change.
+   *
+   * Both halves of a failover come through switchNarrated, so this covers the
+   * switch out and the switch back. The requested level is left untouched in
+   * config — the fallback is temporary and the user's choice must survive it —
+   * but the level actually sent is the resolved one, and the SDK's own sentence
+   * explaining the remap is surfaced verbatim rather than reworded.
+   *
+   * The sentence is RETURNED rather than announced. On the failover-out path
+   * this function runs before retryTurn, and retryTurn rolls the conversation
+   * back to its pre-submission message count — which deleted this notice every
+   * time, exactly as it used to delete the failover notice itself. The caller
+   * folds it into the notice it hands to retryTurn so it survives the rollback;
+   * the restore path, which has no rollback after it, announces it directly.
+   */
+  const reconcileEffortWithServingModel = (): string | undefined => {
+    const serving = providerRegistry.getCurrentModel();
+    if (!serving.id) return undefined; // no model id on this surface: nothing to resolve against
+    const model = {
+      id: serving.id,
+      provider: serving.provider,
+      ...(serving.displayName ? { displayName: serving.displayName } : {}),
+      ...(serving.reasoningEffort ? { reasoningEffort: serving.reasoningEffort } : {}),
+    };
+    publishActiveEffortOptions(model);
+    // getConfiguredReasoningEffort reads config `provider.reasoningEffort` —
+    // the REQUESTED level. It must never be re-seeded from a previously snapped
+    // effective value, or a single failover onto a capped model would ratchet
+    // the level down for the rest of the session.
+    const requested = getConfiguredReasoningEffort?.();
+    if (requested === undefined || requested === '') return undefined;
+    return remapEffortForServingModel(requested, model).note;
+  };
+
+  /** True when this MODEL_CHANGED is one of our own narrated switches (consumes the record). */
+  const wasSelfNarrated = (registryKey: string): boolean => {
+    const narratedAt = selfNarratedSwitches.get(registryKey);
+    if (narratedAt === undefined) return false;
+    selfNarratedSwitches.delete(registryKey);
+    return Date.now() - narratedAt <= FALLBACK_CORRELATION_WINDOW_MS;
+  };
+
+  const restoreConfiguredSelection = (): void => {
+    const record = failoverState?.current();
+    if (!record || !failoverState) return;
+    if (providerRegistry.getCurrentModel().registryKey === record.configuredRegistryKey) {
+      failoverState.clear();
+      return;
+    }
+    try {
+      const effortNote = switchNarrated(record.configuredRegistryKey);
+      failoverState.clear();
+      // Nothing rolls the transcript back after this point, so the restore line
+      // and any effort remap that came with it are announced directly.
+      announce(
+        `[Failover] Restored ${record.configuredRegistryKey} for the next turn.`
+        + (effortNote ? `\n[Failover] ${effortNote}` : ''),
+      );
+    } catch (restoreErr) {
+      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 +551,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 +575,7 @@ 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) => {
+      if (wasSelfNarrated(change.registryKey)) return; // a [Failover] line already said this, with its reason
       queueMicrotask(() => {
         const chip = buildRoutingChip(change, providerOptimizer?.fallbackLog ?? [], Date.now());
         if (chip === null) return;
@@ -370,33 +616,64 @@ export function wireStreamEventMetrics(
         const errorClass = formatUserFacingErrorLine(errVal);
         // Capture FROM registry key before switching — needed for cost comparison.
         const fromRegistryKey = providerRegistry.getCurrentModel().registryKey;
+        // The effort remap that comes with the switch is carried, not announced:
+        // retryTurn's rollback below would delete it (see
+        // reconcileEffortWithServingModel).
+        let effortNote: string | undefined;
         try {
-          providerRegistry.setCurrentModel(toRegistryKey);
+          effortNote = switchNarrated(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.
+        const failoverNotice = `[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})${billingSuffix}${costSuffix}`
+          + (effortNote ? `\n[Failover] ${effortNote}` : '');
+        if (!retryTurn(failoverNotice)) {
+          // No turn to re-submit (the failed turn did not come from the
+          // composer, so there is no pre-submission snapshot to roll back to).
+          // The registry has still MOVED, so the switch gets narrated here and
+          // the original error surfaces — silence would leave the user on a
+          // different backend with no turn running and nothing said about it.
+          announce(failoverNotice);
+          systemMessageRouter.high(`[Error] ${errorClass}`);
+          restoreConfiguredSelection();
+          notifyErrorSurfaced(false);
+        }
         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 +771,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

@@ -62,11 +62,14 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
+  readdirSync,
   renameSync,
+  statSync,
   unlinkSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+import { UNRECOGNIZED_SUFFIX } from '@/config/read-versioned.ts';
 import type { SessionSurface } from '@/runtime/index.ts';
 
 // ─── Constants ──────────────────────────────────────────────────────────────
@@ -320,7 +323,7 @@ class TranscriptJournalImpl implements TranscriptJournal {
   }
 
   private _ensureInitialised(): void {
-    if (this._initialised && existsSync(this.path)) return;
+    if (this._initialised && journalHasContent(this.path)) return;
 
     mkdirSync(dirname(this.path), { recursive: true });
     const header: JournalHeader = {
@@ -328,11 +331,20 @@ class TranscriptJournalImpl implements TranscriptJournal {
       sessionId: this._sessionId,
       createdAt: Date.now(),
     };
-    // Append the header as the first line. If the file already exists (e.g.
-    // process restarted mid-session), we start appending records after
-    // whatever is already there — the replay function handles seq ordering.
-    // However, to keep things clean, if the file doesn't exist we write fresh.
-    if (!existsSync(this.path)) {
+    // Append the header as the first line. If the file already exists with
+    // content (e.g. process restarted mid-session), we start appending records
+    // after whatever is already there — the replay function handles seq
+    // ordering.
+    //
+    // The guard is `journalHasContent`, not `existsSync`: a crash between
+    // creating the file and writing the header leaves a zero-byte journal, and
+    // an existence-only check would then skip the header forever. Every record
+    // appended after that would sit in a header-less file, so the next replay
+    // would read record 0 where the header belongs, fail the version gate, and
+    // quarantine the entire journal — losing exactly the turns this module
+    // exists to preserve. Deciding on content instead means a zero-byte
+    // journal is re-headered and stays replayable.
+    if (!journalHasContent(this.path)) {
       appendFileSync(this.path, JSON.stringify(header) + '\n', { mode: 0o600 });
     }
     this._initialised = true;
@@ -358,8 +370,134 @@ function isValidRecord(value: unknown): value is JournalRecord {
 
 function quarantineJournal(journalPath: string): void {
   try {
-    renameSync(journalPath, `${journalPath}.unrecognized`);
+    renameSync(journalPath, `${journalPath}${UNRECOGNIZED_SUFFIX}`);
   } catch {
     // Best-effort — if rename fails, proceed silently.
   }
 }
+
+/** True when the journal file exists AND holds at least one byte. */
+function journalHasContent(journalPath: string): boolean {
+  try {
+    return statSync(journalPath).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Reaping orphaned journals ──────────────────────────────────────────────
+//
+// `rotate()` deletes a journal once its records have been folded into a
+// snapshot or replayed. A session that crashes and is never resumed never
+// reaches either, so its journal stays on disk forever — one file per
+// abandoned session. The SDK's registered append-only retention sweep does not
+// cover this home-scoped path, so the reclaim happens here.
+
+const JOURNAL_PREFIX = 'transcript-';
+const JOURNAL_SUFFIX = '.journal';
+
+/** How long an untouched journal for a non-live session is kept: 7 days. */
+export const JOURNAL_ORPHAN_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Hard ceiling on reapable journals kept after the age rule, newest kept.
+ * A burst of crashes inside the age window is still bounded.
+ */
+export const JOURNAL_ORPHAN_MAX_FILES = 50;
+
+export interface JournalReapResult {
+  /** Journal files examined this sweep. */
+  readonly scanned: number;
+  /** Journal files deleted this sweep. */
+  readonly reaped: number;
+}
+
+export interface JournalReapOptions {
+  /**
+   * Is this session open in a still-running process? Injected rather than
+   * imported so this module keeps no dependency on the liveness marker — the
+   * composition point (runtime/durability-housekeeping.ts) supplies the real
+   * check, and tests supply their own.
+   */
+  readonly isSessionLive: (sessionId: string) => boolean;
+  /** The session this process is writing right now; never reaped. */
+  readonly currentSessionId?: string | null;
+  readonly now?: () => number;
+  /** Override the age window (tests). */
+  readonly maxAgeMs?: number;
+  /** Override the count cap (tests). */
+  readonly maxFiles?: number;
+}
+
+/**
+ * Delete transcript journals belonging to sessions that crashed and were never
+ * resumed.
+ *
+ * A journal is reapable only when it is neither the current session's nor
+ * apparently open in another running process. Of those, one is deleted when it
+ * is empty (a zero-byte file holds no records, so nothing can be lost) or
+ * untouched for longer than the age window; whatever survives both rules is
+ * then capped by count, newest kept.
+ *
+ * The rules are deliberately mtime- and liveness-based, never parse-based: an
+ * unparseable TAIL is the normal, expected shape of a journal killed
+ * mid-append and is exactly the data replay is there to salvage, so a parse
+ * failure must never make a journal reapable.
+ *
+ * Idempotent and concurrency-safe: a journal another sweeper unlinked between
+ * the listing and this unlink (ENOENT) counts as reaped, not as an error.
+ */
+export function reapOrphanedJournals(surface: SessionSurface, options: JournalReapOptions): JournalReapResult {
+  const dir = join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot);
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((n) => n.startsWith(JOURNAL_PREFIX) && n.endsWith(JOURNAL_SUFFIX));
+  } catch {
+    return { scanned: 0, reaped: 0 };
+  }
+
+  const now = options.now?.() ?? Date.now();
+  const maxAgeMs = options.maxAgeMs ?? JOURNAL_ORPHAN_MAX_AGE_MS;
+  const maxFiles = options.maxFiles ?? JOURNAL_ORPHAN_MAX_FILES;
+
+  let reaped = 0;
+  const survivors: { readonly path: string; readonly mtimeMs: number }[] = [];
+
+  for (const name of names) {
+    const sessionId = name.slice(JOURNAL_PREFIX.length, name.length - JOURNAL_SUFFIX.length);
+    if (sessionId.length === 0) continue;
+    if (options.currentSessionId && sessionId === options.currentSessionId) continue;
+    if (options.isSessionLive(sessionId)) continue;
+
+    const path = join(dir, name);
+    let stats: { size: number; mtimeMs: number };
+    try {
+      stats = statSync(path);
+    } catch {
+      continue; // vanished under us
+    }
+    if (stats.size === 0 || now - stats.mtimeMs > maxAgeMs) {
+      if (unlinkJournalIfPresent(path)) reaped++;
+      continue;
+    }
+    survivors.push({ path, mtimeMs: stats.mtimeMs });
+  }
+
+  if (survivors.length > maxFiles) {
+    survivors.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+    for (const victim of survivors.slice(0, survivors.length - maxFiles)) {
+      if (unlinkJournalIfPresent(victim.path)) reaped++;
+    }
+  }
+
+  return { scanned: names.length, reaped };
+}
+
+function unlinkJournalIfPresent(path: string): boolean {
+  try {
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT';
+  }
+}