@herenfor/dsh-wsl 0.0.0-stage → 0.1.0

package/sessions.mjs

@@ -0,0 +1,101 @@
+// Merging the two Hosts' Workspace and Session views for the page. Frames from the WSL Host have already had their
+// identities prefixed (ids.mjs). Kept free of DSH imports so it can be unit-tested.
+//
+// A folder can be known to both Hosts: a Windows folder whose Sessions run in WSL has a twin Workspace on the WSL Host
+// (D:\code\proj here, /mnt/d/code/proj there). The page shows one folder row; the twin's Sessions are listed in it.
+// A folder only the WSL Host knows (\\wsl.localhost\Ubuntu\home\...) is a row of its own.
+
+import { isWsl, toPage } from './ids.mjs'
+import { toWindowsSpec, toWslSpec } from './paths.mjs'
+
+const empty = () => ({ items: [], archivedSessionIds: [], pinnedSessionIds: [] })
+
+/** How the WSL Host names a path of this Host, and how this Host shows a WSL Host path. */
+export function pathMapping(platform, distro) {
+  const win = platform === 'win32'
+  const unc = (path) => typeof path === 'string' && /^[\\/]{2}(?:wsl\.localhost|wsl\$)[\\/]/i.test(path)
+  return {
+    toWsl: (path) => (win || unc(path) ? toWslSpec(path) : path),
+    toLocal: (path) => (win ? toWindowsSpec(path, distro) : path),
+    /** A path naming a folder that lives in WSL (\\wsl.localhost\..., \\wsl$\...). */
+    insideWsl: unc,
+  }
+}
+
+/** Apply one `workspace/follow` frame to a source's state. */
+export function applyWorkspaceFrame(state, frame) {
+  switch (frame.type) {
+    case 'baseline': case 'replace': return { ...frame.value, items: [...frame.value.items] }
+    case 'upsert': return { ...state, items: [...state.items.filter((w) => w.workspaceId !== frame.workspace.workspaceId), frame.workspace] }
+    case 'remove': return { ...state, items: state.items.filter((w) => w.workspaceId !== frame.workspaceId) }
+    case 'order': return { ...state, items: [...state.items].sort((a, b) => frame.workspaceIds.indexOf(a.workspaceId) - frame.workspaceIds.indexOf(b.workspaceId)) }
+    case 'archived': return { ...state, archivedSessionIds: frame.archivedSessionIds }
+    case 'pinned': return { ...state, pinnedSessionIds: frame.pinnedSessionIds }
+    default: return state
+  }
+}
+
+/**
+ * The page's view of both Hosts' Workspaces. Returns the merged baseline and the twin pairs found
+ * (local workspaceId → WSL workspaceId, both as the page names them).
+ */
+export function mergeWorkspaces(local = empty(), wsl = empty(), paths) {
+  const byWslPath = new Map(wsl.items.map((w) => [w.path, w]))
+  const twins = new Map()
+  const items = local.items.map((w) => {
+    const twin = byWslPath.get(paths.toWsl(w.path))
+    if (!twin) return w
+    twins.set(w.workspaceId, twin.workspaceId)
+    return { ...w, sessionIds: [...w.sessionIds, ...twin.sessionIds] }
+  })
+  const folded = new Set(twins.values())
+  for (const w of wsl.items) if (!folded.has(w.workspaceId)) items.push({ ...w, path: paths.toLocal(w.path) })
+  return {
+    value: {
+      items,
+      archivedSessionIds: [...local.archivedSessionIds, ...wsl.archivedSessionIds],
+      pinnedSessionIds: [...local.pinnedSessionIds, ...wsl.pinnedSessionIds],
+    },
+    twins,
+  }
+}
+
+/** Session summaries from the WSL Host, with paths as this Host shows them. */
+export const localizeSessions = (items, paths) => items.map((s) => (typeof s.cwd === 'string' ? { ...s, cwd: paths.toLocal(s.cwd) } : s))
+
+/** A `session/control` baseline as live projection frames, one per Session (for a baseline that arrives late). */
+export const baselineFrames = (baseline) => Object.entries(baseline.projections ?? {}).map(([sessionId, block]) => ({
+  type: 'projection',
+  sessionId,
+  seq: block.asOfSeq ?? 0,
+  changes: Object.entries(block.values ?? {}).map(([key, val]) => ({ key, val })),
+}))
+
+/** `session/control` baseline from the WSL Host: its projections are keyed by Session id. */
+export const prefixProjections = (baseline) => ({
+  ...baseline,
+  projections: Object.fromEntries(Object.entries(baseline.projections ?? {}).map(([id, block]) => [toPage(id), block])),
+})
+
+/** One `$events` frame from the WSL Host: `api-session/*` events name their Session as the first argument. */
+export function prefixEvent(frame) {
+  if (frame.type === 'emit' && /^api-session\//.test(frame.event) && typeof frame.args?.[0] === 'string' && !isWsl(frame.args[0])) {
+    return { ...frame, args: [toPage(frame.args[0]), ...frame.args.slice(1)] }
+  }
+  return frame
+}
+
+/**
+ * Where a new Session goes. `target` is the run location chosen for the folder ('wsl' or 'local'); `twin` is the WSL
+ * Host's Workspace for a local folder, if it has one. Returns the Host and the request to send there (identities as
+ * the page names them; the caller strips the prefix for the WSL Host), or `needsTwin` when the WSL Host must first
+ * adopt the folder.
+ */
+export function placeSession(request, { target, twin }) {
+  const { workspaceId, sessionId, ...rest } = request
+  if (workspaceId === undefined) return { host: 'local', request }
+  if (isWsl(workspaceId)) return { host: 'wsl', request: { ...rest, workspaceId, ...(isWsl(sessionId) ? { sessionId } : {}) } }
+  if (target !== 'wsl') return { host: 'local', request: { ...rest, workspaceId, ...(sessionId !== undefined && !isWsl(sessionId) ? { sessionId } : {}) } }
+  if (twin === undefined) return { host: 'wsl', needsTwin: true, request: { ...rest, ...(isWsl(sessionId) ? { sessionId } : {}) } }
+  return { host: 'wsl', request: { ...rest, workspaceId: twin, ...(isWsl(sessionId) ? { sessionId } : {}) } }
+}

package/settings.mjs

@@ -0,0 +1,53 @@
+// Settings for plugins installed only in WSL. Kept free of DSH imports so it can be unit-tested.
+// The page reads every settings namespace with settings/describe and writes one namespace at a time with
+// settings/update, settings/replace or settings/mutate (argument `ns`). A namespace only the WSL Host serves belongs
+// to a plugin installed only there: describe shows it next to this Host's own, and writes to it go to the WSL Host.
+// Namespaces both Hosts serve stay on this Host (which side they should follow is an open design question).
+
+export const SETTINGS_WRITES = new Set(['update', 'replace', 'mutate'])
+
+/** The settings method an /api path names, or undefined. */
+export function settingsMethod(pathname) {
+  const m = /^\/api\/settings\/([A-Za-z]+)$/.exec(pathname)
+  return m?.[1]
+}
+
+/**
+ * @param local - this Host's describe value { writable, hasDocument, namespaces: [{ ns, ... }] }.
+ * @param remote - the WSL Host's describe value.
+ * @returns { value, remoteNamespaces } where value lists this Host's namespaces, then the WSL-only ones.
+ */
+export function mergeDescribe(local, remote) {
+  const mine = new Set(local.namespaces.map((view) => view.ns))
+  const extra = (remote?.namespaces ?? []).filter((view) => !mine.has(view.ns))
+  return { value: { ...local, namespaces: [...local.namespaces, ...extra] }, remoteNamespaces: new Set(extra.map((view) => view.ns)) }
+}
+
+// Desktop is the source of truth for every setting both Hosts have: those are copied to the WSL Host, one way.
+// Never copied: secret fields (each side keeps its own), and namespaces that describe one machine only.
+export const NEVER_SYNC = new Set(['bash-sandbox', 'pwsh-sandbox'])
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b)
+const secretKeys = (view) => new Set((view?.secrets ?? []).map((s) => s.path?.[0]).filter(Boolean))
+
+/**
+ * The mutate ops that make the WSL Host's user section of one namespace match this Host's, top-level field by field.
+ * @param desktop - this Host's view { user, secrets }.
+ * @param wsl - the WSL Host's view { user, secrets }.
+ * @returns ops: set for a differing field, unset for a field only the WSL Host has; secret fields untouched.
+ */
+export function syncOps(desktop, wsl) {
+  const skip = new Set([...secretKeys(desktop), ...secretKeys(wsl)])
+  const mine = desktop?.user && typeof desktop.user === 'object' ? desktop.user : {}
+  const theirs = wsl?.user && typeof wsl.user === 'object' ? wsl.user : {}
+  const ops = []
+  for (const [key, value] of Object.entries(mine)) if (!skip.has(key) && !same(theirs[key], value)) ops.push({ op: 'set', path: [key], value })
+  for (const key of Object.keys(theirs)) if (!skip.has(key) && !(key in mine)) ops.push({ op: 'unset', path: [key] })
+  return ops
+}
+
+/** The namespaces to copy: both Hosts have them and none is machine-specific. */
+export function sharedNamespaces(desktopViews, wslViews) {
+  const theirs = new Map(wslViews.map((v) => [v.ns, v]))
+  return desktopViews.filter((v) => theirs.has(v.ns) && !NEVER_SYNC.has(v.ns)).map((v) => ({ ns: v.ns, desktop: v, wsl: theirs.get(v.ns) }))
+}

package/setup.mjs

@@ -0,0 +1,286 @@
+// First-run setup of the WSL side (docs/deployment.md). Runs in the Desktop Host. Finds the WSL distribution, its Node
+// and DSH, and says what is missing. Downloads happen only when the person asks (the "install" button runs
+// installScript in WSL); otherwise the commands are shown, or handed to a Windows DSH task as a prompt. What needs no
+// network (the bridge files, the WSL profile and its plugin) is done here and by the daemon.
+//
+// Two ways to run DSH in WSL, chosen by the person when WSL already has a DSH of their own:
+//   reuse    their DSH and its data (~/.dsh): Desktop's WSL tasks and their own DSH sessions see each other
+//   private  a DSH of this plugin's own (~/.dsh-wsl/dsh) with its own data (~/.dsh-wsl/home); nothing is shared, so
+//            two DSH versions never write the same data
+// WSL side layout, in the distribution's home:
+//   ~/.dsh-wsl/node/     Node, when the distribution has none new enough
+//   ~/.dsh-wsl/dsh/      private: DSH, npm --prefix
+//   ~/.dsh-wsl/home/     private: the DSH home (sessions, workspaces, profiles)
+//   ~/.dsh-wsl/bridge/   transport/ and agent/, copied from this plugin (by setup)
+//   ~/.dsh-wsl/run/      the daemon's socket, token, identity and log
+// Versions: the two DSH must share major.minor (compatibleRelease); a WSL DSH older than that is updated, a newer one
+// asks for a Desktop update. Within major.minor they connect, and the person may still align them.
+import { inLanguage } from './language.mjs'
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join, posix, win32 } from 'node:path'
+
+export const NODE_VERSION = '24.22.2'
+export const MIN_NODE = [24, 9, 0]
+export const PROFILE = 'desktop-wsl'
+
+/** Run a command; resolves {code, stdout (Buffer), stderr}. Never rejects (a missing executable gives code null). */
+export function run(command, args, { timeout = 60_000, input } = {}) {
+  return new Promise((resolve) => {
+    const child = execFile(command, args, { encoding: 'buffer', timeout, windowsHide: true, maxBuffer: 4 << 20 }, (error, stdout, stderr) => {
+      resolve({ code: error ? (typeof error.code === 'number' ? error.code : null) : 0, error: error?.code, stdout: stdout ?? Buffer.alloc(0), stderr: (stderr ?? Buffer.alloc(0)).toString('utf8') })
+    })
+    if (input !== undefined) child.stdin.end(input)
+  })
+}
+
+/** wsl.exe writes its own messages in UTF-16LE (without BOM); programs it runs write UTF-8. */
+export function decodeWslText(buffer) {
+  const b = Buffer.from(buffer)
+  const utf16 = b.length >= 2 && (b[1] === 0 || (b[0] === 0xff && b[1] === 0xfe))
+  return (utf16 ? b.toString('utf16le') : b.toString('utf8')).replace(/^\uFEFF/, '').replace(/\0/g, '')
+}
+
+/** `wsl.exe --list --verbose`: rows of `* Ubuntu  Running  2`; the starred one is the default. */
+export function parseDistros(text) {
+  const rows = []
+  for (const line of text.split(/\r?\n/).slice(1)) {
+    const m = /^\s*(\*)?\s*(\S.*?)\s{2,}(\S+)\s+(\d)\s*$/.exec(line)
+    if (m) rows.push({ name: m[2], isDefault: m[1] === '*', state: m[3], version: Number(m[4]) })
+  }
+  return rows
+}
+
+// One shell script answers everything setup needs to know about a distribution, as key=value lines.
+const PROBE = String.raw`H="$HOME"; echo "home=$H"; echo "arch=$(uname -m)"
+for c in "$H/.dsh-wsl/node/bin/node" "$H/.local/bin/node" "$(command -v node 2>/dev/null)" /usr/local/bin/node /usr/bin/node; do
+  [ -n "$c" ] && [ -x "$c" ] && echo "node=$c $("$c" -v 2>/dev/null)"
+done
+P="$H/.dsh-wsl/dsh/node_modules/@deepseek-ai/dsh/package.json"; [ -f "$P" ] && echo "dsh=$(tr -d '\n' < "$P")"
+for c in "$(bash -lc 'command -v dsh' 2>/dev/null | tail -n1)" "$H/.local/bin/dsh" /usr/local/bin/dsh /usr/bin/dsh; do
+  [ -n "$c" ] && [ -e "$c" ] || continue
+  r=$(readlink -f "$c"); d=$(dirname "$r")
+  while [ -n "$d" ] && [ "$d" != / ]; do
+    if [ -f "$d/package.json" ] && grep -q '"name": *"@deepseek-ai/dsh"' "$d/package.json"; then echo "own=$r|$d|$(tr -d '\n' < "$d/package.json")"; break; fi
+    d=$(dirname "$d")
+  done
+done
+true`
+
+/** Parse the probe's output. */
+export function parseProbe(text) {
+  const out = { home: undefined, arch: undefined, nodes: [], dsh: null, own: null }
+  for (const line of text.split(/\r?\n/)) {
+    const i = line.indexOf('='); if (i < 0) continue
+    const key = line.slice(0, i); const value = line.slice(i + 1)
+    if (key === 'home') out.home = value
+    else if (key === 'arch') out.arch = value
+    else if (key === 'node') { const [path, version] = value.split(' '); if (version && !out.nodes.some((n) => n.path === path)) out.nodes.push({ path, version }) }
+    else if (key === 'dsh') { try { const pkg = JSON.parse(value); out.dsh = { version: pkg.version, bin: typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.dsh } } catch {} }
+    else if (key === 'own' && !out.own) {
+      const [entry, pkgDir, ...json] = value.split('|')
+      // The plugin's private DSH is not the person's own.
+      if (out.home && pkgDir.startsWith(`${out.home}/.dsh-wsl/`)) continue
+      try { const pkg = JSON.parse(json.join('|')); out.own = { entry, pkgDir, version: pkg.version, prefix: npmPrefixOf(pkgDir) } } catch {}
+    }
+  }
+  return out
+}
+
+/** The npm prefix a global install lives under (<prefix>/lib/node_modules/@deepseek-ai/dsh), else null. */
+export const npmPrefixOf = (pkgDir) => /^(.*)\/lib\/node_modules\/@deepseek-ai\/dsh$/.exec(pkgDir ?? '')?.[1] ?? null
+
+const parseVersion = (v) => (/^v?(\d+)\.(\d+)\.(\d+)/.exec(v ?? '') ?? []).slice(1).map(Number)
+/** Semver order of two versions (prereleases before their release; numeric identifiers compared as numbers). */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a); const pb = parseVersion(b)
+  for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) < (pb[i] ?? 0) ? -1 : 1
+  const ra = /-([^+]+)/.exec(a ?? '')?.[1]; const rb = /-([^+]+)/.exec(b ?? '')?.[1]
+  if (ra === rb) return 0
+  if (ra === undefined) return 1
+  if (rb === undefined) return -1
+  const xa = ra.split('.'); const xb = rb.split('.')
+  for (let i = 0; i < Math.max(xa.length, xb.length); i++) {
+    if (xa[i] === undefined) return -1
+    if (xb[i] === undefined) return 1
+    const na = /^\d+$/.test(xa[i]); const nb = /^\d+$/.test(xb[i])
+    if (xa[i] === xb[i]) continue
+    if (na && nb) return Number(xa[i]) < Number(xb[i]) ? -1 : 1
+    if (na !== nb) return na ? -1 : 1
+    return xa[i] < xb[i] ? -1 : 1
+  }
+  return 0
+}
+/** The two DSH can work together: same major.minor. */
+export function compatibleRelease(a, b) {
+  const pa = parseVersion(a); const pb = parseVersion(b)
+  return pa.length === 3 && pb.length === 3 && pa[0] === pb[0] && pa[1] === pb[1]
+}
+export const nodeOk = (v) => { const p = parseVersion(v); if (p.length < 3) return false; for (let i = 0; i < 3; i++) if (p[i] !== MIN_NODE[i]) return p[i] > MIN_NODE[i]; return true }
+
+/**
+ * Where the WSL side stands. `listing` is {error?} or {distros}; `chosen` is {distro?, mode?}; `probe` is parseProbe's
+ * result for the distribution (absent when there is none). States: no-wsl, no-distro, wsl1, choose (WSL has the
+ * person's own DSH and no mode is chosen), needs-node, needs-dsh, version-mismatch (WSL's DSH too old),
+ * desktop-outdated (WSL's DSH newer than Desktop's major.minor), ready (with `drift` when versions differ within it).
+ */
+export function evaluate({ desktopVersion, listing, chosen = {}, probe }) {
+  if (listing.error) return { state: 'no-wsl', distros: [] }
+  const distros = listing.distros
+  if (distros.length === 0) return { state: 'no-distro', distros }
+  const distro = distros.find((d) => d.name === chosen.distro) ?? distros.find((d) => d.isDefault) ?? distros[0]
+  const base = { distro: distro.name, distros, home: probe?.home, arch: probe?.arch, own: probe?.own ?? null }
+  if (distro.version === 1) return { ...base, state: 'wsl1' }
+  if (!probe) return { ...base, state: 'error', error: 'cannot look into the distribution' }
+  const node = probe.nodes.find((n) => nodeOk(n.version))
+  let mode = chosen.mode === 'reuse' && !probe.own ? undefined : chosen.mode
+  if (mode !== 'reuse' && mode !== 'private') {
+    if (probe.own) return { ...base, state: 'choose', node }
+    mode = 'private'
+  }
+  const dsh = mode === 'reuse'
+    ? { version: probe.own.version, entry: probe.own.entry }
+    : probe.dsh && { version: probe.dsh.version, entry: posix.join(probe.home, '.dsh-wsl', 'dsh', 'node_modules', '@deepseek-ai', 'dsh', probe.dsh.bin ?? 'lib/bin.js') }
+  const at = { ...base, mode, node, dshHome: mode === 'private' ? posix.join(probe.home, '.dsh-wsl', 'home') : null }
+  if (!dsh) return { ...at, state: node ? 'needs-dsh' : 'needs-node' }
+  at.installed = dsh.version
+  if (!node) return { ...at, state: 'needs-node' }
+  at.dshEntry = dsh.entry
+  const order = compareVersions(dsh.version, desktopVersion)
+  if (!compatibleRelease(dsh.version, desktopVersion)) return { ...at, state: order < 0 ? 'version-mismatch' : 'desktop-outdated' }
+  return { ...at, state: 'ready', drift: order === 0 ? null : order < 0 ? 'wsl-older' : 'wsl-newer' }
+}
+
+const INSTALLS = new Set(['needs-node', 'needs-dsh', 'version-mismatch'])
+/** Whether the DSH install/update commands apply (also offered when versions merely drift with WSL behind). */
+export const canInstall = (status) => INSTALLS.has(status.state) || (status.state === 'ready' && status.drift === 'wsl-older')
+
+/** The commands the person runs in the WSL terminal for this state (empty when none apply). */
+export function commandsFor(status, desktopVersion, lang = 'zh') {
+  const say = (texts) => inLanguage(lang, texts)
+  if (!canInstall(status)) return ''
+  const lines = []
+  const arch = status.arch === 'aarch64' ? 'arm64' : 'x64'
+  const nodeDir = status.node ? posix.dirname(status.node.path) : '$HOME/.dsh-wsl/node/bin'
+  if (status.state === 'needs-node') {
+    const name = `node-v${NODE_VERSION}-linux-${arch}`
+    lines.push(say({ zh: '# 1. Node.js（只给这个插件用，装在 ~/.dsh-wsl/node）', en: '# 1. Node.js (for this plugin only, in ~/.dsh-wsl/node)' }))
+    lines.push(`mkdir -p ~/.dsh-wsl && cd ~/.dsh-wsl && curl -fL https://nodejs.org/dist/v${NODE_VERSION}/${name}.tar.xz | tar -xJ && rm -rf node && mv ${name} node`)
+  }
+  const step = status.state === 'needs-node' ? '2. ' : ''
+  if (status.mode === 'reuse') {
+    const prefix = status.own?.prefix
+    lines.push(say({ zh: `# ${step}把你的 dsh 更新到 ${desktopVersion}（和 Desktop 同版本；你自己用的 dsh 也会一起更新）`, en: `# ${step}Update your dsh to ${desktopVersion} (the Desktop's version; the dsh you use yourself is updated too)` }))
+    lines.push(`PATH="${nodeDir}:$PATH" npm install -g ${prefix ? `--prefix "${prefix}" ` : ''}@deepseek-ai/dsh@${desktopVersion}`)
+  } else {
+    lines.push(say({ zh: `# ${step}DSH ${desktopVersion}（和 Desktop 同版本，装在 ~/.dsh-wsl/dsh）`, en: `# ${step}DSH ${desktopVersion} (the Desktop's version, in ~/.dsh-wsl/dsh)` }))
+    lines.push(`PATH="${nodeDir}:$PATH" npm install --prefix ~/.dsh-wsl/dsh @deepseek-ai/dsh@${desktopVersion}`)
+  }
+  return lines.join('\n')
+}
+
+/** What the install button runs in WSL (bash): stop the daemon first, so no DSH runs from files being replaced. */
+export function installScript(status, desktopVersion) {
+  const commands = commandsFor(status, desktopVersion).split('\n').filter((l) => l && !l.startsWith('#'))
+  if (!commands.length) return ''
+  return [
+    'set -eo pipefail',
+    `D="$HOME/.dsh-wsl/run/${PROFILE}/daemon.json"`,
+    'P=$(sed -n \'s/.*"pid":\\([0-9]*\\).*/\\1/p\' "$D" 2>/dev/null || true)',
+    'if [ -n "$P" ] && kill "$P" 2>/dev/null; then for i in $(seq 1 50); do kill -0 "$P" 2>/dev/null || break; sleep 0.2; done; echo "stopped the WSL side ($P)"; fi',
+    ...commands.map((c) => `echo "\$ ${c.replace(/["\\$`]/g, '\\$&')}"\n${c}`),
+    'echo "done"',
+  ].join('\n')
+}
+
+/** The same setup as a task for the Windows DSH: it runs the commands through wsl.exe and checks the result. */
+export function promptFor(status, desktopVersion, lang = 'zh') {
+  const commands = commandsFor(status, desktopVersion, lang)
+  if (!commands) return ''
+  const check = status.mode === 'reuse' ? 'dsh --version' : 'grep -m1 version ~/.dsh-wsl/dsh/node_modules/@deepseek-ai/dsh/package.json'
+  const en = [
+    `Please set up what the DSH WSL run mode needs in WSL (distribution ${status.distro}). Do not change anything else already in WSL, and do not use sudo.`,
+    '',
+    `In PowerShell, run the commands below one by one with \`wsl.exe -d ${status.distro} -- bash -lc '<command>'\` (lines starting with # are notes, not commands):`,
+    '',
+    '```bash', commands, '```',
+    '',
+    `When done, run \`wsl.exe -d ${status.distro} -- bash -lc '${check}'\` and confirm the version is ${desktopVersion}.`,
+    'If npm cannot find this version, it has not been published to npm yet: stop and tell me; do not install a different version.',
+    'On a network failure you may retry once; if it still fails, tell me the exact error.',
+  ]
+  const zh = [
+    `请帮我在 WSL（发行版 ${status.distro}）里装好 DSH WSL 运行模式需要的组件。不要改动 WSL 里已有的其他东西，也不要用 sudo。`,
+    '',
+    `在 PowerShell 里用 \`wsl.exe -d ${status.distro} -- bash -lc '<命令>'\` 依次执行下面的命令（# 开头的是说明，不用执行）：`,
+    '',
+    '```bash', commands, '```',
+    '',
+    `完成后执行 \`wsl.exe -d ${status.distro} -- bash -lc '${check}'\`，确认版本是 ${desktopVersion}。`,
+    '如果 npm 提示找不到这个版本，说明它还没有发布到 npm，停下来告诉我，不要改装别的版本。',
+    '网络失败时可以重试一次；仍然失败就把错误原文告诉我。',
+  ]
+  return inLanguage(lang, { zh, en }).join('\n')
+}
+
+/** Content stamp of the bridge files this plugin carries (transport/ and agent/). */
+export function stampOf(dirs) {
+  const hash = createHash('sha256')
+  for (const dir of dirs) for (const name of readdirSync(dir).sort()) {
+    const path = join(dir, name)
+    if (statSync(path).isFile()) hash.update(name).update(readFileSync(path))
+  }
+  return hash.digest('hex').slice(0, 16)
+}
+
+/**
+ * Copy transport/ and agent/ into the distribution's ~/.dsh-wsl/bridge when they differ from what is there.
+ * `root` is how this Host reaches the distribution's home (\\wsl.localhost\<distro>\home\<user> on Windows).
+ */
+export function installBridgeFiles(pluginDir, root) {
+  const sources = { transport: join(pluginDir, 'transport'), agent: join(pluginDir, 'agent') }
+  const stamp = stampOf(Object.values(sources))
+  const target = join(root, '.dsh-wsl', 'bridge')
+  const stampFile = join(target, 'STAMP')
+  if (existsSync(stampFile) && readFileSync(stampFile, 'utf8').trim() === stamp) return { stamp, copied: false }
+  mkdirSync(target, { recursive: true })
+  for (const [name, from] of Object.entries(sources)) {
+    rmSync(join(target, name), { recursive: true, force: true })
+    cpSync(from, join(target, name), { recursive: true, dereference: true, filter: (src) => !/[\\/]node_modules([\\/]|$)/.test(src) })
+  }
+  writeFileSync(stampFile, `${stamp}\n`)
+  return { stamp, copied: true }
+}
+
+/** How this Host reaches a path in the distribution. */
+export const hostPathOf = (platform, distro, path) => (platform === 'win32' ? win32.join(`\\\\wsl.localhost\\${distro}`, ...path.split('/').filter(Boolean)) : path)
+
+/**
+ * Check the WSL side. `wsl` is the wsl.exe command (a fake in tests). Returns evaluate()'s result plus the commands,
+ * the prompt, and the bridge command when ready.
+ */
+export async function check({ wsl = 'wsl.exe', desktopVersion, chosen = {}, pluginDir, platform = process.platform }) {
+  const list = await run(wsl, ['--list', '--verbose'], { timeout: 30_000 })
+  const listing = list.code === null ? { error: list.error ?? 'wsl.exe not found' }
+    : { distros: list.code === 0 ? parseDistros(decodeWslText(list.stdout)) : [] }
+  let probe
+  const pick = listing.distros?.find((d) => d.name === chosen.distro) ?? listing.distros?.find((d) => d.isDefault) ?? listing.distros?.[0]
+  if (pick && pick.version !== 1) {
+    const r = await run(wsl, ['-d', pick.name, '--exec', 'sh', '-c', PROBE], { timeout: 90_000 })
+    if (r.code === 0) probe = parseProbe(decodeWslText(r.stdout))
+    else listing.probeError = (decodeWslText(r.stdout) + r.stderr).trim().slice(0, 500)
+  }
+  const status = evaluate({ desktopVersion, listing, chosen, probe })
+  if (listing.probeError) status.probeError = listing.probeError
+  status.script = installScript(status, desktopVersion)
+  if (status.state === 'ready' && pluginDir) {
+    const bridgeDir = posix.join(status.home, '.dsh-wsl', 'bridge')
+    status.files = installBridgeFiles(pluginDir, hostPathOf(platform, status.distro, status.home))
+    status.bridge = {
+      command: wsl,
+      args: ['-d', status.distro, '--exec', status.node.path, posix.join(bridgeDir, 'transport', 'daemon.mjs'), '--bridge', '--profile', PROFILE, '--dsh', status.dshEntry, '--stamp', status.files.stamp, ...(status.dshHome ? ['--dsh-home', status.dshHome] : [])],
+    }
+  }
+  return status
+}

package/transport/client.mjs

@@ -0,0 +1,102 @@
+// Desktop side of the bridge: starts `wsl.exe ... daemon.mjs --bridge` (or any command speaking the same protocol),
+// multiplexes HTTP connections to the WSL DSH Host over its stdio, and keeps the Host's address and launch token in
+// memory only. Reconnects with backoff when the bridge process ends.
+import { spawn } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import http from 'node:http'
+import { Mux } from './mux.mjs'
+
+/**
+ * @param options.command - executable, e.g. 'wsl.exe' (or process.execPath in tests)
+ * @param options.args - its arguments, ending in '--bridge'
+ * @param options.resolve - instead of command/args: async () => {command, args} or null when the WSL side is not set
+ *   up; asked before every (re)connect. While it answers null the bridge waits for retry().
+ * @param options.caps - what this side serves for the WSL side, e.g. ['credentials'] (announced after hello)
+ * @returns a Bridge: events 'state' ({ connected, dsh, hello }); request(); agent; close()
+ */
+export function startBridge({ command, args, resolve, caps = [], log = () => {} }) {
+  const bridge = new EventEmitter()
+  let mux, child, stopped = false, delay = 500, timer, starting = false
+  bridge.state = { connected: false, dsh: { state: 'unknown' }, hello: null }
+  const set = (patch) => { bridge.state = { ...bridge.state, ...patch }; bridge.emit('state', bridge.state) }
+
+  const run = async () => {
+    timer = undefined
+    if (stopped || starting || child) return
+    starting = true
+    let target = { command, args }
+    try { if (resolve) target = await resolve() } catch (error) { log(`bridge: ${error.message}`); target = null }
+    starting = false
+    if (stopped) return
+    if (!target) { set({ connected: false, dsh: { state: 'unknown' } }); return }
+    child = spawn(target.command, target.args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+    child.stderr.on('data', (c) => { const text = c.toString('utf8').trimEnd(); log(`bridge stderr: ${text}`); if (text) set({ lastError: text.split('\n').slice(-1)[0] }) })
+    mux = new Mux(child.stdout, child.stdin, { side: 'opener' })
+    // Streams the WSL side opens (e.g. {kind:'credentials'}) go to the 'stream' listeners; none → refused.
+    mux.on('stream', (stream, target) => { if (bridge.listenerCount('stream') > 0) bridge.emit('stream', stream, target); else stream.destroy(new Error('not served')) })
+    mux.on('control', (m) => {
+      if (m.type === 'hello') { delay = 500; mux.control({ type: 'client', caps }); set({ connected: true, hello: m, lastError: undefined }) }
+      else if (m.type === 'dsh') set({ dsh: { state: m.state, origin: m.origin, token: m.token, exit: m.exit } })
+    })
+    const down = (why) => {
+      if (!bridge.state.connected && why === undefined) return
+      set({ connected: false, dsh: { state: 'unknown' } })
+      if (stopped) return
+      log(`bridge down${why ? `: ${why}` : ''}; retry in ${delay} ms`)
+      timer = setTimeout(run, delay); timer.unref?.()
+      delay = Math.min(delay * 2, 15_000)
+    }
+    const own = child
+    child.once('exit', (code) => { mux.close(); if (child === own) child = undefined; down(`exit ${code}`) })
+    child.once('error', (e) => down(e.message))
+  }
+  run()
+  /** Connect now if not connected (after the person set up the WSL side). */
+  bridge.retry = () => {
+    if (stopped || child || starting) return
+    clearTimeout(timer); delay = 500; void run()
+  }
+  /** Drop the connection and connect again (another distribution, a re-check). */
+  bridge.restart = () => {
+    if (stopped) return
+    clearTimeout(timer); delay = 500
+    if (child) child.kill()   // its exit reconnects after `delay`
+    else void run()
+  }
+
+  // HTTP over the bridge: every connection is one multiplexed stream to the DSH Host.
+  bridge.agent = new (class extends http.Agent {
+    createConnection(_options, callback) {
+      if (!mux || mux.closed || bridge.state.dsh.state !== 'running') {
+        const error = new Error(`WSL DSH Host not available (${bridge.state.connected ? bridge.state.dsh.state : 'bridge disconnected'})`)
+        if (callback) { process.nextTick(callback, error); return undefined }
+        throw error
+      }
+      const stream = mux.open({ kind: 'dsh' })
+      stream.setTimeout = () => stream; stream.setNoDelay = () => stream; stream.setKeepAlive = () => stream; stream.ref = () => stream; stream.unref = () => stream
+      if (callback) process.nextTick(callback, null, stream)
+      return stream
+    }
+  })({ keepAlive: false })
+
+  /** Resolve once the WSL DSH Host is running (or reject after timeoutMs). */
+  bridge.ready = (timeoutMs = 60_000) => new Promise((resolve, reject) => {
+    if (bridge.state.dsh.state === 'running') return resolve(bridge.state)
+    const timer = setTimeout(() => { bridge.off('state', on); reject(new Error('WSL DSH Host did not start in time')) }, timeoutMs)
+    const on = (s) => { if (s.dsh.state === 'running') { clearTimeout(timer); bridge.off('state', on); resolve(s) } }
+    bridge.on('state', on)
+  })
+
+  /** A Node http request to the WSL DSH Host; the Host header is its own authority, as its trust fence expects. */
+  bridge.request = (path, { method = 'GET', headers = {}, body } = {}) => new Promise((resolve, reject) => {
+    const { origin } = bridge.state.dsh
+    if (!origin) return reject(new Error('WSL DSH Host not available'))
+    const url = new URL(path, origin)
+    const req = http.request({ agent: bridge.agent, host: url.hostname, port: url.port, path: url.pathname + url.search, method, headers: { host: url.host, ...headers } }, resolve)
+    req.once('error', reject)
+    if (body !== undefined) req.end(body); else req.end()
+  })
+
+  bridge.close = () => { stopped = true; child?.kill(); mux?.close() }
+  return bridge
+}