@xyagent/cli 1.0.0 → 1.1.0

package/bin/agentlink

@@ -62,18 +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";
+// 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";
 
-// Minimum Node.js 22+ — required for the built-in WebSocket client and the
-// runtime surface we rely on for bridge/service behavior across platforms.
+// 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);
   }
@@ -104,26 +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.
@@ -367,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})",
@@ -395,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──────────────── 解绑结果 ────────────────",
@@ -612,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})",
@@ -640,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 ────────────────",
@@ -781,12 +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]`,
@@ -851,6 +1010,9 @@ function parseArgs(argv) {
     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
@@ -937,6 +1099,14 @@ function parseArgs(argv) {
       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();
       if (!value || value.startsWith("--")) fail(t("err_missing_value", { flag: "--relay" }));
@@ -991,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") {
@@ -1216,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 清理，否则后台服务空转、卸不掉。
@@ -1225,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) {
@@ -1236,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 分叉。
@@ -1249,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() {
@@ -2690,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);
   }
@@ -3438,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}"`,
@@ -3445,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");
@@ -4252,6 +4491,7 @@ async function publishPairToRelay({
   ttlSeconds = 600,
 }) {
   const url = `${relayUrl}/v1/pair-sessions`;
+  const normalizedRuntime = normalizeRuntimeKind(runtimeKind, RUNTIME_KIND_OPENCLAW);
   const headers = {
     "content-type": "application/json",
     ...relayAuthHeaders(),
@@ -4261,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,
@@ -4274,6 +4514,10 @@ async function publishPairToRelay({
       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 } : {}),
     }),
   });
@@ -5496,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) {
@@ -5607,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。
@@ -5700,7 +5967,6 @@ async function handleUnifiedRunDispatch({
   // unify-scan-pairing 全量移除了上一代扫码硬件的命名空间归一 hack:扫码路径
   // 现在与 pair code 共用同一套真实 runtime binding(openclaw/hermes),不再有
   // App 以合成命名空间 agent 绑定的场景,agentId 直接原样使用。
-  const agentId = String(inner.agent_id || request.agentId || "main").trim() || "main";
   const headers = {
     "content-type": "application/json",
     "accept": "text/event-stream",
@@ -6396,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,
           });
@@ -6481,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 宽限延迟。
@@ -6518,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` 首行形如
@@ -6536,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 检查更新，
@@ -6569,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;
@@ -6595,15 +6879,26 @@ function detectInstalledRuntimes({ probeVersion = true } = {}) {
 // openclaw + hermes 的 pair state 都存在 ~/.agentlink/config.json：
 //   openclaw → relayGatewayId/relayGatewayToken
 //   hermes  → hermesRelayGatewayId/hermesRelayGatewayToken
-// claude/codex 存在 ~/.agentlink/ext-<runtime>-last.json。
+// 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 home = process.env.HOME || "";
-    if (!home) return null;
-    if (kind === "claude" || kind === "codex") {
-      const p = `${home}/.agentlink/ext-${kind}-last.json`;
+    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 || "";
@@ -6612,7 +6907,7 @@ function readLocalPairState(kind) {
       return { gw_id: gw, token: tok, relay_url: j?.relay_url || "" };
     }
     if (kind === "openclaw" || kind === "hermes") {
-      const p = `${home}/.agentlink/config.json`;
+      const p = path.join(agentlinkHome, "config.json");
       if (!fs.existsSync(p)) return null;
       let j;
       try { j = JSON.parse(fs.readFileSync(p, "utf8")); }
@@ -6633,17 +6928,20 @@ function readLocalPairState(kind) {
 // 删本机 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`;
+    // 与 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 = `${home}/.agentlink/config.json`;
+      const p = path.join(agentlinkHome, "config.json");
       if (!fs.existsSync(p)) return;
       let j;
       try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return; }
@@ -6739,7 +7037,8 @@ async function probeRelayBinding(state) {
 
 // 对应 runtime 的"重置后重新配对"命令提示。
 function resetHintFor(kind, code) {
-  if (kind === "claude" || kind === "codex") {
+  // 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 子命令
@@ -6759,9 +7058,12 @@ function spawnPairChildForRuntime({ argvTail, runtimeKind, env }) {
 
 // `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"));
@@ -6783,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 子配对命令之前,先把本机装好的
@@ -6852,7 +7168,10 @@ async function runPairAll(options) {
       continue;
     }
     if (a === "--allow-rebind") {
-      continue; // 后面会显式加一次，去重
+      // 刻意**不**转发给子进程：pair-all 的语义是「把没配对的都配上」，已配对的
+      // 由下面的 probeRelayBinding 判定后跳过，不做覆盖兜底（见下一段注释）。
+      // ⚠️ 注释曾写「后面会显式加一次」——那是早期实现，现已不再回注；别照着补回去。
+      continue;
     }
     forwardedArgv.push(a);
   }
@@ -6872,7 +7191,7 @@ async function runPairAll(options) {
   // 已提到顶层（供 runScan 复用，见其上方注释），行为不变。
 
   const summary = [];
-  for (const kind of installedKinds) {
+  for (const kind of pairTargetKinds) {
     const state = readLocalPairState(kind);
     if (state) {
       const probe = await probeRelayBinding(state);
@@ -6932,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);
@@ -6951,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("");
 
@@ -6986,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))
@@ -7000,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 }));
@@ -7012,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) {
@@ -8144,8 +8483,10 @@ async function startScanWorkers({ kinds, relayUrl, gateway, json }) {
 }
 
 async function runScan({ json, relay, noRelay, gateway, qrPath, noServe, strictPlugin, runtime }) {
-  // S2b（显式 -r claude/codex）：不出码、不联系 relay，直接提示 + 非零退出。
-  if (runtime === "claude" || runtime === "codex") {
+  // 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 });
@@ -8171,14 +8512,19 @@ async function runScan({ json, relay, noRelay, gateway, qrPath, noServe, strictP
   // ── 探测本机已装 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 && (d.kind === "claude" || d.kind === "codex"))
+    .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/all），claude/codex 已在上面提前返回。
+    // （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`);
     }
@@ -8187,7 +8533,11 @@ async function runScan({ json, relay, noRelay, gateway, qrPath, noServe, strictP
     candidateKinds = SCAN_CAPABLE_RUNTIME_KINDS.filter((k) => installedKinds.has(k));
   }
   if (candidateKinds.length === 0) {
-    fail(t("pair_all_no_runtimes"));
+    // 🔴 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) {
@@ -8585,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();
@@ -8639,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 };
   });
 
@@ -8867,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` 保持为兼容别名。
@@ -8882,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;
   }