dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,328 @@
+/**
+ * The `ssh2` transport: a pure-JS SSH client.
+ *
+ * Why a second implementation:
+ *
+ *  - **Password authentication** cannot be done by a non-interactive system `ssh` (it hardcodes
+ *    `BatchMode`-style behaviour and would block on a prompt).
+ *  - **Dynamic ProxyJump** chains (per-connection host/port/credentials) cannot be expressed
+ *    through the system client's argv without writing a temporary ssh config.
+ *  - **Connection reuse on Windows**: the host platform's OpenSSH does not support ControlMaster
+ *    (measured: `getsockname failed: Not a socket`), so the only way to reuse one connection for
+ *    many commands there is a client we own. See `doc/03-decisions/0006-windows-host-no-controlmaster.md`.
+ *
+ * Everything the plugin needs from the remote host is expressed with the *same* helpers as the
+ * alias transport — the same probe script, the same shell quoting, the same `size:mtimeSeconds`
+ * version token, the same failure classification — so behaviour does not change when a connection
+ * switches transports. File bytes travel over the SFTP subsystem (part of OpenSSH, still zero
+ * install) instead of base64 over the exec channel.
+ *
+ * The client itself is injected (`Ssh2Connector`), so this module never imports the `ssh2`
+ * package: unit tests run without it and without a network.
+ *
+ * @module dsh-over-ssh/infra/transport/ssh2-transport
+ */
+import { type RemoteCapabilities } from '../../../domain/capability.ts';
+import type { HostKeyPolicy } from '../../../domain/roots/connection.ts';
+import { SshDevError } from '../../../domain/errors.ts';
+import { type ExecRequest, type ExecResult, type ReadFileRangeRequest, type ReadFileRequest, type RemoteFileChunk, type RemoteWriteOutcome, type RemoveRequest, type RenameRequest, type Transport, type WriteFileRangeRequest, type WriteFileRequest } from '../transport.ts';
+import { TransportBase } from '../transport-base.ts';
+/** Authentication material for one hop. */
+export interface Ssh2Auth {
+    readonly password?: string;
+    readonly privateKey?: string | Uint8Array;
+    readonly passphrase?: string;
+    /** ssh-agent socket path, or `pageant` on Windows. */
+    readonly agent?: string;
+}
+/** One host to connect to. */
+export interface Ssh2Target {
+    readonly host: string;
+    readonly port?: number;
+    readonly username: string;
+    readonly auth: Ssh2Auth;
+}
+/** Everything needed to open a session. */
+export interface Ssh2ConnectConfig {
+    /** Final target. */
+    readonly target: Ssh2Target;
+    /** Ordered jump hosts: hop 0 is reached directly, each next hop through the previous one. */
+    readonly jump?: readonly Ssh2Target[];
+    readonly hostKeyPolicy?: HostKeyPolicy;
+    /** Accepted host key fingerprints (`SHA256:…`), required when the policy is `strict`. */
+    readonly trustedHostKeys?: readonly string[];
+    readonly connectTimeoutMs?: number;
+    readonly keepAliveMs?: number;
+    /** Cancellation for the connect attempt. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * An SFTP file handle.
+ *
+ * Opaque on purpose: `ssh2` hands back a raw `Buffer` handle that is only meaningful to
+ * `sftp.read` / `sftp.close` (verified against the real library — there is **no**
+ * `handle.read` method, which is exactly the mistake this shape prevents).
+ */
+export type Ssh2FileHandle = unknown;
+/** SFTP statistics as far as this transport needs them. */
+export interface Ssh2Stats {
+    /** Base name of a `readdir` entry; absent on objects returned by `stat`. */
+    readonly filename?: string;
+    readonly size: number;
+    /**
+     * Modification time in **seconds** since the epoch.
+     *
+     * SFTP v3 attributes carry seconds, and `ssh2` passes them through unchanged (verified on a
+     * real host: `mtime = 1789217901`). The alias transport's `stat -c %Y` also reports seconds, so
+     * keeping the same unit is what makes version tokens comparable across transports.
+     */
+    readonly mtime: number;
+    /**
+     * SFTP file mode bits (`stats.mode & 0o170000`).
+     *
+     * Optional because a caller may hand over a `Stats`-shaped object without it, but the real
+     * library always sets it. It is the only reliable way to detect a **symbolic link** during a
+     * recursive removal: SFTP v3 `readdir` reports the link itself and never follows it.
+     */
+    readonly mode?: number;
+    /** `readdir` long name; starts with `l` for a symbolic link (`-` file, `d` directory). */
+    readonly longname?: string;
+    isDirectory?(): boolean;
+    isFile?(): boolean;
+    isSymbolicLink?(): boolean;
+}
+/**
+ * The narrow SFTP surface this transport uses, mirroring the real `ssh2` API:
+ * `open` yields a handle, and reads go through `read(handle, …)`, not through the handle.
+ *
+ * `readdir` / `rmdir` are optional for the same reason `ext_openssh_rename` is: a fake or a
+ * non-OpenSSH server may not provide them, and {@link Ssh2Transport.remove} must then report
+ * `REMOTE_UNSUPPORTED` instead of pretending a tree went away.
+ */
+export interface Ssh2Sftp {
+    stat(path: string, callback: (error?: Error, stats?: Ssh2Stats) => void): void;
+    open(path: string, flags: string, callback: (error?: Error, handle?: Ssh2FileHandle) => void): void;
+    /** Read into a real `Buffer` (the library rejects plain `Uint8Array` views). */
+    read(handle: Ssh2FileHandle, buffer: Buffer, offset: number, length: number, position: number, callback: (error?: Error, bytesRead?: number) => void): void;
+    /**
+     * Positioned write into an open handle. `position` is the **file** offset; `offset` is the
+     * offset inside `buffer` (the same parameter order as the real library).
+     */
+    write(handle: Ssh2FileHandle, buffer: Buffer, offset: number, length: number, position: number, callback: (error?: Error) => void): void;
+    close(handle: Ssh2FileHandle, callback: (error?: Error) => void): void;
+    /** Statistics for an **open handle**, used to size a positioned write before truncating. */
+    fstat?(handle: Ssh2FileHandle, callback: (error?: Error, stats?: Ssh2Stats) => void): void;
+    /** Truncate an open handle to `length` bytes. */
+    ftruncate?(handle: Ssh2FileHandle, length: number, callback: (error?: Error) => void): void;
+    writeFile(path: string, data: Uint8Array, callback: (error?: Error) => void): void;
+    mkdir(path: string, attributes: {
+        readonly mode: number;
+    }, callback: (error?: Error) => void): void;
+    /** List a directory. The v3 protocol returns `.` and `..` too, so callers must skip them. */
+    readdir?(path: string, callback: (error?: Error, entries?: readonly Ssh2Stats[]) => void): void;
+    /** Remove an **empty** directory. */
+    rmdir?(path: string, callback: (error?: Error) => void): void;
+    /**
+     * Plain SFTP rename.
+     *
+     * Measured on a real OpenSSH server: this **fails with SSH_FX_FAILURE when the destination
+     * already exists**, so it cannot be the only path for an overwriting write.
+     */
+    rename(from: string, to: string, callback: (error?: Error) => void): void;
+    /**
+     * `posix-rename@openssh.com`: atomic overwrite. Present on OpenSSH servers/clients, absent
+     * elsewhere — which is why {@link writeFile} keeps a fallback ladder.
+     */
+    ext_openssh_rename?: ((from: string, to: string, callback: (error?: Error) => void) => void) | undefined;
+    unlink(path: string, callback: (error?: Error) => void): void;
+    end(): void;
+}
+/** A command channel as far as this transport needs it. */
+export interface Ssh2Channel {
+    on(event: 'data', listener: (chunk: Buffer) => void): this;
+    on(event: 'close', listener: (code: number | null, signal: string | null) => void): this;
+    on(event: string, listener: (...args: never[]) => void): this;
+    stderr: {
+        on(event: 'data', listener: (chunk: Buffer) => void): unknown;
+    };
+    write(data: string | Uint8Array): boolean;
+    end(data?: string | Uint8Array): void;
+    close(): void;
+}
+/** An open SSH session: many channels, one connection. */
+export interface Ssh2Session {
+    exec(command: string, options: {
+        readonly pty?: boolean;
+    }, callback: (error?: Error, channel?: Ssh2Channel) => void): void;
+    sftp(callback: (error?: Error, sftp?: Ssh2Sftp) => void): void;
+    /** Open a TCP channel through this session, used to chain jump hosts. */
+    forwardOut(sourceAddress: string, sourcePort: number, destinationAddress: string, destinationPort: number, callback: (error?: Error, stream?: unknown) => void): void;
+    end(): void;
+    destroy(): void;
+    /**
+     * Intermediate jump-host sessions this session rides on, so `dispose()` can close them too.
+     *
+     * **Deliberately per-session, not a module-level slot.** The first version of this fix kept them in
+     * a module-level `lastHops`, which is wrong as soon as one process has two connections
+     * (`TransportService` caches by `profile.id`, so multiple profiles are normal):
+     *  - the second `connect` cleared the array, so the first connection's hops were **leaked**;
+     *  - the first `dispose()` then took the *second* connection's hops and **ended a live connection
+     *    another transport was still using**.
+     * Hanging them on the session they belong to makes ownership structural instead of positional.
+     * `ssh2`'s real `Client` has no such property, so it is optional and set only by
+     * {@link defaultConnector}.
+     */
+    readonly hops?: readonly Ssh2Session[];
+}
+/** Opens a session; injected so tests never load the real client. */
+export type Ssh2Connector = (config: Ssh2ConnectConfig) => Promise<Ssh2Session>;
+/** Construction options. */
+export interface Ssh2TransportOptions {
+    readonly connectionId: string;
+    /** Session factory. Defaults to the real `ssh2` client (loaded lazily). */
+    readonly connector?: Ssh2Connector;
+    readonly connect?: Ssh2ConnectConfig;
+    readonly commandTimeoutMs?: number;
+    readonly now?: () => number;
+}
+/**
+ * Bytes of a command's **stderr** that are retained.
+ *
+ * `maxBytes` bounds stdout only, and stderr used to be accumulated without any bound at all: a command
+ * that writes diagnostics in a loop (`ssh -v`, a verbose build, a remote program that logs errors) grew
+ * this process's heap until the channel closed. Measured before the fix: a peer emitting 64 MiB of
+ * stderr retained **all 64 MiB** while stdout was correctly capped at 1 KiB (审计 0050).
+ *
+ * The **tail** is kept, not the head: every consumer of this string wants the last thing the command
+ * said. `domain/errors.ts` reduces it with `tail(stderr, 2000)` for classification, and a failing
+ * command's useful diagnostic (the final error, the `DSH_ERROR=` refusal) is at the end.
+ */
+export declare const SSH2_STDERR_MAX_BYTES: number;
+/**
+ * First line prepended to a truncated stderr capture.
+ *
+ * The truncation is announced **in the string itself** because `ExecResult.truncated` is stdout's flag
+ * (see its JSDoc) and must keep that meaning: `remote-backend` treats a truncated batch read as "these
+ * paths were not read", so setting it for a chatty command's stderr would report readable files as
+ * missing. Announcing it here keeps the diagnostic honest without overloading the flag.
+ */
+export declare const STDERR_TRUNCATION_NOTICE = "\uFF08stderr \u8FC7\u957F\uFF0C\u4EC5\u4FDD\u7559\u672B\u5C3E\u7247\u6BB5\uFF09";
+/**
+ * The pure-JS transport.
+ *
+ * One session serves every command and every file transfer, which is what gives Windows hosts
+ * the connection reuse their OpenSSH client cannot provide.
+ */
+export declare class Ssh2Transport extends TransportBase implements Transport {
+    #private;
+    readonly id: string;
+    constructor(options: Ssh2TransportOptions);
+    get sessionCount(): number;
+    /**
+     * Open the session; concurrent calls share one attempt.
+     *
+     * The attempt owns its own controller and is aborted only when the **last** waiter gives up, so one
+     * caller's cancellation no longer rejects the others with `CANCELLED` (audit 2026-10-31 P1) while a lone
+     * cancelled dial still stops instead of running to `readyTimeout`.
+     */
+    connect(signal?: AbortSignal): Promise<void>;
+    /** Close the session. Idempotent. */
+    dispose(): Promise<void>;
+    /** Run one remote command over a channel of the shared session. */
+    exec(request: ExecRequest, signal?: AbortSignal): Promise<ExecResult>;
+    /**
+     * Read a remote file over SFTP.
+     *
+     * The version token is `size:mtimeSeconds` — the same shape the alias transport produces, so
+     * caches keyed on version tokens keep working when a connection changes transport.
+     */
+    readFile(request: ReadFileRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Read `maxBytes` from `offset` over SFTP, seeking with a real `position`.
+     *
+     * Why the seek matters: `readFile` always starts at 0, so paging through a large file by
+     * reading `[0, offset+len)` and slicing transfers every earlier byte on every page. Here the
+     * server only sends the requested window, and only `maxBytes` is ever allocated locally.
+     */
+    readFileRange(request: ReadFileRangeRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Write at `offset` over SFTP, leaving the bytes before it untouched.
+     *
+     * Flags are chosen by offset, and the semantics are deliberately narrow:
+     *
+     *  - `offset === 0` uses `'w'`: the file is **created or truncated**, so a chunked upload that
+     *    restarts from 0 overwrites a longer previous file instead of leaving a stale tail.
+     *  - `offset > 0` uses `'r+'`: the file **must already exist** (there is no other way to preserve
+     *    the earlier bytes), otherwise `REMOTE_NOT_FOUND`.
+     *
+     * Neither branch truncates: the bytes outside the written range are left alone (POSIX `pwrite`), the same
+     * meaning the shell transports give `dd conv=notrunc`. An earlier version of this comment claimed the file
+     * was truncated to `offset + bytes.byteLength` — it never was, and doing so would have made the same call
+     * mean two different things depending on which transport answered.
+     */
+    writeFileRange(request: WriteFileRangeRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Move a remote path with a plain SFTP `rename`.
+     *
+     * A cross-device move makes the server fail (`SSH_FX_FAILURE` / `EXDEV`) and that failure is
+     * **propagated as-is**: copying would silently turn a move into a copy, which breaks the
+     * "move, then delete the source only after confirmation" semantics callers rely on.
+     */
+    rename(request: RenameRequest, signal?: AbortSignal): Promise<void>;
+    /**
+     * Remove a file, or a directory tree when `recursive` is set.
+     *
+     * A directory without `recursive` is an explicit error, never a silent success: a caller that
+     * hears "removed" must be able to trust that the path is gone.
+     *
+     * Symbolic links are never followed. SFTP v3 `readdir` reports a link as an entry with
+     * `mode & 0o170000 === 0o120000`; treating it as a directory would either recurse forever on a
+     * self-referential link or descend into a tree that was never requested for deletion.
+     */
+    remove(request: RemoveRequest, signal?: AbortSignal): Promise<void>;
+    /**
+     * Write a remote file over SFTP: temp file in the target directory, then a rename.
+     *
+     * The optional `expectedSha256` guard runs the same remote digest tool the alias transport
+     * uses, so a guarded write means the same thing on both transports.
+     */
+    writeFile(request: WriteFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Probe the remote host once and remember the result.
+     *
+     * @param signal - cancellation.
+     * @param maxAgeMs - reuse a previous probe inside this window (default 5 minutes).
+     * @returns the discovered capabilities.
+     */
+    probeCapabilities(signal?: AbortSignal, maxAgeMs?: number): Promise<RemoteCapabilities>;
+}
+/**
+ * Tier 1 的版本令牌：`size:mtimeSeconds`。
+ *
+ * **不是「所有传输共用」**：Tier 2 的令牌由代理侧产生，形状以 `infra/transport/transport.ts` 的
+ * `RemoteStatResult.version` 注释为准（本文件不再复述那个形状——三处注释曾经互相矛盾，见审计
+ * 2026-10-31 P3；能验证的只有"两端从不互相比较"这一条，因为令牌只在产生它的那条连接里回传）。
+ *
+ * 已知限制：这里的 mtime 只有**秒**级（来自远端 `ls`/`stat` 的文本输出），同一秒内、大小不变的
+ * 两次写入无法区分。Tier 2 的令牌更细（代理侧能拿到更精确的时间）；Tier 1 要补得改远端命令，
+ * 代价与收益不成比例，先如实记在这里而不是假装没有。
+ */
+export declare function versionToken(size: number, mtimeSeconds: number): string;
+/**
+ * Map an SFTP failure onto a plugin error code.
+ *
+ * A remote `permission denied` is **not** `SANDBOX_DENIED`: that code means "the plugin's own fence refused
+ * this write" (`doc/07-reference/error-codes.md`, and `fs-provider.ts` maps it to `FS_SANDBOX_DENIED`). A 0755
+ * directory or a foreign owner on the server is an ordinary remote failure, and reporting it as a fence refusal
+ * sends the caller looking for a different path instead of at permissions (audit 2026-10-31 P2).
+ */
+export declare function sftpError(operation: string, path: string, error?: Error): SshDevError;
+/**
+ * The real connector: wraps the `ssh2` package.
+ *
+ * Loaded lazily so this module (and its unit tests) never require the dependency, and required
+ * for dynamic jump chains: each hop is reached by forwarding a TCP channel through the previous
+ * session.
+ */
+export declare const defaultConnector: Ssh2Connector;
+//# sourceMappingURL=ssh2-transport.d.ts.map

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

@@ -0,0 +1,43 @@
+/**
+ * The one place that decides which `ssh` arguments a connection's credentials turn into.
+ *
+ * Two call sites need exactly the same answer — the alias transport (which builds master and per-command
+ * argv) and the Tier 2 agent launcher (which spawns `ssh <alias> <agent> --stdio`) — and the agent-path e2e
+ * caught both of them drifting: the transport ignored `keyPath`, then the launcher ignored `user`, so the
+ * ladder authenticated and the agent session did not. Duplicating this list is what allowed that.
+ *
+ * Honesty rule: a value is only emitted when the connection actually set it. Emitting `-l`/`-i`
+ * unconditionally would override the user's own `~/.ssh/config`, which is the alias transport's whole point.
+ *
+ * @module dsh-remote-workspace/infra/transport/ssh-argv
+ */
+import type { HostKeyPolicy } from '../../domain/connection.ts';
+/** Credential-ish options shared by every `ssh` invocation this plugin makes. */
+export interface SshArgvOptions {
+    /** Destination: an `~/.ssh/config` alias or a bare `user@host`-less host. */
+    readonly alias: string;
+    /** Remote user; omitted or empty means "let ssh decide". */
+    readonly user?: string;
+    /** `-i` identity file. */
+    readonly identityFile?: string;
+    /** `-o UserKnownHostsFile=…`. */
+    readonly knownHostsFile?: string;
+    readonly hostKeyPolicy?: HostKeyPolicy;
+    readonly connectTimeoutMs?: number;
+    /** `-o BatchMode=yes` (never prompt). Defaults to true: this plugin never has a human at the tty. */
+    readonly batchMode?: boolean;
+    /** Extra `-o` options appended verbatim, in order. */
+    readonly extraOptions?: readonly string[];
+}
+/** `-i`, `-o UserKnownHostsFile`, `-l` — only what the connection configured. */
+export declare function credentialArgv(options: SshArgvOptions): readonly string[];
+/** Common `-o` options (policy, timeout, batch mode) plus {@link credentialArgv}. */
+export declare function commonSshOptions(options: SshArgvOptions): readonly string[];
+/**
+ * A complete `ssh` prefix ending at the destination: `ssh -T <options…> <alias>`.
+ *
+ * The Tier 2 launcher appends the remote command to this; the alias transport appends its own control
+ * sockets and the command.
+ */
+export declare function sshPrefix(sshBinary: string, options: SshArgvOptions): readonly string[];
+//# sourceMappingURL=ssh-argv.d.ts.map

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

@@ -0,0 +1,302 @@
+/**
+ * The `ssh2` transport: a pure-JS SSH client.
+ *
+ * Why a second implementation:
+ *
+ *  - **Password authentication** cannot be done by a non-interactive system `ssh` (it hardcodes
+ *    `BatchMode`-style behaviour and would block on a prompt).
+ *  - **Dynamic ProxyJump** chains (per-connection host/port/credentials) cannot be expressed
+ *    through the system client's argv without writing a temporary ssh config.
+ *  - **Connection reuse on Windows**: the host platform's OpenSSH does not support ControlMaster
+ *    (measured: `getsockname failed: Not a socket`), so the only way to reuse one connection for
+ *    many commands there is a client we own. See `doc/03-decisions/0006-windows-host-no-controlmaster.md`.
+ *
+ * Everything the plugin needs from the remote host is expressed with the *same* helpers as the
+ * alias transport — the same probe script, the same shell quoting, the same `size:mtimeSeconds`
+ * version token, the same failure classification — so behaviour does not change when a connection
+ * switches transports. File bytes travel over the SFTP subsystem (part of OpenSSH, still zero
+ * install) instead of base64 over the exec channel.
+ *
+ * The client itself is injected (`Ssh2Connector`), so this module never imports the `ssh2`
+ * package: unit tests run without it and without a network.
+ *
+ * @module dsh-remote-workspace/infra/transport/ssh2-transport
+ */
+import { type RemoteCapabilities } from '../../domain/capability.ts';
+import type { HostKeyPolicy } from '../../domain/connection.ts';
+import { SshDevError } from '../../domain/errors.ts';
+import { type ExecRequest, type ExecResult, type ReadFileRangeRequest, type ReadFileRequest, type RemoteFileChunk, type RemoteWriteOutcome, type RemoveRequest, type RenameRequest, type Transport, type WriteFileRangeRequest, type WriteFileRequest } from './transport.ts';
+import { TransportBase } from './transport-base.ts';
+/** Authentication material for one hop. */
+export interface Ssh2Auth {
+    readonly password?: string;
+    readonly privateKey?: string | Uint8Array;
+    readonly passphrase?: string;
+    /** ssh-agent socket path, or `pageant` on Windows. */
+    readonly agent?: string;
+}
+/** One host to connect to. */
+export interface Ssh2Target {
+    readonly host: string;
+    readonly port?: number;
+    readonly username: string;
+    readonly auth: Ssh2Auth;
+}
+/** Everything needed to open a session. */
+export interface Ssh2ConnectConfig {
+    /** Final target. */
+    readonly target: Ssh2Target;
+    /** Ordered jump hosts: hop 0 is reached directly, each next hop through the previous one. */
+    readonly jump?: readonly Ssh2Target[];
+    readonly hostKeyPolicy?: HostKeyPolicy;
+    /** Accepted host key fingerprints (`SHA256:…`), required when the policy is `strict`. */
+    readonly trustedHostKeys?: readonly string[];
+    readonly connectTimeoutMs?: number;
+    readonly keepAliveMs?: number;
+    /** Cancellation for the connect attempt. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * An SFTP file handle.
+ *
+ * Opaque on purpose: `ssh2` hands back a raw `Buffer` handle that is only meaningful to
+ * `sftp.read` / `sftp.close` (verified against the real library — there is **no**
+ * `handle.read` method, which is exactly the mistake this shape prevents).
+ */
+export type Ssh2FileHandle = unknown;
+/** SFTP statistics as far as this transport needs them. */
+export interface Ssh2Stats {
+    /** Base name of a `readdir` entry; absent on objects returned by `stat`. */
+    readonly filename?: string;
+    readonly size: number;
+    /**
+     * Modification time in **seconds** since the epoch.
+     *
+     * SFTP v3 attributes carry seconds, and `ssh2` passes them through unchanged (verified on a
+     * real host: `mtime = 1789217901`). The alias transport's `stat -c %Y` also reports seconds, so
+     * keeping the same unit is what makes version tokens comparable across transports.
+     */
+    readonly mtime: number;
+    /**
+     * SFTP file mode bits (`stats.mode & 0o170000`).
+     *
+     * Optional because a caller may hand over a `Stats`-shaped object without it, but the real
+     * library always sets it. It is the only reliable way to detect a **symbolic link** during a
+     * recursive removal: SFTP v3 `readdir` reports the link itself and never follows it.
+     */
+    readonly mode?: number;
+    /** `readdir` long name; starts with `l` for a symbolic link (`-` file, `d` directory). */
+    readonly longname?: string;
+    isDirectory?(): boolean;
+    isFile?(): boolean;
+    isSymbolicLink?(): boolean;
+}
+/**
+ * The narrow SFTP surface this transport uses, mirroring the real `ssh2` API:
+ * `open` yields a handle, and reads go through `read(handle, …)`, not through the handle.
+ *
+ * `readdir` / `rmdir` are optional for the same reason `ext_openssh_rename` is: a fake or a
+ * non-OpenSSH server may not provide them, and {@link Ssh2Transport.remove} must then report
+ * `REMOTE_UNSUPPORTED` instead of pretending a tree went away.
+ */
+export interface Ssh2Sftp {
+    stat(path: string, callback: (error?: Error, stats?: Ssh2Stats) => void): void;
+    open(path: string, flags: string, callback: (error?: Error, handle?: Ssh2FileHandle) => void): void;
+    /** Read into a real `Buffer` (the library rejects plain `Uint8Array` views). */
+    read(handle: Ssh2FileHandle, buffer: Buffer, offset: number, length: number, position: number, callback: (error?: Error, bytesRead?: number) => void): void;
+    /**
+     * Positioned write into an open handle. `position` is the **file** offset; `offset` is the
+     * offset inside `buffer` (the same parameter order as the real library).
+     */
+    write(handle: Ssh2FileHandle, buffer: Buffer, offset: number, length: number, position: number, callback: (error?: Error) => void): void;
+    close(handle: Ssh2FileHandle, callback: (error?: Error) => void): void;
+    /** Statistics for an **open handle**, used to size a positioned write before truncating. */
+    fstat?(handle: Ssh2FileHandle, callback: (error?: Error, stats?: Ssh2Stats) => void): void;
+    /** Truncate an open handle to `length` bytes. */
+    ftruncate?(handle: Ssh2FileHandle, length: number, callback: (error?: Error) => void): void;
+    writeFile(path: string, data: Uint8Array, callback: (error?: Error) => void): void;
+    mkdir(path: string, attributes: {
+        readonly mode: number;
+    }, callback: (error?: Error) => void): void;
+    /** List a directory. The v3 protocol returns `.` and `..` too, so callers must skip them. */
+    readdir?(path: string, callback: (error?: Error, entries?: readonly Ssh2Stats[]) => void): void;
+    /** Remove an **empty** directory. */
+    rmdir?(path: string, callback: (error?: Error) => void): void;
+    /**
+     * Plain SFTP rename.
+     *
+     * Measured on a real OpenSSH server: this **fails with SSH_FX_FAILURE when the destination
+     * already exists**, so it cannot be the only path for an overwriting write.
+     */
+    rename(from: string, to: string, callback: (error?: Error) => void): void;
+    /**
+     * `posix-rename@openssh.com`: atomic overwrite. Present on OpenSSH servers/clients, absent
+     * elsewhere — which is why {@link writeFile} keeps a fallback ladder.
+     */
+    ext_openssh_rename?: ((from: string, to: string, callback: (error?: Error) => void) => void) | undefined;
+    unlink(path: string, callback: (error?: Error) => void): void;
+    end(): void;
+}
+/** A command channel as far as this transport needs it. */
+export interface Ssh2Channel {
+    on(event: 'data', listener: (chunk: Buffer) => void): this;
+    on(event: 'close', listener: (code: number | null, signal: string | null) => void): this;
+    on(event: string, listener: (...args: never[]) => void): this;
+    stderr: {
+        on(event: 'data', listener: (chunk: Buffer) => void): unknown;
+    };
+    write(data: string | Uint8Array): boolean;
+    end(data?: string | Uint8Array): void;
+    close(): void;
+}
+/** An open SSH session: many channels, one connection. */
+export interface Ssh2Session {
+    exec(command: string, options: {
+        readonly pty?: boolean;
+    }, callback: (error?: Error, channel?: Ssh2Channel) => void): void;
+    sftp(callback: (error?: Error, sftp?: Ssh2Sftp) => void): void;
+    /** Open a TCP channel through this session, used to chain jump hosts. */
+    forwardOut(sourceAddress: string, sourcePort: number, destinationAddress: string, destinationPort: number, callback: (error?: Error, stream?: unknown) => void): void;
+    end(): void;
+    destroy(): void;
+    /**
+     * Intermediate jump-host sessions this session rides on, so `dispose()` can close them too.
+     *
+     * **Deliberately per-session, not a module-level slot.** The first version of this fix kept them in
+     * a module-level `lastHops`, which is wrong as soon as one process has two connections
+     * (`TransportService` caches by `profile.id`, so multiple profiles are normal):
+     *  - the second `connect` cleared the array, so the first connection's hops were **leaked**;
+     *  - the first `dispose()` then took the *second* connection's hops and **ended a live connection
+     *    another transport was still using**.
+     * Hanging them on the session they belong to makes ownership structural instead of positional.
+     * `ssh2`'s real `Client` has no such property, so it is optional and set only by
+     * {@link defaultConnector}.
+     */
+    readonly hops?: readonly Ssh2Session[];
+}
+/** Opens a session; injected so tests never load the real client. */
+export type Ssh2Connector = (config: Ssh2ConnectConfig) => Promise<Ssh2Session>;
+/** Construction options. */
+export interface Ssh2TransportOptions {
+    readonly connectionId: string;
+    /** Session factory. Defaults to the real `ssh2` client (loaded lazily). */
+    readonly connector?: Ssh2Connector;
+    readonly connect?: Ssh2ConnectConfig;
+    readonly commandTimeoutMs?: number;
+    readonly now?: () => number;
+}
+/**
+ * Bytes of a command's **stderr** that are retained.
+ *
+ * `maxBytes` bounds stdout only, and stderr used to be accumulated without any bound at all: a command
+ * that writes diagnostics in a loop (`ssh -v`, a verbose build, a remote program that logs errors) grew
+ * this process's heap until the channel closed. Measured before the fix: a peer emitting 64 MiB of
+ * stderr retained **all 64 MiB** while stdout was correctly capped at 1 KiB (审计 0050).
+ *
+ * The **tail** is kept, not the head: every consumer of this string wants the last thing the command
+ * said. `domain/errors.ts` reduces it with `tail(stderr, 2000)` for classification, and a failing
+ * command's useful diagnostic (the final error, the `DSH_ERROR=` refusal) is at the end.
+ */
+export declare const SSH2_STDERR_MAX_BYTES: number;
+/**
+ * First line prepended to a truncated stderr capture.
+ *
+ * The truncation is announced **in the string itself** because `ExecResult.truncated` is stdout's flag
+ * (see its JSDoc) and must keep that meaning: `remote-backend` treats a truncated batch read as "these
+ * paths were not read", so setting it for a chatty command's stderr would report readable files as
+ * missing. Announcing it here keeps the diagnostic honest without overloading the flag.
+ */
+export declare const STDERR_TRUNCATION_NOTICE = "\uFF08stderr \u8FC7\u957F\uFF0C\u4EC5\u4FDD\u7559\u672B\u5C3E\u7247\u6BB5\uFF09";
+/**
+ * The pure-JS transport.
+ *
+ * One session serves every command and every file transfer, which is what gives Windows hosts
+ * the connection reuse their OpenSSH client cannot provide.
+ */
+export declare class Ssh2Transport extends TransportBase implements Transport {
+    #private;
+    readonly id: string;
+    constructor(options: Ssh2TransportOptions);
+    get sessionCount(): number;
+    /** Open the session; concurrent calls share one attempt. */
+    connect(signal?: AbortSignal): Promise<void>;
+    /** Close the session. Idempotent. */
+    dispose(): Promise<void>;
+    /** Run one remote command over a channel of the shared session. */
+    exec(request: ExecRequest, signal?: AbortSignal): Promise<ExecResult>;
+    /**
+     * Read a remote file over SFTP.
+     *
+     * The version token is `size:mtimeSeconds` — the same shape the alias transport produces, so
+     * caches keyed on version tokens keep working when a connection changes transport.
+     */
+    readFile(request: ReadFileRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Read `maxBytes` from `offset` over SFTP, seeking with a real `position`.
+     *
+     * Why the seek matters: `readFile` always starts at 0, so paging through a large file by
+     * reading `[0, offset+len)` and slicing transfers every earlier byte on every page. Here the
+     * server only sends the requested window, and only `maxBytes` is ever allocated locally.
+     */
+    readFileRange(request: ReadFileRangeRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Write at `offset` over SFTP, leaving the bytes before it untouched.
+     *
+     * Flags are chosen by offset, and the semantics are deliberately narrow:
+     *
+     *  - `offset === 0` uses `'w'`: the file is **created or truncated**, so a chunked upload that
+     *    restarts from 0 overwrites a longer previous file instead of leaving a stale tail.
+     *  - `offset > 0` uses `'r+'`: the file **must already exist** (there is no other way to preserve
+     *    the earlier bytes), otherwise `REMOTE_NOT_FOUND`. After the positioned write the file is
+     *    truncated to `offset + bytes.byteLength` — a shorter final chunk must shorten the file, or
+     *    the tail of a previous, longer upload would survive and corrupt the result.
+     */
+    writeFileRange(request: WriteFileRangeRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Move a remote path with a plain SFTP `rename`.
+     *
+     * A cross-device move makes the server fail (`SSH_FX_FAILURE` / `EXDEV`) and that failure is
+     * **propagated as-is**: copying would silently turn a move into a copy, which breaks the
+     * "move, then delete the source only after confirmation" semantics callers rely on.
+     */
+    rename(request: RenameRequest, signal?: AbortSignal): Promise<void>;
+    /**
+     * Remove a file, or a directory tree when `recursive` is set.
+     *
+     * A directory without `recursive` is an explicit error, never a silent success: a caller that
+     * hears "removed" must be able to trust that the path is gone.
+     *
+     * Symbolic links are never followed. SFTP v3 `readdir` reports a link as an entry with
+     * `mode & 0o170000 === 0o120000`; treating it as a directory would either recurse forever on a
+     * self-referential link or descend into a tree that was never requested for deletion.
+     */
+    remove(request: RemoveRequest, signal?: AbortSignal): Promise<void>;
+    /**
+     * Write a remote file over SFTP: temp file in the target directory, then a rename.
+     *
+     * The optional `expectedSha256` guard runs the same remote digest tool the alias transport
+     * uses, so a guarded write means the same thing on both transports.
+     */
+    writeFile(request: WriteFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Probe the remote host once and remember the result.
+     *
+     * @param signal - cancellation.
+     * @param maxAgeMs - reuse a previous probe inside this window (default 5 minutes).
+     * @returns the discovered capabilities.
+     */
+    probeCapabilities(signal?: AbortSignal, maxAgeMs?: number): Promise<RemoteCapabilities>;
+}
+/** Version token shared by every transport: `size:mtimeSeconds`. */
+export declare function versionToken(size: number, mtimeSeconds: number): string;
+/** Map an SFTP failure onto a plugin error code. */
+export declare function sftpError(operation: string, path: string, error?: Error): SshDevError;
+/**
+ * The real connector: wraps the `ssh2` package.
+ *
+ * Loaded lazily so this module (and its unit tests) never require the dependency, and required
+ * for dynamic jump chains: each hop is reached by forwarding a TCP channel through the previous
+ * session.
+ */
+export declare const defaultConnector: Ssh2Connector;
+//# sourceMappingURL=ssh2-transport.d.ts.map