@gajae-code/coding-agent 0.12.18 → 0.12.20

package/src/sdk/bus/topic-registry.ts

@@ -578,7 +578,10 @@ export class TopicRegistry {
 					: {}),
 				...(isValidBindingString(raw.archiveHostId) ? { archiveHostId: raw.archiveHostId } : {}),
 				...(isValidBindingGeneration(raw.archiveLeaseEpoch) ? { archiveLeaseEpoch: raw.archiveLeaseEpoch } : {}),
-				...(typeof raw.disconnectGraceExpiresAt === "number" && Number.isFinite(raw.disconnectGraceExpiresAt)
+				...(raw.authorityState === "disconnect_grace" &&
+				!fenceSupersedesRecord &&
+				typeof raw.disconnectGraceExpiresAt === "number" &&
+				Number.isFinite(raw.disconnectGraceExpiresAt)
 					? { disconnectGraceExpiresAt: raw.disconnectGraceExpiresAt }
 					: {}),
 				...(bindingMalformed ? { bindingMalformed: true as const } : {}),
@@ -1179,6 +1182,9 @@ export class TopicRegistry {
 		} else {
 			record.authorityEpoch = snapshot.authorityEpoch;
 			record.authorityState = snapshot.authorityState;
+			if (snapshot.authorityState === "disconnect_grace" && snapshot.record?.disconnectGraceExpiresAt !== undefined)
+				record.disconnectGraceExpiresAt = snapshot.record.disconnectGraceExpiresAt;
+			else delete record.disconnectGraceExpiresAt;
 			this.rebuildInboundRoutes();
 		}
 		if (snapshot.fenceEpoch === undefined) this.epochs.delete(snapshot.sessionId);

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

@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { getAgentDir } from "@gajae-code/utils";
 import { ensureBroker } from "../broker/ensure";
+import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
 import {
 	listSdkSessionEndpoints,
 	readSdkBrokerDiscovery,
@@ -242,7 +243,13 @@ export async function runSdkSessionCli(
 				throw new SdkSessionCliError("invalid_input", "--idempotency-key is required for lifecycle operations.", 2);
 			const client = await connectBroker(agentDir);
 			try {
-				writeOutput(await client.global(operation, input, { idempotencyKey }));
+				const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
+				writeOutput(
+					await client.global(operation, input, {
+						idempotencyKey,
+						...(timeoutMs === undefined ? {} : { timeoutMs }),
+					}),
+				);
 			} finally {
 				await client.close();
 			}

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

@@ -405,7 +405,7 @@ export class QueryHandlers {
 		const range =
 			itemId === undefined
 				? await this.revisions.readStringRange(kind, id, revision, field, offset, TARGET_PAGE_BYTES)
-				: await this.revisions.readIndexedStringRange(kind, id, revision, itemId, field, offset, TARGET_PAGE_BYTES);
+				: await this.revisions.readIndexedFieldRange(kind, id, revision, itemId, field, offset, TARGET_PAGE_BYTES);
 		if (!range) return this.#error(request, "resource_gone");
 		return this.#chunkRange(request, kind, id, revision, range, selector, {
 			field,

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

@@ -312,8 +312,7 @@ export class RevisionStore {
 	readonly #onReadRange?: (start: number, end: number) => void;
 	#closing = false;
 	#closePromise: Promise<void> | undefined;
-	#writesInFlight = 0;
-	#writesDrained: PromiseWithResolvers<void> | undefined;
+	readonly #pendingWrites = new Set<Promise<void>>();
 
 	constructor(
 		readonly sessionId: string,
@@ -326,10 +325,11 @@ export class RevisionStore {
 
 	createRevision(resourceKind: string, resourceId: string, payload: unknown): Promise<string> {
 		if (this.#closing) return Promise.reject(new RevisionStoreError("resource_gone", "snapshot store is closing"));
-		this.#writesInFlight++;
+		const settled = Promise.withResolvers<void>();
+		this.#pendingWrites.add(settled.promise);
 		return this.#createRevision(resourceKind, resourceId, payload).finally(() => {
-			this.#writesInFlight--;
-			if (this.#writesInFlight === 0) this.#writesDrained?.resolve();
+			this.#pendingWrites.delete(settled.promise);
+			settled.resolve();
 		});
 	}
 
@@ -468,6 +468,25 @@ export class RevisionStore {
 		const range = item?.fields?.[field];
 		return range ? this.#readStringRange(revision, range, offset, length) : undefined;
 	}
+	async readIndexedFieldRange(
+		resourceKind: string,
+		resourceId: string,
+		id: string,
+		itemId: string,
+		field: string,
+		offset: number,
+		length: number,
+	): Promise<{ body: string; complete: boolean; offset: number } | undefined> {
+		const revision = this.#resources.get(`${resourceKind}:${resourceId}`)?.find(item => item.id === id);
+		if (!revision) return undefined;
+		revision.lastAccessed = this.now();
+		const item = revision.index?.items?.find(candidate => candidate.entryId === itemId);
+		const range = item?.fields?.[field];
+		if (!range) return undefined;
+		return range.isString
+			? this.#readStringRange(revision, range, offset, length)
+			: this.#readJsonRange(revision, range, offset, length);
+	}
 	async describeIndexedItem(
 		resourceKind: string,
 		resourceId: string,
@@ -479,9 +498,7 @@ export class RevisionStore {
 		if (!item) return undefined;
 		return {
 			itemId: item.entryId,
-			fields: Object.entries(item.fields ?? {})
-				.filter(([, range]) => range.isString)
-				.map(([field]) => field),
+			fields: Object.keys(item.fields ?? {}),
 		};
 	}
 	async readTranscriptBodyRange(
@@ -531,10 +548,7 @@ export class RevisionStore {
 		if (this.#closePromise) return this.#closePromise;
 		this.#closing = true;
 		this.#closePromise = (async () => {
-			if (this.#writesInFlight > 0) {
-				this.#writesDrained ??= Promise.withResolvers<void>();
-				await this.#writesDrained.promise;
-			}
+			await Promise.all(this.#pendingWrites);
 			this.#resources.clear();
 			this.#pinIndex.clear();
 			this.#memoryBytes = 0;
@@ -801,6 +815,28 @@ export class RevisionStore {
 		return { isString: true, stringIndex };
 	}
 
+	async #readJsonRange(
+		revision: Revision,
+		range: IndexedField,
+		offset: number,
+		length: number,
+	): Promise<{ body: string; complete: boolean; offset: number } | undefined> {
+		if (offset < 0 || length <= 0) return undefined;
+		const bytes = range.end - range.start;
+		const requestedStart = Math.min(offset, bytes);
+		const source = await this.#readBytes(
+			revision,
+			range.start + requestedStart,
+			range.start + Math.min(bytes, requestedStart + length + 7),
+		);
+		const skipped = utf8ContinuationPrefixLength(source);
+		const start = requestedStart + skipped;
+		const body = source.subarray(skipped);
+		const end = utf8BoundaryAtOrBefore(body, Math.min(body.length, length));
+		if (end === 0 && start < bytes) return undefined;
+		return { body: body.subarray(0, end).toString("utf8"), complete: start + end === bytes, offset: start };
+	}
+
 	async #readStringRange(
 		revision: Revision,
 		range: IndexedField,

package/src/sdk/host/session-runtime.test.ts

@@ -3,6 +3,7 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import {
+	createInvocationReconciliation,
 	createSdkSessionRuntimeExtension,
 	SessionSdkSessionRuntime,
 	type SessionSdkTransport,
@@ -64,6 +65,55 @@ function extensionContext(sessionId: string, cwd: string): any {
 	};
 }
 
+test("preserves an agent failure code in host prompt reconciliation", async () => {
+	const reconciliation = createInvocationReconciliation();
+	const correlation = { commandId: "failed-command", turnId: "failed-turn" };
+	await reconciliation.noteAccepted("prompt", correlation, "failed-ref");
+	await reconciliation.noteTransition("prompt", correlation, {
+		type: "agent_failed",
+		error: Object.assign(new Error("provider unavailable"), { code: "provider_unavailable" }),
+	});
+	expect(reconciliation.lookup("prompt", { clientRef: "failed-ref" })).toMatchObject({
+		status: "failed",
+		error: { code: "provider_unavailable", message: "Prompt submission failed." },
+	});
+});
+
+test("redacts a persisted host failure during hydration", async () => {
+	const stateRoot = await mkdtemp(path.join(os.tmpdir(), "gjc-sdk-reconciliation-"));
+	const sessionId = "hydrated-failure";
+	try {
+		await Bun.write(
+			path.join(stateRoot, ".sdk-reconciliation", `${sessionId}.json`),
+			JSON.stringify({
+				version: 1,
+				sessionId,
+				records: [
+					{
+						kind: "prompt",
+						commandId: "persisted-command",
+						turnId: "persisted-turn",
+						status: "failed",
+						acceptedAt: 1,
+						terminalAt: Date.now(),
+						error: { code: "unsafe code!", message: "secret provider payload" },
+					},
+				],
+			}),
+		);
+		const reconciliation = createInvocationReconciliation({ stateRoot, sessionId });
+		await reconciliation.hydrate();
+		expect(
+			reconciliation.lookup("prompt", { commandId: "persisted-command", turnId: "persisted-turn" }),
+		).toMatchObject({
+			status: "failed",
+			error: { code: "internal", message: "Prompt submission failed." },
+		});
+	} finally {
+		await rm(stateRoot, { recursive: true, force: true });
+	}
+});
+
 describe("SessionSdkSessionRuntime", () => {
 	test("has no notification adapter or native notification import edge", async () => {
 		const source = await readFile(new URL("./session-runtime.ts", import.meta.url), "utf8");

package/src/sdk/host/session-runtime.ts

@@ -22,6 +22,7 @@ import {
 	syntheticNamespaceCollision,
 } from "../model-profile-model";
 import { projectQ10Models } from "../models.js";
+import { formatPromptFailureForLocalLog, sanitizePromptFailure } from "../prompt-failure";
 import { OPERATIONS } from "../protocol/operation-registry";
 import { type ControlSurface, dispatchControl } from "./control";
 import { SessionSdkHost, type SessionSdkHostOptions } from "./host";
@@ -265,7 +266,7 @@ export interface InvocationReconciliation {
 	hydrate(): Promise<void>;
 }
 
-function createInvocationReconciliation(
+export function createInvocationReconciliation(
 	options: { stateRoot?: string; sessionId?: string } = {},
 ): InvocationReconciliation {
 	const ACTIVE_CAPACITY = 256;
@@ -361,6 +362,7 @@ function createInvocationReconciliation(
 					record.terminalAt = Date.now();
 					record.error = { code: "process_restart", message: "Reconciliation incomplete after process restart." };
 				}
+				if (record.status === "failed") record.error = sanitizePromptFailure(record.error);
 				records.set(key(record.kind, record), { ...record });
 			}
 		}
@@ -416,7 +418,15 @@ function createInvocationReconciliation(
 			} else {
 				record.status = frame.type === "agent_failed" ? "failed" : "terminal_ok";
 				record.terminalAt = Date.now();
-				if (frame.type === "agent_failed") record.error = { code: "prompt_failed", message: "Invocation failed." };
+				if (frame.type === "agent_failed") {
+					logger.error("SDK invocation failed", {
+						kind,
+						commandId: correlation.commandId,
+						turnId: correlation.turnId,
+						error: formatPromptFailureForLocalLog(frame.error),
+					});
+					record.error = sanitizePromptFailure(frame.error);
+				}
 			}
 			await persist();
 		},

package/src/sdk/lifecycle-session.ts

@@ -13,11 +13,22 @@ export type CreateLifecycleAgentSessionResult =
 			session: AgentSession;
 			capability: SdkStartupCapability;
 			rollback: SdkStartupRollbackTracker;
+			/**
+			 * Starts the memory backend that construction deliberately skipped. The
+			 * caller MUST run it only after readiness is published.
+			 */
+			startDeferredMemoryBackend: () => Promise<void>;
 	  }
 	| { capability: SdkStartupCapability; rollback: SdkStartupRollbackTracker; failure: SdkStartupFailure };
 
-/** Options accepted by lifecycle-only session construction. */
-export type CreateLifecycleAgentSessionOptions = CreateAgentSessionOptions & {
+/**
+ * Options accepted by lifecycle-only session construction.
+ *
+ * `deferMemoryBackendStartup` is not accepted: lifecycle sessions are launched
+ * by the broker under a fixed readiness deadline, and memory startup runs
+ * unbounded LLM work, so deferral is an invariant rather than a caller choice.
+ */
+export type CreateLifecycleAgentSessionOptions = Omit<CreateAgentSessionOptions, "deferMemoryBackendStartup"> & {
 	/**
 	 * Startup budget for ACP lifecycle MCP launches, in milliseconds. Set only
 	 * when the lifecycle request supplies `mcpServers`; ordinary consumers keep
@@ -42,6 +53,11 @@ export async function createLifecycleAgentSession(
 		const { mcpStartupTimeoutMs, readiness: _readiness, ...sessionOptions } = options;
 		const internalOptions = {
 			...sessionOptions,
+			// Memory startup (rollout summarisation) issues one LLM request per
+			// claimed rollout, so its duration scales with the backlog. Keeping it
+			// inside the broker's readiness window is what kills the child at the
+			// cutoff; the host resumes it once readiness is published.
+			deferMemoryBackendStartup: true,
 			[lifecycleStartupCapabilityOption]: capability,
 			...(mcpStartupTimeoutMs !== undefined ? { [lifecycleMcpStartupTimeoutOption]: mcpStartupTimeoutMs } : {}),
 		} as CreateAgentSessionOptions & {
@@ -51,7 +67,14 @@ export async function createLifecycleAgentSession(
 		const result = await createAgentSession(internalOptions);
 		if (!result.session.extensionRunner)
 			capability.settleFailure(capability.normalizeFailure("registration", "runner_absent"));
-		return { session: result.session, capability, rollback };
+		if (!result.startDeferredMemoryBackend)
+			throw new Error("Lifecycle session construction did not return a deferred memory backend starter.");
+		return {
+			session: result.session,
+			capability,
+			rollback,
+			startDeferredMemoryBackend: result.startDeferredMemoryBackend,
+		};
 	} catch (error) {
 		const settled = capability.settleFailure(capability.normalizeFailure("registration", "failed", error));
 		const failure =

package/src/sdk/mcp/server.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { getAgentDir } from "@gajae-code/utils";
 import { ensureBroker } from "../broker/ensure";
+import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
 import { SdkClient, SdkClientError } from "../client/client";
 import {
 	listSdkSessionEndpoints,
@@ -253,7 +254,11 @@ export function createSdkMcpServer(options: SdkMcpServerOptions = {}) {
 				const broker = await readSdkBrokerDiscovery(agentDir);
 				if (!broker) return { ok: false, error: { code: "not_found", message: "SDK broker not found" } };
 				client = await connect(broker.url, broker.token);
-				const response = await client.global(operation, input, { idempotencyKey });
+				const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
+				const response = await client.global(operation, input, {
+					idempotencyKey,
+					...(timeoutMs === undefined ? {} : { timeoutMs }),
+				});
 				return isLifecycleOperation(operation) ? redactLifecycleCredentials(response) : response;
 			} catch (error) {
 				return resultError(error);

package/src/sdk/prompt-failure.ts

@@ -0,0 +1,42 @@
+/**
+ * Safe failure shaping shared by SDK transports and reconciliation stores.
+ * Provider error text is retained only in the local diagnostic log; wire and
+ * persisted reconciliation details expose a fixed redacted message.
+ */
+export const PROMPT_FAILURE_CODE_MAX = 64;
+const LOCAL_FAILURE_LOG_MAX = 16_384;
+
+/** Safe-token code capped at 64; arbitrary failure text is never retained. */
+export function sanitizePromptFailure(error: unknown): { code: string; message: string } {
+	let rawCode = "";
+	try {
+		const candidate = error as { code?: unknown } | undefined;
+		rawCode = typeof candidate?.code === "string" ? candidate.code : "";
+	} catch {
+		// Untrusted error records may expose throwing accessors.
+	}
+	const code = rawCode.length <= PROMPT_FAILURE_CODE_MAX && /^[A-Za-z0-9._-]+$/.test(rawCode) ? rawCode : "internal";
+	return { code, message: "Prompt submission failed." };
+}
+
+/** Best-effort local diagnostic text that never crosses the SDK boundary. */
+export function formatPromptFailureForLocalLog(error: unknown): string {
+	try {
+		let detail: string;
+		if (error instanceof Error) {
+			const stack = error.stack;
+			detail = typeof stack === "string" ? stack : error.message;
+		} else if (typeof error === "string") detail = error;
+		else if (error !== null && typeof error === "object") {
+			const candidate = error as { code?: unknown; message?: unknown };
+			const code = typeof candidate.code === "string" ? candidate.code : undefined;
+			const message = typeof candidate.message === "string" ? candidate.message : undefined;
+			detail =
+				[code, message].filter((value): value is string => value !== undefined).join(": ") ||
+				"<object prompt failure>";
+		} else detail = String(error);
+		return detail.length <= LOCAL_FAILURE_LOG_MAX ? detail : `${detail.slice(0, LOCAL_FAILURE_LOG_MAX)}…`;
+	} catch {
+		return "<unserializable prompt failure>";
+	}
+}

package/src/sdk/prompt-watchdog.ts

@@ -0,0 +1,162 @@
+import { TOOL_TIMEOUTS } from "../tools/tool-timeouts";
+import { HEARTBEAT_TTL_MS } from "./bus/daemon-paths";
+
+/** Ceiling a caller may *request* for one tool call; `bash`/`ssh` cap out at 3600s. */
+const MAX_TOOL_RUNTIME_MS = Math.max(...Object.values(TOOL_TIMEOUTS).map(config => config.max)) * 1_000;
+
+/** Budget one tool call gets when nobody asks to extend it; `bash` defaults to 300s. */
+const DEFAULT_TOOL_RUNTIME_MS = Math.max(...Object.values(TOOL_TIMEOUTS).map(config => config.default)) * 1_000;
+
+/**
+ * Frame-free cost of one transport round trip while the producer is still healthy:
+ * the owner heartbeat has to lapse ({@link HEARTBEAT_TTL_MS}) before a reconnect is
+ * even attempted, and the reconnect itself gets a second window.
+ */
+const SDK_RECONNECT_BUDGET_MS = 2 * HEARTBEAT_TTL_MS;
+
+/**
+ * Inactivity bound for a prompt whose session host has no tool call in flight: after
+ * this much silence the host is treated as having stopped producing, so the prompt is
+ * settled instead of hanging the client forever.
+ *
+ * Every step of a live turn emits a frame (`agent_start`, message events, tool events,
+ * `agent_end`), so this bound only has to exceed the longest frame-free gap a healthy
+ * turn can produce *with nothing executing*: one model round trip, from the request
+ * leaving the host to the first streamed event coming back, possibly straddling a
+ * transport reconnect.
+ *
+ * `TOOL_TIMEOUTS` is this runtime's own statement of how long a single unattended step
+ * may block before it is declared stuck, and its slowest **default**
+ * ({@link DEFAULT_TOOL_RUNTIME_MS}) is the longest such wait nobody explicitly opted
+ * into. That is well above the agent's own model-stream watchdog (120s idle / 100s
+ * first event in `packages/ai/src/utils/idle-iterator.ts`), which aborts a stalled
+ * provider stream and republishes it as an error frame — itself a frame — long before
+ * this bound. {@link SDK_RECONNECT_BUDGET_MS} is added on top so a reconnect landing
+ * inside that gap cannot trip it either. Two providers widen their first-event
+ * fallback past this bound (alibaba-token-plan 600s, kimi-code 300s); a turn that
+ * emits nothing at all for this long on those is reported as abandoned rather than
+ * left `running`, and the session still accepts the next prompt.
+ *
+ * {@link MAX_TOOL_RUNTIME_MS} is deliberately *not* used here. `max` is what a caller
+ * may request, not what tools take, so sizing every gap for it produced a 63min bound
+ * that could never act as a safety net. Turns that legitimately reach that ceiling are
+ * covered by {@link ACP_PROMPT_TOOL_ACTIVITY_TIMEOUT_MS} instead, which is gated on
+ * evidence that a tool is actually executing.
+ */
+export const ACP_PROMPT_INACTIVITY_TIMEOUT_MS = DEFAULT_TOOL_RUNTIME_MS + SDK_RECONNECT_BUDGET_MS;
+
+/**
+ * Inactivity bound that applies only while the session host has an unfinished tool
+ * call — a `tool_execution_start`/`tool_execution_update` with no matching
+ * `tool_execution_end`.
+ *
+ * A long `bash` is protected by the evidence that it is running, not by a constant
+ * sized for the worst case, so this wide bound stands only for as long as that
+ * evidence does. It still terminates: no tool call may outlive
+ * {@link MAX_TOOL_RUNTIME_MS}, after which the host must publish `tool_execution_end`,
+ * so a host that dies mid-tool is still reported (one reconnect budget later).
+ */
+export const ACP_PROMPT_TOOL_ACTIVITY_TIMEOUT_MS = MAX_TOOL_RUNTIME_MS + SDK_RECONNECT_BUDGET_MS;
+
+/**
+ * Widest frame-free window a single provider call may legitimately occupy before the
+ * agent's own stream watchdog aborts it. Mirrors `ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS`
+ * in `packages/ai/src/utils/idle-iterator.ts` (600s), the largest per-provider first-event
+ * fallback of any built-in provider — `DEFAULT_STREAM_FIRST_EVENT_TIMEOUT_MS` is 100s and
+ * `kimi-code` gets 300s. That constant is module-private there, so it is mirrored here and
+ * pinned against `getProviderFirstEventTimeoutFallbackMs` in the watchdog test: a change on
+ * either side fails loudly instead of silently inflating this bound.
+ */
+const MAX_PROVIDER_FIRST_EVENT_TIMEOUT_MS = 600_000;
+
+/**
+ * Inactivity bound that applies while a prompt is awaiting the model: a provider call is in
+ * flight and has not produced the first frame of its response yet.
+ *
+ * Tool execution had evidence and model inference did not, so a turn thinking after
+ * `agent_start` looked exactly like a dead producer and was killed at
+ * {@link ACP_PROMPT_INACTIVITY_TIMEOUT_MS}. Inference gets the same evidence-based
+ * tolerance: the wide bound stands only as long as a model call is observably unanswered.
+ *
+ * It still terminates. A provider stream that yields nothing within
+ * {@link MAX_PROVIDER_FIRST_EVENT_TIMEOUT_MS} is aborted by the agent's own stream watchdog,
+ * which republishes as an error/retry frame, so a host that dies mid-inference is still
+ * reported one reconnect budget later.
+ */
+export const ACP_PROMPT_INFERENCE_TIMEOUT_MS = MAX_PROVIDER_FIRST_EVENT_TIMEOUT_MS + SDK_RECONNECT_BUDGET_MS;
+
+/**
+ * Per-prompt view of what the session host is observably doing: which tool calls it has
+ * started but not finished, and whether it is waiting on a model call. Inbound frames are
+ * the only evidence the ACP side has, so "a tool is running" means exactly "a start was
+ * observed and its end was not", and "awaiting the model" means exactly "a model call was
+ * dispatched and nothing from its response has been observed".
+ */
+export class PromptActivity {
+	readonly #running = new Set<string>();
+	#awaitingModel = false;
+
+	/** Folds one inbound frame's lifecycle event into the in-flight tool and model state. */
+	observe(eventType: string | undefined, toolCallId: string | undefined, messageRole: string | undefined): void {
+		this.#observeInference(eventType, messageRole);
+		if (toolCallId === undefined) return;
+		if (eventType === "tool_execution_start" || eventType === "tool_execution_update") this.#running.add(toolCallId);
+		else if (eventType === "tool_execution_end") this.#running.delete(toolCallId);
+	}
+
+	/**
+	 * A turn is awaiting the model from every point where the host dispatches a provider
+	 * call — `agent_start` for the turn's first call, `tool_execution_end` for the
+	 * re-invocation that carries a tool result back — until the first frame of that
+	 * response proves the model answered.
+	 */
+	#observeInference(eventType: string | undefined, messageRole: string | undefined): void {
+		if (eventType === "agent_start" || eventType === "tool_execution_end") {
+			this.#awaitingModel = true;
+			return;
+		}
+		// Streamed content/thinking/tool-call deltas, and the tool call the model asked for,
+		// are only ever produced by an answering model.
+		if (eventType === "message_update" || eventType === "tool_execution_start") {
+			this.#awaitingModel = false;
+			return;
+		}
+		// Providers that do not stream emit no `message_update`, so the assistant message
+		// itself is the first proof. `message_start`/`message_end` also carry the user and
+		// tool-result messages the host echoes back, which prove nothing about the model.
+		if ((eventType === "message_start" || eventType === "message_end") && messageRole === "assistant")
+			this.#awaitingModel = false;
+	}
+
+	/** True while at least one started tool call has not reported an end. */
+	get running(): boolean {
+		return this.#running.size > 0;
+	}
+
+	/** True while a dispatched model call has not produced the first frame of its response. */
+	get awaitingModel(): boolean {
+		return this.#awaitingModel;
+	}
+
+	/** Bound that applies to the next frame-free gap, given what is observably executing. */
+	get inactivityBoundMs(): number {
+		if (this.running) return ACP_PROMPT_TOOL_ACTIVITY_TIMEOUT_MS;
+		return this.#awaitingModel ? ACP_PROMPT_INFERENCE_TIMEOUT_MS : ACP_PROMPT_INACTIVITY_TIMEOUT_MS;
+	}
+}
+
+/** Timer surface behind the prompt watchdog; tests substitute a virtual clock. */
+export interface PromptWatchdogClock {
+	now(): number;
+	/** Runs `handler` after `delayMs`; the returned callback cancels the pending run. */
+	schedule(handler: () => void, delayMs: number): () => void;
+}
+
+export const systemPromptWatchdogClock: PromptWatchdogClock = {
+	now: () => Date.now(),
+	schedule(handler: () => void, delayMs: number): () => void {
+		const timer = setTimeout(handler, delayMs);
+		timer.unref?.();
+		return () => clearTimeout(timer);
+	},
+};

package/src/sdk/session-reconnect.ts

@@ -0,0 +1,43 @@
+import { HEARTBEAT_TTL_MS } from "./bus/daemon-paths";
+import type { SdkClientOptions } from "./client";
+
+type SessionReconnectOptions = Required<
+	Pick<SdkClientOptions, "reconnectAttempts" | "reconnectBackoffMs" | "reconnectMaxBackoffMs">
+>;
+
+const SESSION_RECONNECT_BACKOFF_MS = 250;
+const SESSION_RECONNECT_MAX_BACKOFF_MS = 2_000;
+/** Cover twice the host heartbeat TTL so a reaped stall still has room to recover. */
+const SESSION_RECONNECT_BUDGET_MS = 2 * HEARTBEAT_TTL_MS;
+
+function attemptsCovering(budgetMs: number): number {
+	let elapsed = 0;
+	let attempts = 0;
+	while (elapsed <= budgetMs) {
+		elapsed += Math.min(SESSION_RECONNECT_BACKOFF_MS * 2 ** attempts, SESSION_RECONNECT_MAX_BACKOFF_MS);
+		attempts++;
+	}
+	return attempts;
+}
+
+/**
+ * Reconnect budget for every long-lived SDK session client: ACP sessions and the
+ * chat daemon's attached sessions alike. Named for the ACP session that first
+ * needed it; it lives here because both live under the same host reaper and the
+ * bus layer must not import the ACP layer to reach it.
+ *
+ * Invariant: the client's total reconnect budget must outlive the host heartbeat
+ * TTL ({@link HEARTBEAT_TTL_MS}). The SDK host drops a session whose client has
+ * not ponged within that TTL, so a client that gives up reconnecting sooner turns
+ * every stall the host reaps into a permanently lost session ("SDK WebSocket
+ * reconnect attempts exhausted"). The transport defaults (3 attempts at 25ms base
+ * = 175ms total) are correct only for one-shot request clients.
+ *
+ * Backoff ramps 250 -> 500 -> 1000 and then holds at the 2s cap, so individual
+ * sleeps stay short and recovery is prompt once the host answers again.
+ */
+export const ACP_SESSION_RECONNECT: SessionReconnectOptions = {
+	reconnectAttempts: attemptsCovering(SESSION_RECONNECT_BUDGET_MS),
+	reconnectBackoffMs: SESSION_RECONNECT_BACKOFF_MS,
+	reconnectMaxBackoffMs: SESSION_RECONNECT_MAX_BACKOFF_MS,
+};

package/src/sdk/startup-capability.ts

@@ -5,7 +5,14 @@ import {
 } from "../config/model-profile-contract";
 export type SdkStartupPhase = "registration" | "startup";
 
-export type SdkStartupReason = "disabled" | "ineligible" | "factory_absent" | "runner_absent" | "pending" | "failed";
+export type SdkStartupReason =
+	| "disabled"
+	| "ineligible"
+	| "factory_absent"
+	| "runner_absent"
+	| "admission_timeout"
+	| "pending"
+	| "failed";
 
 export interface SdkStartupFailure {
 	phase: SdkStartupPhase;
@@ -143,9 +150,11 @@ export function normalizeSdkStartupFailure(
 					? "SDK startup factory is unavailable."
 					: reason === "runner_absent"
 						? "SDK startup extension runner is unavailable."
-						: reason === "pending"
-							? "SDK startup did not complete before readiness cutoff."
-							: FALLBACK_MESSAGE;
+						: reason === "admission_timeout"
+							? "SDK host startup was not admitted before the queue wait cutoff."
+							: reason === "pending"
+								? "SDK startup did not complete before readiness cutoff."
+								: FALLBACK_MESSAGE;
 	const message = sanitizeSdkStartupMessage(error, knownSecrets);
 	const profileError = isModelProfileError(error) ? { code: error.code, details: error.details } : {};
 	return { phase, reason, message: message === FALLBACK_MESSAGE ? fallback : message, ...profileError };