@sayknow-cli/coding-agent 0.6.5 → 0.6.7

package/src/sdk/broker/process-guard.ts

@@ -0,0 +1,160 @@
+import * as fs from "node:fs";
+
+/**
+ * Guards for the SDK's long-lived background processes (`sdk broker-internal`,
+ * `sdk session-host-internal`). They are spawned detached and outlive whoever
+ * started them, so each one has to notice on its own when it has no reason, or no
+ * way, to keep running.
+ */
+
+/** How often the guards run. Cheap: one `stat`, plus a small JSON read for hosts. */
+export const PROCESS_GUARD_INTERVAL_MS = 5_000;
+
+/**
+ * The entry script of a process run from source (`bun …/src/cli.ts sdk …`), or
+ * undefined for a compiled binary, whose entry lives in Bun's virtual filesystem
+ * and cannot disappear from under it.
+ */
+export function sourceEntryPath(main: string | undefined = Bun.main): string | undefined {
+	if (!main) return undefined;
+	if (main.startsWith("/$bunfs/") || /^[A-Za-z]:[\\/]~BUN[\\/]/.test(main)) return undefined;
+	return main;
+}
+
+/** Errors that mean the file is gone, or the volume holding it is: unmounted, ejected, or failing. */
+const SOURCE_GONE_CODES = new Set(["ENOENT", "ENOTDIR", "EIO", "ENXIO", "ENODEV"]);
+
+/** Whether the source entry is still reachable. A compiled binary (no entry) always is. */
+export function sourceEntryAvailable(
+	entry: string | undefined,
+	stat: (file: string) => unknown = file => fs.statSync(file),
+): boolean {
+	if (!entry) return true;
+	try {
+		stat(entry);
+		return true;
+	} catch (error) {
+		return !SOURCE_GONE_CODES.has((error as NodeJS.ErrnoException).code ?? "");
+	}
+}
+
+/**
+ * End this process at once when the source it runs from has vanished — typically
+ * an external drive with the checkout was unplugged. The native addon is mapped
+ * from that checkout and paged in lazily, so the next call into it faults on a
+ * page that can no longer be read, and Bun's fault handler then spins on the same
+ * unreadable mapping at 100% CPU forever. No cleanup is safe at that point (it
+ * would call into the same addon), so the process kills itself; readers already
+ * treat its discovery and markers as stale once the pid is gone.
+ *
+ * Call this before any native call in a periodic task. Returns true if it fired.
+ */
+export function exitIfSourceGone(
+	entry: string | undefined = sourceEntryPath(),
+	options: { stat?: (file: string) => unknown; kill?: () => void } = {},
+): boolean {
+	if (sourceEntryAvailable(entry, options.stat)) return false;
+	(options.kill ?? (() => process.kill(process.pid, "SIGKILL")))();
+	return true;
+}
+
+/** What a session host needs to recognise that its session is still its own. */
+export interface SessionHostAuthority {
+	/** `<stateRoot>/sdk/<sessionId>.lifecycle.json`, written once by the broker when it spawned this host. */
+	markerPath: string;
+	pid: number;
+	effectMarker: string;
+	incarnation: string;
+	/** The host's worktree. */
+	cwd: string;
+}
+
+/**
+ * `held`: the marker still names this process and the worktree exists. `lost`: the
+ * marker or worktree is gone, or the marker names another process — the session was
+ * deleted, taken over, or its whole state root was removed (a finished test). `unknown`:
+ * something could not be read for another reason; that is not evidence either way.
+ */
+export type SessionHostAuthorityState = "held" | "lost" | "unknown";
+
+const GONE_CODES = new Set(["ENOENT", "ENOTDIR"]);
+
+export function checkSessionHostAuthority(
+	authority: SessionHostAuthority,
+	io: { readFile?: (file: string) => string; stat?: (file: string) => unknown } = {},
+): SessionHostAuthorityState {
+	const readFile = io.readFile ?? (file => fs.readFileSync(file, "utf8"));
+	const stat = io.stat ?? (file => fs.statSync(file));
+	const code = (error: unknown) => (error as NodeJS.ErrnoException).code ?? "";
+	try {
+		stat(authority.cwd);
+	} catch (error) {
+		return GONE_CODES.has(code(error)) ? "lost" : "unknown";
+	}
+	let raw: string;
+	try {
+		raw = readFile(authority.markerPath);
+	} catch (error) {
+		return GONE_CODES.has(code(error)) ? "lost" : "unknown";
+	}
+	let marker: { pid?: unknown; effectMarker?: unknown; incarnation?: unknown };
+	try {
+		marker = JSON.parse(raw) as typeof marker;
+	} catch {
+		// The broker publishes the marker by atomic rename, so a torn read is not
+		// expected; still, one unparsable read alone does not end a live session.
+		return "unknown";
+	}
+	return marker.pid === authority.pid &&
+		marker.effectMarker === authority.effectMarker &&
+		marker.incarnation === authority.incarnation
+		? "held"
+		: "lost";
+}
+
+/** Consecutive `lost` checks before a host gives up its session (≈15s at the default interval). */
+export const SESSION_HOST_LOST_CHECKS = 3;
+
+/**
+ * Watch a running session host. It stops (through `onLost`, the host's normal
+ * shutdown) once its ownership marker or worktree has been gone for
+ * {@link SESSION_HOST_LOST_CHECKS} checks in a row, and kills itself at once if the
+ * source checkout it runs from disappears. Before this, a host whose session state
+ * had been deleted kept running until someone killed it — for days, after tests.
+ * Returns a function that stops the watch.
+ */
+export function startSessionHostGuard(
+	options: SessionHostAuthority & {
+		onLost: () => void;
+		intervalMs?: number;
+		lostChecks?: number;
+		check?: (authority: SessionHostAuthority) => SessionHostAuthorityState;
+		sourceGuard?: () => boolean;
+		setInterval?: typeof setInterval;
+		clearInterval?: typeof clearInterval;
+	},
+): () => void {
+	const testInterval = Number(process.env.SKC_SDK_TEST_HOST_GUARD_MS);
+	const intervalMs =
+		options.intervalMs ??
+		(Number.isFinite(testInterval) && testInterval > 0 ? testInterval : PROCESS_GUARD_INTERVAL_MS);
+	const lostChecks = options.lostChecks ?? SESSION_HOST_LOST_CHECKS;
+	const check = options.check ?? checkSessionHostAuthority;
+	const sourceGuard = options.sourceGuard ?? (() => exitIfSourceGone());
+	const set = options.setInterval ?? setInterval;
+	const clear = options.clearInterval ?? clearInterval;
+	let misses = 0;
+	let stopped = false;
+	const timer = set(() => {
+		if (stopped || sourceGuard()) return;
+		misses = check(options) === "lost" ? misses + 1 : 0;
+		if (misses < lostChecks) return;
+		stopped = true;
+		clear(timer);
+		options.onLost();
+	}, intervalMs);
+	return () => {
+		stopped = true;
+		clear(timer);
+	};
+}

package/src/sdk/broker/transport.ts

@@ -45,11 +45,16 @@ export class BrokerTransport {
 	readonly #requestedPort: number;
 	#server: Bun.Server<undefined> | null = null;
 	#port = 0;
+	#openConnections = 0;
 	constructor(broker: Broker, token: string, port = 0) {
 		this.#broker = broker;
 		this.#token = token;
 		this.#requestedPort = port;
 	}
+	/** Client WebSockets currently open. The broker does not idle out while any is. */
+	get openConnections(): number {
+		return this.#openConnections;
+	}
 	get port(): number {
 		if (!this.#server) throw new Error("Broker transport is not running");
 		return this.#port;
@@ -71,7 +76,15 @@ export class BrokerTransport {
 			},
 			websocket: {
 				maxPayloadLength: MAX_BROKER_JSON_FRAME_BYTES * 2,
-				open: socket => send(socket, { type: "broker_hello", protocolVersion: PROTOCOL_VERSION }),
+				open: socket => {
+					this.#openConnections += 1;
+					this.#broker.noteActivity();
+					send(socket, { type: "broker_hello", protocolVersion: PROTOCOL_VERSION });
+				},
+				close: () => {
+					this.#openConnections = Math.max(0, this.#openConnections - 1);
+					this.#broker.noteActivity();
+				},
 				message: (socket, message) => void this.#handleMessage(socket, message),
 			},
 		});
@@ -82,6 +95,7 @@ export class BrokerTransport {
 		const server = this.#server;
 		this.#server = null;
 		if (server) await server.stop(true);
+		this.#openConnections = 0;
 	}
 	async #handleMessage(socket: ServerWebSocket<unknown>, raw: string | Buffer): Promise<void> {
 		if (Buffer.byteLength(raw) > MAX_BROKER_JSON_FRAME_BYTES) {

package/src/sdk/bus/chat-daemon-runtime.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { ensureBroker } from "../broker/ensure";
 import { type IndexedSession, SessionIndex } from "../broker/session-index";
 import { SdkClient, SdkClientError } from "../client/client";
 import { readSdkBrokerDiscovery, readSdkSessionEndpoint, type SdkSessionEndpoint } from "../client/discovery";
@@ -61,6 +62,8 @@ export interface ChatDaemonRuntimeDeps {
 	createClient?: (endpoint: SdkSessionEndpoint) => Promise<ChatDaemonSdkClient>;
 	createIndex?: (agentDir: string) => SessionIndex;
 	createBrokerClient?: (endpoint: { url: string; token: string }) => Promise<ChatDaemonSdkClient>;
+	/** Starts the agent broker when none is running (default: `ensureBroker`). */
+	ensureBroker?: (settings: { agentDir: string }) => Promise<unknown>;
 	onReconciled?: () => void;
 	setInterval?: typeof setInterval;
 	clearInterval?: typeof clearInterval;
@@ -480,7 +483,16 @@ export class ChatDaemonRuntime {
 		input: Record<string, unknown>,
 		idempotencyKey: string,
 	): Promise<Record<string, unknown>> {
-		const discovery = await readSdkBrokerDiscovery(this.input.agentDir);
+		let discovery = await readSdkBrokerDiscovery(this.input.agentDir);
+		if (!discovery) {
+			// A broker with nothing to serve stops on its own; start a fresh one for this command.
+			try {
+				await (this.deps.ensureBroker ?? ensureBroker)({ agentDir: this.input.agentDir });
+			} catch {
+				throw new ChatDeliveryError("pre_send");
+			}
+			discovery = await readSdkBrokerDiscovery(this.input.agentDir);
+		}
 		if (!discovery) throw new ChatDeliveryError("pre_send");
 		let client: ChatDaemonSdkClient;
 		try {

package/src/sdk/protocol/operation-inventory.generated.json

@@ -1771,6 +1771,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "slash_command:fallback",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "exclude",
+		"rationale": "local fallback-chain configuration (fallback.models / fallback.auto settings); no SDK operation counterpart, and SDK clients observe switches via model_fallback_switched",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "slash_command:effort",
 		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
@@ -4419,6 +4430,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "agent_session:getDefaultFallbackChain",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal profile and fallback-chain state, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:abortRetry",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/session.ts

@@ -110,7 +110,7 @@ import {
 } from "../secrets";
 import { AgentSession, type ForkContextSeed } from "../session/agent-session";
 import type { AuthStorage } from "../session/auth-storage";
-import { discoverAuthStorage } from "../session/auth-storage-discovery";
+import { applyCredentialRankingModeSetting, discoverAuthStorage } from "../session/auth-storage-discovery";
 import { type CustomMessage, convertToLlm } from "../session/messages";
 import { createReadonlySessionManager, SessionManager } from "../session/session-manager";
 import { formatNoModelsAvailableFallback } from "../setup/model-onboarding-guidance";
@@ -1057,6 +1057,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 		const settings = options.settings ?? (await logger.time("settings", Settings.init, { cwd, agentDir }));
 		modelRegistry.applyConfiguredModelBindings(settings);
+		// Multi-account order comes from settings (the env var still overrides it); apply it
+		// before the first model-availability probe picks an account for this session.
+		applyCredentialRankingModeSetting(authStorage, settings);
 		logger.time("initializeWithSettings", initializeWithSettings, settings);
 		const canRefreshModelsBeforeCredentialSelector =
 			!options.credentialSelector || runtimeCredentialSelectorInstalled || options.modelRegistry !== undefined;

package/src/session/agent-session.ts

@@ -366,6 +366,7 @@ import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-
 import { buildWorkflowIntentDiff, WORKFLOW_INTENT_DIFF_CUSTOM_TYPE } from "../workflow/workflow-intent-diff";
 import { buildWorkspaceTree, type WorkspaceTree } from "../workspace-tree";
 import type { AuthStorage } from "./auth-storage";
+import { autoFallbackSelectors, selectorProvider } from "./auto-fallback";
 import {
 	DefaultModelSelectionRecoveryError,
 	type DefaultModelSelectionResult,
@@ -378,6 +379,7 @@ import {
 	effectiveFallbackDelay,
 	FallbackChainController,
 } from "./fallback-chain-controller";
+import { buildResponseLanguageReminder, detectResponseLanguage } from "./response-language";
 
 export { DefaultModelSelectionRecoveryError } from "./default-model-selection";
 
@@ -868,6 +870,14 @@ const KIMI_CODE_FIRST_EVENT_TIMEOUT_MESSAGES = {
 	]),
 } as const;
 
+/**
+ * Configured default-chain origins that mean "exactly this model": a subagent call
+ * composed by the task router, and an explicit `--model` at startup. These never get
+ * `fallback.models` or automatic entries appended. (A temporary pick installs its own
+ * runtime controller and never reaches the configured-chain path at all.)
+ */
+const EXACT_FALLBACK_CHAIN_ORIGINS: ReadonlySet<string> = new Set(["subagent", "startup-override"]);
+
 const ALIBABA_TOKEN_PLAN_PROVIDER = "alibaba-token-plan";
 const ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MESSAGES = {
 	"openai-responses": new Set([
@@ -7832,6 +7842,7 @@ export class AgentSession {
 			const eagerTodoPrelude =
 				!options?.synthetic && !hasPendingUserDirective ? this.#createEagerTodoPrelude(expandedText) : undefined;
 			const uiSkillPrelude = options?.synthetic ? undefined : this.#createUiSkillPrelude(expandedText);
+			const languagePrelude = options?.synthetic ? undefined : this.#createResponseLanguagePrelude(expandedText);
 
 			const userContent: (TextContent | ImageContent)[] = [{ type: "text", text: expandedText }];
 			if (options?.images) {
@@ -7861,8 +7872,9 @@ export class AgentSession {
 				await this.#promptWithMessage(message, expandedText, {
 					...options,
 					prependMessages:
-						eagerTodoPrelude || uiSkillPrelude
+						eagerTodoPrelude || uiSkillPrelude || languagePrelude
 							? [
+									...(languagePrelude ? [languagePrelude] : []),
 									...(uiSkillPrelude ? [uiSkillPrelude] : []),
 									...(eagerTodoPrelude ? [eagerTodoPrelude.message] : []),
 								]
@@ -12136,6 +12148,21 @@ export class AgentSession {
 	 * routing and therefore costs nothing extra. The patterns stay in front of it: when
 	 * they match, the model is never asked.
 	 */
+	/**
+	 * Name the user's language at the start of the turn when their message is clearly in a
+	 * non-Latin script, so the final report after long English tool output stays in it.
+	 */
+	#createResponseLanguagePrelude(promptText: string): AgentMessage | undefined {
+		const language = detectResponseLanguage(promptText);
+		if (!language) return undefined;
+		return {
+			role: "developer",
+			content: [{ type: "text", text: buildResponseLanguageReminder(language) }],
+			attribution: "agent",
+			timestamp: Date.now(),
+		};
+	}
+
 	#createUiSkillPrelude(promptText: string): AgentMessage | undefined {
 		if (this.#planModeState?.enabled) return undefined;
 		const matched = buildUiSkillActivationContext(promptText);
@@ -13903,10 +13930,28 @@ export class AgentSession {
 			controller.seedResolution(activeIndex, [...controller.skips, ...resolution.skips]);
 		}
 		if (!resolution.model) throw new Error(this.#fallbackExhaustionError(controller));
+		if ((controller.chain.appendedFrom ?? controller.chain.entries.length) < 2) {
+			// A one-model configuration is a chain only through appended fallbacks. With its
+			// model usable and the session not sitting on an appended fallback, leave the live
+			// model alone exactly as before anything was appended: a context promotion or a
+			// temporary scope stays, and an unchanged model is not re-set (which would close
+			// provider sessions such as the Codex websocket on every prompt).
+			if (activeIndex === resolutionStart && !this.#isOnAppendedFallback(controller)) return;
+			if (this.model && modelsAreEqual(this.model, resolution.model)) return;
+		}
 		this.#setModelAuthoritatively(resolution.model, "restore");
 		this.setThinkingLevel(resolution.explicitThinkingLevel ? resolution.thinkingLevel : this.thinkingLevel);
 	}
 
+	/** True when the live model is one of the entries appended after the configured chain. */
+	#isOnAppendedFallback(controller: FallbackChainController): boolean {
+		const model = this.model;
+		const appendedFrom = controller.chain.appendedFrom;
+		if (!model || appendedFrom === undefined) return false;
+		const key = `${model.provider}/${model.id}`;
+		return controller.chain.entries.slice(appendedFrom).some(entry => entry === key || entry.startsWith(`${key}:`));
+	}
+
 	/**
 	 * Materialize the default controller from the persisted configured-chain
 	 * metadata. Consumers seed only resolution state; role/origin/identity stay
@@ -13925,11 +13970,12 @@ export class AgentSession {
 		if (materializeSettingsChain) {
 			this.setConfiguredModelChain("default", settingsEntries, "modelRoles");
 		}
-		const chain: ConfiguredFallbackChain = materializeSettingsChain
+		const configured: ConfiguredFallbackChain = materializeSettingsChain
 			? { role: "default", entries: settingsEntries, origin: "modelRoles", explicitHead: true }
 			: configuredChain
 				? { ...configuredChain, entries: [...configuredChain.entries] }
 				: { role: "default", entries: settingsEntries, origin: "session", explicitHead: true };
+		const chain = this.#withFallbackExtras(configured);
 		const existing = this.#defaultFallbackController;
 		if (
 			existing &&
@@ -13943,6 +13989,76 @@ export class AgentSession {
 		return this.#defaultFallbackController;
 	}
 
+	/**
+	 * Append what runs after the configured chain when it is blocked: the user's
+	 * `fallback.models`, then (with `fallback.auto`) one model from each other
+	 * logged-in provider. Extras live only in the controller; the configured chain
+	 * the session persists is untouched. Temporary picks, subagent calls and an
+	 * explicit `--model` stay exactly what was asked for.
+	 */
+	#withFallbackExtras(chain: ConfiguredFallbackChain): ConfiguredFallbackChain {
+		if (EXACT_FALLBACK_CHAIN_ORIGINS.has(chain.origin)) return chain;
+		const entries = [...chain.entries];
+		const seen = new Set(entries);
+		const push = (selector: string): void => {
+			const trimmed = selector.trim();
+			if (!trimmed || seen.has(trimmed)) return;
+			seen.add(trimmed);
+			entries.push(trimmed);
+		};
+		for (const selector of this.settings.get("fallback.models")) push(selector);
+		// Automatic picks stay out of an `enabledModels` allow-list (a deliberate scope) and
+		// out of an explicit `retry.enabled: false` (the user asked for failures to surface).
+		if (
+			this.settings.get("fallback.auto") &&
+			this.settings.get("retry.enabled") !== false &&
+			this.settings.get("enabledModels").length === 0
+		) {
+			// Depends only on configured intent (never the live model), so the chain stays
+			// stable while a fallback is active and when the primary comes back.
+			const excludeProviders = new Set<string>();
+			for (const entry of entries) {
+				const provider = selectorProvider(entry);
+				if (provider) excludeProviders.add(provider);
+			}
+			for (const selector of this.#autoFallbackTail(excludeProviders)) push(selector);
+		}
+		return entries.length === chain.entries.length
+			? chain
+			: { ...chain, entries, appendedFrom: chain.entries.length };
+	}
+
+	#autoFallbackTail(excludeProviders: ReadonlySet<string>): string[] {
+		try {
+			const registry = this.#modelRegistry;
+			return autoFallbackSelectors({
+				available: registry.getAvailable(),
+				hasCredentials: provider => registry.authStorage.hasAuth(provider),
+				excludeProviders,
+				usageOrder: this.settings.getStorage()?.getModelUsageOrder(),
+			});
+		} catch (error) {
+			logger.debug("Automatic model fallback candidates unavailable", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return [];
+		}
+	}
+
+	/**
+	 * The default fallback chain the next prompt walks, automatic entries included,
+	 * and the position currently in use.
+	 */
+	getDefaultFallbackChain(): { entries: readonly string[]; activeIndex: number; appendedFrom: number } {
+		const controller = this.#defaultFallbackChain();
+		const entries = [...controller.chain.entries];
+		return {
+			entries,
+			activeIndex: controller.activeIndex,
+			appendedFrom: controller.chain.appendedFrom ?? entries.length,
+		};
+	}
+
 	async #handleManagedAttemptOutcome(outcome: ManagedAttemptOutcome): Promise<ManagedAttemptDecision> {
 		if (outcome.type === "run_terminal") {
 			this.#defaultFallbackChain().resetAttemptBudget();

package/src/session/auth-storage-discovery.ts

@@ -9,6 +9,7 @@
  */
 import { getAgentDbPath, getAgentDir } from "@sayknow-cli/utils";
 import { resolveConfigValue } from "../config/resolve-config-value";
+import type { Settings } from "../config/settings";
 import { resolveAuthBrokerConfig } from "./auth-broker-config";
 import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "./auth-storage";
 
@@ -25,7 +26,7 @@ import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "./auth
  */
 export async function discoverAuthStorage(agentDir: string = getAgentDir()): Promise<AuthStorage> {
 	const brokerConfig = await resolveAuthBrokerConfig();
-	const credentialRankingMode = resolveCredentialRankingMode();
+	const credentialRankingMode = credentialRankingModeFromEnv();
 	if (brokerConfig) {
 		const client = new AuthBrokerClient({ url: brokerConfig.url, token: brokerConfig.token });
 		const initialResult = await client.fetchSnapshot();
@@ -70,14 +71,28 @@ export async function discoverAuthStorage(agentDir: string = getAgentDir()): Pro
 }
 
 /**
- * Opt-in multi-account credential ranking mode, read from the
- * `SKC_CREDENTIAL_RANKING_MODE` env var. Unset/unknown → `undefined`, leaving
- * {@link AuthStorage}'s default (`balanced`) untouched. `earliest-reset`
- * switches to earliest-expiry-first selection so soon-to-reset tumbling-window
- * quota is drained before it is lost.
+ * Per-machine multi-account ranking override from `SKC_CREDENTIAL_RANKING_MODE`.
+ * Unset/unknown → `undefined`, so the `auth.credentialRankingMode` setting (or
+ * {@link AuthStorage}'s `balanced` default) decides. `earliest-reset` switches to
+ * earliest-expiry-first selection so soon-to-reset tumbling-window quota is
+ * drained before it is lost.
  */
-function resolveCredentialRankingMode(): "balanced" | "earliest-reset" | undefined {
+export function credentialRankingModeFromEnv(): "balanced" | "earliest-reset" | undefined {
 	const raw = process.env.SKC_CREDENTIAL_RANKING_MODE?.trim();
 	if (raw === "balanced" || raw === "earliest-reset") return raw;
 	return undefined;
 }
+
+/**
+ * Apply the `auth.credentialRankingMode` setting to a credential store. The env
+ * var still wins, so a machine that pins a mode keeps it whatever config says.
+ * Returns the mode now in effect.
+ */
+export function applyCredentialRankingModeSetting(
+	storage: Pick<AuthStorage, "setCredentialRankingMode">,
+	settings: Pick<Settings, "get">,
+): "balanced" | "earliest-reset" {
+	const mode = credentialRankingModeFromEnv() ?? settings.get("auth.credentialRankingMode");
+	storage.setCredentialRankingMode(mode);
+	return mode;
+}

package/src/session/auto-fallback.ts

@@ -0,0 +1,59 @@
+import type { Api, Model } from "@sayknow-cli/ai";
+import { defaultModelPerProvider } from "../config/model-resolver";
+
+/**
+ * How many other providers the automatic tail may add. Each entry can cost up to
+ * `fallback.maxAttempts` tries before the chain moves on, so the tail stays short.
+ */
+export const AUTO_FALLBACK_PROVIDER_LIMIT = 3;
+
+/** Provider of a `provider/model[:level]` selector, or undefined for bare aliases. */
+export function selectorProvider(selector: string): string | undefined {
+	const slash = selector.indexOf("/");
+	return slash > 0 ? selector.slice(0, slash) : undefined;
+}
+
+export interface AutoFallbackInput {
+	/** Models whose provider has auth configured (`ModelRegistry.getAvailable()`). */
+	available: readonly Model<Api>[];
+	/** True when the provider has a stored credential or API key (keyless local providers do not count). */
+	hasCredentials: (provider: string) => boolean;
+	/** Providers already in the chain; the tail adds a different provider or nothing. */
+	excludeProviders: ReadonlySet<string>;
+	/** Most-recently-used `provider/id` keys, newest first. */
+	usageOrder?: readonly string[];
+	limit?: number;
+}
+
+/**
+ * One model per other logged-in provider, for the automatic tail of the default
+ * fallback chain. Within a provider the model the user used most recently wins,
+ * then the provider's curated default; a provider with neither is skipped rather
+ * than guessed, because catalog order would land on an old model. Providers used
+ * recently come first, then the rest in curated-default order.
+ */
+export function autoFallbackSelectors(input: AutoFallbackInput): string[] {
+	const limit = input.limit ?? AUTO_FALLBACK_PROVIDER_LIMIT;
+	if (limit <= 0) return [];
+	const availableKeys = new Set(input.available.map(model => `${model.provider}/${model.id}`));
+	const picked = new Map<string, { selector: string; rank: number }>();
+	const eligible = (provider: string): boolean =>
+		!picked.has(provider) && !input.excludeProviders.has(provider) && input.hasCredentials(provider);
+
+	const usageOrder = input.usageOrder ?? [];
+	usageOrder.forEach((key, index) => {
+		const provider = selectorProvider(key);
+		if (!provider || !availableKeys.has(key) || !eligible(provider)) return;
+		picked.set(provider, { selector: key, rank: index });
+	});
+	Object.entries(defaultModelPerProvider).forEach(([provider, modelId], index) => {
+		const key = `${provider}/${modelId}`;
+		if (!availableKeys.has(key) || !eligible(provider)) return;
+		picked.set(provider, { selector: key, rank: usageOrder.length + index });
+	});
+
+	return [...picked.values()]
+		.sort((left, right) => left.rank - right.rank)
+		.slice(0, limit)
+		.map(entry => entry.selector);
+}

package/src/session/fallback-chain-controller.ts

@@ -7,6 +7,11 @@ export interface ConfiguredFallbackChain {
 	origin: string;
 	identity?: string;
 	explicitHead: boolean;
+	/**
+	 * Index of the first entry appended at runtime after the configured intent
+	 * (`fallback.models`, then automatic picks). Absent when nothing was appended.
+	 */
+	appendedFrom?: number;
 }
 
 export interface FallbackFailure {