@m2canvas/connect 0.4.0 → 0.6.0

package/dist/bridge/errors.js

@@ -0,0 +1,9 @@
+export class BridgeFailure extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}

package/dist/bridge/exec.js

@@ -9,6 +9,9 @@
  * 超时必须真的封顶：命令可能再拉起子进程（`claude mcp list` 会启动用户配置的 stdio MCP 做健康检查，npm ci 有自己的子进程），
  * 孙进程继承了输出管道时，'close' 要等它们全部退出才触发。所以 POSIX 下每条命令是独立进程组，超时对整组 SIGKILL 并**立即**返回，
  * 不再等 'close'。bridge 退出时 killActiveExecs 清掉仍在运行的命令（main.ts 的退出路径调用）。
+ *
+ * startCommand 是可从外部结束的版本（授权命令：页面取消、连接关闭、10 分钟超时，见 authorize.ts）；execCommand 建在它上面，
+ * 两者共用同一个 active 集合，所以 bridge 退出时授权命令也一起被清理（design D7）。
  */
 import { spawn } from 'node:child_process';
 const DEFAULT_MAX_OUTPUT = 1024 * 1024;
@@ -34,22 +37,56 @@ export function killActiveExecs() {
         killTree(child);
     active.clear();
 }
-export const execCommand = (command, args, options) => new Promise((resolve) => {
+function signalTree(child, signal) {
+    if (child.pid === undefined)
+        return;
+    try {
+        if (GROUPS)
+            process.kill(-child.pid, signal);
+        else
+            child.kill(signal);
+    }
+    catch {
+        // ESRCH：已经退出，'close' 会照常结束这条命令
+    }
+}
+export function startCommand(command, args, options) {
     const max = options.maxOutput ?? DEFAULT_MAX_OUTPUT;
     let stdout = '';
     let stderr = '';
     let settled = false;
-    let timer;
+    let graceTimer;
     let child;
-    const finish = (result, timedOut = false) => {
+    let resolve = () => undefined;
+    const result = new Promise((done) => {
+        resolve = done;
+    });
+    const finish = (outcome, timedOut = false) => {
         if (settled)
             return;
         settled = true;
-        if (timer)
-            clearTimeout(timer);
+        if (graceTimer)
+            clearTimeout(graceTimer);
         if (child)
             active.delete(child);
-        resolve({ ...result, stdout, stderr, timedOut });
+        resolve({ ...outcome, stdout, stderr, timedOut });
+    };
+    const kill = (error, timedOut = false) => {
+        if (settled)
+            return;
+        if (child)
+            killTree(child);
+        finish({ code: null, signal: null, error }, timedOut);
+    };
+    const handle = {
+        result,
+        kill,
+        terminate(graceMs, error, timedOut = false) {
+            if (settled || !child || graceTimer)
+                return;
+            signalTree(child, 'SIGTERM');
+            graceTimer = setTimeout(() => kill(error, timedOut), graceMs);
+        },
     };
     try {
         child = spawn(command, args, {
@@ -64,25 +101,29 @@ export const execCommand = (command, args, options) => new Promise((resolve) =>
     catch (error) {
         // 同步抛出只发生在参数非法时；按启动失败处理
         finish({ code: null, signal: null, error: error instanceof Error ? error.message : String(error) });
-        return;
+        return handle;
     }
     const running = child;
     active.add(running);
-    timer = setTimeout(() => {
-        killTree(running);
-        finish({ code: null, signal: null, error: `timed out after ${options.timeoutMs}ms` }, true);
-    }, options.timeoutMs);
     running.stdout?.setEncoding('utf8');
     running.stderr?.setEncoding('utf8');
     running.stdout?.on('data', (chunk) => {
         stdout = (stdout + chunk).slice(-max);
+        options.onOutput?.(chunk);
     });
     running.stderr?.on('data', (chunk) => {
         stderr = (stderr + chunk).slice(-max);
+        options.onOutput?.(chunk);
     });
     running.on('error', (error) => finish({ code: null, signal: null, error: error.message }));
     running.on('close', (code, signal) => finish({ code, signal, error: null }));
-});
+    return handle;
+}
+export const execCommand = (command, args, options) => {
+    const running = startCommand(command, args, options);
+    const timer = setTimeout(() => running.kill(`timed out after ${options.timeoutMs}ms`, true), options.timeoutMs);
+    return running.result.finally(() => clearTimeout(timer));
+};
 /** stdout 与 stderr 合并（有些 CLI 把状态写在 stderr，例如 `codex login status`） */
 export function combinedOutput(result) {
     const parts = [result.stdout, result.stderr, result.error ?? ''].filter((part) => part.length > 0);

package/dist/bridge/instance.js

@@ -0,0 +1,239 @@
+/**
+ * 端口被占时识别并接管正在运行的 bridge（change acp-terminal-free-auth，design D20，`connect/local-bridge` 契约 13）。
+ *
+ * 场景：页面已经连上一个 bridge、只是没配对，用户却找不到那个 bridge 的终端（在别的窗口、被别的工具在后台拉起），
+ * 拿不到配对码；新运行的命令又撞端口。这里让新命令认出占端口的是不是 M2 bridge，给出 pid 与终端，或者在 `--replace` 时接管。
+ *
+ * 维护约束：
+ * - 状态文件只放 pid / port / startedAt，**不放配对码、token、承诺**：契约 2 要求码只出现在终端，
+ *   能读 `~/.m2canvas`、又能连本机端口的进程（例如沙箱里的 agent）拿到码就能自己配对。
+ * - 「认定」要同时满足：文件端口相符、pid 存活、`ps` 算出的启动时刻与 startedAt 相差 ≤ START_TOLERANCE_MS。
+ *   崩溃留下的旧文件、被复用的 pid 都过不了这一关；认不出来就什么都不停。
+ * - 停止只发 SIGTERM（第一次走旧 bridge 的正常收尾，第二次走它「连按两次」的立即清理），**不发 SIGKILL**：
+ *   SIGKILL 跳过清理，agent 都在各自的进程组里，会变成孤儿（契约 5）。
+ * - Windows 没有 `ps`，一律不认定（D1 / CO-1）。
+ * - 认不出来时只提示：用 lsof 查到占端口的 pid 与命令行给用户看，让用户自己决定停不停；这里从不停认不出来的进程。
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** startedAt 是进程启动时刻（不是写文件时刻），与 ps 的 etime 只差秒级取整；留 3 秒余量 */
+export const START_TOLERANCE_MS = 3_000;
+/** 第一次 SIGTERM 后等多久：旧 bridge 正常收尾先关连接、停 agent，再等 agent 退出（宽限 3 秒），还要留出启动横幅里检测命令的余量 */
+export const STOP_GRACEFUL_WAIT_MS = 8_000;
+/** 第二次 SIGTERM（立即清理）后再等多久 */
+export const STOP_IMMEDIATE_WAIT_MS = 3_000;
+const STOP_POLL_MS = 100;
+const PS_PATH = '/bin/ps';
+const PS_TIMEOUT_MS = 5_000;
+const LSOF_PATHS = ['/usr/sbin/lsof', '/usr/bin/lsof'];
+const COMMAND_DISPLAY_CHARS = 160;
+export function instanceFilePath(m2Dir, port) {
+    return join(m2Dir, `bridge-${port}.json`);
+}
+/** 本进程的启动时刻 */
+export function processStartedAt() {
+    return Math.round(Date.now() - process.uptime() * 1000);
+}
+/** 只写这四个字段：调用方多带的任何字段都不落盘（契约 2：文件里不能有配对码、token、承诺） */
+export function writeInstanceRecord(path, record) {
+    const { pid, port, startedAt } = record;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(path), 0o700);
+    writeFileSync(path, `${JSON.stringify({ version: 1, pid, port, startedAt })}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+export function readInstanceRecord(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const record = parsed;
+    if (record.version !== 1 || !isPositiveInteger(record.pid) || !isPositiveInteger(record.port) || !isPositiveInteger(record.startedAt))
+        return null;
+    return { version: 1, pid: record.pid, port: record.port, startedAt: record.startedAt };
+}
+/** 只删属于这个 pid 的文件：接管它的新 bridge 可能已经写了自己的 */
+export function removeInstanceRecord(path, pid) {
+    if (readInstanceRecord(path)?.pid !== pid)
+        return;
+    rmSync(path, { force: true });
+}
+/** `ps -o etime=` 的格式 `[[dd-]hh:]mm:ss` → 秒 */
+export function parseEtime(value) {
+    const match = /^(?:(?:(\d+)-)?(\d{1,2}):)?(\d{1,2}):(\d{2})$/.exec(value.trim());
+    if (!match)
+        return null;
+    const [, days, hours, minutes, seconds] = match;
+    const [d, h, m, s] = [days, hours, minutes, seconds].map((part) => (part === undefined ? 0 : Number(part)));
+    if (m === undefined || s === undefined || s > 59 || m > 59)
+        return null;
+    return (d ?? 0) * 86_400 + (h ?? 0) * 3_600 + m * 60 + s;
+}
+export function createPsProbe(exec, env, now = Date.now) {
+    return {
+        async inspect(pid) {
+            const result = await exec(PS_PATH, ['-o', 'etime=,tty=', '-p', String(pid)], {
+                env: { ...env, LC_ALL: 'C' },
+                timeoutMs: PS_TIMEOUT_MS,
+                maxOutput: 1024,
+            });
+            if (result.code !== 0)
+                return null;
+            const [etime, tty] = result.stdout.trim().split(/\s+/);
+            const seconds = etime === undefined ? null : parseEtime(etime);
+            if (seconds === null)
+                return null;
+            const terminal = tty && !/^[?-]+$/.test(tty) ? tty : null;
+            return { startedAt: now() - seconds * 1000, terminal };
+        },
+    };
+}
+/** 用 lsof 查占端口的进程（只读）。没有 lsof（多数 Linux 默认没装）、没有监听者、输出认不出时 null */
+export function createLsofProbe(exec, env, exists = existsSync) {
+    return {
+        async find(port) {
+            const lsof = LSOF_PATHS.find((path) => exists(path));
+            if (!lsof)
+                return null;
+            const options = { env: { ...env, LC_ALL: 'C' }, timeoutMs: PS_TIMEOUT_MS, maxOutput: 4096 };
+            const listed = await exec(lsof, ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fp'], options);
+            const pid = Number(/^p(\d+)$/m.exec(listed.stdout)?.[1]);
+            if (listed.code !== 0 || !Number.isInteger(pid) || pid <= 0)
+                return null;
+            const ps = await exec(PS_PATH, ['-o', 'command=', '-p', String(pid)], options);
+            const full = ps.code === 0 ? ps.stdout.trim() : '';
+            const command = full.length > COMMAND_DISPLAY_CHARS ? `${full.slice(0, COMMAND_DISPLAY_CHARS - 1)}…` : full;
+            return { pid, command: command || null };
+        },
+    };
+}
+export async function identifyRunningBridge(path, port, probe, platform) {
+    if (platform === 'win32')
+        return null;
+    const record = readInstanceRecord(path);
+    if (!record || record.port !== port)
+        return null;
+    const info = await probe.inspect(record.pid);
+    if (!info || Math.abs(info.startedAt - record.startedAt) > START_TOLERANCE_MS)
+        return null;
+    return { pid: record.pid, port: record.port, startedAt: record.startedAt, terminal: info.terminal };
+}
+/**
+ * 本机进程的实现。存活要两步判断：`kill(pid, 0)` 报 ESRCH 就是不在了；否则（成功或 EPERM）再看 `ps` 的状态，
+ * 僵尸（Z，已退出、父进程还没回收）按已退出处理 —— 端口已经释放，而 `kill(pid, 0)` 对僵尸照样成功。
+ * 被别的工具在后台拉起、父进程不及时回收的 bridge 会停在僵尸状态（实测：测试脚本拉起的 bridge 退出后一直是 Z）。
+ */
+export function createStopDeps(exec, env, kill = process.kill.bind(process)) {
+    return {
+        signal: (pid, signal) => {
+            kill(pid, signal);
+        },
+        async isAlive(pid) {
+            try {
+                kill(pid, 0);
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    return false;
+            }
+            const result = await exec(PS_PATH, ['-o', 'stat=', '-p', String(pid)], { env: { ...env, LC_ALL: 'C' }, timeoutMs: PS_TIMEOUT_MS, maxOutput: 256 });
+            if (result.code !== 0)
+                return false;
+            return !result.stdout.trim().startsWith('Z');
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: Date.now,
+    };
+}
+async function waitForExit(pid, deps, timeoutMs) {
+    const deadline = deps.now() + timeoutMs;
+    while (await deps.isAlive(pid)) {
+        if (deps.now() >= deadline)
+            return false;
+        await deps.sleep(STOP_POLL_MS);
+    }
+    return true;
+}
+function sendTerm(pid, deps) {
+    try {
+        deps.signal(pid, 'SIGTERM');
+    }
+    catch {
+        // 不在这里判断：已经退出（ESRCH）会被随后的存活检查认成「已停止」，发不了信号（EPERM）会被认成「没停掉」
+    }
+}
+/** 停掉认定的 bridge：SIGTERM → 等正常收尾 → 再一次 SIGTERM（立即清理）→ 再等。从不 SIGKILL。返回是否已退出 */
+export async function stopRunningBridge(pid, deps) {
+    sendTerm(pid, deps);
+    if (await waitForExit(pid, deps, STOP_GRACEFUL_WAIT_MS))
+        return true;
+    sendTerm(pid, deps);
+    return waitForExit(pid, deps, STOP_IMMEDIATE_WAIT_MS);
+}
+function isAddressInUse(error) {
+    return error?.code === 'EADDRINUSE';
+}
+function describe(bridge, clock) {
+    const where = bridge.terminal ? `in terminal ${bridge.terminal}` : 'in the background';
+    return `pid ${bridge.pid}, started at ${clock(bridge.startedAt)} ${where}`;
+}
+/** 认不出来时的提示：只给可操作的查找 / 停止方法，不停任何进程 */
+function unrecognizedMessage(port, listener, platform, replace) {
+    const note = replace ? ' --replace only stops a bridge it can recognize (0.6.0 or later, not on Windows), so nothing was stopped.' : '';
+    if (listener) {
+        return (`Port ${port} is already in use by pid ${listener.pid}${listener.command ? ` (${listener.command})` : ''}.\n` +
+            `If that's an older M2 bridge, stop it with "kill ${listener.pid}" (or press Ctrl+C in its terminal), then run this command again. ` +
+            `Otherwise start this one with --port <n>.${note}`);
+    }
+    const find = platform === 'win32'
+        ? `find it with "netstat -ano | findstr :${port}" and stop it with "taskkill /PID <pid>"`
+        : `find it with "lsof -nP -iTCP:${port} -sTCP:LISTEN" and stop it with "kill <pid>"`;
+    return (`Port ${port} is already in use. If another bridge is running, ${find} (or press Ctrl+C in its terminal), then run this command again. ` +
+        `Otherwise start this one with --port <n>.${note}`);
+}
+/**
+ * 监听；撞端口时认定占用者并按 `--replace` 处理。返回 null 表示已打印原因、调用方以退出码 1 结束。
+ * 不是 EADDRINUSE 的错误照常抛出。
+ */
+export async function listenWithReplace(listen, ctx) {
+    try {
+        return await listen();
+    }
+    catch (error) {
+        if (!isAddressInUse(error))
+            throw error;
+    }
+    const running = await ctx.identify();
+    if (!running) {
+        ctx.error(unrecognizedMessage(ctx.port, await ctx.findListener(), ctx.platform, ctx.replace));
+        return null;
+    }
+    if (!ctx.replace) {
+        const stopIt = running.terminal ? `press Ctrl+C in that terminal or run "kill ${running.pid}"` : `stop it with "kill ${running.pid}"`;
+        ctx.error(`Port ${ctx.port} is already in use by another M2 bridge (${describe(running, ctx.clock)}).\n` +
+            `To start this one instead, ${stopIt}, then run this command again. Or run it again with --replace to stop that bridge first.`);
+        return null;
+    }
+    ctx.log(`Stopping the M2 bridge already running on port ${ctx.port} (${describe(running, ctx.clock)})…`);
+    if (!(await ctx.stop(running.pid))) {
+        ctx.error(`The M2 bridge on port ${ctx.port} (pid ${running.pid}) didn't stop. Stop it with "kill ${running.pid}" (or press Ctrl+C in its terminal), then run this command again.`);
+        return null;
+    }
+    try {
+        return await listen();
+    }
+    catch (error) {
+        if (!isAddressInUse(error))
+            throw error;
+        ctx.error(`Port ${ctx.port} is still in use after stopping the old bridge. Wait a few seconds and run this command again.`);
+        return null;
+    }
+}

package/dist/bridge/main.js

@@ -9,13 +9,15 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { home, which } from '../system.js';
+import { home, isExecutable, which } from '../system.js';
 import { AdapterManager, ADAPTERS } from './adapters.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 { installShutdownSignals } from './lifecycle.js';
-import { PairingManager, createFilePairingStore } from './pairing.js';
+import { PairingManager, createFilePairingStore, isPairCommitment } from './pairing.js';
 import { BRIDGE_AGENT_IDS, BRIDGE_DEFAULT_PORT, BRIDGE_WS_PATH } from './protocol.js';
 import { DEV_ORIGINS, PROD_ORIGINS, allowedOrigins } from './security.js';
 import { startBridgeServer } from './server.js';
@@ -29,26 +31,35 @@ const LABELS = {
     opencode: 'OpenCode',
     qoder: 'Qoder',
 };
-const HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev]
+export const BRIDGE_HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev] [--pair <value>] [--replace]
        npx @m2canvas/connect bridge --unpair
 
 Runs the local agent bridge so M2 (in Chrome) can 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 first time, M2 asks for the pairing code shown here. A paired page can make
-these agents read and change files and run commands as you, so only pair M2.
+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.
 
-  --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
-  --unpair     forget all paired pages and exit
-  -h, --help   show this help`;
-function parseArgs(argv) {
-    const args = { port: BRIDGE_DEFAULT_PORT, cwd: process.cwd(), verbose: false, unpair: false, help: false, dev: false };
+  --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`;
+/** 解析 `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 };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '-h' || arg === '--help')
@@ -59,6 +70,16 @@ function parseArgs(argv) {
             args.unpair = true;
         else if (arg === '--dev')
             args.dev = true;
+        else if (arg === '--replace')
+            args.replace = true;
+        else if (arg === '--pair') {
+            const value = argv[++i];
+            if (value === undefined)
+                return '--pair needs a value';
+            if (!isPairCommitment(value))
+                return `invalid --pair value ${value}; copy the start command from M2 again`;
+            args.pair = value;
+        }
         else if (arg === '--port' || arg === '--cwd') {
             const value = argv[++i];
             if (value === undefined)
@@ -96,6 +117,15 @@ function printCode(info) {
     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); ` +
@@ -112,13 +142,13 @@ function describeAdapter(agent, info) {
     return null;
 }
 export async function runBridge(argv) {
-    const parsed = parseArgs(argv);
+    const parsed = parseBridgeArgs(argv);
     if (typeof parsed === 'string') {
-        console.error(`${parsed}\n\n${HELP}`);
+        console.error(`${parsed}\n\n${BRIDGE_HELP}`);
         return 2;
     }
     if (parsed.help) {
-        console.log(HELP);
+        console.log(BRIDGE_HELP);
         return 0;
     }
     const m2Dir = join(home, '.m2canvas');
@@ -142,7 +172,12 @@ export async function runBridge(argv) {
         onCodeIssued: printCode,
         onLocked: printLocked,
         onProblem: (message) => console.warn(message),
+        onCommitmentReused: printReused,
     });
+    // 承诺必须在开始监听之前挂上：等待中的页面每 2 秒探测一次，监听一开始就可能连上；晚挂一步它就撞上 no_commitment、落到输码
+    const pairUntil = parsed.pair ? pairing.armCommitment(parsed.pair) : null;
+    // 进度更新（D12）也经 onState 广播，终端只在状态变化时打一行
+    const loggedState = new Map();
     const adapters = new AdapterManager({
         sourceRoot: join(PACKAGE_ROOT, 'adapters'),
         installRoot: join(m2Dir, 'acp-adapters'),
@@ -154,9 +189,12 @@ export async function runBridge(argv) {
             shell: process.platform === 'win32',
         }),
         onState: (agent, info) => {
-            const line = describeAdapter(agent, info);
-            if (line)
-                log(line);
+            if (loggedState.get(agent) !== info.state) {
+                loggedState.set(agent, info.state);
+                const line = describeAdapter(agent, info);
+                if (line)
+                    log(line);
+            }
             server?.broadcast('adapter/state', { agent, adapter: info });
         },
     });
@@ -171,34 +209,55 @@ export async function runBridge(argv) {
         nodePath: process.execPath,
         nodeVersion: process.versions.node,
         cliPath: fileURLToPath(new URL('../cli.js', import.meta.url)),
+        platform: process.platform,
+        expectAvailable: () => isExecutable(EXPECT_PATH),
     });
     const version = packageVersion();
     const origins = allowedOrigins(parsed.dev);
+    // 端口被占时认出正在运行的 M2 bridge，给出 pid 与终端，或在 --replace 时接管（D20）。状态文件不含任何密钥
+    const instancePath = instanceFilePath(m2Dir, parsed.port);
+    server = await listenWithReplace(() => startBridgeServer({
+        port: parsed.port,
+        cwd: parsed.cwd,
+        bridge: { name: '@m2canvas/connect', version, platform: process.platform, arch: process.arch, node: process.versions.node },
+        pairing,
+        service,
+        agentEnv: buildAgentEnv(),
+        allowedOrigins: origins,
+        log,
+        verbose: parsed.verbose,
+    }), {
+        port: parsed.port,
+        replace: parsed.replace,
+        identify: () => identifyRunningBridge(instancePath, parsed.port, createPsProbe(execCommand, probeEnv), process.platform),
+        findListener: () => createLsofProbe(execCommand, probeEnv).find(parsed.port),
+        platform: process.platform,
+        stop: (pid) => stopRunningBridge(pid, createStopDeps(execCommand, probeEnv)),
+        log,
+        error: (message) => console.error(message),
+        clock,
+    });
+    if (!server)
+        return 1;
+    const running = server;
     try {
-        server = await startBridgeServer({
-            port: parsed.port,
-            cwd: parsed.cwd,
-            bridge: { name: '@m2canvas/connect', version, platform: process.platform, arch: process.arch, node: process.versions.node },
-            pairing,
-            service,
-            agentEnv: buildAgentEnv(),
-            allowedOrigins: origins,
-            log,
-            verbose: parsed.verbose,
-        });
+        // startedAt 必须是进程启动时刻：--replace 时要等旧的退出后才写，取写文件时刻会晚出几百毫秒到几秒，下一次 --replace 就认不出它
+        writeInstanceRecord(instancePath, { version: 1, pid: process.pid, port: parsed.port, startedAt: processStartedAt() });
     }
     catch (error) {
-        const code = error.code;
-        if (code === 'EADDRINUSE') {
-            console.error(`Port ${parsed.port} is already in use. Another bridge may already be running; stop it, or start this one with --port <n>.`);
-            return 1;
-        }
-        throw error;
+        console.warn(`Couldn't write ${instancePath} (${error instanceof Error ? error.message : String(error)}); --replace won't recognize this bridge.`);
     }
-    const running = server;
     // 兜底：bridge 经 process.exit 或未捕获异常退出时，不留下 agent 进程组和仍在运行的命令。
     // 注意 SIGHUP / SIGINT / SIGTERM 的默认处理会直接终止进程、不触发 'exit'，所以这三个信号由 lifecycle.ts 显式接管。
     process.on('exit', () => {
+        // 只删属于本进程的状态文件；删不掉只会让之后的认定落到「pid 不在」，不影响退出
+        try {
+            removeInstanceRecord(instancePath, process.pid);
+        }
+        catch {
+            // 见上
+        }
+        running.authorizations.killAllNow();
         running.processes.killAllNow();
         killActiveExecs();
     });
@@ -213,7 +272,9 @@ export async function runBridge(argv) {
     });
     const stop = async () => {
         log('Stopping the bridge and its agents…');
-        // 一次性命令（npm ci、预检、检测）没有「正常收尾」可言，先同步杀掉，不等 close
+        // 一次性命令（npm ci、预检、检测、授权）没有「正常收尾」可言，先同步杀掉，不等 close。
+        // 授权先标记取消并删临时目录，被杀的授权命令不会被当成失败再去重跑预检
+        running.authorizations.killAllNow();
         killActiveExecs();
         await running.close();
         const deadline = Date.now() + KILL_GRACE_MS;
@@ -226,6 +287,7 @@ export async function runBridge(argv) {
         graceful: () => void stop(),
         // 收尾期间又来一个信号（连按 Ctrl+C）：不再等宽限期，立刻清理退出（exit 钩子也会再清一遍）
         immediate: () => {
+            running.authorizations.killAllNow();
             running.processes.killAllNow();
             killActiveExecs();
             process.exit(130);
@@ -237,7 +299,12 @@ export async function runBridge(argv) {
     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.');
-    pairing.issueCode('startup');
+    // 带 --pair（命令是从 M2 页面复制的）：主路径上用户不需要启动码，打印出来反而让人以为要去输码；
+    // 页面对不上承诺时会以未配对状态连上，那时照常出码并带上发起方 Origin
+    if (pairUntil !== null)
+        console.log(`  Waiting for the M2 page that gave you this command (until ${clock(pairUntil)})…`);
+    else
+        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('   ')}`);
     console.log('  Keep this window open while you use local agents in M2. Press Ctrl+C to stop.\n');