@namzu/sdk 20.3.0 → 20.4.0

package/dist/store/run/listing.js

@@ -147,9 +147,16 @@ export function toDurableRunEntry(scope, checkpoints, now) {
  */
 export function paginateDurableRuns(entries, options) {
     const wanted = options?.park;
-    const filtered = wanted && wanted.length > 0
+    const byPark = wanted && wanted.length > 0
         ? entries.filter((e) => e.park !== undefined && wanted.includes(e.park.state))
         : entries;
+    // An expired claim counts as unheld. That is what expiry means, and a
+    // queue reader that treated an expired claim as held would leave a dead
+    // worker's runs invisible forever — the exact failure a lease exists to
+    // prevent, reintroduced by the filter that reads it.
+    const filtered = options?.claimed === undefined
+        ? byPark
+        : byPark.filter((e) => (e.claim !== undefined && !e.claim.expired) === options.claimed);
     // Both orders sort on a key that cannot move under a paging caller — see
     // the contract comment on `listDurableRuns`.
     const orderBy = options?.orderBy ?? 'runId';
@@ -239,4 +246,88 @@ export async function listDurableRuns(store, scope, options) {
     assertContiguousListingScope(scope, 'listDurableRuns');
     return store.listDurableRuns(scope, options);
 }
+/**
+ * Take working possession of a run, refusing when the store cannot arbitrate.
+ *
+ * The refusal is the entire safety property. `claimRun` is optional on the
+ * contract, and the natural way to reach an absent optional method is to skip
+ * it — which here means every worker proceeds, believing it holds a run
+ * nobody arbitrated. Two workers then restore the same checkpoint, both run
+ * the tools, and both write under one run id; half the work vanishes with no
+ * error anywhere.
+ *
+ * So a store with no claim support does not get "claimed by default". It gets
+ * an error naming the deployment shape it cannot support. A single-writer
+ * host never calls this and is unaffected.
+ *
+ * Returns `null` — not an error — when another holder has the run. That is
+ * the ordinary outcome of two readers on one queue, and a caller loops to the
+ * next run rather than handling a fault.
+ */
+export async function claimRun(store, scope, options) {
+    if (typeof store.claimRun !== 'function') {
+        throw new NamzuError({
+            code: 'capability_unavailable',
+            message: 'claimRun: the injected checkpoint store does not implement `claimRun`, so it cannot arbitrate between two workers taking the same run. Refusing rather than proceeding unclaimed — proceeding would let two workers restore one checkpoint, both execute its tools, and both write under one run id, which loses half the work and reports nothing. Supply a store that implements it, or run a single writer per run.',
+            details: { runId: scope.runId },
+        });
+    }
+    if (!Number.isFinite(options.ttlMs) || options.ttlMs <= 0) {
+        throw new NamzuError({
+            code: 'invalid_config',
+            message: `claimRun: ttlMs must be a positive number of milliseconds, got ${String(options.ttlMs)}. A lease that expires immediately is a lease every worker can take at once, which is the condition this call exists to prevent.`,
+            details: { runId: scope.runId, ttlMs: options.ttlMs },
+        });
+    }
+    return store.claimRun(scope, options);
+}
+/**
+ * Give a claim up early, refusing when the store cannot arbitrate.
+ *
+ * Refuses for the same reason as {@link claimRun}: a host that believes it is
+ * releasing a claim on a store that has none is a host that believes the
+ * whole mechanism is running.
+ */
+export async function releaseRun(store, scope, fence) {
+    if (typeof store.releaseRun !== 'function') {
+        throw new NamzuError({
+            code: 'capability_unavailable',
+            message: 'releaseRun: the injected checkpoint store does not implement `releaseRun`. A release that silently does nothing would leave the run held until its lease expires while the caller believes it is back on the queue.',
+            details: { runId: scope.runId },
+        });
+    }
+    return store.releaseRun(scope, fence);
+}
+/**
+ * The refusal a store raises when a write presents a superseded fence.
+ *
+ * Shared so both shipped stores say the same thing, and so a host writing its
+ * own backend raises something a caller can branch on rather than a message
+ * string. This is the moment a stalled worker learns it lost the run — the
+ * only moment it CAN learn, since from the inside a pause and a partition
+ * both look like time not passing.
+ */
+export function fencedOut(scope, presented, current) {
+    return new NamzuError({
+        code: 'storage_error',
+        message: `writeCheckpoint: refusing a write for run ${scope.runId} fenced at ${presented} — the run is now claimed at ${current}. Another worker took this run over, so this process no longer holds it and its work is not the record. Stop the run rather than retrying: the claim is gone, not busy.`,
+        details: { runId: scope.runId, presentedFence: presented, currentFence: current },
+        retryable: false,
+    });
+}
+/**
+ * Whether a recorded claim still holds at `now`, and the summary a listing
+ * reports for it.
+ */
+export function toClaimSummary(claim, now) {
+    return {
+        holder: claim.holder,
+        fence: claim.fence,
+        expiresAt: claim.expiresAt,
+        // Judged here, once, against the store's clock. Left to the caller it
+        // would be judged against a different one, and a single page could
+        // then disagree with itself about which rows are available.
+        expired: now >= claim.expiresAt,
+    };
+}
 //# sourceMappingURL=listing.js.map

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

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

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

@@ -167,6 +167,16 @@ export interface DurableRunEntry extends CheckpointRunScope {
     readonly latestCheckpointAt: number;
     /** Absent when the run has never parked. */
     readonly park?: ParkSummary;
+    /**
+     * Absent when no process has ever claimed the run.
+     *
+     * A SIBLING of {@link DurableRunEntry.park}, not a member of
+     * {@link ParkState} — see the note on that union. A park is a question put
+     * to a human; a claim is a lease held by a process. A run can have both,
+     * neither, or either, and the state a queue worker needs most is parked
+     * AND unclaimed, which one union cannot say.
+     */
+    readonly claim?: ClaimSummary;
 }
 /**
  * Which order a listing comes back in.
@@ -198,6 +208,61 @@ export type DurableRunOrder =
  * instead of a date nobody recorded.
  */
  | 'createdAt';
+/**
+ * A monotonically increasing number identifying one holding of a run's claim.
+ *
+ * The load-bearing word is *fencing*. A mutex answers "may I proceed", and a
+ * holder that stalls past its lease — a long GC pause, a suspended container,
+ * a partitioned network — answers it "yes" and then writes, long after
+ * somebody else legitimately took over. A fence answers a different question
+ * at the moment of the WRITE: "is the holding I belong to still the current
+ * one". Every claim of a run mints a number strictly greater than the last,
+ * so a store can reject a write from a superseded holder without knowing
+ * anything about processes, clocks or liveness.
+ *
+ * Not a random token, deliberately: randomness proves identity and cannot
+ * establish *order*, and order is the entire mechanism.
+ */
+export type ClaimFence = number;
+/** A holding of a run's claim, as issued to the process that took it. */
+export interface RunClaim {
+    /** Opaque caller-supplied identity — a worker id, a pod name. Evidence, not authority. */
+    readonly holder: string;
+    /** See {@link ClaimFence}. Present it on every durable write. */
+    readonly fence: ClaimFence;
+    /**
+     * Absolute epoch ms after which the claim may be taken by somebody else.
+     *
+     * Absolute rather than a duration for the same reason a park's deadline
+     * is: it has to survive the process that set it. A duration plus an
+     * in-process timer cannot — the holder is the thing that dies.
+     */
+    readonly expiresAt: number;
+}
+/** A run's claim as a listing reports it. */
+export interface ClaimSummary {
+    readonly holder: string;
+    readonly fence: ClaimFence;
+    readonly expiresAt: number;
+    /**
+     * Whether the claim had expired at the instant the listing was taken.
+     *
+     * A separate field rather than something the caller derives from
+     * `expiresAt`, because the caller would derive it against a DIFFERENT
+     * clock than the store used, and one page would then disagree with
+     * itself about which rows are available.
+     */
+    readonly expired: boolean;
+}
+/** What a caller asks for when taking a run. */
+export interface ClaimRunOptions {
+    /** Who is taking it. Recorded so an operator can see what holds a stuck run. */
+    readonly holder: string;
+    /** How long the holding is good for, in ms. */
+    readonly ttlMs: number;
+    /** Clock, for tests and so one operation judges every expiry against one instant. */
+    readonly now?: number;
+}
 /** Filters and paging for {@link CheckpointStore.listDurableRuns}. */
 export interface ListDurableRunsOptions {
     /**
@@ -212,6 +277,16 @@ export interface ListDurableRunsOptions {
      * to include it.
      */
     readonly park?: readonly ParkState[];
+    /**
+     * Keep only runs that are, or are not, currently held by a worker.
+     *
+     * `false` is the queue-reader's filter: give me the work nobody has. A
+     * claim that has expired counts as NOT held, because that is what expiry
+     * means and a reader that skipped expired claims would leave a dead
+     * worker's runs invisible forever — the exact failure the lease exists to
+     * prevent.
+     */
+    readonly claimed?: boolean;
     /** Page size. Defaults to 100, clamped to at least 1. */
     readonly limit?: number;
     /** Resume token from the previous page's {@link DurableRunPage.cursor}. */
@@ -266,8 +341,23 @@ export interface DurableRunPage {
  * proceed.
  */
 export interface CheckpointStore {
-    /** Persist one checkpoint. Overwrites an existing checkpoint with the same id. */
-    writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void>;
+    /**
+     * Persist one checkpoint. Overwrites an existing checkpoint with the same id.
+     *
+     * @param fence the {@link ClaimFence} of the holding this write belongs
+     *   to, when the run is claimed. A store that supports claims REFUSES a
+     *   write whose fence is below the run's current one — that refusal is
+     *   what makes a claim a lease rather than a suggestion, because a holder
+     *   stalled past its expiry believes it still holds and is wrong only at
+     *   the moment it writes.
+     *
+     *   Omit it and the write is unfenced, which is exactly today's behaviour
+     *   and correct for a single-writer deployment. A store MUST NOT start
+     *   refusing unfenced writes because some other write carried a fence:
+     *   that would make adding a claim to one worker break every worker that
+     *   has not adopted it yet.
+     */
+    writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint, fence?: ClaimFence): Promise<void>;
     /** Load a single checkpoint by id. Returns `null` when it does not exist. */
     readCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<IterationCheckpoint | null>;
     /**
@@ -319,5 +409,91 @@ export interface CheckpointStore {
      * @param options filters and paging. See {@link ListDurableRunsOptions}.
      */
     listDurableRuns?(scope: CheckpointListingScope, options?: ListDurableRunsOptions): Promise<DurableRunPage>;
+    /**
+     * Take exclusive working possession of a run, or report that somebody
+     * else has it. OPTIONAL — see the optional-capability rule on this
+     * interface.
+     *
+     * Returns the holding on success and `null` when the run is currently
+     * held by somebody else. `null` is not an error: "another worker got
+     * there first" is the ordinary outcome of a queue with more than one
+     * reader, and a thrown exception would make the normal case look like a
+     * fault.
+     *
+     * ### What it is for
+     *
+     * Putting parked runs on a queue and letting more than one worker drain
+     * it. Without this, two workers restore the same checkpoint, both execute
+     * the run's tools, and both write checkpoints under one run id — each
+     * write minting a fresh checkpoint id, so two divergent chains land in
+     * one list and the pending lookup returns whichever wrote last. Half the
+     * work vanishes and nothing reports an error.
+     *
+     * ### The lease, and why it expires
+     *
+     * A claim is a LEASE, not a lock. A lock held by a process that dies is
+     * held forever, and the runs behind it are unreachable by anything except
+     * a human with a shell. The expiry is what makes a dead holder's work
+     * recoverable without one.
+     *
+     * The expiry is also why a fence exists. A holder does not know it has
+     * expired — a long pause, a suspended container and a partition all look
+     * from the inside like time not passing — so it wakes and writes as
+     * though it still holds. Liveness cannot be checked from here. What CAN
+     * be checked, at the write, is whether the holding that write belongs to
+     * is still the current one, and that is a comparison of two numbers.
+     *
+     * ### Reclaiming
+     *
+     * Calling this on a run whose claim has expired SUCCEEDS and mints a
+     * fence strictly greater than the expired holding's. The previous holder
+     * is not notified — it cannot be, that is the premise — it simply stops
+     * being able to write.
+     *
+     * Calling it again as the CURRENT holder also succeeds and extends the
+     * lease, minting a new fence. Renewal and reclamation are the same
+     * operation from the store's side, which is why there is no separate
+     * `renew`: two code paths that must agree about who holds a run is one
+     * more than can be kept correct.
+     *
+     * ### What a backend implementing this MUST guarantee
+     *
+     * These are the properties the fence comparison depends on. None of them
+     * is checkable from here, and every one of them was violated by the first
+     * built-in implementation, so they are written down rather than assumed:
+     *
+     *  1. **A fence exceeds every fence ever issued for the run** — including
+     *     across a release, and across deletion of whatever recorded it. A
+     *     counter that rewinds re-issues a number a stalled worker still
+     *     believes it holds, and that worker's writes become legal again.
+     *  2. **Fences are unique.** The write check is `fence < current`, so two
+     *     holders at one number are both admitted. Equality is permissive
+     *     here, which makes a duplicate worse than a gap.
+     *  3. **The fence check is atomic with the write.** Reading the current
+     *     fence and then writing is check-then-act, and the gap is a race. A
+     *     database gets this free (`UPDATE … WHERE fence >= ?`); a filesystem
+     *     does not, and the built-in disk store narrows rather than closes it.
+     *  4. **`holder` is unique per process.** It is evidence rather than
+     *     authority, but it is the only thing distinguishing a RENEWAL from a
+     *     theft — two workers sharing a holder string take a live, unexpired
+     *     claim from each other instantly. Use something per-process, not a
+     *     per-deployment name.
+     */
+    claimRun?(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null>;
+    /**
+     * Give a claim up early. Idempotent: releasing a claim that already
+     * expired, was superseded, or never existed succeeds as a no-op.
+     *
+     * Presenting a stale fence releases NOTHING — a worker that stalled past
+     * its lease must not be able to hand away a run somebody else is now
+     * holding, and that is the same fencing comparison the write path makes.
+     *
+     * Optional to call, not optional to matter: a worker that finishes and
+     * releases returns the run to the queue immediately, where one that just
+     * exits leaves it stuck until the lease expires. That is a latency
+     * difference, never a correctness one, which is the property that lets a
+     * crashed worker be indistinguishable from a slow one.
+     */
+    releaseRun?(scope: CheckpointRunScope, fence: ClaimFence): Promise<void>;
 }
 //# sourceMappingURL=checkpoint-store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/types/run/checkpoint-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/types/run/checkpoint-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "20.3.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/public-runtime.ts

@@ -218,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/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,
@@ -413,6 +413,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
@@ -1013,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

@@ -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'