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

package/dist/runs/run-exits.js

@@ -0,0 +1,191 @@
+import { isUsageLimitHold } from '../contract/index.js';
+/** A root that holds a pending Finish intent. */
+const rootFinishPending = (run) => run.delegation?.role === 'root' && !!run.delegation.finishRequestedAt;
+/** The root's pending Finish intent, retired as a patch (SRF): nothing when the run holds none. */
+export function retiredFinishPatch(run) {
+    if (run.delegation?.role !== 'root' || !run.delegation.finishRequestedAt)
+        return {};
+    const { finishRequestedAt: _intent, ...delegation } = run.delegation;
+    return { delegation };
+}
+/** The statuses a run settles at. `review` is one, though not final: a settled turn rests there. */
+const SETTLED_STATUSES = ['done', 'review', 'failed', 'cancelled'];
+/** Whether `exit` settles a run: it writes done, review, failed or cancelled. */
+export function settlesRun(exit) {
+    return SETTLED_STATUSES.includes(RUN_EXITS[exit].to);
+}
+/**
+ * What every settling exit writes over its caller's extras (Table B targets): a settled run points
+ * at no step, and a root's Finish intent means nothing once the run settled (B1-B3). Its first
+ * settlement time is the fact, so a later write on a settled run keeps it (B4); else it settles at
+ * the time `write` names (a site whose steps settled at that time passes it), else now.
+ */
+const settledRun = (run, write, { now }) => ({ ...retiredFinishPatch(run), currentStepId: undefined, finishedAt: run.finishedAt ?? write.finishedAt ?? now });
+/** The legacy `activity` cleared: a key no patch type takes (`WithLegacyActivity`). */
+const CLEARED_ACTIVITY = { activity: undefined };
+/** A run that succeeded: its resume counter and the legacy `activity` retired. A run that got all
+ *  the way to a settled turn is not in a usage-limit loop, so its resume counter starts over
+ *  instead of creeping toward the cap. */
+const succeeded = () => ({ autoResumeAttempts: undefined, ...CLEARED_ACTIVITY });
+/** A step that is running or waiting. */
+const openStep = (step) => step.status === 'running' || step.status === 'waiting';
+/** A run that succeeded settles its running and waiting steps done at its time (B5). A worker's
+ *  incomplete earlier step, the one the caller names, stays waiting: a parent resume re-enters it
+ *  (hearsay-tools/cezarion#1620). */
+const succeededStep = (step, _run, { finishedAt, stepId }) => openStep(step) && step.id !== stepId ? { ...step, status: 'done', finishedAt: step.finishedAt ?? finishedAt } : step;
+/** A cancelled run has no live step (B10): its running and waiting steps settle cancelled at the
+ *  run's time. */
+const cancelledStep = (step, _run, { finishedAt }) => openStep(step) ? { ...step, status: 'cancelled', finishedAt: step.finishedAt ?? finishedAt } : step;
+/** A failed run has no live step (B11): its running steps fail at the run's time, each keeping an
+ *  error of its own, else taking the run's. A waiting step stays waiting: it is the cursor a
+ *  Continue resumes, a root's (`settleIncompleteStep`) and an owned worker's alike
+ *  (hearsay-tools/cezarion#1620). */
+const failedStep = (step, _run, { finishedAt, error }) => step.status === 'running' ? { ...step, status: 'failed', finishedAt: step.finishedAt ?? finishedAt, error: step.error ?? error } : step;
+/** A park settles its step waiting in the same write (B8): the step the caller names, else the
+ *  run's current step. A step that already ended (a failed attempt a park keeps for its wakes)
+ *  stays as it is. */
+const parkedStep = (step, run, { stepId }) => step.id === (stepId ?? run.currentStepId) && (step.status === 'running' || step.status === 'pending') ? { ...step, status: 'waiting' } : step;
+/** A released park: the legacy `activity` cleared. */
+function settleParkRelease(run) {
+    const settled = { ...run, activity: undefined };
+    return settled;
+}
+/** The lifecycle event of a cancellation: one for each run a cancel exit moves into cancelled (B12). */
+export const RUN_CANCELLED = 'run cancelled';
+const rootFinishWaiting = (run) => run.status === 'waiting' && rootFinishPending(run);
+export const RUN_EXITS = {
+    start: { durability: 'debounced', from: ['queued', 'running', 'waiting'], to: 'running' },
+    'start-held': { durability: 'debounced', from: ['queued'], to: 'queued' },
+    requeue: { durability: 'debounced', from: ['queued', 'running', 'failed'], to: 'queued', fields: () => ({ currentStepId: undefined }) },
+    'continue-line': { durability: 'debounced', from: ['waiting', 'review', 'done', 'failed', 'cancelled'], to: 'queued',
+        fields: () => ({ error: undefined, finishedAt: undefined, currentStepId: undefined }) },
+    // The step it runs is the caller's: `currentStepId` is an extra.
+    'continue-now': { durability: 'debounced', from: ['waiting', 'review', 'done', 'failed', 'cancelled'], to: 'running',
+        fields: () => ({ error: undefined, finishedAt: undefined }) },
+    park: { durability: 'debounced', from: ['running', 'queued', 'waiting'], to: 'waiting', steps: parkedStep },
+    // A park that gives up its slot (hearsay-tools/cezarion#1235): committed at once, so a refused
+    // write throws with nothing changed and the caller keeps the slot.
+    'park-release': { durability: 'committed', from: ['running', 'queued', 'waiting'], to: 'waiting', settle: settleParkRelease, steps: parkedStep },
+    'park-for-wake': { durability: 'debounced', from: ['queued', 'waiting'], to: 'waiting' },
+    hold: { durability: 'debounced', from: ['failed', 'waiting'], to: 'waiting', fields: () => ({ finishedAt: undefined }) },
+    resume: { durability: 'debounced', from: ['waiting'], to: 'running' },
+    succeed: { durability: 'debounced', from: ['running', 'waiting'], to: 'done', fields: succeeded, steps: succeededStep },
+    'succeed-review': { durability: 'debounced', from: ['running', 'waiting'], to: 'review', fields: succeeded, steps: succeededStep },
+    // A root's durable Finish: a concurrent explicit cancellation is never overwritten.
+    'succeed-root': { durability: 'committed', from: ['waiting'], to: 'done', guard: rootFinishWaiting, fields: succeeded, steps: succeededStep },
+    'succeed-root-review': { durability: 'committed', from: ['waiting'], to: 'review', guard: rootFinishWaiting, fields: succeeded, steps: succeededStep },
+    'accept-review': { durability: 'debounced', from: ['review'], to: 'done' },
+    // Draft PR (`POST /runs/:id/pr`): the cockpit offers it on review and on settled runs, so a
+    // settled run that is published reads done too. The route refuses a usage-limit hold (spec B13).
+    'draft-pr': { durability: 'debounced', from: ['review', 'done', 'failed', 'cancelled'], to: 'done' },
+    'fail-start': { durability: 'debounced', from: ['queued', 'running'], to: 'failed', steps: failedStep },
+    fail: { durability: 'debounced', from: ['running', 'waiting'], to: 'failed', steps: failedStep },
+    // settleFailedContinuation alone: a worker Stop can record cancelled before it settles.
+    'fail-continue': { durability: 'debounced', from: ['running', 'waiting', 'cancelled'], to: 'failed', steps: failedStep },
+    'fail-interrupted': { durability: 'debounced', from: ['queued', 'running', 'waiting'], to: 'failed',
+        fields: () => ({ error: 'interrupted — cezar process exited during the run' }), steps: failedStep },
+    'fail-crash': { durability: 'debounced', from: ['queued', 'running', 'waiting'], to: 'failed', steps: failedStep },
+    // A crash right after the withdrawal must not find it on disk (hearsay-tools/cezarion#1236).
+    'withdraw-hold': { durability: 'committed', from: ['waiting'], to: 'failed', guard: isUsageLimitHold,
+        settle: run => ({ ...run, autoResumeAt: undefined, autoResumeAttempts: undefined }), steps: failedStep },
+    cancel: { durability: 'debounced', from: ['queued', 'running', 'waiting'], to: 'cancelled', steps: cancelledStep, event: RUN_CANCELLED },
+    // Cancellation supersedes a root's pending Finish; from cancelled it repairs a snapshot an older
+    // controller left with the intent.
+    'cancel-root': { durability: 'committed', from: ['waiting', 'cancelled'], to: 'cancelled',
+        guard: run => (run.status === 'waiting' || run.status === 'cancelled') && rootFinishPending(run), steps: cancelledStep, event: RUN_CANCELLED },
+    // Must hit disk before queued no-start evidence authorizes cleanup.
+    'stop-worker': { durability: 'committed', from: ['queued', 'running', 'waiting', 'review', 'done', 'failed'], to: 'cancelled',
+        guard: run => run.delegation?.role === 'worker', refused: 'Worker not found', steps: cancelledStep, event: RUN_CANCELLED },
+    // A Stop that lands after the run settled. A Stop accepted before an exit (`stopping` on load)
+    // can meet any status, as the engine's late Stop can.
+    'cancel-late': { durability: 'debounced', from: ['queued', 'running', 'waiting', 'done', 'review', 'failed'], to: 'cancelled', steps: cancelledStep, event: RUN_CANCELLED },
+};
+/** The lifecycle event a write that applies `exit` to a run at `from` writes: the exit's `event`,
+ *  or the caller's text for it, when the exit moves the run into its status. A repeated write on a
+ *  run already there writes none, so one cancellation reads as one event (B12). */
+export function exitEvent(exit, from, call = {}) {
+    const spec = RUN_EXITS[exit];
+    return spec.event && from !== spec.to ? call.event ?? spec.event : undefined;
+}
+/** The record rule: a Done commits at once on a run with a completion option, because its
+ *  completion action and archive must be durable (hearsay-tools/cezarion#2324). */
+export function doneCommits(run) {
+    return Boolean(run.archiveWhenDone || run.autoMergePr);
+}
+/**
+ * How `RunStore.move` persists `exit` on `run`, the record before the write (Decision 4). First
+ * match wins: the record rule (an exit to `done` on a run with a completion option commits), then
+ * the exit's own `durability`. A rule only raises a debounced exit to committed. An exit applied
+ * inside another commit (`resume` in `commitOutcome`, `continue-*` in `commitWorkerContinuation`)
+ * commits with that commit, before either rule; the caller's extras never decide.
+ */
+export function exitDurability(exit, run) {
+    const spec = RUN_EXITS[exit];
+    return spec.to === 'done' && doneCommits(run) ? 'committed' : spec.durability;
+}
+let strict = false;
+/** Strict mode only: outside it nothing is recorded, so production keeps no growing list. */
+const violations = [];
+/** Tests only: `vitest.setup.ts` calls it, so a violation is recorded for `throwRunExitViolations`
+ *  instead of logged. Returns the previous mode, so a test that changes it can put it back. */
+export function strictRunExits(on = true) {
+    const previous = strict;
+    strict = on;
+    return previous;
+}
+/** The violations recorded since the last call. */
+export function takeRunExitViolations() {
+    return violations.splice(0);
+}
+/** Throws the violations recorded since the last call: the test setup runs it after each test. */
+export function throwRunExitViolations() {
+    const taken = takeRunExitViolations();
+    if (taken.length)
+        throw new Error(taken.join('\n'));
+}
+/** Report run-exit and wait-phase violations without interrupting the write.
+ * Strict mode records them for the test setup; production warns once per violation. */
+export function reportStoreViolation(message) {
+    if (strict)
+        violations.push(message);
+    else
+        console.warn(message);
+}
+function checkFrom(exit, from) {
+    const spec = RUN_EXITS[exit];
+    if (from === undefined || from === spec.to || spec.from.includes(from))
+        return;
+    reportStoreViolation(`undeclared run transition: exit ${exit} from ${from} (declare it in runs/run-exits.ts)`);
+}
+/**
+ * Apply `exit` to `run`, a record in hand: check its status against the exit's `from` and return
+ * the fields to write: the exit's `fields`, then `extras` over them, then what a settling exit
+ * writes on every run (`settledRun`), then the steps its `steps` changed, then the exit's status. It
+ * neither runs a guard nor a guarded `settle`: a caller of a guarded exit checks its guard itself.
+ * `RunStore.move` writes through it, and the store's load-time and archive writers assign its
+ * result onto the record they change.
+ */
+export function applyExit(run, exit, extras = {}, call = {}) {
+    const spec = RUN_EXITS[exit];
+    const at = { ...call, now: new Date().toISOString() };
+    const patch = { ...spec.fields?.(run, at), ...extras };
+    const write = { ...patch, ...(settlesRun(exit) ? settledRun(run, patch, at) : {}) };
+    const settlement = { ...at, finishedAt: write.finishedAt ?? at.now, error: write.error ?? run.error };
+    const steps = spec.steps && run.steps ? settleSteps(run.steps, step => spec.steps(step, run, settlement)) : undefined;
+    return { ...write, ...(steps ? { steps } : {}), status: exitStatus(exit, run.status) };
+}
+/** `steps` with each settled by `settle`, or undefined when none changed. */
+function settleSteps(steps, settle) {
+    const settled = steps.map(settle);
+    return settled.some((step, index) => step !== steps[index]) ? settled : undefined;
+}
+/**
+ * The status `exit` writes onto a run whose status is `from`. The store calls it inside the write
+ * that applies the exit, with the record that write changes. It reports an exit that does not
+ * leave from `from`, then returns the status all the same.
+ */
+export function exitStatus(exit, from) {
+    checkFrom(exit, from);
+    return RUN_EXITS[exit].to;
+}
+//# sourceMappingURL=run-exits.js.map

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

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

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

@@ -0,0 +1,36 @@
+import { type RunSummary } from '../contract/index.js';
+import { type RepoHandle } from './store.ts';
+/** A cold project's runs as list rows, and whether older archived roots were left out. */
+export interface ColdRunIndex {
+    runs: RunSummary[];
+    truncated: boolean;
+}
+/**
+ * Read project history without ownership or recovery side effects. Prefer completed SQLite
+ * imports; never fall back to stale JSON when that database is unreadable. Share run decoding
+ * and normalization with the store.
+ */
+export declare function readRunIndexFromDisk(dataDir: string, options?: {
+    handle?: RepoHandle | null | undefined;
+    archivedWindow?: number;
+    roots?: boolean;
+}): ColdRunIndex;
+/**
+ * A cold project's ROOT runs, archived or not, that match `query` (`matchesRunSearch`), newest
+ * first: at most `limit`, and whether more matched. The workspace search behind ⌘K (#864), with
+ * the same side-effect-free contract as `readRunIndexFromDisk`.
+ */
+export declare function searchRunIndexFromDisk(dataDir: string, query: string, options: {
+    handle?: RepoHandle | null | undefined;
+    limit: number;
+}): ColdRunIndex;
+/**
+ * The run that owns a checkout in a cold project, as its list row: the one holding a worktree at
+ * one of `worktreePaths`, else the newest that owns `branch`. The database answers through its
+ * indexed `worktree_path` and `branch` columns, never a scan; same contract as
+ * `readRunIndexFromDisk`, so an unreadable project names no run.
+ */
+export declare function findColdRunByCheckout(dataDir: string, checkout: {
+    worktreePaths: readonly string[];
+    branch: string | null;
+}): RunSummary | undefined;

package/dist/runs/run-index.js

@@ -0,0 +1,262 @@
+import { logPrefix } from '../home/display.js';
+import { legacyIndexRows } from './legacy-run-rows.js';
+import { addRunSource, fallbackRunSource } from './project-run-sources.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runSummarySchema, toRunSummary } from '../contract/index.js';
+import { RUNS_DB_FILE, RUNS_IMPORT_COMPLETE_KEY, RunDatabase } from './run-database.js';
+import { decodeRunRecord, LEGACY_INDEX_FILE, reconcileLoadedRun, parseRunRecords } from './store.js';
+import { rescopeRun } from './run-references.js';
+import { matchesRunSearch, searchTokens, sqlPrefilterTokens } from '../contract/index.js';
+const EMPTY = { runs: [], truncated: false };
+/** Projects whose unreadable rows this process has already reported: ⌘K reads the index on every
+ *  keystroke's request, and one warning per project is enough. */
+const reportedUnreadable = new Set();
+/**
+ * Read project history without ownership or recovery side effects. Prefer completed SQLite
+ * imports; never fall back to stale JSON when that database is unreadable. Share run decoding
+ * and normalization with the store.
+ */
+export function readRunIndexFromDisk(dataDir, options = {}) {
+    return readCold(dataDir, EMPTY, (db) => readDatabase(db, dataDir, options), () => readLegacyIndex(dataDir, options));
+}
+/**
+ * A cold project's ROOT runs, archived or not, that match `query` (`matchesRunSearch`), newest
+ * first: at most `limit`, and whether more matched. The workspace search behind ⌘K (#864), with
+ * the same side-effect-free contract as `readRunIndexFromDisk`.
+ */
+export function searchRunIndexFromDisk(dataDir, query, options) {
+    return readCold(dataDir, EMPTY, (db) => searchDatabase(db, dataDir, query, options), () => {
+        const { runs } = readLegacyIndex(dataDir, options);
+        return firstMatches(runs.filter((run) => run.delegation?.role !== 'worker'), query, options.limit);
+    });
+}
+/**
+ * The run that owns a checkout in a cold project, as its list row: the one holding a worktree at
+ * one of `worktreePaths`, else the newest that owns `branch`. The database answers through its
+ * indexed `worktree_path` and `branch` columns, never a scan; same contract as
+ * `readRunIndexFromDisk`, so an unreadable project names no run.
+ */
+export function findColdRunByCheckout(dataDir, checkout) {
+    const pick = (rows) => rows.find((row) => row.worktreePath !== null && checkout.worktreePaths.includes(row.worktreePath))
+        ?? rows.filter((row) => checkout.branch !== null && row.branch === checkout.branch)
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+    return readCold(dataDir, undefined, (db) => {
+        const ids = new Set(checkout.worktreePaths.flatMap((worktreePath) => db.findResourceHolders({ branch: checkout.branch ?? '', worktreePath })));
+        const row = pick(db.getMany([...ids]));
+        return row ? parseSummary(row.summary) : undefined;
+    }, () => {
+        try {
+            const owner = pick(readLegacyRecords(dataDir).map((run) => ({ run, worktreePath: run.worktreePath ?? null, branch: run.branch ?? null, createdAt: run.createdAt })));
+            return owner ? coldSummary(owner.run) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+/** The source rule both readers share: an imported `runs.db` is the only source, a `runs.db` that
+ *  cannot be read contributes `empty`, and before the import the legacy `runs.json` is read. */
+function readCold(dataDir, empty, fromDatabase, fromLegacy) {
+    let db = null;
+    try {
+        db = RunDatabase.openReadOnly(join(dataDir, RUNS_DB_FILE));
+        const source = fallbackRunSource(dataDir, bytes => legacyIndexRows(bytes, parseRunRecords)?.rows);
+        if (source) {
+            if (db && db.getMeta(RUNS_IMPORT_COMPLETE_KEY) === undefined) {
+                db.close();
+                db = null;
+            }
+            if (!db) {
+                const index = join(dataDir, LEGACY_INDEX_FILE);
+                const parsed = existsSync(index) ? legacyIndexRows(readFileSync(index), parseRunRecords) : { rows: [] };
+                if (!parsed)
+                    return empty;
+                const rows = parsed.rows;
+                db = RunDatabase.open(':memory:');
+                db.transaction({ upserts: rows, deletes: [], meta: { [RUNS_IMPORT_COMPLETE_KEY]: 'read-only' } });
+            }
+            db = addRunSource(db, dataDir, source, true);
+        }
+    }
+    catch {
+        db?.close();
+        return empty;
+    }
+    if (db) {
+        try {
+            if (db.getMeta(RUNS_IMPORT_COMPLETE_KEY) !== undefined)
+                return fromDatabase(db);
+        }
+        catch {
+            return empty;
+        }
+        finally {
+            db.close();
+        }
+    }
+    return fromLegacy();
+}
+/** The newest `limit` of `runs` that match, and whether another one did. */
+function firstMatches(runs, query, limit) {
+    const matched = [];
+    for (const run of runs) {
+        if (!matchesRunSearch(run, query))
+            continue;
+        if (matched.length === limit)
+            return { runs: matched, truncated: true };
+        matched.push(run);
+    }
+    return { runs: matched, truncated: false };
+}
+/** `runs` (newest first) with archived roots past `archivedWindow` cut, and whether any were. */
+function applyWindow(runs, archivedWindow) {
+    if (archivedWindow === undefined)
+        return { runs, truncated: false };
+    let archived = 0;
+    const kept = runs.filter((run) => !run.archived || ++archived <= archivedWindow);
+    return { runs: kept, truncated: archived > archivedWindow };
+}
+function readDatabase(db, dataDir, { handle, archivedWindow, roots }) {
+    // One archived root past the window is how "there are older ones" is known without counting.
+    const rows = archivedWindow === undefined ? db.listSummaries() : db.listWindowSummaries(archivedWindow + 1, { roots });
+    return applyWindow(projectRows(db, rows, dataDir, handle), archivedWindow);
+}
+function searchDatabase(db, dataDir, query, { handle, limit }) {
+    // Match on the stored summary first, so only candidates pay for a decode; each candidate is
+    // projected and matched again as it is read, because reading it cold can drop a foreign
+    // reference it matched on. The scan stops at one match past the limit counted AFTER that, so
+    // dropped candidates can never use up the cap and hide an older real match (#864 review).
+    const matched = [];
+    // Repair can introduce an issue number or URL, but cannot introduce an unrelated prose word.
+    const repairIssueAttribution = searchTokens(query).some(token => /^#?\d+$/.test(token) || /(?:^|\/)issues\/\d+/i.test(token));
+    db.visitRootSummaries(sqlPrefilterTokens(query), (row) => {
+        const summary = parseSummary(row.summary);
+        if (summary !== undefined && (!repairIssueAttribution || summary.markerRefs?.issue === undefined) && !matchesRunSearch(summary, query))
+            return true;
+        const [projected] = projectRows(db, [row], dataDir, handle);
+        if (projected && matchesRunSearch(projected, query))
+            matched.push(projected);
+        return matched.length <= limit;
+    }, { includeIssueMarked: repairIssueAttribution });
+    return matched.length > limit ? { runs: matched.slice(0, limit), truncated: true } : { runs: matched, truncated: false };
+}
+/** Rows as list rows: the stored summary when reading cold cannot change it, else the decoded
+ *  record projected as the store would. A row that decodes to nothing is left out. */
+function projectRows(db, rows, dataDir, handle) {
+    const summaries = rows.map((row) => parseSummary(row.summary));
+    const decode = rows.filter((row, i) => {
+        const summary = summaries[i];
+        return summary === undefined || needsRecord(summary, handle);
+    });
+    const records = new Map(db.getMany(decode.map((row) => row.id)).map((row) => [row.id, decodeRunRecord(row.data)]));
+    const runs = [];
+    let unreadable = 0;
+    rows.forEach((row, i) => {
+        const summary = summaries[i];
+        if (summary !== undefined && !needsRecord(summary, handle)) {
+            runs.push(summary);
+            return;
+        }
+        // A row that decodes to nothing is one the store leaves out of its list rows too.
+        const record = records.get(row.id);
+        if (record)
+            runs.push(coldSummary(record, handle));
+        else
+            unreadable++;
+    });
+    if (unreadable > 0 && !reportedUnreadable.has(dataDir)) {
+        reportedUnreadable.add(dataDir);
+        console.warn(`${logPrefix()} ${unreadable} run(s) in ${join(dataDir, RUNS_DB_FILE)} could not be read; they are left out of the run index and left in the database untouched.`);
+    }
+    return runs;
+}
+function parseSummary(text) {
+    try {
+        const parsed = runSummarySchema.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether reading this run cold could change its stored summary: the questions
+ * `reconcileLoadedRun`, `rescopeRun` and the ask refresh would answer, asked of the summary. Only
+ * these runs pay for decoding their full record; every other row is served as stored.
+ *
+ * One case is invisible from here: a finished run that still carries an accepted Stop (`stopping`
+ * is not in the summary) would read as cancelled once its record were decoded. The writer clears
+ * `stopping` as the run settles, so that takes a crash inside that window.
+ */
+function needsRecord(summary, handle) {
+    // A live-looking run reads as interrupted (or cancelled, after an accepted Stop).
+    if (summary.status === 'queued' || summary.status === 'running' || summary.status === 'waiting')
+        return true;
+    // Monitoring state, and a usage-limit resume on anything but a waiting run, are cleared; an old
+    // failed one is read as waiting (hearsay-tools/cezarion#1236). Any resume time, not
+    // `isUsageLimitHold`: a stale one on a finished summary is what the record must correct.
+    if (summary.activity !== undefined)
+        return true;
+    if (summary.autoResumeAt !== undefined)
+        return true;
+    // A referenced PR that an older cezar's created-PR declaration erased is restored.
+    if (summary.referencedPullRequestUrl === undefined && summary.markerRefs?.pr !== undefined)
+        return true;
+    // Issue markers may have overwritten the originating issue in older records.
+    if (summary.markerRefs?.issue !== undefined)
+        return true;
+    // A foreign reference the prompt does not corroborate is dropped; the prompt is in the record.
+    if (handle && (summary.referencedPullRequestUrl !== undefined || summary.referencedIssueUrl !== undefined))
+        return true;
+    // A summary an older build stored may still show the old engine's `delegation.wait`: it is
+    // re-derived, so the upgraded record speaks instead (hearsay-tools/cezarion#1301). A pending
+    // question is an open human wait in the record since phase 4b (hearsay-tools/cezarion#1236), so no
+    // transcript is read for it.
+    return summary.delegation?.role === 'root' && summary.delegation.wait !== undefined;
+}
+function readLegacyIndex(dataDir, { handle, archivedWindow, roots }) {
+    try {
+        const records = readLegacyRecords(dataDir);
+        // The window leaves archived workers out, as `RunDatabase.listWindowSummaries` does, and
+        // with `roots` every worker.
+        const listed = archivedWindow === undefined
+            ? records
+            : records.filter((run) => run.delegation?.role !== 'worker' || (!run.archived && !roots));
+        // Reconciling never moves `createdAt` or `archived`, so the window is cut before projecting.
+        const newest = listed.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        const { runs: kept, truncated } = applyWindow(newest, archivedWindow);
+        return { runs: kept.map((run) => coldSummary(run, handle)), truncated };
+    }
+    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 EMPTY;
+    }
+}
+/** The legacy `runs.json` records; none when the file is absent. A record that does not parse
+ *  costs that record only, exactly as its import will (store.ts). Throws on an unreadable file. */
+function readLegacyRecords(dataDir) {
+    const indexPath = join(dataDir, LEGACY_INDEX_FILE);
+    if (!existsSync(indexPath))
+        return [];
+    const raw = JSON.parse(readFileSync(indexPath, 'utf8'));
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((entry) => {
+        const parsed = parseRunRecords([entry]);
+        return parsed.success ? parsed.data : [];
+    });
+}
+/**
+ * One record read cold, as its list row. `reconcileLoadedRun` mutates, which is safe here in a way
+ * it is not in the store: the record was just parsed into a fresh object nothing else holds.
+ * Never `keepLive` — this reader has no RunManager, so there is nothing to recover into.
+ */
+function coldSummary(run, handle) {
+    reconcileLoadedRun(run);
+    rescopeRun(run, handle);
+    return toRunSummary(run);
+}
+//# 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":"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"}

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

@@ -0,0 +1,61 @@
+import type { RunEvent, RunPullRequest } from '../contract/index.js';
+import type { RepoHandle, RunRecord } from './store.ts';
+export declare const PR_URL_RE: RegExp;
+export declare const ISSUE_URL_RE: RegExp;
+/**
+ * Resolve declarations and prompt-supported candidates without guessing through ambiguity. Apply
+ * repository scope to the winner only; filtering candidates first could promote an otherwise
+ * ambiguous reference.
+ */
+export declare function resolveReferencedRef(candidates: string[], task: string, declared?: number, handle?: RepoHandle | null): string | undefined;
+/** The number a forge URL's last segment names (`…/pull/402` → 402), or undefined. */
+export declare function refUrlNumber(url: string | undefined): number | undefined;
+/**
+ * Ignore a created-PR declaration when resolving the referenced subject, so a task can retain
+ * both its original subject and its new PR.
+ */
+export declare function referencedPrDeclaration(run: RunRecord): number | undefined;
+/** Prompt attribution survives declarations of follow-up issues. Bare hashes become issues
+ * only after an issue signal; explicit PR prompts never acquire an invented issue identity. */
+export declare function originatingIssue(run: RunRecord): number | undefined;
+export declare function resolveIssueReference(run: RunRecord, handle?: RepoHandle | null): string | undefined;
+export declare function restoreOriginatingIssue(run: RunRecord): void;
+/**
+ * Drop this run's referenced PR/issue if the project's handle proves it foreign and the prompt
+ * does not corroborate it (#945). Returns whether anything changed.
+ *
+ * One-directional by construction: it only ever clears fields, so a record written by an older
+ * cezar — or read by one after this ran — is never worse off, and a downgrade sees a record whose
+ * format is untouched and whose cleared fields were already optional.
+ */
+export declare function rescopeRun(run: RunRecord, handle?: RepoHandle | null): boolean;
+/**
+ * Fold every PR URL in `haystack` into the run's referenced-tier working
+ * set and re-resolve `referencedPullRequestUrl` (spec
+ * 2026-07-16-pr-autodiscovery). Mutates the record in place — the caller
+ * owns persistence/fan-out — and reports whether anything changed.
+ */
+export declare function trackReferencedPrs(run: RunRecord, haystack: string, handle?: RepoHandle | null): boolean;
+/**
+ * The issue-side mirror of `trackReferencedPrs` (spec
+ * 2026-07-21-report-ref-discovery): fold every issue URL in `haystack` into
+ * the working set and re-resolve `referencedIssueUrl`. An unambiguous
+ * resolution also seeds `issueNumber` when nothing owns that field yet —
+ * marker and namer both outrank this janitor and overwrite it freely.
+ */
+export declare function trackReferencedIssues(run: RunRecord, haystack: string, handle?: RepoHandle | null, seedHaystack?: string): boolean;
+/**
+ * The janitor trick: agents print the PR URL after `gh pr create` — the
+ * first one spotted in the transcript becomes the run's PR link. Scans v1
+ * fields AND nested v2 `item.*` content (#407). A URL without the created
+ * phrasing still feeds the referenced tier (the PR the task is about) —
+ * and the phrasing itself is only believed from a source that can speak
+ * FOR this run (`eventCreationClaimFragments`), never from quoted output.
+ *
+ * Runs after the event is appended, indexed and emitted: discovery reads the
+ * event text and may still update and touch the run.
+ * `accumulatePullRequests` is the store's staging callback
+ * (`stagePullRequests` with the store's repo handle); `touch` is the
+ * store's dirty/save/fan-out signal.
+ */
+export declare function scanEventReferences(run: RunRecord, event: RunEvent, repoHandle: RepoHandle | null | undefined, accumulatePullRequests: (run: RunRecord, entries: readonly RunPullRequest[]) => boolean, touch: (run: RunRecord) => void): void;