dsh-over-ssh 0.2.2 → 0.2.4

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

@@ -128,6 +128,17 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
+        /**
+         * Split one connection into traffic lanes (`interactive` / `bulk` / `compute`).
+         *
+         * On by default: transfers then open their own transport instead of competing with an interactive
+         * `remote_exec` for the connection's in-flight window. A lane that fails to connect falls back to the
+         * interactive transport, and turning this off restores exactly the pre-lane behaviour (one transport
+         * per connection). `stateful` carries long-lived job/LSP/watch state (watch uses a dedicated per-session key when an ambient session id is available).
+         */
+        transportLanes: z<boolean, boolean, "defined">;
+        /** Upper bound on concurrent stateful lane transports per connection, separately for job/LSP sessions and watch (default 8 each). */
+        statefulLanes: z<number, number, "defined">;
         /** How many finished transfers the progress table retains (FR-2.6.4). */
         transferHistoryEntries: z<number, number, "defined">;
         binDir: z<string, string, "defined">;
@@ -214,6 +225,17 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
+        /**
+         * Split one connection into traffic lanes (`interactive` / `bulk` / `compute`).
+         *
+         * On by default: transfers then open their own transport instead of competing with an interactive
+         * `remote_exec` for the connection's in-flight window. A lane that fails to connect falls back to the
+         * interactive transport, and turning this off restores exactly the pre-lane behaviour (one transport
+         * per connection). `stateful` carries long-lived job/LSP/watch state (watch uses a dedicated per-session key when an ambient session id is available).
+         */
+        transportLanes: z<boolean, boolean, "defined">;
+        /** Upper bound on concurrent stateful lane transports per connection, separately for job/LSP sessions and watch (default 8 each). */
+        statefulLanes: z<number, number, "defined">;
         /** How many finished transfers the progress table retains (FR-2.6.4). */
         transferHistoryEntries: z<number, number, "defined">;
         binDir: z<string, string, "defined">;
@@ -346,6 +368,17 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
+        /**
+         * Split one connection into traffic lanes (`interactive` / `bulk` / `compute`).
+         *
+         * On by default: transfers then open their own transport instead of competing with an interactive
+         * `remote_exec` for the connection's in-flight window. A lane that fails to connect falls back to the
+         * interactive transport, and turning this off restores exactly the pre-lane behaviour (one transport
+         * per connection). `stateful` carries long-lived job/LSP/watch state (watch uses a dedicated per-session key when an ambient session id is available).
+         */
+        transportLanes: z<boolean, boolean, "defined">;
+        /** Upper bound on concurrent stateful lane transports per connection, separately for job/LSP sessions and watch (default 8 each). */
+        statefulLanes: z<number, number, "defined">;
         /** How many finished transfers the progress table retains (FR-2.6.4). */
         transferHistoryEntries: z<number, number, "defined">;
         binDir: z<string, string, "defined">;
@@ -432,6 +465,17 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         transferChunkBytes: z<number, number, "defined">;
         /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
         transferConcurrency: z<number, number, "defined">;
+        /**
+         * Split one connection into traffic lanes (`interactive` / `bulk` / `compute`).
+         *
+         * On by default: transfers then open their own transport instead of competing with an interactive
+         * `remote_exec` for the connection's in-flight window. A lane that fails to connect falls back to the
+         * interactive transport, and turning this off restores exactly the pre-lane behaviour (one transport
+         * per connection). `stateful` carries long-lived job/LSP/watch state (watch uses a dedicated per-session key when an ambient session id is available).
+         */
+        transportLanes: z<boolean, boolean, "defined">;
+        /** Upper bound on concurrent stateful lane transports per connection, separately for job/LSP sessions and watch (default 8 each). */
+        statefulLanes: z<number, number, "defined">;
         /** How many finished transfers the progress table retains (FR-2.6.4). */
         transferHistoryEntries: z<number, number, "defined">;
         binDir: z<string, string, "defined">;

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

@@ -60,6 +60,10 @@ export interface BackendText {
     readonly size: number;
     readonly truncated: boolean;
     readonly version: string;
+    /** The bytes are not valid UTF-8; `text` is only a readable replacement. */
+    readonly binary?: boolean;
+    /** Exact bytes (base64), present only when {@link binary} is true. */
+    readonly dataBase64?: string;
 }
 /** Outcome of a write. */
 export interface BackendWrite {
@@ -129,6 +133,33 @@ export interface Backend {
      *   ignore it. Structural on purpose — the app layer must not import platform types.
      */
     writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal, policy?: BackendWritePolicy): Promise<BackendWrite>;
+    /** One-round-trip project overview; absent when the backend has no `repo.summary`. */
+    repoSummary?(root: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /** Multi-file edit in one round trip; absent when the backend has no `fs.patchMany`. */
+    patchMany?(edits: readonly {
+        readonly path: string;
+        readonly expectedVersion?: string;
+        readonly find?: string;
+        readonly replace?: string;
+        readonly all?: boolean;
+        readonly create?: boolean;
+        readonly patch?: string;
+    }[], atomic: boolean, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Read several paths in **one** round trip (the backend's own batch sweep).
+     *
+     * Optional: backends without a batch primitive leave it absent and the caller falls back to parallel
+     * single reads. `chunks` keeps one slot per requested path (undefined where it could not be read), so
+     * "missing" and "truncated" never collapse into a shorter array.
+     */
+    readMany?(absolutePaths: readonly string[], options: {
+        readonly maxBytesEach: number;
+        readonly totalBytesCap?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly chunks: readonly (BackendText | undefined)[];
+        readonly missing: readonly string[];
+    }>;
     /**
      * Apply a unified diff to one file, atomically.
      *

package/lib/types/src/host/app/routed-fs.d.ts

@@ -0,0 +1,238 @@
+/**
+ * The routed file system: one workspace, many roots, local and remote side by side.
+ *
+ * Responsibilities, in order:
+ *
+ *  1. **Resolve** a model-facing path to exactly one root plus a backend-absolute path
+ *     (all rules live in `domain/route-table.ts`; this module only applies the result).
+ *     One addition lives here rather than in the table: the **implicit session root**, so the session's own
+ *     working directory is always usable even when no registered root covers it (see {@link
+ *     RoutedFileSystem.tryResolve}).
+ *  2. **Namespace** target keys as `{backendId}\0{absolute path}` — the same file spelled locally
+ *     and remotely must never collide, because core components key their state by target key.
+ *  3. **Fence writes**: resolution already rejects paths outside every root, so `workspace-write`
+ *     means "inside the roots"; `read-only` denies every write; `danger-full-access` allows.
+ *     This is the plugin's own multi-root confinement (the core's single-root fence cannot express
+ *     several roots, see `doc/02-platform/fs-seam.md` §4).
+ *  4. Keep the operations the model's tools need: stat / list / read / write / edit.
+ *
+ * @module dsh-over-ssh/app/routed-fs
+ */
+import type { Backend, BackendEntry, BackendRead, BackendSandboxMode, BackendStat, BackendText } from './backend.ts';
+import { SshDevError } from '../domain/errors.ts';
+import { type RootRef } from '../domain/roots/root.ts';
+import { type RouteOptions } from '../domain/roots/route-table.ts';
+/** A resolved path: one root, one backend, one backend-absolute location. */
+export interface RoutedTarget {
+    readonly root: RootRef;
+    readonly backend: Backend;
+    /** Key of the root, also the router's backend key. */
+    readonly backendKey: string;
+    /** Absolute path in the backend's own spelling. */
+    readonly absolute: string;
+    /** Namespaced identity: `{backendId}\0{absolute}`. */
+    readonly targetKey: string;
+    readonly relativePath: string;
+    /** Model-facing spelling (`ssh://…` for remote roots). */
+    readonly displayPath: string;
+}
+/** Resolution outcome with a resolved target, or the reason it failed. */
+export type RoutedResolution = {
+    readonly ok: true;
+    readonly target: RoutedTarget;
+} | {
+    readonly ok: false;
+    readonly error: SshDevError;
+};
+/** A directory entry with its resolved identity. */
+export interface RoutedEntry extends BackendEntry {
+    readonly targetKey: string;
+    readonly displayPath: string;
+}
+/** Options for {@link RoutedFileSystem}. */
+export interface RoutedFileSystemOptions {
+    readonly roots: readonly RootRef[];
+    /** Backends keyed by `rootKey(root)`. */
+    readonly backends: ReadonlyMap<string, Backend>;
+    readonly caseInsensitive?: boolean;
+    /** Cap for a single read; defaults to 8 MiB. */
+    readonly maxReadBytes?: number;
+    /**
+     * Builds the backend for the **implicit session root** — the session's own cwd (see {@link
+     * RoutedFileSystem.tryResolve}).
+     *
+     * Injected rather than imported because building a local backend needs `node:fs`, and this layer must not
+     * reach a concrete adapter (架构测试: `app` only depends on `infra` port modules). Omitting it **disables**
+     * the implicit root, which is the honest default: a router that was given no way to serve host paths keeps
+     * reporting `ROOT_OUTSIDE` for them.
+     */
+    readonly createLocalBackend?: (root: RootRef) => Backend;
+}
+/** Write options. */
+export interface RoutedWriteOptions {
+    readonly cwd?: string;
+    /** Version token that must match before the write proceeds. */
+    readonly expectedVersion?: string;
+    /** Policy the caller is operating under. */
+    readonly sandbox?: BackendSandboxMode;
+    readonly signal?: AbortSignal;
+}
+/** Literal edit request, mirroring the core's `editText` semantics. */
+export interface RoutedEdit {
+    readonly find: string;
+    readonly replace: string;
+    /** Replace every occurrence instead of requiring a unique one. */
+    readonly all?: boolean;
+}
+/** Multi-root file system over a set of backends. */
+export declare class RoutedFileSystem {
+    #private;
+    constructor(options: RoutedFileSystemOptions);
+    /** Registered roots, in registration order. */
+    get roots(): readonly RootRef[];
+    /** Confinement the router enforces itself. */
+    get sandboxMode(): BackendSandboxMode;
+    /** Register a root together with the backend that serves it. */
+    addRoot(root: RootRef, backend: Backend): void;
+    /** Remove a root and its backend binding. */
+    removeRoot(key: string): boolean;
+    /** Replace every root and backend binding at once. */
+    setRoots(entries: readonly {
+        readonly root: RootRef;
+        readonly backend: Backend;
+    }[]): void;
+    /**
+     * Resolve a path.
+     *
+     * @param input - model-facing path (host path, `ssh://…`, or relative to `cwd`).
+     * @param options - session cwd and case folding.
+     * @returns the resolved target.
+     * @throws SshDevError `ROOT_OUTSIDE` / `ROOT_AMBIGUOUS` / `ROOT_INVALID`.
+     */
+    resolve(input: string, options?: RouteOptions): RoutedTarget;
+    /**
+     * Non-throwing resolution for UI code.
+     *
+     * A registered root is always asked first, so it wins over the implicit session root — the implicit root only
+     * answers paths the table refused.
+     */
+    tryResolve(input: string, options?: RouteOptions): RoutedResolution;
+    /** Metadata for a path. */
+    stat(input: string, options?: RouteOptions & {
+        readonly signal?: AbortSignal;
+    }): Promise<BackendStat & {
+        readonly target: RoutedTarget;
+    }>;
+    /** Direct children of a directory, with resolved identities. */
+    list(input: string, options?: RouteOptions & {
+        readonly signal?: AbortSignal;
+    }): Promise<readonly RoutedEntry[]>;
+    /**
+     * List an already-resolved directory.
+     *
+     * Takes the target so callers that hold one (the core `FsTarget` contract hands one to every
+     * operation) do not pay for a second resolution.
+     *
+     * @param target - resolved directory.
+     * @param signal - cancellation.
+     * @returns direct children with resolved identities.
+     */
+    listTarget(target: RoutedTarget, signal?: AbortSignal): Promise<readonly RoutedEntry[]>;
+    /**
+     * Stat an already-resolved target.
+     *
+     * @param target - resolved target.
+     * @param options - when `followSymlink` is false and the backend supports it, the link itself is
+     *   inspected instead of its target.
+     * @returns metadata (never content).
+     */
+    statTarget(target: RoutedTarget, options?: {
+        readonly followSymlink?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<BackendStat>;
+    /**
+     * Resolve an opaque target key back to the root, backend and backend-absolute path that own it.
+     *
+     * Every operation after {@link resolve} arrives this way (the core hands back only the target key), so an
+     * implicit session root must be found here too: it is not in the table, but its backend id is what its target
+     * keys carry.
+     */
+    targetFromKey(targetKey: string): RoutedTarget;
+    /** Whether a path exists. */
+    exists(input: string, options?: RouteOptions & {
+        readonly signal?: AbortSignal;
+    }): Promise<boolean>;
+    /** Read bytes, capped by the router's limit. */
+    readBytes(input: string, options?: RouteOptions & {
+        readonly maxBytes?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<BackendRead & {
+        readonly target: RoutedTarget;
+    }>;
+    /** Read text. */
+    readText(input: string, options?: RouteOptions & {
+        readonly maxBytes?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<BackendText & {
+        readonly target: RoutedTarget;
+    }>;
+    /**
+     * Write text after enforcing the router's own confinement.
+     *
+     * @param input - destination path.
+     * @param text - content to write.
+     * @param options - policy, version guard and cancellation.
+     * @returns the write outcome plus the resolved target.
+     */
+    writeText(input: string, text: string, options?: RoutedWriteOptions): Promise<{
+        readonly bytes: number;
+        readonly version: string;
+        readonly target: RoutedTarget;
+    }>;
+    /**
+     * Apply a unified diff to one file, atomically.
+     *
+     * Forwarded rather than reimplemented: the backend owns the hunk matching, and a second implementation
+     * here would be a second set of edge cases to keep in sync.
+     */
+    patchText(input: string, diff: string, options?: RoutedWriteOptions): Promise<{
+        readonly bytes: number;
+        readonly version: string;
+        readonly hunks: number;
+        readonly target: RoutedTarget;
+    }>;
+    /**
+     * Replace a literal string inside a file.
+     *
+     * Mirrors the core's semantics: an absent pattern and an ambiguous match without `all` are both
+     * errors, and a version guard can refuse the whole edit.
+     *
+     * @param input - file to edit.
+     * @param edit - find/replace plus the `all` flag.
+     * @param options - policy, version guard, cwd and cancellation.
+     * @returns the new version and the number of replacements.
+     */
+    editText(input: string, edit: RoutedEdit, options?: RoutedWriteOptions): Promise<{
+        readonly replacements: number;
+        readonly version: string;
+        readonly target: RoutedTarget;
+    }>;
+    /**
+     * Whether one target is inside another.
+     *
+     * Both targets must belong to the same backend; across backends the answer is always `false`
+     * (a local path can never contain a remote path).
+     */
+    contains(parent: RoutedTarget, child: RoutedTarget): boolean;
+    /** Host path for a child process in the target's world, when that world has one. */
+    processPath(target: RoutedTarget): string | undefined;
+    /** `file:` URL in the target's world. */
+    fileUrl(target: RoutedTarget): string | undefined;
+}
+/** Namespaced identity of one file; the backend id prevents local/remote collisions. */
+export declare function makeTargetKey(backend: Backend, absolute: string): string;
+/** Split a target key back into its parts (diagnostics and tests only). */
+export declare function splitTargetKey(targetKey: string): {
+    readonly backendId: string;
+    readonly absolute: string;
+} | undefined;

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

@@ -163,6 +163,23 @@ export interface RestoreSessionResult {
     /** Absolute path the session directory was moved back to. */
     readonly restoredPath: string;
     readonly movedBy: 'rename' | 'copy';
+    /**
+     * Sub-sessions restored **together with** the requested entry.
+     *
+     * Restoring a parent used to leave its deleted children in the bin with no discoverable link back to the
+     * parent, so the user could never learn they were still there. They are now restored in the same call.
+     */
+    readonly restoredSubsessions: readonly {
+        readonly sessionId: string;
+        readonly restoredPath: string;
+    }[];
+    /** Sub-sessions that could not be restored (path occupied, move failed); they stay in the bin. */
+    readonly failedSubsessions: readonly {
+        readonly sessionId: string;
+        readonly reason: string;
+    }[];
+    /** True when the restored entry is a sub-session whose parent is still in the bin. */
+    readonly parentStillBinned: boolean;
 }
 /** One purge outcome. */
 export interface PurgeSessionResult {

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

@@ -1,14 +1,16 @@
 /**
- * Transport lifecycle: acquire, reuse, replace and release one transport per connection.
+ * Transport lifecycle: acquire, reuse, replace and release transports per connection and lane.
  *
  * The service owns three behaviours the rest of the plugin relies on:
  *
- *  1. **One transport per connection**, created lazily and shared by every caller (single flight).
+ *  1. **One transport per connection and lane**, created lazily and shared by every caller on that
+ *     lane (single flight). A call without a lane keeps the historical one-transport-per-connection
+ *     behaviour and shares that slot with the `interactive` lane.
  *  2. **Replacement on a changed decision**: when the selector's answer changes (for example after
- *     a mux failure is recorded), the old transport is disposed and a new one built, so a stale
+ *     a mux failure is recorded), the old transports are disposed and new ones built, so a stale
  *     decision can never keep serving traffic.
  *  3. **Explicit release**, so shutting a connection down closes its process/connection rather
- *     than leaving it to the garbage collector.
+ *     than leaving it to the garbage collector. Release/dispose cover **every lane** of a profile.
  *
  * The transport contract lives in `infra/transport/transport.ts` and is imported as a type only,
  * which keeps this module free of implementation and of the core packages.
@@ -27,7 +29,7 @@ export interface TransportFactories {
      * Creates the Tier 2 agent transport. Optional: a build without the agent (or without a shipped binary)
      * simply omits it, and the selector never chooses `agent` in that case.
      */
-    readonly createAgent?: (profile: ConnectionProfile, decision: TransportDecision) => Transport;
+    readonly createAgent?: (profile: ConnectionProfile, decision: TransportDecision, lane?: TransportLane, sessionKey?: string) => Transport;
 }
 /**
  * Optional asynchronous step between deciding and connecting.
@@ -45,10 +47,34 @@ export interface TransportFactories {
  * keep uploading anyway because only `transport.connect()` saw the signal.
  */
 export type TransportPreflight = (profile: ConnectionProfile, decision: TransportDecision, signal?: AbortSignal) => Promise<TransportDecision>;
+/**
+ * Traffic class of a transport.
+ *
+ * `interactive` carries fs/exec calls a user is waiting on; `bulk` carries transfer reads; `compute`
+ * carries search/index/git/repo-summary work; `stateful` carries long-lived job/LSP/watch sessions.
+ * The wiring uses a DSH session id for job/LSP and a `watch:<session>` (or shared `watch`) key for watch. Splitting them keeps a
+ * large transfer or an index scan from consuming the slots of an interactive command.
+ */
+export type TransportLane = 'interactive' | 'bulk' | 'compute' | 'stateful';
+/** Lane selection for {@link TransportService.acquire}. */
+export interface TransportAcquireOptions {
+    /** Traffic class; defaults to `interactive`. */
+    readonly lane?: TransportLane;
+    /**
+     * Extra cache dimension for stateful clients (one agent session per id).
+     *
+     * Ignored unless a lane is given: a call without options must keep the old key.
+     */
+    readonly sessionKey?: string;
+}
 /** One acquired transport plus the decision that produced it. */
 export interface AcquiredTransport {
     readonly transport: Transport;
     readonly decision: TransportDecision;
+    /** Which lane this transport serves. */
+    readonly lane: TransportLane;
+    /** Connection this transport belongs to; set by the service's own cache. */
+    readonly connectionId?: string;
 }
 /** Facts injected for testability. */
 export interface TransportServiceOptions {
@@ -56,8 +82,17 @@ export interface TransportServiceOptions {
     readonly factories: TransportFactories;
     /** See {@link TransportPreflight}. Omitted means "no revision". */
     readonly preflight?: TransportPreflight;
+    /**
+     * Upper bound on concurrent `stateful` lane transports per connection.
+     *
+     * Each stateful lane carries an AgentTransport with its own in-flight window; without a cap, one DSH
+     * session per connection would multiply the bounded window by the number of live sessions. Job/LSP and
+     * watch lanes are counted separately; hitting the cap makes {@link acquire} fail and lets
+     * `TransportLaneRouter` fall back to interactive.
+     */
+    readonly statefulLaneLimit?: number;
 }
-/** Owns one transport instance per connection. */
+/** Owns transport instances per connection and lane. */
 export declare class TransportService {
     #private;
     constructor(options: TransportServiceOptions);
@@ -65,17 +100,37 @@ export declare class TransportService {
      * Get a connected transport for a profile, creating it if needed.
      *
      * @param profile - the connection to serve.
-     * @param signal - cancellation for the connect attempt.
+     * @param signalOrOptions - cancellation for the connect attempt (legacy form) or lane selection.
+     * @param signal - cancellation when the second argument carries lane options.
      * @returns the transport and the decision behind it (after any preflight revision).
      * @throws SshDevError from the selector or from the transport's own connect.
      */
     acquire(profile: ConnectionProfile, signal?: AbortSignal): Promise<AcquiredTransport>;
-    /** The cached transport for a connection, if any. */
-    current(connectionId: string): AcquiredTransport | undefined;
+    acquire(profile: ConnectionProfile, options?: TransportAcquireOptions, signal?: AbortSignal): Promise<AcquiredTransport>;
+    /**
+     * The cached transport for a connection.
+     *
+     * Without options this is the legacy interactive slot, so existing callers keep their old meaning.
+     */
+    current(connectionId: string, options?: TransportAcquireOptions): AcquiredTransport | undefined;
     /** Decisions currently in force, for the connection status UI. */
     decisions(): readonly TransportDecision[];
-    /** Dispose and forget one connection. */
+    /** Dispose and forget **every lane** of one connection. */
     release(connectionId: string): Promise<void>;
-    /** Dispose every connection (plugin unload, connection-service shutdown). */
+    /** Unique DSH session keys currently owning a stateful lane (used by the idle janitor). */
+    statefulSessions(): readonly string[];
+    /** Release stateful lanes whose DSH session is no longer live. */
+    pruneStatefulSessions(isLive: (sessionKey: string) => boolean): Promise<void>;
+    /**
+     * Dispose the `stateful` lane of one DSH session on every connection.
+     *
+     * Stateful lanes are keyed by session, so deleting a DSH session would otherwise leave one agent
+     * transport per connection alive for the life of the host process (and with it the daemon-side jobs/LSP
+     * ownership records that transport created). Other lanes are untouched.
+     *
+     * @param sessionKey - the DSH session id used when the stateful lane was acquired.
+     */
+    releaseSession(sessionKey: string): Promise<void>;
+    /** Dispose every connection and lane (plugin unload, connection-service shutdown). */
     disposeAll(): Promise<void>;
 }

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

@@ -28,6 +28,12 @@ export interface RemoteCapabilities {
      * reported to a caller as "not installed", because we have no evidence either way.
      */
     readonly lspServers?: readonly LspServerInfo[];
+    /**
+     * `search.grep` offset/limit paging support (agent capability `grepPaging`).
+     *
+     * Optional: `undefined` means "this transport cannot page" — same as false for callers.
+     */
+    readonly grepPaging?: boolean;
 }
 /** One language server found on the remote `PATH`. */
 export interface LspServerInfo {

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

@@ -0,0 +1,101 @@
+/**
+ * The route table: turns a model-facing path into one backend plus a root-relative path.
+ *
+ * This is the heart of "one workspace, several roots". Resolution order is deliberate, and
+ * every branch is a documented rule rather than a heuristic:
+ *
+ *  1. `ssh://<connection>/abs` — the explicit remote grammar always wins.
+ *  2. Anchor match — a path (or the session cwd) under a remote root's local anchor resolves
+ *     to that remote root. The anchor is what makes a remote root a legal DSH workspace.
+ *  3. Local root containment — absolute host paths, and `cwd`-relative spellings.
+ *  4. Bare POSIX absolute path matching remote roots — needed because a prompt lists remote
+ *     roots in POSIX spelling; two equally specific remote roots on different connections
+ *     are reported as ambiguous instead of being guessed.
+ *
+ * @module dsh-over-ssh/domain/route-table
+ */
+import { SshDevError } from '../errors.ts';
+import { type RootRef } from './root.ts';
+import { type SessionIdentity } from './session-roots.ts';
+/** One resolved route. */
+export interface RouteTarget {
+    /** The root the path belongs to. */
+    readonly root: RootRef;
+    /** Root-relative spelling with `/` separators; an empty string means the root itself. */
+    readonly relativePath: string;
+    /** Stable backend key; one backend serves all paths of one root. */
+    readonly backendKey: string;
+}
+/** Per-call resolution options. */
+export interface RouteOptions {
+    /** Session working directory used for relative spellings. */
+    readonly cwd?: string;
+    /**
+     * Who is asking, when the caller knows more than its cwd (ADR-0013).
+     *
+     * The route table never invents this: the fs provider reads it from the session scope the tool dispatcher
+     * carries down (`integration/session-scope.ts`) and hands it over. `undefined` means "no session identity" —
+     * the workspace-level rule then stands, which is exactly the behaviour before ADR-0013.
+     */
+    readonly session?: SessionIdentity;
+    /**
+     * The asking session's own working directory, when the caller did not supply a `cwd`.
+     *
+     * Used **only** by the implicit session root (a session's own directory is always readable to it) — never by
+     * the gate below, which must keep seeing exactly what the platform passed. Synthesising a `cwd` for the gate
+     * would apply the workspace rule to calls that legitimately carry none, which is the failure ADR-0012 §4
+     * boundary 2 records (a whole turn lost before the model was called).
+     */
+    readonly sessionCwd?: string;
+    /** Override host-path case folding (defaults to the platform). */
+    readonly caseInsensitive?: boolean;
+}
+/** A path resolved to a root, or a diagnostic reason why it could not be. */
+export type RouteOutcome = {
+    readonly ok: true;
+    readonly target: RouteTarget;
+} | {
+    readonly ok: false;
+    readonly error: SshDevError;
+};
+/** Resolution table over an ordered set of roots. */
+export declare class RouteTable {
+    #private;
+    constructor(roots?: readonly RootRef[], options?: {
+        readonly caseInsensitive?: boolean;
+    });
+    /** Roots in registration order. */
+    get roots(): readonly RootRef[];
+    /**
+     * Register a root.
+     *
+     * @param root - root to add.
+     * @throws SshDevError `ROOT_INVALID` when the root is malformed or already registered.
+     */
+    add(root: RootRef): void;
+    /** Remove a root by its key; returns whether it was present. */
+    remove(key: string): boolean;
+    /** Replace every root; throws like {@link add} when any root is invalid. */
+    reset(roots: readonly RootRef[]): void;
+    /**
+     * Resolve a path, then apply the **session gate**.
+     *
+     * Two failures wear the same code on purpose: "no root covers this path" and "the root that covers it belongs
+     * to another session" are both `ROOT_OUTSIDE`, because from the caller's side they are the same fact — this
+     * session cannot use that path. The message and the `root` detail say which one it was.
+     *
+     * @param input - model-facing, host or remote spelling.
+     * @param options - session cwd (also the session identity, see {@link rootVisibleToSession}) and case folding.
+     * @returns the resolved route, or a failure carrying `ROOT_OUTSIDE` / `ROOT_AMBIGUOUS`.
+     */
+    tryResolve(input: string, options?: RouteOptions): RouteOutcome;
+    /**
+     * Resolve a path or throw.
+     *
+     * @param input - path to resolve.
+     * @param options - session cwd and case-folding override.
+     * @returns the resolved route.
+     * @throws SshDevError `ROOT_OUTSIDE` or `ROOT_AMBIGUOUS`.
+     */
+    resolve(input: string, options?: RouteOptions): RouteTarget;
+}

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

@@ -227,6 +227,13 @@ export interface SessionTrashEntry {
      */
     readonly originalSegment: string;
     readonly title: string | undefined;
+    /**
+     * Parent session id from the header, when this deleted session was a sub-session.
+     *
+     * Optional so an index written by 0.2.2 (which did not record it) still parses; restoring a parent then
+     * cannot find children recorded before the field existed, which is exactly the old behaviour.
+     */
+    readonly parentSessionId?: string | undefined;
     /** Total bytes of the moved log files, for the retention policy. */
     readonly bytes: number;
     readonly deletedAtMs: number;
@@ -342,6 +349,7 @@ export declare function makeSessionTrashEntry(input: {
     readonly segment: string;
     readonly originalSegment: string;
     readonly title: string | undefined;
+    readonly parentSessionId?: string | undefined;
     readonly bytes: number;
     readonly deletedAtMs: number;
     readonly movedBy: 'rename' | 'copy';