@gajae-code/coding-agent 0.17.2 → 0.17.4

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

@@ -3,7 +3,9 @@ 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 { getAgentDir, logger, sanitizeDisplayLine } from "@gajae-code/utils";
+import { PublicCommandFailure, type PublicEffectProof, type PublicFailureKind } from "../../cli/public-command-errors";
+import type { EvidenceReference } from "../../cli/public-command-evidence";
 import { repo as resolveGitRepository } from "../../utils/git";
 import { ensureBroker } from "../broker/ensure";
 import { resolveSessionLocator } from "../broker/session-index";
@@ -20,6 +22,7 @@ import { createBrokerSessionLifecycleService } from "../lifecycle/broker-client"
 import type {
 	SessionLifecycleMutationRequest,
 	SessionLifecycleOperation,
+	SessionLifecycleResult,
 	SessionLifecycleSavedSession,
 	SessionLifecycleSavedSessionIdentity,
 	SessionLifecycleService,
@@ -58,12 +61,12 @@ export type SdkSessionCliAction =
 	| "send"
 	| "status"
 	| "tail"
+	| "close"
 	| "retire"
 	| "global"
 	| "raw"
 	| "control"
-	| "query"
-	| "global";
+	| "query";
 export type SdkSessionListScope = "repo" | "cwd" | "worktree" | "all";
 export type SdkSessionCliRawKind = "control" | "query" | "global";
 
@@ -86,6 +89,8 @@ export interface SdkSessionCliArgs {
 	strict?: boolean;
 	untilIdle?: boolean;
 	allEvents?: boolean;
+	/** tail --cursor: transcript row id the caller has already processed; rows up to and including it are omitted. */
+	afterTranscriptId?: string;
 	page?: boolean;
 	repo?: string;
 	scope?: string;
@@ -95,9 +100,14 @@ export interface SdkSessionCliArgs {
 	agentDir?: string;
 }
 
+export interface SdkSessionCliDependencies {
+	readonly lifecycleService?: SessionLifecycleService;
+}
+
 type JsonRecord = Record<string, unknown>;
 type LifecycleMutationOperation = Exclude<SessionLifecycleOperation, "session.lookup" | "session.list">;
-type TailExitReason = "idle" | "close";
+/** Why a tail call returned: the turn went idle, the session closed, or the caller's wait window closed (non-terminal). */
+type TailExitReason = "idle" | "close" | "timeout";
 export interface RetainedTranscriptTailReader {
 	readonly size: number;
 	readRange(start: number, end: number): Promise<Uint8Array>;
@@ -117,6 +127,7 @@ 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;
+export const SDK_JSON_INPUT_FILE_MAX_BYTES = 4 * 1024 * 1024;
 
 const TERMINAL_TURN_KINDS = new Set(["turn_end", "agent_end"]);
 const START_TURN_KINDS = new Set(["turn_start", "agent_start"]);
@@ -144,9 +155,109 @@ class SdkSessionCliError extends Error {
 	}
 }
 
+/** Translate only SDK-owned codes and explicitly allowlisted reconciliation fields. */
+export function sdkPublicFailure(code: string, details?: unknown, proof?: PublicEffectProof): PublicCommandFailure {
+	const kinds: Record<string, PublicFailureKind> = {
+		usage: "usage",
+		invalid_input: "usage",
+		invalid_json: "invalid_json",
+		broker_unavailable: "broker_unavailable",
+		session_unavailable: "endpoint_stale",
+		endpoint_stale: "endpoint_stale",
+		broker_restarting: "broker_restarting",
+		unavailable: "unavailable",
+		timeout: "timeout",
+		tail_timeout: "timeout",
+		wait_timeout: "wait_timeout",
+		uncertain_after_send: "uncertain_after_send",
+		authorization_denied: "authorization_denied",
+		unauthorized: "authorization_denied",
+		forbidden: "authorization_denied",
+		master_context_required: "authorization_denied",
+		adapter_operation_prohibited: "authorization_denied",
+		endpoint_credential_forbidden: "authorization_denied",
+	};
+	const references: EvidenceReference[] = [];
+	const source = object(details);
+	for (const [field, kind] of [
+		["sessionId", "sessionId"],
+		["operationRef", "operationRef"],
+		["clientRef", "operationRef"],
+		["idempotencyKey", "idempotencyKey"],
+		["claimId", "claimId"],
+		["commandId", "commandId"],
+		["turnId", "turnId"],
+	] as const) {
+		if (typeof source?.[field] === "string") references.push({ kind, value: source[field] as string });
+	}
+	return new PublicCommandFailure({
+		kind: Object.hasOwn(kinds, code) ? kinds[code]! : "operation_failed",
+		proof: code === "wait_timeout" ? "accepted" : proof,
+		references,
+	});
+}
+
+function normalizeSessionFailure(error: unknown, args: SdkSessionCliArgs): PublicCommandFailure {
+	if (error instanceof PublicCommandFailure)
+		return new PublicCommandFailure({
+			...error.input,
+			references: [
+				...(error.input.references ?? []),
+				...(sdkPublicFailure("operation_failed", {
+					sessionId: args.sessionId,
+					operationRef: args.opRef,
+					idempotencyKey: args.idempotencyKey,
+				}).input.references ?? []),
+			],
+		});
+	const context = { sessionId: args.sessionId, operationRef: args.opRef, idempotencyKey: args.idempotencyKey };
+	if (error instanceof SdkSessionCliError)
+		return sdkPublicFailure(
+			error.exitCode === 2 && error.code !== "invalid_json" ? "usage" : error.code,
+			{ ...context, ...object(error.details) },
+			error.exitCode === 2 ? "pre-effect" : undefined,
+		);
+	if (error instanceof SdkClientError)
+		return sdkPublicFailure(
+			error.code,
+			{ ...context, ...object(error.details) },
+			object(error.details)?.requestSent === false
+				? "pre-send"
+				: object(error.details)?.requestSent === true
+					? "sent"
+					: undefined,
+		);
+	if (error instanceof SessionRouterError)
+		return sdkPublicFailure(
+			error.phase === "pre_send" ? "endpoint_stale" : "uncertain_after_send",
+			context,
+			error.phase === "pre_send" ? "pre-send" : "sent",
+		);
+	return sdkPublicFailure("operation_failed", context);
+}
+
+/** Lifecycle terminality/retryability is not, by itself, proof of an effect outcome. */
+export function lifecyclePublicFailure(outcome: Extract<SessionLifecycleResult, { ok: false }>): PublicCommandFailure {
+	const failure = sdkPublicFailure(outcome.error.code);
+	// The service emits retryable protocol_error only when requestSent is explicitly false.
+	const proof: PublicEffectProof =
+		outcome.certainty === "retryable" && outcome.error.code === "protocol_error" ? "pre-send" : "unknown";
+	return new PublicCommandFailure({
+		...failure.input,
+		// Generic lifecycle codes cannot override the authoritative, conservative proof.
+		kind:
+			failure.input.kind === "usage" || failure.input.kind === "invalid_json"
+				? "operation_failed"
+				: failure.input.kind === "wait_timeout"
+					? "timeout"
+					: failure.input.kind,
+		proof,
+	});
+}
+
 class RetainedTranscriptTailError extends Error {
 	constructor(
-		readonly reason: "unavailable" | "corrupt" | "line_limit" | "scan_limit" | "changed",
+		readonly reason: "unavailable" | "corrupt" | "line_limit" | "scan_limit" | "changed" | "boundary_out_of_window",
 		message: string,
 	) {
 		super(message);
@@ -186,6 +297,128 @@ function parseInput(raw: string | undefined, source: string): JsonRecord {
 	}
 }
 
+function matchesSecurePathIdentity(before: fsSync.BigIntStats, after: fsSync.BigIntStats): boolean {
+	return (
+		before.dev === after.dev &&
+		before.ino === after.ino &&
+		before.nlink === after.nlink &&
+		before.mode === after.mode &&
+		before.size === after.size &&
+		before.mtimeNs === after.mtimeNs &&
+		before.ctimeNs === after.ctimeNs
+	);
+}
+
+function matchesSecureInputIdentity(before: fsSync.BigIntStats, after: fsSync.BigIntStats): boolean {
+	return before.isFile() && after.isFile() && matchesSecurePathIdentity(before, after);
+}
+
+type SecureInputPathSnapshot = {
+	resolvedPath: string;
+	ancestors: readonly { path: string; stat: fsSync.BigIntStats }[];
+};
+
+async function secureInputPath(filePath: string): Promise<SecureInputPathSnapshot> {
+	const resolved = path.resolve(filePath);
+	const canonical = await fs.realpath(resolved);
+	if (canonical !== resolved)
+		throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+	const ancestorPaths: string[] = [];
+	for (let current = path.dirname(resolved); ; ) {
+		ancestorPaths.unshift(current);
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	const ancestors = [] as { path: string; stat: fsSync.BigIntStats }[];
+	for (const ancestor of ancestorPaths) {
+		const stat = await fs.lstat(ancestor, { bigint: true });
+		if (!stat.isDirectory())
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+		ancestors.push({ path: ancestor, stat });
+	}
+	return { resolvedPath: resolved, ancestors };
+}
+
+function sameSecureInputAncestors(
+	before: readonly { path: string; stat: fsSync.BigIntStats }[],
+	after: readonly { path: string; stat: fsSync.BigIntStats }[],
+): boolean {
+	return (
+		before.length === after.length &&
+		before.every(
+			(entry, index) =>
+				after[index]?.path === entry.path &&
+				after[index] !== undefined &&
+				matchesSecurePathIdentity(entry.stat, after[index]!.stat),
+		)
+	);
+}
+
+/** Reads a 0600 JSON input through one descriptor, never through a replaceable pathname. */
+export async function readSecureJsonInputFile(filePath: string): Promise<string> {
+	let descriptor: fs.FileHandle | undefined;
+	try {
+		const beforePath = await secureInputPath(filePath);
+		const resolvedPath = beforePath.resolvedPath;
+		const noFollow = process.platform === "win32" ? 0 : fsSync.constants.O_NOFOLLOW;
+		descriptor = await fs.open(resolvedPath, fsSync.constants.O_RDONLY | noFollow);
+		const before = await descriptor.stat({ bigint: true });
+		const uid = process.getuid?.();
+		if (
+			!before.isFile() ||
+			(before.mode & 0o7777n) !== 0o600n ||
+			(process.platform !== "win32" && uid !== undefined && before.uid !== BigInt(uid))
+		)
+			throw new SdkSessionCliError(
+				"input_file_permissions",
+				"--json-input-file must be a regular file with 0600 permissions.",
+				2,
+			);
+		if (before.size > BigInt(SDK_JSON_INPUT_FILE_MAX_BYTES))
+			throw new SdkSessionCliError(
+				"usage",
+				`--json-input-file must be at most ${SDK_JSON_INPUT_FILE_MAX_BYTES} bytes.`,
+				2,
+			);
+
+		const pathIdentity = await fs.lstat(resolvedPath, { bigint: true });
+		const openedPath = await secureInputPath(resolvedPath);
+		if (
+			!matchesSecureInputIdentity(before, pathIdentity) ||
+			!sameSecureInputAncestors(beforePath.ancestors, openedPath.ancestors)
+		)
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+
+		const size = Number(before.size);
+		const bytes = Buffer.alloc(size);
+		let offset = 0;
+		while (offset < size) {
+			const read = await descriptor.read(bytes, offset, size - offset, offset);
+			if (read.bytesRead === 0) break;
+			offset += read.bytesRead;
+		}
+		if (offset !== size)
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+
+		const after = await descriptor.stat({ bigint: true });
+		const finalPath = await secureInputPath(resolvedPath);
+		const finalPathIdentity = await fs.lstat(resolvedPath, { bigint: true });
+		if (
+			!matchesSecureInputIdentity(before, after) ||
+			!matchesSecureInputIdentity(before, finalPathIdentity) ||
+			!sameSecureInputAncestors(beforePath.ancestors, finalPath.ancestors)
+		)
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+		return bytes.toString("utf8");
+	} catch (error) {
+		if (error instanceof SdkSessionCliError) throw error;
+		throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+	} finally {
+		if (descriptor !== undefined) await descriptor.close().catch(() => {});
+	}
+}
+
 function containsSecretField(value: unknown): boolean {
 	if (Array.isArray(value)) return value.some(containsSecretField);
 	if (!isRecord(value)) return false;
@@ -211,14 +444,7 @@ async function inputFromArgs(args: SdkSessionCliArgs): Promise<JsonRecord> {
 	}
 	if (args.jsonInputFile !== undefined) {
 		try {
-			const stat = await fs.stat(args.jsonInputFile);
-			if (!stat.isFile() || (stat.mode & 0o077) !== 0)
-				throw new SdkSessionCliError(
-					"input_file_permissions",
-					"--json-input-file must be a regular file with 0600 permissions.",
-					2,
-				);
-			return parseInput(await Bun.file(args.jsonInputFile).text(), "--json-input-file");
+			return parseInput(await readSecureJsonInputFile(args.jsonInputFile), "--json-input-file");
 		} catch (error) {
 			if (error instanceof SdkSessionCliError) throw error;
 			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
@@ -274,9 +500,8 @@ async function bounded<T>(promise: Promise<T>, timeoutMs: number, message: strin
 	}
 }
 
-function reportRouterCleanupFailure(error: unknown): void {
-	const message = error instanceof Error ? error.message : String(error);
-	process.stderr.write(`SDK session Router cleanup failed: ${message}\n`);
+function reportRouterCleanupFailure(): void {
+	logger.warn("SDK session Router cleanup failed");
 }
 
 /**
@@ -314,8 +539,14 @@ async function withRouter<T>(
 	}
 	try {
 		await bounded(router.stop(), ROUTER_STOP_TIMEOUT_MS, "SDK session Router shutdown timed out.");
-	} catch (error) {
-		reportRouterCleanupFailure(error);
+	} catch {
+		if (actionFailed) {
+			const failure = normalizeSessionFailure(actionError, {});
+			actionError = new PublicCommandFailure({
+				...failure.input,
+				diagnostics: [...(failure.input.diagnostics ?? []), "router_cleanup_failed"],
+			});
+		} else reportRouterCleanupFailure();
 	}
 	if (actionFailed) throw actionError;
 	return result;
@@ -336,12 +567,17 @@ function throwResponseFailure(response: unknown): void {
 	const record = object(response);
 	if (record?.ok !== false) return;
 	const failure = object(record.error);
-	throw new SdkSessionCliError(
-		typeof failure?.code === "string" ? failure.code : "unavailable",
-		typeof failure?.message === "string" ? failure.message : "SDK request failed.",
-		1,
+	const failureInput = sdkPublicFailure(
+		typeof failure?.code === "string" ? failure.code : "operation_failed",
 		failure,
 	);
+	throw new PublicCommandFailure({
+		...failureInput.input,
+		references: [
+			...(failureInput.input.references ?? []),
+			...(sdkPublicFailure("operation_failed", record.result).input.references ?? []),
+		],
+	});
 }
 
 async function paginatedSessionList(
@@ -488,9 +724,10 @@ async function probeSearchRows(agentDir: string, result: SdkSearchResultV1): Pro
 	} catch {
 		return {
 			...result,
+			warnings: [...result.warnings, "probe_unavailable"],
 			rows: mergeProbedSearchRows(
 				result.rows,
-				rows.map(row => ({ ...row, probe: row.live ? "unreachable" : "stale" })),
+				rows.map(row => (row.live ? { ...row } : { ...row, probe: "stale" as const })),
 			),
 		};
 	}
@@ -501,54 +738,32 @@ 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 = path.resolve(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 };
+): Promise<{ result: SdkSearchResultV1; exitCode: 0 }> {
+	try {
+		const agentDir = path.resolve(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 sdkPublicFailure("usage", undefined, "pre-effect");
+					})();
+		const request = searchScopeRequest(scope, locator);
+		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")
+					throw sdkPublicFailure(outcome.result.error?.code ?? "unavailable");
+				return { result: await probe(agentDir, outcome.result), exitCode: 0 };
+			}
+			throw sdkPublicFailure("operation_failed");
 		}
-		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,
-		};
+		throw lifecyclePublicFailure(outcome);
+	} catch (error) {
+		throw normalizeSessionFailure(error, args);
 	}
-	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 {
@@ -560,7 +775,10 @@ function searchScopeLabel(result: SdkSearchResultV1): string {
 }
 
 function safeSearchText(value: string): string {
-	return truncateToWidth(replaceTabs(value).replaceAll(/[\r\n]/g, " "), SEARCH_TEXT_WIDTH);
+	return truncateToWidth(
+		replaceTabs(sanitizeDisplayLine(value).replaceAll(/[\u2028\u2029]/gu, " ")),
+		SEARCH_TEXT_WIDTH,
+	);
 }
 
 /** Renders a credential-free scope/status preamble and bounded search table. */
@@ -568,15 +786,15 @@ 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}`,
+		`Status: ${safeSearchText(result.status)}`,
+		`Observed at: ${safeSearchText(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)}`,
+			`${safeSearchText(row.id).padEnd(20)}  ${safeSearchText(row.probe ?? "-").padEnd(11)}  ${String(row.live).padEnd(4)}  ${safeSearchText(row.locator.cwd)}`,
 		);
 	return lines.join("\n");
 }
@@ -844,22 +1062,35 @@ async function requestBrokerOperatorAbort(
 		timeoutMs,
 		reconnectAttempts: 0,
 	});
+	let actionFailed = false;
+	let actionError: unknown;
+	let result!: JsonRecord;
 	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`,
-			);
-		});
+		const record = object(response);
+		if (!record) throw new SdkClientError("protocol_error", "SDK broker returned a malformed control response.");
+		throwResponseFailure(record);
+		result = record;
+	} catch (error) {
+		actionFailed = true;
+		actionError = error;
+	}
+	try {
+		await client.close();
+	} catch {
+		if (actionFailed) {
+			const failure = normalizeSessionFailure(actionError, args);
+			actionError = new PublicCommandFailure({
+				...failure.input,
+				diagnostics: [...(failure.input.diagnostics ?? []), "broker_cleanup_failed"],
+			});
+		} else logger.warn("SDK broker client cleanup failed");
 	}
+	if (actionFailed) throw actionError;
+	return result;
 }
 
 async function requestQuery(
@@ -939,6 +1170,8 @@ export async function waitForTerminalStatus(
  * reports when a request that was already on the wire is abandoned.
  */
 function isWaitWindowFailure(error: unknown): boolean {
+	if (error instanceof PublicCommandFailure)
+		return error.input.kind === "timeout" || error.input.kind === "uncertain_after_send";
 	if (error instanceof SdkClientError) return error.code === "timeout" || error.code === "uncertain_after_send";
 	return error instanceof SdkSessionCliError && error.code === "timeout";
 }
@@ -958,30 +1191,49 @@ async function runSend(agentDir: string, sessionId: string, args: SdkSessionCliA
 	if (inputRef === undefined) promptInput.clientRef = clientRef;
 	const invalid = validateAdapterControl("turn.prompt", promptInput);
 	if (invalid) throw new SdkSessionCliError(invalid.code, invalid.message, 2);
-	await ensureBroker({ agentDir });
+	let accepted = false;
+	try {
+		await ensureBroker({ agentDir });
 
-	return await withRouter(agentDir, [sessionId], async router => {
-		const response = await requestControl(router, sessionId, "turn.prompt", promptInput, args);
-		const result: JsonRecord = {
-			version: SESSION_ROWS_VERSION,
-			operationRef: clientRef,
-			status: "accepted",
-			receipt: resultObject(response) ?? response,
-		};
-		if (args.wait === true) {
-			const outcome = await waitForTerminalStatus(router, sessionId, clientRef, args.timeoutMs ?? 30_000);
-			if (!outcome.terminal)
-				throw new SdkSessionCliError(
-					"wait_timeout",
-					`Prompt ${clientRef} did not reach a terminal state within the wait window.`,
-					1,
-					{ operationRef: clientRef, status: outcome.status },
-				);
-			result.status = outcome.status;
-			result.statusDetail = outcome.detail;
-		}
-		return { ok: true, result };
-	});
+		return await withRouter(agentDir, [sessionId], async router => {
+			const response = await requestControl(router, sessionId, "turn.prompt", promptInput, args);
+			accepted = true;
+			const result: JsonRecord = {
+				version: SESSION_ROWS_VERSION,
+				operationRef: clientRef,
+				status: "accepted",
+				receipt: resultObject(response) ?? response,
+			};
+			if (args.wait === true) {
+				const outcome = await waitForTerminalStatus(router, sessionId, clientRef, args.timeoutMs ?? 30_000);
+				if (!outcome.terminal)
+					throw new SdkSessionCliError(
+						"wait_timeout",
+						`Prompt ${clientRef} did not reach a terminal state within the wait window.`,
+						1,
+						{ operationRef: clientRef, status: outcome.status },
+					);
+				result.status = outcome.status;
+				result.statusDetail = outcome.detail;
+			}
+			return { ok: true, result };
+		});
+	} catch (error) {
+		const failure = normalizeSessionFailure(error, { ...args, sessionId, opRef: clientRef });
+		throw new PublicCommandFailure({
+			...failure.input,
+			...(accepted
+				? {
+						proof: "accepted" as const,
+						kind:
+							failure.input.kind === "uncertain_after_send" || failure.input.kind === "timeout"
+								? ("wait_timeout" as const)
+								: failure.input.kind,
+					}
+				: {}),
+			references: failure.input.references,
+		});
+	}
 }
 
 async function runStatus(
@@ -1266,14 +1518,23 @@ function retainedTranscriptCorrupt(): RetainedTranscriptTailError {
 	);
 }
 
-export async function scanRetainedTranscriptTail(reader: RetainedTranscriptTailReader): Promise<unknown[]> {
+export async function scanRetainedTranscriptTail(
+	reader: RetainedTranscriptTailReader,
+	options: { boundaryId?: string } = {},
+): Promise<unknown[]> {
 	if (!Number.isSafeInteger(reader.size) || reader.size < 0) throw retainedTranscriptUnavailable();
 	const entries: unknown[] = [];
+	let rowsAfterBoundary = 0;
+	let boundaryFound = false;
 	let position = reader.size;
 	let scannedBytes = 0;
 	let scannedLines = 0;
 	let trailingFragment = new Uint8Array();
-	while (position > 0 && entries.length < TAIL_OFFLINE_MAX_ENTRIES) {
+	while (
+		position > 0 &&
+		(entries.length < TAIL_OFFLINE_MAX_ENTRIES || (options.boundaryId !== undefined && !boundaryFound)) &&
+		(options.boundaryId === undefined || !boundaryFound)
+	) {
 		const remainingBytes = TAIL_OFFLINE_MAX_SCAN_BYTES - scannedBytes;
 		if (remainingBytes <= 0)
 			throw new RetainedTranscriptTailError(
@@ -1313,7 +1574,11 @@ export async function scanRetainedTranscriptTail(reader: RetainedTranscriptTailR
 		}
 
 		let lineEnd = complete.byteLength;
-		while (lineEnd > 0 && entries.length < TAIL_OFFLINE_MAX_ENTRIES) {
+		while (
+			lineEnd > 0 &&
+			(entries.length < TAIL_OFFLINE_MAX_ENTRIES || (options.boundaryId !== undefined && !boundaryFound)) &&
+			(options.boundaryId === undefined || !boundaryFound)
+		) {
 			const newline = complete.lastIndexOf(0x0a, lineEnd - 1);
 			const lineStart = newline < 0 ? 0 : newline + 1;
 			const line = complete.subarray(lineStart, lineEnd);
@@ -1331,12 +1596,24 @@ export async function scanRetainedTranscriptTail(reader: RetainedTranscriptTailR
 					"Retained transcript history exceeds the bounded tail replay limit.",
 				);
 			try {
-				entries.push(JSON.parse(transcriptDecoder.decode(line)));
-			} catch {
+				const entry: unknown = JSON.parse(transcriptDecoder.decode(line));
+				if (options.boundaryId !== undefined && isRecord(entry) && entry.id === options.boundaryId) {
+					if (rowsAfterBoundary > TAIL_OFFLINE_MAX_ENTRIES)
+						throw new RetainedTranscriptTailError(
+							"boundary_out_of_window",
+							"The requested transcript boundary is older than the bounded offline tail window.",
+						);
+					boundaryFound = true;
+				} else if (options.boundaryId !== undefined && !boundaryFound) {
+					rowsAfterBoundary++;
+				}
+				if (entries.length < TAIL_OFFLINE_MAX_ENTRIES) entries.push(entry);
+			} catch (error) {
+				if (error instanceof RetainedTranscriptTailError) throw error;
 				throw retainedTranscriptCorrupt();
 			}
 		}
-		if (entries.length === TAIL_OFFLINE_MAX_ENTRIES) break;
+		if (entries.length === TAIL_OFFLINE_MAX_ENTRIES && (options.boundaryId === undefined || boundaryFound)) break;
 		if (start > 0) {
 			if (partial.byteLength > TAIL_OFFLINE_MAX_LINE_BYTES)
 				throw new RetainedTranscriptTailError(
@@ -1350,7 +1627,10 @@ export async function scanRetainedTranscriptTail(reader: RetainedTranscriptTailR
 	return entries.reverse();
 }
 
-async function readRetainedTranscriptTail(savedSession: SessionLifecycleSavedSession): Promise<unknown[]> {
+async function readRetainedTranscriptTail(
+	savedSession: SessionLifecycleSavedSession,
+	afterTranscriptId?: string,
+): Promise<unknown[]> {
 	let descriptor: fs.FileHandle | undefined;
 	try {
 		descriptor = await fs.open(savedSession.path, retainedTranscriptOpenFlags());
@@ -1360,10 +1640,13 @@ async function readRetainedTranscriptTail(savedSession: SessionLifecycleSavedSes
 		// Bind every range read to the opened descriptor so a later pathname replacement
 		// cannot change the retained history selected by the lifecycle lookup.
 		const file = Bun.file(descriptor.fd);
-		const entries = await scanRetainedTranscriptTail({
-			size: Number(before.size),
-			readRange: async (start, end) => new Uint8Array(await file.slice(start, end).arrayBuffer()),
-		});
+		const entries = await scanRetainedTranscriptTail(
+			{
+				size: Number(before.size),
+				readRange: async (start, end) => new Uint8Array(await file.slice(start, end).arrayBuffer()),
+			},
+			{ boundaryId: afterTranscriptId },
+		);
 		const after = await descriptor.stat({ bigint: true });
 		if (
 			!matchesRetainedTranscriptIdentity(savedSession.identity, after) ||
@@ -1391,6 +1674,7 @@ async function offlineTailReplay(
 	agentDir: string,
 	sessionId: string,
 	row: SdkSessionRowV1,
+	afterTranscriptId?: string,
 ): Promise<unknown> {
 	const lifecycle = createBrokerSessionLifecycleService(agentDir);
 	const outcome = await lifecycle.list({
@@ -1398,8 +1682,7 @@ async function offlineTailReplay(
 		capability: "session.list",
 		target: { cwd: repo, resolveSessionId: sessionId },
 	});
-	if (!outcome.ok)
-		throw new SdkSessionCliError(outcome.error.code, outcome.error.message, 1, { certainty: outcome.certainty });
+	if (!outcome.ok) throw lifecyclePublicFailure(outcome);
 	if ("rows" in outcome.result)
 		throw new SdkSessionCliError(
 			"malformed_response",
@@ -1415,7 +1698,7 @@ async function offlineTailReplay(
 		);
 	let entries: unknown[];
 	try {
-		entries = await readRetainedTranscriptTail(savedSession);
+		entries = await readRetainedTranscriptTail(savedSession, afterTranscriptId);
 	} catch (error) {
 		const retained = error instanceof RetainedTranscriptTailError ? error : retainedTranscriptUnavailable();
 		throw new SdkSessionCliError("retention_gap", retained.message, 1, {
@@ -1423,15 +1706,21 @@ async function offlineTailReplay(
 			reason: retained.reason,
 		});
 	}
+	const items = entries.map((entry, index) =>
+		toTailItemV1(entry, { kind: "transcript", revision: index + 1, seq: index }),
+	);
+	// The same contract as a live resume: rows up to and including the id the
+	// caller already has are omitted, so a session that stopped between two
+	// polls does not replay processed history on the next one. Unknown
+	// boundary keeps everything (a duplicate is recoverable; a missing row is not).
+	const boundary = afterTranscriptId === undefined ? -1 : items.findIndex(item => item.id === afterTranscriptId);
 	return {
 		ok: true,
 		result: {
 			version: SESSION_ROWS_VERSION,
 			source: "offline",
 			session: row,
-			items: entries.map((entry, index) =>
-				toTailItemV1(entry, { kind: "transcript", revision: index + 1, seq: index }),
-			),
+			items: boundary >= 0 ? items.slice(boundary + 1) : items,
 			terminal: true,
 		},
 	};
@@ -1460,6 +1749,8 @@ async function runLiveTail(
 	const seenEvents = new Set<string>();
 	const liveRevisionBuffer = new TailRevisionBuffer();
 	let checkpoint: SdkCheckpointRecordV1 | undefined;
+	let transcriptCheckpoint: SdkCheckpointRecordV1 | undefined;
+	let eventReplayCheckpoint: SdkCheckpointRecordV1 | undefined;
 	let gap: SdkRetentionGapV1 | undefined;
 	let liveReason: TailExitReason | undefined;
 	let resolveLive: ((reason: TailExitReason) => void) | undefined;
@@ -1473,6 +1764,7 @@ async function runLiveTail(
 	let turnIdle = false;
 	let turnStateKey: TailSeqKey | undefined;
 	let closed = false;
+	let acceptingLiveFrames = true;
 	// Lifecycle kind already claimed at each canonical position. A same-kind
 	// duplicate never reaches here (dedupe keys include kind), so any entry that
 	// disagrees is a host stating two different lifecycle kinds at one position.
@@ -1537,6 +1829,7 @@ async function runLiveTail(
 	};
 
 	const recordLiveFrame = (attachment: SessionAttachment, frame: SessionRouterFrame): void => {
+		if (!acceptingLiveFrames) return;
 		if (attachment.sessionId !== sessionId) return;
 		const item = tailItemFromRouterFrame(frame);
 		if (!item) return;
@@ -1572,6 +1865,8 @@ async function runLiveTail(
 			throwResponseFailure(checkpointResponse);
 			const extraction = extractCheckpoint(checkpointResponse);
 			checkpoint = extraction.record;
+			transcriptCheckpoint = checkpoint;
+			eventReplayCheckpoint = checkpoint;
 			gap = extraction.gap;
 			if (checkpoint !== undefined)
 				applyLifecycle(
@@ -1585,7 +1880,87 @@ async function runLiveTail(
 					gap,
 				);
 
+			// Which snapshot to page. A fresh tail pages the checkpoint it was just
+			// handed. A resumed tail (`--cursor`) must NOT page the exchanged cursor:
+			// that one is pinned to the OLD snapshot at offset 0, so it would replay
+			// every row the caller already processed. It pages a fresh snapshot
+			// instead and drops rows up to the caller's `--after-transcript-id`, so
+			// the result is exactly the transcript delta since the last tail - the
+			// rows that carry tool calls and interim assistant text.
 			let cursor = extraction.cursor;
+			if (args.cursor !== undefined) {
+				if (cursor === undefined)
+					throw new SdkSessionCliError(
+						"unavailable",
+						"The host did not return the exchanged checkpoint needed to resume this tail.",
+						1,
+					);
+				const exchangedCursor = cursor;
+				let freshPagingCursor: string | undefined;
+				let freshPagingCheckpoint: SdkCheckpointRecordV1 | undefined;
+				try {
+					const fresh = await router.request(
+						sessionId,
+						{ type: "query_request", query: "session.checkpoint", input: {} },
+						attachment.generation,
+						attachment,
+						args.timeoutMs === undefined ? undefined : { timeoutMs: args.timeoutMs },
+					);
+					throwResponseFailure(fresh);
+					const freshExtraction = extractCheckpoint(fresh);
+					freshPagingCursor = freshExtraction.cursor;
+					freshPagingCheckpoint = freshExtraction.record;
+					if (freshPagingCursor === undefined || freshPagingCheckpoint === undefined)
+						throw new Error("The host returned an incomplete transcript checkpoint.");
+				} catch {
+					// Keep the exchanged cursor as a complete fallback. Returning only live
+					// frames after a failed fresh checkpoint would silently discard the
+					// transcript delta the caller is resuming for.
+					freshPagingCursor = undefined;
+					freshPagingCheckpoint = undefined;
+				}
+				if (freshPagingCursor !== undefined && freshPagingCheckpoint !== undefined) {
+					const pagingCursor = freshPagingCursor;
+					const pagingCheckpoint = freshPagingCheckpoint;
+					// The exchanged cursor is pinned to the old snapshot. Release it only
+					// after the fresh snapshot has been acquired so a failed mint can still
+					// page the exchanged snapshot instead of returning partial success.
+					let drain: string | undefined = exchangedCursor;
+					while (drain !== undefined) {
+						try {
+							const page = extractTranscriptPage(
+								await router.request(
+									sessionId,
+									{ type: "query_request", query: "transcript.list", input: {}, cursor: drain },
+									attachment.generation,
+									attachment,
+									args.timeoutMs === undefined ? undefined : { timeoutMs: args.timeoutMs },
+								),
+							);
+							drain = page.complete ? undefined : page.cursor;
+						} catch {
+							// Releasing is best-effort; a pin that cannot be drained expires with its TTL.
+							drain = undefined;
+						}
+					}
+					cursor = pagingCursor;
+					transcriptCheckpoint = pagingCheckpoint;
+					eventReplayCheckpoint = pagingCheckpoint;
+					applyLifecycle(
+						mergeEventTailItems(
+							eventItems,
+							seenEvents,
+							liveRevisionBuffer.resolve(pagingCheckpoint.revision),
+							include,
+						),
+					);
+				} else {
+					cursor = exchangedCursor;
+					transcriptCheckpoint = checkpoint;
+					eventReplayCheckpoint = checkpoint;
+				}
+			}
+			const transcriptStart = transcriptItems.length;
 			while (cursor !== undefined) {
 				const response = await router.request(
 					sessionId,
@@ -1596,7 +1971,7 @@ async function runLiveTail(
 				);
 				throwResponseFailure(response);
 				const page = extractTranscriptPage(response);
-				const rev = checkpoint?.revision;
+				const rev = transcriptCheckpoint?.revision;
 				let nextSeq = transcriptItems.length;
 				mergeTailItems(
 					transcriptItems,
@@ -1604,7 +1979,7 @@ async function runLiveTail(
 					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.generation === undefined) it.generation = transcriptCheckpoint?.generation ?? 0;
 						if (it.seq === undefined) it.seq = nextSeq++;
 						return it;
 					}),
@@ -1613,14 +1988,23 @@ async function runLiveTail(
 				if (page.complete || page.cursor === undefined) break;
 				cursor = page.cursor;
 			}
+			if (args.cursor !== undefined && args.afterTranscriptId !== undefined) {
+				// Drop the rows the caller already has. Unknown boundary (row rotated
+				// out, or a different session) → keep everything: a duplicate is
+				// recoverable downstream, a silently missing row is not.
+				const boundary = transcriptItems.findIndex(
+					(item, index) => index >= transcriptStart && item.id === args.afterTranscriptId,
+				);
+				if (boundary >= 0) transcriptItems.splice(transcriptStart, boundary + 1 - transcriptStart);
+			}
 
 			const replayResponse = await router.request(
 				sessionId,
 				{
 					type: "event_replay",
-					...(checkpoint === undefined
+					...(eventReplayCheckpoint === undefined
 						? {}
-						: { sinceGeneration: checkpoint.generation, sinceSeq: checkpoint.seq }),
+						: { sinceGeneration: eventReplayCheckpoint.generation, sinceSeq: eventReplayCheckpoint.seq }),
 				},
 				attachment.generation,
 				attachment,
@@ -1628,7 +2012,7 @@ async function runLiveTail(
 			);
 			throwResponseFailure(replayResponse);
 			const replay = object(replayResponse) ?? {};
-			const replayGap = eventGapToRetentionGap(replay.gap, replay, checkpoint);
+			const replayGap = eventGapToRetentionGap(replay.gap, replay, eventReplayCheckpoint);
 			if (replayGap !== undefined) {
 				gap = replayGap;
 				if (args.strict === true)
@@ -1655,20 +2039,21 @@ async function runLiveTail(
 			}
 			const replayItems = rawEvents.map(event => {
 				const it = toTailItemV1(event, { kind: "event" });
-				if (it.revision === undefined && checkpoint?.revision !== undefined) it.revision = checkpoint.revision;
+				if (it.revision === undefined && eventReplayCheckpoint?.revision !== undefined)
+					it.revision = eventReplayCheckpoint.revision;
 				return it;
 			});
 			applyLifecycle(mergeEventTailItems(eventItems, seenEvents, replayItems, include));
 			if (malformed !== undefined) throw malformed;
-			if (checkpoint !== undefined) {
+			if (eventReplayCheckpoint !== undefined) {
 				const checkpointKey = {
-					revision: checkpoint.revision,
-					generation: checkpoint.generation,
-					seq: checkpoint.seq,
+					revision: eventReplayCheckpoint.revision,
+					generation: eventReplayCheckpoint.generation,
+					seq: eventReplayCheckpoint.seq,
 				};
 				if (turnStateKey === undefined || compareTailSeqKeys(checkpointKey, turnStateKey) >= 0) {
 					turnStateKey = checkpointKey;
-					turnIdle = checkpoint.idle;
+					turnIdle = eventReplayCheckpoint.idle;
 				}
 			}
 			if (liveReason === undefined && args.untilIdle === true && turnIdle) liveReason = "idle";
@@ -1677,18 +2062,14 @@ async function runLiveTail(
 				resolveLive = completion.resolve;
 				rejectLive = completion.reject;
 				const timeoutMs = args.timeoutMs ?? 10_000;
-				const timer = setTimeout(
-					() =>
-						completion.reject(
-							new SdkSessionCliError(
-								"tail_timeout",
-								"Tail did not reach an exit condition within the wait window.",
-								1,
-								{ sessionId, timeoutMs },
-							),
-						),
-					timeoutMs,
-				);
+				// The wait window closing is not a failure: it is the caller's bound on
+				// one tail call, and everything collected inside it (transcript rows,
+				// replayed and live events) is a valid, non-terminal observation.
+				// Throwing here discarded that observation, so a poller watching a
+				// running turn with `--until-idle` saw nothing until the turn ended -
+				// every mid-turn tool call and interim line was lost, and the poll
+				// itself blocked for the whole window. `terminal: false` says the rest.
+				const timer = setTimeout(() => completion.resolve("timeout"), timeoutMs);
 				try {
 					liveReason = await completion.promise;
 				} finally {
@@ -1697,6 +2078,48 @@ async function runLiveTail(
 					rejectLive = undefined;
 				}
 			}
+			// Freeze collection before minting the caller's continuation. A host can
+			// capture the checkpoint watermark and publish a frame before the response
+			// reaches us; that frame belongs to the next poll, not behind this cursor.
+			acceptingLiveFrames = false;
+			// Mint the caller's continuation only after replay and live follow have
+			// reached their exit condition. A checkpoint minted earlier can point
+			// behind events already included in this response, causing the next poll
+			// to replay observations the caller already processed.
+			let resumeCursor: string | undefined;
+			try {
+				const fresh = await router.request(
+					sessionId,
+					{ type: "query_request", query: "session.checkpoint", input: {} },
+					attachment.generation,
+					attachment,
+					args.timeoutMs === undefined ? undefined : { timeoutMs: args.timeoutMs },
+				);
+				throwResponseFailure(fresh);
+				resumeCursor = extractCheckpoint(fresh).cursor;
+			} catch (error) {
+				// A closed session has no next poll that could resume, so preserve the
+				// complete terminal observation even when the host tears down the
+				// connection before it can mint a final cursor. Active and timed-out
+				// tails still fail closed: returning them without a continuation would
+				// let the caller advance past observations it cannot resume.
+				if (liveReason !== "close") {
+					if (error instanceof SdkSessionCliError) throw error;
+					throw new SdkSessionCliError(
+						"unavailable",
+						"The host did not return a continuation checkpoint for this tail.",
+						1,
+						{ sessionId },
+					);
+				}
+			}
+			if (resumeCursor === undefined && liveReason !== "close")
+				throw new SdkSessionCliError(
+					"unavailable",
+					"The host did not return a continuation cursor for this tail.",
+					1,
+					{ sessionId },
+				);
 			return {
 				ok: true,
 				result: {
@@ -1704,6 +2127,13 @@ async function runLiveTail(
 					source: "session",
 					session: row,
 					...(checkpoint === undefined ? {} : { checkpoint }),
+					// A signed, UNCONSUMED checkpoint cursor to resume from. Carried as
+					// `cursor`, not `checkpointToken`: output passes through
+					// stripSecretFields, whose /token/i matches the latter by name, so a
+					// caller never saw it and no tail could ever be resumed (every poll
+					// replayed the whole session). It is an opaque per-grant cursor, not a
+					// credential - the same shape `list`/`transcript` already return.
+					...(resumeCursor === undefined ? {} : { cursor: resumeCursor }),
 					...(gap === undefined ? {} : { gap }),
 					items: tailItems(),
 					terminal: liveReason === "idle" || liveReason === "close",
@@ -1720,6 +2150,12 @@ export async function runTail(
 	sessionId: string,
 	args: SdkSessionCliArgs,
 ): Promise<unknown> {
+	if (args.cursor !== undefined && args.afterTranscriptId === undefined)
+		throw new SdkSessionCliError(
+			"usage",
+			"--after-transcript-id is required when resuming a session tail with --cursor.",
+			2,
+		);
 	const row = (await sessionRows(agentDir, { resolveSessionId: sessionId })).sessions.find(
 		candidate => candidate.sessionId === sessionId,
 	);
@@ -1727,7 +2163,10 @@ export async function runTail(
 		throw new SdkSessionCliError("session_unavailable", `Session ${sessionId} is not indexed by the broker.`, 1);
 	if (row.deleted)
 		throw new SdkSessionCliError("session_deleted", `Session ${sessionId} was deleted and has no tail.`, 1);
-	if (!row.live || row.terminalUncertain === true) return await offlineTailReplay(repo, agentDir, sessionId, row);
+	if (row.live && row.terminalUncertain !== true && args.afterTranscriptId !== undefined && args.cursor === undefined)
+		throw new SdkSessionCliError("usage", "--after-transcript-id requires --cursor for a live session tail.", 2);
+	if (!row.live || row.terminalUncertain === true)
+		return await offlineTailReplay(repo, agentDir, sessionId, row, args.afterTranscriptId);
 	return await runLiveTail(agentDir, sessionId, row, args);
 }
 
@@ -1803,11 +2242,44 @@ function lifecycleMutationRequest(
 	return { ...base, operation, capability: "session.delete", target };
 }
 
+async function resolveCloseAuthority(
+	lifecycle: SessionLifecycleService,
+	sessionId: string,
+): Promise<{ endpointGeneration: number; endpointIncarnation: string }> {
+	const listed = await lifecycle.list({
+		actor: SDK_SESSION_CLI_LIFECYCLE_ACTOR,
+		capability: "session.list",
+		target: { resolveSessionId: sessionId },
+	});
+	if (!listed.ok) throw new SdkSessionCliError(listed.error.code, listed.error.message, 1);
+	if (!("sessions" in listed.result))
+		throw new SdkSessionCliError("malformed_response", "broker returned a scoped result for session close", 1);
+	const row = listed.result.sessions.find(session => session.sessionId === sessionId);
+	if (
+		row === undefined ||
+		typeof row.endpointGeneration !== "number" ||
+		!Number.isSafeInteger(row.endpointGeneration) ||
+		row.endpointGeneration <= 0 ||
+		typeof row.endpointIncarnation !== "string" ||
+		!/^[a-f0-9]{64}$/u.test(row.endpointIncarnation)
+	)
+		throw new SdkSessionCliError("session_unavailable", `Session ${sessionId} has no live endpoint authority.`, 1);
+	return { endpointGeneration: row.endpointGeneration, endpointIncarnation: row.endpointIncarnation };
+}
+
+function sessionCloseRequestKey(
+	sessionId: string,
+	authority: { endpointGeneration: number; endpointIncarnation: string },
+): string {
+	return `${SDK_SESSION_CLI_LIFECYCLE_ACTOR.namespace}:session.close:${sessionId}:${authority.endpointGeneration}:${authority.endpointIncarnation}`;
+}
+
 async function runRawGlobal(
 	agentDir: string,
 	operation: string,
 	input: JsonRecord,
 	args: SdkSessionCliArgs,
+	lifecycleOverride?: SessionLifecycleService,
 ): Promise<unknown> {
 	if (args.page && operation !== "session.list")
 		throw new SdkSessionCliError("usage", "--page is only available for raw global session.list.", 2);
@@ -1834,7 +2306,7 @@ async function runRawGlobal(
 	if (operation === "session.lookup") {
 		if (!args.idempotencyKey)
 			throw new SdkSessionCliError("invalid_input", "--idempotency-key is required for session lookup.", 2);
-		const lifecycle = createBrokerSessionLifecycleService(agentDir);
+		const lifecycle = lifecycleOverride ?? createBrokerSessionLifecycleService(agentDir);
 		return await lifecycle.lookup({
 			actor: SDK_SESSION_CLI_LIFECYCLE_ACTOR,
 			capability: "session.lookup",
@@ -1847,10 +2319,17 @@ async function runRawGlobal(
 		throw new SdkSessionCliError("unknown_operation", `Unknown global operation: ${operation}`, 1);
 	if (!args.idempotencyKey)
 		throw new SdkSessionCliError("invalid_input", "--idempotency-key is required for lifecycle operations.", 2);
-	const lifecycle = createBrokerSessionLifecycleService(agentDir);
+	const lifecycle = lifecycleOverride ?? createBrokerSessionLifecycleService(agentDir);
 	const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
 	const response = await lifecycle.execute(lifecycleMutationRequest(operation, input, args.idempotencyKey, timeoutMs));
-	throwResponseFailure(response);
+	try {
+		if (!response.ok) throw lifecyclePublicFailure(response);
+	} catch (error) {
+		throw normalizeSessionFailure(error, {
+			...args,
+			sessionId: typeof input.sessionId === "string" ? input.sessionId : args.sessionId,
+		});
+	}
 	return response;
 }
 
@@ -1869,6 +2348,7 @@ export async function runSdkSessionCli(
 	setExitCode: (exitCode: 1 | 2) => void = exitCode => {
 		process.exitCode = exitCode;
 	},
+	deps: SdkSessionCliDependencies = {},
 ): Promise<void> {
 	try {
 		const action = args.action;
@@ -1879,6 +2359,7 @@ export async function runSdkSessionCli(
 			action !== "send" &&
 			action !== "status" &&
 			action !== "tail" &&
+			action !== "close" &&
 			action !== "retire" &&
 			action !== "raw" &&
 			action !== "control" &&
@@ -1887,7 +2368,7 @@ export async function runSdkSessionCli(
 		)
 			throw new SdkSessionCliError(
 				"usage",
-				"Expected one of: list, inspect, send, status, tail, retire, raw (control|query|global).",
+				"Expected one of: list, inspect, send, status, tail, close, retire, raw (control|query|global).",
 				2,
 			);
 		const agentDir = path.resolve(args.agentDir ?? getAgentDir());
@@ -1898,7 +2379,6 @@ export async function runSdkSessionCli(
 		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") {
@@ -1930,6 +2410,57 @@ export async function runSdkSessionCli(
 			);
 			return;
 		}
+		if (action === "close") {
+			const sessionId = requireValue(args.sessionId, "<sessionId>");
+			const input = await inputFromArgs(args);
+			if (input.sessionId !== undefined && input.sessionId !== sessionId)
+				throw new SdkSessionCliError("invalid_input", "Close sessionId does not match the selected session.", 2);
+			const secretError = validateAdapterSecretFields("session.close", input);
+			if (secretError) throw new SdkSessionCliError(secretError.code, secretError.message, 2);
+			const lifecycle = deps.lifecycleService ?? createBrokerSessionLifecycleService(agentDir);
+			const hasExplicitAuthority =
+				Object.hasOwn(input, "endpointGeneration") || Object.hasOwn(input, "endpointIncarnation");
+			const authority = hasExplicitAuthority
+				? typeof input.endpointGeneration === "number" &&
+					Number.isSafeInteger(input.endpointGeneration) &&
+					input.endpointGeneration > 0 &&
+					typeof input.endpointIncarnation === "string" &&
+					/^[a-f0-9]{64}$/u.test(input.endpointIncarnation)
+					? { endpointGeneration: input.endpointGeneration, endpointIncarnation: input.endpointIncarnation }
+					: undefined
+				: await resolveCloseAuthority(lifecycle, sessionId);
+			if (hasExplicitAuthority && authority === undefined)
+				throw new SdkSessionCliError(
+					"invalid_input",
+					"endpointGeneration and endpointIncarnation must identify a valid endpoint authority.",
+					2,
+				);
+			const target = { ...input, sessionId, ...(authority ?? {}) };
+			const requestKey = args.idempotencyKey ?? sessionCloseRequestKey(sessionId, authority!);
+			// Closing never attaches: a Router attachment registers this process as a
+			// live client and renews the host's abandonment window, which is the
+			// opposite of what a close is for. The Broker answers the lifecycle
+			// mutation over its own client.
+			//
+			// The default request key is scoped to the current endpoint generation and
+			// incarnation. A retry for one live host replays, while a resumed host with
+			// the same session id receives a fresh lifecycle identity.
+			writeOutput(
+				stripSecretFields(
+					await runRawGlobal(
+						agentDir,
+						"session.close",
+						target,
+						{
+							...args,
+							idempotencyKey: requestKey,
+						},
+						lifecycle,
+					),
+				),
+			);
+			return;
+		}
 		if (action === "retire") {
 			const sessionId = requireValue(args.sessionId, "<sessionId>");
 			const input = await inputFromArgs(args);
@@ -1953,19 +2484,11 @@ export async function runSdkSessionCli(
 		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,
-			);
+			throw sdkPublicFailure("adapter_operation_prohibited", undefined, "pre-effect");
 		const dispositionError = cliOperationError(kind, operation);
-		if (dispositionError) throw new SdkSessionCliError(dispositionError.code, dispositionError.message, 1);
+		if (dispositionError) throw sdkPublicFailure(dispositionError.code, undefined, "pre-effect");
 		if (isEndpointOperation(operation))
-			throw new SdkSessionCliError(
-				"endpoint_credential_forbidden",
-				"session.get_endpoint is not available through the SDK session CLI.",
-				1,
-			);
+			throw sdkPublicFailure("endpoint_credential_forbidden", undefined, "pre-effect");
 		const input = await inputFromArgs(args);
 		const secretError = validateAdapterSecretFields(operation, input);
 		if (secretError) throw new SdkSessionCliError(secretError.code, secretError.message, 2);
@@ -1984,26 +2507,6 @@ export async function runSdkSessionCli(
 			),
 		);
 	} catch (error) {
-		const cliError =
-			error instanceof SdkSessionCliError
-				? error
-				: error instanceof SessionRouterError
-					? new SdkSessionCliError(error.phase, error.message, 1)
-					: error instanceof SdkClientError
-						? new SdkSessionCliError(error.code, error.message, 1, error.details)
-						: new SdkSessionCliError(
-								"operation_failed",
-								error instanceof Error ? error.message : "SDK operation failed.",
-								1,
-							);
-		writeOutput({
-			ok: false,
-			error: {
-				code: cliError.code,
-				message: cliError.message,
-				...(cliError.details === undefined ? {} : { details: stripSecretFields(cliError.details) }),
-			},
-		});
-		setExitCode(cliError.exitCode);
+		throw normalizeSessionFailure(error, args);
 	}
 }