@cleocode/core 2026.4.98 → 2026.4.100

package/dist/gc/runner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/gc/runner.ts", "../../../../node_modules/.pnpm/check-disk-space@3.4.0/node_modules/check-disk-space/dist/check-disk-space.mjs", "../../src/gc/state.ts"],
+  "sourcesContent": ["/**\n * GC Runner \u2014 Core garbage collection logic for autonomous transcript cleanup.\n *\n * Performs disk-pressure-aware pruning of ephemeral transcript and temp files\n * under `~/.claude/projects/` using the five-tier threshold model from T751.\n *\n * Retention policy (per ADR-047 and docs/specs/memory-architecture-spec.md \u00A78):\n * - `.temp/` files: 24h normal, 1h emergency\n * - Transcript directories (agent-*.jsonl, tool-results/): 7d normal, 1d emergency\n * - `.cleo/logs/`: 30d normal, 7d emergency\n * - `.cleo/agent-outputs/*.md` (committed artifacts): NEVER auto-pruned\n *\n * Circuit breaker: if `ANTHROPIC_API_KEY` is absent AND no local model configured,\n * skip extraction and only delete transcripts older than 30 days.\n *\n * @see ADR-047 \u2014 Autonomous GC and Disk Safety\n * @see docs/specs/memory-architecture-spec.md \u00A78\n * @task T731\n * @epic T726\n */\n\nimport { lstat, readdir, rm, stat } from 'node:fs/promises';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport checkDiskSpaceModule from 'check-disk-space';\n\n/**\n * Checks free + total bytes on the filesystem containing the given path.\n *\n * `check-disk-space@3.4.0` publishes its function as `export { x as default }`\n * in the .d.ts, which TS 6.0 strict resolution treats as a namespaced re-export\n * rather than a callable default. The runtime module itself exposes a callable;\n * we bridge the type gap by typing `checkDiskSpaceModule` as the callable\n * shape at the single import boundary.\n */\nconst checkDiskSpace = checkDiskSpaceModule as unknown as (path: string) => Promise<{\n  diskPath: string;\n  free: number;\n  size: number;\n}>;\n\nimport { patchGCState, readGCState } from './state.js';\n\n// ---------------------------------------------------------------------------\n// Threshold Tiers (from T751 \u00A73.2 and ADR-047)\n// ---------------------------------------------------------------------------\n\n/**\n * Disk usage percentage thresholds.\n *\n * Values mirror the five-tier model recommended by T751 research \u00A73.2:\n * - OK:        < 70% \u2014 routine cleanup by age policy only\n * - WATCH:    70-85% \u2014 log + schedule next GC sooner\n * - WARN:     85-90% \u2014 log + set escalation flag for next CLI invocation\n * - URGENT:   90-95% \u2014 auto-prune oldest transcripts immediately\n * - EMERGENCY: \u2265 95% \u2014 auto-prune all transcripts > 1d, pause new writes\n */\nexport const DISK_THRESHOLDS = {\n  WATCH: 70,\n  WARN: 85,\n  URGENT: 90,\n  EMERGENCY: 95,\n} as const;\n\n/** Human-readable tier labels. */\nexport type DiskTier = 'ok' | 'watch' | 'warn' | 'urgent' | 'emergency';\n\n/**\n * Result of a single GC run.\n */\nexport interface GCResult {\n  /** Disk usage percentage at time of GC run (0\u2013100). */\n  diskUsedPct: number;\n  /** Disk tier classification. */\n  threshold: DiskTier;\n  /** Files pruned during this run. */\n  pruned: Array<{ path: string; bytes: number }>;\n  /** Total bytes freed. */\n  bytesFreed: number;\n  /** Whether escalation flag was set (disk \u2265 WARN). */\n  escalationSet: boolean;\n  /** Human-readable escalation reason (set when escalationSet=true). */\n  escalationReason: string | null;\n  /** ISO-8601 timestamp of run completion. */\n  completedAt: string;\n}\n\n/**\n * Options for a GC run.\n */\nexport interface GCRunOptions {\n  /**\n   * Absolute path to the `.cleo/` directory (used for state file and disk check).\n   * Defaults to `~/.cleo`.\n   */\n  cleoDir?: string;\n  /**\n   * Override the default `~/.claude/projects/` scan directory.\n   * Primarily used in tests to point at a temp directory.\n   */\n  projectsDir?: string;\n  /**\n   * Paths from a previous crashed run to resume deletion from.\n   * Written to `pendingPrune` in gc-state.json BEFORE starting deletion.\n   */\n  resumeFrom?: string[];\n  /**\n   * Dry-run mode: compute what would be pruned, but make zero filesystem changes.\n   */\n  dryRun?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Classify a disk usage percentage into a tier.\n *\n * @param pct - Disk usage percentage (0\u2013100)\n * @returns DiskTier\n */\nexport function classifyDiskTier(pct: number): DiskTier {\n  if (pct >= DISK_THRESHOLDS.EMERGENCY) return 'emergency';\n  if (pct >= DISK_THRESHOLDS.URGENT) return 'urgent';\n  if (pct >= DISK_THRESHOLDS.WARN) return 'warn';\n  if (pct >= DISK_THRESHOLDS.WATCH) return 'watch';\n  return 'ok';\n}\n\n/**\n * Compute retention threshold in milliseconds based on disk tier.\n *\n * Higher disk pressure \u2192 shorter retention \u2192 more aggressive pruning.\n *\n * @param tier - Current disk tier\n * @returns Maximum age in milliseconds for transcript retention\n */\nexport function retentionMs(tier: DiskTier): number {\n  switch (tier) {\n    case 'emergency':\n      return 1 * 24 * 60 * 60 * 1000; // 1 day\n    case 'urgent':\n      return 3 * 24 * 60 * 60 * 1000; // 3 days\n    case 'warn':\n      return 7 * 24 * 60 * 60 * 1000; // 7 days\n    default:\n      return 30 * 24 * 60 * 60 * 1000; // 30 days (watch + ok)\n  }\n}\n\n/**\n * Get the size of a path in bytes (file or directory recursively).\n * Returns 0 if the path does not exist.\n *\n * @param targetPath - Path to measure\n * @returns Size in bytes\n */\nexport async function getPathBytes(targetPath: string): Promise<number> {\n  try {\n    const info = await lstat(targetPath);\n    if (info.isFile()) return info.size;\n    if (!info.isDirectory()) return 0;\n\n    const entries = await readdir(targetPath, { withFileTypes: true });\n    let total = 0;\n    for (const entry of entries) {\n      total += await getPathBytes(join(targetPath, entry.name));\n    }\n    return total;\n  } catch {\n    return 0;\n  }\n}\n\n/**\n * Idempotently delete a path (file or directory).\n *\n * Silently ignores ENOENT \u2014 safe to call if path was already deleted.\n * Uses `force: true` to suppress errors on missing paths.\n *\n * @param targetPath - Path to delete\n */\nexport async function idempotentRm(targetPath: string): Promise<void> {\n  try {\n    await rm(targetPath, { recursive: true, force: true });\n  } catch (err) {\n    const nodeErr = err as NodeJS.ErrnoException;\n    if (nodeErr.code === 'ENOENT') return; // already gone \u2014 idempotent\n    throw err;\n  }\n}\n\n/**\n * Gather transcript session directories under `~/.claude/projects/` that are\n * older than `maxAgeMs`.\n *\n * Only session UUID directories are candidates (not the root JSONL files \u2014\n * those are the main transcript). The `tool-results/` subdirectory within a\n * session directory is always included in the prune candidate once the session\n * is old enough.\n *\n * Committed artifact files (`.cleo/agent-outputs/*.md`) are NEVER included.\n *\n * @param maxAgeMs - Maximum age in ms; sessions older than this are candidates\n * @returns Array of absolute directory paths eligible for pruning\n */\nasync function gatherPruneCandidates(maxAgeMs: number, projectsDir?: string): Promise<string[]> {\n  const resolvedProjectsDir = projectsDir ?? join(homedir(), '.claude', 'projects');\n  const candidates: string[] = [];\n  const now = Date.now();\n\n  let projectSlugs: string[];\n  try {\n    const entries = await readdir(resolvedProjectsDir, { withFileTypes: true });\n    projectSlugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);\n  } catch {\n    // ~/.claude/projects/ doesn't exist yet\n    return candidates;\n  }\n\n  for (const slug of projectSlugs) {\n    const slugDir = join(resolvedProjectsDir, slug);\n\n    // Collect root JSONL files (HOT/WARM main session transcripts)\n    let slugEntries: import('fs').Dirent[];\n    try {\n      slugEntries = await readdir(slugDir, { withFileTypes: true });\n    } catch {\n      continue;\n    }\n\n    for (const entry of slugEntries) {\n      const entryPath = join(slugDir, entry.name);\n\n      if (entry.isFile() && entry.name.endsWith('.jsonl')) {\n        // Root-level session JSONL \u2014 check age\n        try {\n          const info = await stat(entryPath);\n          const ageMs = now - info.mtimeMs;\n          if (ageMs > maxAgeMs) {\n            candidates.push(entryPath);\n          }\n        } catch {\n          // File disappeared between readdir and stat \u2014 skip\n        }\n      } else if (entry.isDirectory()) {\n        // Session UUID directory \u2014 check mtime of the directory itself\n        try {\n          const info = await stat(entryPath);\n          const ageMs = now - info.mtimeMs;\n          if (ageMs > maxAgeMs) {\n            candidates.push(entryPath);\n          }\n        } catch {\n          // Directory disappeared \u2014 skip\n        }\n      }\n    }\n  }\n\n  return candidates;\n}\n\n// ---------------------------------------------------------------------------\n// Main GC Runner\n// ---------------------------------------------------------------------------\n\n/**\n * Execute a GC run: check disk pressure, determine retention threshold,\n * prune eligible transcript files, update gc-state.json.\n *\n * This function is idempotent and safe to call multiple times. Crash recovery\n * is implemented via the `pendingPrune` field in gc-state.json:\n * 1. Write paths to `pendingPrune` BEFORE starting deletion\n * 2. Remove each path from `pendingPrune` AFTER successful deletion\n * 3. Clear `pendingPrune` when the job completes\n *\n * @param opts - GC run options\n * @returns GC run results\n */\nexport async function runGC(opts: GCRunOptions = {}): Promise<GCResult> {\n  const cleoDir = opts.cleoDir ?? join(homedir(), '.cleo');\n  const statePath = join(cleoDir, 'gc-state.json');\n  const dryRun = opts.dryRun ?? false;\n  const projectsDir = opts.projectsDir;\n\n  // Step 1: Crash recovery \u2014 resume any pending prune from prior run\n  const initialState = await readGCState(statePath);\n  const resumePaths = opts.resumeFrom ?? initialState.pendingPrune ?? [];\n\n  // Step 2: Check disk space on the filesystem containing .cleo/\n  let diskUsedPct = 0;\n  try {\n    const { free, size } = await checkDiskSpace(cleoDir);\n    diskUsedPct = size > 0 ? ((size - free) / size) * 100 : 0;\n  } catch {\n    // Disk check failure is non-fatal; proceed with default tier\n    diskUsedPct = 0;\n  }\n\n  const tier = classifyDiskTier(diskUsedPct);\n  const maxAgeMs = retentionMs(tier);\n\n  // Step 3: Gather prune candidates\n  const candidatesFromScan =\n    resumePaths.length > 0 ? resumePaths : await gatherPruneCandidates(maxAgeMs, projectsDir);\n\n  // Step 4: Write pendingPrune to state BEFORE any deletion (crash-safe)\n  if (!dryRun && candidatesFromScan.length > 0) {\n    await patchGCState(statePath, { pendingPrune: candidatesFromScan });\n  }\n\n  // Step 5: Delete candidates and accumulate results\n  const pruned: GCResult['pruned'] = [];\n  let bytesFreed = 0;\n  const remaining = [...candidatesFromScan];\n\n  for (const candidatePath of candidatesFromScan) {\n    const bytes = await getPathBytes(candidatePath);\n\n    if (dryRun) {\n      // Dry run: record what would be deleted, make no changes\n      pruned.push({ path: candidatePath, bytes });\n      bytesFreed += bytes;\n      continue;\n    }\n\n    try {\n      await idempotentRm(candidatePath);\n      pruned.push({ path: candidatePath, bytes });\n      bytesFreed += bytes;\n      // Remove successfully-deleted path from the pending list\n      const idx = remaining.indexOf(candidatePath);\n      if (idx !== -1) remaining.splice(idx, 1);\n      // Persist updated pendingPrune after each deletion (crash-safe)\n      await patchGCState(statePath, {\n        pendingPrune: remaining.length > 0 ? remaining : null,\n      });\n    } catch {\n      // Deletion failure: leave in pendingPrune for next run\n    }\n  }\n\n  // Step 6: Determine escalation state\n  const escalationSet = tier === 'warn' || tier === 'urgent' || tier === 'emergency';\n  let escalationReason: string | null = null;\n  if (escalationSet) {\n    escalationReason = `Disk at ${diskUsedPct.toFixed(1)}% (${tier.toUpperCase()}): ${pruned.length} paths pruned, ${bytesFreed} bytes freed`;\n  }\n\n  const completedAt = new Date().toISOString();\n\n  // Step 7: Update gc-state.json with run results\n  if (!dryRun) {\n    await patchGCState(statePath, {\n      lastRunAt: completedAt,\n      lastRunResult: remaining.length === 0 ? 'success' : 'partial',\n      lastRunBytesFreed: bytesFreed,\n      pendingPrune: remaining.length > 0 ? remaining : null,\n      consecutiveFailures: remaining.length > 0 ? initialState.consecutiveFailures + 1 : 0,\n      diskThresholdBreached: diskUsedPct >= DISK_THRESHOLDS.WATCH,\n      lastDiskUsedPct: diskUsedPct,\n      escalationNeeded: escalationSet || initialState.escalationNeeded,\n      escalationReason: escalationReason ?? initialState.escalationReason,\n    });\n  }\n\n  return {\n    diskUsedPct,\n    threshold: tier,\n    pruned,\n    bytesFreed,\n    escalationSet,\n    escalationReason,\n    completedAt,\n  };\n}\n", "import { execFile } from 'node:child_process';\nimport { access } from 'node:fs/promises';\nimport { release } from 'node:os';\nimport { normalize, sep } from 'node:path';\nimport { platform } from 'node:process';\nimport { promisify } from 'node:util';\n\nclass InvalidPathError extends Error {\n    constructor(message) {\n        super(message);\n        this.name = 'InvalidPathError';\n        // Set the prototype explicitly.\n        Object.setPrototypeOf(this, InvalidPathError.prototype);\n    }\n}\n\nclass NoMatchError extends Error {\n    constructor(message) {\n        super(message);\n        this.name = 'NoMatchError';\n        // Set the prototype explicitly.\n        Object.setPrototypeOf(this, NoMatchError.prototype);\n    }\n}\n\n/**\n * Tells if directory exists\n *\n * @param directoryPath - The file/folder path\n * @param dependencies - Dependencies container\n */\nasync function isDirectoryExisting(directoryPath, dependencies) {\n    try {\n        await dependencies.fsAccess(directoryPath);\n        return Promise.resolve(true);\n    }\n    catch (error) {\n        return Promise.resolve(false);\n    }\n}\n\n/**\n * Get the first existing parent path\n *\n * @param directoryPath - The file/folder path from where we want to know disk space\n * @param dependencies - Dependencies container\n */\nasync function getFirstExistingParentPath(directoryPath, dependencies) {\n    let parentDirectoryPath = directoryPath;\n    let parentDirectoryFound = await isDirectoryExisting(parentDirectoryPath, dependencies);\n    while (!parentDirectoryFound) {\n        parentDirectoryPath = dependencies.pathNormalize(parentDirectoryPath + '/..');\n        parentDirectoryFound = await isDirectoryExisting(parentDirectoryPath, dependencies);\n    }\n    return parentDirectoryPath;\n}\n\n/**\n * Tell if PowerShell 3 is available based on Windows version\n *\n * Note: 6.* is Windows 7\n * Note: PowerShell 3 is natively available since Windows 8\n *\n * @param dependencies - Dependencies Injection Container\n */\nasync function hasPowerShell3(dependencies) {\n    const major = parseInt(dependencies.release.split('.')[0], 10);\n    if (major <= 6) {\n        return false;\n    }\n    try {\n        await dependencies.cpExecFile('where', ['powershell'], { windowsHide: true });\n        return true;\n    }\n    catch (error) {\n        return false;\n    }\n}\n\n/**\n * Check disk space\n *\n * @param directoryPath - The file/folder path from where we want to know disk space\n * @param dependencies - Dependencies container\n */\nfunction checkDiskSpace(directoryPath, dependencies = {\n    platform,\n    release: release(),\n    fsAccess: access,\n    pathNormalize: normalize,\n    pathSep: sep,\n    cpExecFile: promisify(execFile),\n}) {\n    // Note: This function contains other functions in order\n    //       to wrap them in a common context and make unit tests easier\n    /**\n     * Maps command output to a normalized object {diskPath, free, size}\n     *\n     * @param stdout - The command output\n     * @param filter - To filter drives (only used for win32)\n     * @param mapping - Map between column index and normalized column name\n     * @param coefficient - The size coefficient to get bytes instead of kB\n     */\n    function mapOutput(stdout, filter, mapping, coefficient) {\n        const parsed = stdout\n            .split('\\n') // Split lines\n            .map(line => line.trim()) // Trim all lines\n            .filter(line => line.length !== 0) // Remove empty lines\n            .slice(1) // Remove header\n            .map(line => line.split(/\\s+(?=[\\d/])/)); // Split on spaces to get columns\n        const filtered = parsed.filter(filter);\n        if (filtered.length === 0) {\n            throw new NoMatchError();\n        }\n        const diskData = filtered[0];\n        return {\n            diskPath: diskData[mapping.diskPath],\n            free: parseInt(diskData[mapping.free], 10) * coefficient,\n            size: parseInt(diskData[mapping.size], 10) * coefficient,\n        };\n    }\n    /**\n     * Run the command and do common things between win32 and unix\n     *\n     * @param cmd - The command to execute\n     * @param filter - To filter drives (only used for win32)\n     * @param mapping - Map between column index and normalized column name\n     * @param coefficient - The size coefficient to get bytes instead of kB\n     */\n    async function check(cmd, filter, mapping, coefficient = 1) {\n        const [file, ...args] = cmd;\n        /* istanbul ignore if */\n        if (file === undefined) {\n            return Promise.reject(new Error('cmd must contain at least one item'));\n        }\n        try {\n            const { stdout } = await dependencies.cpExecFile(file, args, { windowsHide: true });\n            return mapOutput(stdout, filter, mapping, coefficient);\n        }\n        catch (error) {\n            return Promise.reject(error);\n        }\n    }\n    /**\n     * Build the check call for win32\n     *\n     * @param directoryPath - The file/folder path from where we want to know disk space\n     */\n    async function checkWin32(directoryPath) {\n        if (directoryPath.charAt(1) !== ':') {\n            return Promise.reject(new InvalidPathError(`The following path is invalid (should be X:\\\\...): ${directoryPath}`));\n        }\n        const powershellCmd = [\n            'powershell',\n            'Get-CimInstance -ClassName Win32_LogicalDisk | Select-Object Caption, FreeSpace, Size',\n        ];\n        const wmicCmd = [\n            'wmic',\n            'logicaldisk',\n            'get',\n            'size,freespace,caption',\n        ];\n        const cmd = await hasPowerShell3(dependencies) ? powershellCmd : wmicCmd;\n        return check(cmd, driveData => {\n            // Only get the drive which match the path\n            const driveLetter = driveData[0];\n            return directoryPath.toUpperCase().startsWith(driveLetter.toUpperCase());\n        }, {\n            diskPath: 0,\n            free: 1,\n            size: 2,\n        });\n    }\n    /**\n     * Build the check call for unix\n     *\n     * @param directoryPath - The file/folder path from where we want to know disk space\n     */\n    async function checkUnix(directoryPath) {\n        if (!dependencies.pathNormalize(directoryPath).startsWith(dependencies.pathSep)) {\n            return Promise.reject(new InvalidPathError(`The following path is invalid (should start by ${dependencies.pathSep}): ${directoryPath}`));\n        }\n        const pathToCheck = await getFirstExistingParentPath(directoryPath, dependencies);\n        return check([\n            'df',\n            '-Pk',\n            '--',\n            pathToCheck,\n        ], () => true, // We should only get one line, so we did not need to filter\n        {\n            diskPath: 5,\n            free: 3,\n            size: 1,\n        }, 1024);\n    }\n    // Call the right check depending on the OS\n    if (dependencies.platform === 'win32') {\n        return checkWin32(directoryPath);\n    }\n    return checkUnix(directoryPath);\n}\n\nexport { InvalidPathError, NoMatchError, checkDiskSpace as default, getFirstExistingParentPath };\n", "/**\n * GC State \u2014 Persistent crash-recovery state for the autonomous GC daemon.\n *\n * Stored in `.cleo/gc-state.json` (plain JSON, not SQLite) to avoid\n * SQLite WAL conflicts between the long-running daemon process and the\n * main CLEO CLI process. Human-readable for debugging.\n *\n * The file is gitignored (see .gitignore \u00A7.cleo/ section) and created empty\n * by `cleo init`. It is NOT included in `cleo backup restore` scope because\n * it is ephemeral operational state \u2014 only the `daemonPid` and `lastRunAt`\n * fields survive between process restarts.\n *\n * @see ADR-047 \u2014 Autonomous GC and Disk Safety\n * @task T731\n * @epic T726\n */\n\nimport { mkdir, readFile, rename, writeFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\n\n/** Schema version for gc-state.json. Bump on breaking field changes. */\nexport const GC_STATE_SCHEMA_VERSION = '1.0' as const;\n\n/**\n * Persistent GC daemon state written to `.cleo/gc-state.json`.\n *\n * Design principles:\n * - `pendingPrune` enables idempotent crash recovery: populate BEFORE deletion,\n *   clear each entry AFTER successful deletion, clear entirely when job completes.\n * - `diskThresholdBreached` is a sticky flag: cleared only when disk drops\n *   below the WATCH tier (70%).\n * - `escalationNeeded` is set by the daemon when disk is in WARN/URGENT range;\n *   cleared by the CLI after displaying the escalation banner.\n */\nexport interface GCState {\n  /** JSON schema version for forward-compatibility checks. */\n  schemaVersion: typeof GC_STATE_SCHEMA_VERSION;\n  /** ISO-8601 timestamp of last COMPLETED GC run. null = never run. */\n  lastRunAt: string | null;\n  /** Outcome of the last GC run. */\n  lastRunResult: 'success' | 'partial' | 'failed' | null;\n  /** Bytes freed in the last completed GC run. */\n  lastRunBytesFreed: number;\n  /**\n   * Paths queued for deletion but not yet deleted.\n   * Written BEFORE starting deletion; cleared entry-by-entry on success.\n   * Enables idempotent crash recovery on daemon restart.\n   */\n  pendingPrune: string[] | null;\n  /** Number of consecutive GC failures. Triggers escalation banner after 3. */\n  consecutiveFailures: number;\n  /** Sticky flag: true when disk is \u2265 WATCH tier (70%). Cleared when disk < 70%. */\n  diskThresholdBreached: boolean;\n  /** Current disk usage percentage (0\u2013100) from the last GC run. */\n  lastDiskUsedPct: number | null;\n  /**\n   * Escalation banner flag. Set by daemon when disk is in WARN+ range.\n   * Cleared by CLI after displaying the banner to the user.\n   */\n  escalationNeeded: boolean;\n  /** Escalation reason shown in the CLI banner. */\n  escalationReason: string | null;\n  /** PID of the currently running daemon process. null = daemon not running. */\n  daemonPid: number | null;\n  /** ISO-8601 timestamp when the daemon was last started. */\n  daemonStartedAt: string | null;\n}\n\n/** Default (empty) GC state for fresh initialisation. */\nexport const DEFAULT_GC_STATE: GCState = {\n  schemaVersion: GC_STATE_SCHEMA_VERSION,\n  lastRunAt: null,\n  lastRunResult: null,\n  lastRunBytesFreed: 0,\n  pendingPrune: null,\n  consecutiveFailures: 0,\n  diskThresholdBreached: false,\n  lastDiskUsedPct: null,\n  escalationNeeded: false,\n  escalationReason: null,\n  daemonPid: null,\n  daemonStartedAt: null,\n};\n\n/**\n * Read the GC state from disk.\n *\n * Returns the default state if the file does not exist or is malformed.\n * Never throws \u2014 GC state file absence is not an error condition.\n *\n * @param statePath - Absolute path to gc-state.json\n * @returns Parsed GC state, merged with defaults for any missing fields\n */\nexport async function readGCState(statePath: string): Promise<GCState> {\n  try {\n    const raw = await readFile(statePath, 'utf-8');\n    const parsed = JSON.parse(raw) as Partial<GCState>;\n    // Merge with defaults so new fields added in future schema versions\n    // don't cause undefined access on old state files.\n    return { ...DEFAULT_GC_STATE, ...parsed };\n  } catch {\n    // ENOENT (file not yet created) or JSON parse error \u2192 use defaults\n    return { ...DEFAULT_GC_STATE };\n  }\n}\n\n/**\n * Write the GC state to disk atomically via tmp-then-rename.\n *\n * Atomic write prevents partial reads if the daemon crashes mid-write.\n * Idempotent: safe to call multiple times.\n *\n * @param statePath - Absolute path to gc-state.json\n * @param state - GC state to persist\n */\nexport async function writeGCState(statePath: string, state: GCState): Promise<void> {\n  const dir = dirname(statePath);\n  await mkdir(dir, { recursive: true });\n\n  const tmpPath = join(dir, `.gc-state-${process.pid}.tmp`);\n  const json = JSON.stringify(state, null, 2);\n\n  await writeFile(tmpPath, json, 'utf-8');\n  await rename(tmpPath, statePath);\n}\n\n/**\n * Patch a subset of fields in the GC state file.\n *\n * Convenience wrapper: reads current state, merges patch, writes back.\n *\n * @param statePath - Absolute path to gc-state.json\n * @param patch - Partial state to merge over the existing state\n */\nexport async function patchGCState(statePath: string, patch: Partial<GCState>): Promise<GCState> {\n  const current = await readGCState(statePath);\n  const updated: GCState = { ...current, ...patch };\n  await writeGCState(statePath, updated);\n  return updated;\n}\n"],
+  "mappings": "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",
+  "names": ["join", "directoryPath", "checkDiskSpace", "join"]
+}

package/dist/gc/state.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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
+ */
+/** Schema version for gc-state.json. Bump on breaking field changes. */
+export declare const GC_STATE_SCHEMA_VERSION: "1.0";
+/**
+ * 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 declare const DEFAULT_GC_STATE: GCState;
+/**
+ * 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 declare function readGCState(statePath: string): Promise<GCState>;
+/**
+ * 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 declare function writeGCState(statePath: string, state: GCState): Promise<void>;
+/**
+ * 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 declare function patchGCState(statePath: string, patch: Partial<GCState>): Promise<GCState>;
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/gc/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,EAAG,KAAc,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO;IACtB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,uBAAuB,CAAC;IAC9C,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kCAAkC;IAClC,aAAa,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;IACvD,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC9B,6EAA6E;IAC7E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,qBAAqB,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2DAA2D;IAC3D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,EAAE,OAa9B,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWrE;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CASnF;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAK/F"}

package/dist/gc/state.js

@@ -0,0 +1,49 @@
+// 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;
+}
+export {
+  DEFAULT_GC_STATE,
+  GC_STATE_SCHEMA_VERSION,
+  patchGCState,
+  readGCState,
+  writeGCState
+};
+//# sourceMappingURL=state.js.map

package/dist/gc/state.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/gc/state.ts"],
+  "sourcesContent": ["/**\n * GC State \u2014 Persistent crash-recovery state for the autonomous GC daemon.\n *\n * Stored in `.cleo/gc-state.json` (plain JSON, not SQLite) to avoid\n * SQLite WAL conflicts between the long-running daemon process and the\n * main CLEO CLI process. Human-readable for debugging.\n *\n * The file is gitignored (see .gitignore \u00A7.cleo/ section) and created empty\n * by `cleo init`. It is NOT included in `cleo backup restore` scope because\n * it is ephemeral operational state \u2014 only the `daemonPid` and `lastRunAt`\n * fields survive between process restarts.\n *\n * @see ADR-047 \u2014 Autonomous GC and Disk Safety\n * @task T731\n * @epic T726\n */\n\nimport { mkdir, readFile, rename, writeFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\n\n/** Schema version for gc-state.json. Bump on breaking field changes. */\nexport const GC_STATE_SCHEMA_VERSION = '1.0' as const;\n\n/**\n * Persistent GC daemon state written to `.cleo/gc-state.json`.\n *\n * Design principles:\n * - `pendingPrune` enables idempotent crash recovery: populate BEFORE deletion,\n *   clear each entry AFTER successful deletion, clear entirely when job completes.\n * - `diskThresholdBreached` is a sticky flag: cleared only when disk drops\n *   below the WATCH tier (70%).\n * - `escalationNeeded` is set by the daemon when disk is in WARN/URGENT range;\n *   cleared by the CLI after displaying the escalation banner.\n */\nexport interface GCState {\n  /** JSON schema version for forward-compatibility checks. */\n  schemaVersion: typeof GC_STATE_SCHEMA_VERSION;\n  /** ISO-8601 timestamp of last COMPLETED GC run. null = never run. */\n  lastRunAt: string | null;\n  /** Outcome of the last GC run. */\n  lastRunResult: 'success' | 'partial' | 'failed' | null;\n  /** Bytes freed in the last completed GC run. */\n  lastRunBytesFreed: number;\n  /**\n   * Paths queued for deletion but not yet deleted.\n   * Written BEFORE starting deletion; cleared entry-by-entry on success.\n   * Enables idempotent crash recovery on daemon restart.\n   */\n  pendingPrune: string[] | null;\n  /** Number of consecutive GC failures. Triggers escalation banner after 3. */\n  consecutiveFailures: number;\n  /** Sticky flag: true when disk is \u2265 WATCH tier (70%). Cleared when disk < 70%. */\n  diskThresholdBreached: boolean;\n  /** Current disk usage percentage (0\u2013100) from the last GC run. */\n  lastDiskUsedPct: number | null;\n  /**\n   * Escalation banner flag. Set by daemon when disk is in WARN+ range.\n   * Cleared by CLI after displaying the banner to the user.\n   */\n  escalationNeeded: boolean;\n  /** Escalation reason shown in the CLI banner. */\n  escalationReason: string | null;\n  /** PID of the currently running daemon process. null = daemon not running. */\n  daemonPid: number | null;\n  /** ISO-8601 timestamp when the daemon was last started. */\n  daemonStartedAt: string | null;\n}\n\n/** Default (empty) GC state for fresh initialisation. */\nexport const DEFAULT_GC_STATE: GCState = {\n  schemaVersion: GC_STATE_SCHEMA_VERSION,\n  lastRunAt: null,\n  lastRunResult: null,\n  lastRunBytesFreed: 0,\n  pendingPrune: null,\n  consecutiveFailures: 0,\n  diskThresholdBreached: false,\n  lastDiskUsedPct: null,\n  escalationNeeded: false,\n  escalationReason: null,\n  daemonPid: null,\n  daemonStartedAt: null,\n};\n\n/**\n * Read the GC state from disk.\n *\n * Returns the default state if the file does not exist or is malformed.\n * Never throws \u2014 GC state file absence is not an error condition.\n *\n * @param statePath - Absolute path to gc-state.json\n * @returns Parsed GC state, merged with defaults for any missing fields\n */\nexport async function readGCState(statePath: string): Promise<GCState> {\n  try {\n    const raw = await readFile(statePath, 'utf-8');\n    const parsed = JSON.parse(raw) as Partial<GCState>;\n    // Merge with defaults so new fields added in future schema versions\n    // don't cause undefined access on old state files.\n    return { ...DEFAULT_GC_STATE, ...parsed };\n  } catch {\n    // ENOENT (file not yet created) or JSON parse error \u2192 use defaults\n    return { ...DEFAULT_GC_STATE };\n  }\n}\n\n/**\n * Write the GC state to disk atomically via tmp-then-rename.\n *\n * Atomic write prevents partial reads if the daemon crashes mid-write.\n * Idempotent: safe to call multiple times.\n *\n * @param statePath - Absolute path to gc-state.json\n * @param state - GC state to persist\n */\nexport async function writeGCState(statePath: string, state: GCState): Promise<void> {\n  const dir = dirname(statePath);\n  await mkdir(dir, { recursive: true });\n\n  const tmpPath = join(dir, `.gc-state-${process.pid}.tmp`);\n  const json = JSON.stringify(state, null, 2);\n\n  await writeFile(tmpPath, json, 'utf-8');\n  await rename(tmpPath, statePath);\n}\n\n/**\n * Patch a subset of fields in the GC state file.\n *\n * Convenience wrapper: reads current state, merges patch, writes back.\n *\n * @param statePath - Absolute path to gc-state.json\n * @param patch - Partial state to merge over the existing state\n */\nexport async function patchGCState(statePath: string, patch: Partial<GCState>): Promise<GCState> {\n  const current = await readGCState(statePath);\n  const updated: GCState = { ...current, ...patch };\n  await writeGCState(statePath, updated);\n  return updated;\n}\n"],
+  "mappings": ";AAiBA,SAAS,OAAO,UAAU,QAAQ,iBAAiB;AACnD,SAAS,SAAS,YAAY;AAGvB,IAAM,0BAA0B;AAgDhC,IAAM,mBAA4B;AAAA,EACvC,eAAe;AAAA,EACf,WAAW;AAAA,EACX,eAAe;AAAA,EACf,mBAAmB;AAAA,EACnB,cAAc;AAAA,EACd,qBAAqB;AAAA,EACrB,uBAAuB;AAAA,EACvB,iBAAiB;AAAA,EACjB,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,iBAAiB;AACnB;AAWA,eAAsB,YAAY,WAAqC;AACrE,MAAI;AACF,UAAM,MAAM,MAAM,SAAS,WAAW,OAAO;AAC7C,UAAM,SAAS,KAAK,MAAM,GAAG;AAG7B,WAAO,EAAE,GAAG,kBAAkB,GAAG,OAAO;AAAA,EAC1C,QAAQ;AAEN,WAAO,EAAE,GAAG,iBAAiB;AAAA,EAC/B;AACF;AAWA,eAAsB,aAAa,WAAmB,OAA+B;AACnF,QAAM,MAAM,QAAQ,SAAS;AAC7B,QAAM,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;AAEpC,QAAM,UAAU,KAAK,KAAK,aAAa,QAAQ,GAAG,MAAM;AACxD,QAAM,OAAO,KAAK,UAAU,OAAO,MAAM,CAAC;AAE1C,QAAM,UAAU,SAAS,MAAM,OAAO;AACtC,QAAM,OAAO,SAAS,SAAS;AACjC;AAUA,eAAsB,aAAa,WAAmB,OAA2C;AAC/F,QAAM,UAAU,MAAM,YAAY,SAAS;AAC3C,QAAM,UAAmB,EAAE,GAAG,SAAS,GAAG,MAAM;AAChD,QAAM,aAAa,WAAW,OAAO;AACrC,SAAO;AACT;",
+  "names": []
+}

package/dist/gc/transcript.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Transcript Scanner — Inventory and age-classification of Claude session transcripts.
+ *
+ * Implements the hot/warm/cold three-tier model from memory-architecture-spec.md §6:
+ * - HOT  (0–24h):  Full JSONL retained; agents can re-read
+ * - WARM (1–7d):   Pending extraction; scheduled at session end
+ * - COLD (>7d):    brain.db entries only; raw JSONL deleted (tombstone in brain_obs)
+ *
+ * Storage layout scanned (§6.2):
+ * ```
+ * ~/.claude/projects/
+ *   <project-slug>/
+ *     <session-uuid>.jsonl              ← root-level main session transcript
+ *     <session-uuid>/                   ← session UUID directory
+ *       subagents/
+ *         agent-<agentId>.jsonl         ← subagent transcript
+ *         agent-<agentId>.meta.json
+ *       tool-results/
+ *         <toolUseId>.json
+ * ```
+ *
+ * @see docs/specs/memory-architecture-spec.md §6.1–6.2
+ * @task T728
+ * @epic T726
+ */
+/** Hot/warm/cold lifecycle tier for a transcript session. */
+export type TranscriptTier = 'hot' | 'warm' | 'cold';
+/**
+ * Metadata for a single session transcript discovered on disk.
+ */
+export interface SessionInfo {
+    /** Absolute path to the root session JSONL file. */
+    jsonlPath: string;
+    /** Project slug (directory name under `~/.claude/projects/`). */
+    projectSlug: string;
+    /** Session UUID extracted from the JSONL filename. */
+    sessionId: string;
+    /** Last modified time of the JSONL file (ms since epoch). */
+    mtimeMs: number;
+    /** Age of the session in milliseconds. */
+    ageMs: number;
+    /** Lifecycle tier. */
+    tier: TranscriptTier;
+    /** Size in bytes of the root JSONL file. */
+    bytes: number;
+    /**
+     * Absolute path to the session UUID directory (if it exists).
+     * Contains `subagents/` and `tool-results/` subdirs.
+     */
+    sessionDir: string | null;
+    /** Size in bytes of the session UUID directory (including subagents). */
+    sessionDirBytes: number;
+}
+/**
+ * Aggregate scan result: session inventory with tier-based grouping.
+ */
+export interface TranscriptScanResult {
+    /** Total number of sessions found. */
+    totalSessions: number;
+    /** HOT tier sessions (< 24h). */
+    hot: SessionInfo[];
+    /** WARM tier sessions (24h–7d). */
+    warm: SessionInfo[];
+    /** Total size of all discovered transcripts in bytes. */
+    totalBytes: number;
+    /** Absolute path to `~/.claude/projects/`. */
+    projectsDir: string;
+}
+/**
+ * Result of a transcript prune operation.
+ */
+export interface TranscriptPruneResult {
+    /** Number of sessions pruned. */
+    pruned: number;
+    /** Bytes freed. */
+    bytesFreed: number;
+    /** Paths that were deleted (or would be deleted in dry-run). */
+    deletedPaths: string[];
+    /** Whether this was a dry-run (no filesystem mutations). */
+    dryRun: boolean;
+}
+/**
+ * Classify a session age into a transcript tier.
+ *
+ * @param ageMs - Session age in milliseconds
+ * @returns Lifecycle tier
+ */
+export declare function classifyTranscriptTier(ageMs: number): TranscriptTier;
+/**
+ * Scan `~/.claude/projects/` and return a structured inventory of all
+ * session transcripts, classified by hot/warm/cold tier.
+ *
+ * Does not modify any files. Safe to call at any time.
+ *
+ * @param projectsDir - Override the default `~/.claude/projects/` path (for testing)
+ * @returns Transcript scan result with tier-classified session list
+ */
+export declare function scanTranscripts(projectsDir?: string): Promise<TranscriptScanResult>;
+/**
+ * Prune session transcripts older than `olderThanMs` milliseconds.
+ *
+ * Dry-run by default: pass `confirm: true` to perform actual deletion.
+ *
+ * Circuit breakers (from memory-architecture-spec.md §6.4):
+ * - If `ANTHROPIC_API_KEY` is absent, only delete sessions older than 30d
+ *   (raw preservation fallback — skip extraction).
+ *
+ * @param opts - Prune options
+ * @param opts.olderThanMs - Delete sessions older than this many milliseconds
+ * @param opts.confirm - If true, perform actual deletion; dry-run if false
+ * @param opts.projectsDir - Override `~/.claude/projects/` (for testing)
+ * @returns Prune result with count, bytes freed, and deleted paths
+ */
+export declare function pruneTranscripts(opts: {
+    olderThanMs: number;
+    confirm: boolean;
+    projectsDir?: string;
+}): Promise<TranscriptPruneResult>;
+/**
+ * Parse a human-readable duration string into milliseconds.
+ *
+ * Supported formats: `7d`, `24h`, `30m`, `1d`, `14d`, `168h`, etc.
+ * Used by `cleo transcript prune --older-than <duration>`.
+ *
+ * @param duration - Duration string (e.g. `"7d"`, `"24h"`, `"30m"`)
+ * @returns Duration in milliseconds
+ * @throws Error if the format is not recognized
+ */
+export declare function parseDurationMs(duration: string): number;
+//# sourceMappingURL=transcript.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/gc/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAqBH,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,IAAI,EAAE,cAAc,CAAC;IACrB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,GAAG,EAAE,WAAW,EAAE,CAAC;IACnB,mCAAmC;IACnC,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,4DAA4D;IAC5D,MAAM,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAIpE;AAmBD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAsFzF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAmGjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAcxD"}

package/dist/gc/transcript.js

@@ -0,0 +1,209 @@
+// packages/core/src/gc/transcript.ts
+import { lstat as lstat2, readdir as readdir2, stat as stat2 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// packages/core/src/gc/runner.ts
+import { lstat, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+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(join(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;
+  }
+}
+
+// packages/core/src/gc/transcript.ts
+var HOT_MAX_MS = 24 * 60 * 60 * 1e3;
+var WARM_MAX_MS = 7 * 24 * 60 * 60 * 1e3;
+function classifyTranscriptTier(ageMs) {
+  if (ageMs < HOT_MAX_MS) return "hot";
+  if (ageMs < WARM_MAX_MS) return "warm";
+  return "cold";
+}
+function parseSessionId(filename) {
+  return filename.replace(/\.jsonl$/, "");
+}
+async function scanTranscripts(projectsDir) {
+  const resolvedProjectsDir = projectsDir ?? join2(homedir(), ".claude", "projects");
+  const now = Date.now();
+  const hot = [];
+  const warm = [];
+  let totalBytes = 0;
+  let slugs;
+  try {
+    const entries = await readdir2(resolvedProjectsDir, { withFileTypes: true });
+    slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return { totalSessions: 0, hot, warm, totalBytes, projectsDir: resolvedProjectsDir };
+  }
+  for (const slug of slugs) {
+    const slugDir = join2(resolvedProjectsDir, slug);
+    let entries;
+    try {
+      entries = await readdir2(slugDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+      const jsonlPath = join2(slugDir, entry.name);
+      const sessionId = parseSessionId(entry.name);
+      let fileInfo;
+      try {
+        fileInfo = await stat2(jsonlPath);
+      } catch {
+        continue;
+      }
+      const mtimeMs = fileInfo.mtimeMs;
+      const ageMs = now - mtimeMs;
+      const tier = classifyTranscriptTier(ageMs);
+      const bytes = fileInfo.size;
+      const candidateSessionDir = join2(slugDir, sessionId);
+      let sessionDir = null;
+      let sessionDirBytes = 0;
+      try {
+        const dirInfo = await lstat2(candidateSessionDir);
+        if (dirInfo.isDirectory()) {
+          sessionDir = candidateSessionDir;
+          sessionDirBytes = await getPathBytes(candidateSessionDir);
+        }
+      } catch {
+      }
+      const info = {
+        jsonlPath,
+        projectSlug: slug,
+        sessionId,
+        mtimeMs,
+        ageMs,
+        tier,
+        bytes,
+        sessionDir,
+        sessionDirBytes
+      };
+      totalBytes += bytes + sessionDirBytes;
+      if (tier === "hot") {
+        hot.push(info);
+      } else if (tier === "warm") {
+        warm.push(info);
+      }
+    }
+  }
+  const totalSessions = hot.length + warm.length;
+  return { totalSessions, hot, warm, totalBytes, projectsDir: resolvedProjectsDir };
+}
+async function pruneTranscripts(opts) {
+  const { olderThanMs, confirm, projectsDir } = opts;
+  const dryRun = !confirm;
+  const hasApiKey = Boolean(process.env["ANTHROPIC_API_KEY"]);
+  const effectiveMaxAgeMs = hasApiKey ? olderThanMs : Math.max(olderThanMs, 30 * 24 * 60 * 60 * 1e3);
+  const now = Date.now();
+  const deletedPaths = [];
+  let bytesFreed = 0;
+  let pruned = 0;
+  const resolvedProjectsDir = projectsDir ?? join2(homedir(), ".claude", "projects");
+  let slugs;
+  try {
+    const entries = await readdir2(resolvedProjectsDir, { withFileTypes: true });
+    slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return { pruned: 0, bytesFreed: 0, deletedPaths: [], dryRun };
+  }
+  for (const slug of slugs) {
+    const slugDir = join2(resolvedProjectsDir, slug);
+    let entries;
+    try {
+      entries = await readdir2(slugDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+      const jsonlPath = join2(slugDir, entry.name);
+      let fileInfo;
+      try {
+        fileInfo = await stat2(jsonlPath);
+      } catch {
+        continue;
+      }
+      const ageMs = now - fileInfo.mtimeMs;
+      if (ageMs <= effectiveMaxAgeMs) continue;
+      const sessionId = parseSessionId(entry.name);
+      const sessionDir = join2(slugDir, sessionId);
+      const jsonlBytes = fileInfo.size;
+      let sessionDirBytes = 0;
+      try {
+        const dirInfo = await lstat2(sessionDir);
+        if (dirInfo.isDirectory()) {
+          sessionDirBytes = await getPathBytes(sessionDir);
+        }
+      } catch {
+      }
+      if (dryRun) {
+        deletedPaths.push(jsonlPath);
+        if (sessionDirBytes > 0) deletedPaths.push(sessionDir);
+        bytesFreed += jsonlBytes + sessionDirBytes;
+        pruned++;
+        continue;
+      }
+      try {
+        await idempotentRm(jsonlPath);
+        deletedPaths.push(jsonlPath);
+        bytesFreed += jsonlBytes;
+        pruned++;
+      } catch {
+        continue;
+      }
+      try {
+        const dirInfo = await lstat2(sessionDir);
+        if (dirInfo.isDirectory()) {
+          await idempotentRm(sessionDir);
+          deletedPaths.push(sessionDir);
+          bytesFreed += sessionDirBytes;
+        }
+      } catch {
+      }
+    }
+  }
+  return { pruned, bytesFreed, deletedPaths, dryRun };
+}
+function parseDurationMs(duration) {
+  const match = /^(\d+(\.\d+)?)(d|h|m|s)$/.exec(duration.trim());
+  if (!match?.[1] || !match[3]) {
+    throw new Error(`Invalid duration format: "${duration}". Use format like 7d, 24h, 30m, 60s.`);
+  }
+  const value = parseFloat(match[1]);
+  const unit = match[3];
+  const multipliers = {
+    d: 24 * 60 * 60 * 1e3,
+    h: 60 * 60 * 1e3,
+    m: 60 * 1e3,
+    s: 1e3
+  };
+  return value * (multipliers[unit] ?? 1e3);
+}
+export {
+  classifyTranscriptTier,
+  parseDurationMs,
+  pruneTranscripts,
+  scanTranscripts
+};
+//# sourceMappingURL=transcript.js.map