@enderfga/claw-orchestrator 5.1.0 → 6.0.0

package/dist/src/kernel/projections.js

@@ -0,0 +1,133 @@
+/**
+ * Legacy mode shapes, projected from a kernel run.
+ *
+ * Before 6.0.0 each mode kept its results in its own `Map` on SessionManager,
+ * evicted after 30 minutes, gone on restart. The shapes those maps held —
+ * `CouncilSession`, `FanoutSession`, `UltraplanResult`, `UltrareviewResult`,
+ * `AutoloopState` — are the public contract of the `*_status` tools, so they
+ * survive; what changes is where they come from. They are now derived from the
+ * durable run record, which is why a fan-out's results are still there tomorrow.
+ *
+ * Pure functions, no I/O beyond the caller-supplied text, so the mapping is
+ * testable without starting anything.
+ */
+/** Node id used by every single-node legacy workflow, so projections know where to look. */
+export const LEGACY_NODE = 'main';
+function node(record, id = LEGACY_NODE) {
+    return record.nodes[id];
+}
+/**
+ * The node's declaration, used as the fallback for fields the node has not
+ * published yet. A run polled the instant it starts has no `data`, and reading
+ * the task out of the spec beats reporting the workflow's name as the task.
+ */
+function spec(record, id = LEGACY_NODE) {
+    return record.spec?.nodes?.find((n) => n.id === id);
+}
+/** Terminal states that mean "it ran to the end", whatever the verdict was. */
+function isDone(state) {
+    return state === 'completed' || state === 'failed' || state === 'cancelled';
+}
+export function toCouncilSession(record) {
+    const data = node(record)?.data;
+    const declared = spec(record);
+    return {
+        id: record.runId,
+        task: data?.task ?? declared?.task ?? record.workflow,
+        config: {
+            agents: data?.agents ?? declared?.agents ?? [],
+            maxRounds: data?.maxRounds ?? declared?.maxRounds ?? 0,
+            projectDir: data?.projectDir ?? record.cwd,
+        },
+        responses: data?.responses ?? [],
+        // The council's own status is preserved when it reported one; otherwise the
+        // run's state stands in. A run that was cancelled or failed before the
+        // council spoke has no council status to report, and inventing `consensus`
+        // for it would be the exact kind of claim this release removes.
+        status: data?.councilStatus ?? (record.state === 'running' ? 'running' : 'error'),
+        startTime: record.createdAt,
+        endTime: record.endedAt,
+        finalSummary: data?.finalSummary,
+        compactContext: data?.compactContext,
+    };
+}
+export function toFanoutSession(record) {
+    const data = node(record)?.data;
+    const declared = spec(record);
+    const status = record.state === 'cancelled'
+        ? 'aborted'
+        : record.state === 'failed'
+            ? 'error'
+            : isDone(record.state)
+                ? 'done'
+                : 'running';
+    return {
+        id: record.runId,
+        status,
+        task: data?.task ?? declared?.prompt ?? record.workflow,
+        agentCount: data?.agentCount ?? declared?.agents?.length ?? 0,
+        startedAt: record.createdAt,
+        finishedAt: record.endedAt,
+        results: data?.results ?? [],
+        synthesis: data?.synthesis,
+        error: record.error,
+    };
+}
+// ─── Ultraplan ──────────────────────────────────────────────────────────────
+/**
+ * An engine that answers with a bare error string counts as failed even though
+ * the turn technically completed. Kept verbatim from the previous
+ * implementation so behaviour does not shift under existing callers.
+ */
+const LOOKS_LIKE_ERROR = /^(Error|not logged in|authentication|auth failed|permission denied)/i;
+export function toUltraplanResult(record, plan) {
+    const text = (plan ?? '').trim();
+    const failed = record.state === 'failed' || record.state === 'cancelled';
+    const empty = isDone(record.state) && (!text || LOOKS_LIKE_ERROR.test(text));
+    const status = !isDone(record.state) ? 'running' : failed || empty ? 'error' : 'completed';
+    return {
+        id: record.runId,
+        status,
+        sessionName: `${record.runId}-${LEGACY_NODE}-a1`,
+        startTime: record.createdAt,
+        endTime: record.endedAt,
+        plan: status === 'completed' ? text : undefined,
+        error: status === 'error' ? (record.error ?? text ?? 'Empty response from engine') : undefined,
+    };
+}
+// ─── Ultrareview ────────────────────────────────────────────────────────────
+export function toUltrareviewResult(record, findings) {
+    const data = node(record)?.data;
+    const declared = spec(record);
+    const status = record.state === 'failed' || record.state === 'cancelled'
+        ? 'error'
+        : isDone(record.state)
+            ? 'completed'
+            : 'running';
+    return {
+        id: record.runId,
+        status,
+        // Kept for the UltrareviewResult contract; it now holds the run id, which is
+        // also the fan-out id, because they are the same run.
+        councilId: record.runId,
+        agentCount: data?.agentCount ?? declared?.agents?.length ?? 0,
+        startTime: record.createdAt,
+        endTime: record.endedAt,
+        findings: status === 'completed' ? findings : undefined,
+        error: status === 'error' ? record.error : undefined,
+    };
+}
+/** Join per-agent results into the review text, when no synthesis pass ran. */
+export function joinFindings(data) {
+    if (!data)
+        return undefined;
+    if (data.synthesis)
+        return data.synthesis;
+    const ok = data.results.filter((r) => r.ok && r.output);
+    if (ok.length === 0)
+        return undefined;
+    return ok.map((r) => `## ${r.agent}\n\n${r.output}`).join('\n\n---\n\n');
+}
+/** Engine label used when a legacy caller supplied none. */
+export const DEFAULT_ENGINE = 'claude';
+//# sourceMappingURL=projections.js.map

package/dist/src/kernel/projections.js.map

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

package/dist/src/kernel/repo.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Repository fingerprinting for ledger rows.
+ *
+ * Only what can be read off a manifest file. The point of stamping `repoLang` is
+ * to make the ledger groupable later ("which engine is better at TypeScript test
+ * failures"), and a guessed label would poison exactly the comparison it is meant
+ * to enable — so anything not evidenced by a manifest stays undefined.
+ */
+/**
+ * Detect the primary language of a checkout. A JS manifest plus a tsconfig reads
+ * as TypeScript, since that is what the code in it actually is.
+ */
+export declare function detectRepoLang(cwd: string): string | undefined;

package/dist/src/kernel/repo.js

@@ -0,0 +1,64 @@
+/**
+ * Repository fingerprinting for ledger rows.
+ *
+ * Only what can be read off a manifest file. The point of stamping `repoLang` is
+ * to make the ledger groupable later ("which engine is better at TypeScript test
+ * failures"), and a guessed label would poison exactly the comparison it is meant
+ * to enable — so anything not evidenced by a manifest stays undefined.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Manifest → language, in precedence order. First hit wins. */
+const MANIFESTS = [
+    ['package.json', 'javascript'],
+    ['tsconfig.json', 'typescript'],
+    ['pyproject.toml', 'python'],
+    ['setup.py', 'python'],
+    ['requirements.txt', 'python'],
+    ['go.mod', 'go'],
+    ['Cargo.toml', 'rust'],
+    ['pom.xml', 'java'],
+    ['build.gradle', 'java'],
+    ['build.gradle.kts', 'kotlin'],
+    ['Gemfile', 'ruby'],
+    ['composer.json', 'php'],
+    ['CMakeLists.txt', 'cpp'],
+    ['Package.swift', 'swift'],
+];
+/**
+ * Detect the primary language of a checkout. A JS manifest plus a tsconfig reads
+ * as TypeScript, since that is what the code in it actually is.
+ */
+export function detectRepoLang(cwd) {
+    if (!cwd)
+        return undefined;
+    let found;
+    for (const [file, lang] of MANIFESTS) {
+        let exists = false;
+        try {
+            exists = fs.existsSync(path.join(cwd, file));
+        }
+        catch {
+            exists = false;
+        }
+        if (!exists)
+            continue;
+        if (lang === 'typescript')
+            return 'typescript';
+        found ??= lang;
+    }
+    if (found === 'javascript') {
+        // package.json with a "types"/"typescript" signal but no tsconfig at the root.
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if ('typescript' in deps)
+                return 'typescript';
+        }
+        catch {
+            // Unreadable manifest — keep the weaker answer rather than inventing one.
+        }
+    }
+    return found;
+}
+//# sourceMappingURL=repo.js.map

package/dist/src/kernel/repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../../src/kernel/repo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,gEAAgE;AAChE,MAAM,SAAS,GAA4B;IACzC,CAAC,cAAc,EAAE,YAAY,CAAC;IAC9B,CAAC,eAAe,EAAE,YAAY,CAAC;IAC/B,CAAC,gBAAgB,EAAE,QAAQ,CAAC;IAC5B,CAAC,UAAU,EAAE,QAAQ,CAAC;IACtB,CAAC,kBAAkB,EAAE,QAAQ,CAAC;IAC9B,CAAC,QAAQ,EAAE,IAAI,CAAC;IAChB,CAAC,YAAY,EAAE,MAAM,CAAC;IACtB,CAAC,SAAS,EAAE,MAAM,CAAC;IACnB,CAAC,cAAc,EAAE,MAAM,CAAC;IACxB,CAAC,kBAAkB,EAAE,QAAQ,CAAC;IAC9B,CAAC,SAAS,EAAE,MAAM,CAAC;IACnB,CAAC,eAAe,EAAE,KAAK,CAAC;IACxB,CAAC,gBAAgB,EAAE,KAAK,CAAC;IACzB,CAAC,eAAe,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAI,KAAyB,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;QACrC,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,IAAI,IAAI,KAAK,YAAY;YAAE,OAAO,YAAY,CAAC;QAC/C,KAAK,KAAK,IAAI,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;QAC3B,+EAA+E;QAC/E,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAA4B,CAAC;YAC3G,MAAM,IAAI,GAAG,EAAE,GAAI,GAAG,CAAC,YAAuB,EAAE,GAAI,GAAG,CAAC,eAA0B,EAAE,CAAC;YACrF,IAAI,YAAY,IAAI,IAAI;gBAAE,OAAO,YAAY,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/kernel/secrets.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Secret references.
+ *
+ * Custom-engine configs carry credentials, so they are never written to a run's
+ * spec and never accepted over HTTP. That left a real gap: a run started with a
+ * custom engine could not be resumed after a crash through the dashboard or any
+ * remote caller, because the material it needed could not be supplied.
+ *
+ * A reference closes it without putting anything on the wire. The caller names a
+ * secret; the server resolves the name from its own environment. The name is not
+ * sensitive, the value never leaves the host, and a name that resolves to
+ * nothing is an error rather than a silent start with no credentials.
+ */
+/** Environment variable a reference resolves to. */
+export declare function secretEnvVar(ref: string): string;
+/**
+ * Resolve a reference to a custom-engine config.
+ *
+ * Throws when the name is unknown: starting without the credentials the caller
+ * asked for would fail later, further from the cause, and possibly after doing
+ * work.
+ */
+export declare function resolveSecretRef(ref: string, env?: NodeJS.ProcessEnv): unknown;
+/** Resolve a `{ role: ref }` map. Absent entries stay absent. */
+export declare function resolveSecretRefs(refs: Record<string, string | undefined> | undefined, env?: NodeJS.ProcessEnv): Record<string, unknown>;

package/dist/src/kernel/secrets.js

@@ -0,0 +1,48 @@
+/**
+ * Secret references.
+ *
+ * Custom-engine configs carry credentials, so they are never written to a run's
+ * spec and never accepted over HTTP. That left a real gap: a run started with a
+ * custom engine could not be resumed after a crash through the dashboard or any
+ * remote caller, because the material it needed could not be supplied.
+ *
+ * A reference closes it without putting anything on the wire. The caller names a
+ * secret; the server resolves the name from its own environment. The name is not
+ * sensitive, the value never leaves the host, and a name that resolves to
+ * nothing is an error rather than a silent start with no credentials.
+ */
+const PREFIX = 'CLAWO_CUSTOM_ENGINE_';
+/** Environment variable a reference resolves to. */
+export function secretEnvVar(ref) {
+    return `${PREFIX}${ref.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()}`;
+}
+/**
+ * Resolve a reference to a custom-engine config.
+ *
+ * Throws when the name is unknown: starting without the credentials the caller
+ * asked for would fail later, further from the cause, and possibly after doing
+ * work.
+ */
+export function resolveSecretRef(ref, env = process.env) {
+    const key = secretEnvVar(ref);
+    const raw = env[key];
+    if (!raw) {
+        throw new Error(`Unknown secret reference '${ref}': set ${key} on the orchestrator host to the JSON custom-engine config`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Secret reference '${ref}' (${key}) is not valid JSON: ${err.message}`);
+    }
+}
+/** Resolve a `{ role: ref }` map. Absent entries stay absent. */
+export function resolveSecretRefs(refs, env = process.env) {
+    const out = {};
+    for (const [role, ref] of Object.entries(refs ?? {})) {
+        if (ref)
+            out[role] = resolveSecretRef(ref, env);
+    }
+    return out;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/src/kernel/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../../src/kernel/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,GAAG,sBAAsB,CAAC;AAEtC,oDAAoD;AACpD,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;AACxE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,MAAyB,OAAO,CAAC,GAAG;IAChF,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,6BAA6B,GAAG,UAAU,GAAG,4DAA4D,CAC1G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,MAAM,GAAG,wBAAyB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACrG,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,iBAAiB,CAC/B,IAAoD,EACpD,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;QACrD,IAAI,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/src/kernel/store.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Durable run store.
+ *
+ * Layout, one directory per run under `~/.claw-orchestrator/wf/<runId>/`:
+ *
+ *   spec.json      the WorkflowSpec, written once at creation, never mutated
+ *   run.json       the mutable checkpoint, rewritten atomically on every transition
+ *   events.jsonl   append-only audit + stream source
+ *   nodes/<id>/    per-node artifacts
+ *   evidence/<id>/ evidence bundles (see verify/evidence.ts)
+ *
+ * Splitting the immutable spec from the mutable checkpoint is what carries crash
+ * recovery: if `run.json` is missing or half-written, the state is rebuilt by
+ * replaying `events.jsonl` against `spec.json`. The atomic rewrite makes that
+ * path rare; the replay makes it usually survivable.
+ *
+ * The checkpoint and the events it describes are written by the same
+ * transaction, so they cannot disagree: a commit that reports `committed` has
+ * both, and one that does not has neither. That was not always true — the event
+ * append used to swallow its own errors while the replay treated the same log as
+ * authoritative, which is a contradiction sitting in the recovery path. The
+ * replay is now a plain fallback for a lost `run.json`; a run that lost both it
+ * and the log is unrecoverable, and `loadRun` returns undefined rather than
+ * inventing a state.
+ *
+ * There is exactly one way to write to a run — `commit()` — and it is not
+ * optional: the checkpoint writer and the event appender are module-private, and
+ * a batch is published by a single atomic directory rename rather than by a
+ * sequence of writes that can each fail on their own. `atomicWriteJson` replaces
+ * four near-identical implementations that had grown across the codebase
+ * (`session-manager.ts` sync + async variants, `ultraapp/store.ts`,
+ * `ultraapp/patcher.ts`); the tmp-name shape is kept from the ultraapp one,
+ * whose comment records the CI bug it fixed: a reader catching a plain
+ * `writeFile` mid-flight and parsing a truncated object.
+ */
+import type { Logger } from '../logger.js';
+import type { KernelEvent, RunRecord, RunState, WorkflowSpec } from './types.js';
+export declare function wfDir(): string;
+export declare function isValidRunId(runId: string): boolean;
+/**
+ * Resolve a run's directory. Throws on an invalid id rather than returning a
+ * path, because this is the chokepoint every other path derives from — checking
+ * here means no caller can forget to.
+ */
+export declare function runDir(runId: string): string;
+export declare function nodeDir(runId: string, nodeId: string): string;
+/** Write JSON so a concurrent reader sees either the old file or the new one, never a partial. */
+export declare function atomicWriteJson(file: string, value: unknown): void;
+export declare function runExists(runId: string): boolean;
+export declare function sanitizeForDisk<T>(value: T): T;
+export declare function loadSpec(runId: string): WorkflowSpec | undefined;
+export declare function readEvents(runId: string, limit?: number): KernelEvent[];
+/**
+ * Rebuild a run's state from its spec plus its event log. Used when `run.json`
+ * is absent or unparseable — the belt to the atomic rewrite's braces.
+ */
+export declare function replayRun(runId: string, spec: WorkflowSpec): RunRecord | undefined;
+/** Load a run, preferring the checkpoint and falling back to an event replay. */
+export declare function loadRun(runId: string): RunRecord | undefined;
+export declare function listRunIds(): string[];
+/**
+ * Remove a run's directory. Only ever called from an explicit user delete —
+ * nothing in the kernel prunes runs on its own, for the same reason the ledger
+ * does not: deleting someone's history is not ours to decide.
+ */
+export declare function deleteRunDir(runId: string, logger?: Logger): void;
+/**
+ * Full text a node produced, preferring the artifact file over the record's
+ * preview. `NodeRecord.output` is capped so a checkpoint stays small, but the
+ * whole point of some nodes is their text — an ultraplan whose plan is silently
+ * cut at 4 kB has lost the deliverable.
+ */
+export declare function readNodeOutput(runId: string, nodeId: string): string | undefined;
+/**
+ * Where a node artifact will live, without writing it.
+ *
+ * Pure, because the checkpoint that references an artifact and the artifact
+ * itself are written in the same {@link commit}: the caller needs the path
+ * before the write, to put it in the record it is committing.
+ */
+export declare function nodeArtifactPath(runId: string, nodeId: string, name: string): string;
+export declare const LEASE_TTL_MS = 60000;
+/** How often a live owner refreshes its claim, independently of any work it is doing. */
+export declare const LEASE_HEARTBEAT_MS = 15000;
+/**
+ * The capability to change a run.
+ *
+ * Held by the executing kernel, passed to every write, and impossible to forge
+ * from a run id alone — which is what makes `commit` a boundary rather than a
+ * convention.
+ */
+export interface RunGuard {
+    runId: string;
+    incarnationId: string;
+    ownerId: string;
+    acquisitionId: string;
+    fence: number;
+}
+/**
+ * Who holds a run, as recorded on disk.
+ *
+ * `ownerId` is the identity, not `pid`. Two `RunKernel` instances in one process
+ * — two SessionManagers is not a strange thing to have — share a pid, so
+ * treating the pid as the owner let both of them execute the same run and call
+ * it re-entrancy. The pid is kept because it is what tells us whether the holder
+ * is still alive; it is not what tells us whether the holder is us.
+ */
+export interface RunLease extends RunGuard {
+    pid: number;
+    host: string;
+    acquiredAt: string;
+    renewedAt: string;
+}
+/** What one `commit` may change. Everything durable about a run is in here. */
+export interface CommitBatch {
+    /** The new checkpoint. */
+    record?: RunRecord;
+    /** Appended to `events.jsonl`, in order. */
+    events?: KernelEvent[];
+    /** Node artifact files, published together with the record that references them. */
+    artifacts?: Array<{
+        nodeId: string;
+        name: string;
+        body: string;
+    }>;
+}
+/**
+ * Why a write did or did not happen.
+ *
+ * Three outcomes rather than a boolean, because the two failures call for
+ * opposite responses: `superseded` means stop permanently, `blocked` means this
+ * attempt did not get through and the run is still ours.
+ */
+export type CommitOutcome = 'committed' | 'superseded' | 'blocked';
+export interface CommitResult {
+    outcome: CommitOutcome;
+    reason?: string;
+}
+export type ReleaseOutcome = 'released' | 'not-ours' | 'blocked';
+export declare function readLease(runId: string): RunLease | undefined;
+/**
+ * True when a lease no longer represents a live owner.
+ *
+ * On the same host the pid is the authority and the heartbeat is not consulted:
+ * a process running one long node makes no checkpoints, and judging it dead for
+ * that reason is how two owners end up running the same work. The heartbeat is
+ * the fallback for a holder we cannot ask about — another machine, or a pid
+ * whose meaning we cannot trust across hosts.
+ */
+export declare function leaseIsStale(lease: RunLease | undefined, now?: number): boolean;
+/** Apply anything a crashed owner committed but did not finish writing. */
+export declare function recoverPending(runId: string, logger?: Logger): boolean;
+/**
+ * Create a run and claim it, atomically.
+ *
+ * The non-recursive `mkdir` IS the claim: it fails with EEXIST for everyone but
+ * the first caller, so exactly one process can create a given run id. The
+ * previous version asked `runExists()` and then created with
+ * `{ recursive: true }`, which is a check-then-write race and lost it routinely
+ * — two processes creating the same id 80 times had both "succeed" 76 times,
+ * leaving one workflow executing while the other's `spec.json` sat on disk, and
+ * a lease belonging to an incarnation that had already been overwritten.
+ */
+export declare function createAndAcquire(runId: string, spec: WorkflowSpec, ownerId: string): RunGuard;
+/**
+ * Claim an existing run and receive the capability to write to it.
+ *
+ * Refused when someone else's claim is still live. Allowed for the same owner —
+ * but the guard it returns is a NEW one, and the previous guard is dead from
+ * that moment: re-acquiring is a fresh claim, not a renewal of the old one, so
+ * anything still holding the old guard stops being able to write.
+ */
+export declare function acquireLease(runId: string, ownerId: string): RunGuard;
+/** Heartbeat. Best-effort: losing a renewal must not break the run. */
+export declare function renewLease(guard: RunGuard): void;
+/**
+ * The one way to change anything durable about a run.
+ *
+ * The guard is verified and the transaction is published inside a single
+ * critical section, so a holder that has been superseded cannot land a write
+ * between the check and the change.
+ *
+ * Callers pass a record they have already produced by copying and mutating,
+ * never the record they are still using: `commit` persists what it is given, and
+ * the caller adopts it only on `committed`. That is what keeps a refused write
+ * from leaving a run *in memory* claiming a state the disk rejected.
+ */
+export declare function commit(guard: RunGuard, batch: CommitBatch, logger?: Logger): CommitResult;
+/**
+ * Release the claim. The incarnation file is deliberately NOT removed — the
+ * fence must keep increasing for as long as this creation of the run exists.
+ *
+ * `blocked` is not `not-ours`: an owner that is standing down and cannot take
+ * the lock still has to hand the run back, so the caller retries rather than
+ * leaving a lease behind that no one can take over.
+ */
+export declare function releaseLease(guard: RunGuard): ReleaseOutcome;
+export interface RunSummary {
+    runId: string;
+    workflow: string;
+    state: RunState;
+    outcome: RunRecord['outcome'];
+    cwd: string;
+    createdAt: string;
+    updatedAt: string;
+    endedAt?: string;
+    currentNode?: string;
+    evidenceId?: string;
+    error?: string;
+    costUsd?: number;
+}
+export interface ListRunsQuery {
+    workflow?: string;
+    state?: RunState;
+    limit?: number;
+}
+export declare function summarize(record: RunRecord): RunSummary;
+/**
+ * Every run on this machine, newest first — the cross-process listing the three
+ * mode-specific enumerations each did differently (council regex-scraped its own
+ * markdown transcripts, autoloop read a JSONL registry, ultraapp walked a store
+ * directory). No separate index file is needed here because every run lives
+ * under one root, so the directory *is* the index.
+ */
+export declare function listRuns(query?: ListRunsQuery): RunSummary[];