@pellux/goodvibes-tui 1.20.1 → 1.21.1

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

@@ -21,7 +21,7 @@
  * `messageCount` boundaries stay valid because a resume rehydrates the same
  * message history the anchors were recorded against.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { SessionSurface } from '@/runtime/index.ts';
 
@@ -92,12 +92,14 @@ export function clearTurnAnchors(sessionId: string): void {
 const ANCHOR_SIDECAR_VERSION = 1;
 
 /** Absolute path to a session's anchor sidecar, or null when inputs are unusable. */
+const ANCHOR_SIDECAR_SUFFIX = '.anchors.json';
+
 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(surface.sessionsDir, `${sessionId}.anchors.json`);
+  return join(surface.sessionsDir, `${sessionId}${ANCHOR_SIDECAR_SUFFIX}`);
 }
 
 function isTurnAnchor(value: unknown): value is TurnAnchor {
@@ -125,7 +127,7 @@ export function persistTurnAnchors(sessionId: string, surface: SessionSurface):
   try {
     mkdirSync(surface.sessionsDir, { recursive: true });
     const payload = JSON.stringify({ version: ANCHOR_SIDECAR_VERSION, sessionId, anchors: list });
-    const tmp = `${path}.tmp-${process.pid}`;
+    const tmp = `${path}${ANCHOR_SIDECAR_TMP_MARKER}${process.pid}`;
     writeFileSync(tmp, payload);
     renameSync(tmp, path);
   } catch {
@@ -157,3 +159,153 @@ export function restoreTurnAnchors(sessionId: string, surface: SessionSurface):
     return 0;
   }
 }
+
+// ─── Reaping orphaned sidecars ────────────────────────────────────────────────
+//
+// A sidecar's OWNER is the session JSONL it sits beside. Deleting a session
+// removes the JSONL but nothing ever removed the sidecar, so anchors for
+// sessions that no longer exist accumulate in the sessions directory forever.
+// The sweep below reclaims them, plus the `.tmp-<pid>` staging files a crash
+// between write and rename leaves behind.
+
+/** Infix for the atomic-write staging file, before the writing process's pid. */
+const ANCHOR_SIDECAR_TMP_MARKER = '.tmp-';
+
+/**
+ * How long a staging file is tolerated before it is treated as crash residue:
+ * 1 hour. `persistTurnAnchors` renames within microseconds of writing, so
+ * anything this old was interrupted, and the completed sidecar (if the write
+ * ever finished) is a separate file.
+ */
+export const ANCHOR_TMP_MAX_AGE_MS = 60 * 60 * 1000;
+
+/**
+ * How settled a sidecar must be before this sweep will delete it: 1 hour.
+ *
+ * Another instance can be persisting anchors for a session this process knows
+ * nothing about, and the window between reading a sidecar's content and
+ * unlinking it is not atomic. Requiring the file to have been untouched for an
+ * hour means a sidecar that some other instance is actively rewriting is never
+ * a candidate, while genuine residue — whose writer is long gone — always is.
+ * The sweep repeats, so the delay costs nothing.
+ */
+export const ANCHOR_SIDECAR_SETTLE_MS = 60 * 60 * 1000;
+
+export interface AnchorSidecarReapResult {
+  /** Sidecar and staging files examined this sweep. */
+  readonly scanned: number;
+  /** Files deleted this sweep. */
+  readonly reaped: number;
+}
+
+export interface AnchorSidecarReapOptions {
+  /** The session this process is using right now; its sidecar is never reaped. */
+  readonly currentSessionId?: string | null;
+  readonly now?: () => number;
+  /** Override the staging-file age window (tests). */
+  readonly tmpMaxAgeMs?: number;
+  /** Override how long a sidecar must be untouched before it can be reaped (tests). */
+  readonly settleMs?: number;
+}
+
+/**
+ * Delete anchor sidecars whose owning session file is gone, sidecars that hold
+ * nothing readable, and abandoned staging files.
+ *
+ * A sidecar survives when `<sessionsDir>/<sessionId>.jsonl` still exists AND
+ * the sidecar itself parses into at least one usable anchor — content, not
+ * mere existence, because a sidecar truncated by a crash restores nothing and
+ * would otherwise sit there indefinitely looking like valid state. It also
+ * survives while it is still fresh (see `ANCHOR_SIDECAR_SETTLE_MS`), which
+ * keeps a sidecar another instance is mid-rewrite out of reach.
+ *
+ * The current session's sidecar is never touched, and an unreadable or absent
+ * sessions directory simply reclaims nothing. Idempotent and concurrency-safe:
+ * a file another sweeper unlinked first (ENOENT) counts as reaped.
+ */
+export function reapOrphanedAnchorSidecars(
+  surface: SessionSurface,
+  options: AnchorSidecarReapOptions = {},
+): AnchorSidecarReapResult {
+  const dir = surface.sessionsDir;
+  if (!dir) return { scanned: 0, reaped: 0 };
+
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter(
+      (n) => n.endsWith(ANCHOR_SIDECAR_SUFFIX) || n.includes(`${ANCHOR_SIDECAR_SUFFIX}${ANCHOR_SIDECAR_TMP_MARKER}`),
+    );
+  } catch {
+    return { scanned: 0, reaped: 0 };
+  }
+
+  const now = options.now?.() ?? Date.now();
+  const tmpMaxAgeMs = options.tmpMaxAgeMs ?? ANCHOR_TMP_MAX_AGE_MS;
+  const settleMs = options.settleMs ?? ANCHOR_SIDECAR_SETTLE_MS;
+  let reaped = 0;
+
+  for (const name of names) {
+    const path = join(dir, name);
+
+    if (!name.endsWith(ANCHOR_SIDECAR_SUFFIX)) {
+      // A `<sessionId>.anchors.json.tmp-<pid>` staging file. Age alone decides:
+      // a young one may belong to another instance's in-flight write.
+      let mtimeMs: number;
+      try {
+        mtimeMs = statSync(path).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (now - mtimeMs > tmpMaxAgeMs && unlinkAnchorFile(path)) reaped++;
+      continue;
+    }
+
+    const sessionId = name.slice(0, name.length - ANCHOR_SIDECAR_SUFFIX.length);
+    if (sessionId.length === 0) continue;
+    if (options.currentSessionId && sessionId === options.currentSessionId) continue;
+
+    // A sidecar written moments ago belongs to a writer that is still around —
+    // possibly another instance whose session this process cannot see.
+    let sidecarMtimeMs: number;
+    try {
+      sidecarMtimeMs = statSync(path).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (now - sidecarMtimeMs <= settleMs) continue;
+
+    if (!existsSync(join(dir, `${sessionId}.jsonl`))) {
+      // The owning session is gone — this sidecar can never be used again.
+      if (unlinkAnchorFile(path)) reaped++;
+      continue;
+    }
+    if (!sidecarHoldsAnchors(path)) {
+      // The session survives but the sidecar is empty or torn: it restores
+      // nothing, so keeping it only hides the loss.
+      if (unlinkAnchorFile(path)) reaped++;
+    }
+  }
+
+  return { scanned: names.length, reaped };
+}
+
+/** Content check: does this sidecar parse into at least one usable anchor? */
+function sidecarHoldsAnchors(path: string): boolean {
+  try {
+    const text = readFileSync(path, 'utf8');
+    if (text.trim().length === 0) return false;
+    const parsed = JSON.parse(text) as { anchors?: unknown };
+    return Array.isArray(parsed?.anchors) && parsed.anchors.some(isTurnAnchor);
+  } catch {
+    return false;
+  }
+}
+
+function unlinkAnchorFile(path: string): boolean {
+  try {
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT';
+  }
+}

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

@@ -1,10 +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.
@@ -75,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;
 }
 
@@ -183,8 +201,14 @@ export interface WireStreamEventMetricsOptions {
    * 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?: (notice?: string) => 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,
@@ -222,6 +246,15 @@ export interface WireStreamEventMetricsOptions {
    * 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. */
@@ -336,6 +369,7 @@ export function wireStreamEventMetrics(
     events, metrics, orchestrator, providerRegistry,
     systemMessageRouter, render, providerOptimizer, retryTurn, costLookup,
     isApprovalPending, stallThresholdMs, failoverState, getConfiguredRegistryKey,
+    getConfiguredReasoningEffort,
   } = options;
 
   const unsubs: Array<() => void> = [];
@@ -370,13 +404,85 @@ export function wireStreamEventMetrics(
    * 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.
+   * 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.
    */
-  let pendingRestoreKey: string | null = null;
+  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();
@@ -386,12 +492,15 @@ export function wireStreamEventMetrics(
       return;
     }
     try {
-      pendingRestoreKey = record.configuredRegistryKey;
-      providerRegistry.setCurrentModel(record.configuredRegistryKey);
+      const effortNote = switchNarrated(record.configuredRegistryKey);
       failoverState.clear();
-      announce(`[Failover] Restored ${record.configuredRegistryKey} for the next turn.`);
+      // 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) {
-      pendingRestoreKey = null;
       logger.debug('failover restore failed', {
         configuredRegistryKey: record.configuredRegistryKey, error: String(restoreErr),
       });
@@ -466,11 +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) => {
-      // 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;
+      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;
@@ -511,8 +616,12 @@ 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. This ends the
           // turn, so an EARLIER hop's switch (if this is a second failover
@@ -540,7 +649,19 @@ export function wireStreamEventMetrics(
         // 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}`);
+        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();
         return;
       }

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