@cleocode/core 2026.4.98 → 2026.4.99

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/index.d.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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gc/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/gc/runner.d.ts

@@ -0,0 +1,132 @@
+/**
+ * GC Runner — Core garbage collection logic for autonomous transcript cleanup.
+ *
+ * Performs disk-pressure-aware pruning of ephemeral transcript and temp files
+ * under `~/.claude/projects/` using the five-tier threshold model from T751.
+ *
+ * Retention policy (per ADR-047 and docs/specs/memory-architecture-spec.md §8):
+ * - `.temp/` files: 24h normal, 1h emergency
+ * - Transcript directories (agent-*.jsonl, tool-results/): 7d normal, 1d emergency
+ * - `.cleo/logs/`: 30d normal, 7d emergency
+ * - `.cleo/agent-outputs/*.md` (committed artifacts): NEVER auto-pruned
+ *
+ * Circuit breaker: if `ANTHROPIC_API_KEY` is absent AND no local model configured,
+ * skip extraction and only delete transcripts older than 30 days.
+ *
+ * @see ADR-047 — Autonomous GC and Disk Safety
+ * @see docs/specs/memory-architecture-spec.md §8
+ * @task T731
+ * @epic T726
+ */
+/**
+ * Disk usage percentage thresholds.
+ *
+ * Values mirror the five-tier model recommended by T751 research §3.2:
+ * - OK:        < 70% — routine cleanup by age policy only
+ * - WATCH:    70-85% — log + schedule next GC sooner
+ * - WARN:     85-90% — log + set escalation flag for next CLI invocation
+ * - URGENT:   90-95% — auto-prune oldest transcripts immediately
+ * - EMERGENCY: ≥ 95% — auto-prune all transcripts > 1d, pause new writes
+ */
+export declare const DISK_THRESHOLDS: {
+    readonly WATCH: 70;
+    readonly WARN: 85;
+    readonly URGENT: 90;
+    readonly EMERGENCY: 95;
+};
+/** Human-readable tier labels. */
+export type DiskTier = 'ok' | 'watch' | 'warn' | 'urgent' | 'emergency';
+/**
+ * Result of a single GC run.
+ */
+export interface GCResult {
+    /** Disk usage percentage at time of GC run (0–100). */
+    diskUsedPct: number;
+    /** Disk tier classification. */
+    threshold: DiskTier;
+    /** Files pruned during this run. */
+    pruned: Array<{
+        path: string;
+        bytes: number;
+    }>;
+    /** Total bytes freed. */
+    bytesFreed: number;
+    /** Whether escalation flag was set (disk ≥ WARN). */
+    escalationSet: boolean;
+    /** Human-readable escalation reason (set when escalationSet=true). */
+    escalationReason: string | null;
+    /** ISO-8601 timestamp of run completion. */
+    completedAt: string;
+}
+/**
+ * Options for a GC run.
+ */
+export interface GCRunOptions {
+    /**
+     * Absolute path to the `.cleo/` directory (used for state file and disk check).
+     * Defaults to `~/.cleo`.
+     */
+    cleoDir?: string;
+    /**
+     * Override the default `~/.claude/projects/` scan directory.
+     * Primarily used in tests to point at a temp directory.
+     */
+    projectsDir?: string;
+    /**
+     * Paths from a previous crashed run to resume deletion from.
+     * Written to `pendingPrune` in gc-state.json BEFORE starting deletion.
+     */
+    resumeFrom?: string[];
+    /**
+     * Dry-run mode: compute what would be pruned, but make zero filesystem changes.
+     */
+    dryRun?: boolean;
+}
+/**
+ * Classify a disk usage percentage into a tier.
+ *
+ * @param pct - Disk usage percentage (0–100)
+ * @returns DiskTier
+ */
+export declare function classifyDiskTier(pct: number): DiskTier;
+/**
+ * Compute retention threshold in milliseconds based on disk tier.
+ *
+ * Higher disk pressure → shorter retention → more aggressive pruning.
+ *
+ * @param tier - Current disk tier
+ * @returns Maximum age in milliseconds for transcript retention
+ */
+export declare function retentionMs(tier: DiskTier): number;
+/**
+ * Get the size of a path in bytes (file or directory recursively).
+ * Returns 0 if the path does not exist.
+ *
+ * @param targetPath - Path to measure
+ * @returns Size in bytes
+ */
+export declare function getPathBytes(targetPath: string): Promise<number>;
+/**
+ * Idempotently delete a path (file or directory).
+ *
+ * Silently ignores ENOENT — safe to call if path was already deleted.
+ * Uses `force: true` to suppress errors on missing paths.
+ *
+ * @param targetPath - Path to delete
+ */
+export declare function idempotentRm(targetPath: string): Promise<void>;
+/**
+ * Execute a GC run: check disk pressure, determine retention threshold,
+ * prune eligible transcript files, update gc-state.json.
+ *
+ * This function is idempotent and safe to call multiple times. Crash recovery
+ * is implemented via the `pendingPrune` field in gc-state.json:
+ * 1. Write paths to `pendingPrune` BEFORE starting deletion
+ * 2. Remove each path from `pendingPrune` AFTER successful deletion
+ * 3. Clear `pendingPrune` when the job completes
+ *
+ * @param opts - GC run options
+ * @returns GC run results
+ */
+export declare function runGC(opts?: GCRunOptions): Promise<GCResult>;
+//# sourceMappingURL=runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/gc/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA4BH;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;;;;;CAKlB,CAAC;AAEX,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,SAAS,EAAE,QAAQ,CAAC;IACpB,oCAAoC;IACpC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;IACvB,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAMtD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAWlD;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAetE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQpE;AA6ED;;;;;;;;;;;;GAYG;AACH,wBAAsB,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgGtE"}

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/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/sentient/daemon-entry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sentient Daemon Entry Point — spawned by `spawnSentientDaemon()`.
+ *
+ * Runs as a detached background process. Receives the project root as
+ * argv[2]. Does NOT import the CLI shim — only the sentient/ subtree.
+ *
+ * @see sentient/daemon.ts for spawn logic
+ * @task T946
+ */
+export {};
+//# sourceMappingURL=daemon-entry.d.ts.map

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

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

package/dist/sentient/daemon.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Sentient Daemon — Tier-1 autonomous loop sidecar.
+ *
+ * Runs as a detached Node.js process and executes `runTick()` every 5
+ * minutes. Mirrors the gc/daemon.ts sidecar pattern (ADR-047) and honours
+ * the worktree protocol — all state lives under the project's `.cleo/`.
+ *
+ * Scoped IN (this module):
+ *   - Tier-1 execution of unblocked tasks via `cleo orchestrate spawn`
+ *   - Kill-switch with re-check at every tick checkpoint
+ *   - Advisory locking via an OS-level lockfile (two daemons cannot coexist)
+ *   - Stuck detection + self-pause on stuck-rate threshold
+ *   - fs.watch-based fast kill propagation
+ *
+ * Scoped OUT (separate epics):
+ *   - Tier-2 proposal queue (`cleo propose` / status='proposed' generation)
+ *   - Tier-3 sandbox auto-merge (requires agent-in-container infra)
+ *   - Ed25519 signing of receipts (handled by Agent B2 llmtxt/identity wiring)
+ *
+ * @see ADR-054 — Sentient Loop Tier-1
+ * @task T946
+ */
+import { type FileHandle } from 'node:fs/promises';
+import { type SentientState } from './state.js';
+/** Relative subpath under a project root where sentient state lives. */
+export declare const SENTIENT_STATE_FILE: ".cleo/sentient-state.json";
+/** Relative subpath for the daemon lockfile. */
+export declare const SENTIENT_LOCK_FILE: ".cleo/sentient.lock";
+/** Cron expression: every 5 minutes (Tier-1 tick). */
+export declare const SENTIENT_CRON_EXPR = "*/5 * * * *";
+/**
+ * Cron expression: every 2 hours (Tier-2 propose tick).
+ *
+ * Separate from the Tier-1 cron to avoid proposal flooding.
+ * Only fires when `tier2Enabled = true` in sentient-state.json.
+ *
+ * @task T1008
+ */
+export declare const SENTIENT_PROPOSE_CRON_EXPR = "0 */2 * * *";
+/** Subdirectory for daemon logs. */
+export declare const SENTIENT_LOG_DIR: ".cleo/logs";
+/** Log filename (stdout). */
+export declare const SENTIENT_LOG: "sentient.log";
+/** Log filename (stderr). */
+export declare const SENTIENT_ERR: "sentient.err";
+/** Handle to an active advisory lock. */
+export interface LockHandle {
+    /** Absolute path to the lockfile. */
+    path: string;
+    /** Underlying file handle held exclusively by this process. */
+    handle: FileHandle;
+}
+/**
+ * Acquire an exclusive advisory lock on the sentient lockfile.
+ *
+ * Uses `fs.open` with `O_CREAT | O_EXCL` semantics — if the file already
+ * exists AND its recorded pid is alive, acquisition fails. Stale lockfiles
+ * (pid dead) are reclaimed automatically.
+ *
+ * @param lockPath - Absolute path to `.cleo/sentient.lock`
+ * @returns Lock handle, or null if lock is held by a live process
+ */
+export declare function acquireLock(lockPath: string): Promise<LockHandle | null>;
+/**
+ * Release an advisory lock acquired via {@link acquireLock}.
+ * Does NOT remove the lockfile — the pid inside is a useful diagnostic.
+ */
+export declare function releaseLock(lock: LockHandle): Promise<void>;
+/**
+ * Bootstrap the sentient daemon process.
+ *
+ * Steps:
+ *   1. Acquire advisory lock (fail fast if another daemon is running)
+ *   2. Persist our pid + startedAt to state.json
+ *   3. Watch state.json for killSwitch changes (fast propagation)
+ *   4. Register a SIGTERM handler for graceful shutdown
+ *   5. Schedule cron with noOverlap so long ticks don't stack
+ *
+ * @param projectRoot - Absolute path to the project (contains `.cleo/`)
+ */
+export declare function bootstrapDaemon(projectRoot: string): Promise<void>;
+/** Outcome of {@link spawnSentientDaemon}. */
+export interface SpawnDaemonResult {
+    /** PID of the spawned daemon. */
+    pid: number;
+    /** Absolute path to the .cleo/sentient-state.json file. */
+    statePath: string;
+    /** Absolute path to the log file. */
+    logPath: string;
+}
+/**
+ * Spawn the sentient daemon as a detached background process.
+ *
+ * All three T751 §2.2 requirements:
+ *   1. `detached: true` — process-group leader survives parent exit
+ *   2. File-based stdio — no TTY inheritance
+ *   3. `child.unref()` — parent CLI returns immediately
+ *
+ * @param projectRoot - Absolute path to the project root (contains `.cleo/`)
+ * @returns PID + log paths
+ */
+export declare function spawnSentientDaemon(projectRoot: string): Promise<SpawnDaemonResult>;
+/** Outcome of {@link stopSentientDaemon}. */
+export interface StopDaemonResult {
+    /** Whether the stop signal was delivered. */
+    stopped: boolean;
+    /** Last known pid; null if no pid was recorded. */
+    pid: number | null;
+    /** Human-readable reason. */
+    reason: string;
+}
+/**
+ * Stop the sentient daemon.
+ *
+ * Flips killSwitch=true FIRST (so an in-flight tick notices on its next
+ * checkpoint re-read), then sends SIGTERM. This gives the daemon a fast,
+ * graceful shutdown path even during a long-running spawn.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param reason - Optional reason stored on state file for diagnostics
+ * @returns Stop result
+ */
+export declare function stopSentientDaemon(projectRoot: string, reason?: string): Promise<StopDaemonResult>;
+/**
+ * Clear the kill switch so the cron schedule resumes executing ticks.
+ *
+ * Does NOT restart the daemon process — that is the caller's responsibility
+ * via `cleo sentient start` if the process itself exited.
+ *
+ * @param projectRoot - Absolute path to the project root
+ */
+export declare function resumeSentientDaemon(projectRoot: string): Promise<SentientState>;
+/** Status snapshot returned by {@link getSentientDaemonStatus}. */
+export interface SentientStatus {
+    /** Whether the pid on file is currently alive. */
+    running: boolean;
+    /** Recorded pid (null when never started or cleared on stop). */
+    pid: number | null;
+    /** ISO-8601 timestamp of last start. */
+    startedAt: string | null;
+    /** ISO-8601 timestamp of the last completed tick. */
+    lastTickAt: string | null;
+    /** Kill-switch state. */
+    killSwitch: boolean;
+    /** Reason supplied with the last kill. */
+    killSwitchReason: string | null;
+    /** Rolling stats. */
+    stats: SentientState['stats'];
+    /** Number of currently-stuck tasks. */
+    stuckCount: number;
+    /** Currently active task id (set mid-tick). */
+    activeTaskId: string | null;
+}
+/**
+ * Return a diagnostic snapshot for `cleo sentient status`.
+ *
+ * @param projectRoot - Absolute path to the project root
+ */
+export declare function getSentientDaemonStatus(projectRoot: string): Promise<SentientStatus>;
+//# sourceMappingURL=daemon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/sentient/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,kBAAkB,CAAC;AAK1E,OAAO,EAAyC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAOvF,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,EAAG,2BAAoC,CAAC;AAExE,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,EAAG,qBAA8B,CAAC;AAEjE,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AAExD,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,EAAG,YAAqB,CAAC;AAEtD,6BAA6B;AAC7B,eAAO,MAAM,YAAY,EAAG,cAAuB,CAAC;AAEpD,6BAA6B;AAC7B,eAAO,MAAM,YAAY,EAAG,cAAuB,CAAC;AAMpD,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAgD9E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2GxE;AAMD,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgCzF;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,SAAuB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA0C3B;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAMtF;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,wCAAwC;IACxC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qDAAqD;IACrD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yBAAyB;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,qBAAqB;IACrB,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAyB1F"}