@m2canvas/connect 0.6.0 → 0.7.1

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. When a page isn't paired yet (another browser, or the pairing expired), M2 gives it the same start command: the new bridge process sees the one already running and hands the page's pairing value to it, so the page pairs without restarting the bridge and other tabs keep their sessions. The handoff goes through `~/.m2canvas/bridge-<port>.sock` plus a one-time file in `~/.m2canvas`, so only a process that can write to that folder (your account; agent sandboxes normally can't write there) can hand a pairing value over; the file holds only the hash and is deleted right away. If that doesn't work, M2 offers to restart the bridge with `--replace`, which ends the sessions on the old one.
+- **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/handoff.js

@@ -0,0 +1,197 @@
+/**
+ * 把命令承诺交给正在运行的后台 bridge（change acp-bridge-one-time-install design D27、R11、review r3 R3-S1；`connect/local-bridge` 契约 2 delta）。
+ *
+ * 后台模式的 bridge 不出配对码，新页面只能靠启动命令里的承诺配对；原来承诺只能在启动时经 `--pair` 带进去，
+ * 换一个浏览器就得 `--replace` 重启 bridge，打断其他页面上正在跑的 agent。现在：
+ *  - 后台模式的 bridge 监听 `~/.m2canvas/bridge-<port>.sock`；
+ *  - 启动器拉起的新 `bridge --background --pair <c>` 撞上认定的 M2 bridge 时，把 c 写进 `~/.m2canvas/handoff-<编号>.pending`，
+ *    经 socket 只发这个编号；bridge 读出承诺、删掉文件、挂上，再回复。交出方随后以退出码 3 退出。
+ *
+ * 跨版本接口（启动器只随重装更新，bridge 会自动更新，交出方与接收方可能是不同版本；`connect/local-bridge` 契约 14 delta）：
+ *  - 请求一行（不含换行最多 256 字节）：`{"type":"arm","nonce":"<32 位小写十六进制>"}\n`；承诺在 `<m2 目录>/handoff-<nonce>.pending`（普通文件、属于本账号）；
+ *  - 回复一行：`{"ok":true,"until":<毫秒时间戳>}` 或 `{"ok":false,"error":"…"}`，回复后断开。
+ *  只能加字段；要改语义就换请求的 type，并让接收方继续认旧的。
+ *
+ * 维护约束：
+ * - 门槛是「能写 `~/.m2canvas`」，而不只是「能连 socket」（R3-S1）：agent 沙箱里的命令可能被放开了本机 socket，
+ *   但默认只能写工作目录与临时目录；只靠 socket 的话，它就能配上、再经 bridge 驱动沙箱外的 agent。能写这个目录的进程
+ *   本来就能配对（bridge 每次校验 token 都重读 `bridge-pairings.json`，往里加一条记录即可；在沙箱里、做不到 `--replace` 也一样），
+ *   所以不算新的攻击者类别。这条论证依赖「每次重读配对文件」：改成只在启动时读或缓存时，要重新评估这里的门槛。
+ *   不要退回「socket 上直接带承诺」，也不要放宽文件名（只认 32 位十六进制）。
+ * - socket 上不收 S、不回 token：拿 token 仍要页面在 hello 里出示 S，Origin 白名单照旧。
+ * - 只有同一个账号能连：`~/.m2canvas` 0700、socket 0600。不要把 socket 放到别的目录，也不要放宽权限。
+ * - 每个连接只处理一行、有长度上限、有从连上起算的绝对超时：这是本机进程能碰到的入口，不能让它挂住 bridge 或吃内存。
+ * - socket 路径受 macOS 的 sun_path 限制（104 字节含结尾 0）：超出就不监听，只记日志（交接不可用，页面用 `--replace` 兜底）。
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, lstatSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { basename, dirname, join } from 'node:path';
+import { isPairCommitment } from './pairing.js';
+/** sockaddr_un.sun_path 是 104 字节，含结尾的 0 */
+export const HANDOFF_MAX_PATH_BYTES = 103;
+export const HANDOFF_TIMEOUT_MS = 3_000;
+/** `{"type":"arm","nonce":"<32 字符>"}` 不到 60 字节，留足余量 */
+const MAX_LINE_BYTES = 256;
+const NONCE_RE = /^[0-9a-f]{32}$/;
+/** 承诺文件只放 22 个字符（可能带换行） */
+const MAX_PENDING_BYTES = 64;
+export function handoffSocketPath(dir, port) {
+    return join(dir, `bridge-${port}.sock`);
+}
+function pendingPath(dir, nonce) {
+    return join(dir, `handoff-${nonce}.pending`);
+}
+/** 删不掉（例如被换成了目录）只当没删：这里的异常没人接，抛出会让 bridge 退出（契约 5，r3 复核 R3C-N1） */
+function removeQuietly(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // 留下的残留由卸载脚本或下一次同名交接处理
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function requestedNonce(line) {
+    try {
+        const request = JSON.parse(line);
+        if (typeof request !== 'object' || request === null)
+            return null;
+        const { type, nonce } = request;
+        return type === 'arm' && typeof nonce === 'string' && NONCE_RE.test(nonce) ? nonce : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 读出交出方写的承诺并删掉文件；不是本账号的普通文件、内容不对都当没有（不跟随符号链接） */
+function takePendingCommitment(dir, nonce) {
+    const path = pendingPath(dir, nonce);
+    // 编号的正则已经挡住了路径分隔符；这里再按路径结构核一次，正则被改松时也不会读到目录外（r3 复核 R3C-S1）
+    if (dirname(path) !== join(dir) || basename(path) !== `handoff-${nonce}.pending`)
+        return null;
+    try {
+        const info = lstatSync(path);
+        const uid = typeof process.getuid === 'function' ? process.getuid() : info.uid;
+        if (!info.isFile() || info.uid !== uid || info.size > MAX_PENDING_BYTES)
+            return null;
+        const commitment = readFileSync(path, 'utf8').trim();
+        return isPairCommitment(commitment) ? commitment : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        removeQuietly(path);
+    }
+}
+/**
+ * 后台模式的 bridge 在拿到端口之后调用：同名的 socket 残留（上次没清干净）先删掉 —— 端口在自己手里，这个端口的 socket 不可能属于别人。
+ * 返回 null = 没监听（路径太长或建不起来），只记日志，不影响 bridge 本身。
+ */
+export async function listenForHandoff(options) {
+    const { dir, port, arm, log } = options;
+    const path = handoffSocketPath(dir, port);
+    if (Buffer.byteLength(path) > HANDOFF_MAX_PATH_BYTES) {
+        log(`Pairing handoff is unavailable: ${path} is too long for a local socket. A new browser has to use the reconnect command instead.`);
+        return null;
+    }
+    const server = createServer((socket) => {
+        const deadline = setTimeout(() => socket.destroy(), HANDOFF_TIMEOUT_MS);
+        socket.on('close', () => clearTimeout(deadline));
+        socket.on('error', () => undefined);
+        let buffer = '';
+        let done = false;
+        socket.on('data', (chunk) => {
+            // 只处理第一行：之后再发什么都丢掉（不暂停读取，对方断开时这边也跟着关）
+            if (done)
+                return;
+            buffer += chunk.toString('utf8');
+            const end = buffer.indexOf('\n');
+            if (Buffer.byteLength(end < 0 ? buffer : buffer.slice(0, end)) > MAX_LINE_BYTES) {
+                socket.destroy();
+                return;
+            }
+            if (end < 0)
+                return;
+            done = true;
+            const nonce = requestedNonce(buffer.slice(0, end));
+            const commitment = nonce ? takePendingCommitment(dir, nonce) : null;
+            if (!commitment) {
+                socket.end(`${JSON.stringify({ ok: false, error: nonce ? 'not_found' : 'bad_request' })}\n`);
+                return;
+            }
+            const until = arm(commitment);
+            log('Armed a pairing value received over the local handoff socket; the page that holds it can pair now.');
+            socket.end(`${JSON.stringify({ ok: true, until })}\n`);
+        });
+    });
+    try {
+        rmSync(path, { force: true });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(path, () => resolve());
+        });
+        chmodSync(path, 0o600);
+    }
+    catch (error) {
+        server.close();
+        log(`Pairing handoff is unavailable (${errorText(error)}). A new browser has to use the reconnect command instead.`);
+        return null;
+    }
+    return {
+        close() {
+            server.close();
+            rmSync(path, { force: true });
+        },
+    };
+}
+/**
+ * 新的 `bridge --background --pair <c>` 撞上认定的 M2 bridge 时调用：把承诺写进一次性文件，经 socket 发编号。
+ * true = 对方确认挂上了；没人在听、对方拒绝、超时都是 false（调用方照常以退出码 3 退出，只是新页面配不上）。文件无论如何都删掉。
+ */
+export function handOffCommitment(options) {
+    const { dir, port, commitment, timeoutMs = HANDOFF_TIMEOUT_MS } = options;
+    if (!isPairCommitment(commitment))
+        return Promise.resolve(false);
+    const nonce = randomBytes(16).toString('hex');
+    const file = pendingPath(dir, nonce);
+    try {
+        writeFileSync(file, commitment, { mode: 0o600, flag: 'wx' });
+    }
+    catch {
+        return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+        let reply = '';
+        let settled = false;
+        const socket = createConnection(handoffSocketPath(dir, port));
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(ok);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        socket.on('error', () => finish(false));
+        socket.on('data', (chunk) => {
+            reply += chunk.toString('utf8');
+            if (reply.length > MAX_LINE_BYTES)
+                finish(false);
+        });
+        socket.on('end', () => {
+            try {
+                const answer = JSON.parse(reply.trim());
+                finish(typeof answer === 'object' && answer !== null && answer.ok === true);
+            }
+            catch {
+                finish(false);
+            }
+        });
+        socket.on('connect', () => socket.write(`${JSON.stringify({ type: 'arm', nonce })}\n`));
+    }).finally(() => removeQuietly(file));
+}

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';
@@ -16,14 +20,37 @@ import { EXPECT_PATH } from './authorize.js';
 import { buildAgentEnv, buildNpmEnv, buildProbeEnv } from './env.js';
 import { execCommand, killActiveExecs } from './exec.js';
 import { createLsofProbe, createPsProbe, createStopDeps, identifyRunningBridge, instanceFilePath, listenWithReplace, processStartedAt, removeInstanceRecord, stopRunningBridge, writeInstanceRecord } from './instance.js';
+import { handOffCommitment, listenForHandoff } from './handoff.js';
 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 +83,20 @@ 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 (handing its --pair
+                  to that bridge first), ${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 +109,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 +186,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 +212,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 +239,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 +259,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 +296,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 +324,18 @@ export async function runBridge(argv) {
         log,
         error: (message) => console.error(message),
         clock,
+        alreadyRunning: () => {
+            alreadyRunning = true;
+        },
     });
+    // listenWithReplace 返回 null 的情况都与端口有关（已在运行、被别的程序占着、停不掉旧的）；后台模式把「已在运行」与其余分开。
+    // 已在运行时先把承诺交给它，新页面不用重启 bridge 就能配对（D27）；交不过去也照常退出码 3
+    if (!server && parsed.background && alreadyRunning && parsed.pair) {
+        const handed = await handOffCommitment({ dir: m2Dir, port: parsed.port, commitment: parsed.pair });
+        log(handed ? 'Handed the pairing to the M2 bridge already running on this port; the new page pairs with it.' : "Couldn't hand the pairing to the M2 bridge already running on this port; the new page can reconnect with --replace.");
+    }
     if (!server)
-        return 1;
+        return parsed.background ? (alreadyRunning ? EXIT_ALREADY_RUNNING : EXIT_PORT_UNAVAILABLE) : 1;
     const running = server;
     try {
         // startedAt 必须是进程启动时刻：--replace 时要等旧的退出后才写，取写文件时刻会晚出几百毫秒到几秒，下一次 --replace 就认不出它
@@ -247,6 +344,8 @@ export async function runBridge(argv) {
     catch (error) {
         console.warn(`Couldn't write ${instancePath} (${error instanceof Error ? error.message : String(error)}); --replace won't recognize this bridge.`);
     }
+    // 交接 socket（D27）在装好信号处理之后才开始监听：中间有 await，这段时间收到 SIGTERM 也要走清理
+    let handoff = null;
     // 兜底：bridge 经 process.exit 或未捕获异常退出时，不留下 agent 进程组和仍在运行的命令。
     // 注意 SIGHUP / SIGINT / SIGTERM 的默认处理会直接终止进程、不触发 'exit'，所以这三个信号由 lifecycle.ts 显式接管。
     process.on('exit', () => {
@@ -257,6 +356,12 @@ export async function runBridge(argv) {
         catch {
             // 见上
         }
+        try {
+            handoff?.close();
+        }
+        catch {
+            // 残留的 socket 文件由下一次启动删掉
+        }
         running.authorizations.killAllNow();
         running.processes.killAllNow();
         killActiveExecs();
@@ -293,6 +398,15 @@ export async function runBridge(argv) {
             process.exit(130);
         },
     });
+    if (parsed.background)
+        handoff = await listenForHandoff({ dir: m2Dir, port: parsed.port, arm: (c) => pairing.armCommitment(c), log });
+    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 +415,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');
+    }
+}