@tiphareth/dsh-hardssh 0.1.2-alpha

package/src/index.ts

@@ -0,0 +1,244 @@
+/**
+ * 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
+ * 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
+ * operations and SSH operations ride ONE shared SshEngine/HostStore over
+ * ~/.dsh/dsh-ssh.json (a single connection pool; SSH ops and workspaces
+ * invalidate together on config change). The browser half (./client) renders
+ * 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
+ * (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.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import z from '@deepseek-ai/schemastery'
+import type { HardsshCore } from './core.ts'
+import { SshWorkspaceLedger } from './ledger.ts'
+import type { SshWorkspaceRecord } from './protocol.ts'
+import { LedgerWorkspaceFileService } from './backend.ts'
+import { RemoteWorkspaceRunner } from './remote-runner.ts'
+import { makeRoutes } from './routes.ts'
+import { makeWorkspaceTools } from './tools.ts'
+import { WorkspaceSeamState } from './seam-state.ts'
+import { SshEngine } from './ssh/engine.ts'
+import { mountSshCapability } from './ssh/plugin.ts'
+import { HostStore } from './ssh/store.ts'
+import { SecureHostStore } from './ssh/store.ts'
+import { KnownHostsStore } from './ssh/known-hosts.ts'
+import { Vault } from './ssh/vault.ts'
+import { RemoteSearchService } from './remote-search.ts'
+import { mountWorkspaceCore } from './runtime/workspace-core.ts'
+
+/** Stable cordis plugin name. */
+export const name = 'hardssh'
+
+/**
+ * Services required before the workspace surfaces can mount. `webServer` is
+ * deliberately NOT here: headless profiles lack it, and a hard inject would
+ * block the whole load tree — routes register through the dynamic
+ * ctx.inject(['webServer'], …) below (DSH 插件规范 §4.2).
+ */
+export const inject = ['tools', 'systemPrompt']
+
+/** Plugin config (schemastery; optional fields use .default, never .optional). */
+export interface Config {
+  /** Master switch (default on). Disabling requires reverting the profile seam patch. */
+  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.
+   */
+  secretStorage: 'none' | 'vault'
+}
+
+export const Config: z<Config> = z.object({
+  enabled: z.boolean().default(true),
+  announceToAgent: z.boolean().default(true),
+  secretStorage: z.union([z.const('none'), z.const('vault')]).default('none'),
+})
+
+/** Order of the announcement section (right after the dsh-ssh section at 150). */
+const SECTION_ORDER = 160
+
+/** Tools that execute a WINDOWS-format binary locally and therefore cannot
+ *  work when the spawn routes to a remote host (glob/grep spawn the packaged
+ *  ripgrep, pwsh spawns powershell). Blocked with a clear error in SSH-bound
+ *  sessions instead of failing with "No such file or directory". */
+const REMOTE_INCOMPATIBLE_TOOLS = new Set(['glob', 'grep', 'pwsh'])
+
+/** Minimal shape of the assembly context the guidance section reads. The DSH
+ *  type (`AssembleContext`) only declares scope/signal, but the agent loop
+ *  passes `{ agent, scope, signal }` (see dsh-agent assembleContextFor). */
+interface GuidanceAssemblyContext {
+  agent?: { session?: { header?: { cwd?: string } } }
+}
+
+/** Render the workspace guidance from the LEDGER facts for this session:
+ *  a cwd the ledger binds renders the remote branch (with the real alias /
+ *  remote root), everything else the local branch. No path-string matching. */
+function renderWorkspaceGuidance(ledger: SshWorkspaceLedger, context: unknown): string {
+  const agent = (context as GuidanceAssemblyContext).agent
+  const cwd = agent?.session?.header?.cwd
+  const record = cwd === undefined || cwd === '' ? undefined : ledger.findByAnchorSync(cwd)
+  if (record === undefined) return localGuidance()
+  return remoteGuidance(record)
+}
+
+/** Local-session branch of the announcement. */
+function localGuidance(): string {
+  return '本机已安装 dsh-hardssh 插件（SSH 工作区）。当前会话是本机工作区：正常使用全部工具（pwsh / glob / grep / read / write / edit），文件操作在本机。remote_ls / remote_search / remote_status 与 ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster 用于一次性远程运维（消耗真实远程资源，先确认再执行）。用户提到「SSH 工作区 / 远程工作区 / 远程文件 / 远程项目 / 远程服务器上改代码」时即指本插件。'
+}
+
+/** SSH-bound-session branch of the announcement. */
+function remoteGuidance(record: SshWorkspaceRecord): string {
+  return `本机已安装 dsh-hardssh 插件（SSH 工作区）。当前会话绑定到远程工作区「${record.title}」（${record.alias} @ ${record.remoteRoot}）：
+- read / write / edit 自动路由到远程（SFTP）；路径用远程绝对路径（如 ${record.remoteRoot}/src/main.ts），相对路径以远程根目录为基准。
+- glob / grep / pwsh 在本工作区不可用（已被自动拦截并返回明确错误），请改用 remote_search（mode="glob" 按文件名、mode="grep" 按固定字符串搜内容）、remote_ls、remote_status、ssh_exec。
+- 远程操作消耗真实远程资源，先确认再执行；remote_search 有限深与条数上限。`
+}
+
+/**
+ * Mount the mode store, routes, tools, announcement, guard, and the shared core.
+ * @param ctx - host plugin context carrying tools/systemPrompt (webServer optional).
+ * @param config - resolved plugin config (schema defaults applied by the loader).
+ */
+export function apply(ctx: Context, config?: Config): void {
+  const resolved = {
+    enabled: config?.enabled ?? true,
+    announceToAgent: config?.announceToAgent ?? true,
+    // Secret storage: 'none' (VSCode Remote-SSH style; default) or 'vault'.
+    secretStorage: config?.secretStorage ?? 'none' as const,
+  }
+
+  // Host-key TOFU: connections are refused until the operator confirms the
+  // server fingerprint (see known-hosts.ts). Default-enabled for new installs;
+  // the engine falls back to pre-security behavior when no store is passed.
+  const knownHosts = new KnownHostsStore()
+  // Credential handling per secretStorage:
+  // - 'vault': encrypt at rest (AES-256-GCM + scrypt) via SecureHostStore;
+  //   for unattended agents running password hosts.
+  // - 'none' (default): passwords are NEVER persisted — they are prompted
+  //   once per session (VSCode Remote-SSH style) and held in the engine's
+  //   in-memory session table for the connection pool lifetime.
+  const vault = resolved.secretStorage === 'vault' ? new Vault() : undefined
+  const secureHosts = new SecureHostStore(vault, undefined, undefined, resolved.secretStorage)
+  const engine = new SshEngine(secureHosts, undefined, {
+    knownHosts,
+    resolveSecrets: (entry) => secureHosts.resolveAuth(entry),
+  })
+  const search = new RemoteSearchService(engine)
+  const ledger = new SshWorkspaceLedger()
+  const seams = new WorkspaceSeamState(ledger)
+  ctx.effect(() => () => {
+    engine.dispose()
+    vault?.dispose()
+  }, 'dsh-hardssh: engine')
+
+  // The shared core is ALWAYS provided: the seam-switch rows (./fs,
+  // ./subprocess) inject it, and they replace the deployment's fs/subprocess
+  // providers — starving them would break the model's file tools.
+  const runner = new RemoteWorkspaceRunner(engine, ledger)
+  const core: HardsshCore = { hosts: secureHosts, engine, ledger, seams, resolveRemote: (root) => runner.resolveRemote(root) }
+  ctx.provide('hardsshCore', core)
+  // Workspace clients (e.g. dsh-workbench-tiphareth) may read the SSH
+  // workspace core under the legacy `sshWorkspaceCore` service name —
+  // provide the same instance under both names so SSH-mode fs/git
+  // delegation actually engages.
+  ctx.provide('sshWorkspaceCore', core)
+
+  // Generic workspace base: canonical `workspaceCore` service carrying the
+  // provider-agnostic ledger/registry/router + builtin providers (local/ssh).
+  // Third-party plugins consume this; the legacy aliases above keep existing
+  // consumers working unchanged.
+  mountWorkspaceCore(ctx, { engine, hosts: secureHosts })
+
+  // Keep the shared seam state in sync with the ledger (synchronous re-apply
+  // on every commit + initial load). Registered before the enabled switch so
+  // routing stays consistent even when the agent-facing surfaces are off.
+  ctx.effect(() => seams.attach(), 'dsh-hardssh: seam state')
+
+  // SSH operations capability (host manager, ssh_* tools, /api/dsh-ssh,
+  // terminal, settings, prompt) — mounted against the SAME engine/store and
+  // kept independent of the workspace `enabled` switch below (its own
+  // `dsh-ssh` settings namespace toggles it).
+  mountSshCapability(ctx, { store: secureHosts, engine, knownHosts, vault, ledger })
+
+  if (!resolved.enabled) return
+
+  // Host workspace registration hooks (make the anchor a real sidebar
+  // workspace). workspaceRegistry is optional — headless profiles lack it.
+  const registerHostWorkspace = async (anchorPath: string, title: string): Promise<void> => {
+    const registry = ctx.get('workspaceRegistry') as { resolveByPath?: (path: string) => Promise<{ id: string } | undefined>; create?: (path: string, title?: string) => Promise<{ id: string }> } | undefined
+    if (registry?.create === undefined) return
+    const existing = registry.resolveByPath !== undefined ? await registry.resolveByPath(anchorPath) : undefined
+    if (existing !== undefined) return
+    await registry.create(anchorPath, title)
+  }
+  const unregisterHostWorkspace = async (anchorPath: string): Promise<void> => {
+    const registry = ctx.get('workspaceRegistry') as { resolveByPath?: (path: string) => Promise<{ id: string } | undefined>; delete?: (id: string) => Promise<boolean> } | undefined
+    if (registry?.resolveByPath === undefined || registry.delete === undefined) return
+    const existing = await registry.resolveByPath(anchorPath)
+    if (existing !== undefined) await registry.delete(existing.id)
+  }
+
+  const routes = makeRoutes({
+    hosts: secureHosts,
+    engine,
+    ledger,
+    files: new LedgerWorkspaceFileService(ledger, engine, search),
+    registerHostWorkspace,
+    unregisterHostWorkspace,
+  })
+  // webServer is optional (headless profiles lack it): dynamic inject keeps
+  // this plugin loadable everywhere, mounting routes only when it appears.
+  // The inject callback receives a scoped Context with the service available.
+  ctx.inject(['webServer'], (scoped) => {
+    const disposers = routes.map(route => scoped.webServer.register(route))
+    return () => {
+      for (const dispose of disposers) dispose()
+    }
+  })
+
+  const tools = makeWorkspaceTools({ engine, ledger, search })
+  ctx.effect(() => {
+    const disposers = tools.map(tool => ctx.tools.register(tool))
+    return () => {
+      for (const dispose of disposers) dispose()
+    }
+  }, 'dsh-hardssh: tools')
+
+  // Global guard: deny glob/grep/pwsh in SSH-bound sessions with a clear
+  // reason (their executables are Windows-format and cannot run on the
+  // remote host); every other session is untouched.
+  ctx.effect(() => ctx.tools.guard((execution) => {
+    if (execution.agent === undefined || !REMOTE_INCOMPATIBLE_TOOLS.has(execution.name)) return undefined
+    const cwd = execution.agent.session?.header?.cwd
+    if (cwd === undefined || cwd === '') return undefined
+    const record = ledger.findByAnchorSync(cwd)
+    if (record === undefined) return undefined
+    return `当前会话绑定 SSH 远程工作区「${record.title}」（${record.alias} @ ${record.remoteRoot}），${execution.name} 的可执行文件是 Windows 格式、在远程主机上不存在，已被拦截。请改用 remote_search / remote_ls / ssh_exec 操作远程文件与命令，或使用 read / write / edit（自动路由到远程）。`
+  }), 'dsh-hardssh: remote-incompatible tool guard')
+
+  if (resolved.announceToAgent) {
+    ctx.systemPrompt.section({
+      name: 'plugin:dsh-hardssh',
+      order: SECTION_ORDER,
+      text: (context) => renderWorkspaceGuidance(ledger, context),
+    })
+  }
+}

package/src/ledger.ts

@@ -0,0 +1,416 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @module dsh-hardssh/ledger
+ */
+
+import { randomUUID } from 'node:crypto'
+import { realpathSync } from 'node:fs'
+import {
+  mkdir,
+  readFile,
+  rename as renameFile,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, posix } from 'node:path'
+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
+
+/** The change payload before the committed revision is stamped on. */
+type LedgerChangeWithoutRevision =
+  | { type: 'created'; record: SshWorkspaceRecord }
+  | { type: 'renamed'; before: SshWorkspaceRecord; record: SshWorkspaceRecord }
+  | { type: 'removed'; record: SshWorkspaceRecord }
+
+/** Ledger file location: ~/.dsh/dsh-hardssh-workspaces.json. */
+export function ledgerPath(): string {
+  return join(homedir(), '.dsh', 'dsh-hardssh-workspaces.json')
+}
+
+/**
+ * Normalize a remote POSIX root: keep '/' as '/', collapse repeated
+ * separators and dot segments, reject relative paths and NUL.
+ */
+export function normalizeRemoteRoot(raw: string): string {
+  if (raw.includes('\0')) {
+    throw new Error(`remoteRoot must not contain NUL (got '${raw}')`)
+  }
+  const normalized = posix.normalize(raw.trim())
+  if (!normalized.startsWith('/')) {
+    throw new Error(`remoteRoot must be an absolute POSIX path (got '${raw}')`)
+  }
+  return normalized === '/' ? '/' : normalized.replace(/\/+$/, '')
+}
+
+/** Anchor roots: ~/.dsh/ssh-workspaces/<id>/ — visible in the sidebar as
+ *  ordinary host workspaces (and thus selectable for sessions). */
+export function anchorRoot(): string {
+  return join(homedir(), '.dsh', 'ssh-workspaces')
+}
+
+/** The anchor directory for one id. */
+export function anchorPathFor(id: string): string {
+  return join(anchorRoot(), id)
+}
+
+/** Default record title when the user gives none. */
+export function defaultTitle(remoteRoot: string, alias: string): string {
+  return `${alias}:${remoteRoot.split('/').filter(Boolean).pop() ?? remoteRoot}`
+}
+
+/**
+ * Normalize a local anchor path for comparison: Windows anchors are
+ * case-insensitive with mixed separators; POSIX anchors stay case-sensitive.
+ */
+export function normalizeAnchorPath(path: string): string {
+  const windowsStyle = isWindowsAnchor(path)
+  if (windowsStyle) {
+    const normalized = path.replace(/\//g, '\\')
+    const rootLength = windowsRootLength(normalized)
+    return trimTrailingSeparators(normalized, rootLength).toLowerCase()
+  }
+  const rootLength = path.startsWith('/') ? 1 : 0
+  return trimTrailingSeparators(path, rootLength)
+}
+
+/** True when candidate equals anchor or is one of its descendants. Lexical
+ *  comparison over already-resolved paths; deliberately no fs access. */
+export function isPathUnderAnchor(anchor: string, candidate: string): boolean {
+  const windowsStyle = isWindowsAnchor(anchor)
+  const normalizedAnchor = normalizeAnchorPath(anchor)
+
+  let normalizedCandidate: string
+  if (windowsStyle) {
+    const withWindowsSeparators = candidate.replace(/\//g, '\\')
+    const rootLength = windowsRootLength(withWindowsSeparators)
+    normalizedCandidate = trimTrailingSeparators(withWindowsSeparators, rootLength).toLowerCase()
+  } else {
+    const rootLength = candidate.startsWith('/') ? 1 : 0
+    normalizedCandidate = trimTrailingSeparators(candidate, rootLength)
+  }
+
+  if (normalizedCandidate === normalizedAnchor) return true
+
+  const separator = windowsStyle ? '\\' : '/'
+  const descendantPrefix = normalizedAnchor.endsWith(separator)
+    ? normalizedAnchor
+    : `${normalizedAnchor}${separator}`
+  return normalizedCandidate.startsWith(descendantPrefix)
+}
+
+/**
+ * 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.
+ */
+export class SshWorkspaceLedger {
+  private records: SshWorkspaceRecord[] | undefined
+  private loadPromise: Promise<void> | undefined
+  private anchorIndex: Array<{ anchor: string; record: SshWorkspaceRecord }> = []
+  private mutationTail: Promise<void> = Promise.resolve()
+  private currentRevision = 0
+  private readonly listeners = new Set<LedgerListener>()
+
+  /** Overridable file location (tests isolate per instance). */
+  constructor(private readonly fileOverride?: string, private readonly anchorOverride?: string) {}
+
+  private file(): string {
+    return this.fileOverride ?? ledgerPath()
+  }
+
+  private anchors(): string {
+    return this.anchorOverride ?? anchorRoot()
+  }
+
+  private anchorFor(id: string): string {
+    return join(this.anchors(), id)
+  }
+
+  /** Load the ledger once (missing/unreadable/malformed file -> empty ledger). */
+  private async ensureLoaded(): Promise<void> {
+    if (this.records !== undefined) return
+    if (this.loadPromise === undefined) {
+      this.loadPromise = this.readRecords()
+    }
+    await this.loadPromise
+  }
+
+  private async readRecords(): Promise<void> {
+    try {
+      const text = await readFile(this.file(), 'utf8')
+      const parsed = JSON.parse(text) as unknown
+      this.records = Array.isArray(parsed) ? parsed.filter(isRecord).map(cloneRecord) : []
+    } catch {
+      this.records = []
+    }
+    this.reindex()
+  }
+
+  /** Rebuild the synchronous anchor index from the current records. */
+  private reindex(): void {
+    this.anchorIndex = (this.records ?? [])
+      .map((record) => ({ anchor: normalizeAnchorPath(record.anchorPath), record }))
+      .sort((a, b) => b.anchor.length - a.anchor.length) // longest prefix first
+  }
+
+  /** Persist a proposed record array without touching observable state. */
+  private async save(nextRecords: readonly SshWorkspaceRecord[]): Promise<void> {
+    const target = this.file()
+    await mkdir(join(target, '..'), { recursive: true })
+    const temporary = `${target}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`
+    try {
+      await writeFile(temporary, JSON.stringify(nextRecords, null, 2), 'utf8')
+      await renameFile(temporary, target)
+    } catch (error) {
+      await rm(temporary, { force: true }).catch(() => undefined)
+      throw error
+    }
+  }
+
+  /** Serialize one mutation; a rejected earlier mutation never poisons later ones. */
+  private enqueueMutation<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.mutationTail.then(operation)
+    this.mutationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  /** Commit a computed next state: swap memory, bump revision, notify. */
+  private commit(nextRecords: SshWorkspaceRecord[], change: LedgerChangeWithoutRevision): void {
+    this.records = nextRecords
+    this.reindex()
+    this.currentRevision += 1
+    this.emit({ ...change, revision: this.currentRevision } as LedgerChange)
+  }
+
+  private emit(change: LedgerChange): void {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(cloneChange(change))
+      } catch (error) {
+        // Listener failures must never reject an already-committed mutation.
+        console.warn('[dsh-hardssh] ledger subscriber failed:', error instanceof Error ? error.message : String(error))
+      }
+    }
+  }
+
+  /** Load the ledger (compat; returns detached copies). */
+  async load(): Promise<SshWorkspaceRecord[]> {
+    await this.ensureLoaded()
+    return cloneRecords(this.records ?? [])
+  }
+
+  /** All records, in creation order (detached copies). */
+  async list(): Promise<SshWorkspaceRecord[]> {
+    await this.ensureLoaded()
+    return cloneRecords(this.records ?? [])
+  }
+
+  /** Current detached snapshot. */
+  async snapshot(): Promise<LedgerSnapshot> {
+    await this.ensureLoaded()
+    return { revision: this.currentRevision, records: cloneRecords(this.records ?? []) }
+  }
+
+  /** 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 {
+    return { revision: this.currentRevision, records: this.records ?? [] }
+  }
+
+  /** Current in-process revision (restarts at 0 on process restart). */
+  revision(): number {
+    return this.currentRevision
+  }
+
+  /** Subscribe to committed mutations (no initial event). Returns a disposer. */
+  subscribe(listener: LedgerListener): () => void {
+    this.listeners.add(listener)
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      this.listeners.delete(listener)
+    }
+  }
+
+  /** Look up by id. */
+  async get(id: string): Promise<SshWorkspaceRecord | undefined> {
+    await this.ensureLoaded()
+    const record = this.records?.find((candidate) => candidate.id === id)
+    return record === undefined ? undefined : cloneRecord(record)
+  }
+
+  /** Look up by LOCAL anchor path (resolved). Returns the record whose
+   *  anchor owns the path (the anchor itself or any descendant). */
+  async findByAnchor(path: string): Promise<SshWorkspaceRecord | undefined> {
+    await this.ensureLoaded()
+    return this.findByAnchorSync(path)
+  }
+
+  /** Synchronous anchor lookup (uses the in-memory index). */
+  findByAnchorSync(path: string): SshWorkspaceRecord | undefined {
+    const canonical = safeRealpathSync(path)
+    if (canonical === undefined) return undefined
+    for (const { anchor, record } of this.anchorIndex) {
+      if (isPathUnderAnchor(anchor, canonical)) return cloneRecord(record)
+    }
+    return undefined
+  }
+
+  /** Create a record: materialize the anchor, then persist+commit. */
+  async create(input: { title: string; alias: string; remoteRoot: string }): Promise<SshWorkspaceRecord> {
+    return this.enqueueMutation(async () => {
+      await this.ensureLoaded()
+      const id = randomUUID()
+      const remoteRoot = normalizeRemoteRoot(input.remoteRoot)
+      const record: SshWorkspaceRecord = {
+        id,
+        title: input.title.trim() === '' ? defaultTitle(remoteRoot, input.alias) : input.title.trim(),
+        alias: input.alias,
+        remoteRoot,
+        anchorPath: this.anchorFor(id),
+        createdAt: new Date().toISOString(),
+      }
+      // Materialize before publishing a binding that points at the anchor;
+      // a persistence failure leaves an unreferenced dir but no snapshot change.
+      await mkdir(record.anchorPath, { recursive: true })
+      const nextRecords = [...(this.records ?? []), record]
+      await this.save(nextRecords)
+      this.commit(nextRecords, { type: 'created', record })
+      return cloneRecord(record)
+    })
+  }
+
+  /** Rename a record (display title only). */
+  async rename(id: string, title: string): Promise<SshWorkspaceRecord | undefined> {
+    return this.enqueueMutation(async () => {
+      await this.ensureLoaded()
+      const records = this.records ?? []
+      const index = records.findIndex((record) => record.id === id)
+      if (index < 0) return undefined
+      const before = records[index]
+      const record: SshWorkspaceRecord = { ...before, title: title.trim() }
+      const nextRecords = [...records]
+      nextRecords[index] = record
+      await this.save(nextRecords)
+      this.commit(nextRecords, { type: 'renamed', before, record })
+      return cloneRecord(record)
+    })
+  }
+
+  /** Remove a record. The anchor directory is left in place (a host
+   *  workspace may still reference it; the caller decides on deletion). */
+  async remove(id: string): Promise<boolean> {
+    return this.enqueueMutation(async () => {
+      await this.ensureLoaded()
+      const records = this.records ?? []
+      const index = records.findIndex((record) => record.id === id)
+      if (index < 0) return false
+      const record = records[index]
+      const nextRecords = [...records.slice(0, index), ...records.slice(index + 1)]
+      await this.save(nextRecords)
+      this.commit(nextRecords, { type: 'removed', record })
+      return true
+    })
+  }
+
+  /** The anchor root shared by every record (for UI hints). */
+  anchorsRoot(): string {
+    return this.anchors()
+  }
+}
+
+/** Guard: a parsed JSON value is a valid record. */
+function isRecord(value: unknown): value is SshWorkspaceRecord {
+  if (typeof value !== 'object' || value === null) return false
+  const record = value as Record<string, unknown>
+  return typeof record.id === 'string'
+    && typeof record.title === 'string'
+    && typeof record.alias === 'string'
+    && typeof record.remoteRoot === 'string'
+    && typeof record.anchorPath === 'string'
+}
+
+/** Synchronous realpath, swallowing errors (a session cwd can vanish mid-flight). */
+function safeRealpathSync(path: string): string | undefined {
+  try {
+    return realpathSync(path)
+  } catch {
+    return undefined
+  }
+}
+
+function isWindowsAnchor(path: string): boolean {
+  return /^[a-zA-Z]:[\\/]/.test(path) || path.startsWith('\\\\') || path.includes('\\')
+}
+
+function windowsRootLength(path: string): number {
+  if (/^[a-zA-Z]:\\/.test(path)) return 3
+  if (path.startsWith('\\\\')) {
+    const segments = path.slice(2).split('\\')
+    if (segments.length >= 2 && segments[0] !== '' && segments[1] !== '') {
+      return 2 + segments[0].length + 1 + segments[1].length
+    }
+    return 2
+  }
+  return 0
+}
+
+function trimTrailingSeparators(path: string, minimumLength: number): string {
+  let end = path.length
+  while (end > minimumLength && (path[end - 1] === '/' || path[end - 1] === '\\')) {
+    end -= 1
+  }
+  return path.slice(0, end)
+}
+
+function cloneRecord(record: SshWorkspaceRecord): SshWorkspaceRecord {
+  return { ...record }
+}
+
+function cloneRecords(records: readonly SshWorkspaceRecord[]): SshWorkspaceRecord[] {
+  return records.map(cloneRecord)
+}
+
+function cloneChange(change: LedgerChange): LedgerChange {
+  switch (change.type) {
+    case 'created':
+      return { ...change, record: cloneRecord(change.record) }
+    case 'renamed':
+      return { ...change, before: cloneRecord(change.before), record: cloneRecord(change.record) }
+    case 'removed':
+      return { ...change, record: cloneRecord(change.record) }
+  }
+}