@bitkyc08/opencodex 2.50.0 → 2.52.0-preview.20260911

package/src/adapters/qoder/adapter.ts

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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/cli/capabilities.ts

@@ -132,6 +132,34 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "envelope",
     details: ["Reads /healthz plus local config; drives no management API route."],
   },
+  {
+    command: ["hub", "invite"],
+    summary: "Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.",
+    // Deliberately empty. The command DOES drive `POST /api/gui/pairing-grants` -- the attested
+    // local mint route `ocx gui pair` uses, authorized by a capability HMAC'd with the running
+    // proxy's own attestation secret rather than by the admin token, which is why it needs
+    // nothing exported in the shell. That route is answered in the composition root, ahead of
+    // `handleManagementAPI`, so it is not in MANAGEMENT_ROUTES; declaring it here would fail the
+    // capability/registry reconciliation rather than inform anyone. Widening the registry's scope
+    // to `src/server/index.ts` is its own change.
+    routes: [],
+    flags: [
+      { name: "--json", value: "boolean", summary: "Emit code, expiresAt, dataUrl, managementUrl, and command." },
+      { name: "--data-url", value: "string", summary: "Advertise this data origin instead of hub.dataPublicOrigin or the bind address." },
+      { name: "--management-url", value: "string", summary: "Confirm the management origin; it must equal hub.managementPublicOrigin." },
+      { name: "--clients", value: "string", summary: "Pre-select codex and/or claude in the printed connect command." },
+    ],
+    mutates: true,
+    json: "envelope",
+    details: [
+      "Hub only: refuses when runtimeRole is not hub, and requires a running attested proxy.",
+      "The code is secret, single-use and short-lived; it is bound to hub.managementPublicOrigin and to the connecting machine's loopback browser origin.",
+      "The bound browser origin is always printed; when it is not http://localhost:10100 the warning names the port the connecting machine must use.",
+      "Refuses when the advertised data origin would be loopback (a loopback or wildcard bind with no hub.dataPublicOrigin and no --data-url) rather than printing a line that dials the other machine itself.",
+      "Prints no data-plane token. Remote machines receive their own revocable per-client key from the exchange.",
+      "Mints through the attested local pairing-grant route, the same one ocx gui pair uses; no admin token is read.",
+    ],
+  },
   {
     command: ["connect", "rotate"],
     summary: "Rotate the connected client's data key against the hub, with commit and abort.",

package/src/cli/claude-agent-startup-sync.ts

@@ -1,5 +1,6 @@
 import type { OcxConfig } from "../types";
 import { injectClaudeAgentDefs } from "../claude/agents-inject";
+import { readCachedHubState } from "../client/hub-state";
 import { fetchClaudeContextWindows } from "./claude";
 import type { ReadinessGate } from "../server/readiness";
 
@@ -7,6 +8,30 @@ export interface ClaudeAgentStartupSyncDeps {
   fetchContextWindows?: typeof fetchClaudeContextWindows;
   injectAgentDefs?: typeof injectClaudeAgentDefs;
   warn?: (message: string) => void;
+  /** Seam for the hub roster lookup; the default reads only the on-disk cache. */
+  readHubRoster?: (config: OcxConfig) => readonly string[] | undefined;
+}
+
+/**
+ * The hub's roster for a connected client, from the CACHE only (#4236).
+ *
+ * Startup deliberately makes no network call for this. The roster is a convenience here — `ocx
+ * claude` does the live read on the path where it matters — and a hub round trip on every proxy
+ * start would put an offline hub in the way of a local launch. Undefined falls back to local
+ * `subagentModels`, which is what this path has always used.
+ */
+function cachedHubRoster(config: OcxConfig): readonly string[] | undefined {
+  if (config.runtimeRole !== "client" || !config.client) return undefined;
+  try {
+    const cached = readCachedHubState({
+      serverUrl: config.client.serverUrl,
+      apiKeyId: config.client.apiKeyId,
+      connectedAt: config.client.connectedAt,
+    });
+    return cached?.state.subagentModels;
+  } catch {
+    return undefined;
+  }
 }
 
 /**
@@ -70,7 +95,7 @@ export async function syncClaudeAgentDefsAtProxyStartup(
       // Startup remains best-effort. The next management mutation or `ocx claude` launch can
       // restore context markers after a transient catalog/Management API failure.
     }
-    return inject(config, windows);
+    return inject(config, windows, undefined, (deps.readHubRoster ?? cachedHubRoster)(config));
   } catch (error) {
     warn(`⚠ Claude agent definitions could not be synced at proxy startup: ${error instanceof Error ? error.message : String(error)}`);
     return null;