@bitkyc08/opencodex 2.89.0 → 2.91.0

package/src/server/gui-session.ts

@@ -1,6 +1,7 @@
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import type { OcxConfig } from "../types";
 import { canonicalGuiBrowserOrigin, standaloneGuiPairingOrigin } from "../lib/gui-pair-capability";
+import { authorizationCredential } from "../lib/authorization-scheme";
 import {
   isAllowedManagementOrigin,
   isApiAuthRequired,
@@ -409,7 +410,7 @@ function isPairingTransportPermitted(origin: string): boolean {
 
 function requestCredential(req: Request): string | null {
   return req.headers.get("x-opencodex-api-key")?.trim()
-    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim()
+    || authorizationCredential(req.headers)
     || null;
 }
 

package/src/server/index/link-listener.ts

@@ -1,4 +1,5 @@
 import { createLinkRelaySessions } from "./link-relay-sessions";
+import { createLinkPeerObservations, type LinkPeerEntry } from "../../link/peer-report";
 import type { Server } from "bun";
 import {
   emptyLinkStore,
@@ -9,6 +10,7 @@ import {
 import { linkStorePath } from "../../link/paths";
 import { linkRouteAllowed } from "../../link/routes";
 import { withConfigMutationLockSync } from "../../config/mutation-lock";
+import { registerFallbackLinkResolver } from "../../routing/fallback-policy";
 
 export const LINK_INGRESS_HOSTNAME = "opencodex-link.invalid";
 
@@ -51,6 +53,8 @@ export interface LinkListenerLifecycle<T> {
   linkAdmissionKeyIds(): ReadonlySet<string>;
   onAuthenticatedCatalog(listener: (apiKeyId: string) => void): () => void;
   notifyAuthenticatedCatalog(apiKeyId: string): void;
+  /** What this Home last learned of a Child over the link; empty until it relays a request. */
+  peerObservation(linkId: string): LinkPeerEntry;
   status(): LinkListenerStatus;
   close(): Promise<void>;
   stop(): Promise<void>;
@@ -76,6 +80,7 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
   let stopped = false;
   const authenticatedCatalogListeners = new Set<(apiKeyId: string) => void>();
   let lifecycleStatus: LinkListenerStatus = { state: "off", port: null, reason: null };
+  const peers = createLinkPeerObservations();
 
   const setStatus = (state: LinkListenerStatus["state"], port: number | null, reason: string | null): void => {
     lifecycleStatus = { state, port, reason };
@@ -89,6 +94,9 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
   const readStoreForAdmission = (): LinkStore => {
     try { return readStore(storePath); } catch { return emptyLinkStore(); }
   };
+  // OCX-11: the fallback policy resolves a link data key to its link id through this slot.
+  const releaseFallbackLinkResolver = registerFallbackLinkResolver(keyId =>
+    readStoreForAdmission().links.find(link => link.apiKeyId === keyId)?.id);
 
   const bindIfNeeded = (): void => {
     if (stopped || listener || !startContext) return;
@@ -104,7 +112,7 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
       return;
     }
     const requestedPort = store.listenerPort ?? 0;
-    const sessions = createLinkRelaySessions({ fingerprints: (keyId, linkId) => {
+    const sessions = createLinkRelaySessions({ peers, fingerprints: (keyId, linkId) => {
       if (!readStoreForAdmission().links.some(link => link.id === linkId && link.apiKeyId === keyId)) return [];
       return startContext?.keyFingerprints?.(keyId) ?? [];
     } });
@@ -214,12 +222,14 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
     notifyAuthenticatedCatalog(apiKeyId) {
       for (const listener of authenticatedCatalogListeners) listener(apiKeyId);
     },
+    peerObservation: linkId => peers.get(linkId),
     status() {
       return { ...lifecycleStatus };
     },
     close,
     async stop() {
       stopped = true;
+      releaseFallbackLinkResolver();
       // Process shutdown is deliberately forceful, unlike last-link removal. Every
       // authenticated socket is closed, and the client transport cannot reconnect it.
       relaySessions?.abortReservations();

package/src/server/index/link-management.ts

@@ -14,22 +14,69 @@ import type { ManagementSessionControl } from "../management-auth";
 import { runPassiveRead } from "../../lib/passive-read";
 import { LINK_CODEX_SETTINGS_PATH, linkManagementRouteAllowed, linkManagementTarget } from "../../link/management-routes";
 import { projectHomeCodexSettings } from "../../link/codex-settings";
+import { homeLinkChildParity, LINK_CHILD_PARITY_MAX_BYTES, LINK_CHILD_PARITY_PATH, parseLinkChildParityReport } from "../../link/child-parity";
+import { linkStorePath } from "../../link/paths";
+import { readLinkStore } from "../../link/store";
+import { readBoundedResponseBytes } from "../../lib/bounded-body";
 import { packageVersion } from "../../lib/package-version";
 
 const VERSION = packageVersion("0.0.0");
 const KEPT_RESPONSE_HEADERS = ["content-type", "content-language", "etag", "last-modified"];
+const REPORT_READ_TIMEOUT_MS = 5_000;
 
 function notFound(): Response {
   return Response.json({ error: "not_found" }, { status: 404, headers: { "cache-control": "no-store" } });
 }
 
+function refused(status: number, code: string): Response {
+  return Response.json({ error: code }, { status, headers: { "cache-control": "no-store" } });
+}
+
+/**
+ * `POST` {@link LINK_CHILD_PARITY_PATH}: the Child's apply report (OCX-6). The one write the link
+ * accepts, handled here, before and apart from the read-only table, so it never widens what a
+ * read may do. It is admitted only for the link the admitting key belongs to, reads at most
+ * {@link LINK_CHILD_PARITY_MAX_BYTES} and changes nothing but the in-memory report.
+ */
+async function handleChildParityReport(req: Request, url: URL, admittedKeyId: string | undefined): Promise<Response> {
+  if (req.method !== "POST" || url.search !== "" || req.headers.has("upgrade")) return notFound();
+  if (!admittedKeyId) return refused(403, "link_key_required");
+  const declared = Number(req.headers.get("content-length") ?? "0");
+  if (Number.isFinite(declared) && declared > LINK_CHILD_PARITY_MAX_BYTES) return refused(413, "report_too_large");
+  let bytes: Uint8Array;
+  try {
+    const read = await readBoundedResponseBytes(new Response(req.body), {
+      maxBytes: LINK_CHILD_PARITY_MAX_BYTES,
+      signal: AbortSignal.timeout(REPORT_READ_TIMEOUT_MS),
+    });
+    if (read.oversized) return refused(413, "report_too_large");
+    bytes = read.bytes;
+  } catch {
+    return refused(400, "invalid_report");
+  }
+  let report: ReturnType<typeof parseLinkChildParityReport>;
+  try {
+    report = parseLinkChildParityReport(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+  } catch {
+    report = null;
+  }
+  if (!report) return refused(400, "invalid_report");
+  let links: ReturnType<typeof readLinkStore>["links"];
+  try { links = readLinkStore(linkStorePath()).links; } catch { return refused(503, "link_store_unavailable"); }
+  if (!links.some(link => link.id === report.linkId && link.apiKeyId === admittedKeyId)) return refused(403, "link_mismatch");
+  homeLinkChildParity.record(report, new Set(links.map(link => link.id)));
+  return new Response(null, { status: 204, headers: { "cache-control": "no-store" } });
+}
+
 export async function handleLinkManagementRequest(
   req: Request,
   url: URL,
   config: OcxConfig,
   deps: ManagementApiDeps,
   sessionControl?: ManagementSessionControl,
+  admittedKeyId?: string,
 ): Promise<Response> {
+  if (url.pathname === LINK_CHILD_PARITY_PATH) return handleChildParityReport(req, url, admittedKeyId);
   if (!linkManagementRouteAllowed(url, req)) return notFound();
   if (url.pathname === LINK_CODEX_SETTINGS_PATH) {
     return Response.json(projectHomeCodexSettings(config, VERSION), { headers: { "cache-control": "no-store" } });

package/src/server/index/link-relay-sessions.ts

@@ -3,6 +3,7 @@ import {
   LINK_RELAY_AUTH_PATH, LINK_RELAY_AUTH_TIMEOUT_MS, LINK_RELAY_AUTH_VERSION,
   LINK_RELAY_SESSION_HEADER, linkRelayProof, linkRelayProofMatches,
 } from "../../link/relay-auth";
+import { parseLinkPeerReport, type LinkPeerObservations } from "../../link/peer-report";
 
 interface Session {
   peer: string;
@@ -18,6 +19,8 @@ export interface LinkRelaySessionOptions {
   fingerprints: (keyId: string, linkId: string) => readonly string[];
   /** Tests can use a bounded shorter reservation; production uses five seconds. */
   reservationMs?: number;
+  /** Where a verified challenge records the Child's report, and a known link's version mismatch. */
+  peers?: LinkPeerObservations;
 }
 
 /** One book per bound listener. A pending proof reserves the bind before the data request arrives. */
@@ -64,14 +67,20 @@ export function createLinkRelaySessions(options: LinkRelaySessionOptions) {
         if (closing || req.method !== "GET" || sessions.size >= 256 || req.headers.has("upgrade")
           || req.headers.has("authorization") || req.headers.has("x-opencodex-api-key")) return refuse();
         const q = url.searchParams;
-        if (q.get("version") !== LINK_RELAY_AUTH_VERSION || [...q.keys()].length !== 5
-          || ["version", "key", "link", "nonce", "proof"].some(name => q.getAll(name).length !== 1)) return refuse();
+        if ([...q.keys()].length !== 5 || ["version", "key", "link", "nonce", "proof"].some(name => q.getAll(name).length !== 1)) return refuse();
         const keyId = q.get("key")!, linkId = q.get("link")!, nonce = q.get("nonce")!;
+        if (q.get("version") !== LINK_RELAY_AUTH_VERSION) {
+          // Unverifiable, but only for a link and key this Home issued: status names the mismatch.
+          const version = q.get("version")!;
+          if (/^[1-9]\d{0,3}$/.test(version) && options.fingerprints(keyId, linkId).length > 0) options.peers?.refuse(linkId, version);
+          return refuse();
+        }
         const peer = peerOf(req, server as Server<unknown>);
         if (!peer || sessions.has(nonce)) return refuse();
         const fingerprint = options.fingerprints(keyId, linkId).find(candidate =>
           linkRelayProofMatches(q.get("proof"), linkRelayProof(candidate, "caller", keyId, linkId, nonce)));
         if (!fingerprint) return refuse();
+        options.peers?.observe(linkId, LINK_RELAY_AUTH_VERSION, parseLinkPeerReport(req.headers));
         const release = acquire();
         const timer = setTimeout(() => { consume(nonce)?.release(); }, reservationMs);
         sessions.set(nonce, { peer, keyId, linkId, fingerprint, release, timer, expiresAt: Date.now() + reservationMs });

package/src/server/index/optional-listeners.ts

@@ -15,6 +15,7 @@ import {
 } from "./link-listener";
 import { createLinkSupervisor, type LinkSupervisor } from "../../link/supervisor";
 import { linkManagementRouteAllowed } from "../../link/management-routes";
+import { linkChildParityRouteAllowed } from "../../link/child-parity";
 import { saveConfigPreservingClaudeCode } from "../../config/live-reconcile";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
 import { startJevQuotaActivation } from "../../combos/jev-quota-activation";
@@ -38,6 +39,7 @@ export interface OptionalListenerSet<T> {
   linkAdmissionKeyIds(): ReadonlySet<string>;
   onAuthenticatedCatalog(listener: (apiKeyId: string) => void): () => void;
   notifyAuthenticatedCatalog(apiKeyId: string): void;
+  peerObservation(linkId: string): import("../../link/peer-report").LinkPeerEntry;
   status(): LinkListenerStatus;
   linkStatus(): LinkListenerStatus;
   linkSupervisor(): LinkSupervisor;
@@ -83,11 +85,14 @@ export function createOptionalListenerSet<T>(linkDeps: LinkListenerDeps = {}): O
     },
     // The Home's link listener admits the data plane plus the read-only management relay
     // (#6957). The Child's own ingress keeps the data-only table, so a local caller on the Child
-    // cannot reach the Home's management reads without the Child's dashboard session.
-    linkRouteAllowed: (url, req) => linkRouteAllowed(url, req) || linkManagementRouteAllowed(url, req),
+    // cannot reach the Home's management reads without the Child's dashboard session. The one
+    // write is the Child's apply report (OCX-6), which changes only an in-memory status field.
+    linkRouteAllowed: (url, req) => linkRouteAllowed(url, req) || linkManagementRouteAllowed(url, req)
+      || linkChildParityRouteAllowed(url, req),
     linkAdmissionKeyIds: () => linkListener.linkAdmissionKeyIds(),
     onAuthenticatedCatalog: listener => linkListener.onAuthenticatedCatalog(listener),
     notifyAuthenticatedCatalog: apiKeyId => linkListener.notifyAuthenticatedCatalog(apiKeyId),
+    peerObservation: linkId => linkListener.peerObservation(linkId),
     status: () => linkListener.status(),
     linkStatus: () => linkListener.status(),
     linkSupervisor: () => supervisor,

package/src/server/index/serve-options.ts

@@ -204,10 +204,13 @@ import type { ReadinessGate } from "../readiness";
 import type { WorkflowRefusalLog } from "../workflow-refusal";
 
 import { readyProtocolMetadata } from "../../remote/protocol";
+import { homeInstanceId, stampServedBy } from "../../remote/served-by";
 import { modelCapabilityFields } from "../models-capabilities";
 import { createWebsocketHandler } from "./websocket-handler";
+import { reasoningArchiveErrorResponse } from "../responses/reasoning-archive-error";
 import { withGrokSessionIdentity } from "../../grok/session-identity";
 import { withCallerSessionIdentity } from "../caller-session-identity";
+import { agentAssertionUnsupportedResponse, hasAgentAssertionAuthorization } from "../../lib/authorization-scheme";
 
 export type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management" | "claude-intercept" | "hub-link";
 
@@ -369,6 +372,10 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         : ingress === "unauthenticated-loopback" || ingress === "claude-intercept"
           ? loopbackPolicy()
           : config;
+      // Codex runtime agent assertion_only (Authorization: AgentAssertion) is refused before
+      // admission or routing: it is never a bearer, never an admission secret, and no pool or
+      // routed credential may stand in for it.
+      if (hasAgentAssertionAuthorization(req.headers)) return withCors(agentAssertionUnsupportedResponse(), req, policy);
       if (ingress === "hub-link") {
         const admission = resolveApiAuth(req, policy);
         if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
@@ -379,7 +386,10 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         // the shared table in src/link/management-routes.ts; never reachable on another ingress.
         if (isLinkManagementPath(requestUrl.pathname)) {
           const { handleLinkManagementRequest } = await import("./link-management");
-          return withCors(await handleLinkManagementRequest(req, requestUrl, config, requestManagementApiDeps, managementSessionControl), req, policy);
+          return withCors(await handleLinkManagementRequest(
+            req, requestUrl, config, requestManagementApiDeps, managementSessionControl,
+            admission.kind === "configured" ? admission.keyId : undefined,
+          ), req, policy);
         }
       }
       const url = requestUrl;
@@ -407,11 +417,13 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         const message = "OpenCodex package files changed while this proxy was running; it restarts on its own, or run 'ocx restart' ('ocx service restart' for a background service).";
         const fencedPort = ctx.boundPort ?? requestServer.port ?? listenPort;
         const fencedHealth = url.pathname === "/healthz";
+        const fencedInstanceId = fencedHealth ? homeInstanceId() : undefined;
         const response = fencedHealth || readyzPath !== undefined
           ? jsonResponse({
               status: "restart_required",
               service: "opencodex",
               version: VERSION,
+              ...(fencedInstanceId ? { instanceId: fencedInstanceId } : {}),
               uptime: process.uptime(),
               pid: process.pid,
               port: fencedPort,
@@ -622,10 +634,13 @@ export function createServeOptions(ctx: ServeOptionsContext) {
       if (url.pathname === "/healthz" && req.method === "GET") {
         // service/pid/port let CLI liveness reject foreign 200s and verify pid identity.
         const healthPort = ctx.server.port ?? listenPort;
+        // Opaque Home instance id (src/remote/served-by.ts); omitted until the identity exists.
+        const instanceId = homeInstanceId();
         const response = jsonResponse({
           status: "ok",
           service: "opencodex",
           version: VERSION,
+          ...(instanceId ? { instanceId } : {}),
           uptime: process.uptime(),
           pid: process.pid,
           port: healthPort,
@@ -1347,8 +1362,9 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             response = await handleResponsesCompact(req, config, logCtx, turnAdmissionLease, admission, {
               onRequestBodyRead: () => disableResponsesRequestTimeout(req, requestServer),
             });
-          } catch {
-            response = formatErrorResponse(500, "server_error", "Unexpected compact request failure");
+          } catch (error) {
+            response = reasoningArchiveErrorResponse(error)
+              ?? formatErrorResponse(500, "server_error", "Unexpected compact request failure");
           }
           addFinalRequestLog(requestId, start, logCtx, response.status,
             response.status === 499 ? { closeReason: "client_cancel" } : undefined);
@@ -1519,6 +1535,10 @@ export function createServeOptions(ctx: ServeOptionsContext) {
               },
             });
           } catch (error) {
+            const archiveError = reasoningArchiveErrorResponse(error);
+            if (archiveError) return withRequestLogId(
+              withCors(responseWithDeferredRequestLog(archiveError, requestId, start, logCtx), req, policy), requestId,
+            );
             // A bounded upstream body can fail before handleResponses returns a client response.
             // Finalize before rethrow so accounting observes the physical send while the caller
             // retains the existing reset/rejection instead of receiving a synthesized response.
@@ -1971,5 +1991,8 @@ export function createServeOptions(ctx: ServeOptionsContext) {
     },
     websocket: createWebsocketHandler(ctx, requestMetrics),
   } as const;
-  return serveOptions;
+  const routeFetch = serveOptions.fetch;
+  // x-opencodex-served-by on GET /v1/models, whichever branch answered (src/remote/served-by.ts).
+  return { ...serveOptions, fetch: async (req: Request, requestServer: Server<WsData>): Promise<Response> =>
+    stampServedBy(req.method, codexCompatibleUrl(req.url).pathname, await routeFetch(req, requestServer)) } as const;
 }

package/src/server/index/websocket-handler.ts

@@ -2,6 +2,7 @@ import { nativeSteeringUnavailableReason, nativeResponseControlMode, type Native
 import { NativeInjectionChannel } from "../responses/native-injection";
 import { NativeSteeringChannel, NativeSteeringError } from "../responses/native-steering";
 import { createNativeSteeringLogObserver } from "../responses/native-steering-log";
+import { reasoningArchiveErrorResponse } from "../responses/reasoning-archive-error";
 import type { Server, ServerWebSocket } from "bun";
 import {
   LIVE_SIDEBAND_UPSTREAM_OPEN_TIMEOUT_MS,
@@ -396,6 +397,15 @@ export function createWebsocketHandler(
                 }));
                 return;
               }
+              // A local archive refusal happens before any send. Carry the same sanitized 503
+              // body and stable code as HTTP so no filesystem path reaches the client frame.
+              const archiveError = reasoningArchiveErrorResponse(err);
+              if (archiveError) {
+                finalizeLog(archiveError.status);
+                const body = await archiveError.json() as { error: Record<string, unknown> };
+                sendJsonFrame(ws, buildWsErrorFrame(archiveError.status, body.error));
+                return;
+              }
               finalizeLog(502);
               sendJsonFrame(ws, buildWsErrorFrame(502, {
                 type: "proxy_error",

package/src/server/lifecycle.ts

@@ -476,13 +476,25 @@ export function trackStreamLifetime(
   registerTurn(ac, lease);
   const reader = body.getReader();
   let closed = false;
+  let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+  // A drain aborts the turn's controller; many callers pass a fresh one nothing else listens to,
+  // so the tracked stream itself has to stop.
+  const onAbort = () => {
+    if (closed) return;
+    // Stop the stream before the caller's onDone runs, so a throwing callback cannot leave it open.
+    reader.cancel(ac.signal.reason).catch(() => {});
+    try { streamController?.error(ac.signal.reason); } catch { /* already closed */ }
+    finish();
+  };
   const finish = () => {
     if (closed) return;
     closed = true;
+    ac.signal.removeEventListener("abort", onAbort);
     unregisterTurn(ac);
     onDone?.();
   };
-  return new ReadableStream<Uint8Array>({
+  const tracked = new ReadableStream<Uint8Array>({
+    start(controller) { streamController = controller; },
     async pull(controller) {
       try {
         const { done, value } = await reader.read();
@@ -499,6 +511,10 @@ export function trackStreamLifetime(
       reader.cancel(reason).catch(() => {});
     },
   });
+  // After registerTurn, so the lease's own abort listener (release the turn) runs first. A
+  // controller registerTurn already aborted (a settled lease) keeps its previous behaviour.
+  ac.signal.addEventListener("abort", onAbort, { once: true });
+  return tracked;
 }
 
 export async function drainAndShutdown(

package/src/server/live.ts

@@ -88,6 +88,10 @@ export const LIVE_SIDEBAND_API_ROOT = "https://api.openai.com/v1";
  * upstream the caller was addressing, so there is nothing to scope it away from. That is not
  * true of the images sidecar, which strips it deliberately and keeps doing so.
  *
+ * `voice-session-id` is the client-generated voice session id Codex 0.164 forwards on WebSocket,
+ * WebRTC and existing-call transports (openai/codex#53784). It is a separate identity from the
+ * realtime session id carried in `x-session-id`, so neither may stand in for the other.
+ *
  * Every name here is relayed only when the caller sent it. Nothing on this list is invented,
  * which is what keeps a caller that omits one byte-identical upstream. Auth headers
  * (`authorization`, `chatgpt-account-id`) stay proxy-owned and are never taken from this list.
@@ -100,6 +104,7 @@ export const LIVE_CLIENT_PROTOCOL_HEADERS = [
   "originator",
   "x-oai-attestation",
   "x-codex-turn-metadata",
+  "voice-session-id",
 ] as const;
 
 /**

package/src/server/management/context.ts

@@ -156,7 +156,7 @@ export interface ManagementApiDeps {
   codexPromptPaths?: CodexPromptPaths;
   /** Link seams are getters so the optional listener and supervisor are singletons. */
   linkSupervisor?: () => LinkSupervisor;
-  linkListener?: () => Pick<LinkListenerLifecycle<unknown>, "ensureStarted" | "status" | "close" | "onAuthenticatedCatalog"> & Partial<Pick<import("../index/optional-listeners").OptionalListenerSet<unknown>, "ensureClaudeIntercept" | "claudeInterceptOutcome">>;
+  linkListener?: () => Pick<LinkListenerLifecycle<unknown>, "ensureStarted" | "status" | "close" | "onAuthenticatedCatalog"> & Partial<Pick<LinkListenerLifecycle<unknown>, "peerObservation">> & Partial<Pick<import("../index/optional-listeners").OptionalListenerSet<unknown>, "ensureClaudeIntercept" | "claudeInterceptOutcome">>;
   readLinkStore?: () => LinkStore;
   writeLinkStore?: (store: LinkStore) => void;
   linkKnownHostsPath?: () => string;

package/src/server/management/fallback-routes.ts

@@ -0,0 +1,75 @@
+/**
+ * `GET|PUT /api/fallback`: the OCX-11 fallback state (`ocx.fallback/1`) and its one scoped write.
+ *
+ * GET is a passive read. A Remote Link Child reaches it through the read-only link relay
+ * (`LINK_MANAGEMENT_READ_PATHS`); there it drops link aliases (`buildFallbackState` passive). PUT
+ * runs on the Home only: a Child's relay and CLI refuse writes before sending.
+ */
+import type { ManagementContext } from "./context";
+import { jsonResponse } from "../auth-cors";
+import { mutatePersistedConfig } from "../../config";
+import { isPassiveRead } from "../../lib/passive-read";
+import { readLinkStore, type LinkRecord } from "../../link/store";
+import { linkStorePath } from "../../link/paths";
+import { applyFallbackWrite, buildFallbackState, parseFallbackWrites } from "../../routing/fallback-state";
+import { managementBodyTooLargeResponse, readManagementJsonBody } from "./body";
+
+function links(ctx: ManagementContext): LinkRecord[] {
+  try {
+    return (ctx.deps.readLinkStore?.() ?? readLinkStore(linkStorePath())).links;
+  } catch {
+    return [];
+  }
+}
+
+function view(ctx: ManagementContext): Response {
+  const response = jsonResponse(buildFallbackState(ctx.config, { links: links(ctx), passive: isPassiveRead() }), 200, ctx.req, ctx.config);
+  response.headers.set("cache-control", "no-store");
+  return response;
+}
+
+export async function handleFallbackRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config } = ctx;
+  if (url.pathname === "/api/fallback" && req.method === "GET") return view(ctx);
+  if (url.pathname === "/api/fallback" && req.method === "PUT") return await writeFallback(ctx);
+  return null;
+}
+
+async function writeFallback(ctx: ManagementContext): Promise<Response> {
+  const { req, config } = ctx;
+  let body: unknown;
+  try {
+    body = await readManagementJsonBody(req);
+  } catch (error) {
+    return managementBodyTooLargeResponse(error, req, config)
+      ?? jsonResponse({ error: "invalid JSON body", code: "invalid_request" }, 400, req, config);
+  }
+  const parsed = parseFallbackWrites(body);
+  if (!parsed.ok) return jsonResponse({ error: parsed.error, code: "invalid_request" }, 400, req, config);
+  const known = links(ctx);
+  for (const write of parsed.writes) {
+    if (write.scope !== "device") continue;
+    // A link alias names its link; otherwise the key must be a known link id or data key id.
+    const byAlias = known.find(link => link.alias === write.key);
+    if (byAlias) write.key = byAlias.id;
+    // Clearing stays possible for a device that is gone (a revoked link, a deleted data key):
+    // its entry still lists in the state, and clearing a missing entry is a no-op.
+    if (write.value === null) continue;
+    const exists = known.some(link => link.id === write.key)
+      || (config.apiKeys ?? []).some(entry => entry.id === write.key);
+    if (!exists) {
+      return jsonResponse({ error: "unknown device: use a link id or alias from ocx link status, or a Hub data key id", code: "unknown_device" }, 404, req, config);
+    }
+  }
+  const outcome = mutatePersistedConfig(persisted => {
+    let changed = false;
+    for (const write of parsed.writes) changed = applyFallbackWrite(persisted, write) || changed;
+    return { changed, value: persisted.fallback === undefined ? undefined : structuredClone(persisted.fallback) };
+  });
+  if (outcome.status === "unavailable") {
+    return jsonResponse({ error: "config.json is " + outcome.reason + "; fallback settings were not saved", code: "config_unavailable" }, 409, req, config);
+  }
+  if (outcome.value === undefined) delete config.fallback;
+  else config.fallback = outcome.value;
+  return view(ctx);
+}

package/src/server/management/link-enrollment.ts

@@ -3,6 +3,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { assertSshAlias, buildExecArgv, buildFingerprintArgv, buildProbeArgv, REMOTE_COMMAND_NOT_FOUND, REMOTE_PLATFORM_UNSUPPORTED, remoteOcxArgv } from "../../link/ssh-argv";
 import { parseFingerprintLine } from "../../link/fingerprint";
+import { detectRemotePlatform, isWindowsShellRefusal, WINDOWS_CHILD_REFUSAL } from "../../link/remote-platform";
+import type { SshRunner } from "../../link/ssh-runner";
 import { LINK_CATALOG_MAX_BYTES, LINK_RELAY_VERIFY_MS, isChildHealth, linkCommandBudget, linkRestartBudget, parseChildHttp, remoteChildHttpArgv, REMOTE_CURL_PREFLIGHT } from "../../link/remote-probe";
 import { newLinkId, type LinkStore } from "../../link/store";
 import { SshRunnerError, boundHint, sshFailureHint, sshRunnerErrorHint, type SshRunResult } from "../../link/ssh-runner";
@@ -24,11 +26,23 @@ async function serialized(state: LinkRouteState, alias: string, action: () => Pr
 }
 
 function remoteFailure(result: SshRunResult, code: string, message: string): Response | null {
-  if (result.code === REMOTE_PLATFORM_UNSUPPORTED) return fail("remote_platform_unsupported", "Remote Link Children require macOS or Linux; Windows is unsupported.", 409);
+  if (result.code === REMOTE_PLATFORM_UNSUPPORTED || (result.code !== 0 && isWindowsShellRefusal(result.stderr))) return windowsRefusal();
   if (result.code === REMOTE_COMMAND_NOT_FOUND) return fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr));
   return result.code === 0 ? null : fail(code, message, 502, sshFailureHint(result.stderr));
 }
 
+function windowsRefusal(): Response {
+  return fail("remote_platform_unsupported", WINDOWS_CHILD_REFUSAL, 409);
+}
+
+/**
+ * Pre-issuance Windows gate for a failed remote command: exit 125, the English cmd/PowerShell
+ * refusal, or (for localized shells) the fixed %OS% probe against the same host key.
+ */
+async function windowsChild(runner: SshRunner, alias: string, knownHostsFile: string, result: SshRunResult): Promise<boolean> {
+  return result.code !== 0 && await detectRemotePlatform(runner, alias, knownHostsFile, result) === "windows";
+}
+
 export async function probe(ctx: ManagementContext, state: LinkRouteState): Promise<Response> {
   const value = await readManagementJsonBodyOr(ctx.req, null);
   const body = exactBody(value, ["alias"]) ?? exactBody(value, ["alias", "includeVersion"]);
@@ -44,7 +58,8 @@ export async function probe(ctx: ManagementContext, state: LinkRouteState): Prom
       const started = now();
       const result = await runner.run(buildProbeArgv({ alias, tempKnownHostsFile: path }), { timeoutMs: 30_000 });
       const latency = Math.max(0, now() - started);
-      if (result.code !== 0) return fail("probe_failed", "SSH host probing failed.", 502, sshFailureHint(result.stderr));
+      // cmd.exe and PowerShell refuse the POSIX `true` the probe runs; say Windows, not "probe failed".
+      if (result.code !== 0) return await windowsChild(runner, alias, path, result) ? windowsRefusal() : fail("probe_failed", "SSH host probing failed.", 502, sshFailureHint(result.stderr));
       const fp = await runner.run(buildFingerprintArgv(path), { timeoutMs: 10_000 });
       if (fp.code !== 0) return fail("fingerprint_failed", "The SSH host fingerprint could not be read.", 502, sshFailureHint(fp.stderr));
       const parsed = parseFingerprintLine(fp.stdout.trim());
@@ -53,6 +68,7 @@ export async function probe(ctx: ManagementContext, state: LinkRouteState): Prom
       let ocxVersion: string | undefined;
       if (body.includeVersion === true) {
         const versionResult = await runner.run(buildExecArgv({ alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 });
+        if (await windowsChild(runner, alias, path, versionResult)) return windowsRefusal();
         const denied = remoteFailure(versionResult, "version_probe_failed", "The remote ocx version could not be read.");
         if (denied) return denied;
         const parsedVersion = parseVersion(versionResult.stdout);
@@ -84,7 +100,9 @@ export async function confirmHost(ctx: ManagementContext, state: LinkRouteState)
     writeFileSync(path, pending.knownHostLine + "\n", { mode: 0o600 });
     try {
       const started = now();
-      const result = await runnerFor(ctx).run(buildExecArgv({ alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 });
+      const runner = runnerFor(ctx);
+      const result = await runner.run(buildExecArgv({ alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 });
+      if (await windowsChild(runner, alias, path, result)) return windowsRefusal();
       const denied = remoteFailure(result, "version_probe_failed", "The remote ocx version could not be confirmed.");
       if (denied) return denied;
       const version = parseVersion(result.stdout);

package/src/server/management/link-route-state.ts

@@ -27,6 +27,8 @@ export interface LinkRouteListener {
   status(): { state: "off" | "listening" | "failed"; port: number | null; reason: string | null };
   close(): Promise<void>;
   onAuthenticatedCatalog(listener: (apiKeyId: string) => void): () => void;
+  /** Optional so route fakes stay small; without it every link reports an unknown peer. */
+  peerObservation?(linkId: string): import("../../link/peer-report").LinkPeerEntry;
 }
 
 export interface LinkRouteState {

package/src/server/management/link-routes.ts

@@ -6,7 +6,11 @@ import { clearCompensationFailed, compensationPath, readCompensation } from "../
 import { loadHostCandidates } from "../../link/ssh-config";
 import { newLinkId, type LinkStore } from "../../link/store";
 import { sshFailureHint, sshRunnerErrorHint } from "../../link/ssh-runner";
-import { projectLinkStatus, type LinkStatusDto } from "../../link/status-projection";
+import { attachLinkPeers, projectLinkStatus, type LinkStatusDto } from "../../link/status-projection";
+import { homeLinkChildParity } from "../../link/child-parity";
+import { localLinkPeer } from "../../link/compatibility";
+import { packageVersion } from "../../lib/package-version";
+import { buildPeerFeatures } from "../../remote/features";
 import { isLinkPort } from "../../link/ports";
 import { joinHome, type ClientLinkJoinDeps } from "../../client/link-join";
 import { clientLinkStatusIdentity } from "../../client/link-status";
@@ -268,6 +272,7 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
       store, state.supervisor.status(), listenerStatus, ctx.config, readCompensation(),
       ctx.config.runtimeRole === "client" ? clientLinkTunnelStatus() : null,
       ctx.config.runtimeRole === "client" && ctx.config.client?.link ? clientLinkStatusIdentity(ctx.config.client.link.linkId) : null,
+      linkId => homeLinkChildParity.get(linkId),
     );
     for (const link of dto.links) {
       const failure = state.compensationFailures?.get(link.id);
@@ -277,6 +282,12 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
       const failure = state.compensationFailures?.get(store.links[0].id);
       if (failure) Object.assign(dto.child, { state: "failed" as const, since: failure.since, reason: failure.reason });
     }
+    // Opt-in: an older `ocx link status` validates the document key by key and would reject the
+    // added fields, so only a caller that asks for compatibility gets `local` and `peer`.
+    if (url.searchParams.get("compatibility") === "1") {
+      attachLinkPeers(dto, localLinkPeer(packageVersion("0.0.0"), buildPeerFeatures()),
+        linkId => state.listener.peerObservation?.(linkId) ?? { observed: null, refused: null });
+    }
     // A dashboard session also learns why it cannot join as a Child. The admin-token answer stays
     // the exact K16 document that `ocx link status` validates key by key.
     const denial = ctx.principal === "gui-session" ? joinDenied(ctx) : null;

package/src/server/management/oauth-account-routes.ts

@@ -374,7 +374,8 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     // Without a flow id this cancels the provider's newest in-flight login, which is what the
     // single-user GUI has always meant by "Cancel". A host running concurrent code logins for
     // several users passes the flowId it was given at /api/oauth/login.
-    const cancelled = cancelLoginFlow(provider, typeof body.flowId === "string" ? body.flowId : undefined);
+    const cancelled = cancelLoginFlow(provider, typeof body.flowId === "string" ? body.flowId : undefined,
+      { dismissSettledFailure: true });
     return jsonResponse({ ok: true, cancelled });
   }
 

package/src/server/management/quota-pool-routes.ts

@@ -0,0 +1,24 @@
+/**
+ * `GET /api/quota-pool`: the `ocx.quota-pool/1` read GOAT consumes (see src/quota-pool/).
+ *
+ * Same management authorization as the neighbouring reads; a Remote Link Child reaches it through
+ * the read-only link relay (`LINK_MANAGEMENT_READ_PATHS`) and a Hub client through its hub relay.
+ * The read is always passive: there is no refresh form, so nothing here can make the Home probe.
+ */
+import type { ManagementContext } from "./context";
+import { jsonResponse } from "../auth-cors";
+
+export async function handleQuotaPoolRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config } = ctx;
+  // Any query (including a stray refresh=1) is ignored: the read has no active form.
+  if (url.pathname === "/api/quota-pool" && req.method === "GET") {
+    const { readQuotaPool } = await import("../../quota-pool/assemble");
+    const result = await readQuotaPool(config);
+    const response = result.ok
+      ? jsonResponse(result.pool, 200, req, config)
+      : jsonResponse({ error: result.error }, 503, req, config);
+    response.headers.set("cache-control", "no-store");
+    return response;
+  }
+  return null;
+}