@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/capabilities/session/extension-bridge.js

@@ -1,77 +1,112 @@
+/**
+ * 会话扩展桥(extension-bridge,RFC docs/rfc/user-session-data-rfc.md §2.2 通道 C——2026-08-29 founder 定案为 PRIMARY 传输)。
+ *
+ * 形态:Node http 服务,懒启动单例,只绑 127.0.0.1,端口池 8791-8795(与 extension/manifest.json
+ * host_permissions 一一对应,防漂移测试守住);**零新依赖**(node:http 手写,对齐已退役 shell 薄壳
+ * 的回环纪律;不引 ws——MV3 Service Worker 靠 ≤20s 的长轮询节奏维持 30s 存活窗口,HTTP 够用)。
+ *
+ * 授权模型:扩展经「一次性安装」获得信任,每请求校验 Origin ∈ 双通道扩展源白名单
+ * (网页发起的跨域请求必带邪恶 Origin,直接 403;POST 端点强制;GET /health /status 是本机
+ * 诊断面放行)。不做 CORS——有 host_permissions 的扩展 fetch 天然免预检,网页过不来。
+ * 双通道 ID 实录(2026-09-02):unpacked 通道(bundled/GitHub Releases)由 manifest 固定 key
+ * 派生 EXTENSION_ID;Chrome Web Store 用商店自己的签名 key 重签(不认 manifest key),
+ * 商店版 ID = EXTENSION_ID_STORE。两个 ID 都是 founder 控制的同一扩展,白名单双收。
+ *
+ * 协议(长轮询):
+ *   GET  /health           → lastSeen 刷新(扩展每 ≤30s 一次 + 每次断线重连)
+ *   GET  /status           → 诊断面 {port, extensionConnected, lastSeenMsAgo, queued, inFlight, parked}
+ *   POST /jobs             → 长轮询取活(hold ≤20s 返 {job:null});扩展单客户端
+ *   POST /results/:jobId   → 善果/失败回传(≤8MB;batchSearch ~550KB)
+ * 语义:桥不存在即整个扩展车道不存在——fail-closed 不变量在调用方(session-search 的 needs-extension)。
+ * 审计:job 提交/回传写 GuardAuditEntry 同款 JSONL(kind:'extension-session-job',channel 层负责)。
+ */
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { createServer } from 'node:http';
-export const BRIDGE_PORTS = [
-    8791,
-    8792,
-    8793,
-    8794,
-    8795
-];
+/** 桥端口池(extension/manifest.json host_permissions 必须同面;§38 断言) */
+export const BRIDGE_PORTS = [8791, 8792, 8793, 8794, 8795];
 export const BRIDGE_PROTOCOL = 'session-bridge.v1';
+/** 扩展固定 ID(unpacked 通道:manifest key 派生;bundled/GitHub Releases 均此 ID。变更即失配,Node 侧拒绝) */
 export const EXTENSION_ID = 'olpgkofjhhiiiahdkkbcninhjmegghfe';
 export const EXTENSION_ORIGIN = `chrome-extension://${EXTENSION_ID}`;
+/**
+ * Chrome Web Store 版扩展 ID(2026-09-02 上架):商店用自己生成的签名 key 重签,
+ * **不认 manifest 里的固定 key**——商店版 ID 与 unpacked 版不同(上架材料文档的
+ * 「若商店不认 key」预案坐实)。item ID 即商店详情页 URL 末段。
+ */
 export const EXTENSION_ID_STORE = 'oeajpiccmonococjcegddlooeeohlbgd';
 export const EXTENSION_ORIGIN_STORE = `chrome-extension://${EXTENSION_ID_STORE}`;
+/** 商店详情页(一键安装 + 自动更新通道;推荐安装方式) */
 export const EXTENSION_STORE_URL = `https://chromewebstore.google.com/detail/gotry-session-bridge/${EXTENSION_ID_STORE}`;
-export const EXTENSION_ORIGINS = [
-    EXTENSION_ORIGIN,
-    EXTENSION_ORIGIN_STORE
-];
+/** 桥信任的扩展 Origin 白名单:unpacked(固定 key)+ 商店版,双通道同一扩展同源信任 */
+export const EXTENSION_ORIGINS = [EXTENSION_ORIGIN, EXTENSION_ORIGIN_STORE];
+/**
+ * 本地 unpacked 通道是否已落位(~/.gotry/extension/manifest.json)。
+ * 商店版没有本地文件面(装在 Chrome 里),离线不可探测——本函数只回答「本地通道在不在」,
+ * 商店版用户在这里恒 false,这正是 D-24 自适应文案的判定输入。
+ */
 export function localExtensionInstalled(home = homedir()) {
     return existsSync(join(home, '.gotry', 'extension', 'manifest.json'));
 }
+/**
+ * needs-extension 自适应摘要(issue #117,D-24 残量):
+ * - 本地 unpacked 已落位 → 完整双通道指引(商店 + GitHub/开发者模式本地通道);
+ * - 未落位(商店版用户,或完全未装)→ 只推商店一键装,并给「已装商店版?打开 Chrome 即可」
+ *   提示——**不再出现开发者模式/本地通道文案**(已装商店版的用户不该再被指导 load unpacked)。
+ * 纯函数(默认 HOME 可注入)。
+ */
 export function needsExtensionSummary(opts = {}) {
     const local = opts.localInstalled ?? localExtensionInstalled(opts.home);
     if (local) {
-        return 'GoTry Session Bridge 扩展未连接(未安装或已停用)。推荐 Chrome 应用商店一键装(自动更新) ' + `${EXTENSION_STORE_URL} ;或 npx gotry setup 落位后 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension`;
+        return 'GoTry Session Bridge 扩展未连接(未安装或已停用)。推荐 Chrome 应用商店一键装(自动更新) '
+            + `${EXTENSION_STORE_URL} ;或 npx @danceiny/gotry setup 落位后 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension`;
     }
-    return 'GoTry Session Bridge 扩展未连接。若你已从 Chrome 商店安装(自动更新):打开 Chrome 并确认扩展已启用即可自动连接,无需再装。' + `若尚未安装:应用商店一键装 ${EXTENSION_STORE_URL} (装完零弹窗,浏览器自己当安装器)`;
+    return 'GoTry Session Bridge 扩展未连接。若你已从 Chrome 商店安装(自动更新):打开 Chrome 并确认扩展已启用即可自动连接,无需再装。'
+        + `若尚未安装:应用商店一键装 ${EXTENSION_STORE_URL} (装完零弹窗,浏览器自己当安装器)`;
 }
+/** 扩展在线判定:/health 心跳 ≤30s 一次 + 轮询重连,1.5 倍容差 */
 export const EXTENSION_CONNECTED_WINDOW_MS = 45_000;
+/** /jobs 长轮询 hold 上限(必须 < MV3 SW 30s 存活窗口) */
 export const JOBS_LONG_POLL_MS = 20_000;
+/** 提交 job 时扩展尚未上线,等它连上桥的宽限(首次调用后桥才拉起,扩展 5s 内即回连) */
 export const DEFAULT_EXTENSION_WAIT_MS = 6_000;
+/** /results 回包上限(batchSearch ~550KB,余量给未来酒店/多航段) */
 export const MAX_RESULT_BODY_BYTES = 8 * 1024 * 1024;
+function jobMatches(entry, capabilities) {
+    if (capabilities == null || capabilities.size === 0)
+        return true;
+    return capabilities.has(entry.site);
+}
 function readBody(req, cap) {
-    return new Promise((resolve)=>{
+    return new Promise((resolve) => {
         const chunks = [];
         let size = 0;
         let done = false;
-        req.on('data', (c)=>{
-            if (done) return;
+        req.on('data', (c) => {
+            if (done)
+                return;
             size += c.length;
             if (size > cap) {
                 done = true;
                 req.removeAllListeners('data');
-                resolve({
-                    err: `body 超 ${cap} 字节上限(防失控回包)`
-                });
+                resolve({ err: `body 超 ${cap} 字节上限(防失控回包)` });
                 return;
             }
             chunks.push(c);
         });
-        req.on('end', ()=>{
-            if (!done) {
-                done = true;
-                resolve(Buffer.concat(chunks).toString('utf8'));
-            }
-        });
-        req.on('error', ()=>{
-            if (!done) {
-                done = true;
-                resolve({
-                    err: 'body 读取失败'
-                });
-            }
-        });
+        req.on('end', () => { if (!done) {
+            done = true;
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        } });
+        req.on('error', () => { if (!done) {
+            done = true;
+            resolve({ err: 'body 读取失败' });
+        } });
     });
 }
-export async function createSessionBridge(opts = {}) {
-    const ports = opts.ports ?? [
-        ...BRIDGE_PORTS
-    ];
+export function createBridgeJobQueue(opts = {}) {
     const extensionOrigins = new Set(opts.extensionOrigins ?? EXTENSION_ORIGINS);
     const now = opts.now ?? Date.now;
     const queue = [];
@@ -79,199 +114,210 @@ export async function createSessionBridge(opts = {}) {
     const parked = [];
     let lastSeenAt = 0;
     let closed = false;
-    let port = 0;
-    const extensionConnected = ()=>lastSeenAt > 0 && now() - lastSeenAt < EXTENSION_CONNECTED_WINDOW_MS;
-    function takeQueued() {
-        const next = queue.shift();
-        if (next) inFlight.set(next.job.jobId, next);
-        return next ?? null;
+    const extensionConnected = () => lastSeenAt > 0 && now() - lastSeenAt < EXTENSION_CONNECTED_WINDOW_MS;
+    /** 领走首个 capability 匹配的 job(移入 inFlight——回包按 jobId 路由,两处都可找到) */
+    function takeMatching(capabilities) {
+        const idx = queue.findIndex((q) => jobMatches(q.job, capabilities));
+        if (idx < 0)
+            return null;
+        const [next] = queue.splice(idx, 1);
+        inFlight.set(next.job.jobId, next);
+        return next;
     }
-    const server = createServer((req, res)=>{
-        if (closed) {
-            res.statusCode = 503;
-            res.end();
-            return;
-        }
-        const urlPath = (req.url ?? '').split('?')[0];
-        const origin = req.headers.origin;
-        const isPost = req.method === 'POST';
-        const originTrusted = typeof origin === 'string' && extensionOrigins.has(origin);
-        if (isPost && !originTrusted) {
-            res.statusCode = 403;
-            res.setHeader('content-type', 'application/json');
-            res.end(JSON.stringify({
-                ok: false,
-                error: 'origin 不在桥白名单'
-            }));
-            return;
-        }
-        if (originTrusted) {
-            lastSeenAt = now();
-        }
-        const finish = (code, body)=>{
-            res.statusCode = code;
-            res.setHeader('content-type', 'application/json');
-            res.end(JSON.stringify(body));
-        };
-        if (req.method === 'GET' && urlPath === '/health') {
-            finish(200, {
-                ok: true,
-                service: 'gotry-session-bridge',
-                protocol: BRIDGE_PROTOCOL
-            });
-            return;
-        }
-        if (req.method === 'GET' && urlPath === '/status') {
-            finish(200, {
-                ok: true,
-                port,
-                protocol: BRIDGE_PROTOCOL,
-                extensionConnected: extensionConnected(),
-                lastSeenMsAgo: lastSeenAt > 0 ? now() - lastSeenAt : null,
-                queued: queue.length,
-                inFlight: inFlight.size,
-                parked: parked.length
-            });
-            return;
-        }
-        if (isPost && urlPath === '/jobs') {
-            const next = takeQueued();
-            if (next) {
-                finish(200, {
-                    job: next.job
-                });
-                return;
-            }
-            const parkTimer = setTimeout(()=>{
-                const i = parked.findIndex((p)=>p.res === res);
-                if (i >= 0) parked.splice(i, 1);
-                finish(200, {
-                    job: null
-                });
-            }, JOBS_LONG_POLL_MS);
-            if (!opts.keepBridge) parkTimer.unref();
-            parked.push({
-                res,
-                timer: parkTimer
-            });
-            res.on('close', ()=>{
-                const i = parked.findIndex((p)=>p.res === res);
-                if (i >= 0) parked.splice(i, 1);
-                clearTimeout(parkTimer);
-            });
-            return;
-        }
-        if (isPost && urlPath.startsWith('/results/')) {
-            const jobId = decodeURIComponent(urlPath.slice('/results/'.length));
-            void readBody(req, MAX_RESULT_BODY_BYTES).then((body)=>{
-                if (typeof body !== 'string') {
-                    finish(400, {
-                        ok: false,
-                        error: body.err
-                    });
-                    return;
-                }
-                let parsed;
-                try {
-                    parsed = JSON.parse(body);
-                } catch  {
-                    finish(400, {
-                        ok: false,
-                        error: '回包不是 JSON'
-                    });
-                    return;
-                }
-                finish(200, {
-                    ok: true
-                });
-                resolveJob(jobId, parsed);
-            });
-            return;
-        }
-        finish(404, {
-            ok: false,
-            error: 'unknown endpoint'
-        });
-    });
-    server.on('connection', (socket)=>{
-        if (!opts.keepBridge) socket.unref();
-    });
+    /** 扩展回包:queued 与 inFlight 两处都可寻址(job 执行失败 = result.ok:false,桥自身不吞) */
     function resolveJob(jobId, parsed) {
         const inFlightHit = inFlight.get(jobId);
         if (inFlightHit) {
             inFlight.delete(jobId);
-            if (inFlightHit.timer) clearTimeout(inFlightHit.timer);
-            inFlightHit.resolve({
-                ok: true,
-                result: parsed
-            });
+            if (inFlightHit.timer)
+                clearTimeout(inFlightHit.timer);
+            inFlightHit.resolve({ ok: true, result: parsed });
             return;
         }
-        const idx = queue.findIndex((q)=>q.job.jobId === jobId);
-        if (idx < 0) return;
+        const idx = queue.findIndex((q) => q.job.jobId === jobId);
+        if (idx < 0)
+            return;
         const [entry] = queue.splice(idx, 1);
-        if (entry.timer) clearTimeout(entry.timer);
-        entry.resolve({
-            ok: true,
-            result: parsed
-        });
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.resolve({ ok: true, result: parsed });
     }
+    /** 新 job 入队时即时派发给 capability 匹配的 parked 取活者(否则要白等一个 20s 长轮询周期) */
     function dispatchToParked(entry) {
-        const p = parked.shift();
-        if (!p) return false;
+        const i = parked.findIndex((p) => jobMatches(entry.job, p.capabilities));
+        if (i < 0)
+            return false;
+        const [p] = parked.splice(i, 1);
         clearTimeout(p.timer);
         inFlight.set(entry.job.jobId, entry);
         p.res.statusCode = 200;
         p.res.setHeader('content-type', 'application/json');
-        p.res.end(JSON.stringify({
-            job: entry.job
-        }));
+        p.res.end(JSON.stringify({ job: entry.job }));
         return true;
     }
-    const bridge = {
+    const stats = () => ({
+        queued: queue.length,
+        inFlight: inFlight.size,
+        parked: parked.length,
+        lastSeenMsAgo: lastSeenAt > 0 ? now() - lastSeenAt : null,
+    });
+    /**
+     * 协议处理器工厂:prefix='' 为独立桥形态(路径式 results);prefix='/v1/session/bridge'
+     * 为挂载形态(查询式 results——gotry-backend 内核只支持精确路由,jobId 走 query)。
+     * Origin 白名单校验内置于两种形态(远程形态同样强制:网页跨域请求必带邪恶 Origin)。
+     */
+    function makeHandler(prefix, resultsViaQuery, statusExtra) {
+        return (req, res) => {
+            if (closed) {
+                res.statusCode = 503;
+                res.end();
+                return;
+            }
+            const urlPath = (req.url ?? '').split('?')[0];
+            const path = prefix && urlPath.startsWith(prefix) ? urlPath.slice(prefix.length) : urlPath;
+            const origin = req.headers.origin;
+            const isPost = req.method === 'POST';
+            const originTrusted = typeof origin === 'string' && extensionOrigins.has(origin);
+            // 网页侧请求必带 Origin;桥端点只信任白名单内的 chrome-extension:// 源(诊断 GET 面放行)
+            if (isPost && !originTrusted) {
+                res.statusCode = 403;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify({ ok: false, error: 'origin 不在桥白名单' }));
+                return;
+            }
+            // 心跳:扩展平时只走 /jobs 长轮询(健康只在启动探测时 ping 一次)——
+            // 一切携带白名单扩展 Origin 的请求都刷新 lastSeen,否则 45s 后误判扩展掉线;
+            // 无 Origin 的诊断 GET(/health /status)不记心跳,curl 探活不能伪造「扩展在线」
+            if (originTrusted) {
+                lastSeenAt = now();
+            }
+            const finish = (code, body) => {
+                res.statusCode = code;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify(body));
+            };
+            if (req.method === 'GET' && path === '/health') {
+                finish(200, { ok: true, service: 'gotry-session-bridge', protocol: BRIDGE_PROTOCOL });
+                return;
+            }
+            if (req.method === 'GET' && path === '/status') {
+                finish(200, {
+                    ok: true, protocol: BRIDGE_PROTOCOL, ...stats(),
+                    extensionConnected: extensionConnected(),
+                    ...(statusExtra ? statusExtra() : {}),
+                });
+                return;
+            }
+            if (isPost && path === '/jobs') {
+                // 轮询体携带 {extensionVersion, capabilities: SITES 键清单}——按站点 capability
+                // 路由(见 ParkedPoller 注);体缺失/非 JSON 视为 match-all,向前兼容旧扩展。
+                void readBody(req, 64 * 1024).then((body) => {
+                    const pollerCaps = (() => {
+                        if (typeof body !== 'string')
+                            return null;
+                        try {
+                            const parsed = JSON.parse(body);
+                            return Array.isArray(parsed.capabilities) ? new Set(parsed.capabilities.filter((c) => typeof c === 'string')) : null;
+                        }
+                        catch {
+                            return null;
+                        }
+                    })();
+                    const next = takeMatching(pollerCaps);
+                    if (next) {
+                        finish(200, { job: next.job });
+                        return;
+                    }
+                    // 长轮询:hold ≤ JOBS_LONG_POLL_MS(必须 < MV3 SW 30s 存活窗口,每次响应都续命);
+                    // 新 job 提交时即时唤醒 parked 取活者(见 dispatchToParked)
+                    const poller = { res, timer: null, capabilities: pollerCaps };
+                    const parkTimer = setTimeout(() => {
+                        const i = parked.findIndex((p) => p.res === res);
+                        if (i >= 0)
+                            parked.splice(i, 1);
+                        finish(200, { job: null });
+                    }, JOBS_LONG_POLL_MS);
+                    poller.timer = parkTimer;
+                    // 默认桥是惰性能力:外部扩展的 parked 轮询不得在主流程结束后钉住 CLI。
+                    // keepBridge wizard 反过来要靠它守住进程,因此只对默认形态 unref。
+                    if (!opts.keepBridge)
+                        parkTimer.unref();
+                    parked.push(poller);
+                    res.on('close', () => {
+                        const i = parked.findIndex((p) => p.res === res);
+                        if (i >= 0)
+                            parked.splice(i, 1);
+                        clearTimeout(parkTimer);
+                    });
+                });
+                return;
+            }
+            const isResults = isPost && (resultsViaQuery ? path === '/results' : path.startsWith('/results/'));
+            if (isResults) {
+                const jobId = resultsViaQuery
+                    ? new URL(req.url ?? '', 'http://bridge.local').searchParams.get('jobId') ?? ''
+                    : decodeURIComponent(path.slice('/results/'.length));
+                if (!jobId) {
+                    finish(400, { ok: false, error: '缺 jobId' });
+                    return;
+                }
+                void readBody(req, MAX_RESULT_BODY_BYTES).then((body) => {
+                    if (typeof body !== 'string') {
+                        finish(400, { ok: false, error: body.err });
+                        return;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(body);
+                    }
+                    catch {
+                        finish(400, { ok: false, error: '回包不是 JSON' });
+                        return;
+                    }
+                    finish(200, { ok: true });
+                    resolveJob(jobId, parsed);
+                });
+                return;
+            }
+            finish(404, { ok: false, error: 'unknown endpoint' });
+        };
+    }
+    const queueHandle = {
         port: 0,
         extensionConnected,
-        submit (job, submitOpts = {}) {
+        stats,
+        handleRequest: makeHandler('', false),
+        handleMountedRequest: makeHandler('/v1/session/bridge', true),
+        submit(job, submitOpts = {}) {
             const extensionWaitMs = submitOpts.extensionWaitMs ?? DEFAULT_EXTENSION_WAIT_MS;
             const timeoutMs = submitOpts.timeoutMs ?? job.timeoutMs ?? 30_000;
-            const full = {
-                jobId: randomUUID(),
-                ...job
-            };
-            return new Promise((resolve)=>{
+            const full = { jobId: randomUUID(), ...job };
+            return new Promise((resolve) => {
                 if (closed) {
-                    resolve({
-                        ok: false,
-                        reason: 'bridge-unavailable',
-                        summary: '扩展桥已关闭'
-                    });
+                    resolve({ ok: false, reason: 'bridge-unavailable', summary: '扩展桥已关闭' });
                     return;
                 }
-                const entry = {
-                    job: full,
-                    resolve: null,
-                    timer: null
-                };
-                const settle = (outcome)=>{
-                    if (entry.timer) clearTimeout(entry.timer);
-                    const i = queue.findIndex((q)=>q.job.jobId === full.jobId);
-                    if (i >= 0) queue.splice(i, 1);
+                const entry = { job: full, resolve: null, timer: null };
+                const settle = (outcome) => {
+                    if (entry.timer)
+                        clearTimeout(entry.timer);
+                    const i = queue.findIndex((q) => q.job.jobId === full.jobId);
+                    if (i >= 0)
+                        queue.splice(i, 1);
                     inFlight.delete(full.jobId);
                     resolve(outcome);
                 };
                 entry.resolve = settle;
-                entry.timer = setTimeout(()=>{
-                    settle({
-                        ok: false,
-                        reason: 'timeout',
-                        summary: `扩展未在 ${timeoutMs}ms 内回包(标签页无嗅探命中或扩展已停用)`
-                    });
+                entry.timer = setTimeout(() => {
+                    settle({ ok: false, reason: 'timeout', summary: `扩展未在 ${timeoutMs}ms 内回包(标签页无嗅探命中或扩展已停用)` });
                 }, timeoutMs);
-                if (!dispatchToParked(entry)) queue.push(entry);
+                if (!dispatchToParked(entry))
+                    queue.push(entry);
+                // 扩展未上线:有界等待(桥刚拉起时扩展 ≤5s 即连上);宽限过仍无 → 立即 no-spend 失败,不空耗
                 let waited = 0;
-                const waitTimer = setInterval(()=>{
+                const waitTimer = setInterval(() => {
                     waited += 250;
-                    if (bridge.extensionConnected()) {
+                    if (queueHandle.extensionConnected()) {
                         clearInterval(waitTimer);
                         return;
                     }
@@ -280,92 +326,107 @@ export async function createSessionBridge(opts = {}) {
                         settle({
                             ok: false,
                             reason: 'extension-not-connected',
-                            summary: needsExtensionSummary()
+                            // D-24 自适应文案(issue #117):按本地通道是否落位决定是否提及开发者模式
+                            summary: needsExtensionSummary(),
                         });
                     }
                 }, 250);
             });
         },
-        close: ()=>new Promise((resolve)=>{
-                closed = true;
-                const voided = {
-                    ok: false,
-                    reason: 'bridge-unavailable',
-                    summary: '扩展桥关闭,任务作废(零花费)'
-                };
-                for (const q of queue.splice(0)){
-                    if (q.timer) clearTimeout(q.timer);
-                    q.resolve(voided);
-                }
-                for (const [, q] of inFlight){
-                    if (q.timer) clearTimeout(q.timer);
-                    q.resolve(voided);
-                }
-                inFlight.clear();
-                for (const p of parked.splice(0)){
-                    clearTimeout(p.timer);
-                    p.res.destroy();
-                }
-                server.close(()=>resolve());
+        close: () => new Promise((resolve) => {
+            closed = true;
+            const voided = { ok: false, reason: 'bridge-unavailable', summary: '扩展桥关闭,任务作废(零花费)' };
+            for (const q of queue.splice(0)) {
+                if (q.timer)
+                    clearTimeout(q.timer);
+                q.resolve(voided);
+            }
+            for (const [, q] of inFlight) {
+                if (q.timer)
+                    clearTimeout(q.timer);
+                q.resolve(voided);
+            }
+            inFlight.clear();
+            for (const p of parked.splice(0)) {
+                clearTimeout(p.timer);
+                p.res.destroy();
+            }
+            resolve();
+        }),
+    };
+    return queueHandle;
+}
+/** 创 Bridge 服务(测试可直接调;生产走 getOrCreateSessionBridge 懒单例) */
+export async function createSessionBridge(opts = {}) {
+    const ports = opts.ports ?? [...BRIDGE_PORTS];
+    const queueHandle = createBridgeJobQueue(opts);
+    let port = 0;
+    const server = createServer((req, res) => queueHandle.handleRequest(req, res));
+    server.on('connection', (socket) => {
+        // server.unref() 只解开监听器;已接受的扩展长轮询 socket 仍会引用事件循环。
+        if (!opts.keepBridge)
+            socket.unref();
+    });
+    const bridge = {
+        port: 0,
+        extensionConnected: queueHandle.extensionConnected,
+        submit: (job, submitOpts) => queueHandle.submit(job, submitOpts),
+        close: () => new Promise((resolve) => {
+            void queueHandle.close().then(() => {
+                server.close(() => resolve());
                 server.closeAllConnections?.();
-            })
+            });
+        }),
     };
-    const listenAt = (p)=>new Promise((resolve, reject)=>{
-            const onError = (e)=>{
-                server.off('listening', onListening);
-                reject(e);
-            };
-            const onListening = ()=>{
-                server.off('error', onError);
-                resolve();
-            };
-            server.once('error', onError);
-            server.once('listening', onListening);
-            server.listen(p, '127.0.0.1');
-        });
-    for (const p of ports){
+    const listenAt = (p) => new Promise((resolve, reject) => {
+        const onError = (e) => { server.off('listening', onListening); reject(e); };
+        const onListening = () => { server.off('error', onError); resolve(); };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(p, '127.0.0.1');
+    });
+    for (const p of ports) {
         try {
             await listenAt(p);
             if (!opts.keepBridge) {
+                // 桥是后台服务:不得钉住事件循环——否则任何跑完主流程的宿主进程(如 smoke/CI)无法退出
                 server.unref();
             }
+            // keepBridge 模式下:wizard 期间要持续监听扩展心跳(30s 周期),
+            // 不 unref 让 server 钉事件循环,wizard main 退时再显式 close 释放。
             port = server.address().port;
             bridge.port = port;
-            return {
-                ok: true,
-                bridge
-            };
-        } catch  {}
+            return { ok: true, bridge };
+        }
+        catch {
+            // 端口被占(如另一个 gotry 实例)——试端口池下一个
+        }
     }
+    await queueHandle.close().catch(() => { });
     return {
         ok: false,
-        summary: `扩展桥端口池 ${ports.join('/')} 全部被占(多为并行 gotry 实例);不影响官方通道 gotry_flyai_search。关闭多余实例后重试。`
+        summary: `扩展桥端口池 ${ports.join('/')} 全部被占(多为并行 gotry 实例);不影响官方通道 gotry_flyai_search。关闭多余实例后重试。`,
     };
 }
+/* ---------- 生产懒单例(进程内随 dsh 存活;失败可重试) ---------- */
 let singleton = null;
 export async function getOrCreateSessionBridge(opts = {}) {
-    if (singleton) return singleton;
+    if (singleton)
+        return singleton;
     const created = await createSessionBridge(opts);
-    const result = created.ok ? {
-        ok: true,
-        bridge: created.bridge
-    } : {
-        ok: false,
-        summary: created.summary
-    };
+    const result = created.ok
+        ? { ok: true, bridge: created.bridge }
+        : { ok: false, summary: created.summary };
     singleton = result;
     return result;
 }
+/** 测试隔离:丢弃单例(端口是进程内资源,close 后端口池立即可复用) */
 export async function __resetSessionBridgeForTest() {
-    if (singleton?.ok) await singleton.bridge.close().catch(()=>{});
+    if (singleton?.ok)
+        await singleton.bridge.close().catch(() => { });
     singleton = null;
 }
+/** 测试注入:以临时端口的桥替换单例(channel 层测试不碰真实端口池) */
 export function __setSessionBridgeForTest(bridge) {
-    singleton = bridge ? {
-        ok: true,
-        bridge
-    } : null;
+    singleton = bridge ? { ok: true, bridge } : null;
 }
-
-
-//# sourceURL=ts/capabilities/session/extension-bridge.ts