@gajae-code/coding-agent 0.17.1 → 0.17.2

package/src/sdk/acp/adapter.ts

@@ -9,6 +9,7 @@ import {
 	type SessionReconcileUncertainTarget,
 	validateSessionReconcileUncertainTarget,
 } from "../lifecycle/service";
+import { ACP_PROMPT_INACTIVITY_TIMEOUT_MS } from "../prompt-watchdog";
 import {
 	validateAdapterControl,
 	validateAdapterSecretFields,
@@ -19,6 +20,35 @@ import { type SessionAttachment, type SessionRouter, SessionRouterError } from "
 import { ACP_SESSION_RECONNECT, SESSION_ABORT_TIMEOUT_MS } from "../session-reconnect";
 import type { SessionLifecycleMcpServer } from "./mcp";
 
+/**
+ * Registration rounds one provider activation may spend chasing a moving attachment.
+ *
+ * The activation loop restarts whenever the Router attachment changes identity while it
+ * is registering, because the leases it just took belong to a connection that no longer
+ * exists. One reconnect costs one restart, so a handful covers any churn that is actually
+ * converging; beyond that the attachment is rotating faster than registration completes
+ * and another round only re-takes leases that will be invalidated again. Bounding this is
+ * what turns "many session hosts contend for one agent dir" from an unbounded spin into a
+ * reported failure (issue #5658).
+ */
+export const PROVIDER_ACTIVATION_MAX_ATTEMPTS = 8;
+
+/**
+ * Wall-clock budget for the same loop.
+ *
+ * The attempt cap alone bounds rounds, not time: every round is a `#requestSession` round
+ * trip per provider, so under lease contention attempts are slow rather than fast-spinning
+ * and eight of them can still outlast the caller. The budget is sized to a third of
+ * {@link ACP_PROMPT_INACTIVITY_TIMEOUT_MS} so a prompt stalled in provider preflight fails
+ * with this error — which names the contended capability — with room to spare before the
+ * ACP prompt watchdog reports the same stall as undifferentiated silence.
+ *
+ * It gates *starting* another round, never interrupting one in flight: a single slow but
+ * healthy registration keeps whatever time it needs, and only a retry decided after the
+ * deadline is refused.
+ */
+export const PROVIDER_ACTIVATION_BUDGET_MS = Math.floor(ACP_PROMPT_INACTIVITY_TIMEOUT_MS / 3);
+
 type JsonObject = Record<string, unknown>;
 function object(value: unknown): JsonObject | undefined {
 	return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as JsonObject) : undefined;
@@ -600,7 +630,12 @@ export class AcpSdkAdapter {
 		}
 
 		const activation = (async () => {
-			for (;;) {
+			const startedAt = Date.now();
+			// Exhaustion is checked here, outside the try below, so the throw cannot be caught
+			// by the same `continue` branch that spent the budget.
+			for (let attempt = 1; ; attempt++) {
+				if (attempt > PROVIDER_ACTIVATION_MAX_ATTEMPTS || Date.now() - startedAt >= PROVIDER_ACTIVATION_BUDGET_MS)
+					throw this.#providerActivationExhausted(attempt - 1, startedAt);
 				const attachment = this.#attachment;
 				const connectionId = attachment?.connectionId;
 				try {
@@ -652,6 +687,33 @@ export class AcpSdkAdapter {
 		}
 	}
 
+	/**
+	 * Names what the exhausted activation loop was still fighting over, so a stalled
+	 * preflight is attributable to a capability instead of surfacing as generic silence.
+	 */
+	#providerActivationExhausted(attempts: number, startedAt: number): AcpSdkAdapterError {
+		const elapsedMs = Date.now() - startedAt;
+		const contended = this.#providers
+			.filter(provider => !this.#leases.has(provider.capability))
+			.map(provider => provider.capability);
+		const detail =
+			contended.length > 0
+				? `still unleased: ${contended.join(", ")}`
+				: "the SDK session attachment changed identity on every attempt";
+		logger.error("acp_provider_activation_exhausted", {
+			sessionId: this.#sessionId,
+			attempts,
+			elapsedMs,
+			contended,
+			leaseCount: this.#leases.size,
+		});
+		return new AcpSdkAdapterError(
+			"provider_activation_exhausted",
+			`SDK provider activation did not converge after ${attempts} attempts over ${Math.round(elapsedMs / 1_000)}s ` +
+				`(${detail}). The session host is contending for provider leases it cannot hold.`,
+		);
+	}
+
 	#assertGenericDisposition(kind: "control" | "global", sdkId: string): void {
 		const operation = OPERATIONS.find(candidate => candidate.kind === kind && candidate.sdkId === sdkId);
 		if (!operation) throw new AcpSdkAdapterError("unknown_operation", `Unknown SDK ${kind}: ${sdkId}`);

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

@@ -31,10 +31,27 @@ export function acpFinalTextFromMessage(message: unknown): BoundedAcpFinalText {
 	return boundAcpFinalText(parts.join(""));
 }
 
+/**
+ * Assistant-content presence is trimmed everywhere in the prompt pipeline: whitespace carries no
+ * assistant content. The ACP retry gate, prompt reconciliation
+ * (`sdk/bus/prompt-reconciliation.ts`) and terminal publication must agree, otherwise a terminal
+ * the retry gate treats as "no output" can still publish a whitespace chunk alongside the retry's
+ * real answer (review P2 on #5628).
+ */
+export function hasAcpFinalTextContent(value: string): boolean {
+	return value.trim().length > 0;
+}
+
 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 (!hasAcpFinalTextContent(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) };
+	if (final.text.startsWith(streamed)) {
+		// A pure-whitespace delta is the same defect class as whitespace-only final text: it adds no
+		// assistant content, so it must not reach consumers either.
+		const tail = final.text.slice(streamed.length);
+		return hasAcpFinalTextContent(tail) ? { kind: "emit", final, text: tail } : { kind: "none", final };
+	}
 	return { kind: "divergent", final };
 }

package/src/sdk/broker/ensure.ts

@@ -70,6 +70,72 @@ const SPAWN_LOCK_RETRY_DELAY_MS = 50;
 const SPAWN_LOCK_TARGET_NAME = "broker.spawn";
 const STARTUP_LOCK_TARGET_NAME = "broker.startup";
 
+export interface BrokerStartupLockTestHooks {
+	onAcquired?: () => void;
+	onContended?: () => void;
+}
+
+/**
+ * Test-only phase observation for detached broker startup regressions. The
+ * signal is opt-in through the child environment and never affects broker
+ * ownership or error handling when the test seam is absent.
+ */
+export async function emitBrokerStartupTestSignal(signal: string): Promise<void> {
+	const directory = process.env.GJC_SDK_TEST_BROKER_SIGNAL_DIR;
+	if (!directory || !/^[a-z0-9-]+$/.test(signal)) return;
+	try {
+		await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+		await fs.writeFile(path.join(directory, signal), `${process.pid}\n`);
+	} catch {
+		// Test observability must never change broker startup semantics.
+	}
+}
+
+/**
+ * The parent discovery budget published as a composition rather than a number.
+ * A test that stages a fence contention has to time itself against these legs,
+ * and retyping the sum makes it win or lose on scheduler noise while letting a
+ * change to any single leg silently re-tune it (#5604). This is the one source
+ * of truth for how the budget is built; nothing may restate the arithmetic.
+ */
+export const BROKER_DISCOVERY_BUDGET = {
+	staleRetirementMs: STALE_BROKER_RETIREMENT_TIMEOUT_MS,
+	startupLockWaitMs: STARTUP_LOCK_WAIT_MS,
+	publicationMs: BROKER_PUBLICATION_TIMEOUT_MS,
+	/** What the startup fence grants its holder: retirement plus one publication attempt. */
+	fenceOperationMs: STALE_BROKER_RETIREMENT_TIMEOUT_MS + BROKER_PUBLICATION_TIMEOUT_MS,
+	/**
+	 * When a child spawned under the parent's spawn lock gives up on the fence,
+	 * measured from that lock acquisition: the parent retires the stale incumbent
+	 * first, then the child exhausts its own fence wait. Not a production
+	 * constant -- an emergent property of the two legs that precede publication.
+	 */
+	childFenceWaitMs: STALE_BROKER_RETIREMENT_TIMEOUT_MS + STARTUP_LOCK_WAIT_MS,
+	discoveryMs: DISCOVERY_TIMEOUT_MS,
+} as const;
+
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Clock the discovery budget is measured on. The default is the real one; a test
+ * installs a virtual clock to assert the composition order -- stale retirement,
+ * then the child fence, then startup and publication -- in-process instead of
+ * racing three wall clocks against each other (#5604). Reaping keeps its own
+ * {@link ReapTiming} seam and is deliberately not driven from here.
+ */
+export interface EnsureBrokerTiming {
+	now(): number;
+	sleep(ms: number): Promise<void>;
+}
+
+const REAL_ENSURE_BROKER_TIMING: EnsureBrokerTiming = { now: Date.now, sleep };
+let ensureBrokerTiming: EnsureBrokerTiming = REAL_ENSURE_BROKER_TIMING;
+
+/** Test hook: drives the discovery budget on a controllable clock. */
+export function setEnsureBrokerTimingForTest(timing: EnsureBrokerTiming | undefined): void {
+	ensureBrokerTiming = timing ?? REAL_ENSURE_BROKER_TIMING;
+}
+
 type SpawnLockOptions = Pick<FileLockOptions, "retries" | "retryDelayMs" | "signal">;
 
 interface BrokerLockHostIdentity {
@@ -104,7 +170,7 @@ async function readBrokerDiscoveryBeforeDeadline(
 	heartbeatTtlMs: number | undefined,
 	deadline: number,
 ): Promise<BrokerDiscovery | null> {
-	const remainingMs = deadline - Date.now();
+	const remainingMs = deadline - ensureBrokerTiming.now();
 	if (!Number.isFinite(remainingMs)) return await readBrokerDiscovery(agentDir, heartbeatTtlMs);
 	if (remainingMs <= 0) throw new Error("Timed out reading SDK broker discovery.");
 	const read = readBrokerDiscovery(agentDir, heartbeatTtlMs);
@@ -151,14 +217,17 @@ async function acquireSpawnLock(agentDir: string, options: SpawnLockOptions = {}
 export async function withBrokerStartupLock<T>(
 	agentDir: string,
 	operation: (deadline: number) => Promise<T>,
+	testHooks: BrokerStartupLockTestHooks = {},
 ): Promise<T> {
 	const hostIdentity = await brokerLockHostIdentity(agentDir);
 	return withFileLock(
 		path.join(agentDir, "sdk", STARTUP_LOCK_TARGET_NAME),
-		() => operation(Date.now() + STALE_BROKER_RETIREMENT_TIMEOUT_MS + BROKER_PUBLICATION_TIMEOUT_MS),
+		() => operation(ensureBrokerTiming.now() + BROKER_DISCOVERY_BUDGET.fenceOperationMs),
 		{
 			retries: Math.ceil(STARTUP_LOCK_WAIT_MS / SPAWN_LOCK_RETRY_DELAY_MS),
 			retryDelayMs: SPAWN_LOCK_RETRY_DELAY_MS,
+			onAcquired: testHooks.onAcquired,
+			onContended: testHooks.onContended,
 			...hostIdentity,
 		},
 	);
@@ -275,7 +344,6 @@ const DEFAULT_REAP_TIMING: ReapTiming = {
 	gracefulMs: REAP_GRACEFUL_MS,
 	killVerifyMs: REAP_SIGKILL_CAP_MS,
 };
-const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
 /**
  * Terminate and reap a detached broker this process spawned, targeting the exact
@@ -410,9 +478,9 @@ export async function closeBrokerClientBeforeDeadline(
 ): Promise<void> {
 	const close = client.close();
 	void close.catch(() => undefined);
-	const remainingMs = deadline - Date.now();
+	const remainingMs = deadline - ensureBrokerTiming.now();
 	if (remainingMs <= 0) return;
-	await Promise.race([close, Bun.sleep(remainingMs)]);
+	await Promise.race([close, ensureBrokerTiming.sleep(remainingMs)]);
 }
 
 async function retireUnusableBroker(
@@ -420,7 +488,7 @@ async function retireUnusableBroker(
 	settings: EnsureBrokerSettings,
 	outerDeadline = Number.POSITIVE_INFINITY,
 ): Promise<void> {
-	const deadline = Math.min(outerDeadline, Date.now() + STALE_BROKER_RETIREMENT_TIMEOUT_MS);
+	const deadline = Math.min(outerDeadline, ensureBrokerTiming.now() + BROKER_DISCOVERY_BUDGET.staleRetirementMs);
 	let shutdownSucceeded = false;
 	try {
 		const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
@@ -443,10 +511,10 @@ async function retireUnusableBroker(
 		} catch {}
 	}
 	// Wait for the stale identity to disappear (owner-fenced: pid+incarnation).
-	while (Date.now() < deadline) {
+	while (ensureBrokerTiming.now() < deadline) {
 		const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
 		if (!sameBrokerOwner(current, stale)) break;
-		await sleep(STALE_BROKER_POLL_MS);
+		await ensureBrokerTiming.sleep(STALE_BROKER_POLL_MS);
 	}
 }
 
@@ -459,6 +527,7 @@ export async function reconcileBrokerGenerationForStartup(
 	if (!current) return undefined;
 	if (await isBrokerReusable(current)) return current;
 	await retireUnusableBroker(current, settings, deadline);
+	await emitBrokerStartupTestSignal("retirement-finished");
 	const replacement = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
 	return replacement && (await isBrokerReusable(replacement)) ? replacement : undefined;
 }
@@ -506,7 +575,7 @@ function createFixtureLease(owner: BrokerOwner, child: ChildProcess): ExactFixtu
 
 async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: EnsureInitiator): Promise<EnsureOutcome> {
 	const initialDiscoveryDeadline =
-		Date.now() + (initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
+		ensureBrokerTiming.now() + (initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
 	const priorOwner = owners.get(settings.agentDir);
 	const existing = await readBrokerDiscoveryBeforeDeadline(
 		settings.agentDir,
@@ -514,7 +583,11 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		initialDiscoveryDeadline,
 	);
 	const restartIntent = await readBrokerRestartIntent(settings.agentDir);
-	if (restartIntent && restartIntent.expiresAt > Date.now() && restartIntent.requestId !== settings.restartRequestId)
+	if (
+		restartIntent &&
+		restartIntent.expiresAt > ensureBrokerTiming.now() &&
+		restartIntent.requestId !== settings.restartRequestId
+	)
 		throw new Error("broker_restart_in_progress");
 	if (initiator === "fixture-lease" && (priorOwner || existing)) throw fixtureLeaseUnavailable();
 	if (priorOwner) {
@@ -543,9 +616,14 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 	const releaseSpawnLock = initiator === "fixture-lease" ? async () => {} : await acquireSpawnLock(settings.agentDir);
 	try {
 		const deadline =
-			Date.now() + (initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
+			ensureBrokerTiming.now() +
+			(initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
 		const lockedIntent = await readBrokerRestartIntent(settings.agentDir);
-		if (lockedIntent && lockedIntent.expiresAt > Date.now() && lockedIntent.requestId !== settings.restartRequestId)
+		if (
+			lockedIntent &&
+			lockedIntent.expiresAt > ensureBrokerTiming.now() &&
+			lockedIntent.requestId !== settings.restartRequestId
+		)
 			throw new Error("broker_restart_in_progress");
 		// The lock winner may still find a discovery published by an earlier winner
 		// that finished between our first read and the lock acquisition.
@@ -572,7 +650,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		// parent's diagnostic handle must not discard exact ownership of a live child.
 		await spawnLog?.handle.close().catch(() => undefined);
 		let discoveryError: unknown;
-		while (Date.now() < deadline) {
+		while (ensureBrokerTiming.now() < deadline) {
 			if (spawnError || child.exitCode !== null || child.signalCode !== null) break;
 			try {
 				const discovered = await readBrokerDiscoveryBeforeDeadline(
@@ -582,7 +660,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 				);
 				if (discovered) {
 					if (!(await isBrokerReusable(discovered))) {
-						await sleep(50);
+						await ensureBrokerTiming.sleep(50);
 						continue;
 					}
 					if (owner.markReady(discovered)) {
@@ -596,7 +674,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			} catch (error) {
 				discoveryError = error;
 			}
-			await sleep(50);
+			await ensureBrokerTiming.sleep(50);
 		}
 		const exitedBeforeDiscovery = child.exitCode !== null || child.signalCode !== null;
 		if (exitedBeforeDiscovery && child.exitCode === 0) {
@@ -616,7 +694,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 						await owner.stop();
 						return { kind: "external-discovery", discovery: winner };
 					}
-					await sleep(50);
+					await ensureBrokerTiming.sleep(50);
 				}
 			} catch {
 				// fall through to cleanup + failure
@@ -649,8 +727,8 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			// reaches the end of its publication allowance, so keep the parent attached
 			// to the exact agent dir and give that incumbent one final bounded chance to
 			// publish before treating the replacement failure as terminal.
-			const recoveryDeadline = Math.min(deadline, Date.now() + BROKER_PUBLICATION_TIMEOUT_MS);
-			while (Date.now() < recoveryDeadline) {
+			const recoveryDeadline = Math.min(deadline, ensureBrokerTiming.now() + BROKER_DISCOVERY_BUDGET.publicationMs);
+			while (ensureBrokerTiming.now() < recoveryDeadline) {
 				try {
 					const incumbent = await readBrokerDiscoveryBeforeDeadline(
 						settings.agentDir,
@@ -665,7 +743,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 					// Keep the bounded retry alive; a transient read failure is not
 					// authority to classify the incumbent as failed.
 				}
-				await sleep(50);
+				await ensureBrokerTiming.sleep(50);
 			}
 		}
 		const spawnLogTail = exitedBeforeDiscovery && spawnLog ? await readBrokerSpawnLogTail(spawnLog.path) : "";

package/src/sdk/bus/index.ts

@@ -4803,10 +4803,19 @@ export function createNotificationsExtension(
 			 * by the firing deadline timer, cleared when the attempt completes or
 			 * is superseded). Fresh attributable progress recorded while the
 			 * attempt awaits durable reconciliation advances the lease generation;
-			 * the attempt must then back off instead of terminalizing a live prompt
-			 * (mirrors PromptDeadlineManager).
+			 * before self-abort starts, the attempt must then back off instead of
+			 * terminalizing a live prompt (mirrors PromptDeadlineManager).
 			 */
-			deadlineAttempt?: { lease: PromptDeadlineLease; generation: number };
+			deadlineAttempt?: {
+				lease: PromptDeadlineLease;
+				generation: number;
+				/**
+				 * Set synchronously immediately before this expiry attempt aborts
+				 * its own run. Progress from that abort belongs to this attempt,
+				 * not to an independently live prompt.
+				 */
+				selfAbortStarted?: true;
+			};
 			phase: "active" | "outcome_claimed" | "terminalizing" | "publication_closed" | "delivered";
 			outcome?: SdkPromptTerminalOutcome;
 			/** Agent-owned resource run captured at acceptance; cleanup targets only this handle. */
@@ -5108,10 +5117,24 @@ export function createNotificationsExtension(
 		const deadlineAttemptStatus = (
 			key: string,
 			submission: PromptSubmission,
-			attempt: { lease: PromptDeadlineLease; generation: number },
+			attempt: { lease: PromptDeadlineLease; generation: number; selfAbortStarted?: true },
 		): DeadlineAttemptStatus => {
 			if (promptSubmissions.get(key) !== submission || submission.deadlineLease !== attempt.lease) return "stale";
 			const lease = submission.deadlineLease;
+			// A deadline expiry attempt must not be superseded by progress that its
+			// OWN abort caused. Terminal fencing aborts the running tool, and the
+			// agent loop pairs that tool off with a `tool_execution_end` which is
+			// NOT marked non-dispatched — the marker is reserved for calls that
+			// never started, and this one did (`dispatched = record.started`,
+			// agent-loop.ts). So the abort's teardown reaches renewPromptDeadline as
+			// ordinary attributable progress and advances the generation of the very
+			// lease this attempt is expiring. Reading that as supersession makes the
+			// attempt back off, re-arm, and walk into the identical trap forever: the
+			// prompt never gets a terminal frame and its durable claim stays pending
+			// (#5583). Progress observed BEFORE the self-abort is still authoritative
+			// — that is the post-claim fence, and it keeps a genuinely live prompt
+			// from being killed.
+			if (attempt.selfAbortStarted) return "current";
 			if (lease.generation !== attempt.generation && Date.now() < promptDeadlineAt(lease)) return "superseded";
 			return "current";
 		};
@@ -5403,6 +5426,10 @@ export function createNotificationsExtension(
 				}
 				let proof: RunSettlementProof;
 				try {
+					// Mark immediately before the abort seam, with no await between:
+					// abort-time attributable completion is caused by this deadline
+					// attempt and must not supersede its own expiry terminal.
+					if (deadlineAttempt) deadlineAttempt.selfAbortStarted = true;
 					proof = await terminalAbortSeams.abortPromptAndWaitWithTerminal(submission.executionHandle, {
 						graceMs: PROMPT_TERMINALIZATION_GRACE_MS,
 						// Terminal abort registers the continuation fence for the