@bitkyc08/opencodex 2.82.0 → 2.84.0

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

@@ -1,126 +1,29 @@
-import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { assertSshAlias, buildExecArgv, buildFingerprintArgv, buildProbeArgv, REMOTE_COMMAND_NOT_FOUND, remoteOcxArgv } from "../../link/ssh-argv";
-import { parseFingerprintLine } from "../../link/fingerprint";
-import { awaitFirstAdmission } from "../../link/admission-wait";
-import { linkKnownHostsPath, linkStorePath } from "../../link/paths";
-import { clearCompensationFailed, compensationPath, markCompensationFailed, readCompensation } from "../../link/compensation";
+import { probe, confirmHost, apply } from "./link-enrollment";
+import { fail, pairedSession, auth, port, isRecord, exactBody, runnerFor, readStoreFor, writeStoreFor, knownHostsFile, issueKey, revokeKeyIdempotent, compensateNewLink, type LinkRouteState } from "./link-route-state";
+export type { LinkRouteState, PendingLinkHost, ConfirmedLinkHost, LinkRouteListener } from "./link-route-state";
+import { assertSshAlias, buildExecArgv, remoteOcxArgv } from "../../link/ssh-argv";
+import { clearCompensationFailed, compensationPath, readCompensation } from "../../link/compensation";
 import { loadHostCandidates } from "../../link/ssh-config";
-import { newLinkId, readLinkStore, writeLinkStore, type LinkStore } from "../../link/store";
-import { boundHint, createSshRunner, sshFailureHint, sshRunnerErrorHint, type SshRunner, type SshRunResult } from "../../link/ssh-runner";
+import { newLinkId, type LinkStore } from "../../link/store";
+import { sshFailureHint, sshRunnerErrorHint } from "../../link/ssh-runner";
 import { projectLinkStatus, type LinkStatusDto } from "../../link/status-projection";
 import { isLinkPort } from "../../link/ports";
 import { joinHome, type ClientLinkJoinDeps } from "../../client/link-join";
+import { clientLinkStatusIdentity } from "../../client/link-status";
 import { clientLinkTunnelStatus } from "../../client/link-tunnel";
+import { withConfigMutationLockSync } from "../../config/mutation-lock";
 import type { ManagementContext } from "./context";
 import { readManagementJsonBodyOr } from "./body";
-import { issueApiKeyInProcess, revokeApiKeyInProcess, type IssuedApiKey } from "./oauth-account-routes";
+import { type IssuedApiKey } from "./oauth-account-routes";
 import { acceptSystemRestart, resolveListenPort } from "./system-restart";
 
-const PROBE_TTL_MS = 5 * 60_000;
-const APPLY_ADMISSION_TIMEOUT_MS = 15_000;
 const LINK_ID = /^lnk_[0-9a-f]{16}$/;
-// `ocx link` and `ocx connect --link` first shipped in 2.66.0; an older remote passes --version
-// and then fails at apply with remote_port_failed.
-const MIN_REMOTE_OCX = [2, 66, 0] as const;
-// A bounded semver shape: the parsed version reaches the confirm-host body and the outdated hint,
-// so the tail admits only a pre-release and build of semver identifier characters and must end
-// the token. Anything else attached to the version makes the output unrecognized.
-const REMOTE_OCX_VERSION = /^opencodex (\d{1,9})\.(\d{1,9})\.(\d{1,9})(-[0-9A-Za-z.-]{1,64})?(\+[0-9A-Za-z.-]{1,64})?(?=\s|$)/;
 const isLinkPath = (path: string): boolean => path === "/api/link" || path.startsWith("/api/link/");
 
-export interface PendingLinkHost {
-  alias: string;
-  fingerprint: string;
-  keyType: string;
-  knownHostLine: string;
-  probedAt: number;
-}
-
-export interface ConfirmedLinkHost extends PendingLinkHost {
-  ocxVersion: string;
-}
-
-export interface LinkRouteListener {
-  ensureStarted(): Promise<void>;
-  status(): { state: "off" | "listening" | "failed"; port: number | null; reason: string | null };
-  close(): Promise<void>;
-  onAuthenticatedCatalog(listener: (apiKeyId: string) => void): () => void;
-}
-
-export interface LinkRouteState {
-  pendingHosts: Map<string, PendingLinkHost>;
-  confirmedHosts?: Map<string, ConfirmedLinkHost>;
-  compensationFailures?: Map<string, { since: string; reason: "compensation_failed" }>;
-  supervisor: import("../../link/supervisor").LinkSupervisor;
-  listener: LinkRouteListener;
-}
-
 const states = new WeakMap<object, LinkRouteState>();
 // One process runs at most one join: a join ends by restarting this process as a client.
 let joinInProgress = false;
 
-/**
- * `hint` is one line bounded by `boundHint`: from ssh stderr (`sshFailureHint`), from the ssh
- * runner's own failure (`sshRunnerErrorHint`), or the parsed remote version for
- * `remote_ocx_outdated`. It is returned, never logged.
- */
-function fail(code: string, message: string, status: number, hint?: string): Response {
-  return Response.json({ error: { code, message, ...(hint ? { hint } : {}) } }, { status, headers: { "cache-control": "no-store" } });
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-function exactBody(body: unknown, keys: readonly string[]): Record<string, unknown> | null {
-  if (!isRecord(body)) return null;
-  const actual = Object.keys(body).sort();
-  const expected = [...keys].sort();
-  return actual.length === expected.length && actual.every((key, index) => key === expected[index]) ? body : null;
-}
-
-function port(value: unknown): value is number {
-  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
-}
-
-/** A GUI session redeemed from an operator-created, one-use pairing grant. */
-function pairedSession(ctx: ManagementContext): boolean {
-  return ctx.principal === "gui-session"
-    && ctx.sessionControl?.isPaired(ctx.req, ctx.config) === true;
-}
-
-/**
- * A paired session, or on a standalone runtime the current loopback-issued session that reached
- * the public listener bound to a loopback hostname. The loopback bootstrap mints that session
- * without a credential, so this is casual-path protection like POST /api/github/star, not a
- * secret-backed boundary like the admin token. Hubs keep the paired-only rule. Durable operations
- * that require operator approval, such as joining this machine as a Child, use pairedSession.
- */
-function dashboardSession(ctx: ManagementContext): boolean {
-  if (pairedSession(ctx)) return true;
-  return ctx.principal === "gui-session"
-    && (ctx.config.runtimeRole ?? "standalone") === "standalone"
-    && ctx.guiSessionIssuance === "loopback"
-    && ctx.trustedLoopbackIngress
-    && ctx.sessionControl?.isCurrent(ctx.req, ctx.config) === true;
-}
-
-function adminLoopback(ctx: ManagementContext): boolean {
-  return ctx.principal === "admin-token" && ctx.trustedLoopbackIngress;
-}
-
-function auth(ctx: ManagementContext, kind: "dashboard" | "paired" | "admin" | "either"): Response | null {
-  if (ctx.guiSessionIssuance === "tailscale-identity") return fail("tailscale_session_refused", "Tailscale identity sessions cannot use link routes.", 403);
-  const allowed = kind === "dashboard" ? dashboardSession(ctx)
-    : kind === "paired" ? pairedSession(ctx)
-    : kind === "admin" ? adminLoopback(ctx)
-      : dashboardSession(ctx) || adminLoopback(ctx);
-  return allowed ? null : fail("forbidden", "The required link authorization was not present.", 403);
-}
-
 /**
  * The client runtime a join restarts into binds exactly the configured port, with no fallback.
  * A standalone that runs elsewhere (`ocx start --port`, or a port fallback) would restart into a
@@ -141,18 +44,6 @@ function joinDenied(ctx: ManagementContext): LinkJoinDenied | null {
   return null;
 }
 
-function runnerFor(ctx: ManagementContext): SshRunner {
-  return ctx.deps.sshRunner ?? createSshRunner();
-}
-
-function readStoreFor(ctx: ManagementContext): LinkStore {
-  return ctx.deps.readLinkStore?.() ?? readLinkStore(linkStorePath());
-}
-
-function writeStoreFor(ctx: ManagementContext, store: LinkStore): void {
-  (ctx.deps.writeLinkStore ?? (value => writeLinkStore(linkStorePath(), value)))(store);
-}
-
 function stateFor(ctx: ManagementContext): LinkRouteState | null {
   const supervisor = ctx.deps.linkSupervisor?.();
   const listener = ctx.deps.linkListener?.();
@@ -171,246 +62,11 @@ function stateFor(ctx: ManagementContext): LinkRouteState | null {
   return state;
 }
 
-function knownHostsFile(ctx: ManagementContext): string {
-  return ctx.deps.linkKnownHostsPath?.() ?? linkKnownHostsPath();
-}
-
-function putKnownHost(path: string, alias: string, line: string): string {
-  const before = (() => { try { return readFileSync(path, "utf8"); } catch { return ""; } })();
-  const lines = before.split(/\r?\n/).filter(value => value && !value.startsWith(`${alias} `) && !value.startsWith(`${alias},`));
-  lines.push(line.trim());
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  writeFileSync(path, `${lines.join("\n")}\n`, { mode: 0o600 });
-  try { chmodSync(path, 0o600); } catch { /* best effort on Windows */ }
-  return before;
-}
-
-function restoreKnownHost(path: string, before: string): void {
-  if (!before) {
-    try { rmSync(path, { force: true }); } catch { /* best effort compensation */ }
-    return;
-  }
-  writeFileSync(path, before, { mode: 0o600 });
-}
-
-function issueKey(ctx: ManagementContext, name: string): IssuedApiKey {
-  return (ctx.deps.issueApiKey ?? issueApiKeyInProcess)(ctx.config, name);
-}
-
-function revokeKey(ctx: ManagementContext, id: string): boolean {
-  return (ctx.deps.revokeApiKey ?? revokeApiKeyInProcess)(ctx.config, id);
-}
-
-/**
- * Revocation that a retry can repeat. A key that is no longer in the live config is already
- * revoked, which is exactly the state a partially completed cleanup leaves behind; without this
- * a retried DELETE would fail forever on the key it removed the first time.
- */
-function revokeKeyIdempotent(ctx: ManagementContext, id: string): boolean {
-  let revoked = false;
-  try { revoked = revokeKey(ctx, id); } catch { revoked = false; }
-  if (revoked) return true;
-  return !(ctx.config.apiKeys ?? []).some(entry => entry.id === id);
-}
-
-function compensationFailure(ctx: ManagementContext, state: LinkRouteState, record: LinkStore["links"][number], phase: string): Response {
-  const since = new Date((ctx.deps.now ?? Date.now)()).toISOString();
-  (state.compensationFailures ??= new Map()).set(record.id, { since, reason: "compensation_failed" });
-  try { markCompensationFailed(record.id, since, compensationPath()); } catch (error) {
-    console.warn(`[link] compensation marker persistence failed linkId=${record.id}: ${error instanceof Error ? error.message : String(error)}`);
-  }
-  console.warn(`[link] compensation_failed linkId=${record.id} phase=${phase}`);
-  return fail("compensation_failed", "The link compensation could not be completed.", 500);
-}
-
-async function compensateNewLink(ctx: ManagementContext, state: LinkRouteState, record: LinkStore["links"][number]): Promise<Response | null> {
-  const revoked = revokeKeyIdempotent(ctx, record.apiKeyId);
-  if (!revoked) {
-    try { await state.supervisor.stopLink(record.id); } catch { /* retain the record and failure marker */ }
-    try {
-      const current = readStoreFor(ctx);
-      if (!current.links.some(link => link.id === record.id)) {
-        writeStoreFor(ctx, { ...current, links: [...current.links, record] });
-      }
-    } catch {
-      // The in-memory marker still makes the residual visible when persistence is unavailable.
-    }
-    return compensationFailure(ctx, state, record, "revoke");
-  }
-  try { await state.supervisor.stopLink(record.id); } catch { return compensationFailure(ctx, state, record, "stop"); }
-  try {
-    const current = readStoreFor(ctx);
-    const next = { ...current, links: current.links.filter(link => link.id !== record.id) };
-    if (next.links.length !== current.links.length) {
-      writeStoreFor(ctx, next);
-    }
-    clearCompensationFailed(record.id, compensationPath());
-    state.compensationFailures?.delete(record.id);
-    if (next.links.length === 0) await state.listener.close();
-    return null;
-  } catch {
-    return compensationFailure(ctx, state, record, "store");
-  }
-}
-
 async function candidates(ctx: ManagementContext): Promise<Response> {
   const values = ctx.deps.loadLinkCandidates?.() ?? loadHostCandidates();
   return Response.json({ candidates: values.map(value => ({ alias: value.alias, source: value.source })) });
 }
 
-async function probe(ctx: ManagementContext, state: LinkRouteState): Promise<Response> {
-  const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias"]);
-  if (!body || typeof body.alias !== "string") return fail("invalid_body", "alias is required.", 400);
-  try { assertSshAlias(body.alias); } catch { return fail("invalid_alias", "alias must be a valid SSH host alias.", 400); }
-  const dir = mkdtempSync(join(tmpdir(), "ocx-link-probe-"));
-  const tempKnownHosts = join(dir, "known_hosts");
-  writeFileSync(tempKnownHosts, "", { mode: 0o600 });
-  const runner = runnerFor(ctx);
-  try {
-    const result = await runner.run(buildProbeArgv({ alias: body.alias, tempKnownHostsFile: tempKnownHosts }), { timeoutMs: 30_000 });
-    if (result.code !== 0) return fail("probe_failed", "SSH host probing failed.", 502, sshFailureHint(result.stderr));
-    const fingerprintResult = await runner.run(buildFingerprintArgv(tempKnownHosts), { timeoutMs: 10_000 });
-    if (fingerprintResult.code !== 0) return fail("fingerprint_failed", "The SSH host fingerprint could not be read.", 502, sshFailureHint(fingerprintResult.stderr));
-    const parsed = parseFingerprintLine(fingerprintResult.stdout.trim());
-    const knownHostLine = readFileSync(tempKnownHosts, "utf8").trim().split(/\r?\n/).filter(Boolean).at(-1);
-    if (!knownHostLine) return fail("fingerprint_failed", "The SSH probe did not record a host key.", 502);
-    state.pendingHosts.set(body.alias, { alias: body.alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, knownHostLine, probedAt: (ctx.deps.now ?? Date.now)() });
-    return Response.json({ alias: body.alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType });
-  } catch (error) {
-    return fail("probe_failed", "SSH host probing failed.", 502, sshRunnerErrorHint(error));
-  } finally {
-    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
-  }
-}
-
-async function confirmHost(ctx: ManagementContext, state: LinkRouteState): Promise<Response> {
-  const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias", "fingerprint"]);
-  if (!body || typeof body.alias !== "string" || typeof body.fingerprint !== "string") return fail("invalid_body", "alias and fingerprint are required.", 400);
-  const pending = state.pendingHosts.get(body.alias);
-  const now = (ctx.deps.now ?? Date.now)();
-  if (!pending || now - pending.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host probe has expired.", 409);
-  if (pending.fingerprint !== body.fingerprint) return fail("host_fingerprint_mismatch", "The confirmed fingerprint does not match the probe.", 409);
-  const path = knownHostsFile(ctx);
-  const before = putKnownHost(path, pending.alias, pending.knownHostLine);
-  // Every refusal restores known_hosts and keeps the pending probe, so a retry within its TTL works.
-  const refuse = (response: Response): Response => { restoreKnownHost(path, before); return response; };
-  let result: SshRunResult;
-  try {
-    result = await runnerFor(ctx).run(buildExecArgv({ alias: pending.alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 });
-  } catch (error) {
-    return refuse(fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshRunnerErrorHint(error)));
-  }
-  if (result.code === REMOTE_COMMAND_NOT_FOUND) return refuse(fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr)));
-  if (result.code !== 0) return refuse(fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshFailureHint(result.stderr)));
-  const version = parseRemoteOcxVersion(result.stdout);
-  if (!version) return refuse(fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502));
-  if (!meetsRemoteOcxFloor(version.parts)) {
-    return refuse(fail("remote_ocx_outdated", `The remote OpenCodex is older than ${MIN_REMOTE_OCX.join(".")}.`, 409, boundHint(`opencodex ${version.version}`)));
-  }
-  const confirmed = { ...pending, ocxVersion: version.version };
-  state.confirmedHosts ??= new Map();
-  state.confirmedHosts.set(pending.alias, confirmed);
-  state.pendingHosts.delete(pending.alias);
-  return Response.json({ alias: pending.alias, fingerprint: pending.fingerprint, ocxVersion: confirmed.ocxVersion });
-}
-
-/**
- * `ocx --version` prints `opencodex <version>` first; a usage banner, an unbounded version tail or
- * other output is refused.
- */
-function parseRemoteOcxVersion(stdout: string): { version: string; parts: [number, number, number] } | null {
-  const match = REMOTE_OCX_VERSION.exec(stdout.trim().split(/\r?\n/)[0] ?? "");
-  if (!match) return null;
-  return { version: `${match[1]}.${match[2]}.${match[3]}${match[4] ?? ""}${match[5] ?? ""}`, parts: [Number(match[1]), Number(match[2]), Number(match[3])] };
-}
-
-function meetsRemoteOcxFloor(parts: readonly [number, number, number]): boolean {
-  for (let index = 0; index < MIN_REMOTE_OCX.length; index += 1) {
-    if (parts[index] !== MIN_REMOTE_OCX[index]) return parts[index]! > MIN_REMOTE_OCX[index]!;
-  }
-  return true;
-}
-
-function parsePortOutput(stdout: string): number | null {
-  try {
-    const value: unknown = JSON.parse(stdout.trim());
-    if (!isRecord(value) || Object.keys(value).length !== 1 || !port(value.port)) return null;
-    return value.port;
-  } catch { return null; }
-}
-
-async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Response> {
-  const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias"]);
-  if (!body || typeof body.alias !== "string") return fail("invalid_body", "alias is required.", 400);
-  const confirmed = state.confirmedHosts?.get(body.alias);
-  if (!confirmed) return fail("host_not_confirmed", "Confirm the SSH host before applying the link.", 409);
-  const knownHosts = knownHostsFile(ctx);
-  const runner = runnerFor(ctx);
-  let remotePort: number;
-  let portHint: string | undefined;
-  try {
-    const result = await runner.run(buildExecArgv({ alias: body.alias, argv: remoteOcxArgv(["link", "port"]), knownHostsFile: knownHosts }), { timeoutMs: 30_000 });
-    if (result.code === REMOTE_COMMAND_NOT_FOUND) return fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr));
-    remotePort = result.code === 0 ? parsePortOutput(result.stdout) ?? 0 : 0;
-    if (result.code !== 0) portHint = sshFailureHint(result.stderr);
-  } catch (error) { remotePort = 0; portHint = sshRunnerErrorHint(error); }
-  if (!port(remotePort)) return fail("remote_port_failed", "The remote link port could not be determined.", 502, portHint);
-  let issued: IssuedApiKey;
-  try { issued = issueKey(ctx, `link:${body.alias}`); }
-  catch { return fail("key_issue_failed", "The link key could not be issued.", 503); }
-  const id = newLinkId();
-  const record = { id, alias: body.alias, direction: "hub-initiated" as const, hostKeyFingerprint: confirmed.fingerprint, tunnelPort: remotePort, apiKeyId: issued.id, createdAt: new Date((ctx.deps.now ?? Date.now)()).toISOString() };
-  let store: LinkStore;
-  try {
-    const current = readStoreFor(ctx);
-    if (current.links.some(link => link.alias === body.alias && link.direction === "hub-initiated")) {
-      const compensation = await compensateNewLink(ctx, state, record);
-      if (compensation) return compensation;
-      return fail("link_exists", "A link for this alias already exists.", 409);
-    }
-    store = { ...current, links: [...current.links, record] };
-    writeStoreFor(ctx, store);
-    await state.listener.ensureStarted();
-    if (state.listener.status().state !== "listening") {
-      const compensation = await compensateNewLink(ctx, state, record);
-      return compensation ?? fail("listener_unavailable", "The link listener is unavailable.", 503);
-    }
-    await state.supervisor.ensureStarted();
-    await state.supervisor.reload();
-  } catch {
-    const compensation = await compensateNewLink(ctx, state, record);
-    if (compensation) return compensation;
-    return fail("link_apply_failed", "The link could not be started.", 503);
-  }
-  const admission = awaitFirstAdmission(issued.id, APPLY_ADMISSION_TIMEOUT_MS, state.listener.onAuthenticatedCatalog);
-  const input = new TextEncoder().encode(JSON.stringify({ apiKeyId: issued.id, key: issued.key }));
-  try {
-    const result = await runner.run(buildExecArgv({ alias: body.alias, argv: remoteOcxArgv(["connect", "--link", "--key-stdin", "--tunnel-port", String(remotePort), "--link-id", id]), knownHostsFile: knownHosts }), { stdin: input, timeoutMs: APPLY_ADMISSION_TIMEOUT_MS });
-    if (result.code !== 0) {
-      void admission.catch(() => {});
-      const compensation = await compensateNewLink(ctx, state, record);
-      if (compensation) return compensation;
-      const hint = sshFailureHint(result.stderr);
-      return result.code === REMOTE_COMMAND_NOT_FOUND
-        ? fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, hint)
-        : fail("remote_connect_failed", "The remote link connection failed.", 502, hint);
-    }
-    try {
-      await admission;
-    } catch {
-      const compensation = await compensateNewLink(ctx, state, record);
-      return compensation ?? fail("admission_timeout", "The remote link did not authenticate a catalog request in time.", 502);
-    }
-    return Response.json({ linkId: id }, { status: 202 });
-  } catch (error) {
-    void admission.catch(() => {});
-    const compensation = await compensateNewLink(ctx, state, record);
-    return compensation ?? fail("remote_connect_failed", "The remote link connection failed.", 502, sshRunnerErrorHint(error));
-  } finally {
-    input.fill(0);
-  }
-}
-
 async function issue(ctx: ManagementContext): Promise<Response> {
   const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias", "tunnelPort"]);
   if (!body || typeof body.alias !== "string" || !isLinkPort(body.tunnelPort)) return fail("invalid_body", "alias and tunnelPort are required.", 400);
@@ -430,13 +86,18 @@ async function issue(ctx: ManagementContext): Promise<Response> {
   const record = { id, alias: body.alias, direction: "client-initiated" as const, hostKeyFingerprint: null, tunnelPort: body.tunnelPort, apiKeyId: issued.id, createdAt: new Date((ctx.deps.now ?? Date.now)()).toISOString() };
   let failureCode = "link_issue_failed";
   try {
-    const current = readStoreFor(ctx);
-    if (current.links.some(link => link.id === id)) throw new Error("link id collision");
-    if (current.links.some(link => link.alias === body.alias && link.direction === "client-initiated")) {
+    // Same atomic duplicate-check+append as the hub-initiated branch.
+    const writeOutcome = withConfigMutationLockSync((): "dup" | "written" => {
+      const current = readStoreFor(ctx);
+      if (current.links.some(link => link.id === id)) throw new Error("link id collision");
+      if (current.links.some(link => link.alias === body.alias && link.direction === "client-initiated")) return "dup";
+      writeStoreFor(ctx, { ...current, links: [...current.links, record] });
+      return "written";
+    });
+    if (writeOutcome === "dup") {
       const compensation = await compensateNewLink(ctx, state, record);
       return compensation ?? fail("link_exists", "A link for this alias already exists.", 409);
     }
-    writeStoreFor(ctx, { ...current, links: [...current.links, record] });
     await state.listener.ensureStarted();
     if (state.listener.status().state !== "listening") {
       failureCode = "listener_unavailable";
@@ -506,6 +167,30 @@ async function handleJoin(ctx: ManagementContext, state: LinkRouteState): Promis
   }
 }
 
+/**
+ * Restart a Home-initiated link's tunnel now: the dashboard's Retry and `ocx link reconnect`.
+ * The supervisor stops the current ssh child, if any, forgets its backoff or failed state and
+ * spawns a fresh attempt; status then reports it like any other attempt.
+ */
+async function reconnect(ctx: ManagementContext, state: LinkRouteState, id: string): Promise<Response> {
+  if (!LINK_ID.test(id)) return fail("invalid_link_id", "The link id is invalid.", 400);
+  const record = readStoreFor(ctx).links.find(link => link.id === id);
+  if (!record) return fail("link_not_found", "The link was not found.", 404);
+  if (record.direction !== "hub-initiated") {
+    return fail("link_not_home_initiated", "Only a Home-initiated link has a tunnel this computer can restart.", 409);
+  }
+  try {
+    // A reverse forward may only target a port the link listener owns, as when a link is applied.
+    await state.listener.ensureStarted();
+    if (state.listener.status().state !== "listening") return fail("listener_unavailable", "The link listener is unavailable.", 503);
+    await state.supervisor.ensureStarted();
+    if (!await state.supervisor.reconnect(id)) return fail("link_unavailable", "The link tunnel could not be restarted.", 503);
+  } catch {
+    return fail("link_unavailable", "The link tunnel could not be restarted.", 503);
+  }
+  return Response.json({ linkId: id });
+}
+
 async function remove(ctx: ManagementContext, state: LinkRouteState, id: string): Promise<Response> {
   if (!LINK_ID.test(id)) return fail("invalid_link_id", "The link id is invalid.", 400);
   const current = readStoreFor(ctx);
@@ -514,38 +199,46 @@ async function remove(ctx: ManagementContext, state: LinkRouteState, id: string)
   const body = await readManagementJsonBodyOr(ctx.req, {});
   if (!isRecord(body) || Object.keys(body).some(key => key !== "force") || (body.force !== undefined && typeof body.force !== "boolean")) return fail("invalid_body", "force must be a boolean.", 400);
   const force = body.force === true;
-  await state.supervisor.stopLink(id);
-  const restartTunnel = async (): Promise<void> => {
-    try {
-      await state.supervisor.ensureStarted();
-      await state.supervisor.reload();
-    } catch (error) {
-      console.warn(`[link] tunnel restart failed linkId=${id}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  };
-  if (!force && record.direction === "hub-initiated") {
-    try {
-      const result = await runnerFor(ctx).run(buildExecArgv({ alias: record.alias, argv: remoteOcxArgv(["disconnect"]), knownHostsFile: knownHostsFile(ctx) }), { timeoutMs: 30_000 });
-      if (result.code !== 0) {
+  const release = state.supervisor.holdLink?.(id);
+  try {
+    await state.supervisor.stopLink(id);
+    const restartTunnel = async (): Promise<void> => {
+      release?.();
+      try {
+        await state.supervisor.ensureStarted();
+        await state.supervisor.reload();
+      } catch (error) {
+        console.warn(`[link] tunnel restart failed linkId=${id}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    };
+    if (!force && record.direction === "hub-initiated") {
+      try {
+        const result = await runnerFor(ctx).run(buildExecArgv({ alias: record.alias, argv: remoteOcxArgv(["disconnect"]), knownHostsFile: knownHostsFile(ctx) }), { timeoutMs: 30_000 });
+        if (result.code !== 0) {
+          await restartTunnel();
+          return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshFailureHint(result.stderr));
+        }
+      } catch (error) {
         await restartTunnel();
-        return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshFailureHint(result.stderr));
+        return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshRunnerErrorHint(error));
       }
-    } catch (error) {
-      await restartTunnel();
-      return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshRunnerErrorHint(error));
     }
-  }
-  if (!revokeKeyIdempotent(ctx, record.apiKeyId)) return fail("key_revoke_failed", "The link key could not be revoked.", 502);
-  let next: LinkStore;
-  try {
-    const latest = readStoreFor(ctx);
-    next = { ...latest, links: latest.links.filter(link => link.id !== id) };
-    if (next.links.length !== latest.links.length) writeStoreFor(ctx, next);
-    clearCompensationFailed(id, compensationPath());
-  } catch { return fail("link_remove_failed", "The link record could not be removed.", 503); }
-  state.compensationFailures?.delete(id);
-  if (next.links.length === 0) await state.listener.close();
-  return Response.json({ linkId: id });
+    if (!revokeKeyIdempotent(ctx, record.apiKeyId)) return fail("key_revoke_failed", "The link key could not be revoked.", 502);
+    let next: LinkStore;
+    try {
+      next = withConfigMutationLockSync(() => {
+        const latest = readStoreFor(ctx);
+        const filtered = { ...latest, links: latest.links.filter(link => link.id !== id) };
+        if (filtered.links.length !== latest.links.length) writeStoreFor(ctx, filtered);
+        return filtered;
+      });
+      clearCompensationFailed(id, compensationPath());
+    } catch { return fail("link_remove_failed", "The link record could not be removed.", 503); }
+    state.compensationFailures?.delete(id);
+    await state.supervisor.reload();
+    if (next.links.length === 0) await state.listener.close();
+    return Response.json({ linkId: id });
+  } finally { release?.(); }
 }
 
 export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: LinkRouteState): Promise<Response | null> {
@@ -574,6 +267,7 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
     const dto: LinkStatusDto = projectLinkStatus(
       store, state.supervisor.status(), listenerStatus, ctx.config, readCompensation(),
       ctx.config.runtimeRole === "client" ? clientLinkTunnelStatus() : null,
+      ctx.config.runtimeRole === "client" && ctx.config.client?.link ? clientLinkStatusIdentity(ctx.config.client.link.linkId) : null,
     );
     for (const link of dto.links) {
       const failure = state.compensationFailures?.get(link.id);
@@ -596,17 +290,17 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
     return candidates(ctx);
   }
   if (url.pathname === "/api/link/probe" && req.method === "POST") {
-    const denied = auth(ctx, "dashboard");
+    const denied = auth(ctx, "either");
     if (denied) return denied;
     return probe(ctx, state);
   }
   if (url.pathname === "/api/link/confirm-host" && req.method === "POST") {
-    const denied = auth(ctx, "dashboard");
+    const denied = auth(ctx, "either");
     if (denied) return denied;
     return confirmHost(ctx, state);
   }
   if (url.pathname === "/api/link/apply" && req.method === "POST") {
-    const denied = auth(ctx, "dashboard");
+    const denied = auth(ctx, "either");
     if (denied) return denied;
     return apply(ctx, state);
   }
@@ -615,6 +309,14 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
     if (denied) return denied;
     return issue(ctx);
   }
+  const reconnectPath = req.method === "POST" ? /^\/api\/link\/([^/]+)\/reconnect$/.exec(path) : null;
+  if (reconnectPath) {
+    const denied = auth(ctx, "either");
+    if (denied) return denied;
+    let id: string;
+    try { id = decodeURIComponent(reconnectPath[1]!); } catch { return fail("invalid_link_id", "The link id is invalid.", 400); }
+    return reconnect(ctx, state, id);
+  }
   if (req.method === "DELETE" && path.startsWith("/api/link/")) {
     const denied = auth(ctx, "either");
     if (denied) return denied;

package/src/server/management/model-rows.ts

@@ -11,6 +11,7 @@
 import type { CatalogModel } from "../../codex/catalog";
 import { antigravityFamilyDisabled } from "../../providers/antigravity-effort-families";
 import { observeModelCacheRevision } from "../../codex/model-cache";
+import { isPassiveRead } from "../../lib/passive-read";
 import {
   captureExportConfigAdmission,
   detachedConfigSnapshot,
@@ -306,8 +307,9 @@ export async function listManagementModelRows(
    * that brings its own roster still sees exactly what a writer would, and the two cannot
    * disagree about the roster for any reason except the roster itself.
    */
+  // A passive read (#6959) also skips the entitlement refresh, which reaches the Codex accounts.
   const models = options.models === undefined
-    ? (await Promise.all([
+    ? isPassiveRead() ? [] : (await Promise.all([
       fetchAllModels(config, options.providerContentRevisions, projection => { config = projection; }),
       ensureCodexEntitlementFreshness(config, {
         waitMs: options.entitlementWaitMs ?? 3_000,

package/src/server/management/provider-overwrite-carry.ts

@@ -50,6 +50,7 @@ const RETRY_POLICY_VALIDATORS = {
  */
 export const PROVIDER_COMPAT_CARRY_FIELDS = [
   "preserveReasoningContentModels",
+  "preserveResponsesReasoningContent",
   "requiresReasoningPlaceholderModels",
   "foldDeveloperRoleToSystem",
   "reasoningWireFormat",
@@ -160,6 +161,8 @@ export function providerCompatFieldConfigError(provider: Record<string, unknown>
   if (fold !== undefined && typeof fold !== "boolean") return "foldDeveloperRoleToSystem must be a boolean";
   const hideRawReasoning = provider.hideRawReasoning;
   if (hideRawReasoning !== undefined && typeof hideRawReasoning !== "boolean") return "hideRawReasoning must be a boolean";
+  const preserveResponses = provider.preserveResponsesReasoningContent;
+  if (preserveResponses !== undefined && typeof preserveResponses !== "boolean") return "preserveResponsesReasoningContent must be a boolean";
   const wire = provider.reasoningWireFormat;
   if (wire !== undefined && !PROVIDER_REASONING_WIRE_FORMATS.includes(wire as never)) {
     return `reasoningWireFormat must be one of: ${PROVIDER_REASONING_WIRE_FORMATS.join(", ")}`;
@@ -204,6 +207,13 @@ export function applyProviderCompatPatchFields(
     else return { error: "hideRawReasoning must be a boolean" };
     touched = true;
   }
+  if (Object.hasOwn(rawBody, "preserveResponsesReasoningContent")) {
+    const value = rawBody.preserveResponsesReasoningContent;
+    if (value === null) delete next.preserveResponsesReasoningContent;
+    else if (typeof value === "boolean") next.preserveResponsesReasoningContent = value;
+    else return { error: "preserveResponsesReasoningContent must be a boolean" };
+    touched = true;
+  }
   if (Object.hasOwn(rawBody, "reasoningWireFormat")) {
     const value = rawBody.reasoningWireFormat;
     if (value === null) {

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

@@ -917,6 +917,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       // Presence only (#959 review): header names and values never leave the process.
       hasHeaders: !!p.headers && Object.keys(p.headers).length > 0,
       allowPrivateNetwork: p.allowPrivateNetwork === true,
+      preserveResponsesReasoningContent: p.preserveResponsesReasoningContent,
       liveModels: p.liveModels !== false,
       requestPacing: p.requestPacing,
       models: p.models ?? [],