@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/server/workflow-refusal.ts

@@ -5,6 +5,10 @@
  * check in `src/server/index.ts` and the pre-dispatch ceiling check in
  * `src/server/responses/core.ts` -- had drifted into saying different things about the same
  * refusal, and because the non-obvious part below has to be stated once and not twice.
+ *
+ * The HTTP admission DECISION lives here too, for the same reason: the lane derivation and the
+ * refusal it produces are two halves of one answer, and keeping them in one file is what stops
+ * a denial from losing the detail that makes it legible on the way out.
  */
 import { formatErrorResponse } from "../bridge";
 import {
@@ -14,9 +18,13 @@ import {
 } from "./request-log";
 import {
   WORKFLOW_LOCAL_REFUSAL_HEADER,
+  admitWorkflowTurn,
   workflowDenialSummary,
   recordWorkflowRefusalEvent,
   type WorkflowDenial,
+  type WorkflowDecision,
+  type WorkflowLane,
+  type WorkflowSpendDenialDetail,
 } from "../lib/workflow-budget";
 
 /**
@@ -54,11 +62,16 @@ export function workflowRefusalResponse(
   logCtx?: RequestLogContext,
   refusalLog?: WorkflowRefusalLog,
   rootId?: string,
+  spend?: WorkflowSpendDenialDetail,
 ): Response {
-  const summary = workflowDenialSummary(reason);
+  // The denial detail, when the caller has it, is what turns "a token ceiling refused this"
+  // into "the account ceiling of 100,000 is spent". It reaches the message, the event ring and
+  // the log row through this one function, so the three cannot drift into saying different
+  // things about the same refusal -- which is what put this module here in the first place.
+  const summary = workflowDenialSummary(reason, spend);
   // Only a caller that decided the refusal ITSELF passes a root id. admitWorkflowTurn already
   // records its own denials, so passing one there would double-count them.
-  if (rootId) recordWorkflowRefusalEvent(rootId, reason);
+  if (rootId) recordWorkflowRefusalEvent(rootId, reason, Date.now(), spend);
   const recordOn = logCtx ?? refusalLog?.logCtx;
   if (recordOn) {
     markLocalRequestLogRefusal(recordOn, summary.code);
@@ -82,3 +95,44 @@ export function workflowRefusalResponse(
   refusal.headers.set("Access-Control-Expose-Headers", WORKFLOW_LOCAL_REFUSAL_HEADER);
   return refusal;
 }
+
+/**
+ * Admit one HTTP turn against its root workflow budget.
+ *
+ * A fan-out shares the conversation it serves. Without a reserve, a worker burst takes every
+ * slot under its own root and the interactive turn that started it waits behind its own
+ * children. A request that names a parent is treated as that fan-out; a top-level request is
+ * the conversation and may use the reserved slots.
+ */
+export function admitHttpWorkflowTurn(headers: Headers): WorkflowDecision | undefined {
+  const rootId = headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  const threadId = headers.get("thread-id")?.trim() || undefined;
+  const lane: WorkflowLane = rootId !== undefined && threadId !== undefined && threadId !== rootId
+    ? "worker"
+    : "interactive";
+  return admitWorkflowTurn(rootId, lane, undefined, threadId);
+}
+
+/**
+ * The refusal for a decision {@link admitHttpWorkflowTurn} declined.
+ *
+ * It exists so the denial's own detail survives the trip to the wire. A token-ceiling denial
+ * arrives carrying the scope that refused and the number it refused against, and a caller that
+ * forwarded only `reason` would answer with a 429 that names no ceiling -- which is the
+ * illegible refusal this whole path is built to avoid. No root id is passed on: the admission
+ * check already recorded its own event, and passing one would count the refusal twice.
+ */
+export function workflowDecisionRefusalResponse(
+  decision: Extract<WorkflowDecision, { admitted: false }>,
+  logCtx?: RequestLogContext,
+  refusalLog?: WorkflowRefusalLog,
+): Response {
+  const spend = decision.spendScope !== undefined && decision.spendLimit !== undefined
+    ? {
+      scope: decision.spendScope,
+      limit: decision.spendLimit,
+      ...(decision.spendProjected !== undefined ? { projected: decision.spendProjected } : {}),
+    }
+    : undefined;
+  return workflowRefusalResponse(decision.reason, logCtx, refusalLog, undefined, spend);
+}

package/src/service/cli.ts

@@ -197,23 +197,28 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     assertServiceAuthEnvironment();
     // A throw used to escape straight to the top level, so the one command that can
     // leave a macOS hub evicted never reached its own serving check (#4236, defect 1f).
-    // Report the failure, then still ask whether anything is listening: on darwin the
-    // rollback inside installLaunchd may have brought the previous job back, and on
-    // Windows the preserve/restart protocol may have done the same. The operator needs
-    // both halves of that answer, and the exit code stays non-zero either way.
+    // Still ask whether anything is listening: on darwin the rollback inside installLaunchd
+    // may have brought the previous job back, and on Windows the preserve/restart protocol
+    // may have done the same. The operator needs both halves of that answer, and the exit
+    // code stays non-zero either way.
+    //
+    // The failure text travels INTO that report rather than being printed here. Printing it
+    // here and then letting the report reach its success line stated both outcomes for one
+    // run — "❌ Service repair failed: ... exit code 199" beside "✅ opencodex service
+    // repaired and serving on port 10100" — and the checkmark was the false half: the
+    // existing registration had been restarted, not repaired (#4914).
     let repairError: unknown;
     try {
       await repairService({ verb });
     } catch (error) {
       repairError = error;
-      console.error(`❌ Service ${verb} failed: ${error instanceof Error ? error.message : String(error)}`);
       process.exitCode = 1;
     }
     // All three platforms: a repair that reports success while nothing serves is the
     // defect class this unit exists to close. Windows bakes its port into the
     // scheduler wrapper or the WinSW XML, both of which installedServiceListenPort()
     // now reads.
-    await reportServiceServing(verb === "restart" ? "restarted" : "repaired");
+    await reportServiceServing(verb === "restart" ? "restarted" : "repaired", {}, repairError);
     if (repairError !== undefined) process.exitCode = 1;
     return;
   }
@@ -265,6 +270,11 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       await maybeShowStarPrompt();
       break;
     case "start":
+      // The installed launcher preserves the recorded CODEX_SQLITE_HOME: a
+      // changed sqlite_home/CODEX_SQLITE_HOME/CODEX_HOME would start the service
+      // on the recorded database while this shell resolves another, splitting
+      // native Codex history between databases. Same guard `stop` already runs.
+      assertServiceEnvironmentMatchesInstall();
       ops.start();
       await reportServiceServing("started");
       break;

package/src/service/guards.ts

@@ -10,6 +10,7 @@ import { isTestHomeGuardArmed } from "../lib/test-home-guard";
 import { diagnoseService } from "./diagnostics";
 import type { ServiceDiagnostic } from "./diagnostics";
 import { currentCodexHome, currentOpenCodexHome, normalizePathForCompare, readServiceInstallState } from "./state";
+import { resolveCodexSqliteHome } from "../codex/paths";
 import { win32 } from "node:path";
 
 /**
@@ -61,6 +62,15 @@ export function assertServiceEnvironmentMatchesInstall(): void {
         "Run the service command from the same OpenCodex home so service state and secrets match.",
     );
   }
+  if (state.codexSqliteHome !== undefined) {
+    const actualCodexSqliteHome = resolveCodexSqliteHome({ codexHome: actualCodexHome });
+    if (normalizePathForCompare(state.codexSqliteHome) !== normalizePathForCompare(actualCodexSqliteHome)) {
+      throw new ServiceOwnershipError(
+        `Service was installed with Codex SQLite home=${state.codexSqliteHome}, but the current Codex SQLite home=${actualCodexSqliteHome}. ` +
+          "Run the service command with the same sqlite_home configuration and CODEX_SQLITE_HOME so native Codex history restore updates the correct database.",
+      );
+    }
+  }
 }
 
 function isLoopbackHostname(hostname: string | undefined): boolean {

package/src/service/health.ts

@@ -148,6 +148,19 @@ export async function confirmServiceServing(
   return { ok: false, port };
 }
 
+/**
+ * The operation, as a noun, for a sentence that has to say it did not complete.
+ *
+ * The verb form reads as an accomplished fact ("service repaired"), which is exactly the
+ * claim that must not be made when the operation threw.
+ */
+const SERVICE_OPERATION_NOUN = {
+  installed: "install",
+  started: "start",
+  repaired: "repair",
+  restarted: "restart",
+} as const;
+
 /**
  * Print the outcome of `install` / `start` / `repair` in terms of what the user cares
  * about — is it serving? — instead of whether the manager accepted the registration.
@@ -156,10 +169,18 @@ export async function confirmServiceServing(
  * worker reads the child's exit status, so a registered-but-silent service now makes it
  * fall back to a direct proxy start rather than reporting a successful update over a
  * dead port.
+ *
+ * `precedingFailure` is the error the operation itself threw, when it threw. The serving
+ * probe still runs — a rollback or a preserve/restart protocol may well have left the
+ * previous job answering, and the operator needs that half of the answer (#4236). But the
+ * two halves have to be ONE sentence. Printing the failure separately and then reaching
+ * the success line here reported both outcomes for the same run and credited work that did
+ * not happen: the registration was kept, not repaired (#4914).
  */
 export async function reportServiceServing(
   verb: "installed" | "started" | "repaired" | "restarted",
   deps: Parameters<typeof confirmServiceServing>[0] = {},
+  precedingFailure?: unknown,
 ): Promise<void> {
   const healthBudgetMs = deps.timeoutMs ?? serviceInstallHealthMs();
   // Timed here rather than reported from the budget. confirmServiceServing knocks once
@@ -171,6 +192,28 @@ export async function reportServiceServing(
   const startedAt = now();
   const serving = await confirmServiceServing({ ...deps, timeoutMs: healthBudgetMs });
   const waitedMs = Math.max(0, now() - startedAt);
+  const failureDetail = precedingFailure === undefined
+    ? null
+    : precedingFailure instanceof Error ? precedingFailure.message : String(precedingFailure);
+  const operation = SERVICE_OPERATION_NOUN[verb];
+  if (failureDetail !== null) {
+    // Serving or not, the operation did not complete, so neither branch may print a
+    // checkmark. What differs is whether anything is answering, which is the fact the
+    // operator acts on next.
+    console.error(
+      serving.ok
+        ? `⚠️  Service ${operation} did not complete: ${failureDetail}\n`
+          + `   A proxy is answering on port ${serving.port}, so the existing registration was kept rather than replaced.\n`
+          + `   The ${operation} did not take effect; rerun it once the reported cause is resolved.\n`
+          + `   Log:       ${serviceLogPath()}`
+        : `❌ Service ${operation} failed: ${failureDetail}\n`
+          + `   No proxy answered on port ${serving.port} after ${Math.round(waitedMs / 1000)}s either.\n`
+          + `   Log:       ${serviceLogPath()}\n`
+          + `   Meanwhile: ocx start   (serves in the foreground)`,
+    );
+    process.exitCode = 1;
+    return;
+  }
   if (serving.ok) {
     console.log(`✅ opencodex service ${verb} and serving on port ${serving.port}.`);
     return;

package/src/service/state.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
 import { resolveCodexHomeDir, type CodexHomeDeps } from "../codex/home";
+import { resolveCodexSqliteHome } from "../codex/paths";
 import { durableBunRuntime, type BunRuntimeSource, type DurableBunRuntime } from "../lib/bun-runtime";
 import { WINSW_SHA256, WINSW_VERSION } from "../lib/winsw";
 import { hardenSecretPath } from "../lib/windows-secret-acl";
@@ -218,6 +219,8 @@ export interface ServiceInstallState {
   version: 1 | 2;
   codexHome: string;
   opencodexHome: string;
+  /** Effective Codex SQLite home used by this service's history integration. */
+  codexSqliteHome?: string;
   /** Baked at install; lets status flag paths gone stale after npm prefix/nvm moves. */
   bunPath?: string;
   cliPath?: string;
@@ -241,7 +244,7 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
   if (state.version !== 1 && state.version !== 2) return null;
   if (typeof state.codexHome !== "string" || state.codexHome.length === 0) return null;
   if (typeof state.opencodexHome !== "string" || state.opencodexHome.length === 0) return null;
-  for (const key of ["bunPath", "cliPath", "launcherPath", "winswVersion", "winswSha256"] as const) {
+  for (const key of ["codexSqliteHome", "bunPath", "cliPath", "launcherPath", "winswVersion", "winswSha256"] as const) {
     if (state[key] !== undefined && (typeof state[key] !== "string" || state[key].length === 0)) return null;
   }
   if (state.version === 1) {
@@ -254,10 +257,12 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
 
 export function writeServiceInstallState(backend: ServiceBackend = "scheduler", launcherPath?: string | null): void {
   const { bun, cli } = cliEntry();
+  const codexHome = currentCodexHome();
   const state: ServiceInstallState = {
     version: 2,
-    codexHome: currentCodexHome(),
+    codexHome,
     opencodexHome: currentOpenCodexHome(),
+    codexSqliteHome: resolveCodexSqliteHome({ codexHome }),
     bunPath: bun,
     cliPath: cli,
     ...(launcherPath ? { launcherPath } : {}),

package/src/tray/windows-tray.ps1

@@ -116,6 +116,88 @@ function Start-OcxCommand([string[]]$CommandArgs, [switch]$TrackExit) {
   }
 }
 
+function Parse-StartupHealthText([string]$Text) {
+  foreach ($line in ($Text -split "\r?\n")) {
+    $trimmed = $line.Trim()
+    if (-not $trimmed) { continue }
+    try {
+      $parsed = $trimmed | ConvertFrom-Json
+      if ($parsed.status -in @("native", "protected", "at-risk") -and ($parsed.rebootSafe -is [bool])) {
+        return $parsed
+      }
+    } catch {
+      # A non-JSON line from the CLI (for example a diagnostic banner) is not a
+      # startup-health payload; keep scanning for the actual JSON result.
+      continue
+    }
+  }
+  return $null
+}
+
+function Start-StartupHealthProbe {
+  # Startup safety is machine-local diagnostic state, so the tray asks the CLI to
+  # collect it directly (ocx __startup-health) instead of poking the management API,
+  # which is admin-token gated. The CLI collects the diagnostic straight from the OS,
+  # so it works without the proxy answering and without any credential.
+  #
+  # The child writes into redirected pipes that the tick reads asynchronously: only
+  # the completed Task<string> is ever touched, so a slow or hung diagnostic can never
+  # block the Windows Forms UI thread, and its lifetime is bounded by a kill in the
+  # tick that lets the next refresh replace it instead of stacking another process.
+  try {
+    $psi = New-Object System.Diagnostics.ProcessStartInfo
+    $psi.FileName = $BunPath
+    $psi.Arguments = ((@($CliPath, "__startup-health") | ForEach-Object { ConvertTo-NativeArgument $_ }) -join " ")
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
+    $psi.StandardErrorEncoding = [System.Text.Encoding]::UTF8
+    $psi.EnvironmentVariables["CODEX_HOME"] = $CodexHome
+    $psi.EnvironmentVariables["OPENCODEX_HOME"] = $OpenCodexHome
+    if ($BunRuntimeSource) {
+      $psi.EnvironmentVariables["OCX_BUN_RUNTIME_SOURCE"] = $BunRuntimeSource
+      $psi.EnvironmentVariables["OCX_BUN_RUNTIME_PATH"] = $BunPath
+    }
+    $process = [System.Diagnostics.Process]::Start($psi)
+    $script:startupProbeProcess = $process
+    # Drain both pipes asynchronously from the start so neither can fill and stall
+    # the child while the tick is only watching the output task's completion.
+    $script:startupProbeOutputTask = $process.StandardOutput.ReadToEndAsync()
+    $script:startupProbeErrorTask = $process.StandardError.ReadToEndAsync()
+    $script:startupProbeStarted = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  } catch {
+    Write-ActionLog "startup-health probe launch failed: $($_.Exception.GetType().Name)"
+    if ($null -ne $script:startupProbeProcess) {
+      # Process.Start succeeded but the async pipe setup failed: Dispose alone
+      # would leave the Bun child running, so terminate it before cleanup.
+      try {
+        $script:startupProbeProcess.Kill()
+        [void]$script:startupProbeProcess.WaitForExit(3000)
+      } catch {
+        Write-ActionLog "startup-health probe launch cleanup failed: $($_.Exception.GetType().Name)"
+      }
+    }
+    Complete-StartupHealthProbe
+  }
+}
+
+function Complete-StartupHealthProbe {
+  $process = $script:startupProbeProcess
+  $script:startupProbeProcess = $null
+  $script:startupProbeOutputTask = $null
+  $script:startupProbeErrorTask = $null
+  if ($null -ne $process) {
+    try {
+      $process.Dispose()
+    } catch {
+      Write-ActionLog "startup-health probe dispose failed: $($_.Exception.GetType().Name)"
+    }
+  }
+}
+
 function Read-ListenTarget {
   foreach ($path in @((Join-Path $OpenCodexHome "runtime-port.json"), (Join-Path $OpenCodexHome "config.json"))) {
     try {
@@ -172,6 +254,15 @@ $exitItem = $menu.Items.Add("Exit Tray")
 $script:online = $false
 $script:port = 10100
 $script:proxyPid = $null
+$script:wasOnline = $false
+$script:startupHealth = $null
+$script:startupHealthCheckedAt = 0L
+$script:startupRefreshMs = 20000L
+$script:startupProbeProcess = $null
+$script:startupProbeOutputTask = $null
+$script:startupProbeErrorTask = $null
+$script:startupProbeStarted = 0L
+$script:startupProbeTimeoutMs = 30000L
 $script:pendingAction = $null
 $script:pendingStarted = 0L
 $script:pendingDeadline = 0L
@@ -228,18 +319,66 @@ function Update-TrayState {
   $pidMatches = $null -eq $target.pid -or [int]$target.pid -eq [int]$health.pid
   $script:online = $null -ne $health -and $health.status -eq "ok" -and $health.service -eq "opencodex" -and [int]$health.port -eq $script:port -and $pidMatches
   $script:proxyPid = if ($script:online) { [int]$health.pid } else { $null }
+  $cameOnline = $script:online -and -not $script:wasOnline
+  $script:wasOnline = $script:online
+  $now = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  if ($null -ne $script:startupProbeProcess) {
+    $probeExited = $false
+    try {
+      $probeExited = $script:startupProbeProcess.HasExited
+    } catch {
+      $probeExited = $true
+    }
+    $probeTimedOut = ($now - $script:startupProbeStarted) -gt $script:startupProbeTimeoutMs
+    if ($probeExited -and $null -ne $script:startupProbeOutputTask -and $script:startupProbeOutputTask.IsCompleted) {
+      $probeStartup = $null
+      try {
+        $probeStartup = Parse-StartupHealthText $script:startupProbeOutputTask.Result
+      } catch {
+        Write-ActionLog "startup-health probe read failed: $($_.Exception.GetType().Name)"
+      }
+      $script:startupHealth = $probeStartup
+      Complete-StartupHealthProbe
+      $script:startupHealthCheckedAt = $now
+    } elseif ($probeTimedOut) {
+      # A hung diagnostic must not survive its refresh slot: terminate it so the
+      # next refresh cannot stack another orphaned Bun process behind it.
+      Write-ActionLog "startup-health probe timed out; terminating it"
+      try {
+        $script:startupProbeProcess.Kill()
+        [void]$script:startupProbeProcess.WaitForExit(3000)
+      } catch {
+        Write-ActionLog "startup-health probe kill failed: $($_.Exception.GetType().Name)"
+      }
+      $script:startupHealth = $null
+      Complete-StartupHealthProbe
+      $script:startupHealthCheckedAt = $now
+    }
+  }
+  $refreshDue =
+    $script:startupHealthCheckedAt -eq 0 -or
+    ($now - $script:startupHealthCheckedAt -gt $script:startupRefreshMs)
+  if ($script:online -and ($cameOnline -or $refreshDue) -and $null -eq $script:startupProbeProcess) {
+    # Record the attempt so launch failures and invalid results remain throttled.
+    $script:startupHealthCheckedAt = $now
+    Start-StartupHealthProbe
+  }
   if ($script:online) {
     $statusItem.Text = "Proxy: Online (port $($script:port))"
     $notify.Text = "opencodex: Online"
     $startItem.Enabled = $false
     $stopItem.Enabled = $true
     $restartItem.Enabled = $true
-    try {
-      $startup = Read-JsonUrl "$origin/api/startup-health"
+    # The management API is admin-token gated, so the tray must not poke
+    # /api/startup-health for the icon. The probe lifecycle maintenance and the
+    # refresh gate above run on every tick (even while offline) so a hung
+    # diagnostic is cleaned up outside the online-only UI branch.
+    $startup = $script:startupHealth
+    if ($null -ne $startup) {
       $label = if ($startup.status -eq "at-risk") { "At risk" } elseif ($startup.status -eq "protected") { "Protected" } else { "Native routing" }
       $safetyItem.Text = "Restart safety: $label"
       $notify.Icon = if ($startup.status -eq "at-risk") { $warningIcon } else { $onlineIcon }
-    } catch {
+    } else {
       $safetyItem.Text = "Restart safety: unavailable"
       $notify.Icon = $warningIcon
     }
@@ -360,6 +499,19 @@ try {
   if ($null -ne $script:pendingProcess) {
     try { $script:pendingProcess.Dispose() } catch { $null = $_ }
   }
+  if ($null -ne $script:startupProbeProcess) {
+    # A probe still running when the tray shuts down would outlive it: Dispose()
+    # releases the handle but does not terminate the child, so kill the active
+    # probe, wait briefly for exit, then release the probe state.
+    try {
+      Write-ActionLog "terminating active startup-health probe on tray shutdown"
+      $script:startupProbeProcess.Kill()
+      [void]$script:startupProbeProcess.WaitForExit(3000)
+    } catch {
+      Write-ActionLog "startup-health probe shutdown kill failed: $($_.Exception.GetType().Name)"
+    }
+    Complete-StartupHealthProbe
+  }
   $notify.Dispose()
   foreach ($icon in $script:ownedIcons) { $icon.Dispose() }
   $menu.Dispose()

package/src/types/accounts.ts

@@ -19,6 +19,10 @@ export interface CodexAccount {
 }
 
 export interface CodexAccountCredentials {
+  /** Read-only Orca auth.json link; Orca exclusively owns OAuth refresh. */
+  sourceAuthPath?: string;
+  /** Bind the link to the originally imported OAuth subject. */
+  sourceSubject?: string;
   accessToken: string;
   refreshToken: string;
   expiresAt: number;

package/src/types/config.ts

@@ -93,6 +93,31 @@ export interface OcxClaudeCodeConfig {
    * forcing effort on every request can leak reasoning params to non-reasoning routes.
    */
   alwaysEnableEffort?: boolean;
+  /**
+   * Opt-in ENABLE_TOOL_SEARCH injection for launched Claude Code sessions (#4838).
+   *
+   * Claude Code turns MCP tool deferral off whenever ANTHROPIC_BASE_URL names a
+   * non-first-party host, so an `ocx claude` session ships every tool schema in
+   * full on every request. Its own diagnostic states the precondition for turning
+   * that back on: "Set ENABLE_TOOL_SEARCH=true (or auto / auto:N) if your proxy
+   * forwards tool_reference blocks."
+   *
+   * Default OFF, because opencodex only forwards them on the NATIVE ANTHROPIC
+   * PASSTHROUGH route, where the body reaches Anthropic untouched. On a translated
+   * route the deferral shape is not representable: compatibility.ts marks
+   * tool_search/tool_reference/deferred_tools unsupported, and toolsToResponses
+   * drops the tool_search server tool while ignoring defer_loading — deferred tools
+   * still carry input_schema on the wire, so the routed provider receives every
+   * schema anyway while Claude Code stops accounting for them and therefore stops
+   * compacting. Under `claudeCode.compatibility: "enforce"` the same request is
+   * rejected with 400 instead.
+   *
+   * `true` injects "true"; a string is passed through verbatim so Claude Code's own
+   * vocabulary (`auto`, `auto:N`, `force`) stays reachable. `false` and absent
+   * inject nothing — they do not force the variable off, because a value the
+   * operator exported themselves always wins.
+   */
+  toolSearch?: boolean | string;
   /**
    * Subagent tier slots (devlog 260712 B2): injected as ANTHROPIC_DEFAULT_*_MODEL so
    * Claude Code's Agent-tool aliases (opus/sonnet/haiku/fable + parent-inherit) route
@@ -378,6 +403,8 @@ export interface OcxConfig {
   client?: OcxClientConnectionConfig;
   /** Operator-facing redaction policy for management and CLI projections. */
   privacy?: OcxPrivacyConfig;
+  /** Opt-in process-local aggregate request metrics on the authenticated management plane. */
+  metricsExport?: { enabled?: boolean };
   /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
   emptyCompletionRetry?: boolean;
   /** Suppress allowlisted client-facing Codex transport hints; provider enforcement is unchanged. */
@@ -591,6 +618,12 @@ export interface OcxConfig {
   subagentEffortCap?: string;
   /** Global model effort overrides, after provider model/wide pins; none means omission. */
   modelPinnedEfforts?: Record<string, string>;
+  compactionRouting?: {
+    model: string;
+    reasoningEffort?: string;
+    /** Compaction triggers this override covers; omission means `["manual"]`. */
+    triggers?: ("manual" | "auto")[];
+  };
   /**
    * Models hidden from Codex discovery without blocking direct proxy calls. Routed provider ids
    * are excluded from the catalog + /v1/models entirely. Account-qualified native ids hide only
@@ -722,13 +755,15 @@ export interface OcxConfig {
     | { enabled: false }
     | { enabled: true; port?: number };
   /**
-   * Outbound HTTP(S) proxy URL for provider requests (e.g. "http://user:pass@proxy:8080", or
-   * "${HTTPS_PROXY}"-style env reference). Mirrored into HTTP_PROXY/HTTPS_PROXY at startup when
-   * those are unset — Bun's fetch honors them for all outbound calls; localhost is excluded.
+   * Outbound proxy URL for provider requests. HTTP(S) example: "http://user:pass@proxy:8080"
+   * or "${HTTPS_PROXY}". SOCKS5 example: "socks5://127.0.0.1:10808" (`ocx start --socks5`).
+   * HTTP URLs are mirrored into HTTP_PROXY/HTTPS_PROXY when unset. SOCKS5 URLs are mirrored
+   * into ALL_PROXY, clear inherited HTTP(S)_PROXY, and use OpenCodex's SOCKS5 transport.
+   * Loopback stays in NO_PROXY.
    * The literal `"auto"` reads the Windows WinINET static proxy (`ProxyEnable`/`ProxyServer`)
-   * once at process start; on other platforms, or when the system proxy is off, SOCKS-only,
-   * or unreadable, it degrades to direct egress with one log line (#1525). PAC/WPAD and live
-   * changes are not followed.
+   * once at process start, preserving separate HTTP and HTTPS entries; on other platforms, or
+   * when the system proxy is off, SOCKS-only, or unreadable, it degrades to direct egress with
+   * one log line (#1525). PAC/WPAD and live changes are not followed.
    */
   proxy?: string;
   /**
@@ -778,6 +813,20 @@ export interface OcxConfig {
    * built-in `openai` provider, so Codex does not select native remote compaction. Default off.
    */
   codexClientCompaction?: boolean;
+  /**
+   * Label Codex shows for the injected `opencodex` provider. Defaults to `OpenCodex Proxy`.
+   *
+   * Presentation only. Routing is keyed on the provider id `opencodex` — the root
+   * `model_provider = "opencodex"` line and the `[model_providers.opencodex]` header — and this
+   * setting never touches either, so renaming the label cannot reroute or orphan a thread whose
+   * row already names that id.
+   *
+   * There is no way to emit an empty label: Codex rejects a provider with no name, so a blank,
+   * over-long, or control-character value falls back to the default rather than writing a config
+   * Codex would refuse to load. "Suppressing" the OpenCodex branding therefore means choosing a
+   * neutral label, not removing the field.
+   */
+  codexProviderDisplayName?: string;
   /**
    * Compatibility mode: temporarily rewrite Codex resume-history metadata while the proxy is active
    * so Codex App can show old OpenAI chats and opencodex-created exec chats under its default
@@ -811,6 +860,16 @@ export interface OcxConfig {
    * absence is the only default state this policy has.
    */
   codexPool?: OcxCodexPoolConfig;
+  /**
+   * Durable token ceilings for the spend-reservation ledger (#4546). Absent means the
+   * historical behaviour exactly: token spend is still accounted and journalled, and nothing
+   * is refused on it.
+   *
+   * Not in `getDefaultConfig()` on purpose, and deliberately shipped with no default figure.
+   * The ledger is on by default, so a default ceiling would start refusing real traffic on
+   * upgrade against a number nobody chose.
+   */
+  spend?: OcxSpendConfig;
   /** Opt-in per-account activation of newly reset Codex quota windows. */
   codexQuotaAutoRefresh?: Record<string, {
     fiveHour?: boolean;
@@ -1385,3 +1444,49 @@ export interface OcxCatalogAutoRefreshConfig {
    */
   intervalMinutes?: number;
 }
+
+/**
+ * One scope's token ceiling.
+ *
+ * An object rather than a bare number because the ledger's scope limit is already a record in
+ * `SpendReservationPolicy`, and a config shape that mirrors the runtime one cannot drift from
+ * it silently. Absent `maxTokens` is the same as an absent scope: observe only.
+ */
+export interface OcxSpendScopeConfig {
+  /**
+   * Tokens the scope may hold at once, counting settled spend, open reservations and
+   * unresolved spend. A reservation is the request's whole input plus its enforceable output
+   * ceiling, so this is compared against a number that assumes every cached prefix misses.
+   *
+   * There is no default. A ceiling is a number only the operator knows -- it depends on the
+   * plan, the account roster and what the install is for -- and the recorded lesson from the
+   * observational phase of #4546 is that guessing one is worse than shipping none.
+   */
+  maxTokens?: number;
+}
+
+/**
+ * Durable spend ceilings (#4546).
+ *
+ * The three scopes intersect: a request is admitted only when its own root workflow, the
+ * identity that would serve it, and the pool it would draw from all have room. That is what
+ * makes the ceiling hold against a caller that mints a fresh root id per request -- the root
+ * is new, the identity and pool are not.
+ *
+ * Every field is optional and an empty section is the same as no section at all.
+ */
+export interface OcxSpendConfig {
+  /** Ceiling for one root workflow -- the user-visible task, including its whole fan-out. */
+  root?: OcxSpendScopeConfig;
+  /** Ceiling for one authenticated identity, across every root it serves. */
+  identity?: OcxSpendScopeConfig;
+  /** Ceiling for one account pool, across every identity in it. */
+  pool?: OcxSpendScopeConfig;
+  /**
+   * Days a dormant scope's accounting is retained. Default 7.
+   *
+   * A scope is dropped only when it is both idle and under its ceiling, so shortening this
+   * cannot hand an exhausted scope a fresh allowance.
+   */
+  retentionDays?: number;
+}