@bitkyc08/opencodex 2.90.0 → 2.91.0

package/src/cli/update-restart-home.ts

@@ -1,4 +1,4 @@
-import { realpathSync, statSync } from "node:fs";
+import { realpathSync, statSync, type BigIntStats } from "node:fs";
 import { readClientConnectionState } from "../client/state";
 import { readConfigDiagnostics } from "../config/diagnostics";
 import { getConfigDir } from "../config/paths";
@@ -6,23 +6,34 @@ import { currentCodexHome } from "../service/state";
 import { captureUpdateRestartServiceRecord, type UpdateRestartServiceRecord, type UpdateRestartServiceRecordDeps } from "./update-restart-service-record";
 import { probeUpdateRestartSupervision, type UpdateRestartSupervisionDeps } from "./update-restart-supervision";
 
+/**
+ * `fileId` is the exact identity ("dev:ino" from a bigint stat). `dev` and `ino` are doubles and
+ * cannot be: an NTFS file id carries the MFT sequence in its high bits, so above 2^53 a replacement
+ * directory with a nearby MFT index can round to the same `ino` as the one it replaced.
+ */
+export interface UpdateRestartDirectory { path: string; dev: number; ino: number; fileId: string }
+
 export interface UpdateRestartHome {
-  config: { path: string; dev: number; ino: number };
-  codex: { path: string; dev: number; ino: number };
+  config: UpdateRestartDirectory;
+  codex: UpdateRestartDirectory;
   revision: number;
   serviceRecord: UpdateRestartServiceRecord;
 }
 
-function physicalDirectory(path: string): UpdateRestartHome["config"] {
+export type UpdateRestartDirectoryStat = Pick<BigIntStats, "dev" | "ino" | "isDirectory">;
+
+function physicalDirectory(path: string, stat: (path: string) => UpdateRestartDirectoryStat): UpdateRestartDirectory {
   const canonical = realpathSync.native(path);
-  const stat = statSync(canonical);
-  if (!stat.isDirectory()) throw new Error("update_restart_home_unverified");
-  return { path: canonical, dev: stat.dev, ino: stat.ino };
+  const observed = stat(canonical);
+  if (!observed.isDirectory()) throw new Error("update_restart_home_unverified");
+  return { path: canonical, dev: Number(observed.dev), ino: Number(observed.ino), fileId: `${observed.dev}:${observed.ino}` };
 }
 
 export interface UpdateRestartHomeDeps {
   record?: UpdateRestartServiceRecordDeps;
   supervision?: UpdateRestartSupervisionDeps;
+  /** Test seam for the directory identity source; production reads a bigint stat. */
+  statDirectory?: (path: string) => UpdateRestartDirectoryStat;
 }
 
 /** Capture eligibility from the same bytes that supply the frozen fingerprint. */
@@ -32,7 +43,8 @@ export function readUpdateRestartHome(deps: UpdateRestartHomeDeps = {}): UpdateR
   if (owner.kind !== "none" || (state.kind === "state" && platform !== "darwin" && platform !== "linux")) {
     throw new Error("update_restart_owner_unverified");
   }
-  return { config: physicalDirectory(getConfigDir()), codex: physicalDirectory(currentCodexHome()), revision: owner.revision, serviceRecord };
+  const stat = deps.statDirectory ?? (path => statSync(path, { bigint: true }));
+  return { config: physicalDirectory(getConfigDir(), stat), codex: physicalDirectory(currentCodexHome(), stat), revision: owner.revision, serviceRecord };
 }
 
 export function assertUpdateRestartHome(expected: UpdateRestartHome, deadlineAt = Date.now() + 2000, deps: UpdateRestartHomeDeps = {}): void {

package/src/client/connect.ts

@@ -78,9 +78,14 @@ import { overlayHomeCodexSettings } from "../link/codex-settings";
 import {
   clearHomeCodexSettingsRecord,
   fetchHomeCodexSettings,
+  homeCodexSettingsReceipt,
+  readHomeCodexSettingsRecord,
   resolveHomeCodexSettings,
   recordHomeCodexSettings,
+  withLinkApply,
+  withdrawChangingHomeCodexSettingsRecord,
   writeHomeCodexSettingsRecord,
+  type HomeCodexSettingsRecord,
   type HomeCodexSettingsSource,
   type LinkHomeDeps,
 } from "./link-home";
@@ -122,6 +127,8 @@ export interface ClientConnectDeps {
   catalogCompatibility?: CatalogCompatibilityDeps;
   /** Link mode: how the Home's Codex settings are read (#6957). */
   linkHome?: LinkHomeDeps;
+  /** Link mode: the apply lock's path (OCX-6); defaults to `<configDir>/link/apply-lock.sqlite`. */
+  linkApplyLockPath?: string;
 }
 
 export interface RotateClientOptions {
@@ -549,9 +556,22 @@ function assertConnectingState(expectedTokenFingerprint?: string): void {
 }
 
 /** Enroll a client key, keeping its pending ownership visible until commit or rollback. */
+/**
+ * Connect this machine to a hub or, with `transport: "link"`, to a Remote Link Home. A link
+ * connect holds the apply lock throughout (OCX-6), because it applies the Home's Codex settings
+ * and records that apply exactly as `ocx sync` does.
+ */
 export async function connectClient(
   options: ConnectOptions,
   deps: ClientConnectDeps = {},
+): Promise<OcxClientConnectionConfig> {
+  if ((options.transport ?? "hub") !== "link") return connectClientUnlocked(options, deps);
+  return withLinkApply(() => connectClientUnlocked(options, deps), deps.linkApplyLockPath);
+}
+
+async function connectClientUnlocked(
+  options: ConnectOptions,
+  deps: ClientConnectDeps = {},
 ): Promise<OcxClientConnectionConfig> {
   deps.signal?.throwIfAborted();
   const rawFetch = deps.fetchImpl ?? fetch;
@@ -755,11 +775,17 @@ export async function connectClient(
       commitClientConnection(connection);
       committed = true;
     }), deps.lifecycleLockDeps);
-    // Recorded only when the injection that applied it ran (not with --no-sync).
+    // Recorded only when the injection that applied it ran (not with --no-sync). The connection is
+    // already committed, so a failed record write must not reach the rollback below: it is a
+    // warning, and `ocx status` reports no recorded apply until `ocx sync` writes one.
     if (homeSettings?.kind === "fresh" && linkMetadata && injectionCommitted) {
       try {
-        writeHomeCodexSettingsRecord({ linkId: linkMetadata.linkId, fetchedAt: now, document: homeSettings.document });
-      } catch { /* the next sync records it; the applied config is already committed */ }
+        writeHomeCodexSettingsRecord(homeCodexSettingsReceipt(
+          linkMetadata.linkId, homeSettings.document, now, (deps.now ?? (() => new Date()))().toISOString(), null,
+        ));
+      } catch {
+        console.warn("Warning: the Home's Codex settings were applied, but the apply record was not written; run 'ocx sync' to record it.");
+      }
     }
     return connection;
   } catch (error) {
@@ -804,10 +830,34 @@ export async function connectClient(
   }
 }
 
+export interface ConnectedSyncResult {
+  catalogWritten: boolean;
+  cacheSynced: boolean;
+  injected: boolean;
+  stale: boolean;
+  homeSettings?: HomeCodexSettingsSource;
+  /** The apply record this sync committed or kept (link Child with Home settings only). */
+  appliedRecord?: HomeCodexSettingsRecord;
+  /** The Home's settings were injected but their record could not be written (OCX-6). */
+  applyRecordFailed?: true;
+}
+
+/**
+ * Refresh the catalog and Codex config from the hub or Home. Every sync holds the apply lock
+ * (OCX-6), so a sync that finds a link connection inside, whatever an earlier unlocked read said,
+ * never interleaves with another apply, and its record names what its own injection wrote.
+ */
 export async function syncConnectedClient(
+  options: { restartCodex?: boolean } = {},
+  deps: ClientConnectDeps = {},
+): Promise<ConnectedSyncResult> {
+  return withLinkApply(() => syncConnectedClientUnlocked(options, deps), deps.linkApplyLockPath);
+}
+
+async function syncConnectedClientUnlocked(
   _options: { restartCodex?: boolean } = {},
   deps: ClientConnectDeps = {},
-): Promise<{ catalogWritten: boolean; cacheSynced: boolean; injected: boolean; stale: boolean; homeSettings?: HomeCodexSettingsSource }> {
+): Promise<ConnectedSyncResult> {
   if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
   const initial = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
     assertNoClientDisconnectPending();
@@ -853,12 +903,18 @@ export async function syncConnectedClient(
   };
   let injected = false;
   let homeSettings: HomeCodexSettingsSource | undefined;
+  let appliedRecord: HomeCodexSettingsRecord | undefined;
+  let applyRecordFailed = false;
   if (next.selectedClients.includes("codex")) {
     let config = loadConfig();
     // #6957: a link Child applies the Home's OpenCodex-owned Codex settings with the catalog.
     if (isLinkConnection(next)) {
       homeSettings = await resolveHomeCodexSettings(next, initial.token.token, deps.linkHome);
       if (homeSettings.source !== "local") config = overlayHomeCodexSettings(config, homeSettings.document.settings);
+      // About to write different settings: until their record commits, report no applied digest
+      // rather than the previous one (OCX-6). A failed injection then reads "unknown", never a
+      // digest of values Codex no longer has or never got.
+      if (homeSettings.source === "home" && next.link) withdrawChangingHomeCodexSettingsRecord(next.link.linkId, homeSettings.document);
     }
     const result = await injectCodexConfig(config.port, { ...config, syncResumeHistory: false }, {
       routingTarget: routingTarget(next.serverUrl, isLinkConnection(next) ? config.port : undefined, config), catalogPath: DEFAULT_CATALOG_PATH,
@@ -866,14 +922,34 @@ export async function syncConnectedClient(
     });
     if (!result.success || result.status === "skipped") throw new Error(result.message);
     injected = true;
-    if (homeSettings && next.link) recordHomeCodexSettings(next.link.linkId, homeSettings);
+    if (homeSettings && next.link) {
+      const linkId = next.link.linkId;
+      const settings = homeSettings;
+      try {
+        appliedRecord = withClientLifecycleSync(() => {
+          beforeClientWrite();
+          return recordHomeCodexSettings(linkId, settings, deps.now) ?? readHomeCodexSettingsRecord(linkId) ?? undefined;
+        }, deps.lifecycleLockDeps);
+      } catch (error) {
+        // An ownership change is not a disk problem: report it as itself.
+        if (error instanceof Error && (error.message === "client_token_changed" || error.message === "client_connection_changed")) throw error;
+        // The injection committed, so the cache refresh below still runs; the caller reports this.
+        try { clearHomeCodexSettingsRecord(); } catch { /* status already reads no recorded apply or reports the write */ }
+        applyRecordFailed = true;
+      }
+    }
   }
   const cacheSynced = withClientLifecycleSync(() => {
     beforeClientWrite();
     // Cache invalidation acquires K itself (N -> K -> C); never call it while C is held.
     return invalidateCodexModelsCache({ allowWhenDesiredDisabled: true });
   }, deps.lifecycleLockDeps);
-  return { catalogWritten: downloaded !== undefined, cacheSynced, injected, stale, ...(homeSettings ? { homeSettings } : {}) };
+  return {
+    catalogWritten: downloaded !== undefined, cacheSynced, injected, stale,
+    ...(homeSettings ? { homeSettings } : {}),
+    ...(appliedRecord ? { appliedRecord } : {}),
+    ...(applyRecordFailed ? { applyRecordFailed } : {}),
+  };
 }
 
 /**

package/src/client/home-unreachable.ts

@@ -0,0 +1,16 @@
+/**
+ * OCX-11: the stable answer a Remote Link Child or Hub client gives when its Home cannot be
+ * reached. The relay keeps its status, `error` string and retry semantics; `code` and
+ * `message` are added so callers (Codex, GOAT) read one contract. The client runtime has no
+ * provider dispatch, so nothing is ever served from this device's local providers. Whether GOAT
+ * may move the work to them is the Home's per-device `fallback.devices.<id>.localFallback`.
+ */
+export const HOME_UNREACHABLE_CODE = "home_unreachable";
+
+export const HOME_UNREACHABLE_MESSAGE = "The Home is unreachable, and OpenCodex did not serve this request "
+  + "from this device's local providers. Retry once the Home is back. Allowing local fallback for this "
+  + "device is set on the Home: ocx fallback local on --device <id>.";
+
+export function homeUnreachableBody(error: string): { error: string; code: string; message: string } {
+  return { error, code: HOME_UNREACHABLE_CODE, message: HOME_UNREACHABLE_MESSAGE };
+}

package/src/client/hub-relay.ts

@@ -1,4 +1,5 @@
 import { stripMachineAuthHeaders } from "./machine-auth";
+import { homeUnreachableBody } from "./home-unreachable";
 
 export interface HubRelayTarget {
   managementUrl: string;
@@ -73,6 +74,11 @@ function relayError(status: number, error: string): Response {
   return Response.json({ error }, { status });
 }
 
+/** The Hub did not answer (OCX-11 `home_unreachable`); the 502 status is kept. */
+function hubUnreachable(): Response {
+  return Response.json(homeUnreachableBody("hub relay unavailable"), { status: 502 });
+}
+
 function canonicalOrigin(value: string): string | null {
   try {
     const url = new URL(value);
@@ -275,12 +281,12 @@ export async function relayHubManagementRequest(
     });
   } catch {
     cleanup();
-    return relayError(502, "hub relay unavailable");
+    return hubUnreachable();
   }
   if (signal.aborted) {
     cleanup();
     try { await upstream.body?.cancel(); } catch { /* best effort */ }
-    return relayError(502, "hub relay unavailable");
+    return hubUnreachable();
   }
   if (upstream.status >= 300 && upstream.status < 400) {
     cleanup();

package/src/client/link-home.ts

@@ -13,9 +13,11 @@ import { readBoundedResponseBytes } from "../lib/bounded-body";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import { hardenSecretDir } from "../lib/windows-secret-acl";
 import {
+  codexSettingsDigest,
   parseHomeCodexSettingsDocument,
   type HomeCodexSettingsDocument,
 } from "../link/codex-settings";
+import { LINK_CHILD_PARITY_PATH, type LinkChildParityReport } from "../link/child-parity";
 import {
   LINK_CODEX_SETTINGS_PATH,
   LINK_MANAGEMENT_PREFIX,
@@ -23,10 +25,17 @@ import {
 } from "../link/management-routes";
 import { linkDir } from "../link/paths";
 import type { OcxClientConnectionConfig } from "../types";
+import { withClientLifecycle } from "./lifecycle-lock";
 import { fetchBoundLinkRelay } from "./link-relay-transport";
 import { readClientLinkState, type ClientLinkState } from "./link-state";
 
 const RECORD_MAX_BYTES = 64 * 1024;
+
+function isIsoTimestamp(value: unknown): value is string {
+  if (typeof value !== "string" || value.length !== 24) return false;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
 const SETTINGS_MAX_BYTES = 64 * 1024;
 const READ_TIMEOUT_MS = 10_000;
 
@@ -42,6 +51,11 @@ export type LinkHomeConnection = Pick<OcxClientConnectionConfig, "transport" | "
 export interface HomeCodexSettingsRecord {
   linkId: string;
   fetchedAt: string;
+  /**
+   * When this Child first applied these settings (OCX-6, P5). A re-apply of the same digest for
+   * the same link keeps it, so an idempotent `ocx sync` never makes a fresh runtime look stale.
+   */
+  appliedAt: string;
   document: HomeCodexSettingsDocument;
 }
 
@@ -69,7 +83,9 @@ export function readHomeCodexSettingsRecord(linkId: string, path = homeCodexSett
     const record = raw as Record<string, unknown>;
     if (record.linkId !== linkId || typeof record.fetchedAt !== "string" || Number.isNaN(Date.parse(record.fetchedAt))) return null;
     const document = parseHomeCodexSettingsDocument(record.document);
-    return document ? { linkId, fetchedAt: record.fetchedAt, document } : null;
+    // Records written before OCX-6 carry no apply time; their read time is the closest one.
+    const appliedAt = isIsoTimestamp(record.appliedAt) ? record.appliedAt : record.fetchedAt;
+    return document ? { linkId, fetchedAt: record.fetchedAt, appliedAt, document } : null;
   } catch {
     return null;
   }
@@ -89,6 +105,59 @@ export function clearHomeCodexSettingsRecord(path = homeCodexSettingsPath()): vo
   try { unlinkSync(path); } catch (error) { if (!isMissingPathError(error)) throw error; }
 }
 
+/**
+ * The record an apply of `document` produces: the apply time is `appliedAt` unless the previous
+ * record is for the same link and the same settings digest, in which case it is kept.
+ */
+export function homeCodexSettingsReceipt(
+  linkId: string,
+  document: HomeCodexSettingsDocument,
+  fetchedAt: string,
+  appliedAt: string,
+  previous: HomeCodexSettingsRecord | null = readHomeCodexSettingsRecord(linkId),
+): HomeCodexSettingsRecord {
+  const unchanged = previous !== null && previous.linkId === linkId
+    && codexSettingsDigest(previous.document.settings) === codexSettingsDigest(document.settings);
+  return { linkId, fetchedAt, appliedAt: unchanged ? previous.appliedAt : appliedAt, document };
+}
+
+export function linkApplyLockPath(): string {
+  return join(linkDir(), "apply-lock.sqlite");
+}
+
+/**
+ * Before an apply writes settings that differ from the recorded ones, withdraw the record, so a
+ * failed injection or record write reads as "no recorded apply" instead of the previous digest
+ * (OCX-6). Re-applying the same settings keeps it. Returns whether the record was withdrawn.
+ */
+export function withdrawChangingHomeCodexSettingsRecord(linkId: string, document: HomeCodexSettingsDocument): boolean {
+  const previous = readHomeCodexSettingsRecord(linkId);
+  if (!previous || codexSettingsDigest(previous.document.settings) === codexSettingsDigest(document.settings)) return false;
+  clearHomeCodexSettingsRecord();
+  return true;
+}
+
+/**
+ * Serialize applies of the Home's settings on this Child, from the Home read through the Codex
+ * injection to the record write, so a receipt always names the settings the injection wrote.
+ * Outermost in the client lock order (before N, L and C); a second apply fails fast.
+ */
+export async function withLinkApply<T>(work: () => Promise<T>, lockPath: string = linkApplyLockPath()): Promise<T> {
+  const dir = linkDir();
+  assertNotRealHomeUnderTest(join(dir, ".."));
+  // Only a refusal of the apply lock itself means "another apply"; an error from inside `work`
+  // (including a busy ordinary lifecycle lock) passes through as itself.
+  let entered = false;
+  try {
+    return await withClientLifecycle(() => { entered = true; return work(); }, { lockPath });
+  } catch (error) {
+    if (!entered && error instanceof Error && error.message === "client_lifecycle_busy") {
+      throw new Error("another Home settings apply is in progress on this machine; retry when it finishes");
+    }
+    throw error;
+  }
+}
+
 /**
  * The Home's name as this Child knows it: the SSH alias of a Child-initiated link, else the
  * host name the Home published with its Codex settings, else null ("its Home").
@@ -239,10 +308,54 @@ export async function resolveHomeCodexSettings(
     : { source: "local", reason: fetched.reason };
 }
 
-/** Record settings a successful injection applied. Best effort: the config is already written. */
-export function recordHomeCodexSettings(linkId: string, settings: HomeCodexSettingsSource): void {
-  if (settings.source !== "home") return;
+/**
+ * Record settings a successful injection applied and return the committed record; null when the
+ * source was not a fresh Home read. A write failure throws: the caller reports it, because
+ * `ocx status` and the Home read this record as the proof of what was applied.
+ */
+export function recordHomeCodexSettings(
+  linkId: string,
+  settings: HomeCodexSettingsSource,
+  now: () => Date = () => new Date(),
+): HomeCodexSettingsRecord | null {
+  if (settings.source !== "home") return null;
+  const record = homeCodexSettingsReceipt(linkId, settings.document, settings.fetchedAt, now().toISOString());
+  writeHomeCodexSettingsRecord(record);
+  return record;
+}
+
+/**
+ * Tell the Home what this Child last applied and when its runtime started (OCX-6). Resolves to
+ * `"accepted"`, `"unsupported"` for a Home that predates the route, or `"failed"`.
+ */
+export async function sendLinkChildParityReport(
+  connection: LinkHomeConnection,
+  admissionKey: string,
+  report: LinkChildParityReport,
+  deps: LinkHomeDeps = {},
+): Promise<"accepted" | "unsupported" | "failed"> {
+  let response: Response;
   try {
-    writeHomeCodexSettingsRecord({ linkId, fetchedAt: settings.fetchedAt, document: settings.document });
-  } catch { /* the next sync records it */ }
+    const target = linkTarget(connection, admissionKey);
+    const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_CHILD_PARITY_PATH}`;
+    const body = JSON.stringify(report);
+    const request: RequestInit = {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${admissionKey}`,
+        "content-type": "application/json",
+        "content-length": String(Buffer.byteLength(body)),
+      },
+      body,
+      redirect: "manual",
+      signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS),
+    };
+    response = deps.fetchImpl ? await deps.fetchImpl(destination, request) : await fetchBoundLinkRelay(target, destination, request);
+  } catch {
+    return "failed";
+  }
+  try { await response.body?.cancel(); } catch { /* best effort */ }
+  if (response.status === 404) return "unsupported";
+  return response.status === 204 ? "accepted" : "failed";
 }

package/src/client/link-parity-reporter.ts

@@ -0,0 +1,107 @@
+/**
+ * The Child half of the OCX-6 report: tell the Home, over the link, when this Child last applied
+ * the Home's Codex settings, which digest it applied and when this runtime started.
+ *
+ * Runs in a linked client runtime. The first report goes out shortly after start (the tunnel may
+ * still be coming up, so failures back off: 2, 5, 15, 30 then 60 seconds), and then once a minute,
+ * so a Home that restarted and forgot the report learns it again within a minute. A Home that
+ * predates the route (404) is not asked again. Timers are unref'd and never keep the process alive.
+ */
+import { codexSettingsDigest } from "../link/codex-settings";
+import type { LinkChildParityReport } from "../link/child-parity";
+import type { OcxClientConnectionConfig } from "../types";
+import { readHomeCodexSettingsRecord, sendLinkChildParityReport, type HomeCodexSettingsRecord } from "./link-home";
+
+export const LINK_PARITY_RETRY_MS = [2_000, 5_000, 15_000, 30_000, 60_000] as const;
+export const LINK_PARITY_PERIOD_MS = 60_000;
+
+/** Process-wide, so a reporter rebuilt by a restart rollback keeps counting up (see `sequence`). */
+let reportSequence = 0;
+function nextReportSequence(): number {
+  reportSequence += 1;
+  return reportSequence;
+}
+
+export interface LinkParityReporter {
+  start(): void;
+  stop(): void;
+}
+
+export interface LinkParityReporterDeps {
+  connection: OcxClientConnectionConfig;
+  linkKey: () => string | null;
+  /** ISO start time of this runtime. */
+  runtimeStartedAt: string;
+  readRecord?: (linkId: string) => HomeCodexSettingsRecord | null;
+  send?: typeof sendLinkChildParityReport;
+  setTimer?: (callback: () => void, ms: number) => unknown;
+  clearTimer?: (timer: unknown) => void;
+}
+
+/** The report for this Child's current record; null without link metadata. */
+export function linkChildParityReport(
+  connection: OcxClientConnectionConfig,
+  runtimeStartedAt: string,
+  record: HomeCodexSettingsRecord | null,
+  sequence: number = nextReportSequence(),
+): LinkChildParityReport | null {
+  const linkId = connection.link?.linkId;
+  const started = Date.parse(runtimeStartedAt);
+  if (!linkId || !Number.isFinite(started)) return null;
+  const applied = record ? Date.parse(record.appliedAt) : Number.NaN;
+  return Number.isFinite(applied)
+    ? { linkId, lastApplyAt: applied, runtimeStartedAt: started, appliedCodexSettingsDigest: codexSettingsDigest(record!.document.settings), sequence }
+    : { linkId, lastApplyAt: null, runtimeStartedAt: started, appliedCodexSettingsDigest: null, sequence };
+}
+
+export function createLinkParityReporter(deps: LinkParityReporterDeps): LinkParityReporter {
+  const readRecord = deps.readRecord ?? readHomeCodexSettingsRecord;
+  const send = deps.send ?? sendLinkChildParityReport;
+  const setTimer = deps.setTimer ?? ((callback: () => void, ms: number) => {
+    const timer = setTimeout(callback, ms);
+    if (typeof timer === "object" && "unref" in timer) timer.unref();
+    return timer;
+  });
+  const clearTimer = deps.clearTimer ?? (timer => clearTimeout(timer as ReturnType<typeof setTimeout>));
+  let timer: unknown;
+  let stopped = true;
+  let failures = 0;
+
+  const schedule = (ms: number) => {
+    if (stopped) return;
+    timer = setTimer(() => { void tick(); }, ms);
+  };
+
+  const tick = async (): Promise<void> => {
+    timer = undefined;
+    if (stopped) return;
+    const key = deps.linkKey();
+    const linkId = deps.connection.link?.linkId;
+    let record: HomeCodexSettingsRecord | null = null;
+    try { record = linkId ? readRecord(linkId) : null; } catch { record = null; }
+    const report = linkChildParityReport(deps.connection, deps.runtimeStartedAt, record);
+    const outcome = key && report ? await send(deps.connection, key, report).catch(() => "failed" as const) : "failed";
+    if (outcome === "unsupported") { stopped = true; return; }
+    if (outcome === "accepted") {
+      failures = 0;
+      schedule(LINK_PARITY_PERIOD_MS);
+      return;
+    }
+    failures = Math.min(failures + 1, LINK_PARITY_RETRY_MS.length - 1);
+    schedule(LINK_PARITY_RETRY_MS[failures]!);
+  };
+
+  return {
+    start() {
+      if (!stopped) return;
+      stopped = false;
+      failures = 0;
+      schedule(LINK_PARITY_RETRY_MS[0]);
+    },
+    stop() {
+      stopped = true;
+      if (timer !== undefined) clearTimer(timer);
+      timer = undefined;
+    },
+  };
+}

package/src/client/link-relay-transport.ts

@@ -4,6 +4,9 @@ import { Readable } from "node:stream";
 import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
 import { serviceApiTokenFingerprint } from "../lib/service-secrets";
 import { clearableDeadline } from "../lib/abort";
+import { packageVersion } from "../lib/package-version";
+import { linkPeerReportHeaders } from "../link/peer-report";
+import { buildPeerFeatures } from "../remote/features";
 import {
   LINK_RELAY_AUTH_PATH, LINK_RELAY_AUTH_TIMEOUT_MS, LINK_RELAY_AUTH_VERSION,
   LINK_RELAY_SESSION_HEADER, linkRelayChallenge, linkRelayProofMatches,
@@ -148,6 +151,8 @@ async function responseOnConnection(incoming: IncomingMessage, agent: SingleConn
   }, { highWaterMark: 0 }), { status, headers });
 }
 
+let peerReport: Record<string, string> | undefined;
+
 /** Authenticate and stream one request on the SAME socket; never fall back to an ordinary fetch. */
 export async function fetchBoundLinkRelay(target: BoundLinkRelayTarget, destination: string, init: RequestInit): Promise<Response> {
   if (!target.linkId || !target.apiKeyId) throw new LinkRelayAuthenticationError();
@@ -160,7 +165,9 @@ export async function fetchBoundLinkRelay(target: BoundLinkRelayTarget, destinat
   const agent = new SingleConnectionAgent({ keepAlive: true, maxSockets: 1, maxFreeSockets: 1 });
   const deadline = clearableDeadline(LINK_RELAY_AUTH_TIMEOUT_MS, init.signal ?? undefined);
   try {
-    const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal }, agent);
+    // The challenge also carries this Child's version and features for the Home's link status.
+    peerReport ??= linkPeerReportHeaders(packageVersion("0.0.0"), buildPeerFeatures());
+    const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal, headers: peerReport }, agent);
     const socket = agent.socket;
     const proof = response.headers["x-opencodex-link-proof"];
     if (response.statusCode !== 204 || typeof proof !== "string" || !linkRelayProofMatches(proof, challenge.expected)) {

package/src/client/link-relay.ts

@@ -1,4 +1,5 @@
 import { fetchBoundLinkRelay, LinkRelayAuthenticationError } from "./link-relay-transport";
+import { homeUnreachableBody } from "./home-unreachable";
 import {
   boundedRelayResponseStream,
   filterRelayHeaders,
@@ -112,6 +113,29 @@ function jsonError(status: number, error: string, retry = false): Response {
   return Response.json({ error }, { status, headers });
 }
 
+/** A retryable 503 for a Home this Child cannot reach (OCX-11 `home_unreachable`). */
+function homeUnreachable(error: string): Response {
+  return Response.json(homeUnreachableBody(error), {
+    status: 503,
+    headers: { "Retry-After": String(LINK_RELAY_RETRY_AFTER_SECONDS) },
+  });
+}
+
+/**
+ * The peer answered but the connection-bound relay authentication failed. That is not a Home
+ * outage (an unrecognized protocol needs an upgrade or a re-link), so it must never read as
+ * `home_unreachable`, which GOAT's device-local fallback keys on. The status and Retry-After it
+ * carried before OCX-11 are kept: a lost bound socket can succeed on a fresh connection.
+ */
+export const LINK_RELAY_AUTH_FAILED_CODE = "link_relay_auth_failed";
+
+function relayAuthenticationFailed(error: string): Response {
+  return Response.json({ error, code: LINK_RELAY_AUTH_FAILED_CODE }, {
+    status: 503,
+    headers: { "Retry-After": String(LINK_RELAY_RETRY_AFTER_SECONDS) },
+  });
+}
+
 export function linkRelayDestination(url: URL, target: Pick<LinkRelayTarget, "tunnelPort">): string {
   if (!isLinkPort(target.tunnelPort)) {
     throw new RangeError("invalid link tunnel port");
@@ -369,7 +393,7 @@ export async function relayLinkDataRequest(
   const tunnelUnavailable = async (): Promise<Response> => {
     cleanup();
     try { await body?.cancel(); } catch { /* best effort */ }
-    return jsonError(503, "link tunnel unavailable", true);
+    return homeUnreachable("link tunnel unavailable");
   };
   const readyForFetch = async (): Promise<boolean> => {
     if (!tunnel) return false;
@@ -393,7 +417,7 @@ export async function relayLinkDataRequest(
       if (error instanceof LinkRelayAuthenticationError) {
         cleanup();
         try { await body?.cancel(); } catch { /* an upload might already be drained */ }
-        return jsonError(503, error.message, true);
+        return relayAuthenticationFailed(error.message);
       }
       if (bodyOverflow) {
         cleanup();
@@ -408,7 +432,7 @@ export async function relayLinkDataRequest(
   if (relayAbort.signal.aborted) {
     cleanup();
     try { await upstream.body?.cancel(); } catch { /* best effort */ }
-    return jsonError(503, "link tunnel unavailable", true);
+    return homeUnreachable("link tunnel unavailable");
   }
 
   const sse = isSse(upstream.headers);