@gajae-code/coding-agent 0.15.6 → 0.16.1

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

@@ -2,17 +2,27 @@ import { randomBytes } from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { replaceTabs, truncateToWidth } from "@gajae-code/tui";
 import { getAgentDir } from "@gajae-code/utils";
 import { repo as resolveGitRepository } from "../../utils/git";
 import { ensureBroker } from "../broker/ensure";
+import { resolveSessionLocator } from "../broker/session-index";
+import {
+	resolveScopeRequest,
+	type ScopeNameV1,
+	type ScopeRequestV1,
+	type SdkSearchResultV1,
+	type SdkSearchRowV1,
+} from "../broker/session-scope";
 import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
-import { SdkClientError } from "../client";
+import { readSdkBrokerDiscovery, SdkClient, SdkClientError } from "../client";
 import { createBrokerSessionLifecycleService } from "../lifecycle/broker-client";
 import type {
 	SessionLifecycleMutationRequest,
 	SessionLifecycleOperation,
 	SessionLifecycleSavedSession,
 	SessionLifecycleSavedSessionIdentity,
+	SessionLifecycleService,
 	SessionReconcileUncertainTarget,
 } from "../lifecycle/service";
 import { PROMPT_CLIENT_REF_MAX_LENGTH } from "../prompt-status";
@@ -24,6 +34,7 @@ import {
 import { adapterDispositionError, findOperation, type OperationKind } from "../protocol/operation-registry";
 import { type SessionAttachment, SessionRouter, SessionRouterError, type SessionRouterFrame } from "../router";
 import { SessionListTraversalError, sessionListPageFromResponse, traverseSessionList } from "../session-list";
+import { SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
 import {
 	type SdkCheckpointRecordV1,
 	type SdkRetentionGapV1,
@@ -39,6 +50,7 @@ import {
 
 export type SdkSessionCliAction =
 	| "list"
+	| "search"
 	| "inspect"
 	| "send"
 	| "status"
@@ -64,7 +76,6 @@ export interface SdkSessionCliArgs {
 	jsonInputFile?: string;
 	jsonInputStdin?: boolean;
 	idempotencyKey?: string;
-	scope?: string;
 	confirm?: boolean;
 	cursor?: string;
 	wait?: boolean;
@@ -73,6 +84,10 @@ export interface SdkSessionCliArgs {
 	untilIdle?: boolean;
 	allEvents?: boolean;
 	repo?: string;
+	scope?: string;
+	limit?: number;
+	json?: boolean;
+
 	agentDir?: string;
 }
 
@@ -95,6 +110,9 @@ const TAIL_OFFLINE_MAX_SCAN_BYTES = 4 * 1024 * 1024;
 const TAIL_OFFLINE_MAX_SCANNED_LINES = 4_096;
 const TAIL_OFFLINE_MAX_LINE_BYTES = 256 * 1024;
 const transcriptDecoder = new TextDecoder("utf-8", { fatal: true });
+const SEARCH_PROBE_TIMEOUT_MS = 2_000;
+const SEARCH_PROBE_MAX_ROWS = 100;
+const SEARCH_TEXT_WIDTH = 80;
 
 const TERMINAL_TURN_KINDS = new Set(["turn_end", "agent_end"]);
 const START_TURN_KINDS = new Set(["turn_start", "agent_start"]);
@@ -214,6 +232,10 @@ function isEndpointOperation(operation: string): boolean {
 	return operation === "session.get_endpoint";
 }
 
+function isRawSpawnOperation(kind: OperationKind, operation: string): boolean {
+	return kind === "global" && operation === "session.spawn";
+}
+
 function isLifecycleOperation(operation: string): operation is LifecycleMutationOperation {
 	return (
 		operation === "session.create" ||
@@ -257,9 +279,11 @@ async function withRouter<T>(
 	agentDir: string,
 	action: (router: SessionRouter) => Promise<T>,
 	onFrame?: (attachment: SessionAttachment, frame: SessionRouterFrame) => void,
+	sessionIds?: readonly string[],
 ): Promise<T> {
 	const router = new SessionRouter({
 		agentDir,
+		...(sessionIds === undefined ? {} : { sessionIds }),
 		...(onFrame === undefined ? {} : { deps: { onFrame } }),
 	});
 	let result!: T;
@@ -367,6 +391,145 @@ async function sessionRows(agentDir: string): Promise<SessionRows> {
 	});
 }
 
+function searchScopeRequest(scope: ScopeNameV1, locator: { cwd: string; worktreeRoot: string | null }): ScopeRequestV1 {
+	return { version: 1, requested: scope, requestAnchor: { cwd: locator.cwd, worktreeRoot: locator.worktreeRoot } };
+}
+
+function searchProbe(row: SdkSearchRowV1, router: SessionRouter): Promise<SdkSearchRowV1> {
+	if (!row.live) return Promise.resolve({ ...row, probe: "stale" });
+	return (async () => {
+		try {
+			const attachment = router.attachment(row.id);
+			if (!attachment) return { ...row, probe: "unreachable" };
+			const response = await router.request(
+				row.id,
+				{ type: "query_request", query: "session.checkpoint", input: {} },
+				attachment.generation,
+				attachment,
+				{ timeoutMs: SEARCH_PROBE_TIMEOUT_MS },
+			);
+			return { ...row, probe: response.ok === true ? "reachable" : "unreachable" };
+		} catch {
+			return { ...row, probe: "unreachable" };
+		}
+	})();
+}
+
+export function mergeProbedSearchRows(
+	rows: readonly SdkSearchRowV1[],
+	probedRows: readonly SdkSearchRowV1[],
+): readonly SdkSearchRowV1[] {
+	return [...probedRows, ...rows.slice(probedRows.length)];
+}
+
+async function probeSearchRows(agentDir: string, result: SdkSearchResultV1): Promise<SdkSearchResultV1> {
+	if (result.status === "unavailable" || result.status === "not-in-git-worktree" || result.rows.length === 0)
+		return result;
+	const rows = result.rows.slice(0, SEARCH_PROBE_MAX_ROWS);
+	try {
+		const probes = await withRouter(
+			agentDir,
+			async router => await Promise.all(rows.map(row => searchProbe(row, router))),
+			undefined,
+			rows.map(row => row.id),
+		);
+		return { ...result, rows: mergeProbedSearchRows(result.rows, probes) };
+	} catch {
+		return {
+			...result,
+			rows: mergeProbedSearchRows(
+				result.rows,
+				rows.map(row => ({ ...row, probe: row.live ? "unreachable" : "stale" })),
+			),
+		};
+	}
+}
+
+/** Resolves, lists, and probes only the exact rows selected by the Broker-scoped search. */
+export async function runSdkSearch(
+	args: Pick<SdkSessionCliArgs, "agentDir" | "repo" | "scope" | "limit" | "cursor">,
+	createService: (agentDir: string) => SessionLifecycleService = createBrokerSessionLifecycleService,
+	probe: (agentDir: string, result: SdkSearchResultV1) => Promise<SdkSearchResultV1> = probeSearchRows,
+): Promise<{ result: SdkSearchResultV1; exitCode: 0 | 1 }> {
+	const agentDir = args.agentDir ?? getAgentDir();
+	const locator = await resolveSessionLocator(args.repo ?? process.cwd(), agentDir);
+	const scope: ScopeNameV1 =
+		args.scope === undefined || args.scope === "repo" || args.scope === "pwd" || args.scope === "global"
+			? ((args.scope ?? "repo") as ScopeNameV1)
+			: (() => {
+					throw new SdkSessionCliError(
+						"usage",
+						`Invalid search scope "${args.scope}". Expected repo, pwd, or global.`,
+						2,
+					);
+				})();
+	const request = searchScopeRequest(scope, locator);
+	const resolved = await resolveScopeRequest(request);
+	const outcome = await createService(agentDir).scopedList(request, args.limit, args.cursor);
+	if (outcome.ok) {
+		if ("rows" in outcome.result) {
+			if (outcome.result.status === "not-in-git-worktree") return { result: outcome.result, exitCode: 0 };
+			if (outcome.result.status === "unavailable") return { result: outcome.result, exitCode: 1 };
+			return { result: await probe(agentDir, outcome.result), exitCode: 0 };
+		}
+		return {
+			result: {
+				version: 1,
+				scope: resolved,
+				status: "unavailable",
+				observedAt: new Date().toISOString(),
+				rows: [],
+				warnings: [],
+				error: { code: "malformed_response", message: "broker search returned an unscoped result" },
+			},
+			exitCode: 1,
+		};
+	}
+	if (!outcome.ok && outcome.result?.status === "unavailable") return { result: outcome.result, exitCode: 1 };
+	return {
+		result: {
+			version: 1,
+			scope: resolved,
+			status: "unavailable",
+			observedAt: new Date().toISOString(),
+			rows: [],
+			warnings: [],
+			error: { code: outcome.error.code, message: outcome.error.message },
+		},
+		exitCode: 1,
+	};
+}
+
+function searchScopeLabel(result: SdkSearchResultV1): string {
+	const resolved = result.scope.resolved;
+	if (resolved === null) return "not-in-git-worktree";
+	if (resolved.kind === "repo") return resolved.worktreeRoot;
+	if (resolved.kind === "pwd") return resolved.cwd;
+	return resolved.visibility;
+}
+
+function safeSearchText(value: string): string {
+	return truncateToWidth(replaceTabs(value).replaceAll(/[\r\n]/g, " "), SEARCH_TEXT_WIDTH);
+}
+
+/** Renders a credential-free scope/status preamble and bounded search table. */
+export function renderSdkSearchTable(result: SdkSearchResultV1): string {
+	const lines = [
+		`Scope requested: ${result.scope.requested}`,
+		`Scope resolved: ${safeSearchText(searchScopeLabel(result))}`,
+		`Status: ${result.status}`,
+		`Observed at: ${result.observedAt}`,
+		...(result.cursor === undefined ? [] : [`Continuation cursor: ${safeSearchText(result.cursor)}`]),
+	];
+	if (result.rows.length === 0) return lines.join("\n");
+	lines.push("ID  PROBE        LIVE  CWD");
+	for (const row of result.rows)
+		lines.push(
+			`${safeSearchText(row.id).padEnd(20)}  ${(row.probe ?? "-").padEnd(11)}  ${String(row.live).padEnd(4)}  ${safeSearchText(row.locator.cwd)}`,
+		);
+	return lines.join("\n");
+}
+
 const SESSION_LIST_SCOPES: readonly SdkSessionListScope[] = ["repo", "cwd", "worktree", "all"];
 /** Row workspaces whose locator cannot be canonicalized still get one deterministic identity. */
 const WORKSPACE_IDENTITY_CACHE_LIMIT = 4096;
@@ -450,14 +613,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. ` +
@@ -487,7 +651,7 @@ export async function filterSessionRowsByScope(
 	const warnings: string[] = [];
 	const sessions: SdkSessionRowV1[] = [];
 	for (const row of rows) {
-		const identity = await workspaceIdentity(row.locator.repo);
+		const identity = await workspaceIdentity(row.locator.cwd);
 		let keep: boolean;
 		if (scope === "cwd") keep = identity.canonicalPath === selection.selection.canonicalPath;
 		else if (scope === "worktree")
@@ -496,7 +660,7 @@ export async function filterSessionRowsByScope(
 		if (keep) sessions.push(row);
 		else if (identity.repoRoot === null && identity.commonDir === null)
 			warnings.push(
-				`Session ${row.sessionId} workspace "${row.locator.repo}" is outside Git; excluded by scope ${scope}.`,
+				`Session ${row.sessionId} workspace "${row.locator.cwd}" is outside Git; excluded by scope ${scope}.`,
 			);
 	}
 	return { sessions, warnings };
@@ -563,7 +727,7 @@ async function requestControl(
 	const attachment = attachmentFor(router, sessionId);
 	const response = await router.request(
 		sessionId,
-		{ type: "control_request", operation, input, confirm: args.confirm === true },
+		controlRequestFrame(operation, input, args),
 		attachment.generation,
 		attachment,
 		args.timeoutMs === undefined ? undefined : { timeoutMs: args.timeoutMs },
@@ -572,6 +736,81 @@ async function requestControl(
 	return response;
 }
 
+/** Builds the public CLI control envelope without leaking envelope fields into operation input. */
+export function controlRequestFrame(
+	operation: string,
+	input: JsonRecord,
+	args: Pick<SdkSessionCliArgs, "confirm" | "idempotencyKey">,
+): JsonRecord {
+	return {
+		type: "control_request",
+		operation,
+		input,
+		confirm: args.confirm === true,
+		...(args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {}),
+	};
+}
+
+const BROKER_OPERATOR_ABORT_FIELDS = new Set(["mode", "scope", "operator"]);
+
+export function operatorAbortBrokerRequest(
+	sessionId: string,
+	operation: string,
+	input: JsonRecord,
+	args: Pick<SdkSessionCliArgs, "confirm" | "idempotencyKey">,
+): JsonRecord | undefined {
+	if (!Object.hasOwn(input, "operator")) return undefined;
+	if (operation !== "turn.abort")
+		throw new SdkSessionCliError("invalid_input", "operator is only available for terminal turn.abort.", 2);
+	if (input.operator !== true)
+		throw new SdkSessionCliError("invalid_input", "turn.abort operator must be true when provided.", 2);
+	if (input.mode !== "terminal")
+		throw new SdkSessionCliError("invalid_input", 'operator turn.abort requires mode:"terminal".', 2);
+	for (const key of Object.keys(input))
+		if (!BROKER_OPERATOR_ABORT_FIELDS.has(key))
+			throw new SdkSessionCliError(`invalid_input`, `Unknown turn.abort terminal field: ${key}`, 2);
+	if (input.scope !== undefined && input.scope !== "turn" && input.scope !== "owned")
+		throw new SdkSessionCliError("invalid_input", 'operator turn.abort scope must be "turn" or "owned".', 2);
+	if (args.confirm !== true)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --confirm.", 2);
+	if (!args.idempotencyKey)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --idempotency-key.", 2);
+	return { sessionId, operation: "turn.abort", input, confirm: true };
+}
+
+async function requestBrokerOperatorAbort(
+	agentDir: string,
+	request: JsonRecord,
+	args: SdkSessionCliArgs,
+): Promise<JsonRecord> {
+	const idempotencyKey = args.idempotencyKey;
+	if (!idempotencyKey)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --idempotency-key.", 2);
+	const discovery = await readSdkBrokerDiscovery(agentDir);
+	if (!discovery) throw new SdkSessionCliError("session_unavailable", "SDK broker discovery is unavailable.", 1);
+	const timeoutMs = args.timeoutMs ?? SESSION_REQUEST_TIMEOUT_MS;
+	const client = await SdkClient.connect(discovery.url, discovery.token, {
+		timeoutMs,
+		reconnectAttempts: 0,
+	});
+	try {
+		const response = await client.global("session.control", request, {
+			idempotencyKey,
+			timeoutMs,
+		});
+		const result = object(response);
+		if (!result) throw new SdkClientError("protocol_error", "SDK broker returned a malformed control response.");
+		throwResponseFailure(result);
+		return result;
+	} finally {
+		await client.close().catch(error => {
+			process.stderr.write(
+				`SDK broker control cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`,
+			);
+		});
+	}
+}
+
 async function requestQuery(
 	router: SessionRouter,
 	sessionId: string,
@@ -731,11 +970,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 };
 }
 
@@ -912,12 +1147,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
@@ -925,18 +1154,16 @@ 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 }),
+			...(seq === undefined ? {} : { generation: frame.generation, seq }),
 			payload: frame.body,
 		},
 		{
 			kind: frame.name,
-			...(frame.generation === undefined ? {} : { generation: frame.generation }),
-			...(seq === undefined ? {} : { seq }),
+			...(seq === undefined ? {} : { generation: frame.generation, seq }),
 		},
 	);
 }
@@ -1121,6 +1348,12 @@ async function offlineTailReplay(
 	});
 	if (!outcome.ok)
 		throw new SdkSessionCliError(outcome.error.code, outcome.error.message, 1, { certainty: outcome.certainty });
+	if ("rows" in outcome.result)
+		throw new SdkSessionCliError(
+			"malformed_response",
+			"broker returned a scoped result for retained transcript replay",
+			1,
+		);
 	const savedSession = outcome.result.savedSession;
 	if (!savedSession)
 		throw new SdkSessionCliError(
@@ -1144,7 +1377,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,
 		},
 	};
@@ -1252,6 +1487,8 @@ async function runLiveTail(
 		if (attachment.sessionId !== sessionId) return;
 		const item = tailItemFromRouterFrame(frame);
 		if (!item) return;
+		if (item.revision === undefined && checkpoint?.revision !== undefined) item.revision = checkpoint.revision;
+		// If checkpoint was undefined, queue for later stamping? For now leave without rev
 		applyLifecycle(mergeEventTailItems(eventItems, seenEvents, [item], include));
 	};
 
@@ -1293,10 +1530,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;
@@ -1342,9 +1587,20 @@ 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 = { 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>();
@@ -1413,6 +1669,8 @@ async function runRawControl(
 	const invalid = validateAdapterControl(operation, input);
 	if (invalid) throw new SdkSessionCliError(invalid.code, invalid.message, 2);
 	await ensureBroker({ agentDir });
+	const operatorRequest = operatorAbortBrokerRequest(sessionId, operation, input, args);
+	if (operatorRequest) return await requestBrokerOperatorAbort(agentDir, operatorRequest, args);
 	return await withRouter(agentDir, async router => await requestControl(router, sessionId, operation, input, args));
 }
 
@@ -1506,6 +1764,7 @@ export async function runSdkSessionCli(
 		const action = args.action;
 		if (
 			action !== "list" &&
+			action !== "search" &&
 			action !== "inspect" &&
 			action !== "send" &&
 			action !== "status" &&
@@ -1526,6 +1785,12 @@ export async function runSdkSessionCli(
 			writeOutput(stripSecretFields(await runList(agentDir, args)));
 			return;
 		}
+		if (action === "search") {
+			const search = await runSdkSearch(args);
+			writeOutput(args.json === true ? search.result : renderSdkSearchTable(search.result));
+			if (search.exitCode !== 0) setExitCode(search.exitCode);
+			return;
+		}
 		if (action === "inspect") {
 			writeOutput(stripSecretFields(await runInspect(agentDir, requireValue(args.sessionId, "<sessionId>"))));
 			return;
@@ -1577,6 +1842,12 @@ export async function runSdkSessionCli(
 		const kind = rawKind(requireValue(action, "<verb>"), args);
 		if (!kind) throw new SdkSessionCliError("usage", "raw requires one of: control, query, global.", 2);
 		const operation = kind === "query" ? requireValue(args.query, "--query") : requireValue(args.operation, "--op");
+		if (isRawSpawnOperation(kind, operation))
+			throw new SdkSessionCliError(
+				"adapter_operation_prohibited",
+				"session.spawn is unavailable through the SDK session CLI.",
+				1,
+			);
 		const dispositionError = cliOperationError(kind, operation);
 		if (dispositionError) throw new SdkSessionCliError(dispositionError.code, dispositionError.message, 1);
 		if (isEndpointOperation(operation))

package/src/sdk/client/client.ts

@@ -116,13 +116,13 @@ export interface SdkDispatchContext {
 	readonly generation: number;
 }
 
-/** Request identity retained after an uncertain send for lifecycle reconciliation. */
-
+/** Request identity retained after an uncertain send. */
 export interface SdkSentRecord {
 	readonly id: string;
 	readonly operation?: string;
 	readonly idempotencyKey?: string;
-	readonly fingerprint: string;
+	/** Present for lifecycle lookups; `session.spawn` replays through its idempotency key. */
+	readonly fingerprint?: string;
 }
 
 export type SdkFrameHandler = (frame: SdkFrame) => void;
@@ -473,8 +473,10 @@ export class SdkClient {
 		const sentOperation = typeof serializedFrame.operation === "string" ? serializedFrame.operation : undefined;
 		const sentIdempotencyKey =
 			typeof serializedFrame.idempotencyKey === "string" ? serializedFrame.idempotencyKey : undefined;
-		const sentFingerprint =
-			typeof serializedFrame.operation === "string"
+		const isSpawn = sentOperation === "session.spawn";
+		const sentFingerprint = isSpawn
+			? undefined
+			: typeof serializedFrame.operation === "string"
 				? lifecycleFingerprint(serializedFrame.operation, serializedFrame.input ?? {})
 				: inputFingerprint(serializedFrame.input ?? {});
 		const deferred = Promise.withResolvers<unknown>();
@@ -571,11 +573,15 @@ export class SdkClient {
 		// nothing reached the transport, so the request stays retryable and
 		// non-uncertain with no record retained.
 		pending.sent = true;
+		// A spawn claim replays only through its caller-provided idempotency key;
+		// it deliberately has no lifecycle fingerprint. Retain the common sent
+		// record anyway so an uncertain transport result tells the caller which
+		// key can join that durable claim.
 		this.#rememberSentRecord({
 			id,
-			operation: sentOperation,
-			idempotencyKey: sentIdempotencyKey,
-			fingerprint: sentFingerprint,
+			...(sentOperation === undefined ? {} : { operation: sentOperation }),
+			...(sentIdempotencyKey === undefined ? {} : { idempotencyKey: sentIdempotencyKey }),
+			...(sentFingerprint === undefined ? {} : { fingerprint: sentFingerprint }),
 		});
 		try {
 			incarnation.socket.send(serializedRequest);