@f5-sales-demo/xcsh 19.57.2 → 19.58.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.57.2",
+	"version": "19.58.0",
 	"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.0",
+		"@f5-sales-demo/pi-agent-core": "19.58.0",
+		"@f5-sales-demo/pi-ai": "19.58.0",
+		"@f5-sales-demo/pi-natives": "19.58.0",
+		"@f5-sales-demo/pi-resource-management": "19.58.0",
+		"@f5-sales-demo/pi-tui": "19.58.0",
+		"@f5-sales-demo/pi-utils": "19.58.0",
 		"@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.0",
+	"commit": "def3667fcf2f20c14de7b9ab37b29e85b390e5c4",
+	"shortCommit": "def3667",
 	"branch": "main",
-	"tag": "v19.57.2",
-	"commitDate": "2026-07-04T22:01:28Z",
-	"buildDate": "2026-07-04T22:29:54.204Z",
+	"tag": "v19.58.0",
+	"commitDate": "2026-07-05T03:37:49Z",
+	"buildDate": "2026-07-05T04:00:08.049Z",
 	"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/def3667fcf2f20c14de7b9ab37b29e85b390e5c4",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.58.0"
 };

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/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;
+}