@tiphareth/dsh-hardssh 0.1.2 → 0.2.2

package/lib/types/fs.d.ts

@@ -1,36 +1,29 @@
 /**
- * The `ctx.fs` switch row: provides the workspace-routing filesystem facade in
- * the host scope. The local backend (the deployment's sandboxed filesystem) is
- * mounted in an isolated child scope so its own `ctx.fs` provide never
- * collides. Routing and per-record remote backends are owned by the SHARED
- * seam state (hardsshCore.seams): the row only binds its per-record backend
- * factory and reads the state on every call. Every SSH-bound workspace record
- * gets its OWN remote backend instance bound to that record's alias + remote
- * root; the facade routes each call by the session cwd — an anchor path of an
- * SSH workspace routes remote, everything else stays local. The facade
- * auto-provides `fs` here because the `fs-sandbox` row is disabled by the
- * profile patch.
+ * The `ctx.fs` switch row: provides the generic WorkspaceCore-routing
+ * filesystem facade in the host scope. The local backend (the deployment's
+ * sandboxed filesystem) is mounted in an isolated child scope so its own
+ * `ctx.fs` provide never collides.
  *
- * The seam state re-applies the ledger snapshot synchronously on every
- * commit, so creating or removing an SSH workspace takes effect without a
- * plugin restart and the fs/subprocess seams can never disagree. Before the
- * initial ledger load finishes, routing degrades to local with a one-time
- * warning for anchor-root paths.
+ * Routing worlds always come from `WorkspaceCore`/router:
+ * `connection.get('workspace.fs')` returns the root-bound DSH `FileSystem`
+ * cached by the provider. A cwd inside a workspace anchor resolves through
+ * that connection; everything else stays local. Before the core is ready, or
+ * for an unowned path beneath the managed SSH anchor root, access fails closed
+ * rather than touching the client filesystem.
  *
  * @module dsh-hardssh/fs
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { HardsshCore } from './core.ts';
-declare module '@deepseek-ai/cordis' {
-    interface Context {
-        hardsshCore: HardsshCore;
-    }
-}
+import { type WorkspaceWorld } from './switch/switch-fs.ts';
+import type { WorkspaceCore } from './runtime/workspace-core.ts';
 /** Stable cordis plugin name. */
 export declare const name = "hardssh-fs";
-/** Services required: the shared workspace core (mode store + engine) and the
- *  sandbox policy the local backend (`SandboxedFileSystem`) consumes. */
+/** The generic workspace core plus the policy used by the local fallback. */
 export declare const inject: string[];
-/** Mount the switching filesystem facade. */
+/** Resolve the fs world owning a cwd, or undefined when it is definitely local. */
+export declare function genericFsWorldFor(core: WorkspaceCore, cwd: string | undefined, reservedAnchorRoots: readonly string[]): WorkspaceWorld | undefined;
+/** Resolve one namespaced target key, failing closed for stale namespaces. */
+export declare function genericFsWorldForNamespace(core: WorkspaceCore, namespace: string): WorkspaceWorld | undefined;
+/** Mount the generic switching filesystem facade. */
 export declare function apply(ctx: Context): void;
 //# sourceMappingURL=fs.d.ts.map

package/lib/types/index.d.ts

@@ -1,9 +1,8 @@
 /**
  * dsh-hardssh — host half. Owns the local⇄remote mode store, the
  * /api/dsh-hardssh route family (loopback-only), the remote_* agent
- * tools, a model-facing announcement section, the shared workspace core
- * (`ctx.hardsshCore`, including the shared seam state the fs/subprocess
- * switch rows consume), and — since the legacy dsh-ssh package was merged
+ * tools, a model-facing announcement section, the generic workspace core,
+ * and — since the legacy dsh-ssh package was merged
  * in — the SSH operations capability (host manager, ssh_* tools, /api/dsh-ssh,
  * web terminal). In SSH mode the model's ordinary read/write/edit/bash tools
  * run transparently on the remote host through those switch rows. File
@@ -13,14 +12,25 @@
  * the header buttons, the SSH config dialog, the left workspace panel, and
  * the SSH host-manager surfaces.
  *
- * The announcement section is rendered PER SESSION from the ledger facts
+ * The announcement section is rendered PER SESSION from the workspace facts
  * (which workspace this session's cwd binds to), never from path-string
- * heuristics; and a global tool guard blocks glob/grep/pwsh calls in
- * SSH-bound sessions with a clear error instead of letting them fail with
- * "No such file or directory" on the remote host.
+ * heuristics. There is no tool guard layer: routing lives in the fs/subprocess
+ * seams, and the subprocess facade refuses the one combination that cannot be
+ * routed correctly — a client-side search helper (glob/grep's bundled ripgrep)
+ * inside a remote-bound session, which would otherwise return confidently wrong
+ * "no matches" from the local anchor.
+ *
+ * The generic WorkspaceCore is the only production workspace runtime. On the
+ * first upgraded boot, the frozen legacy SSH ledger is imported once into
+ * `~/.dsh/workspaces/index.v1.json`; the atomic migration report is the durable
+ * cutover marker. Emergency generic-to-legacy conversion is an offline export,
+ * never an alternate in-process routing mode.
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { type HostWorkspaceReconcileDeps, type HostWorkspaceReconcileReport } from './routes.ts';
+import { type WorkspaceCore } from './runtime/workspace-core.ts';
+import type { SshWorkspaceRecord } from './protocol.ts';
 /** Stable cordis plugin name. */
 export declare const name = "hardssh";
 /**
@@ -32,18 +42,137 @@ export declare const name = "hardssh";
 export declare const inject: string[];
 /** Plugin config (schemastery; optional fields use .default, never .optional). */
 export interface Config {
-    /** Master switch (default on). Disabling requires reverting the profile seam patch. */
+    /**
+     * Workspace-surface switch (default on). It gates ONLY the SSH-workspace
+     * surfaces this row mounts after the check below: the /api/dsh-hardssh
+     * workspace CRUD routes, the remote_* workspace agent tools, and the
+     * workspace announcement section. It does NOT gate the SSH operations
+     * capability (host manager, ssh_* tools, /api/dsh-ssh, web terminal — its
+     * own `dsh-ssh` settings namespace `enabled`), the shared
+     * engine/host-store/vault, the fs/subprocess routing rows, or the seam
+     * replacement itself: those mount before this switch and keep running.
+     */
     enabled: boolean;
     /** Whether the model-facing announcement section is mounted. */
     announceToAgent: boolean;
     /**
      * Secret storage mode: 'none' (default, VSCode Remote-SSH style: passwords
      * never persisted, prompted once per session) or 'vault' (encrypted at
-     * rest, for unattended agents). Mirrors the dsh-ssh settings namespace.
+     * rest, for unattended agents).
+     *
+     * This is the SINGLE SOURCE for the mode: the Vault and SecureHostStore are
+     * constructed once from it when the plugin loads, so changing it requires a
+     * plugin reload. The `dsh-ssh` settings namespace also exposes
+     * `secretStorage` for the settings UI, but that value cannot switch storage
+     * mode at runtime (see reportSecretStorageDrift below).
      */
     secretStorage: 'none' | 'vault';
+    /**
+     * Whether the credential vault may auto-unlock from the
+     * `DSH_CREDENTIAL_PASSWORD` environment variable at plugin load.
+     *
+     * `'off'` (default): the vault stays locked until a password is entered, so a
+     * leaked ciphertext is not enough to recover credentials. `'env'` is the
+     * explicit opt-in for unattended/headless agents.
+     */
+    vaultAutoUnlock: 'off' | 'env';
 }
 export declare const Config: z<Config>;
+/**
+ * The ONE effective secretStorage mode: the plugin config value, defaulting to
+ * 'none'. The Vault and SecureHostStore are constructed from this value once
+ * (plugin load), which is what makes it authoritative.
+ */
+export declare function resolveSecretStorageMode(config?: {
+    secretStorage?: unknown;
+}): 'none' | 'vault';
+/**
+ * Report a secretStorage disagreement between the RUNNING mode (fixed when the
+ * Vault/SecureHostStore were constructed at plugin load) and the value the
+ * `dsh-ssh` settings namespace currently resolves to. The mode cannot change
+ * at runtime, so staying silent would let the settings UI claim a storage mode
+ * this process is not using.
+ * @param running - the construction-time mode actually in effect.
+ * @param section - the resolved `dsh-ssh` settings section (any shape).
+ * @returns the warning text, or undefined when both agree / the value is unusable.
+ */
+export declare function secretStorageDriftMessage(running: 'none' | 'vault', section: unknown): string | undefined;
+/**
+ * Report secretStorage drift once at mount and on every committed settings
+ * change (deduplicated, so a repeated change does not spam the log). The
+ * settings service is a sibling context and cordis events travel UP from the
+ * emitting ctx, so the listener sits on the root context; `ctx.effect` keeps
+ * the subscription tied to this plugin's lifetime.
+ * @param ctx - the plugin context (provides `settings` when present).
+ * @param running - the construction-time mode actually in effect.
+ */
+export declare function watchSecretStorageDrift(ctx: Context, running: 'none' | 'vault'): void;
+/** Isolated-path options for one generic startup (tests inject temp dirs). */
+export interface GenericBootOptions {
+    /** The frozen legacy SSH ledger file (~/.dsh/dsh-hardssh-workspaces.json). */
+    legacyPath: string;
+    /** The generic ledger target (~/.dsh/workspaces/index.v1.json). */
+    genericPath: string;
+    /** Migration report path. The report is also the durable cutover marker. */
+    reportPath?: string;
+}
+/**
+ * Run the Phase-7 cutover sequence against one generic core. A structurally
+ * valid atomic migration report is the durable cutover marker: once it exists,
+ * the generic ledger is permanently authoritative and startup never compares
+ * it with (or even reads) the frozen legacy source again. Without a marker the
+ * one-time migration runs and atomically publishes that report only after the
+ * generic snapshot has committed and verified.
+ *
+ * A valid marker is also a proof of existence: it records that N workspaces
+ * were committed, so a MISSING or UNREADABLE ledger underneath it is data loss,
+ * not a fresh deployment. `WorkspaceLedger` treats ENOENT as an empty array,
+ * which would silently drop every workspace forever (the marker suppresses the
+ * one-time import); this gate therefore recovers the ledger — `.last-good`,
+ * then the newest `.backup-*`, then a legacy re-import — and, failing that,
+ * refuses to start so the surfaces fail closed instead of showing nothing.
+ *
+ * The recovery is verified against the marker's own id list, so a source that
+ * would restore FEWER workspaces than were recorded is rejected instead of
+ * accepted as success. A ledger that exists but is corrupt is treated like a
+ * missing one; a ledger that exists and is valid is authoritative even when it
+ * is empty (deleting every workspace is a legitimate, recorded intent).
+ *
+ * On any failure the promise rejects and the core stays NOT ready, so workspace
+ * consumers fail closed instead of silently operating local files.
+ */
+export declare function bootstrapGenericWorkspaceCore(core: WorkspaceCore, options: GenericBootOptions): Promise<void>;
+/** Local-session branch of the announcement. Exported for the guidance test. */
+export declare function localGuidance(): string;
+/**
+ * SSH-bound-session branch of the announcement.
+ *
+ * The tool facts here must match the seams. read/write/edit route through
+ * `SwitchFileSystem` (server data remote, client-declared local roots local).
+ * glob/grep do NOT: they run the CLIENT's bundled ripgrep through
+ * `ctx.subprocess`, which cannot see the remote workspace, so the subprocess
+ * facade refuses that combination and points here to the remote tools. `pwsh`
+ * is a client-native binary and runs on this machine.
+ *
+ * Exported for the guidance test.
+ */
+export declare function remoteGuidance(record: SshWorkspaceRecord): string;
+/**
+ * A-04 startup half: replay host-workspace registration for every stored
+ * record once the workspace store is ready, so a process restart (or a create
+ * whose registration failed before the compensating rollback existed) cannot
+ * leave a binding whose sidebar entry is missing. `registerHostWorkspace` is
+ * create-if-missing, so replay is idempotent.
+ *
+ * Thin delegation to the shared `reconcileHostWorkspaces` (src/routes.ts) that
+ * the loopback-guarded `/reconcile` route also calls, so the two halves cannot
+ * drift. This wrapper owns the startup-only rules: never reject (a broken host
+ * registry or an unreadable ledger must not break plugin load) and log what
+ * happened instead of surfacing it to the loader.
+ * @param deps - the record source and the host-registry registration hook.
+ * @returns the shared reconcile report (empty when the record list failed).
+ */
+export declare function reconcileHostWorkspacesOnStartup(deps: HostWorkspaceReconcileDeps): Promise<HostWorkspaceReconcileReport>;
 /**
  * Mount the mode store, routes, tools, announcement, guard, and the shared core.
  * @param ctx - host plugin context carrying tools/systemPrompt (webServer optional).

package/lib/types/ledger.d.ts

@@ -1,46 +1,19 @@
 /**
- * SSH-bound workspace ledger: the mapping from a LOCAL ANCHOR directory (the
- * host-visible workspace path, which sessions use as their cwd) to a REMOTE
- * directory on an SSH host. Persisted as JSON next to dsh-ssh.json so the
- * fs/subprocess seams can route a session whose cwd is an anchor to the
- * remote execution world, and everything else stays local.
+ * SSH-bound workspace path helpers.
  *
- * A ledger record is created through the GUI (pick a host, browse a remote
- * dir, give it a title). The host-side anchor directory is auto-created
- * under ~/.dsh/ssh-workspaces/<id>/; the host workspace registry owns it as
- * a normal local workspace, so session creation/listing/persistence keep
- * working untouched.
- *
- * Mutations are serialized through a per-instance queue and committed as:
- * write temp file → atomic rename → swap memory/index → bump revision →
- * notify subscribers. A persistence failure leaves observable state
- * unchanged and never publishes an event.
+ * This module is the last remaining piece of the retired SSH ledger module:
+ * the `SshWorkspaceLedger` class was removed with the generic cutover, so what
+ * survives here are the anchor/path helpers the generic runtime still shares —
+ * the managed SSH anchor layout (`~/.dsh/ssh-workspaces/<id>`), the legacy
+ * ledger file location (the one-time import source), the client DTO title
+ * default, and the lexical anchor-containment helpers used by fs/subprocess
+ * fail-closed gating. Record persistence itself is owned by the generic
+ * `WorkspaceLedger` (`./base/ledger.ts`).
  *
  * @module dsh-hardssh/ledger
  */
-import type { SshWorkspaceRecord } from './protocol.ts';
-/** One committed snapshot of the ledger. */
-export interface LedgerSnapshot {
-    revision: number;
-    records: readonly SshWorkspaceRecord[];
-}
-/** One committed mutation, delivered to subscribers. */
-export type LedgerChange = {
-    type: 'created';
-    revision: number;
-    record: SshWorkspaceRecord;
-} | {
-    type: 'renamed';
-    revision: number;
-    before: SshWorkspaceRecord;
-    record: SshWorkspaceRecord;
-} | {
-    type: 'removed';
-    revision: number;
-    record: SshWorkspaceRecord;
-};
-export type LedgerListener = (change: LedgerChange) => void;
-/** Ledger file location: ~/.dsh/dsh-hardssh-workspaces.json. */
+/** The frozen legacy SSH ledger location: ~/.dsh/dsh-hardssh-workspaces.json.
+ *  Only read once by the startup import when no cutover marker exists. */
 export declare function ledgerPath(): string;
 /**
  * Normalize a remote POSIX root: keep '/' as '/', collapse repeated
@@ -55,78 +28,10 @@ export declare function anchorPathFor(id: string): string;
 /** Default record title when the user gives none. */
 export declare function defaultTitle(remoteRoot: string, alias: string): string;
 /**
- * Normalize a local anchor path for comparison: Windows anchors are
- * case-insensitive with mixed separators; POSIX anchors stay case-sensitive.
- */
-export declare function normalizeAnchorPath(path: string): string;
-/** True when candidate equals anchor or is one of its descendants. Lexical
- *  comparison over already-resolved paths; deliberately no fs access. */
-export declare function isPathUnderAnchor(anchor: string, candidate: string): boolean;
-/**
- * The in-memory ledger. Loaded lazily on first access; every mutation writes
- * through durably (atomic rename) and is serialized through a per-instance
- * queue. A synchronous anchor index is maintained from the latest committed
- * records so host seams can resolve a cwd/root without awaiting I/O.
+ * Anchor-path comparison is owned by ONE implementation (`base/ledger.ts`):
+ * two copies had already drifted in their Windows/UNC root handling, and the
+ * seams, the store, and the client all compare anchors. Re-exported here so
+ * existing `from './ledger.ts'` imports keep working.
  */
-export declare class SshWorkspaceLedger {
-    private readonly fileOverride?;
-    private readonly anchorOverride?;
-    private records;
-    private loadPromise;
-    private anchorIndex;
-    private mutationTail;
-    private currentRevision;
-    private readonly listeners;
-    /** Overridable file location (tests isolate per instance). */
-    constructor(fileOverride?: string | undefined, anchorOverride?: string | undefined);
-    private file;
-    private anchors;
-    private anchorFor;
-    /** Load the ledger once (missing/unreadable/malformed file -> empty ledger). */
-    private ensureLoaded;
-    private readRecords;
-    /** Rebuild the synchronous anchor index from the current records. */
-    private reindex;
-    /** Persist a proposed record array without touching observable state. */
-    private save;
-    /** Serialize one mutation; a rejected earlier mutation never poisons later ones. */
-    private enqueueMutation;
-    /** Commit a computed next state: swap memory, bump revision, notify. */
-    private commit;
-    private emit;
-    /** Load the ledger (compat; returns detached copies). */
-    load(): Promise<SshWorkspaceRecord[]>;
-    /** All records, in creation order (detached copies). */
-    list(): Promise<SshWorkspaceRecord[]>;
-    /** Current detached snapshot. */
-    snapshot(): Promise<LedgerSnapshot>;
-    /** Current in-process snapshot, synchronously (empty before first load).
-     *  The returned records are the live immutable objects — callers must not
-     *  mutate them (commits always replace the array wholesale). */
-    snapshotSync(): LedgerSnapshot;
-    /** Current in-process revision (restarts at 0 on process restart). */
-    revision(): number;
-    /** Subscribe to committed mutations (no initial event). Returns a disposer. */
-    subscribe(listener: LedgerListener): () => void;
-    /** Look up by id. */
-    get(id: string): Promise<SshWorkspaceRecord | undefined>;
-    /** Look up by LOCAL anchor path (resolved). Returns the record whose
-     *  anchor owns the path (the anchor itself or any descendant). */
-    findByAnchor(path: string): Promise<SshWorkspaceRecord | undefined>;
-    /** Synchronous anchor lookup (uses the in-memory index). */
-    findByAnchorSync(path: string): SshWorkspaceRecord | undefined;
-    /** Create a record: materialize the anchor, then persist+commit. */
-    create(input: {
-        title: string;
-        alias: string;
-        remoteRoot: string;
-    }): Promise<SshWorkspaceRecord>;
-    /** Rename a record (display title only). */
-    rename(id: string, title: string): Promise<SshWorkspaceRecord | undefined>;
-    /** Remove a record. The anchor directory is left in place (a host
-     *  workspace may still reference it; the caller decides on deletion). */
-    remove(id: string): Promise<boolean>;
-    /** The anchor root shared by every record (for UI hints). */
-    anchorsRoot(): string;
-}
+export { isPathUnderAnchor, normalizeAnchorPath } from './base/ledger.ts';
 //# sourceMappingURL=ledger.d.ts.map

package/lib/types/protocol.d.ts

@@ -62,9 +62,6 @@ export interface ApiErrorBody {
 export declare const WORKSPACE_API_BASE: "/api/dsh-hardssh";
 export declare const WORKSPACE_API: {
     readonly state: string;
-    readonly tree: string;
-    readonly file: string;
-    readonly search: string;
     readonly sshWorkspaces: string;
     readonly sshWorkspaceDir: string;
 };
@@ -89,8 +86,6 @@ export interface SshWorkspaceRecord {
     /** When the record was created. */
     createdAt: string;
 }
-/** The ledger of SSH-bound workspaces (persisted by the host). */
-export type SshWorkspaceLedger = SshWorkspaceRecord[];
 /** One remote directory entry for the picker tree. */
 export interface RemoteDirEntry {
     name: string;

package/lib/types/providers/index.d.ts

@@ -8,11 +8,14 @@
 import type { WorkspaceProviderRegistry } from '../base/registry.ts';
 import type { SshEngine } from '../ssh/engine.ts';
 import type { HostStoreView } from '../core.ts';
-/** Register both built-in providers. Returns per-provider disposers. */
-export declare function registerBuiltinProviders(registry: WorkspaceProviderRegistry, deps?: {
+import type { Context } from '@deepseek-ai/cordis';
+/** Register both built-in providers. Returns per-provider disposers. The
+ *  Cordis context is mandatory: both providers serve only the real DSH
+ *  fs/process capabilities, which need a per-workspace Cordis scope. */
+export declare function registerBuiltinProviders(registry: WorkspaceProviderRegistry, deps: {
     engine?: SshEngine;
     hosts?: HostStoreView;
-}): Array<() => void>;
+}, context: Context): Array<() => void>;
 /** The canonical provider ids. */
 export declare const BUILTIN_PROVIDER_IDS: readonly ["local", "ssh"];
 export type BuiltinProviderId = (typeof BUILTIN_PROVIDER_IDS)[number];

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

@@ -1,39 +1,82 @@
 /**
- * Local provider — the workspace provider for local-disk workspaces. Direct
- * Node fs implementation of `WorkspaceFileSystem`, so the local provider is
- * usable OUTSIDE the dsh harness too (a consumer only needs `base`).
- *
- * The DSH runtime later re-wraps this over `dsh-fs-sandbox` / `dsh-fs-local`
- * for sandbox semantics when running inside the harness; the base contract
- * stays identical.
+ * Local workspace provider. Inside DSH it exposes the official FileSystem and
+ * SubprocessRuntime capability shapes, both confined to the record root. Pure
+ * base consumers without Cordis keep the lightweight path-style fallbacks.
  *
  * @module @tiphareth/dsh-hardssh/providers/local
  */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsPathInfo, FsTarget } from '@deepseek-ai/dsh-fs';
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local';
+import type { SubprocessHandle, SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import { LocalSubprocessRuntime } from '@deepseek-ai/dsh-subprocess-local';
 import type { WorkspaceCapabilityMap, WorkspaceConnection, WorkspaceProvider, WorkspaceProviderManifest } from '../../base/model.ts';
-import type { WorkspaceDirEntry, WorkspaceFileSystem, WorkspaceStat } from '../../base/capability.ts';
-/** The local provider manifest. */
+import type { WorkspaceDirEntry, WorkspaceFileSystem, WorkspaceProcessRuntime, WorkspaceStat } from '../../base/capability.ts';
+/** The local provider implements the same official v2 fs/process keys as SSH. */
 export declare const localProviderManifest: WorkspaceProviderManifest;
-/** One open local workspace connection. */
+/** Official DSH local filesystem with the record root promoted to a hard jail. */
+export declare class RootedLocalFileSystem extends LocalFileSystem {
+    readonly workspaceRoot: string;
+    constructor(ctx: Context, root: string);
+    /** LocalFileSystem.resolve() has no root jail, so this override adds one. */
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    /** LocalFileSystem.lstat() bypasses resolve(), so it needs the same explicit jail. */
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    /** LocalFileSystem maps every host path; a rooted capability must hide outsiders. */
+    processPathFromHostPath(hostPath: string): string | undefined;
+}
+/**
+ * Per-connection root guard over one shared official local subprocess runtime.
+ * LocalSubprocessRuntime cannot bind a record root and cannot tear down only
+ * one workspace's handles, so this facade adds both missing lifecycle facts.
+ */
+export declare class RootedLocalSubprocessRuntime {
+    private readonly runtime;
+    readonly workspaceRoot: string;
+    private readonly processes;
+    private readonly terminals;
+    constructor(runtime: LocalSubprocessRuntime, workspaceRoot: string);
+    /** The shared runtime already owns executable lookup; no root path is involved. */
+    resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+    /** LocalSubprocessRuntime.spawn() accepts any cwd, so this method fences it. */
+    spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    /** LocalSubprocessRuntime.spawnTerminal() accepts any cwd, so this method fences it. */
+    spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+    /** The shared runtime cannot close one workspace, so terminate only owned handles. */
+    close(): Promise<void>;
+}
+/** One open local workspace connection with identity-cached capabilities. */
 export declare class LocalWorkspaceConnection implements WorkspaceConnection {
     readonly workspaceId: string;
     private readonly root;
+    private readonly cordisContext?;
+    private readonly officialProcess?;
     readonly providerId = "local";
-    constructor(workspaceId: string, root: string);
+    private state;
+    private fsInstance;
+    private processInstance;
+    constructor(workspaceId: string, root: string, cordisContext?: Context | undefined, officialProcess?: LocalSubprocessRuntime | undefined);
+    /** A static manifest cannot return instances, so get() lazily caches each capability. */
     get<K extends keyof WorkspaceCapabilityMap>(capability: K): WorkspaceCapabilityMap[K] | undefined;
+    /** The old path-style wrapper is not a DSH FileSystem, so Cordis uses the official rooted backend. */
+    private fs;
+    /** The fs capability cannot spawn processes, so process has its own official rooted facade. */
+    private process;
+    /** Same honesty rule as the SSH connection: only states this object owns. */
     status(): 'connecting' | 'ready' | 'degraded' | 'closed';
+    /** Dropping references alone cannot stop live local processes, so close the rooted facade first. */
     close(): Promise<void>;
 }
-/**
- * Node-fs implementation of `WorkspaceFileSystem` confined to a root.
- * Workspace-relative paths (`/src/index.ts`, `src/index.ts`) are resolved
- * against the root; `..` escapes are rejected; symlinks are not followed
- * out of the root by the stat path (defense in depth — the contract says
- * the provider enforces confinement).
- */
+/** Standalone path-style filesystem fallback for consumers without Cordis. */
 export declare class LocalWorkspaceFileSystem implements WorkspaceFileSystem {
     private readonly root;
     constructor(root: string);
-    /** Resolve a workspace-relative path into an absolute path inside root. */
+    /** Node fs accepts arbitrary paths, so every fallback operation resolves through this jail. */
     private abs;
     stat(path: string, signal?: AbortSignal): Promise<WorkspaceStat | undefined>;
     list(path: string, signal?: AbortSignal): Promise<WorkspaceDirEntry[]>;
@@ -48,11 +91,28 @@ export declare class LocalWorkspaceFileSystem implements WorkspaceFileSystem {
         signal?: AbortSignal;
     }): Promise<void>;
     rename(from: string, to: string, signal?: AbortSignal): Promise<void>;
-    /** Convenience: check the root exists and is readable (for open()). */
+    /** WorkspaceProvider.open() cannot infer root availability from stat(undefined), so expose this probe. */
     accessible(): Promise<boolean>;
 }
-/** The local provider factory. */
-export declare function createLocalWorkspaceProvider(): WorkspaceProvider;
-/** Helper: title mostly used by record factories. */
+/** Standalone process fallback for base-only consumers without a Cordis runtime. */
+export declare class LocalWorkspaceProcess implements WorkspaceProcessRuntime {
+    private readonly root;
+    constructor(root: string);
+    /** LocalSubprocessRuntime needs Cordis, so standalone exec uses node:child_process with the same root jail. */
+    exec(command: string, options?: {
+        timeoutMs?: number;
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        timedOut?: boolean;
+        durationMs?: number;
+    }>;
+}
+/** The local provider factory; Context is optional only for standalone base consumers/tests. */
+export declare function createLocalWorkspaceProvider(context?: Context): WorkspaceProvider;
+/** basename() alone returns empty for filesystem roots, so retain the root as fallback. */
 export declare function localDefaultTitle(root: string): string;
 //# sourceMappingURL=provider.d.ts.map