@pellux/goodvibes-tui 1.20.0 → 1.21.0

package/src/runtime/recovery-decisions.ts

@@ -0,0 +1,295 @@
+/**
+ * recovery-decisions.ts — a durable record of the recovery snapshots the user
+ * has already said "Remove" to.
+ *
+ * The defect this exists for: answering Remove deletes the snapshot file, and
+ * that was the whole memory of the decision. Anything that puts the file back
+ * — a session still running on an older build rewriting its snapshot every
+ * 60s, a restored backup, a synced directory — produced the same question
+ * again on the next launch, and again after the next removal, with no way for
+ * the user to make it stop. A decision the product forgets the instant it acts
+ * on it is not a decision the user gets to make.
+ *
+ * So Remove now writes a record that outlives the process, and a recorded
+ * snapshot found on disk again is deleted without asking. "Keep" is
+ * deliberately NOT recorded here: Keep means "leave it, ask me next launch",
+ * and recovery-prompt.ts's in-process set already holds it for the rest of the
+ * run.
+ *
+ * WHERE IT LIVES, and why not under `surface.stateDir`:
+ * `<homeDirectory>/.goodvibes/<surfaceRoot>/recovery-decisions.json` — home-
+ * anchored, matching session-liveness-marker.ts, and deliberately NOT the
+ * project-anchored `surface.stateDir`. The snapshots this defends against
+ * include the ones in the SDK's legacy shared recovery directory, which is
+ * itself home-anchored and shared by every project that ever used this
+ * surfaceRoot; the current build dual-reads it, so ONE such snapshot is
+ * offered at the launch of EVERY project. A project-scoped record could only
+ * ever silence one project at a time, which is the same nag wearing a
+ * different hat. Records are matched on session id alone; ids are unique, so
+ * a record made in one project cannot suppress a different snapshot in
+ * 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, 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. */
+export interface RecoveryRemovalRecord {
+  readonly sessionId: string;
+  /** The project the decision was made in. Provenance — matching is on sessionId alone. */
+  readonly workspace: string;
+  readonly removedAt: number;
+}
+
+/**
+ * Bounds on the ledger. It is append-mostly and never read by anything but
+ * the boot offer, so it stays small by construction; these are the guards
+ * against a pathological case, not a routine cleanup.
+ *
+ * Note what is deliberately NOT the pruning rule: "drop records whose snapshot
+ * file no longer exists". Every record in here describes a file that was just
+ * 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;
+
+/** Absolute path to this surface's removal ledger. */
+export function recoveryDecisionsPathFor(surface: SessionSurface): string {
+  return join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot, 'recovery-decisions.json');
+}
+
+function isRecord(value: unknown): value is RecoveryRemovalRecord {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as Partial<RecoveryRemovalRecord>;
+  return typeof candidate.sessionId === 'string'
+    && candidate.sessionId.length > 0
+    && typeof candidate.workspace === 'string'
+    && typeof candidate.removedAt === 'number'
+    && 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 {
+    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 {
+    // 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;
+}
+
+/**
+ * Has the user already chosen Remove for this snapshot's session, in this or
+ * any earlier run?
+ */
+export function isRecoveryRemovalRecorded(surface: SessionSurface, sessionId: string, nowMs: number = Date.now()): boolean {
+  if (!sessionId.trim()) return false;
+  return readRecoveryRemovals(surface, nowMs).some((record) => record.sessionId === sessionId);
+}
+
+/**
+ * Record that the user chose Remove for `sessionId`. Idempotent — a repeat
+ * removal of a snapshot that came back refreshes the existing record's
+ * timestamp rather than adding a second one, so the ledger cannot grow by one
+ * entry per reappearance.
+ *
+ * Best-effort: a ledger that cannot be written must not break the removal the
+ * user actually asked for. The cost of a failed write is one more question on
+ * a future launch, which is exactly the behaviour that shipped before this
+ * file existed.
+ */
+export function recordRecoveryRemoval(surface: SessionSurface, sessionId: string, nowMs: number = Date.now()): void {
+  if (!sessionId.trim()) return;
+  const path = recoveryDecisionsPathFor(surface);
+  try {
+    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);
+    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.
+  }
+}

package/src/runtime/recovery-prompt.ts

@@ -39,10 +39,21 @@
  *     without reading keeps the snapshot.
  *   - Keep (or a dismissal) stays quiet for the rest of the run. The snapshot
  *     is offered again on the next launch, not again in this one.
+ *   - Remove is permanent, not just for this file. The decision is written to
+ *     the durable ledger in recovery-decisions.ts, so a snapshot that comes
+ *     back byte-for-byte — because a session still running on an older build
+ *     is rewriting it every minute — is deleted on sight instead of asked
+ *     about again. Deleting the file used to be the entire memory of the
+ *     answer, which is how the same question survived being answered three
+ *     times.
+ *   - The offer is also where that ledger gets swept. Every run prunes it to
+ *     its age and count bounds and logs what it dropped, so the record of past
+ *     decisions cannot quietly grow forever and nothing is deleted in silence.
  */
 import { statSync } from 'node:fs';
 import { checkRecoveryFile, checkRecoveryForSession, consumeRecovery, removeRecoveryPoint } from '@/runtime/index.ts';
 import type { RecoveryFileInfo, SessionSurface } from '@/runtime/index.ts';
+import { isRecoveryRemovalRecorded, pruneRecoveryDecisions, recordRecoveryRemoval } from './recovery-decisions.ts';
 import { checkSessionLiveness } from './session-liveness-marker.ts';
 import type { SelectionItem, SelectionResult } from '../input/selection-modal.ts';
 
@@ -213,11 +224,50 @@ function defaultSnapshotBytes(surface: SessionSurface, sessionId: string): numbe
  */
 const answeredThisRun = new Set<string>();
 
-/** Test seam: a fresh process has no answered offers. */
+/**
+ * Test seam: a fresh process has no answered offers. Only clears the
+ * in-process Keep memory — removal decisions are durable on purpose and live
+ * in the surface's own directory, so a test gets a clean ledger by using a
+ * fresh temp surface, the same way a real user gets one by using a different
+ * machine.
+ */
 export function resetAnsweredRecoveryOffersForTest(): void {
   answeredThisRun.clear();
 }
 
+/**
+ * How many times one offer pass will delete a recorded-removed snapshot and
+ * look again. A bound rather than a `while (true)`: the same session can have
+ * a snapshot in both the canonical and the legacy shared directory, so one
+ * removal can legitimately need a second pass, but nothing here should be able
+ * to spin if a delete ever fails to take.
+ */
+const MAX_RECORDED_REMOVAL_PASSES = 8;
+
+/**
+ * The snapshot to actually ask about, after honouring decisions already made.
+ *
+ * A snapshot whose session is in the removal ledger is deleted here and NOT
+ * offered: the user answered that question already, and re-asking because the
+ * file came back is the defect. Deleting rather than merely skipping matters —
+ * skipping would leave the file to mask an older, genuinely-orphaned snapshot
+ * underneath it forever.
+ */
+function findOfferableSnapshot(deps: RecoveryPromptDeps): RecoveryFileInfo | null {
+  for (let pass = 0; pass < MAX_RECORDED_REMOVAL_PASSES; pass += 1) {
+    const info = deps.targetSessionId !== undefined
+      ? checkRecoveryForSession(deps.surface, deps.targetSessionId)
+      : checkRecoveryFile({ surface: deps.surface });
+    if (!info) return null;
+    if (!isRecoveryRemovalRecorded(deps.surface, info.sessionId)) return info;
+    // Silently, because the user already said remove. A receipt here would be
+    // a notification about a decision they made and do not need re-confirmed.
+    const { removed } = removeRecoveryPoint(deps.surface, info.sessionId);
+    if (!removed) return null;
+  }
+  return null;
+}
+
 /**
  * Run the startup recovery offer. Resolves once the user has answered (or
  * once it is established that there is nothing to ask about). Never throws:
@@ -225,9 +275,14 @@ export function resetAnsweredRecoveryOffersForTest(): void {
  */
 export async function offerRecoverySnapshot(deps: RecoveryPromptDeps): Promise<RecoveryPromptOutcome> {
   try {
-    const info = deps.targetSessionId !== undefined
-      ? checkRecoveryForSession(deps.surface, deps.targetSessionId)
-      : checkRecoveryFile({ surface: deps.surface });
+    // Housekeeping first: recovery time is when the removal ledger gets its
+    // bounds actually applied to disk and says what it discarded. Without this
+    // the expired records were filtered on read but never removed, so on a
+    // machine where the user never answers "Remove" again the file only ever
+    // grew. Idempotent, so the second call in a run (targeted --continue offer
+    // plus the general startup offer) drops nothing and writes nothing.
+    pruneRecoveryDecisions(deps.surface, deps.now?.() ?? Date.now());
+    const info = findOfferableSnapshot(deps);
     if (!info) return 'none';
     // Already answered about this snapshot earlier in this same run (the
     // targeted --continue offer and the general startup offer can both find
@@ -270,9 +325,14 @@ export async function offerRecoverySnapshot(deps: RecoveryPromptDeps): Promise<R
     const retire = await ask(open, RECOVERY_RETIRE_TITLE, buildRecoveryRetireItems(facts));
     if (retire === 'remove') {
       const { removed } = removeRecoveryPoint(deps.surface, info.sessionId);
+      // Recorded whether or not a file was there to delete: the answer is
+      // about this snapshot, and a snapshot that vanished between the question
+      // and the answer can still be rewritten a minute later by whatever wrote
+      // it in the first place.
+      recordRecoveryRemoval(deps.surface, info.sessionId);
       deps.receipt(removed
-        ? `Recovery point removed (session ${info.sessionId}).`
-        : `No recovery point was found to remove (session ${info.sessionId}).`);
+        ? `Recovery point removed (session ${info.sessionId}) — it will not be offered again, even if the file reappears.`
+        : `No recovery point was found to remove (session ${info.sessionId}) — if one reappears for that session it will be discarded, not offered.`);
       deps.render();
       return 'removed';
     }

package/src/runtime/services.ts

@@ -96,6 +96,8 @@ export interface RuntimeServicesOptions {
   /** Host power seam opt-in. Fork mirrors the SDK: non-spawning unavailable-seam
    * default (idle-power-services.ts); daemon + embedded runtime pass createHostPowerSeam(). */
   readonly powerSeam?: Parameters<typeof wireIdlePowerAndLiveTurn>[0]['powerSeam'];
+  /** Live session id, read per crash-residue sweep so the running session is exempt — see durability-services.ts. */
+  readonly currentSessionId?: (() => string | null) | undefined;
 }
 
 export interface RuntimeServices {
@@ -207,6 +209,9 @@ export interface RuntimeServices {
   readonly codeIndexReindexScheduler: CodeIndexReindexScheduler; // tool-site reindex
   /** Daily snapshots of every SQLite store this runtime writes, with bounded retention; unref'd timers (mirrors the SDK composition — hosts that tear down a runtime stop() it themselves). */
   readonly storeSnapshotScheduler: StoreSnapshotScheduler;
+  readonly appendOnlyRetentionScheduler: ReturnType<typeof createDurabilityServices>['appendOnlyRetentionScheduler']; // periodic append-only sweep; unref'd timers, stop() on teardown
+  /** Stops the recurring crash-residue sweep; idempotent, unref'd timer (hosts that tear a runtime down call it). */
+  readonly stopDurabilityHousekeeping: () => void;
   readonly memoryConsolidationScheduler: MemoryConsolidationScheduler;
   readonly powerManager: PowerManager;
   /** The daemon's memory governor (default ON). Backs ops.memory.get and defends the daemon's footprint by tier. */
@@ -566,10 +571,10 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // with MemoryStore above. Auto-build is config-gated (default off) — see
   // code-index-services.ts's header doc.
   const { codeIndexStore, codeIndexReindexScheduler } = createCodeIndexServices({ workingDirectory, configManager, memoryEmbeddingRegistry, isReindexPaused: () => pauseController.isPaused('code-index-reindex'), admitExpensiveWork });
-  // Store snapshots + durable remembered-approval rules + the live credential
-  // chain, mirroring the SDK composition — see durability-services.ts.
-  const { storeSnapshotScheduler, userPermissionRuleStore } = createDurabilityServices({
+  // Store snapshots, the periodic append-only sweep, durable remembered-approval rules + the live credential chain — see durability-services.ts.
+  const { storeSnapshotScheduler, appendOnlyRetentionScheduler, userPermissionRuleStore, stopDurabilityHousekeeping } = createDurabilityServices({
     configManager, secretsManager, providerRegistry, memoryDbPath, codeIndexDbPath: codeIndexDbPath(workingDirectory), surface, shellPaths, // + retention-sweep roots & live config watch (mirrors the SDK)
+    ...(options.currentSessionId ? { currentSessionId: options.currentSessionId } : {}), // exempts the running session from crash-residue reaping
   });
   const codeInjectionOrchestratorDeps = { codeIndex: codeIndexStore, isCodeInjectionSettingEnabled: () => isCodeInjectionSettingEnabled(configManager), codeIndexReindexScheduler }; // Code-injection seam (agent here; main via orchestrator-core-services.ts)
   const { processRegistry } = createFleetServices({ // Shared archive-aware fleet registry (+ daemon observed rows) — see fleet-services.ts
@@ -778,7 +783,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     workstreamCommands,
     codeIndexStore,
     codeIndexReindexScheduler,
-    storeSnapshotScheduler,
+    storeSnapshotScheduler, appendOnlyRetentionScheduler, stopDurabilityHousekeeping,
     memoryConsolidationScheduler,
     powerManager,
     memoryGovernor,

package/src/runtime/session-liveness-marker.ts

@@ -24,7 +24,7 @@
  * recovery snapshots they describe — mirrors the transcript-journal.ts
  * convention (homeDirectory-scoped, under the surface's own directory).
  */
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { SessionSurface } from '@/runtime/index.ts';
 
@@ -42,9 +42,14 @@ export interface LivenessMarker {
  */
 export const LIVENESS_STALE_AFTER_MS = 150_000;
 
+/** Absolute path to the directory holding every session's liveness marker. */
+export function livenessMarkerDirFor(surface: SessionSurface): string {
+  return join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot, 'liveness');
+}
+
 /** Absolute path to a session's liveness marker file. */
 export function livenessMarkerPathFor(surface: SessionSurface, sessionId: string): string {
-  return join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot, 'liveness', `${sessionId}.json`);
+  return join(livenessMarkerDirFor(surface), `${sessionId}.json`);
 }
 
 /** Refresh (creating if needed) the liveness marker for this session/pid. Best-effort — never throws. */
@@ -69,18 +74,27 @@ export function removeLivenessMarker(surface: SessionSurface, sessionId: string)
   }
 }
 
-function readLivenessMarker(surface: SessionSurface, sessionId: string): LivenessMarker | null {
+/** Parse one marker file by absolute path. Returns null for missing, empty, torn, or wrong-shaped content. */
+function parseMarkerFile(path: string): LivenessMarker | null {
   try {
-    const path = livenessMarkerPathFor(surface, sessionId);
     if (!existsSync(path)) return null;
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<LivenessMarker>;
+    const text = readFileSync(path, 'utf-8');
+    // A crash between create and write leaves a zero-byte file. Content, not
+    // existence, decides whether this marker says anything at all.
+    if (text.trim().length === 0) return null;
+    const parsed = JSON.parse(text) as Partial<LivenessMarker>;
     if (typeof parsed.sessionId !== 'string' || typeof parsed.pid !== 'number' || typeof parsed.updatedAt !== 'number') return null;
+    if (!Number.isFinite(parsed.pid) || !Number.isFinite(parsed.updatedAt)) return null;
     return { sessionId: parsed.sessionId, pid: parsed.pid, updatedAt: parsed.updatedAt };
   } catch {
     return null;
   }
 }
 
+function readLivenessMarker(surface: SessionSurface, sessionId: string): LivenessMarker | null {
+  return parseMarkerFile(livenessMarkerPathFor(surface, sessionId));
+}
+
 /** Best-effort check that a pid still refers to a running process. Injectable for tests. */
 export function isPidAlive(pid: number, kill: (pid: number, signal: 0) => void = process.kill.bind(process)): boolean {
   try {
@@ -118,3 +132,126 @@ export function checkSessionLiveness(
   if (!aliveCheck(marker.pid)) return { live: false, pid: null };
   return { live: true, pid: marker.pid };
 }
+
+// ─── Reaping ────────────────────────────────────────────────────────────────
+//
+// `removeLivenessMarker` only runs on a CLEAN exit (process-lifecycle.ts). A
+// SIGKILL, a panic, or a pulled power cord leaves the marker behind forever,
+// and `checkSessionLiveness` treating it as not-live does not remove the file
+// — so the liveness directory grows one file per session id ever opened. The
+// sweep below is the reclaim half of that lifecycle.
+
+/**
+ * Hard ceiling on marker files kept after a sweep, oldest dropped first.
+ *
+ * The liveness rule below already reclaims ordinary crash residue, but it can
+ * be defeated: `isPidAlive` deliberately reports EPERM (a pid this user cannot
+ * signal) as alive, so on a busy host a reused pid can keep a dead session's
+ * marker "live" indefinitely. This cap is the second, unconditional bound so
+ * the directory can never grow without limit whatever the pid probe says.
+ */
+export const LIVENESS_MARKER_MAX_FILES = 200;
+
+export interface LivenessReapResult {
+  /** Marker files examined this sweep. */
+  readonly scanned: number;
+  /** Marker files deleted this sweep. */
+  readonly reaped: number;
+}
+
+export interface LivenessReapOptions {
+  readonly now?: () => number;
+  readonly isPidAliveFn?: typeof isPidAlive;
+  /**
+   * Session ids that must never be reaped regardless of what the marker says
+   * — normally just the current session's id. Belt-and-braces: the current
+   * session refreshes its own marker every 60s, so the liveness rule already
+   * keeps it.
+   */
+  readonly keepSessionIds?: readonly string[];
+  /** Override the count cap (tests). */
+  readonly maxFiles?: number;
+}
+
+/**
+ * Delete liveness markers that no longer describe a running session.
+ *
+ * A marker is reaped when it is either:
+ *   - unreadable, empty, or not shaped like a marker (crash residue that can
+ *     never resolve to a live session again — validated by parsing the
+ *     content, not by the file merely existing); or
+ *   - definitively not live: older than `LIVENESS_STALE_AFTER_MS` AND its pid
+ *     no longer resolves to a running process.
+ *
+ * Both halves of that second rule are required on purpose. Deleting is
+ * destructive while a liveness answer is only advisory, so a marker that is
+ * stale-but-pid-alive (a wedged owner still holding the session) or
+ * fresh-but-pid-dead (a process that died seconds ago, or a pid probe that
+ * failed transiently) is left for a later sweep. A genuinely crashed session
+ * satisfies both conditions within `LIVENESS_STALE_AFTER_MS` and is reclaimed
+ * on the next sweep after that.
+ *
+ * Idempotent and safe to run concurrently from several processes: a marker
+ * another sweeper unlinked between the directory listing and this unlink
+ * (ENOENT) counts as reaped, never as an error.
+ */
+export function reapStaleLivenessMarkers(surface: SessionSurface, opts: LivenessReapOptions = {}): LivenessReapResult {
+  const dir = livenessMarkerDirFor(surface);
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((name) => name.endsWith('.json'));
+  } catch {
+    // No liveness directory yet, or it is unreadable — nothing to reclaim.
+    return { scanned: 0, reaped: 0 };
+  }
+
+  const now = opts.now?.() ?? Date.now();
+  const aliveCheck = opts.isPidAliveFn ?? isPidAlive;
+  const keep = new Set(opts.keepSessionIds ?? []);
+  const maxFiles = opts.maxFiles ?? LIVENESS_MARKER_MAX_FILES;
+
+  let reaped = 0;
+  /** Survivors, so the count cap below can drop the oldest of them. */
+  const survivors: { readonly path: string; readonly updatedAt: number }[] = [];
+
+  for (const name of names) {
+    const sessionId = name.slice(0, -'.json'.length);
+    if (keep.has(sessionId)) continue;
+    const path = join(dir, name);
+    const marker = parseMarkerFile(path);
+    if (marker === null) {
+      if (unlinkIfPresent(path)) reaped++;
+      continue;
+    }
+    const stale = now - marker.updatedAt > LIVENESS_STALE_AFTER_MS;
+    if (stale && !aliveCheck(marker.pid)) {
+      if (unlinkIfPresent(path)) reaped++;
+      continue;
+    }
+    survivors.push({ path, updatedAt: marker.updatedAt });
+  }
+
+  if (survivors.length > maxFiles) {
+    survivors.sort((a, b) => a.updatedAt - b.updatedAt); // oldest first
+    for (const victim of survivors.slice(0, survivors.length - maxFiles)) {
+      if (unlinkIfPresent(victim.path)) reaped++;
+    }
+  }
+
+  return { scanned: names.length, reaped };
+}
+
+/**
+ * Best-effort unlink shared by the sweep. Returns true when the file is gone
+ * because of (or by the time of) this call. A concurrent sweeper winning the
+ * race (ENOENT) is success, not failure; any other error leaves the file for
+ * the next sweep.
+ */
+function unlinkIfPresent(path: string): boolean {
+  try {
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT';
+  }
+}