dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/app/takeover/takeover-plan.d.ts

@@ -0,0 +1,227 @@
+/**
+ * 阶段 2「一键接管」的**纯模型**：四行的开关 → 组合状态 / 操作序列 / 运行态核对 / 手动改法。
+ *
+ * 本模块没有 I/O、不 import 任何 `@deepseek-ai/*`（AGENTS.md 红线 2），输入只是一张
+ * `patchId → {enabled, readOnlyReason, fiberPhase}` 表，输出是纯数据。执行器在
+ * `src/host/integration/takeover/takeover-service.ts`。
+ *
+ * ## 身份：`patchId` 才是本插件认识的那一行
+ *
+ * 宿主把两套 id 混在同一个行对象里，**不能互相顶替**（`plugin-manager/src/index.ts:256-272`）：
+ *
+ * | 字段 | 含义 | 真机上的例子 |
+ * |---|---|---|
+ * | `entryId` | **Loader 条目身份**。挂在 `include` 下的条目带前缀 | `include:fs-sandbox` |
+ * | `patchId` | profile patch 里的**行 id**，即 `actual.options.id`（`index.ts:261,270`） | `fs-sandbox` |
+ * | `moduleName` | 该条目 import 的模块说明符（`entry.options.name`） | `@deepseek-ai/dsh-fs-sandbox` |
+ *
+ * 用户在自己的 `cordis.patch.yml` 里看到、也需要改的是 **patchId**；`setPluginEnabled` 收的却是
+ * **entryId**（宿主自己再去查 `patchId`）。所以：
+ *
+ *  - 本模块的常量、步骤、UI 一律用 **patchId**（`TAKEOVER_PATCH_IDS`）；
+ *  - 真实 `entryId` 只作为诊断信息随行保存（`TakeoverRow.entryId`），**从不**用来判断身份 ——
+ *    拿它跟 `fs-sandbox` 这种常量比，在真机上永远匹配不上（真值是 `include:fs-sandbox`）。
+ *
+ * ## 为什么顺序要单独建模
+ *
+ * `ctx.fs` / `ctx.fileReferences` 都是单例服务，两个提供方同时在场时后来者注册会抛
+ * `service "fs" has been registered at …`（`doc/02-platform/fs-seam.md` §1）；而本插件的 `./fs`
+ * 条目在核心行仍占用时会 warn 后 `return undefined`（`src/fs.ts:55-62`），并且**不会自己重试**。
+ * 所以 apply 的顺序是正确性的一部分：
+ *
+ *   1. 先 enable 我们的两条 —— 核心仍占用时会被跳过（无害）；
+ *   2. 再 disable 两条核心 —— 让出两个服务；
+ *   3. 最后把我们的两条各做一次 disable + enable —— 强制在核心让位后重新 apply。
+ *
+ * revert 反向：先 disable 我们的两条，再 enable 两条核心。
+ *
+ * ## 三件它不假装的事
+ *
+ * 1. **`enabled` 是配置值，不是运行态。** 宿主 `PluginInfo.enabled` = `!entry.disabled`
+ *    （`packages/host/plugin-inventory/src/index.ts:89-95`），只有 `fiberPhase` 才说明「提供方真的在跑」。
+ *    两者不一致时 {@link liveMismatch} 会说出来，而不是让面板显示一个漂亮的谎。
+ * 2. **只读行只挡它真正要碰的行**：`readOnlyReason` 非空的行不能通过 profile patch 改，必须在动第一行
+ *    之前拒绝；但**已经满足的请求**（空序列）不算「要碰」。
+ * 3. **幂等**：已处于目标态时步骤序列为空，执行器因此不会为了「确认一下」去写 profile patch。
+ *
+ * @module dsh-remote-workspace/app/takeover-plan
+ */
+/** 我们自己的两行（`cordis.patch.yml` 里的 `remote-workspace-fs` 与 `remote-workspace-file-references`）。 */
+export declare const OUR_PATCH_IDS: readonly ["remote-workspace-fs", "remote-workspace-file-references"];
+/** 核心的两行（bundle patch 里的 `fs-sandbox` 与 `file-reference-local`）。 */
+export declare const CORE_PATCH_IDS: readonly ["fs-sandbox", "file-reference-local"];
+/** 接管涉及的全部四行，顺序固定：先我们的、后核心的（与 apply 的叙述顺序一致）。 */
+export declare const TAKEOVER_PATCH_IDS: readonly ["remote-workspace-fs", "remote-workspace-file-references", "fs-sandbox", "file-reference-local"];
+/** 一行属于哪一边。 */
+export type TakeoverSide = 'ours' | 'core';
+/** 宿主 `PluginInfo.fiberPhase` 的取值（`plugin-inventory/src/types.ts:8-14`）；`null` = 没有活着的根 fiber。 */
+export type TakeoverFiberPhase = 'pending' | 'loading' | 'active' | 'failed' | 'unloading' | null;
+/** 四行之一在宿主 `listPlugins()` 里的最小投影。 */
+export interface TakeoverRow {
+    /** **规范身份**：profile patch 里的行 id。内部判断与 UI 都用它。 */
+    readonly patchId: string;
+    /** Loader 条目的真实 id（如 `include:fs-sandbox`）。只作诊断，**不参与身份判断**。 */
+    readonly entryId?: string | undefined;
+    /** 该条目 import 的模块说明符，身份交叉校验用。 */
+    readonly moduleName?: string | undefined;
+    /** 该行当前是否启用：`PluginInfo.enabled`，即**配置/组合**的开关，不是「fiber 正在跑」。 */
+    readonly enabled: boolean;
+    /**
+     * 非空表示这一行**不能**通过 profile patch 修改（`'management-required'` | `'unaddressable'`）。
+     * 原样透传，不做枚举校验：宿主将来多一种原因时，这里要如实报告而不是把它当「没有原因」。
+     */
+    readonly readOnlyReason?: string | undefined;
+    /** 该行根 fiber 的运行状态；`undefined` = 宿主没给这个字段（无法判断）。 */
+    readonly fiberPhase?: TakeoverFiberPhase | undefined;
+}
+/** 四行组合起来的接管状态。 */
+export type TakeoverState = 
+/** 核心两行在、我们的两行不在：阶段 1（本插件没有接管）。 */
+'off'
+/** 我们的两行在、核心两行不在：阶段 2（本插件已接管）。 */
+ | 'on'
+/** 其它组合（含两方同时在场、只有一行切换）。 */
+ | 'mixed'
+/** 这台宿主上无法表达接管：没有 `pluginManager`，或插件清单里缺行。 */
+ | 'unsupported';
+/** 一键接管的两个方向。 */
+export type TakeoverAction = 'apply' | 'revert';
+/** 一步为什么存在。 */
+export type TakeoverStepWhy = 
+/** apply 的第 1 段：预置我们自己的行。核心仍占用时这一步会被跳过，**按设计无害**。 */
+'enable-ours'
+/** apply 的第 2 段：让核心的两行让位。 */
+ | 'disable-core'
+/** apply 的第 3 段：把我们自己的行各做一次 disable + enable，强制重新 apply。 */
+ | 'reapply-ours'
+/** revert 的第 1 段：先撤掉我们自己的两行。 */
+ | 'disable-ours'
+/** revert 的第 2 段：再把核心的两行恢复回来。 */
+ | 'enable-core';
+/** 一条**原始**操作：对某一行调用一次 `setPluginEnabled`。 */
+export interface TakeoverStep {
+    /** 规范身份（patchId）。真正写盘时宿主还要用它自己的 `entryId` 换算，那是执行器的事。 */
+    readonly patchId: string;
+    /** 目标值：`true` = 启用，`false` = 禁用。 */
+    readonly enabled: boolean;
+    readonly why: TakeoverStepWhy;
+}
+/** 整次操作被拒绝的原因（在**动第一行之前**就判定，不留半成品）。 */
+export type TakeoverRefusal = 
+/** 计划要碰的行里有 `readOnlyReason` 非空的。 */
+'read-only'
+/** 插件清单里找不到四行中的某一行（或身份有歧义，按缺行处理）。 */
+ | 'rows-missing';
+/** 规划结果：要么一串步骤，要么一个拒绝（附原因与涉及的行）。 */
+export type TakeoverPlan = {
+    readonly ok: true;
+    readonly action: TakeoverAction;
+    readonly steps: readonly TakeoverStep[];
+} | {
+    readonly ok: false;
+    readonly refusal: TakeoverRefusal;
+    /** 造成拒绝的行（patchId）。 */
+    readonly patchIds: readonly string[];
+    /** 面向用户的说明，直接可进 HTTP 的 `error` 字段。 */
+    readonly message: string;
+};
+/**
+ * 一行属于哪一边。
+ *
+ * @param patchId - profile patch 行 id。
+ * @returns `'ours'` / `'core'`，不认识的行返回 `undefined`。
+ */
+export declare function sideOf(patchId: string): TakeoverSide | undefined;
+/**
+ * 插件清单里缺了哪几行（按 {@link TAKEOVER_PATCH_IDS} 的顺序）。
+ *
+ * 「缺」也包括**身份有歧义**（两行都声称是 `fs-sandbox`）：识别层会把歧义行丢掉，
+ * 于是这里如实报缺 —— 宁可说「没有这一行」，也不猜哪一行是真的。
+ *
+ * @param rows - 已投影的四行（可能不全）。
+ * @returns 缺失的 `patchId` 列表；齐全时为空数组。
+ */
+export declare function missingPatchIds(rows: readonly TakeoverRow[]): readonly string[];
+/**
+ * 四行的当前组合属于哪种接管状态。
+ *
+ * @param rows - 已投影的四行（可能不全）。
+ * @returns {@link TakeoverState}；行不齐时是 `'unsupported'`（无法表达，而不是猜一个）。
+ */
+export declare function takeoverState(rows: readonly TakeoverRow[]): TakeoverState;
+/**
+ * 规划一次 apply / revert。
+ *
+ * 步骤只包含**真正会改变状态**的操作（幂等），并且严格按模块头注释的顺序排列：
+ *
+ * - apply：`enable-ours*` → `disable-core*` → (`reapply-ours` 的 disable+enable)*
+ *   —— 最后一段只在前面确实有动作时追加；已经 `on` 时整串为空。
+ * - revert：`disable-ours*` → `enable-core*`；已经 `off` 时整串为空。
+ *
+ * @param rows - 四行的当前状态（`listPlugins()` 的投影）。
+ * @param action - `'apply'` 或 `'revert'`。
+ * @returns 步骤序列，或一个拒绝。
+ */
+export declare function planTakeover(rows: readonly TakeoverRow[], action: TakeoverAction): TakeoverPlan;
+/**
+ * 每一行在这次操作里的目标值。
+ *
+ * @param action - `'apply'`（接管）或 `'revert'`（交还）。
+ * @returns `patchId → enabled` 的目标表。
+ */
+export declare function targetEnabled(action: TakeoverAction): ReadonlyMap<string, boolean>;
+/**
+ * 计划要碰的行里，哪些是只读的。
+ *
+ * 只读行不能被 profile patch 改，所以必须在**动第一行之前**拒绝；但只针对真的要改的行 —— 已经满足的
+ * 请求（空序列）不该因为某行只读而失败。
+ *
+ * @param present - 按 `patchId` 索引的四行。
+ * @param steps - 已排好的步骤。
+ * @returns 只读且被计划碰到的 `patchId`（按步骤首次出现顺序，去重）。
+ */
+export declare function readOnlyTouched(present: ReadonlyMap<string, TakeoverRow>, steps: readonly TakeoverStep[]): readonly string[];
+/**
+ * 面向用户的拒绝说明（HTTP `error` 字段直接用这一段）。
+ *
+ * @param refusal - 拒绝原因。
+ * @param patchIds - 涉及的行。
+ * @returns 一句话，说明「为什么不行、下一步怎么办」。
+ */
+export declare function refusalMessage(refusal: TakeoverRefusal, patchIds: readonly string[]): string;
+/** 一处「配置说这样、运行态不是这样」。 */
+export interface TakeoverLiveMismatch {
+    readonly patchId: string;
+    /** 组合状态要求它是什么：提供方该在跑，还是该没有 fiber。 */
+    readonly expected: 'active' | 'off';
+    /** 实际看到的 fiber 状态；`undefined` = 宿主没给这个字段（判断不了）。 */
+    readonly actual: TakeoverFiberPhase | undefined;
+}
+/**
+ * 配置状态与运行态不一致的行。
+ *
+ * `enabled` 是**配置**（`PluginInfo.enabled` = `!entry.disabled`），`fiberPhase` 才是**运行**。两者不一致
+ * 的典型场景：改完 profile patch 但没重启（或宿主没有 hmr）—— 面板若只看 `enabled`，会显示「已接管」
+ * 而实际提供方根本没在跑。
+ *
+ * 只对 `on` / `off` 两个自洽形态回答；`mixed` / `unsupported` 没有「应有的运行态」可言，返回空。
+ *
+ * @param rows - 四行（含 `fiberPhase`）。
+ * @returns 不一致的行；全部一致或状态不自洽时为空数组。
+ */
+export declare function liveMismatch(rows: readonly TakeoverRow[]): readonly TakeoverLiveMismatch[];
+/**
+ * 用户自己改 profile patch 时要写的行（YAML 片段，直接可粘贴）。
+ *
+ * 为什么需要它：宿主的写入口只接受「一行一个布尔值」，也没有批量/事务接口；本插件不替用户改文件
+ * （见 `takeover-service.ts` 模块头）。所以这张表就是拒绝时交还给用户的东西 —— 行 id 用的是
+ * **patchId**，正是他 `cordis.patch.yml` 里写的那一个。
+ *
+ * 只列出**需要改**的行：已经是目标值的行不出现（避免用户把无意义的覆盖写进自己的 patch）。
+ *
+ * @param rows - 四行的当前状态。
+ * @param action - `'apply'` 或 `'revert'`。
+ * @returns YAML 行；已经处于目标态时为空数组。
+ */
+export declare function manualPatchRows(rows: readonly TakeoverRow[], action: TakeoverAction): readonly string[];
+//# sourceMappingURL=takeover-plan.d.ts.map

package/lib/types/src/host/app/takeover/takeover-rows.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `pluginManager.listPlugins()` 的答案 → 本插件认识的四行。
+ *
+ * 这一层唯一的职责是**认身份**，而身份在真机上是个坑：宿主行同时带 `entryId`（Loader 条目 id，
+ * 挂在 `include` 下的条目带前缀，例如 `include:fs-sandbox`）与 `patchId`（profile patch 的行 id，
+ * 例如 `fs-sandbox`）。用户 `cordis.patch.yml` 里写的是后者，`setPluginEnabled` 收的却是前者。
+ * 拿 `entryId` 去跟常量比，在真机上**永远匹配不上** —— 那正是这一层要挡住的事。
+ *
+ * 识别规则（按顺序，全部 fail closed）：
+ *
+ *  1. **有 `patchId`**：必须是我们认识的四个之一，且 `moduleName` 与预期一致（防止别的插件复用了同一个
+ *     行 id）；两行声称同一个 `patchId` → 有歧义，两行都不要。
+ *  2. **没有 `patchId`**（宿主只在不可改的行上省略它）：只能靠 `moduleName` 认 —— 该模块名必须**恰好**
+ *     出现在一行上，出现两行或零行都不认。
+ *  3. 认不出来就是「缺行」，由上层报 `rows-missing` / `unsupported`，而不是猜一个。
+ *
+ * 纯逻辑、无 I/O（AGENTS.md 红线 2），因此可以离线逐字段断言。
+ *
+ * @module dsh-remote-workspace/app/takeover-rows
+ */
+import { type TakeoverRow } from './takeover-plan.ts';
+/**
+ * 每个 patch 行应该 import 的模块说明符。
+ *
+ * 出处：核心两行在 bundle patch 里声明（`packages/bundle/base/cordis.patch.yml:518-519` 的
+ * `fs-sandbox`、`packages/bundle/web-app/cordis.patch.yml:97-98` 的 `file-reference-local`），
+ * 我们两行在本仓库的 `cordis.patch.yml:34-37`。
+ */
+export declare const EXPECTED_MODULE_NAMES: Readonly<Record<string, string>>;
+/** 一行离开宿主后允许携带的字段（wire 形态，与 `GET` 的 `rows` 元素一一对应）。 */
+export interface PublicTakeoverRow {
+    /** 规范身份：profile patch 的行 id，UI 显示这个。 */
+    readonly patchId: string;
+    /** Loader 条目的真实 id（`include:fs-sandbox`），只作诊断。 */
+    readonly loaderEntryId?: string;
+    readonly enabled: boolean;
+    readonly readOnlyReason?: string;
+}
+/**
+ * 把宿主插件清单投影成四行。
+ *
+ * @param listed - `pluginManager.listPlugins()` 的返回值（形状未知，逐字段校验）。
+ * @returns 认出来的那几行，按 {@link TAKEOVER_PATCH_IDS} 的顺序；认不出的、歧义的都丢掉。
+ */
+export declare function readTakeoverRows(listed: unknown): readonly TakeoverRow[];
+/**
+ * 一行的 wire 投影：规范 id + 可选诊断 id，`readOnlyReason` 缺省时不出现。
+ *
+ * `fiberPhase` 刻意不出去：客户端按 `enabled` 画开关，运行态差异由 `GET` 的 `reason` 说清楚。
+ *
+ * @param row - 内部行。
+ * @returns `{ patchId, loaderEntryId?, enabled, readOnlyReason? }`。
+ */
+export declare function publicTakeoverRow(row: TakeoverRow): PublicTakeoverRow;
+//# sourceMappingURL=takeover-rows.d.ts.map

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

@@ -0,0 +1,98 @@
+/**
+ * Transport selection: which implementation serves a connection, and why.
+ *
+ * The decision is **probe-driven**, never platform-guessed (ADR-0006): a mux failure measured on
+ * this machine is remembered, and a later decision for the same connection changes accordingly.
+ * Everything observable about the decision is returned as a structured record so the connection
+ * UI can show *why* a connection is slower instead of hiding it.
+ *
+ * @module dsh-over-ssh/app/transport-selector
+ */
+import type { ConnectionProfile, TransportKind } from '../../domain/roots/connection.ts';
+import type { MultiplexingCache } from '../../infra/transport/transport.ts';
+/** Stable reasons a transport was chosen. */
+export type TransportReason = 'explicit-ssh2' | 'explicit-alias' | 'explicit-agent' | 'agent-unavailable' | 'password-requires-ssh2' | 'no-multiplexing' | 'ssh2-unavailable' | 'alias-required' | 'default-alias';
+/** A non-fatal loss of quality the user should know about. */
+export interface TransportDegradation {
+    /** Stable code for the UI to branch on. */
+    readonly code: 'no-connection-reuse' | 'ssh2-unavailable' | 'alias-unavailable' | 'password-needs-key' | 'agent-unavailable';
+    /** Actionable, user-facing sentence. */
+    readonly hint: string;
+}
+/** The outcome of one selection. */
+export interface TransportDecision {
+    readonly connectionId: string;
+    readonly kind: TransportKind;
+    readonly reason: TransportReason;
+    /** One sentence for the UI/status badge. */
+    readonly hint: string;
+    readonly degradations: readonly TransportDegradation[];
+    /** Whether commands can share one connection (`false` on Windows without ssh2, for example). */
+    readonly reusesConnection: boolean;
+}
+/** Whether the optional Tier 2 agent can serve this connection right now. */
+export interface AgentAvailability {
+    /**
+     * `false` only when a previous ladder run already failed (the reason is then required).
+     *
+     * `true` and `undefined` both mean "the selector cannot know yet": an explicit agent choice is honoured
+     * optimistically and the async preflight downgrades it after running the ladder.
+     */
+    readonly available: boolean;
+    /** Why it is unavailable (the ladder's reason), for the UI. */
+    readonly reason?: string;
+    /** One sentence for the status badge. */
+    readonly hint?: string;
+}
+/** Facts the selector needs. All of them are injected so this module stays testable offline. */
+export interface TransportSelectionInput {
+    readonly profile: ConnectionProfile;
+    /** Whether the `ssh2` dependency is loadable in this build. */
+    readonly ssh2Available: boolean;
+    /** Remembers hosts whose `ssh` client cannot multiplex. */
+    readonly multiplexing: Pick<MultiplexingCache, 'isUnsupported' | 'reasonFor'>;
+    /** `ssh` executable name, for the multiplexing cache key. */
+    readonly sshBinary?: string;
+    /** Tier 2 availability. Absent means "not considered", which keeps the agent strictly opt-in. */
+    readonly agent?: AgentAvailability;
+}
+/**
+ * Choose a transport for one connection.
+ *
+ * Order of concerns: an explicit user choice wins unless it cannot work at all (password auth on
+ * the system client, a missing dependency); only then is another implementation substituted, and
+ * the substitution is always reported as a degradation.
+ *
+ * @param input - profile plus injected environment facts.
+ * @returns the decision, including every degradation.
+ */
+export declare function selectTransport(input: TransportSelectionInput): TransportDecision;
+/** Records observed facts so later decisions reflect reality. */
+export declare class TransportSelector {
+    #private;
+    constructor(options: {
+        readonly multiplexing: Pick<MultiplexingCache, 'isUnsupported' | 'reasonFor'> & Partial<Pick<MultiplexingCache, 'markUnsupported'>>;
+        readonly ssh2Available: boolean;
+        readonly sshBinary?: string;
+    });
+    /** Whether the `ssh2` dependency is currently loadable. */
+    get ssh2Available(): boolean;
+    /** Late-bound availability (the dependency is loaded lazily). */
+    setSsh2Available(available: boolean): void;
+    /**
+     * Decide for one profile.
+     *
+     * @param profile - the saved connection.
+     * @returns the decision.
+     * @throws SshDevError `CONNECTION_INVALID` when no implementation can serve the connection.
+     */
+    decide(profile: ConnectionProfile): TransportDecision;
+    /**
+     * Record that this connection's `ssh` client could not multiplex.
+     *
+     * Called by the integration layer right after an {@link AliasTransport} connect attempt, so the
+     * next decision (and every other connection sharing the same client+alias) picks ssh2.
+     */
+    noteMultiplexingFailure(profile: ConnectionProfile, reason: string): void;
+}
+//# sourceMappingURL=transport-selector.d.ts.map

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

@@ -0,0 +1,82 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=transport-service.d.ts.map

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

@@ -0,0 +1,98 @@
+/**
+ * Transport selection: which implementation serves a connection, and why.
+ *
+ * The decision is **probe-driven**, never platform-guessed (ADR-0006): a mux failure measured on
+ * this machine is remembered, and a later decision for the same connection changes accordingly.
+ * Everything observable about the decision is returned as a structured record so the connection
+ * UI can show *why* a connection is slower instead of hiding it.
+ *
+ * @module dsh-remote-workspace/app/transport-selector
+ */
+import type { ConnectionProfile, TransportKind } from '../domain/connection.ts';
+import type { MultiplexingCache } from '../infra/transport/transport.ts';
+/** Stable reasons a transport was chosen. */
+export type TransportReason = 'explicit-ssh2' | 'explicit-alias' | 'explicit-agent' | 'agent-unavailable' | 'password-requires-ssh2' | 'no-multiplexing' | 'ssh2-unavailable' | 'alias-required' | 'default-alias';
+/** A non-fatal loss of quality the user should know about. */
+export interface TransportDegradation {
+    /** Stable code for the UI to branch on. */
+    readonly code: 'no-connection-reuse' | 'ssh2-unavailable' | 'alias-unavailable' | 'password-needs-key' | 'agent-unavailable';
+    /** Actionable, user-facing sentence. */
+    readonly hint: string;
+}
+/** The outcome of one selection. */
+export interface TransportDecision {
+    readonly connectionId: string;
+    readonly kind: TransportKind;
+    readonly reason: TransportReason;
+    /** One sentence for the UI/status badge. */
+    readonly hint: string;
+    readonly degradations: readonly TransportDegradation[];
+    /** Whether commands can share one connection (`false` on Windows without ssh2, for example). */
+    readonly reusesConnection: boolean;
+}
+/** Whether the optional Tier 2 agent can serve this connection right now. */
+export interface AgentAvailability {
+    /**
+     * `false` only when a previous ladder run already failed (the reason is then required).
+     *
+     * `true` and `undefined` both mean "the selector cannot know yet": an explicit agent choice is honoured
+     * optimistically and the async preflight downgrades it after running the ladder.
+     */
+    readonly available: boolean;
+    /** Why it is unavailable (the ladder's reason), for the UI. */
+    readonly reason?: string;
+    /** One sentence for the status badge. */
+    readonly hint?: string;
+}
+/** Facts the selector needs. All of them are injected so this module stays testable offline. */
+export interface TransportSelectionInput {
+    readonly profile: ConnectionProfile;
+    /** Whether the `ssh2` dependency is loadable in this build. */
+    readonly ssh2Available: boolean;
+    /** Remembers hosts whose `ssh` client cannot multiplex. */
+    readonly multiplexing: Pick<MultiplexingCache, 'isUnsupported' | 'reasonFor'>;
+    /** `ssh` executable name, for the multiplexing cache key. */
+    readonly sshBinary?: string;
+    /** Tier 2 availability. Absent means "not considered", which keeps the agent strictly opt-in. */
+    readonly agent?: AgentAvailability;
+}
+/**
+ * Choose a transport for one connection.
+ *
+ * Order of concerns: an explicit user choice wins unless it cannot work at all (password auth on
+ * the system client, a missing dependency); only then is another implementation substituted, and
+ * the substitution is always reported as a degradation.
+ *
+ * @param input - profile plus injected environment facts.
+ * @returns the decision, including every degradation.
+ */
+export declare function selectTransport(input: TransportSelectionInput): TransportDecision;
+/** Records observed facts so later decisions reflect reality. */
+export declare class TransportSelector {
+    #private;
+    constructor(options: {
+        readonly multiplexing: Pick<MultiplexingCache, 'isUnsupported' | 'reasonFor'> & Partial<Pick<MultiplexingCache, 'markUnsupported'>>;
+        readonly ssh2Available: boolean;
+        readonly sshBinary?: string;
+    });
+    /** Whether the `ssh2` dependency is currently loadable. */
+    get ssh2Available(): boolean;
+    /** Late-bound availability (the dependency is loaded lazily). */
+    setSsh2Available(available: boolean): void;
+    /**
+     * Decide for one profile.
+     *
+     * @param profile - the saved connection.
+     * @returns the decision.
+     * @throws SshDevError `CONNECTION_INVALID` when no implementation can serve the connection.
+     */
+    decide(profile: ConnectionProfile): TransportDecision;
+    /**
+     * Record that this connection's `ssh` client could not multiplex.
+     *
+     * Called by the integration layer right after an {@link AliasTransport} connect attempt, so the
+     * next decision (and every other connection sharing the same client+alias) picks ssh2.
+     */
+    noteMultiplexingFailure(profile: ConnectionProfile, reason: string): void;
+}
+//# sourceMappingURL=transport-selector.d.ts.map

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

@@ -0,0 +1,75 @@
+/**
+ * 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-remote-workspace/app/transport-service
+ */
+import type { ConnectionProfile } from '../domain/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.
+ */
+export type TransportPreflight = (profile: ConnectionProfile, decision: TransportDecision) => 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>;
+}
+//# sourceMappingURL=transport-service.d.ts.map