@bitkyc08/opencodex 2.50.0 → 2.51.0

package/src/grok/status.ts

@@ -111,11 +111,18 @@ export function readGrokStatus(opts: { grokHome?: string } = {}): GrokStatus {
  * `ocx status` is for.
  *
  * Returns null when there is nothing to say: no fence, an unparsable endpoint, or a
- * fence that already agrees with the live listener.
+ * fence that already agrees with a port we are actually listening on.
+ *
+ * "Listening on" is a SET, not one number (#4236). A hub with an unauthenticated loopback
+ * listener answers on the public port and on the listener's port; a fence pointing at the
+ * latter is exactly what `ocx sync` wrote, so reporting it as drift told the operator their
+ * working config was broken. `loopbackPort` is that second reachable port, already resolved
+ * through `effectiveLoopbackListenerPort`, or null when no such listener is configured.
  */
 export function grokFenceEndpointDrift(
   status: Pick<GrokStatus, "present" | "baseUrl">,
   livePort: number | undefined,
+  loopbackPort?: number | null,
 ): { fencePort: number; livePort: number } | null {
   if (!status.present || !status.baseUrl) return null;
   if (typeof livePort !== "number" || !Number.isFinite(livePort) || livePort <= 0) return null;
@@ -130,5 +137,6 @@ export function grokFenceEndpointDrift(
     return null;
   }
   if (!Number.isFinite(fencePort) || fencePort === livePort) return null;
+  if (typeof loopbackPort === "number" && fencePort === loopbackPort) return null;
   return { fencePort, livePort };
 }

package/src/integrations/config-io.ts

@@ -256,7 +256,10 @@ export function fileIO(): Omit<IntegrationIO, "appendJournal" | "putRecord" | "d
         return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "failed";
       }
     },
-    writeText: (path, text) => atomicWriteFile(path, text),
+    writeText: (path, text) => {
+      assertIntegrationWriteOwnership(path);
+      atomicWriteFile(path, text);
+    },
     removeFile: path => rmSync(path, { force: true }),
     mkdirp: path => mkdirSync(path, { recursive: true, mode: 0o700 }),
     now: () => Date.now(),
@@ -282,3 +285,53 @@ export function defaultIntegrationIO(store: {
     dropRecord: clientId => store.dropRecord(clientId),
   };
 }
+
+/**
+ * Refuse to replace an integration file this process does not own.
+ *
+ * `atomicWriteFile` writes a private temp file and renames it over the target. That is the right
+ * shape for a secret — the replacement is atomic and the result is owner-only `0600` — but it also
+ * means the surviving inode belongs to whoever runs opencodex. When the target is another product's
+ * configuration on a shared mount, the replace quietly takes the file away from its owner. #4197 is
+ * that case: opencodex at uid 1000 replaces a DSH `settings.yaml` owned by uid 987, and DSH dies with
+ * `EACCES` on its next read while the restore call reports success.
+ *
+ * Preserving the previous uid would need a `chown` capability we usually do not have, and relaxing
+ * `0600` would weaken every integration to fix one. So refuse before writing, and say what is wrong,
+ * rather than succeeding into a broken state.
+ *
+ * Windows has no uid model here; `hardenSecretPath` owns that platform, so the check is skipped when
+ * the runtime exposes no effective uid.
+ */
+export function assertIntegrationWriteOwnership(
+  path: string,
+  deps: {
+    effectiveUid?: () => number | undefined;
+    ownerUid?: (target: string) => number | undefined;
+  } = {},
+): void {
+  const effectiveUid = deps.effectiveUid ?? (() =>
+    typeof process.geteuid === "function" ? process.geteuid() : undefined);
+  const euid = effectiveUid();
+  if (euid === undefined) return;
+
+  const ownerUid = deps.ownerUid ?? ((target: string) => {
+    try {
+      return statSync(target).uid;
+    } catch {
+      // An absent or unreadable target has no owner to dispossess; the write itself will report
+      // any real failure.
+      return undefined;
+    }
+  });
+  const owner = ownerUid(path);
+  if (owner === undefined || owner === euid) return;
+
+  throw new Error(
+    `refusing to replace ${path}: it belongs to uid ${owner} while opencodex runs as uid ${euid}. `
+    + "An atomic replace would transfer ownership of that file and leave its owner unable to read "
+    + "its own configuration. Run both under the same user, or give each one its own copy instead "
+    + "of sharing the mount.",
+  );
+}
+

package/src/lib/bun-runtime.ts

@@ -176,7 +176,7 @@ export function durableBunRuntime(): DurableBunRuntime {
 /**
  * Bun path to bake into durable artifacts (launchd/systemd/Task Scheduler and
  * the Codex auto-start shim). Prefer the bundled binary — it lives under the
- * npm global prefix and survives across `ocx update` — and fall back to the
+ * manager-owned global package directory and survives across `ocx update` — and fall back to the
  * current runtime, which is Bun when launched normally.
  */
 export function durableBunPath(): string {

package/src/lib/gui-pair-capability.ts

@@ -38,6 +38,33 @@ export function canonicalGuiBrowserOrigin(value: unknown): string | null {
   }
 }
 
+/**
+ * A bare http(s) origin, or null.
+ *
+ * Stricter than {@link canonicalGuiBrowserOrigin}: that one also accepts non-HTTP schemes
+ * (a packaged app's custom scheme can be a browser origin), while this is the rule for an
+ * origin that will be DIALLED — the hub's management and data origins, and the `serverOrigin`
+ * a pairing grant is bound to. Credentials, a path, a query or a fragment are all rejected
+ * rather than silently dropped, because every caller goes on to print or compare the result.
+ *
+ * Exported here, beside the browser-origin canonicaliser, because this file is the only
+ * module the CLI pairing path and the hub command already share. `src/config.ts` and
+ * `src/server/gui-session.ts` still hold byte-identical private copies; folding those in
+ * would pull a heavy config import into a server security-boundary file, so it is its own
+ * change rather than a drive-by in a token-UX PR.
+ */
+export function canonicalHttpOrigin(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) return null;
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
 function capabilityPayload(
   nonce: string,
   method: string,

package/src/lib/local-destinations.ts

@@ -0,0 +1,162 @@
+/**
+ * Where a process running ON THE HUB ITSELF dials the hub (#4236).
+ *
+ * There are TWO destinations here, not one base URL substituted everywhere, and conflating
+ * them is what broke every local integration on a tailnet-bound hub:
+ *
+ * 1. `localManagementOrigin` — authenticated management discovery/state (`/api/*`). It is
+ *    served by the public listener and, on a hub, additionally by the loopback-only
+ *    `hub.managementIngress`. Callers must still send a management credential: management
+ *    authentication has no loopback bypass (structure/05), and the unauthenticated loopback
+ *    listener deliberately does not serve `/api/*` at all.
+ * 2. `localInferenceDestination` — the data plane a client wire actually speaks.
+ *
+ * Both resolvers have the SAME three-branch shape, because the bind address is the thing that
+ * decides. The first review of this module got that wrong for inference: it returned
+ * `http://127.0.0.1:<public port>` unconditionally whenever the loopback listener was off, so a
+ * hub with `hostname: <tailnet IP>` and no listener handed all eight call sites a socket that
+ * does not exist. The bind address has to be the fallback, exactly as it already was for
+ * management:
+ *
+ *   loopback listener enabled   → `127.0.0.1:<effective listener port>`, no credential
+ *   loopback/absent `hostname`  → `127.0.0.1:<public port>`, no credential
+ *   wildcard `hostname`         → `127.0.0.1:<public port>`, ADMISSION CREDENTIAL REQUIRED
+ *   anything else               → `<probeHostname(hostname)>:<public port>`, credential REQUIRED
+ *
+ * A wildcard bind does answer on 127.0.0.1, which is why its origin stays loopback, but the
+ * public listener demands data-plane admission regardless of which address received the
+ * request — so it lands in the same credential bucket as a tailnet bind. That is why the
+ * resolver returns a STRUCT rather than a string: a caller that cannot see
+ * `requiresAdmissionToken` cannot tell a free socket from one that will 401, and the only
+ * honest answers are "attach the data-plane credential" or "say so in a log line".
+ *
+ * The credential in question is the DATA-PLANE one — `OPENCODEX_API_AUTH_TOKEN`, the hardened
+ * service token file, or a configured `apiKeys` entry, the same ladder
+ * `standaloneCodexRoutingTarget` / the Codex provider table already uses. Never the admin
+ * token: no exported client configuration may carry management authority (reviewer constraint
+ * on #4236).
+ */
+import { effectiveLoopbackListenerPort, isLoopbackHostname, isWildcardHostname, shouldInjectApiAuthHeader } from "../codex/loopback-target";
+import { probeHostname } from "../server/proxy-liveness";
+import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "./service-secrets";
+import type { OcxConfig } from "../types";
+
+export type LocalInferenceConfig = Pick<OcxConfig, "hostname" | "unauthenticatedLoopbackListener">;
+export type LocalManagementConfig = Pick<OcxConfig, "hostname" | "runtimeRole" | "hub">;
+
+export interface LocalInferenceDestination {
+  /** Origin a local client wire dials, e.g. `http://127.0.0.1:10104`. */
+  origin: string;
+  /** Port component of `origin`. */
+  port: number;
+  /**
+   * Does the listener at `origin` demand `x-opencodex-api-key`?
+   *
+   * False only for the unauthenticated loopback listener and a genuinely loopback public bind.
+   * A caller that cannot attach a credential must log that it is degrading rather than write a
+   * destination that answers 401.
+   */
+  requiresAdmissionToken: boolean;
+}
+
+/**
+ * The one answer for "where does a local client send inference, and does it need a key?".
+ *
+ * Kept in one place so the day the resolution changes a forgotten site cannot point a client
+ * config at a closed socket — which is precisely the defect this module exists to close.
+ */
+export function localInferenceDestination(
+  config: LocalInferenceConfig | undefined,
+  publicPort: number,
+): LocalInferenceDestination {
+  const listenerPort = effectiveLoopbackListenerPort(config, publicPort);
+  if (listenerPort !== null) {
+    // Always bound to 127.0.0.1 and admits local callers with no credential, which is what
+    // lets an exported client configuration stay credential-free.
+    return { origin: `http://127.0.0.1:${listenerPort}`, port: listenerPort, requiresAdmissionToken: false };
+  }
+  const hostname = config?.hostname;
+  // A loopback bind keeps the byte-identical string every call site wrote before this module
+  // existed, including the `localhost`/`::1` spellings that `probeHostname` would preserve.
+  if (isLoopbackHostname(hostname)) {
+    return { origin: `http://127.0.0.1:${publicPort}`, port: publicPort, requiresAdmissionToken: false };
+  }
+  // `probeHostname` turns every all-zero spelling into 127.0.0.1 and brackets a bare IPv6
+  // literal; `shouldInjectApiAuthHeader` is the existing encoding of "this bind demands a
+  // data-plane credential", so the two stay in agreement by construction.
+  return {
+    origin: `http://${probeHostname(hostname)}:${publicPort}`,
+    port: publicPort,
+    requiresAdmissionToken: shouldInjectApiAuthHeader(config),
+  };
+}
+
+/**
+ * Every port this proxy's data plane answers on at 127.0.0.1 — the set an inherited
+ * `http://127.0.0.1:<port>` base URL must hit to count as one of OURS.
+ *
+ * On a tailnet bind with no loopback listener the set is EMPTY, and that is the point: a
+ * leftover `http://127.0.0.1:10100` from a previous loopback-bound install is a dead socket
+ * there, so `ocx claude` must replace it rather than preserve it as its own destination.
+ */
+export function localLoopbackInferencePorts(
+  config: LocalInferenceConfig | undefined,
+  publicPort: number,
+): number[] {
+  const ports: number[] = [];
+  // A wildcard bind owns loopback on the public port too, so a URL naming it is still ours.
+  if (isLoopbackHostname(config?.hostname) || isWildcardHostname(config?.hostname)) ports.push(publicPort);
+  const listenerPort = effectiveLoopbackListenerPort(config, publicPort);
+  if (listenerPort !== null && !ports.includes(listenerPort)) ports.push(listenerPort);
+  return ports;
+}
+
+/**
+ * The DATA-PLANE admission credential this host can present to its own public listener.
+ *
+ * Same ladder the Codex provider table and `ocx opencode` already use — environment token,
+ * hardened service token file, first configured `apiKeys` entry — and deliberately NOT the
+ * admin token, which must never leave the management surface. `undefined` means the caller has
+ * nothing to attach and has to degrade loudly.
+ */
+export function localAdmissionToken(
+  config: Pick<OcxConfig, "apiKeys"> | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const envToken = env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (envToken) return envToken;
+  const lookup = env.OCX_API_TOKEN_FILE?.trim()
+    ? env
+    : { ...env, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() };
+  const fileToken = loadServiceTokenFromFile(lookup as Record<string, string | undefined>)?.trim();
+  // Shape-check the FILE candidate only. The env var and `apiKeys` are values an operator set
+  // deliberately and pass through verbatim; a path, by contrast, can be pointed at or replaced
+  // by something that is not a credential at all, and sending that as one leaks file contents
+  // into a request header. Configured keys are never checked, so no existing key can be broken.
+  if (fileToken && ADMISSION_TOKEN_SHAPE.test(fileToken)) return fileToken;
+  const configured = config?.apiKeys?.find(entry => entry.key.trim().length > 0)?.key.trim();
+  return configured || undefined;
+}
+
+/** An admission credential is an opaque printable token — never JSON, a path, or multi-line. */
+const ADMISSION_TOKEN_SHAPE = /^[A-Za-z0-9._~+/=-]{8,4096}$/;
+
+/**
+ * The origin a local CLI dials for `/api/*`.
+ *
+ * A hub's management ingress is loopback-only and exists precisely so the operator's own
+ * machine has a management address when the proxy listener is bound elsewhere. Everything else
+ * keeps dialing the public listener on the bind address it can actually reach — `probeHostname`
+ * turns a wildcard bind into 127.0.0.1 and brackets a bare IPv6 literal.
+ *
+ * The caller still supplies the management credential. Never write that credential into an
+ * exported client configuration.
+ */
+export function localManagementOrigin(
+  config: LocalManagementConfig | undefined,
+  publicPort: number,
+): string {
+  const ingress = config?.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
+  if (ingress?.enabled) return `http://127.0.0.1:${ingress.port}`;
+  return `http://${probeHostname(config?.hostname)}:${publicPort}`;
+}

package/src/lib/package-tree-integrity.ts

@@ -16,7 +16,7 @@ export interface PackageTreeIntegrityGuard {
 }
 
 type ObservePackageTree = () => PackageTreeObservation | null;
-type PackageTreeRuntimeInstall = "bun" | "npm" | "source";
+type PackageTreeRuntimeInstall = "bun" | "npm" | "pnpm" | "source";
 
 const packageManifestUrl = new URL("../../package.json", import.meta.url);
 

package/src/lib/process-control.ts

@@ -80,17 +80,96 @@ export type GracefulStopResult = boolean | "refused" | "teardown-unconfirmed";
  */
 let lastRefusalMessage: string | null = null;
 
+/**
+ * The server's machine-readable reason for the most recent 409, captured alongside the
+ * message so a refusal that arrives without a body still names the right cause. Without it
+ * the fallback has to guess, and guessing "ownership" sent operators to re-check
+ * CODEX_HOME for a refusal the scheduler wrapper had issued (#4169).
+ */
+let lastRefusalCode: string | null = null;
+
 /** The server's explanation for the most recent 409, or `null` when it sent none. */
 export function lastStopRefusalMessage(): string | null {
   return lastRefusalMessage;
 }
 
+/** The server's `code` for the most recent 409, or `null` when it sent none. */
+export function lastStopRefusalCode(): string | null {
+  return lastRefusalCode;
+}
+
+/**
+ * Wording for a refusal whose body carried no message. Each branch mirrors a refusal the
+ * management API can return from `POST /api/stop`; the default stays cause-neutral because
+ * naming the wrong cause is worse than naming none — it costs the operator the time they
+ * spend acting on it.
+ *
+ * These name the cause only. The command belongs to {@link refusalNextStep}, because the
+ * only callers of `stopProxy` are `ocx stop` and the service manager's own cleanup, and a
+ * message that told either of them to run `ocx stop` would be the #4169 loop again.
+ */
+function refusalFallbackMessage(code: string | null): string {
+  switch (code) {
+    case "respawnable_service":
+      return "The running proxy refused to stop: a service manager that can respawn it owns "
+        + "the process.";
+    case "self_unload_service":
+      return "The running proxy refused to stop: it is the installed service itself, so "
+        + "stopping the manager from inside it would end the process before native Codex is "
+        + "restored.";
+    case "service_state_unknown":
+      return "The running proxy refused to stop: the service manager state could not be read, "
+        + "so it cannot tell whether a wrapper would respawn it.";
+    default:
+      return "The running proxy refused to stop and sent no reason.";
+  }
+}
+
+/**
+ * What is actually left to do when `ocx stop` is the command that received the refusal.
+ *
+ * Every refusal `POST /api/stop` produces is written for an API client, so it recommends
+ * `ocx stop` — which is the command already running when the CLI prints it. That is the
+ * loop #4169 reports: the endpoint points at `ocx stop`, `ocx stop` repeats the endpoint,
+ * and neither names the wrapper that is refusing. `ocx stop` has already asked the service
+ * manager to stop by the time this is reached, so the remaining question is always what the
+ * service manager is doing, and no branch may answer with the command that just failed.
+ */
+export function refusalNextStep(code: string | null): string {
+  switch (code) {
+    case "respawnable_service":
+      return "This stop already asked the service manager to stop, so running `ocx stop` "
+        + "again is not the missing step. Run `ocx service status` to see whether a wrapper "
+        + "is still installed and able to respawn the proxy.";
+    case "self_unload_service":
+      return "This stop already asked the service manager to stop, so running `ocx stop` "
+        + "again is not the missing step. Run `ocx service status` to see whether the service "
+        + "is still registered.";
+    case "service_state_unknown":
+      return "Run `ocx service status` to see the query error, repair the service manager "
+        + "access, then retry.";
+    default:
+      return "Run `ocx service status` to inspect the service state.";
+  }
+}
+
 /**
  * A proxy declined shutdown (HTTP 409). There is more than one reason it can say no — a
  * scheduler wrapper under another home, or the proxy being the installed service itself
  * (#4023) — so the server's own message is carried through rather than guessed at.
+ *
+ * The refusal's `code` travels on the error because the reporting caller has to act on the
+ * cause, not re-parse prose: the message is the server's, and it recommends a command the
+ * CLI has already run.
  */
-export class ProxyOwnershipRefusedError extends Error {}
+export class ProxyOwnershipRefusedError extends Error {
+  readonly code: string | null;
+
+  constructor(message: string, code: string | null = null) {
+    super(message);
+    this.code = code;
+  }
+}
 
 /**
  * Ask a running proxy to stop itself via the management API (`POST /api/stop`), which
@@ -104,9 +183,28 @@ export class ProxyOwnershipRefusedError extends Error {}
  * attest the process exit code or completion of every drain/shutdown hook.
  */
 export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}): Promise<GracefulStopResult> {
+  return (await stopProxyGracefullyDetailed(pid, io)).result;
+}
+
+/**
+ * The refusal a single stop attempt received, carried back to that attempt's caller.
+ *
+ * Module-scoped state cannot do this job: two overlapping stops race, and the first would
+ * report the second's cause. The exported accessors stay as observational state for callers
+ * that only want the last refusal, but the error text is built from this per-call value.
+ */
+type StopRefusal = { message: string | null; code: string | null };
+
+async function stopProxyGracefullyDetailed(
+  pid: number,
+  io: GracefulStopIo = {},
+): Promise<{ result: GracefulStopResult; refusal: StopRefusal }> {
+  const refusal: StopRefusal = { message: null, code: null };
+  const done = (result: GracefulStopResult): { result: GracefulStopResult; refusal: StopRefusal } =>
+    ({ result, refusal });
   const readRuntime = io.readRuntime ?? readRuntimePort;
   const runtime = io.runtimeEndpoint ?? readRuntime(pid);
-  if (!runtime?.port) return false;
+  if (!runtime?.port) return done(false);
   const env = io.env ?? process.env;
   const headers: Record<string, string> = {};
   const token = configuredAdminToken(env.OPENCODEX_HOME?.trim() || undefined, env as NodeJS.ProcessEnv);
@@ -128,20 +226,31 @@ export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}):
       // longer than a health poll so we prefer drain over taskkill /F.
       signal: AbortSignal.timeout(io.exitTimeoutMs ? Math.min(io.exitTimeoutMs, 10_000) : 10_000),
     });
-    // 409 is the proxy REFUSING to stop (a service installed under another home owns it and
-    // would respawn it anyway). That is a policy answer, not a dead endpoint — escalating to
-    // SIGTERM here would run the daemon's cleanup and strip shared config out from under the
+    // 409 is the proxy REFUSING to stop. There is more than one reason it can say no — a
+    // respawning service manager, the proxy being the installed service itself, or an
+    // unreadable scheduler state — so both the message and the code are captured rather
+    // than assumed. That is a policy answer, not a dead endpoint — escalating to SIGTERM
+    // here would run the daemon's cleanup and strip shared config out from under the
     // still-running service. Report the refusal instead of forcing.
     if (res.status === 409) {
-      lastRefusalMessage = await res.json()
+      const parsed = await res.json()
         .then(body => {
-          const message = (body as { message?: unknown } | null)?.message;
-          return typeof message === "string" && message.trim() ? message.trim() : null;
+          const record = body as { message?: unknown; code?: unknown } | null;
+          const message = record?.message;
+          const code = record?.code;
+          return {
+            message: typeof message === "string" && message.trim() ? message.trim() : null,
+            code: typeof code === "string" && code.trim() ? code.trim() : null,
+          };
         })
-        .catch(() => null);
-      return "refused";
+        .catch(() => ({ message: null, code: null }));
+      refusal.message = parsed.message;
+      refusal.code = parsed.code;
+      lastRefusalMessage = parsed.message;
+      lastRefusalCode = parsed.code;
+      return done("refused");
     }
-    if (!res.ok) return false;
+    if (!res.ok) return done(false);
     const body: unknown = await res.json().catch(() => null);
     const expectedTeardown = io.deferSharedTeardownNonce ? "deferred" : "performed";
     sharedTeardownConfirmed = body !== null
@@ -150,14 +259,14 @@ export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}):
       && "success" in body && body.success === true
       && "sharedTeardown" in body && body.sharedTeardown === expectedTeardown;
   } catch {
-    return false;
+    return done(false);
   }
   const waitExit = io.waitExit ?? waitForExit;
   // Honor the server's own drain window: /api/stop answers 200 first, then drains for
   // config.shutdownTimeoutMs. Waiting less than that hard-kills mid-drain.
   const exitTimeoutMs = io.exitTimeoutMs ?? drainDeadlineMs();
-  if (!waitExit(pid, exitTimeoutMs)) return false;
-  return sharedTeardownConfirmed ? true : "teardown-unconfirmed";
+  if (!waitExit(pid, exitTimeoutMs)) return done(false);
+  return done(sharedTeardownConfirmed ? true : "teardown-unconfirmed");
 }
 
 function drainDeadlineMs(): number {
@@ -172,14 +281,15 @@ function drainDeadlineMs(): number {
 export async function stopProxy(pid: number, io: GracefulStopIo = {}): Promise<boolean> {
   if (!isProcessAlive(pid)) return false;
   const runtime = io.runtimeEndpoint ?? readRuntimePort(pid);
-  const graceful = await stopProxyGracefully(pid, io);
+  const { result: graceful, refusal } = await stopProxyGracefullyDetailed(pid, io);
   if (graceful === "refused") {
-    // The proxy refused on purpose (foreign service owns it). Forcing would strip shared
-    // config while that service keeps the proxy alive.
+    // The proxy refused on purpose. Forcing would strip shared config while whatever owns
+    // the process keeps it alive. The server's own message is preferred; the fallback is
+    // selected from its code so an empty body still names the right cause. Both come from
+    // THIS attempt, so an overlapping stop cannot lend it the wrong reason.
     throw new ProxyOwnershipRefusedError(
-      lastRefusalMessage
-      ?? "The running proxy refused to stop: a service installed under a different "
-        + "CODEX_HOME/OPENCODEX_HOME owns it. Run the stop from that home.",
+      refusal.message ?? refusalFallbackMessage(refusal.code),
+      refusal.code,
     );
   }
   if (graceful === "teardown-unconfirmed") {

package/src/lib/service-secrets.ts

@@ -184,6 +184,34 @@ export function loadServiceTokenFromFile(env: Record<string, string | undefined>
   }
 }
 
+/**
+ * The data-plane token a boot should export, or null when the environment already has one
+ * (or there is nothing to export).
+ *
+ * The launchd plist and the systemd unit `cat` the token file into the environment before
+ * exec'ing the proxy, and WinSW native mode names it through `OCX_API_TOKEN_FILE` — so under
+ * a service the server has always seen `OPENCODEX_API_AUTH_TOKEN` regardless of the calling
+ * shell. A FOREGROUND `ocx start` on the same machine had neither, so `assertServerAuthConfig`
+ * refused to bind a non-loopback hostname that the installed service was serving happily.
+ * This closes that gap with the same precedence the wrappers use, in one place.
+ *
+ * `authRequired` is the caller's admission decision (`isApiAuthRequired`), passed in rather
+ * than recomputed: this module must not load config, and the installed file is deliberately
+ * NOT consulted on a loopback bind — on a machine connected to a hub it holds that hub's
+ * issued client key, which is not this proxy's admission secret.
+ */
+export function startupDataPlaneToken(
+  env: Record<string, string | undefined>,
+  options: { authRequired: boolean },
+): string | null {
+  if (env.OPENCODEX_API_AUTH_TOKEN?.trim()) return null;
+  const named = loadServiceTokenFromFile(env);
+  if (named) return named;
+  if (!options.authRequired) return null;
+  const state = readServiceApiTokenState();
+  return state.kind === "present" ? state.token : null;
+}
+
 /**
  * Contents of the installed service token file. The launch wrapper always re-exports
  * this file as OPENCODEX_API_AUTH_TOKEN, so doctor and start must inspect it even

package/src/lib/test-home-guard.ts

@@ -61,6 +61,16 @@ function canonicalize(path: string): string {
 const REAL_HOME = process.env[REAL_HOME_ENV]?.trim() || homedir();
 const PROTECTED_HOME = canonicalize(join(REAL_HOME, ".opencodex"));
 const PROTECTED_CODEX_HOME = canonicalize(join(REAL_HOME, ".codex"));
+/**
+ * `~/Library/LaunchAgents` needs its own entry because HOME isolation does not reach it:
+ * `os.homedir()` reads the password database, not `$HOME`, so a macOS test that rewrites
+ * HOME still resolves `plistPath()` to the developer's real LaunchAgents directory. The
+ * launchd install tests were doing exactly that — replacing the live
+ * `com.opencodex.proxy.plist` with one whose token file, log path and Bun paths all point
+ * into a temp sandbox, for as long as the case ran. launchd holds its own parsed copy, so
+ * nothing broke until the job next restarted.
+ */
+const PROTECTED_LAUNCH_AGENTS = canonicalize(join(REAL_HOME, "Library", "LaunchAgents"));
 
 /** The production home this process protects. Exported for the guard's own tests. */
 export function protectedHomeForTests(): string {
@@ -76,6 +86,23 @@ export function isTestHomeGuardArmed(): boolean {
   return process.env[GUARD_ENV] === "1";
 }
 
+/**
+ * Whether `dir` IS the protected production home, decided with the SAME canonicalization as
+ * {@link assertNotRealHomeUnderTest}.
+ *
+ * For the caller that must FILTER the real home out of a candidate list instead of refusing
+ * one write: `serviceStatePaths()` in `src/service.ts` keeps a legacy
+ * `~/.opencodex/service-state.json` entry so an install made before OPENCODEX_HOME existed
+ * can still be found, and under an armed test process that entry is the developer's live
+ * record. Exported so that filter cannot drift onto a weaker comparison — `resolve()` alone
+ * calls `/var/folders/...` and `/private/var/folders/...` different paths, which is exactly
+ * how a macOS sandbox path slips past a string compare.
+ */
+export function isProtectedHomeUnderTest(dir: string): boolean {
+  if (!isTestHomeGuardArmed()) return false;
+  return canonicalize(dir) === PROTECTED_HOME;
+}
+
 /**
  * Throw when an armed test process is about to write the real OpenCodex home.
  *
@@ -94,6 +121,28 @@ export function assertNotRealHomeUnderTest(dir: string): void {
   );
 }
 
+/** The production LaunchAgents directory this process protects. Exported for its tests. */
+export function protectedLaunchAgentsDirForTests(): string {
+  return PROTECTED_LAUNCH_AGENTS;
+}
+
+/**
+ * Throw when an armed test process is about to write the real `~/Library/LaunchAgents`.
+ *
+ * Same contract as {@link assertNotRealHomeUnderTest}: call before any mkdir/write, and
+ * pass a DIRECTORY. A launchd test gives `installLaunchd` an explicit plist path inside its
+ * own fixture directory instead.
+ */
+export function assertNotRealLaunchAgentsUnderTest(dir: string): void {
+  if (!isTestHomeGuardArmed()) return;
+  if (canonicalize(dir) !== PROTECTED_LAUNCH_AGENTS) return;
+  throw new Error(
+    `refusing to write the real LaunchAgents directory (${PROTECTED_LAUNCH_AGENTS}) from a test `
+    + "process: os.homedir() ignores HOME, so rewriting HOME does not move this path. Pass an "
+    + "explicit plist path inside the test's own fixture directory instead.",
+  );
+}
+
 /** Throw when an armed test process is about to write the real native Codex home. */
 export function assertNotRealCodexHomeUnderTest(dir: string): void {
   if (!isTestHomeGuardArmed()) return;

package/src/providers/opencode-go-transport.ts

@@ -22,7 +22,15 @@ export function deriveOpenCodeGoSessionId(sessionLane: string): string {
   return `ocx_${digest}`;
 }
 
-/** Add per-conversation Go affinity only to the canonical fixed-key destination. */
+/**
+ * Add Go affinity only to the canonical fixed-key destination.
+ *
+ * Callers on the request path resolve the lane with `getOrAllocateRequestSessionLane`, which returns
+ * real conversation identity when the client supplied it and a per-request value otherwise, so a
+ * request reaching this helper from the proxy always carries a lane. The `!sessionLane` guard stays
+ * for direct callers that have no request context; it is not a per-request identity of its own, and
+ * minting one here would hand each retry a different value.
+ */
 export function resolveOpenCodeGoTransport<T extends OcxProviderConfig>(
   provider: T,
   sessionLane: string | undefined,

package/src/providers/quota.ts

@@ -2906,7 +2906,11 @@ function keyQuotaReaderForProvider(name: string, provider: OcxProviderConfig): K
   if (name === "deepseek" && isCanonicalDeepSeekBaseUrl(provider.baseUrl)) return fetchDeepSeekQuota;
   if (name === "cline-pass" && isCanonicalClineBaseUrl(provider.baseUrl)) return fetchClineQuota;
   if (isCanonicalOllamaCloudBaseUrl(provider.baseUrl ?? getProviderRegistryEntry(name)?.baseUrl)) return fetchOllamaCloudQuota;
-  if (["zai", "glm", "glm-cn", "zhipu-bigmodel-coding"].includes(name) && isCanonicalZaiBaseUrl(provider.baseUrl)) return fetchZaiQuota;
+  // #4201: the Responses preset is the same domestic GLM Coding Plan subscription on the OpenAI
+  // Responses wire, so it reads the same monitor endpoint. Eligibility stays a name list AND the
+  // canonical-URL guard: the guard is what keeps BigModel's bare-key Authorization from reaching a
+  // lookalike host, so a same-named custom destination still dispatches nothing.
+  if (["zai", "glm", "glm-cn", "zhipu-bigmodel-coding", "zhipu-bigmodel-responses"].includes(name) && isCanonicalZaiBaseUrl(provider.baseUrl)) return fetchZaiQuota;
   if (["minimax", "minimax-cn"].includes(name) && isCanonicalMinimaxBaseUrl(provider.baseUrl)) return fetchMinimaxQuota;
   if (name === "moonshot" && isCanonicalMoonshotBaseUrl(provider.baseUrl)) return fetchMoonshotQuota;
   if (name === "venice" && isCanonicalVeniceBaseUrl(provider.baseUrl)) return fetchVeniceQuota;