dsh-over-ssh 0.1.1 → 0.2.0

package/README.md

@@ -45,11 +45,11 @@ shell:
 
 | 平台 | 字节 | sha256 |
 |---|---|---|
-| linux-amd64 | 4,907,168 | `08998e6f51bc1a3759a966e96263c380f81f4281f2a50b0257b61f12b1341c3b` |
-| linux-arm64 | 4,653,216 | `0e19b3e77590f233093c09a7adc20487d721407bf805a9f879a756c9f03b9a11` |
+| linux-amd64 | 4,927,648 | `4f47307e4927e39972ebad9c2f25b3676e990ff1335b72ee33c3e8ec25a1e2cf` |
+| linux-arm64 | 4,653,216 | `9c1895ca3310a8fe5aed13a281cbdd98fe95928c24848ba58fea509b5f7341e6` |
 
-- 代理版本：`1.7.0-0ae8c02`
-- 源码提交：`0ae8c02`（Go 仓 `dsh-over-ssh-agent` 的这个提交）
+- 代理版本：`0.2.0-2dc1feb`
+- 源码提交：`2dc1feb`（Go 仓 `dsh-over-ssh-agent` 的这个提交）
 - 清单原文：包内 `agents/agent-manifest.json`
 - 核对：`sha256sum agents/<平台>/dsh-over-ssh-agent` 与上表比对；按上面的提交检出 Go 仓后
   `scripts/check.sh` 可重建同样的产物。
@@ -61,7 +61,7 @@ shell:
 - **传输层自研**，不使用核心 `packages/ssh/*` 家族。原因见设计文档 §3.1：官方实现的 `BatchMode=yes` 让密码认证不可能、远端必须预装 Node + helper、`ctx.ssh` 单例、且其 Web 集成需单独实现（preset 的 `isolate` 子树覆盖不到 `agent.ctx`）。
 - **文件按路径路由，进程不路由**：核心 provider 的公开方法收不到 agent/session 身份，因此 fs 用自研路由 provider 支持"本地 + 远端多根"，而 bash/终端保持单一执行世界，远端命令走显式入口。
 - **远端零安装（Tier 1，地板）**：只依赖远端已有的 POSIX 工具（`sh`/`base64`/`stat`/`find`/可选 `git`/`rg`），连上后做一次能力探测并按能力降级。
-- **可选 Go 代理（Tier 2，增强）**：独立仓库 `../dsh-over-ssh-agent`，纯静态单文件（随包产物的体积与摘要以 `agents/agent-manifest.json` 的 `bytes`/`sha256` 为准，交叉编译矩阵见 `../dsh-over-ssh-agent/doc/05-benchmarks/baseline.md`；零第三方依赖），经 ssh stdio 通信（不监听端口），补齐原生监听/索引/长任务/远端 LSP/Landlock 围栏。决策见 `doc/03-decisions/0005-optional-go-remote-agent.md`；代理不可用时一律回退 Tier 1。
+- **可选 Go 代理（Tier 2，增强）**：独立仓库 `../dsh-over-ssh-agent`，纯静态单文件（随包产物的体积与摘要以 `agents/agent-manifest.json` 的 `bytes`/`sha256` 为准，交叉编译矩阵见 `../dsh-over-ssh-agent/doc/05-benchmarks/baseline.md`；第三方依赖 4 个，全部经 ADR-0008 授权），经 ssh 通信（stdio 或常驻 daemon 的 unix socket，**不监听 TCP 端口**），补齐原生监听/索引/长任务/远端 LSP/Landlock 围栏。决策见 `doc/03-decisions/0005-optional-go-remote-agent.md`；代理不可用时一律回退 Tier 1。
   - **默认尝试部署**（2026-10-13 起，审计 0040）：连接的默认传输是 `agent`，首次连接会把代理装到远端 `$HOME/.cache/dsh-over-ssh/dsh-over-ssh-agent`（约 4.7 MiB / 4,907,168 B，以 `agents/agent-manifest.json` 为准，`0700`），失败自动回退 Tier 1。想避开远端写入就显式写 `transport: alias`。
   - **密码认证同样可用**：代理经系统 ssh 启动，而系统 ssh 靠 `SSH_ASKPASS` 助手取密码（秘密只经环境变量传递，不落盘）。此前"密码认证无法用代理"的说法是把本插件硬写 `BatchMode=yes` 误当成了 SSH 的限制。
   - 随包只带 `linux-amd64` 与 `linux-arm64` 两个产物；其它平台的远端会正常降级到 Tier 1。
@@ -71,13 +71,15 @@ shell:
 
 ```
 src/
+  index.ts fs.ts file-references.ts   # 三个 DSH 入口（组合根）
   host/
     domain/        # 纯 TS、零框架依赖、100% 单测覆盖
-    app/           # 应用层用例（依赖抽象）
+    app/           # 应用层用例（根路由、传输服务、状态）
     infra/         # 传输/后端/缓存/持久化实现
     integration/   # 与核心对接：fs provider、fileReferences、tools、Remote API、终端 wrapper
-    client/        # web client 半（React + TS + CSS Modules）
-tests/             # 每个模块一个独立测试文件
+  client/          # web client 半（React + TS + CSS Modules）——与 host/ 是兄弟目录
+  shared/          # 两半共用的纯工具（路由常量、根键等）
+tests/             # 镜像 src/ 的测试树（每模块一个 *.test.ts；根级只留 architecture/config 两个横切用例）
 ```
 
 ## 测试

package/agents/agent-manifest.json

@@ -1,19 +1,19 @@
 {
   "version": 1,
-  "generatedAt": "2026-11-02T16:02:32.695Z",
-  "agentVersion": "1.7.0-0ae8c02",
-  "sourceCommit": "0ae8c02",
+  "generatedAt": "2026-11-04T23:44:48.795Z",
+  "agentVersion": "0.2.0-2dc1feb",
+  "sourceCommit": "2dc1feb",
   "artifacts": [
     {
       "platform": "linux-amd64",
       "path": "linux-amd64/dsh-over-ssh-agent",
-      "sha256": "08998e6f51bc1a3759a966e96263c380f81f4281f2a50b0257b61f12b1341c3b",
-      "bytes": 4907168
+      "sha256": "4f47307e4927e39972ebad9c2f25b3676e990ff1335b72ee33c3e8ec25a1e2cf",
+      "bytes": 4927648
     },
     {
       "platform": "linux-arm64",
       "path": "linux-arm64/dsh-over-ssh-agent",
-      "sha256": "0e19b3e77590f233093c09a7adc20487d721407bf805a9f879a756c9f03b9a11",
+      "sha256": "9c1895ca3310a8fe5aed13a281cbdd98fe95928c24848ba58fea509b5f7341e6",
       "bytes": 4653216
     }
   ]

package/lib/client.js

@@ -43,9 +43,10 @@ var OVER_SSH_DICTS = {
     rootsTitle: "\u8FDC\u7A0B\u5DE5\u4F5C\u533A",
     // 本页只列插件已登记的根、并可移除：「增」在审计 0027 已移到工作区目录流，旧文案的
     // 「在这里增删…」是错的。作用域那句（不会自动出现在会话的目录列表里）是审计 0056 的护栏，保留。
-    rootsDescription: "\u8FD9\u91CC\u53EA\u5217\u51FA\u63D2\u4EF6\u5DF2\u767B\u8BB0\u7684\u6839\uFF0C\u5E76\u53EF\u4EE5\u79FB\u9664\uFF1B\u8981\u6DFB\u52A0\u76EE\u5F55\u8BF7\u5728\u5DE5\u4F5C\u533A\u7684\u76EE\u5F55\u6D41\u91CC\u505A\u3002\u8FD9\u91CC\u767B\u8BB0\u7684\u6839\u4E0D\u4F1A\u81EA\u52A8\u51FA\u73B0\u5728\u4F1A\u8BDD\u7684\u76EE\u5F55\u5217\u8868\u91CC\uFF1A\u4F1A\u8BDD\u8981\u7528\u5B83\uFF0C\u9700\u5728\u4F1A\u8BDD\u91CC\u70B9\u300C\u6DFB\u52A0\u76EE\u5F55\u300D\u3002profile \u91CC\u58F0\u660E\u7684\u6839\u53EA\u8BFB\u663E\u793A\uFF1A\u5220\u6389\u5B83\u91CD\u542F\u540E\u8FD8\u4F1A\u56DE\u6765\u3002",
+    rootsDescription: "\u8FD9\u91CC\u53EA\u5217\u51FA\u63D2\u4EF6\u5DF2\u767B\u8BB0\u7684\u6839\uFF0C\u5E76\u53EF\u4EE5\u79FB\u9664\uFF1B\u8981\u6DFB\u52A0\u76EE\u5F55\u8BF7\u5728\u5DE5\u4F5C\u533A\u7684\u76EE\u5F55\u6D41\u91CC\u505A\u3002\u8FD9\u91CC\u767B\u8BB0\u7684\u6839\u4E0D\u4F1A\u81EA\u52A8\u51FA\u73B0\u5728\u4F1A\u8BDD\u7684\u76EE\u5F55\u5217\u8868\u91CC\uFF1A\u4F1A\u8BDD\u8981\u7528\u5B83\uFF0C\u9700\u5728\u4F1A\u8BDD\u91CC\u70B9\u300C\u6DFB\u52A0\u76EE\u5F55\u300D\u3002\u6A21\u578B\u5DE5\u5177\u53EA\u8BA4\u300C\u843D\u5728\u672C\u4F1A\u8BDD\u5DE5\u4F5C\u533A\u5185\u7684\u6839\u300D\u4E0E\u300C\u951A\u70B9\u5C31\u662F\u672C\u4F1A\u8BDD\u5DE5\u4F5C\u533A\u7684\u8FDC\u7AEF\u6839\u300D\uFF1B\u5176\u4F59\u6839\u5728\u88C5\u5165\u4F1A\u8BDD\u4E4B\u524D\u4F1A\u62A5\u300C\u4F1A\u8BDD\u9694\u79BB\u300D\u3002profile \u91CC\u58F0\u660E\u7684\u6839\u53EA\u8BFB\u663E\u793A\uFF1A\u5220\u6389\u5B83\u91CD\u542F\u540E\u8FD8\u4F1A\u56DE\u6765\u3002",
     rootsAdvancedSummary: "\u9AD8\u7EA7\uFF1A\u6839\u8868\uFF08\u8BCA\u65AD\uFF09",
     rootsAdvancedNote: "\u8FD9\u662F\u63D2\u4EF6\u7684\u6839\u8DEF\u7531\u8868\uFF1A\u6BCF\u6761 = \u4E00\u4E2A\u8FDC\u7AEF\u76EE\u5F55 + \u63D2\u4EF6\u4E3A\u5B83\u5EFA\u7684\u672C\u5730\u951A\u70B9\u76EE\u5F55\u3002\u5220\u6389\u67D0\u6761\u540E\uFF0C\u6B63\u5728\u4F7F\u7528\u8BE5\u951A\u70B9\u7684\u5DE5\u4F5C\u533A\u91CC remote_* \u5DE5\u5177\u4F1A\u7ACB\u523B\u62A5\u300C\u4E0D\u5728\u4EFB\u4F55\u8FDC\u7AEF\u6839\u5185\u300D\uFF1B\u5DE5\u4F5C\u533A\u672C\u8EAB\u4ECD\u5728\u4FA7\u680F\u3002",
+    rootsScopeNoSession: "\u6CA1\u6709\u4F1A\u8BDD\u4F5C\u7528\u57DF\uFF1A\u6A21\u578B\u53EA\u5BF9\u843D\u5728\u4F1A\u8BDD\u5DE5\u4F5C\u533A\u5185\u7684\u6839\u53EF\u8FBE\uFF1B\u5176\u4F59\u9700\u5728\u4F1A\u8BDD\u91CC\u70B9\u300C\u6DFB\u52A0\u76EE\u5F55\u300D",
     rootsEmpty: "\u8FD8\u6CA1\u6709\u914D\u7F6E\u4EFB\u4F55\u6839\u3002",
     rootsPending: "\u6B63\u5728\u4E0E\u5BBF\u4E3B\u901A\u4FE1\u2026",
     rootsAuthPassword: "\u7528\u6237\u540D + \u5BC6\u7801",
@@ -167,7 +168,6 @@ var OVER_SSH_DICTS = {
     rootsImportFailed: "\u5BFC\u5165\u5931\u8D25\uFF1A{message}",
     transferTitle: "\u4F20\u8F93\u8FDB\u5EA6",
     transferDescription: "\u5F53\u524D\u4E0E\u6700\u8FD1\u7684\u4F20\u8F93\uFF1A\u901F\u7387\u3001\u5DF2\u5B8C\u6210\u5B57\u8282\u3001\u5269\u4F59\u65F6\u95F4\u3002\u5931\u8D25\u9879\u7559\u5728\u4E0B\u9762\u3002",
-    remoteFilesHint: "\u8FDC\u7AEF\u6587\u4EF6\u901A\u8FC7\u5BF9\u8BDD\u8BBF\u95EE\uFF1A@ \u8DEF\u5F84\uFF0C\u6216\u8BA9\u6211\u5217\u76EE\u5F55\u3002",
     transferEmpty: "\u5F53\u524D\u6CA1\u6709\u4F20\u8F93\u3002",
     transferLoading: "\u6B63\u5728\u8BFB\u53D6\u4F20\u8F93\u72B6\u6001\u2026",
     transferRefresh: "\u5237\u65B0",
@@ -283,9 +283,10 @@ var OVER_SSH_DICTS = {
     rootsTitle: "Remote workspaces",
     // Same correction as the Chinese copy: this page can only remove rows (adding moved to the workspace
     // directory flow, audit 0027). The scope sentence is the audit-0056 guard and stays.
-    rootsDescription: "This page only lists the roots the plugin has registered, and lets you remove them; to add a directory, use the workspace directory flow. A root registered here does not appear in a session's directory list automatically: to use it, add it from the session first. Roots declared in the profile are read-only here: deleting one would bring it back after a restart.",
+    rootsDescription: "This page only lists the roots the plugin has registered, and lets you remove them; to add a directory, use the workspace directory flow. A root registered here does not appear in a session's directory list automatically: to use it, add it from the session first. The model reaches only roots that fall inside the session workspace (or a remote root whose anchor is that workspace); every other root reports session isolation until a session takes it in. Roots declared in the profile are read-only here: deleting one would bring it back after a restart.",
     rootsAdvancedSummary: "Advanced: root table (diagnostic)",
     rootsAdvancedNote: "This is the plugin's root routing table: each row is a remote directory plus the local anchor directory the plugin created for it. Deleting a row makes the remote_* tools fail immediately in any workspace that already uses that anchor; the workspace itself stays in the sidebar.",
+    rootsScopeNoSession: "No session scope: the model reaches only roots inside the session workspace; add it from the session otherwise",
     rootsEmpty: "No root is configured yet.",
     rootsPending: "Talking to the host\u2026",
     rootsAuthPassword: "Username + password",
@@ -402,7 +403,6 @@ var OVER_SSH_DICTS = {
     rootsImportFailed: "Import failed: {message}",
     transferTitle: "Transfers",
     transferDescription: "Current and recent transfers: rate, bytes done, time left. Failures stay listed below.",
-    remoteFilesHint: "Remote files are reached through the conversation: @ a path, or ask me to list a directory.",
     transferEmpty: "Nothing is transferring.",
     transferLoading: "Reading transfer state\u2026",
     transferRefresh: "Refresh",
@@ -1785,6 +1785,9 @@ function buildRootsView(input) {
     title: row.label ?? row.path,
     subtitle: row.location === "remote" ? `${row.connectionId ?? "?"}:${row.path}` : row.path,
     badgeKey: row.location === "remote" ? "rootsBadgeRemote" : "rootsBadgeLocal",
+    // 只有"用户在设置页登记、且没有任何会话作用域"的行才对 AI 不可用；profile 里的根是部署级共享根，
+    // 不属于这个提示的适用范围。
+    ...row.source === "user" && (row.workspaces?.length ?? 0) === 0 && (row.sessions?.length ?? 0) === 0 ? { scopeKey: "rootsScopeNoSession" } : {},
     // Only a root the panel owns can be deleted: a config root comes back after a restart, so offering a
     // delete button for it would be a lie the user cannot see. A root that is both declared and added is
     // deletable — the file entry goes away, which is what the user asked for.
@@ -2446,6 +2449,17 @@ function createTransferProgress(options) {
       listeners.clear();
       void running;
     },
+    /**
+     * Re-arm after a `dispose()`.
+     *
+     * React's development replay runs an effect's cleanup and then the effect again **on the same controller**
+     * (the instance is kept by `useMemo`). Without `activate()` the second mount's `start()` was silently
+     * ignored — `dispose()` set `disposed = true` and nothing cleared it — so the transfer panel never polled
+     * again for the rest of the session. Every other controller in this half already has this method.
+     */
+    activate: () => {
+      disposed = false;
+    },
     requests: () => issued
   };
 }
@@ -2456,6 +2470,7 @@ function TransferProgressSection({ copy }) {
   const progress = (0, import_react4.useMemo)(() => createTransferProgress({ io }), [io]);
   const panel = (0, import_react4.useSyncExternalStore)(progress.subscribe, progress.getState);
   (0, import_react4.useEffect)(() => {
+    progress.activate();
     progress.start();
     return () => progress.dispose();
   }, [progress]);
@@ -2766,6 +2781,7 @@ function renderRow(row, copy, editable, onRemove) {
     (0, import_react5.createElement)("span", { className: CLASS.rowTitle }, row.title),
     (0, import_react5.createElement)("code", { className: CLASS.badge }, resolveMessage2(copy, { key: row.badgeKey })),
     (0, import_react5.createElement)("span", { className: CLASS.rowMeta }, row.subtitle),
+    row.scopeKey === void 0 ? null : (0, import_react5.createElement)("span", { className: CLASS.hint }, resolveMessage2(copy, { key: row.scopeKey })),
     // The one and only source of "may this be deleted": the view model's `removable`. A per-row destructive
     // action is the `ghost` variant, so the row stays quiet until the operator means it.
     row.removable ? (0, import_react5.createElement)(
@@ -3219,12 +3235,10 @@ function RootsPanelSection({
       Button({ variant: "secondary", disabled: !editable, onClick: () => actions.onImportOpen(), children: copy.rootsImportOpen })
     ),
     SshConfigImportDialog({ copy, state, actions, idPrefix }),
-    // -- remote files are reached through the conversation (audit 0085) -------
-    // There is no tree here, and no button that opens one. A file manager inside settings was the wrong
-    // artifact: it duplicated the agent's own access, wrote to the remote machine with no audit trail, and
-    // competed with the conversation as a second source of truth. The sentence says where the capability
-    // actually lives; the tools behind it (`@` a path, or asking for a listing) are the agent's.
-    (0, import_react5.createElement)("p", { className: CLASS.description }, copy.remoteFilesHint),
+    // -- no file tree, no entry point (audit 0085) ---------------------------
+    // Settings used to carry a sentence pointing at the conversation. It was a signpost for a capability
+    // that deliberately has no UI; the decision still stands (remote files are the agent's), but the
+    // signpost is gone — the settings section is not the place to teach it.
     // -- transfer progress (FR-2.6.4) ----------------------------------------
     transfers ?? null,
     // -- edit one saved connection (a dialog, not a block in this page) -------
@@ -4598,11 +4612,12 @@ function postFailureReason(parsed, status, path) {
   const error = parsed?.["error"];
   return typeof error === "string" ? error : transportFailureReason(status, path);
 }
-async function postRootsJson(fetchImpl, path, body) {
+async function postRootsJson(fetchImpl, path, body, signal) {
   try {
     const response = await fetchImpl(path, {
       method: "POST",
       headers: { "content-type": "application/json" },
+      ...signal === void 0 ? {} : { signal },
       body: JSON.stringify(body)
     });
     let parsed;
@@ -4626,10 +4641,10 @@ function createDirectoryBrowserIo(options) {
     const result = await rootsApi.load();
     return result.ok ? { ok: true, value: result.value.connections } : { ok: false, error: result.error };
   };
-  const listLocal = async (target) => {
+  const listLocal = async (target, signal) => {
     const body = { action: "list-local" };
     if (target !== void 0 && target !== "") body["path"] = target;
-    const result = await postRootsJson(options.fetchImpl, path, body);
+    const result = await postRootsJson(options.fetchImpl, path, body, signal);
     if (!result.ok) return result;
     const answer = result.value;
     const answerPath = answer["path"];
@@ -4650,9 +4665,9 @@ function createDirectoryBrowserIo(options) {
     }
     return { ok: true, value: { path: answerPath, crumbs, entries, truncated: answer["truncated"] === true } };
   };
-  const listRemote = async (input) => {
+  const listRemote = async (input, signal) => {
     if (input.connectionId === "") return { ok: false, error: NO_CONNECTION_ERROR };
-    const result = await postRootsJson(options.fetchImpl, path, { action: "list-remote", connectionId: input.connectionId, path: input.path });
+    const result = await postRootsJson(options.fetchImpl, path, { action: "list-remote", connectionId: input.connectionId, path: input.path }, signal);
     if (!result.ok) return result;
     const raw = result.value["entries"];
     const entries = [];
@@ -4666,9 +4681,9 @@ function createDirectoryBrowserIo(options) {
     const answerPath = typeof result.value["path"] === "string" && result.value["path"] !== "" ? result.value["path"] : input.path;
     return { ok: true, value: { path: answerPath, entries, truncated: result.value["truncated"] === true } };
   };
-  const loadGitStatus = async (input) => {
+  const loadGitStatus = async (input, signal) => {
     if (input.connectionId === "" || input.path === "") return { ok: false, error: NO_CONNECTION_ERROR };
-    const result = await postRootsJson(options.fetchImpl, GIT_STATUS_API_PATH, { connectionId: input.connectionId, path: input.path });
+    const result = await postRootsJson(options.fetchImpl, GIT_STATUS_API_PATH, { connectionId: input.connectionId, path: input.path }, signal);
     if (!result.ok) return result;
     return { ok: true, value: parseGitStatusView(result.value) };
   };
@@ -4750,11 +4765,14 @@ function directoryBrowserReducer(state, action) {
         }))
       };
     case "git-loaded": {
-      if (action.view.available !== true) return { ...withoutOptional(state) };
+      if (action.view.available !== true) {
+        const { git: _drop, ...rest } = state;
+        return rest;
+      }
       const changes = {};
       for (const change of action.view.changes) changes[change.path] = change.status;
       return {
-        ...withoutOptional(state),
+        ...state,
         git: {
           root: action.view.root ?? "",
           directory: action.view.directory ?? "",
@@ -4827,6 +4845,13 @@ function createDirectoryBrowser(deps) {
   };
   const listeners = /* @__PURE__ */ new Set();
   let token = 0;
+  let inFlight;
+  const beginRequest = () => {
+    inFlight?.abort();
+    const controller = new AbortController();
+    inFlight = controller;
+    return controller.signal;
+  };
   let gitToken = 0;
   let disposed = false;
   const dispatch = (action) => {
@@ -4837,20 +4862,21 @@ function createDirectoryBrowser(deps) {
   };
   const current = (issued) => !disposed && issued === token;
   const currentGit = (issued) => !disposed && issued === gitToken;
-  const loadGit = async (connectionId, path) => {
+  const loadGit = async (connectionId, path, signal) => {
     const load = deps.io.loadGitStatus;
     if (load === void 0 || connectionId === "" || path === "") return;
     const issued = ++gitToken;
-    const result = await load({ connectionId, path });
+    const result = await load({ connectionId, path }, signal);
     if (!currentGit(issued)) return;
     if (!result.ok) return;
     dispatch({ type: "git-loaded", view: result.value });
   };
   const readLocal = async (path) => {
+    const signal = beginRequest();
     const issued = ++token;
     gitToken += 1;
     dispatch({ type: "target", path: path ?? "" });
-    const result = await deps.io.listLocal(path === void 0 || path === "" ? void 0 : path);
+    const result = await deps.io.listLocal(path === void 0 || path === "" ? void 0 : path, signal);
     if (!current(issued)) return;
     if (!result.ok) {
       dispatch({ type: "failed", error: result.error });
@@ -4859,17 +4885,18 @@ function createDirectoryBrowser(deps) {
     dispatch({ type: "local-loaded", listing: result.value });
   };
   const readRemote = async (connectionId, path) => {
+    const signal = beginRequest();
     const issued = ++token;
     gitToken += 1;
     dispatch({ type: "target", path });
-    const result = await deps.io.listRemote({ connectionId, path });
+    const result = await deps.io.listRemote({ connectionId, path }, signal);
     if (!current(issued)) return;
     if (!result.ok) {
       dispatch({ type: "failed", error: result.error });
       return;
     }
     dispatch({ type: "remote-loaded", path, listing: result.value });
-    void loadGit(connectionId, result.value.path);
+    void loadGit(connectionId, result.value.path, signal);
   };
   const ensureConnections = async () => {
     if (state.connections.length > 0) return true;
@@ -4942,6 +4969,8 @@ function createDirectoryBrowser(deps) {
     },
     dispose: () => {
       disposed = true;
+      inFlight?.abort();
+      inFlight = void 0;
       listeners.clear();
     }
   };
@@ -5212,6 +5241,9 @@ function createSessionDirectoryIo(options) {
   const loadRoots = async (workspacePath, sessionId) => {
     const result = await rootsApi.load();
     if (!result.ok) return result;
+    if (result.value.warnings.includes("roots-invalid-answer")) {
+      return { ok: false, error: "roots-invalid-answer" };
+    }
     const all = result.value.roots;
     if (workspacePath === void 0 || workspacePath === "") return { ok: true, value: [] };
     return {
@@ -5390,6 +5422,10 @@ function createSessionDirectory(deps) {
       dispatch({ type: "roots-failed", reason: result.error });
       return;
     }
+    if (state.workspacePath !== workspacePath || state.sessionId !== sessionId) {
+      await refreshRoots();
+      return;
+    }
     dispatch({ type: "root-removed", key });
   };
   const commit = async (path, connectionId) => {

package/lib/file-references.js

@@ -49,14 +49,26 @@ var DEFAULTS = {
 function rankMatches(paths, query, limit) {
   const needle = query.trim().toLowerCase();
   if (needle === "") {
-    const order = [];
-    for (let index = 0; index < paths.length; index += 1) order.push(index);
-    const depths = new Int32Array(paths.length);
-    for (let index = 0; index < paths.length; index += 1) depths[index] = depth(paths[index]);
-    order.sort(
-      (left, right) => depths[left] - depths[right] || (paths[left] < paths[right] ? -1 : 1)
-    );
-    return order.slice(0, limit).map((index) => paths[index]);
+    const top = [];
+    const better = (left, right) => {
+      const leftDepth = depth(paths[left]);
+      const rightDepth = depth(paths[right]);
+      if (leftDepth !== rightDepth) return leftDepth < rightDepth;
+      return paths[left] < paths[right];
+    };
+    for (let index = 0; index < paths.length; index += 1) {
+      if (top.length >= limit && !better(index, top[top.length - 1])) continue;
+      let low = 0;
+      let high = top.length;
+      while (low < high) {
+        const middle = low + high >> 1;
+        if (better(index, top[middle])) high = middle;
+        else low = middle + 1;
+      }
+      top.splice(low, 0, index);
+      if (top.length > limit) top.pop();
+    }
+    return top.map((index) => paths[index]);
   }
   const scored = [];
   for (const path of paths) {

package/lib/fs.js

@@ -381,6 +381,9 @@ function normalizePosixPath(path) {
 
 // src/host/domain/path-grammar.ts
 function normalizeRemotePath(path) {
+  if (/[\u0000-\u001f]/.test(path)) {
+    throw new SshDevError("ROOT_INVALID", "\u8FDC\u7A0B\u8DEF\u5F84\u4E0D\u80FD\u5305\u542B\u63A7\u5236\u5B57\u7B26", { path: JSON.stringify(path) });
+  }
   const normalized = normalizePosixPath(path);
   if (normalized !== void 0) return normalized;
   if (path === "") throw new SshDevError("ROOT_INVALID", "\u8FDC\u7A0B\u8DEF\u5F84\u4E0D\u80FD\u4E3A\u7A7A", {});
@@ -542,6 +545,18 @@ function relativeDirectory(root, path) {
 function normalizeLocalPath2(path, options = {}) {
   return normalizeLocalPath(path, { caseInsensitive: options.caseInsensitive ?? process.platform === "win32" });
 }
+function localPathContains(root, candidate, options = {}) {
+  const normalizedRoot = normalizeLocalPath2(root, options);
+  const normalizedCandidate = normalizeLocalPath2(candidate, options);
+  if (normalizedRoot === "/" || /^[a-z]:\/$/.test(normalizedRoot)) {
+    return normalizedCandidate.startsWith(normalizedRoot);
+  }
+  return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}/`);
+}
+
+// src/host/app/roots/user-roots.ts
+var USER_ROOTS_FILE_NAME = "user-roots.json";
+var USER_ROOTS_LOCK_FILE_NAME = `${USER_ROOTS_FILE_NAME}.lock`;
 
 // src/shared/routes.ts
 function asRouteHost(value) {
@@ -823,6 +838,92 @@ function walkAncestors(ctx, sessionId) {
   }
   return { ancestors, settled };
 }
+function readSessionCwd(ctx, sessionId) {
+  const cached = sessionCwdCache.get(sessionId);
+  if (cached !== void 0) {
+    sessionCwdCache.delete(sessionId);
+    sessionCwdCache.set(sessionId, cached);
+    return cached.value === "" ? void 0 : cached.value;
+  }
+  const found = walkSessionCwd(ctx, sessionId);
+  if (found.settled) {
+    sessionCwdCache.set(sessionId, { value: found.cwd ?? "" });
+    while (sessionCwdCache.size > SESSION_CWD_CACHE_MAX) {
+      const oldest = sessionCwdCache.keys().next();
+      if (oldest.done === true) break;
+      sessionCwdCache.delete(oldest.value);
+    }
+  }
+  return found.cwd;
+}
+function readSessionCwds(ctx) {
+  let list;
+  try {
+    const sessions = ctx.get("sessions");
+    list = sessions?.list?.();
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(list)) return [];
+  const cwds = [];
+  for (const session of list) {
+    const cwd = session?.header?.cwd;
+    if (typeof cwd === "string" && cwd !== "") cwds.push(cwd);
+  }
+  return cwds;
+}
+var sessionCwdCache = /* @__PURE__ */ new Map();
+var SESSION_CWD_CACHE_MAX = 256;
+function walkSessionCwd(ctx, sessionId) {
+  let list;
+  try {
+    const sessions = ctx.get("sessions");
+    list = sessions?.list?.();
+  } catch {
+    return { cwd: void 0, settled: false };
+  }
+  if (!Array.isArray(list)) return { cwd: void 0, settled: false };
+  for (const session of list) {
+    if (session?.header?.id !== sessionId) continue;
+    const cwd = session.header.cwd;
+    return { cwd: typeof cwd === "string" && cwd !== "" ? cwd : void 0, settled: true };
+  }
+  return { cwd: void 0, settled: false };
+}
+
+// src/host/domain/roots/session-roots.ts
+function workspaceWriteArea(root, workspaceRoot, cwd, identity = {}) {
+  const sessions = root.sessions ?? [];
+  if (sessions.length > 0 && identity.sessionId !== void 0 && identity.sessionId !== "") {
+    if (addedBySession(sessions, identity)) return "whole-root";
+  } else if (sessions.length === 0 && cwd !== void 0 && cwd !== "") {
+    if ((root.workspaces ?? []).some((candidate) => sameWorkspacePath(candidate, cwd))) return "whole-root";
+  }
+  if (workspaceRoot === void 0 || workspaceRoot === "") return "deny";
+  if (root.location === "remote") {
+    const anchor = root.anchorPath;
+    if (anchor === void 0 || anchor === "") return "deny";
+    if (sameWorkspacePath(anchor, workspaceRoot) || localPathContains(anchor, workspaceRoot)) return "whole-root";
+    if (localPathContains(workspaceRoot, anchor)) return "whole-root";
+    return "deny";
+  }
+  if (localPathContains(root.path, workspaceRoot)) return "workspace-only";
+  if (cwd !== void 0 && cwd !== "" && sameWorkspacePath(root.path, cwd)) return "workspace-only";
+  return "deny";
+}
+function addedBySession(sessions, identity) {
+  const sessionId = identity.sessionId;
+  if (sessionId === void 0 || sessionId === "") return false;
+  if (sessions.includes(sessionId)) return true;
+  return (identity.ancestors ?? []).some((ancestor) => sessions.includes(ancestor));
+}
+function sameWorkspacePath(left, right) {
+  const fold = (value) => {
+    const normalized = normalizeLocalPath2(value, { caseInsensitive: false }).replace(/\/+/g, "/");
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+  };
+  return fold(left) === fold(right);
+}
 
 // src/host/integration/fs/fs-provider.ts
 var MAX_WHOLE_READ_BYTES = 16 * 1024 * 1024;
@@ -1051,7 +1152,7 @@ var RoutedFsProvider = class extends FileSystem {
     }
     const guard = expected?.kind === "replaceIfVersion" ? expected.version : void 0;
     const outcome = await this.call(
-      () => routed.backend.writeText(routed.absolute, content, guard, signal)
+      () => routed.backend.writeText(routed.absolute, content, guard, signal, sandboxPolicy)
     ).catch((error) => {
       throw mapWriteError(error, routed.displayPath);
     });
@@ -1096,7 +1197,8 @@ var RoutedFsProvider = class extends FileSystem {
             edit.newString,
             edit.replaceAll === true,
             chunk.version,
-            signal
+            signal,
+            sandboxPolicy
           )
         );
         return { version: FsVersion(native.version), before, after };
@@ -1107,7 +1209,7 @@ var RoutedFsProvider = class extends FileSystem {
       }
     }
     const outcome = await this.call(
-      () => routed.backend.writeText(routed.absolute, restoreLineEndings(after, lineEndings), chunk.version, signal)
+      () => routed.backend.writeText(routed.absolute, restoreLineEndings(after, lineEndings), chunk.version, signal, sandboxPolicy)
     ).catch((error) => {
       throw mapWriteError(error, routed.displayPath);
     });
@@ -1236,7 +1338,24 @@ var RoutedFsProvider = class extends FileSystem {
       throw isSshDevError(error) ? toFsError(error) : error;
     }
   }
-  /** Enforce the per-call policy and the root's own writability. */
+  /**
+   * Enforce the per-call policy and the root's own writability.
+   *
+   * Three gates, in order:
+   *  1. `read-only` denies every mutation (the platform's own contract);
+   *  2. a root registered `writable: false` denies;
+   *  3. under **`workspace-write`**, the target must be inside the session's workspace — where "workspace"
+   *     includes the directories **this session added** (product decision 2026-11-04: 「添加到会话的目录」=
+   *     该目录临时成为 workspace 的一部分). Before that decision the plugin admitted every writable root it
+   *     could route, which made the mode wider than the platform's own `fs-sandbox` fence
+   *     (`workspace-write` = "canonicalizes under `workspaceRoot` or the platform temp area").
+   *
+   * A call without a per-call policy keeps the historical behaviour (the mode comes from
+   * {@link sandboxMode}); the area rule needs `workspaceRoot`, which only the policy carries.
+   *
+   * @param routed - the resolved target.
+   * @param policy - the per-call sandbox policy the tool layer resolved.
+   */
   assertWritable(routed, policy) {
     const mode = policy?.mode ?? this.sandboxMode;
     if (mode === "read-only") {
@@ -1245,6 +1364,19 @@ var RoutedFsProvider = class extends FileSystem {
     if (routed.root.writable === false) {
       throw platformFsError(`the root of "${routed.displayPath}" is registered read-only`, "FS_SANDBOX_DENIED");
     }
+    if (mode !== "workspace-write" || policy === void 0) return;
+    const sessionId = currentSessionId();
+    const identity = sessionId === void 0 || sessionId === "" ? {} : { sessionId, ancestors: this.sessionAncestors(sessionId) };
+    const cwd = sessionId === void 0 || sessionId === "" ? void 0 : this.sessionWorkspaceCwdOf(sessionId);
+    const area = workspaceWriteArea(routed.root, policy.workspaceRoot, cwd, identity);
+    if (area === "whole-root") return;
+    if (area === "workspace-only" && routed.root.location === "local" && localPathContains(policy.workspaceRoot, routed.absolute, { caseInsensitive: process.platform === "win32" })) {
+      return;
+    }
+    throw platformFsError(
+      `sandbox denies writing "${routed.displayPath}": the path is outside this session's workspace (its workspace, or a directory this session added with \u300C\u6DFB\u52A0\u76EE\u5F55\u300D)`,
+      "FS_SANDBOX_DENIED"
+    );
   }
   /**
    * Previous text content, when it is readable text inside the cap; `undefined` otherwise.
@@ -1260,9 +1392,8 @@ var RoutedFsProvider = class extends FileSystem {
       return void 0;
     });
     if (chunk === void 0 || chunk.truncated) return void 0;
-    const bytes = Buffer.from(chunk.text, "utf8");
-    const sniff = bytes.subarray(0, BINARY_SNIFF_BYTES);
-    if (sniff.includes(0)) return void 0;
+    const nul = chunk.text.indexOf("\0");
+    if (nul !== -1 && nul < BINARY_SNIFF_BYTES) return void 0;
     return chunk.text;
   }
   /** Run a backend call, translating domain errors into core codes. */
@@ -1352,38 +1483,6 @@ function sessionSyncSignature(cwds, registry) {
   const roots = registry.sessionWorkspaceRecords.map((record) => record.key).join("\0");
   return `${cwds.join("\0")}
${roots}`;
 }
-function readSessionCwd(ctx, sessionId) {
-  let list;
-  try {
-    const sessions = ctx.get("sessions");
-    list = sessions?.list?.();
-  } catch {
-    return void 0;
-  }
-  if (!Array.isArray(list)) return void 0;
-  for (const session of list) {
-    if (session?.header?.id !== sessionId) continue;
-    const cwd = session.header.cwd;
-    return typeof cwd === "string" && cwd !== "" ? cwd : void 0;
-  }
-  return void 0;
-}
-function readSessionCwds(ctx) {
-  let list;
-  try {
-    const sessions = ctx.get("sessions");
-    list = sessions?.list?.();
-  } catch {
-    return [];
-  }
-  if (!Array.isArray(list)) return [];
-  const cwds = [];
-  for (const session of list) {
-    const cwd = session?.header?.cwd;
-    if (typeof cwd === "string" && cwd !== "") cwds.push(cwd);
-  }
-  return cwds;
-}
 function assertText(displayPath, bytes) {
   if (bytes.subarray(0, BINARY_SNIFF_BYTES).includes(0)) {
     throw platformFsError(`cannot read "${displayPath}": not a UTF-8 text file`, "FS_NOT_TEXT");