@m2canvas/connect 0.5.0 → 0.7.0

package/dist/bridge/pairing.js

@@ -18,6 +18,9 @@
  *   不要为了「方便」放宽次数、延长有效期或加一个页面能触发的解锁：码是唯一挡住本机恶意页面的东西。
  *   也不要改成「在终端按回车解锁」：那需要读终端，而 bridge 放到后台（`… bridge &`）时读终端会被系统挂起（review r2 实测）。
  * - 比较用常量时间（timingSafeEqual），不要改回 ===。
+ * - 后台模式（`issueCodes: false`，`bridge --background`，change acp-bridge-one-time-install D17）不出码：没有终端，stdout 写的是日志文件，
+ *   出码就等于把码写盘。这时 `issueCode` / `ensureCode` 什么都不做，`pair` 一律 pairing_code_unavailable，配对只剩命令承诺与已有 token。
+ *   不要给后台模式另开出码通道（文件、系统对话框）：「把码写进文件」已被否决过（`connect/local-bridge` 契约 2 / 13）。
  */
 import { createHash, randomBytes, randomInt, randomUUID, timingSafeEqual } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -84,6 +87,7 @@ export class PairingManager {
     lastPrompt = new Map();
     store;
     now;
+    issueCodes;
     onCodeIssued;
     onLocked;
     onProblem;
@@ -91,13 +95,16 @@ export class PairingManager {
     constructor(options) {
         this.store = options.store;
         this.now = options.now ?? Date.now;
+        this.issueCodes = options.issueCodes ?? true;
         this.onCodeIssued = options.onCodeIssued;
         this.onLocked = options.onLocked ?? (() => undefined);
         this.onProblem = options.onProblem ?? (() => undefined);
         this.onCommitmentReused = options.onCommitmentReused ?? (() => undefined);
     }
-    /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式 */
+    /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式；后台模式不出码，返回 null */
     issueCode(reason, origin = null) {
+        if (!this.issueCodes)
+            return null;
         let code = '';
         for (let i = 0; i < CODE_LENGTH; i++)
             code += ALPHABET[randomInt(ALPHABET.length)];
@@ -118,10 +125,10 @@ export class PairingManager {
      * 未配对页面连上时调用。没有有效码就出新码；有有效码也把它连同发起方 Origin 再提示一次 ——
      * 最常见的首次流程是「启动 bridge 后马上打开页面」，终端里只有一个不带 Origin 的启动码，
      * 不再提示的话用户看不到是哪个页面在请求配对。同一 Origin、同一个码一分钟内只提示一次（页面重连不刷屏）。
-     * 锁定期间什么都不做。
+     * 锁定期间、后台模式下什么都不做。
      */
     ensureCode(origin) {
-        if (this.locked)
+        if (this.locked || !this.issueCodes)
             return;
         if (!this.hasValidCode() || !this.active) {
             this.issueCode('requested', origin);
@@ -141,6 +148,9 @@ export class PairingManager {
      * （review r1 实测 1.6 秒 20000 次），还会让陌生页面把用户的配对码一直刷掉。
      */
     pair(input, origin) {
+        // 后台模式没有码可比：在锁定检查之前返回，也不计入错码次数（页面并没有猜码，只是不知道这个 bridge 不出码）
+        if (!this.issueCodes)
+            return { ok: false, code: 'pairing_code_unavailable' };
         if (this.locked)
             return { ok: false, code: 'pairing_locked' };
         if (!this.active) {

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,

package/dist/bridge/release-manifest.js

@@ -0,0 +1,80 @@
+/**
+ * 更新清单 `https://m2ui.ai/connect/manifest.json` 的格式、解析与下载地址（change acp-bridge-one-time-install D13 / D14 / R7）。
+ *
+ * 清单由仓库的 `packages/connect/install/release.json` 生成，随 App 部署发布；部署 App 才是放量开关，发 npm 不等于推给所有用户。
+ * 清单**只提供版本号与哈希**：下载地址在这里由版本号拼出，固定指向官方源与 npmmirror。
+ * 不要在清单里加 URL 字段 —— 那会让清单（或篡改清单的人）把下载指到任意地方，信任根就不止 m2ui.ai 加哈希了。
+ *
+ * 跨版本兼容：已安装的旧版本 bridge 会读新部署的清单（`--check-update` 跑的是当前版本的代码）。
+ * - 同一 `schema` 内只加字段；本解析器忽略不认识的字段。
+ * - 要改语义就升 `schema`；旧版本认不出新 schema 时按「读清单失败」处理，用当前版本继续（不会误装）。
+ * - 版本号与哈希一律严格校验格式：它们会进入文件路径与下载地址。
+ */
+export const MANIFEST_URL = 'https://m2ui.ai/connect/manifest.json';
+export const MANIFEST_SCHEMA = 1;
+/** 只认纯 x.y.z（不接受预发布、构建元数据）：版本号会拼进目录名与下载地址 */
+const VERSION_RE = /^\d{1,4}\.\d{1,4}\.\d{1,6}$/;
+const SHA512_RE = /^[0-9a-f]{128}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+export function isReleaseVersion(value) {
+    return typeof value === 'string' && VERSION_RE.test(value);
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+}
+function pinned(value, hash) {
+    const entry = record(value);
+    if (!entry || !isReleaseVersion(entry.version) || typeof entry.sha512 !== 'string' || !hash.test(entry.sha512))
+        return null;
+    return { version: entry.version, sha512: entry.sha512 };
+}
+/** 解析清单正文；格式不对时返回原因（英文，写进 update.log） */
+export function parseReleaseManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return 'manifest is not valid JSON';
+    }
+    const root = record(parsed);
+    if (!root)
+        return 'manifest is not a JSON object';
+    if (root.schema !== MANIFEST_SCHEMA)
+        return `unsupported manifest schema ${JSON.stringify(root.schema)}`;
+    const connect = pinned(root.connect, SHA512_RE);
+    if (!connect)
+        return 'manifest has no valid connect version / sha512';
+    const ws = pinned(root.ws, SHA512_RE);
+    if (!ws)
+        return 'manifest has no valid ws version / sha512';
+    const node = record(root.node);
+    const sha256 = record(node?.sha256);
+    const arm64 = sha256?.arm64;
+    const x64 = sha256?.x64;
+    if (!node || !isReleaseVersion(node.version) || typeof arm64 !== 'string' || !SHA256_RE.test(arm64) || typeof x64 !== 'string' || !SHA256_RE.test(x64)) {
+        return 'manifest has no valid node version / sha256';
+    }
+    return { schema: MANIFEST_SCHEMA, connect, ws, node: { version: node.version, sha256: { arm64, x64 } } };
+}
+/**
+ * 下载源：官方优先，失败（含校验不符）再退 npmmirror（D14）。顺序有意义，不要打乱。
+ * 安装脚本的生成块用的是同一组基址（src/install/assets.ts），两边只此一处。
+ */
+export const NPM_REGISTRY_BASES = ['https://registry.npmjs.org', 'https://registry.npmmirror.com'];
+export const NODE_DIST_BASES = ['https://nodejs.org/dist', 'https://npmmirror.com/mirrors/node'];
+export function connectTarballUrls(version) {
+    return NPM_REGISTRY_BASES.map((base) => `${base}/@m2canvas/connect/-/connect-${version}.tgz`);
+}
+export function wsTarballUrls(version) {
+    return NPM_REGISTRY_BASES.map((base) => `${base}/ws/-/ws-${version}.tgz`);
+}
+/** 私有 Node 的目录名，也是官方包解开后的顶层目录名 */
+export function nodeDirName(version, arch) {
+    return `node-v${version}-darwin-${arch}`;
+}
+/** `.tar.xz`：只有 `.tar.gz` 的一半大小，macOS 自带的 bsdtar 能解（R9） */
+export function nodeTarballUrls(version, arch) {
+    const file = `${nodeDirName(version, arch)}.tar.xz`;
+    return NODE_DIST_BASES.map((base) => `${base}/v${version}/${file}`);
+}

package/dist/bridge/self-test.js

@@ -0,0 +1,30 @@
+/**
+ * `bridge --self-test`：自动更新时对新版本的冒烟测试（change acp-bridge-one-time-install D20 ④、N4）。
+ *
+ * 当前版本的 `--check-update` 用新版本自己的 Node 运行新版本的 cli.js。能走到这里，说明 cli.js → bridge/main.js
+ * 及其全部静态依赖（含 ws）都加载成功；这里再核对几种「能加载、但装得不全」的情况，任何一项不满足就退出 1，
+ * 更新流程就不会切换到这个版本。
+ *
+ * 不监听端口、不写文件、不联网：它在旧版本 bridge 还在运行时执行。
+ * 检测不到「起来了但功能坏了」（例如协议处理有 bug）：那种情况靠改清单回滚（`connect/local-bridge` 契约 16 delta）。
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ADAPTERS } from './adapters.js';
+import { bundledNpmCli } from './npm-command.js';
+/** 返回发现的问题（英文，写进 update.log）；空数组 = 通过 */
+export function selfTestProblems(input) {
+    const exists = input.exists ?? existsSync;
+    const problems = [];
+    if (!/^\d+\.\d+\.\d+/.test(input.version) || input.version === '0.0.0')
+        problems.push(`unreadable package version (${input.version})`);
+    for (const spec of Object.values(ADAPTERS)) {
+        const lock = join(input.packageRoot, 'adapters', spec.dir, 'package-lock.json');
+        if (!exists(lock))
+            problems.push(`missing ${lock}`);
+    }
+    const npm = bundledNpmCli(input.execPath);
+    if (!exists(npm))
+        problems.push(`missing ${npm}`);
+    return problems;
+}

package/dist/bridge/server.js

@@ -8,17 +8,23 @@
  * - 只监听 127.0.0.1；upgrade 校验（对端、Host、Origin、路径）在完成握手之前，失败直接写 HTTP 状态并销毁 socket。
  * - 握手后第一条消息必须是 hello；未配对的连接只能调用 pair，其余已知方法与 acp 帧一律 not_paired。
  *   连接只有两种方式成为已配对：hello 带有效 token，或 hello 的 pairSecret 与启动命令的承诺一致（pairing.ts 文件头）。
- * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
+ * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、授权动作（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
+ *   agent/authorize 与 agent/authorize-cancel 的 params 只能有规定的键，多一个就 bad_message（分派在 auth-call.ts，命令清单写死在 authorize.ts）。
  * - 页面发给 agent 的 ACP 行禁止含换行，并经 acp-guard.ts 检查：只能用白名单里的方法、会话目录固定为 bridge 的 cwd、不能让 agent 额外拉起 MCP 服务器。
  *
- * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责），不替用户登录。
+ * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责）。
+ * 登录 / m2 授权只代跑写死清单里的命令，授权页由用户在浏览器里亲自完成（authorize.ts）；授权链接只发给发起的连接，不进终端日志。
  */
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
 import { TOKEN_IDLE_DAYS } from './pairing.js';
 import { ProcessError, ProcessManager } from './processes.js';
-import { BRIDGE_AGENT_IDS, BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
+import { isBridgeAgentId } from './agents.js';
+import { handleAuthCall } from './auth-call.js';
+import { handlePairCall } from './pair-call.js';
+import { AuthorizationManager } from './authorize.js';
+import { BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
 import { checkPageAcpLine } from './acp-guard.js';
 import { checkUpgrade } from './security.js';
 import { BridgeFailure } from './service.js';
@@ -32,9 +38,6 @@ const MAX_CALL_ID = 64;
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function isAgentId(value) {
-    return typeof value === 'string' && BRIDGE_AGENT_IDS.includes(value);
-}
 function isMethod(value) {
     return typeof value === 'string' && BRIDGE_METHODS.includes(value);
 }
@@ -77,6 +80,23 @@ export function startBridgeServer(options) {
         },
         onStderr: options.verbose ? (_id, agent, text) => process.stderr.write(`[${agent}] ${text}`) : undefined,
     });
+    const authorizations = new AuthorizationManager({
+        timeoutMs: options.timing?.authTimeoutMs,
+        graceMs: options.timing?.authGraceMs,
+        pollMs: options.timing?.authPollMs,
+    });
+    const authContext = {
+        authorizations,
+        service: options.service,
+        log,
+        isConnected: (ownerId) => connections.has(ownerId),
+        // 授权链接只发给发起的连接（D4）
+        sendLink: (ownerId, data) => {
+            const owner = connections.get(ownerId);
+            if (owner)
+                send(owner, { type: 'event', event: 'auth/link', data });
+        },
+    };
     const unpairedCount = () => [...connections.values()].filter((conn) => !conn.paired).length;
     const markPaired = (conn) => {
         conn.paired = true;
@@ -86,20 +106,10 @@ export function startBridgeServer(options) {
     };
     async function handleCall(conn, id, method, params) {
         if (method === 'pair') {
-            const code = params.code;
-            if (typeof code !== 'string')
-                throw new BridgeFailure('bad_message', 'pair needs a string "code"');
-            const result = options.pairing.pair(code, conn.origin);
-            if (!result.ok) {
-                if (result.code === 'pairing_invalid')
-                    throw new BridgeFailure('pairing_invalid', 'wrong pairing code', { attemptsLeft: result.attemptsLeft });
-                if (result.code === 'pairing_locked')
-                    throw new BridgeFailure('pairing_locked', 'too many wrong pairing codes; new pages cannot pair until the bridge is restarted');
-                throw new BridgeFailure('pairing_code_rotated', 'pairing code expired or used up; a new one is shown in the terminal');
-            }
+            const token = handlePairCall(options.pairing, conn.origin, params);
             markPaired(conn);
             log(`Paired with ${conn.origin}.`);
-            return { token: result.token, cwd: options.cwd, idleExpiryDays: TOKEN_IDLE_DAYS };
+            return { token, cwd: options.cwd, idleExpiryDays: TOKEN_IDLE_DAYS };
         }
         if (!conn.paired)
             throw new BridgeFailure('not_paired', 'pair this page first');
@@ -111,8 +121,10 @@ export function startBridgeServer(options) {
         }
         if (method === 'agents/list')
             return { agents: await options.service.list() };
+        if (method === 'agent/authorize' || method === 'agent/authorize-cancel')
+            return handleAuthCall(authContext, conn.id, method, params);
         const agent = params.agent;
-        if (!isAgentId(agent))
+        if (!isBridgeAgentId(agent))
             throw new BridgeFailure('unknown_agent', `unknown agent ${String(agent)}`);
         switch (method) {
             case 'agent/prepare':
@@ -296,12 +308,12 @@ export function startBridgeServer(options) {
                     clearTimeout(conn.timer);
                 connections.delete(conn.id);
                 processes.stopOwner(conn.id);
+                authorizations.cancelOwner(conn.id);
             });
             // ws 的错误（非法帧、超过 maxPayload 等）之后必然紧跟 'close'，清理在 close 里做；这里只防止未处理的 error 事件让进程崩溃
             ws.on('error', () => undefined);
         });
     });
-    // 心跳：浏览器自动回 pong；连续一个周期没回（休眠、崩溃、断网）就断开并清理它的进程
     // 被拒连接的终端日志限频：任何网站都能反复连 127.0.0.1，逐条打印会把配对码和「X wants to pair」顶出视野（review r3 S5）。
     // 同一原因在一个窗口内只打第一条，窗口结束时汇总被合并的次数。
     const rejectWindowMs = options.timing?.rejectLogWindowMs ?? REJECT_LOG_WINDOW_MS;
@@ -332,25 +344,33 @@ export function startBridgeServer(options) {
             },
         };
     })();
-    const heartbeat = setInterval(() => {
-        for (const conn of connections.values()) {
-            if (!conn.alive) {
-                conn.ws.terminate();
-                continue;
-            }
-            conn.alive = false;
-            conn.ws.ping();
-        }
-    }, timing.pingIntervalMs);
     return new Promise((resolve, reject) => {
-        http.once('error', reject);
+        // 监听失败（端口被占）时停掉已经开始的计时器：--replace 会在同一进程里再监听一次（review r4 N4）。心跳在监听成功后才开始
+        const fail = (error) => {
+            rejectLog.stop();
+            wss.close();
+            reject(error);
+        };
+        http.once('error', fail);
         http.listen(options.port, '127.0.0.1', () => {
-            http.off('error', reject);
+            http.off('error', fail);
+            // 心跳：浏览器自动回 pong；连续一个周期没回（休眠、崩溃、断网）就断开并清理它的进程
+            const heartbeat = setInterval(() => {
+                for (const conn of connections.values()) {
+                    if (!conn.alive) {
+                        conn.ws.terminate();
+                        continue;
+                    }
+                    conn.alive = false;
+                    conn.ws.ping();
+                }
+            }, timing.pingIntervalMs);
             const address = http.address();
             resolve({
                 port: address.port,
                 address: address.address,
                 processes,
+                authorizations,
                 broadcast(event, data) {
                     for (const conn of connections.values())
                         if (conn.paired)
@@ -359,6 +379,8 @@ export function startBridgeServer(options) {
                 close() {
                     clearInterval(heartbeat);
                     rejectLog.stop();
+                    // 先于关闭连接：标记取消，被杀掉的授权命令不会被当成「失败」再去重跑预检
+                    authorizations.killAllNow();
                     for (const conn of connections.values())
                         conn.ws.close(BRIDGE_CLOSE_CODES.goingAway, 'bridge is shutting down');
                     processes.stopAll();

package/dist/bridge/service.js

@@ -1,19 +1,29 @@
 /**
- * 页面方法背后的 agent 操作：列表、准备适配器、预检、写 m2 配置、生成启动规格。server.ts 只做协议，这里只做业务。
+ * 页面方法背后的 agent 操作：列表、准备适配器、预检、写 m2 配置、生成启动规格与授权命令计划。server.ts 只做协议，这里只做业务。
  *
  * 前置条件统一在这里检查，错误以 BridgeFailure（带协议错误码）抛出：
- * - 未安装 → agent_not_installed（安装命令与文档链接由前端提供，bridge 不代装）；
+ * - 拉不起来 → agent_not_installed（安装命令与文档链接由前端提供，bridge 不代装）。claude / codex 用适配器自带的程序，
+ *   本机没装命令行也能拉起（D11：`available` 恒为 true；`installed` 仍只表示本机检测到了命令行）；
  * - 适配器类 agent 未就绪 → adapter_not_ready（页面要先调 agent/prepare）。
  *
  * m2/configure 以子进程运行本包自己的 cli.js `--client <id> --yes`：stdin 不是 TTY，cli.js 走现有的非交互分支
  * （只写配置、不跑登录、退出码 0 = 全部写入或已存在）。这样一字不改 clients.ts，也不让它的 spawnSync 卡住转发。
- * 改 cli.js 非交互分支的行为时要同步检查这里。
+ * 改 cli.js 非交互分支的行为时要同步检查这里。clients.ts 只认 PATH 上跑得起来的 claude / codex，所以对这两家把自带程序所在目录
+ * 和 bridge 自己的 node 排到 PATH 最前（D10），本机没装命令行也能写配置。
+ *
+ * 授权（change acp-terminal-free-auth）：authorizePlan 按写死清单生成命令（authorize.ts），m2 的配置项名只取 bridge 自己的 m2 预检：
+ * 优先用最近一次预检 / 写配置时得到的名字（D19，页面先预检才会显示按钮，省掉一次重跑 —— Claude 的 `mcp list` 实测约 5 秒），没有记录时重跑；
+ * 预检 / 写配置的结果按同一判据带上 `authorize` 能力，页面只在能力存在时才调用 agent/authorize。
  */
+import { dirname, join } from 'node:path';
 import { ADAPTERS, isAdapterAgent } from './adapters.js';
+import { BridgeFailure } from './errors.js';
 import { LAUNCH_KIND, NATIVE_ACP_ARGS } from './agents.js';
+import { authCapability, buildAuthPlan, isSafeAuthEntry } from './authorize.js';
+import { prependPath } from './env.js';
 import { combinedOutput } from './exec.js';
 import { precheckAgent, precheckM2 } from './precheck.js';
-import { BRIDGE_AGENT_IDS } from './protocol.js';
+import { BRIDGE_AGENT_IDS, } from './protocol.js';
 export const CONFIGURE_TIMEOUT_MS = 120_000;
 /**
  * Claude 适配器（claude-agent-acp@0.84.0）声明 `node >=22`，实测在 Node 20 上可用（ACP PoC 与本 change 的端到端都是 Node 20）；
@@ -21,15 +31,7 @@ export const CONFIGURE_TIMEOUT_MS = 120_000;
  */
 export const MIN_NODE_MAJOR_FOR_CLAUDE = 20;
 const CONFIGURE_OUTPUT_LIMIT = 4096;
-export class BridgeFailure extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.code = code;
-        this.data = data;
-    }
-}
+export { BridgeFailure };
 /** bridge 的 agent id → connect `--client` 的取值 */
 const CLIENT_ID = {
     claude: 'claude-code',
@@ -40,25 +42,74 @@ const CLIENT_ID = {
 };
 export function createAgentService(deps) {
     const precheckDeps = { ...deps, env: deps.probeEnv };
-    async function installed(agent) {
+    /**
+     * 最近一次 m2 预检得到的配置项名（D19）。只由 bridge 自己的预检写入，页面仍不能指定（契约 3）；
+     * 最近一次没有名字（未配置、读不出）就清掉，授权时重跑。名字过期（预检到点击之间用户改了配置）时，授权命令失败并带输出（再点一次即可：命令结束后的预检已经刷新了记录），
+     * 或者针对同名的新配置项（用户在授权页上看得到授权对象）。Claude / Codex / Cursor 实测名字不存在时退出码 1；OpenCode 不是，所以它不用记录（见下）。
+     */
+    const m2Entries = new Map();
+    /**
+     * 授权前总是重新检查、不用记录的 agent（D21）。OpenCode 的 m2 授权先 `mcp logout <entry>`：名字过期时可能删掉同名的别的服务器的凭证；
+     * 而且名字不存在时 `mcp logout` / `mcp auth` 都以退出码 0 结束（实测 1.18.5），bridge 会判成成功。多 2–4 秒，换来名字一定是当下的。
+     */
+    const alwaysRecheck = new Set(['opencode']);
+    function remember(agent, m2) {
+        if (m2.state !== 'not_configured' && m2.entry)
+            m2Entries.set(agent, m2.entry);
+        else
+            m2Entries.delete(agent);
+        return m2;
+    }
+    /** 能拉起（D11）：claude / codex 用适配器自带的程序，不要求本机命令行；其余三家要本机装了 */
+    async function available(agent) {
         const detected = await deps.detect(agent);
-        if (!detected.installed)
+        if (!isAdapterAgent(agent) && !detected.installed)
             throw new BridgeFailure('agent_not_installed', `${agent} is not installed on this machine`);
         return detected;
     }
     async function ready(agent) {
-        const detected = await installed(agent);
+        const detected = await available(agent);
         if (isAdapterAgent(agent) && !deps.adapters.isReady(agent)) {
             throw new BridgeFailure('adapter_not_ready', `call agent/prepare for ${agent} first`, { adapter: deps.adapters.info(agent) });
         }
         return detected;
     }
+    const capability = (agent, action) => authCapability(agent, action, {
+        platform: deps.platform,
+        expectAvailable: deps.expectAvailable(),
+        claudeBinary: agent === 'claude' ? deps.adapters.claudeBinary() : null,
+    });
+    /** 预检 / 写配置结果带上「能不能代跑」：与 authorizePlan 用同一判据（含 m2 配置项名的校验），页面看到按钮就一定能调用 */
+    function withCapability(check, agent, action) {
+        const authorize = capability(agent, action);
+        const entry = 'entry' in check ? check.entry : null;
+        if (!authorize || (entry !== null && !isSafeAuthEntry(entry)))
+            return check;
+        return { ...check, authorize };
+    }
+    const withCapabilities = (result) => ({
+        ...result,
+        login: withCapability(result.login, result.agent, 'login'),
+        m2: withCapability(result.m2, result.agent, 'm2'),
+    });
+    /** D10：clients.ts 只认 PATH 上能跑起来的 claude / codex */
+    function configureEnv(agent) {
+        const node = dirname(deps.nodePath);
+        if (agent === 'claude') {
+            const claude = deps.adapters.claudeBinary();
+            return prependPath(deps.probeEnv, claude ? [dirname(claude), node] : [node], deps.platform);
+        }
+        if (agent === 'codex')
+            return prependPath(deps.probeEnv, [join(deps.adapters.installDir('codex'), 'node_modules', '.bin'), node], deps.platform);
+        return deps.probeEnv;
+    }
     return {
         async list() {
             const detected = await Promise.all(BRIDGE_AGENT_IDS.map((id) => deps.detect(id)));
             return detected.map((agent) => ({
                 id: agent.id,
                 installed: agent.installed,
+                available: isAdapterAgent(agent.id) || agent.installed,
                 path: agent.path,
                 version: agent.version,
                 launch: LAUNCH_KIND[agent.id],
@@ -66,7 +117,7 @@ export function createAgentService(deps) {
             }));
         },
         async prepare(agent) {
-            await installed(agent);
+            await available(agent);
             if (!isAdapterAgent(agent))
                 return null;
             const major = Number(deps.nodeVersion.split('.')[0]);
@@ -80,12 +131,14 @@ export function createAgentService(deps) {
             return info;
         },
         async precheck(agent) {
-            return precheckAgent(await ready(agent), precheckDeps);
+            const result = await precheckAgent(await ready(agent), precheckDeps);
+            remember(agent, result.m2);
+            return withCapabilities(result);
         },
         async configure(agent) {
             const detected = await ready(agent);
             const result = await deps.exec(deps.nodePath, [deps.cliPath, '--client', CLIENT_ID[agent], '--yes'], {
-                env: deps.probeEnv,
+                env: configureEnv(agent),
                 cwd: deps.cwd,
                 timeoutMs: CONFIGURE_TIMEOUT_MS,
             });
@@ -93,7 +146,7 @@ export function createAgentService(deps) {
             return {
                 ok: result.code === 0,
                 output: output.length > CONFIGURE_OUTPUT_LIMIT ? output.slice(-CONFIGURE_OUTPUT_LIMIT) : output,
-                m2: await precheckM2(detected, precheckDeps),
+                m2: withCapability(remember(agent, await precheckM2(detected, precheckDeps)), agent, 'm2'),
             };
         },
         async launch(agent) {
@@ -105,5 +158,35 @@ export function createAgentService(deps) {
                 throw new BridgeFailure('internal', `no executable path for ${agent}`);
             return { command: detected.path, args: NATIVE_ACP_ARGS[agent] };
         },
+        async authorizePlan(agent, action) {
+            const verb = action === 'login' ? 'sign-in' : 'M2 authorization';
+            if (deps.platform !== 'darwin')
+                throw new BridgeFailure('auth_unavailable', `the bridge only runs ${verb} on macOS; use the terminal command instead`);
+            const detected = await ready(agent);
+            if (!capability(agent, action))
+                throw new BridgeFailure('auth_unavailable', `the bridge cannot run ${verb} for ${agent}; use the terminal command instead`);
+            let entry = null;
+            if (action === 'm2') {
+                // 配置项名不一定叫 m2，也不能由页面指定：用 bridge 最近一次预检的结果，没有就重跑（D19）；OpenCode 总是重跑（D21）
+                const rechecked = alwaysRecheck.has(agent) || !m2Entries.has(agent) ? remember(agent, await precheckM2(detected, precheckDeps)) : null;
+                entry = m2Entries.get(agent) ?? null;
+                if (!entry) {
+                    // 读不出（unknown）不等于没配置：不能叫已经配置了 M2 的用户「先添加」（review r5 R5-N5）
+                    const why = rechecked?.state === 'unknown' ? `couldn't read ${agent}'s MCP config; check again, or use the terminal command` : `add M2 to ${agent}'s MCP config first (m2/configure)`;
+                    throw new BridgeFailure('auth_unavailable', why);
+                }
+            }
+            return buildAuthPlan({
+                agent,
+                action,
+                detected,
+                entry,
+                cwd: deps.cwd,
+                env: deps.probeEnv,
+                nodePath: deps.nodePath,
+                claudeBinary: agent === 'claude' ? deps.adapters.claudeBinary() : null,
+                codexDir: deps.adapters.installDir('codex'),
+            });
+        },
     };
 }