@m2canvas/connect 0.3.1 → 0.4.0

package/dist/bridge/agents.js

@@ -0,0 +1,73 @@
+/**
+ * bridge 自己的 agent 检测与启动规格（ACP 可行性评估 §4 的表）。
+ *
+ * 与 connect 现有的 detectClients（clients.ts）是两套判据，**不要合并**：
+ * - connect 的检测用于写 MCP 配置，只装了 Cursor IDE（有 ~/.cursor）也算 —— IDE 也读那份配置；
+ * - 这里判断「能不能用 ACP 拉起」，Cursor 只认 CLI（`cursor-agent`，或真实路径指向 cursor-agent 的 `agent`）。
+ *   `agent` 是很泛的命令名，别的工具也可能叫这个，所以必须看真实路径。
+ * - Qoder 先找 `qodercli`（PATH，再 ~/.local/bin），最后兼容 `qoder`（官方文档的写法，PoC 本机没有）。
+ *
+ * 「能运行」= `--version` 在超时内退出码 0（与 connect 的 firstRunnable 同一判据：PATH 上的 shim 可能是坏的）。
+ */
+import { realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { isExecutable, which } from '../system.js';
+export const VERSION_TIMEOUT_MS = 15_000;
+/** claude / codex 经适配器拉起（不用检测到的本机二进制）；其余三家用自带的 ACP 模式 */
+export const LAUNCH_KIND = {
+    claude: 'adapter',
+    codex: 'adapter',
+    cursor: 'native',
+    opencode: 'native',
+    qoder: 'native',
+};
+/** 原生 ACP 模式的启动参数（实测：PoC 报告 §2.3–2.5） */
+export const NATIVE_ACP_ARGS = {
+    cursor: ['acp'],
+    opencode: ['acp'],
+    qoder: ['--acp'],
+};
+function realpathOrSelf(path, realpath) {
+    try {
+        return realpath(path);
+    }
+    catch {
+        return path;
+    }
+}
+function candidates(id, deps) {
+    const onPath = (command) => ({ path: deps.which(command), command });
+    const fixed = (path) => ({ path, command: path });
+    switch (id) {
+        case 'claude':
+            return [onPath('claude')];
+        case 'codex':
+            // Codex 桌面端（ChatGPT.app）自带 CLI，也算已安装（拉起时仍用适配器自带的 codex）
+            return [onPath('codex'), fixed('/Applications/ChatGPT.app/Contents/Resources/codex')];
+        case 'cursor':
+            return [
+                onPath('cursor-agent'),
+                { ...onPath('agent'), accept: (path) => realpathOrSelf(path, deps.realpath).includes('cursor-agent') },
+            ];
+        case 'opencode':
+            return [onPath('opencode'), fixed('/Applications/OpenCode.app/Contents/Resources/opencode-cli')];
+        case 'qoder':
+            return [onPath('qodercli'), fixed(join(deps.home, '.local', 'bin', 'qodercli')), onPath('qoder')];
+    }
+}
+export async function detectAgent(id, deps) {
+    const resolved = { which: deps.which ?? which, realpath: deps.realpath ?? realpathSync, home: deps.home };
+    for (const candidate of candidates(id, resolved)) {
+        const path = candidate.path;
+        if (!path || !isExecutable(path))
+            continue;
+        if (candidate.accept && !candidate.accept(path))
+            continue;
+        const result = await deps.exec(path, ['--version'], { env: deps.env, timeoutMs: VERSION_TIMEOUT_MS, maxOutput: 4096 });
+        if (result.code !== 0)
+            continue;
+        const firstLine = `${result.stdout}\n${result.stderr}`.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0);
+        return { id, installed: true, path, command: candidate.command, version: firstLine ?? null };
+    }
+    return { id, installed: false, path: null, command: null, version: null };
+}

package/dist/bridge/env.js

@@ -0,0 +1,107 @@
+/**
+ * bridge 拉起的所有子进程（agent、预检 CLI、m2/configure、适配器安装）只继承这里放行的环境变量。
+ *
+ * 为什么是白名单而不是黑名单：用户可能在 Claude Code / Codex 之类宿主的终端里运行 bridge，宿主注入的变量会改变子 agent
+ * 的鉴权与路由（ACP PoC 第一轮 Claude 结果因此作废）。实测宿主注入的除了 ANTHROPIC_BASE_URL、几十个 CLAUDE_CODE_*，
+ * 还有 SUPABASE_ACCESS_TOKEN、USE_STAGING_OAUTH 这类密钥和开关，黑名单列不全。
+ *
+ * 维护约束：
+ * - 预检和 agent 用同一份环境，两者看到的配置才一致。新增放行项前先确认它不是宿主注入的鉴权 / 路由变量。
+ * - CODEX_HOME / CLAUDE_CONFIG_DIR / XDG_* 是「配置在哪」：connect 写 MCP 配置时读它们（clients.ts），agent 必须读同一处。
+ * - 依赖环境变量登录的用户（例如 QODER_PERSONAL_ACCESS_TOKEN）会被挡掉，这是有意的取舍（FU-2026-10-02-121）。
+ */
+/** 精确名（非 Windows 区分大小写） */
+const ALLOWED_NAMES = [
+    'HOME',
+    'PATH',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'TMPDIR',
+    'TEMP',
+    'TMP',
+    'TERM',
+    'LANG',
+    'LANGUAGE',
+    'TZ',
+    '__CF_USER_TEXT_ENCODING',
+    'SSH_AUTH_SOCK',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'ALL_PROXY',
+    'NO_PROXY',
+    'http_proxy',
+    'https_proxy',
+    'all_proxy',
+    'no_proxy',
+    'NODE_EXTRA_CA_CERTS',
+    'NODE_USE_SYSTEM_CA',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'CODEX_HOME',
+    'CLAUDE_CONFIG_DIR',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'XDG_CACHE_HOME',
+    'XDG_STATE_HOME',
+    'XDG_RUNTIME_DIR',
+];
+/** Windows 系统变量（Windows 的环境变量名不区分大小写，按大写比较） */
+const WINDOWS_NAMES = [
+    'SYSTEMROOT',
+    'WINDIR',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'USERPROFILE',
+    'HOMEDRIVE',
+    'HOMEPATH',
+    'PATHEXT',
+    'COMSPEC',
+    'PROGRAMDATA',
+    'PROGRAMFILES',
+    'PROGRAMFILES(X86)',
+];
+const ALLOWED_PREFIXES = ['LC_'];
+/**
+ * 适配器安装（npm ci）额外需要的 npm 配置：用户用 `npx --registry=…` 启动时，npm 以这些变量传给子进程。
+ * 不放行 npm_config_prefix / npm_config_local_prefix 等：它们会把安装改到别的目录。
+ */
+const NPM_CONFIG_NAMES = [
+    'npm_config_registry',
+    'npm_config_cache',
+    'npm_config_userconfig',
+    'npm_config_proxy',
+    'npm_config_https_proxy',
+    'npm_config_noproxy',
+    'npm_config_cafile',
+    'npm_config_strict_ssl',
+];
+function isAllowed(name, platform) {
+    if (platform === 'win32') {
+        const upper = name.toUpperCase();
+        return (ALLOWED_NAMES.some((allowed) => allowed.toUpperCase() === upper) ||
+            WINDOWS_NAMES.includes(upper) ||
+            ALLOWED_PREFIXES.some((prefix) => upper.startsWith(prefix)));
+    }
+    return ALLOWED_NAMES.includes(name) || ALLOWED_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+function pick(source, keep) {
+    const env = {};
+    for (const [name, value] of Object.entries(source)) {
+        if (value !== undefined && keep(name))
+            env[name] = value;
+    }
+    return env;
+}
+/** agent 进程的环境：只有白名单，不添加任何变量 */
+export function buildAgentEnv(source = process.env, platform = process.platform) {
+    return pick(source, (name) => isAllowed(name, platform));
+}
+/** 预检命令的环境：agent 环境 + NO_COLOR（只为输出好解析；OpenCode 实测仍带 ANSI，解析前另行剥离） */
+export function buildProbeEnv(source = process.env, platform = process.platform) {
+    return { ...buildAgentEnv(source, platform), NO_COLOR: '1' };
+}
+/** 适配器安装的环境：agent 环境 + 少数 npm 配置 */
+export function buildNpmEnv(source = process.env, platform = process.platform) {
+    return { ...buildAgentEnv(source, platform), ...pick(source, (name) => NPM_CONFIG_NAMES.includes(name)) };
+}

package/dist/bridge/exec.js

@@ -0,0 +1,90 @@
+/**
+ * bridge 内执行一次性命令（--version、状态检查、mcp list、npm ci、connect 写配置）。
+ *
+ * 必须异步：bridge 同时在转发 agent 的 ACP 流，connect 原有的 run()（spawnSync）会把事件循环卡住几秒到几十秒
+ * （`claude mcp list` 实测约 10 秒），期间所有页面都收不到消息。
+ *
+ * stdin 一律 'ignore'：被调命令看到的是非 TTY，不会停下来等输入；connect 的 cli.js 也据此走非交互分支（m2/configure 依赖这一点）。
+ *
+ * 超时必须真的封顶：命令可能再拉起子进程（`claude mcp list` 会启动用户配置的 stdio MCP 做健康检查，npm ci 有自己的子进程），
+ * 孙进程继承了输出管道时，'close' 要等它们全部退出才触发。所以 POSIX 下每条命令是独立进程组，超时对整组 SIGKILL 并**立即**返回，
+ * 不再等 'close'。bridge 退出时 killActiveExecs 清掉仍在运行的命令（main.ts 的退出路径调用）。
+ */
+import { spawn } from 'node:child_process';
+const DEFAULT_MAX_OUTPUT = 1024 * 1024;
+const GROUPS = process.platform !== 'win32';
+/** 正在运行的命令（bridge 退出时要清理） */
+const active = new Set();
+function killTree(child) {
+    if (child.pid === undefined)
+        return;
+    try {
+        if (GROUPS)
+            process.kill(-child.pid, 'SIGKILL');
+        else
+            child.kill('SIGKILL');
+    }
+    catch {
+        // ESRCH：已经退出。这里是超时 / 退出清理路径，再失败也没有更好的处理，结果已按超时上报
+    }
+}
+/** 同步杀掉所有仍在运行的命令及其子进程（bridge 退出时调用） */
+export function killActiveExecs() {
+    for (const child of active)
+        killTree(child);
+    active.clear();
+}
+export const execCommand = (command, args, options) => new Promise((resolve) => {
+    const max = options.maxOutput ?? DEFAULT_MAX_OUTPUT;
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timer;
+    let child;
+    const finish = (result, timedOut = false) => {
+        if (settled)
+            return;
+        settled = true;
+        if (timer)
+            clearTimeout(timer);
+        if (child)
+            active.delete(child);
+        resolve({ ...result, stdout, stderr, timedOut });
+    };
+    try {
+        child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: options.shell ?? false,
+            detached: GROUPS,
+            windowsHide: true,
+        });
+    }
+    catch (error) {
+        // 同步抛出只发生在参数非法时；按启动失败处理
+        finish({ code: null, signal: null, error: error instanceof Error ? error.message : String(error) });
+        return;
+    }
+    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);
+    });
+    running.stderr?.on('data', (chunk) => {
+        stderr = (stderr + chunk).slice(-max);
+    });
+    running.on('error', (error) => finish({ code: null, signal: null, error: error.message }));
+    running.on('close', (code, signal) => finish({ code, signal, error: null }));
+});
+/** stdout 与 stderr 合并（有些 CLI 把状态写在 stderr，例如 `codex login status`） */
+export function combinedOutput(result) {
+    const parts = [result.stdout, result.stderr, result.error ?? ''].filter((part) => part.length > 0);
+    return parts.join(parts.length > 1 ? '\n' : '');
+}

package/dist/bridge/lifecycle.js

@@ -0,0 +1,24 @@
+/**
+ * bridge 进程的退出信号处理。
+ *
+ * SIGINT（Ctrl+C）、SIGTERM、SIGHUP（关终端窗口）的默认处理都会直接终止进程，不触发 'exit' 事件，
+ * 所以三个信号都必须挂监听器走清理：agent 与一次性命令都在各自的进程组里（detached），收不到终端发来的信号。
+ *
+ * 第一次信号走正常收尾（关连接、SIGTERM 进程组、等宽限期）。之后的任何信号走立即清理（SIGKILL 进程组后退出）：
+ * 用户连按两次 Ctrl+C 很常见，如果用 once 挂监听器，第二个信号会落回默认处理、直接终止进程，跳过清理，留下孤儿进程
+ * （正在跑的 npm ci 可能长达 15 分钟、几百 MB 下载）。所以监听器用 on，一直挂着。
+ */
+export const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+export function installShutdownSignals(target, handlers) {
+    let received = false;
+    for (const signal of SHUTDOWN_SIGNALS) {
+        target.on(signal, () => {
+            if (received) {
+                handlers.immediate();
+                return;
+            }
+            received = true;
+            handlers.graceful();
+        });
+    }
+}

package/dist/bridge/m2-config.js

@@ -0,0 +1,38 @@
+/**
+ * 从 `{ mcpServers: { <name>: { url | serverUrl } } }` 形状的配置文件里找出所有指向 M2 的配置项名。
+ * 只给 Cursor 的预检用：`agent mcp list` 只输出名字不输出 URL，必须先从配置文件知道哪几个名字是 m2。
+ *
+ * 与 connect 的 findM2Entry（config-files.ts）判据相同（按 URL host），区别是这里要全部名字而不是第一个：
+ * 实测同一份 ~/.cursor/mcp.json 里会同时有 `m2` 和 `m2-test`，项目级 .cursor/mcp.json 里还可能再有一个。
+ *
+ * 读不了的文件（JSON 损坏）不能静默跳过：跳过会让预检报 not_configured、页面引导用户去「添加 m2」，
+ * 而真正的问题是配置文件坏了。所以把读不了的文件连同原因一起返回，由调用方报 unknown。
+ */
+import { isM2Url } from '../config-files.js';
+import { readJson } from '../system.js';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function m2NamesIn(config) {
+    if (!isObject(config) || !isObject(config.mcpServers))
+        return [];
+    return Object.entries(config.mcpServers)
+        .filter(([, entry]) => isObject(entry) && (isM2Url(entry.url) || isM2Url(entry.serverUrl)))
+        .map(([name]) => name);
+}
+/** 按给定顺序读多个配置文件（不存在的跳过），名字去重 */
+export function findM2Names(paths) {
+    const names = [];
+    const unreadable = [];
+    for (const path of paths) {
+        const read = readJson(path);
+        if (read.kind === 'invalid')
+            unreadable.push(`${path}: ${read.error}`);
+        if (read.kind !== 'ok')
+            continue;
+        for (const name of m2NamesIn(read.value))
+            if (!names.includes(name))
+                names.push(name);
+    }
+    return { names, unreadable };
+}

package/dist/bridge/main.js

@@ -0,0 +1,245 @@
+/**
+ * `npx @m2canvas/connect bridge`：在本机运行 ACP bridge，让 M2 页面经 ws://127.0.0.1 拉起并驱动本机的 agent。
+ *
+ * 只由 cli.ts 在第一个参数是 `bridge` 时动态加载：默认的 MCP 配置流程（Copy to agent 起手式）不会加载这里的任何代码与依赖。
+ *
+ * 本文件负责组装与终端交互：参数、启动横幅、配对码打印、信号处理、退出兜底清理。协议在 server.ts，安全判定在 security.ts / pairing.ts。
+ * 终端输出用英文，与 connect 现有输出一致。
+ */
+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 { AdapterManager, ADAPTERS } from './adapters.js';
+import { detectAgent } from './agents.js';
+import { buildAgentEnv, buildNpmEnv, buildProbeEnv } from './env.js';
+import { execCommand, killActiveExecs } from './exec.js';
+import { installShutdownSignals } from './lifecycle.js';
+import { PairingManager, createFilePairingStore } 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';
+import { createAgentService } from './service.js';
+import { KILL_GRACE_MS } from './processes.js';
+const NPM_CI_TIMEOUT_MS = 15 * 60 * 1000;
+const LABELS = {
+    claude: 'Claude Code',
+    codex: 'Codex',
+    cursor: 'Cursor',
+    opencode: 'OpenCode',
+    qoder: 'Qoder',
+};
+const HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev]
+       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.
+Agents run in the directory you start the bridge from (or --cwd), with your own logins.
+
+  --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 };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help')
+            args.help = true;
+        else if (arg === '--verbose')
+            args.verbose = true;
+        else if (arg === '--unpair')
+            args.unpair = true;
+        else if (arg === '--dev')
+            args.dev = true;
+        else if (arg === '--port' || arg === '--cwd') {
+            const value = argv[++i];
+            if (value === undefined)
+                return `${arg} needs a value`;
+            if (arg === '--cwd')
+                args.cwd = resolve(value);
+            else {
+                const port = Number(value);
+                if (!Number.isInteger(port) || port < 1 || port > 65535)
+                    return `invalid --port ${value}`;
+                args.port = port;
+            }
+        }
+        else
+            return `unknown option ${arg}`;
+    }
+    return args;
+}
+/** 包根目录：dist/bridge/*.js 与 src/bridge/*.ts 到包根的相对深度相同 */
+const PACKAGE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+function packageVersion() {
+    const parsed = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+    const version = typeof parsed === 'object' && parsed !== null ? parsed.version : undefined;
+    return typeof version === 'string' ? version : '0.0.0';
+}
+function printCode(info) {
+    const until = new Date(info.expiresAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    const code = `Pairing code: ${info.display}  (valid until ${until})`;
+    if (info.reason === 'startup')
+        console.log(`\n  ${code}\n  Enter it in M2 when it asks to connect to this bridge.\n`);
+    else if (info.reason === 'requested')
+        console.log(`\n→ ${info.origin ?? 'A page'} wants to pair with this bridge. ${code}\n  Only enter it if you opened M2 yourself.\n`);
+    else if (info.reason === 'expired')
+        console.log(`\n→ The pairing code expired. New ${code}\n`);
+    else
+        console.log(`\n→ Too many wrong pairing codes${info.origin ? ` from ${info.origin}` : ''}. New ${code}\n`);
+}
+function printLocked(origin) {
+    const from = origin ? ` (the last ones came from ${origin})` : '';
+    console.log(`\n→ Too many wrong pairing codes${from}. New pages can't pair until you restart the bridge (Ctrl+C, then run it again); ` +
+        `pages that are already paired keep working.${origin ? ` If you didn't open ${origin}, close that page first.` : ''}\n`);
+}
+function describeAdapter(agent, info) {
+    const name = `${LABELS[agent]} adapter (${ADAPTERS[agent].package}@${ADAPTERS[agent].version})`;
+    if (info.state === 'installing')
+        return `Installing the ${name}. First time only; it downloads the bundled agent and can take a few minutes…`;
+    if (info.state === 'ready')
+        return `${name} is ready.`;
+    if (info.state === 'failed')
+        return `Installing the ${name} failed: ${info.error ?? 'unknown error'}`;
+    return null;
+}
+export async function runBridge(argv) {
+    const parsed = parseArgs(argv);
+    if (typeof parsed === 'string') {
+        console.error(`${parsed}\n\n${HELP}`);
+        return 2;
+    }
+    if (parsed.help) {
+        console.log(HELP);
+        return 0;
+    }
+    const m2Dir = join(home, '.m2canvas');
+    const store = createFilePairingStore(join(m2Dir, 'bridge-pairings.json'), (message) => console.warn(message));
+    if (parsed.unpair) {
+        store.clear();
+        console.log('Forgot all paired pages. M2 will ask for a new pairing code next time.');
+        return 0;
+    }
+    if (!existsSync(parsed.cwd) || !statSync(parsed.cwd).isDirectory()) {
+        console.error(`--cwd ${parsed.cwd} is not a directory.`);
+        return 2;
+    }
+    const log = (message) => console.log(`[${new Date().toLocaleTimeString()}] ${message}`);
+    const probeEnv = buildProbeEnv();
+    const npm = which('npm') ?? (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    let server = null;
+    // 配对锁定只能靠重启 bridge 解除：bridge 不读终端（放到后台时读终端会被系统挂起），页面也没有任何途径解锁
+    const pairing = new PairingManager({
+        store,
+        onCodeIssued: printCode,
+        onLocked: printLocked,
+        onProblem: (message) => console.warn(message),
+    });
+    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',
+        }),
+        onState: (agent, info) => {
+            const line = describeAdapter(agent, info);
+            if (line)
+                log(line);
+            server?.broadcast('adapter/state', { agent, adapter: info });
+        },
+    });
+    const detect = (id) => detectAgent(id, { exec: execCommand, env: probeEnv, home });
+    const service = createAgentService({
+        detect,
+        exec: execCommand,
+        probeEnv,
+        cwd: parsed.cwd,
+        home,
+        adapters,
+        nodePath: process.execPath,
+        nodeVersion: process.versions.node,
+        cliPath: fileURLToPath(new URL('../cli.js', import.meta.url)),
+    });
+    const version = packageVersion();
+    const origins = allowedOrigins(parsed.dev);
+    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,
+        });
+    }
+    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;
+    }
+    const running = server;
+    // 兜底：bridge 经 process.exit 或未捕获异常退出时，不留下 agent 进程组和仍在运行的命令。
+    // 注意 SIGHUP / SIGINT / SIGTERM 的默认处理会直接终止进程、不触发 'exit'，所以这三个信号由 lifecycle.ts 显式接管。
+    process.on('exit', () => {
+        running.processes.killAllNow();
+        killActiveExecs();
+    });
+    // 关终端窗口后再往终端写会报 EIO / EPIPE；没有监听器时这会变成未捕获异常，打断清理。输出丢了无所谓，清理不能断
+    process.stdout.on('error', () => undefined);
+    process.stderr.on('error', () => undefined);
+    // 信号处理必须在服务器开始监听后立刻装好：下面的启动横幅要跑一遍 agent 检测（某个 --version 卡住时最长 15 秒），
+    // 这期间按 Ctrl+C 或关终端也要走清理（已配对的页面此时就可能拉起 agent，检测命令本身也在独立进程组里）
+    let resolveExit = () => undefined;
+    const exited = new Promise((resolve) => {
+        resolveExit = resolve;
+    });
+    const stop = async () => {
+        log('Stopping the bridge and its agents…');
+        // 一次性命令（npm ci、预检、检测）没有「正常收尾」可言，先同步杀掉，不等 close
+        killActiveExecs();
+        await running.close();
+        const deadline = Date.now() + KILL_GRACE_MS;
+        while (running.processes.size > 0 && Date.now() < deadline)
+            await new Promise((r) => setTimeout(r, 100));
+        running.processes.killAllNow();
+        resolveExit(0);
+    };
+    installShutdownSignals(process, {
+        graceful: () => void stop(),
+        // 收尾期间又来一个信号（连按 Ctrl+C）：不再等宽限期，立刻清理退出（exit 钩子也会再清一遍）
+        immediate: () => {
+            running.processes.killAllNow();
+            killActiveExecs();
+            process.exit(130);
+        },
+    });
+    console.log(`M2 local agent bridge ${version}`);
+    console.log(`  Listening on ws://127.0.0.1:${running.port}${BRIDGE_WS_PATH} (this machine only)`);
+    console.log(`  Working directory for agents: ${parsed.cwd}`);
+    console.log(`  Accepts pages from: ${origins.join(', ')}`);
+    if (parsed.dev)
+        console.log('  --dev: any app on the dev port can ask to pair. Only enter the code into your own M2 dev server.');
+    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');
+    return exited;
+}