@bitkyc08/opencodex 2.90.0 → 2.92.0

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-ingress.ts

@@ -76,7 +76,7 @@ function liftRequestIdleTimer(req: Request, server: Pick<Server<unknown>, "timeo
  *   fetch, so a rebinding or cross-site browser page cannot reach the Home through this port.
  * - Without the committed link key nothing is fetched, and the caller gets
  *   `503 link_credential_unavailable`.
- * - `/readyz` stays local: it reports this listener, not the tunnel.
+ * - `/readyz` stays local and is never relayed; the listener answers it from `link-readiness.ts`.
  * - A relayed request is exempt from the listener's idle limit, like a standalone data route.
  */
 export function handleLinkIngress(

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-readiness.ts

@@ -0,0 +1,97 @@
+/**
+ * Whether a Remote Link Child can serve relayed requests right now, for its `GET /readyz`.
+ *
+ * `/healthz` keeps meaning "this process answers". A Child whose tunnel is down still answers it,
+ * yet every relayed turn fails with 503, so readiness is where that shows: not ready, with one
+ * fixed reason word. Nothing here carries ssh output, host names, ports or keys.
+ *
+ * - A Child-initiated link reads its own tunnel supervisor; no network traffic.
+ * - A Home-initiated link has no local tunnel to inspect (the Home runs `ssh -R`), so it runs
+ *   the credential-free relay preflight through the tunnel port. One preflight runs at a time, a
+ *   verdict is reused for `LINK_READINESS_TTL_MS`, and a request waits at most
+ *   `LINK_READINESS_WAIT_MS` for a running preflight before it answers `link_unverified`. An
+ *   unauthenticated caller can therefore cause at most one preflight per TTL.
+ */
+import { LINK_RELAY_AUTH_TIMEOUT_MS } from "../link/relay-auth";
+import { isLinkPort } from "../link/ports";
+import { probeLinkRelayPreflight, type BoundLinkRelayTarget, type LinkRelayPreflightResult } from "./link-relay-transport";
+import type { ClientLinkSupervisorStatus } from "./link-tunnel";
+
+export type LinkReadinessReason =
+  | "tunnel_idle" | "tunnel_connecting" | "tunnel_failed" | "tunnel_unavailable" | "sidecar_invalid"
+  | "home_unreachable" | "home_unauthorized" | "link_auth_failed" | "link_credential_unavailable"
+  | "link_unverified";
+
+export type LinkReadiness = { ready: true } | { ready: false; reason: LinkReadinessReason };
+
+export const LINK_READINESS_TTL_MS = 5_000;
+export const LINK_READINESS_WAIT_MS = 500;
+
+const READY: LinkReadiness = { ready: true };
+const notReady = (reason: LinkReadinessReason): LinkReadiness => ({ ready: false, reason });
+
+/**
+ * A Child-initiated link from its supervisor. The keyed probe the supervisor runs every 30 seconds
+ * while connected is display-only for the tunnel, but a Home that stopped answering or refuses the
+ * key cannot serve a turn, so readiness follows it. A Home whose own startup readiness is pending
+ * still serves relayed requests (the probe's `home_not_ready`), so that reads ready.
+ */
+export function clientInitiatedLinkReadiness(status: ClientLinkSupervisorStatus): LinkReadiness {
+  if (status.kind === "failed") return notReady("sidecar_invalid");
+  if (status.kind === "stopped") return notReady("tunnel_idle");
+  const { state, probe } = status;
+  if (state.kind === "connected") {
+    if (probe === "home_unreachable") return notReady("home_unreachable");
+    if (probe === "unauthorized") return notReady("home_unauthorized");
+    return READY;
+  }
+  if (state.kind === "connecting" || state.kind === "reconnecting") return notReady("tunnel_connecting");
+  if (state.kind === "failed") return notReady(state.inFlight ? "tunnel_connecting" : "tunnel_failed");
+  return notReady("tunnel_idle");
+}
+
+function fromPreflight(result: LinkRelayPreflightResult): LinkReadiness {
+  if (result === "ok") return READY;
+  return notReady(result === "unreachable" ? "home_unreachable" : "link_auth_failed");
+}
+
+export interface HomeInitiatedLinkReadinessDeps {
+  target: Omit<BoundLinkRelayTarget, "admissionKey">;
+  linkKey: () => string | null;
+  probe?: (target: BoundLinkRelayTarget, options: { timeoutMs: number }) => Promise<LinkRelayPreflightResult>;
+  now?: () => number;
+  /** Resolves after `ms`; the wait for a running preflight. */
+  delay?: (ms: number) => Promise<void>;
+}
+
+/** The readiness of a Home-initiated link, from a shared, rate-limited relay preflight. */
+export function createHomeInitiatedLinkReadiness(deps: HomeInitiatedLinkReadinessDeps): () => Promise<LinkReadiness> {
+  const probe = deps.probe ?? probeLinkRelayPreflight;
+  const now = deps.now ?? Date.now;
+  const delay = deps.delay ?? (ms => new Promise<void>(resolve => {
+    const timer = setTimeout(resolve, ms);
+    (timer as { unref?: () => void }).unref?.();
+  }));
+  let last: { at: number; verdict: LinkReadiness } | undefined;
+  let flight: Promise<LinkReadiness> | undefined;
+  const run = (admissionKey: string): Promise<LinkReadiness> => {
+    flight ??= probe({ ...deps.target, admissionKey }, { timeoutMs: LINK_RELAY_AUTH_TIMEOUT_MS })
+      .then(fromPreflight, () => notReady("home_unreachable"))
+      .then(verdict => {
+        last = { at: now(), verdict };
+        return verdict;
+      })
+      .finally(() => { flight = undefined; });
+    return flight;
+  };
+  return async () => {
+    if (!isLinkPort(deps.target.tunnelPort)) return notReady("tunnel_unavailable");
+    let admissionKey: string | null;
+    try { admissionKey = deps.linkKey(); } catch { admissionKey = null; }
+    if (!admissionKey) return notReady("link_credential_unavailable");
+    const at = now();
+    if (last && at >= last.at && at - last.at < LINK_READINESS_TTL_MS) return last.verdict;
+    const unverified = notReady("link_unverified");
+    return await Promise.race([run(admissionKey), delay(LINK_READINESS_WAIT_MS).then(() => unverified)]);
+  };
+}