@gajae-code/coding-agent 0.11.9 → 0.11.11

package/src/runtime/memory-guard.ts

@@ -0,0 +1,292 @@
+import type { Settings } from "../config/settings";
+import type {
+	MemoryGuardActionTarget,
+	MemoryGuardDecision,
+	MemoryGuardDomainSnapshot,
+	MemoryGuardPolicy,
+	MemoryGuardSchedulerState,
+} from "./memory-guard-contract";
+
+const BYTES_PER_MB = 1024 * 1024;
+const DEFAULT_CHECK_INTERVAL_MS = 30_000;
+
+type ScheduleOwner = { generation: number; token: number };
+type DeferredSchedule = { generation: number; deadline: number };
+type WorkOwner = { generation: number; source: "timer" | "external" };
+
+export interface MemoryGuardHostRegistration {
+	ownerId: string;
+	intervalMs: number;
+}
+
+export interface MemoryGuardHostOptions {
+	run: () => Promise<void>;
+	logDebug?: (message: string, meta?: Record<string, unknown>) => void;
+	schedulerNow?: () => number;
+}
+
+function normalizePositiveIntervalMs(intervalMs: number): number {
+	if (!Number.isFinite(intervalMs) || intervalMs <= 0) throw new Error("invalid_interval_ms");
+	return intervalMs;
+}
+
+function toRatio(percent: number): number {
+	return percent / 100;
+}
+
+function mbToBytes(value: number): number {
+	return Math.round(value * BYTES_PER_MB);
+}
+
+function sortTargets(left: MemoryGuardActionTarget, right: MemoryGuardActionTarget): number {
+	if (left.excessBytes !== right.excessBytes) return right.excessBytes - left.excessBytes;
+	if (left.kind !== right.kind) return left.kind === "host" ? -1 : 1;
+	if (left.kind === "worker" && right.kind === "worker") return left.workerId.localeCompare(right.workerId);
+	return 0;
+}
+
+export function resolveMemoryGuardPolicy(settings: Settings): MemoryGuardPolicy {
+	const configuredPolicyLimitMb = settings.get("memoryGuard.policyLimitMb");
+	return {
+		enabled: settings.get("memoryGuard.enabled"),
+		checkIntervalMs: settings.get("memoryGuard.checkIntervalMs"),
+		gcThresholdRatio: toRatio(settings.get("memoryGuard.gcThresholdPercent")),
+		restartThresholdRatio: toRatio(settings.get("memoryGuard.restartThresholdPercent")),
+		restartThresholdWindowMs: settings.get("memoryGuard.restartThresholdWindowMs"),
+		cooldownMs: settings.get("memoryGuard.cooldownMs"),
+		parentReserveBytes: mbToBytes(settings.get("memoryGuard.parentReserveMb")),
+		policyLimitBytes: configuredPolicyLimitMb > 0 ? mbToBytes(configuredPolicyLimitMb) : null,
+	};
+}
+
+export function chooseMemoryGuardAction(input: {
+	domain: MemoryGuardDomainSnapshot;
+	hostSupported: boolean;
+	workerSupported: (workerId: string) => boolean;
+}): MemoryGuardDecision {
+	const candidates: MemoryGuardActionTarget[] = [];
+	if (input.hostSupported && input.domain.hostExcessBytes > 0) {
+		candidates.push({ kind: "host", excessBytes: input.domain.hostExcessBytes });
+	}
+	for (const worker of input.domain.workers) {
+		if (!worker.accepted || worker.excessBytes <= 0 || !input.workerSupported(worker.workerId)) continue;
+		candidates.push({ kind: "worker", workerId: worker.workerId, excessBytes: worker.excessBytes });
+	}
+	if (candidates.length > 0) {
+		candidates.sort(sortTargets);
+		return { kind: "execute", target: candidates[0]! };
+	}
+	const unsupportedExcessExists =
+		input.domain.hostExcessBytes > 0 ||
+		input.domain.workers.some(worker => worker.accepted && worker.excessBytes > 0);
+	if (unsupportedExcessExists) return { kind: "noop", reason: "memory_guard_action_noop_unsupported" };
+	return { kind: "noop", reason: "memory_guard_action_noop_unmanaged_or_within_allowance" };
+}
+
+export function revalidateMemoryGuardAction(
+	previous: Extract<MemoryGuardDecision, { kind: "execute" }>,
+	revalidated: MemoryGuardDecision,
+): MemoryGuardDecision {
+	if (revalidated.kind !== "execute")
+		return { kind: "revalidated_out", reason: "memory_guard_action_revalidated_out" };
+	if (previous.target.kind !== revalidated.target.kind)
+		return { kind: "revalidated_out", reason: "memory_guard_action_revalidated_out" };
+	if (
+		previous.target.kind === "worker" &&
+		revalidated.target.kind === "worker" &&
+		previous.target.workerId !== revalidated.target.workerId
+	) {
+		return { kind: "revalidated_out", reason: "memory_guard_action_revalidated_out" };
+	}
+	return revalidated;
+}
+
+export class MemoryGuardHost {
+	#run: () => Promise<void>;
+	#logDebug: (message: string, meta?: Record<string, unknown>) => void;
+	#defaultSchedulerNow: () => number;
+	#schedulerNow: () => number;
+	#registrations = new Map<string, { intervalMs: number; nextDueMs: number }>();
+	#pendingTimer: NodeJS.Timeout | null = null;
+	#pendingDeadline: number | null = null;
+	#pendingOwner: ScheduleOwner | null = null;
+	#deferredSchedule: DeferredSchedule | null = null;
+	#inProgressOwner: WorkOwner | null = null;
+	#stopped = false;
+	#generation = 0;
+	#nextTimerToken = 0;
+
+	constructor(options: MemoryGuardHostOptions) {
+		this.#run = options.run;
+		this.#logDebug = options.logDebug ?? (() => undefined);
+		this.#defaultSchedulerNow = options.schedulerNow ?? (() => performance.now());
+		this.#schedulerNow = this.#defaultSchedulerNow;
+	}
+
+	register(registration: MemoryGuardHostRegistration): () => void {
+		const intervalMs = normalizePositiveIntervalMs(registration.intervalMs);
+		const now = this.#schedulerNow();
+		const existing = this.#registrations.get(registration.ownerId);
+		const isNewRegistration = !existing;
+		const nextDueMs = existing ? Math.min(existing.nextDueMs, now + intervalMs) : now + intervalMs;
+		this.#registrations.set(registration.ownerId, { intervalMs, nextDueMs });
+		this.#stopped = false;
+		if (isNewRegistration) {
+			const deadline = nextDueMs;
+			if (
+				this.#inProgressOwner?.generation === this.#generation &&
+				(this.#pendingDeadline === null || this.#pendingDeadline <= deadline)
+			) {
+				this.#deferSchedule(this.#generation, deadline);
+			} else {
+				this.#requestSchedule(deadline);
+			}
+		}
+		let unregistered = false;
+		return () => {
+			if (unregistered) return;
+			unregistered = true;
+			this.#registrations.delete(registration.ownerId);
+			if (this.#registrations.size === 0) this.#stop();
+		};
+	}
+
+	updateInterval(ownerId: string, intervalMs: number): void {
+		const existing = this.#registrations.get(ownerId);
+		if (!existing) return;
+		const normalized = normalizePositiveIntervalMs(intervalMs);
+		if (existing.intervalMs === normalized) return;
+		const now = this.#schedulerNow();
+		const nextDueMs = now + normalized;
+		this.#registrations.set(ownerId, { intervalMs: normalized, nextDueMs });
+		if (this.#inProgressOwner) return;
+		const nextDeadline = this.#nextDeadlineMs();
+		if (this.#pendingDeadline !== null && nextDeadline > this.#pendingDeadline) {
+			this.#clearPendingSchedule();
+		}
+		this.#requestSchedule(nextDeadline);
+	}
+
+	async runTick(generation = this.#generation, source: WorkOwner["source"] = "external"): Promise<void> {
+		if (this.#inProgressOwner || this.#registrations.size === 0) return;
+		const owner: WorkOwner = { generation, source };
+		this.#inProgressOwner = owner;
+		try {
+			await this.#run();
+		} catch (error) {
+			this.#logDebug("memory guard tick failed", { error: error instanceof Error ? error.message : String(error) });
+		} finally {
+			if (this.#inProgressOwner === owner) this.#inProgressOwner = null;
+			this.#advanceDueTimes();
+			this.#reconcileCurrentSchedule();
+		}
+	}
+
+	async runTimerCallbackForTest(owner: { generation: number; token: number }, deadline: number): Promise<void> {
+		await this.#handleTimerCallback(owner, deadline);
+	}
+
+	setSchedulerNowForTest(now: () => number): void {
+		this.#schedulerNow = now;
+	}
+
+	getStateForTest(): MemoryGuardSchedulerState {
+		return {
+			timerActive: this.#pendingTimer !== null,
+			registrationCount: this.#registrations.size,
+			inProgress: this.#inProgressOwner !== null,
+			generation: this.#generation,
+			pendingDeadline: this.#pendingDeadline,
+			pendingOwner: this.#pendingOwner ? { ...this.#pendingOwner } : null,
+			deferredDeadline: this.#deferredSchedule?.deadline ?? null,
+			deferredGeneration: this.#deferredSchedule?.generation ?? null,
+			activeGeneration: this.#inProgressOwner?.generation ?? null,
+		};
+	}
+
+	resetForTest(): void {
+		this.#stop();
+		this.#registrations.clear();
+		this.#inProgressOwner = null;
+		this.#deferredSchedule = null;
+		this.#nextTimerToken = 0;
+		this.#schedulerNow = this.#defaultSchedulerNow;
+	}
+
+	#nextDeadlineMs(): number {
+		let minDue = Number.POSITIVE_INFINITY;
+		for (const reg of this.#registrations.values()) {
+			minDue = Math.min(minDue, reg.nextDueMs);
+		}
+		return Number.isFinite(minDue) ? minDue : this.#schedulerNow() + DEFAULT_CHECK_INTERVAL_MS;
+	}
+
+	#advanceDueTimes(): void {
+		const now = this.#schedulerNow();
+		for (const reg of this.#registrations.values()) {
+			if (reg.nextDueMs <= now) {
+				reg.nextDueMs = now + reg.intervalMs;
+			}
+		}
+	}
+
+	#clearPendingSchedule(): void {
+		if (this.#pendingTimer) clearTimeout(this.#pendingTimer);
+		this.#pendingTimer = null;
+		this.#pendingDeadline = null;
+		this.#pendingOwner = null;
+	}
+
+	#requestSchedule(deadline: number): void {
+		if (this.#stopped || this.#registrations.size === 0) return;
+		if (this.#pendingDeadline !== null && this.#pendingDeadline <= deadline) return;
+		this.#clearPendingSchedule();
+		const owner = { generation: this.#generation, token: ++this.#nextTimerToken };
+		this.#pendingDeadline = deadline;
+		this.#pendingOwner = owner;
+		this.#pendingTimer = setTimeout(
+			() => {
+				void this.#handleTimerCallback(owner, deadline);
+			},
+			Math.max(0, deadline - this.#schedulerNow()),
+		);
+		this.#pendingTimer.unref?.();
+	}
+
+	#deferSchedule(generation: number, deadline: number): void {
+		if (generation !== this.#generation) return;
+		if (this.#deferredSchedule?.generation === generation) {
+			this.#deferredSchedule.deadline = Math.min(this.#deferredSchedule.deadline, deadline);
+			return;
+		}
+		this.#deferredSchedule = { generation, deadline };
+	}
+
+	async #handleTimerCallback(owner: ScheduleOwner, deadline: number): Promise<void> {
+		if (this.#pendingOwner?.generation !== owner.generation || this.#pendingOwner.token !== owner.token) return;
+		this.#pendingTimer = null;
+		this.#pendingDeadline = null;
+		this.#pendingOwner = null;
+		if (this.#inProgressOwner) {
+			this.#deferSchedule(owner.generation, deadline);
+			return;
+		}
+		await this.runTick(owner.generation, "timer");
+	}
+
+	#reconcileCurrentSchedule(): void {
+		if (this.#stopped || this.#registrations.size === 0 || this.#inProgressOwner) return;
+		const normalDeadline = this.#nextDeadlineMs();
+		const deferredDeadline =
+			this.#deferredSchedule?.generation === this.#generation ? this.#deferredSchedule.deadline : null;
+		if (deferredDeadline !== null) this.#deferredSchedule = null;
+		this.#requestSchedule(deferredDeadline === null ? normalDeadline : Math.min(deferredDeadline, normalDeadline));
+	}
+
+	#stop(): void {
+		this.#stopped = true;
+		this.#generation++;
+		this.#clearPendingSchedule();
+		this.#deferredSchedule = null;
+	}
+}

package/src/runtime/memory-limit.ts

@@ -0,0 +1,50 @@
+export interface EffectiveMemoryLimitInput {
+	hardCapBytes?: number | null;
+	policyLimitBytes?: number | null;
+}
+
+export interface EffectiveMemoryLimit {
+	hardCapBytes: number | null;
+	policyLimitBytes: number | null;
+	effectiveBytes: number | null;
+	source: "none" | "hard_cap" | "policy_limit" | "hard_cap_and_policy_limit";
+}
+
+function normalizePositiveByteCount(value: number | null | undefined): number | null {
+	return Number.isSafeInteger(value) && typeof value === "number" && value > 0 ? value : null;
+}
+
+export function resolveEffectiveMemoryLimit(input: EffectiveMemoryLimitInput): EffectiveMemoryLimit {
+	const hardCapBytes = normalizePositiveByteCount(input.hardCapBytes);
+	const policyLimitBytes = normalizePositiveByteCount(input.policyLimitBytes);
+	if (hardCapBytes !== null && policyLimitBytes !== null) {
+		return {
+			hardCapBytes,
+			policyLimitBytes,
+			effectiveBytes: Math.min(hardCapBytes, policyLimitBytes),
+			source: "hard_cap_and_policy_limit",
+		};
+	}
+	if (hardCapBytes !== null) {
+		return {
+			hardCapBytes,
+			policyLimitBytes: null,
+			effectiveBytes: hardCapBytes,
+			source: "hard_cap",
+		};
+	}
+	if (policyLimitBytes !== null) {
+		return {
+			hardCapBytes: null,
+			policyLimitBytes,
+			effectiveBytes: policyLimitBytes,
+			source: "policy_limit",
+		};
+	}
+	return {
+		hardCapBytes: null,
+		policyLimitBytes: null,
+		effectiveBytes: null,
+		source: "none",
+	};
+}

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/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/identity.ts

@@ -11,20 +11,30 @@ export function brokerIdentityPath(agentDir: string): string {
 export async function getBrokerIdentityKey(agentDir: string): Promise<string> {
 	const file = brokerIdentityPath(agentDir);
 	await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
-	try {
-		const key = (await fs.readFile(file, "utf8")).trim();
-		if (/^[0-9a-f]{64}$/i.test(key)) return key;
-		throw new Error(`Invalid broker identity key at ${file}`);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	while (true) {
+		try {
+			const key = (await fs.readFile(file, "utf8")).trim();
+			if (/^[0-9a-f]{64}$/i.test(key)) return key;
+			throw new Error(`Invalid broker identity key at ${file}`);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+
 		const key = randomBytes(32).toString("hex");
+		const temporary = path.join(path.dirname(file), `.broker.identity-${randomBytes(16).toString("hex")}`);
 		try {
-			await fs.writeFile(file, `${key}\n`, { encoding: "utf8", mode: MODE, flag: "wx" });
-			await fs.chmod(file, MODE);
-			return key;
-		} catch (writeError) {
-			if ((writeError as NodeJS.ErrnoException).code !== "EEXIST") throw writeError;
-			return getBrokerIdentityKey(agentDir);
+			await fs.writeFile(temporary, `${key}\n`, { encoding: "utf8", mode: MODE, flag: "wx" });
+			await fs.chmod(temporary, MODE);
+			try {
+				// Link publishes a fully written key without exposing a partial target.
+				// Same-directory hard-link support is required (standard on Linux, macOS, and Windows NTFS).
+				await fs.link(temporary, file);
+				return key;
+			} catch (linkError) {
+				if ((linkError as NodeJS.ErrnoException).code !== "EEXIST") throw linkError;
+			}
+		} finally {
+			await fs.rm(temporary, { force: true });
 		}
 	}
 }

package/src/sdk/broker/lifecycle.ts

@@ -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;
 };
@@ -2299,9 +2374,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 +2393,7 @@ async function launchInput(
 			sessionPath: saved.path,
 			sessionIdentity: saved.identity,
 			modelPreset,
+			mcpServers,
 			worktree,
 			worktreePlan,
 		};
@@ -2336,6 +2415,7 @@ async function launchInput(
 		sourceSessionIdentity: source.identity,
 		sourceCwd,
 		modelPreset,
+		mcpServers,
 		worktree,
 		worktreePlan,
 	};
@@ -2805,6 +2885,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;