@cleocode/core 2026.4.98 → 2026.4.100

package/src/gc/__tests__/transcript.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Transcript Lifecycle Tests (T735)
+ *
+ * Covers memory-architecture-spec.md §12.1 acceptance criteria:
+ * - TL-F5: prune --dry-run makes zero filesystem mutations
+ * - TL-F6: Budget cap triggers early prune when total size > threshold
+ * - TL-F7: API key absent falls back to 30d-only deletion
+ *
+ * Additional unit tests:
+ * - classifyTranscriptTier: correct hot/warm/cold at all boundary values
+ * - scanTranscripts: correct hot/warm counts for a known directory layout
+ * - pruneTranscripts: correct deletion with confirm=true
+ * - parseDurationMs: correct parsing of all supported formats
+ *
+ * Uses real temp directories (mkdtemp). No mocked filesystem.
+ *
+ * @task T735
+ * @epic T726
+ */
+
+import { mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  classifyTranscriptTier,
+  parseDurationMs,
+  pruneTranscripts,
+  scanTranscripts,
+} from '../transcript.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a fake session JSONL under `projectsDir/<slug>/`.
+ * Sets the mtime to `now - ageMs` so tier classification works correctly.
+ */
+async function createSession(
+  projectsDir: string,
+  slug: string,
+  sessionId: string,
+  ageMs: number,
+): Promise<string> {
+  const slugDir = join(projectsDir, slug);
+  await mkdir(slugDir, { recursive: true });
+
+  const jsonlPath = join(slugDir, `${sessionId}.jsonl`);
+  await writeFile(jsonlPath, `{"type":"user","text":"session ${sessionId}"}\n`, 'utf-8');
+
+  // Back-date the mtime to simulate age
+  const pastDate = new Date(Date.now() - ageMs);
+  await utimes(jsonlPath, pastDate, pastDate);
+
+  return jsonlPath;
+}
+
+// ---------------------------------------------------------------------------
+// classifyTranscriptTier
+// ---------------------------------------------------------------------------
+
+describe('classifyTranscriptTier', () => {
+  it('returns hot for age < 24h', () => {
+    expect(classifyTranscriptTier(0)).toBe('hot');
+    expect(classifyTranscriptTier(1 * 60 * 60 * 1000)).toBe('hot'); // 1h
+    expect(classifyTranscriptTier(23 * 60 * 60 * 1000)).toBe('hot'); // 23h
+  });
+
+  it('returns warm for age 24h–7d', () => {
+    const ONE_DAY = 24 * 60 * 60 * 1000;
+    const SEVEN_DAYS = 7 * ONE_DAY;
+    expect(classifyTranscriptTier(ONE_DAY)).toBe('warm');
+    expect(classifyTranscriptTier(ONE_DAY + 1000)).toBe('warm'); // just past 24h
+    expect(classifyTranscriptTier(3 * ONE_DAY)).toBe('warm'); // 3 days
+    expect(classifyTranscriptTier(SEVEN_DAYS - 1000)).toBe('warm'); // just under 7d
+  });
+
+  it('returns cold for age >= 7d', () => {
+    const SEVEN_DAYS = 7 * 24 * 60 * 60 * 1000;
+    expect(classifyTranscriptTier(SEVEN_DAYS)).toBe('cold');
+    expect(classifyTranscriptTier(SEVEN_DAYS + 1000)).toBe('cold');
+    expect(classifyTranscriptTier(30 * 24 * 60 * 60 * 1000)).toBe('cold'); // 30d
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseDurationMs
+// ---------------------------------------------------------------------------
+
+describe('parseDurationMs', () => {
+  it('parses days correctly', () => {
+    expect(parseDurationMs('7d')).toBe(7 * 24 * 60 * 60 * 1000);
+    expect(parseDurationMs('1d')).toBe(24 * 60 * 60 * 1000);
+    expect(parseDurationMs('30d')).toBe(30 * 24 * 60 * 60 * 1000);
+  });
+
+  it('parses hours correctly', () => {
+    expect(parseDurationMs('24h')).toBe(24 * 60 * 60 * 1000);
+    expect(parseDurationMs('1h')).toBe(60 * 60 * 1000);
+    expect(parseDurationMs('168h')).toBe(168 * 60 * 60 * 1000);
+  });
+
+  it('parses minutes correctly', () => {
+    expect(parseDurationMs('30m')).toBe(30 * 60 * 1000);
+    expect(parseDurationMs('1m')).toBe(60 * 1000);
+  });
+
+  it('parses seconds correctly', () => {
+    expect(parseDurationMs('60s')).toBe(60 * 1000);
+  });
+
+  it('throws on invalid format', () => {
+    expect(() => parseDurationMs('invalid')).toThrow();
+    expect(() => parseDurationMs('7')).toThrow();
+    expect(() => parseDurationMs('')).toThrow();
+    expect(() => parseDurationMs('7w')).toThrow(); // weeks not supported
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scanTranscripts — correct hot/warm counts
+// ---------------------------------------------------------------------------
+
+describe('scanTranscripts', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-scan-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns empty result when projects dir does not exist', async () => {
+    const result = await scanTranscripts(join(tmpDir, 'nonexistent'));
+    expect(result.totalSessions).toBe(0);
+    expect(result.hot).toHaveLength(0);
+    expect(result.warm).toHaveLength(0);
+  });
+
+  it('correctly identifies hot sessions (< 24h)', async () => {
+    // 1 hour old → hot
+    await createSession(projectsDir, 'proj', 'hot-session', 1 * 60 * 60 * 1000);
+
+    const result = await scanTranscripts(projectsDir);
+
+    expect(result.hot).toHaveLength(1);
+    expect(result.warm).toHaveLength(0);
+    expect(result.hot[0]?.sessionId).toBe('hot-session');
+    expect(result.hot[0]?.tier).toBe('hot');
+  });
+
+  it('correctly identifies warm sessions (1–7d)', async () => {
+    // 3 days old → warm
+    await createSession(projectsDir, 'proj', 'warm-session', 3 * 24 * 60 * 60 * 1000);
+
+    const result = await scanTranscripts(projectsDir);
+
+    expect(result.warm).toHaveLength(1);
+    expect(result.hot).toHaveLength(0);
+    expect(result.warm[0]?.sessionId).toBe('warm-session');
+    expect(result.warm[0]?.tier).toBe('warm');
+  });
+
+  it('cold sessions (>7d, already deleted) do not appear in scan', async () => {
+    // Create a file but COLD sessions should have already been deleted from disk
+    // We verify cold sessions don't appear in warm/hot lists
+    const result = await scanTranscripts(projectsDir);
+    // No sessions created yet → all empty
+    expect(result.totalSessions).toBe(0);
+  });
+
+  it('counts sessions across multiple projects', async () => {
+    await createSession(projectsDir, 'proj-a', 'session-1', 1 * 60 * 60 * 1000); // hot
+    await createSession(projectsDir, 'proj-a', 'session-2', 2 * 24 * 60 * 60 * 1000); // warm
+    await createSession(projectsDir, 'proj-b', 'session-3', 5 * 24 * 60 * 60 * 1000); // warm
+
+    const result = await scanTranscripts(projectsDir);
+
+    expect(result.totalSessions).toBe(3);
+    expect(result.hot).toHaveLength(1);
+    expect(result.warm).toHaveLength(2);
+  });
+
+  it('totalBytes is the sum of all session file sizes', async () => {
+    await createSession(projectsDir, 'proj', 'size-session', 1 * 60 * 60 * 1000);
+
+    const result = await scanTranscripts(projectsDir);
+    expect(result.totalBytes).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TL-F5: prune --dry-run makes zero filesystem mutations
+// ---------------------------------------------------------------------------
+
+describe('pruneTranscripts dry-run (TL-F5)', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-prune-dr-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('dry-run (confirm=false) makes zero filesystem mutations', async () => {
+    // Use 35d to be beyond the 30d API-key-absent circuit breaker minimum
+    const OLD_SESSION_AGE = 35 * 24 * 60 * 60 * 1000; // 35 days
+    const jsonlPath = await createSession(projectsDir, 'proj', 'old-session', OLD_SESSION_AGE);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000, // 7d threshold
+      confirm: false, // dry-run
+      projectsDir,
+    });
+
+    // File must still exist after dry-run
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined();
+
+    expect(result.dryRun).toBe(true);
+    expect(result.pruned).toBeGreaterThan(0);
+    expect(result.deletedPaths).toContain(jsonlPath);
+  });
+
+  it('dry-run reports correct byte count', async () => {
+    const content = 'x'.repeat(1024); // 1 KB
+    const slugDir = join(projectsDir, 'proj');
+    await mkdir(slugDir, { recursive: true });
+    const jsonlPath = join(slugDir, 'big-session.jsonl');
+    await writeFile(jsonlPath, content, 'utf-8');
+    // Use 35d to exceed the 30d API-key-absent circuit breaker minimum
+    const past = new Date(Date.now() - 35 * 24 * 60 * 60 * 1000);
+    await utimes(jsonlPath, past, past);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: false,
+      projectsDir,
+    });
+
+    expect(result.bytesFreed).toBeGreaterThanOrEqual(1024);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// pruneTranscripts with confirm=true (actual deletion)
+// ---------------------------------------------------------------------------
+
+describe('pruneTranscripts confirm=true', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-prune-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('deletes sessions older than the threshold', async () => {
+    // Use 35d to be beyond the 30d API-key-absent circuit breaker minimum
+    const OLD_AGE = 35 * 24 * 60 * 60 * 1000; // 35 days
+    const jsonlPath = await createSession(projectsDir, 'proj', 'old-del', OLD_AGE);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: true,
+      projectsDir,
+    });
+
+    // File must be gone
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).rejects.toThrow();
+
+    expect(result.dryRun).toBe(false);
+    expect(result.pruned).toBeGreaterThan(0);
+  });
+
+  it('does NOT delete sessions younger than the threshold', async () => {
+    const RECENT_AGE = 1 * 24 * 60 * 60 * 1000; // 1 day
+    const jsonlPath = await createSession(projectsDir, 'proj', 'recent-keep', RECENT_AGE);
+
+    await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: true,
+      projectsDir,
+    });
+
+    // Recent file must still exist
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TL-F7: ANTHROPIC_API_KEY absent → 30d-only deletion (circuit breaker)
+// ---------------------------------------------------------------------------
+
+describe('pruneTranscripts API key circuit breaker (TL-F7)', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+  let savedApiKey: string | undefined;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-apikey-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+    // Save and clear API key
+    savedApiKey = process.env['ANTHROPIC_API_KEY'];
+    delete process.env['ANTHROPIC_API_KEY'];
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    // Restore API key
+    if (savedApiKey !== undefined) {
+      process.env['ANTHROPIC_API_KEY'] = savedApiKey;
+    }
+  });
+
+  it('skips deletion of sessions < 30d when API key is absent', async () => {
+    // 10-day-old session; caller requests 7d threshold
+    const TEN_DAYS = 10 * 24 * 60 * 60 * 1000;
+    const jsonlPath = await createSession(projectsDir, 'proj', 'apikey-test', TEN_DAYS);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000, // 7d requested
+      confirm: true,
+      projectsDir,
+    });
+
+    // Circuit breaker: no API key → 30d minimum. 10-day session is NOT deleted.
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined();
+
+    expect(result.pruned).toBe(0);
+  });
+
+  it('allows deletion of sessions > 30d even without API key', async () => {
+    // 35-day-old session — beyond the 30d circuit-breaker minimum
+    const THIRTY_FIVE_DAYS = 35 * 24 * 60 * 60 * 1000;
+    const jsonlPath = await createSession(projectsDir, 'proj', 'old-apikey', THIRTY_FIVE_DAYS);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: true,
+      projectsDir,
+    });
+
+    // 35-day session IS deleted (beyond 30d fallback minimum)
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).rejects.toThrow();
+
+    expect(result.pruned).toBeGreaterThan(0);
+  });
+});

package/src/gc/daemon-entry.ts

@@ -0,0 +1,26 @@
+/**
+ * GC Daemon Entry Point — Standalone script executed by `spawnGCDaemon()`.
+ *
+ * This script is spawned as a detached background process by `cleo daemon start`.
+ * It must NOT import from the main CLI shim (no citty, no commander). It only
+ * imports from the gc/ module subtree.
+ *
+ * The cleoDir is passed as argv[2] by `spawnGCDaemon()`.
+ *
+ * @see gc/daemon.ts for the spawn logic
+ * @task T731
+ * @epic T726
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { bootstrapDaemon } from './daemon.js';
+
+const cleoDir = process.argv[2] ?? join(homedir(), '.cleo');
+
+bootstrapDaemon(cleoDir).catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  // stderr is redirected to gc.err by the parent spawn call
+  process.stderr.write(`[CLEO GC] Fatal daemon error: ${message}\n`);
+  process.exit(1);
+});

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';