@tiphareth/dsh-hardssh 0.1.2-alpha → 0.2.2

package/lib/types/ssh/protocol.d.ts

@@ -80,6 +80,16 @@ export interface ClusterResult {
     stderr?: string;
     durationMs?: number;
     error?: string;
+    /** Stable machine code for a per-host failure (B-14) — lets callers retry
+     *  on an auth/TOFU gate instead of parsing the human message. */
+    code?: 'NEEDS_PASSWORD' | 'HOST_KEY_UNKNOWN' | 'HOST_KEY_MISMATCH' | 'ALIAS_NOT_FOUND' | 'ABORTED' | 'TIMEOUT' | 'ERROR';
+    /** Which secret the host needs when `code` is NEEDS_PASSWORD. */
+    secret?: 'password' | 'passphrase';
+    /** Server-key fingerprint for HOST_KEY_UNKNOWN / HOST_KEY_MISMATCH. */
+    hostKeyFingerprint?: string;
+    /** Expected/actual fingerprints for HOST_KEY_MISMATCH. */
+    expected?: string;
+    actual?: string;
 }
 /** SFTP transfer progress frame (upload stream). */
 export interface TransferProgress {
@@ -227,10 +237,18 @@ export type KnownHostAction = 'trust' | 'forget';
 export type TransferStreamLine = {
     type: 'progress';
     progress: TransferProgress;
+}
+/** The final remote rename is about to start; loss after this point means
+ *  the target's result is unknown until inspected. */
+ | {
+    type: 'commit';
 } | {
     type: 'result';
     ok: boolean;
     transferredBytes?: number;
     error?: string;
+    code?: string;
+    secret?: 'password' | 'passphrase';
+    hostKeyFingerprint?: string;
 };
 //# sourceMappingURL=protocol.d.ts.map

package/lib/types/ssh/routes.d.ts

@@ -21,8 +21,8 @@ export interface SshRoutesDeps {
     knownHosts?: KnownHostsStore;
     /** Credential vault (optional; enables /api/dsh-ssh/vault endpoints). */
     vault?: import('./vault.ts').Vault;
-    /** SSH-bound workspace ledger (host-delete reference check). */
-    ledger?: import('../ledger.ts').SshWorkspaceLedger;
+    /** SSH-bound workspace record source (host-delete reference check). */
+    ledger?: import('../backend.ts').WorkspaceStoreView;
     /** Temp dir for upload/download staging (tests inject a sandbox). */
     stagingDir?: string;
     /** Hard cap on ACTUAL upload bytes accepted (chunked requests included).
@@ -32,13 +32,21 @@ export interface SshRoutesDeps {
      *  remote environment cache) can drop that alias. */
     onHostInvalidated?: (alias: string) => void;
 }
+/** Every /api/dsh-ssh route plus the terminal upgrade, owned by one call. */
+export interface SshRoutes {
+    routes: WebRoute[];
+    upgrade: WebUpgradeRoute;
+    /**
+     * Release this instance's terminal resources: refuse new upgrades, close
+     * every live terminal session (and its SSH shell), close the WebSocketServer.
+     * Idempotent — a second call resolves without touching anything.
+     */
+    dispose: () => Promise<void>;
+}
 /**
  * Build every /api/dsh-ssh route (exact paths) plus the terminal upgrade.
  * @param deps - store, engine, staging dir.
- * @returns routes and the upgrade route.
+ * @returns routes, the upgrade route, and this instance's disposer.
  */
-export declare function makeRoutes(deps: SshRoutesDeps): {
-    routes: WebRoute[];
-    upgrade: WebUpgradeRoute;
-};
+export declare function makeRoutes(deps: SshRoutesDeps): SshRoutes;
 //# sourceMappingURL=routes.d.ts.map

package/lib/types/ssh/sftp/service.d.ts

@@ -0,0 +1,216 @@
+import { Client } from 'ssh2';
+import type { ClientLease } from '../connection/lease.ts';
+import type { TransferProgress } from '../protocol.ts';
+/** Lets an SFTP operation declare the point after which replay is unsafe. */
+export interface SftpOperationControl {
+    markCommitted(): void;
+}
+/** Options for one access.withClient() call. */
+export interface SftpClientOptions {
+    /** Total acquire+operation attempt budget (default 3). */
+    attempts?: number;
+    retryPolicy?: 'never' | 'connect-only' | 'idempotent';
+    signal?: AbortSignal;
+}
+/**
+ * Narrow connection dependency of the SFTP component: the pooled lease
+ * acquisition plus the engine's retry/replay policy. The component owns the
+ * lease for the whole operation (including the lifetime of a returned read
+ * stream) and never reaches into the pool's bookkeeping.
+ */
+export interface SftpClientAccess {
+    withClient<T>(alias: string, fn: (client: Client, control: SftpOperationControl) => Promise<T>, options?: SftpClientOptions): Promise<T>;
+    acquire(alias: string, options: {
+        kind: 'operation' | 'stream';
+        signal?: AbortSignal;
+    }): Promise<ClientLease>;
+}
+/**
+ * The engine knobs the SFTP component reads. Keyed exactly like the engine's
+ * resolved options, so every SFTP deadline/concurrency keeps one source of
+ * truth.
+ */
+export interface SftpOptions {
+    sftpConcurrency: number;
+    sftpOpenTimeoutMs: number;
+    sftpOperationTimeoutMs: number;
+    sftpReadTimeoutMs: number;
+    maxReadFileBytes: number;
+    sftpTransferIdleTimeoutMs: number;
+    sftpRecursiveRmTimeoutMs: number;
+}
+/**
+ * Owns every SFTP operation for the engine: one cached subsystem channel per
+ * live pooled client (plus its cancellation), the per-request deadlines, and
+ * the upload/download/ls/stat/read/write/mkdir/rm/rename surface.
+ */
+export declare class SftpService {
+    private readonly access;
+    private readonly sftpOpts;
+    /**
+     * One cached SFTP subsystem channel per live client. `Client.sftp()` opens a
+     * NEW subsystem channel on every call and OpenSSH caps open sessions per
+     * connection (MaxSessions, default 10) —reopening SFTP per operation lets
+     * channels pile up on the pooled long-lived connection until listing/reading
+     * fails intermittently. Caching one channel per client fixes that; the pool
+     * drops the cache via onClientDisposed when a connection is torn down.
+     */
+    private readonly cache;
+    constructor(access: SftpClientAccess, sftpOpts: SftpOptions);
+    /** Upload one local file (or directory tree) to a remote path. */
+    upload(alias: string, localPath: string, remotePath: string, recursive: boolean, onProgress?: (progress: TransferProgress) => void, signal?: AbortSignal): Promise<{
+        bytes: number;
+        files: number;
+    }>;
+    /** Download one remote file to a local path. */
+    download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, signal?: AbortSignal): Promise<{
+        bytes: number;
+    }>;
+    /** List a remote directory (file browser). Bounded by a timeout so a
+     *  stalled SFTP request fails instead of leaving the file tree spinning. */
+    ls(alias: string, path: string, signal?: AbortSignal): Promise<import('../protocol.ts').RemoteDirEntry[]>;
+    /**
+     * Resolve many remote paths to their canonical form in one SFTP pass
+     * (P1-26): one lease + one batch of `sftp.realpath` calls instead of N
+     * `realpath` execs. A path that cannot resolve (dangling symlink, vanished
+     * entry) fails the whole batch — callers treat an unresolvable listing as
+     * an error rather than silently using an uncanonical path.
+     */
+    realpaths(alias: string, remotePaths: readonly string[], signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Classify readdir entries, following symlinks so a link to a directory
+     * (e.g. AutoDL's /root/autodl-tmp) lists as a directory instead of 'other'.
+     * Symlinks are stat'd in PARALLEL batches: serializing them turns a conda /
+     * venv bin full of links into N round-trips (seconds to tens of seconds on a
+     * slow link) — batching keeps it to a handful of round-trips. The whole pass
+     * is bounded by ls()'s timeout.
+     */
+    classifyEntries(sftp: import('ssh2').SFTPWrapper, dirPath: string, list: Array<{
+        filename: string;
+        attrs: import('ssh2').Stats;
+    }>): Promise<import('../protocol.ts').RemoteDirEntry[]>;
+    /** Stat one remote path (file browser / conflict checks). Bounded by a timeout. */
+    stat(alias: string, remotePath: string, signal?: AbortSignal): Promise<{
+        type: 'dir' | 'file' | 'other';
+        size: number;
+        mtimeMs: number;
+        mode: number;
+    }>;
+    /**
+     * Lstat one remote path without following the final symlink. Returns
+     * undefined when the path is absent (the fs seam's lstat contract).
+     */
+    lstat(alias: string, remotePath: string, signal?: AbortSignal): Promise<{
+        type: 'file' | 'directory' | 'symlink' | 'other';
+        size: number;
+        mtimeMs: number;
+        mode: number;
+    } | undefined>;
+    /**
+     * Open a remote file read stream (the fs seam's streamText). The returned
+     * stream must be consumed or destroyed; the pooled connection stays busy
+     * for the stream's lifetime.
+     */
+    /**
+     * Open a remote file read stream (the fs seam's streamText). The returned
+     * stream must be consumed or destroyed; the pooled connection stays busy
+     * for the stream's lifetime (P0-10: a 'stream' lease, released on
+     * end/close/error/destroy — not when this function returns).
+     */
+    readStream(alias: string, remotePath: string, signal?: AbortSignal): Promise<import('node:stream').Readable>;
+    /**
+     * Read one remote file fully into memory (text or binary) with its mtime.
+     * The workspace plugin's text gate (UTF-8 + size caps) lives on its caller.
+     */
+    readFile(alias: string, remotePath: string, maxBytes?: number, signal?: AbortSignal): Promise<{
+        content: Buffer;
+        mtime: number;
+        size: number;
+    }>;
+    /**
+     * Write one remote file from memory (parents are created). When
+     * `expectedMtime` is given, a stat-then-write conflict check throws before
+     * any byte is written (the GUI and the workspace tools use it for
+     * overwrite protection).
+     */
+    writeFile(alias: string, remotePath: string, content: Buffer, expectedMtime?: number, signal?: AbortSignal): Promise<{
+        mtime: number;
+    }>;
+    /** Create a remote directory chain (mkdir -p semantics). */
+    mkdir(alias: string, remotePath: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Remove a remote file or directory. Directories require `recursive: true`
+     * and are walked depth-first (children first, then the directory itself).
+     *
+     * Deletion never follows symlinks: every node is classified with lstat, so
+     * a symlink pointing at a directory is unlinked (only the link), never
+     * recursed into — the old stat/readdir-attr check could delete the link
+     * target's contents.
+     */
+    rm(alias: string, remotePath: string, recursive?: boolean, signal?: AbortSignal): Promise<void>;
+    /** Rename / move a remote path (mv semantics, same filesystem). */
+    rename(alias: string, fromPath: string, toPath: string, signal?: AbortSignal): Promise<void>;
+    /** Reject a promise after `ms` (unref'd so it never keeps the process alive).
+     *  `onTimeout` (when given) runs right before the rejection: ssh2 SFTP
+     *  requests have no cancel API, so callers that hold an abort handle (e.g.
+     *  a read stream) destroy it here — otherwise the underlying transfer would
+     *  keep running (and, for reads, keep buffering) after the caller was told
+     *  it timed out. */
+    withTimeout<T>(promise: Promise<T>, ms: number, message: string, onTimeout?: () => void): Promise<T>;
+    /** Bound one SFTP request and retire the subsystem only when it is safe.
+     *
+     * Every request rides ONE cached subsystem channel per pooled client. Closing
+     * that channel on a single request's timeout used to destroy every concurrent
+     * SFTP operation on the same connection. A timeout therefore only MARKS the
+     * channel suspect; the decision to close it belongs to the drain path, which
+     * ends it exactly once the last in-flight request has settled — so a stalled
+     * callback cannot linger behind another lease, and a healthy concurrent request
+     * is never destroyed. */
+    withSftpTimeout<T>(sftp: import('ssh2').SFTPWrapper, promise: Promise<T>, ms: number, message: string, onTimeout?: () => void): Promise<T>;
+    /** Count one operation against a cached subsystem's in-flight set. */
+    private enter;
+    /** End one operation's count; rotate a suspect channel only once it drains. */
+    private leave;
+    /**
+     * Retire a subsystem after a timeout without destroying concurrent SFTP work.
+     *
+     * A cached channel is SHARED by every operation on the pooled client, so
+     * closing it here would fail whatever else is in flight. Instead it is marked
+     * suspect and rotated by `leave()` once the last operation finishes. Only a
+     * wrapper this service does not track (a direct caller) is ended immediately.
+     *
+     * @param sftp - the subsystem that timed out.
+     */
+    private retireSharedSubsystem;
+    /** The cache entry owning one resolved subsystem channel, if still cached. */
+    private entryFor;
+    /** Drop a suspect channel once it has drained, so the next call reopens. */
+    private rotateSuspect;
+    /** Stat wrapper (one SFTP stat call). */
+    sftpStat(sftp: import('ssh2').SFTPWrapper, remotePath: string): Promise<import('ssh2').Stats>;
+    /** Lstat wrapper (does NOT follow symlinks — the deletion safety gate). */
+    sftpLstat(sftp: import('ssh2').SFTPWrapper, remotePath: string, timeoutMs?: number): Promise<import('ssh2').Stats>;
+    /** Unlink wrapper with the same per-operation deadline as every other SFTP callback. */
+    sftpUnlink(sftp: import('ssh2').SFTPWrapper, remotePath: string, timeoutMs?: number): Promise<void>;
+    /**
+     * The (cached) SFTP channel for a pooled client. `Client.sftp()` opens a new
+     * subsystem channel per call, so this memoizes one channel per live client;
+     * when the channel closes the cache entry is dropped so the next call opens
+     * SFTP on the replacement connection. Failed opens are also evicted so a
+     * transient channel failure can be retried.
+     */
+    sftpFor(client: Client): Promise<import('ssh2').SFTPWrapper>;
+    /** Create a remote directory chain (stat-then-mkdir per segment). */
+    ensureRemoteDir(sftp: import('ssh2').SFTPWrapper, remote: string): Promise<void>;
+    fastPut(sftp: import('ssh2').SFTPWrapper, src: string, dst: string, onProgress?: (progress: TransferProgress) => void): Promise<void>;
+    fastGet(sftp: import('ssh2').SFTPWrapper, src: string, dst: string, initialTotal: number, onProgress?: (progress: TransferProgress) => void): Promise<void>;
+    /**
+     * Drop one client's cached channel. Wired as the connection pool's
+     * onDispose hook, so a torn-down client never keeps a half-open SFTP
+     * subsystem behind it.
+     */
+    onClientDisposed(client: Client, error: Error): void;
+    /** Drop every cached channel (engine dispose). */
+    dispose(error: Error): void;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/ssh/store.d.ts

@@ -35,6 +35,8 @@ export declare class HostStore {
     constructor(path?: string, sshConfigOverride?: string);
     /** Load all entries (empty store when the file is absent). */
     list(): SshHostEntry[];
+    /** The ssh-config path this store reads (override or the default). */
+    get sshConfigOverridePath(): string | undefined;
     /** Find one entry by alias. */
     find(alias: string): SshHostEntry | undefined;
     /** Secret-free projection for the browser and agent surfaces. */
@@ -48,7 +50,8 @@ export declare class HostStore {
     /**
      * Import hosts from `~/.ssh/config`: Host blocks with a single non-wildcard
      * pattern and a HostName become entries (key auth via IdentityFile, jump
-     * hosts via ProxyJump). Existing aliases are skipped.
+     * hosts via ProxyJump). Existing aliases are skipped. Each entry is created
+     * through this store's own `create`, which keeps plaintext secrets inline.
      * @returns import statistics.
      */
     importFromSshConfig(): ImportResult;
@@ -77,8 +80,9 @@ export interface ResolvedAuth {
  *
  * - **'none' (default, VSCode Remote-SSH style)**: secrets are NEVER
  *   persisted. create/update strip the password/passphrase from the entry
- *   (kind + keyPath stay); the engine prompts once per session and holds the
- *   credential in-memory (session password table). The plaintext HostStore
+ *   (kind + keyPath stay); the engine prompts once and holds the credential
+ *   in-memory for that CONNECTION's lifetime (the pool's retirement drops it).
+ *   The plaintext HostStore
  *   remains untouched, so existing v1 tests and dual-format reads keep
  *   working.
  */
@@ -86,19 +90,27 @@ export declare class SecureHostStore {
     private readonly vault;
     private readonly mode;
     private readonly inner;
+    private readonly pendingSecretCleanup;
     constructor(vault: import('./vault.ts').Vault | undefined, path?: string, sshConfigOverride?: string, mode?: 'none' | 'vault');
     list(): SshHostEntry[];
     find(alias: string): SshHostEntry | undefined;
     summarize(entry: SshHostEntry): SshHostSummary;
     get path(): string;
-    /** Legacy ssh-config import (delegates; passwords imported stay inline —
-     *  a follow-up may route them through the vault). */
-    importFromSshConfig(): ImportResult;
-    /** Create: secrets are stashed per mode; entry only keeps kind (+ keyPath). */
+    /** The ssh-config path the underlying store reads (override or default). */
+    get sshConfigOverridePath(): string | undefined;
+    /** ssh-config import routed through THIS store's `create`, so every imported
+     *  credential is handled per `secretStorage` (never persisted in 'none' mode,
+     *  vault-encrypted in 'vault' mode) instead of being stored inline. */
+    importFromSshConfig(): Promise<ImportResult>;
+    /** Deferred best-effort cleanup queue (diagnostics/tests; contains no plaintext). */
+    pendingSecretCleanupRefs(): string[];
+    private removeSecret;
+    private retryPendingCleanup;
+    /** Create: secrets are staged, then rolled back if host persistence fails. */
     create(payload: HostPayload): Promise<SshHostEntry>;
     /** Update: auth present -> re-stash (or strip in none mode); absent → keep. */
     update(alias: string, patch: Partial<HostPayload>): Promise<SshHostEntry>;
-    /** Delete: drop the host (and its vault secrets in vault mode, best-effort). */
+    /** Delete the host first; vault cleanup can then only leave an orphan. */
     delete(alias: string): Promise<void>;
     /** Resolve the authentication for one entry (vault reveal when needed). */
     resolveAuth(entry: SshHostEntry): Promise<ResolvedAuth>;

package/lib/types/ssh/terminal/service.d.ts

@@ -0,0 +1,49 @@
+import type { Client } from 'ssh2';
+import type { ExecSession, ShellSession } from '../engine.ts';
+/**
+ * Narrow connection dependency used by the standalone terminal transports.
+ * `connectStandalone` must reach the store itself (the not-found wording is
+ * this component's own contract) and must always return a PRIVATE connection
+ * — never a pooled one.
+ */
+export interface TerminalConnectionAccess {
+    connectStandalone(alias: string): Promise<{
+        client: Client;
+        hops: Client[];
+    }>;
+}
+/**
+ * Owns the standalone PTY-shell / streaming-exec transports: one exclusive
+ * connection per session (closing a shell can therefore never tear down a
+ * pooled exec or tunnel sharing the alias), the channel-open deadline,
+ * idempotent teardown and session assembly.
+ */
+export declare class TerminalService {
+    private readonly connection;
+    /** Teardowns of live standalone transports, so dispose() can close sessions
+     *  that the caller never closed explicitly (openShell/openExec own their
+     *  whole connection and would otherwise outlive the engine). */
+    private readonly activeTeardowns;
+    constructor(connection: TerminalConnectionAccess);
+    /**
+     * Open one standalone channel on its own connection (never a pooled one).
+     * Shared by openShell/openExec: alias lookup, jump chain, channel-open
+     * timeout, idempotent teardown, and late-callback cleanup live here, so the
+     * two public methods keep only their session-specific assembly.
+     */
+    private openStandaloneChannel;
+    /** Open a PTY shell session for the web terminal (standalone connection). */
+    openShell(alias: string, size: {
+        cols: number;
+        rows: number;
+    }): Promise<ShellSession>;
+    /**
+     * Open a streaming exec channel (no PTY) for the remote subprocess seam.
+     * Like the PTY shell, the channel rides its own connection so closing it
+     * can never tear down a pooled exec/tunnel sharing the alias.
+     */
+    openExec(alias: string, command: string): Promise<ExecSession>;
+    /** Close every standalone transport this service still owns. */
+    dispose(): void;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/ssh/tunnel/service.d.ts

@@ -0,0 +1,26 @@
+import type { SshConnectionService } from '../connection/pool.ts';
+import type { SshHostEntry, TunnelInfo } from '../protocol.ts';
+/** Narrow connection dependency used by the tunnel component. */
+export interface TunnelConnectionAccess {
+    readonly connections: SshConnectionService;
+    findEntry(alias: string): SshHostEntry | undefined;
+}
+/** Owns local listeners, forwarded sockets, and tunnel leases. */
+export declare class TunnelService {
+    private readonly connection;
+    private readonly tunnels;
+    private nextTunnelId;
+    constructor(connection: TunnelConnectionAccess);
+    private removeClientFailureListener;
+    private markFailedForClient;
+    startTunnel(alias: string, options: {
+        remotePort: number;
+        remoteHost?: string;
+        localPort?: number;
+    }): Promise<TunnelInfo>;
+    listTunnels(): TunnelInfo[];
+    stopTunnel(id: string): boolean;
+    stopAllTunnels(alias?: string): number;
+    dispose(): void;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/ssh/vault.d.ts

@@ -13,6 +13,8 @@
  *
  * @module dsh-hardssh/vault
  */
+/** Minimum non-whitespace master-password length. */
+export declare const MIN_MASTER_PASSWORD_LENGTH = 8;
 /** Types of secrets the vault stores. */
 export type VaultPurpose = 'host.password' | 'host.passphrase';
 /** KDF parameters persisted in the file header. */
@@ -29,8 +31,37 @@ export interface VaultStatus {
     mode: 'env' | 'password';
     entries: number;
 }
-/** Default vault file location: <home>/.dsh/dsh-ssh-vault.json. */
+/**
+ * Directory holding the credential vault: `<home>/.dsh/ssh-secrets`.
+ *
+ * It IS inside `~/.dsh` (which the fs seam declares a local-infrastructure root
+ * so skills and plugin config stay readable), so its protection does NOT come
+ * from location — it comes from `SwitchFileSystem.deniedRoots` (fs.ts), which
+ * refuses this directory on every dispatch path, resolve to write, before any
+ * backend sees it.
+ *
+ * Residual risk, stated plainly: a command that runs on THIS machine as the
+ * same user (e.g. the client-side `pwsh` tool) can still read the file. What
+ * keeps the credential safe is that the file is encrypted (AES-256-GCM +
+ * scrypt) AND that environment auto-unlock is off by default — so a stolen
+ * ciphertext is only an offline scrypt target, not a usable credential.
+ */
+export declare function vaultDirectory(): string;
+/** Vault file location: <home>/.dsh/ssh-secrets/dsh-ssh-vault.json. */
 export declare function vaultPath(): string;
+/** Pre-relocation vault location (<home>/.dsh/dsh-ssh-vault.json). */
+export declare function legacyVaultPath(): string;
+/**
+ * Move a pre-relocation vault into {@link vaultDirectory} on first use.
+ *
+ * Never destructive: the new location wins when both exist, and a failed move
+ * falls back to copying so the source file is left in place.
+ *
+ * @param target - destination path (defaults to {@link vaultPath}).
+ * @param legacy - source path (defaults to {@link legacyVaultPath}).
+ * @returns true when a move/copy happened.
+ */
+export declare function migrateLegacyVault(target?: string, legacy?: string): boolean;
 /** SHA3-256 hex of a UTF-8 string. */
 export declare function sha3_256Hex(text: string): string;
 /** Errors raised by the vault. */
@@ -64,19 +95,31 @@ export interface RevealedSecret {
  */
 export declare class Vault {
     private readonly path;
-    private readonly passwordProvider;
     private document;
     private unlockedKey;
     private lockTimer;
+    private readonly idleLockMs;
     private readonly leaked;
+    /** Whether `DSH_CREDENTIAL_PASSWORD` may unlock this instance at load. */
+    private readonly allowEnvUnlock;
+    /** Single-instance mutation queue. Every operation that can change the
+     *  in-memory document or persist it runs in invocation order. The tail is
+     *  always recovered so one rejected mutation never poisons later work. */
+    private mutationTail;
     constructor(filePath?: string, options?: {
-        /** Session password source (loopback unlock route passes a password). */
-        passwordProvider?: () => Promise<string | undefined>;
         /** Vault idle auto-lock (ms); 0 disables (default 30 min). */
         idleLockMs?: number;
+        /**
+         * Allow unlocking from `DSH_CREDENTIAL_PASSWORD` at construction.
+         * OFF by default: that variable is visible to anything running as the
+         * same user — including an agent session — so auto-unlock is an explicit
+         * opt-in (`vaultAutoUnlock: 'env'` in the plugin config), not a default.
+         */
+        allowEnvUnlock?: boolean;
     });
     private load;
     private save;
+    private saveDocument;
     private deriveKey;
     private lockoutRetryAfter;
     private checkLockout;
@@ -84,6 +127,10 @@ export declare class Vault {
     private encryptEntryBuffer;
     private decryptEntryBuffer;
     private requireKey;
+    private validateMasterPassword;
+    /** Successful credential activity extends the idle lock deadline. */
+    private touch;
+    private enqueueMutation;
     private tryEnvUnlock;
     /** Current status (locked / mode / entry count) — safe for UIs. */
     status(): VaultStatus;

package/lib/types/subprocess.d.ts

@@ -1,32 +1,24 @@
 /**
- * The `ctx.subprocess` switch row: provides the workspace-routing subprocess
- * facade in the host scope. The local runtime is mounted in an isolated
- * child scope; every SSH-bound workspace record gets its OWN remote runtime
- * bound to that record's alias + remote root; the facade routes each spawn by
- * its cwd. The facade auto-provides `subprocess` here because the plain
- * subprocess row is disabled by the profile patch.
+ * The `ctx.subprocess` switch row: provides the generic WorkspaceCore-routing
+ * subprocess facade in the host scope. The local runtime is mounted in an
+ * isolated child scope; each spawn resolves by cwd through the same workspace
+ * router used by the filesystem seam.
  *
- * Routing and per-record remote runtimes are owned by the SHARED seam state
- * (hardsshCore.seams): the row binds its per-record runtime factory and reads
- * the state on every spawn. The seam state re-applies the ledger snapshot
- * synchronously on every commit, so creating or removing an SSH workspace
- * takes effect without a plugin restart and the fs/subprocess seams can never
- * disagree. Before the initial ledger load finishes, routing degrades to
- * local with a one-time warning for anchor-root paths.
+ * A bound connection supplies `workspace.process`. Before the core is ready,
+ * or for an unowned cwd beneath the managed SSH anchor root, spawning fails
+ * closed rather than executing on the client machine.
  *
  * @module dsh-hardssh/subprocess
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { HardsshCore } from './core.ts';
-declare module '@deepseek-ai/cordis' {
-    interface Context {
-        hardsshCore: HardsshCore;
-    }
-}
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+import type { WorkspaceCore } from './runtime/workspace-core.ts';
 /** Stable cordis plugin name. */
 export declare const name = "hardssh-subprocess";
-/** Services required: the shared workspace core (mode store + engine). */
+/** Workspace routing is exclusively provided by the generic core. */
 export declare const inject: string[];
-/** Mount the switching subprocess facade. */
+/** Resolve the subprocess runtime owning a cwd, or undefined when local. */
+export declare function genericSubprocessFor(core: WorkspaceCore, cwd: string | undefined, reservedAnchorRoots: readonly string[]): SubprocessRuntime | undefined;
+/** Mount the generic switching subprocess facade. */
 export declare function apply(ctx: Context): void;
 //# sourceMappingURL=subprocess.d.ts.map

package/lib/types/switch/switch-fs.d.ts

@@ -46,20 +46,70 @@ export interface SwitchFsDeps {
     /** The world owning one namespaced target key (never undefined: every
      *  key this facade issued maps back). */
     worldForNamespace(namespace: string): WorkspaceWorld | undefined;
+    /** Client-side roots that must stay LOCAL even in a bound workspace (dsh's
+     *  own `~/.dsh` with skills & harness state, plugin configs, …). Default
+     *  routing in a remote world is REMOTE for everything else. */
+    localRoots?: ReadonlyArray<string>;
+    /** Windows inside `localRoots` that must NEVER be treated as local
+     *  infrastructure — the managed workspace ANCHOR ROOT. Anchors physically
+     *  live under `~/.dsh`, so without this carve-out a path inside the anchors
+     *  window (including a stale anchor dir with no ledger record) would fall
+     *  into the local exception and a remote session would silently write to
+     *  the client machine. Semantics: local exception = localRoots MINUS
+     *  exclusions. */
+    localRootExclusions?: ReadonlyArray<string>;
+    /** Roots whose contents are NEVER accessible through this seam — the
+     *  encrypted credential store. Enforced on every dispatch path (see
+     *  `assertNotDenied`), so a bound session's agent cannot read the vault
+     *  ciphertext through the routed filesystem and attack it offline. It does
+     *  NOT constrain a command that runs natively on this machine as the same
+     *  user (e.g. the client-side `pwsh` tool). */
+    deniedRoots?: ReadonlyArray<string>;
+    /** The world owning an ABSOLUTE workspace anchor path (the caller's own
+     *  workspace or a SIBLING workspace's anchor), or undefined when no
+     *  workspace claims that path. Consulted BEFORE the `localRoots`
+     *  carve-out: managed SSH workspace anchors live under `~/.dsh` (a
+     *  declared local root), so routing a sibling anchor to local would
+     *  silently run a remote-workspace file operation on this machine. */
+    worldForAnchorPath?(path: string): WorkspaceWorld | undefined;
 }
 /** The routing filesystem facade. */
 export declare class SwitchFileSystem extends FileSystem {
     private readonly deps;
     private readonly local;
     constructor(ctx: Context, deps: SwitchFsDeps);
-    /** Sandbox default from the local backend (remote worlds are unconfined —
-     *  the docs/doc of the tool layer reads this once at mount). */
+    /** The deployment's local backend is still a sandboxed filesystem, and
+     *  `dsh-tool-fs` reads this capability fact ONCE at apply() to decide whether
+     *  to advertise `sandbox_permissions` / `justification` at all. Returning
+     *  undefined here disabled that escalation entry for EVERY session,
+     *  including purely local ones, so the local backend's mode is the honest
+     *  answer. Remote worlds are not confined by the local sandbox, so a wider
+     *  per-call policy is meaningless for them and is dropped at the call site
+     *  instead of being silently swallowed by a 4-parameter remote backend. */
     get sandboxMode(): SandboxMode | undefined;
     /** Encode a raw key into the world's namespace. */
     private encode;
     /** Decode a namespaced key back to (rawKey, world). Supports both the
      *  current `wfs://<id>/…` form and the legacy `ssh:<recordId>:…` form. */
     private decode;
+    /**
+     * Refuse a protected client directory before any backend sees it.
+     *
+     * Only a LOCAL world is checked: for a remote world the path is a path on the
+     * SERVER, which may legitimately look like a client path (both can be
+     * `/home/me/.dsh/…`).
+     *
+     * @param path - the path (or canonical target key) about to be dispatched.
+     * @param namespace - the resolved world's namespace ('' = local).
+     */
+    private assertNotDenied;
+    /**
+     * The world owning one call: an explicit anchor path (this workspace's or a
+     * SIBLING's) wins over the session cwd, because anchors are physically under
+     * the local-infrastructure root and would otherwise be carved out as local.
+     * Falls back to the session cwd's world, then to the caller's default.
+     */
+    private worldForPath;
     resolve(path: string, opts?: {
         cwd?: string;
         signal?: AbortSignal;