@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/service/repair.ts

@@ -1,3 +1,7 @@
+import { existsSync } from "node:fs";
+import { getConfigDir } from "../config";
+import { durableBunRuntime, type DurableBunRuntime } from "../lib/bun-runtime";
+import { assertSelectedRuntimeWritable, type RuntimePreflightDeps } from "../lib/bun-runtime-preflight";
 import { randomUUID } from "node:crypto";
 import { defaultWinswEntry, installWinswService } from "../lib/winsw";
 import { resolveWindowsTaskDiagnosticUserId, diagnoseService } from "./diagnostics";
@@ -14,6 +18,7 @@ import type { WindowsSchedulerTaskProbe } from "./windows-scheduler";
 import { taskXmlSection, taskXmlWithoutCommentsAndCdata, taskXmlElementCount, taskXmlOptionalValueEquals, windowsTaskRegistrationOwnedByAttempt, windowsTaskHasSessionRecoveryTriggers, windowsTaskRegistrationHealthy, windowsTaskRegistrationRefreshableLegacy } from "./windows-taskxml";
 import type { ExpectedWindowsTaskUserId } from "./windows-taskxml";
 import { win32 } from "node:path";
+import { assertNoDesktopSupervision, createSupervisionLatch, type SupervisionInspector, type SupervisionLatch } from "./desktop-command-guard";
 
 /**
  * The two CLI verbs `repairService` serves. They differ on ONE platform and ONE case: a
@@ -22,16 +27,18 @@ import { win32 } from "node:path";
  */
 export type ServiceRepairVerb = "repair" | "restart";
 
-export interface RepairServiceDeps {
+export interface RepairServiceDeps extends RuntimePreflightDeps {
+  inspectSupervision?: SupervisionInspector;
+  supervisionLatch?: SupervisionLatch;
   diagnose?: () => ServiceDiagnostic;
   assertEnv?: () => void;
   assertAuth?: () => void;
-  writeSchedulerAssets?: () => void;
+  writeSchedulerAssets?: (runtime: DurableBunRuntime) => void;
   stopScheduler?: () => void;
   startScheduler?: () => void;
-  writeSchedulerState?: () => void;
-  writeNativeState?: () => void;
-  repairNative?: () => void | Promise<void>;
+  writeSchedulerState?: (runtime: DurableBunRuntime) => void;
+  writeNativeState?: (runtime: DurableBunRuntime) => void;
+  repairNative?: (runtime: DurableBunRuntime) => void | Promise<void>;
   repairLaunchd?: () => LaunchdInstallOutcome | void;
   repairSystemd?: () => void;
   /** Restarts a launchd job the install path deliberately left alone. `restart` only. */
@@ -148,6 +155,8 @@ export async function assertSchedulerRegistrationBeforeStart(
  * macOS/Linux: re-run the user-level install/reload path.
  */
 export async function repairService(deps: RepairServiceDeps = {}): Promise<void> {
+  const latch = deps.supervisionLatch ?? createSupervisionLatch();
+  assertNoDesktopSupervision(deps.inspectSupervision, latch);
   const diagnose = deps.diagnose ?? diagnoseService;
   const platform = deps.platform ?? process.platform;
   const diag = diagnose();
@@ -176,14 +185,18 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
 
   (deps.assertEnv ?? assertServiceEnvironmentMatchesInstall)();
   (deps.assertAuth ?? assertServiceAuthEnvironment)();
+  const runtime = Object.freeze({ ...(deps.selectRuntime ?? durableBunRuntime)() });
+  const configDir = (deps.configDir ?? getConfigDir)();
+  (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform, rootWasAbsent: !existsSync(configDir) });
 
   const temporaryLauncher = (deps.launcherPathDiagnostic ?? (() => serviceLauncherPathDiagnostic(undefined, platform, true)))();
   if (temporaryLauncher) console.warn(`⚠️ ${temporaryLauncher}`);
 
   if (platform === "win32") {
     if (diag.backend === "native") {
-      await (deps.repairNative ?? (() => installWinswService(defaultWinswEntry(serviceSourceDir))))();
-      (deps.writeNativeState ?? (() => writeServiceInstallState("native")))();
+      await (deps.repairNative ?? ((selected: DurableBunRuntime) => installWinswService(defaultWinswEntry(serviceSourceDir, selected))))(runtime);
+      assertNoDesktopSupervision(deps.inspectSupervision, latch);
+      (deps.writeNativeState ?? ((selected: DurableBunRuntime) => writeServiceInstallState("native", undefined, {}, selected)))(runtime);
       return;
     }
     const readSchedulerXml = deps.readSchedulerXml ?? statusWindowsXml;
@@ -243,7 +256,7 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
       );
     }
     try { (deps.stopScheduler ?? stopWindows)(); } catch { /* not running */ }
-    (deps.writeSchedulerAssets ?? writeWindowsSchedulerAssets)();
+    (deps.writeSchedulerAssets ?? writeWindowsSchedulerAssets)(runtime);
     // Rewriting the on-disk assets does not touch the definition Task Scheduler holds, so a
     // task registered by an older version keeps its old triggers forever: status reports it
     // stale, tells the user to run repair, and repair changes nothing it complains about.
@@ -311,6 +324,7 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
             }
             if (probe.status === "absent") {
               try {
+                assertNoDesktopSupervision(deps.inspectSupervision, latch);
                 await (deps.restoreSchedulerIfAbsent ?? restoreWindowsSchedulerTaskIfAbsent)(registeredXml);
                 restartExpectedXml = registeredXml;
               } catch (error) {
@@ -333,6 +347,7 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
               "The Task Scheduler registration changed again before restart; the newer definition was preserved and not started.",
               "Task Scheduler state remained unreadable before restart; the registration was preserved and not started.",
             );
+            assertNoDesktopSupervision(deps.inspectSupervision, latch);
             (deps.startScheduler ?? startWindows)();
           } catch (error) {
             recoveryErrors.push(error);
@@ -358,8 +373,9 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
       "Task Scheduler registration changed before restart; the current definition was preserved and not started.",
       "Task Scheduler registration became unreadable before restart; it was preserved and not started.",
     );
+    assertNoDesktopSupervision(deps.inspectSupervision, latch);
     (deps.startScheduler ?? startWindows)();
-    (deps.writeSchedulerState ?? (() => writeServiceInstallState("scheduler")))();
+    (deps.writeSchedulerState ?? ((selected: DurableBunRuntime) => writeServiceInstallState("scheduler", undefined, {}, selected)))(runtime);
     return;
   }
   if (platform === "darwin") {

package/src/service/state.ts

@@ -360,8 +360,8 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
  * it describes the install that just ran. {@link ServiceInstallState.ownership} deliberately
  * is not part of it.
  */
-function installProvenanceRecord(backend: ServiceBackend, launcherPath?: string | null): ServiceInstallState {
-  const { bun, cli } = cliEntry();
+function installProvenanceRecord(backend: ServiceBackend, launcherPath: string | null | undefined, runtime: DurableBunRuntime): ServiceInstallState {
+  const { bun, cli } = cliEntry(runtime);
   const codexHome = currentCodexHome();
   return {
     version: 2,
@@ -391,9 +391,10 @@ export function writeServiceInstallState(
   backend: ServiceBackend = "scheduler",
   launcherPath?: string | null,
   deps: ServiceStateSwapDeps = {},
+  runtime: DurableBunRuntime = durableBunRuntime(),
 ): void {
   swapServiceInstallState(current => ({
-    ...installProvenanceRecord(backend, launcherPath),
+    ...installProvenanceRecord(backend, launcherPath, runtime),
     ...preservedConsent(current),
   }), deps);
 }

package/src/service/systemd.ts

@@ -102,13 +102,22 @@ WantedBy=default.target
 
 /** The per-user runtime dir systemd creates (holds the user-bus socket), or null. */
 function userRuntimeDir(): string | null {
-  const fromEnv = process.env.XDG_RUNTIME_DIR;
-  if (fromEnv && existsSync(fromEnv)) return fromEnv;
-  if (typeof process.getuid === "function") {
-    const candidate = `/run/user/${process.getuid()}`;
-    if (existsSync(candidate)) return candidate;
+  const env = { ...process.env };
+  if (env.XDG_RUNTIME_DIR && !existsSync(env.XDG_RUNTIME_DIR)) delete env.XDG_RUNTIME_DIR;
+  return systemdUserBusEnvironment(env).XDG_RUNTIME_DIR || null;
+}
+
+/** Return explicit SSH user-bus discovery without changing the caller's environment. */
+export function systemdUserBusEnvironment(environment: NodeJS.ProcessEnv = process.env, deps: {
+  uid?: number; exists?: (path: string) => boolean;
+} = {}): NodeJS.ProcessEnv {
+  const env = { ...environment };
+  if (!env.XDG_RUNTIME_DIR) {
+    const uid = deps.uid ?? process.getuid?.();
+    const candidate = uid === undefined ? null : `/run/user/${uid}`;
+    if (candidate && (deps.exists ?? existsSync)(candidate)) env.XDG_RUNTIME_DIR = candidate;
   }
-  return null;
+  return env;
 }
 
 /**
@@ -119,8 +128,8 @@ function userRuntimeDir(): string | null {
  */
 function ensureUserBusEnv(): void {
   if (process.env.XDG_RUNTIME_DIR) return;
-  const dir = userRuntimeDir();
-  if (dir) process.env.XDG_RUNTIME_DIR = dir;
+  const env = systemdUserBusEnvironment();
+  if (env.XDG_RUNTIME_DIR) process.env.XDG_RUNTIME_DIR = env.XDG_RUNTIME_DIR;
 }
 
 export function isSystemd(): boolean {

package/src/service/windows-ops.ts

@@ -3,6 +3,8 @@ import { createHash } from "node:crypto";
 import { win32 } from "node:path";
 import { winswXmlPath } from "../lib/winsw";
 import { hardenSecretPath } from "../lib/windows-secret-acl";
+import { durableBunRuntime, type DurableBunRuntime } from "../lib/bun-runtime";
+import { assertSelectedRuntimeWritable, type RuntimePreflightDeps } from "../lib/bun-runtime-preflight";
 import { parseBakedListenPort } from "./health";
 import { windowsServiceScriptPath } from "./state";
 import { execFileSync } from "node:child_process";
@@ -18,7 +20,7 @@ import { killWindowsSchedulerWrappers } from "../lib/windows-service-wrappers";
 import { isTestHomeGuardArmed } from "../lib/test-home-guard";
 import { writeServiceApiTokenFile } from "./guards";
 import type { ServiceStopOutcome } from "./orchestration";
-import { TASK, windowsLauncherVbsPath, windowsTaskXmlPath, serviceStatePath, writeServiceInstallState, serviceSourceDir } from "./state";
+import { TASK, windowsLauncherVbsPath, windowsTaskXmlPath, serviceStatePath, writeServiceInstallState, serviceSourceDir, cliEntry } from "./state";
 import { decodeSchtasksOutput, querySchtasks, schtasks, type WindowsSchedulerTaskProbe, schtasksErrorDetail, probeWindowsSchedulerTask, rollbackWindowsSchedulerTaskOwnedByAttempt } from "./windows-scheduler";
 import { buildWindowsServiceScript, buildWindowsSchtasksCreateArgs, buildWindowsSchtasksCreateArgsForXml, buildWindowsLauncherVbs, resolvedWindowsTaskSid, buildWindowsTaskXmlDocument, windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy } from "./windows-taskxml";
 
@@ -108,11 +110,11 @@ function writeServiceAssetWithRetry(path: string, content: string, encoding: "ut
  * Rewrite on-disk scheduler assets (script/VBS/XML) without itself registering the task.
  * Fresh install creates it afterwards; repair does so only when the live definition is stale.
  */
-export function writeWindowsSchedulerAssets(): void {
+export function writeWindowsSchedulerAssets(runtime: DurableBunRuntime = durableBunRuntime()): void {
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
   const script = windowsServiceScriptPath();
-  writeServiceAssetWithRetry(script, buildWindowsServiceScript(), "utf8");
+  writeServiceAssetWithRetry(script, buildWindowsServiceScript(cliEntry(runtime)), "utf8");
   // UTF-16LE + BOM: a BOM-less UTF-8 VBS mis-decodes non-ASCII (e.g. Korean) profile
   // paths on some WSH/codepage combinations — same contract as the task XML below.
   writeServiceAssetWithRetry(windowsLauncherVbsPath(), `\uFEFF${buildWindowsLauncherVbs(script)}`, "utf16le");
@@ -597,16 +599,40 @@ export function removeNativeWindowsServiceForScheduler(
   }
 }
 
-export function installWindows(): void {
-  recordWindowsSchedulerOwnership();
-  removeNativeWindowsServiceForScheduler();
+/** External Windows effects shared by the gated entrypoints and admitted commit paths. */
+export interface WindowsServiceInstallDeps extends RuntimePreflightDeps {
+  recordSchedulerOwnership?: () => boolean;
+  removeNativeService?: () => void;
+  stopScheduler?: () => void;
+  writeSchedulerAssets?: (runtime: DurableBunRuntime) => void;
+  schedulerCommand?: typeof schtasks;
+  writeState?: (backend: "scheduler" | "native", runtime: DurableBunRuntime) => void;
+  assertNativeAccount?: () => void;
+  prepareNativeConfig?: () => void;
+  uninstallScheduler?: () => void;
+  installNativeService?: typeof installWinswService;
+}
+
+export function installWindows(selected?: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): void {
+  const runtime = Object.freeze({ ...(selected ?? (deps.selectRuntime ?? durableBunRuntime)()) });
+  const configDir = (deps.configDir ?? getConfigDir)();
+  (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform: deps.platform, rootWasAbsent: !existsSync(configDir) });
+  commitWindowsInstall(runtime, deps);
+}
+
+/** Internal commit boundary: the caller has admitted this frozen runtime before cleanup. */
+export function commitWindowsInstall(runtime: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): void {
+  (deps.recordSchedulerOwnership ?? recordWindowsSchedulerOwnership)();
+  (deps.removeNativeService ?? removeNativeWindowsServiceForScheduler)();
   // End a running task BEFORE rewriting the assets it is executing — cmd.exe reading the
   // script mid-rewrite runs a torn batch file, and its open handle can fail the write.
-  try { stopWindows(); } catch { /* not running */ }
-  writeWindowsSchedulerAssets();
-  schtasks(buildWindowsSchtasksCreateArgs(windowsServiceScriptPath()));
-  schtasks(["/run", "/tn", TASK]);
-  writeServiceInstallState("scheduler");
+  try { (deps.stopScheduler ?? stopWindows)(); } catch { /* not running */ }
+  (deps.writeSchedulerAssets ?? writeWindowsSchedulerAssets)(runtime);
+  const command = deps.schedulerCommand ?? schtasks;
+  command(buildWindowsSchtasksCreateArgs(windowsServiceScriptPath()));
+  command(["/run", "/tn", TASK]);
+  if (deps.writeState) deps.writeState("scheduler", runtime);
+  else writeServiceInstallState("scheduler", undefined, {}, runtime);
 }
 
 /**
@@ -748,26 +774,38 @@ function readWindowsPrincipalSource(): string | null {
   }
 }
 
-export async function installWindowsNative(): Promise<void> {
-  assertWindowsNativeServiceAccountSupported();
-  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
-  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
-  writeServiceApiTokenFile();
+export async function installWindowsNative(selected?: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): Promise<void> {
+  const runtime = Object.freeze({ ...(selected ?? (deps.selectRuntime ?? durableBunRuntime)()) });
+  const configDir = (deps.configDir ?? getConfigDir)();
+  (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform: deps.platform, rootWasAbsent: !existsSync(configDir) });
+  await commitWindowsNativeInstall(runtime, deps);
+}
+
+/** Internal commit boundary; direct native installs go through the public admission gate. */
+export async function commitWindowsNativeInstall(runtime: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): Promise<void> {
+  (deps.assertNativeAccount ?? assertWindowsNativeServiceAccountSupported)();
+  if (deps.prepareNativeConfig) deps.prepareNativeConfig();
+  else {
+    recordOwnedConfigPath(getConfigDir(), serviceStatePath());
+    if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+    writeServiceApiTokenFile();
+  }
+  const command = deps.schedulerCommand ?? schtasks;
   let hadScheduler = false;
   try {
-    hadScheduler = schtasks(["/query", "/tn", TASK]).includes(TASK);
+    hadScheduler = command(["/query", "/tn", TASK]).includes(TASK);
   } catch { /* task absent */ }
   if (hadScheduler) {
     console.log("🔁 Removing the Task Scheduler backend before installing the native (WinSW) service...");
-    try { stopWindows(); } catch { /* not running */ }
+    try { (deps.stopScheduler ?? stopWindows)(); } catch { /* not running */ }
     try {
-      uninstallWindows();
+      (deps.uninstallScheduler ?? uninstallWindows)();
     } catch (err) {
       throw new Error(`Cannot remove the Task Scheduler backend before switching to native: ${err instanceof Error ? err.message : String(err)}`);
     }
     // Verify removal — schtasks /delete can silently fail if UAC or policy blocks it.
     try {
-      if (schtasks(["/query", "/tn", TASK]).includes(TASK)) {
+      if (command(["/query", "/tn", TASK]).includes(TASK)) {
         throw new Error("Task Scheduler backend still present after removal — aborting switch.");
       }
     } catch (e) {
@@ -776,12 +814,13 @@ export async function installWindowsNative(): Promise<void> {
     }
   }
   try {
-    await installWinswService(defaultWinswEntry(serviceSourceDir));
+    await (deps.installNativeService ?? installWinswService)(defaultWinswEntry(serviceSourceDir, runtime));
   } catch (err) {
     if (hadScheduler) console.error("⚠️  Native install failed AFTER removing the Task Scheduler backend — no service is installed now. Run `ocx service install` to restore the scheduler backend, or retry `--native`.");
     throw err;
   }
-  writeServiceInstallState("native");
+  if (deps.writeState) deps.writeState("native", runtime);
+  else writeServiceInstallState("native", undefined, {}, runtime);
 }
 
 export function startWindows(): void { schtasks(["/run", "/tn", TASK]); }

package/src/sidecar/anthropic-binding.ts

@@ -0,0 +1,79 @@
+import type { OcxConfig } from "../types";
+import type { AnthropicInstanceId } from "../providers/anthropic-instance-id";
+import { configuredAnthropicInstance } from "../providers/anthropic-instance";
+import { anthropicRoutingFor } from "../oauth/anthropic-routing";
+import { resolveAnthropicModelRouteForInstance, routeCandidates } from "../oauth/anthropic-model-routes";
+import type { OAuthAccessSnapshot } from "../oauth";
+import { AnthropicHelperUnavailableError } from "./auth";
+import { captureAnthropicPhysicalSendOwnership, anthropicPhysicalSendOwnershipIsCurrent } from "../oauth/anthropic-send-ownership";
+import { recordAnthropicAccountQuotaFromHeadersForInstance } from "../providers/quota/account-cache";
+import { captureConfigGeneration } from "../lib/state-store-sweeper";
+import { getAccountCredentialWithStatus } from "../oauth/store";
+import { bindAnthropicRefusalCredentialForSend } from "../oauth/anthropic-account-refusal";
+
+/** The one Messages URL builder shared by helper executors and the physical-send fence. */
+export function anthropicHelperMessagesUrl(baseUrl: string): string {
+  return `${baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "")}/v1/messages`;
+}
+
+/**
+ * Select the helper's account the way the legacy sidecar token path does: a read of the pool's
+ * selection for this model route, with no promotion. A helper never moves the active pointer and
+ * never consumes an operator's one-dispatch manual choice; the physical send is still fenced by
+ * the captured target/config, the account's credential generation and its send ownership.
+ */
+export async function resolveAnthropicHelperSnapshot(config: OcxConfig, instance: AnthropicInstanceId, model: string): Promise<OAuthAccessSnapshot> {
+  const target = config.providers[instance]?.baseUrl;
+  const assertConfigured = () => {
+    const provider = config.providers[instance];
+    if (!provider || provider.disabled || provider.authMode !== "oauth" || provider.adapter !== "anthropic"
+      || configuredAnthropicInstance(config, instance) !== instance || provider.baseUrl !== target) {
+      throw new AnthropicHelperUnavailableError(instance);
+    }
+  };
+  assertConfigured();
+  const routing = anthropicRoutingFor(instance);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const route = resolveAnthropicModelRouteForInstance(instance, config, model);
+    if (route.error) throw new AnthropicHelperUnavailableError(instance);
+    const selection = routing.resolveAnthropicAccountForSession(null, config, Date.now(), route.decision, model);
+    if (!selection.accountId) throw new AnthropicHelperUnavailableError(instance);
+    const snapshot = await routing.getAnthropicPoolAccessSnapshot(selection.accountId);
+    assertConfigured();
+    const current = resolveAnthropicModelRouteForInstance(instance, config, model);
+    if (current.error || JSON.stringify(current.decision) !== JSON.stringify(route.decision)) continue;
+    if (snapshot.provider === instance && snapshot.accountId === selection.accountId) return snapshot;
+  }
+  throw new AnthropicHelperUnavailableError(instance);
+}
+
+/** One physical helper send; reset replays call this boundary again with the same snapshot. */
+export async function fetchAnthropicHelper(
+  config: OcxConfig, snapshot: OAuthAccessSnapshot, model: string,
+  capturedTarget: string, url: string, init: RequestInit,
+): Promise<Response> {
+  const instance = snapshot.provider;
+  if (instance !== "anthropic" && instance !== "anthropic2") throw new Error("Invalid Anthropic helper instance");
+  const row = config.providers[instance];
+  const live = getAccountCredentialWithStatus(instance, snapshot.accountId);
+  if (!row || row.disabled || row.authMode !== "oauth" || row.adapter !== "anthropic"
+    || configuredAnthropicInstance(config, instance) !== instance || row.baseUrl !== capturedTarget
+    || url !== anthropicHelperMessagesUrl(capturedTarget) || !live || live.paused || live.needsReauth
+    || new Headers(init.headers).get("authorization") !== `Bearer ${snapshot.accessToken}`) {
+    throw new AnthropicHelperUnavailableError(instance);
+  }
+  const route = resolveAnthropicModelRouteForInstance(instance, config, model);
+  const routing = anthropicRoutingFor(instance);
+  if (route.error || !routeCandidates(routing.getEligibleAnthropicAccounts(Date.now(), model), route.decision).includes(snapshot.accountId)) {
+    throw new AnthropicHelperUnavailableError(instance);
+  }
+  const owner = captureAnthropicPhysicalSendOwnership(snapshot);
+  if (!owner) throw new AnthropicHelperUnavailableError(instance);
+  const writer = captureConfigGeneration();
+  const response = await fetch(url, init);
+  if (anthropicPhysicalSendOwnershipIsCurrent(owner)) {
+    recordAnthropicAccountQuotaFromHeadersForInstance(instance, snapshot.accountId, response.headers, writer, response.status, model);
+    bindAnthropicRefusalCredentialForSend(response, owner);
+  }
+  return response;
+}

package/src/sidecar/auth.ts

@@ -17,6 +17,73 @@ import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { isCodexAccountUsable } from "../codex/account-usability";
 import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "../codex/account-id";
 import { getAccountSet } from "../oauth/store";
+import { configuredAnthropicInstance, type AnthropicInstanceId } from "../providers/anthropic-instance";
+import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
+
+/**
+ * The parent request's pool for an inheriting helper. A missing or disabled row keeps the parent's
+ * identity, so a pool removed mid-request refuses instead of discovering another pool; only a present
+ * custom row that is not the builtin instance (an unmarked custom `anthropic2`) stops inheritance.
+ */
+export function inheritedAnthropicInstance(config: OcxConfig, parentProviderName: string | undefined): AnthropicInstanceId | undefined {
+  if (!isAnthropicInstanceId(parentProviderName)) return undefined;
+  const row = config.providers?.[parentProviderName];
+  if (!row || row.disabled === true) return parentProviderName;
+  return configuredAnthropicInstance(config, parentProviderName);
+}
+
+export class AnthropicHelperUnavailableError extends Error {
+  readonly code = "anthropic_helper_unavailable";
+  constructor(readonly instance: AnthropicInstanceId) {
+    super(`The selected ${instance} helper account pool is unavailable`);
+    this.name = "AnthropicHelperUnavailableError";
+  }
+}
+export type AnthropicHelperContext = {
+  backendFamily: string;
+  anthropicInstance?: AnthropicInstanceId;
+  parentProviderName?: string;
+};
+
+/**
+ * Availability of one selected pool: the configured builtin row plus at least one stored account the
+ * pool could select. Which account actually sends (model route, cooldown, manual choice) is decided
+ * by snapshot resolution at send time, exactly as the main request path does, so a paused or
+ * reauth-pending ACTIVE account does not make a pool with another usable account unavailable.
+ */
+export function resolveAnthropicSidecarAuth(config: OcxConfig, instance: AnthropicInstanceId):
+  { anthropicProviderName: AnthropicInstanceId; anthropicProvider: OcxProviderConfig } | undefined {
+  const provider = config.providers[instance];
+  if (!provider || provider.disabled || provider.authMode !== "oauth" || provider.adapter !== "anthropic"
+    || configuredAnthropicInstance(config, instance) !== instance) return undefined;
+  if (!getAccountSet(instance)?.accounts.some(row => row.paused !== true && row.needsReauth !== true)) return undefined;
+  return { anthropicProviderName: instance, anthropicProvider: provider };
+}
+
+/**
+ * Explicit target, then the parent's CONFIGURED builtin instance. The parent name alone is not
+ * enough: a custom provider that happens to be named `anthropic2` is not Pool 2 and is never inherited.
+ */
+export function resolveAnthropicHelperInstance(config: OcxConfig, context: AnthropicHelperContext): AnthropicInstanceId | undefined {
+  if (context.backendFamily !== "anthropic") return undefined;
+  const instance = context.anthropicInstance ?? inheritedAnthropicInstance(config, context.parentProviderName);
+  if (instance && !resolveAnthropicSidecarAuth(config, instance)) throw new AnthropicHelperUnavailableError(instance);
+  return instance;
+}
+
+/**
+ * Planner boundary for the typed refusal: an unavailable selected pool means "this helper does not
+ * run", never "fail the main request" and never "discover another pool". Other errors propagate.
+ */
+export function withAnthropicHelperRefusal<T>(surface: string, resolve: () => T): T | undefined {
+  try {
+    return resolve();
+  } catch (error) {
+    if (!(error instanceof AnthropicHelperUnavailableError)) throw error;
+    console.warn(`[${surface}] ${error.message}; the request continues without this helper`);
+    return undefined;
+  }
+}
 
 export interface SidecarAuthState {
   /** ChatGPT login usable: canonical forward provider AND a live stored credential. */
@@ -63,6 +130,10 @@ function findAnthropicAuthProvider(
   config: OcxConfig,
 ): { providerName: string; provider: OcxProviderConfig } | undefined {
   for (const [providerName, provider] of Object.entries(config.providers)) {
+    // Never adds Pool 2 automatically. The OAuth store key `anthropic2` belongs to the builtin pool:
+    // its token path and the token guardian refuse an unmarked row of that name, so offering such a
+    // custom row here would advertise credentials no helper executor will spend.
+    if (providerName === "anthropic2") continue;
     if (provider.disabled === true) continue;
     if (provider.adapter !== "anthropic" || provider.authMode !== "oauth") continue;
     const set = getAccountSet(providerName);
@@ -72,8 +143,11 @@ function findAnthropicAuthProvider(
   return undefined;
 }
 
-export function resolveSidecarAuth(config: OcxConfig): SidecarAuthState {
-  const anthropic = findAnthropicAuthProvider(config);
+export function resolveSidecarAuth(config: OcxConfig, instance?: AnthropicInstanceId): SidecarAuthState {
+  const exact = instance ? resolveAnthropicSidecarAuth(config, instance) : undefined;
+  if (instance && !exact) throw new AnthropicHelperUnavailableError(instance);
+  const anthropic = exact ? { providerName: exact.anthropicProviderName, provider: exact.anthropicProvider }
+    : findAnthropicAuthProvider(config);
   return {
     isCodexAuth: hasUsableCodexLogin(config),
     isAnthropicAuth: anthropic !== undefined,

package/src/storage/policy-job.ts

@@ -65,6 +65,8 @@ export interface PolicyJobTestHooks {
    * policy load, so concurrent PUTs can race completion metadata writes.
    */
   blockMs?: number;
+  /** Test-only shared barrier after the Worker has loaded its initial policy. */
+  workerLoadGate?: Int32Array;
   /**
    * When true, run on the main thread via `queueMicrotask` + optional sleep.
    * Used only for unit tests that cannot spawn workers; responsiveness tests
@@ -304,7 +306,7 @@ function applyMutationBusy(): void {
   };
 }
 
-function runInWorker(opts: RequestPolicyRunOptions & { blockMs?: number }): Promise<PolicyRunResult> {
+function runInWorker(opts: RequestPolicyRunOptions & { blockMs?: number; workerLoadGate?: Int32Array }): Promise<PolicyRunResult> {
   const reservation = tryReserveStorageWorker();
   if (!reservation) return Promise.reject(new StorageWorkerAdmissionBusyError());
   return withStorageWorkerSpawnGate(() => new Promise<PolicyRunResult>((resolve, reject) => {
@@ -369,6 +371,7 @@ function runInWorker(opts: RequestPolicyRunOptions & { blockMs?: number }): Prom
       ...(opts.codexHome ? { codexHome: opts.codexHome } : {}),
       ...(opts.busyTimeoutMs !== undefined ? { busyTimeoutMs: opts.busyTimeoutMs } : {}),
       ...(opts.blockMs !== undefined ? { blockMs: opts.blockMs } : {}),
+      ...(opts.workerLoadGate ? { workerLoadGate: opts.workerLoadGate } : {}),
       env: {
         ...(process.env.CODEX_HOME ? { CODEX_HOME: process.env.CODEX_HOME } : {}),
         ...(process.env.OPENCODEX_HOME ? { OPENCODEX_HOME: process.env.OPENCODEX_HOME } : {}),
@@ -410,6 +413,7 @@ async function executeJob(opts: RequestPolicyRunOptions): Promise<void> {
         ...opts,
         codexHome,
         ...(typeof blockMs === "number" && blockMs > 0 ? { blockMs } : {}),
+        ...(testHooks?.workerLoadGate ? { workerLoadGate: testHooks.workerLoadGate } : {}),
       });
     }
 

package/src/storage/policy-worker.ts

@@ -13,6 +13,7 @@ interface RunMessage {
   busyTimeoutMs?: number;
   /** Test-only: block after loading the start-of-job policy (see holdAfterLoadMs). */
   blockMs?: number;
+  workerLoadGate?: Int32Array;
   /** Env snapshot — Workers may not see parent mutations on all platforms. */
   env?: { CODEX_HOME?: string; OPENCODEX_HOME?: string };
 }
@@ -29,7 +30,7 @@ declare const self: Worker;
 
 self.onmessage = (event: MessageEvent<unknown>) => {
   if (!isRunMessage(event.data)) return;
-  const { requestId, reason, force, codexHome, busyTimeoutMs, blockMs, env } = event.data;
+  const { requestId, reason, force, codexHome, busyTimeoutMs, blockMs, workerLoadGate, env } = event.data;
   try {
     if (env?.CODEX_HOME) process.env.CODEX_HOME = env.CODEX_HOME;
     if (env?.OPENCODEX_HOME) process.env.OPENCODEX_HOME = env.OPENCODEX_HOME;
@@ -38,6 +39,7 @@ self.onmessage = (event: MessageEvent<unknown>) => {
       force: force === true,
       ...(codexHome ? { codexHome } : {}),
       ...(busyTimeoutMs !== undefined ? { busyTimeoutMs } : {}),
+      ...(workerLoadGate ? { holdAfterLoadGate: workerLoadGate } : {}),
       ...(typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0
         ? { holdAfterLoadMs: Math.floor(blockMs) }
         : {}),

package/src/storage/policy.ts

@@ -74,6 +74,8 @@ export interface PolicyRunDeps {
    * land before completion merges run metadata.
    */
   holdAfterLoadMs?: number;
+  /** Test-only Worker barrier: 0=pending, 1=policy loaded, 2=released. */
+  holdAfterLoadGate?: Int32Array;
 }
 
 /** Canonical defaults — enabled is always false. */
@@ -500,6 +502,13 @@ export function runStorageCleanupPolicy(deps: PolicyRunDeps): PolicyRunResult {
       })
     : (patch: PolicyRunMetadataPatch) => commitPolicyRunMetadataToConfig(patch, policy);
 
+  if (deps.holdAfterLoadGate) {
+    Atomics.compareExchange(deps.holdAfterLoadGate, 0, 0, 1);
+    Atomics.notify(deps.holdAfterLoadGate, 0);
+    if (Atomics.wait(deps.holdAfterLoadGate, 0, 1, 10_000) === "timed-out") {
+      throw new Error("policy_test_load_gate_timeout");
+    }
+  }
   if (typeof deps.holdAfterLoadMs === "number" && Number.isFinite(deps.holdAfterLoadMs) && deps.holdAfterLoadMs > 0) {
     Bun.sleepSync(Math.floor(deps.holdAfterLoadMs));
   }

package/src/types/anthropic-account-pool.ts

@@ -0,0 +1,33 @@
+/**
+ * Anthropic OAuth account-pool settings. One shape, two locations:
+ * `config.anthropicAccountPool` for the `anthropic` instance and
+ * `config.providers.anthropic2.anthropicAccountPool` for `anthropic2`. Neither inherits from the other.
+ *
+ * Leaf module: `config.ts` and `provider.ts` import these types, never the reverse.
+ */
+export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
+
+export type OcxAccountPoolQuotaWindow = "five-hour" | "weekly" | "max-utilization";
+
+export interface AnthropicModelRoute {
+  name: string;
+  match: string;
+  accounts: string[];
+  fallback?: boolean;
+}
+
+export interface AnthropicAccountPoolConfig {
+  enabled?: boolean;
+  /** Preserve native Claude Messages while the pool is enabled. Default true; false selects legacy translation. */
+  nativeMessages?: boolean;
+  /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
+  autoSwitchThreshold?: number;
+  /** New-session rotation strategy. Default quota (today's behaviour). */
+  strategy?: OcxAccountPoolRotationStrategy;
+  /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
+  stickyLimit?: number;
+  /** Usage window for quota-based scoring. Default "five-hour" (today's behaviour). */
+  quotaWindow?: OcxAccountPoolQuotaWindow;
+  /** Ordered model allowlists; inactive while the pool is disabled. Stored account IDs only. */
+  routes?: AnthropicModelRoute[];
+}