@chronosun/dsh-wsl 0.0.0-stage → 1.5.1

package/src/wsl-diff-v2.mjs

@@ -0,0 +1,315 @@
+// WSL-side workspace-change summaries and diffs.
+//
+// The shipped `workspaceChanges` recorder is a Host service: it runs Windows
+// git against the UNC worktree. This companion takes a snapshot inside the
+// distribution at `turn/start` and `turn/end` (private GIT_INDEX_FILE, then
+// write-tree/diff-tree), stores the summary by the `workspace/changes` event's
+// seq, and serves it before the Host fallback. The Host summary's `cwd`/`path`
+// stay usable for `/api/changes.open`; only the comparison work moves to Linux.
+import { registry } from './registry.mjs'
+import { linuxPathFromUnc } from './preset-default.mjs'
+import { userFor } from './settings.mjs'
+
+export const WSL_PRESET = 'wsl'
+const PATCH = Symbol.for('dsh-wsl/wsl-diff')
+const MAX_ENTRIES = 500
+
+function unwrap(value) {
+  if (!value || (typeof value !== 'object' && typeof value !== 'function')) return value
+  try { return value[Symbol.for('cordis.original')] ?? value } catch { return value }
+}
+
+function linuxCwd(session) {
+  const cwd = session?.header?.cwd
+  return linuxPathFromUnc(cwd) ?? (typeof cwd === 'string' && cwd.startsWith('/') ? cwd : undefined)
+}
+
+function brokerFor(cwd) {
+  const match = /^\\\\[?]?(?:wsl\.localhost|wsl\$)\\([^\\]+)\\/i.exec(String(cwd ?? ''))
+  const distro = match ? match[1] : ''
+  return registry.get(distro, userFor(distro))
+}
+
+/** A running helper from before the git ops were added still has `exec`. */
+async function exec(broker, argv, cwd) {
+  return broker.call('exec', { argv, cwd })
+}
+
+/**
+ * `gitSnapshot` with a shell fallback so a Session whose helper predates the
+ * operation still gets a WSL snapshot instead of the Host fallback.
+ */
+async function snapshotInWsl(broker, cwd) {
+  const script = [
+    'set -e',
+    'd=$(mktemp -d)',
+    'trap \'rm -rf "$d"\' EXIT',
+    'export GIT_INDEX_FILE="$d/index"',
+    'git -C "$PWD" read-tree --empty',
+    "git -C \"$PWD\" add -A -- . ':(exclude).agents/worktrees'",
+    'git -C "$PWD" write-tree',
+  ].join('\n')
+  const result = await exec(broker, ['bash', '-c', script], cwd)
+  if (result.code !== 0) throw new Error(`wsl-diff: snapshot failed: ${result.err || result.out}`)
+  const lines = result.out.trim().split(/\r?\n/)
+  const tree = lines[lines.length - 1]?.trim()
+  if (!tree) throw new Error('wsl-diff: snapshot produced no tree')
+  return tree
+}
+
+async function summaryInWsl(broker, cwd, before, after) {
+  const prefix = (await exec(broker, ['git', '-C', cwd, 'rev-parse', '--show-prefix'], cwd)).out.trim()
+  const raw = await exec(broker, ['git', '-C', cwd, 'diff-tree', '-r', '--no-commit-id', '--numstat', '--no-renames', before, after], cwd)
+  if (raw.code !== 0) throw new Error(`wsl-diff: summary failed: ${raw.err || raw.out}`)
+  const files = []
+  for (const line of raw.out.split(/\r?\n/)) {
+    const match = /^(\S+)\t(\S+)\t(.*)$/.exec(line)
+    if (!match) continue
+    let file = match[3]
+    if (prefix && file.startsWith(prefix)) file = file.slice(prefix.length)
+    const binary = match[1] === '-' && match[2] === '-'
+    files.push({ path: file, added: binary ? 0 : Number(match[1]) || 0, deleted: binary ? 0 : Number(match[2]) || 0, ...(binary ? { binary: true } : {}) })
+  }
+  return files
+}
+
+function parseHunks(raw, pathValue, before, after) {
+  const hunks = []
+  let current = null
+  for (const line of raw.split(/\r?\n/)) {
+    const header = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line)
+    if (header) {
+      if (current) hunks.push(current)
+      current = {
+        oldStart: Number(header[1]),
+        oldLines: Number(header[2] ?? 1),
+        newStart: Number(header[3]),
+        newLines: Number(header[4] ?? 1),
+        lines: [],
+      }
+      continue
+    }
+    if (!current) continue
+    if (line.startsWith('\\ No newline')) { current.lines.push(line); continue }
+    if (line.startsWith('+') || line.startsWith('-') || line.startsWith(' ')) current.lines.push(line)
+  }
+  if (current) hunks.push(current)
+  return { kind: 'text', path: pathValue, display: pathValue, before, after, hunks, coarse: false }
+}
+
+async function diffInWsl(broker, cwd, before, after, file) {
+  const prefix = (await exec(broker, ['git', '-C', cwd, 'rev-parse', '--show-prefix'], cwd)).out.trim()
+  const full = `${prefix}${file}`
+  const exists = async (tree) => {
+    const result = await exec(broker, ['git', '-C', cwd, 'cat-file', '-e', `${tree}:${full}`], cwd)
+    return result.code === 0
+  }
+  const beforeExists = await exists(before)
+  const afterExists = await exists(after)
+  if (afterExists) {
+    const size = await exec(broker, ['git', '-C', cwd, 'cat-file', '-s', `${after}:${full}`], cwd)
+    if (Number(size.out) > 2 * 1024 * 1024) return { kind: 'oversized', path: file, display: file }
+  }
+  const raw = await exec(broker, ['git', '-C', cwd, 'diff', '--no-color', '--unified=3', before, after, '--', full], cwd)
+  if (raw.code !== 0) throw new Error(`wsl-diff: diff failed: ${raw.err || raw.out}`)
+  if (/^Binary files /m.test(raw.out)) return { kind: 'binary', path: file, display: file }
+  return parseHunks(raw.out, file, beforeExists, afterExists)
+}
+
+/**
+ * Install the WSL recorder companion. Sessions outside `wsl` and sessions
+ * without a Linux seed are untouched; every failure falls back to the Host.
+ *
+ * @returns `{ installed, dispose }`; `installed` is a live getter.
+ */
+export function installWslDiff(ctx) {
+  const disposers = []
+  const states = new Map()
+  const bySeq = new Map()
+  const seqByTurn = new Map()
+  const stats = { events: 0, wslEvents: 0, starts: 0, ends: 0, summaries: 0, late: 0, errors: 0, lastError: '' }
+  let installed = false
+
+  const presetOf = (session) => {
+    try { return ctx.get('agentPresets')?.presetForSession?.(session) } catch { return undefined }
+  }
+  const isWsl = (session) => presetOf(session) === WSL_PRESET && linuxCwd(session) !== undefined
+
+  const stateFor = (session) => {
+    let state = states.get(session.id)
+    if (state === undefined) {
+      state = { beforeTree: null, pending: null, busy: false }
+      states.set(session.id, state)
+    }
+    return state
+  }
+
+  const snapshot = async (session) => {
+    const cwd = linuxCwd(session)
+    return snapshotInWsl(brokerFor(session.header.cwd), cwd)
+  }
+
+  const remember = (sessionId, seq, pending) => {
+    bySeq.set(`${sessionId}|${seq}`, pending)
+    if (bySeq.size > MAX_ENTRIES) {
+      const first = bySeq.keys().next().value
+      if (first !== undefined) bySeq.delete(first)
+    }
+  }
+
+  const onSessionEvent = (session, event) => {
+    stats.events += 1
+    if (!isWsl(session)) return
+    stats.wslEvents += 1
+    const turn = Number(event?.data?.turn)
+    if (!Number.isFinite(turn)) return
+    if (event.type === 'turn/start') {
+      stats.starts += 1
+      const state = stateFor(session)
+      state.beforeTree = null
+      state.pending = null
+      const tree = snapshot(session)
+      tree.then((value) => { state.beforeTree = value }).catch((error) => {
+        stats.errors += 1
+        stats.lastError = String(error?.message ?? error)
+      })
+      return
+    }
+    if (event.type === 'turn/end') {
+      stats.ends += 1
+      const state = stateFor(session)
+      if (state.busy) return
+      state.busy = true
+      const cwd = session.header.cwd
+      const linux = linuxCwd(session)
+      const run = (async () => {
+        // Wait for the start tree; the Agent's own turn start usually lands
+        // well before its first tool call, but a slow git start must not make
+        // an empty diff.
+        for (let i = 0; i < 50 && state.beforeTree === null; i += 1) await new Promise((resolve) => setTimeout(resolve, 20))
+        const after = await snapshot(session)
+        if (state.beforeTree === null) throw new Error('wsl-diff: no start tree')
+        const files = await summaryInWsl(brokerFor(cwd), linux, state.beforeTree, after)
+        const pending = { turn, before: state.beforeTree, after, cwd, files }
+        state.pending = pending
+        stats.summaries += 1
+        const key = `${session.id}|${turn}`
+        const seq = seqByTurn.get(key)
+        if (seq !== undefined) {
+          seqByTurn.delete(key)
+          state.pending = null
+          remember(session.id, seq, pending)
+          stats.late += 1
+        }
+      })().catch((error) => {
+        stats.errors += 1
+        stats.lastError = String(error?.message ?? error)
+      }).finally(() => { state.busy = false })
+      void run
+      return
+    }
+    if (event.type === 'workspace/changes') {
+      const key = `${session.id}|${turn}`
+      seqByTurn.set(key, event.seq)
+      if (seqByTurn.size > MAX_ENTRIES) {
+        const first = seqByTurn.keys().next().value
+        if (first !== undefined) seqByTurn.delete(first)
+      }
+      const state = states.get(session.id)
+      const pending = state?.pending
+      if (pending === undefined || pending === null || pending.turn !== turn) return
+      seqByTurn.delete(key)
+      state.pending = null
+      remember(session.id, event.seq, pending)
+    }
+  }
+  // Prepended so the WSL snapshot starts before the Host recorder's Windows
+  // git runs over the UNC worktree; the `workspace/changes` event is appended
+  // after that Host work, so the summary is usually ready by then.
+  ctx.on('session/event', onSessionEvent, { prepend: true })
+
+  const install = (service) => {
+    if (installed) return true
+    const raw = unwrap(service)
+    if (!raw || typeof raw.summary !== 'function' || typeof raw.diff !== 'function') return false
+    if (raw[PATCH]) { installed = true; return true }
+    const summaryDescriptor = Object.getOwnPropertyDescriptor(raw, 'summary')
+    const diffDescriptor = Object.getOwnPropertyDescriptor(raw, 'diff')
+    const originalSummary = raw.summary
+    const originalDiff = raw.diff
+
+    const summary = function summaryPatched(sessionId, seq) {
+      const ours = bySeq.get(`${sessionId}|${seq}`)
+      if (ours === undefined) return originalSummary.call(raw, sessionId, seq)
+      const files = ours.files.map((file) => ({
+        path: file.path,
+        display: file.path,
+        added: file.added,
+        deleted: file.deleted,
+        ...(file.binary === true ? { binary: true } : {}),
+      }))
+      return {
+        turn: ours.turn,
+        cwd: ours.cwd,
+        source: 'wsl',
+        files,
+        total: files.length,
+        added: files.reduce((sum, file) => sum + file.added, 0),
+        deleted: files.reduce((sum, file) => sum + file.deleted, 0),
+      }
+    }
+
+    const diff = async function diffPatched(sessionId, seq, index, signal) {
+      const ours = bySeq.get(`${sessionId}|${seq}`)
+      if (ours === undefined) return originalDiff.call(raw, sessionId, seq, index, signal)
+      const file = ours.files[index]
+      if (file === undefined) return undefined
+      signal?.throwIfAborted?.()
+      try {
+        const broker = brokerFor(ours.cwd)
+        const cwd = linuxPathFromUnc(ours.cwd)
+        return await diffInWsl(broker, cwd, ours.before, ours.after, file.path)
+      } catch {
+        return originalDiff.call(raw, sessionId, seq, index, signal)
+      }
+    }
+
+    try {
+      Object.defineProperty(raw, 'summary', { configurable: true, enumerable: false, writable: true, value: summary })
+      Object.defineProperty(raw, 'diff', { configurable: true, enumerable: false, writable: true, value: diff })
+    } catch {
+      return false
+    }
+    const dispose = () => {
+      try { if (summaryDescriptor) Object.defineProperty(raw, 'summary', summaryDescriptor) } catch {}
+      try { if (diffDescriptor) Object.defineProperty(raw, 'diff', diffDescriptor) } catch {}
+      try { delete raw[PATCH] } catch {}
+    }
+    Object.defineProperty(raw, PATCH, { configurable: true, enumerable: false, writable: true, value: dispose })
+    disposers.push(dispose)
+    installed = true
+    return true
+  }
+
+  const current = ctx.get('workspaceChanges')
+  if (current) install(current)
+  else ctx.on('internal/service', (name, value) => { if (name === 'workspaceChanges') install(value) })
+
+  ctx.on('agent/disposed', ({ agent }) => {
+    const id = agent?.session?.id
+    if (id === undefined) return
+    states.delete(id)
+    for (const key of bySeq.keys()) if (key.startsWith(`${id}|`)) bySeq.delete(key)
+  })
+
+  return {
+    get installed() { return installed },
+    get stats() { return { ...stats, sessions: states.size, entries: bySeq.size } },
+    dispose() {
+      for (const dispose of disposers.splice(0)) dispose()
+      states.clear()
+      bySeq.clear()
+      installed = false
+    },
+  }
+}

package/terminal-launcher.mjs

@@ -0,0 +1,59 @@
+// Sidebar-terminal launcher.
+//
+// `terminal-controller` is a Host service: it spawns the terminal process
+// itself, outside any agent preset, so a WSL preset cannot influence it. This
+// launcher is the supported way in: point the controller's `shell.path` at node
+// and this file, and pick the shell from the working directory the controller
+// hands us. Windows workspaces keep their normal shell — nothing changes there.
+import { execFileSync, spawn } from 'node:child_process'
+import { appendFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { userFor } from './src/settings.mjs'
+import { userFromLinuxPath } from './src/path-user.mjs'
+
+const cwd = process.cwd()
+const unc = /^\\\\[?]?(?:wsl\.localhost|wsl\$)\\([^\\]+)\\(.*)$/i.exec(cwd)
+
+// Terminals open rarely; one line here makes "it opened cmd again" debuggable.
+const LOG = join(tmpdir(), 'dsh-wsl-terminal.log')
+try { appendFileSync(LOG, `${new Date().toISOString()} cwd=${JSON.stringify(cwd)} branch=${unc ? 'wsl:' + unc[1] : 'windows'}\n`) } catch {}
+
+function run(file, args, options) {
+  const child = spawn(file, args, { stdio: 'inherit', windowsHide: false, ...options })
+  child.on('error', (error) => {
+    process.stderr.write(`terminal-launcher: ${error.message}\r\n`)
+    process.exit(1)
+  })
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+}
+
+if (unc) {
+  const distro = unc[1]
+  const linuxPath = '/' + unc[2].replace(/\\/g, '/')
+  const user = userFromLinuxPath(linuxPath) || userFor(distro)
+  const userArgs = user ? ['-u', user] : []
+  // Match the Agent's clean environment: keep the login PATH but drop every
+  // `/mnt/*` interop entry. A probe failure falls back to the normal login shell.
+  let cleanPath = ''
+  try {
+    const login = execFileSync('wsl.exe', ['-d', distro, ...userArgs, '-e', 'bash', '-lc', 'printenv PATH'], {
+      encoding: 'utf8', windowsHide: true, timeout: 10_000,
+    }).trim()
+    cleanPath = login.split(':').filter((entry) => entry && !/^\/mnt(\/|$)/i.test(entry)).join(':')
+    appendFileSync(LOG, `${new Date().toISOString()} user=${user || '(default)'} cleanPath mnt=${login.split(':').filter((entry) => /^\/mnt(\/|$)/i.test(entry)).length}\n`)
+  } catch {}
+  // Do not hand wsl.exe a UNC cwd of its own: --cd already points at the
+  // directory, and a UNC process cwd makes Windows tools complain.
+  const args = ['-d', distro, ...userArgs, '--cd', linuxPath]
+  if (cleanPath) {
+    const script = `export PATH='${cleanPath.replace(/'/g, `'\\''`)}'; exec bash -i`
+    args.push('-e', 'bash', '-lc', script)
+  } else {
+    args.push('-e', 'bash', '-l')
+  }
+  run('wsl.exe', args, { cwd: process.env.SystemRoot ?? 'C:\\Windows' })
+} else {
+  // Leave Windows workspaces exactly as they were: their configured shell.
+  run(process.env.DSH_WSL_WIN_SHELL ?? 'pwsh.exe', [], { cwd })
+}

package/worktree-tool-v2.mjs

@@ -0,0 +1,102 @@
+// Model-facing worktree creation inside the WSL world.
+//
+// The shipped `create_worktree` tool is a Host runtime: it enters the checkout
+// by changing the Session working directory, which resolves through the Host
+// filesystem. That cannot work for a Linux path. This tool creates the same
+// kind of retained checkout with Linux git and returns its path; the Session
+// cwd stays unchanged, so callers pass `workdir`/the explicit path instead.
+import { registry } from './src/registry.mjs'
+import { linuxPathFromUnc } from './src/preset-default.mjs'
+import { userFor } from './src/settings.mjs'
+
+export const name = 'dsh-wsl/worktree'
+export const inject = ['tools']
+
+function brokerFor(cwd) {
+  const match = /^\\\\[?]?(?:wsl\.localhost|wsl\$)\\([^\\]+)\\/i.exec(String(cwd ?? ''))
+  const distro = match ? match[1] : ''
+  return registry.get(distro, userFor(distro))
+}
+
+function sanitize(name) {
+  return String(name ?? '').trim().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+export function apply(ctx) {
+  const tool = {
+    name: 'create_wsl_worktree',
+    description: 'Create a retained Git worktree inside the WSL distribution. Returns its Linux path, branch and base commit. The Session working directory does not change: pass the returned path explicitly (or as workdir) to later tools.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Optional worktree/branch suffix; defaults to a timestamp.' },
+        from: { type: 'string', description: 'Optional commit/ref to start from; defaults to HEAD.' },
+      },
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          branch: { type: 'string' },
+          baseCommit: { type: 'string' },
+          repositoryRoot: { type: 'string' },
+        },
+        additionalProperties: true,
+      },
+      render: (_args, value) => [{ type: 'text', text: `worktree ${value.path}\nbranch ${value.branch}\nbase ${value.baseCommit}` }],
+    },
+    async execute(args, exec) {
+      const session = exec?.agent?.session
+      const agentCwd = exec?.agent?.cwd
+      const headerCwd = session?.header?.cwd ?? ctx.get('workingDirectory')?.get?.(session)
+      // `agent.cwd` can be `/` in the tool context even when the Session is in
+      // a WSL workspace; prefer the recorded UNC cwd in that case.
+      const source = (typeof agentCwd === 'string' && agentCwd !== '' && agentCwd !== '/') ? agentCwd : (headerCwd || agentCwd || '/')
+      const linux = linuxPathFromUnc(source) ?? (source.startsWith('/') ? source : undefined)
+      if (linux === undefined) throw new Error(`create_wsl_worktree: the Session is not in a WSL workspace (cwd=${source})`)
+      const broker = brokerFor(source)
+      const rootResult = await broker.call('exec', { argv: ['git', '-C', linux, 'rev-parse', '--show-toplevel'], cwd: linux })
+      if (rootResult.code !== 0) {
+        throw new Error(`create_wsl_worktree: not a Git repository: ${rootResult.err || rootResult.out} (source=${source} linux=${linux} session=${session?.id ?? ''} header=${headerCwd ?? ''} agentCwd=${agentCwd ?? ''} keys=${Object.keys(exec?.agent ?? {}).join(',')})`)
+      }
+      const repositoryRoot = rootResult.out.trim()
+      // Keep the retained checkouts out of the parent's status/snapshots; the
+      // diff recorder also excludes this path, but the Host recorder reads Git
+      // directly and needs the exclude file.
+      try {
+        const exclude = await broker.call('exec', {
+          argv: ['git', '-C', repositoryRoot, 'rev-parse', '--path-format=absolute', '--git-path', 'info/exclude'],
+          cwd: repositoryRoot,
+        })
+        let excludePath = exclude.out.trim()
+        if (!excludePath.startsWith('/')) excludePath = `${repositoryRoot.replace(/\/+$/, '')}/${excludePath}`
+        if (excludePath) {
+          await broker.call('exec', {
+            argv: ['bash', '-c', `grep -qxF '.agents/worktrees/' ${shellQuote(excludePath)} 2>/dev/null || printf '%s\\n' '.agents/worktrees/' >> ${shellQuote(excludePath)}`],
+            cwd: repositoryRoot,
+          })
+        }
+      } catch {}
+      const suffix = sanitize(args?.name) || `wt-${Date.now().toString(36)}`
+      const branch = `dsh/${suffix}`
+      const target = `${repositoryRoot.replace(/\/+$/, '')}/.agents/worktrees/${suffix}`
+      const from = args?.from ? String(args.from) : 'HEAD'
+      const created = await broker.call('exec', {
+        argv: ['git', '-C', repositoryRoot, 'worktree', 'add', '-b', branch, target, from],
+        cwd: repositoryRoot,
+      })
+      if (created.code !== 0) throw new Error(`create_wsl_worktree: ${created.err || created.out || `git exited ${created.code}`}`)
+      const base = await broker.call('exec', { argv: ['git', '-C', target, 'rev-parse', 'HEAD'], cwd: target })
+      return { path: target, branch, baseCommit: base.out.trim(), repositoryRoot }
+    },
+  }
+
+  const dispose = ctx.tools.register(tool)
+  return () => { dispose() }
+}

package/world.js

@@ -0,0 +1,112 @@
+// The WSL execution world: one preset-scoped `ctx.subprocess` for Linux.
+//
+// NOTE: no `#private` members here on purpose. Cordis wraps a Service instance
+// in a context proxy, so methods can run with a `this` that is not the branded
+// original; V8 then throws "Receiver must be an instance of class ...". Plain
+// underscore properties survive that indirection.
+//
+// It also does not hard-depend on `@deepseek-ai/dsh-subprocess`: a
+// profile-installed plugin cannot resolve the harness' own packages (verified:
+// ERR_MODULE_NOT_FOUND from the profile), so the Service base is imported when
+// available and otherwise replaced by a shim that registers through Context.
+import { appendFileSync } from 'node:fs'
+import { registry } from './src/registry.mjs'
+import { parseWslUnc } from './src/broker.mjs'
+import { createWslSubprocess } from './src/subprocess.mjs'
+import { defaultDistro, userFor } from './src/settings.mjs'
+import { userFromLinuxPath } from './src/path-user.mjs'
+
+const LOG = 'C:\\Users\\Yunson\\dsh-wsl-plugin\\wsl-world.log'
+const DEBUG = process.env.DSH_WSL_DEBUG === '1'
+function log(line) {
+  if (DEBUG) try { appendFileSync(LOG, `${new Date().toISOString()} ${line}\n`) } catch {}
+}
+
+let Base = null
+let baseError = ''
+try {
+  const mod = await import('@deepseek-ai/dsh-subprocess')
+  Base = mod.SubprocessRuntime ?? mod.default ?? null
+} catch (error) {
+  baseError = String(error?.code ?? error?.message ?? error)
+  Base = null
+}
+log(`import base=${Base ? 'real' : 'shim'}${baseError ? ` (${baseError})` : ''}`)
+
+class ServiceShim {
+  constructor(ctx) {
+    this.ctx = ctx
+    if (typeof ctx.set !== 'function') {
+      throw new Error('subprocess-wsl: this Harness build exposes neither the Service base class nor ctx.set')
+    }
+    ctx.provide?.('subprocess')
+    ctx.set('subprocess', this)
+    log('shim installed ctx.subprocess')
+  }
+}
+
+const Parent = Base ?? ServiceShim
+
+export default class WslSubprocessWorld extends Parent {
+  _impls = new Map()
+  _config = {}
+
+  constructor(ctx, config = {}) {
+    super(ctx)
+    if (!this.ctx) this.ctx = ctx
+    this._config = config ?? {}
+    log(`ctor ok base=${Base ? 'real' : 'shim'} distro=${this._config.distro ?? ''}`)
+  }
+
+  /** One implementation per (distro, user); sessions in different distros coexist. */
+  _for(cwd) {
+    const parsed = parseWslUnc(cwd)
+    const distro = parsed?.distro ?? (this._config.distro || defaultDistro())
+    // The workspace path wins: /home/alice means alice, /root means root.
+    const linux = parsed?.linuxPath ?? (typeof cwd === 'string' && cwd.startsWith('/') ? cwd : '')
+    const user = this._config.user || userFromLinuxPath(linux) || userFor(distro)
+    const key = `${distro}|${user}`
+    if (!this._impls) this._impls = new Map()
+    let impl = this._impls.get(key)
+    if (!impl) {
+      // Shared with the panel, so its connection state is the session's state.
+      const broker = registry.get(distro, user)
+      // Resolve the login PATH (minus /mnt) before the first command: the
+      // spawn path is synchronous, so it falls back until this connect lands.
+      broker.connect().catch(() => {})
+      impl = createWslSubprocess({ broker, distro, user })
+      this._impls.set(key, impl)
+      log(`impl created for ${key}`)
+    }
+    return impl
+  }
+
+  resolveExecutable(command, env, signal) {
+    log(`resolveExecutable ${command}`)
+    return this._for(undefined).resolveExecutable(command, env, signal)
+  }
+
+  terminalEnvironment(signal) {
+    return this._for(undefined).terminalEnvironment(signal)
+  }
+
+  spawn(spec) {
+    log(`spawn cwd=${spec?.cwd} argv=${JSON.stringify(spec?.argv)}`)
+    return this._for(spec?.cwd).spawn(spec)
+  }
+
+  async spawnTerminal(spec, delegate) {
+    // Delegate to the host PTY: wsl.exe allocates the tty, Linux bash inherits
+    // it. `root` is outside this isolate realm, so it is the local provider.
+    const host = delegate ?? this.ctx?.root?.get?.('subprocess')
+    if (!host || host === this) {
+      throw Object.assign(new Error('subprocess-wsl: host PTY provider unavailable'), { code: 'SUBPROCESS_UNSUPPORTED' })
+    }
+    return this._for(spec?.cwd).spawnTerminal(spec, host)
+  }
+
+  async dispose() {
+    for (const impl of this._impls?.values() ?? []) await impl.dispose?.().catch(() => {})
+    this._impls?.clear()
+  }
+}