@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/run-records.js

@@ -0,0 +1,1678 @@
+import { appendFile, link, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { acquireSaveLock, SaveLockBusyError } from './save-lock.js';
+import { configDirectory } from './config.js';
+import { writeSessionSnapshot } from './sessions.js';
+import { ToolFailureTracker } from './tool-failure-tracker.js';
+import { stopReasonPhrase } from './runtime.js';
+/**
+ * The directory holding one JSON Lines event log and one JSON result per run.
+ *
+ * `runs/` sits inside the installation directory, beside `config.json` and `artifacts/`, so the
+ * identity that names a record is also the last path segment of a file this process writes.
+ */
+export function runRecordsDirectory(directory = configDirectory()) {
+    return join(directory, 'runs');
+}
+/** The history entry a session carries while its attempt is in flight, replaced when the attempt lands. */
+export const RUNNING_TURN_SUMMARY = 'This attempt was interrupted or is still running. Verify the workspace before continuing.';
+/** The same entry after recovery classifies the attempt as one the engine never finished. */
+export const INTERRUPTED_TURN_SUMMARY = 'This attempt stopped unexpectedly before it finished; its work may be incomplete.';
+/**
+ * What a session marker should say when the run record finalized but the session never heard how
+ * the attempt ended. Stopped outcomes commonly carry no completion object at all — a cancel has
+ * nothing to summarize — and then the recorded status is the only account left: a sentence about
+ * the engine stopping unexpectedly would contradict a record that says the user cancelled.
+ */
+export function summaryForStoppedRecord(record) {
+    const summary = record.completion?.summary;
+    if (typeof summary === 'string')
+        return summary;
+    if (record.status === 'cancelled')
+        return 'This attempt was cancelled before it finished; its work may be incomplete.';
+    if (record.status === 'interrupted')
+        return INTERRUPTED_TURN_SUMMARY;
+    const reason = typeof record.reason === 'string' && record.reason.length > 0 ? record.reason : undefined;
+    // A record's reason is read after the colon of a sentence about the attempt, so it goes through
+    // the same classification every other surface uses: an internal code such as
+    // `maxNodeVisits:qa` becomes the sentence a person can act on, and a failure message is used
+    // whole. Reading the code raw would leak the identifier this repository never shows a user.
+    return reason === undefined ? 'This attempt did not finish; its work may be incomplete.' : `This attempt did not finish: ${stopReasonPhrase(reason)}.`;
+}
+export async function writeStudioRunSummary(directory, record) {
+    const graph = record.graph && typeof record.graph === 'object' ? record.graph : undefined;
+    const projected = {
+        id: record.id, status: record.status,
+        ...(record.startedAt ? { startedAt: record.startedAt } : {}),
+        ...(record.graphSelection ? { graphSelection: record.graphSelection } : {}),
+        ...(record.accountSubject ? { accountSubject: record.accountSubject } : {}),
+        ...(graph ? { graph: { id: graph.id, revision: graph.revision } } : {}),
+        ...(typeof record.toolCalls === 'number' ? { toolCalls: record.toolCalls } : {}),
+    };
+    await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+    await writeSessionSnapshot(join(runRecordsDirectory(directory), `${record.id}.studio-summary`), JSON.stringify(projected) + '\n');
+}
+/**
+ * The claim naming a run open — required, unlike the supplemental studio summary.
+ *
+ * The claim is the answer `sessionHasOpenRun` gives every rail mutation, so a run whose claim
+ * failed to land would be invisible to the guard while its result record says the session is
+ * live: another process could then archive, rename, or delete the live session, and the run's
+ * final save would overwrite or recreate what that mutation did. `writeOpenRunRecord` therefore
+ * publishes the record only once this write has landed; the snapshot layer behind it already
+ * retries the transient rename failures (Windows AV locks) that a suppressed failure would
+ * otherwise turn into that state.
+ */
+async function writeOpenRunClaim(directory, claim) {
+    const body = { runId: claim.runId, sessionId: claim.sessionId, pid: claim.pid ?? process.pid, claimedAt: new Date().toISOString(), startedAt: processStartedAt(), nonce: PROCESS_NONCE };
+    await writeSessionSnapshot(runRecordPath(directory, claim.runId, 'open-run'), JSON.stringify(body) + '\n');
+}
+/** Drop a run's open claim. A run only ever owns its own claim, so this cannot clobber another's. */
+export async function clearOpenRunClaim(directory, runId) {
+    await rm(runRecordPath(directory, runId, 'open-run'), { force: true }).catch(() => { });
+}
+/**
+ * Remove the record of an attempt that never began.
+ *
+ * The claim and the record answer one question — is a run live? — and a question with no run behind
+ * it has to have neither. A record left behind is an attempt the Runs view lists, and its live pid
+ * tells the recovery that another process owns it, so the attempt stays `running` until that
+ * process exits.
+ */
+export async function removeOpenRunRecord(directory, runId) {
+    // The claim is released only when the record is gone. A record that still says the run is live,
+    // with no claim to say so, is a history that contradicts itself — and when the file cannot be
+    // removed, the claim stays and the recovery classifies the attempt once its owner is gone.
+    const removed = await rm(runRecordPath(directory, runId, 'json'), { force: true }).then(() => true, () => false);
+    await rm(join(runRecordsDirectory(directory), `${runId}.studio-summary`), { force: true }).catch(() => { });
+    if (removed)
+        await clearOpenRunClaim(directory, runId);
+}
+/** The result file written at start; atomic, so a crash mid-write cannot tear the record. */
+export async function writeOpenRunRecord(directory, record) {
+    await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+    // The claim lands before the record, and the record is not published without it: from the
+    // moment any engine can see the open record, the guard already has its index entry. The reverse
+    // order — or a suppressed claim failure — would leave the state this method's own guard cannot
+    // answer: the record says the run is live while the claim, the guard's fast answer, is missing,
+    // and a rail mutation of this session is accepted against a run that trusts the record.
+    await writeOpenRunClaim(directory, { runId: record.id, sessionId: record.sessionId, pid: record.pid });
+    await writeSessionSnapshot(runRecordPath(directory, record.id, 'json'), JSON.stringify(record, null, 2) + '\n');
+    // Best effort: failure of the supplemental index must not abort a real coding run.
+    await writeStudioRunSummary(directory, record).catch(() => { });
+}
+/** Whether a process is running. A live process owned by another user answers EPERM, not ESRCH. */
+export function isPidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** This process's own start time, as the claims it writes record it. */
+export function processStartedAt() {
+    return new Date(Date.now() - Math.round(process.uptime() * 1000)).toISOString();
+}
+/**
+ * This process instance's identity, as the claims it writes record it.
+ *
+ * A pid is not an identity — the OS hands a dead process's number to the next one, and a
+ * container that restarts within seconds reuses the same number for its replacement. A start
+ * time compared with a tolerance cannot tell those apart either: a restarted PID-1 container
+ * starts within the tolerance of the one it replaces, so its predecessor's claim would look
+ * like this process's own. A value that exists only in this instance of the process answers it
+ * exactly: the claim carries the nonce of the process that wrote it, and a claim this process
+ * did not write is a claim of a different instance, whatever the number it carried.
+ */
+const PROCESS_NONCE = randomUUID();
+/** This process instance's nonce, for a claim that carries one. */
+export function processNonce() {
+    return PROCESS_NONCE;
+}
+/**
+ * The workspaces this process is working in.
+ *
+ * The reservation is the process's rather than an engine's: an app server and an MCP or CLI
+ * subagent in one process are two engines over one workspace, and two full-access runs in it
+ * would write the same files at once. The unit the reservation covers is the workspace, because
+ * that is what two overlapping runs would both write to.
+ */
+const processWorkspaces = new Map();
+/**
+ * Reserve a workspace for an engine in this process.
+ *
+ * @returns whether the reservation was taken; a workspace another engine in this process is
+ * working in is not available.
+ */
+export function claimProcessWorkspace(workspace, owner) {
+    if (processWorkspaces.has(workspace))
+        return false;
+    processWorkspaces.set(workspace, owner);
+    return true;
+}
+/** Give a workspace back, when the engine releasing it is the one that reserved it. */
+export function releaseProcessWorkspace(workspace, owner) {
+    if (processWorkspaces.get(workspace) === owner)
+        processWorkspaces.delete(workspace);
+}
+/**
+ * When a running process started, as the platform can report it, or `undefined` when it cannot.
+ *
+ * A pid alone is not an identity: the OS reuses it, so a claim whose holder was killed can appear
+ * to be held by an unrelated process that inherited the number, and that attempt would refuse to be
+ * resumed for as long as the impostor lives. Comparing the start time the claim recorded for its
+ * holder with the start time the OS reports for that pid is what tells the two apart. The probe is
+ * deliberately best-effort — a platform that cannot answer returns nothing, and the caller falls
+ * back to pid liveness — because being unable to check must never turn a live holder into a stale
+ * one (which is the direction that would let two engines resume the same attempt).
+ */
+async function processStartedAtFor(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return undefined;
+    try {
+        if (process.platform === 'linux') {
+            // Field 22 of `/proc/<pid>/stat` is the start time in clock ticks since boot; the process name
+            // (field 2) may hold spaces and parentheses, so parsing starts after its last `)`.
+            const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+            const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            const ticks = Number(fields[19]);
+            const boot = /^btime (\d+)/m.exec(await readFile('/proc/stat', 'utf8'));
+            if (!Number.isFinite(ticks) || !boot)
+                return undefined;
+            return (Number(boot[1]) + ticks / 100) * 1000;
+        }
+        const { execFile } = await import('node:child_process');
+        const [command, args] = process.platform === 'win32'
+            ? ['powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString('o')`]]
+            : ['ps', ['-o', 'lstart=', '-p', String(pid)]];
+        const output = await new Promise(resolve => {
+            execFile(command, args, { timeout: 5_000, windowsHide: true }, (error, stdout) => resolve(error ? undefined : stdout));
+        });
+        const parsed = output === undefined ? NaN : Date.parse(output.trim());
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How far a recorded start time may differ from the probed one and still be the same process. */
+const PROCESS_START_TOLERANCE_MS = 5_000;
+const validSessionFile = (id) => /^[a-f0-9-]{36}$/i.test(id);
+/**
+ * Classify the runs and session turns a previous process left unfinished.
+ *
+ * A run that finalizes replaces its open record and its marker turn together; anything that ends
+ * that way needs no help here. What this repairs is the other end: a process killed between the
+ * open record and the finalizer leaves a record stuck at `running` and a session turn claiming the
+ * attempt "is still running", and neither can tell the difference between live work and a crash on
+ * its own. The pid answers it — a process this home's engine cannot see is gone — and from there
+ * the record becomes `interrupted`, the marker entry is upgraded to say so, and a marker whose
+ * record never landed gets an interrupted record synthesized so the run is at least listable.
+ *
+ * A record whose pid is alive is left untouched: another engine on this home may genuinely be
+ * running it — and it is named in `live`, captured by the same walk, so a caller who wants to
+ * react when such a holder exits needs no second scan (and no gap between two). `onlyRunIds`
+ * bounds the rewrite to records the caller already knows its own earlier sweep left open: a
+ * delayed repair must never touch a record a live process still owns, including the calling
+ * engine's own active run. The whole pass is best-effort; one damaged record never hides the
+ * others.
+ */
+export async function reconcileInterruptedRuns(directory, onlyRunIds, options) {
+    const recovery = { runs: [], markers: 0, live: [], interrupted: [] };
+    const swept = await markOpenRunsInterrupted(directory, onlyRunIds, options?.skipOwnProcess === true, options?.includePending === true);
+    recovery.runs = swept.ids;
+    recovery.live = swept.live;
+    recovery.interrupted = swept.records;
+    recovery.markers = await upgradeSessionMarkers(directory);
+    return recovery;
+}
+/**
+ * The open records this process can no longer own, rewritten with status `interrupted`, plus the
+ * records the same walk left running because a live foreign process owns them.
+ *
+ * The live set is what lets a starting engine watch its predecessor without a second scan: the
+ * sweep either recovers a record whose holder is gone or names it here, so an exit at any moment
+ * is caught by one pass or the other. `onlyRunIds` bounds the rewrite to records the caller knows
+ * its own earlier sweep left open — a delayed repair must not touch a record a live process still
+ * owns, including the calling engine's own active run.
+ */
+/**
+ * Whether an open run belongs to a run this very process instance is executing.
+ *
+ * A pid is not an identity: the OS hands a dead process's number to the next one, and this
+ * process's own number is no different. The claim beside the record carries the start time its
+ * owner recorded, so a claim this instance wrote is told apart from one an earlier instance with
+ * the same number wrote. The first is a live run — an in-process host that starts a second engine
+ * must not terminalize the first engine's work, which is still executing — and the second is the
+ * debris of a crash.
+ *
+ * A claim with no recorded start time, or one that names another process, proves neither: the
+ * answer is the conservative one, and the run is classified as a crash.
+ */
+async function claimedByThisProcess(directory, runId) {
+    try {
+        const claim = JSON.parse(await readFile(runRecordPath(directory, runId, 'open-run'), 'utf8'));
+        if (claim.pid !== process.pid)
+            return false;
+        // The nonce is the exact answer: a claim this process instance wrote carries it, and one
+        // another instance wrote does not — however close its start time is to this one's.
+        if (typeof claim.nonce === 'string')
+            return claim.nonce === PROCESS_NONCE;
+        // A claim without one was written before the nonce existed, so the start time is all there
+        // is. The tolerance is the conservative direction: a claim that looks like this process's own
+        // is left alone rather than terminalized.
+        if (typeof claim.startedAt !== 'string')
+            return false;
+        const claimed = Date.parse(claim.startedAt);
+        if (!Number.isFinite(claimed))
+            return false;
+        return Math.abs(Date.parse(processStartedAt()) - claimed) <= PROCESS_START_TOLERANCE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+async function markOpenRunsInterrupted(directory, onlyRunIds, skipOwnProcess = false, includePending = false) {
+    const runs = runRecordsDirectory(directory);
+    let names;
+    try {
+        names = await readdir(runs);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { ids: [], live: [], records: [] };
+        throw error;
+    }
+    const ids = [];
+    const live = [];
+    const records = [];
+    for (const name of names) {
+        // Only result records: `.json` is the result's extension, and `.checkpoint.json` names only
+        // ever existed as a checkpoint before the suffix was shortened to keep it out of the scans.
+        if (!name.endsWith('.json') || name.endsWith('.checkpoint.json'))
+            continue;
+        const path = join(runs, name);
+        let value;
+        try {
+            value = JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!value || typeof value !== 'object')
+            continue;
+        if (value.status !== 'running' && !(includePending && value.status === 'interrupted' && value.telemetryPending === true))
+            continue;
+        const runId = typeof value.id === 'string' && value.id === name.slice(0, -'.json'.length) ? value.id : undefined;
+        if (runId === undefined)
+            continue;
+        // A record rewritten by an earlier recovery whose finish was never queued: the pair is still
+        // owed, and the derived event id makes re-reporting it idempotent.
+        if (value.status === 'interrupted') {
+            records.push(value);
+            continue;
+        }
+        const pid = typeof value.pid === 'number' ? value.pid : undefined;
+        // A live foreign pid is the only answer that keeps a record open — another engine's run, or
+        // the predecessor still shutting down, and it is named in `live` for a watcher to hold. This
+        // process's own pid keeps its active run open too, but it is nobody to watch: the engine is
+        // the one running this code. Anything else is a crash.
+        if (pid !== undefined && pid !== process.pid && isPidAlive(pid)) {
+            live.push({ runId, pid, sessionId: typeof value.sessionId === 'string' ? value.sessionId : undefined });
+            continue;
+        }
+        // A run this very process instance is executing is not debris either. A pid is not an
+        // identity — the OS hands a dead process's number to the next one, and this process's own
+        // number is no different — so the claim beside the record is what tells the two apart: it
+        // carries the start time its owner recorded, and a claim this instance wrote is a run that
+        // is still going. An in-process host that starts a second engine must not terminalize the
+        // first engine's live work: the claim it would remove is what holds the session against a
+        // mutation, and the run would save over that mutation when it finished.
+        if (skipOwnProcess && pid === process.pid && await claimedByThisProcess(directory, runId))
+            continue;
+        if (onlyRunIds !== undefined && !onlyRunIds.has(runId))
+            continue;
+        // Two coordinators can read the same open record before either rewrite lands. The lock makes
+        // the running-to-interrupted transition single-owner, so only one of them enqueues the finish;
+        // the loser has nothing to emit and leaves the record to the winner.
+        const lockDirectory = join(runs, `${runId}.recover`);
+        let release;
+        try {
+            release = await acquireSaveLock(lockDirectory);
+        }
+        catch (error) {
+            if (error instanceof SaveLockBusyError)
+                continue;
+            throw error;
+        }
+        const unlock = async () => {
+            await release();
+            // The lock's own directory is an implementation detail; leaving one empty directory per
+            // recovered run would clutter `runs/` for no reason.
+            await rm(lockDirectory, { recursive: true, force: true }).catch(() => { });
+        };
+        // The record was read before the lock. A coordinator that read it, was descheduled, and then
+        // acquired the lock the winner just released would otherwise rewrite a record that already
+        // says `interrupted` and enqueue a second finish. Only the reading under the lock counts.
+        let current;
+        try {
+            current = JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            await unlock();
+            continue;
+        }
+        if (!current || typeof current !== 'object' || current.status !== 'running') {
+            await unlock();
+            continue;
+        }
+        // `telemetryPending` is cleared by whoever queues the finish. A process that dies between the
+        // rewrite and the enqueue therefore leaves a record a later pass still knows to report.
+        const interrupted = { ...current, status: 'interrupted', telemetryPending: true, reason: 'the engine stopped while this run was active', endedAt: new Date().toISOString() };
+        try {
+            await writeSessionSnapshot(path, JSON.stringify(interrupted, null, 2) + '\n');
+        }
+        catch {
+            await unlock();
+            continue;
+        }
+        await unlock();
+        // Startup recovery can delete the dead claim before MCP monitoring ever
+        // runs. Preserve the pre-snapshot crash signal from the recovered run record
+        // so a previous successful session turn cannot hide this interrupted attempt.
+        const crash = await rememberCrashedClaim(directory, {
+            runId, sessionId: value.sessionId, claimedAt: value.startedAt,
+        });
+        // A marker that could not be persisted leaves the claim as the only
+        // durable, retryable copy of the signal: removing it here would erase the
+        // crash from monitoring for good. A later monitor pass retries the write.
+        if (crash?.durable !== false)
+            // The record says the attempt is over, so its open claim must stop naming it to the guard: a
+            // claim whose holder later turns out to be alive would otherwise hold the session shut.
+            await rm(join(runs, `${runId}.open-run`), { force: true }).catch(() => { });
+        ids.push(runId);
+        records.push(interrupted);
+    }
+    return { ids, live, records };
+}
+/** The facts a session's own history carries, when a caller already holds the snapshot. */
+function sessionCrashFacts(history) {
+    const turns = Array.isArray(history) ? history : [];
+    const runIds = new Set();
+    for (const turn of turns) {
+        const runId = turn?.runId;
+        if (typeof runId === 'string')
+            runIds.add(runId);
+    }
+    const last = turns.at(-1);
+    return last && typeof last.runId === 'string'
+        ? { kind: 'present', runIds, lastRunId: last.runId }
+        : { kind: 'present', runIds };
+}
+async function readSessionCrashFacts(directory, sessionId) {
+    let raw;
+    try {
+        raw = await readFile(join(directory, 'sessions', `${sessionId}.json`), 'utf8');
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? { kind: 'missing' } : { kind: 'unreadable' };
+    }
+    try {
+        return sessionCrashFacts(JSON.parse(raw).history);
+    }
+    catch {
+        return { kind: 'unreadable' };
+    }
+}
+/** Whether a run that started after `time` has persisted a turn in this session. */
+async function persistedRunStartedAfter(directory, runId, time) {
+    if (runId === undefined)
+        return false;
+    const record = await readRunRecord(directory, runId);
+    const startedAt = typeof record?.startedAt === 'string' ? Date.parse(record.startedAt) : Number.NaN;
+    return Number.isFinite(startedAt) && startedAt > time;
+}
+/**
+ * A crashed run may die between writing its claim and saving the running turn.
+ * Keep a small, durable monitor-only signal before cleaning up the dead claim.
+ *
+ * The sidecar exists for one state only: an attempt the session snapshot never
+ * records, hidden behind an older turn. A session that has a turn naming this
+ * run already reports the attempt — a `running` marker turn included — so a
+ * finalizer's terminal record left behind by a failed claim removal must not
+ * become a `crashedAttempt`. A run that started after the claim proves a newer
+ * attempt was persisted, which supersedes the crash. Startup recovery calls
+ * this after rewriting its record, so the pre-snapshot test is the same whether
+ * recovery or a monitor observed the dead claim.
+ *
+ * @returns the marker and whether it reached the disk. `undefined` means no
+ * marker is needed; `durable: false` means the caller must keep its claim, the
+ * only retryable copy of the signal left.
+ */
+async function rememberCrashedClaim(directory, claim, factsFor = sessionId => readSessionCrashFacts(directory, sessionId)) {
+    const runId = claim.runId, sessionId = claim.sessionId, claimedAt = claim.claimedAt;
+    if (typeof runId !== 'string' || typeof sessionId !== 'string'
+        || !validSessionFile(runId) || !validSessionFile(sessionId)
+        || typeof claimedAt !== 'string' || !Number.isFinite(Date.parse(claimedAt)))
+        return undefined;
+    const facts = await factsFor(sessionId);
+    // A deleted session has no monitor row to report. An unreadable snapshot is
+    // not proof the attempt was recorded, so only a readable one can answer.
+    if (facts.kind === 'missing')
+        return undefined;
+    if (facts.kind === 'present') {
+        if (facts.runIds.has(runId))
+            return undefined;
+        if (await persistedRunStartedAfter(directory, facts.lastRunId, Date.parse(claimedAt)))
+            return undefined;
+    }
+    const marker = { runId, claimedAt };
+    try {
+        await writeSessionSnapshot(runRecordPath(directory, runId, 'mcp-crash'), JSON.stringify({ ...marker, sessionId }) + '\n');
+        return { marker, durable: true };
+    }
+    catch {
+        // The session layer already retries transient Windows renames; a failure
+        // that survives that is reported so the caller keeps its claim.
+        return { marker, durable: false };
+    }
+}
+export async function sessionsWithOpenRunClaims(directory, sessions) {
+    const runs = runRecordsDirectory(directory);
+    let names;
+    try {
+        names = await readdir(runs);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { active: new Set(), crashed: new Map() };
+        throw error;
+    }
+    const active = new Set();
+    const crashed = new Map();
+    // A query passes the same snapshot its views are built from, so pruning can
+    // never delete a marker using a save the answer does not reflect. Without one
+    // (no current caller) the files are the only source.
+    const snapshots = sessions === undefined ? undefined : new Map(sessions.map(session => [session.id, session]));
+    const fileFacts = new Map();
+    const absentFacts = new Map();
+    const confirmAbsent = async (sessionId) => {
+        try {
+            await stat(join(directory, 'sessions', `${sessionId}.json`));
+            return { kind: 'unreadable' };
+        }
+        catch (error) {
+            return error.code === 'ENOENT' ? { kind: 'missing' } : { kind: 'unreadable' };
+        }
+    };
+    const factsFor = (sessionId) => {
+        if (snapshots !== undefined) {
+            const session = snapshots.get(sessionId);
+            if (session !== undefined)
+                return sessionCrashFacts(session.history);
+            // The store omits unreadable or invalid records from its listing, so
+            // absence from the snapshot is proof of deletion only when the file
+            // itself is gone. Anything still on disk stays an unknown state, keeping
+            // its marker alive for when the record is repaired.
+            let pending = absentFacts.get(sessionId);
+            if (pending === undefined) {
+                pending = confirmAbsent(sessionId);
+                absentFacts.set(sessionId, pending);
+            }
+            return pending;
+        }
+        let pending = fileFacts.get(sessionId);
+        if (pending === undefined) {
+            pending = readSessionCrashFacts(directory, sessionId);
+            fileFacts.set(sessionId, pending);
+        }
+        return pending;
+    };
+    // Only the newest unresolved crash per session is actionable. Older sidecars
+    // can never outlive it (a persisted run that supersedes the newest also
+    // supersedes them), so keeping them would make every poll reread them forever.
+    const kept = new Map();
+    const keepCrash = async (entry, file) => {
+        const existing = crashed.get(entry.sessionId);
+        const prior = kept.get(entry.sessionId);
+        if (existing !== undefined && Date.parse(existing.claimedAt) >= Date.parse(entry.claimedAt)) {
+            // The selected crash is at least as new; this sidecar is redundant.
+            if (file !== prior)
+                await rm(join(runs, file), { force: true }).catch(() => { });
+            return;
+        }
+        if (prior !== undefined && prior !== file)
+            await rm(join(runs, prior), { force: true }).catch(() => { });
+        crashed.set(entry.sessionId, { runId: entry.runId, claimedAt: entry.claimedAt });
+        kept.set(entry.sessionId, file);
+    };
+    for (const name of names) {
+        if (!name.endsWith('.mcp-crash'))
+            continue;
+        try {
+            const record = JSON.parse(await readFile(join(runs, name), 'utf8'));
+            if (!record || typeof record !== 'object' || Array.isArray(record))
+                continue;
+            const entry = record;
+            if (typeof entry.runId !== 'string' || typeof entry.sessionId !== 'string'
+                || !validSessionFile(entry.runId) || !validSessionFile(entry.sessionId)
+                || typeof entry.claimedAt !== 'string' || !Number.isFinite(Date.parse(entry.claimedAt))
+                || name !== entry.runId + '.mcp-crash')
+                continue;
+            const known = await factsFor(entry.sessionId);
+            // Remove markers nothing can report any more, so the scan stays bounded:
+            // a deleted session is orphaned, and a session that already records the
+            // attempt, or a later run that supersedes it, makes the sidecar redundant.
+            if (known.kind === 'missing'
+                || (known.kind === 'present' && (known.runIds.has(entry.runId)
+                    || await persistedRunStartedAfter(directory, known.lastRunId, Date.parse(entry.claimedAt))))) {
+                await rm(join(runs, name), { force: true }).catch(() => { });
+                continue;
+            }
+            await keepCrash({ runId: entry.runId, sessionId: entry.sessionId, claimedAt: entry.claimedAt }, name);
+        }
+        catch { /* Damaged monitor sidecars must not hide unrelated sessions. */ }
+    }
+    for (const name of names) {
+        if (!name.endsWith('.open-run'))
+            continue;
+        let claim;
+        try {
+            claim = JSON.parse(await readFile(join(runs, name), 'utf8'));
+        }
+        catch {
+            continue; /* A torn claim is handled by the per-session legacy fallback. */
+        }
+        if (!claim || typeof claim !== 'object' || typeof claim.sessionId !== 'string')
+            continue;
+        const outdated = await claimOutlivedItsRun(directory, claim);
+        const pid = typeof claim.pid === 'number' ? claim.pid : undefined;
+        if (!outdated && await claimOwnerIsLive(pid, claim.startedAt)) {
+            active.add(claim.sessionId);
+            continue;
+        }
+        const outcome = await rememberCrashedClaim(directory, claim, factsFor);
+        if (outcome !== undefined)
+            await keepCrash({ ...outcome.marker, sessionId: claim.sessionId }, outcome.marker.runId + '.mcp-crash');
+        // Keep a claim whose crash marker could not be persisted: the claim is the
+        // only retryable copy, and removing it would permanently hide the attempt.
+        if (outcome?.durable === false)
+            continue;
+        await rm(join(runs, name), { force: true }).catch(() => { });
+    }
+    return { active, crashed };
+}
+/**
+ * Whether a live open-run claim still holds this session against mutations.
+ *
+ * `ignoreRunId` excuses one run from the answer: the engine that owns that run mutates the session
+ * safely beside it when its finalizer merges into the record it saves, so it names its own
+ * in-flight run here instead of being held by its own claim. Every other owner — a second window
+ * or the CLI sharing the home — answers exactly as before, crash-claim cleanup included.
+ */
+export async function sessionHasOpenRun(directory, sessionId, options = {}) {
+    const runs = runRecordsDirectory(directory);
+    let names;
+    try {
+        names = await readdir(runs);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (!validSessionFile(sessionId))
+        return scanRunsForOpenRun(directory, sessionId, options.ignoreRunId);
+    for (const name of names) {
+        if (!name.endsWith('.open-run'))
+            continue;
+        let claim;
+        try {
+            claim = JSON.parse(await readFile(join(runs, name), 'utf8'));
+        }
+        // A claim that cannot be parsed proves no owner but hides what the records would say: the scan
+        // is the conservative answer for this directory, not a silent miss.
+        catch {
+            return scanRunsForOpenRun(directory, sessionId, options.ignoreRunId);
+        }
+        if (!claim || typeof claim !== 'object' || claim.sessionId !== sessionId)
+            continue;
+        // The named run is the caller's own work, not a stranger: its claim is excused outright, so
+        // nothing here reclaims or removes it.
+        if (options.ignoreRunId !== undefined && (claim.runId === options.ignoreRunId || name === `${options.ignoreRunId}.open-run`))
+            continue;
+        // A claim the finalizer failed to remove is not evidence of live work, however alive its owner
+        // looks: see `claimOutlivedItsRun`. Reclaiming it here is what keeps a transient removal failure
+        // from holding a session shut for the life of the process that wrote it.
+        if (await claimOutlivedItsRun(directory, claim)) {
+            const outcome = await rememberCrashedClaim(directory, claim);
+            // A marker that could not be written leaves the claim in place: it is the
+            // only retryable signal that this attempt never reached the session.
+            if (outcome?.durable !== false)
+                await rm(join(runs, name), { force: true }).catch(() => { });
+            continue;
+        }
+        const pid = typeof claim.pid === 'number' ? claim.pid : undefined;
+        if (await claimOwnerIsLive(pid, claim.startedAt))
+            return true;
+        const outcome = await rememberCrashedClaim(directory, claim);
+        if (outcome?.durable !== false)
+            await rm(join(runs, name), { force: true }).catch(() => { });
+    }
+    return false;
+}
+/**
+ * Whether an armed wake still names this session from any engine.
+ *
+ * A wake lives in the registry of the engine that armed it, and every engine sharing the
+ * installation runs a reaper pass over the same store: asked of its own registry alone, one
+ * engine's pass would file away a session another engine still owes a prompt. Each arm wrote a
+ * claim, so the claims are the answer. A claim whose owner is live holds the session; a claim
+ * whose owner is gone is swept here, because the wake it named was a promise its process held and
+ * nothing will deliver it now. A claim that cannot be read might name a live wake, so it holds
+ * the session too.
+ */
+export async function sessionHasArmedWake(directory, sessionId) {
+    const runs = runRecordsDirectory(directory);
+    let names;
+    try {
+        names = await readdir(runs);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    let armed = false;
+    for (const name of names) {
+        if (!name.startsWith(`${sessionId}.`) || !name.endsWith('.wake-claim'))
+            continue;
+        let claim;
+        try {
+            claim = JSON.parse(await readFile(join(runs, name), 'utf8'));
+        }
+        catch {
+            armed = true;
+            continue;
+        }
+        const pid = typeof claim.pid === 'number' ? claim.pid : undefined;
+        if (await claimOwnerIsLive(pid, claim.startedAt)) {
+            armed = true;
+            continue;
+        }
+        // The owner is gone, and with it the wake: the claim it left cannot hold the session against
+        // every later pass, so the read that proved it dead clears it.
+        await rm(join(runs, name), { force: true }).catch(() => { });
+    }
+    return armed;
+}
+/** The path of one wake's claim, beside the open-run claims it is read with. */
+function wakeClaimPath(directory, sessionId, timerId) {
+    if (!validSessionFile(sessionId) || !validSessionFile(timerId)) {
+        throw new Error('A wake claim needs a session identity and a timer identity');
+    }
+    return join(runRecordsDirectory(directory), `${sessionId}.${timerId}.wake-claim`);
+}
+/**
+ * Record that this engine armed a wake for a session.
+ *
+ * The wake itself lives in this process's registry, so a reaper pass in another engine cannot see
+ * it there. The claim is what makes it visible across the engines that share the installation: one
+ * small file per wake, carrying the writing process's identity, read by `sessionHasArmedWake`. Best
+ * effort — a claim that fails to land leaves the wake invisible to a foreign pass until its
+ * delivery lands and reverts the filing, the way the run that armed it would have.
+ */
+export async function writeWakeClaim(directory, sessionId, timerId) {
+    const body = { sessionId, timerId, pid: process.pid, claimedAt: new Date().toISOString(), startedAt: processStartedAt(), nonce: PROCESS_NONCE };
+    // A home with no runs yet has no directory for the claim: the write lands beside the open-run claims.
+    await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 }).catch(() => { });
+    await writeSessionSnapshot(wakeClaimPath(directory, sessionId, timerId), JSON.stringify(body) + '\n');
+}
+/** Drop one wake's claim: the wake was delivered, spent, or canceled by the engine that armed it. */
+export async function clearWakeClaim(directory, sessionId, timerId) {
+    if (!validSessionFile(sessionId) || !validSessionFile(timerId))
+        return;
+    await rm(wakeClaimPath(directory, sessionId, timerId), { force: true }).catch(() => { });
+}
+/**
+ * Drop every claim a session's wakes hold, when the wakes go with the session they were armed for.
+ *
+ * Deleting a session clears its wakes with the record; the claims have to go with them, or claims
+ * naming a session that no longer exists would outlive the session that could ever clear them.
+ * Only claims naming this session are removed: another session's wakes are nobody else's to drop.
+ */
+export async function clearWakeClaims(directory, sessionId) {
+    if (!validSessionFile(sessionId))
+        return;
+    const runs = runRecordsDirectory(directory);
+    let names;
+    try {
+        names = await readdir(runs);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    for (const name of names) {
+        if (!name.startsWith(`${sessionId}.`) || !name.endsWith('.wake-claim'))
+            continue;
+        await rm(join(runs, name), { force: true }).catch(() => { });
+    }
+}
+/**
+ * Whether this claim's own run record closed after the claim was made, which makes the claim failed
+ * cleanup rather than live work.
+ *
+ * A run finalizes by rewriting its result record and then removing its claim. If that removal fails — a
+ * scanner holding the file on Windows is enough, and the removal is deliberately best-effort so a
+ * transient lock cannot abort a finished run — the leftover goes on naming its owner, and nothing else
+ * sweeps it: the startup repair walks only records that are still `running`, so a claim whose record is
+ * closed survives every later restart and keeps `sessionHasOpenRun` answering `busy` for this session
+ * until the process it names exits. Comparing the two stamps is what tells this apart from the claim of
+ * a run in flight: a resume reuses its attempt's run id, so a record that closed *before* this claim was
+ * written belongs to that earlier attempt and says nothing about this one. A record that is absent,
+ * unreadable, or without a closing stamp proves nothing, and the claim stands — the conservative
+ * direction, because clearing a live claim is what lets a mutation land on a session a run still owns.
+ */
+async function claimOutlivedItsRun(directory, claim) {
+    const runId = typeof claim.runId === 'string' ? claim.runId : undefined;
+    if (runId === undefined)
+        return false;
+    const claimedAt = typeof claim.claimedAt === 'string' ? Date.parse(claim.claimedAt) : Number.NaN;
+    if (!Number.isFinite(claimedAt))
+        return false;
+    let record;
+    try {
+        record = JSON.parse(await readFile(runRecordPath(directory, runId, 'json'), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (!record || typeof record !== 'object')
+        return false;
+    const closed = record;
+    if (closed.status === undefined || closed.status === 'running')
+        return false;
+    const endedAt = typeof closed.endedAt === 'string' ? Date.parse(closed.endedAt) : Number.NaN;
+    return Number.isFinite(endedAt) && endedAt > claimedAt;
+}
+/**
+ * Whether the process an open-run claim names is the one that wrote it.
+ *
+ * `isPidAlive` alone is not an identity: the OS reuses numbers, so a claim whose engine crashed
+ * can come to name an unrelated process that inherited the pid, and treating that as the owner
+ * would hold the session busy — refusing every rename, archive, and delete — for as long as the
+ * impostor lives. The start time the owner recorded when it claimed the run is corroborated
+ * against the one the platform reports for that pid, which is how `inspectClaim` judges a resume
+ * claim. A claim written before that field existed, and a platform that cannot report a start
+ * time, fall back to pid liveness: the conservative direction, because a live owner read as
+ * stale is what lets a rail mutation land while a run still owns the session.
+ */
+async function claimOwnerIsLive(pid, startedAt) {
+    if (pid === undefined || !Number.isSafeInteger(pid) || pid < 1)
+        return true;
+    if (!isPidAlive(pid))
+        return false;
+    const claimed = typeof startedAt === 'string' ? Date.parse(startedAt) : Number.NaN;
+    if (!Number.isFinite(claimed))
+        return true;
+    // Our own start time is known without a probe: the common case is this process's own run.
+    const actual = pid === process.pid ? Date.parse(processStartedAt()) : await processStartedAtFor(pid);
+    return actual === undefined || Math.abs(actual - claimed) <= PROCESS_START_TOLERANCE_MS;
+}
+/** The pre-index answer: read the result records themselves. Only the fallback paths reach it. */
+async function scanRunsForOpenRun(directory, sessionId, ignoreRunId) {
+    const runs = runRecordsDirectory(directory);
+    let names;
+    try {
+        names = await readdir(runs);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json') || name.endsWith('.checkpoint.json'))
+            continue;
+        let value;
+        try {
+            value = JSON.parse(await readFile(join(runs, name), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!value || typeof value !== 'object' || value.status !== 'running' || value.sessionId !== sessionId)
+            continue;
+        // The caller's own in-flight run is excused from the answer, exactly as in the claim index.
+        if (ignoreRunId !== undefined && (value.id === ignoreRunId || name === `${ignoreRunId}.json`))
+            continue;
+        const pid = typeof value.pid === 'number' ? value.pid : undefined;
+        if (pid === undefined || isPidAlive(pid))
+            return true;
+    }
+    return false;
+}
+/** Whether a value is the plain object a completion's `output` is declared to be. */
+const plainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Whether a value is the `{ type, ref }` pair a completion's artifact reference is declared to be. */
+function isArtifactRef(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const ref = value;
+    return typeof ref.type === 'string' && typeof ref.ref === 'string';
+}
+/**
+ * Bring every session's view of unfinished attempts in line with the run records.
+ *
+ * A marker turn whose record finalized means the final turn never reached the session file — the
+ * finalizer saved the record and the session save itself failed — so the marker takes the record's
+ * own account of the attempt. A marker with no record at all is a crash between the two writes: it
+ * becomes interrupted, and with a known run identity an interrupted record is synthesized so the
+ * Runs view shows the attempt instead of only the transcript. A marker whose record is still open
+ * under a live pid is real in-flight work and stays.
+ */
+async function upgradeSessionMarkers(directory, only) {
+    const sessions = join(directory, 'sessions');
+    let names;
+    try {
+        names = await readdir(sessions);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 0;
+        throw error;
+    }
+    let markers = 0;
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        if (only !== undefined && name !== `${only}.json`)
+            continue;
+        try {
+            const session = JSON.parse(await readFile(join(sessions, name), 'utf8'));
+            if (!session || typeof session !== 'object' || typeof session.id !== 'string' || session.id !== name.slice(0, -'.json'.length))
+                continue;
+            let changed = 0;
+            const usageFolded = new Set();
+            for (const key of ['history', 'contextHistory']) {
+                const turns = session[key];
+                if (!Array.isArray(turns))
+                    continue;
+                for (const turn of turns) {
+                    const completion = turn?.completion;
+                    if (!completion || typeof completion !== 'object')
+                        continue;
+                    if (completion.status !== 'running' && completion.summary !== RUNNING_TURN_SUMMARY)
+                        continue;
+                    const runId = turn.runId;
+                    const known = typeof runId === 'string' && /^[\w-]{1,64}$/.test(runId);
+                    const record = known ? await readRunRecord(directory, runId) : undefined;
+                    if (record && record.status === 'running') {
+                        if (typeof record.pid !== 'number' || isPidAlive(record.pid))
+                            continue;
+                        // `markOpenRunsInterrupted` already landed, but a record this pass cannot rewrite (a
+                        // locked file on Windows) must not leave the transcript claiming work in flight.
+                    }
+                    if (record && record.status !== 'running' && typeof record.status === 'string') {
+                        // The attempt finished; only the session never heard how — or what it produced. The
+                        // finalization persisted the whole completion (tests, outcome, artifacts) even when its
+                        // session save failed, so the repaired turn takes it whole rather than only its summary.
+                        const finalized = (record.completion && typeof record.completion === 'object' && !Array.isArray(record.completion))
+                            ? { ...record.completion }
+                            : undefined;
+                        if (finalized) {
+                            if (record.status === 'succeeded') {
+                                // A successful run: the turn is a normal completed turn, and the desktop labels any
+                                // present non-running status as a stopped one, so it carries the record's completion
+                                // with no status at all.
+                                delete finalized.status;
+                            }
+                            else {
+                                finalized.status = record.status;
+                            }
+                            // The saved session must stay loadable and renderable: session validation keeps only a
+                            // string summary and a string-array tests list, and clients render the outcome beside
+                            // them, so the fields a hand-edited or damaged record gets wrong are repaired to their
+                            // declared shapes rather than written through verbatim. `output` and `artifacts` are not
+                            // drawn but are serialized into the next run's model context, so they are held to their
+                            // shapes too; a field that cannot be repaired is dropped.
+                            if (typeof finalized.summary !== 'string' || finalized.summary.length === 0) {
+                                finalized.summary = record.status === 'succeeded'
+                                    ? (typeof completion.summary === 'string' && completion.summary.length > 0 ? completion.summary : summaryForStoppedRecord(record))
+                                    : summaryForStoppedRecord(record);
+                            }
+                            if (!Array.isArray(finalized.tests) || !finalized.tests.every((test) => typeof test === 'string'))
+                                finalized.tests = [];
+                            // A React child must stringify: an object where the outcome belongs throws while the
+                            // transcript renders, which would make the repaired session unusable in the desktop.
+                            if (typeof finalized.outcome !== 'string')
+                                delete finalized.outcome;
+                            if (!plainObject(finalized.output))
+                                delete finalized.output;
+                            if (!Array.isArray(finalized.artifacts) || !finalized.artifacts.every(isArtifactRef))
+                                delete finalized.artifacts;
+                            turn.completion = finalized;
+                        }
+                        else if (record.status === 'succeeded') {
+                            delete completion.status;
+                        }
+                        else {
+                            completion.summary = summaryForStoppedRecord(record);
+                            completion.status = record.status;
+                        }
+                        // The session totals are the pre-run snapshot the marker was saved with; the attempt's
+                        // usage lives only in the record. Fold it once per file even when the marker turn sits
+                        // in both history arrays, or the recovery would count the same run twice.
+                        if (known && !usageFolded.has(runId)) {
+                            usageFolded.add(runId);
+                            foldRecordUsage(session, record.usage);
+                        }
+                    }
+                    else {
+                        completion.summary = INTERRUPTED_TURN_SUMMARY;
+                        completion.status = 'interrupted';
+                        if (known)
+                            await synthesizeInterruptedRecord(directory, runId, typeof session.id === 'string' && validSessionFile(session.id) ? session.id : undefined);
+                    }
+                    changed += 1;
+                }
+            }
+            if (!changed)
+                continue;
+            await writeSessionSnapshot(join(sessions, name), JSON.stringify(session) + '\n');
+            markers += changed;
+        }
+        catch { /* One damaged session must not stop the sweep. */ }
+    }
+    return markers;
+}
+/**
+ * Bring one session's unfinished turns in line with the run records.
+ *
+ * The same repair the startup pass makes, for one session: a run whose final session save failed
+ * leaves its turn marked running, and a long-lived server would keep it that way until it was
+ * restarted. The attempt's own record says how it ended, so the turn takes that account of it.
+ */
+export async function repairSessionMarkers(directory, sessionId) {
+    return await upgradeSessionMarkers(directory, sessionId);
+}
+/**
+ * Add a finished run's usage to the session totals during recovery.
+ *
+ * The saved session holds the totals as they were when the marker was written — before the run's
+ * model calls — and after a failed final save the attempt's usage exists only on its record. The
+ * fold matches the live one: the three required counters always add, a cache counter the provider
+ * reported (even as zero) adds, and an unreported one stays absent.
+ */
+function foldRecordUsage(session, usage) {
+    if (!usage || typeof usage !== 'object' || Array.isArray(usage))
+        return;
+    const delta = usage;
+    const current = (session.usage && typeof session.usage === 'object' && !Array.isArray(session.usage))
+        ? session.usage
+        : {};
+    const count = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+    for (const key of ['requests', 'inputTokens', 'outputTokens'])
+        current[key] = count(current[key]) + count(delta[key]);
+    for (const key of ['cacheRead', 'cacheWrite']) {
+        if (typeof delta[key] === 'number' && Number.isFinite(delta[key]))
+            current[key] = count(current[key]) + delta[key];
+    }
+    session.usage = current;
+}
+async function readRunRecord(directory, runId) {
+    try {
+        return JSON.parse(await readFile(runRecordPath(directory, runId, 'json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The record a crashed run never wrote, so the attempt is listable and classifiable. */
+async function synthesizeInterruptedRecord(directory, runId, sessionId) {
+    if (await readRunRecord(directory, runId) !== undefined)
+        return;
+    // The crash can land before anything ever created `runs/`: the session marker is written first,
+    // and a home whose only run never opened a record has no directory to synthesize into.
+    await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+    let startedAt = new Date().toISOString();
+    try {
+        const first = (await readFile(runRecordPath(directory, runId, 'jsonl'), 'utf8')).split('\n', 1)[0];
+        const time = JSON.parse(first).time;
+        if (typeof time === 'string')
+            startedAt = time;
+    }
+    catch { /* No journal: the record starts its life at recovery time. */ }
+    try {
+        await writeSessionSnapshot(runRecordPath(directory, runId, 'json'), JSON.stringify({
+            id: runId, status: 'interrupted', reason: 'the engine stopped before the run was recorded', startedAt,
+            ...(sessionId === undefined ? {} : { sessionId }), usage: { inputTokens: 0, outputTokens: 0, requests: 0 }, toolCalls: 0,
+        }, null, 2) + '\n');
+    }
+    catch { /* A record that cannot be written must not fail the sweep. */ }
+}
+/**
+ * The path a run's persisted record lives at.
+ *
+ * The run identity reaches this path from runtime events, where it is typed `unknown`, so the
+ * alphabet is checked here at the sink rather than trusted from every caller. The identity is
+ * always a UUID, and the guard admits only `[A-Za-z0-9_-]` -- the same alphabet `ArtifactStore`
+ * uses for its own run-scoped directory. That rejects every spelling that could leave `runs/`:
+ * `.` and `..` segments (the dot is not in the alphabet, so `..` is not merely resolved away but
+ * refused), `/` and `\` separators, an absolute path, and a Windows drive-relative or
+ * alternate-data-stream name (`:`).
+ * @param directory - the installation directory holding `runs/`.
+ * @param runId - the run identity, typically a generated UUID.
+ * @param extension - which record per run this path names: the result, the journal, or the
+ *   checkpoint the resume work leaves behind until the run succeeds.
+ * @returns the absolute or installation-relative path of the record.
+ */
+export function runRecordPath(directory, runId, extension) {
+    // The alphabet alone is not the whole test: `$` also matches just before a trailing newline, so
+    // `/^…$/` would admit "run\n" as readily as "run". Requiring the value to survive `trim()`
+    // unchanged closes that and rejects padded input at the same time.
+    if (typeof runId !== 'string' || runId.trim() !== runId || !/^[\w-]{1,64}$/.test(runId)) {
+        // The rejected value is deliberately not echoed: it is untrusted text, and an error message
+        // is rendered to a terminal.
+        throw new Error('A persisted run record needs a run identity of up to 64 word characters');
+    }
+    return join(runRecordsDirectory(directory), `${runId}.${extension}`);
+}
+/**
+ * Record that a run's journal stopped accepting events, durably and separately from the sink that
+ * failed.
+ *
+ * The journal is rewritten for every runtime event, and the engine deliberately keeps running when
+ * one append fails (a full disk must not kill the user's work). What it must not keep is the
+ * pretence that the file is a complete account: the lines after the failure are present, so the
+ * gap is invisible to a reader — a crashed attempt would replay to a position missing whichever
+ * completion the failure ate, and resume by repeating it. This marker is the failure's own record
+ * (best effort: if even it cannot be written, the resume read of the record's flag is what stands),
+ * and `journalWriteFailed` is what a resume consults before trusting the lineage.
+ */
+export async function noteJournalWriteFailure(directory, runId, detail) {
+    try {
+        await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+        await appendFile(runRecordPath(directory, runId, 'journal-error'), `${new Date().toISOString()}\t${detail.replace(/[\r\n]+/g, ' ')}\n`, { mode: 0o600 });
+    }
+    catch { /* the marker is best effort; the record's own flag covers a write that failed here */ }
+}
+/**
+ * Whether a run's journal is known to be incomplete — the marker the sink left, or the flag the
+ * attempt's result record carries. An attempt whose journal is incomplete is never a resume source:
+ * replaying it would reconstruct a position whose missing events repeat completed work.
+ */
+export async function journalWriteFailed(directory, runId) {
+    try {
+        await stat(runRecordPath(directory, runId, 'journal-error'));
+        return true;
+    }
+    catch { /* no marker: the record flag is the only other account */ }
+    try {
+        const value = JSON.parse(await readFile(runRecordPath(directory, runId, 'json'), 'utf8'));
+        return value.journalIntegrity === 'failed';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Record that a run's checkpoints stopped being written, durably and separately from the sink
+ * that failed.
+ *
+ * A checkpoint is the conversation a resume re-enters a node with: the node's own messages at the
+ * moment it stopped. A write that failed leaves that conversation unwritten, so a resume would
+ * re-enter the node from its opening task and repeat the tool calls it had already made — the
+ * same harm a hole in the journal does, reached through a different file. The engine keeps the
+ * run working (a full disk must not kill the user's work), but the attempt stops being a resume
+ * source. This marker is the failure's own record (best effort: if even it cannot be written, the
+ * resume read of the record's flag is what stands), and `checkpointWriteFailed` is what a resume
+ * consults before trusting the lineage.
+ */
+export async function noteCheckpointWriteFailure(directory, runId, detail) {
+    try {
+        await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+        await appendFile(runRecordPath(directory, runId, 'checkpoint-error'), `${new Date().toISOString()}\t${detail.replace(/[\r\n]+/g, ' ')}\n`, { mode: 0o600 });
+    }
+    catch { /* the marker is best effort; the record's own flag covers a write that failed here */ }
+}
+/**
+ * Whether a run's checkpoints are known to be incomplete — the marker the sink left, or the flag
+ * the attempt's result record carries. An attempt whose checkpoint could not be written is never
+ * a resume source: the resume would re-enter the node from its opening task and repeat the work
+ * that node had already done.
+ */
+export async function checkpointWriteFailed(directory, runId) {
+    try {
+        await stat(runRecordPath(directory, runId, 'checkpoint-error'));
+        return true;
+    }
+    catch { /* no marker: the record flag is the only other account */ }
+    try {
+        const value = JSON.parse(await readFile(runRecordPath(directory, runId, 'json'), 'utf8'));
+        return value.checkpointIntegrity === 'failed';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The checkpoint file for one node of a run: `<runId>.checkpoint.<node-key>`.
+ *
+ * Parallel branches checkpoint concurrently, and one shared file per run meant every branch's
+ * write overwrote the others' — a crash kept only whichever conversation landed last. Each node
+ * owns a file instead, so every unfinished branch survives. Node ids carry arbitrary characters,
+ * so the name gets a sanitized prefix for debuggability plus a hash of the exact id for
+ * uniqueness: two ids that sanitize to the same prefix still get different files.
+ */
+function runCheckpointPath(directory, runId, nodeId) {
+    const slug = nodeId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 48);
+    let hash = 2166136261;
+    for (let i = 0; i < nodeId.length; i += 1) {
+        hash ^= nodeId.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return `${runRecordPath(directory, runId, 'checkpoint')}.${slug}-${(hash >>> 0).toString(36)}`;
+}
+/**
+ * Persist the in-flight conversation of the node a run is working on.
+ *
+ * The write is atomic (a staged rename, the same discipline as every durable record in this
+ * directory) at mode 0600: the file carries the node's full message history — including tool
+ * outputs — so it is as sensitive as the run journal, and a crash mid-write must never leave a
+ * half-file a resume would read back. A new snapshot replaces the last; the runner already
+ * sanitizes an interrupted conversation before publishing its checkpoint (stub tool messages are
+ * marked as not replayed), so whatever the callback handed over is what belongs on disk.
+ */
+export async function writeRunCheckpoint(directory, runId, checkpoint) {
+    await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+    await writeSessionSnapshot(runCheckpointPath(directory, runId, checkpoint.nodeId), JSON.stringify(checkpoint) + '\n');
+}
+/**
+ * Read back one node's checkpoint, or nothing when there is no usable one.
+ *
+ * Missing and unreadable both mean the same thing to the caller: resume without the prior
+ * conversation (the safe restart the runner falls back to). Shape validation is deliberately
+ * shallow — a checkpoint from an incompatible build would carry the wrong state fields, and the
+ * node re-running from scratch is safer than a seeded conversation whose counters disagree with
+ * the graph the run is being replayed onto.
+ *
+ * One field is rebuilt rather than trusted: the tool-failure tracker is a class whose behavior
+ * (and whose Map) JSON does not carry, so a resumed node gets a fresh one. Losing the repeated-
+ * failure strike counts is the conservative direction — the worst case is one more retry before
+ * the tracker strikes out again, not a crash on a state object without its methods.
+ */
+export async function readRunCheckpoint(directory, runId, nodeId) {
+    let raw;
+    try {
+        raw = await readFile(runCheckpointPath(directory, runId, nodeId), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    return parseRunCheckpoint(raw);
+}
+/**
+ * Read every checkpoint the run kept — one file per node, plus the legacy single-file shape an
+ * older build may have left behind. Unreadable or invalid files are skipped individually: a
+ * damaged branch costs that branch its conversation, nothing more.
+ */
+export async function readRunCheckpoints(directory, runId) {
+    const root = runRecordsDirectory(directory);
+    const prefix = `${runId}.checkpoint`;
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const checkpoints = [];
+    for (const name of names.sort()) {
+        // The bare `<runId>.checkpoint` is the pre-per-node shape; a per-node file is
+        // `<runId>.checkpoint.<node-key>`. Nothing else the runs directory holds matches either.
+        if (name !== prefix && !name.startsWith(`${prefix}.`))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(root, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const checkpoint = parseRunCheckpoint(raw);
+        if (checkpoint)
+            checkpoints.push(checkpoint);
+    }
+    return checkpoints;
+}
+/**
+ * Rebuild every tool-failure tracker a persisted continuation state carries.
+ *
+ * The tracker is a class JSON cannot round-trip, so its strike counts live as plain numbers in the
+ * file and its methods do not. A modified agent's state nests one continuation per copy
+ * (`state.copies[i].state`), and the runtime reaches into those on the resumed copy's first tool
+ * result — where a plain object has no `record`, so the failure lands after the tool already
+ * executed and the effect can be repeated by the next resume. The rebuild is recursive for the same
+ * reason: whatever state shape nests further, every tracker in it has to come back as a tracker.
+ */
+function reviveFailures(state) {
+    const revived = { ...state, failures: new ToolFailureTracker() };
+    if (Array.isArray(state.copies))
+        revived.copies = state.copies.map(copy => ({ ...copy, state: reviveFailures(copy.state) }));
+    return revived;
+}
+const CHECKPOINT_MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool']);
+function parseRunCheckpoint(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (!value || typeof value.nodeId !== 'string' || !Array.isArray(value.messages)
+            || typeof value.state !== 'object' || value.state === null
+            || typeof value.state.directionRevision !== 'number'
+            || typeof value.revision !== 'number' || typeof value.savedAt !== 'string')
+            return undefined;
+        // A checkpoint whose conversation is not a conversation is worse than no checkpoint: the
+        // resumed node REPLACES its freshly built system prompt, history and task with this array, so
+        // an empty or malformed one would run the node with no task at all. Anything the current
+        // runtime could not continue reads as absent — the compatibility contract is a fresh node.
+        if (value.messages.length === 0 || value.messages.some(message => !message || typeof message !== 'object'
+            || !CHECKPOINT_MESSAGE_ROLES.has(message.role)
+            || typeof message.content !== 'string'))
+            return undefined;
+        // The continuation counters drive the resumed run's limits (iterations, repairs, todo calls);
+        // a checkpoint missing them is from a build whose state shape this reader cannot trust.
+        if (![value.state.iterations, value.state.repairs, value.state.todoCalls, value.state.directionRevision]
+            .every(count => typeof count === 'number' && Number.isFinite(count)))
+            return undefined;
+        // The model identity stamp is optional: garbage there degrades to "no stamp" (no predecessor-
+        // conversation restore for a pending successor) rather than refusing a sound checkpoint file.
+        if (typeof value.provider !== 'string')
+            delete value.provider;
+        if (typeof value.model !== 'string')
+            delete value.model;
+        // The delivery marker is optional and self-describing: garbage degrades to "no marker", which
+        // only means the text fallback is used, never that a sound checkpoint is refused.
+        if (Array.isArray(value.steeringDelivered))
+            value.steeringDelivered = value.steeringDelivered.filter(id => typeof id === 'string');
+        else
+            delete value.steeringDelivered;
+        return { ...value, state: reviveFailures(value.state) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Discard a run's checkpoints — every per-node file and the legacy single file. The terminal
+ * paths call this once the attempt has finished, so durable checkpoints exist only for attempts
+ * a resume can actually pick up again.
+ */
+export async function removeRunCheckpoint(directory, runId) {
+    const root = runRecordsDirectory(directory);
+    const prefix = `${runId}.checkpoint`;
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name !== prefix && !name.startsWith(`${prefix}.`))
+            continue;
+        await rm(join(root, name), { force: true }).catch(() => { });
+    }
+}
+/**
+ * Read a claim where it stands.
+ *
+ * An ordinary read never disturbs the lock path, so a live holder cannot lose its claim merely to
+ * being inspected. The identity comes back with the content — and is deliberately read BEFORE the
+ * content, so a file replaced underneath the read answers with the identity of the newer file
+ * while the caller acts on the older content: a reclaimer re-reads both under its ticket, and that
+ * mismatch is what refuses the reclamation instead of letting it delete a claim it never judged.
+ * An unreadable file proves no live holder (it is stale); the holder's own pid is stale too,
+ * because a crashed process's pid can be recycled to this one.
+ *
+ * A live pid is corroborated against the start time the claim recorded before it counts as a live
+ * holder: a pid the OS handed to an unrelated process that started later cannot be the claim's
+ * author, and treating it as one would refuse that attempt's resume for as long as the impostor
+ * runs. Where the platform cannot report a start time, the pid stands on its own — the conservative
+ * direction, since a live holder treated as stale is what lets two engines resume at once.
+ */
+async function inspectClaim(path) {
+    let identity;
+    try {
+        const info = await stat(path);
+        identity = { dev: info.dev, ino: info.ino };
+    }
+    catch {
+        return undefined;
+    }
+    let pid;
+    let startedAt;
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        if (typeof value.pid === 'number')
+            pid = value.pid;
+        if (typeof value.startedAt === 'string')
+            startedAt = Date.parse(value.startedAt);
+    }
+    catch { /* an unreadable claim proves no live holder: it is stale */ }
+    let live = pid !== undefined && pid !== process.pid && isPidAlive(pid);
+    if (live && startedAt !== undefined && Number.isFinite(startedAt)) {
+        const actual = await processStartedAtFor(pid);
+        if (actual !== undefined && Math.abs(actual - startedAt) > PROCESS_START_TOLERANCE_MS)
+            live = false;
+    }
+    return { ...identity, live };
+}
+/**
+ * Take the exclusive right to reclaim a stale claim, or refuse while another engine holds it.
+ *
+ * Reclaiming means deleting a file, and no filesystem offers a conditional delete: two processes
+ * that both judge the same stale file can both proceed to remove it, and the one that removes
+ * second can remove the claim the other has already created and started resuming under — leaving
+ * two live resumers. The ticket turns the delete into a serialized step (taken by the same
+ * create-exclusive link the claim itself uses), so only one reclaimer at a time may remove
+ * anything, and every removal is additionally gated on re-reading the exact file it judged.
+ *
+ * A ticket left by a reclaimer that died mid-reclaim is taken over the way a stale claim is: its
+ * holder is read where it stands, and only a dead one is discarded. Two processes taking over that
+ * same dead ticket does not reopen the hole: the ticket guards only the delete, and the delete is
+ * still conditional on the identity re-read, so a doubled ticket can at worst make both reclaimers
+ * refuse.
+ *
+ * @returns whether this process holds the ticket, in which case the caller must remove it.
+ */
+async function takeReclaimTicket(ticket) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const temp = `${ticket}.tmp-${process.pid}-${randomUUID()}`;
+        await writeFile(temp, JSON.stringify({ pid: process.pid, claimedAt: new Date().toISOString(), startedAt: processStartedAt() }) + '\n', { mode: 0o600 });
+        try {
+            await link(temp, ticket);
+            await rm(temp, { force: true });
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            await rm(temp, { force: true }).catch(() => { });
+        }
+        const held = await inspectClaim(ticket);
+        if (held === undefined)
+            continue;
+        // Another engine is reclaiming this run right now: refuse rather than removing anything it
+        // may be in the middle of. Its own refusal-or-claim answer arrives for the caller to retry.
+        if (held.live)
+            return false;
+        await rm(ticket, { force: true }).catch(() => { });
+    }
+    return false;
+}
+/**
+ * Take (or refuse) the cross-process claim that this run id is being resumed.
+ *
+ * Two engines sharing one home can both be asked to resume the same stopped attempt, and the
+ * per-process start guard cannot see the other one. The claim is a create-exclusive file: the
+ * winner proceeds, and a file left by a process that is gone is stale and gets reclaimed. It is
+ * deliberately a separate name from every record the Runs view scans, and it names the original
+ * attempt — the thing two resumers would collide over.
+ *
+ * Reclamation may not be "read the file, then unlink the path", nor "rename whatever is in the
+ * way, then read it": the first deletes a claim another engine may have created in between, and
+ * the second vacates the canonical path — unlocking a live holder's claim for the rename window,
+ * so a third engine linking into it takes the name while the original holder still believes it
+ * owns it. What survives both is refusing to act on anything but verified evidence: the claim is
+ * read in place (which never disturbs it), the reclamation takes the ticket above, the file is
+ * re-read UNDER the ticket so a claim replaced in between refuses instead of being moved, and the
+ * moved file's identity is checked before it is discarded. A live claim is never vacated, and the
+ * only file ever deleted here is one this process read as stale twice and matched by identity.
+ *
+ * @returns whether the claim was taken; false means a live process holds it, or another engine is
+ *   reclaiming it right now.
+ */
+export async function claimRunResume(directory, runId) {
+    await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+    return takeStaleableClaim(runRecordPath(directory, runId, 'claim'));
+}
+/**
+ * The generic cross-process exclusive claim over one path.
+ *
+ * One protocol serves every exclusive claim in this directory: the resume claim above and the
+ * per-session mutation lock below. Create-exclusive first; a file left by a dead process is
+ * reclaimed only under the reclaim ticket and only when the re-read under the ticket is still the
+ * exact file judged stale.
+ */
+async function takeStaleableClaim(path) {
+    const ticket = `${path}.reclaim`;
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        const temp = `${path}.tmp-${process.pid}-${randomUUID()}`;
+        await writeFile(temp, JSON.stringify({ pid: process.pid, claimedAt: new Date().toISOString(), startedAt: processStartedAt() }) + '\n', { mode: 0o600 });
+        try {
+            await link(temp, path);
+            await rm(temp, { force: true });
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            await rm(temp, { force: true }).catch(() => { });
+        }
+        // A file is in the way. A live holder answers refusal before anything touches the path.
+        const judged = await inspectClaim(path);
+        if (judged === undefined)
+            continue;
+        if (judged.live)
+            return false;
+        if (!await takeReclaimTicket(ticket))
+            return false;
+        try {
+            // Re-read under the ticket: between the judgement above and here another engine may have
+            // reclaimed the claim and started resuming under its own file. Only a file that is still
+            // stale AND still the exact file judged is acted on; anything else is left untouched.
+            const current = await inspectClaim(path);
+            if (current === undefined || current.live || current.dev !== judged.dev || current.ino !== judged.ino)
+                continue;
+            const aside = `${path}.stale-${process.pid}-${randomUUID()}`;
+            try {
+                await rename(path, aside);
+            }
+            catch (error) {
+                // Gone already (a competing reclaim took it): retry the create against the new state.
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            const moved = await inspectClaim(aside);
+            if (moved === undefined || moved.dev !== judged.dev || moved.ino !== judged.ino) {
+                // A file this process never judged stale — an out-of-protocol writer (an older build
+                // sharing this home) replaced the claim between the re-read and the rename. It is put back
+                // before anything else happens: an unverified file is never deleted. If a third contender
+                // took the name in the meantime the displaced file stays under its aside name, intact,
+                // rather than being destroyed to make room for this attempt.
+                try {
+                    await link(aside, path);
+                    await rm(aside, { force: true });
+                }
+                catch { /* the canonical name is taken again; the displaced claim survives under its own name */ }
+                return false;
+            }
+            await rm(aside, { force: true });
+        }
+        finally {
+            await rm(ticket, { force: true }).catch(() => { });
+        }
+        // The verified stale file is gone. The next pass takes the name with the same create-exclusive
+        // link: a fresh contender may win it, and then its live claim is what refuses this resume.
+    }
+    return false;
+}
+/**
+ * Give up a resume claim taken by a start that never reached its run — the claim itself, and the
+ * reclaim ticket this process could be holding. A live reclaimer's ticket is left alone: it is
+ * what serializes that engine's delete, and removing it early would hand the serialization to a
+ * third contender mid-reclaim.
+ */
+export async function releaseRunResumeClaim(directory, runId) {
+    const path = runRecordPath(directory, runId, 'claim');
+    await rm(path, { force: true }).catch(() => { });
+    const held = await inspectClaim(`${path}.reclaim`);
+    if (held !== undefined && !held.live)
+        await rm(`${path}.reclaim`, { force: true }).catch(() => { });
+}
+/** Thrown when a session mutation lock is held elsewhere and does not free up within the wait. */
+export class SessionMutationLockHeldError extends Error {
+    constructor(sessionId) {
+        super(`The session ${sessionId} is being changed by another writer`);
+        this.name = 'SessionMutationLockHeldError';
+    }
+}
+/**
+ * The in-process turnstiles, keyed by directory and session.
+ *
+ * A create-exclusive claim serializes processes, not the two awaits inside one process: two
+ * concurrent requests of the same engine would each try to claim, and a holder's claim carries this
+ * very pid, which `inspectClaim` must read as stale (a recycled pid cannot be trusted as ours). So
+ * same-process contenders queue here and only the queue's head ever touches the claim.
+ */
+const mutationTurns = new Map();
+/**
+ * Serialize a session's cross-process read-modify-write mutation.
+ *
+ * Every rename, archive, and delete reads a session record, edits fields, and saves it back. Two
+ * windows doing that to one session can interleave — each save overwrites the whole record, so one
+ * loses the other's field, and a save landing after a delete recreates the session the user
+ * removed. The answer is one lock per session, held across exactly that window: take it before the
+ * busy check, do the check, the fresh re-read, and the save inside it, and release. A fresh read
+ * under the lock is what makes two serialized mutations additive rather than lossy: each sees what
+ * the last one wrote.
+ *
+ * The lock is the same claim protocol the resume claim uses — create-exclusive, with verified
+ * reclamation of a file left by a dead process — so a holder that dies cannot strand the session:
+ * the next contender reclaims and proceeds. It also carries an in-process turnstile, because the
+ * app-server can have two concurrent requests for one session, and a request must never judge its
+ * own process's live claim stale.
+ *
+ * @returns the release function. Throws `SessionMutationLockHeldError` when another writer keeps
+ *   the lock past the wait — the caller owes the user a busy error, not a mutation.
+ */
+export async function acquireSessionMutationLock(directory, sessionId, options = {}) {
+    const turnKey = `${resolve(directory)}\u0000${sessionId}`;
+    const previous = mutationTurns.get(turnKey) ?? Promise.resolve();
+    let releaseTurn = () => { };
+    const turn = new Promise(done => { releaseTurn = done; });
+    mutationTurns.set(turnKey, turn);
+    await previous.catch(() => { });
+    let released = false;
+    const finish = () => {
+        if (released)
+            return;
+        released = true;
+        if (mutationTurns.get(turnKey) === turn)
+            mutationTurns.delete(turnKey);
+        releaseTurn();
+    };
+    // A path-unsafe identity — never a real session, which is a UUID — cannot name a claim file. The
+    // turnstile above is the only serialization such an id gets; the mutation it guards is itself
+    // unreachable through the validated paths that construct these ids.
+    let path;
+    try {
+        path = runRecordPath(directory, sessionId, 'mutation-lock');
+    }
+    catch {
+        path = undefined;
+    }
+    let claimHeld = false;
+    if (path !== undefined) {
+        try {
+            await mkdir(runRecordsDirectory(directory), { recursive: true, mode: 0o700 });
+            const deadline = Date.now() + (options.waitMs ?? 4_000);
+            for (;;) {
+                if (await takeStaleableClaim(path)) {
+                    claimHeld = true;
+                    break;
+                }
+                if (Date.now() >= deadline)
+                    throw new SessionMutationLockHeldError(sessionId);
+                await new Promise(done => setTimeout(done, options.intervalMs ?? 100));
+            }
+        }
+        catch (error) {
+            // Anything thrown on the way to holding the claim — the timeout above, or a transient
+            // filesystem or permission error out of the directory write or the claim attempt — must give
+            // the turnstile back before it propagates. The map would otherwise keep this unresolved turn,
+            // and every later mutation of the session would wait behind a release that never comes: one
+            // transient error would shut the session's rail actions for the process lifetime.
+            finish();
+            throw error;
+        }
+    }
+    /** Remove the claim at `claimPath` and its dead reclaim ticket. False when the filesystem refused the unlink. */
+    const removeClaim = async (claimPath) => {
+        try {
+            await rm(claimPath, { force: true });
+        }
+        catch {
+            return false;
+        }
+        // A reclaim ticket left by a holder that died would keep refusing reclamation for whoever
+        // reads it next; drop one only when its holder is provably gone, as the resume release does.
+        const held = await inspectClaim(`${claimPath}.reclaim`).catch(() => undefined);
+        if (held !== undefined && !held.live)
+            await rm(`${claimPath}.reclaim`, { force: true }).catch(() => { });
+        return true;
+    };
+    return async () => {
+        const claimPath = path;
+        if (claimPath !== undefined && claimHeld) {
+            // A release whose unlink is refused must not resolve as though the lock were gone: the claim
+            // file names this live pid, so every other process keeps waiting out a mutation that is over.
+            // Short retries first — a scanner or indexer holding the file is a matter of moments — and if
+            // the filesystem keeps refusing, the in-process turn comes back at once while a detached pass
+            // keeps removing the claim until it is gone. The writer is done; only the file owes anyone.
+            let removed = await removeClaim(claimPath);
+            for (const wait of [50, 100, 200]) {
+                if (removed)
+                    break;
+                await new Promise(done => setTimeout(done, wait));
+                removed = await removeClaim(claimPath);
+            }
+            if (!removed)
+                void (async () => {
+                    let wait = 250;
+                    while (!(await removeClaim(claimPath))) {
+                        await new Promise(done => { const timer = setTimeout(done, wait); timer.unref?.(); });
+                        wait = Math.min(wait * 2, 2_000);
+                    }
+                })().catch(() => { });
+        }
+        finish();
+    };
+}
+/**
+ * Clear the recovery marker once a record's `interrupted` finish has been queued.
+ *
+ * Called by the reporter rather than the sweep: the sweep must not claim the work is done, because
+ * the finish it returns may never be enqueued if this process dies first.
+ */
+export async function clearInterruptedTelemetry(directory, runIds) {
+    for (const runId of runIds) {
+        const path = runRecordPath(directory, runId, 'json');
+        try {
+            const value = JSON.parse(await readFile(path, 'utf8'));
+            if (value.status !== 'interrupted' || value.telemetryPending !== true)
+                continue;
+            delete value.telemetryPending;
+            await writeSessionSnapshot(path, JSON.stringify(value, null, 2) + '\n');
+        }
+        catch { /* A record that cannot be rewritten is reported again next time; the id is stable. */ }
+    }
+}