dsh-over-ssh 0.1.0 → 0.1.1

package/lib/types/src/host/integration/session/session-api.d.ts

@@ -1,88 +0,0 @@
-/**
- * The session-administration HTTP route: `/api/over-ssh/sessions`.
- *
- * The route is the client half's only way to reach the session store. It reuses the roots route's
- * **same-origin trust check** ({@link trustVerdict}) rather than inventing a second policy: a request that may
- * edit roots may also delete sessions, and one that may not, may not.
- *
- * ## Two rules that shape the wire
- *
- *  1. **`GET` never mutates.** It answers the inventory and the bin. Deletion and restore are `POST` actions,
- *     so a prefetch, a link preview or an over-eager browser cannot destroy anything.
- *  2. **Irreversible actions are refused here unless the caller says it means it.** `purge` and
- *     `mode: 'permanent'` require `confirm: true` in the body. The UI already asks; this is the second lock, so
- *     a bug in the client cannot turn a recycle into an irreversible delete.
- *
- * @module dsh-over-ssh/integration/session-api
- */
-import { type RootsApiRequest, type RootsApiResponse } from '../../app/roots/roots-api.ts';
-import type { SessionAdminService } from '../../app/session-admin/session-admin-service.ts';
-import type { SessionRecord, SessionTrashEntry } from '../../domain/session/session-admin.ts';
-/** The one path this plugin claims for session administration. */
-export declare const SESSION_API_PATH = "/api/over-ssh/sessions";
-/** Largest accepted request body. An id list is a few hundred bytes. */
-export declare const SESSION_API_MAX_BODY_BYTES: number;
-/** One accepted `POST` action; anything else is refused with the list. */
-export declare const SESSION_API_ACTIONS: readonly ["delete", "delete-workspace", "restore", "purge", "sweep", "preview"];
-/** One accepted action. */
-export type SessionApiAction = (typeof SESSION_API_ACTIONS)[number];
-/** One inventory row as the wire carries it (a field-by-field projection, never the record itself). */
-export interface SessionRow {
-    readonly id: string;
-    readonly classification: 'normal' | 'subsession' | 'unreadable';
-    readonly parentSessionId?: string;
-    readonly title?: string;
-    readonly cwd?: string;
-    /** Display title of the workspace owning `cwd`; absent when no registered workspace owns it. */
-    readonly workspaceTitle?: string;
-    readonly bytes: number;
-    readonly updatedAtMs: number;
-    /**
-     * The host holds this session in its store: it was opened in this DSH process.
-     *
-     * Not a running state — see {@link running}. The panel renders it as 已打开.
-     */
-    readonly live: boolean;
-    /** The session's agent is running a turn right now (the platform's own "运行中" signal). */
-    readonly running: boolean;
-}
-/** One bin row as the wire carries it. */
-export interface SessionBinRow {
-    readonly entryId: string;
-    readonly sessionId: string;
-    readonly title?: string;
-    readonly bytes: number;
-    readonly deletedAtMs: number;
-    readonly movedBy: 'rename' | 'copy';
-    readonly confirmedBy?: string;
-}
-/** The seams the route needs. */
-export interface SessionApiDeps {
-    /** The session administration service (or a getter, since services can appear after activation). */
-    readonly service: () => SessionAdminService | undefined;
-    /** Retention limits used by `sweep`, from configuration. */
-    readonly policy: () => {
-        readonly maxEntries: number;
-        readonly maxBytes: number;
-        readonly maxAgeMs: number;
-    };
-    /** Injected clock, so a test can pin `sweep`'s "now". */
-    readonly now?: () => number;
-}
-/** The handler pair the entry registers. */
-export interface SessionApi {
-    readonly handle: (req: RootsApiRequest, res: RootsApiResponse) => Promise<void>;
-    dispose(): void;
-}
-/** Project one inventory record to the wire shape. */
-export declare function toSessionRow(record: SessionRecord): SessionRow;
-/** Project one bin entry to the wire shape. */
-export declare function toSessionBinRow(entry: SessionTrashEntry): SessionBinRow;
-/**
- * Build the handler pair.
- *
- * @param deps - injected seams.
- * @returns `handle` plus a no-op `dispose`.
- */
-export declare function createSessionApi(deps: SessionApiDeps): SessionApi;
-//# sourceMappingURL=session-api.d.ts.map

package/lib/types/src/host/integration/session/session-bin-lock.d.ts

@@ -1,80 +0,0 @@
-/**
- * A cross-process advisory lock for the session recycle-bin index.
- *
- * Why this exists: the in-process promise chain in `session-admin-service.ts` cannot see **another DSH
- * process**. Two processes deleting a session at the same time can each read the old index and then each
- * write back their own version, so one entry is lost — and a lost entry is not a cosmetic problem: the
- * moved bytes stay on disk while the index does not mention them, making them invisible *and* unrestorable.
- *
- * ## Design
- *
- * A lock file created with `wx` (exclusive create) is the mutual exclusion primitive: the filesystem
- * guarantees exactly one creator wins, on local and network filesystems alike, without any dependency.
- * The file records `{ pid, host, acquiredAtMs }` so a human can see who holds it.
- *
- * **Stale locks are reclaimed by age.** A process that dies while holding the lock leaves the file behind;
- * without reclamation every later deletion would fail forever. The threshold is deliberately generous
- * (see {@link DEFAULT_STALE_LOCK_MS}) because reclaiming a *live* holder's lock is worse than waiting: it
- * reintroduces exactly the race this module prevents.
- *
- * This is advisory, not a guarantee: it coordinates cooperating processes of this plugin, and does not
- * protect the bin from a process that ignores the protocol.
- *
- * @module dsh-over-ssh/integration/session-bin-lock
- */
-/** How long a lock may sit before another process may reclaim it. */
-export declare const DEFAULT_STALE_LOCK_MS = 60000;
-/** How long to wait between acquisition attempts. */
-export declare const DEFAULT_LOCK_RETRY_MS = 25;
-/** How long to keep trying before giving up and reporting contention. */
-export declare const DEFAULT_LOCK_TIMEOUT_MS = 30000;
-/** Options for {@link createSessionBinLock}. */
-export interface SessionBinLockOptions {
-    /** Lock file path. */
-    readonly path: string;
-    /** Stale threshold; non-positive disables reclamation (waiting forever is then the caller's risk). */
-    readonly staleMs?: number;
-    readonly retryMs?: number;
-    readonly timeoutMs?: number;
-    /** Injected sleep so tests need no real waiting. */
-    readonly sleep?: (ms: number) => Promise<void>;
-    /** Injected clock. */
-    readonly now?: () => number;
-    /** Identity recorded in the lock file (defaults to pid/host). */
-    readonly owner?: string;
-    /** Called when a stale lock is reclaimed, so the event is observable instead of silent. */
-    readonly onReclaim?: (event: {
-        readonly path: string;
-        readonly ageMs: number;
-        readonly holder: Partial<SessionBinLockRecord>;
-    }) => void;
-}
-/** What one lock file records. */
-export interface SessionBinLockRecord {
-    readonly pid: number;
-    readonly host: string;
-    readonly acquiredAtMs: number;
-    /** Human-readable holder, for diagnosis (see `onReclaim`). **Not** used for ownership checks. */
-    readonly owner?: string;
-    /**
-     * Per-acquisition ownership token, compared before release.
-     *
-     * Separate from `owner` on purpose: `owner` is documented as a **diagnostic** field and is asserted as
-     * such by `tests/session-bin-lock.test.ts`; overloading it with a token would change what a reader of
-     * the lock file sees. This field exists only so a holder whose lock was reclaimed cannot delete its
-     * successor's lock.
-     */
-    readonly token?: string;
-}
-/**
- * Run one operation under the cross-process lock.
- *
- * @param options - lock file path plus timing knobs.
- * @returns a `withLock(key, operation)` function; `key` is accepted for interface compatibility and is not
- *   used to derive the path (there is exactly one session-bin index).
- */
-export declare function createSessionBinLock(options: SessionBinLockOptions): {
-    withLock: <T>(_key: string, operation: () => Promise<T>) => Promise<T>;
-    lockPath: string;
-};
-//# sourceMappingURL=session-bin-lock.d.ts.map

package/lib/types/src/host/integration/session/session-header.d.ts

@@ -1,151 +0,0 @@
-/**
- * Read a session log's header line, with a **bounded** memory footprint.
- *
- * Why this is its own module: the reader used to live in the composition root (`src/index.ts`), where no
- * test can reach it (审计 0046 记录了同款教训). A file-system reader is exactly the kind of code that needs a
- * test to pin its *bounds*, and the bound is the whole point here.
- *
- * ## What went wrong before
- *
- * The old reader claimed to "decompress only the head" but read the **whole file** first:
- *
- * ```ts
- * const handle = await readFile(path);                                    // 10.9 MiB for one real session
- * text = zstdDecompressSync(handle.subarray(0, 256 * 1024)).toString();   // cap applies to the SLICE only
- * } catch {
- *   text = zstdDecompressSync(await readFile(path)).toString();           // and the fallback reads it AGAIN
- * }
- * ```
- *
- * `readFile` has no `maxBytes`, so the 256 KiB constant bounded the decompressor's *input*, never the read.
- * Measured on the reference machine's real store (73 sessions): **105.3 MiB** read into memory to extract
- * 73 first lines (19 KiB of output), worst single session **10.9 MiB**, and 51 of 73 logs exceeded the
- * "cap" that was supposedly in force. See `doc/06-audits/0050`.
- *
- * ## What went wrong the second time (2026-10-31)
- *
- * The fallback decompressed the head with `zstdDecompressSync`, which requires a **complete frame** and answers
- * `Z_BUF_ERROR` for anything shorter. That was true of the store it was written against (one small frame per
- * record) and is **not** true of the current one: a 13.2 MB session compresses its head into a frame far larger
- * than any bounded read, so no cap could ever be "complete". Measured on this machine's real store: 8 of 19
- * sessions in one workspace were classified `unreadable`, and every one had an intact header line — 64 KiB of a
- * 13.2 MB log stream-decodes to 184 KB of text whose first line is the header. Users saw it as
- * 「该会话无法读取，不能删除」 on a perfectly healthy session.
- *
- * The fix is to decode **incrementally**: feed the bounded prefix to a stream decoder, keep the output until the
- * first newline, then stop. A truncated frame ending in an `error` event is the normal case here.
- *
- * ## The contract this module implements
- *
- *  1. **Never read more than `cap` bytes of any one file.** The read is a positioned `read(2)` off a
- *     descriptor, so the file's size is irrelevant to peak memory.
- *  2. **The fallback is bounded too.** A slice that ends inside a zstd frame can be rejected by the
- *     decoder; the retry asks for a larger head (`retryBytes`), never for the whole file.
- *  3. **Failure is `undefined`, never a throw.** A directory with no log, a corrupt frame, or an
- *     unparsable first line all yield `undefined`, so the inventory classifies the session as
- *     `unreadable` instead of guessing from the lossy directory name (ADR-0009).
- *
- * @module dsh-over-ssh/integration/session-header
- */
-import type { SessionHeader } from '../../app/session-admin/session-admin-service.ts';
-/**
- * Bytes read from the head of a session log on the first attempt.
- *
- * Chosen from measurement, not taste. On the reference machine's real store (73 sessions, `0050`):
- *
- *  - the largest **header line** is **309 B** of UTF-8 (p50 279 B);
- *  - the largest compressed frame carrying a lone header is **253 B**;
- *  - the smallest head that recovered **all 73** headers is **4 KiB**.
- *
- * 64 KiB is therefore **16x** the empirically sufficient head and **212x** the largest header line, while
- * being 4x smaller than the previous (and, as it turned out, entirely non-binding) 256 KiB constant.
- */
-export declare const SESSION_HEADER_READ_BYTES: number;
-/**
- * Bytes read on the retry, when the first slice ended inside the frame.
- *
- * Still bounded, and still independent of the file's real size — that is the property the old fallback
- * broke. A log whose header genuinely cannot be recovered from 1 MiB is reported `unreadable`.
- */
-export declare const SESSION_HEADER_RETRY_BYTES: number;
-/** The I/O this reader needs; injected so a test can pin the byte bounds exactly (AGENTS.md 红线 3). */
-export interface SessionHeaderIo {
-    /** List one directory's entry names. */
-    readonly listDir: (dir: string) => Promise<readonly string[]>;
-    /**
-     * Read at most `maxBytes` from the **head** of one file.
-     *
-     * An implementation must not read the whole file and slice: that is precisely the defect this module
-     * exists to prevent. It may return fewer bytes (a short file, or a short read).
-     */
-    readonly readHead: (path: string, maxBytes: number) => Promise<Uint8Array>;
-    /**
-     * Decompress a zstd frame **or frame prefix** to UTF-8 text.
-     *
-     * May be async: a prefix has to be decoded incrementally (see {@link decompressPrefix}), and a partial frame
-     * is expected rather than exceptional.
-     */
-    readonly decompress: (bytes: Uint8Array) => string | Promise<string>;
-    /** Head caps to try, in order. Defaults to `[SESSION_HEADER_READ_BYTES, SESSION_HEADER_RETRY_BYTES]`. */
-    readonly caps?: readonly number[];
-}
-/**
- * Parse the first JSONL line into the header fields this feature needs.
- *
- * @param text - decompressed log text (only the head is present).
- * @returns the header, or `undefined` when the first line is absent or not a session record.
- */
-export declare function parseSessionHeaderLine(text: string): SessionHeader | undefined;
-/**
- * Build the header reader.
- *
- * Every failure is reported as `undefined` rather than thrown: an inventory must survive one unreadable
- * session.
- *
- * @param io - directory listing, bounded head read and decompressor.
- * @returns a reader from one session directory to its header, or `undefined` when unreadable.
- */
-export declare function createSessionHeaderReader(io: SessionHeaderIo): (dir: string) => Promise<SessionHeader | undefined>;
-/**
- * Decode a zstd frame **prefix** to text, stopping at the first complete line.
- *
- * Why not `zstdDecompressSync`: it requires a complete frame and answers `Z_BUF_ERROR` for a prefix. The current
- * session store writes frames far larger than any bounded read, so every such log was classified `unreadable`
- * (see the module note). The stream decoder emits what it can from the prefix it was given; a truncated frame
- * ends in an `error` event with the partial output already delivered, which is the **normal** case here.
- *
- * Bounded on purpose: collection stops at the first newline (the header is one line) and the stream is
- * destroyed, so decoding a 13 MB log's head never materialises the body.
- *
- * @param bytes - the bounded head read from the log.
- * @returns the decoded text (possibly a prefix, possibly empty), never a throw.
- */
-export declare function decompressPrefix(bytes: Uint8Array): Promise<string>;
-/**
- * Read at most `maxBytes` from the head of a file, off a descriptor.
- *
- * A positioned read is what makes the bound real: `readFile` would materialise the entire log first.
- *
- * @param path - file to read.
- * @param maxBytes - hard ceiling on the bytes returned.
- * @returns the bytes actually read (possibly fewer, possibly none).
- */
-export declare function readHeadFromDisk(path: string, maxBytes: number): Promise<Uint8Array>;
-/**
- * The production I/O: real `readdir`, a **bounded** head read and the real zstd decoder.
- *
- * Exported so a test can pin the one property the reader's whole contract rests on — that the production
- * `readHead` respects its cap. Exercising the assembled reader through an *injected* fake cannot catch a
- * regression in this wiring, because the fake stays bounded either way; a mutation experiment during
- * audit 0050 exposed exactly that gap.
- *
- * @returns the production I/O bundle.
- */
-export declare function createDiskSessionHeaderIo(): SessionHeaderIo;
-/**
- * The production reader: real `readdir`, a bounded head read and the real zstd decoder.
- *
- * @returns a reader from one session directory to its header, or `undefined` when unreadable.
- */
-export declare function createDiskSessionHeaderReader(): (dir: string) => Promise<SessionHeader | undefined>;
-//# sourceMappingURL=session-header.d.ts.map

package/lib/types/src/host/integration/session/session-labels.d.ts

@@ -1,56 +0,0 @@
-/**
- * Resolve the two human labels a session listing needs: the session's own title and the display name of the
- * workspace that owns its directory.
- *
- * Both live in **optional platform services**, and both are read through a structural context shape rather
- * than a Cordis import, so this module is unit-testable with a plain object and the domain layer keeps its
- * no-`@deepseek-ai/*` rule.
- *
- * Why this is its own module: these are the only two places where the session feature reaches into the
- * platform, and the composition root that calls them cannot be exercised by a test. Anything decision-like
- * that lands there is untested by construction (审计 0046 记录了同款教训), so the decisions live here.
- *
- * @module dsh-over-ssh/integration/session-labels
- */
-import type { SessionHeader } from '../../app/session-admin/session-admin-service.ts';
-/** The one context method these resolvers need, kept structural so no Cordis import is required. */
-export interface OptionalServiceLookup {
-    get(name: string): unknown;
-}
-/**
- * Resolve a session's generated title through the platform's projection cache.
- *
- * The title is a **projection**, never header metadata: the header's own `title` field is always absent (all
- * 88 sessions on the reference machine had none), which is why the panel could only ever show a uuid. The
- * cache is the sanctioned zero-I/O listing read — `cachedSnapshot` validates the stored row against the
- * header's lifecycle identity (`formatVersion`, `createdAt`, `cwd`, `isSeeded`), so a title from a different
- * lifecycle that reused the same id can never be served.
- *
- * Every failure is benign and yields `undefined`: a session persisted before the cache was composed has no
- * row until it is opened once, and the row's unit version must match the live title projection. The caller
- * then falls back to the workspace, and finally to the id.
- *
- * The service is looked up **per call**, not once at activation: on this runtime an optional service can
- * still be absent while a plugin entry activates (`session-route-wiring.ts` documents the same trap for
- * `webServer`), and a one-time check would then disable titles for the whole process lifetime.
- *
- * @param ctx - anything with cordis's `get`; usually the plugin context.
- * @returns a resolver from header to title; it yields `undefined` whenever the service or the row is absent.
- */
-export declare function createSessionTitleResolver(ctx: OptionalServiceLookup): (header: SessionHeader) => string | undefined;
-/**
- * Resolve a `cwd` to its registered workspace's display title.
- *
- * The registry is the platform's own durable mapping from directory to a human name (`libaw_vep`,
- * `a733_android13`), which is exactly the label a session list needs and the one the sidebar shows. A
- * directory no workspace owns yields `undefined`; the client then uses the path's leaf name, so a session
- * outside a workspace is still identifiable.
- *
- * Like {@link createSessionTitleResolver}, the service is looked up **per call** so a late-arriving registry
- * still works.
- *
- * @param ctx - anything with cordis's `get`; usually the plugin context.
- * @returns a resolver from `cwd` to workspace title; it yields `undefined` whenever none applies.
- */
-export declare function createWorkspaceTitleResolver(ctx: OptionalServiceLookup): (cwd: string | undefined) => string | undefined;
-//# sourceMappingURL=session-labels.d.ts.map

package/lib/types/src/host/integration/session/session-route-wiring.d.ts

@@ -1,50 +0,0 @@
-/**
- * Own the session-administration route (`/api/over-ssh/sessions`) on the browser carrier.
- *
- * This is the same **deferred carrier** dance as `roots-wiring.ts`, and for the same measured reason: on the
- * packaged 0.2.0-rc.2 runtime `ctx.get('webServer')` is `undefined` while a plugin entry activates (the
- * carrier row is constructed later), so a `ctx.get` lookup silently skips registration and every request
- * answers `http-404` from the SPA fallback while the plugin looks perfectly healthy.
- * `ctx.inject(['webServer'], ...)` resolves the service when it appears.
- *
- * A profile without a carrier (headless) is **not** an error: the plugin works, the panel simply has no
- * session data channel. The reason is collected as a warning the entry logs once `ctx.logger` resolves.
- *
- * @module dsh-over-ssh/integration/session-route-wiring
- */
-import { type SessionApi, type SessionApiDeps } from './session-api.ts';
-/** The browser HTTP carrier, narrowed to the one method this wiring calls. */
-export interface SessionRouteHost {
-    register(route: {
-        readonly kind: 'exact';
-        readonly path: string;
-        readonly handler: (req: never, res: never) => Promise<void>;
-    }): () => void;
-}
-/** The provider that hands out the carrier once it exists. */
-export interface SessionRouteHostProvider {
-    inject(names: readonly string[], callback: (scoped: {
-        get(name: string): unknown;
-    }) => void | (() => void)): unknown;
-}
-/** Everything the wiring needs from the entry. */
-export interface SessionRouteWiringDeps extends SessionApiDeps {
-    readonly webServerProvider?: SessionRouteHostProvider | undefined;
-}
-/** What the entry holds on to. */
-export interface SessionRouteWiring {
-    readonly api: SessionApi;
-    /** Human-readable reasons the route may not be live; logged after activation. */
-    readonly routeWarnings: () => readonly string[];
-    /** Whether the deferred carrier callback ever ran. */
-    readonly injectRan: () => boolean;
-    readonly dispose: () => void;
-}
-/**
- * Register the route as soon as the carrier exists, and again if it ever comes back.
- *
- * @param deps - the API seams plus the carrier provider.
- * @returns the wiring handle.
- */
-export declare function createSessionRouteWiring(deps: SessionRouteWiringDeps): SessionRouteWiring;
-//# sourceMappingURL=session-route-wiring.d.ts.map

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

@@ -1,236 +0,0 @@
-/**
- * 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 DeleteDecision, type SessionRecord, type SessionTrashEntry, type SessionTrashEntryId } from '../domain/session-admin.ts';
-/** One directory entry as the inventory sees it. */
-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;
-}
-/** 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).
- */
-export declare function createSessionAdminService(deps: SessionAdminDeps): SessionAdminService;
-//# sourceMappingURL=session-admin-service.d.ts.map