@m2canvas/connect 0.6.0 → 0.7.0

package/README.md

@@ -45,3 +45,20 @@ Lets M2 (in Chrome or another Chromium browser) start and talk to the agents on
 Agent sessions start in that directory.
 
 Options: `--port <n>`, `--cwd <dir>` (default: current directory), `--verbose` (also print agent stderr), `--dev` (also accept the local M2 dev server), `--replace` (stop the M2 bridge already running on the port first).
+
+## One-time install (macOS)
+
+M2's Local Agent tab can have an agent app set the bridge up for you, so you need neither a terminal nor Node.js:
+
+```bash
+curl -fsSL https://m2ui.ai/connect/install.sh | sh -s -- --pair <value from M2>
+```
+
+- **From M2.** Click "Connect with Claude" (or Codex, or Cursor): the app opens with this command in a prompt, and you press Return. The installer puts a private Node.js and a pinned version of this package in `~/.m2canvas`, checking every download against the hashes M2 publishes; writes the launcher `~/.m2canvas/bin/m2-bridge`; and starts the bridge in the background. The page pairs by itself. Agent sessions start in `~/.m2canvas/workspace`.
+- **Nothing starts at login.** After a restart, M2 asks the agent app to run `~/.m2canvas/bin/m2-bridge start --pair <value>` (you can run it yourself too). The launcher first updates the bridge to the version listed at `https://m2ui.ai/connect/manifest.json`, and goes back to the previous version if the new one doesn't start. The bridge keeps running after you quit the app, until you log out or shut down.
+- **No pairing codes in the background.** A bridge started this way has no window to show a code in. If a page isn't paired (the pairing expired, or you use another browser), M2 offers "Reconnect", which runs the launcher with `--replace`: it restarts the bridge and pairs that page, and agent sessions on the old bridge end.
+- **Sandboxes.** Codex needs its Full access permission mode: its default sandbox can't reach the network or write to your home folder. Inside the Codex or Claude command sandbox, the scripts change nothing and say what to do instead.
+- **What it leaves alone.** macOS 13.5 or later. It doesn't use sudo, register anything to start at login, change your shell config or PATH, or touch a Node.js you installed yourself. Logs are in `~/.m2canvas/logs/`.
+- **Uninstall** with `curl -fsSL https://m2ui.ai/connect/uninstall.sh | sh`, or "Uninstall local connection" in the Local Agent tab's ⋯ menu. It stops the bridge and removes what the installer added; `~/.m2canvas/workspace` is kept if it has files in it, and your agents' M2 settings stay as they are.
+
+The `npx` command above still works and is what M2 shows under "Advanced", for running the bridge in a folder you choose.

package/dist/bridge/adapters.js

@@ -41,7 +41,9 @@ export const ADAPTERS = {
 /** 适配器自带的 codex：预检与授权命令都要用它（本机旧版 codex 存的凭证，新版本刷新不了，PoC 报告 §2.2） */
 export const CODEX_SCRIPT = 'node_modules/@openai/codex/bin/codex.js';
 export const CODEX_BIN_LINK = 'node_modules/.bin/codex';
-const READY_MARKER = '.m2canvas-ready';
+/** 安装完成的标记文件：没有它的目录一律视为未安装（自动更新清理旧目录时也只删带它的，change acp-bridge-one-time-install N2） */
+export const ADAPTER_READY_MARKER = '.m2canvas-ready';
+const READY_MARKER = ADAPTER_READY_MARKER;
 const PROGRESS_INTERVAL_MS = 1000;
 /**
  * Linux 上没有 glibc（Alpine 等）时优先 musl 版本：与 claude-agent-sdk 自身的判断相同（process.report 的 glibcVersionRuntime）。
@@ -122,6 +124,14 @@ function isProcessAlive(pid) {
 export function isAdapterAgent(agent) {
     return agent === 'claude' || agent === 'codex';
 }
+/**
+ * 安装目录名 = `<适配器目录名>-<lockfile 的 sha256 前 16 位>`：换了 lockfile 就是新目录。
+ * 自动更新按 current / previous 两个版本各自的 lockfile 算出要保留的目录（change acp-bridge-one-time-install N2），所以规则只能在这一处。
+ */
+export function adapterInstallDirName(sourceRoot, dir) {
+    const lock = readFileSync(join(sourceRoot, dir, 'package-lock.json'));
+    return `${dir}-${createHash('sha256').update(lock).digest('hex').slice(0, 16)}`;
+}
 export class AdapterManager {
     options;
     installing = new Map();
@@ -130,12 +140,8 @@ export class AdapterManager {
     constructor(options) {
         this.options = options;
     }
-    lockKey(agent) {
-        const lock = readFileSync(join(this.options.sourceRoot, ADAPTERS[agent].dir, 'package-lock.json'));
-        return createHash('sha256').update(lock).digest('hex').slice(0, 16);
-    }
     installDir(agent) {
-        return join(this.options.installRoot, `${ADAPTERS[agent].dir}-${this.lockKey(agent)}`);
+        return join(this.options.installRoot, adapterInstallDirName(this.options.sourceRoot, ADAPTERS[agent].dir));
     }
     entryPath(agent) {
         return join(this.installDir(agent), ADAPTERS[agent].entry);

package/dist/bridge/install-layout.js

@@ -0,0 +1,37 @@
+/**
+ * 一次性安装在 `~/.m2canvas` 下的目录布局（change acp-bridge-one-time-install D15）。
+ *
+ * 同一份布局还写死在两个 sh 脚本里：安装脚本 `public/connect/install.sh` 与启动器源 `packages/connect/install/m2-bridge.sh`
+ * （脚本不能 import 这里）。改这里要同批改那两处；脚本测试会按这里的路径核对它们的产物。
+ *
+ * 全部在用户主目录下，不写任何系统目录、不注册任何启动项、不改 PATH（`connect/local-bridge` 契约 14 delta）。
+ * 其余已有文件（配对记录 `bridge-pairings.json`、状态文件 `bridge-<port>.json`、适配器 `acp-adapters/`）位置不变。
+ */
+import { join } from 'node:path';
+export function installLayout(home) {
+    const root = join(home, '.m2canvas');
+    const bridge = join(root, 'bridge');
+    const logs = join(root, 'logs');
+    return {
+        root,
+        runtime: join(root, 'runtime'),
+        bridge,
+        current: join(bridge, 'current'),
+        previous: join(bridge, 'previous'),
+        rejected: join(bridge, 'rejected'),
+        launcher: join(root, 'bin', 'm2-bridge'),
+        logs,
+        updateLog: join(logs, 'update.log'),
+        workspace: join(root, 'workspace'),
+        adapters: join(root, 'acp-adapters'),
+    };
+}
+/** 版本目录里的文件：这个版本用哪份 Node（绝对路径一行）。回退版本时 Node 跟着一起回退 */
+export const NODE_PATH_FILE = 'node-path';
+/** 版本目录内 connect 包的位置（npm tarball 解开后的 `package/` 改名而来） */
+export function connectPackageDir(versionDir) {
+    return join(versionDir, 'node_modules', '@m2canvas', 'connect');
+}
+export function connectCliPath(versionDir) {
+    return join(connectPackageDir(versionDir), 'dist', 'cli.js');
+}

package/dist/bridge/instance.js

@@ -34,7 +34,12 @@ export function instanceFilePath(m2Dir, port) {
 export function processStartedAt() {
     return Math.round(Date.now() - process.uptime() * 1000);
 }
-/** 只写这四个字段：调用方多带的任何字段都不落盘（契约 2：文件里不能有配对码、token、承诺） */
+/**
+ * 只写这四个字段：调用方多带的任何字段都不落盘（契约 2：文件里不能有配对码、token、承诺）。
+ * 这也是跨版本接口：用户机器上的启动器 `~/.m2canvas/bin/m2-bridge` 只随重装更新，它按「JSON 对象里的 "pid"」核对
+ * 拉起的是不是这个进程（change acp-bridge-one-time-install review r1 R1-S2）。改格式前先确认已装出去的启动器仍认得，
+ * `install-launcher-real.test.ts` 用真实 bridge 锁住了这一点。
+ */
 export function writeInstanceRecord(path, record) {
     const { pid, port, startedAt } = record;
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
@@ -217,6 +222,7 @@ export async function listenWithReplace(listen, ctx) {
         return null;
     }
     if (!ctx.replace) {
+        ctx.alreadyRunning?.(running);
         const stopIt = running.terminal ? `press Ctrl+C in that terminal or run "kill ${running.pid}"` : `stop it with "kill ${running.pid}"`;
         ctx.error(`Port ${ctx.port} is already in use by another M2 bridge (${describe(running, ctx.clock)}).\n` +
             `To start this one instead, ${stopIt}, then run this command again. Or run it again with --replace to stop that bridge first.`);

package/dist/bridge/main.js

@@ -5,6 +5,10 @@
  *
  * 本文件负责组装与终端交互：参数、启动横幅、配对码打印、信号处理、退出兜底清理。协议在 server.ts，安全判定在 security.ts / pairing.ts。
  * 终端输出用英文，与 connect 现有输出一致。
+ *
+ * 后台模式（`--background`，只由启动器 `~/.m2canvas/bin/m2-bridge` 使用，change acp-bridge-one-time-install）：输出写进日志文件，
+ * 所以不出配对码（契约 2）、不提示「保持窗口打开」；页面经 `welcome.bridge.background` 得知，改走「重新连接」。
+ * 端口上已有认定的 M2 bridge 时以 EXIT_ALREADY_RUNNING 退出，启动器把它当成功。
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -19,11 +23,33 @@ import { createLsofProbe, createPsProbe, createStopDeps, identifyRunningBridge,
 import { installShutdownSignals } from './lifecycle.js';
 import { PairingManager, createFilePairingStore, isPairCommitment } from './pairing.js';
 import { BRIDGE_AGENT_IDS, BRIDGE_DEFAULT_PORT, BRIDGE_WS_PATH } from './protocol.js';
+import { resolveNpmCommand } from './npm-command.js';
 import { DEV_ORIGINS, PROD_ORIGINS, allowedOrigins } from './security.js';
+import { selfTestProblems } from './self-test.js';
+import { runCheckUpdate } from './update-io.js';
 import { startBridgeServer } from './server.js';
 import { createAgentService } from './service.js';
 import { KILL_GRACE_MS } from './processes.js';
 const NPM_CI_TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * 后台模式下，端口上已有认定的 M2 bridge、又没带 `--replace` 时的退出码（change acp-bridge-one-time-install R1）。
+ * 启动器把它当「已在运行」（成功）；认不出的占用者、停不掉等失败仍是 1，不能并进来。终端模式不用它（照旧 1）。
+ */
+export const EXIT_ALREADY_RUNNING = 3;
+/**
+ * 后台模式下，端口被占、又认不出占用者是 M2 bridge（或 `--replace` 停不掉旧的、停掉后端口仍被占）时的退出码（review r1 R1-S1）。
+ * 这些都是环境问题，不是这个版本坏了：启动器据此**不回退、不拉黑**刚更新的版本，只把原因写进结果行。终端模式仍是 1。
+ */
+export const EXIT_PORT_UNAVAILABLE = 4;
+/**
+ * 后台模式加 `--dev`（本机开发页联调用，design R6）时的寿命（review r1 R1-S6，用户 2026-10-05 拍板）。
+ * 开发域名的 Origin 与 localStorage 被本机所有 Vite 项目共用，契约 1 因此只在 `--dev` 时放行、且否决了「常开」；
+ * 后台 bridge 没有终端、一直运行到注销，不限时就等于常开。到时走正常收尾退出，需要时再用启动器拉起。
+ */
+export const DEV_BACKGROUND_LIFETIME_MS = 2 * 60 * 60 * 1000;
+export function backgroundLifetimeMs(args) {
+    return args.background && args.dev ? DEV_BACKGROUND_LIFETIME_MS : null;
+}
 const LABELS = {
     claude: 'Claude Code',
     codex: 'Codex',
@@ -56,10 +82,19 @@ your browser.
                   stop it first (its agent sessions end) and start this one instead;
                   not on Windows
   --unpair        forget all paired pages and exit
-  -h, --help      show this help`;
+  -h, --help      show this help
+
+Internal (used by the M2 launcher ~/.m2canvas/bin/m2-bridge; don't run these yourself):
+  --background    run without a terminal: no pairing codes are shown; exits with
+                  code ${EXIT_ALREADY_RUNNING} if an M2 bridge is already running on the port, ${EXIT_PORT_UNAVAILABLE} if
+                  something else holds the port; with --dev it stops by itself after 2 hours
+  --check-update  update this installation to the version M2 publishes, then exit
+  --self-test     check that this installation loads completely, print its version and exit
+  --stop          stop the M2 bridge running on the port (only one it can recognize; it's
+                  sent SIGTERM so it cleans up), then exit`;
 /** 解析 `bridge` 之后的参数；返回字符串表示参数错误（调用方连同帮助打印、退出码 2）。 */
 export function parseBridgeArgs(argv) {
-    const args = { port: BRIDGE_DEFAULT_PORT, cwd: process.cwd(), verbose: false, unpair: false, help: false, dev: false, pair: null, replace: false };
+    const args = { port: BRIDGE_DEFAULT_PORT, cwd: process.cwd(), verbose: false, unpair: false, help: false, dev: false, pair: null, replace: false, background: false, selfTest: false, checkUpdate: false, stop: false };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '-h' || arg === '--help')
@@ -72,6 +107,14 @@ export function parseBridgeArgs(argv) {
             args.dev = true;
         else if (arg === '--replace')
             args.replace = true;
+        else if (arg === '--background')
+            args.background = true;
+        else if (arg === '--self-test')
+            args.selfTest = true;
+        else if (arg === '--check-update')
+            args.checkUpdate = true;
+        else if (arg === '--stop')
+            args.stop = true;
         else if (arg === '--pair') {
             const value = argv[++i];
             if (value === undefined)
@@ -141,6 +184,22 @@ function describeAdapter(agent, info) {
         return `Installing the ${name} failed: ${info.error ?? 'unknown error'}`;
     return null;
 }
+/**
+ * `--stop`：卸载脚本先停掉正在运行的 bridge（change acp-bridge-one-time-install D23 ①）。
+ * 认定与停止都复用契约 13 的实现（instance.ts）：只停认定的 M2 bridge，只发 SIGTERM（走它自己的清理），认不出就什么都不停。
+ * 不在卸载脚本里用 sh 再写一遍认定（要用 `ps` 推算启动时刻，两份实现会漂；理由同 design R1）。
+ */
+async function stopRecognizedBridge(port) {
+    const probeEnv = buildProbeEnv();
+    const running = await identifyRunningBridge(instanceFilePath(join(home, '.m2canvas'), port), port, createPsProbe(execCommand, probeEnv), process.platform);
+    if (!running) {
+        console.log(`No M2 bridge that this version can recognize is running on port ${port}; nothing was stopped.`);
+        return 0;
+    }
+    const stopped = await stopRunningBridge(running.pid, createStopDeps(execCommand, probeEnv));
+    console.log(stopped ? `Stopped the M2 bridge on port ${port} (pid ${running.pid}).` : `The M2 bridge on port ${port} (pid ${running.pid}) didn't stop.`);
+    return stopped ? 0 : 1;
+}
 export async function runBridge(argv) {
     const parsed = parseBridgeArgs(argv);
     if (typeof parsed === 'string') {
@@ -151,6 +210,20 @@ export async function runBridge(argv) {
         console.log(BRIDGE_HELP);
         return 0;
     }
+    if (parsed.selfTest) {
+        const version = packageVersion();
+        const problems = selfTestProblems({ packageRoot: PACKAGE_ROOT, execPath: process.execPath, version });
+        if (problems.length > 0) {
+            console.error(`M2 bridge self-test failed: ${problems.join('; ')}`);
+            return 1;
+        }
+        console.log(`M2 bridge self-test ok ${version}`);
+        return 0;
+    }
+    if (parsed.checkUpdate)
+        return runCheckUpdate();
+    if (parsed.stop)
+        return stopRecognizedBridge(parsed.port);
     const m2Dir = join(home, '.m2canvas');
     const store = createFilePairingStore(join(m2Dir, 'bridge-pairings.json'), (message) => console.warn(message));
     if (parsed.unpair) {
@@ -164,11 +237,14 @@ export async function runBridge(argv) {
     }
     const log = (message) => console.log(`[${new Date().toLocaleTimeString()}] ${message}`);
     const probeEnv = buildProbeEnv();
-    const npm = which('npm') ?? (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    // 后台模式用私有 Node 自带的 npm（目标用户 PATH 上可能根本没有 npm，R3）；终端模式照旧用 PATH 上的
+    const npm = resolveNpmCommand({ background: parsed.background, execPath: process.execPath, platform: process.platform, which });
     let server = null;
     // 配对锁定只能靠重启 bridge 解除：bridge 不读终端（放到后台时读终端会被系统挂起），页面也没有任何途径解锁
     const pairing = new PairingManager({
         store,
+        // 后台模式没有终端、输出写进日志文件：不出码（契约 2「码只出现在终端」），配对只剩命令承诺与已有 token（D17 / D18）
+        issueCodes: !parsed.background,
         onCodeIssued: printCode,
         onLocked: printLocked,
         onProblem: (message) => console.warn(message),
@@ -181,13 +257,15 @@ export async function runBridge(argv) {
     const adapters = new AdapterManager({
         sourceRoot: join(PACKAGE_ROOT, 'adapters'),
         installRoot: join(m2Dir, 'acp-adapters'),
-        runNpmCi: (dir) => execCommand(npm, ['ci', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'], {
-            cwd: dir,
-            env: buildNpmEnv(),
-            timeoutMs: NPM_CI_TIMEOUT_MS,
-            maxOutput: 64 * 1024,
-            shell: process.platform === 'win32',
-        }),
+        runNpmCi: (dir) => 'error' in npm
+            ? Promise.reject(new Error(npm.error))
+            : execCommand(npm.command, [...npm.prefix, 'ci', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'], {
+                cwd: dir,
+                env: buildNpmEnv(),
+                timeoutMs: NPM_CI_TIMEOUT_MS,
+                maxOutput: 64 * 1024,
+                shell: npm.shell,
+            }),
         onState: (agent, info) => {
             if (loggedState.get(agent) !== info.state) {
                 loggedState.set(agent, info.state);
@@ -216,10 +294,18 @@ export async function runBridge(argv) {
     const origins = allowedOrigins(parsed.dev);
     // 端口被占时认出正在运行的 M2 bridge，给出 pid 与终端，或在 --replace 时接管（D20）。状态文件不含任何密钥
     const instancePath = instanceFilePath(m2Dir, parsed.port);
+    let alreadyRunning = false;
     server = await listenWithReplace(() => startBridgeServer({
         port: parsed.port,
         cwd: parsed.cwd,
-        bridge: { name: '@m2canvas/connect', version, platform: process.platform, arch: process.arch, node: process.versions.node },
+        bridge: {
+            name: '@m2canvas/connect',
+            version,
+            platform: process.platform,
+            arch: process.arch,
+            node: process.versions.node,
+            ...(parsed.background ? { background: true } : {}),
+        },
         pairing,
         service,
         agentEnv: buildAgentEnv(),
@@ -236,9 +322,13 @@ export async function runBridge(argv) {
         log,
         error: (message) => console.error(message),
         clock,
+        alreadyRunning: () => {
+            alreadyRunning = true;
+        },
     });
+    // listenWithReplace 返回 null 的情况都与端口有关（已在运行、被别的程序占着、停不掉旧的）；后台模式把「已在运行」与其余分开
     if (!server)
-        return 1;
+        return parsed.background ? (alreadyRunning ? EXIT_ALREADY_RUNNING : EXIT_PORT_UNAVAILABLE) : 1;
     const running = server;
     try {
         // startedAt 必须是进程启动时刻：--replace 时要等旧的退出后才写，取写文件时刻会晚出几百毫秒到几秒，下一次 --replace 就认不出它
@@ -293,6 +383,13 @@ export async function runBridge(argv) {
             process.exit(130);
         },
     });
+    const lifetime = backgroundLifetimeMs(parsed);
+    if (lifetime !== null) {
+        setTimeout(() => {
+            log('Dev mode in the background reached its 2-hour limit; stopping. Start it again with ~/.m2canvas/bin/m2-bridge if you still need it.');
+            void stop();
+        }, lifetime);
+    }
     console.log(`M2 local agent bridge ${version}`);
     console.log(`  Listening on ws://127.0.0.1:${running.port}${BRIDGE_WS_PATH} (this machine only)`);
     console.log(`  Working directory for agents: ${parsed.cwd}`);
@@ -301,12 +398,17 @@ export async function runBridge(argv) {
         console.log('  --dev: any app on the dev port can ask to pair. Only enter the code into your own M2 dev server.');
     // 带 --pair（命令是从 M2 页面复制的）：主路径上用户不需要启动码，打印出来反而让人以为要去输码；
     // 页面对不上承诺时会以未配对状态连上，那时照常出码并带上发起方 Origin
+    if (parsed.background)
+        console.log('  Started in the background by the M2 launcher: no pairing codes are shown; pair from M2 with a new start command.');
+    if (lifetime !== null)
+        console.log(`  Dev mode in the background: stops by itself at ${clock(Date.now() + lifetime)}.`);
     if (pairUntil !== null)
         console.log(`  Waiting for the M2 page that gave you this command (until ${clock(pairUntil)})…`);
-    else
+    else if (!parsed.background)
         pairing.issueCode('startup');
     const found = await Promise.all(BRIDGE_AGENT_IDS.map(detect));
     console.log(`  Agents: ${found.map((agent) => `${LABELS[agent.id]} ${agent.installed ? '✓' : '–'}`).join('   ')}`);
-    console.log('  Keep this window open while you use local agents in M2. Press Ctrl+C to stop.\n');
+    if (!parsed.background)
+        console.log('  Keep this window open while you use local agents in M2. Press Ctrl+C to stop.\n');
     return exited;
 }

package/dist/bridge/npm-command.js

@@ -0,0 +1,25 @@
+/**
+ * 适配器安装（`npm ci`）用哪个 npm（change acp-bridge-one-time-install R3）。
+ *
+ * - 终端模式（`npx @m2canvas/connect bridge`）：沿用 PATH 上的 npm —— 用户能运行 npx，就一定有 npm；不改既有行为。
+ * - 后台模式（`bridge --background`，由启动器用 `~/.m2canvas/runtime` 里的私有 Node 拉起）：目标用户往往根本没装 Node，
+ *   PATH 上没有 npm。必须用运行 bridge 的那份 Node（`process.execPath`）去跑同一 Node 包里的 `lib/node_modules/npm/bin/npm-cli.js`。
+ *   不能直接运行 `bin/npm`：它的 shebang 是 `#!/usr/bin/env node`，又会去 PATH 找 node。
+ *   找不到 npm-cli.js 就报错，**不退回 PATH 上的 npm**：那会让组件装进一份与 bridge 不同的 Node 环境里，失败时也更难查。
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** 官方 Node 二进制包的布局：`<prefix>/bin/node` 与 `<prefix>/lib/node_modules/npm/bin/npm-cli.js` */
+export function bundledNpmCli(execPath) {
+    return join(dirname(execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js');
+}
+export function resolveNpmCommand(input) {
+    if (input.background) {
+        const cli = bundledNpmCli(input.execPath);
+        if (!(input.exists ?? existsSync)(cli))
+            return { error: `npm was not found next to this bridge's Node.js (${cli}); reinstall the M2 local connection` };
+        return { command: input.execPath, prefix: [cli], shell: false };
+    }
+    const windows = input.platform === 'win32';
+    return { command: input.which('npm') ?? (windows ? 'npm.cmd' : 'npm'), prefix: [], shell: windows };
+}

package/dist/bridge/pair-call.js

@@ -0,0 +1,31 @@
+/**
+ * bridge 方法 `pair`（页面输码换 token）：校验参数、调用 PairingManager.pair、把失败映射成页面看得懂的错误码。
+ * 只负责「这次输码对不对」；配对成功后把连接标为已配对、记日志、回 cwd 由 server.ts 负责（连接状态只在那里改）。
+ *
+ * 错误码的语义是页面协议的一部分（`protocol.ts` 的 BridgeErrorCode，`connect/local-bridge` 契约 9）：
+ * - pairing_invalid：错码，带剩余次数；
+ * - pairing_code_rotated：码过期或错太多次被换掉，新码已打印在终端；
+ * - pairing_locked：累计错码太多，只有重启 bridge 才解除；
+ * - pairing_code_unavailable：后台模式（`bridge --background`）根本不出码，页面要改走「重新连接」（change acp-bridge-one-time-install D17）。
+ * 不要把后两种并进 pairing_code_rotated：页面据此决定是让用户看终端，还是让 agent 重新拉起 bridge。
+ */
+import { BridgeFailure } from './errors.js';
+/** 成功时返回新签发的 token；失败抛 BridgeFailure */
+export function handlePairCall(pairing, origin, params) {
+    const code = params.code;
+    if (typeof code !== 'string')
+        throw new BridgeFailure('bad_message', 'pair needs a string "code"');
+    const result = pairing.pair(code, origin);
+    if (result.ok)
+        return result.token;
+    switch (result.code) {
+        case 'pairing_invalid':
+            throw new BridgeFailure('pairing_invalid', 'wrong pairing code', { attemptsLeft: result.attemptsLeft });
+        case 'pairing_locked':
+            throw new BridgeFailure('pairing_locked', 'too many wrong pairing codes; new pages cannot pair until the bridge is restarted');
+        case 'pairing_code_unavailable':
+            throw new BridgeFailure('pairing_code_unavailable', 'this bridge was started in the background and shows no pairing code; reconnect from M2 to pair');
+        case 'pairing_code_rotated':
+            throw new BridgeFailure('pairing_code_rotated', 'pairing code expired or used up; a new one is shown in the terminal');
+    }
+}

package/dist/bridge/pairing.js

@@ -18,6 +18,9 @@
  *   不要为了「方便」放宽次数、延长有效期或加一个页面能触发的解锁：码是唯一挡住本机恶意页面的东西。
  *   也不要改成「在终端按回车解锁」：那需要读终端，而 bridge 放到后台（`… bridge &`）时读终端会被系统挂起（review r2 实测）。
  * - 比较用常量时间（timingSafeEqual），不要改回 ===。
+ * - 后台模式（`issueCodes: false`，`bridge --background`，change acp-bridge-one-time-install D17）不出码：没有终端，stdout 写的是日志文件，
+ *   出码就等于把码写盘。这时 `issueCode` / `ensureCode` 什么都不做，`pair` 一律 pairing_code_unavailable，配对只剩命令承诺与已有 token。
+ *   不要给后台模式另开出码通道（文件、系统对话框）：「把码写进文件」已被否决过（`connect/local-bridge` 契约 2 / 13）。
  */
 import { createHash, randomBytes, randomInt, randomUUID, timingSafeEqual } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -84,6 +87,7 @@ export class PairingManager {
     lastPrompt = new Map();
     store;
     now;
+    issueCodes;
     onCodeIssued;
     onLocked;
     onProblem;
@@ -91,13 +95,16 @@ export class PairingManager {
     constructor(options) {
         this.store = options.store;
         this.now = options.now ?? Date.now;
+        this.issueCodes = options.issueCodes ?? true;
         this.onCodeIssued = options.onCodeIssued;
         this.onLocked = options.onLocked ?? (() => undefined);
         this.onProblem = options.onProblem ?? (() => undefined);
         this.onCommitmentReused = options.onCommitmentReused ?? (() => undefined);
     }
-    /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式 */
+    /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式；后台模式不出码，返回 null */
     issueCode(reason, origin = null) {
+        if (!this.issueCodes)
+            return null;
         let code = '';
         for (let i = 0; i < CODE_LENGTH; i++)
             code += ALPHABET[randomInt(ALPHABET.length)];
@@ -118,10 +125,10 @@ export class PairingManager {
      * 未配对页面连上时调用。没有有效码就出新码；有有效码也把它连同发起方 Origin 再提示一次 ——
      * 最常见的首次流程是「启动 bridge 后马上打开页面」，终端里只有一个不带 Origin 的启动码，
      * 不再提示的话用户看不到是哪个页面在请求配对。同一 Origin、同一个码一分钟内只提示一次（页面重连不刷屏）。
-     * 锁定期间什么都不做。
+     * 锁定期间、后台模式下什么都不做。
      */
     ensureCode(origin) {
-        if (this.locked)
+        if (this.locked || !this.issueCodes)
             return;
         if (!this.hasValidCode() || !this.active) {
             this.issueCode('requested', origin);
@@ -141,6 +148,9 @@ export class PairingManager {
      * （review r1 实测 1.6 秒 20000 次），还会让陌生页面把用户的配对码一直刷掉。
      */
     pair(input, origin) {
+        // 后台模式没有码可比：在锁定检查之前返回，也不计入错码次数（页面并没有猜码，只是不知道这个 bridge 不出码）
+        if (!this.issueCodes)
+            return { ok: false, code: 'pairing_code_unavailable' };
         if (this.locked)
             return { ok: false, code: 'pairing_locked' };
         if (!this.active) {

package/dist/bridge/release-manifest.js

@@ -0,0 +1,80 @@
+/**
+ * 更新清单 `https://m2ui.ai/connect/manifest.json` 的格式、解析与下载地址（change acp-bridge-one-time-install D13 / D14 / R7）。
+ *
+ * 清单由仓库的 `packages/connect/install/release.json` 生成，随 App 部署发布；部署 App 才是放量开关，发 npm 不等于推给所有用户。
+ * 清单**只提供版本号与哈希**：下载地址在这里由版本号拼出，固定指向官方源与 npmmirror。
+ * 不要在清单里加 URL 字段 —— 那会让清单（或篡改清单的人）把下载指到任意地方，信任根就不止 m2ui.ai 加哈希了。
+ *
+ * 跨版本兼容：已安装的旧版本 bridge 会读新部署的清单（`--check-update` 跑的是当前版本的代码）。
+ * - 同一 `schema` 内只加字段；本解析器忽略不认识的字段。
+ * - 要改语义就升 `schema`；旧版本认不出新 schema 时按「读清单失败」处理，用当前版本继续（不会误装）。
+ * - 版本号与哈希一律严格校验格式：它们会进入文件路径与下载地址。
+ */
+export const MANIFEST_URL = 'https://m2ui.ai/connect/manifest.json';
+export const MANIFEST_SCHEMA = 1;
+/** 只认纯 x.y.z（不接受预发布、构建元数据）：版本号会拼进目录名与下载地址 */
+const VERSION_RE = /^\d{1,4}\.\d{1,4}\.\d{1,6}$/;
+const SHA512_RE = /^[0-9a-f]{128}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+export function isReleaseVersion(value) {
+    return typeof value === 'string' && VERSION_RE.test(value);
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+}
+function pinned(value, hash) {
+    const entry = record(value);
+    if (!entry || !isReleaseVersion(entry.version) || typeof entry.sha512 !== 'string' || !hash.test(entry.sha512))
+        return null;
+    return { version: entry.version, sha512: entry.sha512 };
+}
+/** 解析清单正文；格式不对时返回原因（英文，写进 update.log） */
+export function parseReleaseManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return 'manifest is not valid JSON';
+    }
+    const root = record(parsed);
+    if (!root)
+        return 'manifest is not a JSON object';
+    if (root.schema !== MANIFEST_SCHEMA)
+        return `unsupported manifest schema ${JSON.stringify(root.schema)}`;
+    const connect = pinned(root.connect, SHA512_RE);
+    if (!connect)
+        return 'manifest has no valid connect version / sha512';
+    const ws = pinned(root.ws, SHA512_RE);
+    if (!ws)
+        return 'manifest has no valid ws version / sha512';
+    const node = record(root.node);
+    const sha256 = record(node?.sha256);
+    const arm64 = sha256?.arm64;
+    const x64 = sha256?.x64;
+    if (!node || !isReleaseVersion(node.version) || typeof arm64 !== 'string' || !SHA256_RE.test(arm64) || typeof x64 !== 'string' || !SHA256_RE.test(x64)) {
+        return 'manifest has no valid node version / sha256';
+    }
+    return { schema: MANIFEST_SCHEMA, connect, ws, node: { version: node.version, sha256: { arm64, x64 } } };
+}
+/**
+ * 下载源：官方优先，失败（含校验不符）再退 npmmirror（D14）。顺序有意义，不要打乱。
+ * 安装脚本的生成块用的是同一组基址（src/install/assets.ts），两边只此一处。
+ */
+export const NPM_REGISTRY_BASES = ['https://registry.npmjs.org', 'https://registry.npmmirror.com'];
+export const NODE_DIST_BASES = ['https://nodejs.org/dist', 'https://npmmirror.com/mirrors/node'];
+export function connectTarballUrls(version) {
+    return NPM_REGISTRY_BASES.map((base) => `${base}/@m2canvas/connect/-/connect-${version}.tgz`);
+}
+export function wsTarballUrls(version) {
+    return NPM_REGISTRY_BASES.map((base) => `${base}/ws/-/ws-${version}.tgz`);
+}
+/** 私有 Node 的目录名，也是官方包解开后的顶层目录名 */
+export function nodeDirName(version, arch) {
+    return `node-v${version}-darwin-${arch}`;
+}
+/** `.tar.xz`：只有 `.tar.gz` 的一半大小，macOS 自带的 bsdtar 能解（R9） */
+export function nodeTarballUrls(version, arch) {
+    const file = `${nodeDirName(version, arch)}.tar.xz`;
+    return NODE_DIST_BASES.map((base) => `${base}/v${version}/${file}`);
+}

package/dist/bridge/self-test.js

@@ -0,0 +1,30 @@
+/**
+ * `bridge --self-test`：自动更新时对新版本的冒烟测试（change acp-bridge-one-time-install D20 ④、N4）。
+ *
+ * 当前版本的 `--check-update` 用新版本自己的 Node 运行新版本的 cli.js。能走到这里，说明 cli.js → bridge/main.js
+ * 及其全部静态依赖（含 ws）都加载成功；这里再核对几种「能加载、但装得不全」的情况，任何一项不满足就退出 1，
+ * 更新流程就不会切换到这个版本。
+ *
+ * 不监听端口、不写文件、不联网：它在旧版本 bridge 还在运行时执行。
+ * 检测不到「起来了但功能坏了」（例如协议处理有 bug）：那种情况靠改清单回滚（`connect/local-bridge` 契约 16 delta）。
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ADAPTERS } from './adapters.js';
+import { bundledNpmCli } from './npm-command.js';
+/** 返回发现的问题（英文，写进 update.log）；空数组 = 通过 */
+export function selfTestProblems(input) {
+    const exists = input.exists ?? existsSync;
+    const problems = [];
+    if (!/^\d+\.\d+\.\d+/.test(input.version) || input.version === '0.0.0')
+        problems.push(`unreadable package version (${input.version})`);
+    for (const spec of Object.values(ADAPTERS)) {
+        const lock = join(input.packageRoot, 'adapters', spec.dir, 'package-lock.json');
+        if (!exists(lock))
+            problems.push(`missing ${lock}`);
+    }
+    const npm = bundledNpmCli(input.execPath);
+    if (!exists(npm))
+        problems.push(`missing ${npm}`);
+    return problems;
+}

package/dist/bridge/server.js

@@ -22,6 +22,7 @@ import { TOKEN_IDLE_DAYS } from './pairing.js';
 import { ProcessError, ProcessManager } from './processes.js';
 import { isBridgeAgentId } from './agents.js';
 import { handleAuthCall } from './auth-call.js';
+import { handlePairCall } from './pair-call.js';
 import { AuthorizationManager } from './authorize.js';
 import { BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
 import { checkPageAcpLine } from './acp-guard.js';
@@ -105,20 +106,10 @@ export function startBridgeServer(options) {
     };
     async function handleCall(conn, id, method, params) {
         if (method === 'pair') {
-            const code = params.code;
-            if (typeof code !== 'string')
-                throw new BridgeFailure('bad_message', 'pair needs a string "code"');
-            const result = options.pairing.pair(code, conn.origin);
-            if (!result.ok) {
-                if (result.code === 'pairing_invalid')
-                    throw new BridgeFailure('pairing_invalid', 'wrong pairing code', { attemptsLeft: result.attemptsLeft });
-                if (result.code === 'pairing_locked')
-                    throw new BridgeFailure('pairing_locked', 'too many wrong pairing codes; new pages cannot pair until the bridge is restarted');
-                throw new BridgeFailure('pairing_code_rotated', 'pairing code expired or used up; a new one is shown in the terminal');
-            }
+            const token = handlePairCall(options.pairing, conn.origin, params);
             markPaired(conn);
             log(`Paired with ${conn.origin}.`);
-            return { token: result.token, cwd: options.cwd, idleExpiryDays: TOKEN_IDLE_DAYS };
+            return { token, cwd: options.cwd, idleExpiryDays: TOKEN_IDLE_DAYS };
         }
         if (!conn.paired)
             throw new BridgeFailure('not_paired', 'pair this page first');

package/dist/bridge/update-io.js

@@ -0,0 +1,118 @@
+/**
+ * `bridge --check-update` 的真实 IO 与命令入口（change acp-bridge-one-time-install D20、R7）。更新的判断都在 update.ts，这里只做外部调用：
+ * - 读清单、下载：一律 `/usr/bin/curl`。安装脚本也用 curl，两边代理行为相同 —— curl 读 HTTPS_PROXY / ALL_PROXY / NO_PROXY 与
+ *   `~/.curlrc`，Node 的 fetch 默认不读代理变量。`-f`：HTTP 错误码当失败，不把错误页写成「下载好的文件」。
+ * - 解压：`/usr/bin/tar`（macOS 的 bsdtar 自带 xz；内容已按清单哈希校验过）。
+ * - 冒烟：用新版本自己的 Node 跑新版本的 `cli.js bridge --self-test`。
+ * 子进程环境由调用方给：生产用 env.ts 的白名单（代理与证书变量都在里面），不把宿主注入的变量带给 curl。
+ *
+ * 不提供清单地址、下载地址的覆盖参数或环境变量（design R8）：测试经 UpdateDeps 注入，或直接对本模块的原语传本机地址。
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { home } from '../system.js';
+import { buildAgentEnv } from './env.js';
+import { combinedOutput, execCommand } from './exec.js';
+import { installLayout } from './install-layout.js';
+import { tail } from './precheck-parse.js';
+import { checkForUpdate } from './update.js';
+const CURL = '/usr/bin/curl';
+const TAR = '/usr/bin/tar';
+/** 单个文件的下载上限：Node 包约 27MB，慢网（约 100KB/s）也要下得完 */
+const DOWNLOAD_TIMEOUT_MS = 10 * 60 * 1000;
+const EXTRACT_TIMEOUT_MS = 2 * 60 * 1000;
+/** 冒烟时限（D20 ④） */
+const SELF_TEST_TIMEOUT_MS = 20_000;
+/** update.log 超过这个大小先轮转成 `.1`（每次启动只写几行，很少触发） */
+const UPDATE_LOG_MAX_BYTES = 1024 * 1024;
+function failure(what, result) {
+    const reason = result.timedOut ? 'timed out' : result.code === null ? (result.error ?? 'did not start') : `exited ${result.code}`;
+    const output = tail(combinedOutput(result).trim());
+    return new Error(`${what} ${reason}${output ? `: ${output}` : ''}`);
+}
+export function createUpdateIO(options) {
+    const { exec, env } = options;
+    return {
+        async fetchText(url, timeoutMs) {
+            const seconds = String(Math.max(1, Math.ceil(timeoutMs / 1000)));
+            const result = await exec(CURL, ['-fsSL', '--connect-timeout', '5', '--max-time', seconds, url], { env, timeoutMs: timeoutMs + 2_000, maxOutput: 256 * 1024 });
+            if (result.code !== 0)
+                throw failure('curl', result);
+            return result.stdout;
+        },
+        async download(url, dest) {
+            const seconds = String(DOWNLOAD_TIMEOUT_MS / 1000);
+            // 低于 10KB/s 持续 30 秒就放弃、换下一个源：官方源只有涓流速度时不能拖到总时限（review r1 R1-S4，与安装脚本相同）
+            const result = await exec(CURL, ['-fsSL', '--connect-timeout', '10', '--speed-limit', '10240', '--speed-time', '30', '--max-time', seconds, '-o', dest, url], {
+                env,
+                timeoutMs: DOWNLOAD_TIMEOUT_MS + 5_000,
+                maxOutput: 16 * 1024,
+            });
+            if (result.code !== 0) {
+                // curl 失败时可能留下半截或空文件：删掉，免得被当成下载好的内容
+                rmSync(dest, { force: true });
+                throw failure('curl', result);
+            }
+        },
+        async extract(archive, dir) {
+            const result = await exec(TAR, ['-xf', archive, '-C', dir], { env, timeoutMs: EXTRACT_TIMEOUT_MS, maxOutput: 16 * 1024 });
+            if (result.code !== 0)
+                throw failure('tar', result);
+        },
+        async selfTest(nodePath, cliPath) {
+            const result = await exec(nodePath, [cliPath, 'bridge', '--self-test'], { env, timeoutMs: SELF_TEST_TIMEOUT_MS, maxOutput: 16 * 1024 });
+            return { ok: result.code === 0, output: result.timedOut ? `self-test timed out after ${SELF_TEST_TIMEOUT_MS / 1000}s` : combinedOutput(result) };
+        },
+    };
+}
+/** 追加一行到 `logs/update.log`（目录 0700、文件 0600，与 bridge.log 相同）；超过上限先轮转 */
+export function appendUpdateLog(layout, line, maxBytes = UPDATE_LOG_MAX_BYTES) {
+    mkdirSync(layout.logs, { recursive: true, mode: 0o700 });
+    chmodSync(layout.logs, 0o700);
+    if (existsSync(layout.updateLog) && statSync(layout.updateLog).size > maxBytes)
+        renameSync(layout.updateLog, `${layout.updateLog}.1`);
+    appendFileSync(layout.updateLog, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+    chmodSync(layout.updateLog, 0o600);
+}
+function describeOutcome(outcome) {
+    switch (outcome.kind) {
+        case 'unsupported':
+            return 'skipped (only macOS is supported)';
+        case 'not_installed':
+            return 'skipped (not installed by the M2 installer)';
+        case 'manifest_failed':
+            return `kept the current version (couldn't read the manifest: ${outcome.reason})`;
+        case 'up_to_date':
+            return `up to date (${outcome.version})`;
+        case 'rejected':
+            return `kept the current version (${outcome.version} failed to start before)`;
+        case 'failed':
+            return `kept the current version (update to ${outcome.version} failed: ${outcome.reason})`;
+        case 'updated':
+            return `updated ${outcome.from} -> ${outcome.to}`;
+    }
+}
+/**
+ * 命令入口（由启动器调用）。日志写进 update.log；标准输出只打一行摘要（启动器把它追加进 bridge.log）。
+ * 退出码只供排障：启动器不论成败都用 current 继续，是否刚切换过版本由它自己比较 current 的前后指向得出。
+ */
+export async function runCheckUpdate() {
+    const layout = installLayout(home);
+    const io = createUpdateIO({ exec: execCommand, env: buildAgentEnv() });
+    const outcome = await checkForUpdate({
+        layout,
+        platform: process.platform,
+        arch: process.arch,
+        ...io,
+        log: (line) => {
+            try {
+                appendUpdateLog(layout, line);
+            }
+            catch {
+                // 日志写不进（磁盘满、权限）不能拦住更新判断；摘要仍会打到标准输出
+            }
+        },
+        now: Date.now,
+    });
+    console.log(`M2 bridge update: ${describeOutcome(outcome)}`);
+    return outcome.kind === 'failed' || outcome.kind === 'manifest_failed' ? 1 : 0;
+}

package/dist/bridge/update.js

@@ -0,0 +1,365 @@
+/**
+ * `bridge --check-update`：启动器每次拉起 bridge 之前调用（change acp-bridge-one-time-install D9 / D13 / D14 / D20）。
+ * 运行它的是**当前版本**的代码；它把新版本下载、校验、冒烟后切成 current，下一步由启动器用新版本拉起。
+ *
+ * 不变量（`connect/local-bridge` 契约 16 delta）：
+ * - 只更新到 m2ui.ai 清单指定的版本（清单版本比当前低也照做，这就是回滚），不跟随 npm latest；
+ * - 清单只给版本与哈希，下载地址由 release-manifest.ts 固定拼出；任何下载内容与清单哈希不符都换下一个源，全部不符就放弃；
+ * - 读清单失败、超时、格式认不出：什么都不改，用当前版本继续；
+ * - 新版本先冒烟（`--self-test`），通过才切换；切换用「先建临时软链再改名」，任何时刻 current 都指向一个完整的版本；
+ * - 「新版本拉起后没起来」的回退不在这里：新版本可能连模块都加载不了，回退判定在很少改动的启动器里（契约 16 delta）；
+ * - 不加清单地址、下载地址的覆盖开关：那会让「只读 m2ui.ai 清单」多出一条旁路（design R8）。测试经 UpdateDeps 注入下载。
+ *
+ * 并发（design N1）：不加锁。所有写入先写临时目录 / 临时软链再改名；两个更新同时跑时各自下到自己的临时目录，
+ * 后完成的发现版本目录已完整就丢掉自己的，发现 current 已经切好就不再切。
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { ADAPTERS, ADAPTER_READY_MARKER, adapterInstallDirName } from './adapters.js';
+import { NODE_PATH_FILE, connectCliPath, connectPackageDir } from './install-layout.js';
+import { readInstanceRecord } from './instance.js';
+import { tail } from './precheck-parse.js';
+import { MANIFEST_URL, connectTarballUrls, isReleaseVersion, nodeDirName, nodeTarballUrls, parseReleaseManifest, wsTarballUrls, } from './release-manifest.js';
+/** 读清单的总时限（不含下载）：读不到就用当前版本继续，不能拖住启动（D20 ①） */
+export const MANIFEST_TIMEOUT_MS = 10_000;
+/** 临时目录超过这个时长就当作被杀掉的更新留下的残留（正在进行的更新不会这么久） */
+const STALE_TEMP_MS = 60 * 60 * 1000;
+const NODE_DIR_RE = /^node-v\d+\.\d+\.\d+-darwin-(arm64|x64)$/;
+class UpdateError extends Error {
+}
+const message = (error) => (error instanceof Error ? error.message : String(error));
+const tempName = (label) => `.tmp-${label}-${process.pid}-${randomBytes(4).toString('hex')}`;
+/** current / previous 软链指向的版本号；软链不在、内容不是版本号时为 null */
+function readVersionLink(path) {
+    try {
+        const target = readlinkSync(path);
+        return isReleaseVersion(target) ? target : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 启动器写入的拉黑名单：每行一个版本号，其他内容忽略 */
+export function readRejected(path) {
+    try {
+        return readFileSync(path, 'utf8')
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(isReleaseVersion);
+    }
+    catch {
+        return [];
+    }
+}
+function readNodePath(versionDir) {
+    try {
+        const value = readFileSync(join(versionDir, NODE_PATH_FILE), 'utf8').trim();
+        return value || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 版本目录是否完整：node-path、connect 的 cli.js、ws 都在 */
+function isCompleteVersion(dir) {
+    return readNodePath(dir) !== null && existsSync(connectCliPath(dir)) && existsSync(join(dir, 'node_modules', 'ws', 'package.json'));
+}
+/** 原子替换软链：先建临时软链再 rename 覆盖 */
+function swapLink(link, target) {
+    const tmp = `${link}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
+    symlinkSync(target, tmp);
+    renameSync(tmp, link);
+}
+/** 原子写小文件：先写临时文件再 rename */
+function writeFileAtomic(path, content) {
+    const tmp = `${path}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+}
+function fileHash(algorithm, path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash(algorithm);
+        createReadStream(path)
+            .on('error', reject)
+            .on('data', (chunk) => hash.update(chunk))
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}
+/** 依次试各个源（官方在前），下载失败或哈希不符都换下一个；全部不行就删掉 dest 并抛错 */
+async function fetchVerified(deps, urls, algorithm, expected, dest) {
+    const problems = [];
+    for (const url of urls) {
+        try {
+            await deps.download(url, dest);
+        }
+        catch (error) {
+            problems.push(`download ${url} failed: ${message(error)}`);
+            deps.log(problems[problems.length - 1] ?? '');
+            continue;
+        }
+        if ((await fileHash(algorithm, dest)) === expected) {
+            deps.log(`downloaded ${url} (${algorithm} ok)`);
+            return;
+        }
+        problems.push(`${algorithm} mismatch for ${url}`);
+        deps.log(problems[problems.length - 1] ?? '');
+    }
+    rmSync(dest, { force: true });
+    throw new UpdateError(problems.join('; '));
+}
+/** 清单要求的 Node 已在就直接用；否则下载、校验、解到临时目录再改名（D8 / R9） */
+async function ensureNode(deps, manifest, arch) {
+    const name = nodeDirName(manifest.node.version, arch);
+    const nodeDir = join(deps.layout.runtime, name);
+    const nodeBin = join(nodeDir, 'bin', 'node');
+    if (existsSync(nodeBin))
+        return nodeBin;
+    mkdirSync(deps.layout.runtime, { recursive: true });
+    if (existsSync(nodeDir)) {
+        // 残缺的旧目录（上次解到一半被打断）：挪开再装，不然改名会一直失败（review r1 R1-N3）；挪开的由之后的清理删除
+        renameSync(nodeDir, join(deps.layout.runtime, tempName('old-node')));
+        deps.log(`moved an incomplete ${name} aside`);
+    }
+    const tmp = join(deps.layout.runtime, tempName('node'));
+    mkdirSync(tmp);
+    try {
+        const archive = join(tmp, `${name}.tar.xz`);
+        await fetchVerified(deps, nodeTarballUrls(manifest.node.version, arch), 'sha256', manifest.node.sha256[arch], archive);
+        await deps.extract(archive, tmp);
+        if (!existsSync(join(tmp, name, 'bin', 'node')))
+            throw new UpdateError(`${name}.tar.xz has no bin/node`);
+        // 别的更新抢先装好了同一份 Node：用它的
+        if (!existsSync(nodeBin))
+            renameSync(join(tmp, name), nodeDir);
+        deps.log(`installed Node.js ${manifest.node.version} (${arch})`);
+        return nodeBin;
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** 解开 npm tarball（顶层目录 `package/`）并改名到 dest */
+async function unpackNpm(deps, archive, workDir, dest) {
+    const unpacked = join(workDir, `${basename(archive)}.d`);
+    mkdirSync(unpacked);
+    await deps.extract(archive, unpacked);
+    if (!existsSync(join(unpacked, 'package', 'package.json')))
+        throw new UpdateError(`${basename(archive)} has no package/package.json`);
+    mkdirSync(dirname(dest), { recursive: true });
+    renameSync(join(unpacked, 'package'), dest);
+    rmSync(unpacked, { recursive: true, force: true });
+    rmSync(archive, { force: true });
+}
+/**
+ * 准备目标版本目录：已完整存在（例如回滚到 previous）就复用，只把 node-path 对齐到清单的 Node；
+ * 否则在 `bridge/.tmp-*` 里组装（connect 与 ws 两个 tarball 就是完整的 bridge，D13），返回临时目录，由调用方冒烟后改名。
+ */
+async function prepareVersion(deps, manifest, nodeBin) {
+    const versionDir = join(deps.layout.bridge, manifest.connect.version);
+    if (isCompleteVersion(versionDir)) {
+        if (readNodePath(versionDir) !== nodeBin)
+            writeFileAtomic(join(versionDir, NODE_PATH_FILE), `${nodeBin}\n`);
+        deps.log(`reusing ${versionDir}`);
+        return { dir: versionDir, fresh: false };
+    }
+    const tmp = join(deps.layout.bridge, tempName(manifest.connect.version));
+    mkdirSync(tmp, { recursive: true });
+    try {
+        const connectArchive = join(tmp, 'connect.tgz');
+        await fetchVerified(deps, connectTarballUrls(manifest.connect.version), 'sha512', manifest.connect.sha512, connectArchive);
+        await unpackNpm(deps, connectArchive, tmp, connectPackageDir(tmp));
+        const wsArchive = join(tmp, 'ws.tgz');
+        await fetchVerified(deps, wsTarballUrls(manifest.ws.version), 'sha512', manifest.ws.sha512, wsArchive);
+        await unpackNpm(deps, wsArchive, tmp, join(tmp, 'node_modules', 'ws'));
+        writeFileSync(join(tmp, NODE_PATH_FILE), `${nodeBin}\n`);
+        return { dir: tmp, fresh: true };
+    }
+    catch (error) {
+        rmSync(tmp, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** 冒烟通过的临时目录改名为版本目录；版本目录在这期间被别的更新装好了就丢掉自己的 */
+function commitVersion(deps, tmp, version) {
+    const versionDir = join(deps.layout.bridge, version);
+    if (isCompleteVersion(versionDir)) {
+        rmSync(tmp, { recursive: true, force: true });
+        return;
+    }
+    if (existsSync(versionDir)) {
+        // 不完整的残留（被杀掉的旧更新）：先挪开再删，保证改名那一刻目标不存在
+        const aside = join(deps.layout.bridge, tempName('old'));
+        renameSync(versionDir, aside);
+        rmSync(aside, { recursive: true, force: true });
+    }
+    renameSync(tmp, versionDir);
+}
+function isStaleTemp(path, now) {
+    try {
+        return now - statSync(path).mtimeMs > STALE_TEMP_MS;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM：进程在，只是不属于当前用户 —— 也算在运行
+        return error.code === 'EPERM';
+    }
+}
+/** 状态文件里还活着的 bridge 的 pid（任意端口、任意版本，含终端里运行的 npx bridge） */
+function runningBridgePid(deps) {
+    const isAlive = deps.isAlive ?? defaultIsAlive;
+    const names = existsSync(deps.layout.root) ? readdirSync(deps.layout.root) : [];
+    for (const name of names) {
+        if (!/^bridge-\d+\.json$/.test(name))
+            continue;
+        const record = readInstanceRecord(join(deps.layout.root, name));
+        if (record && isAlive(record.pid))
+            return record.pid;
+    }
+    return null;
+}
+const listDir = (dir) => (existsSync(dir) ? readdirSync(dir) : []);
+function removePath(deps, path, what) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+        deps.log(`removed ${what}`);
+    }
+    catch (error) {
+        deps.log(`couldn't remove ${what}: ${message(error)}`);
+    }
+}
+/**
+ * 过期的 `bridge/.tmp-*`、`runtime/.tmp-*`：被打断的安装 / 更新留下的半截下载，以及挪开的残缺目录（review r2 R2-N4）。
+ * 每次检查都清（启动器每次启动都会调用），不等版本切换：清单版本不变时它们会一直留着，慢网下每被 agent 打断一次就多一份。
+ * 不受「有 bridge 在运行」的约束：它们不属于任何在用的版本；正在写入的临时目录是新近的（下载一次最多 10 分钟），过不了 1 小时的门槛。
+ */
+function removeStaleTemps(deps) {
+    const now = deps.now();
+    for (const dir of [deps.layout.bridge, deps.layout.runtime]) {
+        for (const name of listDir(dir)) {
+            const path = join(dir, name);
+            if (name.startsWith('.tmp-') && isStaleTemp(path, now))
+                removePath(deps, path, `stale ${name}`);
+        }
+    }
+}
+/**
+ * 只保留两个版本与它们用到的 Node 和适配器目录（D20「清理」、N2）。清理失败只记日志，不影响这次更新的结果。
+ * 有 bridge 在运行时整段跳过（review r1 R1-S3）：它可能是更早的版本（bridge 运行期间启动器被调用、中间跨了两次清单更新），
+ * 它用的 Node、npm 与组件目录都不能删；之后某次启动时没有 bridge 在运行，再清。过期临时目录另由 `removeStaleTemps` 每次清。
+ */
+function cleanup(deps, keep) {
+    const { layout } = deps;
+    const running = runningBridgePid(deps);
+    if (running !== null) {
+        deps.log(`skipped cleanup: an M2 bridge is running (pid ${running})`);
+        return;
+    }
+    const remove = (path, what) => removePath(deps, path, what);
+    for (const name of listDir(layout.bridge)) {
+        if (isReleaseVersion(name) && !keep.includes(name))
+            remove(join(layout.bridge, name), `bridge ${name}`);
+    }
+    const usedNode = new Set(keep.map((version) => readNodePath(join(layout.bridge, version))).flatMap((node) => (node ? [basename(dirname(dirname(node)))] : [])));
+    for (const name of listDir(layout.runtime)) {
+        if (NODE_DIR_RE.test(name) && !usedNode.has(name))
+            remove(join(layout.runtime, name), `runtime ${name}`);
+    }
+    // 适配器目录名由各版本自带的 lockfile 决定；任何一个保留版本的 lockfile 读不出，就整段跳过（宁可多留几百 MB，不能删掉在用的）
+    const keepAdapters = new Set();
+    try {
+        for (const version of keep) {
+            const sourceRoot = join(connectPackageDir(join(layout.bridge, version)), 'adapters');
+            for (const spec of Object.values(ADAPTERS))
+                keepAdapters.add(adapterInstallDirName(sourceRoot, spec.dir));
+        }
+    }
+    catch (error) {
+        deps.log(`skipped adapter cleanup: ${message(error)}`);
+        return;
+    }
+    const patterns = Object.values(ADAPTERS).map((spec) => new RegExp(`^${spec.dir}-[0-9a-f]{16}$`));
+    for (const name of listDir(layout.adapters)) {
+        if (!patterns.some((pattern) => pattern.test(name)) || keepAdapters.has(name))
+            continue;
+        if (existsSync(join(layout.adapters, name, ADAPTER_READY_MARKER)))
+            remove(join(layout.adapters, name), `adapter ${name}`);
+    }
+}
+export async function checkForUpdate(deps) {
+    const arch = deps.arch === 'arm64' || deps.arch === 'x64' ? deps.arch : null;
+    if (deps.platform !== 'darwin' || !arch)
+        return { kind: 'unsupported' };
+    const installed = readVersionLink(deps.layout.current);
+    if (!installed)
+        return { kind: 'not_installed' };
+    try {
+        removeStaleTemps(deps);
+    }
+    catch (error) {
+        deps.log(`stale temp cleanup stopped early: ${message(error)}`);
+    }
+    let manifest;
+    try {
+        const parsed = parseReleaseManifest(await deps.fetchText(MANIFEST_URL, MANIFEST_TIMEOUT_MS));
+        if (typeof parsed === 'string')
+            throw new UpdateError(parsed);
+        manifest = parsed;
+    }
+    catch (error) {
+        const reason = message(error);
+        deps.log(`manifest unavailable (${reason}); staying on ${installed}`);
+        return { kind: 'manifest_failed', reason };
+    }
+    const target = manifest.connect.version;
+    deps.log(`manifest says ${target}; installed ${installed}`);
+    if (target === installed)
+        return { kind: 'up_to_date', version: target };
+    if (readRejected(deps.layout.rejected).includes(target)) {
+        deps.log(`skipping ${target}: it failed to start before (listed in rejected)`);
+        return { kind: 'rejected', version: target };
+    }
+    try {
+        const nodeBin = await ensureNode(deps, manifest, arch);
+        const candidate = await prepareVersion(deps, manifest, nodeBin);
+        const test = await deps.selfTest(nodeBin, connectCliPath(candidate.dir));
+        if (!test.ok) {
+            if (candidate.fresh)
+                rmSync(candidate.dir, { recursive: true, force: true });
+            throw new UpdateError(`self-test failed: ${tail(test.output.trim())}`);
+        }
+        deps.log(`self-test ok for ${target}`);
+        if (candidate.fresh)
+            commitVersion(deps, candidate.dir, target);
+        const before = readVersionLink(deps.layout.current);
+        if (before === target) {
+            deps.log(`${target} is already current (another update switched it)`);
+            return { kind: 'up_to_date', version: target };
+        }
+        if (before)
+            swapLink(deps.layout.previous, before);
+        swapLink(deps.layout.current, target);
+        deps.log(`switched current ${before ?? '(none)'} -> ${target}`);
+        try {
+            cleanup(deps, before ? [target, before] : [target]);
+        }
+        catch (error) {
+            // 已经切换完成：清理出错只是少删了东西，不能把这次更新报成失败（review r1 R1-N4）
+            deps.log(`cleanup stopped early: ${message(error)}`);
+        }
+        return { kind: 'updated', from: before ?? installed, to: target };
+    }
+    catch (error) {
+        const reason = message(error);
+        deps.log(`update to ${target} failed (${reason}); staying on ${installed}`);
+        return { kind: 'failed', version: target, reason };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Connect your local agent clients (Claude Code, Codex, Cursor, OpenCode, Qoder) to M2 Canvas over MCP in one command, and run the local bridge that lets M2 drive them over ACP.",
   "type": "module",
   "bin": {