@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/update/npm-cache-preflight.mjs

@@ -1,13 +1,17 @@
-import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { isAbsolute, resolve } from "node:path";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { npmInvocation } from "./npm-invocation.mjs";
 
 const WORKER_ARG = "--ocx-npm-cache-preflight-worker";
+const ROOT_ONLY_ARG = "--root-only";
 const PROTOCOL_VERSION = 1;
-const WORKER_TIMEOUT_MS = 10_000;
-const NPM_CONFIG_TIMEOUT_MS = 5_000;
+// Windows starts npm through cmd.exe and is routinely slowed by on-access scanning, so the
+// same `npm config get cache` that takes well under a second on POSIX can take several there.
+const WORKER_TIMEOUT_MS = process.platform === "win32" ? 25_000 : 10_000;
+const NPM_CONFIG_TIMEOUT_MS = process.platform === "win32" ? 15_000 : 5_000;
 const INSPECTION_TIMEOUT_MS = 7_500;
 const MAX_ENTRIES = 100_000;
 const MAX_DEPTH = 64;
@@ -17,6 +21,8 @@ const RESULT_REASONS = new Set([
   "cache_entry_foreign_owner",
   "cache_entry_inaccessible",
   "cache_path_malformed",
+  "cache_root_dangling_link",
+  "cache_root_not_directory",
   "inspection_incomplete",
   "npm_config_failed",
   "npm_unavailable",
@@ -29,12 +35,58 @@ function inaccessibleByMode(stat) {
   return (ownerBits & 0o400) === 0;
 }
 
+/**
+ * Check that npm can create or use its cache ROOT (#6288). This is the part of the inspection
+ * that is meaningful on every platform: npm's first action is `mkdir -p <cache>`, and it fails
+ * with ENOTDIR when the root — or the nearest existing ancestor npm would create it under — is
+ * a file, or a link/junction whose target is gone. A Windows directory junction relocated to
+ * another volume is ordinary configuration; only an unresolvable one is a problem.
+ */
+export function inspectNpmCacheRoot(cachePath, options = {}) {
+  const lstat = options.lstatFn ?? lstatSync;
+  const stat = options.statFn ?? statSync;
+  let current = resolve(cachePath);
+  let entry;
+  for (;;) {
+    try {
+      entry = lstat(current);
+      break;
+    } catch (error) {
+      // A file somewhere above the root: POSIX reports ENOTDIR here, which is exactly the
+      // ENOTDIR npm's own mkdir would hit. Windows reports ENOENT and the walk reaches the file.
+      if (error?.code === "ENOTDIR") return { ok: false, reason: "cache_root_not_directory" };
+      if (error?.code !== "ENOENT") return { ok: false, reason: "cache_entry_inaccessible" };
+      const parent = dirname(current);
+      // Nothing on the path exists at all (a missing drive root); npm cannot mkdir there either.
+      if (parent === current) return { ok: false, reason: "cache_root_not_directory" };
+      current = parent;
+    }
+  }
+  let target = entry;
+  if (entry.isSymbolicLink()) {
+    try {
+      target = stat(current);
+    } catch (error) {
+      return {
+        ok: false,
+        reason: error?.code === "ENOENT" || error?.code === "ENOTDIR" || error?.code === "ELOOP"
+          ? "cache_root_dangling_link"
+          : "cache_entry_inaccessible",
+      };
+    }
+  }
+  if (!target.isDirectory()) return { ok: false, reason: "cache_root_not_directory" };
+  return { ok: true, reason: "cache_accessible" };
+}
+
 /**
  * Inspect an existing Unix npm cache without following symlinks. The limits are
  * deliberately part of the result contract: an incomplete inspection cannot prove
  * that replacing the live package will succeed.
  */
 export function inspectNpmCacheDirectory(cachePath, options = {}) {
+  const root = inspectNpmCacheRoot(cachePath, options);
+  if (!root.ok) return root;
   const expectedUid = options.expectedUid ?? process.getuid?.();
   const deadline = (options.nowMs ?? Date.now)() + (options.timeoutMs ?? INSPECTION_TIMEOUT_MS);
   const maxEntries = options.maxEntries ?? MAX_ENTRIES;
@@ -118,22 +170,59 @@ export function inspectNpmCacheDirectory(cachePath, options = {}) {
   return { ok: true, reason: "cache_accessible" };
 }
 
-function workerResult() {
-  const invocation = npmInvocation(["config", "get", "cache"]);
+// cmd.exe re-parses npm.cmd's %* after our quoting, so on Windows a pinned path must not carry
+// characters that quoting cannot neutralize there. Such a path is refused, never escaped.
+const WINDOWS_CMD_METACHARACTERS = /["%!^&|<>]/;
+
+function validCachePath(value, platform = process.platform) {
+  return typeof value === "string" && value.length > 0 && value.length <= 4096
+    && !value.includes("\0") && !/[\r\n]/.test(value) && isAbsolute(value)
+    && !(platform === "win32" && WINDOWS_CMD_METACHARACTERS.test(value));
+}
+
+/**
+ * Resolve the cache npm itself uses, with the operator's full npmrc chain. The transactional
+ * stage pins this path with `--cache`: its `--prefix <stage>` moves npm's globalconfig to
+ * `<stage>/etc/npmrc`, so without the pin a `cache=` from the global npmrc is silently dropped
+ * and staging falls back to npm's default root — not the root this preflight checked (#6288).
+ */
+export function resolveNpmCachePath(options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  // Global mode, from the home directory: the staged install is `npm install -g`, which never
+  // reads a project .npmrc, so a repository the user happens to run `ocx update` in must not be
+  // able to choose the cache that install is pinned to.
+  const invocation = (options.invocationFn ?? npmInvocation)(["config", "get", "cache", "--global"], platform, env);
   if (!invocation) return { ok: false, reason: "npm_unavailable" };
-  const npm = spawnSync(invocation.file, invocation.args, {
+  const npm = (options.spawnSyncFn ?? spawnSync)(invocation.file, invocation.args, {
     encoding: "utf8",
-    timeout: NPM_CONFIG_TIMEOUT_MS,
+    timeout: options.timeoutMs ?? NPM_CONFIG_TIMEOUT_MS,
     windowsHide: true,
+    cwd: options.cwd ?? homedir(),
     ...invocation.options,
+    env: invocation.options?.env ?? env,
   });
-  if (npm.status !== 0) return { ok: false, reason: "npm_config_failed" };
-
+  if (npm?.status !== 0) return { ok: false, reason: "npm_config_failed" };
   const output = typeof npm.stdout === "string" ? npm.stdout.trim() : "";
-  if (!output || output.length > 4096 || output.includes("\0") || /[\r\n]/.test(output) || !isAbsolute(output)) {
-    return { ok: false, reason: "cache_path_malformed" };
+  if (!validCachePath(output, platform)) return { ok: false, reason: "cache_path_malformed" };
+  return { ok: true, path: output };
+}
+
+function workerResult(argv) {
+  const rootOnly = argv.includes(ROOT_ONLY_ARG);
+  const supplied = argv.find(arg => arg !== ROOT_ONLY_ARG);
+  let cachePath;
+  if (supplied !== undefined) {
+    if (!validCachePath(supplied)) return { ok: false, reason: "cache_path_malformed" };
+    cachePath = supplied;
+  } else {
+    const resolved = resolveNpmCachePath();
+    if (!resolved.ok) return resolved;
+    cachePath = resolved.path;
   }
-  return inspectNpmCacheDirectory(output);
+  // Windows has no uid and no Unix owner bits, so the deep ownership/mode walk proves nothing
+  // there; the root check is the part of the contract that holds on every platform.
+  return rootOnly ? inspectNpmCacheRoot(cachePath) : inspectNpmCacheDirectory(cachePath);
 }
 
 // Reasons that legitimately accompany `ok: true`. The parser below cross-checks the flag against
@@ -161,15 +250,33 @@ function parseWorkerOutput(stdout) {
   }
 }
 
-/** Run the bounded cache inspection in an isolated, synchronously-timeboxed worker. */
+/**
+ * Run the bounded cache inspection in an isolated, synchronously-timeboxed worker. Pass
+ * `cachePath` (from {@link resolveNpmCachePath}) to inspect exactly the root a later stage pins;
+ * without it the worker resolves npm's cache itself.
+ */
 export function runNpmCachePreflight(options = {}) {
-  if ((options.platform ?? process.platform) === "win32") {
+  const result = runPreflightWorker(options);
+  // Before #6288 Windows skipped this gate entirely. Only the root shapes that make npm's own
+  // mkdir fail with ENOTDIR may now refuse an update there; a slow or unavailable npm, a worker
+  // timeout, or any other inconclusive result keeps the previous behavior instead of blocking.
+  if ((options.platform ?? process.platform) === "win32" && !result.ok
+    && !WINDOWS_BLOCKING_REASONS.has(result.reason)) {
     return { ok: true, reason: "windows_skip" };
   }
+  return result;
+}
+
+const WINDOWS_BLOCKING_REASONS = new Set(["cache_root_dangling_link", "cache_root_not_directory"]);
+
+function runPreflightWorker(options) {
+  const workerArgs = [fileURLToPath(import.meta.url), WORKER_ARG];
+  if ((options.platform ?? process.platform) === "win32") workerArgs.push(ROOT_ONLY_ARG);
+  if (options.cachePath !== undefined) workerArgs.push(options.cachePath);
   const spawn = options.spawnSyncFn ?? spawnSync;
   const result = spawn(
     options.execPath ?? process.execPath,
-    [fileURLToPath(import.meta.url), WORKER_ARG],
+    workerArgs,
     {
       encoding: "utf8",
       timeout: options.timeoutMs ?? WORKER_TIMEOUT_MS,
@@ -182,8 +289,14 @@ export function runNpmCachePreflight(options = {}) {
   return parseWorkerOutput(result.stdout) ?? { ok: false, reason: "worker_output_malformed" };
 }
 
-/** Fixed operator guidance; worker/npm output is intentionally never interpolated. */
+/** Fixed operator guidance; worker/npm output and the cache path are intentionally never interpolated. */
 export function npmCachePreflightFailureMessage(reason) {
+  if (reason === "cache_root_dangling_link") {
+    return `npm cache access pre-flight failed (${reason}); npm's cache folder (see 'npm config get cache') is a link or junction whose target is missing — recreate the target folder or remove the link, then retry`;
+  }
+  if (reason === "cache_root_not_directory") {
+    return `npm cache access pre-flight failed (${reason}); npm's cache folder (see 'npm config get cache') or a folder above it is a file or an unavailable drive, so npm would fail with ENOTDIR on mkdir — fix that path or set a different cache, then retry`;
+  }
   return `npm cache access pre-flight failed (${reason}); fix cache ownership and permissions, then retry`;
 }
 
@@ -193,7 +306,7 @@ const isWorker = process.argv[1]
 if (isWorker) {
   let result;
   try {
-    result = workerResult();
+    result = workerResult(process.argv.slice(3));
   } catch {
     result = { ok: false, reason: "cache_entry_inaccessible" };
   }

package/src/update/ownership-transaction.ts

@@ -9,19 +9,37 @@ type Environment = Record<string, string | undefined>;
 export interface UpdateOwnershipTransaction {
   controlEnvironment(environment?: Environment): Environment;
   unprivilegedEnvironment(environment?: Environment): Environment;
+  /**
+   * Free the lease before a service-manager-mediated start that cannot join it —
+   * the manager's `ocx start` child runs with the stored registration environment,
+   * not a delegated token, so held through the repair's serving wait the lease
+   * keeps that proxy from starting (#5760). Idempotent; controlEnvironment keeps
+   * injecting the token afterwards, which a released lease self-corrects (the
+   * delegated join fails and the child acquires normally).
+   */
+  release(): void;
+  /**
+   * Take the lease back before re-reading ownership and mutating directly: the
+   * released refresh window could have admitted a claim that must be vetoed, not
+   * killed unleased. No-op while held; a still-claimed lease throws (bounded),
+   * which callers must treat as fail-closed.
+   */
+  reacquire(): void;
 }
 
 /** One lease spans awaited stop, replacement and recovery. Never publish its token globally. */
 export async function withUpdateOwnershipLease<T>(
   paths: string[], run: (transaction: UpdateOwnershipTransaction) => Promise<T>,
 ): Promise<T> {
-  const lease = acquireOwnershipMutationLease(paths);
+  let lease = acquireOwnershipMutationLease(paths);
   let released = false;
   const release = () => { if (!released) { released = true; lease.release(); } };
   try {
     return await run({
       controlEnvironment: (env = process.env) => ownershipMutationLeaseChildEnvironment(env, lease.token),
       unprivilegedEnvironment: (env = process.env) => unprivilegedOwnershipMutationEnvironment(env),
+      release: () => release(),
+      reacquire: () => { if (released) { lease = acquireOwnershipMutationLease(paths); released = false; } },
     });
   } finally { release(); }
 }

package/src/update/restart-ownership.ts

@@ -36,19 +36,93 @@ export function updateRestartVeto(
   return plan.notice ?? "The background runtime is owned elsewhere; it was left running.";
 }
 
+/**
+ * The lease boundary inside a running restart, handed to `restart`.
+ *
+ * `ocx service repair` re-activates the OS service manager — Task Scheduler, launchd
+ * or systemd — and that `ocx start` child is not a descendant of this process: it runs
+ * with the stored registration environment, carries no delegated token, and can never
+ * join the lease held here. Held through the repair's serving wait, the lease keeps
+ * that child from ever starting (#5760; the npm lane releases at this boundary). The
+ * veto is the decision the lease must cover — the reclaim and kills it authorizes —
+ * so the fallthrough takes the lease back before re-running it: anything between the
+ * service refresh and the direct start would otherwise mutate the port unleased.
+ */
+export interface UpdateRestartLeaseControl {
+  /** Free the lease before a service-manager-mediated start that cannot join it. Idempotent. */
+  releaseForServiceManager(): void;
+  /**
+   * Take the lease back before the fallthrough mutates the port, then re-run the veto
+   * under it. A lease that stays claimed (a live claimant mid-mutation) fails closed:
+   * the returned notice stops the restart before any kill or start, and `failed` marks
+   * the job failed — the refresh just before this did not produce a serving proxy, so
+   * nothing is known to be running. An ownership veto is not a failure.
+   */
+  reacquireForDirectStart(): UpdateRestartStop | null;
+  /** Re-run the recorded-owner veto; a non-null notice must stop the restart there. */
+  vetoAgain(): string | null;
+}
+
+/** Why the direct-start fallthrough stopped; `failed` means no proxy is known to be serving. */
+export interface UpdateRestartStop {
+  readonly notice: string;
+  readonly failed: boolean;
+}
+
+/**
+ * Long enough to outlast one service-wrapper respawn cycle (5 s) of the managed child the
+ * refresh just started, which briefly holds the lease while it binds and publishes.
+ */
+const REACQUIRE_WAIT_MS = 10_000;
+
 export async function runUpdateRestartWithOwnershipLease<T>(
   resolve: (() => ServiceOwnershipResolution) | undefined,
-  restart: () => Promise<T>,
+  restart: (lease: UpdateRestartLeaseControl) => Promise<T>,
 ): Promise<{ readonly kind: "veto"; readonly notice: string } | { readonly kind: "ran"; readonly value: T }> {
-  const lease = acquireOwnershipMutationLease(serviceStatePaths());
+  let lease = acquireOwnershipMutationLease(serviceStatePaths());
   const previous = process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
   process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV] = lease.token;
-  try {
-    const veto = updateRestartVeto(resolve);
-    return veto ? { kind: "veto", notice: veto } : { kind: "ran", value: await restart() };
-  } finally {
+  let heldNow = true;
+  const restoreEnv = () => {
     if (previous === undefined) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
     else process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV] = previous;
+  };
+  const release = () => {
+    if (!heldNow) return;
+    heldNow = false;
+    restoreEnv();
     lease.release();
+  };
+  const reacquireForDirectStart = (): UpdateRestartStop | null => {
+    if (!heldNow) {
+      try {
+        lease = acquireOwnershipMutationLease(serviceStatePaths(), { waitMs: REACQUIRE_WAIT_MS });
+      } catch {
+        return {
+          failed: true,
+          notice: "Update installed, but another process kept the runtime ownership lease claimed, so no proxy was started. "
+            + "Run 'ocx service status', then 'ocx service repair' or 'ocx start'.",
+        };
+      }
+      heldNow = true;
+      process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV] = lease.token;
+    }
+    const veto = updateRestartVeto(resolve);
+    return veto ? { notice: veto, failed: false } : null;
+  };
+  try {
+    const veto = updateRestartVeto(resolve);
+    return veto
+      ? { kind: "veto", notice: veto }
+      : {
+          kind: "ran",
+          value: await restart({
+            releaseForServiceManager: release,
+            reacquireForDirectStart,
+            vetoAgain: () => updateRestartVeto(resolve),
+          }),
+        };
+  } finally {
+    release();
   }
 }

package/src/update/transactional-install.d.mts

@@ -31,6 +31,8 @@ export function transactionalNpmUpdate(args: {
   targetVersion?: string;
   tag: string;
   runNpm: (args: string[]) => { status: number | null };
+  /** npm cache root the pre-flight resolved and checked; pinned with `--cache` for staging. */
+  cachePath?: string;
   log?: (line: string) => void;
   deps?: UpdateFsDeps;
 }): {

package/src/update/transactional-install.mjs

@@ -390,6 +390,7 @@ export function transactionalNpmUpdate({
   targetVersion,
   tag,
   runNpm,
+  cachePath,
   log = () => {},
   deps = {},
 }) {
@@ -432,8 +433,12 @@ export function transactionalNpmUpdate({
   // @oven/bun-* executable into bun/bin, so a successful npm exit without this narrow
   // approval leaves the staged tree intentionally incomplete. Allow only the package
   // whose executable the manifest verifies below; never broaden this to all scripts.
+  // --prefix <stage> also moves npm's globalconfig to <stage>/etc/npmrc, so a `cache=` from the
+  // operator's global npmrc would be dropped and npm would fall back to its default root. Pin
+  // the cache the pre-flight resolved and checked, so staging uses that exact root (#6288).
+  const cacheArgs = typeof cachePath === "string" && cachePath.length > 0 ? ["--cache", cachePath] : [];
   const install = runNpm([
-    "install", "-g", "--prefix", stageRoot,
+    "install", "-g", "--prefix", stageRoot, ...cacheArgs,
     "--allow-scripts=bun", "--no-audit", "--no-fund", spec,
   ]);
   if (install.status !== 0) {

package/src/usage/jev-stats.ts

@@ -18,6 +18,7 @@ export const JEV_DECISION_GATES = [
 export type JevDecisionGate = (typeof JEV_DECISION_GATES)[number];
 
 const JEV_GATE_SET = new Set<string>(JEV_DECISION_GATES);
+const JEV_STATS_BACKENDS = ["typesafe", "systemone", "model", "unknown"] as const;
 const JEV_EFFORTS = new Set<OcxComboDefaultEffort>([
   "low", "medium", "high", "xhigh", "max", "ultra",
 ]);
@@ -30,6 +31,7 @@ const CONTROL_CHARS = /[\u0000-\u001f\u007f]/u;
 export interface PersistedJevDecisionV1 {
   version: 1;
   comboId: string;
+  backend?: "typesafe" | "systemone" | "model";
   selected: {
     provider: string;
     model: string;
@@ -103,6 +105,12 @@ export interface JevStatsResponse {
     averageChosenProbability: number | null;
   };
   gates: Array<{ gate: JevDecisionGate; decisions: number }>;
+  backends: Array<{
+    backend: "typesafe" | "systemone" | "model" | "unknown";
+    decisions: number;
+    applied: number;
+    averageLatencyMs: number | null;
+  }>;
   models: JevStatsModelRow[];
   snapshotWindowStart: number | null;
   snapshotWindowEnd: number | null;
@@ -174,9 +182,13 @@ export function normalizePersistedJevDecision(value: unknown): PersistedJevDecis
   const confidence = probability(value.confidence);
   const chosenProbability = probability(value.chosenProbability);
   const usage = normalizedDecisionUsage(value.usage);
+  const backend = value.backend === "typesafe" || value.backend === "systemone" || value.backend === "model"
+    ? value.backend
+    : undefined;
   return {
     version: 1,
     comboId,
+    ...(backend !== undefined ? { backend } : {}),
     selected: {
       provider,
       model,
@@ -269,6 +281,9 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
   private readonly models = new Map<string, MutableModelRow>();
   private overflowModel: MutableModelRow | null = null;
   private readonly gates = new Map<JevDecisionGate, number>();
+  private readonly backends = new Map<
+    JevStatsResponse["backends"][number]["backend"], JevStatsResponse["backends"][number]
+  >();
   private snapshotWindowStart: number | null = null;
   private snapshotWindowEnd: number | null = null;
   private decisions = 0;
@@ -300,7 +315,7 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
   }
 
   get estimatedBytes(): number {
-    let bytes = 512;
+    let bytes = 512 + this.backends.size * 96;
     for (const row of this.models.values()) {
       bytes += 256 + (row.provider.length + row.model.length) * 2 + row.effortCounts.size * 32;
     }
@@ -340,6 +355,13 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
     const decision = normalizePersistedJevDecision(entry.jevDecision);
     if (!decision || (this.comboId !== null && decision.comboId !== this.comboId)) return;
 
+    const backend = decision.backend ?? "unknown";
+    const backendRow = this.backends.get(backend)
+      ?? { backend, decisions: 0, applied: 0, averageLatencyMs: null };
+    backendRow.averageLatencyMs = nextMean(backendRow.averageLatencyMs, backendRow.decisions, decision.latencyMs);
+    backendRow.decisions = saturatingAdd(backendRow.decisions, 1);
+    if (decision.gate === "apply") backendRow.applied = saturatingAdd(backendRow.applied, 1);
+    this.backends.set(backend, backendRow);
     this.averageLatencyMs = nextMean(this.averageLatencyMs, this.decisions, decision.latencyMs);
     this.decisions = saturatingAdd(this.decisions, 1);
     if (decision.gate === "apply") this.appliedDecisions = saturatingAdd(this.appliedDecisions, 1);
@@ -419,6 +441,7 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
     for (const [key, row] of this.models) cloned.models.set(key, cloneModelRow(row));
     cloned.overflowModel = this.overflowModel ? cloneModelRow(this.overflowModel) : null;
     for (const [gate, count] of this.gates) cloned.gates.set(gate, count);
+    for (const [backend, row] of this.backends) cloned.backends.set(backend, { ...row });
     cloned.snapshotWindowStart = this.snapshotWindowStart;
     cloned.snapshotWindowEnd = this.snapshotWindowEnd;
     cloned.decisions = this.decisions;
@@ -487,6 +510,10 @@ class StreamingJevStatsAccumulator implements JevStatsAccumulator {
         const count = this.gates.get(gate) ?? 0;
         return count > 0 ? [{ gate, decisions: count }] : [];
       }),
+      backends: JEV_STATS_BACKENDS.flatMap(backend => {
+        const row = this.backends.get(backend);
+        return row && row.decisions > 0 ? [{ ...row }] : [];
+      }),
       models: rows,
       snapshotWindowStart: this.snapshotWindowStart,
       snapshotWindowEnd: this.snapshotWindowEnd,

package/src/usage/log.ts

@@ -506,7 +506,7 @@ const KNOWN_AFFINITY_MOVES = new Set<NonNullable<PersistedUsageEntry["affinity"]
 ]);
 const KNOWN_AFFINITY_REASONS = new Set<NonNullable<PersistedUsageEntry["affinityReason"]>>([
   "healthy", "quota_headroom", "quota_refusal", "transient", "transient_hold_expired",
-  "unusable", "paused", "plan_excluded", "cooldown", "quota_avoided", "generation",
+  "unusable", "paused", "plan_excluded", "credits_off", "cooldown", "quota_avoided", "generation",
   "expired", "model_lane",
 ]);
 const KNOWN_CONVERSATION_STATE_SCRUBS = new Set<NonNullable<PersistedUsageEntry["conversationStateScrub"]>>([

package/src/vision/anthropic-describe.ts

@@ -1,10 +1,11 @@
-import type { OcxProviderConfig } from "../types";
+import type { OcxConfig, OcxProviderConfig } from "../types";
 import { sidecarThinkingOff } from "../adapters/anthropic-model-contract";
 import { CLAUDE_CODE_HEADERS, claudeCodeSessionId } from "../adapters/client-fingerprint";
 import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import { applyUpstreamRecoveryInit, fetchWithResetRetry } from "../lib/upstream-retry";
-import { getValidAccessToken, publicOAuthAuthenticationErrorMessage } from "../oauth";
+import { publicOAuthAuthenticationErrorMessage } from "../oauth";
+import { getAnthropicSidecarAccessToken } from "../oauth/anthropic-routing";
 import { ANTHROPIC_OAUTH_BETA, CLAUDE_CODE_SYSTEM_INSTRUCTION } from "../oauth/anthropic";
 import type { DescribeOutcome, VisionSettings } from "./describe";
 
@@ -152,13 +153,14 @@ export async function describeImageAnthropic(
   provider: OcxProviderConfig,
   settings: VisionSettings,
   abortSignal?: AbortSignal,
+  config?: OcxConfig,
 ): Promise<DescribeOutcome> {
   const image = buildImageBlock(imageUrl);
   if (!image.block) return { text: "", error: image.error ?? "invalid image" };
 
   let token: string;
   try {
-    token = await getValidAccessToken(providerName);
+    token = await getAnthropicSidecarAccessToken(providerName, settings.model, config);
   } catch (error) {
     return { text: "", error: `anthropic vision sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(error)}` };
   }

package/src/vision/index.ts

@@ -256,6 +256,7 @@ async function executeDescription(
       sidecar.provider,
       plan.settings,
       abortSignal,
+      sidecar.config,
     );
   }
   if (!plan.forwardSidecar) return { text: "", error: "OpenAI vision sidecar is unavailable" };

package/src/vision/plan.ts

@@ -43,6 +43,7 @@ export function resolveVisionTimeoutMs(value: unknown): number {
 export interface AnthropicVisionProvider {
   providerName: string;
   provider: OcxProviderConfig;
+  config: OcxConfig;
 }
 
 /**
@@ -52,7 +53,7 @@ export interface AnthropicVisionProvider {
 export function findAnthropicVisionProvider(config: OcxConfig): AnthropicVisionProvider | undefined {
   const auth = resolveSidecarAuth(config);
   if (!auth.isAnthropicAuth || !auth.anthropicProviderName || !auth.anthropicProvider) return undefined;
-  return { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider };
+  return { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider, config };
 }
 
 export function resolveVisionBackend(