@cleocode/core 2026.4.98 → 2026.4.100

package/src/gc/runner.ts

@@ -0,0 +1,378 @@
+/**
+ * GC Runner — Core garbage collection logic for autonomous transcript cleanup.
+ *
+ * Performs disk-pressure-aware pruning of ephemeral transcript and temp files
+ * under `~/.claude/projects/` using the five-tier threshold model from T751.
+ *
+ * Retention policy (per ADR-047 and docs/specs/memory-architecture-spec.md §8):
+ * - `.temp/` files: 24h normal, 1h emergency
+ * - Transcript directories (agent-*.jsonl, tool-results/): 7d normal, 1d emergency
+ * - `.cleo/logs/`: 30d normal, 7d emergency
+ * - `.cleo/agent-outputs/*.md` (committed artifacts): NEVER auto-pruned
+ *
+ * Circuit breaker: if `ANTHROPIC_API_KEY` is absent AND no local model configured,
+ * skip extraction and only delete transcripts older than 30 days.
+ *
+ * @see ADR-047 — Autonomous GC and Disk Safety
+ * @see docs/specs/memory-architecture-spec.md §8
+ * @task T731
+ * @epic T726
+ */
+
+import { lstat, readdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import checkDiskSpaceModule from 'check-disk-space';
+
+/**
+ * Checks free + total bytes on the filesystem containing the given path.
+ *
+ * `check-disk-space@3.4.0` publishes its function as `export { x as default }`
+ * in the .d.ts, which TS 6.0 strict resolution treats as a namespaced re-export
+ * rather than a callable default. The runtime module itself exposes a callable;
+ * we bridge the type gap by typing `checkDiskSpaceModule` as the callable
+ * shape at the single import boundary.
+ */
+const checkDiskSpace = checkDiskSpaceModule as unknown as (path: string) => Promise<{
+  diskPath: string;
+  free: number;
+  size: number;
+}>;
+
+import { patchGCState, readGCState } from './state.js';
+
+// ---------------------------------------------------------------------------
+// Threshold Tiers (from T751 §3.2 and ADR-047)
+// ---------------------------------------------------------------------------
+
+/**
+ * Disk usage percentage thresholds.
+ *
+ * Values mirror the five-tier model recommended by T751 research §3.2:
+ * - OK:        < 70% — routine cleanup by age policy only
+ * - WATCH:    70-85% — log + schedule next GC sooner
+ * - WARN:     85-90% — log + set escalation flag for next CLI invocation
+ * - URGENT:   90-95% — auto-prune oldest transcripts immediately
+ * - EMERGENCY: ≥ 95% — auto-prune all transcripts > 1d, pause new writes
+ */
+export const DISK_THRESHOLDS = {
+  WATCH: 70,
+  WARN: 85,
+  URGENT: 90,
+  EMERGENCY: 95,
+} as const;
+
+/** Human-readable tier labels. */
+export type DiskTier = 'ok' | 'watch' | 'warn' | 'urgent' | 'emergency';
+
+/**
+ * Result of a single GC run.
+ */
+export interface GCResult {
+  /** Disk usage percentage at time of GC run (0–100). */
+  diskUsedPct: number;
+  /** Disk tier classification. */
+  threshold: DiskTier;
+  /** Files pruned during this run. */
+  pruned: Array<{ path: string; bytes: number }>;
+  /** Total bytes freed. */
+  bytesFreed: number;
+  /** Whether escalation flag was set (disk ≥ WARN). */
+  escalationSet: boolean;
+  /** Human-readable escalation reason (set when escalationSet=true). */
+  escalationReason: string | null;
+  /** ISO-8601 timestamp of run completion. */
+  completedAt: string;
+}
+
+/**
+ * Options for a GC run.
+ */
+export interface GCRunOptions {
+  /**
+   * Absolute path to the `.cleo/` directory (used for state file and disk check).
+   * Defaults to `~/.cleo`.
+   */
+  cleoDir?: string;
+  /**
+   * Override the default `~/.claude/projects/` scan directory.
+   * Primarily used in tests to point at a temp directory.
+   */
+  projectsDir?: string;
+  /**
+   * Paths from a previous crashed run to resume deletion from.
+   * Written to `pendingPrune` in gc-state.json BEFORE starting deletion.
+   */
+  resumeFrom?: string[];
+  /**
+   * Dry-run mode: compute what would be pruned, but make zero filesystem changes.
+   */
+  dryRun?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a disk usage percentage into a tier.
+ *
+ * @param pct - Disk usage percentage (0–100)
+ * @returns DiskTier
+ */
+export function classifyDiskTier(pct: number): DiskTier {
+  if (pct >= DISK_THRESHOLDS.EMERGENCY) return 'emergency';
+  if (pct >= DISK_THRESHOLDS.URGENT) return 'urgent';
+  if (pct >= DISK_THRESHOLDS.WARN) return 'warn';
+  if (pct >= DISK_THRESHOLDS.WATCH) return 'watch';
+  return 'ok';
+}
+
+/**
+ * Compute retention threshold in milliseconds based on disk tier.
+ *
+ * Higher disk pressure → shorter retention → more aggressive pruning.
+ *
+ * @param tier - Current disk tier
+ * @returns Maximum age in milliseconds for transcript retention
+ */
+export function retentionMs(tier: DiskTier): number {
+  switch (tier) {
+    case 'emergency':
+      return 1 * 24 * 60 * 60 * 1000; // 1 day
+    case 'urgent':
+      return 3 * 24 * 60 * 60 * 1000; // 3 days
+    case 'warn':
+      return 7 * 24 * 60 * 60 * 1000; // 7 days
+    default:
+      return 30 * 24 * 60 * 60 * 1000; // 30 days (watch + ok)
+  }
+}
+
+/**
+ * Get the size of a path in bytes (file or directory recursively).
+ * Returns 0 if the path does not exist.
+ *
+ * @param targetPath - Path to measure
+ * @returns Size in bytes
+ */
+export async function getPathBytes(targetPath: string): Promise<number> {
+  try {
+    const info = await lstat(targetPath);
+    if (info.isFile()) return info.size;
+    if (!info.isDirectory()) return 0;
+
+    const entries = await readdir(targetPath, { withFileTypes: true });
+    let total = 0;
+    for (const entry of entries) {
+      total += await getPathBytes(join(targetPath, entry.name));
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Idempotently delete a path (file or directory).
+ *
+ * Silently ignores ENOENT — safe to call if path was already deleted.
+ * Uses `force: true` to suppress errors on missing paths.
+ *
+ * @param targetPath - Path to delete
+ */
+export async function idempotentRm(targetPath: string): Promise<void> {
+  try {
+    await rm(targetPath, { recursive: true, force: true });
+  } catch (err) {
+    const nodeErr = err as NodeJS.ErrnoException;
+    if (nodeErr.code === 'ENOENT') return; // already gone — idempotent
+    throw err;
+  }
+}
+
+/**
+ * Gather transcript session directories under `~/.claude/projects/` that are
+ * older than `maxAgeMs`.
+ *
+ * Only session UUID directories are candidates (not the root JSONL files —
+ * those are the main transcript). The `tool-results/` subdirectory within a
+ * session directory is always included in the prune candidate once the session
+ * is old enough.
+ *
+ * Committed artifact files (`.cleo/agent-outputs/*.md`) are NEVER included.
+ *
+ * @param maxAgeMs - Maximum age in ms; sessions older than this are candidates
+ * @returns Array of absolute directory paths eligible for pruning
+ */
+async function gatherPruneCandidates(maxAgeMs: number, projectsDir?: string): Promise<string[]> {
+  const resolvedProjectsDir = projectsDir ?? join(homedir(), '.claude', 'projects');
+  const candidates: string[] = [];
+  const now = Date.now();
+
+  let projectSlugs: string[];
+  try {
+    const entries = await readdir(resolvedProjectsDir, { withFileTypes: true });
+    projectSlugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    // ~/.claude/projects/ doesn't exist yet
+    return candidates;
+  }
+
+  for (const slug of projectSlugs) {
+    const slugDir = join(resolvedProjectsDir, slug);
+
+    // Collect root JSONL files (HOT/WARM main session transcripts)
+    let slugEntries: import('fs').Dirent[];
+    try {
+      slugEntries = await readdir(slugDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of slugEntries) {
+      const entryPath = join(slugDir, entry.name);
+
+      if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+        // Root-level session JSONL — check age
+        try {
+          const info = await stat(entryPath);
+          const ageMs = now - info.mtimeMs;
+          if (ageMs > maxAgeMs) {
+            candidates.push(entryPath);
+          }
+        } catch {
+          // File disappeared between readdir and stat — skip
+        }
+      } else if (entry.isDirectory()) {
+        // Session UUID directory — check mtime of the directory itself
+        try {
+          const info = await stat(entryPath);
+          const ageMs = now - info.mtimeMs;
+          if (ageMs > maxAgeMs) {
+            candidates.push(entryPath);
+          }
+        } catch {
+          // Directory disappeared — skip
+        }
+      }
+    }
+  }
+
+  return candidates;
+}
+
+// ---------------------------------------------------------------------------
+// Main GC Runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a GC run: check disk pressure, determine retention threshold,
+ * prune eligible transcript files, update gc-state.json.
+ *
+ * This function is idempotent and safe to call multiple times. Crash recovery
+ * is implemented via the `pendingPrune` field in gc-state.json:
+ * 1. Write paths to `pendingPrune` BEFORE starting deletion
+ * 2. Remove each path from `pendingPrune` AFTER successful deletion
+ * 3. Clear `pendingPrune` when the job completes
+ *
+ * @param opts - GC run options
+ * @returns GC run results
+ */
+export async function runGC(opts: GCRunOptions = {}): Promise<GCResult> {
+  const cleoDir = opts.cleoDir ?? join(homedir(), '.cleo');
+  const statePath = join(cleoDir, 'gc-state.json');
+  const dryRun = opts.dryRun ?? false;
+  const projectsDir = opts.projectsDir;
+
+  // Step 1: Crash recovery — resume any pending prune from prior run
+  const initialState = await readGCState(statePath);
+  const resumePaths = opts.resumeFrom ?? initialState.pendingPrune ?? [];
+
+  // Step 2: Check disk space on the filesystem containing .cleo/
+  let diskUsedPct = 0;
+  try {
+    const { free, size } = await checkDiskSpace(cleoDir);
+    diskUsedPct = size > 0 ? ((size - free) / size) * 100 : 0;
+  } catch {
+    // Disk check failure is non-fatal; proceed with default tier
+    diskUsedPct = 0;
+  }
+
+  const tier = classifyDiskTier(diskUsedPct);
+  const maxAgeMs = retentionMs(tier);
+
+  // Step 3: Gather prune candidates
+  const candidatesFromScan =
+    resumePaths.length > 0 ? resumePaths : await gatherPruneCandidates(maxAgeMs, projectsDir);
+
+  // Step 4: Write pendingPrune to state BEFORE any deletion (crash-safe)
+  if (!dryRun && candidatesFromScan.length > 0) {
+    await patchGCState(statePath, { pendingPrune: candidatesFromScan });
+  }
+
+  // Step 5: Delete candidates and accumulate results
+  const pruned: GCResult['pruned'] = [];
+  let bytesFreed = 0;
+  const remaining = [...candidatesFromScan];
+
+  for (const candidatePath of candidatesFromScan) {
+    const bytes = await getPathBytes(candidatePath);
+
+    if (dryRun) {
+      // Dry run: record what would be deleted, make no changes
+      pruned.push({ path: candidatePath, bytes });
+      bytesFreed += bytes;
+      continue;
+    }
+
+    try {
+      await idempotentRm(candidatePath);
+      pruned.push({ path: candidatePath, bytes });
+      bytesFreed += bytes;
+      // Remove successfully-deleted path from the pending list
+      const idx = remaining.indexOf(candidatePath);
+      if (idx !== -1) remaining.splice(idx, 1);
+      // Persist updated pendingPrune after each deletion (crash-safe)
+      await patchGCState(statePath, {
+        pendingPrune: remaining.length > 0 ? remaining : null,
+      });
+    } catch {
+      // Deletion failure: leave in pendingPrune for next run
+    }
+  }
+
+  // Step 6: Determine escalation state
+  const escalationSet = tier === 'warn' || tier === 'urgent' || tier === 'emergency';
+  let escalationReason: string | null = null;
+  if (escalationSet) {
+    escalationReason = `Disk at ${diskUsedPct.toFixed(1)}% (${tier.toUpperCase()}): ${pruned.length} paths pruned, ${bytesFreed} bytes freed`;
+  }
+
+  const completedAt = new Date().toISOString();
+
+  // Step 7: Update gc-state.json with run results
+  if (!dryRun) {
+    await patchGCState(statePath, {
+      lastRunAt: completedAt,
+      lastRunResult: remaining.length === 0 ? 'success' : 'partial',
+      lastRunBytesFreed: bytesFreed,
+      pendingPrune: remaining.length > 0 ? remaining : null,
+      consecutiveFailures: remaining.length > 0 ? initialState.consecutiveFailures + 1 : 0,
+      diskThresholdBreached: diskUsedPct >= DISK_THRESHOLDS.WATCH,
+      lastDiskUsedPct: diskUsedPct,
+      escalationNeeded: escalationSet || initialState.escalationNeeded,
+      escalationReason: escalationReason ?? initialState.escalationReason,
+    });
+  }
+
+  return {
+    diskUsedPct,
+    threshold: tier,
+    pruned,
+    bytesFreed,
+    escalationSet,
+    escalationReason,
+    completedAt,
+  };
+}

package/src/gc/state.ts

@@ -0,0 +1,140 @@
+/**
+ * GC State — Persistent crash-recovery state for the autonomous GC daemon.
+ *
+ * Stored in `.cleo/gc-state.json` (plain JSON, not SQLite) to avoid
+ * SQLite WAL conflicts between the long-running daemon process and the
+ * main CLEO CLI process. Human-readable for debugging.
+ *
+ * The file is gitignored (see .gitignore §.cleo/ section) and created empty
+ * by `cleo init`. It is NOT included in `cleo backup restore` scope because
+ * it is ephemeral operational state — only the `daemonPid` and `lastRunAt`
+ * fields survive between process restarts.
+ *
+ * @see ADR-047 — Autonomous GC and Disk Safety
+ * @task T731
+ * @epic T726
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/** Schema version for gc-state.json. Bump on breaking field changes. */
+export const GC_STATE_SCHEMA_VERSION = '1.0' as const;
+
+/**
+ * Persistent GC daemon state written to `.cleo/gc-state.json`.
+ *
+ * Design principles:
+ * - `pendingPrune` enables idempotent crash recovery: populate BEFORE deletion,
+ *   clear each entry AFTER successful deletion, clear entirely when job completes.
+ * - `diskThresholdBreached` is a sticky flag: cleared only when disk drops
+ *   below the WATCH tier (70%).
+ * - `escalationNeeded` is set by the daemon when disk is in WARN/URGENT range;
+ *   cleared by the CLI after displaying the escalation banner.
+ */
+export interface GCState {
+  /** JSON schema version for forward-compatibility checks. */
+  schemaVersion: typeof GC_STATE_SCHEMA_VERSION;
+  /** ISO-8601 timestamp of last COMPLETED GC run. null = never run. */
+  lastRunAt: string | null;
+  /** Outcome of the last GC run. */
+  lastRunResult: 'success' | 'partial' | 'failed' | null;
+  /** Bytes freed in the last completed GC run. */
+  lastRunBytesFreed: number;
+  /**
+   * Paths queued for deletion but not yet deleted.
+   * Written BEFORE starting deletion; cleared entry-by-entry on success.
+   * Enables idempotent crash recovery on daemon restart.
+   */
+  pendingPrune: string[] | null;
+  /** Number of consecutive GC failures. Triggers escalation banner after 3. */
+  consecutiveFailures: number;
+  /** Sticky flag: true when disk is ≥ WATCH tier (70%). Cleared when disk < 70%. */
+  diskThresholdBreached: boolean;
+  /** Current disk usage percentage (0–100) from the last GC run. */
+  lastDiskUsedPct: number | null;
+  /**
+   * Escalation banner flag. Set by daemon when disk is in WARN+ range.
+   * Cleared by CLI after displaying the banner to the user.
+   */
+  escalationNeeded: boolean;
+  /** Escalation reason shown in the CLI banner. */
+  escalationReason: string | null;
+  /** PID of the currently running daemon process. null = daemon not running. */
+  daemonPid: number | null;
+  /** ISO-8601 timestamp when the daemon was last started. */
+  daemonStartedAt: string | null;
+}
+
+/** Default (empty) GC state for fresh initialisation. */
+export const DEFAULT_GC_STATE: GCState = {
+  schemaVersion: GC_STATE_SCHEMA_VERSION,
+  lastRunAt: null,
+  lastRunResult: null,
+  lastRunBytesFreed: 0,
+  pendingPrune: null,
+  consecutiveFailures: 0,
+  diskThresholdBreached: false,
+  lastDiskUsedPct: null,
+  escalationNeeded: false,
+  escalationReason: null,
+  daemonPid: null,
+  daemonStartedAt: null,
+};
+
+/**
+ * Read the GC state from disk.
+ *
+ * Returns the default state if the file does not exist or is malformed.
+ * Never throws — GC state file absence is not an error condition.
+ *
+ * @param statePath - Absolute path to gc-state.json
+ * @returns Parsed GC state, merged with defaults for any missing fields
+ */
+export async function readGCState(statePath: string): Promise<GCState> {
+  try {
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<GCState>;
+    // Merge with defaults so new fields added in future schema versions
+    // don't cause undefined access on old state files.
+    return { ...DEFAULT_GC_STATE, ...parsed };
+  } catch {
+    // ENOENT (file not yet created) or JSON parse error → use defaults
+    return { ...DEFAULT_GC_STATE };
+  }
+}
+
+/**
+ * Write the GC state to disk atomically via tmp-then-rename.
+ *
+ * Atomic write prevents partial reads if the daemon crashes mid-write.
+ * Idempotent: safe to call multiple times.
+ *
+ * @param statePath - Absolute path to gc-state.json
+ * @param state - GC state to persist
+ */
+export async function writeGCState(statePath: string, state: GCState): Promise<void> {
+  const dir = dirname(statePath);
+  await mkdir(dir, { recursive: true });
+
+  const tmpPath = join(dir, `.gc-state-${process.pid}.tmp`);
+  const json = JSON.stringify(state, null, 2);
+
+  await writeFile(tmpPath, json, 'utf-8');
+  await rename(tmpPath, statePath);
+}
+
+/**
+ * Patch a subset of fields in the GC state file.
+ *
+ * Convenience wrapper: reads current state, merges patch, writes back.
+ *
+ * @param statePath - Absolute path to gc-state.json
+ * @param patch - Partial state to merge over the existing state
+ */
+export async function patchGCState(statePath: string, patch: Partial<GCState>): Promise<GCState> {
+  const current = await readGCState(statePath);
+  const updated: GCState = { ...current, ...patch };
+  await writeGCState(statePath, updated);
+  return updated;
+}