@sayknow-cli/coding-agent 0.6.6 → 0.6.8

package/src/modes/interactive-mode.ts

@@ -8,7 +8,9 @@ import {
 	Container,
 	clearRenderCache,
 	getRenderCacheRetainedBytes,
+	isKeyRelease,
 	Loader,
+	matchesKey,
 	onImageProtocolChanged,
 	ProcessTerminal,
 	Spacer,
@@ -224,8 +226,27 @@ export function resolveWelcomePetSkin(petMode: PetMode, themeName: string | unde
  * rail glyph a submitted prompt keeps in the transcript, colored by the editor's
  * border color (session accent, thinking level, shell/python mode).
  */
+/** Background band under the composer's input rows, so the line being typed stands out. */
+function composerInputBackground(): string | undefined {
+	try {
+		return theme.getBgAnsi("userMessageBg");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Canonical form of a session path, so /private/var and /var compare equal on macOS. */
+function canonicalPath(file: string): string {
+	try {
+		return fs.realpathSync(file);
+	} catch {
+		return path.resolve(file);
+	}
+}
+
 export function configureDefaultComposerChrome(editor: CustomEditor): void {
 	editor.setBorderVisible(false);
+	editor.setInputBackground(composerInputBackground());
 	editor.setClosedBorderBox(false);
 	editor.setPromptGutter(undefined);
 	editor.setRailGutter(theme.rail.user);
@@ -472,6 +493,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	#eventBus?: EventBus;
 	#eventBusUnsubscribers: Array<() => void> = [];
 	#welcomeComponent?: WelcomeComponent;
+	#welcomeInputUnsubscribe?: () => void;
+	/** Mouse reporting was switched on for the launch card and must be restored after it. */
+	#welcomeEnabledMouse = false;
 	#ircSplitView: IrcSplitViewComponent;
 	#ircSidebarAvailable = false;
 	#ircSidebarRequestedVisible = false;
@@ -764,11 +788,13 @@ export class InteractiveMode implements InteractiveModeContext {
 					resumeKey: this.keybindings.getKeys("app.session.resume")[0],
 					continueKey: this.keybindings.getKeys("app.session.continue")[0],
 					petSkin: resolveWelcomePetSkin(settings.get("pet.mode"), getCurrentThemeName()),
+					onOpenSession: session => void this.#openWelcomeSession(session),
 				},
 			);
 
 			this.ui.addChild(this.#welcomeComponent);
 			this.#welcomeComponent.playIntro(() => this.ui.requestRender());
+			this.#startWelcomeInteraction();
 		}
 
 		this.ui.addChild(this.#ircSplitView);
@@ -880,11 +906,15 @@ export class InteractiveMode implements InteractiveModeContext {
 					)
 					.then(sessions => {
 						if (this.#welcomeComponent !== welcomeComponent) return;
+						const current = this.#currentSessionFileCanonical();
 						welcomeComponent.setRecentSessions(
-							sessions.map(session => ({
-								name: session.name,
-								timeAgo: session.timeAgo,
-							})),
+							sessions
+								.filter(session => canonicalPath(session.path) !== current)
+								.map(session => ({
+									name: session.name,
+									timeAgo: session.timeAgo,
+									path: session.path,
+								})),
 						);
 						this.ui.requestRender();
 					})
@@ -1231,6 +1261,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 		// Re-read the glyph so a symbol-preset switch (unicode/nerd/ascii) reaches the rail.
 		this.editor.setRailGutter(theme.rail.user);
+		this.editor.setInputBackground(composerInputBackground());
 		this.editor.setPlaceholder(this.#getComposerPlaceholder());
 		this.#setComposerTopBorder();
 		this.ui.requestRender();
@@ -1433,6 +1464,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.loadingAnimation.stop();
 			this.loadingAnimation = undefined;
 		}
+		this.#endWelcomeInteraction();
 		this.#welcomeComponent?.dispose();
 		this.#welcomeComponent = undefined;
 		if (this.#sttController) {
@@ -2183,20 +2215,97 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#selectorController.showSessionSelector();
 	}
 
+	#currentSessionFileCanonical(): string | undefined {
+		const currentFile = this.sessionManager.getSessionFile();
+		return currentFile ? canonicalPath(currentFile) : undefined;
+	}
+
+	/**
+	 * The launch card's session rows take ↓/↑/Enter/Esc and clicks until the first prompt
+	 * is sent. Mouse reporting is switched on for that window (unless the user already
+	 * runs with it) so a click reaches the card; it goes back to the configured state when
+	 * the card stops taking input.
+	 */
+	#startWelcomeInteraction(): void {
+		this.#releaseWelcomeInput();
+		const welcome = this.#welcomeComponent;
+		if (!welcome) return;
+		this.#welcomeInputUnsubscribe = this.ui.addInputListener(data => this.#handleWelcomeKey(welcome, data));
+		if (settings.get("startup.welcomeMouse") && !this.ui.mouseEnabled) {
+			this.ui.setMouseEnabled(true);
+			this.#welcomeEnabledMouse = true;
+		}
+	}
+
+	/** The card stops taking input: first prompt sent, a session opened, or the UI rebuilt. */
+	endWelcomeInteraction(): void {
+		this.#endWelcomeInteraction();
+	}
+
+	/** Drop the card's key listener and give mouse reporting back to its configured state. */
+	#releaseWelcomeInput(): void {
+		this.#welcomeInputUnsubscribe?.();
+		this.#welcomeInputUnsubscribe = undefined;
+		if (this.#welcomeEnabledMouse) {
+			this.#welcomeEnabledMouse = false;
+			this.ui.setMouseEnabled(settings.get("mouse.enabled"));
+		}
+	}
+
+	#endWelcomeInteraction(): void {
+		this.#releaseWelcomeInput();
+		if (this.#welcomeComponent?.interactive) {
+			this.#welcomeComponent.endInteraction();
+			this.ui.requestRender();
+		}
+	}
+
+	/**
+	 * ↓ from an empty composer (not walking history) moves into the session rows; there,
+	 * ↑/↓ move, Enter opens, Esc (or ↑ past the first row) hands focus back. Any other key
+	 * leaves the rows and reaches the composer as usual.
+	 */
+	#handleWelcomeKey(welcome: WelcomeComponent, data: string): { consume: true } | undefined {
+		if (this.#welcomeComponent !== welcome || !welcome.interactive) return undefined;
+		if (this.ui.getFocusedComponent() !== this.editor) return undefined;
+		// Terminals with the kitty keyboard protocol (Ghostty, kitty, WezTerm) send a release
+		// event after every press. It is not a keystroke: treating it as "another key" cancelled
+		// the pick a ↓ had just made, so a single tap never moved the highlight.
+		if (isKeyRelease(data)) return undefined;
+		const picking = welcome.selectedIndex !== undefined;
+		if (!picking) {
+			if (!matchesKey(data, "down")) return undefined;
+			if (this.editor.getText() !== "" || this.editor.isBrowsingHistory() || this.editor.isShowingAutocomplete())
+				return undefined;
+			if (!welcome.select(0)) return undefined;
+			this.ui.requestRender();
+			return { consume: true };
+		}
+		if (matchesKey(data, "down")) welcome.moveSelection(1);
+		else if (matchesKey(data, "up")) welcome.moveSelection(-1);
+		else if (matchesKey(data, "enter")) welcome.openSelected();
+		else if (matchesKey(data, "escape")) welcome.select(undefined);
+		else {
+			welcome.select(undefined);
+			this.ui.requestRender();
+			return undefined;
+		}
+		this.ui.requestRender();
+		return { consume: true };
+	}
+
+	async #openWelcomeSession(session: RecentSession): Promise<void> {
+		if (!session.path) return;
+		this.#endWelcomeInteraction();
+		await this.handleResumeSession(session.path, { requireIdle: true });
+	}
+
 	async continueRecentSession(): Promise<void> {
 		// Listing returns canonical paths (/private/var on macOS); compare canonically so the
 		// live session is never "continued" into itself.
-		const canonical = (file: string): string => {
-			try {
-				return fs.realpathSync(file);
-			} catch {
-				return path.resolve(file);
-			}
-		};
-		const currentFile = this.sessionManager.getSessionFile();
-		const current = currentFile ? canonical(currentFile) : undefined;
+		const current = this.#currentSessionFileCanonical();
 		const recent = await getRecentSessions(this.sessionManager.getSessionDir());
-		const target = recent.find(session => canonical(session.path) !== current);
+		const target = recent.find(session => canonicalPath(session.path) !== current);
 		if (!target) {
 			this.showStatus("No earlier session to continue");
 			return;

package/src/modes/types.ts

@@ -329,6 +329,8 @@ export interface InteractiveModeContext {
 	showSessionSelector(): void;
 	/** Resume the most recent saved session other than this one (the launch card's first row). */
 	continueRecentSession(): Promise<void>;
+	/** The launch card stops taking ↓/Enter/clicks and releases mouse capture (first prompt sent). */
+	endWelcomeInteraction?(): void;
 	showSessionsDashboard(): void;
 	handleResumeSession(sessionPath: string, options?: { requireIdle?: boolean }): Promise<boolean>;
 	handleSessionDeleteCommand(): Promise<void>;

package/src/prompts/system/system-prompt.md

@@ -43,11 +43,16 @@ Optimize for correctness first, maintainability second, and brevity third. Prefe
 - Do not defer actionable work. Underpromise and overdeliver: report only what is done or in progress, never announce remaining work instead of doing it.
 </communication>
 
+<response-language>
+- Write every user-facing message in the language the user writes in (their latest message); a language they explicitly asked for wins.
+- This holds for the whole turn, including progress notes and the final report after long tool work. Tool output, logs, code, file contents, English skill or system text, and context summaries in another language never change it.
+- Keep code, commands, file paths, identifiers, and quoted output as they are; translate the prose around them.
+</response-language>
+
 {{#if reasoningLanguageEnglish}}
 <reasoning-language>
 - Reason through development and technical problem-solving in English.
-- Keep user-facing answers in the language the user requested or used.
-- This changes reasoning language only; it does not relax correctness, safety, or communication requirements.
+- This changes reasoning language only; user-facing answers still follow <response-language>, and it does not relax correctness, safety, or communication requirements.
 </reasoning-language>
 {{/if}}
 

package/src/prompts/tools/locate.md

@@ -0,0 +1,12 @@
+Find where behaviour lives by describing what the code does, when you do not know a file, symbol, or string to grep for.
+
+<instruction>
+- Ask a question about behaviour: "Where does the broker stop when idle?", "Which code picks fallback models?", "Which tests cover retry after a timeout?"
+- Returns ranked files with their declaration lines and line numbers. Read the listed lines next; the result is a lead, not proof, and it can miss files.
+- Use `search` or `find` instead when you already know an exact name, path, or string. They are faster and free.
+- Narrow `path` to the part of the repository you care about when you can.
+</instruction>
+
+<data>
+Relevance is judged by Jev (TypeSafe). It receives the question, folder paths, file names, and each candidate file's declaration lines (function, class, type, and constant signatures). It never receives function bodies or comments. Files ignored by .gitignore, hidden files, and binaries are skipped.
+</data>

package/src/sdk/broker/broker.ts

@@ -40,6 +40,18 @@ export interface BrokerSettings {
 	packageGeneration?: string;
 	port?: number;
 	heartbeatTtlMs?: number;
+	/**
+	 * Stop after this long with no connection, no request in flight and no live
+	 * session. Clients call `ensureBroker` before use, so the next one starts a fresh
+	 * broker. 0 disables. Default {@link BROKER_IDLE_SHUTDOWN_MS}.
+	 */
+	idleShutdownMs?: number;
+	/**
+	 * Runs at the start of every publication tick, before the tick calls into the
+	 * native addon. The broker process uses it to stop at once when its source
+	 * checkout has vanished (see `process-guard.ts`); return true to skip the tick.
+	 */
+	beforePublicationTick?: () => boolean;
 	/** Broker-owned migration policy. Client lifecycle frames cannot select it. */
 	resolveDirectoryMigration?: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
 }
@@ -49,6 +61,8 @@ type ResolvedBrokerSettings = {
 	packageGeneration: string;
 	port: number;
 	heartbeatTtlMs: number;
+	idleShutdownMs: number;
+	beforePublicationTick: () => boolean;
 	resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
 };
 
@@ -371,6 +385,12 @@ type BrokerLockSnapshot = {
 const BROKER_PUBLICATION_CADENCE_MS = 5_000;
 const BROKER_PUBLICATION_GRACE_MS = 15_000;
 const BROKER_SETTLEMENT_MS = 2_000;
+/**
+ * A broker with nothing to serve stops after this long. Without it a broker lived
+ * until killed: one started by a test (or a crashed client) whose caller never came
+ * back stayed up for days holding a port, memory and a mapped native addon.
+ */
+export const BROKER_IDLE_SHUTDOWN_MS = 30 * 60_000;
 type BrokerPublicationState =
 	| "healthy-owned"
 	| "suspect-unpublished"
@@ -400,12 +420,17 @@ export class Broker {
 	#completion!: Promise<void>;
 	#resolveCompletion!: () => void;
 	#rejectCompletion!: (error: unknown) => void;
+	/** Last time a client connected, disconnected, or sent a request. Drives idle shutdown. */
+	#lastActivityAt = Date.now();
+	#idleCheckInFlight = false;
 	constructor(settings: BrokerSettings) {
 		this.settings = {
 			agentDir: settings.agentDir,
 			packageGeneration: settings.packageGeneration ?? "unknown",
 			port: settings.port ?? 0,
 			heartbeatTtlMs: settings.heartbeatTtlMs ?? BROKER_HEARTBEAT_TTL_MS,
+			idleShutdownMs: Math.max(0, settings.idleShutdownMs ?? BROKER_IDLE_SHUTDOWN_MS),
+			beforePublicationTick: settings.beforePublicationTick ?? (() => false),
 			resolveDirectoryMigration: settings.resolveDirectoryMigration ?? (async () => "copy-retain"),
 		};
 		this.index = new SessionIndex(settings.agentDir);
@@ -598,7 +623,8 @@ export class Broker {
 				10,
 				Math.min(BROKER_PUBLICATION_CADENCE_MS, Math.floor(this.settings.heartbeatTtlMs / 3)),
 			);
-			this.#heartbeatTimer = setInterval(() => void this.#watchPublication(), cadenceMs);
+			this.#lastActivityAt = Date.now();
+			this.#heartbeatTimer = setInterval(() => void this.#publicationTick(), cadenceMs);
 			return this.discovery;
 		} catch (error) {
 			await this.#transport?.stop();
@@ -625,6 +651,52 @@ export class Broker {
 		if (kind === "suspect-unpublished") this.#lossAt ??= process.hrtime.bigint();
 		else this.#lossAt = null;
 	}
+	async #publicationTick(): Promise<void> {
+		// Before anything that reaches the native addon: the process guard may end the process here.
+		if (this.settings.beforePublicationTick()) return;
+		await this.#watchPublication();
+		if (this.#publicationState === "healthy-owned") await this.#stopIfIdle();
+	}
+	/** Record client activity; an active broker never idles out. */
+	noteActivity(): void {
+		this.#lastActivityAt = Date.now();
+	}
+	/**
+	 * Stop once nothing has used the broker for `idleShutdownMs`: no open client
+	 * connection, no request or lifecycle chain in flight, and no live session host
+	 * in the index. A stop from here is the ordinary owned-root stop, so discovery
+	 * and the lock are released and the next `ensureBroker` starts a new broker.
+	 */
+	async #stopIfIdle(): Promise<void> {
+		const idleMs = this.settings.idleShutdownMs;
+		if (idleMs <= 0 || this.#stopping || this.#idleCheckInFlight) return;
+		if (!this.#idleCandidate(idleMs)) return;
+		this.#idleCheckInFlight = true;
+		try {
+			await this.index.refresh();
+			if (this.index.listSessions().sessions.some(session => session.live)) {
+				// Live hosts keep the broker; look again after another idle window.
+				this.#lastActivityAt = Date.now();
+				return;
+			}
+			// Re-check: a client may have connected while the index was read.
+			if (this.#stopping || !this.#idleCandidate(idleMs)) return;
+			void this.#complete("owned-root");
+		} catch {
+			// An unreadable index is not evidence of idleness; try again next window.
+			this.#lastActivityAt = Date.now();
+		} finally {
+			this.#idleCheckInFlight = false;
+		}
+	}
+	#idleCandidate(idleMs: number): boolean {
+		return (
+			Date.now() - this.#lastActivityAt >= idleMs &&
+			(this.#transport?.openConnections ?? 0) === 0 &&
+			this.#admitted.size === 0 &&
+			this.#chains.size === 0
+		);
+	}
 	async #watchPublication(writeHeartbeat = true): Promise<void> {
 		if (!this.#publication || this.#publicationState === "stopping") return;
 		let observation: ReturnType<RetainedBrokerDiscovery["observe"]>;
@@ -747,12 +819,14 @@ export class Broker {
 	handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse> {
 		if (this.#stopping || (this.#publication !== null && this.#publicationState !== "healthy-owned"))
 			return Promise.resolve(error("unavailable", "broker publication is unavailable"));
+		this.#lastActivityAt = Date.now();
 		let release!: () => void;
 		const admission = new Promise<void>(resolve => (release = resolve));
 		this.#admitted.add(admission);
 		return this.#handleRequest(operation, input, idempotencyKey).finally(() => {
 			release();
 			this.#admitted.delete(admission);
+			this.#lastActivityAt = Date.now();
 		});
 	}
 	async #handleRequest(

package/src/sdk/broker/process-guard.ts

@@ -0,0 +1,160 @@
+import * as fs from "node:fs";
+
+/**
+ * Guards for the SDK's long-lived background processes (`sdk broker-internal`,
+ * `sdk session-host-internal`). They are spawned detached and outlive whoever
+ * started them, so each one has to notice on its own when it has no reason, or no
+ * way, to keep running.
+ */
+
+/** How often the guards run. Cheap: one `stat`, plus a small JSON read for hosts. */
+export const PROCESS_GUARD_INTERVAL_MS = 5_000;
+
+/**
+ * The entry script of a process run from source (`bun …/src/cli.ts sdk …`), or
+ * undefined for a compiled binary, whose entry lives in Bun's virtual filesystem
+ * and cannot disappear from under it.
+ */
+export function sourceEntryPath(main: string | undefined = Bun.main): string | undefined {
+	if (!main) return undefined;
+	if (main.startsWith("/$bunfs/") || /^[A-Za-z]:[\\/]~BUN[\\/]/.test(main)) return undefined;
+	return main;
+}
+
+/** Errors that mean the file is gone, or the volume holding it is: unmounted, ejected, or failing. */
+const SOURCE_GONE_CODES = new Set(["ENOENT", "ENOTDIR", "EIO", "ENXIO", "ENODEV"]);
+
+/** Whether the source entry is still reachable. A compiled binary (no entry) always is. */
+export function sourceEntryAvailable(
+	entry: string | undefined,
+	stat: (file: string) => unknown = file => fs.statSync(file),
+): boolean {
+	if (!entry) return true;
+	try {
+		stat(entry);
+		return true;
+	} catch (error) {
+		return !SOURCE_GONE_CODES.has((error as NodeJS.ErrnoException).code ?? "");
+	}
+}
+
+/**
+ * End this process at once when the source it runs from has vanished — typically
+ * an external drive with the checkout was unplugged. The native addon is mapped
+ * from that checkout and paged in lazily, so the next call into it faults on a
+ * page that can no longer be read, and Bun's fault handler then spins on the same
+ * unreadable mapping at 100% CPU forever. No cleanup is safe at that point (it
+ * would call into the same addon), so the process kills itself; readers already
+ * treat its discovery and markers as stale once the pid is gone.
+ *
+ * Call this before any native call in a periodic task. Returns true if it fired.
+ */
+export function exitIfSourceGone(
+	entry: string | undefined = sourceEntryPath(),
+	options: { stat?: (file: string) => unknown; kill?: () => void } = {},
+): boolean {
+	if (sourceEntryAvailable(entry, options.stat)) return false;
+	(options.kill ?? (() => process.kill(process.pid, "SIGKILL")))();
+	return true;
+}
+
+/** What a session host needs to recognise that its session is still its own. */
+export interface SessionHostAuthority {
+	/** `<stateRoot>/sdk/<sessionId>.lifecycle.json`, written once by the broker when it spawned this host. */
+	markerPath: string;
+	pid: number;
+	effectMarker: string;
+	incarnation: string;
+	/** The host's worktree. */
+	cwd: string;
+}
+
+/**
+ * `held`: the marker still names this process and the worktree exists. `lost`: the
+ * marker or worktree is gone, or the marker names another process — the session was
+ * deleted, taken over, or its whole state root was removed (a finished test). `unknown`:
+ * something could not be read for another reason; that is not evidence either way.
+ */
+export type SessionHostAuthorityState = "held" | "lost" | "unknown";
+
+const GONE_CODES = new Set(["ENOENT", "ENOTDIR"]);
+
+export function checkSessionHostAuthority(
+	authority: SessionHostAuthority,
+	io: { readFile?: (file: string) => string; stat?: (file: string) => unknown } = {},
+): SessionHostAuthorityState {
+	const readFile = io.readFile ?? (file => fs.readFileSync(file, "utf8"));
+	const stat = io.stat ?? (file => fs.statSync(file));
+	const code = (error: unknown) => (error as NodeJS.ErrnoException).code ?? "";
+	try {
+		stat(authority.cwd);
+	} catch (error) {
+		return GONE_CODES.has(code(error)) ? "lost" : "unknown";
+	}
+	let raw: string;
+	try {
+		raw = readFile(authority.markerPath);
+	} catch (error) {
+		return GONE_CODES.has(code(error)) ? "lost" : "unknown";
+	}
+	let marker: { pid?: unknown; effectMarker?: unknown; incarnation?: unknown };
+	try {
+		marker = JSON.parse(raw) as typeof marker;
+	} catch {
+		// The broker publishes the marker by atomic rename, so a torn read is not
+		// expected; still, one unparsable read alone does not end a live session.
+		return "unknown";
+	}
+	return marker.pid === authority.pid &&
+		marker.effectMarker === authority.effectMarker &&
+		marker.incarnation === authority.incarnation
+		? "held"
+		: "lost";
+}
+
+/** Consecutive `lost` checks before a host gives up its session (≈15s at the default interval). */
+export const SESSION_HOST_LOST_CHECKS = 3;
+
+/**
+ * Watch a running session host. It stops (through `onLost`, the host's normal
+ * shutdown) once its ownership marker or worktree has been gone for
+ * {@link SESSION_HOST_LOST_CHECKS} checks in a row, and kills itself at once if the
+ * source checkout it runs from disappears. Before this, a host whose session state
+ * had been deleted kept running until someone killed it — for days, after tests.
+ * Returns a function that stops the watch.
+ */
+export function startSessionHostGuard(
+	options: SessionHostAuthority & {
+		onLost: () => void;
+		intervalMs?: number;
+		lostChecks?: number;
+		check?: (authority: SessionHostAuthority) => SessionHostAuthorityState;
+		sourceGuard?: () => boolean;
+		setInterval?: typeof setInterval;
+		clearInterval?: typeof clearInterval;
+	},
+): () => void {
+	const testInterval = Number(process.env.SKC_SDK_TEST_HOST_GUARD_MS);
+	const intervalMs =
+		options.intervalMs ??
+		(Number.isFinite(testInterval) && testInterval > 0 ? testInterval : PROCESS_GUARD_INTERVAL_MS);
+	const lostChecks = options.lostChecks ?? SESSION_HOST_LOST_CHECKS;
+	const check = options.check ?? checkSessionHostAuthority;
+	const sourceGuard = options.sourceGuard ?? (() => exitIfSourceGone());
+	const set = options.setInterval ?? setInterval;
+	const clear = options.clearInterval ?? clearInterval;
+	let misses = 0;
+	let stopped = false;
+	const timer = set(() => {
+		if (stopped || sourceGuard()) return;
+		misses = check(options) === "lost" ? misses + 1 : 0;
+		if (misses < lostChecks) return;
+		stopped = true;
+		clear(timer);
+		options.onLost();
+	}, intervalMs);
+	return () => {
+		stopped = true;
+		clear(timer);
+	};
+}

package/src/sdk/broker/transport.ts

@@ -45,11 +45,16 @@ export class BrokerTransport {
 	readonly #requestedPort: number;
 	#server: Bun.Server<undefined> | null = null;
 	#port = 0;
+	#openConnections = 0;
 	constructor(broker: Broker, token: string, port = 0) {
 		this.#broker = broker;
 		this.#token = token;
 		this.#requestedPort = port;
 	}
+	/** Client WebSockets currently open. The broker does not idle out while any is. */
+	get openConnections(): number {
+		return this.#openConnections;
+	}
 	get port(): number {
 		if (!this.#server) throw new Error("Broker transport is not running");
 		return this.#port;
@@ -71,7 +76,15 @@ export class BrokerTransport {
 			},
 			websocket: {
 				maxPayloadLength: MAX_BROKER_JSON_FRAME_BYTES * 2,
-				open: socket => send(socket, { type: "broker_hello", protocolVersion: PROTOCOL_VERSION }),
+				open: socket => {
+					this.#openConnections += 1;
+					this.#broker.noteActivity();
+					send(socket, { type: "broker_hello", protocolVersion: PROTOCOL_VERSION });
+				},
+				close: () => {
+					this.#openConnections = Math.max(0, this.#openConnections - 1);
+					this.#broker.noteActivity();
+				},
 				message: (socket, message) => void this.#handleMessage(socket, message),
 			},
 		});
@@ -82,6 +95,7 @@ export class BrokerTransport {
 		const server = this.#server;
 		this.#server = null;
 		if (server) await server.stop(true);
+		this.#openConnections = 0;
 	}
 	async #handleMessage(socket: ServerWebSocket<unknown>, raw: string | Buffer): Promise<void> {
 		if (Buffer.byteLength(raw) > MAX_BROKER_JSON_FRAME_BYTES) {

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

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { ensureBroker } from "../broker/ensure";
 import { type IndexedSession, SessionIndex } from "../broker/session-index";
 import { SdkClient, SdkClientError } from "../client/client";
 import { readSdkBrokerDiscovery, readSdkSessionEndpoint, type SdkSessionEndpoint } from "../client/discovery";
@@ -61,6 +62,8 @@ export interface ChatDaemonRuntimeDeps {
 	createClient?: (endpoint: SdkSessionEndpoint) => Promise<ChatDaemonSdkClient>;
 	createIndex?: (agentDir: string) => SessionIndex;
 	createBrokerClient?: (endpoint: { url: string; token: string }) => Promise<ChatDaemonSdkClient>;
+	/** Starts the agent broker when none is running (default: `ensureBroker`). */
+	ensureBroker?: (settings: { agentDir: string }) => Promise<unknown>;
 	onReconciled?: () => void;
 	setInterval?: typeof setInterval;
 	clearInterval?: typeof clearInterval;
@@ -480,7 +483,16 @@ export class ChatDaemonRuntime {
 		input: Record<string, unknown>,
 		idempotencyKey: string,
 	): Promise<Record<string, unknown>> {
-		const discovery = await readSdkBrokerDiscovery(this.input.agentDir);
+		let discovery = await readSdkBrokerDiscovery(this.input.agentDir);
+		if (!discovery) {
+			// A broker with nothing to serve stops on its own; start a fresh one for this command.
+			try {
+				await (this.deps.ensureBroker ?? ensureBroker)({ agentDir: this.input.agentDir });
+			} catch {
+				throw new ChatDeliveryError("pre_send");
+			}
+			discovery = await readSdkBrokerDiscovery(this.input.agentDir);
+		}
 		if (!discovery) throw new ChatDeliveryError("pre_send");
 		let client: ChatDaemonSdkClient;
 		try {

package/src/sdk/protocol/operation-inventory.generated.json

@@ -1771,6 +1771,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "slash_command:fallback",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "exclude",
+		"rationale": "local fallback-chain configuration (fallback.models / fallback.auto settings); no SDK operation counterpart, and SDK clients observe switches via model_fallback_switched",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "slash_command:effort",
 		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
@@ -4419,6 +4430,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "agent_session:getDefaultFallbackChain",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal profile and fallback-chain state, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:abortRetry",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/session.ts

@@ -110,7 +110,7 @@ import {
 } from "../secrets";
 import { AgentSession, type ForkContextSeed } from "../session/agent-session";
 import type { AuthStorage } from "../session/auth-storage";
-import { discoverAuthStorage } from "../session/auth-storage-discovery";
+import { applyCredentialRankingModeSetting, discoverAuthStorage } from "../session/auth-storage-discovery";
 import { type CustomMessage, convertToLlm } from "../session/messages";
 import { createReadonlySessionManager, SessionManager } from "../session/session-manager";
 import { formatNoModelsAvailableFallback } from "../setup/model-onboarding-guidance";
@@ -1057,6 +1057,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 		const settings = options.settings ?? (await logger.time("settings", Settings.init, { cwd, agentDir }));
 		modelRegistry.applyConfiguredModelBindings(settings);
+		// Multi-account order comes from settings (the env var still overrides it); apply it
+		// before the first model-availability probe picks an account for this session.
+		applyCredentialRankingModeSetting(authStorage, settings);
 		logger.time("initializeWithSettings", initializeWithSettings, settings);
 		const canRefreshModelsBeforeCredentialSelector =
 			!options.credentialSelector || runtimeCredentialSelectorInstalled || options.modelRegistry !== undefined;