@pellux/goodvibes-tui 1.20.1 → 1.21.0

package/src/renderer/markdown.ts

@@ -4,6 +4,12 @@ import { renderCodeBlock } from './code-block.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
 import { LAYOUT } from './layout.ts';
 import { activeTheme } from './theme.ts';
+import { renderInlineMarkdown, type InlineToken } from './markdown-inline.ts';
+import { isLikelyTableHeaderRow, isLikelyTableSeparatorRow, renderTable } from './markdown-table.ts';
+
+// Re-exported so existing importers of renderInlineMarkdown keep working after
+// the tokenizer moved to markdown-inline.ts (see that module's header).
+export { renderInlineMarkdown, type InlineToken };
 
 // Transcript tokens are read live per render (const T = activeTheme() at the top
 // of each render function below) so a dark→light repaint re-resolves with no
@@ -15,27 +21,6 @@ export interface MarkdownRenderOptions {
   isStreaming?: boolean;
 }
 
-/** Module-level set of inline markdown special characters (hoisted out of hot loop). */
-const INLINE_SPECIAL_CHARS = new Set(['[', '`', '*', '_', '~']);
-
-function splitTableCells(row: string): string[] {
-  const cells = row.trim().split('|').map((c) => c.trim());
-  if (cells.length > 0 && cells[0] === '') cells.shift();
-  if (cells.length > 0 && cells[cells.length - 1] === '') cells.pop();
-  return cells;
-}
-
-function isLikelyTableSeparatorRow(row: string): boolean {
-  if (!row.includes('|')) return false;
-  const cells = splitTableCells(row);
-  if (cells.length === 0) return false;
-  return cells.every((cell) => /:?-{3,}:?/.test(cell));
-}
-
-function isLikelyTableHeaderRow(row: string): boolean {
-  return splitTableCells(row).length >= 2;
-}
-
 /**
  * renderMarkdown - Parse markdown text into styled Line[].
  * Thin wrapper over renderMarkdownTracked for callers that don't need code-block metadata.
@@ -220,320 +205,6 @@ export function renderMarkdownTracked(
   return { lines, codeBlocks };
 }
 
-/**
- * Strip markdown formatting from text for width measurement.
- * Removes **, *, `, ~~ markers but keeps the inner text.
- */
-function stripMarkdown(text: string): string {
-  return text
-    .replace(/\*\*(.+?)\*\*/g, '$1')  // bold
-    .replace(/\*(.+?)\*/g, '$1')      // italic
-    .replace(/~~(.+?)~~/g, '$1')      // strikethrough
-    .replace(/`(.+?)`/g, '$1');       // inline code
-}
-
-/**
- * Render a markdown table with box-drawing borders.
- * Parses inline markdown in cells, fits to terminal width,
- * truncates long content, and renders with proper styling.
- */
-function renderTable(rows: string[], width: number, indent: number): Line[] {
-  const T = activeTheme();
-  const lines: Line[] = [];
-
-  // Parse rows into cells, skip separator
-  const parsedRows: string[][] = [];
-  let hasSeparator = false;
-  for (const row of rows) {
-    const trimmed = row.trim();
-    if (isLikelyTableSeparatorRow(trimmed)) {
-      hasSeparator = true;
-      continue;
-    }
-    const cells = splitTableCells(trimmed);
-    if (cells.length > 0) parsedRows.push(cells);
-  }
-
-  if (parsedRows.length === 0) return lines;
-
-  const colCount = Math.max(...parsedRows.map(r => r.length));
-  const availW = width - indent;
-
-  // Measure column widths using stripped text (no markdown markers)
-  const naturalWidths: number[] = new Array(colCount).fill(0);
-  for (const row of parsedRows) {
-    for (let c = 0; c < row.length; c++) {
-      naturalWidths[c] = Math.max(naturalWidths[c], getDisplayWidth(stripMarkdown(row[c])));
-    }
-  }
-
-  // Budget: availW minus borders (colCount+1) minus padding (2 per col)
-  const overhead = (colCount + 1) + (colCount * 2);
-  const contentBudget = Math.max(colCount, availW - overhead);
-  const totalNatural = naturalWidths.reduce((a, b) => a + b, 0);
-
-  // Compute final column widths
-  const colWidths: number[] = new Array(colCount).fill(0);
-  if (totalNatural <= contentBudget) {
-    // Everything fits
-    for (let c = 0; c < colCount; c++) colWidths[c] = naturalWidths[c];
-  } else {
-    // Proportionally shrink, with minimum of 4 chars per column
-    const minW = 4;
-    for (let c = 0; c < colCount; c++) {
-      colWidths[c] = Math.max(minW, Math.floor((naturalWidths[c] / totalNatural) * contentBudget));
-    }
-    // Distribute leftover from rounding
-    let used = colWidths.reduce((a, b) => a + b, 0);
-    for (let c = 0; c < colCount && used < contentBudget; c++) {
-      colWidths[c]++;
-      used++;
-    }
-  }
-
-  const bc = '240'; // border color
-
-  // Helper: build a border line
-  const makeBorder = (left: string, mid: string, right: string, horiz: string): Line => {
-    let s = ' '.repeat(indent) + left;
-    for (let c = 0; c < colCount; c++) {
-      s += horiz.repeat(colWidths[c] + 2) + (c < colCount - 1 ? mid : right);
-    }
-    return UIFactory.stringToLine(s, width, { fg: bc });
-  };
-
-  // Helper: render a cell's content with inline markdown into Cell[]
-  const renderCellContent = (raw: string, maxW: number, isHdr: boolean): Cell[] => {
-    const cells: Cell[] = [];
-    const tokens = renderInlineMarkdown(raw);
-    let w = 0;
-
-    for (const token of tokens) {
-      const text = token.text;
-      for (const ch of text) {
-        const cw = getDisplayWidth(ch);
-        if (w + cw > maxW) {
-          // Truncate with ellipsis. If the last cell pushed is a wide-glyph
-          // placeholder (the empty second column of a 2-wide character),
-          // overwriting it in place would leave the wide glyph's first
-          // column dangling next to the ellipsis with no placeholder cell \u2014
-          // step back one more cell so the ellipsis replaces the actual
-          // glyph, not its placeholder.
-          if (cells.length > 0 && cells[cells.length - 1].char === '' && cells.length > 1) {
-            cells.pop();
-          }
-          if (cells.length > 0) cells[cells.length - 1] = createStyledCell('\u2026', cells[cells.length - 1]);
-          return cells;
-        }
-        let style: Partial<Cell> = {};
-        if (token.type === 'code') {
-          style = { fg: T.inlineCodeFg, bold: true };
-        } else if (token.type === 'link') {
-          style = { fg: T.link, underline: true };
-        } else {
-          style = { ...token.style };
-        }
-        if (isHdr) {
-          style.fg = style.fg || T.heading1;
-          style.bold = true;
-        } else {
-          style.fg = style.fg || '252';
-        }
-        cells.push(createStyledCell(ch, style));
-        if (cw === 2) cells.push(createStyledCell('', style)); // wide char placeholder
-        w += cw;
-      }
-    }
-
-    // Pad remaining space
-    while (w < maxW) {
-      cells.push(createStyledCell(' ', isHdr ? { fg: T.heading1 } : { fg: '252' }));
-      w++;
-    }
-    return cells;
-  };
-
-  // Top border
-  lines.push(makeBorder('\u250c', '\u252c', '\u2510', '\u2500'));
-
-  // Rows
-  for (let r = 0; r < parsedRows.length; r++) {
-    const row = parsedRows[r];
-    const isHeader = hasSeparator && r === 0;
-
-    // Build the row line cell-by-cell
-    const line = new Array(width).fill(null).map(() => createStyledCell(' ')) as Cell[];
-    let x = indent;
-
-    // Left border
-    if (x < width) line[x] = createStyledCell('\u2502', { fg: bc });
-    x++;
-
-    for (let c = 0; c < colCount; c++) {
-      // Space before content
-      if (x < width) line[x] = createStyledCell(' ');
-      x++;
-
-      // Cell content
-      const raw = c < row.length ? row[c] : '';
-      const cellContent = renderCellContent(raw, colWidths[c], isHeader);
-      for (const cell of cellContent) {
-        if (x < width) line[x] = cell;
-        x++;
-      }
-
-      // Space after content
-      if (x < width) line[x] = createStyledCell(' ');
-      x++;
-
-      // Column separator
-      if (x < width) line[x] = createStyledCell('\u2502', { fg: bc });
-      x++;
-    }
-
-    lines.push(line);
-
-    // Header separator
-    if (isHeader) {
-      lines.push(makeBorder('\u251c', '\u253c', '\u2524', '\u2500'));
-    }
-  }
-
-  // Bottom border
-  lines.push(makeBorder('\u2514', '\u2534', '\u2518', '\u2500'));
-
-  return lines;
-}
-
-/**
- * Inline markdown token types.
- */
-type InlineToken =
-  | { type: 'text'; text: string; style: Partial<Cell> }
-  | { type: 'code'; text: string }
-  | { type: 'link'; text: string; url: string };
-
-/**
- * renderInlineMarkdown - Parse inline markdown (bold, italic, inline code, links)
- * and return a flat array of tokens with style info.
- */
-export function renderInlineMarkdown(text: string): InlineToken[] {
-  const tokens: InlineToken[] = [];
-  let i = 0;
-
-  while (i < text.length) {
-    // Link: [text](url)
-    if (text[i] === '[') {
-      const closeB = text.indexOf(']', i);
-      if (closeB !== -1 && text[closeB + 1] === '(') {
-        const closeP = text.indexOf(')', closeB + 2);
-        if (closeP !== -1) {
-          const linkText = text.slice(i + 1, closeB);
-          const url = text.slice(closeB + 2, closeP);
-          tokens.push({ type: 'link', text: linkText, url });
-          i = closeP + 1;
-          continue;
-        }
-      }
-    }
-
-    // Inline code: `code`
-    if (text[i] === '`') {
-      const end = text.indexOf('`', i + 1);
-      if (end !== -1) {
-        tokens.push({ type: 'code', text: text.slice(i + 1, end) });
-        i = end + 1;
-        continue;
-      }
-    }
-
-    // Bold+italic: ***text***
-    if (text.slice(i, i + 3) === '***') {
-      const end = text.indexOf('***', i + 3);
-      if (end !== -1) {
-        tokens.push({ type: 'text', text: text.slice(i + 3, end), style: { bold: true, italic: true } });
-        i = end + 3;
-        continue;
-      }
-      // No closing *** found — emit the leading * as plain text so the ** bold
-      // check can handle the remaining ** on the next iteration.
-      tokens.push({ type: 'text', text: '*', style: {} });
-      i += 1;
-      continue;
-    }
-
-    // Bold: **text**
-    if (text.slice(i, i + 2) === '**') {
-      const end = text.indexOf('**', i + 2);
-      if (end !== -1) {
-        tokens.push({ type: 'text', text: text.slice(i + 2, end), style: { bold: true } });
-        i = end + 2;
-        continue;
-      }
-    }
-
-    // Italic: *text* or _text_
-    // Guard: text[i - 1] !== '*' prevents the second * of ** from starting italic.
-    // Guard: text[i + 1] !== text[i] prevents the first * of ** (or _ of __) from
-    // starting italic when bold/underscore-bold detection failed (e.g. unclosed **).
-    if (
-      (text[i] === '*' || text[i] === '_') &&
-      text[i - 1] !== text[i] &&
-      text[i + 1] !== text[i]
-    ) {
-      const closer = text[i];
-      const end = text.indexOf(closer, i + 1);
-      if (end !== -1 && end > i + 1) {
-        tokens.push({ type: 'text', text: text.slice(i + 1, end), style: { italic: true } });
-        i = end + 1;
-        continue;
-      }
-    }
-
-    // Strikethrough: ~~text~~
-    if (text.slice(i, i + 2) === '~~') {
-      const end = text.indexOf('~~', i + 2);
-      if (end !== -1) {
-        tokens.push({ type: 'text', text: text.slice(i + 2, end), style: { strikethrough: true, fg: '244' } });
-        i = end + 2;
-        continue;
-      }
-    }
-
-    // Plain text — accumulate until next special char, detect bare URLs and file paths
-    let end = i + 1;
-    while (end < text.length && !INLINE_SPECIAL_CHARS.has(text[end])) {
-      const code = text.charCodeAt(end);
-      end += (code >= 0xD800 && code <= 0xDBFF) ? 2 : 1;
-    }
-    const plainText = text.slice(i, end);
-
-    // Detect http/https URLs in plain text
-    const urlMatch = plainText.match(/^(https?:\/\/[^\s,)>"]+)/);
-    if (urlMatch) {
-      const url = urlMatch[1];
-      tokens.push({ type: 'link', text: url, url });
-      i += url.length;
-      continue;
-    }
-
-    // Detect absolute file paths in plain text (require at least one directory separator)
-    const fileMatch = plainText.match(/^(\/[^\s,)>"]+\/[^\s,)>"]+(?:\.[a-zA-Z0-9]+)?)/);
-    if (fileMatch) {
-      const filePath = fileMatch[1];
-      const fileUrl = `file://${filePath}`;
-      tokens.push({ type: 'link', text: filePath, url: fileUrl });
-      i += filePath.length;
-      continue;
-    }
-
-    tokens.push({ type: 'text', text: plainText, style: {} });
-    i = end;
-  }
-
-  return tokens;
-}
-
 /**
  * compositeInlineLine - Convert a prefix + InlineTokens into Line[], applying word wrap.
  * Builds cells directly from token styles.

package/src/renderer/model-workspace.ts

@@ -280,14 +280,49 @@ function renderModelRows(picker: ModelPickerModal, lines: Line[], rows: number,
   if (end < models.length && lines[rows - 1]) writeText(lines[rows - 1]!, startX + 1, width - 2, `${GLYPHS.navigation.moreBelow} ${models.length - end} more model(s) below`, { fg: PALETTE.dim, bg: PALETTE.bodyBg, dim: true });
 }
 
+/**
+ * The effort step of the model picker.
+ *
+ * The list is exactly the levels the chosen model resolved to — not a fixed
+ * four — and it is introduced by a headline naming what this model does with
+ * the setting (named levels, a thinking-token budget, an on/off toggle, or
+ * nothing at all). A best-guess spec prints its caveat under the list rather
+ * than presenting unverified levels as if the provider had confirmed them.
+ */
 function renderEffortRows(picker: ModelPickerModal, lines: Line[], rows: number, startX: number, width: number): void {
-  for (let row = 0; row < Math.min(rows, picker.effortLevels.length); row += 1) {
-    const effort = picker.effortLevels[row]!;
-    const selected = row === picker.selectedIndex;
+  const presentation = picker.effortPresentation;
+  let row = 0;
+
+  if (presentation && rows > 0) {
+    fillRange(lines[row]!, startX, startX + width - 1, PALETTE.bodyBg);
+    writeText(lines[row]!, startX + 1, width - 2, presentation.headline, { fg: PALETTE.subtitle, bg: PALETTE.bodyBg });
+    row += 1;
+  }
+
+  // A model with nothing to configure gets a statement, not an empty list.
+  if (presentation && !presentation.configurable) {
+    if (row < rows) {
+      fillRange(lines[row]!, startX, startX + width - 1, PALETTE.bodyBg);
+      writeText(lines[row]!, startX + 1, width - 2, 'Esc returns to the model list.', { fg: PALETTE.dim, bg: PALETTE.bodyBg, dim: true });
+    }
+    return;
+  }
+
+  const firstLevelRow = row;
+  for (let i = 0; i < picker.effortLevels.length && row < rows; i += 1, row += 1) {
+    const effort = picker.effortLevels[i]!;
+    const selected = i === picker.selectedIndex;
     const bg = selected ? PALETTE.selectedBg : PALETTE.bodyBg;
     fillRange(lines[row]!, startX, startX + width - 1, bg);
     const marker = selected ? GLYPHS.navigation.selected : ' ';
-    writeText(lines[row]!, startX + 1, width - 2, `${marker} ${effort}`, { fg: selected ? PALETTE.text : PALETTE.muted, bg, bold: selected });
+    const detail = presentation?.choices[i]?.description ?? '';
+    const text = detail ? `${marker} ${effort.padEnd(8)}${detail}` : `${marker} ${effort}`;
+    writeText(lines[row]!, startX + 1, width - 2, text, { fg: selected ? PALETTE.text : PALETTE.muted, bg, bold: selected });
+  }
+
+  if (presentation?.caveat && row < rows && row > firstLevelRow) {
+    fillRange(lines[row]!, startX, startX + width - 1, PALETTE.bodyBg);
+    writeText(lines[row]!, startX + 1, width - 2, presentation.caveat, { fg: PALETTE.dim, bg: PALETTE.bodyBg, dim: true });
   }
 }
 
@@ -489,7 +524,15 @@ function getRenderCacheKey(picker: ModelPickerModal, width: number, viewportHeig
     const filteredProviders = picker.getFilteredProviders();
     base.push(objectId(picker.providers), objectId(filteredProviders), filteredProviders.length);
   } else if (picker.mode === 'effort') {
-    base.push(objectId(picker.effortLevels), picker.effortLevels.join('\u001f'), picker.pendingModel?.registryKey ?? picker.pendingModel?.id ?? '');
+    base.push(
+      objectId(picker.effortLevels),
+      picker.effortLevels.join('\u001f'),
+      picker.pendingModel?.registryKey ?? picker.pendingModel?.id ?? '',
+      // The headline and caveat are rendered content too: two models with the
+      // same level list but different spec kinds must not share a cache entry.
+      picker.effortPresentation?.headline ?? '',
+      picker.effortPresentation?.caveat ?? '',
+    );
   } else if (picker.mode === 'contextCap') {
     base.push(picker.contextCapQuery, picker.contextCapPendingModel?.registryKey ?? picker.contextCapPendingModel?.id ?? '');
   } else if (picker.mode === 'embeddingProvider') {

package/src/runtime/bootstrap-command-parts.ts

@@ -1,4 +1,10 @@
 import { getConfigSnapshot } from '../config/index.ts';
+import {
+  describeServingEffort,
+  publishActiveEffortOptions,
+  resolveRequestedEffortForServingModel,
+  toEffortModel,
+} from '../providers/reasoning-effort-surface.ts';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { AdaptivePlanner } from '@pellux/goodvibes-sdk/platform/core';
 import type { ConversationManager } from '../core/conversation';
@@ -227,7 +233,7 @@ export function createBootstrapCommandActions(
     clearScreen: () => unwiredShellAction('clearScreen'),
     activatePlan,
     requestPermission: (request) => requestPermission(request),
-    completeModelSelection: ({ model, effort, contextCap, target }) => {
+    completeModelSelection: ({ model, effort, contextCap, target, effortChosenByUser }) => {
       if (!model) return;
       const def = model;
       const key = def.registryKey ?? `${def.provider}:${def.id}`;
@@ -257,13 +263,39 @@ export function createBootstrapCommandActions(
           providerRegistry.setCurrentModel(key);
           runtime.model = key;
           runtime.provider = def.provider;
-          runtime.reasoningEffort = effort as 'instant' | 'low' | 'medium' | 'high';
+          // Two levels, kept apart on purpose. Config `provider.reasoningEffort`
+          // holds what the USER asked for; `runtime.reasoningEffort` holds what
+          // the model now serving will actually receive, which is the requested
+          // level snapped DOWN to this model's own levels.
+          //
+          // Only the picker's effort STEP is a user choice, and only it writes
+          // the preference. Every other route into this callback (model-only
+          // commit, context-cap commit) carries a level merely carried over
+          // from the previous model; storing that is what used to ratchet the
+          // preference down for good — one hop through a model that caps at
+          // 'medium' and 'xhigh' was gone from config, so hopping back could
+          // not restore it.
+          //
+          // A stored 'xhigh' that becomes 'high' on the wire would make a
+          // single-value display a lie, so the display carries BOTH values with
+          // their provenance instead (describeServingEffort) rather than the
+          // preference being corrupted to match.
+          const effortModel = toEffortModel(def);
+          // Publish this model's real levels first, so both the preference
+          // write below and a later `config set provider.reasoningEffort` are
+          // validated against them.
+          publishActiveEffortOptions(effortModel);
+          if (effortChosenByUser && effort) configManager.set('provider.reasoningEffort', effort);
+          const serving = resolveRequestedEffortForServingModel(configManager, effortModel);
+          runtime.reasoningEffort = serving.effective ?? '';
           configManager.set('provider.model', key);
-          configManager.set('provider.reasoningEffort', effort as 'instant' | 'low' | 'medium' | 'high');
           const ctxNote = contextCap != null && contextCap > 0
             ? `, context cap: ${contextCap.toLocaleString()}`
             : '';
-          conversation.log(`Switched to model: ${def.displayName} (${def.provider}), effort: ${effort}${ctxNote}`, { fg: '135' });
+          conversation.log(`Switched to model: ${def.displayName} (${def.provider}), effort: ${describeServingEffort(serving, effortModel)}${ctxNote}`, { fg: '135' });
+          // The SDK's own sentence, printed verbatim so the explanation cannot
+          // drift from the resolution that produced it.
+          if (serving.note) conversation.log(serving.note, { fg: '214' });
         }
       } catch (e) {
         conversation.log(`Error switching model: ${summarizeError(e)}`, { fg: '#ef4444' });

package/src/runtime/bootstrap-core.ts

@@ -350,7 +350,7 @@ export async function initializeBootstrapCore(
 
   const toolRegistry = new ToolRegistry();
   const { fileCache, projectIndex } = registerAllTools(toolRegistry, {
-    surfaceRoot: services.surface.surfaceRoot,
+    resolveSessionId: () => runtimeSessionIdRef.value, surfaceRoot: services.surface.surfaceRoot, // task refs follow the LIVE runtime session (recovery reassigns it in place); without this they fall into the shared legacy namespace
     localhostFetchApproval: services.localhostFetchApproval, // loopback-fetch ask, built once in the services composition
     execPromptAnswerHandler: services.execPromptAnswerHandler, // terminal prompt-answer path, built once in the services composition
     fileUndoManager: services.fileUndoManager,

package/src/runtime/durability-housekeeping.ts

@@ -0,0 +1,183 @@
+/**
+ * durability-housekeeping.ts — the reclaim half of every crash-durability
+ * artefact this product writes to disk.
+ *
+ * The standing rule this module implements: if something is persisted across
+ * restarts and crashes, recovery has to do the housekeeping. Each individual
+ * store already knew how to WRITE its artefact and how to retire it on a clean
+ * path; none of them reclaimed what a SIGKILL left behind. Four stores, four
+ * kinds of residue:
+ *
+ *   - liveness markers      `<home>/.goodvibes/<root>/liveness/<id>.json`
+ *                           removed only on a clean exit, so a crash leaks one
+ *                           file per session id ever opened.
+ *   - transcript journals   `<home>/.goodvibes/<root>/transcript-<id>.journal`
+ *                           deleted on snapshot or replay, so a session that
+ *                           crashes and is never resumed leaks its journal.
+ *   - quarantine files      `<path>.unrecognized` — written so a human can
+ *                           inspect a corrupt file, never removed afterwards.
+ *   - anchor sidecars       `<sessionsDir>/<id>.anchors.json` — outlives the
+ *                           session JSONL that owns it.
+ *
+ * Every reap here is bounded by BOTH an age window and a count cap, decides
+ * what to keep by reading content rather than by a file merely existing, never
+ * touches the current session, tolerates a competing sweeper deleting the same
+ * file first, and reports what it removed. `startDurabilityHousekeeping` runs
+ * the sweep at startup and then on a repeating timer, because a long-lived
+ * process that only sweeps at boot never sweeps.
+ *
+ * Best-effort throughout: a failure in one reap never aborts the others and
+ * nothing here ever throws to its caller.
+ */
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { join } from 'node:path';
+import { reapQuarantinedFiles } from '@/config/read-versioned.ts';
+import { reapOrphanedAnchorSidecars } from '@/core/rewind-turn-anchors.ts';
+import { reapOrphanedJournals } from '@/core/transcript-journal.ts';
+import { checkSessionLiveness, reapStaleLivenessMarkers } from '@/runtime/session-liveness-marker.ts';
+import type { SessionSurface } from '@/runtime/index.ts';
+
+/**
+ * How often the sweep repeats after startup: 6 hours. Hours, not minutes — the
+ * residue this reclaims accumulates per crashed session, not continuously, and
+ * a directory scan is not something a foreground TUI should be doing often.
+ */
+export const DURABILITY_HOUSEKEEPING_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+export interface DurabilityHousekeepingInput {
+  /** The app's declare-once storage handle; every swept path derives from it. */
+  readonly surface: SessionSurface;
+  /**
+   * The session this process is using right now, read at sweep time rather
+   * than captured once — a resume or fork can repoint it between sweeps.
+   * Returning null means "not known yet", which is safe: the age and liveness
+   * rules independently protect an actively written artefact.
+   */
+  readonly currentSessionId?: () => string | null;
+  /** Extra directories to scan for `.unrecognized` quarantine files. */
+  readonly extraQuarantineDirs?: readonly string[];
+}
+
+export interface DurabilityHousekeepingOutcome {
+  readonly livenessMarkers: number;
+  readonly transcriptJournals: number;
+  readonly quarantineFiles: number;
+  readonly anchorSidecars: number;
+  /** Sum of the four counts above — zero means nothing was reclaimed. */
+  readonly total: number;
+}
+
+/**
+ * Run all four reaps once and return what each reclaimed.
+ *
+ * Each reap is isolated: one throwing is logged at warn level and counted as
+ * zero, and the remaining reaps still run. The caller never sees an exception.
+ */
+export function runDurabilityHousekeeping(input: DurabilityHousekeepingInput): DurabilityHousekeepingOutcome {
+  const { surface } = input;
+  const currentSessionId = safely('current session id', () => input.currentSessionId?.() ?? null, null);
+
+  const livenessMarkers = safely('liveness markers', () =>
+    reapStaleLivenessMarkers(surface, {
+      keepSessionIds: currentSessionId ? [currentSessionId] : [],
+    }).reaped, 0);
+
+  const transcriptJournals = safely('transcript journals', () =>
+    reapOrphanedJournals(surface, {
+      currentSessionId,
+      // Composition happens here so transcript-journal.ts keeps no dependency
+      // on the liveness marker: a journal whose session is open in another
+      // running instance is live state, not residue.
+      isSessionLive: (sessionId) => checkSessionLiveness(surface, sessionId).live,
+    }).reaped, 0);
+
+  const quarantineFiles = safely('quarantine files', () =>
+    reapQuarantinedFiles(quarantineDirsFor(input)).reaped, 0);
+
+  const anchorSidecars = safely('anchor sidecars', () =>
+    reapOrphanedAnchorSidecars(surface, { currentSessionId }).reaped, 0);
+
+  const outcome: DurabilityHousekeepingOutcome = {
+    livenessMarkers,
+    transcriptJournals,
+    quarantineFiles,
+    anchorSidecars,
+    total: livenessMarkers + transcriptJournals + quarantineFiles + anchorSidecars,
+  };
+  discloseHousekeeping(outcome);
+  return outcome;
+}
+
+/**
+ * Start durability housekeeping: one sweep now, then a repeating sweep every
+ * `DURABILITY_HOUSEKEEPING_INTERVAL_MS`. Returns a disposer that stops the
+ * timer; calling it more than once is harmless.
+ *
+ * The timer is `unref()`d, so an undisposed sweeper can never hold the process
+ * open — same convention the store-snapshot scheduler and the config-file
+ * watchers in durability-services.ts use.
+ */
+export function startDurabilityHousekeeping(
+  input: DurabilityHousekeepingInput,
+  options: { readonly intervalMs?: number } = {},
+): () => void {
+  runDurabilityHousekeeping(input);
+  const timer = setInterval(
+    () => { runDurabilityHousekeeping(input); },
+    options.intervalMs ?? DURABILITY_HOUSEKEEPING_INTERVAL_MS,
+  );
+  timer.unref?.();
+  let stopped = false;
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+  };
+}
+
+/**
+ * Disclose what was reclaimed — silent deletion is indistinguishable from data
+ * loss. Paths and counts only; nothing about a reclaimed file's contents.
+ *
+ * A sweep that reclaimed nothing logs nothing: the overwhelmingly common boot
+ * has no residue at all, and a per-boot "reclaimed 0" line would train readers
+ * to ignore the line that actually matters.
+ */
+function discloseHousekeeping(outcome: DurabilityHousekeepingOutcome): void {
+  if (outcome.total === 0) return;
+  logger.info('durability housekeeping reclaimed crash residue', {
+    livenessMarkers: outcome.livenessMarkers,
+    transcriptJournals: outcome.transcriptJournals,
+    quarantineFiles: outcome.quarantineFiles,
+    anchorSidecars: outcome.anchorSidecars,
+    total: outcome.total,
+  });
+}
+
+/**
+ * Every directory that can accumulate `.unrecognized` files: the home-scoped
+ * surface root (transcript-journal quarantines) and the per-project session,
+ * state, recovery and checkpoint directories (versioned-config quarantines),
+ * plus whatever the caller adds.
+ */
+function quarantineDirsFor(input: DurabilityHousekeepingInput): readonly string[] {
+  const { surface } = input;
+  return [
+    join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot),
+    surface.sessionsDir,
+    surface.stateDir,
+    surface.recoveryDir,
+    surface.checkpointsDir,
+    ...(input.extraQuarantineDirs ?? []),
+  ].filter((dir): dir is string => typeof dir === 'string' && dir.length > 0);
+}
+
+/** Run one reap in isolation: never throws, returns `fallback` if it would have. */
+function safely<T>(label: string, run: () => T, fallback: T): T {
+  try {
+    return run();
+  } catch (error) {
+    logger.warn('durability housekeeping step failed', { step: label, error: summarizeError(error) });
+    return fallback;
+  }
+}