@bitkyc08/opencodex 2.68.0 → 2.69.0-preview.20260928

package/src/cli/opencode.ts

@@ -51,6 +51,8 @@ import type { OcxConfig } from "../types";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { withoutSiblingMarker } from "../codex/sibling-start";
+import { parseJsonc } from "../lib/jsonc";
+export { parseJsonc };
 
 /**
  * The provider-block serializer, its constants, and the config-path helpers now live in
@@ -124,89 +126,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/**
- * Strip `//` and block comments outside string literals. Escape-aware so a quote inside
- * an escaped sequence cannot flip string state and expose config text to the stripper.
- */
-function stripJsonComments(text: string): string {
-  let out = "";
-  let inString = false;
-  let inLine = false;
-  let inBlock = false;
-  for (let i = 0; i < text.length; i++) {
-    const ch = text[i]!;
-    const next = text[i + 1];
-    if (inLine) {
-      if (ch === "\n") {
-        inLine = false;
-        out += ch;
-      }
-      continue;
-    }
-    if (inBlock) {
-      // Newlines are preserved so JSON.parse error positions stay meaningful.
-      if (ch === "\n") out += ch;
-      else if (ch === "*" && next === "/") { inBlock = false; i++; }
-      continue;
-    }
-    if (inString) {
-      out += ch;
-      if (ch === "\\") {
-        const escaped = text[i + 1];
-        if (escaped !== undefined) { out += escaped; i++; }
-        continue;
-      }
-      if (ch === "\"") inString = false;
-      continue;
-    }
-    if (ch === "\"") { inString = true; out += ch; continue; }
-    if (ch === "/" && next === "/") { inLine = true; i++; continue; }
-    if (ch === "/" && next === "*") { inBlock = true; i++; continue; }
-    out += ch;
-  }
-  return out;
-}
-
-/** Drop commas that sit directly before `}` or `]`, ignoring string contents. */
-function stripTrailingCommas(text: string): string {
-  let out = "";
-  let inString = false;
-  for (let i = 0; i < text.length; i++) {
-    const ch = text[i]!;
-    if (inString) {
-      out += ch;
-      if (ch === "\\") {
-        const escaped = text[i + 1];
-        if (escaped !== undefined) { out += escaped; i++; }
-        continue;
-      }
-      if (ch === "\"") inString = false;
-      continue;
-    }
-    if (ch === "\"") { inString = true; out += ch; continue; }
-    if (ch === ",") {
-      let j = i + 1;
-      while (j < text.length && /\s/.test(text[j]!)) j++;
-      if (text[j] === "}" || text[j] === "]") continue;
-    }
-    out += ch;
-  }
-  return out;
-}
-
-/**
- * opencode documents opencode.json as JSONC, so a valid user config may carry comments
- * or trailing commas. Strict JSON.parse runs first and untouched — the tolerant path is
- * only attempted when that throws, keeping well-formed configs away from the stripper.
- */
-export function parseJsonc(text: string): unknown {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return JSON.parse(stripTrailingCommas(stripJsonComments(text)));
-  }
-}
-
 /** Model key as the proxy routes it: `provider/id` for routed models, bare slug for native OpenAI entries. */
 export function opencodeModelKey(provider: string, id: string): string {
   return provider === "native" ? id : `${provider}/${id}`;

package/src/cli/registry.ts

@@ -416,12 +416,13 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "export",
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo|cline> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast, omo, Cline) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo|cline|kilo|droid> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",
       "Cline exports a two-document bundle: settings for providers.json and catalog for sibling models.json. Use integration client enable --client cline for a journaled write.",
+      "Droid exports documented customModels for settings.json; use integration client enable --client droid for a journaled write.",
       "The config never contains a real key; it carries a documented env reference or a non-secret loopback placeholder.",
       "The destination path is printed for merging by hand — ocx never writes your real client config.",
     ],

package/src/cli/status.ts

@@ -31,6 +31,8 @@ import { tokenCollidesWithAdmin } from "../lib/admin-secrets";
 export { proxyHealthFailureReason, isConnectionRefused, isUncleanExitEvidence, probeUncleanExitState } from "./status-probes";
 export type { ListenTarget } from "./status-probes";
 import { checkProxyHealth, probeUncleanExitState, type ListenTarget } from "./status-probes";
+import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability";
+import { fetchBoundLocalManagementRead } from "../server/local-management-read-client";
 
 /**
  * The state of the data-plane admission secret the SERVICE will use. State only -- never the value.
@@ -235,6 +237,84 @@ function statusDashboardUrl(config: StatusListenConfig, hostname: string | undef
   return `http://${dashboardHostname}:${port}/`;
 }
 
+const STARTUP_HEALTH_BOOLEAN_FIELDS = [
+  "routingInjected", "localRoutingDependency", "autostartEnabled", "rebootSafe",
+  "serviceInstalled", "serviceViable", "serviceEnabled", "serviceRunning",
+  "serviceStale", "serviceConflict", "shimInstalled", "shimHealthy",
+  "serviceSupported", "diagnosticStale",
+] as const;
+
+export async function fetchLiveStartupHealth(
+  live: NonNullable<Awaited<ReturnType<typeof findLiveProxy>>>,
+  deps: Parameters<typeof fetchBoundLocalManagementRead>[2] = {},
+): Promise<StartupHealth | null> {
+  const result = await fetchBoundLocalManagementRead(
+    live, LOCAL_MANAGEMENT_READ_PATHS.startupHealth, { timeoutMs: 1_500, ...deps, requireResponseProof: true },
+  );
+  if (result.kind !== "response" || !result.response.ok) return null;
+  let payload: unknown;
+  try { payload = await result.response.json(); } catch { return null; }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const row = payload as Record<string, unknown>;
+  if (row.status !== "native" && row.status !== "protected" && row.status !== "at-risk") return null;
+  if (row.protection !== "service" && row.protection !== "shim" && row.protection !== "none") return null;
+  if (row.routingKind !== "native" && row.routingKind !== "opencodex-local"
+    && row.routingKind !== "custom-local" && row.routingKind !== "custom-remote" && row.routingKind !== "unknown") return null;
+  if (row.shimCoverage !== "full" && row.shimCoverage !== "cli-only" && row.shimCoverage !== "none") return null;
+  if (typeof row.platform !== "string") return null;
+  if (row.recommendedCommand !== null && typeof row.recommendedCommand !== "string") return null;
+  if (!row.commands || typeof row.commands !== "object" || Array.isArray(row.commands)) return null;
+  for (const key of ["installService", "repairService", "installShim", "restoreNative"] as const) {
+    if (typeof (row.commands as Record<string, unknown>)[key] !== "string") return null;
+  }
+  if (row.routingAdoption !== undefined) {
+    if (!row.routingAdoption || typeof row.routingAdoption !== "object" || Array.isArray(row.routingAdoption)) return null;
+    const adoption = row.routingAdoption as Record<string, unknown>;
+    if (adoption.adoption !== "not-applicable" && adoption.adoption !== "adopted"
+      && adoption.adoption !== "pending-client-restart" && adoption.adoption !== "unknown") return null;
+    if (adoption.injectedAtMs !== null && typeof adoption.injectedAtMs !== "number") return null;
+    if (typeof adoption.observedClients !== "number" || !Array.isArray(adoption.staleClients)) return null;
+    for (const client of adoption.staleClients) {
+      if (!client || typeof client !== "object" || Array.isArray(client)) return null;
+      const row = client as Record<string, unknown>;
+      if (typeof row.pid !== "number" || typeof row.startedAtMs !== "number") return null;
+    }
+  }
+  for (const key of STARTUP_HEALTH_BOOLEAN_FIELDS) if (typeof row[key] !== "boolean") return null;
+  return payload as StartupHealth;
+}
+
+/** Prefer an attested live verdict and evaluate the local fallback only when live state is absent. */
+export function selectStatusStartupHealth(
+  liveStartup: StartupHealth | null,
+  fallback: () => StartupHealth,
+): StartupHealth {
+  return liveStartup ?? fallback();
+}
+
+/** Build the service summary from the same startup source that `ocx status` selected. */
+export function statusServiceSummary(
+  liveStartup: StartupHealth | null,
+  service: Pick<ReturnType<typeof diagnoseService>, "installed" | "summary">,
+  live: boolean,
+): string {
+  if (liveStartup) {
+    if (liveStartup.protection === "service" && liveStartup.serviceViable) {
+      return `running under the live managed service (logs: ${serviceLogPath()})`;
+    }
+    const state = [
+      liveStartup.serviceInstalled ? "installed" : "absent",
+      liveStartup.serviceRunning ? "running" : "not running",
+      liveStartup.serviceViable ? "viable" : "not viable",
+    ].join(", ");
+    const action = liveStartup.recommendedCommand ? `; run '${liveStartup.recommendedCommand}'` : "";
+    return `live startup reports service ${state}${action} (logs: ${serviceLogPath()})`;
+  }
+  return service.installed && !live
+    ? `${service.summary} — registered but NOT serving; see ${serviceLogPath()} and re-run 'ocx service repair'`
+    : service.summary;
+}
+
 /**
  * The hub block, or null when this machine is not a hub.
  *
@@ -666,20 +746,19 @@ export async function collectStatus(): Promise<CliStatusView> {
     hostname: config.hostname,
   });
   const bunRuntime = durableBunRuntime();
+  const liveStartup = live ? await fetchLiveStartupHealth(live) : null;
   const service = diagnoseService();
   // A service can be registered and still not serve: the manager reports the job
-  // either way. `live` was already identity-probed a few lines above, so cross-check
-  // rather than print registration as if it were service.
-  const serviceSummary = service.installed && !live
-    ? `${service.summary} — registered but NOT serving; see ${serviceLogPath()} and re-run 'ocx service repair'`
-    : service.summary;
+  // either way. When the identity-probed live proxy provides an attested startup verdict,
+  // prefer it over a shell-local service-manager probe that lacks the service environment.
+  const serviceSummary = statusServiceSummary(liveStartup, service, Boolean(live));
   const codexShim = diagnoseCodexShim();
   const codexShimSummary = codexShim.summary;
-  const startup = collectStartupHealth(config, {
+  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(config, {
     service,
     shim: codexShim,
     routingKind: getCodexRoutingKind(),
-  });
+  }));
   const codexPlugins = diagnoseCodexBundledPlugins();
   const lastClamp = loadLastEffortClamp();
   const clampActive = effortClampAppliesToRuntime(lastClamp, resolvedRuntime.runtime);

package/src/client/connect.ts

@@ -104,6 +104,8 @@ export interface LinkClientCredential {
 }
 
 export interface ClientConnectDeps {
+  /** Abort enrollment network work and refuse subsequent writes; rollback still drains. */
+  signal?: AbortSignal;
   fetchImpl?: typeof fetch;
   now?: () => Date;
   lifecycleLockDeps?: ClientLifecycleLockDeps;
@@ -539,6 +541,18 @@ export async function connectClient(
   options: ConnectOptions,
   deps: ClientConnectDeps = {},
 ): Promise<OcxClientConnectionConfig> {
+  deps.signal?.throwIfAborted();
+  const rawFetch = deps.fetchImpl ?? fetch;
+  const fetchImpl: typeof fetch = deps.signal ? Object.assign(async (...[input, init = {}]: Parameters<typeof fetch>) => {
+    deps.signal!.throwIfAborted();
+    const signals = [deps.signal, init.signal, input instanceof Request ? input.signal : undefined]
+      .filter((signal): signal is AbortSignal => signal != null);
+    return rawFetch(input, { ...init, signal: AbortSignal.any(signals), redirect: "manual" });
+  }, { preconnect: rawFetch.preconnect }) : rawFetch;
+  const assertActiveConnectingState = (fingerprint?: string) => {
+    deps.signal?.throwIfAborted();
+    assertConnectingState(fingerprint);
+  };
   let serverUrl = "";
   let managementUrl = "";
   let linkAdmissionToken: string | null = null;
@@ -586,7 +600,7 @@ export async function connectClient(
       throw new Error("link mode requires a valid local config port");
     }
     withClientLifecycleSync(() => withConfigMutationLockSync(() => {
-      assertConnectingState();
+      assertActiveConnectingState();
       const externalProvider = currentExternalCodexModelProvider();
       if (externalProvider) throw new Error("connect refused: an external Codex provider owns config.toml");
       if (linkMode) {
@@ -603,7 +617,7 @@ export async function connectClient(
       }
     }), deps.lifecycleLockDeps);
 
-    const upstreamFetch = deps.fetchImpl ?? fetch;
+    const upstreamFetch = fetchImpl;
     const readinessFetch = linkMode
       ? (async (input, init = {}) => {
         const url = input instanceof Request ? input.url : String(input);
@@ -622,18 +636,18 @@ export async function connectClient(
         managementUrl,
         localGuiOrigin(),
         options.credential.value,
-        { fetchImpl: deps.fetchImpl },
+        { fetchImpl },
       );
       cleanupCredential = { kind: "gui-session", value: session };
     } else if (!linkMode && options.credential.kind === "admin") {
       cleanupCredential = { kind: "admin", value: options.credential.value };
     }
     if (!linkMode) {
-      issued = await issueClientKey(managementUrl, cleanupCredential!, clientKeyName(), { fetchImpl: deps.fetchImpl });
+      issued = await issueClientKey(managementUrl, cleanupCredential!, clientKeyName(), { fetchImpl });
     }
 
     const initialFiles = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
-      assertConnectingState(linkMode ? pendingConnectFingerprint! : undefined);
+      assertActiveConnectingState(linkMode ? pendingConnectFingerprint! : undefined);
       const persisted = linkMode
         ? (() => {
           const current = readServiceApiTokenState();
@@ -656,7 +670,7 @@ export async function connectClient(
     if (!admissionToken) throw new Error("client admission credential unavailable");
     const apiKeyId = linkMode ? (options.credential as LinkClientCredential).apiKeyId : issued!.id;
     const catalog = await downloadClientCatalog(serverUrl, admissionToken, {
-      fetchImpl: deps.fetchImpl,
+      fetchImpl,
       timeoutMs: options.catalogTimeoutMs,
     });
     // Fail closed BEFORE the write (#4207). The hub being reachable and the credential working
@@ -666,7 +680,7 @@ export async function connectClient(
     // than writing one and restoring it afterwards.
     assertClientCatalogCompatible(catalog.body, deps.catalogCompatibility);
     writtenCatalogFingerprint = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
-      assertConnectingState(persisted.fingerprint);
+      assertActiveConnectingState(persisted.fingerprint);
       atomicWriteFile(DEFAULT_CATALOG_PATH, catalog.body);
       return sha256(catalog.body);
     }), deps.lifecycleLockDeps);
@@ -679,7 +693,7 @@ export async function connectClient(
       routingTarget: target,
       catalogPath: DEFAULT_CATALOG_PATH,
       journalOwner: { kind: "client", apiKeyId },
-      beforeClientWrite: () => assertConnectingState(persisted.fingerprint),
+      beforeClientWrite: () => assertActiveConnectingState(persisted.fingerprint),
     });
     if (!preflight.success) throw new Error(preflight.message);
 
@@ -688,7 +702,7 @@ export async function connectClient(
         routingTarget: target,
         catalogPath: DEFAULT_CATALOG_PATH,
         journalOwner: { kind: "client", apiKeyId },
-        beforeClientWrite: () => assertConnectingState(persisted.fingerprint),
+        beforeClientWrite: () => assertActiveConnectingState(persisted.fingerprint),
       });
       if (!injected.success || injected.status === "skipped") throw new Error(injected.message);
       injectionCommitted = true;
@@ -715,7 +729,7 @@ export async function connectClient(
       ...(linkMode ? { transport: "link" as const, link: linkMetadata } : {}),
     };
     withClientLifecycleSync(() => withConfigMutationLockSync(() => {
-      assertConnectingState(persisted.fingerprint);
+      assertActiveConnectingState(persisted.fingerprint);
       clearClientConnectPending(persisted.fingerprint);
       commitClientConnection(connection);
       committed = true;

package/src/client/link-ingress.ts

@@ -43,6 +43,8 @@ export function createLinkKeySource(expectedFingerprint: string, deps: LinkKeySo
 
 export interface LinkIngress {
   tunnelPort: number;
+  linkId?: string;
+  apiKeyId?: string;
   /** The listener's loopback policy: the standalone Host and Origin anti-rebinding gate. */
   policy: RequestPolicyView;
   linkKey: () => string | null;
@@ -98,5 +100,5 @@ export function handleLinkIngress(
   const admissionKey = ingress.linkKey();
   if (!admissionKey) return Response.json({ error: "link_credential_unavailable" }, { status: 503 });
   liftRequestIdleTimer(req, server);
-  return relayLinkDataRequest(req, { tunnelPort: ingress.tunnelPort, admissionKey }, ingress.relay);
+  return relayLinkDataRequest(req, { tunnelPort: ingress.tunnelPort, admissionKey, linkId: ingress.linkId, apiKeyId: ingress.apiKeyId }, ingress.relay);
 }

package/src/client/link-join.ts

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { isPortAvailable } from "../server/ports";
+import { scanListenPidsForAddress, type ListenPidScan } from "../server/port-reclaim";
 import { isLinkPort, JOIN_TUNNEL_PORT_MAX, JOIN_TUNNEL_PORT_MIN } from "../link/ports";
 import { buildExecArgv, REMOTE_COMMAND_NOT_FOUND, remoteOcxArgv } from "../link/ssh-argv";
 import { sshFailureHint, sshRunnerErrorHint, type SshRunner, type SshRunResult } from "../link/ssh-runner";
@@ -22,6 +23,7 @@ import type { OcxConnectedClientId } from "../types";
 
 const JOIN_TUNNEL_READY_TIMEOUT_MS = 15_000;
 const JOIN_TUNNEL_POLL_MS = 100;
+const JOIN_TUNNEL_SPAWN_GRACE_MS = 100;
 const JOIN_REVOKE_TIMEOUT_MS = 30_000;
 const JOIN_CONFIRM_TTL_MS = 5 * 60_000;
 const JOIN_PORT_ATTEMPTS = 32;
@@ -74,6 +76,12 @@ export interface ClientLinkJoinDeps {
   hostname?: () => string;
   randomBytes?: (size: number) => Uint8Array;
   fetchImpl?: typeof fetch;
+  /**
+   * LISTEN-owner probe for the tunnel port; defaults to the netstat/lsof/ss scan.
+   * Receives the loopback address the tunnel binds so listeners on unrelated
+   * addresses do not confuse the readiness check.
+   */
+  scanListenPids?: (port: number, address?: string) => ListenPidScan;
   spawnTunnel?: (spec: {
     linkId: string;
     alias: string;
@@ -222,8 +230,10 @@ async function compensateStaleSidecar(deps: ClientLinkJoinDeps): Promise<void> {
   }
 }
 
+/** Wait for the live tunnel's authenticated readiness, retaining the deadline after failed ownership rechecks. */
 async function waitForReady(
   deps: ClientLinkJoinDeps,
+  tunnel: ClientLinkTunnelHandle,
   port: number,
   key: string,
 ): Promise<void> {
@@ -231,19 +241,53 @@ async function waitForReady(
   const now = deps.now ?? Date.now;
   const sleep = deps.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
   const deadline = now() + JOIN_TUNNEL_READY_TIMEOUT_MS;
+  const tunnelExited = tunnel.exited.then(() => { throw new ClientLinkJoinError("join_tunnel_failed"); });
+  await Promise.race([
+    tunnelExited,
+    new Promise<void>(resolve => setTimeout(resolve, JOIN_TUNNEL_SPAWN_GRACE_MS)),
+  ]);
+  const listenPids = deps.scanListenPids ?? scanListenPidsForAddress;
+  // The tunnel binds 127.0.0.1; a listener on a different loopback or interface address
+  // never receives our requests, so ownership is only judged among sockets that serve it.
+  const tunnelAddress = "127.0.0.1";
   for (;;) {
     try {
-      const response = await fetchImpl(`http://127.0.0.1:${port}/readyz`, {
-        headers: { "x-opencodex-api-key": key },
-      });
-      if (response.status === 200) return;
-      if (response.status === 401) throw new ClientLinkJoinError("admission_failed");
+      // A squatter answering the 401 challenge would otherwise collect the issued key:
+      // the only listener allowed a keyed request is the ssh process we spawned — it owns
+      // the port only after a successful bind, and ExitOnForwardFailure makes it exit when
+      // it cannot take the port. An unverifiable scan stays "not ready", never a pass.
+      const ownership = listenPids(port, tunnelAddress);
+      if (ownership.ok && ownership.pids.length === 1 && ownership.pids[0] === tunnel.pid) {
+        // Never follow redirects: a port occupant must not reroute the challenge, and a
+        // redirected keyed request would carry the issued key to an unrelated listener.
+        const probe = await Promise.race([
+          tunnelExited,
+          fetchImpl(`http://127.0.0.1:${port}/readyz`, { redirect: "manual" }),
+        ]);
+        if (probe.status === 401) {
+          // Ownership can flip between the probe and the keyed request (a squatter
+          // takes the port after the tunnel dies). Re-scan in the same iteration and
+          // skip only the keyed request on failure, not the deadline check and sleep.
+          const recheck = listenPids(port, tunnelAddress);
+          if (recheck.ok && recheck.pids.length === 1 && recheck.pids[0] === tunnel.pid) {
+            const response = await Promise.race([
+              tunnelExited,
+              fetchImpl(`http://127.0.0.1:${port}/readyz`, {
+                headers: { "x-opencodex-api-key": key },
+                redirect: "manual",
+              }),
+            ]);
+            if (response.status === 200) return;
+            if (response.status === 401) throw new ClientLinkJoinError("admission_failed");
+          }
+        }
+      }
     } catch (error) {
       if (error instanceof ClientLinkJoinError) throw error;
     }
     const remaining = deadline - now();
     if (remaining <= 0) throw new ClientLinkJoinError("join_tunnel_failed");
-    await sleep(Math.min(JOIN_TUNNEL_POLL_MS, remaining));
+    await Promise.race([tunnelExited, sleep(Math.min(JOIN_TUNNEL_POLL_MS, remaining))]);
   }
 }
 
@@ -256,6 +300,7 @@ function requireConfirmedHost(deps: ClientLinkJoinDeps, alias: string): JoinConf
   return confirmed;
 }
 
+/** Issue and enroll a confirmed Home link, compensating failures before committing the connection. */
 export async function joinHome(deps: ClientLinkJoinDeps, input: { alias: string }): Promise<{ linkId: string; apiKeyId: string }> {
   const confirmed = requireConfirmedHost(deps, input.alias);
   await compensateStaleSidecar(deps);
@@ -308,15 +353,29 @@ export async function joinHome(deps: ClientLinkJoinDeps, input: { alias: string
       configDir: deps.configDir,
       knownHostsFile: deps.knownHostsFile,
     });
-    await waitForReady(deps, tunnelPort, issued.key);
+    await waitForReady(deps, tunnel, tunnelPort, issued.key);
   } catch (error) {
     const code = error instanceof ClientLinkJoinError ? error.code : "join_tunnel_failed";
     await rollback(deps, issued.linkId, tunnel);
     throw new ClientLinkJoinError(code);
   }
 
+  const enrollmentAbort = new AbortController();
+  let enrollmentFinished = false;
   try {
+    if (!tunnel) throw new ClientLinkJoinError("join_tunnel_failed");
     const connect = deps.connect ?? connectClient;
+    // A tunnel exit cancels work; it is NOT a competing terminal result. The connect
+    // transaction alone decides commit versus rollback, so an exit queued immediately
+    // after commit cannot revoke a key that a connected client has already retained.
+    void tunnel.exited.then(() => {
+      if (!enrollmentFinished) enrollmentAbort.abort(new ClientLinkJoinError("join_tunnel_failed"));
+    });
+    const signal = deps.connectDeps?.signal
+      ? AbortSignal.any([enrollmentAbort.signal, deps.connectDeps.signal]) : enrollmentAbort.signal;
+    // Observe a tunnel that exited after readiness before starting any enrollment write.
+    await Promise.resolve();
+    signal.throwIfAborted();
     await connect({
       serverUrl: `http://127.0.0.1:${tunnelPort}`,
       managementUrl: `http://127.0.0.1:${tunnelPort}`,
@@ -328,10 +387,18 @@ export async function joinHome(deps: ClientLinkJoinDeps, input: { alias: string
     }, {
       fetchImpl: deps.fetchImpl,
       ...deps.connectDeps,
+      signal,
     });
-  } catch {
+  } catch (error) {
+    // connectClient has drained its local rollback before rejecting. Only then can
+    // the tunnel and the remote key be compensated without racing a late writer.
+    const tunnelAborted = enrollmentAbort.signal.aborted;
+    enrollmentFinished = true;
     await rollback(deps, issued.linkId, tunnel);
-    throw new ClientLinkJoinError("join_connect_failed");
+    throw new ClientLinkJoinError(tunnelAborted ? "join_tunnel_failed"
+      : error instanceof ClientLinkJoinError ? error.code : "join_connect_failed");
+  } finally {
+    enrollmentFinished = true;
   }
 
   await stopTunnel(tunnel);