From 45988d4cbdd777aaaf32270a52f78c38da7d9c2b Mon Sep 17 00:00:00 2001
From: Serhii Vecherenko <SDSLeon999@gmail.com>
Date: Sat, 23 May 2026 18:34:17 -0700
Subject: [PATCH] feat(agent): improve auth and logout command support

- Map Codex and Cursor "not logged in" status to "missing" to trigger sign-in.
- Standardize agent logout command building across Claude, Codex, and Cursor.
- Handle Claude upstream API failures that report as success-subtypes.
- Introduce heuristic to detect agent authentication errors in the renderer.
- Prevent focus blinks on composer when clicking the auth dock action button.
- Ignore view transition InvalidStateError exceptions in global error handler.
---
 .../thread/ThreadAuthRequiredDock.tsx         | 40 ++++++++++++++++---
 .../thread/ThreadComposerSection.tsx          | 14 +++++--
 .../thread/threadErrorState.test.ts           | 24 ++++++++++-
 .../components/thread/threadErrorState.ts     | 24 +++++++++++
 src/renderer/rendererGlobalErrors.test.ts     | 16 ++++++++
 src/renderer/rendererGlobalErrors.ts          | 16 +++++++-
 src/supervisor/agents/base/index.ts           | 16 ++++++++
 src/supervisor/agents/claude/claude.test.ts   | 12 ++++++
 src/supervisor/agents/claude/index.ts         |  2 +
 src/supervisor/agents/claude/probe.ts         | 29 +++++++++++---
 .../agents/claude/sdkCanonicalMapping.test.ts | 29 ++++++++++++++
 .../agents/claude/sdkCanonicalMapping.ts      | 28 ++++++++++++-
 src/supervisor/agents/claude/sdkSession.ts    | 15 ++++++-
 src/supervisor/agents/codex/codex.test.ts     | 20 ++++++++++
 src/supervisor/agents/codex/detection.ts      | 25 ++++++++++--
 src/supervisor/agents/codex/index.ts          |  2 +
 src/supervisor/agents/cursor/cursor.test.ts   |  7 ++++
 src/supervisor/agents/cursor/detection.ts     |  2 +-
 src/supervisor/agents/cursor/index.ts         | 11 +----
 19 files changed, 300 insertions(+), 32 deletions(-)

diff --git a/src/renderer/components/thread/ThreadAuthRequiredDock.tsx b/src/renderer/components/thread/ThreadAuthRequiredDock.tsx
index f3cb2bd3..0ac9aa5f 100644
--- a/src/renderer/components/thread/ThreadAuthRequiredDock.tsx
+++ b/src/renderer/components/thread/ThreadAuthRequiredDock.tsx
@@ -22,6 +22,17 @@ async function refreshAgentStatus(status: AgentStatus): Promise<void> {
   });
 }
 
+/**
+ * Keep focus on whatever the user had focused before they mouse-clicked the
+ * dock's action button. Without this, clicking the button takes focus, the
+ * `isDisabled` swap during the in-flight action then releases focus, and
+ * react-aria restores focus to the composer for one frame before the dock
+ * finally unmounts — producing a visible border blink on the composer.
+ */
+function preventFocusSteal(event: React.MouseEvent<HTMLElement>): void {
+  event.preventDefault();
+}
+
 export function ThreadAuthRequiredDock(props: { agentStatus: AgentStatus; project?: Project }) {
   const { agentStatus, project } = props;
   const [pendingAction, setPendingAction] = useState<"login" | "refresh" | undefined>();
@@ -60,12 +71,28 @@ export function ThreadAuthRequiredDock(props: { agentStatus: AgentStatus; projec
     }
 
     if (agentStatus.loginCommand) {
-      runAgentLoginCommand({
+      setPendingAction("login");
+      const opened = runAgentLoginCommand({
         label: agentStatus.label,
         command: agentStatus.loginCommand,
         ...(terminalAuthMethod?.env ? { env: terminalAuthMethod.env } : {}),
         ...(project ? { project } : {}),
+        onCommandComplete: (exitCode) => {
+          void refreshAgentStatus(agentStatus)
+            .then(() => {
+              if (exitCode === 0) toast.success(`${agentStatus.label} authenticated.`);
+            })
+            .catch((error: unknown) => {
+              toast.danger(
+                error instanceof Error
+                  ? error.message
+                  : `Unable to refresh ${agentStatus.label} status.`,
+              );
+            })
+            .finally(() => setPendingAction(undefined));
+        },
       });
+      if (!opened) setPendingAction(undefined);
     }
   }
 
@@ -94,10 +121,11 @@ export function ThreadAuthRequiredDock(props: { agentStatus: AgentStatus; projec
             {hasDirectLogin ? (
               <Button
                 size="sm"
-                variant="secondary"
-                className="h-6 min-w-0 px-2 text-xs"
+                variant="ghost"
+                className="h-6 min-w-0 px-2 text-xs text-foreground"
                 isDisabled={pendingAction !== undefined}
                 isPending={pendingAction === "login"}
+                onMouseDown={preventFocusSteal}
                 onPress={() => void handleLogin()}
               >
                 <LogIn className="size-3.5" />
@@ -106,8 +134,9 @@ export function ThreadAuthRequiredDock(props: { agentStatus: AgentStatus; projec
             ) : (
               <Button
                 size="sm"
-                variant="secondary"
-                className="h-6 min-w-0 px-2 text-xs"
+                variant="ghost"
+                className="h-6 min-w-0 px-2 text-xs text-foreground"
+                onMouseDown={preventFocusSteal}
                 onPress={openSettings}
               >
                 <Settings className="size-3.5" />
@@ -122,6 +151,7 @@ export function ThreadAuthRequiredDock(props: { agentStatus: AgentStatus; projec
               className="h-6 w-6 min-w-0 text-muted"
               isDisabled={pendingAction !== undefined}
               isPending={pendingAction === "refresh"}
+              onMouseDown={preventFocusSteal}
               onPress={() => void handleRefresh()}
             >
               <RefreshCw className="size-3.5" />
diff --git a/src/renderer/components/thread/ThreadComposerSection.tsx b/src/renderer/components/thread/ThreadComposerSection.tsx
index 731ce005..a3793cc3 100644
--- a/src/renderer/components/thread/ThreadComposerSection.tsx
+++ b/src/renderer/components/thread/ThreadComposerSection.tsx
@@ -52,7 +52,7 @@ import {
   resolveLocalSlashCommandAction,
 } from "./threadSlashCommands";
 import { handleComposerControlShortcut } from "./threadComposerShortcuts";
-import type { ThreadErrorDockState } from "./threadErrorState";
+import { isAuthErrorMessage, type ThreadErrorDockState } from "./threadErrorState";
 import type { ThreadGoalDockState } from "./threadGoalState";
 import type { ThreadTodoDockState } from "./threadTodoState";
 import type { TerminalPaneHandle } from "./TerminalPane";
@@ -350,7 +350,14 @@ function ThreadComposerSectionInner(props: ThreadComposerSectionProps & { thread
   );
   const filteredCommands = filterSlashCommands(availableCommands, slashQuery);
   const showCommandPanel = filteredCommands.length > 0;
-  const authRequired = agentStatus?.authState === "missing";
+  // A stale runtime auth error (e.g. a 401 from before the user signed in)
+  // must not keep the auth dock visible once detection confirms the agent is
+  // authenticated again — otherwise the dock sticks until the user sends a
+  // new message and the error item scrolls off `selectThreadLatestErrorItem`.
+  const isAgentAuthenticated = agentStatus?.authState === "authenticated";
+  const hasRuntimeAuthError =
+    !isAgentAuthenticated && errorDockState !== null && isAuthErrorMessage(errorDockState.message);
+  const authRequired = agentStatus?.authState === "missing" || hasRuntimeAuthError;
   const isServerControlled =
     agentStatus?.capabilities.liveInputMode === "server" || !usesTerminalPresentation;
   const isTerminalInput = agentStatus?.capabilities.liveInputMode === "terminal";
@@ -381,7 +388,8 @@ function ThreadComposerSectionInner(props: ThreadComposerSectionProps & { thread
   const showTodoInComposer =
     !usesTerminalPresentation && todoDockState !== null && todoDockPlacement === "composer";
   const showGoalInComposer = !usesTerminalPresentation && goalDockState !== null;
-  const showErrorInComposer = !usesTerminalPresentation && errorDockState !== null;
+  const showErrorInComposer =
+    !usesTerminalPresentation && errorDockState !== null && !hasRuntimeAuthError;
   const hasActiveSubAgent = useAppStore(
     (s) => !usesTerminalPresentation && selectActiveSubAgentParentItemIds(s, thread.id).length > 0,
   );
diff --git a/src/renderer/components/thread/threadErrorState.test.ts b/src/renderer/components/thread/threadErrorState.test.ts
index 73cecbfb..543108dc 100644
--- a/src/renderer/components/thread/threadErrorState.test.ts
+++ b/src/renderer/components/thread/threadErrorState.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { RuntimeChatItem } from "@/renderer/state/slices/runtimeEventSlice";
-import { getThreadErrorDockStateForItem } from "./threadErrorState";
+import { getThreadErrorDockStateForItem, isAuthErrorMessage } from "./threadErrorState";
 
 function errorItem(message: string): RuntimeChatItem {
   return {
@@ -25,3 +25,25 @@ describe("threadErrorState", () => {
     });
   });
 });
+
+describe("isAuthErrorMessage", () => {
+  it.each([
+    "Failed to authenticate. API Error: 401 Invalid authentication credentials",
+    "Not logged in · Please run /login",
+    "Session expired. Please run /login to sign in again.",
+    "authentication_failed",
+    "API Error: 401",
+    "oauth_org_not_allowed",
+  ])("recognizes %q as an auth error", (msg) => {
+    expect(isAuthErrorMessage(msg)).toBe(true);
+  });
+
+  it.each([
+    "Network error: request failed",
+    "Rate limit exceeded",
+    "Internal server error",
+    "Claude turn failed.",
+  ])("does not flag %q as an auth error", (msg) => {
+    expect(isAuthErrorMessage(msg)).toBe(false);
+  });
+});
diff --git a/src/renderer/components/thread/threadErrorState.ts b/src/renderer/components/thread/threadErrorState.ts
index 05f6bf37..025e189b 100644
--- a/src/renderer/components/thread/threadErrorState.ts
+++ b/src/renderer/components/thread/threadErrorState.ts
@@ -48,3 +48,27 @@ export function getThreadErrorDockStateForItem(item: RuntimeChatItem): ThreadErr
 function isAbortOnlyErrorMessage(message: string): boolean {
   return /^(?:error:\s*)?(?:aborterror:\s*)?aborted\.?$/i.test(message.trim());
 }
+
+/**
+ * Heuristic for runtime errors that indicate the agent is unauthenticated.
+ * Covers strings emitted by the Claude binary ("Failed to authenticate. API
+ * Error: 401 …", "Please run /login", "Session expired …") and the
+ * Anthropic-SDK error codes the agent SDK surfaces ("authentication_failed",
+ * "oauth_org_not_allowed"). When this returns true, the composer should
+ * render the auth-required dock (with its Login button) rather than the
+ * generic error dock — `/login` itself isn't reachable through the SDK
+ * transport, so the user needs the terminal-login affordance.
+ */
+export function isAuthErrorMessage(message: string): boolean {
+  const m = message.toLowerCase();
+  return (
+    m.includes("failed to authenticate") ||
+    m.includes("invalid authentication credentials") ||
+    m.includes("api error: 401") ||
+    m.includes("please run /login") ||
+    m.includes("session expired") ||
+    m.includes("authentication_failed") ||
+    m.includes("oauth_org_not_allowed") ||
+    /\bnot logged in\b/.test(m)
+  );
+}
diff --git a/src/renderer/rendererGlobalErrors.test.ts b/src/renderer/rendererGlobalErrors.test.ts
index c25cf184..230c0e41 100644
--- a/src/renderer/rendererGlobalErrors.test.ts
+++ b/src/renderer/rendererGlobalErrors.test.ts
@@ -3,6 +3,7 @@ import {
   isIgnorableRejection,
   isIgnorableWindowError,
   isResizeObserverLoopError,
+  isViewTransitionInvalidStateError,
   isViewTransitionSkippedError,
 } from "./rendererGlobalErrors";
 
@@ -44,4 +45,19 @@ describe("rendererGlobalErrors", () => {
     expect(isIgnorableRejection(new Error("Transition was skipped"))).toBe(false);
     expect(isIgnorableRejection("Transition was skipped")).toBe(false);
   });
+
+  it("recognizes view-transition invalid-state InvalidStateError rejections", () => {
+    const err = new DOMException(
+      "Transition was aborted because of invalid state",
+      "InvalidStateError",
+    );
+    expect(isViewTransitionInvalidStateError(err)).toBe(true);
+    expect(isIgnorableRejection(err)).toBe(true);
+  });
+
+  it("does not ignore unrelated InvalidStateErrors", () => {
+    const err = new DOMException("IndexedDB transaction inactive", "InvalidStateError");
+    expect(isViewTransitionInvalidStateError(err)).toBe(false);
+    expect(isIgnorableRejection(err)).toBe(false);
+  });
 });
diff --git a/src/renderer/rendererGlobalErrors.ts b/src/renderer/rendererGlobalErrors.ts
index 8e0c941e..4e3e827e 100644
--- a/src/renderer/rendererGlobalErrors.ts
+++ b/src/renderer/rendererGlobalErrors.ts
@@ -41,10 +41,24 @@ export function isViewTransitionSkippedError(error: unknown): boolean {
   return message === "Transition was skipped";
 }
 
+// Sibling of `isViewTransitionSkippedError`: when the document state changes
+// in a way that invalidates the snapshot mid-transition (e.g. the Settings
+// overlay closes while a button-press transition is mid-flight, or the
+// terminal panel opens and reflows the tree), Chromium rejects the
+// ViewTransition promises with InvalidStateError "Transition was aborted
+// because of invalid state" instead of the AbortError variant. Same root
+// cause, same benign treatment — the DOM update still completed.
+export function isViewTransitionInvalidStateError(error: unknown): boolean {
+  const name = readErrorName(error);
+  if (name !== "InvalidStateError") return false;
+  const message = readErrorMessage(error);
+  return message === "Transition was aborted because of invalid state";
+}
+
 export function isIgnorableWindowError(event: ErrorEvent): boolean {
   return isResizeObserverLoopError(event.error) || isResizeObserverLoopError(event.message);
 }
 
 export function isIgnorableRejection(reason: unknown): boolean {
-  return isViewTransitionSkippedError(reason);
+  return isViewTransitionSkippedError(reason) || isViewTransitionInvalidStateError(reason);
 }
diff --git a/src/supervisor/agents/base/index.ts b/src/supervisor/agents/base/index.ts
index 52ce69e2..d61732e5 100644
--- a/src/supervisor/agents/base/index.ts
+++ b/src/supervisor/agents/base/index.ts
@@ -395,6 +395,22 @@ export function detectProbeLocation(ctx: AgentEnvContext | undefined): ProjectLo
   return { kind: "posix", path: homedir() };
 }
 
+/**
+ * Adapter helper for CLIs that expose logout as a shell subcommand
+ * (`claude auth logout`, `codex logout`, `cursor-agent logout`). Delegates
+ * to `buildAgentCommand` so posix, Windows, and WSL share the same shell
+ * wrapping the agent uses in production.
+ */
+export function buildAgentLogoutCommand(
+  binary: string,
+  args: string[],
+): (ctx?: AgentEnvContext) => Promise<CommandSpec> {
+  return async (ctx) => {
+    const location = detectProbeLocation(ctx);
+    return buildAgentCommand(location, binary, args, resolveAgentBinaryPath(location, binary));
+  };
+}
+
 async function resolveDetectedBinary(
   ctx: AgentEnvContext | undefined,
   binary: string,
diff --git a/src/supervisor/agents/claude/claude.test.ts b/src/supervisor/agents/claude/claude.test.ts
index be4a3577..7f476360 100644
--- a/src/supervisor/agents/claude/claude.test.ts
+++ b/src/supervisor/agents/claude/claude.test.ts
@@ -131,6 +131,18 @@ describe("createClaudeAdapter structured sessions", () => {
   });
 });
 
+describe("createClaudeAdapter buildAcpLogoutCommand", () => {
+  it("returns `claude auth logout` so the Settings logout button can drive it", async () => {
+    const adapter = createClaudeAdapter();
+    const command = await adapter.buildAcpLogoutCommand?.();
+    expect(command).toBeDefined();
+    // `buildAgentCommand` wraps the argv in a login shell (`sh -c "exec
+    // 'claude' 'auth' 'logout'"`) on posix and in `wsl.exe -d <distro> --` on
+    // WSL — assert on the substring so both platforms pass.
+    expect(command?.args.join(" ")).toContain("'claude' 'auth' 'logout'");
+  });
+});
+
 describe("parseClaudeAuthStatusJson", () => {
   it("extracts account metadata from Claude's auth-status JSON", () => {
     expect(
diff --git a/src/supervisor/agents/claude/index.ts b/src/supervisor/agents/claude/index.ts
index 45cf8e1c..4c1b06c6 100644
--- a/src/supervisor/agents/claude/index.ts
+++ b/src/supervisor/agents/claude/index.ts
@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import type { PromptSegment } from "@/shared/contracts";
 import {
   brailleSpinnerOscTitleHint,
+  buildAgentLogoutCommand,
   createKnownSessionRef,
   detectAgentInstall,
   iterm2ProgressOscHint,
@@ -87,6 +88,7 @@ export function createClaudeAdapter(): AgentAdapter {
       if (input.presentationMode !== "gui") return undefined;
       return ClaudeSdkSession.create(input);
     },
+    buildAcpLogoutCommand: buildAgentLogoutCommand("claude", ["auth", "logout"]),
     buildDirectInput(prompt, segments) {
       const attachmentCount = segments?.filter((s) => s.kind === "attachment").length ?? 0;
       const wait = attachmentCount > 0 ? 800 + (attachmentCount - 1) * 150 : 60;
diff --git a/src/supervisor/agents/claude/probe.ts b/src/supervisor/agents/claude/probe.ts
index 03d14c94..43f291c0 100644
--- a/src/supervisor/agents/claude/probe.ts
+++ b/src/supervisor/agents/claude/probe.ts
@@ -1,8 +1,19 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AgentCapability } from "@/shared/contracts";
+import type { AgentAuthMethod, AgentCapability } from "@/shared/contracts";
 import type { SDKUserMessage, SlashCommand } from "@anthropic-ai/claude-agent-sdk";
-import { readWslLoginShellCommandOutputAsync, type DetectProbeCtx } from "../base";
+import {
+  readWslLoginShellCommandOutputAsync,
+  type CapabilitiesProbeResult,
+  type DetectProbeCtx,
+} from "../base";
+
+const CLAUDE_TERMINAL_AUTH_METHOD: AgentAuthMethod = {
+  type: "terminal",
+  id: "claude-login",
+  name: "Claude login",
+  args: ["auth", "login"],
+};
 
 const MIN_CLAUDE_OPUS_47_CLI = [2, 1, 111] as const;
 const OPUS_47_MODEL_ID = "claude-opus-4-7";
@@ -198,7 +209,7 @@ async function probeClaudeSdkPartialWsl(
 
 export async function probeClaudeCapabilities(
   ctx: DetectProbeCtx,
-): Promise<Partial<AgentCapability> | undefined> {
+): Promise<CapabilitiesProbeResult | undefined> {
   if (!ctx.executablePath) return undefined;
 
   const timeoutMs = process.platform === "win32" ? 12_000 : 10_000;
@@ -209,6 +220,14 @@ export async function probeClaudeCapabilities(
 
   const versionPartial = claudeCapabilitiesFromCliVersion(ctx.version);
 
-  if (!sdkPartial && !versionPartial) return undefined;
-  return { ...(sdkPartial ?? {}), ...(versionPartial ?? {}) };
+  // Always advertise the terminal login + `claude auth logout` capabilities
+  // when the binary is installed — the Settings UI gates the Login/Logout
+  // controls on these fields, and the supervisor's logout dispatcher uses
+  // the adapter's `buildAcpLogoutCommand` to invoke `claude auth logout`.
+  return {
+    ...(sdkPartial ?? {}),
+    ...(versionPartial ?? {}),
+    authMethods: [CLAUDE_TERMINAL_AUTH_METHOD],
+    authLogoutSupported: true,
+  };
 }
diff --git a/src/supervisor/agents/claude/sdkCanonicalMapping.test.ts b/src/supervisor/agents/claude/sdkCanonicalMapping.test.ts
index 36c6b148..07aa18b6 100644
--- a/src/supervisor/agents/claude/sdkCanonicalMapping.test.ts
+++ b/src/supervisor/agents/claude/sdkCanonicalMapping.test.ts
@@ -1340,6 +1340,35 @@ describe("sdkCanonicalMapping — turn completion", () => {
       { type: "turn.completed", threadId: "thread-1", turnId: "turn-1", state: "completed" },
     ]);
   });
+
+  it("maps a success-subtype result with is_error to a failed turn and surfaces the API message", () => {
+    const state = createClaudeMapperState("thread-1");
+    startClaudeTurn(state, "turn-auth", "hi", undefined);
+
+    const events = mapClaudeSdkMessage(
+      {
+        type: "result",
+        subtype: "success",
+        is_error: true,
+        api_error_status: 401,
+        result: "Failed to authenticate. API Error: 401 Invalid authentication credentials",
+        session_id: "claude-session",
+      } as unknown as SDKMessage,
+      state,
+    );
+
+    expect(events).toContainEqual({
+      type: "error",
+      threadId: "thread-1",
+      message: "Failed to authenticate. API Error: 401 Invalid authentication credentials",
+    });
+    expect(events).toContainEqual({
+      type: "turn.completed",
+      threadId: "thread-1",
+      turnId: "turn-auth",
+      state: "failed",
+    });
+  });
 });
 
 describe("sdkCanonicalMapping — requests", () => {
diff --git a/src/supervisor/agents/claude/sdkCanonicalMapping.ts b/src/supervisor/agents/claude/sdkCanonicalMapping.ts
index 1f61dd4a..3528fac4 100644
--- a/src/supervisor/agents/claude/sdkCanonicalMapping.ts
+++ b/src/supervisor/agents/claude/sdkCanonicalMapping.ts
@@ -1071,6 +1071,30 @@ export function nonDiagnosticErrors(message: SDKMessage): string[] {
   );
 }
 
+/**
+ * claude.exe can emit subtype "success" while still surfacing an upstream API
+ * failure (e.g. 401/429) via `is_error: true` and `api_error_status`. Treat
+ * those as failures so the turn doesn't quietly resolve to idle.
+ */
+export function isApiErrorResult(message: SDKMessage): boolean {
+  if (message.type !== "result") return false;
+  const m = message as { is_error?: unknown; api_error_status?: unknown };
+  if (m.is_error === true) return true;
+  return typeof m.api_error_status === "number" && m.api_error_status >= 400;
+}
+
+export function extractResultErrorMessage(message: SDKMessage): string | undefined {
+  if (message.type !== "result") return undefined;
+  const fromErrors = nonDiagnosticErrors(message)[0];
+  if (fromErrors) return fromErrors;
+  const result = (message as { result?: unknown }).result;
+  if (typeof result === "string") {
+    const trimmed = result.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  return undefined;
+}
+
 function completeActiveGoalEvents(
   state: ClaudeMapperState,
   message: Extract<SDKMessage, { type: "result" }>,
@@ -1114,6 +1138,7 @@ function readClaudeResultUsage(
 }
 
 function mapResultState(message: Extract<SDKMessage, { type: "result" }>): TurnState {
+  if (isApiErrorResult(message)) return "failed";
   if (message.subtype === "success") return "completed";
   const filtered = nonDiagnosticErrors(message);
   // All errors were diagnostics — claude.exe was interrupted before producing
@@ -1435,8 +1460,7 @@ function mapClaudeSdkMessageInner(message: SDKMessage, state: ClaudeMapperState)
     const stateValue = mapResultState(message);
     events.push(...closeClaudeOpenItems(state));
     if (stateValue === "failed") {
-      const remaining = nonDiagnosticErrors(message);
-      const msg = remaining[0] ?? "Claude turn failed.";
+      const msg = extractResultErrorMessage(message) ?? "Claude turn failed.";
       events.push({ type: "error", threadId: state.threadId, message: msg });
     }
     events.push(...completeActiveGoalEvents(state, message));
diff --git a/src/supervisor/agents/claude/sdkSession.ts b/src/supervisor/agents/claude/sdkSession.ts
index aee0b797..6d091fac 100644
--- a/src/supervisor/agents/claude/sdkSession.ts
+++ b/src/supervisor/agents/claude/sdkSession.ts
@@ -52,6 +52,8 @@ import {
   buildClaudeQuestionAnswerEvents,
   closeClaudeOpenItems,
   createClaudeMapperState,
+  extractResultErrorMessage,
+  isApiErrorResult,
   mapClaudePermissionRequest,
   mapClaudeQuestionRequest,
   mapClaudeContextUsageResponse,
@@ -936,12 +938,21 @@ export class ClaudeSdkSession implements StructuredSessionHandle {
       const wasInterrupted = this.interruptInFlight || isInterruptedResult(message);
       this.interruptInFlight = false;
       const remaining = nonDiagnosticErrors(message);
+      // claude.exe surfaces upstream API failures (e.g. 401 auth, 429 rate
+      // limit) as subtype "success" with `is_error: true` / `api_error_status`
+      // set — the failure text lives in `result`, not `errors[]`. Treat those
+      // as failures regardless of subtype/interrupt state so the composer can
+      // show the error and stop the spinner.
+      const apiErrored = isApiErrorResult(message);
       // Only diagnostic lines remained → treat as interrupted, matching
       // `mapResultState`. claude.exe emits `[ede_diagnostic] ...` whenever a
       // turn ends before the assistant produced content, including external
       // (in-CLI) Esc interrupts where `interruptInFlight` is false.
-      const failed = message.subtype !== "success" && !wasInterrupted && remaining.length > 0;
-      const errorMessage = failed ? remaining[0] : undefined;
+      const failed =
+        apiErrored || (message.subtype !== "success" && !wasInterrupted && remaining.length > 0);
+      const errorMessage = failed
+        ? (extractResultErrorMessage(message) ?? "Claude turn failed.")
+        : undefined;
       this.emitUpdate({
         status: failed ? "error" : "idle",
         attention: failed ? "error" : "none",
diff --git a/src/supervisor/agents/codex/codex.test.ts b/src/supervisor/agents/codex/codex.test.ts
index 6eb68765..fad6297e 100644
--- a/src/supervisor/agents/codex/codex.test.ts
+++ b/src/supervisor/agents/codex/codex.test.ts
@@ -572,6 +572,26 @@ describe("parseCodexLoginStatusOutput", () => {
       },
     });
   });
+
+  // A confirmed "Not logged in" CLI message must report `missing`, not
+  // `unknown` — the composer's Sign-in dock gate is `authState === "missing"`,
+  // so reporting `unknown` here would hide the dock until the user hit a
+  // runtime 401.
+  it("reports missing when Codex explicitly says the user is not logged in", () => {
+    expect(parseCodexLoginStatusOutput("Not logged in")).toEqual({ authState: "missing" });
+  });
+});
+
+describe("createCodexAdapter buildAcpLogoutCommand", () => {
+  it("returns `codex logout` so the Settings logout button can drive it", async () => {
+    const adapter = createCodexAdapter();
+    const command = await adapter.buildAcpLogoutCommand?.();
+    expect(command).toBeDefined();
+    // `buildAgentCommand` wraps the argv in a login shell (`sh -c "exec
+    // 'codex' 'logout'"`) on posix and in `wsl.exe -d <distro> --` on WSL —
+    // assert on the substring so both platforms pass.
+    expect(command?.args.join(" ")).toContain("'codex' 'logout'");
+  });
 });
 
 describe("formatCodexPlanLabel", () => {
diff --git a/src/supervisor/agents/codex/detection.ts b/src/supervisor/agents/codex/detection.ts
index e9dd2b14..e1eaf088 100644
--- a/src/supervisor/agents/codex/detection.ts
+++ b/src/supervisor/agents/codex/detection.ts
@@ -1,4 +1,8 @@
-import { compactAgentProviderMetadata, type AgentCapability } from "@/shared/contracts";
+import {
+  compactAgentProviderMetadata,
+  type AgentAuthMethod,
+  type AgentCapability,
+} from "@/shared/contracts";
 import {
   configFileAuthProbe,
   readAgentCommandOutput,
@@ -232,7 +236,7 @@ export function parseCodexLoginStatusOutput(output: string): StatusProbeResult |
   }
 
   if (/not\s+logged\s+in|login required|sign in/i.test(trimmed)) {
-    return { authState: "unknown" };
+    return { authState: "missing" };
   }
 
   return undefined;
@@ -316,6 +320,13 @@ async function probeCodexStatus(ctx: Parameters<NonNullable<DetectionSpec["statu
   return result.ok ? { authState: "authenticated" as const } : { authState: "unknown" as const };
 }
 
+const CODEX_TERMINAL_AUTH_METHOD: AgentAuthMethod = {
+  type: "terminal",
+  id: "codex-login",
+  name: "Codex login",
+  args: ["login"],
+};
+
 export const codexDetectionSpec: DetectionSpec = {
   kind: "codex",
   label: "Codex",
@@ -342,6 +353,14 @@ export const codexDetectionSpec: DetectionSpec = {
           ? `codex:wsl:${ctx.location.distro}`
           : `codex:${ctx.location.kind}`,
     });
-    return probe ? probeResultToCapabilityPartial(probe) : undefined;
+    // Always advertise the terminal login + `codex logout` capabilities when
+    // the binary is installed — the Settings UI gates Login/Logout on these
+    // fields, and the supervisor's logout dispatcher uses the adapter's
+    // `buildAcpLogoutCommand` to invoke `codex logout`. Mirrors Claude.
+    return {
+      ...(probe ? probeResultToCapabilityPartial(probe) : {}),
+      authMethods: [CODEX_TERMINAL_AUTH_METHOD],
+      authLogoutSupported: true,
+    };
   },
 };
diff --git a/src/supervisor/agents/codex/index.ts b/src/supervisor/agents/codex/index.ts
index 6363c698..06c5807e 100644
--- a/src/supervisor/agents/codex/index.ts
+++ b/src/supervisor/agents/codex/index.ts
@@ -3,6 +3,7 @@ import type { OscNotification } from "@/shared/osc";
 import {
   batchWslCommandsAsync,
   brailleSpinnerOscTitleHint,
+  buildAgentLogoutCommand,
   createKnownSessionRef,
   createRecursiveDirWatcher,
   detectAgentInstall,
@@ -195,6 +196,7 @@ export function createCodexAdapter(): AgentAdapter {
       const wslExecPath = resolveAgentBinaryPath(input.projectLocation, "codex");
       return CodexStructuredSession.create(input, wslExecPath);
     },
+    buildAcpLogoutCommand: buildAgentLogoutCommand("codex", ["logout"]),
     buildDirectInput(prompt) {
       return [prompt, "@wait:160", "\r"];
     },
diff --git a/src/supervisor/agents/cursor/cursor.test.ts b/src/supervisor/agents/cursor/cursor.test.ts
index 7a780820..f2926034 100644
--- a/src/supervisor/agents/cursor/cursor.test.ts
+++ b/src/supervisor/agents/cursor/cursor.test.ts
@@ -562,6 +562,13 @@ describe("parseCursor account output", () => {
     });
   });
 
+  // Sibling of the Codex regression — a confirmed "not logged in" whoami must
+  // map to `missing` so the composer Sign-in dock can appear without waiting
+  // for a runtime auth error.
+  it("reports missing when whoami says the user is not logged in", () => {
+    expect(parseCursorWhoamiOutput("Not logged in")).toEqual({ authState: "missing" });
+  });
+
   it("extracts plan and email from about output", () => {
     expect(
       parseCursorAboutOutput(`About Cursor CLI
diff --git a/src/supervisor/agents/cursor/detection.ts b/src/supervisor/agents/cursor/detection.ts
index 4ef02843..cc5080eb 100644
--- a/src/supervisor/agents/cursor/detection.ts
+++ b/src/supervisor/agents/cursor/detection.ts
@@ -659,7 +659,7 @@ export function parseCursorWhoamiOutput(output: string): {
   }
 
   if (/not\s+logged\s+in|login required|sign in/i.test(text)) {
-    return { authState: "unknown" };
+    return { authState: "missing" };
   }
 
   return {};
diff --git a/src/supervisor/agents/cursor/index.ts b/src/supervisor/agents/cursor/index.ts
index a618d8ba..4d272dbd 100644
--- a/src/supervisor/agents/cursor/index.ts
+++ b/src/supervisor/agents/cursor/index.ts
@@ -2,6 +2,7 @@ import type { AgentCapability, PromptSegment } from "@/shared/contracts";
 import { createAcpStructuredSession } from "../acp";
 import {
   buildAgentCommand,
+  buildAgentLogoutCommand,
   createKnownSessionRef,
   detectAgentInstall,
   detectProbeLocation,
@@ -136,15 +137,7 @@ export function createCursorAdapter(): AgentAdapter {
         resolveAgentBinaryPath(location, "cursor-agent"),
       );
     },
-    async buildAcpLogoutCommand(ctx?: AgentEnvContext) {
-      const location = detectProbeLocation(ctx);
-      return buildAgentCommand(
-        location,
-        "cursor-agent",
-        ["logout"],
-        resolveAgentBinaryPath(location, "cursor-agent"),
-      );
-    },
+    buildAcpLogoutCommand: buildAgentLogoutCommand("cursor-agent", ["logout"]),
     buildDirectInput(prompt, _segments, _config, projectLocation) {
       // Cursor's TUI debounces fast incoming bytes as a paste burst. With
       // less than ~120ms between the text and Enter, the agent submits but