@spzxg/cli-ui 0.6.1 → 0.6.5

package/src/operator/node/navHistory.ts

@@ -0,0 +1,70 @@
+// Browser-history mechanics for the mobile projects → tasks → session panes,
+// kept pure (no React, no globals) so the Back-button behaviour can be unit-tested.
+//
+// Why a "trap" instead of one-entry-per-level: the live task list re-selects the
+// open task on every background refresh, so selTask churns null↔id constantly.
+// Any scheme that pushes a history entry when the selection gets *deeper* turns
+// that churn into a pile of duplicate session entries, and Back can never escape
+// them (the original "back acts very strange / does nothing" bug on prod).
+//
+// Instead we keep at most ONE "trap" entry on top whenever a detail pane is open.
+// Arming is keyed on the BOOLEAN "is a pane open" (isDeep), which selTask churn
+// does not change — so churn only ever rewrites the current entry's URL, never
+// adds entries. Back consumes the trap; the app then closes exactly one level
+// (closeOneLevel) and re-arms, so Back walks session → tasks → projects → exit.
+import type { View } from "./types";
+
+export interface NavSel {
+  proj: string | null;
+  task: string | null;
+  view: View;
+}
+
+// Minimal slice of window.history this logic needs — lets tests pass a fake.
+export interface HistoryLike {
+  readonly state: unknown;
+  pushState(state: unknown, unused: string, url: string): void;
+  replaceState(state: unknown, unused: string, url: string): void;
+}
+
+export function selectionUrl(sel: NavSel, pathname: string): string {
+  const q = new URLSearchParams();
+  if (sel.proj) q.set("project", sel.proj);
+  if (sel.task) q.set("task", sel.task);
+  if (sel.view === "settings" || sel.view === "insights") q.set("view", sel.view);
+  const s = q.toString();
+  return s ? `?${s}` : pathname;
+}
+
+// Deeper than the projects list? i.e. a detail pane (a project's task list, an
+// open task, or settings) is showing and Back should close it rather than leave.
+export const isDeep = (sel: NavSel): boolean => !!sel.proj || sel.view === "settings" || sel.view === "insights";
+
+const trapArmed = (h: HistoryLike): boolean =>
+  !!(h.state && (h.state as { trap?: unknown }).trap);
+
+// Keep the URL mirrored to the current selection (so a refresh lands back where
+// you were) and, when `armTrap`, ensure exactly one trap entry sits on top while
+// a pane is open. armTrap is the caller's "is mobile" gate — on desktop all
+// columns are visible at once, so Back should not hijack to close a panel.
+export function reconcileHistory(h: HistoryLike, pathname: string, sel: NavSel, armTrap: boolean): void {
+  const url = selectionUrl(sel, pathname);
+  const armed = trapArmed(h);
+  if (armTrap && isDeep(sel) && !armed) {
+    // Entering a detail pane from a non-trap entry: arm the single trap.
+    h.pushState({ trap: true }, "", url);
+  } else {
+    // Already armed (pane open — incl. selTask churn), or shallow/desktop: just
+    // mirror the URL onto the current entry, preserving the trap flag.
+    h.replaceState({ trap: armed }, "", url);
+  }
+}
+
+// One Back press closes the deepest open level. Returns the selection to apply;
+// at the projects root it returns the input unchanged (Back then leaves the app).
+export function closeOneLevel(sel: NavSel): NavSel {
+  if (sel.view === "settings" || sel.view === "insights") return { ...sel, view: "workspace" };
+  if (sel.task) return { ...sel, task: null };
+  if (sel.proj) return { ...sel, proj: null };
+  return sel;
+}

package/src/operator/node/persist.ts

@@ -0,0 +1,26 @@
+// localStorage + URL persistence for the open project/task, layout and prefs.
+import type { Appearance, Layout, Settings, TaskView } from "./types";
+
+export const LS = "orchestrator_ui_v2";
+
+type Persisted = { selProj?: string; selTask?: string; appearance?: Partial<Appearance>; layout?: Layout; settings?: Settings; taskView?: TaskView };
+
+export function loadPersist(): Persisted {
+  if (typeof window === "undefined") return {};
+  try {
+    // `appearance` used to be called `tweaks` — read the legacy key so an existing
+    // install keeps its theme/density across the rename (dropped fields are ignored
+    // by the DEFAULT_APPEARANCE spread at the call site).
+    const raw = JSON.parse(localStorage.getItem(LS) || "{}") as Persisted & { tweaks?: Partial<Appearance> };
+    if (!raw.appearance && raw.tweaks) raw.appearance = raw.tweaks;
+    return raw;
+  } catch { return {}; }
+}
+
+// The open project/task live in the URL query (?project=…&task=…) so a refresh
+// lands back where you were and the view is shareable. URL wins over localStorage.
+export function readUrlSel(): { project?: string; task?: string; view?: string } {
+  if (typeof window === "undefined") return {};
+  const q = new URLSearchParams(window.location.search);
+  return { project: q.get("project") ?? undefined, task: q.get("task") ?? undefined, view: q.get("view") ?? undefined };
+}

package/src/operator/node/protocol/agents/optIn.ts

@@ -0,0 +1,9 @@
+// Agents that run only when explicitly chosen (task / project default / app
+// default). Connecting one never retargets existing work: implicit fallbacks
+// (firstConnectedAgent, the new-task default, the "connect another agent"
+// nudge) skip them. Dependency-free so server and client code can both import it.
+export const OPT_IN_AGENTS: readonly string[] = ["grok", "pi"];
+
+export function isOptInAgent(id: string | null | undefined): boolean {
+  return !!id && OPT_IN_AGENTS.includes(id);
+}

package/src/operator/node/protocol/agents/types.ts

@@ -0,0 +1,394 @@
+// The agent-driver seam. The app never talks to a specific coding agent
+// directly — every call site resolves an AgentDriver through
+// lib/agents/registry.ts (keyed by tasks.agent / projects.default_agent) and
+// speaks this interface. Adding an agent (Codex, Gemini, …) is a new driver
+// module + a registry entry, with no edits to the runner, routes, or UI data
+// flow — the same swappable-seam pattern as lib/billing/ and
+// lib/control-plane/provisioner/.
+
+import type { Project, Task, StreamEvent, TurnUsage } from "../types";
+
+export type { StreamEvent };
+
+// One selectable model in a driver's picker. `value` is what's persisted in
+// tasks.model (null there = inherit the driver's default); `contextWindow` is
+// the model's token window, driving the context-occupancy gauge. `group` is an
+// optional section heading — drivers with long lists (Claude Code offers a
+// dozen-plus pins) split them so the picker stays scannable; consecutive
+// options sharing a group render under one header.
+export interface AgentModelOption {
+  value: string;
+  label: string;
+  sub: string; // short picker subtitle, e.g. "most capable"
+  contextWindow: number;
+  group?: string;
+}
+
+// A reasoning preset / permission mode a driver supports. `value` is what's
+// persisted in tasks.reasoning / tasks.permission_mode (null = driver default).
+export interface AgentPickerOption {
+  value: string;
+  label: string;
+  sub: string;
+}
+
+/**
+ * What a driver can do, as data. Exposed to the client (GET /api/agents) so
+ * the UI renders model/reasoning/permission pickers and gates features
+ * (asks, cost display, resume) from the descriptor instead of hardcoding
+ * per-agent knowledge.
+ */
+export interface AgentCapabilities {
+  models: AgentModelOption[];
+  reasoningOptions: AgentPickerOption[];
+  permissionModes: AgentPickerOption[];
+  /** Can surface interactive AskUserQuestion-style prompts mid-turn ("ask" events). */
+  supportsAsks: boolean;
+  /** Can mount the orchestrator's MCP tools (suggest_task / expose_service). */
+  supportsMcpTools: boolean;
+  /** Usage events carry a real dollar cost (not just token counts). */
+  reportsCostUsd: boolean;
+  /**
+   * The dollar cost in usage events is an ESTIMATE (token counts × published
+   * API prices) rather than a billed amount — set by drivers whose auth
+   * reports tokens only (Codex on a ChatGPT plan). The UI shows the figure
+   * with an ~ and labels it estimated. Mutually exclusive with reportsCostUsd.
+   */
+  costIsEstimated: boolean;
+  /** Turns can resume a prior session/thread id (tasks.session_id). */
+  supportsResume: boolean;
+  /**
+   * Absolute path to the CLI binary this driver spawns, when the app PINS one
+   * (Claude Code: CLAUDE_CLI_PATH, passed to the SDK as
+   * pathToClaudeCodeExecutable). A pinned path is also an installability test:
+   * the SDK does NOT fall back to PATH, so a missing file means every turn on
+   * this agent dies with "native binary not found" — see isAgentInstalled() in
+   * lib/agents/capabilities.ts, which is what keeps agent resolution from
+   * picking an agent that cannot possibly run. null/undefined = the driver
+   * resolves its own executable (bundled with its SDK, or found on PATH), so
+   * installation isn't knowable from here and the agent counts as installed.
+   */
+  cliPath?: string | null;
+  /** The driver accepts a user-supplied model id in addition to its catalog. */
+  supportsCustomModels?: boolean;
+  /** Claude Code can use Amazon Bedrock instead of Anthropic-hosted auth. */
+  supportsBedrock?: boolean;
+  /**
+   * Placeholder for the "I have an API key instead" field, e.g. "sk-ant-…".
+   * null = this agent has no per-token API-key path (subscription login only),
+   * so the client hides the api-key toggle.
+   */
+  apiKeyHint: string | null;
+  /**
+   * How the subscription login completes, so the generic connect UI knows what
+   * to render: "paste_code" — the user pastes an authorization code back into
+   * the app (Claude); "device_code" — the app shows a one-time code the user
+   * enters in the browser, then polls until it lands (Codex).
+   */
+  loginStyle: "paste_code" | "device_code";
+  /**
+   * Replaces the connect card's default "you'll get a login link" copy, for an
+   * agent whose sign-in happens outside Operator (Pi: /login in its own TUI).
+   * Unset = the default copy.
+   */
+  loginHint?: string;
+  /** The driver fronts many model providers and exposes `providers` (per-provider
+   *  logins, API keys, custom endpoints) — the connect card renders that panel. */
+  supportsProviderAuth?: boolean;
+}
+
+// ---------- per-provider auth (an agent that fronts many model providers) ----------
+// Pi talks to 40+ providers, each with its own OAuth and/or API-key login, plus
+// user-defined endpoints. One "connect" button can't cover that, so such a
+// driver exposes this optional surface and the UI lists providers to manage.
+// Secrets only ever flow IN (prompt answers, endpoint keys); nothing here
+// returns a credential value.
+
+export interface AgentProviderEndpoint {
+  baseUrl: string;
+  api: string | null;
+  models: string[];
+  contextWindow: number | null;
+  reasoning: boolean;
+  /** The config file itself carries a key (set outside Operator). */
+  inlineKey: boolean;
+}
+
+export interface AgentProviderInfo {
+  id: string;
+  name: string;
+  /** Usable credentials from any source (stored login, env var, config file). */
+  configured: boolean;
+  /** Where the working credential comes from, as the agent reports it. */
+  source: string | null;
+  authType: "api_key" | "oauth" | null;
+  /** A credential in the agent's own store — what logout removes. */
+  credential: "api_key" | "oauth" | null;
+  /** Models usable right now through this provider. */
+  models: number;
+  apiKey: { name: string; canLogin: boolean } | null;
+  oauth: { name: string; label: string | null; subscription: boolean } | null;
+  /** Ships with the agent (vs. a user-defined endpoint). */
+  builtin: boolean;
+  /** A built-in provider pointed at another address (gateway / proxy), plus model ids added for it. */
+  override: { baseUrl: string | null; models: string[] } | null;
+  /** A user-defined endpoint; null for built-in providers. */
+  endpoint: AgentProviderEndpoint | null;
+}
+
+/** "Fill in an API key" for a provider, optionally through another address. */
+export interface AgentProviderKeyInput {
+  /** Omit to keep the stored key (e.g. only changing the address). */
+  key?: string;
+  /** Empty = the provider's official address. */
+  baseUrl?: string;
+  /** Extra model ids the address serves (gateways often rename models). */
+  models?: string[];
+}
+
+export interface AgentProviderEndpointInput {
+  id: string;
+  name?: string;
+  baseUrl: string;
+  api: string;
+  models: string[];
+  contextWindow?: number;
+  reasoning?: boolean;
+  /** Optional; stored through the agent's own credential store, never in the config file. */
+  apiKey?: string;
+}
+
+/** Something the provider's login flow wants the user to see. */
+export type AgentLoginEvent =
+  | { type: "info"; message: string; links?: { url: string; label?: string }[] }
+  | { type: "auth_url"; url: string; instructions?: string }
+  | { type: "device_code"; userCode: string; verificationUri: string; expiresInSeconds?: number }
+  | { type: "progress"; message: string };
+
+/** Something the provider's login flow needs the user to answer. */
+export type AgentLoginPrompt = { id: string } & (
+  | { type: "text" | "secret" | "manual_code"; message: string; placeholder?: string }
+  | { type: "select"; message: string; options: { id: string; label: string; description?: string }[] }
+);
+
+export interface AgentProviderLogin {
+  provider: string;
+  type: "oauth" | "api_key";
+  status: "running" | "success" | "error" | "cancelled";
+  events: AgentLoginEvent[];
+  /** The question the flow is waiting on, if any. */
+  prompt: AgentLoginPrompt | null;
+  error: string | null;
+}
+
+export interface AgentProviderAuth {
+  list(): Promise<{ providers: AgentProviderInfo[]; error: string | null }>;
+  startLogin(provider: string, type: "oauth" | "api_key"): Promise<AgentProviderLogin>;
+  getLogin(): AgentProviderLogin | null;
+  answer(promptId: string, value: string): Promise<AgentProviderLogin | null>;
+  cancelLogin(): void;
+  /** Save an API key (and optional address override). Returns the login flow when a key
+   *  was given — it may still ask follow-up questions — or null when only the address changed. */
+  saveKey(provider: string, input: AgentProviderKeyInput): Promise<AgentProviderLogin | null>;
+  /** Remove the provider's stored credential. */
+  logout(provider: string): Promise<void>;
+  saveEndpoint(input: AgentProviderEndpointInput): Promise<{ backup: string | null }>;
+  removeEndpoint(id: string): Promise<{ backup: string | null }>;
+}
+
+// ---------- auth surface (shape after lib/claude-auth.ts) ----------
+
+export interface AgentAuthStatus {
+  authenticated: boolean;
+  method: string | null; // how the account is signed in (raw provider text)
+  email: string | null;
+  plan: string | null;
+  error: string | null;
+  /** Underlying API provider when the CLI reports it (for example "bedrock"). */
+  provider?: string | null;
+}
+
+// A headless device-style login in progress (start → awaiting code → success).
+export interface AgentLoginSession {
+  status: "starting" | "awaiting" | "submitting" | "success" | "error";
+  url: string | null; // the authorize URL for the user to open
+  code?: string | null; // device-code drivers: the one-time code to enter in the browser
+  email: string | null;
+  plan: string | null;
+  error: string | null;
+  log: string; // tail of the login terminal output, for the UI's pane
+}
+
+// ---------- account quota (the "how much have I got left" surface) ----------
+
+/** A rate-limit window's duration, named where it's one of the common ones. */
+export type AgentQuotaWindowKind = "hourly" | "5h" | "daily" | "weekly" | "monthly" | "custom";
+
+/** One metered window on the account (a plan can meter several at once, e.g. a
+ *  5-hour burst cap alongside a weekly cap, and per model family). */
+export interface AgentQuotaWindow {
+  /** The provider's bucket id, e.g. "codex" — stable, unlike the label. */
+  limitId: string | null;
+  /** Human name when the provider gives one, else the bucket id. */
+  label: string | null;
+  /** Which of the bucket's two windows this is, as the provider ordered them. */
+  scope: "primary" | "secondary";
+  kind: AgentQuotaWindowKind;
+  windowMinutes: number | null;
+  /** Pre-rendered duration ("1 周", "5 小时") so callers don't re-derive it. */
+  windowLabel: string | null;
+  usedPercent: number;
+  remainingPercent: number;
+  /** Epoch MS (the app's unit; providers often report seconds). */
+  resetsAt: number | null;
+  resetsInMs: number | null;
+  /** This particular window is spent. */
+  reached: boolean;
+}
+
+/** Who the quota belongs to, so a multi-account instance can tell them apart. */
+export interface AgentQuotaAccount {
+  /** How the account authenticates, e.g. "chatgpt" | "apiKey" | "amazonBedrock". */
+  authType: string;
+  email: string | null;
+  plan: string | null;
+}
+
+/**
+ * An account's live quota state — the AUTHORITATIVE answer to "am I out?",
+ * as opposed to lib/usageLimit.ts, which can only pattern-match a provider's
+ * error text and so cannot distinguish a spent plan from a transient 429.
+ * A driver that can't read its provider's quota simply omits `quota()`.
+ */
+export interface AgentQuota {
+  account: AgentQuotaAccount | null;
+  plan: string | null;
+  /** The provider says a limit is actually reached — not merely a 429. */
+  exhausted: boolean;
+  /** The provider's own reason code when it declared a limit reached. */
+  reachedType: string | null;
+  /** A spend control (not a rate limit) is what stopped the account. */
+  spendControlReached: boolean;
+  /** The most-consumed weekly window — the headline "周额度". */
+  weekly: AgentQuotaWindow | null;
+  /** Every metered window, including the one surfaced as `weekly`. */
+  limits: AgentQuotaWindow[];
+  credits: { hasCredits: boolean; unlimited: boolean; balance: string | null } | null;
+  /** One-off "reset my limit early" credits the account holds, when reported. */
+  resetCreditsAvailable: number | null;
+  totals: {
+    lifetimeTokens: number | null;
+    peakDailyTokens: number | null;
+    longestRunningTurnSec: number | null;
+    currentStreakDays: number | null;
+    longestStreakDays: number | null;
+  } | null;
+  daily: { date: string; tokens: number }[] | null;
+  fetchedAt: number;
+  /** Populated instead of the figures when the quota couldn't be read. */
+  error: string | null;
+}
+
+export interface AgentVerifyResult {
+  ok: boolean;
+  output: string;
+  error: string | null;
+}
+
+export interface OneShotResult {
+  text: string;
+  usage?: TurnUsage;
+}
+
+/**
+ * The "I have an API key instead" alternative to the subscription login, as a
+ * small surface a driver optionally provides (mirrors lib/anthropic-key.ts /
+ * lib/openai-key.ts). The key is persisted to a 0600 file on the volume and
+ * mirrored into process.env so the agent's children bill per-token against it.
+ * Drivers without a per-token path simply omit `apiKey`.
+ */
+export interface AgentApiKeyAuth {
+  /** Placeholder for the input, e.g. "sk-ant-…". Also surfaced via capabilities.apiKeyHint. */
+  hint: string;
+  /** Loose shape check; the real validation is the verify turn working. */
+  looksValid(key: string): boolean;
+  /** Whether a key is currently persisted. */
+  has(): boolean;
+  /** Persist + apply the key. */
+  set(key: string): void;
+  /** Forget the key. */
+  clear(): void;
+}
+
+/**
+ * A pluggable coding-agent backend.
+ *
+ * `runTurn` is THE contract: one user turn in, a stream of normalized
+ * StreamEvents out (session/model/assistant/tool/tool_result/ask/ask_answered/
+ * suggested/usage/notice/error/done — see lib/types.ts). Drivers normalize
+ * their native event stream into it; everything downstream (lib/runner.ts
+ * persistence + publish, the SSE tail, the UI) is agent-agnostic.
+ *
+ * The session/thread id a driver reports via "session"/"done" events is opaque
+ * to the app — it's stored in tasks.session_id / sessions.claude_session_id
+ * and handed back verbatim on resume (a Codex thread id fits the same column).
+ */
+export interface AgentDriver {
+  id: string; // persisted in tasks.agent / projects.default_agent
+  label: string; // human name, e.g. "Claude Code"
+  capabilities: AgentCapabilities;
+  /** Instance-wide provider selected outside Operator, when applicable. */
+  configuredProvider?(): string | null;
+  /** Whether the configured provider's credentials can be refreshed from the
+   *  UI via the login surface (e.g. an AWS SSO device-code flow). Drives the
+   *  refresh button in the connect card and gates POST /api/agents/[id]/login
+   *  when a third-party provider is active. */
+  providerAuthRefreshable?(): boolean;
+
+  /**
+   * Run one user turn. Resumes task.session_id when set, otherwise starts a
+   * fresh session seeded with the project context. `abort` (the Stop button)
+   * must end the stream without emitting an error event.
+   */
+  runTurn(task: Task, project: Project, userText: string, abort?: AbortController): AsyncGenerator<StreamEvent>;
+
+  // ---------- one-shot helpers (no session, text in → text out) ----------
+  //
+  // All three are OPTIONAL: a driver can ship runTurn() alone and the app
+  // backstops the missing helper with the configured utility agent (see
+  // lib/agents/oneshots.ts). summarizeTranscript is task-scoped (runs on the
+  // task's own agent so the work bills the right login); draft/recap are
+  // project-scoped and run on the utility agent.
+
+  /** Condense a session transcript into a handoff note for the /clear flow. */
+  summarizeTranscript?(transcript: string, project: Project): Promise<OneShotResult>;
+  /** Draft a fresh "what we're building" context by exploring the repo (read-only). */
+  draftProjectContext?(project: Project, digest: string): Promise<OneShotResult>;
+  /** Short "where you left off" recap from a recent-activity digest. */
+  summarizeProjectRecap?(project: Project, digest: string): Promise<OneShotResult>;
+
+  // ---------- auth (the setup wizard's connect / verify flow) ----------
+
+  /** Whether the agent's CLI/SDK is signed in, and as whom. */
+  authStatus(): Promise<AgentAuthStatus>;
+  /** Start (or rejoin) a headless login; resolves once the authorize URL is known. */
+  startLogin(): Promise<AgentLoginSession>;
+  /** The in-progress login, if any (for the UI's poll loop). */
+  getLogin(): AgentLoginSession | null;
+  /** Hand the pasted authorization code to the waiting login. */
+  submitLoginCode(code: string): Promise<AgentLoginSession>;
+  /** Abandon an in-progress login. */
+  cancelLogin(): void;
+  /** Prove the connection works by running a real one-shot test turn. */
+  verify(): Promise<AgentVerifyResult>;
+  /**
+   * The account's live quota / usage, when the provider exposes it. Optional:
+   * a driver without it means the app falls back to error-text classification
+   * (lib/usageLimit.ts) alone.
+   */
+  quota?(): Promise<AgentQuota>;
+  /** The per-token API-key path, if this agent supports one (else undefined). */
+  apiKey?: AgentApiKeyAuth;
+  /** Per-provider auth management (see AgentProviderAuth); with capabilities.supportsProviderAuth. */
+  providers?: AgentProviderAuth;
+}

package/src/operator/node/protocol/approvalFailure.ts

@@ -0,0 +1,77 @@
+// Detection + recovery constants for the "Codex's approval policy blocked the
+// turn" failure mode.
+//
+// Operator runs Codex through `codex exec` (via @openai/codex-sdk), which is
+// non-interactive: nobody can answer a command-approval prompt mid-turn. So the
+// driver asks for `approval_policy=never` (the auto-run analog of Claude's
+// bypassPermissions). Two configurations defeat that and produce the same
+// baffling failure:
+//
+//   1. Enterprise-managed Codex requirements disallow `never`. The CLI warns
+//      ("Configured value for `approval_policy` is disallowed by requirements;
+//      falling back to required value UnlessTrusted") and silently downgrades.
+//      Under UnlessTrusted every non-allowlisted command needs an approval that
+//      exec mode cannot service — codex_core rejects each one ("approval
+//      request failed"), and the agent flails through its tools with no
+//      explanation.
+//   2. The user's own ~/.codex/config.toml sets an approval-requiring policy
+//      and Operator runs with CODEX_APPROVAL_POLICY=inherit.
+//
+// The downgrade warning arrives as an error item on the very first affected
+// turn (lib/agents/codex/events.ts maps it to a StreamEvent error), so the
+// Codex driver matches it there and flips an instance-wide flag that makes it
+// request the exec-compatible "on-request" policy from the next turn on
+// (self-healing, no user action). This module classifies the failure for
+// lib/runner.ts — same pattern as lib/promptLimits.ts / lib/authFailure.ts —
+// which appends APPROVAL_BLOCKED_NOTICE so the UI can render a one-click Retry.
+// Kept dependency-free so both server and client bundles can import it.
+
+/** The CLI's managed-requirements downgrade warning — the signal that the
+ *  approval policy Operator asked for was rejected and a stricter one applies.
+ *  Matched by the Codex driver to trigger auto-negotiation. */
+const APPROVAL_DOWNGRADE_RES = [
+  /approval_policy[^\n]{0,80}disallowed by requirements/i,
+  /disallowed by requirements[^\n]{0,120}approval_policy/i,
+  /invalid value for [`'"]?approval_policy[`'"]?[^\n]{0,80}not in the allowed set/i,
+];
+
+/** True when an error is the CLI's "your approval_policy was rejected by
+ *  managed requirements, falling back to a stricter value" warning. */
+export function isApprovalDowngrade(msg: string | null | undefined): boolean {
+  return !!msg && APPROVAL_DOWNGRADE_RES.some((re) => re.test(msg));
+}
+
+// The rejections codex_core emits when an approval-requiring policy meets exec
+// mode's inability to ask anyone:
+//   - "command execution approval is not supported in exec mode for thread …"
+//   - "exec_command failed …: Rejected(\"approval request failed\")"
+//   - "approval policy is UnlessTrusted; reject command — you cannot ask for
+//     escalated permissions if the approval policy is UnlessTrusted"
+const APPROVAL_BLOCKED_RES = [
+  ...APPROVAL_DOWNGRADE_RES,
+  /approval request failed/i,
+  /approval policy is \w+; reject/i,
+  /(?:command execution )?approval is not supported in exec mode/i,
+  /cannot ask for escalated permissions/i,
+];
+
+/** True when a turn's error text is an approval-policy rejection (the managed
+ *  downgrade warning, or exec mode failing to service an approval) rather than
+ *  a work failure. */
+export function isApprovalBlocked(msg: string | null | undefined): boolean {
+  return !!msg && APPROVAL_BLOCKED_RES.some((re) => re.test(msg));
+}
+
+/** Appended to the persisted error line when a turn is blocked by the approval
+ *  policy. The UI (app/orchestrator/Transcript.tsx) matches this exact string
+ *  to render the "Retry" button — the driver has already switched future turns
+ *  to the exec-compatible "on-request" policy by the time anyone reads this, so
+ *  resending the same message is the recovery. Persisted message content is the
+ *  durable channel — it survives SSE reconnects because the snapshot replays
+ *  from SQLite. */
+export const APPROVAL_BLOCKED_NOTICE =
+  "智能体的审批策略拦截了这一轮：它要求交互式命令审批，而 " +
+  "Operator 的无人值守会话无法提供。Operator 现已为其 Codex 会话改用兼容的 'on-request' " +
+  "策略，因此重试这条消息通常就能通过。（如果你使用了 " +
+  "CODEX_APPROVAL_POLICY=inherit，请在 ~/.codex/config.toml 中改为设置一个与 exec 兼容的 " +
+  "approval_policy，例如 \"on-request\"。）";

package/src/operator/node/protocol/authFailure.ts

@@ -0,0 +1,66 @@
+// Detection + recovery constants for the "your agent login stopped working"
+// failure mode.
+//
+// An expired OAuth session is invisible until you send a turn, and then it looks
+// like a code problem: the raw provider string ("Failed to authenticate: OAuth
+// session expired and could not be refreshed") lands in ONE task's transcript,
+// while every other task on the instance is equally dead — same CLI, same
+// credentials on disk. Worse, each queued follow-up would dequeue and fail the
+// same way, emptying the queue for nothing.
+//
+// So an auth failure is classified here (agent-agnostically — Codex phrases it
+// differently and fails identically), which lets lib/runner.ts append
+// AUTH_EXPIRED_NOTICE for a one-click reconnect, park the queue instead of
+// burning it, and flag the agent instance-wide (lib/agents/connections.ts) so
+// the app can say so in the titlebar rather than only inside the task that
+// happened to run first. Kept dependency-free so both server and client bundles
+// can import it (same rule as lib/promptLimits.ts).
+
+// Each agent CLI/SDK words a dead credential differently, and the recovery
+// ("reconnect this agent") is identical for all of them:
+//   - Claude Code:  "Failed to authenticate: OAuth session expired and could
+//     not be refreshed"; API-key path: "invalid x-api-key" / 401.
+//   - Codex: "not logged in", "please run codex login", "401 Unauthorized".
+//   - Either provider's raw HTTP rejection: 401 + authentication_error.
+// The 401/403 patterns require a nearby auth word so an unrelated error that
+// merely contains a status code can't trip the banner.
+const AUTH_FAILURE_RES = [
+  /failed to authenticate/i,
+  /authentication (?:failed|error|required)/i,
+  /could not be refreshed/i,
+  /(?:oauth|login|access|refresh) (?:session|token)[^.\n]{0,40}(?:expired|revoked|invalid|refresh)/i,
+  /(?:session|token|credentials?)[^.\n]{0,30}(?:has |have |is |are )?(?:expired|revoked)/i,
+  /invalid[_ ]grant/i,
+  /invalid[^.\n]{0,20}(?:api[- ]?key|x-api-key|credentials?|token)/i,
+  /(?:api[- ]?key|credentials?)[^.\n]{0,30}(?:invalid|expired|revoked|missing|not found)/i,
+  /\bnot (?:logged in|authenticated|signed in)\b/i,
+  /(?:re-?authenticate|re-?login|log ?in again|sign ?in again)/i,
+  /run [`'"]?(?:claude|codex)(?: auth)? login/i,
+  /\b40[13]\b[^\n]{0,60}(?:unauthorized|forbidden|authentication|invalid|expired|api[- ]?key)/i,
+  /(?:unauthorized|forbidden)[^\n]{0,40}\b40[13]\b/i,
+  /unable to locate (?:aws )?credentials/i,
+  /aws default-chain credential resolve (?:timed out|failed)/i,
+  /(?:ExpiredToken|InvalidClientTokenId|UnrecognizedClientException)/i,
+  /(?:aws|sso)[^.\n]{0,30}(?:credentials?|session|token)[^.\n]{0,30}(?:expired|invalid|missing)/i,
+];
+
+/** True when a turn's error text is a dead-credential rejection (expired OAuth
+ *  session, revoked token, bad/missing API key) rather than a work failure. */
+export function isAuthFailure(msg: string | null | undefined): boolean {
+  return !!msg && AUTH_FAILURE_RES.some((re) => re.test(msg));
+}
+
+/** Appended to the persisted error line when a turn dies on authentication. The
+ *  UI (app/orchestrator/Transcript.tsx) matches this exact string to render the
+ *  "Reconnect" button, so it must stay agent-neutral — the client already knows
+ *  the task's agent and labels the button with it. Persisted message content is
+ *  the durable channel: it survives SSE reconnects because the snapshot replays
+ *  from SQLite. */
+export const AUTH_EXPIRED_NOTICE =
+  "该智能体的连接已失效 —— 登录凭据过期、被撤销或不可用，" +
+  "在你重新连接或刷新之前无法运行任何轮次。没有任何内容丢失：本次会话及其 " +
+  "worktree 均未受影响，排队中的消息也仍在队列里。";
+
+/** The one-line, instance-wide version of the same news, for the titlebar banner
+ *  (app/orchestrator/AgentConnect.tsx → AgentAuthBanner). */
+export const AUTH_BANNER_HINT = "在凭据刷新之前，任何会话都无法运行。";