@iislee/opencodex 2.11.0

package/src/claude/agents-inject.ts

@@ -0,0 +1,243 @@
+/**
+ * Claude Code custom-agent definition injection (devlog 260712 070).
+ *
+ * The Agent tool's `model` argument is a hard 4-alias enum (2.1.207 binary), but an
+ * agent DEFINITION's frontmatter `model:` is a free string ("Model alias this agent
+ * uses. If omitted, inherits the parent's model"). So we sync the featured
+ * subagent roster (config.subagentModels, <=5) plus the main model (when not
+ * already covered) into ~/.claude/agents/ocx-*.md — one dispatchable
+ * `subagent_type` per routed model, loaded at the next session start.
+ *
+ * Ownership contract: this module only creates/overwrites/deletes files matching
+ * `ocx-*.md` inside the agents dir. User-authored agents are never touched.
+ */
+import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { OcxConfig } from "../types";
+import { claudeCodeAlias, claudeCodeNativeAlias } from "./alias";
+import { resolveAutoContext, stripOneMillionMarker, withOneMillionMarker } from "./context-windows";
+import { claudeConfigDir } from "./gateway-cache";
+import { DEFAULT_SUBAGENT_MODELS, hasOwnProvider } from "../config";
+import { effectiveBlockedSkillNames, resolveInboundModel } from "./inbound";
+import { knownModelIdsForProvider } from "../router";
+import { decodeRoutedModelId } from "../providers/slug-codec";
+
+export interface ClaudeAgentDef {
+  file: string;
+  name: string;
+  model: string;
+  description: string;
+  effort?: NonNullable<OcxConfig["claudeCode"]>["subagentEffort"];
+  blockedSkills: readonly string[];
+}
+
+const OWNED_PREFIX = "ocx-";
+/** Ownership proof (audit 071 #2): a file without this marker is NEVER touched. */
+const GENERATED_MARKER = "generated-by: opencodex";
+
+function sanitizeName(value: string): string {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned.length > 0 ? cleaned : "model";
+}
+
+/**
+ * The user's default model as saved by the /model picker (settings.json `model`).
+ * `model: "inherit"` in agent frontmatter is DISPROVEN on 2.1.207 (live: a
+ * no-model ocx-self dispatch fell back to claude-fable-5 — devlog 072), so the
+ * self-clone pins this value instead, refreshed at every launch-time sync.
+ */
+function pickerDefaultModel(configDir: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(join(configDir, "settings.json"), "utf8")) as Record<string, unknown>;
+    return typeof parsed.model === "string" && parsed.model.trim() !== "" ? parsed.model.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Roster entry -> alias + display parts. Entries are bare native slugs or "provider/id".
+ * Codex-facing encoded ids (`provider/vendor-model`) decode to the native slash id first
+ * so the alias joins the raw-native context-window map (context-windows.ts). */
+function entryParts(entry: string, config: OcxConfig): { alias: string; id: string; provider: string } {
+  const slash = entry.indexOf("/");
+  if (slash > 0) {
+    const provider = entry.slice(0, slash);
+    const prov = hasOwnProvider(config.providers, provider) ? config.providers[provider] : undefined;
+    const id = prov
+      ? decodeRoutedModelId(entry.slice(slash + 1), knownModelIdsForProvider(provider, prov))
+      : entry.slice(slash + 1);
+    return { alias: claudeCodeAlias(provider, id), id, provider };
+  }
+  return { alias: claudeCodeNativeAlias(entry), id: entry, provider: "native" };
+}
+
+export function buildClaudeAgentDefs(config: OcxConfig, windows: Record<string, number>, configDir = claudeConfigDir()): ClaudeAgentDef[] {
+  const auto = resolveAutoContext(config.claudeCode);
+  const blockedSkills = effectiveBlockedSkillNames(config.claudeCode);
+  const blockedSkillsFor = (model: string): readonly string[] => {
+    const unmarked = stripOneMillionMarker(model);
+    const nativePassthrough = config.claudeCode?.nativePassthrough !== false
+      && !unmarked.includes("/")
+      && /^(claude|anthropic)(?:-|$)/i.test(unmarked)
+      && resolveInboundModel(unmarked, config.claudeCode) === unmarked;
+    return nativePassthrough ? [] : blockedSkills;
+  };
+  const defs: ClaudeAgentDef[] = [];
+  const usedNames = new Set<string>();
+  const coveredModels = new Set<string>();
+
+  const push = (name: string, alias: string, description: string) => {
+    // Effective model value: [1m] marking follows the same predicate as env slots.
+    const model = withOneMillionMarker(alias, windows, auto) ?? alias;
+    const bare = alias.toLowerCase();
+    if (coveredModels.has(bare)) return;
+    coveredModels.add(bare);
+    let unique = name;
+    for (let i = 2; usedNames.has(unique); i++) unique = `${name}-${i}`;
+    usedNames.add(unique);
+    defs.push({
+      file: `${OWNED_PREFIX}${unique}.md`,
+      name: `${OWNED_PREFIX}${unique}`,
+      model,
+      description,
+      effort: config.claudeCode?.subagentEffort,
+      blockedSkills: blockedSkillsFor(model),
+    });
+  };
+
+  // Default roster applies only when the field is UNSET — an explicit [] is
+  // respected (audit 071 #6: an upgraded config must not lose the default five).
+  const roster = config.subagentModels === undefined ? DEFAULT_SUBAGENT_MODELS : config.subagentModels;
+  for (const entry of roster.slice(0, 5)) {
+    if (typeof entry !== "string" || entry.trim() === "") continue;
+    const { alias, id, provider } = entryParts(entry.trim(), config);
+    push(sanitizeName(id), alias, `Delegate work to ${id} (${provider}) via opencodex routing. General-purpose worker/explorer on that model. ${NO_MODEL_ARG}`);
+  }
+
+  // Self-clone slot: pin the picker-saved default (settings.json), falling back to
+  // config.claudeCode.model. `inherit` is NOT honored by 2.1.207 (live-disproven,
+  // devlog 072); a session started with a divergent --model stays divergent until
+  // the next launch sync — documented limit. No resolvable default -> no self def.
+  const selfModel = pickerDefaultModel(configDir) ?? (config.claudeCode?.model?.trim() || null);
+  if (selfModel) {
+    const marked = withOneMillionMarker(selfModel, windows, auto) ?? selfModel;
+    defs.push({
+      file: `${OWNED_PREFIX}self.md`,
+      name: `${OWNED_PREFIX}self`,
+      model: marked,
+      description: `Self-clone: delegate to your default main model (${marked}), synced from the /model picker at launch. ${NO_MODEL_ARG}`,
+      effort: config.claudeCode?.subagentEffort,
+      blockedSkills: blockedSkillsFor(marked),
+    });
+  }
+  return defs;
+}
+
+function skillNameLiteral(name: string): string {
+  return JSON.stringify(name)
+    .replaceAll("`", "\\u0060")
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e");
+}
+
+function renderAgentDef(def: ClaudeAgentDef): string {
+  const blockedSkillGuard = def.blockedSkills.length === 0 ? [] : [
+    "",
+    `Do not invoke blocked Claude Code skills: ${def.blockedSkills.map(skillNameLiteral).join(", ")}.`,
+    "Their document bundles are intentionally omitted for routed models; continue without loading them.",
+  ];
+  // YAML frontmatter: model ids carry dots/brackets — always double-quote scalars.
+  return [
+    "---",
+    `name: ${JSON.stringify(def.name)}`,
+    `description: ${JSON.stringify(def.description)}`,
+    `model: ${JSON.stringify(def.model)}`,
+    ...(def.effort ? [`effort: ${JSON.stringify(def.effort)}`] : []),
+    "---",
+    "",
+    `<!-- ${GENERATED_MARKER} -->`,
+    // Proxy routing directive (devlog 072): 2.1.207 does not honor custom gateway
+    // ids in agent frontmatter (falls back to sonnet — live-proven), but the agent
+    // BODY rides the subagent's system prompt verbatim. The proxy detects this
+    // directive and overrides the request model before routing/passthrough.
+    `<!-- ocx-route: ${def.model} -->`,
+    ...(def.effort ? [`<!-- ocx-effort: ${def.effort} -->`] : []),
+    "",
+    `You are a delegated worker running on \`${def.model}\` through the local opencodex proxy.`,
+    `IDENTITY: your ACTUAL underlying model is \`${def.model}\` — the opencodex proxy routes this`,
+    "session there regardless of what model name the Claude Code harness displays or claims.",
+    "If asked which model you are, answer with the id above; do not guess a Claude model name.",
+    ...blockedSkillGuard,
+    "",
+    "Complete the dispatched task directly and report results concisely. This file is",
+    "auto-generated by opencodex (`ocx claude`) from the featured subagent roster —",
+    "manual edits will be overwritten; remove the model from the roster to drop it.",
+    "",
+  ].join("\n");
+}
+
+/** True only for a REGULAR file we generated (marker present; symlinks never owned). */
+function isOwnedFile(path: string): boolean {
+  try {
+    const st = lstatSync(path);
+    if (!st.isFile()) return false; // symlink or dir: never touch (audit 071 #2)
+    return readFileSync(path, "utf8").includes(GENERATED_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sync owned agent files: write/overwrite current defs, prune stale ocx-*.md,
+ * never touch anything else. Ownership requires the generated marker; writes are
+ * atomic (tmp + rename). Best-effort — returns null on any failure.
+ */
+export function syncClaudeAgentDefs(defs: readonly ClaudeAgentDef[], configDir = claudeConfigDir()): string[] | null {
+  try {
+    const dir = join(configDir, "agents");
+    mkdirSync(dir, { recursive: true });
+    const keep = new Set(defs.map(d => d.file));
+    for (const existing of readdirSync(dir)) {
+      if (!existing.startsWith(OWNED_PREFIX) || !existing.endsWith(".md")) continue;
+      if (!keep.has(existing) && isOwnedFile(join(dir, existing))) {
+        try { unlinkSync(join(dir, existing)); } catch { /* best-effort prune */ }
+      }
+    }
+    const written: string[] = [];
+    for (const def of defs) {
+      const target = join(dir, def.file);
+      // A pre-existing ocx-* file WITHOUT our marker is user property: skip the def.
+      try {
+        lstatSync(target);
+        if (!isOwnedFile(target)) continue;
+      } catch { /* does not exist: ours to create */ }
+      const tmp = `${target}.tmp-${process.pid}`;
+      writeFileSync(tmp, renderAgentDef(def), { encoding: "utf8", mode: 0o644 });
+      renameSync(tmp, target);
+      written.push(def.file);
+    }
+    return written;
+  } catch {
+    return null;
+  }
+}
+
+/** Launch-time hook: gate + build + sync in one call (used by ocx claude and systemEnv). */
+export function injectClaudeAgentDefs(config: OcxConfig, windows: Record<string, number>, configDir?: string): string[] | null {
+  if (config.claudeCode?.enabled === false || config.claudeCode?.injectAgents === false) {
+    // Disabled: prune verified-owned files so stale definitions stop loading
+    // in future sessions (audit 071 #3).
+    return syncClaudeAgentDefs([], configDir);
+  }
+  return syncClaudeAgentDefs(buildClaudeAgentDefs(config, windows, configDir), configDir);
+}
+/**
+ * Dispatcher directive appended to every ocx-* description. The ocx-route body
+ * directive makes the Agent tool's `model` argument INERT (the proxy overrides
+ * the request model before routing — live-proven), so instead of asking the
+ * dispatcher to omit it (which caused schema-anxiety loops), we hand it a fixed
+ * placeholder: any value works; "haiku" is canonical because a haiku-labeled call
+ * is visibly a placeholder in the Claude Code UI, while "sonnet" was
+ * indistinguishable from a genuine Sonnet call (issue #252).
+ */
+const NO_MODEL_ARG = "NOTE: this agent's real model is pinned by the opencodex proxy — the `model` argument is ignored. Pass model: \"haiku\" as a placeholder (or omit it); routing is unaffected either way.";

package/src/claude/alias.ts

@@ -0,0 +1,149 @@
+/**
+ * Gateway model-discovery aliases (devlog/260711_claude_inbound/020, 003 G1-G6).
+ *
+ * Claude Code's /model picker only lists discovery entries whose id literally
+ * begins with `claude` or `anthropic`, so routed models are exposed as
+ * `claude-ocx-<provider>--<model>` with an honest display_name. Aliases must be
+ * deterministic, reversible, and STABLE across releases (picker selections
+ * persist to Claude Code's settings.json `model` field).
+ *
+ * Versioned prefixes:
+ *  - `claude-ocx-` (v1) — legacy / plain model ids with no `/` or `~`. Decode
+ *    is literal (no escape expansion), so a persisted model id that literally
+ *    contained the two-char sequences `~s` / `~t` keeps resolving.
+ *  - `claude-ocx2-` (v2) — used whenever the model id needs escape encoding
+ *    (`/` → `~s`, `~` → `~t`). Decode expands those escapes. New slash/tilde
+ *    models always mint v2 so they cannot collide with v1 literals.
+ *
+ * Reversibility rules:
+ *  - providers containing `--` or `/` are not aliased (split boundary safety);
+ *  - model ids MAY contain `/` or `~` — minted under the v2 prefix with escapes
+ *    (e.g. openrouter `anthropic/claude-opus-4-8` →
+ *    `claude-ocx2-openrouter--anthropic~sclaude-opus-4-8`);
+ *  - model ids MAY contain `--` (resolve splits on the FIRST `--` only);
+ *  - native OpenAI slugs use the pseudo-provider `native` and resolve back to
+ *    the bare slug; a real provider named "native" is therefore never aliased.
+ */
+
+import { desktop3pAlias } from "./desktop-3p";
+
+/** Legacy / plain readable prefix (literal model portion on decode). */
+export const CLAUDE_ALIAS_PREFIX_V1 = "claude-ocx-";
+/** Escape-encoded readable prefix (`~s`/`~t` expanded on decode). */
+export const CLAUDE_ALIAS_PREFIX_V2 = "claude-ocx2-";
+/**
+ * Current write prefix for plain (unescaped) model ids.
+ * Escape-needing models mint {@link CLAUDE_ALIAS_PREFIX_V2} instead.
+ */
+export const CLAUDE_ALIAS_PREFIX = CLAUDE_ALIAS_PREFIX_V1;
+
+/** Encoded `/` inside the model portion of a v2 Claude Code alias. */
+const CLAUDE_ALIAS_SLASH_ENC = "~s";
+/** Encoded literal `~` inside the model portion of a v2 Claude Code alias. */
+const CLAUDE_ALIAS_TILDE_ENC = "~t";
+const NATIVE_PSEUDO_PROVIDER = "native";
+
+function modelNeedsEscapeEncoding(modelId: string): boolean {
+  return modelId.includes("/") || modelId.includes("~");
+}
+
+function encodeModelId(modelId: string): string {
+  // Escape literal tildes first so slash encoding cannot create ambiguity.
+  return modelId
+    .replaceAll("~", CLAUDE_ALIAS_TILDE_ENC)
+    .replaceAll("/", CLAUDE_ALIAS_SLASH_ENC);
+}
+
+function decodeEscapedModelId(encoded: string): string {
+  let out = "";
+  for (let i = 0; i < encoded.length; i++) {
+    if (encoded[i] === "~" && i + 1 < encoded.length) {
+      const next = encoded[i + 1];
+      if (next === "s") {
+        out += "/";
+        i += 1;
+        continue;
+      }
+      if (next === "t") {
+        out += "~";
+        i += 1;
+        continue;
+      }
+    }
+    out += encoded[i];
+  }
+  return out;
+}
+
+function splitAlias(id: string, prefix: string): { provider: string; model: string } | null {
+  const rest = id.slice(prefix.length);
+  const sep = rest.indexOf("--");
+  if (sep <= 0) return null;
+  const provider = rest.slice(0, sep);
+  const model = rest.slice(sep + 2);
+  if (!provider || !model) return null;
+  return { provider, model };
+}
+
+/** Alias for a routed "<provider>/<model>" pair; null when not representable. */
+export function aliasForRoute(provider: string, modelId: string): string | null {
+  if (!provider || provider.includes("--") || provider.includes("/") || provider === NATIVE_PSEUDO_PROVIDER) return null;
+  if (!modelId) return null;
+  if (modelNeedsEscapeEncoding(modelId)) {
+    return `${CLAUDE_ALIAS_PREFIX_V2}${provider}--${encodeModelId(modelId)}`;
+  }
+  return `${CLAUDE_ALIAS_PREFIX_V1}${provider}--${modelId}`;
+}
+
+/** Alias for a native OpenAI slug (bare model id, no provider namespace). */
+export function aliasForNative(slug: string): string | null {
+  // Reject "/" — native ids are bare slugs. Literal `~` is fine via v2 + ~t.
+  if (!slug || slug.includes("/") || slug.includes("--")) return null;
+  if (modelNeedsEscapeEncoding(slug)) {
+    return `${CLAUDE_ALIAS_PREFIX_V2}${NATIVE_PSEUDO_PROVIDER}--${encodeModelId(slug)}`;
+  }
+  return `${CLAUDE_ALIAS_PREFIX_V1}${NATIVE_PSEUDO_PROVIDER}--${slug}`;
+}
+
+/**
+ * Reverse an alias to the inbound model string routeModel understands:
+ * routed -> "<provider>/<model>", native -> bare slug. Null when not an alias.
+ */
+export function resolveAlias(id: string): string | null {
+  // Check v2 before v1 for clarity (prefixes are disjoint: ocx2 vs ocx-).
+  if (id.startsWith(CLAUDE_ALIAS_PREFIX_V2)) {
+    const parts = splitAlias(id, CLAUDE_ALIAS_PREFIX_V2);
+    if (!parts) return null;
+    const model = decodeEscapedModelId(parts.model);
+    if (!model) return null;
+    return parts.provider === NATIVE_PSEUDO_PROVIDER ? model : `${parts.provider}/${model}`;
+  }
+  if (id.startsWith(CLAUDE_ALIAS_PREFIX_V1)) {
+    const parts = splitAlias(id, CLAUDE_ALIAS_PREFIX_V1);
+    if (!parts) return null;
+    // Literal decode — preserves pre-escape aliases whose model id contained
+    // the two-char sequences ~s / ~t.
+    return parts.provider === NATIVE_PSEUDO_PROVIDER ? parts.model : `${parts.provider}/${parts.model}`;
+  }
+  return null;
+}
+
+/**
+ * Claude Code (CLI) surface alias — devlog 050 + audit 051 #2.
+ *
+ * The readable `claude-ocx*` form when representable; otherwise the desktop-3p
+ * hash so the model still appears in discovery (collisions follow the same
+ * first-wins policy as the desktop registry — audit 051 #1). Real Anthropic
+ * models pass through unchanged (they must keep hitting the sk-ant passthrough).
+ * Both families keep decoding forever in resolveInboundModel, so ids persisted
+ * in Claude Code's settings.json never break when the surface style changes.
+ */
+export function claudeCodeAlias(provider: string, modelId: string): string {
+  if (provider === "anthropic" && modelId.startsWith("claude-")) return modelId;
+  return aliasForRoute(provider, modelId) ?? desktop3pAlias(provider, modelId);
+}
+
+/** Claude Code (CLI) surface alias for a native OpenAI slug. */
+export function claudeCodeNativeAlias(slug: string): string {
+  return aliasForNative(slug) ?? desktop3pAlias("native", slug);
+}

package/src/claude/auth-detect.ts

@@ -0,0 +1,229 @@
+/**
+ * Claude auth presence detection.
+ *
+ * THREE values, not two. `unknown` means a source could not be READ (denied keychain,
+ * permission error, corrupt JSON) — treating that as `absent` would silently flip a
+ * subscriber into proxy mode, which is the failure this whole unit exists to prevent
+ * (devlog/_plan/260726_claude_auth_auto/001 F1). The resolver maps unknown to the
+ * historical default (subscription), never to proxy.
+ *
+ * IO is injectable so every source is testable without touching the real home
+ * directory, keychain, or environment.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export type AuthPresence = "present" | "absent" | "unknown";
+
+export type AuthSourceId =
+  | "claude-json-oauth"        // S1: <config-dir>/../.claude.json oauthAccount
+  | "claude-credentials-file"  // S2: <config-dir>/.credentials.json
+  | "macos-keychain"           // S3: security find-generic-password (metadata only)
+  | "exported-env";            // S5: ANTHROPIC_API_KEY / a USER's ANTHROPIC_AUTH_TOKEN
+
+// NOTE: there is deliberately no "opencodex anthropic OAuth" source. That is a
+// PROVIDER credential in opencodex's own store which the Claude CLI never consumes,
+// so it is not evidence the client can authenticate natively (audit 002 §5).
+
+/**
+ * The one opencodex-owned dummy token. Exported so the CLI, the system-env writer and
+ * the tests all compare against the same literal — a second copy is how the marker
+ * feedback loop (002 §1) sneaks back in.
+ */
+export const PROXY_MARKER = "opencodex-proxy";
+
+const KEYCHAIN_SERVICE = "Claude Code-credentials";
+/** `security` exit code for "the item does not exist" — a real absent, not a failure. */
+const KEYCHAIN_ITEM_NOT_FOUND = 44;
+const KEYCHAIN_TIMEOUT_MS = 1_500;
+
+export interface AuthSourceResult {
+  source: AuthSourceId;
+  presence: AuthPresence;
+  /** One short, credential-free line. Never contains token material. */
+  detail?: string;
+}
+
+export interface AuthDetectDeps {
+  /** Parsed ~/.claude.json; undefined when missing; throws on corrupt/unreadable. */
+  readClaudeJson(): Record<string, unknown> | undefined;
+  /** Whether <config-dir>/.credentials.json exists; throws on read error. */
+  credentialsFileExists(): boolean;
+  /** present/absent/unknown for the macOS keychain probe; absent on non-Darwin. */
+  keychainProbe(): AuthPresence;
+  /**
+   * The environment to inspect for S5. Callers pass the SAME base env the launch will
+   * use, so detection and the spawned process can never disagree. Injection is typed
+   * to exclude this key (see `detectClaudeAuth` callers) so a test fake cannot
+   * silently replace the binding.
+   */
+  env(): NodeJS.ProcessEnv;
+  /**
+   * Token values opencodex itself put into the environment. `system-env.ts` exports the
+   * configured admission key as `ANTHROPIC_AUTH_TOKEN`, so without this the detector
+   * reads OUR OWN output back as proof the user can authenticate natively — the same
+   * feedback loop the `PROXY_MARKER` guard closes, one variable over.
+   */
+  ownTokens?: readonly string[];
+}
+
+export interface AuthDetectResult {
+  /** present if ANY source is present; unknown if none present but ANY unknown. */
+  presence: AuthPresence;
+  /** The source that proved presence, when any — feeds the GUI reason badge. */
+  foundBy?: AuthSourceId;
+  sources: AuthSourceResult[];
+  /**
+   * True when the inspected env carries OUR OWN dummy marker. It must never count as
+   * user auth, and a subscription resolution strips it before launch (002 §1).
+   */
+  staleProxyMarker: boolean;
+}
+
+/** Claude Code config dir: `CLAUDE_CONFIG_DIR` override, else `~/.claude`. */
+export function claudeConfigDir(env: NodeJS.ProcessEnv = process.env): string {
+  const explicit = env.CLAUDE_CONFIG_DIR?.trim();
+  return explicit ? explicit : join(homeDir(env), ".claude");
+}
+
+/**
+ * `os.homedir()` reads the OS user database and ignores a reassigned `HOME`, which
+ * makes an isolated-profile probe silently read the real user's files. Prefer the
+ * environment the caller handed us; fall back to the OS value.
+ */
+function homeDir(env: NodeJS.ProcessEnv): string {
+  const fromEnv = env.HOME?.trim() || env.USERPROFILE?.trim();
+  return fromEnv ? fromEnv : homedir();
+}
+
+function detectClaudeJson(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    const parsed = deps.readClaudeJson();
+    if (parsed === undefined) return { source: "claude-json-oauth", presence: "absent" };
+    const account = parsed.oauthAccount;
+    if (account && typeof account === "object" && !Array.isArray(account)) {
+      const email = (account as Record<string, unknown>).emailAddress;
+      if (typeof email === "string" && email.trim().length > 0) {
+        // Never echo the address itself — the detail line is UI copy, not a credential.
+        return { source: "claude-json-oauth", presence: "present", detail: "oauthAccount" };
+      }
+    }
+    return { source: "claude-json-oauth", presence: "absent" };
+  } catch {
+    // Corrupt or unreadable is NOT absent (F1).
+    return { source: "claude-json-oauth", presence: "unknown", detail: "unreadable" };
+  }
+}
+
+function detectCredentialsFile(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    return {
+      source: "claude-credentials-file",
+      presence: deps.credentialsFileExists() ? "present" : "absent",
+    };
+  } catch {
+    return { source: "claude-credentials-file", presence: "unknown", detail: "unreadable" };
+  }
+}
+
+function detectKeychain(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    return { source: "macos-keychain", presence: deps.keychainProbe() };
+  } catch {
+    return { source: "macos-keychain", presence: "unknown", detail: "probe failed" };
+  }
+}
+
+function detectExportedEnv(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    const env = deps.env();
+    const isOwn = (value: string): boolean =>
+      value === PROXY_MARKER || (deps.ownTokens ?? []).includes(value);
+    const apiKey = env.ANTHROPIC_API_KEY?.trim();
+    if (apiKey && !isOwn(apiKey)) {
+      return { source: "exported-env", presence: "present", detail: "ANTHROPIC_API_KEY" };
+    }
+    const token = env.ANTHROPIC_AUTH_TOKEN?.trim();
+    // Our own dummy is opencodex state, never user auth: counting it would make a
+    // proxy-mode launch look authenticated on the NEXT launch (002 §1). The configured
+    // admission key is opencodex state for exactly the same reason — the system-env
+    // writer exports it into this very variable.
+    if (token && !isOwn(token)) {
+      return { source: "exported-env", presence: "present", detail: "ANTHROPIC_AUTH_TOKEN" };
+    }
+    return { source: "exported-env", presence: "absent" };
+  } catch {
+    return { source: "exported-env", presence: "unknown" };
+  }
+}
+
+export function detectClaudeAuth(deps: AuthDetectDeps): AuthDetectResult {
+  const sources = [
+    detectClaudeJson(deps),
+    detectCredentialsFile(deps),
+    detectKeychain(deps),
+    detectExportedEnv(deps),
+  ];
+  let staleProxyMarker = false;
+  try {
+    staleProxyMarker = deps.env().ANTHROPIC_AUTH_TOKEN?.trim() === PROXY_MARKER;
+  } catch {
+    staleProxyMarker = false;
+  }
+
+  const present = sources.find(source => source.presence === "present");
+  if (present) return { presence: "present", foundBy: present.source, sources, staleProxyMarker };
+  if (sources.some(source => source.presence === "unknown")) {
+    return { presence: "unknown", sources, staleProxyMarker };
+  }
+  return { presence: "absent", sources, staleProxyMarker };
+}
+
+/**
+ * Real IO. The keychain probe is METADATA ONLY: no `-g` and no `-w`, because those
+ * flags print the password itself. We only need the exit code.
+ */
+export function defaultAuthDetectDeps(
+  env: NodeJS.ProcessEnv = process.env,
+  ownTokens: readonly string[] = [],
+): AuthDetectDeps {
+  const configDir = claudeConfigDir(env);
+  return {
+    readClaudeJson() {
+      // Sibling of the config dir when CLAUDE_CONFIG_DIR is set, else ~/.claude.json.
+      const path = env.CLAUDE_CONFIG_DIR?.trim()
+        ? join(configDir, "..", ".claude.json")
+        : join(homeDir(env), ".claude.json");
+      if (!existsSync(path)) return undefined;
+      // A parse failure propagates so the caller records `unknown`, not `absent`.
+      return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    },
+    credentialsFileExists() {
+      return existsSync(join(configDir, ".credentials.json"));
+    },
+    keychainProbe() {
+      if (process.platform !== "darwin") return "absent";
+      const result = spawnSync("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE], {
+        timeout: KEYCHAIN_TIMEOUT_MS,
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+      if (result.error || result.signal !== null) return "unknown";
+      if (result.status === 0) return "present";
+      if (result.status === KEYCHAIN_ITEM_NOT_FOUND) return "absent";
+      return "unknown";
+    },
+    env: () => env,
+    ownTokens,
+  };
+}
+
+/**
+ * The token values opencodex itself exports. Configured admission keys land in
+ * `ANTHROPIC_AUTH_TOKEN` (see `system-env.ts`), so detection must not read them back
+ * as user auth.
+ */
+export function ownAdmissionTokens(config: { apiKeys?: Array<{ key: string }> }): string[] {
+  return (config.apiKeys ?? []).map(entry => entry.key).filter(key => key.length > 0);
+}

package/src/claude/auth-mode-migration.ts

@@ -0,0 +1,32 @@
+/**
+ * One-time authMode migration (devlog/_plan/260726_claude_auth_auto/015).
+ *
+ * Before auto existed, choosing "Subscription" in the GUI DELETED the key. So on disk
+ * an explicit subscription choice and "never chose anything" are byte-identical, and
+ * reading both as auto would flip a deliberate subscriber into proxy mode the moment
+ * their credentials are undetectable. This migration preserves the old EFFECTIVE
+ * behaviour for configs that already had a claudeCode block, and leaves genuinely
+ * untouched configs on auto.
+ */
+import type { OcxConfig } from "../types";
+
+/**
+ * @returns true when the config changed and the caller should persist it.
+ */
+export function runClaudeAuthModeMigration(config: OcxConfig, now = new Date()): boolean {
+  const claudeCode = config.claudeCode;
+  // No block at all = a fresh or Claude-untouched install: auto is the right default,
+  // and writing a sentinel here would create the block for no reason.
+  if (!claudeCode) return false;
+  // Idempotent: the sentinel's presence is the "already migrated" fact. A user who
+  // later picks Auto deletes authMode but KEEPS the sentinel, so the next start must
+  // not resurrect subscription.
+  if (typeof claudeCode.authModeMigratedAt === "string" && claudeCode.authModeMigratedAt.length > 0) {
+    return false;
+  }
+  if (claudeCode.authMode === undefined) {
+    claudeCode.authMode = "subscription";
+  }
+  claudeCode.authModeMigratedAt = now.toISOString();
+  return true;
+}