@tiphareth/dsh-hardssh 0.1.2

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

@@ -0,0 +1,112 @@
+/**
+ * SSH provider — wraps the SSH engine/host store as a generic
+ * `WorkspaceProvider`, so the workspace base can route SSH-bound workspaces
+ * without knowing anything about ssh2. This is the concrete "provider-ssh"
+ * layer: everything SSH lives here (or in the legacy ./ssh, ./remote
+ * modules it adapts), and the base + runtime never import it directly by
+ * type.
+ *
+ * A record with `provider.id === 'ssh'` maps:
+ * - `provider.connectionRef.id` → HostStore alias
+ * - `location.root` → the remote root directory
+ * - `anchor.path` → the local anchor (session-visible)
+ *
+ * @module @tiphareth/dsh-hardssh/providers/ssh
+ */
+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 { SshEngine } from '../../ssh/engine.ts';
+/** The ssh provider manifest. */
+export declare const sshProviderManifest: WorkspaceProviderManifest;
+/** One open SSH workspace connection. */
+export declare class SshWorkspaceConnection implements WorkspaceConnection {
+    readonly workspaceId: string;
+    private readonly engine;
+    private readonly alias;
+    private readonly remoteRoot;
+    readonly providerId = "ssh";
+    constructor(workspaceId: string, engine: SshEngine, alias: string, remoteRoot: string);
+    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. */
+export declare class SshWorkspaceSearch implements WorkspaceSearchService {
+    private readonly engine;
+    private readonly alias;
+    private readonly root;
+    private readonly service;
+    constructor(engine: SshEngine, alias: string, root: string);
+    glob(pattern: string, options?: {
+        root?: string;
+        maxDepth?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        hits: WorkspaceSearchHit[];
+        truncated: boolean;
+    }>;
+    grep(fixedPhrase: string, options?: {
+        root?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        hits: WorkspaceSearchHit[];
+        truncated: boolean;
+    }>;
+}
+/** The ssh provider factory. */
+export declare function createSshWorkspaceProvider(engine: SshEngine): WorkspaceProvider;
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * Remote-environment scrubbing and caching for the SSH process and terminal
+ * launchers. Ported from UynajGI/dsh-ssh (MIT) — adapted to the dsh-ssh
+ * engine. The read side is cached per (engine, alias) with a short TTL and
+ * merged concurrent requests, so repeated spawns/terminals on one host stop
+ * issuing an `env` exec each time (P1-12).
+ */
+import type { SshEngine } from '../ssh/engine.ts';
+import { shellQuote as quoteShellArg } from '../shell.ts';
+/** Quote one argument for a POSIX login shell (canonical implementation in shell.ts). */
+export { quoteShellArg };
+/** Wrap a remote command so it runs from the given working directory. */
+export declare function wrapCwd(cwd: string, command: string): string;
+/**
+ * Read + scrub the remote login environment, cached per (engine, alias).
+ * Concurrent requests share one fetch; failures are never cached.
+ */
+export declare function readScrubbedRemoteEnvironment(engine: SshEngine, alias: string): Promise<ReadonlyMap<string, string>>;
+/** Drop cached environments for one alias (call after a host config change). */
+export declare function invalidateRemoteEnvironment(engine: SshEngine, alias: string): void;
+/**
+ * Remove harness-private and credential-shaped names from a remote environment.
+ */
+export declare function scrubRemoteEnvironment(environment: ReadonlyMap<string, string>): Map<string, string>;
+/**
+ * Overlay explicit entries and serialize one validated environment for `env -i`.
+ */
+export declare function serializeEnvironment(scrubbed: ReadonlyMap<string, string>, explicit: Readonly<NodeJS.ProcessEnv> | undefined): string;
+//# sourceMappingURL=environment.d.ts.map

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

@@ -0,0 +1,38 @@
+/**
+ * Bounded host-side projection of one remote output stream with a local
+ * spill file. Ported from UynajGI/dsh-ssh (MIT) — verbatim semantics.
+ */
+import type { CollectedOutput, SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess';
+/**
+ * Collects one remote stream with a bounded in-memory tail. On first overflow
+ * a spill file is opened (when a spill cap is configured) and every chunk —
+ * already-collected ones included — is appended there while the full stream
+ * stays within the cap; without one, only the in-memory tail is retained.
+ */
+export declare class SshOutputCollector implements SubprocessOutputReader {
+    private readonly maxBytes;
+    private readonly maxSpillBytes;
+    private readonly label;
+    private readonly spillDir;
+    private chunks;
+    private retained;
+    private total;
+    private dropped;
+    private spillFd;
+    private spillFile;
+    private spillDisabled;
+    constructor(maxBytes: number, maxSpillBytes: number | undefined, label: string, spillDir?: string);
+    /** Append one byte-faithful remote chunk, trimming the retained tail to the cap. */
+    push(chunk: Uint8Array): void;
+    /** @inheritdoc */
+    readFrom(fromByte: number): SubprocessOutputRead;
+    /** Open the spill file lazily and append one chunk (plus any prior chunks once). */
+    private spillAll;
+    /** Stop spilling and remove the file once it can no longer hold the complete stream. */
+    private discardSpill;
+    /** Close the spill file once the stream has ended; stop advertising it on a failed close. */
+    seal(): void;
+    /** Seal the spill and return the final collected output. */
+    finalize(): CollectedOutput;
+}
+//# sourceMappingURL=output.d.ts.map

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

@@ -0,0 +1,69 @@
+/**
+ * Remote filesystem provider for the `ctx.fs` capability seam: paths,
+ * contents, and atomic staging files live on the remote host, reached through
+ * the dsh-ssh engine's SFTP/exec primitives. Ported and adapted from
+ * UynajGI/dsh-ssh (MIT, https://github.com/UynajGI/dsh-ssh) — the seam
+ * contract (targets, versions, atomic writes, CRLF handling, canonical path
+ * transport) is preserved; the connection owner is replaced by the shared
+ * SshEngine and the working directory follows the mode store's remote root.
+ *
+ * @module dsh-hardssh/remote-fs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+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';
+/**
+ * Remote filesystem backend over the dsh-ssh engine. The working directory
+ * follows the mode store: relative paths resolve against the resolved remote
+ * root; a POSIX-absolute cwd override is honored; local (Windows) cwds are
+ * ignored so the model's relative-path habit keeps working remotely.
+ */
+export declare class SshFileSystem extends FileSystem {
+    private readonly engine;
+    private readonly getState;
+    private readonly locks;
+    constructor(ctx: Context, engine: SshEngine, getState: () => WorkspaceState);
+    /** The active remote execution world (throws when not in remote mode). */
+    private current;
+    /**
+     * Resolve the working directory for a path: a POSIX-absolute cwd wins;
+     * anything else (relative or a local Windows path) falls back to the
+     * remote root.
+     */
+    resolveRemoteCwd(cwd: string | undefined): string;
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    processPath(target: FsTarget): string;
+    fileUrl(target: FsTarget): string;
+    contains(parent: FsTarget, child: FsTarget): boolean;
+    stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
+    streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>;
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: ReturnType<typeof FsVersion>;
+    }, signal?: AbortSignal): Promise<FsEditOutcome>;
+    private withLock;
+    private canonicalPath;
+    private probe;
+    private requireRegular;
+    private readBytesRaw;
+    private checkWriteIntent;
+    private readForDiff;
+    private readForEdit;
+    private writeAtomic;
+    private removeStaging;
+    /** Normalize an engine stat/ls shape into the RemoteStats the helpers expect. */
+    private asStats;
+}
+export default SshFileSystem;
+//# sourceMappingURL=remote-fs.d.ts.map

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

@@ -0,0 +1,41 @@
+/**
+ * One asynchronously-started SSH command projected onto the subprocess seam.
+ * Ported from UynajGI/dsh-ssh (MIT) — the raw ssh2 channel is replaced by the
+ * engine's streaming ExecSession.
+ */
+import { PassThrough } from 'node:stream';
+import type { SshEngine } from '../ssh/engine.ts';
+import type { SubprocessHandle, SubprocessOutcome, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { WorkspaceState } from '../protocol.ts';
+/** SSH-backed subprocess handle. The channel does not expose a remote pid, so `pid` is `-1`. */
+export declare class SshSubprocessHandle implements SubprocessHandle {
+    private readonly engine;
+    private readonly getState;
+    private readonly spec;
+    private readonly spillDir;
+    readonly stdin: PassThrough | undefined;
+    readonly stdout: PassThrough | undefined;
+    readonly stderr: PassThrough | undefined;
+    readonly collected: SubprocessHandle['collected'];
+    readonly done: Promise<SubprocessOutcome>;
+    private readonly terminationController;
+    private readonly stdoutCollector;
+    private readonly stderrCollector;
+    private session;
+    private graceTimer;
+    private settled;
+    constructor(engine: SshEngine, getState: () => WorkspaceState, spec: SubprocessSpawnSpec, spillDir: string);
+    /** Remote process id; `-1` because the SSH channel does not expose one. */
+    get pid(): number;
+    /** @inheritdoc */
+    terminate(): void;
+    /** @inheritdoc */
+    waitForExit(signal?: AbortSignal): Promise<boolean>;
+    private readonly onAbort;
+    private signalTerm;
+    private settle;
+    private run;
+    private wireStdout;
+    private wireStderr;
+}
+//# sourceMappingURL=remote-process.d.ts.map

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

@@ -0,0 +1,31 @@
+/**
+ * Remote subprocess provider for the `ctx.subprocess` capability seam: each
+ * spawn opens a streaming exec channel (or a PTY for terminals) on the
+ * current SSH-mode host through the dsh-ssh engine; output spill files stay
+ * on the local host. Ported from UynajGI/dsh-ssh (MIT).
+ *
+ * @module dsh-hardssh/remote-subprocess
+ */
+import type { Context } from '@deepseek-ai/cordis';
+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';
+/** SSH command manager registered as `ctx.subprocess` (remote mode). */
+export declare class SshSubprocessRuntime extends SubprocessRuntime {
+    private readonly engine;
+    private readonly getState;
+    private readonly live;
+    private readonly terminals;
+    private readonly spillDir;
+    private disposing;
+    constructor(ctx: Context, engine: SshEngine, getState: () => WorkspaceState);
+    /** @inheritdoc */
+    resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+    /** @inheritdoc */
+    spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    /** @inheritdoc */
+    spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+}
+export default SshSubprocessRuntime;
+//# sourceMappingURL=remote-subprocess.d.ts.map

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

@@ -0,0 +1,41 @@
+/**
+ * SSH PTY allocation and process-session ownership for the subprocess seam.
+ * Ported from UynajGI/dsh-ssh (MIT) — the raw ssh2 shell channel is replaced
+ * by the engine's openShell session.
+ */
+import { PassThrough } from 'node:stream';
+import type { SshEngine } from '../ssh/engine.ts';
+import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { WorkspaceState } from '../protocol.ts';
+/** One SSH PTY and its remote login shell, projected onto the subprocess terminal seam. */
+export declare class SshTerminalHandle implements SubprocessTerminalHandle {
+    private readonly closeChannel;
+    private readonly sendChannel;
+    private readonly signalChannel;
+    private readonly graceMs;
+    readonly pid = -1;
+    readonly output: PassThrough;
+    readonly done: Promise<SubprocessOutcome>;
+    private exitResolve;
+    topLevelExited: boolean;
+    private cleanup;
+    constructor(closeChannel: () => void, sendChannel: (data: string) => void, signalChannel: (name: string) => void, graceMs: number);
+    /** Settle the exit promise (called by the runtime when the channel closes). */
+    resolveExit(outcome: SubprocessOutcome): void;
+    /** @inheritdoc */
+    write(data: string): Promise<void>;
+    /** The SSH channel does not expose a foreground process group. */
+    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    /** @inheritdoc */
+    signalForeground(_signal: SubprocessTerminalSignal): Promise<number>;
+    /** @inheritdoc */
+    terminate(): Promise<void>;
+    private signal;
+    private closeOnce;
+}
+/**
+ * Allocate an SSH PTY, replace its login shell with the requested argv, and
+ * return the live terminal handle.
+ */
+export declare function spawnSshTerminal(engine: SshEngine, getState: () => WorkspaceState, spec: SubprocessTerminalSpawnSpec): Promise<SshTerminalHandle>;
+//# sourceMappingURL=remote-terminal.d.ts.map

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

@@ -0,0 +1,83 @@
+/**
+ * Remote-workspace runner: lets other plugins (dsh-workbench-tiphareth) run
+ * git/files/terminals against an SSH-bound workspace. The workbench host asks
+ * `resolveRemote(root)` for a local anchor path; a hit returns the remote
+ * context + callable channels (git exec via the engine, SFTP ops, PTY).
+ * Kept duck-typed so the workbench never needs a compile-time dependency.
+ */
+import type { SshEngine } from './ssh/engine.ts';
+import type { SshWorkspaceLedger } from './ledger.ts';
+/** The remote context one SSH-bound workspace resolves to. */
+export interface RemoteWorkspaceContext {
+    alias: string;
+    remoteRoot: string;
+    /** Run `git [args...]` inside remoteRoot. Mirrors runGit's result shape. */
+    git(args: readonly string[], opts?: {
+        timeoutMs?: number;
+        input?: string;
+        allowNonZero?: boolean;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /** Run one arbitrary command (used by tools that shell out). */
+    run(command: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /** SFTP operations. */
+    list(path: string): Promise<Array<{
+        name: string;
+        type: 'dir' | 'file' | 'other';
+        size: number;
+        mtimeMs: number;
+    }>>;
+    stat(path: string): Promise<{
+        type: 'dir' | 'file' | 'other';
+        size: number;
+        mtimeMs: number;
+        mode: number;
+    }>;
+    readFile(path: string): Promise<{
+        content: Buffer;
+        mtime: number;
+        size: number;
+    }>;
+    writeFile(path: string, content: Buffer, expectedMtime?: number): Promise<{
+        mtime: number;
+    }>;
+    mkdir(path: string): Promise<void>;
+    rm(path: string, recursive: boolean): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    /** Open an interactive SSH PTY in remoteRoot (columns/rows for the channel). */
+    openTerminal(cols: number, rows: number): Promise<RemotePtyHandle>;
+}
+/** Minimal PTY handle (duck-typed for consumers like dsh-workbench-tiphareth). */
+export interface RemotePtyHandle {
+    shell: string;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(): void;
+    onData(handler: (data: string) => void): {
+        dispose(): void;
+    };
+    onExit(handler: (event: {
+        exitCode: number;
+    }) => void): {
+        dispose(): void;
+    };
+}
+/** Builds remote-workspace contexts off the shared ledger + engine. */
+export declare class RemoteWorkspaceRunner {
+    private readonly engine;
+    private readonly ledger;
+    constructor(engine: SshEngine, ledger: SshWorkspaceLedger);
+    /** Resolve a LOCAL anchor path to a remote context, or null if not SSH-bound. */
+    resolveRemote(root: string): RemoteWorkspaceContext | null;
+    private build;
+}
+//# sourceMappingURL=remote-runner.d.ts.map

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

@@ -0,0 +1,50 @@
+/**
+ * Remote search semantics shared by the UI file-name search (backend) and the
+ * remote_search agent tool (glob / grep modes). Centralizes command building,
+ * literal escaping, NUL-delimited parsing, and truncation rules (P1-11) so
+ * the three former hand-rolled implementations cannot drift again.
+ *
+ * Command output is never treated as authorization evidence: this service
+ * returns raw absolute paths; callers (backend) re-authorize each hit against
+ * the workspace root before exposing it.
+ */
+import type { SshEngine } from './ssh/engine.ts';
+/** One SSH workspace to search on. */
+export interface SearchTarget {
+    alias: string;
+    /** Remote root; every path is reported absolute under it. */
+    root: string;
+}
+/** One raw file-name hit (absolute path, type). */
+export interface RemoteNameHit {
+    path: string;
+    isDir: boolean;
+}
+export interface RemoteNameSearch {
+    query: string;
+    hits: RemoteNameHit[];
+    truncated: boolean;
+}
+export interface RemoteGlobResult {
+    hits: string[];
+    truncated: boolean;
+}
+export interface RemoteGrepResult {
+    lines: string[];
+    truncated: boolean;
+}
+/**
+ * One search implementation shared by the UI and the agent tools.
+ * Stateless apart from the engine; safe to construct per call or share.
+ */
+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>;
+    /** Glob search (pattern keeps glob semantics; `**` crosses directories). */
+    glob(target: SearchTarget, pattern: string): Promise<RemoteGlobResult>;
+    /** Fixed-string grep (literal pattern, `-F`; NUL file boundary `-Z`). */
+    grepFixed(target: SearchTarget, pattern: string): Promise<RemoteGrepResult>;
+}
+//# sourceMappingURL=remote-search.d.ts.map

package/lib/types/routes.d.ts

@@ -0,0 +1,24 @@
+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';
+/** 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;
+    /** 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.
+ */
+export declare function makeRoutes(deps: WorkspaceRoutesDeps): WebRoute[];
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +1,59 @@
+/**
+ * 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
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { WorkspaceProviderRegistry, type WorkspaceRegistry } from '../base/registry.ts';
+import type { WorkspaceRecord } from '../base/model.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. */
+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;
+}
+/** 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`.
+ */
+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;
+    }
+}
+//# sourceMappingURL=workspace-core.d.ts.map

package/lib/types/seam-state.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The shared derived seam state: ONE ledger-derived routing snapshot
+ * (records + normalized anchor index) plus the per-record fs/subprocess
+ * instances, owned by the hardssh core and consumed by BOTH switch rows
+ * (./fs and ./subprocess). Because both seams read the SAME state, they can
+ * never disagree with each other or with the ledger's own index for a given
+ * session cwd — eliminating the split-brain window of the old per-seam
+ * async refresh caches.
+ *
+ * The state re-applies SYNCHRONOUSLY on every ledger commit: ledger
+ * listeners run synchronously AFTER the commit already swapped the
+ * in-memory records, so a synchronous re-apply is always current — no async
+ * refresh pipeline, no stale-snapshot race, no revision-guard interleaving.
+ * The initial file load is awaited before the state is marked ready; until
+ * then routing degrades to local with a one-time warning from the rows.
+ *
+ * Per-record instances are built lazily on first route and kept alive
+ * across refreshes (connections survive); removing a workspace drops its
+ * instances so stale target keys resolve to NOTHING (fail closed), never to
+ * the local backend.
+ *
+ * @module dsh-hardssh/seam-state
+ */
+import type { SshWorkspaceRecord } from './protocol.ts';
+import { type SshWorkspaceLedger } from './ledger.ts';
+import { type WorkspaceWorld } from './switch/switch-fs.ts';
+import type { SshSubprocessRuntime } from './remote/remote-subprocess.ts';
+/** Shared routing state for the fs/subprocess switch rows. */
+export declare class WorkspaceSeamState {
+    private readonly ledger;
+    private readonly records;
+    private readonly instances;
+    private anchors;
+    private appliedRevision;
+    private ready;
+    private readyResolvers;
+    private fsFactory;
+    private subFactory;
+    constructor(ledger: SshWorkspaceLedger);
+    /** Bind the fs-row's per-record backend builder (called once at apply). */
+    bindFs(factory: (record: SshWorkspaceRecord) => WorkspaceWorld): void;
+    /** Bind the subprocess-row's per-record runtime builder (called once at apply). */
+    bindSub(factory: (record: SshWorkspaceRecord) => SshSubprocessRuntime): void;
+    /** True once the initial ledger snapshot has been applied. */
+    isReady(): boolean;
+    /** Resolves once the initial ledger snapshot has been applied. */
+    whenReady(): Promise<void>;
+    /**
+     * Subscribe to ledger commits and kick the initial load. Returns the
+     * subscription disposer (register it through ctx.effect for HMR cleanup).
+     */
+    attach(): () => void;
+    /** Re-apply the ledger's current in-memory state (idempotent, guarded). */
+    applySync(): void;
+    /** The record owning a session cwd, or undefined when the cwd is local. */
+    private recordFor;
+    private ensureFs;
+    private ensureSubprocess;
+    /** The fs world owning a session cwd, or undefined (local). */
+    worldForFs(cwd: string | undefined): WorkspaceWorld | undefined;
+    /** The fs world for one namespaced target key (`wfs://<id>/…` or legacy
+     *  `ssh:<id>:`), or undefined when the owning workspace no longer exists
+     *  (stale key → fail closed). */
+    worldForFsNamespace(namespace: string): WorkspaceWorld | undefined;
+    /** The subprocess runtime owning a session cwd, or undefined (local). */
+    runtimeForSub(cwd: string | undefined): SshSubprocessRuntime | undefined;
+    private markReady;
+}
+//# sourceMappingURL=seam-state.d.ts.map

package/lib/types/shell.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonical POSIX shell single-quoting for remote command construction.
+ * Replaces the three near-identical copies that used to live in backend.ts,
+ * tools.ts and remote/environment.ts.
+ */
+/** Quote one argument for a POSIX login shell (single-quote, `'\''` for embedded quotes). */
+export declare function shellQuote(value: string): string;
+//# sourceMappingURL=shell.d.ts.map