agent-hub-runner 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+<!-- @意图#R666(2026-10-29): 改成不用全局安装的 npx 一条命令（码@地址）、Mac 开机自启、stop / uninstall、常见报错 -->
+<!-- @意图#R664(2026-10-29): npm 包 agent-hub-runner 的说明（随包发布）：给客户看的安装、配对、再连、查看、断开、卸载和安全提示 -->
+# agent-hub-runner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+agent-hub 的电脑运行器。装在你自己的电脑上，配对之后，你的 bot 就能在你给它选的文件夹里读、写、改文件，跑命令（跑命令每次都要你在网页上点批准）。
+
+- 没有第三方依赖，只用 Node 自带的功能。不用先装：用 `npx` 直接运行。
+- Mac 上可以设成开机自动连上（在后台跑，不用开终端）；不设的话在终端前台跑，按 Ctrl-C 断开。
+
+## 需要
+
+- **Node 22 或更新**（终端里运行 `node -v` 看版本）。还没装：去 [nodejs.org](https://nodejs.org) 下载 LTS 版（Mac 选 .pkg 安装包），或者 `brew install node`。
+- **macOS**：给 bot 选目录时会在 Mac 上弹出系统的「选文件夹」窗口；开机自启也只支持 Mac。别的系统能连上，但选不了目录。
+- bot 跑命令时用 `bash`（macOS、Linux 自带）。
+
+## 第一次连接
+
+1. 在网页上打开某个 bot 的私聊，点输入框下面「我的电脑」那一行，右侧会打开抽屉，里面有一条命令。
+2. 复制那条命令到终端运行，形如：
+
+   ```bash
+   npx -y agent-hub-runner@latest pair <配对码>@你的服务器地址
+   ```
+
+   配对码 5 分钟有效、只能用一次；过期了在抽屉里点「换一个码」。配对成功后直接连上。
+3. Mac 上会问「开机自动连上？(Y/n)」：回车就是「是」，以后开机自己连上，终端可以关；选「否」的话终端窗口别关。
+4. 抽屉里第 2 步会自动打勾。第 3 步点「选择目录…」，在 Mac 弹出的窗口里选这个 bot 能用的文件夹。每个 bot 各选各的。
+
+`@` 后面的地址默认是 https；`localhost`、`127.x` 默认 http；也可以写全 `码@http://…`。老写法 `pair <配对码> --server <地址>` 照样能用。只配对不连：加 `--no-start`。
+
+## 以后再连
+
+开了开机自启的不用管。没开的，重启电脑或关了终端之后运行：
+
+```bash
+npx -y agent-hub-runner@latest start
+```
+
+服务器地址和令牌配对时已经存下了，不用再给。后台已经连着时再 `start` 会说「已经在后台连着，不用再开」。
+
+## 其他命令
+
+```bash
+npx -y agent-hub-runner@latest status          # 版本、连的哪个服务器、在不在跑、开机自启、每个 bot 的目录
+npx -y agent-hub-runner@latest autostart on    # 开机自动连上（Mac）；升级到新版也用这条
+npx -y agent-hub-runner@latest autostart off   # 关掉开机自启
+npx -y agent-hub-runner@latest autostart status
+npx -y agent-hub-runner@latest stop            # 停掉在跑的运行器（开机自启的下次开机还会起）
+npx -y agent-hub-runner@latest uninstall       # 关掉开机自启、删掉复制的程序；会问要不要删配置
+```
+
+开机自启时，程序复制到 `~/.agent-runner/bin/<版本>/`，日志在 `~/.agent-runner/logs/runner.log`（超过 5MB 自动清空）。网页上提示「有新版本」时，按提示运行那一条升级命令。
+
+## 配置文件
+
+- 默认在 `~/.agent-runner/config.json`（权限 600），里面有服务器地址、设备 id、长期令牌、电脑名和每个 bot 的目录。别发给别人。
+- 想放别处：设环境变量 `AGENT_RUNNER_CONFIG=/某个路径/config.json`。
+- 文件坏了：删掉它，回网页拿新配对码重新配对。
+
+## 常见问题
+
+- `command not found: npx`：还没装 Node。
+- 「需要 Node 22 或更新」（上面还有几行英文 `npm warn EBADENGINE`）：Node 太旧，装新的 LTS 版后关掉终端重开。
+- 「权限不够」/ `EACCES`：别用 sudo；运行 `sudo chown -R "$(whoami)" ~/.npm ~/.agent-runner` 修好再试。
+- 「找不到服务器」「连不上服务器」「超时」：检查网络；命令要整条原样复制。
+- 「配对码过期了 / 已经用过了 / 已经作废了」：网页上点「换一个码」再运行新命令。
+- 「这个账号已经连着一台电脑了」：一个账号同时只能连一台，先在网页抽屉「连着的电脑」里点「断开」。
+
+## 断开、卸载
+
+- 在网页抽屉「连着的电脑」里点「断开」：令牌立刻作废，再连要重新配对；开机自启也会自己关掉。
+- 卸载：`npx -y agent-hub-runner@latest uninstall`（加 `--purge` 连配置一起删，不再问）。
+
+## 安全提示
+
+- 别把放着密钥、令牌的文件夹授权出去：bot 在授权文件夹里读、写、改文件不用你批准。
+- 跑命令前网页上会弹批准卡片，看清命令再点「允许一次」；命令本身能碰到文件夹以外的东西（没有沙箱）。

package/autostart.mjs

@@ -0,0 +1,188 @@
+// @意图#R666(2026-10-29): Mac 开机自启（king 同意 R666 二丙）：配对后选「是」就写一个 launchd 的 LaunchAgent，之后登录 Mac 自动连上，不用开终端。
+// - 不靠 npx 缓存（路径不稳定、会被清）：把运行器自己（零依赖的几份源码 + package.json）复制到 ~/.agent-runner/bin/<版本>/，current 软链指向它；
+//   plist 里跑 [node 绝对路径（优先 /opt/homebrew/bin/node、/usr/local/bin/node 这种稳定软链）, ~/.agent-runner/bin/current/runner.mjs, start]，开机不联网也能起来，
+//   也不会每次登录自动拉 npm 上的新代码；升级 = 重新跑一次 npx -y agent-hub-runner@latest autostart on。
+// - Label com.agenthub.runner；用的不是默认配置（AGENT_RUNNER_CONFIG 指别处）时加配置路径 sha256 前 8 位后缀，一份配置一个后台任务；
+//   环境变量写明 AGENT_RUNNER_CONFIG 绝对路径、AGENT_RUNNER_LAUNCHD=1（运行器据此知道自己在后台），PATH 用开启时终端里的（bot 跑的命令要找得到 git、npm 这些）。
+// - RunAtLoad；KeepAlive 只在非 0 退出时拉起（被网页断开、令牌失效、被顶掉都是 0 退出，不会被反复拉起）；ThrottleInterval 10 秒；
+//   日志 ~/.agent-runner/logs/runner.log（非默认配置 runner-<后缀>.log），每次启动超过 5MB 就清空。
+// - launchctl 调用可以换成假的（测试用：参数里传，或环境变量 AGENT_RUNNER_LAUNCHCTL 指一个假程序），目录可以用 AGENT_RUNNER_HOME、AGENT_RUNNER_LAUNCH_AGENTS 换到临时目录。
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, truncateSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const LABEL = "com.agenthub.runner";
+export const LOG_MAX_BYTES = 5 * 1024 * 1024;
+export const THROTTLE_S = 10;
+/** 复制到 ~/.agent-runner/bin/<版本>/ 的文件（package.json 用来读版本号） */
+export const COPY_FILES = ["runner.mjs", "ops.mjs", "edit.mjs", "autostart.mjs", "package.json"];
+/** 优先用的稳定 node 路径（Homebrew 升级 node 后这两个软链还在；nvm 的带版本号路径卸了就没了） */
+export const STABLE_NODES = ["/opt/homebrew/bin/node", "/usr/local/bin/node"];
+export const ONLY_MAC = "开机自启目前只支持 Mac";
+
+const real = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+
+/** 运行器自己的目录（配置、副本、日志都在这下面）；测试可用 AGENT_RUNNER_HOME 换掉 */
+export const runnerHome = (env = process.env) => env.AGENT_RUNNER_HOME || path.join(os.homedir(), ".agent-runner");
+export const defaultConfigFile = (env = process.env) => path.join(runnerHome(env), "config.json");
+export const launchAgentsDir = (env = process.env) => env.AGENT_RUNNER_LAUNCH_AGENTS || path.join(os.homedir(), "Library", "LaunchAgents");
+
+/** 默认配置没有后缀；别的配置用绝对路径 sha256 前 8 位 */
+export function configTag(configFile, env = process.env) {
+  const abs = path.resolve(configFile);
+  if (abs === path.resolve(defaultConfigFile(env))) return "";
+  return createHash("sha256").update(abs).digest("hex").slice(0, 8);
+}
+export const labelFor = (configFile, env = process.env) => { const t = configTag(configFile, env); return t ? `${LABEL}.${t}` : LABEL; };
+export const plistPathFor = (configFile, env = process.env) => path.join(launchAgentsDir(env), `${labelFor(configFile, env)}.plist`);
+export const logFileFor = (configFile, env = process.env) => {
+  const t = configTag(configFile, env);
+  return path.join(runnerHome(env), "logs", t ? `runner-${t}.log` : "runner.log");
+};
+
+/** node 的绝对路径：稳定软链和当前 node 是同一个文件就用软链，否则用当前的 */
+export function pickNode(execPath = process.execPath, candidates = STABLE_NODES) {
+  const me = real(execPath);
+  for (const c of candidates) if (existsSync(c) && real(c) === me) return c;
+  return execPath;
+}
+
+const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** 生成 LaunchAgent 的 plist（XML） */
+export function plistXml({ label, args, env, log }) {
+  const envXml = Object.entries(env).map(([k, v]) => `      <key>${esc(k)}</key>\n      <string>${esc(v)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${esc(label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${args.map((a) => `      <string>${esc(a)}</string>`).join("\n")}
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+${envXml}
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>${THROTTLE_S}</integer>
+    <key>StandardOutPath</key>
+    <string>${esc(log)}</string>
+    <key>StandardErrorPath</key>
+    <string>${esc(log)}</string>
+  </dict>
+</plist>
+`;
+}
+
+/** 把运行器复制到 <home>/bin/<版本>/，current 软链指过去（先建临时链再改名，换的那一下不会断）。返回 current/runner.mjs 的路径。 */
+export function installCopy({ srcDir, version, env = process.env }) {
+  const binRoot = path.join(runnerHome(env), "bin");
+  const dest = path.join(binRoot, version);
+  mkdirSync(dest, { recursive: true, mode: 0o700 });
+  if (real(srcDir) !== real(dest)) {
+    for (const f of COPY_FILES) {
+      const from = path.join(srcDir, f);
+      if (existsSync(from)) copyFileSync(from, path.join(dest, f));
+    }
+  }
+  const cur = path.join(binRoot, "current");
+  const tmp = path.join(binRoot, `.current-${process.pid}`);
+  rmSync(tmp, { force: true });
+  symlinkSync(version, tmp);
+  renameSync(tmp, cur);
+  return path.join(cur, "runner.mjs");
+}
+
+/** 默认的 launchctl：返回 { code, stdout, stderr }，不抛错。AGENT_RUNNER_LAUNCHCTL 可换成别的程序（测试用假的，不真加载） */
+export function runLaunchctl(args, env = process.env) {
+  return new Promise((resolve) => {
+    execFile(env.AGENT_RUNNER_LAUNCHCTL || "launchctl", args, { encoding: "utf8" }, (err, stdout, stderr) => resolve({ code: err ? (typeof err.code === "number" ? err.code : 1) : 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") }));
+  });
+}
+const uid = () => (typeof process.getuid === "function" ? process.getuid() : 0);
+
+/**
+ * 开启开机自启：复制自己、写 plist、（先卸掉旧的）再加载。加载后 launchd 马上起一个后台运行器（RunAtLoad）。
+ * 返回 { label, plist, script, node, log }。
+ */
+export async function autostartOn({ configFile, version, srcDir, execPath = process.execPath, env = process.env, launchctl, platform = process.platform }) {
+  launchctl ??= (a) => runLaunchctl(a, env);
+  if (platform !== "darwin") throw new Error(ONLY_MAC);
+  const cfg = path.resolve(configFile);
+  if (!existsSync(cfg)) throw new Error(`还没配对：没有 ${cfg}，配对成功后才能设开机自启`);
+  const script = installCopy({ srcDir, version, env });
+  const node = pickNode(execPath);
+  const label = labelFor(cfg, env);
+  const log = logFileFor(cfg, env);
+  mkdirSync(path.dirname(log), { recursive: true, mode: 0o700 });
+  const vars = { AGENT_RUNNER_CONFIG: cfg, AGENT_RUNNER_LAUNCHD: "1", PATH: env.PATH || "/usr/bin:/bin:/usr/sbin:/sbin", LANG: env.LANG || "en_US.UTF-8" };
+  if (env.AGENT_RUNNER_HOME) vars.AGENT_RUNNER_HOME = env.AGENT_RUNNER_HOME;
+  const plist = plistPathFor(cfg, env);
+  mkdirSync(path.dirname(plist), { recursive: true });
+  writeFileSync(plist, plistXml({ label, args: [node, script, "start"], env: vars, log }), { mode: 0o644 });
+  await launchctl(["bootout", `gui/${uid()}/${label}`]); // 以前加载过（升级）：先卸掉，没有也不要紧
+  const r = await launchctl(["bootstrap", `gui/${uid()}`, plist]);
+  if (r.code !== 0) throw new Error(`开机自启没设成：launchctl bootstrap 失败（${(r.stderr || r.stdout).trim() || r.code}）`);
+  return { label, plist, script, node, log };
+}
+
+/** 关掉开机自启：卸载任务（后台那个会被停掉）、删 plist。返回 { wasOn }（原来有没有 plist）。 */
+export async function autostartOff({ configFile, env = process.env, launchctl }) {
+  launchctl ??= (a) => runLaunchctl(a, env);
+  const cfg = path.resolve(configFile);
+  const plist = plistPathFor(cfg, env);
+  const wasOn = existsSync(plist);
+  rmSync(plist, { force: true });
+  await launchctl(["bootout", `gui/${uid()}/${labelFor(cfg, env)}`]);
+  return { wasOn };
+}
+
+/** 开机自启现在的样子：装没装（有没有 plist）、加载没有、后台进程号；plist 里的 node / 脚本找不到就写进 problems */
+export async function autostartStatus({ configFile, env = process.env, launchctl, platform = process.platform }) {
+  launchctl ??= (a) => runLaunchctl(a, env);
+  const cfg = path.resolve(configFile);
+  const label = labelFor(cfg, env);
+  const plist = plistPathFor(cfg, env);
+  const out = { supported: platform === "darwin", installed: existsSync(plist), loaded: false, pid: null, label, plist, log: logFileFor(cfg, env), problems: [] };
+  if (!out.supported) return out;
+  if (out.installed) {
+    const xml = readFileSync(plist, "utf8");
+    const args = [...(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml)?.[1] ?? "").matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1].replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&amp;/g, "&"));
+    if (args[0] && !existsSync(args[0])) out.problems.push(`找不到 node：${args[0]}（换过 Node 的装法？重新运行 autostart on）`);
+    if (args[1] && !existsSync(args[1])) out.problems.push(`找不到运行器副本：${args[1]}（重新运行 autostart on）`);
+  }
+  const r = await launchctl(["print", `gui/${uid()}/${label}`]);
+  if (r.code === 0) {
+    out.loaded = true;
+    const m = /\bpid = (\d+)/.exec(r.stdout);
+    if (m) out.pid = Number(m[1]);
+  }
+  return out;
+}
+
+/** 还有没有别的配置开着自启（uninstall 时决定删不删共用的 bin 副本） */
+export function otherAutostarts(configFile, env = process.env) {
+  const mine = `${labelFor(configFile, env)}.plist`;
+  try { return readdirSync(launchAgentsDir(env)).filter((f) => f.startsWith(LABEL) && f.endsWith(".plist") && f !== mine); } catch { return []; }
+}
+
+/** 日志超过 max 字节就清空（launchd 用追加方式打开，清空后接着往后写不会乱）。清了返回 true。 */
+export function truncateLogIfBig(file, max = LOG_MAX_BYTES) {
+  try {
+    if (statSync(file).size <= max) return false;
+    truncateSync(file, 0);
+    return true;
+  } catch { return false; }
+}

package/bin/agent-hub-runner.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// @意图#R664(2026-10-29): npm 包 agent-hub-runner 的命令入口（package.json 的 bin）：客户电脑 npm i -g agent-hub-runner 后直接跑
+// agent-hub-runner pair <配对码> --start --server <地址> / start / status；逻辑全在 ../runner.mjs，这里只把参数和命令名交过去。
+// @意图#R666(2026-10-29): 主要用法改成 npx -y agent-hub-runner@latest pair 码@地址；最先查 Node 版本（在加载别的代码之前，老 Node 上也只打一句大白话，
+// 说明上面 npm 的英文 EBADENGINE 警告不用管）；出错用 explainError 打大白话（权限不够单独说）
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 22 || typeof WebSocket === "undefined") {
+  console.error(`需要 Node 22 或更新，你这台电脑上是 ${process.versions.node}。\n（上面如果有几行英文 npm warn EBADENGINE，说的就是这个，不用管它。）\n去 https://nodejs.org 下载 LTS 版装上（Mac 选 .pkg 安装包），装好后关掉终端重新打开，再运行同一条命令。`);
+  process.exit(1);
+}
+const { main, progName, explainError } = await import("../runner.mjs");
+main(process.argv.slice(2), progName()).catch((e) => { console.error(explainError(e)); process.exit(1); });

package/edit.mjs

@@ -0,0 +1,143 @@
+// @意图#R636(2026-10-27): 运行器零依赖，edit 的匹配规则照搬 pi 1.1.0 的 edit-diff（先精确、再按引号/破折号/行尾空白放宽），
+// 这样 bot 在你电脑上改文件和 pi 原版的 edit 行为一样；路径判断在 ops.mjs 里做，这里只管文字替换。
+export function detectLineEnding(content) {
+  const crlfIdx = content.indexOf("\r\n");
+  const lfIdx = content.indexOf("\n");
+  if (lfIdx === -1 || crlfIdx === -1) return "\n";
+  return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+export const normalizeToLF = (text) => text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+export const restoreLineEndings = (text, ending) => (ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text);
+
+export function normalizeForFuzzyMatch(text) {
+  return text.normalize("NFKC")
+    .split("\n").map((line) => line.trimEnd()).join("\n")
+    .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+    .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+    .replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+    .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
+}
+const splitLinesWithEndings = (content) => content.match(/[^\n]*\n|[^\n]+/g) ?? [];
+function getLineSpans(content) {
+  let offset = 0;
+  return splitLinesWithEndings(content).map((line) => {
+    const span = { start: offset, end: offset + line.length };
+    offset = span.end;
+    return span;
+  });
+}
+function getReplacementLineRange(lines, r) {
+  const s = r.matchIndex;
+  const e = r.matchIndex + r.matchLength;
+  let startLine = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (s >= lines[i].start && s < lines[i].end) { startLine = i; break; }
+  }
+  if (startLine === -1) throw new Error("Replacement range is outside the base content.");
+  let endLine = startLine;
+  while (endLine < lines.length && lines[endLine].end < e) endLine++;
+  if (endLine >= lines.length) throw new Error("Replacement range is outside the base content.");
+  return { startLine, endLine: endLine + 1 };
+}
+function applyReplacements(content, replacements, offset = 0) {
+  let result = content;
+  for (let i = replacements.length - 1; i >= 0; i--) {
+    const r = replacements[i];
+    const at = r.matchIndex - offset;
+    result = result.substring(0, at) + r.newText + result.substring(at + r.matchLength);
+  }
+  return result;
+}
+function applyReplacementsPreservingUnchangedLines(originalContent, baseContent, replacements) {
+  const originalLines = splitLinesWithEndings(originalContent);
+  const baseLines = getLineSpans(baseContent);
+  if (originalLines.length !== baseLines.length) {
+    throw new Error("Cannot preserve unchanged lines because the base content has a different line count.");
+  }
+  const groups = [];
+  for (const r of [...replacements].sort((a, b) => a.matchIndex - b.matchIndex)) {
+    const range = getReplacementLineRange(baseLines, r);
+    const cur = groups[groups.length - 1];
+    if (cur && range.startLine < cur.endLine) {
+      cur.endLine = Math.max(cur.endLine, range.endLine);
+      cur.replacements.push(r);
+      continue;
+    }
+    groups.push({ ...range, replacements: [r] });
+  }
+  let idx = 0;
+  let result = "";
+  for (const g of groups) {
+    result += originalLines.slice(idx, g.startLine).join("");
+    const gs = baseLines[g.startLine].start;
+    const ge = baseLines[g.endLine - 1].end;
+    result += applyReplacements(baseContent.slice(gs, ge), g.replacements, gs);
+    idx = g.endLine;
+  }
+  return result + originalLines.slice(idx).join("");
+}
+function fuzzyFindText(content, oldText) {
+  const exact = content.indexOf(oldText);
+  if (exact !== -1) return { found: true, index: exact, matchLength: oldText.length, usedFuzzyMatch: false };
+  const fc = normalizeForFuzzyMatch(content);
+  const fo = normalizeForFuzzyMatch(oldText);
+  const fi = fc.indexOf(fo);
+  if (fi === -1) return { found: false, index: -1, matchLength: 0, usedFuzzyMatch: false };
+  return { found: true, index: fi, matchLength: fo.length, usedFuzzyMatch: true };
+}
+const countOccurrences = (content, oldText) => normalizeForFuzzyMatch(content).split(normalizeForFuzzyMatch(oldText)).length - 1;
+
+export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
+  const ne = edits.map((e) => ({ oldText: normalizeToLF(String(e.oldText)), newText: normalizeToLF(String(e.newText)) }));
+  const n = ne.length;
+  for (let i = 0; i < n; i++) {
+    if (ne[i].oldText.length === 0) {
+      throw new Error(n === 1 ? `oldText must not be empty in ${path}.` : `edits[${i}].oldText must not be empty in ${path}.`);
+    }
+  }
+  const usedFuzzy = ne.map((e) => fuzzyFindText(normalizedContent, e.oldText)).some((m) => m.usedFuzzyMatch);
+  const base = usedFuzzy ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;
+  const matched = [];
+  for (let i = 0; i < n; i++) {
+    const m = fuzzyFindText(base, ne[i].oldText);
+    if (!m.found) {
+      throw new Error(n === 1
+        ? `Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`
+        : `Could not find edits[${i}] in ${path}. The oldText must match exactly including all whitespace and newlines.`);
+    }
+    const occ = countOccurrences(base, ne[i].oldText);
+    if (occ > 1) {
+      throw new Error(n === 1
+        ? `Found ${occ} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`
+        : `Found ${occ} occurrences of edits[${i}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`);
+    }
+    matched.push({ editIndex: i, matchIndex: m.index, matchLength: m.matchLength, newText: ne[i].newText });
+  }
+  matched.sort((a, b) => a.matchIndex - b.matchIndex);
+  for (let i = 1; i < matched.length; i++) {
+    const p = matched[i - 1];
+    const c = matched[i];
+    if (p.matchIndex + p.matchLength > c.matchIndex) {
+      throw new Error(`edits[${p.editIndex}] and edits[${c.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`);
+    }
+  }
+  const newContent = usedFuzzy
+    ? applyReplacementsPreservingUnchangedLines(normalizedContent, base, matched)
+    : applyReplacements(base, matched);
+  if (newContent === normalizedContent) {
+    throw new Error(n === 1
+      ? `No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`
+      : `No changes made to ${path}. The replacements produced identical content.`);
+  }
+  return { baseContent: normalizedContent, newContent };
+}
+
+/** 整个文件的改法：去 BOM、统一换行再匹配，写回时恢复原来的换行和 BOM（和 pi 原版一样）。 */
+// @意图#R636(2026-10-27): 和 pi edit 同样的 BOM、换行处理
+export function editText(raw, edits, path) {
+  const bom = raw.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const content = bom ? raw.slice(1) : raw;
+  const ending = detectLineEnding(content);
+  const { newContent } = applyEditsToNormalizedContent(normalizeToLF(content), edits, path);
+  return bom + restoreLineEndings(newContent, ending);
+}

package/ops.mjs

@@ -0,0 +1,152 @@
+// @意图#R636(2026-10-27): 运行器在你电脑上真正执行 read / write / edit / bash。路径只在这里判断（S6 结论：服务器不解析用户电脑的路径）：
+// 先按授权目录换算成真实路径（解开符号链接，包括指向不存在目标的符号链接），不在授权目录里的一律拒绝；bash 的工作目录就是授权目录。
+// 第一轮没有沙箱（king 定的范围）：bash 里的命令本身能碰到目录外的东西，只能靠你看清批准卡片再点。
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { editText } from "./edit.mjs";
+
+export const MAX_READ_BYTES = 20 * 1024 * 1024;
+/** bash 没给 timeout 时的默认上限（秒），到点杀掉整个进程组。 */
+export const DEFAULT_BASH_TIMEOUT_S = 300;
+
+/** 把 bot 给的路径按授权目录换成绝对路径（~ 指你的家目录，相对路径相对授权目录；去掉开头的 @，和 pi 一样）。 */
+// @意图#R636(2026-10-27): 相对路径一律相对授权目录
+export function expandPath(p, root) {
+  let s = String(p).replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ");
+  if (s.startsWith("@")) s = s.slice(1);
+  if (s === "~") s = os.homedir();
+  else if (s.startsWith("~/")) s = path.join(os.homedir(), s.slice(2));
+  return path.resolve(root, s);
+}
+
+/** 真实路径：存在的直接 realpath；不存在的找到最近的已存在上级再拼回去；悬空的符号链接按它指向的地方算。 */
+// @意图#R636(2026-10-27): 挡住 ../、越界符号链接、悬空符号链接（写的时候会顺着链接写到目录外）
+export async function realOf(abs, depth = 0) {
+  if (depth > 40) throw new Error("符号链接太多层");
+  try {
+    return await fs.realpath(abs);
+  } catch (e) {
+    if (e?.code !== "ENOENT") throw e;
+    let st;
+    try { st = await fs.lstat(abs); } catch { st = undefined; }
+    if (st?.isSymbolicLink()) {
+      const target = path.resolve(path.dirname(abs), await fs.readlink(abs));
+      return realOf(target, depth + 1);
+    }
+    const parent = path.dirname(abs);
+    if (parent === abs) throw e;
+    return path.join(await realOf(parent, depth + 1), path.basename(abs));
+  }
+}
+
+export const inside = (real, root) => real === root || real.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+
+/** 换算并检查：在授权目录里返回真实路径，不在就抛「目录外路径已拒绝」。 */
+// @意图#R636(2026-10-27): 授权目录外的路径一律拒绝
+export async function resolveInside(p, root) {
+  if (typeof p !== "string" || !p.trim()) throw new Error("路径是空的");
+  let real;
+  try { real = await realOf(expandPath(p, root)); } catch (e) { throw new Error(`无法解析路径：${p}（${e?.code ?? e?.message ?? e}）`); }
+  if (!inside(real, root)) throw new Error(`目录外路径已拒绝：${p}（授权目录是 ${root}）`);
+  return real;
+}
+
+function imageMime(buf) {
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "image/jpeg";
+  if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
+  const head = buf.subarray(0, 6).toString("latin1");
+  if (head === "GIF87a" || head === "GIF89a") return "image/gif";
+  if (buf.length >= 12 && buf.subarray(0, 4).toString("latin1") === "RIFF" && buf.subarray(8, 12).toString("latin1") === "WEBP") return "image/webp";
+  if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d) return "image/bmp";
+  return null;
+}
+
+/** read：返回整份文字（截断由服务器照 pi 原版做）或图片。 */
+// @意图#R636(2026-10-27): 读文件不用批准，但同样只能读授权目录里的
+export async function opRead(args, root) {
+  const real = await resolveInside(args.path, root);
+  const st = await fs.stat(real);
+  if (st.isDirectory()) throw new Error(`${args.path} 是目录，不是文件（看目录里有什么用 bash 的 ls）`);
+  if (st.size > MAX_READ_BYTES) throw new Error(`${args.path} 太大（${st.size} 字节），超过 ${MAX_READ_BYTES} 字节；用 bash 的 head/sed 看一部分`);
+  const buf = await fs.readFile(real);
+  const mime = imageMime(buf);
+  if (mime) return { kind: "image", mime, data: buf.toString("base64") };
+  return { kind: "text", text: buf.toString("utf8") };
+}
+
+/** write：建好上级目录再整份写入。 */
+// @意图#R636(2026-10-27): 写文件（已经过批准，只执行这一次）
+export async function opWrite(args, root) {
+  if (typeof args.content !== "string") throw new Error("content 必须是文字");
+  const real = await resolveInside(args.path, root);
+  await fs.mkdir(path.dirname(real), { recursive: true });
+  await fs.writeFile(real, args.content, "utf8");
+  return { bytes: Buffer.byteLength(args.content, "utf8") };
+}
+
+/** edit：和 pi 原版同样的精确替换。 */
+// @意图#R636(2026-10-27): 改文件（已经过批准，只执行这一次）
+export async function opEdit(args, root) {
+  if (!Array.isArray(args.edits) || args.edits.length === 0) throw new Error("Edit tool input is invalid. edits must contain at least one replacement.");
+  const real = await resolveInside(args.path, root);
+  let raw;
+  try { raw = await fs.readFile(real, "utf8"); } catch (e) { throw new Error(`Could not edit file: ${args.path}. Error code: ${e?.code ?? "unknown"}.`); }
+  const next = editText(raw, args.edits, args.path);
+  await fs.writeFile(real, next, "utf8");
+  return { replaced: args.edits.length };
+}
+
+function killGroup(child) {
+  if (!child.pid) return;
+  try { process.kill(-child.pid, "SIGKILL"); } catch { /* 进程组已经没了 */ }
+  try { child.kill("SIGKILL"); } catch { /* ignore */ }
+}
+
+/**
+ * bash：在授权目录里用你终端的环境变量跑（服务器的环境变量不下发）。输出边跑边交给 onData；
+ * 超时或 signal 中止时杀掉整个进程组。返回 { exitCode, timedOut, aborted }。
+ */
+// @意图#R636(2026-10-27): 跑命令（已经过批准，只执行这一次），有超时，超时杀进程
+export function opBash(args, root, { onData, signal } = {}) {
+  const command = args.command;
+  if (typeof command !== "string" || !command.trim()) return Promise.reject(new Error("command 是空的"));
+  let timeoutS = DEFAULT_BASH_TIMEOUT_S;
+  if (args.timeout !== undefined && args.timeout !== null) {
+    const t = Number(args.timeout);
+    if (!Number.isFinite(t) || t <= 0) return Promise.reject(new Error("Invalid timeout: must be a finite number of seconds"));
+    timeoutS = t;
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn("bash", ["-c", command], { cwd: root, detached: true, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    let timedOut = false;
+    let aborted = false;
+    const timer = setTimeout(() => { timedOut = true; killGroup(child); }, timeoutS * 1000);
+    const onAbort = () => { aborted = true; killGroup(child); };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+    child.stdout.on("data", (d) => onData?.(d));
+    child.stderr.on("data", (d) => onData?.(d));
+    const done = () => { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); };
+    child.on("error", (e) => { done(); reject(e); });
+    child.on("close", (code, sig) => {
+      done();
+      const exitCode = code ?? (sig ? 128 + (os.constants.signals[sig] ?? 0) : 1);
+      resolve({ exitCode, timedOut, aborted, timeout: timeoutS });
+    });
+  });
+}
+
+/** 按 op 分派；未知 op 拒绝。 */
+// @意图#R636(2026-10-27): 协议里只有这四种工具调用
+export function runOp(op, args, root, extra) {
+  const a = args && typeof args === "object" ? args : {};
+  if (op === "read") return opRead(a, root);
+  if (op === "write") return opWrite(a, root);
+  if (op === "edit") return opEdit(a, root);
+  if (op === "bash") return opBash(a, root, extra);
+  return Promise.reject(new Error(`未知操作 ${op}`));
+}

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "agent-hub-runner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "agent-hub 的电脑运行器：配对后让你的 bot 在这台电脑上读写授权目录里的文件、跑命令（跑命令要你在网页上批准）",
+  "type": "module",
+  "bin": { "agent-hub-runner": "bin/agent-hub-runner.mjs" },
+  "files": ["runner.mjs", "ops.mjs", "edit.mjs", "autostart.mjs", "bin/agent-hub-runner.mjs", "README.md"],
+  "engines": { "node": ">=22" },
+  "scripts": { "test": "node --test" }
+}

package/runner.mjs

@@ -0,0 +1,622 @@
+#!/usr/bin/env node
+// @意图#R636(2026-10-27): 你电脑上的运行器（第一轮最小可用，king 定甲）：零第三方依赖，只用 Node 22+ 自带的 WebSocket、fetch、进程和文件 API。
+// 用法：
+//   npx -y agent-hub-runner@latest pair <配对码>@<服务器地址>     （R666：抽屉里就这一条；配完直接连上）
+//   node agent-hub/runner/runner.mjs pair <配对码> [--no-start] [--server http://127.0.0.1:3220]
+//   node agent-hub/runner/runner.mjs start | stop | status | autostart on|off|status | uninstall
+// @意图#R666(2026-10-29): 更傻瓜（king 同意 R666）：抽屉只给一条 npx 命令、配对码后面带服务器（码@域名）、pair 默认配完直接 start（--no-start 只配对）；
+//   Mac 上配对后问要不要开机自启（launchd，见 autostart.mjs）；报错一律大白话（Node 版本、连不上的各种原因、配对码不对/用过/过期、已有电脑、权限不够、配置坏了）；
+//   同一份配置只能跑一个（配置旁边 <配置>.lock 记进程号）；被服务器 4409 顶掉不再重连；4401/4403/顶掉都正常退出（0）并关掉自启；
+//   hello 报自己的版本和是不是开机自启，网页据此提示「有新版本」。
+// @意图#R664(2026-10-29): 运行器做成客户电脑 npm 安装的小工具（包名、命令名都是 agent-hub-runner，入口 bin/agent-hub-runner.mjs）：
+//   npm i -g agent-hub-runner → agent-hub-runner pair <配对码> --start --server <地址>；以后 agent-hub-runner start。仓库里 node 直接跑照旧。
+// @意图#R663(2026-10-29): pair 加 --start（二甲）：配对成功后直接接着 start 连上，网页上只给一条命令；不带 --start 的老用法不变
+// @意图#R640(2026-10-27): 一台电脑一个运行器，但每个 bot 有自己的授权目录（bot→目录 对照表 bot_dirs），互相碰不到；king 定乙：没有默认目录，
+// 每个 bot 都要在它的私聊里「我的电脑」（R663 起是输入框下面那一行，原来是右栏）点「选择目录」，运行器在本机弹窗选。服务器只报 bot_id，定不了路径。pair 不再收 --dir。
+// @意图#R639(2026-10-27): 配对不再选目录（king 定乙，替换 R637 配对时弹窗）；start 连上后在网页「我的电脑」点「选择目录」，
+// 服务器经这条 WebSocket 叫运行器在 Mac 上弹系统选文件夹窗口，选完马上生效并写回配置文件。
+// 配对后长期令牌和授权目录存在 ~/.agent-runner/config.json（权限 600）；目录只能由你在本机窗口里选，服务器只能叫你弹窗、定不了目录。
+// （R639 时目录是一台电脑一个、配对时还能 --dir；R640 起换成每个 bot 一个，老配置里的单一 dir 读到直接忽略。）
+// start 在终端前台运行，主动用 WebSocket 连服务器；按 Ctrl-C 立刻断开。没有沙箱。（R666 起有开机自启、npx 用法。）
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { runOp } from "./ops.mjs";
+import { autostartOff, autostartOn, autostartStatus, logFileFor, ONLY_MAC, otherAutostarts, runnerHome, truncateLogIfBig } from "./autostart.mjs";
+
+export const PROTOCOL_VERSION = 1;
+/** npm 包名，也是装好后的命令名 */
+export const PKG_BIN = "agent-hub-runner";
+/** R666：抽屉里给的、npx 运行时提示里写的命令前缀（@latest：每次都用最新版，也不会被电脑上旧的全局安装盖掉） */
+export const NPX_CMD = `npx -y ${PKG_BIN}@latest`;
+/** R666：自己的版本号（读同目录的 package.json；开机自启的副本也带着它），hello 时报给服务器 */
+export const RUNNER_VERSION = (() => { try { return String(JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version); } catch { return "0.0.0"; } })();
+/** R666：配对请求、连接超时（秒） */
+export const PAIR_TIMEOUT_MS = 15_000;
+export const HEARTBEAT_MS = 10_000;
+export const DEFAULT_SERVER = "http://127.0.0.1:3220";
+/** 服务器用这两个关闭码表示令牌不对 / 已在网页上断开：不再重连。 */
+export const CLOSE_BAD_TOKEN = 4401;
+export const CLOSE_REVOKED = 4403;
+/** R666：同一台电脑又连上来一个（同一份配置开了两个运行器），服务器把旧的这条用 4409 断开：不再重连 */
+export const CLOSE_REPLACED = 4409;
+
+// @意图#R666(2026-10-29): 默认目录可用 AGENT_RUNNER_HOME 换（测试、开机自启的副本用）；不设时和原来一样是 ~/.agent-runner/config.json
+export const configPath = () => process.env.AGENT_RUNNER_CONFIG || path.join(runnerHome(), "config.json");
+
+const stamp = () => new Date().toLocaleTimeString("zh-CN", { hour12: false });
+const say = (s) => console.log(`[${stamp()}] ${s}`);
+
+// @意图#R636(2026-10-27): 令牌文件权限 600、目录 700
+export function saveConfig(cfg, file = configPath()) {
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  writeFileSync(file, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(file, 0o600);
+}
+// @意图#R666(2026-10-29): 提示改成现在网页上的位置（输入框下面「我的电脑」那一行），不再说「连接电脑」；配置文件坏了说清楚怎么办
+export function loadConfig(file = configPath()) {
+  if (!existsSync(file)) throw new Error(`还没配对：没有 ${file}。先在网页上 bot 的私聊里点输入框下面「我的电脑」那一行，复制里面的命令运行。`);
+  const text = readFileSync(file, "utf8");
+  try { return JSON.parse(text); }
+  catch { throw new Error(`配置文件坏了：${file}。删掉它（rm "${file}"），再回网页拿新配对码重新配对。`); }
+}
+
+// @意图#R666(2026-10-29): pair 默认配完直接 start：--start 照样认（老命令），--no-start 只配对；--autostart / --no-autostart 跳过「开机自动连上？」的提问；
+// uninstall --purge 连配置一起删；--version / -v 打版本
+// @意图#R663(2026-10-29): 认 --start（只对 pair 有意义，不带值）
+export function parseArgs(argv) {
+  const [cmd, ...rest] = argv;
+  const out = { cmd: cmd === "--version" || cmd === "-v" ? "version" : cmd === "--help" || cmd === "-h" ? "help" : cmd, positional: [] };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--dir") out.dir = rest[++i];
+    else if (a === "--server") out.server = rest[++i];
+    else if (a === "--name") out.name = rest[++i];
+    else if (a === "--start") out.start = true;
+    else if (a === "--no-start") out.start = false;
+    else if (a === "--autostart") out.autostart = true;
+    else if (a === "--no-autostart") out.autostart = false;
+    else if (a === "--purge") out.purge = true;
+    else if (a.startsWith("--")) throw new Error(`不认识的参数 ${a}`);
+    else out.positional.push(a);
+  }
+  return out;
+}
+
+/** R666：Node 太低时的大白话（bin 入口在加载别的代码之前也用同样的话） */
+export const nodeTooOld = (v) => `需要 Node 22 或更新，你这台电脑上是 ${v}。\n（上面如果有几行英文 npm warn EBADENGINE，说的就是这个，不用管它。）\n去 https://nodejs.org 下载 LTS 版装上（Mac 选 .pkg 安装包），装好后关掉终端重新打开，再运行同一条命令。`;
+// @意图#R666(2026-10-29): 版本太低的提示改成大白话（怎么装、英文警告不用管）
+function checkNode() {
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 22 || typeof WebSocket === "undefined") throw new Error(nodeTooOld(process.versions.node));
+}
+
+export const PICK_PROMPT = "选择要授权给 bot 的文件夹";
+export const PICK_SCRIPT = `POSIX path of (choose folder with prompt "${PICK_PROMPT}")`;
+/** R640：这个 bot 在对照表里没有目录时，调用一律回这句。 */
+// @意图#R666(2026-10-29): 「右栏」是 R663 以前的位置，改成输入框下面「我的电脑」那一行（和服务器 devices.ts 的 NO_DIR 一字不差）
+export const NO_DIR = "还没给这个 bot 选目录，请在这个 bot 的私聊里点输入框下面「我的电脑」那一行，再点「选择目录」";
+export const PICK_ONLY_MAC = "只支持 Mac：选目录的窗口只在 Mac 上弹";
+/** R640：pair 带了 --dir 时的提示（不报错，照常配对，目录不用）。 */
+export const PAIR_DIR_IGNORED = "目录请连上后在每个 bot 的私聊里选（--dir 已不用，这次没用它）";
+
+/** 配置里的 bot→目录 对照表。只认 bot_dirs 里值是非空字符串的条目；老格式的单一 dir 直接忽略（所有 bot 都没有目录）。 */
+// @意图#R640(2026-10-27): king 定乙：没有默认目录；老配置的 dir 不迁成任何 bot 的目录
+export function botDirsOf(cfg) {
+  const out = {};
+  const m = cfg && typeof cfg.bot_dirs === "object" && cfg.bot_dirs !== null && !Array.isArray(cfg.bot_dirs) ? cfg.bot_dirs : {};
+  for (const [bot, dir] of Object.entries(m)) if (bot && typeof dir === "string" && dir) out[bot] = dir;
+  return out;
+}
+
+/**
+ * Mac 上弹系统「选文件夹」窗口。选了返回 POSIX 路径；点取消返回 null；signal 中止时关掉窗口进程并抛 AbortError；
+ * 弹不出来（比如没有图形界面）抛错。
+ */
+// @意图#R640(2026-10-27): 弹不出来时不再提 --dir（pair 不收 --dir 了）
+// @意图#R639(2026-10-27): 改成网页点「选择目录」时调用；服务器超时发 abort 要能关掉弹窗进程
+// @意图#R637(2026-10-27): 不写 --dir 时用 osascript 弹系统选文件夹窗口（king 定）；取消和弹不出来分开报
+export function pickDirMac({ signal } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile("osascript", ["-e", PICK_SCRIPT], { encoding: "utf8", signal }, (err, stdout, stderr) => {
+      if (!err) {
+        const p = String(stdout).trim();
+        return p ? resolve(p) : resolve(null);
+      }
+      if (signal?.aborted || err.name === "AbortError") return reject(Object.assign(new Error("已中止"), { name: "AbortError" }));
+      if (/-128|User canceled|用户已取消/.test(String(stderr))) return resolve(null);
+      const why = String(stderr).trim() || err.message;
+      reject(new Error(`弹不出选文件夹的窗口（${why}）`));
+    });
+  });
+}
+
+/** 检查授权目录：存在、换成真实路径、是目录、不是磁盘根目录。返回真实路径。 */
+// @意图#R640(2026-10-27): 每个 bot 选的目录都走这套检查
+// @意图#R639(2026-10-27): 配对时的 --dir 和网页上选的目录走同一套检查
+export async function checkDir(dir) {
+  const real = await fs.realpath(path.resolve(dir)).catch(() => { throw new Error(`授权目录不存在：${dir}`); });
+  if (!statSync(real).isDirectory()) throw new Error(`授权目录不是目录：${dir}`);
+  if (real === path.parse(real).root) throw new Error("不能把整个磁盘根目录授权出去");
+  return real;
+}
+
+/** 配对：用一次性配对码换长期令牌，存进本地配置。不选目录（连上后在每个 bot 的私聊里选）；带了 dir 不报错、不用，返回 dirIgnored。 */
+// @意图#R640(2026-10-27): 去掉 --dir：带了只提示「目录请连上后在每个 bot 的私聊里选」，照常配对；配置里 bot_dirs 是空表、不再有 dir
+// @意图#R639(2026-10-27已废弃): 配对不弹窗、不要求目录（king 定乙）；--dir 还能用，给了就照旧检查；没给 config.dir 为空（R640 去掉 --dir）
+// @意图#R637(2026-10-27已废弃): Mac 上没写 --dir 就弹窗选目录、取消不请求服务器（R639 改成连上后在网页上选）
+// @意图#R636(2026-10-27): 配对码一次性、5 分钟有效（服务器判断）；授权目录先换成真实路径再存
+// @意图#R666(2026-10-29): 配对码可以写成「码@服务器」（code 里带 @ 时拆开，见 parsePairTarget；显式给了 server 就用 server）；15 秒超时；
+// 连不上、服务器回错都翻成大白话（explainNetError / explainPairFailure）；缺码的提示不再写 runner.mjs
+export async function pair({ code, dir, server, name = os.hostname(), timeoutMs = PAIR_TIMEOUT_MS }, file = configPath()) {
+  checkNode();
+  const t = parsePairTarget(code, server);
+  if (!t.code) throw new Error(`缺配对码：${progName()} pair <配对码>@<服务器地址>（请从网页上原样复制整条命令）`);
+  let r;
+  try {
+    r = await fetch(`${t.server}/devices/pair`, {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ code: t.code, name, os: `${process.platform} ${os.release()}` }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) { throw new Error(explainNetError(e, t.server, timeoutMs)); }
+  const text = await r.text().catch(() => "");
+  let body = null;
+  try { body = JSON.parse(text); } catch { body = null; }
+  if (r.status !== 201 || !body || typeof body.token !== "string") throw new Error(explainPairFailure(r.status, body));
+  saveConfig({ server: t.server, device_id: body.device_id, token: body.token, name, bot_dirs: {} }, file);
+  return { deviceId: body.device_id, file, server: t.server, dirIgnored: dir !== undefined && dir !== null && dir !== "" };
+}
+
+const isLoopback = (h) => h === "localhost" || /^127\./.test(h) || h === "[::1]" || h === "::1";
+/**
+ * 「码@服务器」拆成 { code, server }（R666）：@ 后面没写 http:// / https:// 时默认 https，localhost、127.x、[::1] 用 http；可以带端口、路径；
+ * 去掉末尾的 /。显式给了 server（--server）就用它；没 @ 也没 --server 用 DEFAULT_SERVER（老行为）。地址看不懂、带 ? # 或账号密码就报错。
+ */
+// @意图#R666(2026-10-29): 配对码里带服务器信息（king 定一甲：码@域名），命令里不用再写 --server；老写法 pair 码 --server 地址照样能用
+export function parsePairTarget(raw, server) {
+  const s = String(raw ?? "").trim();
+  const at = s.indexOf("@");
+  const code = (at < 0 ? s : s.slice(0, at)).trim();
+  const where = at < 0 ? "" : s.slice(at + 1).trim();
+  if (server) return { code, server: String(server).trim().replace(/\/+$/, "") };
+  if (!where) return { code, server: DEFAULT_SERVER };
+  const explicit = /^https?:\/\//i.test(where);
+  let u;
+  try { u = new URL(explicit ? where : `https://${where}`); }
+  catch { throw new Error(`配对码后面的服务器地址看不懂：${where}。请从网页上原样复制整条命令。`); }
+  if (u.search || u.hash || u.username || u.password) throw new Error(`服务器地址不能带 ? # 或账号密码：${where}。请从网页上原样复制整条命令。`);
+  if (!explicit && isLoopback(u.hostname)) u.protocol = "http:";
+  return { code, server: `${u.origin}${u.pathname}`.replace(/\/+$/, "") };
+}
+
+const hostOf = (server) => { try { return new URL(server).host; } catch { return server; } };
+/** fetch 失败（连不上）翻成大白话：找不到、没开、证书、超时、被断开、其他 */
+// @意图#R666(2026-10-29): 原来只打一句英文 fetch failed；按 cause.code 分开说（king 定五）
+export function explainNetError(e, server, timeoutMs = PAIR_TIMEOUT_MS) {
+  const code = String(e?.cause?.code ?? e?.cause?.cause?.code ?? e?.code ?? "");
+  const host = hostOf(server);
+  if (e?.name === "TimeoutError" || e?.name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT") {
+    return `连服务器超时（${Math.round(timeoutMs / 1000)} 秒没回应）：${host}。检查这台电脑能不能上网，或者稍后再试。`;
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") return `找不到服务器 ${host}：命令里 @ 后面的地址可能写错了，或者这台电脑没联网。`;
+  if (code === "ECONNREFUSED") return `连不上服务器 ${server}：服务器没开，或者地址、端口不对。`;
+  if (/CERT|SELF_SIGNED|UNABLE_TO_VERIFY|ERR_TLS|SSL/.test(code)) return `服务器 ${host} 的 https 证书有问题（${code}）：可能证书过期了，或者网络在拦截。请告诉服务器的管理员。`;
+  if (code === "ECONNRESET" || code === "EPIPE" || code === "UND_ERR_SOCKET") return `和服务器 ${host} 的连接被断开了：稍后再试；一直这样请检查代理或网络。`;
+  return `连不上服务器 ${server}（${code || e?.message || "未知原因"}）：检查网络和命令里的地址。`;
+}
+
+/** R666：服务器回的错误码（/devices/pair 返回的 code）对应的大白话 */
+export const PAIR_ERR = {
+  bad_code: "配对码不对：请从网页上原样复制整条命令再运行（码只能用一次，5 分钟有效）。",
+  used: "这个配对码已经用过了：回网页点「换一个码」，再复制新命令运行。",
+  replaced: "这个配对码已经作废了（网页上换过新码）：请复制网页上最新的那条命令运行。",
+  expired: "配对码过期了（5 分钟有效）：回网页点「换一个码」，再复制新命令运行。",
+  device_exists: "这个账号已经连着一台电脑了：先在网页「我的电脑」抽屉最下面「连着的电脑」里点「断开」，再换一个码重新配对。",
+  bad_input: "命令不完整：请从网页上原样复制整条命令再运行。",
+};
+const NOT_HUB = (status) => `这个地址不是 agent-hub 服务器（回了 ${status}）：检查命令里 @ 后面的地址，请从网页上原样复制整条命令。`;
+/** 配对请求回的不是 201：先看服务器给的 code，老服务器没 code 就按状态码猜；回的不是 JSON 多半不是 agent-hub */
+// @意图#R666(2026-10-29): 400/410/409/404/405/非 JSON/5xx 各给一句（king 定五）
+export function explainPairFailure(status, body) {
+  if (body && typeof body === "object" && PAIR_ERR[body.code]) return `配对失败：${PAIR_ERR[body.code]}`;
+  if (status === 404 || status === 405) return `配对失败：${NOT_HUB(status)}`;
+  if (status >= 500) return `配对失败：服务器出错了（${status}），稍后再试。`;
+  if (!body || typeof body !== "object") return `配对失败：${NOT_HUB(status)}`;
+  if (status === 410) return `配对失败：${PAIR_ERR.expired}`;
+  if (status === 409) return `配对失败：${PAIR_ERR.device_exists}`;
+  if (status === 400) return `配对失败：${PAIR_ERR.bad_code}`;
+  return `配对失败（${status}）：${body.error ?? "未知原因"}`;
+}
+
+/** 整个命令出错时打给人看的话：权限不够（多半用 sudo 跑过）单独说怎么修，别的原样 */
+// @意图#R666(2026-10-29): EACCES / EPERM 提示别用 sudo + chown（king 定五）
+export function explainError(e) {
+  const code = e?.code;
+  if (code === "EACCES" || code === "EPERM") {
+    const p = e.path ? String(e.path) : runnerHome();
+    const dir = p.startsWith(runnerHome()) ? runnerHome() : path.dirname(p);
+    return `权限不够，写不了 ${p}：别用 sudo 运行这个命令。如果以前用 sudo 跑过，先运行 sudo chown -R "$(whoami)" "${dir}"，再重新运行。`;
+  }
+  return e?.message ?? String(e);
+}
+
+const wsUrlOf = (server) => `${server.replace(/^http/, "ws")}/devices/ws`;
+
+/**
+ * 一条连接上的工作：执行工具调用、网页叫弹窗选目录。每个 bot 一个授权目录（对照表），选完新目录，这个 bot 之后的调用只认新目录；已经在跑的不打断。
+ * 返回 { onMessage(msg, send), killAll(), botDirs }，startRunner 用它，测试也直接用它（不用起 WebSocket）。
+ */
+// @意图#R640(2026-10-27): 目录按 bot 分：call 按 bot_id 查对照表，没有就拒绝 NO_DIR；pick_dir 带 bot_id，选完检查后记进对照表、写回配置（600），
+// 回 dir_result {id, ok, bot_id, dir}；老配置的单一 dir 忽略
+// @意图#R639(2026-10-27已废弃): 目录不再是连接时固定的常量；没目录时 call 一律拒绝；pick_dir 选完检查、写回配置（600）、回 dir_result（R640 改成按 bot 分）
+export function createSession(cfg, { log = say, pickDir = pickDirMac, platform = process.platform, file = configPath() } = {}) {
+  let dirs = botDirsOf(cfg); // bot_id → 授权目录
+  const jobs = new Map(); // 调用 id → AbortController
+  const picks = new Map(); // 弹窗 id → AbortController
+
+  async function handleCall(send, msg) {
+    const { id, op, args } = msg;
+    const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
+    const dir = bot ? dirs[bot] : undefined; // 这次调用用开始时这个 bot 的目录；中途换目录不影响它
+    if (!dir) { send({ type: "result", id, ok: false, error: NO_DIR }); return; }
+    const ac = new AbortController();
+    jobs.set(id, ac);
+    log(`[${bot}] ${op === "bash" ? `bash：${args?.command}` : `${op}：${args?.path}`}`);
+    try {
+      const res = await runOp(op, args, dir, { signal: ac.signal, onData: (d) => send({ type: "output", id, data: Buffer.from(d).toString("base64") }) });
+      if (ac.signal.aborted) send({ type: "result", id, ok: false, error: "已中止" });
+      else send({ type: "result", id, ok: true, ...res });
+    } catch (e) {
+      send({ type: "result", id, ok: false, error: e?.message ?? String(e) });
+    } finally {
+      jobs.delete(id);
+    }
+  }
+
+  async function handlePick(send, msg) {
+    const { id } = msg;
+    const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
+    if (!bot) { send({ type: "dir_result", id, ok: false, error: "缺 bot_id" }); return; }
+    if (platform !== "darwin") { send({ type: "dir_result", id, ok: false, bot_id: bot, error: PICK_ONLY_MAC }); return; }
+    const ac = new AbortController();
+    picks.set(id, ac);
+    log(`网页上给 bot ${bot} 点了选择目录：请在弹出的窗口里选文件夹`);
+    try {
+      const picked = await pickDir({ signal: ac.signal });
+      if (ac.signal.aborted) return; // 服务器那边已经按超时处理了
+      if (!picked) { log("没换目录（点了取消）"); send({ type: "dir_result", id, ok: false, bot_id: bot, cancelled: true }); return; }
+      const real = await checkDir(picked);
+      dirs = { ...dirs, [bot]: real };
+      cfg.bot_dirs = { ...dirs };
+      delete cfg.dir; // 老格式的单一 dir 不再写回
+      saveConfig(cfg, file);
+      log(`bot ${bot} 的授权目录换成 ${real}`);
+      send({ type: "dir_result", id, ok: true, bot_id: bot, dir: real });
+    } catch (e) {
+      if (ac.signal.aborted) { log("选目录超时，窗口已关掉"); return; }
+      send({ type: "dir_result", id, ok: false, bot_id: bot, error: e?.message ?? String(e) });
+    } finally {
+      picks.delete(id);
+    }
+  }
+
+  return {
+    get botDirs() { return { ...dirs }; },
+    onMessage(msg, send) {
+      if (msg.type === "call") return handleCall(send, msg);
+      if (msg.type === "pick_dir") return handlePick(send, msg);
+      if (msg.type === "abort") { jobs.get(msg.id)?.abort(); picks.get(msg.id)?.abort(); }
+      return undefined;
+    },
+    killAll() {
+      for (const ac of jobs.values()) ac.abort();
+      for (const ac of picks.values()) ac.abort();
+      jobs.clear();
+      picks.clear();
+    },
+  };
+}
+
+/**
+ * 连服务器并执行转发来的工具调用。断线会自动重连（不重放旧调用）；令牌不对或网页上断开了就停。
+ * 返回 { stop, done }：stop() 立刻断开并杀掉正在跑的命令。
+ */
+// @意图#R666(2026-10-29): hello 多报 runner_version（网页提示有新版本）和 autostart（是不是开机自启起的，网页据此给升级命令）；
+// 服务器用 4409 顶掉这条（同一份配置又开了一个）：不再重连、结束（"replaced"）；连不上时只在第一次和之后每 30 次打一行，开机自启没网时日志不刷屏；
+// 连上那句不再说「右栏」，开机自启时不说「按 Ctrl-C」
+// @意图#R640(2026-10-27): hello 报 bot→目录 对照表（bot_dirs），不再报单一 dir
+// @意图#R639(2026-10-27): 没目录也能连上；目录由 createSession 管（网页上选完马上生效），重连时 hello 带当前目录
+// @意图#R636(2026-10-27): 前台运行、心跳、执行工具调用；断线时杀掉正在跑的命令，重连后不重放
+export function startRunner(cfg, { log = say, retryMs = 2000, pickDir = pickDirMac, platform = process.platform, file = configPath(), background = process.env.AGENT_RUNNER_LAUNCHD === "1" } = {}) {
+  checkNode();
+  let fails = 0;
+  const session = createSession(cfg, { log, pickDir, platform, file });
+  let ws = null;
+  let stopped = false;
+  let beat = null;
+  let resolveDone;
+  const done = new Promise((r) => { resolveDone = r; });
+  const finish = (why) => { if (!stopped) { stopped = true; } resolveDone(why); };
+  const send = (sock, msg) => { if (sock.readyState === WebSocket.OPEN) sock.send(JSON.stringify(msg)); };
+
+  function connect() {
+    if (stopped) return;
+    const sock = new WebSocket(wsUrlOf(cfg.server));
+    ws = sock;
+    sock.addEventListener("open", () => {
+      send(sock, { type: "hello", version: PROTOCOL_VERSION, device_id: cfg.device_id, token: cfg.token, bot_dirs: session.botDirs,
+        name: cfg.name ?? os.hostname(), os: `${process.platform} ${os.release()}`, runner_version: RUNNER_VERSION, autostart: background });
+      beat = setInterval(() => send(sock, { type: "ping" }), HEARTBEAT_MS);
+    });
+    sock.addEventListener("message", (ev) => {
+      let msg;
+      try { msg = JSON.parse(typeof ev.data === "string" ? ev.data : Buffer.from(ev.data).toString("utf8")); } catch { return; }
+      if (msg.type === "ready") {
+        fails = 0;
+        const n = Object.keys(session.botDirs).length;
+        const tail = background ? "（开机自启，在后台运行）" : "按 Ctrl-C 断开。";
+        log(n ? `已连上服务器 ${cfg.server}，${n} 个 bot 选了目录。${tail}`
+          : `已连上服务器 ${cfg.server}，还没有 bot 选目录：请在网页上每个 bot 的私聊里点输入框下面「我的电脑」那一行，再点「选择目录」。${tail}`);
+      } else if (msg.type === "revoked") { session.killAll(); log("网页上已断开这台电脑，令牌已作废。要再连，请在网页上重新拿配对码配对。"); }
+      else void session.onMessage(msg, (m) => send(sock, m));
+    });
+    sock.addEventListener("close", (ev) => {
+      clearInterval(beat);
+      session.killAll(); // 断线：正在跑的命令杀掉、弹窗关掉，服务器那边按「设备离线」返回，重连后不重放
+      if (ws === sock) ws = null;
+      if (stopped) return;
+      if (ev.code === CLOSE_BAD_TOKEN) { log("服务器不认这个令牌（可能已经在网页上断开过）。请重新配对。"); finish("bad_token"); return; }
+      if (ev.code === CLOSE_REVOKED) { log("这台电脑已在网页上断开。请重新配对。"); finish("revoked"); return; }
+      if (ev.code === CLOSE_REPLACED) { log("同一份配置在别处又开了一个运行器，服务器把这个顶掉了：这个先退出（不再重连）。"); finish("replaced"); return; }
+      fails += 1;
+      if (fails === 1 || fails % 30 === 0) log(`和服务器的连接断了，${retryMs / 1000} 秒后重连${fails > 1 ? `（已经连不上 ${fails} 次，会一直重试）` : ""}`);
+      setTimeout(connect, retryMs);
+    });
+    sock.addEventListener("error", () => { /* close 里处理 */ });
+  }
+  connect();
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    session.killAll();
+    clearInterval(beat);
+    try { ws?.close(1000, "runner stopped"); } catch { /* ignore */ }
+    resolveDone("stopped");
+  };
+  return { stop, done };
+}
+
+/** R666：同一份配置只能跑一个：配置旁边的 <配置>.lock 记着进程号 */
+export const lockPath = (file = configPath()) => `${file}.lock`;
+export function readLock(file = configPath()) {
+  try { const j = JSON.parse(readFileSync(lockPath(file), "utf8")); return Number.isInteger(j?.pid) ? j : null; } catch { return null; }
+}
+export const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e?.code === "EPERM"; } };
+/**
+ * 拿锁：别的活着的进程拿着就返回 { ok: false, pid, launchd }；否则写上自己（600）返回 { ok: true, release }。
+ * 进程死了留下的旧锁直接覆盖。
+ */
+// @意图#R666(2026-10-29): 防互踢（king 定必须做）：开机自启的在后台跑着，再在终端里 start 就提示「已经在后台连着」退出，不再两个互相顶
+export function takeLock(file = configPath(), { pid = process.pid, launchd = process.env.AGENT_RUNNER_LAUNCHD === "1" } = {}) {
+  const cur = readLock(file);
+  if (cur && cur.pid !== pid && pidAlive(cur.pid)) return { ok: false, pid: cur.pid, launchd: !!cur.launchd };
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  writeFileSync(lockPath(file), `${JSON.stringify({ pid, launchd, started_at: new Date().toISOString() })}\n`, { mode: 0o600 });
+  return { ok: true, release: () => { if (readLock(file)?.pid === pid) rmSync(lockPath(file), { force: true }); } };
+}
+
+/** 被网页断开 / 令牌失效后把这份配置的开机自启关掉（不然每次登录都白起一次）；不是 Mac、没开都不要紧 */
+async function autostartOffQuietly(file, deps) {
+  if ((deps.platform ?? process.platform) !== "darwin") return false;
+  try { return (await autostartOff({ configFile: file, launchctl: deps.launchctl })).wasOn; } catch { return false; }
+}
+
+// @意图#R666(2026-10-29): 先拿锁（后台已在跑就提示退出 0）；开机自启时启动前日志超 5MB 清空、配置坏了/没配对也退出 0（不让 launchd 反复拉起）；
+// 结束一律退出码 0（Ctrl-C、被网页断开、令牌失效、被顶掉），被断开 / 令牌失效时顺手关掉自启
+// @意图#R663(2026-10-29): 前台跑 start，Ctrl-C 断开（pair --start 和 start 共用）
+async function runStart(prog = progName(), deps = {}) {
+  const file = configPath();
+  const background = process.env.AGENT_RUNNER_LAUNCHD === "1";
+  if (background && truncateLogIfBig(logFileFor(file))) say("日志超过 5MB，已清空");
+  let cfg;
+  try { cfg = loadConfig(file); } catch (e) {
+    if (background) { console.error(explainError(e)); process.exit(0); }
+    throw e;
+  }
+  const lock = takeLock(file);
+  if (!lock.ok) {
+    console.log(`已经在后台连着，不用再开（进程 ${lock.pid}${lock.launchd ? "，开机自启起的" : ""}）。要停掉它：${prog} stop`);
+    process.exit(0);
+  }
+  const r = startRunner(cfg, { file, background });
+  const quit = () => { r.stop(); lock.release(); setTimeout(() => process.exit(0), 100); };
+  process.on("SIGINT", quit);
+  process.on("SIGTERM", quit);
+  const why = await r.done;
+  lock.release();
+  if (why === "bad_token" || why === "revoked") {
+    if (await autostartOffQuietly(file, deps)) say("已关掉开机自启（这台电脑在网页上断开了）。");
+  }
+  process.exit(0);
+}
+
+/** R666：配完要不要开机自启：flag（--autostart / --no-autostart）优先；不是 Mac 不开；是终端就问；不是终端（脚本、管道）不问、只提示 */
+export function decideAutostart({ flag, platform = process.platform, tty = !!(process.stdin.isTTY && process.stdout.isTTY) }) {
+  if (flag === true) return platform === "darwin" ? "on" : "unsupported";
+  if (flag === false) return "off";
+  if (platform !== "darwin") return "off";
+  return tty ? "ask" : "hint";
+}
+
+/** 终端里问一句 是/否；直接回车 = dflt */
+export async function askYesNo(question, dflt = true, { input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({ input, output });
+  try {
+    const a = (await rl.question(question)).trim().toLowerCase();
+    if (!a) return dflt;
+    return ["y", "yes", "是", "好", "要"].includes(a);
+  } finally { rl.close(); }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 停掉拿着锁的那个运行器（不是自己）；等它真退出（最多 5 秒）。返回被停的锁信息，没有在跑的返回 null */
+async function stopHolder(file) {
+  const l = readLock(file);
+  if (!l || l.pid === process.pid || !pidAlive(l.pid)) return null;
+  try { process.kill(l.pid, "SIGTERM"); } catch { /* 已经没了 */ }
+  for (let i = 0; i < 50 && pidAlive(l.pid); i++) await sleep(100);
+  return l;
+}
+
+const here = () => path.dirname(fileURLToPath(import.meta.url));
+// @意图#R666(2026-10-29): 开启自启：前台有一个在跑就先停掉它（不然后台那个起来就因为锁退出了），再交给 autostart.mjs（复制自己、写 plist、加载）
+async function turnAutostartOn(file, prog, deps = {}) {
+  const held = readLock(file);
+  if (held && !held.launchd) await stopHolder(file);
+  const r = await autostartOn({ configFile: file, version: RUNNER_VERSION, srcDir: here(), launchctl: deps.launchctl, platform: deps.platform });
+  console.log(`已设开机自启：以后登录这台 Mac 会自动连上，不用开终端。现在已经在后台连着，可以关掉这个终端窗口了。\n日志：${r.log}\n关掉开机自启：${prog} autostart off`);
+  return r;
+}
+
+const usage = (prog) => `用法：
+  ${prog} pair <配对码>@<服务器地址> [--no-start] [--autostart | --no-autostart]
+    （网页上「我的电脑」里复制的就是这一条；配完直接连上，Mac 上会问要不要开机自动连上；--no-start 只配对不连）
+    （老写法 ${prog} pair <配对码> --server <地址> 也能用）
+  ${prog} start              连上服务器（终端窗口别关；Ctrl-C 断开）
+  ${prog} stop               停掉在跑的运行器
+  ${prog} status             看配置、各 bot 的目录、在不在跑、开机自启
+  ${prog} autostart on|off|status   Mac 开机自启（on 也用来升级到新版本）
+  ${prog} uninstall [--purge]       关掉自启、删掉本地副本和日志（--purge 连配置一起删）
+  ${prog} --version
+目录请连上后在网页上每个 bot 的私聊里点输入框下面「我的电脑」那一行选，Mac 上会弹窗让你选。`;
+
+// @意图#R666(2026-10-29): pair 默认配完直接 start（--no-start 只配对）；配完按 decideAutostart 问 / 提示 / 开启开机自启，开了就不在前台跑；
+// 新命令 stop、autostart on|off|status、uninstall、--version；status 多显示在不在跑、版本、开机自启；用法里的命令按运行方式写（npx 时写 npx 写法）
+// @意图#R664(2026-10-29): 导出给 bin/agent-hub-runner.mjs 调；用法和「现在运行：… start」里的命令名用 progName（装好的 agent-hub-runner，仓库里 node 写法）
+// @意图#R663(2026-10-29): pair --start 配对成功后直接进 start（二甲）；提示里「我的电脑」改成在私聊输入框下面那一行点开（R663 挪了位置）；不带 --start 照旧提示再运行 start（R666 起默认就 start，--no-start 才提示）
+// @意图#R640(2026-10-27): pair 带 --dir 只提示不报错；status 列出每个 bot 的目录；用法文字去掉 --dir
+export async function main(argv, prog = progName(), deps = {}) {
+  checkNode();
+  const a = parseArgs(argv);
+  const platform = deps.platform ?? process.platform;
+  if (a.cmd === "pair") {
+    const r = await pair({ code: a.positional[0], dir: a.dir, server: a.server, name: a.name ?? os.hostname() });
+    if (r.dirIgnored) console.log(PAIR_DIR_IGNORED);
+    const where = "目录：连上后在网页上每个 bot 的私聊里，点输入框下面「我的电脑」那一行选。";
+    console.log(`配对成功（服务器 ${r.server}）。${where}\n配置存在 ${r.file}（权限 600）。`);
+    const how = decideAutostart({ flag: a.autostart, platform, tty: deps.tty });
+    let on = how === "on";
+    if (how === "ask") on = await (deps.ask ?? askYesNo)("开机自动连上？以后不用开终端 (Y/n) ", true);
+    if (how === "unsupported") console.log(ONLY_MAC + "，这次不设。");
+    if (on) {
+      try { await turnAutostartOn(r.file, prog, deps); return; }
+      catch (e) { console.log(`开机自启没设成：${explainError(e)}\n这次先在前台连着（终端窗口别关）。`); }
+    }
+    if (how === "ask") console.log(`好的，不设开机自启。以后想开：${prog} autostart on`);
+    if (how === "hint") console.log(`想开机自动连上（不用开终端）：运行 ${prog} autostart on`);
+    if (a.start === false) { console.log(`现在运行：${prog} start`); return; }
+    console.log("接着连服务器……");
+    await runStart(prog, deps);
+    return;
+  }
+  if (a.cmd === "start") { await runStart(prog, deps); return; }
+  if (a.cmd === "stop") {
+    const l = await stopHolder(configPath());
+    if (!l) { console.log("没有在跑的运行器。"); return; }
+    console.log(`已停掉（进程 ${l.pid}）。${l.launchd ? `开机自启还开着，下次登录会自己连上；不想要：${prog} autostart off` : ""}`);
+    return;
+  }
+  if (a.cmd === "autostart") {
+    const sub = a.positional[0] ?? "status";
+    const file = configPath();
+    if (sub === "on") { loadConfig(file); await turnAutostartOn(file, prog, deps); return; }
+    if (platform !== "darwin") { console.log(ONLY_MAC); return; }
+    if (sub === "off") {
+      const r = await autostartOff({ configFile: file, launchctl: deps.launchctl });
+      console.log(r.wasOn ? "已关掉开机自启（后台那个也停了）。" : "本来就没开开机自启。");
+      return;
+    }
+    if (sub === "status") {
+      const st = await autostartStatus({ configFile: file, launchctl: deps.launchctl, platform });
+      console.log(st.installed ? `开机自启：开着（${st.loaded ? (st.pid ? `后台在跑，进程 ${st.pid}` : "已加载，现在没在跑") : "还没加载"}）\nplist：${st.plist}\n日志：${st.log}` : "开机自启：没开");
+      for (const p of st.problems) console.log(`注意：${p}`);
+      return;
+    }
+    throw new Error(`autostart 后面只能是 on、off 或 status（${sub} 不认识）`);
+  }
+  if (a.cmd === "uninstall") {
+    const file = configPath();
+    if (platform === "darwin") await autostartOff({ configFile: file, launchctl: deps.launchctl }).catch(() => {});
+    await stopHolder(file);
+    const home = runnerHome();
+    if (!otherAutostarts(file).length) {
+      rmSync(path.join(home, "bin"), { recursive: true, force: true });
+      rmSync(path.join(home, "logs"), { recursive: true, force: true });
+    }
+    let purge = !!a.purge;
+    if (!purge && existsSync(file) && (deps.tty ?? !!(process.stdin.isTTY && process.stdout.isTTY))) {
+      purge = await (deps.ask ?? askYesNo)("要连配对信息（令牌）一起删掉吗？删了以后要重新配对 (y/N) ", false);
+    }
+    if (purge) { rmSync(file, { force: true }); rmSync(lockPath(file), { force: true }); }
+    console.log(`已卸载：开机自启关了、本地副本和日志删了。${purge ? `配置也删了（${file}）；记得在网页「我的电脑」里点「断开」作废令牌。` : `配置留着（${file}）；连配置一起删：${prog} uninstall --purge`}`);
+    return;
+  }
+  if (a.cmd === "status") {
+    const file = configPath();
+    const cfg = loadConfig(file);
+    const d = Object.entries(botDirsOf(cfg));
+    const l = readLock(file);
+    const run = l && pidAlive(l.pid) ? `在跑（进程 ${l.pid}${l.launchd ? "，开机自启" : ""}）` : "没在跑";
+    let auto = "";
+    if (platform === "darwin") {
+      const st = await autostartStatus({ configFile: file, launchctl: deps.launchctl, platform }).catch(() => null);
+      auto = `\n开机自启：${st?.installed ? "开着" : "没开"}${st?.problems?.length ? `（${st.problems.join("；")}）` : ""}`;
+    }
+    console.log(`服务器：${cfg.server}\n设备：${cfg.device_id}\n运行器版本：${RUNNER_VERSION}\n现在：${run}${auto}\n各 bot 的授权目录：${d.length ? d.map(([b, p]) => `\n  ${b}：${p}`).join("") : "（还没有，连上后在每个 bot 的私聊里点「选择目录」）"}`);
+    return;
+  }
+  if (a.cmd === "version") { console.log(RUNNER_VERSION); return; }
+  console.log(usage(prog));
+  process.exitCode = a.cmd && a.cmd !== "help" ? 1 : 0;
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+
+/** 这个文件是不是被直接运行的（经符号链接运行也算：两边都换成真实路径再比）。 */
+// @意图#R664(2026-10-29): npm 装好的命令是指向源码的符号链接，原来按字面路径比较会判成「不是直接运行」、什么都不做；改成真实路径比较
+export function isMainModule(argv1 = process.argv[1], metaUrl = import.meta.url) {
+  return !!argv1 && real(argv1) === real(fileURLToPath(metaUrl));
+}
+
+/**
+ * 用法和提示里怎么称呼自己：npm 装好的（经 bin 里的 agent-hub-runner 链接运行，或文件在 node_modules 里）说 agent-hub-runner，
+ * 仓库里直接跑说 node <相对路径>。
+ */
+// @意图#R666(2026-10-29): npx 跑的（npm 设 npm_lifecycle_event=npx，或文件在 npx 缓存 _npx 目录里）和开机自启的本地副本（~/.agent-runner/bin 下）都写 npx 写法：
+// 这两种情况电脑上都没有 agent-hub-runner 这个命令
+// @意图#R664(2026-10-29): 用法和配对成功提示按运行方式区分：装好的显示 agent-hub-runner …，仓库里显示 node 写法
+export function progName(entry = process.argv[1], cwd = process.cwd(), env = process.env) {
+  if (!entry) return PKG_BIN;
+  if (isNpx(entry, env)) return NPX_CMD;
+  const r = real(entry);
+  const bin = real(path.join(runnerHome(env), "bin"));
+  if (r === bin || r.startsWith(`${bin}${path.sep}`)) return NPX_CMD;
+  if (path.basename(entry) === PKG_BIN) return PKG_BIN;
+  if (/[\\/]node_modules[\\/]/.test(r)) return PKG_BIN;
+  return `node ${path.relative(cwd, r) || path.basename(r)}`;
+}
+/** 是不是 npx 跑起来的 */
+export function isNpx(entry = process.argv[1], env = process.env) {
+  if (env.npm_lifecycle_event === "npx") return true;
+  return !!entry && /[\\/]_npx[\\/]/.test(real(entry));
+}
+
+// @意图#R666(2026-10-29): 出错时打大白话（权限不够单独说）
+if (isMainModule()) {
+  main(process.argv.slice(2)).catch((e) => { console.error(explainError(e)); process.exit(1); });
+}