@pellux/goodvibes-tui 1.20.1 → 1.21.1

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

package/src/runtime/durability-services.ts

@@ -18,6 +18,12 @@
  *    EVERY root the composition knows (working dir, surface root, home,
  *    logDir, telemetryDir) — omitting logDir/telemetryDir/home would silently
  *    skip the activity-log, telemetry-ledger, and recovery-snapshot stores.
+ *  - Durability housekeeping: the crash-residue reclaim the retention janitor
+ *    above does NOT cover — stale liveness markers, orphaned transcript
+ *    journals, `.unrecognized` quarantine files, and anchor sidecars whose
+ *    session is gone (see durability-housekeeping.ts). It runs at startup AND
+ *    on a repeating unref'd timer, because a long-lived process that only
+ *    sweeps at boot never sweeps; the returned disposer stops that timer.
  *  - Live config-file watch: external edits to the settings file apply through
  *    the same subscribe() pipeline an in-process set() uses — no restart. The
  *    underlying watchers are unref'd, so this never pins the event loop.
@@ -28,6 +34,7 @@ import { resolveMemoryVectorDbPath } from '@pellux/goodvibes-sdk/platform/state'
 import { StoreSnapshotScheduler } from '@pellux/goodvibes-sdk/platform/state/store-snapshots';
 import { UserPermissionRuleStore } from '@pellux/goodvibes-sdk/platform/permissions';
 import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { startDurabilityHousekeeping } from './durability-housekeeping.ts';
 import type { SessionSurface } from '@/runtime/index.ts';
 
 export interface DurabilityServicesInput {
@@ -48,11 +55,44 @@ export interface DurabilityServicesInput {
    */
   readonly surface: SessionSurface;
   readonly shellPaths: { resolveUserPath(...segments: string[]): string };
+  /**
+   * The session id this process is currently using, read at each sweep. When
+   * omitted the crash-residue reap still protects live artefacts through its
+   * age and liveness rules — this is the explicit belt-and-braces guard.
+   */
+  /**
+   * Resolves the live session id, read fresh on every crash-residue sweep so
+   * the running session's own transcript journal and liveness marker are
+   * exempt from reaping.
+   *
+   * A getter, not a value: the id is reassigned in place when a recovery
+   * snapshot is accepted, and this sweep repeats for the life of the process.
+   *
+   * Omitting it is not merely untidy. The journal reaper's other guard is the
+   * liveness marker, and that marker goes stale after 150 seconds — so a host
+   * that passes nothing here is trusting a heartbeat that a single long
+   * blocking turn can outrun, and an in-process sweep landing in that window
+   * would delete the journal of the session currently writing it. Passing this
+   * makes the exemption unconditional instead of timing-dependent.
+   */
+  readonly currentSessionId?: () => string | null;
 }
 
 export interface DurabilityServices {
   readonly storeSnapshotScheduler: StoreSnapshotScheduler;
+  /**
+   * Re-sweeps every registered append-only store on a cadence. The start-time
+   * sweep alone never prunes again in a process that stays up, which is the
+   * window in which those stores grow. Unref'd timers; teardown stop()s it.
+   */
+  readonly appendOnlyRetentionScheduler: InstanceType<typeof operations.AppendOnlyRetentionScheduler>;
   readonly userPermissionRuleStore: UserPermissionRuleStore;
+  /**
+   * Stops the repeating crash-residue sweep. The timer is unref'd, so a host
+   * that never calls this is not held open by it; teardown calls it to stop
+   * the work rather than to release the loop.
+   */
+  readonly stopDurabilityHousekeeping: () => void;
 }
 
 export function createDurabilityServices(input: DurabilityServicesInput): DurabilityServices {
@@ -73,16 +113,33 @@ export function createDurabilityServices(input: DurabilityServicesInput): Durabi
   // activity-log, telemetry-ledger, and recovery-snapshot stores are all swept.
   // Best-effort — a retention failure never takes startup down (the sweep
   // swallows its own errors).
-  operations.runStartupAppendOnlySweep(
-    {
-      workingDirectory: input.surface.workingDirectory,
-      surfaceRoot: input.surface.surfaceRoot,
-      homeDirectory: input.surface.homeDirectory,
-      logDir: input.shellPaths.resolveUserPath('logs'),
-      telemetryDir: input.shellPaths.resolveUserPath('telemetry'),
-    },
-    (k: string) => configManager.get(k as never),
-  );
+  const appendOnlyRetentionRoots = {
+    workingDirectory: input.surface.workingDirectory,
+    surfaceRoot: input.surface.surfaceRoot,
+    homeDirectory: input.surface.homeDirectory,
+    logDir: input.shellPaths.resolveUserPath('logs'),
+    telemetryDir: input.shellPaths.resolveUserPath('telemetry'),
+  };
+  const appendOnlyRetentionConfigGet = (k: string): unknown => configManager.get(k as never);
+  operations.runStartupAppendOnlySweep(appendOnlyRetentionRoots, appendOnlyRetentionConfigGet);
+  // ...and again on a cadence for as long as this process lives. A start-time
+  // sweep alone never prunes a long-lived session again after boot, which is
+  // exactly the window in which these stores grow. Unref'd timers; the disposer
+  // below stops it, same posture as storeSnapshotScheduler.
+  const appendOnlyRetentionScheduler = new operations.AppendOnlyRetentionScheduler({
+    roots: appendOnlyRetentionRoots,
+    configGet: appendOnlyRetentionConfigGet,
+  });
+  appendOnlyRetentionScheduler.start();
+  // Crash-residue reclaim the sweep above does not cover (liveness markers,
+  // orphaned transcript journals, .unrecognized quarantine files, anchor
+  // sidecars whose session file is gone). Runs once now and every few hours
+  // after that; the timer is unref'd and the disposer stops it.
+  const stopDurabilityHousekeeping = startDurabilityHousekeeping({
+    surface: input.surface,
+    currentSessionId: input.currentSessionId,
+    extraQuarantineDirs: [configManager.getControlPlaneConfigDir()],
+  });
   // External config edits apply LIVE through the same subscribe() pipeline an
   // in-process set() uses; the underlying watchers are unref'd.
   configManager.watchConfigFiles();
@@ -90,5 +147,5 @@ export function createDurabilityServices(input: DurabilityServicesInput): Durabi
   const userPermissionRuleStore = new UserPermissionRuleStore(join(configManager.getControlPlaneConfigDir(), 'permission-rules.json'));
   void userPermissionRuleStore.init().catch((error) => logger.warn('user permission rule store init failed; asks will prompt', { error: summarizeError(error) }));
 
-  return { storeSnapshotScheduler, userPermissionRuleStore };
+  return { storeSnapshotScheduler, appendOnlyRetentionScheduler, userPermissionRuleStore, stopDurabilityHousekeeping };
 }

package/src/runtime/legacy-daemon-reconcile.ts

@@ -101,6 +101,14 @@ export interface ReconcileRedundantLegacyUnitInput {
   readonly readOwnCgroup?: (() => string) | undefined;
   /** Timeout applied to the DEFAULT systemctl runner only. Defaults to SYSTEMCTL_TIMEOUT_MS. */
   readonly systemctlTimeoutMs?: number | undefined;
+  /**
+   * Program the DEFAULT runner executes. Defaults to `systemctl` (resolved on
+   * PATH). Tests that deliberately exercise the default (non-injected) runner
+   * point this at an absolute stub path: Bun resolves a spawned program from
+   * the PATH captured at process start, so mutating `process.env.PATH` inside
+   * a test cannot redirect the call and the host's real systemctl would answer.
+   */
+  readonly systemctlCommand?: string | undefined;
   /** Cumulative budget for the whole pass. Defaults to RECONCILE_DEADLINE_MS. */
   readonly deadlineMs?: number | undefined;
 }
@@ -201,6 +209,7 @@ export async function reconcileRedundantLegacyUnit(
     input.systemctlTimeoutMs ?? SYSTEMCTL_TIMEOUT_MS,
     input.deadlineMs ?? RECONCILE_DEADLINE_MS,
   );
+  const systemctl = input.systemctlCommand ?? 'systemctl';
   const canonicalUnit = `${input.trackedServiceName}.service`;
   const legacyUnit = `${LEGACY_SERVICE_UNIT_NAME}.service`;
   const deadlineNote = (): string[] =>
@@ -210,7 +219,7 @@ export async function reconcileRedundantLegacyUnit(
 
   // Guard 1: the canonical unit must report active. (A timed-out, skipped, or
   // failed probe — e.g. a wedged user bus — lands here too and refuses.)
-  const probe = run('systemctl', ['--user', 'is-active', canonicalUnit]);
+  const probe = run(systemctl, ['--user', 'is-active', canonicalUnit]);
   const canonicalActive = (probe.status ?? 1) === 0 && (probe.stdout ?? '').trim() === 'active';
   if (!canonicalActive) {
     return {
@@ -227,7 +236,7 @@ export async function reconcileRedundantLegacyUnit(
   // Guard 2: 'active' alone does not prove the canonical unit is the daemon
   // actually serving (Type=simple reports active from fork onward). Require
   // its MainPID to resolve and be a live process.
-  const canonicalPid = parseMainPid(run('systemctl', ['--user', 'show', '-p', 'MainPID', '--value', canonicalUnit]));
+  const canonicalPid = parseMainPid(run(systemctl, ['--user', 'show', '-p', 'MainPID', '--value', canonicalUnit]));
   const alive = input.processAlive ?? defaultProcessAlive;
   if (canonicalPid === undefined || !alive(canonicalPid)) {
     return {
@@ -253,7 +262,7 @@ export async function reconcileRedundantLegacyUnit(
   // it: in the wrong-port state the legacy daemon itself answers the
   // configured-endpoint probe). Unknown refuses.
   const ownPid = input.ownPid ?? process.pid;
-  const legacyPidReply = run('systemctl', ['--user', 'show', '-p', 'MainPID', '--value', legacyUnit]);
+  const legacyPidReply = run(systemctl, ['--user', 'show', '-p', 'MainPID', '--value', legacyUnit]);
   const legacyPidKnown = (legacyPidReply.status ?? 1) === 0;
   const legacyPid = parseMainPid(legacyPidReply);
   const ownCgroup = (input.readOwnCgroup ?? defaultReadOwnCgroup)();
@@ -359,7 +368,7 @@ export async function reconcileRedundantLegacyUnit(
   // unit file if the disable actually succeeded — otherwise the enablement
   // symlink dangles at a deleted file and this tool can never repair it (the
   // next pass no-ops at the file-exists check).
-  const disableResult = run('systemctl', ['--user', 'disable', '--now', legacyUnit]);
+  const disableResult = run(systemctl, ['--user', 'disable', '--now', legacyUnit]);
   const disableStatus = disableResult.status ?? 1;
   if (disableStatus !== 0) {
     if (disableResult.status === null) {
@@ -367,7 +376,7 @@ export async function reconcileRedundantLegacyUnit(
       // removes the enablement symlinks synchronously BEFORE waiting on the
       // stop job, so the disable may well have taken effect even though the
       // client was killed. Re-inspect instead of printing a blanket denial.
-      const reinspect = run('systemctl', ['--user', 'is-enabled', legacyUnit]);
+      const reinspect = run(systemctl, ['--user', 'is-enabled', legacyUnit]);
       const reinspectOut = (reinspect.stdout ?? '').trim();
       const confirmedDisabled = (reinspect.status !== null)
         && (reinspectOut === 'disabled' || reinspectOut === 'not-found');
@@ -381,7 +390,7 @@ export async function reconcileRedundantLegacyUnit(
         } catch (error) {
           removeErrorAfterTimeout = summarizeError(error);
         }
-        run('systemctl', ['--user', 'daemon-reload']);
+        run(systemctl, ['--user', 'daemon-reload']);
         const lines = [
           `reconciled: the disable command timed out waiting on the stop job, but re-inspection confirms the ` +
             `installer-managed ${legacyUnit} is no longer enabled${removeErrorAfterTimeout ? '' : ` — its unit file was removed (${path})`}. ` +
@@ -425,7 +434,7 @@ export async function reconcileRedundantLegacyUnit(
   } catch (error) {
     removeError = summarizeError(error);
   }
-  run('systemctl', ['--user', 'daemon-reload']);
+  run(systemctl, ['--user', 'daemon-reload']);
 
   const lines = [
     `reconciled: ${canonicalUnit} is active and serving, so the redundant installer-managed ${legacyUnit} ` +

package/src/runtime/provider-fallback.ts

@@ -6,7 +6,12 @@
  * compaction denominator agree with the post-catalog window.
  */
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
-import { inferFallbackContextWindow, type ModelDefinition, type ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
+import {
+  inferFallbackContextWindow,
+  resolveReasoningEffortSpec,
+  type ModelDefinition,
+  type ProviderRegistry,
+} from '@pellux/goodvibes-sdk/platform/providers';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 function buildFallbackModelDefinition(provider: string, modelId: string): ModelDefinition {
@@ -32,7 +37,16 @@ function buildFallbackModelDefinition(provider: string, modelId: string): ModelD
     contextWindowProvenance: 'fallback',
     selectable: true,
     tier: 'standard',
-    ...(isReasoningProvider ? { reasoningEffort: ['instant', 'low', 'medium', 'high'] } : {}),
+    // Which levels this model accepts is a property of the model, not of the
+    // provider it sits behind: the hardcoded four ('instant', 'low', 'medium',
+    // 'high') offered 'instant' to models that reject it and hid 'xhigh',
+    // 'max' and 'none' from models that accept them. The SDK resolver answers
+    // from the curated family table when the catalog has not loaded yet, and
+    // otherwise returns its own labelled best guess, which the adapters treat
+    // as "send nothing" rather than as verified levels.
+    ...(isReasoningProvider
+      ? { reasoningEffort: resolveReasoningEffortSpec({ modelId }) }
+      : {}),
   };
 }
 

package/src/runtime/recovery-decisions.ts

@@ -30,8 +30,9 @@
  * another. Each record still carries the workspace it was made in, so the file
  * says plainly where the decision came from.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import type { SessionSurface } from '@/runtime/index.ts';
 
 /** One "the user removed this snapshot" decision. */
@@ -52,6 +53,12 @@ export interface RecoveryRemovalRecord {
  * deleted, so that rule would empty the ledger immediately and reinstate the
  * exact defect it was written to fix — the point is precisely to still
  * remember once the file comes back. Age and count are the honest bounds.
+ *
+ * Both bounds are enforced wherever records actually leave the disk —
+ * pruneRecoveryDecisions (once per boot) and recordRecoveryRemoval (every
+ * write) — and both DISCLOSE what they discarded. A deletion nobody reports is
+ * indistinguishable from data loss, so the counts go in the log with the ledger
+ * path, the TTL and the cap alongside them.
  */
 const MAX_RECORDS = 200;
 const RECORD_TTL_MS = 90 * 24 * 60 * 60 * 1000;
@@ -71,22 +78,162 @@ function isRecord(value: unknown): value is RecoveryRemovalRecord {
     && Number.isFinite(candidate.removedAt);
 }
 
+/** What one load of the ledger found, including everything it discarded. */
+interface LedgerLoad {
+  /** Records still in force, oldest first. */
+  readonly kept: RecoveryRemovalRecord[];
+  /** Records dropped because they aged past the TTL. */
+  readonly expired: number;
+  /** Entries dropped because they were not shaped like a record at all. */
+  readonly malformed: number;
+  /** The ledger file was present but could not be read or parsed as an array. */
+  readonly unreadable: boolean;
+  /** The ledger file exists on disk. */
+  readonly present: boolean;
+}
+
+/**
+ * Load and filter the ledger. Validation is by CONTENT — the file is parsed and
+ * every entry is shape-checked — so a torn, truncated or zero-byte ledger left
+ * by a crash reads as "no decisions recorded" instead of being trusted because
+ * it exists. Never throws: a corrupt file must not be able to take a boot down,
+ * and the worst outcome of losing it is that the user is asked once more.
+ */
+function loadLedger(surface: SessionSurface, nowMs: number): LedgerLoad {
+  const path = recoveryDecisionsPathFor(surface);
+  let present = false;
+  try {
+    present = existsSync(path);
+    if (!present) return { kept: [], expired: 0, malformed: 0, unreadable: false, present: false };
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    if (!Array.isArray(parsed)) return { kept: [], expired: 0, malformed: 0, unreadable: true, present };
+    const wellFormed = parsed.filter(isRecord);
+    const kept = wellFormed.filter((record) => nowMs - record.removedAt < RECORD_TTL_MS);
+    return {
+      kept,
+      expired: wellFormed.length - kept.length,
+      malformed: parsed.length - wellFormed.length,
+      unreadable: false,
+      present,
+    };
+  } catch {
+    return { kept: [], expired: 0, malformed: 0, unreadable: true, present };
+  }
+}
+
 /**
  * Every removal decision still in force, oldest first. A missing, unreadable
  * or malformed ledger reads as "no decisions recorded" rather than throwing:
  * a corrupt file must not be able to take a boot down, and the worst outcome
  * of losing it is that the user is asked once more.
+ *
+ * This is a filtered READ — it discards nothing from disk, so it stays silent.
+ * Disclosure belongs to the calls that actually delete: {@link pruneRecoveryDecisions}
+ * and {@link recordRecoveryRemoval}.
  */
 export function readRecoveryRemovals(surface: SessionSurface, nowMs: number = Date.now()): RecoveryRemovalRecord[] {
+  return loadLedger(surface, nowMs).kept;
+}
+
+/**
+ * Write `records` to the ledger through a temp file and an atomic rename.
+ *
+ * A plain `writeFileSync` onto the live path truncates first and fills after,
+ * so a crash — or a second TUI in another terminal writing the same home-
+ * anchored ledger at the same moment — could leave a half-written array that a
+ * later boot reads as an empty or corrupt ledger, silently forgetting every
+ * decision the user made. `rename` is atomic on the same filesystem: a reader
+ * sees either the whole old ledger or the whole new one. The temp name carries
+ * the pid so two writers cannot interleave into one temp file.
+ */
+function writeLedgerAtomically(path: string, records: readonly RecoveryRemovalRecord[]): void {
+  const temp = `${path}.${process.pid}.tmp`;
+  mkdirSync(dirname(path), { recursive: true });
   try {
-    const path = recoveryDecisionsPathFor(surface);
-    if (!existsSync(path)) return [];
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
-    if (!Array.isArray(parsed)) return [];
-    return parsed.filter(isRecord).filter((record) => nowMs - record.removedAt < RECORD_TTL_MS);
+    writeFileSync(temp, JSON.stringify(records, null, 2) + '\n', { mode: 0o600 });
+    renameSync(temp, path);
+  } catch (error) {
+    try {
+      rmSync(temp, { force: true });
+    } catch {
+      // The temp file is inert; a failed cleanup is not worth a second error.
+    }
+    throw error;
+  }
+}
+
+/** What a prune pass discarded, returned so callers (and tests) can assert it. */
+export interface RecoveryDecisionsPruneOutcome {
+  /** Records dropped because they aged past the 90-day TTL. */
+  readonly expired: number;
+  /** Entries dropped because they were not shaped like a record. */
+  readonly malformed: number;
+  /** Records dropped because the ledger was over the 200-record cap. */
+  readonly overCap: number;
+  /** Records still in force after the prune. */
+  readonly kept: number;
+  /** The ledger file was present but unreadable or not an array. */
+  readonly unreadable: boolean;
+}
+
+/**
+ * Apply both bounds to the on-disk ledger and say what was discarded.
+ *
+ * `readRecoveryRemovals` filters in memory on every call, so the expired
+ * records were already inert — but they stayed on disk until the next time the
+ * user happened to answer "Remove", which on a machine where that never happens
+ * again is never. This makes the reap explicit and, crucially, VISIBLE: a
+ * silent deletion is indistinguishable from data loss, so every pass that drops
+ * anything logs the counts and the ledger path.
+ *
+ * Idempotent and safe to run from two processes at once: it is a pure function
+ * of the file's content plus `nowMs`, the rewrite is a temp-file-plus-rename,
+ * and a second run over an already-pruned ledger drops nothing and writes
+ * nothing. Best-effort — a ledger that cannot be pruned is left exactly as it
+ * was and never breaks a boot.
+ */
+export function pruneRecoveryDecisions(surface: SessionSurface, nowMs: number = Date.now()): RecoveryDecisionsPruneOutcome {
+  const path = recoveryDecisionsPathFor(surface);
+  const load = loadLedger(surface, nowMs);
+  const overCap = Math.max(0, load.kept.length - MAX_RECORDS);
+  const bounded = load.kept.slice(-MAX_RECORDS);
+  const outcome: RecoveryDecisionsPruneOutcome = {
+    expired: load.expired,
+    malformed: load.malformed,
+    overCap,
+    kept: bounded.length,
+    unreadable: load.unreadable,
+  };
+
+  if (load.unreadable) {
+    // Do NOT rewrite: an unreadable ledger might be a transient read failure,
+    // and replacing it with `[]` would turn "could not read" into "forgot every
+    // decision the user made". Say so and leave it alone.
+    logger.warn('recovery decisions: ledger present but unreadable — left untouched, decisions may be re-asked', {
+      ledger: path,
+    });
+    return outcome;
+  }
+  const dropped = load.expired + load.malformed + overCap;
+  if (dropped === 0 || !load.present) return outcome;
+
+  try {
+    writeLedgerAtomically(path, bounded);
   } catch {
-    return [];
+    // The in-memory filter already ignores these records; failing to persist
+    // the prune costs disk space, not correctness.
+    return outcome;
   }
+  logger.info('recovery decisions: pruned the removal ledger', {
+    ledger: path,
+    expiredRecords: load.expired,
+    malformedEntries: load.malformed,
+    overCapRecords: overCap,
+    keptRecords: bounded.length,
+    ttlDays: Math.round(RECORD_TTL_MS / (24 * 60 * 60 * 1000)),
+    maxRecords: MAX_RECORDS,
+  });
+  return outcome;
 }
 
 /**
@@ -111,15 +258,37 @@ export function isRecoveryRemovalRecorded(surface: SessionSurface, sessionId: st
  */
 export function recordRecoveryRemoval(surface: SessionSurface, sessionId: string, nowMs: number = Date.now()): void {
   if (!sessionId.trim()) return;
+  const path = recoveryDecisionsPathFor(surface);
   try {
-    const kept = readRecoveryRemovals(surface, nowMs).filter((record) => record.sessionId !== sessionId);
+    const load = loadLedger(surface, nowMs);
+    if (load.unreadable) {
+      // Appending onto an unreadable ledger would rewrite it as a one-record
+      // array, silently discarding whatever the user decided before. Say so
+      // rather than quietly resetting their history.
+      logger.warn('recovery decisions: ledger unreadable — recording this removal replaces it', {
+        ledger: path,
+        sessionId,
+      });
+    }
+    const kept = load.kept.filter((record) => record.sessionId !== sessionId);
     kept.push({ sessionId, workspace: surface.workingDirectory, removedAt: nowMs });
     // Oldest decisions fall off first; the newest are the ones a reappearing
     // snapshot is most likely to match.
+    const overCap = Math.max(0, kept.length - MAX_RECORDS);
     const bounded = kept.slice(-MAX_RECORDS);
-    const path = recoveryDecisionsPathFor(surface);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(bounded, null, 2) + '\n', { mode: 0o600 });
+    writeLedgerAtomically(path, bounded);
+    // Disclosure: this write is where records actually leave the disk, so it
+    // is where the counts get said out loud.
+    const dropped = load.expired + load.malformed + overCap;
+    if (dropped > 0) {
+      logger.info('recovery decisions: dropped records while recording a removal', {
+        ledger: path,
+        expiredRecords: load.expired,
+        malformedEntries: load.malformed,
+        overCapRecords: overCap,
+        keptRecords: bounded.length,
+      });
+    }
   } catch {
     // Best-effort by construction — see the doc comment above.
   }