chainlesschain 0.165.4 → 0.165.6

package/src/lib/process-execution-broker/index.js

@@ -71,6 +71,10 @@ import {
   consumeMcpStdioExecutableIdentityAuthority,
   MCP_STDIO_CAPSULE_SANDBOX_CONTRACT_KIND,
 } from "../mcp-stdio-executable-identity.js";
+import {
+  isMcpStdioCapsuleNativeCodePolicy,
+  mcpStdioCapsuleNativeCodePolicyDigest,
+} from "../mcp-stdio-native-code-policy.js";
 
 const SUPPORTED_SANDBOX_BOUNDARIES = new Set(Object.values(SANDBOX_BOUNDARIES));
 const SUPPORTED_SANDBOX_PROFILES = new Set([
@@ -1193,6 +1197,7 @@ class ProcessExecutionBroker extends EventEmitter {
       "rootIdentity",
       "entryIdentity",
       "runtimeIdentity",
+      "nativeCodePolicy",
     ]);
     const unsupportedKey = Object.keys(raw).find(
       (key) => !supportedKeys.has(key),
@@ -1213,6 +1218,15 @@ class ProcessExecutionBroker extends EventEmitter {
     ) {
       return invalid("unsupported sandboxExecutionContract kind or version");
     }
+    if (
+      (mcpCapsule &&
+        !isMcpStdioCapsuleNativeCodePolicy(raw.nativeCodePolicy)) ||
+      (!mcpCapsule && raw.nativeCodePolicy !== undefined)
+    ) {
+      return invalid(
+        "sandboxExecutionContract native-code policy is invalid for this contract kind",
+      );
+    }
     if (
       options.shell !== false ||
       (!mcpCapsule &&
@@ -1303,6 +1317,11 @@ class ProcessExecutionBroker extends EventEmitter {
       rootIdentity,
       entryIdentity: this._freezeExecutableIdentity(entryIdentity),
       runtimeIdentity: this._freezeExecutableIdentity(runtimeIdentity),
+      ...(mcpCapsule
+        ? {
+            nativeCodePolicy: Object.freeze({ ...raw.nativeCodePolicy }),
+          }
+        : {}),
     });
   }
 
@@ -1789,6 +1808,13 @@ class ProcessExecutionBroker extends EventEmitter {
         "helperTeamIdentifier",
         "helperPackageIdentifier",
         "helperPackageVersion",
+        "nativeCodePolicySchema",
+        "nativeCodePolicyMode",
+        "capsuleNativeCodeFormat",
+        "nativeAddonLoading",
+        "nativeAddonDenialMechanism",
+        "hostRuntimeSharedLibraries",
+        "anonymousExecutableMemory",
       ]) {
         if (
           plan.runtimeProbe[field] !== undefined &&
@@ -1842,6 +1868,7 @@ class ProcessExecutionBroker extends EventEmitter {
         "processForkExplicitlyDenied",
         "sandboxExecLiveGateContract",
         "globalLaunchSerialization",
+        "nativeCodePolicyBound",
       ]) {
         if (
           plan.runtimeProbe[field] !== undefined &&
@@ -1890,6 +1917,7 @@ class ProcessExecutionBroker extends EventEmitter {
         "helperDesignatedRequirementSha256",
         "installAttestationDigest",
         "planBindingDigest",
+        "nativeCodePolicyDigest",
       ]) {
         if (
           plan.runtimeProbe[field] !== undefined &&
@@ -2347,6 +2375,75 @@ class ProcessExecutionBroker extends EventEmitter {
           "Successful dynamic ELF evidence requires a runtime pathname shared-library closure",
         );
       }
+      const nativeCodeEvidenceFields = [
+        "nativeCodePolicyBound",
+        "nativeCodePolicySchema",
+        "nativeCodePolicyDigest",
+        "nativeCodePolicyMode",
+        "capsuleNativeCodeFormat",
+        "nativeAddonLoading",
+        "nativeAddonDenialMechanism",
+        "hostRuntimeSharedLibraries",
+        "anonymousExecutableMemory",
+      ];
+      const nativeAddonLoadingGuaranteed = guarantees.includes(
+        SANDBOX_BOUNDARIES.NATIVE_ADDON_LOADING,
+      );
+      const capsuleExecutionContract = launchContext.executionContract;
+      const expectedNativeCodePolicy =
+        capsuleExecutionContract?.nativeCodePolicy;
+      const nativeCodePolicyEvidenceValid =
+        nativeAddonLoadingGuaranteed &&
+        guarantees.includes(SANDBOX_BOUNDARIES.CODE_SNAPSHOT) &&
+        capsuleExecutionContract?.kind ===
+          MCP_STDIO_CAPSULE_SANDBOX_CONTRACT_KIND &&
+        isMcpStdioCapsuleNativeCodePolicy(expectedNativeCodePolicy) &&
+        plan.runtimeProbe.nativeCodePolicyBound === true &&
+        plan.runtimeProbe.nativeCodePolicySchema ===
+          expectedNativeCodePolicy.schema &&
+        plan.runtimeProbe.nativeCodePolicyDigest ===
+          mcpStdioCapsuleNativeCodePolicyDigest(expectedNativeCodePolicy) &&
+        plan.runtimeProbe.nativeCodePolicyMode ===
+          expectedNativeCodePolicy.mode &&
+        plan.runtimeProbe.capsuleNativeCodeFormat ===
+          expectedNativeCodePolicy.capsuleFormat &&
+        plan.runtimeProbe.nativeAddonLoading ===
+          expectedNativeCodePolicy.nativeAddonLoading &&
+        plan.runtimeProbe.nativeAddonDenialMechanism ===
+          expectedNativeCodePolicy.nativeAddonDenialMechanism &&
+        plan.runtimeProbe.hostRuntimeSharedLibraries ===
+          expectedNativeCodePolicy.hostRuntimeSharedLibraries &&
+        plan.runtimeProbe.anonymousExecutableMemory ===
+          expectedNativeCodePolicy.anonymousExecutableMemory &&
+        plan.runtimeProbe.sharedLibraryClosure === false;
+      if (nativeAddonLoadingGuaranteed && !nativeCodePolicyEvidenceValid) {
+        throw this._sandboxError(
+          "invalid_sandbox_plan",
+          "Native-addon loading guarantee requires the exact deny-native-addons capsule policy",
+        );
+      }
+      if (
+        !nativeAddonLoadingGuaranteed &&
+        nativeCodeEvidenceFields.some(
+          (field) => plan.runtimeProbe[field] !== undefined,
+        )
+      ) {
+        throw this._sandboxError(
+          "invalid_sandbox_plan",
+          "Native-addon policy evidence requires its sandbox guarantee",
+        );
+      }
+      if (
+        capsuleExecutionContract?.kind ===
+          MCP_STDIO_CAPSULE_SANDBOX_CONTRACT_KIND &&
+        guarantees.includes(SANDBOX_BOUNDARIES.CODE_SNAPSHOT) &&
+        !nativeCodePolicyEvidenceValid
+      ) {
+        throw this._sandboxError(
+          "invalid_sandbox_plan",
+          "MCP capsule code snapshots require a bound native-addon denial policy",
+        );
+      }
       const codeSnapshotGuaranteed = guarantees.includes(
         SANDBOX_BOUNDARIES.CODE_SNAPSHOT,
       );
@@ -3099,6 +3196,21 @@ class ProcessExecutionBroker extends EventEmitter {
             }
           : {}),
       };
+      for (const field of [
+        "nativeCodePolicyBound",
+        "nativeCodePolicySchema",
+        "nativeCodePolicyDigest",
+        "nativeCodePolicyMode",
+        "capsuleNativeCodeFormat",
+        "nativeAddonLoading",
+        "nativeAddonDenialMechanism",
+        "hostRuntimeSharedLibraries",
+        "anonymousExecutableMemory",
+      ]) {
+        if (plan.runtimeProbe[field] !== undefined) {
+          runtimeProbe[field] = plan.runtimeProbe[field];
+        }
+      }
       for (const field of [
         "pluginTreeContentSnapshot",
         ...pluginTreeEvidenceFields,

package/src/lib/process-execution-broker/platform-sandbox.js

@@ -48,6 +48,11 @@ import {
   macosMcpLauncherPolicyDigest,
   verifyMacosMcpLauncherInstallContract,
 } from "./macos-mcp-launcher-contract.js";
+import {
+  isMcpStdioCapsuleNativeCodePolicy,
+  mcpStdioCapsuleNativeCodeEvidence,
+  mcpStdioCapsuleNativeCodePolicyDigest,
+} from "../mcp-stdio-native-code-policy.js";
 
 export {
   MCP_STDIO_FD_ENTRY_BOOTSTRAP,
@@ -68,6 +73,7 @@ export const SANDBOX_BOUNDARIES = Object.freeze({
   PROCESS_TREE: "process-tree",
   RESOURCE_LIMITS: "resource-limits",
   PRIVILEGE_REDUCTION: "privilege-reduction",
+  NATIVE_ADDON_LOADING: "native-addon-loading",
 });
 
 /**
@@ -1663,6 +1669,7 @@ function validateMacMcpCapsuleContract(
   if (
     contract?.kind !== MCP_STDIO_CAPSULE_SANDBOX_CONTRACT_KIND ||
     contract.contractVersion !== 1 ||
+    !isMcpStdioCapsuleNativeCodePolicy(contract.nativeCodePolicy) ||
     (sync !== true && sync !== false) ||
     spawnOpts?.shell !== false ||
     !linuxStdioIsNarrow(spawnOpts?.stdio) ||
@@ -1774,6 +1781,9 @@ function applyMacMcpCapsuleCodeSnapshot(
     });
   }
 
+  const nativeCodeEvidence = mcpStdioCapsuleNativeCodeEvidence(
+    contract.nativeCodePolicy,
+  );
   const protocol = MACOS_MCP_LAUNCHER_INPUTS.protocol;
   const legacyUnavailable = () =>
     unavailable("macos_atomic_runtime_exec_unavailable", {
@@ -1894,6 +1904,7 @@ function applyMacMcpCapsuleCodeSnapshot(
           entryFd: entryPin.fd,
           capsuleRootFd: capsulePin.fd,
           callerLifelineFd: protocol.callerLifelineFd,
+          nativeCodePolicyDigest: nativeCodeEvidence.nativeCodePolicyDigest,
         }),
       )
       .digest("hex");
@@ -1940,6 +1951,7 @@ function applyMacMcpCapsuleCodeSnapshot(
       entrySnapshotBootstrapSha256:
         MCP_STDIO_MACOS_GATED_ENTRY_BOOTSTRAP_SHA256,
       sharedLibraryClosure: false,
+      ...nativeCodeEvidence,
       rootProtectedRuntimeSnapshot: true,
       entryRootOwnedAnonymousSnapshot: true,
       entrySourcePrePostStat: true,
@@ -1996,6 +2008,7 @@ function applyMacMcpCapsuleCodeSnapshot(
         SANDBOX_BOUNDARIES.PROCESS_EXEC,
         SANDBOX_BOUNDARIES.PROCESS_TREE,
         SANDBOX_BOUNDARIES.PRIVILEGE_REDUCTION,
+        SANDBOX_BOUNDARIES.NATIVE_ADDON_LOADING,
       ],
       cleanup,
     });
@@ -4039,6 +4052,15 @@ function windowsPluginNodeEntrySnapshot(invocation, sandboxOpts, spawnOpts) {
       reason: "windows_plugin_execution_contract_unsupported",
     };
   }
+  if (
+    capsuleContract &&
+    !isMcpStdioCapsuleNativeCodePolicy(contract.nativeCodePolicy)
+  ) {
+    return {
+      locks: null,
+      reason: "windows_mcp_native_code_policy_invalid",
+    };
+  }
   if (
     (!capsuleContract && sandboxOpts.sync !== true) ||
     spawnOpts?.detached === true
@@ -4189,6 +4211,9 @@ function windowsAppContainerPolicyDigest({
               runtimeLaunchMechanism:
                 "filter-oplock-locked-createprocess-suspended-image-v1",
               sharedLibraryClosure: false,
+              nativeCodePolicyDigest: mcpStdioCapsuleNativeCodePolicyDigest(
+                executionContract.nativeCodePolicy,
+              ),
             }
           : {}),
         launchPathLocks: snapshotLocks,
@@ -4241,6 +4266,7 @@ export function applyWindowsSandbox(
   const appContainerSupportedBoundaries = [
     ...appContainerGuarantees,
     SANDBOX_BOUNDARIES.CODE_SNAPSHOT,
+    SANDBOX_BOUNDARIES.NATIVE_ADDON_LOADING,
   ];
   const base = {
     platform: runtime.platform,
@@ -4859,6 +4885,9 @@ export function applyWindowsSandbox(
               runtimeLaunchMechanism:
                 "filter-oplock-locked-createprocess-suspended-image-v1",
               sharedLibraryClosure: false,
+              ...mcpStdioCapsuleNativeCodeEvidence(
+                sandboxOpts.executionContract.nativeCodePolicy,
+              ),
               planBindingMechanism: "windows-mcp-code-snapshot-plan-binding-v1",
               planBindingDigest: windowsMcpPlanBinding.planBindingDigest,
             }
@@ -4884,7 +4913,10 @@ export function applyWindowsSandbox(
       ...(entrySnapshot.locks &&
       sandboxOpts.executionContract?.kind ===
         MCP_STDIO_CAPSULE_SANDBOX_CONTRACT_KIND
-        ? [SANDBOX_BOUNDARIES.CODE_SNAPSHOT]
+        ? [
+            SANDBOX_BOUNDARIES.CODE_SNAPSHOT,
+            SANDBOX_BOUNDARIES.NATIVE_ADDON_LOADING,
+          ]
         : []),
     ],
     command: helperInvocation.command,
@@ -5402,6 +5434,12 @@ function validateLinuxPluginContract(
   ) {
     return { ok: false, reason: "execution_contract_missing" };
   }
+  if (
+    capsuleContract &&
+    !isMcpStdioCapsuleNativeCodePolicy(contract.nativeCodePolicy)
+  ) {
+    return { ok: false, reason: "mcp_native_code_policy_invalid" };
+  }
   if (
     (sync !== true && sync !== false) ||
     spawnOpts?.shell !== false ||
@@ -6173,6 +6211,9 @@ function applyLinuxMcpCapsuleCodeSnapshot(
     entrySnapshotSha256: entrySnapshot.attestation.sha256,
     entrySnapshotBytes: entrySnapshot.attestation.bytes,
   });
+  const nativeCodeEvidence = mcpStdioCapsuleNativeCodeEvidence(
+    contract.nativeCodePolicy,
+  );
   const policyDigest = sha256(
     JSON.stringify({
       version: 1,
@@ -6186,6 +6227,7 @@ function applyLinuxMcpCapsuleCodeSnapshot(
       entrySnapshotBootstrapSha256: MCP_STDIO_FD_ENTRY_BOOTSTRAP_SHA256,
       runtimeLaunchMechanism: "inherited-executable-fd-v1",
       passthroughArgsDigest: sha256(JSON.stringify(invocation.args.slice(1))),
+      nativeCodePolicyDigest: nativeCodeEvidence.nativeCodePolicyDigest,
     }),
   );
   let closed = false;
@@ -6218,10 +6260,14 @@ function applyLinuxMcpCapsuleCodeSnapshot(
       runtimeLaunchMechanism: "inherited-executable-fd-v1",
       entrySnapshotBootstrapSha256: MCP_STDIO_FD_ENTRY_BOOTSTRAP_SHA256,
       sharedLibraryClosure: false,
+      ...nativeCodeEvidence,
       ...snapshotIdentity,
     },
     reason: null,
-    guarantees: [SANDBOX_BOUNDARIES.CODE_SNAPSHOT],
+    guarantees: [
+      SANDBOX_BOUNDARIES.CODE_SNAPSHOT,
+      SANDBOX_BOUNDARIES.NATIVE_ADDON_LOADING,
+    ],
     command: `/proc/self/fd/${runtimeFd}`,
     args: [
       "-e",
@@ -9694,6 +9740,9 @@ export function applyLinuxSandbox(
             runtimeLaunchMechanism:
               "bwrap-descriptor-mount-node-runtime-exec-v1",
             sharedLibraryClosure: false,
+            ...mcpStdioCapsuleNativeCodeEvidence(
+              validation.contract.nativeCodePolicy,
+            ),
             runtimeSnapshotSha256: validation.contract.runtimeIdentity.sha256,
             runtimeSnapshotBytes: validation.contract.runtimeIdentity.bytes,
             entrySnapshotSha256: entrySnapshot.attestation.sha256,
@@ -9749,7 +9798,12 @@ export function applyLinuxSandbox(
           SANDBOX_BOUNDARIES.FILESYSTEM,
           SANDBOX_BOUNDARIES.NETWORK,
           SANDBOX_BOUNDARIES.PROCESS_TREE,
-          ...(capsuleContract ? [SANDBOX_BOUNDARIES.CODE_SNAPSHOT] : []),
+          ...(capsuleContract
+            ? [
+                SANDBOX_BOUNDARIES.CODE_SNAPSHOT,
+                SANDBOX_BOUNDARIES.NATIVE_ADDON_LOADING,
+              ]
+            : []),
         ],
         command: invocation.command,
         args: invocation.args,

package/src/lib/process-execution-broker/workspace-transaction.js

@@ -102,6 +102,8 @@ const WORKSPACE_LOCK_OWNER_KEYS = Object.freeze([
 const WORKSPACE_LOCK_RETENTION_REQUEST = Symbol(
   "workspace-lock-retention-request",
 );
+const WORKSPACE_COORDINATION_TOKEN_PATTERN = /^[A-Za-z0-9-]{16,128}$/;
+const WORKSPACE_COORDINATION_RECLAIM_TOKENS_PATTERN = /^[A-Za-z0-9-]{33,257}$/;
 const TERMINAL_STATES = new Set([
   WORKSPACE_TRANSACTION_STATE.COMMITTED,
   WORKSPACE_TRANSACTION_STATE.ROLLED_BACK,
@@ -1669,6 +1671,24 @@ function workspacesOverlap(left, right) {
   return isPathInside(left, right) || isPathInside(right, left);
 }
 
+function isWorkspaceCoordinationDebris(name) {
+  for (const lifecycle of ["acquire", "release"]) {
+    const prefix = `coordination.lock.${lifecycle}-`;
+    if (name.startsWith(prefix)) {
+      return WORKSPACE_COORDINATION_TOKEN_PATTERN.test(
+        name.slice(prefix.length),
+      );
+    }
+  }
+  const reclaimedPrefix = "coordination.lock.reclaimed-";
+  return (
+    name.startsWith(reclaimedPrefix) &&
+    WORKSPACE_COORDINATION_RECLAIM_TOKENS_PATTERN.test(
+      name.slice(reclaimedPrefix.length),
+    )
+  );
+}
+
 function assertNoOverlappingWorkspaceLock(
   lockDir,
   workspaceRoot,
@@ -1695,6 +1715,12 @@ function assertNoOverlappingWorkspaceLock(
         { path: candidate },
       );
     }
+    // withFileLock atomically detaches its private coordination directory
+    // before recursive cleanup. Windows can temporarily retain that uniquely
+    // tokened directory after the coordination lock itself is already free.
+    // It contains state-lock ownership, not workspace ownership, and therefore
+    // must not be interpreted as an overlapping workspace lease.
+    if (isWorkspaceCoordinationDebris(name)) continue;
     const owner = readLockOwner(candidate);
     if (!owner) {
       throw codedError(

package/src/lib/remote-approval-bridge.js

@@ -43,11 +43,15 @@ import {
   REMOTE_MEMBERSHIP_HOST_UNAVAILABLE_CODE,
 } from "./remote-membership-host-store.js";
 import {
+  assertDirectWsUrlAllowed,
   buildDirectPairingUri,
+  isLoopbackBindHost,
   pickLanAddress,
   renderQrCode,
   resolveRemoteControlOptions,
+  resolveRemoteControlWsUrl,
 } from "./remote-control.js";
+import { logger } from "./logger.js";
 
 const DEFAULT_DECISION_TIMEOUT_MS = 5 * 60 * 1000;
 const REMOTE_LEASE_AUTHORIZATION_KIND =
@@ -345,7 +349,8 @@ export class RemoteApprovalBridge {
 
   /**
    * Pairing descriptor for devices. Relay-configured servers return a ready
-   * E2EE URI; otherwise build the direct-LAN URI from the caller's endpoint.
+   * E2EE URI; otherwise build a direct URI from the explicitly selected
+   * loopback/LAN endpoint.
    */
   pairingInfo({ lanWsUrl = null } = {}) {
     if (!this.pairing) return null;
@@ -363,6 +368,7 @@ export class RemoteApprovalBridge {
       });
     return {
       uri,
+      mode: this.pairing.uri ? "relay" : "direct",
       remoteSessionId: this.remoteSessionId,
       scopes: this.pairing.scopes,
       expiresAt: this.pairing.expiresAt,
@@ -1297,21 +1303,60 @@ export class RemoteApprovalBridge {
  * self-hosts a lightweight WS server on an OS-assigned port (no sessionManager
  * needed — the session stays client-hosted), starts a bridge for this run's
  * session, prints the pairing URI (+ optional QR) to stderr, and returns the
- * gate confirmer + teardown. Relay settings (env/config) flow through, so a
- * configured relay yields an E2EE pairing URI reaching devices off-LAN.
+ * gate confirmer + teardown. Relay settings flow through the startup
+ * environment; LAN exposure remains a separate explicit caller authority.
  */
 export async function startHeadlessRemoteApproval({
   agentSessionId,
+  allowLan = false,
   env = process.env,
-  config = {},
+  config = undefined,
   writeErr = () => {},
   isText = false,
   decisionTimeoutMs = undefined,
   deps = {},
 } = {}) {
+  let effectiveConfig = config;
+  if (effectiveConfig === undefined) {
+    try {
+      const configModule =
+        deps.configModule || (await import("./config-manager.js"));
+      effectiveConfig = configModule.loadConfig();
+    } catch {
+      effectiveConfig = {};
+    }
+  }
+  const resolved = resolveRemoteControlOptions({
+    flags: { allowApprove: true, allowLan: allowLan === true },
+    env,
+    config: effectiveConfig || {},
+  });
+  if (!resolved.relayUrl && !resolved.lanAccessible) {
+    throw new Error(
+      "remote approval is loopback-only by default; configure a relay, or enable " +
+        "allowLan with a non-loopback host (omit host to use 0.0.0.0) on a trusted network",
+    );
+  }
+  const lanAddress = resolved.lanAccessible
+    ? deps.lanAddress ||
+      (deps.pickLanAddress ? deps.pickLanAddress() : pickLanAddress())
+    : null;
+  const preflightLanWsUrl = resolveRemoteControlWsUrl(
+    { ...resolved, port: 1 },
+    { lanAddress },
+  );
+  if (
+    !resolved.relayUrl &&
+    resolved.lanAccessible &&
+    isLoopbackBindHost(new URL(preflightLanWsUrl).hostname)
+  ) {
+    throw new Error(
+      "LAN binding is enabled but no private LAN address can be advertised; " +
+        "configure a private host or a relay",
+    );
+  }
   const { ChainlessChainWSServer } =
     deps.serverModule || (await import("../gateways/ws/ws-server.js"));
-  const resolved = resolveRemoteControlOptions({ flags: {}, env, config });
   const server = new ChainlessChainWSServer({
     port: 0,
     host: resolved.host,
@@ -1319,50 +1364,95 @@ export async function startHeadlessRemoteApproval({
     remoteSessionRelayUrl: resolved.relayUrl,
     remoteSessionPeerId: resolved.peerId,
   });
-  await server.start();
-  const bridge = new RemoteApprovalBridge({
-    wsUrl: `ws://127.0.0.1:${server.port}`,
-    token: resolved.token,
-    agentSessionId,
-    scopes: ["observe", "approve"],
-    decisionTimeoutMs,
-  });
+  let bridge;
   try {
-    await bridge.start();
+    await server.start();
+    const createBridge =
+      deps.createBridge || ((options) => new RemoteApprovalBridge(options));
+    bridge = createBridge({
+      wsUrl: resolveRemoteControlWsUrl(
+        { ...resolved, port: server.port, allowLan: resolved.lanAccessible },
+        { lanAddress: null },
+      ),
+      token: resolved.token,
+      agentSessionId,
+      scopes: ["observe", "approve"],
+      decisionTimeoutMs,
+    });
+    try {
+      await bridge.start();
+    } catch (err) {
+      await server.stop().catch(() => undefined);
+      throw err;
+    }
+    const lanWsUrl = resolveRemoteControlWsUrl(
+      { ...resolved, port: server.port },
+      { lanAddress },
+    );
+    const pairing = bridge.pairingInfo({ lanWsUrl });
+    if (resolved.relayUrl && pairing?.mode !== "relay") {
+      throw new Error(
+        "the configured relay did not provide a pairing URI; refusing to fall back to direct pairing",
+      );
+    }
+    if (
+      !resolved.relayUrl &&
+      pairing?.mode !== "relay" &&
+      !resolved.lanAccessible
+    ) {
+      throw new Error(
+        "direct remote approval requires explicit allowLan on a trusted network",
+      );
+    }
+    if (pairing?.mode === "direct") {
+      if (isLoopbackBindHost(new URL(lanWsUrl).hostname)) {
+        throw new Error(
+          "LAN binding is enabled but no private LAN address can be advertised",
+        );
+      }
+      assertDirectWsUrlAllowed(lanWsUrl);
+      const warn = deps.warn || ((message) => logger.warn(message));
+      warn(
+        `LAN remote approval enabled on ${resolved.host}:${server.port}. ` +
+          "Direct pairing uses plaintext ws:// with bearer credentials; use only on a trusted network.",
+      );
+    }
+    if (!pairing?.uri) {
+      throw new Error("remote approval did not produce a pairing URI");
+    }
+    if (isText) {
+      writeErr(
+        "  remote-control: approvals can be answered from a paired device\n",
+      );
+      writeErr(`  pairing: ${pairing.uri}\n`);
+      const qr = await renderQrCode(pairing.uri, deps);
+      if (qr) writeErr(qr + "\n");
+    }
+    return {
+      pairing,
+      server,
+      bridge,
+      confirmer: bridge.makeConfirmer({
+        onAsk: (ask) => {
+          if (isText) {
+            writeErr(
+              `  permission(${ask.tool || "?"}): waiting for remote approval…\n`,
+            );
+          }
+        },
+      }),
+      consumeAuthorization: (authorization, context) =>
+        bridge.consumeAuthorization(authorization, context),
+      close: async () => {
+        await bridge.close().catch(() => undefined);
+        await server.stop().catch(() => undefined);
+      },
+    };
   } catch (err) {
+    if (bridge) {
+      await bridge.close().catch(() => undefined);
+    }
     await server.stop().catch(() => undefined);
     throw err;
   }
-  const lanAddress = deps.lanAddress || pickLanAddress() || "127.0.0.1";
-  const pairing = bridge.pairingInfo({
-    lanWsUrl: `ws://${lanAddress}:${server.port}`,
-  });
-  if (isText) {
-    writeErr(
-      "  remote-control: approvals can be answered from a paired device\n",
-    );
-    writeErr(`  pairing: ${pairing.uri}\n`);
-    const qr = await renderQrCode(pairing.uri, deps);
-    if (qr) writeErr(qr + "\n");
-  }
-  return {
-    pairing,
-    server,
-    bridge,
-    confirmer: bridge.makeConfirmer({
-      onAsk: (ask) => {
-        if (isText) {
-          writeErr(
-            `  permission(${ask.tool || "?"}): waiting for remote approval…\n`,
-          );
-        }
-      },
-    }),
-    consumeAuthorization: (authorization, context) =>
-      bridge.consumeAuthorization(authorization, context),
-    close: async () => {
-      await bridge.close().catch(() => undefined);
-      await server.stop().catch(() => undefined);
-    },
-  };
 }