dsh-wsl-desktop 0.7.2 → 0.7.3

package/lib/index.js

@@ -13,19 +13,25 @@
  * @module dsh-wsl-desktop
  */
 
-import { randomBytes, timingSafeEqual } from 'node:crypto'
-import { existsSync, watch as nativeFsWatch } from 'node:fs'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { homedir } from 'node:os'
+import { watch as nativeFsWatch } from 'node:fs'
+import { mkdir, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import z from '@deepseek-ai/schemastery'
 import {
   MAX_BODY_BYTES, DEV_TOKEN_HEADER, bodyAdmission, dispatchAdmission, fenceRejection, methodAdmission, preflight, tokenMatches,
 } from './http-admission.js'
+import {
+  connectionOf, devToken, isDeveloperCaller, readJsonBody, sendJson, sendRejection,
+} from './host/http.js'
+import {
+  GENERATED_PREFIX, basePluginsOf, runShellSpec, sourceDirFor, variantIdFor,
+} from './host/presets.js'
+import { bindingTape, hostSession, presetRun } from './host/state.js'
 import { buildVariantPlugins } from './wsl/preset.js'
 import { setLocalSubprocess } from './wsl/host-refs.js'
-import { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell, wslMajorVersion } from './wsl/world.js'
+import { checkLinuxPath, defaultWorkspaceUnc, listLinuxDir, resolveDistroHome, runWslShell } from './wsl/world.js'
+import { defaultDistro, listDistros, wslMajorVersion } from './wsl/distros.js'
 import { joinWslUnc, parseWslUnc, shellQuote, windowsToMntPath } from './wsl/paths.js'
 import { WslRouteError, browserFailure, routeErrorFor } from './route-errors.js'
 import { CHECK_IDS, CHECK_LABELS, CHECK_REMEDIES, DOCS, ERROR_CODES, FEATURE_IDS, FEATURE_LABELS } from './protocol.js'
@@ -87,23 +93,6 @@ const HERE = dirname(fileURLToPath(import.meta.url))
  */
 const SELF_MODULE = fileURLToPath(import.meta.url)
 
-/** Prefix of every preset this plugin owns; its own outputs are never sources. */
-const GENERATED_PREFIX = 'wsl-'
-
-/**
- * The generated variant id for a resolved base preset.
- *
- * A preset that is already a variant keeps its id; anything else gets the prefix. The
- * selftest and createWorkspace both derived it this way — the second site's own comment
- * admitted it resolved exactly like the first — so a change to the prefix rule had two
- * homes.
- * @param {{ id: string }} preset - the resolved base preset.
- * @returns {string} the variant id.
- */
-function variantIdFor(preset) {
-  return preset.id.startsWith(GENERATED_PREFIX) ? preset.id : `${GENERATED_PREFIX}${preset.id}`
-}
-
 /**
  * Module specifiers of the WSL providers, as the preset rows must name them.
  * The 0.1.7 loader imports row names via `new URL(name, baseUrl)` or a bare
@@ -132,30 +121,6 @@ const SANDBOX_MODULE = pathToFileURL(join(HERE, 'wsl', 'sandbox.js')).href
  */
 const SEARCH_MODULE = pathToFileURL(join(HERE, 'wsl', 'search-tool.js')).href
 
-/** Last preset materialization outcome, reported through the route. */
-let presetState = { status: 'pending' }
-
-/** Recent preset-binding decisions, reported through the route. */
-const bindingLog = []
-
-/** Most binding decisions kept for inspection. */
-const BINDING_LOG_LIMIT = 50
-
-/** The plugin context, captured so route methods can reach host services. */
-let hostCtx
-
-/**
- * The configured `wsl.exe` path, captured where the route methods can read it.
- *
- * The methods table is module-level (the route dispatcher calls into it without
- * carrying the plugin's config), so the configured path is held beside the
- * captured context rather than threaded through every signature.
- */
-let routeWslPath = 'wsl.exe'
-
-/** Whether the preset registry has been reached; `bootstrap` waits briefly for it. */
-let hostReady = false
-
 /** The plugin version, read from the shipped package.json once. */
 let pluginVersionValue = null
 
@@ -184,21 +149,21 @@ async function pluginVersion() {
  * @returns {Promise<object>} the probe, or a pending marker.
  */
 async function probeHostWhenReady() {
-  if (hostCtx === undefined) {
+  if (hostSession.ctx === undefined) {
     return { status: 'pending', features: {}, missing: [], checkedAt: new Date().toISOString() }
   }
   const deadline = Date.now() + 5_000
-  while (!hostReady && Date.now() < deadline) {
+  while (!hostSession.ready && Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, 100))
   }
-  if (!hostReady) {
+  if (!hostSession.ready) {
     // The registry never appeared. Probing the context anyway reports the missing
     // feature as degraded; returning `pending` here would leave the picker
     // proceeding against a world it cannot name a preset in.
-    if (hostCtx.get('agentPresets') === undefined) return probeHost(hostCtx)
+    if (hostSession.ctx.get('agentPresets') === undefined) return probeHost(hostSession.ctx)
     return { status: 'pending', features: {}, missing: [], checkedAt: new Date().toISOString() }
   }
-  return probeHost(hostCtx)
+  return probeHost(hostSession.ctx)
 }
 
 /**
@@ -209,14 +174,6 @@ const DISCOVERY_METHODS = new Set([
   'listDistros', 'defaultDistro', 'listDir', 'checkPath', 'resolve', 'resolveHome', 'wslPresetFor',
 ])
 
-/**
- * The harness home that holds the user preset root.
- * @returns {string} the resolved `$DSH_HOME`.
- */
-function dshHome() {
-  return process.env.DSH_HOME ?? join(homedir(), '.dsh')
-}
-
 /**
  * Resolve a location the caller supplied into one distribution plus Linux path.
  * @param {unknown} location - UNC path, absolute Linux path, or Windows drive path.
@@ -235,53 +192,6 @@ async function resolveLocation(location, distroHint) {
   return { distro, linuxPath, uncPath: joinWslUnc(distro, linuxPath) }
 }
 
-/**
- * Locate the directory a preset was discovered under.
- *
- * A preset may name a row by a path relative to its own directory, so the
- * variant needs that base to rewrite the name to something that still resolves
- * from where the variant lives.
- *
- * Both spellings are historical: the package is `@deepseek-ai/dsh-agent-preset`
- * (singular — the plural name never existed, so this resolve always threw), and
- * since the presets moved into profile YAML declarations the package ships no
- * `presets/<id>/agent.cordis.yml` tree at all. Neither branch is expected to
- * hit on a current desktop; a base preset that DOES use relative row names
- * therefore has no resolvable source directory, and `buildVariantPlugins`
- * leaves the name as it found it. This stays a lookup rather than a guess so
- * the failure mode is unchanged if a deployment ever ships that tree again.
- * @param {string} id - preset id.
- * @returns {string | undefined} the directory, or undefined when it cannot be found.
- */
-function sourceDirFor(id) {
-  const local = join(dshHome(), '.agent-presets', id)
-  if (existsSync(join(local, 'agent.cordis.yml'))) return local
-  try {
-    const manifest = fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-agent-preset/package.json'))
-    const shipped = join(dirname(manifest), 'presets', id)
-    if (existsSync(join(shipped, 'agent.cordis.yml'))) return shipped
-  } catch {
-    // A deployment without the preset package leaves relative names as they are.
-  }
-  return undefined
-}
-
-/**
- * Read a base preset's declared plugin rows as OBJECTS.
- *
- * 0.1.7 keeps each declaration's `PresetDefinition` — with `plugins` as entry
- * objects — in a registry map that is TS-private but reachable in-process
- * (ctx.get returns the service instance). No YAML parser is needed on this
- * path; the public readDocument only exposes a re-dumped text form.
- * @param {object} presets - the agentPresets service.
- * @param {string} id - base preset id.
- * @returns {readonly object[] | null} the declared rows, or null when unreachable.
- */
-function basePluginsOf(presets, id) {
-  const plugins = presets.definitions?.get?.(id)?.config?.plugins
-  return Array.isArray(plugins) ? plugins : null
-}
-
 /**
  * Derive and register the WSL variant presets (0.1.7-native).
  *
@@ -303,24 +213,6 @@ function basePluginsOf(presets, id) {
  *   refuses duplicates).
  * @returns {Promise<object>} the registration outcome for the route.
  */
-/**
- * Run a shell spec through whichever seam the host exposes, and always hand back a
- * handle whose `result()` is awaitable.
- *
- * 0.1.7 hosts expose `execute`, which resolves with a live handle; older ones have
- * only `run`, whose settled result carries no `result()` projection. Both selftest
- * steps used to spell that dual dispatch themselves, and the second one called
- * `.result()` on `run`'s settled result — a TypeError on exactly the hosts that
- * branch exists to support. One owner, so the two steps cannot drift again.
- * @param {object} shell - the realm's shell service.
- * @param {object} spec - the resolved spec to run.
- * @returns {Promise<{ result: () => Promise<object> }>} a result()-able handle.
- */
-function runShellSpec(shell, spec) {
-  if (typeof shell.execute === 'function') return shell.execute(spec)
-  return shell.run(spec).then((settled) => ({ result: async () => settled }))
-}
-
 async function materializePresets(ctx, distro, generation, previous) {
   const presets = ctx.get('agentPresets')
   if (presets === undefined) throw new Error('agentPresets 服务不可用')
@@ -415,12 +307,6 @@ async function materializePresets(ctx, distro, generation, previous) {
   return { written, skipped, hostCompat }
 }
 
-/** Serialises refreshPresets so boot-time and developer-token calls cannot interleave. */
-let refreshMutex = Promise.resolve()
-
-/** The live registration generation; teardown flips its disposed flag. */
-let currentGeneration = null
-
 /**
  * Refresh the presets, recording the outcome for the route.
  * @param {import('@deepseek-ai/cordis').Context} ctx - the plugin context.
@@ -429,7 +315,7 @@ let currentGeneration = null
  *   generation's lifecycle token (see materializePresets).
  * @returns {Promise<object>} the new preset state.
  */
-async function refreshPresets(ctx, distro, generation = currentGeneration) {
+async function refreshPresets(ctx, distro, generation = presetRun.generation) {
   const run = async () => {
     // A caller may omit the generation (developer-token regenerate before the
     // inject ran): mint a transient one so every disposer has an owner.
@@ -437,19 +323,19 @@ async function refreshPresets(ctx, distro, generation = currentGeneration) {
     // Withdrawal targets the PREVIOUS generation's disposers; a self-refresh
     // (developer-token regenerate) withdraws its own — the exact behaviour of
     // the historical shared map, minus the cross-generation teardown theft.
-    const previous = currentGeneration === gen ? gen : currentGeneration
-    currentGeneration = gen
-    presetState = { status: 'running' }
+    const previous = presetRun.generation === gen ? gen : presetRun.generation
+    presetRun.generation = gen
+    presetRun.state = { status: 'running' }
     try {
       const result = await materializePresets(ctx, distro, gen, previous)
-      presetState = { status: 'ready', ...result }
+      presetRun.state = { status: 'ready', ...result }
     } catch (error) {
-      presetState = { status: 'failed', error: error instanceof Error ? error.message : String(error) }
+      presetRun.state = { status: 'failed', error: error instanceof Error ? error.message : String(error) }
     }
-    return presetState
+    return presetRun.state
   }
-  const result = refreshMutex.then(run, run)
-  refreshMutex = result.then(() => {}, () => {})
+  const result = presetRun.mutex.then(run, run)
+  presetRun.mutex = result.then(() => {}, () => {})
   return result
 }
 
@@ -510,8 +396,8 @@ const METHODS = {
     return healthFor({
       distro,
       username,
-      wslPath: routeWslPath,
-      wslVersionProbe: ({ distro: name }) => wslMajorVersion(name, { wslPath: routeWslPath }),
+      wslPath: hostSession.wslPath,
+      wslVersionProbe: ({ distro: name }) => wslMajorVersion(name, { wslPath: hostSession.wslPath }),
     })
   },
 
@@ -519,7 +405,7 @@ const METHODS = {
    * List the installed distributions.
    * @returns {Promise<string[]>} distribution names.
    */
-  listDistros: () => listDistros({ wslPath: routeWslPath }),
+  listDistros: () => listDistros({ wslPath: hostSession.wslPath }),
 
   /**
    * Report the default distribution.
@@ -536,7 +422,7 @@ const METHODS = {
     assertDistro(distro)
     assertLinuxPath(path ?? '/')
     try {
-      return await listLinuxDir(distro, path ?? '/', { wslPath: routeWslPath })
+      return await listLinuxDir(distro, path ?? '/', { wslPath: hostSession.wslPath })
     } catch (error) {
       throw routeErrorFor(error, { distro, path })
     }
@@ -554,7 +440,7 @@ const METHODS = {
     const uncPath = joinWslUnc(distro, path)
     let facts
     try {
-      facts = await checkLinuxPath(distro, path, { wslPath: routeWslPath })
+      facts = await checkLinuxPath(distro, path, { wslPath: hostSession.wslPath })
     } catch (error) {
       throw routeErrorFor(error, { distro, path })
     }
@@ -601,7 +487,7 @@ const METHODS = {
     assertDistro(distro)
     assertUser(username)
     try {
-      return await resolveDistroHome(distro, username, { wslPath: routeWslPath })
+      return await resolveDistroHome(distro, username, { wslPath: hostSession.wslPath })
     } catch (error) {
       throw routeErrorFor(error, { distro, user: username })
     }
@@ -617,7 +503,7 @@ const METHODS = {
    * @returns {Promise<{ agentPreset: string, base: string }>} the variant to request.
    */
   wslPresetFor: async ({ base } = {}) => {
-    const presets = hostCtx?.get('agentPresets')
+    const presets = hostSession.ctx?.get('agentPresets')
     if (presets === undefined) throw new WslRouteError('host-capability-missing', { feature: 'preset-generation' })
     let resolved
     try {
@@ -669,7 +555,7 @@ const METHODS = {
       ...(username !== undefined ? { username } : {}),
       ...(timeoutMs !== undefined ? { timeoutMs } : {}),
       ...(raw === true ? { raw: true } : {}),
-      wslPath: routeWslPath,
+      wslPath: hostSession.wslPath,
     })
     return { ...result, target }
   },
@@ -679,7 +565,7 @@ const METHODS = {
    * @returns {Promise<object>} the state, plus `deployed` — the path the running host loaded.
    */
   presetStatus: () => Promise.resolve({
-    ...presetState,
+    ...presetRun.state,
     deployed: { modulePath: SELF_MODULE },
   }),
 
@@ -708,8 +594,8 @@ const METHODS = {
     let handle
     let agent
     try {
-      const agents = hostCtx.get('agents')
-      const presets = hostCtx.get('agentPresets')
+      const agents = hostSession.ctx.get('agents')
+      const presets = hostSession.ctx.get('agentPresets')
       if (agents === undefined || presets === undefined) throw new Error('agents / agentPresets 服务不可用')
       // NOT /tmp: the fence refuses a workspace root under /tmp by design (the
       // confinement mounts a private tmpfs over /tmp AFTER binding the workspace,
@@ -721,7 +607,7 @@ const METHODS = {
       // throws before any probe — and then handed its {user, home} result to a
       // function that requires a path string. Nothing reddened: every acceptance
       // path passes cwd. The default is now exercised by verify-world/check-2.
-      const workspaceCwd = cwd ?? (await defaultWorkspaceUnc({ wslPath: routeWslPath })).uncPath
+      const workspaceCwd = cwd ?? (await defaultWorkspaceUnc({ wslPath: hostSession.wslPath })).uncPath
       const sessionId = `wsl-selftest-${Date.now()}`
       handle = await agents.create({ sessionId, meta: { cwd: workspaceCwd, agentPreset: preset } })
       agent = handle?.agent ?? handle
@@ -739,7 +625,7 @@ const METHODS = {
       if (presets.composedPreset(agent.ctx) !== preset) {
         try {
           await presets.select(agent, preset)
-          record('select', { ok: true, composed: presets.composedPreset(agent.ctx) ?? null, bindings: bindingLog.length })
+          record('select', { ok: true, composed: presets.composedPreset(agent.ctx) ?? null, bindings: bindingTape.log.length })
         } catch (error) {
           record('select', { ok: false, error: error instanceof Error ? error.message : String(error) })
         }
@@ -958,7 +844,7 @@ const METHODS = {
 
       // The model calls tools, not providers. Driving the registry is what makes
       // the acceptance cover the layer a session actually uses.
-      const tools = hostCtx.get('tools')
+      const tools = hostSession.ctx.get('tools')
       if (tools !== undefined && agent !== undefined) {
         const controller = new AbortController()
         /**
@@ -969,14 +855,38 @@ const METHODS = {
          */
         const invoke = async (toolName, args) => {
           try {
-            const result = await tools.execute({
-              callId: `wsl-selftest-${toolName}-${Date.now()}`,
-              name: toolName,
-              arguments: args,
+            // Host 0.2.1-rc.3 changed `tools.execute` from ONE call to a BATCH: it now
+            // takes `{ calls: ToolCallBlock[], signal, agent? }` and answers
+            // `{ results, additionalContexts, concluded }`. The previous single-call
+            // object is rejected with `ToolBatchExecutionError` ("Tool batch execution
+            // failed"), which every tool row below reported as a null result.
+            //
+            // `ToolCallBlock.arguments` is the RAW JSON STRING the model produces, not an
+            // object — the block is the wire shape, not a convenience wrapper.
+            const batch = await tools.execute({
+              calls: [{
+                type: 'tool-call',
+                id: `wsl-selftest-${toolName}-${Date.now()}`,
+                name: toolName,
+                arguments: JSON.stringify(args ?? {}),
+              }],
               agent,
               signal: controller.signal,
             })
-            return { ok: true, result: JSON.parse(JSON.stringify(result ?? null)) }
+            const outcome = batch?.results?.[0]
+            if (outcome === undefined) return { ok: false, error: 'the batch returned no result for this call' }
+            // `ToolCallResult` is `{ callId, result: ToolExecutionResult }`, and the
+            // execution result carries `value` (often a serialized JSON string). The
+            // rows below read `.text`, so the text is what this normalises: a string
+            // value is used as-is, anything else is serialized.
+            const execution = outcome.result ?? {}
+            const isError = execution.isError === true || execution.error !== undefined
+            const text = typeof execution.value === 'string'
+              ? execution.value
+              : JSON.stringify(execution.value ?? execution ?? null)
+            return isError
+              ? { ok: false, error: String(execution.error?.message ?? execution.error ?? 'the tool reported an error'), text }
+              : { ok: true, result: JSON.parse(JSON.stringify(execution ?? null)), text }
           } catch (error) {
             return { ok: false, error: error instanceof Error ? error.message : String(error) }
           }
@@ -985,7 +895,7 @@ const METHODS = {
         record('tools.bash', {
           ok: bashTool.ok,
           error: bashTool.error ?? null,
-          text: JSON.stringify(bashTool.result ?? null).slice(0, 400),
+          text: (bashTool.text ?? JSON.stringify(bashTool.result ?? null)).slice(0, 400),
         })
         // Derived from the workspace, not hardcoded: the fixture used to live at
         // /tmp/dsh-wsl-selftest.txt, which only worked while the workspace was
@@ -1003,13 +913,13 @@ const METHODS = {
         record('tools.read', {
           ok: readTool.ok,
           error: readTool.error ?? null,
-          text: JSON.stringify(readTool.result ?? null).slice(0, 400),
+          text: (readTool.text ?? JSON.stringify(readTool.result ?? null)).slice(0, 400),
         })
         const pwshTool = await invoke('pwsh', { command: 'echo host-side', description: 'selftest: this tool must not exist in a WSL session' })
         record('tools.pwsh', {
           ok: pwshTool.ok,
           error: pwshTool.error ?? null,
-          text: JSON.stringify(pwshTool.result ?? null).slice(0, 200),
+          text: (pwshTool.text ?? JSON.stringify(pwshTool.result ?? null)).slice(0, 200),
         })
 
         // The realm's own `grep`/`glob`: the host removes both names from a WSL world
@@ -1085,13 +995,13 @@ const METHODS = {
         record('tool.search.grep', {
           ok: grepSearch.ok && searchFixtureError === null,
           error: grepSearch.error ?? searchFixtureError,
-          text: JSON.stringify(grepSearch.result ?? null).slice(0, 800),
+          text: (grepSearch.text ?? JSON.stringify(grepSearch.result ?? null)).slice(0, 800),
         })
         const globSearch = await invoke('glob', { pattern: 'src/**/*.ts' })
         record('tool.search.glob', {
           ok: globSearch.ok && searchFixtureError === null,
           error: globSearch.error ?? searchFixtureError,
-          text: JSON.stringify(globSearch.result ?? null).slice(0, 800),
+          text: (globSearch.text ?? JSON.stringify(globSearch.result ?? null)).slice(0, 800),
         })
 
         // A tool resolves its policy from the session's logged permission state
@@ -1148,7 +1058,7 @@ const METHODS = {
         record('tools.bashPersist.a', {
           ok: persistA.ok,
           error: persistA.error ?? null,
-          text: JSON.stringify(persistA.result ?? null).slice(0, 400),
+          text: (persistA.text ?? JSON.stringify(persistA.result ?? null)).slice(0, 400),
         })
         const persistB = await invoke('bash', {
           command: `pwd; echo "$DSH_WSL_PERSIST_PROBE"; echo probe > "$HOME/.dsh-wsl-persist-outside"; echo write-exit=$?`,
@@ -1157,7 +1067,7 @@ const METHODS = {
         record('tools.bashPersist.b', {
           ok: persistB.ok,
           error: persistB.error ?? null,
-          text: JSON.stringify(persistB.result ?? null).slice(0, 800),
+          text: (persistB.text ?? JSON.stringify(persistB.result ?? null)).slice(0, 800),
         })
 
         // F8's guard, observed from the realm: once a persistent terminal session exists, a
@@ -1216,7 +1126,7 @@ const METHODS = {
         // through this runner; that pin now covers THIS form structurally as well
         // (`insideCall` + `carrier` in the structural row beside the count table), so dropping
         // the spread reddens it instead of silently reverting to the default `wsl.exe`.
-        const sweepSelect = { wslPath: routeWslPath }
+        const sweepSelect = { wslPath: hostSession.wslPath }
         const sweepShell = (command) => runWslShell({ distro: sweepDistro, linuxCwd: '/', loginShell: false, command, ...sweepSelect })
         const sweepList = async () => String((await sweepShell('ls -1 /tmp/dsh-pty-*.fifo 2>/dev/null; echo END')).stdout ?? '')
           .split('\n').map((line) => line.trim()).filter((line) => line.startsWith('/tmp/dsh-pty-'))
@@ -1260,7 +1170,7 @@ const METHODS = {
           const [distroSecondsText, distroIso] = String(clock.stdout ?? '').trim().split('\n')
           await sweepPlant()
           const planted = await sweepList()
-          const removedFirst = await sweepOrphanFifos({ distro: sweepDistro }, { wslPath: routeWslPath })
+          const removedFirst = await sweepOrphanFifos({ distro: sweepDistro }, { wslPath: hostSession.wslPath })
           const afterFirst = await sweepList()
           // The host-side shift. `Date.now` is the only host clock this process offers the
           // sweep, so patching it is the whole of "the host's reading changed".
@@ -1280,7 +1190,7 @@ const METHODS = {
           let removedShifted
           try {
             Date.now = () => realNow() + HOST_SHIFT_MS
-            removedShifted = await sweepOrphanFifos({ distro: sweepDistro }, { wslPath: routeWslPath })
+            removedShifted = await sweepOrphanFifos({ distro: sweepDistro }, { wslPath: hostSession.wslPath })
           } finally {
             Date.now = realNow
           }
@@ -1375,17 +1285,17 @@ const METHODS = {
    * @returns {Promise<object>} what each step observed.
    */
   workspaceFlow: async ({ distro, linuxPath }) => {
-    const registry = hostCtx.get('workspaceRegistry')
+    const registry = hostSession.ctx.get('workspaceRegistry')
     if (registry === undefined) throw new Error('workspaceRegistry 服务不可用')
     // Default the same way the selftest does — the distribution home, never /tmp:
     // the fence refuses a workspace root under /tmp (confinement mounts a private
     // tmpfs over it after binding the workspace), so a workspace registered there
     // could never be used as a writable root. This method's old default handed the
     // registry exactly such a path.
-    const location = linuxPath ?? (await defaultWorkspaceUnc({ wslPath: routeWslPath })).uncPath
+    const location = linuxPath ?? (await defaultWorkspaceUnc({ wslPath: hostSession.wslPath })).uncPath
     const target = await resolveLocation(location, distro)
-    const listing = await listLinuxDir(target.distro, target.linuxPath, { wslPath: routeWslPath })
-    const facts = await checkLinuxPath(target.distro, target.linuxPath, { wslPath: routeWslPath })
+    const listing = await listLinuxDir(target.distro, target.linuxPath, { wslPath: hostSession.wslPath })
+    const facts = await checkLinuxPath(target.distro, target.linuxPath, { wslPath: hostSession.wslPath })
     const existing = await registry.resolveByPath(target.uncPath)
     const workspace = existing ?? await registry.create(target.uncPath, `wsl-selftest ${target.linuxPath}`)
     const created = existing === undefined
@@ -1408,7 +1318,7 @@ const METHODS = {
    * Report recent preset-binding decisions.
    * @returns {Promise<object>} the decisions, newest last.
    */
-  bindingLog: () => Promise.resolve({ entries: bindingLog }),
+  bindingLog: () => Promise.resolve({ entries: bindingTape.log }),
 
   /**
    * Read the harness's own view of every preset's composition.
@@ -1418,7 +1328,7 @@ const METHODS = {
    * @returns {Promise<object>} the composition inventory.
    */
   presetInventory: async () => {
-    const presets = hostCtx.get('agentPresets')
+    const presets = hostSession.ctx.get('agentPresets')
     if (presets === undefined) throw new Error('agentPresets 服务不可用')
     return { inventory: await presets.compositionInventory() }
   },
@@ -1428,7 +1338,7 @@ const METHODS = {
    * @returns {Promise<object>} the roster.
    */
   presetRoster: async () => {
-    const presets = hostCtx.get('agentPresets')
+    const presets = hostSession.ctx.get('agentPresets')
     if (presets === undefined) throw new Error('agentPresets 服务不可用')
     const roster = await presets.list()
     return { roster: roster.map((entry) => ({ id: entry.id, name: entry.name, broken: entry.broken ?? null, isDefault: entry.isDefault ?? false })) }
@@ -1439,7 +1349,7 @@ const METHODS = {
    * @param {{ distro?: string }} params - optional distribution to pin.
    * @returns {Promise<object>} the new state.
    */
-  regeneratePresets: ({ distro }) => refreshPresets(hostCtx, distro),
+  regeneratePresets: ({ distro }) => refreshPresets(hostSession.ctx, distro),
 
   /**
    * Create (or find) the workspace for a WSL directory.
@@ -1451,9 +1361,9 @@ const METHODS = {
    */
   createWorkspace: async ({ distro, path, title }) => {
     const target = await resolveLocation(path, distro)
-    const facts = await checkLinuxPath(target.distro, target.linuxPath, { wslPath: routeWslPath })
+    const facts = await checkLinuxPath(target.distro, target.linuxPath, { wslPath: hostSession.wslPath })
     if (!facts.isDirectory) throw new Error(`${target.linuxPath} 不是一个存在的目录`)
-    const registry = hostCtx.get('workspaceRegistry')
+    const registry = hostSession.ctx.get('workspaceRegistry')
     if (registry === undefined) throw new Error('workspaceRegistry 服务不可用')
     const existing = await registry.resolveByPath(target.uncPath)
     const workspace = existing ?? await registry.create(target.uncPath, title ?? target.linuxPath)
@@ -1463,7 +1373,7 @@ const METHODS = {
     // degrades to the default spelling instead of failing the creation.
     let presetId = 'wsl-standard'
     try {
-      const presets = hostCtx.get('agentPresets')
+      const presets = hostSession.ctx.get('agentPresets')
       if (presets !== undefined) {
         const resolved = await presets.resolve()
         const candidate = variantIdFor(resolved)
@@ -1492,7 +1402,7 @@ const METHODS = {
   listPresetDirectories: async () => {
     // 0.1.6 read generated directories off disk; the registry is the source of
     // truth now. The method name is kept for the developer surface.
-    const presets = hostCtx?.get('agentPresets')
+    const presets = hostSession.ctx?.get('agentPresets')
     if (presets === undefined) return { root: null, names: [] }
     const roster = await presets.list()
     const names = roster
@@ -1511,7 +1421,7 @@ const METHODS = {
     if (typeof id !== 'string' || !/^[A-Za-z0-9._-]+$/.test(id)) {
       throw new Error(`readPreset: 非法的预设 id ${JSON.stringify(id)}`)
     }
-    const presets = hostCtx?.get('agentPresets')
+    const presets = hostSession.ctx?.get('agentPresets')
     if (presets === undefined) throw new Error('readPreset: agentPresets 服务不可用')
     // 0.1.7: readDocument returns the declaration re-dumped as YAML content.
     const doc = await presets.readDocument(id)
@@ -1519,102 +1429,17 @@ const METHODS = {
   },
 }
 
-/**
- * Read one JSON request body, bounded.
- * @param {import('node:http').IncomingMessage} req - the request to drain.
- * @returns {Promise<{ text: string | null, byteLength: number }>} the body, or null past the ceiling.
- */
-async function readJsonBody(req) {
-  const chunks = []
-  let size = 0
-  for await (const chunk of req) {
-    size += chunk.byteLength
-    if (size > MAX_BODY_BYTES) {
-      // Drain the remainder so the refusal is a readable response, not a socket cut.
-      req.resume()
-      return { text: null, byteLength: size }
-    }
-    chunks.push(chunk)
-  }
-  return { text: Buffer.concat(chunks, size).toString('utf8'), byteLength: size }
-}
-
-/**
- * Answer one request with a JSON envelope and an explicit status.
- * @param {import('node:http').ServerResponse} res - the response to complete.
- * @param {number} status - the HTTP status.
- * @param {{ ok: boolean }} payload - the envelope, success or failure.
- */
-function sendJson(res, status, payload) {
-  const body = JSON.stringify(payload)
-  res.writeHead(status, {
-    'content-type': 'application/json; charset=utf-8',
-    'content-length': Buffer.byteLength(body),
-    'cache-control': 'no-store',
-  })
-  res.end(body)
-}
-
-/**
- * Answer with one admission rejection.
- * @param {import('node:http').ServerResponse} res - the response to complete.
- * @param {import('./http-admission.js').Rejection} rejection - the refusal.
- */
-function sendRejection(res, rejection) {
-  sendJson(res, rejection.status, { ok: false, code: rejection.code, error: rejection.message })
-}
-
-/** Trust surface consumed here; the browser-side connection package owns the full type. */
-function connectionOf(ctx) {
-  return Reflect.get(ctx, 'connection')
-}
-
-/**
- * This installation's development token, minted on first use.
- *
- * The file is owner-only and lives outside the repository. A web page cannot
- * read it, which is what keeps the acceptance surface unreachable from a
- * cross-site request even though the route itself is on loopback.
- * @returns {Promise<string>} the token.
- */
-async function devToken() {
-  const path = join(dshHome(), 'wsl-desktop-dev-token')
-  try {
-    const existing = (await readFile(path, 'utf8')).trim()
-    if (existing.length > 0) return existing
-    // An empty file is unusual — treat it like absent and re-mint below.
-  } catch (error) {
-    // ENOENT = first use. Any other read failure (ACL, AV lock, disk) must
-    // fail loud rather than silently rotate the credential and revoke every
-    // scripted caller.
-    if (error?.code !== 'ENOENT') throw error
-  }
-  const minted = randomBytes(32).toString('hex')
-  await mkdir(dirname(path), { recursive: true })
-  await writeFile(path, `${minted}\n`, { mode: 0o600 })
-  return minted
-}
-
-/**
- * Whether one request may use the acceptance surface.
- * @param {import('node:http').IncomingMessage} req - the request.
- * @param {{ developerTools: boolean }} config - resolved plugin config.
- * @returns {Promise<boolean>} true for a caller presenting this installation's token.
- */
-async function isDeveloperCaller(req, config) {
-  if (config.developerTools !== true) return false
-  return tokenMatches(req.headers[DEV_TOKEN_HEADER], await devToken(), timingSafeEqual)
-}
-
 /**
  * Register the WSL route and generate the WSL presets.
  * @param {import('@deepseek-ai/cordis').Context} ctx - the plugin context.
  * @param {{ routePath: string, developerTools: boolean, wslPath?: string }} config - resolved plugin config.
  */
 export function apply(ctx, config) {
-  hostCtx = ctx
-  routeWslPath = config.wslPath
-  hostReady = false
+  hostSession.ctx = ctx
+  // The declared default, not `undefined`: every route method passes this to
+  // wsl.exe, and an undefined path is not the same as the default one.
+  hostSession.wslPath = config.wslPath ?? 'wsl.exe'
+  hostSession.ready = false
   // Bound concurrent route methods: each discovery call spawns wsl.exe, and a
   // misbehaving page could fan out without limit. Named because a bare "8" here
   // was once mis-read as a wsl.exe SPAWN cap — it is not: one route method may
@@ -1744,10 +1569,10 @@ export function apply(ctx, config) {
       // The probe is allowed to run even after a failed materialization: the result
       // then says which capability is missing, instead of leaving the browser on
       // "pending" forever.
-      hostReady = true
+      hostSession.ready = true
       // One startup line, as the spec asks: the post-restart gate and a bug report
       // both need the capability state without opening the dialog.
-      void probeHost(hostCtx).then((status) => {
+      void probeHost(hostSession.ctx).then((status) => {
         ctx.logger?.info?.(`wsl-desktop: capabilities ${JSON.stringify(status)}`)
       }, () => {})
     })
@@ -1758,7 +1583,7 @@ export function apply(ctx, config) {
   // This listener is the LAST RESORT for a WSL-workspace session created
   // without a preset (some other entry point): it tries a post-hoc select,
   // which is refused for any session that has already taken a turn, and both
-  // outcomes land in `bindingLog` as an anomaly signal.
+  // outcomes land in `bindingTape.log` as an anomaly signal.
   //
   // ONE listener, not two. `agent/created` is a scoped event, but a listener
   // registered without a scope is admitted globally, so registering both paths
@@ -1776,8 +1601,7 @@ export function apply(ctx, config) {
  * @param {object} entry - the decision to record.
  */
 function recordBinding(entry) {
-  bindingLog.push(entry)
-  if (bindingLog.length > BINDING_LOG_LIMIT) bindingLog.splice(0, bindingLog.length - BINDING_LOG_LIMIT)
+  bindingTape.record(entry)
 }
 
 /**