@m2canvas/connect 0.7.3 → 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/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/main.js

@@ -9,6 +9,7 @@
  * 后台模式（`--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 } from 'node:path';
@@ -22,6 +23,7 @@ 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 } from './pairing.js';
 import { BRIDGE_AGENT_IDS, BRIDGE_WS_PATH } from './protocol.js';
@@ -32,6 +34,7 @@ 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;
 const LABELS = {
     claude: 'Claude Code',
@@ -196,6 +199,23 @@ export async function runBridge(argv) {
     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,
@@ -211,6 +231,7 @@ export async function runBridge(argv) {
         service,
         agentEnv: buildAgentEnv(),
         allowedOrigins: origins,
+        uninstall: uninstaller,
         onOriginRejected: (origin) => {
             lastRejected = { origin, at: Date.now() };
         },

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/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,6 +265,9 @@ 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) {

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.3",
+  "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"