@gajae-code/coding-agent 0.18.6 → 0.18.8

package/src/runtime-mcp/client.ts

@@ -451,6 +451,9 @@ function isModernMethodNotFound(error: unknown): boolean {
  * The original request is retried with `inputResponses` and a verbatim
  * `requestState` echo under a fresh JSON-RPC id, at most MAX_MRTR_RETRIES times;
  * the retry is fenced to the originating exchange by a stable correlation id.
+ * `roots/list` input requests are answered locally; every other input request
+ * requires `options.inputHandler`, and its absence fails the exchange before any
+ * retry is sent (no write replay, no implicit accept).
  */
 async function requestWithInputHandling<T>(
 	connection: MCPServerConnection,
@@ -474,17 +477,20 @@ async function requestWithInputHandling<T>(
 	if (!inputRequired) return stripResultType(initial);
 
 	const handler = options?.inputHandler;
-	if (!handler) {
-		throw new MCPExpectedFailure(
+	const correlationId = crypto.randomUUID();
+
+	const missingHandler = () =>
+		new MCPExpectedFailure(
 			new Error(
 				`MCP server "${connection.name}" requested additional input (input_required) for ${method}, but no interactive input handler is available`,
 			),
 		);
-	}
-	const correlationId = crypto.randomUUID();
 
 	for (let attempt = 0; attempt < MAX_MRTR_RETRIES; attempt++) {
 		const inputResponses: Record<string, unknown> = {};
+		// A requestState-only round has no local answer to give; without an
+		// interactive handler it is never replayed unattended.
+		if (!handler && Object.keys(inputRequired.inputRequests).length === 0) throw missingHandler();
 		for (const [key, request] of Object.entries(inputRequired.inputRequests)) {
 			if (options?.signal?.aborted) {
 				throw options.signal.reason instanceof Error ? options.signal.reason : new Error("Aborted");
@@ -494,6 +500,9 @@ async function requestWithInputHandling<T>(
 				inputResponses[key] = await defaultRequestHandler("roots/list", undefined);
 				continue;
 			}
+			// Everything else (elicitation, sampling, ...) needs a real interactive
+			// handler. It is never answered implicitly; fail before any retry is sent.
+			if (!handler) throw missingHandler();
 			const outcome = await handler(key, request, {
 				serverName: connection.name,
 				originMethod: method,

package/src/runtime-mcp/config-writer.ts

@@ -50,13 +50,17 @@ export async function writeMCPConfigFile(filePath: string, config: MCPConfigFile
 	const dir = path.dirname(filePath);
 	await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
 
-	// Write to temp file first (atomic write)
-	const tmpPath = `${filePath}.tmp`;
+	// A predictable `${file}.tmp` can already be a symlink planted in the project.
+	// Write a unique sibling and fail closed if that path exists.
+	const tmpPath = `${filePath}.${crypto.randomUUID()}.tmp`;
 	const content = JSON.stringify(withSchema(config), null, 2);
-	await fs.promises.writeFile(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
-
-	// Rename to final path (atomic on most systems)
-	await fs.promises.rename(tmpPath, filePath);
+	try {
+		await fs.promises.writeFile(tmpPath, content, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+		await fs.promises.rename(tmpPath, filePath);
+	} catch (error) {
+		await fs.promises.rm(tmpPath, { force: true });
+		throw error;
+	}
 	// Invalidate the capability fs cache so subsequent reads see the new content
 	invalidateFsCache(filePath);
 }

package/src/runtime-mcp/config.ts

@@ -103,6 +103,7 @@ function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
 			url: server.url ?? "",
 		};
 		if (server.headers) config.headers = server.headers;
+		if (server.publicNetwork === true) config.publicNetwork = true;
 		canonicalizeMCPEndpoint(config.url);
 		return config;
 	}

package/src/runtime-mcp/elicitation.ts

@@ -0,0 +1,142 @@
+import { untilAborted } from "@gajae-code/utils";
+import type { ExtensionUIContext } from "../extensibility/extensions/types";
+import type { AskAnswerSource, AskRemoteReceipt } from "../tools";
+import type { MCPInputRequestHandler } from "./types";
+
+export interface MCPFormInputDependencies {
+	getUi(): { ui?: Pick<ExtensionUIContext, "select" | "input">; hasUI: boolean };
+	getAskAnswerSource(): AskAnswerSource | undefined;
+}
+
+interface FormField {
+	key: string;
+	label: string;
+	type: "string" | "boolean";
+	choices?: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function displayText(value: string): string {
+	return value.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ").slice(0, 4000);
+}
+
+/** Unsupported constraints are rejected, never silently discarded. */
+function decodeField(schema: unknown): FormField | undefined {
+	if (!isRecord(schema) || schema.type !== "object" || !isRecord(schema.properties)) return undefined;
+	const allowed = new Set(["type", "properties", "required", "additionalProperties", "title", "description"]);
+	if (Object.keys(schema).some(key => !allowed.has(key))) return undefined;
+	if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") return undefined;
+	const entries = Object.entries(schema.properties);
+	if (entries.length !== 1) return undefined;
+	const [key, property] = entries[0]!;
+	if (!isRecord(property) || (property.type !== "string" && property.type !== "boolean")) return undefined;
+	if (
+		schema.required !== undefined &&
+		(!Array.isArray(schema.required) || schema.required.some(value => value !== key))
+	)
+		return undefined;
+	const propertyKeys = new Set(["type", "title", "description", "enum"]);
+	if (Object.keys(property).some(name => !propertyKeys.has(name))) return undefined;
+	if (property.title !== undefined && typeof property.title !== "string") return undefined;
+	if (property.description !== undefined && typeof property.description !== "string") return undefined;
+	let choices: string[] | undefined;
+	if (property.enum !== undefined) {
+		if (
+			property.type !== "string" ||
+			!Array.isArray(property.enum) ||
+			property.enum.length === 0 ||
+			!property.enum.every(value => typeof value === "string") ||
+			new Set(property.enum).size !== property.enum.length ||
+			property.enum.some(value => displayText(value) !== value)
+		)
+			return undefined;
+		choices = property.enum;
+	}
+	const description = typeof property.description === "string" ? ` — ${property.description}` : "";
+	return { key, label: displayText(`${property.title ?? key}${description}`), type: property.type, choices };
+}
+
+/** Register on an owned manager; dependencies are resolved per call for late UI registration. */
+export function createMCPFormInputHandler(deps: MCPFormInputDependencies): MCPInputRequestHandler {
+	return async (_key, request, context) => {
+		if (context.signal?.aborted) return { kind: "failed", reason: "cancelled" };
+		if (request.method !== "elicitation/create") return { kind: "failed", reason: "unavailable" };
+		const params = request.params;
+		if (!params || typeof params.message !== "string" || (params.mode !== undefined && params.mode !== "form"))
+			return { kind: "failed", reason: "unavailable", message: "Unsupported MCP form request" };
+		const field = decodeField(params.requestedSchema);
+		if (!field) return { kind: "failed", reason: "unavailable", message: "Unsupported MCP form schema" };
+		const local = deps.getUi();
+		const ui = local.hasUI ? local.ui : undefined;
+		const source = ui ? undefined : deps.getAskAnswerSource();
+		if (!ui && !source)
+			return { kind: "failed", reason: "unavailable", message: "No user input surface is available" };
+		const signal = context.signal;
+		const ask = async (question: string, choices?: string[]): Promise<string | undefined> => {
+			return untilAborted(signal, async () => {
+				if (ui)
+					return choices ? ui.select(question, choices, { signal }) : ui.input(question, undefined, { signal });
+				if (!source) return undefined;
+				const answer = source.awaitAnswerRequest
+					? await source.awaitAnswerRequest(
+							{
+								question,
+								options: choices ?? [],
+								interaction: choices ? "selector" : "custom_editor",
+								controls: [],
+							},
+							signal,
+						)
+					: await source.awaitAnswer(question, choices ?? [], signal);
+				let receipt: AskRemoteReceipt | undefined;
+				let value: string | undefined;
+				if (typeof answer === "string") value = answer;
+				else if (answer) {
+					receipt = answer;
+					if (answer.interaction.kind === "value") value = answer.interaction.value;
+				}
+				if (signal?.aborted) {
+					await receipt?.settle({ kind: "resolve_without_commit", reason: "aborted" });
+					return undefined;
+				}
+				if (receipt?.interaction.kind === "control") {
+					await receipt.settle({ kind: "invalid", reason: "invalid_control" });
+					throw new Error("Invalid MCP form control");
+				}
+				if (value !== undefined && choices && !choices.includes(value)) {
+					await receipt?.settle({ kind: "invalid", reason: "invalid_option" });
+					throw new Error("Invalid MCP form answer");
+				}
+				const settlement = await receipt?.settle(
+					value === undefined ? { kind: "resolve_without_commit", reason: "cancelled" } : { kind: "commit" },
+				);
+				if (receipt && value !== undefined && settlement?.kind !== "committed") return undefined;
+				return value;
+			});
+		};
+		try {
+			const title = `MCP server ${displayText(context.serverName)} requests input (untrusted server text): ${displayText(params.message)}`;
+			const action = await ask(title, ["Accept", "Decline"]);
+			if (signal?.aborted) return { kind: "failed", reason: "cancelled" };
+			if (action === undefined) return { kind: "result", result: { action: "cancel" } };
+			if (action === "Decline") return { kind: "result", result: { action: "decline" } };
+			if (action !== "Accept") return { kind: "failed", reason: "error", message: "Invalid MCP form action" };
+			const choices = field.type === "boolean" ? ["Yes", "No"] : field.choices;
+			const answer = await ask(
+				`MCP server ${displayText(context.serverName)} (untrusted server text): ${field.label}`,
+				choices,
+			);
+			if (signal?.aborted) return { kind: "failed", reason: "cancelled" };
+			if (answer === undefined) return { kind: "result", result: { action: "cancel" } };
+			if (choices && !choices.includes(answer))
+				return { kind: "failed", reason: "error", message: "Invalid MCP form answer" };
+			const value = field.type === "boolean" ? answer === "Yes" : answer;
+			return { kind: "result", result: { action: "accept", content: { [field.key]: value } } };
+		} catch {
+			return { kind: "failed", reason: signal?.aborted ? "cancelled" : "error" };
+		}
+	};
+}

package/src/runtime-mcp/oauth-flow.ts

@@ -8,6 +8,7 @@
 import type { OAuthCallbackFlowOptions } from "@gajae-code/ai/utils/oauth/callback-server";
 import { OAuthCallbackFlow } from "@gajae-code/ai/utils/oauth/callback-server";
 import type { OAuthController, OAuthCredentials } from "@gajae-code/ai/utils/oauth/types";
+import { assertPublicOAuthUrl } from "./oauth-public-url";
 
 const DEFAULT_PORT = 3000;
 const CALLBACK_PATH = "/callback";
@@ -261,8 +262,10 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 			params.set("client_secret", clientSecret);
 		}
 
+		await assertPublicOAuthUrl(this.config.tokenUrl);
 		const response = await fetch(this.config.tokenUrl, {
 			method: "POST",
+			redirect: "error",
 			headers: {
 				"Content-Type": "application/x-www-form-urlencoded",
 			},
@@ -340,8 +343,10 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 		if (!registrationEndpoint) return;
 
 		try {
+			await assertPublicOAuthUrl(registrationEndpoint);
 			const response = await fetch(registrationEndpoint, {
 				method: "POST",
+				redirect: "error",
 				headers: {
 					"Content-Type": "application/json",
 					Accept: "application/json",

package/src/runtime-mcp/oauth-public-url.ts

@@ -0,0 +1,8 @@
+import { validatePublicHttpUrl } from "../web/insane/url-guard";
+
+export async function assertPublicOAuthUrl(url: string): Promise<void> {
+	const checked = await validatePublicHttpUrl(url);
+	if (!checked.ok) {
+		throw new Error(`Refusing non-public OAuth endpoint: ${checked.reason ?? url}`);
+	}
+}

package/src/runtime-mcp/plugin-network-boundary.ts

@@ -19,6 +19,10 @@ export function bindPluginMcpToPublicNetwork<T extends MCPHttpServerConfig | MCP
 }
 
 /** The marker is an internal symbol, so persisted user MCP configs cannot opt into or forge this path. */
+export function usesPublicNetworkMcpFetch(config: MCPHttpServerConfig | MCPSseServerConfig): boolean {
+	return ("publicNetwork" in config && config.publicNetwork === true) || isPluginMcpPublicNetworkBound(config);
+}
+
 export function isPluginMcpPublicNetworkBound(config: MCPHttpServerConfig | MCPSseServerConfig): boolean {
 	return (
 		(config as MCPHttpServerConfig & { [PLUGIN_MCP_PUBLIC_NETWORK_BOUNDARY]?: boolean })[

package/src/runtime-mcp/smithery-registry.ts

@@ -1,4 +1,5 @@
 import { logger } from "@gajae-code/utils";
+import { type AddressResolver, validatePublicHttpUrl } from "../web/insane/url-guard";
 import type { MCPServerConfig } from "./types";
 
 const SMITHERY_REGISTRY_BASE_URL = "https://registry.smithery.ai";
@@ -289,6 +290,20 @@ function chooseConnection(
 	return null;
 }
 
+export async function resolveSmitheryServerConfig(
+	qualifiedName: string,
+	selected: { connection: SmitheryConnection; useDirectHttp: boolean },
+	options?: { resolver?: AddressResolver },
+): Promise<MCPServerConfig | null> {
+	let useDirectHttp = selected.useDirectHttp;
+	const deploymentUrl = selected.connection.deploymentUrl;
+	if (useDirectHttp && selected.connection.type === "http" && deploymentUrl) {
+		const checked = await validatePublicHttpUrl(deploymentUrl, { resolver: options?.resolver });
+		if (!checked.ok) useDirectHttp = false;
+	}
+	return createConfig(qualifiedName, { connection: selected.connection, useDirectHttp });
+}
+
 function createConfig(
 	qualifiedName: string,
 	selected: { connection: SmitheryConnection; useDirectHttp: boolean },
@@ -297,6 +312,7 @@ function createConfig(
 		return {
 			type: "http",
 			url: selected.connection.deploymentUrl,
+			publicNetwork: true,
 		};
 	}
 
@@ -335,7 +351,10 @@ async function fetchServerDetailsFromEntry(
 	return null;
 }
 
-function toSearchResult(entry: SmitherySearchEntry, details: SmitheryServerDetails): SmitherySearchResult | null {
+async function toSearchResult(
+	entry: SmitherySearchEntry,
+	details: SmitheryServerDetails,
+): Promise<SmitherySearchResult | null> {
 	if (!entry.id) return null;
 	const qualifiedName = normalizeQualifiedName(
 		details.qualifiedName ?? entry.qualifiedName ?? `${entry.namespace}/${entry.slug}`,
@@ -343,7 +362,7 @@ function toSearchResult(entry: SmitherySearchEntry, details: SmitheryServerDetai
 	const selected = chooseConnection(details);
 	if (!selected) return null;
 
-	const config = createConfig(qualifiedName, selected);
+	const config = await resolveSmitheryServerConfig(qualifiedName, selected);
 	if (!config) return null;
 
 	const requiredInputs = getSchemaInputs(selected.connection.configSchema);
@@ -450,7 +469,7 @@ export async function searchSmitheryRegistry(
 			try {
 				const details = await fetchServerDetailsFromEntry(entry, { apiKey: options?.apiKey });
 				if (!details) return null;
-				return toSearchResult(entry, details);
+				return await toSearchResult(entry, details);
 			} catch (error) {
 				detailFailures.push({
 					identity: getEntryIdentityKey(entry) ?? entry.id ?? "unknown",

package/src/runtime-mcp/transports/http.ts

@@ -28,7 +28,7 @@ import {
 	MCP_MAX_SSE_REQUEST_MESSAGES,
 	readMCPResponseText,
 } from "../content-limits";
-import { fetchPluginMcpRequest, isPluginMcpPublicNetworkBound } from "../plugin-network-boundary";
+import { fetchPluginMcpRequest, usesPublicNetworkMcpFetch } from "../plugin-network-boundary";
 import { buildModernMcpHeaders, type MCPModernClientContext, type MCPProtocolEra, withModernMeta } from "../protocol";
 
 /**
@@ -155,7 +155,7 @@ export class HttpTransport implements MCPTransport {
 	}
 
 	#fetch(init: BunFetchRequestInit): Promise<Response> {
-		return isPluginMcpPublicNetworkBound(this.config)
+		return usesPublicNetworkMcpFetch(this.config)
 			? fetchPluginMcpRequest(this.config.url, init)
 			: fetch(this.config.url, init);
 	}

package/src/runtime-mcp/types.ts

@@ -139,6 +139,12 @@ export interface MCPHttpServerConfig extends MCPServerConfigBase {
 	type: "http";
 	url: string;
 	headers?: Record<string, string>;
+	/**
+	 * When true, every request and redirect for this URL is rechecked against
+	 * the public-network policy. Persisted so a later process cannot fall back
+	 * to an unguarded fetch. Ordinary localhost MCP servers leave this unset.
+	 */
+	publicNetwork?: boolean;
 }
 
 /** SSE server configuration (deprecated, use HTTP) */

package/src/sdk/acp/adapter.ts

@@ -1,7 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { logger } from "@gajae-code/utils";
 import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
-import { type SdkClient, SdkClientError } from "../client";
+import {
+	DEFAULT_SDK_REQUEST_TIMEOUT_MS,
+	type SdkClient,
+	SdkClientError,
+	type SdkDispatchContext,
+	type SdkSentRecord,
+} from "../client";
 import type { AbortScope } from "../host/control/operations";
 import { assertReverseResponseFrame, ReverseLeaseError } from "../host/reverse-leases";
 import {
@@ -143,6 +149,7 @@ const ACP_MCP_PRESERVED_LAUNCH_CODES = new Set([
 	"readiness_timeout",
 	"spawn_failed",
 	"worktree_in_use",
+	"uncertain_after_send",
 ]);
 
 /**
@@ -531,7 +538,11 @@ export class AcpSdkAdapter {
 		return envelope?.result ?? response;
 	}
 
-	async #requestSession(frame: JsonObject, raw = false, options?: { timeoutMs: number }): Promise<unknown> {
+	async #requestSession(
+		frame: JsonObject,
+		raw = false,
+		options?: { timeoutMs: number; deadline?: number },
+	): Promise<unknown> {
 		const router = this.#router;
 		if (!router)
 			throw new AcpSdkAdapterError(
@@ -603,11 +614,68 @@ export class AcpSdkAdapter {
 		// request that named no readiness budget is queued for the default one, so it
 		// needs the same extension rather than the client's generic request deadline.
 		const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
-		const response = await this.#client.global(operation, input, {
+		const budgetMs = timeoutMs ?? DEFAULT_SDK_REQUEST_TIMEOUT_MS;
+		const deadline = Date.now() + budgetMs;
+		let sent = false;
+		let sentRecord: SdkSentRecord | undefined;
+		let uncertainty: SdkClientError | undefined;
+		const deadlineFailure = () =>
+			uncertainty ??
+			(sent
+				? new SdkClientError(
+						"uncertain_after_send",
+						"ACP lifecycle deadline elapsed after dispatch.",
+						sentRecord ?? {
+							operation,
+							idempotencyKey,
+						},
+					)
+				: new SdkClientError("timeout", "ACP lifecycle deadline elapsed before dispatch.", undefined, undefined, {
+						transport: true,
+					}));
+		const options = {
 			idempotencyKey,
-			...(timeoutMs === undefined ? {} : { timeoutMs }),
-		});
-		return response;
+			deadline,
+			// SdkClient reads this after connecting, so reconnect and replay spend the same allowance.
+			get timeoutMs() {
+				return Math.max(0, deadline - Date.now());
+			},
+			beforeDispatch: () => {
+				if (Date.now() >= deadline) throw deadlineFailure();
+			},
+			onDispatch: (context: SdkDispatchContext) => {
+				sent = true;
+				if (typeof context.frame.id === "string") sentRecord = client.getSentRecord(context.frame.id);
+			},
+		};
+		const expired = Promise.withResolvers<never>();
+		const timer = setTimeout(() => expired.reject(deadlineFailure()), budgetMs);
+		const recover = async () => {
+			try {
+				const result = await client.global(operation, input, options);
+				if (Date.now() >= deadline) throw deadlineFailure();
+				return result;
+			} catch (firstError) {
+				if (!(firstError instanceof SdkClientError) || firstError.code !== "uncertain_after_send") throw firstError;
+				uncertainty = firstError;
+				// Same-key replay joins the original durable claim, within the original deadline.
+				// Failure to recover does not prove that the committed operation failed.
+				if (Date.now() >= deadline) throw firstError;
+				try {
+					const result = await client.global(operation, input, options);
+					if (Date.now() >= deadline) throw firstError;
+					return result;
+				} catch (replayError) {
+					if (replayError !== firstError) Object.assign(firstError, { recovery: replayError });
+					throw firstError;
+				}
+			}
+		};
+		try {
+			return await Promise.race([recover(), expired.promise]);
+		} finally {
+			clearTimeout(timer);
+		}
 	}
 
 	async sdkControl(params: { operation: string; input?: JsonObject }): Promise<unknown> {
@@ -646,7 +714,7 @@ export class AcpSdkAdapter {
 		throw new AcpSdkAdapterError("method_not_found", `Unsupported ACP SDK method: ${method}`);
 	}
 
-	async registerProvider(provider: AcpProviderRegistration): Promise<void> {
+	async registerProvider(provider: AcpProviderRegistration, timeoutMs?: number, deadline?: number): Promise<void> {
 		if (!this.#router)
 			throw new AcpSdkAdapterError(
 				"operation_prohibited",
@@ -665,10 +733,15 @@ export class AcpSdkAdapter {
 				...(previousLeaseId ? { expectedLeaseId: previousLeaseId } : {}),
 			},
 			true,
+			timeoutMs === undefined ? undefined : { timeoutMs, ...(deadline === undefined ? {} : { deadline }) },
 		);
 		const result = object(object(response)?.result) ?? object(response) ?? {};
 		if (typeof result.leaseId !== "string")
 			throw new AcpSdkAdapterError("invalid_reverse_frame", "Provider registration omitted leaseId.");
+		if (this.#closed)
+			throw new AcpSdkAdapterError("connection_closed", "ACP provider activation closed before acknowledgement.");
+		if (deadline !== undefined && Date.now() >= deadline)
+			throw new AcpSdkAdapterError("provider_activation_exhausted", "ACP provider activation deadline elapsed.");
 		this.#leases.set(provider.capability, result.leaseId);
 		if (previousLeaseId && previousLeaseId !== result.leaseId) this.#abortReverseForCapability(provider.capability);
 	}
@@ -694,9 +767,20 @@ export class AcpSdkAdapter {
 				const connectionId = attachment?.connectionId;
 				try {
 					for (const provider of this.#providers) {
+						const providerRemainingMs = PROVIDER_ACTIVATION_BUDGET_MS - (Date.now() - startedAt);
+						if (providerRemainingMs <= 0) throw this.#providerActivationExhausted(attempt, startedAt);
 						try {
-							await this.registerProvider(provider);
+							await this.registerProvider(
+								provider,
+								Math.max(1, providerRemainingMs),
+								startedAt + PROVIDER_ACTIVATION_BUDGET_MS,
+							);
+							if (Date.now() - startedAt >= PROVIDER_ACTIVATION_BUDGET_MS)
+								throw this.#providerActivationExhausted(attempt, startedAt);
 						} catch (error) {
+							if (providerErrorCode(error) === "uncertain_after_send") throw error;
+							if (Date.now() - startedAt >= PROVIDER_ACTIVATION_BUDGET_MS)
+								throw this.#providerActivationExhausted(attempt, startedAt);
 							if (providerErrorCode(error) === "provider_lease_conflict") {
 								this.#leases.delete(provider.capability);
 								this.#abortReverseForCapability(provider.capability);
@@ -725,6 +809,7 @@ export class AcpSdkAdapter {
 					this.#providersActivated = true;
 					return;
 				} catch (error) {
+					if (providerErrorCode(error) === "uncertain_after_send") throw error;
 					if (this.#router && attachment !== this.#attachment && !this.#closed) {
 						this.#providersActivated = false;
 						continue;

package/src/sdk/broker/broker-exit.ts

@@ -22,6 +22,7 @@ export type BrokerFenceReason = "suspect-unpublished" | "observation-ambiguous"
 export type BrokerExitReason =
 	| "ownership-fence-expired"
 	| "publication-liveness-timeout"
+	| "heartbeat-renewal-blocked"
 	| "restart-committed"
 	| "shutdown-request"
 	| "startup-failure"
@@ -39,6 +40,8 @@ export interface BrokerExitRecord {
 	fenceReason: BrokerFenceReason | null;
 	fencedForMs: number;
 	uptimeMs: number;
+	/** For a blocked heartbeat renewal: retained removal transition path. */
+	blockingLockPath?: string;
 	pid: number;
 	signal: "SIGINT" | "SIGTERM" | null;
 	writtenAt: number;
@@ -47,7 +50,7 @@ export interface BrokerExitRecord {
 export interface BrokerStartupExitRecord {
 	version: 1;
 	mode: "startup";
-	reason: "startup-deadline" | "startup-signal";
+	reason: "startup-deadline" | "startup-signal" | "startup-lock-blocked";
 	fenceReason: null;
 	fencedForMs: 0;
 	uptimeMs: number;
@@ -56,6 +59,8 @@ export interface BrokerStartupExitRecord {
 	exitCode: 1 | 130 | 143;
 	timeoutMs: number | null;
 	writtenAt: number;
+	/** For lock-blocked reason: path to the retained removal transition. */
+	blockingLockPath?: string;
 }
 
 export type BrokerStartupExitWriteStatus =
@@ -71,6 +76,7 @@ const lastWriteGenerationByPath = new Map<string, number>();
 const EXIT_REASONS = new Set<BrokerExitReason>([
 	"ownership-fence-expired",
 	"publication-liveness-timeout",
+	"heartbeat-renewal-blocked",
 	"restart-committed",
 	"shutdown-request",
 	"startup-failure",
@@ -94,11 +100,20 @@ function isBrokerExitRecord(value: unknown): value is BrokerExitRecord {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
 	const record = value as Partial<BrokerExitRecord>;
 	const keys = Object.keys(record).sort();
+	const requiredKeys = [
+		"fenceReason",
+		"fencedForMs",
+		"mode",
+		"pid",
+		"reason",
+		"signal",
+		"uptimeMs",
+		"version",
+		"writtenAt",
+	];
 	return (
-		keys.join(",") ===
-			["fenceReason", "fencedForMs", "mode", "pid", "reason", "signal", "uptimeMs", "version", "writtenAt"]
-				.sort()
-				.join(",") &&
+		keys.every(key => requiredKeys.includes(key) || key === "blockingLockPath") &&
+		requiredKeys.every(key => keys.includes(key)) &&
 		record.version === 1 &&
 		(record.mode === "owned-root" || record.mode === "lost-root") &&
 		typeof record.reason === "string" &&
@@ -115,6 +130,14 @@ function isBrokerExitRecord(value: unknown): value is BrokerExitRecord {
 		(record.pid as number) > 0 &&
 		(record.signal === null || record.signal === "SIGINT" || record.signal === "SIGTERM") &&
 		(record.reason === "signal") === (record.signal !== null) &&
+		(record.reason === "heartbeat-renewal-blocked"
+			? record.mode === "owned-root" &&
+				record.fenceReason === null &&
+				record.fencedForMs === 0 &&
+				record.signal === null &&
+				typeof record.blockingLockPath === "string" &&
+				record.blockingLockPath.length > 0
+			: record.blockingLockPath === undefined) &&
 		Number.isSafeInteger(record.writtenAt) &&
 		(record.writtenAt as number) > 0
 	);
@@ -125,26 +148,29 @@ function isBrokerStartupExitRecord(value: unknown): value is BrokerStartupExitRe
 	const record = value as Partial<BrokerStartupExitRecord>;
 	const signalExitCode = record.signal === "SIGINT" ? 130 : record.signal === "SIGTERM" ? 143 : null;
 	const keys = Object.keys(record).sort();
+	const requiredKeys = [
+		"exitCode",
+		"fenceReason",
+		"fencedForMs",
+		"mode",
+		"pid",
+		"reason",
+		"signal",
+		"timeoutMs",
+		"uptimeMs",
+		"version",
+		"writtenAt",
+	];
+	const isValidShape =
+		keys.every(k => requiredKeys.includes(k) || k === "blockingLockPath") &&
+		requiredKeys.every(k => keys.includes(k));
 	return (
-		keys.join(",") ===
-			[
-				"exitCode",
-				"fenceReason",
-				"fencedForMs",
-				"mode",
-				"pid",
-				"reason",
-				"signal",
-				"timeoutMs",
-				"uptimeMs",
-				"version",
-				"writtenAt",
-			]
-				.sort()
-				.join(",") &&
+		isValidShape &&
 		record.version === 1 &&
 		record.mode === "startup" &&
-		(record.reason === "startup-deadline" || record.reason === "startup-signal") &&
+		(record.reason === "startup-deadline" ||
+			record.reason === "startup-signal" ||
+			record.reason === "startup-lock-blocked") &&
 		record.fenceReason === null &&
 		record.fencedForMs === 0 &&
 		Number.isSafeInteger(record.uptimeMs) &&
@@ -154,7 +180,10 @@ function isBrokerStartupExitRecord(value: unknown): value is BrokerStartupExitRe
 		(record.signal === null || record.signal === "SIGINT" || record.signal === "SIGTERM") &&
 		(record.exitCode === 1 || record.exitCode === 130 || record.exitCode === 143) &&
 		(record.timeoutMs === null || (Number.isSafeInteger(record.timeoutMs) && (record.timeoutMs as number) > 0)) &&
-		(record.reason === "startup-deadline"
+		(record.reason === "startup-lock-blocked"
+			? typeof record.blockingLockPath === "string" && record.blockingLockPath.length > 0
+			: record.blockingLockPath === undefined) &&
+		(record.reason === "startup-deadline" || record.reason === "startup-lock-blocked"
 			? record.exitCode === 1 && record.signal === null && record.timeoutMs !== null
 			: record.exitCode === signalExitCode && signalExitCode !== null && record.timeoutMs === null) &&
 		Number.isSafeInteger(record.writtenAt) &&