@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/sdk/bus/telegram-daemon.ts

@@ -26,6 +26,7 @@ import {
 	parseToolActivityToggleCommand,
 } from "./config-commands";
 import { agentDirDigest, daemonPaths, HEARTBEAT_TTL_MS } from "./daemon-paths";
+import { type DoctorDaemonOccupancy, doctorDaemonOccupancySettled } from "./doctor-daemon-restart";
 import {
 	acquireDaemonTransitionLock,
 	type DaemonTransitionLock,
@@ -160,6 +161,33 @@ export type EnsureTelegramDaemonDetailedResult = "spawned" | "reloaded" | "attac
 
 export type TelegramDaemonOwnershipPhase = "provisional" | "ready" | "retired";
 
+/** Closed vocabulary for the durable reason an owner stopped serving. */
+export type TelegramDaemonStopCause =
+	| "stop"
+	| "reload"
+	| "signal"
+	| "idle_timeout"
+	| "ownership_loss"
+	| "startup_failed"
+	| "unexpected_exception"
+	| "postmortem";
+
+export function isTelegramDaemonStopCause(value: unknown): value is TelegramDaemonStopCause {
+	switch (value) {
+		case "stop":
+		case "reload":
+		case "signal":
+		case "idle_timeout":
+		case "ownership_loss":
+		case "startup_failed":
+		case "unexpected_exception":
+		case "postmortem":
+			return true;
+		default:
+			return false;
+	}
+}
+
 export interface DaemonState {
 	pid: number;
 	/** OS process-start provenance; mandatory for PID-authorized ownership actions. */
@@ -189,6 +217,8 @@ export interface DaemonState {
 	/** Lifecycle-serving compatibility epoch; absent pre-epoch records are epoch 1. */
 	servingEpoch?: number;
 	stoppedAt?: number;
+	/** Bounded, secret-free explanation for a stopped owner; absent on legacy/unknown records. */
+	stopCause?: TelegramDaemonStopCause;
 }
 interface ExactFileStat {
 	dev: bigint;
@@ -1640,6 +1670,7 @@ export function hasSafeDaemonStateShape(state: unknown): state is DaemonState {
 			(candidate.generation === undefined ||
 				(Number.isSafeInteger(candidate.generation) && (candidate.generation as number) > 0)) &&
 			(candidate.stoppedAt === undefined || Number.isSafeInteger(candidate.stoppedAt)) &&
+			(candidate.stopCause === undefined || isTelegramDaemonStopCause(candidate.stopCause)) &&
 			(candidate.servingEpoch === undefined ||
 				(Number.isSafeInteger(candidate.servingEpoch) && (candidate.servingEpoch as number) > 0)),
 	);
@@ -2471,6 +2502,7 @@ export async function renewDaemonHeartbeat(input: {
 				...boundState,
 				ownershipPhase: "retired",
 				stoppedAt: (input.now ?? Date.now)(),
+				stopCause: boundState.stopCause ?? "startup_failed",
 			}).catch(() => undefined);
 			if (await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))
 				await unlinkOwnershipLockExactly(fsImpl, paths.lock, lock);
@@ -2609,10 +2641,14 @@ export async function retireProvisionalDaemonOwnership(input: {
 		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))) return false;
 		const lock = await readOwnershipLock(fsImpl, paths.lock);
 		if (!ownershipLockMatchesState(lock, state)) return false;
+		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))) return false;
+		const stoppedAt = state.stoppedAt ?? (input.now ?? Date.now)();
+		const stopCause = state.stopCause ?? (state.stoppedAt === undefined ? "startup_failed" : undefined);
 		await writeJsonAtomic(fsImpl, paths.state, {
 			...state,
 			ownershipPhase: "retired",
-			stoppedAt: (input.now ?? Date.now)(),
+			stoppedAt,
+			...(stopCause === undefined ? {} : { stopCause }),
 		});
 		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))) return false;
 		return await unlinkOwnershipLockExactly(fsImpl, paths.lock, lock);
@@ -2859,6 +2895,7 @@ export async function releaseDaemonOwnership(input: {
 	pidIncarnation?: (pid: number) => string | undefined;
 	fs?: TelegramDaemonFs;
 	now?: () => number;
+	stopCause?: TelegramDaemonStopCause;
 }): Promise<void> {
 	const fsImpl = input.fs ?? nodeFs;
 	const paths = daemonPaths(input.settings.getAgentDir());
@@ -2890,7 +2927,15 @@ export async function releaseDaemonOwnership(input: {
 		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))) return;
 		const lock = await readOwnershipLock(fsImpl, paths.lock);
 		if (!ownershipLockMatchesState(lock, state)) return;
-		await writeJsonAtomic(fsImpl, paths.state, { ...state, stoppedAt: (input.now ?? Date.now)() });
+		const stoppedAt = state.stoppedAt ?? (input.now ?? Date.now)();
+		const stopCause =
+			state.stopCause ??
+			(state.stoppedAt === undefined && isTelegramDaemonStopCause(input.stopCause) ? input.stopCause : undefined);
+		await writeJsonAtomic(fsImpl, paths.state, {
+			...state,
+			stoppedAt,
+			...(stopCause === undefined ? {} : { stopCause }),
+		});
 		try {
 			const { removeTelegramOwnerMarker } = await import("./telegram-daemon-owner-registry");
 			await removeTelegramOwnerMarker(fsImpl, input.settings.getAgentDir(), state.acquisitionId ?? state.ownerId);
@@ -2912,9 +2957,9 @@ export async function releaseDaemonOwnership(input: {
  * `ownershipPhase: "ready"` and a fresh-looking lock behind forever, so later
  * readers attached to an owner that had not existed for hours.
  *
- * This writes `stoppedAt` and nothing else. The lock is left in place for the
- * existing reclaim path to adjudicate, because a process on its way out is the
- * least qualified party to decide who owns what next.
+ * This writes `stoppedAt` and a closed-vocabulary `stopCause`. The lock is left
+ * in place for the existing reclaim path to adjudicate, because a process on
+ * its way out is the least qualified party to decide who owns what next.
  *
  * Fenced on full owner identity: if the state no longer names this exact
  * owner, acquisition, pid and incarnation, a successor already took over and
@@ -2950,7 +2995,12 @@ export async function markDaemonOwnerStopped(input: {
 			return false;
 		const lock = await readOwnershipLock(fsImpl, paths.lock);
 		if (!ownershipLockMatchesState(lock, state)) return false;
-		await writeJsonAtomic(fsImpl, paths.state, { ...state, stoppedAt: (input.now ?? Date.now)() });
+		const stopCause = state.stopCause ?? "postmortem";
+		await writeJsonAtomic(fsImpl, paths.state, {
+			...state,
+			stoppedAt: (input.now ?? Date.now)(),
+			stopCause,
+		});
 		try {
 			const { removeTelegramOwnerMarker } = await import("./telegram-daemon-owner-registry");
 			await removeTelegramOwnerMarker(fsImpl, input.settings.getAgentDir(), state.acquisitionId ?? state.ownerId);
@@ -3992,6 +4042,12 @@ export class TelegramEventDispatchState {
 export interface DaemonControlHooks {
 	/** Returns true when a stop/reload has been requested for this owner. */
 	shouldStop(ownerId: string): Promise<boolean>;
+	/**
+	 * Returns the owner-fenced action behind `shouldStop`, when the control
+	 * plane can provide one. This is a diagnostic projection, not an alternate
+	 * stop authority: callers must still gate it behind `shouldStop`.
+	 */
+	requestedAction?(ownerId: string): Promise<"reload" | "stop" | undefined>;
 	/** Clear a consumed control request (best-effort). */
 	clear?(ownerId: string): Promise<void>;
 }
@@ -4405,10 +4461,18 @@ class TelegramEffectSupervisor {
 		return this.#stopping;
 	}
 
+	get admitting(): boolean {
+		return this.#admitting;
+	}
+
 	closeAdmission(): void {
 		this.#admitting = false;
 	}
 
+	openAdmission(): void {
+		if (!this.#stopping) this.#admitting = true;
+	}
+
 	beginShutdown(): void {
 		this.closeAdmission();
 		this.#stopping = true;
@@ -4496,6 +4560,10 @@ export class TelegramNotificationDaemon {
 	private running = false;
 	/** Once set, a concurrent startup await can never restore a running daemon. */
 	private stopRequested = false;
+	/** First observed stop cause wins, including an explicit stop. */
+	#stopCause: TelegramDaemonStopCause | undefined;
+	/** Signal cause resolution is asynchronous because control requests are file-backed. */
+	#stopCauseResolution: Promise<void> | undefined;
 
 	private readonly fsImpl: TelegramDaemonFs;
 	readonly #deliveryAbort = new AbortController();
@@ -4652,12 +4720,47 @@ export class TelegramNotificationDaemon {
 		}
 	}
 
+	#resolveControlStopCause(fallback: "signal" | "stop"): void {
+		if (this.#stopCause !== undefined || this.#stopCauseResolution !== undefined) return;
+		const requestedAction = this.opts.control?.requestedAction;
+		if (!requestedAction) {
+			this.#stopCause = fallback;
+			return;
+		}
+		// Diagnostics must never hold ownership cleanup behind a stalled file read.
+		const deadline = Promise.withResolvers<void>();
+		const timer = setTimeout(() => {
+			this.#stopCause ??= fallback;
+			deadline.resolve();
+		}, 250);
+		const lookup = Promise.resolve()
+			.then(() => requestedAction.call(this.opts.control, this.opts.ownerId))
+			.then(
+				action => {
+					this.#stopCause ??= action === "reload" || action === "stop" ? action : fallback;
+				},
+				() => {
+					this.#stopCause ??= fallback;
+				},
+			);
+		this.#stopCauseResolution = Promise.race([lookup, deadline.promise]).finally(() => clearTimeout(timer));
+	}
+
 	/**
 	 * Cooperatively stop the daemon: set the stop flag and abort the in-flight
 	 * long poll so the run loop wakes immediately instead of waiting out the
-	 * ~25s getUpdates timeout. Safe to call from a signal handler.
+	 * ~25s getUpdates timeout. Safe to call from a signal handler. The
+	 * no-argument form is the generic finally fallback and never overwrites a
+	 * previously observed specific cause.
 	 */
-	requestStop(_reason?: "reload" | "stop" | "signal"): void {
+	requestStop(reason?: TelegramDaemonStopCause): void {
+		if (reason === "signal") {
+			this.#resolveControlStopCause("signal");
+		} else if (reason !== undefined && this.#stopCauseResolution === undefined) {
+			this.#stopCause ??= reason;
+		} else if (this.#stopCauseResolution === undefined) {
+			this.#stopCause ??= "stop";
+		}
 		this.stopRequested = true;
 		this.effects.closeAdmission();
 		this.#deliveryAbort.abort();
@@ -4705,6 +4808,45 @@ export class TelegramNotificationDaemon {
 		this.running = false;
 	}
 
+	/** Doctor reservation hook: stop admitting new provider work without killing the owner. Synchronous fence; returns a real acknowledgement. */
+	prepareDoctorRestart(): boolean {
+		this.effects.closeAdmission();
+		return !this.effects.admitting;
+	}
+
+	/**
+	 * Real occupancy read from the live runtime structures the daemon actually
+	 * uses, not synthetic zeros. `inflight` is turns currently executing;
+	 * `inbound` is inbound work accepted but not yet resolved (pending /btw
+	 * turns, topic-adoption session_create dispatches in flight, and inbound
+	 * reaction acks not yet terminal); `outbound` is the real rate-limit pool
+	 * backlog plus terminal /btw deliveries still in flight; `cleanup` counts
+	 * only genuinely outstanding cleanup — non-completed cleanup receipts plus
+	 * live archive/compensation fences — never a completed receipt or an
+	 * unrelated rejected-topic notice timer.
+	 */
+	doctorOccupancy(): DoctorDaemonOccupancy {
+		const outstandingCleanupReceipts = [...this.#cleanupReceipts.values()].filter(
+			receipt => receipt.state !== "completed",
+		).length;
+		return {
+			attached: this.sessions.size,
+			inflight: this.busy.size,
+			inbound:
+				this.#pendingBtwTurns.size + this.#adoptionStartingTopics.size + this.dispatchState.inboundReactions.size,
+			outbound: this.pool.pending + this.#btwTerminalDeliveries.size,
+			cleanup: outstandingCleanupReceipts + this.archiveFlights.size + this.compensationFenceRetries.size,
+		};
+	}
+
+	doctorRestartReady(): boolean {
+		return doctorDaemonOccupancySettled(this.doctorOccupancy());
+	}
+
+	cancelDoctorRestart(): void {
+		if (!this.stopRequested) this.effects.openAdmission();
+	}
+
 	#lifecycleActor(): SessionLifecycleActor {
 		return { id: String(this.opts.chatId), namespace: `telegram:${tokenFingerprint(this.opts.botToken)}` };
 	}
@@ -8884,7 +9026,7 @@ export class TelegramNotificationDaemon {
 		);
 	}
 	private submitPool(item: Parameters<RateLimitPool<TelegramQueuePayload>["submit"]>[0]): boolean {
-		if (this.stopRequested || this.effects.stopping) return false;
+		if (this.stopRequested || this.effects.stopping || !this.effects.admitting) return false;
 		this.pool.submit(item);
 		return true;
 	}
@@ -9832,7 +9974,7 @@ export class TelegramNotificationDaemon {
 					// and the next interval republishes (#4200). Only a proven
 					// ownership loss stops the owner.
 					if ((await this.renewOwnershipHeartbeat()) === "not_owner") {
-						this.runtime.requestStop();
+						this.requestStop("ownership_loss");
 						return;
 					}
 					await this.renewActiveTopicLeases();
@@ -11949,6 +12091,16 @@ export class TelegramNotificationDaemon {
 		if (this.validationMode() || !this.#topicRegistryMutationAllowed()) return;
 		if ((await this.handleForumTopicCreatedUpdate(update)) !== "not-topic") return;
 		if ((await this.handleForumTopicEdited(update)) !== "not-topic") return;
+		// Doctor admission fence: forum-topic bookkeeping above is structural
+		// registry housekeeping for topics that already exist, not new user-facing
+		// work, so it stays live. Everything below this line admits genuinely NEW
+		// inbound work — adoption/session_create, /session_* lifecycle commands,
+		// /btw turns, model-picker taps, and inline session control dispatch — and
+		// MUST be refused while the owner has closed admission for a doctor
+		// restart. Already-active turns and the outbound queue are untouched here:
+		// they drain through their own existing paths (RateLimitPool.drain,
+		// in-flight session turns), never invalidated by this refusal.
+		if (!this.effects.admitting) return;
 		// A raw path is accepted only after the explicit direct-entry choice. The exact
 		// `/session_create path <dir>` form remains available in any pending topic.
 		// Both must precede the general lifecycle handler, which would otherwise create
@@ -12803,7 +12955,10 @@ export class TelegramNotificationDaemon {
 						`notifications: ownership heartbeat renewal threw; continuing: ${sanitizeDiagnostic(String(error))}`,
 					);
 				}
-				if (!ownerHeld) break;
+				if (!ownerHeld) {
+					this.requestStop("ownership_loss");
+					break;
+				}
 				if (await this.controlStopRequested()) break;
 				const idleElapsed = this.runtime.now() - idleSince >= (this.opts.idleTimeoutMs ?? 60_000);
 				if (this.sessions.size > 0) {
@@ -12811,6 +12966,7 @@ export class TelegramNotificationDaemon {
 				} else if (idleElapsed) {
 					// Zero sessions past the idle window: exit so the owner does not run
 					// forever. An active session resets the idle window above.
+					this.requestStop("idle_timeout");
 					break;
 				}
 				// Poll getUpdates whenever the daemon owns the token — even with zero
@@ -12836,8 +12992,12 @@ export class TelegramNotificationDaemon {
 				if (await this.controlStopRequested()) break;
 				await this.runtime.sleep(10);
 			}
+		} catch (error) {
+			this.requestStop("unexpected_exception");
+			throw error;
 		} finally {
-			this.requestStop("stop");
+			this.requestStop();
+			await this.#stopCauseResolution;
 			this.running = false;
 			await this.#attachmentRouter
 				.stop()
@@ -12911,6 +13071,7 @@ export class TelegramNotificationDaemon {
 						pidIncarnation: this.opts.pidIncarnation,
 						fs: this.fsImpl,
 						now: this.opts.now,
+						stopCause: this.#stopCause,
 					});
 				}
 			}
@@ -12922,7 +13083,11 @@ export class TelegramNotificationDaemon {
 		if (this.runtime.stopRequested) return true;
 		if (!this.opts.control) return false;
 		try {
-			return await this.opts.control.shouldStop(this.opts.ownerId);
+			const requested = await this.opts.control.shouldStop(this.opts.ownerId);
+			if (!requested) return false;
+			this.#resolveControlStopCause("stop");
+			this.requestStop();
+			return true;
 		} catch {
 			return false;
 		}

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

@@ -86,6 +86,7 @@ export interface SdkSessionCliArgs {
 	strict?: boolean;
 	untilIdle?: boolean;
 	allEvents?: boolean;
+	page?: boolean;
 	repo?: string;
 	scope?: string;
 	limit?: number;
@@ -95,7 +96,7 @@ export interface SdkSessionCliArgs {
 }
 
 type JsonRecord = Record<string, unknown>;
-type LifecycleMutationOperation = Exclude<SessionLifecycleOperation, "session.list">;
+type LifecycleMutationOperation = Exclude<SessionLifecycleOperation, "session.lookup" | "session.list">;
 type TailExitReason = "idle" | "close";
 export interface RetainedTranscriptTailReader {
 	readonly size: number;
@@ -278,15 +279,27 @@ function reportRouterCleanupFailure(error: unknown): void {
 	process.stderr.write(`SDK session Router cleanup failed: ${message}\n`);
 }
 
+/**
+ * Sessions a CLI-opened Router is allowed to attach to. Required, and required
+ * to be exhaustive: attaching is not free and is not invisible, because every
+ * attachment registers this process as a live client on that host and renews
+ * the host's abandonment window. An omitted scope used to mean "the whole
+ * fleet", so a single-session command silently kept every unrelated host alive.
+ *
+ * `BROKER_ONLY` is the empty scope, for work the Broker answers over its own
+ * client (`session.list`) and which therefore needs no session transport at all.
+ */
+const BROKER_ONLY: readonly string[] = [];
+
 async function withRouter<T>(
 	agentDir: string,
+	sessionIds: readonly 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 }),
+		sessionIds,
 		...(onFrame === undefined ? {} : { deps: { onFrame } }),
 	});
 	let result!: T;
@@ -370,6 +383,36 @@ async function paginatedSessionList(
 	}
 }
 
+async function singleSessionListPage(
+	router: SessionRouter,
+	input: JsonRecord = {},
+	requestKey = `${SDK_SESSION_CLI_LIFECYCLE_ACTOR.namespace}:session.list:${randomBytes(12).toString("hex")}`,
+): Promise<unknown> {
+	try {
+		const cursor = typeof input.cursor === "string" ? input.cursor : "initial";
+		const response = object(await router.listBrokerSessions(input, `${requestKey}:${cursor}`));
+		if (response?.ok === false) {
+			const failure = object(response.error);
+			throw new SdkClientError(
+				typeof failure?.code === "string" ? failure.code : "broker_error",
+				typeof failure?.message === "string" ? failure.message : "session.list failed",
+			);
+		}
+		const page = sessionListPageFromResponse(response);
+		const continuationCursor = page?.continuationCursor;
+		if (
+			!page ||
+			(continuationCursor !== undefined &&
+				(typeof continuationCursor !== "string" || continuationCursor.length === 0))
+		)
+			throw new SessionListTraversalError("malformed_page");
+		return response;
+	} catch (error) {
+		if (error instanceof SessionListTraversalError) throw new SdkClientError("protocol_error", error.message);
+		throw error;
+	}
+}
+
 type SessionRows = {
 	indexSeq?: number;
 	warnings: unknown[];
@@ -378,7 +421,12 @@ type SessionRows = {
 
 async function sessionRows(agentDir: string, input: JsonRecord = {}): Promise<SessionRows> {
 	await ensureBroker({ agentDir });
-	return await withRouter(agentDir, async router => {
+	// `session.list` is answered by the Broker over its own client, so resolving a
+	// row needs no session transport. `runInspect` and `runTail` resolve exactly
+	// one session through here, and an unscoped lookup attached every live
+	// session in the directory before the scoped operation that follows it ever
+	// ran — renewing the abandonment window of hosts the caller never named.
+	return await withRouter(agentDir, BROKER_ONLY, async router => {
 		const response = await paginatedSessionList(router, input);
 		const result = resultObject(response) ?? {};
 		let sessions: SdkSessionRowV1[];
@@ -433,9 +481,8 @@ async function probeSearchRows(agentDir: string, result: SdkSearchResultV1): Pro
 	try {
 		const probes = await withRouter(
 			agentDir,
-			async router => await Promise.all(rows.map(row => searchProbe(row, router))),
-			undefined,
 			rows.map(row => row.id),
+			async router => await Promise.all(rows.map(row => searchProbe(row, router))),
 		);
 		return { ...result, rows: mergeProbedSearchRows(result.rows, probes) };
 	} catch {
@@ -913,7 +960,7 @@ async function runSend(agentDir: string, sessionId: string, args: SdkSessionCliA
 	if (invalid) throw new SdkSessionCliError(invalid.code, invalid.message, 2);
 	await ensureBroker({ agentDir });
 
-	return await withRouter(agentDir, async router => {
+	return await withRouter(agentDir, [sessionId], async router => {
 		const response = await requestControl(router, sessionId, "turn.prompt", promptInput, args);
 		const result: JsonRecord = {
 			version: SESSION_ROWS_VERSION,
@@ -945,7 +992,7 @@ async function runStatus(
 ): Promise<unknown> {
 	assertClientRef(opRef);
 	await ensureBroker({ agentDir });
-	return await withRouter(agentDir, async router => {
+	return await withRouter(agentDir, [sessionId], async router => {
 		const response = await requestQuery(router, sessionId, "turn.result", { kind: "prompt", clientRef: opRef }, args);
 		const status = resultObject(response) ?? {};
 		const raw = typeof status.status === "string" ? status.status : "unknown";
@@ -1508,6 +1555,7 @@ async function runLiveTail(
 
 	return await withRouter(
 		agentDir,
+		[sessionId],
 		async router => {
 			const attachment = attachmentFor(router, sessionId);
 			const checkpointResponse = await router.request(
@@ -1695,7 +1743,11 @@ async function runRawControl(
 	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));
+	return await withRouter(
+		agentDir,
+		[sessionId],
+		async router => await requestControl(router, sessionId, operation, input, args),
+	);
 }
 
 async function runRawQuery(
@@ -1706,7 +1758,11 @@ async function runRawQuery(
 	args: SdkSessionCliArgs,
 ): Promise<unknown> {
 	await ensureBroker({ agentDir });
-	return await withRouter(agentDir, async router => await requestQuery(router, sessionId, operation, input, args));
+	return await withRouter(
+		agentDir,
+		[sessionId],
+		async router => await requestQuery(router, sessionId, operation, input, args),
+	);
 }
 
 function lifecycleMutationRequest(
@@ -1753,9 +1809,39 @@ async function runRawGlobal(
 	input: JsonRecord,
 	args: SdkSessionCliArgs,
 ): Promise<unknown> {
+	if (args.page && operation !== "session.list")
+		throw new SdkSessionCliError("usage", "--page is only available for raw global session.list.", 2);
 	if (operation === "session.list") {
 		await ensureBroker({ agentDir });
-		return await withRouter(agentDir, async router => await paginatedSessionList(router, input));
+		const pageInput = { ...input };
+		if (args.cursor !== undefined) {
+			if (pageInput.cursor !== undefined && pageInput.cursor !== args.cursor)
+				throw new SdkSessionCliError("usage", "--cursor must match the cursor in --json-input.", 2);
+			pageInput.cursor = args.cursor;
+		}
+		if (args.limit !== undefined) {
+			if (pageInput.limit !== undefined && pageInput.limit !== args.limit)
+				throw new SdkSessionCliError("usage", "--limit must match the limit in --json-input.", 2);
+			pageInput.limit = args.limit;
+		}
+		return await withRouter(
+			agentDir,
+			BROKER_ONLY,
+			async router =>
+				await (args.page ? singleSessionListPage(router, pageInput) : paginatedSessionList(router, pageInput)),
+		);
+	}
+	if (operation === "session.lookup") {
+		if (!args.idempotencyKey)
+			throw new SdkSessionCliError("invalid_input", "--idempotency-key is required for session lookup.", 2);
+		const lifecycle = createBrokerSessionLifecycleService(agentDir);
+		return await lifecycle.lookup({
+			actor: SDK_SESSION_CLI_LIFECYCLE_ACTOR,
+			capability: "session.lookup",
+			operation: "session.create",
+			requestKey: args.idempotencyKey,
+			target: input,
+		});
 	}
 	if (!isLifecycleOperation(operation))
 		throw new SdkSessionCliError("unknown_operation", `Unknown global operation: ${operation}`, 1);
@@ -1884,7 +1970,9 @@ export async function runSdkSessionCli(
 		const secretError = validateAdapterSecretFields(operation, input);
 		if (secretError) throw new SdkSessionCliError(secretError.code, secretError.message, 2);
 		if (kind === "global") {
-			writeOutput(stripSecretFields(await runRawGlobal(agentDir, operation, input, args)));
+			const result = await runRawGlobal(agentDir, operation, input, args);
+			writeOutput(stripSecretFields(result));
+			if (isRecord(result) && result.ok === false) setExitCode(1);
 			return;
 		}
 		const sessionId = requireValue(args.sessionId, "<sessionId>");

package/src/sdk/host/host.ts

@@ -1,6 +1,6 @@
 import { logger } from "@gajae-code/utils";
 import { AUTOROUTING_INACTIVE_WARNING } from "../../config/autorouting-contract";
-import { FileLockAcquireError } from "../../config/file-lock";
+import { isFileLockAcquireTimeout } from "../../config/file-lock";
 import { redactBrokerRuntimeCapabilities, redactObservedRequestContent } from "./control/runtime-gate";
 import { type EventFrame, SessionEventStream } from "./events";
 import { isAutoroutingInactive } from "./internal-autorouting-state";
@@ -395,12 +395,7 @@ export class SessionSdkHost {
 				// the durable row in place is fail-closed because peers still fence
 				// authority on process liveness and incarnation, while propagating the
 				// contention error turns ordinary shutdown into an uncaught failure.
-				if (
-					!options.allowLockContention ||
-					!(error instanceof FileLockAcquireError) ||
-					error.code !== "acquire_timeout"
-				)
-					throw error;
+				if (!options.allowLockContention || !isFileLockAcquireTimeout(error)) throw error;
 				logger.warn("sdk broker unregister deferred because the session index is busy", {
 					holder: error.holder,
 					lockPath: error.lockPath,