dsh-remote-workspaces 0.2.1 → 0.3.0

package/src/index.js

@@ -6,6 +6,8 @@ import { RoutingFileSystem } from './routing-fs.js'
 import { SshShellExecutor } from './shell-exec.js'
 import { registerAnchor, unregisterAnchor, findByCwd, updateAnchorOs } from './registry.js'
 import { applySearchTools } from './search.js'
+import { createShellSessions } from './shell-sessions.js'
+import { expandLocalTarget, localHome, localDriveRoots, localLevelListing, localListError, LOCAL_DRIVES } from './local-browse.js'
 
 export { parseSshConfig, expandTilde } from './ssh-config.js'
 export { SshClient, hostsFromConfig, shellQuote, defaultSshConfigPath, clientForHost } from './transport.js'
@@ -68,7 +70,16 @@ const INVOCATIONS = [
   invocation('sshAliasDetail', [jsonParameter('alias')]),
   invocation('testConnection', [jsonParameter('machine')]),
   invocation('listRemoteDir', [jsonParameter('machine'), jsonParameter('path')]),
+  invocation('listLocalDir', [jsonParameter('path')]),
   invocation('openRemoteWorkspace', [jsonParameter('machine'), jsonParameter('path')]),
+  invocation('openShellLocal', [jsonParameter('opts')]),
+  invocation('openShellRemote', [jsonParameter('machine'), jsonParameter('opts')]),
+  invocation('openShellAt', [jsonParameter('cwd'), jsonParameter('opts')]),
+  invocation('shellWrite', [jsonParameter('id'), jsonParameter('data')]),
+  invocation('shellRead', [jsonParameter('id')]),
+  invocation('shellResize', [jsonParameter('id'), jsonParameter('rows'), jsonParameter('cols')]),
+  invocation('shellClose', [jsonParameter('id')]),
+  invocation('shellList'),
 ]
 
 /** Build an `SshClient` from a machine record (alias/host/port/user/identityFile). */
@@ -183,7 +194,11 @@ async function resolveRemotePath(client, raw, sharedSftp) {
  * Host owner of the `remoteWorkspaces` Remote namespace. Every method returns
  * only lossless-JSON data and never echoes stored secrets back to the browser.
  */
-function remoteWorkspacesService() {
+function remoteWorkspacesService(remote) {
+  const shells = createShellSessions({
+    getSubprocess: () => remote.getSubprocess(),
+    openRemote: (machine, opts) => sshClientFor(machine).openShell(opts),
+  })
   return {
     listMachines() {
       return { ok: true, machines: loadMachines().map(sanitizeMachine) }
@@ -261,6 +276,28 @@ function remoteWorkspacesService() {
       }
     },
 
+    async listLocalDir(path) {
+      // Virtual Windows drive-selection level: '上一级' at a drive root.
+      if (typeof path === 'string' && path === LOCAL_DRIVES) {
+        try {
+          const roots = await localDriveRoots()
+          const entries = roots.map((r) => ({ name: r.slice(0, 2), dir: true }))
+          return { ok: true, path: '', entries, truncated: false }
+        } catch (error) {
+          return { ok: false, error: '无法读取盘符：' + messageOf(error) }
+        }
+      }
+      let target = ''
+      try {
+        const home = localHome()
+        target = expandLocalTarget(path, home)
+        const level = await localLevelListing(target, {})
+        return { ok: true, path: level.path, entries: level.entries, truncated: level.truncated }
+      } catch (error) {
+        return { ok: false, error: localListError(error, target || (typeof path === 'string' ? path : '')) }
+      }
+    },
+
     /**
      * Open a remote directory as a workspace: create an EMPTY local anchor
      * directory (the harness's workspace identity — `fs.realpath` must resolve
@@ -306,6 +343,93 @@ function remoteWorkspacesService() {
         sftp.end()
       }
     },
+
+    // Shell tool: interactive local shell (ctx.subprocess.spawnTerminal) and
+    // remote shell (ssh2 conn.shell + pty). No approval (D6/D7): opening a
+    // shell is a user GUI action, equivalent to xshell — a separate line from
+    // the agent-side sandboxPolicy/approval gate. Credentials never ride the
+    // wire: the client sends only the sanitized machine (no secrets) and the
+    // host recovers password/passphrase from the store by id.
+    async openShellLocal(opts) {
+      try {
+        const session = await shells.openLocal(opts ?? {})
+        return { ok: true, ...session }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    async openShellRemote(machine, opts) {
+      try {
+        const session = await shells.openRemote(machine ?? {}, opts ?? {})
+        return { ok: true, ...session }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    /**
+     * Open a shell AT the current workspace cwd, resolving the target without
+     * the user choosing: a cwd under a registered remote anchor opens a remote
+     * shell on that machine, chdir'd to the anchor's remote path (+ subpath);
+     * anything else opens a local shell at that cwd. This is the default
+     * "click Shell" entry — no local/remote chooser.
+     */
+    async openShellAt(cwd, opts) {
+      try {
+        const anchor = typeof cwd === 'string' && cwd !== '' ? findByCwd(cwd) : undefined
+        if (anchor !== undefined) {
+          const machine = (anchor.machineId !== undefined && anchor.machineId !== null ? machineById(anchor.machineId) : undefined)
+            ?? { host: anchor.host, port: anchor.port, user: anchor.user }
+          const remoteCwd = anchor.remoteSubpath === ''
+            ? anchor.remotePath
+            : `${anchor.remotePath.replace(/\/+$/, '')}/${anchor.remoteSubpath}`
+          const session = await shells.openRemote(machine, { ...(opts ?? {}), cwd: remoteCwd })
+          return { ok: true, ...session, cwd: remoteCwd, label: machine.alias || machine.host || '远程' }
+        }
+        const session = await shells.openLocal({ ...(opts ?? {}), cwd })
+        return { ok: true, ...session, cwd: typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd(), label: '本机' }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    async shellWrite(id, data) {
+      try {
+        await shells.write(id, data)
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    shellRead(id) {
+      try {
+        return { ok: true, ...shells.read(id) }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    async shellResize(id, rows, cols) {
+      try {
+        return { ok: true, ...(await shells.resize(id, rows, cols)) }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    async shellClose(id) {
+      try {
+        return { ok: true, ...(await shells.close(id)) }
+      } catch (error) {
+        return { ok: false, error: messageOf(error) }
+      }
+    },
+
+    shellList() {
+      return { ok: true, sessions: shells.list() }
+    },
   }
 }
 
@@ -334,7 +458,7 @@ export function apply(ctx) {
   ctx.provide('fs', new RoutingFileSystem(remote))
   ctx.provide('shell', new SshShellExecutor(remote))
 
-  const service = remoteWorkspacesService()
+  const service = remoteWorkspacesService(remote)
   service.typertRemote = Object.freeze({ service, serviceKey: NAMESPACE, namespace: NAMESPACE })
   ctx.provide(NAMESPACE, service)
 

package/src/local-browse.js

@@ -0,0 +1,168 @@
+/**
+ * Local-directory listing for the workspace-add flow's "本地文件夹" tab when
+ * the page is NOT served from the host's own loopback (remote access): the OS
+ * chooser would open on an unattended desktop, so the plugin browses the host
+ * filesystem in-app instead. Pure Node stdlib (the plugin cannot import
+ * harness packages); mirrors the `listRemoteDir` contract so the client reuses
+ * the same entry rendering.
+ *
+ * Security posture: read-only one-level directory listing, driven by the user's
+ * own GUI action. Never writes, never executes, and never enters the agent
+ * toolchain's sandboxPolicy/approval line (same trust surface as the harness
+ * `directory-picker-browse` backend).
+ */
+
+import { access, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, posix, win32 } from 'node:path'
+
+/**
+ * Wire value for the virtual Windows drive-selection level: listing it returns
+ * the available drive roots. It is not a filesystem path, so it is fenced out
+ * of every real-path branch (never fully qualified). The client sends it only
+ * when a drive root's "上一级" is pressed on a win32 host (the client keeps an
+ * identical copy of this constant).
+ */
+export const LOCAL_DRIVES = '::drives::'
+
+/** The host account's home directory (listing default + `~` expansion). */
+export function localHome() {
+  return homedir()
+}
+
+/**
+ * Available Windows drive roots (`C:\`, `D:\`, …) for the virtual drive level.
+ * Empty on non-win32 platforms. Probes `A:`–`Z:` with fs access.
+ * @param platform - replaces `process.platform` for deterministic tests.
+ */
+export async function localDriveRoots(platform = process.platform) {
+  if (platform !== 'win32') return []
+  const found = []
+  for (const letter of 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') {
+    const root = `${letter}:\\`
+    try {
+      await access(root)
+      found.push(root)
+    } catch { /* absent drive */ }
+  }
+  return found
+}
+
+/**
+ * True when the path names one fixed filesystem location regardless of process
+ * state: POSIX-absolute on POSIX; on Windows only drive-qualified (`C:\…`) or
+ * complete UNC (`\\server\share…`) forms. Rooted drive-less forms and
+ * incomplete UNC prefixes pass `isAbsolute` yet still resolve against the
+ * process's current drive — mirroring the harness browse backend's fence so a
+ * wire value never rebases under the host cwd.
+ * @param path - candidate path.
+ * @param platform - replaces `process.platform` for deterministic tests.
+ */
+export function localFullyQualified(path, platform = process.platform) {
+  if (typeof path !== 'string') return false
+  if (platform === 'win32') {
+    return win32.isAbsolute(path)
+      && /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/]+[^\\/]+)/.test(path)
+  }
+  return posix.isAbsolute(path)
+}
+
+/** Not-absolute / non-`~` input: never rebase under the host cwd. */
+function notAbsolute(raw) {
+  const error = new Error(`不是完整路径（需要绝对路径或以 ~ 开头）：${String(raw)}`)
+  error.code = 'DSH_NOT_ABSOLUTE'
+  return error
+}
+
+/** Resolve + normalize one fully qualified target on the platform. */
+function normalizeTarget(input, platform) {
+  return platform === 'win32' ? win32.resolve(input) : posix.resolve(input)
+}
+
+/** Platform-consistent segment join (node's default join is host-flavored). */
+function platformJoin(a, b, platform) {
+  return platform === 'win32' ? win32.join(a, b) : posix.join(a, b)
+}
+
+/**
+ * Turn the RPC's raw `path` argument into a concrete absolute listing target.
+ * `''`/undefined/`~`/`~/…` expand to the home directory; anything else must be
+ * fully qualified (client-browsed paths are, and `..` segments are resolved by
+ * the platform resolver, so the client's "上一级" can send `<path>/..`).
+ * @param raw - the wire value (may be undefined).
+ * @param home - home directory to expand against.
+ * @param platform - replaces `process.platform` for deterministic tests.
+ * @returns the absolute listing target.
+ * @throws {Error} with `code === 'DSH_NOT_ABSOLUTE'` for non-`~` relative input.
+ */
+export function expandLocalTarget(raw, home, platform = process.platform) {
+  const input = typeof raw === 'string' ? raw.trim() : ''
+  if (input === '' || input === '~') return normalizeTarget(home, platform)
+  if (input.startsWith('~/') || input.startsWith('~\\')) {
+    return normalizeTarget(platformJoin(home, input.slice(2), platform), platform)
+  }
+  if (!localFullyQualified(input, platform)) throw notAbsolute(raw)
+  return normalizeTarget(input, platform)
+}
+
+/** Classify one dirent: directories (symlinked dirs probed) are enterable rows. */
+async function entryRow(target, dirent) {
+  const isDirectory = dirent.isDirectory()
+  if (!isDirectory && dirent.isSymbolicLink()) {
+    try {
+      return { name: dirent.name, dir: (await stat(join(target, dirent.name))).isDirectory() }
+    } catch {
+      // Broken/cyclic link: keep a plain (non-enterable) row.
+      return { name: dirent.name, dir: false }
+    }
+  }
+  return { name: dirent.name, dir: isDirectory }
+}
+
+/**
+ * List one directory level. Directories and files both return (files render
+ * muted and non-clickable, mirroring the remote tab); `.`/`..` are dropped;
+ * rows are name-sorted. The complete level is bounded at `maxEntries` rows with
+ * `truncated` flagging a cut tail.
+ * @param target - absolute listing target (already expanded).
+ * @param opts - `maxEntries` bound (default 1000, like the harness browse
+ * backend); `platform` for tests.
+ * @returns `{ path, entries: [{name, dir}], truncated }`.
+ * @throws filesystem errors (`ENOENT`/`ENOTDIR`/`EACCES`…) unchanged.
+ */
+export async function localLevelListing(target, opts = {}) {
+  const maxEntries = opts.maxEntries === undefined ? 1000 : opts.maxEntries
+  const entries = (await readdir(target, { withFileTypes: true }))
+    .filter((d) => d.name !== '.' && d.name !== '..')
+  const rows = []
+  for (const dirent of entries) {
+    if (rows.length === maxEntries) break
+    // eslint-disable-next-line no-await-in-loop -- per-entry symlink probes are sequential like the remote backend.
+    rows.push(await entryRow(target, dirent))
+  }
+  rows.sort((a, b) => a.name.localeCompare(b.name))
+  return {
+    path: target,
+    entries: rows,
+    truncated: entries.length > maxEntries,
+  }
+}
+
+/**
+ * Operator-facing text for a failed local listing.
+ * @param error - thrown value (filesystem error or DSH_NOT_ABSOLUTE).
+ * @param target - resolved target (for messages naming the directory).
+ */
+export function localListError(error, target) {
+  const code = error && error.code
+  if (code === 'DSH_NOT_ABSOLUTE') {
+    return error.message || '路径无效'
+  }
+  if (code === 'ENOENT' || code === 'ENOTDIR') {
+    return `目录不存在：${target}`
+  }
+  if (code === 'EACCES' || code === 'EPERM') {
+    return `无权限读取：${target}`
+  }
+  return `无法读取目录：${target}（${error instanceof Error ? error.message : String(error)}）`
+}

package/src/registry.js

@@ -9,7 +9,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join, sep } from 'node:path'
+import { join } from 'node:path'
 import { remoteWorkspacesRoot } from './anchor.js'
 
 function anchorsPath() {
@@ -64,27 +64,36 @@ export function unregisterAnchor(anchorPath) {
 }
 
 /**
- * Resolve a session cwd (the anchor path, or any descendant) to its remote
- * origin. Returns `{ anchorPath, remotePath, remoteSubpath, host, port, user, machineId }`
- * or `undefined` when the cwd is not under any registered anchor.
+ * Resolve a session cwd — the anchor path, any descendant, or the Files tree's
+ * `/`-joined child spelling of either — to its remote origin. Returns
+ * `{ anchorPath, remotePath, remoteSubpath, host, port, user, machineId }` or
+ * `undefined` when the cwd is not under any registered anchor.
+ *
+ * Matching is done on separator-normalized forms: anchor keys are stored with
+ * the native `sep` (`\` on Windows), while harness session cwds and the right
+ * Sidebar Files tree spell paths with `/` (and children are `root + '/' + name`
+ * even when the root is `\`-spelled). `remoteSubpath` is always `/`-joined.
  */
 export function findByCwd(cwd) {
   if (typeof cwd !== 'string' || cwd === '') return undefined
   const anchors = loadAnchors()
+  const flat = (p) => p.replace(/\\/g, '/')
+  const query = flat(cwd)
   let best
   let bestLen = -1
   for (const [anchorPath, rec] of Object.entries(anchors)) {
-    const base = anchorPath.endsWith(sep) ? anchorPath : anchorPath + sep
-    if (cwd === anchorPath || cwd.startsWith(base)) {
-      if (anchorPath.length > bestLen) {
-        bestLen = anchorPath.length
-        best = { anchorPath, ...rec }
+    const base = flat(anchorPath)
+    const prefix = base.endsWith('/') ? base : `${base}/`
+    if (query === base || query.startsWith(prefix)) {
+      if (base.length > bestLen) {
+        bestLen = base.length
+        best = { anchorPath, base, rec }
       }
     }
   }
   if (best === undefined) return undefined
-  const rel = cwd === best.anchorPath ? '' : cwd.slice(best.anchorPath.length + sep.length)
-  return { ...best, remoteSubpath: rel === '' ? '' : rel.split(sep).join('/') }
+  const rel = query === best.base ? '' : query.slice(best.base.length + 1)
+  return { ...best.rec, anchorPath: best.anchorPath, remoteSubpath: rel }
 }
 
 export default { loadAnchors, registerAnchor, unregisterAnchor, updateAnchorOs, findByCwd, remoteWorkspacesRoot }

package/src/routing-fs.js

@@ -1,10 +1,14 @@
 /**
  * Routing filesystem: the plugin's `ctx.fs` provider.
  *
- * Routes by the session cwd. Two remote triggers:
- *   - an `ssh://[user@]host[:port]/path` cwd (URI form), and
+ * Routes by the session cwd OR by the path itself. Remote triggers:
+ *   - an `ssh://[user@]host[:port]/path` cwd (URI form),
  *   - a LOCAL anchor directory registered in the remote-workspace registry
- *     (`anchors.json`), whose real content lives on the remote host.
+ *     (`anchors.json`), whose real content lives on the remote host, and
+ *   - any absolute path that IS a registered anchor or sits under one (the
+ *     anchor path is the remote world's local alias — the Files tree lists,
+ *     expands and opens entirely in this spelling, so routing must answer it
+ *     with or without an anchor cwd).
  * Everything else goes to the local backend (with the workspace-write fence).
  *
  * The world identity is ENCODED into the target key (`ssh://host/path` for
@@ -75,6 +79,41 @@ export class RoutingFileSystem {
     return `ssh://${user ? `${user}@` : ''}${host}${port ? `:${port}` : ''}${subKey}`
   }
 
+  /**
+   * Anchor alias of an absolute LOCAL path: a registered anchor dir — or any
+   * path under one — is the remote world's local spelling, so the registry
+   * lookup that maps a session cwd maps the path itself. Returns the remote
+   * origin (`{ host, user, port, remotePath }`) when `path` is an anchor dir or
+   * a descendant of one, else null. This is what lets the right Sidebar Files
+   * tree (which roots at the anchor path and joins children with `/`) reach the
+   * remote: those strings ARE remote aliases.
+   */
+  aliasOfPath(path) {
+    if (typeof path !== 'string' || path === '') return null
+    const hit = findByCwd(path)
+    if (hit === undefined) return null
+    return {
+      host: hit.host,
+      user: hit.user,
+      port: hit.port,
+      remotePath: hit.remoteSubpath === '' ? hit.remotePath : posix.join(hit.remotePath, hit.remoteSubpath),
+    }
+  }
+
+  /** Remote routing params for a call, from its cwd first and its path second. */
+  routeRemote(path, cwd) {
+    const byCwd = this.remoteCwd(cwd)
+    if (byCwd !== null) return byCwd
+    const byPath = this.aliasOfPath(path)
+    return byPath === null ? null : { ...byPath, remoteCwd: byPath.remotePath }
+  }
+
+  /** The path argument translated to the remote world when it is itself an alias. */
+  remotePathArg(path) {
+    const alias = this.aliasOfPath(path)
+    return alias === null ? path : alias.remotePath
+  }
+
   /** Decode a target key into { backend, target } using the encoded world prefix. */
   splitTarget(target) {
     const key = String(target.targetKey)
@@ -92,10 +131,17 @@ export class RoutingFileSystem {
 
   async resolve(path, opts) {
     const cwd = opts && opts.cwd
-    const remote = this.remoteCwd(cwd)
+    // Remote by cwd (session anchor), or by the path itself when no remote cwd
+    // is given — the Files endpoint resolves the workspace root WITHOUT a cwd,
+    // and the root is the anchor path, so the path must trigger routing alone.
+    const remote = this.routeRemote(path, cwd)
     if (remote !== null) {
       const backend = this.remoteBackend(remote.host, remote.user, remote.port)
-      const sub = await backend.resolve(path, { cwd: remote.remoteCwd })
+      // An anchor-absolute path (the Files vocabulary) is translated to its
+      // remote spelling here; a relative path under an anchor cwd passes
+      // through unchanged so the backend's cwd resolution applies as before.
+      const arg = this.remotePathArg(path)
+      const sub = await backend.resolve(arg, { cwd: remote.remoteCwd })
       return {
         targetKey: this.encodeTarget(remote.host, remote.user, remote.port, sub.targetKey),
         displayPath: sub.displayPath,
@@ -135,10 +181,11 @@ export class RoutingFileSystem {
 
   lstat(path, opts, signal) {
     const cwd = opts && opts.cwd
-    const remote = this.remoteCwd(cwd)
+    const remote = this.routeRemote(path, cwd)
     if (remote !== null) {
       const backend = this.remoteBackend(remote.host, remote.user, remote.port)
-      return backend.lstat(path, { cwd: remote.remoteCwd })
+      const arg = this.remotePathArg(path)
+      return backend.lstat(arg, { cwd: remote.remoteCwd })
     }
     return this.local.lstat(path, opts)
   }

package/src/shell-sessions.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto'
+
+/**
+ * In-process registry of interactive UI shell sessions (local + remote).
+ *
+ * Every `openLocal` allocates an INDEPENDENT PTY process through the harness's
+ * `ctx.subprocess.spawnTerminal` seam; every `openRemote` opens an INDEPENDENT
+ * ssh2 shell channel through `SshClient.openShell`. Sessions never share a
+ * process/connection, cwd, stdin/stdout, or buffer (the §3.1 isolation model).
+ * Lifecycle is process-local (matches ctx.terminals semantics): no persistence,
+ * no cross-process recovery.
+ *
+ * A session keeps TWO buffers over the same stream:
+ *   - `unread` — drained by `read` (incremental polling);
+ *   - `history` — the full (capped) output, returned on ATTACH so a re-mounted
+ *     tab replays its scrollback instead of coming back blank.
+ *
+ * Attach: an `open*` carrying a stable `key` REUSES a still-live session under
+ * that key instead of spawning a new one — this is what keeps a Shell tab's
+ * terminal alive across the client unmounting it on a DSH-session switch.
+ */
+
+const MAX_UNREAD = 256 * 1024
+const MAX_HISTORY = 512 * 1024
+
+export function createShellSessions({ getSubprocess, openRemote: openRemoteChannel, sweepMs = 10 * 60 * 1000 }) {
+  const sessions = new Map()
+
+  // Reap sessions no client has read from or written to within `sweepMs`: a
+  // shell whose tab was lost to a refresh (or an archived session) has nobody
+  // left to close it. An on-screen tab polls continuously, so only abandoned
+  // shells — or ones hidden longer than the threshold — are collected.
+  function sweep(now = Date.now()) {
+    for (const [id, session] of [...sessions]) {
+      if (!session.ended && now - session.lastActivityAt > sweepMs) {
+        sessions.delete(id)
+        void session.handle.terminate()
+      }
+    }
+  }
+  const sweepTimer = setInterval(sweep, 60 * 1000)
+  if (typeof sweepTimer.unref === 'function') sweepTimer.unref()
+
+  function liveSession(key) {
+    if (typeof key !== 'string' || key === '') return undefined
+    const existing = sessions.get(key)
+    return existing !== undefined && !existing.ended ? existing : undefined
+  }
+
+  function pushCapped(bag, cap, buf) {
+    bag.chunks.push(buf)
+    bag.bytes += buf.length
+    while (bag.bytes > cap && bag.chunks.length > 1) {
+      bag.bytes -= bag.chunks.shift().length
+    }
+  }
+
+  function register(handle, meta, key) {
+    const id = typeof key === 'string' && key !== '' ? key : randomUUID()
+    const session = {
+      id,
+      handle,
+      meta,
+      unread: { chunks: [], bytes: 0 },
+      history: { chunks: [], bytes: 0 },
+      ended: false,
+      lastActivityAt: Date.now(),
+    }
+    handle.output.on('data', (chunk) => {
+      const buf = Buffer.from(chunk)
+      pushCapped(session.unread, MAX_UNREAD, buf)
+      pushCapped(session.history, MAX_HISTORY, buf)
+    })
+    handle.output.on('end', () => { session.ended = true })
+    handle.output.on('close', () => { session.ended = true })
+    sessions.set(id, session)
+    return session
+  }
+
+  function historyText(session) {
+    return Buffer.concat(session.history.chunks).toString('utf8')
+  }
+
+  async function openLocal(opts = {}) {
+    const key = typeof opts.key === 'string' && opts.key !== '' ? opts.key : undefined
+    const existing = liveSession(key)
+    if (existing !== undefined) {
+      const history = historyText(existing)
+      // The attach hands the client the full scrollback, so the unread tail is
+      // now covered — start incremental reads fresh to avoid double replay.
+      existing.unread.chunks.length = 0
+      existing.unread.bytes = 0
+      return { id: existing.id, pid: existing.handle.pid, kind: 'local', attached: true, history }
+    }
+    const subprocess = getSubprocess()
+    if (subprocess === undefined || typeof subprocess.spawnTerminal !== 'function') {
+      throw new Error('subprocess service unavailable (no spawnTerminal)')
+    }
+    const win = process.platform === 'win32'
+    const argv = win ? ['powershell.exe', '-NoLogo'] : ['bash', '-i']
+    const cwd = typeof opts.cwd === 'string' && opts.cwd !== '' ? opts.cwd : process.cwd()
+    const rows = Number.isInteger(opts.rows) && opts.rows > 0 ? opts.rows : 24
+    const cols = Number.isInteger(opts.cols) && opts.cols > 0 ? opts.cols : 80
+    const handle = await subprocess.spawnTerminal({ argv, cwd, rows, cols, graceMs: 3000 })
+    const session = register(handle, { kind: 'local', label: win ? 'PowerShell' : 'bash' }, key)
+    return { id: session.id, pid: handle.pid, kind: 'local', attached: false }
+  }
+
+  async function openRemote(machine, opts = {}) {
+    const key = typeof opts.key === 'string' && opts.key !== '' ? opts.key : undefined
+    const existing = liveSession(key)
+    if (existing !== undefined) {
+      const history = historyText(existing)
+      existing.unread.chunks.length = 0
+      existing.unread.bytes = 0
+      return { id: existing.id, pid: null, kind: 'remote', attached: true, history }
+    }
+    if (typeof openRemoteChannel !== 'function') throw new Error('remote shell unavailable (no openShell)')
+    const rows = Number.isInteger(opts.rows) && opts.rows > 0 ? opts.rows : 24
+    const cols = Number.isInteger(opts.cols) && opts.cols > 0 ? opts.cols : 80
+    const cwd = typeof opts.cwd === 'string' && opts.cwd !== '' ? opts.cwd : undefined
+    const handle = await openRemoteChannel(machine ?? {}, { rows, cols, ...(cwd ? { cwd } : {}) })
+    const session = register(handle, {
+      kind: 'remote',
+      label: (machine && (machine.alias || machine.host)) || 'remote',
+    }, key)
+    return { id: session.id, pid: null, kind: 'remote', attached: false }
+  }
+
+  function requireSession(id) {
+    const session = sessions.get(id)
+    if (session === undefined) throw new Error(`shell session not found: ${id}`)
+    return session
+  }
+
+  async function write(id, data) {
+    const session = requireSession(id)
+    session.lastActivityAt = Date.now()
+    if (!session.ended && typeof data === 'string' && data !== '') await session.handle.write(data)
+  }
+
+  function read(id) {
+    const session = requireSession(id)
+    session.lastActivityAt = Date.now()
+    const text = Buffer.concat(session.unread.chunks).toString('utf8')
+    session.unread.chunks.length = 0
+    session.unread.bytes = 0
+    return { text, eof: session.ended }
+  }
+
+  async function resize(id, rows, cols) {
+    const session = requireSession(id)
+    if (session.ended) return { resized: false }
+    if (typeof session.handle.resize === 'function') {
+      session.handle.resize(rows, cols)
+      return { resized: true }
+    }
+    return { resized: false }
+  }
+
+  async function close(id) {
+    const session = sessions.get(id)
+    if (session === undefined) return { closed: false }
+    sessions.delete(id)
+    await session.handle.terminate()
+    return { closed: true }
+  }
+
+  function list() {
+    return [...sessions.values()].map((session) => ({
+      id: session.id,
+      pid: session.handle.pid ?? null,
+      kind: session.meta.kind,
+      label: session.meta.label,
+      ended: session.ended,
+    }))
+  }
+
+  return { openLocal, openRemote, write, read, resize, close, list, sweep }
+}