@gajae-code/coding-agent 0.16.0 → 0.16.3

package/src/sdk/cli/session-cli.ts

@@ -38,10 +38,13 @@ import { SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
 import {
 	type SdkCheckpointRecordV1,
 	type SdkRetentionGapV1,
+	type SdkRingPositionV1,
 	type SdkSessionRowV1,
 	type SdkTailItemV1,
 	SESSION_ROWS_VERSION,
 	stripSecretFields,
+	TailRevisionBuffer,
+	tailItemKey,
 	toCheckpointRecordV1,
 	toRetentionGapV1,
 	toSessionRowV1,
@@ -613,14 +616,15 @@ async function workspaceIdentity(target: string): Promise<WorkspaceIdentity> {
 /**
  * Resolves the list selection from `--repo` (default: process cwd) under the
  * effective scope. Outside Git, `repo`/`worktree` fail typed and actionable —
- * they never broaden to `all`; `cwd` remains an exact canonical match.
+ * they never broaden to `all`; `cwd` remains an exact canonical match, and
+ * `all` ignores the selection entirely so it works outside any checkout.
  */
 export async function resolveSessionListSelection(
 	scope: SdkSessionListScope,
 	repoArg: string | undefined,
 ): Promise<SdkSessionListSelection> {
 	const selection = await workspaceIdentity(repoArg ?? process.cwd());
-	if (scope !== "cwd" && !selection.repoRoot)
+	if (scope !== "cwd" && scope !== "all" && !selection.repoRoot)
 		throw new SdkSessionCliError(
 			"not_a_repository",
 			`--scope ${scope} requires a Git repository, but "${selection.canonicalPath}" is outside any Git checkout. ` +
@@ -969,11 +973,7 @@ function extractCheckpoint(response: unknown): CheckpointExtraction {
 	if (gap !== undefined) return { gap };
 	const record = toCheckpointRecordV1(result.checkpoint ?? result);
 	const cursor =
-		typeof result.cursor === "string" && result.cursor
-			? result.cursor
-			: typeof result.checkpointToken === "string" && result.checkpointToken
-				? result.checkpointToken
-				: undefined;
+		typeof result.checkpointToken === "string" && result.checkpointToken ? result.checkpointToken : undefined;
 	return { record, cursor };
 }
 
@@ -988,13 +988,6 @@ function extractTranscriptPage(response: unknown): { items: unknown[]; complete:
 	};
 }
 
-function tailItemKey(item: SdkTailItemV1): string {
-	if (item.generation !== undefined && item.seq !== undefined)
-		return `${item.kind}\u0000${item.generation}\u0000${item.seq}`;
-	if (item.id !== undefined) return `${item.kind}\u0000${item.id}`;
-	return `${item.kind}\u0000${JSON.stringify(item.payload)}`;
-}
-
 function mergeTailItems(
 	target: SdkTailItemV1[],
 	seen: Set<string>,
@@ -1009,8 +1002,9 @@ function mergeTailItems(
 	}
 }
 
-/** Canonical ring position of an event item, when the host stated one. */
-type TailSeqKey = { generation: number; seq: number };
+/** Canonical session-wide ring position of an event item, when the host stated one. */
+type TailSeqKey = SdkRingPositionV1;
+type TailLocalPosition = Pick<SdkRingPositionV1, "generation" | "seq">;
 
 function isPositionCoordinate(value: unknown): value is number {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -1060,7 +1054,7 @@ function classifyRawEventPosition(event: unknown): "unpositioned" | "malformed"
  * it is never silently downgraded to unpositioned. Claiming neither coordinate
  * is a genuine unpositioned event.
  */
-function classifyTailPosition(item: SdkTailItemV1): TailSeqKey | "unpositioned" | "malformed" {
+function classifyTailPosition(item: SdkTailItemV1): TailLocalPosition | "unpositioned" | "malformed" {
 	if (item.generation === undefined && item.seq === undefined) return "unpositioned";
 	if (!isPositionCoordinate(item.generation) || !isPositionCoordinate(item.seq)) return "malformed";
 	return { generation: item.generation, seq: item.seq };
@@ -1068,10 +1062,13 @@ function classifyTailPosition(item: SdkTailItemV1): TailSeqKey | "unpositioned"
 
 function tailSeqKey(item: SdkTailItemV1): TailSeqKey | undefined {
 	const position = classifyTailPosition(item);
-	return typeof position === "string" ? undefined : position;
+	return typeof position === "string" || !isPositionCoordinate(item.revision)
+		? undefined
+		: { revision: item.revision, ...position };
 }
 
 function compareTailSeqKeys(left: TailSeqKey, right: TailSeqKey): number {
+	if (left.revision !== right.revision) return left.revision - right.revision;
 	return left.generation !== right.generation ? left.generation - right.generation : left.seq - right.seq;
 }
 
@@ -1115,10 +1112,12 @@ function mergeEventTailItems(
 			target.unpositioned.push(item);
 			continue;
 		}
+		const orderedPosition = tailSeqKey(item);
+		if (orderedPosition === undefined) throw new Error("A positioned tail item has no authoritative revision.");
 		let index = target.positioned.length;
 		for (; index > 0; index--) {
 			const previous = tailSeqKey(target.positioned[index - 1]!);
-			if (previous === undefined || compareTailSeqKeys(previous, position) <= 0) break;
+			if (previous === undefined || compareTailSeqKeys(previous, orderedPosition) <= 0) break;
 		}
 		target.positioned.splice(index, 0, item);
 	}
@@ -1150,12 +1149,6 @@ function eventGapToRetentionGap(
 	return undefined;
 }
 
-function publicationSequence(publicationId: string): number | undefined {
-	const parts = publicationId.split(":");
-	const value = Number(parts.at(-1));
-	return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
-}
-
 function tailItemFromRouterFrame(frame: SessionRouterFrame): SdkTailItemV1 | undefined {
 	if (frame.name === undefined) return undefined;
 	// The replay response is an out-of-band control frame, not an event-ring
@@ -1163,18 +1156,18 @@ function tailItemFromRouterFrame(frame: SessionRouterFrame): SdkTailItemV1 | und
 	// intentionally has no event `seq`; projecting it as a tail item would make
 	// the strict event-position validator reject every otherwise valid tail.
 	if (frame.name === "event_replay_result") return undefined;
-	const seq = frame.publicationId === undefined ? undefined : publicationSequence(frame.publicationId);
+	const seq = frame.seq;
 	return toTailItemV1(
 		{
 			kind: frame.name,
-			...(frame.generation === undefined ? {} : { generation: frame.generation }),
-			...(seq === undefined ? {} : { seq }),
+			...(frame.revision === undefined ? {} : { revision: frame.revision }),
+			...(seq === undefined ? {} : { generation: frame.generation, seq }),
 			payload: frame.body,
 		},
 		{
 			kind: frame.name,
-			...(frame.generation === undefined ? {} : { generation: frame.generation }),
-			...(seq === undefined ? {} : { seq }),
+			...(frame.revision === undefined ? {} : { revision: frame.revision }),
+			...(seq === undefined ? {} : { generation: frame.generation, seq }),
 		},
 	);
 }
@@ -1388,7 +1381,9 @@ async function offlineTailReplay(
 			version: SESSION_ROWS_VERSION,
 			source: "offline",
 			session: row,
-			items: entries.map((entry, index) => toTailItemV1(entry, { kind: "transcript", seq: index })),
+			items: entries.map((entry, index) =>
+				toTailItemV1(entry, { kind: "transcript", revision: index + 1, seq: index }),
+			),
 			terminal: true,
 		},
 	};
@@ -1415,6 +1410,7 @@ async function runLiveTail(
 	// evidence.
 	const seenTranscript = new Set<string>();
 	const seenEvents = new Set<string>();
+	const liveRevisionBuffer = new TailRevisionBuffer();
 	let checkpoint: SdkCheckpointRecordV1 | undefined;
 	let gap: SdkRetentionGapV1 | undefined;
 	let liveReason: TailExitReason | undefined;
@@ -1454,7 +1450,7 @@ async function runLiveTail(
 				// close at a contested position win instead of failing closed, and
 				// checking it after the monotonic guard would silently skip a
 				// conflicting kind at an already-decided position.
-				const positionKey = `${position.generation}\u0000${position.seq}`;
+				const positionKey = `${position.revision}\u0000${position.generation}\u0000${position.seq}`;
 				const claimed = claimedLifecycleKinds.get(positionKey);
 				if (claimed !== undefined && claimed !== item.kind) {
 					malformed ??= new SdkSessionCliError(
@@ -1496,7 +1492,17 @@ async function runLiveTail(
 		if (attachment.sessionId !== sessionId) return;
 		const item = tailItemFromRouterFrame(frame);
 		if (!item) return;
-		applyLifecycle(mergeEventTailItems(eventItems, seenEvents, [item], include));
+		try {
+			applyLifecycle(mergeEventTailItems(eventItems, seenEvents, liveRevisionBuffer.push(item), include));
+		} catch (error) {
+			malformed ??= new SdkSessionCliError(
+				"protocol_error",
+				error instanceof Error ? error.message : "A live tail item had no authoritative revision.",
+				1,
+				{ sessionId, kind: item.kind, generation: item.generation, seq: item.seq },
+			);
+			rejectLive?.(malformed);
+		}
 	};
 
 	return await withRouter(
@@ -1518,6 +1524,10 @@ async function runLiveTail(
 			const extraction = extractCheckpoint(checkpointResponse);
 			checkpoint = extraction.record;
 			gap = extraction.gap;
+			if (checkpoint !== undefined)
+				applyLifecycle(
+					mergeEventTailItems(eventItems, seenEvents, liveRevisionBuffer.resolve(checkpoint.revision), include),
+				);
 			if (gap !== undefined && args.strict === true)
 				throw new SdkSessionCliError(
 					"retention_gap",
@@ -1537,10 +1547,18 @@ async function runLiveTail(
 				);
 				throwResponseFailure(response);
 				const page = extractTranscriptPage(response);
+				const rev = checkpoint?.revision;
+				let nextSeq = transcriptItems.length;
 				mergeTailItems(
 					transcriptItems,
 					seenTranscript,
-					page.items.map(item => toTailItemV1(item, { kind: "transcript" })),
+					page.items.map(item => {
+						const it = toTailItemV1(item, { kind: "transcript" });
+						if (it.revision === undefined && rev !== undefined) it.revision = rev;
+						if (it.generation === undefined) it.generation = checkpoint?.generation ?? 0;
+						if (it.seq === undefined) it.seq = nextSeq++;
+						return it;
+					}),
 					include,
 				);
 				if (page.complete || page.cursor === undefined) break;
@@ -1586,9 +1604,24 @@ async function runLiveTail(
 					raw.seq,
 				);
 			}
-			const replayItems = rawEvents.map(event => toTailItemV1(event, { kind: "event" }));
+			const replayItems = rawEvents.map(event => {
+				const it = toTailItemV1(event, { kind: "event" });
+				if (it.revision === undefined && checkpoint?.revision !== undefined) it.revision = checkpoint.revision;
+				return it;
+			});
 			applyLifecycle(mergeEventTailItems(eventItems, seenEvents, replayItems, include));
 			if (malformed !== undefined) throw malformed;
+			if (checkpoint !== undefined) {
+				const checkpointKey = {
+					revision: checkpoint.revision,
+					generation: checkpoint.generation,
+					seq: checkpoint.seq,
+				};
+				if (turnStateKey === undefined || compareTailSeqKeys(checkpointKey, turnStateKey) >= 0) {
+					turnStateKey = checkpointKey;
+					turnIdle = checkpoint.idle;
+				}
+			}
 			if (liveReason === undefined && args.untilIdle === true && turnIdle) liveReason = "idle";
 			if (liveReason === undefined) {
 				const completion = Promise.withResolvers<TailExitReason>();

package/src/sdk/host/control/dispatch.ts

@@ -291,8 +291,8 @@ function invoke(
 			return surface.setQueueMode("steering", input.mode);
 		case "queue.follow_up_mode.set":
 			return surface.setQueueMode("follow_up", input.mode);
-		case "queue.interrupt_mode.set":
-			return surface.setQueueMode("interrupt", input.mode);
+		case "queue.tool_interrupt_policy.set":
+			return surface.setQueueMode("tool_interrupt", input.mode);
 		case "compaction.run":
 			return surface.runCompaction();
 		case "compaction.auto.set":

package/src/sdk/host/events.ts

@@ -2,6 +2,7 @@ import type { SdkFrame } from "./types";
 
 export interface EventFrame extends SdkFrame {
 	type: "event";
+	revision?: number;
 	generation: number;
 	seq: number;
 }
@@ -31,11 +32,20 @@ export class SessionEventStream {
 	#frames: EventFrame[] = [];
 	readonly #ringSize: number;
 	readonly #resyncQueries: string[];
+	readonly #revisionProvider: (() => number | undefined) | undefined;
 
-	constructor(options: { generation?: number; ringSize?: number; resyncQueryIds?: string[] } = {}) {
+	constructor(
+		options: {
+			generation?: number;
+			ringSize?: number;
+			resyncQueryIds?: string[];
+			revisionProvider?: () => number | undefined;
+		} = {},
+	) {
 		this.#generation = options.generation ?? 0;
 		this.#ringSize = options.ringSize ?? 256;
 		this.#resyncQueries = options.resyncQueryIds ?? ["Q01", "Q02", "Q03"];
+		this.#revisionProvider = options.revisionProvider;
 	}
 
 	get generation(): number {
@@ -53,7 +63,21 @@ export class SessionEventStream {
 	}
 
 	emit(frame: SdkFrame): EventFrame {
-		const event: EventFrame = { ...frame, type: "event", generation: this.#generation, seq: ++this.#seq };
+		const suppliedRevision = frame.revision;
+		const providedRevision = this.#revisionProvider?.();
+		const revision =
+			typeof suppliedRevision === "number" && Number.isSafeInteger(suppliedRevision) && suppliedRevision >= 0
+				? suppliedRevision
+				: typeof providedRevision === "number" && Number.isSafeInteger(providedRevision) && providedRevision >= 0
+					? providedRevision
+					: undefined;
+		const event: EventFrame = {
+			...frame,
+			type: "event",
+			...(revision === undefined ? {} : { revision }),
+			generation: this.#generation,
+			seq: ++this.#seq,
+		};
 		this.#frames.push(event);
 		if (this.#frames.length > this.#ringSize) this.#frames.shift();
 		return event;

package/src/sdk/host/host.ts

@@ -47,6 +47,8 @@ export type SessionActivationGate = (input: { sessionId: string; generation: num
 export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
 	query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+	/** Supplies the durable transcript revision stamped on ordinary emitted events. */
+	eventRevision?: () => number | undefined;
 	/** Test/lifecycle seam invoked synchronously before fire-and-forget dispatch. */
 	onFrameAdmitted?: (connectionId: string, frame: SdkFrame) => void;
 	/** Synchronously rejects external input while a runtime is being replaced. */
@@ -199,7 +201,7 @@ function has(frame: SdkFrame, field: string): boolean {
 
 /** Adapter-based session host; bus wiring owns NotificationServer creation and transport framing. */
 export class SessionSdkHost {
-	readonly events = new SessionEventStream();
+	readonly events: SessionEventStream;
 	readonly reverse: ReverseLeaseRuntime;
 	readonly #options: SessionSdkHostOptions;
 	#started = false;
@@ -214,6 +216,7 @@ export class SessionSdkHost {
 
 	constructor(options: SessionSdkHostOptions) {
 		this.#options = options;
+		this.events = new SessionEventStream({ revisionProvider: options.eventRevision });
 		this.reverse = new ReverseLeaseRuntime({
 			sendFrame: options.sendFrame,
 			installDefinitions: options.installProviderDefinitions,
@@ -354,6 +357,8 @@ export class SessionSdkHost {
 			if (this.events.generation !== generation) return "generation_changed";
 			if (this.#readyGeneration === generation) return "already";
 		}
+		if (!this.#started || this.#stopping) return "not_prepared";
+		if (this.events.generation !== generation) return "generation_changed";
 		this.#publishReadiness();
 		return "activated";
 	}

package/src/sdk/host/query/cursor.ts

@@ -18,6 +18,7 @@ export interface CursorEnvelope {
 	issuedAt?: number;
 	/** TTL metadata minted by `CursorRegistry.grant`: wall-clock ms when the cursor expires. */
 	expiresAt?: number;
+	purpose?: "checkpoint";
 	position: unknown;
 	direction: string;
 	pageShape: unknown;
@@ -68,6 +69,7 @@ export interface CursorQueryContext {
 	resourceId?: string;
 	direction: string;
 	pageShape: unknown;
+	purpose?: "checkpoint";
 }
 
 export class CursorError extends Error {
@@ -170,26 +172,68 @@ export class CursorRegistry {
 		cursor: string,
 		connectionId: string,
 		expected: CursorQueryContext,
-		resourceKind: string,
+		_resourceKind: string,
 		resourceId: string,
 	): Promise<{ cursor: string; envelope: CursorEnvelope }> {
 		const envelope = verifyCursor(cursor, this.sessionToken);
-		if (!envelope) throw new CursorError("invalid_cursor", false);
-		if (envelope.expiresAt === undefined || envelope.expiresAt <= this.now()) throw new CursorError("cursor_expired");
+		if (!envelope) {
+			this.release(cursor);
+			throw new CursorError("invalid_cursor", true);
+		}
+		const source = this.#active.get(cursor);
+		if (!source || envelope.expiresAt === undefined) {
+			this.release(cursor);
+			throw new CursorError("invalid_cursor", true);
+		}
+		const validatedAt = this.now();
+		if (source.expiresAt <= validatedAt || envelope.expiresAt <= validatedAt) {
+			this.release(cursor);
+			throw new CursorError("cursor_expired");
+		}
 		if (
 			envelope.sessionId !== expected.sessionId ||
 			(expected.resource !== undefined && envelope.resource !== expected.resource) ||
 			envelope.direction !== expected.direction ||
-			canonicalJson(envelope.pageShape) !== canonicalJson(expected.pageShape)
+			canonicalJson(envelope.pageShape) !== canonicalJson(expected.pageShape) ||
+			envelope.purpose !== expected.purpose ||
+			_resourceKind !== envelope.resource ||
+			source.resourceId !== resourceId
 		)
 			throw new CursorError("invalid_input", false, "cursor does not match query");
+		// Preserve the already-validated source while removing expired target
+		// grants before capacity accounting. The shared timestamp prevents the
+		// source from changing classification at a TTL boundary mid-exchange.
+		this.sweep(cursor, validatedAt);
+		const targetConnectionCount = [...this.#active.values()].filter(
+			item => item.connectionId === connectionId,
+		).length;
+		if (
+			this.#active.size > MAX_CURSORS_PER_SESSION ||
+			targetConnectionCount - (source.connectionId === connectionId ? 1 : 0) >= MAX_CURSORS_PER_CONNECTION
+		)
+			throw new CursorError("snapshot_capacity_exceeded", false);
 		const exchanged: CursorEnvelope = {
 			...envelope,
 			nonce: randomUUID(),
 			issuedAt: undefined,
 			expiresAt: undefined,
 		};
-		const exchangedCursor = await this.grant(connectionId, exchanged, resourceKind, resourceId);
+		const issuedAt = this.now();
+		exchanged.issuedAt = issuedAt;
+		exchanged.expiresAt = issuedAt + CURSOR_TTL_MS;
+		const exchangedCursor = signCursor(exchanged, this.sessionToken);
+		try {
+			this.revisions.transferPin(cursor, exchangedCursor);
+		} catch (error) {
+			if (error instanceof RevisionStoreError) throw new CursorError(error.code, false, error.message);
+			throw error;
+		}
+		this.#active.delete(cursor);
+		this.#active.set(exchangedCursor, {
+			connectionId,
+			resourceId,
+			expiresAt: exchanged.expiresAt,
+		});
 		return { cursor: exchangedCursor, envelope: exchanged };
 	}
 
@@ -227,8 +271,9 @@ export class CursorRegistry {
 	close(): void {
 		for (const cursor of this.#active.keys()) this.release(cursor);
 	}
-	sweep(): void {
-		for (const [cursor, active] of this.#active) if (active.expiresAt <= this.now()) this.release(cursor);
+	sweep(exceptCursor?: string, at = this.now()): void {
+		for (const [cursor, active] of this.#active)
+			if (cursor !== exceptCursor && active.expiresAt <= at) this.release(cursor);
 		this.revisions.sweep();
 	}
 	get size(): number {

package/src/sdk/host/query/handlers.ts

@@ -108,6 +108,7 @@ export interface SdkCheckpointRecord {
 	revision: number;
 	generation: number;
 	seq: number;
+	idle: boolean;
 }
 
 function isNonNegativeSafeInteger(value: unknown): value is number {
@@ -119,10 +120,11 @@ export function isCheckpointRecord(value: unknown): value is SdkCheckpointRecord
 	const record = value as Record<string, unknown>;
 	const keys = Object.keys(record);
 	return (
-		keys.length === 3 &&
+		keys.length === 4 &&
 		isNonNegativeSafeInteger(record.revision) &&
 		isNonNegativeSafeInteger(record.generation) &&
-		isNonNegativeSafeInteger(record.seq)
+		isNonNegativeSafeInteger(record.seq) &&
+		typeof record.idle === "boolean"
 	);
 }
 const sources: Record<string, { resource: string; method: keyof SessionSurface; mvcc: boolean }> = {
@@ -296,9 +298,10 @@ export class QueryHandlers {
 		let snapshot: unknown;
 		// The cursor may arrive either as the top-level continuation cursor or,
 		// on Q01 only (validated in `dispatch`), as the `checkpointToken` resume
-		// seed. Both are signed checkpoint cursors consumed through the same
-		// CursorRegistry authority; neither mints a fresh snapshot.
-		const rawCursorToken = request.cursor ?? (queryId === "Q01" ? request.input?.checkpointToken : undefined);
+		// seed. Both are consumed through the same CursorRegistry authority, but
+		// only the named input token is required to carry checkpoint purpose.
+		const checkpointToken = queryId === "Q01" ? request.input?.checkpointToken : undefined;
+		const rawCursorToken = request.cursor ?? checkpointToken;
 		if (rawCursorToken !== undefined && typeof rawCursorToken !== "string")
 			return this.#error(request, "invalid_request", false, "checkpointToken must be a non-empty string.");
 		const cursorToken = rawCursorToken;
@@ -309,6 +312,8 @@ export class QueryHandlers {
 				direction: "forward",
 				pageShape: { targetBytes: TARGET_PAGE_BYTES },
 			});
+			if (checkpointToken !== undefined && cursor.purpose !== "checkpoint")
+				throw new CursorError("invalid_input", false, "checkpointToken does not carry checkpoint purpose");
 			selector = assertCursorSelector(cursorSelector(cursor.position), selector);
 			resourceId = selector.resourceId ?? "default";
 			revision = cursor.revision;
@@ -467,10 +472,20 @@ export class QueryHandlers {
 						resource: "transcript",
 						direction: "forward",
 						pageShape: { targetBytes: TARGET_PAGE_BYTES },
+						purpose: "checkpoint",
 					},
 					"transcript",
 					"default",
 				);
+				if (!isCheckpointRecord(exchanged.envelope.highWatermark)) {
+					this.cursors.release(exchanged.cursor);
+					return this.#error(
+						request,
+						"invalid_input",
+						false,
+						"checkpointToken is not an authoritative checkpoint.",
+					);
+				}
 				return {
 					id: request.id,
 					ok: true,
@@ -494,13 +509,18 @@ export class QueryHandlers {
 		// Atomic synchronous capture (C9): entries and event-ring watermark come
 		// from the same host-owned call, so the pinned snapshot revision and the
 		// subscribe position can never straddle a concurrent append.
-		const captured =
-			typeof this.surface.getCheckpointSnapshot === "function" ? this.surface.getCheckpointSnapshot() : undefined;
-		const entries = captured !== undefined ? captured.entries : await this.surface.getTranscriptEntries();
-		const head: SdkCheckpointRecord =
-			captured !== undefined
-				? captured.watermark
-				: { revision: Array.isArray(entries) ? entries.length : 0, generation: 0, seq: 0 };
+		if (typeof this.surface.getCheckpointSnapshot !== "function")
+			return this.#error(request, "unavailable", false, "Atomic session checkpoint capture is unavailable.");
+		const captured = this.surface.getCheckpointSnapshot();
+		const entries = captured.entries;
+		const head = captured.watermark;
+		if (!isCheckpointRecord(head))
+			return this.#error(
+				request,
+				"unavailable",
+				false,
+				"Atomic session checkpoint capture returned an invalid watermark.",
+			);
 		// Mint the snapshot from the exact entries captured with the watermark;
 		// entries appended after this point are excluded from replay by
 		// construction (append-during-checkpoint), and the returned token is the
@@ -517,6 +537,7 @@ export class QueryHandlers {
 			highWatermark: head,
 			nonce,
 			position: { offset: 0, selector: { queryId: "Q01" } },
+			purpose: "checkpoint",
 			direction: "forward",
 			pageShape: { targetBytes: TARGET_PAGE_BYTES },
 		};

package/src/sdk/host/query/revision-store.ts

@@ -524,6 +524,18 @@ export class RevisionStore {
 		await this.#enforceMemory();
 	}
 
+	transferPin(sourceCursorId: string, replacementCursorId: string): void {
+		if (sourceCursorId === replacementCursorId) return;
+		if (this.#pinIndex.has(replacementCursorId))
+			throw new RevisionStoreError("snapshot_capacity_exceeded", "replacement cursor is already pinned");
+		const revision = this.#pinIndex.get(sourceCursorId);
+		if (!revision) throw new RevisionStoreError("snapshot_capacity_exceeded", "snapshot pin is unavailable");
+		revision.pins.delete(sourceCursorId);
+		revision.pins.add(replacementCursorId);
+		this.#pinIndex.delete(sourceCursorId);
+		this.#pinIndex.set(replacementCursorId, revision);
+	}
+
 	unpin(cursorId: string): void {
 		const revision = this.#pinIndex.get(cursorId);
 		if (!revision) return;