@m2canvas/connect 0.12.0 → 0.13.0

package/README.md

@@ -26,40 +26,22 @@ Options: `--client <id>` sets up only that client; `--dry-run` shows the plan wi
 
 After setup, restart each client so it loads the new server.
 
-## Local agent bridge
+## Local agent bridge (M2 for Mac)
 
-```bash
-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.
+The `bridge` subcommand is the local connection that lets M2 start and talk to the agents on this machine over [ACP](https://agentclientprotocol.com): Claude Code, Codex, Cursor CLI, OpenCode and Qoder. Local agents in M2 only work inside the M2 desktop app, which runs this bridge for you in the background. Running `npx @m2canvas/connect bridge` in a terminal only explains this and exits; to add M2 to an agent client instead, run `npx @m2canvas/connect` without `bridge`.
 
-- **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.
+- **Desktop app only.** It listens on `127.0.0.1:47821` and only accepts pages from `https://patch.design` that the M2 desktop app connects: for every connection the app first gets a one-time ticket from the bridge over `~/.m2canvas/bridge-<port>.sock` (only your account can open it) and adds it to the request. A browser tab can't add it, so browsers, other sites, other machines and other hosts are refused before a connection is made. Tickets work once, expire after 60 seconds and stop working when the bridge exits; pages hold no pairing token or other credential. (`--dev` also accepts a local M2 dev server on port 5173, still only through a desktop app started for development.)
+- **Connecting gives the page your agents.** A connected page can make these agents read and change files and run commands as you, the same as typing into them yourself. The first time, the desktop app asks you before it starts the bridge.
 - **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.
-
-Options: `--port <n>`, `--cwd <dir>` (default: current directory), `--verbose` (also print agent stderr), `--dev` (also accept the local M2 dev server), `--replace` (stop the M2 bridge already running on the port first).
-
-## One-time install (macOS)
+## Install and updates (macOS)
 
-M2's Local Agent tab can have an agent app set the bridge up for you, so you need neither a terminal nor Node.js:
-
-```bash
-curl -fsSL https://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://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.
+- **From the M2 desktop app.** The app puts a private Node.js and a pinned version of this package in `~/.m2canvas` (from its own bundle, or with `https://patch.design/connect/install.sh` as a fallback, checking every download against the hashes M2 publishes), writes the launcher `~/.m2canvas/bin/m2-bridge`, and starts the bridge in the background. Agent sessions start in `~/.m2canvas/workspace`.
+- **Nothing starts at login.** The app runs the launcher when it opens. 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.
 - **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://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.
+- **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 page the M2 desktop app connected 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.

package/dist/bridge/args.js

@@ -5,7 +5,6 @@
  * （契约 14、`install/m2-bridge.sh` 头注释），已安装的 bridge 又会自动更新，所以每个版本都要保持这套接口兼容。
  */
 import { resolve } from 'node:path';
-import { isPairCommitment } from './pairing.js';
 import { BRIDGE_DEFAULT_PORT } from './protocol.js';
 import { DEV_ORIGINS, PROD_ORIGINS } from './security.js';
 /**
@@ -27,53 +26,50 @@ export const DEV_BACKGROUND_LIFETIME_MS = 2 * 60 * 60 * 1000;
 export function backgroundLifetimeMs(args) {
     return args.background && args.dev ? DEV_BACKGROUND_LIFETIME_MS : null;
 }
-export const BRIDGE_HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev] [--pair <value>] [--replace]
-       npx @m2canvas/connect bridge --unpair
+export const BRIDGE_HELP = `Usage: this command is run by the M2 desktop app; you don't need to run it yourself.
 
-Runs the local agent bridge so M2 (in Chrome) can start and talk to the agents
+Runs the local agent bridge that lets M2 for Mac start and talk to the agents
 installed on this machine: Claude Code, Codex, Cursor CLI, OpenCode and Qoder.
 
-It only listens on 127.0.0.1 and only accepts the M2 web app (${PROD_ORIGINS.join(', ')}).
-The command M2 gives you pairs that page automatically; other pages ask for the
-pairing code shown here. A paired page can make these agents read and change
-files and run commands as you, so only run commands you copied from M2.
-Agents run in the directory you start the bridge from (or --cwd), with your own logins.
-On macOS a paired page can also start an agent's own sign-in; you finish it in
-your browser.
+It only listens on 127.0.0.1 and only accepts pages that the M2 desktop app
+opens from ${PROD_ORIGINS.join(', ')}: the app authorizes each connection, so a browser tab
+can't connect. A connected page can make these agents read and change files and
+run commands as you.
 
-  --port <n>      port to listen on (default ${BRIDGE_DEFAULT_PORT})
-  --cwd <dir>     working directory for agent sessions (default: current directory)
-  --verbose       also print agent stderr and connection details
-  --dev           also accept a local M2 dev server (${DEV_ORIGINS.join(', ')});
-                  any app served on that port could then ask to pair
-  --pair <value>  pair the M2 page that gave you this command (M2 adds it for you;
-                  valid for 10 minutes, once)
-  --replace       if an M2 bridge (0.6.0 or later) is already running on the port,
-                  stop it first (its agent sessions end) and start this one instead;
-                  not on Windows
-  --unpair        forget all paired pages and exit
-  -h, --help      show this help
+To add M2 to an agent client instead (Claude Code, Codex, Cursor, OpenCode,
+Qoder), run "npx @m2canvas/connect" without "bridge".
 
 Internal (used by the M2 launcher ~/.m2canvas/bin/m2-bridge; don't run these yourself):
-  --background    run without a terminal: no pairing codes are shown; exits with
-                  code ${EXIT_ALREADY_RUNNING} if an M2 bridge is already running on the port (handing its --pair
-                  to that bridge first), ${EXIT_PORT_UNAVAILABLE} if something else holds the port; with --dev it
-                  stops by itself after 2 hours
+  --background    run without a terminal; this is the only mode that accepts pages.
+                  Exits with code ${EXIT_ALREADY_RUNNING} if an M2 bridge is already running on the port,
+                  ${EXIT_PORT_UNAVAILABLE} if something else holds the port; with --dev it stops by itself after 2 hours
+  --port <n>      port to listen on (default ${BRIDGE_DEFAULT_PORT})
+  --cwd <dir>     working directory for agent sessions
+  --dev           also accept a local M2 dev server (${DEV_ORIGINS.join(', ')})
+  --replace       if an M2 bridge is already running on the port, stop it first
+                  (its agent sessions end) and start this one instead; not on Windows
+  --verbose       also print agent stderr and connection details
   --check-update  update this installation to the version M2 publishes, then exit
   --self-test     check that this installation loads completely, print its version and exit
   --stop          stop the M2 bridge running on the port (only one it can recognize; it's
-                  sent SIGTERM so it cleans up), then exit`;
+                  sent SIGTERM so it cleans up), then exit
+  -h, --help      show this help`;
+/**
+ * 不带 `--background` 时的说明（change bridge-client-only D7，用户 2026-11-07「去掉NPX」）：终端模式发不出票据，
+ * 任何页面都连不上，所以直接说明并退出。不带 `bridge` 的 `npx @m2canvas/connect` 是给外接 agent 写 M2 配置的命令，不受影响。
+ */
+export const TERMINAL_MODE_UNSUPPORTED = `Local agents in M2 now run only inside the M2 desktop app.
+Open your project in M2 for Mac and connect from the Agent panel there; the app starts this bridge for you.
+To add M2 to an agent client instead, run "npx @m2canvas/connect" (without "bridge").`;
 /** 解析 `bridge` 之后的参数；返回字符串表示参数错误（调用方连同帮助打印、退出码 2）。 */
 export function parseBridgeArgs(argv) {
-    const args = { port: BRIDGE_DEFAULT_PORT, cwd: process.cwd(), verbose: false, unpair: false, help: false, dev: false, pair: null, replace: false, background: false, selfTest: false, checkUpdate: false, stop: false };
+    const args = { port: BRIDGE_DEFAULT_PORT, cwd: process.cwd(), verbose: false, help: false, dev: false, legacyPair: false, replace: false, background: false, selfTest: false, checkUpdate: false, stop: false };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '-h' || arg === '--help')
             args.help = true;
         else if (arg === '--verbose')
             args.verbose = true;
-        else if (arg === '--unpair')
-            args.unpair = true;
         else if (arg === '--dev')
             args.dev = true;
         else if (arg === '--replace')
@@ -87,12 +83,10 @@ export function parseBridgeArgs(argv) {
         else if (arg === '--stop')
             args.stop = true;
         else if (arg === '--pair') {
-            const value = argv[++i];
-            if (value === undefined)
+            // 值照收不验：旧启动器已按自己的规则校验过；这里拒绝任何值都会让启动器把新版本拉黑（见 BridgeArgs.legacyPair）
+            if (argv[++i] === undefined)
                 return '--pair needs a value';
-            if (!isPairCommitment(value))
-                return `invalid --pair value ${value}; copy the start command from M2 again`;
-            args.pair = value;
+            args.legacyPair = true;
         }
         else if (arg === '--port' || arg === '--cwd') {
             const value = argv[++i];

package/dist/bridge/call-dispatch.js

@@ -1,26 +1,19 @@
 /**
- * bridge 方法的分派（从 server.ts 拆出）：未配对只放行 pair，其余按方法交给 service / ProcessManager / auth-call.ts。
- * 连接状态（是否已配对、连接是否还在）只在 server.ts 里改，这里经 ctx 的回调读写。
+ * bridge 方法的分派（从 server.ts 拆出）：按方法交给 service / ProcessManager / auth-call.ts。
+ * 连接状态（怎么认证的、连接是否还在）只在 server.ts 里改，这里经 ctx 的回调读。
  *
- * 安全边界同 server.ts 文件头：页面可控的参数只有 agent id（枚举校验）、配对码、processId，进不了 spawn 的命令、参数、cwd、环境；
+ * 安全边界同 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');
+    // 纵深判断：upgrade 只放行带有效票据的连接（server.ts 也在调用前判过一次）
+    if (conn.auth !== 'client-ticket')
+        throw new BridgeFailure('not_paired', 'this connection was not authorized by the M2 desktop app');
     if (method === 'process/stop') {
         const processId = params.processId;
         if (typeof processId !== 'string' || !ctx.processes.stop(conn.id, processId))

package/dist/bridge/install-layout.js

@@ -5,7 +5,8 @@
  * （脚本不能 import 这里）。改这里要同批改那两处；脚本测试会按这里的路径核对它们的产物。
  *
  * 全部在用户主目录下，不写任何系统目录、不注册任何启动项、不改 PATH（`connect/local-bridge` 契约 14 delta）。
- * 其余已有文件（配对记录 `bridge-pairings.json`、状态文件 `bridge-<port>.json`、适配器 `acp-adapters/`）位置不变。
+ * 其余已有文件（状态文件 `bridge-<port>.json`、票据 socket `bridge-<port>.sock`、适配器 `acp-adapters/`）位置不变；旧版本的配对记录
+ * `bridge-pairings.json` 由新版本 bridge 启动时删除（change bridge-client-only D4）。
  */
 import { join } from 'node:path';
 export function installLayout(home) {

package/dist/bridge/main.js

@@ -3,29 +3,30 @@
  *
  * 只由 cli.ts 在第一个参数是 `bridge` 时动态加载：默认的 MCP 配置流程（Copy to agent 起手式）不会加载这里的任何代码与依赖。
  *
- * 本文件负责组装与终端交互：启动横幅、配对码打印、信号处理、退出兜底清理。参数与帮助在 args.ts，协议在 server.ts，安全判定在 security.ts / pairing.ts。
- * 终端输出用英文，与 connect 现有输出一致。
+ * 本文件负责组装：启动横幅、信号处理、退出兜底清理。参数与帮助在 args.ts，协议在 server.ts，安全判定在 security.ts / ticket.ts。
+ * 输出用英文，与 connect 现有输出一致。
  *
- * 后台模式（`--background`，只由启动器 `~/.m2canvas/bin/m2-bridge` 使用，change acp-bridge-one-time-install）：输出写进日志文件，
- * 所以不出配对码（契约 2）、不提示「保持窗口打开」；页面经 `welcome.bridge.background` 得知，改走「重新连接」。
- * 端口上已有认定的 M2 bridge 时以 EXIT_ALREADY_RUNNING 退出，启动器把它当成功。
- * 后台模式且在 macOS 上时还能卸载自己（`bridge/uninstall`，change bridge-uninstall-from-page D2 / D3；执行在 uninstall.ts）。
+ * 只剩后台模式（`--background`，由启动器 `~/.m2canvas/bin/m2-bridge` 使用；M2 客户端运行启动器）。change bridge-client-only 起：
+ * - 页面只能经 M2 客户端主进程替它领的一次性票据连上（D2 / D4）。票据从本进程监听的 `~/.m2canvas/bridge-<port>.sock` 领（ticket-socket.ts）；
+ *   socket 建不起来时退出，不留一个谁也连不上的进程（F7）。
+ * - 不带 `--background` 时直接说明「只能在 M2 客户端里用」并退出（D7，用户 2026-11-07「去掉NPX」）。
+ * - 没有配对：`--pair` 只为启动器兼容而接受（F1），拿到端口之后删掉遗留的 `bridge-pairings.json`。
+ * 输出写进日志文件，所以不能出现票据。端口上已有认定的 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 { existsSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { home, isExecutable, which } from '../system.js';
 import { AdapterManager, ADAPTERS, isAdapterAgent } from './adapters.js';
-import { BRIDGE_HELP, EXIT_ALREADY_RUNNING, EXIT_PORT_UNAVAILABLE, backgroundLifetimeMs, parseBridgeArgs } from './args.js';
+import { BRIDGE_HELP, EXIT_ALREADY_RUNNING, EXIT_PORT_UNAVAILABLE, TERMINAL_MODE_UNSUPPORTED, backgroundLifetimeMs, parseBridgeArgs } from './args.js';
 import { detectAgent } from './agents.js';
 import { EXPECT_PATH } from './authorize.js';
 import { buildAgentEnv, buildNpmEnv, buildProbeEnv } from './env.js';
 import { execCommand, killActiveExecs } from './exec.js';
 import { createLsofProbe, createPsProbe, createStopDeps, identifyRunningBridge, instanceFilePath, listenWithReplace, processStartedAt, removeInstanceRecord, stopRunningBridge, writeInstanceRecord } from './instance.js';
-import { handOffCommitment, listenForHandoff } from './handoff.js';
 import { installLayout } from './install-layout.js';
 import { installShutdownSignals } from './lifecycle.js';
-import { PairingManager, createFilePairingStore } from './pairing.js';
 import { BRIDGE_AGENT_IDS, BRIDGE_WS_PATH } from './protocol.js';
 import { resolveNpmCommand } from './npm-command.js';
 import { allowedOrigins } from './security.js';
@@ -35,6 +36,8 @@ import { runCheckUpdate } from './update-io.js';
 import { startBridgeServer } from './server.js';
 import { createAgentService } from './service.js';
 import { KILL_GRACE_MS } from './processes.js';
+import { TicketBook } from './ticket.js';
+import { listenForTicketRequests, ticketSocketPathProblem } from './ticket-socket.js';
 import { createSelfUninstaller, uninstallScriptPath } from './uninstall.js';
 const NPM_CI_TIMEOUT_MS = 15 * 60 * 1000;
 /** 启动时预热预检的 agent（契约 18；用户 2026-11-04 拍板 B-P1：随包的两家，不管用没用过） */
@@ -53,31 +56,24 @@ function packageVersion() {
     const version = typeof parsed === 'object' && parsed !== null ? parsed.version : undefined;
     return typeof version === 'string' ? version : '0.0.0';
 }
-function printCode(info) {
-    const until = new Date(info.expiresAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
-    const code = `Pairing code: ${info.display}  (valid until ${until})`;
-    if (info.reason === 'startup')
-        console.log(`\n  ${code}\n  Enter it in M2 when it asks to connect to this bridge.\n`);
-    else if (info.reason === 'requested')
-        console.log(`\n→ ${info.origin ?? 'A page'} wants to pair with this bridge. ${code}\n  Only enter it if you opened M2 yourself.\n`);
-    else if (info.reason === 'expired')
-        console.log(`\n→ The pairing code expired. New ${code}\n`);
-    else
-        console.log(`\n→ Too many wrong pairing codes${info.origin ? ` from ${info.origin}` : ''}. New ${code}\n`);
-}
 function clock(at) {
     return new Date(at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
 }
-/** 启动命令里的配对已被用掉，同一个密钥又出现：同一个 M2 标签页被复制 / 连接途中刷新，或者别的程序抢先配对了（review r1 S2） */
-function printReused(info) {
-    console.log(`\n→ Warning: the pairing in your start command was already used (by ${info.firstOrigin} at ${clock(info.usedAt)}), ` +
-        `and ${info.origin} just presented it again. If you didn't duplicate or reload that M2 tab while it was connecting, another program on this machine ` +
-        `may have paired with this bridge: press Ctrl+C, run "npx @m2canvas/connect bridge --unpair", then start the bridge again.\n`);
-}
-function printLocked(origin) {
-    const from = origin ? ` (the last ones came from ${origin})` : '';
-    console.log(`\n→ Too many wrong pairing codes${from}. New pages can't pair until you restart the bridge (Ctrl+C, then run it again); ` +
-        `pages that are already paired keep working.${origin ? ` If you didn't open ${origin}, close that page first.` : ''}\n`);
+/**
+ * 拿到端口之后删掉旧版本留下的配对记录（change bridge-client-only D4）：里面只有哈希，删掉是为了不留下「还能用」的误解。
+ * 必须在拿到端口之后：端口上可能还是旧版本的 bridge，它每次校验 token 都重读这个文件。删不掉只记日志。
+ */
+function removeLegacyPairings(m2Dir, log) {
+    const path = join(m2Dir, 'bridge-pairings.json');
+    if (!existsSync(path))
+        return;
+    try {
+        rmSync(path, { force: true });
+        log('Removed the pairing records left by an older version; pages now connect through the M2 desktop app.');
+    }
+    catch (error) {
+        log(`Couldn't remove ${path} (${error instanceof Error ? error.message : String(error)}); it isn't used anymore.`);
+    }
 }
 function describeAdapter(agent, info) {
     const name = `${LABELS[agent]} adapter (${ADAPTERS[agent].package}@${ADAPTERS[agent].version})`;
@@ -129,34 +125,31 @@ export async function runBridge(argv) {
         return runCheckUpdate();
     if (parsed.stop)
         return stopRecognizedBridge(parsed.port);
-    const m2Dir = join(home, '.m2canvas');
-    const store = createFilePairingStore(join(m2Dir, 'bridge-pairings.json'), (message) => console.warn(message));
-    if (parsed.unpair) {
-        store.clear();
-        console.log('Forgot all paired pages. M2 will ask for a new pairing code next time.');
-        return 0;
+    // 终端模式发不出票据，任何页面都连不上（D7）：说明后退出，不占端口、不写状态文件
+    if (!parsed.background) {
+        console.error(TERMINAL_MODE_UNSUPPORTED);
+        return 1;
     }
+    const m2Dir = join(home, '.m2canvas');
     if (!existsSync(parsed.cwd) || !statSync(parsed.cwd).isDirectory()) {
         console.error(`--cwd ${parsed.cwd} is not a directory.`);
         return 2;
     }
     const log = (message) => console.log(`[${new Date().toLocaleTimeString()}] ${message}`);
+    // 票据 socket 的路径放不进 sun_path 时，开始监听之前就退出：不去占端口，也不会 --replace 掉正在运行的那个（F7）
+    const socketProblem = ticketSocketPathProblem(m2Dir, parsed.port);
+    if (socketProblem) {
+        log(`The M2 desktop app can't reach this bridge: ${socketProblem}. Not starting.`);
+        return 1;
+    }
+    if (parsed.legacyPair)
+        log('Ignoring --pair: pages no longer pair with this bridge; the M2 desktop app authorizes each connection.');
     const probeEnv = buildProbeEnv();
-    // 后台模式用私有 Node 自带的 npm（目标用户 PATH 上可能根本没有 npm，R3）；终端模式照旧用 PATH 上的
+    // 后台模式用私有 Node 自带的 npm（目标用户 PATH 上可能根本没有 npm，R3）
     const npm = resolveNpmCommand({ background: parsed.background, execPath: process.execPath, platform: process.platform, which });
     let server = null;
-    // 配对锁定只能靠重启 bridge 解除：bridge 不读终端（放到后台时读终端会被系统挂起），页面也没有任何途径解锁
-    const pairing = new PairingManager({
-        store,
-        // 后台模式没有终端、输出写进日志文件：不出码（契约 2「码只出现在终端」），配对只剩命令承诺与已有 token（D17 / D18）
-        issueCodes: !parsed.background,
-        onCodeIssued: printCode,
-        onLocked: printLocked,
-        onProblem: (message) => console.warn(message),
-        onCommitmentReused: printReused,
-    });
-    // 承诺必须在开始监听之前挂上：等待中的页面每 2 秒探测一次，监听一开始就可能连上；晚挂一步它就撞上 no_commitment、落到输码
-    const pairUntil = parsed.pair ? pairing.armCommitment(parsed.pair) : null;
+    // 票据只在本进程内存里（ticket.ts）：进程退出全部失效
+    const tickets = new TicketBook();
     // 进度更新（D12）也经 onState 广播，终端只在状态变化时打一行
     const loggedState = new Map();
     const adapters = new AdapterManager({
@@ -203,10 +196,8 @@ export async function runBridge(argv) {
     // 端口被占时认出正在运行的 M2 bridge，给出 pid 与终端，或在 --replace 时接管（D20）。状态文件不含任何密钥
     const instancePath = instanceFilePath(m2Dir, parsed.port);
     let alreadyRunning = false;
-    /** 最近一次因 Origin 不在白名单被拒的页面（desktop-bridge-launcher D15）：交接 socket 的状态查询带回给 M2 Mac 客户端 */
-    let lastRejected = null;
     // 只有启动器从 ~/.m2canvas 拉起的后台 bridge、且在 macOS 上（后台安装只有 macOS，契约 15）才能卸载自己（D2）。
-    // 回调里用到的 handoff / stop 在下面才赋值：卸载只会在服务开始监听、它们都已就绪之后被调用
+    // 回调里用到的 ticketSocket / stop 在下面才赋值：卸载只会在服务开始监听、它们都已就绪之后被调用
     const uninstaller = parsed.background && process.platform === 'darwin'
         ? createSelfUninstaller({
             scriptPath: uninstallScriptPath(PACKAGE_ROOT),
@@ -218,7 +209,7 @@ export async function runBridge(argv) {
             stopInstalling: () => adapters.stopInstalling(),
             killExecs: killActiveExecs,
             forgetSelf: () => removeInstanceRecord(instancePath, process.pid),
-            closeHandoff: () => handoff?.close(),
+            closeTicketSocket: () => ticketSocket?.close(),
             exit: () => void stop(),
         })
         : undefined;
@@ -233,14 +224,11 @@ export async function runBridge(argv) {
             node: process.versions.node,
             ...(parsed.background ? { background: true } : {}),
         },
-        pairing,
+        tickets,
         service,
         agentEnv: buildAgentEnv(),
         allowedOrigins: origins,
         uninstall: uninstaller,
-        onOriginRejected: (origin) => {
-            lastRejected = { origin, at: Date.now() };
-        },
         log,
         verbose: parsed.verbose,
     }), {
@@ -257,14 +245,9 @@ export async function runBridge(argv) {
             alreadyRunning = true;
         },
     });
-    // listenWithReplace 返回 null 的情况都与端口有关（已在运行、被别的程序占着、停不掉旧的）；后台模式把「已在运行」与其余分开。
-    // 已在运行时先把承诺交给它，新页面不用重启 bridge 就能配对（D27）；交不过去也照常退出码 3
-    if (!server && parsed.background && alreadyRunning && parsed.pair) {
-        const handed = await handOffCommitment({ dir: m2Dir, port: parsed.port, commitment: parsed.pair });
-        log(handed ? 'Handed the pairing to the M2 bridge already running on this port; the new page pairs with it.' : "Couldn't hand the pairing to the M2 bridge already running on this port; the new page can reconnect with --replace.");
-    }
+    // listenWithReplace 返回 null 的情况都与端口有关（已在运行、被别的程序占着、停不掉旧的）：把「已在运行」与其余分开
     if (!server)
-        return parsed.background ? (alreadyRunning ? EXIT_ALREADY_RUNNING : EXIT_PORT_UNAVAILABLE) : 1;
+        return alreadyRunning ? EXIT_ALREADY_RUNNING : EXIT_PORT_UNAVAILABLE;
     const running = server;
     try {
         // startedAt 必须是进程启动时刻：--replace 时要等旧的退出后才写，取写文件时刻会晚出几百毫秒到几秒，下一次 --replace 就认不出它
@@ -273,8 +256,10 @@ export async function runBridge(argv) {
     catch (error) {
         console.warn(`Couldn't write ${instancePath} (${error instanceof Error ? error.message : String(error)}); --replace won't recognize this bridge.`);
     }
-    // 交接 socket（D27）在装好信号处理之后才开始监听：中间有 await，这段时间收到 SIGTERM 也要走清理
-    let handoff = null;
+    // 端口已经是自己的：旧版本的 bridge 不会再读配对文件了
+    removeLegacyPairings(m2Dir, log);
+    // 票据 socket 在装好信号处理之后才开始监听：中间有 await，这段时间收到 SIGTERM 也要走清理
+    let ticketSocket = null;
     // 兜底：bridge 经 process.exit 或未捕获异常退出时，不留下 agent 进程组和仍在运行的命令。
     // 注意 SIGHUP / SIGINT / SIGTERM 的默认处理会直接终止进程、不触发 'exit'，所以这三个信号由 lifecycle.ts 显式接管。
     process.on('exit', () => {
@@ -286,7 +271,7 @@ export async function runBridge(argv) {
             // 见上
         }
         try {
-            handoff?.close();
+            ticketSocket?.close();
         }
         catch {
             // 残留的 socket 文件由下一次启动删掉
@@ -304,7 +289,7 @@ export async function runBridge(argv) {
     const exited = new Promise((resolve) => {
         resolveExit = resolve;
     });
-    const stop = async () => {
+    const stop = async (code = 0) => {
         log('Stopping the bridge and its agents…');
         // 一次性命令（npm ci、预检、检测、授权）没有「正常收尾」可言，先同步杀掉，不等 close。
         // 授权先标记取消并删临时目录，被杀的授权命令不会被当成失败再去重跑预检
@@ -315,7 +300,7 @@ export async function runBridge(argv) {
         while (running.processes.size > 0 && Date.now() < deadline)
             await new Promise((r) => setTimeout(r, 100));
         running.processes.killAllNow();
-        resolveExit(0);
+        resolveExit(code);
     };
     installShutdownSignals(process, {
         graceful: () => void stop(),
@@ -327,14 +312,12 @@ export async function runBridge(argv) {
             process.exit(130);
         },
     });
-    if (parsed.background) {
-        handoff = await listenForHandoff({
-            dir: m2Dir,
-            port: parsed.port,
-            arm: (c) => pairing.armCommitment(c),
-            status: (c) => ({ ...pairing.commitmentStatus(c), ...(lastRejected ? { rejected: lastRejected } : {}) }),
-            log,
-        });
+    ticketSocket = await listenForTicketRequests({ dir: m2Dir, port: parsed.port, issue: () => tickets.issue(), log });
+    if (!ticketSocket) {
+        // 没有 socket 就领不到票据，任何页面都连不上：退出，让启动器与客户端看到「没在运行」而不是「已在运行」（F7）
+        log('No page can connect without the ticket socket; stopping.');
+        await stop(1);
+        return exited;
     }
     // 预热（契约 18，用户 2026-11-04 拍板 B-P1）：信号处理装好之后再起，收尾时 killActiveExecs 能杀掉它的命令；不等它，页面来查会加入
     void prewarmPrechecks({
@@ -353,22 +336,10 @@ export async function runBridge(argv) {
     console.log(`M2 local agent bridge ${version}`);
     console.log(`  Listening on ws://127.0.0.1:${running.port}${BRIDGE_WS_PATH} (this machine only)`);
     console.log(`  Working directory for agents: ${parsed.cwd}`);
-    console.log(`  Accepts pages from: ${origins.join(', ')}`);
-    if (parsed.dev)
-        console.log('  --dev: any app on the dev port can ask to pair. Only enter the code into your own M2 dev server.');
-    // 带 --pair（命令是从 M2 页面复制的）：主路径上用户不需要启动码，打印出来反而让人以为要去输码；
-    // 页面对不上承诺时会以未配对状态连上，那时照常出码并带上发起方 Origin
-    if (parsed.background)
-        console.log('  Started in the background by the M2 launcher: no pairing codes are shown; pair from M2 with a new start command.');
+    console.log(`  Accepts only pages the M2 desktop app authorizes, from: ${origins.join(', ')}`);
     if (lifetime !== null)
         console.log(`  Dev mode in the background: stops by itself at ${clock(Date.now() + lifetime)}.`);
-    if (pairUntil !== null)
-        console.log(`  Waiting for the M2 page that gave you this command (until ${clock(pairUntil)})…`);
-    else if (!parsed.background)
-        pairing.issueCode('startup');
     const found = await Promise.all(BRIDGE_AGENT_IDS.map(detect));
     console.log(`  Agents: ${found.map((agent) => `${LABELS[agent.id]} ${agent.installed ? '✓' : '–'}`).join('   ')}`);
-    if (!parsed.background)
-        console.log('  Keep this window open while you use local agents in M2. Press Ctrl+C to stop.\n');
     return exited;
 }

package/dist/bridge/protocol.js

@@ -11,7 +11,11 @@
  *   bridge 至少同时支持前一个版本。页面必须忽略不认识的字段 / 事件，把不认识的 state 当成 unknown。
  * - bridge 不翻译 ACP：agent → 页面的 `acp` 行原样转发（不保证是 JSON）；页面 → agent 的行只做方法白名单、会话范围与无人值守模式检查（acp-guard.ts），
  *   翻译全部在页面做。
- * - 配对 = 授权该页面以用户的身份驱动本机 agent（包括让它执行命令）；页面代码与 token 的保管要按这个级别对待。
+ * - 连上本机连接 = 授权该页面以用户的身份驱动本机 agent（包括让它执行命令）。change bridge-client-only 起只有 M2 客户端主进程
+ *   替页面加了一次性票据（`BRIDGE_TICKET_HEADER`）的握手才被接受，页面不持有任何本机连接凭证；配对整体删掉（hello 的
+ *   `token` / `pairSecret`、`pair` 方法、`pairing_*` 错误码、`tooManyUnpaired`、welcome 的 `token`），类型随页面一起删了（1a 阶段 B）。
+ *   不升协议版本、也不同时支持前一版本：这是契约 9「同版本只加法」经用户拍板的例外（U5 / F6，不兼容旧版本）。
+ *   welcome 的 `paired` / `tokenRejected` 本机连接仍按旧形状发出（恒为 true / false），页面不再读。
  */
 /** 本 bridge 支持的协议版本（页面在 hello 里给出自己支持的列表，bridge 选双方共有的最大值） */
 export const BRIDGE_PROTOCOL_VERSION = 1;
@@ -19,6 +23,12 @@ export const BRIDGE_SUPPORTED_PROTOCOLS = [1];
 /** 默认端口与路径。页面必须连 127.0.0.1（不是 localhost：localhost 可能先解析到 ::1，bridge 不监听 IPv6）。 */
 export const BRIDGE_DEFAULT_PORT = 47821;
 export const BRIDGE_WS_PATH = '/bridge';
+/**
+ * M2 客户端主进程替页面加进 WebSocket 握手的一次性票据请求头（change bridge-client-only D3 / D4 起）。
+ * 票据从后台模式的 `~/.m2canvas/bridge-<port>.sock` 领（请求 `{"type":"ticket"}`）。页面代码不会、也不能设置它：
+ * 浏览器的 WebSocket API 加不了自定义请求头。客户端那边各存一份常量，由防漂移单测对照这里（mac-client 契约 11）。
+ */
+export const BRIDGE_TICKET_HEADER = 'X-M2-Bridge-Ticket';
 /** 与前端 src/lib/agent-types 的 AgentType 取值一致（是它的子集），顺序即 agents/list 的返回顺序 */
 export const BRIDGE_AGENT_IDS = ['claude', 'codex', 'cursor', 'opencode', 'qoder'];
 /**
@@ -64,7 +74,6 @@ export const BRIDGE_UNATTENDED_MODE_VALUES = {
     qoder: ['yolo'],
 };
 export const BRIDGE_METHODS = [
-    'pair',
     'agents/list',
     'agent/prepare',
     'agent/precheck',
@@ -86,5 +95,4 @@ export const BRIDGE_CLOSE_CODES = {
     badHandshake: 4400,
     timeout: 4408,
     protocolUnsupported: 4426,
-    tooManyUnpaired: 4429,
 };

package/dist/bridge/security.js

@@ -1,22 +1,5 @@
-/**
- * 本机 ACP bridge 的连接准入判定（纯函数）。在 HTTP upgrade 阶段、完成 WebSocket 握手之前调用。
- *
- * 这里管的是「谁能连上来」：Origin 白名单与只接受本机连接（第三道「配对 token」在 pairing.ts）。
- * 浏览器这层不可依赖：开了本机代理的用户，Chrome 不会弹本地网络访问框（ACP PoC 报告 §3），
- * 所以任何网站都能尝试连 127.0.0.1，只能靠 bridge 自己挡。
- * 连上并配对之后页面能做什么，见 server.ts / acp-guard.ts 的文件头：配对 = 授权该页面驱动本机 agent。
- *
- * 维护约束：
- * - 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，推翻了最初的「开发域名常开」）。名单写死在包里（主站 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';
+import { BRIDGE_TICKET_HEADER, BRIDGE_WS_PATH } from './protocol.js';
 export { PROD_ORIGINS };
 /** 本地开发 M2 用（Vite 默认端口）；只有 `bridge --dev` 才放行 */
 export const DEV_ORIGINS = ['http://localhost:5173', 'http://127.0.0.1:5173'];
@@ -34,13 +17,19 @@ export function isAllowedHost(host, port) {
 export function isLoopbackAddress(address) {
     return address === '127.0.0.1' || address === '::ffff:127.0.0.1' || address === '::1';
 }
-const MAX_REPORTED_ORIGIN_CHARS = 200;
+/** Node 把请求头名转成小写；同名头出现多次时自定义头会被拼成一个字符串（再由票据格式挡掉），数组一律当没有 */
+export function readTicketHeader(headers) {
+    const value = headers[BRIDGE_TICKET_HEADER.toLowerCase()];
+    return typeof value === 'string' ? value : undefined;
+}
 /**
  * 拒绝时返回 HTTP 状态，由调用方直接写回并销毁 socket，不完成握手。
- * 403 而不是「握手后再关」：不对非白名单页面完成任何握手。注意这挡不住「探测 bridge 是否在运行」——
+ * 403 / 401 而不是「握手后再关」：不对非白名单页面、没有票据的连接完成任何握手。注意这挡不住「探测 bridge 是否在运行」——
  * 任何网站用 no-cors 请求 http://127.0.0.1:<port>/ 都能分辨「有响应」与「连接被拒」，只暴露这一点信息。
+ *
+ * `redeem` 核对并用掉票据（TicketBook.redeem）；只在前三条都通过后调用。
  */
-export function checkUpgrade(info, port, origins) {
+export function checkUpgrade(info, port, origins, redeem) {
     const pathname = (info.path ?? '').split('?')[0];
     if (pathname !== BRIDGE_WS_PATH)
         return { ok: false, status: 404, reason: `unknown path ${pathname}` };
@@ -48,10 +37,11 @@ export function checkUpgrade(info, port, origins) {
         return { ok: false, status: 403, reason: `remote ${info.remoteAddress ?? 'unknown'}` };
     if (!isAllowedHost(info.host, port))
         return { ok: false, status: 403, reason: `host ${info.host ?? 'missing'}` };
-    if (!isAllowedOrigin(info.origin, origins)) {
-        if (info.origin === undefined)
-            return { ok: false, status: 403, reason: 'origin missing' };
-        return { ok: false, status: 403, reason: `origin ${info.origin}`, rejectedOrigin: info.origin.slice(0, MAX_REPORTED_ORIGIN_CHARS) };
-    }
-    return { ok: true };
+    if (!isAllowedOrigin(info.origin, origins))
+        return { ok: false, status: 403, reason: info.origin === undefined ? 'origin missing' : `origin ${info.origin}` };
+    if (info.ticket === undefined)
+        return { ok: false, status: 401, reason: 'missing ticket' };
+    if (!redeem(info.ticket))
+        return { ok: false, status: 401, reason: 'invalid ticket' };
+    return { ok: true, auth: 'client-ticket' };
 }