@wjarka/cezarion 0.10.0-pr30.54

package/dist/runs/retention.d.ts

@@ -0,0 +1,60 @@
+import type { RunRecord } from './store.ts';
+/** A run is reclaimable when it is finished, still has a materialized worktree
+ *  directory, and has not already been reclaimed. */
+export declare function isReclaimable(run: RunRecord): boolean;
+/**
+ * Given every run and the keep-count `keep`, return the ids of the finished
+ * worktrees whose *directory* should be reclaimed: keep the `keep`
+ * most-recently-finished reclaimable worktrees, reclaim the rest.
+ *
+ * `keep === 0` means "unlimited — never auto-reclaim" and returns `[]`.
+ * Pure: no I/O, no mutation of the input.
+ */
+export declare function selectReclaimableWorktrees(runs: readonly RunRecord[], keep: number): string[];
+/** The slice of the runs store the enforcer needs. Kept structural so the
+ *  enforcer stays easy to test and never imports the concrete store. */
+export interface RetentionStore {
+    listRuns(): RunRecord[];
+    updateRun(id: string, patch: {
+        worktreeReclaimedAt?: string;
+    }): unknown;
+}
+/** The slice of the store the re-materializer needs. */
+export interface RematerializeStore {
+    getRun(id: string): RunRecord | undefined;
+    updateRun(id: string, patch: {
+        worktreeReclaimedAt?: string;
+    }): unknown;
+}
+/**
+ * If retention (#483) reclaimed this run's worktree — branch kept, directory
+ * gone, `worktreeReclaimedAt` stamped — re-materialize the directory (via the
+ * idempotent `createWorktree`, which reattaches the surviving `cez/<id8>`
+ * branch) and CLEAR the stamp. Called on the resume/continue path so a resumed
+ * run regains its isolated tree and becomes eligible for retention again;
+ * without it the run would keep a directory on disk while staying invisible to
+ * the enforcer forever (a leak). Returns true when it re-materialized.
+ * Best-effort: never throws (the caller falls back to the repo root).
+ */
+export declare function rematerializeReclaimedWorktree(repoRoot: string, store: RematerializeStore, runId: string): Promise<boolean>;
+/**
+ * Enforce the retention budget: reclaim the *directory* of every over-limit
+ * finished worktree (branch kept via `removeWorktree` without the branch arg),
+ * stamping `worktreeReclaimedAt` on each run actually reclaimed. Returns the
+ * reclaimed run ids (for logging/SSE).
+ *
+ * Never throws (helper discipline). `removeWorktree` is best-effort and does not
+ * report failure, so a run is stamped only once its directory is confirmed gone
+ * — a locked/permission failure leaves the stamp unset so the next pass retries.
+ * Idempotent under races: `removeWorktree` is `--force` + `prune` and a repeated
+ * stamp is harmless.
+ */
+export interface ReclaimOptions {
+    /** Timestamp source for the stamp — injectable for deterministic tests. */
+    now?: () => string;
+    /** Directory reclaimer — defaults to the real `removeWorktree` (branch kept).
+     *  Injectable so tests can exercise the "removal failed" branch without brittle
+     *  filesystem-permission tricks. */
+    remove?: (repoRoot: string, worktreePath: string) => Promise<void>;
+}
+export declare function reclaimWorktrees(repoRoot: string, store: RetentionStore, keep: number, opts?: ReclaimOptions): Promise<string[]>;

package/dist/runs/retention.js

@@ -0,0 +1,86 @@
+// Count-based worktree retention (#483). A busy cockpit leaves one full repo
+// checkout per finished task under `.ai/cezar/worktrees/<runId>`; nothing bounds
+// the total, so disk saturates. This module decides *which* finished worktrees
+// to reclaim (directory only — the `cez/<id8>` branch is kept, so the work stays
+// recoverable) and the thin I/O enforcer that performs the reclaim. The selector
+// is pure and unit-testable; the enforcer never throws (helper discipline).
+import { existsSync } from 'node:fs';
+import { createWorktree, removeWorktree } from '../git-worktree.js';
+/** The "finished" status set — mirrors `RunStore.archiveFinished`. A run at the
+ *  `review` gate is deliberately excluded: it still needs its worktree to render
+ *  the diff and open a draft PR, so reclaiming it would break the gate. */
+const FINISHED = new Set(['done', 'failed', 'cancelled']);
+/** Recency key for retention ordering: when a run finished, falling back to when
+ *  it was created (a finished run should always have `finishedAt`, but old
+ *  records may not). Lexicographic compare is correct for ISO-8601 timestamps. */
+function recencyKey(run) {
+    return run.finishedAt ?? run.createdAt;
+}
+/** A run is reclaimable when it is finished, still has a materialized worktree
+ *  directory, and has not already been reclaimed. */
+export function isReclaimable(run) {
+    return FINISHED.has(run.status) && !!run.worktreePath && !run.worktreeReclaimedAt;
+}
+/**
+ * Given every run and the keep-count `keep`, return the ids of the finished
+ * worktrees whose *directory* should be reclaimed: keep the `keep`
+ * most-recently-finished reclaimable worktrees, reclaim the rest.
+ *
+ * `keep === 0` means "unlimited — never auto-reclaim" and returns `[]`.
+ * Pure: no I/O, no mutation of the input.
+ */
+export function selectReclaimableWorktrees(runs, keep) {
+    if (!Number.isFinite(keep) || keep <= 0)
+        return [];
+    const reclaimable = runs
+        .filter(isReclaimable)
+        .sort((a, b) => (recencyKey(a) < recencyKey(b) ? 1 : recencyKey(a) > recencyKey(b) ? -1 : 0));
+    return reclaimable.slice(keep).map((r) => r.id);
+}
+/**
+ * If retention (#483) reclaimed this run's worktree — branch kept, directory
+ * gone, `worktreeReclaimedAt` stamped — re-materialize the directory (via the
+ * idempotent `createWorktree`, which reattaches the surviving `cez/<id8>`
+ * branch) and CLEAR the stamp. Called on the resume/continue path so a resumed
+ * run regains its isolated tree and becomes eligible for retention again;
+ * without it the run would keep a directory on disk while staying invisible to
+ * the enforcer forever (a leak). Returns true when it re-materialized.
+ * Best-effort: never throws (the caller falls back to the repo root).
+ */
+export async function rematerializeReclaimedWorktree(repoRoot, store, runId) {
+    const run = store.getRun(runId);
+    if (!run?.worktreePath || !run.worktreeReclaimedAt || existsSync(run.worktreePath))
+        return false;
+    try {
+        await createWorktree(repoRoot, runId, run.baseBranch ?? 'HEAD');
+        store.updateRun(runId, { worktreeReclaimedAt: undefined });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function reclaimWorktrees(repoRoot, store, keep, opts = {}) {
+    const now = opts.now ?? (() => new Date().toISOString());
+    const remove = opts.remove ?? ((root, path) => removeWorktree(root, path)); // branch kept
+    const runs = store.listRuns();
+    const byId = new Map(runs.map((r) => [r.id, r]));
+    const reclaimed = [];
+    for (const id of selectReclaimableWorktrees(runs, keep)) {
+        const run = byId.get(id);
+        if (!run?.worktreePath)
+            continue;
+        try {
+            await remove(repoRoot, run.worktreePath);
+            if (existsSync(run.worktreePath))
+                continue; // reclaim failed; retry next pass
+            store.updateRun(id, { worktreeReclaimedAt: now() });
+            reclaimed.push(id);
+        }
+        catch {
+            // best-effort: never let retention crash a terminal transition or startup.
+        }
+    }
+    return reclaimed;
+}
+//# sourceMappingURL=retention.js.map

package/dist/runs/retention.js.map

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

package/dist/runs/review-gate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Optional diff-first review gate (#489, spec `2026-07-18-optional-review-gate`).
+ *
+ * The review gate (spec 009) used to fire for EVERY successful run whose worktree
+ * held changes — parking it at `review` until a human accepts. This resolver makes
+ * that opt-in. It mirrors `liveTitleUpdatesEnabled` (`src/runs/auto-name.ts`) but
+ * with the OPPOSITE default: OFF unless explicitly turned on.
+ *
+ * Precedence: the `config.reviewGate` Settings toggle wins when set; otherwise the
+ * `CEZ_REVIEW_GATE` env decides — enabled ONLY by the exact string `'1'` (anything
+ * else, including `'true'`/`'yes'`/unset, is off); otherwise off.
+ *
+ * Autonomy is applied by the callers, not here: a run parks at `review` only when
+ * `worktreeHasDiff && reviewGateEnabled(config) && !run.autonomous`.
+ */
+export declare function reviewGateEnabled(config: {
+    reviewGate?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;

package/dist/runs/review-gate.js

@@ -0,0 +1,21 @@
+/**
+ * Optional diff-first review gate (#489, spec `2026-07-18-optional-review-gate`).
+ *
+ * The review gate (spec 009) used to fire for EVERY successful run whose worktree
+ * held changes — parking it at `review` until a human accepts. This resolver makes
+ * that opt-in. It mirrors `liveTitleUpdatesEnabled` (`src/runs/auto-name.ts`) but
+ * with the OPPOSITE default: OFF unless explicitly turned on.
+ *
+ * Precedence: the `config.reviewGate` Settings toggle wins when set; otherwise the
+ * `CEZ_REVIEW_GATE` env decides — enabled ONLY by the exact string `'1'` (anything
+ * else, including `'true'`/`'yes'`/unset, is off); otherwise off.
+ *
+ * Autonomy is applied by the callers, not here: a run parks at `review` only when
+ * `worktreeHasDiff && reviewGateEnabled(config) && !run.autonomous`.
+ */
+export function reviewGateEnabled(config, env = process.env) {
+    if (config.reviewGate !== undefined)
+        return config.reviewGate;
+    return env.CEZ_REVIEW_GATE === '1';
+}
+//# sourceMappingURL=review-gate.js.map

package/dist/runs/review-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-gate.js","sourceRoot":"","sources":["../../src/runs/review-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAgC,EAChC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAEpC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC;IAC9D,OAAO,GAAG,CAAC,eAAe,KAAK,GAAG,CAAC;AACrC,CAAC"}

package/dist/runs/run-index.d.ts

@@ -0,0 +1,19 @@
+import { type RunRecord } from './store.ts';
+/**
+ * The READ-ONLY half of `runs.json`, for the workspace-level run index (`GET
+ * /workspace/runs-index`) — the one place that must read a project's runs WITHOUT owning it.
+ *
+ * `RunStore.open` cannot be used here and the reason is the whole point of this module. Opening a
+ * store `mkdir`s `<dataDir>/runs/`, and the caller that opens one goes on to build a
+ * `ProjectContext` — which prunes orphan worktrees and calls `manager.recover()`, resuming
+ * interrupted runs. Building the workspace index must never do any of that: answering "which
+ * tasks exist" would restart agents across every registered project, and typing into a search box
+ * would spend tokens. Cold projects are precisely the ones the index exists to reach, so
+ * `contexts.peek()` (which returns nothing for them) is not an answer either.
+ *
+ * What this does share with the store is the schema and `reconcileLoadedRun`, so a `running` row
+ * left behind by a crashed process reads as interrupted here exactly as it would once the project
+ * were opened for real. A second, subtly different parse of that field would show a task as
+ * running in the palette and failed the moment you clicked it.
+ */
+export declare function readRunIndexFromDisk(dataDir: string): RunRecord[];

package/dist/runs/run-index.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { reconcileLoadedRun, runRecordSchema } from './store.js';
+/**
+ * The READ-ONLY half of `runs.json`, for the workspace-level run index (`GET
+ * /workspace/runs-index`) — the one place that must read a project's runs WITHOUT owning it.
+ *
+ * `RunStore.open` cannot be used here and the reason is the whole point of this module. Opening a
+ * store `mkdir`s `<dataDir>/runs/`, and the caller that opens one goes on to build a
+ * `ProjectContext` — which prunes orphan worktrees and calls `manager.recover()`, resuming
+ * interrupted runs. Building the workspace index must never do any of that: answering "which
+ * tasks exist" would restart agents across every registered project, and typing into a search box
+ * would spend tokens. Cold projects are precisely the ones the index exists to reach, so
+ * `contexts.peek()` (which returns nothing for them) is not an answer either.
+ *
+ * What this does share with the store is the schema and `reconcileLoadedRun`, so a `running` row
+ * left behind by a crashed process reads as interrupted here exactly as it would once the project
+ * were opened for real. A second, subtly different parse of that field would show a task as
+ * running in the palette and failed the moment you clicked it.
+ */
+export function readRunIndexFromDisk(dataDir) {
+    const indexPath = join(dataDir, 'runs.json');
+    if (!existsSync(indexPath))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(indexPath, 'utf8'));
+        const parsed = z.array(runRecordSchema).safeParse(raw);
+        if (!parsed.success)
+            return [];
+        // `reconcileLoadedRun` mutates, which is safe here in a way it is not in the store: these
+        // records were just parsed into fresh objects that nothing else holds a reference to.
+        // Never `keepLive` — this reader has no RunManager, so there is nothing to recover into.
+        return parsed.data.map((run) => reconcileLoadedRun(run));
+    }
+    catch {
+        // Corrupt or unreadable index. A project that cannot be read contributes nothing to the
+        // index rather than failing the whole workspace's search — the same degrade-quietly rule
+        // the rest of the registry follows.
+        return [];
+    }
+}
+//# sourceMappingURL=run-index.js.map

package/dist/runs/run-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-index.js","sourceRoot":"","sources":["../../src/runs/run-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAkB,MAAM,YAAY,CAAC;AAEjF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAC/B,0FAA0F;QAC1F,sFAAsF;QACtF,yFAAyF;QACzF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,wFAAwF;QACxF,yFAAyF;QACzF,oCAAoC;QACpC,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}