dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,221 @@
+/**
+ * 会话管理的**契约**：依赖注入形状、会话头、删除/恢复/清理结果与服务接口。
+ *
+ * 从 `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;
+    /** 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).
+ */
+//# sourceMappingURL=session-admin-contract.d.ts.map

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

@@ -0,0 +1,34 @@
+/**
+ * 会话管理的**删除族**：预览、物理删除、移入回收站、批量清理、按工作区删除。
+ *
+ * 从 `session-admin-service.ts` 的工厂里抽出（审计 0076）：只依赖上下文，不依赖列表/恢复/清扫。
+ *
+ * @module dsh-over-ssh/app/session-admin-delete
+ */
+import { type SessionTrashEntry, type SessionTrashEntryId } from '../../domain/session/session-admin.ts';
+import { type SessionAdminContext } from './session-admin-context.ts';
+import type { PurgeSessionResult, DeleteSessionResult } from './session-admin-contract.ts';
+import type { DeleteDecision } from '../../domain/session/session-admin.ts';
+export declare function createSessionAdminDelete(ctx: SessionAdminContext): {
+    previewDelete: (ids: readonly string[], options?: import("./session-admin-contract.ts").SessionAdminOptions & {
+        readonly keep?: readonly string[];
+    }) => Promise<DeleteDecision>;
+    deleteSession: (ids: readonly string[], options?: import("./session-admin-contract.ts").SessionAdminOptions & {
+        readonly mode?: "recycle" | "permanent";
+        readonly keep?: readonly string[];
+    }) => Promise<DeleteSessionResult>;
+    deleteWorkspaceSessions: (cwd: string, options?: import("./session-admin-contract.ts").SessionAdminOptions & {
+        readonly mode?: "recycle" | "permanent";
+    }) => Promise<DeleteSessionResult & {
+        readonly matched: number;
+    }>;
+    purgeEntry: (entryId: string) => Promise<PurgeSessionResult>;
+    purgeEntries: (doomed: readonly SessionTrashEntry[], known: readonly SessionTrashEntry[]) => Promise<{
+        readonly purged: readonly PurgeSessionResult[];
+        readonly failed: readonly {
+            readonly id: SessionTrashEntryId;
+            readonly reason: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=session-admin-delete.d.ts.map

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

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

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

@@ -0,0 +1,36 @@
+/**
+ * 会话管理的**上下文**：bin 根、索引读写、跨进程串行化、会话清单。
+ *
+ * 从 `session-admin-service.ts` 的工厂里抽出（审计 0076）：所有方法族的公共底座。
+ *
+ * @module dsh-remote-workspace/app/session-admin-context
+ */
+import { type SessionRecord, type SessionTrashEntry } from '../domain/session-admin.ts';
+import type { SessionAdminDeps, SessionAdminOptions } from './session-admin-contract.ts';
+/** Whether a thrown error means "the path does not exist". */
+export declare function isMissing(error: unknown): boolean;
+export declare function createSessionAdminContext(deps: SessionAdminDeps): {
+    deps: SessionAdminDeps;
+    sessionsRoot: string;
+    binRoot: string;
+    indexePath: () => string;
+    serialized: <T>(operation: () => Promise<T>) => Promise<T>;
+    entryDir: (segment: string) => string;
+    readIndex: () => Promise<readonly SessionTrashEntry[]>;
+    writeIndex: (entries: readonly SessionTrashEntry[]) => Promise<void>;
+    inventory: (options?: SessionAdminOptions) => Promise<readonly SessionRecord[]>;
+};
+export type SessionAdminContext = ReturnType<typeof createSessionAdminContext>;
+/**
+ * Fold a path to a comparison key: forward slashes, no trailing separator, lower case.
+ *
+ * The same fold the label resolver uses (`session-labels.ts`), duplicated here because this module must not
+ * import the resolver: the resolver reads platform services, this one is pure. Windows paths are
+ * case-insensitive and a header's `cwd` is the raw spawn directory while a workspace record's path is
+ * canonicalized, so an exact compare would miss real matches.
+ *
+ * @param path - a path in either spelling.
+ * @returns the comparison key.
+ */
+export declare function normalizePathKey(path: string): string;
+//# sourceMappingURL=session-admin-context.d.ts.map

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

@@ -0,0 +1,214 @@
+/**
+ * 会话管理的**契约**：依赖注入形状、会话头、删除/恢复/清理结果与服务接口。
+ *
+ * 从 `session-admin-service.ts` 抽出（审计 0076）：上下文模块需要这些类型，留在 service 里会形成环。
+ *
+ * @module dsh-remote-workspace/app/session-admin-contract
+ */
+import { type DeleteDecision, type SessionRecord, type SessionTrashEntry, type SessionTrashEntryId } from '../domain/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 a session is currently held by a live agent; never deleted. */
+    readonly isLive: (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;
+    /** 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).
+ */
+//# sourceMappingURL=session-admin-contract.d.ts.map

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

@@ -0,0 +1,34 @@
+/**
+ * 会话管理的**删除族**：预览、物理删除、移入回收站、批量清理、按工作区删除。
+ *
+ * 从 `session-admin-service.ts` 的工厂里抽出（审计 0076）：只依赖上下文，不依赖列表/恢复/清扫。
+ *
+ * @module dsh-remote-workspace/app/session-admin-delete
+ */
+import { type SessionTrashEntry, type SessionTrashEntryId } from '../domain/session-admin.ts';
+import { type SessionAdminContext } from './session-admin-context.ts';
+import type { PurgeSessionResult, DeleteSessionResult } from './session-admin-contract.ts';
+import type { DeleteDecision } from '../domain/session-admin.ts';
+export declare function createSessionAdminDelete(ctx: SessionAdminContext): {
+    previewDelete: (ids: readonly string[], options?: import("./session-admin-contract.ts").SessionAdminOptions & {
+        readonly keep?: readonly string[];
+    }) => Promise<DeleteDecision>;
+    deleteSession: (ids: readonly string[], options?: import("./session-admin-contract.ts").SessionAdminOptions & {
+        readonly mode?: "recycle" | "permanent";
+        readonly keep?: readonly string[];
+    }) => Promise<DeleteSessionResult>;
+    deleteWorkspaceSessions: (cwd: string, options?: import("./session-admin-contract.ts").SessionAdminOptions & {
+        readonly mode?: "recycle" | "permanent";
+    }) => Promise<DeleteSessionResult & {
+        readonly matched: number;
+    }>;
+    purgeEntry: (entryId: string) => Promise<PurgeSessionResult>;
+    purgeEntries: (doomed: readonly SessionTrashEntry[], known: readonly SessionTrashEntry[]) => Promise<{
+        readonly purged: readonly PurgeSessionResult[];
+        readonly failed: readonly {
+            readonly id: SessionTrashEntryId;
+            readonly reason: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=session-admin-delete.d.ts.map

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

@@ -0,0 +1,38 @@
+/**
+ * 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. **Live sessions are never touched.** The decision layer refuses them; this layer re-checks before moving, so
+ *     a session that went live between preview and confirm is refused rather than killed.
+ *
+ * ## 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-remote-workspace/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;
+//# sourceMappingURL=session-admin-service.d.ts.map