@tanstack/ai-sandbox 0.2.4 → 0.3.1

package/dist/esm/claim.d.ts

@@ -0,0 +1,187 @@
+import { LockStore } from '@tanstack/ai/locks';
+import { InternalLogger } from '@tanstack/ai/adapter-internals';
+import { RunStore, StreamDurability } from '@tanstack/ai';
+/** Quiescence window before a successor's first append. */
+export declare const DEFAULT_FENCE_QUIET_MS = 5000;
+/**
+ * Appends a fenced log makes between `driverEpoch` re-reads.
+ *
+ * Deliberately a COUNT, not an interval: `pipeToRunLog` appends one chunk per
+ * call, so this bounds a superseded driver to at most 31 further chunk batches
+ * (the bump can land immediately after a check) regardless of how fast the run
+ * streams. At 500 chunks/sec that worst case is ~62ms of writes; at 5
+ * chunks/sec it is ~6s of writes — either way 31 chunks, never ~1000.
+ *
+ * The cost of a smaller number is one extra `RunStore.get` per 32 chunks.
+ */
+export declare const DEFAULT_EPOCH_RECHECK_APPENDS = 32;
+/** Lock key for a run's driver. Per-run, so two runs never serialize. */
+export declare function runDriverLockKey(runId: string): string;
+/** The claim was never acquired, so the caller must not drive the run. */
+export declare class RunClaimNotAcquiredError extends Error {
+    readonly runId: string;
+    readonly reason: 'terminal' | 'unknown' | 'superseded';
+    constructor(runId: string, reason: 'terminal' | 'unknown' | 'superseded');
+}
+/** The claim was held and has been superseded; stop writing immediately. */
+export declare class RunClaimLostError extends Error {
+    readonly runId: string;
+    readonly heldEpoch: number;
+    readonly observedEpoch: number | 'lease-lost';
+    constructor(runId: string, heldEpoch: number, observedEpoch: number | 'lease-lost');
+}
+/** A held claim on one run. */
+export interface RunClaim {
+    runId: string;
+    /** This driver's fencing token; strictly greater than any predecessor's. */
+    epoch: number;
+    /** Aborts when the lock can no longer guarantee ownership. */
+    signal: AbortSignal;
+}
+export interface WithRunClaimOptions {
+    runs: RunStore;
+    locks: LockStore;
+    runId: string;
+    /**
+     * Quiescence window for {@link awaitLogQuiescence}. Defaults to
+     * {@link DEFAULT_FENCE_QUIET_MS}.
+     *
+     * `withRunClaim` itself does not read this: it has no durability handle. It
+     * lives here so a caller assembling a drive passes ONE options object to
+     * `withRunClaim`, `awaitLogQuiescence`, and {@link fenceDurability} instead of
+     * three that can drift apart.
+     */
+    fenceQuietMs?: number;
+    /**
+     * Forwarded to {@link fenceDurability}. Defaults to
+     * {@link DEFAULT_EPOCH_RECHECK_APPENDS}. Same rationale as `fenceQuietMs`.
+     */
+    epochRecheckAppends?: number;
+    logger?: InternalLogger;
+}
+/**
+ * Claim exclusive driver rights on `runId` for the duration of `fn`.
+ *
+ * The ENTIRE body runs inside the lock, so a snapshot taken by `fn` and every
+ * append that follows it sit in one critical section.
+ *
+ * Rejects with {@link RunClaimNotAcquiredError} when the run is unknown or
+ * already terminal — a terminal run has nothing left to drive, and bumping its
+ * epoch would fence out nobody while confusing an operator reading the record.
+ *
+ * The epoch is bumped INSIDE the lock and only after those checks pass, so a
+ * refused claim leaves `driverEpoch` untouched.
+ */
+export declare function withRunClaim<T>(options: WithRunClaimOptions, fn: (claim: RunClaim) => Promise<T>): Promise<T>;
+/**
+ * Wait until the stored log stops growing, then answer how many entries it
+ * holds.
+ *
+ * Uses `snapshot()`, never `read()`: `read` tails and only resolves once the log
+ * is terminalized or the caller aborts, and a taken-over run's log is open by
+ * definition — the host that would have closed it is the host that died.
+ *
+ * Rejects rather than looping forever. A log that never quiesces means a
+ * predecessor is still actively writing, which is a condition to surface, not to
+ * append into.
+ *
+ * This only detects a CONCURRENT predecessor, which means it can only fire when
+ * the two drivers are in different processes. Within one process an
+ * `InMemoryLockStore` serializes the claims, so the predecessor has already
+ * stopped by the time the successor probes.
+ */
+export declare function awaitLogQuiescence<TOffset extends string = string>(durability: StreamDurability<TOffset>, quietMs: number): Promise<number>;
+/**
+ * Wrap a log so every `append` is fenced by `claim`.
+ *
+ * `append` is the ONLY fenced method, deliberately:
+ *
+ * - `close()` must never be fenced. It runs on every teardown path including
+ *   the teardown caused by losing the claim, and a fenced `close` would leave
+ *   the record wedged at `'running'` with every live tailer parked forever (a
+ *   `read` only ends when the log closes).
+ * - `read` / `snapshot` / `resumeFrom` do not mutate, so a superseded host
+ *   reading them is harmless.
+ *
+ * The lease check is synchronous and happens before any I/O, so a fenced append
+ * cannot half-land. The epoch re-check is throttled to `epochRecheckAppends`
+ * because it costs a store read and the append path is hot.
+ *
+ * ONE REFUSAL CLOSES THE FENCE FOR GOOD. The first `append` that is refused —
+ * for EITHER cause, lost lease or moved epoch — latches this wrapper shut, and
+ * every later `append` refuses immediately without consulting the throttle and
+ * without a store read. This is not a nicety:
+ *
+ * - Losing a claim is not transient. Epochs only move forward and a lease is
+ *   never handed back, so a wrapper that has refused once can never legitimately
+ *   append again. Re-deciding per append can only produce a WRONG answer.
+ * - The throttle makes that wrong answer reachable. A refusal consumes the
+ *   re-read budget, so the very next append rides a fresh throttle window and is
+ *   NOT re-checked. `pipeToRunLog`'s recovery path appends a `RUN_ERROR` right
+ *   after the refusal it is recovering from, and that log belongs to the
+ *   SUCCESSOR: a terminal `RUN_ERROR` from a dead host would fail the stream for
+ *   every client attached to the live, healthy run.
+ * - It is also strictly cheaper: a latched boolean replaces a store read.
+ *
+ * The latch deliberately does NOT extend to `close()` — see above.
+ *
+ * PASSES THE OFFSET TYPE THROUGH, rather than collapsing it to `string`. The
+ * fence sits mid-chain between a caller's log and `pipeToRunLog`, so widening
+ * here would reintroduce the branded-offset wall one layer in: a
+ * `StreamDurability<DurableStreamOffset>` would go in and a
+ * `StreamDurability<string>` would come out, which is not assignable back to
+ * the caller's own type.
+ */
+export declare function fenceDurability<TOffset extends string = string>(durability: StreamDurability<TOffset>, claim: RunClaim, options: {
+    runs: RunStore;
+    epochRecheckAppends?: number;
+}): StreamDurability<TOffset>;
+/**
+ * Wrap a run store so a TERMINAL record write is fenced by `claim`.
+ *
+ * The record is the run's other authoritative channel, and the same rule applies
+ * to it: a host that has lost its claim must not state that the run is over. It
+ * reaches this seam by the most ordinary route — `pipeToRunLog` catches the
+ * `RunClaimLostError` its refused append threw, folds it in, and calls
+ * `finish(ctx, 'failed', …)` — so fencing the log alone only moves where the harm
+ * surfaces. `'completed'` and `'aborted'` arrive the same way (an empty stream
+ * that never appended; a lease loss that aborts `claim.signal`, which
+ * `pipeToRunLog` reads as an abort before it appends anything), which is why the
+ * gate is {@link isTerminalRunStatus} and not "did an append refuse".
+ *
+ * SUPPRESSED, NOT ATTEMPTED-AND-SWALLOWED, and not thrown either. `update`
+ * resolves without writing. `pipeToRunLog` must not reject — `RunController.start`
+ * consumes its promise fire-and-forget — and a rejection here would additionally
+ * make `finish` report the run through the local rebuilt record as if the store
+ * had broken, which is a different and false fact.
+ *
+ * WHAT IS *NOT* FENCED, deliberately:
+ *
+ * - **`close()`** is not on this seam at all, and must stay off it: see
+ *   {@link fenceDurability}. A wedged `'running'` record with tailers parked
+ *   forever is worse than the write being prevented.
+ * - **Non-terminal writes pass through**, including `detachedSince` and
+ *   `sandboxKey` written by a superseded host. They are stale, but staleness is
+ *   not the harm being fixed: none of them can make a live run look finished, so
+ *   none can mislead `isTerminalRunStatus`, `findActiveRun`, or the reaper. They
+ *   are also self-healing — the successor owns those fields and overwrites them —
+ *   whereas over-suppressing strands a record: `createOrResume` is how the row
+ *   comes into existence at all, and refusing a non-terminal write on a
+ *   mis-observed loss would leave a run with no record to recover from. Suppress
+ *   the writes that assert an outcome; let bookkeeping through.
+ * - **Reads** (`get`, `listByThread`, `listReclaimable`, `findActiveRun`) do not
+ *   mutate, so a superseded host reading them is harmless. `finish`'s terminal
+ *   re-read therefore still works and answers with the SUCCESSOR's live record,
+ *   which is the truthful thing to resolve with.
+ * - **Another run's record.** The fence knows about `claim.runId` only; a write
+ *   aimed elsewhere is not this claim's to judge.
+ *
+ * The OPTIONAL methods (`listByThread`, `listReclaimable`) are forwarded only
+ * when the wrapped store actually has them: consumers feature-detect
+ * (`store.listReclaimable?.(…)`), so materializing one that delegates to a
+ * missing method would turn a graceful degrade into a `TypeError`.
+ * `findActiveRun` is required on the contract, so it forwards unconditionally.
+ */
+export declare function fenceRunStore(runs: RunStore, claim: RunClaim, options?: {
+    logger?: InternalLogger;
+}): RunStore;

package/dist/esm/claim.js

@@ -0,0 +1,349 @@
+import { isTerminalRunStatus } from "@tanstack/ai";
+//#region src/claim.ts
+/**
+* The single-writer claim: what makes a takeover safe to attempt at all.
+*
+* WHY THIS MODULE EXISTS. `alignToStoredLog` decides where its appends start by
+* reading `durability.snapshot()`, and `snapshot()` carries NO LOCK — core says
+* so explicitly (`packages/ai/src/stream-durability.ts`: "a concurrent `append`
+* may land immediately after the snapshot is taken"). If two hosts drive one
+* run, both snapshot, both compute a "remainder", and both append it. The log
+* then holds the same logical chunk twice under two different offsets, and the
+* client CANNOT survive that: `ai-client`'s de-dup is keyed on the adapter's
+* offset string, so a re-appended chunk looks new, and the stream processor
+* applies text and tool-argument deltas unconditionally. The visible result is
+* doubled message text and `{"a":1}{"a":1}` tool arguments.
+*
+* Takeover is by definition two hosts wanting one run, so nothing may read a
+* journal for a run it has not claimed.
+*
+* THREE LAYERS, strongest first:
+*
+* 1. **The lease.** {@link withRunClaim} runs the whole drive inside
+*    `LockStore.withLock('run-driver:<runId>', …)`, so the snapshot and every
+*    append that follows are one critical section. A lease-backed lock aborts
+*    the callback signal the moment ownership is lost, and
+*    {@link fenceDurability} turns that into a thrown {@link RunClaimLostError}
+*    BEFORE the append reaches the log.
+* 2. **The epoch.** Each successful claim bumps `RunRecord.driverEpoch`.
+*    {@link fenceDurability} re-reads it every
+*    {@link DEFAULT_EPOCH_RECHECK_APPENDS} appends and refuses to append once a
+*    higher epoch exists. This covers what a lease cannot: an
+*    `InMemoryLockStore`, whose signal is a fresh `AbortController().signal`
+*    that is never aborted, and any backend whose renewal is coarser than the
+*    run's append rate. Once EITHER fence has refused an append, the fence
+*    latches shut and every later append refuses without re-reading anything.
+* 3. **Quiescence.** {@link awaitLogQuiescence} requires the stored log to stop
+*    growing before the successor appends anything, so a predecessor that is
+*    still writing is OBSERVED rather than raced.
+*
+* THE LOG IS NOT THE ONLY AUTHORITATIVE CHANNEL. A host that has lost its claim
+* must not write authoritative facts about the run through ANY seam, and there
+* are two: the event log and the run RECORD. Fencing only the log moves the harm
+* rather than removing it — a superseded driver whose append was refused folds
+* that refusal into a terminal `runs.update`, so the record reads `'failed'` for
+* a run the successor is healthily streaming, and `isTerminalRunStatus` (which
+* `findActiveRun`, the resume driver, and `reapDetachedRuns` all branch on) then
+* answers `true` for a live run. {@link fenceRunStore} closes that seam; both
+* fences share one per-claim latch so they can never disagree about whether the
+* claim is still held.
+*
+* WHY THE EPOCH RE-CHECK COUNTS APPENDS, NOT MILLISECONDS. `pipeToRunLog`
+* appends ONE chunk per call, so a time-based interval couples the fence's
+* resolution to the run's chunk rate: at 500 chunks/sec a 2s interval lets a
+* superseded driver write ~1000 chunks before it notices. A count gives a hard
+* bound independent of rate — see {@link DEFAULT_EPOCH_RECHECK_APPENDS}.
+*
+* WHAT THIS IS NOT. It is not airtight fencing.
+*
+* - A predecessor paused (GC, VM suspend) for longer than the quiescence
+*   window, between its last fence check and its append landing at the backend,
+*   can still write one batch. Closing that requires a compare-and-set on the
+*   durability write; `StreamDurability.append` has no such parameter and this
+*   phase deliberately does not add one.
+* - Layer 3 is only meaningful across PROCESSES. On a single-process
+*   `InMemoryLockStore` the two claims are serialized by the lock, not
+*   concurrent, so `awaitLogQuiescence` can never observe a predecessor still
+*   writing there — and consequently no unit test on that backend proves layer
+*   3 does anything. What the tests do prove on that backend is layer 2.
+*
+* The mitigation for both is deployment-level: use a lease-backed distributed
+* `LockStore`, and keep `fenceQuietMs` above the lease's renewal interval.
+*/
+/** Quiescence window before a successor's first append. */
+var DEFAULT_FENCE_QUIET_MS = 5e3;
+/** Probes {@link awaitLogQuiescence} makes before giving up. */
+var MAX_QUIESCENCE_PROBES = 6;
+/** Lock key for a run's driver. Per-run, so two runs never serialize. */
+function runDriverLockKey(runId) {
+	return `run-driver:${runId}`;
+}
+/** The claim was never acquired, so the caller must not drive the run. */
+var RunClaimNotAcquiredError = class extends Error {
+	runId;
+	reason;
+	constructor(runId, reason) {
+		super(`run ${runId}: driver claim not acquired (${reason})`);
+		this.runId = runId;
+		this.reason = reason;
+		this.name = "RunClaimNotAcquiredError";
+	}
+};
+/** The claim was held and has been superseded; stop writing immediately. */
+var RunClaimLostError = class extends Error {
+	runId;
+	heldEpoch;
+	observedEpoch;
+	constructor(runId, heldEpoch, observedEpoch) {
+		super(`run ${runId}: driver claim lost (held epoch ${heldEpoch}, observed ${observedEpoch})`);
+		this.runId = runId;
+		this.heldEpoch = heldEpoch;
+		this.observedEpoch = observedEpoch;
+		this.name = "RunClaimLostError";
+	}
+};
+/**
+* Claim exclusive driver rights on `runId` for the duration of `fn`.
+*
+* The ENTIRE body runs inside the lock, so a snapshot taken by `fn` and every
+* append that follows it sit in one critical section.
+*
+* Rejects with {@link RunClaimNotAcquiredError} when the run is unknown or
+* already terminal — a terminal run has nothing left to drive, and bumping its
+* epoch would fence out nobody while confusing an operator reading the record.
+*
+* The epoch is bumped INSIDE the lock and only after those checks pass, so a
+* refused claim leaves `driverEpoch` untouched.
+*/
+async function withRunClaim(options, fn) {
+	const { runs, locks, runId, logger } = options;
+	return locks.withLock(runDriverLockKey(runId), async (signal) => {
+		const record = await runs.get(runId);
+		if (record === null) throw new RunClaimNotAcquiredError(runId, "unknown");
+		if (isTerminalRunStatus(record.status)) throw new RunClaimNotAcquiredError(runId, "terminal");
+		const epoch = (record.driverEpoch ?? 0) + 1;
+		await runs.update(runId, { driverEpoch: epoch });
+		logger?.sandbox(`run ${runId}: driver claim acquired at epoch ${epoch}`, {
+			runId,
+			epoch
+		});
+		return fn({
+			runId,
+			epoch,
+			signal
+		});
+	});
+}
+/**
+* Wait until the stored log stops growing, then answer how many entries it
+* holds.
+*
+* Uses `snapshot()`, never `read()`: `read` tails and only resolves once the log
+* is terminalized or the caller aborts, and a taken-over run's log is open by
+* definition — the host that would have closed it is the host that died.
+*
+* Rejects rather than looping forever. A log that never quiesces means a
+* predecessor is still actively writing, which is a condition to surface, not to
+* append into.
+*
+* This only detects a CONCURRENT predecessor, which means it can only fire when
+* the two drivers are in different processes. Within one process an
+* `InMemoryLockStore` serializes the claims, so the predecessor has already
+* stopped by the time the successor probes.
+*/
+async function awaitLogQuiescence(durability, quietMs) {
+	let previous = (await durability.snapshot()).length;
+	for (let probe = 0; probe < MAX_QUIESCENCE_PROBES; probe += 1) {
+		await sleep(quietMs);
+		const current = (await durability.snapshot()).length;
+		if (current === previous) return current;
+		previous = current;
+	}
+	throw new Error(`journal takeover: the event log never quiesced after ${MAX_QUIESCENCE_PROBES} probes (${previous} entries and still growing); another host is still driving this run`);
+}
+function sleep(ms) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var CLAIM_LATCHES = /* @__PURE__ */ new WeakMap();
+function latchFor(claim) {
+	const existing = CLAIM_LATCHES.get(claim);
+	if (existing !== void 0) return existing;
+	const latch = { lost: void 0 };
+	CLAIM_LATCHES.set(claim, latch);
+	return latch;
+}
+/**
+* The I/O-free half of the check: the latch and the lease. Synchronous on
+* purpose — a fenced write must be refused BEFORE anything can half-land.
+*/
+function claimLostSynchronously(claim, latch) {
+	if (latch.lost !== void 0) return latch.lost;
+	if (claim.signal.aborted) {
+		latch.lost = new RunClaimLostError(claim.runId, claim.epoch, "lease-lost");
+		return latch.lost;
+	}
+}
+/**
+* The other half: re-read `driverEpoch` and refuse once a successor exists.
+*
+* A store failure is NOT treated as loss. The lease is the primary fence and it
+* has not fired, so fencing ourselves out on a store blip would kill a healthy
+* driver — and, for the record fence, would suppress a legitimate terminal write
+* and strand the run at `'running'`, which is worse than the write it prevents.
+*/
+async function claimLostByEpoch(claim, latch, runs) {
+	let observed;
+	try {
+		observed = (await runs.get(claim.runId))?.driverEpoch;
+	} catch {
+		return;
+	}
+	if (observed !== void 0 && observed > claim.epoch) {
+		latch.lost = new RunClaimLostError(claim.runId, claim.epoch, observed);
+		return latch.lost;
+	}
+}
+/**
+* Wrap a log so every `append` is fenced by `claim`.
+*
+* `append` is the ONLY fenced method, deliberately:
+*
+* - `close()` must never be fenced. It runs on every teardown path including
+*   the teardown caused by losing the claim, and a fenced `close` would leave
+*   the record wedged at `'running'` with every live tailer parked forever (a
+*   `read` only ends when the log closes).
+* - `read` / `snapshot` / `resumeFrom` do not mutate, so a superseded host
+*   reading them is harmless.
+*
+* The lease check is synchronous and happens before any I/O, so a fenced append
+* cannot half-land. The epoch re-check is throttled to `epochRecheckAppends`
+* because it costs a store read and the append path is hot.
+*
+* ONE REFUSAL CLOSES THE FENCE FOR GOOD. The first `append` that is refused —
+* for EITHER cause, lost lease or moved epoch — latches this wrapper shut, and
+* every later `append` refuses immediately without consulting the throttle and
+* without a store read. This is not a nicety:
+*
+* - Losing a claim is not transient. Epochs only move forward and a lease is
+*   never handed back, so a wrapper that has refused once can never legitimately
+*   append again. Re-deciding per append can only produce a WRONG answer.
+* - The throttle makes that wrong answer reachable. A refusal consumes the
+*   re-read budget, so the very next append rides a fresh throttle window and is
+*   NOT re-checked. `pipeToRunLog`'s recovery path appends a `RUN_ERROR` right
+*   after the refusal it is recovering from, and that log belongs to the
+*   SUCCESSOR: a terminal `RUN_ERROR` from a dead host would fail the stream for
+*   every client attached to the live, healthy run.
+* - It is also strictly cheaper: a latched boolean replaces a store read.
+*
+* The latch deliberately does NOT extend to `close()` — see above.
+*
+* PASSES THE OFFSET TYPE THROUGH, rather than collapsing it to `string`. The
+* fence sits mid-chain between a caller's log and `pipeToRunLog`, so widening
+* here would reintroduce the branded-offset wall one layer in: a
+* `StreamDurability<DurableStreamOffset>` would go in and a
+* `StreamDurability<string>` would come out, which is not assignable back to
+* the caller's own type.
+*/
+function fenceDurability(durability, claim, options) {
+	const recheckAppends = Math.max(1, Math.trunc(options.epochRecheckAppends ?? 32));
+	let appendsSinceEpochRead = recheckAppends;
+	const latch = latchFor(claim);
+	async function assertHeld() {
+		const synchronous = claimLostSynchronously(claim, latch);
+		if (synchronous !== void 0) throw synchronous;
+		if (appendsSinceEpochRead < recheckAppends) {
+			appendsSinceEpochRead += 1;
+			return;
+		}
+		appendsSinceEpochRead = 1;
+		const byEpoch = await claimLostByEpoch(claim, latch, options.runs);
+		if (byEpoch !== void 0) throw byEpoch;
+	}
+	return {
+		resumeFrom: () => durability.resumeFrom(),
+		append: async (chunks) => {
+			await assertHeld();
+			return durability.append(chunks);
+		},
+		read: (offset, signal) => durability.read(offset, signal),
+		close: () => durability.close(),
+		snapshot: () => durability.snapshot()
+	};
+}
+/**
+* Wrap a run store so a TERMINAL record write is fenced by `claim`.
+*
+* The record is the run's other authoritative channel, and the same rule applies
+* to it: a host that has lost its claim must not state that the run is over. It
+* reaches this seam by the most ordinary route — `pipeToRunLog` catches the
+* `RunClaimLostError` its refused append threw, folds it in, and calls
+* `finish(ctx, 'failed', …)` — so fencing the log alone only moves where the harm
+* surfaces. `'completed'` and `'aborted'` arrive the same way (an empty stream
+* that never appended; a lease loss that aborts `claim.signal`, which
+* `pipeToRunLog` reads as an abort before it appends anything), which is why the
+* gate is {@link isTerminalRunStatus} and not "did an append refuse".
+*
+* SUPPRESSED, NOT ATTEMPTED-AND-SWALLOWED, and not thrown either. `update`
+* resolves without writing. `pipeToRunLog` must not reject — `RunController.start`
+* consumes its promise fire-and-forget — and a rejection here would additionally
+* make `finish` report the run through the local rebuilt record as if the store
+* had broken, which is a different and false fact.
+*
+* WHAT IS *NOT* FENCED, deliberately:
+*
+* - **`close()`** is not on this seam at all, and must stay off it: see
+*   {@link fenceDurability}. A wedged `'running'` record with tailers parked
+*   forever is worse than the write being prevented.
+* - **Non-terminal writes pass through**, including `detachedSince` and
+*   `sandboxKey` written by a superseded host. They are stale, but staleness is
+*   not the harm being fixed: none of them can make a live run look finished, so
+*   none can mislead `isTerminalRunStatus`, `findActiveRun`, or the reaper. They
+*   are also self-healing — the successor owns those fields and overwrites them —
+*   whereas over-suppressing strands a record: `createOrResume` is how the row
+*   comes into existence at all, and refusing a non-terminal write on a
+*   mis-observed loss would leave a run with no record to recover from. Suppress
+*   the writes that assert an outcome; let bookkeeping through.
+* - **Reads** (`get`, `listByThread`, `listReclaimable`, `findActiveRun`) do not
+*   mutate, so a superseded host reading them is harmless. `finish`'s terminal
+*   re-read therefore still works and answers with the SUCCESSOR's live record,
+*   which is the truthful thing to resolve with.
+* - **Another run's record.** The fence knows about `claim.runId` only; a write
+*   aimed elsewhere is not this claim's to judge.
+*
+* The OPTIONAL methods (`listByThread`, `listReclaimable`) are forwarded only
+* when the wrapped store actually has them: consumers feature-detect
+* (`store.listReclaimable?.(…)`), so materializing one that delegates to a
+* missing method would turn a graceful degrade into a `TypeError`.
+* `findActiveRun` is required on the contract, so it forwards unconditionally.
+*/
+function fenceRunStore(runs, claim, options = {}) {
+	const latch = latchFor(claim);
+	const listByThread = runs.listByThread?.bind(runs);
+	const listReclaimable = runs.listReclaimable?.bind(runs);
+	return {
+		createOrResume: (input) => runs.createOrResume(input),
+		get: (runId) => runs.get(runId),
+		findActiveRun: (threadId) => runs.findActiveRun(threadId),
+		update: async (runId, patch) => {
+			const status = patch.status;
+			if (runId !== claim.runId || status === void 0 || !isTerminalRunStatus(status)) return runs.update(runId, patch);
+			const lost = claimLostSynchronously(claim, latch) ?? await claimLostByEpoch(claim, latch, runs);
+			if (lost === void 0) return runs.update(runId, patch);
+			try {
+				options.logger?.sandbox(`run ${runId}: suppressed a terminal '${status}' record write from a superseded driver`, {
+					runId,
+					status,
+					heldEpoch: claim.epoch,
+					error: lost
+				});
+			} catch {}
+		},
+		...listByThread === void 0 ? {} : { listByThread },
+		...listReclaimable === void 0 ? {} : { listReclaimable }
+	};
+}
+//#endregion
+export { DEFAULT_FENCE_QUIET_MS, RunClaimLostError, RunClaimNotAcquiredError, awaitLogQuiescence, fenceDurability, fenceRunStore, runDriverLockKey, withRunClaim };
+
+//# sourceMappingURL=claim.js.map

package/dist/esm/claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.js","names":[],"sources":["../../src/claim.ts"],"sourcesContent":["/**\n * The single-writer claim: what makes a takeover safe to attempt at all.\n *\n * WHY THIS MODULE EXISTS. `alignToStoredLog` decides where its appends start by\n * reading `durability.snapshot()`, and `snapshot()` carries NO LOCK — core says\n * so explicitly (`packages/ai/src/stream-durability.ts`: \"a concurrent `append`\n * may land immediately after the snapshot is taken\"). If two hosts drive one\n * run, both snapshot, both compute a \"remainder\", and both append it. The log\n * then holds the same logical chunk twice under two different offsets, and the\n * client CANNOT survive that: `ai-client`'s de-dup is keyed on the adapter's\n * offset string, so a re-appended chunk looks new, and the stream processor\n * applies text and tool-argument deltas unconditionally. The visible result is\n * doubled message text and `{\"a\":1}{\"a\":1}` tool arguments.\n *\n * Takeover is by definition two hosts wanting one run, so nothing may read a\n * journal for a run it has not claimed.\n *\n * THREE LAYERS, strongest first:\n *\n * 1. **The lease.** {@link withRunClaim} runs the whole drive inside\n *    `LockStore.withLock('run-driver:<runId>', …)`, so the snapshot and every\n *    append that follows are one critical section. A lease-backed lock aborts\n *    the callback signal the moment ownership is lost, and\n *    {@link fenceDurability} turns that into a thrown {@link RunClaimLostError}\n *    BEFORE the append reaches the log.\n * 2. **The epoch.** Each successful claim bumps `RunRecord.driverEpoch`.\n *    {@link fenceDurability} re-reads it every\n *    {@link DEFAULT_EPOCH_RECHECK_APPENDS} appends and refuses to append once a\n *    higher epoch exists. This covers what a lease cannot: an\n *    `InMemoryLockStore`, whose signal is a fresh `AbortController().signal`\n *    that is never aborted, and any backend whose renewal is coarser than the\n *    run's append rate. Once EITHER fence has refused an append, the fence\n *    latches shut and every later append refuses without re-reading anything.\n * 3. **Quiescence.** {@link awaitLogQuiescence} requires the stored log to stop\n *    growing before the successor appends anything, so a predecessor that is\n *    still writing is OBSERVED rather than raced.\n *\n * THE LOG IS NOT THE ONLY AUTHORITATIVE CHANNEL. A host that has lost its claim\n * must not write authoritative facts about the run through ANY seam, and there\n * are two: the event log and the run RECORD. Fencing only the log moves the harm\n * rather than removing it — a superseded driver whose append was refused folds\n * that refusal into a terminal `runs.update`, so the record reads `'failed'` for\n * a run the successor is healthily streaming, and `isTerminalRunStatus` (which\n * `findActiveRun`, the resume driver, and `reapDetachedRuns` all branch on) then\n * answers `true` for a live run. {@link fenceRunStore} closes that seam; both\n * fences share one per-claim latch so they can never disagree about whether the\n * claim is still held.\n *\n * WHY THE EPOCH RE-CHECK COUNTS APPENDS, NOT MILLISECONDS. `pipeToRunLog`\n * appends ONE chunk per call, so a time-based interval couples the fence's\n * resolution to the run's chunk rate: at 500 chunks/sec a 2s interval lets a\n * superseded driver write ~1000 chunks before it notices. A count gives a hard\n * bound independent of rate — see {@link DEFAULT_EPOCH_RECHECK_APPENDS}.\n *\n * WHAT THIS IS NOT. It is not airtight fencing.\n *\n * - A predecessor paused (GC, VM suspend) for longer than the quiescence\n *   window, between its last fence check and its append landing at the backend,\n *   can still write one batch. Closing that requires a compare-and-set on the\n *   durability write; `StreamDurability.append` has no such parameter and this\n *   phase deliberately does not add one.\n * - Layer 3 is only meaningful across PROCESSES. On a single-process\n *   `InMemoryLockStore` the two claims are serialized by the lock, not\n *   concurrent, so `awaitLogQuiescence` can never observe a predecessor still\n *   writing there — and consequently no unit test on that backend proves layer\n *   3 does anything. What the tests do prove on that backend is layer 2.\n *\n * The mitigation for both is deployment-level: use a lease-backed distributed\n * `LockStore`, and keep `fenceQuietMs` above the lease's renewal interval.\n */\nimport { isTerminalRunStatus } from '@tanstack/ai'\nimport type { LockStore } from '@tanstack/ai/locks'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { RunStore, StreamChunk, StreamDurability } from '@tanstack/ai'\n\n/** Quiescence window before a successor's first append. */\nexport const DEFAULT_FENCE_QUIET_MS = 5_000\n\n/**\n * Appends a fenced log makes between `driverEpoch` re-reads.\n *\n * Deliberately a COUNT, not an interval: `pipeToRunLog` appends one chunk per\n * call, so this bounds a superseded driver to at most 31 further chunk batches\n * (the bump can land immediately after a check) regardless of how fast the run\n * streams. At 500 chunks/sec that worst case is ~62ms of writes; at 5\n * chunks/sec it is ~6s of writes — either way 31 chunks, never ~1000.\n *\n * The cost of a smaller number is one extra `RunStore.get` per 32 chunks.\n */\nexport const DEFAULT_EPOCH_RECHECK_APPENDS = 32\n\n/** Probes {@link awaitLogQuiescence} makes before giving up. */\nconst MAX_QUIESCENCE_PROBES = 6\n\n/** Lock key for a run's driver. Per-run, so two runs never serialize. */\nexport function runDriverLockKey(runId: string): string {\n  return `run-driver:${runId}`\n}\n\n/** The claim was never acquired, so the caller must not drive the run. */\nexport class RunClaimNotAcquiredError extends Error {\n  constructor(\n    readonly runId: string,\n    readonly reason: 'terminal' | 'unknown' | 'superseded',\n  ) {\n    super(`run ${runId}: driver claim not acquired (${reason})`)\n    this.name = 'RunClaimNotAcquiredError'\n  }\n}\n\n/** The claim was held and has been superseded; stop writing immediately. */\nexport class RunClaimLostError extends Error {\n  constructor(\n    readonly runId: string,\n    readonly heldEpoch: number,\n    readonly observedEpoch: number | 'lease-lost',\n  ) {\n    super(\n      `run ${runId}: driver claim lost (held epoch ${heldEpoch}, observed ${observedEpoch})`,\n    )\n    this.name = 'RunClaimLostError'\n  }\n}\n\n/** A held claim on one run. */\nexport interface RunClaim {\n  runId: string\n  /** This driver's fencing token; strictly greater than any predecessor's. */\n  epoch: number\n  /** Aborts when the lock can no longer guarantee ownership. */\n  signal: AbortSignal\n}\n\nexport interface WithRunClaimOptions {\n  runs: RunStore\n  locks: LockStore\n  runId: string\n  /**\n   * Quiescence window for {@link awaitLogQuiescence}. Defaults to\n   * {@link DEFAULT_FENCE_QUIET_MS}.\n   *\n   * `withRunClaim` itself does not read this: it has no durability handle. It\n   * lives here so a caller assembling a drive passes ONE options object to\n   * `withRunClaim`, `awaitLogQuiescence`, and {@link fenceDurability} instead of\n   * three that can drift apart.\n   */\n  fenceQuietMs?: number\n  /**\n   * Forwarded to {@link fenceDurability}. Defaults to\n   * {@link DEFAULT_EPOCH_RECHECK_APPENDS}. Same rationale as `fenceQuietMs`.\n   */\n  epochRecheckAppends?: number\n  logger?: InternalLogger\n}\n\n/**\n * Claim exclusive driver rights on `runId` for the duration of `fn`.\n *\n * The ENTIRE body runs inside the lock, so a snapshot taken by `fn` and every\n * append that follows it sit in one critical section.\n *\n * Rejects with {@link RunClaimNotAcquiredError} when the run is unknown or\n * already terminal — a terminal run has nothing left to drive, and bumping its\n * epoch would fence out nobody while confusing an operator reading the record.\n *\n * The epoch is bumped INSIDE the lock and only after those checks pass, so a\n * refused claim leaves `driverEpoch` untouched.\n */\nexport async function withRunClaim<T>(\n  options: WithRunClaimOptions,\n  fn: (claim: RunClaim) => Promise<T>,\n): Promise<T> {\n  const { runs, locks, runId, logger } = options\n  return locks.withLock(runDriverLockKey(runId), async (signal) => {\n    const record = await runs.get(runId)\n    if (record === null) {\n      throw new RunClaimNotAcquiredError(runId, 'unknown')\n    }\n    if (isTerminalRunStatus(record.status)) {\n      throw new RunClaimNotAcquiredError(runId, 'terminal')\n    }\n    const epoch = (record.driverEpoch ?? 0) + 1\n    await runs.update(runId, { driverEpoch: epoch })\n    logger?.sandbox(`run ${runId}: driver claim acquired at epoch ${epoch}`, {\n      runId,\n      epoch,\n    })\n    return fn({ runId, epoch, signal })\n  })\n}\n\n/**\n * Wait until the stored log stops growing, then answer how many entries it\n * holds.\n *\n * Uses `snapshot()`, never `read()`: `read` tails and only resolves once the log\n * is terminalized or the caller aborts, and a taken-over run's log is open by\n * definition — the host that would have closed it is the host that died.\n *\n * Rejects rather than looping forever. A log that never quiesces means a\n * predecessor is still actively writing, which is a condition to surface, not to\n * append into.\n *\n * This only detects a CONCURRENT predecessor, which means it can only fire when\n * the two drivers are in different processes. Within one process an\n * `InMemoryLockStore` serializes the claims, so the predecessor has already\n * stopped by the time the successor probes.\n */\nexport async function awaitLogQuiescence<TOffset extends string = string>(\n  durability: StreamDurability<TOffset>,\n  quietMs: number,\n): Promise<number> {\n  let previous = (await durability.snapshot()).length\n  for (let probe = 0; probe < MAX_QUIESCENCE_PROBES; probe += 1) {\n    await sleep(quietMs)\n    const current = (await durability.snapshot()).length\n    if (current === previous) return current\n    previous = current\n  }\n  throw new Error(\n    `journal takeover: the event log never quiesced after ${MAX_QUIESCENCE_PROBES} probes (${previous} entries and still growing); another host is still driving this run`,\n  )\n}\n\nfunction sleep(ms: number): Promise<void> {\n  if (ms <= 0) return Promise.resolve()\n  return new Promise<void>((resolve) => setTimeout(resolve, ms))\n}\n\n/**\n * The one-way \"this claim is gone\" flag, latched by the first refusal.\n *\n * Keyed by the claim rather than held in one wrapper's closure because a claim\n * has TWO fenced seams — its log ({@link fenceDurability}) and its record\n * ({@link fenceRunStore}) — and a latch per wrapper would let them disagree: a\n * lease that flaps back to `aborted === false`, or an epoch read that fails,\n * would re-open the fence that had not refused yet. Losing a claim is not\n * transient, so one observation must close both.\n *\n * A `WeakMap` and not a field on {@link RunClaim} so the claim stays the plain\n * data structure core's `RunDriverOptions.claim` types it as, and so the latch is\n * collected with the claim.\n */\ninterface ClaimLatch {\n  /** `undefined` while the fence is open; otherwise the refusal to replay. */\n  lost: RunClaimLostError | undefined\n}\n\nconst CLAIM_LATCHES = new WeakMap<RunClaim, ClaimLatch>()\n\nfunction latchFor(claim: RunClaim): ClaimLatch {\n  const existing = CLAIM_LATCHES.get(claim)\n  if (existing !== undefined) return existing\n  const latch: ClaimLatch = { lost: undefined }\n  CLAIM_LATCHES.set(claim, latch)\n  return latch\n}\n\n/**\n * The I/O-free half of the check: the latch and the lease. Synchronous on\n * purpose — a fenced write must be refused BEFORE anything can half-land.\n */\nfunction claimLostSynchronously(\n  claim: RunClaim,\n  latch: ClaimLatch,\n): RunClaimLostError | undefined {\n  if (latch.lost !== undefined) return latch.lost\n  if (claim.signal.aborted) {\n    latch.lost = new RunClaimLostError(claim.runId, claim.epoch, 'lease-lost')\n    return latch.lost\n  }\n  return undefined\n}\n\n/**\n * The other half: re-read `driverEpoch` and refuse once a successor exists.\n *\n * A store failure is NOT treated as loss. The lease is the primary fence and it\n * has not fired, so fencing ourselves out on a store blip would kill a healthy\n * driver — and, for the record fence, would suppress a legitimate terminal write\n * and strand the run at `'running'`, which is worse than the write it prevents.\n */\nasync function claimLostByEpoch(\n  claim: RunClaim,\n  latch: ClaimLatch,\n  runs: RunStore,\n): Promise<RunClaimLostError | undefined> {\n  let observed: number | undefined\n  try {\n    observed = (await runs.get(claim.runId))?.driverEpoch\n  } catch {\n    return undefined\n  }\n  if (observed !== undefined && observed > claim.epoch) {\n    latch.lost = new RunClaimLostError(claim.runId, claim.epoch, observed)\n    return latch.lost\n  }\n  return undefined\n}\n\n/**\n * Wrap a log so every `append` is fenced by `claim`.\n *\n * `append` is the ONLY fenced method, deliberately:\n *\n * - `close()` must never be fenced. It runs on every teardown path including\n *   the teardown caused by losing the claim, and a fenced `close` would leave\n *   the record wedged at `'running'` with every live tailer parked forever (a\n *   `read` only ends when the log closes).\n * - `read` / `snapshot` / `resumeFrom` do not mutate, so a superseded host\n *   reading them is harmless.\n *\n * The lease check is synchronous and happens before any I/O, so a fenced append\n * cannot half-land. The epoch re-check is throttled to `epochRecheckAppends`\n * because it costs a store read and the append path is hot.\n *\n * ONE REFUSAL CLOSES THE FENCE FOR GOOD. The first `append` that is refused —\n * for EITHER cause, lost lease or moved epoch — latches this wrapper shut, and\n * every later `append` refuses immediately without consulting the throttle and\n * without a store read. This is not a nicety:\n *\n * - Losing a claim is not transient. Epochs only move forward and a lease is\n *   never handed back, so a wrapper that has refused once can never legitimately\n *   append again. Re-deciding per append can only produce a WRONG answer.\n * - The throttle makes that wrong answer reachable. A refusal consumes the\n *   re-read budget, so the very next append rides a fresh throttle window and is\n *   NOT re-checked. `pipeToRunLog`'s recovery path appends a `RUN_ERROR` right\n *   after the refusal it is recovering from, and that log belongs to the\n *   SUCCESSOR: a terminal `RUN_ERROR` from a dead host would fail the stream for\n *   every client attached to the live, healthy run.\n * - It is also strictly cheaper: a latched boolean replaces a store read.\n *\n * The latch deliberately does NOT extend to `close()` — see above.\n *\n * PASSES THE OFFSET TYPE THROUGH, rather than collapsing it to `string`. The\n * fence sits mid-chain between a caller's log and `pipeToRunLog`, so widening\n * here would reintroduce the branded-offset wall one layer in: a\n * `StreamDurability<DurableStreamOffset>` would go in and a\n * `StreamDurability<string>` would come out, which is not assignable back to\n * the caller's own type.\n */\nexport function fenceDurability<TOffset extends string = string>(\n  durability: StreamDurability<TOffset>,\n  claim: RunClaim,\n  options: { runs: RunStore; epochRecheckAppends?: number },\n): StreamDurability<TOffset> {\n  const recheckAppends = Math.max(\n    1,\n    Math.trunc(options.epochRecheckAppends ?? DEFAULT_EPOCH_RECHECK_APPENDS),\n  )\n  // Seeded at the threshold so the FIRST append always re-reads the epoch: a\n  // successor may have claimed between this fence being built and its first\n  // write.\n  let appendsSinceEpochRead = recheckAppends\n  // Latched by the FIRST refusal and never cleared, and SHARED with this claim's\n  // record fence so the two seams cannot disagree.\n  const latch = latchFor(claim)\n\n  async function assertHeld(): Promise<void> {\n    // Layer 1 plus the latch: no I/O, so nothing has been written yet, and once\n    // refused no throttle and no store read can let a later append through.\n    const synchronous = claimLostSynchronously(claim, latch)\n    if (synchronous !== undefined) throw synchronous\n    if (appendsSinceEpochRead < recheckAppends) {\n      appendsSinceEpochRead += 1\n      return\n    }\n    appendsSinceEpochRead = 1\n    // Layer 2, throttled because it costs a store read.\n    const byEpoch = await claimLostByEpoch(claim, latch, options.runs)\n    if (byEpoch !== undefined) throw byEpoch\n  }\n\n  return {\n    resumeFrom: () => durability.resumeFrom(),\n    append: async (chunks: Array<StreamChunk>) => {\n      await assertHeld()\n      return durability.append(chunks)\n    },\n    read: (offset, signal) => durability.read(offset, signal),\n    close: () => durability.close(),\n    snapshot: () => durability.snapshot(),\n  }\n}\n\n/**\n * Wrap a run store so a TERMINAL record write is fenced by `claim`.\n *\n * The record is the run's other authoritative channel, and the same rule applies\n * to it: a host that has lost its claim must not state that the run is over. It\n * reaches this seam by the most ordinary route — `pipeToRunLog` catches the\n * `RunClaimLostError` its refused append threw, folds it in, and calls\n * `finish(ctx, 'failed', …)` — so fencing the log alone only moves where the harm\n * surfaces. `'completed'` and `'aborted'` arrive the same way (an empty stream\n * that never appended; a lease loss that aborts `claim.signal`, which\n * `pipeToRunLog` reads as an abort before it appends anything), which is why the\n * gate is {@link isTerminalRunStatus} and not \"did an append refuse\".\n *\n * SUPPRESSED, NOT ATTEMPTED-AND-SWALLOWED, and not thrown either. `update`\n * resolves without writing. `pipeToRunLog` must not reject — `RunController.start`\n * consumes its promise fire-and-forget — and a rejection here would additionally\n * make `finish` report the run through the local rebuilt record as if the store\n * had broken, which is a different and false fact.\n *\n * WHAT IS *NOT* FENCED, deliberately:\n *\n * - **`close()`** is not on this seam at all, and must stay off it: see\n *   {@link fenceDurability}. A wedged `'running'` record with tailers parked\n *   forever is worse than the write being prevented.\n * - **Non-terminal writes pass through**, including `detachedSince` and\n *   `sandboxKey` written by a superseded host. They are stale, but staleness is\n *   not the harm being fixed: none of them can make a live run look finished, so\n *   none can mislead `isTerminalRunStatus`, `findActiveRun`, or the reaper. They\n *   are also self-healing — the successor owns those fields and overwrites them —\n *   whereas over-suppressing strands a record: `createOrResume` is how the row\n *   comes into existence at all, and refusing a non-terminal write on a\n *   mis-observed loss would leave a run with no record to recover from. Suppress\n *   the writes that assert an outcome; let bookkeeping through.\n * - **Reads** (`get`, `listByThread`, `listReclaimable`, `findActiveRun`) do not\n *   mutate, so a superseded host reading them is harmless. `finish`'s terminal\n *   re-read therefore still works and answers with the SUCCESSOR's live record,\n *   which is the truthful thing to resolve with.\n * - **Another run's record.** The fence knows about `claim.runId` only; a write\n *   aimed elsewhere is not this claim's to judge.\n *\n * The OPTIONAL methods (`listByThread`, `listReclaimable`) are forwarded only\n * when the wrapped store actually has them: consumers feature-detect\n * (`store.listReclaimable?.(…)`), so materializing one that delegates to a\n * missing method would turn a graceful degrade into a `TypeError`.\n * `findActiveRun` is required on the contract, so it forwards unconditionally.\n */\nexport function fenceRunStore(\n  runs: RunStore,\n  claim: RunClaim,\n  options: { logger?: InternalLogger } = {},\n): RunStore {\n  const latch = latchFor(claim)\n  // Bound, not merely captured: the store may be a class instance\n  // (`InMemoryRunStore`), whose methods need their receiver.\n  const listByThread = runs.listByThread?.bind(runs)\n  const listReclaimable = runs.listReclaimable?.bind(runs)\n\n  return {\n    createOrResume: (input) => runs.createOrResume(input),\n    get: (runId) => runs.get(runId),\n    findActiveRun: (threadId) => runs.findActiveRun(threadId),\n    update: async (runId, patch) => {\n      const status = patch.status\n      if (\n        runId !== claim.runId ||\n        status === undefined ||\n        !isTerminalRunStatus(status)\n      ) {\n        return runs.update(runId, patch)\n      }\n      const lost =\n        claimLostSynchronously(claim, latch) ??\n        // Unthrottled, unlike the append path: a terminal write happens once per\n        // run, so one store read is not a hot cost — and it is the read that\n        // catches a superseded driver whose stream ended without ever appending.\n        (await claimLostByEpoch(claim, latch, runs))\n      if (lost === undefined) return runs.update(runId, patch)\n      // Absorbing this silently would make it invisible: a detached run has no\n      // caller to report to. The logger is consumer-supplied, so a throwing sink\n      // must not turn a suppression into a rejection.\n      try {\n        options.logger?.sandbox(\n          `run ${runId}: suppressed a terminal '${status}' record write from a superseded driver`,\n          { runId, status, heldEpoch: claim.epoch, error: lost },\n        )\n      } catch {\n        // Intentionally empty: there is no second channel to report on.\n      }\n      return undefined\n    },\n    ...(listByThread === undefined ? {} : { listByThread }),\n    ...(listReclaimable === undefined ? {} : { listReclaimable }),\n  }\n}\n"],"mappings":"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"}

package/dist/esm/contracts.d.ts

@@ -20,6 +20,19 @@ export interface SandboxCapabilities {
      * file + shell redirection.
      */
     writableStdin: boolean;
+    /**
+     * A spawned process can be forcibly terminated via {@link SpawnHandle.kill}
+     * and aborted mid-flight via the {@link ProcessOptions.signal} passed to
+     * {@link SandboxProcess.spawn}. `true` for host/Docker; some edge providers
+     * (e.g. Cloudflare) implement `kill()` as a no-op and drop the abort signal
+     * entirely, so a long-running follower process (e.g. `tail -f`) started
+     * there can never be stopped by the caller — only polled and abandoned.
+     * Callers MUST branch on this before relying on `kill`/abort to reclaim a
+     * background process: a bring-your-own provider that omits it would
+     * otherwise be silently treated as killable, leaking an unstoppable process
+     * inside the sandbox.
+     */
+    killableProcesses: boolean;
     /** Capture/restore filesystem snapshots via {@link SandboxHandle.snapshot}. */
     snapshots: boolean;
     /** Declarative network egress allow/deny policy. */