@shumkov/orchestra 0.2.0 → 0.4.0

package/docs/AUTH_DISABLED_DETECTION_SPEC.md

@@ -0,0 +1,388 @@
+# AUTH_DISABLED detection — spec
+
+## Problem
+
+When Anthropic disables Claude Code / subscription access on an account
+(non-payment, org policy, an admin toggling a Team/Enterprise setting), the
+`claude` CLI does not exit or surface an HTTP error orchestra's process
+wrapper can see. It renders the notice **inside the TUI**, as if it were a
+turn's output, then sits there — no reply-tool call, no hook `Stop` event.
+orchestra's `CliProcess` has no detector for this text, so the turn just
+waits. It is eventually killed by the existing idle ceiling
+(`DEFAULT_TURN_TIMEOUT_MS` = 10 min) or the hard wall-clock backstop
+(`DEFAULT_TURN_HARD_MAX_MS` = 90 min), rejecting with the generic
+`err.code = 'TURN_TIMEOUT'` / `'TURN_MAX_EXCEEDED'` (cli-process.js:2458).
+Both consumer bots (water, polygram) then classify that generic code into a
+canned "went quiet" reply, 10+ minutes late, with no indication that the
+real cause is an account-level auth problem an operator needs to act on.
+
+Because CliProcess is shared, water and polygram can both go dark at the
+same minute on the same account — which is what happened in production.
+
+This is a **different failure mode** from the OAuth-refresh-token-expiry
+case fixed in 0.3.0 (`checkClaudeAuthHealth` / `claude-bin.js`) — that one
+is a free, local, credentials-file check for an *expired* token, done
+*before* spawn. This one is Anthropic *actively disabling* access
+mid-conversation; it has no file-readable precondition and can only be
+observed in the live CLI output.
+
+## What the message actually looks like (verified)
+
+Contrary to the initial hand-off note ("NOT an HTTP 401/403"), the
+underlying cause genuinely is an HTTP 403 (`permission_error`,
+`"OAuth authentication is currently not allowed for this organization"`)
+— but that response is consumed *inside* the `claude` binary. orchestra
+runs `claude` inside tmux over the channels bridge; it never sees raw HTTP.
+What it sees is the CLI's own rendering of the error, in the pane, as if it
+were conversational output. Per Anthropic's own error reference
+(`code.claude.com/docs/en/errors`, confirmed against multiple
+`anthropics/claude-code` GitHub issues, e.g. #63886, #62722, #68212), the
+literal, stable text is:
+
+```
+Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access
+```
+
+This is a fixed product string (not a template with variable account
+details), and it is what the CLI prints regardless of surface (`/login`,
+mid-session, `-p` mode surfaces it as the structured code
+`oauth_org_not_allowed`, which orchestra also never sees — that's an SDK
+path, not the CLI/tmux path CliProcess drives).
+
+## Where in cli-process.js to hook this
+
+CliProcess has three distinct places that inspect Claude's output, and only
+one of them is a good fit:
+
+1. **Bridge MCP protocol** (`_handleBridgeMessage`, `_dispatchToolCall`) —
+   structured tool calls (`reply`, `ask`, permission requests) delivered
+   over the channels socket. Not applicable: this failure produces no tool
+   call. Claude never gets far enough to call anything.
+2. **Hook ndjson stream** (`_handleHookEvent`, `Stop`'s
+   `lastAssistantMessage`) — this *would* be the natural place if the CLI
+   fired a `Stop` hook after emitting the notice. It does not: the turn
+   diagnosis confirms it hangs to the idle ceiling rather than resolving via
+   the existing zero-reply Stop-fallback (`_computeTurnDelivery`,
+   cli-process.js:2153), which only fires once `Stop` lands. No `Stop`
+   event here means no hook payload carries this text.
+3. **tmux pane-capture watchdog** (`_pollMidTurnDialogs`, cli-process.js
+   ~4008) — the *only* place that regex-matches Claude's literal rendered
+   output. It already runs every `PONG_CHECK_INTERVAL_MS` (5s) while a turn
+   is pending (`pendingTurns.size > 0`), captures the pane with `-J`
+   (line-rewrap-safe), and matches a catalog of known dialog strings
+   (`MID_TURN_PROMPTS`, `SESSION_AGE_PROMPT_RE`, `UNKNOWN_PROMPT_HEURISTIC_RE`).
+   This is the existing "live scan of streamed output" the task referred
+   to — it is the mechanism that already recovers session-age dialogs and
+   other TUI-only text. It is the correct, minimal hook point.
+
+**Chosen approach:** add an `AUTH_DISABLED_RE` check inside
+`_pollMidTurnDialogs`, run once per poll, BEFORE the `STREAMING_HINT_RE` /
+`MID_TURN_PROMPTS` / unknown-prompt checks (most severe signal first; on
+confirmed match the rest of the method is skipped via an explicit early
+`return` — see "same-poll interference" below). On confirmed match: reject
+every currently-pending turn with `err.code = 'AUTH_DISABLED'`, mirroring
+the existing drain idiom already used three times in this file
+(`_handleBridgeDisconnected`, `_doKill`, `resetSession`). Detection latency
+is bounded by two poll intervals (≤10s, see debounce below) — effectively
+immediate next to the current 10-minute wait.
+
+**Bounded tail, not the full pane.** `_pollMidTurnDialogs` reuses the
+pane already captured for the other detectors, which defaults to
+`capturePane`'s `lines: 1000` (tmux-runner.js:345). That's the right depth
+for dialogs that must survive scrollback, but wrong for this detector: once
+printed, the notice would stay inside a 1000-line window for a long time
+(review finding — a legitimate assistant reply that happens to quote this
+exact error text, e.g. a user asking Claude to explain the error, would
+then falsely arm detection for every subsequent turn in the session until
+~1000 lines of new output rolled it out of view). Mitigation: only test
+`AUTH_DISABLED_RE` against the **last ~40 lines** of the already-captured
+pane (`pane.split('\n').slice(-40).join('\n')` — same pattern already used
+for the unknown-prompt excerpt at cli-process.js:4119-4120, no extra tmux
+call). A wrapped single-sentence notice is 1-3 logical lines after `-J`
+join; 40 lines comfortably covers TUI chrome around it while aging the
+match out within roughly one screen of subsequent output — versus ~1000
+lines for the untrimmed pane.
+
+**Two-consecutive-poll debounce.** Even bounded to 40 lines, a single-poll
+match isn't enough: a legitimate reply that quotes the string could still
+be visible in the tail for one poll tick while the turn is still
+in-flight (not yet `Stop`-resolved). Require the match on two consecutive
+polls (`this._authDisabledArmed`, reset to `false` on any poll where the
+tail does *not* match) before rejecting. Adds ≤1 poll interval (~5s) of
+latency to the worst case; still trivial next to the 10-minute status quo.
+
+**Implementation correction found in code review (must-fix, applied):** the
+first draft only reset `_authDisabledArmed` inside the tail-check block
+itself — every EARLY-RETURN guard above it (`this.closed`,
+`pendingTurns.size === 0`, `_openQuestions.size > 0`, no `tmuxSession`, no
+`captureWide`, a `captureWide` throw, an empty `pane`) left the flag
+untouched. Concretely: turn A arms the flag, then resolves normally via
+`Stop` — `pendingTurns` empties, so every subsequent poll returns early at
+the `pendingTurns.size === 0` guard *without* touching the flag. It stays
+`true` indefinitely. When an unrelated turn B starts later and its pane
+still shows the same old text within the last 40 lines (plausible — nothing
+scrolled it away during the idle gap), turn B's very FIRST poll sees the
+stale `true` and "confirms" against it, rejecting a turn that had nothing
+to do with the original sighting. This defeated the debounce's actual
+purpose (protecting the *next* turn, not just the one that produced the
+quote). Fixed by resetting `_authDisabledArmed = false` on every one of
+those early-return paths, so "armed" can only ever mean "the immediately
+preceding poll actually re-observed a match against a still-pending turn."
+Caught by an independent correctness-review agent, confirmed by direct
+reproduction, and pinned by a dedicated regression test (test plan below)
+that fails against the first-draft code and passes against the fix.
+
+**Same-poll interference with other detectors (review finding).** Once
+`AUTH_DISABLED_RE` confirms, `_pollMidTurnDialogs` must `return`
+immediately after the drain, rather than falling through to the
+`STREAMING_HINT_RE` heartbeat, `MID_TURN_PROMPTS` loop, or
+`UNKNOWN_PROMPT_HEURISTIC_RE` check. Reason: the drain empties
+`pendingTurns`, and the TUI's idle input cursor (`❯ `) below a static
+notice is exactly what `UNKNOWN_PROMPT_HEURISTIC_RE` matches — without the
+early return, the same poll tick would also emit a confusing
+`cli-mid-turn-unknown-prompt` telemetry row with `pending_count: 0`, or
+worse, send stray dismissal keystrokes (`MID_TURN_PROMPTS` actions) into an
+already-terminated turn.
+
+**Drain must match-and-reject `pendingQueue`, not blunt-truncate it, and
+must reset `inFlight` (review finding).** The three existing drain sites
+are NOT identical: `_handleBridgeDisconnected` (cli-process.js:3436)
+truncates `pendingQueue` with `this.pendingQueue.length = 0` and never
+rejects its items; `_doKill` (3473) and `resetSession` (3697) both walk
+`pendingQueue`, skip entries already covered by `pendingTurns` (matched by
+`turnId`), and explicitly `reject()` the rest (`resetSession`'s own
+comment: entries can be "pushed by callers other than this.send"). This
+fix follows the `_doKill`/`resetSession` shape, not
+`_handleBridgeDisconnected`'s — truncating without rejecting would leak
+orphaned promises, reproducing the exact silent-hang bug class this fix
+exists to close. All three existing sites also set `this.inFlight = false`
+after draining; this fix does the same (missing it would leave
+`inFlight` stuck `true` on a session that can never produce another
+reply).
+
+Not in scope: startup-time detection (before the first `send()`). If
+access is disabled before any turn starts, the existing startup-gate /
+dialog-timeout paths apply and are a different symptom with an existing
+(if generic) error code. This spec only closes the mid-turn gap the
+diagnosis describes.
+
+## The regex
+
+```js
+const AUTH_DISABLED_RE =
+  /organization\s+has\s+disabled\s+Claude\s+subscription\s+access\s+for\s+Claude\s+Code/i;
+```
+
+Anchored on the *exact*, distinctive middle clause of Anthropic's fixed
+product string, not the full sentence (avoids the `·` bullet/separator,
+which could be rendered inconsistently) and not the "use an Anthropic API
+key instead" clause (which is generic advice someone could plausibly type
+in unrelated conversation — the seed regex from the hand-off note used it
+as a standalone alternative, which is the false-positive risk called out
+in the task; this spec drops that alternative). `\s+` (not literal spaces)
+tolerates any pane rewrap artifacts even though `captureWide` already
+passes `-J` (join-wrapped) to tmux.
+
+This phrase is Anthropic product copy naming both "Claude subscription
+access" and "Claude Code" together in a disablement sentence — not
+something a legitimate assistant reply would casually construct while
+answering a user's question about API keys. Verified against real
+production reports (GitHub issues #63886, #62722, #68212) — same string in
+every report, not account-specific interpolation.
+
+**False-positive check performed:** a legitimate reply like *"you can use
+an Anthropic API key instead of your Claude subscription for that"* does
+not match — it doesn't contain "disabled ... Claude Code" in that shape.
+Covered by a negative test case (below).
+
+**Residual false-positive: verbatim quoting (review finding, mitigated
+above, not eliminated by regex alone).** A user debugging *this exact
+issue* could paste the real string and ask Claude to explain it, and a
+healthy Claude reply might echo it back. The regex cannot distinguish
+"this is happening to me" from "here's what that message means" — no
+regex can, the distinguishing signal is behavioral (does the turn go on to
+resolve normally?), not textual. That's what the bounded-tail +
+two-consecutive-poll debounce above defends against, not the regex shape.
+Residual risk after mitigation: a session would have to (a) have this
+exact phrase land in the last ~40 captured lines, (b) on two consecutive
+5s-apart polls, (c) while the turn genuinely has not yet `Stop`-resolved
+both times — a narrow enough window that it's an acceptable trade for
+closing a 10-minute silent production hang. Blast radius if it ever does
+mis-fire: self-scoped to that one chat's one turn (own pane, own
+`pendingTurns`) — not a cross-tenant or cross-session amplification.
+
+## The AUTH_DISABLED contract
+
+- `err.code = 'AUTH_DISABLED'` on the rejection every currently-pending
+  `send()` promise receives.
+- `err.message` — human-readable, includes the detected pane excerpt
+  is *not* included (see security note below) — just a static description.
+- Emitted alongside the reject: `this.emit('auth-disabled-detected', {
+  sessionId, backend })` (telemetry parity with `mid-turn-dialog-detected`)
+  and `this._logEvent('cli-auth-disabled-detected', { pending_count })`
+  (parity with the existing `cli-mid-turn-dialog-detected` telemetry row).
+- `emit('idle')` fires before the rejections resolve, so a wired
+  `HeartbeatReactor` stops cycling (Step E contract, pinned by existing
+  tests for the other drain paths).
+- The underlying `claude` process and tmux session are **not** killed and
+  the session is **not** reset (`claudeSessionId` untouched) — mirrors
+  `TURN_TIMEOUT`'s behavior, not `resetSession`'s. Killing/resetting is a
+  policy decision (notify admin? pause the chat? wait for the org to
+  re-enable?) that belongs to the consumer, not to the shared engine.
+- water and polygram add `AUTH_DISABLED` as a `CODES` short-circuit in
+  their own `classify()` (out of scope for this repo/PR — happening in
+  parallel per the task).
+- **Consumer backoff requirement (review finding, documented here since
+  it's a cross-repo coordination point, not enforceable from this repo):**
+  `AUTH_DISABLED` means the *account* is blocked, not the request — an
+  immediate automatic retry will hit the same wall. Because
+  `_pollMidTurnDialogs`'s only gate is `pendingTurns.size > 0`, a consumer
+  that retries into the same session on catch will get rejected again on
+  the next poll (≤5s), not instantly — this is not a busy-loop on
+  orchestra's side (poll cadence is fixed, independent of `pendingTurns`
+  churn) — but it is repeated wasted `send()` calls against a
+  known-disabled account. water/polygram should treat `AUTH_DISABLED` as
+  non-retryable (surface to the operator / admin, don't auto-resend) the
+  same way they'd treat `AUTH_EXPIRED` today.
+- The rejection `err.message` is a static, generic description — it does
+  **not** include the captured pane excerpt. This mirrors the L13
+  incident precedent already in this file (cli-process.js:1206-1210):
+  logging raw pane/reply content at default log levels previously leaked
+  private chat content into the log sink unconditionally. The matched
+  string here is fixed Anthropic product copy with no user content, so
+  there's nothing account-specific to lose by omitting it — but the
+  precedent is why the omission is deliberate, not an oversight.
+
+## orchestra's own `lib/error/classify.js` — decision
+
+**Decision: no entry added.** Investigated and confirmed:
+`lib/error/classify.js` is `require`d by exactly one file in this repo,
+`lib/process/sdk-process.js` (only `isTransientHttpError`, for the SDK
+backend's own retry-once decision on `SDKResultMessage`/`SDKAssistantMessage`
+errors). It is not `require`d by `cli-process.js`, not called anywhere on a
+`CliProcess`-thrown error, and not re-exported from `index.js` (confirmed:
+`index.js`'s `module.exports` has no `classify` key). Its existing
+`TURN_TIMEOUT`/`TURN_MAX_EXCEEDED`/`BRIDGE_DISCONNECTED` entries are
+already dead weight for any CliProcess consumer of *this* package — nothing
+in-repo classifies a CliProcess error through this file today (those
+entries are there for internal consistency / a hypothetical future shared
+consumer, not because something calls them). Adding `AUTH_DISABLED` here
+would look like it wires the contract up when it does not — actively
+misleading. This is purely a downstream-consumer concern: water and
+polygram each already maintain their own `classify()` and add the
+`AUTH_DISABLED` case there, per the task's parallel work.
+
+## Failure modes / edge cases considered
+
+- **`_openQuestions.size > 0` gate**: `_pollMidTurnDialogs` returns early
+  while an interactive `ask` is outstanding (pane shows the question text,
+  not activity). If Anthropic disables access while a question is
+  mid-flight, detection is delayed until the question resolves or times
+  out. Pre-existing limitation shared with every other entry in
+  `MID_TURN_PROMPTS` — not introduced by this change, not fixed by it.
+  Documented, not addressed (out of scope; the question-timeout backstop
+  already bounds this).
+- **Multiple pending turns**: pane detection is process-wide (one pane, not
+  attributable to a specific turn), same limitation the `Stop`-hook
+  attribution comment (cli-process.js:2074) already documents for that
+  path. All currently-pending turns are rejected — correct, since a
+  disabled account can serve none of them.
+- **Re-detection after reject**: no time-windowed dedup is used (unlike
+  `MID_TURN_DEDUP_WINDOW_MS` for `MID_TURN_PROMPTS`). Once rejected,
+  `pendingTurns` is empty, so `_pollMidTurnDialogs`'s
+  `pendingTurns.size === 0` guard means the next poll no-ops. If the
+  consumer resends into the same wedged session, the pane still shows the
+  notice (nothing consumes it) and the new turn is rejected again on the
+  next poll (≤5s) — correct, not a busy-loop (poll cadence is fixed at
+  `PONG_CHECK_INTERVAL_MS`, unrelated to pendingTurns state).
+- **Startup-time disablement** (before first `send()`): out of scope, see
+  above.
+- **Leaking the raw pane excerpt**: existing telemetry
+  (`cli-mid-turn-unknown-prompt`) logs a pane excerpt for *unknown*
+  prompts, by design, for operator triage. This detector's payload is
+  intentionally minimal (no excerpt) — see the L13-precedent note in the
+  contract section above.
+- **Not a new abstraction**: this is the *fourth* near-identical
+  reject-all-pending drain block in this file
+  (`_handleBridgeDisconnected`, `_doKill`, `resetSession`, now this).
+  Extracting a shared `_rejectAllPending(code, opts)` helper was
+  considered and deliberately deferred — the four sites differ enough
+  (queue-truncate-vs-reject, `emit('idle')` conditionality,
+  `claudeSessionId` reset, tmux/bridge teardown) that a parameterized
+  helper risks more complexity than the duplication it removes, and
+  refactoring three already-working shutdown paths is out of scope for a
+  bug fix whose stated purpose is adding one detector. Flagged here as a
+  legitimate follow-up, not silently skipped.
+
+## Test plan
+
+New test in `tests/resume-dialog-fix.test.js`-style direct-invocation form
+(mirrors the existing `B2-midturn` test, which already drives
+`_pollMidTurnDialogs()` directly against a manually-set `pendingTurns`
+entry — no fake-bridge harness needed):
+
+1. **Red**: construct a `CliProcess` with a fake runner whose
+   `captureWide` returns a pane string containing the exact Anthropic
+   notice. Seed `pendingTurns` with one entry (`resolve`/`reject` stubs
+   that record calls). Call `_pollMidTurnDialogs()` **twice** (mirroring
+   the two-consecutive-poll debounce) against the *current, unfixed* code.
+   Assert the pending turn is **not** rejected (`reject` never called,
+   entry still in `pendingTurns`) — pins the current bug (silent hang
+   toward the 10-min ceiling).
+2. **Green**: same test, run again after the fix lands. Assert `reject`
+   is NOT yet called after the first poll (armed, not confirmed), then IS
+   called once after the second poll with `err.code === 'AUTH_DISABLED'`,
+   `pendingTurns` is empty, `'idle'` was emitted, and both
+   `auth-disabled-detected` was emitted and `cli-auth-disabled-detected`
+   was passed to `_logEvent` (via a fake `db.logEvent` collector, same
+   pattern as `resume-dialog-fix.test.js`'s `session-age-dialog-fallback`
+   assertion).
+3. **Single-poll match does not reject**: one poll with a match must not
+   drain `pendingTurns` by itself — asserts the debounce is load-bearing,
+   not a no-op.
+4. **Debounce resets on a clean poll**: match on poll 1, no match on poll
+   2 (pane changed / cleared), match again on poll 3 → still requires two
+   *consecutive* matching polls from that point; poll 3 alone doesn't
+   reject. Guards against an accumulating counter instead of a reset-on-miss
+   flag.
+5. **Negative / false-positive guard**: pane text containing a *legitimate*
+   assistant reply mentioning API keys (e.g. "you can use an Anthropic API
+   key instead of your Claude subscription for that automation") must
+   **not** trigger detection across repeated polls — assert `reject` is
+   never called and the pending turn survives.
+6. **Bounded tail**: a pane where the notice sits *before* the last ~40
+   lines (padded with ≥40 lines of unrelated trailing output) must **not**
+   trigger — pins the tail-bounding behavior, not just "some substring
+   match somewhere in 1000 lines."
+7. **Multi-turn drain**: two pending turns, two consecutive confirming
+   polls → both rejected with `AUTH_DISABLED`, both removed from
+   `pendingTurns` and any matching `pendingQueue` rows.
+8. **No same-poll interference**: on the confirming poll, assert no
+   `sendControl` keystrokes were sent and no `mid-turn-unknown-prompt` /
+   `mid-turn-dialog-detected` events fired — pins the early-`return` after
+   the drain.
+9. Existing `resume-dialog-fix.test.js` / `cli-process-integration.test.js`
+   suites re-run green (no regression to the existing `MID_TURN_PROMPTS`
+   catalog or `STREAMING_HINT_RE` heartbeat).
+10. **`pendingQueue` drain** (added after test-coverage review flagged it as
+    uncovered): a `pendingQueue` entry matching a rejected `turnId` must not
+    be double-rejected; a `pendingQueue`-only entry (no matching
+    `pendingTurns` row) must still be rejected with `AUTH_DISABLED` and
+    removed. Guards against silently regressing to
+    `_handleBridgeDisconnected`'s blunt `pendingQueue.length = 0`
+    truncation, which would leak orphaned promises — every existing test
+    up to that point would still pass under that regression; this is the
+    one that would catch it.
+11. **Stale-arm regression** (added after correctness review found the bug
+    described above): turn A arms the debounce, is then manually cleared
+    from `pendingTurns` (simulating a normal `Stop` resolution before the
+    second poll), and an unrelated turn B is added. Turn B's first poll
+    must NOT be rejected. Verified this test fails against the pre-fix
+    code (which had the detector but not the early-return resets) while
+    every other test in the file still passes — confirms it's the specific
+    pin for this bug, not a duplicate of the existing debounce tests.
+
+Per the repo owner's TDD discipline, the whole suite was run red (detector
+absent) then green (detector added) for the initial cut, and the two
+review-driven additions (10, 11) were each independently confirmed red
+against the version of the code that predated their respective fix.

package/lib/claude-bin.js

@@ -238,10 +238,51 @@ function ensureVendoredClaudeBin(version, { logger = console } = {}) {
   return { ok: true, path: vendored, vendored: true };
 }
 
+/**
+ * Check Claude CLI OAuth health from the credentials file — FREE (no API call,
+ * no model spawn). The CLI stores its login in ~/.claude/.credentials.json under
+ * `claudeAiOauth`, with two expiries: the short-lived `expiresAt` (access token,
+ * which the CLI silently auto-refreshes) and `refreshTokenExpiresAt` (the HARD
+ * limit — once the refresh token itself ages out, auto-refresh 401s and every
+ * channels-backend turn wedges INVISIBLY: claude fires UserPromptSubmit then
+ * dies with "OAuth access token has expired", which never reaches polygram's
+ * classifier, so it degrades to a silent "⏱ went quiet"). We watch the
+ * refresh-token expiry so the daemon can refuse turns with a clear message
+ * instead of wedging.
+ *
+ * Pure + injectable (`home`/`now`) for tests.
+ *
+ * @param {{home?:string, now?:number, warnWithinMs?:number}} [opts]
+ * @returns {{state:'healthy'|'expiring'|'expired'|'unknown', reason?:string,
+ *   refreshTokenExpiresAt:?number, msLeft:?number, daysLeft:?number}}
+ */
+function checkClaudeAuthHealth({ home = os.homedir(), now = Date.now(), warnWithinMs = 3 * 86_400_000 } = {}) {
+  const credPath = path.join(home, '.claude', '.credentials.json');
+  let creds;
+  try {
+    creds = JSON.parse(fs.readFileSync(credPath, 'utf8'));
+  } catch (err) {
+    // Missing/unreadable → can't prove expiry. Report 'unknown' (caller logs it)
+    // rather than 'expired', so a transient read error never hard-refuses traffic.
+    return { state: 'unknown', reason: `credentials unreadable: ${err.code || err.message}`, refreshTokenExpiresAt: null, msLeft: null, daysLeft: null };
+  }
+  const exp = creds && creds.claudeAiOauth && creds.claudeAiOauth.refreshTokenExpiresAt;
+  if (typeof exp !== 'number') {
+    return { state: 'unknown', reason: 'no claudeAiOauth.refreshTokenExpiresAt', refreshTokenExpiresAt: null, msLeft: null, daysLeft: null };
+  }
+  const msLeft = exp - now;
+  const daysLeft = Math.round((msLeft / 86_400_000) * 10) / 10;
+  let state = 'healthy';
+  if (msLeft <= 0) state = 'expired';
+  else if (msLeft <= warnWithinMs) state = 'expiring';
+  return { state, refreshTokenExpiresAt: exp, msLeft, daysLeft };
+}
+
 module.exports = {
   resolvePinnedClaudeBin,
   verifyPinnedClaudeBin,
   ensureVendoredClaudeBin,
   vendorDir,
   CLAUDE_CLI_PINNED_VERSION,
+  checkClaudeAuthHealth,
 };

package/lib/process/cli-process.js

@@ -187,6 +187,38 @@ const UNKNOWN_PROMPT_HEURISTIC_RE = /(\?\s*$|\(y\/N\)|Yes\/No|❯\s|^\s*[12345]\
 // doesn't spam sendControl/event emissions. Aligned with the 5s poll cadence.
 const MID_TURN_DEDUP_WINDOW_MS = 30_000;
 
+// docs/AUTH_DISABLED_DETECTION_SPEC.md: when Anthropic disables Claude
+// subscription access for an account (non-payment, org policy), the `claude`
+// CLI renders a fixed notice INSIDE the TUI instead of exiting or surfacing
+// an HTTP error orchestra's tmux wrapper can see — no reply-tool call, no
+// Stop hook. Pre-fix, the turn just hangs to the 10-min idle ceiling
+// (TURN_TIMEOUT). This is the only literal-text-match detector strong
+// enough to warrant terminating pending turns outright (the others
+// dismiss-and-continue or emit telemetry only), so unlike them it is
+// bounded to a recent tail (not the full ~1000-line pane capture) and
+// requires two consecutive polls before acting — see the spec for the
+// false-positive analysis this defends against.
+//
+// Anchored on the distinctive middle clause of Anthropic's fixed product
+// string (code.claude.com/docs/en/errors; confirmed against
+// anthropics/claude-code issues #63886, #62722, #68212): "Your organization
+// has disabled Claude subscription access for Claude Code · Use an
+// Anthropic API key instead, or ask your admin to enable access". Deliberately
+// drops the "use an Anthropic API key instead" clause — that's generic
+// advice a legitimate reply could construct on its own; the disablement
+// clause is not. \s+ (not literal spaces) tolerates any pane-rewrap
+// artifact even though captureWide already passes tmux `-J` (join-wrapped).
+const AUTH_DISABLED_RE = /organization\s+has\s+disabled\s+Claude\s+subscription\s+access\s+for\s+Claude\s+Code/i;
+// Only the last N lines of the captured pane are tested against
+// AUTH_DISABLED_RE. The shared pane capture defaults to 1000 lines of
+// scrollback (right for dialogs that must survive scrollback); wrong here —
+// a legitimate reply that ever quotes this exact error text (e.g. a user
+// asking Claude to explain it) would otherwise stay "visible" to the
+// detector for the rest of the session. 40 lines comfortably covers the
+// wrapped notice + TUI chrome while aging the match out within roughly one
+// screen of subsequent output.
+const AUTH_DISABLED_TAIL_LINES = 40;
+
 // Parity with TmuxProcess (R2-F1 / G5b) and SdkProcess: strip C0 control
 // chars + DEL before injecting. Allows \t (0x09) and \n (0x0a) through.
 // Same regex as `lib/tmux/tmux-runner.js` CONTROL_CHAR_RE — keep in sync.
@@ -357,6 +389,11 @@ class CliProcess extends Process {
     // watchdog. Dedups within MID_TURN_DEDUP_WINDOW_MS so a lingering dialog
     // doesn't trigger sendControl/emit on every 5s poll.
     this.midTurnDialogLastFiredAt = new Map();   // patternName → ts
+    // AUTH_DISABLED two-consecutive-poll debounce (docs/AUTH_DISABLED_DETECTION_
+    // SPEC.md): true once AUTH_DISABLED_RE matched on the immediately-prior poll.
+    // Reset to false on any poll where it doesn't match — an accumulating
+    // counter would let non-consecutive false-positive sightings add up.
+    this._authDisabledArmed = false;
     // Review F#16: secondary content-hash dedup. The tool_call_id cache above
     // catches retries that reuse the same id, but Claude's bridge generates a
     // NEW tool_call_id per retry (channels-bridge.mjs:230). If the daemon's
@@ -4005,17 +4042,88 @@ class CliProcess extends Process {
     }
   }
 
+  /**
+   * docs/AUTH_DISABLED_DETECTION_SPEC.md: reject every currently-pending
+   * turn with err.code = 'AUTH_DISABLED' once the pane watchdog confirms
+   * Anthropic has disabled Claude subscription access for this account.
+   * Mirrors resetSession's drain shape (cli-process.js resetSession,
+   * ~line 3697) — match-and-reject pendingQueue entries by turnId rather
+   * than _handleBridgeDisconnected's blunt `pendingQueue.length = 0`
+   * truncation, which would leak orphaned promises. Does NOT kill the tmux
+   * session or clear claudeSessionId (mirrors TURN_TIMEOUT, not
+   * resetSession) — whether to notify an operator, pause the chat, or wait
+   * for the org to re-enable access is a downstream-consumer policy
+   * decision, not this shared engine's to make.
+   */
+  _rejectPendingTurnsAuthDisabled() {
+    const makeErr = () => {
+      const err = new Error(
+        'Claude subscription access has been disabled for this account — ' +
+        'the operator needs to re-enable Claude Code access or switch to an API key',
+      );
+      err.code = 'AUTH_DISABLED';
+      return err;
+    };
+    const channelsTurnIds = new Set();
+    let drained = 0;
+    for (const [turnId, pending] of this.pendingTurns) {
+      channelsTurnIds.add(turnId);
+      drained++;
+      if (pending.quietTimer) clearTimeout(pending.quietTimer);
+      if (pending.hardTimer) clearTimeout(pending.hardTimer);
+      if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
+      if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
+      if (pending._activityQuietTimer) clearTimeout(pending._activityQuietTimer);
+      if (pending._onStop) this.off('stop-hook', pending._onStop);
+      try { pending.reject(makeErr()); } catch {}
+    }
+    this.pendingTurns.clear();
+
+    const remaining = [];
+    for (const item of this.pendingQueue) {
+      if (item.turnId && channelsTurnIds.has(item.turnId)) continue;
+      remaining.push(item);
+    }
+    this.pendingQueue.length = 0;
+    for (const item of remaining) {
+      drained++;
+      try { item.clearTimers?.(); } catch {}
+      try { item.reject?.(makeErr()); } catch {}
+    }
+
+    this.inFlight = false;
+    // Step E parity (resetSession/fireTimeout/_finalizeTurn): emit 'idle'
+    // BEFORE the detection event so a wired HeartbeatReactor stops cycling.
+    if (drained > 0) this.emit('idle');
+    this.emit('auth-disabled-detected', {
+      sessionId: this.claudeSessionId,
+      backend: this.backend,
+      drainedPendings: drained,
+    });
+    this._logEvent('cli-auth-disabled-detected', { drained_pendings: drained });
+    return drained;
+  }
+
   async _pollMidTurnDialogs() {
-    if (this.closed) return;
-    if (this.pendingTurns.size === 0) return;        // no work to do when idle
+    // AUTH_DISABLED_TAIL_LINES/_authDisabledArmed note: every early-return
+    // guard below resets the arm flag. The two-consecutive-poll debounce
+    // (docs/AUTH_DISABLED_DETECTION_SPEC.md) only means anything if "armed"
+    // reflects the IMMEDIATELY PRECEDING poll actually re-observing the same
+    // still-pending turn's pane. Without these resets, a turn that armed the
+    // flag and then resolved normally (pendingTurns.size hits 0, this method
+    // starts early-returning) would leave the flag stuck true — a later,
+    // unrelated turn's very first poll could then falsely "confirm" against
+    // that stale arm instead of its own second observation.
+    if (this.closed) { this._authDisabledArmed = false; return; }
+    if (this.pendingTurns.size === 0) { this._authDisabledArmed = false; return; }        // no work to do when idle
     // 0.12 interactive questions: while an `ask` is open claude sits idle at the
     // prompt waiting on the tool result — so the pane shows no "esc to interrupt"
     // and the question's own echoed text (a "?"/numbered list/"Yes/No") would
     // false-trip the unknown-prompt heuristic + starve the STALL heartbeat. The
     // keyboard lives on Telegram; suppress the pane watchdog while a question is open.
-    if (this._openQuestions.size > 0) return;
-    if (!this.tmuxSession) return;                   // pre-spawn / post-kill
-    if (typeof this.runner?.captureWide !== 'function') return;
+    if (this._openQuestions.size > 0) { this._authDisabledArmed = false; return; }
+    if (!this.tmuxSession) { this._authDisabledArmed = false; return; }                   // pre-spawn / post-kill
+    if (typeof this.runner?.captureWide !== 'function') { this._authDisabledArmed = false; return; }
 
     let pane;
     try {
@@ -4024,10 +4132,33 @@ class CliProcess extends Process {
       // captureWide can fail if tmux died, session got renamed, etc. Log
       // once at warn (rate-limited by the outer pong loop's cadence) and
       // return — pong watchdog will eventually trip on the real symptom.
+      // A failed capture didn't actually re-observe the pane, so it can't
+      // count as a consecutive confirmation either way.
       this.logger.warn?.(`[${this.label}] channels: mid-turn captureWide failed: ${err.message}`);
+      this._authDisabledArmed = false;
       return;
     }
-    if (!pane) return;
+    if (!pane) { this._authDisabledArmed = false; return; }
+
+    // docs/AUTH_DISABLED_DETECTION_SPEC.md: checked first (most severe
+    // signal) and against a BOUNDED TAIL, not the full ~1000-line pane —
+    // see AUTH_DISABLED_TAIL_LINES for why. Two consecutive matching polls
+    // required before acting; a single match only arms.
+    const authDisabledTail = pane.split('\n').slice(-AUTH_DISABLED_TAIL_LINES).join('\n');
+    if (AUTH_DISABLED_RE.test(authDisabledTail)) {
+      if (this._authDisabledArmed) {
+        this._authDisabledArmed = false;
+        this.logger.warn?.(
+          `[${this.label}] cli: AUTH_DISABLED detected (confirmed on 2 consecutive polls) — ` +
+          `rejecting ${this.pendingTurns.size} pending turn(s)`,
+        );
+        this._rejectPendingTurnsAuthDisabled();
+        return;   // skip the rest of this poll — pendingTurns is now empty
+      }
+      this._authDisabledArmed = true;
+    } else if (this._authDisabledArmed) {
+      this._authDisabledArmed = false;
+    }
 
     // rc.14: removed the rc.11 pane-based "dead bridge" detection here. It
     // matched the BENIGN banner "server:water-bridge  no MCP server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shumkov/orchestra",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Drive interactive Claude Code CLI sessions: spawn, inject messages via the MCP channels bridge, observe turns, recover. The transport-agnostic session engine extracted from polygram, shared by polygram (Telegram) and water (WhatsApp).",
   "type": "commonjs",
   "main": "index.js",