@m2canvas/connect 0.5.0 → 0.7.0

package/dist/bridge/instance.js

@@ -0,0 +1,245 @@
+/**
+ * 端口被占时识别并接管正在运行的 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、承诺）。
+ * 这也是跨版本接口：用户机器上的启动器 `~/.m2canvas/bin/m2-bridge` 只随重装更新，它按「JSON 对象里的 "pid"」核对
+ * 拉起的是不是这个进程（change acp-bridge-one-time-install review r1 R1-S2）。改格式前先确认已装出去的启动器仍认得，
+ * `install-launcher-real.test.ts` 用真实 bridge 锁住了这一点。
+ */
+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) {
+        ctx.alreadyRunning?.(running);
+        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

@@ -5,23 +5,51 @@
  *
  * 本文件负责组装与终端交互：参数、启动横幅、配对码打印、信号处理、退出兜底清理。协议在 server.ts，安全判定在 security.ts / pairing.ts。
  * 终端输出用英文，与 connect 现有输出一致。
+ *
+ * 后台模式（`--background`，只由启动器 `~/.m2canvas/bin/m2-bridge` 使用，change acp-bridge-one-time-install）：输出写进日志文件，
+ * 所以不出配对码（契约 2）、不提示「保持窗口打开」；页面经 `welcome.bridge.background` 得知，改走「重新连接」。
+ * 端口上已有认定的 M2 bridge 时以 EXIT_ALREADY_RUNNING 退出，启动器把它当成功。
  */
 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, isPairCommitment } from './pairing.js';
 import { BRIDGE_AGENT_IDS, BRIDGE_DEFAULT_PORT, BRIDGE_WS_PATH } from './protocol.js';
+import { resolveNpmCommand } from './npm-command.js';
 import { DEV_ORIGINS, PROD_ORIGINS, allowedOrigins } from './security.js';
+import { selfTestProblems } from './self-test.js';
+import { runCheckUpdate } from './update-io.js';
 import { startBridgeServer } from './server.js';
 import { createAgentService } from './service.js';
 import { KILL_GRACE_MS } from './processes.js';
 const NPM_CI_TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * 后台模式下，端口上已有认定的 M2 bridge、又没带 `--replace` 时的退出码（change acp-bridge-one-time-install R1）。
+ * 启动器把它当「已在运行」（成功）；认不出的占用者、停不掉等失败仍是 1，不能并进来。终端模式不用它（照旧 1）。
+ */
+export const EXIT_ALREADY_RUNNING = 3;
+/**
+ * 后台模式下，端口被占、又认不出占用者是 M2 bridge（或 `--replace` 停不掉旧的、停掉后端口仍被占）时的退出码（review r1 R1-S1）。
+ * 这些都是环境问题，不是这个版本坏了：启动器据此**不回退、不拉黑**刚更新的版本，只把原因写进结果行。终端模式仍是 1。
+ */
+export const EXIT_PORT_UNAVAILABLE = 4;
+/**
+ * 后台模式加 `--dev`（本机开发页联调用，design R6）时的寿命（review r1 R1-S6，用户 2026-10-05 拍板）。
+ * 开发域名的 Origin 与 localStorage 被本机所有 Vite 项目共用，契约 1 因此只在 `--dev` 时放行、且否决了「常开」；
+ * 后台 bridge 没有终端、一直运行到注销，不限时就等于常开。到时走正常收尾退出，需要时再用启动器拉起。
+ */
+export const DEV_BACKGROUND_LIFETIME_MS = 2 * 60 * 60 * 1000;
+export function backgroundLifetimeMs(args) {
+    return args.background && args.dev ? DEV_BACKGROUND_LIFETIME_MS : null;
+}
 const LABELS = {
     claude: 'Claude Code',
     codex: 'Codex',
@@ -29,7 +57,7 @@ const LABELS = {
     opencode: 'OpenCode',
     qoder: 'Qoder',
 };
-export const BRIDGE_HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev] [--pair <value>]
+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
@@ -40,6 +68,8 @@ 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)
@@ -48,11 +78,23 @@ Agents run in the directory you start the bridge from (or --cwd), with your own
                   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`;
+  -h, --help      show this help
+
+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, ${EXIT_PORT_UNAVAILABLE} if
+                  something else holds the port; with --dev it stops by itself after 2 hours
+  --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`;
 /** 解析 `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 };
+    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 };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '-h' || arg === '--help')
@@ -63,6 +105,16 @@ export function parseBridgeArgs(argv) {
             args.unpair = true;
         else if (arg === '--dev')
             args.dev = true;
+        else if (arg === '--replace')
+            args.replace = true;
+        else if (arg === '--background')
+            args.background = true;
+        else if (arg === '--self-test')
+            args.selfTest = true;
+        else if (arg === '--check-update')
+            args.checkUpdate = true;
+        else if (arg === '--stop')
+            args.stop = true;
         else if (arg === '--pair') {
             const value = argv[++i];
             if (value === undefined)
@@ -132,6 +184,22 @@ function describeAdapter(agent, info) {
         return `Installing the ${name} failed: ${info.error ?? 'unknown error'}`;
     return null;
 }
+/**
+ * `--stop`：卸载脚本先停掉正在运行的 bridge（change acp-bridge-one-time-install D23 ①）。
+ * 认定与停止都复用契约 13 的实现（instance.ts）：只停认定的 M2 bridge，只发 SIGTERM（走它自己的清理），认不出就什么都不停。
+ * 不在卸载脚本里用 sh 再写一遍认定（要用 `ps` 推算启动时刻，两份实现会漂；理由同 design R1）。
+ */
+async function stopRecognizedBridge(port) {
+    const probeEnv = buildProbeEnv();
+    const running = await identifyRunningBridge(instanceFilePath(join(home, '.m2canvas'), port), port, createPsProbe(execCommand, probeEnv), process.platform);
+    if (!running) {
+        console.log(`No M2 bridge that this version can recognize is running on port ${port}; nothing was stopped.`);
+        return 0;
+    }
+    const stopped = await stopRunningBridge(running.pid, createStopDeps(execCommand, probeEnv));
+    console.log(stopped ? `Stopped the M2 bridge on port ${port} (pid ${running.pid}).` : `The M2 bridge on port ${port} (pid ${running.pid}) didn't stop.`);
+    return stopped ? 0 : 1;
+}
 export async function runBridge(argv) {
     const parsed = parseBridgeArgs(argv);
     if (typeof parsed === 'string') {
@@ -142,6 +210,20 @@ export async function runBridge(argv) {
         console.log(BRIDGE_HELP);
         return 0;
     }
+    if (parsed.selfTest) {
+        const version = packageVersion();
+        const problems = selfTestProblems({ packageRoot: PACKAGE_ROOT, execPath: process.execPath, version });
+        if (problems.length > 0) {
+            console.error(`M2 bridge self-test failed: ${problems.join('; ')}`);
+            return 1;
+        }
+        console.log(`M2 bridge self-test ok ${version}`);
+        return 0;
+    }
+    if (parsed.checkUpdate)
+        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) {
@@ -155,11 +237,14 @@ export async function runBridge(argv) {
     }
     const log = (message) => console.log(`[${new Date().toLocaleTimeString()}] ${message}`);
     const probeEnv = buildProbeEnv();
-    const npm = which('npm') ?? (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    // 后台模式用私有 Node 自带的 npm（目标用户 PATH 上可能根本没有 npm，R3）；终端模式照旧用 PATH 上的
+    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),
@@ -167,20 +252,27 @@ export async function runBridge(argv) {
     });
     // 承诺必须在开始监听之前挂上：等待中的页面每 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'),
-        runNpmCi: (dir) => execCommand(npm, ['ci', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'], {
-            cwd: dir,
-            env: buildNpmEnv(),
-            timeoutMs: NPM_CI_TIMEOUT_MS,
-            maxOutput: 64 * 1024,
-            shell: process.platform === 'win32',
-        }),
+        runNpmCi: (dir) => 'error' in npm
+            ? Promise.reject(new Error(npm.error))
+            : execCommand(npm.command, [...npm.prefix, 'ci', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'], {
+                cwd: dir,
+                env: buildNpmEnv(),
+                timeoutMs: NPM_CI_TIMEOUT_MS,
+                maxOutput: 64 * 1024,
+                shell: npm.shell,
+            }),
         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 });
         },
     });
@@ -195,34 +287,67 @@ 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);
+    let alreadyRunning = false;
+    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,
+            ...(parsed.background ? { background: true } : {}),
+        },
+        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,
+        alreadyRunning: () => {
+            alreadyRunning = true;
+        },
+    });
+    // listenWithReplace 返回 null 的情况都与端口有关（已在运行、被别的程序占着、停不掉旧的）；后台模式把「已在运行」与其余分开
+    if (!server)
+        return parsed.background ? (alreadyRunning ? EXIT_ALREADY_RUNNING : EXIT_PORT_UNAVAILABLE) : 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();
     });
@@ -237,7 +362,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;
@@ -250,11 +377,19 @@ export async function runBridge(argv) {
         graceful: () => void stop(),
         // 收尾期间又来一个信号（连按 Ctrl+C）：不再等宽限期，立刻清理退出（exit 钩子也会再清一遍）
         immediate: () => {
+            running.authorizations.killAllNow();
             running.processes.killAllNow();
             killActiveExecs();
             process.exit(130);
         },
     });
+    const lifetime = backgroundLifetimeMs(parsed);
+    if (lifetime !== null) {
+        setTimeout(() => {
+            log('Dev mode in the background reached its 2-hour limit; stopping. Start it again with ~/.m2canvas/bin/m2-bridge if you still need it.');
+            void stop();
+        }, lifetime);
+    }
     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}`);
@@ -263,12 +398,17 @@ export async function runBridge(argv) {
         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.');
+    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
+    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('   ')}`);
-    console.log('  Keep this window open while you use local agents in M2. Press Ctrl+C to stop.\n');
+    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/npm-command.js

@@ -0,0 +1,25 @@
+/**
+ * 适配器安装（`npm ci`）用哪个 npm（change acp-bridge-one-time-install R3）。
+ *
+ * - 终端模式（`npx @m2canvas/connect bridge`）：沿用 PATH 上的 npm —— 用户能运行 npx，就一定有 npm；不改既有行为。
+ * - 后台模式（`bridge --background`，由启动器用 `~/.m2canvas/runtime` 里的私有 Node 拉起）：目标用户往往根本没装 Node，
+ *   PATH 上没有 npm。必须用运行 bridge 的那份 Node（`process.execPath`）去跑同一 Node 包里的 `lib/node_modules/npm/bin/npm-cli.js`。
+ *   不能直接运行 `bin/npm`：它的 shebang 是 `#!/usr/bin/env node`，又会去 PATH 找 node。
+ *   找不到 npm-cli.js 就报错，**不退回 PATH 上的 npm**：那会让组件装进一份与 bridge 不同的 Node 环境里，失败时也更难查。
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** 官方 Node 二进制包的布局：`<prefix>/bin/node` 与 `<prefix>/lib/node_modules/npm/bin/npm-cli.js` */
+export function bundledNpmCli(execPath) {
+    return join(dirname(execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js');
+}
+export function resolveNpmCommand(input) {
+    if (input.background) {
+        const cli = bundledNpmCli(input.execPath);
+        if (!(input.exists ?? existsSync)(cli))
+            return { error: `npm was not found next to this bridge's Node.js (${cli}); reinstall the M2 local connection` };
+        return { command: input.execPath, prefix: [cli], shell: false };
+    }
+    const windows = input.platform === 'win32';
+    return { command: input.which('npm') ?? (windows ? 'npm.cmd' : 'npm'), prefix: [], shell: windows };
+}

package/dist/bridge/pair-call.js

@@ -0,0 +1,31 @@
+/**
+ * bridge 方法 `pair`（页面输码换 token）：校验参数、调用 PairingManager.pair、把失败映射成页面看得懂的错误码。
+ * 只负责「这次输码对不对」；配对成功后把连接标为已配对、记日志、回 cwd 由 server.ts 负责（连接状态只在那里改）。
+ *
+ * 错误码的语义是页面协议的一部分（`protocol.ts` 的 BridgeErrorCode，`connect/local-bridge` 契约 9）：
+ * - pairing_invalid：错码，带剩余次数；
+ * - pairing_code_rotated：码过期或错太多次被换掉，新码已打印在终端；
+ * - pairing_locked：累计错码太多，只有重启 bridge 才解除；
+ * - pairing_code_unavailable：后台模式（`bridge --background`）根本不出码，页面要改走「重新连接」（change acp-bridge-one-time-install D17）。
+ * 不要把后两种并进 pairing_code_rotated：页面据此决定是让用户看终端，还是让 agent 重新拉起 bridge。
+ */
+import { BridgeFailure } from './errors.js';
+/** 成功时返回新签发的 token；失败抛 BridgeFailure */
+export function handlePairCall(pairing, origin, params) {
+    const code = params.code;
+    if (typeof code !== 'string')
+        throw new BridgeFailure('bad_message', 'pair needs a string "code"');
+    const result = pairing.pair(code, origin);
+    if (result.ok)
+        return result.token;
+    switch (result.code) {
+        case 'pairing_invalid':
+            throw new BridgeFailure('pairing_invalid', 'wrong pairing code', { attemptsLeft: result.attemptsLeft });
+        case 'pairing_locked':
+            throw new BridgeFailure('pairing_locked', 'too many wrong pairing codes; new pages cannot pair until the bridge is restarted');
+        case 'pairing_code_unavailable':
+            throw new BridgeFailure('pairing_code_unavailable', 'this bridge was started in the background and shows no pairing code; reconnect from M2 to pair');
+        case 'pairing_code_rotated':
+            throw new BridgeFailure('pairing_code_rotated', 'pairing code expired or used up; a new one is shown in the terminal');
+    }
+}