@gajae-code/coding-agent 0.11.10 → 0.12.0

package/src/runtime-mcp/manager.ts

@@ -68,17 +68,24 @@ type ConnectionTask = {
 
 const STARTUP_TIMEOUT_MS = 250;
 const STARTUP_TIMEOUT_GRACE_MS = 500;
+/**
+ * Default ceiling on how long `discoverAndConnect` waits for a server batch to
+ * come up. Deliberately short: a config with a large `timeout` must not be able
+ * to hang ordinary startup. ACP lifecycle launches carry their own, larger
+ * budget derived from the readiness deadline (see `maxStartupTimeoutMs`).
+ */
 const MAX_STARTUP_TIMEOUT_MS = 1_750;
 
-function resolveStartupTimeoutMs(configs: MCPServerConfig[]): number {
+export function resolveStartupTimeoutMs(configs: MCPServerConfig[], maxStartupTimeoutMs?: number): number {
+	const ceiling =
+		typeof maxStartupTimeoutMs === "number" && Number.isFinite(maxStartupTimeoutMs) && maxStartupTimeoutMs > 0
+			? Math.max(STARTUP_TIMEOUT_MS, maxStartupTimeoutMs)
+			: MAX_STARTUP_TIMEOUT_MS;
 	const configuredTimeouts = configs
 		.map(config => config.timeout)
 		.filter((timeout): timeout is number => typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0);
 	if (configuredTimeouts.length === 0) return STARTUP_TIMEOUT_MS;
-	return Math.min(
-		MAX_STARTUP_TIMEOUT_MS,
-		Math.max(STARTUP_TIMEOUT_MS, Math.max(...configuredTimeouts) + STARTUP_TIMEOUT_GRACE_MS),
-	);
+	return Math.min(ceiling, Math.max(STARTUP_TIMEOUT_MS, Math.max(...configuredTimeouts) + STARTUP_TIMEOUT_GRACE_MS));
 }
 
 function trackPromise<T>(promise: Promise<T>): TrackedPromise<T> {
@@ -185,6 +192,13 @@ export interface MCPDiscoverOptions {
 export interface MCPManagerOptions {
 	/** Restrict this instance to tools from an explicit MCP config. */
 	toolsOnly?: boolean;
+	/**
+	 * Ceiling for the startup wait, in milliseconds. Only ACP lifecycle launches
+	 * set this, so a slow ACP MCP handshake gets the readiness budget while every
+	 * other consumer keeps the short default. Non-positive or non-finite values
+	 * are ignored and the default applies.
+	 */
+	maxStartupTimeoutMs?: number;
 }
 
 /**
@@ -269,12 +283,15 @@ export class MCPManager {
 		);
 	}
 
+	readonly #maxStartupTimeoutMs: number | undefined;
+
 	constructor(
 		private cwd: string,
 		private toolCache: MCPToolCache | null = null,
 		options: MCPManagerOptions = {},
 	) {
 		this.#toolsOnly = options.toolsOnly === true;
+		this.#maxStartupTimeoutMs = options.maxStartupTimeoutMs;
 	}
 
 	isToolsOnly(): boolean {
@@ -633,7 +650,10 @@ export class MCPManager {
 		}
 
 		if (connectionTasks.length > 0) {
-			const startupTimeoutMs = resolveStartupTimeoutMs(connectionTasks.map(task => task.config));
+			const startupTimeoutMs = resolveStartupTimeoutMs(
+				connectionTasks.map(task => task.config),
+				this.#maxStartupTimeoutMs,
+			);
 			const firstUnexpectedFailure = Promise.withResolvers<{ reason: unknown }>();
 			if (this.#toolsOnly) {
 				for (const task of connectionTasks) {

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

@@ -2,9 +2,18 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent, logger } from "@gajae-code/utils";
 import { getAgentDir } from "@gajae-code/utils/dirs";
+import { $credentialEnv } from "@gajae-code/utils/env";
 
 const SMITHERY_AUTH_FILENAME = "smithery.json";
-const SMITHERY_URL = process.env.SMITHERY_URL || "https://smithery.ai";
+/**
+ * Smithery web origin, from trusted environment sources only.
+ *
+ * This origin serves the CLI auth session and the verification URL the user is
+ * sent to, so whatever can set it can drive the login flow. `$env` merges the
+ * caller's `cwd/.env` into `process.env`, so reading it there would let
+ * repository content redirect that flow.
+ */
+const SMITHERY_URL = $credentialEnv("SMITHERY_URL") || "https://smithery.ai";
 
 type SmitheryCliAuthSession = {
 	sessionId: string;
@@ -31,6 +40,11 @@ function normalizeApiKey(value: string | undefined): string | undefined {
 	return trimmed.length > 0 ? trimmed : undefined;
 }
 
+/** Test seam: the Smithery origin and env API key as resolved from trusted env. */
+export function resolveSmitheryEnvForTest(): { url: string; apiKey: string | undefined } {
+	return { url: SMITHERY_URL, apiKey: normalizeApiKey($credentialEnv("SMITHERY_API_KEY")) };
+}
+
 export function getSmitheryLoginUrl(): string {
 	return SMITHERY_URL;
 }
@@ -62,7 +76,8 @@ export async function pollSmitheryCliAuthSession(
 }
 
 export async function getSmitheryApiKey(): Promise<string | undefined> {
-	const envKey = normalizeApiKey(process.env.SMITHERY_API_KEY);
+	// Trusted sources only: this key authenticates every Smithery API call.
+	const envKey = normalizeApiKey($credentialEnv("SMITHERY_API_KEY"));
 	if (envKey) return envKey;
 
 	const authPath = getSmitheryAuthPath();

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

@@ -1,4 +1,14 @@
-const SMITHERY_API_BASE_URL = (process.env.SMITHERY_API_URL || "https://api.smithery.ai").replace(/\/+$/, "");
+import { $credentialEnv } from "@gajae-code/utils/env";
+
+/**
+ * Smithery API base, from trusted environment sources only.
+ *
+ * Every request to this base carries `Authorization: Bearer <apiKey>` and the
+ * `/connect` routes return the connection records the agent consumes, so
+ * whatever can set it receives the key and supplies those records. `$env` merges
+ * the caller's `cwd/.env` into `process.env`.
+ */
+const SMITHERY_API_BASE_URL = ($credentialEnv("SMITHERY_API_URL") || "https://api.smithery.ai").replace(/\/+$/, "");
 
 export class SmitheryConnectError extends Error {
 	status: number;

package/src/sdk/acp/adapter.ts

@@ -179,7 +179,14 @@ export class AcpSdkAdapter {
 		this.#assertGenericDisposition("global", operation);
 		if (isLifecycleOperation(operation) && !idempotencyKey)
 			throw new AcpSdkAdapterError("invalid_input", "idempotencyKey is required for lifecycle operations.");
-		return await this.#client.global(operation, input, { idempotencyKey });
+		const readinessTimeoutMs =
+			typeof input.readinessTimeoutMs === "number" && Number.isSafeInteger(input.readinessTimeoutMs)
+				? input.readinessTimeoutMs
+				: undefined;
+		return await this.#client.global(operation, input, {
+			idempotencyKey,
+			...(readinessTimeoutMs ? { timeoutMs: readinessTimeoutMs + 1_000 } : {}),
+		});
 	}
 
 	async sdkControl(params: { operation: string; input?: JsonObject }): Promise<unknown> {

package/src/sdk/acp/final-text.ts

@@ -0,0 +1,40 @@
+export const ACP_FINAL_TEXT_LIMIT = 100_000;
+
+export interface BoundedAcpFinalText {
+	text: string;
+	truncated: boolean;
+}
+
+export type AcpFinalTextResolution =
+	| { kind: "none"; final: BoundedAcpFinalText }
+	| { kind: "emit"; final: BoundedAcpFinalText; text: string }
+	| { kind: "divergent"; final: BoundedAcpFinalText };
+
+export function boundAcpFinalText(value: string): BoundedAcpFinalText {
+	if (value.length <= ACP_FINAL_TEXT_LIMIT) return { text: value, truncated: false };
+	let text = value.slice(0, ACP_FINAL_TEXT_LIMIT);
+	const finalCodeUnit = text.charCodeAt(text.length - 1);
+	if (finalCodeUnit >= 0xd800 && finalCodeUnit <= 0xdbff) text = text.slice(0, -1);
+	return { text, truncated: true };
+}
+
+export function acpFinalTextFromMessage(message: unknown): BoundedAcpFinalText {
+	const content = (message as { content?: unknown } | null | undefined)?.content;
+	if (typeof content === "string") return boundAcpFinalText(content);
+	if (!Array.isArray(content)) return { text: "", truncated: false };
+	const parts: string[] = [];
+	for (const block of content) {
+		if (!block || typeof block !== "object" || (block as { type?: unknown }).type !== "text") continue;
+		const text = (block as { text?: unknown }).text;
+		if (typeof text === "string") parts.push(text);
+	}
+	return boundAcpFinalText(parts.join(""));
+}
+
+export function resolveAcpFinalText(streamed: string, finalText: string): AcpFinalTextResolution {
+	const final = boundAcpFinalText(finalText);
+	if (!final.text || streamed === final.text || streamed.includes(final.text)) return { kind: "none", final };
+	if (!streamed) return { kind: "emit", final, text: final.text };
+	if (final.text.startsWith(streamed)) return { kind: "emit", final, text: final.text.slice(streamed.length) };
+	return { kind: "divergent", final };
+}

package/src/sdk/acp/mcp.ts

@@ -0,0 +1,26 @@
+export const ACP_MCP_REQUEST_TIMEOUT_MS = 30_000;
+export const ACP_MCP_LIFECYCLE_TIMEOUT_MS = ACP_MCP_REQUEST_TIMEOUT_MS + 500;
+/**
+ * Slice of the readiness budget reserved for the work that follows MCP startup
+ * (session wiring, marker publication). The ACP MCP startup ceiling is the
+ * remaining time to `semanticReadyDeadlineAt` minus this headroom, so a slow
+ * MCP handshake cannot consume the whole readiness window.
+ */
+export const ACP_MCP_STARTUP_HEADROOM_MS = 250;
+
+export interface SessionLifecycleMcpStdioServer {
+	type?: "stdio";
+	name: string;
+	command: string;
+	args: string[];
+	env?: Record<string, string>;
+}
+
+export interface SessionLifecycleMcpRemoteServer {
+	type: "http" | "sse";
+	name: string;
+	url: string;
+	headers?: Record<string, string>;
+}
+
+export type SessionLifecycleMcpServer = SessionLifecycleMcpStdioServer | SessionLifecycleMcpRemoteServer;

package/src/sdk/broker/lifecycle.ts

@@ -5,7 +5,7 @@ import * as fs from "node:fs/promises";
 import path from "node:path";
 import type { NativeExactUnlinkResult } from "@gajae-code/natives";
 import * as native from "@gajae-code/natives";
-import { resolveEquivalentPath } from "@gajae-code/utils";
+import { $credentialEnv, resolveEquivalentPath } from "@gajae-code/utils";
 
 import {
 	isModelProfileError,
@@ -29,6 +29,7 @@ import {
 	type VerifiedSessionDeleteResult,
 	type VerifiedSessionDeleteTarget,
 } from "../../session/session-storage";
+import type { SessionLifecycleMcpServer } from "../acp/mcp";
 import { SdkClient, SdkClientError } from "../client/client";
 import {
 	type LogicalSessionCandidate,
@@ -215,6 +216,7 @@ export interface SessionLifecycleLaunchRequest {
 	/** Broker-issued effect marker which the child echoes only after host readiness. */
 	effectMarker?: string;
 	modelPreset?: string;
+	mcpServers?: SessionLifecycleMcpServer[];
 	worktree?: SessionLifecycleWorktreeTarget;
 	receivedAt: number;
 	requestedReadinessTimeoutMs: number;
@@ -248,6 +250,77 @@ function hasValidTranscriptAuthority(path: unknown, identity: unknown): path is
 	return typeof path === "string" && path.length > 0 && isSessionLifecycleTranscriptIdentity(identity);
 }
 
+function isSessionLifecycleMcpServer(value: unknown): value is SessionLifecycleMcpServer {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const server = value as Record<string, unknown>;
+	if (server.type === "http" || server.type === "sse") {
+		if (
+			!Object.keys(server).every(key => key === "type" || key === "name" || key === "url" || key === "headers") ||
+			typeof server.name !== "string" ||
+			!/^[A-Za-z0-9_.-]{1,100}$/.test(server.name) ||
+			typeof server.url !== "string" ||
+			server.url.length > 8_192
+		)
+			return false;
+		try {
+			const url = new URL(server.url);
+			if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+		} catch {
+			return false;
+		}
+		if (server.headers === undefined) return true;
+		if (typeof server.headers !== "object" || server.headers === null || Array.isArray(server.headers)) return false;
+		const headers = server.headers as Record<string, unknown>;
+		return (
+			Object.keys(headers).length <= 100 &&
+			Object.entries(headers).every(
+				([name, headerValue]) =>
+					name.length > 0 &&
+					name.length <= 256 &&
+					!name.includes("\r") &&
+					!name.includes("\n") &&
+					typeof headerValue === "string" &&
+					headerValue.length <= 8_192 &&
+					!headerValue.includes("\r") &&
+					!headerValue.includes("\n"),
+			)
+		);
+	}
+	const env = server.env;
+	return (
+		Object.keys(server).every(
+			key => key === "type" || key === "name" || key === "command" || key === "args" || key === "env",
+		) &&
+		(server.type === undefined || server.type === "stdio") &&
+		typeof server.name === "string" &&
+		/^[A-Za-z0-9_.-]{1,100}$/.test(server.name) &&
+		typeof server.command === "string" &&
+		server.command.length <= 4_096 &&
+		path.isAbsolute(server.command) &&
+		Array.isArray(server.args) &&
+		server.args.length <= 100 &&
+		server.args.every(argument => typeof argument === "string" && argument.length <= 8_192) &&
+		(env === undefined ||
+			(typeof env === "object" &&
+				env !== null &&
+				!Array.isArray(env) &&
+				Object.keys(env).length <= 100 &&
+				Object.entries(env).every(
+					([name, envValue]) =>
+						/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && typeof envValue === "string" && envValue.length <= 32_768,
+				)))
+	);
+}
+
+function isSessionLifecycleMcpServers(value: unknown): value is SessionLifecycleMcpServer[] {
+	return (
+		Array.isArray(value) &&
+		value.length <= 64 &&
+		value.every(isSessionLifecycleMcpServer) &&
+		new Set(value.map(server => server.name)).size === value.length
+	);
+}
+
 export function readSessionLifecycleLaunchRequest(
 	value: string | undefined,
 	now = Date.now(),
@@ -278,6 +351,7 @@ export function readSessionLifecycleLaunchRequest(
 		(request.effectMarker !== undefined &&
 			(typeof request.effectMarker !== "string" || !/^[A-Za-z0-9._-]{1,128}$/.test(request.effectMarker))) ||
 		(request.modelPreset !== undefined && (typeof request.modelPreset !== "string" || !request.modelPreset)) ||
+		(request.mcpServers !== undefined && !isSessionLifecycleMcpServers(request.mcpServers)) ||
 		!hasValidLifecycleDeadlines(
 			{
 				receivedAt: request.receivedAt as number,
@@ -310,6 +384,7 @@ type SessionLaunch = {
 	sessionPath?: string;
 	sessionIdentity?: SessionLifecycleTranscriptIdentity;
 	modelPreset?: string;
+	mcpServers?: SessionLifecycleMcpServer[];
 	worktree?: SessionLifecycleWorktreeTarget;
 	worktreePlan?: GjcLaunchWorktreePlan;
 };
@@ -631,12 +706,31 @@ async function reconcileReadyScope(broker: Broker, id: string, scope: string | u
 	});
 }
 
+/**
+ * Operator override for the session-host command, resolved from trusted
+ * environment sources only.
+ *
+ * The result is spawned directly, so whatever can set it chooses which binary
+ * the broker runs. `$env` merges the caller's `cwd/.env` into `process.env`, so
+ * reading it there would let repository content replace the session host;
+ * resolve it the same way provider credentials are (launching shell plus
+ * GJC/user-owned `.env` files, never the project `.env`).
+ */
+function sdkSessionCommandOverride(): { file: string; args: string[] } | undefined {
+	const configured = $credentialEnv("GJC_SDK_SESSION_COMMAND");
+	if (!configured) return undefined;
+	const [file, ...args] = configured.trim().split(/\s+/);
+	return file ? { file, args } : undefined;
+}
+
+/** Test seam: the session-host command override as resolved from trusted env. */
+export function sdkSessionCommandOverrideForTest(): { file: string; args: string[] } | undefined {
+	return sdkSessionCommandOverride();
+}
+
 function command(broker: Broker): LifecycleCommand {
-	const configured = process.env.GJC_SDK_SESSION_COMMAND;
-	if (configured) {
-		const [file, ...args] = configured.trim().split(/\s+/);
-		if (file) return { file, args };
-	}
+	const configured = sdkSessionCommandOverride();
+	if (configured) return configured;
 	return lifecycleCommandResolversForTest.get(broker)?.() ?? resolveSdkInternalSpawnCommand("session-host-internal");
 }
 
@@ -2299,9 +2393,12 @@ async function launchInput(
 	if (input.modelPreset !== undefined && (typeof input.modelPreset !== "string" || input.modelPreset.length === 0))
 		return fail("invalid_input", "modelPreset must be a non-empty exact profile ID.");
 	const modelPreset = text(input.modelPreset);
+	if (input.mcpServers !== undefined && !isSessionLifecycleMcpServers(input.mcpServers))
+		return fail("invalid_input", "mcpServers must contain unique valid stdio, HTTP, or SSE server definitions.");
+	const mcpServers = input.mcpServers as SessionLifecycleMcpServer[] | undefined;
 
 	if (operation === "session.create")
-		return { id: randomUUID(), cwd, root: resolvedRoot, modelPreset, worktree, worktreePlan };
+		return { id: randomUUID(), cwd, root: resolvedRoot, modelPreset, mcpServers, worktree, worktreePlan };
 	if (operation === "session.resume") {
 		if (!requested) return fail("invalid_input", "sessionId is required to resume a saved session.");
 		const savedPath = text(input.sessionPath);
@@ -2315,6 +2412,7 @@ async function launchInput(
 			sessionPath: saved.path,
 			sessionIdentity: saved.identity,
 			modelPreset,
+			mcpServers,
 			worktree,
 			worktreePlan,
 		};
@@ -2336,6 +2434,7 @@ async function launchInput(
 		sourceSessionIdentity: source.identity,
 		sourceCwd,
 		modelPreset,
+		mcpServers,
 		worktree,
 		worktreePlan,
 	};
@@ -2805,6 +2904,7 @@ async function executeLifecycleResponse(
 			...(launch.sessionPath ? { sessionPath: launch.sessionPath } : {}),
 			...(launch.sessionIdentity ? { sessionIdentity: launch.sessionIdentity } : {}),
 			...(launch.modelPreset ? { modelPreset: launch.modelPreset } : {}),
+			...(launch.mcpServers ? { mcpServers: launch.mcpServers } : {}),
 			...(launch.worktree ? { worktree: launch.worktree } : {}),
 		};
 		let child: ChildProcess | undefined;

package/src/sdk/bus/chat-daemon-cli.ts

@@ -67,7 +67,7 @@ async function loadConfig(agentDir: string, kind: ChatDaemonKind): Promise<ChatD
 				idleTimeoutMs: 60_000,
 				rich: { enabled: true },
 				richDraft: { enabled: false },
-				toolActivity: { enabled: true },
+				toolActivity: { enabled: false },
 				topics: { nameTemplate: undefined },
 				btw: { enabled: true },
 				streaming: { enabled: true },
@@ -102,7 +102,7 @@ async function loadConfig(agentDir: string, kind: ChatDaemonKind): Promise<ChatD
 			idleTimeoutMs: 60_000,
 			rich: { enabled: true },
 			richDraft: { enabled: false },
-			toolActivity: { enabled: true },
+			toolActivity: { enabled: false },
 			topics: { nameTemplate: undefined },
 			btw: { enabled: true },
 			streaming: { enabled: true },

package/src/sdk/bus/chat-daemon-control.ts

@@ -34,11 +34,12 @@ export type ChatDaemonAction = "stop" | "reload";
  * concrete detached quarantine plus a proven-absent canonical lock pathname —
  * when deleting an observed owner-lock lease. Generation 12 refreshes retained
  * native path and process authority semantics. Generation 13 rejects special
- * files before retained native authority opens.
+ * files before retained native authority opens. Generation 14 reloads shared
+ * chat daemons after notification configuration parsing changes.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 13,
-	slack: 13,
+	discord: 14,
+	slack: 14,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

package/src/sdk/bus/config.ts

@@ -170,7 +170,7 @@ export function parseNotificationSettingsSnapshot(rawConfig?: unknown): Notifica
 				enabled: notificationSettingsBoolean(richDraft.enabled, false),
 			},
 			toolActivity: {
-				enabled: notificationSettingsBoolean(toolActivity.enabled, true),
+				enabled: notificationSettingsBoolean(toolActivity.enabled, false),
 			},
 			streaming: {
 				enabled: notificationSettingsBoolean(streaming.enabled, true),

package/src/sdk/bus/control-drain-lease.ts

@@ -0,0 +1,104 @@
+/**
+ * Ordering seam for an in-band SDK identity transition.
+ *
+ * A request arrives through predecessor A, so a successful terminal response cannot
+ * be published until successor B is ready. Native builds may provide a true
+ * send-only connection lease; source/dev builds use the conservative fallback in
+ * which the predecessor server remains alive until the terminal write completes.
+ */
+
+export type TerminalSendOutcome = "written" | "disconnected" | "write_failed";
+
+/** Fence/capability hooks may return false to reject; undefined means ok. */
+export type IdentityControlGateResult = boolean | undefined;
+export type IdentityControlGate = () => IdentityControlGateResult | Promise<IdentityControlGateResult>;
+
+export interface IdentityControlSuccessPathInput {
+	/** Fence predecessor inbound work. The fence must not close its response writer. */
+	fence: IdentityControlGate;
+	/** Optional explicit proof that the predecessor writer is still usable. */
+	ensurePredecessorSendCapable?: IdentityControlGate;
+	/** Start successor B and resolve only after its public endpoint is ready. */
+	startSuccessor: () => Promise<void>;
+	/** Write and flush either the success or non-success terminal response. */
+	sendTerminal: () => Promise<TerminalSendOutcome>;
+	/** Release predecessor A after the terminal response has settled. */
+	stopPredecessor: () => Promise<void>;
+	/** Set only when a caller cannot use the retained-writer fallback. */
+	requireNativeControlDrain?: boolean;
+}
+
+export interface IdentityControlTerminalPathInput {
+	fenceInbound: IdentityControlGate;
+	ensurePredecessorSendCapable?: IdentityControlGate;
+	startSuccessorReady: () => Promise<void>;
+	sendTerminal: () => Promise<TerminalSendOutcome>;
+	stopPredecessor: () => Promise<void>;
+	requireNativeControlDrain?: boolean;
+}
+
+/**
+ * Probe the loaded native addon, never an environment flag or a TypeScript shim.
+ * Older/source installs intentionally report false so callers can select the
+ * retained-writer fallback or fail closed when detach is mandatory.
+ */
+export function isNativeControlDrainAvailable(): boolean {
+	try {
+		// Keep the addon lazy: importing the bus must continue to work without a
+		// compiled native artifact (tests and source distributions do that often).
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const natives = require("@gajae-code/natives") as {
+			NotificationServer?: {
+				prototype?: Record<string, unknown>;
+			};
+		};
+		const prototype = natives.NotificationServer?.prototype;
+		return (
+			typeof prototype?.acquireControlDrain === "function" &&
+			typeof prototype?.sendTerminalAndWait === "function" &&
+			typeof prototype?.closeControlDrain === "function"
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Run the only safe ordering for a successful identity-control response.
+ *
+ * The `finally` is deliberately around both successor startup and terminal
+ * delivery: a failed startup must not leave the fenced predecessor alive, and a
+ * failed/disconnected terminal write must still release it. When native detach
+ * is unavailable the caller is expected to keep A's server up (not call
+ * `stopAndWait`) until `sendTerminal` settles.
+ */
+export async function runIdentityControlSuccessPath(
+	input: IdentityControlSuccessPathInput,
+): Promise<TerminalSendOutcome> {
+	if (input.requireNativeControlDrain && !isNativeControlDrainAvailable())
+		throw new Error("SDK identity control requires the native control-drain lease.");
+
+	if ((await input.fence()) === false) throw new Error("SDK identity control predecessor fence was not acquired.");
+	if ((await input.ensurePredecessorSendCapable?.()) === false)
+		throw new Error("SDK identity control predecessor writer is not send-capable.");
+	try {
+		await input.startSuccessor();
+		return await input.sendTerminal();
+	} finally {
+		await input.stopPredecessor();
+	}
+}
+
+/** Compatibility spelling used by the host wiring design notes. */
+export async function runIdentityControlTerminalPath(
+	input: IdentityControlTerminalPathInput,
+): Promise<TerminalSendOutcome> {
+	return runIdentityControlSuccessPath({
+		fence: input.fenceInbound,
+		ensurePredecessorSendCapable: input.ensurePredecessorSendCapable,
+		startSuccessor: input.startSuccessorReady,
+		sendTerminal: input.sendTerminal,
+		stopPredecessor: input.stopPredecessor,
+		requireNativeControlDrain: input.requireNativeControlDrain,
+	});
+}