@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/runs/report-rows.d.ts

@@ -0,0 +1,36 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare const REPORTS_BACKFILL_KEY = "reports-backfill-complete";
+export declare const REPORTS_MIGRATION = "\n  CREATE TABLE artifacts (\n    id TEXT PRIMARY KEY, run_id TEXT NOT NULL, name TEXT NOT NULL,\n    title TEXT, created_at TEXT NOT NULL, size INTEGER NOT NULL\n  ) STRICT;\n  CREATE INDEX artifacts_created_at ON artifacts (created_at DESC, id);\n  CREATE INDEX artifacts_run_id ON artifacts (run_id);\n";
+export interface IndexedArtifact {
+    id: string;
+    runId: string;
+    name: string;
+    title?: string | undefined;
+    createdAt: string;
+    size: number;
+}
+export type ReportRow = IndexedArtifact & {
+    summary: string;
+};
+export type ReportCursor = readonly [string, string];
+type Execute = <T>(work: () => T) => T;
+export declare function reportRows(db: DatabaseSync, execute: Execute): ReportRows;
+/** Prepared once per connection. Only replace() owns a transaction; mark/delete join the run write. */
+export declare class ReportRows {
+    private db;
+    private execute;
+    private statements;
+    constructor(db: DatabaseSync, execute: Execute);
+    markDirty(id: string, live: boolean, revision: number): void;
+    retry(id: string, revision?: number): void;
+    dirty(): string[];
+    deleteRun(id: string): void;
+    drop(id: string): void;
+    count(): number;
+    page(before: ReportCursor | undefined, limit: number): ReportRow[];
+    summaries(): Generator<ReportRow>;
+    forRun(id: string): IndexedArtifact[];
+    list(): IndexedArtifact[];
+    replace(runId: string, artifacts: readonly IndexedArtifact[], revision?: number, complete?: boolean): void;
+}
+export {};

package/dist/runs/report-rows.js

@@ -0,0 +1,102 @@
+export const REPORTS_BACKFILL_KEY = 'reports-backfill-complete';
+export const REPORTS_MIGRATION = `
+  CREATE TABLE artifacts (
+    id TEXT PRIMARY KEY, run_id TEXT NOT NULL, name TEXT NOT NULL,
+    title TEXT, created_at TEXT NOT NULL, size INTEGER NOT NULL
+  ) STRICT;
+  CREATE INDEX artifacts_created_at ON artifacts (created_at DESC, id);
+  CREATE INDEX artifacts_run_id ON artifacts (run_id);
+`;
+const instances = new WeakMap();
+export function reportRows(db, execute) {
+    let rows = instances.get(db);
+    if (!rows) {
+        rows = new ReportRows(db, execute);
+        instances.set(db, rows);
+    }
+    return rows;
+}
+function artifact(row) {
+    return { id: row.id, runId: row.run_id, name: row.name,
+        ...(row.title === null ? {} : { title: row.title }), createdAt: row.created_at, size: row.size };
+}
+/** Prepared once per connection. Only replace() owns a transaction; mark/delete join the run write. */
+export class ReportRows {
+    db;
+    execute;
+    statements;
+    constructor(db, execute) {
+        this.db = db;
+        this.execute = execute;
+        this.statements = {
+            live: db.prepare('SELECT live FROM runs WHERE id = ?'),
+            exists: db.prepare('SELECT 1 FROM runs WHERE id = ?'),
+            mark: db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value'),
+            dirty: db.prepare("SELECT key FROM meta WHERE key >= 'reports-dirty:' AND key < 'reports-dirty;'"),
+            clear: db.prepare('DELETE FROM meta WHERE key = ? AND CAST(value AS INTEGER) <= ?'),
+            retry: db.prepare(`INSERT INTO meta (key, value) SELECT ?, ? WHERE EXISTS (SELECT 1 FROM runs WHERE id = ?)
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value WHERE CAST(meta.value AS INTEGER) < CAST(excluded.value AS INTEGER)`),
+            clearRun: db.prepare('DELETE FROM meta WHERE key = ?'),
+            deleteRun: db.prepare('DELETE FROM artifacts WHERE run_id = ?'),
+            drop: db.prepare('DELETE FROM artifacts WHERE id = ?'),
+            insert: db.prepare('INSERT INTO artifacts (id, run_id, name, title, created_at, size) VALUES (?, ?, ?, ?, ?, ?)'),
+            count: db.prepare('SELECT COUNT(*) AS total FROM artifacts a JOIN runs r ON r.id = a.run_id'),
+            all: db.prepare('SELECT a.*, r.summary FROM artifacts a JOIN runs r ON r.id = a.run_id ORDER BY a.created_at DESC, a.id'),
+            first: db.prepare('SELECT a.*, r.summary FROM artifacts a JOIN runs r ON r.id = a.run_id ORDER BY a.created_at DESC, a.id LIMIT ?'),
+            page: db.prepare(`SELECT a.*, r.summary FROM artifacts a JOIN runs r ON r.id = a.run_id
+        WHERE a.created_at < ? OR (a.created_at = ? AND a.id > ?) ORDER BY a.created_at DESC, a.id LIMIT ?`),
+            perRun: db.prepare('SELECT * FROM artifacts WHERE run_id = ?'),
+        };
+    }
+    markDirty(id, live, revision) {
+        this.execute(() => { if (live || this.statements.live.get(id)?.live === 1)
+            this.statements.mark.run(`reports-dirty:${id}`, String(revision)); });
+    }
+    retry(id, revision) { this.execute(() => this.statements.retry.run(`reports-dirty:${id}`, String(revision ?? 0), id)); }
+    dirty() { return this.execute(() => this.statements.dirty.all().map(row => { return row.key.slice('reports-dirty:'.length); })); }
+    deleteRun(id) { this.execute(() => { this.statements.deleteRun.run(id); this.statements.clearRun.run(`reports-dirty:${id}`); }); }
+    drop(id) { this.execute(() => this.statements.drop.run(id)); }
+    count() { return this.execute(() => this.statements.count.get().total); }
+    page(before, limit) {
+        return this.execute(() => {
+            const rows = before ? this.statements.page.all(before[0], before[0], before[1], limit) : this.statements.first.all(limit);
+            return rows.map(row => ({ ...artifact(row), summary: row.summary }));
+        });
+    }
+    *summaries() {
+        const iterator = this.execute(() => this.statements.all.iterate());
+        for (let next = this.execute(() => iterator.next()); !next.done; next = this.execute(() => iterator.next())) {
+            const row = next.value;
+            yield { ...artifact(row), summary: row.summary };
+        }
+    }
+    forRun(id) { return this.execute(() => this.statements.perRun.all(id).map(artifact)); }
+    list() { return this.execute(() => this.statements.all.all().map(artifact)); }
+    replace(runId, artifacts, revision, complete = true) {
+        this.execute(() => {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                this.statements.deleteRun.run(runId);
+                if (this.statements.exists.get(runId)) {
+                    for (const a of artifacts)
+                        this.statements.insert.run(a.id, runId, a.name, a.title ?? null, a.createdAt, a.size);
+                }
+                if (complete)
+                    this.statements.clear.run(`reports-dirty:${runId}`, revision ?? -1);
+                else
+                    this.retry(runId, revision);
+                this.db.exec('COMMIT');
+            }
+            catch (error) {
+                if (this.db.isTransaction) {
+                    try {
+                        this.db.exec('ROLLBACK');
+                    }
+                    catch { /* Preserve the original write failure. */ }
+                }
+                throw error;
+            }
+        });
+    }
+}
+//# sourceMappingURL=report-rows.js.map

package/dist/runs/report-rows.js.map

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

package/dist/runs/retention.d.ts

@@ -0,0 +1,91 @@
+import type { PreviewHostLike } from '../preview/registration.ts';
+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. Finished owned workers count
+ *  (#575) once their parent is gone or `done` (collection-gated). A live,
+ *  failed, or cancelled parent can still collect/diff from the dir. Live runs,
+ *  `review`, `invalid`, and workers mid-destroy do not. `lookup` finds the parent
+ *  by id (the store's `getRun`; a parent need not have a worktree of its own). */
+export declare function isReclaimable(run: RunRecord, lookup?: (id: string) => RunRecord | undefined): boolean;
+/**
+ * Given the runs with a worktree 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. `lookup` finds an owned
+ * worker's parent; without it, the parent is looked for among `runs`.
+ *
+ * `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, lookup?: (id: string) => RunRecord | undefined): 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 {
+    /** The candidates: runs with a materialized worktree (an indexed query, #779). */
+    listRunsWithWorktree(): RunRecord[];
+    getRun(id: string): RunRecord | undefined;
+    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 | undefined;
+    }): 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).
+ * Owned workers still refuse this path: continue verifies the owned workspace
+ * instead of recreating an unverified tree. `invalid` is never rematerialized.
+ */
+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>;
+    /** Claims the run for the whole reclaim, or returns null to skip it. A selection is made before
+     *  any await, so without a claim a Continue admitted in between would resume into the directory
+     *  the forced removal is about to delete. The run manager's `claimWorktreeReclaim` is the one
+     *  that also blocks admission; startup sweeps run before any run can start and omit it. */
+    claim?: (run: RunRecord) => (() => void) | null;
+    /** Require a clean, ref-kept checkout for an owned worker too. Retention (#575) relies on the
+     *  worker's evidence snapshot; a person pressing Reclaim on one row (issue 08 §B4) is not shown
+     *  that a diff snapshot drops binary content and caps its size, so that path asks for clean. */
+    requireClean?: boolean;
+    /** The workspace preview host (#781): the default reclaimer releases the run's preview first. */
+    previewHost?: Pick<PreviewHostLike, 'release'> | undefined;
+}
+export declare function reclaimWorktrees(repoRoot: string, store: RetentionStore, keep: number, opts?: ReclaimOptions): Promise<string[]>;
+/**
+ * Reclaim ONE run's worktree directory — the step `reclaimWorktrees` applies to each over-limit
+ * run, and what `POST /worktrees/:runId/reclaim` (issue 08 §B4) calls for a single row. The
+ * caller has already decided the run `isReclaimable`. Branch kept; owned workers get their
+ * evidence snapshotted first, and any other run's checkout must be clean — uncommitted work is
+ * not on the branch, so removing it would not be recoverable. Returns the stamp it wrote, or null
+ * when nothing was reclaimed (the directory survived or was dirty, or evidence could not be
+ * preserved). Never throws.
+ */
+export declare function reclaimWorktree(repoRoot: string, store: RetentionStore, run: RunRecord, opts?: ReclaimOptions): Promise<string | null>;

package/dist/runs/retention.js

@@ -0,0 +1,193 @@
+import { logPrefix } from '../home/display.js';
+import { isFallbackProjectPath, projectPaths } from '../project-paths.js';
+// 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 { autosaveCleanupBlocker } from '../autosave-cleanup.js';
+import { collectWorkerEvidence } from '../delegation/results.js';
+import { createWorktree } from '../git-worktree.js';
+import { releaseThenRemoveWorktree } from '../git-worktree-release.js';
+/** The "finished" status set — mirrors the statuses `RunStore.archiveFinished` sweeps. 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. Finished owned workers count
+ *  (#575) once their parent is gone or `done` (collection-gated). A live,
+ *  failed, or cancelled parent can still collect/diff from the dir. Live runs,
+ *  `review`, `invalid`, and workers mid-destroy do not. `lookup` finds the parent
+ *  by id (the store's `getRun`; a parent need not have a worktree of its own). */
+export function isReclaimable(run, lookup = () => undefined) {
+    if (run.delegation?.role === 'invalid')
+        return false;
+    if (run.delegation?.role === 'worker' && run.delegation.destroy)
+        return false;
+    if (!FINISHED.has(run.status) || !run.worktreePath || !existsSync(run.worktreePath) || run.worktreeReclaimedAt)
+        return false;
+    if (run.delegation?.role === 'worker') {
+        const parent = lookup(run.delegation.parentRunId);
+        // `done` is collection-gated. failed/cancelled parents can still collect later.
+        if (parent && parent.status !== 'done')
+            return false;
+    }
+    return true;
+}
+/**
+ * Given the runs with a worktree 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. `lookup` finds an owned
+ * worker's parent; without it, the parent is looked for among `runs`.
+ *
+ * `keep === 0` means "unlimited — never auto-reclaim" and returns `[]`.
+ * Pure: no I/O, no mutation of the input.
+ */
+export function selectReclaimableWorktrees(runs, keep, lookup = (id) => runs.find((run) => run.id === id)) {
+    if (!Number.isFinite(keep) || keep <= 0)
+        return [];
+    const reclaimable = runs
+        .filter((run) => isReclaimable(run, lookup))
+        .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).
+ * Owned workers still refuse this path: continue verifies the owned workspace
+ * instead of recreating an unverified tree. `invalid` is never rematerialized.
+ */
+export async function rematerializeReclaimedWorktree(repoRoot, store, runId) {
+    const run = store.getRun(runId);
+    if (run?.delegation?.role === 'worker' || run?.delegation?.role === 'invalid')
+        return false;
+    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;
+    }
+}
+/** Snapshot parent-owned worker evidence before the checkout goes.
+ *  Test fakes without `commitWorkerResult` skip this. A collect/commit failure
+ *  returns false so the directory is left for the next pass. */
+async function preserveWorkerResult(repoRoot, store, run) {
+    if (run.delegation?.role !== 'worker')
+        return true;
+    const commit = store.commitWorkerResult;
+    if (typeof commit !== 'function')
+        return true;
+    const evidence = await collectWorkerEvidence(repoRoot, store, run);
+    commit.call(store, run.delegation.parentRunId, evidence.result, evidence.diffSnapshot);
+    return evidence.diffSnapshot !== undefined || evidence.result.diff.state === 'available';
+}
+function readOnlyWorktree(repoRoot, store, run) {
+    return store.isFallbackRun?.(run.id) === true ||
+        Boolean(run.worktreePath && isFallbackProjectPath(repoRoot, run.worktreePath));
+}
+export async function reclaimWorktrees(repoRoot, store, keep, opts = {}) {
+    const runs = store.listRunsWithWorktree();
+    const byId = new Map(runs.map((r) => [r.id, r]));
+    const reclaimed = [];
+    const selected = selectReclaimableWorktrees(runs, keep, (parentId) => store.getRun(parentId));
+    const readonly = (id) => Boolean(byId.get(id) && readOnlyWorktree(repoRoot, store, byId.get(id)));
+    const skipped = selected.filter(readonly).length;
+    if (skipped)
+        console.info(`${logPrefix()} Worktree retention skipped ${skipped} read-only fallback item(s) under ${projectPaths(repoRoot).reads[1]}.`);
+    for (const id of selected.filter(id => !readonly(id))) {
+        const run = byId.get(id);
+        if (run && (await reclaimWorktree(repoRoot, store, run, opts)))
+            reclaimed.push(id);
+    }
+    return reclaimed;
+}
+/**
+ * Reclaim ONE run's worktree directory — the step `reclaimWorktrees` applies to each over-limit
+ * run, and what `POST /worktrees/:runId/reclaim` (issue 08 §B4) calls for a single row. The
+ * caller has already decided the run `isReclaimable`. Branch kept; owned workers get their
+ * evidence snapshotted first, and any other run's checkout must be clean — uncommitted work is
+ * not on the branch, so removing it would not be recoverable. Returns the stamp it wrote, or null
+ * when nothing was reclaimed (the directory survived or was dirty, or evidence could not be
+ * preserved). Never throws.
+ */
+export async function reclaimWorktree(repoRoot, store, run, opts = {}) {
+    if (readOnlyWorktree(repoRoot, store, run))
+        return null;
+    const now = opts.now ?? (() => new Date().toISOString());
+    // Branch kept. An owned worker's evidence (uncommitted diff included) is snapshotted first; any
+    // other run's uncommitted work lives only in the directory, so a dirty one is left for later.
+    const onlyClean = opts.requireClean === true || run.delegation?.role !== 'worker';
+    const real = store;
+    const execution = real.readWorkerExecution?.(run.id);
+    const assertSafe = () => {
+        // Startup has no manager claim. Terminal execution can still have a retained
+        // autosave writer, so recheck its durable proof before every destructive step.
+        if (autosaveCleanupBlocker(real.sourceDataDir?.(run.id) ?? projectPaths(repoRoot).write, run.id))
+            throw Error('Autosave cleanup is not confirmed');
+        if (run.delegation?.role !== 'worker')
+            return;
+        // Structural test stores have no private execution machinery. Real stores must attest both
+        // generation ownership and fresh resource holders, including after async evidence/preview.
+        if (typeof real.workerResourcesSafe === 'function' && (!execution ||
+            !real.workerResourcesSafe(run.id, execution.generation, run.delegation.workspace.resourceId)))
+            throw Error('Worker resources are not safe to reclaim');
+    };
+    const remove = opts.remove ?? ((root, path) => releaseThenRemoveWorktree({ previewHost: opts.previewHost }, run.id, root, path, undefined, { reclaimOwnedDirectory: true, onlyClean, assertCurrent: assertSafe }));
+    if (!run.worktreePath)
+        return null;
+    const release = opts.claim ? opts.claim(run) : () => undefined;
+    if (!release)
+        return null; // in use since it was selected
+    // Claimed in the run database too, for the whole reclaim (#779, plan step 3): no other cezar
+    // process writes this run or reclaims it meanwhile, and another process's run is left alone.
+    // Structural test stores have no claims.
+    let pinned = typeof real.pin !== 'function';
+    try {
+        pinned ||= real.pin.call(store, run.id, 'cleanup') !== undefined;
+    }
+    catch { /* busy: not claimed */ }
+    if (!pinned) {
+        release();
+        return null;
+    }
+    try {
+        assertSafe();
+        if (!(await preserveWorkerResult(repoRoot, store, run).catch(() => false)))
+            return null;
+        if (opts.remove)
+            assertSafe(); // injected reclaimer has no final callback
+        await remove(repoRoot, run.worktreePath);
+        if (existsSync(run.worktreePath))
+            return null; // reclaim failed; retry next pass
+        const stamp = now();
+        store.updateRun(run.id, { worktreeReclaimedAt: stamp });
+        return stamp;
+    }
+    catch {
+        // best-effort: never let retention crash a terminal transition or startup.
+        return null;
+    }
+    finally {
+        real.unpin?.call(store, run.id, 'cleanup');
+        release();
+    }
+}
+//# 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 | undefined;
+}, env?: NodeJS.ProcessEnv): boolean;

package/dist/runs/review-gate.js

@@ -0,0 +1,22 @@
+import { productEnv } from '../core/product-env.js';
+/**
+ * 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 productEnv('REVIEW_GATE', env) === '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,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA4C,EAC5C,GAAG,GAAsB,OAAO,CAAC,GAAG;IAEpC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC;IAC9D,OAAO,UAAU,CAAC,aAAa,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC;AAChD,CAAC"}

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

@@ -0,0 +1,30 @@
+import type { RunDatabase, RunRow } from './run-database.ts';
+import type { RunRecord } from './store.ts';
+/**
+ * Claim owners carry store session, PID and process start identity. Only a proven dead owner can
+ * be replaced; unknown identity on a live PID remains live.
+ */
+export interface ClaimOwner {
+    session: string;
+    pid: number;
+    /** Null only where the platform cannot read a start identity. */
+    startToken: string | null;
+}
+/** A fresh owner identity for one store, live until `closeClaimSession`. */
+export declare function openClaimSession(): ClaimOwner;
+/** The store behind `session` is gone: any claim it left behind is now provably dead. */
+export declare function closeClaimSession(session: string): void;
+/** Whether the owner of `claim` may still be writing. False only when it is proven gone. */
+export declare function claimOwnerLive(claim: ClaimOwner): boolean;
+/** Every run whose family a store other than `owner` claims — alive, or dead with a live run left
+ *  to recover (cleanup keeps their scratch: it is theirs, or recovery's once someone adopts them).
+ *  A dead owner's claim on a family with nothing live is no claim (see `RunStore.runOwnership`). */
+export declare function foreignClaimedRunIds(db: RunDatabase | null, owner: ClaimOwner | undefined): string[];
+/** The runs of every family a live store other than `owner` claims: a headless `cez run`, another
+ *  binary, or a second store of this process. Both physical claim tables count, so a stale legacy
+ *  claim never hides a live fallback one. A project migration fence refuses while any exists. */
+export declare function liveForeignClaimedRunIds(db: RunDatabase | null, owner: ClaimOwner | undefined): string[];
+/** The `run_claims` family of a run: a worker's parent, else the run itself (`parent_run_id ?? id`). */
+export declare function familyKey(run: Pick<RunRecord, 'id' | 'delegation'>): string;
+/** The same family, off a stored row's columns. */
+export declare function rowFamily(row: Pick<RunRow, 'id' | 'parentRunId'>): string;

package/dist/runs/run-claims.js

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { isCurrentProcess, processStartToken, recordedProcessLive } from '../delegation/process-liveness.js';
+/** The sessions open in this process: the only way to tell two stores in one process apart. */
+const openSessions = new Set();
+let ownStartToken;
+/** A fresh owner identity for one store, live until `closeClaimSession`. */
+export function openClaimSession() {
+    ownStartToken ??= processStartToken(process.pid) ?? null;
+    const owner = { session: randomUUID(), pid: process.pid, startToken: ownStartToken };
+    openSessions.add(owner.session);
+    return owner;
+}
+/** The store behind `session` is gone: any claim it left behind is now provably dead. */
+export function closeClaimSession(session) {
+    openSessions.delete(session);
+}
+/** Whether the owner of `claim` may still be writing. False only when it is proven gone. */
+export function claimOwnerLive(claim) {
+    const entry = { pid: claim.pid, ...(claim.startToken === null ? {} : { startToken: claim.startToken }) };
+    if (claim.pid === process.pid)
+        return isCurrentProcess(entry) && openSessions.has(claim.session);
+    return recordedProcessLive(entry);
+}
+/** Every run whose family a store other than `owner` claims — alive, or dead with a live run left
+ *  to recover (cleanup keeps their scratch: it is theirs, or recovery's once someone adopts them).
+ *  A dead owner's claim on a family with nothing live is no claim (see `RunStore.runOwnership`). */
+export function foreignClaimedRunIds(db, owner) {
+    if (!db || !owner)
+        return [];
+    // Both physical claim tables: a stale legacy claim must not hide a live fallback owner.
+    const kept = new Set(db.listClaims(true).filter((claim) => claim.session !== owner.session &&
+        (claimOwnerLive(claim) || db.familyHasLive(claim.family))).map((claim) => claim.family));
+    return kept.size === 0 ? [] : db.listForeignClaimedIds(owner.session).filter((row) => kept.has(row.family)).map((row) => row.id);
+}
+/** The runs of every family a live store other than `owner` claims: a headless `cez run`, another
+ *  binary, or a second store of this process. Both physical claim tables count, so a stale legacy
+ *  claim never hides a live fallback one. A project migration fence refuses while any exists. */
+export function liveForeignClaimedRunIds(db, owner) {
+    if (!db || !owner)
+        return [];
+    const live = new Set(db.listClaims(true).filter((claim) => claim.session !== owner.session && claimOwnerLive(claim)).map((claim) => claim.family));
+    return [...live].flatMap((family) => [family, ...db.listIdsByParent(family)]);
+}
+/** The `run_claims` family of a run: a worker's parent, else the run itself (`parent_run_id ?? id`). */
+export function familyKey(run) {
+    return run.delegation?.role === 'worker' ? run.delegation.parentRunId : run.id;
+}
+/** The same family, off a stored row's columns. */
+export function rowFamily(row) {
+    return row.parentRunId ?? row.id;
+}
+//# sourceMappingURL=run-claims.js.map

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

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

package/dist/runs/run-database-peer-page.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { RunSummaryRow } from './run-database.ts';
+export type PeerSummaryPageQuery = {
+    all: boolean;
+    excluded: readonly string[];
+    offset: number;
+    limit: number;
+};
+/** Each archive branch uses the existing runs_archived_roots index (archive, date, seq).
+ * SQLite merges those ordered branches before LIMIT; no archive or worker list enters JS. */
+export declare function readPeerSummaryPage(db: DatabaseSync, options: PeerSummaryPageQuery): RunSummaryRow[];
+export declare function toSummaryRow(row: Record<string, unknown>): RunSummaryRow;

package/dist/runs/run-database-peer-page.js

@@ -0,0 +1,25 @@
+/** Each archive branch uses the existing runs_archived_roots index (archive, date, seq).
+ * SQLite merges those ordered branches before LIMIT; no archive or worker list enters JS. */
+export function readPeerSummaryPage(db, options) {
+    const archives = options.all ? [0, 1] : [0];
+    const selects = archives.map(archived => `SELECT seq, id, created_at, revision, summary FROM runs
+    WHERE parent_run_id IS NULL AND archived = ${archived}
+      AND id NOT IN (SELECT value FROM json_each(?))
+      AND CASE WHEN json_valid(data) THEN
+        (json_extract(data, '$.delegation.role') IS NULL OR json_extract(data, '$.delegation.role') = 'root')
+        AND json_extract(data, '$.delegation.historyDeletion') IS NULL
+        ELSE 0 END`);
+    const excluded = JSON.stringify(options.excluded);
+    return db.prepare(`${selects.join(' UNION ALL ')} ORDER BY created_at DESC, seq LIMIT ? OFFSET ?`)
+        .all(...archives.map(() => excluded), options.limit, options.offset).map(toSummaryRow);
+}
+export function toSummaryRow(row) {
+    return {
+        seq: row.seq,
+        id: row.id,
+        createdAt: row.created_at,
+        revision: row.revision,
+        summary: row.summary,
+    };
+}
+//# sourceMappingURL=run-database-peer-page.js.map

package/dist/runs/run-database-peer-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-database-peer-page.js","sourceRoot":"","sources":["../../src/runs/run-database-peer-page.ts"],"names":[],"mappings":"AAKA;6FAC6F;AAC7F,MAAM,UAAU,mBAAmB,CAAC,EAAgB,EAAE,OAA6B;IACjF,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;iDACM,QAAQ;;;;;mBAKtC,CAAC,CAAC;IACnB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClD,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,iDAAiD,CAAC;SAC/F,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAA4B;IACvD,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,GAAa;QACtB,EAAE,EAAE,GAAG,CAAC,EAAY;QACpB,SAAS,EAAE,GAAG,CAAC,UAAoB;QACnC,QAAQ,EAAE,GAAG,CAAC,QAAkB;QAChC,OAAO,EAAE,GAAG,CAAC,OAAiB;KAC/B,CAAC;AACJ,CAAC"}