@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/run-records.d.ts

@@ -0,0 +1,500 @@
+import { type SavedSession } from './sessions.js';
+import type { RunCheckpoint } from './run-progress.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 declare function runRecordsDirectory(directory?: string): string;
+/**
+ * The state a run record's `status` field can hold.
+ *
+ * The terminal names are the runtime's own result statuses. `running` is written when the run
+ * starts — before any result exists — so a stopped or crashed attempt is visible without waiting
+ * for a finalizer that may never land, and `interrupted` is what recovery writes when it finds
+ * such a record whose engine is gone.
+ */
+export type RunRecordStatus = 'running' | 'interrupted' | 'succeeded' | 'exhausted' | 'cancelled' | 'infrastructure_error' | 'needs_clarification';
+/**
+ * The record written the moment a run starts, replaced by the terminal result when it finalizes.
+ *
+ * It is deliberately the same file the finalizer writes: a crash between the two leaves the open
+ * record on disk, which is what lets startup recovery classify the run instead of losing it, and
+ * `listRuns` reports it with a status rather than hiding a run that has no result yet.
+ */
+export interface OpenRunRecord {
+    id: string;
+    status: 'running';
+    /** The session the attempt belongs to, so recovery can find the marker turn to upgrade. */
+    sessionId: string;
+    startedAt: string;
+    /** The engine process that owns the run; recovery marks the run interrupted when this pid is gone. */
+    pid: number;
+    /** What the user selected (`default`, `:andorra`, a custom graph id) — a resume re-selects through the access rules with this, not with the pinned graph's id. */
+    graphSelection?: string;
+    /** Signed-in account subject at run creation, bound to Graph Studio run inspection. */
+    accountSubject?: string;
+    graph: {
+        id: string;
+    };
+    provider: string;
+    model: string;
+    /** Set on a run an external host drives as a subagent, so a recovered attempt keeps that identity. */
+    subagent?: boolean;
+    /**
+     * The permission the attempt ran under, when the host bound it to one.
+     *
+     * A read-only subagent that is later resumed must not come back as a full-access run: the
+     * workspace's own setting is not the host's instruction, and the host is the one that
+     * prohibited the mutations. A resuming caller that names a permission of its own still wins.
+     */
+    permissions?: string;
+    /** Set on a resumed attempt: the run whose stopped state this run continues. */
+    resumedFrom?: string;
+    /**
+     * Set when the resume carried a message: the instruction the user sent as this attempt continued.
+     * The finalized record carries it; the open record must too, because an attempt that crashes or
+     * stops leaves this record as the only per-run account of the continuation while it stands.
+     */
+    direction?: string;
+    /**
+     * Older recorded directions this attempt armed ahead of its own message, oldest first, each
+     * naming the attempt that sent it. A record that carries only the newest direction drops the
+     * older instruction behind it when a second crash lands before any checkpoint proves delivery.
+     */
+    pendingDirections?: {
+        runId: string;
+        direction: string;
+        id?: string;
+    }[];
+    /**
+     * The run's full scope and per-run thinking effort, persisted so a resume rebuilds the same
+     * `$run.input.*`/`$run.state.*` work under the same model behavior the stopped attempt ran: the
+     * open record carries them from the first moment, and the finalizer copies them forward, so a
+     * resume can read them whether the attempt crashed or stopped cleanly.
+     */
+    runInput?: Record<string, unknown>;
+    runState?: Record<string, unknown>;
+    reasoningEffort?: string;
+    /**
+     * Set when the attempt overrode every node's model: the graph's own per-node selections were set
+     * aside for this run, so a resume has to set them aside again or the nodes would come back on
+     * the models the graph names for themselves.
+     */
+    overrideAllNodes?: boolean;
+    /**
+     * A live model selection was accepted during this attempt. The current provider/model and
+     * override scope are persisted before that selection becomes visible to model turns. On resume,
+     * old-stamped checkpoints are reconciled to this pair without losing completed tool history.
+     */
+    liveModelChanged?: boolean;
+    /**
+     * The surface that produced the run, so recovery on another surface reports the pair as one
+     * pair: a crashed CLI run found by a desktop app-server must not finish as `desktop`, or the
+     * joined lifecycle events disagree and the interrupted outcome lands in the wrong bucket.
+     */
+    surface?: 'cli' | 'desktop' | 'remote' | 'subagent';
+    /**
+     * The random telemetry run id and the start's dimensions.
+     *
+     * They are written into the open record so recovery can enqueue one idempotent `interrupted`
+     * finish for a run whose process died: the finish repeats the start's dimensions, and `runId`
+     * is what joins the pair. Neither value is derived from local state or from an account.
+     */
+    telemetry?: {
+        runId: string;
+        nodes: number;
+        subagents: boolean;
+        jevEnabled: boolean;
+        decisionRouting: 'off' | 'shadow' | 'active';
+        /** The workspace permission mode, where the surface records it inside telemetry. */
+        permissions?: string;
+        permissionMode?: string;
+        /** False until the start is queued; recovery reads it to decide whether it owes the start. */
+        startSent?: boolean;
+    };
+}
+/** The history entry a session carries while its attempt is in flight, replaced when the attempt lands. */
+export declare 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 declare 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 declare function summaryForStoppedRecord(record: Record<string, unknown>): string;
+/** A small independent projection for Graph Studio: final run records may be huge. */
+export interface StudioRunSummary {
+    id: string;
+    status: string;
+    startedAt?: string;
+    graphSelection?: string;
+    accountSubject?: string;
+    graph?: {
+        id?: string;
+        revision?: number;
+    };
+    toolCalls?: number;
+}
+export declare function writeStudioRunSummary(directory: string, record: StudioRunSummary): Promise<void>;
+/**
+ * The small marker naming an open run: one per run in flight, holding what the guard needs.
+ *
+ * It is the index entry `sessionHasOpenRun` answers from, so the guard never reopens the result
+ * records: those are the files that grow (a completed attempt's record carries its whole
+ * completion), and the guard runs on every rail action. The claim is deliberately a separate
+ * extension from every record the scans read, it names the run rather than the session so two
+ * concurrent runs of one session each keep their own entry, and an engine clears its own on
+ * finalize. A claim left by a process that is gone proves nothing: `sessionHasOpenRun` clears one
+ * whose owner is gone — a dead pid, or a pid the platform says now belongs to a process that
+ * started after the claim — and startup recovery clears the claims of the records it marks
+ * interrupted.
+ */
+export interface OpenRunClaim {
+    runId: string;
+    sessionId: string;
+    /** The engine process owning the run; a dead pid marks the claim as a crash leftover. */
+    pid: number;
+    claimedAt: string;
+    /**
+     * When the owning process started, as that process recorded it. A pid alone is not an
+     * identity — the OS hands a dead process's number to the next one — so `sessionHasOpenRun`
+     * corroborates a live pid against this, the way `inspectClaim` does for a resume claim.
+     * Absent on a claim an older installation wrote, where the pid stands on its own.
+     */
+    startedAt?: string;
+    /**
+     * The writing process instance's nonce, when it had one.
+     *
+     * It is the exact answer to "is this claim mine": the start time beside it is a wall-clock
+     * reading that a restarted process can come within a few seconds of, and the nonce cannot be
+     * come close to. Absent on a claim an older installation wrote.
+     */
+    nonce?: string;
+}
+/** Drop a run's open claim. A run only ever owns its own claim, so this cannot clobber another's. */
+export declare function clearOpenRunClaim(directory: string, runId: string): Promise<void>;
+/**
+ * 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 declare function removeOpenRunRecord(directory: string, runId: string): Promise<void>;
+/** The result file written at start; atomic, so a crash mid-write cannot tear the record. */
+export declare function writeOpenRunRecord(directory: string, record: OpenRunRecord): Promise<void>;
+/** Whether a process is running. A live process owned by another user answers EPERM, not ESRCH. */
+export declare function isPidAlive(pid: number): boolean;
+/** This process's own start time, as the claims it writes record it. */
+export declare function processStartedAt(): string;
+/** This process instance's nonce, for a claim that carries one. */
+export declare function processNonce(): string;
+/**
+ * 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 declare function claimProcessWorkspace(workspace: string, owner: string): boolean;
+/** Give a workspace back, when the engine releasing it is the one that reserved it. */
+export declare function releaseProcessWorkspace(workspace: string, owner: string): void;
+export interface RunRecovery {
+    /** Open run records that could not belong to a live process and were marked interrupted. */
+    runs: string[];
+    /** Sessions whose in-flight marker turns were upgraded to match. */
+    markers: number;
+    /**
+     * Open records the sweep left running because a live process other than this one owns them —
+     * each holder's run identity, pid, and session. Captured by the same walk that did the sweep,
+     * so a holder that exited before the pass observed it is already recovered and one that exits
+     * after it is already in this set: an engine watching these pids needs no second scan, and an
+     * exit at any moment is either recovered immediately or retained for polling.
+     */
+    live: {
+        runId: string;
+        pid: number;
+        sessionId: string | undefined;
+    }[];
+    /** The rewritten records, so a caller can emit the `interrupted` finish that joins their start. */
+    interrupted: Record<string, unknown>[];
+}
+/**
+ * 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 declare function reconcileInterruptedRuns(directory: string, onlyRunIds?: Set<string>, options?: {
+    skipOwnProcess?: boolean;
+    includePending?: boolean;
+}): Promise<RunRecovery>;
+/**
+ * Whether a live process currently owns a run of this session, this engine or another.
+ *
+ * The open-run claims are the answer: one small file per run in flight, written by
+ * `writeOpenRunRecord` and cleared when the run finalizes, each naming its session and its owning
+ * pid. A guard reading them touches only files that stay small (open runs are few, and a claim is
+ * one line), so a rail action costs a directory listing and a handful of tiny reads — never the
+ * historical records, which grow with the installation's whole history and are expensive to reopen
+ * (a completed attempt's record can carry a large completion). An engine's in-process fields
+ * describe only itself: an archive or rename accepted while a second window runs the same session
+ * would be silently reverted when that run saves the record it captured before the mutation. A
+ * claim is treated as owned unless its owner is provably gone — a dead pid, or a live pid whose
+ * start time contradicts the one the claim recorded, which means the number went to an unrelated
+ * process after the owner died. Both are crash leftovers that reconcile marks interrupted, so an
+ * unknown owner blocks conservatively rather than racing, and one read as gone is removed on the
+ * way out. Without that corroboration a recycled pid would hold a session busy — refusing every
+ * rename, archive, and delete — for as long as the unrelated process lives.
+ *
+ * Two fallbacks keep the old scan's answers for states the index cannot see: a session identity
+ * outside the claim path's alphabet (never a real session, which is a UUID) and a claim file that
+ * cannot be parsed, both of which fall back to reading the `running` records directly.
+ */
+/**
+ * The live session IDs named by open-run claims, plus the crashed attempts the
+ * session snapshots cannot show. One bounded directory pass lets session-monitor
+ * identify a new run before the running turn has been saved, without scanning
+ * every claim for every retained session. Superseded and orphaned crash markers
+ * are removed by that same pass, so later polls read only live crash signals.
+ *
+ * These are hints only: callers can still check sessionHasOpenRun immediately
+ * before reporting status, retaining its conservative malformed-claim fallback.
+ */
+export interface MonitoredRunClaims {
+    active: Set<string>;
+    /** Dead attempts with no persisted turn of their own and no later run to supersede them. */
+    crashed: Map<string, {
+        runId: string;
+        claimedAt: string;
+    }>;
+}
+export declare function sessionsWithOpenRunClaims(directory: string, sessions?: readonly SavedSession[]): Promise<MonitoredRunClaims>;
+/**
+ * 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 declare function sessionHasOpenRun(directory: string, sessionId: string, options?: {
+    ignoreRunId?: string;
+}): Promise<boolean>;
+/**
+ * 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 declare function sessionHasArmedWake(directory: string, sessionId: string): Promise<boolean>;
+/**
+ * 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 declare function writeWakeClaim(directory: string, sessionId: string, timerId: string): Promise<void>;
+/** Drop one wake's claim: the wake was delivered, spent, or canceled by the engine that armed it. */
+export declare function clearWakeClaim(directory: string, sessionId: string, timerId: string): Promise<void>;
+/**
+ * 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 declare function clearWakeClaims(directory: string, sessionId: string): Promise<void>;
+/**
+ * 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 declare function repairSessionMarkers(directory: string, sessionId: string): Promise<number>;
+/**
+ * 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 declare function runRecordPath(directory: string, runId: unknown, extension: 'json' | 'jsonl' | 'checkpoint' | 'claim' | 'journal-error' | 'checkpoint-error' | 'open-run' | 'mutation-lock' | 'mcp-crash'): string;
+/**
+ * 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 declare function noteJournalWriteFailure(directory: string, runId: string, detail: string): Promise<void>;
+/**
+ * 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 declare function journalWriteFailed(directory: string, runId: string): Promise<boolean>;
+/**
+ * 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 declare function noteCheckpointWriteFailure(directory: string, runId: string, detail: string): Promise<void>;
+/**
+ * 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 declare function checkpointWriteFailed(directory: string, runId: string): Promise<boolean>;
+/**
+ * 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 declare function writeRunCheckpoint(directory: string, runId: string, checkpoint: RunCheckpoint): Promise<void>;
+/**
+ * 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 declare function readRunCheckpoint(directory: string, runId: string, nodeId: string): Promise<RunCheckpoint | undefined>;
+/**
+ * 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 declare function readRunCheckpoints(directory: string, runId: string): Promise<RunCheckpoint[]>;
+/**
+ * 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 declare function removeRunCheckpoint(directory: string, runId: string): Promise<void>;
+/**
+ * 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 declare function claimRunResume(directory: string, runId: string): Promise<boolean>;
+/**
+ * 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 declare function releaseRunResumeClaim(directory: string, runId: string): Promise<void>;
+/** Thrown when a session mutation lock is held elsewhere and does not free up within the wait. */
+export declare class SessionMutationLockHeldError extends Error {
+    constructor(sessionId: string);
+}
+/**
+ * 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 declare function acquireSessionMutationLock(directory: string, sessionId: string, options?: {
+    waitMs?: number;
+    intervalMs?: number;
+}): Promise<() => Promise<void>>;
+/**
+ * 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 declare function clearInterruptedTelemetry(directory: string, runIds: string[]): Promise<void>;