@xyagent/cli 0.0.1 → 1.1.0

package/bin/agentlink

@@ -30,6 +30,7 @@ import {
   formatHostForUrl,
   generatePairCode,
   generateRelayGatewayId,
+  generateScanPairCode,
   isTransientNetworkError,
   normalizeBaseUrl,
   normalizeChatTransportMode,
@@ -61,15 +62,30 @@ import { createLogger as _createBubLogger } from "../src-shared/logger.mjs";
 import { scanWorkspacesByRuntime } from "../src-ext/core/scanWorkspaces.mjs";
 import { createWorkspace } from "../src-ext/core/createWorkspace.mjs";
 import { normalizeHostName } from "../src-ext/core/pairCodeClient.mjs";
+import { getOrCreateInstallationId } from "../src-ext/core/installationIdentity.mjs";
 import { buildPairSessionResults } from "../src-ext/core/pairInventory.mjs";
-
-// Minimum Node.js 22+ — required for the built-in WebSocket client and the
-// runtime surface we rely on for bridge/service behavior across platforms.
+// runtime 能力分层的**单一真相**（bin 与 src-ext 共用，防两边各持一份名单漂移）。
+// 语义分层的完整说明见该模块头注释 —— 改分层前先读它。
+import {
+  PAIRABLE_RUNTIME_KINDS,
+  BRIDGE_CAPABLE_RUNTIME_KINDS,
+  PAIR_ONLY_RUNTIME_KINDS,
+  EXT_AGENT_RUNTIME_KINDS,
+  RUNTIME_CAPABILITIES,
+  RUNTIME_BINARY_CANDIDATES,
+  pairingCapabilitiesForRuntime,
+} from "../src-ext/core/runtimeRegistry.mjs";
+import { SCAN_QR_PNG_OUTPUT_PATH, clearQRImage } from "../src-ext/core/scanPairFlow.mjs";
+import { renderQrToTerminal } from "../src-ext/core/scanQrRenderer.mjs";
+import { buildScanDeeplink, renderScanQrPng } from "../src-ext/core/scanDeeplink.mjs";
+
+// Keep this aligned with Desktop's embedded CLI compatibility floor.
+const MIN_SUPPORTED_NODE_MAJOR = 18;
 {
   const major = Number.parseInt((process.versions?.node ?? "0").split(".")[0], 10);
-  if (major < 22) {
+  if (major < MIN_SUPPORTED_NODE_MAJOR) {
     process.stderr.write(
-      `Error: agentlink requires Node.js >= 22, current: ${process.version}\nPlease upgrade: https://nodejs.org/\n`,
+      `Error: agentlink requires Node.js >= ${MIN_SUPPORTED_NODE_MAJOR}, current: ${process.version}\nPlease upgrade: https://nodejs.org/\n`,
     );
     process.exit(1);
   }
@@ -100,20 +116,139 @@ const CLI_COMMAND_NAME = "agentlink";
 const SERVICE_LABEL = "com.agentlink.bridge";
 const SERVICE_UNIT_NAME = "agentlink-bridge.service";
 const SERVICE_TASK_NAME = "Agentlink Bridge";
+// 非默认状态根（例如 Desktop Debug 的 ~/.agentlink-debug）必须有独立服务名，
+// 否则会覆盖正式 ~/.agentlink 的 launchd/systemd/schtasks 服务。
+const SERVICE_SCOPE_HASH_LENGTH = 12;
 const RUNTIME_KIND_OPENCLAW = "openclaw";
 const RUNTIME_KIND_HERMES = "hermes";
+const RUNTIME_KIND_CLAUDE = "claude";
+const RUNTIME_KIND_CODEX = "codex";
+const RUNTIME_KIND_CURSOR = "cursor";
+// add-deepagents-opencode-runtime-enum: 已知 runtime 枚举扩到 6 个。
+// opencode 自 devagent-m-20260807-cli-runtime-opencode-pairable 起**有了配对实现**
+// （PATH 探测 + 握手 + 凭证落地），但仍**没有** bridge / mcpConfigAdapter；
+// deepagents 至今只入枚举。两者的差别由下面的分层集合承载，不靠人记。
+const RUNTIME_KIND_OPENCODE = "opencode";
+const RUNTIME_KIND_DEEPAGENTS = "deepagents";
+const RUNTIME_KIND_QWEN = "qwen";
+const RUNTIME_KIND_KIMI = "kimi";
+const RUNTIME_KIND_CODEBUDDY = "codebuddy";
+
+// ─── runtime 种类登记表（cli-runtime-kind-registry） ─────────────────────────
+// 本仓有 **多种语义不同** 的 runtime 集合。早期它们恰好都等于同一批 4 个字符串，
+// 于是被当成"4 种 runtime"散落成字面量；新增 opencode/deepagents 打破了这个巧合，
+// 所以这里把每一层显式列出来 —— 以后加 runtime 只需在对应集合里加一行，
+// 「这一层要不要带上它」被逼成一次显式选择，不再靠人记得满仓 grep。
+//
+// ① 能力分层（PAIRABLE / BRIDGE_CAPABLE / PAIR_ONLY / EXT_AGENT）已上移到
+//    src-ext/core/runtimeRegistry.mjs（见文件顶部 import）—— 因为 agentlink-agent
+//    那侧（src-ext/**）也要用同一套判定，各持一份必然漂移。
+//    · PAIRABLE      = 有 pair/reset 实现（openclaw/hermes/claude/codex/opencode）
+//    · BRIDGE_CAPABLE= 有 bridge/service/MCP 实现（前四个，**不含 opencode**）
+//    · PAIR_ONLY     = 配得上但跑不起来（= opencode），命令层必须显式拦停
+//    · EXT_AGENT     = 凭证存 ext-<rt>-last.json（claude/codex/opencode）
+// ② 走 `which <bin>`（win `where`）两阶段 PATH 探测的 runtime。
+//    openclaw 不在此列 —— 它以 openclaw.json 是否存在作为"已安装"信号。
+const PATH_PROBED_RUNTIME_KINDS = Object.freeze([
+  RUNTIME_KIND_HERMES, RUNTIME_KIND_CLAUDE, RUNTIME_KIND_CODEX,
+  RUNTIME_KIND_CURSOR, RUNTIME_KIND_OPENCODE, RUNTIME_KIND_DEEPAGENTS,
+  RUNTIME_KIND_QWEN, RUNTIME_KIND_KIMI, RUNTIME_KIND_CODEBUDDY,
+]);
+// ③ 本机探测集 = detectInstalledRuntimes() 的返回顺序，也是 host-inventory
+//    上报（Phase 1 runtimes / Phase 2 results）的口径。
+//    DeepAgents 以 `agentlink-deepagents` 独立 sidecar 命令作为 PATH 探测信号。
+const HOST_DETECTED_RUNTIME_KINDS = Object.freeze([
+  RUNTIME_KIND_OPENCLAW, ...PATH_PROBED_RUNTIME_KINDS,
+]);
+// ④ 已知 runtime 枚举 = `--runtime` 参数解析层承认的全集（不含 `all` 别名）。
+const KNOWN_RUNTIME_KINDS = Object.freeze([
+  ...HOST_DETECTED_RUNTIME_KINDS,
+]);
+// ⑤ 已知但连配对都没有的 runtime。必须显式拦停：
+//    runPair/runReset/runBridge 都以 normalizeRuntimeKind(runtime, "openclaw")
+//    开头，而它只认 openclaw/hermes、其余一律回落 fallback —— 不拦停就会把
+//    非 openclaw 的配对静默写进 openclaw 的凭证槽位（relayGatewayId/Token），
+//    用户还以为配的是自己选的那个 runtime。
+const ENUM_ONLY_RUNTIME_KINDS = Object.freeze(
+  KNOWN_RUNTIME_KINDS.filter((k) => !PAIRABLE_RUNTIME_KINDS.includes(k)),
+);
+// scan-capable runtimes (unify-scan-pairing): openclaw/hermes read their gateway
+// credentials locally (~/.agentlink/config.json via ensureRelayBridgeCredentials)
+// and can host-claim immediately. claude/codex credentials are issued by the
+// server at consume-time — no host-claim path exists for them this cycle (see
+// spec "术语" + Non-goals; S2b covers the explicit unsupported-runtime notice).
+// 🔴 opencode **不得**加进来：它没有本机 host-claim 凭证路径，走 pair 路径。
+const SCAN_CAPABLE_RUNTIME_KINDS = Object.freeze([RUNTIME_KIND_OPENCLAW, RUNTIME_KIND_HERMES]);
+
+/**
+ * enum-only runtime（已知枚举 ∖ 可配对集，当前 = deepagents）撞上任何实现路径时
+ * 显式失败退出，绝不静默回落成 openclaw。
+ *
+ * 必须在**所有命令分派之前**调用：runPair / runReset / runBridge / runService /
+ * runScan 都以 normalizeRuntimeKind(runtime, RUNTIME_KIND_OPENCLAW) 起手，而
+ * src/core.mjs 的 normalizeRuntimeKind **只认 openclaw/hermes**、其余一律回落
+ * fallback。不拦停就会把 `-r <未实现 runtime>` 静默当成 openclaw 执行（配对结果
+ * 写进 openclaw 的 relayGatewayId/Token 槽位），用户看到的却是「配对成功」
+ * = 静默错配。
+ *
+ * ⚠️ 这与「取值非法」是两类失败：取值域错误由 parseArgs 给 `must be one of ...`，
+ * 这里给的是「取值合法但本轮没有实现」。两条文案不得混用（测试有断言）。
+ *
+ * @param {string|undefined} runtime options.runtime 原值（未 normalize）
+ */
+function assertRuntimeOperableOrFail(runtime) {
+  if (runtime && ENUM_ONLY_RUNTIME_KINDS.includes(runtime)) {
+    fail(t("runtime_known_but_unsupported", {
+      runtime,
+      cli: CLI_COMMAND_NAME,
+      pairable: PAIRABLE_RUNTIME_KINDS.join(" / "),
+    }));
+  }
+}
+
+/**
+ * PAIR_ONLY runtime（可配对、但本轮没有 bridge/service 实现，当前 = opencode）
+ * 撞上「需要真的把进程跑起来 / 展示运行态」的命令时显式失败退出。
+ *
+ * 🔴 这是 assertRuntimeOperableOrFail 让出的那半边防护，不是可选的收尾：
+ * opencode 进了可配对集之后就不再被上面那道拦停命中，而 runBridge / runService /
+ * runReload / runScan / runStatus 依然全都以 normalizeRuntimeKind(x, "openclaw")
+ * 起手 —— 少了这道闸，`agentlink status -r opencode` 会把 **openclaw 的**
+ * 凭证与服务态当成 opencode 的展示给用户（同一个静默错配家族的另一种形态）。
+ *
+ * pair / reset 刻意**不**调这个：它们对 opencode 是真实现（转发 agentlink-agent）。
+ *
+ * @param {string|undefined} runtime options.runtime 原值（未 normalize）
+ * @param {string} command 触发的命令名，仅用于文案
+ */
+function assertRuntimeBridgeSupportedOrFail(runtime, command) {
+  if (runtime && PAIR_ONLY_RUNTIME_KINDS.includes(runtime)) {
+    fail(t("runtime_paired_but_no_bridge", {
+      runtime,
+      command,
+      cli: CLI_COMMAND_NAME,
+      bridgeable: BRIDGE_CAPABLE_RUNTIME_KINDS.join(" / "),
+    }));
+  }
+}
 
 function serviceNames(runtimeKind) {
   const kind = normalizeRuntimeKind(runtimeKind, RUNTIME_KIND_OPENCLAW);
+  const scope = serviceScopeSuffix();
   if (kind === RUNTIME_KIND_OPENCLAW) {
-    return { label: SERVICE_LABEL, unit: SERVICE_UNIT_NAME, task: SERVICE_TASK_NAME, logPrefix: "bridge" };
+    return {
+      label: `${SERVICE_LABEL}${scope}`,
+      unit: scope ? `agentlink-bridge${scope}.service` : SERVICE_UNIT_NAME,
+      task: `${SERVICE_TASK_NAME}${scope}`,
+      logPrefix: `bridge${scope}`,
+    };
   }
   const capitalized = kind.charAt(0).toUpperCase() + kind.slice(1);
   return {
-    label: `${SERVICE_LABEL}-${kind}`,
-    unit: `agentlink-bridge-${kind}.service`,
-    task: `${SERVICE_TASK_NAME} ${capitalized}`,
-    logPrefix: `bridge-${kind}`,
+    label: `${SERVICE_LABEL}-${kind}${scope}`,
+    unit: `agentlink-bridge-${kind}${scope}.service`,
+    task: `${SERVICE_TASK_NAME} ${capitalized}${scope}`,
+    logPrefix: `bridge-${kind}${scope}`,
   };
 }
 // Mirror the WS bridge's operator scopes for local HTTP proxy calls as well.
@@ -357,7 +492,21 @@ const CLI_I18N = {
     pair_all_detecting_runtimes: "\n检测本机已安装的 AI runtime ...",
     pair_all_runtime_installed_extra: "（{detail}）",
     pair_all_runtime_not_installed: "  · {kind} 未安装，跳过{hint}",
-    pair_all_no_runtimes: "本机未检测到任何可用 runtime（openclaw / hermes / claude / codex）。",
+    // {kinds} 由 HOST_DETECTED_RUNTIME_KINDS 渲染 —— 文案本身不再持有 runtime 名，
+    // 加 runtime 时中英两侧自动跟随，从结构上消灭「两份枚举串漂移」。
+    pair_all_no_runtimes: "本机未检测到任何可用 runtime（{kinds}）。",
+    // 已知 runtime 枚举里、但本轮还没有 pair/bridge 实现的 runtime。
+    runtime_known_but_unsupported:
+      "runtime `{runtime}` 已被识别，但本版 {cli} 还没有它的配对/桥接实现，暂不支持该命令。\n"
+      + "当前可操作的 runtime：{pairable}。",
+    // 可配对、但本轮没有 bridge/service 实现的 runtime（PAIR_ONLY）。
+    // 与上一条是**两类**失败：这条的配对是通的，只是跑不起来。
+    runtime_paired_but_no_bridge:
+      "runtime `{runtime}` 本版 {cli} 只支持配对（pair / reset），还没有 bridge 实现，`{command}` 暂不可用。\n"
+      + "支持 bridge/service 的 runtime：{bridgeable}。",
+    pair_all_runtime_pair_unsupported: "  · {kind} 已安装但本版暂无配对实现，跳过配对（已如实上报本机清单）",
+    pair_all_summary_pair_unsupported: "ℹ️  已装但暂无配对实现 ({count}): {kinds}",
+    pair_all_summary_nothing_pairable: "\n本机没有可配对的 runtime；已把探测结果如实上报给 App。",
     pair_all_host_inventory_report_failed: "  ⚠️  host-inventory 上报失败 (HTTP {status})，继续配对 ...",
     pair_all_host_inventory_report_error: "  ⚠️  host-inventory 上报异常 ({error})，继续配对 ...",
     pair_all_host_inventory_prepare_failed: "  ⚠️  host-inventory 准备失败 ({error})",
@@ -385,6 +534,8 @@ const CLI_I18N = {
     reset_all_detecting_runtimes: "\n检测本机已安装的 AI runtime（逐个解绑）...",
     reset_all_no_runtimes: "本机未检测到任何已安装 runtime，也无可解绑的本地残留。",
     reset_all_runtime_state_only: "  ⚠ {kind} 未安装，但检测到本地绑定残留，将清理",
+    // 已装、但本轮没有配对实现 → 不可能存在可解绑的绑定，不进解绑目标集。
+    reset_all_runtime_no_binding: "  · {kind} 已安装但本版暂无配对实现，无可解绑绑定，跳过",
     reset_all_resetting_runtime: "\n→ 正在解绑 {kind} ...",
     reset_all_runtime_reset_failed: "  ⚠️  {kind} 解绑失败 (退出码 {status})，继续下一个 ...",
     reset_all_summary_header: "\n──────────────── 解绑结果 ────────────────",
@@ -602,7 +753,21 @@ const CLI_I18N = {
     pair_all_detecting_runtimes: "\nDetecting installed AI runtimes on this host ...",
     pair_all_runtime_installed_extra: " ({detail})",
     pair_all_runtime_not_installed: "  · {kind} not installed, skipping{hint}",
-    pair_all_no_runtimes: "No usable runtime detected on this host (openclaw / hermes / claude / codex).",
+    // {kinds} rendered from HOST_DETECTED_RUNTIME_KINDS — see the zh table note:
+    // the text no longer holds runtime names, so both locales can never drift.
+    pair_all_no_runtimes: "No usable runtime detected on this host ({kinds}).",
+    // Pairable but no bridge/service implementation yet (PAIR_ONLY tier).
+    // A *different* failure class from runtime_known_but_unsupported below:
+    // pairing does work here, the runtime just cannot be run yet.
+    runtime_paired_but_no_bridge:
+      "runtime `{runtime}` only supports pairing (pair / reset) in this {cli} build; there is no bridge implementation yet, so `{command}` is unavailable.\n"
+      + "Runtimes with bridge/service support: {bridgeable}.",
+    runtime_known_but_unsupported:
+      "runtime `{runtime}` is recognized, but this {cli} build has no pairing/bridge implementation for it yet.\n"
+      + "Currently operable runtimes: {pairable}.",
+    pair_all_runtime_pair_unsupported: "  · {kind} installed but no pairing implementation in this build, skipping pairing (still reported in the host inventory)",
+    pair_all_summary_pair_unsupported: "ℹ️  Installed, pairing not implemented yet ({count}): {kinds}",
+    pair_all_summary_nothing_pairable: "\nNo pairable runtime on this host; the detection result was reported to the App as-is.",
     pair_all_host_inventory_report_failed: "  ⚠️  host-inventory report failed (HTTP {status}), continuing pairing ...",
     pair_all_host_inventory_report_error: "  ⚠️  host-inventory report error ({error}), continuing pairing ...",
     pair_all_host_inventory_prepare_failed: "  ⚠️  host-inventory prepare failed ({error})",
@@ -630,6 +795,7 @@ const CLI_I18N = {
     reset_all_detecting_runtimes: "\nDetecting installed AI runtimes on this host (unbind each) ...",
     reset_all_no_runtimes: "No installed runtime and no local binding trace on this host; nothing to unbind.",
     reset_all_runtime_state_only: "  ⚠ {kind} not installed, but a local binding trace was found — will clean it up",
+    reset_all_runtime_no_binding: "  · {kind} installed but pairing is not implemented in this build; no binding to unbind, skipping",
     reset_all_resetting_runtime: "\n→ Resetting {kind} ...",
     reset_all_runtime_reset_failed: "  ⚠️  {kind} reset failed (exit {status}), continuing ...",
     reset_all_summary_header: "\n──────────────── Reset Results ────────────────",
@@ -771,11 +937,15 @@ function printHelp() {
       "",
       t("help_usage"),
       `  ${CLI_COMMAND_NAME} setup [--relay <url>] [--public-base <url>] [--mode <relay>] [--account <id>] [--restart|--no-restart] [--strict-plugin] [--json]`,
-      `  ${CLI_COMMAND_NAME} pair <4-digit|6-digit|8-alnum> [-r|--runtime <openclaw|hermes|claude|codex|all>] [--mode <relay>] [--strict-plugin]  # default: all`,
-      `  ${CLI_COMMAND_NAME} reset [-r|--runtime <openclaw|hermes|claude|codex|all>] [--relay <url>] [--gateway <url>] [--json]  # default: all`,
-      `  ${CLI_COMMAND_NAME} bridge [--relay <url>] [--gateway <url>] [-r|--runtime <openclaw|hermes|claude|codex>] [--json]`,
+      // pair / reset 的取值域 = 可配对集（含 opencode），由登记表渲染，
+      // 不再手抄第二份枚举串（加 runtime 时用法行自动跟随）。
+      `  ${CLI_COMMAND_NAME} pair <4-digit|6-digit|8-alnum> [-r|--runtime <${PAIRABLE_RUNTIME_KINDS.join("|")}|all>] [--mode <relay>] [--strict-plugin]  # default: all`,
+      `  ${CLI_COMMAND_NAME} reset [-r|--runtime <${PAIRABLE_RUNTIME_KINDS.join("|")}|all>] [--relay <url>] [--gateway <url>] [--json]  # default: all`,
+      // bridge / reload 的取值域 = 可桥接集（**不含** opencode：本轮它只能配对）。
+      `  ${CLI_COMMAND_NAME} bridge [--relay <url>] [--gateway <url>] [-r|--runtime <${BRIDGE_CAPABLE_RUNTIME_KINDS.join("|")}>] [--json]`,
+      `  ${CLI_COMMAND_NAME} scan [-r|--runtime <openclaw|hermes>] [--relay <url>] [--json] [--no-serve] [--qr-path <path>] [--strict-plugin]  # 扫码配对：出二维码 → App 扫码 → 本机 scan-capable runtime(openclaw/hermes)收发；claude/codex 不支持，请改用 pair`,
       `  ${CLI_COMMAND_NAME} service <status|install|stop|uninstall|restart> [--relay <url>] [--gateway <url>] [--runtime <openclaw|hermes>] [--json]`,
-      `  ${CLI_COMMAND_NAME} reload [-r|--runtime <openclaw|hermes|claude|codex>] [--json]`,
+      `  ${CLI_COMMAND_NAME} reload [-r|--runtime <${BRIDGE_CAPABLE_RUNTIME_KINDS.join("|")}>] [--json]`,
       `  ${CLI_COMMAND_NAME} pair-url [<4-digit|6-digit|8-alnum>] [--account <id>] [--code <4-digit|6-digit|8-alnum>] [--json]`,
       `  ${CLI_COMMAND_NAME} tunnel <on|off> <port> [--relay <url>] [--ws|--tcp] [--json]`,
       `  ${CLI_COMMAND_NAME} tunnel ls [--json]`,
@@ -838,6 +1008,16 @@ function parseArgs(argv) {
     doctorAction: undefined,
     mcpSubcommand: undefined,
     mcpRuntime: undefined,
+    noServe: false,
+    qrPath: undefined,
+    // Debug Desktop passes an isolated state root here. Keep it internal so normal
+    // users do not accidentally split their existing runtime pairing state.
+    agentlinkHome: undefined,
+    // Internal plumbing flag — not advertised in --help. Set by `runScan`'s
+    // per-runtime host-claim child spawn (`--pair-mode scan`), never expected
+    // from a human-typed `agentlink pair` invocation. See runPair()'s
+    // pairMode branch (unify-scan-pairing).
+    pairMode: "",
   };
 
   while (args.length > 0) {
@@ -893,6 +1073,39 @@ function parseArgs(argv) {
       options.fix = true;
       continue;
     }
+    if (token === "--no-serve") {
+      // `agentlink scan` 专属：只配对不起 worker（spec S5）。与已有的
+      // --no-serve-relay（options.serveRelay，pair 命令的"配完对不装后台服务"
+      // 语义）刻意分开——scan 这里是"不启动前台 bridge worker"，不是装/不装
+      // service，两者不通用。
+      options.noServe = true;
+      continue;
+    }
+    if (token === "--qr-path") {
+      const value = args.shift();
+      if (!value || value.startsWith("--")) fail(t("err_missing_value", { flag: "--qr-path" }));
+      options.qrPath = value.trim();
+      continue;
+    }
+    if (token === "--pair-mode") {
+      // Internal — see options.pairMode default comment above.
+      const value = args.shift();
+      if (!value || value.startsWith("--")) fail(t("err_missing_value", { flag: "--pair-mode" }));
+      const normalized = value.trim().toLowerCase();
+      if (normalized !== "" && normalized !== "scan") {
+        fail(`--pair-mode must be "scan" (got ${value})`);
+      }
+      options.pairMode = normalized;
+      continue;
+    }
+
+    if (token === "--agentlink-home") {
+      const value = args.shift();
+      if (!value || value.startsWith("--")) fail(t("err_missing_value", { flag: "--agentlink-home" }));
+      if (!path.isAbsolute(value.trim())) fail("--agentlink-home must be an absolute path");
+      options.agentlinkHome = value.trim();
+      continue;
+    }
 
     if (token === "--relay") {
       const value = args.shift();
@@ -948,18 +1161,25 @@ function parseArgs(argv) {
       const value = args.shift();
       if (!value || value.startsWith("--")) fail(`missing value for ${token}`);
       const raw = value.trim().toLowerCase();
-      // 扩展：claude / codex 走新 agentlink-agent（shim 在 main() 做）；
-      // all 仅 pair 命令支持，逐个 runtime 串行配对；
-      // 其余还走老 normalizeRuntimeKind。
-      if (raw === "all" || raw === "claude" || raw === "codex") {
+      // 解析层只做「取值在不在已知枚举里」这一件事（KNOWN_RUNTIME_KINDS，见常量区）：
+      //   · openclaw / hermes        → bin 内 native 路径
+      //   · claude / codex / opencode → main() 转发 agentlink-agent（shim）。
+      //     opencode 自 opencode-pairable 起进了可配对集：pair / reset / uninstall
+      //     是真实现，assertRuntimeOperableOrFail() 对它**不再触发**；
+      //     bridge / service / reload / scan / status 另由
+      //     assertRuntimeBridgeSupportedOrFail() 显式拦停（两道闸分工见其文档注释）
+      //   · deepagents               → 本轮只有枚举，真执行由 main() 的
+      //     assertRuntimeOperableOrFail() 给显式「暂不支持」错误
+      //   · all                      → 仅 pair / reset 支持，逐 runtime 串行
+      // 这里刻意 **不** 再走 normalizeRuntimeKind —— 它只认 openclaw/hermes、其余
+      // 静默回落 fallback，会把新 runtime 悄悄变成 openclaw（静默错配）。
+      // raw 已 trim + toLowerCase，与 normalizeRuntimeKind 的归一化口径一致。
+      if (raw === "all" || KNOWN_RUNTIME_KINDS.includes(raw)) {
         options.runtime = raw;
         continue;
       }
-      const normalizedRuntime = normalizeRuntimeKind(raw, "__invalid__");
-      if (normalizedRuntime !== RUNTIME_KIND_OPENCLAW && normalizedRuntime !== RUNTIME_KIND_HERMES) {
-        fail(`${token} must be openclaw / hermes / claude / codex / all`);
-      }
-      options.runtime = normalizedRuntime;
+      // 取值域文案由常量渲染 —— 加 runtime 时无需再改这行（防两处真相漂移）。
+      fail(`${token} must be one of ${KNOWN_RUNTIME_KINDS.join(" / ")} / all`);
       continue;
     }
     if (token === "--hermes-python") {
@@ -1173,8 +1393,8 @@ function resolveAgentlinkStatePath() {
 // reset 用：某 runtime 是否有「可解绑的本地痕迹」（已配对的凭证 / state 文件）。
 // 与「二进制是否安装」解耦 —— 卸了 CLI 但 binding 还在的 runtime 仍须能被 reset
 // 清掉（否则 server 端绑定 + 本地 state 永久泄漏）。读 reset 实际操作的同一批文件：
-//   openclaw / hermes → ~/.agentlink/config.json（relayGatewayId / hermesRelayGatewayId）
-//   claude / codex     → ~/.agentlink/ext-<rt>-last.json（gw_id）
+//   openclaw / hermes          → ~/.agentlink/config.json（relayGatewayId / hermesRelayGatewayId）
+//   claude / codex / opencode  → ~/.agentlink/ext-<rt>-last.json（gw_id）
 function runtimeHasLocalState(kind) {
   // 1) 残留的 bridge service 也算「有痕迹」—— 凭证 id 已被上一次部分 reset 清掉、
   //    但 service 还在的孤儿，必须仍纳入 reset 清理，否则后台服务空转、卸不掉。
@@ -1182,9 +1402,19 @@ function runtimeHasLocalState(kind) {
   //    linux ~/.config/systemd/user），**不**走 `launchctl print`/`systemctl --user`
   //    那种用户级全局探测 —— 否则 reset 的扇出决策会依赖跨 HOME 的全局服务状态，
   //    破坏隔离、并可能误删别的上下文的服务。(win 用 schtasks 无文件，跳过该信号。)
+  //
+  // 🔴 只对 **native 服务** （openclaw/hermes）做这个探测：resolveMacLaunchAgentPath /
+  // resolveLinuxUserUnitPath 都经 serviceNames() → normalizeRuntimeKind(x,"openclaw")，
+  // 而后者只认 openclaw/hermes —— 对 ext-agent runtime（claude/codex/opencode）会
+  // **别名到 openclaw 自己的 plist/unit**，于是"装了 openclaw 的 bridge 服务"会被
+  // 误判成"claude/opencode 有本地痕迹"。ext-agent 的服务单元命名另在
+  // src-ext/service/serviceManager.mjs（com.agentlink.agent.<rt>），不由这里定位；
+  // 它们的痕迹判定完全走下面的 ext-<rt>-last.json 凭证文件，够用且不会串台。
   try {
-    if (process.platform === "darwin" && fs.existsSync(resolveMacLaunchAgentPath(kind))) return true;
-    if (process.platform === "linux" && fs.existsSync(resolveLinuxUserUnitPath(kind))) return true;
+    if (!EXT_AGENT_RUNTIME_KINDS.includes(kind)) {
+      if (process.platform === "darwin" && fs.existsSync(resolveMacLaunchAgentPath(kind))) return true;
+      if (process.platform === "linux" && fs.existsSync(resolveLinuxUserUnitPath(kind))) return true;
+    }
   } catch { /* 文件探测失败不影响下面的凭证判定 */ }
   try {
     if (kind === RUNTIME_KIND_OPENCLAW || kind === RUNTIME_KIND_HERMES) {
@@ -1193,7 +1423,7 @@ function runtimeHasLocalState(kind) {
       const idKey = kind === RUNTIME_KIND_OPENCLAW ? "relayGatewayId" : "hermesRelayGatewayId";
       return Boolean(String(cfg[idKey] ?? "").trim());
     }
-    if (kind === "claude" || kind === "codex") {
+    if (EXT_AGENT_RUNTIME_KINDS.includes(kind)) {
       // ext state（ext-<rt>-last.json）由 pairCodeClient.stateDir() 定位，现已统一
       // 优先 AGENTLINK_HOME（见该文件注释），与此处 resolveAgentlinkHome() 一致 ——
       // 探测与实际清理读写同一份文件，无 AGENTLINK_HOME 分叉。
@@ -1206,7 +1436,15 @@ function runtimeHasLocalState(kind) {
 }
 
 function resolveMatecliRuntimeDir() {
-  return path.join(os.homedir(), ".agentlink");
+  return resolveAgentlinkHome();
+}
+
+function serviceScopeSuffix() {
+  const currentHome = path.resolve(resolveAgentlinkHome());
+  const defaultHome = path.resolve(path.join(os.homedir(), ".agentlink"));
+  if (currentHome === defaultHome) return "";
+  const digest = createHash("sha256").update(currentHome).digest("hex");
+  return `-${digest.slice(0, SERVICE_SCOPE_HASH_LENGTH)}`;
 }
 
 function resolveBridgeLogsDir() {
@@ -2647,6 +2885,34 @@ function ensureRelayBridgeCredentials({
     }
   }
 
+  // 🔴 把 relay 地址一起落盘。缺了它，openclaw / hermes 的常驻服务重启后**静默连到
+  // 生产** —— 这不是理论问题，2026-08-13 在真机上坐实过：
+  //
+  //   · 桌面端配对时确实传了 `--relay <测试环境>`（pairing.rs pair_args）
+  //   · 但 launchd plist 的 ProgramArguments 只有 [node, agentlink-agent, <rt>]，
+  //     没有 --relay（plutil 解析确认）
+  //   · config.json 里只有 gateway 凭据、**没有任何 URL**
+  //   → pairCodeClient.readPairStateFromConfig 读 parsed.relayUrl 读到 undefined
+  //   → resolveRelayUrl 回落到 DEFAULT_RELAY_URL = https://go-relay.xyagent.com（生产）
+  //   → `agentlink doctor` 实测：relay.reachable = https://go-relay.xyagent.com
+  //
+  // 后果对测试用户最恶劣：配对当时一切正常，**重启电脑后全部悄悄连到生产**，表现是
+  // 「配对好了但会话和消息都不见了」——极难排查。
+  //
+  // 读侧（readPairStateFromConfig）早就在读 `parsed.relayUrl` 了，只有写侧一直没写；
+  // 本函数连 relayUrl 参数都收了、没有它还直接早退，却从不落盘。属纯遗漏。
+  //
+  // 用单个 `relayUrl` 而非 runtime 分槽（hermesRelayUrl/relayUrl）：读侧对 hermes 与
+  // openclaw 读的是**同一个 key**，写成两个反而对不上。四端本来同属一台机器、同一个
+  // 桌面端，relay 地址天然相同；真出现要分开的需求时再连读侧一起改。
+  const normalizedRelayUrl = String(relayUrl).trim();
+  if (normalizedRelayUrl && section.relayUrl !== normalizedRelayUrl) {
+    section.relayUrl = normalizedRelayUrl;
+    // 记进 changes 才会触发下面的落盘 —— 只有 URL 变化（凭据都已存在）时，
+    // changes 为空就会静默不写，这一步等于没做。
+    changes.push(`state.relayUrl=${normalizedRelayUrl}`);
+  }
+
   if (changes.length > 0) {
     writeJsonFile(resolveAgentlinkStatePath(), section);
   }
@@ -3395,6 +3661,21 @@ function writeBridgeLaunchScript(installConfig) {
     const appData =
       (process.env.APPDATA ?? "").trim() ||
       path.join(capturedHome, "AppData", "Roaming");
+    // ScheduledTask 的 PATH 是注册表值，看不到安装时进程里的增量（尤其是桌面端
+    // 私有 Node 的目录）—— 与 POSIX 版 `export PATH=<defaultPath>:$PATH` 同口径，
+    // 把 node/openclaw 兄弟目录 + 常见安装位快照进脚本，`%` 转义防意外展开。
+    // 兄弟目录解析显式用 win32 语义、分隔符显式 `;`（生产 win 上与默认等价；
+    // 保证非 win 环境下生成的脚本形态也正确，便于测试与排查）。
+    const defaultPath = buildPathString(
+      [
+        ...resolveSiblingBinDirs(installConfig.nodePath, path.win32),
+        ...resolveSiblingBinDirs(installConfig.openclawPath, path.win32),
+        path.join(capturedHome, ".volta", "bin"),
+        path.join(appData, "npm"),
+        "C:\\Program Files\\nodejs",
+      ],
+      ";",
+    );
     const script = [
       "@echo off",
       `set "HOME=${capturedHome}"`,
@@ -3402,6 +3683,7 @@ function writeBridgeLaunchScript(installConfig) {
       `set "APPDATA=${appData}"`,
       `set "OPENCLAW_HOME=${capturedOpenClawHome}"`,
       `set "AGENTLINK_HOME=${capturedAgentlinkHome}"`,
+      `set "PATH=${defaultPath.replaceAll("%", "%%")};%PATH%"`,
       `"${installConfig.nodePath}" ${nodeArg}`,
       "",
     ].join("\r\n");
@@ -4199,8 +4481,17 @@ async function publishPairToRelay({
   relayClientToken,
   relayGatewayToken,
   accountId,
+  // unify-scan-pairing: "" (default, pair code path) | "scan". Threaded into
+  // the request body so the server can allow an empty clientUserId for the
+  // scan host-claim branch (spec "服务端支持 scan 模式的 pending 归属").
+  // Never persisted server-side — request-only semantics (spec L81).
+  pairMode = "",
+  // scan pending rows SHALL expire within 5 minutes (spec 安全信封 §2); the
+  // pair-code path keeps its existing 600s default.
+  ttlSeconds = 600,
 }) {
   const url = `${relayUrl}/v1/pair-sessions`;
+  const normalizedRuntime = normalizeRuntimeKind(runtimeKind, RUNTIME_KIND_OPENCLAW);
   const headers = {
     "content-type": "application/json",
     ...relayAuthHeaders(),
@@ -4210,7 +4501,7 @@ async function publishPairToRelay({
     headers,
     body: JSON.stringify({
       code,
-      runtimeKind: normalizeRuntimeKind(runtimeKind, RUNTIME_KIND_OPENCLAW),
+      runtimeKind: normalizedRuntime,
       transportMode: normalizeChatTransportMode(transportMode, "relay"),
       ...(clientUserId ? { clientUserId } : {}),
       bindUrl,
@@ -4220,9 +4511,14 @@ async function publishPairToRelay({
       ...(relayClientToken ? { relayClientToken } : {}),
       ...(relayGatewayToken ? { relayGatewayToken } : {}),
       accountId,
-      ttlSeconds: 600,
+      ttlSeconds,
       source: "agentlink-cli",
       hostName: normalizeHostName(os.hostname()),
+      // /v1/pair-sessions 是 OpenClaw/Hermes 的旧配对入口；必须同步 v2
+      // 工作区身份，避免 relay 把已配对 gateway 当作 legacy bridge。
+      installation_id: getOrCreateInstallationId(),
+      capabilities: pairingCapabilitiesForRuntime(normalizedRuntime),
+      ...(pairMode ? { pairMode } : {}),
     }),
   });
   const text = await response.text();
@@ -5444,11 +5740,12 @@ async function handleUnifiedRunDispatch({
   gatewayAuthToken,
   bridgeToken,
   defaultModel,
+  openclawConfig,
   request,
   json: jsonMode,
 }) {
   const inner = request?.request ?? {};
-  const { thread_id, run_id, input, blocks: rawBlocks = [] } = inner;
+  const { thread_id, run_id, input, blocks: rawBlocks = [], workspace_path } = inner;
 
   if (!thread_id || !run_id) {
     if (!jsonMode) {
@@ -5555,6 +5852,28 @@ async function handleUnifiedRunDispatch({
     }
   }
 
+  // OpenClaw's strict /v1/responses schema has no request-level cwd. Select
+  // the workspace through agent_id and verify that agent's configured
+  // workspace before dispatch; a mismatch must never fall back to main.
+  const agentId = String(inner.agent_id || request.agentId || "main").trim() || "main";
+  if (workspace_path) {
+    try {
+      const contextUrl = new URL("../src-ext/runtime/openclaw/workspaceContext.mjs", import.meta.url).href;
+      const { assertOpenClawWorkspaceContext } = await import(contextUrl);
+      assertOpenClawWorkspaceContext({ config: openclawConfig, agentId, workspacePath: workspace_path });
+    } catch (workspaceError) {
+      try {
+        await postEnvelopes([_buildRunFailed(
+          run_id,
+          "workspace_context_unavailable",
+          String(workspaceError?.message || "openclaw workspace context is unavailable"),
+        )]);
+      } catch { /* best-effort */ }
+      cleanupActiveRunContext(thread_id, run_id);
+      return;
+    }
+  }
+
   // bridge-auto-tunnel: chat-side `/tunnel ls` / `/tunnel off <port>` 拦截。
   // 命中 → 直接 reply bridge-origin text block + run.completed，跳过本地
   // OpenClaw 网关派发。失败 / 未命中 → 兜底 pass-through 继续走 runtime。
@@ -5645,10 +5964,13 @@ async function handleUnifiedRunDispatch({
   // 每轮都是全新 session → 上下文断裂（实测 "go on" 不知道前文是什么）。
   // 用 thread_id 后，同一 agentlink thread 内的所有 turn 落到 openclaw 的
   // 同一个 session bucket，上下文自然续接。
+  // unify-scan-pairing 全量移除了上一代扫码硬件的命名空间归一 hack:扫码路径
+  // 现在与 pair code 共用同一套真实 runtime binding(openclaw/hermes),不再有
+  // App 以合成命名空间 agent 绑定的场景,agentId 直接原样使用。
   const headers = {
     "content-type": "application/json",
     "accept": "text/event-stream",
-    "x-openclaw-agent-id": inner.agent_id || request.agentId || "main",
+    "x-openclaw-agent-id": agentId,
     "x-openclaw-session-key": thread_id,
     "x-openclaw-scopes": DEFAULT_GATEWAY_SCOPES,
   };
@@ -5664,7 +5986,7 @@ async function handleUnifiedRunDispatch({
   // (which lives in agents.defaults.model.primary). The accepted forms are
   // `openclaw` (default agent) or `openclaw/<agentId>`. The agentId comes from
   // the dispatch payload's agent_id (or "main" if absent).
-  const agentId = inner.agent_id || request.agentId || "main";
+  // (agentId 已在上方解析,缺省回退 "main"。)
   if (!jsonMode) {
     const blockSummary = blocks.map((b) => {
       const kind = b?.source?.kind ? `/${b.source.kind}` : "";
@@ -6340,6 +6662,7 @@ async function runRelayBridge({
             gatewayAuthToken,
             bridgeToken: gatewayToken, // server lookupBridgeToken accepts relay_gateway_token
             defaultModel: bridgeMeta?.openclawConfig?.agents?.defaults?.model?.primary || null,
+            openclawConfig: bridgeMeta?.openclawConfig || null,
             request,
             json,
           });
@@ -6425,7 +6748,10 @@ function formatServiceStatusOutput(result) {
     .join("\n");
 }
 
-// 探测本机已安装的 4 种 runtime。返回顺序：openclaw / hermes / claude / codex。
+// 探测本机已安装的 runtime。集合与返回顺序 = HOST_DETECTED_RUNTIME_KINDS
+// （openclaw / hermes / claude / codex / opencode）。
+// 🔴 deepagents 不在这里：它只入 runtime 枚举，本机没有任何探测手段 —— 没探测过
+//    就不能出现在探测表/host-inventory 里谎报 not_installed。
 // 设计：每项探测要快（≤3s），失败时给出可读 hint。
 // opts.probeVersion=false：只判 installed（which / 文件存在），跳过 `--version`
 //   子进程探测 —— reset 不需要版本号，省去 hermes 最长 60s 的 ls-remote 宽限延迟。
@@ -6462,7 +6788,11 @@ function detectInstalledRuntimes({ probeVersion = true } = {}) {
     });
   }
 
-  // hermes / claude / codex：检测 PATH 中的 CLI 二进制。
+  // hermes / claude / codex / opencode：检测 PATH 中的 CLI 二进制。
+  // opencode（add-deepagents-opencode-runtime-enum）复用**完全同一套** installed
+  // 判定，不另造探测逻辑；自 opencode-pairable 起它同时进入配对扇出目标
+  // （单 runtime 的 `pair -r opencode` 另有 src-ext/runtime/opencode/preflight.mjs
+  // 在消费配对码前再确认一次二进制可用，同构自 codex 的 preflight）。
   //
   // hermes = Nous Research `hermes-agent`（https://github.com/nousresearch/hermes-agent），
   // 装好后会在 PATH 暴露 `hermes` 命令，`hermes --version` 首行形如
@@ -6480,27 +6810,37 @@ function detectInstalledRuntimes({ probeVersion = true } = {}) {
   //      （banner.py:140 timeout=10s），网络慢时整条 spawnSync 会 ETIMEDOUT 被
   //      上层误判"未安装"；现在不依赖它。
   //   ② 拿到 binary 后再跑 `--version` 取版本字符串，超时不影响 installed 判断；
-  //      hermes 给 60s 宽限（GitHub ls-remote + git fetch 可能慢），claude/codex
-  //      是 native 二进制保留 10s。
-  for (const bin of ["hermes", "claude", "codex"]) {
+  //      hermes 给 60s 宽限（GitHub ls-remote + git fetch 可能慢），
+  //      claude/codex/opencode 是 native 二进制保留 10s。
+  for (const kind of PATH_PROBED_RUNTIME_KINDS) {
     const whichCmd = process.platform === "win32" ? "where" : "which";
-    const which = spawnSync(whichCmd, [bin], {
-      encoding: "utf8", timeout: 2000, windowsHide: true,
-    });
-    const binPath = (!which.error && which.status === 0)
-      ? String(which.stdout ?? "").trim().split(/\r?\n/)[0]
-      : "";
+    const candidates = RUNTIME_BINARY_CANDIDATES[kind] ?? [kind];
+    let bin = candidates[0];
+    let which = null;
+    let binPath = "";
+    for (const candidate of candidates) {
+      const probeWhich = spawnSync(whichCmd, [candidate], {
+        encoding: "utf8", timeout: 2000, windowsHide: true,
+      });
+      if (!probeWhich.error && probeWhich.status === 0) {
+        bin = candidate;
+        which = probeWhich;
+        binPath = String(probeWhich.stdout ?? "").trim().split(/\r?\n/)[0];
+        break;
+      }
+      which = probeWhich;
+    }
     if (!binPath) {
       const code = which.error?.code || "";
       const hint = code && code !== "ENOENT"
         ? t("pair_all_hint_which_failed", { cmd: whichCmd, bin, code })
         : t("pair_all_hint_bin_not_in_path", { bin });
-      results.push({ kind: bin, installed: false, hint });
+      results.push({ kind, installed: false, hint });
       continue;
     }
     if (!probeVersion) {
       // reset 路径：只需 installed 布尔，跳过 `--version`（省 hermes 最长 60s 宽限）。
-      results.push({ kind: bin, installed: true });
+      results.push({ kind, installed: true });
       continue;
     }
     // ② 取版本（best-effort）。hermes 第一次跑会做 git ls-remote 检查更新，
@@ -6513,7 +6853,7 @@ function detectInstalledRuntimes({ probeVersion = true } = {}) {
     if (!probe.error && probe.status === 0) {
       version = String(probe.stdout ?? "").trim().split(/\r?\n/)[0] || "";
     }
-    const entry = { kind: bin, installed: true, version: version || t("pair_all_version_unknown") };
+    const entry = { kind, installed: true, version: version || t("pair_all_version_unknown") };
     if (!version) {
       // 记一下为啥没拿到版本，方便用户/我们之后定位
       const code = probe.error?.code;
@@ -6531,11 +6871,199 @@ function detectInstalledRuntimes({ probeVersion = true } = {}) {
   return results;
 }
 
+// ─── per-runtime local pair-state helpers ───────────────────────────────────
+// 抽出自 runPairAll（原为其内部闭包）：unify-scan-pairing 的 runScan 复用同一套
+// "本机已有凭证 + 服务端 binding 是否还活着" 判定逻辑（spec S3），避免两套配对
+// 代码漂移。纯函数/无 runPairAll 局部状态捕获，提到顶层不改变行为。
+
+// openclaw + hermes 的 pair state 都存在 ~/.agentlink/config.json：
+//   openclaw → relayGatewayId/relayGatewayToken
+//   hermes  → hermesRelayGatewayId/hermesRelayGatewayToken
+// claude/codex/opencode 存在 ~/.agentlink/ext-<runtime>-last.json。
+//
+// 🔴 目录一律走 resolveAgentlinkHome()（优先 AGENTLINK_HOME），**不得**用
+// `process.env.HOME + "/.agentlink"` 自己拼：写方（ext 侧 pairCodeClient.stateDir()）
+// 与探方（runtimeHasLocalState）都优先认 AGENTLINK_HOME，这里拼裸 HOME 会造成
+// 「写在 A、探在 A、读/清在 B」的三方分叉 —— 已配对的 ext-agent runtime 被判成未
+// 配对而重复 consume（服务端多一条 orphan binding），stale 清理又会去删另一个
+// HOME 下的同名凭证（误删别人的）。launchd/systemd 单元本身就注入 AGENTLINK_HOME
+// （见 3600/3636/3841 行），所以这不是理论风险。
+//
+// 返回 { gw_id, token, relay_url } 或 null。
+function readLocalPairState(kind) {
+  try {
+    const agentlinkHome = resolveAgentlinkHome();
+    if (!agentlinkHome) return null;
+    // ext-agent 家族（claude / codex / opencode）：凭证在 ext-<kind>-last.json。
+    // 🔴 判据走登记表而不是字面量 —— 漏一个就会掉进下面的 config.json 分支，
+    // 把 openclaw 的 relayGatewayId 当成它的凭证读出来（静默错配的读方向）。
+    if (EXT_AGENT_RUNTIME_KINDS.includes(kind)) {
+      const p = path.join(agentlinkHome, `ext-${kind}-last.json`);
+      if (!fs.existsSync(p)) return null;
+      const j = JSON.parse(fs.readFileSync(p, "utf8"));
+      const gw = j?.gw_id || "";
+      const tok = j?.bridge_token || "";
+      if (!gw || !tok) return null;
+      return { gw_id: gw, token: tok, relay_url: j?.relay_url || "" };
+    }
+    if (kind === "openclaw" || kind === "hermes") {
+      const p = path.join(agentlinkHome, "config.json");
+      if (!fs.existsSync(p)) return null;
+      let j;
+      try { j = JSON.parse(fs.readFileSync(p, "utf8")); }
+      catch { return null; }
+      const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
+      const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
+      const gw = j?.[idKey] || "";
+      const tok = j?.[tokKey] || "";
+      if (!gw) return null;
+      return { gw_id: gw, token: tok, relay_url: j?.relayUrl || "" };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// 删本机 state 文件（App 删除后 server 没了，CLI 需要清干净本机才能 re-pair）。
+function clearLocalPairState(kind) {
+  try {
+    // 与 readLocalPairState 同一判据（登记表驱动）**且同一目录解析**
+    // （resolveAgentlinkHome / 优先 AGENTLINK_HOME）—— 读写必须落在同一个文件上，
+    // 否则"清理"是空操作、真正被删的却是另一个 HOME 下的同名凭证。
+    const agentlinkHome = resolveAgentlinkHome();
+    if (!agentlinkHome) return;
+    if (EXT_AGENT_RUNTIME_KINDS.includes(kind)) {
+      const p = path.join(agentlinkHome, `ext-${kind}-last.json`);
+      if (fs.existsSync(p)) {
+        try { fs.unlinkSync(p); } catch {}
+      }
+      return;
+    }
+    if (kind === "openclaw" || kind === "hermes") {
+      const p = path.join(agentlinkHome, "config.json");
+      if (!fs.existsSync(p)) return;
+      let j;
+      try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return; }
+      const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
+      const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
+      const clientTokKey = kind === "openclaw" ? "relayClientToken" : "hermesRelayClientToken";
+      delete j[idKey];
+      delete j[tokKey];
+      delete j[clientTokKey];
+      try { fs.writeFileSync(p, JSON.stringify(j, null, 2)); } catch {}
+    }
+  } catch {}
+}
+
+// 服务端探"绑定状态"：GET /v1/gateways/<gw>/binding 返回当前 active
+// (consumed=1) 的 app-user 绑定。
+//   - 404/401/410          → 服务端 pair_session 已不存在/无权 → 视为已删
+//   - 200 且 binding=null   → 网关 session 还在但没有 active 绑定（典型：App
+//                             删除了智能体把 pair_session 软删；或网关重连
+//                             host-claim 复活出一条 consumed=0 的行）→ 视为已删
+//   - 200 且 binding!=null  → 仍有 active 绑定 → 还在
+//   - 5xx / 超时            → 网络/服务端问题，保守按"还在"处理，不误删本机 state
+//
+// 不要用 /meta 探活：那只校验网关 bridge_token / 进程是否存活，网关还在跑就返
+// 200，**不反映 app-user 绑定是否已被删**。openclaw/hermes 网关常驻，App 删除
+// 智能体后 /meta 仍 200 → 误判"已配对"、跳过重配对（这正是删 openclaw 后再添加
+// 显示"已配对"的根因）。
+//
+// 也不要比对 binding.code 跟用户传的 code —— pair code 每次扫码新生成，用户拿
+// 新 code 重跑 pair 时 binding 里仍是旧 code，对不上是常态；只判断 binding 是否
+// 存在即可，避免把"换码重配对"误判成需要 re-pair。
+async function probeRelayBinding(state) {
+  if (!state || !state.gw_id) {
+    return { alive: true, reason: "no_probe_url" };
+  }
+  // 老 state 缺 relay_url（典型 openclaw 老格式）→ 回退 env / 内置默认 relay
+  // 再探，而不是直接按"已配对"跳过：那条逃逸正是 P0#18 ReOpen 的残留路径——
+  // App 删除智能体后用户重新 pair，老 state 机器永远卡在「已配对，跳过」。
+  let relayUrl = String(state.relay_url || "").trim();
+  if (!relayUrl) {
+    relayUrl =
+      String(process.env.OPENIM_RELAY_URL || "").trim() ||
+      String(process.env.AGENTLINK_RELAY_URL || "").trim() ||
+      DEFAULT_RELAY_URL;
+  }
+  if (!state.token) {
+    // 没有网关凭证 → 探不了也证明不了 binding 存活。用户此刻正在主动
+    // `pair <code>`，重配对幂等且是用户意图；按 stale 走清理+重配对，
+    // 比误判「已配对」把用户卡死安全。
+    return { alive: false, reason: "no_gateway_token" };
+  }
+  const base = relayUrl.replace(/\/$/, "");
+  const url = `${base}/v1/gateways/${encodeURIComponent(state.gw_id)}/binding`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 3000);
+  try {
+    const resp = await fetch(url, {
+      method: "GET",
+      signal: controller.signal,
+      headers: {
+        "Authorization": `Bearer ${state.token}`,
+      },
+    });
+    clearTimeout(timer);
+    // 401 (token 无效) / 404 (gateway session 不存在) / 410 → server 端已删
+    if (resp.status === 401 || resp.status === 404 || resp.status === 410) {
+      return { alive: false, reason: `http_${resp.status}` };
+    }
+    if (resp.ok) {
+      let body = null;
+      try {
+        body = await resp.json();
+      } catch {
+        // 解析失败时保守按"还在"处理，不误删
+        return { alive: true, reason: "binding_parse_failed_assume_alive" };
+      }
+      const binding =
+        body && typeof body === "object" ? body.binding : undefined;
+      // binding 为 null/缺失 → 没有 active 绑定 → 视为已删
+      if (binding == null) {
+        return { alive: false, reason: "binding_null" };
+      }
+      return { alive: true, reason: `http_${resp.status}` };
+    }
+    // 500/503 等服务端错误 → 保守不删
+    return { alive: true, reason: `http_${resp.status}_assume_alive` };
+  } catch (err) {
+    clearTimeout(timer);
+    // 网络超时 / DNS 失败 → 保守不删
+    return { alive: true, reason: `network_err_assume_alive` };
+  }
+}
+
+// 对应 runtime 的"重置后重新配对"命令提示。
+function resetHintFor(kind, code) {
+  // ext-agent 家族没有 reset 子命令，其"解绑"即 uninstall（见 forwardToAgent）。
+  if (EXT_AGENT_RUNTIME_KINDS.includes(kind)) {
+    return `agentlink uninstall -r ${kind} && agentlink pair ${code} -r ${kind}`;
+  }
+  // openclaw / hermes 走 reset 子命令
+  return `agentlink reset -r ${kind} && agentlink pair ${code} -r ${kind}`;
+}
+
+// 每 runtime 一次 host-claim 子进程 spawn（unify-scan-pairing 抽出，供
+// runPairAll 与 runScan 共用，"出码方式"通过 extraArgv 注入 —— pair code
+// 路径转发原始 argv 不变；scan 路径注入 `pair <code> --pair-mode scan
+// --no-serve-relay ...`，见 runScan()）。隔离 fail()/process.exit：单个
+// runtime 失败不影响其余 runtime（每个都是独立子进程）。
+function spawnPairChildForRuntime({ argvTail, runtimeKind, env }) {
+  const argv = [CLI_ENTRY, ...argvTail, "--runtime", runtimeKind];
+  const child = spawnSync(process.execPath, argv, { stdio: "inherit", env });
+  return { kind: runtimeKind, ok: child.status === 0, status: child.status ?? null };
+}
+
 // `agentlink pair <code>` 默认批量配对所有已安装 runtime。
 // 也兼容 `agentlink pair <code> --runtime all` 显式写法。
-// 检测本机安装的 4 种 runtime（openclaw / hermes / claude / codex），
-// 对每个已安装的 runtime 串行 spawn 一次自身（替换 --runtime <kind>），
+// 检测本机安装的 runtime（HOST_DETECTED_RUNTIME_KINDS），对每个「已安装 **且**
+// 本轮有配对实现」的 runtime 串行 spawn 一次自身（替换 --runtime <kind>），
 // 互不影响 fail()，最后汇总结果。
+// opencode 自 devagent-m-20260807-cli-runtime-opencode-pairable 起**已进扇出**
+// （它有了真配对实现）。已装但仍无配对实现的 runtime 才只进 host-inventory 上报、
+// 不进扇出 —— 见 runPairAll 内 pairTargetKinds 处注释。
 async function runPairAll(options) {
   if (!options.code || !String(options.code).trim()) {
     fail(t("pair_usage_missing"));
@@ -6557,7 +7085,21 @@ async function runPairAll(options) {
 
   const installedKinds = detected.filter((d) => d.installed).map((d) => d.kind);
   if (installedKinds.length === 0) {
-    fail(t("pair_all_no_runtimes"));
+    fail(t("pair_all_no_runtimes", { kinds: HOST_DETECTED_RUNTIME_KINDS.join(" / ") }));
+  }
+
+  // 扇出目标 = 已安装 ∩ 可配对集。已装但没有配对实现的 runtime **必须**排除在外：
+  // 给它 spawn 一次 `--runtime <kind>` 只会撞 assertRuntimeOperableOrFail() 白拿
+  // 一个非 0 退出，把整批 pair-all 拖成失败（纯回归）。
+  // 但它仍留在 installedKinds 里上报给 relay —— 「本机装了它」是事实，App 需要知道。
+  //
+  // 现状：本机探测集 ⊆ 可配对集（opencode 自本轮起有了配对实现），所以
+  // pairUnsupportedKinds 实际恒空。**保留**这条分支而不是删掉：它是由登记表
+  // 派生的通用兜底，下一个"只入探测、还没配对实现"的 runtime 会立刻用上。
+  const pairTargetKinds = installedKinds.filter((k) => PAIRABLE_RUNTIME_KINDS.includes(k));
+  const pairUnsupportedKinds = installedKinds.filter((k) => !PAIRABLE_RUNTIME_KINDS.includes(k));
+  for (const kind of pairUnsupportedKinds) {
+    console.log(t("pair_all_runtime_pair_unsupported", { kind }));
   }
 
   // host-inventory side channel —— 在 spawn 子配对命令之前,先把本机装好的
@@ -6626,7 +7168,10 @@ async function runPairAll(options) {
       continue;
     }
     if (a === "--allow-rebind") {
-      continue; // 后面会显式加一次，去重
+      // 刻意**不**转发给子进程：pair-all 的语义是「把没配对的都配上」，已配对的
+      // 由下面的 probeRelayBinding 判定后跳过，不做覆盖兜底（见下一段注释）。
+      // ⚠️ 注释曾写「后面会显式加一次」——那是早期实现，现已不再回注；别照着补回去。
+      continue;
     }
     forwardedArgv.push(a);
   }
@@ -6642,162 +7187,11 @@ async function runPairAll(options) {
     AGENTLINK_AGENT_LOG_LEVEL: process.env.AGENTLINK_AGENT_LOG_LEVEL || "warn",
   };
 
-  // openclaw + hermes 的 pair state 都存在 ~/.agentlink/config.json：
-  //   openclaw → relayGatewayId/relayGatewayToken
-  //   hermes  → hermesRelayGatewayId/hermesRelayGatewayToken
-  // claude/codex 存在 ~/.agentlink/ext-<runtime>-last.json。
-  //
-  // 返回 { gw_id, token, relay_url } 或 null。
-  function readLocalPairState(kind) {
-    try {
-      const home = process.env.HOME || "";
-      if (!home) return null;
-      if (kind === "claude" || kind === "codex") {
-        const p = `${home}/.agentlink/ext-${kind}-last.json`;
-        if (!fs.existsSync(p)) return null;
-        const j = JSON.parse(fs.readFileSync(p, "utf8"));
-        const gw = j?.gw_id || "";
-        const tok = j?.bridge_token || "";
-        if (!gw || !tok) return null;
-        return { gw_id: gw, token: tok, relay_url: j?.relay_url || "" };
-      }
-      if (kind === "openclaw" || kind === "hermes") {
-        const p = `${home}/.agentlink/config.json`;
-        if (!fs.existsSync(p)) return null;
-        let j;
-        try { j = JSON.parse(fs.readFileSync(p, "utf8")); }
-        catch { return null; }
-        const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
-        const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
-        const gw = j?.[idKey] || "";
-        const tok = j?.[tokKey] || "";
-        if (!gw) return null;
-        return { gw_id: gw, token: tok, relay_url: j?.relayUrl || "" };
-      }
-      return null;
-    } catch {
-      return null;
-    }
-  }
-
-  // 删本机 state 文件（App 删除后 server 没了，CLI 需要清干净本机才能 re-pair）。
-  function clearLocalPairState(kind) {
-    try {
-      const home = process.env.HOME || "";
-      if (!home) return;
-      if (kind === "claude" || kind === "codex") {
-        const p = `${home}/.agentlink/ext-${kind}-last.json`;
-        if (fs.existsSync(p)) {
-          try { fs.unlinkSync(p); } catch {}
-        }
-        return;
-      }
-      if (kind === "openclaw" || kind === "hermes") {
-        const p = `${home}/.agentlink/config.json`;
-        if (!fs.existsSync(p)) return;
-        let j;
-        try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return; }
-        const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
-        const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
-        const clientTokKey = kind === "openclaw" ? "relayClientToken" : "hermesRelayClientToken";
-        delete j[idKey];
-        delete j[tokKey];
-        delete j[clientTokKey];
-        try { fs.writeFileSync(p, JSON.stringify(j, null, 2)); } catch {}
-      }
-    } catch {}
-  }
-
-  // 服务端探"绑定状态"：GET /v1/gateways/<gw>/binding 返回当前 active
-  // (consumed=1) 的 app-user 绑定。
-  //   - 404/401/410          → 服务端 pair_session 已不存在/无权 → 视为已删
-  //   - 200 且 binding=null   → 网关 session 还在但没有 active 绑定（典型：App
-  //                             删除了智能体把 pair_session 软删；或网关重连
-  //                             host-claim 复活出一条 consumed=0 的行）→ 视为已删
-  //   - 200 且 binding!=null  → 仍有 active 绑定 → 还在
-  //   - 5xx / 超时            → 网络/服务端问题，保守按"还在"处理，不误删本机 state
-  //
-  // 不要用 /meta 探活：那只校验网关 bridge_token / 进程是否存活，网关还在跑就返
-  // 200，**不反映 app-user 绑定是否已被删**。openclaw/hermes 网关常驻，App 删除
-  // 智能体后 /meta 仍 200 → 误判"已配对"、跳过重配对（这正是删 openclaw 后再添加
-  // 显示"已配对"的根因）。
-  //
-  // 也不要比对 binding.code 跟用户传的 code —— pair code 每次扫码新生成，用户拿
-  // 新 code 重跑 pair 时 binding 里仍是旧 code，对不上是常态；只判断 binding 是否
-  // 存在即可，避免把"换码重配对"误判成需要 re-pair。
-  async function probeRelayBinding(state) {
-    if (!state || !state.gw_id) {
-      return { alive: true, reason: "no_probe_url" };
-    }
-    // 老 state 缺 relay_url（典型 openclaw 老格式）→ 回退 env / 内置默认 relay
-    // 再探，而不是直接按"已配对"跳过：那条逃逸正是 P0#18 ReOpen 的残留路径——
-    // App 删除智能体后用户重新 pair，老 state 机器永远卡在「已配对，跳过」。
-    let relayUrl = String(state.relay_url || "").trim();
-    if (!relayUrl) {
-      relayUrl =
-        String(process.env.OPENIM_RELAY_URL || "").trim() ||
-        String(process.env.AGENTLINK_RELAY_URL || "").trim() ||
-        DEFAULT_RELAY_URL;
-    }
-    if (!state.token) {
-      // 没有网关凭证 → 探不了也证明不了 binding 存活。用户此刻正在主动
-      // `pair <code>`，重配对幂等且是用户意图；按 stale 走清理+重配对，
-      // 比误判「已配对」把用户卡死安全。
-      return { alive: false, reason: "no_gateway_token" };
-    }
-    const base = relayUrl.replace(/\/$/, "");
-    const url = `${base}/v1/gateways/${encodeURIComponent(state.gw_id)}/binding`;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 3000);
-    try {
-      const resp = await fetch(url, {
-        method: "GET",
-        signal: controller.signal,
-        headers: {
-          "Authorization": `Bearer ${state.token}`,
-        },
-      });
-      clearTimeout(timer);
-      // 401 (token 无效) / 404 (gateway session 不存在) / 410 → server 端已删
-      if (resp.status === 401 || resp.status === 404 || resp.status === 410) {
-        return { alive: false, reason: `http_${resp.status}` };
-      }
-      if (resp.ok) {
-        let body = null;
-        try {
-          body = await resp.json();
-        } catch {
-          // 解析失败时保守按"还在"处理，不误删
-          return { alive: true, reason: "binding_parse_failed_assume_alive" };
-        }
-        const binding =
-          body && typeof body === "object" ? body.binding : undefined;
-        // binding 为 null/缺失 → 没有 active 绑定 → 视为已删
-        if (binding == null) {
-          return { alive: false, reason: "binding_null" };
-        }
-        return { alive: true, reason: `http_${resp.status}` };
-      }
-      // 500/503 等服务端错误 → 保守不删
-      return { alive: true, reason: `http_${resp.status}_assume_alive` };
-    } catch (err) {
-      clearTimeout(timer);
-      // 网络超时 / DNS 失败 → 保守不删
-      return { alive: true, reason: `network_err_assume_alive` };
-    }
-  }
-
-  // 对应 runtime 的"重置后重新配对"命令提示。
-  function resetHintFor(kind, code) {
-    if (kind === "claude" || kind === "codex") {
-      return `agentlink uninstall -r ${kind} && agentlink pair ${code} -r ${kind}`;
-    }
-    // openclaw / hermes 走 reset 子命令
-    return `agentlink reset -r ${kind} && agentlink pair ${code} -r ${kind}`;
-  }
+  // readLocalPairState / clearLocalPairState / probeRelayBinding / resetHintFor
+  // 已提到顶层（供 runScan 复用，见其上方注释），行为不变。
 
   const summary = [];
-  for (const kind of installedKinds) {
+  for (const kind of pairTargetKinds) {
     const state = readLocalPairState(kind);
     if (state) {
       const probe = await probeRelayBinding(state);
@@ -6825,12 +7219,10 @@ async function runPairAll(options) {
       clearLocalPairState(kind);
     }
     console.log(t("pair_all_pairing_runtime", { kind }));
-    const argv = [CLI_ENTRY, ...forwardedArgv, "--runtime", kind];
-    const child = spawnSync(process.execPath, argv, { stdio: "inherit", env: quietEnv });
-    const ok = child.status === 0;
-    summary.push({ kind, ok, status: child.status ?? null });
+    const { ok, status } = spawnPairChildForRuntime({ argvTail: forwardedArgv, runtimeKind: kind, env: quietEnv });
+    summary.push({ kind, ok, status });
     if (!ok) {
-      console.warn(t("pair_all_runtime_pair_failed", { kind, status: child.status ?? "?" }));
+      console.warn(t("pair_all_runtime_pair_failed", { kind, status: status ?? "?" }));
     }
   }
 
@@ -6859,7 +7251,7 @@ async function runPairAll(options) {
     }
   }
 
-  // 汇总：4 行 max（4 种 runtime），一眼扫完。
+  // 汇总：一行一类，一眼扫完。
   const newlyPaired = summary.filter((s) => s.ok && !s.skipped).map((s) => s.kind);
   const alreadyPaired = summary.filter((s) => s.skipped).map((s) => s.kind);
   const failList = summary.filter((s) => !s.ok);
@@ -6878,13 +7270,23 @@ async function runPairAll(options) {
       detail: failList.map((s) => `${s.kind}[exit ${s.status}]`).join("、"),
     }));
   }
+  if (pairUnsupportedKinds.length > 0) {
+    console.log(t("pair_all_summary_pair_unsupported", {
+      count: pairUnsupportedKinds.length,
+      kinds: pairUnsupportedKinds.join("、"),
+    }));
+  }
   if (notInstalledList.length > 0) {
     console.log(t("pair_all_summary_not_installed", { count: notInstalledList.length, kinds: notInstalledList.join("、") }));
   }
-  if (failList.length === 0) {
+  if (failList.length > 0) {
+    console.log(t("pair_all_summary_failure_hint"));
+  } else if (newlyPaired.length > 0 || alreadyPaired.length > 0) {
     console.log(t("pair_all_summary_ok_hint"));
   } else {
-    console.log(t("pair_all_summary_failure_hint"));
+    // 本机只装了「已知但无配对实现」的 runtime（如只装了 opencode）：
+    // 一个都没配上，别报「回 App 看已配对的智能体」那种假成功。
+    console.log(t("pair_all_summary_nothing_pairable"));
   }
   console.log("");
 
@@ -6913,13 +7315,19 @@ async function runResetAll(options) {
   // reset 不需要版本号 → 跳过 `--version` 探测（省 hermes 最长 60s 宽限）。
   const detected = detectInstalledRuntimes({ probeVersion: false });
   const installedKinds = detected.filter((d) => d.installed).map((d) => d.kind);
+  // 只有「可配对集」的 runtime 会留下可解绑痕迹（config.json 的凭证 / ext-<rt>-last.json）。
+  // 无配对实现的 runtime 不可能存在绑定，装了也没什么可解绑的 ——
+  // 放进目标集只会让子进程撞 assertRuntimeOperableOrFail()、把整批 reset 拖成非 0 退出。
+  // opencode 自本轮起在可配对集内：它会正常进入解绑目标（走 agentlink-agent uninstall）。
+  const installedPairableKinds = installedKinds.filter((k) => PAIRABLE_RUNTIME_KINDS.includes(k));
+  const noBindingKinds = installedKinds.filter((k) => !PAIRABLE_RUNTIME_KINDS.includes(k));
   // 未安装但有本地痕迹（卸了 CLI / 删了 openclaw.json 但 binding 还在）的 runtime
   // 也要纳入清理。读 reset 实际操作的同一批文件（config.json / ext-<rt>-last.json）。
-  const ALL_KINDS = [RUNTIME_KIND_OPENCLAW, RUNTIME_KIND_HERMES, "claude", "codex"];
+  const ALL_KINDS = PAIRABLE_RUNTIME_KINDS;
   const stateOnlyKinds = ALL_KINDS.filter(
-    (k) => !installedKinds.includes(k) && runtimeHasLocalState(k),
+    (k) => !installedPairableKinds.includes(k) && runtimeHasLocalState(k),
   );
-  const targetKinds = [...installedKinds, ...stateOnlyKinds];
+  const targetKinds = [...installedPairableKinds, ...stateOnlyKinds];
   // 真正「无事可做」的 runtime（既没装、也没痕迹）才算 not-installed。
   const notInstalledList = detected
     .filter((d) => !d.installed && !stateOnlyKinds.includes(d.kind))
@@ -6927,7 +7335,9 @@ async function runResetAll(options) {
 
   if (!json) {
     for (const entry of detected) {
-      if (entry.installed) {
+      if (entry.installed && noBindingKinds.includes(entry.kind)) {
+        console.log(t("reset_all_runtime_no_binding", { kind: entry.kind }));
+      } else if (entry.installed) {
         console.log(`  ✓ ${entry.kind}`);
       } else if (stateOnlyKinds.includes(entry.kind)) {
         console.log(t("reset_all_runtime_state_only", { kind: entry.kind }));
@@ -6939,6 +7349,8 @@ async function runResetAll(options) {
   }
   log.info("reset_all.targets", "resolved reset targets", {
     installed: installedKinds, stateOnly: stateOnlyKinds, notInstalled: notInstalledList,
+    // 已装但无配对实现 → 无绑定可解，不进目标集（诊断时能一眼看出为何被跳过）
+    noBinding: noBindingKinds,
   });
 
   if (targetKinds.length === 0) {
@@ -7040,7 +7452,12 @@ async function runPair({
   runtime,
   strictPlugin,
   allowRebind,
+  // unify-scan-pairing: "" (default, pair code manual-entry path) | "scan".
+  // Set internally by runScan's per-runtime host-claim child spawn
+  // (`--pair-mode scan`) — never by a human-typed `agentlink pair` call.
+  pairMode = "",
 }) {
+  const isScanMode = pairMode === "scan";
   if (!explicitCode || !String(explicitCode).trim()) {
     fail(t("pair_usage_missing"));
   }
@@ -7067,11 +7484,24 @@ async function runPair({
     );
   }
 
-  const currentSession = await readPairSessionFromRelay({
-    relayUrl,
-    code,
-    runtimeKind: requestedRuntime,
-  });
+  // scan 模式 SHALL 不做 host-ready 预检(spec P1-4):code 由 CLI 本地生成、
+  // 无 App 预建行,readPairSessionFromRelay 的 GET 预检会因"行不存在"误挡。
+  // 直接以合成的空会话继续,走下面统一的 publishPairToRelay(pairMode=scan)
+  // Upsert 建 pending 行。
+  const currentSession = isScanMode
+    ? {
+        accountId: "",
+        runtimeKind: requestedRuntime,
+        transportMode: "relay",
+        clientUserID: "",
+        bindUrl: "",
+        consumed: false,
+      }
+    : await readPairSessionFromRelay({
+        relayUrl,
+        code,
+        runtimeKind: requestedRuntime,
+      });
   if (!currentSession) {
     fail(
       [
@@ -7092,15 +7522,18 @@ async function runPair({
   const runtimeKind = requestedRuntime;
   // 复合主键升级后,GET 已经按 runtimeKind 精确取了对应的行,server 不会
   // 再返回其他 runtime 的数据,这里 mismatch 不可能发生 —— 保留旧检查仅作冗余防护。
-  if (runtime && runtimeKind !== sessionRuntimeKind) {
+  // scan 模式没有真实 GET 结果(currentSession 是本函数合成的),该检查天然满足,跳过即可。
+  if (!isScanMode && runtime && runtimeKind !== sessionRuntimeKind) {
     fail(t("pair_runtime_mismatch", { app: sessionRuntimeKind, cli: runtimeKind }));
   }
   const transportMode = normalizeChatTransportMode(
     mode,
     normalizeChatTransportMode(currentSession.transportMode, "relay"),
   );
+  // scan 模式:clientUserId 由 App scan-claim 时从 Bearer 派生,host-claim 阶段
+  // 天生为空(spec「服务端支持 scan 模式的 pending 归属」)——不是错误,不 fail()。
   const clientUserId = String(currentSession.clientUserID ?? "").trim().toLowerCase();
-  if (!clientUserId) {
+  if (!isScanMode && !clientUserId) {
     fail(
       [
         t("pair_missing_client_user_id"),
@@ -7176,8 +7609,13 @@ async function runPair({
     process.env.OPENCLAW_CUSTOM_IM_PUBLIC_BASE_URL?.trim() ||
     "";
 
+  // scan 模式:gateway.port 可能尚未配置(真机上通常已配置,但 host-claim 本身
+  // 不依赖它——scan 是 CLI-bridge 模型,relay-worker 轮询,不像 pair code 那条
+  // legacy 直连 webhook 路径需要一个外部可达的 bindUrl)。optional:true 让
+  // resolveGatewayBaseUrl 缺配置时返回 null 而不是 fail()/exit;pair code 路径
+  // (isScanMode=false)行为完全不变。
   const localGatewayBaseUrl = runtimeNeedsOpenClaw(runtimeKind)
-    ? resolveGatewayBaseUrl({ gateway }, config)
+    ? resolveGatewayBaseUrl({ gateway, optional: isScanMode }, config)
     : normalizeBaseUrl(gateway) || "";
   const gatewayAuthToken = runtimeNeedsOpenClaw(runtimeKind)
     ? resolveGatewayAuthToken(config)
@@ -7196,8 +7634,8 @@ async function runPair({
     accountId,
     code,
   });
-  const relayBindUrl = currentSession.bindUrl || publicBindUrl || localBindUrl;
-  if (!relayBindUrl) {
+  const relayBindUrl = currentSession.bindUrl || publicBindUrl || localBindUrl || (isScanMode ? "" : null);
+  if (!isScanMode && !relayBindUrl) {
     fail(t("pairurl_bind_url_unknown"));
   }
 
@@ -7291,16 +7729,24 @@ async function runPair({
         c.startsWith("gateway.http.endpoints.responses.enabled") ||
         c.startsWith("gateway.auth."),
     );
-  if (runtimeNeedsOpenClaw(runtimeKind) && prepared.changed) {
+  // scan 模式跳过重启宽限等待:出码循环追求"CLI 秒起二维码",这段睡眠/探测只是
+  // "让日志更友好"的诊断性等待(gatewayProbe.ok=false 只 warn,从不 fail() ——
+  // 不影响 publishPairToRelay 是否成功),对 pair code 手输路径行为不变
+  // (isScanMode 为 false 时,下面两处判断与改动前完全一致)。
+  if (runtimeNeedsOpenClaw(runtimeKind) && prepared.changed && !isScanMode) {
     await new Promise((resolve) => setTimeout(resolve, 2000));
   }
 
-  if (runtimeNeedsOpenClaw(runtimeKind)) {
+  // scan 模式且 gateway.port 未配置(localGatewayBaseUrl=null,见上方 optional:true)
+  // 时完全跳过探测——没有 URL 可探,buildGatewayResponsesUrlOrFail 遇 null 会
+  // fail()/exit,而这段探测本就只是诊断性的(见上方注释),跳过不影响正确性。
+  if (runtimeNeedsOpenClaw(runtimeKind) && (!isScanMode || localGatewayBaseUrl)) {
     // 90s covers the observed ~35s restart with ample margin; ~7s handles the
-    // steady-state case where openclaw is already serving.
-    const PROBE_ATTEMPTS = criticalChange ? 90 : prepared.changed ? 15 : 6;
+    // steady-state case where openclaw is already serving. scan 模式只探测
+    // 1 次、不重试(见上方注释)。
+    const PROBE_ATTEMPTS = isScanMode ? 1 : criticalChange ? 90 : prepared.changed ? 15 : 6;
     const PROBE_INTERVAL_MS = 1000;
-    const announcedStart = criticalChange;
+    const announcedStart = !isScanMode && criticalChange;
     if (announcedStart) {
       console.log(t("gateway_wait_restart"));
     }
@@ -7353,6 +7799,7 @@ async function runPair({
     relayClientToken: relayCredentials?.clientToken,
     relayGatewayToken: relayCredentials?.gatewayToken,
     accountId,
+    ...(isScanMode ? { pairMode: "scan", ttlSeconds: 300 } : {}),
   });
 
   const output = {
@@ -7960,6 +8407,281 @@ function runPairUrl({ json, account, code: explicitCode }) {
   console.log(resolvedBindUrl);
 }
 
+// `agentlink scan`：统一扫码配对（unify-scan-pairing，取代 add-openclaw-scan-pairing
+// 的上一代扫码硬件方案）——CLI 本地出一个高熵 code → 对每个 scan-capable
+// runtime（openclaw/hermes）host-claim → 渲染中性 deeplink 二维码 → 等 App
+// scan-claim → 起 worker。配对后效果与 pair code 路径完全一致（同一
+// `pair_sessions` 底座，同一 App 侧工作区选择流程），只有出码方式不同。
+//
+// `scan --json` 跨多阶段持续输出（探测 → 等待扫码 → 配对成功 → 起 worker），
+// 采用 NDJSON：每阶段一行紧凑 JSON object（见 printScanEvent）。
+function printScanEvent(fields) {
+  console.log(JSON.stringify({ command: "scan", ...fields }));
+}
+
+// claude/codex 在 scan 模式下没有 host-claim 路径（gateway 凭证由服务端在
+// consume 时才下发，host-claim 阶段无来源——spec 术语 + Non-goals，本期不做
+// pending 预分配子系统）。检测到时打印明确提示，不静默、不失败（S2b）。
+function scanUnsupportedRuntimeMessage(kinds) {
+  return `⚠️  ${kinds.join("/")} 暂不支持扫码配对（scan-capable runtime 仅 openclaw/hermes）。请改用 \`${CLI_COMMAND_NAME} pair <code> -r ${kinds[0]}\` 手动配对。`;
+}
+
+// env 覆盖仅供测试加速 S4(过期重出码)场景用——与既有
+// AGENTLINK_SCAN_QR_PNG_PATH 同一约定(见 scanPairFlow.mjs)。生产默认值:
+// 2s 轮询间隔、300s TTL(与 host-claim 请求的 ttlSeconds 对齐,安全信封 §2)。
+const SCAN_CLAIM_POLL_INTERVAL_MS = parseNonNegativeInt(process.env.AGENTLINK_SCAN_CLAIM_POLL_INTERVAL_MS) || 2000;
+// 轮询超过这个窗口还没等到 scan-claim,视为码已过期,重新出码(S4)，而不是无限等下去。
+const SCAN_CLAIM_TTL_MS = (parseNonNegativeInt(process.env.AGENTLINK_SCAN_CLAIM_TTL_SEC) || 300) * 1000;
+
+// 轮询等待 App scan-claim 完成。复用既有 readPairSessionFromRelay(GET
+// /v1/pair-sessions/:code)——scan-claim 会把该 code 下全部 pending 行标记
+// consumed=1(spec「新增端点」),任取其中一个已 host-claim 的 runtimeKind
+// 查询即可代表整组的归属状态,不需要新端点。
+async function waitForScanClaim({ relayUrl, code, representativeRuntimeKind, ttlMs, sleepImpl }) {
+  const sleep = sleepImpl || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const deadline = Date.now() + ttlMs;
+  for (;;) {
+    const session = await readPairSessionFromRelay({
+      relayUrl,
+      code,
+      runtimeKind: representativeRuntimeKind,
+    });
+    if (session && session.consumed) {
+      return true;
+    }
+    if (Date.now() >= deadline) {
+      return false;
+    }
+    await sleep(SCAN_CLAIM_POLL_INTERVAL_MS);
+  }
+}
+
+// 起本地已装 scan-capable runtime 的 worker：单 runtime 用既有前台 runBridge
+// （与 revoke 时既有 selfUninstallOnRevoke 退出路径完全一致，S6）；多 runtime
+// 复用 runPair `--serve-relay` 分支已经在用的后台服务安装机制（安装成功后各自
+// 独立常驻，不受本进程退出影响）。S1 的多 runtime 场景是 manual-device 验收
+// 载体（spec 执行载体声明），这里不额外发明新机制，只编排既有函数。
+async function startScanWorkers({ kinds, relayUrl, gateway, json }) {
+  if (kinds.length === 1) {
+    await runBridge({ json, relay: relayUrl, noRelay: false, gateway, runtime: kinds[0] });
+    return;
+  }
+  for (const kind of kinds) {
+    const gatewayBaseUrl = runtimeNeedsOpenClaw(kind)
+      ? resolveGatewayBaseUrl({ gateway, optional: true }, ensureObject(readOptionalJsonFile(resolveOpenClawConfigPath()))) || ""
+      : relayUrl; // hermes 占位:installBridgeService 契约要求非空,hermes 分支不读它。
+    try {
+      const serviceStatus = getBridgeServiceStatus(kind);
+      (serviceStatus.installed ? restartBridgeService : installBridgeService)({
+        relayUrl, gatewayBaseUrl, runtimeKind: kind,
+      });
+      if (!json) console.log(t("service_installed"));
+    } catch (err) {
+      if (!json) console.warn(`⚠️  ${kind} bridge service 安装失败：${err?.message || err}`);
+    }
+  }
+}
+
+async function runScan({ json, relay, noRelay, gateway, qrPath, noServe, strictPlugin, runtime }) {
+  // S2b（显式 -r 到非 scan-capable 的 ext-agent runtime）：不出码、不联系 relay，
+  // 直接提示 + 非零退出。（opencode 更早已被 assertRuntimeBridgeSupportedOrFail
+  // 拦停；这里保留登记表判据作双保险。）
+  if (EXT_AGENT_RUNTIME_KINDS.includes(runtime)) {
+    const message = scanUnsupportedRuntimeMessage([runtime]);
+    if (json) {
+      printScanEvent({ phase: "unsupported_runtime", unsupportedRuntimes: [runtime], hint: message });
+    } else {
+      console.error(message);
+    }
+    process.exit(1);
+  }
+
+  const config = ensureObject(readOptionalJsonFile(resolveOpenClawConfigPath()));
+  const section = readChannelSection(config);
+  const relayUrl = resolveRelayUrl({ relay, noRelay }, section);
+  if (!relayUrl) {
+    fail(
+      [
+        t("relay_url_required"),
+        t("relay_url_missing_detail"),
+        t("relay_url_hint"),
+      ].join("\n"),
+    );
+  }
+
+  // ── 探测本机已装 runtime，划出「scan-capable 候选集」（S1/S2）───────────
+  const detected = detectInstalledRuntimes();
+  const installedKinds = new Set(detected.filter((d) => d.installed).map((d) => d.kind));
+  // 已装、但不在 scan-capable 白名单里的 runtime：提示改走 pair（ext-agent 家族
+  // 的凭证由服务端在 consume 时下发，本机没有 host-claim 路径）。判据走登记表，
+  // 加 runtime 时不会漏提示。
+  const unsupportedDetected = detected
+    .filter((d) => d.installed && EXT_AGENT_RUNTIME_KINDS.includes(d.kind))
+    .map((d) => d.kind);
+
+  let candidateKinds;
+  if (runtime) {
+    // -r openclaw|hermes：只配这一个（S2）。校验值域已在 CLI 参数解析阶段完成
+    // （openclaw/hermes/claude/codex/opencode/deepagents/all）；ext-agent 家族
+    // （claude/codex/opencode）已在上面提前返回，enum-only 的 deepagents 与
+    // pair-only 的 opencode 更早就被命令分派前的两道显式拦停挡下，走不到这里。
+    if (!installedKinds.has(runtime)) {
+      fail(`${CLI_COMMAND_NAME} scan -r ${runtime}: runtime not installed on this host`);
+    }
+    candidateKinds = [runtime];
+  } else {
+    candidateKinds = SCAN_CAPABLE_RUNTIME_KINDS.filter((k) => installedKinds.has(k));
+  }
+  if (candidateKinds.length === 0) {
+    // 🔴 kinds 必须显式传:该文案自 add-deepagents-opencode-runtime-enum 起改成
+    // {kinds} 占位(不再把 runtime 名写死进文案),漏传会把字面 "{kinds}" 打给用户。
+    // 这里的语境是 scan,所以报的是 **scan-capable 集合**(openclaw/hermes),
+    // 不是 HOST_DETECTED 全集 —— 装了 opencode 也不构成"可扫码配对的 runtime"。
+    fail(t("pair_all_no_runtimes", { kinds: SCAN_CAPABLE_RUNTIME_KINDS.join(" / ") }));
+  }
+
+  if (unsupportedDetected.length > 0) {
+    const message = scanUnsupportedRuntimeMessage(unsupportedDetected);
+    if (json) {
+      printScanEvent({ phase: "unsupported_runtime_detected", unsupportedRuntimes: unsupportedDetected, hint: message });
+    } else {
+      console.log(message);
+    }
+  }
+
+  // ── S3：已有有效凭证 + 服务端 binding 仍存活的 runtime 直接跳过出码 ──────
+  const quietEnv = {
+    ...process.env,
+    AGENTLINK_AGENT_LOG_LEVEL: process.env.AGENTLINK_AGENT_LOG_LEVEL || "warn",
+  };
+  const alreadyAliveKinds = [];
+  const needsClaimKinds = [];
+  for (const kind of candidateKinds) {
+    const state = readLocalPairState(kind);
+    if (state) {
+      const probe = await probeRelayBinding(state);
+      if (probe.alive) {
+        alreadyAliveKinds.push(kind);
+        if (kind === RUNTIME_KIND_HERMES) {
+          try {
+            const hLog = _createBubLogger({ comp: "scan" }).child({ rt: "hermes" });
+            await ensureHermesEnvAndProbe(hLog);
+          } catch (err) {
+            console.warn(`⚠️  hermes env/gateway 自检失败：${err?.message || err}`);
+          }
+        }
+        continue;
+      }
+      clearLocalPairState(kind);
+    }
+    needsClaimKinds.push(kind);
+  }
+
+  let claimedKinds = [];
+  if (needsClaimKinds.length === 0) {
+    if (!json) {
+      console.log(`ℹ️  ${alreadyAliveKinds.join("、")} 已有有效凭证，跳过扫码，直接启动 bridge…`);
+    } else {
+      printScanEvent({ phase: "skip_pairing", relayUrl, runtimes: alreadyAliveKinds });
+    }
+  } else {
+    // ── 出码循环（S1 前半段 + S4）：本地生成高熵 code → 对 needsClaimKinds
+    // 逐个 host-claim(子进程,与 pair-all 同一隔离机制)→ 渲染二维码 → 轮询
+    // scan-claim；超时/过期则清二维码、重新出码，进程不退出。
+    const resolvedQrPath = qrPath || SCAN_QR_PNG_OUTPUT_PATH;
+    for (;;) {
+      const code = generateScanPairCode();
+      const argvTail = [
+        "pair", code,
+        "--relay", relayUrl,
+        "--pair-mode", "scan",
+        "--no-serve-relay",
+        ...(json ? ["--json"] : []),
+        ...(strictPlugin ? ["--strict-plugin"] : []),
+      ];
+      const roundResults = needsClaimKinds.map((kind) =>
+        spawnPairChildForRuntime({ argvTail, runtimeKind: kind, env: quietEnv }),
+      );
+      const roundClaimed = roundResults.filter((r) => r.ok).map((r) => r.kind);
+      const roundFailed = roundResults.filter((r) => !r.ok).map((r) => r.kind);
+      if (roundFailed.length > 0 && !json) {
+        console.warn(`⚠️  以下 runtime host-claim 失败，不会出现在本轮二维码中：${roundFailed.join("、")}`);
+      }
+      if (roundClaimed.length === 0) {
+        fail(`agentlink scan: host-claim failed for all candidate runtimes (${needsClaimKinds.join(", ")})`);
+      }
+
+      const deeplink = buildScanDeeplink({ code, relay: relayUrl });
+      const pngResult = await renderScanQrPng({ payload: deeplink, outputPath: resolvedQrPath });
+      if (json) {
+        printScanEvent({
+          phase: "waiting_for_scan",
+          code,
+          deeplink,
+          runtimes: roundClaimed,
+          qr_png_path: pngResult.ok ? pngResult.path : null,
+          qr_png_error: pngResult.ok ? null : pngResult.error,
+        });
+      } else {
+        console.log(`\n扫码配对（${roundClaimed.join("、")}）：用 App 扫描下方二维码` +
+          (pngResult.ok ? `（或打开 ${pngResult.path} 用图片扫码）` : "") + "\n");
+        renderQrToTerminal(deeplink);
+        console.log(`\n扫不到？把这段贴到浏览器/App 输入框也可以：${deeplink}\n`);
+      }
+
+      const claimedInTime = await waitForScanClaim({
+        relayUrl,
+        code,
+        representativeRuntimeKind: roundClaimed[0],
+        ttlMs: SCAN_CLAIM_TTL_MS,
+      });
+      clearQRImage(resolvedQrPath);
+      if (claimedInTime) {
+        claimedKinds = roundClaimed;
+        if (json) {
+          printScanEvent({ phase: "paired", relayUrl, runtimes: claimedKinds });
+        } else {
+          console.log(`✅ 配对成功（${claimedKinds.join("、")}）`);
+        }
+        break;
+      }
+      // 过期/超时（S4）：重新生成 code，重新 host-claim，刷新二维码，不退出。
+      if (!json) {
+        console.log("⏳ 配对码已过期，重新生成二维码…");
+      } else {
+        printScanEvent({ phase: "code_expired_retrying", runtimes: roundClaimed });
+      }
+    }
+  }
+
+  const finalKinds = [...alreadyAliveKinds, ...claimedKinds];
+
+  // ── --no-serve：只配对不起 worker（S5 命令签名之一）─────────────────────
+  if (noServe) {
+    if (json) {
+      printScanEvent({ phase: "done", serve: false, runtimes: finalKinds, relayUrl });
+    } else {
+      console.log("ℹ️  --no-serve：已完成配对，不启动 bridge worker。");
+    }
+    return;
+  }
+
+  // ── 起 worker；revoke 由既有共享路径清凭证 + exit（S6，不逆改）──────────
+  if (json) {
+    printScanEvent({
+      phase: "starting_worker",
+      runtimes: finalKinds,
+      relayUrl,
+      note: `on revoke this process/service clears credentials and exits; re-run \`${CLI_COMMAND_NAME} scan\` to re-pair`,
+    });
+  } else {
+    console.log(
+      `若之后在 App 端解绑（或凭证失效），worker 会自动清凭证并退出 —— 到时重跑 \`${CLI_COMMAND_NAME} scan\` 即可重新配对。`,
+    );
+  }
+  await startScanWorkers({ kinds: finalKinds, relayUrl, gateway, json });
+}
+
 async function runBridge({ json, relay, noRelay, gateway, runtime }) {
   const configPath = resolveOpenClawConfigPath();
   // 先容忍读（缺文件 → null）：runtimeKind 可能来自 ~/.agentlink state 的
@@ -8213,10 +8935,11 @@ async function runBridge({ json, relay, noRelay, gateway, runtime }) {
 }
 
 function runStatus({ json, runtime }) {
-  // claude / codex 不走 bin 的 openclaw/hermes 状态视图（normalizeRuntimeKind 会把
+  // ext-agent runtime 不走 bin 的 openclaw/hermes 状态视图（normalizeRuntimeKind 会把
   // 它们静默回退成 openclaw，导致展示错 runtime 的状态）。显式拦下并指向正确命令，
-  // 而非静默误导。
-  if (runtime === "claude" || runtime === "codex") {
+  // 而非静默误导。（opencode 更早已被 assertRuntimeBridgeSupportedOrFail 拦停，
+  // 这里保留登记表判据是双保险 —— 两道闸的判据不同、都不能漏。）
+  if (EXT_AGENT_RUNTIME_KINDS.includes(runtime)) {
     fail(t("status_ext_runtime_unsupported", { runtime, cli: CLI_COMMAND_NAME }));
   }
   const configPath = resolveOpenClawConfigPath();
@@ -8267,14 +8990,23 @@ function runStatus({ json, runtime }) {
         : null,
   };
 
-  // 四端汇总（不指定 -r 时也能一眼看全 openclaw/hermes/claude/codex 的配对 + 服务态），
+  // 多端汇总（不指定 -r 时也能一眼看全**可配对** runtime 的配对 + 服务态），
   // 对称 pair/reset 的「无 -r = 全部」。paired 走 HOME 隔离的凭证判定；service 态走
   // 实际服务管理器（展示用途，反映真实情况）。best-effort，不让汇总失败影响主输出。
-  status.runtimes = [RUNTIME_KIND_OPENCLAW, RUNTIME_KIND_HERMES, "claude", "codex"].map((k) => {
+  // 🔴 这里刻意用 **可配对集** 而不是已知枚举全集：本视图展示的是「配对态 + 服务态」，
+  // 而 enum-only runtime（deepagents）永远没有配对、也没有 service，
+  // 加进来只会长期多出恒为空的行 = 噪音。它们的"装没装"由 pair 的探测清单负责。
+  status.runtimes = PAIRABLE_RUNTIME_KINDS.map((k) => {
     let paired = false;
     try { paired = runtimeHasLocalState(k); } catch { /* ignore */ }
     let svc = { installed: false, running: false };
-    try { svc = getBridgeServiceStatus(k); } catch { /* ignore */ }
+    // 🔴 无 bridge 实现的 runtime（PAIR_ONLY，当前 = opencode）**不探服务态**：
+    // getBridgeServiceStatus → serviceNames() → normalizeRuntimeKind(x,"openclaw")
+    // 会把它别名到 openclaw 的 plist/unit，于是「openclaw 的 bridge 在跑」会被
+    // 展示成「opencode 的服务在跑」= 静默错配。它压根没有 service，恒 false 才是实话。
+    if (BRIDGE_CAPABLE_RUNTIME_KINDS.includes(k)) {
+      try { svc = getBridgeServiceStatus(k); } catch { /* ignore */ }
+    }
     return { kind: k, paired, serviceInstalled: !!svc.installed, serviceRunning: !!svc.running };
   });
 
@@ -8495,6 +9227,15 @@ async function forwardToAgent(command, options) {
 
 async function main() {
   const { command, options } = parseArgs(process.argv.slice(2));
+  // Must happen before any pairing/runtime dispatch: every downstream resolver
+  // reads AGENTLINK_HOME, and external-agent child processes inherit it.
+  if (options.agentlinkHome) {
+    process.env.AGENTLINK_HOME = options.agentlinkHome;
+  }
+  if (command === "capabilities") {
+    process.stdout.write(`${JSON.stringify(RUNTIME_CAPABILITIES)}\n`);
+    return;
+  }
   // `agentlink pair <code>` / `agentlink reset` 默认分别为本机已安装的 4 种
   // runtime 各 spawn 一次（不写死默认 openclaw —— 四端互不依赖：没装 openclaw
   // 的机器也能整机 reset）。`--runtime all` 保持为兼容别名。
@@ -8510,13 +9251,26 @@ async function main() {
   if (command !== "pair" && command !== "reset" && options.runtime === "all") {
     fail(`--runtime all 仅 \`${CLI_COMMAND_NAME} pair\` / \`${CLI_COMMAND_NAME} reset\` 命令支持`);
   }
-  // External Agents (Claude / Codex) shim ——
-  // 统一把 `agentlink pair <code> -r claude/codex`、`bridge -r claude/codex`、
-  // `reset -r claude/codex`（→ uninstall）转发到 agentlink-agent。避免 external
+  // 🔴 已知枚举 ∖ 可配对集（deepagents）：显式拦停，绝不放进实现路径。
+  // 判据与理由都在 assertRuntimeOperableOrFail 的文档注释里（单一事实源）。
+  assertRuntimeOperableOrFail(options.runtime);
+  // 🔴 可配对 ∖ 可桥接（opencode）：pair / reset 放行，其余"要把进程跑起来 / 展示
+  // 运行态"的命令显式拦停 —— 见 assertRuntimeBridgeSupportedOrFail 的文档注释。
+  // 放在分派之前统一做，避免每个 run* 各自记得判一次（漏一个就退化成静默回落）。
+  if (command === "bridge" || command === "service" || command === "reload" ||
+      command === "scan" || command === "status" || command === "setup" ||
+      command === "prepare") {
+    assertRuntimeBridgeSupportedOrFail(options.runtime, command);
+  }
+  // External Agents (Claude / Codex / OpenCode) shim ——
+  // 统一把 `agentlink pair <code> -r <ext>`、`bridge -r <ext>`、
+  // `reset -r <ext>`（→ uninstall）转发到 agentlink-agent。避免 external
   // 平行世界代码污染老 bin，也防止 reset 被 normalizeRuntimeKind 回退成 openclaw。
+  // 目标集用 EXT_AGENT_RUNTIME_KINDS（登记表），不再写死 claude/codex 字面量 ——
+  // opencode 的凭证同样存 ext-<rt>-last.json，必须走同一条转发路径。
   if ((command === "pair" || command === "bridge" || command === "service" ||
        command === "uninstall" || command === "reset") &&
-      (options.runtime === "claude" || options.runtime === "codex")) {
+      EXT_AGENT_RUNTIME_KINDS.includes(options.runtime)) {
     await forwardToAgent(command, options);
     return;
   }
@@ -8534,6 +9288,9 @@ async function main() {
     case "bridge":
       await runBridge(options);
       return;
+    case "scan":
+      await runScan(options);
+      return;
     case "service":
       await runService(options);
       return;