From 2b7420e0293cd96bef2049fd995254f6fa32cebe Mon Sep 17 00:00:00 2001
From: Lexus2016 <lexus@cdzv.com>
Date: Wed, 2 Sep 2026 17:26:41 +0200
Subject: [PATCH] fix: stop a run on an auth failure instead of retrying it
 (#86)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Failed to authenticate: OAuth session expired and could not be refreshed"
stopped the work and said nothing about why. The visible symptom hid a
worse defect: an auth failure is not subtype:'success', so all three agent
loops AUTO-CONTINUED it. Each continue fails instantly with the identical
error, the whole MAX_AUTO_CONTINUES budget empties in seconds, and the run
ends as a generic 'agent_incomplete' that names nothing. A chain task then
retried twice more on top of that.

auth-errors.js is the third class of "the turn stopped and it was not the
agent's fault", alongside the two in rate-limit-utils.js — and the only one
that NEVER passes on its own. It refreshes nothing and cannot: the OAuth
tokens belong to the `claude` CLI's own credentials store, and the refresh
exchange needs client credentials this server has never held and must not
hold. Detecting it precisely and refusing to retry IS the fix.

- Detection is anchored to CLI/API-internal wording, disjoint from the
  rate-limit anchors, and a CLEAN SUCCESS is never classified as an auth
  failure — this repo's own issue, module and test contain the phrase, so
  an agent asked to read them reproduces it in a turn that succeeded.
- A bare "/login" or "unauthorized" is deliberately not matched: the studio
  serves its own /login route and answers {error:'unauthorized'}.
- The detector runs BEFORE the success break and before the auto-continue in
  all three loops (chat, SSH, taskWorker); the chain retry excludes it.
- The chat gets a real status line (--- fence, or the SPA stamps "Done" over
  the warning), the log gets a root-cause kind, the Kanban card gets a
  parseable auth_error:<kind> reason and a lock badge in 5 languages.

test/auth-errors.test.js: 66 assertions, including structural pins on the
ordering in server.js — a reorder there silently restores the bug.
---
 CLAUDE.md                |  47 +++++++++-
 auth-errors.js           | 159 ++++++++++++++++++++++++++++++++++
 package.json             |   4 +-
 public/kanban.html       |  24 ++++--
 server.js                |  62 +++++++++++++-
 test/auth-errors.test.js | 179 +++++++++++++++++++++++++++++++++++++++
 6 files changed, 463 insertions(+), 12 deletions(-)
 create mode 100644 auth-errors.js
 create mode 100644 test/auth-errors.test.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 5a83901..ffee2e3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ docker compose up -d
 docker compose logs -f claude-chat
 ```
 
-No linting and no build step configured. `npm test` chains 76 test files under `test/`: 19 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 57 plain-`node` suites in `test/` covering the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, the Kanban card's run-settings badges (`kanban-run-badges.test.js` pins the card's model/effort/engine chain against the one `startTask` actually resolves — the two live in different files and the card silently lies when they drift), the board-only `create_task` status (`task-backlog.test.js`), i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, the filesystem path guard (including the SVG sandbox header and the symlink rule on the `@`-mention search endpoints) plus the tunnel-blocks-terminal rule, WS session re-subscription, the SSH remote CLI-session import, the live engine pane / interactive-prompt watchdog, the cross-project global workspace aggregation, the rule that an SSH credential never leaves the server process, the Windows command-quoting oracle, the auth token lifecycle, the multi-agent dependency scheduler (waves, plan sanitising, and the rule that a failure warning must survive dep-context truncation), the SSH stream parser's three guards, the SSH run's termination guarantee (`ssh-termination.test.js` drives `ClaudeSSH.send()` through a fake ssh2 `Client` in `require.cache` and asserts `onDone` fires EXACTLY once on every ending — a missed one hangs the chat forever, a doubled one re-emits stderr) and the recovery contract of "Restart Session" (`session-restart.test.js` boots a real server against a fake `claude` that never exits, then pins that a restart ABORTS that turn and releases the session instead of refusing), the remote non-interactive shell environment (`remote-env.test.js`, which runs the generated prelude through real `bash -lc`: it must parse, print nothing on stdout, and never end on a false test — the caller chains `&& claude …` behind it), the remote CLI-list framing parser, the bot inbox's SQL seam (`bot-inbox.test.js` pins that `from_bot AS "from"` keeps the exact key `planInboxDelivery` reads — rename one without the other and every letter is silently retired as malformed), the one-time config/.env migration onto CCS_CONFIG_PATH and the mid-task clarification delivery contract on the subscription engine (`interrupt-delivery.test.js` — pins that the tmux injection block sits BEFORE the poll loop's completion `break`, that draining does not imply delivery, that a failed paste is re-queued and warns non-terminally, and that the task runner passes the same callbacks the chat path does), the CLAUDE.md / AGENTS.md discovery rules (`agents-md.test.js`, which also pins that AGENTS.md reaches the subprocess as `--append-system-prompt` and never as `--system-prompt`), and the remote file browser's three guard layers (`remote-files.test.js` runs the generated POSIX script through a real `/bin/sh` against a temp tree that contains symlinks OUT of the project; `remote-files-api.test.js` boots a server against a fake remote via `CCS_REMOTE_EXEC_HOOK` and drives `/api/files` the way the SPA does), the editor deep links (`editor-links.test.js` pins the two URI shapes literally — the browser link puts `vscode-remote` in the AUTHORITY and the CLI argument puts it in the SCHEME, and collapsing the two silently breaks one path; `editor-open-api.test.js` boots a real server with `PATH` pointed at an EMPTY directory, which both makes the `opened:'client'` fallback deterministic and guarantees the suite never launches an editor window on a developer's desktop), and the new-chat defaults chain (`chat-defaults.test.js` pins the pure resolver — the built-ins are asserted to be exactly what the SPA hardcoded before #58, and the choice lists to be exactly the toolbar's `data-v` sets and `MODEL_MAP`'s aliases; `chat-defaults-api.test.js` boots a real server in a throwaway `APP_DIR` and pins that a project writes back a SPARSE override object — a five-key snapshot passes every other assertion in that file and still breaks the feature). On the render side, `tables.test.mjs` also pins the ReDoS bound in renderMd step 3.4, `xss.test.mjs` runs 24 adversarial payloads end-to-end, and `forged-tokens.test.mjs` covers the case where user text contains the renderer's own placeholder control bytes, and `pane-font.test.mjs` pins the clamp DIRECTION of `_fitEnginePaneFont` (a wide engine pane may only shrink; a narrow split pane must be allowed to grow). `script-scope.test.mjs` pins which `<script>` block a helper is declared in — declarations hoist only within their own block, so a helper used by `loadSess()` must not live in the terminal block at the bottom of the file. Note the glob: a file under `test/render/` whose name does not end in `.test.mjs` is NEVER run — `_load.selftest.mjs` sat there unexecuted until it was renamed to `loader.test.mjs`. It runs serially and aborts on the first failing file. `.github/workflows/ci.yml` runs it on every push and PR to `main` (tmux installed, so the five tmux-dependent suites do not self-skip).
+No linting and no build step configured. `npm test` chains 77 test files under `test/`: 19 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 58 plain-`node` suites in `test/` covering the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, the Kanban card's run-settings badges (`kanban-run-badges.test.js` pins the card's model/effort/engine chain against the one `startTask` actually resolves — the two live in different files and the card silently lies when they drift), the board-only `create_task` status (`task-backlog.test.js`), i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, authentication-failure classification (`auth-errors.test.js`, which pins that the detector runs BEFORE the auto-continue in all three agent loops — a reorder there silently restores #86), the filesystem path guard (including the SVG sandbox header and the symlink rule on the `@`-mention search endpoints) plus the tunnel-blocks-terminal rule, WS session re-subscription, the SSH remote CLI-session import, the live engine pane / interactive-prompt watchdog, the cross-project global workspace aggregation, the rule that an SSH credential never leaves the server process, the Windows command-quoting oracle, the auth token lifecycle, the multi-agent dependency scheduler (waves, plan sanitising, and the rule that a failure warning must survive dep-context truncation), the SSH stream parser's three guards, the SSH run's termination guarantee (`ssh-termination.test.js` drives `ClaudeSSH.send()` through a fake ssh2 `Client` in `require.cache` and asserts `onDone` fires EXACTLY once on every ending — a missed one hangs the chat forever, a doubled one re-emits stderr) and the recovery contract of "Restart Session" (`session-restart.test.js` boots a real server against a fake `claude` that never exits, then pins that a restart ABORTS that turn and releases the session instead of refusing), the remote non-interactive shell environment (`remote-env.test.js`, which runs the generated prelude through real `bash -lc`: it must parse, print nothing on stdout, and never end on a false test — the caller chains `&& claude …` behind it), the remote CLI-list framing parser, the bot inbox's SQL seam (`bot-inbox.test.js` pins that `from_bot AS "from"` keeps the exact key `planInboxDelivery` reads — rename one without the other and every letter is silently retired as malformed), the one-time config/.env migration onto CCS_CONFIG_PATH and the mid-task clarification delivery contract on the subscription engine (`interrupt-delivery.test.js` — pins that the tmux injection block sits BEFORE the poll loop's completion `break`, that draining does not imply delivery, that a failed paste is re-queued and warns non-terminally, and that the task runner passes the same callbacks the chat path does), the CLAUDE.md / AGENTS.md discovery rules (`agents-md.test.js`, which also pins that AGENTS.md reaches the subprocess as `--append-system-prompt` and never as `--system-prompt`), and the remote file browser's three guard layers (`remote-files.test.js` runs the generated POSIX script through a real `/bin/sh` against a temp tree that contains symlinks OUT of the project; `remote-files-api.test.js` boots a server against a fake remote via `CCS_REMOTE_EXEC_HOOK` and drives `/api/files` the way the SPA does), the editor deep links (`editor-links.test.js` pins the two URI shapes literally — the browser link puts `vscode-remote` in the AUTHORITY and the CLI argument puts it in the SCHEME, and collapsing the two silently breaks one path; `editor-open-api.test.js` boots a real server with `PATH` pointed at an EMPTY directory, which both makes the `opened:'client'` fallback deterministic and guarantees the suite never launches an editor window on a developer's desktop), and the new-chat defaults chain (`chat-defaults.test.js` pins the pure resolver — the built-ins are asserted to be exactly what the SPA hardcoded before #58, and the choice lists to be exactly the toolbar's `data-v` sets and `MODEL_MAP`'s aliases; `chat-defaults-api.test.js` boots a real server in a throwaway `APP_DIR` and pins that a project writes back a SPARSE override object — a five-key snapshot passes every other assertion in that file and still breaks the feature). On the render side, `tables.test.mjs` also pins the ReDoS bound in renderMd step 3.4, `xss.test.mjs` runs 24 adversarial payloads end-to-end, and `forged-tokens.test.mjs` covers the case where user text contains the renderer's own placeholder control bytes, and `pane-font.test.mjs` pins the clamp DIRECTION of `_fitEnginePaneFont` (a wide engine pane may only shrink; a narrow split pane must be allowed to grow). `script-scope.test.mjs` pins which `<script>` block a helper is declared in — declarations hoist only within their own block, so a helper used by `loadSess()` must not live in the terminal block at the bottom of the file. Note the glob: a file under `test/render/` whose name does not end in `.test.mjs` is NEVER run — `_load.selftest.mjs` sat there unexecuted until it was renamed to `loader.test.mjs`. It runs serially and aborts on the first failing file. `.github/workflows/ci.yml` runs it on every push and PR to `main` (tmux installed, so the five tmux-dependent suites do not self-skip).
 
 ## Architecture
 
@@ -793,6 +793,49 @@ would be noise on every long chat. It is applied to the FIRST retry notice as we
 exhausted one — `hit the 50-turn limit (used 3)` contradicts itself, and a user who stops
 reading after the first retry never reaches the corrected sentence.
 
+### A stop that retrying cannot fix (issue #86, auth-errors.js)
+
+`"Failed to authenticate: OAuth session expired and could not be refreshed"` is the
+THIRD way a turn stops through no fault of the agent, and the retry machinery handled
+it worst. The two in `rate-limit-utils.js` both clear on their own — an overload after a
+backoff, a quota at `resetsAt`. An auth failure never does; a human must re-authenticate
+the CLI. But it is not `subtype:'success'`, so all three agent loops AUTO-CONTINUED it:
+each retry failed instantly with the identical error, the whole `MAX_AUTO_CONTINUES`
+budget emptied in seconds, and a chain task then retried twice more — ending as a generic
+`agent_incomplete` that named nothing. The report was "work stops and I am not told why";
+the burnt budget was the part nobody could see.
+
+- **This module refreshes nothing, and cannot.** The OAuth tokens belong to the `claude`
+  CLI's own credentials store; the refresh exchange needs a refresh token and client
+  credentials this server has never held and must not hold. "Refresh automatically" is
+  the CLI's job — when it reports that the refresh FAILED, the only correct move here is
+  to stop at once and name the action. Detecting it precisely and REFUSING to retry is
+  the fix, not a lesser version of one.
+- **The clean-success guard is what keeps it usable in this repo.** These are English
+  CLI strings, and issue #86, `auth-errors.js` and its own test all contain the phrase
+  "OAuth session expired" — an agent asked to read any of them reproduces it in a turn
+  that SUCCEEDED. `detectAuthError()` returns null for `subtype:'success'` with no error
+  flag, exactly as `shouldRetryOverload()` does. A turn that ended well was not blocked
+  by authentication, whatever its text says.
+- **Anchors are CLI/API-internal wording, never keywords.** A bare `/login` or
+  `unauthorized` is excluded deliberately: this project serves its own `/login` route and
+  answers `{error:'unauthorized'}` from its own middleware, so either would fire on a run
+  that merely reads `server.js`. The set is also DISJOINT from `rate-limit-utils.js` in
+  both directions — reading a quota banner as an auth stop would strand work that would
+  have resumed by itself.
+- **The ordering is the fix, so the test pins indices.** `auth-errors.test.js` compares
+  the position of the detector against the success break and `taskContinueCount++` in
+  `server.js`. Moving the block below the auto-continue restores the bug while every
+  behavioural assertion still passes — verified by mutation.
+- **The card has to say it.** `failure_reason` carries `auth_error:<kind> <line>`, mirroring
+  the parseable `usage_limit:<unix> …` prefix, and `kbAuthStop()` renders a 🔐 badge.
+  Without it an auth stop is indistinguishable from an ordinary failure on the board,
+  which is the "nothing tells me why" half of the report.
+- **`claudeCliStatus().authenticated` does NOT cover this, by construction.** It tests
+  that `~/.claude/.credentials.json` EXISTS — an expired token's file exists too. Telling
+  a live token from a dead one needs a network round trip, so the preflight flag stays a
+  cheap "is anything configured" check and the stop is caught reactively, mid-turn.
+
 ### Composer geometry and terminal-pane control
 
 Four reports that all reduce to "the UI moved or stopped listening". Pinned by
@@ -914,7 +957,7 @@ message replays the chat's history into a fresh Claude session rather than losin
 
 ## How to Verify Changes
 
-`npm test` runs 76 test files under `test/` (19 `test/render/*.test.mjs` + 57 `test/*.test.js`), and `.github/workflows/ci.yml` runs the same command on every push and PR to `main`. Nothing covers the live browser/WebSocket path, so also verify that manually:
+`npm test` runs 77 test files under `test/` (19 `test/render/*.test.mjs` + 58 `test/*.test.js`), and `.github/workflows/ci.yml` runs the same command on every push and PR to `main`. Nothing covers the live browser/WebSocket path, so also verify that manually:
 
 ```bash
 # 1. Start server
diff --git a/auth-errors.js b/auth-errors.js
new file mode 100644
index 0000000..013e397
--- /dev/null
+++ b/auth-errors.js
@@ -0,0 +1,159 @@
+// Authentication-failure classification (issue #86).
+//
+// This is the THIRD class of "the turn stopped and it was not the agent's fault",
+// alongside the two in rate-limit-utils.js, and it is the one the retry machinery
+// handles worst:
+//
+//   1. Transient overload (429/529) — passes on its own. Pause ~15-30s, retry.
+//   2. Account usage quota          — passes on its own. Re-queue at `resetsAt`.
+//   3. Auth failure (THIS module)   — NEVER passes on its own. A human must
+//                                     re-authenticate the `claude` CLI.
+//
+// The distinction matters because every agent loop ends a non-success turn by
+// AUTO-CONTINUING. A run whose credentials have expired fails instantly, gets
+// auto-continued, fails instantly again, and burns the whole MAX_AUTO_CONTINUES
+// budget in seconds before reporting a generic failure that names nothing. That
+// is what the user in #86 saw: work stops, the cause is not stated, and the only
+// hint is a raw CLI line buried in the transcript.
+//
+// WHAT THIS MODULE DOES NOT DO — and cannot. It does not refresh anything. The
+// OAuth tokens belong to the `claude` CLI (its own credentials store); the refresh
+// exchange needs a refresh token and client credentials this server has never held
+// and must not hold. So "the session should refresh automatically" is the CLI's job,
+// and when it reports that the refresh FAILED, the only correct move here is to stop
+// immediately and say exactly what the human has to do. Detecting it precisely and
+// refusing to retry IS the fix.
+//
+// ── False positives are the real design risk ──────────────────────────────────
+// These strings are English CLI/API text, and an agent discussing this very issue
+// will reproduce them verbatim — this repository's own issue #86, this file, and its
+// test all contain the phrase "OAuth session expired". So detection is anchored to
+// CLI/API-internal wording that does not occur in ordinary prose, and — exactly like
+// shouldRetryOverload() — a CLEAN SUCCESS is never classified as an auth failure.
+// A turn that ended well cannot have been blocked by authentication, whatever its
+// text says.
+
+// Anchors are deliberately DISJOINT from rate-limit-utils.js: a quota rejection is
+// not an auth failure and must keep its reset-based re-queue.
+//
+// Intentionally NOT matched: a bare "/login" or "unauthorized". This project serves
+// its own `/login` route and answers `{error:'unauthorized'}` from its own auth
+// middleware, so either one would fire on a run that merely reads server.js.
+const AUTH_ERROR_RE = new RegExp([
+  // The #86 report, verbatim: "OAuth session expired and could not be refreshed"
+  "oauth\\s+session\\s+expired",
+  "could\\s+not\\s+be\\s+refreshed",
+  "oauth\\s+token\\s+(?:has\\s+)?expired",
+  "refresh\\s+token\\s+(?:is\\s+)?(?:missing|expired|invalid|revoked)",
+  "failed\\s+to\\s+refresh\\s+(?:the\\s+)?(?:oauth\\s+)?(?:access\\s+)?token",
+  // Claude CLI / Anthropic API auth rejections
+  "invalid\\s+api\\s+key",
+  "authentication_error",
+  "authentication\\s+failed",
+  "invalid\\s+bearer\\s+token",
+  "please\\s+run\\s+`?/?claude\\s+login`?",
+  "please\\s+run\\s+`?/login`?",
+  "run\\s+`?claude\\s+login`?\\s+to\\s+(?:re-?)?authenticate",
+  "not\\s+logged\\s+in\\s+to\\s+claude",
+  "credentials\\s+(?:are\\s+)?(?:invalid|expired)",
+].join('|'), 'i');
+
+/**
+ * True when `text` carries the signature of an authentication failure.
+ * @param {string} text - assistant text, result payload, or error text
+ * @returns {boolean}
+ */
+function isAuthError(text = '') {
+  if (!text || typeof text !== 'string') return false;
+  return AUTH_ERROR_RE.test(text);
+}
+
+// Root-cause buckets, most specific first — the "display the root cause" ask in #86.
+// Each carries the ACTION that resolves it, because "authentication failed" without
+// a next step is the complaint the issue was filed about.
+const AUTH_KINDS = [
+  {
+    kind: 'oauth_refresh_failed',
+    re: /oauth\s+session\s+expired|could\s+not\s+be\s+refreshed|failed\s+to\s+refresh\s+(?:the\s+)?(?:oauth\s+)?(?:access\s+)?token|refresh\s+token\s+(?:is\s+)?(?:missing|expired|invalid|revoked)|oauth\s+token\s+(?:has\s+)?expired/i,
+    label: 'OAuth session expired and the CLI could not refresh it',
+    hint: 'Re-authenticate the Claude CLI: run `claude login` (in a studio terminal, or on the remote host for an SSH project).',
+  },
+  {
+    kind: 'invalid_api_key',
+    re: /invalid\s+api\s+key|invalid\s+bearer\s+token/i,
+    label: 'The API key was rejected',
+    hint: 'Check ANTHROPIC_API_KEY, or run `claude login` to use a subscription instead.',
+  },
+  {
+    kind: 'not_logged_in',
+    re: /not\s+logged\s+in\s+to\s+claude|please\s+run\s+`?\/?claude\s+login`?|please\s+run\s+`?\/login`?|run\s+`?claude\s+login`?\s+to\s+(?:re-?)?authenticate/i,
+    label: 'The Claude CLI is not logged in',
+    hint: 'Run `claude login` (in a studio terminal, or on the remote host for an SSH project).',
+  },
+];
+
+/** The single line carrying the auth failure, clipped for storage in failure_reason. */
+function authErrorSnippet(text) {
+  for (const line of String(text).split(/\r?\n/)) {
+    if (AUTH_ERROR_RE.test(line)) return line.trim().substring(0, 160);
+  }
+  return String(text).trim().substring(0, 160);
+}
+
+/**
+ * Classify an auth failure found in `text`.
+ * @param {string} text
+ * @returns {{kind:string, label:string, hint:string, message:string}|null}
+ */
+function classifyAuthError(text = '') {
+  if (!isAuthError(text)) return null;
+  const snippet = authErrorSnippet(text);
+  for (const k of AUTH_KINDS) {
+    if (k.re.test(text)) return { kind: k.kind, label: k.label, hint: k.hint, message: snippet };
+  }
+  return {
+    kind: 'auth_error',
+    label: 'Authentication failed',
+    hint: 'Re-authenticate the Claude CLI: run `claude login` (in a studio terminal, or on the remote host for an SSH project).',
+    message: snippet,
+  };
+}
+
+/**
+ * Inspect a finished turn for an authentication stop.
+ *
+ * Returns null for a clean success even when the text matches — see the false-positive
+ * note in the header. `isError`/`subtype` come from the CLI result payload, so this
+ * mirrors shouldRetryOverload()'s guard exactly.
+ *
+ * @param {object} o
+ * @param {string[]} [o.texts] - candidate texts (turn tail, result payload, stderr)
+ * @param {string} [o.subtype] - result subtype (e.g. 'success', 'error_during_execution')
+ * @param {boolean} [o.isError] - the result.is_error flag
+ * @returns {{reason:'auth_error', kind:string, label:string, hint:string, message:string}|null}
+ */
+function detectAuthError({ texts = [], subtype, isError } = {}) {
+  if (subtype === 'success' && !isError) return null;
+  for (const raw of texts) {
+    const c = classifyAuthError(raw);
+    if (c) return { reason: 'auth_error', ...c };
+  }
+  return null;
+}
+
+/**
+ * The chat notice for an auth stop. Written as a real status line (leading `---`
+ * fence) because statusLineKind() in public/index.html requires it — without the
+ * fence the SPA stamps its own "✅ Done" badge over the warning (the run-continuation.js
+ * lesson).
+ * @param {{label:string, hint:string, message:string}} info
+ * @returns {string}
+ */
+function authErrorNotice(info) {
+  return `\n\n---\n🔐 **${info.label}.** ${info.hint}\n\nThis is not retried: re-authentication needs a human, so retrying would only repeat the same failure.\n\n> ${info.message}\n\n`;
+}
+
+module.exports = {
+  isAuthError, classifyAuthError, detectAuthError, authErrorNotice, authErrorSnippet,
+  AUTH_ERROR_RE,
+};
diff --git a/package.json b/package.json
index 4e0d27d..6c1eed2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "claude-code-studio",
-  "version": "7.16.0",
+  "version": "7.16.1",
   "description": "Full-featured web workspace for Claude Code — chat, Kanban, multi-agent, MCP, skills, projects",
   "bin": {
     "claude-code-studio": "./bin/cli.js"
@@ -8,7 +8,7 @@
   "scripts": {
     "start": "node server.js",
     "dev": "node --watch server.js",
-    "test": "node --test test/render/*.test.mjs && node test/overload-detector.test.js && node test/usage-limit.test.js && node test/env-load-order.test.js && node test/multi-agent-result.test.js && node test/terminal-session.test.js && node test/terminal-schema.test.js && node test/bots.test.js && node test/bot-inbox.test.js && node test/bots-api.test.js && node test/running-sessions.test.js && node test/session-liveness.test.js && node test/terminal-bridge.integration.test.js && node test/tmux-composite.test.js && node test/telegram-format.test.js && node test/telegram-behaviour.test.js && node test/ask-user-question.test.js && node test/delegate-terminal.test.js && node test/update-flow.test.js && node test/kanban-schedule.test.js && node test/kanban-run-badges.test.js && node test/task-backlog.test.js && node test/i18n-completeness.test.js && node test/config-resolve.test.js && node test/chat-defaults.test.js && node test/chat-defaults-api.test.js && node test/run-continuation.test.js && node test/worktree-manager.test.js && node test/setup-gate.test.js && node test/path-guard.test.js && node test/subscribe-nocatchup.test.js && node test/cli-import-remote.test.js && node test/remote-list-parse.test.js && node test/config-migrate.test.js && node test/engine-pane.test.js && node test/global-workspace.test.js && node test/ssh-secret.test.js && node test/agent-dag.test.js && node test/ssh-parser.test.js && node test/ssh-termination.test.js && node test/session-restart.test.js && node test/remote-env.test.js && node test/remote-files.test.js && node test/remote-files-api.test.js && node test/auth-token.test.js && node test/cmd-model.test.js && node test/origin-guard.test.js && node test/interrupted-recovery.test.js && node test/queue-persistence.test.js && node test/interrupt-idle-config.test.js && node test/agents-md.test.js && node test/editor-links.test.js && node test/editor-open-api.test.js && node test/interrupt-delivery.test.js && node test/terminal-pane-guard.integration.test.js && node test/composer-terminal.test.js && node test/claude-cli-status.test.js && node test/asar-helpers.test.js",
+    "test": "node --test test/render/*.test.mjs && node test/overload-detector.test.js && node test/usage-limit.test.js && node test/auth-errors.test.js && node test/env-load-order.test.js && node test/multi-agent-result.test.js && node test/terminal-session.test.js && node test/terminal-schema.test.js && node test/bots.test.js && node test/bot-inbox.test.js && node test/bots-api.test.js && node test/running-sessions.test.js && node test/session-liveness.test.js && node test/terminal-bridge.integration.test.js && node test/tmux-composite.test.js && node test/telegram-format.test.js && node test/telegram-behaviour.test.js && node test/ask-user-question.test.js && node test/delegate-terminal.test.js && node test/update-flow.test.js && node test/kanban-schedule.test.js && node test/kanban-run-badges.test.js && node test/task-backlog.test.js && node test/i18n-completeness.test.js && node test/config-resolve.test.js && node test/chat-defaults.test.js && node test/chat-defaults-api.test.js && node test/run-continuation.test.js && node test/worktree-manager.test.js && node test/setup-gate.test.js && node test/path-guard.test.js && node test/subscribe-nocatchup.test.js && node test/cli-import-remote.test.js && node test/remote-list-parse.test.js && node test/config-migrate.test.js && node test/engine-pane.test.js && node test/global-workspace.test.js && node test/ssh-secret.test.js && node test/agent-dag.test.js && node test/ssh-parser.test.js && node test/ssh-termination.test.js && node test/session-restart.test.js && node test/remote-env.test.js && node test/remote-files.test.js && node test/remote-files-api.test.js && node test/auth-token.test.js && node test/cmd-model.test.js && node test/origin-guard.test.js && node test/interrupted-recovery.test.js && node test/queue-persistence.test.js && node test/interrupt-idle-config.test.js && node test/agents-md.test.js && node test/editor-links.test.js && node test/editor-open-api.test.js && node test/interrupt-delivery.test.js && node test/terminal-pane-guard.integration.test.js && node test/composer-terminal.test.js && node test/claude-cli-status.test.js && node test/asar-helpers.test.js",
     "postinstall": "node scripts/install-hooks.js",
     "release": "node scripts/release.js",
     "electron:dev": "electron .",
diff --git a/public/kanban.html b/public/kanban.html
index 3169027..488e241 100644
--- a/public/kanban.html
+++ b/public/kanban.html
@@ -492,7 +492,7 @@
     'nav.chat':'Чат','nav.kanban':'Kanban дошка','nav.aria':'Навігація між розділами',
     'stat.total':'всього',
     'card.sched_tip':'Чекає запуску:','modal.sched_wait':'Чекає запуску:','locale':'uk-UA',
-    'card.paused':'Ліміт використання','card.paused_tip':'Виконання зупинив ліміт використання. Автопродовження:',
+    'card.paused':'Ліміт використання','card.paused_tip':'Виконання зупинив ліміт використання. Автопродовження:','card.auth':'Автентифікація','card.auth_tip':'Зупинено помилкою автентифікації. Виконайте `claude login`, щоб під’єднатися знову:',
     'hdr.group':'Група','group.add':'Нова група','group.edit':'Редагувати групу',
     'group.title':'Назва групи *','group.tasks':'Завдання','group.add_task':'+ Додати завдання',
     'group.empty':'Додайте завдання до групи','group.activate':'Запустити',
@@ -540,7 +540,7 @@
     'nav.chat':'Chat','nav.kanban':'Kanban board','nav.aria':'Navigation',
     'stat.total':'total',
     'card.sched_tip':'Waiting for launch:','modal.sched_wait':'Waiting for launch:','locale':'en-US',
-    'card.paused':'Usage limit','card.paused_tip':'Stopped by a usage limit. Resumes automatically:',
+    'card.paused':'Usage limit','card.paused_tip':'Stopped by a usage limit. Resumes automatically:','card.auth':'Auth','card.auth_tip':'Stopped by an authentication failure. Run `claude login` to reconnect:',
     'hdr.group':'Group','group.add':'New group','group.edit':'Edit group',
     'group.title':'Group title *','group.tasks':'Tasks','group.add_task':'+ Add task',
     'group.empty':'Add tasks to the group','group.activate':'Run',
@@ -588,7 +588,7 @@
     'nav.chat':'Чат','nav.kanban':'Kanban доска','nav.aria':'Навигация',
     'stat.total':'всего',
     'card.sched_tip':'Ожидает запуска:','modal.sched_wait':'Ожидает запуска:','locale':'ru-RU',
-    'card.paused':'Лимит использования','card.paused_tip':'Выполнение остановил лимит использования. Автопродолжение:',
+    'card.paused':'Лимит использования','card.paused_tip':'Выполнение остановил лимит использования. Автопродолжение:','card.auth':'Аутентификация','card.auth_tip':'Остановлено ошибкой аутентификации. Выполните `claude login`, чтобы подключиться снова:',
     'hdr.group':'Группа','group.add':'Новая группа','group.edit':'Редактировать группу',
     'group.title':'Название группы *','group.tasks':'Задания','group.add_task':'+ Добавить задание',
     'group.empty':'Добавьте задания в группу','group.activate':'Запустить',
@@ -636,7 +636,7 @@
     'nav.chat':'Discussion','nav.kanban':'Tableau Kanban','nav.aria':'Navigation',
     'stat.total':'au total',
     'card.sched_tip':'En attente du lancement :','modal.sched_wait':'En attente du lancement :','locale':'fr-FR',
-    'card.paused':"Limite d'utilisation",'card.paused_tip':"Arrêté par une limite d'utilisation. Reprise automatique :",
+    'card.paused':"Limite d'utilisation",'card.paused_tip':"Arrêté par une limite d'utilisation. Reprise automatique :",'card.auth':'Authentification','card.auth_tip':"Arrêté par un échec d'authentification. Exécutez `claude login` pour vous reconnecter :",
     'hdr.group':'Groupe','group.add':'Nouveau groupe','group.edit':'Modifier le groupe',
     'group.title':'Titre du groupe *','group.tasks':'Tâches','group.add_task':'+ Ajouter une tâche',
     'group.empty':'Ajoutez des tâches au groupe','group.activate':'Lancer',
@@ -684,7 +684,7 @@
     'nav.chat':'צ׳אט','nav.kanban':'לוח קנבן','nav.aria':'ניווט',
     'stat.total':'סה״כ',
     'card.sched_tip':'ממתין להפעלה:','modal.sched_wait':'ממתין להפעלה:','locale':'he-IL',
-    'card.paused':'מגבלת שימוש','card.paused_tip':'נעצר בגלל מגבלת שימוש. יתחדש אוטומטית:',
+    'card.paused':'מגבלת שימוש','card.paused_tip':'נעצר בגלל מגבלת שימוש. יתחדש אוטומטית:','card.auth':'אימות','card.auth_tip':'נעצר עקב כשל אימות. הרץ `claude login` כדי להתחבר מחדש:',
     'hdr.group':'קבוצה','group.add':'קבוצה חדשה','group.edit':'עריכת הקבוצה',
     'group.title':'שם הקבוצה *','group.tasks':'משימות','group.add_task':'+ הוספת משימה',
     'group.empty':'הוסיפו משימות לקבוצה','group.activate':'הפעלה',
@@ -1259,6 +1259,16 @@
   if(!m)return null;
   return {resumeAt:m[1]?+m[1]:(tk.scheduled_at||null),message:(m[2]||'').trim().substring(0,160)};
 }
+// #86: failure_reason "auth_error:<kind> <line>" means the run stopped because the Claude
+// CLI could not authenticate — an expired OAuth session it could not refresh. Unlike a usage
+// limit this NEVER clears by itself and is never retried, so the card has to say so: without
+// this badge an auth stop is indistinguishable from a task that simply failed, which is the
+// "nothing tells me why" half of the report.
+function kbAuthStop(tk){
+  const m=/^auth_error(?::(\S+))?(?:\s+([\s\S]*))?$/.exec(tk&&tk.failure_reason||'');
+  if(!m)return null;
+  return {kind:m[1]||'auth_error',message:(m[2]||'').trim().substring(0,160)};
+}
 // The dials the next run will ACTUALLY use, as card badges (#84, "Kanban Visibility").
 //
 // Pure on purpose — `test/kanban-run-badges.test.js` lifts it out of this file, so the
@@ -1299,6 +1309,8 @@
   const cfgBadges=kbRunBadges(tk).map(b=>`<span class="badge badge-muted" title="${escH(b.title)}">${escH(b.text)}</span>`).join('');
   const retryBadge=tk.retry_count>0?`<span class="badge badge-muted" title="${tk.retry_count} ${t('card.retry_tooltip')}">${escH(t('card.retry'))} ×${tk.retry_count}</span>`:'';
   const pausedInfo=kbUsageLimit(tk);
+  const authInfo=kbAuthStop(tk);
+  const authBadge=authInfo?`<span class="badge badge-paused" title="${escH(t('card.auth_tip'))}${authInfo.message?' '+escH(authInfo.message):''}">🔐 ${escH(t('card.auth'))}</span>`:'';
   const pausedBadge=pausedInfo?`<span class="badge badge-paused" title="${escH(t('card.paused_tip'))} ${escH(pausedInfo.resumeAt?fmtScheduledAt(pausedInfo.resumeAt):'')}${pausedInfo.message?' — '+escH(pausedInfo.message):''}">⏸ ${escH(t('card.paused'))}${pausedInfo.resumeAt?' · '+escH(fmtScheduledAt(pausedInfo.resumeAt)):''}</span>`:'';
   const schedBadge=(!pausedInfo&&tk.scheduled_at&&(tk.status==='todo'||tk.status==='backlog'))?`<span class="badge badge-sched" title="${escH(t('card.sched_tip'))} ${escH(fmtScheduledAt(tk.scheduled_at))}"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" style="flex-shrink:0"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 12"/></svg>${escH(fmtScheduledAt(tk.scheduled_at))}</span>`:'';
   // Only while the board shows every project: inside one project the badge would repeat
@@ -1308,7 +1320,7 @@
     <div class="card-title">${escH(tk.title)}</div>
     ${tk.description?`<div class="card-desc">${escH(tk.description)}</div>`:''}
     <div class="card-foot">
-      ${projBadge}${pausedBadge}${schedBadge}${sessBadge}${cfgBadges}${retryBadge}
+      ${projBadge}${pausedBadge}${authBadge}${schedBadge}${sessBadge}${cfgBadges}${retryBadge}
       <span class="card-time">${relTime(tk.updated_at)}</span>
       <span class="card-actions">
         <button class="cbtn" title="${t('modal.edit')}" onclick="event.stopPropagation();openEditModal('${tk.id}')">✎</button>
diff --git a/server.js b/server.js
index 129fcdd..12918ac 100644
--- a/server.js
+++ b/server.js
@@ -112,6 +112,7 @@ const editorLinks = require('./editor-links');
 const UNATTENDED_MAX_TURNS = 30;
 
 const { isTransientOverload, shouldRetryOverload, detectUsageLimit, taskStatusForStop } = require('./rate-limit-utils');
+const { detectAuthError, authErrorNotice } = require('./auth-errors');
 const { buildTerminalCommand: buildDelegateCommand, winTerminalArgs } = require('./delegate-terminal');
 const { isAgentSuccess, shouldAutoContinue, agentStopReason } = require('./multi-agent-result');
 const {
@@ -1972,6 +1973,9 @@ async function startTask(task) {
     // Auto-continue loop: keep resuming until agent completes or budget exhausted
     let taskContinueCount = 0;
     let taskOverloadRetryCount = 0;
+    // #86 — set when a turn stopped on an authentication failure. Survives the loop so
+    // the card is failed with a reason that names the cause instead of a generic stop.
+    let taskAuthStop = null;
     let clarifyTurns = 0; // follow-up turns spent on undelivered clarifications — see MAX_CLARIFY_TURNS
     let currentTaskPrompt = prompt;
     let currentTaskCid = claudeSessionId;
@@ -2202,6 +2206,22 @@ async function startTask(task) {
         }
       }
 
+      // 🔐 Authentication failure (#86) — never auto-continued. An expired OAuth session
+      // needs a human, so the remaining budget would buy nothing but identical failures.
+      {
+        const _lastTurn = fullText.slice(_ftBefore);
+        const _resultText = typeof lastTaskResult?.result === 'string' ? lastTaskResult.result : '';
+        taskAuthStop = detectAuthError({ texts: [_lastTurn, _resultText], subtype: lastTaskResult?.subtype, isError: lastTaskResult?.is_error });
+        if (taskAuthStop) {
+          log.error('[taskWorker] auth failure', { taskId: task.id, kind: taskAuthStop.kind, message: taskAuthStop.message });
+          const _n = authErrorNotice(taskAuthStop);
+          fullText += _n;
+          { const _tb = (taskBuffers.get(task.id) || '') + _n; taskBuffers.set(task.id, _tb.length > MAX_CHAT_BUFFER ? _tb.slice(-MAX_CHAT_BUFFER) : _tb); }
+          broadcastToSession(sessionId, { type: 'text', text: _n, tabId: sessionId });
+          break;
+        }
+      }
+
       // ✅ Success — agent finished naturally
       if (lastTaskResult?.subtype === 'success') break;
       // 💰 Budget limit — can't continue
@@ -2432,7 +2452,7 @@ async function startTask(task) {
               botId: task.bot_id || null,
             }).catch(() => {});
           }
-        } else if (task.chain_id && !usageLimitExhausted && (task.task_retry_count || 0) < MAX_CHAIN_RETRIES) {
+        } else if (task.chain_id && !usageLimitExhausted && !taskAuthStop && (task.task_retry_count || 0) < MAX_CHAIN_RETRIES) {
           // 🔄 Auto-retry for chain tasks — don't give up on first failure
           const reason = isRateLimited ? 'rate_limited' : 'agent_incomplete';
           _retryBackoffMs = isRateLimited ? Math.min(60000 * ((task.task_retry_count || 0) + 1), 300000) : 3000;
@@ -2452,7 +2472,13 @@ async function startTask(task) {
           }
         } else {
           // ❌ Failed — retries exhausted or not a chain task
-          const reason = usageLimitExhausted ? 'usage_limit_exhausted' : isRateLimited ? 'rate_limited' : 'agent_incomplete';
+          // #86: an auth stop is reported as itself. It is neither "incomplete work" nor
+          // a rate limit, and naming it is the whole point — the card is the only place a
+          // user sees WHY unattended work stopped. Format "auth_error:<kind> <line>"
+          // mirrors the parseable "usage_limit:<unix> …" prefix above.
+          const reason = taskAuthStop
+            ? `auth_error:${taskAuthStop.kind} ${taskAuthStop.message || ''}`.trim().substring(0, 300)
+            : usageLimitExhausted ? 'usage_limit_exhausted' : isRateLimited ? 'rate_limited' : 'agent_incomplete';
           db.prepare(`UPDATE tasks SET status='cancelled', failure_reason=?, worker_pid=NULL, updated_at=datetime('now') WHERE id=?`)
             .run(reason, task.id);
           log.error(`[taskWorker] task ${task.id}: cancelled (${reason}, subtype: ${lastTaskResult?.subtype || 'unknown'})`);
@@ -4273,6 +4299,23 @@ async function runCliSingle(p) {
       continue;
     }
 
+    // 🔐 Authentication failure (#86) — stop NOW, before the auto-continue below.
+    // Unlike an overload or a quota stop, this one never clears by itself: the CLI's
+    // OAuth session cannot be refreshed without a human. Auto-continuing just repeats
+    // the same instant failure until the budget is gone, which is what hid the cause.
+    {
+      const lastTurnText = fullText.slice(fullTextBefore);
+      const resultText = typeof resultData?.result === 'string' ? resultData.result : '';
+      const authStop = detectAuthError({ texts: [errorText, resultText, lastTurnText], subtype: resultData?.subtype, isError: resultData?.is_error });
+      if (authStop) {
+        log.error('auth-failure', { sessionId, kind: authStop.kind, message: authStop.message });
+        const notice = authErrorNotice(authStop);
+        fullText += notice;
+        emitTurnNotice({ ws, sessionId, tabId, text: notice });
+        break;
+      }
+    }
+
     // ✅ Success — agent finished naturally, unless it left a background task behind
     // that even the harvest run did not collect. Saying "Done" there is the bug.
     if (resultData?.subtype === 'success') {
@@ -4601,6 +4644,21 @@ async function runSshSingle(p) {
       continue;
     }
 
+    // 🔐 Authentication failure (#86) — see the CLI loop above; mirrored for SSH.
+    // The credentials live on the REMOTE host, so the fix is `claude login` there.
+    {
+      const lastTurnText = fullText.slice(fullTextBefore);
+      const resultText = typeof resultData?.result === 'string' ? resultData.result : '';
+      const authStop = detectAuthError({ texts: [errorText, resultText, lastTurnText], subtype: resultData?.subtype, isError: resultData?.is_error });
+      if (authStop) {
+        log.error('ssh-auth-failure', { sessionId, kind: authStop.kind, message: authStop.message });
+        const notice = authErrorNotice(authStop);
+        fullText += notice;
+        emitTurnNotice({ ws, sessionId, tabId, text: notice });
+        break;
+      }
+    }
+
     if (resultData?.subtype === 'success') {
       const _owed = runContinuation.backgroundOutstanding(bgState);
       const _stranded = runContinuation.describeStrandedBackgroundTask({ outstanding: _owed, nudges: bgNudges });
diff --git a/test/auth-errors.test.js b/test/auth-errors.test.js
new file mode 100644
index 0000000..cd61dd7
--- /dev/null
+++ b/test/auth-errors.test.js
@@ -0,0 +1,179 @@
+// Issue #86 — an expired OAuth session must stop the run, not burn the auto-continue budget.
+//
+// The report: "Failed to authenticate: OAuth session expired and could not be refreshed",
+// work stops, nothing says why. The deeper defect is what the loops did with it: an auth
+// failure is not subtype:'success', so all three agent loops AUTO-CONTINUED it. Each retry
+// fails instantly with the identical error, the budget empties in seconds, and the card ends
+// as a generic 'agent_incomplete' that names nothing. Chain tasks then retried twice more.
+//
+// This suite pins three things:
+//   1. The classifier fires on the CLI/API wording and NOT on ordinary prose.
+//   2. It stays DISJOINT from rate-limit-utils.js — a quota banner keeps its re-queue.
+//   3. The detector sits BEFORE the auto-continue in every loop, and auth is excluded from
+//      the chain retry. Those are ordering facts; a reorder silently restores the bug.
+//
+// Run: node test/auth-errors.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const {
+  isAuthError, classifyAuthError, detectAuthError, authErrorNotice,
+} = require('../auth-errors');
+const { isUsageLimit, isTransientOverload } = require('../rate-limit-utils');
+
+let pass = 0, fail = 0;
+function check(label, actual, expected) {
+  try { assert.deepStrictEqual(actual, expected); pass++; console.log(`  ok   ${label}`); }
+  catch { fail++; console.error(`  FAIL ${label} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`); }
+}
+
+// The exact line from the issue.
+const REPORTED = 'Failed to authenticate: OAuth session expired and could not be refreshed';
+const QUOTA = "You've hit your session limit · resets 11pm (Europe/Paris)";
+const TRANSIENT = 'API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited';
+
+// ── 1. Detection positives ──────────────────────────────────────────────────
+console.log('isAuthError — the messages named in the issue:');
+check('the reported line, verbatim', isAuthError(REPORTED), true);
+check('OAuth session expired', isAuthError('OAuth session expired'), true);
+check('could not be refreshed', isAuthError('The token could not be refreshed'), true);
+check('OAuth token has expired', isAuthError('OAuth token has expired'), true);
+check('refresh token is missing', isAuthError('refresh token is missing'), true);
+check('refresh token expired', isAuthError('The refresh token expired 3 days ago'), true);
+check('refresh token revoked', isAuthError('refresh token revoked by provider'), true);
+check('failed to refresh access token', isAuthError('Failed to refresh the OAuth access token'), true);
+check('Invalid API key', isAuthError('API Error: Invalid API key · Please run /login'), true);
+check('authentication_error', isAuthError('{"type":"authentication_error","message":"..."}'), true);
+check('authentication failed', isAuthError('Authentication failed'), true);
+check('please run claude login', isAuthError('Please run `claude login`'), true);
+check('not logged in to claude', isAuthError('You are not logged in to Claude'), true);
+check('credentials are expired', isAuthError('credentials are expired'), true);
+check('case-insensitive', isAuthError('OAUTH SESSION EXPIRED'), true);
+
+// ── 2. False positives — the reason detection is anchored, not keyword-based ──
+console.log('\nisAuthError — must NOT fire on ordinary text:');
+check('empty', isAuthError(''), false);
+check('non-string', isAuthError(null), false);
+check('the studio\'s own /login route in server.js', isAuthError("app.get('/login', (_,res) => res.sendFile(...))"), false);
+check('the studio\'s own unauthorized reply', isAuthError("return res.status(401).json({ error: 'unauthorized' })"), false);
+check('a bare 401 mention', isAuthError('the endpoint answers 401'), false);
+check('agent planning auth work', isAuthError('I will add OAuth support to the login page'), false);
+check('the word token alone', isAuthError('the auth token is 32 bytes of hex'), false);
+
+// ── 3. Disjoint from rate-limit-utils — each stop keeps its own handling ─────
+// A quota stop re-queues at resetsAt; an overload backs off and retries. Reading either
+// as an auth failure would strand work that would have resumed by itself.
+console.log('\nDisjoint from the rate-limit classifiers:');
+check('quota banner is not an auth error', isAuthError(QUOTA), false);
+check('transient overload is not an auth error', isAuthError(TRANSIENT), false);
+check('auth error is not a usage limit', isUsageLimit(REPORTED), false);
+check('auth error is not a transient overload', isTransientOverload(REPORTED), false);
+
+// ── 4. The clean-success guard ──────────────────────────────────────────────
+// This repository's own issue #86, auth-errors.js and this very file contain the phrase,
+// so an agent asked to read them reproduces it in a turn that SUCCEEDED. Ending that turn
+// on "your credentials expired" would be a lie caused by the fix.
+console.log('\nA clean success is never an auth stop:');
+check('success + no error flag → null', detectAuthError({ texts: [REPORTED], subtype: 'success', isError: false }), null);
+check('success but is_error → detected', detectAuthError({ texts: [REPORTED], subtype: 'success', isError: true })?.kind, 'oauth_refresh_failed');
+check('error subtype → detected', detectAuthError({ texts: [REPORTED], subtype: 'error_during_execution', isError: true })?.kind, 'oauth_refresh_failed');
+check('no texts → null', detectAuthError({ texts: [] }), null);
+check('scans every candidate text', detectAuthError({ texts: ['', 'all fine', REPORTED], isError: true })?.reason, 'auth_error');
+
+// ── 5. Root cause + action (the "display the root cause" ask) ────────────────
+console.log('\nclassifyAuthError — root cause buckets:');
+check('refresh failure is its own kind', classifyAuthError(REPORTED).kind, 'oauth_refresh_failed');
+check('rejected key is its own kind', classifyAuthError('Invalid API key').kind, 'invalid_api_key');
+check('never logged in is its own kind', classifyAuthError('You are not logged in to Claude').kind, 'not_logged_in');
+check('unrecognised wording still classifies', classifyAuthError('Authentication failed').kind, 'auth_error');
+check('every kind carries an action', ['oauth_refresh_failed', 'invalid_api_key', 'not_logged_in', 'auth_error']
+  .map(k => [REPORTED, 'Invalid API key', 'not logged in to Claude', 'Authentication failed'])
+  .flat().every(t => (classifyAuthError(t)?.hint || '').length > 20), true);
+check('the snippet is the offending line only', classifyAuthError(`ok\nfine\n${REPORTED}\nmore`).message, REPORTED);
+check('snippet is clipped', classifyAuthError('OAuth session expired ' + 'x'.repeat(400)).message.length <= 160, true);
+
+// ── 6. The notice must be a real status line ────────────────────────────────
+// statusLineKind() in public/index.html requires the `---` fence; without it the SPA
+// stamps its own "✅ Done" badge over the warning (the run-continuation.js lesson).
+console.log('\nauthErrorNotice:');
+{
+  const n = authErrorNotice(classifyAuthError(REPORTED));
+  check('carries the --- status-line fence', n.includes('\n---\n'), true);
+  check('states the action', n.includes('claude login'), true);
+  check('says it is not retried', /not retried/i.test(n), true);
+  check('quotes the original line', n.includes(REPORTED), true);
+}
+
+// ── 7. Structural pins on server.js ─────────────────────────────────────────
+// Behaviour that lives in a 10k-line file and cannot be unit-tested without booting it.
+// Needles are real statements, never comment prose (the chat-defaults lesson: a needle
+// matched the comment explaining the rule and passed while the code was wrong).
+console.log('\nserver.js integration:');
+{
+  const src = fs.readFileSync(path.join(__dirname, '..', 'server.js'), 'utf8');
+  check('imports the detector', /require\('\.\/auth-errors'\)/.test(src), true);
+  check('imports both helpers used', src.includes('detectAuthError') && src.includes('authErrorNotice'), true);
+
+  // Three call sites: CLI chat, SSH chat, taskWorker.
+  const callSites = src.match(/detectAuthError\(\{/g) || [];
+  check('detector is called in all three loops', callSites.length, 3);
+
+  // ORDER — the actual fix. The detector must precede the auto-continue, or the run
+  // spends its whole budget re-failing before anyone is told why.
+  const iTaskDetect = src.indexOf('taskAuthStop = detectAuthError({');
+  const iTaskSuccessBreak = src.indexOf("if (lastTaskResult?.subtype === 'success') break;");
+  const iTaskContinue = src.indexOf('taskContinueCount++;');
+  check('taskWorker: detector is present', iTaskDetect > 0, true);
+  check('taskWorker: detector runs BEFORE the success break', iTaskDetect < iTaskSuccessBreak, true);
+  check('taskWorker: detector runs BEFORE the auto-continue', iTaskDetect < iTaskContinue, true);
+
+  const iChatDetect = src.indexOf('const authStop = detectAuthError({');
+  const iChatSuccess = src.indexOf("if (resultData?.subtype === 'success') {");
+  check('chat loop: detector is present', iChatDetect > 0, true);
+  check('chat loop: detector runs BEFORE the success break', iChatDetect < iChatSuccess, true);
+
+  // The SSH loop is the second pair; both must hold.
+  const iChatDetect2 = src.indexOf('const authStop = detectAuthError({', iChatDetect + 1);
+  const iChatSuccess2 = src.indexOf("if (resultData?.subtype === 'success') {", iChatSuccess + 1);
+  check('ssh loop: detector is present', iChatDetect2 > 0, true);
+  check('ssh loop: detector runs BEFORE the success break', iChatDetect2 < iChatSuccess2, true);
+
+  // An auth stop must not be retried by the chain machinery.
+  check('chain auto-retry excludes an auth stop',
+    src.includes('task.chain_id && !usageLimitExhausted && !taskAuthStop &&'), true);
+  // The card names the cause, with a parseable prefix like the usage_limit one.
+  check('failure_reason carries the auth_error prefix',
+    src.includes('`auth_error:${taskAuthStop.kind}'), true);
+  check('the auth stop is logged with its kind',
+    /log\.error\('auth-failure', \{ sessionId, kind:/.test(src), true);
+}
+
+// ── 8. The Kanban card must say why (public/kanban.html) ────────────────────
+// Without a badge an auth stop is indistinguishable from an ordinary failure, which is
+// the "nothing tells me why" half of the report. kbAuthStop is lifted out and run, the
+// way kanban-run-badges.test.js does, so the parser is tested rather than eyeballed.
+console.log('\nkanban.html auth badge:');
+{
+  const kb = fs.readFileSync(path.join(__dirname, '..', 'public', 'kanban.html'), 'utf8');
+  const m = /function kbAuthStop\(tk\)\{[\s\S]*?\n\}/.exec(kb);
+  check('kbAuthStop exists', !!m, true);
+  const kbAuthStop = new Function(`${m[0]}; return kbAuthStop;`)();
+
+  check('parses kind and message', kbAuthStop({ failure_reason: 'auth_error:oauth_refresh_failed ' + REPORTED }),
+    { kind: 'oauth_refresh_failed', message: REPORTED });
+  check('kind only', kbAuthStop({ failure_reason: 'auth_error:not_logged_in' }), { kind: 'not_logged_in', message: '' });
+  check('bare prefix', kbAuthStop({ failure_reason: 'auth_error' }), { kind: 'auth_error', message: '' });
+  check('a usage-limit reason is not an auth stop', kbAuthStop({ failure_reason: 'usage_limit:123 banner' }), null);
+  check('an ordinary failure is not an auth stop', kbAuthStop({ failure_reason: 'agent_incomplete' }), null);
+  check('no reason', kbAuthStop({ failure_reason: null }), null);
+  check('no task', kbAuthStop(null), null);
+  check('message is clipped', kbAuthStop({ failure_reason: 'auth_error:k ' + 'x'.repeat(400) }).message.length, 160);
+
+  // The badge has to be rendered, not just computed.
+  check('the badge is in the card footer', /\$\{projBadge\}\$\{pausedBadge\}\$\{authBadge\}/.test(kb), true);
+  check('every language has the badge strings',
+    (kb.match(/'card\.auth'/g) || []).length, (kb.match(/'card\.paused'/g) || []).length);
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);