@tiphareth/dsh-hardssh 0.1.2-alpha → 0.2.2

package/lib/types/providers/ssh/provider.d.ts

@@ -13,10 +13,11 @@
  *
  * @module @tiphareth/dsh-hardssh/providers/ssh
  */
+import type { Context } from '@deepseek-ai/cordis';
 import type { WorkspaceCapabilityMap, WorkspaceConnection, WorkspaceProvider, WorkspaceProviderManifest } from '../../base/model.ts';
-import type { WorkspaceFileSystem, WorkspaceProcessRuntime, WorkspaceSearchService, WorkspaceStat, WorkspaceTerminalService, WorkspaceDirEntry, WorkspaceSearchHit } from '../../base/capability.ts';
+import type { WorkspaceSearchHit, WorkspaceSearchService } from '../../base/capability.ts';
 import type { SshEngine } from '../../ssh/engine.ts';
-/** The ssh provider manifest. */
+/** The ssh provider manifest (provider API v2, no separate terminal capability — terminals live on `workspace.process`). */
 export declare const sshProviderManifest: WorkspaceProviderManifest;
 /** One open SSH workspace connection. */
 export declare class SshWorkspaceConnection implements WorkspaceConnection {
@@ -24,73 +25,35 @@ export declare class SshWorkspaceConnection implements WorkspaceConnection {
     private readonly engine;
     private readonly alias;
     private readonly remoteRoot;
+    private readonly cordisContext;
     readonly providerId = "ssh";
-    constructor(workspaceId: string, engine: SshEngine, alias: string, remoteRoot: string);
+    private state;
+    private fsInstance;
+    private processInstance;
+    private searchInstance;
+    /** One workspace is one fixed remote execution world for every capability instance. */
+    private readonly stateOf;
+    constructor(workspaceId: string, engine: SshEngine, alias: string, remoteRoot: string, cordisContext: Context);
     get<K extends keyof WorkspaceCapabilityMap>(capability: K): WorkspaceCapabilityMap[K] | undefined;
     private fs;
     private process;
-    private terminal;
     private search;
     status(): 'connecting' | 'ready' | 'degraded' | 'closed';
     close(): Promise<void>;
 }
 /** POSIX-join a remote root with a relative path, confining to the root. */
 export declare function joinRemoteRoot(root: string, path: string): string;
-/** Wrap engine FS calls as the generic WorkspaceFileSystem. */
-export declare class SshWorkspaceFileSystem implements WorkspaceFileSystem {
-    private readonly engine;
-    private readonly alias;
-    private readonly root;
-    constructor(engine: SshEngine, alias: string, root: string);
-    private full;
-    stat(path: string, signal?: AbortSignal): Promise<WorkspaceStat | undefined>;
-    list(path: string, signal?: AbortSignal): Promise<WorkspaceDirEntry[]>;
-    readFile(path: string, signal?: AbortSignal): Promise<Uint8Array>;
-    writeFile(path: string, data: Uint8Array, signal?: AbortSignal): Promise<void>;
-    mkdir(path: string, options?: {
-        recursive?: boolean;
-        signal?: AbortSignal;
-    }): Promise<void>;
-    rm(path: string, options?: {
-        recursive?: boolean;
-        signal?: AbortSignal;
-    }): Promise<void>;
-    rename(from: string, to: string, signal?: AbortSignal): Promise<void>;
-}
-/** Wrap engine exec as the generic WorkspaceProcessRuntime. */
-export declare class SshWorkspaceProcess implements WorkspaceProcessRuntime {
-    private readonly engine;
-    private readonly alias;
-    private readonly root;
-    constructor(engine: SshEngine, alias: string, root: string);
-    exec(command: string, options?: {
-        timeoutMs?: number;
-        cwd?: string;
-        signal?: AbortSignal;
-    }): Promise<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        timedOut?: boolean;
-        durationMs?: number;
-    }>;
-    private full;
-}
-/** Wrap engine PTY as the generic WorkspaceTerminalService. */
-export declare class SshWorkspaceTerminal implements WorkspaceTerminalService {
-    private readonly engine;
-    private readonly alias;
-    private readonly root;
-    constructor(engine: SshEngine, alias: string, root: string);
-    openTerminal(cols: number, rows: number): Promise<import('../../base/capability.ts').WorkspaceTerminalHandle>;
-}
-/** Wrap the remote search service as the generic WorkspaceSearchService. */
+/** Wrap the shared RemoteSearchService as the generic WorkspaceSearchService. */
 export declare class SshWorkspaceSearch implements WorkspaceSearchService {
     private readonly engine;
     private readonly alias;
-    private readonly root;
+    private readonly remoteRoot;
     private readonly service;
-    constructor(engine: SshEngine, alias: string, root: string);
+    constructor(engine: SshEngine, alias: string, remoteRoot: string);
+    /** Workspace-relative POSIX search base → absolute remote root. */
+    private searchBase;
+    /** Absolute path → path relative to `base`, or undefined when outside it. */
+    private relativeTo;
     glob(pattern: string, options?: {
         root?: string;
         maxDepth?: number;
@@ -106,7 +69,11 @@ export declare class SshWorkspaceSearch implements WorkspaceSearchService {
         hits: WorkspaceSearchHit[];
         truncated: boolean;
     }>;
+    /** Depth of a base-relative path (root-level entries are depth 1, find -maxdepth style). */
+    private depthOf;
 }
-/** The ssh provider factory. */
-export declare function createSshWorkspaceProvider(engine: SshEngine): WorkspaceProvider;
+/** The ssh provider factory. `context` is mandatory: the provider serves only
+ *  the real DSH FileSystem/SubprocessRuntime capabilities, which need a Cordis
+ *  scope to isolate each workspace's resources. */
+export declare function createSshWorkspaceProvider(engine: SshEngine, context: Context): WorkspaceProvider;
 //# sourceMappingURL=provider.d.ts.map

package/lib/types/remote/environment.d.ts

@@ -24,6 +24,8 @@ export declare function invalidateRemoteEnvironment(engine: SshEngine, alias: st
 export declare function scrubRemoteEnvironment(environment: ReadonlyMap<string, string>): Map<string, string>;
 /**
  * Overlay explicit entries and serialize one validated environment for `env -i`.
+ * Login-critical names are emitted first (see CRITICAL_ENV_ORDER); everything
+ * else keeps the remote's own order.
  */
 export declare function serializeEnvironment(scrubbed: ReadonlyMap<string, string>, explicit: Readonly<NodeJS.ProcessEnv> | undefined): string;
 //# sourceMappingURL=environment.d.ts.map

package/lib/types/remote/remote-fs.d.ts

@@ -14,6 +14,8 @@ import type { SshEngine } from '../ssh/engine.ts';
 import { FileSystem, FsVersion } from '@deepseek-ai/dsh-fs';
 import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsWriteIntent, FsWriteOutcome } from '@deepseek-ai/dsh-fs';
 import type { WorkspaceState } from '../protocol.ts';
+/** Decode a base64-wrapped NUL-terminated canonical path from `realpath -mz`. */
+export declare function decodeCanonicalPath(encoded: string): string;
 /**
  * Remote filesystem backend over the dsh-ssh engine. The working directory
  * follows the mode store: relative paths resolve against the resolved remote
@@ -24,7 +26,15 @@ export declare class SshFileSystem extends FileSystem {
     private readonly engine;
     private readonly getState;
     private readonly locks;
-    constructor(ctx: Context, engine: SshEngine, getState: () => WorkspaceState);
+    /** When set, every resolved target must stay under this root (the SSH
+     *  workspace's `location.root`). Absent for the legacy/global SSH seam,
+     *  which intentionally addresses the whole host. */
+    private readonly confineRoot;
+    constructor(ctx: Context, engine: SshEngine, getState: () => WorkspaceState, confineRoot?: string);
+    /** Root-confinement gate for the workspace capability: reject any canonical
+     *  path that escapes `confineRoot` (including via an in-root symlink whose
+     *  realpath lands outside). Mirrors the local provider's fail-closed rule. */
+    private confine;
     /** The active remote execution world (throws when not in remote mode). */
     private current;
     /**
@@ -53,6 +63,7 @@ export declare class SshFileSystem extends FileSystem {
         version: ReturnType<typeof FsVersion>;
     }, signal?: AbortSignal): Promise<FsEditOutcome>;
     private withLock;
+    private canonicalTarget;
     private canonicalPath;
     private probe;
     private requireRegular;

package/lib/types/remote/remote-process.d.ts

@@ -22,7 +22,13 @@ export declare class SshSubprocessHandle implements SubprocessHandle {
     private readonly stdoutCollector;
     private readonly stderrCollector;
     private session;
+    private inputSink;
+    private inputErrorListener;
+    private terminationPhase;
     private graceTimer;
+    private forceTimer;
+    private resolveForced;
+    private forceClosed;
     private settled;
     constructor(engine: SshEngine, getState: () => WorkspaceState, spec: SubprocessSpawnSpec, spillDir: string);
     /** Remote process id; `-1` because the SSH channel does not expose one. */
@@ -32,9 +38,24 @@ export declare class SshSubprocessHandle implements SubprocessHandle {
     /** @inheritdoc */
     waitForExit(signal?: AbortSignal): Promise<boolean>;
     private readonly onAbort;
-    private signalTerm;
+    private signalCurrentPhase;
+    private startTermination;
+    /** Immediately close the owned channel and settle `done`, including while
+     * openExec is still pending. A late-opened channel observes forceClosed and
+     * closes itself before any stream wiring is installed. */
+    forceClose(): void;
     private settle;
     private run;
+    /** Install every callback under one ownership boundary. Any synchronous
+     * wiring failure or async stdin sink failure closes the established session
+     * and rejects the handle instead of leaking it. */
+    private runSession;
+    /** Route one stream through the engine's leak guard before it reaches the
+     *  consumer. Without this, a remote `bash`/subprocess channel bypassed the
+     *  redaction that every exec/cluster result already applies. Redaction is
+     *  exact-match over known secrets, so it is best-effort and may change byte
+     *  length — the same trade-off the PTY route documents. */
+    private redactBytes;
     private wireStdout;
     private wireStderr;
 }

package/lib/types/remote/remote-subprocess.d.ts

@@ -11,6 +11,9 @@ import type { SshEngine } from '../ssh/engine.ts';
 import { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
 import type { SubprocessHandle, SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
 import type { WorkspaceState } from '../protocol.ts';
+/** Hard upper bound for plugin/workspace teardown, independent of a caller's
+ * potentially very large per-process TERM/KILL grace setting. */
+export declare const SUBPROCESS_DISPOSE_DEADLINE_MS = 5000;
 /** SSH command manager registered as `ctx.subprocess` (remote mode). */
 export declare class SshSubprocessRuntime extends SubprocessRuntime {
     private readonly engine;
@@ -18,8 +21,17 @@ export declare class SshSubprocessRuntime extends SubprocessRuntime {
     private readonly live;
     private readonly terminals;
     private readonly spillDir;
-    private disposing;
+    private closePromise;
     constructor(ctx: Context, engine: SshEngine, getState: () => WorkspaceState);
+    /**
+     * Public idempotent close that releases every workspace-owned live process
+     * and terminal. The ctx.effect teardown cannot be invoked by a workspace
+     * connection (it only runs when the cordis scope disposes, which would also
+     * tear down the shared engine's scope), so a SshWorkspaceConnection calls
+     * this on-demand close() instead — the engine pool itself stays untouched.
+     */
+    close(): Promise<void>;
+    private closeOwnedResources;
     /** @inheritdoc */
     resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
     /** @inheritdoc */

package/lib/types/remote/remote-terminal.d.ts

@@ -30,6 +30,10 @@ export declare class SshTerminalHandle implements SubprocessTerminalHandle {
     signalForeground(_signal: SubprocessTerminalSignal): Promise<number>;
     /** @inheritdoc */
     terminate(): Promise<void>;
+    /** Immediately release the channel when the owning runtime's independent
+     * disposal deadline expires. This also settles output/done if ssh2 never
+     * reports a terminal exit after close(). */
+    forceClose(): void;
     private signal;
     private closeOnce;
 }

package/lib/types/remote-search.d.ts

@@ -41,10 +41,10 @@ export declare class RemoteSearchService {
     private readonly engine;
     constructor(engine: SshEngine);
     /** Literal file-name search under `root` (skips node_modules/.git). */
-    searchNames(target: SearchTarget, query: string): Promise<RemoteNameSearch>;
+    searchNames(target: SearchTarget, query: string, signal?: AbortSignal): Promise<RemoteNameSearch>;
     /** Glob search (pattern keeps glob semantics; `**` crosses directories). */
-    glob(target: SearchTarget, pattern: string): Promise<RemoteGlobResult>;
+    glob(target: SearchTarget, pattern: string, signal?: AbortSignal): Promise<RemoteGlobResult>;
     /** Fixed-string grep (literal pattern, `-F`; NUL file boundary `-Z`). */
-    grepFixed(target: SearchTarget, pattern: string): Promise<RemoteGrepResult>;
+    grepFixed(target: SearchTarget, pattern: string, signal?: AbortSignal): Promise<RemoteGrepResult>;
 }
 //# sourceMappingURL=remote-search.d.ts.map

package/lib/types/routes.d.ts

@@ -1,24 +1,52 @@
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import { type SshEngine } from './ssh/engine.ts';
-import type { SshWorkspaceLedger } from './ledger.ts';
-import { type WorkspaceFileService } from './backend.ts';
+import type { WorkspaceStoreView } from './backend.ts';
+/** One record whose host-workspace (re)registration failed. */
+export interface HostWorkspaceReconcileFailure {
+    id: string;
+    error: string;
+}
+/** Result of replaying host-workspace registration for every stored record. */
+export interface HostWorkspaceReconcileReport {
+    registered: number;
+    failures: HostWorkspaceReconcileFailure[];
+    /** Set when the record source itself could not be listed (startup path
+     *  tolerates it; the route surfaces it as an I/O failure). */
+    listError?: string;
+}
+/** Registration replay dependencies (the route and the startup path share it). */
+export interface HostWorkspaceReconcileDeps {
+    workspaces: WorkspaceStoreView;
+    registerHostWorkspace?: (anchorPath: string, title: string) => Promise<void>;
+}
+/**
+ * Replay host-workspace registration for every stored record. Registration
+ * happens only on create/delete, so a process restart (or a registration that
+ * failed before compensation existed) leaves records whose sidebar entry is
+ * missing; `registerHostWorkspace` is create-if-missing, so this is the
+ * idempotent startup/retry compensation. Per-record failures are reported and
+ * never thrown: a broken host registry must not break plugin startup.
+ *
+ * Shared by the `/reconcile` route and the boot path so the two halves cannot
+ * drift.
+ */
+export declare function reconcileHostWorkspaces(deps: HostWorkspaceReconcileDeps): Promise<HostWorkspaceReconcileReport>;
 /** Route family dependencies. */
 export interface WorkspaceRoutesDeps {
     /** Read-only host surface (list only; the SSH routes own the write path). */
     hosts: import('./core.ts').HostStoreView;
     engine: SshEngine;
-    ledger: SshWorkspaceLedger;
-    /** Gated workspace file service (tree / file / search). */
-    files: WorkspaceFileService;
+    /** SSH-workspace record source: the generic WorkspaceCore-backed
+     *  projection store (the only runtime). */
+    workspaces: WorkspaceStoreView;
     /** Register the anchor dir as a HOST workspace (sidebar visibility). */
     registerHostWorkspace?: (anchorPath: string, title: string) => Promise<void>;
     /** Drop the host workspace registration for an anchor dir. */
     unregisterHostWorkspace?: (anchorPath: string) => Promise<void>;
 }
 /**
- * Build every /api/dsh-hardssh route.
- * @param deps - host store (alias listing), ssh engine, workspace ledger, file service.
- * @returns the routes to register.
+ * Build every /api/dsh-hardssh route (workspace CRUD + remote directory
+ * browsing for the picker; the per-workspace file surface was removed).
  */
 export declare function makeRoutes(deps: WorkspaceRoutesDeps): WebRoute[];
 //# sourceMappingURL=routes.d.ts.map

package/lib/types/runtime/dsh-capabilities.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The sole DSH runtime augmentation point for generic workspace capabilities.
+ * The platform-neutral model cannot name these runtime services itself.
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+import type { WorkspaceSearchService } from '../base/capability.ts';
+/** DSH's official workspace capability bindings; no terminal key exists because process owns terminals. */
+export interface DshWorkspaceCapabilityMap {
+    'workspace.fs': FileSystem;
+    'workspace.process': SubprocessRuntime;
+    'workspace.search': WorkspaceSearchService;
+}
+declare module '../base/model.ts' {
+    interface WorkspaceCapabilityMap extends DshWorkspaceCapabilityMap {
+    }
+}
+//# sourceMappingURL=dsh-capabilities.d.ts.map

package/lib/types/runtime/workspace-core.d.ts

@@ -1,56 +1,91 @@
 /**
- * Runtime bridge: exposes the generic workspace base (ledger, provider
- * registry, router, plugin host) as a cordis service under the canonical
- * `workspaceCore` name, while keeping the legacy `hardsshCore` /
- * `sshWorkspaceCore` aliases pointing at the same instances so existing
- * consumers keep working.
- *
- * This module is the DSH boundary: it imports the base (provider-agnostic)
- * and the legacy SSH modules, but the base itself never imports this
- * module — direction of dependency stays base ← runtime.
- *
- * @module @tiphareth/dsh-hardssh/runtime/workspace-core
+ * High-level generic WorkspaceCore runtime boundary. The generic core is the
+ * ONLY production workspace runtime: it owns the ledger, the record CRUD, and
+ * the provider routing used by the fs/subprocess seams, the workspace routes,
+ * the `remote_*` agent tools, and the SSH host-delete guard. Mounting is
+ * side-effect-free until `initialize()` runs, which the plugin boot does
+ * explicitly.
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { WorkspaceProviderRegistry, type WorkspaceRegistry } from '../base/registry.ts';
-import type { WorkspaceRecord } from '../base/model.ts';
+import type { LedgerListener, WorkspaceLedger as WorkspaceLedgerType } from '../base/ledger.ts';
 import { WorkspaceLedger } from '../base/ledger.ts';
-import type { SshEngine } from '../ssh/engine.ts';
-import type { HostStoreView } from '../core.ts';
-import type { SshWorkspaceLedger } from '../ledger.ts';
-import type { SshWorkspaceRecord } from '../protocol.ts';
 import { LedgerWorkspaceRouter } from '../base/ledger-router.ts';
-/** The canonical workspace-core service shape. */
+import type { WorkspaceConnection, WorkspaceCreateInput, WorkspaceId, WorkspaceProvider, WorkspaceRecord, WorkspaceUpdate } from '../base/model.ts';
+import { WorkspaceProviderRegistry, type WorkspaceRegistry } from '../base/registry.ts';
+import type { HostStoreView } from '../core.ts';
+import type { SshEngine } from '../ssh/engine.ts';
+import './dsh-capabilities.ts';
+export type WorkspaceListener = LedgerListener;
+/** Canonical high-level workspace consumer surface. */
 export interface WorkspaceCore {
-    /** Generic ledger (WorkspaceRecord CRUD + anchor index). */
-    ledger: WorkspaceLedger;
-    /** Provider registry (local/ssh/builtin + third-party). */
-    providers: WorkspaceProviderRegistry;
-    /** Ledger+provider router for the switch facades. */
-    router: LedgerWorkspaceRouter;
-    /** Registry surface exposed to plugins. */
-    registry: WorkspaceRegistry;
-    /** Map a legacy SSH record into a generic WorkspaceRecord. */
-    fromSshRecord(record: SshWorkspaceRecord): WorkspaceRecord;
+    initialize(): Promise<void>;
+    isReady(): boolean;
+    whenReady(): Promise<void>;
+    list(): Promise<WorkspaceRecord[]>;
+    get(id: WorkspaceId): Promise<WorkspaceRecord | undefined>;
+    findByAnchor(path: string): Promise<WorkspaceRecord | undefined>;
+    openById(id: WorkspaceId, signal?: AbortSignal): Promise<WorkspaceConnection | undefined>;
+    openByAnchor(path: string, signal?: AbortSignal): Promise<WorkspaceConnection | undefined>;
+    create(input: WorkspaceCreateInput): Promise<WorkspaceRecord>;
+    update(id: WorkspaceId, patch: WorkspaceUpdate): Promise<WorkspaceRecord | undefined>;
+    remove(id: WorkspaceId): Promise<boolean>;
+    subscribe(listener: WorkspaceListener): () => void;
+    registerProvider(provider: WorkspaceProvider): () => void;
+    closeAll(): Promise<void>;
+    /** @deprecated Internal compatibility surface; ordinary consumers use high-level methods. */
+    readonly ledger: WorkspaceLedger;
+    /** @deprecated Internal compatibility surface; ordinary consumers use registerProvider(). */
+    readonly providers: WorkspaceProviderRegistry;
+    /** @deprecated Internal compatibility surface; ordinary consumers use openById/openByAnchor(). */
+    readonly router: LedgerWorkspaceRouter;
+    /** @deprecated Plugin compatibility surface. */
+    readonly registry: WorkspaceRegistry;
+}
+/** mountWorkspaceCore() requires Cordis and builtins, so this class makes the same core testable with injected generic foundations. */
+export declare class DefaultWorkspaceCore implements WorkspaceCore {
+    readonly ledger: WorkspaceLedgerType;
+    readonly providers: WorkspaceProviderRegistry;
+    readonly router: LedgerWorkspaceRouter;
+    readonly registry: WorkspaceRegistry;
+    constructor(ledger: WorkspaceLedgerType, providers: WorkspaceProviderRegistry, router?: LedgerWorkspaceRouter);
+    /** WorkspaceLedger.load() cannot preopen providers or establish router readiness, so initialize delegates to router initialization. */
+    initialize(): Promise<void>;
+    /** WorkspaceLedger.snapshotSync() cannot prove provider preopen completed, so readiness comes from the router lifecycle. */
+    isReady(): boolean;
+    /** isReady() cannot await a pending or failed initialization, so whenReady delegates to the router promise. */
+    whenReady(): Promise<void>;
+    /** WorkspaceLedger.list() alone may expose records before runtime readiness, so list waits for initialization first. */
+    list(): Promise<WorkspaceRecord[]>;
+    /** WorkspaceLedger.get() alone may run before strict load/preopen, so get waits for initialization first. */
+    get(id: WorkspaceId): Promise<WorkspaceRecord | undefined>;
+    /** WorkspaceLedger.findByAnchor() alone may run before strict load/preopen, so findByAnchor waits for initialization first. */
+    findByAnchor(path: string): Promise<WorkspaceRecord | undefined>;
+    /** LedgerWorkspaceRouter.ensureOpen() requires a record, so openById exposes identity-based opening to consumers. */
+    openById(id: WorkspaceId, signal?: AbortSignal): Promise<WorkspaceConnection | undefined>;
+    /** WorkspaceLedger.findByAnchor() returns data only, so openByAnchor exposes the resolved connection in one operation. */
+    openByAnchor(path: string, signal?: AbortSignal): Promise<WorkspaceConnection | undefined>;
+    /** WorkspaceLedger.create() cannot validate provider-specific references, so create validates before committing the record. */
+    create(input: WorkspaceCreateInput): Promise<WorkspaceRecord>;
+    /** WorkspaceLedger.update() cannot validate a changed provider binding, so update checks the proposed record before commit. */
+    update(id: WorkspaceId, patch: WorkspaceUpdate): Promise<WorkspaceRecord | undefined>;
+    /** WorkspaceLedger.remove() owns persistence while its synchronous change event makes router removal fail closed before this promise returns. */
+    remove(id: WorkspaceId): Promise<boolean>;
+    /** WorkspaceLedger.list() cannot publish later mutations, so subscribe exposes its detached commit stream. */
+    subscribe(listener: WorkspaceListener): () => void;
+    /** WorkspaceProviderRegistry.get() cannot establish disposer ownership, so registerProvider returns the registry-owned disposer. */
+    registerProvider(provider: WorkspaceProvider): () => void;
+    /** WorkspaceConnection.close() only closes one handle, so closeAll delegates complete cached/in-flight teardown to the router. */
+    closeAll(): Promise<void>;
 }
-/** Convert a legacy SSH-bound workspace record into the generic model. */
-export declare function sshRecordToWorkspaceRecord(record: SshWorkspaceRecord): WorkspaceRecord;
 /** Persistence path for the generic ledger (~/.dsh/workspaces/index.v1.json). */
 export declare function genericLedgerPath(): string;
 /** Anchor root for managed generic workspaces (~/.dsh/workspaces/anchors). */
 export declare function genericAnchorRoot(): string;
-/**
- * Build and provide the workspace core on the cordis context: registers the
- * builtin providers, instantiates the generic ledger (persisting under
- * ~/.dsh/workspaces/index.v1.json), constructs the ledger router, and
- * provides `workspaceCore`.
- */
+/** mountWorkspaceCore() cannot register Cordis services or builtin providers, so it performs host assembly (provider registration + `ctx.provide('workspaceCore')`); the boot calls `initialize()` afterwards. */
 export declare function mountWorkspaceCore(ctx: Context, deps: {
     engine?: SshEngine;
     hosts?: HostStoreView;
 }): WorkspaceCore;
-/** The legacy SSH ledger held by the hardssh core (type bridge). */
-export type { SshWorkspaceLedger };
 declare module '@deepseek-ai/cordis' {
     interface Context {
         workspaceCore: WorkspaceCore;

package/lib/types/runtime/workspace-migration.d.ts

@@ -0,0 +1,113 @@
+/** Phase 3 legacy-to-generic conversion and side-effect-free shadow comparison. */
+import { type WorkspaceNamespaceCodec } from '../base/namespace.ts';
+import type { WorkspaceRecord } from '../base/model.ts';
+import type { SshWorkspaceRecord } from '../protocol.ts';
+/**
+ * Which runtime the migration is preparing. The legacy runtime is gone — the
+ * generic core is the ONLY production runtime — so this has a single value; it
+ * stays a named field so the cutover marker and the migration report record
+ * which runtime wrote them.
+ */
+export type WorkspaceRuntimeMode = 'generic';
+export interface WorkspaceMigrationOptions {
+    mode: WorkspaceRuntimeMode;
+    legacyPath: string;
+    genericPath: string;
+    reportPath?: string;
+    now?: () => Date;
+}
+export interface WorkspaceMigrationReport {
+    schemaVersion: 1;
+    mode: WorkspaceRuntimeMode;
+    createdAt: string;
+    status: 'migrated' | 'unchanged';
+    sourceDigest: string;
+    targetDigest: string;
+    recordCount: number;
+    ids: string[];
+    backupPath?: string;
+    differences: string[];
+}
+export interface ShadowCapabilityObservation {
+    providerId: string;
+    manifestCapabilities: readonly string[];
+    availableCapabilities: readonly string[];
+}
+export interface WorkspaceShadowComparisonInput {
+    legacy: readonly SshWorkspaceRecord[];
+    generic: readonly WorkspaceRecord[];
+    anchorProbes?: readonly string[];
+    namespaceProbes?: readonly string[];
+    codec?: WorkspaceNamespaceCodec;
+    capabilities?: readonly ShadowCapabilityObservation[];
+}
+export interface WorkspaceShadowComparisonReport {
+    matches: boolean;
+    differences: string[];
+}
+/** The generic ledger's create() generates identity and time fields, so it cannot preserve a legacy record exactly; this mapper exists to retain the source id/anchor/timestamp verbatim. */
+export declare function legacySshRecordToWorkspaceRecord(record: SshWorkspaceRecord): WorkspaceRecord;
+/** Repeated WorkspaceLedger.create() calls cannot provide an all-or-nothing full-snapshot conversion with one backup. */
+export declare function migrateLegacySshLedger(options: WorkspaceMigrationOptions): Promise<WorkspaceMigrationReport>;
+/** LedgerWorkspaceRouter.fromAnchor() cannot compare detached legacy/generic decisions, and capability get() must not run in shadow. */
+export declare function compareWorkspaceShadow(input: WorkspaceShadowComparisonInput): WorkspaceShadowComparisonReport;
+/** Where a recovered generic ledger came from. */
+export type GenericLedgerRecoverySource = 'last-good' | 'backup' | 'legacy';
+/** Outcome of one missing-ledger recovery attempt. */
+export interface GenericLedgerRecoveryResult {
+    recovered: boolean;
+    source?: GenericLedgerRecoverySource;
+    /** The file the records were restored from (absent for a legacy re-import). */
+    path?: string;
+    /** How many records the restored ledger holds. */
+    recordCount?: number;
+    /** Why recovery failed, when it did. */
+    reason?: string;
+}
+/** Options for {@link recoverGenericLedger}. */
+export interface GenericLedgerRecoveryOptions {
+    /** The missing/unreadable generic ledger target. */
+    genericPath: string;
+    /** The frozen legacy SSH ledger, the last-resort source. */
+    legacyPath: string;
+    /**
+     * Record ids the cutover marker proves existed. A candidate that cannot
+     * produce ALL of them is rejected: recovery must never silently restore a
+     * SMALLER workspace set than the marker recorded — that would look like a
+     * successful recovery while quietly losing workspaces. An empty/absent list
+     * disables the id check (count is still required to be non-zero).
+     */
+    expectedIds?: readonly string[];
+    /** Sink for recovery diagnostics (defaults to console.warn). */
+    log?: (message: string) => void;
+}
+/**
+ * Classify the generic ledger file so the boot can tell "legitimately empty"
+ * (the user deleted every workspace, the file exists with `[]`) from "lost or
+ * damaged" (missing, truncated, or unparseable).
+ *
+ * @param path - the generic ledger path.
+ * @returns the ledger state, never throwing.
+ */
+export declare function inspectGenericLedger(path: string): Promise<'absent' | 'readable' | 'corrupt'>;
+/**
+ * Restore a generic ledger that the cutover marker proves should exist.
+ *
+ * The marker records that a migration committed N workspaces, so a missing or
+ * unreadable ledger is data loss — never a fresh deployment. Recovery is
+ * attempted newest-first: the rolling `.last-good` snapshot, then the newest
+ * `.backup-<timestamp>` left by a ledger replacement, then a re-import from the
+ * frozen legacy source. EVERY candidate must satisfy `expectedIds`; a source
+ * that would restore fewer workspaces than the marker recorded is rejected
+ * rather than accepted as success.
+ *
+ * The legacy tier deliberately migrates WITHOUT a report path: rewriting the
+ * marker there could downgrade it (an empty legacy source produces
+ * `recordCount: 0`) and permanently disarm the gate that asked for this
+ * recovery in the first place.
+ *
+ * @param options - paths, the expected ids, and an optional logger.
+ * @returns which source was used, or `recovered: false` plus the reason.
+ */
+export declare function recoverGenericLedger(options: GenericLedgerRecoveryOptions): Promise<GenericLedgerRecoveryResult>;
+//# sourceMappingURL=workspace-migration.d.ts.map

package/lib/types/ssh/connection/lease.d.ts

@@ -8,9 +8,32 @@ export interface ClientLease {
     readonly generation: number;
     readonly kind: LeaseKind;
     readonly released: boolean;
+    /**
+     * True when this is the only lease on its pooled connection.
+     *
+     * Cancellation uses it to decide the blast radius: retiring the transport is
+     * safe (nobody else is using it) while other holders exist it would destroy
+     * unrelated work on the same alias.
+     */
+    holdsOnlyLease(): boolean;
     /** Mark the underlying connection broken (surfaces to every holder). */
     markBroken(error?: unknown): void;
     /** Idempotent: release this holder's ownership of the connection. */
     release(): void;
 }
+/**
+ * Tie a lease's release to the OPERATION's settlement, not to the caller's
+ * promise.
+ *
+ * Why this exists: `withClient` rejects its caller as soon as an abort arrives,
+ * but the underlying request may keep running (SFTP has no cancel API). If the
+ * lease were released at rejection time, `holdsOnlyLease()` would report "no
+ * other user" while that request was still in flight — and a later abort in a
+ * different session would then close the shared transport underneath it.
+ *
+ * @param lease - the lease owned by this operation.
+ * @param operation - the operation whose settlement frees the lease.
+ * @returns the operation, unchanged, with the release chained to it.
+ */
+export declare function holdLeaseUntilSettled<T>(lease: ClientLease, operation: Promise<T>): Promise<T>;
 //# sourceMappingURL=lease.d.ts.map