@gajae-code/coding-agent 0.18.7 → 0.18.9

package/src/modes/controllers/input-controller.ts

@@ -40,7 +40,9 @@ import { CommandPalette, type CommandPaletteAction, type CommandPaletteEntry } f
 import type { PasteTextContext } from "../components/custom-editor";
 import { QueuePaneComponent } from "../components/queue-pane";
 import { type QueuedMessageMoveDirection, QueuedMessageSelectorComponent } from "../components/queued-message-selector";
+import { focusedUiOwnsInterrupt } from "../utils/interrupt-ownership";
 import { matchesAppInterrupt } from "../utils/keybinding-matchers";
+import { createUnforwardedOptionChordWarner } from "../utils/macos-option-forwarding";
 
 const QUEUE_SELECTOR_NAVIGATION_ACTIONS = [
 	"tui.select.up",
@@ -95,6 +97,8 @@ function isExpandable(obj: unknown): obj is Expandable {
 export class InputController {
 	readonly actionRegistry: ActionRegistry<void>;
 	readonly #loadPastedImageBatch: typeof loadPastedImageBatch;
+	/** Session id with an automatic-title request pending, if any. */
+	#autoTitleInFlightSessionId: string | undefined;
 	#deferredSubmission?: {
 		text: string;
 		images?: InteractiveModeContext["pendingImages"];
@@ -546,15 +550,23 @@ export class InputController {
 			if (!isInterruptKey && !isClearKey) {
 				return undefined;
 			}
-			if (isClearKey && !isInterruptKey && this.ctx.hasActiveBtw() && this.ctx.handleBtwEscape()) {
+			// Listeners run before focused handleInput. Yield interrupt/back to the
+			// focused UI before touching BTW, maintenance, retries or workflow state.
+			// Clear (Ctrl+C by default) remains a global abort, even if the same
+			// key is also configured as interrupt.
+			if (isInterruptKey && !isClearKey && focusedUiOwnsInterrupt(this.ctx)) {
+				this.#resetEscapeGestures();
+				return undefined;
+			}
+			if (isClearKey && this.ctx.hasActiveBtw() && this.ctx.handleBtwEscape()) {
 				this.#resetEscapeGestures();
 				return { consume: true };
 			}
-			if (isClearKey && !isInterruptKey && this.ctx.hookSelector?.hasActiveInlineInput?.() === true) {
+			if (isClearKey && this.ctx.hookSelector?.hasActiveInlineInput?.() === true) {
 				this.#resetEscapeGestures();
 				return undefined;
 			}
-			if (isClearKey && !isInterruptKey) {
+			if (isClearKey) {
 				if (this.#handlePendingSteerInterrupt()) return { consume: true };
 				if (
 					this.#handleCancellableWorkEscape({
@@ -807,6 +819,12 @@ export class InputController {
 		this.ctx.editor.setActionKeys("app.message.queue", this.ctx.keybindings.getKeys("app.message.queue"));
 		this.ctx.editor.onQueue = () => this.#executeAction("app.message.queue");
 		this.#registerCommandPaletteAction("app.message.queue", queue, true);
+		this.ctx.editor.onUnforwardedOptionChord ??= createUnforwardedOptionChordWarner({
+			platform: process.platform,
+			terminalProgram: Bun.env.TERM_PROGRAM,
+			formatKeyHint: key => this.ctx.keybindings.formatKeyHint(key),
+			showWarning: message => this.ctx.showWarning(message),
+		});
 
 		this.ctx.editor.onViewportPageScroll = direction => this.ctx.ui.scrollViewportPages(direction);
 		this.ctx.editor.onViewportFollowLive = () => {
@@ -1163,6 +1181,7 @@ export class InputController {
 				return;
 			}
 			this.ctx.queueCompactionMessage(text, "steer", composer);
+			this.#titleQueuedCompactionText(text);
 			return;
 		}
 
@@ -1172,6 +1191,9 @@ export class InputController {
 		// This handles extension commands (execute immediately), prompt template expansion, and queueing
 		if (this.ctx.session.isStreaming) {
 			invalidateSessionTitleGeneration(this.ctx.sessionManager);
+			// A turn started by a skill command has no user message yet, so the
+			// first typed message can arrive here instead of the idle path.
+			this.maybeGenerateSessionTitle(text);
 			if (this.#canModifyComposer(composer)) {
 				this.ctx.editor.addToHistory(text);
 				this.ctx.editor.setText("");
@@ -1200,32 +1222,7 @@ export class InputController {
 		// First, move any pending bash components to chat
 		this.ctx.flushPendingBashComponents();
 
-		// Generate session title on first message
-		const hasUserMessages = this.ctx.session.messages.some((m: AgentMessage) => m.role === "user");
-		if (!hasUserMessages && !this.ctx.sessionManager.getSessionName() && !$pickenv("GJC_NO_TITLE", "PI_NO_TITLE")) {
-			const registry = this.ctx.session.modelRegistry;
-			generateSessionTitle(
-				text,
-				registry,
-				this.ctx.settings,
-				this.ctx.session.credentialSessionId,
-				this.ctx.session.model,
-				provider => this.ctx.session.agent.metadataForProvider(provider),
-			)
-				.then(async title => {
-					if (title) {
-						const applied = await this.ctx.sessionManager.setSessionName(title, "auto");
-						if (applied) {
-							setSessionTerminalTitle(
-								this.ctx.sessionManager.getSessionName()!,
-								this.ctx.sessionManager.getCwd(),
-							);
-							this.ctx.updateEditorBorderColor();
-						}
-					}
-				})
-				.catch(() => {});
-		}
+		this.maybeGenerateSessionTitle(text);
 
 		if (this.ctx.onInputCallback) {
 			// Include any pending images from clipboard paste
@@ -1303,7 +1300,7 @@ export class InputController {
 		});
 
 		// Stop the TUI (restore terminal to normal mode)
-		this.ctx.ui.stop();
+		this.ctx.ui.suspend();
 
 		// Send SIGTSTP to process group (pid=0 means all processes in group)
 		process.kill(0, "SIGTSTP");
@@ -1628,6 +1625,51 @@ export class InputController {
 		return this.ctx.settings.get("busyPromptMode") === "steer" ? "steer" : "followUp";
 	}
 
+	/**
+	 * Generate the automatic session title from the first user message. Called
+	 * from the editor submit and queue-shortcut paths (idle and streaming) and
+	 * from interactive startup messages; it is a no-op once the session has a
+	 * user message, a name, or a title request already in flight. The result is
+	 * bound to the session that requested it: a completion that lands after the
+	 * session was replaced (New Session, switch, resume) is discarded.
+	 */
+	maybeGenerateSessionTitle(text: string): void {
+		if (this.ctx.sessionManager.getSessionName()) return;
+		const sessionId = this.ctx.sessionManager.getSessionId();
+		if (this.#autoTitleInFlightSessionId === sessionId) return;
+		if ($pickenv("GJC_NO_TITLE", "PI_NO_TITLE")) return;
+		if (this.ctx.session.messages.some((m: AgentMessage) => m.role === "user")) return;
+		// Keep locally intercepted command arguments away from the title model.
+		if (this.ctx.session.isLocallyHandledSlashCommand(text)) return;
+		this.#autoTitleInFlightSessionId = sessionId;
+		generateSessionTitle(
+			text,
+			this.ctx.session.modelRegistry,
+			this.ctx.settings,
+			this.ctx.session.credentialSessionId,
+			this.ctx.session.model,
+			provider => this.ctx.session.agent.metadataForProvider(provider),
+		)
+			.then(async title => {
+				if (!title || this.ctx.sessionManager.getSessionId() !== sessionId) return;
+				const applied = await this.ctx.sessionManager.setSessionName(title, "auto");
+				if (applied) {
+					setSessionTerminalTitle(this.ctx.sessionManager.getSessionName()!, this.ctx.sessionManager.getCwd());
+					this.ctx.updateEditorBorderColor();
+				}
+			})
+			.catch(() => {})
+			.finally(() => {
+				if (this.#autoTitleInFlightSessionId === sessionId) this.#autoTitleInFlightSessionId = undefined;
+			});
+	}
+
+	/** Title text accepted into the compaction queue; skill commands replay through the skill path and are not titled. */
+	#titleQueuedCompactionText(text: string): void {
+		if (parseSkillInvocations(text, this.ctx.skillCommands ?? new Map()).length > 0) return;
+		this.maybeGenerateSessionTitle(text);
+	}
+
 	/**
 	 * Dispatch skill slash invocation(s) (`/skill:<name>`) through custom messages
 	 * using the supplied `streamingBehavior`. Returns true if the text contains a
@@ -1736,6 +1778,7 @@ export class InputController {
 				return;
 			}
 			this.ctx.queueCompactionMessage(text, "followUp");
+			this.#titleQueuedCompactionText(text);
 			return;
 		}
 
@@ -1750,6 +1793,7 @@ export class InputController {
 					followUpQueuePolicy: "sequential",
 				}),
 			);
+			this.maybeGenerateSessionTitle(text);
 			this.ctx.updatePendingMessagesDisplay();
 			this.ctx.ui.requestRender();
 			return;
@@ -1761,6 +1805,7 @@ export class InputController {
 			return;
 		}
 
+		this.maybeGenerateSessionTitle(text);
 		if (this.ctx.session.isStreaming) {
 			this.ctx.editor.addToHistory(text);
 			this.ctx.editor.setText("");
@@ -2517,7 +2562,7 @@ export class InputController {
 		let ttyHandle: fs.FileHandle | null = null;
 		try {
 			ttyHandle = await this.#openEditorTerminalHandle();
-			this.ctx.ui.stop();
+			this.ctx.ui.suspend();
 
 			const stdio: [number | "inherit", number | "inherit", number | "inherit"] = ttyHandle
 				? [ttyHandle.fd, ttyHandle.fd, ttyHandle.fd]

package/src/modes/controllers/runtime-mcp-command-controller.ts

@@ -19,6 +19,7 @@ import {
 	updateMCPServer,
 } from "../../runtime-mcp/config-writer";
 import { canonicalMCPResourceUri, type MCPOAuthConfig, MCPOAuthFlow } from "../../runtime-mcp/oauth-flow";
+import { nativeMcpSource } from "../../runtime-mcp/project-host-values";
 import {
 	clearSmitheryApiKey,
 	createSmitheryCliAuthSession,
@@ -44,7 +45,8 @@ import { parseCommandArgs } from "../shared";
 import { buildOAuthLoginAnchor, createOAuthUrlCopyLease } from "../shared/oauth-url-copy";
 import { theme } from "../theme/theme";
 import type { InteractiveModeContext } from "../types";
-import { matchesAppInterrupt } from "../utils/keybinding-matchers";
+import { focusedUiOwnsInterrupt } from "../utils/interrupt-ownership";
+import { matchesAppClear, matchesAppInterrupt } from "../utils/keybinding-matchers";
 import { groupBySource, parseRemoveArgs, readScopeFlag, showCommandMessage } from "./command-controller-shared";
 
 function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
@@ -645,7 +647,9 @@ export class MCPCommandController {
 		const cancellationUnsubscribe =
 			signal === undefined && typeof this.ctx.ui.addInputListener === "function"
 				? this.ctx.ui.addInputListener(data => {
-						if (data !== "\x03" && !matchesAppInterrupt(data)) return;
+						const isClearKey = data === "\x03" || matchesAppClear(data);
+						if (!isClearKey && !matchesAppInterrupt(data)) return;
+						if (!isClearKey && focusedUiOwnsInterrupt(this.ctx)) return;
 						userController.abort(new Error("OAuth flow cancelled"));
 						return { consume: true };
 					})
@@ -812,7 +816,7 @@ export class MCPCommandController {
 	 * Test connection to an MCP server.
 	 * Throws an error if connection fails (used for auto-detection).
 	 */
-	async #handleTestConnection(config: MCPServerConfig): Promise<void> {
+	async #handleTestConnection(config: MCPServerConfig, source?: SourceMeta): Promise<void> {
 		const testName = `test_${Date.now()}`;
 		const manager =
 			this.ctx.mcpManager ??
@@ -820,7 +824,7 @@ export class MCPCommandController {
 				sharedPoolIdleMs: this.ctx.settings.get("mcp.sharedPoolIdleMs"),
 			});
 		if (!this.ctx.mcpManager) manager.setAuthStorage(this.ctx.session.modelRegistry.authStorage);
-		await manager.withPreparedLease(testName, config, async () => {});
+		await manager.withPreparedLease(testName, config, async () => {}, { source });
 	}
 
 	async #findConfiguredServer(
@@ -877,7 +881,10 @@ export class MCPCommandController {
 		return next;
 	}
 
-	async #resolveOAuthEndpointsFromServer(config: MCPServerConfig): Promise<{
+	async #resolveOAuthEndpointsFromServer(
+		config: MCPServerConfig,
+		source?: SourceMeta,
+	): Promise<{
 		authorizationUrl: string;
 		tokenUrl: string;
 		clientId?: string;
@@ -885,11 +892,12 @@ export class MCPCommandController {
 		issuer?: string;
 		authorizationResponseIssSupported?: boolean;
 	}> {
-		// First test if server actually needs auth by connecting without OAuth
+		// First test if server actually needs auth by connecting without OAuth.
+		// A stored file keeps its source so project `!` and secret names stay gated.
 		let connectionSucceeded = false;
 		let connectionError: Error | undefined;
 		try {
-			await this.#handleTestConnection(this.#stripOAuthAuth(config));
+			await this.#handleTestConnection(this.#stripOAuthAuth(config), source);
 			connectionSucceeded = true;
 		} catch (error) {
 			connectionError = error as Error;
@@ -964,10 +972,10 @@ export class MCPCommandController {
 		}
 	}
 
-	async #syncManagerConnection(name: string, config: MCPServerConfig): Promise<void> {
+	async #syncManagerConnection(name: string, config: MCPServerConfig, source?: SourceMeta): Promise<void> {
 		if (!this.ctx.mcpManager) return;
 		if (this.ctx.mcpManager.getConnectionStatus(name) !== "disconnected") return;
-		await this.ctx.mcpManager.connectServers({ [name]: config }, {});
+		await this.ctx.mcpManager.connectServers({ [name]: config }, source ? { [name]: source } : {});
 		if (this.ctx.mcpManager.getConnectionStatus(name) === "connected") {
 			await this.ctx.session.refreshMCPTools(this.ctx.mcpManager.getTools());
 		}
@@ -995,9 +1003,10 @@ export class MCPCommandController {
 			// report as connected to avoid false-negative messaging.
 			if (!isConnected && !isConnecting && config.enabled !== false) {
 				try {
-					await this.#handleTestConnection(config);
+					const source = nativeMcpSource(scope, filePath);
+					await this.#handleTestConnection(config, source);
 					isConnected = true;
-					await this.#syncManagerConnection(name, config);
+					await this.#syncManagerConnection(name, config, source);
 				} catch {
 					// Keep disconnected status
 				}
@@ -1273,7 +1282,8 @@ export class MCPCommandController {
 				return;
 			}
 
-			const { config } = found;
+			const { config, scope, filePath } = found;
+			const source = nativeMcpSource(scope, filePath);
 			if (config.enabled === false) {
 				this.ctx.showError(`Server "${name}" is disabled. Run /mcp enable ${name} first.`);
 				return;
@@ -1310,10 +1320,10 @@ export class MCPCommandController {
 					}
 
 					lines.push("");
-					await this.#syncManagerConnection(name, config);
+					await this.#syncManagerConnection(name, config, source);
 					this.#showMessage(lines.join("\n"));
 				},
-				{ signal: abortController.signal },
+				{ signal: abortController.signal, source },
 			);
 		} catch (error) {
 			if (abortController.signal.aborted || (error instanceof Error && error.name === "AbortError")) {
@@ -1489,7 +1499,8 @@ export class MCPCommandController {
 			}
 
 			const baseConfig = this.#stripOAuthAuth(found.config);
-			const oauth = await this.#resolveOAuthEndpointsFromServer(baseConfig);
+			const source = nativeMcpSource(found.scope, found.filePath);
+			const oauth = await this.#resolveOAuthEndpointsFromServer(baseConfig, source);
 			const oauthClientSecret = found.config.oauth?.clientSecret ?? currentAuth?.clientSecret ?? "";
 
 			this.#showMessage(["", theme.fg("muted", `Reauthorizing "${name}"...`), ""].join("\n"));
@@ -1839,7 +1850,9 @@ export class MCPCommandController {
 		const oauthUrlCopyLease = createOAuthUrlCopyLease(this.ctx);
 		const abortController = new AbortController();
 		const interruptUnsubscribe = this.ctx.ui.addInputListener?.(data => {
-			if (data !== "\x03" && !matchesAppInterrupt(data)) return;
+			const isClearKey = data === "\x03" || matchesAppClear(data);
+			if (!isClearKey && !matchesAppInterrupt(data)) return;
+			if (!isClearKey && focusedUiOwnsInterrupt(this.ctx)) return;
 			abortController.abort(new Error("Smithery authorization cancelled."));
 			return { consume: true };
 		});

package/src/modes/controllers/selector-controller.ts

@@ -1612,7 +1612,7 @@ export class SelectorController {
 	}
 
 	async #handleCredentialImport(): Promise<void> {
-		this.ctx.showStatus("Scanning for existing Claude Code / Codex CLI credentials…");
+		this.ctx.showStatus("Scanning for existing Claude Code / Codex CLI / Kiro CLI credentials…");
 		const preview = await runExternalCredentialAutoImport({
 			authStorage: {
 				importCredentialIfAbsent: async () => ({
@@ -2494,17 +2494,20 @@ export class SelectorController {
 	 * default) then refresh the status surfaces. Rethrows so callers surface errors.
 	 */
 	async #applyModelProfile(profileName: string, persistDefault: boolean): Promise<void> {
+		this.ctx.session.markUserModelSelection();
 		const profileLabel = formatModelProfileDisplayLabel(
 			this.ctx.session.modelRegistry.getModelProfile(profileName) ?? { name: profileName },
 		);
-		await activateModelProfile(
-			{
-				session: this.ctx.session,
-				modelRegistry: this.ctx.session.modelRegistry,
-				settings: this.ctx.settings,
-				profileName,
-			},
-			{ persistDefault },
+		await this.ctx.session.withSdkControlMutation(() =>
+			activateModelProfile(
+				{
+					session: this.ctx.session,
+					modelRegistry: this.ctx.session.modelRegistry,
+					settings: this.ctx.settings,
+					profileName,
+				},
+				{ persistDefault },
+			),
 		);
 		this.ctx.statusLine.invalidate();
 		this.ctx.updateEditorBorderColor();
@@ -2779,6 +2782,7 @@ export class SelectorController {
 							await this.ctx.session.setModelTemporary(model, thinkingLevel, {
 								cause: "temporary-operation",
 								reason: "other",
+								onMutationStarted: () => this.ctx.session.markUserModelSelection(),
 							});
 							this.ctx.session.setDefaultFallbackRuntimeModel(
 								selectedSelector ?? formatModelSelectorValue(`${model.provider}/${model.id}`, thinkingLevel),
@@ -2816,6 +2820,7 @@ export class SelectorController {
 								selectedSelector && thinkingLevel && selectedSelector.endsWith(`:${thinkingLevel}`)
 									? selectedSelector.slice(0, -thinkingLevel.length - 1)
 									: selectedSelector;
+							if (includesRoleAgent && !includesDefault) this.ctx.session.markUserModelSelection();
 
 							const rollbackSnapshot = this.#captureDefaultAssignmentRollback();
 							let defaultMutationStarted = false;
@@ -2938,6 +2943,7 @@ export class SelectorController {
 							}
 							const value =
 								selectedSelector ?? formatModelSelectorValue(`${model.provider}/${model.id}`, thinkingLevel);
+							this.ctx.session.markUserModelSelection();
 							const assignments = new Map<GjcModelAssignmentTargetId, string>([[role, value]]);
 							const materializedProfile = materializeActiveModelProfileAssignments({
 								session: this.ctx.session,
@@ -3677,12 +3683,15 @@ export class SelectorController {
 			return;
 		}
 
-		await activateModelProfile({
-			session: this.ctx.session,
-			modelRegistry: this.ctx.session.modelRegistry,
-			settings: this.ctx.settings,
-			profileName: recommendedProfile.name,
-		});
+		this.ctx.session.markUserModelSelection();
+		await this.ctx.session.withSdkControlMutation(() =>
+			activateModelProfile({
+				session: this.ctx.session,
+				modelRegistry: this.ctx.session.modelRegistry,
+				settings: this.ctx.settings,
+				profileName: recommendedProfile.name,
+			}),
+		);
 	}
 
 	async #handleOAuthLogin(providerId: string, options?: OAuthSelectorOptions): Promise<void> {

package/src/modes/controllers/todo-command-controller.ts

@@ -409,7 +409,7 @@ export class TodoCommandController {
 			current.length > 0 ? phasesToMarkdown(current) : "# Todos\n- [ ] (replace this with your tasks)\n";
 
 		const fileHandle = await this.#openTtyHandle();
-		this.ctx.ui.stop();
+		this.ctx.ui.suspend();
 		try {
 			const stdio: [number | "inherit", number | "inherit", number | "inherit"] = fileHandle
 				? [fileHandle.fd, fileHandle.fd, fileHandle.fd]

package/src/modes/interactive-mode.ts

@@ -679,7 +679,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			startPendingSubmission: input => thisMode.startPendingSubmission(input),
 			addChatChild: child => addChatChild(thisMode, child),
 			requestRender: full => thisMode.ui.requestRender(full),
-			stopUi: () => thisMode.ui.stop(),
+			stopUi: () => thisMode.ui.suspend(),
 			startUi: () => thisMode.ui.start(),
 			showStatus: message => thisMode.showStatus(message),
 			showWarning: message => thisMode.showWarning(message),
@@ -2642,6 +2642,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#inputController.handleBackgroundCommand();
 	}
 
+	maybeGenerateSessionTitle(text: string): void {
+		this.#inputController.maybeGenerateSessionTitle(text);
+	}
+
 	handleImagePaste(): Promise<boolean> {
 		return this.#inputController.handleImagePaste();
 	}

package/src/modes/runtime-init.ts

@@ -11,6 +11,8 @@ import { ThinkingLevel } from "@gajae-code/agent-core";
 import { runExtensionCompact, runExtensionSetModel } from "../extensibility/extensions/compact-handler";
 import { getSessionSlashCommands } from "../extensibility/extensions/get-commands-handler";
 import type { ExtensionError, ExtensionUIContext } from "../extensibility/extensions/types";
+import { buildSessionProjectProgress } from "../progress/collect-project-progress";
+import { toProjectProgressSnapshot } from "../progress/progress-snapshot";
 import {
 	parseSyntheticModelId,
 	resolveSyntheticModelSelection,
@@ -201,6 +203,8 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 				return { bytes: new Uint8Array(await file.slice(start, end).arrayBuffer()), totalBytes: file.size };
 			},
 			getJobs: () => session.getAsyncJobSnapshot(),
+			getProjectProgress: async () =>
+				toProjectProgressSnapshot(await buildSessionProjectProgress(session, session.sessionManager)),
 			onJobFold: listener => session.onJobFold(listener),
 			onSessionEvent: listener => session.subscribe(listener),
 			setSdkPermissionProvider: provider => session.setSdkPermissionProvider(provider),

package/src/modes/utils/abort-message.ts

@@ -1,3 +1,5 @@
+import { getStreamIdleTimeoutRemediationMs } from "@gajae-code/ai/utils/idle-iterator";
+
 const STREAM_IDLE_TIMEOUT_PATTERN = /\bstream stalled while waiting for the next event\b/i;
 const GENERIC_ABORT_PATTERN = /^Request was aborted\.?$/i;
 const ABORT_DISPLAY_LABEL_PATTERN = /^(?:Operation aborted|Aborted after \d+ retry attempts?)(?::|$)/;
@@ -37,5 +39,5 @@ function normalizeAbortCause(errorMessage: string | undefined): string {
 function streamIdleTimeoutHint(cause: string): string {
 	if (!STREAM_IDLE_TIMEOUT_PATTERN.test(cause)) return "";
 	const separator = /[.!?]$/.test(cause) ? " " : ". ";
-	return `${separator}Hint: set PI_STREAM_IDLE_TIMEOUT_MS=300000 for slow reasoning/proxy streams, or PI_STREAM_IDLE_TIMEOUT_MS=0 to disable the watchdog.`;
+	return `${separator}Hint: set PI_STREAM_IDLE_TIMEOUT_MS=${getStreamIdleTimeoutRemediationMs()} for slow reasoning/proxy streams, or PI_STREAM_IDLE_TIMEOUT_MS=0 to disable the watchdog.`;
 }

package/src/modes/utils/interrupt-ownership.ts

@@ -0,0 +1,12 @@
+import type { InteractiveModeContext } from "../types";
+
+/** Ordinary focused UI owns interrupt/back before background work does. */
+export function focusedUiOwnsInterrupt(
+	ctx: Pick<InteractiveModeContext, "ui" | "editor" | "hookSelector" | "hookInput" | "hookEditor">,
+): boolean {
+	const focused = ctx.ui.getFocusedComponent?.();
+	if (!focused?.handleInput || focused === ctx.editor) return false;
+	// Non-inline hook prompts deliberately retain workflow-level interruption.
+	if (focused === ctx.hookSelector) return ctx.hookSelector.hasActiveInlineInput();
+	return focused !== ctx.hookInput && focused !== ctx.hookEditor;
+}

package/src/modes/utils/keybinding-matchers.ts

@@ -16,6 +16,10 @@ export function matchesAppInterrupt(data: string): boolean {
 	return matchesKey(data, "escape") || matchesKey(data, "esc");
 }
 
+export function matchesAppClear(data: string): boolean {
+	return getKeybindings().matches(data, "app.clear");
+}
+
 export function matchesSelectCancel(data: string): boolean {
 	return getKeybindings().matches(data, "tui.select.cancel");
 }

package/src/modes/utils/macos-option-forwarding.ts

@@ -0,0 +1,80 @@
+import type { KeyId } from "@gajae-code/tui";
+
+/**
+ * Characters macOS composes for Option+<letter> on the US/ABC layout when the
+ * terminal sends Option as text instead of Alt/Meta. Dead-key letters (e, i, n,
+ * u) compose nothing on their own and are absent.
+ */
+const MACOS_OPTION_COMPOSED_KEYS: ReadonlyMap<string, KeyId> = new Map<string, KeyId>([
+	["å", "alt+a"],
+	["∫", "alt+b"],
+	["ç", "alt+c"],
+	["∂", "alt+d"],
+	["ƒ", "alt+f"],
+	["©", "alt+g"],
+	["˙", "alt+h"],
+	["∆", "alt+j"],
+	["˚", "alt+k"],
+	["¬", "alt+l"],
+	["µ", "alt+m"],
+	["ø", "alt+o"],
+	["π", "alt+p"],
+	["œ", "alt+q"],
+	["®", "alt+r"],
+	["ß", "alt+s"],
+	["†", "alt+t"],
+	["√", "alt+v"],
+	["∑", "alt+w"],
+	["≈", "alt+x"],
+	["¥", "alt+y"],
+	["Ω", "alt+z"],
+]);
+
+/** The Option chord that composes `text` on the macOS US/ABC layout, if any. */
+export function macosOptionChordForComposedText(text: string): KeyId | undefined {
+	return MACOS_OPTION_COMPOSED_KEYS.get(text);
+}
+
+/** Terminal-specific instruction for sending Option as Alt/Meta, when the terminal is known. */
+export function macosOptionForwardingInstruction(terminalProgram: string | undefined): string | undefined {
+	const program = terminalProgram?.toLowerCase() ?? "";
+	if (program.includes("ghostty")) {
+		return "Ghostty: set macos-option-as-alt = true in its config, then reload the config or restart Ghostty.";
+	}
+	if (program === "apple_terminal") {
+		return "Terminal.app: enable Settings > Profiles > Keyboard > Use Option as Meta key.";
+	}
+	if (program === "iterm.app") {
+		return "iTerm2: set Settings > Profiles > Keys > Left and Right Option key to Esc+.";
+	}
+	return undefined;
+}
+
+export interface UnforwardedOptionChordWarnerOptions {
+	platform: NodeJS.Platform;
+	terminalProgram: string | undefined;
+	formatKeyHint: (key: KeyId) => string;
+	showWarning: (message: string) => void;
+}
+
+/**
+ * Builds the composer callback that explains, once, why a bound Option shortcut
+ * produced a character instead of firing. Returns undefined off macOS, where the
+ * composition table does not apply.
+ */
+export function createUnforwardedOptionChordWarner(
+	options: UnforwardedOptionChordWarnerOptions,
+): ((key: KeyId, text: string) => void) | undefined {
+	if (options.platform !== "darwin") return undefined;
+	let warned = false;
+	return (key, text) => {
+		if (warned) return;
+		warned = true;
+		const instruction =
+			macosOptionForwardingInstruction(options.terminalProgram) ??
+			"Configure the terminal to send Option as Alt/Meta (Esc+).";
+		options.showWarning(
+			`${options.formatKeyHint(key)} arrived as "${text}": the terminal is sending Option as text, so Option shortcuts cannot reach GJC. ${instruction} Or remap the shortcut to a Control chord in keybindings.json.`,
+		);
+	};
+}