dsh-tabbit 0.2.2 → 0.3.0

package/lib/runtime/endpoint.js

@@ -0,0 +1,248 @@
+/*
+ * ============================================================================
+ * 文件职责：直连 Runtime Service 公开端点（endpoint.json + NDJSON socket）
+ * ============================================================================
+ *
+ * 这是与浏览器通信的【第二条物理通道】，与 cli.ts（launcher 子进程）并列：
+ *
+ *   cli.ts     —— 每次 spawn launcher 子进程，走完整 CLI 面（求值/finish/…），
+ *                 具备"浏览器没在跑时自动拉起"的能力，代价是 ~1 秒级延迟；
+ *   endpoint.ts（本文件）—— 直接连浏览器发布的本机 socket，仅覆盖【无任务】
+ *                 操作（目前是 tabs 清单与 ping），稳态延迟 ~1ms，
+ *                 但【不会】拉起浏览器：离线就如实报离线。
+ *
+ * 选型背景（2026-08-28，与 Tabbit 团队确认）：persistent 模式（CLI 的 NDJSON
+ * 交互式子命令）计划移除，不能依赖；而 socket 协议里的 unbound `tabs` 是
+ * dispatch 的一等 case，与 persistent/bootstrap 绑定机制无关，且在 tab-browser
+ * tip-of-tree 上逐行未变——这是"零浏览器改动 + 快速读取"的唯一交集。
+ *
+ * ─── 线上协议（对 Dev 1.13.8 / 稳定 1.11.16 / tip-of-tree 三版源码核对一致，
+ *      并经真机验证；服务端实现 runtime-public-server.mjs + runtime-service.mjs）───
+ *
+ *  1. endpoint.json（schema v2，浏览器 C++ 侧 local_agent_endpoint.cc 写出）：
+ *       {version:2, kind:"browser-runtime-service", transport, address,
+ *        token(32字节 base64url), generation, browserPid}
+ *     位置在 <用户数据目录>/LocalAgent/endpoint.json（注册表记录里给了全路径）。
+ *     【只在 Runtime Service 运行期间存在，浏览器退出即删；每次重启
+ *     address/token/generation 三元组全部轮换】——所以本文件的铁律是：
+ *     每次连接前【现读】该文件，绝不缓存凭据。
+ *  2. 传输：macOS/Linux = unix domain socket（0600）；Windows = named pipe
+ *     （\\.\pipe\tabbit-runtime-…）。Node 的 net.createConnection 对两者同一 API。
+ *  3. 帧格式：NDJSON（一行一个 JSON + \n）。连接后第一帧必须是【严格恰好
+ *     三个键】的认证帧 {"version":1,"token":…,"generation":…}——服务端用
+ *     timingSafeEqual 比对，不匹配就【无响应直接断开】（这是认证失败唯一的
+ *     可观测征兆，见下面 STALE_ENDPOINT 的处理）。认证帧成功也没有回执。
+ *  4. 认证后每帧一个请求对象，响应一行 {ok:true,value} 或
+ *     {ok:false,error:{name,code,message}}。非 persistent 连接一问一答后由
+ *     服务端主动收尾；我们读到响应行就自行断开，不依赖这一行为。
+ *  5. unbound {"op":"tabs"}（连接上没有任务绑定时）：返回全 profile 标签页
+ *     清单。服务端内部开一个临时会话并在同一 dispatch 里 finalize(keep:true)
+ *     ——不产生任务、页面、标签组，也不出现在 `tasks` 列表里（真机核查）。
+ *     {"op":"ping"} 返回 {running:true, generation}，可当健康检查。
+ *  6. 服务端限额：认证帧 ≤4KB、请求 ≤64MB、8 并发 dispatch（超了回
+ *     SERVICE_BUSY）、未认证连接空闲 5 秒收、dispatch 超时 150 秒。
+ *
+ * 错误统一包装成 TabbitCliError（与 CLI 通道共用一套错误分类，上层不用区分
+ * 消息是从哪条通道冒出来的）。
+ */
+import { readFileSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { TabbitCliError, classifyAppError } from './errors.js';
+/* 我们支持的 endpoint.json schema 版本（浏览器侧 kBrowserRuntimeEndpointVersion）。 */
+const ENDPOINT_SCHEMA_VERSION = 2;
+const DEFAULT_TIMEOUT_MS = 15_000;
+/*
+ * 读取并校验 endpoint.json。三种失败各有语义：
+ *   - 文件读不到/不是 JSON：浏览器离线（文件退出即删）——ENDPOINT_MISSING；
+ *   - schema 版本或 kind 不认识：浏览器换了协议世代，需要升级本插件——
+ *     ENDPOINT_UNSUPPORTED（宁可明确失败也不猜着连）；
+ *   - transport 不认识：同上。
+ */
+export function readEndpoint(endpointPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(endpointPath, 'utf8'));
+    }
+    catch (error) {
+        throw new TabbitCliError({
+            kind: 'browser-unavailable',
+            code: 'ENDPOINT_MISSING',
+            message: `Tabbit Browser is not running (cannot read ${endpointPath}): ${String(error?.message ?? error)}`,
+        });
+    }
+    if (parsed.version !== ENDPOINT_SCHEMA_VERSION || parsed.kind !== 'browser-runtime-service') {
+        throw new TabbitCliError({
+            kind: 'protocol',
+            code: 'ENDPOINT_UNSUPPORTED',
+            message: `Unsupported Runtime Service endpoint schema (version=${String(parsed.version)} kind=${String(parsed.kind)}); update dsh-tabbit.`,
+        });
+    }
+    if ((parsed.transport !== 'unix_socket' && parsed.transport !== 'named_pipe') ||
+        typeof parsed.address !== 'string' ||
+        parsed.address === '' ||
+        typeof parsed.token !== 'string' ||
+        typeof parsed.generation !== 'string') {
+        throw new TabbitCliError({
+            kind: 'protocol',
+            code: 'ENDPOINT_UNSUPPORTED',
+            message: 'Runtime Service endpoint file is missing transport/address/token/generation fields.',
+        });
+    }
+    return parsed;
+}
+/*
+ * 在一条新连接上完成"认证帧 + 单个请求帧 → 一行响应"的完整交换。
+ *
+ * 实现要点：
+ *   - 认证帧和请求帧一次性写出（服务端逐帧消费，无需等认证回执——协议里
+ *     认证成功本来就没有回执）；
+ *   - settled 布尔量保证 resolve/reject 只发生一次（error/close/data 会竞争）；
+ *   - 读到第一个换行即为完整响应，之后立刻 destroy——unbound 连接没有任何
+ *     需要善后的服务端状态（无任务绑定），断开即干净；
+ *   - 【close 先于 data 到达 = 认证被拒或服务端换代】：服务端对坏凭据的行为
+ *     是无响应断开，映射为 STALE_ENDPOINT，由上层（requestViaEndpoint）现读
+ *     endpoint.json 重试一次——覆盖"浏览器刚重启、我们拿的是上一代凭据"窗口。
+ */
+function endpointRequestOnce(endpoint, payload, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(endpoint.address);
+        let buffer = '';
+        let settled = false;
+        const settle = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            action();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new TabbitCliError({
+                kind: 'timeout',
+                code: 'CLIENT_TIMEOUT',
+                message: `Runtime Service endpoint did not respond within ${timeoutMs}ms`,
+            })));
+        }, timeoutMs);
+        timer.unref();
+        socket.on('error', (error) => {
+            // 两类都归为"凭据/端点过期"（可现读文件重试一次）：
+            //   ENOENT/ECONNREFUSED —— 文件还在但 socket 已不可连（浏览器正在退出
+            //   或重启的窗口期）；
+            //   ECONNRESET/EPIPE —— 交换中途被掐（服务端对坏凭据的 destroy 在
+            //   客户端常表现为 RST，而不是干净的 close）。
+            const stale = error.code === 'ENOENT' ||
+                error.code === 'ECONNREFUSED' ||
+                error.code === 'ECONNRESET' ||
+                error.code === 'EPIPE';
+            settle(() => reject(new TabbitCliError({
+                kind: stale ? 'browser-unavailable' : 'protocol',
+                code: stale ? 'STALE_ENDPOINT' : 'SOCKET_ERROR',
+                message: stale
+                    ? `Runtime Service connection dropped before a response (browser restarting or stale credentials): ${error.code}`
+                    : `Runtime Service socket error: ${error.message}`,
+            })));
+        });
+        socket.on('connect', () => {
+            socket.write(`${JSON.stringify({ version: 1, token: endpoint.token, generation: endpoint.generation })}\n` +
+                `${JSON.stringify(payload)}\n`);
+        });
+        socket.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            settle(() => {
+                let response;
+                try {
+                    response = JSON.parse(buffer.slice(0, newline));
+                }
+                catch {
+                    reject(new TabbitCliError({
+                        kind: 'protocol',
+                        code: 'BAD_FRAME',
+                        message: `Runtime Service returned a non-JSON frame: ${buffer.slice(0, 200)}`,
+                    }));
+                    return;
+                }
+                if (response.ok === true) {
+                    resolve(response.value);
+                    return;
+                }
+                const error = response.error ?? {};
+                reject(new TabbitCliError({
+                    kind: classifyAppError(error),
+                    code: error.code ?? 'REQUEST_FAILED',
+                    message: error.message ?? 'Runtime Service request failed',
+                }));
+            });
+        });
+        socket.on('close', () => settle(() => reject(new TabbitCliError({
+            kind: 'browser-unavailable',
+            code: 'STALE_ENDPOINT',
+            message: 'Runtime Service closed the connection before responding (endpoint credentials are stale; the browser likely restarted)',
+        }))));
+    });
+}
+/*
+ * 对外的单请求入口：现读 endpoint.json → 交换一次；命中"凭据过期/socket 刚没"
+ * 这两类【重启窗口】错误时，再现读一次文件重试——文件是浏览器新一代身份的
+ * 唯一权威来源，重读即自愈。其余错误（离线、超时、服务端应用错误）原样上抛。
+ */
+export async function requestViaEndpoint(endpointPath, payload, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    try {
+        return await endpointRequestOnce(readEndpoint(endpointPath), payload, timeoutMs);
+    }
+    catch (error) {
+        if (!(error instanceof TabbitCliError) || error.code !== 'STALE_ENDPOINT')
+            throw error;
+        return await endpointRequestOnce(readEndpoint(endpointPath), payload, timeoutMs);
+    }
+}
+/*
+ * 全 profile 标签页清单（含用户自己开的页面，不限于代理任务页）。
+ * 零副作用：不建任务、不开页面、不出现在 tasks 列表（服务端 unbound tabs
+ * 的固有语义）。返回值形状逐字段校验——数据要进提示词/UI，宁可在这里挡住
+ * 服务端未来的形状漂移，也不把 unknown 直接漏给上层。
+ */
+export async function listAllTabs(endpointPath, options) {
+    const value = await requestViaEndpoint(endpointPath, { op: 'tabs' }, options);
+    const inventory = value;
+    if (typeof inventory !== 'object' || inventory === null || !Array.isArray(inventory.tabs)) {
+        throw new TabbitCliError({
+            kind: 'protocol',
+            code: 'BAD_FRAME',
+            message: 'Runtime Service tabs inventory has an unexpected shape',
+        });
+    }
+    const tabs = [];
+    for (const entry of inventory.tabs) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const tab = entry;
+        if (typeof tab.tabId !== 'number' || typeof tab.url !== 'string')
+            continue;
+        const group = tab.group;
+        tabs.push({
+            tabId: tab.tabId,
+            windowId: typeof tab.windowId === 'number' ? tab.windowId : 0,
+            index: typeof tab.index === 'number' ? tab.index : 0,
+            title: typeof tab.title === 'string' ? tab.title : '',
+            url: tab.url,
+            active: tab.active === true,
+            state: tab.state === 'owned' || tab.state === 'busy' ? tab.state : 'available',
+            group: typeof group === 'object' && group !== null && typeof group.groupId === 'string'
+                ? { groupId: group.groupId, title: typeof group.title === 'string' ? group.title : '' }
+                : null,
+        });
+    }
+    return { tabs, truncated: inventory.truncated === true };
+}
+/* 健康检查：浏览器在线时返回 {running:true, generation}。 */
+export async function pingEndpoint(endpointPath, options) {
+    const value = (await requestViaEndpoint(endpointPath, { op: 'ping' }, options));
+    return {
+        running: value?.running === true,
+        generation: typeof value?.generation === 'string' ? value.generation : '',
+    };
+}

package/lib/runtime/errors.js

@@ -0,0 +1,126 @@
+/*
+ * ============================================================================
+ * 文件职责：错误分类体系（error taxonomy）
+ * ============================================================================
+ *
+ * 本文件定义了与 Tabbit Browser「Runtime Service」（浏览器内置的自动化运行时
+ * 服务）打交道时可能遇到的所有错误类型。我们不直接连浏览器，而是通过命令行
+ * 启动器（launcher，装在 ~/.local/bin/ 下，新名 `tabbit-cli`、旧名
+ * `tabbit-playwright`）间接通信，所以错误会从好几个"层"冒出来：
+ *
+ *   第 1 层：launcher 外壳脚本（POSIX shell 脚本）自己失败
+ *           —— 比如机器上装了多个 Tabbit 实例、它不知道选哪个。
+ *           表现：stderr 上输出【纯文本】错误信息，进程退出码 69。
+ *
+ *   第 2 层：launcher 转交给的浏览器原生 CLI 失败
+ *           —— 比如任务超时、浏览器没起来、任务队列满了。
+ *           表现：stderr 上输出【一行 JSON】，形如
+ *           `{"ok":false,"error":{name,code,message}}`，退出码 64/69/70。
+ *
+ *   第 3 层：子进程本身起不来（launcher 文件不存在/没有执行权限），
+ *           或者我们这边等超时把它杀了。
+ *
+ * 上层代码（client.ts、tool-browser 等）拿到这里分类好的错误后，才能决定：
+ * 该不该自动重试？该给模型/用户什么样的提示语？
+ * 所有涉及具体错误码和退出码的知识，都是对真机 CLI 实测得来的（不是猜的）。
+ */
+/*
+ * Runtime Service 在应用层（第 2 层）会报出的错误码常量表。
+ * 键是我们自己起的驼峰名，值是 CLI 真实返回的错误码字符串。
+ * 集中列在这里，是为了让 classifyAppError() 的 switch 不出现裸字符串。
+ */
+export const CLI_ERROR_CODES = {
+    /* 浏览器或它的 Runtime Service 不可达（可能正在启动/已退出）。 */
+    browserUnavailable: 'BROWSER_RUNTIME_UNAVAILABLE',
+    /* 服务端并发已满，暂时忙。 */
+    serviceBusy: 'SERVICE_BUSY',
+    /* 单次求值超时（服务端上限 120 秒）。 */
+    taskTimeout: 'TASK_TIMEOUT',
+    /* 任务数达到上限（整台机器最多 8 个并发任务）。 */
+    taskLimitReached: 'TASK_LIMIT_REACHED',
+    /* 单个任务的排队队列满了。 */
+    taskQueueFull: 'TASK_QUEUE_FULL',
+    /* 任务的 worker 进程丢了（浏览器崩溃/重启）——任务内所有状态已丢失。 */
+    taskWorkerLost: 'TASK_WORKER_LOST',
+    /* 服务"代际"（generation）不匹配——服务重启过，旧任务作废。 */
+    generationMismatch: 'GENERATION_MISMATCH',
+    /* 整个 Runtime Service 丢失。 */
+    serviceLost: 'SERVICE_LOST',
+    /* CLI 与服务端协议版本不匹配（浏览器和 launcher 版本差太多）。 */
+    protocolMismatch: 'PROTOCOL_MISMATCH',
+    /* 想 claim（认领）的标签页已被别的任务占有。 */
+    tabOwnershipConflict: 'TAB_OWNERSHIP_CONFLICT',
+    /* 兜底的通用请求失败码。 */
+    requestFailed: 'REQUEST_FAILED',
+    /* 提交的代码体积超限。 */
+    codeTooLarge: 'CODE_TOO_LARGE',
+    /* 返回结果体积超限。 */
+    resultTooLarge: 'RESULT_TOO_LARGE',
+};
+/*
+ * 统一的错误类：所有从 CLI 层冒出来的失败都被包装成这个类抛出。
+ * 继承自 JS 内置的 Error，附加了四个字段方便上层判断与排障：
+ *   - kind：行为类别（见上面的 TabbitErrorKind）
+ *   - code：CLI 原始错误码（或我们自己造的，如 CLIENT_TIMEOUT）
+ *   - exitCode：子进程退出码（没有则为 null）
+ *   - stderrRaw：stderr 原文（排障时看）
+ */
+export class TabbitCliError extends Error {
+    kind;
+    code;
+    exitCode;
+    stderrRaw;
+    constructor(options) {
+        // super() 调用父类 Error 的构造函数，把 message 存进去。
+        super(options.message);
+        this.name = 'TabbitCliError';
+        this.kind = options.kind;
+        this.code = options.code;
+        this.exitCode = options.exitCode ?? null;
+        this.stderrRaw = options.stderrRaw ?? '';
+    }
+}
+/*
+ * "任务被隔离"没有专属错误码，只能靠错误信息文案匹配。
+ * 服务端原文形如 "... is quarantined; checkpoint before submitting more work"。
+ */
+const QUARANTINE_PATTERN = /is quarantined; checkpoint before submitting more work/u;
+/* "未知任务名"错误的文案前缀（对不存在的任务调 finish/receipt 时出现）。 */
+const UNKNOWN_TASK_PATTERN = /^Unknown task name: /u;
+/*
+ * 把 CLI 返回的应用层错误对象（{name, code, message}）归类成 TabbitErrorKind。
+ * 这是"错误码 → 行为类别"的唯一映射点。
+ */
+export function classifyAppError(error) {
+    const code = error.code ?? CLI_ERROR_CODES.requestFailed;
+    const message = error.message ?? '';
+    switch (code) {
+        case CLI_ERROR_CODES.browserUnavailable:
+            return 'browser-unavailable';
+        case CLI_ERROR_CODES.serviceBusy:
+        case CLI_ERROR_CODES.taskQueueFull:
+            return 'busy';
+        // 下面三种码本质相同：任务/服务的"上一世"没了，之前的状态全部作废。
+        case CLI_ERROR_CODES.taskWorkerLost:
+        case CLI_ERROR_CODES.generationMismatch:
+        case CLI_ERROR_CODES.serviceLost:
+            return 'task-reset';
+        case CLI_ERROR_CODES.tabOwnershipConflict:
+            return 'tab-claim';
+        case CLI_ERROR_CODES.taskTimeout:
+            return 'timeout';
+        default:
+            // 隔离错误没有专属 code，只能从 message 文案里认。
+            if (QUARANTINE_PATTERN.test(message))
+                return 'quarantined';
+            return 'app';
+    }
+}
+/*
+ * 判断一个错误是不是"未知任务名"。
+ * 用途：清理任务时（finishTask），任务可能早已不存在（浏览器重启过/用户手动
+ * 关了）——这种情况视为"已经清理完成"，静默吞掉即可，不算失败。
+ */
+export function isUnknownTaskError(error) {
+    return error instanceof TabbitCliError && UNKNOWN_TASK_PATTERN.test(error.message);
+}

package/lib/runtime/instances.js

@@ -0,0 +1,287 @@
+/*
+ * ============================================================================
+ * 文件职责：读取 Tabbit「实例注册表」（instance registry）
+ * ============================================================================
+ *
+ * 背景知识：一台机器上可以同时装多个 Tabbit Browser（比如正式版 + Dev 版 +
+ * 国内版）。每个安装好的浏览器在首次启动时会写一条注册记录，【两平台不同构】
+ * （均以 tab-browser 源码 local_agent_host_integration_manager.cc 为准）：
+ *
+ * macOS/Linux：`~/.local/share/tabbit-playwright/instances/<16位大写hex>.instance`
+ * 三行纯文本：
+ *     第 1 行：固定魔法串（见下面 REGISTRY_MAGIC），防止误读无关文件；
+ *     第 2 行：该实例自带 CLI 可执行文件的绝对路径；
+ *     第 3 行：该实例 endpoint.json 的绝对路径——【浏览器只在自己的
+ *             Runtime Service 正在运行时才会创建这个文件，退出即删】。
+ *             所以"endpoint 文件当前存在" == "这个实例在线"。
+ * 新版浏览器（2026-08 起）还会在旁边写一个同名 `.product` 档案（两行：
+ * 魔法串 + 产品名，如 "Tabbit Browser Dev"）——比从 CLI 路径猜应用名可靠，
+ * 有就优先用它做展示名。
+ *
+ * Windows：`%LOCALAPPDATA%\Tabbit\LocalAgent\instances\<16位大写hex>.json`
+ * （C++ 侧 BuildWindowsInstanceRecord 写出的 JSON，DACL 保护）：
+ *     {version:1, instanceId, product, cliPath, endpointPath, browserPath,
+ *      userDataDir}
+ * 产品名直接在记录里，没有 .product 旁档；在线判定同样看 endpointPath
+ * 文件是否存在。注意所有产品共用同一个注册表目录（launcher 也固定装在
+ * %LOCALAPPDATA%\Tabbit\LocalAgent\bin\，不随产品名变化）。
+ *
+ * launcher 外壳脚本（新名 `tabbit-cli`，旧名 `tabbit-playwright`，见
+ * defaultLauncherPath 的说明）自己也读这个注册表来决定把命令转发
+ * 给哪个实例。我们为什么还要【自己再解析一遍】而不是只依赖外壳的报错？
+ *   1. `/tabbit-info` 诊断命令要能列出所有实例给用户看；
+ *   2. 选择无歧义时（只有一个在线实例）可以自动选中，用户零配置；
+ *   3. 有歧义时能抛出带完整实例清单的、可操作的错误信息。
+ * 本文件的校验规则刻意与外壳脚本保持一致，避免"我们认、外壳不认"的分裂。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join } from 'node:path';
+/* 注册文件必须以这行魔法串开头，否则视为无关文件跳过。 */
+const REGISTRY_MAGIC = '# tabbit-playwright instance managed by Tabbit Browser';
+/* .product 档案的首行魔法串（第二行是产品名）。 */
+const PRODUCT_MAGIC = '# tabbit-playwright product managed by Tabbit Browser';
+/* 合法实例 id 的形状：恰好 16 位大写十六进制。 */
+const INSTANCE_ID_PATTERN = /^[0-9A-F]{16}$/u;
+/* POSIX 注册表目录的默认位置。 */
+export function defaultRegistryDir() {
+    return join(homedir(), '.local', 'share', 'tabbit-playwright', 'instances');
+}
+/* Windows 注册表目录的默认位置（= 原生 CLI 目录的上一级 + instances）。 */
+export function defaultWindowsRegistryDir({ env = process.env, userHome = homedir(), } = {}) {
+    const base = env.LOCALAPPDATA || join(userHome, 'AppData', 'Local');
+    return join(base, 'Tabbit', 'LocalAgent', 'instances');
+}
+/*
+ * launcher 外壳的默认安装位置。浏览器新版本（2026-08 起）注册的名字是
+ * `tabbit-cli`（加固版外壳：校验属主/权限、读 .product 档案、优先选择
+ * 「浏览器进程还活着」的实例），旧名 `tabbit-playwright` 一段时间内并存但
+ * 已被官方弃用——且旧壳在多实例机器上无法自动选实例（直接报错要求设环境
+ * 变量），新壳能自动选中活跃实例。选择顺序：
+ *   - Windows：%LOCALAPPDATA%\Tabbit\LocalAgent\bin\tabbit-cli.exe
+ *     （原生可执行文件，浏览器安装时布置）；
+ *   - 其它平台：~/.local/bin/tabbit-cli 存在就用；否则回退旧名
+ *     tabbit-playwright；两个都不存在时返回新名——让"launcher 缺失"的
+ *     报错信息指向当前正确的安装路径。
+ * 参数可注入（platform/env/userHome）仅为单元测试；生产调用一律无参。
+ */
+export function defaultLauncherPath({ platform = process.platform, env = process.env, userHome = homedir(), } = {}) {
+    if (platform === 'win32') {
+        const base = env.LOCALAPPDATA || join(userHome, 'AppData', 'Local');
+        return join(base, 'Tabbit', 'LocalAgent', 'bin', 'tabbit-cli.exe');
+    }
+    const modern = join(userHome, '.local', 'bin', 'tabbit-cli');
+    if (existsSync(modern))
+        return modern;
+    const legacy = join(userHome, '.local', 'bin', 'tabbit-playwright');
+    if (existsSync(legacy))
+        return legacy;
+    return modern;
+}
+/*
+ * 从 CLI 路径里提取应用名：macOS 上路径通常形如
+ * `/Applications/Tabbit Browser.app/Contents/.../cli`，取 `.app` 那段；
+ * 匹配不到就退化为文件名。仅用于展示，不参与任何逻辑判断。
+ */
+function deriveAppName(cliPath) {
+    const match = cliPath.match(/\/([^/]+\.app)\//u);
+    if (match)
+        return match[1].replace(/\.app$/u, '');
+    return basename(cliPath);
+}
+/*
+ * 读实例的 .product 档案（新版浏览器写的产品名，如 "Tabbit Browser Dev"）。
+ * 档案缺失/魔法串不对/产品名为空 → undefined（回退到 deriveAppName）。
+ */
+function readProductName(registryDir, id) {
+    let text;
+    try {
+        text = readFileSync(join(registryDir, `${id}.product`), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const lines = text.split('\n');
+    if (lines[0] !== PRODUCT_MAGIC)
+        return undefined;
+    const product = (lines[1] ?? '').trim();
+    return product !== '' ? product : undefined;
+}
+/*
+ * 列出所有合法的已注册实例（平台分派入口）。
+ *
+ * 有意用【同步】文件 API（readdirSync 等）：调用频率低、文件极小，同步读省去
+ * 到处传 Promise 的复杂度，也让 core 层的 resolveExecutionInstance() 可以保持
+ * 同步签名。
+ *
+ * 显式传了 registryDir 时按 POSIX 格式解析（历史签名，单元测试与诊断用）；
+ * 不传时按当前平台选注册表：win32 走 JSON 记录，其余走 .instance 三行文本。
+ */
+export function listInstances(registryDir) {
+    if (registryDir === undefined && process.platform === 'win32')
+        return listInstancesWindows();
+    return listInstancesPosix(registryDir ?? defaultRegistryDir());
+}
+/*
+ * POSIX 注册表解析。每个候选文件要闯过 5 道校验（与 launcher 外壳一致），
+ * 任何一道不过就整个跳过：
+ *   1. 文件名以 .instance 结尾且去后缀后是 16 位大写 hex；
+ *   2. 首行等于魔法串；
+ *   3. 第 2、3 行都是绝对路径；
+ *   4. CLI 路径确实存在且是普通文件；
+ *   5. （不淘汰，只标记）endpoint 文件存在与否决定 online。
+ */
+export function listInstancesPosix(registryDir = defaultRegistryDir()) {
+    let names;
+    try {
+        names = readdirSync(registryDir);
+    }
+    catch {
+        // 目录不存在（从没装过 Tabbit）：返回空列表而不是抛错。
+        return [];
+    }
+    const instances = [];
+    for (const name of names) {
+        if (!name.endsWith('.instance'))
+            continue;
+        const id = name.slice(0, -'.instance'.length);
+        if (!INSTANCE_ID_PATTERN.test(id))
+            continue;
+        let text;
+        try {
+            text = readFileSync(join(registryDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const lines = text.split('\n');
+        if (lines[0] !== REGISTRY_MAGIC)
+            continue;
+        const cliPath = lines[1] ?? '';
+        const endpointPath = lines[2] ?? '';
+        if (!isAbsolute(cliPath) || !isAbsolute(endpointPath))
+            continue;
+        let cliOk = false;
+        try {
+            cliOk = statSync(cliPath).isFile();
+        }
+        catch {
+            continue;
+        }
+        if (!cliOk)
+            continue;
+        let online = false;
+        try {
+            online = statSync(endpointPath).isFile();
+        }
+        catch {
+            online = false;
+        }
+        instances.push({ id, cliPath, endpointPath, online, appName: readProductName(registryDir, id) ?? deriveAppName(cliPath) });
+    }
+    // 按 id 排序，保证多次调用输出顺序稳定（诊断输出、错误信息里好对照）。
+    instances.sort((a, b) => a.id.localeCompare(b.id));
+    return instances;
+}
+/*
+ * Windows 注册表解析。校验规则镜像 C++ 写入端（BuildWindowsInstanceRecord）：
+ *   1. 文件名以 .json 结尾；
+ *   2. 记录 version === 1；
+ *   3. instanceId 是 16 位大写 hex 且与文件名一致（防止拷贝改名产生分裂身份）；
+ *   4. cliPath/endpointPath 是非空字符串，cliPath 指向存在的普通文件；
+ *   5. endpoint 文件存在与否决定 online（同 POSIX）。
+ * 展示名优先记录里的 product 字段（Windows 没有 .product 旁档）。
+ */
+export function listInstancesWindows(registryDir = defaultWindowsRegistryDir()) {
+    let names;
+    try {
+        names = readdirSync(registryDir);
+    }
+    catch {
+        return [];
+    }
+    const instances = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(readFileSync(join(registryDir, name), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (record.version !== 1)
+            continue;
+        const id = typeof record.instanceId === 'string' ? record.instanceId : '';
+        if (!INSTANCE_ID_PATTERN.test(id) || `${id}.json` !== name)
+            continue;
+        const cliPath = typeof record.cliPath === 'string' ? record.cliPath : '';
+        const endpointPath = typeof record.endpointPath === 'string' ? record.endpointPath : '';
+        if (cliPath === '' || endpointPath === '')
+            continue;
+        let cliOk = false;
+        try {
+            cliOk = statSync(cliPath).isFile();
+        }
+        catch {
+            continue;
+        }
+        if (!cliOk)
+            continue;
+        let online = false;
+        try {
+            online = statSync(endpointPath).isFile();
+        }
+        catch {
+            online = false;
+        }
+        instances.push({
+            id,
+            cliPath,
+            endpointPath,
+            online,
+            appName: typeof record.product === 'string' && record.product !== '' ? record.product : deriveAppName(cliPath),
+        });
+    }
+    instances.sort((a, b) => a.id.localeCompare(b.id));
+    return instances;
+}
+/*
+ * 决定最终把哪个实例 id 通过环境变量 TABBIT_PLAYWRIGHT_INSTANCE 传给 launcher。
+ * 消歧规则刻意镜像 launcher 外壳自己的规则：
+ *
+ *   - 显式指定（settings 配了 tabbit.instance）：必须在注册表里，否则抛出
+ *     带可用实例清单的错误（帮用户发现是配错了 id 还是没装）；
+ *   - 未指定：
+ *       · 恰好 1 个在线实例 → 选它；
+ *       · 0 个在线但总共只装了 1 个 → 选它（launcher 会自动把浏览器拉起来）；
+ *       · 一个都没装 → 抛"请先安装并启动一次 Tabbit"；
+ *       · 多个且无法定夺 → 抛带完整清单的引导错误，提示用户去 settings 里
+ *         设置 tabbit.instance。
+ *
+ * 返回 undefined 的含义：不设置环境变量、裸调 launcher 也一定能成功的场景
+ * （机器上只有一个实例时 launcher 自己就能选对）。
+ */
+export function resolveInstanceId(configured, instances) {
+    if (configured) {
+        const found = instances.find((instance) => instance.id === configured);
+        if (!found) {
+            const available = instances.map((instance) => `${instance.id} (${instance.appName})`).join(', ') || 'none';
+            throw new Error(`Configured Tabbit instance ${configured} is not registered. Available instances: ${available}.`);
+        }
+        return configured;
+    }
+    const online = instances.filter((instance) => instance.online);
+    if (online.length === 1)
+        return online[0].id;
+    if (online.length === 0 && instances.length === 1)
+        return instances[0].id;
+    if (instances.length === 0) {
+        throw new Error('No Tabbit Browser instance is registered on this machine (missing ~/.local/share/tabbit-playwright/instances). Install and launch Tabbit Browser first.');
+    }
+    const listing = instances
+        .map((instance) => `${instance.id} (${instance.appName}${instance.online ? ', online' : ''})`)
+        .join(', ');
+    throw new Error(`Multiple Tabbit Browser instances are registered; set the "tabbit" settings key "instance" to one of: ${listing}.`);
+}