npm - @bitkyc08/opencodex - Versions diffs - 2.49.0 → 2.51.0 - Mend

@bitkyc08/opencodex 2.49.0 → 2.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (141) hide show

package/AGENTS_INSTALL.md +9 -1
package/README.md +3 -0
package/bin/ocx.mjs +222 -71
package/gui/dist/assets/index-D7BdZpZm.js +115 -0
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/adapters/qoder/adapter.ts +69 -1
package/src/adapters/qoder/scaffold-guard.ts +233 -0
package/src/claude/agents-inject.ts +29 -5
package/src/claude/desktop-3p.ts +31 -3
package/src/claude/gateway-cache.ts +12 -21
package/src/claude/inbound.ts +17 -5
package/src/cli/account-api.ts +18 -3
package/src/cli/account-auth.ts +8 -1
package/src/cli/account-extended.ts +2 -1
package/src/cli/account.ts +1 -0
package/src/cli/capabilities.ts +43 -1
package/src/cli/claude-agent-startup-sync.ts +26 -1
package/src/cli/claude.ts +138 -20
package/src/cli/config-command.ts +67 -1
package/src/cli/connect.ts +181 -14
package/src/cli/dispatch.ts +53 -9
package/src/cli/doctor.ts +9 -2
package/src/cli/ensure-desired-integrations.ts +10 -0
package/src/cli/gui-pair-client.ts +1 -12
package/src/cli/help.ts +4 -1
package/src/cli/hub.ts +367 -0
package/src/cli/index.ts +99 -31
package/src/cli/launcher-context.ts +1 -1
package/src/cli/models-runtime.ts +8 -3
package/src/cli/observe.ts +13 -3
package/src/cli/registry.ts +43 -3
package/src/cli/status.ts +325 -5
package/src/cli/version-skew.ts +4 -1
package/src/cli.ts +2 -2
package/src/client/catalog-compatibility.ts +192 -0
package/src/client/connect.ts +31 -0
package/src/client/hub-client.ts +52 -0
package/src/client/hub-state.ts +214 -0
package/src/clients/config-export/zcode.ts +24 -0
package/src/codex/account-runtime-state.ts +6 -1
package/src/codex/account-store.ts +72 -9
package/src/codex/account-usability.ts +50 -13
package/src/codex/auth-api.ts +156 -28
package/src/codex/auth-context.ts +21 -0
package/src/codex/catalog/effort.ts +67 -8
package/src/codex/catalog/parsing.ts +23 -0
package/src/codex/catalog/provider-fetch.ts +71 -2
package/src/codex/catalog/sync.ts +99 -0
package/src/codex/codex-write-lock.ts +11 -2
package/src/codex/desired-state.ts +47 -1
package/src/codex/inject-coordination.ts +10 -5
package/src/codex/inject.ts +29 -12
package/src/codex/loopback-target.ts +45 -0
package/src/codex/quota-auto-refresh.ts +6 -1
package/src/codex/quota.ts +54 -8
package/src/codex/routing.ts +48 -1
package/src/codex/runtime.ts +37 -3
package/src/codex/sync.ts +29 -9
package/src/codex/warmup.ts +21 -4
package/src/combos/index.ts +2 -0
package/src/combos/resolve.ts +52 -0
package/src/config/pending-teardown.ts +1 -1
package/src/config.ts +184 -12
package/src/generated/compatibility-version.json +188 -116
package/src/grok/status.ts +9 -1
package/src/integrations/config-io.ts +54 -1
package/src/lib/bun-runtime.ts +1 -1
package/src/lib/errors.ts +8 -0
package/src/lib/gui-pair-capability.ts +27 -0
package/src/lib/local-destinations.ts +162 -0
package/src/lib/package-tree-integrity.ts +1 -1
package/src/lib/privacy.ts +25 -0
package/src/lib/process-control.ts +130 -20
package/src/lib/service-secrets.ts +28 -0
package/src/lib/test-home-guard.ts +49 -0
package/src/oauth/health.ts +47 -12
package/src/oauth/index.ts +46 -8
package/src/oauth/token-guardian.ts +32 -6
package/src/providers/google-ai-studio-model-discovery.ts +74 -0
package/src/providers/opencode-go-transport.ts +9 -1
package/src/providers/opencode-zen-rate-limit.ts +75 -0
package/src/providers/quota.ts +20 -1
package/src/providers/registry.ts +35 -6
package/src/remote/hub-state.ts +182 -0
package/src/server/auth-cors.ts +11 -0
package/src/server/chat-completions.ts +10 -7
package/src/server/chat-native.ts +10 -1
package/src/server/claude-messages.ts +12 -6
package/src/server/hub-state.ts +98 -0
package/src/server/images.ts +2 -2
package/src/server/index.ts +149 -8
package/src/server/management/api-access.ts +14 -3
package/src/server/management/config-routes.ts +2 -2
package/src/server/management/cursor-integration-routes.ts +13 -4
package/src/server/management/logs-usage-routes.ts +4 -1
package/src/server/management/model-rows.ts +16 -1
package/src/server/management/oauth-account-routes.ts +6 -2
package/src/server/management/provider-routes.ts +9 -2
package/src/server/management/request-history-routes.ts +4 -2
package/src/server/management/route-registry.ts +5 -4
package/src/server/management/shared.ts +66 -3
package/src/server/management-api.ts +1 -1
package/src/server/proxy-liveness.ts +7 -1
package/src/server/request-decompress.ts +91 -3
package/src/server/request-log-conversation.ts +41 -1
package/src/server/request-log.ts +10 -0
package/src/server/responses/codex-auth-error.ts +18 -1
package/src/server/responses/codex-ws-exchange.ts +36 -4
package/src/server/responses/codex-ws-wire.ts +76 -5
package/src/server/responses/compact.ts +28 -11
package/src/server/responses/context-overflow.ts +11 -0
package/src/server/responses/core.ts +201 -48
package/src/server/responses/policy-fallback.ts +13 -3
package/src/server/search.ts +2 -2
package/src/server/system-env-shell.ts +14 -2
package/src/server/system-env.ts +106 -14
package/src/service.ts +965 -68
package/src/types/accounts.ts +18 -0
package/src/types/config.ts +93 -4
package/src/types/provider.ts +56 -0
package/src/types.ts +4 -0
package/src/update/badge.ts +3 -2
package/src/update/index.ts +317 -64
package/src/update/install-detection.d.mts +6 -0
package/src/update/install-detection.mjs +73 -0
package/src/update/job.ts +101 -49
package/src/update/pnpm-global-install.d.mts +144 -0
package/src/update/pnpm-global-install.mjs +591 -0
package/src/update/pnpm-invocation.d.mts +43 -0
package/src/update/pnpm-invocation.mjs +141 -0
package/src/update/registry-integrity.d.mts +16 -0
package/src/update/registry-integrity.mjs +37 -0
package/src/update/transactional-install.d.mts +1 -1
package/src/update/transactional-install.mjs +101 -7
package/src/update/tray-update-plan.mjs +1 -1
package/src/vision/plan.ts +13 -3
package/src/vision/routed-describe.ts +51 -20
package/src/web-search/ollama-executor.ts +127 -0
package/src/web-search/passthrough-bridge.ts +761 -0
package/gui/dist/assets/index-BtyONQrZ.js +0 -115

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-BtyONQrZ.js"></script>
+    <script type="module" crossorigin src="/assets/index-D7BdZpZm.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BoBRSehJ.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.49.0",
+  "version": "2.51.0",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/adapters/qoder/adapter.ts CHANGED Viewed

@@ -4,6 +4,7 @@ import { mapReasoningEffort } from "../../reasoning-effort";
 import { buildSystemPrompt } from "../coding-agent/protocol";
 import { baseScopedEnv, runCodingAgentTurn, type CodingAgentDeps } from "../coding-agent/turn";
 import { QODER_PROFILES, type QoderProfile } from "./profiles";
+import { QoderScaffoldFilter, QODER_SCAFFOLD_ERROR_CODE, qoderScaffoldErrorMessage } from "./scaffold-guard";
 export type QoderAdapterDeps = CodingAgentDeps;
@@ -31,6 +32,73 @@ export function buildQoderArgs(parsed: OcxParsedRequest, provider: OcxProviderCo
   return args;
 }
+/**
+ * Wrap the turn's outbound channel with the scaffolding guard (#4190).
+ *
+ * The vendor CLI can put its own agent layer into the text channel despite being launched
+ * with tools and MCP disabled, and the shared stream-json parser forwards a text delta
+ * without inspecting it. This is the last point that is still qoder-specific, so the guard
+ * sits here rather than in the parser every coding-agent CLI shares.
+ *
+ * A terminal event flushes both channels first. The held tail is text the filter could not
+ * yet prove was not the start of a marker; dropping it would truncate a legitimate answer,
+ * and swallowing an entire response before forwarding a "done" reads downstream as an empty
+ * completion rather than as the refusal it is.
+ */
+export function guardQoderScaffolding(emit: (event: AdapterEvent) => void): (event: AdapterEvent) => void {
+  const textFilter = new QoderScaffoldFilter();
+  const thinkingFilter = new QoderScaffoldFilter();
+  let closed = false;
+  const refuse = (reason: string): void => {
+    if (closed) return;
+    closed = true;
+    emit({
+      type: "error",
+      message: qoderScaffoldErrorMessage(reason),
+      status: 502,
+      errorType: "upstream_error",
+      code: QODER_SCAFFOLD_ERROR_CODE,
+      // Intermittent, but a silent retry spends the operator's vendor credits on a
+      // contract violation the proxy cannot influence. Surface it instead.
+      retryable: false,
+    });
+  };
+  return (event: AdapterEvent): void => {
+    if (closed) return;
+    if (event.type === "text_delta") {
+      const cleaned = textFilter.push(event.text);
+      if (cleaned.text) emit({ ...event, text: cleaned.text });
+      if (cleaned.fail) refuse(cleaned.fail);
+      return;
+    }
+    if (event.type === "thinking_delta") {
+      const cleaned = thinkingFilter.push(event.thinking);
+      if (cleaned.text) emit({ ...event, thinking: cleaned.text });
+      if (cleaned.fail) refuse(cleaned.fail);
+      return;
+    }
+    if (event.type === "done" || event.type === "error" || event.type === "incomplete") {
+      const tail = textFilter.flush();
+      const reasoning = thinkingFilter.flush();
+      if (tail.text) emit({ type: "text_delta", text: tail.text });
+      if (reasoning.text) emit({ type: "thinking_delta", thinking: reasoning.text });
+      const fail = tail.fail ?? reasoning.fail;
+      // A vendor error already carries the better explanation for why the turn ended;
+      // only a terminal that claims success is replaced.
+      if (fail && event.type !== "error") {
+        refuse(fail);
+        return;
+      }
+      closed = true;
+      emit(event);
+      return;
+    }
+    emit(event);
+  };
+}
 export function createQoderAdapter(provider: OcxProviderConfig, deps: QoderAdapterDeps = {}): ProviderAdapter {
   return {
     name: "qoder",
@@ -60,7 +128,7 @@ export function createQoderAdapter(provider: OcxProviderConfig, deps: QoderAdapt
         provider,
         parsed,
         incoming,
-        emit,
+        emit: guardQoderScaffolding(emit),
         buildArgs: (_profile, req, prov) => buildQoderArgs(req, prov),
         buildEnv: (profile, apiKey) => buildQoderChildEnv(profile as QoderProfile, apiKey),
         deps,

package/src/adapters/qoder/scaffold-guard.ts ADDED Viewed

@@ -0,0 +1,233 @@
+/**
+ * Vendor-scaffolding guard for the qoder route (#4190).
+ *
+ * The qoder route is contractually a text and reasoning surface: the CLI is spawned with
+ * `--tools "" --strict-mcp-config --setting-sources ""`, and Codex keeps tool ownership.
+ * The vendor CLI does not always honour that. It has been observed emitting its own agent
+ * layer into the assistant text channel — an MCP lazy-loading `<system-reminder>` block
+ * listing the local machine's configured MCP servers, and framework tool-call markup with a
+ * mismatched closer. Both reached the client verbatim, because the shared stream-json parser
+ * forwards a text delta without inspecting it.
+ *
+ * Two shapes, two answers. A complete `<system-reminder>` block is recognizable and
+ * self-delimiting, so it is removed and the surrounding answer survives. Anything else that
+ * carries a scaffolding signature is not repairable by guesswork — a partial tool-call block
+ * has no reliable end, and the text around it may already be the vendor's own agent
+ * narration rather than the model's answer — so the turn fails closed instead.
+ *
+ * The filter is a stream, not a regex over a finished string: a marker can be split across
+ * deltas, so a tail that is still a possible marker prefix is held back rather than emitted.
+ * Callers must therefore `flush()` before forwarding a terminal event, or a legitimate
+ * answer ending in "<" would lose its last character.
+ */
+/** Error code for a turn refused because vendor scaffolding reached the text channel. */
+export const QODER_SCAFFOLD_ERROR_CODE = "vendor_scaffold_detected";
+const REMINDER_OPEN = "<system-reminder";
+const REMINDER_CLOSE = "</system-reminder>";
+/**
+ * Scaffolding signatures that are never repaired.
+ *
+ * `<functions.` and the invoke pair are the vendor runtime's tool-call markup. The reported
+ * leak carried `<functions.exec>` opened and `</invoke>` closed — mismatched, which is what
+ * a model emitting remembered markup looks like, and exactly why reconstructing the intended
+ * text is not possible. A stray `</system-reminder>` with no opener is in the same class:
+ * the block it belonged to was already partly forwarded, or never existed.
+ */
+const UNREPAIRABLE_MARKERS = ["<functions.", "<invoke name=", "<invoke>", "</invoke>", REMINDER_CLOSE] as const;
+/** Markers that end a block rather than start one; their prefix is never an answer. */
+const CLOSING_MARKERS = new Set<string>(["</invoke>", REMINDER_CLOSE]);
+/** Every marker the scanner must be able to recognize mid-split. */
+const ALL_MARKERS = [REMINDER_OPEN, ...UNREPAIRABLE_MARKERS] as const;
+const MAX_MARKER_LENGTH = Math.max(...ALL_MARKERS.map(marker => marker.length));
+/**
+ * True when `<system-reminder` at `at` is the tag rather than the start of a longer word.
+ *
+ * The opener is matched without its `>` so a truncated or self-closed tag still suppresses,
+ * which means `<system-reminders>` in an ordinary answer would otherwise open a block and
+ * refuse the turn. A stem running to the end of the buffer still counts: more text may be
+ * arriving, and reading it as prose is the one reading that could release the block body.
+ */
+function reminderOpensHere(lowered: string, at: number): boolean {
+  const after = lowered[at + REMINDER_OPEN.length];
+  return after === undefined || /[\s/>]/.test(after);
+}
+/**
+ * Ceiling on a suppressed block before it is treated as unterminated.
+ *
+ * The block itself is discarded as it arrives, so this is not a memory bound — only the
+ * trailing bytes needed to spot a split closer are retained. It bounds how much of a turn a
+ * single unclosed reminder is allowed to swallow silently before the turn is refused.
+ */
+const MAX_SUPPRESSED_CHARS = 64 * 1024;
+/** Result of feeding one chunk: the text safe to forward, and a refusal reason once tripped. */
+export interface ScaffoldFilterResult {
+  /** Text cleared for the client. Empty when everything in the chunk was held or dropped. */
+  text: string;
+  /** Non-null exactly once, on the chunk that trips the guard. */
+  fail: string | null;
+}
+/** Longest suffix of `text` that could still grow into one of the markers. */
+function heldSuffixLength(text: string): number {
+  const limit = Math.min(MAX_MARKER_LENGTH - 1, text.length);
+  for (let length = limit; length > 0; length--) {
+    const suffix = text.slice(text.length - length).toLowerCase();
+    for (const marker of ALL_MARKERS) {
+      if (marker.length > length && marker.startsWith(suffix)) return length;
+    }
+  }
+  return 0;
+}
+/**
+ * Streaming scaffolding filter for one channel (text or reasoning).
+ *
+ * One instance per channel: the two never share suppression state, so a reminder block
+ * opened in reasoning cannot swallow the answer text.
+ */
+export class QoderScaffoldFilter {
+  private mode: "pass" | "suppress" = "pass";
+  private pending = "";
+  private suppressedTail = "";
+  private suppressedChars = 0;
+  private failed = false;
+  /** True once a reminder block has been suppressed on this channel. */
+  private suppressedBlock = false;
+  /** Open reminder blocks; only the closer that unwinds the last one ends suppression. */
+  private suppressDepth = 0;
+  push(chunk: string): ScaffoldFilterResult {
+    if (this.failed || !chunk) return { text: "", fail: null };
+    let cleared = "";
+    let buffer = this.mode === "pass" ? this.pending + chunk : chunk;
+    this.pending = "";
+    for (;;) {
+      if (this.mode === "suppress") {
+        const scan = this.suppressedTail + buffer;
+        const scanned = scan.toLowerCase();
+        // Unwind nesting rather than ending at the first closer. A reminder containing another
+        // reminder would otherwise hand the outer block's remaining body — the MCP server list
+        // in the reported leak — to the client as the model's answer, with a successful
+        // terminal and nothing to signal that anything had gone wrong.
+        let cursor = 0;
+        let close = -1;
+        for (;;) {
+          const nextClose = scanned.indexOf(REMINDER_CLOSE, cursor);
+          if (nextClose < 0) break;
+          let nextOpen = scanned.indexOf(REMINDER_OPEN, cursor);
+          while (nextOpen >= 0 && !reminderOpensHere(scanned, nextOpen)) {
+            nextOpen = scanned.indexOf(REMINDER_OPEN, nextOpen + 1);
+          }
+          if (nextOpen >= 0 && nextOpen < nextClose) {
+            this.suppressDepth += 1;
+            cursor = nextOpen + REMINDER_OPEN.length;
+            continue;
+          }
+          this.suppressDepth -= 1;
+          cursor = nextClose + REMINDER_CLOSE.length;
+          if (this.suppressDepth === 0) {
+            close = nextClose;
+            break;
+          }
+        }
+        if (close < 0) {
+          this.suppressedChars += buffer.length;
+          if (this.suppressedChars > MAX_SUPPRESSED_CHARS) {
+            return this.fail(cleared, `an unterminated ${REMINDER_OPEN}> block`);
+          }
+          // The block is discarded as it arrives; only enough tail to spot a split closer is kept.
+          // The tail must cover a split opener too, now that nesting is counted.
+          this.suppressedTail = scan.slice(Math.max(0, scan.length - (MAX_MARKER_LENGTH - 1)));
+          return { text: cleared, fail: null };
+        }
+        buffer = scan.slice(close + REMINDER_CLOSE.length);
+        this.mode = "pass";
+        this.suppressedTail = "";
+        this.suppressedChars = 0;
+        continue;
+      }
+      let earliest = -1;
+      let found = "";
+      const lowered = buffer.toLowerCase();
+      for (const marker of ALL_MARKERS) {
+        let at = lowered.indexOf(marker);
+        while (at >= 0 && marker === REMINDER_OPEN && !reminderOpensHere(lowered, at)) {
+          at = lowered.indexOf(marker, at + 1);
+        }
+        if (at < 0) continue;
+        // A closer sitting exactly where an opener starts cannot happen, so ties are impossible.
+        if (earliest < 0 || at < earliest) {
+          earliest = at;
+          found = marker;
+        }
+      }
+      if (earliest < 0) {
+        const held = heldSuffixLength(buffer);
+        cleared += held > 0 ? buffer.slice(0, buffer.length - held) : buffer;
+        this.pending = held > 0 ? buffer.slice(buffer.length - held) : "";
+        return { text: cleared, fail: null };
+      }
+      // Text produced before the scaffolding is the model's own answer, and it is kept — but
+      // only while this channel has not already suppressed a block. Once it has, the text
+      // between that block and an unrepairable marker is not an answer that happens to
+      // precede a leak; it is the region the vendor was narrating in, and in the reported
+      // case it carries the MCP server list. Forwarding it on the way to a refusal would
+      // publish exactly what the refusal exists to contain.
+      // A closer with no opener never keeps its prefix either: the block it belonged to was
+      // already partly forwarded or never existed, so the text ahead of it is that body.
+      if (!CLOSING_MARKERS.has(found) && (found === REMINDER_OPEN || !this.suppressedBlock)) {
+        cleared += buffer.slice(0, earliest);
+      }
+      if (found !== REMINDER_OPEN) return this.fail(cleared, `vendor tool-call markup (${found})`);
+      this.suppressedBlock = true;
+      this.mode = "suppress";
+      this.suppressDepth = 1;
+      this.suppressedTail = "";
+      this.suppressedChars = 0;
+      buffer = buffer.slice(earliest + REMINDER_OPEN.length);
+    }
+  }
+  /** Release the held tail. Call before forwarding a terminal event, never mid-stream. */
+  flush(): ScaffoldFilterResult {
+    if (this.failed) return { text: "", fail: null };
+    if (this.mode === "suppress") return this.fail("", `an unterminated ${REMINDER_OPEN}> block`);
+    const text = this.pending;
+    this.pending = "";
+    return { text, fail: null };
+  }
+  private fail(cleared: string, reason: string): ScaffoldFilterResult {
+    this.failed = true;
+    this.pending = "";
+    this.suppressedTail = "";
+    return { text: cleared, fail: reason };
+  }
+}
+/**
+ * Message for a refused turn.
+ *
+ * It names the marker class and nothing else. The leaked reminder in the report enumerated
+ * the operator's own MCP servers, so echoing the offending text back — into an error the
+ * client renders, and that a user may paste into an issue — would publish the thing this
+ * guard exists to contain.
+ */
+export function qoderScaffoldErrorMessage(reason: string): string {
+  return `Qoder CLI emitted ${reason} in the assistant text channel. This route runs the CLI with`
+    + " its own tools and MCP servers disabled and Codex owns tool control, so the turn was refused"
+    + " rather than forwarding vendor agent scaffolding to the client.";
+}

package/src/claude/agents-inject.ts CHANGED Viewed

@@ -94,7 +94,23 @@ function entryParts(entry: string, config: OcxConfig): { alias: string; id: stri
   return { alias: claudeCodeNativeAlias(entry), id: entry, provider: "native" };
 }
-export function buildClaudeAgentDefs(config: OcxConfig, windows: Record<string, number>, configDir = claudeConfigDir()): ClaudeAgentDef[] {
+export function buildClaudeAgentDefs(
+  config: OcxConfig,
+  windows: Record<string, number>,
+  configDir = claudeConfigDir(),
+  /**
+   * The roster to generate defs from, overriding local `config.subagentModels` (#4236).
+   *
+   * A connected client's local roster is whatever it had before it joined the hub — on a fresh
+   * client, the five native defaults — while the hub's featured roster is the list that
+   * actually routes. Passing it in keeps this function pure and keeps the override visible at
+   * the call site instead of hidden behind a config read.
+   *
+   * Undefined preserves today's behaviour exactly, including "unset means the defaults, an
+   * explicit `[]` means none".
+   */
+  rosterOverride?: readonly string[],
+): ClaudeAgentDef[] {
   const blockedSkills = effectiveBlockedSkillNames(config.claudeCode);
   const blockedSkillsFor = (model: string): readonly string[] => {
     const unmarked = stripOneMillionMarker(model);
@@ -137,7 +153,8 @@ export function buildClaudeAgentDefs(config: OcxConfig, windows: Record<string,
   // Default roster applies only when the field is UNSET — an explicit [] is
   // respected (audit 071 #6: an upgraded config must not lose the default five).
-  const roster = config.subagentModels === undefined ? DEFAULT_SUBAGENT_MODELS : config.subagentModels;
+  const roster = rosterOverride
+    ?? (config.subagentModels === undefined ? DEFAULT_SUBAGENT_MODELS : config.subagentModels);
   for (const entry of roster.slice(0, 5)) {
     if (typeof entry !== "string" || entry.trim() === "") continue;
     const { alias, id, provider } = entryParts(entry.trim(), config);
@@ -260,13 +277,20 @@ export function syncClaudeAgentDefs(defs: readonly ClaudeAgentDef[], configDir =
 }
 /** Launch-time hook: gate + build + sync in one call (used by ocx claude and systemEnv). */
-export function injectClaudeAgentDefs(config: OcxConfig, windows: Record<string, number>, configDir?: string): string[] | null {
+export function injectClaudeAgentDefs(
+  config: OcxConfig,
+  windows: Record<string, number>,
+  configDir?: string,
+  /** Hub-sourced roster on a connected client; see `buildClaudeAgentDefs`. */
+  rosterOverride?: readonly string[],
+): string[] | null {
   if (config.claudeCode?.enabled === false || config.claudeCode?.injectAgents === false) {
     // Disabled: prune verified-owned files so stale definitions stop loading
-    // in future sessions (audit 071 #3).
+    // in future sessions (audit 071 #3). The roster override is irrelevant here by
+    // construction: there is nothing to build.
     return syncClaudeAgentDefs([], configDir);
   }
-  return syncClaudeAgentDefs(buildClaudeAgentDefs(config, windows, configDir), configDir);
+  return syncClaudeAgentDefs(buildClaudeAgentDefs(config, windows, configDir, rosterOverride), configDir);
 }
 /**
  * Dispatcher directive appended to every ocx-* description. The ocx-route body

package/src/claude/desktop-3p.ts CHANGED Viewed

@@ -22,6 +22,7 @@ import {
   type DesktopProfileModel,
 } from "./desktop-profile";
 import { nativeOpenAiContextWindow, type NativeContextLimitsInput } from "../codex/catalog";
+import { localAdmissionToken, localInferenceDestination } from "../lib/local-destinations";
 import { assertDesktop3pModelsValid } from "./desktop-3p-guard";
 export interface Desktop3pModelEntry {
@@ -322,9 +323,14 @@ export function activeDesktop3pAlias(provider: string, modelId: string): string
  * channel for supports1m/tier pins and it overrides discovery anyway (no merge), so
  * discovery stays off for determinism. supports1m makes Desktop offer a separate 1M
  * row; selecting it sends the bare id + `anthropic-beta: context-1m-2025-08-07`.
+ *
+ * `portOrOrigin` is the LOCAL destination Desktop should dial, already resolved by the caller
+ * (see `writeDesktop3pConfig`): on a hub that is the unauthenticated loopback listener, and with
+ * no listener the bind address — which is why an ORIGIN is accepted and not only a port. A bare
+ * port keeps meaning `http://127.0.0.1:<port>`, so every existing caller and test is unchanged.
  */
 export function generateDesktop3pConfig(
-  port: number,
+  portOrOrigin: number | string,
   nativeSlugs: string[],
   routedModels: Array<Desktop3pRoutedModel>,
   apiKey = "ocx",
@@ -335,7 +341,7 @@ export function generateDesktop3pConfig(
   const base = {
     inferenceProvider: "gateway",
     inferenceCredentialKind: "static",
-    inferenceGatewayBaseUrl: `http://127.0.0.1:${port}`,
+    inferenceGatewayBaseUrl: typeof portOrOrigin === "number" ? `http://127.0.0.1:${portOrOrigin}` : portOrOrigin,
     inferenceGatewayApiKey: apiKey,
   };
   if (mode === "discovery") {
@@ -620,8 +626,30 @@ export function writeDesktop3pConfig(
       if (connection.kind === "connected" || inspectRemoteDesktopCleanup().kind !== "absent") {
         return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_remote_store_active" };
       }
+      // Claude Desktop runs on this machine, so it dials the unauthenticated loopback listener
+      // when one is enabled — on such a hub that is the only credential-free local socket
+      // (#4236) — and otherwise the bind address, which answers but demands data-plane
+      // admission. Resolved here, from the config this write already re-read, rather than in
+      // the pure generator: `latest.config` is the freshest answer any caller could pass in.
+      const destination = localInferenceDestination(latest.config, port);
+      // Desktop can carry a credential, so it does: the key the caller passed (the first
+      // configured `apiKeys` entry), else the env token / hardened service token file. This is
+      // the DATA-PLANE secret only — an admin token must never enter an exported client
+      // configuration (reviewer constraint on #4236).
+      const gatewayKey = destination.requiresAdmissionToken
+        ? apiKey ?? localAdmissionToken(latest.config)
+        : apiKey;
+      if (destination.requiresAdmissionToken && !gatewayKey) {
+        // The placeholder the generator defaults to would 401 on this bind. Write the profile
+        // anyway — a reachable URL with a visible auth failure beats a dead socket — but say so.
+        console.error(
+          `⚠ Claude Desktop will dial ${destination.origin}, which requires an opencodex data-plane `
+          + "credential that could not be resolved. Configure an API key or enable "
+          + "`unauthenticatedLoopbackListener`.",
+        );
+      }
       return writeDesktop3pConfigWithGenerator(() => (
-        generateDesktop3pConfig(port, nativeSlugs, routedModels, apiKey, mode, profile, nativeContextCap)
+        generateDesktop3pConfig(destination.origin, nativeSlugs, routedModels, gatewayKey, mode, profile, nativeContextCap)
       ));
     }), lifecycleLockDeps);
   } catch { return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_lifecycle_busy_or_unsafe" }; }

package/src/claude/gateway-cache.ts CHANGED Viewed

@@ -13,7 +13,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets";
+import { localAdmissionToken, localInferenceDestination } from "../lib/local-destinations";
 import type { OcxConfig } from "../types";
 export interface GatewayModelRow {
@@ -24,7 +24,12 @@ export interface GatewayModelRow {
 export interface GatewayModelCacheRefreshOptions {
   timeoutMs?: number;
   configDir?: string;
-  admissionConfig?: Pick<OcxConfig, "apiKeys">;
+  /**
+   * Admission credential source AND local destination source: the cache file's `baseUrl` must
+   * equal the `ANTHROPIC_BASE_URL` the CLI is launched with or Claude Code ignores the whole
+   * cache, so this has to resolve the same loopback listener `buildClaudeEnv` resolves (#4236).
+   */
+  admissionConfig?: Pick<OcxConfig, "apiKeys" | "hostname" | "unauthenticatedLoopbackListener">;
   env?: NodeJS.ProcessEnv;
   fetchImpl?: typeof fetch;
 }
@@ -60,19 +65,6 @@ export function writeGatewayModelCache(baseUrl: string, models: readonly Gateway
   }
 }
-/**
- * Hardened service-token file, the same precedence `ocx opencode` uses. A service
- * install writes the admission token to disk rather than the interactive environment,
- * so an interactive `ocx claude` with neither env token nor configured key would
- * otherwise still get a 401 and keep a stale picker list.
- */
-function serviceFileToken(env: NodeJS.ProcessEnv): string | null {
-  const lookup = env.OCX_API_TOKEN_FILE?.trim()
-    ? env
-    : { ...env, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() };
-  return loadServiceTokenFromFile(lookup as Record<string, string | undefined>);
-}
 /** Fetch the anthropic-flavor /v1/models from the local proxy and write the cache. */
 export async function refreshGatewayModelCacheFromProxy(
   port: number,
@@ -92,17 +84,16 @@ export async function refreshGatewayModelCacheFromProxy(
     // request sent to its local 127.0.0.1 address. Reuse the same dedicated
     // credential domain as /v1/models admission; never place it in Authorization,
     // which can belong to an upstream provider on other data-plane surfaces.
-    const envToken = (options.env ?? process.env).OPENCODEX_API_AUTH_TOKEN?.trim();
-    const configuredToken = options.admissionConfig?.apiKeys
-      ?.find(entry => entry.key.trim().length > 0)
-      ?.key.trim();
+    // Env token, then the hardened service token file (a service install writes the admission
+    // token to disk rather than the interactive environment), then a configured key — one
+    // shared ladder, so this cannot drift from what `buildClaudeEnv` puts in the launch env.
     const admissionToken = typeof portOrTarget === "number"
-      ? envToken || serviceFileToken(options.env ?? process.env) || configuredToken
+      ? localAdmissionToken(options.admissionConfig, options.env ?? process.env)
       : portOrTarget.admissionToken;
     if (admissionToken) headers.set("x-opencodex-api-key", admissionToken);
     const baseUrl = typeof portOrTarget === "number"
-      ? `http://127.0.0.1:${portOrTarget}`
+      ? localInferenceDestination(options.admissionConfig, portOrTarget).origin
       : new URL(portOrTarget.baseUrl).origin;
     // ?ids=cli pins the readable claude-ocx id family deterministically (audit 051

package/src/claude/inbound.ts CHANGED Viewed

@@ -150,10 +150,17 @@ function blockedSkillCallIds(messages: readonly unknown[], blocked: readonly str
 /**
  * Claude Code (observed 2026-07-11, real CLI smoke) sends `role:"system"` entries in
- * `messages` despite the published API having no system role. Map them to Responses
- * instructions text: the native ChatGPT backend rejects system message items in
- * `input` ("System messages are not allowed", verified live), so folding into
- * `instructions` is the only shape that works on every route.
+ * `messages` despite the published API having no system role. They are emitted as
+ * chronological `role:"developer"` input items, which keeps the timeline intact and
+ * leaves `instructions` owned solely by the top-level Anthropic `system` field.
+ *
+ * The original mapping folded them into `instructions` because the native ChatGPT
+ * backend rejects `role:"system"` items in `input` ("System messages are not allowed",
+ * verified live). That constraint is real and still respected — but it only rules out
+ * `system`, not `developer`, which every Responses route accepts. Folding meant each
+ * mid-conversation reminder mutated the prompt head, invalidating the upstream KV
+ * prefix and rotating the Desktop `prompt_cache_key` fallback below on every turn
+ * (#4148).
  */
 function systemMessageText(content: unknown): string {
   if (typeof content === "string") return content;
@@ -333,7 +340,12 @@ function translateAnthropicRequest(raw: unknown, cc: OcxClaudeCodeConfig | undef
     else if (msg.role === "assistant") assistantMessageToItems(msg.content, input, budget);
     else if (msg.role === "system") {
       const text = systemMessageText(msg.content);
-      if (text.length > 0) systemParts.push(text);
+      // Keep it where the client put it. `developer` is first-class in the Responses
+      // schema and survives parseRequest as a chronological message, where `system`
+      // would be re-hoisted back onto the system prompt and defeat the point.
+      if (text.length > 0) {
+        input.push({ type: "message", role: "developer", content: [{ type: "input_text", text }] });
+      }
     }
     else throw new AnthropicRequestError(`unsupported message role: ${String(msg.role)}`);
   }

package/src/cli/account-api.ts CHANGED Viewed

@@ -18,10 +18,16 @@ export interface AccountRow {
   id: string;
   label?: string;
   email?: string;
-  plan?: string;
+  /**
+   * Subscription tier. `null` means this version looked and the provider did not report one;
+   * an absent key means the row's surface does not carry a tier at all (#3777).
+   */
+  plan?: string | null;
   masked?: string;
   active: boolean;
   needsReauth?: boolean;
+  /** Registered credential that is still excluded from routing until validation completes. */
+  validationPending?: boolean;
   /** Codex pool selection order, higher used earlier. Absent where ordering does not apply. */
   priority?: number;
   quota?: CodexQuotaDto | null;
@@ -237,6 +243,7 @@ interface CodexAccountDto {
   plan?: string;
   isMain?: boolean;
   needsReauth?: boolean;
+  health?: { reason?: string };
   priority?: number;
   quota?: CodexQuotaDto | null;
   quotaRefresh?: unknown;
@@ -263,10 +270,12 @@ export async function fetchCodexRows(
   baseUrl: string,
   forceRefresh = false,
   includeQuota = forceRefresh,
+  options: { refreshAction?: boolean } = {},
 ): Promise<FamilyRows> {
-  const accountsPath = `/api/codex-auth/accounts${forceRefresh ? "?refresh=1" : ""}`;
+  const refreshAction = options.refreshAction === true;
+  const accountsPath = `/api/codex-auth/accounts${refreshAction ? "/refresh" : forceRefresh ? "?refresh=1" : ""}`;
   const [accountsRes, activeRes] = await Promise.all([
-    apiJson(deps, baseUrl, "GET", accountsPath),
+    apiJson(deps, baseUrl, refreshAction ? "POST" : "GET", accountsPath),
     apiJson(deps, baseUrl, "GET", "/api/codex-auth/active"),
   ]);
   if (accountsRes.status !== 0 && accountsRes.status !== 200) {
@@ -300,6 +309,7 @@ export async function fetchCodexRows(
     plan: a.plan,
     active: a.id === activeId,
     needsReauth: a.needsReauth,
+    ...(a.health?.reason === "validation_pending" ? { validationPending: true } : {}),
     priority: typeof a.priority === "number" ? a.priority : 0,
     paused: a.paused === true,
     ...(includeQuota ? {
@@ -316,6 +326,8 @@ interface OAuthAccountDto {
   email?: string;
   active?: boolean;
   needsReauth?: boolean;
+  /** Always sent by the management route; explicitly `null` when the tier is unknown. */
+  plan?: string | null;
   quota?: CodexQuotaDto | null;
   quotaUnavailable?: boolean;
 }
@@ -346,6 +358,9 @@ async function fetchOAuthRows(
     email: a.email,
     active: a.active ?? a.id === activeId,
     needsReauth: a.needsReauth,
+    // Forward the server's answer verbatim, including `null`. Collapsing null to "absent" here
+    // would destroy the one distinction this field exists to make.
+    plan: a.plan ?? null,
     ...(a.quota !== undefined ? { quota: a.quota } : {}),
     ...(a.quotaUnavailable !== undefined ? { quotaUnavailable: a.quotaUnavailable } : {}),
   }));

package/src/cli/account-auth.ts CHANGED Viewed

@@ -154,7 +154,14 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
         {}, deps,
       );
       if (state.status === "done") {
-        printData({ ...state, modelSelection: modelSelectionNextSteps("openai") }, wantsJson, [`Logged in${state.email ? ` as ${String(state.email)}` : ""}.`, ...modelSelectionGuidance("openai")]);
+        if (state.validationPending === true) {
+          printData({ ...state, recoveryCommand: "ocx gui", recoveryAction: "After quota recovers, click Refresh quotas in the dashboard Codex account pool." }, wantsJson, [
+            "Account registered; validation pending (routing disabled).",
+            "After quota recovers, open 'ocx gui' and click Refresh quotas to complete validation.",
+          ]);
+        } else {
+          printData({ ...state, modelSelection: modelSelectionNextSteps("openai") }, wantsJson, [`Logged in${state.email ? ` as ${String(state.email)}` : ""}.`, ...modelSelectionGuidance("openai")]);
+        }
         if (!wantsJson) warnIfCodexCatalogRefreshPending(state);
         return;
       }