@pellux/goodvibes-tui 1.20.1 → 1.21.0

package/src/config/read-versioned.ts

@@ -1,4 +1,12 @@
-import { existsSync, readFileSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The suffix every quarantined file in this codebase gets. Exported so the
+ * other producer of these files (the transcript journal's corrupt-tail
+ * quarantine) and the reclaim sweep below all agree on one spelling.
+ */
+export const UNRECOGNIZED_SUFFIX = '.unrecognized';
 
 /**
  * A migration function that transforms data from version N to N+1.
@@ -108,8 +116,113 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 
 function quarantine(path: string): void {
   try {
-    renameSync(path, `${path}.unrecognized`);
+    renameSync(path, `${path}${UNRECOGNIZED_SUFFIX}`);
   } catch {
     // Best-effort — if rename fails (e.g. race), proceed silently.
   }
 }
+
+// ─── Quarantine reclaim ───────────────────────────────────────────────────────
+//
+// Quarantining renames a bad file out of the way so a human can inspect it,
+// and until now nothing ever removed the result — every corrupt config file
+// and every torn journal tail left a `.unrecognized` file behind permanently.
+// Forensic value is real, so the retention window below is deliberately long,
+// but "keep forever" is a leak.
+
+/**
+ * How long a quarantined file is kept before it is reclaimed: 30 days
+ * (2_592_000_000 ms). These files exist so a person can look at what went
+ * wrong, so the window is a month rather than the hours-to-days retention the
+ * live durability artefacts get — long enough to survive a holiday, short
+ * enough that a recurring corruption cannot fill a disk.
+ */
+export const QUARANTINE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * Hard ceiling on quarantined files kept per swept directory, newest kept.
+ * The age rule alone cannot bound a fast repeating corruption (a boot loop
+ * quarantining the same file every restart), so a count cap runs alongside it.
+ */
+export const QUARANTINE_MAX_FILES_PER_DIR = 50;
+
+export interface QuarantineReapResult {
+  /** Quarantined files examined across every directory. */
+  readonly scanned: number;
+  /** Quarantined files deleted. */
+  readonly reaped: number;
+}
+
+export interface QuarantineReapOptions {
+  readonly now?: () => number;
+  /** Override the age window (tests). */
+  readonly maxAgeMs?: number;
+  /** Override the per-directory count cap (tests). */
+  readonly maxFilesPerDir?: number;
+}
+
+/**
+ * Delete `.unrecognized` quarantine files that are past the retention window,
+ * plus any beyond the per-directory count cap (newest kept).
+ *
+ * Each directory is scanned non-recursively; a missing or unreadable directory
+ * contributes nothing and is not an error. Idempotent, and safe to run
+ * concurrently from several processes — a file another sweeper already
+ * unlinked (ENOENT) counts as reclaimed rather than failing the sweep.
+ */
+export function reapQuarantinedFiles(
+  directories: readonly string[],
+  options: QuarantineReapOptions = {},
+): QuarantineReapResult {
+  const now = options.now?.() ?? Date.now();
+  const maxAgeMs = options.maxAgeMs ?? QUARANTINE_RETENTION_MS;
+  const maxFilesPerDir = options.maxFilesPerDir ?? QUARANTINE_MAX_FILES_PER_DIR;
+
+  let scanned = 0;
+  let reaped = 0;
+
+  for (const dir of new Set(directories)) {
+    let names: string[];
+    try {
+      names = readdirSync(dir).filter((name) => name.endsWith(UNRECOGNIZED_SUFFIX));
+    } catch {
+      continue;
+    }
+    scanned += names.length;
+
+    const survivors: { readonly path: string; readonly mtimeMs: number }[] = [];
+    for (const name of names) {
+      const path = join(dir, name);
+      let mtimeMs: number;
+      try {
+        mtimeMs = statSync(path).mtimeMs;
+      } catch {
+        // Vanished under us (another sweeper) — nothing left to reclaim.
+        continue;
+      }
+      if (now - mtimeMs > maxAgeMs) {
+        if (unlinkQuarantined(path)) reaped++;
+        continue;
+      }
+      survivors.push({ path, mtimeMs });
+    }
+
+    if (survivors.length > maxFilesPerDir) {
+      survivors.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+      for (const victim of survivors.slice(0, survivors.length - maxFilesPerDir)) {
+        if (unlinkQuarantined(victim.path)) reaped++;
+      }
+    }
+  }
+
+  return { scanned, reaped };
+}
+
+function unlinkQuarantined(path: string): boolean {
+  try {
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT';
+  }
+}

package/src/core/conversation-event-navigation.ts

@@ -0,0 +1,42 @@
+/**
+ * conversation-event-navigation.ts — resolving "jump to the next/previous
+ * transcript event" into a history-buffer line number.
+ *
+ * Extracted from ConversationManager (core/conversation.ts), which is at its
+ * line-count gate, and kept structural (no SDK imports beyond the event kind)
+ * so the ordering rule can be tested without building a conversation.
+ *
+ * The rule both directions share: take the events of the requested kind, map
+ * each to the line its message was rendered at, drop the ones that were never
+ * rendered (a message with no registry entry), sort ascending, then wrap —
+ * searching forward past `currentLine` falls back to the first line, searching
+ * backward falls back to the last. -1 means there is nowhere to go.
+ */
+
+import type { TranscriptEventKind } from '@pellux/goodvibes-sdk/platform/core';
+
+/** The subset of a transcript-event-index entry this module reads. */
+export interface TranscriptEventLike {
+  readonly kind: TranscriptEventKind;
+  readonly messageIndex: number;
+}
+
+export function resolveTranscriptEventLine(
+  events: readonly TranscriptEventLike[],
+  kind: TranscriptEventKind | 'all',
+  messageLineRegistry: readonly (number | undefined)[],
+  currentLine: number,
+  direction: 'next' | 'prev',
+): number {
+  const selected = kind === 'all' ? events : events.filter((event) => event.kind === kind);
+  if (selected.length === 0) return -1;
+  const lines = selected
+    .map((event) => messageLineRegistry[event.messageIndex] ?? -1)
+    .filter((line) => line >= 0)
+    .sort((a, b) => a - b);
+  if (lines.length === 0) return -1;
+  if (direction === 'next') {
+    return lines.find((line) => line > currentLine) ?? lines[0]!;
+  }
+  return [...lines].reverse().find((line) => line < currentLine) ?? lines[lines.length - 1]!;
+}

package/src/core/conversation-search-expansion.ts

@@ -0,0 +1,67 @@
+/**
+ * conversation-search-expansion.ts — tracks which collapse keys transcript
+ * search auto-expanded so they can be restored on search close, unless the
+ * user explicitly acted on the block while it was open.
+ *
+ * Extracted from conversation.ts to keep that file under the architecture
+ * line-count gate. restoreOnto() applies restoration through a structural
+ * `{ setCollapsed }` shape (ConversationManager's own public setCollapsed())
+ * rather than importing ConversationManager itself, so this module has no
+ * import-cycle back to conversation.ts.
+ *
+ * The contract (see SearchManager.revealCurrentMatch and .close in
+ * search.ts): a single keystroke in the search field must never expand
+ * collapsed content — only navigating TO a match hidden inside it does, and
+ * that expansion is undone when search closes UNLESS the user separately
+ * touched the block (toggled, copied, bookmarked, saved, or bulk-expanded
+ * via /expand) while it sat auto-expanded. An explicit user action always
+ * wins over search's own bookkeeping, regardless of which happened first.
+ */
+
+/** Structural shape restoreOnto() needs — matches ConversationManager's own
+ *  public setCollapsed() without importing the class (avoids a cycle). */
+export interface CollapseSettable {
+  setCollapsed(collapseKey: string, collapsed: boolean): void;
+}
+
+export class SearchExpansionTracker {
+  /**
+   * Collapse keys currently expanded because the user navigated to a search
+   * match hidden inside them. Never contains a key the user has touched
+   * explicitly — noteUserTouch() removes it on the way in.
+   */
+  private searchExpandedKeys = new Set<string>();
+
+  /**
+   * Collapse keys the user has explicitly acted on at least once. Growth is
+   * unbounded for the life of the conversation — membership only ever gates
+   * one decision (whether restoreSearchExpansions() may re-collapse a key),
+   * so a stale positive is harmless and pruning would add complexity for no
+   * behavioral gain.
+   */
+  private userTouchedKeys = new Set<string>();
+
+  /** Record that `collapseKey` was expanded because the user navigated to a
+   *  search match hidden inside it. No-op for a key the user already
+   *  touched explicitly, since that ownership always wins. */
+  markSearchExpanded(collapseKey: string): void {
+    if (!this.userTouchedKeys.has(collapseKey)) this.searchExpandedKeys.add(collapseKey);
+  }
+
+  /** Record an explicit user action on `collapseKey` (toggle/copy/bookmark/
+   *  save/bulk-expand). Exempts it from restoreSearchExpansions()'s
+   *  auto-re-collapse for the rest of the session. */
+  noteUserTouch(collapseKey: string): void {
+    this.userTouchedKeys.add(collapseKey);
+    this.searchExpandedKeys.delete(collapseKey);
+  }
+
+  /** Re-collapse every key search auto-expanded and not since user-touched,
+   *  through `conversationManager`'s public setCollapsed() — called from
+   *  SearchManager.close() to restore pre-search collapse state. */
+  restoreOnto(conversationManager: CollapseSettable): void {
+    const keys = [...this.searchExpandedKeys];
+    this.searchExpandedKeys.clear();
+    for (const key of keys) conversationManager.setCollapsed(key, true);
+  }
+}

package/src/core/conversation-splash-state.ts

@@ -0,0 +1,58 @@
+/**
+ * conversation-splash-state.ts — when the splash owns the conversation area,
+ * and what has to happen the moment it stops.
+ *
+ * Two pieces of state, kept out of ConversationManager (core/conversation.ts,
+ * already at its line-count gate) and out of `suppressSplash`, which is a
+ * per-frame posture the panel workspace sets both ways on every render:
+ *
+ *   - `dismissed` — sticky for the run. Owner rule: the splash yields to ANY
+ *     submission, a chat message or a slash command alike. A slash command
+ *     whose whole output is a modal (or nothing) still means the session has
+ *     started, so the splash must not reappear underneath it, and must not
+ *     come back in the gap before the first reply arrives.
+ *
+ *   - the splash→transcript EDGE — latched when a rebuild that would have
+ *     drawn the splash draws transcript content instead. The shell consumes
+ *     it to repaint the whole viewport for that one frame. Without that, the
+ *     differential renderer only rewrites rows it knows changed, so every row
+ *     the incoming transcript does not cover keeps showing splash art: rule
+ *     lines, the hint line, and half-overwritten rows where a short transcript
+ *     line collides with the tail of a longer splash line.
+ */
+export class SplashGateState {
+  private dismissedForRun = false;
+  private onScreen = false;
+  private yielded = false;
+
+  /** True once the run's first submission has retired the splash. */
+  get dismissed(): boolean {
+    return this.dismissedForRun;
+  }
+
+  /** Retire the splash for the run. Returns true when this call changed anything. */
+  dismiss(): boolean {
+    if (this.dismissedForRun) return false;
+    this.dismissedForRun = true;
+    return true;
+  }
+
+  /** Record that this rebuild drew the splash. */
+  enter(): void {
+    this.onScreen = true;
+  }
+
+  /** Record that this rebuild drew transcript content; latches the edge. */
+  leave(): void {
+    if (!this.onScreen) return;
+    this.onScreen = false;
+    this.yielded = true;
+  }
+
+  /** True exactly once per splash→transcript transition. */
+  consumeTransition(): boolean {
+    const transition = this.yielded;
+    this.yielded = false;
+    return transition;
+  }
+}

package/src/core/conversation.ts

@@ -5,8 +5,7 @@ import type { ToolCall, ToolResult } from '@pellux/goodvibes-sdk/platform/types'
 import type { ProviderMessage, ContentPart } from '@pellux/goodvibes-sdk/platform/providers';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { TranscriptEventKind } from '@pellux/goodvibes-sdk/platform/core';
-// SystemMessageKind imported from runtime directly to avoid cycle:
-//   conversation.ts → system-message-router.ts → conversation.ts
+// SystemMessageKind imported from runtime directly to avoid cycle: conversation.ts → system-message-router.ts → conversation.ts
 import type { SystemMessageKind } from '@/runtime/index.ts';
 import {
   ConversationManager as SdkConversationManager,
@@ -15,6 +14,9 @@ import {
 import type { BlockMeta } from './conversation-types.ts';
 import { MessageLineCache } from './conversation-line-cache.ts';
 import { UserReceiptIndices } from './conversation-user-receipts.ts';
+import { SplashGateState } from './conversation-splash-state.ts';
+import { resolveTranscriptEventLine } from './conversation-event-navigation.ts';
+import { SearchExpansionTracker } from './conversation-search-expansion.ts';
 import {
   addConversationSplashScreen,
   conversationTextToLines,
@@ -111,6 +113,7 @@ export class ConversationManager extends SdkConversationManager {
   private _configManager: ConfigManager | null = null;
   /** Collapse state: stable key (msg_N) -> collapsed (true = collapsed). */
   private collapseState: Map<string, boolean> = new Map();
+  public readonly searchExpansion = new SearchExpansionTracker();
   /** Block registry: track rendered blocks for copy/apply. */
   protected blockRegistry: BlockMeta[] = [];
   /**
@@ -167,6 +170,8 @@ export class ConversationManager extends SdkConversationManager {
 
   public suppressSplash: boolean = false;
   public splashOptions: SplashOptions = {};
+  /** Run-sticky dismissal + the splash→transcript edge (conversation-splash-state.ts). */
+  private readonly splashGate = new SplashGateState();
 
   constructor(
     getWidth: () => number = () => process.stdout.columns || 80,
@@ -488,10 +493,12 @@ export class ConversationManager extends SdkConversationManager {
       return true;
     });
 
-    if (displayMessages.length === 0 && displayStart === 0 && !this.suppressSplash) {
+    if (displayMessages.length === 0 && displayStart === 0 && !this.suppressSplash && !this.splashGate.dismissed) {
       this.addSplashScreen(width);
+      this.splashGate.enter();
       return;
     }
+    this.splashGate.leave(); // latches the splash→transcript edge for consumeSplashTransition()
 
     // The in-progress streaming placeholder (rendered EMPTY above via
     // renderSnapshot) is left uncached: its content mutates in place per delta and
@@ -643,6 +650,7 @@ export class ConversationManager extends SdkConversationManager {
     if (!nearest) return -1;
     const current = this.collapseState.get(nearest.collapseKey) ?? false;
     this.collapseState.set(nearest.collapseKey, !current);
+    this.searchExpansion.noteUserTouch(nearest.collapseKey);
     this.markDirty();
     return nearest.blockIndex;
   }
@@ -704,30 +712,12 @@ export class ConversationManager extends SdkConversationManager {
 
   public nextTranscriptEventLine(currentLine: number, kind: TranscriptEventKind | 'all' = 'all'): number {
     this.flushHistory();
-    const index = this.getTranscriptEventIndex();
-    const events = kind === 'all' ? index.events : index.events.filter((event) => event.kind === kind);
-    if (events.length === 0) return -1;
-    const lines = events
-      .map((event) => this.messageLineRegistry[event.messageIndex] ?? -1)
-      .filter((line) => line >= 0)
-      .sort((a, b) => a - b);
-    if (lines.length === 0) return -1;
-    const after = lines.find((line) => line > currentLine);
-    return after ?? lines[0]!;
+    return resolveTranscriptEventLine(this.getTranscriptEventIndex().events, kind, this.messageLineRegistry, currentLine, 'next');
   }
 
   public prevTranscriptEventLine(currentLine: number, kind: TranscriptEventKind | 'all' = 'all'): number {
     this.flushHistory();
-    const index = this.getTranscriptEventIndex();
-    const events = kind === 'all' ? index.events : index.events.filter((event) => event.kind === kind);
-    if (events.length === 0) return -1;
-    const lines = events
-      .map((event) => this.messageLineRegistry[event.messageIndex] ?? -1)
-      .filter((line) => line >= 0)
-      .sort((a, b) => a - b);
-    if (lines.length === 0) return -1;
-    const before = [...lines].reverse().find((line) => line < currentLine);
-    return before ?? lines[lines.length - 1]!;
+    return resolveTranscriptEventLine(this.getTranscriptEventIndex().events, kind, this.messageLineRegistry, currentLine, 'prev');
   }
 
   public setSplashSuppressed(suppressed: boolean): void {
@@ -736,6 +726,16 @@ export class ConversationManager extends SdkConversationManager {
     this.markDirty();
   }
 
+  /** Retire the splash for the run — any submission does it (SplashGateState). */
+  public dismissSplash(): void {
+    if (this.splashGate.dismiss()) this.markDirty();
+  }
+
+  /** True once, on the frame the splash gives way to transcript content. */
+  public consumeSplashTransition(): boolean {
+    return this.splashGate.consumeTransition();
+  }
+
   private addSplashScreen(width: number): void {
     addConversationSplashScreen(this.renderingContext(), width);
   }

package/src/core/model-routing-chip.ts

@@ -9,18 +9,22 @@
  * narration of their own.
  *
  * Division of labour with the failover path: the optimizer-gated failover in
- * stream-event-wiring.ts already renders a richer `[Failover] from → to
- * (reason)(+cost)` line AND records the transition into the optimizer's
- * fallback log. So when a MODEL_CHANGED correlates to a just-recorded fallback
- * transition, this chip stays silent (buildRoutingChip returns null) — the
- * [Failover] line already narrated that exact change with its real reason.
- * Every other change is surfaced here.
+ * stream-event-wiring.ts renders a richer `[Failover] from → to
+ * (reason)(+cost)` line for the switches it makes itself, and tells this
+ * listener so directly (see the self-narrated guard there) rather than relying
+ * on this module to infer it. Those changes never reach buildRoutingChip.
  *
- * Reason honesty: for the paths this chip surfaces the routing layer exposes no
- * machine-readable reason (a deliberate user switch has none; an SDK-internal
- * downgrade does not thread one to the TUI), so the notice states "reason
- * unknown" rather than omitting the change — per the honesty rule that a change
- * with no explanation is still reported, just marked unknown.
+ * Reason honesty, in three tiers:
+ *   1. a change the failover path already narrated → not offered here at all;
+ *   2. a change that correlates to a transition in the optimizer's fallback
+ *      log → the log's own reason is quoted, because the reason IS known. The
+ *      log is shared: the TUI's failover records provider ids ("abacusai"),
+ *      the SDK's agent-orchestrator fallback records registry keys
+ *      ("abacusai:route-llm"), and a match on either form counts. Reading only
+ *      one form is what made a real, explained failover print
+ *      "(reason unknown)";
+ *   3. no correlation → "(reason unknown)", because a change with no
+ *      explanation is still reported, just honestly marked as unexplained.
  */
 
 /** The subset of a FallbackTransition this module reads (structural, SDK-agnostic). */
@@ -44,9 +48,22 @@ export const FALLBACK_CORRELATION_WINDOW_MS = 4_000;
 /** The forced conversation prefix so the notice is never gated as noise or routed away. */
 export const ROUTING_CHIP_PREFIX = '[Routing]';
 
+/**
+ * The provider id of a fallback-log endpoint, which may be written either as a
+ * bare provider id or as a `provider:model` registry key depending on which
+ * writer recorded it. Everything before the first ':' is the provider in both
+ * forms, so one rule reads both.
+ */
+function providerOf(endpoint: string): string {
+  const separator = endpoint.indexOf(':');
+  return separator === -1 ? endpoint : endpoint.slice(0, separator);
+}
+
 /**
  * Most recent fallback-log reason for a from→to provider transition within the
  * correlation window, or null. Scans newest-first so the freshest transition wins.
+ * Endpoints are compared by provider id, so entries recorded as registry keys
+ * correlate exactly like entries recorded as bare provider ids.
  */
 export function findRecentFallbackReason(
   fallbackLog: readonly FallbackTransitionLike[],
@@ -57,17 +74,20 @@ export function findRecentFallbackReason(
 ): string | null {
   for (let i = fallbackLog.length - 1; i >= 0; i--) {
     const t = fallbackLog[i]!;
-    if (t.from === fromProvider && t.to === toProvider && now - t.ts <= windowMs) return t.reason;
+    if (providerOf(t.from) === providerOf(fromProvider)
+      && providerOf(t.to) === providerOf(toProvider)
+      && now - t.ts <= windowMs) return t.reason;
   }
   return null;
 }
 
 /**
  * The routing-chip line to emit for a MODEL_CHANGED event, or null to stay
- * silent. Null only when there is no real change (no/same previous model) or
- * when the change was a failover already narrated by its own [Failover] line
- * (correlated via the fallback log). Otherwise returns the honest
- * `[Routing] model changed: old → new (reason unknown)` notice.
+ * silent. Null only when there is no real change (no/same previous model) —
+ * changes the failover path narrates itself never reach this function.
+ *
+ * A change that correlates to a logged fallback transition is reported WITH
+ * that transition's reason; anything else is reported as "reason unknown".
  */
 export function buildRoutingChip(
   change: ModelChangedLike,
@@ -77,6 +97,6 @@ export function buildRoutingChip(
   const prev = change.previous;
   if (!prev || prev.registryKey === change.registryKey) return null;
   const failoverReason = findRecentFallbackReason(fallbackLog, prev.provider, change.provider, now);
-  if (failoverReason !== null) return null; // [Failover] already narrated this transition
-  return `${ROUTING_CHIP_PREFIX} model changed: ${prev.registryKey} → ${change.registryKey} (reason unknown)`;
+  const reason = failoverReason === null ? 'reason unknown' : `failover: ${failoverReason}`;
+  return `${ROUTING_CHIP_PREFIX} model changed: ${prev.registryKey} → ${change.registryKey} (${reason})`;
 }