@bitkyc08/opencodex 2.90.0 → 2.92.0

package/src/cli/launcher-context.ts

@@ -24,7 +24,11 @@ export type TrustedNodeLaunchContext = {
     codexCliPath: string | null;
     path: string | null;
     pathExt: string | null;
+    home: string | null;
+    nodePath: string | null;
     managerRoots: CodexCliVersionManagerRoots | null;
+    transportEnv: Readonly<Record<string, string>>;
+    arch: NodeJS.Architecture | null;
     configDir: string;
   }> | null;
 };
@@ -50,6 +54,27 @@ function parseVersionManagerRoots(value: unknown): CodexCliVersionManagerRoots |
   return Object.freeze(Object.fromEntries(entries)) as CodexCliVersionManagerRoots;
 }
 
+function parseTransportEnv(value: unknown): Readonly<Record<string, string>> | undefined {
+  // Older snapshots convey no transport settings. Never fill them from Bun's ambient env.
+  if (value === undefined) return Object.freeze({});
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const entries = Object.entries(value);
+  if (entries.some(([name, setting]) => !CODEX_CLI_TRANSPORT_ENV_KEYS.includes(name.toLowerCase())
+    || typeof setting !== "string" || setting.length > 32 * 1024)) return undefined;
+  return Object.freeze(Object.fromEntries(entries));
+}
+
+const NODE_ARCHITECTURES: ReadonlySet<string> = new Set<NodeJS.Architecture>([
+  "arm", "arm64", "ia32", "loong64", "mips", "mipsel", "ppc64", "riscv64", "s390x", "x64",
+]);
+
+function parseLauncherArch(value: unknown): NodeJS.Architecture | null | undefined {
+  // Older snapshots predate the field; absent stays null (Bun's own arch is the
+  // pre-existing fallback). Any other non-architecture value is untrusted.
+  if (value === undefined || value === null) return null;
+  return typeof value === "string" && NODE_ARCHITECTURES.has(value) ? value as NodeJS.Architecture : undefined;
+}
+
 /** Consume the internal proof before normal CLI argument parsing. */
 export function initializeNodeLauncherContext(
   argv: string[] = process.argv,
@@ -70,7 +95,7 @@ export function initializeNodeLauncherContext(
   delete env.OCX_PRE_BUN_ANTHROPIC_ENV;
   trustedContext = null;
 
-  if (proofArgs.length !== 1 || !raw || raw.length > 64 * 1024) return null;
+  if (proofArgs.length !== 1 || !raw || raw.length > NODE_LAUNCH_CONTEXT_MAX_CHARS) return null;
   const proof = proofArgs[0]!;
   if (!isLaunchProof(proof)) return null;
 
@@ -95,6 +120,12 @@ export function initializeNodeLauncherContext(
     const managerRoots = inspection && typeof inspection === "object" && !Array.isArray(inspection)
       ? parseVersionManagerRoots((inspection as Record<string, unknown>).managerRoots)
       : null;
+    const transportEnv = inspection && typeof inspection === "object" && !Array.isArray(inspection)
+      ? parseTransportEnv((inspection as Record<string, unknown>).transportEnv)
+      : undefined;
+    const arch = inspection && typeof inspection === "object" && !Array.isArray(inspection)
+      ? parseLauncherArch((inspection as Record<string, unknown>).arch)
+      : undefined;
     const codexCliInspectionEnv = inspection === null || inspection === undefined
       ? null
       : inspection && typeof inspection === "object" && !Array.isArray(inspection)
@@ -102,15 +133,27 @@ export function initializeNodeLauncherContext(
           const value = (inspection as Record<string, unknown>)[key];
           return value === null || typeof value === "string";
         })
+        // Older launchers predate the lookup-seed slots; absent stays null so
+        // the fallback lane simply remains unverifiable rather than untrusted.
+        && ["home", "nodePath"].every(key => {
+          const value = (inspection as Record<string, unknown>)[key];
+          return value === undefined || value === null || typeof value === "string";
+        })
         && typeof (inspection as Record<string, unknown>).configDir === "string"
         && (inspection as Record<string, string>).configDir.length > 0
         && (inspection as Record<string, string>).configDir.length <= 32 * 1024
         && managerRoots !== undefined
+        && transportEnv !== undefined
+        && arch !== undefined
         ? Object.freeze({
             codexCliPath: (inspection as Record<string, string | null>).codexCliPath ?? null,
             path: (inspection as Record<string, string | null>).path ?? null,
             pathExt: (inspection as Record<string, string | null>).pathExt ?? null,
+            home: (inspection as Record<string, string | null>).home ?? null,
+            nodePath: (inspection as Record<string, string | null>).nodePath ?? null,
             managerRoots,
+            transportEnv,
+            arch,
             configDir: (inspection as Record<string, string>).configDir,
           })
         : undefined;
@@ -125,4 +168,8 @@ export function initializeNodeLauncherContext(
 export function trustedNodeLauncherContext(): TrustedNodeLaunchContext | null {
   return trustedContext;
 }
-import { CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS } from "../update/codex-cli-update-launch-policy.mjs";
+import {
+  CODEX_CLI_TRANSPORT_ENV_KEYS,
+  CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS,
+  NODE_LAUNCH_CONTEXT_MAX_CHARS,
+} from "../update/codex-cli-update-launch-policy.mjs";

package/src/cli/link-apply-restart.ts

@@ -0,0 +1,72 @@
+/**
+ * After `ocx sync` applies the Home's Codex settings on a Remote Link Child, restart the Child's
+ * runtime so it started after the apply (OCX-6, P5).
+ *
+ * Idempotent: the record keeps its apply time while the settings digest is unchanged, so a runtime
+ * that already started after it is left alone, and a sync after a failed restart retries it. The
+ * restart is `ocx restart`'s own (`handleProxyRestart`); this module only decides whether to call
+ * it and never starts a runtime that was not running, except to recover one an accepted restart
+ * left absent.
+ */
+import type { HomeCodexSettingsRecord } from "../client/link-home";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import type { ProxyRestartStartOutcome } from "./tray-proxy";
+
+export type ApplyRestartOutcome =
+  | { kind: "current" }
+  | { kind: "not-running" }
+  | { kind: "connection-changed" }
+  | { kind: "restarted" }
+  | { kind: "failed" };
+
+export interface ApplyRestartDeps {
+  findLive?: () => Promise<LiveProxy | null>;
+  /** Epoch ms the live client runtime reports as its start, or null when it reports none. */
+  readStartedAt?: (live: LiveProxy) => Promise<number | null>;
+  restart: (startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>) => Promise<boolean>;
+  recoveryStart: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>;
+  /** Still the connection this sync applied for (rechecked right before the restart). */
+  connectionUnchanged: () => boolean;
+}
+
+export async function readClientRuntimeStartedAt(live: LiveProxy, fetchImpl: typeof fetch = fetch): Promise<number | null> {
+  try {
+    const response = await fetchImpl(`http://${probeHostname(live.hostname)}:${live.port}/healthz`, {
+      headers: { accept: "application/json" },
+      redirect: "manual",
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!response.ok) return null;
+    const body = await response.json() as { pid?: unknown; startedAt?: unknown } | null;
+    if (body?.pid !== live.pid || typeof body.startedAt !== "string") return null;
+    const startedAt = Date.parse(body.startedAt);
+    return Number.isFinite(startedAt) ? startedAt : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function restartRuntimeAfterApply(record: HomeCodexSettingsRecord, deps: ApplyRestartDeps): Promise<ApplyRestartOutcome> {
+  const live = await (deps.findLive ?? (() => findLiveProxy()))();
+  if (!live || live.role !== "client") return { kind: "not-running" };
+  const appliedAt = Date.parse(record.appliedAt);
+  // A runtime that reports no start time predates OCX-6 and cannot prove it is current.
+  const startedAt = await (deps.readStartedAt ?? (target => readClientRuntimeStartedAt(target)))(live);
+  if (startedAt !== null && Number.isFinite(appliedAt) && startedAt >= appliedAt) return { kind: "current" };
+  if (!deps.connectionUnchanged()) return { kind: "connection-changed" };
+  const ok = await deps.restart(async recovering => recovering
+    ? deps.recoveryStart(true)
+    : { status: "skipped" });
+  return ok ? { kind: "restarted" } : { kind: "failed" };
+}
+
+/** One line for each outcome, printed by `ocx sync`. */
+export function applyRestartMessage(outcome: ApplyRestartOutcome): string {
+  switch (outcome.kind) {
+    case "current": return "Client runtime already started after this apply; no restart needed.";
+    case "not-running": return "No client runtime is running; the applied settings take effect when it starts.";
+    case "connection-changed": return "The connection changed during sync; the client runtime was not restarted. Run 'ocx sync' again.";
+    case "restarted": return "Client runtime restarted after applying the Home's settings.";
+    case "failed": return "The client runtime restart did not complete; the previous runtime keeps serving. If a background service or the desktop app owns it, restart it there; otherwise retry with 'ocx restart' or 'ocx sync'.";
+  }
+}

package/src/cli/link-child.ts

@@ -74,6 +74,7 @@ export async function readLinkHomeJson(
   context: LinkChildContext,
   path: string,
   deps: LinkHomeDeps = {},
+  init: { signal?: AbortSignal } = {},
 ): Promise<{ status: number; body: unknown }> {
   const token = readServiceApiTokenState();
   if (token.kind !== "present" || token.fingerprint !== context.connection.tokenFingerprint) {
@@ -81,12 +82,15 @@ export async function readLinkHomeJson(
   }
   let response: Response;
   try {
-    response = await fetchLinkHomeManagement(context.connection, token.token, path.startsWith("/") ? path : `/${path}`, {}, deps);
+    response = await fetchLinkHomeManagement(context.connection, token.token, path.startsWith("/") ? path : `/${path}`,
+      init.signal ? { signal: init.signal } : {}, deps);
   } catch (error) {
     const detail = error instanceof Error && error.name === "LinkRelayAuthenticationError" ? error.message : "the link tunnel did not answer";
     throw new Error(`Could not read ${context.homePhrase} over Remote Link (${context.linkId}): ${detail}.`);
   }
-  const result = await readBoundedResponseBytes(response, { maxBytes: RESPONSE_MAX_BYTES, signal: AbortSignal.timeout(30_000) });
+  // A caller's deadline (the status report's 2 s) bounds the body read as well as the request.
+  const readSignal = init.signal ? AbortSignal.any([init.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+  const result = await readBoundedResponseBytes(response, { maxBytes: RESPONSE_MAX_BYTES, signal: readSignal });
   if (result.oversized) throw new Error(`${context.homePhrase} returned a response larger than the CLI accepts.`);
   const text = new TextDecoder().decode(result.bytes);
   let body: unknown = null;

package/src/cli/link-cleanup.ts

@@ -0,0 +1,95 @@
+/**
+ * `ocx link cleanup`: find Home-initiated Remote Link Children that run Windows and explain how to
+ * move each one to Hub mode. It never revokes or changes anything.
+ *
+ * Windows Children are refused at enrollment, but a link enrolled before that refusal existed keeps
+ * its record, key and reverse tunnel. Its record carries no platform, so this command asks the
+ * Child over the same pinned SSH trust the tunnel uses (`uname -s` through `sh`) and classifies the
+ * answer with `detectRemotePlatform` (a localized cmd or PowerShell refusal gets the fixed %OS% probe).
+ *
+ * The recovery order matters. An ordinary `ocx link revoke` runs `ocx disconnect` on the Child
+ * through the POSIX ocx prelude, which exits 125 on Windows, so for these Children the revoke must
+ * be forced after the Child disconnected itself.
+ */
+import { linkKnownHostsPath, linkStorePath } from "../link/paths";
+import { detectRemotePlatform, REMOTE_UNAME_ARGV, type RemotePlatform } from "../link/remote-platform";
+import { buildExecArgv } from "../link/ssh-argv";
+import { createSshRunner, sshFailureHint, sshRunnerErrorHint, type SshRunner } from "../link/ssh-runner";
+import { readLinkStore, type LinkStore } from "../link/store";
+import { CliUsageError, printData, rejectArgs, takeJsonFlag, takeOption } from "./runtime-api";
+
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+const CHECK_TIMEOUT_MS = 30_000;
+
+export interface LinkCleanupDeps {
+  readStore?: () => LinkStore;
+  sshRunner?: SshRunner;
+  knownHostsFile?: string;
+}
+
+export interface LinkCleanupEntry {
+  linkId: string;
+  alias: string;
+  direction: LinkStore["links"][number]["direction"];
+  platform: RemotePlatform | "not_checked";
+  reason: string | null;
+  recovery: string[];
+}
+
+export function windowsChildRecovery(linkId: string, alias: string): string[] {
+  return [
+    `On ${alias}, run 'ocx disconnect' and then 'ocx restart' so it stops using this link.`,
+    `On this Home, run 'ocx link revoke --link-id ${linkId} --force --yes'. A plain revoke cannot disconnect a Windows Child remotely.`,
+    `Then connect ${alias} in Hub mode: run 'ocx hub invite' on a Hub and the printed 'ocx connect' command on ${alias}.`,
+  ];
+}
+
+async function checkPlatform(runner: SshRunner, alias: string, knownHostsFile: string): Promise<{ platform: RemotePlatform; reason: string | null }> {
+  try {
+    const result = await runner.run(buildExecArgv({ alias, argv: REMOTE_UNAME_ARGV, knownHostsFile }), { timeoutMs: CHECK_TIMEOUT_MS });
+    const platform = await detectRemotePlatform(runner, alias, knownHostsFile, result);
+    return { platform, reason: platform === "unknown" ? (sshFailureHint(result.stderr) ?? `ssh exited ${result.code}`) : null };
+  } catch (error) {
+    return { platform: "unknown", reason: sshRunnerErrorHint(error) ?? "ssh could not run" };
+  }
+}
+
+function humanLines(entries: LinkCleanupEntry[]): string[] {
+  if (entries.length === 0) return ["No links are recorded on this Home.", "Nothing was revoked or changed."];
+  const lines: string[] = [];
+  for (const entry of entries) {
+    const label = `${entry.linkId} (${entry.alias})`;
+    if (entry.platform === "windows") {
+      lines.push(`${label}: Windows Child. Remote Link does not support Windows Children; this link predates that refusal.`);
+      for (const [index, step] of entry.recovery.entries()) lines.push(`  ${index + 1}. ${step}`);
+    } else if (entry.platform === "posix") lines.push(`${label}: macOS or Linux Child; nothing to clean up.`);
+    else if (entry.platform === "not_checked") lines.push(`${label}: Child-initiated; this Home has no SSH route to check it.`);
+    else lines.push(`${label}: platform could not be checked (${entry.reason ?? "unknown"}); retry when it is reachable.`);
+  }
+  lines.push("Nothing was revoked or changed.");
+  return lines;
+}
+
+export async function runLinkCleanup(args: string[], deps: LinkCleanupDeps, usage: string): Promise<void> {
+  const wantsJson = takeJsonFlag(args);
+  const linkId = takeOption(args, "--link-id");
+  if (linkId !== undefined && !LINK_ID.test(linkId)) throw new CliUsageError("cleanup --link-id must be a valid link id", usage);
+  rejectArgs(args, usage);
+  const store = (deps.readStore ?? (() => readLinkStore(linkStorePath())))();
+  const records = linkId === undefined ? store.links : store.links.filter(link => link.id === linkId);
+  if (linkId !== undefined && records.length === 0) throw new CliUsageError(`No link ${linkId} is recorded on this Home.`, usage);
+  const runner = deps.sshRunner ?? createSshRunner();
+  const knownHostsFile = deps.knownHostsFile ?? linkKnownHostsPath();
+  const entries: LinkCleanupEntry[] = [];
+  // One at a time: each check is a bounded SSH command, and order keeps the report stable.
+  for (const record of records) {
+    const checked = record.direction === "hub-initiated"
+      ? await checkPlatform(runner, record.alias, knownHostsFile)
+      : { platform: "not_checked" as const, reason: null };
+    entries.push({
+      linkId: record.id, alias: record.alias, direction: record.direction, ...checked,
+      recovery: checked.platform === "windows" ? windowsChildRecovery(record.id, record.alias) : [],
+    });
+  }
+  printData({ links: entries, changed: false }, wantsJson, humanLines(entries));
+}

package/src/cli/link-enrollment.ts

@@ -1,5 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import { assertSshAlias } from "../link/ssh-argv";
+import { windowsChildRefusal } from "../link/remote-platform";
 import { CliUsageError, RuntimeApiError, runtimeBaseUrl, rejectArgs, takeJsonFlag, takeOption, printData } from "./runtime-api";
 import type { LinkCliDeps } from "./link";
 
@@ -83,6 +84,9 @@ export async function runLinkEnrollment(command: "probe" | "add", args: string[]
   catch (error) {
     if (error instanceof RuntimeApiError && record(error.body)) {
       const code = record(error.body.error) ? error.body.error.code : undefined;
+      // Refused at probe or confirm, before any key or tunnel: point at Hub mode, not at a phase.
+      // A residual response comes after key issuance; it keeps its Child recovery below.
+      if (code === "remote_platform_unsupported" && error.body.residual !== true) throw new Error(windowsChildRefusal(alias));
       const phase = typeof code === "string" && Object.hasOwn(PHASES, code) ? PHASES[code] : undefined;
       const message = phase ? "Remote Link failed during " + phase : error.message;
       if (phase || error.body.residual === true) throw new Error(message + (error.body.residual === true ? ". " + RECOVERY : ""));

package/src/cli/link.ts

@@ -1,8 +1,15 @@
 import { clientLinkStatusIdentity } from "../client/link-status";
 import { clientLinkTunnelStatus } from "../client/link-tunnel";
 import { loadConfig } from "../config";
-import { projectLinkStatus, type ClientLinkIdentity, type LinkStatusConfig, type LinkStatusDto } from "../link/status-projection";
+import {
+  projectLinkStatus, type ClientLinkIdentity, type LinkStatusConfig, type LinkStatusDto, type LinkTunnelDiagnostics, type LinkWireState,
+} from "../link/status-projection";
+import { TUNNEL_CAUSES } from "../link/tunnel-history";
+import { isEpochMs, type LinkChildParity } from "../link/child-parity";
+import { CODEX_SETTINGS_DIGEST_PATTERN } from "../link/codex-settings";
+import type { LinkLocalPeer, LinkPeerStatus } from "../link/compatibility";
 import { runLinkEnrollment } from "./link-enrollment";
+import { runLinkCleanup, type LinkCleanupDeps } from "./link-cleanup";
 import { assertSshAlias } from "../link/ssh-argv";
 import { linkStorePath } from "../link/paths";
 import { isLinkPort } from "../link/ports";
@@ -31,31 +38,16 @@ export const LINK_USAGE = `Usage:
   ocx link status [--json]
   ocx link revoke --link-id <id> [--force --yes] [--json]
   ocx link reconnect --link-id <id> [--json]
+  ocx link cleanup [--link-id <id>] [--json]
 
-Forced revoke skips remote cleanup. Run ocx disconnect on the remote client.`;
-
-type LinkState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
-type ListenerState = "off" | "listening" | "failed";
+Forced revoke skips remote cleanup. Run ocx disconnect on the remote client.
+Cleanup finds Windows Children and explains how to move them to Hub mode; it changes nothing.`;
 
-export interface LinkStatusPayload {
-  role: "standalone" | "home" | "child";
-  listener: { state: ListenerState; port: number | null };
-  links: Array<{
-    id: string;
-    alias: string;
-    direction: LinkDirection;
-    state: LinkState;
-    since: string;
-    reason: string | null;
-    tunnelPort: number;
-  }>;
-  child: null | {
-    alias: string;
-    state: LinkState;
-    since: string;
-    reason: string | null;
-  };
-}
+/**
+ * What `ocx link status` prints: the runtime's status DTO itself, so a field the server adds (like
+ * `peer` or the diagnostics `tunnel`) is part of this type the moment it is part of the wire.
+ */
+export type LinkStatusPayload = LinkStatusDto;
 
 export interface LinkIssuePayload {
   linkId: string;
@@ -64,7 +56,7 @@ export interface LinkIssuePayload {
   listenerPort: number;
 }
 
-export interface LinkCliDeps extends RuntimeApiDeps {
+export interface LinkCliDeps extends RuntimeApiDeps, Omit<LinkCleanupDeps, "readStore"> {
   /** Test seam can shorten, never extend, the whole enrollment deadline. */
   enrollmentTimeoutMs?: number;
   choosePort?: () => Promise<number>;
@@ -85,9 +77,14 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function assertExactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
-  const expected = new Set(keys);
+  assertKeys(value, keys, [], label);
+}
+
+/** Exact keys plus fields a newer proxy adds; an older proxy omits them. */
+function assertKeys(value: Record<string, unknown>, keys: readonly string[], optional: readonly string[], label: string): void {
+  const allowed = new Set([...keys, ...optional]);
   const actual = Object.keys(value);
-  if (actual.length !== expected.size || actual.some(key => !expected.has(key))) {
+  if (keys.some(key => !(key in value)) || actual.some(key => !allowed.has(key))) {
     throw new Error(`invalid link API response: ${label} fields`);
   }
 }
@@ -104,9 +101,42 @@ function validNullableString(value: unknown): value is string | null {
   return value === null || typeof value === "string";
 }
 
+function validStringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(validString);
+}
+
+function validateLocal(value: unknown): LinkLocalPeer {
+  if (!isRecord(value)) throw new Error("invalid link API response: local");
+  assertExactKeys(value, ["version", "relayAuth", "features"], "local");
+  if (!validString(value.version) || !validString(value.relayAuth) || !validStringList(value.features)) {
+    throw new Error("invalid link API response: local fields");
+  }
+  return { version: value.version, relayAuth: value.relayAuth, features: [...value.features] };
+}
+
+function validatePeer(value: unknown, index: number): LinkPeerStatus {
+  const fail = (): never => { throw new Error(`invalid link API response: link ${index} peer`); };
+  if (!isRecord(value)) return fail();
+  assertExactKeys(value, ["observedAt", "version", "versionRange", "relayAuth", "features", "compatibility", "reasons"], `link ${index} peer`);
+  const range = value.versionRange;
+  if (!validNullableString(value.observedAt) || !validNullableString(value.version) || !validNullableString(value.relayAuth)
+    || (value.features !== null && !validStringList(value.features)) || !validStringList(value.reasons)
+    || !["compatible", "degraded", "incompatible", "unknown"].includes(value.compatibility as string)
+    || (range !== null && (!isRecord(range) || !validNullableString(range.min) || !validString(range.below)))) fail();
+  return {
+    observedAt: value.observedAt as string | null,
+    version: value.version as string | null,
+    versionRange: range === null ? null : { min: (range as Record<string, unknown>).min as string | null, below: (range as Record<string, unknown>).below as string },
+    relayAuth: value.relayAuth as string | null,
+    features: value.features === null ? null : [...value.features as string[]],
+    compatibility: value.compatibility as LinkPeerStatus["compatibility"],
+    reasons: [...value.reasons as string[]],
+  };
+}
+
 function validateStatus(value: unknown): LinkStatusPayload {
   if (!isRecord(value)) throw new Error("invalid link API response: status object");
-  assertExactKeys(value, ["role", "listener", "links", "child"], "status");
+  assertKeys(value, ["role", "listener", "links", "child"], ["local"], "status");
   if (value.role !== "standalone" && value.role !== "home" && value.role !== "child") {
     throw new Error("invalid link API response: status role");
   }
@@ -119,9 +149,12 @@ function validateStatus(value: unknown): LinkStatusPayload {
     throw new Error("invalid link API response: listener port");
   }
   if (!Array.isArray(value.links)) throw new Error("invalid link API response: links");
-  const links = value.links.map((candidate, index) => {
+  const links = value.links.map((candidate, index): LinkStatusPayload["links"][number] => {
     if (!isRecord(candidate)) throw new Error(`invalid link API response: link ${index}`);
-    assertExactKeys(candidate, ["id", "alias", "direction", "state", "since", "reason", "tunnelPort"], `link ${index}`);
+    // The OCX-6 parity fields are optional on the wire (an older runtime omits them) and always
+    // present in this output, null when absent.
+    assertKeys(candidate, ["id", "alias", "direction", "state", "since", "reason", "tunnelPort"], [...PARITY_KEYS, "peer", "tunnel"], `link ${index}`);
+    const parity = validateParity(candidate, index);
     if (typeof candidate.id !== "string" || !LINK_ID.test(candidate.id)
       || !validString(candidate.alias) || (candidate.direction !== "hub-initiated" && candidate.direction !== "client-initiated")
       || (candidate.state !== "connecting" && candidate.state !== "connected" && candidate.state !== "reconnecting" && candidate.state !== "failed" && candidate.state !== "idle")
@@ -131,12 +164,15 @@ function validateStatus(value: unknown): LinkStatusPayload {
     return {
       id: candidate.id,
       alias: candidate.alias,
-      direction: candidate.direction,
-      state: candidate.state,
+      direction: candidate.direction as LinkDirection,
+      state: candidate.state as LinkWireState,
       since: candidate.since,
       reason: candidate.reason,
       tunnelPort: candidate.tunnelPort,
-    } as LinkStatusPayload["links"][number];
+      ...parity,
+      ...(candidate.peer !== undefined ? { peer: validatePeer(candidate.peer, index) } : {}),
+      ...(candidate.tunnel !== undefined ? { tunnel: validateTunnel(candidate.tunnel, index) } : {}),
+    };
   });
   let child: LinkStatusPayload["child"] = null;
   if (value.child !== null) {
@@ -159,6 +195,7 @@ function validateStatus(value: unknown): LinkStatusPayload {
     listener: { state: value.listener.state, port: value.listener.port },
     links,
     child,
+    ...(value.local !== undefined ? { local: validateLocal(value.local) } : {}),
   };
 }
 
@@ -258,7 +295,9 @@ async function runStatus(args: string[], deps: LinkCliDeps): Promise<void> {
     }
     throw error;
   }
-  const result = validateStatus(await linkRequest<unknown>("/api/link/status", {}, { ...deps, baseUrl }));
+  // A proxy older than the compatibility report or the tunnel diagnostics ignores the query and
+  // answers without those fields.
+  const result = validateStatus(await linkRequest<unknown>("/api/link/status?compatibility=1&diagnostics=1", {}, { ...deps, baseUrl }));
   console.log(JSON.stringify(result));
 }
 
@@ -326,6 +365,55 @@ export async function runLinkCommand(rawArgs: string[], deps: LinkCliDeps = {}):
     else if (command === "status") await runStatus(args, deps);
     else if (command === "revoke") await runRevoke(args, deps);
     else if (command === "reconnect") await runReconnect(args, deps);
-    else throw new CliUsageError("link requires one of: probe, add, port, issue, status, revoke, reconnect", LINK_USAGE);
+    else if (command === "cleanup") await runLinkCleanup(args, deps, LINK_USAGE);
+    else throw new CliUsageError("link requires one of: probe, add, port, issue, status, revoke, reconnect, cleanup", LINK_USAGE);
   });
 }
+
+const PARITY_KEYS = ["lastApplyAt", "runtimeStartedAt", "appliedCodexSettingsDigest", "reportedAt"] as const;
+const WIRE_STATES = new Set(["connecting", "connected", "reconnecting", "failed", "idle"]);
+const CAUSES = new Set<string>(TUNNEL_CAUSES);
+
+function validIso(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 64 && Number.isFinite(Date.parse(value));
+}
+
+function validateTunnel(value: unknown, index: number): LinkTunnelDiagnostics {
+  const fail = (): never => { throw new Error(`invalid link API response: link ${index} tunnel`); };
+  if (!isRecord(value)) return fail();
+  assertExactKeys(value, ["attempt", "nextRetryAt", "lastTransition", "lastFailure"], `link ${index} tunnel`);
+  const { attempt, nextRetryAt, lastTransition, lastFailure } = value;
+  if (typeof attempt !== "number" || !Number.isSafeInteger(attempt) || attempt < 0) fail();
+  if (nextRetryAt !== null && !validIso(nextRetryAt)) fail();
+  if (lastTransition !== null) {
+    if (!isRecord(lastTransition)) return fail();
+    assertExactKeys(lastTransition, ["from", "to", "at", "cause"], `link ${index} tunnel transition`);
+    if (!WIRE_STATES.has(lastTransition.from as string) || !WIRE_STATES.has(lastTransition.to as string)
+      || !validIso(lastTransition.at) || (lastTransition.cause !== null && !CAUSES.has(lastTransition.cause as string))) fail();
+  }
+  if (lastFailure !== null) {
+    if (!isRecord(lastFailure)) return fail();
+    assertExactKeys(lastFailure, ["cause", "at"], `link ${index} tunnel failure`);
+    if (!CAUSES.has(lastFailure.cause as string) || !validIso(lastFailure.at)) fail();
+  }
+  return value as unknown as LinkTunnelDiagnostics;
+}
+
+function validateParity(candidate: Record<string, unknown>, index: number): LinkChildParity {
+  const time = (key: "lastApplyAt" | "runtimeStartedAt" | "reportedAt"): number | null => {
+    const value = candidate[key];
+    if (value === undefined || value === null) return null;
+    if (!isEpochMs(value)) throw new Error(`invalid link API response: link ${index} ${key}`);
+    return value;
+  };
+  const digest = candidate.appliedCodexSettingsDigest;
+  if (digest !== undefined && digest !== null && (typeof digest !== "string" || !CODEX_SETTINGS_DIGEST_PATTERN.test(digest))) {
+    throw new Error(`invalid link API response: link ${index} appliedCodexSettingsDigest`);
+  }
+  return {
+    lastApplyAt: time("lastApplyAt"),
+    runtimeStartedAt: time("runtimeStartedAt"),
+    appliedCodexSettingsDigest: typeof digest === "string" ? digest : null,
+    reportedAt: time("reportedAt"),
+  };
+}

package/src/cli/provider.ts

@@ -28,6 +28,8 @@ import type { RuntimeApiDeps } from "./runtime-api";
 import { redactSecretArgs } from "./secret-args";
 import { projectLocalSyncResult, type LocalSyncResult } from "./local-sync-result";
 import { providerManagementConfigError } from "../server/auth-cors";
+import { readClientConnectionState, type ClientConnectionState } from "../client/state";
+import { SENSITIVE_KEY_PATTERN } from "../lib/redact";
 
 export interface ProviderCommandDeps extends RuntimeApiDeps {
   syncModels?: typeof syncModelsToCodex;
@@ -102,7 +104,46 @@ function validateAndSave(config: ReturnType<typeof loadConfig>): void {
 // provider list
 // ---------------------------------------------------------------------------
 
-function handleList(args: string[]): void {
+/**
+ * Does this device's own provider config serve requests? A device linked to a Home — a Remote
+ * Link Child or a Hub-mode client — routes through the Home, so its local rows are shadowed.
+ * A standalone device and a Hub serve their own rows. An unreadable or inconsistent client
+ * state is not a link, the same reading `readLinkChildContext` takes.
+ */
+export function localProvidersActive(read: () => ClientConnectionState = readClientConnectionState): boolean {
+  try {
+    return read().kind !== "connected";
+  } catch {
+    return true;
+  }
+}
+
+const SENSITIVE_QUERY_KEY = /key|token|secret|password|passwd|signature|^sig$|auth|credential/i;
+
+/**
+ * The baseUrl as `provider list` prints it. Validation already rejects embedded credentials;
+ * this also covers a hand-edited config, dropping userinfo and masking credential-shaped query
+ * values while keeping ordinary parameters such as `api-version`.
+ */
+export function providerListBaseUrl(baseUrl: string): string {
+  let parsed: URL;
+  try { parsed = new URL(baseUrl); } catch { return baseUrl; }
+  let changed = false;
+  if (parsed.username || parsed.password) {
+    parsed.username = "";
+    parsed.password = "";
+    changed = true;
+  }
+  for (const key of [...new Set(parsed.searchParams.keys())]) {
+    if (SENSITIVE_KEY_PATTERN.test(key) || SENSITIVE_QUERY_KEY.test(key)) {
+      parsed.searchParams.set(key, "redacted");
+      changed = true;
+    }
+  }
+  return changed ? parsed.toString() : baseUrl;
+}
+
+function handleList(args: string[], active: boolean = localProvidersActive()): void {
   const wantsJson = consumeFlag(args, "--json");
   const wantsJsonl = consumeFlag(args, "--jsonl");
   rejectUnknownArgs(args, "Usage: ocx provider list [--json|--jsonl]");
@@ -120,12 +161,13 @@ function handleList(args: string[]): void {
     return {
       name,
       adapter: prov.adapter,
-      baseUrl: prov.baseUrl,
+      baseUrl: providerListBaseUrl(prov.baseUrl),
       authMode: prov.authMode ?? "key",
       defaultModel: prov.defaultModel ?? null,
       isDefault: name === config.defaultProvider,
       source: registryEntry ? "registry" : "custom",
       models: prov.models ?? [],
+      active,
     };
   });
 
@@ -149,7 +191,7 @@ function handleList(args: string[]): void {
     console.log(`  ${name}${isDefault}${source}  adapter=${prov.adapter}${model}`);
   }
 
-  const available = PROVIDER_REGISTRY.filter(e => !configured.includes(e.id));
+  const available = PROVIDER_REGISTRY.filter(e => !e.deprecated && !configured.includes(e.id));
   if (available.length > 0) {
     console.log(`\nAvailable from registry (${available.length}):\n`);
     for (const entry of available) {
@@ -223,6 +265,7 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
   const registryEntry = getProviderRegistryEntry(name);
 
   if (registryEntry) {
+    if (registryEntry.deprecated) console.warn(`Warning: provider "${name}" is deprecated: ${registryEntry.deprecated}`);
     provConfig = providerConfigSeed(registryEntry);
     if (apiKey) {
       const candidateError = providerCredentialInputError({ apiKey });