@namzu/sdk 20.3.0 → 21.0.0

package/src/runtime/query/events.ts

@@ -4,6 +4,7 @@ import { buildProbeContext } from '../../probe/context.js'
 import { type ProbeRegistry, probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ActivityEvent, ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
+import type { ClaimFence } from '../../types/run/checkpoint-store.js'
 import { isEphemeralEvent } from '../../types/run/events.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { TaskEvent, TaskStore } from '../../types/task/index.js'
@@ -37,6 +38,22 @@ export class EventTranslator {
 		this.probes = probeRegistry
 	}
 
+	/**
+	 * The claim this run is being written under, when it holds one.
+	 *
+	 * Stamped on every durable event as its `generation`, so a consumer whose
+	 * cursor predates a takeover is told its sequence space changed instead of
+	 * being handed a splice from a different writer's log.
+	 */
+	private generation: ClaimFence | undefined
+
+	/** Serializes sequence assignment against the append. See {@link emitEvent}. */
+	private appendChain: Promise<void> = Promise.resolve()
+
+	setGeneration(fence: ClaimFence | undefined): void {
+		this.generation = fence
+	}
+
 	readonly emitEvent: EmitEvent = async (event: RunEvent): Promise<void> => {
 		this.probes.dispatch(event, buildProbeContext({ runId: event.runId }))
 
@@ -64,15 +81,62 @@ export class EventTranslator {
 			// briefly than to drop a state transition.
 		}
 
-		this.pendingEvents.push(event)
-
 		// D1 middle path: ephemeral events never enter `transcript.jsonl`.
 		// They live only on the in-memory bus for live UI rendering.
 		// Replay (`runtime/query/replay/prepare.ts`) reads checkpoints
 		// not transcripts, so this preserves replay fidelity while
 		// eliminating the durable bloat review flagged.
-		if (!isEphemeralEvent(event)) {
-			await this.runMgr.getRunStore().appendEvent(event)
+		if (isEphemeralEvent(event)) {
+			// No number, and that is the honest statement: nothing will
+			// persist this, so a consumer must never advance a cursor to it.
+			this.pendingEvents.push(event)
+			return
+		}
+
+		// One appender at a time, and this is not a precaution — it is the fix
+		// for a measured defect. Taking the number, awaiting the write and then
+		// committing is a read-modify-write, and emits genuinely interleave:
+		// the task store, the plan manager and a batch of parallel tools all
+		// emit into this one funnel. Measured on a two-tool run, three events
+		// took the number 15 and two took 12. A duplicated sequence is worse
+		// than a missing one — a consumer asking for everything above 15 is
+		// handed part of the run it already had, spliced in as if it were new.
+		const previous = this.appendChain
+		let release!: () => void
+		this.appendChain = new Promise<void>((resolve) => {
+			release = resolve
+		})
+
+		try {
+			await previous
+
+			// The number is a claim that the event is IN the log, so it is taken
+			// against the append and not before it. The candidate goes to the
+			// store first; only a write that landed advances the counter and
+			// reaches the live stream carrying it.
+			//
+			// The failure path still delivers the event — unstamped. A store
+			// that cannot record a `run_failed` must not also swallow it, and an
+			// unstamped event says exactly what is true of it: it happened, and
+			// it is not recoverable.
+			const seq = this.runMgr.nextEventSeq()
+			const stamped = {
+				...event,
+				seq,
+				...(this.generation !== undefined ? { generation: this.generation } : {}),
+			} as RunEvent
+
+			try {
+				await this.runMgr.getRunStore().appendEvent(stamped)
+			} catch (err) {
+				this.pendingEvents.push(event)
+				throw err
+			}
+
+			this.runMgr.commitEventSeq(seq)
+			this.pendingEvents.push(stamped)
+		} finally {
+			release()
 		}
 	};
 

package/src/runtime/query/index.ts

@@ -15,6 +15,7 @@ import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire
 import type { CompactionConfig } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
+import type { RunPersistence } from '../../manager/run/persistence.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
 import {
 	type ProviderChainMember,
@@ -58,7 +59,9 @@ 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 { RunEventCursor, RunEventReplay } from '../../types/run/event-cursor.js'
+import { resolveRunEventReplay } from '../../types/run/event-cursor.js'
 import type {
 	AgentRunConfig,
 	PrepareStepChain,
@@ -413,6 +416,27 @@ 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
@@ -424,6 +448,43 @@ export interface QueryParams {
 	 */
 	runStore?: RunStore
 
+	/**
+	 * Where a reconnecting consumer left off, so this run's stream can start by
+	 * handing back what it missed.
+	 *
+	 * The case this serves is the one that exists without a network hop: the
+	 * process holding the run died, and the consumer watching it is coming back
+	 * to a run that has to be resumed. Pair it with `resumeFromCheckpoint` — or
+	 * reach it through {@link import('./resume-run.js').resumeRun}, which is the
+	 * surface that does both — and the missed durable events are yielded, in
+	 * order, before the resumed run emits anything of its own.
+	 *
+	 * On a run with no log to catch up on the cursor is answered honestly rather
+	 * than ignored: a `sinceSeq` above what exists is `cursor_ahead`, not
+	 * silence.
+	 *
+	 * What comes back is message-granular. Streaming deltas are never persisted
+	 * — see {@link import('../../types/run/store.js').RunStore.appendEvent} —
+	 * so a late subscriber recovers the assistant text, the tool results and the
+	 * lifecycle, not the keystroke cadence that produced them.
+	 */
+	eventCursor?: RunEventCursor
+
+	/**
+	 * What became of {@link QueryParams.eventCursor}.
+	 *
+	 * A callback rather than an event on the stream, because the answer is about
+	 * the SUBSCRIPTION and not about the run — and rather than a throw, because
+	 * a stale cursor is a client's problem and must not be able to stop a run
+	 * from continuing. A host that receives `unavailable` re-derives from the
+	 * transcript; one that receives nothing at all would splice a hole into its
+	 * state and never know.
+	 *
+	 * Called once, before the run's first event, and only when a cursor was
+	 * supplied.
+	 */
+	onEventReplay?: (replay: RunEventReplay) => void
+
 	runId?: RunId
 
 	parentRunId?: RunId
@@ -1013,6 +1074,14 @@ 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)
+		// And every EVENT it records carries the same fence as its generation,
+		// so a consumer whose cursor was minted under an older holding is told
+		// the sequence space changed rather than handed a splice from it.
+		eventTranslator.setGeneration(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
@@ -1090,6 +1159,20 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		try {
 			await ctx.runMgr.init()
 
+			// A consumer coming back gets what it missed BEFORE the run says
+			// anything new, which is the only order that lets it fold one
+			// stream into one state. It has to follow `init()` — that is what
+			// binds the store and reads the log's head — and precede every
+			// emit below.
+			if (params.eventCursor) {
+				yield* catchUpFromCursor(
+					ctx.runMgr,
+					params.eventCursor,
+					params.onEventReplay,
+					params.claimFence,
+				)
+			}
+
 			// Handed over here, and the position is load-bearing in BOTH
 			// directions. It has to follow `wirePlanManager`, or a host that
 			// builds its plan in this callback — which is what the callback is
@@ -1569,6 +1652,35 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	})()
 }
 
+/**
+ * Hand a returning consumer what it missed, or tell it why it cannot have it.
+ *
+ * Yields NOTHING on a refusal. A partial catch-up is the failure this exists to
+ * prevent: a consumer that receives some of the gap folds it into its state and
+ * cannot tell the state is wrong, where one that receives an explicit
+ * `unavailable` re-derives from the transcript and is right. The run continues
+ * either way — a stale cursor belongs to the client, and must not be able to
+ * stop the work.
+ */
+async function* catchUpFromCursor(
+	runMgr: RunPersistence,
+	cursor: RunEventCursor,
+	onEventReplay: ((replay: RunEventReplay) => void) | undefined,
+	generation: ClaimFence | undefined,
+): AsyncGenerator<RunEvent, void> {
+	const missed = await runMgr.getRunStore().readEvents({ sinceSeq: cursor.sinceSeq })
+	const replay = resolveRunEventReplay(
+		cursor,
+		{ lastSeq: runMgr.lastEventSeq, ...(generation !== undefined ? { generation } : {}) },
+		missed,
+	)
+
+	onEventReplay?.(replay)
+
+	if (replay.status !== 'replayed') return
+	for (const event of replay.events) yield event
+}
+
 export async function drainQuery(
 	params: Omit<QueryParams, 'resumeHandler'> & { resumeHandler?: ResumeHandler },
 	listener?: RunEventListener,

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

@@ -1,6 +1,8 @@
 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 { RunEventReplay } from '../../types/run/event-cursor.js'
+import type { RunEventListener } from '../../types/run/events.js'
 import type { RunState } from '../../types/run/state.js'
 import { type QueryParams, drainQuery } from './index.js'
 import { type RunStateScope, loadRunState } from './run-state.js'
@@ -23,7 +25,21 @@ export type ResumeOutcome =
 			readonly pending: PendingDecision
 			readonly state: RunState
 	  }
-	| { readonly resumed: true; readonly run: Run; readonly state: RunState }
+	| {
+			readonly resumed: true
+			readonly run: Run
+			readonly state: RunState
+			/**
+			 * What became of {@link ResumeRunParams.eventCursor}. Absent when no
+			 * cursor was supplied.
+			 *
+			 * Reported rather than thrown: a stale cursor is the client's
+			 * problem and the run still had to be resumed. A caller that sees
+			 * `unavailable` re-derives its view from the run's transcript
+			 * instead of folding a hole into it.
+			 */
+			readonly replay?: RunEventReplay
+	  }
 
 /**
  * The half of a run that cannot be serialized, plus where to look.
@@ -38,11 +54,34 @@ 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.
 	 */
 	readonly checkpointId?: RunState['checkpointId']
+
+	/**
+	 * Where to send the resumed run's events.
+	 *
+	 * This call had none, and the consequence was total: it drains the run to
+	 * completion and every event the run emits — every tool call, every park,
+	 * every token update — was discarded, because `drainQuery` forwards to a
+	 * listener and none was ever passed. So the one API for continuing a run
+	 * another process started could not show anybody what the run was doing.
+	 *
+	 * It is also what makes {@link ResumeRunParams.eventCursor} mean anything:
+	 * a catch-up delivered into a stream nobody receives is not a catch-up.
+	 */
+	readonly listener?: RunEventListener
 }
 
 /**
@@ -67,7 +106,16 @@ 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,
+		listener,
+		onEventReplay,
+		...rest
+	} = params
 
 	const state = await loadRunState(checkpointStore, scope, checkpointId)
 	if (!state?.checkpointId) return { resumed: false, reason: 'no-checkpoint' }
@@ -80,14 +128,31 @@ export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome>
 		return { resumed: false, reason: 'awaiting-decision', pending: outstanding, state }
 	}
 
-	const run = await drainQuery({
-		...rest,
-		messages: [],
-		runId: state.runId,
-		resumeFromCheckpoint: state.checkpointId,
-		checkpointStore,
-		...(pendingDecision ? { pendingDecision } : {}),
-	} as QueryParams)
+	let replay: RunEventReplay | undefined
+
+	const run = await drainQuery(
+		{
+			...rest,
+			messages: [],
+			runId: state.runId,
+			// Forwarded, and it is not cosmetic: the run store nests a sub-run's
+			// evidence under `<parent>/children/<run>`, so resuming a sub-run
+			// without this binds `<base>/<run>` instead — a second, empty
+			// transcript under a run id that already has one, a sequence that
+			// restarts at 1, and a catch-up that reports a live run as having
+			// produced nothing.
+			...(state.parentRunId !== undefined ? { parentRunId: state.parentRunId } : {}),
+			resumeFromCheckpoint: state.checkpointId,
+			checkpointStore,
+			...(claimFence !== undefined ? { claimFence } : {}),
+			...(pendingDecision ? { pendingDecision } : {}),
+			onEventReplay: (verdict: RunEventReplay) => {
+				replay = verdict
+				onEventReplay?.(verdict)
+			},
+		} as QueryParams,
+		listener,
+	)
 
-	return { resumed: true, run, state }
+	return { resumed: true, run, state, ...(replay !== undefined ? { replay } : {}) }
 }

package/src/store/index.ts

@@ -1,7 +1,7 @@
 export { InMemoryStore } from './InMemoryStore.js'
 export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
-export { RunDiskStore } from './run/disk.js'
+export { RunDiskStore, readRunEventsIn } 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'
@@ -18,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 {

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

@@ -3,11 +3,20 @@ import type {
 	CheckpointListingScope,
 	CheckpointRunScope,
 	CheckpointStore,
+	ClaimFence,
+	ClaimRunOptions,
 	DurableRunEntry,
 	DurableRunPage,
 	ListDurableRunsOptions,
+	RunClaim,
 } from '../../types/run/checkpoint-store.js'
-import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+import {
+	assertContiguousListingScope,
+	fencedOut,
+	paginateDurableRuns,
+	toClaimSummary,
+	toDurableRunEntry,
+} from './listing.js'
 
 /**
  * Process-local {@link CheckpointStore}, keyed by the full five-layer scope.
@@ -35,7 +44,111 @@ export class InMemoryCheckpointStore implements CheckpointStore {
 		return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/')
 	}
 
-	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+	/** `tenant/project/session/run` → the run's current holding, if any. */
+	private readonly claims = new Map<string, RunClaim>()
+
+	/**
+	 * The highest fence ever issued per run, kept separately from the claim.
+	 *
+	 * The claim is removed on release; this is not. That separation is the
+	 * whole point: the first version deleted the claim and then computed the
+	 * next fence from it, so releasing rewound the counter to 1 and a worker
+	 * stalled at fence 1 could write beside a new holder also at fence 1 —
+	 * and the documented `finally { releaseRun() }` did it on every pass.
+	 *
+	 * The disk store gets this property from file names that persist. In
+	 * memory the equivalent is a high-water mark nothing clears, and the two
+	 * must agree, because this class is what a host reads when writing a
+	 * backend of its own.
+	 */
+	private readonly highWater = new Map<string, ClaimFence>()
+
+	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null> {
+		const key = this.key(scope)
+		const now = options.now ?? Date.now()
+		const held = this.claims.get(key)
+
+		// Held by somebody else and still live. Not an error: two readers on
+		// one queue is the ordinary case.
+		if (held && now < held.expiresAt && held.holder !== options.holder) return null
+
+		// A reclaim of an expired holding and a renewal by the current holder
+		// are the same write. The fence advances either way, so a previous
+		// holder that wakes up is fenced out in both cases — a renewal that
+		// kept the fence would leave a stalled twin able to write.
+		// Counted from the high-water mark, never from the live claim. A
+		// released run has no claim, and computing from that absence is what
+		// rewound the counter to 1 on every release.
+		const fence = (this.highWater.get(key) ?? 0) + 1
+		const claim: RunClaim = { holder: options.holder, fence, expiresAt: now + options.ttlMs }
+		this.highWater.set(key, fence)
+		this.claims.set(key, claim)
+		return claim
+	}
+
+	async releaseRun(scope: CheckpointRunScope, fence: ClaimFence): Promise<void> {
+		const key = this.key(scope)
+		const held = this.claims.get(key)
+		// A stale fence releases nothing. A worker that stalled past its lease
+		// must not be able to hand away a run somebody else now holds.
+		//
+		// The high-water mark deliberately survives this. Dropping the claim
+		// returns the run to the queue; forgetting the number it reached would
+		// re-issue a fence a stalled worker still believes it holds.
+		if (!held || held.fence !== fence) return
+		this.claims.delete(key)
+		// And the counter steps past the released holding, because the disk
+		// store's release does: it appends a TOMBSTONE at `fence + 1`, which
+		// raises the maximum name and therefore the fence every later write is
+		// checked against. Without this step a holder that released could still
+		// write with the fence it just gave up — refused on disk, accepted here.
+		//
+		// The consequence is visible in the numbering: a released run's next
+		// claim is `fence + 2` in both stores, because the tombstone consumed
+		// one. That is parity, not an off-by-one.
+		this.highWater.set(key, fence + 1)
+	}
+
+	async writeCheckpoint(
+		scope: CheckpointRunScope,
+		checkpoint: IterationCheckpoint,
+		fence?: ClaimFence,
+	): Promise<void> {
+		const key = this.key(scope)
+		// An unfenced write is allowed even on a claimed run: a host adopting
+		// claims on one worker must not break the workers that have not
+		// adopted them. A fenced write is checked, and that check is what
+		// makes the lease real.
+		if (fence !== undefined) {
+			// Against the HIGH-WATER MARK, not the live claim, and the difference
+			// is a silent loss rather than a duplicate.
+			//
+			// `releaseRun` deletes the claim. Reading `claims` here meant that
+			// between a release and the next take there was no holding to
+			// compare against, so `held` was `undefined` and every fence was
+			// accepted however stale. w1 stalls at fence 1; w2 reclaims at 2,
+			// finishes the work, releases cleanly; w1 wakes and writes with
+			// fence 1 — accepted — and its checkpoint carries a fresh
+			// `createdAt`, so it sorts newest and the next resume restores w1's
+			// stale history. w2's completed work is gone, with no error
+			// anywhere.
+			//
+			// The disk store refuses that write, because `currentFence` reads
+			// file names and the release tombstone raised the maximum. The
+			// minting side here already counted from the high-water mark; only
+			// the enforcement side was left reading the claim, so the two
+			// shipped stores disagreed at the one point that decides whether a
+			// lease is real.
+			const current = this.highWater.get(key) ?? 0
+			if (fence < current) throw fencedOut(scope, fence, current)
+		}
+		return this.writeUnchecked(scope, checkpoint)
+	}
+
+	private async writeUnchecked(
+		scope: CheckpointRunScope,
+		checkpoint: IterationCheckpoint,
+	): Promise<void> {
 		const key = this.key(scope)
 		let run = this.runs.get(key)
 		if (!run) {
@@ -93,7 +206,9 @@ export class InMemoryCheckpointStore implements CheckpointStore {
 			if (scope.sessionId !== undefined && runScope.sessionId !== scope.sessionId) continue
 
 			const entry = toDurableRunEntry(runScope, [...checkpoints.values()], now)
-			if (entry) entries.push(entry)
+			if (!entry) continue
+			const claim = this.claims.get(key)
+			entries.push(claim ? { ...entry, claim: toClaimSummary(claim, now) } : entry)
 		}
 
 		return paginateDurableRuns(entries, options)