@m2canvas/connect 0.5.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,11 +9,13 @@
 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';
@@ -29,7 +31,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 +42,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 +52,14 @@ 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`;
 /** 解析 `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 };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '-h' || arg === '--help')
@@ -63,6 +70,8 @@ export function parseBridgeArgs(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)
@@ -167,6 +176,8 @@ 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'),
@@ -178,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 });
         },
     });
@@ -195,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();
     });
@@ -237,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;
@@ -250,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);

package/dist/bridge/precheck.js

@@ -4,15 +4,19 @@
  * 为什么要预检：m2 没配置、没授权、还没连上时，ACP 里没有任何信号，agent 只会说「没有这个工具」（PoC 报告 §4.1）。
  *
  * 边界：
- * - 只运行不修改配置的状态命令（status、mcp list；注意 `claude mcp list` 会启动用户配置的 stdio MCP 做健康检查）；bridge 不替用户登录、不替用户授权，只返回命令让用户在自己的终端执行。
+ * - 只运行不修改配置的状态命令（status、mcp list；注意 `claude mcp list` 会启动用户配置的 stdio MCP 做健康检查）。
+ *   预检本身不登录、不授权，只返回命令（终端兜底）；代跑写死清单里的授权命令是 agent/authorize 的事（authorize.ts），
+ *   预检结果里的 `authorize` 能力由 service.ts 加上。
  * - 不调用 ACP authenticate 探测登录：Qoder 未登录时 60 秒不响应（PoC 报告 §2.5）。
  * - `qodercli mcp list` 会以 `mcp-test-client` 身份连 M2，服务端判成 mcp、不进项目房间（总控 §6）：页面不要把这次连接当成 Qoder 会话。
  * - Cursor 的 m2 授权按目录保存，mcp list 与授权命令都必须在会话 cwd 下执行。
  * - Codex 的预检与授权都用适配器自带的 codex（调用方保证适配器已就绪）。
+ * - Claude 同样用适配器自带的 claude（D9）：会话用的就是它，本机那份只决定兜底命令怎么显示。找不到自带程序时报 unknown，
+ *   不退回本机的 claude（否则预检和会话看的是两个程序）。
  */
 import { join } from 'node:path';
 import { findM2Names } from './m2-config.js';
-import { CODEX_BIN_LINK, CODEX_SCRIPT } from './adapters.js';
+import { ADAPTERS, CODEX_BIN_LINK, CODEX_SCRIPT } from './adapters.js';
 import { combinedOutput } from './exec.js';
 import { parseClaudeAuthStatus, parseClaudeMcpList, parseCodexLoginStatus, parseCodexMcpListJson, parseCursorMcpList, parseCursorStatus, parseOpencodeMcpList, parseQoderMcpList, parseQoderStatus, tail, } from './precheck-parse.js';
 export const PRECHECK_TIMEOUT_MS = 45_000;
@@ -41,20 +45,27 @@ function plan(agent, deps) {
     const cmd = agent.command ?? agent.path ?? agent.id;
     const path = agent.path ?? cmd;
     switch (agent.id) {
-        case 'claude':
+        case 'claude': {
+            const binary = deps.adapters.claudeBinary();
+            // 兜底命令：本机装了 claude 就显示 `claude …`（用户熟悉），否则显示自带程序的绝对路径（D9）
+            const shown = agent.installed ? cmd : (binary ?? cmd);
             return {
-                exec: { command: path, prefix: [] },
-                login: { args: ['auth', 'status', '--json'], parse: (r) => parseClaudeAuthStatus(r.stdout, r.code), next: run(cmd, ['auth', 'login']) },
+                exec: { command: binary ?? '', prefix: [] },
+                missing: binary
+                    ? undefined
+                    : `Could not find the Claude Code program bundled with ${ADAPTERS.claude.package}@${ADAPTERS.claude.version}; try reinstalling the adapter.`,
+                login: { args: ['auth', 'status', '--json'], parse: (r) => parseClaudeAuthStatus(r.stdout, r.code), next: run(shown, ['auth', 'login']) },
                 m2: {
                     args: ['mcp', 'list'],
                     parse: (r) => parseClaudeMcpList(combinedOutput(r), r.code),
                     next: (state, entry) => state === 'needs_auth'
-                        ? run(cmd, ['mcp', 'login', entry])
+                        ? run(shown, ['mcp', 'login', entry])
                         : state === 'needs_enable'
                             ? { kind: 'manual', text: `Run claude in ${deps.cwd} and approve the project MCP server "${entry}".` }
                             : null,
                 },
             };
+        }
         case 'codex': {
             const dir = deps.adapters.installDir('codex');
             const display = join(dir, CODEX_BIN_LINK);
@@ -126,6 +137,8 @@ async function runStep(deps, p, args) {
 }
 export async function precheckM2(agent, deps) {
     const p = plan(agent, deps);
+    if (p.missing)
+        return toM2({ state: 'unknown', entry: null, raw: tail(p.missing) }, p.m2.next);
     const result = await runStep(deps, p, p.m2.args);
     const failure = failed(result);
     return toM2(failure ? { state: 'unknown', entry: null, raw: failure } : p.m2.parse(result), p.m2.next);
@@ -133,6 +146,9 @@ export async function precheckM2(agent, deps) {
 /** 调用方保证 agent 已安装；适配器类 agent 的适配器已就绪 */
 export async function precheckAgent(agent, deps, now = () => new Date()) {
     const p = plan(agent, deps);
+    if (p.missing) {
+        return { agent: agent.id, login: toLogin({ state: 'unknown', raw: tail(p.missing) }, p.login.next), m2: await precheckM2(agent, deps), checkedAt: now().toISOString() };
+    }
     const loginArgs = p.login.args;
     const [loginResult, m2] = await Promise.all([
         loginArgs ? runStep(deps, p, loginArgs) : Promise.resolve(null),

package/dist/bridge/protocol.js

@@ -1,7 +1,8 @@
 /**
  * 本机 ACP bridge ↔ M2 页面的 WebSocket 协议（change acp-local-bridge，给 change 3 acp-panel-local-agent 用）。
  *
- * 规范正文在 openspec 里该 change 的 design「页面协议」一节；本文件是它的类型落地，两者不一致时以 design 为准并修正这里。
+ * 规范正文在 openspec/archive/acp-local-bridge/design.md 的「页面协议」一节（之后改协议的 change 在自己的 design 里写出变化）；
+ * 本文件是它的类型落地，两者不一致时以 design 为准并修正这里。长期契约见 openspec/specs/connect/local-bridge.md。
  *
  * 维护约束：
  * - 本文件同时被 bridge（Node，ES2022 / NodeNext）和前端（浏览器，ES2020 / bundler / noUncheckedIndexedAccess）编译，
@@ -20,6 +21,13 @@ export const BRIDGE_DEFAULT_PORT = 47821;
 export const BRIDGE_WS_PATH = '/bridge';
 /** 与前端 src/lib/agent-types 的 AgentType 取值一致（是它的子集），顺序即 agents/list 的返回顺序 */
 export const BRIDGE_AGENT_IDS = ['claude', 'codex', 'cursor', 'opencode', 'qoder'];
+/**
+ * `agent/authorize` 的动作（change acp-terminal-free-auth，0.6.0 起）：login = agent 账号登录，m2 = m2 MCP 授权。
+ * 页面只能选「哪个 agent × 哪个动作」，可执行文件、参数、环境、工作目录全部由 bridge 的写死清单决定（契约 3）。
+ */
+export const BRIDGE_AUTH_ACTIONS = ['login', 'm2'];
+/** `auth/link` 的链接上限（bridge 只转交不超过它的 https 链接，页面收到时再按同一上限把一次关） */
+export const BRIDGE_MAX_AUTH_LINK_CHARS = 8 * 1024;
 /**
  * 页面可以发给 agent 的 ACP 方法（bridge 的 acp-guard.ts 按它放行，名单外回 `acp_rejected`、不转发）。
  * 页面对 agent 请求的响应（没有 method 键，例如审批结果）不受它限制。页面要用新方法：先在这里加上并发新版 bridge，
@@ -46,6 +54,8 @@ export const BRIDGE_METHODS = [
     'm2/configure',
     'process/start',
     'process/stop',
+    'agent/authorize',
+    'agent/authorize-cancel',
 ];
 export const BRIDGE_CLOSE_CODES = {
     normal: 1000,