dsh-over-ssh 0.1.0 → 0.1.1

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,7 +84,27 @@ 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">;
         terminalStateDir: z<string, string, "plain">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
@@ -110,8 +130,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,7 +151,27 @@ 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">;
         terminalStateDir: z<string, string, "plain">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
@@ -159,8 +197,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,7 +264,27 @@ 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">;
         terminalStateDir: z<string, string, "plain">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
@@ -254,8 +310,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,7 +331,27 @@ 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">;
         terminalStateDir: z<string, string, "plain">;
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
@@ -303,10 +377,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

@@ -77,6 +77,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`).
      *
@@ -167,4 +176,3 @@ export interface Backend {
     /** `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

@@ -148,4 +148,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/ssh/ssh2-transport.d.ts

@@ -325,4 +325,3 @@ export declare function sftpError(operation: string, path: string, error?: Error
  * session.
  */
 export declare const defaultConnector: Ssh2Connector;
-//# sourceMappingURL=ssh2-transport.d.ts.map

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

@@ -31,4 +31,3 @@ export declare abstract class TransportBase {
     /** Forget the probe (a reconnect must not keep a stale timestamp). */
     protected clearProbed(): void;
 }
-//# sourceMappingURL=transport-base.d.ts.map

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

@@ -522,6 +522,20 @@ export interface Transport {
 }
 /** Encode bytes as base64 without line wrapping. */
 export declare function encodeBase64(bytes: Uint8Array): string;
-/** Decode base64, ignoring line breaks produced by remote tooling. */
+/**
+ * Decode base64, ignoring line breaks produced by remote tooling.
+ *
+ * **两次多余的整串处理被去掉了**（审计 0112 P3-2）：
+ *
+ *  1. `text.replace(/\s+/g, '')` 先把整串扫一遍去掉空白。Node 的 base64 解码**本来就忽略空白**
+ *     （`\n` / `\r\n` / 空格 / 制表符都已实测逐字节等价，见本函数下方的测试），所以这一遍纯属浪费：
+ *     9 MiB 负载（12.7 MB base64）实测 17.3 ms → 7.1 ms。
+ *  2. `new Uint8Array(...)` 把解码结果再拷一遍。4 KiB 以上的解码本来就不走 Buffer 的共享池，
+ *     `Buffer.from(str, 'base64')` 的返回对象已经是独占、正好大小的 `Uint8Array`，直接交出去即可
+ *     （9 MiB 的一次拷贝实测 1.4 ms，而它正是这条读路径上最大的一块）。
+ *
+ * **小结果仍然拷一次，这是有意的**：`Buffer.from(string)` 在 4 KiB 以下会落进 Node 的 64 KiB 共享池，
+ * 原样返回会让一个几十字节的缓存值长期钉住 64 KiB（读缓存按 `byteLength` 记账，看不见这块）。
+ * 那次拷贝是几十字节，与热路径无关。
+ */
 export declare function decodeBase64(text: string): Uint8Array;
-//# sourceMappingURL=transport.d.ts.map

package/lib/types/src/host/integration/agent/agent-preflight.d.ts

@@ -53,4 +53,3 @@ export interface AgentPreflight {
  * @returns the preflight, an installation lookup, and a way to forget a connection.
  */
 export declare function createAgentPreflight(options: AgentPreflightOptions): AgentPreflight;
-//# sourceMappingURL=agent-preflight.d.ts.map

package/lib/types/src/host/integration/fs/file-reference-provider.d.ts

@@ -139,4 +139,3 @@ export declare class RemoteFileReferenceService extends FileReferenceService {
     list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
 }
 export default RemoteFileReferenceService;
-//# sourceMappingURL=file-reference-provider.d.ts.map

package/lib/types/src/host/integration/fs/fs-provider.d.ts

@@ -101,7 +101,6 @@ export interface RoutedFsProviderOptions {
  * model's file tools follow the router (see `cordis.patch.yml`).
  */
 export declare class RoutedFsProvider extends FileSystem {
-    #private;
     static inject: string[];
     protected readonly rangeReader: BackendRangeReader | undefined;
     protected readonly rangeChunkBytes: number;
@@ -365,4 +364,3 @@ export declare function createBackendRangeReader(store: (backend: Backend, offse
 export declare function toFsError(error: SshDevError): FsError;
 /** Codes this provider can surface, exported for tests that assert the mapping table. */
 export declare const MAPPED_DOMAIN_CODES: readonly SshDevErrorCode[];
-//# sourceMappingURL=fs-provider.d.ts.map

package/lib/types/src/host/integration/transfer/transfer-service.d.ts

@@ -209,4 +209,3 @@ export declare const RESUME_VERIFY_BYTES: number;
  * @returns the upload/download operations; no state is kept between calls.
  */
 export declare function createTransferService(dependencies: TransferDependencies): TransferService;
-//# sourceMappingURL=transfer-service.d.ts.map

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

@@ -1,3 +1,18 @@
+/**
+ * The host plugin entry: configuration, services and the object graph behind this plugin.
+ *
+ * It provides two services and nothing else, deliberately:
+ *
+ *  - `sshDevConnections` — the validated connection profiles (secrets referenced by credential key).
+ *  - `sshDevRoots` — the {@link RootRegistry} the `ctx.fs` provider (`dsh-over-ssh/fs`) injects.
+ *
+ * Transports are constructed lazily and owned by a {@link TransportService}, so a client half (or a
+ * root added at runtime) simply calls into the registry and everything else follows. Nothing here
+ * reads a secret eagerly: passwords live in `ctx.credentials` and are resolved when a connection is
+ * actually opened.
+ *
+ * @module dsh-over-ssh
+ */
 import { Context } from '@deepseek-ai/cordis';
 import { TransportService } from './host/app/transport/transport-service.ts';
 import { Config } from './config.ts';
@@ -54,6 +69,14 @@ declare module '@deepseek-ai/cordis' {
         sshDevSessionAdmin: SessionAdminService;
     }
 }
+/**
+ * Read a session log's header line.
+ *
+ * The bounded reader lives in {@link createDiskSessionHeaderReader} rather than here: a composition root
+ * cannot be exercised by a test (审计 0046 记录了同款教训), and a reader whose *memory bound* is its whole
+ * contract must have one. The previous inline version read the entire log before slicing 256 KiB off it —
+ * measured at 105.3 MiB of reads for this machine's 73 sessions, worst single log 10.9 MiB (审计 0050).
+ */
 /**
  * Install the plugin.
  *
@@ -63,4 +86,3 @@ declare module '@deepseek-ai/cordis' {
  */
 export { Config };
 export declare function apply(ctx: Context, config: ResolvedConfig): void;
-//# sourceMappingURL=index.d.ts.map

package/lib/types/src/local-bridge-refs.d.ts

@@ -23,4 +23,3 @@ export default class LocalFileReferencesBridge {
     static inject: readonly ["fileReferences"];
     constructor(ctx: Context);
 }
-//# sourceMappingURL=local-bridge-refs.d.ts.map

package/lib/types/src/local-bridge.d.ts

@@ -33,4 +33,3 @@ export default class LocalFsBridge {
     static inject: readonly ["fs"];
     constructor(ctx: Context);
 }
-//# sourceMappingURL=local-bridge.d.ts.map

package/lib/types/src/shared/root-keys.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 根路径与根键的**唯一拼写规则**：client 与 host 两侧都 import 这一份。
+ *
+ * 为什么在 `shared/`：这三条规则此前各有两份实现，而每一对都已经分叉过一次（审计 0112 P2-11）：
+ *
+ *  - **根键**：客户端拼 `local:<原样路径>`，宿主拼 `local:<规范化路径>`（Windows 上还折叠大小写）。
+ *    0024 §8.3 的"删除按钮发出宿主匹配不上的键"就是这个分叉的直接后果——面板把那行显示出来，
+ *    点删除却什么也没发生，而两边各自的用例都是绿的；
+ *  - **绝对本地路径**：宿主不认 `\\server\share`（它先规范化再判断，所以只认 `//server/share`），
+ *    客户端认。同一个 UNC 路径在两半得到相反的答案；
+ *  - **远端父目录**：客户端自己 `lastIndexOf('/')`，宿主的 `remoteDirname` 先规范化（`/a//b/` 与
+ *    `/a/b` 因此是不同的答案）。
+ *
+ * `shared/` 是两侧唯一都能 import 的位置：`tests/architecture.test.ts` 规定 client 只能依赖
+ * `client` 与 `shared`，而 `shared` 只能依赖自己。这也是 `routes.ts` / `format.ts` 住在这里的理由。
+ *
+ * 本模块是**纯函数**，且**不读 `process`**：它会被打进浏览器 bundle（`platform: 'browser'`），
+ * 那里没有 `process`。平台相关的决定由调用方作为参数传进来——见 {@link rootKeySpelling} 的
+ * `caseInsensitive`：宿主的 `domain/roots/root.ts` 传 `process.platform === 'win32'`，客户端不猜。
+ *
+ * 三个函数都是**全函数**（不抛错）：宿主那一侧的错误策略（`SshDevError('ROOT_INVALID')`）留在
+ * `domain/` 里，因为客户端在 reducer 里抛错等于把界面炸掉。所以这里能共享的是**规则**，不是
+ * "遇到坏输入怎么办"。
+ *
+ * @module dsh-over-ssh/shared/root-keys
+ */
+/** Where a root lives: on this machine, or behind a connection. */
+export type RootLocation = 'local' | 'remote';
+/**
+ * One option bag for every spelling rule here.
+ *
+ * Only `caseInsensitive` exists today, and only for **local** paths: a Windows host folds case in the
+ * registry, a POSIX host does not, and a browser cannot know which. So the decision travels as an argument
+ * instead of being read from `process` inside a function that both halves call.
+ */
+export interface RootKeyOptions {
+    /** Fold case in a local path/key. Defaults to `false` — "keep the caller's case". */
+    readonly caseInsensitive?: boolean;
+}
+/**
+ * Whether a host path is absolute in either the Windows or the POSIX spelling.
+ *
+ * Both UNC spellings are accepted: `\\server\share` (what a Windows operator types) and `//server/share`
+ * (what {@link normalizeLocalPath} produces). The host used to accept only the second, the client only the
+ * first — so the panel and `makeLocalRoot` disagreed about the same string.
+ *
+ * @param path - candidate host path.
+ * @returns whether it names an absolute host path.
+ */
+export declare function isAbsoluteLocalPath(path: string): boolean;
+/**
+ * Normalize a host path for comparison: separators to `/`, `.`/`..` resolved, trailing separators dropped,
+ * and (optionally) the drive letter and case folded.
+ *
+ * Total: a relative spelling comes back as a relative spelling (`src` → `src`). The caller decides whether
+ * that is an error (the host's `makeLocalRoot`/`validateRoot` check {@link isAbsoluteLocalPath} after this).
+ *
+ * @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?: RootKeyOptions): string;
+/**
+ * Normalize an absolute POSIX path: repeated separators collapsed, `.`/`..` resolved, trailing separators
+ * dropped (except for the root).
+ *
+ * Total: `undefined` means "not an absolute POSIX spelling". The host's `normalizeRemotePath` is the same
+ * rule plus the `SshDevError('ROOT_INVALID')` policy on top.
+ *
+ * @param path - candidate absolute POSIX path.
+ * @returns the normalized path, or `undefined` when the spelling is not absolute.
+ */
+export declare function normalizePosixPath(path: string): string | undefined;
+/**
+ * The parent directory of a **normalized** absolute POSIX path; the root's parent is `/`.
+ *
+ * One rule, two policies on top: the host's `remoteDirname` answers `/` for the root (a root's parent is
+ * itself, which is what its callers assume), while the directory browser's `parentRemotePath` answers
+ * `undefined` there (the "up" button must be disabled). The separator arithmetic is not repeated.
+ *
+ * @param normalized - an absolute POSIX path already passed through {@link normalizePosixPath}.
+ * @returns the parent directory.
+ */
+export declare function posixDirname(normalized: string): string;
+/**
+ * The key one root answers to, spelled the way **both halves** must spell it:
+ * `local:<normalized local path>` or `remote:<connectionId>:<normalized POSIX path>`.
+ *
+ * This is the string a client sends back to remove a root and the string the registry stores, so the two
+ * have to be the same function — the earlier client spelling (`local:-:<path>`, then `local:<raw path>`)
+ * produced keys the host could not match (audit 0024 §8.3, §8.5).
+ *
+ * Case is **not** folded here unless the caller asks: the host passes `{ caseInsensitive: process.platform
+ * === 'win32' }` (that is where its registry folds), and the client passes nothing because it cannot know
+ * the host's platform. Case-differing keys are therefore matched by {@link rootKeyIdentity} (the client's
+ * join) and by the host's own `sameRootKey`/`liveKeyFor` comparison — never by string equality on the key.
+ *
+ * @param location - local or remote.
+ * @param path - host path (either separator spelling) or absolute POSIX path.
+ * @param connectionId - the connection for a remote root; absent spells `remote::<path>` (the client's
+ *   fallback for a malformed answer — the host rejects such a root before it ever gets here).
+ * @param options - `caseInsensitive` folds case in a local key.
+ * @returns the key.
+ */
+export declare function rootKeySpelling(location: RootLocation, path: string, connectionId?: string, options?: RootKeyOptions): string;
+/**
+ * The identity two root keys are joined by: `local:` keys compare **case-insensitively**, remote keys do not.
+ *
+ * Why unconditional for local: the host's registry folds a Windows local path to lower case while the panel's
+ * own file keeps the caller's case, so "the same root" routinely arrives with two spellings. The host has
+ * always compared this way (`sameRootKey` in `app/roots/user-roots.ts`, out of this change's write scope);
+ * this is the client's half of the same rule, and without it a live root reads as "not in the file", which
+ * silently removes its delete button (audit 0024 §8.5).
+ *
+ * Remote paths are POSIX and therefore case-sensitive, so their keys are compared verbatim.
+ *
+ * @param key - one root key (or anything shaped like one).
+ * @returns the join identity.
+ */
+export declare function rootKeyIdentity(key: string): string;

package/lib/types/src/wiring/helpers.d.ts

@@ -141,4 +141,3 @@ export interface CredentialsLike {
 }
 /** 会话日志头读取器（原先在 index.ts 底部，被 tools 段的会话管理使用）。 */
 export declare const readSessionHeader: (dir: string) => Promise<import("../host/app/session-admin/session-admin-contract.ts").SessionHeader | undefined>;
-//# sourceMappingURL=helpers.d.ts.map