@gajae-code/coding-agent 0.7.7 → 0.7.9

package/src/modes/prompt-action-autocomplete.ts

@@ -29,6 +29,7 @@ interface PromptActionAutocompleteOptions {
 	copyCurrentLine: () => void;
 	copyPrompt: () => void;
 	pasteImage: () => void;
+	scrollTmuxToPreviousUserInput: () => void;
 	undo: (prefix: string) => void;
 	moveCursorToMessageEnd: () => void;
 	moveCursorToMessageStart: () => void;
@@ -378,6 +379,13 @@ export function createPromptActionAutocompleteProvider(
 			keywords: ["paste", "image", "clipboard", "screenshot", "attach", "vision"],
 			execute: options.pasteImage,
 		},
+		{
+			id: "tmux-previous-user-input",
+			label: "Scroll to previous user input",
+			description: "tmux copy-mode",
+			keywords: ["scroll", "tmux", "previous", "user", "input", "prompt", "history"],
+			execute: options.scrollTmuxToPreviousUserInput,
+		},
 		{
 			id: "undo",
 			label: "Undo",

package/src/modes/shared/agent-wire/deep-interview-gate.ts

@@ -11,7 +11,7 @@
  * the interactive select/editor UI) when an unattended controller + gate broker
  * are attached is wired with the transport in #321 and exercised by #323.
  */
-import type { RpcJsonSchema } from "../../rpc/rpc-types";
+import type { RpcJsonSchema, RpcWorkflowGateKind, RpcWorkflowStage } from "../../rpc/rpc-types";
 import type { OpenGateInput } from "./workflow-gate-broker";
 
 /** "Other (type your own)" sentinel, mirroring the interactive ask tool. */
@@ -26,6 +26,11 @@ export interface AskGateDeepInterviewState {
 	ambiguity: number;
 }
 
+export interface AskGateWorkflowGateMeta {
+	stage: RpcWorkflowStage;
+	kind: RpcWorkflowGateKind;
+}
+
 export interface AskGateQuestion {
 	id: string;
 	question: string;
@@ -37,6 +42,8 @@ export interface AskGateQuestion {
 	 * `stage_state`; when absent, the question text is regex-parsed as a fallback.
 	 */
 	deepInterview?: AskGateDeepInterviewState;
+	/** Override the emitted workflow gate address for non-deep-interview ask prompts. */
+	workflowGate?: AskGateWorkflowGateMeta;
 }
 
 export interface AskGateResult {
@@ -157,13 +164,13 @@ function structuredDeepInterviewState(meta: AskGateDeepInterviewState): Record<s
 	return state;
 }
 
-/** Build the `workflow_gate` open-input for one deep-interview question. */
+/** Build the `workflow_gate` open-input for one ask question. */
 export function questionToGate(question: AskGateQuestion): OpenGateInput {
 	const labels = question.options.map(o => o.label);
 	const schema = questionAnswerSchema(question, labels);
 	return {
-		stage: "deep-interview",
-		kind: "question",
+		stage: question.workflowGate?.stage ?? "deep-interview",
+		kind: question.workflowGate?.kind ?? "question",
 		schema,
 		options: question.options.map((o, i) => ({
 			value: o.label,

package/src/modes/tmux-scroll.ts

@@ -0,0 +1,92 @@
+import { resolveGjcTmuxCommand } from "../gjc-runtime/tmux-common";
+
+// tmux copy-mode pads lines to the pane width, so allow trailing spaces before
+// the line end while keeping the match scoped to the standalone `user` label.
+export const TMUX_PREVIOUS_USER_INPUT_SEARCH_PATTERN = "^ *user *$";
+
+type TmuxScrollFailureReason =
+	| "not_inside_tmux"
+	| "tmux_command_failed"
+	| "copy_mode_failed"
+	| "history_bottom_failed"
+	| "search_failed";
+
+export type TmuxScrollToPreviousUserInputResult =
+	| { ok: true }
+	| { ok: false; reason: TmuxScrollFailureReason; error?: string };
+
+interface TmuxSpawnResult {
+	exitCode: number | null;
+	stderr?: { toString(): string };
+}
+
+type TmuxSpawnSync = (command: string, args: string[], env: NodeJS.ProcessEnv) => TmuxSpawnResult;
+
+function defaultSpawnSync(command: string, args: string[], env: NodeJS.ProcessEnv): TmuxSpawnResult {
+	return Bun.spawnSync([command, ...args], {
+		env,
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+}
+
+function getErrorText(result: TmuxSpawnResult): string | undefined {
+	const text = result.stderr?.toString().trim();
+	return text ? text : undefined;
+}
+
+function runTmuxStep(
+	command: string,
+	args: string[],
+	env: NodeJS.ProcessEnv,
+	spawnSync: TmuxSpawnSync,
+	reason: TmuxScrollFailureReason,
+): TmuxScrollToPreviousUserInputResult {
+	try {
+		const result = spawnSync(command, args, env);
+		if (result.exitCode === 0) return { ok: true };
+		return { ok: false, reason, error: getErrorText(result) };
+	} catch (error) {
+		return { ok: false, reason, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+export function scrollTmuxToPreviousUserInput(
+	env: NodeJS.ProcessEnv = process.env,
+	spawnSync: TmuxSpawnSync = defaultSpawnSync,
+): TmuxScrollToPreviousUserInputResult {
+	if (!env.TMUX) return { ok: false, reason: "not_inside_tmux" };
+
+	let tmuxCommand: string;
+	try {
+		tmuxCommand = resolveGjcTmuxCommand(env);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "tmux_command_failed",
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+
+	const targetPane = env.TMUX_PANE?.trim();
+	const targetArgs = targetPane ? ["-t", targetPane] : [];
+	const copyModeResult = runTmuxStep(tmuxCommand, ["copy-mode", ...targetArgs], env, spawnSync, "copy_mode_failed");
+	if (!copyModeResult.ok) return copyModeResult;
+
+	const historyBottomResult = runTmuxStep(
+		tmuxCommand,
+		["send-keys", ...targetArgs, "-X", "history-bottom"],
+		env,
+		spawnSync,
+		"history_bottom_failed",
+	);
+	if (!historyBottomResult.ok) return historyBottomResult;
+
+	return runTmuxStep(
+		tmuxCommand,
+		["send-keys", ...targetArgs, "-X", "search-backward", TMUX_PREVIOUS_USER_INPUT_SEARCH_PATTERN],
+		env,
+		spawnSync,
+		"search_failed",
+	);
+}

package/src/modes/types.ts

@@ -290,7 +290,12 @@ export interface InteractiveModeContext {
 		dialogOptions?: ExtensionUIDialogOptions,
 	): Promise<string | undefined>;
 	hideHookSelector(): void;
-	showHookInput(title: string, placeholder?: string): Promise<string | undefined>;
+	showHookInput(
+		title: string,
+		placeholder?: string,
+		dialogOptions?: ExtensionUIDialogOptions,
+		inputOptions?: { readonly initialValue?: string },
+	): Promise<string | undefined>;
 	hideHookInput(): void;
 	showHookEditor(
 		title: string,

package/src/modes/utils/terminal-bell.ts

@@ -0,0 +1,48 @@
+import { settings } from "../../config/settings";
+
+export type TerminalBellEvent = "complete" | "approval" | "ask";
+
+const BEL = "\x07";
+
+function getBellSetting(key: Parameters<typeof settings.get>[0]): boolean {
+	try {
+		return Boolean(settings.get(key));
+	} catch {
+		// Some component-level tests exercise UI helpers before Settings.init().
+		// Terminal bells are purely best-effort, so an unavailable settings store
+		// must not make the UI path throw.
+		return false;
+	}
+}
+
+function enabledForEvent(event: TerminalBellEvent): boolean {
+	if (!getBellSetting("notifications.terminalBell")) return false;
+	switch (event) {
+		case "complete":
+			return getBellSetting("notifications.bellOnComplete");
+		case "approval":
+			return getBellSetting("notifications.bellOnApproval");
+		case "ask":
+			return getBellSetting("notifications.bellOnAsk");
+	}
+}
+
+export function ringTerminalBell(
+	event: TerminalBellEvent,
+	output: Pick<NodeJS.WriteStream, "write"> = process.stdout,
+): void {
+	if (!enabledForEvent(event)) return;
+	try {
+		output.write(BEL);
+	} catch {
+		// Best-effort local notification only.
+	}
+}
+
+export function classifyHookSelectorBellEvent(title: string): TerminalBellEvent {
+	const normalized = title.toLowerCase();
+	if (normalized.includes("approval") || normalized.includes("approve") || normalized.includes("plan ready")) {
+		return "approval";
+	}
+	return "ask";
+}

package/src/notifications/daemon-paths.ts

@@ -0,0 +1,22 @@
+import * as path from "node:path";
+
+export interface DaemonPaths {
+	dir: string;
+	lock: string;
+	state: string;
+	roots: string;
+	steal: string;
+	aliases: string;
+}
+
+export function daemonPaths(agentDir: string): DaemonPaths {
+	const dir = path.join(agentDir, "notifications");
+	return {
+		dir,
+		lock: path.join(dir, "telegram-daemon.lock"),
+		state: path.join(dir, "telegram-daemon.state.json"),
+		roots: path.join(dir, "telegram-daemon.roots.json"),
+		steal: path.join(dir, "telegram-daemon.steal"),
+		aliases: path.join(dir, "telegram-callback-aliases.json"),
+	};
+}

package/src/notifications/telegram-daemon-cli.ts

@@ -1,14 +1,23 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { Settings } from "../config/settings";
+import { YAML } from "bun";
+import type { Settings } from "../config/settings";
 import { getNotificationConfig, isGloballyConfigured } from "./config";
-import { daemonPaths, TelegramNotificationDaemon } from "./telegram-daemon";
-import { clearTelegramControlRequest, readTelegramControlRequest } from "./telegram-daemon-control";
+import { daemonPaths } from "./daemon-paths";
+import type { TelegramDaemonOptions } from "./telegram-daemon";
+
+type TelegramDaemonRunner = {
+	run(): Promise<void>;
+	requestStop(reason?: "reload" | "signal" | "stop"): void;
+};
+
+type TelegramDaemonConstructor = new (opts: TelegramDaemonOptions) => TelegramDaemonRunner;
 
 export interface RunDaemonInternalDeps {
-	SettingsImpl?: Pick<typeof Settings, "init">;
-	DaemonImpl?: typeof TelegramNotificationDaemon;
+	SettingsImpl?: { init: (options?: { agentDir?: string }) => Promise<Pick<Settings, "get" | "getAgentDir">> };
+	DaemonImpl?: TelegramDaemonConstructor;
 	processPid?: number;
+	pidAlive?: (pid: number) => boolean;
 }
 
 function argValue(argv: string[], name: string): string | undefined {
@@ -16,9 +25,105 @@ function argValue(argv: string[], name: string): string | undefined {
 	return i >= 0 ? argv[i + 1] : undefined;
 }
 
+function getByPath(obj: unknown, pathSegments: string[]): unknown {
+	let current = obj;
+	for (const segment of pathSegments) {
+		if (!current || typeof current !== "object" || Array.isArray(current)) return undefined;
+		current = (current as Record<string, unknown>)[segment];
+	}
+	return current;
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function asBoolean(value: unknown, fallback: boolean): boolean {
+	return typeof value === "boolean" ? value : fallback;
+}
+
+function asIdleTimeoutMs(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 60_000;
+}
+
+export function createLightweightDaemonSettings(input: {
+	agentDir: string;
+	rawConfig?: unknown;
+}): Pick<Settings, "get" | "getAgentDir"> {
+	const rawConfig = input.rawConfig && typeof input.rawConfig === "object" ? input.rawConfig : {};
+	return {
+		get(pathName: string): unknown {
+			const value = getByPath(rawConfig, pathName.split("."));
+			switch (pathName) {
+				case "notifications.enabled":
+					return asBoolean(value, false);
+				case "notifications.telegram.botToken":
+				case "notifications.telegram.chatId":
+				case "notifications.discord.botToken":
+				case "notifications.discord.channelId":
+				case "notifications.slack.botToken":
+				case "notifications.slack.channelId":
+					return asString(value);
+				case "notifications.redact":
+					return asBoolean(value, false);
+				case "notifications.verbosity":
+					return value === "verbose" ? "verbose" : "lean";
+				case "notifications.daemon.idleTimeoutMs":
+					return asIdleTimeoutMs(value);
+				default:
+					return undefined;
+			}
+		},
+		getAgentDir(): string {
+			return input.agentDir;
+		},
+	} as Pick<Settings, "get" | "getAgentDir">;
+}
+
+export async function loadLightweightDaemonSettings(agentDir: string): Promise<Pick<Settings, "get" | "getAgentDir">> {
+	const configPath = path.join(agentDir, "config.yml");
+	let rawConfig: unknown = {};
+	try {
+		rawConfig = YAML.parse(await fs.promises.readFile(configPath, "utf8"));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	return createLightweightDaemonSettings({ agentDir, rawConfig });
+}
+
+async function resolveDaemonSettings(
+	agentDir: string,
+	deps: RunDaemonInternalDeps,
+): Promise<Pick<Settings, "get" | "getAgentDir">> {
+	if (deps.SettingsImpl) return await deps.SettingsImpl.init({ agentDir });
+	return await loadLightweightDaemonSettings(agentDir);
+}
+
+export function ownerPidFromOwnerId(ownerId: string): number | undefined {
+	const match = /^(\d+)(?:-|$)/.exec(ownerId);
+	if (!match) return undefined;
+	const pid = Number(match[1]);
+	return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+function defaultPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function ownerProcessIsAlive(ownerId: string, deps: RunDaemonInternalDeps): boolean {
+	const ownerPid = ownerPidFromOwnerId(ownerId);
+	if (ownerPid === undefined) return true;
+	return (deps.pidAlive ?? defaultPidAlive)(ownerPid);
+}
+
 export async function runDaemonSmoke(opts: { agentDir?: string } = {}): Promise<void> {
 	const agentDir = opts.agentDir ?? fs.mkdtempSync(path.join(process.cwd(), ".telegram-daemon-smoke-"));
-	const settings = Settings.isolated({});
+	const settings = createLightweightDaemonSettings({ agentDir, rawConfig: {} });
 	const paths = daemonPaths(agentDir);
 	await fs.promises.mkdir(paths.dir, { recursive: true, mode: 0o700 });
 	const tempLock = `${paths.lock}.smoke.${process.pid}`;
@@ -34,12 +139,19 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 	if (smoke) return runDaemonSmoke({ agentDir });
 	const ownerId = argValue(argv, "--owner-id");
 	if (!ownerId) throw new Error("missing --owner-id");
-	const settings = await (deps.SettingsImpl ?? Settings).init(agentDir ? { agentDir } : {});
-	const cfg = getNotificationConfig(settings);
+	if (!ownerProcessIsAlive(ownerId, deps)) {
+		process.stderr.write(`GJC notify daemon exiting: owner process from --owner-id ${ownerId} is not alive.\n`);
+		return;
+	}
+	const resolvedAgentDir = agentDir ?? process.env.GJC_CODING_AGENT_DIR ?? path.join(process.cwd(), ".gjc", "agent");
+	const settings = await resolveDaemonSettings(resolvedAgentDir, deps);
+	const cfg = getNotificationConfig(settings as Settings);
 	if (!isGloballyConfigured(cfg) || !cfg.botToken || !cfg.chatId) return;
-	const Daemon = deps.DaemonImpl ?? TelegramNotificationDaemon;
+	const { clearTelegramControlRequest, readTelegramControlRequest } = await import("./telegram-daemon-control");
+	const Daemon: TelegramDaemonConstructor =
+		deps.DaemonImpl ?? (await import("./telegram-daemon")).TelegramNotificationDaemon;
 	const daemon = new Daemon({
-		settings,
+		settings: settings as Settings,
 		ownerId,
 		botToken: cfg.botToken,
 		chatId: cfg.chatId,
@@ -47,15 +159,15 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 		pid: deps.processPid ?? process.pid,
 		control: {
 			shouldStop: async owner => {
-				const req = await readTelegramControlRequest(settings);
+				const req = await readTelegramControlRequest(settings as Settings);
 				return Boolean(req && (!req.ownerId || req.ownerId === owner));
 			},
 			clear: async owner => {
-				const req = await readTelegramControlRequest(settings);
+				const req = await readTelegramControlRequest(settings as Settings);
 				// Only clear a request that targets this daemon owner, so an exiting
 				// daemon never erases a newer request meant for a different owner.
 				if (req && (!req.ownerId || req.ownerId === owner)) {
-					await clearTelegramControlRequest(settings, req.requestId);
+					await clearTelegramControlRequest(settings as Settings, req.requestId);
 				}
 			},
 		},

package/src/notifications/telegram-daemon.ts

@@ -10,6 +10,7 @@ import type { DaemonRuntimeInfo } from "../daemon/control-types";
 import { resolveGjcRuntimeSpawnInfo } from "../daemon/runtime";
 import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
 import { parseInThreadConfigCommand } from "./config-commands";
+import { daemonPaths } from "./daemon-paths";
 import { buildCompactChoiceGrid, TELEGRAM_PARSE_MODE } from "./html-format";
 import type {
 	SessionCloseTarget,
@@ -62,16 +63,6 @@ export interface DaemonState {
 	version: 1;
 	stoppedAt?: number;
 }
-
-export interface DaemonPaths {
-	dir: string;
-	lock: string;
-	state: string;
-	roots: string;
-	steal: string;
-	aliases: string;
-}
-
 export interface TelegramDaemonFs {
 	mkdir(path: string, opts?: fs.MakeDirectoryOptions): Promise<void>;
 	readFile(path: string, encoding: BufferEncoding): Promise<string>;
@@ -184,17 +175,7 @@ async function fetchWithRetry(
 	throw lastErr;
 }
 
-export function daemonPaths(agentDir: string): DaemonPaths {
-	const dir = path.join(agentDir, "notifications");
-	return {
-		dir,
-		lock: path.join(dir, "telegram-daemon.lock"),
-		state: path.join(dir, "telegram-daemon.state.json"),
-		roots: path.join(dir, "telegram-daemon.roots.json"),
-		steal: path.join(dir, "telegram-daemon.steal"),
-		aliases: path.join(dir, "telegram-callback-aliases.json"),
-	};
-}
+export { type DaemonPaths, daemonPaths } from "./daemon-paths";
 
 /**
  * Attach session-lifecycle control (create/close/resume) to the running daemon.
@@ -2005,6 +1986,10 @@ export class TelegramNotificationDaemon {
 					{ command: "verbose", description: "Mirror full tool output + reasoning in this thread" },
 					{ command: "lean", description: "Mirror assistant text + tool names only (default)" },
 					{ command: "redact", description: "Toggle redaction of streamed content: /redact <on|off>" },
+					{ command: "session_create", description: "Create a GJC session: path, worktree, or dir" },
+					{ command: "session_recent", description: "List recent GJC sessions" },
+					{ command: "session_close", description: "Close a GJC-managed session" },
+					{ command: "session_resume", description: "Resume or reattach a session" },
 				],
 			});
 		} catch {

package/src/prompts/system/system-prompt.md

@@ -82,6 +82,11 @@ Use for read-only plan critique. It approves only when execution can proceed wit
 - Do not load or inject user-home Anthropic model or provider instructions (`~/.anthropic-model`, `~/.openai-code`) into the model context.
 - Public commands, paths, examples, and workflow names must use `gjc` and `.gjc`.
 </runtime-state>
+<self-awareness>
+- When the user asks about GJC usage, how to use a GJC feature/command/workflow, or about the gajae-code system itself, do not answer from memory alone. First clone the canonical source repository into `/tmp` (e.g. `git clone --depth 1 https://github.com/Yeachan-Heo/gajae-code /tmp/gajae-code-<unique>`), then read and analyze the actual source there to ground your answer.
+- Reuse an existing fresh clone under `/tmp` instead of re-cloning when one is already present in the session.
+- Base usage and system answers on what the cloned source actually says; cite concrete files/paths from the clone rather than guessing.
+</self-awareness>
 </gjc-runtime>
 
 <communication>

package/src/sdk.ts

@@ -2007,7 +2007,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			.map(name => toolRegistry.get(name))
 			.filter((tool): tool is AgentTool => tool !== undefined)
 			// AgentSession tool wrapping is not installed until after Agent construction.
-			.map(tool => guardToolForUltragoalAsk(tool, () => sessionManager.getCwd()));
+			.map(tool =>
+				guardToolForUltragoalAsk(
+					tool,
+					() => sessionManager.getCwd(),
+					() => ({
+						activeSkillState: session?.getActiveSkillState(),
+						sessionId: sessionManager.getSessionId?.() ?? null,
+					}),
+				),
+			);
 
 		const openaiWebsocketSetting = settings.get("providers.openaiWebsockets") ?? "off";
 		const preferOpenAICodexWebsockets =

package/src/session/agent-session.ts

@@ -526,6 +526,15 @@ export interface SessionStats {
 type RetryFallbackChains = Record<string, string[]>;
 
 type RetryFallbackRevertPolicy = "never" | "cooldown-expiry";
+type RetryErrorClassification =
+	| "none"
+	| "overflow"
+	| "terminal"
+	| "usage_limit"
+	| "first_event_timeout"
+	| "transient"
+	| "local_unavailable"
+	| "unknown";
 
 interface RetryFallbackSelector {
 	raw: string;
@@ -563,6 +572,37 @@ function formatRetryFallbackBaseSelector(selector: RetryFallbackSelector): strin
 	return `${selector.provider}/${selector.id}`;
 }
 
+function isLocalModelEndpoint(model: Model | undefined): boolean {
+	if (!model) return false;
+	if (model.provider === "ollama" || model.provider === "lm-studio" || model.provider === "llama.cpp") {
+		return true;
+	}
+	try {
+		const hostname = new URL(model.baseUrl).hostname.toLowerCase();
+		if (
+			hostname === "localhost" ||
+			hostname === "0.0.0.0" ||
+			hostname === "::1" ||
+			hostname === "[::1]" ||
+			hostname.endsWith(".local")
+		) {
+			return true;
+		}
+		if (/^127\./.test(hostname) || /^10\./.test(hostname) || /^192\.168\./.test(hostname)) {
+			return true;
+		}
+		const private172 = /^172\.(\d{1,2})\./.exec(hostname);
+		if (private172) {
+			const secondOctet = Number(private172[1]);
+			return secondOctet >= 16 && secondOctet <= 31;
+		}
+	} catch {
+		// A malformed base URL is configuration, not availability. Keep it visible.
+		return false;
+	}
+	return false;
+}
+
 const IRC_REPLY_MAX_BYTES = 4096;
 
 /**
@@ -3880,7 +3920,16 @@ export class AgentSession {
 
 	#prepareToolForExecution<T extends AgentTool>(tool: T): T {
 		return this.#wrapToolForDeepInterviewMutationGuard(
-			this.#wrapToolForAcpPermission(guardToolForUltragoalAsk(tool, () => this.sessionManager.getCwd())),
+			this.#wrapToolForAcpPermission(
+				guardToolForUltragoalAsk(
+					tool,
+					() => this.sessionManager.getCwd(),
+					() => ({
+						activeSkillState: this.getActiveSkillState(),
+						sessionId: this.sessionManager.getSessionId(),
+					}),
+				),
+			),
 		);
 	}
 
@@ -8221,6 +8270,12 @@ export class AgentSession {
 	 */
 	#isRetryableError(message: AssistantMessage): boolean {
 		const classification = this.#classifyErrorForRetry(message);
+		if (classification === "local_unavailable") {
+			return this.#hasRetryFallbackCandidate({
+				currentSelector: this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined,
+				requireNonLocal: true,
+			});
+		}
 		return (
 			classification === "usage_limit" ||
 			classification === "transient" ||
@@ -8260,6 +8315,12 @@ export class AgentSession {
 		return /timed?\s*out while waiting for the first event|timeout waiting for first/i.test(errorMessage);
 	}
 
+	#isLocalProviderAvailabilityErrorMessage(errorMessage: string): boolean {
+		return /connection.?refused|econnrefused|timed?\s*out|timeout|fetch failed|network.?error|socket hang up|terminated|service.?unavailable|server.?error|internal.?error|503|model_not_found|model not found|no such model|unknown model|model .*not.*(found|available|loaded)|not ready|not.?ready|warming|loading|currently loading|try again|out of memory|\boom\b|memory guard|insufficient memory|not enough memory|failed to allocate|kv.?cache|malformed (stream|streaming|sse)|invalid (stream|streaming|sse)|stream envelope error|unexpected end of (json|input)|unterminated json|no error details in response/i.test(
+			errorMessage,
+		);
+	}
+
 	/**
 	 * Whether a first-event timeout on the error's provider should fail closed —
 	 * i.e. retry a bounded number of times (capped at retry.maxRetries) and then
@@ -8303,13 +8364,14 @@ export class AgentSession {
 	 * -> usage_limit (rotation) -> first_event_timeout (bounded retry) ->
 	 * transient (retry) -> unknown (retry).
 	 */
-	#classifyErrorForRetry(
-		message: AssistantMessage,
-	): "none" | "overflow" | "terminal" | "usage_limit" | "first_event_timeout" | "transient" | "unknown" {
+	#classifyErrorForRetry(message: AssistantMessage): RetryErrorClassification {
 		if (message.stopReason !== "error" || !message.errorMessage) return "none";
 		const contextWindow = this.model?.contextWindow ?? 0;
 		if (isContextOverflow(message, contextWindow)) return "overflow";
 		const err = message.errorMessage;
+		if (isLocalModelEndpoint(this.model) && this.#isLocalProviderAvailabilityErrorMessage(err)) {
+			return "local_unavailable";
+		}
 		// Stream-envelope errors are only transient in the pre-message_start
 		// variant; any other envelope failure is structural and must surface.
 		if (/anthropic stream envelope error:/i.test(err)) {
@@ -8444,6 +8506,20 @@ export class AgentSession {
 		return chain;
 	}
 
+	#hasRetryFallbackCandidate(options: { currentSelector: string | undefined; requireNonLocal?: boolean }): boolean {
+		if (!options.currentSelector) return false;
+		const role = this.#activeRetryFallback?.role ?? this.#resolveRetryFallbackRole(options.currentSelector);
+		if (!role) return false;
+		for (const selector of this.#findRetryFallbackCandidates(role, options.currentSelector)) {
+			if (this.#isRetryFallbackSelectorSuppressed(selector)) continue;
+			const candidate = this.#modelRegistry.find(selector.provider, selector.id);
+			if (!candidate) continue;
+			if (options.requireNonLocal && isLocalModelEndpoint(candidate)) continue;
+			return true;
+		}
+		return false;
+	}
+
 	#findRetryFallbackCandidates(role: string, currentSelector: string): RetryFallbackSelector[] {
 		const chain = this.#getRetryFallbackEffectiveChain(role);
 		if (chain.length <= 1) return [];
@@ -8497,7 +8573,7 @@ export class AgentSession {
 		});
 	}
 
-	async #tryRetryModelFallback(currentSelector: string): Promise<boolean> {
+	async #tryRetryModelFallback(currentSelector: string, options?: { requireNonLocal?: boolean }): Promise<boolean> {
 		const role = this.#activeRetryFallback?.role ?? this.#resolveRetryFallbackRole(currentSelector);
 		if (!role) return false;
 
@@ -8505,6 +8581,7 @@ export class AgentSession {
 			if (this.#isRetryFallbackSelectorSuppressed(selector)) continue;
 			const candidate = this.#modelRegistry.find(selector.provider, selector.id);
 			if (!candidate) continue;
+			if (options?.requireNonLocal && isLocalModelEndpoint(candidate)) continue;
 			const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
 			if (!apiKey) continue;
 			await this.#applyRetryFallbackCandidate(role, selector, currentSelector);
@@ -8615,6 +8692,7 @@ export class AgentSession {
 		if (!retrySettings.enabled) return false;
 		const retryClassification = this.#classifyErrorForRetry(message);
 		const unboundedClass = retryClassification === "transient" || retryClassification === "unknown";
+		const localUnavailable = retryClassification === "local_unavailable";
 
 		const generation = this.#promptGeneration;
 		this.#retryAttempt++;
@@ -8668,7 +8746,7 @@ export class AgentSession {
 		const currentSelector = this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined;
 		if (!switchedCredential && currentSelector) {
 			this.#noteRetryFallbackCooldown(currentSelector, parsedRetryAfterMs, errorMessage);
-			switchedModel = await this.#tryRetryModelFallback(currentSelector);
+			switchedModel = await this.#tryRetryModelFallback(currentSelector, { requireNonLocal: localUnavailable });
 			if (switchedModel) {
 				delayMs = 0;
 			} else if (parsedRetryAfterMs && parsedRetryAfterMs > delayMs) {