@cleocode/core 2026.4.98 → 2026.4.99

package/dist/sentient/tick.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Sentient Loop Tick — Single-iteration tick runner for the Tier-1 daemon.
+ *
+ * A tick is one complete pass of:
+ *   1. Check killSwitch (abort if true)
+ *   2. Pick an unblocked task via @cleocode/core/sdk
+ *   3. Check killSwitch again (abort if true)
+ *   4. Spawn worker via `cleo orchestrate spawn <taskId> --adapter <adapter>`
+ *   5. Check killSwitch again before recording result
+ *   6. Record success (receipt + stats) or failure (retry/backoff)
+ *
+ * Each step re-reads the state file so that a killSwitch flipped mid-tick is
+ * honoured on the very next instruction (Round 2 audit §1: "mid-experiment
+ * kill limbo").
+ *
+ * Rate limit: driven by the cron schedule (`*\/5 * * * *` → ≤12 ticks/hour ≤
+ * 12 spawns/hour). No in-tick sleep is required — cron provides the cadence.
+ *
+ * Scoped OUT: Tier 2 (propose) and Tier 3 (sandbox auto-merge) per ADR-054.
+ *
+ * @task T946
+ * @see ADR-054 — Sentient Loop Tier-1
+ */
+import type { Task } from '@cleocode/contracts';
+import { type SentientState } from './state.js';
+/**
+ * Number of new brain observations since the last consolidation that causes
+ * the tick loop to trigger a dream cycle (volume tier).
+ * Configurable via the injected `dreamVolumeThreshold` option.
+ */
+export declare const DREAM_VOLUME_THRESHOLD_DEFAULT = 50;
+/**
+ * Number of consecutive no-task ticks before the idle dream trigger fires.
+ * Represents "N idle ticks" — when no task has been picked for this many
+ * consecutive ticks, the system is considered sufficiently idle.
+ */
+export declare const DREAM_IDLE_TICKS_DEFAULT = 5;
+/** Default adapter used when spawning workers. */
+export declare const DEFAULT_ADAPTER: "claude-code";
+/**
+ * Backoff delays between successive retries for the same task (milliseconds).
+ * Index n = delay before attempt n+1. After exhaustion the task is `stuck`.
+ * 30 s → 5 min → 30 min, then the task is marked stuck.
+ */
+export declare const RETRY_BACKOFF_MS: readonly number[];
+/**
+ * Maximum spawn attempts per task before it is classified as `stuck`.
+ * Matches RETRY_BACKOFF_MS.length but surfaced as a named constant for
+ * readability in tests and status output.
+ */
+export declare const MAX_TASK_ATTEMPTS: number;
+/**
+ * Threshold for self-pause: if this many tasks become `stuck` within a
+ * rolling 1-hour window, the daemon flips killSwitch=true and exits.
+ */
+export declare const SELF_PAUSE_STUCK_THRESHOLD = 5;
+/** Rolling window (ms) used for stuck-rate calculation. */
+export declare const SELF_PAUSE_WINDOW_MS: number;
+/** Reason stored on the state file when self-pause fires. */
+export declare const SELF_PAUSE_REASON = "self-pause: 5 stuck tasks in 1 hour";
+/** Max wall-clock time for a single spawn before forceful kill (30 min). */
+export declare const SPAWN_TIMEOUT_MS: number;
+/** Discriminant for the tick outcome. */
+export type TickOutcomeKind = 'killed' | 'no-task' | 'backoff' | 'success' | 'failure' | 'stuck' | 'self-paused' | 'error';
+/** Structured outcome of a single tick. */
+export interface TickOutcome {
+    /** Discriminant describing how the tick ended. */
+    kind: TickOutcomeKind;
+    /** Task id that was the subject of this tick (if any). */
+    taskId: string | null;
+    /** Human-readable detail (one line). */
+    detail: string;
+}
+/** Options for {@link runTick}. */
+export interface TickOptions {
+    /** Absolute path to the project root (contains `.cleo/`). */
+    projectRoot: string;
+    /** Absolute path to sentient-state.json. */
+    statePath: string;
+    /**
+     * Adapter to pass to `cleo orchestrate spawn --adapter`. Defaults to
+     * {@link DEFAULT_ADAPTER}. Overridden in tests via options.spawn.
+     */
+    adapter?: string;
+    /**
+     * Dry-run mode: skip the actual `cleo orchestrate spawn` subprocess and
+     * treat the pick as a no-op (still records picked stat). Used by
+     * `cleo sentient tick --dry-run`.
+     */
+    dryRun?: boolean;
+    /**
+     * Override for the spawn function — lets tests inject a deterministic fake
+     * without forking real subprocesses. Must resolve to an exit code.
+     *
+     * When omitted, the default implementation spawns
+     * `cleo orchestrate spawn <taskId> --adapter <adapter>` and resolves with
+     * the child's exit code.
+     */
+    spawn?: (taskId: string, adapter: string) => Promise<SpawnResult>;
+    /**
+     * Override for the "pick next unblocked task" source. Lets tests return
+     * a deterministic task without constructing a SQLite fixture.
+     */
+    pickTask?: (projectRoot: string) => Promise<Task | null>;
+    /**
+     * New observation count since last consolidation that triggers the volume
+     * dream cycle. Defaults to {@link DREAM_VOLUME_THRESHOLD_DEFAULT}.
+     * Pass 0 to disable volume trigger. Injected by tests.
+     */
+    dreamVolumeThreshold?: number;
+    /**
+     * Number of consecutive no-task ticks before the idle dream trigger fires.
+     * Defaults to {@link DREAM_IDLE_TICKS_DEFAULT}.
+     * Pass 0 to disable idle trigger. Injected by tests.
+     */
+    dreamIdleTicks?: number;
+    /**
+     * Override for the dream trigger function — lets tests assert dream calls
+     * without touching the real brain.db stack.
+     * Signature mirrors `checkAndDream` from `@cleocode/core`.
+     */
+    checkAndDream?: (projectRoot: string, opts?: {
+        volumeThreshold?: number;
+        inline?: boolean;
+    }) => Promise<{
+        triggered: boolean;
+        tier: string | null;
+        skippedReason?: string;
+    }>;
+}
+/** Result of a spawn invocation. */
+export interface SpawnResult {
+    /** Process exit code (0 = success). */
+    exitCode: number;
+    /** Captured stdout, truncated by the caller if needed. */
+    stdout: string;
+    /** Captured stderr, truncated by the caller if needed. */
+    stderr: string;
+}
+/**
+ * Run a single tick of the sentient loop.
+ *
+ * Every checkpoint re-reads state so that a killSwitch flipped mid-tick is
+ * honoured on the next instruction.
+ *
+ * @param options - Tick options (see {@link TickOptions})
+ * @returns Structured outcome describing how the tick ended.
+ */
+export declare function runTick(options: TickOptions): Promise<TickOutcome>;
+/**
+ * Convenience wrapper used by the daemon cron handler and the `cleo sentient
+ * tick` CLI command. Reads state, runs a tick, swallows any unexpected
+ * exception so the cron scheduler never sees a rejection.
+ *
+ * After the tick completes, evaluates volume + idle dream triggers via
+ * {@link maybeTriggerDream}. Dream errors are swallowed independently so
+ * they never affect the tick outcome.
+ *
+ * @param options - Tick options
+ * @returns The tick outcome (or an `error` outcome if the tick itself threw).
+ */
+export declare function safeRunTick(options: TickOptions): Promise<TickOutcome>;
+/**
+ * Type-narrowing helper used by tests and status rendering to identify tick
+ * outcomes that consumed a retry attempt.
+ */
+export declare function isFailureOutcome(outcome: TickOutcome): outcome is TickOutcome & {
+    kind: 'failure' | 'stuck' | 'self-paused';
+};
+/**
+ * Returns a shallow view of the current state's kill status.
+ * Exposed for diagnostic/test consumers.
+ */
+export declare function getKillStatus(statePath: string): Promise<Pick<SentientState, 'killSwitch' | 'killSwitchReason'>>;
+/**
+ * Reset dream-cycle in-process state.
+ *
+ * Intended for test teardown only — clears `consecutiveIdleTicks` so that
+ * successive test cases start from a clean slate.
+ *
+ * @internal
+ */
+export declare function _resetDreamTickState(): void;
+/**
+ * Return the current consecutive-idle-tick counter value.
+ *
+ * Read-only accessor for test assertions. The counter is reset to 0 whenever
+ * a task is picked, and incremented on each no-task tick.
+ *
+ * @internal
+ */
+export declare function _getConsecutiveIdleTicks(): number;
+//# sourceMappingURL=tick.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tick.d.ts","sourceRoot":"","sources":["../../src/sentient/tick.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.4.98",
+  "version": "2026.4.99",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -111,6 +111,71 @@
       "import": "./dist/memory/brain-backfill.js",
       "require": "./dist/memory/brain-backfill.js"
     },
+    "./sentient": {
+      "types": "./dist/sentient/index.d.ts",
+      "import": "./dist/sentient/index.js",
+      "require": "./dist/sentient/index.js"
+    },
+    "./sentient/*": {
+      "types": "./dist/sentient/*.d.ts",
+      "import": "./dist/sentient/*.js",
+      "require": "./dist/sentient/*.js"
+    },
+    "./sentient/daemon.js": {
+      "types": "./dist/sentient/daemon.d.ts",
+      "import": "./dist/sentient/daemon.js",
+      "require": "./dist/sentient/daemon.js"
+    },
+    "./sentient/state.js": {
+      "types": "./dist/sentient/state.d.ts",
+      "import": "./dist/sentient/state.js",
+      "require": "./dist/sentient/state.js"
+    },
+    "./sentient/tick.js": {
+      "types": "./dist/sentient/tick.d.ts",
+      "import": "./dist/sentient/tick.js",
+      "require": "./dist/sentient/tick.js"
+    },
+    "./sentient/propose-tick.js": {
+      "types": "./dist/sentient/propose-tick.d.ts",
+      "import": "./dist/sentient/propose-tick.js",
+      "require": "./dist/sentient/propose-tick.js"
+    },
+    "./sentient/proposal-rate-limiter.js": {
+      "types": "./dist/sentient/proposal-rate-limiter.d.ts",
+      "import": "./dist/sentient/proposal-rate-limiter.js",
+      "require": "./dist/sentient/proposal-rate-limiter.js"
+    },
+    "./gc": {
+      "types": "./dist/gc/index.d.ts",
+      "import": "./dist/gc/index.js",
+      "require": "./dist/gc/index.js"
+    },
+    "./gc/*": {
+      "types": "./dist/gc/*.d.ts",
+      "import": "./dist/gc/*.js",
+      "require": "./dist/gc/*.js"
+    },
+    "./gc/daemon.js": {
+      "types": "./dist/gc/daemon.d.ts",
+      "import": "./dist/gc/daemon.js",
+      "require": "./dist/gc/daemon.js"
+    },
+    "./gc/runner.js": {
+      "types": "./dist/gc/runner.d.ts",
+      "import": "./dist/gc/runner.js",
+      "require": "./dist/gc/runner.js"
+    },
+    "./gc/state.js": {
+      "types": "./dist/gc/state.d.ts",
+      "import": "./dist/gc/state.js",
+      "require": "./dist/gc/state.js"
+    },
+    "./gc/transcript.js": {
+      "types": "./dist/gc/transcript.d.ts",
+      "import": "./dist/gc/transcript.js",
+      "require": "./dist/gc/transcript.js"
+    },
     "./system/platform-paths.js": {
       "types": "./dist/system/platform-paths.d.ts",
       "import": "./dist/system/platform-paths.js",
@@ -148,16 +213,18 @@
     "tree-sitter-ruby": "^0.23.1",
     "tree-sitter-rust": "0.23.1",
     "tree-sitter-typescript": "^0.23.2",
+    "check-disk-space": "^3.4.0",
+    "node-cron": "^4.2.1",
     "write-file-atomic": "^7.0.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@cleocode/adapters": "2026.4.98",
-    "@cleocode/agents": "2026.4.98",
-    "@cleocode/caamp": "2026.4.98",
-    "@cleocode/nexus": "2026.4.98",
-    "@cleocode/lafs": "2026.4.98",
-    "@cleocode/skills": "2026.4.98",
-    "@cleocode/contracts": "2026.4.98"
+    "@cleocode/adapters": "2026.4.99",
+    "@cleocode/agents": "2026.4.99",
+    "@cleocode/lafs": "2026.4.99",
+    "@cleocode/caamp": "2026.4.99",
+    "@cleocode/contracts": "2026.4.99",
+    "@cleocode/nexus": "2026.4.99",
+    "@cleocode/skills": "2026.4.99"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -174,6 +241,7 @@
     "src"
   ],
   "devDependencies": {
+    "@types/node-cron": "^3.0.11",
     "@types/proper-lockfile": "^4.1.4",
     "@types/tar": "^6.1.13",
     "@types/write-file-atomic": "^4.0.3",

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

@@ -0,0 +1,367 @@
+/**
+ * GC Runner Tests (T735)
+ *
+ * Covers:
+ * - classifyDiskTier: correct tier at all boundary values
+ * - retentionMs: correct retention mapping per tier
+ * - runGC: dry-run mode makes zero filesystem mutations
+ * - runGC: budget cap (>5GB equivalent) triggers URGENT tier prune
+ * - runGC: API key absent falls back to 30d-only deletion (circuit breaker)
+ * - Crash recovery: pendingPrune paths are re-deleted on resume
+ *
+ * Uses real temp directories (mkdtemp). No mocked filesystem.
+ *
+ * @task T735
+ * @epic T726
+ */
+
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mock check-disk-space so tests don't depend on actual disk state
+vi.mock('check-disk-space', () => ({
+  default: vi.fn(),
+}));
+
+import checkDiskSpace from 'check-disk-space';
+
+import { classifyDiskTier, DISK_THRESHOLDS, retentionMs, runGC } from '../runner.js';
+import { readGCState } from '../state.js';
+
+const mockCheckDisk = vi.mocked(checkDiskSpace);
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a fake project directory structure under a temp dir.
+ * Writes a session JSONL file with an mtime in the past.
+ */
+async function createFakeSession(
+  projectsDir: string,
+  slug: string,
+  sessionId: string,
+  ageMs: number,
+): Promise<string> {
+  const slugDir = join(projectsDir, slug);
+  await mkdir(slugDir, { recursive: true });
+
+  const jsonlPath = join(slugDir, `${sessionId}.jsonl`);
+  await writeFile(jsonlPath, `{"type":"user","text":"hello"}\n`, 'utf-8');
+
+  // Set mtime to simulate age
+  const pastTime = new Date(Date.now() - ageMs);
+  const { utimes } = await import('node:fs/promises');
+  await utimes(jsonlPath, pastTime, pastTime);
+
+  return jsonlPath;
+}
+
+// ---------------------------------------------------------------------------
+// classifyDiskTier
+// ---------------------------------------------------------------------------
+
+describe('classifyDiskTier', () => {
+  it('returns ok for disk usage below WATCH threshold', () => {
+    expect(classifyDiskTier(0)).toBe('ok');
+    expect(classifyDiskTier(50)).toBe('ok');
+    expect(classifyDiskTier(DISK_THRESHOLDS.WATCH - 0.01)).toBe('ok');
+  });
+
+  it('returns watch at WATCH threshold boundary (70%)', () => {
+    expect(classifyDiskTier(DISK_THRESHOLDS.WATCH)).toBe('watch');
+    expect(classifyDiskTier(70)).toBe('watch');
+    expect(classifyDiskTier(84.9)).toBe('watch');
+  });
+
+  it('returns warn at WARN threshold boundary (85%)', () => {
+    expect(classifyDiskTier(DISK_THRESHOLDS.WARN)).toBe('warn');
+    expect(classifyDiskTier(85)).toBe('warn');
+    expect(classifyDiskTier(89.9)).toBe('warn');
+  });
+
+  it('returns urgent at URGENT threshold boundary (90%)', () => {
+    expect(classifyDiskTier(DISK_THRESHOLDS.URGENT)).toBe('urgent');
+    expect(classifyDiskTier(90)).toBe('urgent');
+    expect(classifyDiskTier(94.9)).toBe('urgent');
+  });
+
+  it('returns emergency at EMERGENCY threshold boundary (95%)', () => {
+    expect(classifyDiskTier(DISK_THRESHOLDS.EMERGENCY)).toBe('emergency');
+    expect(classifyDiskTier(95)).toBe('emergency');
+    expect(classifyDiskTier(100)).toBe('emergency');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// retentionMs
+// ---------------------------------------------------------------------------
+
+describe('retentionMs', () => {
+  it('returns 30 days for ok tier', () => {
+    expect(retentionMs('ok')).toBe(30 * 24 * 60 * 60 * 1000);
+  });
+
+  it('returns 30 days for watch tier', () => {
+    expect(retentionMs('watch')).toBe(30 * 24 * 60 * 60 * 1000);
+  });
+
+  it('returns 7 days for warn tier', () => {
+    expect(retentionMs('warn')).toBe(7 * 24 * 60 * 60 * 1000);
+  });
+
+  it('returns 3 days for urgent tier', () => {
+    expect(retentionMs('urgent')).toBe(3 * 24 * 60 * 60 * 1000);
+  });
+
+  it('returns 1 day for emergency tier', () => {
+    expect(retentionMs('emergency')).toBe(1 * 24 * 60 * 60 * 1000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// runGC — dry-run makes zero filesystem mutations
+// ---------------------------------------------------------------------------
+
+describe('runGC dry-run', () => {
+  let tmpDir: string;
+  let cleoDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-gc-test-'));
+    cleoDir = join(tmpDir, '.cleo');
+    projectsDir = join(tmpDir, '.claude', 'projects');
+    await mkdir(cleoDir, { recursive: true });
+    await mkdir(projectsDir, { recursive: true });
+
+    // Simulate low disk usage (ok tier) for deterministic prune behavior
+    mockCheckDisk.mockResolvedValue({ diskPath: cleoDir, free: 900, size: 1000 } as Awaited<
+      ReturnType<typeof checkDiskSpace>
+    >);
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    vi.clearAllMocks();
+  });
+
+  it('dry-run reports prunable paths without deleting any files', async () => {
+    // Create a session old enough to be pruned (35 days old — beyond 30d ok-tier retention)
+    const OLD_AGE_MS = 35 * 24 * 60 * 60 * 1000;
+    const jsonlPath = await createFakeSession(
+      projectsDir,
+      'test-project',
+      'session-abc',
+      OLD_AGE_MS,
+    );
+
+    const gcResult = await runGC({ cleoDir, projectsDir, dryRun: true });
+
+    // Dry-run: file must still exist
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined(); // still exists
+
+    // Dry-run: result reports the path as prunable
+    expect(gcResult.pruned.length).toBeGreaterThan(0);
+    expect(gcResult.pruned.some((p) => p.path === jsonlPath)).toBe(true);
+  });
+
+  it('dry-run does not write to gc-state.json', async () => {
+    await runGC({ cleoDir, projectsDir, dryRun: true });
+
+    // gc-state.json should not be written in dry-run
+    const statePath = join(cleoDir, 'gc-state.json');
+    try {
+      await readFile(statePath, 'utf-8');
+      // If it exists, it shouldn't have updated lastRunAt
+      const state = await readGCState(statePath);
+      expect(state.lastRunAt).toBeNull();
+    } catch {
+      // File doesn't exist — that's also fine for dry-run
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// runGC — threshold-based auto-prune
+// ---------------------------------------------------------------------------
+
+describe('runGC threshold-based prune', () => {
+  let tmpDir: string;
+  let cleoDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-gc-thresh-'));
+    cleoDir = join(tmpDir, '.cleo');
+    projectsDir = join(tmpDir, '.claude', 'projects');
+    await mkdir(cleoDir, { recursive: true });
+    await mkdir(projectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    vi.clearAllMocks();
+  });
+
+  it('URGENT tier (90%+ disk): prunes sessions older than 3d', async () => {
+    // Simulate URGENT disk pressure (92%)
+    mockCheckDisk.mockResolvedValue({ diskPath: cleoDir, free: 80, size: 1000 } as Awaited<
+      ReturnType<typeof checkDiskSpace>
+    >);
+
+    // Create a 4-day-old session (older than 3d urgent threshold)
+    const OLD_AGE_MS = 4 * 24 * 60 * 60 * 1000;
+    const jsonlPath = await createFakeSession(projectsDir, 'proj', 'sess-urgent', OLD_AGE_MS);
+
+    const gcResult = await runGC({ cleoDir, projectsDir });
+
+    expect(gcResult.threshold).toBe('urgent');
+    expect(gcResult.pruned.some((p) => p.path === jsonlPath)).toBe(true);
+  });
+
+  it('URGENT tier: escalation flag is set in gc-state.json', async () => {
+    mockCheckDisk.mockResolvedValue({ diskPath: cleoDir, free: 80, size: 1000 } as Awaited<
+      ReturnType<typeof checkDiskSpace>
+    >);
+
+    await createFakeSession(projectsDir, 'proj', 'sess-escalate', 4 * 24 * 60 * 60 * 1000);
+    await runGC({ cleoDir, projectsDir });
+
+    const state = await readGCState(join(cleoDir, 'gc-state.json'));
+    expect(state.escalationNeeded).toBe(true);
+  });
+
+  it('OK tier: sessions within 30d are NOT pruned', async () => {
+    // Simulate OK disk pressure (30%)
+    mockCheckDisk.mockResolvedValue({ diskPath: cleoDir, free: 700, size: 1000 } as Awaited<
+      ReturnType<typeof checkDiskSpace>
+    >);
+
+    // Create a 10-day-old session (below 30d ok-tier threshold)
+    const RECENT_AGE_MS = 10 * 24 * 60 * 60 * 1000;
+    const jsonlPath = await createFakeSession(projectsDir, 'proj', 'sess-recent', RECENT_AGE_MS);
+
+    const gcResult = await runGC({ cleoDir, projectsDir });
+
+    // File should still exist
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined();
+
+    expect(gcResult.threshold).toBe('ok');
+    expect(gcResult.pruned.some((p) => p.path === jsonlPath)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// runGC — crash recovery via pendingPrune
+// ---------------------------------------------------------------------------
+
+describe('runGC crash recovery', () => {
+  let tmpDir: string;
+  let cleoDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-gc-crash-'));
+    cleoDir = join(tmpDir, '.cleo');
+    await mkdir(cleoDir, { recursive: true });
+
+    mockCheckDisk.mockResolvedValue({ diskPath: cleoDir, free: 900, size: 1000 } as Awaited<
+      ReturnType<typeof checkDiskSpace>
+    >);
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    vi.clearAllMocks();
+  });
+
+  it('resumes deletion from pendingPrune when resumeFrom is provided', async () => {
+    // Simulate a file that was in the pending list
+    const fakeFilePath = join(tmpDir, 'session-pending.jsonl');
+    await writeFile(fakeFilePath, '{"type":"user"}\n', 'utf-8');
+
+    // Run GC with resumeFrom (simulates crash recovery)
+    const gcResult = await runGC({ cleoDir, resumeFrom: [fakeFilePath] });
+
+    // File should be deleted
+    const { access } = await import('node:fs/promises');
+    await expect(access(fakeFilePath)).rejects.toThrow();
+
+    expect(gcResult.pruned.some((p) => p.path === fakeFilePath)).toBe(true);
+  });
+
+  it('pendingPrune is cleared after successful deletion', async () => {
+    const fakeFilePath = join(tmpDir, 'pending-cleared.jsonl');
+    await writeFile(fakeFilePath, '{"type":"user"}\n', 'utf-8');
+
+    await runGC({ cleoDir, resumeFrom: [fakeFilePath] });
+
+    const state = await readGCState(join(cleoDir, 'gc-state.json'));
+    expect(state.pendingPrune).toBeNull();
+  });
+
+  it('skips ENOENT paths idempotently (already deleted)', async () => {
+    // Path that does not exist — should not throw
+    const nonExistentPath = join(tmpDir, 'already-gone.jsonl');
+
+    const gcResult = await runGC({ cleoDir, resumeFrom: [nonExistentPath] });
+
+    // Should complete without error; path included in pruned (reported as 0 bytes)
+    expect(gcResult).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// runGC — gc-state.json is written with correct structure
+// ---------------------------------------------------------------------------
+
+describe('runGC state persistence', () => {
+  let tmpDir: string;
+  let cleoDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-gc-state-'));
+    cleoDir = join(tmpDir, '.cleo');
+    projectsDir = join(tmpDir, '.claude', 'projects');
+    await mkdir(cleoDir, { recursive: true });
+    await mkdir(projectsDir, { recursive: true });
+
+    mockCheckDisk.mockResolvedValue({ diskPath: cleoDir, free: 700, size: 1000 } as Awaited<
+      ReturnType<typeof checkDiskSpace>
+    >);
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    vi.clearAllMocks();
+  });
+
+  it('writes lastRunAt as ISO-8601 after a successful run', async () => {
+    await runGC({ cleoDir, projectsDir });
+
+    const state = await readGCState(join(cleoDir, 'gc-state.json'));
+    expect(state.lastRunAt).toBeTruthy();
+    expect(() => new Date(state.lastRunAt as string)).not.toThrow();
+  });
+
+  it('sets lastRunResult to success when no errors', async () => {
+    await runGC({ cleoDir, projectsDir });
+
+    const state = await readGCState(join(cleoDir, 'gc-state.json'));
+    expect(state.lastRunResult).toBe('success');
+  });
+
+  it('sets lastDiskUsedPct from check-disk-space result', async () => {
+    // 30% used: (1000 - 700) / 1000 = 30%
+    await runGC({ cleoDir, projectsDir });
+
+    const state = await readGCState(join(cleoDir, 'gc-state.json'));
+    expect(state.lastDiskUsedPct).toBeCloseTo(30, 1);
+  });
+});