@m2canvas/connect 0.8.0 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @m2canvas/connect
 
-Connect the agent clients on your machine to [M2 Canvas](https://m2ui.ai) in one command.
+Connect the agent clients on your machine to [M2 Canvas](https://patch.design) in one command.
 
 ```bash
 npx @m2canvas/connect
@@ -34,12 +34,13 @@ npx -y @m2canvas/connect@latest bridge
 
 Lets M2 (in Chrome or another Chromium browser) start and talk to the agents on this machine over [ACP](https://agentclientprotocol.com): Claude Code, Codex, Cursor CLI, OpenCode and Qoder. Run it in the project directory you want the agents to work in, and keep the window open. Copy the command from M2's Local Agent tab: it adds `--pair <value>` so that page pairs by itself.
 
-- **Local only.** It listens on `127.0.0.1:47821` and only accepts pages from `https://m2ui.ai`. Other sites, other machines and other hosts are refused before a connection is made. (`--dev` also accepts a local M2 dev server on port 5173; any app you serve on that port could then ask to pair, so only use it while developing M2.)
+- **Local only.** It listens on `127.0.0.1:47821` and only accepts pages from `https://patch.design`. Other sites, other machines and other hosts are refused before a connection is made. (`--dev` also accepts a local M2 dev server on port 5173; any app you serve on that port could then ask to pair, so only use it while developing M2.)
 - **Pairing gives the page your agents.** A paired page can make these agents read and change files and run commands as you, the same as typing into them yourself. Only run commands you copied from M2, and only enter the code into M2.
 - **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 (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.
@@ -51,14 +52,14 @@ Options: `--port <n>`, `--cwd <dir>` (default: current directory), `--verbose` (
 M2's Local Agent tab can have an agent app set the bridge up for you, so you need neither a terminal nor Node.js:
 
 ```bash
-curl -fsSL https://m2ui.ai/connect/install.sh | sh -s -- --pair <value from M2>
+curl -fsSL https://patch.design/connect/install.sh | sh -s -- --pair <value from M2>
 ```
 
 - **From M2.** Click "Connect with Claude" (or Codex, or Cursor): the app opens with this command in a prompt, and you press Return. The installer puts a private Node.js and a pinned version of this package in `~/.m2canvas`, checking every download against the hashes M2 publishes; writes the launcher `~/.m2canvas/bin/m2-bridge`; and starts the bridge in the background. The page pairs by itself. Agent sessions start in `~/.m2canvas/workspace`.
-- **Nothing starts at login.** After a restart, M2 asks the agent app to run `~/.m2canvas/bin/m2-bridge start --pair <value>` (you can run it yourself too). The launcher first updates the bridge to the version listed at `https://m2ui.ai/connect/manifest.json`, and goes back to the previous version if the new one doesn't start. The bridge keeps running after you quit the app, until you log out or shut down.
+- **Nothing starts at login.** After a restart, M2 asks the agent app to run `~/.m2canvas/bin/m2-bridge start --pair <value>` (you can run it yourself too). The launcher first updates the bridge to the version listed at `https://patch.design/connect/manifest.json`, and goes back to the previous version if the new one doesn't start. The bridge keeps running after you quit the app, until you log out or shut down.
 - **No pairing codes in the background.** A bridge started this way has no window to show a code in. When a page isn't paired yet (another browser, or the pairing expired), M2 gives it the same start command: the new bridge process sees the one already running and hands the page's pairing value to it, so the page pairs without restarting the bridge and other tabs keep their sessions. The handoff goes through `~/.m2canvas/bridge-<port>.sock` plus a one-time file in `~/.m2canvas`, so only a process that can write to that folder (your account; agent sandboxes normally can't write there) can hand a pairing value over; the file holds only the hash and is deleted right away. If that doesn't work, M2 offers to restart the bridge with `--replace`, which ends the sessions on the old one.
 - **Sandboxes.** Codex needs its Full access permission mode: its default sandbox can't reach the network or write to your home folder. Inside the Codex or Claude command sandbox, the scripts change nothing and say what to do instead.
 - **What it leaves alone.** macOS 13.5 or later. It doesn't use sudo, register anything to start at login, change your shell config or PATH, or touch a Node.js you installed yourself. Logs are in `~/.m2canvas/logs/`.
-- **Uninstall** with "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.
+- **Uninstall** with "Uninstall local connection" in the Local Agent tab's ⋯ menu, or `curl -fsSL https://patch.design/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/call-dispatch.js

@@ -38,7 +38,8 @@ export async function handleCall(ctx, conn, id, method, params) {
         case 'agent/prepare':
             return { agent, adapter: await ctx.service.prepare(agent) };
         case 'agent/precheck':
-            return ctx.service.precheck(agent);
+            // 带连接 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)) };

package/dist/bridge/main.js

@@ -15,7 +15,7 @@ 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';
@@ -29,6 +29,7 @@ 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';
@@ -36,6 +37,8 @@ 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',
@@ -191,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);
@@ -330,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/release-manifest.js

@@ -1,16 +1,17 @@
 /**
- * 更新清单 `https://m2ui.ai/connect/manifest.json` 的格式、解析与下载地址（change acp-bridge-one-time-install D13 / D14 / R7）。
+ * 主站更新清单（`MANIFEST_URL`，主站的 `/connect/manifest.json`，地址在 `site-config.ts`）的格式、解析与下载地址
+ * （change acp-bridge-one-time-install D13 / D14 / R7）。
  *
  * 清单由仓库的 `packages/connect/install/release.json` 生成，随 App 部署发布；部署 App 才是放量开关，发 npm 不等于推给所有用户。
  * 清单**只提供版本号与哈希**：下载地址在这里由版本号拼出，固定指向官方源与 npmmirror。
- * 不要在清单里加 URL 字段 —— 那会让清单（或篡改清单的人）把下载指到任意地方，信任根就不止 m2ui.ai 加哈希了。
+ * 不要在清单里加 URL 字段 —— 那会让清单（或篡改清单的人）把下载指到任意地方，信任根就不止主站加哈希了。
  *
  * 跨版本兼容：已安装的旧版本 bridge 会读新部署的清单（`--check-update` 跑的是当前版本的代码）。
  * - 同一 `schema` 内只加字段；本解析器忽略不认识的字段。
  * - 要改语义就升 `schema`；旧版本认不出新 schema 时按「读清单失败」处理，用当前版本继续（不会误装）。
  * - 版本号与哈希一律严格校验格式：它们会进入文件路径与下载地址。
  */
-export const MANIFEST_URL = 'https://m2ui.ai/connect/manifest.json';
+export { MANIFEST_URL } from '../site-config.js';
 export const MANIFEST_SCHEMA = 1;
 /** 只认纯 x.y.z（不接受预发布、构建元数据）：版本号会拼进目录名与下载地址 */
 const VERSION_RE = /^\d{1,4}\.\d{1,4}\.\d{1,6}$/;

package/dist/bridge/security.js

@@ -7,16 +7,17 @@
  * 连上并配对之后页面能做什么，见 server.ts / acp-guard.ts 的文件头：配对 = 授权该页面驱动本机 agent。
  *
  * 维护约束：
- * - Origin 必须精确匹配（scheme + host + port 全等）。不要改成后缀匹配、正则或「包含 m2ui.ai」——
- *   `https://m2ui.ai.evil.com`、`https://evil.m2ui.ai` 都必须被拒。
- * - 默认只放行正式域名。开发域名只在 `bridge --dev` 时放行：`localhost:5173` 是所有本机 Vite 项目共用的 Origin、
+ * - Origin 必须精确匹配（scheme + host + port 全等）。不要改成后缀匹配、正则或「包含主站主机名」——
+ *   `https://<主站主机>.evil.com`、`https://evil.<主站主机>` 都必须被拒。名单作为参数传入：名单为空即全部拒绝。
+ * - 默认只放行主站。开发域名只在 `bridge --dev` 时放行：`localhost:5173` 是所有本机 Vite 项目共用的 Origin、
  *   共用 localStorage，给开发版 M2 配对过后，任何跑在 5173 的项目（包括它的依赖）都能读走 token 免码连上
- *   （review r3 B2，用户 2026-10-02 拍板改为 --dev，推翻了最初的「开发域名常开」）。名单写死在包里，不提供任意扩展参数。
+ *   （review r3 B2，用户 2026-10-02 拍板改为 --dev，推翻了最初的「开发域名常开」）。名单写死在包里（主站 origin 在
+ *   `site-config.ts`），不提供任意扩展参数。
  * - Host 校验防 DNS rebinding：攻击者域名解析到 127.0.0.1 时，Host 头是攻击者域名。
  */
+import { PROD_ORIGINS } from '../site-config.js';
 import { BRIDGE_WS_PATH } from './protocol.js';
-/** www.m2ui.ai 由 m2-router 301 到根域，页面 Origin 不会是它，所以不列 */
-export const PROD_ORIGINS = ['https://m2ui.ai'];
+export { PROD_ORIGINS };
 /** 本地开发 M2 用（Vite 默认端口）；只有 `bridge --dev` 才放行 */
 export const DEV_ORIGINS = ['http://localhost:5173', 'http://127.0.0.1:5173'];
 export function allowedOrigins(dev) {

package/dist/bridge/server.js

@@ -304,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.js

@@ -3,7 +3,7 @@
  * 门槛、停止接受新连接、停 agent、回复与退出在 server.ts / uninstall-call.ts；本文件只管「怎么跑脚本、怎么读结果」。
  *
  * 不在 TypeScript 里再写一份删除逻辑：删除范围只有 `install/uninstall.sh` 一份实现（`connect/local-bridge` 契约 15「卸载脚本」），
- * 终端、agent 应用、M2 Mac 客户端运行的是 m2ui.ai 上它的逐字副本（`connect:install-assets -- --check` 锁住）。
+ * 终端、agent 应用、M2 Mac 客户端运行的是主站上它的逐字副本（`connect:install-assets -- --check` 锁住）。
  *
  * 维护约束：
  * - **先删自己的状态文件，再运行脚本。** 脚本只停它能从状态文件找到的 M2 bridge（`--stop` 发 SIGTERM）；自己的还在，

package/dist/bridge/update.js

@@ -3,12 +3,12 @@
  * 运行它的是**当前版本**的代码；它把新版本下载、校验、冒烟后切成 current，下一步由启动器用新版本拉起。
  *
  * 不变量（`connect/local-bridge` 契约 16 delta）：
- * - 只更新到 m2ui.ai 清单指定的版本（清单版本比当前低也照做，这就是回滚），不跟随 npm latest；
+ * - 只更新到主站清单指定的版本（清单版本比当前低也照做，这就是回滚），不跟随 npm latest；
  * - 清单只给版本与哈希，下载地址由 release-manifest.ts 固定拼出；任何下载内容与清单哈希不符都换下一个源，全部不符就放弃；
  * - 读清单失败、超时、格式认不出：什么都不改，用当前版本继续；
  * - 新版本先冒烟（`--self-test`），通过才切换；切换用「先建临时软链再改名」，任何时刻 current 都指向一个完整的版本；
  * - 「新版本拉起后没起来」的回退不在这里：新版本可能连模块都加载不了，回退判定在很少改动的启动器里（契约 16 delta）；
- * - 不加清单地址、下载地址的覆盖开关：那会让「只读 m2ui.ai 清单」多出一条旁路（design R8）。测试经 UpdateDeps 注入下载。
+ * - 不加清单地址、下载地址的覆盖开关：那会让「只读主站清单」多出一条旁路（design R8）。测试经 UpdateDeps 注入下载。
  *
  * 并发（design N1）：不加锁。所有写入先写临时目录 / 临时软链再改名；两个更新同时跑时各自下到自己的临时目录，
  * 后完成的发现版本目录已完整就丢掉自己的，发现 current 已经切好就不再切。

package/dist/clients.js

@@ -1,11 +1,19 @@
 // 各客户端的探测 / 写入 / 登录。每家的命令与坑位都经本机逐一实测，见 README。
 import { join } from 'node:path';
-import { M2_MCP_URL, SERVER_NAME, findInClaudeConfig, findInCodexToml, findInQoderSettings, appendCodexServer, mergeCursorConfig, mergeOpencodeConfig, } from './config-files.js';
+import { M2_MCP_URL, SERVER_NAME, findInClaudeConfig, findInCodexToml, findInQoderSettings, hasCodexNameConflict, hasNameConflictInServers, nameConflictNote, appendCodexServer, mergeCursorConfig, mergeOpencodeConfig, } from './config-files.js';
 import { existsSync, firstExecutable, firstRunnable, home, readJson, readText, run, which, writeJsonWithBackup, writeTextWithBackup, } from './system.js';
 function jsonExisting(path, find) {
     const read = readJson(path);
     return read.kind === 'ok' ? find(read.value) : null;
 }
+/** 用户级 server 表里同名 `m2` 指向别处 → blocked 提示（D-C1）；读不出文件按无冲突，由客户端自己的 CLI 报错 */
+function jsonConflict(path, servers) {
+    const read = readJson(path);
+    return read.kind === 'ok' && hasNameConflictInServers(servers(read.value)) ? nameConflictNote(path) : null;
+}
+function mcpServersOf(value) {
+    return typeof value === 'object' && value !== null ? value.mcpServers : undefined;
+}
 function addWith(command, args) {
     const result = run(command, args);
     return result.status === 0 ? { ok: true } : { ok: false, note: result.output };
@@ -17,7 +25,7 @@ function claudeCode() {
     return {
         label: 'Claude Code',
         existing: jsonExisting(join(home, '.claude.json'), findInClaudeConfig),
-        blocked: null,
+        blocked: jsonConflict(join(home, '.claude.json'), mcpServersOf),
         actions: [`claude mcp add --transport http --scope user ${SERVER_NAME} ${M2_MCP_URL}`],
         restart: 'Restart Claude Code (claude --continue keeps your conversation).',
         // `claude mcp login` 在非 TTY 下直接失败（实测 "stdin isn't a terminal"），agent 的 shell 就是这种。
@@ -38,7 +46,7 @@ function codex() {
     return {
         label: 'Codex',
         existing: toml ? findInCodexToml(toml) : null,
-        blocked: null,
+        blocked: toml && !findInCodexToml(toml) && hasCodexNameConflict(toml) ? nameConflictNote(path) : null,
         actions: [`add [mcp_servers.${SERVER_NAME}] to ${path}`],
         // 顺序敏感：login 的本地回调端口挂在 login 进程上，必须授权完成后再重启 Codex。
         restart: 'Fully quit and reopen Codex (after signing in).',
@@ -58,7 +66,7 @@ function qoder() {
     return {
         label: 'Qoder',
         existing: jsonExisting(join(home, '.qoder', 'settings.json'), findInQoderSettings),
-        blocked: null,
+        blocked: jsonConflict(join(home, '.qoder', 'settings.json'), mcpServersOf),
         actions: [`qodercli mcp add -s user -t http ${SERVER_NAME} ${M2_MCP_URL}`],
         restart: 'Reopen Qoder if it is running.',
         // qodercli 没有 mcp login 子命令，授权只能在 UI 里点。
@@ -93,6 +101,8 @@ function opencode() {
     if (read.kind === 'invalid')
         return { ...base, blocked: `${path} is not valid JSON (${read.error}).` };
     const merged = mergeOpencodeConfig(read.kind === 'ok' ? read.value : {});
+    if (merged.conflict)
+        return { ...base, blocked: nameConflictNote(path) };
     return {
         ...base,
         existing: merged.existing,
@@ -123,6 +133,8 @@ function cursor() {
     if (read.kind === 'invalid')
         return { ...base, blocked: `${path} is not valid JSON (${read.error}).` };
     const merged = mergeCursorConfig(read.kind === 'ok' ? read.value : {});
+    if (merged.conflict)
+        return { ...base, blocked: nameConflictNote(path) };
     return {
         ...base,
         existing: merged.existing,

package/dist/config-files.js

@@ -1,5 +1,7 @@
 // 各客户端配置文件的纯函数读写：查已有 m2 入口、按原格式合并。全部不碰磁盘，便于单测。
-export const M2_MCP_URL = 'https://mcp.m2ui.ai/mcp';
+// MCP 地址来自 site-config.ts（connect 唯一的站点配置来源），这里转出供 cli.ts / clients.ts 沿用原导出名。
+import { M2_MCP_URL, MCP_HOST } from './site-config.js';
+export { M2_MCP_URL };
 export const SERVER_NAME = 'm2';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -9,7 +11,7 @@ export function isM2Url(value) {
     if (typeof value !== 'string')
         return false;
     try {
-        return new URL(value).host === new URL(M2_MCP_URL).host;
+        return new URL(value).host === MCP_HOST;
     }
     catch {
         return false;
@@ -25,6 +27,21 @@ export function findM2Entry(servers) {
     }
     return null;
 }
+/**
+ * server 表里已有名为 `m2`、但不指向 M2 的入口（change domain-cutover design D-C1）。
+ * 我们只会以 `m2` 这个名字写入；同名入口指向别处时既不能追加（Codex 的 TOML 会出现重复表、整个文件解析失败），
+ * 也不能覆盖（那可能是用户自己的 server，或换域名前留下的旧入口，静默改掉用户看不出发生了什么）。一律报冲突交给用户。
+ */
+export function hasNameConflictInServers(servers) {
+    if (!isObject(servers) || !Object.hasOwn(servers, SERVER_NAME))
+        return false;
+    const entry = servers[SERVER_NAME];
+    return !(isObject(entry) && (isM2Url(entry.url) || isM2Url(entry.serverUrl)));
+}
+/** 同名冲突的提示（给 ClientPlan.blocked 用）：说明不改的原因与用户要做的事，不打印对方的地址 */
+export function nameConflictNote(where) {
+    return `${where} already has an MCP server named "${SERVER_NAME}" that does not point to M2 (for example one left from an old M2 address). Remove or rename it, then run this again.`;
+}
 /** Claude Code `~/.claude.json` 顶层 mcpServers = user scope。 */
 export function findInClaudeConfig(config) {
     return isObject(config) ? findM2Entry(config.mcpServers) : null;
@@ -56,15 +73,38 @@ export function findInCodexToml(toml) {
     }
     return null;
 }
+/** Codex `config.toml` 里已有 `[mcp_servers.m2]` 段且段内 url 不指向 M2（判定见 `hasNameConflictInServers`） */
+export function hasCodexNameConflict(toml) {
+    let inTarget = false;
+    let found = false;
+    let pointsToM2 = false;
+    for (const raw of toml.split(/\r?\n/)) {
+        const line = raw.trim();
+        const header = /^\[mcp_servers\.("?)([^\]"]+)\1\]$/.exec(line);
+        if (header || line.startsWith('[')) {
+            inTarget = header?.[2] === SERVER_NAME;
+            if (inTarget)
+                found = true;
+            continue;
+        }
+        const url = /^url\s*=\s*["']([^"']+)["']/.exec(line);
+        if (inTarget && url && isM2Url(url[1]))
+            pointsToM2 = true;
+    }
+    return found && !pointsToM2;
+}
 /** Cursor `~/.cursor/mcp.json`：合并 `{ url }`，保留其余 server。 */
 export function mergeCursorConfig(config) {
     const base = isObject(config) ? config : {};
     const existing = findM2Entry(base.mcpServers);
     if (existing)
-        return { existing, config: base };
+        return { existing, conflict: false, config: base };
+    if (hasNameConflictInServers(base.mcpServers))
+        return { existing: null, conflict: true, config: base };
     const servers = isObject(base.mcpServers) ? base.mcpServers : {};
     return {
         existing: null,
+        conflict: false,
         config: { ...base, mcpServers: { ...servers, [SERVER_NAME]: { url: M2_MCP_URL } } },
     };
 }
@@ -81,12 +121,15 @@ export function mergeOpencodeConfig(config) {
     const flatEntries = Object.fromEntries(Object.entries(mcp).filter(([key]) => key !== 'servers'));
     const existing = findM2Entry(flatEntries) ?? findM2Entry(nested);
     if (existing)
-        return { existing, config: base };
+        return { existing, conflict: false, config: base };
+    if (hasNameConflictInServers(flatEntries) || hasNameConflictInServers(nested)) {
+        return { existing: null, conflict: true, config: base };
+    }
     const useNested = nested !== null && Object.keys(flatEntries).length === 0;
     const nextMcp = useNested
         ? { ...mcp, servers: { ...nested, [SERVER_NAME]: { type: 'remote', url: M2_MCP_URL } } }
         : { ...mcp, [SERVER_NAME]: { type: 'remote', url: M2_MCP_URL, enabled: true } };
-    return { existing: null, config: { ...base, mcp: nextMcp } };
+    return { existing: null, conflict: false, config: { ...base, mcp: nextMcp } };
 }
 /**
  * Codex `config.toml` 追加 m2 段。不走 `codex mcp add`：它在没有已存 token 时会顺手启动 OAuth

package/dist/site-config.js

@@ -0,0 +1,28 @@
+/**
+ * connect 唯一的站点配置来源（change domain-config-externalize D1）。
+ *
+ * connect 随 npm 发布、在用户机器上运行，没有部署期配置可读，所以站点地址以代码常量的形式集中在这里；
+ * 包内其余代码只从这里取值。换域名时只改本文件（`package.json` 的 homepage 同批改），随 connect 发版生效。
+ *
+ * 维护约束：
+ * - 这些值是安全边界的一部分：主站 origin 是 bridge 唯一放行的生产 Origin（`connect/local-bridge` 契约 1：名单写死在包里、
+ *   精确匹配），主站清单是更新的唯一信任根（契约 16）。不得改成读环境变量、命令行参数或配置文件 —— 那等于给 Origin
+ *   白名单与清单地址加了覆盖开关。
+ * - 只写下面两个 origin 字面量，派生值一律由它们拼出，不写第二份。两个 origin 保持单行 `export const NAME = '…';`：
+ *   不发版的包之间靠读源码比对防漂移，换写法会让这类比对失效。
+ * - origin 必须是规范形式（https、不带路径与尾斜杠、不写默认端口）：bridge 拿它与浏览器的 Origin 头逐字比较。
+ */
+/** 主站（用户打开画布的网站）的 origin；页面连 bridge 时 Origin 头就是它 */
+export const APP_PUBLIC_ORIGIN = 'https://patch.design';
+/** MCP 服务的 origin；connect 写进各家 agent 客户端配置的 MCP 地址在它下面 */
+export const MCP_ORIGIN = 'https://mcp.m2ui.ai';
+/** 主站主机名（含端口时带端口） */
+export const APP_PUBLIC_HOST = new URL(APP_PUBLIC_ORIGIN).host;
+/** MCP 服务主机名：按它识别已有的 M2 配置项，老入口的 path / query / 尾斜杠不论 */
+export const MCP_HOST = new URL(MCP_ORIGIN).host;
+/** bridge 默认放行的 Origin：只有主站。`www.<主站主机>` 由 m2-router 301 到根域，页面 Origin 不会是它，所以不列 */
+export const PROD_ORIGINS = [APP_PUBLIC_ORIGIN];
+/** 主站清单：bridge 更新时唯一读取的版本与哈希来源 */
+export const MANIFEST_URL = `${APP_PUBLIC_ORIGIN}/connect/manifest.json`;
+/** 写进各家 agent 客户端配置的 MCP 地址（streamable HTTP） */
+export const M2_MCP_URL = `${MCP_ORIGIN}/mcp`;

package/install/uninstall.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
-# M2 local connection uninstaller: https://m2ui.ai/connect/uninstall.sh
-#   curl -fsSL https://m2ui.ai/connect/uninstall.sh | sh
+# M2 local connection uninstaller, served by the M2 site at /connect/uninstall.sh
+#   curl -fsSL https://<M2 site>/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.8.0",
+  "version": "0.10.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": {
@@ -21,7 +21,7 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"
   },
-  "homepage": "https://m2ui.ai/mcp",
+  "homepage": "https://patch.design/mcp",
   "license": "MIT",
   "publishConfig": {
     "access": "public",