@gajae-code/coding-agent 0.16.0 → 0.16.1

package/src/modes/prompt-action-autocomplete.ts

@@ -6,6 +6,8 @@ import {
 	CombinedAutocompleteProvider,
 	extractSlashCommandTokenPrefix,
 	getSlashCommandMatchRank,
+	hasInlineCodeDelimiter,
+	isInsideInlineCodeSpan,
 	normalizeFuzzyText,
 	type SlashCommand,
 } from "@gajae-code/tui";
@@ -140,7 +142,7 @@ function withoutSkillCommandSuggestions(
 	suggestions: { items: AutocompleteItem[]; prefix: string } | null,
 ): { items: AutocompleteItem[]; prefix: string } | null {
 	if (!suggestions) return null;
-	const items = suggestions.items.filter(item => !item.value.startsWith("skill:"));
+	const items = suggestions.items.filter(item => !item.value.toLowerCase().startsWith("skill:"));
 	return items.length > 0 ? { ...suggestions, items } : null;
 }
 
@@ -160,6 +162,21 @@ function getSlashTokenPrefix(textBeforeCursor: string): string | null {
 	return extractSlashCommandTokenPrefix(textBeforeCursor);
 }
 
+function getRawSlashTokenPrefix(textBeforeCursor: string): string | null {
+	return textBeforeCursor.match(/(?:^|\s)(\/[^\s]*)$/)?.[1] ?? null;
+}
+
+function isSlashTokenInsideInlineCodeSpan(
+	lines: string[],
+	cursorLine: number,
+	textBeforeCursor: string,
+	prefix: string,
+): boolean {
+	const tokenStart = textBeforeCursor.length - prefix.length;
+	const textBeforeToken = [...lines.slice(0, cursorLine), textBeforeCursor.slice(0, tokenStart)].join("\n");
+	return isInsideInlineCodeSpan(textBeforeToken);
+}
+
 export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 	#baseProvider: CombinedAutocompleteProvider;
 	#actions: PromptActionDefinition[];
@@ -211,8 +228,13 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			}
 		}
 
+		const rawSlashPrefix = getRawSlashTokenPrefix(textBeforeCursor);
 		const slashPrefix = getSlashTokenPrefix(textBeforeCursor);
-		if (slashPrefix) {
+		const slashTokenInsideCode =
+			rawSlashPrefix !== null &&
+			(hasInlineCodeDelimiter(rawSlashPrefix) ||
+				isSlashTokenInsideInlineCodeSpan(lines, cursorLine, textBeforeCursor, rawSlashPrefix));
+		if (slashPrefix && !slashTokenInsideCode) {
 			const baseSuggestions = withoutSkillCommandSuggestions(
 				await this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol),
 			);
@@ -225,6 +247,9 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 				this.#commands,
 			);
 		}
+		if (rawSlashPrefix && slashTokenInsideCode) {
+			return withoutSkillCommandSuggestions(await this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol));
+		}
 
 		if (!isSettingsInitialized() || settings.get("emojiAutocomplete")) {
 			const emojiSuggestions = getEmojiSuggestions(textBeforeCursor);
@@ -282,12 +307,13 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			const currentLine = lines[cursorLine] || "";
 			const beforePrefix = currentLine.slice(0, cursorCol - prefix.length);
 			const afterCursor = currentLine.slice(cursorCol);
+			const separator = afterCursor.length === 0 ? " " : "";
 			const newLines = [...lines];
-			newLines[cursorLine] = `${beforePrefix}/${item.value} ${afterCursor}`;
+			newLines[cursorLine] = `${beforePrefix}/${item.value}${separator}${afterCursor}`;
 			return {
 				lines: newLines,
 				cursorLine,
-				cursorCol: beforePrefix.length + item.value.length + 2,
+				cursorCol: beforePrefix.length + item.value.length + 1 + separator.length,
 			};
 		}
 		return this.#baseProvider.applyCompletion(lines, cursorLine, cursorCol, item, prefix);

package/src/modes/runtime-init.ts

@@ -18,6 +18,7 @@ import {
 	syntheticNamespaceCollision,
 } from "../sdk/model-profile-model";
 import type { AgentSession } from "../session/agent-session";
+import { bashBackgroundControlError } from "../session/fold-coordinator";
 import { parseThinkingLevel } from "../thinking";
 import type { TodoPhase } from "../tools/todo-write";
 
@@ -68,8 +69,12 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 	runner.initialize(
 		// ExtensionActions
 		{
+			// Extension sends are INDEPENDENT producers, never continuations of the
+			// current turn: the trusted adapter classifies them so a terminal abort
+			// preserves them instead of dropping them as turn-owned work. Extensions
+			// never supply this bit themselves.
 			sendMessage: (message, sendOptions) => {
-				session.sendCustomMessage(message, sendOptions).catch(e => {
+				session.sendCustomMessage(message, { ...sendOptions, origin: "external" }).catch(e => {
 					reportSendError("extension_send", e instanceof Error ? e : new Error(String(e)));
 				});
 			},
@@ -154,8 +159,8 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 					session.setFollowUpMode(mode);
 					return true;
 				}
-				if (kind === "interrupt" && (mode === "immediate" || mode === "wait")) {
-					session.setInterruptMode(mode);
+				if (kind === "tool_interrupt" && (mode === "abort_tools" || mode === "finish_tools")) {
+					session.setToolInterruptPolicy(mode);
 					return true;
 				}
 				return false;
@@ -195,6 +200,7 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 				return { bytes: new Uint8Array(await file.slice(start, end).arrayBuffer()), totalBytes: file.size };
 			},
 			getJobs: () => session.getAsyncJobSnapshot(),
+			onJobFold: listener => session.onJobFold(listener),
 			setSdkPermissionProvider: provider => session.setSdkPermissionProvider(provider),
 			setSdkClientBridge: bridge => session.setClientBridge(bridge),
 			sdkControl: async (operation, input) => {
@@ -343,12 +349,9 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 						return { retried: true, immediate: true };
 					}
 					case "bash.background": {
-						if (!(await session.requestForegroundBashBackground()))
-							throw Object.assign(
-								new Error("The active bash command cannot be moved to a managed background job."),
-								{ code: "not_foldable" },
-							);
-						return { backgrounded: true };
+						const outcome = await session.requestForegroundBashBackgroundOutcome("sdk_control");
+						if (outcome.status !== "folded") throw bashBackgroundControlError(outcome);
+						return { backgrounded: true, jobId: outcome.jobId };
 					}
 					case "compaction.auto.set":
 						session.setAutoCompactionEnabled(input.on === true);

package/src/modes/theme/theme.ts

@@ -136,6 +136,7 @@ export type SymbolKey =
 	| "icon.output"
 	| "icon.host"
 	| "icon.session"
+	| "icon.star"
 	| "icon.package"
 	| "icon.warning"
 	| "icon.rewind"
@@ -300,6 +301,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.output": "⤴",
 	"icon.host": "🖥",
 	"icon.session": "🆔",
+	"icon.star": "★",
 	"icon.package": "📦",
 	"icon.warning": "⚠",
 	"icon.rewind": "↶",
@@ -534,6 +536,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.host": "\uf109",
 	// pick:  | alt:  
 	"icon.session": "\uf550",
+	"icon.star": "\uf005",
 	// pick:  | alt: 
 	"icon.package": "\uf487",
 	// pick:  | alt:  
@@ -722,6 +725,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.output": "out:",
 	"icon.host": "host",
 	"icon.session": "id",
+	"icon.star": "*",
 	"icon.package": "[P]",
 	"icon.warning": "[!]",
 	"icon.rewind": "<-",
@@ -1496,6 +1500,7 @@ export class Theme {
 			output: this.#symbols["icon.output"],
 			host: this.#symbols["icon.host"],
 			session: this.#symbols["icon.session"],
+			star: this.#symbols["icon.star"],
 			package: this.#symbols["icon.package"],
 			warning: this.#symbols["icon.warning"],
 			rewind: this.#symbols["icon.rewind"],

package/src/modes/types.ts

@@ -41,6 +41,8 @@ export type CompactionQueuedMessage = {
 	text: string;
 	mode: "steer" | "followUp";
 	followUpQueuePolicy?: "sequential";
+	/** Composer steers stay one per poll even under `steeringMode: "all"`. */
+	steerQueuePolicy?: "sequential";
 };
 
 export type SubmittedUserInput = {

package/src/modes/utils/ui-helpers.ts

@@ -1091,6 +1091,11 @@ export class UiHelpers {
 
 	queueCompactionMessage(text: string, mode: "steer" | "followUp", options?: ComposerSubmissionOptions): void {
 		const entry: CompactionQueuedMessage = { text, mode };
+		// A composer steer keeps the same one-per-poll delivery it would have had
+		// without compaction: the mark has to survive the park/replay round trip.
+		if (mode === "steer") {
+			entry.steerQueuePolicy = "sequential";
+		}
 		if (mode === "followUp") {
 			entry.followUpQueuePolicy = "sequential";
 		}
@@ -1115,6 +1120,11 @@ export class UiHelpers {
 		return message.followUpQueuePolicy ?? "sequential";
 	}
 
+	#compactionSteerQueuePolicy(message: CompactionQueuedMessage): "sequential" | undefined {
+		if (message.mode !== "steer") return undefined;
+		return message.steerQueuePolicy ?? "sequential";
+	}
+
 	async #deliverQueuedSkillMessage(message: CompactionQueuedMessage): Promise<boolean> {
 		const invocations = parseSkillInvocations(message.text, this.ctx.skillCommands ?? new Map());
 		if (invocations.length === 0) {
@@ -1163,7 +1173,10 @@ export class UiHelpers {
 							streamingBehavior: message.mode,
 							followUpQueuePolicy: this.#compactionFollowUpQueuePolicy(message),
 						}
-					: { streamingBehavior: message.mode };
+					: {
+							streamingBehavior: message.mode,
+							steerQueuePolicy: this.#compactionSteerQueuePolicy(message),
+						};
 			await this.ctx.session.promptCustomMessage(
 				{
 					customType: SKILL_PROMPT_MESSAGE_TYPE,
@@ -1196,7 +1209,10 @@ export class UiHelpers {
 				? this.ctx.session.followUp(message.text, undefined, {
 						followUpQueuePolicy: this.#compactionFollowUpQueuePolicy(message),
 					})
-				: this.ctx.session.steer(message.text),
+				: this.ctx.session.prompt(message.text, {
+						streamingBehavior: "steer",
+						steerQueuePolicy: this.#compactionSteerQueuePolicy(message),
+					}),
 		);
 	}
 
@@ -1310,7 +1326,10 @@ export class UiHelpers {
 							streamingBehavior: "followUp" as const,
 							followUpQueuePolicy: this.#compactionFollowUpQueuePolicy(firstPrompt),
 						}
-					: { streamingBehavior: "steer" as const };
+					: {
+							streamingBehavior: "steer" as const,
+							steerQueuePolicy: this.#compactionSteerQueuePolicy(firstPrompt),
+						};
 			const promptPromise = this.ctx.session.prompt(firstPrompt.text, firstPromptOptions).catch((error: unknown) => {
 				disposeFirstPrompt();
 				restoreQueue(error);

package/src/prompts/agent-fragments/browser-aside.md

@@ -0,0 +1,22 @@
+<browser-backend>
+Browser backend: Aside direct CLI. The built-in Puppeteer browser tool is disabled by configuration (`browser.backend: aside`). NEVER use or register an MCP browser server.
+
+Routing:
+- Every task that requires a rendered page, authenticated/private browser state, live tabs, browser UI, screenshots, downloads behind cookies, history, saved credentials, or profile data MUST use Bash to invoke the installed Aside CLI.
+- Default to `aside repl '<JavaScript>'` for deterministic Playwright inspection and actions, even when the answer is unknown but the procedure is discoverable from `snapshot(page, { interactive: true })`.
+- Use `aside exec '<prompt>'` only for runtime judgment, source-heavy research, browser-history search, MFA or opaque password autofill, approval/notification waits, long monitoring, multi-site synthesis, routines, or work worth a second model. Continue with `aside exec --session <id> '<follow-up>'`. Use `--account`, `--model`, `--provider`, `--speed`, or `--effort` only when the task requires overriding user defaults.
+- Cookie-free public HTTP content that does not require rendered or authenticated browser state may use GJC `read` directly.
+
+Deterministic procedure:
+- Each non-interactive `aside repl '<code>'` shell invocation starts from neutral local JavaScript scope: make it self-contained and do not depend on variables declared in an earlier invocation.
+- Call `listBrowserTabs()`, select by URL/title, `attachBrowserTab(targetId)`, then verify `page.url()` and `await page.title()` before reading or acting. Use `attachActiveBrowserTab()` only when active-tab authority is intentional; use `openTab()` only when no relevant tab exists.
+- Print results with `console.log`; returned and final-expression values are not emitted. Use `snapshot(page, { interactive: true })` before acting, prefer locators/refs, and verify every meaningful action with a fresh URL/title, snapshot diff, screenshot, or file path.
+- Use authenticated `fetch` for cookie-bearing downloads. Prefer dedicated integrations for Gmail, Google Docs/Sheets, YouTube, search, social, PDF, and Office files over manual UI automation.
+- Use `chrome.*` only for task-scoped tabs/windows/bookmarks/tab-groups/history/downloads/top-sites profile operations. Use `cua.*` only when DOM semantics cannot control canvas or visual UI; screenshot before and verify after. Use `captcha.*` only in an authorized user-owned session where automation is permitted.
+
+Safety:
+- Aside controls a live authenticated profile. Never print cookies, authorization headers, passwords, OTPs, card values, recovery material, signed URLs, raw task transcripts, private profile paths, or broad inbox/contact/history/session collections.
+- Read, inspect, draft, and preview by default. Sending/posting, accepting invitations, payments/purchases/subscriptions, credential saves, document edits, downloads to an external destination, settings/session/routine/channel changes, and destructive profile operations require explicit user intent for the exact target. Stop before the final side effect when authorization is ambiguous.
+- Permission rules (`allow`, `ask`, `deny`), password access policy, target origin, and file/network/download boundaries remain authoritative and must never be bypassed.
+- Load the installed GJC `aside` skill before a browser job when available; it contains the complete official API inventory and scenario matrix. Never claim browser work ran without the Aside CLI result and verified state.
+</browser-backend>

package/src/prompts/tools/ask.md

@@ -17,7 +17,7 @@ Asks user when you need clarification or input during task execution.
 <critical>
 - **Default to action.** Resolve ambiguity yourself using repo conventions, existing patterns, and reasonable defaults. Exhaust existing sources (code, configs, docs, history) before asking. Only ask when options have materially different tradeoffs the user must decide.
 - **If multiple choices are acceptable**, pick the most conservative/standard option and proceed; state the choice.
-- **Do NOT include "Other" option** — UI automatically adds "Other (type your own)" to every question.
+- **Do NOT include the automatic custom-input control or labels that imitate it** such as "Other (type your own)", "Other (specify)", "type your own", "custom input", or "직접 입력" — UI automatically adds "Other (type your own)" to every question. A plain domain value such as "Other" is allowed when it is a genuine answer, not a request for free text. To collect free text, ask for it in the question body and rely on the automatic Other/custom-input control instead of adding a fake option.
 </critical>
 
 <examples>

package/src/prompts/tools/bash.md

@@ -18,6 +18,7 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 {{/if}}
 {{#if foregroundFoldEnabled}}
 - In the interactive TUI, the user can press the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via the `app.tool.backgroundFold` keybinding) while a foreground command is still running to fold it into a background job. All three command surfaces fold: managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded command keeps its original timeout and is never killed or restarted by folding; a folded PTY continues output-only, so it stops accepting input. The turn then ends cleanly and a later turn resumes automatically with the command's result, so the interrupted task is finished rather than abandoned. `task`/`subagent` waits are deliberately NOT foldable. Do not instruct users to use raw shell `Ctrl+Z`/`bg` inside the GJC TUI; ownership and output routing are not safe there.
+- A user steer folds the same way: when the user sends a message while a foreground command has already run for at least 2 seconds, the command is folded into a background job and this call returns the background-start result plus the line `Folded into background job <id> because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.` The steer is then delivered at this tool boundary, so handle it next; do not re-run the folded command. Steers that arrive within the first 2 seconds let the command finish normally. This applies only while `busyPromptMode` is `steer` and `toolInterruptPolicy` is `abort_tools`.
 {{/if}}
 </instruction>
 {{#if restrictedAllowedPrefixes}}

package/src/prompts/tools/job.md

@@ -2,7 +2,7 @@ Inspects, waits, or cancels async jobs.
 
 Background job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.
 
-In the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.
+In the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` and `toolInterruptPolicy=abort_tools`). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.
 
 # Operations
 

package/src/sdk/acp/adapter.ts

@@ -91,6 +91,11 @@ const ACP_MCP_PRESERVED_LAUNCH_CODES = new Set([
 	"startup_admission_timeout",
 	"ready_then_exited",
 	"endpoint_unreadable",
+	"worktree_preparation_timeout",
+	"dependency_preparation_timeout",
+	"readiness_timeout",
+	"spawn_failed",
+	"worktree_in_use",
 ]);
 
 /**

package/src/sdk/broker/broker.ts

@@ -5,6 +5,7 @@ import * as os from "node:os";
 import path from "node:path";
 import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
 import { logger, resolveEquivalentPath } from "@gajae-code/utils";
+import packageJson from "../../../package.json" with { type: "json" };
 import type { ModelProfileErrorDetails } from "../../config/model-profile-contract";
 import { planLaunchWorktree } from "../../gjc-runtime/launch-worktree";
 import { SdkClient, SdkClientError } from "../client";
@@ -101,6 +102,10 @@ type ResolvedBrokerSettings = {
 	spawnPromptLayer?: SpawnPromptLayer;
 	masterOrphanGraceMs: number;
 };
+export function resolveBrokerPackageGeneration(): string {
+	const v = (packageJson as { version?: unknown }).version;
+	return typeof v === "string" && v.length > 0 ? v : "unknown";
+}
 
 function modelResolutionCwd(input: Record<string, unknown>): string | undefined {
 	const cwd = typeof input.cwd === "string" ? input.cwd : undefined;
@@ -132,6 +137,10 @@ export type BrokerErrorCode =
 	| "startup_admission_timeout"
 	| "startup_admission_refused"
 	| "readiness_timeout"
+	| "worktree_preparation_timeout"
+	| "dependency_preparation_timeout"
+	| "worktree_in_use"
+	| "incarnation_unavailable"
 	| "close_refused"
 	| "not_found"
 	| "live_session"
@@ -1280,7 +1289,7 @@ export class Broker {
 	constructor(settings: BrokerSettings) {
 		this.settings = {
 			agentDir: settings.agentDir,
-			packageGeneration: settings.packageGeneration ?? "unknown",
+			packageGeneration: settings.packageGeneration ?? resolveBrokerPackageGeneration(),
 			port: settings.port ?? 0,
 			heartbeatTtlMs: settings.heartbeatTtlMs ?? BROKER_HEARTBEAT_TTL_MS,
 			resolveDirectoryMigration: settings.resolveDirectoryMigration ?? (async () => "copy-retain"),

package/src/sdk/broker/ensure.ts

@@ -3,9 +3,21 @@ import { randomUUID } from "node:crypto";
 import type { FileHandle } from "node:fs/promises";
 import * as fs from "node:fs/promises";
 import path from "node:path";
+import packageJson from "../../../package.json" with { type: "json" };
+import { SdkClient } from "../client/client";
 import { type BrokerDiscovery, brokerProcessIncarnation, readBrokerDiscovery } from "./discovery";
 import { resolveSdkInternalSpawnCommand, type SdkInternalSpawnCommand } from "./runtime";
 import { BrokerStartupError, clearBrokerStartupFailureMarker, readBrokerStartupFailureMarker } from "./startup-failure";
+
+function resolveExpectedBrokerGeneration(): string {
+	const v = (packageJson as { version?: unknown }).version;
+	return typeof v === "string" && v.length > 0 ? v : "unknown";
+}
+
+function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean {
+	if (!discovery) return false;
+	return discovery.packageGeneration === resolveExpectedBrokerGeneration();
+}
 export interface EnsureBrokerSettings {
 	agentDir: string;
 	heartbeatTtlMs?: number;
@@ -248,6 +260,47 @@ function fixtureLeaseUnavailable(): Error {
 	return new Error("fixture_broker_lease_unavailable");
 }
 
+const STALE_BROKER_SHUTDOWN_TIMEOUT_MS = 5_000;
+const STALE_BROKER_POLL_MS = 50;
+
+type BrokerOwnerIdentity = Pick<BrokerDiscovery, "ownerId" | "pid" | "incarnation">;
+
+function sameBrokerOwner(left: BrokerOwnerIdentity | null, right: BrokerOwnerIdentity): boolean {
+	return Boolean(
+		left && left.ownerId === right.ownerId && left.pid === right.pid && left.incarnation === right.incarnation,
+	);
+}
+
+async function retireStaleBrokerGeneration(stale: BrokerDiscovery, settings: EnsureBrokerSettings): Promise<void> {
+	let shutdownSucceeded = false;
+	try {
+		const current = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (!current || !sameBrokerOwner(current, stale)) return;
+		const client = await SdkClient.connect(current.url, current.token, { timeoutMs: 2_000 });
+		try {
+			await client.global("broker.shutdown", {});
+			shutdownSucceeded = true;
+		} finally {
+			await client.close().catch(() => {});
+		}
+	} catch {}
+	if (!shutdownSucceeded) {
+		try {
+			if (brokerProcessIncarnation(stale.pid) === stale.incarnation) {
+				try {
+					process.kill(stale.pid, "SIGTERM");
+				} catch {}
+			}
+		} catch {}
+	}
+	// Wait for the stale identity to disappear (owner-fenced: pid+incarnation).
+	const deadline = Date.now() + STALE_BROKER_SHUTDOWN_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		const current = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (!sameBrokerOwner(current, stale)) break;
+		await sleep(STALE_BROKER_POLL_MS);
+	}
+}
 function createFixtureLeaseFromChild(child: ChildProcess, terminate: () => Promise<void>): ExactFixtureBrokerLease {
 	let termination: Promise<void> | undefined;
 	const hasExited = (): boolean => child.exitCode !== null || child.signalCode !== null || child.pid === undefined;
@@ -300,11 +353,24 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		if (priorOwner.canReuse(existing)) return { kind: "prior-local-owner", discovery: existing!, owner: priorOwner };
 		await priorOwner.stop();
 		const discoveredAfterCleanup = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
-		if (discoveredAfterCleanup) return { kind: "external-discovery", discovery: discoveredAfterCleanup };
+		if (discoveredAfterCleanup && isBrokerGenerationCompatible(discoveredAfterCleanup))
+			return { kind: "external-discovery", discovery: discoveredAfterCleanup };
+		// A stale-generation discovery after cleanup must not be reused — fall through to replacement.
+		if (!discoveredAfterCleanup) {
+			// no discovery left after cleanup — fall through to spawn
+		} else {
+			await retireStaleBrokerGeneration(discoveredAfterCleanup, settings);
+			const afterRetire = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+			if (afterRetire && isBrokerGenerationCompatible(afterRetire))
+				return { kind: "external-discovery", discovery: afterRetire };
+		}
 	} else if (existing) {
-		return { kind: "external-discovery", discovery: existing };
+		if (isBrokerGenerationCompatible(existing)) return { kind: "external-discovery", discovery: existing };
+		await retireStaleBrokerGeneration(existing, settings);
+		const afterRetire = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (afterRetire && isBrokerGenerationCompatible(afterRetire))
+			return { kind: "external-discovery", discovery: afterRetire };
 	}
-
 	const command = resolveSdkInternalSpawnCommand("broker-internal");
 	const spawnLog = await openBrokerSpawnLog(settings.agentDir);
 	// A stale marker must never be misattributed to this spawn; clear it first.
@@ -477,6 +543,13 @@ export function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBroker
 export function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined {
 	return owners.get(agentDir);
 }
+/** Test hook: verifies the complete broker owner identity used during stale retirement. */
+export function brokerOwnerIdentityMatchesForTest(
+	left: BrokerOwnerIdentity | null,
+	right: BrokerOwnerIdentity,
+): boolean {
+	return sameBrokerOwner(left, right);
+}
 /** Test hook: drives the detached-broker reap on a controllable child surface. */
 export function reapSpawnedBrokerForTest(child: ChildProcess, timing: ReapTiming = DEFAULT_REAP_TIMING): Promise<void> {
 	return reapSpawnedBroker(child, timing);

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

@@ -55,6 +55,7 @@ export interface LifecycleDurableEffectsReceipt {
 		cwdDigest: string;
 		created: boolean;
 		reused: boolean;
+		createdBranch: boolean;
 		branchDigest?: string;
 	};
 	transcript?: {
@@ -62,6 +63,11 @@ export interface LifecycleDurableEffectsReceipt {
 		contentDigest: string;
 	};
 	startup?: LifecycleStartupFailureReceipt;
+	timings?: {
+		worktreePreparationMs?: number;
+		dependencyPreparationMs?: number;
+		spawnAuthorizedAtOffsetMs?: number;
+	};
 	digest?: string;
 }