@bitkyc08/opencodex 2.90.0 → 2.92.0

package/src/lib/authorization-scheme.ts

@@ -0,0 +1,95 @@
+/**
+ * One parser for the inbound `Authorization` scheme.
+ *
+ * Bearer reads in the proxy used `replace(/^Bearer\s+/i, "")`, which returns any other value
+ * unchanged. Codex 0.164 runtime agent instances (`features.runtime_agent_instances`) can send
+ * `Authorization: AgentAssertion <jwt>`, and that replace handed the whole value on as an opaque
+ * bearer. An agent assertion is never a bearer: it is not an opencodex admission secret, it is not
+ * a ChatGPT credential, and it must never be forwarded as `Bearer`.
+ *
+ * The legacy read is preserved for every other value, including a scheme-less token, so this file
+ * changes nothing except the AgentAssertion case.
+ */
+
+/** The companion header Codex sends in `dual_header` mode next to an ordinary Bearer. */
+export const AGENT_ASSERTION_HEADER = "x-openai-agent-assertion";
+
+/** Stable error code for `Authorization: AgentAssertion`, which opencodex does not route. */
+export const AGENT_ASSERTION_UNSUPPORTED_CODE = "agent_assertion_unsupported";
+
+export const AGENT_ASSERTION_UNSUPPORTED_MESSAGE = "Codex runtime agent assertion_only authentication "
+  + "(Authorization: AgentAssertion) is not supported through opencodex pooling or routing. "
+  + "Use dual_header mode, or turn off features.runtime_agent_instances.";
+
+export type AuthorizationScheme =
+  | { kind: "none" }
+  | { kind: "bearer"; token: string }
+  | { kind: "agent-assertion" }
+  | { kind: "other"; credential: string };
+
+const BEARER_PREFIX = /^Bearer\s+/i;
+// RFC 9110 auth schemes are case-insensitive; the scheme ends at whitespace or end of value.
+const AGENT_ASSERTION_SCHEME = /^\s*AgentAssertion(?:\s|$)/i;
+
+/** Classify an Authorization value. The assertion's own bytes are deliberately not returned. */
+export function parseAuthorizationScheme(value: string | null | undefined): AuthorizationScheme {
+  if (value == null) return { kind: "none" };
+  if (AGENT_ASSERTION_SCHEME.test(value)) return { kind: "agent-assertion" };
+  if (BEARER_PREFIX.test(value)) {
+    const token = value.replace(BEARER_PREFIX, "").trim();
+    return token ? { kind: "bearer", token } : { kind: "none" };
+  }
+  const credential = value.trim();
+  return credential ? { kind: "other", credential } : { kind: "none" };
+}
+
+/**
+ * The credential the legacy `replace(/^Bearer\s+/i, "").trim()` read produced, except that an
+ * AgentAssertion value yields nothing. Use this wherever that replace used to be.
+ */
+export function authorizationCredential(headers: Pick<Headers, "get">): string | undefined {
+  const parsed = parseAuthorizationScheme(headers.get("authorization"));
+  if (parsed.kind === "bearer") return parsed.token;
+  if (parsed.kind === "other") return parsed.credential;
+  return undefined;
+}
+
+/** Whether the request authenticates with `Authorization: AgentAssertion` (assertion_only). */
+export function hasAgentAssertionAuthorization(headers: Pick<Headers, "get">): boolean {
+  return parseAuthorizationScheme(headers.get("authorization")).kind === "agent-assertion";
+}
+
+export class AgentAssertionUnsupportedError extends Error {
+  readonly code = AGENT_ASSERTION_UNSUPPORTED_CODE;
+  constructor() {
+    super(AGENT_ASSERTION_UNSUPPORTED_MESSAGE);
+    this.name = "AgentAssertionUnsupportedError";
+  }
+}
+
+/** The typed refusal. It never echoes the request's Authorization or assertion header. */
+export function agentAssertionUnsupportedResponse(): Response {
+  return Response.json({
+    error: {
+      message: AGENT_ASSERTION_UNSUPPORTED_MESSAGE,
+      type: "invalid_request_error",
+      code: AGENT_ASSERTION_UNSUPPORTED_CODE,
+    },
+  }, { status: 400, headers: { "cache-control": "no-store" } });
+}
+
+/**
+ * Carry the dual_header assertion onto first-party Direct headers, and only when the outbound
+ * Authorization is the caller's own Bearer, byte for byte. A pool account, a substituted main
+ * credential, or a stripped Authorization means the assertion would accompany a credential it was
+ * not sent with, so it is dropped instead.
+ */
+export function carryAgentAssertionForCallerBearer(target: Headers, caller: Pick<Headers, "get">): void {
+  target.delete(AGENT_ASSERTION_HEADER);
+  const assertion = caller.get(AGENT_ASSERTION_HEADER);
+  if (!assertion) return;
+  const callerAuth = parseAuthorizationScheme(caller.get("authorization"));
+  const outboundAuth = parseAuthorizationScheme(target.get("authorization"));
+  if (callerAuth.kind !== "bearer" || outboundAuth.kind !== "bearer" || callerAuth.token !== outboundAuth.token) return;
+  target.set(AGENT_ASSERTION_HEADER, assertion);
+}

package/src/lib/decision-quota-sink.ts

@@ -18,6 +18,10 @@ import type { CodexAccountCredentialRecord } from "../types";
 
 export type DecisionPoolRead = readonly { id: string; usable: boolean; windows?: readonly DecisionQuotaWindow[] }[];
 export interface MainDecisionRow { generation: number; usable: boolean }
+/** Opaque, process-local producer receipt; only the active snapshot can validate it. */
+export interface AntigravityQuotaReceipt { readonly kind: "antigravity" }
+export interface AntigravityQuotaObservation { name: string; provider: OcxProviderConfig; receipt: AntigravityQuotaReceipt; windows: readonly DecisionQuotaWindow[] }
+export interface DecisionKeyObservation { name: string; provider: OcxProviderConfig; windows: readonly DecisionQuotaWindow[] }
 
 export interface DecisionQuotaSink {
   observeKeyCredential(reference: string, resolved: string | undefined): void;
@@ -32,6 +36,8 @@ export interface DecisionQuotaSink {
   mainRosterChanged(row: MainDecisionRow | undefined): void;
   readKeyQuota(name: string, provider: OcxProviderConfig): readonly DecisionQuotaWindow[] | undefined;
   readPool(provider: string): DecisionPoolRead | undefined;
+  captureAntigravityReceipt(name: string, provider: OcxProviderConfig, id: string, generation: string): AntigravityQuotaReceipt | undefined;
+  replaceCollectedQuotas(keys: readonly DecisionKeyObservation[], oauth: readonly AntigravityQuotaObservation[]): void;
 }
 
 let sink: DecisionQuotaSink | undefined;
@@ -71,6 +77,10 @@ export function notifyCodexStoreLoaded(store: Readonly<Record<string, CodexAccou
 export function notifyMainRosterChanged(row: () => MainDecisionRow | undefined): void { forward(s => s.mainRosterChanged(row())); }
 export function readLoadedDecisionKeyQuota(name: string, provider: OcxProviderConfig): readonly DecisionQuotaWindow[] | undefined { return read(s => s.readKeyQuota(name, provider)); }
 export function readLoadedDecisionQuotaPool(provider: string): DecisionPoolRead | undefined { return read(s => s.readPool(provider)); }
+/** Capture from the producer's already-loaded credential, never from a decision read. */
+export function captureAntigravityQuotaReceipt(name: string, provider: OcxProviderConfig, id: string, generation: string): AntigravityQuotaReceipt | undefined { return read(s => s.captureAntigravityReceipt(name, provider, id, generation)); }
+/** Accepted collector atomically replaces its key/instance evidence set. */
+export function replaceCollectedDecisionQuotas(keys: readonly DecisionKeyObservation[], oauth: readonly AntigravityQuotaObservation[]): void { forward(s => s.replaceCollectedQuotas(keys, oauth)); }
 
 /** Test-only: drop any registration a previous test left behind. */
 export function resetDecisionQuotaSinkForTests(): void { sink = undefined; }

package/src/lib/provider-client-headers.ts

@@ -21,6 +21,7 @@ const BLOCKED_FORWARDED_CLIENT_HEADERS = new Set([
   "api-key",
   "x-goog-api-key",
   "x-oai-attestation",
+  "x-openai-agent-assertion",
 ]);
 
 const ALLOWED_FORWARDED_CLIENT_HEADERS = new Set([

package/src/lib/redact.ts

@@ -7,7 +7,7 @@ export const REDACTED_SECRET = "[REDACTED]";
  * credentials over an unsafe channel (e.g. plaintext non-loopback HTTP) rather than
  * re-deriving a narrower local list.
  */
-export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|x-dsh-auth-token|copilot[-_]?session[-_]?token|session[-_]?token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
+export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|x-dsh-auth-token|x-openai-agent-assertion|copilot[-_]?session[-_]?token|session[-_]?token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
 
 /**
  * Colon-labelled credential headers echoed back inside an error body
@@ -40,7 +40,7 @@ export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cook
 // Every letter position also accepts \u0001, the placeholder the fold emits for
 // an unresolved HTML named reference: `authorⅈzation` is the label with one
 // character we cannot name, and that is still the label.
-const CREDENTIAL_HEADER_LABEL_RAW = "copilot[_-]?session[_-]?token|session[_-]?token|sessionToken|x-api-key|x-goog-api-key|x-amz-security-token|x-dsh-auth-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
+const CREDENTIAL_HEADER_LABEL_RAW = "copilot[_-]?session[_-]?token|session[_-]?token|sessionToken|x-openai-agent-assertion|x-api-key|x-goog-api-key|x-amz-security-token|x-dsh-auth-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
 
 const CREDENTIAL_HEADER_LABEL = CREDENTIAL_HEADER_LABEL_RAW
   .replace(/(?<![\[\\])([A-Za-z])(?![\]\-])/g, "[$1\u0001]");

package/src/lib/system-restart-contract.ts

@@ -12,6 +12,30 @@ export const SYSTEM_RESTART_CAPABILITY_HEADER = "x-opencodex-restart-capability"
 export const MEMORY_DRAIN_RESTART_MS = 60_000;
 export const REPLACEMENT_READY_TIMEOUT_MS = 70_000;
 
+/**
+ * A connected client runtime's whole restart, from accepting the request to serving again on the
+ * old process after a failed replacement (OCX-6). The CLI sends the request only while this budget
+ * still fits before its own replacement observation ends, so a rollback is never raced by the
+ * CLI's recovery start. The phases are measured from acceptance.
+ */
+export const CLIENT_RESTART_BUDGET_MS = 90_000;
+/** In-flight requests on the client listener get this long before the listener closes them. */
+export const CLIENT_RESTART_DRAIN_MS = 20_000;
+/** The replacement must answer by this point; a later one is stopped and the old runtime resumes. */
+export const CLIENT_RESTART_READY_BY_MS = 70_000;
+/** How long a rollback waits for the port the stopped replacement released. */
+export const CLIENT_RESTART_REBIND_WAIT_MS = 10_000;
+/** The 409 code a supervised client runtime answers a bound restart with. */
+export const RESTART_SUPERVISED_ERROR = "restart_supervised";
+/** `ocx restart` stops waiting for a replacement this long before its overall deadline. */
+export const RESTART_REOBSERVE_RESERVE_MS = 10_000;
+/**
+ * Room `ocx restart` must still have before it may ask a client runtime to restart: the client's
+ * whole budget, the reobserve reserve and a margin for the request itself. A later request is
+ * refused before it is sent, so a rollback always finishes while the CLI is still observing.
+ */
+export const CLIENT_RESTART_REQUEST_MIN_REMAINING_MS = CLIENT_RESTART_BUDGET_MS + RESTART_REOBSERVE_RESERVE_MS + 5_000;
+
 /**
  * The env var a restarting process hands its replacement `ocx start`: the restarting (parent) pid.
  *

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

@@ -13,14 +13,15 @@
  * 1. It must be INERT in production. Guessing "am I a test?" from ecosystem variables
  *    like NODE_ENV would brick `NODE_ENV=test ocx ...` for a user who did nothing
  *    wrong — worse than the bug it prevents. Arming requires OCX_TEST_HOME_GUARD=1,
- *    which only this repository's test preload sets.
+ *    which this repository's test preload sets, or a process whose entry module is a
+ *    Bun test file (see {@link isBunTestFileProcess}); no production entrypoint is one.
  * 2. It must fail CLOSED for code nobody has written yet. So it denies ONE path — the
  *    captured production home — instead of allow-listing known-good test directories.
  *    An allowlist would have to be opted into, and the test that forgets is exactly
  *    how this incident happened.
  */
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
@@ -109,8 +110,71 @@ export function protectedClaudeConfigDirsForTests(): readonly string[] {
   return PROTECTED_CLAUDE_TREES.map(tree => tree.path);
 }
 
+/**
+ * The file names Bun's test runner discovers: `.test`, `_test`, `.spec` or `_spec` before a
+ * JS/TS extension. Under `bun test`, `Bun.main` names the test file being evaluated, in the
+ * main runner and in `--parallel` workers alike. Every production entrypoint — the CLI, the
+ * service daemon, the compiled sidecar (`/$bunfs/...`), a release script — has a different name.
+ */
+const BUN_TEST_FILE = /[._](?:test|spec)\.[cm]?[jt]sx?$/i;
+
+/**
+ * Whether this process runs a Bun test file as its entry module.
+ *
+ * This exists for the run that never loads `tests/preload.ts`. Bun resolves `bunfig.toml` from
+ * the CURRENT WORKING DIRECTORY, so `cd /tmp && bun test <repo>/tests/x.test.ts` skips the
+ * preload: HOME stays real, OPENCODEX_HOME stays unset, and before this check the guard stayed
+ * down, so an OAuth save landed in the developer's real `~/.opencodex/auth.json` (#7407).
+ * Bun exposes no runner flag, and NODE_ENV=test is both settable by users and overridable by the
+ * runner's caller, so the entry file's name is the one signal that production never carries.
+ *
+ * A file passed by explicit path under a non-test name (`bun test ./scratch.ts`) is not
+ * recognised; every repository suite is a `*.test.ts`, the only name `tests/test-layout.test.ts` admits.
+ *
+ * The converse also holds: `bun run ./something.test.ts` arms, because nothing distinguishes it
+ * from the runner. That is accepted. Requiring NODE_ENV=test as well would exempt every developer
+ * whose shell exports another NODE_ENV (`bun test` keeps an existing value), reopening #7407;
+ * the cost of the false positive is a refused real-home write from a script named like a test.
+ */
+export function isBunTestFileProcess(): boolean {
+  const main = (globalThis as { Bun?: { main?: unknown } }).Bun?.main;
+  const entry = typeof main === "string" ? main : process.argv[1];
+  return typeof entry === "string" && BUN_TEST_FILE.test(basename(entry));
+}
+
+/**
+ * Armed when the preload (or a harness) set OCX_TEST_HOME_GUARD=1, or when this process runs a
+ * Bun test file and nobody set the flag. An explicit OCX_TEST_HOME_GUARD=0 is how a test case
+ * exercises the production branch of a guarded call, so it disarms even inside a test file.
+ */
 export function isTestHomeGuardArmed(): boolean {
-  return process.env[GUARD_ENV] === "1";
+  const flag = process.env[GUARD_ENV];
+  if (flag === "1") return true;
+  if (flag === "0") return false;
+  return isBunTestFileProcess();
+}
+
+/**
+ * A test process that armed through its entry file publishes the flag, so the CLI and helper
+ * processes it spawns — whose own entry is not a test file — inherit the arming instead of
+ * writing the real home they also inherited. Runs at import, which in such a run happens before
+ * any test body. A production process never matches, so it never reaches the assignment. Any value
+ * but the explicit "0" opt-out is normalised, because an empty or stray value arms this process by
+ * name but would leave a non-test child, which cannot match by name, disarmed.
+ */
+if (process.env[GUARD_ENV] !== "0" && process.env[GUARD_ENV] !== "1" && isBunTestFileProcess()) {
+  process.env[GUARD_ENV] = "1";
+}
+
+/**
+ * Appended to a refusal when no preload ran, because the fix there is different: the test did
+ * not forget OPENCODEX_HOME, the whole run started from a directory without bunfig.toml.
+ */
+function missingPreloadHint(): string {
+  if (process.env.OCX_TEST_PRELOAD_PID !== undefined) return "";
+  return " This test process did not load tests/preload.ts — Bun reads bunfig.toml from the "
+    + "current working directory — so nothing was sandboxed. Run bun test from the repository "
+    + "root, or pass --preload <repo>/tests/preload.ts.";
 }
 
 /**
@@ -144,7 +208,8 @@ export function assertNotRealHomeUnderTest(dir: string): void {
   throw new Error(
     `refusing to write the real OpenCodex home (${PROTECTED_HOME}) from a test process. `
     + "Point OPENCODEX_HOME at a temp directory for this test, or inject persistence "
-    + "instead of calling the global writer (see devlog 260730_codex_rs_upstream_v2_live_handoff/070).",
+    + "instead of calling the global writer (see devlog 260730_codex_rs_upstream_v2_live_handoff/070)."
+    + missingPreloadHint(),
   );
 }
 
@@ -177,7 +242,8 @@ export function assertNotRealCodexHomeUnderTest(dir: string): void {
   throw new Error(
     `refusing to write the real Codex home (${PROTECTED_CODEX_HOME}) from a test process. `
     + "Point CODEX_HOME at a temp directory for this test before writing Codex files "
-    + "(auth.json, the catalog, models_cache.json, the journal or config.toml).",
+    + "(auth.json, the catalog, models_cache.json, the journal or config.toml)."
+    + missingPreloadHint(),
   );
 }
 
@@ -351,12 +417,13 @@ export function protectedRemovalReason(target: string): string | null {
 /**
  * Throw before a removal that would reach a protected tree.
  *
- * Deliberately NOT gated on {@link isTestHomeGuardArmed}. Arming happens in `tests/preload.ts`,
- * which Bun loads from the `bunfig.toml` it finds in the CURRENT WORKING DIRECTORY — so a run
- * started outside the repository arms nothing, leaves OPENCODEX_HOME unset, and resolves the
- * developer's real home. That unarmed run is precisely the one that caused the incident, so the
- * refusal has to hold without it. Nothing in production calls this; the callers are test
- * helpers, where the only cost of an unconditional check is a path comparison.
+ * Deliberately NOT gated on {@link isTestHomeGuardArmed}. `tests/preload.ts` is loaded from the
+ * `bunfig.toml` Bun finds in the CURRENT WORKING DIRECTORY, so a run started outside the
+ * repository leaves OPENCODEX_HOME unset and resolves the developer's real home. Such a run now
+ * arms through its test-file entry, but a helper launched as a plain script does not, and the
+ * incident was exactly this unsandboxed shape, so the refusal has to hold without arming.
+ * Nothing in production calls this; the callers are test helpers, where the only cost of an
+ * unconditional check is a path comparison.
  */
 export function assertRemovalOutsideProtectedTrees(target: string): void {
   const reason = protectedRemovalReason(target);

package/src/lib/translator-budget.ts

@@ -1,4 +1,4 @@
-import { isNonReplayableResponse, markResponseNonReplayable } from "./upstream-retry";
+import { carryReplayRefusal, isNonReplayableResponse, markResponseNonReplayable } from "./upstream-retry";
 
 export const TRANSLATOR_MAX_CALL_ARGUMENT_BYTES = 2 * 1024 * 1024;
 export const TRANSLATOR_MAX_TURN_BYTES = 32 * 1024 * 1024;
@@ -413,8 +413,8 @@ export function finalizeTranslatorBudgetResponse(response: Response, budget: Tra
   if (signal?.aborted) finalize();
   else signal?.addEventListener("abort", finalize, { once: true });
   const finalizedResponse = new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
-  // The rebuild above drops identity markers. A refusal that must not be replayed
-  // stays non-replayable through accounting finalization.
+  // Preserve both replay suppression and refusal provenance across the rebuild
+  // so deferred logging can distinguish synthetic refusals from upstream 429s.
   if (isNonReplayableResponse(response)) markResponseNonReplayable(finalizedResponse);
-  return finalizedResponse;
+  return carryReplayRefusal(response, finalizedResponse);
 }

package/src/lib/upstream-retry.ts

@@ -770,7 +770,10 @@ export async function fetchWithTransientRetry(
   for (let attempt = 0; sent < budget; attempt++) {
     // A non-replayable gateway status was settled after the request body had already left
     // for the origin; retrying it here is the automatic resend the marker exists to forbid.
-    if (res.ok || !isTransientUpstreamStatus(res.status) || isNonReplayableResponse(res)) return res;
+    // An upstream that answers with the exact `x-should-retry: false` verdict has said the same
+    // thing about its own failure, so the ladder stops and hands the response back untouched.
+    if (res.ok || !isTransientUpstreamStatus(res.status) || isNonReplayableResponse(res)
+      || res.headers.get(REPLAY_REFUSAL_NO_RETRY_HEADER) === REPLAY_REFUSAL_NO_RETRY_VALUE) return res;
     // Checked before cancelResponseBodyBestEffort so an already-aborted caller never receives
     // a response whose body we just cancelled.
     if (opts.abortSignal?.aborted) return res;

package/src/link/child-parity.ts

@@ -0,0 +1,124 @@
+/**
+ * What a Remote Link Child tells its Home about the last settings apply (OCX-6).
+ *
+ * The Child knows when it last applied the Home's Codex settings, which digest it applied and when
+ * its runtime started; the Home knows none of it. The Child reports these facts over the link
+ * (`POST` to {@link LINK_CHILD_PARITY_PATH}, admitted by its link key) and the Home shows them on
+ * each link row of `GET /api/link/status` (`lastApplyAt`, `runtimeStartedAt`,
+ * `appliedCodexSettingsDigest`), so a peer can compare apply time with runtime start, and the
+ * applied digest with the Home's own, without reading the Child.
+ *
+ * Display only. A report never admits, routes or changes anything on the Home, carries no setting
+ * value, and lives in memory: a Home restart forgets it until the Child's next report (at most a
+ * minute later).
+ */
+import { CODEX_SETTINGS_DIGEST_PATTERN } from "./codex-settings";
+import { LINK_MANAGEMENT_PREFIX } from "./management-routes";
+
+/** The one write a Child may send its Home over the link. */
+export const LINK_CHILD_PARITY_PATH = `${LINK_MANAGEMENT_PREFIX}/child-parity`;
+/** A report is four short fields; anything larger is refused while it is still being read. */
+export const LINK_CHILD_PARITY_MAX_BYTES = 1024;
+
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+/** 2001-09-09 .. 2286-11-20: any epoch-millisecond time a real clock reports. */
+const MIN_EPOCH_MS = 1_000_000_000_000;
+const MAX_EPOCH_MS = 9_999_999_999_999;
+
+export interface LinkChildParityReport {
+  linkId: string;
+  /** Epoch ms of the Child's last successful apply of a different Home settings document. */
+  lastApplyAt: number | null;
+  /** Epoch ms of the Child runtime's process start. */
+  runtimeStartedAt: number;
+  /** `appliedCodexSettingsDigest` of the applied settings; null before any apply. */
+  appliedCodexSettingsDigest: string | null;
+  /**
+   * Increases with every report this runtime process sends. With `runtimeStartedAt` it orders
+   * reports, so a late POST from an older runtime or an earlier send never replaces a newer one.
+   */
+  sequence: number;
+}
+
+/** The per-link fields `GET /api/link/status` carries; every one is null until a report arrives. */
+export interface LinkChildParity {
+  lastApplyAt: number | null;
+  runtimeStartedAt: number | null;
+  appliedCodexSettingsDigest: string | null;
+  /** Epoch ms the Home received the report (the Home's clock; the other times are the Child's). */
+  reportedAt: number | null;
+}
+
+export const EMPTY_LINK_CHILD_PARITY: LinkChildParity = Object.freeze({
+  lastApplyAt: null, runtimeStartedAt: null, appliedCodexSettingsDigest: null, reportedAt: null,
+});
+
+export function isEpochMs(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= MIN_EPOCH_MS && value <= MAX_EPOCH_MS;
+}
+
+function exactKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value);
+  return actual.length === keys.length && actual.every(key => keys.includes(key));
+}
+
+/** Strict: an unknown field, a non-integer time or a malformed digest rejects the report. */
+export function parseLinkChildParityReport(value: unknown): LinkChildParityReport | null {
+  if (!exactKeys(value, ["linkId", "lastApplyAt", "runtimeStartedAt", "appliedCodexSettingsDigest", "sequence"])) return null;
+  const { linkId, lastApplyAt, runtimeStartedAt, appliedCodexSettingsDigest: digest, sequence } = value;
+  if (typeof linkId !== "string" || !LINK_ID.test(linkId)) return null;
+  if (lastApplyAt !== null && !isEpochMs(lastApplyAt)) return null;
+  if (!isEpochMs(runtimeStartedAt)) return null;
+  if (digest !== null && (typeof digest !== "string" || !CODEX_SETTINGS_DIGEST_PATTERN.test(digest))) return null;
+  // An apply has both a time and a digest; before the first apply it has neither.
+  if ((lastApplyAt === null) !== (digest === null)) return null;
+  if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence < 0) return null;
+  return { linkId, lastApplyAt, runtimeStartedAt, appliedCodexSettingsDigest: digest, sequence };
+}
+
+export interface LinkChildParityStore {
+  /**
+   * Keep the report for its link unless a newer one is already kept (by `runtimeStartedAt`, then
+   * `sequence`), dropping every entry whose link is not in `currentLinkIds`. True when kept.
+   */
+  record(report: LinkChildParityReport, currentLinkIds: ReadonlySet<string>): boolean;
+  get(linkId: string): LinkChildParity;
+  clear(): void;
+}
+
+export function createLinkChildParityStore(now: () => number = Date.now): LinkChildParityStore {
+  const reports = new Map<string, LinkChildParity & { sequence: number }>();
+  return {
+    record(report, currentLinkIds) {
+      for (const id of reports.keys()) if (!currentLinkIds.has(id)) reports.delete(id);
+      if (!currentLinkIds.has(report.linkId)) return false;
+      const kept = reports.get(report.linkId);
+      if (kept && (kept.runtimeStartedAt! > report.runtimeStartedAt
+        || (kept.runtimeStartedAt === report.runtimeStartedAt && kept.sequence >= report.sequence))) return false;
+      reports.set(report.linkId, {
+        lastApplyAt: report.lastApplyAt,
+        runtimeStartedAt: report.runtimeStartedAt,
+        appliedCodexSettingsDigest: report.appliedCodexSettingsDigest,
+        reportedAt: now(),
+        sequence: report.sequence,
+      });
+      return true;
+    },
+    get(linkId) {
+      const kept = reports.get(linkId);
+      if (!kept) return { ...EMPTY_LINK_CHILD_PARITY };
+      const { sequence: _sequence, ...parity } = kept;
+      return parity;
+    },
+    clear() { reports.clear(); },
+  };
+}
+
+/** The Home's reports: one process-wide store, bounded by the link store on every write. */
+export const homeLinkChildParity: LinkChildParityStore = createLinkChildParityStore();
+
+/** Home link listener: is this the Child's report (exact path, POST, no query, no upgrade)? */
+export function linkChildParityRouteAllowed(url: URL, req: Request): boolean {
+  return url.pathname === LINK_CHILD_PARITY_PATH && req.method === "POST" && url.search === "" && !req.headers.has("upgrade");
+}

package/src/link/codex-settings.ts

@@ -23,6 +23,7 @@
  * It rides on its own authenticated link read rather than inside the catalog because the
  * catalog bytes are written verbatim to `model_catalog_json`, which Codex parses itself.
  */
+import { createHash } from "node:crypto";
 import { hostname } from "node:os";
 import type { OcxConfig } from "../types";
 
@@ -153,3 +154,39 @@ export function describeHomeCodexSettings(settings: HomeCodexSettings): string[]
     `native sub-agent defaults: ${d ? `${d.model}${d.reasoningEffort ? ` (${d.reasoningEffort})` : ""}` : "not synced"}`,
   ];
 }
+
+/** 64 lowercase hex digits: the only form a settings digest takes on the wire. */
+export const CODEX_SETTINGS_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+
+/**
+ * The exact bytes {@link codexSettingsDigest} hashes: compact UTF-8 JSON in a fixed key order,
+ *
+ *   {"version":1,"settings":{"fastMode":…,"multiAgentMode":…,"webSearchSidecarEnabled":…,
+ *    "subagentDefaults":null|{"model":…,"reasoningEffort":…}}}
+ *
+ * This is a published contract (GOAT's hub recomputes it byte for byte), so the order is written
+ * out here rather than left to a canonicalizer, and every value is copied by name: whatever key
+ * order or extra field the input object has, the output is the same.
+ */
+export function codexSettingsDigestPayload(settings: HomeCodexSettings): string {
+  const d = settings.subagentDefaults;
+  return JSON.stringify({
+    version: HOME_CODEX_SETTINGS_VERSION,
+    settings: {
+      fastMode: settings.fastMode,
+      multiAgentMode: settings.multiAgentMode,
+      webSearchSidecarEnabled: settings.webSearchSidecarEnabled,
+      subagentDefaults: d ? { model: d.model, reasoningEffort: d.reasoningEffort } : null,
+    },
+  });
+}
+
+/**
+ * `appliedCodexSettingsDigest` (OCX-6b): lowercase hex SHA-256 of
+ * {@link codexSettingsDigestPayload}. It covers the applied values only, never the Home's name or
+ * version, so a Home and a Child that applied the same values agree, and any value change differs.
+ * It carries no setting value, so it is safe wherever `ocx status --json` goes.
+ */
+export function codexSettingsDigest(settings: HomeCodexSettings): string {
+  return createHash("sha256").update(codexSettingsDigestPayload(settings), "utf8").digest("hex");
+}

package/src/link/compatibility.ts

@@ -0,0 +1,119 @@
+/**
+ * Home and Child compatibility over a Remote Link.
+ *
+ * `LINK_PROTOCOL_RELEASES` is the published record of which release first spoke each part of the
+ * link protocol. It is history, so it cannot be derived at run time; `tests/clients/link-peer-
+ * compatibility.test.ts` holds every id to the live feature registry and every release to the
+ * package version. The verdict uses only what the link carries: the relay-auth version of a
+ * verified challenge and, from 2.91.0, the Child's own version and feature report
+ * (`src/link/peer-report.ts`).
+ */
+import { LINK_RELAY_AUTH_VERSION } from "./relay-auth";
+import { LINK_PEER_REPORT_VERSION, type LinkPeerEntry } from "./peer-report";
+
+export interface LinkProtocolRelease {
+  /** The peer feature id, as `GET /readyz` lists it. */
+  readonly id: string;
+  /** First release that speaks it on both sides of a link. */
+  readonly since: string;
+  readonly summary: string;
+}
+
+export const LINK_PEER_REPORT_FEATURE = `link-peer-report/${LINK_PEER_REPORT_VERSION}`;
+
+export const LINK_PROTOCOL_RELEASES: readonly LinkProtocolRelease[] = [
+  { id: "relay-auth/2", since: "2.69.0", summary: "Connection-bound relay authentication before every relayed request." },
+  { id: "link-management-relay", since: "2.84.0", summary: "Read-only Home management and Home Codex settings for the Child." },
+  { id: LINK_PEER_REPORT_FEATURE, since: "2.91.0", summary: "The Child reports its version and features on the relay challenge." },
+];
+
+export type LinkCompatibilityVerdict = "compatible" | "degraded" | "incompatible" | "unknown";
+
+export interface LinkLocalPeer {
+  version: string;
+  relayAuth: string;
+  features: string[];
+}
+
+export interface LinkPeerStatus {
+  observedAt: string | null;
+  /** The Child's reported release, or null when it predates the report. */
+  version: string | null;
+  /** For an unreported version: the oldest release the observed protocol implies, and the first that would report. */
+  versionRange: { min: string | null; below: string } | null;
+  relayAuth: string | null;
+  features: string[] | null;
+  compatibility: LinkCompatibilityVerdict;
+  reasons: string[];
+}
+
+function releaseParts(version: string): number[] {
+  return version.split(/[-+]/, 1)[0]!.split(".").map(part => Number(part));
+}
+
+export function compareReleases(a: string, b: string): number {
+  const left = releaseParts(a), right = releaseParts(b);
+  for (let i = 0; i < 3; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return Math.sign(diff);
+  }
+  return 0;
+}
+
+function sinceOf(id: string): string | null {
+  return LINK_PROTOCOL_RELEASES.find(release => release.id === id)?.since ?? null;
+}
+
+function relayAuthNumber(value: string): number {
+  return /^\d{1,4}$/.test(value) ? Number(value) : Number.NaN;
+}
+
+export function linkPeerStatus(local: LinkLocalPeer, entry: LinkPeerEntry): LinkPeerStatus {
+  const { observed, refused } = entry;
+  if (refused && (!observed || observed.observedAt <= refused.refusedAt)) {
+    const newerChild = relayAuthNumber(refused.relayAuth) > relayAuthNumber(local.relayAuth);
+    return {
+      observedAt: refused.refusedAt, version: null, versionRange: null, relayAuth: refused.relayAuth, features: null,
+      compatibility: "incompatible",
+      reasons: [`The Child speaks relay-auth/${refused.relayAuth} and this Home speaks relay-auth/${local.relayAuth}, so relayed requests are refused. Upgrade the ${newerChild ? "Home" : "Child"}.`],
+    };
+  }
+  if (!observed) {
+    return {
+      observedAt: null, version: null, versionRange: null, relayAuth: null, features: null,
+      compatibility: "unknown", reasons: ["No relayed request from this Child since the Home started."],
+    };
+  }
+  const base = { observedAt: observed.observedAt, relayAuth: observed.relayAuth, features: observed.features };
+  if (!observed.reported) {
+    return {
+      ...base, version: null,
+      versionRange: { min: sinceOf(`relay-auth/${observed.relayAuth}`), below: sinceOf(LINK_PEER_REPORT_FEATURE)! },
+      compatibility: "compatible",
+      reasons: [`relay-auth/${observed.relayAuth} matches. The Child does not report its version; it predates ${LINK_PEER_REPORT_FEATURE}.`],
+    };
+  }
+  if (observed.version === null || observed.features === null) {
+    // A reporting Child whose version or feature list was missing or rejected: the Home cannot tell what it uses.
+    return {
+      ...base, version: observed.version, versionRange: null, compatibility: "unknown",
+      reasons: [`relay-auth/${observed.relayAuth} matches, but the Child's ${observed.version === null && observed.features === null ? "version and feature list were" : observed.version === null ? "version was" : "feature list was"} missing or invalid, so its features cannot be checked.`],
+    };
+  }
+  const childOnly = observed.features.filter(id => !local.features.includes(id));
+  if (childOnly.length > 0) {
+    return {
+      ...base, version: observed.version, versionRange: null, compatibility: "degraded",
+      reasons: [`The Child (${observed.version}) uses ${childOnly.join(", ")}, which this Home (${local.version}) does not serve. Upgrade the Home.`],
+    };
+  }
+  return {
+    ...base, version: observed.version, versionRange: null, compatibility: "compatible",
+    reasons: [compareReleases(observed.version, local.version) === 0 ? "Same release as this Home."
+      : `relay-auth/${observed.relayAuth} matches and this Home (${local.version}) serves every feature the Child (${observed.version}) uses.`],
+  };
+}
+
+export function localLinkPeer(version: string, features: readonly string[]): LinkLocalPeer {
+  return { version, relayAuth: LINK_RELAY_AUTH_VERSION, features: [...features] };
+}