@f5-sales-demo/xcsh 19.61.3 → 19.61.5

package/package.json

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

package/src/browser/chat-handler.ts

@@ -31,12 +31,19 @@ export class ChatHandler {
 	#session: AgentSession;
 	#activeChats = new Map<string, ActiveChat>();
 	#activeHistoryHint: string | undefined;
+	#onTurnStart: (() => void) | undefined;
 
 	constructor(server: BridgeServer, session: AgentSession) {
 		this.#server = server;
 		this.#session = session;
 	}
 
+	/** Register a callback fired when a chat turn is accepted (used by the worker's
+	 * manager keepalive to refresh lastSeen at turn start). */
+	onTurnStart(cb: () => void): void {
+		this.#onTurnStart = cb;
+	}
+
 	attach(): void {
 		this.#server.onMessage(msg => {
 			if (isChatRequest(msg)) this.#handleChatRequest(msg as unknown as ChatRequest);
@@ -75,6 +82,7 @@ export class ChatHandler {
 			spanEmitted: false,
 		};
 		this.#activeChats.set(id, chat);
+		this.#onTurnStart?.();
 
 		const unsubscribe = this.#session.subscribe((event: AgentSessionEvent) => {
 			this.#handleSessionEvent(chat, event);

package/src/browser/ttft-spans.ts

@@ -28,6 +28,17 @@ export function chatSpans(id: string, entryAt: number, promptAt: number, firstDe
 	];
 }
 
+/**
+ * Build the session-build span: the heavy `createAgentSession` step (model
+ * registry load, discovery, extension/plugin loading, context bootstrap) that
+ * runs between `worker_boot` (ends at bridge-listen) and `chat_handler`. Without
+ * this stage the cost is silently absorbed into total ttft_ms, hiding plugin/
+ * discovery regressions from the bench and the diagnostics panel.
+ */
+export function sessionBuildSpan(sid: string, cold: boolean, ms: number): SpanFrame {
+	return { type: "span", stage: "session_build", ms: clamp(ms), sid, cold };
+}
+
 /** Build the per-session cold-start spans, tagged with the session id + authoritative cold. */
 export function coldStartSpans(
 	sid: string,

package/src/commands/manager-core.ts

@@ -17,7 +17,9 @@ const SHUTDOWN_REASONS = new Set<string>(["superseded", "updated", "manual"]);
 export type ControlMsg =
 	| { type: "provision"; sessionId: string; tenant: string }
 	| { type: "release"; sessionId: string }
-	| { type: "status" }
+	// An sid-less status is the legacy no-op sink; an sid-carrying status is a
+	// keepalive from an actively-chatting worker (see keepaliveFrame/touchLastSeen).
+	| { type: "status"; sessionId?: string }
 	| { type: "hello" }
 	| { type: "shutdown"; reason: ShutdownReason };
 
@@ -42,7 +44,8 @@ function isNonEmpty(v: unknown): v is string {
 export function parseControlMsg(raw: unknown): ControlMsg | null {
 	if (!raw || typeof raw !== "object") return null;
 	const m = raw as Record<string, unknown>;
-	if (m.type === "status") return { type: "status" };
+	if (m.type === "status")
+		return isNonEmpty(m.sessionId) ? { type: "status", sessionId: m.sessionId } : { type: "status" };
 	if (m.type === "provision" && isNonEmpty(m.sessionId) && isTenant(m.tenant))
 		return { type: "provision", sessionId: m.sessionId, tenant: m.tenant };
 	if (m.type === "release" && isNonEmpty(m.sessionId)) return { type: "release", sessionId: m.sessionId };
@@ -115,6 +118,27 @@ export function staleKeys(reg: Registry, now: number, idleMs: number): string[]
 	return out;
 }
 
+/** Refresh a worker's `lastSeen` from a keepalive/status frame; true iff a known
+ * session was touched. The manager never sees chat traffic (it flows worker↔
+ * bridge↔extension), so an actively-used session would otherwise be idle-reaped
+ * mid-conversation. An actively-chatting worker emits `keepaliveFrame` to drive
+ * this, keeping its session out of `staleKeys`. */
+export function touchLastSeen(reg: Registry, sessionId: string | undefined, now: number): boolean {
+	if (!sessionId) return false;
+	const w = reg.get(sessionId);
+	if (!w) return false;
+	w.lastSeen = now;
+	return true;
+}
+
+/** The NDJSON keepalive an actively-chatting worker writes to the manager control
+ * socket to refresh its `lastSeen` (consumed by `touchLastSeen`). Null for the
+ * unbound `spare` sentinel or an empty id — a spare has no session to keep alive. */
+export function keepaliveFrame(sessionId: string): string | null {
+	if (!sessionId || sessionId === "spare") return null;
+	return `${JSON.stringify({ type: "status", sessionId })}\n`;
+}
+
 /** 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(

package/src/commands/manager-keepalive.ts

@@ -0,0 +1,117 @@
+/**
+ * Worker→manager keepalive client.
+ *
+ * The manager idle-reaps a worker whose `lastSeen` is older than `IDLE_MS`, and
+ * `lastSeen` is refreshed ONLY when the manager receives a control frame. Chat
+ * traffic flows worker↔bridge↔extension and never reaches the manager, so an
+ * actively-used-then-briefly-idle session used to be reaped mid-conversation
+ * (the "Turn aborted." after a break). This client emits a `status{sessionId}`
+ * keepalive over the manager's UNIX control socket while a turn is in flight and
+ * at each turn start, so the manager's sweep leaves an in-use session alive.
+ *
+ * The socket lifecycle (connect/reconnect) is injected as a `Connector` so the
+ * scheduling/emit logic is unit-testable without a real socket; the worker wires
+ * a `Bun.connect` transport. Best-effort throughout: if the manager socket is
+ * down (e.g. mid-supersede) emits are dropped and the next emit reconnects — so
+ * after a manager handoff the keepalive re-targets the successor manager, which
+ * has already re-adopted this worker.
+ */
+import { keepaliveFrame } from "./manager-core";
+
+/** A live connection to the manager control socket. */
+export interface KeepaliveTransport {
+	write(data: string): void;
+	close(): void;
+}
+
+/** Opens a transport; `onClose` MUST be invoked when the connection drops so the
+ * keepalive knows to reconnect on its next emit. Returns null if it cannot open. */
+export type Connector = (onClose: () => void) => Promise<KeepaliveTransport | null>;
+
+export interface ManagerKeepaliveDeps {
+	connect: Connector;
+	/** Current worker session id (may transition from "spare" to a real id). */
+	sessionId: () => string;
+	/** True while a chat turn is in flight. */
+	busy: () => boolean;
+}
+
+export class ManagerKeepalive {
+	#deps: ManagerKeepaliveDeps;
+	#transport: KeepaliveTransport | null = null;
+	#connecting = false;
+	#pending = false; // a keepalive is due once a connection is (re)established
+	#stopped = false;
+
+	constructor(deps: ManagerKeepaliveDeps) {
+		this.#deps = deps;
+	}
+
+	/** Periodic tick (driven by the worker's interval): emit iff a turn is busy. */
+	tick(): void {
+		if (this.#deps.busy()) this.#emit();
+	}
+
+	/** One-shot emit at the start of each turn — refreshes lastSeen immediately so
+	 * a session with long think-time between turns is never reaped between them. */
+	turnStart(): void {
+		this.#emit();
+	}
+
+	/** Stop emitting and close any open transport. */
+	stop(): void {
+		this.#stopped = true;
+		this.#pending = false;
+		this.#transport?.close();
+		this.#transport = null;
+	}
+
+	#emit(): void {
+		if (this.#stopped) return;
+		const frame = keepaliveFrame(this.#deps.sessionId());
+		if (!frame) return; // spare / unbound → nothing to keep alive (also skips connecting)
+		if (this.#transport) {
+			try {
+				this.#transport.write(frame);
+			} catch {
+				this.#transport = null; // dead socket → drop and reconnect on next emit
+				this.#pending = true;
+				void this.#ensureConnected();
+			}
+			return;
+		}
+		this.#pending = true;
+		void this.#ensureConnected();
+	}
+
+	async #ensureConnected(): Promise<void> {
+		if (this.#stopped || this.#transport || this.#connecting) return;
+		this.#connecting = true;
+		let t: KeepaliveTransport | null = null;
+		try {
+			t = await this.#deps.connect(() => {
+				this.#transport = null; // socket dropped → next emit reconnects
+			});
+		} catch {
+			t = null;
+		}
+		this.#connecting = false;
+		if (!t) return; // manager unreachable — best-effort, a later emit retries
+		if (this.#stopped) {
+			t.close();
+			return;
+		}
+		this.#transport = t;
+		if (this.#pending) {
+			this.#pending = false;
+			const frame = keepaliveFrame(this.#deps.sessionId());
+			if (frame) {
+				try {
+					this.#transport.write(frame);
+				} catch {
+					this.#transport = null;
+				}
+			}
+		}
+	}
+}

package/src/commands/manager.ts

@@ -11,6 +11,8 @@
  *          on sessionId, so two tabs of the SAME tenant get two workers.
  *   {"type":"release","sessionId":"tab-7"}  → kill + forget that session's worker
  *   {"type":"status"}                        → accepted; no-op sink
+ *   {"type":"status","sessionId":"tab-7"}    → keepalive: refresh that worker's
+ *          lastSeen so an actively-chatting session is not idle-reaped
  *
  * All registry/port/idempotency/idle policy is the pure `manager-core`; this file
  * is the thin I/O shell (socket, spawn, kill, timer) around it. A background sweep
@@ -25,7 +27,15 @@ import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { VERSION } from "@f5-sales-demo/pi-utils/dirs";
 import { portCandidates } from "../browser/extension-bridge";
 import { removeManagerState, writeManagerState } from "../services/manager-state";
-import { needsProvision, parseControlMsg, pickPort, type Registry, sparesToSpawn, staleKeys } from "./manager-core";
+import {
+	needsProvision,
+	parseControlMsg,
+	pickPort,
+	type Registry,
+	sparesToSpawn,
+	staleKeys,
+	touchLastSeen,
+} from "./manager-core";
 
 /** Reap a worker idle longer than this (ms). */
 const IDLE_MS = 20 * 60_000;
@@ -434,8 +444,13 @@ export default class Manager extends Command {
 					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)
+				touchLastSeen(reg, msg.sessionId, Date.now()); // touch on every provision (keep-alive)
+			} else if (msg.type === "status") {
+				// Keepalive from an actively-chatting worker (#idle-reap): refresh
+				// lastSeen so the idle sweep never reaps a session that is in use.
+				// Chat traffic never reaches the manager, so this is the only signal
+				// that an otherwise-quiet-to-the-manager worker is still working.
+				touchLastSeen(reg, msg.sessionId, Date.now());
 			} else if (msg.type === "release") {
 				reap(msg.sessionId);
 			} else if (msg.type === "shutdown") {
@@ -452,7 +467,6 @@ export default class Manager extends Command {
 					/* client hung up mid-handshake — ignore */
 				}
 			}
-			// "status" is validated but currently a no-op sink.
 		};
 
 		// Per-connection NDJSON buffer: a control frame can be split across two TCP

package/src/commands/worker.ts

@@ -13,18 +13,21 @@
  * `XCSH_SESSION_TENANT` so it advertises its assigned tenant even before a context
  * is bound. This lets the extension panel lock onto the right tenant immediately.
  */
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { getProjectDir, getXCSHConfigDir, logger } from "@f5-sales-demo/pi-utils";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
 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 { coldStartSpans, type SpanFrame, sessionBuildSpan } from "../browser/ttft-spans";
 import { initializeWithSettings } from "../discovery";
 import { createAgentSession } from "../sdk";
 import { activateTenantContext } from "../services/session-context-binding";
 import { ContextService } from "../services/xcsh-context";
 import { deriveTenantEnv } from "../services/xcsh-env";
+import { type KeepaliveTransport, ManagerKeepalive } from "./manager-keepalive";
 
 /** 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"
@@ -77,6 +80,16 @@ export function sessionInfoForWorker(): {
 /** Hard ceiling for draining an in-flight chat turn on SIGTERM before teardown (#1874). */
 const WORKER_DRAIN_TIMEOUT_MS = 10_000;
 
+/** How often the worker pings the manager while a turn is in flight, refreshing its
+ * lastSeen so an actively-chatting session is never idle-reaped. Comfortably under
+ * the manager's IDLE_MS (20 min); a turn also pings once at its start. */
+const KEEPALIVE_MS = 60_000;
+
+/** The manager control socket (same derivation as native-host / chrome-cli). */
+function managerSockPath(): string {
+	return process.env.XCSH_MANAGER_SOCK ?? join(homedir(), ".xcsh", "manager.sock");
+}
+
 /** Browser-automation tool set — identical scoping to `main.ts`'s extension path.
  * With scoped tools the ONLY way to create a resource is the form-driven workflow
  * runner, which is exactly what the human watching the browser wants. */
@@ -162,11 +175,22 @@ export default class Worker extends Command {
 			for (const s of coldStartBuffer) bridge.send(s);
 			coldStartSent = true;
 		};
+		// TTFT: the session_build span (createAgentSession seam) is computed after the
+		// bridge is listening but possibly before the extension connects — buffer it and
+		// flush on connect, same as the cold-start spans.
+		let sessionBuildFrame: SpanFrame | null = null;
+		let sessionBuildSent = false;
+		const flushSessionBuild = (): void => {
+			if (sessionBuildSent || !clientConnected || !sessionBuildFrame) return;
+			bridge.send(sessionBuildFrame);
+			sessionBuildSent = 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();
+			flushSessionBuild();
 		});
 
 		if (coldSpawn && process.env.XCSH_SESSION_ID && Number.isFinite(spawnAtEnv)) {
@@ -218,6 +242,7 @@ export default class Worker extends Command {
 		// session:createAgentSession — the heavy step between bridge-ready and
 		// session-ready (model registry, tools, context bootstrap). Wrapped as a span
 		// (parity with main.ts:892) so PI_TIMING reveals the per-tab session-load split.
+		const sessionBuildStart = Date.now();
 		const { session } = await logger.time("session:createAgentSession", createAgentSession, {
 			cwd,
 			hasUI: false,
@@ -232,6 +257,15 @@ export default class Worker extends Command {
 			// sets XCSH_BENCH_EXTENSION (absolute path). Inert for normal workers.
 			...(process.env.XCSH_BENCH_EXTENSION ? { additionalExtensionPaths: [process.env.XCSH_BENCH_EXTENSION] } : {}),
 		});
+		// TTFT: emit the session_build stage (createAgentSession seam) as a WS span so the
+		// bench and diagnostics panel stop hiding plugin/discovery/registry-load cost inside
+		// total ttft_ms. Buffered + flushed on connect (parity with cold-start spans).
+		sessionBuildFrame = sessionBuildSpan(
+			process.env.XCSH_SESSION_ID ?? "",
+			coldSpawn,
+			Date.now() - sessionBuildStart,
+		);
+		flushSessionBuild();
 
 		// TTFT Phase 3 hermeticity: the bench-instant stand-in provider is registered while
 		// createAgentSession loads the bench extension (additionalExtensionPaths), which is
@@ -253,6 +287,38 @@ export default class Worker extends Command {
 		const chatHandler = new ChatHandler(bridge, session);
 		chatHandler.attach();
 
+		// Manager keepalive: while a turn is in flight (and at each turn start), ping
+		// the manager control socket so it refreshes this worker's lastSeen and its
+		// idle sweep does not reap an actively-used session mid-conversation. Chat
+		// traffic never reaches the manager, so this is the only liveness signal.
+		// Best-effort + self-reconnecting: a dropped socket (e.g. manager supersede)
+		// is re-opened on the next emit, re-targeting the successor manager.
+		const keepalive = new ManagerKeepalive({
+			sessionId: () => sessionInfoForWorker().sessionId ?? "spare",
+			busy: () => chatHandler.busy,
+			connect: async onClose => {
+				try {
+					const sock = await Bun.connect({
+						unix: managerSockPath(),
+						socket: { data() {}, close: () => onClose(), error: () => onClose() },
+					});
+					const transport: KeepaliveTransport = {
+						write: data => {
+							sock.write(data);
+						},
+						close: () => {
+							sock.end();
+						},
+					};
+					return transport;
+				} catch {
+					return null; // manager not reachable — a later emit retries
+				}
+			},
+		});
+		chatHandler.onTurnStart(() => keepalive.turnStart());
+		const keepaliveTimer = setInterval(() => keepalive.tick(), KEEPALIVE_MS);
+
 		// session-ready. Emit the per-tab boot breakdown when requested (parity with
 		// main.ts:1002-1009). PI_TIMING=x prints then exits — used by bench/extension-session.ts
 		// to measure total worker cold-start; otherwise this is a no-op.
@@ -266,6 +332,8 @@ export default class Worker extends Command {
 
 		let shuttingDown = false;
 		const teardown = () => {
+			clearInterval(keepaliveTimer);
+			keepalive.stop();
 			chatHandler.dispose();
 			void bridge.close().finally(() => process.exit(0));
 		};

package/src/config/auto-config.ts

@@ -16,6 +16,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { $env, logger, readProviderFromModelsYml } from "@f5-sales-demo/pi-utils";
+import { DEFAULT_MODEL_ROLE } from "./settings-schema";
 
 /** Current config schema version. Bump when the generated format changes. */
 export const CURRENT_CONFIG_VERSION = 2;
@@ -118,47 +119,68 @@ export function readLiteLLMConfig(modelsPath: string): LiteLLMConfig | undefined
 	return { baseUrl: resolvedBaseUrl, apiKey: resolvedApiKey };
 }
 
-/** Generate config.yml with sensible defaults for LiteLLM. */
+/**
+ * The default model role is baked into the binary (settings-schema `modelRoles`
+ * default) so a fresh install needs NO config.yml. Re-exported here for the
+ * healer and tests; there is a single source of truth in settings-schema.
+ */
+export const DEFAULT_MODEL_ROLE_VALUE = DEFAULT_MODEL_ROLE;
+
+/**
+ * Generate config.yml for the LiteLLM proxy.
+ *
+ * The default model role is NOT written here — it ships in the binary
+ * (settings-schema), so we never persist a model id that can go stale (the
+ * failure mode behind the invalid-model / catalog-walk bugs). This only carries
+ * settings that differ from the built-in schema defaults.
+ */
 export function generateConfigYml(): string {
 	return [
 		"# Auto-generated by xcsh for LiteLLM proxy",
-		"modelRoles:",
-		"  default: anthropic/claude-opus-4-6",
-		"",
+		"# The default model role ships in the binary — none is written here.",
 		"providers:",
 		"  image: openai",
 		"  webSearch: anthropic",
 		"",
-		"generate_image:",
-		"  enabled: true",
-		"",
-		"inspect_image:",
-		"  enabled: true",
-		"",
-		"images:",
-		"  blockImages: false",
-		"  autoResize: true",
-		"",
-		"terminal:",
-		"  showImages: true",
-		"",
 	].join("\n");
 }
 
 /**
- * Ensure config.yml has a modelRoles.default entry.
- * Existing configs from earlier versions may be missing this, causing xcsh
- * to fall through to the "first available model" fallback which picks stale
- * cached models that the proxy can't serve.
+ * Provider prefixes that are never valid as a persisted runtime default.
+ * `bench-instant` is the TTFT benchmark stand-in provider — it only registers
+ * when XCSH_BENCH_EXTENSION is set, so a `bench-instant/*` default in a normal
+ * worker is unresolvable and drops xcsh into the "first available model"
+ * fallback (which can pick a model the F5 proxy can't serve).
+ */
+const UNRESOLVABLE_DEFAULT_PROVIDER_PREFIXES = ["bench-instant/"];
+
+/**
+ * Repair a config.yml whose `modelRoles.default` can never resolve at runtime
+ * (e.g. `bench-instant/bench-instant` leaked from a benchmark run) by rewriting
+ * it to the binary default. Left unhealed, such a default triggers the
+ * catalog-wide fallback that surfaced as the AWS-SSO / invalid-model errors.
+ *
+ * A config.yml with NO `modelRoles:` needs no healing — the binary provides the
+ * default. We deliberately do not add one, to avoid persisting a stale id.
  */
 export function healConfigYmlModelRoles(configPath: string): void {
 	try {
 		const content = fs.readFileSync(configPath, "utf-8");
-		if (content.includes("modelRoles:")) return; // Already has modelRoles
-		// Prepend modelRoles section
-		const healed = `modelRoles:\n  default: anthropic/claude-opus-4-6\n\n${content}`;
-		fs.writeFileSync(configPath, healed);
-		logger.debug("Healed config.yml: added default modelRoles", { configPath });
+		if (!content.includes("modelRoles:")) return; // binary default applies
+		const defaultLine = /^(\s*)default:\s*(\S+)\s*$/m;
+		const match = content.match(defaultLine);
+		if (match) {
+			const [, indent, value] = match;
+			if (UNRESOLVABLE_DEFAULT_PROVIDER_PREFIXES.some(prefix => value.startsWith(prefix))) {
+				const healed = content.replace(defaultLine, `${indent}default: ${DEFAULT_MODEL_ROLE_VALUE}`);
+				fs.writeFileSync(configPath, healed);
+				logger.debug("Healed config.yml: replaced unresolvable default modelRole", {
+					configPath,
+					previous: value,
+					replacement: DEFAULT_MODEL_ROLE_VALUE,
+				});
+			}
+		}
 	} catch {
 		// Best-effort — don't block startup
 	}

package/src/config/model-registry.ts

@@ -774,6 +774,8 @@ export class ModelRegistry {
 	#customProviderApiKeys: Map<string, string> = new Map();
 	#keylessProviders: Set<string> = new Set();
 	#discoverableProviders: DiscoveryProviderConfig[] = [];
+	/** Provider ids explicitly configured in models.yml (empty until a config is loaded). */
+	#configuredProviderIds: Set<string> = new Set();
 	#customModelOverlays: CustomModelOverlay[] = [];
 	#providerOverrides: Map<string, ProviderOverride> = new Map();
 	#modelOverrides: Map<string, Map<string, ModelOverride>> = new Map();
@@ -923,6 +925,7 @@ export class ModelRegistry {
 		this.#configError = configError;
 		this.#keylessProviders = keylessProviders;
 		this.#discoverableProviders = discoverableProviders;
+		this.#configuredProviderIds = configuredProviders;
 		this.#customModelOverlays = customModels;
 		this.#providerOverrides = overrides;
 		this.#modelOverrides = modelOverrides;
@@ -1993,6 +1996,16 @@ export class ModelRegistry {
 		return this.#models.filter(model => this.#isModelAvailable(model));
 	}
 
+	/**
+	 * Provider ids explicitly configured in models.yml.
+	 * Empty when no config has been loaded (e.g. a fresh install before `/login`).
+	 * Used to keep automatic model selection scoped to providers the user has
+	 * actually set up, rather than probing the entire bundled catalog.
+	 */
+	getConfiguredProviderIds(): Set<string> {
+		return new Set(this.#configuredProviderIds);
+	}
+
 	getDiscoverableProviders(): string[] {
 		const disabledProviders = getDisabledProviderIdsFromSettings();
 		return this.#discoverableProviders

package/src/config/settings-schema.ts

@@ -152,6 +152,14 @@ export interface ModelTagsSettings {
 const EMPTY_STRING_ARRAY: string[] = [];
 const EMPTY_STRING_RECORD: Record<string, string> = {};
 const DEFAULT_CYCLE_ORDER: string[] = ["smol", "default", "slow"];
+/**
+ * Binary-baked default model role. Ships in the binary so a fresh install needs
+ * NO `~/.xcsh/agent/config.yml` — `/login` only supplies the (PII) proxy URL + key.
+ * The gateway serves the id `claude-opus-4-8`; its catalog entry carries the
+ * `context-1m-2025-08-07` beta for 1M context.
+ */
+export const DEFAULT_MODEL_ROLE = "anthropic/claude-opus-4-8";
+const DEFAULT_MODEL_ROLES: Record<string, string> = { default: DEFAULT_MODEL_ROLE };
 const EMPTY_MODEL_TAGS_RECORD: ModelTagsSettings = {};
 export const DEFAULT_BASH_INTERCEPTOR_RULES: BashInterceptorRule[] = [
 	{
@@ -245,7 +253,7 @@ export const SETTINGS_SCHEMA = {
 
 	disabledExtensions: { type: "array", default: EMPTY_STRING_ARRAY },
 
-	modelRoles: { type: "record", default: EMPTY_STRING_RECORD },
+	modelRoles: { type: "record", default: DEFAULT_MODEL_ROLES },
 
 	modelTags: { type: "record", default: EMPTY_MODEL_TAGS_RECORD },
 

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.61.3",
-	"commit": "1546a875f07608812967e1169ea86c2bd3f837ac",
-	"shortCommit": "1546a87",
+	"version": "19.61.5",
+	"commit": "e9f45bc1c87e84c1d99060a016ae1e20907e2210",
+	"shortCommit": "e9f45bc",
 	"branch": "main",
-	"tag": "v19.61.3",
-	"commitDate": "2026-07-07T11:57:08Z",
-	"buildDate": "2026-07-07T12:21:42.145Z",
+	"tag": "v19.61.5",
+	"commitDate": "2026-07-08T01:47:55Z",
+	"buildDate": "2026-07-08T02:09:52.692Z",
 	"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/1546a875f07608812967e1169ea86c2bd3f837ac",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.3"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/e9f45bc1c87e84c1d99060a016ae1e20907e2210",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.5"
 };

package/src/sdk.ts

@@ -31,7 +31,13 @@ import { loadCapability } from "./capability";
 import { type Rule, ruleCapability } from "./capability/rule";
 import { hasLiteLLMEnv } from "./config/auto-config";
 import { ModelRegistry } from "./config/model-registry";
-import { formatModelString, parseModelPattern, parseModelString, resolveModelRoleValue } from "./config/model-resolver";
+import {
+	defaultModelPerProvider,
+	formatModelString,
+	parseModelPattern,
+	parseModelString,
+	resolveModelRoleValue,
+} from "./config/model-resolver";
 import { loadPromptTemplates as loadPromptTemplatesInternal, type PromptTemplate } from "./config/prompt-templates";
 import { Settings, type SkillsSettings } from "./config/settings";
 import { CursorExecHandlers } from "./cursor";
@@ -1296,8 +1302,26 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Fall back to first available model with a valid API key.
 		// Skip fallback if the user explicitly requested a model via --model that wasn't found.
 		if (!model && !options.modelPattern) {
-			const allModels = modelRegistry.getAll();
-			for (const candidate of allModels) {
+			// Scope automatic selection to providers the user has actually configured
+			// in models.yml. This keeps a stray credential for an unconfigured provider
+			// (e.g. an expired AWS_PROFILE that makes Bedrock look "authenticated") from
+			// ever being selected, and stops us probing the entire bundled catalog. A
+			// fresh install (nothing configured) falls straight through to /login guidance
+			// instead of walking legacy catalog entries the proxy can't serve.
+			const configuredProviders = modelRegistry.getConfiguredProviderIds();
+			const candidates =
+				configuredProviders.size > 0
+					? modelRegistry.getAll().filter(candidate => configuredProviders.has(candidate.provider))
+					: [];
+			// Within a configured provider, prefer its designated default model over raw
+			// catalog order (which begins at legacy ids like claude-3-5-sonnet-20240620).
+			const isProviderDefault = (candidate: Model): boolean =>
+				defaultModelPerProvider[candidate.provider as keyof typeof defaultModelPerProvider] === candidate.id;
+			const orderedCandidates = [
+				...candidates.filter(isProviderDefault),
+				...candidates.filter(candidate => !isProviderDefault(candidate)),
+			];
+			for (const candidate of orderedCandidates) {
 				if (await hasModelApiKey(candidate)) {
 					model = candidate;
 					break;