dsh-over-ssh 0.2.3 → 0.2.4

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

@@ -0,0 +1,132 @@
+/**
+ * Non-interactive **password** authentication for the system `ssh` client, via `SSH_ASKPASS`.
+ *
+ * Why this module exists: the Tier 2 agent is launched by spawning `ssh` (`ssh <alias> <agent> --stdio`),
+ * and the alias transport runs every command the same way. System `ssh` cannot read a password from a pipe,
+ * so a password-only connection used to be impossible on any transport that goes through `ssh` — which made
+ * "default to Tier 2" silently false for password connections (they were downgraded to `ssh2`). That was
+ * never a property of SSH: OpenSSH ≥ 8.4 supports `SSH_ASKPASS_REQUIRE=force`, which runs a helper program
+ * to obtain the secret **even with no tty**, exactly the situation a background plugin is in.
+ *
+ * Two rules make this safe:
+ *
+ *  1. **The secret never touches the disk.** The helper program carries no secret; it forwards the value of
+ *     an environment variable (`DSH_OVER_SSH_ASKPASS_SECRET`) that the ssh child process inherits. A leftover
+ *     helper file therefore leaks nothing: with the variable absent it prints an empty line and ssh fails
+ *     the authentication instead of succeeding with a stale credential.
+ *  2. **The secret is never interpolated into a shell or command line.** It travels only as an environment
+ *     value, so characters like `&`, `|`, `%`, `^` and quotes need no escaping (a `cmd`-based helper that
+ *     echoed the secret would break on those, and its argv would be visible in the process list).
+ *
+ * Verified on the real host (Windows, OpenSSH_for_Windows_9.5p1): password auth succeeds through a spawned
+ * `ssh` whose stdio are pipes, and a **wrong** secret fails — so the helper is genuinely what authenticates.
+ *
+ * @module dsh-over-ssh/infra/transport/askpass
+ */
+/** The interpreter that runs the helper script. */
+export interface AskpassInterpreter {
+    /** Absolute path of the executable (`node`/Electron). */
+    readonly execPath: string;
+    /** `'win32'` or a POSIX platform id; decides which shim shape is written. */
+    readonly platform: string;
+}
+/** The two files a helper is made of, and the exact text written to each. */
+export interface AskpassFiles {
+    /** The program `SSH_ASKPASS` points at. */
+    readonly helperPath: string;
+    /** The script the helper delegates to. */
+    readonly scriptPath: string;
+    /** Contents of {@link scriptPath}; carries no secret. */
+    readonly script: string;
+    /** Contents of {@link helperPath}; carries no secret. */
+    readonly helper: string;
+    /** Mode to create the files with (POSIX needs the helper executable). */
+    readonly mode: number;
+}
+/**
+ * The helper script: print the secret from the environment, then a newline.
+ *
+ * A trailing newline is required — an ssh askpass program whose output lacks one is rejected
+ * (measured: `<nul set /p =` without a newline failed while `echo` succeeded).
+ */
+export declare function askpassScript(): string;
+/**
+ * The program `SSH_ASKPASS` names.
+ *
+ * Windows: a `cmd` shim, because ssh executes the path directly and a `.mjs` is not executable there.
+ * POSIX: a `sh` script. Both only *launch* the interpreter with the script path, so the secret is never
+ * quoted into a command line.
+ *
+ * @param interpreter - interpreter and platform.
+ * @param scriptPath - absolute path of {@link askpassScript}'s file.
+ * @returns the shim text.
+ */
+export declare function askpassHelper(interpreter: AskpassInterpreter, scriptPath: string): string;
+/**
+ * Build the files for one helper directory.
+ *
+ * @param dir - directory to place the helper in.
+ * @param interpreter - interpreter and platform.
+ * @returns the file plan (paths plus contents).
+ */
+export declare function planAskpassFiles(dir: string, interpreter: AskpassInterpreter): AskpassFiles;
+/**
+ * The environment that makes the system `ssh` ask {@link AskpassFiles.helperPath} for the password.
+ *
+ * `ELECTRON_RUN_AS_NODE=1` is set unconditionally: this plugin normally runs inside the Electron desktop
+ * app, where `process.execPath` is the Electron binary and would otherwise open a GUI instead of running
+ * the script. Real `node` ignores the variable, so one code path covers both hosts.
+ *
+ * `DISPLAY` is set because pre-8.4 OpenSSH only consults `SSH_ASKPASS` when it is non-empty, and
+ * `SSH_ASKPASS_REQUIRE=force` because ≥ 8.4 additionally requires it when a tty might exist. Setting both
+ * makes the helper work on either generation.
+ *
+ * @param files - the helper plan.
+ * @param secret - the password; only ever passed here, never written to a file.
+ * @returns environment entries to merge into the `ssh` child's environment.
+ */
+export declare function askpassEnvironment(files: AskpassFiles, secret: string): Record<string, string>;
+/** Filesystem surface this module needs; injected so tests never touch a real disk. */
+export interface AskpassIo {
+    /** Create `dir` (and parents). */
+    mkdir(dir: string): Promise<void>;
+    /** Write `content` to `path`, optionally with a POSIX mode. */
+    writeFile(path: string, content: string, mode: number): Promise<void>;
+    /** Remove `dir` recursively; never throws when it is already gone. */
+    remove(dir: string): Promise<void>;
+    /** Create a private directory to hold one helper. */
+    makeTempDir(): Promise<string>;
+}
+/** A live helper: the environment to hand `ssh`, plus a way to take it away again. */
+export interface AskpassHandle {
+    /** Environment entries for the `ssh` child process. */
+    readonly env: Record<string, string>;
+    /** Delete the helper directory. Safe to call more than once. */
+    dispose(): Promise<void>;
+}
+/** Options for {@link createAskpass}. */
+export interface AskpassOptions {
+    /** The password. Held in memory only. */
+    readonly secret: string;
+    /** Interpreter facts; defaults to this process. */
+    readonly interpreter?: AskpassInterpreter;
+    /** Injected filesystem. */
+    readonly io: AskpassIo;
+}
+/**
+ * Create a password helper and the environment that uses it.
+ *
+ * @param options - secret, interpreter and injected filesystem.
+ * @returns the handle; call {@link AskpassHandle.dispose} when the connection goes away.
+ */
+export declare function createAskpass(options: AskpassOptions): Promise<AskpassHandle>;
+/**
+ * Whether a connection's password can be handed to the system `ssh` at all.
+ *
+ * Only `authKind: 'password'` needs the helper: key and agent connections never prompt, and forcing
+ * `BatchMode=no` for them would let a misconfigured host block on an interactive prompt forever.
+ *
+ * @param authKind - the connection's authentication mode.
+ * @returns true when the askpass helper must be wired in.
+ */
+export declare function needsAskpass(authKind: 'agent' | 'key' | 'password'): boolean;

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

@@ -67,6 +67,10 @@ export interface ExecResult {
     readonly timedOut: boolean;
     readonly stdout: string;
     readonly stderr: string;
+    /** Exact bytes of stdout when it was **not truncated** and is not valid UTF-8; `stdout` is then lossy. */
+    readonly stdoutBase64?: string | undefined;
+    /** Exact bytes of stderr when it was **not truncated** and is not valid UTF-8; `stderr` is then lossy. */
+    readonly stderrBase64?: string | undefined;
     readonly durationMs: number;
     /**
      * Whether **stdout** was cut at `maxBytes`.
@@ -452,6 +456,39 @@ export interface Transport {
      * `readFile`; a test pins that identity because it is the contract's entire purpose.
      */
     statPath?(path: string, signal?: AbortSignal): Promise<RemoteStatResult>;
+    /**
+     * Read several file ranges in **one** round trip (agent `fs.readMany`).
+     *
+     * Optional and its absence is meaningful: Tier 1 shell transports have no batch primitive, so the caller
+     * falls back to parallel single reads. Present, a model asking for five files pays one RTT instead of five.
+     */
+    batchRead?(requests: readonly {
+        readonly path: string;
+        readonly offset?: number;
+        readonly maxBytes?: number;
+    }[], signal?: AbortSignal): Promise<readonly BatchReadChunk[]>;
+    /**
+     * Probe one TCP endpoint **from the remote host** (agent `net.probe`).
+     *
+     * Optional: absent when the agent predates the method. The forward tool uses it to fail a dead port at
+     * `start` time instead of relying on the `ssh -W` child's 150 ms probe window.
+     */
+    netProbe?(host: string, port: number, signal?: AbortSignal): Promise<{
+        readonly reachable: boolean;
+        readonly error?: string;
+    }>;
+    /** One-round-trip project overview (agent `repo.summary`). Optional; absent means the agent predates it. */
+    repoSummary?(root: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /** Multi-file edit in one round trip (agent `fs.patchMany`). Optional, same rule. */
+    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>>;
     /**
      * Atomic in-place edit performed by the agent itself (`fs.edit`).
      *
@@ -565,3 +602,14 @@ export declare function encodeBase64(bytes: Uint8Array): string;
  * 那次拷贝是几十字节，与热路径无关。
  */
 export declare function decodeBase64(text: string): Uint8Array;
+/** One chunk returned by {@link Transport.batchRead}. */
+export interface BatchReadChunk {
+    readonly path: string;
+    readonly exists: boolean;
+    readonly size: number;
+    readonly version: string;
+    readonly truncated: boolean;
+    readonly bytes: Uint8Array;
+    /** Per-item failure (e.g. permission); the batch itself still succeeded. */
+    readonly error?: string;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Per-connection store of `SSH_ASKPASS` helpers.
+ *
+ * Why this exists as a module: preparing a helper is **async** (it reads the secret from the credential
+ * service and writes two files), but transport factories are **synchronous** and are also reached from
+ * `createAlias` during the install ladder. The two are joined here: something async calls
+ * {@link AskpassRegistry.prepare} first, and the factory then reads {@link AskpassRegistry.envFor}
+ * without awaiting.
+ *
+ * Three rules:
+ *
+ *  1. **One helper per connection.** Preparing twice returns the same handle, so a reconnect does not
+ *     accumulate temp directories (and the secret is read once).
+ *  2. **Only password connections get one.** Key and agent connections never prompt; handing them
+ *     `BatchMode=no` would let a misconfigured host block on an interactive prompt forever.
+ *  3. **A failure is a degradation, not a throw.** If the secret cannot be resolved the connection still
+ *     works through the transports that do not need it; {@link AskpassRegistry.prepare} reports `undefined`
+ *     and the caller keeps its previous behaviour.
+ *
+ * @module dsh-over-ssh/integration/askpass-registry
+ */
+import { type AskpassHandle } from '../../infra/transport/ssh/askpass.ts';
+import type { ConnectionProfile } from '../../domain/roots/connection.ts';
+/** Options for {@link createAskpassRegistry}. */
+export interface AskpassRegistryOptions {
+    /** Resolve the connection's password. Throws when it is missing or the credential service is absent. */
+    readonly readSecret: (profile: ConnectionProfile) => Promise<string>;
+    /** Materialise one helper for a secret. */
+    readonly create: (secret: string) => Promise<AskpassHandle>;
+    /** Optional sink for "we could not prepare one" so the reason is not swallowed. */
+    readonly onUnavailable?: (connectionId: string, reason: string) => void;
+}
+/** The registry surface the composition root needs. */
+export interface AskpassRegistry {
+    /**
+     * Ensure a helper exists for this connection.
+     *
+     * @param profile - the connection.
+     * @returns the environment to hand `ssh`, or `undefined` when this connection needs none or preparation
+     *          failed (in which case the caller must keep its non-prompting behaviour).
+     */
+    prepare(profile: ConnectionProfile): Promise<Record<string, string> | undefined>;
+    /** The environment prepared for this connection, if any. Synchronous, for transport factories. */
+    envFor(profile: ConnectionProfile): Record<string, string> | undefined;
+    /** Whether a connection is currently using a password helper. */
+    has(connectionId: string): boolean;
+    /** Drop one connection's helper (its transport was released, or the connection changed). */
+    forget(connectionId: string): Promise<void>;
+    /**
+     * Allow a retired connection id to prepare a helper again.
+     *
+     * Call this only when the connection is deliberately re-established. Without it, a re-saved connection
+     * could never get a password helper, because `forget` leaves a tombstone that `prepare` honours.
+     */
+    revive(connectionId: string): void;
+    /** Drop every helper (plugin unload). */
+    disposeAll(): Promise<void>;
+}
+/**
+ * Build the registry.
+ *
+ * @param options - injected secret reader, helper factory and optional sink.
+ * @returns the registry.
+ */
+export declare function createAskpassRegistry(options: AskpassRegistryOptions): AskpassRegistry;

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

@@ -0,0 +1,183 @@
+/**
+ * The remote file index behind `@` completion.
+ *
+ * Requirement FR-2.5 asks for completion over a remote root: prefer `git ls-files` (fast, respects
+ * `.gitignore`), fall back to a **bounded** `find` on hosts without git (our benchmark host has no git),
+ * cache the result, and keep a 900 ms budget so typing never stalls.
+ *
+ * Two tiers serve it, and the choice is reported rather than hidden:
+ *
+ *  - **Tier 2** (`agentScan`) runs the agent's `index.scan`, which measured ~0.16 ms/file on a real host;
+ *  - **Tier 1** runs one shell command over the transport (measured 187–248 ms for 2000 files).
+ *
+ * Budgets are enforced by passing them down (`timeoutMs`), not by hoping: an over-budget result comes back
+ * with `timedOut: true` and whatever was enumerated, so the UI can show partial completion instead of
+ * freezing. Nothing here silently returns a short list as if it were complete.
+ *
+ * @module dsh-over-ssh/integration/remote-index
+ */
+import { type RemoteCapabilities } from '../../domain/capability.ts';
+/** Where a result came from. */
+export type IndexSource = 'agent-index' | 'git-ls-files' | 'find-bounded' | 'cache';
+/** What the index needs from the two tiers. All injected, so this module stays offline-testable. */
+export interface RemoteIndexTiers {
+    /** Tier 2: the agent's `index.scan`. Absent when the connection has no agent. */
+    readonly agentScan?: (root: string, options: {
+        readonly maxEntries: number;
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal;
+    }) => Promise<{
+        readonly paths: readonly string[];
+        readonly strategy: string;
+        readonly truncated: boolean;
+    }>;
+    /**
+     * Tier 2: the agent's `index.refresh` (incremental).
+     *
+     * Only useful **after** a scan the agent still holds a snapshot for; the agent falls back to a full scan
+     * on its own when it cannot refresh, so a caller may always prefer this once it has scanned once. A
+     * transport that predates the method reports `REMOTE_UNSUPPORTED`, which this module treats as "use
+     * agentScan" — never as a failed completion.
+     */
+    readonly agentRefresh?: (root: string, options: {
+        readonly maxEntries: number;
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal;
+    }) => Promise<{
+        readonly paths: readonly string[];
+        readonly strategy: string;
+        readonly truncated: boolean;
+    }>;
+    /** Tier 1: one shell command over the transport. */
+    readonly exec: (command: string, options: {
+        readonly timeoutMs: number;
+        readonly maxBytes: number;
+        readonly signal?: AbortSignal;
+    }) => Promise<{
+        readonly exitCode: number;
+        readonly stdout: string;
+        readonly stderr: string;
+        readonly truncated?: boolean;
+    }>;
+    /** Tier 1 capability facts, used to pick the enumeration command. */
+    readonly capabilities: () => Promise<RemoteCapabilities>;
+}
+/** Options for {@link RemoteIndex}. */
+export interface RemoteIndexOptions {
+    readonly tiers: RemoteIndexTiers;
+    /** How long an enumerated root stays usable. Default 30 s. */
+    readonly ttlMs?: number;
+    /** How many roots to keep. Default 8. */
+    readonly maxRoots?: number;
+    /**
+     * Cap for the "already scanned" hint set (default {@link DEFAULTS.maxScannedRoots}).
+     *
+     * Exposed so a test can drive the bound with a small number instead of allocating 257 roots.
+     */
+    readonly maxScannedRoots?: number;
+    /** Default enumeration budget. Default 900 ms (FR-2.5). */
+    readonly budgetMs?: number;
+    /** Default entry cap. Default 20 000. */
+    readonly maxEntries?: number;
+    /** Byte cap for the cached paths; defaults to {@link DEFAULTS.maxBytes}. */
+    readonly maxBytes?: number;
+    /** Injectable clock, for the TTL and the budget assertions. */
+    readonly now?: () => number;
+}
+/** One enumeration result. */
+export interface IndexResult {
+    readonly paths: readonly string[];
+    readonly source: IndexSource;
+    /** The agent's own strategy string, when Tier 2 served it (`find-bounded`, `git`, …). */
+    readonly agentStrategy?: string;
+    readonly truncated: boolean;
+    /** True when the enumeration stopped because the budget ran out. */
+    readonly timedOut: boolean;
+    /**
+     * Whether the result was cached.
+     *
+     * `false` only for an enumeration that never completed (killed at the deadline, connection lost): such a
+     * result must not be remembered, while a slow-but-successful one must be — the whole point of the cache
+     * is to spare the *next* keystroke, and throwing away a good list because it took 1.2 s would mean
+     * re-running it for every keystroke (found by the real-host measurement).
+     */
+    readonly cacheable: boolean;
+    readonly ms: number;
+    readonly cached: boolean;
+}
+/** One completion request. */
+export interface CompletionRequest {
+    readonly root: string;
+    /** What the user has typed after `@`. */
+    readonly query: string;
+    readonly limit?: number;
+    readonly budgetMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** One completion result. */
+export interface CompletionResult {
+    readonly matches: readonly string[];
+    readonly source: IndexSource;
+    readonly truncated: boolean;
+    readonly timedOut: boolean;
+    readonly ms: number;
+    readonly cached: boolean;
+}
+/** Enumerates a remote root, with TTL caching, ranking and budget accounting. */
+export declare class RemoteIndex {
+    #private;
+    constructor(options: RemoteIndexOptions);
+    /** Enumerate one root (or serve it from cache while fresh). */
+    enumerate(root: string, options?: {
+        readonly maxEntries?: number;
+        readonly budgetMs?: number;
+        readonly force?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<IndexResult>;
+    /**
+     * Completion for a partially typed `@` query.
+     *
+     * Ranking is deliberate and cheap: a basename prefix match beats a path prefix match, which beats a
+     * substring match — so typing `@main` prefers `main.ts` over `src/domain/main-helper.ts`.
+     */
+    complete(request: CompletionRequest): Promise<CompletionResult>;
+    /**
+     * Drop one root (its files changed) or everything.
+     *
+     * **Byte accounting must follow.** Dropping entries without subtracting their bytes made `#cacheBytes` grow
+     * monotonically: after a few invalidate+remember cycles the cap saw a phantom overrun and evicted every live
+     * entry except the newest one, which turned each `@` completion back into a full scan — the exact cost this
+     * cache exists to remove.
+     */
+    invalidate(root?: string): void;
+    /** Whether a root is currently cached and fresh (used by tests and by the status UI). */
+    isFresh(root: string): boolean;
+}
+/**
+ * `git ls-files` for one root.
+ *
+ * `--cached --others --exclude-standard` lists tracked and untracked-but-not-ignored files, which is what
+ * completion should offer; `head -n` bounds the output before it crosses the wire.
+ */
+export declare function gitCommand(root: string, maxEntries: number): string;
+/** Bounded `find` for hosts without git (the benchmark host): files only, no `.git` internals. */
+export declare function findCommand(root: string, maxEntries: number): string;
+/**
+ * The cheap "is this root a git work tree" probe.
+ *
+ * `git ls-files` in the enumeration command is piped into `head`, so its failure (exit 128 in a
+ * non-repository directory) never reaches the caller. This command has no pipe, so its status is git's own:
+ * exit 0 plus `true` on stdout for a work tree, exit non-zero (or `false`) for anything else.
+ */
+export declare function gitRepoProbeCommand(root: string): string;
+/** The cheap "does this directory exist" probe for the find strategy (see `#confirmEmpty`). */
+export declare function directoryProbeCommand(root: string): string;
+/**
+ * Rank paths for a partially typed query.
+ *
+ * @param paths - enumerated paths (absolute or root-relative; both work).
+ * @param query - what the user typed; empty means "show the shallowest entries first".
+ * @param limit - maximum matches.
+ * @returns up to `limit` paths, best first.
+ */
+export declare function rankMatches(paths: readonly string[], query: string, limit: number): readonly string[];

package/lib/types/src/host/integration/roots/remote-home.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Resolve a connection's **home directory** on the remote host.
+ *
+ * Why this exists: the directory browser used to start remote listings at `/` (the filesystem root), which is
+ * almost never what someone adding a remote folder wants — and on a shared server it shows every other
+ * account's home. The obvious "fix" of spelling `home/<user>` is **wrong**, and this host proves it: the login
+ * user's home is `/home1/yezhiyuan` while `/home/yezhiyuan` does not exist, because the site spreads accounts
+ * across `/home`, `/home1`, `/home2`, … (an NFS/automount convention). Only the host can answer the question,
+ * so the answer is **probed, never guessed**.
+ *
+ * Precedence, highest first:
+ *
+ *  1. `remoteDefaultRoot` from the connection's own configuration — an explicit choice always wins.
+ *  2. A probe of the login user's home (`printf %s "$HOME"`), run over the connection's transport.
+ *  3. `/`, the old behaviour, when the probe cannot answer (a transport without command execution, a shell
+ *     that prints nothing, a path that is not absolute). Degrading to the previous behaviour keeps a browse
+ *     surface usable instead of empty.
+ *
+ * Results are cached per connection: the answer is a property of the account, not of the moment, and browsing
+ * re-asks on every level change. {@link RemoteHomeResolver.forget} drops one entry when a connection changes.
+ *
+ * @module dsh-over-ssh/integration/remote-home
+ */
+/** The fallback every path of last resort uses. */
+export declare const REMOTE_ROOT_FALLBACK = "/";
+/** Options for {@link createRemoteHomeResolver}. */
+export interface RemoteHomeResolverOptions {
+    /**
+     * Probe the login user's home over the connection's transport.
+     *
+     * @returns the absolute path, or `undefined` when the host could not answer.
+     */
+    readonly probe: (connectionId: string) => Promise<string | undefined>;
+    /** The connection's configured `remoteDefaultRoot`, when it has one. */
+    readonly configuredRoot?: (connectionId: string) => string | undefined;
+}
+/** The resolver the route calls. */
+export interface RemoteHomeResolver {
+    /**
+     * The directory a remote browse should start at.
+     *
+     * @param connectionId - the connection to resolve for.
+     * @returns an absolute path; never empty, and never throws (failures degrade to `/`).
+     */
+    resolve(connectionId: string): Promise<string>;
+    /** Drop one connection's cached answer (its profile changed, or it was removed). */
+    forget(connectionId: string): void;
+    /** Drop every cached answer. */
+    disposeAll(): void;
+}
+/**
+ * Whether a string is usable as a remote directory to list.
+ *
+ * The same fence the route applies to client-supplied paths: absolute, and no `..` segment. A probe that
+ * answers something else (a shell banner, a relative path, a trailing newline artefact) must not become the
+ * listing target.
+ *
+ * @param value - candidate path.
+ * @returns the normalised path, or `undefined` when it is unusable.
+ */
+export declare function normalizeRemoteDir(value: string | undefined): string | undefined;
+/**
+ * Build the resolver.
+ *
+ * @param options - injected probe and configuration reader.
+ * @returns the resolver.
+ */
+export declare function createRemoteHomeResolver(options: RemoteHomeResolverOptions): RemoteHomeResolver;

package/lib/types/src/host/integration/roots/root-registry.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The root registry: which directories a workspace has, and which backend serves each one.
+ *
+ * It owns exactly one {@link RoutedFileSystem} and mutates it in place, so the object handed to the
+ * core `ctx.fs` provider keeps its identity across root changes (a rebuilt router would silently
+ * invalidate every target key a caller is holding).
+ *
+ * Backend construction is injected: the local and remote backends need `node:fs` and a transport
+ * respectively, and keeping those out of this module is what makes the registry testable without a
+ * filesystem or a network.
+ *
+ * The registry also owns the **session workspace roots** ({@link RootRegistry.syncSessionWorkspaces}): one
+ * hidden, session-scoped local root per live session cwd, so a session's own working directory is always
+ * resolvable — including by absolute path without a cwd, which is how the platform reads the workspace while a
+ * turn starts.
+ *
+ * @module dsh-over-ssh/integration/root-registry
+ */
+import type { Backend } from '../../app/backend.ts';
+import { RoutedFileSystem, type RoutedTarget } from '../../app/routed-fs.ts';
+import { type RootOptions, type RootRef } from '../../domain/roots/root.ts';
+/** One registered root together with its backend. */
+export interface RootRecord {
+    readonly key: string;
+    readonly root: RootRef;
+    readonly backend: Backend;
+}
+/** Options for {@link RootRegistry}. */
+export interface RootRegistryOptions {
+    /** Builds the backend for a local root. */
+    readonly createLocalBackend: (root: RootRef) => Backend;
+    /** Builds the backend for a remote root (one per connection in this design). */
+    readonly createRemoteBackend: (root: RootRef) => Backend;
+    readonly caseInsensitive?: boolean;
+    readonly maxReadBytes?: number;
+    /** Called after every mutation, so a client half or a status view can refresh. */
+    readonly onChanged?: (records: readonly RootRecord[]) => void;
+}
+/** Remote-root options. */
+export interface RemoteRootOptions extends RootOptions {
+    /** Local empty anchor directory; DSH requires a workspace path that exists on the host. */
+    readonly anchorPath?: string;
+}
+/** The set of roots of one workspace. */
+export declare class RootRegistry {
+    #private;
+    constructor(options: RootRegistryOptions);
+    /** The router every consumer reads through (`ctx.fs` wraps this). */
+    get routed(): RoutedFileSystem;
+    /** Registered roots in registration order. **Hidden roots are not here** (see {@link addHidden}). */
+    get records(): readonly RootRecord[];
+    /**
+     * Register a root that only the router knows about.
+     *
+     * Used for the file-level recycle bin, which has to live outside the caller's repository and therefore
+     * outside every visible root (ADR-0011). The backend is built exactly as for a visible root, so routing,
+     * `stat`, `list`, `move` and `remove` all behave normally — what changes is only that nothing lists it.
+     *
+     * Idempotent: registering the same key twice returns the existing record instead of throwing, because the
+     * caller (a bin resolver) may be asked for the same root repeatedly and a duplicate is not an error there.
+     *
+     * @param root - the hidden root to register.
+     * @returns the record, newly created or already present.
+     */
+    addHidden(root: RootRef): RootRecord;
+    /** Hidden roots registered so far (for tests and diagnostics — never for a user-facing list). */
+    get hiddenRecords(): readonly RootRecord[];
+    /** Look up one hidden root by key. */
+    getHidden(key: string): RootRecord | undefined;
+    /** Remove one hidden root by key (used when a connection's bin can no longer be resolved). */
+    removeHidden(key: string): boolean;
+    /** Session-workspace roots added by {@link syncSessionWorkspaces} — diagnostics and tests, never a list. */
+    get sessionWorkspaceRecords(): readonly RootRecord[];
+    /**
+     * Register the **live sessions' working directories** as session-scoped local roots.
+     *
+     * The failure this fixes is turn-level, not tool-level: DSH reads the workspace (`AGENTS.md` and friends)
+     * through `ctx.fs` while a turn is starting, and `@deepseek-ai/dsh-agent-instructions` resolves that file by
+     * **absolute path without a cwd** (`fileSystem.resolve(join(current, marker), { signal })`). A cwd no
+     * registered root covers therefore failed the whole turn before the model was called — and a fallback keyed on
+     * `cwd` cannot help, because that call carries none. So every live session's working directory becomes a real
+     * local root: **in memory only** (never written to `user-roots.json`), scoped to its session
+     * (`workspaces: [cwd]`, which {@link rootVisibleToSession} already reads), and hidden
+     * ({@link addHidden}) so no surface built from `records` shows a directory the user never added.
+     *
+     * Idempotent and cheap: a cwd already covered by a local root is skipped, so a registered root keeps its
+     * priority and its backend; a cwd that already has its session root is reused. Roots whose session is gone are
+     * pruned — an access grant must not outlive the session it was created for — but only when the caller reports
+     * sessions at all: an empty list means "the session service was not readable", not "no session is live", and
+     * dropping every grant on a transient read failure would break live turns.
+     *
+     * @param cwds - working directories of the live sessions, optionally with the session id that owns each one.
+     *   With an id the root carries `sessions: [id]` and is writable **only by that session**; without one it is a
+     *   workspace-scoped root (the legacy shape tests and agentless compositions use).
+     * @returns the session roots this call added (empty when every cwd was already covered).
+     */
+    syncSessionWorkspaces(cwds: readonly (string | {
+        readonly sessionId: string;
+        readonly cwd: string;
+    })[]): readonly RootRecord[];
+    /** Register a local directory root. */
+    addLocal(path: string, options?: RootOptions): RootRecord;
+    /** Register a remote directory root on one connection. */
+    addRemote(connectionId: string, path: string, options?: RemoteRootOptions): RootRecord;
+    /** Register an already-built root reference. */
+    add(root: RootRef): RootRecord;
+    /** Remove one root by key. */
+    remove(key: string): boolean;
+    /**
+     * Remove one root by a key that may differ in case from the registered one.
+     *
+     * Windows local keys are folded by {@link rootKey}, while the file and the client keep the caller's case, so
+     * a removal that only matched verbatim removed the file entry and left the root live. The exact match is
+     * tried first; the fallback folds **only local keys**, where case is not significant on Windows and where
+     * the mismatch can only come from that spelling difference.
+     *
+     * @param key - the key the caller holds.
+     * @returns the key the root was registered under, so related caches can forget the same spelling; `undefined`
+     *   when nothing matched.
+     */
+    removeByLooseKey(key: string): string | undefined;
+    /** Replace every root (workspace switch, profile reload). Hidden roots go too: they are derived from these. */
+    reset(roots: readonly RootRef[]): void;
+    /** Roots belonging to one connection, for connection teardown and status. */
+    forConnection(connectionId: string): readonly RootRecord[];
+    /** Look one root up by key. */
+    get(key: string): RootRecord | undefined;
+    /**
+     * Remove every root of one connection (the connection was deleted or its transport is gone).
+     *
+     * @param connectionId - connection whose roots should disappear.
+     * @returns the removed records, so a caller can report what was dropped.
+     */
+    removeConnection(connectionId: string): readonly RootRecord[];
+}
+/** Declaration merging so the provider can read the registry from `ctx` with a typed property. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Root registry provided by this plugin. */
+        sshDevRoots: RootRegistry;
+    }
+}
+/** Narrow view used by the `ctx.fs` provider: it only needs the router. */
+export interface RoutedTargetOwner {
+    readonly routed: RoutedFileSystem;
+}
+/** Re-exported for consumers that only need the target type. */
+export type { RoutedTarget };