@m2canvas/connect 0.12.0 → 0.14.0

package/README.md

@@ -26,40 +26,23 @@ 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.
-- **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.
+- **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. 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.
+- **M2 without setup for Claude Code and Codex (from 0.14.0).** When you are signed in to the M2 desktop app, the app keeps a 24-hour M2 session token in `~/.m2canvas/mcp-session/headers.json` (only your account can read it; the app removes it when you sign out or quit). For the Claude Code and Codex the bridge bundles, M2 can then ask the bridge to add one MCP server named `patch_session` to that agent session only: its address is fixed in this package, and the agent reads the token through a small script the bridge writes to `~/.m2canvas/bin/m2-mcp-session-headers`. The token never appears in process arguments or environment variables, the page never sees it, and your agent config files are not changed; for that session the bridge hides your own entries that point to M2. Other agents, and sessions where the token isn't available, use their own M2 MCP setup as before.
 - **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 (and the M2 session token, if any); `~/.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,44 @@
 /**
- * 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、`process/start` 的会话令牌开关与用于比对的 userId
+ * （change acp-session-m2-token，契约 3 / 21：params 只认 `agent` 与 `m2Session: { userId }`，多一个键即 bad_message），进不了 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 { isUserId } from './session-token.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 };
+/** params 必须恰好是这些键（自有属性），同 auth-call.ts */
+function hasExactKeys(value, keys) {
+    const own = Object.keys(value);
+    return own.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+/**
+ * `process/start` 的参数（契约 3 / 21）：只认 `agent` 与可选的 `m2Session: { userId }`。返回会话令牌开关；不合规抛 bad_message。
+ * 旧版 bridge 不校验多余字段、会把 `m2Session` 静默丢掉，所以页面只按预检的 `m2Session` 决定走哪条路径（design D11）。
+ */
+function sessionParam(params) {
+    if (hasExactKeys(params, ['agent']))
+        return undefined;
+    if (!hasExactKeys(params, ['agent', 'm2Session']))
+        throw new BridgeFailure('bad_message', 'process/start only accepts agent and m2Session');
+    const session = params.m2Session;
+    if (typeof session !== 'object' || session === null || Array.isArray(session) || !hasExactKeys(session, ['userId'])) {
+        throw new BridgeFailure('bad_message', 'm2Session only accepts userId');
     }
-    if (!conn.paired)
-        throw new BridgeFailure('not_paired', 'pair this page first');
+    const userId = session.userId;
+    if (!isUserId(userId))
+        throw new BridgeFailure('bad_message', 'm2Session.userId is not a valid user id');
+    return { userId };
+}
+export async function handleCall(ctx, conn, id, method, params) {
+    // 纵深判断：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))
@@ -44,14 +62,16 @@ export async function handleCall(ctx, conn, id, method, params) {
             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);
+            // 先校验参数，再做任何检测（多余键不能借检测的副作用）；连接是否经客户端认证已在函数开头判过（1a 的门，契约 21 依赖它）
+            const session = sessionParam(params);
+            const { m2SessionExpiresAt, ...launch } = await ctx.service.launch(agent, session);
             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 };
+                ctx.log(session ? `Started ${agent} with the M2 session token.` : `Started ${agent}.`);
+                return { processId, agent, cwd: ctx.cwd, ...(m2SessionExpiresAt === undefined ? {} : { m2SessionExpiresAt }) };
             }
             catch (error) {
                 if (error instanceof ProcessError)

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,38 +3,45 @@
  *
  * 只由 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';
 import { prewarmPrechecks } from './precheck-cache.js';
 import { selfTestProblems } from './self-test.js';
 import { runCheckUpdate } from './update-io.js';
+import { welcomeRejectedOption } from './update.js';
 import { startBridgeServer } from './server.js';
 import { createAgentService } from './service.js';
+import { createSessionTokens } from './session-token.js';
+import { ensureHelperScript, readTextFile } from './session-token-io.js';
+import { M2_MCP_URL } from '../site-config.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 +60,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 +129,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({
@@ -196,6 +193,17 @@ export async function runBridge(argv) {
         expectAvailable: () => isExecutable(EXPECT_PATH),
         // 出现过「通过」之后一次真跑没通过：告诉之前可能拿到通过的页面（尽力收回，契约 18）
         onPrecheckRevoked: (result) => server?.broadcast('precheck/updated', result),
+        // M2 会话令牌（契约 21）：令牌文件由 M2 客户端维护，这里只读；地址只取站点配置，--dev 也一样（design T3）
+        sessionTokens: createSessionTokens({
+            home,
+            cwd: parsed.cwd,
+            agentEnv: buildAgentEnv(),
+            mcpUrl: M2_MCP_URL,
+            readText: (path) => readTextFile(path),
+            ensureHelper: ensureHelperScript,
+            now: Date.now,
+            log,
+        }),
         log,
     });
     const version = packageVersion();
@@ -203,10 +211,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 +224,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 +239,13 @@ 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() };
-        },
+        // 启动器拉黑的版本只对后台模式有意义（终端模式不经启动器，change bridge-normal-update D6）；每次 welcome 现读
+        ...welcomeRejectedOption({ background: parsed.background, home }),
         log,
         verbose: parsed.verbose,
     }), {
@@ -257,14 +262,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 +273,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 +288,7 @@ export async function runBridge(argv) {
             // 见上
         }
         try {
-            handoff?.close();
+            ticketSocket?.close();
         }
         catch {
             // 残留的 socket 文件由下一次启动删掉
@@ -304,7 +306,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 +317,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 +329,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 +353,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;
 }