@gajae-code/coding-agent 0.18.1 → 0.18.6

package/src/sdk/broker/lifecycle-ledger.ts

@@ -74,6 +74,8 @@ export interface LifecycleDurableEffectsReceipt {
 export interface LifecycleLedgerEntry {
 	operationKey?: string;
 	fingerprint?: string;
+	/** True only when a session.close request supplied immutable generation authority. */
+	closeAuthorityBound?: boolean;
 	version: typeof SDK_STATE_VERSION;
 	identity: string;
 	requestHash: string;
@@ -213,6 +215,20 @@ function pendingCleanupSessionId(response: unknown): string | undefined {
 	return canonicalCleanupSessionId(cleanup?.sessionId) ? cleanup.sessionId : undefined;
 }
 
+function retirementCreateIdentity(response: unknown): string | undefined {
+	if (!response || typeof response !== "object") return undefined;
+	const error = (response as { error?: unknown }).error;
+	if (!error || typeof error !== "object") return undefined;
+	const cleanup = (error as { cleanup?: unknown }).cleanup;
+	if (!cleanup || typeof cleanup !== "object") return undefined;
+	const receipt = (cleanup as { uncertainRetirement?: unknown }).uncertainRetirement;
+	if (!receipt || typeof receipt !== "object") return undefined;
+	const identity = (receipt as { identity?: unknown }).identity;
+	if (!identity || typeof identity !== "object") return undefined;
+	const createIdentity = (identity as { createIdentity?: unknown }).createIdentity;
+	return typeof createIdentity === "string" && createIdentity.length > 0 ? createIdentity : undefined;
+}
+
 function hasValidTerminalDigests(entry: LifecycleLedgerEntry): boolean {
 	const response = entry.response as { ok?: unknown; error?: { code?: unknown; cleanup?: unknown } } | undefined;
 	const cleanupPendingResponse =
@@ -646,23 +662,91 @@ export class LifecycleLedger {
 			await directory.close();
 		}
 	}
-	async #compact(replacement?: LifecycleLedgerEntry): Promise<boolean> {
+	async #compact(
+		replacement?: LifecycleLedgerEntry,
+		incoming?: { readonly bytes: number; readonly rows: number },
+	): Promise<boolean> {
 		const anchors = new Map<string, LifecycleLedgerEntry>();
 		for (const entry of this.#entries) {
 			const latest = replacement?.identity === entry.identity ? replacement : this.#byIdentity.get(entry.identity);
 			if (entry.state === "accepted" && !anchors.has(entry.identity) && entry.requestHash === latest?.requestHash)
 				anchors.set(entry.identity, entry);
 		}
-		const snapshot: LifecycleLedgerEntry[] = [];
 		const compacted = new Map(this.#byIdentity);
 		if (replacement) compacted.set(replacement.identity, replacement);
-		for (const [identity, latest] of compacted) {
-			const anchor = anchors.get(identity);
-			if (!anchor) throw new Error("Lifecycle ledger compaction requires an accepted identity anchor.");
-			snapshot.push(replacement?.identity === identity && latest.state === "accepted" ? latest : anchor);
-			if (latest.state !== "accepted") snapshot.push(latest);
+		const buildSnapshot = (): LifecycleLedgerEntry[] => {
+			const next: LifecycleLedgerEntry[] = [];
+			for (const [identity, latest] of compacted) {
+				const anchor = anchors.get(identity);
+				if (!anchor) throw new Error("Lifecycle ledger compaction requires an accepted identity anchor.");
+				next.push(replacement?.identity === identity && latest.state === "accepted" ? latest : anchor);
+				if (latest.state !== "accepted") next.push(latest);
+			}
+			return next;
+		};
+		let snapshot = buildSnapshot();
+		let contents = Buffer.from(snapshot.map(entry => `${JSON.stringify(entry)}\n`).join(""));
+		const needsEviction = incoming
+			? snapshot.length + incoming.rows > this.#limits.maxRows ||
+				contents.length + incoming.bytes > this.#limits.maxBytes
+			: replacement === undefined
+				? snapshot.length >= this.#limits.maxRows || contents.length >= this.#limits.maxBytes
+				: snapshot.length > this.#limits.maxRows || contents.length > this.#limits.maxBytes;
+		if (needsEviction) {
+			const protectedCreateIdentities = new Set<string>();
+			for (const entry of compacted.values()) {
+				const createIdentity =
+					retirementCreateIdentity(entry.response) ?? retirementCreateIdentity(entry.unresolvedCleanupResponse);
+				if (createIdentity !== undefined) protectedCreateIdentities.add(createIdentity);
+			}
+			const evictable = [...compacted.values()]
+				.filter(
+					latest =>
+						latest.identity !== replacement?.identity &&
+						terminal(latest.state) &&
+						latest.operationKey !== undefined &&
+						latest.fingerprint !== undefined &&
+						(!latest.operationKey.startsWith("session.close\u0000") || latest.closeAuthorityBound === true) &&
+						!protectedCreateIdentities.has(latest.identity) &&
+						pendingCleanupSessionId(latest.response) === undefined &&
+						pendingCleanupSessionId(latest.unresolvedCleanupResponse) === undefined,
+				)
+				.sort((left, right) => left.ts - right.ts);
+			const rowsByIdentity = new Map<string, number>();
+			const bytesByIdentity = new Map<string, number>();
+			for (const entry of snapshot) {
+				rowsByIdentity.set(entry.identity, (rowsByIdentity.get(entry.identity) ?? 0) + 1);
+				bytesByIdentity.set(
+					entry.identity,
+					(bytesByIdentity.get(entry.identity) ?? 0) + Buffer.byteLength(`${JSON.stringify(entry)}\n`),
+				);
+			}
+			let remainingRows = snapshot.length;
+			let remainingBytes = contents.length;
+			const evicted = new Set<string>();
+			for (const latest of evictable) {
+				if (
+					remainingRows <= this.#limits.maxRows / 2 &&
+					remainingBytes <= this.#limits.maxBytes / 2 &&
+					remainingRows + (incoming?.rows ?? 0) <= this.#limits.maxRows &&
+					remainingBytes + (incoming?.bytes ?? 0) <= this.#limits.maxBytes
+				)
+					break;
+				evicted.add(latest.identity);
+				remainingRows -= rowsByIdentity.get(latest.identity) ?? 0;
+				remainingBytes -= bytesByIdentity.get(latest.identity) ?? 0;
+			}
+			for (const identity of evicted) compacted.delete(identity);
+			snapshot = buildSnapshot();
+			contents = Buffer.from(snapshot.map(entry => `${JSON.stringify(entry)}\n`).join(""));
+			// Replay is guaranteed only for identities retained in the compacted ledger.
 		}
-		const contents = Buffer.from(snapshot.map(entry => `${JSON.stringify(entry)}\n`).join(""));
+		if (
+			incoming &&
+			(snapshot.length + incoming.rows > this.#limits.maxRows ||
+				contents.length + incoming.bytes > this.#limits.maxBytes)
+		)
+			throw new Error("Lifecycle ledger append exceeds configured bounds.");
 		if (
 			snapshot.length > this.#limits.maxRows ||
 			contents.length > this.#limits.maxBytes ||
@@ -735,7 +819,7 @@ export class LifecycleLedger {
 	async migrateIdentity(
 		from: string,
 		to: string,
-		metadata: { operationKey: string; fingerprint: string },
+		metadata: { operationKey: string; fingerprint: string; closeAuthorityBound?: boolean },
 	): Promise<LifecycleLedgerEntry | undefined> {
 		return this.#mutate(async () => {
 			const existing = this.#byIdentity.get(to);
@@ -776,9 +860,12 @@ export class LifecycleLedger {
 		);
 		if (line.length - 1 > this.#limits.maxLineBytes)
 			throw new Error("Lifecycle ledger row exceeds the maximum byte length.");
+		if (line.length > this.#limits.maxBytes) throw new Error("Lifecycle ledger append exceeds configured bounds.");
 		let replacementCompacted = false;
 		if (this.#rowCount + 1 > this.#limits.maxRows || this.#byteCount + line.length > this.#limits.maxBytes)
-			replacementCompacted = await this.#compact(this.#byIdentity.has(entry.identity) ? entry : undefined);
+			replacementCompacted = this.#byIdentity.has(entry.identity)
+				? await this.#compact(entry)
+				: await this.#compact(undefined, { bytes: line.length, rows: 1 });
 		if (replacementCompacted) return entry;
 		if (this.#rowCount + 1 > this.#limits.maxRows || this.#byteCount + line.length > this.#limits.maxBytes)
 			throw new Error("Lifecycle ledger append exceeds configured bounds.");
@@ -798,7 +885,12 @@ export class LifecycleLedger {
 	async begin(
 		identity: string,
 		requestHash: string,
-		metadata: { operationKey?: string; fingerprint?: string; intendedSessionId?: string } = {},
+		metadata: {
+			operationKey?: string;
+			fingerprint?: string;
+			intendedSessionId?: string;
+			closeAuthorityBound?: boolean;
+		} = {},
 	): Promise<BeginResult> {
 		return this.#mutate(async () => this.#begin(identity, requestHash, metadata));
 	}
@@ -806,7 +898,12 @@ export class LifecycleLedger {
 	async #begin(
 		identity: string,
 		requestHash: string,
-		metadata: { operationKey?: string; fingerprint?: string; intendedSessionId?: string },
+		metadata: {
+			operationKey?: string;
+			fingerprint?: string;
+			intendedSessionId?: string;
+			closeAuthorityBound?: boolean;
+		},
 	): Promise<BeginResult> {
 		const prior = this.#byIdentity.get(identity);
 		if (!prior)
@@ -819,6 +916,7 @@ export class LifecycleLedger {
 					operationKey: metadata.operationKey,
 					fingerprint: metadata.fingerprint,
 					intendedSessionId: metadata.intendedSessionId,
+					closeAuthorityBound: metadata.closeAuthorityBound,
 					state: "accepted",
 					ts: Date.now(),
 				}),

package/src/sdk/broker/lifecycle.ts

@@ -97,6 +97,7 @@ import {
 } from "./session-index";
 import {
 	cancellableSleep,
+	DEFAULT_BROKER_PRESPAWN_PREPARATION_TIMEOUT_MS,
 	DEFAULT_READINESS_TIMEOUT_MS,
 	deriveLifecycleOuterDeadlines,
 	isValidReadinessTimeoutMs,
@@ -517,6 +518,7 @@ type LifecycleCommandResolver = () => LifecycleCommand;
 const lifecycleCommandResolversForTest = new WeakMap<Broker, LifecycleCommandResolver>();
 const lifecycleCleanupHooksForTest = new WeakMap<Broker, () => void>();
 const startupAdmittedInputs = new WeakSet<Input>();
+const startupBrokerDerivedAdmissions = new WeakMap<Input, { admittedAt: number; preSpawnDeadlineAt: number }>();
 const startupLaunchInputs = new WeakMap<Input, SessionLaunch>();
 type EnsureLaunchWorktreeForTest = (
 	plan: GjcLaunchWorktreePlan,
@@ -627,7 +629,10 @@ export function hasValidLifecycleDeadlines(value: LifecycleDeadlines, now = Date
 type Input = Record<string, unknown>;
 // The admitted launch deadline must survive the response phase: executeLifecycle
 // receives the caller's original input after startup admission has expanded it.
-type LifecycleEffectIntentWithDeadline = LifecycleEffectIntent & { lifecycleCleanupDeadlineAt?: number };
+type LifecycleEffectIntentWithDeadline = LifecycleEffectIntent & {
+	lifecycleCleanupDeadlineAt?: number;
+	admissionCleanupDeadlineAt?: number;
+};
 export const isCanonicalSessionId = (value: string): boolean => /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value);
 const defaultStateRoot = (cwd: string) => path.join(path.resolve(cwd), ".gjc", "state");
 const hasDefaultStateRoot = (cwd: string, root: string) => path.resolve(root) === defaultStateRoot(cwd);
@@ -6414,6 +6419,7 @@ async function executeLifecycleResponse(
 		const timing = lifecycleTiming(broker);
 		const admissionGranted = startupAdmittedInputs.has(input);
 		if (!admissionGranted) {
+			const startupReceivedAt = timing.now();
 			const suppliedDeadlineFields = [
 				input.receivedAt,
 				input.requestedReadinessTimeoutMs,
@@ -6441,15 +6447,26 @@ async function executeLifecycleResponse(
 				);
 			}
 			const admitted = await broker.runStartup(queueWaitMs, timing, async admittedAt => {
-				const admittedInput = launch.worktreePlan
-					? { ...input, admittedAt, requestedReadinessTimeoutMs }
-					: { ...input, ...deriveLifecycleDeadlines(admittedAt, requestedReadinessTimeoutMs) };
+				const callerSuppliedDeadlines = suppliedDeadlineFields.some(value => value !== undefined);
+				let admittedInput: Input;
+				if (launch.worktreePlan) admittedInput = { ...input, admittedAt, requestedReadinessTimeoutMs };
+				else if (callerSuppliedDeadlines) admittedInput = { ...input };
+				else admittedInput = { ...input, ...deriveLifecycleDeadlines(admittedAt, requestedReadinessTimeoutMs) };
 				startupAdmittedInputs.add(admittedInput);
+				if (!launch.worktreePlan && !callerSuppliedDeadlines)
+					startupBrokerDerivedAdmissions.set(admittedInput, {
+						admittedAt,
+						preSpawnDeadlineAt: Math.min(
+							admittedAt + DEFAULT_BROKER_PRESPAWN_PREPARATION_TIMEOUT_MS,
+							startupReceivedAt + queueWaitMs,
+						),
+					});
 				startupLaunchInputs.set(admittedInput, launch);
 				try {
 					return await executeLifecycleResponse(broker, operation, admittedInput, identity, cleanup);
 				} finally {
 					startupLaunchInputs.delete(admittedInput);
+					startupBrokerDerivedAdmissions.delete(admittedInput);
 					startupAdmittedInputs.delete(admittedInput);
 				}
 			});
@@ -6477,6 +6494,8 @@ async function executeLifecycleResponse(
 		let readinessDeadline: number;
 		let terminationStartDeadline: number;
 		let outerCleanupDeadlineAt: number | undefined;
+		const brokerAdmission = startupBrokerDerivedAdmissions.get(input);
+		const preSpawnDeadlineAt = brokerAdmission?.preSpawnDeadlineAt;
 		if (launch.worktreePlan) {
 			const prepTimeouts = readPreparationTimeouts(input);
 			if (!prepTimeouts.ok) return fail("invalid_input", PREPARATION_TIMEOUT_INVALID_MESSAGE);
@@ -6507,6 +6526,10 @@ async function executeLifecycleResponse(
 			lifecycleDeadline = deadlines.lifecycleCleanupDeadlineAt;
 			readinessDeadline = deadlines.semanticReadyDeadlineAt;
 			terminationStartDeadline = deadlines.terminationStartDeadlineAt;
+			if (preSpawnDeadlineAt !== undefined) {
+				outerCleanupDeadlineAt = preSpawnDeadlineAt + deadlines.requestedReadinessTimeoutMs;
+				lifecycleDeadline = outerCleanupDeadlineAt;
+			}
 		}
 
 		if (!hasProcessIncarnationAuthority())
@@ -6530,6 +6553,9 @@ async function executeLifecycleResponse(
 			childOwnershipEstablished: false,
 			lifecycleCleanupDeadlineAt:
 				outerCleanupDeadlineAt ?? (childDeadlines as LifecycleDeadlines).lifecycleCleanupDeadlineAt,
+			...(brokerAdmission
+				? { admissionCleanupDeadlineAt: (childDeadlines as LifecycleDeadlines).lifecycleCleanupDeadlineAt }
+				: {}),
 			...(plannedWorktreeIntent ? { worktree: plannedWorktreeIntent } : {}),
 		};
 
@@ -6631,7 +6657,22 @@ async function executeLifecycleResponse(
 			}
 			return mapPreparationFailure(error);
 		}
-		if (!launch.worktreePlan && timing.now() >= readinessDeadline)
+		if (preSpawnDeadlineAt !== undefined && brokerAdmission !== undefined) {
+			const prepFinishedAt = timing.now();
+			if (prepFinishedAt >= preSpawnDeadlineAt)
+				return fail(
+					"readiness_timeout",
+					`Broker pre-spawn preparation exceeded its ${Math.max(0, preSpawnDeadlineAt - brokerAdmission.admittedAt)} ms allowance after ${Math.max(0, prepFinishedAt - brokerAdmission.admittedAt)} ms.`,
+				);
+			// Only broker-derived tuples restart here; exact caller deadlines remain unchanged.
+			childDeadlines = deriveLifecycleDeadlines(
+				prepFinishedAt,
+				(childDeadlines as LifecycleDeadlines).requestedReadinessTimeoutMs,
+			);
+			readinessDeadline = childDeadlines.semanticReadyDeadlineAt;
+			terminationStartDeadline = childDeadlines.terminationStartDeadlineAt;
+			lifecycleDeadline = childDeadlines.lifecycleCleanupDeadlineAt;
+		} else if (!launch.worktreePlan && timing.now() >= readinessDeadline)
 			return fail(
 				"readiness_timeout",
 				"Lifecycle preparation exhausted the semantic readiness deadline before spawning.",
@@ -7991,6 +8032,26 @@ export interface LifecycleExecutionOutcome {
 	deferredArtifactCleanup?: () => Promise<void>;
 }
 
+export function classifyLateAdmissionSpawnFailure(
+	response: BrokerResponse,
+	effectIntent: LifecycleEffectIntentWithDeadline | undefined,
+	now: number,
+	messageSource: BrokerResponse,
+): BrokerResponse {
+	if (
+		response.ok ||
+		response.error.code !== "spawn_failed" ||
+		effectIntent?.childOwnershipEstablished !== true ||
+		effectIntent.admissionCleanupDeadlineAt === undefined ||
+		now < effectIntent.admissionCleanupDeadlineAt
+	)
+		return response;
+	return {
+		...response,
+		error: { code: "terminal_uncertain", message: terminalUncertainStartupMessage(messageSource) },
+	};
+}
+
 /** Returns the response together with every durable lifecycle fact needed for truthful replay. */
 export async function executeLifecycle(
 	broker: Broker,
@@ -7999,6 +8060,7 @@ export async function executeLifecycle(
 	identity: string,
 	cleanup?: CleanupEvidence,
 ): Promise<LifecycleExecutionOutcome> {
+	const timing = lifecycleTiming(broker);
 	let proofBudget = lifecycleProofBudgetFromInput(broker, input);
 	if (!proofBudget)
 		proofBudget = lifecycleProofBudgetFromEffectIntent(broker, broker.ledger.get(identity)?.effectIntent);
@@ -8052,16 +8114,25 @@ export async function executeLifecycle(
 			const binding = validateLifecycleDeleteMetadataBinding(broker, operation, input, identity, cleanup);
 			if (binding) return { response: binding };
 		}
+		const reconciled = await reconcileLifecycleCleanup(
+			broker,
+			identity,
+			cleanup,
+			operation === "session.delete"
+				? { ok: true, result: { sessionId: cleanup.sessionId } }
+				: fail("spawn_failed", "No ready SDK endpoint remains available."),
+			proofBudget,
+		);
 		return {
-			response: await reconcileLifecycleCleanup(
-				broker,
-				identity,
-				cleanup,
+			response:
 				operation === "session.delete"
-					? { ok: true, result: { sessionId: cleanup.sessionId } }
-					: fail("spawn_failed", "No ready SDK endpoint remains available."),
-				proofBudget,
-			),
+					? reconciled
+					: classifyLateAdmissionSpawnFailure(
+							reconciled,
+							broker.ledger.get(identity)?.effectIntent,
+							timing.now(),
+							reconciled,
+						),
 		};
 	}
 	const response = await executeLifecycleResponse(broker, operation, input, identity, cleanup);
@@ -8089,27 +8160,28 @@ export async function executeLifecycle(
 		expected,
 		evidence,
 		proofBudget,
-		!response.ok && response.error.code === "ready_then_exited",
+		!response.ok ? response.error.code === "ready_then_exited" : false,
 	);
-	const startupFailure: LifecycleStartupFailureReceipt | undefined = evidence
-		? {
-				artifactDigest: evidence.digest,
-				phase: evidence.artifact.phase,
-				reason: evidence.artifact.reason,
-				message: evidence.artifact.message,
-				...(evidence.artifact.code === undefined
-					? {}
-					: { code: evidence.artifact.code, details: evidence.artifact.details }),
-				rollback: {
-					endpointGeneration: evidence.artifact.rollback.endpointGeneration,
-					fenced: evidence.artifact.rollback.fenced,
-					runtimeRemoved: evidence.artifact.rollback.runtimeRemoved,
-					hostStopped: evidence.artifact.rollback.hostStopped,
-					brokerRegistrationReleased: evidence.artifact.rollback.brokerRegistrationReleased,
-				},
-				...(cleanupProof ? { cleanupProof } : {}),
-			}
-		: undefined;
+	const startupFailure: LifecycleStartupFailureReceipt | undefined =
+		evidence && !response.ok
+			? {
+					artifactDigest: evidence.digest,
+					message: evidence.artifact.message,
+					phase: evidence.artifact.phase,
+					reason: evidence.artifact.reason,
+					...(evidence.artifact.code === undefined
+						? {}
+						: { code: evidence.artifact.code, details: evidence.artifact.details }),
+					rollback: {
+						endpointGeneration: evidence.artifact.rollback.endpointGeneration,
+						fenced: evidence.artifact.rollback.fenced,
+						runtimeRemoved: evidence.artifact.rollback.runtimeRemoved,
+						hostStopped: evidence.artifact.rollback.hostStopped,
+						brokerRegistrationReleased: evidence.artifact.rollback.brokerRegistrationReleased,
+					},
+					...(cleanupProof ? { cleanupProof } : {}),
+				}
+			: undefined;
 	const durableEffectsBody: Omit<LifecycleDurableEffectsReceipt, "digest"> = {
 		...(priorDurableEffects?.worktree ? { worktree: priorDurableEffects.worktree } : {}),
 		...(evidence?.artifact.transcript
@@ -8228,8 +8300,10 @@ export async function executeLifecycle(
 										...(startupFailure ? { startupFailure } : {}),
 									}
 			: response;
+	// The extended proof window may reconcile artifacts after the original
+	// admission deadline, but cannot retroactively prove a timely spawn failure.
 	return {
-		response: terminalResponse,
+		response: classifyLateAdmissionSpawnFailure(terminalResponse, entry?.effectIntent, timing.now(), response),
 		...(durableEffects ? { durableEffects } : {}),
 		...(startupFailure ? { startupFailure } : {}),
 	};

package/src/sdk/broker/recovery-backoff.ts

@@ -0,0 +1,135 @@
+/**
+ * Bounded exponential backoff tracker for broker recovery failures per agent dir.
+ * Tracks repeated recovery failures and implements exponential backoff with a cap
+ * to prevent repeated spawns from destabilizing the system.
+ */
+
+/** Configuration for recovery backoff behavior. */
+export interface RecoveryBackoffConfig {
+	/** Initial backoff delay in milliseconds (default: 1000ms). */
+	initialDelayMs: number;
+	/** Maximum backoff delay in milliseconds (default: 30000ms = 30s). */
+	maxDelayMs: number;
+	/** Backoff multiplier applied each retry (default: 2). */
+	multiplier: number;
+	/** Maximum number of recovery attempts per session (default: 5). */
+	maxAttempts: number;
+}
+
+/** State for a single agent dir's recovery backoff. */
+export interface RecoveryBackoffState {
+	/** Timestamp of the last recovery failure. */
+	lastFailureAt: number;
+	/** Current backoff delay in milliseconds. */
+	currentDelayMs: number;
+	/** Number of consecutive failures. */
+	failureCount: number;
+	/** Whether recovery has been permanently stopped due to max attempts. */
+	stopped: boolean;
+}
+
+/**
+ * Session broker recovery ticks every 30 s (`SESSION_BROKER_RECOVERY_INTERVAL_MS`), so the
+ * first retry waits two ticks and the delay doubles up to 30 minutes: a broker that keeps
+ * failing costs about two spawn attempts per hour at steady state instead of one per tick.
+ * Recovery never stops for good on failures alone -- a broker outage must still heal once
+ * the broker comes back. Only a replaced runtime image ends recovery (session-runtime.ts).
+ */
+const DEFAULTS: RecoveryBackoffConfig = {
+	initialDelayMs: 60_000,
+	maxDelayMs: 30 * 60_000,
+	multiplier: 2,
+	maxAttempts: Number.POSITIVE_INFINITY,
+};
+
+/** Manages per-agent-dir recovery backoff state. */
+export class RecoveryBackoffTracker {
+	#state = new Map<string, RecoveryBackoffState>();
+	#config: RecoveryBackoffConfig;
+	#clock: { now(): number } = { now: Date.now };
+
+	constructor(config: Partial<RecoveryBackoffConfig> = {}) {
+		this.#config = { ...DEFAULTS, ...config };
+	}
+
+	/** Test hook: inject a custom clock. */
+	setClockForTest(clock: { now(): number }): void {
+		this.#clock = clock;
+	}
+
+	/**
+	 * Check if recovery should proceed now, considering backoff.
+	 * Returns true if sufficient time has elapsed since the last failure.
+	 */
+	canAttemptRecovery(agentDir: string): boolean {
+		const state = this.#state.get(agentDir);
+		if (!state) return true;
+		if (state.stopped) return false;
+
+		const now = this.#clock.now();
+		return now >= state.lastFailureAt + state.currentDelayMs;
+	}
+
+	/**
+	 * Record a recovery failure and update backoff state.
+	 * Returns true if recovery should continue to be attempted, false if max attempts reached.
+	 */
+	recordFailure(agentDir: string): boolean {
+		let state = this.#state.get(agentDir);
+		if (!state) {
+			state = {
+				lastFailureAt: this.#clock.now(),
+				currentDelayMs: this.#config.initialDelayMs,
+				failureCount: 1,
+				stopped: false,
+			};
+			this.#state.set(agentDir, state);
+		} else {
+			state.lastFailureAt = this.#clock.now();
+			state.failureCount += 1;
+
+			// Apply exponential backoff
+			state.currentDelayMs = Math.min(state.currentDelayMs * this.#config.multiplier, this.#config.maxDelayMs);
+
+			// Stop if we've hit max attempts
+			if (state.failureCount >= this.#config.maxAttempts) {
+				state.stopped = true;
+			}
+		}
+
+		return !state.stopped;
+	}
+
+	/**
+	 * Record a successful recovery and reset backoff state.
+	 */
+	recordSuccess(agentDir: string): void {
+		this.#state.delete(agentDir);
+	}
+
+	/**
+	 * Get the current backoff state for an agent dir (for testing/diagnostics).
+	 */
+	getState(agentDir: string): RecoveryBackoffState | undefined {
+		return this.#state.get(agentDir);
+	}
+
+	/**
+	 * Get milliseconds until the next recovery attempt can proceed.
+	 */
+	getBackoffWaitMs(agentDir: string): number {
+		const state = this.#state.get(agentDir);
+		if (!state) return 0;
+
+		const now = this.#clock.now();
+		const nextAttemptAt = state.lastFailureAt + state.currentDelayMs;
+		return Math.max(0, nextAttemptAt - now);
+	}
+
+	/**
+	 * Reset all backoff state (for testing).
+	 */
+	resetForTest(): void {
+		this.#state.clear();
+	}
+}

package/src/sdk/broker/runtime.ts

@@ -6,7 +6,11 @@ import { currentExecutablePath } from "@gajae-code/natives";
 
 import internalSourceMarker from "./internal-source-marker-2178.txt" with { type: "file" };
 
-export type SdkInternalAction = "broker-internal" | "session-host-internal" | "stderr-drain-internal";
+export type SdkInternalAction =
+	| "broker-internal"
+	| "broker-trampoline-internal"
+	| "session-host-internal"
+	| "stderr-drain-internal";
 
 export type SdkInternalSpawnCommand =
 	| {
@@ -271,6 +275,15 @@ export function sdkInternalRuntimeImage(): string | undefined {
 	return publishedRuntimeImage({});
 }
 
+/** Identity of a runtime image: enough to detect replacement at the same path. */
+export interface SdkInternalRuntimeImageIdentity {
+	path: string;
+	dev: number;
+	ino: number;
+	mtimeMs: number;
+	size: number;
+}
+
 /** A stat that has not answered by here is inconclusive, never proof of absence. */
 const RUNTIME_IMAGE_PROBE_TIMEOUT_MS = 1_000;
 
@@ -308,6 +321,80 @@ export async function isSdkInternalRuntimeImagePresent(file: string): Promise<bo
 	}
 }
 
+const RUNTIME_IMAGE_PROBE_TIMED_OUT = Symbol("runtime-image-probe-timed-out");
+
+/**
+ * `fsp.stat` bounded by the runtime-image probe timeout. A metadata request on a
+ * stalled mount can never settle; the timeout sentinel lets callers treat that as
+ * inconclusive instead of pending forever.
+ */
+async function statRuntimeImageBounded(file: string): Promise<fs.Stats | typeof RUNTIME_IMAGE_PROBE_TIMED_OUT> {
+	const timedOut = Promise.withResolvers<typeof RUNTIME_IMAGE_PROBE_TIMED_OUT>();
+	const timer: NodeJS.Timeout = setTimeout(
+		() => timedOut.resolve(RUNTIME_IMAGE_PROBE_TIMED_OUT),
+		RUNTIME_IMAGE_PROBE_TIMEOUT_MS,
+	);
+	try {
+		return await Promise.race([fsp.stat(file), timedOut.promise]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Capture the runtime image identity (dev, ino, mtimeMs, size) at startup.
+ * Used to detect if the binary at the same path has been replaced.
+ */
+export async function captureRuntimeImageIdentity(file: string): Promise<SdkInternalRuntimeImageIdentity | undefined> {
+	try {
+		const resolved = path.resolve(file);
+		const stats = await statRuntimeImageBounded(resolved);
+		// A timed-out probe leaves the identity unknown, like any other failure.
+		if (stats === RUNTIME_IMAGE_PROBE_TIMED_OUT || !stats.isFile()) return undefined;
+		return {
+			path: resolved,
+			dev: stats.dev,
+			ino: stats.ino,
+			mtimeMs: stats.mtimeMs,
+			size: stats.size,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Check if the runtime image has been replaced since startup.
+ * Returns `true` if the path is gone, its dev/ino differ from the startup identity,
+ * or its size or modification time changed (an in-place rewrite keeps the inode).
+ * Returns `false` (inconclusive) if the file exists and matches, or on any error.
+ */
+export async function isSdkInternalRuntimeImageReplaced(
+	startupIdentity: SdkInternalRuntimeImageIdentity | undefined,
+): Promise<boolean> {
+	if (startupIdentity === undefined) return false;
+
+	try {
+		const stats = await statRuntimeImageBounded(startupIdentity.path);
+		// A timed-out probe is inconclusive, not proof of replacement.
+		if (stats === RUNTIME_IMAGE_PROBE_TIMED_OUT) return false;
+		if (!stats.isFile()) return false; // Not a file, but not proven gone
+		// dev/ino catch a replacement at the same path; size and mtime catch an
+		// in-place rewrite that keeps the inode (mtime also covers same-size bytes).
+		return (
+			stats.dev !== startupIdentity.dev ||
+			stats.ino !== startupIdentity.ino ||
+			stats.size !== startupIdentity.size ||
+			stats.mtimeMs !== startupIdentity.mtimeMs
+		);
+	} catch (error) {
+		// Only ENOENT/ENOTDIR prove absence
+		if (isProvenRuntimeImageAbsence(error)) return true;
+		// Inconclusive on other errors
+		return false;
+	}
+}
+
 /** Resolve the production descriptor from the statically imported marker and current Bun runtime evidence. */
 export function resolveSdkInternalSpawnCommand(action: SdkInternalAction): SdkInternalSpawnCommand {
 	return resolveSdkInternalSpawnCommandWithEvidence(action, {});