@tiphareth/dsh-hardssh 0.2.2 → 0.2.3

package/README.md

@@ -1,74 +1,77 @@
-# dsh-hardssh — SSH 远程工作区 + SSH 运维插件
-
-已适配 DSH **0.1.5**（实测内核 `0.1.5-rc.1`；本包版本 `0.2.2`）。在 DSH Web GUI 中提供两块能力（单包单引擎）：
-
-1. **SSH 运维**：右侧栏「SSH」Tab（从右侧栏标签条的「+」或右侧栏引导页入口打开）→ Web 终端（xterm + WebSocket PTY）、文件上传下载、本地端口转发隧道、当前服务器的远端命令；`ssh_list` / `ssh_exec` / `ssh_upload` / `ssh_download` / `ssh_tunnel` / `ssh_cluster` 六个 Agent 工具；主机配置存 `~/.dsh/dsh-ssh.json`。
-2. **SSH 工作区**：左侧侧栏的全局入口行 → 中央面板管理服务器与工作区（增删改查 / `~/.ssh/config` 导入）；绑定后本地 harness 的 fs/subprocess 经接缝门面透明路由到远程主机执行（read/write/edit/bash 在绑定会话中即远程操作）；`remote_*` 三个 Agent 工具（`remote_ls` / `remote_search` / `remote_status`）用于显式操作远端工作区。
-
-## 核心优势
-
-- **对插件零改动**：`cordis.patch.yml` 禁用部署自带的 `fs-sandbox` / `subprocess` 行，由本包提供路由门面。任何走标准 `ctx.fs` / `ctx.subprocess` 的插件与标准工具，在 SSH 工作区会话里自动运行在远端。
-- **通用工作区底座**：`WorkspaceRecord` / `Provider` / `Connection` / 能力契约 + Registry / Ledger / Router，与 SSH 解耦。SSH 只是一个 provider（如 `ssh`、`local`），可继续接 docker / wsl / 云 devbox，上层插件与 UI 不改；单一运行时，全链路读同一个台账。
-- **少数插件只需改几处接口**：给 agent 的执行手册见 [`SKILLS.md`](./SKILLS.md)——判定命令、接口对照表、可照抄代码与自检清单。
-
-## 架构
-
-- **单一共享实例**：`HostStore` + `SshEngine`（ssh2 连接池）在 `src/index.ts` 创建一次，SSH 运维与 SSH 工作区共用同一引擎 —— 配置变更（PATCH/DELETE）同时失效所有连接，无双池问题。
-- **接缝切换**：`cordis.patch.yml` 禁用部署自带的 `fs-sandbox` / `subprocess` 行，由 `dsh-hardssh/fs`、`dsh-hardssh/subprocess` 提供 provider 路由门面（本地 = 沙箱化原实现；远端 = 该 workspace 连接上的 `workspace.fs` / `workspace.process` capability）。
-- **REST**：`/api/dsh-ssh`（运维路由，loopback-only）+ `/api/dsh-hardssh`（工作区路由，loopback-only）。
-- **工作区核心服务**：`ctx.workspaceCore`（通用 WorkspaceCore：台账 + provider 路由 + capability 连接）是**唯一**的工作区运行时；`ctx.hardsshCore` 只保留 `hosts` + `engine` 供 SSH 专用集成消费（如四列 IDE 形态的 `dsh-workbench-tiphareth`）。
-- **公开入口**：`@tiphareth/dsh-hardssh/base`（通用底座实现）、`@tiphareth/dsh-hardssh/workspace`（平台无关类型面）。
-
-## 界面入口（全部走标准插件扩展点）
-
-插件不使用任何 DOM 注入；两个界面都是内核公开的槽位注册：
-
-| 界面 | 入口 | 槽位 |
-|---|---|---|
-| **SSH 工作区管理**（服务器 + 工作区增删改查，服务器行带已连接/未连接徽章） | 左侧侧栏「新会话」与「工作区」之间的全局入口行 → 中央面板 | `sidebar.panellist`（行）+ `main`（面板，key 同为 `dsh-hardssh-workspaces`） |
-| **SSH 运维**（终端 / 传输 / 隧道 / 当前服务器命令） | 右侧栏标签条的「+」或右侧栏引导页入口 | `ctx.sidebarRightTabs.register`（类型）+ `sidebar.right.pane.tab`（正文）+ `sidebar.right.pane.tab.title`（标签文字） |
-
-右侧栏 Tab 是 **page 类型**（不声明 `patterns`），只按 kind 打开，由用户从右侧栏自己的入口打开；插件不会强制展开右侧栏。右侧栏 Tab 实例是**每会话独立**的（内核的会话作用域语义），因此切换会话后需要重新打开该 Tab。
-
-## 会话绑定语义（操作台不选服务器）
-
-- 操作台的 SSH 目标由**当前会话的 `cwd`** 决定：最长匹配的 SSH 工作区锚点胜出，取该工作区的 `alias` 与 `remoteRoot`。终端 / 传输 / 隧道 / 命令四个子页都强制使用它，**不提供服务器下拉框**。
-- 会话在本地工作区（或未绑定任何 SSH 工作区）时，操作台不挂载任何操作组件，改为渲染**模糊蒙版**并提示「SSH 操作台仅适用于 SSH 工作区会话」。
-- 切换会话时操作台随 `Session → alias` 自动切换，并重置子页状态。
-- 数据源是公开的 `ctx.sessions.list`（`current` + `byId[id].cwd`）+ `WorkspaceManager` 快照，两者都可订阅，不存在第二份工作区句柄。
-
-## 连接行为
-
-- **启动/刷新只连接当前会话的服务器**：连接闸门在 `ctx.sessions.list` 的 `phase === 'ready'` 之前不建立基准，避免历史会话被误判为「新建会话」而逐台探测；本地会话不触发任何连接。
-- **非交互失败可见**：探测失败（网络不可达、认证失败、主机密钥异常、重试耗尽）会弹出「无法连接服务器」对话框并显示具体原因；用户主动取消密码/指纹弹窗不算失败。
-- **状态徽章只读**：左侧面板每 3 秒读取 `/api/dsh-ssh/connections`（连接池 live alias 列表）刷新「已连接 / 未连接」徽章，**不会**主动拨号。
-
-## 安装
-
-```sh
-# profile 机制，热插拔；需重启 dsh
-dsh plugin --profile <name> add link:<repo>/packages/dsh-hardssh
-```
-
-## 开发
-
-在仓库根目录执行：
-
-```sh
-pnpm --filter dsh-hardssh typecheck   # 类型检查
-pnpm test                             # 默认测试套件（vault 加密用例已移出，约 12s）
-pnpm test:vault                       # 只跑 vault 用例（约 21s，scrypt 派生故意慢）
-pnpm --filter dsh-hardssh build       # 产出 lib/（构建前先清空，避免陈旧产物）
-```
-
-> profile 通过 `link:` 指向本包源码目录，因此改码后只需重新 `build`（产出 `lib/`）并重启
-> `dsh web` 即生效；不要把依赖改成 `file:` 安装副本，那会让 profile 加载一份快照而不是源码。
-
-## 安全模型
-
-- `/api/dsh-ssh/*` 与 `/api/dsh-hardssh/*` 仅限 loopback（含同源校验）。
-- 认证材料沿用 `~/.dsh/dsh-ssh.json`（0600 / 0700），不新增存储。
-- 路径 gate：远程操作 root 必须等于 resolved remoteRoot；相对路径禁止 `..`；`workspace.fs` / `workspace.process` capability 在解析后的 canonical 路径上再做一次 root 收敛（symlink 逃逸 fail closed）。
-- 远程操作消耗真实远程资源：工具描述与宣告段明确「先确认再执行」；`remote_search` 有深度与条数上限；`glob` / `grep` 在 SSH 会话里会被**显式拒绝**（本机 ripgrep 读不到服务器内容）并指向 `remote_search`。
-- SSH 模式下本机沙箱不对远程执行生效（远程进程无法被本地内核沙箱约束）：门面的 `sandboxMode` 委托本地后端的真实模式（`write` / `edit` 的沙箱升级入口据此注册），而远端世界的升级策略在门面处**显式丢弃**。
-- 凭据默认不落盘；`secretStorage: vault` 时以 AES-256-GCM + scrypt 加密存储于 `~/.dsh/ssh-secrets/dsh-ssh-vault.json`（被 fs seam 拒绝访问），且 `DSH_CREDENTIAL_PASSWORD` 自动解锁默认关闭（需 `vaultAutoUnlock: env`）。会话密码按**连接存活期**复用，连接池回收即失效。
+# dsh-hardssh — SSH 远程工作区 + SSH 运维插件
+
+已适配 DSH **0.1.5**（实测内核 `0.1.5-rc.1`；本包版本 `0.2.3`）。在 DSH Web GUI 中提供两块能力（单包单引擎）：
+
+1. **SSH 运维**：右侧栏「SSH」Tab（从右侧栏标签条的「+」或右侧栏引导页入口打开）→ Web 终端（xterm + WebSocket PTY）、文件上传下载、本地端口转发隧道、当前服务器的远端命令；`ssh_list` / `ssh_exec` / `ssh_upload` / `ssh_download` / `ssh_tunnel` / `ssh_cluster` 六个 Agent 工具；主机配置存 `~/.dsh/dsh-ssh.json`。
+2. **SSH 工作区**：左侧侧栏的全局入口行 → 中央面板管理服务器与工作区（增删改查 / `~/.ssh/config` 导入）；绑定后本地 harness 的 fs/subprocess 经接缝门面透明路由到远程主机执行（read/write/edit/bash 在绑定会话中即远程操作）；`remote_*` 三个 Agent 工具（`remote_ls` / `remote_search` / `remote_status`）用于显式操作远端工作区。
+
+## 核心优势
+
+- **对插件零改动**：`cordis.patch.yml` 禁用部署自带的 `fs-sandbox` / `subprocess` 行，由本包提供路由门面。任何走标准 `ctx.fs` / `ctx.subprocess` 的插件与标准工具，在 SSH 工作区会话里自动运行在远端。
+- **通用工作区底座**：`WorkspaceRecord` / `Provider` / `Connection` / 能力契约 + Registry / Ledger / Router，与 SSH 解耦。SSH 只是一个 provider（如 `ssh`、`local`），可继续接 docker / wsl / 云 devbox，上层插件与 UI 不改；单一运行时，全链路读同一个台账。
+- **少数插件只需改几处接口**：给 agent 的执行手册见 [`SKILLS.md`](./SKILLS.md)——判定命令、接口对照表、可照抄代码与自检清单。
+
+## 架构
+
+- **单一共享实例**：`HostStore` + `SshEngine`（ssh2 连接池）在 `src/index.ts` 创建一次，SSH 运维与 SSH 工作区共用同一引擎 —— 配置变更（PATCH/DELETE）同时失效所有连接，无双池问题。
+- **接缝切换**：`cordis.patch.yml` 禁用部署自带的 `fs-sandbox` / `subprocess` 行，由 `dsh-hardssh/fs`、`dsh-hardssh/subprocess` 提供 provider 路由门面（本地 = 沙箱化原实现；远端 = 该 workspace 连接上的 `workspace.fs` / `workspace.process` capability）。
+- **REST**：`/api/dsh-ssh`（运维路由，loopback-only）+ `/api/dsh-hardssh`（工作区路由，loopback-only）。
+- **工作区核心服务**：`ctx.workspaceCore`（通用 WorkspaceCore：台账 + provider 路由 + capability 连接）是**唯一**的工作区运行时；`ctx.hardsshCore` 只保留 `hosts` + `engine` 供 SSH 专用集成消费（如四列 IDE 形态的 `dsh-workbench-tiphareth`）。
+- **公开入口**：`@tiphareth/dsh-hardssh/base`（通用底座实现）、`@tiphareth/dsh-hardssh/workspace`（平台无关类型面）。
+
+## 界面入口（全部走标准插件扩展点）
+
+插件不使用任何 DOM 注入；两个界面都是内核公开的槽位注册：
+
+| 界面 | 入口 | 槽位 |
+|---|---|---|
+| **SSH 工作区管理**（服务器 + 工作区增删改查，服务器行带已连接/未连接徽章） | 左侧侧栏「新会话」与「工作区」之间的全局入口行 → 中央面板 | `sidebar.panellist`（行）+ `main`（面板，key 同为 `dsh-hardssh-workspaces`） |
+| **SSH 运维**（终端 / 传输 / 隧道 / 当前服务器命令） | 右侧栏标签条的「+」或右侧栏引导页入口 | `ctx.sidebarRightTabs.register`（类型）+ `sidebar.right.pane.tab`（正文）+ `sidebar.right.pane.tab.title`（标签文字） |
+
+右侧栏 Tab 是 **page 类型**（不声明 `patterns`），只按 kind 打开，由用户从右侧栏自己的入口打开；插件不会强制展开右侧栏。右侧栏 Tab 实例是**每会话独立**的（内核的会话作用域语义），因此切换会话后需要重新打开该 Tab。
+
+## 会话绑定语义（操作台不选服务器）
+
+- 操作台的 SSH 目标由**当前会话的 `cwd`** 决定：最长匹配的 SSH 工作区锚点胜出，取该工作区的 `alias` 与 `remoteRoot`。终端 / 传输 / 隧道 / 命令四个子页都强制使用它，**不提供服务器下拉框**。
+- 会话在本地工作区（或未绑定任何 SSH 工作区）时，操作台不挂载任何操作组件，改为渲染**模糊蒙版**并提示「SSH 操作台仅适用于 SSH 工作区会话」。
+- 切换会话时操作台随 `Session → alias` 自动切换，并重置子页状态。
+- 数据源是公开的 `ctx.sessions.list`（`current` + `byId[id].cwd`）+ `WorkspaceManager` 快照，两者都可订阅，不存在第二份工作区句柄。
+
+## 连接行为
+
+- **启动/刷新只连接当前会话的服务器**：连接闸门在 `ctx.sessions.list` 的 `phase === 'ready'` 之前不建立基准，避免历史会话被误判为「新建会话」而逐台探测；本地会话不触发任何连接。
+- **非交互失败可见**：探测失败（网络不可达、认证失败、主机密钥异常、重试耗尽）会弹出「无法连接服务器」对话框并显示具体原因；用户主动取消密码/指纹弹窗不算失败。
+- **状态徽章只读**：左侧面板每 3 秒读取 `/api/dsh-ssh/connections`（连接池 live alias 列表）刷新「已连接 / 未连接」徽章，**不会**主动拨号。
+
+## 安装
+
+```sh
+# 已发布 npm（当前 0.2.3）：profile 机制，热插拔，需重启 dsh
+dsh plugin --profile <name> add @tiphareth/dsh-hardssh
+
+# 开发/迭代：源码链接（改码重建 lib/ 后重启即生效）
+dsh plugin --profile <name> add link:<repo>/packages/dsh-hardssh
+```
+
+## 开发
+
+在仓库根目录执行：
+
+```sh
+pnpm --filter dsh-hardssh typecheck   # 类型检查
+pnpm test                             # 默认测试套件（vault 加密用例已移出，约 12s）
+pnpm test:vault                       # 只跑 vault 用例（约 21s，scrypt 派生故意慢）
+pnpm --filter dsh-hardssh build       # 产出 lib/（构建前先清空，避免陈旧产物）
+```
+
+> profile 通过 `link:` 指向本包源码目录，因此改码后只需重新 `build`（产出 `lib/`）并重启
+> `dsh web` 即生效；不要把依赖改成 `file:` 安装副本，那会让 profile 加载一份快照而不是源码。
+
+## 安全模型
+
+- `/api/dsh-ssh/*` 与 `/api/dsh-hardssh/*` 仅限 loopback（含同源校验）。
+- 认证材料沿用 `~/.dsh/dsh-ssh.json`（0600 / 0700），不新增存储。
+- 路径 gate：远程操作 root 必须等于 resolved remoteRoot；相对路径禁止 `..`；`workspace.fs` / `workspace.process` capability 在解析后的 canonical 路径上再做一次 root 收敛（symlink 逃逸 fail closed）。
+- 远程操作消耗真实远程资源：工具描述与宣告段明确「先确认再执行」；`remote_search` 有深度与条数上限；`glob` / `grep` 在 SSH 会话里会被**显式拒绝**（本机 ripgrep 读不到服务器内容）并指向 `remote_search`。
+- SSH 模式下本机沙箱不对远程执行生效（远程进程无法被本地内核沙箱约束）：门面的 `sandboxMode` 委托本地后端的真实模式（`write` / `edit` 的沙箱升级入口据此注册），而远端世界的升级策略在门面处**显式丢弃**。
+- 凭据默认不落盘；`secretStorage: vault` 时以 AES-256-GCM + scrypt 加密存储于 `~/.dsh/ssh-secrets/dsh-ssh-vault.json`（被 fs seam 拒绝访问），且 `DSH_CREDENTIAL_PASSWORD` 自动解锁默认关闭（需 `vaultAutoUnlock: env`）。会话密码按**连接存活期**复用，连接池回收即失效。

package/lib/fs.js

@@ -3,7 +3,7 @@ import { t as anchorRoot } from "./ledger-B-LXlftp.js";
 import { n as legacyVaultPath, r as vaultDirectory } from "./vault-3gpWct2Q.js";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { FileSystem } from "@deepseek-ai/dsh-fs";
+import { FileSystem, FsError } from "@deepseek-ai/dsh-fs";
 import { SandboxedFileSystem } from "@deepseek-ai/dsh-fs-sandbox";
 /** Strict WFS key prefix (includes the double slash + separator). */
 const WFS_NAMESPACE_MARKER = `wfs://`;
@@ -320,6 +320,36 @@ function genericFsWorldForNamespace(core, namespace) {
 		remoteRoot: record.location.root
 	};
 }
+/**
+* Refuse a path that sits inside the managed anchor root but is owned by no
+* registered workspace — as a NOT-FOUND answer, not as a fatal error.
+*
+* The path stays unreachable either way (it is never handed to the local
+* backend, so a bound session cannot read or write client files through the
+* anchor window). What changes is how callers SEE the refusal: `FS_NOT_FOUND`
+* is the DSH contract for "this path does not exist", and the harness relies on
+* it when walking UP from the session cwd looking for a project root —
+* `dsh-agent-instructions` probes `<dir>/.git` per ancestor and treats ONLY
+* `FS_NOT_FOUND` as "keep walking" (any other error aborts the whole run),
+* `dsh-skill-filesystem` does the same. With a bare Error the very first step
+* above the anchor (`<anchorRoot>/.git`) killed the run with
+* "fs-ssh: … is inside the workspace anchor root but no registered workspace
+* owns it (fail closed)". The message is kept verbatim so the refusal is still
+* self-explanatory in logs.
+*/
+function refuseUnownedAnchorPath(path) {
+	throw new FsError(`fs-ssh: '${path}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`, "FS_NOT_FOUND");
+}
+/**
+* The shipped `worldForAnchorPath` deps hook: the workspace owning an absolute
+* anchor path (this session's or a SIBLING's), else the anchor-window refusal.
+* Exported so the seam can be exercised without re-implementing the policy.
+*/
+function anchorWorldFor(core, anchorRootDir, path) {
+	const world = genericFsWorldFor(core, path, [anchorRootDir]);
+	if (world !== void 0) return world;
+	if (isPathUnderAnchor(anchorRootDir, path)) refuseUnownedAnchorPath(path);
+}
 /** Mount the generic switching filesystem facade. */
 function apply(ctx) {
 	const localCtx = ctx.isolate("fs");
@@ -335,11 +365,7 @@ function apply(ctx) {
 		localRoots: [join(homedir(), ".dsh"), join(homedir(), ".agents")],
 		localRootExclusions: [anchorRootDir],
 		deniedRoots: [vaultDirectory(), legacyVaultPath()],
-		worldForAnchorPath: (path) => {
-			const world = genericFsWorldFor(ws, path, [anchorRootDir]);
-			if (world !== void 0) return world;
-			if (isPathUnderAnchor(anchorRootDir, path)) throw new Error(`fs-ssh: '${path}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`);
-		},
+		worldForAnchorPath: (path) => anchorWorldFor(ws, anchorRootDir, path),
 		worldFor: (cwd) => {
 			if (!ws.isReady()) {
 				if (cwd !== void 0 && isPathUnderAnchor(anchorRootDir, cwd)) {
@@ -366,4 +392,4 @@ function apply(ctx) {
 	});
 }
 //#endregion
-export { apply, genericFsWorldFor, genericFsWorldForNamespace, inject, name };
+export { anchorWorldFor, apply, genericFsWorldFor, genericFsWorldForNamespace, inject, name, refuseUnownedAnchorPath };

package/lib/types/fs.d.ts

@@ -24,6 +24,30 @@ export declare const inject: string[];
 export declare function genericFsWorldFor(core: WorkspaceCore, cwd: string | undefined, reservedAnchorRoots: readonly string[]): WorkspaceWorld | undefined;
 /** Resolve one namespaced target key, failing closed for stale namespaces. */
 export declare function genericFsWorldForNamespace(core: WorkspaceCore, namespace: string): WorkspaceWorld | undefined;
+/**
+ * Refuse a path that sits inside the managed anchor root but is owned by no
+ * registered workspace — as a NOT-FOUND answer, not as a fatal error.
+ *
+ * The path stays unreachable either way (it is never handed to the local
+ * backend, so a bound session cannot read or write client files through the
+ * anchor window). What changes is how callers SEE the refusal: `FS_NOT_FOUND`
+ * is the DSH contract for "this path does not exist", and the harness relies on
+ * it when walking UP from the session cwd looking for a project root —
+ * `dsh-agent-instructions` probes `<dir>/.git` per ancestor and treats ONLY
+ * `FS_NOT_FOUND` as "keep walking" (any other error aborts the whole run),
+ * `dsh-skill-filesystem` does the same. With a bare Error the very first step
+ * above the anchor (`<anchorRoot>/.git`) killed the run with
+ * "fs-ssh: … is inside the workspace anchor root but no registered workspace
+ * owns it (fail closed)". The message is kept verbatim so the refusal is still
+ * self-explanatory in logs.
+ */
+export declare function refuseUnownedAnchorPath(path: string): never;
+/**
+ * The shipped `worldForAnchorPath` deps hook: the workspace owning an absolute
+ * anchor path (this session's or a SIBLING's), else the anchor-window refusal.
+ * Exported so the seam can be exercised without re-implementing the policy.
+ */
+export declare function anchorWorldFor(core: WorkspaceCore, anchorRootDir: string, path: string): WorkspaceWorld | undefined;
 /** Mount the generic switching filesystem facade. */
 export declare function apply(ctx: Context): void;
 //# sourceMappingURL=fs.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiphareth/dsh-hardssh",
   "description": "Generic workspace base for the dsh harness (local + remote workspace providers with per-workspace routing), with SSH as one concrete provider: bind a server directory as an SSH workspace so the session's file I/O and commands run on that host, manage hosts and workspaces in the GUI, and operate remote servers through the ssh_* / remote_* agent tools",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -164,4 +164,4 @@
     "SKILLS.md"
   ],
   "license": "BSD-3-Clause"
-}
+}

package/src/fs.ts

@@ -16,6 +16,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox'
+import { FsError } from '@deepseek-ai/dsh-fs'
 import type { FileSystem } from '@deepseek-ai/dsh-fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
@@ -83,6 +84,42 @@ export function genericFsWorldForNamespace(core: WorkspaceCore, namespace: strin
   }
 }
 
+/**
+ * Refuse a path that sits inside the managed anchor root but is owned by no
+ * registered workspace — as a NOT-FOUND answer, not as a fatal error.
+ *
+ * The path stays unreachable either way (it is never handed to the local
+ * backend, so a bound session cannot read or write client files through the
+ * anchor window). What changes is how callers SEE the refusal: `FS_NOT_FOUND`
+ * is the DSH contract for "this path does not exist", and the harness relies on
+ * it when walking UP from the session cwd looking for a project root —
+ * `dsh-agent-instructions` probes `<dir>/.git` per ancestor and treats ONLY
+ * `FS_NOT_FOUND` as "keep walking" (any other error aborts the whole run),
+ * `dsh-skill-filesystem` does the same. With a bare Error the very first step
+ * above the anchor (`<anchorRoot>/.git`) killed the run with
+ * "fs-ssh: … is inside the workspace anchor root but no registered workspace
+ * owns it (fail closed)". The message is kept verbatim so the refusal is still
+ * self-explanatory in logs.
+ */
+export function refuseUnownedAnchorPath(path: string): never {
+  throw new FsError(
+    `fs-ssh: '${path}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`,
+    'FS_NOT_FOUND',
+  )
+}
+
+/**
+ * The shipped `worldForAnchorPath` deps hook: the workspace owning an absolute
+ * anchor path (this session's or a SIBLING's), else the anchor-window refusal.
+ * Exported so the seam can be exercised without re-implementing the policy.
+ */
+export function anchorWorldFor(core: WorkspaceCore, anchorRootDir: string, path: string): WorkspaceWorld | undefined {
+  const world = genericFsWorldFor(core, path, [anchorRootDir])
+  if (world !== undefined) return world
+  if (isPathUnderAnchor(anchorRootDir, path)) refuseUnownedAnchorPath(path)
+  return undefined
+}
+
 /** Mount the generic switching filesystem facade. */
 export function apply(ctx: Context): void {
   const localCtx = ctx.isolate('fs')
@@ -106,14 +143,7 @@ export function apply(ctx: Context): void {
     // pre-relocation path is denied too, because a failed move deliberately
     // leaves the original file in place.
     deniedRoots: [vaultDirectory(), legacyVaultPath()],
-    worldForAnchorPath: (path) => {
-      const world = genericFsWorldFor(ws, path, [anchorRootDir])
-      if (world !== undefined) return world
-      if (isPathUnderAnchor(anchorRootDir, path)) {
-        throw new Error(`fs-ssh: '${path}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`)
-      }
-      return undefined
-    },
+    worldForAnchorPath: (path) => anchorWorldFor(ws, anchorRootDir, path),
     worldFor: (cwd) => {
       if (!ws.isReady()) {
         if (cwd !== undefined && isPathUnderAnchor(anchorRootDir, cwd)) {
@@ -128,6 +158,10 @@ export function apply(ctx: Context): void {
       const world = genericFsWorldFor(ws, cwd, [anchorRootDir])
       if (world !== undefined) return world
       if (cwd !== undefined && isPathUnderAnchor(anchorRootDir, cwd)) {
+        // Deliberately NOT the FS_NOT_FOUND refusal above: `cwd` is the session's
+        // own identity, not a path being probed. An unowned cwd means the
+        // workspace was deleted out from under a live session, which must stay
+        // loud instead of degrading into "not found" on every relative path.
         throw new Error(`fs-ssh: '${cwd}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`)
       }
       return { backend: localFs, namespace: '' }