@namzu/sdk 20.2.0 → 20.4.0

package/dist/types/run/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/run/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAK3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,YAAY,EACX,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,GACtB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAChE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACzF,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/run/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAK3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,YAAY,EACX,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,GACtB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAChE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACzF,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/types/run/index.js

@@ -3,6 +3,7 @@ export * from './prepare-step.js';
 export * from './stop-reason.js';
 export * from './config.js';
 export * from './checkpoint-store.js';
+export * from './store.js';
 export * from './entity.js';
 export * from './replay.js';
 // Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Safe to

package/dist/types/run/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/run/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,wEAAwE;AACxE,4EAA4E;AAC5E,0EAA0E;AAC1E,sBAAsB;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAQ1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/run/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,wEAAwE;AACxE,4EAA4E;AAC5E,0EAA0E;AAC1E,sBAAsB;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAQ1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/types/run/store.d.ts

@@ -0,0 +1,103 @@
+/**
+ * RunStore — persistence contract for a run's own evidence.
+ *
+ * The checkpoint store got an injectable seam and this did not, which left
+ * the run record, its messages, its transcript and its report reachable only
+ * through a concrete filesystem class. For a kernel whose stated purpose is
+ * auditable evidence, the evidence was the one thing that could not be
+ * pointed at durable storage: on ephemeral infrastructure the transcript dies
+ * with the container, and behind a load balancer two replicas write two
+ * disjoint run trees for one tenant.
+ *
+ * The location was already injectable through a path builder — but that
+ * returns filesystem path strings, so it relocates the directory without
+ * changing the medium.
+ *
+ * ## Bound to one run, unlike {@link CheckpointStore}
+ *
+ * Every accessor here addresses the run the store was bound to by
+ * {@link RunStore.initRun}, where a `CheckpointStore` takes an explicit scope
+ * per call. That asymmetry is inherited rather than chosen: this contract is
+ * extracted from a class the runtime already constructs per run and holds for
+ * the run's lifetime, and re-keying it would change every call site in the
+ * same change that introduces the seam — two risks where one will do.
+ *
+ * A host implementing a shared backend therefore keys its rows by the
+ * attribution it was constructed with plus the bound run id. If this is later
+ * re-keyed per call, it happens once, deliberately, as its own change.
+ */
+import type { Run } from './entity.js';
+import type { RunEvent } from './events.js';
+/**
+ * One finished tool call, recovered from the run's own transcript.
+ *
+ * Re-declared here rather than imported from the disk store so the contract
+ * does not depend on an implementation of itself.
+ */
+export interface CompletedToolRecord {
+    readonly toolUseId: string;
+    readonly toolName: string;
+    readonly result: string;
+    readonly isError: boolean;
+}
+export interface RunStore {
+    /**
+     * Bind this store to a run, before any other call.
+     *
+     * Returns a location when the backend has one — the built-in disk store
+     * returns the run's directory — and `null` when it does not. A caller
+     * that renders the value must treat `null` as "this run is not on a
+     * filesystem" rather than as an error: an in-memory or object-storage
+     * backend has nothing to print, and inventing a path for it would put a
+     * directory that does not exist in front of an operator.
+     */
+    initRun(runId: string, parentRunId?: string): Promise<string | null>;
+    /** Persist the run record: status, metadata, usage, timings. */
+    writeRunMeta(run: Run): Promise<void>;
+    /** Persist the run's full message history. */
+    writeMessages(run: Run): Promise<void>;
+    /**
+     * Append one event to the run's durable event log.
+     *
+     * High-frequency streaming deltas are excluded before they reach here —
+     * that exclusion is a deliberate trade and belongs to the emitter, not to
+     * the backend, so a store must not re-filter.
+     */
+    appendEvent(event: RunEvent): Promise<void>;
+    /**
+     * Persist the run's final report. Returns a location, or `null` when the
+     * backend has none. See {@link RunStore.initRun}.
+     */
+    writeReport(content: string): Promise<string | null>;
+    /**
+     * Every tool call this run has already finished, keyed by `toolUseId`.
+     *
+     * A batch's results reach the message history only once the WHOLE batch
+     * settles, so a hard kill part-way through loses every result that had
+     * already come back, and the resumed run re-executes those calls. For a
+     * file write that is waste; for a payment or an email it is a second one.
+     *
+     * A backend that does not retain individual events answers with an empty
+     * map, which costs re-execution and is honest. It must not answer with a
+     * PARTIAL map: a caller reads a present entry as "this call is already
+     * answered", so a half-remembered batch is worse than a forgotten one.
+     */
+    readCompletedTools(): Promise<Map<string, CompletedToolRecord>>;
+    /**
+     * Where this run's evidence lives, or `null` when it is not on a
+     * filesystem. Valid only after {@link RunStore.initRun}.
+     */
+    getRunDir(): string | null;
+    /**
+     * Record the run in a browsable catalogue of runs. OPTIONAL.
+     *
+     * Optional because it is the one method here that is not evidence: it
+     * maintains a convenience listing for a human reading the directory, and
+     * a backend whose runs are already queryable has nothing to add. The
+     * programmatic answer to "which runs are there" is
+     * `CheckpointStore.listDurableRuns`, which carries attribution and
+     * includes sub-runs; this does neither.
+     */
+    addToIndex?(run: Run): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/types/run/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/run/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;OASG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEpE,gEAAgE;IAChE,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErC,8CAA8C;IAC9C,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtC;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEpD;;;;;;;;;;;;OAYG;IACH,kBAAkB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAA;IAE/D;;;OAGG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI,CAAA;IAE1B;;;;;;;;;OASG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC"}

package/dist/types/run/store.js

@@ -0,0 +1,30 @@
+/**
+ * RunStore — persistence contract for a run's own evidence.
+ *
+ * The checkpoint store got an injectable seam and this did not, which left
+ * the run record, its messages, its transcript and its report reachable only
+ * through a concrete filesystem class. For a kernel whose stated purpose is
+ * auditable evidence, the evidence was the one thing that could not be
+ * pointed at durable storage: on ephemeral infrastructure the transcript dies
+ * with the container, and behind a load balancer two replicas write two
+ * disjoint run trees for one tenant.
+ *
+ * The location was already injectable through a path builder — but that
+ * returns filesystem path strings, so it relocates the directory without
+ * changing the medium.
+ *
+ * ## Bound to one run, unlike {@link CheckpointStore}
+ *
+ * Every accessor here addresses the run the store was bound to by
+ * {@link RunStore.initRun}, where a `CheckpointStore` takes an explicit scope
+ * per call. That asymmetry is inherited rather than chosen: this contract is
+ * extracted from a class the runtime already constructs per run and holds for
+ * the run's lifetime, and re-keying it would change every call site in the
+ * same change that introduces the seam — two risks where one will do.
+ *
+ * A host implementing a shared backend therefore keys its rows by the
+ * attribution it was constructed with plus the bound run id. If this is later
+ * re-keyed per call, it happens once, deliberately, as its own change.
+ */
+export {};
+//# sourceMappingURL=store.js.map

package/dist/types/run/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/types/run/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "20.2.0",
+  "version": "20.4.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/manager/run/persistence.ts

@@ -9,6 +9,7 @@ import type { ProviderErrorInfo } from '../../types/provider/index.js'
 import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { Run, RunPersistenceConfig, StepResult, StopReason } from '../../types/run/index.js'
+import type { RunStore } from '../../types/run/store.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import { type ModelPricing, ZERO_COST, accumulateCost } from '../../utils/cost.js'
 import { generateEmergencySaveId } from '../../utils/id.js'
@@ -16,7 +17,7 @@ import type { Logger } from '../../utils/logger.js'
 
 export class RunPersistence {
 	private run: Run
-	private runStore: RunDiskStore
+	private runStore: RunStore
 	private checkpointStore: CheckpointStore
 	private pricing?: ModelPricing
 
@@ -38,10 +39,17 @@ export class RunPersistence {
 		this._tenantId = config.tenantId
 		this._projectId = config.projectId
 
-		this.runStore = new RunDiskStore({
-			baseDir: config.outputDir,
-			logger: config.log,
-		})
+		// The run's own evidence goes through the same kind of injectable seam
+		// the checkpoint store already had. Without it the transcript, the run
+		// record and the report could only ever live on a local filesystem —
+		// which for a kernel whose purpose is auditable evidence made the
+		// evidence the one thing that could not be pointed at durable storage.
+		this.runStore =
+			config.runStore ??
+			new RunDiskStore({
+				baseDir: config.outputDir,
+				logger: config.log,
+			})
 
 		// Checkpoints go through the injectable seam; the disk layout under
 		// `outputDir` (same tree the runStore writes to) stays the default.
@@ -137,7 +145,7 @@ export class RunPersistence {
 		return this.run
 	}
 
-	getRunStore(): RunDiskStore {
+	getRunStore(): RunStore {
 		return this.runStore
 	}
 
@@ -457,7 +465,9 @@ export class RunPersistence {
 	async persist(): Promise<void> {
 		await this.runStore.writeRunMeta(this.run)
 		await this.runStore.writeMessages(this.run)
-		await this.runStore.addToIndex(this.run)
+		// Optional on the contract: a backend whose runs are already queryable
+		// has no browsable directory to add a row to.
+		await this.runStore.addToIndex?.(this.run)
 
 		if (this.run.result) {
 			await this.runStore.writeReport(this.run.result)

package/src/public-runtime.ts

@@ -200,6 +200,7 @@ export {
 	DiskTaskStore,
 	InMemoryCheckpointStore,
 	InMemoryMemoryIndex,
+	InMemoryRunStore,
 	InMemoryMemoryStore,
 	InMemoryStore,
 	InMemoryTaskStore,
@@ -217,6 +218,11 @@ export {
 	paginateDurableRuns,
 	toDurableRunEntry,
 } from './store/index.js'
+// Cross-process possession of a run. `claimRun` REFUSES on a store that
+// cannot arbitrate rather than proceeding unclaimed, because proceeding lets
+// two workers restore one checkpoint, both run its tools and both write under
+// one run id — which loses half the work and reports nothing.
+export { claimRun, fencedOut, releaseRun, toClaimSummary } from './store/index.js'
 
 export {
 	AgentRegistry,

package/src/runtime/query/checkpoint.ts

@@ -11,7 +11,11 @@ import type {
 	PendingDecision,
 } from '../../types/hitl/index.js'
 import type { AssistantMessage } from '../../types/message/index.js'
-import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type {
+	CheckpointRunScope,
+	CheckpointStore,
+	ClaimFence,
+} from '../../types/run/checkpoint-store.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { CheckpointListEntry } from '../../types/run/replay.js'
 import { ZERO_COST } from '../../utils/cost.js'
@@ -154,6 +158,22 @@ export class CheckpointManager {
 	/** See {@link setParkTtl}. */
 	private parkTtlMs?: number
 
+	/**
+	 * The claim this run holds, presented on every checkpoint write.
+	 *
+	 * Unset means unfenced, which is correct for a single-writer deployment
+	 * and is what every run did before claims existed. Set it and a write from
+	 * a superseded holding is refused by the store.
+	 *
+	 * This existed nowhere for one release, and the omission was invisible in
+	 * the worst way: the claim, the fence and the refusal were all built and
+	 * tested, and no code path between a run and its store carried the number,
+	 * so every checkpoint a RUN wrote went out unfenced. A capability that is
+	 * complete except for the wire between its halves reads exactly like a
+	 * working one.
+	 */
+	private claimFence?: ClaimFence
+
 	/**
 	 * The run's attribution instant, stamped onto every checkpoint this
 	 * manager writes.
@@ -234,7 +254,7 @@ export class CheckpointManager {
 			traceContext: this.traceSource?.(),
 		}
 
-		await this.store.writeCheckpoint(this.scope, checkpoint)
+		await this.store.writeCheckpoint(this.scope, checkpoint, this.claimFence)
 		this.lastCreatedId = checkpoint.id
 		return checkpoint
 	}
@@ -298,10 +318,27 @@ export class CheckpointManager {
 				...(ttl !== undefined && ttl > 0 ? { deadlineAt: parkedAt + ttl } : {}),
 			},
 		}
-		await this.store.writeCheckpoint(this.scope, parked)
+		await this.store.writeCheckpoint(this.scope, parked, this.claimFence)
 		return parked
 	}
 
+	/**
+	 * Present this claim on every subsequent write. See {@link claimFence}.
+	 *
+	 * A setter rather than a constructor argument because a run is claimed at
+	 * a different moment than it is constructed — a worker draining a queue
+	 * takes the run, then builds the pipeline around it — and because a
+	 * renewal mints a NEW fence mid-run that has to replace the old one.
+	 */
+	setClaimFence(fence: ClaimFence | undefined): void {
+		this.claimFence = fence
+	}
+
+	/** The claim currently presented on writes, if any. */
+	get presentedFence(): ClaimFence | undefined {
+		return this.claimFence
+	}
+
 	/** Default time-to-live applied to every park this manager records. */
 	setParkTtl(ttlMs: number | undefined): void {
 		this.parkTtlMs = ttlMs
@@ -329,7 +366,7 @@ export class CheckpointManager {
 				decision: { action: 'pause', reason: 'The approval request expired without an answer.' },
 			},
 		}
-		await this.store.writeCheckpoint(this.scope, expired)
+		await this.store.writeCheckpoint(this.scope, expired, this.claimFence)
 		return expired
 	}
 
@@ -352,7 +389,7 @@ export class CheckpointManager {
 			...checkpoint,
 			pending: { ...checkpoint.pending, resolvedAt: Date.now(), decision },
 		}
-		await this.store.writeCheckpoint(this.scope, resolved)
+		await this.store.writeCheckpoint(this.scope, resolved, this.claimFence)
 		return resolved
 	}
 

package/src/runtime/query/context.ts

@@ -17,6 +17,7 @@ import type { PermissionMode } from '../../types/permission/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { CheckpointStore } from '../../types/run/checkpoint-store.js'
 import type { AgentRunConfig } from '../../types/run/index.js'
+import type { RunStore } from '../../types/run/store.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { generateRunId } from '../../utils/id.js'
@@ -62,6 +63,7 @@ export interface RunContextConfig {
 	 * output directory.
 	 */
 	checkpointStore?: CheckpointStore
+	runStore?: RunStore
 
 	/**
 	 * Optional injected migrator — tests pass a stub; production code relies
@@ -186,6 +188,7 @@ export class RunContextFactory {
 			parentRunId: config.parentRunId,
 			depth: config.depth,
 			checkpointStore: config.checkpointStore,
+			runStore: config.runStore,
 		})
 
 		const trackingConfig = resolveActivityTracking(permissionMode, config.enableActivityTracking)

package/src/runtime/query/index.ts

@@ -58,7 +58,7 @@ import type { AgentPersona } from '../../types/persona/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { ReviewAnswer } from '../../types/run/answer-review.js'
-import type { CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type { CheckpointStore, ClaimFence } from '../../types/run/checkpoint-store.js'
 import type {
 	AgentRunConfig,
 	PrepareStepChain,
@@ -70,6 +70,7 @@ import type {
 } from '../../types/run/index.js'
 import type { PromoteMemory } from '../../types/run/memory-promotion.js'
 import { memoryCandidateFor } from '../../types/run/memory-promotion.js'
+import type { RunStore } from '../../types/run/store.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
@@ -412,6 +413,38 @@ export interface QueryParams {
 	 */
 	checkpointStore?: CheckpointStore
 
+	/**
+	 * The fence of the claim this worker holds on the run, from `claimRun`.
+	 *
+	 * Presented on every checkpoint the run writes, so a worker that stalled
+	 * past its lease is refused rather than writing into a run somebody else
+	 * has taken over. Omit it for single-writer deployments, which is what
+	 * every run did before claims existed.
+	 *
+	 * This hop did not exist for a release. The claim, the fence and the
+	 * store-side refusal were all built and tested, and no path between a run
+	 * and its store carried the number — so every checkpoint a RUN wrote went
+	 * out unfenced while the tests, which called the store directly, all
+	 * passed. A capability complete except for the wire between its halves
+	 * reads exactly like a working one.
+	 *
+	 * It fences checkpoints and nothing else. {@link QueryParams.runStore}
+	 * takes no fence, so two workers that both took one run still overwrite
+	 * each other's run record, transcript and report — see the changeset.
+	 */
+	claimFence?: ClaimFence
+
+	/**
+	 * Where this run records its own evidence — the run record, its messages,
+	 * its transcript and its report. Defaults to the disk layout under the
+	 * resolved output directory.
+	 *
+	 * The sibling of {@link QueryParams.checkpointStore}, and it should always
+	 * have been one: checkpoints could be pointed at durable storage and the
+	 * evidence could not.
+	 */
+	runStore?: RunStore
+
 	runId?: RunId
 
 	parentRunId?: RunId
@@ -610,6 +643,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		tenantId: params.tenantId,
 		pathBuilder: params.pathBuilder,
 		checkpointStore: params.checkpointStore,
+		runStore: params.runStore,
 		runId: params.runId,
 		parentRunId: params.parentRunId,
 		depth: params.depth,
@@ -1000,6 +1034,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// And every park it records carries an absolute deadline, so an
 		// unanswered approval cannot outlive the worker that asked for it.
 		checkpointMgr.setParkTtl(params.runConfig.hitlParkTtlMs)
+		// The claim this worker holds, if it took one. Without this hop the
+		// fence exists, the refusal exists, and no checkpoint a RUN writes ever
+		// carries a number — so a stalled worker is refused nowhere.
+		checkpointMgr.setClaimFence(params.claimFence)
 
 		// A question raised from inside a tool becomes a real checkpoint
 		// here. It used to park under a synthetic id nothing ever wrote, so

package/src/runtime/query/resume-run.ts

@@ -1,5 +1,5 @@
 import type { PendingDecision } from '../../types/hitl/index.js'
-import type { CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type { CheckpointStore, ClaimFence } from '../../types/run/checkpoint-store.js'
 import type { Run } from '../../types/run/entity.js'
 import type { RunState } from '../../types/run/state.js'
 import { type QueryParams, drainQuery } from './index.js'
@@ -38,6 +38,15 @@ export interface ResumeRunParams
 	readonly scope: RunStateScope
 	/** Required to find the checkpoint; also threaded into the resumed run. */
 	readonly checkpointStore: CheckpointStore
+
+	/**
+	 * The fence of the claim this worker took on the run before resuming.
+	 *
+	 * A resume is the one moment two workers are most likely to collide — it
+	 * is what a queue reader does with a parked run — so this is the call that
+	 * most needs to carry one.
+	 */
+	readonly claimFence?: ClaimFence
 	/**
 	 * Resume a specific checkpoint instead of the one the store would pick.
 	 * Absent means the parked checkpoint if there is one, else the newest.
@@ -67,7 +76,7 @@ export interface ResumeRunParams
  * resumed past without the answer it is waiting for.
  */
 export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome> {
-	const { scope, checkpointStore, checkpointId, pendingDecision, ...rest } = params
+	const { scope, checkpointStore, checkpointId, pendingDecision, claimFence, ...rest } = params
 
 	const state = await loadRunState(checkpointStore, scope, checkpointId)
 	if (!state?.checkpointId) return { resumed: false, reason: 'no-checkpoint' }
@@ -86,6 +95,7 @@ export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome>
 		runId: state.runId,
 		resumeFromCheckpoint: state.checkpointId,
 		checkpointStore,
+		...(claimFence !== undefined ? { claimFence } : {}),
 		...(pendingDecision ? { pendingDecision } : {}),
 	} as QueryParams)
 

package/src/store/index.ts

@@ -2,6 +2,7 @@ export { InMemoryStore } from './InMemoryStore.js'
 export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
 export { RunDiskStore } from './run/disk.js'
+export { InMemoryRunStore } from './run/memory.js'
 export { DiskCheckpointStore } from './run/checkpoint-disk.js'
 export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js'
 export { InMemoryCheckpointStore } from './run/checkpoint-memory.js'
@@ -17,8 +18,12 @@ export { InMemoryCheckpointStore } from './run/checkpoint-memory.js'
 // host has no use for is surface to keep correct forever for nobody.
 export {
 	assertContiguousListingScope,
+	claimRun,
+	fencedOut,
 	listDurableRuns,
 	paginateDurableRuns,
+	releaseRun,
+	toClaimSummary,
 	toDurableRunEntry,
 } from './run/listing.js'
 

package/src/store/run/checkpoint-disk.ts

@@ -7,14 +7,24 @@ import type {
 	CheckpointListingScope,
 	CheckpointRunScope,
 	CheckpointStore,
+	ClaimFence,
+	ClaimRunOptions,
 	DurableRunEntry,
 	DurableRunPage,
 	ListDurableRunsOptions,
+	RunClaim,
 } from '../../types/run/checkpoint-store.js'
 import type { RunStoreConfig } from '../../types/run/index.js'
 import type { ProjectId } from '../../types/session/ids.js'
+import { acquireClaim, currentFence, readClaim, releaseClaim } from './claim-disk.js'
 import { RunDiskStore, readCheckpointsIn } from './disk.js'
-import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+import {
+	assertContiguousListingScope,
+	fencedOut,
+	paginateDurableRuns,
+	toClaimSummary,
+	toDurableRunEntry,
+} from './listing.js'
 
 /**
  * The attribution a disk store's own layout does not record.
@@ -84,11 +94,47 @@ export class DiskCheckpointStore implements CheckpointStore {
 		return promise
 	}
 
-	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+	async writeCheckpoint(
+		scope: CheckpointRunScope,
+		checkpoint: IterationCheckpoint,
+		fence?: ClaimFence,
+	): Promise<void> {
 		const store = await this.bind(scope)
+		if (fence !== undefined) {
+			// Read at the moment of the write, not at the start of the run.
+			// A holder that stalled past its lease believes it still holds,
+			// and this is the only point at which it can be told otherwise.
+			// Names only, no parsing. The fence is the file name, so a corrupt
+			// body cannot make this check skip itself — which the previous shape
+			// did, at the one site whose entire job is refusing.
+			const current = await currentFence(this.runDir(scope))
+			if (fence < current) throw fencedOut(scope, fence, current)
+		}
 		await store.writeCheckpoint(checkpoint)
 	}
 
+	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null> {
+		return acquireClaim(this.runDir(scope), options)
+	}
+
+	async releaseRun(scope: CheckpointRunScope, fence: ClaimFence): Promise<void> {
+		await releaseClaim(this.runDir(scope), fence)
+	}
+
+	/**
+	 * The run's directory, resolved the same way `RunDiskStore.initRun` does.
+	 *
+	 * Duplicated rather than shared because the claim path must be derivable
+	 * WITHOUT binding a store — binding creates the directory, and a claim
+	 * read is a read. Kept beside the layout comment on `listDurableRuns` so
+	 * the two stay together if the layout ever moves.
+	 */
+	private runDir(scope: CheckpointRunScope): string {
+		return scope.parentRunId
+			? join(this.config.baseDir, scope.parentRunId, 'children', scope.runId)
+			: join(this.config.baseDir, scope.runId)
+	}
+
 	async readCheckpoint(
 		scope: CheckpointRunScope,
 		checkpointId: CheckpointId,
@@ -163,21 +209,40 @@ export class DiskCheckpointStore implements CheckpointStore {
 			const runDir = join(this.config.baseDir, runId)
 
 			const own = toDurableRunEntry({ ...attribution, runId }, await readCheckpointsIn(runDir), now)
-			if (own) entries.push(own)
+			if (own) entries.push(await this.withClaim(own, runDir, now))
 
 			for (const childId of await this.readRunDirs(join(runDir, 'children'))) {
+				const childDir = join(runDir, 'children', childId)
 				const child = toDurableRunEntry(
 					{ ...attribution, runId: childId, parentRunId: runId },
-					await readCheckpointsIn(join(runDir, 'children', childId)),
+					await readCheckpointsIn(childDir),
 					now,
 				)
-				if (child) entries.push(child)
+				if (child) entries.push(await this.withClaim(child, childDir, now))
 			}
 		}
 
 		return paginateDurableRuns(entries, options)
 	}
 
+	/**
+	 * Attach the run's claim to its listing row, judged against the page's
+	 * own clock so one page cannot disagree with itself about availability.
+	 */
+	private async withClaim(
+		entry: DurableRunEntry,
+		runDir: string,
+		now: number,
+	): Promise<DurableRunEntry> {
+		const claim = await readClaim(runDir)
+		// A holding whose body could not be read still appears on the row,
+		// carrying an expiry of 0 so it reads as available. Dropping the field
+		// entirely — which is what happened before — put the run under
+		// `claimed: false` by looking unclaimed rather than by being
+		// reclaimable, so a queue reader was told a wedged run was free work.
+		return claim ? { ...entry, claim: toClaimSummary(claim, now) } : entry
+	}
+
 	/** Directory names under `dir`, or none when `dir` does not exist. */
 	private async readRunDirs(dir: string): Promise<RunId[]> {
 		try {