@bitkyc08/opencodex 2.67.0 → 2.68.0-preview.20260927

package/src/client/machine-api.ts

@@ -3,6 +3,7 @@ import { diagnoseCodexShim, installCodexShim, uninstallCodexShim } from "../code
 import { readManagementJsonBody } from "../server/management/body";
 import type { OcxClientConnectionConfig } from "../types";
 import { disconnectClient, syncConnectedClient } from "./connect";
+import { isLinkConnection } from "./state";
 
 export type HubReachability = "unknown" | "online" | "offline" | "unauthorized";
 
@@ -50,14 +51,19 @@ async function jsonBody(req: Request): Promise<unknown | Response> {
 
 function statusPayload(req: Request, state: OcxClientConnectionConfig, deps: MachineApiDeps): MachineStatusV1 {
   const machineBase = new URL(req.url).origin;
+  // A link Child's management URL is the tunnel, whose hub-link ingress serves no /api/* and no
+  // session bootstrap. Its dashboard reads the Child's own listener instead (`/api/link/status`).
+  const linkMode = isLinkConnection(state);
   return {
     mode: "client",
     connected: true,
     machineBase,
-    sharedBase: state.managementTransport === "relay"
-      ? `${machineBase}/api/machine/hub-relay`
-      : state.managementUrl,
-    sharedServerOrigin: state.managementUrl,
+    sharedBase: linkMode
+      ? machineBase
+      : state.managementTransport === "relay"
+        ? `${machineBase}/api/machine/hub-relay`
+        : state.managementUrl,
+    sharedServerOrigin: linkMode ? machineBase : state.managementUrl,
     managementTransport: state.managementTransport,
     apiKeyId: state.apiKeyId,
     protocolVersion: state.protocolVersion,

package/src/client/machine-listener.ts

@@ -1,6 +1,6 @@
 import type { Server } from "bun";
 import { loadConfig } from "../config";
-import { browserSecurityHeaders } from "../server/auth-cors";
+import { browserSecurityHeaders, requestPolicyView } from "../server/auth-cors";
 import { serveGuiFile, serveSessionBootstrap } from "../server/gui-static";
 import {
   initializeManagementAuthState,
@@ -9,13 +9,18 @@ import {
   requireManagementAuth,
   type ManagementAuthState,
 } from "../server/management-auth";
+import { resolveInboundBodyLimitBytes } from "../server/request-decompress";
 import type { OcxClientConnectionConfig, OcxConfig } from "../types";
 import { disconnectClient, syncConnectedClient } from "./connect";
 import { isLinkConnection, readClientConnectionState } from "./state";
 import { handleMachineApi, type HubReachability, type MachineApiDeps } from "./machine-api";
 import { MACHINE_GUI_ORIGIN_HEADER, requireMachineAuth } from "./machine-auth";
 import { HUB_RELAY_REQUEST_BODY_MAX_BYTES, relayHubManagementRequest } from "./hub-relay";
-import { relayLinkDataRequest } from "./link-relay";
+import { createLinkKeySource, handleLinkIngress, type LinkIngress, type LinkKeySourceDeps } from "./link-ingress";
+import type { LinkTunnelGate } from "./link-relay";
+import { readClientLinkState, type ClientLinkState } from "./link-state";
+import { projectClientLinkChild, type ClientLinkSidecarRead } from "./link-status";
+import type { ClientLinkSupervisorStatus } from "./link-tunnel";
 import { packageVersion } from "../lib/package-version";
 import { linkRouteAllowed } from "../link/routes";
 
@@ -24,12 +29,27 @@ const GUI_SPA_PATHS = new Set([
   "/dashboard", "/startup", "/providers", "/models", "/subagents",
   "/logs", "/usage", "/storage", "/codex-set", "/integrations",
 ]);
+/** The standalone listener's idle limit: long generations and held turns are never cut. */
+const LINK_LISTENER_IDLE_TIMEOUT_SECONDS = 255;
 
 export interface MachineListenerDeps {
   state?: OcxClientConnectionConfig;
   managementAuthState?: ManagementAuthState;
   fetchImpl?: typeof fetch;
   machineApi?: Partial<MachineApiDeps>;
+  /** Link mode: the client tunnel supervisor state for `GET /api/link/status`. */
+  linkStatus?: () => ClientLinkSupervisorStatus;
+  /** Link mode: the sidecar read for `GET /api/link/status`. */
+  readSidecar?: () => ClientLinkState | null;
+  /** Link mode: how the link key is read; the listener reads it once and caches it. */
+  linkKey?: LinkKeySourceDeps;
+  /** Link mode: a key source the runtime already holds (shared with the tunnel supervisor). */
+  linkKeySource?: () => string | null;
+  /** Link mode: the tunnel supervisor; relayed requests wait on it while it reconnects. */
+  linkTunnel?: LinkTunnelGate;
+  /** Link mode: relay seams (deadline clock and byte cap). */
+  linkRelay?: LinkIngress["relay"];
+  serve?: (options: Parameters<typeof Bun.serve>[0]) => Server<unknown>;
 }
 
 function json404(req: Request): Response {
@@ -47,6 +67,8 @@ export function machineRouteAllowed(url: URL, req: Request, relayEnabled: boolea
   const path = url.pathname;
   if (req.method === "GET" && (path === "/healthz" || path === "/readyz" || path === "/" || path === "/opencodex-session")) return true;
   if ((req.method === "GET" || req.method === "HEAD") && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
+  // The one link route a connected Child serves: its own read-only link status.
+  if (linkMode && (req.method === "GET" || req.method === "HEAD") && path === "/api/link/status") return true;
   if (req.method === "POST" && (path === "/api/machine/sync" || path === "/api/machine/shim" || path === "/api/machine/disconnect")) return true;
   if (relayEnabled && path.startsWith("/api/machine/hub-relay/")) return true;
   // Known machine endpoints are admitted for every method so an unsupported
@@ -60,6 +82,10 @@ export function machineRouteAllowed(url: URL, req: Request, relayEnabled: boolea
     || /\.(?:css|gif|ico|jpe?g|js|json|map|png|svg|webp|woff2?)$/i.test(path);
 }
 
+function readSidecarSafely(read: () => ClientLinkState | null): ClientLinkSidecarRead {
+  try { return read(); } catch { return "invalid"; }
+}
+
 export function startMachineListener(
   port?: number,
   deps: MachineListenerDeps = {},
@@ -84,17 +110,33 @@ export function startMachineListener(
     setHubReachability: deps.machineApi?.setHubReachability ?? (value => { hubReachability = value; }),
   };
   const relayEnabled = !linkMode && connection.managementTransport === "relay";
+  // Link mode only. Everything is resolved once here, so a relayed request reads no file and
+  // builds no policy: the key is cached, the loopback policy is fixed at bind like the listener.
+  const inboundBodyLimit = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
+  const linkIngress: LinkIngress | null = linkMode
+    ? {
+      tunnelPort: connection.link!.tunnelPort,
+      policy: requestPolicyView(config, "127.0.0.1"),
+      linkKey: deps.linkKeySource ?? createLinkKeySource(connection.tokenFingerprint, deps.linkKey),
+      relay: { fetchImpl: deps.fetchImpl, bodyLimitBytes: inboundBodyLimit, tunnel: deps.linkTunnel, ...deps.linkRelay },
+    }
+    : null;
+  const readSidecar = deps.readSidecar ?? (() => readClientLinkState());
 
-  return Bun.serve({
+  return (deps.serve ?? (options => Bun.serve(options)))({
     port: port ?? config.port ?? 10100,
     hostname: "127.0.0.1",
-    maxRequestBodySize: HUB_RELAY_REQUEST_BODY_MAX_BYTES,
-    async fetch(req, server) {
+    // A hub client relays only bounded management calls. A link Child carries the Codex data
+    // plane, so it admits what a standalone listener admits and keeps its idle limit.
+    maxRequestBodySize: linkMode ? inboundBodyLimit : HUB_RELAY_REQUEST_BODY_MAX_BYTES,
+    ...(linkMode ? { idleTimeout: LINK_LISTENER_IDLE_TIMEOUT_SECONDS } : {}),
+    async fetch(req: Request, server: Server<unknown>) {
       const url = new URL(req.url);
-      if (!machineRouteAllowed(url, req, relayEnabled, linkMode)) return json404(req);
-      if (linkMode && linkRouteAllowed(url, req)) {
-        return relayLinkDataRequest(req, { tunnelPort: connection.link!.tunnelPort }, { fetchImpl: deps.fetchImpl });
+      if (linkIngress) {
+        const handled = handleLinkIngress(req, url, linkIngress, server);
+        if (handled) return handled;
       }
+      if (!machineRouteAllowed(url, req, relayEnabled, linkMode)) return json404(req);
       if (url.pathname === "/healthz" && req.method === "GET") {
         return Response.json({ service: "opencodex", version: VERSION, role: "client", uptime: process.uptime(), pid: process.pid, port: server.port });
       }
@@ -116,7 +158,7 @@ export function startMachineListener(
         else hubReachability = "online";
         return response;
       }
-      if (url.pathname.startsWith("/api/machine/")) {
+      if (url.pathname.startsWith("/api/machine/") || (linkMode && url.pathname === "/api/link/status")) {
         const authError = requireManagementAuth(req, managementAuth, config);
         if (authError) return authError;
         if (managementPrincipal(req, managementAuth, config) !== "gui-session") {
@@ -130,6 +172,11 @@ export function startMachineListener(
         if (req.method !== "GET" && req.method !== "HEAD") {
           return Response.json({ error: "opencodex machine changes require the local CLI" }, { status: 403 });
         }
+        if (url.pathname === "/api/link/status") {
+          // A Child never joins again from here, so the dashboard reads `joinAvailable: false`.
+          const status = projectClientLinkChild(readSidecarSafely(readSidecar), deps.linkStatus?.() ?? { kind: "stopped" }, Date.now());
+          return Response.json({ ...status, joinAvailable: false }, { headers: { "Cache-Control": "no-store" } });
+        }
         return await handleMachineApi(req, url, connection, machineApiDeps) ?? json404(req);
       }
 
@@ -158,5 +205,5 @@ export function startMachineListener(
       }
       return json404(req);
     },
-  });
+  } as Parameters<typeof Bun.serve>[0]);
 }

package/src/client/runtime.ts

@@ -1,15 +1,26 @@
-import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import type { Server } from "bun";
+import { siblingRuntimeField, withSiblingMarker } from "../codex/sibling-start";
+import { issueSiblingHandoff } from "../codex/sibling-handoff";
 import { loadConfig } from "../config";
-import { removePid, removeRuntimePort, writePid, writeRuntimePort } from "../config/process-state";
+import { removePid, removeRuntimePort, writePid, writeRuntimePort, type RuntimePortState } from "../config/process-state";
 import { installCrashGuards } from "../lib/crash-guard";
-import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { createLocalAttestationSecret } from "../lib/local-management-attestation";
 import { loadServiceTokenFromFile, serviceApiTokenFingerprint } from "../lib/service-secrets";
-import { findAvailablePort, PortUnavailableError } from "../server/ports";
+import {
+  DESKTOP_RESTART_EXIT_CODE,
+  DESKTOP_SUPERVISED_ENV,
+  DESKTOP_SUPERVISED_PORT_WAIT_MS,
+  isDesktopSupervised,
+} from "../lib/system-restart-contract";
+import { findAvailablePort, isAddrInUse, PortUnavailableError, waitForPortAvailable } from "../server/ports";
+import type { ReplacementStartRequest } from "../server/restart-replacement";
+import type { OcxClientConnectionConfig } from "../types";
+import { createLinkKeySource } from "./link-ingress";
+import { HOME_INITIATED_LINK_TUNNEL } from "./link-relay";
 import { createClientLinkSupervisor, type ClientLinkSupervisor } from "./link-tunnel";
-import { clientLinkStatePath } from "./link-state";
-import { startMachineListener } from "./machine-listener";
+import { clientLinkStatePath, isChildInitiatedLink, recordChildInitiatedLink } from "./link-state";
+import { startMachineListener, type MachineListenerDeps } from "./machine-listener";
 import { isLinkConnection, readClientConnectionState } from "./state";
 
 let activeServer: Server<unknown> | null = null;
@@ -17,16 +28,64 @@ let activePort: number | null = null;
 let activeSupervisor: ClientLinkSupervisor | null = null;
 let recycleScheduled = false;
 
+/**
+ * How long link mode waits for its configured port: the budget a hard-pinned `ocx start --port`
+ * gives `reclaimListenPort` (`src/cli/index.ts`).
+ */
+export const LINK_PORT_WAIT_MS = 60_000;
+
+/** How long a pinned port is re-probed after the reclaim wait before the start gives up on it. */
+export const PINNED_PREFER_RETRY_MS = 5_000;
+
+/**
+ * Link mode's port-reclaim budget. Under the desktop app the whole wait (this plus
+ * {@link PINNED_PREFER_RETRY_MS}) ends inside the app's 30-second startup deadline, so the app sees
+ * this start either serve or exit instead of giving up on it first.
+ */
+export function linkPortWaitMs(desktopSupervised: boolean = isDesktopSupervised()): number {
+  return desktopSupervised ? DESKTOP_SUPERVISED_PORT_WAIT_MS : LINK_PORT_WAIT_MS;
+}
+/** Bind attempts when the port is taken between the free-port probe and `Bun.serve`. */
+const LINK_BIND_ATTEMPTS = 3;
+
+export interface ClientRuntimeIo {
+  /** Link-mode port budget; defaults to {@link LINK_PORT_WAIT_MS}. */
+  portWaitMs?: number;
+  startListener?: typeof startMachineListener;
+}
+
+export interface StandaloneRecycleIo {
+  spawnReplacement?: (request: ReplacementStartRequest) => Promise<void>;
+  exitProcess?: (code: number) => void;
+  configuredPort?: () => number | undefined;
+  isDesktopSupervised?: () => boolean;
+}
+
 function cleanup(): void {
   removePid(process.pid);
   removeRuntimePort(process.pid);
 }
 
+/**
+ * What this runtime publishes in `runtime-port.json`. The attestation secret is what the desktop app
+ * reads to authenticate the runtime it started (`desktop/src-tauri/src/auth.rs`); a record without one
+ * reads as unusable there, the same as a standalone start's record would.
+ */
+export function clientRuntimeRecord(
+  pid: number,
+  port: number,
+  attestationSecret: string = createLocalAttestationSecret(),
+): RuntimePortState {
+  return { pid, port, hostname: "127.0.0.1", attestationSecret, ...siblingRuntimeField() };
+}
+
 export function standaloneRecycleEnv(
   env: NodeJS.ProcessEnv,
   disconnectedTokenFingerprint: string,
 ): NodeJS.ProcessEnv {
   const childEnv = { ...env };
+  // A detached replacement is not the desktop app's child.
+  delete childEnv[DESKTOP_SUPERVISED_ENV];
   const admissionToken = childEnv.OPENCODEX_API_AUTH_TOKEN?.trim();
   if (admissionToken && serviceApiTokenFingerprint(admissionToken) !== disconnectedTokenFingerprint) {
     // A surviving env token shadows OCX_API_TOKEN_FILE entirely, so nothing below can
@@ -54,8 +113,31 @@ export function scheduleStandaloneRecycle(disconnectedTokenFingerprint: string):
   if (typeof timer === "object" && "unref" in timer) timer.unref();
 }
 
-async function recycleStandalone(disconnectedTokenFingerprint: string): Promise<void> {
-  const port = activePort;
+function configuredTcpPort(): number | undefined {
+  try {
+    const port = loadConfig().port;
+    return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function errorCode(error: unknown): string {
+  const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+  return typeof code === "string" && /^[A-Za-z0-9_]{1,64}$/.test(code) ? code : "failed";
+}
+
+export async function recycleStandalone(
+  disconnectedTokenFingerprint: string,
+  io: StandaloneRecycleIo = {},
+): Promise<void> {
+  // The configured port when the listener never recorded one: the recycle still owes a proxy.
+  const port = activePort ?? (io.configuredPort ?? configuredTcpPort)();
+  const exit = io.exitProcess ?? ((code: number) => { process.exit(code); });
+  // Capture the one-use sibling handoff before this process removes its runtime record.
+  const replacementEnv = port && process.env.OCX_SERVICE !== "1"
+    ? withSiblingMarker(standaloneRecycleEnv(process.env, disconnectedTokenFingerprint), issueSiblingHandoff)
+    : null;
   try {
     await activeSupervisor?.stop();
   } catch (error) {
@@ -69,8 +151,14 @@ async function recycleStandalone(disconnectedTokenFingerprint: string): Promise<
   }
   cleanup();
   // Recycling back to standalone after `ocx disconnect` must actually bring a standalone
-  // proxy back, under either launch shape.
+  // proxy back, under every launch shape.
   //
+  // Under the desktop app that spawned us: exit 75 and let the app start the standalone
+  // runtime, so it keeps owning it (tray Stop, Quit) instead of losing it to a detached child.
+  if ((io.isDesktopSupervised ?? isDesktopSupervised)()) {
+    exit(DESKTOP_RESTART_EXIT_CODE);
+    return;
+  }
   // Unsupervised: spawn the replacement ourselves and exit 0.
   //
   // Supervised (`OCX_SERVICE=1`): do NOT spawn — the supervisor owns the process, and a
@@ -83,22 +171,103 @@ async function recycleStandalone(disconnectedTokenFingerprint: string): Promise<
   //
   // launchd's KeepAlive restarts on any exit, so it is correct under both branches.
   if (process.env.OCX_SERVICE === "1") {
-    process.exit(1);
+    exit(1);
+    return;
+  }
+  if (port === undefined) {
+    console.warn("[client] no valid port to restart the standalone proxy on; run 'ocx start'");
+    exit(1);
+    return;
   }
-  if (port) {
-    const child = spawn(process.execPath, selfLaunchArgv(["start", "--port", String(port)]), {
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
-      env: standaloneRecycleEnv(process.env, disconnectedTokenFingerprint),
+  if (!replacementEnv) throw new Error("Standalone recycle has no replacement environment.");
+  // Wait until the replacement answers (it retries an early exit) instead of exiting the moment
+  // it spawned: a replacement that died unseen left no proxy and nothing to report it.
+  try {
+    const spawnReplacement = io.spawnReplacement
+      ?? (async (request: ReplacementStartRequest) => (await import("../server/restart-replacement")).spawnReplacementStart(request));
+    await spawnReplacement({
+      port,
+      waitForHealth: true,
+      // A sibling's replacement stays a sibling even if the owner is down while it probes.
+      env: replacementEnv,
     });
-    child.unref();
+  } catch (error) {
+    console.warn(`[client] the standalone replacement did not start (${errorCode(error)}); run 'ocx start'`);
+    exit(1);
+    return;
+  }
+  exit(0);
+}
+
+/**
+ * Bind the client listener. Link mode is pinned to the configured port because Codex routes to it:
+ * like a hard-pinned `ocx start --port`, it waits for a port that a restarting parent is still
+ * releasing, never kills the holder and never hops. The waits run only while the port is busy; a
+ * free port binds on the first probe.
+ */
+export async function bindClientListener(
+  request: {
+    state: OcxClientConnectionConfig;
+    linkMode: boolean;
+    preferred: number;
+    explicitPort: boolean;
+    configuredPort: number;
+  } & Pick<MachineListenerDeps, "linkStatus" | "linkKeySource" | "linkTunnel">,
+  io: ClientRuntimeIo = {},
+): Promise<{ server: Server<unknown>; port: number }> {
+  const { linkMode } = request;
+  const portWaitMs = io.portWaitMs ?? (linkMode ? linkPortWaitMs() : LINK_PORT_WAIT_MS);
+  const deadline = Date.now() + portWaitMs;
+  const busy = (cause: unknown) => new Error(
+    `link mode needs port ${request.configuredPort}; free it or change port`,
+    { cause },
+  );
+  let port: number;
+  try {
+    if (linkMode) {
+      const { reclaimListenPort } = await import("../server/port-reclaim");
+      await reclaimListenPort(request.configuredPort, "127.0.0.1", {
+        timeoutMs: portWaitMs,
+        intervalMs: 100,
+        scanIntervalMs: 500,
+        killOcxHolders: false,
+        dropTcpRows: true,
+      });
+    }
+    port = await findAvailablePort(request.preferred, "127.0.0.1", {
+      preferRetryMs: request.explicitPort ? PINNED_PREFER_RETRY_MS : 750,
+      preferRetryIntervalMs: 50,
+      allowEphemeralFallback: linkMode ? false : !request.explicitPort,
+    });
+  } catch (error) {
+    if (linkMode && error instanceof PortUnavailableError) throw busy(error);
+    throw error;
+  }
+  const startListener = io.startListener ?? startMachineListener;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      const server = startListener(port, {
+        state: request.state,
+        ...(request.linkStatus ? { linkStatus: request.linkStatus } : {}),
+        ...(request.linkKeySource ? { linkKeySource: request.linkKeySource } : {}),
+        ...(request.linkTunnel ? { linkTunnel: request.linkTunnel } : {}),
+      });
+      return { server, port: server.port ?? port };
+    } catch (error) {
+      // Check-then-bind: the port can be taken between the probe and Bun.serve.
+      if (!linkMode || !isAddrInUse(error)) throw error;
+      const waitMs = Math.max(1_000, deadline - Date.now());
+      if (attempt >= LINK_BIND_ATTEMPTS
+        || !(await waitForPortAvailable(port, "127.0.0.1", { timeoutMs: waitMs, intervalMs: 100 }))) {
+        throw busy(error);
+      }
+    }
   }
-  process.exit(0);
 }
 
 export async function startClientRuntime(
   options: { port?: number; block?: boolean } = {},
+  io: ClientRuntimeIo = {},
 ): Promise<void> {
   const state = readClientConnectionState();
   if (state.kind !== "connected") throw new Error(`client runtime refused: client state is ${state.kind}`);
@@ -108,33 +277,39 @@ export async function startClientRuntime(
     throw new Error("link mode requires a valid local config port");
   }
   const preferred = linkMode ? config.port : options.port ?? config.port ?? 10100;
-  let port: number;
-  try {
-    port = await findAvailablePort(preferred, "127.0.0.1", {
-      preferRetryMs: options.port === undefined ? 750 : 5_000,
-      preferRetryIntervalMs: 50,
-      allowEphemeralFallback: linkMode ? false : options.port === undefined,
-    });
-  } catch (error) {
-    if (linkMode && error instanceof PortUnavailableError) {
-      throw new Error(`link mode needs port ${config.port}; free it or change port`, { cause: error });
-    }
-    throw error;
+  // Share one cached key source between the listener and its tunnel supervisor.
+  const linkKey = linkMode ? createLinkKeySource(state.value.tokenFingerprint) : undefined;
+  // Joins made before the marker existed get one now, while their sidecar is still here.
+  if (linkMode && state.value.link) {
+    try { recordChildInitiatedLink(state.value.link.linkId); } catch { /* the sidecar check below still applies */ }
   }
-  const server = startMachineListener(port, { state: state.value });
-  const boundPort = server.port ?? port;
-  activeServer = server;
-  activePort = boundPort;
   const supervisor = linkMode && existsSync(clientLinkStatePath())
     ? createClientLinkSupervisor({
       onLinkEnded: () => scheduleStandaloneRecycle(state.value.tokenFingerprint),
+      linkKey,
     })
     : null;
+  // A Child with no sidecar and no record of joining itself was connected by its Home over
+  // `ssh -R`; that link keeps 2.67.0's unproven forward. A Child-initiated link that lost its
+  // sidecar gets no gate at all, so the relay refuses it.
+  const homeInitiated = linkMode && !supervisor && !!state.value.link
+    && !isChildInitiatedLink(state.value.link.linkId);
+  const { server, port: boundPort } = await bindClientListener({
+    state: state.value,
+    linkMode,
+    preferred,
+    explicitPort: options.port !== undefined,
+    configuredPort: config.port,
+    ...(linkMode ? { linkStatus: () => supervisor?.status() ?? { kind: "stopped" as const }, linkKeySource: linkKey } : {}),
+    ...(supervisor ? { linkTunnel: supervisor } : homeInitiated ? { linkTunnel: HOME_INITIATED_LINK_TUNNEL } : {}),
+  }, io);
+  activeServer = server;
+  activePort = boundPort;
   activeSupervisor = supervisor;
   supervisor?.start();
   installCrashGuards();
   writePid(process.pid);
-  writeRuntimePort({ pid: process.pid, port: boundPort, hostname: "127.0.0.1" });
+  writeRuntimePort(clientRuntimeRecord(process.pid, boundPort));
 
   let shuttingDown = false;
   const shutdown = () => {

package/src/clients/config-export/constants.ts

@@ -45,18 +45,7 @@ export const GAJAE_API_KEY_ENV = "OPENCODEX_GAJAE_API_KEY";
 /** Pi's wire-dialect selector for an OpenAI-compatible endpoint. */
 export const PI_API_DIALECT = "openai-completions";
 
-/**
- * opencode's config schema rejects a `limit` block that carries `context` without
- * `output`, but CatalogModel has no authoritative per-model output field. Dropping
- * `limit` entirely would also throw away the authoritative context window we DO have,
- * so the block is emitted with this budget standing in for the missing half.
- *
- * The value matches REASONING_MAX_TOKENS_CEILING in src/adapters/anthropic.ts — the
- * project's existing "safe ceiling across current models" figure. It is a ceiling for
- * schema validity, NOT a claim about any specific model's true maximum, and it is
- * clamped to the context window so a small-context model can never be emitted with
- * output > context. Pi's `maxTokens` uses the same stand-in and the same clamp.
- */
+/** Fallback only when the model has no known output limit; always clamped to context. */
 export const SCHEMA_REQUIRED_OUTPUT_BUDGET = 32_000;
 
 /** Deterministic loopback default for exported provider-block helpers in tests. */

package/src/clients/config-export/contracts.ts

@@ -37,6 +37,7 @@ export interface OpencodeCatalogModel {
   provider?: string;
   id?: string;
   contextWindow?: number;
+  maxTokens?: number;
   displayName?: string;
   /**
    * Declared input modalities, carried verbatim from `/api/models`. Serialized as opencode's
@@ -71,6 +72,7 @@ export interface ExportModel {
   native?: boolean;
   displayName?: string;
   contextWindow?: number;
+  maxTokens?: number;
   inputModalities?: string[];
   /** Optional effort ladder exported only to clients that support it. */
   reasoningEfforts?: string[];

package/src/clients/config-export/model-metadata.ts

@@ -1,4 +1,5 @@
 // Shared client export model metadata.
+import { getModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { SCHEMA_REQUIRED_OUTPUT_BUDGET } from "./constants";
 import { expandFastExportModels } from "./fast-models";
 import type { OpencodeCatalogModel, ExportModel, ExportClientId, ManagedContribution } from "./contracts";
@@ -18,9 +19,14 @@ export function authoritativeContextWindow(contextWindow: number | undefined): n
   return undefined;
 }
 
-/** Schema-required output budget for a known context window. */
-export function outputBudgetFor(context: number): number {
-  return Math.min(SCHEMA_REQUIRED_OUTPUT_BUDGET, context);
+/** Known model output limit, with a schema-required fallback, clamped to context. */
+export function outputBudgetFor(context: number, model: OpencodeCatalogModel): number {
+  const provider = model.provider ?? "";
+  const metadata = getModelMetadata(resolveMetadataProvider(provider) ?? provider, model.id ?? model.namespaced);
+  const limit = authoritativeContextWindow(model.maxTokens)
+    ?? authoritativeContextWindow(metadata?.maxTokens)
+    ?? SCHEMA_REQUIRED_OUTPUT_BUDGET;
+  return Math.min(limit, context);
 }
 
 /**

package/src/clients/config-export/omp.ts

@@ -67,7 +67,7 @@ export function buildOmpClientConfig(ctx: ExportContext): OmpGeneratedConfig {
     const context = authoritativeContextWindow(model.contextWindow);
     if (context !== undefined) {
       entry.contextWindow = context;
-      entry.maxTokens = outputBudgetFor(context);
+      entry.maxTokens = outputBudgetFor(context, model);
     }
     const efforts = ompEfforts(model);
     if (efforts.length > 0) {

package/src/clients/config-export/zcode-store.ts

@@ -42,7 +42,7 @@ export interface ZcodeStoreProviderRule {
   providerName: string;
   config: {
     group: string;
-    access: { apiKey: string };
+    access: { type: "api-key"; apiKey: string };
     api: { type: string; baseUrl: string };
     personalModelIds: string[];
     modelOrder: string[];
@@ -113,7 +113,7 @@ export function buildZcodeStoreProviderRule(ctx: ExportContext): ZcodeStoreProvi
     providerName: ZCODE_STORE_PROVIDER_NAME,
     config: {
       group: ZCODE_STORE_PROVIDER_GROUP,
-      access: { apiKey: LOOPBACK_API_KEY_PLACEHOLDER },
+      access: { type: "api-key", apiKey: LOOPBACK_API_KEY_PLACEHOLDER },
       api: { type: ZCODE_STORE_API_TYPE, baseUrl: `${ctx.baseUrl.replace(/\/v1\/?$/, "")}/v1` },
       personalModelIds: ids,
       /*

package/src/clients/config-export.ts

@@ -722,7 +722,7 @@ export function opencodeProviderBlocks(
     const entry: OpencodeModelEntry = { name: exportModelLabel(model) };
     const context = authoritativeContextWindow(model.contextWindow);
     if (context !== undefined) {
-      entry.limit = { context, output: outputBudgetFor(context) };
+      entry.limit = { context, output: outputBudgetFor(context, model) };
     }
     // `attachment` / `modalities` are fields of opencode's V1 model schema — the shape its
     // published config.json defines and the one its loader reads (verified against opencode
@@ -934,6 +934,17 @@ export interface GajaeModelEntry {
   input: string[];
   contextWindow?: number;
   maxTokens?: number;
+  /** Advertised only when the catalog declares at least one wire-selectable effort. */
+  reasoning?: true;
+  /** GJC's per-model reasoning-effort capability declaration. */
+  thinking?: {
+    mode: "effort";
+    minLevel: string;
+    maxLevel: string;
+    levels: string[];
+  };
+  /** Tells GJC to pass the selected level as OpenAI-compatible reasoning_effort. */
+  compat?: { supportsReasoningEffort: true };
 }
 
 /** Gajae validates strictly: an unknown field fails the whole config. */
@@ -1004,7 +1015,7 @@ function buildPiClientConfig(ctx: ExportContext, options: PiExportOptions = {}):
     const context = authoritativeContextWindow(model.contextWindow);
     if (context !== undefined) {
       entry.contextWindow = context;
-      entry.maxTokens = outputBudgetFor(context);
+      entry.maxTokens = outputBudgetFor(context, model);
     }
     models.push(entry);
   }
@@ -1140,7 +1151,29 @@ function buildGajaeClientConfig(ctx: ExportContext): GajaeGeneratedConfig {
     const context = authoritativeContextWindow(model.contextWindow);
     if (context !== undefined) {
       entry.contextWindow = context;
-      entry.maxTokens = outputBudgetFor(context);
+      entry.maxTokens = outputBudgetFor(context, model);
+    }
+    // GJC accepts the OpenAI-compatible effort ladder in model metadata. `none` means
+    // no parameter and `ultra` is an OCX orchestration level that folds to `max` on the
+    // wire, so neither can be offered as a GJC model-level effort.
+    const declaredEfforts = model.reasoningEfforts
+      // Native Codex rows do not repeat their built-in ladder in the catalog. They still
+      // accept the standard effort field, so omitting this fallback hides GJC's thinking
+      // control for the models most likely to need it.
+      ?? (model.native && model.provider === "openai"
+        ? ["low", "medium", "high", "xhigh", "max"]
+        : []);
+    const efforts = canonicalizeReasoningEfforts(declaredEfforts)
+      .filter(effort => effort !== "none" && effort !== "ultra");
+    if (efforts.length > 0) {
+      entry.reasoning = true;
+      entry.thinking = {
+        mode: "effort",
+        minLevel: efforts[0]!,
+        maxLevel: efforts.at(-1)!,
+        levels: efforts,
+      };
+      entry.compat = { supportsReasoningEffort: true };
     }
     models.push(entry);
   }