dsh-over-ssh 0.0.0-stage → 0.1.1

package/lib/types/src/host/app/recycle-bin/recycle-bin-contract.d.ts

@@ -0,0 +1,246 @@
+/**
+ * 回收站服务的**契约**：依赖注入形状、目标/结果类型、索引状态。
+ *
+ * 从 `recycle-bin-service.ts` 抽出（审计 0076）。抽出的直接原因不是"文件太长"，而是
+ * 世界原语模块需要这些类型：留在 service 里会形成 `world → service`（type）与
+ * `service → world`（value）的环，架构测试会红。契约独立后方向单一。
+ *
+ * @module dsh-over-ssh/app/recycle-bin-contract
+ */
+import type { BackendEntry, BackendStat } from '../backend.ts';
+import { type RecycleBinEntry, type RecycleBinEntryId } from '../../domain/transfer/recycle-bin.ts';
+import { type RootRef } from '../../domain/roots/root.ts';
+export interface RecycleBinRemovalOptions {
+    /** Whether the target is a directory that must be removed with its content. */
+    readonly recursive: boolean;
+    /** Caller cancellation. */
+    readonly signal?: AbortSignal;
+}
+/** The mutating primitives of one execution world, shaped like the remote group. */
+/**
+ * Serialize every read-modify-write of the bin index.
+ *
+ * ## Why this is a seam and not a mutex inside the service
+ *
+ * Two separate processes can drive the same bin: the plugin runs inside DSH, but the user may also have a
+ * second DSH (another port, a headless run) pointed at the same state directory. An in-process promise chain
+ * would serialize one process and still let the other interleave — that is exactly the hole
+ * `session-bin-lock.ts` was written to close for the **session** bin, and this bin has the same shape.
+ *
+ * The implementation is a cross-process file lock (see `createSessionBinLock`). Keeping it behind this seam
+ * means the domain service never imports `node:fs`, and tests can inject a no-op or a recording stub.
+ *
+ * @param key - the root being mutated; implementations may use it to pick a per-root lock file.
+ * @param operation - the critical section; must perform its own read **and** write inside it.
+ */
+export type WithIndexLock = <T>(key: string, operation: () => Promise<T>) => Promise<T>;
+export interface RecycleBinWorldIo {
+    /**
+     * Move (rename) a path.
+     *
+     * Contract: the implementation must create a missing destination parent directory (equivalent to
+     * `mkdir -p` + `rename`). A cross-device move that cannot be done by rename must **fail loudly**; silently
+     * degrading to copy-then-delete would break the "don't delete until it is in the bin" guarantee.
+     */
+    readonly move: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
+    /** Physically delete a path. */
+    readonly remove: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
+    /** List one directory. */
+    readonly list: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
+    /** Read a text file (the index). */
+    readonly readText: (path: string, signal?: AbortSignal) => Promise<string>;
+    /** Write a text file as UTF-8 **without BOM** (the index). */
+    readonly writeText: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
+}
+/** Everything {@link createRecycleBinService} needs; each field is injected so tests need no host. */
+export interface RecycleBinServiceDeps {
+    /** Bin root directory for one root; a deployment setting, never hardcoded here. */
+    readonly binRootFor: (root: RootRef) => string;
+    /** Find a root by its `rootKey()`; `undefined` means the root is no longer registered. */
+    readonly resolveRoot: (key: string) => RootRef | undefined;
+    /** `stat` in the local world. */
+    readonly statLocal: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
+    /** `stat` in the remote world. */
+    readonly statRemote: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
+    /** Move primitive of the remote world. */
+    readonly moveRemote: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
+    /** Remove primitive of the remote world. */
+    readonly removeRemote: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
+    /** List primitive of the remote world. */
+    readonly listRemote: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
+    /** Index read primitive of the remote world. */
+    readonly readTextRemote: (path: string, signal?: AbortSignal) => Promise<string>;
+    /** Index write primitive of the remote world (UTF-8, no BOM). */
+    readonly writeTextRemote: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
+    /** Clock, injected so a test can pin "now". */
+    readonly now: () => number;
+    /** Undo depth from configuration (a non-positive value keeps no history). */
+    readonly undoDepth: number;
+    /** Roots whose bins exist, so `sweep()` can walk them all. */
+    readonly knownRoots: () => readonly RootRef[];
+    /**
+     * Cross-process lock around every index read-modify-write.
+     *
+     * Optional so the domain service stays testable without touching the filesystem; when absent the service
+     * falls back to an in-process chain, which is **weaker** (it cannot see a second DSH process) and is
+     * therefore only acceptable in tests. Production wiring always injects the real lock.
+     */
+    readonly withIndexLock?: WithIndexLock;
+    /**
+     * Local-world mutators.
+     *
+     * Optional: a service built for remote work omits it, and touching a local target then fails with
+     * `REMOTE_UNSUPPORTED` instead of misapplying the remote primitives to a local path.
+     */
+    readonly localIo?: RecycleBinWorldIo;
+}
+/** One deletion target: a root plus a path inside it. */
+export interface RecycleBinTarget {
+    readonly root: RootRef;
+    /** Absolute path in the root's own spelling. */
+    readonly path: string;
+}
+/** A bin view scope: one root, optionally narrowed to targets deleted under one directory. */
+export interface RecycleBinScope {
+    readonly root: RootRef;
+    /** Optional directory prefix, matched per path segment. */
+    readonly path?: string;
+}
+/** How {@link RecycleBinService.discard} removes a target. */
+export type DiscardMode = 'permanent' | 'recycle';
+/** Options for {@link RecycleBinService.discard}. */
+export interface DiscardOptions {
+    readonly mode: DiscardMode;
+    readonly signal?: AbortSignal;
+}
+/** Result of a discard. */
+export interface DiscardResult {
+    readonly mode: DiscardMode;
+    /** The bin entry in `recycle` mode; `undefined` for `permanent`. */
+    readonly entry: RecycleBinEntry | undefined;
+    /** Whether the content can still be recovered. **Always `false` for `permanent`.** */
+    readonly recoverable: boolean;
+    /** Post-operation confirmation: the original path is gone. */
+    readonly verified: boolean;
+    /** Human-facing note, mandatory for an irreversible delete. */
+    readonly warning: string | undefined;
+}
+/** What a bin actually holds for one root. */
+export interface RecycleBinListing {
+    readonly entries: readonly RecycleBinEntry[];
+    /** Ids the index knows but the bin directory no longer contains. */
+    readonly missing: readonly RecycleBinEntryId[];
+    /** Directory names in the bin that no index record claims. */
+    readonly orphans: readonly string[];
+    /** Index records that were unusable and skipped. */
+    readonly skipped: number;
+}
+/** Result of a restore. */
+export interface RestoreResult {
+    readonly entry: RecycleBinEntry;
+    readonly restoredPath: string;
+    readonly verified: boolean;
+}
+/** Result of a physical delete from the bin. */
+export interface PurgeResult {
+    readonly id: RecycleBinEntryId;
+    readonly sizeBytes: number;
+    /** Always true when the call returns; a failed delete throws instead. */
+    readonly purged: boolean;
+    readonly warning: string;
+}
+/** Options for `list`, `restore`, `purge`, `undo` and `redo`. */
+export interface OperationOptions {
+    readonly signal?: AbortSignal;
+}
+/** Result of an undo or redo step. */
+export interface UndoResult {
+    /** The action that was executed. */
+    readonly action: 'discard' | 'restore';
+    readonly entry: RecycleBinEntry;
+    /** Human-facing description of what happened. */
+    readonly message: string;
+}
+/** Retention limits for one sweep; all optional. */
+export interface SweepOptions {
+    /** Keep at most this many entries per bin; non-positive/absent = unlimited. */
+    readonly maxEntries?: number;
+    /** Keep at most this many bytes per bin; non-positive/absent = unlimited. */
+    readonly maxBytes?: number;
+    /** Keep entries at most this old; non-positive/absent = unlimited. */
+    readonly maxAgeMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** One entry physically removed by a sweep. */
+export interface SweepPurge {
+    readonly rootKey: string;
+    readonly id: RecycleBinEntryId;
+    readonly sizeBytes: number;
+    readonly dimension: 'age' | 'count' | 'bytes';
+}
+/** One entry a sweep could not delete; the sweep continues with the rest. */
+export interface SweepFailure {
+    readonly rootKey: string;
+    readonly id?: RecycleBinEntryId;
+    readonly message: string;
+}
+/** Per-root summary of a sweep. */
+export interface SweepRootReport {
+    readonly rootKey: string;
+    readonly considered: number;
+    readonly purged: readonly RecycleBinEntryId[];
+    readonly kept: readonly RecycleBinEntryId[];
+    readonly reasons: readonly {
+        readonly id: RecycleBinEntryId;
+        readonly dimension: 'age' | 'count' | 'bytes';
+    }[];
+}
+/** Outcome of a sweep. */
+export interface SweepReport {
+    readonly purged: readonly SweepPurge[];
+    readonly roots: readonly SweepRootReport[];
+    readonly failures: readonly SweepFailure[];
+    /** `false` when no dimension was limited: no retention decision was made (an unconfigured 0 must not empty a bin). */
+    readonly policyApplied: boolean;
+    /**
+     * Empty entry directories removed because no index record claimed them.
+     *
+     * Reported separately from `purged` because these are garbage, not retention: they are pruned even when no
+     * limit is configured, and they were never recoverable (audit 0098).
+     */
+    readonly prunedOrphans: number;
+}
+/** Read-only undo state, for a UI that needs to enable or disable the buttons. */
+export interface RecycleBinHistory {
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly undo: readonly {
+        readonly kind: string;
+        readonly id: string;
+    }[];
+    readonly redo: readonly {
+        readonly kind: string;
+        readonly id: string;
+    }[];
+    readonly dropped: number;
+    readonly undoDepth: number;
+}
+/** The service surface. */
+export interface RecycleBinService {
+    /** Delete a target permanently or into the recycle bin. */
+    discard(target: RecycleBinTarget, options: DiscardOptions): Promise<DiscardResult>;
+    /** List one bin, reconciled against the directory that actually exists. */
+    list(scope: RecycleBinScope, options?: OperationOptions): Promise<RecycleBinListing>;
+    /** Restore one entry to its original path. */
+    restore(id: RecycleBinEntryId, options?: OperationOptions): Promise<RestoreResult>;
+    /** Physically delete one entry from the bin. */
+    purge(id: RecycleBinEntryId, options?: OperationOptions): Promise<PurgeResult>;
+    /** Apply retention limits to every known bin. */
+    sweep(options: SweepOptions): Promise<SweepReport>;
+    /** Undo the newest operation. */
+    undo(options?: OperationOptions): Promise<UndoResult>;
+    /** Re-apply the newest undone operation. */
+    redo(options?: OperationOptions): Promise<UndoResult>;
+    /** Current undo/redo state. */
+    history(): RecycleBinHistory;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * The recycle-bin service: the domain's pure decisions wired to injected I/O primitives.
+ *
+ * The seam is deliberate (AGENTS.md 红线 3): every path that touches a real filesystem or a real SSH
+ * connection arrives as a function, so this module is testable offline and a test can inject a move that fails.
+ *
+ * Two contracts matter more than the rest:
+ *
+ *  1. **Move first, then confirm.** In `recycle` mode a success is reported only after `stat` shows the entry
+ *     inside the bin **and** the original path gone. A move that throws is confirmed before anything is
+ *     claimed: if the move actually landed (a lost response) it counts as success, otherwise the call fails
+ *     and nothing is recorded — "deleted but not in the bin" must never be reported as success.
+ *  2. **The index write is never swallowed.** If the index cannot be written after a successful move, the move
+ *     is rolled back and the failure is reported; a physical delete has no rollback, so that case is reported
+ *     with `purged: true, indexStale: true` instead of being hidden.
+ *
+ * Other decisions worth knowing:
+ *
+ *  - A `permanent` discard is irreversible by construction and says so in its result (`recoverable: false`),
+ *    and its undo record is refused as `irreversible`.
+ *  - Restoring onto an occupied original path is **refused** (`TRANSFER_CONFLICT`, with the informational
+ *    `suggestedPath` in `details`); this module never silently restores to a different name.
+ *  - `*Remote` primitives are the **remote world's** mutators. A local root additionally needs `localIo`; when it
+ *    is missing the call fails with `REMOTE_UNSUPPORTED` rather than reusing remote primitives on local paths.
+ *  - Every destructive call takes an `AbortSignal`, propagated to every injected primitive.
+ *  - Error codes are reused from the existing table (no new code is registered): `TRASH_NOT_FOUND` (missing
+ *    entry, unreadable index), `REMOTE_NOT_FOUND` (target gone), `TRANSFER_CONFLICT` (occupied restore path),
+ *    `ROOT_OUTSIDE` (symlink target refused), `ROOT_AMBIGUOUS` (one id in two bins), `REMOTE_UNSUPPORTED`
+ *    (local root without local primitives), `REMOTE_COMMAND_FAILED` (an operation that could not be confirmed),
+ *    `ROOT_INVALID` (unusable configuration/input), `CANCELLED` (aborted signal).
+ *
+ * @module dsh-over-ssh/integration/recycle-bin-service
+ */
+import type { RecycleBinServiceDeps, RecycleBinService } from './recycle-bin-contract.ts';
+export * from './recycle-bin-contract.ts';
+/** Removal options for one physical delete. */
+export * from './recycle-bin-contract.ts';
+/**
+ * Build the service.
+ *
+ * @param deps - injected I/O, clock, configuration and root lookup.
+ * @returns a {@link RecycleBinService}; its undo stack is per-instance, in memory and not persisted.
+ */
+export declare function createRecycleBinService(deps: RecycleBinServiceDeps): RecycleBinService;

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

@@ -0,0 +1,232 @@
+/**
+ * 会话管理的**契约**：依赖注入形状、会话头、删除/恢复/清理结果与服务接口。
+ *
+ * 从 `session-admin-service.ts` 抽出（审计 0076）：上下文模块需要这些类型，留在 service 里会形成环。
+ *
+ * @module dsh-over-ssh/app/session-admin-contract
+ */
+import { type DeleteDecision, type SessionRecord, type SessionTrashEntry, type SessionTrashEntryId } from '../../domain/session/session-admin.ts';
+export interface SessionDirEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly bytes: number;
+    readonly mtimeMs: number;
+}
+/**
+ * Everything the service needs from the outside world.
+ *
+ * `readHeader` is deliberately the **only** way to learn about a session: the directory name cannot be decoded
+ * (see ADR-0009), so classification must come from the header.
+ */
+export interface SessionAdminDeps {
+    /** The platform's sessions root (e.g. `~/.dsh/sessions`). */
+    readonly sessionsRoot: string;
+    /** The plugin's own bin root; must **not** be inside {@link sessionsRoot}. */
+    readonly binRoot: string;
+    /** List one directory's entries; a missing directory yields an empty list, not a failure. */
+    readonly listDir: (path: string) => Promise<readonly SessionDirEntry[]>;
+    /** Read a session header. `undefined` means the log is unreadable (corrupt/unsupported). */
+    readonly readHeader: (sessionDir: string) => Promise<SessionHeader | undefined>;
+    /**
+     * Display title of the workspace that owns a session directory, or `undefined` when none does.
+     *
+     * Injected because the mapping lives in the platform's workspace registry, which the domain layer must not
+     * import (see the repository's red lines). A listing without this resolver still answers: every row keeps
+     * its `cwd`, so a reader falls back to the directory's own leaf name.
+     */
+    readonly resolveWorkspaceTitle?: ((cwd: string | undefined) => string | undefined) | undefined;
+    /**
+     * The session's generated title, or `undefined` when it has none.
+     *
+     * The header carries no title (it is a projection, not header metadata), so this is the only way a listing
+     * can label a session by name. Injected for the same reason as {@link resolveWorkspaceTitle}; without it
+     * every row falls back to its id.
+     */
+    readonly resolveSessionTitle?: ((header: SessionHeader) => string | undefined) | undefined;
+    /** `stat`; `undefined` when the path does not exist. */
+    readonly stat: (path: string) => Promise<{
+        readonly isDirectory: boolean;
+        readonly bytes: number;
+    } | undefined>;
+    /** Read a text file. */
+    readonly readText: (path: string) => Promise<string>;
+    /** Write a text file (UTF-8, no BOM). */
+    readonly writeText: (path: string, text: string) => Promise<void>;
+    /**
+     * Replace a text file **atomically** (write a temp file, then rename over the target).
+     *
+     * Optional, and worth supplying: without it a process killed mid-write leaves a truncated JSON index,
+     * which the parser then rejects as a hard failure. Atomic replace makes the index either the old or the
+     * new document, never a fragment.
+     */
+    readonly writeTextAtomic?: (path: string, text: string) => Promise<void>;
+    /**
+     * Run `operation` while holding a **cross-process** lock for `key`.
+     *
+     * The in-process chain cannot see another DSH process; without this, two processes deleting at the same
+     * time can each read the old index and overwrite the other's entry — leaving bytes in the bin that no
+     * index mentions (invisible and unrestorable).
+     *
+     * A caller-supplied implementation must be **exclusive** and must not deadlock when the previous holder
+     * died (see `createSessionBinLock`, which reclaims a stale lock by age).
+     */
+    readonly withLock?: <T>(key: string, operation: () => Promise<T>) => Promise<T>;
+    /**
+     * Move a directory. Must be atomic on one filesystem; the caller supplies the cross-device fallback.
+     *
+     * Returning `'copy'` means the implementation copied (cross-device) and the source is already gone.
+     */
+    readonly moveDir: (from: string, to: string) => Promise<'rename' | 'copy'>;
+    /** Recursively remove a directory (used for purge and for rolling back a failed record). */
+    readonly removeDir: (path: string) => Promise<void>;
+    /** Copy a directory recursively (the cross-device fallback, when the deps implement it themselves). */
+    readonly copyDir?: (from: string, to: string) => Promise<void>;
+    /** Whether the host currently holds this session in its store (it was opened in this process). */
+    readonly isLive: (sessionId: string) => boolean;
+    /**
+     * Whether this session's agent is running a turn right now.
+     *
+     * The platform's own "运行中" signal (`agents.get(id)?.status === 'running'`, the same one the session
+     * list uses for its status dot). This — not {@link isLive} — is what a deletion refuses (FR-3.6).
+     */
+    readonly isRunning: (sessionId: string) => boolean;
+    /** Remove a session from workspace bookkeeping (`detachSession`); optional where unavailable. */
+    readonly detachSession?: (sessionId: string) => Promise<void>;
+    /** Announce the removal so clients drop the row (`api-session/removed`). */
+    readonly emitRemoved?: (sessionId: string) => void;
+    /**
+     * The session is gone: drop it from any bookkeeping that remembers session ids.
+     *
+     * Fired **after** the deletion is durable, on both the permanent and the recycle path, and it is not awaited:
+     * losing a stale id in `user-roots.json` must not turn a completed deletion into a failure. The implementation
+     * is expected to be best-effort and to log its own warnings.
+     *
+     * Audit 0112 P3-13: before this, nothing told `user-roots.json` that a session had been deleted, so every root
+     * a session had added kept its dead id forever — the panel went on showing the root as "added by a session
+     * that no longer exists" and the file grew on every write.
+     */
+    readonly onSessionRemoved?: (sessionId: string) => void;
+    /** Injected clock. */
+    readonly now: () => number;
+    /** Who confirmed, for the audit trail (FR-3.10); absent when the caller did not say. */
+    readonly confirmedBy?: string;
+}
+/** The parts of a session header this feature needs. */
+export interface SessionHeader {
+    readonly id: string;
+    /** `cwd` from the header; `undefined` for the platform's no-cwd bucket. */
+    readonly cwd: string | undefined;
+    readonly title: string | undefined;
+    readonly parentSessionId: string | undefined;
+    /**
+     * Session format generation, as stored in the log's first line.
+     *
+     * Together with {@link createdAt} and {@link isSeeded} this is the **lifecycle identity** a header alone
+     * witnesses, and it is what the platform's projection cache validates a stored title row against. A
+     * resolver that skipped it could serve a title from a different lifecycle that reused the same id.
+     */
+    readonly version?: number | undefined;
+    readonly createdAt?: number | undefined;
+    readonly isSeeded?: boolean | undefined;
+}
+/** Options shared by the destructive calls. */
+export interface SessionAdminOptions {
+    readonly signal?: AbortSignal;
+}
+/** Result of a session deletion. */
+export interface DeleteSessionResult {
+    readonly mode: 'recycle' | 'permanent';
+    /** The bin entry in `recycle` mode; `undefined` for `permanent`. */
+    readonly entry: SessionTrashEntry | undefined;
+    /** Whether the content can still be recovered. **Always `false` for `permanent`.** */
+    readonly recoverable: boolean;
+    /** True when the move was observed to have landed (store gone + bin present). */
+    readonly verified: boolean;
+    /** True when the bytes crossed a filesystem boundary and were copied. */
+    readonly copied: boolean;
+    /** Ids that were refused, with the reason (a partial deletion is reported, never hidden). */
+    readonly refusals: DeleteDecision['refusals'];
+    readonly bytes: number;
+}
+/** Result of a restore. */
+export interface RestoreSessionResult {
+    readonly entry: SessionTrashEntry;
+    /** Absolute path the session directory was moved back to. */
+    readonly restoredPath: string;
+    readonly movedBy: 'rename' | 'copy';
+}
+/** One purge outcome. */
+export interface PurgeSessionResult {
+    readonly id: SessionTrashEntryId;
+    readonly sessionId: string;
+    readonly purged: boolean;
+    /** True when the entry was removed physically but the index could not be updated afterwards. */
+    readonly indexStale: boolean;
+}
+/** A retention sweep outcome for the session bin. */
+export interface SweepSessionResult {
+    readonly purged: readonly PurgeSessionResult[];
+    readonly failed: readonly {
+        readonly id: SessionTrashEntryId;
+        readonly reason: string;
+    }[];
+    readonly remainingEntries: number;
+    readonly remainingBytes: number;
+}
+/** The session-bin retention policy (same three dimensions as the file-level bin). */
+export interface SessionBinPolicy {
+    readonly maxEntries: number;
+    readonly maxBytes: number;
+    readonly maxAgeMs: number;
+}
+export declare function joinPath(base: string, ...segments: readonly string[]): string;
+/** The service surface. */
+export interface SessionAdminService {
+    /** Inventory every session in the store (FR-3.3). */
+    inventory(options?: SessionAdminOptions): Promise<readonly SessionRecord[]>;
+    /** Preview a deletion without touching anything (FR-3.7). */
+    previewDelete(ids: readonly string[], options?: SessionAdminOptions & {
+        readonly keep?: readonly string[];
+    }): Promise<DeleteDecision>;
+    /** Delete sessions: into the bin (`recycle`) or irreversibly (`permanent`). */
+    deleteSession(ids: readonly string[], options?: SessionAdminOptions & {
+        readonly mode?: 'recycle' | 'permanent';
+        readonly keep?: readonly string[];
+    }): Promise<DeleteSessionResult>;
+    /**
+     * Delete every session that belongs to one workspace directory, and nothing else.
+     *
+     * The workspace itself is **left registered**: the user asked to clear the workspace's sessions, not to
+     * unregister the workspace (and the platform's `workspaceRegistry.delete` would also be a different,
+     * separately-confirmed action). Sessions are matched by their header's `cwd` against the given directory,
+     * folded the same way the label resolver folds paths, so a Windows case/separator difference still matches.
+     *
+     * Live sessions are refused by the same rules as {@link deleteSession} (they appear in `refusals`), so a
+     * workspace containing a running session is deleted **except** for that session rather than failing whole.
+     *
+     * @param cwd - the workspace directory whose sessions should go.
+     * @param options - deletion mode plus cancellation.
+     * @returns the ids deleted, the per-id refusals, and the bytes freed.
+     */
+    deleteWorkspaceSessions(cwd: string, options?: SessionAdminOptions & {
+        readonly mode?: 'recycle' | 'permanent';
+    }): Promise<DeleteSessionResult & {
+        readonly matched: number;
+    }>;
+    /** List the bin. */
+    list(options?: SessionAdminOptions): Promise<readonly SessionTrashEntry[]>;
+    /** Move one entry back to where it came from. */
+    restore(entryId: string, options?: SessionAdminOptions): Promise<RestoreSessionResult>;
+    /** Delete one entry physically (the irreversible step, after the retention period). */
+    purge(entryId: string, options?: SessionAdminOptions): Promise<PurgeSessionResult>;
+    /** Apply the retention policy. */
+    sweep(policy: SessionBinPolicy, options?: SessionAdminOptions): Promise<SweepSessionResult>;
+}
+/**
+ * Build the session-administration service.
+ *
+ * @param deps - injected I/O.
+ * @returns the service.
+ * @throws SshDevError `ROOT_INVALID` when the bin root is inside the sessions root (that placement breaks the
+ *   platform's session listing — see the module note and ADR-0009).
+ */

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

@@ -0,0 +1,39 @@
+/**
+ * Session administration service: inventory, deletion into the session bin, restore, purge, retention.
+ *
+ * The domain decisions live in [`domain/session-admin.ts`](../domain/session-admin.ts); this module wires them to
+ * injected I/O. Every filesystem and platform call arrives as a function (AGENTS.md 红线 3), so this module is
+ * testable offline and a test can make a move fail.
+ *
+ * ## Three contracts matter more than the rest
+ *
+ *  1. **Move first, confirm, then record.** `deleteSession` reports success only after the session directory is
+ *     observed inside the bin **and** gone from the store. A move that throws is confirmed before anything is
+ *     claimed: if it actually landed (a lost response), that counts as success; otherwise the call fails and
+ *     **nothing** is recorded. "Deleted but not in the bin" must never be reported as success.
+ *  2. **The index write is never swallowed.** If the index cannot be written after a successful move, the move is
+ *     rolled back and the failure is reported. A physical purge has no rollback, so that case is reported with
+ *     `purged: true, indexStale: true` instead of being hidden.
+ *  3. **Running sessions are never touched.** The decision layer refuses them; this layer re-checks before
+ *     moving, so a session that started running between preview and confirm is refused rather than killed.
+ *     "Running" is the platform's `agents.get(id)?.status === 'running'`, not "loaded in the host": the latter
+ *     is true for every session opened since the process started and would make almost nothing deletable.
+ *
+ * ## Where the bin lives (and why not under `sessions/`)
+ *
+ * The platform enumerates **every** directory under the sessions root (`listProjectDirs` has no dot-directory
+ * filter) and fails the whole listing when one session id appears twice. A bin inside `sessions/` that kept the
+ * original log filename would therefore make deleted sessions reappear *and* break the session list. The bin
+ * lives in the plugin's own storage instead — see ADR-0009.
+ *
+ * @module dsh-over-ssh/integration/session-admin-service
+ */
+import type { SessionAdminDeps, SessionAdminService } from './session-admin-contract.ts';
+export * from './session-admin-contract.ts';
+/**
+ * Build the service.
+ *
+ * @param deps - injected platform services.
+ * @returns the {@link SessionAdminService}.
+ */
+export declare function createSessionAdminService(deps: SessionAdminDeps): SessionAdminService;

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

@@ -0,0 +1,97 @@
+/**
+ * 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;
+}