@sayknow-cli/coding-agent 0.6.5 → 0.6.7

package/src/modes/controllers/input-controller.ts

@@ -112,6 +112,9 @@ export class InputController {
 			"app.session.tree": () => this.ctx.showTreeSelector(),
 			"app.session.fork": () => this.ctx.showUserMessageSelector(),
 			"app.session.resume": () => this.ctx.showSessionSelector(),
+			"app.session.continue": async () => {
+				await this.ctx.continueRecentSession();
+			},
 			"app.session.observe": async () => {
 				await this.ctx.showSessionObserver();
 			},
@@ -710,6 +713,16 @@ export class InputController {
 				return true;
 			});
 		}
+		this.#registerCommandPaletteAction("app.session.continue", () => {
+			void this.ctx.continueRecentSession();
+			return undefined;
+		});
+		for (const key of this.ctx.keybindings.getKeys("app.session.continue")) {
+			this.ctx.editor.setCustomKeyHandler(key, () => {
+				this.#executeAction("app.session.continue");
+				return true;
+			});
+		}
 		this.#registerCommandPaletteAction(
 			"app.message.followUp",
 			() => this.#executeAction("app.message.followUp"),
@@ -835,6 +848,8 @@ export class InputController {
 
 	async submitText(text: string, composer: ComposerSubmissionOptions): Promise<void> {
 		text = text.trim();
+		// Past the launch card: give the mouse back to the terminal and stop offering its rows.
+		if (text) this.ctx.endWelcomeInteraction?.();
 		if ((!isSettingsInitialized() || settings.get("emojiAutocomplete")) && text) text = expandEmoticons(text);
 		if (this.ctx.hasActiveBtw()) {
 			if (!text) return;

package/src/modes/controllers/selector-controller.ts

@@ -70,6 +70,7 @@ import {
 } from "../../sdk/bus/telegram-daemon";
 import { TelegramDaemonController } from "../../sdk/bus/telegram-daemon-control";
 import { runTelegramSetup, type TelegramSetupPreflight } from "../../sdk/bus/telegram-setup";
+import { applyCredentialRankingModeSetting } from "../../session/auth-storage-discovery";
 import { type SessionInfo, SessionManager } from "../../session/session-manager";
 import { getTreeForInternalRead } from "../../session/session-manager-internal";
 
@@ -1372,6 +1373,18 @@ export class SelectorController {
 					});
 				break;
 			}
+			case "auth.credentialRankingMode": {
+				const effective = applyCredentialRankingModeSetting(
+					this.ctx.session.modelRegistry.authStorage,
+					this.ctx.settings,
+				);
+				if (effective !== value) {
+					this.ctx.showWarning(
+						`SKC_CREDENTIAL_RANKING_MODE=${effective} is set, so it overrides this setting on this machine.`,
+					);
+				}
+				break;
+			}
 			case "clearOnShrink":
 				this.ctx.ui.setClearOnShrink(value as boolean);
 				break;

package/src/modes/interactive-mode.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { type Agent, type AgentMessage, ThinkingLevel } from "@sayknow-cli/agent-core";
 import type { CompactionOutcome } from "@sayknow-cli/agent-core/compaction";
@@ -8,6 +9,7 @@ import {
 	clearRenderCache,
 	getRenderCacheRetainedBytes,
 	Loader,
+	matchesKey,
 	onImageProtocolChanged,
 	ProcessTerminal,
 	Spacer,
@@ -25,7 +27,6 @@ import {
 	KeybindingsManager,
 	type KeyDisplayContext,
 } from "../config/keybindings";
-import { getModelProfilePresentation } from "../config/model-profiles";
 import { isSettingsInitialized, type Settings, settings } from "../config/settings";
 import { DEFAULT_SKC_DEFINITION_NAMES } from "../defaults/skc-defaults";
 import type {
@@ -48,7 +49,6 @@ import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import { getRecentSessions, getSessionMessageEntryId } from "../session/session-manager";
-import { loadProjectContextFiles } from "../system-prompt";
 import type { LspStartupServerInfo } from "../tools";
 import { shortenPath } from "../tools/render-utils";
 import { formatPhaseDisplayName } from "../tools/todo-write";
@@ -72,19 +72,12 @@ import {
 	isPetCapabilityProbePending,
 	warnWhenPetCapabilitySettled,
 } from "./components/pet-capability";
-import { type PetMode, SayknowPetWidget } from "./components/sayknow-pet-widget";
+import { type PetMode, type PetSkinId, SayknowPetWidget } from "./components/sayknow-pet-widget";
 import { resolveCurrentBranch } from "./components/status-line/git-utils";
 import type { ToolExecutionHandle } from "./components/tool-execution";
 import { StatusLineComponent } from "./components/tool-status-header";
 import { composeToolText } from "./components/tool-transcript-format";
-import {
-	type RecentSession,
-	WelcomeComponent,
-	type WelcomeLogoMode,
-	type LspServerInfo as WelcomeLspServerInfo,
-	type WelcomeRoleBinding,
-	type WelcomeSnapshot,
-} from "./components/welcome";
+import { type RecentSession, WelcomeComponent, type WelcomeLogoMode, type WelcomeSnapshot } from "./components/welcome";
 import { BtwController } from "./controllers/btw-controller";
 import { CommandController } from "./controllers/command-controller";
 import { EventController } from "./controllers/event-controller";
@@ -107,7 +100,14 @@ import { shouldShowExtensionCommand } from "./slash-command-visibility";
 import { TasksAggregator } from "./tasks-aggregator";
 import { type ShimmerPalette, shimmerSegments, shimmerText } from "./theme/shimmer";
 import type { Theme } from "./theme/theme";
-import { getEditorTheme, getSymbolTheme, onTerminalAppearanceChange, onThemeChange, theme } from "./theme/theme";
+import {
+	getCurrentThemeName,
+	getEditorTheme,
+	getSymbolTheme,
+	onTerminalAppearanceChange,
+	onThemeChange,
+	theme,
+} from "./theme/theme";
 import { type RegisterTranscriptItem, TranscriptItemRegistry, transcriptItemId } from "./transcript-item-registry";
 import {
 	type CompactionQueuedMessage,
@@ -211,13 +211,41 @@ function getShellInputPrefix(isNoContext: boolean): string {
 	return `${shellLabel} `;
 }
 
+/**
+ * The pet on the launch card: the one the user keeps beside the composer, or —
+ * with the pet off — the skin that matches the theme (blue for blue-octopus).
+ */
+export function resolveWelcomePetSkin(petMode: PetMode, themeName: string | undefined): PetSkinId {
+	if (petMode !== "off") return petMode;
+	return themeName?.startsWith("blue") ? "blue" : "red";
+}
+
 /**
  * The composer is an open rail, not a box: every input row starts with the same
  * 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);
@@ -464,6 +492,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;
@@ -743,7 +774,6 @@ export class InteractiveMode implements InteractiveModeContext {
 				modelName,
 				providerName,
 				recentSessions,
-				this.#getWelcomeLspServers(),
 				welcomeLogoMode,
 				{
 					getViewportRows: () => this.ui.terminal.rows,
@@ -755,11 +785,15 @@ export class InteractiveMode implements InteractiveModeContext {
 					skipLogoAnimation,
 					snapshot: this.#buildWelcomeSnapshot(),
 					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);
@@ -871,11 +905,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();
 					})
@@ -1222,6 +1260,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();
@@ -1424,6 +1463,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.loadingAnimation.stop();
 			this.loadingAnimation = undefined;
 		}
+		this.#endWelcomeInteraction();
 		this.#welcomeComponent?.dispose();
 		this.#welcomeComponent = undefined;
 		if (this.#sttController) {
@@ -1611,36 +1651,13 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 
 	#handleLspStartupEvent(event: LspStartupEvent): void {
-		this.#updateWelcomeLspServers();
-
 		const warningMessage = getLspStartupWarningMessage(event);
 		if (warningMessage) {
 			this.showWarning(warningMessage);
 		}
 	}
 
-	#getWelcomeLspServers(): WelcomeLspServerInfo[] {
-		return (
-			this.lspServers?.map(server => ({
-				name: server.name,
-				status: server.status,
-				fileTypes: server.fileTypes,
-			})) ?? []
-		);
-	}
-
-	#updateWelcomeLspServers(): void {
-		if (!this.#welcomeComponent) {
-			return;
-		}
-
-		this.#welcomeComponent.setLspServers(this.#getWelcomeLspServers());
-		// LSP startup settles around the same time the MCP connections do.
-		this.#welcomeComponent.setSnapshot({ mcp: this.#welcomeMcpSummary() });
-		this.ui.requestRender();
-	}
-
-	/** Facts the launch ledger can show synchronously, before any probe runs. */
+	/** Facts the launch card can show synchronously, before the git probe runs. */
 	#buildWelcomeSnapshot(): WelcomeSnapshot {
 		const projectDir = getProjectDir();
 		let branch: string | null = null;
@@ -1649,68 +1666,19 @@ export class InteractiveMode implements InteractiveModeContext {
 		} catch {
 			branch = null;
 		}
-		const profileName = this.session.getActiveModelProfile() ?? settings.get("modelProfile.default");
-		return {
-			cwd: shortenPath(projectDir),
-			branch,
-			thinkingLevel: this.session.thinkingLevel,
-			profile: profileName ? getModelProfilePresentation(profileName).displayName : undefined,
-			roles: this.#welcomeRoleBindings(),
-			mcp: this.#welcomeMcpSummary(),
-			skills: this.session.skills.length,
-		};
-	}
-
-	/** Role agents in their canonical order, with the provider prefix dropped for width. */
-	#welcomeRoleBindings(): WelcomeRoleBinding[] {
-		const overrides = settings.get("task.agentModelOverrides") as Record<string, unknown> | undefined;
-		if (!overrides) return [];
-		const bindings: WelcomeRoleBinding[] = [];
-		for (const role of ["executor", "planner", "critic", "architect"]) {
-			const selector = overrides[role];
-			if (typeof selector !== "string" || selector.length === 0) continue;
-			const slash = selector.indexOf("/");
-			bindings.push({ role, model: slash >= 0 ? selector.slice(slash + 1) : selector });
-		}
-		return bindings;
-	}
-
-	#welcomeMcpSummary(): { connected: number; total: number } {
-		const manager = this.mcpManager;
-		if (!manager) return { connected: 0, total: 0 };
-		return { connected: manager.getConnectedServers().length, total: manager.getAllServerNames().length };
+		return { cwd: shortenPath(projectDir), branch, thinkingLevel: this.session.thinkingLevel };
 	}
 
-	/** Fill in the ledger facts that need I/O: git change counts and project instruction files. */
+	/** Fill in the git change counts, which need I/O. */
 	#probeWelcomeWorkspace(welcomeComponent: WelcomeComponent): void {
-		const projectDir = getProjectDir();
-		const apply = (patch: WelcomeSnapshot): void => {
-			if (this.#welcomeComponent !== welcomeComponent) return;
-			welcomeComponent.setSnapshot(patch);
-			this.ui.requestRender();
-		};
 		void gitUtils.status
-			.summary(projectDir)
-			.then(gitChanges => apply({ gitChanges }))
-			.catch(() => apply({ gitChanges: null }));
-		void gitUtils.log
-			.onelines(projectDir, 3)
-			.then(recentCommits => apply({ recentCommits }))
+			.summary(getProjectDir())
+			.then(gitChanges => {
+				if (this.#welcomeComponent !== welcomeComponent) return;
+				welcomeComponent.setSnapshot({ gitChanges });
+				this.ui.requestRender();
+			})
 			.catch(() => {});
-		void loadProjectContextFiles({ cwd: projectDir })
-			.then(files =>
-				apply({
-					contextFiles: files.map(file => {
-						const relative = path.relative(projectDir, file.path);
-						return relative.startsWith("..") ? shortenPath(file.path) : relative;
-					}),
-				}),
-			)
-			.catch(error => {
-				logger.debug("Failed to load context files for welcome screen", {
-					error: error instanceof Error ? error.message : String(error),
-				});
-			});
 	}
 
 	#getWorkingMessageAccent(): WorkingMessageAccent | undefined {
@@ -2246,6 +2214,100 @@ 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;
+		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 current = this.#currentSessionFileCanonical();
+		const recent = await getRecentSessions(this.sessionManager.getSessionDir());
+		const target = recent.find(session => canonicalPath(session.path) !== current);
+		if (!target) {
+			this.showStatus("No earlier session to continue");
+			return;
+		}
+		await this.handleResumeSession(target.path, { requireIdle: true });
+	}
+
 	handleResumeSession(sessionPath: string, options?: { requireIdle?: boolean }): Promise<boolean> {
 		return this.#selectorController.handleResumeSession(sessionPath, options, () => {
 			this.#btwController.dispose();

package/src/modes/types.ts

@@ -327,6 +327,10 @@ export interface InteractiveModeContext {
 	showUserMessageSelector(): void;
 	showTreeSelector(): void;
 	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(