@m2canvas/connect 0.7.3 → 0.9.0

package/README.md

@@ -39,7 +39,8 @@ 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.
+- **Checking an agent before use.** Before starting an agent, M2 asks the bridge whether it is signed in and has M2 set up (commands such as `claude auth status` and `claude mcp list`; `claude mcp list` starts the MCP servers you configured in order to check them). From 0.9.0 the bridge runs this check for Claude Code and Codex once when it starts, and remembers a result that passed, so opening another project doesn't wait for it again. It checks again when you click "Check again" in M2 and when M2 adds itself to an agent or signs in for you; when a page uses a remembered result that is more than 5 minutes old, it also checks again in the background and tells M2 if the result no longer holds. There is no periodic check. Results that need you to do something are never remembered, and nothing is written to disk.
 - Cursor runs as `agent acp`, OpenCode as `opencode acp`, Qoder as `qodercli --acp`.
 
 Agent sessions start in that directory.
@@ -59,6 +60,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,65 @@
+/**
+ * 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':
+            // 带连接 id：每条连接第一次查这家可用缓存，之后一律真跑（契约 18）
+            return ctx.service.precheck(agent, conn.id);
+        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,12 +9,13 @@
  * 后台模式（`--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';
 import { fileURLToPath } from 'node:url';
 import { home, isExecutable, which } from '../system.js';
-import { AdapterManager, ADAPTERS } from './adapters.js';
+import { AdapterManager, ADAPTERS, isAdapterAgent } 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';
@@ -22,17 +23,22 @@ 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';
 import { resolveNpmCommand } from './npm-command.js';
 import { allowedOrigins } from './security.js';
+import { prewarmPrechecks } from './precheck-cache.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;
+/** 启动时预热预检的 agent（契约 18；用户 2026-11-04 拍板 B-P1：随包的两家，不管用没用过） */
+const PREWARM_AGENTS = ['claude', 'codex'];
 const LABELS = {
     claude: 'Claude Code',
     codex: 'Codex',
@@ -188,6 +194,9 @@ export async function runBridge(argv) {
         cliPath: fileURLToPath(new URL('../cli.js', import.meta.url)),
         platform: process.platform,
         expectAvailable: () => isExecutable(EXPECT_PATH),
+        // 出现过「通过」之后一次真跑没通过：告诉之前可能拿到通过的页面（尽力收回，契约 18）
+        onPrecheckRevoked: (result) => server?.broadcast('precheck/updated', result),
+        log,
     });
     const version = packageVersion();
     const origins = allowedOrigins(parsed.dev);
@@ -196,6 +205,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 +237,7 @@ export async function runBridge(argv) {
         service,
         agentEnv: buildAgentEnv(),
         allowedOrigins: origins,
+        uninstall: uninstaller,
         onOriginRejected: (origin) => {
             lastRejected = { origin, at: Date.now() };
         },
@@ -309,6 +336,13 @@ export async function runBridge(argv) {
             log,
         });
     }
+    // 预热（契约 18，用户 2026-11-04 拍板 B-P1）：信号处理装好之后再起，收尾时 killActiveExecs 能杀掉它的命令；不等它，页面来查会加入
+    void prewarmPrechecks({
+        agents: PREWARM_AGENTS,
+        ready: (agent) => isAdapterAgent(agent) && adapters.isReady(agent),
+        warm: (agent) => service.warmPrecheck(agent),
+        log,
+    });
     const lifetime = backgroundLifetimeMs(parsed);
     if (lifetime !== null) {
         setTimeout(() => {

package/dist/bridge/precheck-cache.js

@@ -0,0 +1,144 @@
+/** 缓存最长可用这么久；之后的第一次查询真跑 */
+export const PRECHECK_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/** 用到的缓存比这更旧时，同时在后台复查一次 */
+export const PRECHECK_REFRESH_AFTER_MS = 5 * 60 * 1000;
+/** 能缓存的「通过」：比页面的 precheckPasses 严 —— 登录 unknown、已跳过的 m2 unknown 页面放行，这里都不记 */
+export function isCacheablePrecheck(result) {
+    const login = result.login.state;
+    const m2 = result.m2.state;
+    return (login === 'logged_in' || login === 'not_required') && (m2 === 'ready' || m2 === 'unverified');
+}
+export class PrecheckCache {
+    deps;
+    slots = new Map();
+    /** 每条连接查过哪几家；连接关闭时 forgetConnection */
+    asked = new Map();
+    sequence = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 页面连接上的一次 `agent/precheck` */
+    forConnection(connectionId, agent) {
+        const asked = this.asked.get(connectionId) ?? new Set();
+        this.asked.set(connectionId, asked);
+        if (asked.has(agent))
+            return this.fresh(agent, 'same page checked again');
+        asked.add(agent);
+        const slot = this.slot(agent);
+        const cached = slot.cached;
+        if (cached && this.deps.usable(agent)) {
+            const age = this.deps.now() - cached.startedAt;
+            // 年龄为负（系统时钟往回拨过）当作过期：不能让它一直「不到 5 分钟」而永不复查（review r1 N2）
+            if (age >= 0 && age <= PRECHECK_CACHE_MAX_AGE_MS) {
+                const refresh = age > PRECHECK_REFRESH_AFTER_MS;
+                this.deps.log(`Precheck of ${agent} for a page: used the result from ${Math.round(age / 1000)}s ago${refresh ? ' (checking again in the background)' : ''}.`);
+                if (refresh)
+                    this.warm(agent, 'background re-check').catch(() => undefined); // 结果与出错由 start 记日志
+                slot.passHandedOut = true;
+                return Promise.resolve(cached.result);
+            }
+        }
+        if (slot.shared) {
+            this.deps.log(`Precheck of ${agent} for a page: joined a check already running.`);
+            return slot.shared;
+        }
+        return this.warm(agent, 'first check for a page');
+    }
+    /** 独立的一次真跑（同一连接的再查、授权结束后的重查）：不加入任何在跑的，结果照常写回 */
+    fresh(agent, reason) {
+        return this.start(agent, reason);
+    }
+    /** 可共享的真跑：这家已有一次在跑就加入它，否则起一次 */
+    warm(agent, reason) {
+        const slot = this.slot(agent);
+        if (slot.shared)
+            return slot.shared;
+        const running = this.start(agent, reason);
+        slot.shared = running;
+        const clear = () => {
+            if (slot.shared === running)
+                slot.shared = null;
+        };
+        running.then(clear, clear);
+        return running;
+    }
+    /** 写配置 / 授权开始时：这家的状态马上要变 */
+    invalidate(agent) {
+        const slot = this.slot(agent);
+        slot.generation += 1;
+        slot.cached = null;
+        slot.latest = null;
+        slot.shared = null;
+    }
+    forgetConnection(connectionId) {
+        this.asked.delete(connectionId);
+    }
+    slot(agent) {
+        let slot = this.slots.get(agent);
+        if (!slot) {
+            slot = { generation: 0, cached: null, latest: null, lastWrite: 0, passHandedOut: false, shared: null };
+            this.slots.set(agent, slot);
+        }
+        return slot;
+    }
+    start(agent, reason) {
+        const slot = this.slot(agent);
+        const run = { sequence: ++this.sequence, generation: slot.generation, startedAt: this.deps.now() };
+        return this.deps.run(agent).then((result) => {
+            const seconds = ((this.deps.now() - run.startedAt) / 1000).toFixed(1);
+            this.deps.log(`Precheck of ${agent} (${reason}): ${verdict(result)} in ${seconds}s.`);
+            this.write(agent, run, result);
+            // 被更晚开始、已写入的真跑推翻：交出那个更新的结论。不看代数：latest 作废时清空、之后只由作废后开始的真跑写入，必然更新
+            const handedOut = run.sequence < slot.lastWrite && slot.latest ? slot.latest : result;
+            if (isCacheablePrecheck(handedOut))
+                slot.passHandedOut = true;
+            return handedOut;
+        }, (error) => {
+            this.deps.log(`Precheck of ${agent} (${reason}) did not run: ${error instanceof Error ? error.message : String(error)}`);
+            // 前置条件不满足：原来的通过不再可信，删掉；不推送 —— 调用方自己会拿到这个错误
+            if (this.canWrite(slot, run)) {
+                slot.lastWrite = run.sequence;
+                slot.cached = null;
+                slot.latest = null;
+            }
+            throw error;
+        });
+    }
+    canWrite(slot, run) {
+        return run.generation === slot.generation && run.sequence > slot.lastWrite;
+    }
+    write(agent, run, result) {
+        const slot = this.slot(agent);
+        if (!this.canWrite(slot, run))
+            return;
+        slot.lastWrite = run.sequence;
+        slot.latest = result;
+        if (isCacheablePrecheck(result)) {
+            slot.cached = { result, startedAt: run.startedAt };
+            return;
+        }
+        slot.cached = null;
+        if (slot.passHandedOut) {
+            slot.passHandedOut = false;
+            this.deps.onRevoked(agent, result);
+        }
+    }
+}
+function verdict(result) {
+    return isCacheablePrecheck(result) ? 'passed' : `not passed (sign-in ${result.login.state}, M2 ${result.m2.state})`;
+}
+/**
+ * bridge 开始监听之后预热（design D6，用户 2026-11-04 拍板 B-P1：Claude 与 Codex，不管用没用过）。
+ * 副作用（契约 8）：`claude mcp list` 会启动用户配置的 stdio MCP 并联网，客户端用户同意连接后每次打开客户端都会发生一次。
+ * 只在启动时一次，不定时重复；各家并行；失败不抛出。结果与耗时由检查本身记一行（`Precheck of … (startup): …`），
+ * 真机的 bridge.log 因此自带每次启动的预检耗时。
+ */
+export async function prewarmPrechecks(deps) {
+    await Promise.all(deps.agents.map(async (agent) => {
+        if (!deps.ready(agent)) {
+            deps.log(`Skipped the startup precheck of ${agent}: its adapter isn't installed.`);
+            return;
+        }
+        await deps.warm(agent).catch(() => undefined);
+    }));
+}

package/dist/bridge/precheck.js

@@ -10,7 +10,8 @@
  * - 不调用 ACP authenticate 探测登录：Qoder 未登录时 60 秒不响应（PoC 报告 §2.5）。
  * - `qodercli mcp list` 会以 `mcp-test-client` 身份连 M2，服务端判成 mcp、不进项目房间（总控 §6）：页面不要把这次连接当成 Qoder 会话。
  * - Cursor 的 m2 授权按目录保存，mcp list 与授权命令都必须在会话 cwd 下执行。
- * - Codex 的预检与授权都用适配器自带的 codex（调用方保证适配器已就绪）。
+ * - Codex 的预检与授权都用适配器自带的 codex（调用方保证适配器已就绪）。Codex 的 m2 检查先断网跑一次，只有本地就能定的
+ *   三种结果直接用，其余联网再跑（`CODEX_OFFLINE_PROXY` 处的说明）。
  * - Claude 同样用适配器自带的 claude（D9）：会话用的就是它，本机那份只决定兜底命令怎么显示。找不到自带程序时报 unknown，
  *   不退回本机的 claude（否则预检和会话看的是两个程序）。
  */
@@ -20,6 +21,24 @@ import { ADAPTERS, CODEX_BIN_LINK, CODEX_SCRIPT } from './adapters.js';
 import { combinedOutput } from './exec.js';
 import { parseClaudeAuthStatus, parseClaudeMcpList, parseCodexLoginStatus, parseCodexMcpListJson, parseCursorMcpList, parseCursorStatus, parseOpencodeMcpList, parseQoderMcpList, parseQoderStatus, tail, } from './precheck-parse.js';
 export const PRECHECK_TIMEOUT_MS = 45_000;
+/**
+ * Codex 的 m2 检查先断网跑一次（change bridge-precheck-speedup D12）。`codex mcp list --json` 联网时会探测每个还没存凭证的
+ * HTTP 服务器支不支持 OAuth（用户真实环境 3–6.6 秒）；而 M2 的 `o_auth`（有本地凭证）、没配置、停用三种状态只由本地配置与凭证决定，
+ * 断网结果与联网一致（2026-11-04 隔离实测，`evidence/measurement.md` §1c）。「配了没授权」断网会给 unknown（联网是 not_logged_in），
+ * 所以只有这三种直接采用，其余一律联网再跑、以联网为准 —— 结果与只联网逐状态一致，变化只在耗时。
+ * 依赖 Codex 的实现细节：升级 Codex 适配器时按该 evidence 的做法重测三种状态（契约 7）。
+ */
+export const CODEX_OFFLINE_PROXY = 'http://127.0.0.1:9';
+/**
+ * 断网那次实测 0.06 秒；超过这个时限就当没结果、联网再跑。不用更紧的值：新铺的程序第一次运行有约 4 秒的系统扫描
+ * （`desktop-bundled-local-runtime` 实测），太紧会让首次 Codex 预检白等一次再联网（review r1 N3）。
+ */
+export const CODEX_OFFLINE_TIMEOUT_MS = 10_000;
+const OFFLINE_TRUSTED = new Set(['unverified', 'not_configured', 'needs_enable']);
+function offlineEnv(env) {
+    const proxy = CODEX_OFFLINE_PROXY;
+    return { ...env, HTTPS_PROXY: proxy, HTTP_PROXY: proxy, ALL_PROXY: proxy, https_proxy: proxy, http_proxy: proxy, all_proxy: proxy, NO_PROXY: '', no_proxy: '' };
+}
 export function shellQuote(value) {
     return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -74,6 +93,7 @@ function plan(agent, deps) {
                 login: { args: ['login', 'status'], parse: (r) => parseCodexLoginStatus(combinedOutput(r), r.code), next: run(display, ['login']) },
                 m2: {
                     args: ['mcp', 'list', '--json'],
+                    offlineFirst: true,
                     parse: (r) => parseCodexMcpListJson(r.stdout, r.code),
                     next: (state, entry) => state === 'needs_auth' || state === 'unverified'
                         ? run(display, ['mcp', 'login', entry])
@@ -132,13 +152,23 @@ function plan(agent, deps) {
             };
     }
 }
-async function runStep(deps, p, args) {
-    return deps.exec(p.exec.command, [...p.exec.prefix, ...args], { env: deps.env, cwd: deps.cwd, timeoutMs: PRECHECK_TIMEOUT_MS });
+async function runStep(deps, p, args, options = {}) {
+    return deps.exec(p.exec.command, [...p.exec.prefix, ...args], {
+        env: options.offline ? offlineEnv(deps.env) : deps.env,
+        cwd: deps.cwd,
+        timeoutMs: options.offline ? CODEX_OFFLINE_TIMEOUT_MS : PRECHECK_TIMEOUT_MS,
+    });
 }
 export async function precheckM2(agent, deps) {
     const p = plan(agent, deps);
     if (p.missing)
         return toM2({ state: 'unknown', entry: null, raw: tail(p.missing) }, p.m2.next);
+    if (p.m2.offlineFirst) {
+        // 断网那次出任何意外（起不来、超时、退出码非 0、认不出），Codex 的解析都给 unknown（退出码不是 0 就不信输出），于是联网再跑
+        const offline = p.m2.parse(await runStep(deps, p, p.m2.args, { offline: true }));
+        if (OFFLINE_TRUSTED.has(offline.state))
+            return toM2(offline, p.m2.next);
+    }
     const result = await runStep(deps, p, p.m2.args);
     const failure = failed(result);
     return toM2(failure ? { state: 'unknown', entry: null, raw: failure } : p.m2.parse(result), p.m2.next);

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) {
@@ -311,6 +304,7 @@ export function startBridgeServer(options) {
                 connections.delete(conn.id);
                 processes.stopOwner(conn.id);
                 authorizations.cancelOwner(conn.id);
+                options.service.forgetConnection(conn.id);
             });
             // ws 的错误（非法帧、超过 maxPayload 等）之后必然紧跟 'close'，清理在 close 里做；这里只防止未处理的 error 事件让进程崩溃
             ws.on('error', () => undefined);

package/dist/bridge/service.js

@@ -14,6 +14,10 @@
  * 授权（change acp-terminal-free-auth）：authorizePlan 按写死清单生成命令（authorize.ts），m2 的配置项名只取 bridge 自己的 m2 预检：
  * 优先用最近一次预检 / 写配置时得到的名字（D19，页面先预检才会显示按钮，省掉一次重跑 —— Claude 的 `mcp list` 实测约 5 秒），没有记录时重跑；
  * 预检 / 写配置的结果按同一判据带上 `authorize` 能力，页面只在能力存在时才调用 agent/authorize。
+ *
+ * 预检缓存（change bridge-precheck-speedup，契约 18，规则在 precheck-cache.ts）：带连接 id 的预检是页面的 `agent/precheck`，
+ * 每条连接第一次查某家可以用缓存；不带的（授权结束后的重查）一律真跑并写回。写配置、授权在**开始运行之前**作废这家的缓存 ——
+ * 前置条件不满足而什么都没运行时不作废。缓存存不带能力的原始结果，给出时再按当前判据加 `authorize`。
  */
 import { dirname, join } from 'node:path';
 import { ADAPTERS, isAdapterAgent } from './adapters.js';
@@ -23,6 +27,7 @@ import { authCapability, buildAuthPlan, isSafeAuthEntry } from './authorize.js';
 import { prependPath } from './env.js';
 import { combinedOutput } from './exec.js';
 import { precheckAgent, precheckM2 } from './precheck.js';
+import { PrecheckCache } from './precheck-cache.js';
 import { BRIDGE_AGENT_IDS, } from './protocol.js';
 export const CONFIGURE_TIMEOUT_MS = 120_000;
 /**
@@ -92,6 +97,18 @@ export function createAgentService(deps) {
         login: withCapability(result.login, result.agent, 'login'),
         m2: withCapability(result.m2, result.agent, 'm2'),
     });
+    const precheckCache = new PrecheckCache({
+        run: async (agent) => {
+            const result = await precheckAgent(await ready(agent), precheckDeps);
+            remember(agent, result.m2);
+            return result;
+        },
+        // 只看文件状态、不起子进程；原生 agent 的检测要跑命令行，不在给缓存前做（拉起时 launch 会报 agent_not_installed）
+        usable: (agent) => !isAdapterAgent(agent) || deps.adapters.isReady(agent),
+        now: deps.now ?? Date.now,
+        onRevoked: (_agent, result) => deps.onPrecheckRevoked?.(withCapabilities(result)),
+        log: deps.log ?? (() => undefined),
+    });
     /** D10：clients.ts 只认 PATH 上能跑起来的 claude / codex */
     function configureEnv(agent) {
         const node = dirname(deps.nodePath);
@@ -130,13 +147,21 @@ export function createAgentService(deps) {
             }
             return info;
         },
-        async precheck(agent) {
-            const result = await precheckAgent(await ready(agent), precheckDeps);
-            remember(agent, result.m2);
+        async precheck(agent, connectionId) {
+            // 不带连接的只有授权结束后的重查（auth-call.ts）：一律新起一次真跑，不加入授权期间别的连接起的共享真跑（契约 12 delta）
+            const result = connectionId === undefined ? await precheckCache.fresh(agent, 'after sign-in or M2 authorization') : await precheckCache.forConnection(connectionId, agent);
             return withCapabilities(result);
         },
+        async warmPrecheck(agent) {
+            return precheckCache.warm(agent, 'startup');
+        },
+        forgetConnection(connectionId) {
+            precheckCache.forgetConnection(connectionId);
+        },
         async configure(agent) {
             const detected = await ready(agent);
+            // 马上要写配置：这家的预检结果不再可信（契约 18）
+            precheckCache.invalidate(agent);
             const result = await deps.exec(deps.nodePath, [deps.cliPath, '--client', CLIENT_ID[agent], '--yes'], {
                 env: configureEnv(agent),
                 cwd: deps.cwd,
@@ -165,6 +190,9 @@ export function createAgentService(deps) {
             const detected = await ready(agent);
             if (!capability(agent, action))
                 throw new BridgeFailure('auth_unavailable', `the bridge cannot run ${verb} for ${agent}; use the terminal command instead`);
+            // 取计划之后就运行授权命令（AuthorizationManager.run）：登录 / 授权状态马上要变，先作废缓存（契约 18）。
+            // 下面因配置项名缺失而 auth_unavailable 时也已作废 —— 没运行任何命令，多一次真跑无害
+            precheckCache.invalidate(agent);
             let entry = null;
             if (action === 'm2') {
                 // 配置项名不一定叫 m2，也不能由页面指定：用 bridge 最近一次预检的结果，没有就重跑（D19）；OpenCode 总是重跑（D21）

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.9.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"