@cleocode/core 2026.4.98 → 2026.4.100

package/dist/gc/daemon-entry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=daemon-entry.d.ts.map

package/dist/gc/daemon-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-entry.d.ts","sourceRoot":"","sources":["../../src/gc/daemon-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/gc/daemon.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare function bootstrapDaemon(cleoDir: string): Promise<void>;
+/**
+ * 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 declare function spawnGCDaemon(cleoDir: string): Promise<number>;
+/**
+ * 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 declare function stopGCDaemon(cleoDir: string): Promise<{
+    stopped: boolean;
+    pid: number | null;
+    reason: string;
+}>;
+/**
+ * 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 declare function getGCDaemonStatus(cleoDir: string): Promise<{
+    running: boolean;
+    pid: number | null;
+    startedAt: string | null;
+    lastRunAt: string | null;
+    lastDiskUsedPct: number | null;
+    escalationNeeded: boolean;
+}>;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/gc/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/gc/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAyBH;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0DpE;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCpE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCnE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC,CAsBD"}

package/dist/gc/daemon.js

@@ -0,0 +1,481 @@
+// packages/core/src/gc/daemon.ts
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { mkdir as mkdir2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+import cron from "node-cron";
+
+// packages/core/src/gc/runner.ts
+import { lstat, readdir, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// node_modules/.pnpm/check-disk-space@3.4.0/node_modules/check-disk-space/dist/check-disk-space.mjs
+import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import { release } from "node:os";
+import { normalize, sep } from "node:path";
+import { platform } from "node:process";
+import { promisify } from "node:util";
+var InvalidPathError = class _InvalidPathError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidPathError";
+    Object.setPrototypeOf(this, _InvalidPathError.prototype);
+  }
+};
+var NoMatchError = class _NoMatchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NoMatchError";
+    Object.setPrototypeOf(this, _NoMatchError.prototype);
+  }
+};
+async function isDirectoryExisting(directoryPath, dependencies) {
+  try {
+    await dependencies.fsAccess(directoryPath);
+    return Promise.resolve(true);
+  } catch (error) {
+    return Promise.resolve(false);
+  }
+}
+async function getFirstExistingParentPath(directoryPath, dependencies) {
+  let parentDirectoryPath = directoryPath;
+  let parentDirectoryFound = await isDirectoryExisting(parentDirectoryPath, dependencies);
+  while (!parentDirectoryFound) {
+    parentDirectoryPath = dependencies.pathNormalize(parentDirectoryPath + "/..");
+    parentDirectoryFound = await isDirectoryExisting(parentDirectoryPath, dependencies);
+  }
+  return parentDirectoryPath;
+}
+async function hasPowerShell3(dependencies) {
+  const major = parseInt(dependencies.release.split(".")[0], 10);
+  if (major <= 6) {
+    return false;
+  }
+  try {
+    await dependencies.cpExecFile("where", ["powershell"], { windowsHide: true });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+function checkDiskSpace(directoryPath, dependencies = {
+  platform,
+  release: release(),
+  fsAccess: access,
+  pathNormalize: normalize,
+  pathSep: sep,
+  cpExecFile: promisify(execFile)
+}) {
+  function mapOutput(stdout, filter, mapping, coefficient) {
+    const parsed = stdout.split("\n").map((line) => line.trim()).filter((line) => line.length !== 0).slice(1).map((line) => line.split(/\s+(?=[\d/])/));
+    const filtered = parsed.filter(filter);
+    if (filtered.length === 0) {
+      throw new NoMatchError();
+    }
+    const diskData = filtered[0];
+    return {
+      diskPath: diskData[mapping.diskPath],
+      free: parseInt(diskData[mapping.free], 10) * coefficient,
+      size: parseInt(diskData[mapping.size], 10) * coefficient
+    };
+  }
+  async function check(cmd, filter, mapping, coefficient = 1) {
+    const [file, ...args] = cmd;
+    if (file === void 0) {
+      return Promise.reject(new Error("cmd must contain at least one item"));
+    }
+    try {
+      const { stdout } = await dependencies.cpExecFile(file, args, { windowsHide: true });
+      return mapOutput(stdout, filter, mapping, coefficient);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+  async function checkWin32(directoryPath2) {
+    if (directoryPath2.charAt(1) !== ":") {
+      return Promise.reject(new InvalidPathError(`The following path is invalid (should be X:\\...): ${directoryPath2}`));
+    }
+    const powershellCmd = [
+      "powershell",
+      "Get-CimInstance -ClassName Win32_LogicalDisk | Select-Object Caption, FreeSpace, Size"
+    ];
+    const wmicCmd = [
+      "wmic",
+      "logicaldisk",
+      "get",
+      "size,freespace,caption"
+    ];
+    const cmd = await hasPowerShell3(dependencies) ? powershellCmd : wmicCmd;
+    return check(cmd, (driveData) => {
+      const driveLetter = driveData[0];
+      return directoryPath2.toUpperCase().startsWith(driveLetter.toUpperCase());
+    }, {
+      diskPath: 0,
+      free: 1,
+      size: 2
+    });
+  }
+  async function checkUnix(directoryPath2) {
+    if (!dependencies.pathNormalize(directoryPath2).startsWith(dependencies.pathSep)) {
+      return Promise.reject(new InvalidPathError(`The following path is invalid (should start by ${dependencies.pathSep}): ${directoryPath2}`));
+    }
+    const pathToCheck = await getFirstExistingParentPath(directoryPath2, dependencies);
+    return check(
+      [
+        "df",
+        "-Pk",
+        "--",
+        pathToCheck
+      ],
+      () => true,
+      // We should only get one line, so we did not need to filter
+      {
+        diskPath: 5,
+        free: 3,
+        size: 1
+      },
+      1024
+    );
+  }
+  if (dependencies.platform === "win32") {
+    return checkWin32(directoryPath);
+  }
+  return checkUnix(directoryPath);
+}
+
+// packages/core/src/gc/state.ts
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+var GC_STATE_SCHEMA_VERSION = "1.0";
+var DEFAULT_GC_STATE = {
+  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
+};
+async function readGCState(statePath) {
+  try {
+    const raw = await readFile(statePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_GC_STATE, ...parsed };
+  } catch {
+    return { ...DEFAULT_GC_STATE };
+  }
+}
+async function writeGCState(statePath, state) {
+  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);
+}
+async function patchGCState(statePath, patch) {
+  const current = await readGCState(statePath);
+  const updated = { ...current, ...patch };
+  await writeGCState(statePath, updated);
+  return updated;
+}
+
+// packages/core/src/gc/runner.ts
+var checkDiskSpace2 = checkDiskSpace;
+var DISK_THRESHOLDS = {
+  WATCH: 70,
+  WARN: 85,
+  URGENT: 90,
+  EMERGENCY: 95
+};
+function classifyDiskTier(pct) {
+  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";
+}
+function retentionMs(tier) {
+  switch (tier) {
+    case "emergency":
+      return 1 * 24 * 60 * 60 * 1e3;
+    // 1 day
+    case "urgent":
+      return 3 * 24 * 60 * 60 * 1e3;
+    // 3 days
+    case "warn":
+      return 7 * 24 * 60 * 60 * 1e3;
+    // 7 days
+    default:
+      return 30 * 24 * 60 * 60 * 1e3;
+  }
+}
+async function getPathBytes(targetPath) {
+  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(join2(targetPath, entry.name));
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+}
+async function idempotentRm(targetPath) {
+  try {
+    await rm(targetPath, { recursive: true, force: true });
+  } catch (err) {
+    const nodeErr = err;
+    if (nodeErr.code === "ENOENT") return;
+    throw err;
+  }
+}
+async function gatherPruneCandidates(maxAgeMs, projectsDir) {
+  const resolvedProjectsDir = projectsDir ?? join2(homedir(), ".claude", "projects");
+  const candidates = [];
+  const now = Date.now();
+  let projectSlugs;
+  try {
+    const entries = await readdir(resolvedProjectsDir, { withFileTypes: true });
+    projectSlugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return candidates;
+  }
+  for (const slug of projectSlugs) {
+    const slugDir = join2(resolvedProjectsDir, slug);
+    let slugEntries;
+    try {
+      slugEntries = await readdir(slugDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of slugEntries) {
+      const entryPath = join2(slugDir, entry.name);
+      if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        try {
+          const info = await stat(entryPath);
+          const ageMs = now - info.mtimeMs;
+          if (ageMs > maxAgeMs) {
+            candidates.push(entryPath);
+          }
+        } catch {
+        }
+      } else if (entry.isDirectory()) {
+        try {
+          const info = await stat(entryPath);
+          const ageMs = now - info.mtimeMs;
+          if (ageMs > maxAgeMs) {
+            candidates.push(entryPath);
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  return candidates;
+}
+async function runGC(opts = {}) {
+  const cleoDir = opts.cleoDir ?? join2(homedir(), ".cleo");
+  const statePath = join2(cleoDir, "gc-state.json");
+  const dryRun = opts.dryRun ?? false;
+  const projectsDir = opts.projectsDir;
+  const initialState = await readGCState(statePath);
+  const resumePaths = opts.resumeFrom ?? initialState.pendingPrune ?? [];
+  let diskUsedPct = 0;
+  try {
+    const { free, size } = await checkDiskSpace2(cleoDir);
+    diskUsedPct = size > 0 ? (size - free) / size * 100 : 0;
+  } catch {
+    diskUsedPct = 0;
+  }
+  const tier = classifyDiskTier(diskUsedPct);
+  const maxAgeMs = retentionMs(tier);
+  const candidatesFromScan = resumePaths.length > 0 ? resumePaths : await gatherPruneCandidates(maxAgeMs, projectsDir);
+  if (!dryRun && candidatesFromScan.length > 0) {
+    await patchGCState(statePath, { pendingPrune: candidatesFromScan });
+  }
+  const pruned = [];
+  let bytesFreed = 0;
+  const remaining = [...candidatesFromScan];
+  for (const candidatePath of candidatesFromScan) {
+    const bytes = await getPathBytes(candidatePath);
+    if (dryRun) {
+      pruned.push({ path: candidatePath, bytes });
+      bytesFreed += bytes;
+      continue;
+    }
+    try {
+      await idempotentRm(candidatePath);
+      pruned.push({ path: candidatePath, bytes });
+      bytesFreed += bytes;
+      const idx = remaining.indexOf(candidatePath);
+      if (idx !== -1) remaining.splice(idx, 1);
+      await patchGCState(statePath, {
+        pendingPrune: remaining.length > 0 ? remaining : null
+      });
+    } catch {
+    }
+  }
+  const escalationSet = tier === "warn" || tier === "urgent" || tier === "emergency";
+  let escalationReason = null;
+  if (escalationSet) {
+    escalationReason = `Disk at ${diskUsedPct.toFixed(1)}% (${tier.toUpperCase()}): ${pruned.length} paths pruned, ${bytesFreed} bytes freed`;
+  }
+  const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+  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
+  };
+}
+
+// packages/core/src/gc/daemon.ts
+var GC_CRON_EXPR = "0 3 * * *";
+var GC_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+async function bootstrapDaemon(cleoDir) {
+  const statePath = join3(cleoDir, "gc-state.json");
+  await patchGCState(statePath, {
+    daemonPid: process.pid,
+    daemonStartedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const state = await readGCState(statePath);
+  if (state.pendingPrune && state.pendingPrune.length > 0) {
+    try {
+      await runGC({ cleoDir, resumeFrom: state.pendingPrune });
+    } catch {
+    }
+  }
+  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 {
+    }
+  }
+  cron.schedule(
+    GC_CRON_EXPR,
+    async () => {
+      try {
+        await runGC({ cleoDir });
+      } catch {
+        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"
+    }
+  );
+}
+async function spawnGCDaemon(cleoDir) {
+  const logsDir = join3(cleoDir, "logs");
+  await mkdir2(logsDir, { recursive: true });
+  const logPath = join3(logsDir, "gc.log");
+  const errPath = join3(logsDir, "gc.err");
+  const outStream = createWriteStream(logPath, { flags: "a" });
+  const errStream = createWriteStream(errPath, { flags: "a" });
+  const daemonEntry = join3(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" }
+  });
+  child.unref();
+  const pid = child.pid ?? 0;
+  await patchGCState(join3(cleoDir, "gc-state.json"), {
+    daemonPid: pid,
+    daemonStartedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  return pid;
+}
+async function stopGCDaemon(cleoDir) {
+  const statePath = join3(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" };
+  }
+  try {
+    process.kill(pid, 0);
+  } catch {
+    await patchGCState(statePath, { daemonPid: null });
+    return {
+      stopped: false,
+      pid,
+      reason: `Daemon PID ${pid} is not running (stale state cleared)`
+    };
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    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}` };
+  }
+}
+async function getGCDaemonStatus(cleoDir) {
+  const state = await readGCState(join3(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
+  };
+}
+export {
+  bootstrapDaemon,
+  getGCDaemonStatus,
+  spawnGCDaemon,
+  stopGCDaemon
+};
+//# sourceMappingURL=daemon.js.map