dsh-over-ssh 0.2.1 → 0.2.2

package/lib/terminal-wrapper.js

@@ -216,8 +216,9 @@ async function loadInputs(options) {
   return { manifest, sessionState: stateRaw === void 0 ? void 0 : parseSessionState(stateRaw) };
 }
 var STATE_DIR_NAMES = ["over-ssh", "remote-workspace", "ssh-dev"];
-function defaultStateDir() {
-  const base = join(homedir(), ".dsh");
+function defaultStateDir(env) {
+  const configured = env["DSH_HOME"];
+  const base = typeof configured === "string" && configured.trim() !== "" ? configured.trim() : join(homedir(), ".dsh");
   for (const name of STATE_DIR_NAMES) {
     const dir = join(base, name);
     if (existsSync(join(dir, "roots.json"))) return dir;
@@ -226,7 +227,7 @@ function defaultStateDir() {
 }
 async function decide(input) {
   const flags = parseWrapperArgs(input.argv);
-  const stateDir = flags.get("state-dir") ?? input.env["DSH_OVER_SSH_STATE_DIR"] ?? input.env["DSH_SSH_DEV_STATE_DIR"] ?? defaultStateDir();
+  const stateDir = flags.get("state-dir") ?? input.env["DSH_OVER_SSH_STATE_DIR"] ?? input.env["DSH_SSH_DEV_STATE_DIR"] ?? defaultStateDir(input.env);
   const sessionId = flags.get("session") ?? input.env["DSH_SESSION_ID"];
   const localShell = flags.get("local-shell") ?? defaultLocalShell(input.platform ?? process.platform, input.env);
   const inputs = await loadInputs({ stateDir, sessionId });

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

@@ -25,8 +25,17 @@ export interface SessionAdminDeps {
     readonly binRoot: string;
     /** List one directory's entries; a missing directory yields an empty list, not a failure. */
     readonly listDir: (path: string) => Promise<readonly SessionDirEntry[]>;
-    /** Read a session header. `undefined` means the log is unreadable (corrupt/unsupported). */
-    readonly readHeader: (sessionDir: string) => Promise<SessionHeader | undefined>;
+    /**
+     * Read a session header. `undefined` means the log is unreadable (corrupt/unsupported).
+     *
+     * `listing` is the directory contents the caller already read (for the byte sum): passing it lets the
+     * production reader use the log's `(size, mtime)` as a cache key without a second `readdir` + `stat`.
+     */
+    readonly readHeader: (sessionDir: string, listing?: readonly {
+        readonly name: string;
+        readonly bytes: number;
+        readonly mtimeMs: number;
+    }[]) => Promise<SessionHeader | undefined>;
     /**
      * Display title of the workspace that owns a session directory, or `undefined` when none does.
      *

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

@@ -160,6 +160,14 @@ export interface Ssh2Session {
     forwardOut(sourceAddress: string, sourcePort: number, destinationAddress: string, destinationPort: number, callback: (error?: Error, stream?: unknown) => void): void;
     end(): void;
     destroy(): void;
+    /**
+     * Lifecycle events of the underlying connection, when the implementation exposes them.
+     *
+     * Optional because the type is a structural minimum: tests' fakes and the alias transport need not implement
+     * it. The real `ssh2` `Client` does.
+     */
+    on?(event: 'close' | 'error' | 'end', listener: (...args: unknown[]) => void): unknown;
+    off?(event: 'close' | 'error' | 'end', listener: (...args: unknown[]) => void): unknown;
     /**
      * Intermediate jump-host sessions this session rides on, so `dispose()` can close them too.
      *

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

@@ -84,7 +84,10 @@ export interface RoutedFsProviderOptions {
      * here so a test can drive the sync without a Cordis host. Returning `[]` is always safe: it disables the
      * sync and leaves every existing behaviour untouched.
      */
-    readonly sessionWorkspaceCwds?: () => readonly string[];
+    readonly sessionWorkspaceCwds?: () => readonly (string | {
+        readonly sessionId: string;
+        readonly cwd: string;
+    })[];
     /**
      * The fork lineage of one session, nearest first (ADR-0013).
      *
@@ -104,8 +107,11 @@ export declare class RoutedFsProvider extends FileSystem {
     static inject: string[];
     protected readonly rangeReader: BackendRangeReader | undefined;
     protected readonly rangeChunkBytes: number;
-    /** Reads the live sessions' working directories; see {@link RoutedFsProviderOptions.sessionWorkspaceCwds}. */
-    protected readonly sessionWorkspaceCwds: () => readonly string[];
+    /** Reads the live sessions' working directories (with ids when available); see {@link RoutedFsProviderOptions.sessionWorkspaceCwds}. */
+    protected readonly sessionWorkspaceCwds: () => readonly (string | {
+        readonly sessionId: string;
+        readonly cwd: string;
+    })[];
     /** Reads one session's fork lineage; see {@link RoutedFsProviderOptions.sessionAncestors}. */
     protected readonly sessionAncestors: (sessionId: string) => readonly string[];
     /**

package/lib/types/src/host/integration/session/session-header.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Read a session log's header line, with a **bounded** memory footprint.
+ *
+ * Why this is its own module: the reader used to live in the composition root (`src/index.ts`), where no
+ * test can reach it (审计 0046 记录了同款教训). A file-system reader is exactly the kind of code that needs a
+ * test to pin its *bounds*, and the bound is the whole point here.
+ *
+ * ## What went wrong before
+ *
+ * The old reader claimed to "decompress only the head" but read the **whole file** first:
+ *
+ * ```ts
+ * const handle = await readFile(path);                                    // 10.9 MiB for one real session
+ * text = zstdDecompressSync(handle.subarray(0, 256 * 1024)).toString();   // cap applies to the SLICE only
+ * } catch {
+ *   text = zstdDecompressSync(await readFile(path)).toString();           // and the fallback reads it AGAIN
+ * }
+ * ```
+ *
+ * `readFile` has no `maxBytes`, so the 256 KiB constant bounded the decompressor's *input*, never the read.
+ * Measured on the reference machine's real store (73 sessions): **105.3 MiB** read into memory to extract
+ * 73 first lines (19 KiB of output), worst single session **10.9 MiB**, and 51 of 73 logs exceeded the
+ * "cap" that was supposedly in force. See `doc/06-audits/0050`.
+ *
+ * ## What went wrong the second time (2026-10-31)
+ *
+ * The fallback decompressed the head with `zstdDecompressSync`, which requires a **complete frame** and answers
+ * `Z_BUF_ERROR` for anything shorter. That was true of the store it was written against (one small frame per
+ * record) and is **not** true of the current one: a 13.2 MB session compresses its head into a frame far larger
+ * than any bounded read, so no cap could ever be "complete". Measured on this machine's real store: 8 of 19
+ * sessions in one workspace were classified `unreadable`, and every one had an intact header line — 64 KiB of a
+ * 13.2 MB log stream-decodes to 184 KB of text whose first line is the header. Users saw it as
+ * 「该会话无法读取，不能删除」 on a perfectly healthy session.
+ *
+ * The fix is to decode **incrementally**: feed the bounded prefix to a stream decoder, keep the output until the
+ * first newline, then stop. A truncated frame ending in an `error` event is the normal case here.
+ *
+ * ## The contract this module implements
+ *
+ *  1. **Never read more than `cap` bytes of any one file.** The read is a positioned `read(2)` off a
+ *     descriptor, so the file's size is irrelevant to peak memory.
+ *  2. **The fallback is bounded too.** A slice that ends inside a zstd frame can be rejected by the
+ *     decoder; the retry asks for a larger head (`retryBytes`), never for the whole file.
+ *  3. **Failure is `undefined`, never a throw.** A directory with no log, a corrupt frame, or an
+ *     unparsable first line all yield `undefined`, so the inventory classifies the session as
+ *     `unreadable` instead of guessing from the lossy directory name (ADR-0009).
+ *
+ * @module dsh-over-ssh/integration/session-header
+ */
+import type { SessionHeader } from '../../app/session-admin/session-admin-service.ts';
+/**
+ * Bytes read from the head of a session log on the first attempt.
+ *
+ * Chosen from measurement, not taste. On the reference machine's real store (73 sessions, `0050`):
+ *
+ *  - the largest **header line** is **309 B** of UTF-8 (p50 279 B);
+ *  - the largest compressed frame carrying a lone header is **253 B**;
+ *  - the smallest head that recovered **all 73** headers is **4 KiB**.
+ *
+ * 64 KiB is therefore **16x** the empirically sufficient head and **212x** the largest header line, while
+ * being 4x smaller than the previous (and, as it turned out, entirely non-binding) 256 KiB constant.
+ */
+export declare const SESSION_HEADER_READ_BYTES: number;
+/**
+ * Bytes read on the retry, when the first slice ended inside the frame.
+ *
+ * Still bounded, and still independent of the file's real size — that is the property the old fallback
+ * broke. A log whose header genuinely cannot be recovered from 1 MiB is reported `unreadable`.
+ */
+export declare const SESSION_HEADER_RETRY_BYTES: number;
+/** The I/O this reader needs; injected so a test can pin the byte bounds exactly (AGENTS.md 红线 3). */
+export interface SessionHeaderIo {
+    /** List one directory's entry names. */
+    readonly listDir: (dir: string) => Promise<readonly string[]>;
+    /**
+     * Read at most `maxBytes` from the **head** of one file.
+     *
+     * An implementation must not read the whole file and slice: that is precisely the defect this module
+     * exists to prevent. It may return fewer bytes (a short file, or a short read).
+     */
+    readonly readHead: (path: string, maxBytes: number) => Promise<Uint8Array>;
+    /**
+     * Decompress a zstd frame **or frame prefix** to UTF-8 text.
+     *
+     * May be async: a prefix has to be decoded incrementally (see {@link decompressPrefix}), and a partial frame
+     * is expected rather than exceptional.
+     */
+    readonly decompress: (bytes: Uint8Array) => string | Promise<string>;
+    /** Head caps to try, in order. Defaults to `[SESSION_HEADER_READ_BYTES, SESSION_HEADER_RETRY_BYTES]`. */
+    readonly caps?: readonly number[];
+    /**
+     * Size and mtime of one file, when the implementation can answer it cheaply.
+     *
+     * Only the cache below uses it: it lets a repeated inventory skip the 64 KiB head read **and** the zstd
+     * decode when the log has not changed. Optional so tests and other IO seams stay two-method simple.
+     */
+    readonly stat?: (path: string) => Promise<{
+        readonly size: number;
+        readonly mtimeMs: number;
+    }>;
+}
+/**
+ * A **signature-keyed** wrapper around {@link createSessionHeaderReader}.
+ *
+ * Why: an inventory refreshes on every panel open and after every delete/restore, and each refresh used to read
+ * 64 KiB of every session log plus a zstd decode — 31 live sessions measured **13.96 ms** of header work per
+ * refresh, against **1.35 ms** for the `stat` calls alone. Reusing a header while the log's `(size, mtime)` is
+ * unchanged turns that into the stat cost; a real change (new turn, compaction) changes the signature and the
+ * cache misses for that one session.
+ *
+ * Bounded as this repository requires of every cache: at most `maxEntries` sessions (LRU, the same rule as the
+ * ancestor cache) and no timers. The value is a header object plus a short signature, so the worst case at
+ * {@link SESSION_HEADER_CACHE_MAX} is ≈256 KB — small enough that a separate byte budget would be accounting
+ * theatre, and stated here so the bound can be re-derived. Negative answers are cached too: an unreadable session
+ * stays unreadable until its log changes, and re-decoding a corrupt 4 MiB head on every refresh is the exact cost
+ * this removes.
+ *
+ * @param io - the same IO seam {@link createSessionHeaderReader} takes; `stat` is required for the cache to work
+ *   (without it this returns the uncached reader, so a partial seam stays correct rather than slower).
+ * @param options - `maxEntries` (default {@link SESSION_HEADER_CACHE_MAX}).
+ * @returns a reader from one session directory to its header.
+ */
+export interface HeaderListingEntry {
+    readonly name: string;
+    /** File size; the cache signature uses it instead of a fresh `stat` when the caller already has it. */
+    readonly size: number;
+    readonly mtimeMs: number;
+}
+export declare function createCachedSessionHeaderReader(io: SessionHeaderIo, options?: {
+    readonly maxEntries?: number;
+}): (dir: string, listing?: readonly HeaderListingEntry[]) => Promise<SessionHeader | undefined>;
+/**
+ * Upper bound on the header cache.
+ *
+ * **Why not 256**: one inventory pass touches every session in order, so a capacity smaller than the session
+ * count makes the pass evict its own entries — the cache then pays a `readdir` + `stat` and still misses, which
+ * measured *worse* than no cache at all (300 sessions: 43.89 ms with a 256-entry cache vs 32.21 ms without;
+ * 400 sessions: 49.29 vs 35.89). 2048 covers a large real store (2 × 1024 sessions) and costs at most
+ * ≈2 MB of header objects; past that the LRU still bounds growth.
+ */
+export declare const SESSION_HEADER_CACHE_MAX = 2048;
+/**
+ * Parse the first JSONL line into the header fields this feature needs.
+ *
+ * @param text - decompressed log text (only the head is present).
+ * @returns the header, or `undefined` when the first line is absent or not a session record.
+ */
+export declare function parseSessionHeaderLine(text: string): SessionHeader | undefined;
+/**
+ * Build the header reader.
+ *
+ * Every failure is reported as `undefined` rather than thrown: an inventory must survive one unreadable
+ * session.
+ *
+ * @param io - directory listing, bounded head read and decompressor.
+ * @returns a reader from one session directory to its header, or `undefined` when unreadable.
+ */
+export declare function createSessionHeaderReader(io: SessionHeaderIo): (dir: string) => Promise<SessionHeader | undefined>;
+/**
+ * Decode a zstd frame **prefix** to text, stopping at the first complete line.
+ *
+ * Why not `zstdDecompressSync`: it requires a complete frame and answers `Z_BUF_ERROR` for a prefix. The current
+ * session store writes frames far larger than any bounded read, so every such log was classified `unreadable`
+ * (see the module note). The stream decoder emits what it can from the prefix it was given; a truncated frame
+ * ends in an `error` event with the partial output already delivered, which is the **normal** case here.
+ *
+ * Bounded on purpose: collection stops at the first newline (the header is one line) and the stream is
+ * destroyed, so decoding a 13 MB log's head never materialises the body.
+ *
+ * @param bytes - the bounded head read from the log.
+ * @returns the decoded text (possibly a prefix, possibly empty), never a throw.
+ */
+export declare function decompressPrefix(bytes: Uint8Array): Promise<string>;
+/**
+ * Read at most `maxBytes` from the head of a file, off a descriptor.
+ *
+ * A positioned read is what makes the bound real: `readFile` would materialise the entire log first.
+ *
+ * @param path - file to read.
+ * @param maxBytes - hard ceiling on the bytes returned.
+ * @returns the bytes actually read (possibly fewer, possibly none).
+ */
+export declare function readHeadFromDisk(path: string, maxBytes: number): Promise<Uint8Array>;
+/**
+ * The production I/O: real `readdir`, a **bounded** head read and the real zstd decoder.
+ *
+ * Exported so a test can pin the one property the reader's whole contract rests on — that the production
+ * `readHead` respects its cap. Exercising the assembled reader through an *injected* fake cannot catch a
+ * regression in this wiring, because the fake stays bounded either way; a mutation experiment during
+ * audit 0050 exposed exactly that gap.
+ *
+ * @returns the production I/O bundle.
+ */
+export declare function createDiskSessionHeaderIo(): SessionHeaderIo;
+/**
+ * The production reader: real `readdir`, a bounded head read and the real zstd decoder.
+ *
+ * @returns a reader from one session directory to its header, or `undefined` when unreadable.
+ */
+export declare function createDiskSessionHeaderReader(): (dir: string, listing?: readonly HeaderListingEntry[]) => Promise<SessionHeader | undefined>;

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

@@ -149,4 +149,4 @@ export interface CredentialsLike {
     } | undefined;
 }
 /** 会话日志头读取器（原先在 index.ts 底部，被 tools 段的会话管理使用）。 */
-export declare const readSessionHeader: (dir: string) => Promise<import("../host/app/session-admin/session-admin-contract.ts").SessionHeader | undefined>;
+export declare const readSessionHeader: (dir: string, listing?: readonly import("../host/integration/session/session-header.ts").HeaderListingEntry[]) => Promise<import("../host/app/session-admin/session-admin-contract.ts").SessionHeader | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-over-ssh",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "SSH remote development for DeepSeek Harness: connections (key/password/ProxyJump/ssh config), remote files without sync, remote terminal, remote workspaces, remote @-completion, upload/download.",
   "type": "module",
   "main": "lib/index.js",