@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/server/responses/sidecar-execution.ts

@@ -7,6 +7,9 @@ import type { ResponsesEffects } from "./response-effects";
 import type { ResponsesSendBudget } from "./request-send-budget";
 import { formatErrorResponse } from "../../bridge";
 import { planWebSearch, buildWebSearchTool, runWithWebSearch } from "../../web-search";
+import { createRegisteredAdvisorPlan } from "./advisor-plan-slot";
+import { ADVISOR_TOOL_NAME } from "./advisor-slot";
+import { buildToolBridgeMaps } from "./collaboration";
 import {
   planImageBridge,
   planVideoBridge,
@@ -18,7 +21,7 @@ import {
   clampImageMaxRounds,
 } from "../../images";
 import type { ProviderAdapter } from "../../adapters/base";
-import type { OcxParsedRequest } from "../../types";
+import type { OcxParsedRequest, OcxUsage } from "../../types";
 import { rotateProviderTransportOn429, rateLimitRetryPolicyFor } from "../../providers/key-failover";
 import {
   isGenericOAuthFailoverEnabled,
@@ -30,6 +33,8 @@ import {
 } from "../../oauth/generic-account-failover";
 import { classifyKiroRefusal } from "../../adapters/kiro-refusal";
 import { isNonReplayableResponse } from "../../lib/upstream-retry";
+import { unwrapUpstreamRetryEvidenceError } from "../../codex/auth-context";
+import { AdmissionModelDeniedError, admissionModelDeniedResponse } from "../admission-model-scope";
 import { noteKiroMonthlyRefusal, noteKiroServedSuccess } from "../../providers/kiro-usage";
 import { persistKiroAccountState } from "../../providers/kiro-account-state-disk";
 import { anthropicPoolCooldownResponse, readDisplaySafeErrorText } from "./core-errors";
@@ -45,6 +50,7 @@ import { providerFetch } from "./fetch-helpers";
 import type { AttemptRecoveryKind } from "../../usage/log";
 import { recordAdapterReasoning, recordAdapterTier } from "../request-log";
 import { normalizeLogConversationId } from "../request-log-conversation";
+import { attemptAccountChanged } from "../request-log-account-rotation";
 import { rememberResponseState } from "../../responses/state";
 import { trackStreamLifetime } from "../lifecycle";
 import { isAntigravityRawValidationRefusal } from "./antigravity-validation-refusal";
@@ -60,6 +66,8 @@ export async function executeResponsesSidecars(
     | "inboundWire"
     | "selectedForwardHeaders"
     | "translatorBudget"
+    | "clientToolCatalogRestriction"
+    | "toolBridgeMaps"
     | "rememberKiroDeliveredFinalAnswer"
     | "responseStateOptions"
   >,
@@ -169,6 +177,25 @@ export async function executeResponsesSidecars(
     }
   }
 
+  // Advisor sidecar plan (optional subsystem; null when disabled, unconfigured, or when this
+  // request IS an advisor loopback consultation — the recursion fence). The plan carries
+  // request-scoped state only; preflight keeps fixed policy separate from user-role advice
+  // before the worker is dispatched. Registration seam: the core path sees only
+  // `parsed._advisorGuard`; only an activated factory can load the optional implementation.
+  const advisorPlan = options.advisorInternal === true
+    ? null
+    : await createRegisteredAdvisorPlan({
+      config,
+      workerIdentity: `${route.modelId} (provider ${route.providerName})`,
+      workerModelId: route.modelId,
+      abortSignal: options.abortSignal,
+    });
+  // Preflight only on real worker turns: a routed-compaction turn is a summarization request,
+  // and injecting advice into it would pollute the summary Codex replaces its history with.
+  if (advisorPlan && !routedCompaction) {
+    await advisorPlan.preflightInject(parsed);
+  }
+
   // Image / web-search sidecars: plan once, then dispatch with runTurn-aware priority.
   // Routed-compaction turns must NOT hit the image bridge: compaction clears tools/_webSearch but
   // leaves _imageGeneration, so planImageBridge would activate and return a normal Responses
@@ -198,6 +225,20 @@ export async function executeResponsesSidecars(
   // A single request may rotate once for a verification refusal. Keep this separate from the
   // broader OAuth failover count: a sidecar turn can also spend that count on rate-limit recovery.
   let antigravityValidationRotationAttempted = false;
+  // A replacement credential whose Copilot Auto negotiation leaves the key's scope ends the turn.
+  // The loops only see "no rotation" and fail with the original, replayable 429, so the refusal
+  // is held here and answers in place of that failure.
+  let sidecarScopeDenial: AdmissionModelDeniedError | undefined;
+  const noteSidecarScopeDenial = (error: unknown): void => {
+    const refusal = unwrapUpstreamRetryEvidenceError(error);
+    if (refusal instanceof AdmissionModelDeniedError) sidecarScopeDenial ??= refusal;
+  };
+  const sidecarScopeRefusal = (response: Response): Response | undefined => {
+    if (!sidecarScopeDenial || response.ok) return undefined;
+    void response.body?.cancel().catch(() => {});
+    releaseSearchProbeLease();
+    return admissionModelDeniedResponse(sidecarScopeDenial);
+  };
   /** Admit a replacement credential, or leave the loop's original refusal authoritative. */
   const rotateSidecarProviderOn429 = async (
     retryAfter: string | null,
@@ -264,7 +305,8 @@ export async function executeResponsesSidecars(
           return null;
         }
         transportState.genericFailovers += 1;
-      } catch {
+      } catch (error) {
+        noteSidecarScopeDenial(error);
         hop.permit?.release();
         return null;
       }
@@ -284,7 +326,10 @@ export async function executeResponsesSidecars(
     } else if (rotated) {
       route.provider = rotated;
       try { await resolveCopilotSelection(retryParsed ?? parsed); }
-      catch { return null; } // Keep the sidecar's original refusal when replacement negotiation fails.
+      catch (error) { // Keep the sidecar's original refusal when replacement negotiation fails.
+        noteSidecarScopeDenial(error);
+        return null;
+      }
     } else if (
       // A POSITIVE gate, not an early return. An early `return null` here made every later arm
       // unreachable: Anthropic never has a genericFailoverAccountId (isGenericFailoverProvider
@@ -326,7 +371,8 @@ export async function executeResponsesSidecars(
           return null;
         }
         if (route.providerName === "kiro") transportState.genericFailovers += 1;
-      } catch {
+      } catch (error) {
+        noteSidecarScopeDenial(error);
         hop.permit?.release();
         return null;
       }
@@ -373,7 +419,8 @@ export async function executeResponsesSidecars(
         hop.permit?.release();
         return null;
       }
-      recoveryKind = originalResponse?.status === 401 ? "oauth-401" : "anthropic-oauth-429";
+      recoveryKind = originalResponse?.status === 401 ? "oauth-401"
+        : originalResponse?.status === 403 ? "oauth-account-403" : "anthropic-oauth-429";
       sidecarBudget.ownCredentialHop(hop.permit);
     } else {
       // No key pool, no generic OAuth roster, no Anthropic pool could produce a replacement
@@ -407,6 +454,15 @@ export async function executeResponsesSidecars(
     });
     return { adapter: rotatedAdapter, recoveryKind };
   };
+  // A loop's hidden rounds before a rotation were spent by the account it left. Bill them to that
+  // account's attempt while it is still open; the next send seals it. Declined when that send
+  // keeps the account (no new attempt), so the loop's final total still carries them.
+  const billRotatedUsage = (usage: OcxUsage): boolean => {
+    const attempt = logCtx.activeAttempt;
+    if (!attempt || !attemptAccountChanged(attempt.accountLogLabel, logCtx.accountLogLabel, attempt.provider, logCtx.provider)) return false;
+    transportState.bindKeyUsageFromBridge(usage);
+    return true;
+  };
   if ((imgPlan || vidPlan) && wsPlan) {
     // Web search takes priority when both are active — the media bridge cannot run
     // alongside runWithWebSearch. Surface a runtime signal so the user knows their
@@ -464,6 +520,7 @@ export async function executeResponsesSidecars(
     );
     const imgResponse = await runWithImageBridge({
       parsed, adapter: transportState.adapter,
+      clientToolCatalogRestriction: route.provider.authMode === "forward" ? undefined : requestState.clientToolCatalogRestriction,
       incomingMeta: { headers: requestState.selectedForwardHeaders, providerName: route.providerName, abortSignal: options.abortSignal, translatorBudget, ...(options.comboInitialSend ? { providerFetch: imageProviderFetch } : {}), ...sidecarBudget.incomingMeta },
       onProducerStart: sidecarBudget.takeProducerOwnership,
       onProducerEnd: sidecarBudget.release,
@@ -505,10 +562,12 @@ export async function executeResponsesSidecars(
         transportState.bindKeyUsageFromBridge(usage);
       },
       on429: rotateSidecarProviderOn429,
+      onRotatedUsage: billRotatedUsage,
       retryOn429Policy: route.providerName === "kiro" && isGenericOAuthFailoverEnabled(config, "kiro")
         ? null : rateLimitRetryPolicyFor(route.provider),
       onFirstOutput: noteSidecarOutput,
       ...(options.forceEmptyResponseId ? { forceEmptyResponseId: true } : {}),
+      terminalRefusalAsFailed: inboundWire !== "chat" && inboundWire !== "anthropic",
       onCompletedResponse: (response, providerState) => {
         const served = transportState.replayOAuthCredentialSnapshot;
         if (route.providerName === "kiro" && response.status === "completed" && served
@@ -527,6 +586,8 @@ export async function executeResponsesSidecars(
         notifyResponseComplete(response);
       },
     });
+    const imgScopeRefusal = sidecarScopeRefusal(imgResponse);
+    if (imgScopeRefusal) return imgScopeRefusal;
     if (imgResponse.body) {
       const imgTurnAc = new AbortController();
       imgTurnAc.signal.addEventListener("abort", cancelResponseCompletion, { once: true });
@@ -557,6 +618,7 @@ export async function executeResponsesSidecars(
       })(input, init)) as typeof globalThis.fetch;
     const loopResponse = await runWithWebSearch({
       parsed, adapter: transportState.adapter,
+      clientToolCatalogRestriction: route.provider.authMode === "forward" ? undefined : requestState.clientToolCatalogRestriction,
       onIterationEnd: sidecarBudget.releaseUnsentHop,
       fetchForRequest: (request, iterParsed, adapter) => providerFetch(route.provider, options.codexWsRuntimeIdentity, {
         dispatchOverride: oauthDispatch(request, iterParsed),
@@ -587,6 +649,7 @@ export async function executeResponsesSidecars(
       settings: wsPlan.settings,
       maxSearches: wsPlan.maxSearches,
       forceEmptyResponseId: true,
+      terminalRefusalAsFailed: inboundWire !== "chat" && inboundWire !== "anthropic",
       abortSignal: options.abortSignal,
       onFirstOutput: noteSidecarOutput,
       onRequestBuilt: request => {
@@ -605,6 +668,7 @@ export async function executeResponsesSidecars(
       stallTimeoutSec: wsPlan.stallTimeoutSec,
       streamRoutedModelOutput: wsPlan.streamRoutedModelOutput,
       on429: rotateSidecarProviderOn429,
+      onRotatedUsage: billRotatedUsage,
       ...(!options.comboInitialSend && route.providerName === "google-antigravity" ? { onIterationEnd: () => {
         // The next Antigravity adapter dispatch claims this permit. If request construction,
         // admission or cancellation stopped it first, return the unused send allowance.
@@ -622,6 +686,8 @@ export async function executeResponsesSidecars(
         notifyResponseComplete(response);
       },
     });
+    const wsScopeRefusal = sidecarScopeRefusal(loopResponse);
+    if (wsScopeRefusal) return wsScopeRefusal;
     // A routed Anthropic model whose last pool account refused on spent quota fails the loop's
     // first iteration with a generic 429 before any search runs. Answer the usage limit instead,
     // as the main path does (#6991), so Codex stops rather than retrying the whole turn.
@@ -645,5 +711,32 @@ export async function executeResponsesSidecars(
     return wsResponse;
   }
 
+  // Advisor synthetic tool + stream guard: attach ONLY when this function is about to hand the
+  // request back to the normal translated exchange (no sidecar loop claimed the turn, not a
+  // run-turn adapter, not compaction). The web-search/image loops own their own event handling;
+  // run-turn adapters execute their own loop; both would leak the synthetic tool call they
+  // cannot intercept. Preflight (above) still applies to those paths — only the tool does not.
+  if (advisorPlan && !routedCompaction && !transportState.adapter.runTurn && !wsPlan && !imgPlan && !vidPlan) {
+    // A client-declared tool named "advisor" would collide with the synthetic injection (one
+    // wire name, two schemas); the synthetic runtime owns the name for this turn.
+    parsed.context.tools = [
+      ...(parsed.context.tools ?? []).filter(t => !t.advisor && t.name !== ADVISOR_TOOL_NAME),
+      advisorPlan.tool,
+    ];
+    // The advisor tool joined AFTER prepare computed the bridge maps; recompute so the tool is
+    // declared (undeclared-tool guard, tool_choice mapping, schema repair) on this turn.
+    //
+    // Rebuild WITHOUT the budget: prepare already charged every tool in the catalog, and
+    // buildToolBridgeMaps charges each name it registers, so re-passing the budget would bill the
+    // whole catalog a second time and can trip `translation_buffer_limit` for a large MCP catalog.
+    // Charge only the one entry that is genuinely new — the synthetic advisor tool is a bare
+    // function tool, so it retains its wire name and its bare name (collaboration.ts:187, :233).
+    requestState.toolBridgeMaps = buildToolBridgeMaps(parsed);
+    translatorBudget.chargeRetained(new TextEncoder().encode(ADVISOR_TOOL_NAME).byteLength * 2, {
+      kind: "retained_collectors",
+    });
+    advisorPlan.attachGuard(parsed);
+  }
+
   return undefined;
 }

package/src/server/responses/terminal-guard.ts

@@ -1,6 +1,6 @@
+import { assistantReplayContent } from "../../responses/assistant-replay";
 import type {
   AdapterEvent,
-  OcxAssistantContentPart,
   OcxAssistantMessage,
   OcxParsedRequest,
   OcxUsage,
@@ -121,21 +121,7 @@ export function analyzeTerminalTurn(parsed: OcxParsedRequest, events: readonly A
 }
 
 function assistantMessageFromEvents(events: readonly AdapterEvent[], timestamp: number): OcxAssistantMessage | undefined {
-  let text = "";
-  let thinking = "";
-  let signature: string | undefined;
-  const redacted: string[] = [];
-  for (const event of events) {
-    if (event.type === "text_delta") text += event.text;
-    else if (event.type === "thinking_delta") thinking += event.thinking;
-    else if (event.type === "thinking_signature") signature = event.signature;
-    else if (event.type === "redacted_thinking") redacted.push(event.data);
-  }
-  const content: OcxAssistantContentPart[] = [];
-  if (thinking || signature || redacted.length > 0) {
-    content.push({ type: "thinking", thinking, ...(signature ? { signature } : {}), ...(redacted.length > 0 ? { redacted } : {}) });
-  }
-  if (text) content.push({ type: "text", text });
+  const content = assistantReplayContent(events);
   if (content.length === 0) return undefined;
   return { role: "assistant", content, timestamp };
 }
@@ -170,7 +156,8 @@ export function isTerminalGuardPassthroughOnly(event: AdapterEvent): boolean {
   return event.type === "heartbeat" || event.type === "tool_call_delta";
 }
 
-function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
+/** Merge two reported usages (canonical Responses convention). Shared with the advisor guard. */
+export function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
   if (!first) return second;
   if (!second) return first;
   const sumOptional = (key: keyof OcxUsage): number | undefined => {

package/src/server/responses-undeclared-tool-guard.ts

@@ -1,3 +1,4 @@
+import { UNDECLARED_TOOL_CALL_ERROR_CODE } from "../lib/errors";
 import {
   collectAmbiguousDottedAliases,
   dottedAliasIsUnambiguous,
@@ -78,7 +79,7 @@ const NAMELESS_TOOL_SPEC_TYPES = new Set([
 /** An upstream-supplied name reaches the error message; keep it bounded. */
 const MAX_REPORTED_NAME_CHARS = 100;
 
-export const UNDECLARED_TOOL_CALL_ERROR_CODE = "undeclared_tool_call";
+export { UNDECLARED_TOOL_CALL_ERROR_CODE };
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -370,6 +371,24 @@ export function hasExplicitWireToolCatalog(body: unknown): boolean {
   );
 }
 
+/**
+ * Whether the caller declared an explicitly EMPTY catalog — `tools: []` or an
+ * `additional_tools` item with `tools: []`. Unlike an absent or partial catalog this is an
+ * unambiguous deny-all: no deferred registry can exist under it, so even deferred wires
+ * enforce it. A hosted-only catalog is NOT empty — it still defers like an absent one.
+ */
+export function hasExplicitEmptyToolCatalog(body: unknown): boolean {
+  if (!isPlainObject(body)) return false;
+  if (Array.isArray(body.tools) && body.tools.length === 0) return true;
+  if (!Array.isArray(body.input)) return false;
+  return body.input.some(item =>
+    isPlainObject(item)
+    && item.type === "additional_tools"
+    && Array.isArray(item.tools)
+    && item.tools.length === 0
+  );
+}
+
 /**
  * Evaluates whether an individual output item represents an undeclared tool call.
  *
@@ -703,7 +722,6 @@ function failedBlocks(name: string, newline: string): readonly string[] {
  * @param providerExecutedCallTypes - Call types executed by the provider.
  * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
  * @param declaredCustom - Current bare custom declarations eligible for code-mode recovery.
- * @param enforceDeclaredToolNames - Refuse undeclared calls; normalization remains active when false.
  * @returns An SSE block rewrite function.
  */
 export function createUndeclaredToolCallGuardBlockRewrite(
@@ -712,8 +730,11 @@ export function createUndeclaredToolCallGuardBlockRewrite(
   providerExecutedCallTypes: ProviderExecutedCallTypes = EMPTY_PROVIDER_EXECUTED_CALL_TYPES,
   declaredBare?: ReadonlySet<string>,
   declaredCustom?: ReadonlySet<string>,
-  enforceDeclaredToolNames = true,
+  options?: { refuseUndeclared?: boolean },
 ): SseBlockRewrite {
+  // Deferred-catalog wires (Chat/Anthropic) keep the default-namespace normalization — the
+  // client can only resolve the bare name it declared — while the refusal itself stays off.
+  const refuse = options?.refuseUndeclared !== false;
   let tripped = false;
   return (block: string) => {
     if (tripped) return [];
@@ -725,12 +746,12 @@ export function createUndeclaredToolCallGuardBlockRewrite(
     } catch {
       return [block];
     }
-    const name = enforceDeclaredToolNames
-      ? undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare, declaredCustom)
-      : undefined;
-    if (name !== undefined) {
-      tripped = true;
-      return failedBlocks(name, block.includes("\r\n") ? "\r\n" : "\n");
+    if (refuse) {
+      const name = undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare, declaredCustom);
+      if (name !== undefined) {
+        tripped = true;
+        return failedBlocks(name, block.includes("\r\n") ? "\r\n" : "\n");
+      }
     }
     const normalized = normalizeDefaultNamespaceInPayload(parsed, declared, declaredBare);
     if (normalized.changed) {

package/src/server/startup-action-control.ts

@@ -3,6 +3,8 @@ import { execFile } from "node:child_process";
 import { join } from "node:path";
 import { durableBunPath } from "../lib/bun-runtime";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { isDesktopSupervised } from "../lib/system-restart-contract";
+import { withLoginShellPath } from "./login-shell-path";
 import {
   WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER,
   isWindowsSchtasksCreateAccessDenied,
@@ -66,6 +68,8 @@ interface StartupInstallLaunch {
   execFile?: typeof execFile;
   /** Overrides Bun's own standalone detection, which a source-mode test cannot flip. */
   isStandaloneExecutable?: boolean;
+  isDesktopSupervised?: () => boolean;
+  withLoginShellPath?: (env: NodeJS.ProcessEnv) => Promise<NodeJS.ProcessEnv>;
 }
 let installLaunch: StartupInstallLaunch = {};
 
@@ -169,7 +173,16 @@ export function installFailureDetail(stdout: string, stderr: string, error: Erro
   return classifyCliInstallFailure(stdout, stderr, error).detail;
 }
 
-function runCliInstall(
+/**
+ * Under OpenCodex Desktop the proxy has the GUI launch PATH, where no user-installed Codex is
+ * visible. The shim installer gets the user's login-shell PATH instead (#6971).
+ */
+async function installChildEnv(action: StartupInstallAction): Promise<NodeJS.ProcessEnv> {
+  if (action !== "install-shim" || !(installLaunch.isDesktopSupervised ?? isDesktopSupervised)()) return process.env;
+  return (installLaunch.withLoginShellPath ?? withLoginShellPath)(process.env);
+}
+
+async function runCliInstall(
   action: StartupInstallAction,
   options?: { repair?: boolean },
 ): Promise<{ stdout: string; stderr: string }> {
@@ -183,13 +196,14 @@ function runCliInstall(
     isStandaloneExecutable: installLaunch.isStandaloneExecutable,
   });
   const run = installLaunch.execFile ?? execFile;
+  const env = await installChildEnv(action);
   return new Promise((resolve, reject) => {
     const timeout = process.platform === "win32" && action === "install-service"
       ? 0
       : 60_000;
     run(bun, argv, {
       encoding: "utf8",
-      env: process.env,
+      env,
       // A fresh Windows scheduler install now owns its UAC prompt inside this CLI
       // transaction. Killing only the CLI at 60s can orphan its elevated schtasks child,
       // which may register the task after the Dashboard has reported failure. Keep the

package/src/server/startup-health-cache.ts

@@ -117,6 +117,7 @@ function conservativeFallback(config: Pick<OcxConfig, "codexAutoStart">): Startu
     serviceSupported: process.platform === "win32" || process.platform === "darwin" || process.platform === "linux",
     shimInstalled: shim.installed,
     shimHealthy: shim.healthy,
+    ...(shim.activationPending ? { shimActivationPending: true } : {}),
     platform: process.platform,
     diagnosticStale: true,
   });

package/src/service/auth-preflight.ts

@@ -0,0 +1,71 @@
+/**
+ * The install/repair preflight over the data-plane credential, plus the retry command it
+ * names. Split out of `guards.ts` so the guard module stops importing `diagnostics`.
+ *
+ * Direction of the remaining edge is deliberate: this module asks `guards` for
+ * `assertNotAdminToken` and `diagnostics` for the install verdict, and neither imports it back.
+ */
+import { loadConfig } from "../config";
+import { isLoopbackHostname } from "../codex/loopback-target";
+import { readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets";
+import { diagnoseService } from "./diagnostics";
+import type { ServiceDiagnostic } from "./diagnostics";
+import { assertNotAdminToken } from "./guards";
+
+/**
+ * The `ocx` command a user should rerun for the service state they actually have.
+ *
+ * `installed` alone is not enough: `repairService()` refuses a Task-Scheduler-plus-WinSW
+ * conflict outright, so recommending repair there names a command guaranteed to fail.
+ * Install IS the valid conflict recovery, because `installWindows` removes the native
+ * backend first. Exported so the guard tests the real selector rather than a copy of it.
+ */
+export function serviceRetryCommand(
+  diag: Pick<ServiceDiagnostic, "installed" | "conflict"> = diagnoseService(),
+): string {
+  return diag.installed && !diag.conflict ? "ocx service repair" : "ocx service install";
+}
+
+/**
+ * Preflight for `service install` / `service repair` on the data-plane credential.
+ *
+ * It used to DEMAND `OPENCODEX_API_AUTH_TOKEN` for a non-loopback hostname, and it threw
+ * even when `~/.opencodex/service-api-token` already held a perfectly good token. That is
+ * the defect behind the incident this unit exists to close (#4236): an operator exported the
+ * ADMIN token as OPENCODEX_API_AUTH_TOKEN because `install` asked for a token, the hub then
+ * crash-looped on `assertNotAdminToken`, and `service repair` asked for the same env var
+ * again — so the only remembered way to make the command proceed was the thing that broke it.
+ *
+ * Nobody should have to export a token by hand to run a hub. {@link writeServiceApiTokenFile}
+ * provisions one, so the only conditions left that install cannot fix are an admin-token
+ * collision in the environment and a token file that exists but cannot be used.
+ */
+export function assertServiceAuthEnvironment(): void {
+  const config = loadConfig();
+  // Both collision checks come BEFORE the loopback short-circuit, because the launch wrapper
+  // exports the token file unconditionally (`buildServiceShellCommand` cats it whenever it
+  // exists, whatever the hostname): a management token in either source fences the whole
+  // management plane closed at boot, even on a loopback install that needs no admission
+  // secret. Returning early is what let that broken state through.
+  const present = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (present) assertNotAdminToken(present);
+  const state = readServiceApiTokenState();
+  // An existing FILE holding the admin token is the incident shape itself, and the first round
+  // only checked the env var — so install/repair reused it and the hub crash-looped at boot.
+  // On a machine connected to a hub this same file holds that hub's issued client key, which
+  // is never a management token, so the check is a no-op there.
+  if (state.kind === "present") assertNotAdminToken(state.token, process.env, "file");
+  if (isLoopbackHostname(config.hostname)) return;
+  if (present) return;
+  // Absent is fine — install/repair generates one below. `unsafe` is not: the writer refuses
+  // to replace a path it cannot vouch for, so say so here, where the operator can still act,
+  // instead of failing mid-install. Reached from `service repair` as well as `install`, so
+  // name a command that can actually succeed (see serviceRetryCommand).
+  if (state.kind !== "unsafe") return;
+  const diag = diagnoseService();
+  throw new Error(
+    `The data-plane token file cannot be used (${state.reason}): ${serviceApiTokenFilePath()}. `
+      + `Move it aside, then rerun \`${serviceRetryCommand(diag)}\`; the service provisions a `
+      + "fresh owner-only token and needs nothing from the environment.",
+  );
+}

package/src/service/cli.ts

@@ -11,8 +11,10 @@ import { statusWinswRaw, type WinswStatus } from "../lib/winsw";
 import { withWindowsServiceMutationLock } from "../lib/windows-service-mutation-lock";
 import { maybeShowStarPrompt } from "../cli/star-prompt";
 import { serviceStatusReport } from "./diagnostics";
-import { assertServiceEnvironmentMatchesInstall, assertServiceAuthEnvironment } from "./guards";
-import { resolveServiceListenPort, reportServiceServing } from "./health";
+import { assertServiceAuthEnvironment } from "./auth-preflight";
+import { assertServiceEnvironmentMatchesInstall } from "./guards";
+import { resolveServiceListenPort } from "./definition";
+import { reportServiceServing } from "./health";
 import { platformOps, proxyStillLiveAfterStop, stopTrackedProxyForServiceCommand, installServiceSafely, installFreshWindowsSchedulerSafely, removeServiceInstallState, isServiceInstalled } from "./orchestration";
 import { repairService } from "./repair";
 import type { ServiceRepairVerb } from "./repair";

package/src/service/definition.ts

@@ -0,0 +1,97 @@
+/**
+ * The shape of a service definition: the shell command both Unix backends bake into
+ * their unit/plist, the port they pin into it, and the proxy environment it carries.
+ *
+ * Leaf module. It reads config and the token-file path, and asks nothing of the
+ * backends that consume it — importing it from `launchd.ts`/`systemd.ts` cannot
+ * route back through them (see `installedServiceListenPort` in `health.ts`, which
+ * intentionally stays behind because it asks every backend).
+ */
+import { loadConfig } from "../config";
+import { serviceApiTokenFilePath } from "../lib/service-secrets";
+import { PROXY_ENV_KEYS } from "../lib/proxy-env";
+
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Listen port baked into service wrappers / WinSW XML.
+ * Priority: explicit override → OCX_BAKE_PORT (update restart) → config.port → 10100.
+ * `config.port === 0` means ephemeral for interactive start; services need a stable pin,
+ * so treat 0 / invalid like unset (default 10100) instead of baking `--port 0`.
+ */
+export function resolveServiceListenPort(override?: number): number {
+  if (typeof override === "number" && Number.isFinite(override) && override > 0 && override <= 65535) {
+    return Math.trunc(override);
+  }
+  const baked = process.env.OCX_BAKE_PORT?.trim();
+  if (baked && /^\d+$/.test(baked)) {
+    const n = Number(baked);
+    if (n > 0 && n <= 65535) return n;
+  }
+  const configured = loadConfig().port;
+  if (typeof configured === "number" && configured > 0 && configured <= 65535) return configured;
+  return 10100;
+}
+
+export function buildServiceShellCommand(bun: string, cli: string | null, port = resolveServiceListenPort()): string {
+  const tokenFile = serviceApiTokenFilePath();
+  const args = cli ? `${shellQuote(cli)} start` : "start";
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${args} --port ${port}`;
+}
+
+/**
+ * The same command shape, launched through a stable `ocx` executable instead of an
+ * explicit Bun + CLI pair. The token-file preamble is identical and deliberately shared
+ * in form: the service still reads the token from disk at start and never carries it in
+ * the unit.
+ */
+export function buildServiceLauncherShellCommand(launcher: string, port = resolveServiceListenPort()): string {
+  const tokenFile = serviceApiTokenFilePath();
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(launcher)} start --port ${port}`;
+}
+
+/**
+ * Shared tail parser for the baked `--port <n>`.
+ *
+ * Terminators cover all three artifact shapes: whitespace (batch wrapper, systemd
+ * unit), `"` (systemd's quoted ExecStart), `<` (WinSW's `</arguments>`), and `&` (an
+ * XML-escaped quote). Matched LAST because every artifact carries the Bun and CLI
+ * paths ahead of the argument, and a path containing the literal must not shadow it.
+ */
+export function parseBakedListenPort(read: () => string): number | null {
+  try {
+    const last = [...read().matchAll(/start --port (\d{1,5})(?:\s|"|&|<|$)/gm)].at(-1);
+    if (!last) return null;
+    const n = Number(last[1]);
+    return n > 0 && n <= 65535 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Outbound proxy settings the installing shell had, resolved for baking into a service
+ * definition.
+ *
+ * A service manager does not inherit the environment of the shell that installed it, and
+ * `ExecStart=/bin/sh -lc` is dash on Ubuntu/WSL — login dash reads `.profile`, not
+ * `.bashrc`, which is where proxy exports usually live. So a user who needs a proxy to
+ * reach the upstream got a service that dialed direct: the socket was reset, the retry
+ * budget drained, and the request surfaced as `502 Provider unreachable` (#2107). The
+ * same install driven through `ocx codex-shim` worked, because that path spawns with
+ * `{ ...process.env }`.
+ *
+ * Lower-case variants are honored because curl-style tooling sets them and the runtime's
+ * own `applyProxyEnv` already treats both cases as equivalent. Only the canonical
+ * upper-case name is baked, so a definition never carries two spellings of one setting.
+ */
+export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name: string; value: string }[] {
+  const resolved: { name: string; value: string }[] = [];
+  for (const key of PROXY_ENV_KEYS) {
+    const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
+    if (value) resolved.push({ name: key, value });
+  }
+  return resolved;
+}

package/src/service/desktop-startup.ts

@@ -122,11 +122,25 @@ function macLoginRegistration(deps: DesktopStartupDeps) {
   }
   const program = /^\s*program = (.+)$/m.exec(loaded)?.[1];
   const loadedPath = /^\s*path = (.+)$/m.exec(loaded)?.[1];
+  // macOS 13+ Background Task Management can take over the user LaunchAgent and resubmit it
+  // through smd; launchctl then names the submitter instead of the plist (#7019). The loaded
+  // job no longer points at the registration, so credit it like an unloaded job: same program,
+  // and the entire registration re-read unchanged.
+  if (program !== undefined && loadedPath !== undefined && SMD_SUBMITTED.test(loadedPath)
+    && /^\s*managed_by = (.+)$/m.exec(loaded)?.[1] === SERVICE_MANAGEMENT && realpathSync(program) === app) {
+    const final = capture();
+    if (!final || JSON.stringify(first) !== JSON.stringify(final)) return { app, proxy, loginEnabled: false };
+    return { app, proxy, loginEnabled: true, loginRegistration: "loaded" as const };
+  }
   const loginEnabled = program !== undefined && realpathSync(program) === app
     && loadedPath !== undefined && realpathSync(loadedPath) === first.registrationPath;
   return { app, proxy, loginEnabled, ...(loginEnabled ? { loginRegistration: "loaded" as const } : {}) };
 }
 
+/** launchctl's `path` for a job Background Task Management resubmitted through smd. */
+const SMD_SUBMITTED = /^\(submitted by smd\.\d+\)$/;
+const SERVICE_MANAGEMENT = "com.apple.xpc.ServiceManagement";
+
 type DesktopLoginFacts = Pick<DesktopStartupDiagnostic, "loginEnabled" | "loginRegistration">;
 
 /**