@f5-sales-demo/xcsh 19.60.0 → 19.61.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.60.0",
+	"version": "19.61.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",
@@ -35,6 +35,7 @@
 		"check": "biome check . && bun run format-prompts -- --check && bun run check:types",
 		"check:types": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
+		"check:bundle": "bun scripts/check-bundle.ts",
 		"test": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-console-catalog && bun run generate-console-field-metadata && bun test --max-concurrency 4",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-api-spec-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
@@ -55,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.60.0",
-		"@f5-sales-demo/pi-agent-core": "19.60.0",
-		"@f5-sales-demo/pi-ai": "19.60.0",
-		"@f5-sales-demo/pi-natives": "19.60.0",
-		"@f5-sales-demo/pi-resource-management": "19.60.0",
-		"@f5-sales-demo/pi-tui": "19.60.0",
-		"@f5-sales-demo/pi-utils": "19.60.0",
+		"@f5-sales-demo/xcsh-stats": "19.61.1",
+		"@f5-sales-demo/pi-agent-core": "19.61.1",
+		"@f5-sales-demo/pi-ai": "19.61.1",
+		"@f5-sales-demo/pi-natives": "19.61.1",
+		"@f5-sales-demo/pi-resource-management": "19.61.1",
+		"@f5-sales-demo/pi-tui": "19.61.1",
+		"@f5-sales-demo/pi-utils": "19.61.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/api-specs-version.ts

@@ -0,0 +1,20 @@
+/**
+ * Version helpers for selecting the api-specs-enriched source.
+ *
+ * Kept in a dedicated module (no side effects) so the freshness logic is unit-testable
+ * without importing generate-api-spec-index.ts, which runs the generator on load.
+ */
+
+/** Normalize a release tag (`v2.1.167`) or bare version (`2.1.167`) to a bare version. */
+export function normalizeSpecsTag(tag: string): string {
+	return tag.trim().replace(/^v/, "");
+}
+
+/**
+ * Whether a local api-specs-enriched checkout matches the latest release tag.
+ * A stale checkout must NOT be used, or local/dev builds silently pin to old specs.
+ */
+export function isLocalSpecsCurrent(localVersion: string | undefined, latestTag: string): boolean {
+	if (!localVersion) return false;
+	return normalizeSpecsTag(localVersion) === normalizeSpecsTag(latestTag);
+}

package/scripts/check-bundle.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+/**
+ * Bundle guard: ensure the CLI entrypoint still bundles.
+ *
+ * Reproduces the `bun build --compile` module-graph analysis in ~1s so a
+ * `require()` into a top-level-await subgraph (or other bundle-breaking graph
+ * change) fails fast in a required CI gate — not only in the slower, optional
+ * install-methods build. See PRs #1888 → #1892 for the regression this guards.
+ *
+ * Runs as a standalone `bun` process (not under `bun test`, whose bundler
+ * resolver cannot resolve some lazily-imported specifiers). Exits non-zero on
+ * any bundle error.
+ */
+import * as path from "node:path";
+
+const cliEntry = path.resolve(import.meta.dir, "../src/cli.ts");
+
+const result = await Bun.build({
+	entrypoints: [cliEntry],
+	target: "bun",
+	define: { PI_COMPILED: "true" },
+	external: ["mupdf"],
+	throw: false,
+});
+
+if (!result.success) {
+	console.error("Bundle check FAILED — the CLI entrypoint does not bundle:\n");
+	for (const log of result.logs) console.error(String(log));
+	process.exit(1);
+}
+
+console.log("Bundle check passed — CLI entrypoint bundles cleanly.");

package/scripts/generate-api-spec-index.ts

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { $ } from "bun";
+import { isLocalSpecsCurrent } from "./api-specs-version";
 
 interface SpecPathOperation {
 	operationId?: string;
@@ -183,15 +184,42 @@ async function downloadFromRelease(): Promise<string> {
 	return extractDir;
 }
 
+function readLocalSpecsVersion(specsDir: string): string | undefined {
+	try {
+		const index = JSON.parse(fs.readFileSync(path.join(specsDir, "index.json"), "utf-8")) as { version?: string };
+		return index.version;
+	} catch {
+		return undefined;
+	}
+}
+
 async function findSpecsDir(): Promise<string> {
 	const envDir = process.env.API_SPECS_DIR;
 	if (envDir && fs.existsSync(envDir)) {
+		// Explicit override — the caller is responsible for its freshness.
 		return envDir;
 	}
 
 	const localCheckout = path.resolve(import.meta.dir, "../../../../api-specs-enriched/docs/specifications/api");
 	if (fs.existsSync(localCheckout)) {
-		return localCheckout;
+		// Only build from the local checkout when it matches the latest release, so a
+		// stale checkout cannot silently pin the build to old specs. If GitHub is
+		// unreachable (offline dev), fall back to the local checkout with a warning.
+		try {
+			const latestTag = await resolveLatestTag();
+			const localVersion = readLocalSpecsVersion(localCheckout);
+			if (isLocalSpecsCurrent(localVersion, latestTag)) {
+				return localCheckout;
+			}
+			console.warn(
+				`Local api-specs-enriched checkout is stale (local ${localVersion ?? "unknown"} != latest ${latestTag}); building against the latest release instead.`,
+			);
+		} catch (err) {
+			console.warn(
+				`Could not verify the latest api-specs version (${err instanceof Error ? err.message : err}); using the local checkout.`,
+			);
+			return localCheckout;
+		}
 	}
 
 	return downloadFromRelease();

package/src/browser/chat-handler.ts

@@ -14,12 +14,16 @@ import {
 import { CONSOLE_ROUTES } from "./console-routes.generated";
 import type { BridgeServer } from "./extension-bridge";
 import { interpretPageState } from "./page-state-interpreter";
+import { chatSpans } from "./ttft-spans";
 
 interface ActiveChat {
 	id: string;
 	seq: number;
 	terminalSent: boolean;
 	unsubscribe: () => void;
+	entryAt: number;
+	promptAt: number | null;
+	spanEmitted: boolean;
 }
 
 export class ChatHandler {
@@ -61,7 +65,15 @@ export class ChatHandler {
 			this.#activeHistoryHint = req.history_hint;
 		}
 
-		const chat: ActiveChat = { id, seq: 0, terminalSent: false, unsubscribe: () => {} };
+		const chat: ActiveChat = {
+			id,
+			seq: 0,
+			terminalSent: false,
+			unsubscribe: () => {},
+			entryAt: Date.now(),
+			promptAt: null,
+			spanEmitted: false,
+		};
 		this.#activeChats.set(id, chat);
 
 		const unsubscribe = this.#session.subscribe((event: AgentSessionEvent) => {
@@ -72,6 +84,7 @@ export class ChatHandler {
 		const prompt = composeChatPrompt(req.text, req.context, req.mode);
 
 		try {
+			chat.promptAt = Date.now();
 			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false });
 		} catch (err: unknown) {
 			const message = err instanceof Error ? err.message : "unknown error";
@@ -121,6 +134,15 @@ export class ChatHandler {
 					seq: chat.seq++,
 					delta: ame.delta,
 				} satisfies ChatDelta);
+				// TTFT Phase 2: first token out — emit the chat-segment spans once, keyed by
+				// the c- turn id. chat.promptAt is set (prompt() was awaited before any event);
+				// guard against re-emit on later deltas.
+				if (!chat.spanEmitted && chat.promptAt !== null) {
+					chat.spanEmitted = true;
+					for (const s of chatSpans(chat.id, chat.entryAt, chat.promptAt, Date.now())) {
+						this.#server.send(s);
+					}
+				}
 			} else if (ame.type === "error") {
 				const errorMsg = ame.error?.errorMessage ?? "LLM error";
 				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: errorMsg });

package/src/browser/ttft-spans.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure TTFT span-frame builders for Phase 2. The worker emits these over the bridge
+ * WS; the extension records them (proc:'xcsh') and summarizeTtft stitches them into
+ * the init->first-token timeline. Chrome-free, so they unit-test in isolation.
+ */
+export interface SpanFrame {
+	type: "span";
+	stage: string;
+	ms: number;
+	id?: string;
+	sid?: string;
+	cold?: boolean;
+}
+
+const clamp = (ms: number): number => (ms > 0 ? ms : 0);
+
+/**
+ * Decompose one chat turn's route->first-token into two disjoint spans that sum to
+ * (firstDeltaAt - entryAt): provider_ttft (prompt issued -> first token) and
+ * chat_handler (the xcsh routing/compose/emit overhead = entry -> prompt issued).
+ */
+export function chatSpans(id: string, entryAt: number, promptAt: number, firstDeltaAt: number): SpanFrame[] {
+	const providerMs = clamp(firstDeltaAt - promptAt);
+	const handlerMs = clamp(firstDeltaAt - entryAt - providerMs);
+	return [
+		{ type: "span", stage: "provider_ttft", ms: providerMs, id },
+		{ type: "span", stage: "chat_handler", ms: handlerMs, id },
+	];
+}
+
+/** Build the per-session cold-start spans, tagged with the session id + authoritative cold. */
+export function coldStartSpans(
+	sid: string,
+	cold: boolean,
+	managerProvisionMs: number,
+	workerBootMs: number,
+): SpanFrame[] {
+	return [
+		{ type: "span", stage: "manager_provision", ms: clamp(managerProvisionMs), sid, cold },
+		{ type: "span", stage: "worker_boot", ms: clamp(workerBootMs), sid, cold },
+	];
+}

package/src/cli/chrome-cli.ts

@@ -7,14 +7,30 @@
  */
 
 import * as fs from "node:fs";
+import { homedir } from "node:os";
 import * as path from "node:path";
 import { acquirePage, type BrowserProviderStatus, CdpBrowserProvider } from "../browser";
 import { PORT_RANGE_END, PORT_RANGE_START, resolveForcedPort } from "../browser/extension-bridge";
 import { installNativeHost } from "../services/native-host-install";
 
+/** Ask a running manager to step down (control-socket `shutdown` frame). Resolves
+ * true if a manager answered the socket, false if none was running. Best-effort. */
+async function requestManagerShutdown(reason: "updated"): Promise<boolean> {
+	const sock = process.env.XCSH_MANAGER_SOCK ?? path.join(homedir(), ".xcsh", "manager.sock");
+	try {
+		const c = await Bun.connect({ unix: sock, socket: { data() {} } });
+		c.write(`${JSON.stringify({ type: "shutdown", reason })}\n`);
+		await Bun.sleep(50);
+		c.end();
+		return true;
+	} catch {
+		return false; // no manager listening
+	}
+}
+
 type Settings = { get(key: string): unknown };
 
-export type ChromeAction = "status" | "relaunch" | "setup" | "install-host";
+export type ChromeAction = "status" | "relaunch" | "setup" | "install-host" | "recycle";
 
 export const EXTENSION_ID = "klajkjdoehjidngligegnpknogmjjhkc";
 
@@ -116,6 +132,18 @@ export async function runChromeCommand(action: ChromeAction, settings: Settings)
 		const manifestPath = installNativeHost({ launchCommand, extensionIds: [EXTENSION_ID] });
 		return `Native-messaging host manifest written to:\n  ${manifestPath}`;
 	}
+	if (action === "recycle") {
+		// Proactive post-upgrade recycle (#1874 Task 7): refresh the wrapper to the
+		// version-stable launcher, then ask any running (old) manager to step down so
+		// the new version takes effect NOW instead of on the next Chrome launch. The
+		// successor re-adopts live workers (zero-downtime). Both best-effort.
+		const launchCommand = nativeHostLaunchCommand();
+		installNativeHost({ launchCommand, extensionIds: [EXTENSION_ID] });
+		const stepped = await requestManagerShutdown("updated");
+		return stepped
+			? "Refreshed native-host wrapper; asked the running manager to recycle to this version."
+			: "Refreshed native-host wrapper; no manager was running (it will start fresh on next use).";
+	}
 	// relaunch: self-consented rung 3 — force allowRelaunch regardless of the setting.
 	const { mode } = await acquirePage({ settings, allowRelaunch: true });
 	return `Chrome ready (${mode}). Your real, logged-in session is now debuggable for xcsh.`;

package/src/cli/update-cli.ts

@@ -315,6 +315,10 @@ function updateViaBrew(targetPath: string, expectedVersion: string): void {
 	console.log(chalk.yellow(`To update to ${expectedVersion}, run:`));
 	console.log(chalk.cyan(`  brew upgrade ${APP_NAME}`));
 	console.log(chalk.dim("\nThis ensures the update goes through your organization's Homebrew tap."));
+	// #1874 Task 7: brew upgrade runs out-of-band, so we can't recycle automatically.
+	// Nudge the one command that applies it to the Chrome extension immediately.
+	console.log(chalk.dim(`Then run  ${APP_NAME} chrome recycle  to apply it to the extension now`));
+	console.log(chalk.dim("(otherwise it takes effect the next time you open Chrome)."));
 }
 
 /**
@@ -413,6 +417,18 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 				await updateViaBinaryAt(target.path, release.version);
 				break;
 		}
+
+		// #1874 Task 7: the binary just changed under a possibly-running OLD manager.
+		// Proactively recycle so the new version takes effect now instead of on the
+		// next Chrome launch — refresh the native-host wrapper + step the old manager
+		// down (its successor re-adopts live workers, zero-downtime). The just-updated
+		// `xcsh` on PATH is the new version. Best-effort, non-blocking; passive
+		// supersede covers it if this is skipped.
+		try {
+			Bun.spawn(["xcsh", "chrome", "recycle"], { stdout: "ignore", stderr: "ignore" });
+		} catch {
+			/* recycle is a convenience — never fail an update on it */
+		}
 	} catch (err) {
 		console.error(chalk.red(`Update failed: ${err}`));
 		process.exit(1);

package/src/commands/chrome.ts

@@ -5,7 +5,7 @@ import { Args, Command } from "@f5-sales-demo/pi-utils/cli";
 import { type ChromeAction, runChromeCommand } from "../cli/chrome-cli";
 import { Settings, settings } from "../config/settings";
 
-const ACTIONS: ChromeAction[] = ["status", "relaunch", "setup", "install-host"];
+const ACTIONS: ChromeAction[] = ["status", "relaunch", "setup", "install-host", "recycle"];
 
 export default class Chrome extends Command {
 	static description = "Inspect or arrange the Chrome session xcsh drives for console automation";

package/src/commands/manager.ts

@@ -54,6 +54,66 @@ function isPortFree(port: number): boolean {
 	}
 }
 
+/** The PID listening on a loopback bridge port, or 0 if unknown (best-effort via
+ * lsof). Used only to give a re-adopted worker a reapable pid; 0 means "manage by
+ * socket liveness, never signal" (see killPid's pid<=0 guard). */
+function pidListeningOn(port: number): number {
+	try {
+		const out = Bun.spawnSync(["lsof", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"])
+			.stdout.toString()
+			.trim()
+			.split("\n")[0];
+		const pid = Number(out);
+		return Number.isInteger(pid) && pid > 0 ? pid : 0;
+	} catch {
+		return 0; // lsof unavailable — leave unknown
+	}
+}
+
+/** Complete the extension `hello` handshake against a bridge port (with the
+ * origin header the bridge requires), resolving the `hello_ack` frame or null.
+ * EXTENSION_ID is lazy-required so it stays off the manager's cold-start path. */
+function bridgeHello(port: number, timeoutMs = 400): Promise<Record<string, unknown> | null> {
+	return new Promise(resolve => {
+		let done = false;
+		const finish = (v: Record<string, unknown> | null) => {
+			if (done) return;
+			done = true;
+			resolve(v);
+		};
+		let ws: WebSocket;
+		try {
+			const { EXTENSION_ID } = require("../cli/chrome-cli");
+			ws = new WebSocket(`ws://127.0.0.1:${port}`, {
+				headers: { Origin: `chrome-extension://${EXTENSION_ID}` },
+			} as unknown as string[]);
+		} catch {
+			return finish(null);
+		}
+		const close = () => {
+			try {
+				ws.close();
+			} catch {
+				/* already closing */
+			}
+		};
+		ws.onopen = () => ws.send(JSON.stringify({ type: "hello" }));
+		ws.onmessage = e => {
+			try {
+				finish(JSON.parse(String(e.data)) as Record<string, unknown>);
+			} catch {
+				finish(null);
+			}
+			close();
+		};
+		ws.onerror = () => finish(null);
+		setTimeout(() => {
+			close();
+			finish(null);
+		}, timeoutMs);
+	});
+}
+
 /**
  * The argv (AFTER `process.execPath`) to re-run THIS binary in `mode`.
  *
@@ -195,12 +255,46 @@ export default class Manager extends Command {
 			for (let i = 0; i < n; i++) spawnSpare();
 		};
 
+		/** Zero-downtime handoff (#1874 Task 6): on startup, discover bridge workers a
+		 * PRIOR (superseded) manager left running and re-register them, so a tab's
+		 * session survives the manager swap. Probes the whole range in parallel; a
+		 * bridge answering with a real per-tab sessionId (not the "spare" sentinel) and
+		 * a tenant+env is re-adopted. Spares/unknowns are ignored (the pool refills
+		 * them). Best-effort — never throws. */
+		const readoptWorkers = async (): Promise<void> => {
+			const found = await Promise.all(range.map(async port => ({ port, ack: await bridgeHello(port) })));
+			for (const { port, ack } of found) {
+				if (!ack) continue;
+				const sid = ack.sessionId;
+				const tenant = ack.tenant;
+				const env = ack.env;
+				if (typeof sid !== "string" || sid === "spare" || typeof tenant !== "string" || typeof env !== "string") {
+					continue; // spare sentinel or tenant-less bridge — not a re-adoptable session
+				}
+				if (reg.has(sid)) continue;
+				reg.set(sid, {
+					sessionId: sid,
+					tenant: `${tenant}|${env}`,
+					port,
+					pid: pidListeningOn(port),
+					lastSeen: Date.now(),
+				});
+				console.error(`[xcsh manager] re-adopted worker ${sid} (${tenant}|${env}) on port ${port}`);
+			}
+		};
+
 		/** Adopt a warm spare for a provision (bind over IPC). Returns false if none available. */
-		const adoptSpare = (msg: { sessionId: string; tenant: string }): boolean => {
+		const adoptSpare = (msg: { sessionId: string; tenant: string }, managerProvisionMs: number): 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 });
+			(rec.proc as { send(m: unknown): void }).send({
+				type: "bind",
+				sessionId: msg.sessionId,
+				tenant: msg.tenant,
+				provisionMs: managerProvisionMs, // TTFT Phase 2: relayed manager_provision (warm)
+				cold: false, // authoritative: warm adopt
+			});
 			reg.set(msg.sessionId, {
 				sessionId: msg.sessionId,
 				tenant: msg.tenant,
@@ -219,18 +313,8 @@ export default class Manager extends Command {
 			return true;
 		};
 
-		const reap = (sessionId: string): void => {
-			const w = reg.get(sessionId);
-			if (!w) return;
-			try {
-				process.kill(w.pid);
-			} catch {
-				/* already gone */
-			}
-			reg.delete(sessionId);
-		};
-
 		const killPid = (pid: number): void => {
+			if (pid <= 0) return; // 0/negative = unknown (re-adopted worker) — NEVER signal (kill(0) hits the group)
 			try {
 				process.kill(pid); // SIGTERM — spares exit at once; bound workers self-drain (worker.ts)
 			} catch {
@@ -238,21 +322,35 @@ export default class Manager extends Command {
 			}
 		};
 
+		const reap = (sessionId: string): void => {
+			const w = reg.get(sessionId);
+			if (!w) return;
+			killPid(w.pid);
+			reg.delete(sessionId);
+		};
+
 		/** Graceful teardown (#1874): stop accepting, terminate the (session-less)
-		 * spare pool at once, SIGTERM bound workers so they drain their in-flight turn,
-		 * drop the socket + liveness record, and exit. Idempotent. Bounded by each
-		 * worker's own drain ceiling — the manager frees the socket immediately so a
-		 * successor can bind without waiting on drains. */
+		 * spare pool at once, drop the socket + liveness record, and exit. Idempotent.
+		 *
+		 * Bound workers depend on the reason: on a HANDOFF (superseded/updated — a
+		 * successor manager is about to bind and re-adopt them), we LEAVE them running
+		 * so tab sessions survive the swap (zero-downtime, Task 6). Otherwise (manual
+		 * operator SIGTERM — no successor) we SIGTERM them so they drain + exit rather
+		 * than leak. The manager frees the socket immediately either way. */
 		const gracefulShutdown = (reason: string): void => {
 			if (shuttingDown) return;
 			shuttingDown = true;
 			accepting = false;
+			const handoff = reason === "superseded" || reason === "updated";
 			console.error(
-				`[xcsh manager] graceful shutdown (${reason}); reaping ${pool.length} spare(s) + ${reg.size} worker(s)`,
+				`[xcsh manager] graceful shutdown (${reason}); reaping ${pool.length} spare(s)` +
+					(handoff ? `, leaving ${reg.size} worker(s) for re-adoption` : ` + ${reg.size} worker(s)`),
 			);
 			for (const s of pool.splice(0)) killPid(s.pid);
-			for (const w of reg.values()) killPid(w.pid);
-			reg.clear();
+			if (!handoff) {
+				for (const w of reg.values()) killPid(w.pid);
+				reg.clear();
+			}
 			removeManagerState(sockPath);
 			try {
 				fs.rmSync(sockPath, { force: true });
@@ -262,7 +360,7 @@ export default class Manager extends Command {
 			process.exit(0);
 		};
 
-		const spawnWorker = (msg: { sessionId: string; tenant: string }): void => {
+		const spawnWorker = (msg: { sessionId: string; tenant: string }, managerProvisionMs: number): void => {
 			// Registry-dedupe (pickPort) over only the ports free at the OS level.
 			const port = pickPort(reg, range.filter(isPortFree));
 			if (port === null) {
@@ -282,6 +380,12 @@ export default class Manager extends Command {
 					// spawned tenant key is authoritative (undefined removes the var in Bun).
 					XCSH_API_URL: undefined,
 					XCSH_API_TOKEN: undefined,
+					// TTFT Phase 2: relay cold-start timing to the worker (only it has a WS to
+					// the extension). Wall-clock spawn instant + manager_provision ms; COLD=1
+					// marks the authoritative cold spawn.
+					XCSH_TTFT_SPAWN_AT: String(Date.now()),
+					XCSH_TTFT_PROVISION_MS: String(managerProvisionMs),
+					XCSH_TTFT_COLD: "1",
 				},
 				stdout: "ignore",
 				stderr: "ignore",
@@ -325,8 +429,10 @@ export default class Manager extends Command {
 					}
 					return;
 				}
+				const provisionReceivedAt = Date.now(); // TTFT Phase 2: start of manager_provision
 				if (needsProvision(reg, msg.sessionId)) {
-					if (!adoptSpare(msg)) spawnWorker(msg); // adopt a warm spare, else cold-spawn (fallback)
+					const managerProvisionMs = Date.now() - provisionReceivedAt;
+					if (!adoptSpare(msg, managerProvisionMs)) spawnWorker(msg, managerProvisionMs); // 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)
@@ -409,6 +515,11 @@ export default class Manager extends Command {
 		process.on("SIGTERM", () => gracefulShutdown("manual"));
 		process.on("SIGINT", () => gracefulShutdown("manual"));
 
+		// Zero-downtime handoff: re-adopt any bound workers a superseded manager left
+		// running BEFORE filling the pool (so their ports aren't mistaken for free).
+		// Awaited but bounded (~parallel 400ms); the socket already accepts connections.
+		await readoptWorkers();
+
 		// Pre-warm the spare pool so provisions can adopt instead of cold-spawn.
 		if (poolTarget > 0) maintainPool();
 

package/src/commands/worker.ts

@@ -19,6 +19,7 @@ import { ChatHandler } from "../browser/chat-handler";
 import { startBridgeServer } from "../browser/extension-bridge";
 import { createExtensionBridgeTools, EXTENSION_AGENT_TOOL_NAMES } from "../browser/extension-bridge-tools";
 import { setSharedBridgeServer } from "../browser/provider";
+import { coldStartSpans, type SpanFrame } from "../browser/ttft-spans";
 import { initializeWithSettings } from "../discovery";
 import { createAgentSession } from "../sdk";
 import { activateTenantContext } from "../services/session-context-binding";
@@ -109,6 +110,12 @@ export default class Worker extends Command {
 		// Spans only accumulate while recording; nothing prints unless PI_TIMING is set,
 		// and each logger.time() returns its wrapped value unchanged — so a normal
 		// `xcsh worker` run is behaviorally identical to before.
+		// TTFT Phase 2: the manager stamps XCSH_TTFT_SPAWN_AT at Bun.spawn for a cold
+		// spawn; worker_boot(cold) = bridge-listening instant - spawn instant (captures
+		// fork + runtime init, which logger.startTiming below misses).
+		const spawnAtEnv = Number(process.env.XCSH_TTFT_SPAWN_AT);
+		const coldSpawn = process.env.XCSH_TTFT_COLD === "1";
+		const managerProvisionMsEnv = Number(process.env.XCSH_TTFT_PROVISION_MS);
 		logger.startTiming();
 
 		process.env.XCSH_BROWSER_PROVIDER = "extension";
@@ -142,15 +149,50 @@ export default class Worker extends Command {
 		bridge.setSessionInfo(sessionInfoForWorker);
 		ContextService.onContextChange(() => bridge.broadcastTenantChanged());
 
+		// TTFT Phase 2: buffer the per-session cold-start spans and flush them once a
+		// client is actually connected. bridge.send() silently no-ops with no client, so
+		// the flush is gated on `clientConnected` — a cold-boot flush before the extension
+		// connects would otherwise burn the once-latch and lose the spans. Cold path is
+		// populated now (env); warm path by the {bind} handler below.
+		let coldStartBuffer: SpanFrame[] = [];
+		let coldStartSent = false;
+		let clientConnected = false;
+		const flushColdStart = (): void => {
+			if (coldStartSent || !clientConnected || coldStartBuffer.length === 0) return;
+			for (const s of coldStartBuffer) bridge.send(s);
+			coldStartSent = true;
+		};
+		// onConnected (raw WS open) is the deliberate flush trigger: no hello hook is exposed
+		// today, and the bridge's origin check already gates opens to the extension.
+		bridge.onConnected(() => {
+			clientConnected = true;
+			flushColdStart();
+		});
+
+		if (coldSpawn && process.env.XCSH_SESSION_ID && Number.isFinite(spawnAtEnv)) {
+			const workerBootMs = Date.now() - spawnAtEnv; // spawn -> bridge listening
+			const mgrMs = Number.isFinite(managerProvisionMsEnv) ? managerProvisionMsEnv : 0;
+			coldStartBuffer = coldStartSpans(process.env.XCSH_SESSION_ID, true, mgrMs, workerBootMs);
+			// No flush here: at cold boot the extension has not connected yet; onConnected flushes.
+		}
+
 		// 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 };
+			const m = raw as {
+				type?: unknown;
+				sessionId?: unknown;
+				tenant?: unknown;
+				provisionMs?: unknown;
+				cold?: 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;
+			const bindAt = Date.now(); // TTFT Phase 2: start of warm worker_boot (bind -> bound)
+			const relayedProvisionMs = typeof m.provisionMs === "number" ? m.provisionMs : 0;
 			setWorkerIdentity(sessionId, tenant);
 			void (async () => {
 				try {
@@ -162,6 +204,9 @@ export default class Worker extends Command {
 				// 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 });
+				// TTFT Phase 2: warm adopt cold-start spans (worker_boot = bind -> bound).
+				coldStartBuffer = coldStartSpans(sessionId, false, relayedProvisionMs, Date.now() - bindAt);
+				flushColdStart();
 			})();
 		});
 

package/src/edit/modes/chunk.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as nodePath from "node:path";
 import type { AgentToolResult } from "@f5-sales-demo/pi-agent-core";
+import { StringEnum } from "@f5-sales-demo/pi-ai";
 import {
 	ChunkAnchorStyle,
 	ChunkEditOp,
@@ -12,7 +13,6 @@ import {
 	type EditOperation as NativeEditOperation,
 } from "@f5-sales-demo/pi-natives";
 import { $envpos } from "@f5-sales-demo/pi-utils";
-import { StringEnum } from "@f5-sales-demo/xcsh";
 import { type Static, Type } from "@sinclair/typebox";
 import type { BunFile } from "bun";
 import { LRUCache } from "lru-cache";