@m2canvas/connect 0.7.2 → 0.8.0

package/README.md

@@ -39,7 +39,7 @@ Lets M2 (in Chrome or another Chromium browser) start and talk to the agents on
 - **Pairing.** When you start the bridge with the command M2 gives you, the page that gave it pairs automatically within 10 minutes. The command only carries a hash (`--pair`); the secret it matches stays in that browser tab, so the command is safe to appear in your shell history, and it works once. Any other page asks for the pairing code printed in this window; the window also shows which site is asking. After that the page remembers the pairing for 30 days of inactivity. After too many wrong codes, new pages can't pair until you restart the bridge (pages already paired keep working); close the page the window names first. `bridge --unpair` forgets all paired pages. If you can't find this window, run the command M2 shows under the code box: it adds `--replace`, which stops the M2 bridge already running on the port (its agent sessions end) and starts a new one that pairs by itself. It only stops a bridge (0.6.0 or later) it can recognize from a small state file in `~/.m2canvas` (process id and start time; no codes or tokens are written there), never anything else on the port, and not on Windows. When it can't recognize what holds the port, it shows you that process (or how to find it) and leaves it alone. With an older bridge, M2 shows the Ctrl+C instructions instead.
 - **Your own logins.** Agents use their own sign-in and their own M2 MCP setup. It starts agents with a minimal environment, so variables set by a host app (for example `ANTHROPIC_BASE_URL` inside Claude Code) don't leak into them.
 - **Signing in from M2 (macOS).** M2 can start an agent's own sign-in, or its M2 authorization, for you: the bridge runs that agent's own command from a fixed list in this package, and M2 opens the sign-in page in the browser you are using (Codex opens your default browser itself). You finish signing in there; nothing is entered for you. The page only picks the agent and whether to sign in or authorize M2, never the command. Covered: sign-in for Claude Code, Codex, Cursor and Qoder; M2 authorization for Claude Code, Codex, Cursor and OpenCode (Qoder's M2 authorization is only available inside Qoder). Claude Code's M2 authorization needs a terminal, so the bridge provides one with macOS's built-in `/usr/bin/expect`. A sign-in can be canceled from M2, gives up after 10 minutes, and stops when the page disconnects or the bridge exits. On other systems M2 shows the command to run instead.
-- **Claude and Codex** run through pinned versions of the official adapters (`@agentclientprotocol/claude-agent-acp@0.84.0`, `@agentclientprotocol/codex-acp@2.1.0`). They are installed on first use into `~/.m2canvas/acp-adapters/` from the lockfiles in this package (about 270 MB and 350 MB, because they bundle the agent); M2 shows the download progress. You don't need Claude Code or Codex installed yourself: checking sign-in, adding M2 and signing in all use the bundled `claude` and `codex`, which read the same settings as your own installs.
+- **Claude and Codex** run through pinned versions of the official adapters (`@agentclientprotocol/claude-agent-acp@0.84.0`, `@agentclientprotocol/codex-acp@2.1.0`). They are installed on first use into `~/.m2canvas/acp-adapters/` from the lockfiles in this package (they bundle the agent: about 110 MB and 140 MB to download, 270 MB and 350 MB on disk); M2 shows the download progress. You don't need Claude Code or Codex installed yourself: checking sign-in, adding M2 and signing in all use the bundled `claude` and `codex`, which read the same settings as your own installs.
 - Cursor runs as `agent acp`, OpenCode as `opencode acp`, Qoder as `qodercli --acp`.
 
 Agent sessions start in that directory.
@@ -59,6 +59,6 @@ curl -fsSL https://m2ui.ai/connect/install.sh | sh -s -- --pair <value from M2>
 - **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.
+- **Uninstall** with "Uninstall local connection" in the Local Agent tab's ⋯ menu, or `curl -fsSL https://m2ui.ai/connect/uninstall.sh | sh`. 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. While a bridge started this way (0.8.0 or later) is running, M2 asks it to uninstall itself: it stops its agents, runs the same uninstaller (shipped in this package as `install/uninstall.sh`), reports what happened to M2, and exits. Only a paired page can ask, and it can't pass anything that changes what gets removed. Otherwise M2 offers the M2 app, an agent app or the Terminal command.
 
 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

@@ -14,7 +14,7 @@
  * - 安装目录名带 lockfile 哈希：换了 lockfile 就是新目录，旧目录不会被半新半旧地复用。旧目录目前不清理（FU-2026-10-02-120）。
  * - 先装到临时目录、写好就绪标记再原子改名；残留的临时目录或没有标记的目录一律视为未安装。
  * - 升级 Claude 适配器时复核 bundledClaudePath 与 SDK 自身的解析规则是否仍一致（acp-terminal-free-auth evidence/sdk-binary-resolution.md），
- *   并按新版本实测 installedBytes。
+ *   并按新版本实测 installedBytes 与 downloadBytes。
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
@@ -29,6 +29,7 @@ export const ADAPTERS = {
         version: '0.84.0',
         entry: 'node_modules/@agentclientprotocol/claude-agent-acp/dist/index.js',
         installedBytes: 268_451_230,
+        downloadBytes: 106_768_111,
     },
     codex: {
         dir: 'codex-acp',
@@ -36,6 +37,7 @@ export const ADAPTERS = {
         version: '2.1.0',
         entry: 'node_modules/@agentclientprotocol/codex-acp/dist/index.js',
         installedBytes: 346_221_434,
+        downloadBytes: 135_994_489,
     },
 };
 /** 适配器自带的 codex：预检与授权命令都要用它（本机旧版 codex 存的凭证，新版本刷新不了，PoC 报告 §2.2） */
@@ -136,6 +138,7 @@ export class AdapterManager {
     options;
     installing = new Map();
     lastError = new Map();
+    stopped = false;
     progress = new Map();
     constructor(options) {
         this.options = options;
@@ -166,10 +169,19 @@ export class AdapterManager {
         const error = this.lastError.get(agent);
         return error ? { ...base, state: 'failed', error } : { ...base, state: 'not_installed', error: null };
     }
+    /**
+     * bridge 在卸载自己（change bridge-uninstall-from-page 实现中发现 I1）：之后不再开始新的安装。
+     * 安装第一步就 mkdir 临时目录，会把刚被卸载脚本删掉的 `~/.m2canvas` 重建出来；进行中的 npm ci 由调用方 killActiveExecs 结束。
+     */
+    stopInstalling() {
+        this.stopped = true;
+    }
     /** 已就绪直接返回；正在装就等同一次安装；否则开始安装。失败不抛错，返回 state = failed */
     prepare(agent) {
         if (this.isReady(agent))
             return Promise.resolve(this.info(agent));
+        if (this.stopped)
+            return Promise.resolve({ ...this.info(agent), state: 'failed', error: 'the bridge is uninstalling itself' });
         const running = this.installing.get(agent);
         if (running)
             return running;

package/dist/bridge/args.js

@@ -0,0 +1,114 @@
+/**
+ * `bridge` 子命令的参数：解析、帮助文本、后台模式的退出码与寿命。
+ *
+ * 从 main.ts 拆出（行数门禁）。启动器 `~/.m2canvas/bin/m2-bridge` 按这里的参数与退出码调用任意版本的 bridge
+ * （契约 14、`install/m2-bridge.sh` 头注释），已安装的 bridge 又会自动更新，所以每个版本都要保持这套接口兼容。
+ */
+import { resolve } from 'node:path';
+import { isPairCommitment } from './pairing.js';
+import { BRIDGE_DEFAULT_PORT } from './protocol.js';
+import { DEV_ORIGINS, PROD_ORIGINS } from './security.js';
+/**
+ * 后台模式下，端口上已有认定的 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;
+}
+export const BRIDGE_HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev] [--pair <value>] [--replace]
+       npx @m2canvas/connect bridge --unpair
+
+Runs the local agent bridge so M2 (in Chrome) can start and talk to the agents
+installed on this machine: Claude Code, Codex, Cursor CLI, OpenCode and Qoder.
+
+It only listens on 127.0.0.1 and only accepts the M2 web app (${PROD_ORIGINS.join(', ')}).
+The command M2 gives you pairs that page automatically; other pages ask for the
+pairing code shown here. A paired page can make these agents read and change
+files and run commands as you, so only run commands you copied from M2.
+Agents run in the directory you start the bridge from (or --cwd), with your own logins.
+On macOS a paired page can also start an agent's own sign-in; you finish it in
+your browser.
+
+  --port <n>      port to listen on (default ${BRIDGE_DEFAULT_PORT})
+  --cwd <dir>     working directory for agent sessions (default: current directory)
+  --verbose       also print agent stderr and connection details
+  --dev           also accept a local M2 dev server (${DEV_ORIGINS.join(', ')});
+                  any app served on that port could then ask to pair
+  --pair <value>  pair the M2 page that gave you this command (M2 adds it for you;
+                  valid for 10 minutes, once)
+  --replace       if an M2 bridge (0.6.0 or later) is already running on the port,
+                  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
+
+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, 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')
+            args.help = true;
+        else if (arg === '--verbose')
+            args.verbose = true;
+        else if (arg === '--unpair')
+            args.unpair = true;
+        else if (arg === '--dev')
+            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)
+                return '--pair needs a value';
+            if (!isPairCommitment(value))
+                return `invalid --pair value ${value}; copy the start command from M2 again`;
+            args.pair = value;
+        }
+        else if (arg === '--port' || arg === '--cwd') {
+            const value = argv[++i];
+            if (value === undefined)
+                return `${arg} needs a value`;
+            if (arg === '--cwd')
+                args.cwd = resolve(value);
+            else {
+                const port = Number(value);
+                if (!Number.isInteger(port) || port < 1 || port > 65535)
+                    return `invalid --port ${value}`;
+                args.port = port;
+            }
+        }
+        else
+            return `unknown option ${arg}`;
+    }
+    return args;
+}

package/dist/bridge/call-dispatch.js

@@ -0,0 +1,64 @@
+/**
+ * bridge 方法的分派（从 server.ts 拆出）：未配对只放行 pair，其余按方法交给 service / ProcessManager / auth-call.ts。
+ * 连接状态（是否已配对、连接是否还在）只在 server.ts 里改，这里经 ctx 的回调读写。
+ *
+ * 安全边界同 server.ts 文件头：页面可控的参数只有 agent id（枚举校验）、配对码、processId，进不了 spawn 的命令、参数、cwd、环境；
+ * agent/authorize 与 agent/authorize-cancel 的参数校验在 auth-call.ts。
+ * bridge/uninstall 不经过这里：server.ts 在调用 handleCall 之前就把它交给 uninstall-call.ts（它要等回复写出再关连接、退出）。
+ */
+import { isBridgeAgentId } from './agents.js';
+import { handleAuthCall } from './auth-call.js';
+import { handlePairCall } from './pair-call.js';
+import { TOKEN_IDLE_DAYS } from './pairing.js';
+import { ProcessError } from './processes.js';
+import { BridgeFailure } from './service.js';
+export async function handleCall(ctx, conn, id, method, params) {
+    if (method === 'pair') {
+        const token = handlePairCall(ctx.pairing, conn.origin, params);
+        ctx.markPaired(conn.id);
+        ctx.log(`Paired with ${conn.origin}.`);
+        return { token, cwd: ctx.cwd, idleExpiryDays: TOKEN_IDLE_DAYS };
+    }
+    if (!conn.paired)
+        throw new BridgeFailure('not_paired', 'pair this page first');
+    if (method === 'process/stop') {
+        const processId = params.processId;
+        if (typeof processId !== 'string' || !ctx.processes.stop(conn.id, processId))
+            throw new BridgeFailure('process_not_found', 'no such process on this connection');
+        return {};
+    }
+    if (method === 'agents/list')
+        return { agents: await ctx.service.list() };
+    if (method === 'agent/authorize' || method === 'agent/authorize-cancel')
+        return handleAuthCall(ctx.auth, conn.id, method, params);
+    const agent = params.agent;
+    if (!isBridgeAgentId(agent))
+        throw new BridgeFailure('unknown_agent', `unknown agent ${String(agent)}`);
+    switch (method) {
+        case 'agent/prepare':
+            return { agent, adapter: await ctx.service.prepare(agent) };
+        case 'agent/precheck':
+            return ctx.service.precheck(agent);
+        case 'm2/configure':
+            ctx.log(`Page asked to add M2 to ${agent}'s MCP config.`);
+            return { agent, ...(await ctx.service.configure(agent)) };
+        case 'process/start': {
+            const launch = await ctx.service.launch(agent);
+            try {
+                const processId = await ctx.processes.start(conn.id, agent, launch);
+                // 启动期间页面已断开：没有人会再停它，立刻清理
+                if (!ctx.isConnected(conn.id))
+                    ctx.processes.stopOwner(conn.id);
+                ctx.log(`Started ${agent}.`);
+                return { processId, agent, cwd: ctx.cwd };
+            }
+            catch (error) {
+                if (error instanceof ProcessError)
+                    throw new BridgeFailure(error.code, error.message);
+                throw error;
+            }
+        }
+    }
+    // 未知方法在调用前已被 server.ts 的 isMethod 拦下；走到这里说明 BRIDGE_METHODS 与上面的分支不一致
+    throw new BridgeFailure('internal', `unhandled method ${method} (call ${id})`);
+}

package/dist/bridge/handoff.js

@@ -10,6 +10,10 @@
  * 跨版本接口（启动器只随重装更新，bridge 会自动更新，交出方与接收方可能是不同版本；`connect/local-bridge` 契约 14 delta）：
  *  - 请求一行（不含换行最多 256 字节）：`{"type":"arm","nonce":"<32 位小写十六进制>"}\n`；承诺在 `<m2 目录>/handoff-<nonce>.pending`（普通文件、属于本账号）；
  *  - 回复一行：`{"ok":true,"until":<毫秒时间戳>}` 或 `{"ok":false,"error":"…"}`，回复后断开。
+ *  - 只读状态查询（change desktop-bridge-launcher D15 起；具体版本见 connect 的发布记录）：请求 `{"type":"status","commitment":"<22 位 base64url>"}\n`，
+ *    回复 `{"ok":true,"state":"waiting","until":…}` / `{"ok":true,"state":"paired","origin":"…","at":…}` / `{"ok":true,"state":"unknown"}`，
+ *    可带 `"rejected":{"origin":"…","at":…}`（最近一次因 Origin 不在白名单被拒的连接）。旧版本对它回 `bad_request`，
+ *    M2 Mac 客户端据此判定「不支持」。
  *  只能加字段；要改语义就换请求的 type，并让接收方继续认旧的。
  *
  * 维护约束：
@@ -18,6 +22,9 @@
  *   本来就能配对（bridge 每次校验 token 都重读 `bridge-pairings.json`，往里加一条记录即可；在沙箱里、做不到 `--replace` 也一样），
  *   所以不算新的攻击者类别。这条论证依赖「每次重读配对文件」：改成只在启动时读或缓存时，要重新评估这里的门槛。
  *   不要退回「socket 上直接带承诺」，也不要放宽文件名（只认 32 位十六进制）。
+ * - `status` 只读、承诺随请求一起发，不要求能写 `~/.m2canvas`：它只透露「这个承诺配没配上、配给了哪个 origin、最近被拒的 origin」，
+ *   这些本来就写在 `~/.m2canvas/logs/bridge.log` 里，能连这个 socket 的本账号进程也能读到；不回 S、不回 token、不改任何状态，
+ *   也不能用来猜承诺（128 bit）。回复里要加别的东西时，先重做这条论证（design D15）。
  * - socket 上不收 S、不回 token：拿 token 仍要页面在 hello 里出示 S，Origin 白名单照旧。
  * - 只有同一个账号能连：`~/.m2canvas` 0700、socket 0600。不要把 socket 放到别的目录，也不要放宽权限。
  * - 每个连接只处理一行、有长度上限、有从连上起算的绝对超时：这是本机进程能碰到的入口，不能让它挂住 bridge 或吃内存。
@@ -54,13 +61,17 @@ function removeQuietly(path) {
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function requestedNonce(line) {
+function parseRequest(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;
+        const { type, nonce, commitment } = request;
+        if (type === 'arm' && typeof nonce === 'string' && NONCE_RE.test(nonce))
+            return { type, nonce };
+        if (type === 'status' && typeof commitment === 'string' && isPairCommitment(commitment))
+            return { type, commitment };
+        return null;
     }
     catch {
         return null;
@@ -92,7 +103,7 @@ function takePendingCommitment(dir, nonce) {
  * 返回 null = 没监听（路径太长或建不起来），只记日志，不影响 bridge 本身。
  */
 export async function listenForHandoff(options) {
-    const { dir, port, arm, log } = options;
+    const { dir, port, arm, status, 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.`);
@@ -117,7 +128,12 @@ export async function listenForHandoff(options) {
             if (end < 0)
                 return;
             done = true;
-            const nonce = requestedNonce(buffer.slice(0, end));
+            const request = parseRequest(buffer.slice(0, end));
+            if (request?.type === 'status' && status) {
+                socket.end(`${JSON.stringify({ ok: true, ...status(request.commitment) })}\n`);
+                return;
+            }
+            const nonce = request?.type === 'arm' ? request.nonce : null;
             const commitment = nonce ? takePendingCommitment(dir, nonce) : null;
             if (!commitment) {
                 socket.end(`${JSON.stringify({ ok: false, error: nonce ? 'not_found' : 'bad_request' })}\n`);

package/dist/bridge/main.js

@@ -3,54 +3,39 @@
  *
  * 只由 cli.ts 在第一个参数是 `bridge` 时动态加载：默认的 MCP 配置流程（Copy to agent 起手式）不会加载这里的任何代码与依赖。
  *
- * 本文件负责组装与终端交互：参数、启动横幅、配对码打印、信号处理、退出兜底清理。协议在 server.ts，安全判定在 security.ts / pairing.ts。
+ * 本文件负责组装与终端交互：启动横幅、配对码打印、信号处理、退出兜底清理。参数与帮助在 args.ts，协议在 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 退出，启动器把它当成功。
+ * 后台模式且在 macOS 上时还能卸载自己（`bridge/uninstall`，change bridge-uninstall-from-page D2 / D3；执行在 uninstall.ts）。
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { home, isExecutable, which } from '../system.js';
 import { AdapterManager, ADAPTERS } from './adapters.js';
+import { BRIDGE_HELP, EXIT_ALREADY_RUNNING, EXIT_PORT_UNAVAILABLE, backgroundLifetimeMs, parseBridgeArgs } from './args.js';
 import { detectAgent } from './agents.js';
 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 { installLayout } from './install-layout.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 { PairingManager, createFilePairingStore } from './pairing.js';
+import { BRIDGE_AGENT_IDS, BRIDGE_WS_PATH } from './protocol.js';
 import { resolveNpmCommand } from './npm-command.js';
-import { DEV_ORIGINS, PROD_ORIGINS, allowedOrigins } from './security.js';
+import { 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';
+import { createSelfUninstaller, uninstallScriptPath } from './uninstall.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',
@@ -58,91 +43,6 @@ const LABELS = {
     opencode: 'OpenCode',
     qoder: 'Qoder',
 };
-export const BRIDGE_HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev] [--pair <value>] [--replace]
-       npx @m2canvas/connect bridge --unpair
-
-Runs the local agent bridge so M2 (in Chrome) can start and talk to the agents
-installed on this machine: Claude Code, Codex, Cursor CLI, OpenCode and Qoder.
-
-It only listens on 127.0.0.1 and only accepts the M2 web app (${PROD_ORIGINS.join(', ')}).
-The command M2 gives you pairs that page automatically; other pages ask for the
-pairing code shown here. A paired page can make these agents read and change
-files and run commands as you, so only run commands you copied from M2.
-Agents run in the directory you start the bridge from (or --cwd), with your own logins.
-On macOS a paired page can also start an agent's own sign-in; you finish it in
-your browser.
-
-  --port <n>      port to listen on (default ${BRIDGE_DEFAULT_PORT})
-  --cwd <dir>     working directory for agent sessions (default: current directory)
-  --verbose       also print agent stderr and connection details
-  --dev           also accept a local M2 dev server (${DEV_ORIGINS.join(', ')});
-                  any app served on that port could then ask to pair
-  --pair <value>  pair the M2 page that gave you this command (M2 adds it for you;
-                  valid for 10 minutes, once)
-  --replace       if an M2 bridge (0.6.0 or later) is already running on the port,
-                  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
-
-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, 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')
-            args.help = true;
-        else if (arg === '--verbose')
-            args.verbose = true;
-        else if (arg === '--unpair')
-            args.unpair = true;
-        else if (arg === '--dev')
-            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)
-                return '--pair needs a value';
-            if (!isPairCommitment(value))
-                return `invalid --pair value ${value}; copy the start command from M2 again`;
-            args.pair = value;
-        }
-        else if (arg === '--port' || arg === '--cwd') {
-            const value = argv[++i];
-            if (value === undefined)
-                return `${arg} needs a value`;
-            if (arg === '--cwd')
-                args.cwd = resolve(value);
-            else {
-                const port = Number(value);
-                if (!Number.isInteger(port) || port < 1 || port > 65535)
-                    return `invalid --port ${value}`;
-                args.port = port;
-            }
-        }
-        else
-            return `unknown option ${arg}`;
-    }
-    return args;
-}
 /** 包根目录：dist/bridge/*.js 与 src/bridge/*.ts 到包根的相对深度相同 */
 const PACKAGE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
 function packageVersion() {
@@ -297,6 +197,25 @@ export async function runBridge(argv) {
     // 端口被占时认出正在运行的 M2 bridge，给出 pid 与终端，或在 --replace 时接管（D20）。状态文件不含任何密钥
     const instancePath = instanceFilePath(m2Dir, parsed.port);
     let alreadyRunning = false;
+    /** 最近一次因 Origin 不在白名单被拒的页面（desktop-bridge-launcher D15）：交接 socket 的状态查询带回给 M2 Mac 客户端 */
+    let lastRejected = null;
+    // 只有启动器从 ~/.m2canvas 拉起的后台 bridge、且在 macOS 上（后台安装只有 macOS，契约 15）才能卸载自己（D2）。
+    // 回调里用到的 handoff / stop 在下面才赋值：卸载只会在服务开始监听、它们都已就绪之后被调用
+    const uninstaller = parsed.background && process.platform === 'darwin'
+        ? createSelfUninstaller({
+            scriptPath: uninstallScriptPath(PACKAGE_ROOT),
+            home,
+            workspace: installLayout(home).workspace,
+            env: buildAgentEnv(),
+            exec: execCommand,
+            exists: existsSync,
+            stopInstalling: () => adapters.stopInstalling(),
+            killExecs: killActiveExecs,
+            forgetSelf: () => removeInstanceRecord(instancePath, process.pid),
+            closeHandoff: () => handoff?.close(),
+            exit: () => void stop(),
+        })
+        : undefined;
     server = await listenWithReplace(() => startBridgeServer({
         port: parsed.port,
         cwd: parsed.cwd,
@@ -312,6 +231,10 @@ export async function runBridge(argv) {
         service,
         agentEnv: buildAgentEnv(),
         allowedOrigins: origins,
+        uninstall: uninstaller,
+        onOriginRejected: (origin) => {
+            lastRejected = { origin, at: Date.now() };
+        },
         log,
         verbose: parsed.verbose,
     }), {
@@ -398,8 +321,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 });
+    if (parsed.background) {
+        handoff = await listenForHandoff({
+            dir: m2Dir,
+            port: parsed.port,
+            arm: (c) => pairing.armCommitment(c),
+            status: (c) => ({ ...pairing.commitmentStatus(c), ...(lastRejected ? { rejected: lastRejected } : {}) }),
+            log,
+        });
+    }
     const lifetime = backgroundLifetimeMs(parsed);
     if (lifetime !== null) {
         setTimeout(() => {

package/dist/bridge/pairing.js

@@ -192,6 +192,25 @@ export class PairingManager {
         this.commitment = { value: Buffer.from(commitment, 'base64url'), armedAt };
         return armedAt + CODE_TTL_MS;
     }
+    /**
+     * 承诺的状态（change desktop-bridge-launcher D15）：M2 Mac 客户端运行启动器交上承诺之后，用它查页面有没有真的配上。
+     * 只读，不改变任何状态；比较用常量时间。只看两个槽：挂着的（10 分钟内）与最近一次用掉的 —— 被更新的承诺替换、过期、
+     * bridge 重启过的都是 unknown，调用方按「还没确认」处理。
+     */
+    commitmentStatus(commitment) {
+        if (!isPairCommitment(commitment))
+            return { state: 'unknown' };
+        const value = Buffer.from(commitment, 'base64url');
+        const armed = this.commitment;
+        if (armed && armed.value.length === value.length && timingSafeEqual(armed.value, value) && this.now() - armed.armedAt <= CODE_TTL_MS) {
+            return { state: 'waiting', until: armed.armedAt + CODE_TTL_MS };
+        }
+        const consumed = this.consumed;
+        if (consumed && consumed.value.length === value.length && timingSafeEqual(consumed.value, value)) {
+            return { state: 'paired', origin: consumed.origin, at: consumed.usedAt };
+        }
+        return { state: 'unknown' };
+    }
     /**
      * 页面在 hello 里出示 S。对不上不计入错码次数：S 有 32 字节、承诺有 128 bit，不存在可猜性，
      * 计入只会让多标签页、旧 S 这类无害的不匹配把用户锁住。锁定期间一律不成立 —— 「锁定只能重启解除」不设例外。

package/dist/bridge/processes.js

@@ -48,6 +48,8 @@ export class ProcessManager {
     processes = new Map();
     /** 已调用 spawn、还没等到 'spawn' 事件的进程（按 owner 计）：也要计入上限，否则同一批并发的 start 能突破上限 */
     starting = new Map();
+    /** bridge 在卸载自己：之后不再拉起任何 agent（`close`） */
+    closed = false;
     constructor(options) {
         this.options = options;
     }
@@ -71,8 +73,17 @@ export class ProcessManager {
         else
             this.starting.delete(ownerId);
     }
+    /**
+     * 不再拉起新的 agent（bridge 卸载自己时调用，change bridge-uninstall-from-page review r1 N1）：卸载开始前已在途、
+     * 还卡在检测阶段的 process/start 之后走到这里也会被拒，不会在卸载脚本运行时从正在被删的适配器目录拉起 agent。已在跑的由调用方停。
+     */
+    close() {
+        this.closed = true;
+    }
     /** 等到子进程真正启动（'spawn' 事件）才返回，启动失败（如 ENOENT）以 ProcessError 拒绝 */
     start(ownerId, agent, launch) {
+        if (this.closed)
+            return Promise.reject(new ProcessError('spawn_failed', 'the bridge is shutting down and starts no new agents'));
         if (this.countFor(ownerId) >= (this.options.maxPerOwner ?? MAX_PROCESSES_PER_OWNER)) {
             return Promise.reject(new ProcessError('too_many_processes', 'too many agent processes for this page'));
         }

package/dist/bridge/protocol.js

@@ -73,6 +73,7 @@ export const BRIDGE_METHODS = [
     'process/stop',
     'agent/authorize',
     'agent/authorize-cancel',
+    'bridge/uninstall',
 ];
 export const BRIDGE_CLOSE_CODES = {
     normal: 1000,

package/dist/bridge/security.js

@@ -33,6 +33,7 @@ export function isAllowedHost(host, port) {
 export function isLoopbackAddress(address) {
     return address === '127.0.0.1' || address === '::ffff:127.0.0.1' || address === '::1';
 }
+const MAX_REPORTED_ORIGIN_CHARS = 200;
 /**
  * 拒绝时返回 HTTP 状态，由调用方直接写回并销毁 socket，不完成握手。
  * 403 而不是「握手后再关」：不对非白名单页面完成任何握手。注意这挡不住「探测 bridge 是否在运行」——
@@ -46,7 +47,10 @@ export function checkUpgrade(info, port, origins) {
         return { ok: false, status: 403, reason: `remote ${info.remoteAddress ?? 'unknown'}` };
     if (!isAllowedHost(info.host, port))
         return { ok: false, status: 403, reason: `host ${info.host ?? 'missing'}` };
-    if (!isAllowedOrigin(info.origin, origins))
-        return { ok: false, status: 403, reason: `origin ${info.origin ?? 'missing'}` };
+    if (!isAllowedOrigin(info.origin, origins)) {
+        if (info.origin === undefined)
+            return { ok: false, status: 403, reason: 'origin missing' };
+        return { ok: false, status: 403, reason: `origin ${info.origin}`, rejectedOrigin: info.origin.slice(0, MAX_REPORTED_ORIGIN_CHARS) };
+    }
     return { ok: true };
 }

package/dist/bridge/self-test.js

@@ -12,6 +12,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ADAPTERS } from './adapters.js';
 import { bundledNpmCli } from './npm-command.js';
+import { uninstallScriptPath } from './uninstall.js';
 /** 返回发现的问题（英文，写进 update.log）；空数组 = 通过 */
 export function selfTestProblems(input) {
     const exists = input.exists ?? existsSync;
@@ -26,5 +27,9 @@ export function selfTestProblems(input) {
     const npm = bundledNpmCli(input.execPath);
     if (!exists(npm))
         problems.push(`missing ${npm}`);
+    // bridge/uninstall 运行的就是它（change bridge-uninstall-from-page D3）：缺了就不切换到这个版本
+    const uninstaller = uninstallScriptPath(input.packageRoot);
+    if (!exists(uninstaller))
+        problems.push(`missing ${uninstaller}`);
     return problems;
 }

package/dist/bridge/server.js

@@ -9,8 +9,9 @@
  * - 握手后第一条消息必须是 hello；未配对的连接只能调用 pair，其余已知方法与 acp 帧一律 not_paired。
  *   连接只有两种方式成为已配对：hello 带有效 token，或 hello 的 pairSecret 与启动命令的承诺一致（pairing.ts 文件头）。
  * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、授权动作（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
- *   agent/authorize 与 agent/authorize-cancel 的 params 只能有规定的键，多一个就 bad_message（分派在 auth-call.ts，命令清单写死在 authorize.ts）。
+ *   方法分派在 call-dispatch.ts；agent/authorize 与 agent/authorize-cancel 的 params 只能有规定的键，多一个就 bad_message（auth-call.ts，命令清单写死在 authorize.ts）。
  * - 页面发给 agent 的 ACP 行禁止含换行，并经 acp-guard.ts 检查：只能用白名单里的方法、会话目录固定为 bridge 的 cwd、不能让 agent 额外拉起 MCP 服务器。
+ * - bridge/uninstall（0.8.0，uninstall-call.ts）：开始后拒绝新连接与一切其他帧（握手与配对会写盘、重建 ~/.m2canvas），端口占到退出，结果回出去后退出。
  *
  * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责）。
  * 登录 / m2 授权只代跑写死清单里的命令，授权页由用户在浏览器里亲自完成（authorize.ts）；授权链接只发给发起的连接，不进终端日志。
@@ -18,16 +19,14 @@
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-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 { KILL_GRACE_MS, ProcessManager } from './processes.js';
+import { handleCall } from './call-dispatch.js';
 import { AuthorizationManager } from './authorize.js';
 import { BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
 import { checkPageAcpLine } from './acp-guard.js';
 import { checkUpgrade } from './security.js';
 import { BridgeFailure } from './service.js';
+import { startUninstall } from './uninstall-call.js';
 export const HELLO_TIMEOUT_MS = 10_000;
 export const UNPAIRED_TIMEOUT_MS = 10 * 60 * 1000;
 export const MAX_UNPAIRED_CONNECTIONS = 4;
@@ -42,7 +41,7 @@ function isMethod(value) {
     return typeof value === 'string' && BRIDGE_METHODS.includes(value);
 }
 function rejectUpgrade(socket, status) {
-    const text = status === 403 ? 'Forbidden' : 'Not Found';
+    const text = status === 403 ? 'Forbidden' : status === 404 ? 'Not Found' : 'Service Unavailable';
     socket.end(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
     socket.destroy();
 }
@@ -59,6 +58,10 @@ export function startBridgeServer(options) {
             conn.ws.send(JSON.stringify(frame));
     };
     const sendError = (conn, id, error) => send(conn, { type: 'error', id, error });
+    /** 等数据写进 socket 再完成：bridge/uninstall 回复之后紧接着关连接、退出 */
+    const sendAndWait = (conn, frame) => new Promise((done) => (conn.ws.readyState === conn.ws.OPEN ? conn.ws.send(JSON.stringify(frame), () => done()) : done()));
+    /** bridge/uninstall 已开始（D3 ⓪）：不再接受新连接，已有连接上的其他帧一律拒绝 */
+    let uninstalling = false;
     const processes = new ProcessManager({
         env: options.agentEnv,
         cwd: options.cwd,
@@ -97,6 +100,16 @@ export function startBridgeServer(options) {
                 send(owner, { type: 'event', event: 'auth/link', data });
         },
     };
+    const uninstallContext = {
+        uninstaller: options.uninstall,
+        processes,
+        authorizations,
+        killGraceMs: options.timing?.killGraceMs ?? KILL_GRACE_MS,
+        stopAccepting: () => {
+            uninstalling = true;
+        },
+        log,
+    };
     const unpairedCount = () => [...connections.values()].filter((conn) => !conn.paired).length;
     const markPaired = (conn) => {
         conn.paired = true;
@@ -104,56 +117,20 @@ export function startBridgeServer(options) {
             clearTimeout(conn.timer);
         conn.timer = null;
     };
-    async function handleCall(conn, id, method, params) {
-        if (method === 'pair') {
-            const token = handlePairCall(options.pairing, conn.origin, params);
-            markPaired(conn);
-            log(`Paired with ${conn.origin}.`);
-            return { token, cwd: options.cwd, idleExpiryDays: TOKEN_IDLE_DAYS };
-        }
-        if (!conn.paired)
-            throw new BridgeFailure('not_paired', 'pair this page first');
-        if (method === 'process/stop') {
-            const processId = params.processId;
-            if (typeof processId !== 'string' || !processes.stop(conn.id, processId))
-                throw new BridgeFailure('process_not_found', 'no such process on this connection');
-            return {};
-        }
-        if (method === 'agents/list')
-            return { agents: await options.service.list() };
-        if (method === 'agent/authorize' || method === 'agent/authorize-cancel')
-            return handleAuthCall(authContext, conn.id, method, params);
-        const agent = params.agent;
-        if (!isBridgeAgentId(agent))
-            throw new BridgeFailure('unknown_agent', `unknown agent ${String(agent)}`);
-        switch (method) {
-            case 'agent/prepare':
-                return { agent, adapter: await options.service.prepare(agent) };
-            case 'agent/precheck':
-                return options.service.precheck(agent);
-            case 'm2/configure':
-                log(`Page asked to add M2 to ${agent}'s MCP config.`);
-                return { agent, ...(await options.service.configure(agent)) };
-            case 'process/start': {
-                const launch = await options.service.launch(agent);
-                try {
-                    const processId = await processes.start(conn.id, agent, launch);
-                    // 启动期间页面已断开：没有人会再停它，立刻清理
-                    if (!connections.has(conn.id))
-                        processes.stopOwner(conn.id);
-                    log(`Started ${agent}.`);
-                    return { processId, agent, cwd: options.cwd };
-                }
-                catch (error) {
-                    if (error instanceof ProcessError)
-                        throw new BridgeFailure(error.code, error.message);
-                    throw error;
-                }
-            }
-        }
-        // 未知方法在调用前已被 isMethod 拦下；走到这里说明 BRIDGE_METHODS 与上面的分支不一致
-        throw new BridgeFailure('internal', `unhandled method ${method} (call ${id})`);
-    }
+    const callContext = {
+        cwd: options.cwd,
+        pairing: options.pairing,
+        service: options.service,
+        processes,
+        auth: authContext,
+        log,
+        isConnected: (connectionId) => connections.has(connectionId),
+        markPaired: (connectionId) => {
+            const conn = connections.get(connectionId);
+            if (conn)
+                markPaired(conn);
+        },
+    };
     function onHello(conn, frame) {
         const protocols = Array.isArray(frame.protocols) ? frame.protocols.filter((value) => typeof value === 'number') : [];
         if (frame.type !== 'hello' || protocols.length === 0) {
@@ -222,6 +199,13 @@ export function startBridgeServer(options) {
         catch {
             frame = null;
         }
+        if (uninstalling) {
+            // 卸载开始后：不再握手（带 token 的 hello 会刷新使用时间、写配对文件），也不再处理任何调用
+            if (!conn.hello)
+                return conn.ws.close(BRIDGE_CLOSE_CODES.goingAway, 'bridge is uninstalling');
+            const id = isObject(frame) && typeof frame.id === 'string' && frame.id.length > 0 && frame.id.length <= MAX_CALL_ID ? frame.id : null;
+            return sendError(conn, id, { code: 'uninstalling', message: 'this bridge is uninstalling itself' });
+        }
         if (!conn.hello) {
             if (isObject(frame))
                 onHello(conn, frame);
@@ -257,7 +241,13 @@ export function startBridgeServer(options) {
             if (!isMethod(method))
                 return sendError(conn, id, { code: 'unknown_method', message: `unknown method ${String(method)}` });
             const params = isObject(frame.params) ? frame.params : {};
-            handleCall(conn, id, method, params).then((result) => send(conn, { type: 'result', id, result }), (error) => {
+            if (method === 'bridge/uninstall') {
+                const refusal = startUninstall(uninstallContext, { paired: conn.paired, params: frame.params, reply: (result) => sendAndWait(conn, { type: 'result', id, result }) });
+                if (refusal)
+                    sendError(conn, id, refusal);
+                return;
+            }
+            handleCall(callContext, conn, id, method, params).then((result) => send(conn, { type: 'result', id, result }), (error) => {
                 if (error instanceof BridgeFailure)
                     sendError(conn, id, { code: error.code, message: error.message, ...(error.data === undefined ? {} : { data: error.data }) });
                 else {
@@ -275,10 +265,15 @@ export function startBridgeServer(options) {
     });
     const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES });
     http.on('upgrade', (req, socket, head) => {
+        // 卸载开始后不再接受新连接；监听本身留到退出才关 —— 端口一直占着，卸载期间被拉起的新 bridge 撞端口、认不出而退出（review r1 S1）
+        if (uninstalling)
+            return rejectUpgrade(socket, 503);
         const port = http.address()?.port ?? options.port;
         const decision = checkUpgrade({ origin: req.headers.origin, host: req.headers.host, remoteAddress: req.socket.remoteAddress, path: req.url }, port, options.allowedOrigins);
         if (!decision.ok) {
             rejectLog.note(decision.reason);
+            if (decision.rejectedOrigin !== undefined)
+                options.onOriginRejected?.(decision.rejectedOrigin);
             rejectUpgrade(socket, decision.status);
             return;
         }

package/dist/bridge/uninstall-call.js

@@ -0,0 +1,47 @@
+async function stopAgents(ctx) {
+    ctx.processes.close();
+    ctx.authorizations.killAllNow();
+    ctx.processes.stopAll();
+    const deadline = Date.now() + ctx.killGraceMs;
+    while (ctx.processes.size > 0 && Date.now() < deadline)
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    ctx.processes.killAllNow();
+}
+async function perform(ctx, uninstaller, request) {
+    ctx.stopAccepting();
+    ctx.log('Page asked to uninstall the M2 bridge. No longer accepting pages; stopping agents…');
+    try {
+        uninstaller.begin();
+        await stopAgents(ctx);
+        let result;
+        try {
+            result = await uninstaller.run();
+        }
+        catch (error) {
+            ctx.log(`Uninstall failed with an internal error: ${error instanceof Error ? error.message : String(error)}`);
+            result = { outcome: 'failed', kept: null, message: 'M2 bridge: the uninstall stopped because of an internal error. Run the uninstall command in Terminal.' };
+        }
+        ctx.log(`Uninstall ${result.outcome}: ${result.message}`);
+        await request.reply(result);
+    }
+    finally {
+        uninstaller.exit();
+    }
+}
+/** 开始卸载；不能开始时返回要回给页面的错误（什么都不做） */
+export function startUninstall(ctx, request) {
+    if (!request.paired)
+        return { code: 'not_paired', message: 'pair this page first' };
+    // 只能省略或是空对象：null、数组、字符串都不当成 {}；自有属性一个都不能有（`__proto__` 之类的也算）—— 页面不能传任何影响卸载的东西
+    const { params } = request;
+    const empty = params === undefined || (typeof params === 'object' && params !== null && !Array.isArray(params) && Object.keys(params).length === 0);
+    if (!empty)
+        return { code: 'bad_message', message: 'bridge/uninstall takes no params' };
+    const uninstaller = ctx.uninstaller;
+    if (!uninstaller)
+        return { code: 'uninstall_unavailable', message: 'only a bridge started in the background by the M2 launcher on macOS can uninstall itself' };
+    // stopAccepting 在 perform 的同步部分执行：本函数返回之前，后续到达的帧已经会被拒。
+    // 兜住意外的 rejection：未处理的 rejection 会让 bridge 直接退出，跳过收尾
+    perform(ctx, uninstaller, request).catch((error) => ctx.log(`Uninstall failed with an internal error: ${error instanceof Error ? error.message : String(error)}`));
+    return null;
+}

package/dist/bridge/uninstall.js

@@ -0,0 +1,88 @@
+/**
+ * `bridge/uninstall` 在 main 一侧的执行（change bridge-uninstall-from-page D3 ②③④）：bridge 运行随包发布的卸载脚本卸载自己。
+ * 门槛、停止接受新连接、停 agent、回复与退出在 server.ts / uninstall-call.ts；本文件只管「怎么跑脚本、怎么读结果」。
+ *
+ * 不在 TypeScript 里再写一份删除逻辑：删除范围只有 `install/uninstall.sh` 一份实现（`connect/local-bridge` 契约 15「卸载脚本」），
+ * 终端、agent 应用、M2 Mac 客户端运行的是 m2ui.ai 上它的逐字副本（`connect:install-assets -- --check` 锁住）。
+ *
+ * 维护约束：
+ * - **先删自己的状态文件，再运行脚本。** 脚本只停它能从状态文件找到的 M2 bridge（`--stop` 发 SIGTERM）；自己的还在，
+ *   脚本就会停掉自己，收尾会先关掉全部连接 —— 页面收不到结果。删不掉就不运行脚本，如实回 failed。
+ * - **脚本会删掉 bridge 自己所在的安装目录**（含正在运行的 node 与已加载的模块，verification §3 实测仍能回复）：
+ *   本文件与卸载之后会走到的代码都只能用静态 import，不得动态加载模块（删除后会 ERR_MODULE_NOT_FOUND）。
+ * - 脚本用白名单环境运行（调用方传 `buildAgentEnv()`）：里面没有沙箱标记，脚本不会误判自己在 agent 沙箱里（grep-summary §3）。
+ */
+import { join } from 'node:path';
+/** 脚本对每个还在运行的 bridge 最多等 8 + 3 秒（`--stop`）；通常只有自己，而自己已从状态文件里拿掉 */
+export const UNINSTALL_SCRIPT_TIMEOUT_MS = 60_000;
+/** 页面只显示一行，太长的截掉 */
+const MAX_MESSAGE_CHARS = 1000;
+const RESULT_PREFIX = 'M2 bridge:';
+/** 包内卸载脚本的位置（`package.json` 的 files 带上了它） */
+export function uninstallScriptPath(packageRoot) {
+    return join(packageRoot, 'install', 'uninstall.sh');
+}
+function clip(message) {
+    return message.length > MAX_MESSAGE_CHARS ? `${message.slice(0, MAX_MESSAGE_CHARS - 3)}...` : message;
+}
+/** 输出里最后一行以 `M2 bridge:` 开头的（契约 15：脚本的结果行） */
+function resultLine(output) {
+    const lines = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith(RESULT_PREFIX));
+    return lines[lines.length - 1] ?? null;
+}
+/** 按退出码与结果行组结果：退出 0 才算卸载了；超时、没能运行、没有结果行都写 bridge 自己的说明，不留空 */
+export function uninstallResult(exec, kept, timeoutMs = UNINSTALL_SCRIPT_TIMEOUT_MS) {
+    const line = resultLine(exec.stdout) ?? resultLine(exec.stderr);
+    if (exec.code === 0)
+        return { outcome: 'uninstalled', kept, message: clip(line ?? `${RESULT_PREFIX} uninstalled.`) };
+    if (exec.timedOut) {
+        return { outcome: 'failed', kept, message: `${RESULT_PREFIX} the uninstaller didn't finish within ${Math.round(timeoutMs / 1000)} seconds. Run the uninstall command in Terminal.` };
+    }
+    if (exec.code === null && exec.signal) {
+        return { outcome: 'failed', kept, message: `${RESULT_PREFIX} the uninstaller was stopped (${exec.signal}). Run the uninstall command in Terminal.` };
+    }
+    if (exec.code === null)
+        return { outcome: 'failed', kept, message: `${RESULT_PREFIX} couldn't run the uninstaller. Run the uninstall command in Terminal.` };
+    return { outcome: 'failed', kept, message: clip(line ?? `${RESULT_PREFIX} the uninstaller exited with code ${exec.code}. Run the uninstall command in Terminal.`) };
+}
+/** 不抛出：任何一步出错都变成 failed 结果，server 照常回复并退出 */
+export async function runSelfUninstall(deps) {
+    deps.stopCommands();
+    try {
+        deps.forgetSelf();
+    }
+    catch {
+        return {
+            outcome: 'failed',
+            kept: null,
+            message: `${RESULT_PREFIX} couldn't remove its own state file, so it didn't run the uninstaller. Run the uninstall command in Terminal.`,
+        };
+    }
+    try {
+        deps.closeHandoff();
+    }
+    catch {
+        // socket 文件删不掉不影响卸载：脚本会把停掉的 bridge 的 socket 一并删掉
+    }
+    const timeoutMs = deps.timeoutMs ?? UNINSTALL_SCRIPT_TIMEOUT_MS;
+    const result = await deps.exec('/bin/sh', [deps.scriptPath], { env: deps.env, cwd: deps.home, timeoutMs, maxOutput: 64 * 1024 });
+    return uninstallResult(result, deps.exists(deps.workspace) ? deps.workspace : null, timeoutMs);
+}
+/**
+ * main 提供给 server 的卸载能力（review r1 S2 / S3：接线抽成可单测的工厂）。
+ * begin 在 ⓪ 就停新安装、杀一次性命令（与停止接受新连接同时）；run 在 ② 再来一遍，收掉 ① 期间才走到这里的在途调用。
+ */
+export function createSelfUninstaller(deps) {
+    const stopCommands = () => {
+        deps.stopInstalling();
+        deps.killExecs();
+    };
+    return {
+        begin: stopCommands,
+        run: () => runSelfUninstall({ ...deps, stopCommands }),
+        exit: deps.exit,
+    };
+}

package/install/uninstall.sh

@@ -0,0 +1,125 @@
+#!/bin/sh
+# M2 local connection uninstaller: https://m2ui.ai/connect/uninstall.sh
+#   curl -fsSL https://m2ui.ai/connect/uninstall.sh | sh
+#
+# What it does:
+#   1. Stops the M2 bridge if one is running (only a bridge it can recognize, and only with
+#      SIGTERM, so it shuts down its agents cleanly).
+#   2. Removes what the installer put in ~/.m2canvas: runtime, bridge, bin, logs, acp-adapters,
+#      the pairing records, the bridge state files, pairing-handoff sockets and leftover
+#      handoff files.
+#   3. Removes ~/.m2canvas/workspace only if it is empty; otherwise keeps it and prints its path.
+#      Removes ~/.m2canvas itself only if nothing else is left in it.
+# It does not touch your agents' M2 settings (set up by npx @m2canvas/connect, they work
+# without the bridge) or any Node.js you installed yourself.
+#
+# Maintenance: keep this file ASCII-only, POSIX sh, and write every variable as ${VAR}.
+# The layout must match packages/connect/src/bridge/install-layout.ts.
+# The source is packages/connect/install/uninstall.sh; it ships in the npm package (a running bridge uses it
+# to uninstall itself) and public/connect/uninstall.sh is a generated copy (npm run connect:install-assets).
+
+say() {
+  printf 'M2 bridge: %s\n' "$*"
+}
+
+main() {
+  if [ -n "${CODEX_SANDBOX:-}" ]; then
+    say "Codex is running this command in its sandbox, where files in your home folder can't be removed. In Codex, switch the permission mode to Full access and run it again, or run it in Terminal."
+    exit 0
+  fi
+  if [ "${SANDBOX_RUNTIME:-}" = "1" ]; then
+    say "Claude is running this command in its sandbox, where files in your home folder can't be removed. Run this exact command again outside the sandbox."
+    exit 1
+  fi
+  case "${HOME:-}" in
+    /?*) ;;
+    *)
+      say "HOME is not set."
+      exit 1
+      ;;
+  esac
+
+  M2_HOME="${HOME}/.m2canvas"
+  if [ ! -d "${M2_HOME}" ]; then
+    say "nothing to uninstall."
+    exit 0
+  fi
+
+  # 1. Stop running bridges with the installed bridge itself (it knows how to recognize one).
+  CURRENT="$(readlink "${M2_HOME}/bridge/current" 2>/dev/null)"
+  NODE="$(cat "${M2_HOME}/bridge/${CURRENT}/node-path" 2>/dev/null)"
+  CLI="${M2_HOME}/bridge/${CURRENT}/node_modules/@m2canvas/connect/dist/cli.js"
+  #    A bridge that didn't stop keeps its state file, so a later --replace can still recognize it.
+  STILL_RUNNING=""
+  if [ -n "${CURRENT}" ] && [ -x "${NODE}" ] && [ -f "${CLI}" ]; then
+    for STATE in "${M2_HOME}"/bridge-*.json; do
+      [ -f "${STATE}" ] || continue
+      PORT="${STATE##*/bridge-}"
+      PORT="${PORT%.json}"
+      case "${PORT}" in
+        "" | *[!0-9]*) continue ;;
+      esac
+      if ! "${NODE}" "${CLI}" bridge --stop --port "${PORT}" </dev/null; then
+        STILL_RUNNING="${STILL_RUNNING} ${PORT}"
+      fi
+    done
+  else
+    # Without a working bridge it can't recognize what is running, so it stops nothing. A state file whose
+    # process is still alive is kept and reported (that process may be the bridge); the others are stale.
+    echo "The installed bridge is incomplete, so a running bridge (if any) was not stopped."
+    for STATE in "${M2_HOME}"/bridge-*.json; do
+      [ -f "${STATE}" ] || continue
+      PORT="${STATE##*/bridge-}"
+      PORT="${PORT%.json}"
+      PID="$(sed -n 's/.*"pid"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "${STATE}" | head -n 1)"
+      if [ -n "${PID}" ] && kill -0 "${PID}" 2>/dev/null; then
+        STILL_RUNNING="${STILL_RUNNING} ${PORT}"
+      fi
+    done
+  fi
+
+  # 2. Remove what the installer created, and check that it is really gone.
+  FAILED=""
+  for NAME in runtime bridge bin logs acp-adapters bridge-pairings.json; do
+    rm -rf "${M2_HOME:?}/${NAME}"
+    if [ -e "${M2_HOME}/${NAME}" ]; then
+      FAILED="${FAILED} ${M2_HOME}/${NAME}"
+    fi
+  done
+  # State files and pairing-handoff sockets of the bridges that stopped (a running bridge removes its own socket when it exits).
+  for STATE in "${M2_HOME}"/bridge-*.json "${M2_HOME}"/bridge-*.sock; do
+    [ -e "${STATE}" ] || continue
+    PORT="${STATE##*/bridge-}"
+    PORT="${PORT%.*}"
+    case " ${STILL_RUNNING} " in
+      *" ${PORT} "*) continue ;;
+    esac
+    rm -f "${STATE}"
+  done
+  # One-time pairing-handoff files: the process that wrote one removes it within seconds, so any left over is stale.
+  rm -f "${M2_HOME}"/handoff-*.pending
+
+  # 3. Keep the workspace if anything is in it (the agents may have created files there).
+  KEPT=""
+  if [ -d "${M2_HOME}/workspace" ] && ! rmdir "${M2_HOME}/workspace" 2>/dev/null; then
+    KEPT="${M2_HOME}/workspace"
+  fi
+  rmdir "${M2_HOME}" 2>/dev/null
+
+  # The last line is what the agent repeats to the user: it must not claim success that didn't happen.
+  if [ -n "${FAILED}" ]; then
+    say "couldn't remove${FAILED}. Remove them yourself, or run this again."
+    exit 1
+  fi
+  if [ -n "${STILL_RUNNING}" ]; then
+    say "uninstalled, but the M2 bridge on port${STILL_RUNNING} is still running. Restart your Mac to stop it."
+    exit 1
+  fi
+  if [ -n "${KEPT}" ]; then
+    say "uninstalled. Kept ${KEPT} because it has files in it; delete it yourself if you don't need them."
+  else
+    say "uninstalled."
+  fi
+}
+
+main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.7.2",
+  "version": "0.8.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": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "adapters"
+    "adapters",
+    "install/uninstall.sh"
   ],
   "engines": {
     "node": ">=18"