rdsh-gateway 0.8.4 → 0.8.6

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";

package/dist/index.js

@@ -7,7 +7,7 @@ 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";

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";
@@ -260,8 +260,22 @@ export function startJoin(opts) {
     };
     const lock = acquireJoinLock(opts.role, opts.lockPath);
     if (!lock.ok) {
-        throw new Error(`join lock held by ${lock.heldBy.role} (pid ${lock.heldBy.pid}); stop it first`);
+        // 「同机单隧道」铁律：任何活锁都拒绝（含本进程自己的 pid —— 那是热重载时的同进程重复获取）
+        throw new Error("contended" in lock
+            ? "join lock is contended by another instance; retry"
+            : lock.heldBy.pid === process.pid
+                ? "another tunnel is already running in this process"
+                : `join lock held by ${lock.heldBy.role} (pid ${lock.heldBy.pid}); stop it first`);
     }
+    /**
+     * 构造期同步抛错必须把锁还回去（否则本进程再也起不来隧道，还谎报「本进程已有隧道」）。
+     * 现实抛点：E2EE 密钥生成/序列化（`loadOrCreateE2eeKeyPair`）与 `connect()` 里的
+     * `new WebSocket(非法 URL)`、以及 embedder 的 onState 钩子。
+     */
+    const releaseLockAndRethrow = (err) => {
+        releaseJoinLock(opts.lockPath);
+        throw err;
+    };
     const parser = new FrameParser();
     let shuttingDown = false;
     let reconnectDelay = RECONNECT_BASE_MS;
@@ -603,7 +617,13 @@ export function startJoin(opts) {
     }
     const plainDispatcher = makeInnerDispatcher(sendTunnelFrame, { jsPatch: () => uiCompat.trustE2EEAsLoopback, gate: true });
     // host 端 E2EE 静态密钥对（持久化 ~/.rdsh/e2ee-key.json；join 注册时上送指纹）
-    const hostE2eeKeypair = loadOrCreateE2eeKeyPair();
+    let hostE2eeKeypair;
+    try {
+        hostE2eeKeypair = loadOrCreateE2eeKeyPair();
+    }
+    catch (err) {
+        releaseLockAndRethrow(err);
+    }
     const rawStreams = new Map();
     function startRawStream(streamId) {
         const inner = makeInnerDispatcher((frame) => {
@@ -733,7 +753,6 @@ export function startJoin(opts) {
         const url = `${hubWsBase}/tunnel`;
         const client = new WebSocket(url, { headers: { authorization: `Bearer ${opts.token}` }, rejectUnauthorized: !opts.insecure });
         currentClient = client;
-        setState("connecting", { message: `connecting to ${opts.hubUrl}` });
         // 401/403 = token 被拒（吊销/不存在）。监听此事件后 ws 不再自动 abort，
         // 需手动 terminate → 触发 close → 决定「重配对」还是「普通重连」。
         let tokenRejected = false;
@@ -826,8 +845,16 @@ export function startJoin(opts) {
                 /* 已关闭 */
             }
         });
+        // 状态回调放在所有监听器挂好**之后**：embedder 的 onState 若抛错，异常会向上抛并被
+        // releaseLockAndRethrow 处理；此时 socket 已有 error 监听，不会因后续连接失败变成未捕获 error 崩进程。
+        setState("connecting", { message: `connecting to ${opts.hubUrl}` });
+    }
+    try {
+        connect();
+    }
+    catch (err) {
+        releaseLockAndRethrow(err);
     }
-    connect();
     return {
         setUiCompat(trustE2EEAsLoopback) {
             uiCompat.trustE2EEAsLoopback = trustE2EEAsLoopback;
@@ -878,6 +905,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/lock.d.ts

@@ -5,8 +5,11 @@ export interface JoinLock {
     role: JoinLockRole;
 }
 /**
- * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 读锁（**纯读，无副作用**）：不存在 / 损坏 / pid 已死（stale）→ null。
  * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ *
+ * 注意：不再顺手删除 stale 文件（旧实现有此行为且无二次校验，会误删他人新锁）；
+ * 清理统一由 acquire 路径的 `reapDeadLock()` 以 compare-and-delete 完成。
  */
 export declare function readJoinLock(path?: string): JoinLock | null;
 export type AcquireResult = {
@@ -14,11 +17,21 @@ export type AcquireResult = {
 } | {
     ok: false;
     heldBy: JoinLock;
+}
+/** 连续被抢占（拿不到也读不到持有者，极罕见）：不伪造持有者，由调用方给出「被占用」提示。 */
+ | {
+    ok: false;
+    contended: true;
 };
 /**
- * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
- * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ * 获取锁：**原子发布**锁文件（临时文件 + `link`；目录 0700、文件 0600），内容 `{pid, role}`。
+ *
+ * - 已有活锁（**无论 pid 是否为自己**）→ 拒绝，防同机 / 同进程双隧道；
+ * - stale（pid 已死）或损坏残锁 → compare-and-delete 清除后重试；
+ * - 文件系统不支持硬链接 → 退回 `wx` 创建（旧实现在这些文件系统上就是这个行为，
+ *   短暂的"空文件窗口"由 `reapDeadLock` 的新鲜度保护兜住）；
+ * - 连续 3 次被抢占 → `{ok:false, contended:true}`。
  */
 export declare function acquireJoinLock(role: JoinLockRole, path?: string): AcquireResult;
-/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）；同时清本进程记账。 */
 export declare function releaseJoinLock(path?: string): void;

package/dist/lock.js

@@ -1,10 +1,18 @@
 /**
  * lock.ts — join pid 锁：CLI 与插件共享「单身份铁律」（同机单隧道，D5 档2）。
  *
- * 锁文件 `~/.rdsh/join.lock`（0600）记 `{pid, role}`；stale（pid 已死）自动视为无锁并清除。
+ * 锁文件 `~/.rdsh/join.lock`（0600）记 `{pid, role}`。
  * role = "cli"（rdsh CLI / systemd 服务持有）| "plugin"（dsh 插件持有）——面板据此显示「外部托管」。
+ *
+ * 三条不变量（2026-09-15 真机复盘：多个 `dsh web` 实例互相顶替导致面板反复掉线/连线）：
+ *   1. **原子发布**「文件 + 内容」：先写临时文件再 `link` —— 锁路径要么不存在、要么内容完整，
+ *      不存在「已存在但内容为空」的窗口（旧实现 `writeFileSync(..., {flag:"wx"})` 有这个窗口，
+ *      会被并发清理者当成坏锁删掉，两边都以为自己持锁）；
+ *   2. **拒绝任何活锁**（包括本进程自己的 pid）：同进程重复获取由 `heldPaths` 记账拦住；
+ *   3. **清理只走 compare-and-delete**：读 → 判断 → 删除之间不得误删他人刚发布的锁
+ *      （旧实现 `readJoinLock` 读到 stale 就无条件 `rmSync`，会删掉别人刚建立的新锁）。
  */
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, linkSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 const RDSH_DIR = join(homedir(), ".rdsh");
@@ -19,47 +27,144 @@ function isAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/** 解析锁内容；损坏/字段非法 → null。纯函数，不碰文件系统。 */
+function parseLock(raw) {
+    try {
+        const j = JSON.parse(raw);
+        if (typeof j.pid !== "number" || (j.role !== "cli" && j.role !== "plugin"))
+            return null;
+        return { pid: j.pid, role: j.role };
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 读锁（**纯读，无副作用**）：不存在 / 损坏 / pid 已死（stale）→ null。
  * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ *
+ * 注意：不再顺手删除 stale 文件（旧实现有此行为且无二次校验，会误删他人新锁）；
+ * 清理统一由 acquire 路径的 `reapDeadLock()` 以 compare-and-delete 完成。
  */
 export function readJoinLock(path = JOIN_LOCK_PATH) {
     try {
         if (!existsSync(path))
             return null;
-        const raw = JSON.parse(readFileSync(path, "utf8"));
-        if (typeof raw.pid !== "number" || (raw.role !== "cli" && raw.role !== "plugin"))
+        const held = parseLock(readFileSync(path, "utf8"));
+        if (held === null)
             return null;
-        if (!isAlive(raw.pid)) {
-            try {
-                rmSync(path, { force: true });
-            }
-            catch {
-                /* 忽略 */
-            }
-            return null;
-        }
-        return { pid: raw.pid, role: raw.role };
+        return isAlive(held.pid) ? held : null;
     }
     catch {
         return null;
     }
 }
+function snapshotLock(path) {
+    try {
+        const st = statSync(path);
+        return { raw: readFileSync(path, "utf8"), ino: st.ino, mtimeMs: st.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+/** 内容解析不出来的锁文件，多新以内视为"并发创建者写到一半"而不回收。 */
+const FRESH_LOCK_MS = 1000;
+/**
+ * 清除「确定已经死了」的残锁（pid 已死，或内容损坏且已不新），成功则锁路径变空、可重试获取。
+ *
+ * 两道保护，避免把别人的**活锁**删掉：
+ * 1. compare-and-delete 比对**内容 + inode**（同内容但换了 inode = 别人刚发布的新锁，不删）；
+ * 2. 内容解析不出来（空/半截）且文件很新 → 视为并发创建者写到一半，不删
+ *    （本实现的发布是原子的，这种文件只可能来自旧版本或外部写入者）。
+ */
+function reapDeadLock(path) {
+    const first = snapshotLock(path);
+    if (first === null)
+        return;
+    const held = parseLock(first.raw);
+    if (held !== null && isAlive(held.pid))
+        return; // 有效活锁
+    if (held === null && Date.now() - first.mtimeMs < FRESH_LOCK_MS)
+        return; // 可能是写到一半
+    const second = snapshotLock(path);
+    if (second === null || second.ino !== first.ino || second.raw !== first.raw)
+        return; // 期间被替换
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        /* 忽略 */
+    }
+}
+/**
+ * 本进程已持有的锁路径。pid 无法区分同进程的两次获取，必须单独记账。
+ *
+ * 必要性：插件热重载（`patchReload: "live"`）时同一进程先后起两条隧道 —— 若只按 pid 判断，
+ * 「锁是自己」会被放行（旧实现正是如此）→ 同机双隧道 → 与 hub 的顶替逻辑叠加成无限互踢。
+ */
+const heldPaths = new Set();
+/** 文件系统不支持硬链接时 `linkSync` 的 errno（SMB / FUSE / exFAT 之类）。 */
+const LINK_UNSUPPORTED = new Set(["EPERM", "ENOSYS", "ENOTSUP", "EOPNOTSUPP"]);
 /**
- * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
- * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ * 获取锁：**原子发布**锁文件（临时文件 + `link`；目录 0700、文件 0600），内容 `{pid, role}`。
+ *
+ * - 已有活锁（**无论 pid 是否为自己**）→ 拒绝，防同机 / 同进程双隧道；
+ * - stale（pid 已死）或损坏残锁 → compare-and-delete 清除后重试；
+ * - 文件系统不支持硬链接 → 退回 `wx` 创建（旧实现在这些文件系统上就是这个行为，
+ *   短暂的"空文件窗口"由 `reapDeadLock` 的新鲜度保护兜住）；
+ * - 连续 3 次被抢占 → `{ok:false, contended:true}`。
  */
 export function acquireJoinLock(role, path = JOIN_LOCK_PATH) {
-    const held = readJoinLock(path);
-    if (held !== null && held.pid !== process.pid) {
-        return { ok: false, heldBy: held };
+    if (heldPaths.has(path)) {
+        return { ok: false, heldBy: { pid: process.pid, role } };
+    }
+    const data = JSON.stringify({ pid: process.pid, role });
+    const tmp = `${path}.${process.pid}.tmp`;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            // 内容先落到临时文件（默认 flag 覆盖写，不会 EEXIST），再 link 到锁路径；
+            // link 是原子的：目标已存在则 EEXIST，且目标**一出现就带完整内容**。
+            writeFileSync(tmp, data, { mode: 0o600 });
+            linkSync(tmp, path);
+            heldPaths.add(path);
+            return { ok: true };
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST") {
+                if (!LINK_UNSUPPORTED.has(code ?? ""))
+                    throw err;
+                try {
+                    writeFileSync(path, data, { flag: "wx", mode: 0o600 });
+                    heldPaths.add(path);
+                    return { ok: true };
+                }
+                catch (err2) {
+                    if (err2.code !== "EEXIST")
+                        throw err2;
+                }
+            }
+        }
+        finally {
+            try {
+                rmSync(tmp, { force: true }); // 删掉临时名，锁路径（硬链接）不受影响
+            }
+            catch {
+                /* 忽略 */
+            }
+        }
+        const held = readJoinLock(path);
+        if (held !== null)
+            return { ok: false, heldBy: held };
+        reapDeadLock(path);
     }
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    writeFileSync(path, JSON.stringify({ pid: process.pid, role }), { mode: 0o600 });
-    return { ok: true };
+    return { ok: false, contended: true };
 }
-/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）；同时清本进程记账。 */
 export function releaseJoinLock(path = JOIN_LOCK_PATH) {
+    heldPaths.delete(path);
     try {
         const held = readJoinLock(path);
         if (held !== null && held.pid === process.pid) {

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/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.4",
+  "version": "0.8.6",
   "description": "rdsh host-side component: LAN auth gateway + outbound tunnel endpoint (spawns dsh web)",
   "license": "MIT",
   "type": "module",