rdsh-gateway 0.8.5 → 0.9.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { SessionPayload } from "./session.ts";
 export { PairManager } from "./pair.ts";
 export { startGateway } from "./server.ts";
 export type { GatewayOptions, RunningGateway } from "./server.ts";
-export { findDsh, spawnDsh, exchangeDshSessionCookie, detectDshVersion, compareDshVersions, dshVersionWarning, DSH_COMPAT_MIN, DSH_COMPAT_MAX } from "./spawn-dsh.ts";
+export { findDsh, spawnDsh, dshSpawnEnv, RDSH_REMOTE_TTY, checkRemotePickerGraph, remotePickerWarning, exchangeDshSessionCookie, detectDshVersion, compareDshVersions, dshVersionWarning, DSH_COMPAT_MIN, DSH_COMPAT_MAX } from "./spawn-dsh.ts";
 export type { SpawnedDsh } from "./spawn-dsh.ts";
 export { forwardHttp, createUpgradeProxy, rewriteHeadersForDsh } from "./proxy.ts";
 export type { ProxyTarget } from "./proxy.ts";
@@ -21,7 +21,7 @@ export { ipInCidrs, parseCidr, ipToInt } from "./cidr.ts";
 export { loadTls } from "./tls.ts";
 export type { TlsMaterial } from "./tls.ts";
 export { loginPageHtml } from "./login-page.ts";
-export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.ts";
+export { installService, uninstallService, serviceStatus, startService, stopService, restartService, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.ts";
 export type { ServiceSpec } from "./service.ts";
 export declare const NAME = "rdsh-gateway";
 export { join, startJoin, registerJoin, detectInsecure, selfRevoke, patchLoopbackJs } from "./join.ts";

package/dist/index.js

@@ -7,14 +7,14 @@ export { serve } from "./serve.js";
 export { SessionManager, SESSION_COOKIE, sessionTokenFromCookie } from "./session.js";
 export { PairManager } from "./pair.js";
 export { startGateway } from "./server.js";
-export { findDsh, spawnDsh, exchangeDshSessionCookie, detectDshVersion, compareDshVersions, dshVersionWarning, DSH_COMPAT_MIN, DSH_COMPAT_MAX } from "./spawn-dsh.js";
+export { findDsh, spawnDsh, dshSpawnEnv, RDSH_REMOTE_TTY, checkRemotePickerGraph, remotePickerWarning, exchangeDshSessionCookie, detectDshVersion, compareDshVersions, dshVersionWarning, DSH_COMPAT_MIN, DSH_COMPAT_MAX } from "./spawn-dsh.js";
 export { forwardHttp, createUpgradeProxy, rewriteHeadersForDsh } from "./proxy.js";
 export { loadConfig, normalizeConfig, resolveConfigPath, saveConfig, DEFAULT_HOST_CONFIG_PATH } from "./config.js";
 export { hashPassword, verifyPassword, UserManager } from "./auth.js";
 export { ipInCidrs, parseCidr, ipToInt } from "./cidr.js";
 export { loadTls } from "./tls.js";
 export { loginPageHtml } from "./login-page.js";
-export { installService, uninstallService, serviceStatus, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.js";
+export { installService, uninstallService, serviceStatus, startService, stopService, restartService, systemdUnit, launchdPlist, SERVICE_NAME, JOIN_SERVICE_NAME, HOST_SERVICE_NAME, HUB_SERVICE_NAME } from "./service.js";
 export const NAME = "rdsh-gateway";
 export { join, startJoin, registerJoin, detectInsecure, selfRevoke, patchLoopbackJs } from "./join.js";
 export { readPersistedToken, clearPersistedToken } from "./token-store.js";

package/dist/join.js

@@ -14,7 +14,7 @@ import { request as httpsRequest } from "node:https";
 import { hostname as osHostname } from "node:os";
 import { WebSocket } from "ws";
 import { FrameParser, FRAME_TYPE, encodeFrame, jsonPayload, parseJsonPayload, FLAG_E2E, MAX_PAYLOAD_LENGTH } from "rdsh-tunnel";
-import { findDsh, spawnDsh, exchangeDshSessionCookie, detectDshVersion, dshVersionWarning } from "./spawn-dsh.js";
+import { findDsh, spawnDsh, exchangeDshSessionCookie, detectDshVersion, dshVersionWarning, checkRemotePickerGraph, remotePickerWarning } from "./spawn-dsh.js";
 import { rewriteHeadersForDsh } from "./proxy.js";
 import { clearPersistedToken, persistToken, readPersistedToken } from "./token-store.js";
 import { decodeBody, encodeBody, firstEncoding } from "./http-encoding.js";
@@ -301,6 +301,14 @@ export function startJoin(opts) {
         const gatedHttp = new Map();
         /** 已报告过"loopback 补丁未命中"的路径（每个路径只报一次，避免日志刷屏）。 */
         const patchMissReported = new Set();
+        /** 已报告过"loopback 补丁命中"的路径（与 miss 对称：只看得到 miss 会让人误判"补丁从未生效"）。 */
+        const patchHitReported = new Set();
+        /**
+         * 已确认**不含**补丁目标串的 URL（键为完整 path，含 query）——命中过一次 miss 后直接走流式，
+         * 不再每次页面加载都缓冲 + 解压 + 全量扫描（DSH 前端壳资源 2 个就 ~1.3 MB）。
+         * 键含 query 且不截断：combo 路由用 query 选内容，资源 URL 由内容决定（rev/hash），内容一变 URL 就变。
+         */
+        const patchSkipped = new Set();
         /** 从转发头里取 rdsh_gate cookie（hub D12 白名单透传）。 */
         function gateCookie(headers) {
             const ck = headers["cookie"];
@@ -474,7 +482,8 @@ export function startJoin(opts) {
                 responded = true;
                 const status = upRes.statusCode ?? 502;
                 const baseHeaders = normalizeRespHeaders(upRes.headers);
-                const wantsPatch = dio?.jsPatch?.() === true && isJsContentType(upRes.headers);
+                // 已确认该 URL 不含目标串（DSH 前端壳资源就属此类）→ 直接流式，省掉白解压与全量扫描
+                const wantsPatch = dio?.jsPatch?.() === true && isJsContentType(upRes.headers) && !patchSkipped.has(path);
                 // 非 JS / 未开补丁：保持原流式路径（OPEN 立即发，body 边到边发）
                 if (!wantsPatch) {
                     send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({ kind: "http", status, reason: upRes.statusMessage, headers: baseHeaders })));
@@ -503,8 +512,11 @@ export function startJoin(opts) {
                     let body = raw;
                     let outHeaders = baseHeaders;
                     let hit = false;
+                    /** 解码成功、且明文里确实**没有**目标串 → 该 URL 可以永久短路（换编码回来也一样没有）。 */
+                    let targetAbsent = false;
                     if (decoded !== null) {
                         const patched = patchLoopbackJs(decoded);
+                        targetAbsent = patched === null;
                         const recoded = patched === null ? null : encodeBody(patched, encoding);
                         if (recoded !== null) {
                             body = recoded;
@@ -516,17 +528,26 @@ export function startJoin(opts) {
                             outHeaders["cache-control"] = "public, max-age=300";
                         }
                     }
-                    // 未命中必须留痕（每个路径一次）：fail-open 是刻意设计，但"补丁从未生效"不能静默
-                    //（2026-09-14 gzip 事故正是因为没有这条日志而排查了很久）
-                    if (!hit) {
-                        const key = (path.split("?")[0] ?? path).slice(0, 120);
-                        if (!patchMissReported.has(key)) {
-                            patchMissReported.add(key);
-                            console.log(`[patch] miss: ${key} (${raw.length}B, content-encoding=${encoding === "" ? "identity" : encoding})`);
+                    // 命中与未命中都必须留痕（每个路径一次）：fail-open 是刻意设计，但"补丁是否生效"不能靠猜。
+                    // 两次误判都源于只看得到一半日志：2026-09-14 gzip 事故（只见 miss）、2026-09-17
+                    // 「补丁在 0.1.5-rc.2 上永不命中」（把前端壳资源的 miss 当成了判据所在的 bundle）。
+                    const logKey = (path.split("?")[0] ?? path).slice(0, 120);
+                    if (hit) {
+                        if (!patchHitReported.has(logKey) || process.env.RDSH_DEBUG_PATCH === "1") {
+                            patchHitReported.add(logKey);
+                            console.log(`[patch] hit: ${logKey} (${raw.length}B → ${body.length}B, ${encoding === "" ? "identity" : encoding})`);
                         }
                     }
-                    else if (process.env.RDSH_DEBUG_PATCH === "1") {
-                        console.log(`[patch] hit: ${path.slice(0, 120)} (${raw.length}B → ${body.length}B, ${encoding === "" ? "identity" : encoding})`);
+                    else {
+                        const firstMiss = !patchMissReported.has(logKey);
+                        patchMissReported.add(logKey);
+                        // 只有"解码后确实没有目标串"才永久短路；编码不支持（decoded === null）时并没看过明文，
+                        // 保持每次尝试（同一 URL 换个编码回来仍能被补丁）；重压失败同理不算。
+                        if (targetAbsent)
+                            patchSkipped.add(path);
+                        if (firstMiss) {
+                            console.log(`[patch] miss: ${logKey} (${raw.length}B, content-encoding=${encoding === "" ? "identity" : encoding}) — fail-open${targetAbsent ? "；此 URL 后续不再尝试补丁" : ""}`);
+                        }
                     }
                     send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({ kind: "http", status, reason: upRes.statusMessage, headers: outHeaders })));
                     sendChunkedBody(send, streamId, body);
@@ -905,6 +926,10 @@ export async function join(opts) {
             console.warn("rdsh join: dsh 0.1.2+ 会话 cookie 换发失败——远程访问将返回 401。");
         }
     }
+    // 自检：目录选择器必须是浏览器内形态（否则远端浏览器只会看到弹在宿主屏幕上的原生对话框）
+    if ((await checkRemotePickerGraph(dsh.port, dshAuthCookieHeader)) === false) {
+        console.warn(`\n⚠  ${remotePickerWarning()}\n`);
+    }
     // 解析 host token（含证书自动检测 + 持久化）；进程重启后复用，避免重复配对。
     const { token, insecure, name } = await registerJoin(opts);
     console.log(`rdsh join: dsh web on 127.0.0.1:${dsh.port}`);

package/dist/proxy.js

@@ -7,6 +7,20 @@
 import { request } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
 import { decodeBody, encodeBody, firstEncoding } from "./http-encoding.js";
+/**
+ * 已知**不含**补丁目标串的 URL（按 patcher 函数身份隔离——目标串由 patcher 决定，只看 URL 会误判）。
+ * 目的与隧道路径（`join.ts` 的 `patchSkipped`）一致：DSH 前端壳资源每次页面加载都被缓冲 + 解压 + 全量扫描，
+ * 而这些字节永远不会命中；记住一次即可一直走流式。
+ */
+const jsPatchMissedUrls = new WeakMap();
+function missedUrlsFor(patcher) {
+    const existing = jsPatchMissedUrls.get(patcher);
+    if (existing !== undefined)
+        return existing;
+    const created = new Set();
+    jsPatchMissedUrls.set(patcher, created);
+    return created;
+}
 /**
  * 重写转发头以通过 DSH 围栏（isTrustedApiRequest 要求 Host/Origin 一致且为 loopback）。
  * - Host → 127.0.0.1:<port>（M1 事实：DSH 只信任 loopback/trusted Host）
@@ -81,7 +95,12 @@ export function forwardHttp(req, res, target, opts) {
             });
             return;
         }
-        const canPatchJs = opts?.jsPatch !== undefined && typeof contentType === "string" && /javascript/i.test(contentType);
+        const patchUrl = req.url ?? "";
+        const patchMissed = opts?.jsPatch === undefined ? undefined : missedUrlsFor(opts.jsPatch);
+        const canPatchJs = opts?.jsPatch !== undefined &&
+            typeof contentType === "string" &&
+            /javascript/i.test(contentType) &&
+            patchMissed?.has(patchUrl) !== true;
         if (canPatchJs) {
             // JS bundle 需缓冲后才能替换目标串；先按 content-encoding 解码（dsh 会 gzip JS），
             // 补丁后按原编码重压（fail-open：未命中/不支持编码 → 原字节原头透传）
@@ -95,6 +114,9 @@ export function forwardHttp(req, res, target, opts) {
                 const patched = decoded === null ? null : opts.jsPatch(decoded);
                 const recoded = patched === null ? null : encodeBody(patched, encoding);
                 const outBody = recoded ?? raw;
+                // 只有"解码后确实没有目标串"才记住该 URL（编码不支持时没看过明文，保持每次尝试）
+                if (patched === null && decoded !== null)
+                    patchMissed?.add(patchUrl);
                 const outHeaders = { ...upstreamRes.headers };
                 if (recoded !== null) {
                     outHeaders["content-length"] = String(outBody.length);

package/dist/serve.js

@@ -3,7 +3,7 @@
  */
 import { networkInterfaces } from "node:os";
 import { startGateway } from "./server.js";
-import { findDsh, spawnDsh, exchangeDshSessionCookie, detectDshVersion, dshVersionWarning } from "./spawn-dsh.js";
+import { findDsh, spawnDsh, exchangeDshSessionCookie, detectDshVersion, dshVersionWarning, checkRemotePickerGraph, remotePickerWarning } from "./spawn-dsh.js";
 import { loadConfig, resolveConfigPath } from "./config.js";
 import { UserManager } from "./auth.js";
 import { loadTls } from "./tls.js";
@@ -39,6 +39,10 @@ export async function serve(opts) {
             console.warn("rdsh: dsh 0.1.2+ 会话 cookie 换发失败——远程访问将返回 401（请确认 dsh web 已就绪或暂用 dsh@0.1.1-rc.2）。");
         }
     }
+    // 自检：目录选择器必须是浏览器内形态（否则远端浏览器只会看到弹在宿主屏幕上的原生对话框）
+    if ((await checkRemotePickerGraph(dsh.port, dshAuthCookieHeader)) === false) {
+        console.warn(`\n⚠  ${remotePickerWarning()}\n`);
+    }
     // TLS 决策：有 tls.cert/key → https；无 → http（behindProxy 或 pair/none）。
     // password + http + 非反代 → server.ts 安全约束拒绝启动（需自行提供证书）。
     const tlsMaterial = await loadTls(config.tls, config.behindProxy);

package/dist/service.d.ts

@@ -30,3 +30,9 @@ export declare function installService(spec: ServiceSpec): Promise<string>;
 export declare function serviceStatus(name?: string): Promise<string>;
 /** 停止并移除服务。 */
 export declare function uninstallService(name?: string): Promise<string>;
+/** 启动服务（运行时控制，不改变开机自启配置）。 */
+export declare function startService(name?: string): Promise<string>;
+/** 停止服务（运行时控制，不改变开机自启配置）。 */
+export declare function stopService(name?: string): Promise<string>;
+/** 重启服务（运行时控制，不改变开机自启配置）。 */
+export declare function restartService(name?: string): Promise<string>;

package/dist/service.js

@@ -158,4 +158,33 @@ export async function uninstallService(name = SERVICE_NAME) {
     await rm(launchdPlistPath(name), { force: true });
     return `removed ${launchdPlistPath(name)}`;
 }
+/** 启动服务（运行时控制，不改变开机自启配置）。 */
+export async function startService(name = SERVICE_NAME) {
+    if (isLinux()) {
+        await run("systemctl", ["--user", "start", name]);
+        return `started ${name}`;
+    }
+    // macOS：kickstart -k 确保在跑（已运行则先停再启）。
+    await run("launchctl", ["kickstart", "-k", `com.${name}`]);
+    return `started com.${name}`;
+}
+/** 停止服务（运行时控制，不改变开机自启配置）。 */
+export async function stopService(name = SERVICE_NAME) {
+    if (isLinux()) {
+        await run("systemctl", ["--user", "stop", name]);
+        return `stopped ${name}`;
+    }
+    // macOS：stop 仅停当前实例；KeepAlive（仅失败退出重启）可能立即拉起 —— 与 systemd stop 语义不同。
+    await run("launchctl", ["stop", `com.${name}`]).catch(() => undefined);
+    return `stopped com.${name}`;
+}
+/** 重启服务（运行时控制，不改变开机自启配置）。 */
+export async function restartService(name = SERVICE_NAME) {
+    if (isLinux()) {
+        await run("systemctl", ["--user", "restart", name]);
+        return `restarted ${name}`;
+    }
+    await run("launchctl", ["kickstart", "-k", `com.${name}`]);
+    return `restarted com.${name}`;
+}
 //# sourceMappingURL=service.js.map

package/dist/spawn-dsh.d.ts

@@ -16,6 +16,27 @@ export interface SpawnedDsh {
  * 找不到返回 null。
  */
 export declare function findDsh(override?: string): string | null;
+/**
+ * 注入给 dsh 的「远端操作者」信号值。用可读字面量而非 `/dev/...`：
+ * 让 `env` 里一眼看出这是 rdsh 注入的，而不是真实终端路径。
+ */
+export declare const RDSH_REMOTE_TTY = "rdsh-remote";
+/**
+ * 构造 spawn dsh 时的环境：保证 dsh 把目录选择器解析为 **browse**（浏览器内目录浏览器）。
+ *
+ * 事实依据（doc/fix/20260917-remote-workspace-picker/discussion.md F2/F4/F8）：
+ * `@deepseek-ai/dsh-host-directory-picker-auto` 在 boot 时读 `SSH_CONNECTION`/`SSH_TTY`
+ * （仅继承进程层，非空即可）——「操作者看不到宿主显示」正是 rdsh 的场景（等价于
+ * SSH 端口转发下的无人值守宿主）。不注入它，宿主是 macOS/Windows/带 DISPLAY 的 Linux
+ * 时会解析成 `native`，原生对话框弹在宿主屏幕上、远端浏览器无法操作。
+ *
+ * 只设 `SSH_TTY`：`SSH_CONNECTION` 有固定 `"ip port ip port"` 格式，写假值会误导解析它的工具。
+ * 用户真的在 SSH 会话里启动时（已有非空信号）保持原值不动。
+ *
+ * ⚠️ 这是上游启发式的输入：上游若改变判定信号，本注入会静默失效（spawn 后自检见
+ * `checkRemotePickerGraph` 与 doc/fix/20260917-remote-workspace-picker/solution.md §6）。
+ */
+export declare function dshSpawnEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
  * spawn `dsh web --port 0 --no-open` 并等待其报告监听端口。
  * 就绪后把 dsh 的 stdout/stderr 透传到本进程。
@@ -29,6 +50,22 @@ export declare function spawnDsh(dshPath: string): Promise<SpawnedDsh>;
  * 返回 cookie 的 `name=value` 段（不含属性）；换发失败/超时/无 cookie → null（调用方降级）。
  */
 export declare function exchangeDshSessionCookie(port: number, token: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * 自检：spawn 出的 dsh 是否真的把目录选择器解析成了 **browse**。
+ *
+ * 方法（与 doc/fix/20260917-remote-workspace-picker 的验证手段一致）：取一次首页，
+ * 在注入的 boot graph 里找浏览器内选择器的客户端模块 —— 在 → 远端浏览器可用；
+ * 不在 → 选择器是 `native`（原生对话框弹在宿主屏幕上）。
+ *
+ * @returns `true`（已挂载 browse）/ `false`（确认未挂载）/ `null`（无法判定：网络、鉴权、超限）
+ * 只有 `false` 才值得告警；`null` 静默，避免噪声。
+ */
+export declare function checkRemotePickerGraph(port: number, cookieHeader?: string | null, timeoutMs?: number): Promise<boolean | null>;
+/**
+ * 自检失败（确认未挂载浏览器内选择器）时的告警文案。
+ * 零文档导向：说清后果 + 直接给动作。
+ */
+export declare function remotePickerWarning(): string;
 /** 探测 dsh 版本号（`dsh --version` 输出如 `0.1.2-rc.1`）；失败/不可解析 → null。 */
 export declare function detectDshVersion(dshPath: string, timeoutMs?: number): Promise<string | null>;
 /**

package/dist/spawn-dsh.js

@@ -42,6 +42,32 @@ export function findDsh(override) {
     }
     return null;
 }
+/**
+ * 注入给 dsh 的「远端操作者」信号值。用可读字面量而非 `/dev/...`：
+ * 让 `env` 里一眼看出这是 rdsh 注入的，而不是真实终端路径。
+ */
+export const RDSH_REMOTE_TTY = "rdsh-remote";
+/**
+ * 构造 spawn dsh 时的环境：保证 dsh 把目录选择器解析为 **browse**（浏览器内目录浏览器）。
+ *
+ * 事实依据（doc/fix/20260917-remote-workspace-picker/discussion.md F2/F4/F8）：
+ * `@deepseek-ai/dsh-host-directory-picker-auto` 在 boot 时读 `SSH_CONNECTION`/`SSH_TTY`
+ * （仅继承进程层，非空即可）——「操作者看不到宿主显示」正是 rdsh 的场景（等价于
+ * SSH 端口转发下的无人值守宿主）。不注入它，宿主是 macOS/Windows/带 DISPLAY 的 Linux
+ * 时会解析成 `native`，原生对话框弹在宿主屏幕上、远端浏览器无法操作。
+ *
+ * 只设 `SSH_TTY`：`SSH_CONNECTION` 有固定 `"ip port ip port"` 格式，写假值会误导解析它的工具。
+ * 用户真的在 SSH 会话里启动时（已有非空信号）保持原值不动。
+ *
+ * ⚠️ 这是上游启发式的输入：上游若改变判定信号，本注入会静默失效（spawn 后自检见
+ * `checkRemotePickerGraph` 与 doc/fix/20260917-remote-workspace-picker/solution.md §6）。
+ */
+export function dshSpawnEnv(base = process.env) {
+    const hasSignal = (base.SSH_TTY ?? "") !== "" || (base.SSH_CONNECTION ?? "") !== "";
+    if (hasSignal)
+        return { ...base };
+    return { ...base, SSH_TTY: RDSH_REMOTE_TTY };
+}
 /**
  * spawn `dsh web --port 0 --no-open` 并等待其报告监听端口。
  * 就绪后把 dsh 的 stdout/stderr 透传到本进程。
@@ -51,6 +77,7 @@ export function spawnDsh(dshPath) {
     return new Promise((resolve, reject) => {
         const child = spawn(dshPath, ["web", "--port", "0", "--no-open"], {
             stdio: ["ignore", "pipe", "pipe"],
+            env: dshSpawnEnv(),
         });
         let stderrBuf = "";
         const timeout = setTimeout(() => {
@@ -124,6 +151,66 @@ export function exchangeDshSessionCookie(port, token, timeoutMs = EXCHANGE_TIMEO
         });
     });
 }
+const GRAPH_CHECK_TIMEOUT_MS = 5_000;
+const MAX_GRAPH_BYTES = 512 * 1024;
+/** boot graph 里浏览器内目录选择器的客户端模块标识（命中即说明 picker = browse）。 */
+const BROWSE_PICKER_MODULE = "@deepseek-ai/dsh-client-ui-directory-picker-browse";
+/**
+ * 自检：spawn 出的 dsh 是否真的把目录选择器解析成了 **browse**。
+ *
+ * 方法（与 doc/fix/20260917-remote-workspace-picker 的验证手段一致）：取一次首页，
+ * 在注入的 boot graph 里找浏览器内选择器的客户端模块 —— 在 → 远端浏览器可用；
+ * 不在 → 选择器是 `native`（原生对话框弹在宿主屏幕上）。
+ *
+ * @returns `true`（已挂载 browse）/ `false`（确认未挂载）/ `null`（无法判定：网络、鉴权、超限）
+ * 只有 `false` 才值得告警；`null` 静默，避免噪声。
+ */
+export function checkRemotePickerGraph(port, cookieHeader = null, timeoutMs = GRAPH_CHECK_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const headers = { Host: `127.0.0.1:${port}` };
+        if (cookieHeader !== null)
+            headers.Cookie = cookieHeader;
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        const req = get({ host: "127.0.0.1", port, path: "/", headers }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                finish(null);
+                return;
+            }
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                body += chunk;
+                if (body.length > MAX_GRAPH_BYTES) {
+                    req.destroy();
+                    finish(null);
+                }
+            });
+            res.on("end", () => finish(body.includes(BROWSE_PICKER_MODULE)));
+            res.on("error", () => finish(null));
+        });
+        req.on("error", () => finish(null));
+        req.setTimeout(timeoutMs, () => {
+            req.destroy();
+            finish(null);
+        });
+    });
+}
+/**
+ * 自检失败（确认未挂载浏览器内选择器）时的告警文案。
+ * 零文档导向：说清后果 + 直接给动作。
+ */
+export function remotePickerWarning() {
+    return ("rdsh: 远端浏览器的目录选择器不是浏览器内目录浏览器（很可能是宿主原生对话框，远端无法操作）。" +
+        "若装了 dsh-web-remote 插件，请检查 profile 的 cordis.patch.yml 是否被其它 patch 层覆盖（目录选择器只允许一个 pin 通道）。" +
+        "否则可能是 dsh 版本变更导致远端信号失效——升级 remote-dsh：npm i -g remote-dsh@latest。");
+}
 /** 探测 dsh 版本号（`dsh --version` 输出如 `0.1.2-rc.1`）；失败/不可解析 → null。 */
 export function detectDshVersion(dshPath, timeoutMs = VERSION_TIMEOUT_MS) {
     return new Promise((resolve) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdsh-gateway",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "rdsh host-side component: LAN auth gateway + outbound tunnel endpoint (spawns dsh web)",
   "license": "MIT",
   "type": "module",