@f5-sales-demo/xcsh 19.57.2 → 19.58.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.57.2",
+	"version": "19.58.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -55,13 +55,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.57.2",
-		"@f5-sales-demo/pi-agent-core": "19.57.2",
-		"@f5-sales-demo/pi-ai": "19.57.2",
-		"@f5-sales-demo/pi-natives": "19.57.2",
-		"@f5-sales-demo/pi-resource-management": "19.57.2",
-		"@f5-sales-demo/pi-tui": "19.57.2",
-		"@f5-sales-demo/pi-utils": "19.57.2",
+		"@f5-sales-demo/xcsh-stats": "19.58.1",
+		"@f5-sales-demo/pi-agent-core": "19.58.1",
+		"@f5-sales-demo/pi-ai": "19.58.1",
+		"@f5-sales-demo/pi-natives": "19.58.1",
+		"@f5-sales-demo/pi-resource-management": "19.58.1",
+		"@f5-sales-demo/pi-tui": "19.58.1",
+		"@f5-sales-demo/pi-utils": "19.58.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/commands/manager-core.ts

@@ -51,3 +51,16 @@ export function staleKeys(reg: Registry, now: number, idleMs: number): string[]
 	for (const w of reg.values()) if (now - w.lastSeen > idleMs) out.push(w.sessionId);
 	return out;
 }
+
+/** How many new spares to spawn now to reach `target`, without exceeding the port
+ * budget: spares + active workers must fit the discovery range. Never negative. */
+export function sparesToSpawn(
+	target: number,
+	currentSpares: number,
+	activeWorkers: number,
+	totalPorts: number,
+): number {
+	const want = Math.max(0, target - currentSpares);
+	const freeSlots = Math.max(0, totalPorts - activeWorkers - currentSpares);
+	return Math.min(want, freeSlots);
+}

package/src/commands/manager.ts

@@ -21,7 +21,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { portCandidates } from "../browser/extension-bridge";
-import { needsProvision, parseControlMsg, pickPort, type Registry, staleKeys } from "./manager-core";
+import { needsProvision, parseControlMsg, pickPort, type Registry, sparesToSpawn, staleKeys } from "./manager-core";
 
 /** Reap a worker idle longer than this (ms). */
 const IDLE_MS = 20 * 60_000;
@@ -130,6 +130,80 @@ export default class Manager extends Command {
 		const reg: Registry = new Map();
 		const range = portCandidates();
 
+		const poolTarget = Math.max(0, Math.trunc(Number(process.env.XCSH_WORKER_POOL_SIZE ?? "2")) || 0);
+		interface SpareRec {
+			proc: Bun.Subprocess;
+			port: number;
+			pid: number;
+		}
+		const pool: SpareRec[] = [];
+
+		const spawnSpare = (): void => {
+			const usedPorts = new Set<number>([...reg.values()].map(w => w.port).concat(pool.map(s => s.port)));
+			const port = pickPort(
+				reg,
+				range.filter(p => !usedPorts.has(p) && isPortFree(p)),
+			);
+			if (port === null) return; // range full — do not pre-warm
+			const proc = Bun.spawn([process.execPath, ...workerArgv()], {
+				env: {
+					...process.env,
+					XCSH_BROWSER_PROVIDER: "extension",
+					XCSH_BRIDGE_PORT: String(port),
+					// Identity-less spare: NO XCSH_SESSION_ID / XCSH_SESSION_TENANT (bound later via IPC).
+					// The spare marker makes sdk.ts skip its create-time context bootstrap, so the
+					// spare never boot-activates a tenant's context/credentials before its IPC bind
+					// (see shouldRunSessionContextBootstrap). Explicitly clear session identity too so
+					// the spare can never inherit an ambient session from the manager's env.
+					XCSH_WORKER_SPARE: "1",
+					XCSH_SESSION_ID: undefined,
+					XCSH_SESSION_TENANT: undefined,
+					XCSH_API_URL: undefined,
+					XCSH_API_TOKEN: undefined,
+				},
+				ipc() {}, // enable Bun parent→child IPC; no worker→manager messages needed today
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			const rec: SpareRec = { proc, port, pid: proc.pid };
+			pool.push(rec);
+			proc.exited.then(() => {
+				const i = pool.indexOf(rec);
+				if (i >= 0) pool.splice(i, 1); // a live spare died → drop + replenish
+				maintainPool();
+			});
+			console.error(`[xcsh manager] pre-warmed spare → pid ${proc.pid} on port ${port}`);
+		};
+
+		const maintainPool = (): void => {
+			const n = sparesToSpawn(poolTarget, pool.length, reg.size, range.length);
+			for (let i = 0; i < n; i++) spawnSpare();
+		};
+
+		/** Adopt a warm spare for a provision (bind over IPC). Returns false if none available. */
+		const adoptSpare = (msg: { sessionId: string; tenant: string }): boolean => {
+			const rec = pool.shift();
+			if (!rec) return false;
+			// `send` exists because the spare was spawned with an `ipc` handler.
+			(rec.proc as { send(m: unknown): void }).send({ type: "bind", sessionId: msg.sessionId, tenant: msg.tenant });
+			reg.set(msg.sessionId, {
+				sessionId: msg.sessionId,
+				tenant: msg.tenant,
+				port: rec.port,
+				pid: rec.pid,
+				lastSeen: Date.now(),
+			});
+			rec.proc.exited.then(() => {
+				const cur = reg.get(msg.sessionId);
+				if (cur && cur.pid === rec.pid) reg.delete(msg.sessionId);
+			});
+			maintainPool(); // replenish the consumed spare
+			console.error(
+				`[xcsh manager] adopted spare pid ${rec.pid} on port ${rec.port} as ${msg.sessionId} (${msg.tenant})`,
+			);
+			return true;
+		};
+
 		const reap = (sessionId: string): void => {
 			const w = reg.get(sessionId);
 			if (!w) return;
@@ -195,7 +269,9 @@ export default class Manager extends Command {
 			const msg = parseControlMsg(raw);
 			if (!msg) return; // fail closed on unknown/invalid frames
 			if (msg.type === "provision") {
-				if (needsProvision(reg, msg.sessionId)) spawnWorker(msg);
+				if (needsProvision(reg, msg.sessionId)) {
+					if (!adoptSpare(msg)) spawnWorker(msg); // adopt a warm spare, else cold-spawn (fallback)
+				}
 				const w = reg.get(msg.sessionId);
 				if (w) w.lastSeen = Date.now(); // touch on every provision (keep-alive)
 			} else if (msg.type === "release") {
@@ -255,6 +331,9 @@ export default class Manager extends Command {
 		}
 		console.error(`[xcsh manager] control socket listening at ${sockPath}`);
 
+		// Pre-warm the spare pool so provisions can adopt instead of cold-spawn.
+		if (poolTarget > 0) maintainPool();
+
 		// Idle sweep: reap workers untouched for longer than the TTL.
 		setInterval(() => {
 			for (const key of staleKeys(reg, Date.now(), IDLE_MS)) reap(key);

package/src/commands/worker.ts

@@ -21,13 +21,28 @@ import { createExtensionBridgeTools, EXTENSION_AGENT_TOOL_NAMES } from "../brows
 import { setSharedBridgeServer } from "../browser/provider";
 import { initializeWithSettings } from "../discovery";
 import { createAgentSession } from "../sdk";
+import { activateTenantContext } from "../services/session-context-binding";
 import { ContextService } from "../services/xcsh-context";
 import { sessionKeyFromUrl } from "../services/xcsh-env";
 
+/** Mutable worker identity. Seeded from env at spawn (backward compat); replaced by a
+ * late IPC bind on a pre-warmed spare. `null` fields fall back to env, then the "spare"
+ * sentinel (a non-`tab-<id>` string the extension registers but never binds to a tab). */
+let boundIdentity: { sessionId: string; tenantKey: string } | null = null;
+
+export function setWorkerIdentity(sessionId: string, tenantKey: string): void {
+	boundIdentity = { sessionId, tenantKey };
+}
+/** Test-only: clear late-bind state so env-seeded cases are deterministic. */
+export function resetWorkerIdentity(): void {
+	boundIdentity = null;
+}
+
 /** Tenant identity for the `hello` handshake. The active context wins; when the
- * worker is contextless we parse `XCSH_SESSION_TENANT` (`tenant|env`) so the panel
- * still learns which tenant this process serves (apiUrl stays null). Must be sync —
- * the bridge invokes it synchronously while answering `hello`. */
+ * worker is contextless we parse the bound tenant (or `XCSH_SESSION_TENANT`,
+ * `tenant|env`) so the panel still learns which tenant this process serves (apiUrl
+ * stays null). Must be sync — the bridge invokes it synchronously while answering
+ * `hello`. */
 export function sessionInfoForWorker(): {
 	tenant: string | null;
 	env: string | null;
@@ -35,9 +50,10 @@ export function sessionInfoForWorker(): {
 	contextBound: boolean;
 	sessionId: string | null;
 } {
-	// The tab session key the manager spawned this worker for; echoed in hello_ack
-	// so the extension can correlate a discovered worker back to the provisioned tab.
-	const sessionId = process.env.XCSH_SESSION_ID ?? null;
+	// The tab session key this worker serves; echoed in hello_ack so the extension can
+	// correlate a discovered worker back to a provisioned tab. A late IPC bind wins over
+	// the spawn env; an unbound spare advertises the "spare" sentinel.
+	const sessionId = boundIdentity?.sessionId ?? process.env.XCSH_SESSION_ID ?? "spare";
 	let apiUrl: string | null = null;
 	let contextBound = false;
 	try {
@@ -45,15 +61,15 @@ export function sessionInfoForWorker(): {
 		// A worker is "context-bound" when it has an active stored context (not just an env-derived apiUrl).
 		contextBound = ContextService.instance.getStatus().activeContextName != null;
 	} catch {
-		/* ContextService not initialized — fall through to env; contextBound stays false. */
+		/* ContextService not initialized — fall through to the tenant key; contextBound stays false. */
 	}
 	apiUrl = apiUrl ?? process.env.XCSH_API_URL ?? null;
 	if (apiUrl) {
 		const key = sessionKeyFromUrl(apiUrl);
 		return { tenant: key?.tenant ?? null, env: key?.env ?? null, apiUrl, contextBound, sessionId };
 	}
-	// Contextless: the worker's assigned tenant is carried in XCSH_SESSION_TENANT.
-	const raw = process.env.XCSH_SESSION_TENANT;
+	// Contextless: advertise the tenant carried by the bind (or spawn env).
+	const raw = boundIdentity?.tenantKey ?? process.env.XCSH_SESSION_TENANT;
 	if (raw) {
 		const [tenant, env] = raw.split("|");
 		return { tenant: tenant || null, env: env || null, apiUrl: null, contextBound, sessionId };
@@ -127,6 +143,29 @@ export default class Worker extends Command {
 		bridge.setSessionInfo(sessionInfoForWorker);
 		ContextService.onContextChange(() => bridge.broadcastTenantChanged());
 
+		// Pre-warm pool late-bind: the manager (our parent) sends {bind} over Bun IPC to adopt
+		// this spare for a tab. Apply the identity, activate the tenant's context LIVE, then
+		// re-announce via broadcastTenantChanged (now carrying the real sessionId).
+		process.on("message", (raw: unknown) => {
+			const m = raw as { type?: unknown; sessionId?: unknown; tenant?: unknown };
+			if (m?.type !== "bind" || typeof m.sessionId !== "string" || typeof m.tenant !== "string") return;
+			// Capture the narrowed values — TS widens `m.*` back to `unknown` inside the async closure.
+			const sessionId = m.sessionId;
+			const tenant = m.tenant;
+			setWorkerIdentity(sessionId, tenant);
+			void (async () => {
+				try {
+					await activateTenantContext(tenant);
+				} catch (err) {
+					console.error(`[xcsh worker] late tenant-bind failed: ${String(err)}`);
+				}
+				bridge.broadcastTenantChanged();
+				// Ack adoption complete (identity applied + context activated + re-announced).
+				// The manager ignores it today; the bench uses it to time adoption latency.
+				process.send?.({ type: "bound", sessionId });
+			})();
+		});
+
 		// The extension's browser actions (navigate/click/read_ax/…) are not builtin
 		// tools — turn each into a bridge-proxying CustomTool so the agent can drive
 		// the browser (without this the agent only has catalog_workflow_runner and

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.57.2",
-	"commit": "642fb826019640261cf1e3c1ec0206581fd9c1fc",
-	"shortCommit": "642fb82",
+	"version": "19.58.1",
+	"commit": "f72a3fa845f24642e4db4d84aa427bb2e2d64538",
+	"shortCommit": "f72a3fa",
 	"branch": "main",
-	"tag": "v19.57.2",
-	"commitDate": "2026-07-04T22:01:28Z",
-	"buildDate": "2026-07-04T22:29:54.204Z",
+	"tag": "v19.58.1",
+	"commitDate": "2026-07-05T13:33:19Z",
+	"buildDate": "2026-07-05T13:53:37.495Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/642fb826019640261cf1e3c1ec0206581fd9c1fc",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.57.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/f72a3fa845f24642e4db4d84aa427bb2e2d64538",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.58.1"
 };

package/src/main.ts

@@ -57,6 +57,7 @@ import type { SubmittedUserInput } from "./modes/types";
 import { type CreateAgentSessionOptions, createAgentSession, discoverAuthStorage } from "./sdk";
 import type { AgentSession } from "./session/agent-session";
 import { resolveResumableSession, type SessionInfo, SessionManager } from "./session/session-manager";
+import { profileDump, profileMark } from "./startup-profile";
 import { resolvePromptInput } from "./system-prompt";
 import type { LspStartupServerInfo } from "./tools";
 import type { EventBus } from "./utils/event-bus";
@@ -146,8 +147,6 @@ export async function submitInteractiveInput(
 	}
 }
 
-const INITIAL_UPDATE_CHECK_TIMEOUT_MS = 500;
-
 async function runInteractiveMode(
 	session: AgentSession,
 	version: string,
@@ -161,23 +160,26 @@ async function runInteractiveMode(
 	initialMessage?: string,
 	initialImages?: ImageContent[],
 ): Promise<void> {
-	const initialUpdateVersion = await Promise.race([
-		versionCheckPromise.catch(() => undefined),
-		new Promise<string | undefined>(resolve => setTimeout(() => resolve(undefined), INITIAL_UPDATE_CHECK_TIMEOUT_MS)),
-	]);
+	profileMark("interactive: enter runInteractiveMode");
 
 	const mode = new InteractiveMode(session, version, setExtensionUIContext, lspServers, mcpManager, eventBus);
 
 	await mode.init();
+	profileMark("interactive: mode.init() done");
 
-	// Non-blocking, one-shot update notice: only surface it if the background check
-	// already resolved within the startup race (no waiting, no live re-render). If it
-	// resolves later, the update is available on demand via /plugins.
-	if (initialUpdateVersion && settings.get("startup.checkUpdate")) {
-		mode.showStatus(`Update available: v${initialUpdateVersion} — run: xcsh update`, { dim: true });
+	// Update notice: fully non-blocking. Startup never waits on the network version
+	// check; surface the notice whenever it resolves (typically after the prompt is
+	// already up). If it never resolves, the update is available on demand via /plugins.
+	if (settings.get("startup.checkUpdate")) {
+		void versionCheckPromise
+			.then(latest => {
+				if (latest) mode.showStatus(`Update available: v${latest} — run: xcsh update`, { dim: true });
+			})
+			.catch(() => {});
 	}
 
 	mode.renderInitialMessages();
+	profileMark("interactive: initial render requested");
 
 	for (const notify of notifs) {
 		if (!notify) {
@@ -210,6 +212,8 @@ async function runInteractiveMode(
 		}
 	}
 
+	profileMark("interactive: READY — awaiting first input");
+	profileDump();
 	while (true) {
 		const input = await mode.getUserInput();
 		await submitInteractiveInput(mode, session, input);
@@ -551,6 +555,7 @@ async function buildSessionOptions(
 
 export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<void> {
 	logger.startTiming();
+	profileMark("entry: runtime + module-graph loaded (pre-main)");
 
 	// Initialize theme early with defaults (CLI commands need symbols)
 	// Will be re-initialized with user preferences later
@@ -895,6 +900,7 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 		sessionOptions,
 	);
 	logger.time("main:afterCreateSession");
+	profileMark("createAgentSession done");
 	if (parsedArgs.apiKey && !sessionOptions.model && session.model) {
 		authStorage.setRuntimeApiKey(session.model.provider, parsedArgs.apiKey);
 	}

package/src/modes/components/welcome.ts

@@ -8,6 +8,32 @@ import { theme } from "../../modes/theme/theme";
  * commands (/plugins, /context) so startup stays instant and never blocks or
  * live-updates. See docs/superpowers/specs for the fast-startup design.
  */
+// biome-ignore format: preserve ASCII art layout
+/** The F5 "ball" startup logo. Rows are vertically symmetric so the disk renders as a
+ * clean circle; keep it that way (see welcome-logo.test.ts). `▓`→red, `█`→white,
+ * `▒`→red stipple halo, `()|_`→red edge glyphs (see WelcomeComponent.#f5ColorLine). */
+export const F5_LOGO_ROWS: readonly string[] = [
+	"                   ________",
+	"              (▒▒▒▒▓▓▓▓▓▓▓▓▒▒▒▒)",
+	"         (▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒)",
+	"      (▒▒▓▓▓▓██████████▓▓▓▓█████████████)",
+	"    (▒▓▓▓▓██████▒▒▒▒▒███▓▓██████████████▒)",
+	"   (▒▓▓▓▓██████▒▓▓▓▓▓▒▒▒▓██▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒)",
+	"  (▒▓▓▓▓▓██████▓▓▓▓▓▓▓▓▓██▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒)",
+	" (▒▓▓███████████████▓▓▓▓█████████████▓▓▓▓▓▓▒)",
+	"(▒▓▓▓▒▒▒███████▒▒▒▒▒▓▓▓████████████████▓▓▓▓▓▒)",
+	"|▒▓▓▓▓▓▓▒██████▓▓▓▓▓▓▓████████████████████▓▓▒|",
+	"|▒▓▓▓▓▓▓▓██████▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒██████████▓▒|",
+	"(▒▓▓▓▓▓▓▓██████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒████████▒▒)",
+	" (▒▓▓▓▓▓▓██████▓▓▓▓▓▓▓███▓▓▓▓▓▓▓▓▓▓▒▒▒████▒▒)",
+	"  (▒▓▓▓▓▓██████▓▓▓▓▓▓█████▓▓▓▓▓▓▓▓▓▓▓▓███▒▒)",
+	"   (▒▒██████████▓▓▓▓▓▒██████▓▓▓▓▓▓▓▓███▒▒▒)",
+	"    (▒▒▒▒▒██████████▓▓▒▒█████████████▒▒▓▒)",
+	"      (▒▓▓▒▒▒▒▒▒▒▒▒▒▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒)",
+	"         (▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒)",
+	"              (▒▒▒▒▓▓▓▓▓▓▓▓▒▒▒▒)",
+];
+
 export class WelcomeComponent implements Component {
 	constructor(private readonly version: string) {}
 	invalidate(): void {}
@@ -20,28 +46,7 @@ export class WelcomeComponent implements Component {
 		if (boxWidth < 4) return [];
 		const leftCol = boxWidth - 2;
 
-		// biome-ignore format: preserve ASCII art layout
-		const f5Logo = [
-			"                   ________",
-			"              (▒▒▒▒▓▓▓▓▓▓▓▓▒▒▒▒)",
-			"         (▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒)",
-			"      (▒▒▓▓▓▓██████████▓▓▓▓███████████████)",
-			"    (▒▓▓▓▓██████▒▒▒▒▒███▓▓█████████████████▒)",
-			"   (▒▓▓▓▓██████▒▓▓▓▓▓▒▒▒▓██▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒)",
-			"  (▒▓▓▓▓▓██████▓▓▓▓▓▓▓▓▓██▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒)",
-			" (▒▓▓████████████████▓▓▓▓████████████▓▓▓▓▓▓▒)",
-			"(▒▓▓▓▒▒▒███████▒▒▒▒▒▓▓▓████████████████▓▓▓▓▓▒)",
-			"|▒▓▓▓▓▓▓▒██████▓▓▓▓▓▓▓████████████████████▓▓▒|",
-			"|▒▓▓▓▓▓▓▓██████▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒██████████▓▒|",
-			"(▒▓▓▓▓▓▓▓██████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒██████████▒▒)",
-			" (▒▓▓▓▓▓▓██████▓▓▓▓▓▓▓███▓▓▓▓▓▓▓▓▓▒▒▒████▒▒)",
-			"  (▒▓▓▓▓▓██████▓▓▓▓▓▓██████▓▓▓▓▓▓▓▓▓▓▓▓████▒▒)",
-			"   (▒▒██████████▓▓▓▓▓▒██████▓▓▓▓▓▓▓▓██████▒▒▒)",
-			"    (▒▒▒▒▒██████████▓▓▒▒██████████████▒▒▓▒)",
-			"      (▒▓▓▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒)",
-			"         (▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒)",
-			"              (▒▒▒▒▓▓▓▓▓▓▓▓▒▒▒▒)",
-		];
+		const f5Logo = F5_LOGO_ROWS;
 
 		const logoColored = f5Logo.map(line => this.#f5ColorLine(line));
 		const logoBlockPad = Math.max(0, Math.floor((leftCol - logoMaxWidth) / 2));

package/src/modes/controllers/extension-ui-controller.ts

@@ -274,10 +274,12 @@ export class ExtensionUiController {
 			this.showExtensionError(error.extensionPath, error.error);
 		});
 
-		// Emit session_start event
-		await extensionRunner.emit({
-			type: "session_start",
-		});
+		// Emit session_start in the BACKGROUND so a slow hook (e.g. a plugin doing a
+		// network/CLI check) can never block the TUI paint. The runner discards
+		// session_start handler results, so nothing downstream depends on completion;
+		// hooks that update the UI (widgets/status) render progressively as they finish.
+		// Handler errors are still surfaced via the onError subscription above.
+		void extensionRunner.emit({ type: "session_start" });
 	}
 
 	setHookWidget(key: string, content: ExtensionWidgetContent, options?: ExtensionWidgetOptions): void {

package/src/modes/interactive-mode.ts

@@ -35,6 +35,7 @@ import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" wit
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
+import { profileMark } from "../startup-profile";
 import { STTController, type SttState } from "../stt";
 import type { ExitPlanModeDetails } from "../tools";
 import type { EventBus } from "../utils/event-bus";
@@ -294,6 +295,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	async init(): Promise<void> {
 		if (this.isInitialized) return;
 
+		profileMark("init: start");
 		logger.time("InteractiveMode.init:keybindings");
 		this.keybindings = KeybindingsManager.create();
 
@@ -305,6 +307,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.refreshSlashCommandState.bind(this),
 			getProjectDir(),
 		);
+		profileMark("init: refreshSlashCommandState done");
 
 		// Refresh user profile in background — fire and forget
 		reconcileFromCollectors().catch(err => logger.warn("Background profile refresh failed", { error: String(err) }));
@@ -368,10 +371,12 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		// Load initial todos
 		await this.#loadTodoList();
+		profileMark("init: loadTodoList done");
 
 		// Start the UI
 		const clearScreen = settings.get("startup.clearScreen");
 		this.ui.start(clearScreen);
+		profileMark("init: ui.start done");
 		pushTerminalTitle();
 		setSessionTerminalTitle(this.sessionManager.getSessionName(), this.sessionManager.getCwd());
 		this.#syncEditorMaxHeight();
@@ -379,9 +384,11 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		// Initialize hooks with TUI-based UI context
 		await this.initHooksAndCustomTools();
+		profileMark("init: initHooksAndCustomTools done");
 
 		// Restore mode from session (e.g. plan mode on resume)
 		await this.#restoreModeFromSession();
+		profileMark("init: restoreModeFromSession done");
 
 		// Subscribe to agent events
 		this.#subscribeToAgent();

package/src/sdk.ts

@@ -779,47 +779,53 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	// is via the existing activate(); auth is validated but never blocks resume.
 	try {
 		const { ContextService } = await import("./services/xcsh-context");
-		const { resolveAutoBind, chooseSessionContext } = await import("./services/session-context-binding");
+		const { resolveAutoBind, chooseSessionContext, activateTenantContext, shouldRunSessionContextBootstrap } =
+			await import("./services/session-context-binding");
 		const svc = ContextService.instance; // inited in main.ts (throws for SDK/tests → caught)
-		if (!process.env.XCSH_API_URL) {
+		// A pre-warmed spare (XCSH_WORKER_SPARE=1) skips the bootstrap entirely and
+		// stays contextless until its IPC bind activates the correct tenant — see
+		// shouldRunSessionContextBootstrap. Cold workers and interactive CLI are
+		// unchanged (they have no spare marker).
+		if (
+			shouldRunSessionContextBootstrap({
+				XCSH_API_URL: process.env.XCSH_API_URL,
+				XCSH_WORKER_SPARE: process.env.XCSH_WORKER_SPARE,
+			})
+		) {
 			const bound = existingSession.activeContextName; // resumed binding, if any
-			const contexts = await svc.listContexts();
-			const available = contexts.map(c => c.name);
 			const tenantKey = process.env.XCSH_SESSION_TENANT;
-			let autoBind: ReturnType<typeof resolveAutoBind>;
 			if (tenantKey) {
-				// Extension worker: match a context to this worker's tenant.
-				const { sessionKeyFromUrl } = await import("./services/xcsh-env");
-				const contextTenantKeys: Record<string, string> = {};
-				for (const c of contexts) {
-					const key = c.apiUrl ? sessionKeyFromUrl(c.apiUrl) : null;
-					if (key) contextTenantKeys[c.name] = `${key.tenant}|${key.env}`;
-				}
-				autoBind = resolveAutoBind({
-					kind: "extension",
-					availableContexts: available,
-					tenantKey,
-					contextTenantKeys,
-				});
-			} else {
-				const folderContext = await svc.resolveFolderContextName(cwd);
-				autoBind = resolveAutoBind({ kind: "cli", availableContexts: available, folderContext });
-			}
-			const choice = chooseSessionContext(bound, autoBind);
-			if ("activate" in choice) {
+				// Extension worker: match a context to this worker's tenant (shared with pool late-bind).
 				try {
-					await svc.activate(choice.activate); // fires onContextChange → records context_change
-					await svc.validateToken(); // authenticate; non-blocking
+					await activateTenantContext(tenantKey, bound);
 				} catch (err) {
 					// Context deleted since last use, or auth failed → surface, never block.
 					logger.warn("XCSH: session context bootstrap could not fully activate", {
-						context: choice.activate,
+						tenantKey,
 						error: String(err),
 					});
 				}
+			} else {
+				const contexts = await svc.listContexts();
+				const available = contexts.map(c => c.name);
+				const folderContext = await svc.resolveFolderContextName(cwd);
+				const autoBind = resolveAutoBind({ kind: "cli", availableContexts: available, folderContext });
+				const choice = chooseSessionContext(bound, autoBind);
+				if ("activate" in choice) {
+					try {
+						await svc.activate(choice.activate); // fires onContextChange → records context_change
+						await svc.validateToken(); // authenticate; non-blocking
+					} catch (err) {
+						// Context deleted since last use, or auth failed → surface, never block.
+						logger.warn("XCSH: session context bootstrap could not fully activate", {
+							context: choice.activate,
+							error: String(err),
+						});
+					}
+				}
+				// choice.needsSelection / choice.none → leave unbound; the /context status
+				// line and tools already prompt "run /context activate".
 			}
-			// choice.needsSelection / choice.none → leave unbound; the /context status
-			// line and tools already prompt "run /context activate".
 		}
 	} catch {
 		// ContextService not initialized (SDK consumers / tests) — skip bootstrap.

package/src/services/session-context-binding.ts

@@ -7,6 +7,22 @@
 
 export type SessionKind = "cli" | "extension";
 
+/**
+ * Whether createAgentSession should run its create-time context bootstrap.
+ *
+ * A pre-warmed spare worker (XCSH_WORKER_SPARE=1) is spawned with NO api url and
+ * NO tenant, so the bootstrap would otherwise fall into the CLI single-context
+ * auto-bind branch and boot-activate a tenant's context/credentials BEFORE any
+ * IPC bind — breaking the "identity-less spare holds no tenant credentials until
+ * bind" isolation guarantee. A spare must stay contextless until its IPC bind
+ * calls activateTenantContext(). This keeps all other paths unchanged:
+ * interactive CLI (no marker) folder-auto-binds, and a cold-spawned worker
+ * (has XCSH_SESSION_TENANT, no marker) tenant-binds.
+ */
+export function shouldRunSessionContextBootstrap(env: { XCSH_API_URL?: string; XCSH_WORKER_SPARE?: string }): boolean {
+	return !env.XCSH_API_URL && !env.XCSH_WORKER_SPARE;
+}
+
 export interface AutoBindInput {
 	kind: SessionKind;
 	/** Names of all available (global) contexts. */
@@ -47,3 +63,34 @@ export function chooseSessionContext(
 	if (autoBind.kind === "needsSelection") return { needsSelection: true };
 	return { none: true };
 }
+
+/**
+ * Activate the stored context matching a worker's tenant key ("tenant|env"), if any.
+ * Extracted from the createAgentSession bootstrap so a pre-warmed spare worker can bind
+ * its tenant AFTER startup (pool late-bind). Returns true if a context was activated.
+ * Never throws when no context matches — the caller stays tenant-advertised/unbound.
+ */
+export async function activateTenantContext(tenantKey: string, bound: string | null = null): Promise<boolean> {
+	const { ContextService } = await import("./xcsh-context");
+	const { sessionKeyFromUrl } = await import("./xcsh-env");
+	const svc = ContextService.instance;
+	const contexts = await svc.listContexts();
+	const contextTenantKeys: Record<string, string> = {};
+	for (const c of contexts) {
+		const key = c.apiUrl ? sessionKeyFromUrl(c.apiUrl) : null;
+		if (key) contextTenantKeys[c.name] = `${key.tenant}|${key.env}`;
+	}
+	const autoBind = resolveAutoBind({
+		kind: "extension",
+		availableContexts: contexts.map(c => c.name),
+		tenantKey,
+		contextTenantKeys,
+	});
+	const choice = chooseSessionContext(bound ?? undefined, autoBind);
+	if ("activate" in choice) {
+		await svc.activate(choice.activate);
+		await svc.validateToken();
+		return true;
+	}
+	return false;
+}

package/src/startup-profile.ts

@@ -0,0 +1,48 @@
+/**
+ * Opt-in startup profiler — `PI_STARTUP_PROFILE=1`.
+ *
+ * PI_TIMING exits before the TUI paints, so it cannot measure `runInteractiveMode`
+ * or the pre-`main` module-graph load. This records labeled timestamps (ms since
+ * process start, via `performance.now()`, which is measured from runtime start) and
+ * dumps the full boot timeline to a FILE at the input-ready point — so nothing
+ * corrupts the live TUI screen. Zero cost when the env var is unset.
+ *
+ * The FIRST mark's timestamp is the time from process start to that mark, i.e. it
+ * captures the runtime init + evaluation of the embedded module graph that happens
+ * before any of our code runs. Later marks show the per-step deltas through paint.
+ *
+ * Usage:  PI_STARTUP_PROFILE=1 xcsh   (then quit; read /tmp/xcsh-startup-profile.txt,
+ *         or set PI_STARTUP_PROFILE_FILE to choose the path).
+ */
+import { writeFileSync } from "node:fs";
+
+const ENABLED = !!process.env.PI_STARTUP_PROFILE;
+const marks: Array<[label: string, atMs: number]> = [];
+
+/** Record a labeled timestamp (no-op unless PI_STARTUP_PROFILE is set). */
+export function profileMark(label: string): void {
+	if (ENABLED) marks.push([label, performance.now()]);
+}
+
+/** Write the collected timeline to a file (no-op unless enabled / no marks). */
+export function profileDump(): void {
+	if (!ENABLED || marks.length === 0) return;
+	const lines = ["=== xcsh startup profile (ms since process start) ===", ""];
+	let prev = 0;
+	for (const [label, at] of marks) {
+		const delta = at - prev;
+		lines.push(`  ${at.toFixed(1).padStart(9)} ms   (+${delta.toFixed(1).padStart(8)} ms)   ${label}`);
+		prev = at;
+	}
+	lines.push(
+		"",
+		`  first mark = runtime + module-graph load; total to ready = ${marks[marks.length - 1][1].toFixed(1)} ms`,
+	);
+	const file = process.env.PI_STARTUP_PROFILE_FILE || "/tmp/xcsh-startup-profile.txt";
+	try {
+		writeFileSync(file, `${lines.join("\n")}\n`);
+		process.stderr.write(`[xcsh] startup profile written to ${file}\n`);
+	} catch {
+		/* best-effort diagnostic */
+	}
+}