dsh-over-ssh 0.1.0 → 0.2.0

package/lib/terminal-wrapper.js

@@ -20,9 +20,9 @@ var SshDevError = class extends Error {
   }
 };
 
-// src/host/domain/roots/root.ts
+// src/shared/root-keys.ts
 function normalizeLocalPath(path, options = {}) {
-  const caseInsensitive = options.caseInsensitive ?? process.platform === "win32";
+  const caseInsensitive = options.caseInsensitive ?? false;
   const unified = path.replace(/\\/g, "/");
   const unc = unified.startsWith("//");
   const posixAbsolute = unified.startsWith("/");
@@ -47,9 +47,14 @@ function normalizeLocalPath(path, options = {}) {
   else normalized = body === "" ? "." : body;
   return caseInsensitive ? normalized.toLowerCase() : normalized;
 }
+
+// src/host/domain/roots/root.ts
+function normalizeLocalPath2(path, options = {}) {
+  return normalizeLocalPath(path, { caseInsensitive: options.caseInsensitive ?? process.platform === "win32" });
+}
 function localPathContains(root, candidate, options = {}) {
-  const normalizedRoot = normalizeLocalPath(root, options);
-  const normalizedCandidate = normalizeLocalPath(candidate, options);
+  const normalizedRoot = normalizeLocalPath2(root, options);
+  const normalizedCandidate = normalizeLocalPath2(candidate, options);
   if (normalizedRoot === "/" || /^[a-z]:\/$/.test(normalizedRoot)) {
     return normalizedCandidate.startsWith(normalizedRoot);
   }

package/lib/types/src/config.d.ts

@@ -84,8 +84,47 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
          */
         readCacheTtlMs: z<number, number, "defined">;
         readCacheMaxEntries: z<number, number, "defined">;
+        /**
+         * Byte ceiling for the read cache of **one remote root**, not for the plugin as a whole.
+         *
+         * 这条的语义必须写清楚，否则会读成"整个插件的上限"：每个远端根各自持有一份版本缓存（外加一份
+         * 目录列举缓存），所以 N 个**同时存在**的根是 N × 这个数。上界因此是"活根数"而不是"历史根数"——
+         * 根被移除时 `Backend.dispose()` 会把它的缓存一起释放（审计 0112 P3-11 接线之前不是这样，
+         * 那才是 P3-12 真正的风险所在）。要压总占用就调小这个数，或者减少同时挂着的远端根。
+         */
         readCacheMaxBytes: z<number, number, "defined">;
+        /**
+         * Ceiling for the **sum** over every remote root's caches, not per root.
+         *
+         * 0112 P3-12 的缺口是"每个根各自封顶、加起来没人管"：`readCacheMaxBytes` 是每根的额度，
+         * 十根就是十倍。这一项把总和钉住——超过时由**占用最大的那个**缓存让出最旧的条目（通常也是读者
+         * 正在看的那个，所以不让刚写的先挨刀）。
+         *
+         * 默认 64 MiB ≈ 8 个满额度的根。**必须是正整数**：要彻底关掉缓存请设
+         * `readCacheMaxBytes: 0`（那是"根本不缓存"），而不是把总预算设为 0——后者只会让每次写入
+         * 立刻把自己的条目淘汰掉，行为既不是"关缓存"也不是"缓存"。
+         */
+        readCacheTotalMaxBytes: z<number, number, "defined">;
+        /**
+         * 端口转发的空闲回收窗口（毫秒）；`0` 关闭回收。
+         *
+         * 判据是"没有任何活跃连接且距最后一次活动超过这个窗口"。没有回收的话，一个被 agent 起过、
+         * 之后没人用的转发会一直占着本地端口（用户实测关心的问题）。默认 30 分钟：比一次开发会话的
+         * 间隔长，比"忘了关一整天"短。
+         */
+        forwardIdleTimeoutMs: z<number, number, "defined">;
         terminalStateDir: z<string, string, "plain">;
+        /**
+         * 是否给 `remote_exec` / `remote_exec_background` 套**远端写入围栏**（Tier 2 的 Landlock）。
+         *
+         * **默认关**是刻意的：围栏只放行 workspace 根与本会话添加的目录，构建工具往 `$HOME/.cache`、
+         * `/tmp` 写缓存时会被拒——默认开启会把正常命令弄坏。关着的时候 shell 命令能碰到 SSH 用户能碰的
+         * 一切，这与"添加目录"的文件边界是两件事，工具描述里如实写着。
+         *
+         * 打开之后，`remote_exec` 只能写：命令起始的 workspace 根、本会话添加的可写根。Tier 1（无代理）
+         * 没有 Landlock 能力，此项对它们无效。
+         */
+        execWriteFence: z<boolean, boolean, "defined">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
@@ -110,8 +149,6 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         sessionBinMaxEntries: z<number, number, "defined">;
         sessionBinMaxBytes: z<number, number, "defined">;
         sessionBinMaxAgeMs: z<number, number, "defined">;
-        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
-        sessionPurgeProjection: z<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
         maxReadBytes: z<number, number, "defined">;
         connectTimeoutMs: z<number, number, "defined">;
@@ -133,8 +170,47 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
          */
         readCacheTtlMs: z<number, number, "defined">;
         readCacheMaxEntries: z<number, number, "defined">;
+        /**
+         * Byte ceiling for the read cache of **one remote root**, not for the plugin as a whole.
+         *
+         * 这条的语义必须写清楚，否则会读成"整个插件的上限"：每个远端根各自持有一份版本缓存（外加一份
+         * 目录列举缓存），所以 N 个**同时存在**的根是 N × 这个数。上界因此是"活根数"而不是"历史根数"——
+         * 根被移除时 `Backend.dispose()` 会把它的缓存一起释放（审计 0112 P3-11 接线之前不是这样，
+         * 那才是 P3-12 真正的风险所在）。要压总占用就调小这个数，或者减少同时挂着的远端根。
+         */
         readCacheMaxBytes: z<number, number, "defined">;
+        /**
+         * Ceiling for the **sum** over every remote root's caches, not per root.
+         *
+         * 0112 P3-12 的缺口是"每个根各自封顶、加起来没人管"：`readCacheMaxBytes` 是每根的额度，
+         * 十根就是十倍。这一项把总和钉住——超过时由**占用最大的那个**缓存让出最旧的条目（通常也是读者
+         * 正在看的那个，所以不让刚写的先挨刀）。
+         *
+         * 默认 64 MiB ≈ 8 个满额度的根。**必须是正整数**：要彻底关掉缓存请设
+         * `readCacheMaxBytes: 0`（那是"根本不缓存"），而不是把总预算设为 0——后者只会让每次写入
+         * 立刻把自己的条目淘汰掉，行为既不是"关缓存"也不是"缓存"。
+         */
+        readCacheTotalMaxBytes: z<number, number, "defined">;
+        /**
+         * 端口转发的空闲回收窗口（毫秒）；`0` 关闭回收。
+         *
+         * 判据是"没有任何活跃连接且距最后一次活动超过这个窗口"。没有回收的话，一个被 agent 起过、
+         * 之后没人用的转发会一直占着本地端口（用户实测关心的问题）。默认 30 分钟：比一次开发会话的
+         * 间隔长，比"忘了关一整天"短。
+         */
+        forwardIdleTimeoutMs: z<number, number, "defined">;
         terminalStateDir: z<string, string, "plain">;
+        /**
+         * 是否给 `remote_exec` / `remote_exec_background` 套**远端写入围栏**（Tier 2 的 Landlock）。
+         *
+         * **默认关**是刻意的：围栏只放行 workspace 根与本会话添加的目录，构建工具往 `$HOME/.cache`、
+         * `/tmp` 写缓存时会被拒——默认开启会把正常命令弄坏。关着的时候 shell 命令能碰到 SSH 用户能碰的
+         * 一切，这与"添加目录"的文件边界是两件事，工具描述里如实写着。
+         *
+         * 打开之后，`remote_exec` 只能写：命令起始的 workspace 根、本会话添加的可写根。Tier 1（无代理）
+         * 没有 Landlock 能力，此项对它们无效。
+         */
+        execWriteFence: z<boolean, boolean, "defined">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
@@ -159,8 +235,6 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         sessionBinMaxEntries: z<number, number, "defined">;
         sessionBinMaxBytes: z<number, number, "defined">;
         sessionBinMaxAgeMs: z<number, number, "defined">;
-        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
-        sessionPurgeProjection: z<boolean, boolean, "defined">;
     }>>, "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     connections: z<({
@@ -228,8 +302,47 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
          */
         readCacheTtlMs: z<number, number, "defined">;
         readCacheMaxEntries: z<number, number, "defined">;
+        /**
+         * Byte ceiling for the read cache of **one remote root**, not for the plugin as a whole.
+         *
+         * 这条的语义必须写清楚，否则会读成"整个插件的上限"：每个远端根各自持有一份版本缓存（外加一份
+         * 目录列举缓存），所以 N 个**同时存在**的根是 N × 这个数。上界因此是"活根数"而不是"历史根数"——
+         * 根被移除时 `Backend.dispose()` 会把它的缓存一起释放（审计 0112 P3-11 接线之前不是这样，
+         * 那才是 P3-12 真正的风险所在）。要压总占用就调小这个数，或者减少同时挂着的远端根。
+         */
         readCacheMaxBytes: z<number, number, "defined">;
+        /**
+         * Ceiling for the **sum** over every remote root's caches, not per root.
+         *
+         * 0112 P3-12 的缺口是"每个根各自封顶、加起来没人管"：`readCacheMaxBytes` 是每根的额度，
+         * 十根就是十倍。这一项把总和钉住——超过时由**占用最大的那个**缓存让出最旧的条目（通常也是读者
+         * 正在看的那个，所以不让刚写的先挨刀）。
+         *
+         * 默认 64 MiB ≈ 8 个满额度的根。**必须是正整数**：要彻底关掉缓存请设
+         * `readCacheMaxBytes: 0`（那是"根本不缓存"），而不是把总预算设为 0——后者只会让每次写入
+         * 立刻把自己的条目淘汰掉，行为既不是"关缓存"也不是"缓存"。
+         */
+        readCacheTotalMaxBytes: z<number, number, "defined">;
+        /**
+         * 端口转发的空闲回收窗口（毫秒）；`0` 关闭回收。
+         *
+         * 判据是"没有任何活跃连接且距最后一次活动超过这个窗口"。没有回收的话，一个被 agent 起过、
+         * 之后没人用的转发会一直占着本地端口（用户实测关心的问题）。默认 30 分钟：比一次开发会话的
+         * 间隔长，比"忘了关一整天"短。
+         */
+        forwardIdleTimeoutMs: z<number, number, "defined">;
         terminalStateDir: z<string, string, "plain">;
+        /**
+         * 是否给 `remote_exec` / `remote_exec_background` 套**远端写入围栏**（Tier 2 的 Landlock）。
+         *
+         * **默认关**是刻意的：围栏只放行 workspace 根与本会话添加的目录，构建工具往 `$HOME/.cache`、
+         * `/tmp` 写缓存时会被拒——默认开启会把正常命令弄坏。关着的时候 shell 命令能碰到 SSH 用户能碰的
+         * 一切，这与"添加目录"的文件边界是两件事，工具描述里如实写着。
+         *
+         * 打开之后，`remote_exec` 只能写：命令起始的 workspace 根、本会话添加的可写根。Tier 1（无代理）
+         * 没有 Landlock 能力，此项对它们无效。
+         */
+        execWriteFence: z<boolean, boolean, "defined">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
@@ -254,8 +367,6 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         sessionBinMaxEntries: z<number, number, "defined">;
         sessionBinMaxBytes: z<number, number, "defined">;
         sessionBinMaxAgeMs: z<number, number, "defined">;
-        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
-        sessionPurgeProjection: z<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
         maxReadBytes: z<number, number, "defined">;
         connectTimeoutMs: z<number, number, "defined">;
@@ -277,8 +388,47 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
          */
         readCacheTtlMs: z<number, number, "defined">;
         readCacheMaxEntries: z<number, number, "defined">;
+        /**
+         * Byte ceiling for the read cache of **one remote root**, not for the plugin as a whole.
+         *
+         * 这条的语义必须写清楚，否则会读成"整个插件的上限"：每个远端根各自持有一份版本缓存（外加一份
+         * 目录列举缓存），所以 N 个**同时存在**的根是 N × 这个数。上界因此是"活根数"而不是"历史根数"——
+         * 根被移除时 `Backend.dispose()` 会把它的缓存一起释放（审计 0112 P3-11 接线之前不是这样，
+         * 那才是 P3-12 真正的风险所在）。要压总占用就调小这个数，或者减少同时挂着的远端根。
+         */
         readCacheMaxBytes: z<number, number, "defined">;
+        /**
+         * Ceiling for the **sum** over every remote root's caches, not per root.
+         *
+         * 0112 P3-12 的缺口是"每个根各自封顶、加起来没人管"：`readCacheMaxBytes` 是每根的额度，
+         * 十根就是十倍。这一项把总和钉住——超过时由**占用最大的那个**缓存让出最旧的条目（通常也是读者
+         * 正在看的那个，所以不让刚写的先挨刀）。
+         *
+         * 默认 64 MiB ≈ 8 个满额度的根。**必须是正整数**：要彻底关掉缓存请设
+         * `readCacheMaxBytes: 0`（那是"根本不缓存"），而不是把总预算设为 0——后者只会让每次写入
+         * 立刻把自己的条目淘汰掉，行为既不是"关缓存"也不是"缓存"。
+         */
+        readCacheTotalMaxBytes: z<number, number, "defined">;
+        /**
+         * 端口转发的空闲回收窗口（毫秒）；`0` 关闭回收。
+         *
+         * 判据是"没有任何活跃连接且距最后一次活动超过这个窗口"。没有回收的话，一个被 agent 起过、
+         * 之后没人用的转发会一直占着本地端口（用户实测关心的问题）。默认 30 分钟：比一次开发会话的
+         * 间隔长，比"忘了关一整天"短。
+         */
+        forwardIdleTimeoutMs: z<number, number, "defined">;
         terminalStateDir: z<string, string, "plain">;
+        /**
+         * 是否给 `remote_exec` / `remote_exec_background` 套**远端写入围栏**（Tier 2 的 Landlock）。
+         *
+         * **默认关**是刻意的：围栏只放行 workspace 根与本会话添加的目录，构建工具往 `$HOME/.cache`、
+         * `/tmp` 写缓存时会被拒——默认开启会把正常命令弄坏。关着的时候 shell 命令能碰到 SSH 用户能碰的
+         * 一切，这与"添加目录"的文件边界是两件事，工具描述里如实写着。
+         *
+         * 打开之后，`remote_exec` 只能写：命令起始的 workspace 根、本会话添加的可写根。Tier 1（无代理）
+         * 没有 Landlock 能力，此项对它们无效。
+         */
+        execWriteFence: z<boolean, boolean, "defined">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
@@ -303,10 +453,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         sessionBinMaxEntries: z<number, number, "defined">;
         sessionBinMaxBytes: z<number, number, "defined">;
         sessionBinMaxAgeMs: z<number, number, "defined">;
-        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
-        sessionPurgeProjection: z<boolean, boolean, "defined">;
     }>>, "defined">;
 }>>, "plain">;
 /** What {@link apply} receives: the schema's resolved output, which is what the loader passes. */
 export type ResolvedConfig = Schemastery.TypeT<typeof Config>;
-//# sourceMappingURL=config.d.ts.map

package/lib/types/src/file-references.d.ts

@@ -22,4 +22,3 @@ import { Context } from '@deepseek-ai/cordis';
  */
 export default function apply(ctx: Context): (import("@deepseek-ai/cordis").Fiber & PromiseLike<import("@deepseek-ai/cordis").Fiber>) | undefined;
 export { RemoteFileReferenceService, DEFAULT_MAX_RESULTS, LOCAL_EXCLUDED_DIRECTORIES, LOCAL_MAX_DEPTH, LOCAL_MAX_ENTRIES, type FileReferenceIndex, type LocalEntry, type RemoteFileReferenceOptions, } from './host/integration/fs/file-reference-provider.ts';
-//# sourceMappingURL=file-references.d.ts.map

package/lib/types/src/host/app/backend.d.ts

@@ -69,6 +69,17 @@ export interface BackendWrite {
 }
 /** How a backend confines writes, mirroring the core's `SandboxMode`. */
 export type BackendSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/**
+ * Per-call write fence; structurally compatible with the platform's `SandboxExecutionPolicy`.
+ *
+ * 用结构化类型而不是 `import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'`：app 层的端口
+ * 不该依赖平台包（`tests/architecture.test.ts` 的可测性规则）。只有真正把写入交给平台沙箱的
+ * {@link PlatformLocalBackend} 会读它，其余后端各有一套自己的围栏。
+ */
+export interface BackendWritePolicy {
+    readonly mode: BackendSandboxMode;
+    readonly workspaceRoot: string;
+}
 /** One backend serving one root. */
 export interface Backend {
     /** Stable id, also the namespace prefix of every target key it produces. */
@@ -77,6 +88,15 @@ export interface Backend {
     readonly sandboxMode: BackendSandboxMode | undefined;
     /** Whether the backend can watch for changes natively. */
     readonly watches: boolean;
+    /**
+     * Stop background work (watchers, poll loops) and release what this backend holds.
+     *
+     * Called when its root is retired. Optional: a backend with nothing to stop omits it. Without this call a
+     * removed root's watcher kept polling — `RemoteBackend.dispose()` existed but had **zero production callers**,
+     * so the poll loop outlived the root that started it and the remote inotify registration was never dropped
+     * (audit 0112 P3-11).
+     */
+    dispose?(): Promise<void>;
     /**
      * Watch one path for changes, in this backend's own absolute spelling (the backend layer has no `FsTarget`).
      *
@@ -104,8 +124,11 @@ export interface Backend {
      * Write text, atomically where the backend can.
      *
      * @param expectedVersion - when non-empty the write must fail if the current version differs.
+     * @param policy - the per-call sandbox policy, when the caller has one. Only backends that delegate to a
+     *   platform sandbox consume it ({@link PlatformLocalBackend}); the others enforce their own fence and
+     *   ignore it. Structural on purpose — the app layer must not import platform types.
      */
-    writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite>;
+    writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal, policy?: BackendWritePolicy): Promise<BackendWrite>;
     /**
      * Apply a unified diff to one file, atomically.
      *
@@ -122,9 +145,10 @@ export interface Backend {
      * apply the **same** three-state semantics as that fallback (not found / ambiguous / replaceAll) and
      * must honour `expectedVersion` across its own read-modify-write.
      */
-    editText?(absolute: string, oldString: string, newString: string, replaceAll: boolean, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
+    editText?(absolute: string, oldString: string, newString: string, replaceAll: boolean, expectedVersion: string | undefined, signal?: AbortSignal, policy?: BackendWritePolicy): Promise<BackendWrite & {
         readonly replaced: number;
     }>;
+    /** Per-call write fence, structurally compatible with the platform's `SandboxExecutionPolicy`. */
     /**
      * Create a directory, and its parents when asked (FR-2.2.2: the file tree's 「新建目录」).
      *
@@ -162,9 +186,26 @@ export interface Backend {
      * caller's `755` is octal digits, not decimal seven hundred and fifty-five, and that confusion is silent.
      */
     chmod?(absolute: string, mode: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Create a symbolic link at `linkPath` pointing at `target`.
+     *
+     * Optional, and it must **refuse** an existing path rather than replace it: silently turning a real file
+     * into a symlink is data loss, and "there used to be a file here" is not recoverable from the link.
+     *
+     * @param target - what the link points at (kept verbatim; a relative target resolves against the link's dir).
+     * @param linkPath - the link to create.
+     * @param signal - cancellation.
+     */
+    symlink?(target: string, linkPath: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Read a symbolic link's target, or `undefined` when the path is not a link.
+     *
+     * `undefined` (not an error) is the honest answer for "not a link": the caller asked a question whose
+     * answer is "no". Only a real failure throws.
+     */
+    readlink?(absolute: string, signal?: AbortSignal): Promise<string | undefined>;
     /** Host path a child process in this backend's world can open, if any. */
     processPath?(absolute: string): string | undefined;
     /** `file:` URL for this path in the backend's world. */
     fileUrl?(absolute: string): string;
 }
-//# sourceMappingURL=backend.d.ts.map

package/lib/types/src/host/app/recycle-bin/recycle-bin-contract.d.ts

@@ -244,4 +244,3 @@ export interface RecycleBinService {
     /** Current undo/redo state. */
     history(): RecycleBinHistory;
 }
-//# sourceMappingURL=recycle-bin-contract.d.ts.map

package/lib/types/src/host/app/recycle-bin/recycle-bin-service.d.ts

@@ -42,4 +42,3 @@ export * from './recycle-bin-contract.ts';
  * @returns a {@link RecycleBinService}; its undo stack is per-instance, in memory and not persisted.
  */
 export declare function createRecycleBinService(deps: RecycleBinServiceDeps): RecycleBinService;
-//# sourceMappingURL=recycle-bin-service.d.ts.map

package/lib/types/src/host/app/session-admin/session-admin-contract.d.ts

@@ -94,6 +94,18 @@ export interface SessionAdminDeps {
     readonly detachSession?: (sessionId: string) => Promise<void>;
     /** Announce the removal so clients drop the row (`api-session/removed`). */
     readonly emitRemoved?: (sessionId: string) => void;
+    /**
+     * The session is gone: drop it from any bookkeeping that remembers session ids.
+     *
+     * Fired **after** the deletion is durable, on both the permanent and the recycle path, and it is not awaited:
+     * losing a stale id in `user-roots.json` must not turn a completed deletion into a failure. The implementation
+     * is expected to be best-effort and to log its own warnings.
+     *
+     * Audit 0112 P3-13: before this, nothing told `user-roots.json` that a session had been deleted, so every root
+     * a session had added kept its dead id forever — the panel went on showing the root as "added by a session
+     * that no longer exists" and the file grew on every write.
+     */
+    readonly onSessionRemoved?: (sessionId: string) => void;
     /** Injected clock. */
     readonly now: () => number;
     /** Who confirmed, for the audit trail (FR-3.10); absent when the caller did not say. */
@@ -218,4 +230,3 @@ export interface SessionAdminService {
  * @throws SshDevError `ROOT_INVALID` when the bin root is inside the sessions root (that placement breaks the
  *   platform's session listing — see the module note and ADR-0009).
  */
-//# sourceMappingURL=session-admin-contract.d.ts.map

package/lib/types/src/host/app/session-admin/session-admin-service.d.ts

@@ -37,4 +37,3 @@ export * from './session-admin-contract.ts';
  * @returns the {@link SessionAdminService}.
  */
 export declare function createSessionAdminService(deps: SessionAdminDeps): SessionAdminService;
-//# sourceMappingURL=session-admin-service.d.ts.map

package/lib/types/src/host/app/transport/transport-selector.d.ts

@@ -95,4 +95,3 @@ export declare class TransportSelector {
      */
     noteMultiplexingFailure(profile: ConnectionProfile, reason: string): void;
 }
-//# sourceMappingURL=transport-selector.d.ts.map

package/lib/types/src/host/app/transport/transport-service.d.ts

@@ -79,4 +79,3 @@ export declare class TransportService {
     /** Dispose every connection (plugin unload, connection-service shutdown). */
     disposeAll(): Promise<void>;
 }
-//# sourceMappingURL=transport-service.d.ts.map

package/lib/types/src/host/domain/capability.d.ts

@@ -75,4 +75,3 @@ export declare function searchStrategyFor(capabilities: RemoteCapabilities): Sea
 export declare function indexStrategyFor(capabilities: RemoteCapabilities): IndexStrategy;
 /** Whether the host can run the plugin's file-transfer path. */
 export declare function canTransferBytes(capabilities: RemoteCapabilities): boolean;
-//# sourceMappingURL=capability.d.ts.map

package/lib/types/src/host/domain/errors.d.ts

@@ -52,4 +52,3 @@ export declare function sshFailureToError(connectionId: string, input: {
 }): SshDevError;
 /** Keep only the tail of a long diagnostic string so details stay bounded. */
 export declare function tail(text: string, maxChars: number): string;
-//# sourceMappingURL=errors.d.ts.map

package/lib/types/src/host/domain/roots/connection.d.ts

@@ -103,4 +103,3 @@ export declare function validateConnectionProfile(input: unknown): ConnectionPro
 export declare function profileFromImportDraft(id: string, draft: SshConfigImportDraft): ConnectionProfile;
 /** One-line summary used by diagnostics and the settings list. */
 export declare function connectionSummary(profile: ConnectionProfile): string;
-//# sourceMappingURL=connection.d.ts.map

package/lib/types/src/host/domain/roots/root.d.ts

@@ -5,8 +5,9 @@
  *
  * @module dsh-over-ssh/domain/root
  */
-/** Where a root lives. */
-export type RootLocation = 'local' | 'remote';
+import { isAbsoluteLocalPath, type RootKeyOptions, type RootLocation } from '../../../shared/root-keys.ts';
+/** Where a root lives. The definition lives in `shared/root-keys.ts`, beside the key rule that needs it. */
+export type { RootLocation };
 /** One project root. */
 export interface RootRef {
     /** Local or remote. */
@@ -76,24 +77,39 @@ export declare function makeRemoteRoot(connectionId: string, remotePath: string,
  * a child process receives via `processPath`.
  */
 export declare function makeLocalRoot(path: string, options?: RootOptions): RootRef;
-/** Whether a host path is absolute in either the Windows or the POSIX spelling. */
-export declare function isAbsoluteLocalPath(path: string): boolean;
+/**
+ * Whether a host path is absolute in either the Windows or the POSIX spelling.
+ *
+ * **Re-exported, not re-implemented.** The rule lives in `shared/root-keys.ts` because the client panel has to
+ * answer the same question before it sends a request — and the two answers had drifted: this file rejected
+ * `\\server\share` while the panel accepted it (审计 0112 P2-11). Both UNC spellings are accepted now, which is
+ * what this function always claimed in its one-line doc.
+ */
+export { isAbsoluteLocalPath };
 /**
  * Normalize a host path for comparison: separators to `/`, `.`/`..` resolved, trailing
  * separators dropped, and (optionally) the drive letter and case folded.
  *
+ * The **implementation** is `shared/root-keys.ts` (the client's key needs the same normalisation). What stays
+ * here is the platform default: `caseInsensitive` defaults to "this host folds case on Windows", which is a
+ * fact only the host has — a browser bundle has no `process` and must not guess it.
+ *
  * @param path - host path in either separator spelling.
  * @param options - `caseInsensitive` folds case for comparison keys.
  * @returns the normalized path.
  */
-export declare function normalizeLocalPath(path: string, options?: {
-    readonly caseInsensitive?: boolean;
-}): string;
+export declare function normalizeLocalPath(path: string, options?: RootKeyOptions): string;
 /** Whether a host path is `root` itself or a descendant of it. */
 export declare function localPathContains(root: string, candidate: string, options?: {
     readonly caseInsensitive?: boolean;
 }): boolean;
-/** Stable identity of a root, used as a cache/route key. */
+/**
+ * Stable identity of a root, used as a cache/route key.
+ *
+ * The **spelling** is `shared/root-keys.ts`'s `rootKeySpelling`: the client rebuilds this same key for a row
+ * whose answer carried none, and a second spelling is what made the panel's delete button address a root the
+ * registry did not have (审计 0024 §8.3). Only the error policy and the platform's case fold stay here.
+ */
 export declare function rootKey(root: RootRef): string;
 /** The model-facing and UI-facing spelling of a root's directory. */
 export declare function rootDisplay(root: RootRef): string;
@@ -105,4 +121,3 @@ export declare function rootsOverlap(left: RootRef, right: RootRef): boolean;
 export declare function validateRoot(root: RootRef): void;
 /** FNV-1a (32-bit) over UTF-16 code units, rendered as 8 lowercase hex characters. */
 export declare function fnv1aHex(input: string): string;
-//# sourceMappingURL=root.d.ts.map

package/lib/types/src/host/domain/roots/session-roots.d.ts

@@ -56,6 +56,29 @@ export interface SessionIdentity {
     /** The asking session's fork ancestors, nearest first. */
     readonly ancestors?: readonly string[] | undefined;
 }
+/**
+ * How much of one root counts as **the session's workspace** for a `workspace-write` mutation.
+ *
+ * 产品决定（2026-11-04，用户明确）：**「添加到会话的目录」= 该目录临时成为 workspace 的一部分，可写。**
+ * 在此之前插件对 `workspace-write` 只做两件事（`read-only` 拒绝、`root.writable === false` 拒绝），写入
+ * 范围实际是"本会话能看见的任何可写根"——比平台声明宽，且和"添加目录"的语义没有关系。
+ *
+ * 三个取值：
+ *  - `whole-root`：整个根都属于 workspace（会话自己添加的目录；或映射到 workspace 的远端根——远端根与
+ *    本地锚点是 1:1 的，锚点就是 workspace）；
+ *  - `workspace-only`：根包含 workspace，但只有 `workspaceRoot` 之内可写（平台自己的语义：`target` 必须
+ *    canonicalize 到 `workspaceRoot` 或其临时目录下）；
+ *  - `deny`：既不是会话添加的目录，也不是 workspace 本身。
+ *
+ * @param root - 一个已注册的根。
+ * @param workspaceRoot - 平台为本次调用解析出的 workspace 根（绝对本地路径）。
+ * @param cwd - 调用方的会话工作目录，用于判定历史条目（ADR-0013 之前只有 `workspaces`）。
+ * @param identity - 调用方的会话身份，用于判定本会话添加的条目。
+ * @returns 该根在 `workspace-write` 下的可写范围。
+ */
+export declare function workspaceWriteArea(root: RootRef, workspaceRoot: string | undefined, cwd: string | undefined, identity?: SessionIdentity): WorkspaceWriteArea;
+/** See {@link workspaceWriteArea}. */
+export type WorkspaceWriteArea = 'whole-root' | 'workspace-only' | 'deny';
 /** The target shape the tools consume; kept structural so this module imports no integration code. */
 export interface SessionRootTarget {
     readonly connectionId: string;
@@ -148,4 +171,3 @@ export declare function ambiguousSessionRootMessage(candidates: readonly Session
  * @returns whether the root may serve that caller.
  */
 export declare function rootVisibleToSession(root: RootRef, cwd: string | undefined, identity?: SessionIdentity): boolean;
-//# sourceMappingURL=session-roots.d.ts.map

package/lib/types/src/host/domain/roots/ssh-config.d.ts

@@ -70,4 +70,3 @@ export declare function importableEntries(entries: readonly SshConfigEntry[], op
     readonly home?: string;
     readonly excluded?: readonly string[];
 }): SshConfigImportResult;
-//# sourceMappingURL=ssh-config.d.ts.map

package/lib/types/src/host/domain/session/session-admin.d.ts

@@ -342,4 +342,3 @@ export declare function makeSessionTrashEntry(input: {
     readonly movedBy: 'rename' | 'copy';
     readonly confirmedBy?: string | undefined;
 }): SessionTrashEntry;
-//# sourceMappingURL=session-admin.d.ts.map

package/lib/types/src/host/domain/transfer/recycle-bin.d.ts

@@ -334,4 +334,3 @@ export declare function serializeRecycleBinIndex(entries: readonly RecycleBinEnt
  * @throws SshDevError `TRASH_NOT_FOUND` when the document cannot be read as an index.
  */
 export declare function parseRecycleBinIndex(text: string): ParsedRecycleBinIndex;
-//# sourceMappingURL=recycle-bin.d.ts.map

package/lib/types/src/host/domain/transfer/transfer.d.ts

@@ -257,4 +257,3 @@ export declare function isTransferFailure(error: unknown, kind?: TransferFailure
  */
 export declare function digestsMatch(left: string | undefined, right: string | undefined): boolean;
 export { formatBytes, formatDuration };
-//# sourceMappingURL=transfer.d.ts.map

package/lib/types/src/host/infra/transport/agent/agent-installer.d.ts

@@ -118,4 +118,3 @@ export declare function loadAgentManifest(manifestPath: string): Promise<{
     /** Commit the artifacts were built from, when the manifest records it. */
     readonly sourceCommit?: string;
 }>;
-//# sourceMappingURL=agent-installer.d.ts.map

package/lib/types/src/host/infra/transport/forward.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 端口转发：请求 / 句柄 / 转发器三个形状，以及请求校验。
+ *
+ * 为什么单独一个模块：两个 Tier 都要实现同一份契约，而调用方（Lead 之后接进 `Transport`）只需要这一份。
+ * 放在 `infra/transport/` 顶层而不是 `ssh/` 下，是因为它是**跨适配器**的端口：`alias-forward` 与
+ * `ssh2-forward` 各自实现它，谁都不该 import 对方。
+ *
+ * 本地端一律绑 `127.0.0.1`：转发出去的端口是给本机浏览器用的（DSH 侧栏只能开本地 URL），绑到
+ * `0.0.0.0` 等于把一个远端服务暴露给整个局域网。这是一条安全决定，不是默认值凑巧。
+ *
+ * @module dsh-over-ssh/infra/transport/forward
+ */
+/** 本地监听地址；固定环回，见模块注释。 */
+export declare const FORWARD_LOCAL_HOST = "127.0.0.1";
+/** 一次转发请求。 */
+export interface ForwardRequest {
+    /** 远端要连的主机（相对**远端**解析；`localhost` 指远端自己）。 */
+    readonly remoteHost: string;
+    /** 远端端口，1..65535。 */
+    readonly remotePort: number;
+    /** 本地端口；省略则自动选一个空闲端口。 */
+    readonly localPort?: number;
+}
+/** 一次已建立的转发。 */
+export interface ForwardHandle {
+    /** 真实的本地端口（自动选择时也一定有值，调用方拿它开 URL）。 */
+    readonly localPort: number;
+    readonly remoteHost: string;
+    readonly remotePort: number;
+    /** 幂等：第二次调用是 no-op，不抛错。 */
+    close(): Promise<void>;
+    /**
+     * 订阅「这条转发已经关掉」，无论关闭的**原因**是什么。
+     *
+     * 为什么需要它：空闲回收（默认 30 分钟）、连接退役、`closeAll` 都能让一条转发消失，而调用方手里只有
+     * 一个 handle；没有这个回调时，调用方的台账（`remote_forward list`）会一直列出已经关掉的转发。
+     *
+     * 可选：只有实现了回收的传输才提供。回调恰好触发一次；可重复订阅。
+     *
+     * @param listener - 收到关闭通知（含回收）时调用。
+     */
+    readonly onClosed?: (listener: () => void) => void;
+}
+/** 一个连接的转发台账。 */
+export interface Forwarder {
+    /** 建立一条转发；失败必须不留本地监听、也不留子进程。 */
+    forward(req: ForwardRequest, signal?: AbortSignal): Promise<ForwardHandle>;
+    /** 当前活着的转发（只读快照语义：调用方不得依赖它的身份稳定）。 */
+    readonly forwards: readonly ForwardHandle[];
+    /** 收掉全部转发，供 dispose 使用；幂等。 */
+    closeAll(): Promise<void>;
+}
+/**
+ * 校验并规整一个转发请求。
+ *
+ * **为什么在拼 argv 之前就校验**：`-L` 的规格串是 `local:remoteHost:remotePort`，靠冒号分隔。主机名里
+ * 多一个冒号（`host:80`、裸 `::1`）会把参数解析成完全不同的目标；空白与逗号同理。ssh 对这些的报错
+ * 文案不稳定，映射不成可操作的错误码，所以这里主动拒绝。
+ *
+ * 方括号 IPv6（`[::1]`）是**允许**的：那是 ssh 自己的写法，`-L` 里的冒号被方括号包住，解析无歧义。
+ *
+ * @param request - 调用方的原始请求。
+ * @returns 去掉首尾空白、字段已校验的请求。
+ * @throws SshDevError `CONNECTION_INVALID` 当主机或端口不合法。
+ */
+export declare function normalizeForwardRequest(request: ForwardRequest): ForwardRequest;
+/**
+ * 一行描述一条转发，日志与错误文案共用。
+ *
+ * `localPort` 缺席时写 `?`：那时端口还没选出来，写 0 会被误读成"转发到 0 号端口"。
+ *
+ * @param forward - 部分句柄（至少要有远端目标）。
+ * @returns 形如 `127.0.0.1:8080 -> db:5432` 的一行。
+ */
+export declare function forwardLabel(forward: Pick<ForwardHandle, 'remoteHost' | 'remotePort'> & Partial<Pick<ForwardHandle, 'localPort'>>): string;