dsh-over-ssh 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,81 @@
+/**
+ * Transport lifecycle: acquire, reuse, replace and release one transport per connection.
+ *
+ * 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).
+ *  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
+ *     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.
+ *
+ * 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.
+ *
+ * @module dsh-over-ssh/app/transport-service
+ */
+import type { ConnectionProfile } from '../../domain/roots/connection.ts';
+import type { Transport } from '../../infra/transport/transport.ts';
+import type { TransportDecision } from './transport-selector.ts';
+import type { TransportSelector } from './transport-selector.ts';
+/** Creates the implementation chosen by the selector. */
+export interface TransportFactories {
+    readonly createAlias: (profile: ConnectionProfile, decision: TransportDecision) => Transport;
+    readonly createSsh2: (profile: ConnectionProfile, decision: TransportDecision) => Transport;
+    /**
+     * 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;
+}
+/**
+ * Optional asynchronous step between deciding and connecting.
+ *
+ * The synchronous selector cannot know whether the agent's install ladder succeeded — that requires
+ * talking to the host. A preflight therefore gets the first decision and may revise it (for example
+ * `agent` → `alias` once the ladder reported a reason), which is how "agent unavailable ⇒ fall back to
+ * Tier 1" is enforced *before* a transport is built.
+ */
+/**
+ * Preflight hook: may replace the decision (e.g. "install the agent and use Tier 2 after all").
+ *
+ * `signal` is the caller's cancellation for the whole acquire. It must reach the hook: the ladder it runs
+ * (ssh connect, manifest load, `$HOME` probe, agent upload) can take minutes, and a cancelled call used to
+ * keep uploading anyway because only `transport.connect()` saw the signal.
+ */
+export type TransportPreflight = (profile: ConnectionProfile, decision: TransportDecision, signal?: AbortSignal) => Promise<TransportDecision>;
+/** One acquired transport plus the decision that produced it. */
+export interface AcquiredTransport {
+    readonly transport: Transport;
+    readonly decision: TransportDecision;
+}
+/** Facts injected for testability. */
+export interface TransportServiceOptions {
+    readonly selector: TransportSelector;
+    readonly factories: TransportFactories;
+    /** See {@link TransportPreflight}. Omitted means "no revision". */
+    readonly preflight?: TransportPreflight;
+}
+/** Owns one transport instance per connection. */
+export declare class TransportService {
+    #private;
+    constructor(options: TransportServiceOptions);
+    /**
+     * Get a connected transport for a profile, creating it if needed.
+     *
+     * @param profile - the connection to serve.
+     * @param signal - cancellation for the connect attempt.
+     * @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;
+    /** Decisions currently in force, for the connection status UI. */
+    decisions(): readonly TransportDecision[];
+    /** Dispose and forget one connection. */
+    release(connectionId: string): Promise<void>;
+    /** Dispose every connection (plugin unload, connection-service shutdown). */
+    disposeAll(): Promise<void>;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * Remote capability probing.
+ *
+ * The plugin installs nothing on the remote host, so it must discover what the host already
+ * offers and degrade accordingly: `git ls-files` when git exists, a bounded `find` otherwise;
+ * `rg` when available, bounded `grep` otherwise.
+ *
+ * @module dsh-over-ssh/domain/capability
+ */
+/** What one probe learned about the remote host. */
+export interface RemoteCapabilities {
+    /** `uname -s` output, or `unknown`. */
+    readonly uname: string;
+    /** Whether the host is a POSIX shell host this plugin supports. */
+    readonly posix: boolean;
+    readonly git: boolean;
+    readonly ripgrep: boolean;
+    readonly grep: boolean;
+    readonly base64: boolean;
+    readonly findMaxDepth: boolean;
+    readonly sha256: 'sha256sum' | 'shasum' | null;
+    readonly statFlavor: 'gnu' | 'bsd' | 'unknown';
+    /**
+     * Language servers found on the remote `PATH`.
+     *
+     * `undefined` means **nobody looked** (Tier 1 shell transport, or an agent older than the probe);
+     * an empty array means the probe ran and found none. The difference matters: the first case must not be
+     * reported to a caller as "not installed", because we have no evidence either way.
+     */
+    readonly lspServers?: readonly LspServerInfo[];
+}
+/** One language server found on the remote `PATH`. */
+export interface LspServerInfo {
+    readonly command: string;
+    readonly language: string;
+    readonly path: string;
+}
+/**
+ * The one-shot probe script.
+ *
+ * Every line is `key=value`; values never contain newlines. The script is written for `sh`
+ * and tolerates missing commands, because discovering a missing command is the point.
+ *
+ * @returns a POSIX shell script.
+ */
+export declare function probeScript(): string;
+/** The capabilities assumed when probing failed: POSIX basics only. */
+export declare function conservativeCapabilities(): RemoteCapabilities;
+/**
+ * Parse probe output into capabilities.
+ *
+ * Unknown keys are ignored so the script can grow without breaking older parsers.
+ *
+ * @param stdout - the probe's standard output.
+ * @returns parsed capabilities.
+ */
+export declare function parseProbeOutput(stdout: string): RemoteCapabilities;
+/** How the plugin will search file contents on a host. */
+export type SearchStrategy = {
+    readonly kind: 'git-grep';
+} | {
+    readonly kind: 'ripgrep';
+} | {
+    readonly kind: 'grep-bounded';
+};
+/** How the plugin will enumerate files for `@` completion on a host. */
+export type IndexStrategy = {
+    readonly kind: 'git-ls-files';
+} | {
+    readonly kind: 'find-bounded';
+};
+/** Pick the content-search strategy for a host. */
+export declare function searchStrategyFor(capabilities: RemoteCapabilities): SearchStrategy;
+/** Pick the file-enumeration strategy for a host. */
+export declare function indexStrategyFor(capabilities: RemoteCapabilities): IndexStrategy;
+/** Whether the host can run the plugin's file-transfer path. */
+export declare function canTransferBytes(capabilities: RemoteCapabilities): boolean;

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

@@ -0,0 +1,54 @@
+/**
+ * Domain errors and SSH failure diagnostics.
+ *
+ * Failure classification satisfies the requirement that a failed connection must name
+ * an actionable cause (missing key vs rejected key vs unreachable host vs changed host key)
+ * instead of a generic "connection failed".
+ *
+ * @module dsh-over-ssh/domain/errors
+ */
+/** Stable error codes crossing the plugin's internal and remote boundaries. */
+export declare const SSH_DEV_ERROR_CODES: readonly ["CONNECTION_INVALID", "CONNECTION_NOT_FOUND", "CONNECTION_LOST", "CONNECTION_UNREACHABLE", "AUTH_FAILED", "HOST_KEY_CHANGED", "ROOT_INVALID", "ROOT_AMBIGUOUS", "ROOT_OUTSIDE", "REMOTE_NOT_FOUND", "REMOTE_UNSUPPORTED", "REMOTE_COMMAND_FAILED", "SANDBOX_DENIED", "TRANSFER_CONFLICT", "TRASH_NOT_FOUND", "SESSION_ACTIVE", "CANCELLED"];
+/** One stable plugin error code. */
+export type SshDevErrorCode = (typeof SSH_DEV_ERROR_CODES)[number];
+/** A plugin-owned failure that carries a stable code and structured details. */
+export declare class SshDevError extends Error {
+    readonly code: SshDevErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: SshDevErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+/** Test whether a value is a plugin-owned failure. */
+export declare function isSshDevError(value: unknown): value is SshDevError;
+/** Actionable classification of one local `ssh` failure. */
+export type SshFailureKind = 'auth-failed' | 'key-missing' | 'key-permissions' | 'agent-unavailable' | 'host-unreachable' | 'dns-failed' | 'host-key-changed' | 'host-key-unknown' | 'timeout' | 'remote-command-missing' | 'connection-lost' | 'unknown';
+/** A classified failure plus the next action a user can take. */
+export interface SshDiagnostic {
+    readonly kind: SshFailureKind;
+    readonly hint: string;
+}
+/** Classify one local `ssh` attempt from its exit status, stderr and signal. */
+export declare function classifySshFailure(input: {
+    readonly exitCode?: number | undefined;
+    readonly stderr?: string | undefined;
+    readonly signal?: string | null | undefined;
+}): SshDiagnostic;
+/**
+ * Build the plugin failure for one unclassified-or-classified ssh failure.
+ *
+ * The classification is what decides the **code**, and the two host-key kinds have codes of their own. Mapping
+ * them onto `CONNECTION_LOST` (the old fallback) told the user "the connection dropped, reconnect" for a
+ * condition where reconnecting is exactly what must not happen silently — a changed host key is the one
+ * failure whose whole point is to stop and be looked at. `HOST_KEY_CHANGED` was declared in
+ * {@link SSH_DEV_ERROR_CODES} and never thrown anywhere until this mapping existed (audit 0043).
+ *
+ * @param connectionId - the connection the attempt belonged to.
+ * @param input - exit status, stderr and signal of the failed attempt.
+ * @returns the error to surface.
+ */
+export declare function sshFailureToError(connectionId: string, input: {
+    readonly exitCode?: number | undefined;
+    readonly stderr?: string | undefined;
+    readonly signal?: string | null | undefined;
+}): SshDevError;
+/** Keep only the tail of a long diagnostic string so details stay bounded. */
+export declare function tail(text: string, maxChars: number): string;

package/lib/types/src/host/domain/roots/connection.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Connection profiles and their validation.
+ *
+ * A profile never carries secret material: a password is referenced by credential key and
+ * resolved from `ctx.credentials` per operation.
+ *
+ * @module dsh-over-ssh/domain/connection
+ */
+import type { SshConfigImportDraft } from './ssh-config.ts';
+/** How the transport reaches the host. `agent` is the opt-in Tier 2 proxy (launched over the system ssh). */
+export type TransportKind = 'alias' | 'ssh2' | 'agent';
+/** Host key verification policy. */
+export type HostKeyPolicy = 'strict' | 'accept-new';
+/** Authentication method. */
+export type AuthSpec = {
+    readonly kind: 'agent';
+} | {
+    readonly kind: 'key';
+    readonly keyPath: string;
+    readonly hasPassphrase: boolean;
+} | {
+    readonly kind: 'password';
+    readonly credentialKey: string;
+};
+/** One saved connection. */
+export interface ConnectionProfile {
+    /** Stable slug used inside `ssh://` paths and as the pool key. */
+    readonly id: string;
+    /** Human-facing name. */
+    readonly name: string;
+    /** Transport implementation. */
+    readonly transport: TransportKind;
+    /** Host name used by the ssh2 transport, and by alias transport only for diagnostics. */
+    readonly host: string;
+    readonly port: number;
+    readonly user: string;
+    /** OpenSSH alias; required by the alias transport. */
+    readonly alias?: string;
+    readonly auth: AuthSpec;
+    /** ProxyJump chain, applied through `-J` (ssh2) or the alias (config). */
+    readonly proxyJump: readonly string[];
+    readonly hostKeyPolicy: HostKeyPolicy;
+    /** Remote directory used as the default root when creating a remote workspace. */
+    readonly remoteDefaultRoot?: string;
+    readonly connectTimeoutMs: number;
+    readonly commandTimeoutMs: number;
+    readonly keepAliveSeconds: number;
+}
+/** Defaults for a new connection. */
+export declare const CONNECTION_DEFAULTS: {
+    readonly port: 22;
+    readonly connectTimeoutMs: 15000;
+    readonly commandTimeoutMs: 30000;
+    readonly keepAliveSeconds: 60;
+};
+/** Whether a string can name a value in the credential store. */
+export declare function isValidCredentialRef(value: string): boolean;
+/**
+ * 一个凭据引用名**可能落在哪几个名字上**，按优先顺序。
+ *
+ * `credentialKey` 会落盘进 `user-roots.json`，所以老连接的引用名仍是 `DSH_SSH_…`，直接用就行。回退是
+ * 为了那些**没落盘**的早期记录：它们的引用名是运行时按 id 现推的，改名后会推出新前缀，不回退就取不到
+ * 已存的密码。反过来，新名字在前，所以迁移过的连接不会去读旧位置。
+ *
+ * @param key - 当前的引用名。
+ * @returns 一个或两个候选名字；不是本插件派生的名字时只有一个（原样）。
+ */
+export declare function credentialRefCandidates(key: string): readonly string[];
+/**
+ * Derive the credential-reference name that holds one connection's password.
+ *
+ * The platform names stored values with a POSIX identifier, so a user-chosen name — `腾讯云` included —
+ * cannot be used verbatim. The derivation keeps whatever ASCII is readable and then appends a 64-bit digest
+ * of the **exact** id: readable enough to find in the credentials file, and collision-free between two names
+ * that sanitise to the same slug (`a b` and `a_b`). It is a pure function of the id, so re-adding the same
+ * name reuses one stored secret instead of accumulating orphans.
+ *
+ * @param connectionId - the user's connection name.
+ * @returns a name satisfying {@link isValidCredentialRef}.
+ */
+export declare function credentialRefFor(connectionId: string): string;
+/**
+ * Validate untrusted input into a connection profile.
+ *
+ * Misconfiguration fails loudly at this boundary, so the rest of the plugin can treat a
+ * `ConnectionProfile` as trustworthy.
+ *
+ * @param input - candidate value (settings JSON, import draft or test fixture).
+ * @returns the validated profile.
+ * @throws SshDevError with code `CONNECTION_INVALID`.
+ */
+export declare function validateConnectionProfile(input: unknown): ConnectionProfile;
+/**
+ * Turn one importable `~/.ssh/config` alias into a profile.
+ *
+ * The alias transport inherits user/port/identity/proxy settings from the alias itself, so
+ * the draft's explicit values are kept only for display and for the ssh2 fallback.
+ *
+ * @param id - connection id assigned by the caller (keeps this function deterministic).
+ * @param draft - one draft from {@link importableEntries}.
+ * @returns the validated profile.
+ */
+export declare function profileFromImportDraft(id: string, draft: SshConfigImportDraft): ConnectionProfile;
+/** One-line summary used by diagnostics and the settings list. */
+export declare function connectionSummary(profile: ConnectionProfile): string;

package/lib/types/src/host/domain/roots/root.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Root references: one project root is either a local directory or a remote directory on
+ * one connection. Remote roots additionally carry a local *anchor* directory, because DSH
+ * requires a workspace path that exists on the host filesystem.
+ *
+ * @module dsh-over-ssh/domain/root
+ */
+import { isAbsoluteLocalPath, type RootKeyOptions, type RootLocation } from '../../../shared/root-keys.ts';
+/** Where a root lives. The definition lives in `shared/root-keys.ts`, beside the key rule that needs it. */
+export type { RootLocation };
+/** One project root. */
+export interface RootRef {
+    /** Local or remote. */
+    readonly location: RootLocation;
+    /** Connection id; present exactly for remote roots. */
+    readonly connectionId?: string;
+    /** Absolute local path, or absolute POSIX path for a remote root. */
+    readonly path: string;
+    /** Whether the sandbox fence admits writes under this root. */
+    readonly writable: boolean;
+    /** Local anchor directory for a remote root (empty directory, never mirrored content). */
+    readonly anchorPath?: string;
+    /** Display label; defaults to the final path segment. */
+    readonly label?: string;
+    /**
+     * The workspaces (session cwd paths) that added this root.
+     *
+     * **Absent means "no session added it"**, which under session isolation means "no session may use it"
+     * ({@link rootVisibleToSession} in `./session-roots.ts`). It is not a default-allow: the user-roots file has
+     * carried this field since the 「添加目录」 grouping landed, and the settings panel writes unscoped roots on
+     * purpose (its form has no scope field).
+     */
+    readonly workspaces?: readonly string[];
+    /**
+     * The **sessions** (conversation ids) that added this root — the strict identity behind {@link workspaces}.
+     *
+     * `workspaces` answers "which workspace added it", which cannot separate two conversations opened on the
+     * same directory; this field can. When it is present **and** the caller carries a session id, the route
+     * table decides by session and never consults the cwd (ADR-0013, `domain/roots/session-roots.ts`). Absent
+     * means "written before ADR-0013" — such a root keeps the workspace-level rule, so existing data does not
+     * lose access on upgrade.
+     */
+    readonly sessions?: readonly string[];
+    /**
+     * Whether this root is **deployment-wide** rather than a session artifact.
+     *
+     * True for roots declared in the plugin's `config.roots`: they are infrastructure the deployment declares once
+     * (the stage-2 requirement "a local root covering the current workspace" is one of them), so every session may
+     * use them. False/absent for roots the user added through the panel or 「添加目录」 — those are per-session and
+     * are gated by {@link workspaces} (see `rootVisibleToSession`).
+     */
+    readonly shared?: boolean;
+}
+/** Options shared by both root kinds. */
+export interface RootOptions {
+    /** Whether writes under this root are allowed; defaults to true. */
+    readonly writable?: boolean;
+    /** Display label override. */
+    readonly label?: string;
+    /** Workspaces that added this root; see {@link RootRef.workspaces}. */
+    readonly workspaces?: readonly string[];
+    /** Sessions that added this root; see {@link RootRef.sessions}. */
+    readonly sessions?: readonly string[];
+    /** Deployment-wide root; see {@link RootRef.shared}. */
+    readonly shared?: boolean;
+}
+/** Create a remote root, validating the connection id and remote path. */
+export declare function makeRemoteRoot(connectionId: string, remotePath: string, options?: RootOptions & {
+    readonly anchorPath?: string;
+}): RootRef;
+/**
+ * Create a local root from an absolute host path.
+ *
+ * The stored path **preserves the caller's case** (only separators, `.`/`..` and the drive letter
+ * are canonicalised). Case folding belongs to comparison and keying — `rootKey` folds, and
+ * `localPathContains` folds on request — because the root's path is also what the UI shows and what
+ * a child process receives via `processPath`.
+ */
+export declare function makeLocalRoot(path: string, options?: RootOptions): RootRef;
+/**
+ * Whether a host path is absolute in either the Windows or the POSIX spelling.
+ *
+ * **Re-exported, not re-implemented.** The rule lives in `shared/root-keys.ts` because the client panel has to
+ * answer the same question before it sends a request — and the two answers had drifted: this file rejected
+ * `\\server\share` while the panel accepted it (审计 0112 P2-11). Both UNC spellings are accepted now, which is
+ * what this function always claimed in its one-line doc.
+ */
+export { isAbsoluteLocalPath };
+/**
+ * Normalize a host path for comparison: separators to `/`, `.`/`..` resolved, trailing
+ * separators dropped, and (optionally) the drive letter and case folded.
+ *
+ * The **implementation** is `shared/root-keys.ts` (the client's key needs the same normalisation). What stays
+ * here is the platform default: `caseInsensitive` defaults to "this host folds case on Windows", which is a
+ * fact only the host has — a browser bundle has no `process` and must not guess it.
+ *
+ * @param path - host path in either separator spelling.
+ * @param options - `caseInsensitive` folds case for comparison keys.
+ * @returns the normalized path.
+ */
+export declare function normalizeLocalPath(path: string, options?: RootKeyOptions): string;
+/** Whether a host path is `root` itself or a descendant of it. */
+export declare function localPathContains(root: string, candidate: string, options?: {
+    readonly caseInsensitive?: boolean;
+}): boolean;
+/**
+ * Stable identity of a root, used as a cache/route key.
+ *
+ * The **spelling** is `shared/root-keys.ts`'s `rootKeySpelling`: the client rebuilds this same key for a row
+ * whose answer carried none, and a second spelling is what made the panel's delete button address a root the
+ * registry did not have (审计 0024 §8.3). Only the error policy and the platform's case fold stay here.
+ */
+export declare function rootKey(root: RootRef): string;
+/** The model-facing and UI-facing spelling of a root's directory. */
+export declare function rootDisplay(root: RootRef): string;
+/** The display label of a root: explicit label, else the final path segment. */
+export declare function rootLabel(root: RootRef): string;
+/** Whether two roots of the same location overlap (one contains the other). */
+export declare function rootsOverlap(left: RootRef, right: RootRef): boolean;
+/** Validate a root reference produced outside this module. */
+export declare function validateRoot(root: RootRef): void;
+/** FNV-1a (32-bit) over UTF-16 code units, rendered as 8 lowercase hex characters. */
+export declare function fnv1aHex(input: string): string;

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

@@ -0,0 +1,150 @@
+/**
+ * Session-scoped remote roots: which remote directories **this** conversation may target.
+ *
+ * The problem this solves. 「添加目录」 registers a directory for one session (the entry's `workspaces` list
+ * holds that session's workspace path), and until now that was a **visibility** rule only: the client card
+ * listed the directory, but every `remote_*` tool picked its root from the agent's session cwd alone
+ * (`remote-tools.ts` `targetFor`). A session opened on a local folder — `D:\project\x` — therefore could add
+ * `165服务器:/home1/me/work/android14`, see it in the card, and still get
+ * `工作目录不在任何远端根内：D:\project\x` from every remote tool. The user's own words:
+ * 「我一个本地目录的会话，我添加远程的路径，这个会话也能正常访问远程路径」.
+ *
+ * The rule implemented here is the narrow one that makes that work without turning 「添加目录」 into a
+ * process-wide switch:
+ *
+ *  1. A cwd that resolves to a remote root **wins** (the pre-existing behaviour, unchanged). A session living
+ *     on a remote workspace keeps targeting it, and nothing about `ssh://` resolution changes.
+ *  2. Otherwise, the roots **this session added** are candidates. Exactly one candidate is used; zero is the
+ *     old `ROOT_OUTSIDE` error; two or more is refused by name instead of guessed — the same stance the
+ *     route table already takes for two remote roots with the same spelling (`ROOT_AMBIGUOUS`).
+ *
+ * Why "scoped to this session" was read from the **workspace path** rather than from a session id: that is
+ * what `add-root` wrote (`session-directory.ts` passes `workspaces: [state.workspacePath]`), and it was the
+ * only field the persisted file carried. **ADR-0013 changes that**: the platform does not hand a session id to
+ * `ctx.fs`, but it does hand one to every tool execution, and `integration/session-scope.ts` carries it down.
+ * Entries now also record `sessions`, and when both the root and the caller have one, **the session decides**
+ * and the workspace path is not consulted. A fork inherits its ancestors' entries ({@link SessionIdentity}).
+ * Entries written before ADR-0013 carry no `sessions` and keep the workspace-level rule unchanged.
+ *
+ * Pure: no filesystem, no transport, no platform types — the caller injects the entries. That is what makes
+ * the rule testable offline (红线 2/3).
+ *
+ * @module dsh-over-ssh/domain/roots/session-roots
+ */
+import { type RootRef } from './root.ts';
+/** One persisted root entry, as far as this module needs to read it. */
+export interface SessionRootEntry {
+    readonly location: 'local' | 'remote';
+    readonly path: string;
+    readonly connectionId?: string;
+    /** The workspaces (session cwd paths) that added this root. Absent means "no session added it". */
+    readonly workspaces?: readonly string[];
+    /** The **sessions** (conversation ids) that added this root. Absent on entries written before ADR-0013. */
+    readonly sessions?: readonly string[];
+}
+/**
+ * Who is asking: the cwd every caller already carries, plus the session identity when one is available.
+ *
+ * `sessionId` is the strict identity — two conversations in the same workspace differ here and nowhere else.
+ * `ancestors` are that session's fork lineage, nearest first: a fork inherits the directories its parent added
+ * (the product decision recorded in ADR-0013), so a root listed for any ancestor is listed for the fork too.
+ * Both are optional because an agentless call (a CLI, a config replay) has neither.
+ */
+export interface SessionIdentity {
+    /** The asking session's id, when one is known. */
+    readonly sessionId?: string | undefined;
+    /** The asking session's fork ancestors, nearest first. */
+    readonly ancestors?: readonly string[] | undefined;
+}
+/** The target shape the tools consume; kept structural so this module imports no integration code. */
+export interface SessionRootTarget {
+    readonly connectionId: string;
+    readonly root: string;
+}
+/** Outcome of {@link resolveSessionRemoteRoot}. */
+export type SessionRootOutcome = {
+    readonly ok: true;
+    readonly target: SessionRootTarget;
+}
+/** Nothing this session added is a remote root: the caller keeps its own error. */
+ | {
+    readonly ok: false;
+    readonly reason: 'none';
+}
+/** Several added remote roots: refused by name rather than guessed. */
+ | {
+    readonly ok: false;
+    readonly reason: 'ambiguous';
+    readonly candidates: readonly SessionRootTarget[];
+};
+/**
+ * Compare two host paths the way the persisted `workspaces` field is written.
+ *
+ * Windows paths are case-insensitive, and the file stores whatever the platform reported at add time while
+ * the session header may spell the same directory with different case. Folding here is what keeps a
+ * `D:\Project\X` session from losing the directory it added as `d:\project\x`.
+ *
+ * @param left - one host path.
+ * @param right - the other host path.
+ * @returns whether they name the same directory.
+ */
+export declare function sameWorkspacePath(left: string, right: string): boolean;
+/**
+ * The remote roots one session added, in file order.
+ *
+ * @param entries - the persisted root entries.
+ * @param workspacePath - the session's workspace path (its cwd), or `undefined` when the platform gave none.
+ * @param identity - the session identity, when the platform could supply one (ADR-0013).
+ * @returns the added remote roots, each with its connection and absolute remote path.
+ */
+export declare function remoteRootsAddedBy(entries: readonly SessionRootEntry[], workspacePath: string | undefined, identity?: SessionIdentity): readonly SessionRootTarget[];
+/**
+ * Pick the remote root a session should target when its cwd names none.
+ *
+ * @param entries - the persisted root entries.
+ * @param workspacePath - the session's workspace path (its cwd).
+ * @param identity - the session identity, when the platform could supply one (ADR-0013).
+ * @returns the single added remote root, a refusal, or `none` when the session added no remote directory.
+ */
+export declare function resolveSessionRemoteRoot(entries: readonly SessionRootEntry[], workspacePath: string | undefined, identity?: SessionIdentity): SessionRootOutcome;
+/**
+ * The model-facing text for a session that added more than one remote directory.
+ *
+ * @param candidates - the added remote roots.
+ * @returns one sentence naming every candidate and the way to disambiguate.
+ */
+export declare function ambiguousSessionRootMessage(candidates: readonly SessionRootTarget[]): string;
+/**
+ * Whether one root may serve one session — the **access** rule, not the view rule.
+ *
+ * 「添加目录」 scopes a root to the workspace that added it (`workspaces`). Until now that was a visibility fact
+ * only: the panel listed the session's own roots while the router answered **any** registered root for **any**
+ * caller (`routed-fs.ts`: "Filtering is a view fact, not a sandbox"). With the routed filesystem mounted
+ * (`远程工作区-路由fs`, stage 2) that gap is an access gap — session B could read a directory only session A
+ * added, merely by spelling its path. This predicate closes it, and it is the one place the rule lives: the route
+ * table calls it for every resolution, so every file tool inherits it.
+ *
+ * **Two identities, in this order (ADR-0013).** When the root carries `sessions` **and** the caller has a
+ * session id, the session decides — the workspace path is not consulted. That is what separates two
+ * conversations opened on the same directory: they share a cwd and differ only here. Otherwise (an entry from
+ * before ADR-0013, or an agentless call) the workspace path stands in, and the root belongs to a session in
+ * exactly two ways:
+ *
+ *  1. it was **added to this workspace** — `workspaces` names the session's cwd ({@link sameWorkspacePath});
+ *  2. the session **lives on** the root — a remote root's anchor directory *is* a workspace path, so a session
+ *     opened on that anchor (or inside it) is that workspace's session. This keeps a remote workspace usable
+ *     when its root was registered before the `workspaces` grouping existed.
+ *
+ * Everything else is refused, **including a root with no `workspaces` at all**: the settings panel's unscoped
+ * roots are "added to no session" (its own copy says so), so a session has to opt in with 「添加目录」 first.
+ * That is a deliberate behaviour change — see ADR-0012 for the migration note.
+ *
+ * A caller with neither cwd nor session is not a session call — agentless config replay, a CLI — and keeps the
+ * plugin-wide view; widening a *session* silently would be the bug this function exists to stop.
+ *
+ * @param root - one registered root.
+ * @param cwd - the asking session's cwd, or `undefined` for an agentless call.
+ * @param identity - the asking session's identity, when the platform could supply one (ADR-0013).
+ * @returns whether the root may serve that caller.
+ */
+export declare function rootVisibleToSession(root: RootRef, cwd: string | undefined, identity?: SessionIdentity): boolean;

package/lib/types/src/host/domain/roots/ssh-config.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `~/.ssh/config` reader used by the "import aliases" flow.
+ *
+ * Only the keys this plugin can represent are read. OpenSSH keeps the first obtained value
+ * for a key inside one Host block, so this parser does the same; `Host` blocks accumulate
+ * their patterns and later blocks shadow earlier ones for the same literal alias.
+ *
+ * @module dsh-over-ssh/domain/ssh-config
+ */
+/** One parsed `Host` block. */
+export interface SshConfigEntry {
+    /** Patterns on the `Host` line, in order. */
+    readonly patterns: readonly string[];
+    /** `HostName` value when present. */
+    readonly hostName?: string;
+    /** `User` value when present. */
+    readonly user?: string;
+    /** `Port` value when present and numeric. */
+    readonly port?: number;
+    /** All `IdentityFile` values, in order. */
+    readonly identityFiles: readonly string[];
+    /** `ProxyJump` value when present and not `none`. */
+    readonly proxyJump?: string;
+    /** `Include` patterns (this parser does not read included files). */
+    readonly includes: readonly string[];
+    /** 1-based line number of the `Host` line. */
+    readonly line: number;
+}
+/** A connection the import flow can turn into a profile. */
+export interface SshConfigImportDraft {
+    /** The literal alias, also usable as the `ssh` target. */
+    readonly alias: string;
+    /** Resolved host name (falls back to the alias). */
+    readonly hostName: string;
+    readonly user?: string;
+    readonly port?: number;
+    readonly identityFile?: string;
+    readonly proxyJump?: string;
+}
+/** One alias the import flow refuses, with the reason shown to the user. */
+export interface SkippedAlias {
+    readonly pattern: string;
+    readonly reason: string;
+    readonly line: number;
+}
+/** Result of selecting importable aliases. */
+export interface SshConfigImportResult {
+    readonly drafts: readonly SshConfigImportDraft[];
+    readonly skipped: readonly SkippedAlias[];
+}
+/**
+ * Parse the textual content of an OpenSSH client config.
+ *
+ * @param text - file content.
+ * @returns parsed Host blocks in file order.
+ */
+export declare function parseSshConfig(text: string): SshConfigEntry[];
+/** Whether a Host pattern names one concrete host rather than a wildcard set. */
+export declare function isConcretePattern(pattern: string): boolean;
+/** Expand a leading `~` using the host home directory. */
+export declare function expandHome(path: string, home: string): string;
+/**
+ * Select the aliases the import flow will offer, and explain what it refuses.
+ *
+ * @param entries - parsed Host blocks.
+ * @param options - `home` expands `~` in identity paths; `excluded` drops known aliases.
+ * @returns importable drafts plus skipped patterns.
+ */
+export declare function importableEntries(entries: readonly SshConfigEntry[], options?: {
+    readonly home?: string;
+    readonly excluded?: readonly string[];
+}): SshConfigImportResult;