@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/server/management/codex-prompt-routes.ts

@@ -30,11 +30,14 @@ import {
   composeProjection,
   computePromptProbeStateFingerprint,
   findInvalidCharacter,
+  importBaseVariant,
   inspectOwnership,
   normalizeBody,
   previewAdopt,
+  previewBaseImport,
   previewSalvage,
   readPromptLayers,
+  recoverPromptJournal,
   salvageProjection,
   selectBaseVariant,
   setToggle,
@@ -76,6 +79,7 @@ const WRITE_ERROR_STATUS: Record<WriteError, number> = {
   unknown_layer: 400,
   store_unreadable: 409,
   invalid_characters: 400,
+  body_too_large: 400,
   write_superseded: 409,
   // Not the caller's fault and not a race: the filesystem refused the write and the
   // transaction rolled itself back. 500 rather than 409 — retrying the same request
@@ -84,6 +88,8 @@ const WRITE_ERROR_STATUS: Record<WriteError, number> = {
   recovery_required: 409,
   locked: 409,
   unsafe: 422,
+  import_body_changed: 409,
+  unsupported_form: 409,
 };
 
 /** Read-only view for the route test that asserts every mapping is a client error. */
@@ -335,7 +341,12 @@ export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<R
     if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
     const id = body.id;
     if (typeof id !== "string") return fail(ctx, "invalid_body", 400, "id must be a string");
-    if (typeof body.enabled !== "boolean") return fail(ctx, "invalid_body", 400, "enabled must be a boolean");
+    // `null` is the restore-the-default verb: it deletes the line instead of
+    // writing the documented default back as a literal, so a later upstream
+    // change to the default still reaches this file.
+    if (typeof body.enabled !== "boolean" && body.enabled !== null) {
+      return fail(ctx, "invalid_body", 400, "enabled must be a boolean or null");
+    }
     const revision = revisionOf(body);
     if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
 
@@ -388,6 +399,109 @@ export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<R
     return settle(ctx, selectBaseVariant(selection, revision, paths(ctx)));
   }
 
+  if (url.pathname === "/api/codex-prompt/base/import" && req.method === "POST") {
+    // The adopt flow for `model_instructions_file`: preview first, write only on
+    // confirmation. The verb exists because /base/select refuses the `external`
+    // state by design — that refusal is about SILENT retargeting, and an
+    // explicit, previewed import is precisely the opt-in it protects.
+    //
+    // The preview carries the SERIALIZED variant file — `# {title}\n{body}` —
+    // not just the body: the heading is part of what Codex will read, so the
+    // thing confirmed must be the whole stored text, title included. Both byte
+    // counts are reported and separately named: `bodyBytes` is the budget the
+    // 64 KiB cap applies to, `serializedBytes` is the complete file.
+    const body = await readBody(ctx);
+    if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
+    const readState = readPromptLayers(paths(ctx));
+    if (!readState.readable) {
+      return fail(ctx, "config_unreadable", 409, "the configuration file exists but could not be read", { path: readState.configPath });
+    }
+    // The title is validated before anything is previewed or written: a caller
+    // that supplies one gets the same contract as a custom-layer title —
+    // 1-80 characters on a single line.
+    if (body.title !== undefined) {
+      const t = body.title;
+      if (typeof t !== "string" || t.trim().length === 0
+        || t.length > MAX_TITLE_CHARS || /[\r\n]/.test(t)) {
+        return fail(ctx, "invalid_title", 400, "title must be 1-80 characters on a single line");
+      }
+    }
+    const preview = previewBaseImport(paths(ctx), typeof body.title === "string" ? body.title : undefined);
+    if (preview.reason === "nothing_to_import") {
+      return fail(ctx, "nothing_to_import", 409,
+        "model_instructions_file is absent or already points at a managed variant");
+    }
+    if (preview.reason === "unsupported_form") {
+      return fail(ctx, "import_unsupported_form", 409, preview.detail, {
+        path: preview.rawPath,
+      });
+    }
+    if (preview.reason === "file_unreadable") {
+      return fail(ctx, "import_file_unreadable", 409, preview.detail, {
+        path: preview.resolvedPath ?? preview.rawPath,
+      });
+    }
+    if (preview.reason === "invalid_characters") {
+      return fail(ctx, "invalid_characters", 400, preview.detail, { path: preview.resolvedPath });
+    }
+    // Same boundary as every other write to this key: the 64 KiB cap applies to
+    // the BODY alone — the title heading lives outside that budget, unchanged
+    // from the managed-variant contract.
+    if (preview.reason === "body_too_large" || utf8Bytes(preview.body!) > MAX_BODY_BYTES) {
+      return fail(ctx, "body_too_large", 400, `the file body exceeds ${MAX_BODY_BYTES} bytes`, {
+        path: preview.resolvedPath,
+      });
+    }
+    if (preview.reason === "slots_full") {
+      return fail(ctx, "variant_slots_full", 409,
+        `at most ${MAX_BASE_VARIANTS} base variants; delete one first`, {
+          maxBaseVariants: MAX_BASE_VARIANTS,
+          serialized: preview.serialized,
+          resolvedPath: preview.resolvedPath,
+        });
+    }
+    if (body.confirm !== true) {
+      // Preview writes nothing, by construction: previewBaseImport is a pure read.
+      return jsonResponse({
+        ok: true,
+        changed: false,
+        preview: {
+          rawPath: preview.rawPath,
+          resolvedPath: preview.resolvedPath,
+          serialized: preview.serialized,
+          serializedBytes: utf8Bytes(preview.serialized!),
+          bodyBytes: utf8Bytes(preview.body!),
+          suggestedTitle: preview.suggestedTitle,
+          effectiveTitle: preview.effectiveTitle,
+          previewSha256: preview.previewSha256,
+        },
+      }, 200, req, ctx.config);
+    }
+    const revision = revisionOf(body);
+    if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
+    // The preview hash is REQUIRED — a confirm that does not name exactly what
+    // was previewed (serialized text, title included) cannot be checked against
+    // it and is refused without writing.
+    const previewSha256 = body.previewSha256;
+    if (typeof previewSha256 !== "string" || !/^[0-9a-f]{64}$/.test(previewSha256)) {
+      return fail(ctx, "import_preview_required", 400,
+        "confirm requires the previewSha256 returned by a preview of the same title");
+    }
+    if (previewSha256 !== preview.previewSha256) {
+      // The file or the selected title moved between preview and confirm. Refuse
+      // rather than import a serialization nobody previewed.
+      return fail(ctx, "import_body_changed", 409,
+        "the preview no longer matches; preview it again", {
+          resolvedPath: preview.resolvedPath,
+        });
+    }
+    return settle(ctx, importBaseVariant(
+      { title: typeof body.title === "string" ? body.title : undefined, previewSha256 },
+      revision,
+      paths(ctx),
+    ));
+  }
+
   if (url.pathname === "/api/codex-prompt/base" && req.method === "PUT") {
     const body = await readBody(ctx);
     if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
@@ -568,11 +682,28 @@ export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<R
       return settle(ctx, adoptDeveloperInstructions(revision, paths(ctx)));
     }
 
-    // journal-present: recovery lives inside WP1's commit and is not exported.
-    // Any ordinary mutation replays it on its own path, so the honest answer is
-    // to name the state rather than duplicate the transaction here.
+    if (drift === "journal-present") {
+      // Recovery as its own locked operation — never a disguised layers write.
+      // The GUI used to replay recovery through a byte-identical custom PUT,
+      // which projected custom=[] over a config still carrying instructions
+      // whenever the store file was missing.
+      if (!confirm) {
+        return jsonResponse({
+          ok: true,
+          changed: false,
+          preview: { drift, storePath: snapshot.storePath },
+        }, 200, req, ctx.config);
+      }
+      if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
+      if (revision !== snapshot.revision) {
+        return fail(ctx, "stale_revision", 409, "the configuration moved since it was read");
+      }
+      return settle(ctx, recoverPromptJournal(paths(ctx)));
+    }
+
+    // A drift kind this build does not repair: name it rather than guess.
     return fail(ctx, "repair_unsupported", 409,
-      "a write journal is present; recovery runs automatically on the next write", {
+      "this drift has no repair on this route", {
         drift, storePath: snapshot.storePath,
       });
   }

package/src/server/management/codex-role-auto-assign.ts

@@ -209,7 +209,7 @@ export async function proposeDelegationModel(options: {
     role: DELEGATED_WORK_ROLE,
     model: options.config.injectionModel ?? null,
     effort: options.config.injectionEffort ?? null,
-  }], outcomes, classified, { alwaysProposeEffort: true });
+  }], outcomes, classified);
   return {
     sizingModel,
     sizingError,

package/src/server/management/grok-coupon-routes.ts

@@ -22,10 +22,12 @@ import {
 } from "../../grok/reset-coupons";
 import {
   getGrokResetCouponOperationAccountId,
+  isTerminalGrokCouponReplay,
   markGrokResetCouponAttempt,
   openGrokResetCouponOperation,
   recordGrokResetCouponSettlement,
   readGrokResetCouponTerminalReplay,
+  refuseGrokResetCouponBeforeOpen,
   settleGrokResetCouponPreflightRefusal,
   type GrokResetCouponOperationRecord,
 } from "../../grok/reset-coupon-ledger";
@@ -140,10 +142,6 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     const { accountId: rawAccountId, tokenId: requestedTokenId, operationId } = body;
 
-    if (requestedTokenId !== undefined && (typeof requestedTokenId !== "string" || requestedTokenId.trim() === "")) {
-      return jsonResponse({ error: { code: "invalid_token_id", message: "tokenId must be a non-empty string" } }, 400, req, config);
-    }
-
     if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
       return jsonResponse(
         { error: { code: "invalid_operation_id", message: "operationId must be a valid UUIDv4" } },
@@ -153,47 +151,87 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       );
     }
 
+    /**
+     * Once a caller supplies an operationId, that id may already name an operation that
+     * another request is spending. A refusal from this request must not read as
+     * definitive then, or the caller drops its hold and mints a replacement.
+     */
+    const uncertain = (id: string): Response => jsonResponse({ operationId: id, error: {
+      code: "attempt_in_progress",
+      message: "This request did not attempt a redemption, but another request may hold this operation; retry the same operationId to read its durable state",
+    } }, 409, req, config);
+    /** Refuse before open: definitive only when the supplied id is durably reserved as failed. */
+    const preOpenRefusal = (definitive: Response, code: string, knownAccountId?: string): Response => {
+      if (operationId === undefined) return definitive;
+      if (knownAccountId === undefined) return uncertain(operationId);
+      try {
+        const result = refuseGrokResetCouponBeforeOpen({
+          operationId, accountId: knownAccountId, code,
+          tokenId: typeof requestedTokenId === "string" ? requestedTokenId : undefined,
+        });
+        if (result.kind === "recorded") return definitive;
+        if (result.kind === "replay") return jsonResponse({
+          code: result.code, replayed: true, tokenId: result.tokenId, settledAt: result.settledAt,
+        }, 200, req, config);
+        if (result.kind === "identity-mismatch") return jsonResponse({ error: {
+          code: "operation_id_owned_by_another_account",
+          message: "Operation ID was previously registered with a different account or token",
+        } }, 409, req, config);
+        return uncertain(operationId);
+      } catch {
+        return uncertain(operationId);
+      }
+    };
+
+    if (requestedTokenId !== undefined && (typeof requestedTokenId !== "string" || requestedTokenId.trim() === "")) {
+      return preOpenRefusal(jsonResponse({ error: { code: "invalid_token_id", message: "tokenId must be a non-empty string" } }, 400, req, config), "invalid_token_id");
+    }
+
     let recordedAccountId: string | undefined;
     if (rawAccountId === undefined && operationId !== undefined) {
       try { recordedAccountId = getGrokResetCouponOperationAccountId(operationId); }
       catch {
-        return jsonResponse({ error: { code: "ledger_unavailable", message: "Coupon ledger could not be read or locked; no redemption was attempted" } }, 503, req, config);
+        return uncertain(operationId);
       }
     }
     let accountId: string;
     try {
       accountId = resolveTargetAccountId(rawAccountId ?? recordedAccountId);
     } catch (err) {
-      return jsonResponse(
+      return preOpenRefusal(jsonResponse(
         { error: { code: "no_account", message: err instanceof Error ? err.message : String(err) } },
         400,
         req,
         config,
-      );
+      ), "no_account");
     }
 
     let tokenSnapshot;
     try {
       tokenSnapshot = await getValidAccessSnapshotForAccount("xai", accountId, { requireUsableAccount: true });
     } catch (err) {
-      return jsonResponse(
+      return preOpenRefusal(jsonResponse(
         { error: { code: "auth_failed", message: "Failed to resolve valid xAI credentials for account" } },
         401,
         req,
         config,
-      );
+      ), "auth_failed", accountId);
     }
 
     // Journaling and Idempotency settlement check
     const effectiveOpId = operationId ?? crypto.randomUUID();
-    if (grokCouponInFlightAttempts.has(effectiveOpId)) return jsonResponse({ error: {
+    if (grokCouponInFlightAttempts.has(effectiveOpId)) return jsonResponse({ operationId: effectiveOpId, error: {
       code: "attempt_in_progress", message: "This operation still has an active request; retry later",
     } }, 409, req, config);
     let opRecord: GrokResetCouponOperationRecord;
     try {
       opRecord = openGrokResetCouponOperation({ accountId, tokenId: requestedTokenId, operationId: effectiveOpId });
     } catch {
-      return jsonResponse({ error: { code: "ledger_unavailable", message: "Coupon ledger could not be read or locked; no redemption was attempted" } }, 503, req, config);
+      // A failed open cannot prove that no earlier request already opened this id.
+      return jsonResponse({ operationId: effectiveOpId, error: {
+        code: "ledger_unavailable",
+        message: "Coupon ledger could not be read or locked; this request did not attempt a redemption. Retry the same operationId",
+      } }, 503, req, config);
     }
 
     let resolvedTokenId = requestedTokenId ?? opRecord.tokenId;
@@ -201,6 +239,14 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     if (opRecord.kind === "replay") {
       if (opRecord.code !== undefined) {
+        // Replay only a definitive outcome; a recorded code that means "unconfirmed"
+        // must keep the caller on this operation.
+        if (!isTerminalGrokCouponReplay(opRecord, accountId, requestedTokenId)) {
+          return jsonResponse({ operationId: effectiveOpId, error: {
+            code: "attempt_unresolved",
+            message: "This operation's recorded outcome is unconfirmed; preserve this operationId and do not create a replacement attempt",
+          } }, 409, req, config);
+        }
         return jsonResponse(
           {
             code: opRecord.code,
@@ -230,6 +276,7 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
         // retry with the recorded token and preserve the operationId.
         return jsonResponse(
           {
+            operationId: effectiveOpId,
             error: {
               code: "operation_token_mismatch",
               message: "Operation was attempted with a different coupon; preserve the operationId and retry with the recorded tokenId",
@@ -282,7 +329,7 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       } }, 409, req, config);
     }
 
-    if (opRecord.kind === "token-mismatch") return jsonResponse({ error: {
+    if (opRecord.kind === "token-mismatch") return jsonResponse({ operationId: effectiveOpId, error: {
       code: "operation_token_mismatch", message: "Operation ID was previously registered with a different coupon",
     } }, 409, req, config);
 
@@ -301,11 +348,14 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
     }
 
     if (opRecord.kind !== "execute") {
+      // A capacity refusal cannot reserve the id, so an earlier same-id request still in
+      // credential resolution may open it once records expire: keep the caller on the id.
       return jsonResponse(
         {
+          ...(operationId !== undefined ? { operationId: effectiveOpId } : {}),
           error: {
             code: opRecord.kind,
-            message: "Coupon ledger capacity or unavailable failure",
+            message: "Coupon ledger is at capacity; this request did not attempt a redemption. Retry the same operationId later",
           },
         },
         503,
@@ -324,14 +374,13 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
         if (result.kind === "replay") return jsonResponse({
           code: result.code, replayed: true, tokenId: result.tokenId, settledAt: result.settledAt,
         }, 200, req, config);
-        return jsonResponse({ error: {
+        return jsonResponse({ operationId: effectiveOpId, error: {
           code: "operation_state_changed",
           message: "Another request changed this operation during inspection; retry the same operationId to read its durable state",
         } }, 409, req, config);
       } catch {
-        return jsonResponse({ error: {
-          code: "ledger_unavailable", message: "Coupon refusal could not be recorded; no redemption was attempted",
-        } }, 503, req, config);
+        // The refusal could not be recorded, so the operation may still be claimed elsewhere.
+        return uncertain(effectiveOpId);
       }
     };
 
@@ -345,6 +394,10 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
         const remaining = await getGrokRemainingResets({ accessToken: tokenSnapshot.accessToken });
         tokens = remaining.tokens ?? [];
       } catch (err) {
+        // Close the still-open operation before reporting a definitive failure: once it is
+        // recorded as failed it can never be claimed, so the caller may safely start over.
+        const changed = settlePreflightRefusal("fetch_resets_failed", resolvedTokenId);
+        if (changed) return changed;
         return jsonResponse(
           { error: { code: "fetch_resets_failed", message: err instanceof Error ? err.message : String(err) } },
           502,
@@ -389,6 +442,8 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     if (resolvedTokenId === undefined) {
       // Unreachable: every path above either resolves a token or returns.
+      const changed = settlePreflightRefusal("token_unresolved");
+      if (changed) return changed;
       return jsonResponse(
         { error: { code: "token_unresolved", message: "No reset coupon token could be resolved" } },
         500,
@@ -403,6 +458,7 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       // on this operationId again regardless of how stale the mark looks.
       return jsonResponse(
         {
+          operationId: effectiveOpId,
           error: {
             code: "attempt_in_progress",
             message: "A redemption attempt for this operation is still running; retry later",
@@ -433,17 +489,12 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
           if (winner) return jsonResponse({
             code: winner.code, replayed: true, tokenId: winner.tokenId, settledAt: winner.settledAt,
           }, 200, req, config);
-          return jsonResponse({ error: {
-            code: "attempt_in_progress", message: "Another request already claimed this operation; no redemption was attempted",
-          } }, 409, req, config);
+          return uncertain(effectiveOpId);
         }
-      } catch (err) {
-        return jsonResponse(
-          { error: { code: "attempt_mark_failed", message: err instanceof Error ? err.message : String(err) } },
-          500,
-          req,
-          config,
-        );
+      } catch {
+        // The claim write failed or was contended: this request dispatched nothing, but a
+        // concurrent holder of this operation may be spending, so keep the caller on it.
+        return uncertain(effectiveOpId);
       }
 
       try {

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

@@ -0,0 +1,192 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { assertSshAlias, buildExecArgv, buildFingerprintArgv, buildProbeArgv, REMOTE_COMMAND_NOT_FOUND, REMOTE_PLATFORM_UNSUPPORTED, remoteOcxArgv } from "../../link/ssh-argv";
+import { parseFingerprintLine } from "../../link/fingerprint";
+import { LINK_CATALOG_MAX_BYTES, LINK_RELAY_VERIFY_MS, isChildHealth, linkCommandBudget, linkRestartBudget, parseChildHttp, remoteChildHttpArgv, REMOTE_CURL_PREFLIGHT } from "../../link/remote-probe";
+import { newLinkId, type LinkStore } from "../../link/store";
+import { SshRunnerError, boundHint, sshFailureHint, sshRunnerErrorHint, type SshRunResult } from "../../link/ssh-runner";
+import { withConfigMutationLockSync } from "../../config/mutation-lock";
+import type { ManagementContext } from "./context";
+import { readManagementJsonBodyOr } from "./body";
+import { fail, exactBody, port, isRecord, runnerFor, readStoreFor, writeStoreFor, knownHostsFile, putKnownHost, issueKey, compensateNewLink, type LinkRouteState } from "./link-route-state";
+
+const PROBE_TTL_MS = 5 * 60_000;
+const MIN_REMOTE_OCX = [2, 66, 0] as const;
+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|$)/;
+
+/** Same-alias operations refuse overlap rather than overwrite a confirmed generation. */
+async function serialized(state: LinkRouteState, alias: string, action: () => Promise<Response>): Promise<Response> {
+  const operations = state.operations ??= new Set();
+  if (operations.has(alias)) return fail("link_operation_in_progress", "A link operation for this alias is already running.", 409);
+  operations.add(alias);
+  try { return await action(); } finally { operations.delete(alias); }
+}
+
+function remoteFailure(result: SshRunResult, code: string, message: string): Response | null {
+  if (result.code === REMOTE_PLATFORM_UNSUPPORTED) return fail("remote_platform_unsupported", "Remote Link Children require macOS or Linux; Windows is unsupported.", 409);
+  if (result.code === REMOTE_COMMAND_NOT_FOUND) return fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr));
+  return result.code === 0 ? null : fail(code, message, 502, sshFailureHint(result.stderr));
+}
+
+export async function probe(ctx: ManagementContext, state: LinkRouteState): Promise<Response> {
+  const value = await readManagementJsonBodyOr(ctx.req, null);
+  const body = exactBody(value, ["alias"]) ?? exactBody(value, ["alias", "includeVersion"]);
+  if (!body || typeof body.alias !== "string" || (body.includeVersion !== undefined && body.includeVersion !== true)) return fail("invalid_body", "alias is required.", 400);
+  const alias = body.alias;
+  try { assertSshAlias(alias); } catch { return fail("invalid_alias", "alias must be a valid SSH host alias.", 400); }
+  return serialized(state, alias, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-link-probe-"));
+    const path = join(dir, "known_hosts");
+    writeFileSync(path, "", { mode: 0o600 });
+    const runner = runnerFor(ctx), now = ctx.deps.now ?? Date.now;
+    try {
+      const started = now();
+      const result = await runner.run(buildProbeArgv({ alias, tempKnownHostsFile: path }), { timeoutMs: 30_000 });
+      const latency = Math.max(0, now() - started);
+      if (result.code !== 0) return fail("probe_failed", "SSH host probing failed.", 502, sshFailureHint(result.stderr));
+      const fp = await runner.run(buildFingerprintArgv(path), { timeoutMs: 10_000 });
+      if (fp.code !== 0) return fail("fingerprint_failed", "The SSH host fingerprint could not be read.", 502, sshFailureHint(fp.stderr));
+      const parsed = parseFingerprintLine(fp.stdout.trim());
+      const line = readFileSync(path, "utf8").trim().split(/\r?\n/).filter(Boolean).at(-1);
+      if (!line) return fail("fingerprint_failed", "The SSH probe did not record a host key.", 502);
+      let ocxVersion: string | undefined;
+      if (body.includeVersion === true) {
+        const versionResult = await runner.run(buildExecArgv({ alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 });
+        const denied = remoteFailure(versionResult, "version_probe_failed", "The remote ocx version could not be read.");
+        if (denied) return denied;
+        const parsedVersion = parseVersion(versionResult.stdout);
+        if (!parsedVersion) return fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502);
+        ocxVersion = parsedVersion.version;
+      }
+      state.pendingHosts.set(alias, { alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, knownHostLine: line, probedAt: now(), sshLatencyMs: latency });
+      state.confirmedHosts?.delete(alias);
+      return Response.json({ alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, ...(ocxVersion === undefined ? {} : { ocxVersion }) });
+    } catch (error) { return fail("probe_failed", "SSH host probing failed.", 502, sshRunnerErrorHint(error)); }
+    finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+}
+
+function parseVersion(stdout: string): { version: string; parts: number[] } | null {
+  const match = REMOTE_OCX_VERSION.exec(stdout.trim().split(/\r?\n/)[0] ?? "");
+  return match ? { version: match.slice(1, 4).join(".") + (match[4] ?? "") + (match[5] ?? ""), parts: match.slice(1, 4).map(Number) } : null;
+}
+
+export 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 alias = body.alias;
+  return serialized(state, alias, async () => {
+    const pending = state.pendingHosts.get(alias), 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 dir = mkdtempSync(join(tmpdir(), "ocx-link-confirm-")), path = join(dir, "known_hosts");
+    writeFileSync(path, pending.knownHostLine + "\n", { mode: 0o600 });
+    try {
+      const started = now();
+      const result = await runnerFor(ctx).run(buildExecArgv({ alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 });
+      const denied = remoteFailure(result, "version_probe_failed", "The remote ocx version could not be confirmed.");
+      if (denied) return denied;
+      const version = parseVersion(result.stdout);
+      if (!version) return fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502);
+      const cmp = version.parts.findIndex((part, i) => part !== MIN_REMOTE_OCX[i]);
+      if (cmp >= 0 && version.parts[cmp]! < MIN_REMOTE_OCX[cmp]!) return fail("remote_ocx_outdated", "The remote OpenCodex is older than 2.66.0.", 409, boundHint("opencodex " + version.version));
+      if (state.pendingHosts.get(alias) !== pending || now() - pending.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host probe changed or expired.", 409);
+      withConfigMutationLockSync(() => putKnownHost(knownHostsFile(ctx), alias, pending.knownHostLine));
+      const confirmed = { ...pending, sshLatencyMs: Math.max(pending.sshLatencyMs ?? 0, now() - started), ocxVersion: version.version };
+      (state.confirmedHosts ??= new Map()).set(alias, confirmed);
+      state.pendingHosts.delete(alias);
+      return Response.json({ alias, fingerprint: pending.fingerprint, ocxVersion: version.version });
+    } catch (error) { return fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshRunnerErrorHint(error)); }
+    finally { rmSync(dir, { recursive: true, force: true }); }
+  });
+}
+
+function parsePort(stdout: string): number | null {
+  try { const value: unknown = JSON.parse(stdout.trim()); return isRecord(value) && Object.keys(value).length === 1 && port(value.port) ? value.port : null; }
+  catch { return null; }
+}
+
+export async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Response> {
+  const value = await readManagementJsonBodyOr(ctx.req, null);
+  const body = exactBody(value, ["alias"]) ?? exactBody(value, ["alias", "fingerprint"]);
+  if (!body || typeof body.alias !== "string" || (body.fingerprint !== undefined && typeof body.fingerprint !== "string")) return fail("invalid_body", "alias and optional fingerprint are required.", 400);
+  const alias = body.alias;
+  return serialized(state, alias, async () => {
+    const confirmed = state.confirmedHosts?.get(alias), now = ctx.deps.now ?? Date.now;
+    if (!confirmed) return fail("host_not_confirmed", "Confirm the SSH host before applying the link.", 409);
+    if (now() - confirmed.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host confirmation has expired.", 409);
+    if (body.fingerprint !== undefined && body.fingerprint !== confirmed.fingerprint) return fail("host_fingerprint_mismatch", "The apply fingerprint does not match the confirmed host.", 409);
+    if (readStoreFor(ctx).links.some(link => link.alias === alias && link.direction === "hub-initiated")) return fail("link_exists", "A link for this alias already exists.", 409);
+    const dir = mkdtempSync(join(tmpdir(), "ocx-link-apply-")), knownHosts = join(dir, "known_hosts");
+    writeFileSync(knownHosts, confirmed.knownHostLine + "\n", { mode: 0o600 });
+    const runner = runnerFor(ctx), budget = linkCommandBudget(confirmed.sshLatencyMs);
+    const run = (argv: readonly string[], timeoutMs = budget, maxOutputBytes?: number) => runner.run(buildExecArgv({ alias, argv, knownHostsFile: knownHosts }), { timeoutMs, ...(maxOutputBytes === undefined ? {} : { maxOutputBytes }) });
+    let record: LinkStore["links"][number] | undefined, input: Uint8Array | undefined;
+    let remoteMayBeConnected = false, phase = "remote_port";
+    const failed = async (response: Response): Promise<Response> => {
+      const compensation = record ? await compensateNewLink(ctx, state, record) : null;
+      const outcome = compensation ?? response;
+      if (!remoteMayBeConnected) return outcome;
+      const payload = await outcome.json() as Record<string, unknown>;
+      return Response.json({ ...payload, residual: true, recovery: "Run ocx disconnect and ocx restart on the Child before retrying." }, { status: outcome.status });
+    };
+    try {
+      const chosen = await run(remoteOcxArgv(["link", "port"]));
+      const denied = remoteFailure(chosen, "remote_port_failed", "The remote link port could not be determined.");
+      if (denied) return denied;
+      const remotePort = parsePort(chosen.stdout);
+      if (!remotePort) return fail("remote_port_failed", "The remote link port could not be determined.", 502);
+      phase = "child_preflight";
+      const configured = await run(remoteOcxArgv(["config", "show", "--json"]));
+      let childConfig: unknown = null;
+      try { if (configured.code === 0) childConfig = JSON.parse(configured.stdout); } catch { /* fail closed */ }
+      if (!isRecord(childConfig) || !port(childConfig.port)) return fail("child_preflight_failed", "The Child effective configuration could not be read.", 502);
+      if ((childConfig.runtimeRole ?? "standalone") !== "standalone") return fail("child_restart_unsupported", "The Child must run standalone OpenCodex; an existing Hub or Child cannot be converted by Add Child.", 409);
+      const childPort = childConfig.port;
+      if ((await run(REMOTE_CURL_PREFLIGHT)).code !== 0) return fail("child_curl_missing", "Install curl on the Child before connecting a Remote Link.", 409);
+      const before = await run(remoteChildHttpArgv(childPort, "healthz"));
+      const beforeHealth = before.code === 0 ? parseChildHttp(before.stdout) : null;
+      if (!isChildHealth(beforeHealth, "standalone", childPort)) return fail("child_restart_unsupported", "The Child must run a standalone OpenCodex with bound restart support; update or disconnect it before linking.", 409);
+      state.confirmedHosts?.delete(alias);
+      phase = "home_setup";
+      const id = newLinkId(), issued = issueKey(ctx, "link:" + alias);
+      record = { id, alias, direction: "hub-initiated", hostKeyFingerprint: confirmed.fingerprint, tunnelPort: remotePort, apiKeyId: issued.id, createdAt: new Date(now()).toISOString() };
+      withConfigMutationLockSync(() => {
+        const current = readStoreFor(ctx);
+        if (current.links.some(link => link.alias === alias && link.direction === "hub-initiated")) throw new Error("link exists");
+        writeStoreFor(ctx, { ...current, links: [...current.links, record!] });
+      });
+      await state.listener.ensureStarted();
+      if (state.listener.status().state !== "listening") return await failed(fail("listener_unavailable", "The link listener is unavailable.", 503));
+      await state.supervisor.ensureStarted();
+      await state.supervisor.reload();
+      phase = "remote_connect";
+      input = new TextEncoder().encode(JSON.stringify({ apiKeyId: issued.id, key: issued.key }));
+      remoteMayBeConnected = true;
+      const connected = await runner.run(buildExecArgv({ alias, argv: remoteOcxArgv(["connect", "--link", "--key-stdin", "--tunnel-port", String(remotePort), "--link-id", id]), knownHostsFile: knownHosts }), { stdin: input, timeoutMs: budget });
+      const connectDenied = remoteFailure(connected, "remote_connect_failed", "The Child enrollment command failed.");
+      if (connectDenied) return await failed(connectDenied);
+      input.fill(0);
+      phase = "child_restart";
+      const restarted = await run(remoteOcxArgv(["restart"]), linkRestartBudget(confirmed.sshLatencyMs));
+      if (restarted.code !== 0) return await failed(fail("child_restart_failed", "The Child restart could not be verified.", 502, sshFailureHint(restarted.stderr)));
+      phase = "child_relay";
+      const deadline = now() + LINK_RELAY_VERIFY_MS, remaining = () => Math.max(1, deadline - now());
+      const health = await run(remoteChildHttpArgv(childPort, "healthz", remaining()), remaining());
+      if (!isChildHealth(health.code === 0 ? parseChildHttp(health.stdout) : null, "client", childPort)) return await failed(fail("child_runtime_not_client", "The Child is not serving the client runtime after restart.", 502));
+      let admitted = false;
+      const unsubscribe = state.listener.onAuthenticatedCatalog(keyId => { if (keyId === issued.id) admitted = true; });
+      try {
+        if (now() >= deadline) return await failed(fail("child_relay_timeout", "The Child relay verification deadline expired.", 502));
+        const catalog = await run(remoteChildHttpArgv(childPort, "v1/catalog", remaining()), remaining(), LINK_CATALOG_MAX_BYTES);
+        let data: unknown = null;
+        try { if (catalog.code === 0) data = parseChildHttp(catalog.stdout); } catch { /* malformed is not a completed catalog */ }
+        if (!isRecord(data) || !Array.isArray(data.models) || !admitted || now() > deadline) return await failed(fail("child_relay_failed", "The Child did not relay a complete authenticated catalog through this Home.", 502));
+        return Response.json({ linkId: id }, { status: 202 });
+      } finally { unsubscribe(); }
+    } catch (error) {
+      return await failed(fail(phase + (error instanceof SshRunnerError && error.code === "timeout" ? "_timeout" : "_failed"), "Remote Link failed during " + phase.replaceAll("_", " ") + ".", 502, sshRunnerErrorHint(error)));
+    } finally { input?.fill(0); rmSync(dir, { recursive: true, force: true }); }
+  });
+}