@tiphareth/dsh-hardssh 0.1.2-alpha → 0.2.2

package/src/ssh/vault.ts

@@ -15,7 +15,7 @@
  */
 
 import { createCipheriv, createDecipheriv, createHash, randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { homedir } from 'node:os'
 
@@ -41,6 +41,8 @@ const LOCKOUT_FLOOR_MS = 30_000
 const LOCKOUT_CAP_MS = 3_600_000
 /** Fixed plaintext used to verify the unlock password. */
 const VERIFIER_TEXT = 'dsh-hardssh:vault:verify:v1'
+/** Minimum non-whitespace master-password length. */
+export const MIN_MASTER_PASSWORD_LENGTH = 8
 
 /** Types of secrets the vault stores. */
 export type VaultPurpose = 'host.password' | 'host.passphrase'
@@ -83,11 +85,64 @@ interface VaultDocument {
   secrets: VaultEntry[]
 }
 
-/** Default vault file location: <home>/.dsh/dsh-ssh-vault.json. */
+/**
+ * Directory holding the credential vault: `<home>/.dsh/ssh-secrets`.
+ *
+ * It IS inside `~/.dsh` (which the fs seam declares a local-infrastructure root
+ * so skills and plugin config stay readable), so its protection does NOT come
+ * from location — it comes from `SwitchFileSystem.deniedRoots` (fs.ts), which
+ * refuses this directory on every dispatch path, resolve to write, before any
+ * backend sees it.
+ *
+ * Residual risk, stated plainly: a command that runs on THIS machine as the
+ * same user (e.g. the client-side `pwsh` tool) can still read the file. What
+ * keeps the credential safe is that the file is encrypted (AES-256-GCM +
+ * scrypt) AND that environment auto-unlock is off by default — so a stolen
+ * ciphertext is only an offline scrypt target, not a usable credential.
+ */
+export function vaultDirectory(): string {
+  return join(homedir(), '.dsh', 'ssh-secrets')
+}
+
+/** Vault file location: <home>/.dsh/ssh-secrets/dsh-ssh-vault.json. */
 export function vaultPath(): string {
+  return join(vaultDirectory(), 'dsh-ssh-vault.json')
+}
+
+/** Pre-relocation vault location (<home>/.dsh/dsh-ssh-vault.json). */
+export function legacyVaultPath(): string {
   return join(homedir(), '.dsh', 'dsh-ssh-vault.json')
 }
 
+/**
+ * Move a pre-relocation vault into {@link vaultDirectory} on first use.
+ *
+ * Never destructive: the new location wins when both exist, and a failed move
+ * falls back to copying so the source file is left in place.
+ *
+ * @param target - destination path (defaults to {@link vaultPath}).
+ * @param legacy - source path (defaults to {@link legacyVaultPath}).
+ * @returns true when a move/copy happened.
+ */
+export function migrateLegacyVault(target: string = vaultPath(), legacy: string = legacyVaultPath()): boolean {
+  if (target === legacy) return false
+  if (existsSync(target) || !existsSync(legacy)) return false
+  try {
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 })
+    try {
+      renameSync(legacy, target)
+    } catch {
+      // Cross-device or locked source: copy the bytes and keep the original.
+      const contents = readFileSync(legacy)
+      writeFileSync(target, contents, { mode: 0o600 })
+    }
+    return true
+  } catch {
+    // Best-effort: an unmigratable legacy file still loads from its old path.
+    return false
+  }
+}
+
 /** AAD for one entry. */
 function entryAad(purpose: VaultPurpose, alias: string): string {
   return `dsh-hardssh:v1:${purpose}:${alias}`
@@ -143,35 +198,45 @@ export interface RevealedSecret {
  */
 export class Vault {
   private readonly path: string
-  private readonly passwordProvider: (() => Promise<string | undefined>) | undefined
   private document: VaultDocument = emptyDocument()
   private unlockedKey: Buffer | undefined
   private lockTimer: ReturnType<typeof setTimeout> | undefined
+  private readonly idleLockMs: number
   private readonly leaked = new Set<string>()
+  /** Whether `DSH_CREDENTIAL_PASSWORD` may unlock this instance at load. */
+  private readonly allowEnvUnlock: boolean
+  /** Single-instance mutation queue. Every operation that can change the
+   *  in-memory document or persist it runs in invocation order. The tail is
+   *  always recovered so one rejected mutation never poisons later work. */
+  private mutationTail: Promise<void> = Promise.resolve()
 
   constructor(
     filePath?: string,
     options?: {
-      /** Session password source (loopback unlock route passes a password). */
-      passwordProvider?: () => Promise<string | undefined>
       /** Vault idle auto-lock (ms); 0 disables (default 30 min). */
       idleLockMs?: number
+      /**
+       * Allow unlocking from `DSH_CREDENTIAL_PASSWORD` at construction.
+       * OFF by default: that variable is visible to anything running as the
+       * same user — including an agent session — so auto-unlock is an explicit
+       * opt-in (`vaultAutoUnlock: 'env'` in the plugin config), not a default.
+       */
+      allowEnvUnlock?: boolean
     },
   ) {
+    if (filePath === undefined) migrateLegacyVault()
     this.path = filePath ?? vaultPath()
-    this.passwordProvider = options?.passwordProvider
+    this.allowEnvUnlock = options?.allowEnvUnlock === true
     this.load()
-    // Auto-unlock from the DSH_CREDENTIAL_PASSWORD environment variable when
-    // present (headless / agent-friendly deterministic channel).
-    const env = process.env.DSH_CREDENTIAL_PASSWORD
+    // Opt-in auto-unlock from DSH_CREDENTIAL_PASSWORD (headless / unattended
+    // agents that deliberately enable it).
+    const env = this.allowEnvUnlock ? process.env.DSH_CREDENTIAL_PASSWORD : undefined
     if (env !== undefined && env !== '') {
       void this.tryEnvUnlock(env)
     }
     const idle = options?.idleLockMs ?? 30 * 60_000
-    if (idle > 0) {
-      this.lockTimer = setInterval(() => { this.lock() }, idle)
-      this.lockTimer.unref?.()
-    }
+    if (!Number.isSafeInteger(idle) || idle < 0) throw new VaultError('VAULT_CONFIG', 'idleLockMs must be a non-negative safe integer')
+    this.idleLockMs = idle
   }
 
   // ------------------------------------------------------------- internals
@@ -192,12 +257,19 @@ export class Vault {
     }
   }
 
-  private save(): void {
+  private save(): void { this.saveDocument(this.document) }
+
+  private saveDocument(document: VaultDocument): void {
     const dir = dirname(this.path)
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
-    const tmp = this.path + '.tmp'
-    writeFileSync(tmp, JSON.stringify(this.document, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
-    renameSync(tmp, this.path)
+    const tmp = this.path + `.tmp-${process.pid}-${randomBytes(6).toString('hex')}`
+    try {
+      writeFileSync(tmp, JSON.stringify(document, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+      renameSync(tmp, this.path)
+    } catch (error) {
+      try { unlinkSync(tmp) } catch { /* preserve the persistence error */ }
+      throw error
+    }
   }
 
   private deriveKey(password: string, kdf: VaultKdfParams): Promise<Buffer> {
@@ -237,6 +309,10 @@ export class Vault {
 
   private async verifyPassword(key: Buffer, password: string): Promise<void> {
     const doc = this.document
+    const previousMeta = { ...doc.meta }
+    const persistFailure = (): void => {
+      try { this.save() } catch (error) { doc.meta = previousMeta; throw error }
+    }
     const verifier = doc.verifier
     try {
       const plain = this.decryptEntryBuffer(key, verifier.aad, verifier.nonceB64, verifier.ciphertextB64, verifier.tagB64)
@@ -247,10 +323,10 @@ export class Vault {
       if (doc.meta.attempts >= LOCKOUT_THRESHOLD) {
         const backoff = backoffFor(doc.meta.attempts)
         doc.meta.lockedUntil = Date.now() + backoff
-        this.save()
+        persistFailure()
         throw new VaultLockoutError(`vault locked after ${doc.meta.attempts} failed attempts — retry after ${Math.ceil(backoff / 1000)}s`, backoff)
       }
-      this.save()
+      persistFailure()
       throw new VaultAuthError(`wrong vault password (${doc.meta.attempts}/${LOCKOUT_THRESHOLD} attempts used)`, LOCKOUT_THRESHOLD - doc.meta.attempts)
     }
   }
@@ -283,6 +359,30 @@ export class Vault {
     return this.unlockedKey
   }
 
+  private validateMasterPassword(password: string): void {
+    if (password.trim().length < MIN_MASTER_PASSWORD_LENGTH) {
+      throw new VaultError('VAULT_PASSWORD_WEAK', `vault password must contain at least ${MIN_MASTER_PASSWORD_LENGTH} non-whitespace characters`)
+    }
+  }
+
+  /** Successful credential activity extends the idle lock deadline. */
+  private touch(): void {
+    if (this.lockTimer !== undefined) clearTimeout(this.lockTimer)
+    this.lockTimer = undefined
+    if (this.unlockedKey === undefined || this.idleLockMs === 0) return
+    this.lockTimer = setTimeout(() => { this.lock() }, this.idleLockMs)
+    this.lockTimer.unref?.()
+  }
+
+  private enqueueMutation<T>(mutation: () => Promise<T> | T): Promise<T> {
+    const result = this.mutationTail.then(mutation)
+    this.mutationTail = result.then(
+      () => undefined,
+      () => undefined,
+    )
+    return result
+  }
+
   private async tryEnvUnlock(password: string): Promise<void> {
     try {
       await this.unlock(password)
@@ -298,60 +398,92 @@ export class Vault {
     const hasEntries = this.document.secrets.length > 0
     return {
       locked: this.unlockedKey === undefined || hasEntries === false && this.document.verifier.ciphertextB64 === '',
-      mode: process.env.DSH_CREDENTIAL_PASSWORD !== undefined ? 'env' : 'password',
+      mode: this.allowEnvUnlock && process.env.DSH_CREDENTIAL_PASSWORD !== undefined ? 'env' : 'password',
       entries: this.document.secrets.length,
     }
   }
 
   /** Unlock with a password (loopback route / env). Persists lockout on failure. */
   async unlock(password: string): Promise<void> {
-    if (this.unlockedKey !== undefined) return
-    this.checkLockout()
-    const doc = this.document
-    if (doc.verifier.ciphertextB64 === '') {
-      // First unlock: create the verifier with this password.
-      const salt = randomBytes(SALT_BYTES)
-      const kdf: VaultKdfParams = { algorithm: 'scrypt', N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, saltB64: salt.toString('base64') }
-      const key = await this.deriveKey(password, kdf)
-      doc.kdf = kdf
-      const box = this.encryptEntryBuffer(key, entryAad('host.password', 'vault-verify'), Buffer.from(VERIFIER_TEXT, 'utf8'))
-      doc.verifier = { ...box, aad: entryAad('host.password', 'vault-verify') }
+    return this.enqueueMutation(async () => {
+      this.validateMasterPassword(password)
+      if (this.unlockedKey !== undefined) { this.touch(); return }
+      this.checkLockout()
+      const doc = this.document
+      if (doc.verifier.ciphertextB64 === '') {
+        // First unlock: create the verifier with this password.
+        const salt = randomBytes(SALT_BYTES)
+        const kdf: VaultKdfParams = { algorithm: 'scrypt', N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, saltB64: salt.toString('base64') }
+        const key = await this.deriveKey(password, kdf)
+        const box = this.encryptEntryBuffer(key, entryAad('host.password', 'vault-verify'), Buffer.from(VERIFIER_TEXT, 'utf8'))
+        const next: VaultDocument = {
+          ...doc,
+          kdf,
+          verifier: { ...box, aad: entryAad('host.password', 'vault-verify') },
+        }
+        try {
+          this.saveDocument(next)
+        } catch (error) {
+          key.fill(0)
+          throw error
+        }
+        this.document = next
+        this.unlockedKey = key
+        this.touch()
+        return
+      }
+      const key = await this.deriveKey(password, doc.kdf)
+      try {
+        await this.verifyPassword(key, password)
+      } catch (error) {
+        key.fill(0)
+        throw error
+      }
       this.unlockedKey = key
-      this.save()
-      return
-    }
-    const key = await this.deriveKey(password, doc.kdf)
-    await this.verifyPassword(key, password)
-    this.unlockedKey = key
+      this.touch()
+    })
   }
 
   /** Lock: drop the in-memory key. JS strings cannot be zeroized; the Buffer
    *  key is wiped. */
   lock(): void {
+    if (this.lockTimer !== undefined) clearTimeout(this.lockTimer)
+    this.lockTimer = undefined
     if (this.unlockedKey !== undefined) {
       this.unlockedKey.fill(0)
       this.unlockedKey = undefined
     }
+    // JS strings cannot be zeroized, but dropping every reference bounds the
+    // leak-guard plaintext lifetime to one unlocked activity session.
+    this.leaked.clear()
   }
 
   /** Store one secret, returning a random ref. Requires unlock. */
   async store(purpose: VaultPurpose, alias: string, secret: string): Promise<string> {
-    const key = this.requireKey()
-    const ref = 'vlt_' + randomBytes(16).toString('hex')
-    const aad = entryAad(purpose, alias)
-    const box = this.encryptEntryBuffer(key, aad, Buffer.from(secret, 'utf8'))
-    const data = `${box.nonceB64}${box.ciphertextB64}${box.tagB64}`
-    const entry: VaultEntry = {
-      ref,
-      purpose,
-      alias,
-      ...box,
-      aad,
-      sha3: sha3_256Hex(data),
-    }
-    this.document.secrets.push(entry)
-    this.save()
-    return ref
+    return this.enqueueMutation(() => {
+      const key = this.requireKey()
+      const ref = 'vlt_' + randomBytes(16).toString('hex')
+      const aad = entryAad(purpose, alias)
+      const box = this.encryptEntryBuffer(key, aad, Buffer.from(secret, 'utf8'))
+      const data = `${box.nonceB64}${box.ciphertextB64}${box.tagB64}`
+      const entry: VaultEntry = {
+        ref,
+        purpose,
+        alias,
+        ...box,
+        aad,
+        sha3: sha3_256Hex(data),
+      }
+      this.document.secrets.push(entry)
+      try {
+        this.save()
+      } catch (error) {
+        this.document.secrets.pop()
+        throw error
+      }
+      this.touch()
+      return ref
+    })
   }
 
   /** Reveal one secret (unlock required); registers it for redaction. */
@@ -368,53 +500,75 @@ export class Vault {
     const text = plain.toString('utf8')
     plain.fill(0)
     this.leaked.add(text)
+    this.touch()
     return text
   }
 
   /** Delete one secret (host delete / cleanup). */
   async remove(ref: string): Promise<void> {
-    const before = this.document.secrets.length
-    this.document.secrets = this.document.secrets.filter(entry => entry.ref !== ref)
-    if (this.document.secrets.length !== before) this.save()
+    return this.enqueueMutation(() => {
+      this.requireKey()
+      const before = this.document.secrets
+      const next = before.filter(entry => entry.ref !== ref)
+      if (next.length !== before.length) {
+        this.document.secrets = next
+        try { this.save() } catch (error) { this.document.secrets = before; throw error }
+      }
+      this.touch()
+    })
   }
 
   /** Rekey with a new password: decrypt all, re-encrypt under a fresh KDF. */
   async rekey(newPassword: string): Promise<void> {
-    const key = this.requireKey()
-    const doc = this.document
-    // Decrypt everything with the current key.
-    const plaintexts: Array<{ purpose: VaultPurpose; alias: string; value: string }> = []
-    for (const entry of doc.secrets) {
-      const plain = this.decryptEntryBuffer(key, entry.aad, entry.nonceB64, entry.ciphertextB64, entry.tagB64)
-      plaintexts.push({ purpose: entry.purpose, alias: entry.alias, value: plain.toString('utf8') })
-      plain.fill(0)
-    }
-    // Fresh KDF + verifier under the new password.
-    const salt = randomBytes(SALT_BYTES)
-    const kdf: VaultKdfParams = { algorithm: 'scrypt', N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, saltB64: salt.toString('base64') }
-    const newKey = await this.deriveKey(newPassword, kdf)
-    doc.kdf = kdf
-    const box = this.encryptEntryBuffer(newKey, entryAad('host.password', 'vault-verify'), Buffer.from(VERIFIER_TEXT, 'utf8'))
-    doc.verifier = { ...box, aad: entryAad('host.password', 'vault-verify') }
-    doc.secrets = plaintexts.map(({ purpose, alias, value }, index) => {
-      const aad = entryAad(purpose, alias)
-      const b = this.encryptEntryBuffer(newKey, aad, Buffer.from(value, 'utf8'))
-      const data = `${b.nonceB64}${b.ciphertextB64}${b.tagB64}`
-      return {
-        // Preserve the original ref: SshHostEntry.auth.secretRef persists it.
-        ref: rekeyOriginalRef(this.document.secrets[index]),
-        purpose,
-        alias,
-        ...b,
-        aad,
-        sha3: sha3_256Hex(data),
-      } satisfies VaultEntry
+    return this.enqueueMutation(async () => {
+      this.validateMasterPassword(newPassword)
+      const key = this.requireKey()
+      const doc = this.document
+      // Decrypt everything with the current key.
+      const plaintexts: Array<{ purpose: VaultPurpose; alias: string; value: string }> = []
+      for (const entry of doc.secrets) {
+        const plain = this.decryptEntryBuffer(key, entry.aad, entry.nonceB64, entry.ciphertextB64, entry.tagB64)
+        plaintexts.push({ purpose: entry.purpose, alias: entry.alias, value: plain.toString('utf8') })
+        plain.fill(0)
+      }
+      // Fresh KDF + verifier under the new password.
+      const salt = randomBytes(SALT_BYTES)
+      const kdf: VaultKdfParams = { algorithm: 'scrypt', N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, saltB64: salt.toString('base64') }
+      const newKey = await this.deriveKey(newPassword, kdf)
+      try {
+        const box = this.encryptEntryBuffer(newKey, entryAad('host.password', 'vault-verify'), Buffer.from(VERIFIER_TEXT, 'utf8'))
+        const secrets = plaintexts.map(({ purpose, alias, value }, index) => {
+          const aad = entryAad(purpose, alias)
+          const b = this.encryptEntryBuffer(newKey, aad, Buffer.from(value, 'utf8'))
+          const data = `${b.nonceB64}${b.ciphertextB64}${b.tagB64}`
+          return {
+            ref: rekeyOriginalRef(doc.secrets[index]),
+            purpose,
+            alias,
+            ...b,
+            aad,
+            sha3: sha3_256Hex(data),
+          } satisfies VaultEntry
+        })
+        const next: VaultDocument = {
+          ...doc,
+          kdf,
+          verifier: { ...box, aad: entryAad('host.password', 'vault-verify') },
+          meta: { attempts: 0, lockedUntil: 0 },
+          secrets,
+        }
+        this.saveDocument(next)
+        key.fill(0)
+        this.document = next
+        this.unlockedKey = newKey
+        this.touch()
+      } catch (error) {
+        newKey.fill(0)
+        throw error
+      } finally {
+        for (const item of plaintexts) item.value = ''
+      }
     })
-    this.unlockedKey?.fill(0)
-    this.unlockedKey = newKey
-    doc.meta.attempts = 0
-    doc.meta.lockedUntil = 0
-    this.save()
   }
 
   /** Redact every leaked secret value in `text` (Leak Guard light). */
@@ -429,7 +583,7 @@ export class Vault {
 
   /** Dispose: wipe the key and stop the idle timer. */
   dispose(): void {
-    if (this.lockTimer !== undefined) clearInterval(this.lockTimer)
+    if (this.lockTimer !== undefined) clearTimeout(this.lockTimer)
     this.lock()
   }
 }

package/src/subprocess.ts

@@ -1,71 +1,88 @@
-/**
- * The `ctx.subprocess` switch row: provides the workspace-routing subprocess
- * facade in the host scope. The local runtime is mounted in an isolated
- * child scope; every SSH-bound workspace record gets its OWN remote runtime
- * bound to that record's alias + remote root; the facade routes each spawn by
- * its cwd. The facade auto-provides `subprocess` here because the plain
- * subprocess row is disabled by the profile patch.
- *
- * Routing and per-record remote runtimes are owned by the SHARED seam state
- * (hardsshCore.seams): the row binds its per-record runtime factory and reads
- * the state on every spawn. 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.
- *
- * @module dsh-hardssh/subprocess
- */
-
-import type { Context } from '@deepseek-ai/cordis'
-import { LocalSubprocessRuntime } from '@deepseek-ai/dsh-subprocess-local'
-import type { HardsshCore } from './core.ts'
-import { isPathUnderAnchor } from './ledger.ts'
-import type { WorkspaceState } from './protocol.ts'
-import { SshSubprocessRuntime } from './remote/remote-subprocess.ts'
-import { SwitchSubprocessRuntime } from './switch/switch-subprocess.ts'
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    hardsshCore: HardsshCore
-  }
-}
-
-/** Stable cordis plugin name. */
-export const name = 'hardssh-subprocess'
-
-/** Services required: the shared workspace core (mode store + engine). */
-export const inject = ['hardsshCore']
-
-/** A remote runtime fixed to one SSH workspace's alias + remote root. */
-function fixedRemoteState(alias: string, remoteRoot: string): () => WorkspaceState {
-  return () => ({ mode: 'remote' as const, alias, remoteRoot })
-}
-
-/** Mount the switching subprocess facade. */
-export function apply(ctx: Context): void {
-  const core = ctx.hardsshCore
-
-  // Local runtime in an isolated scope (its `subprocess` provide shadows only
-  // below this scope). Construct directly and keep the instance.
-  const localCtx = ctx.isolate('subprocess')
-  const localSubprocess = new LocalSubprocessRuntime(localCtx)
-
-  // Bind the per-record remote runtime builder into the shared seam state;
-  // instances are built lazily on first route and reused across refreshes.
-  core.seams.bindSub((record) => new SshSubprocessRuntime(ctx.isolate('subprocess'), core.engine, fixedRemoteState(record.alias, record.remoteRoot)))
-
-  const anchorRoot = core.ledger.anchorsRoot()
-  let warnedUnready = false
-
-  new SwitchSubprocessRuntime(ctx, {
-    local: localSubprocess,
-    worldFor: (cwd) => {
-      if (!core.seams.isReady() && !warnedUnready && cwd !== undefined && isPathUnderAnchor(anchorRoot, cwd)) {
-        warnedUnready = true
-        console.warn('[dsh-hardssh] subprocess routing is not ready yet (workspace ledger still loading) — running locally until the snapshot is applied')
-      }
-      return core.seams.runtimeForSub(cwd) ?? localSubprocess
-    },
-  })
-}
+/**
+ * The `ctx.subprocess` switch row: provides the generic WorkspaceCore-routing
+ * subprocess facade in the host scope. The local runtime is mounted in an
+ * isolated child scope; each spawn resolves by cwd through the same workspace
+ * router used by the filesystem seam.
+ *
+ * A bound connection supplies `workspace.process`. Before the core is ready,
+ * or for an unowned cwd beneath the managed SSH anchor root, spawning fails
+ * closed rather than executing on the client machine.
+ *
+ * @module dsh-hardssh/subprocess
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { LocalSubprocessRuntime } from '@deepseek-ai/dsh-subprocess-local'
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess'
+import { anchorRoot, isPathUnderAnchor } from './ledger.ts'
+import { SwitchSubprocessRuntime } from './switch/switch-subprocess.ts'
+import type { WorkspaceCore } from './runtime/workspace-core.ts'
+import type { WorkspaceRecord } from './base/model.ts'
+
+/** Stable cordis plugin name. */
+export const name = 'hardssh-subprocess'
+
+/** Workspace routing is exclusively provided by the generic core. */
+export const inject = ['workspaceCore']
+
+/** The record behind a router connection (sync snapshot lookup). */
+function genericRecordFor(core: WorkspaceCore, id: string): WorkspaceRecord | undefined {
+  return core.ledger.snapshotSync().records.find(record => record.id === id)
+}
+
+/** Resolve the subprocess runtime owning a cwd, or undefined when local. */
+export function genericSubprocessFor(
+  core: WorkspaceCore,
+  cwd: string | undefined,
+  reservedAnchorRoots: readonly string[],
+): SubprocessRuntime | undefined {
+  if (!core.isReady()) {
+    if (cwd !== undefined && reservedAnchorRoots.some(root => isPathUnderAnchor(root, cwd))) {
+      throw new Error('subprocess-ssh: workspace routing is unavailable while the generic workspace core is not ready (anchor path fails closed)')
+    }
+    return undefined
+  }
+  const connection = core.router.fromAnchor(cwd)
+  if (connection === undefined) return undefined
+  const record = genericRecordFor(core, connection.workspaceId)
+  if (record === undefined) throw new Error(`subprocess-workspace: routed workspace '${connection.workspaceId}' is missing from the ledger`)
+  const runtime = connection.get('workspace.process') as SubprocessRuntime | undefined
+  if (runtime === undefined) throw new Error(`subprocess-workspace: workspace '${record.id}' provides no workspace.process capability`)
+  return runtime
+}
+
+/** Mount the generic switching subprocess facade. */
+export function apply(ctx: Context): void {
+  const localCtx = ctx.isolate('subprocess')
+  const localSubprocess = new LocalSubprocessRuntime(localCtx)
+  const ws = ctx.workspaceCore
+  const anchorRootDir = anchorRoot()
+  let warnedUnready = false
+
+  new SwitchSubprocessRuntime(ctx, {
+    local: localSubprocess,
+    // `undefined` means LOCAL. Returning the local runtime here instead would
+    // force the facade to identity-compare it against `deps.local`, and that
+    // comparison is not reliable for a container-provided service — it once
+    // made the client-search refusal fire for local sessions and broke
+    // glob/grep in every session.
+    worldFor: (cwd) => {
+      if (!ws.isReady()) {
+        if (cwd !== undefined && isPathUnderAnchor(anchorRootDir, cwd)) {
+          if (!warnedUnready) {
+            warnedUnready = true
+            console.warn('[dsh-hardssh] subprocess routing is not ready yet (workspace core still initializing or failed) — refusing to run beneath the workspace anchor root')
+          }
+          throw new Error('subprocess-ssh: workspace routing is unavailable while the generic workspace core is not ready (anchor path fails closed)')
+        }
+        return undefined
+      }
+      const runtime = genericSubprocessFor(ws, cwd, [anchorRootDir])
+      if (runtime !== undefined) return runtime
+      if (cwd !== undefined && isPathUnderAnchor(anchorRootDir, cwd)) {
+        throw new Error(`subprocess-ssh: '${cwd}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`)
+      }
+      return undefined
+    },
+  })
+}