airaknit 1.1.2-rc.9

package/src/runner/turn-factories.ts

@@ -0,0 +1,475 @@
+/**
+ * Turn factory wrappers for the runner process.
+ *
+ * Re-exports startClaudeTurn from claude-harness.ts and provides
+ * startCodexTurn / startClaudePtyTurn so the runner can create harness turns
+ * for all providers.
+ *
+ * Lifecycle ownership for claude-pty:
+ *   • `claudePtySessions` — module-level Map<chatId, ClaudePtySession>.
+ *     Mirrors kanna's `claudeSessions` map. PTY handle persists across
+ *     turns so the live `claude` CLI keeps in-memory context.
+ *   • `OAuthTokenPool` — single instance constructed in `runner.ts` and
+ *     handed to the factory at boot. `pickActive(chatId)` reserves a token
+ *     for the chat; `release(chatId)` drops it on turn end / session close.
+ *     `markLimited` / `markError` rotate the token on rate_limit / stream
+ *     error events. Mirrors kanna's `AgentCoordinator` rotation discipline.
+ *   • `ClaudePtyRegistry` — on-disk pidfile registry. Driver writes its pid
+ *     + runtimeDir before sending the first prompt and unregisters during
+ *     cleanup. Boot's `reapStale()` SIGKILLs orphans from a previous crash.
+ *   • Idle sweeper — `sweepIdleClaudePtySessions(now, idleMs)` closes any
+ *     session whose `lastUsedAt` is past the TTL. Scheduled from runner.ts
+ *     so the runner controls cadence + can `unref()` the timer.
+ */
+
+export { startClaudeTurn } from "../server/claude-harness"
+
+import { CodexAppServerManager } from "../server/codex-app-server"
+import type { HarnessToolRequest, HarnessTurn } from "../shared/harness-types"
+import type { CodexReasoningEffort, ServiceTier } from "../shared/types"
+import { startClaudeSessionPTY, type PtyUsageSample } from "../server/claude-pty/driver"
+import { ptyDeltaSubject } from "../shared/nats-subjects"
+import { compressPayload } from "../shared/compression"
+import type { NatsConnection } from "@nats-io/transport-node"
+import type { PtyInstanceDelta, PtyInstanceState } from "../shared/pty-instance"
+import type { HarnessEvent } from "../shared/harness-types"
+import type { ClaudeSessionHandle } from "../server/claude-pty/agent-normalizers"
+import type { OAuthTokenPool } from "../server/oauth-pool/oauth-token-pool"
+import type { ClaudePtyRegistry } from "../server/claude-pty/pid-registry.adapter"
+import { spawnSync } from "node:child_process"
+
+const ptyDeltaEncoder = new TextEncoder()
+function encodeDelta(delta: PtyInstanceDelta): Uint8Array {
+  return compressPayload(ptyDeltaEncoder.encode(JSON.stringify(delta)))
+}
+
+interface ClaudePtySession {
+  chatId: string
+  handle: ClaudeSessionHandle
+  baseInstance: PtyInstanceState
+  currentTurn: TurnDispatcher | null
+  turnCount: number
+  /** Pool reservation id; null when no pool was available (test/fake paths). */
+  activeTokenId: string | null
+  /** Timestamp of the last turn end (or session start). Used by idle sweeper. */
+  lastUsedAt: number
+  publishDelta: (delta: PtyInstanceDelta) => void
+  /** Stops further onUsageSample deltas (called once the session is torn down). */
+  stopUsage: () => void
+}
+
+interface TurnDispatcher {
+  push(event: HarnessEvent): void
+  end(): void
+  stream: AsyncIterable<HarnessEvent>
+}
+
+function createTurnDispatcher(): TurnDispatcher {
+  const queue: HarnessEvent[] = []
+  const waiters: Array<(r: IteratorResult<HarnessEvent>) => void> = []
+  let ended = false
+
+  function push(event: HarnessEvent): void {
+    if (ended) return
+    const waiter = waiters.shift()
+    if (waiter) waiter({ value: event, done: false })
+    else queue.push(event)
+  }
+
+  function end(): void {
+    if (ended) return
+    ended = true
+    while (waiters.length > 0) {
+      const waiter = waiters.shift()
+      if (waiter) waiter({ value: undefined as unknown as HarnessEvent, done: true })
+    }
+  }
+
+  const stream: AsyncIterable<HarnessEvent> = {
+    [Symbol.asyncIterator]() {
+      return {
+        next(): Promise<IteratorResult<HarnessEvent>> {
+          if (queue.length > 0) {
+            const value = queue.shift() as HarnessEvent
+            return Promise.resolve({ value, done: false })
+          }
+          if (ended) return Promise.resolve({ value: undefined as unknown as HarnessEvent, done: true })
+          return new Promise((resolve) => waiters.push(resolve))
+        },
+      }
+    },
+  }
+
+  return { push, end, stream }
+}
+
+const claudePtySessions = new Map<string, ClaudePtySession>()
+
+// Single pool + registry instance shared across all turns. Set by runner.ts at boot.
+let sharedPool: OAuthTokenPool | null = null
+let sharedRegistry: ClaudePtyRegistry | null = null
+
+export function configureClaudePtyFactory(args: {
+  pool: OAuthTokenPool | null
+  registry: ClaudePtyRegistry | null
+}): void {
+  sharedPool = args.pool
+  sharedRegistry = args.registry
+}
+
+function startSessionReader(session: ClaudePtySession): void {
+  void (async () => {
+    // `poolRotated` mirrors pty-responders semantics: when rate_limit /
+    // stream error marks the token limited/errored, the pool's
+    // `takeStaleOwners` already drops the reservation for this chat. The
+    // finally{} block must skip its plain `release(chatId)` in that case
+    // so it does not touch unrelated tokens (audit #9d).
+    let poolRotated = false
+    try {
+      for await (const event of session.handle.stream) {
+        if (event.type === "rate_limit" && event.rateLimit) {
+          console.log("[claude-pty/runner] rate_limit chatId=" + session.chatId, event.rateLimit)
+          if (session.activeTokenId && sharedPool) {
+            try {
+              const stale = sharedPool.takeStaleOwners(session.activeTokenId)
+              sharedPool.markLimited(session.activeTokenId, event.rateLimit.resetAt)
+              poolRotated = true
+              console.log(
+                "[claude-pty/runner] pool token " + session.activeTokenId
+                + " marked limited until " + event.rateLimit.resetAt
+                + "; stale owners=" + stale.length,
+              )
+            } catch (err) {
+              console.warn(
+                "[claude-pty/runner] markLimited failed token=" + session.activeTokenId,
+                err instanceof Error ? err.message : String(err),
+              )
+            }
+          }
+        }
+        session.currentTurn?.push(event)
+        const entry = (event as { entry?: { kind?: string } }).entry
+        if (entry?.kind === "result") {
+          session.lastUsedAt = Date.now()
+          session.currentTurn?.end()
+          session.currentTurn = null
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      console.warn("[claude-pty/runner] session reader error:", message)
+      if (session.activeTokenId && sharedPool) {
+        try {
+          const stale = sharedPool.takeStaleOwners(session.activeTokenId)
+          sharedPool.markError(session.activeTokenId, message)
+          poolRotated = true
+          console.log(
+            "[claude-pty/runner] pool token " + session.activeTokenId
+            + " marked error; stale owners=" + stale.length,
+          )
+        } catch (markErr) {
+          console.warn(
+            "[claude-pty/runner] markError failed token=" + session.activeTokenId,
+            markErr instanceof Error ? markErr.message : String(markErr),
+          )
+        }
+      }
+    } finally {
+      session.stopUsage()
+      session.currentTurn?.end()
+      if (claudePtySessions.get(session.chatId) === session) {
+        claudePtySessions.delete(session.chatId)
+      }
+      if (!poolRotated && session.activeTokenId && sharedPool) {
+        try { sharedPool.release(session.chatId) } catch { /* swallow */ }
+      }
+      session.publishDelta({ type: "removed", chatId: session.chatId })
+    }
+  })()
+}
+
+export function stopClaudePtySession(chatId: string): void {
+  const session = claudePtySessions.get(chatId)
+  if (!session) return
+  try { session.handle.close() } catch { /* swallow */ }
+  // Map entry + pool release will be cleared by the background reader's
+  // finally{} block once the stream observes the close. Delete eagerly so
+  // a racing `start_turn` for the same chatId does not reuse this handle.
+  claudePtySessions.delete(chatId)
+}
+
+export function stopAllClaudePtySessions(): void {
+  for (const [, session] of claudePtySessions) {
+    try { session.handle.close() } catch { /* swallow */ }
+  }
+  claudePtySessions.clear()
+}
+
+/** Test-only inspector for the live session map. */
+export function getClaudePtySessionChatIds(): string[] {
+  return [...claudePtySessions.keys()]
+}
+
+/**
+ * Close any session whose `lastUsedAt` is older than `idleMs` and has no
+ * active turn. Mirrors kanna's `sweepIdleClaudeSessions`. Runs from a
+ * setInterval in runner.ts; the runner owns timer cadence.
+ */
+export function sweepIdleClaudePtySessions(now: number, idleMs: number): number {
+  let closed = 0
+  for (const [chatId, session] of [...claudePtySessions.entries()]) {
+    if (session.currentTurn !== null) continue
+    if (now - session.lastUsedAt < idleMs) continue
+    console.log("[claude-pty/runner] idle TTL eviction chatId=" + chatId + " idleMs=" + (now - session.lastUsedAt))
+    try { session.handle.close() } catch { /* swallow */ }
+    claudePtySessions.delete(chatId)
+    closed += 1
+  }
+  return closed
+}
+
+let codexManager: CodexAppServerManager | null = null
+
+/**
+ * Resolve the codex binary runner-side by checking PATH, then falling back to
+ * the well-known `codex` name (lets the shell find it via the runner's PATH).
+ * Always runner-local — never relies on a server-sent binaryPath.
+ */
+function resolveCodexBinary(extraEnv?: Record<string, string>): string {
+  // Runner-local resolution: NEVER let a server-supplied PATH redirect which
+  // binary we run (security M1) — strip PATH so the runner's own PATH decides.
+  const { PATH: _serverPath, ...safeEnv } = extraEnv ?? {}
+  const env = { ...process.env, ...safeEnv }
+  const which = spawnSync("which", ["codex"], { encoding: "utf-8", timeout: 3000, env })
+  if (which.status === 0) {
+    const p = which.stdout.trim()
+    if (p) return p
+  }
+  // Fall back: let the OS resolve it at spawn time
+  return "codex"
+}
+
+// NOTE: the codex manager is a once-per-runner-lifetime singleton — the first
+// turn's (PATH-stripped) extraEnv fixes the manager. The binary is always
+// runner-local (PATH stripped above), so this cannot be steered by the server.
+function getCodexManager(extraEnv?: Record<string, string>): CodexAppServerManager {
+  if (!codexManager) {
+    // Strip server-supplied PATH from the spawned process env too (M1).
+    const { PATH: _serverPath, ...safeEnv } = extraEnv ?? {}
+    const binaryPath = resolveCodexBinary(safeEnv)
+    codexManager = new CodexAppServerManager({ binaryPath, extraEnv: safeEnv })
+  }
+  return codexManager
+}
+
+export async function startCodexTurn(args: {
+  chatId: string
+  content: string
+  localPath: string
+  model: string
+  effort?: string
+  serviceTier?: "fast"
+  planMode: boolean
+  sessionToken: string | null
+  onToolRequest: (request: HarnessToolRequest) => Promise<unknown>
+  extraEnv?: Record<string, string>
+}): Promise<HarnessTurn> {
+  const manager = getCodexManager(args.extraEnv)
+
+  await manager.startSession({
+    chatId: args.chatId,
+    cwd: args.localPath,
+    model: args.model,
+    serviceTier: args.serviceTier as ServiceTier | undefined,
+    sessionToken: args.sessionToken,
+  })
+
+  return await manager.startTurn({
+    chatId: args.chatId,
+    content: args.content,
+    model: args.model,
+    effort: args.effort as CodexReasoningEffort | undefined,
+    serviceTier: args.serviceTier as ServiceTier | undefined,
+    planMode: args.planMode,
+    onToolRequest: args.onToolRequest,
+  })
+}
+
+function buildPoolUnavailableMessage(reservedFor: string): string {
+  if (!sharedPool) return "OAuth pool is not configured on the runner."
+  if (!sharedPool.hasAnyToken()) {
+    return "No OAuth pool tokens configured. Add one under Settings → Claude PTY."
+  }
+  const summary = sharedPool
+    .describeUnavailability(reservedFor)
+    .filter((u) => u.reason !== "available")
+    .map((u) => (u.label || u.tokenId.slice(0, 8)) + ": " + u.reason)
+    .join("; ")
+  return "No usable OAuth pool token (" + (summary || "all tokens unavailable") + ")."
+}
+
+export async function startClaudePtyTurn(args: {
+  chatId: string
+  content: string
+  projectId?: string
+  localPath: string
+  model: string
+  effort?: string
+  planMode: boolean
+  sessionToken: string | null
+  onToolRequest: (request: HarnessToolRequest) => Promise<unknown>
+  nc?: NatsConnection
+}): Promise<HarnessTurn> {
+  let session = claudePtySessions.get(args.chatId)
+
+  if (!session) {
+    if (!sharedPool) {
+      throw new Error("Claude PTY runner is not wired to an OAuthTokenPool. Configure via configureClaudePtyFactory().")
+    }
+    if (!sharedPool.hasAnyToken()) {
+      throw new Error("No OAuth pool tokens configured. Add one under Settings → Claude PTY.")
+    }
+    const picked = sharedPool.pickActive(args.chatId)
+    if (!picked) {
+      throw new Error(buildPoolUnavailableMessage(args.chatId))
+    }
+    sharedPool.markUsed(picked.id)
+
+    const now = Date.now()
+    const baseInstance: PtyInstanceState = {
+      chatId: args.chatId,
+      sessionId: null,
+      pid: null,
+      cwd: args.localPath,
+      model: args.model,
+      accountLabel: picked.label,
+      oauthMasked: null,
+      phase: "spawning",
+      startedAt: now,
+      lastEventAt: now,
+      turnCount: 0,
+      tokensIn: 0,
+      tokensOut: 0,
+      planMode: args.planMode,
+      smokeTest: null,
+      outputRingTail: null,
+      exitedAt: null,
+      exitCode: null,
+      rssBytes: null,
+      rssPeakBytes: null,
+      cpuPercent: null,
+      cpuPeakPercent: null,
+    }
+
+    function publishDelta(delta: PtyInstanceDelta): void {
+      if (!args.nc) return
+      try {
+        args.nc.publish(ptyDeltaSubject(), encodeDelta(delta))
+      } catch (err) {
+        console.warn("[claude-pty/runner] pty.delta publish failed:", err instanceof Error ? err.message : String(err))
+      }
+    }
+
+    publishDelta({ type: "added", instance: baseInstance })
+
+    // `baseInstance` is the canonical, mutable record for this session: phase
+    // transitions and usage samples both write into it so every published
+    // delta stays internally coherent. `usageStopped` suppresses late sampler
+    // ticks (spawn-failure or post-teardown) that would otherwise resurrect a
+    // removed instance in the client store.
+    let usageStopped = false
+    const onUsageSample = (usage: PtyUsageSample): void => {
+      if (usageStopped) return
+      baseInstance.rssBytes = usage.rssBytes
+      baseInstance.rssPeakBytes = usage.rssPeakBytes
+      baseInstance.cpuPercent = usage.cpuPercent
+      baseInstance.cpuPeakPercent = usage.cpuPeakPercent
+      baseInstance.lastEventAt = Date.now()
+      publishDelta({ type: "updated", instance: { ...baseInstance } })
+    }
+
+    let handle: ClaudeSessionHandle
+    try {
+      handle = await startClaudeSessionPTY({
+        chatId: args.chatId,
+        projectId: args.projectId ?? args.chatId,
+        localPath: args.localPath,
+        model: args.model,
+        effort: args.effort,
+        planMode: args.planMode,
+        sessionToken: args.sessionToken,
+        forkSession: false,
+        oauthToken: picked.token,
+        oauthLabel: picked.label,
+        ptyRegistry: sharedRegistry ?? undefined,
+        onUsageSample,
+        onToolRequest: args.onToolRequest as never,
+      })
+    } catch (err) {
+      usageStopped = true
+      publishDelta({ type: "removed", chatId: args.chatId })
+      try { sharedPool.release(args.chatId) } catch { /* swallow */ }
+      throw err
+    }
+
+    baseInstance.phase = "ready"
+    baseInstance.lastEventAt = Date.now()
+    publishDelta({ type: "updated", instance: { ...baseInstance } })
+
+    session = {
+      chatId: args.chatId,
+      handle,
+      baseInstance,
+      currentTurn: null,
+      turnCount: 0,
+      activeTokenId: picked.id,
+      lastUsedAt: Date.now(),
+      publishDelta,
+      stopUsage: () => { usageStopped = true },
+    }
+    claudePtySessions.set(args.chatId, session)
+    startSessionReader(session)
+  }
+
+  const dispatcher = createTurnDispatcher()
+  session.currentTurn = dispatcher
+  session.turnCount += 1
+  session.lastUsedAt = Date.now()
+  session.baseInstance.phase = "streaming"
+  session.baseInstance.lastEventAt = Date.now()
+  session.baseInstance.turnCount = session.turnCount
+  session.publishDelta({ type: "updated", instance: { ...session.baseInstance } })
+
+  await session.handle.sendPrompt(args.content)
+
+  return {
+    provider: "claude-pty",
+    stream: dispatcher.stream,
+    interrupt: async () => {
+      try {
+        await session!.handle.interrupt()
+      } finally {
+        dispatcher.end()
+        if (session!.currentTurn === dispatcher) {
+          session!.currentTurn = null
+          session!.lastUsedAt = Date.now()
+        }
+      }
+    },
+    close: () => {
+      dispatcher.end()
+      if (session!.currentTurn === dispatcher) {
+        session!.currentTurn = null
+        session!.lastUsedAt = Date.now()
+      }
+    },
+  }
+}
+
+export function stopCodexSession(chatId: string): void {
+  codexManager?.stopSession(chatId)
+}
+
+export function stopAllCodexSessions(): void {
+  codexManager?.stopAll()
+}

package/src/server/agent-config-journey.test.ts

@@ -0,0 +1,106 @@
+import { describe, test, expect, afterEach } from "bun:test"
+import { EventStore } from "./event-store"
+import { deriveAgentConfigSnapshot } from "./read-models"
+import type { AgentConfig } from "../shared/agent-config-types"
+import { rmSync, mkdirSync } from "node:fs"
+import { join } from "node:path"
+
+const TEST_DIR = join(import.meta.dir, ".test-agent-config-journey")
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true })
+})
+
+async function createStoreWithProject() {
+  mkdirSync(TEST_DIR, { recursive: true })
+  const store = new EventStore(TEST_DIR)
+  await store.initialize()
+  const project = await store.openProject("/tmp/agent-config-journey-test", "AgentConfigJourney")
+  return { store, workspaceId: project.id }
+}
+
+function makeConfig(overrides: Partial<AgentConfig> = {}): AgentConfig {
+  return {
+    id: "cfg-1",
+    name: "Test Agent",
+    description: "A test agent config",
+    provider: "claude",
+    model: "claude-sonnet-4-20250514",
+    ...overrides,
+  }
+}
+
+describe("agent config journey", () => {
+  test("stage 3: save agent config appears in snapshot", async () => {
+    const { store, workspaceId } = await createStoreWithProject()
+    const config = makeConfig()
+
+    await store.saveAgentConfig(workspaceId, config.id, config)
+
+    const snapshot = deriveAgentConfigSnapshot(store.state, workspaceId)
+    expect(snapshot.workspaceId).toBe(workspaceId)
+    expect(snapshot.configs).toHaveLength(1)
+    expect(snapshot.configs[0].id).toBe(config.id)
+    expect(snapshot.configs[0].config.name).toBe("Test Agent")
+    expect(snapshot.configs[0].config.provider).toBe("claude")
+    expect(snapshot.configs[0].workspaceId).toBe(workspaceId)
+  })
+
+  test("stage 4: update agent config (save again) updates in snapshot", async () => {
+    const { store, workspaceId } = await createStoreWithProject()
+    const config = makeConfig()
+
+    await store.saveAgentConfig(workspaceId, config.id, config)
+    await new Promise((r) => setTimeout(r, 5))
+    const updated = makeConfig({ name: "Updated Agent", model: "claude-opus-4-20250514" })
+    await store.saveAgentConfig(workspaceId, config.id, updated)
+
+    const snapshot = deriveAgentConfigSnapshot(store.state, workspaceId)
+    expect(snapshot.configs).toHaveLength(1)
+    expect(snapshot.configs[0].config.name).toBe("Updated Agent")
+    expect(snapshot.configs[0].config.model).toBe("claude-opus-4-20250514")
+    expect(snapshot.configs[0].updatedAt).toBeGreaterThan(snapshot.configs[0].createdAt)
+  })
+
+  test("stage 5: remove agent config disappears from snapshot", async () => {
+    const { store, workspaceId } = await createStoreWithProject()
+    const config = makeConfig()
+
+    await store.saveAgentConfig(workspaceId, config.id, config)
+    expect(deriveAgentConfigSnapshot(store.state, workspaceId).configs).toHaveLength(1)
+
+    await store.removeAgentConfig(workspaceId, config.id)
+    const snapshot = deriveAgentConfigSnapshot(store.state, workspaceId)
+    expect(snapshot.configs).toHaveLength(0)
+  })
+
+  test("agent config survives compact and replay", async () => {
+    const { store, workspaceId } = await createStoreWithProject()
+    const config = makeConfig({ id: "cfg-persist", name: "Persistent Agent" })
+
+    await store.saveAgentConfig(workspaceId, config.id, config)
+    const before = deriveAgentConfigSnapshot(store.state, workspaceId)
+    expect(before.configs).toHaveLength(1)
+
+    await store.compact()
+
+    const store2 = new EventStore(TEST_DIR)
+    await store2.initialize()
+
+    const after = deriveAgentConfigSnapshot(store2.state, workspaceId)
+    expect(after.configs).toHaveLength(1)
+    expect(after.configs[0].id).toBe("cfg-persist")
+    expect(after.configs[0].config.name).toBe("Persistent Agent")
+    expect(after.configs[0].config.provider).toBe("claude")
+    expect(after.configs[0].workspaceId).toBe(workspaceId)
+  })
+
+  test("empty workspace returns empty configs", async () => {
+    const { store, workspaceId } = await createStoreWithProject()
+
+    const snapshot = deriveAgentConfigSnapshot(store.state, workspaceId)
+    expect(snapshot.workspaceId).toBe(workspaceId)
+    expect(snapshot.configs).toHaveLength(0)
+    expect(snapshot.lastUpdated).toBe(new Date(0).toISOString())
+  })
+})

package/src/server/agent.ts

@@ -0,0 +1,8 @@
+/**
+ * Backward-compatible re-exports.
+ *
+ * AgentCoordinator was removed — all turn execution is delegated to the
+ * runner process via RunnerProxy.  Only the shared transcript helpers
+ * survive, now canonical in src/shared/transcript-entries.ts.
+ */
+export { timestamped, discardedToolResult } from "../shared/transcript-entries"

package/src/server/auto-continue/auth-error-detector.ts

@@ -0,0 +1,66 @@
+export interface AuthErrorDetection {
+  chatId: string
+  reason: string
+  raw: unknown
+}
+
+interface ErrorLike {
+  message?: string
+  status?: number
+  api_error_status?: number
+}
+
+// Strings the Claude CLI / Anthropic API emit when an OAuth token is
+// rejected. Covers both the JSON error envelope (`authentication_error`)
+// and the CLI's surfaced result text (`Failed to authenticate.`). The
+// `api_error_status: 401` form appears in JSONL `result` entries from
+// the CLI when subscription auth fails.
+const AUTH_ERROR_PATTERNS = [
+  /api_error_status[^,}]*\s*:\s*401/i,
+  /401\s+Invalid authentication credentials/i,
+  /Failed to authenticate\.\s*API Error:\s*401/i,
+  /"type"\s*:\s*"authentication_error"/i,
+  /"error"\s*:\s*"authentication_failed"/i,
+] as const
+
+function isAuthErrorText(text: string): boolean {
+  return AUTH_ERROR_PATTERNS.some((pattern) => pattern.test(text))
+}
+
+export class ClaudeAuthErrorDetector {
+  /**
+   * Inspect a thrown error (from the SDK `query()` stream) for OAuth/auth
+   * failure signals. Returns a detection when the token used for the
+   * spawn has been rejected by the API — caller should mark the token as
+   * errored and rotate.
+   */
+  detect(chatId: string, error: unknown): AuthErrorDetection | null {
+    if (!error) return null
+    const e = error as ErrorLike
+    if (e.status === 401 || e.api_error_status === 401) {
+      return { chatId, reason: this.summarize(e.message), raw: error }
+    }
+    const message = typeof e.message === "string" ? e.message : null
+    if (message && isAuthErrorText(message)) {
+      return { chatId, reason: this.summarize(message), raw: error }
+    }
+    return null
+  }
+
+  /**
+   * Inspect the textual `result` field of a CLI JSONL `result` entry
+   * (Claude Code's subprocess-level error surface). The CLI emits
+   * `"api_error_status":401` and `"Failed to authenticate. API Error: 401
+   * Invalid authentication credentials"` for OAuth rejection.
+   */
+  detectFromResultText(chatId: string, text: string): AuthErrorDetection | null {
+    if (typeof text !== "string" || text.length === 0) return null
+    if (!isAuthErrorText(text)) return null
+    return { chatId, reason: this.summarize(text), raw: text }
+  }
+
+  private summarize(message: string | undefined): string {
+    if (!message) return "401 authentication error"
+    return message.length > 200 ? `${message.slice(0, 200)}…` : message
+  }
+}