@cleocode/core 2026.4.98 → 2026.4.99

package/src/gc/daemon.ts

@@ -0,0 +1,251 @@
+/**
+ * GC Daemon — Sidecar background process for autonomous transcript cleanup.
+ *
+ * Architecture (Pattern B from T751 §2.2):
+ * - Spawned via `cleo daemon start` as a detached Node.js process
+ * - All three required flags: `detached: true`, file stdio, `child.unref()`
+ * - Persists across CLI invocations
+ * - Crash recovery via `.cleo/gc-state.json` startup-check
+ * - node-cron v4 for scheduling (zero runtime deps, cross-platform)
+ *
+ * Startup algorithm (systemd `Persistent=true` semantics in pure Node.js):
+ * 1. Read gc-state.json
+ * 2. If pendingPrune non-empty → resume deletion (crash recovery)
+ * 3. If lastRunAt null OR elapsed > 24h → run GC immediately (missed-run recovery)
+ * 4. Schedule future runs via node-cron (daily at 03:00 UTC)
+ * 5. Write daemonPid to state
+ *
+ * @see ADR-047 — Autonomous GC and Disk Safety
+ * @see T751 §2.2 for sidecar daemon pattern rationale
+ * @task T731
+ * @epic T726
+ */
+
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import cron from 'node-cron';
+import { runGC } from './runner.js';
+import { patchGCState, readGCState } from './state.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Cron expression: daily at 03:00 UTC. */
+const GC_CRON_EXPR = '0 3 * * *';
+
+/** Interval for missed-run recovery check (24 hours in ms). */
+const GC_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Daemon Bootstrap (runs when this module is executed as a standalone script)
+// ---------------------------------------------------------------------------
+
+/**
+ * Bootstrap the GC daemon process.
+ *
+ * Performs crash recovery, missed-run recovery, and schedules future GC runs.
+ * This function runs in the long-lived daemon process.
+ *
+ * @param cleoDir - Absolute path to the `.cleo/` directory
+ */
+export async function bootstrapDaemon(cleoDir: string): Promise<void> {
+  const statePath = join(cleoDir, 'gc-state.json');
+
+  // Register daemon PID in state file
+  await patchGCState(statePath, {
+    daemonPid: process.pid,
+    daemonStartedAt: new Date().toISOString(),
+  });
+
+  const state = await readGCState(statePath);
+
+  // Step 1: Crash recovery — resume pending prune from prior run
+  if (state.pendingPrune && state.pendingPrune.length > 0) {
+    try {
+      await runGC({ cleoDir, resumeFrom: state.pendingPrune });
+    } catch {
+      // Crash recovery failure is non-fatal; continue with scheduled runs
+    }
+  }
+
+  // Step 2: Missed-run recovery — if last run was > 24h ago, run immediately
+  const lastRunTs = state.lastRunAt ? new Date(state.lastRunAt).getTime() : 0;
+  const elapsed = Date.now() - lastRunTs;
+  if (elapsed > GC_INTERVAL_MS) {
+    try {
+      await runGC({ cleoDir });
+    } catch {
+      // Immediate GC failure is non-fatal; cron will retry next cycle
+    }
+  }
+
+  // Step 3: Schedule future runs via node-cron
+  // noOverlap: true prevents double-runs if a previous run exceeds 24h
+  cron.schedule(
+    GC_CRON_EXPR,
+    async () => {
+      try {
+        await runGC({ cleoDir });
+      } catch {
+        // Log failures via stderr (already redirected to gc.log by spawn)
+        const state2 = await readGCState(statePath);
+        await patchGCState(statePath, {
+          consecutiveFailures: state2.consecutiveFailures + 1,
+          lastRunResult: 'failed',
+          escalationNeeded: state2.consecutiveFailures + 1 >= 3,
+          escalationReason:
+            state2.consecutiveFailures + 1 >= 3
+              ? `GC daemon: ${state2.consecutiveFailures + 1} consecutive failures. Check logs.`
+              : state2.escalationReason,
+        });
+      }
+    },
+    {
+      timezone: 'UTC',
+      noOverlap: true,
+      name: 'cleo-gc',
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Spawn Helpers (called by `cleo daemon start` in the parent CLI process)
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn the GC daemon as a detached background process.
+ *
+ * All three requirements from T751 §2.2 are met:
+ * 1. `detached: true` — process group leader (survives parent exit)
+ * 2. File stdio — stdout/stderr redirected to gc.log (not inherited)
+ * 3. `child.unref()` — parent CLI exits immediately
+ *
+ * @param cleoDir - Absolute path to the `.cleo/` directory
+ * @returns PID of the spawned daemon process
+ */
+export async function spawnGCDaemon(cleoDir: string): Promise<number> {
+  const logsDir = join(cleoDir, 'logs');
+  await mkdir(logsDir, { recursive: true });
+
+  const logPath = join(logsDir, 'gc.log');
+  const errPath = join(logsDir, 'gc.err');
+
+  // File-based stdio: required for detached process to not inherit the TTY
+  const outStream = createWriteStream(logPath, { flags: 'a' });
+  const errStream = createWriteStream(errPath, { flags: 'a' });
+
+  // The daemon entry-point script (compiled alongside this module)
+  const daemonEntry = join(fileURLToPath(import.meta.url), '..', 'daemon-entry.js');
+
+  const child = spawn(process.execPath, [daemonEntry, cleoDir], {
+    detached: true,
+    stdio: ['ignore', outStream, errStream],
+    env: { ...process.env, CLEO_GC_DAEMON: '1' },
+  });
+
+  // unref() allows the parent CLI process to exit while the daemon continues
+  child.unref();
+
+  const pid = child.pid ?? 0;
+
+  // Persist PID so `cleo daemon stop` can find and signal the process
+  await patchGCState(join(cleoDir, 'gc-state.json'), {
+    daemonPid: pid,
+    daemonStartedAt: new Date().toISOString(),
+  });
+
+  return pid;
+}
+
+/**
+ * Stop the GC daemon by sending SIGTERM to its PID.
+ *
+ * Uses `process.kill(pid, 0)` as a no-throw liveness probe before signalling.
+ *
+ * @param cleoDir - Absolute path to the `.cleo/` directory
+ * @returns `{ stopped: boolean; pid: number | null; reason: string }`
+ */
+export async function stopGCDaemon(
+  cleoDir: string,
+): Promise<{ stopped: boolean; pid: number | null; reason: string }> {
+  const statePath = join(cleoDir, 'gc-state.json');
+  const state = await readGCState(statePath);
+  const pid = state.daemonPid;
+
+  if (!pid) {
+    return { stopped: false, pid: null, reason: 'Daemon PID not found in gc-state.json' };
+  }
+
+  // Liveness probe: process.kill(pid, 0) throws if PID is not running
+  try {
+    process.kill(pid, 0);
+  } catch {
+    // Process is not running — clear stale PID from state
+    await patchGCState(statePath, { daemonPid: null });
+    return {
+      stopped: false,
+      pid,
+      reason: `Daemon PID ${pid} is not running (stale state cleared)`,
+    };
+  }
+
+  // Send SIGTERM — daemon should clean up and exit gracefully
+  try {
+    process.kill(pid, 'SIGTERM');
+    // Clear PID from state after successful signal
+    await patchGCState(statePath, { daemonPid: null });
+    return { stopped: true, pid, reason: `SIGTERM sent to PID ${pid}` };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { stopped: false, pid, reason: `Failed to send SIGTERM to PID ${pid}: ${msg}` };
+  }
+}
+
+/**
+ * Check whether the GC daemon is currently running.
+ *
+ * @param cleoDir - Absolute path to the `.cleo/` directory
+ * @returns `{ running: boolean; pid: number | null; startedAt: string | null }`
+ */
+export async function getGCDaemonStatus(cleoDir: string): Promise<{
+  running: boolean;
+  pid: number | null;
+  startedAt: string | null;
+  lastRunAt: string | null;
+  lastDiskUsedPct: number | null;
+  escalationNeeded: boolean;
+}> {
+  const state = await readGCState(join(cleoDir, 'gc-state.json'));
+  const pid = state.daemonPid;
+
+  let running = false;
+  if (pid) {
+    try {
+      process.kill(pid, 0);
+      running = true;
+    } catch {
+      running = false;
+    }
+  }
+
+  return {
+    running,
+    pid: running ? pid : null,
+    startedAt: state.daemonStartedAt,
+    lastRunAt: state.lastRunAt,
+    lastDiskUsedPct: state.lastDiskUsedPct,
+    escalationNeeded: state.escalationNeeded,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Standalone daemon entry point
+// ---------------------------------------------------------------------------
+
+// When this module is executed directly (via `node daemon.js <cleoDir>`),
+// bootstrap the daemon. The daemon-entry.js shim calls bootstrapDaemon().
+// See src/gc/daemon-entry.ts for the entry script.

package/src/gc/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @cleocode/core/gc — Autonomous GC daemon public API.
+ *
+ * Provides transcript cleanup, disk-pressure monitoring, GC state
+ * management, and daemon lifecycle (spawn/stop/status).
+ *
+ * @see ADR-047 — Autonomous GC and Disk Safety
+ * @package @cleocode/core
+ */
+
+export * from './daemon.js';
+export * from './runner.js';
+export * from './state.js';
+export * from './transcript.js';

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