dsh-wsl-desktop 0.7.2 → 0.7.4

package/lib/wsl/confinement.js

@@ -776,6 +776,22 @@ export function buildConfinedCommand({ command, linuxCwd, mode, workspaceLinuxRo
   }
   const script = buildNamespaceScript({ command, linuxCwd, mode, workspaceLinuxRoot, identity, noNewPrivs })
   const flags = ['--mount', '--propagation', 'private']
-  if (isolateProcesses) flags.push('--pid', '--fork')
-  return `sudo -n unshare ${flags.join(' ')} bash -c ${shellQuote(script)}`
+  // A PID namespace re-parents the tree but the inherited procfs still lists the PARENT's
+  // pids, so /proc/<outer-pid>/root names the outer mount namespace — where nothing was
+  // remounted read-only. `--mount-proc` is what closes that, and it is one control with
+  // the pid namespace, not an option beside it.
+  if (isolateProcesses) flags.push('--pid', '--fork', '--mount-proc')
+  // The helper pins PATH and runs its fence under `bash -p` (see its own comments for the
+  // measurements). This runner emits the same fence body, so it must carry the same
+  // invariants: without the pin, a caller able to pass a sudo command-line assignment
+  // shadows mount/findmnt/mountpoint and the postconditions pass while the mounts stay
+  // writable — a fence that lies. `-p` skips BASH_ENV and the function import for the
+  // fence body, and the three `-u` removals close the interop door (a Windows program
+  // launched from here can start an unfenced `wsl.exe ... bash`, where NO_NEW_PRIVS does
+  // not apply and the retained sudo grant re-escalates normally).
+  const hardened = [
+    'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; export PATH;',
+    script,
+  ].join('\n')
+  return `sudo -n unshare ${flags.join(' ')} env -u BASH_ENV -u WSL_INTEROP -u WSLENV -u WSL_DISTRO_NAME bash -p -c ${shellQuote(hardened)}`
 }

package/lib/wsl/distros.js

@@ -0,0 +1,190 @@
+/**
+ * Distribution discovery: which distributions exist, which one is the default, and
+ * which WSL version each one runs.
+ *
+ * Split out of `world.js` (C3). Everything here reaches `wsl.exe` or the Lxss
+ * registry and answers a question ABOUT a distribution; `world.js` keeps what
+ * happens INSIDE one. The two import the decoder and the child environment from
+ * `proc.js`, so neither imports the other.
+ *
+ * The re-exports at the bottom keep `world.js`'s public surface unchanged; that is
+ * a compatibility shim, not a second home for the code.
+ * @module dsh-wsl-desktop/wsl/distros
+ */
+
+import { execFileSync } from 'node:child_process'
+import { WSL_CHILD_ENV, decodeWslOutput, execFileAsync } from './proc.js'
+
+/** Short ceiling for the registry and `wsl.exe` discovery calls. */
+const DISCOVERY_TIMEOUT_MS = 10_000
+
+/** Windows registry key holding the WSL distribution registrations. */
+const LXSS_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Lxss'
+
+/**
+ * List the installed WSL distributions.
+ *
+ * The configured path is spawned here too: this call is a probe like any other,
+ * and a deployment that set the path because `wsl.exe` is not on PATH would get
+ * an empty discovery while its real spawns worked.
+ * @param {{ wslPath?: string }} [options] - the configured `wsl.exe` path.
+ * @returns {Promise<string[]>} distribution names in `wsl.exe` order.
+ */
+export async function listDistros({ wslPath = 'wsl.exe' } = {}) {
+  let stdout
+  try {
+    ({ stdout } = await execFileAsync(wslPath, ['-l', '-q'], {
+      encoding: 'buffer',
+      timeout: DISCOVERY_TIMEOUT_MS,
+      // The discovery call is a wsl.exe spawn like any other: without this its
+      // output is UTF-16LE and only the fallback probe reads it.
+      env: { ...process.env, ...WSL_CHILD_ENV },
+    }))
+  } catch (error) {
+    // The spawn code is the only thing that distinguishes "wsl.exe is not
+    // installed" (ENOENT) from a plugin fault; dropping it would turn the most
+    // common first-run state into `internal`. The message stays host-side.
+    const failure = new Error(`无法列出 WSL 发行版：${error instanceof Error ? error.message : String(error)}`, { cause: error })
+    if (typeof error?.code === 'string') failure.code = error.code
+    throw failure
+  }
+  return decodeWslOutput(stdout)
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\0/g, '').trim())
+    .filter((line) => line.length > 0)
+}
+
+/**
+ * The WSL major version of one distribution, from `wsl.exe -l -v`.
+ *
+ * WSL1 is explicitly unsupported (its syscall translation layer has no mount
+ * namespace), but until now nothing in the product asked the host which version a
+ * distribution runs. The output is a table:
+ *
+ *   `  NAME      STATE           VERSION`
+ *   `* debian    Running         2`
+ *
+ * The active marker is optional; the version is the last column. A table that
+ * cannot be parsed answers `null` — an unmeasured fact is not a failure.
+ * @param {string} distro - the distribution name.
+ * @param {{ wslPath?: string }} [options] - the configured `wsl.exe` path.
+ * @returns {Promise<'1'|'2'|null>} the major version, or null when unreadable.
+ */
+export async function wslMajorVersion(distro, { wslPath = 'wsl.exe' } = {}) {
+  let stdout
+  try {
+    ({ stdout } = await execFileAsync(wslPath, ['-l', '-v'], {
+      encoding: 'buffer',
+      timeout: DISCOVERY_TIMEOUT_MS,
+      env: { ...process.env, ...WSL_CHILD_ENV },
+    }))
+  } catch {
+    return null
+  }
+  return parseWslVersionTable(decodeWslOutput(stdout), distro)
+}
+
+/**
+ * Pick one distribution's major version out of a `wsl.exe -l -v` table.
+ *
+ * Kept pure and exported so the table's spacing variants are testable without a
+ * real WSL host. The active marker (`*`) is optional; the last column is VERSION.
+ * @param {unknown} text - the decoded table.
+ * @param {string} distro - the distribution name.
+ * @returns {'1'|'2'|null} the major version, or null when the row is absent.
+ */
+export function parseWslVersionTable(text, distro) {
+  const lines = String(text ?? '').split(/\r?\n/)
+  for (const raw of lines) {
+    const line = raw.replace(/\0/g, '').trim()
+    if (line === '') continue
+    const cells = line.replace(/^\*\s*/, '').split(/\s{2,}|\t/).filter((cell) => cell !== '')
+    if (cells.length < 2) continue
+    if (cells[0] !== distro) continue
+    const version = cells[cells.length - 1]
+    return version === '1' || version === '2' ? version : null
+  }
+  return null
+}
+
+/**
+ * The Lxss registry values and the two REG_SZ lines the default-distribution read needs.
+ *
+ * The patterns live HERE, once, because the async and the sync reader each carried their
+ * own copy: a registry-format change had two homes, and only one of them was exercised by
+ * whichever caller the operator happened to hit.
+ */
+const DEFAULT_DISTRIBUTION_VALUE = 'DefaultDistribution'
+const DISTRIBUTION_NAME_VALUE = 'DistributionName'
+const GUID_PATTERN = /DefaultDistribution\s+REG_SZ\s+(\{[0-9a-fA-F-]+\})/iu
+const NAME_PATTERN = /DistributionName\s+REG_SZ\s+(.+)/iu
+
+/**
+ * The distribution a `DistributionName` line names.
+ * @param {unknown} output - the registry query's stdout.
+ * @returns {string | undefined} the name, or undefined when the line names none.
+ */
+function distroFromRegistryOutput(output) {
+  const distro = NAME_PATTERN.exec(String(output))?.[1]?.trim()
+  return distro === undefined || distro === '' ? undefined : distro
+}
+
+/**
+ * The Lxss subkey a `DefaultDistribution` line names.
+ * @param {unknown} output - the registry query's stdout.
+ * @returns {string | undefined} the GUID, or undefined when the line names none.
+ */
+function guidFromRegistryOutput(output) {
+  return GUID_PATTERN.exec(String(output))?.[1]
+}
+
+/**
+ * Read the user's default distribution from the Lxss registry. Non-fatal:
+ * `undefined` when the value is absent or unreadable.
+ * @returns {Promise<string | undefined>} the default distribution name.
+ */
+export async function defaultDistro() {
+  try {
+    const value = await execFileAsync('reg.exe', ['query', LXSS_KEY, '/v', DEFAULT_DISTRIBUTION_VALUE], {
+      timeout: DISCOVERY_TIMEOUT_MS,
+    })
+    const guid = guidFromRegistryOutput(value.stdout)
+    if (guid === undefined) return undefined
+    const name = await execFileAsync('reg.exe', ['query', `${LXSS_KEY}\\${guid}`, '/v', DISTRIBUTION_NAME_VALUE], {
+      timeout: DISCOVERY_TIMEOUT_MS,
+    })
+    return distroFromRegistryOutput(name.stdout)
+  } catch {
+    // A missing or unreadable registry value leaves the caller its own fallback.
+    return undefined
+  }
+}
+
+/**
+ * Synchronous default-distribution read for plan steps that cannot await.
+ *
+ * Cached after the first read: a shell plan is built synchronously, and the
+ * registry does not change while the process runs.
+ * @returns {string | undefined} the default distribution name.
+ */
+let syncDefaultResolved = false
+let syncDefault
+export function defaultDistroSync() {
+  if (syncDefaultResolved) return syncDefault
+  syncDefaultResolved = true
+  try {
+    const value = execFileSync('reg.exe', ['query', LXSS_KEY, '/v', DEFAULT_DISTRIBUTION_VALUE], {
+      timeout: DISCOVERY_TIMEOUT_MS,
+    })
+    const guid = guidFromRegistryOutput(value)
+    if (guid === undefined) return undefined
+    const name = execFileSync('reg.exe', ['query', `${LXSS_KEY}\\${guid}`, '/v', DISTRIBUTION_NAME_VALUE], {
+      timeout: DISCOVERY_TIMEOUT_MS,
+    })
+    syncDefault = distroFromRegistryOutput(name)
+  } catch {
+    // An unreadable registry leaves the caller its own fail-loud path.
+    syncDefault = undefined
+  }
+  return syncDefault
+}

package/lib/wsl/dsh-wsl-confine.sh

@@ -194,8 +194,24 @@ command -v findmnt >/dev/null 2>&1 || { echo 'dsh-wsl-sandbox: setup failed: fin
 # form is not portable and the refusal above is what the fence relies on.)
 KEEP_ENTRIES=(/tmp /dev /dev/pts /dev/mqueue /proc /sys)
 [[ -z "$workspace" ]] || KEEP_ENTRIES+=("$workspace")
+
+# Kernel virtual filesystems are exempt as SUBTREES, not as single mount points. A fresh
+# `--mount-proc` brings /proc's own nested mounts with it (measured: /proc/sys/fs/binfmt_misc
+# is a separate mount record), and a nested kernel mount cannot be made read-only — it is
+# not backing storage. Exact-entry matching left those children unexempt, so the
+# postcondition found the first one writable and the fence refused every command.
+#
+# The subtree list is deliberately NARROWER than KEEP_ENTRIES. /dev and /tmp stay exact so
+# their writable children keep being swept: /dev/shm is shared memory that must end up
+# READONLY (the post-condition asserts it), and a workspace under /tmp is already refused
+# outright. The subtree rule applies only to the two pseudo-filesystems whose children are
+# kernel state by construction, and the workspace is never one of them.
+KERNEL_SUBTREE=(/proc /sys)
 EXEMPT_PATTERN=$(printf '%s\n' "${KEEP_ENTRIES[@]}" | sed 's/[][\\^$.*+?(){}|]/\\&/g' | tr '\n' '|')
 EXEMPT_PATTERN="${EXEMPT_PATTERN%|}"
+for kernel in "${KERNEL_SUBTREE[@]}"; do
+  EXEMPT_PATTERN="${EXEMPT_PATTERN}|$(printf '%s' "$kernel" | sed 's/[][\\^$.*+?(){}|]/\\&/g')/.*"
+done
 
 # The fence script is built HERE from the validated parameters — the caller
 # never supplies script text. It is identical in effect to the in-process
@@ -228,12 +244,28 @@ exec setpriv --no-new-privs --reuid="$DROP_UID" --regid="$DROP_GID" --init-group
 PID_FLAG=''
 [[ "$pidns" = 1 ]] && PID_FLAG='--pid --fork'
 
+# A PID namespace alone does NOT hide the outer processes: it re-parents this tree, but
+# the procfs it inherits still lists the PARENT's pids, so /proc/<outer-pid>/root keeps
+# naming the outer mount namespace — where / and /mnt/c were never remounted read-only,
+# because that remount is private to this fence. `--mount-proc` mounts a FRESH procfs over
+# /proc, so a magic link can only ever name a process inside this namespace. The two
+# halves are one control, which is why the flag is tied to the pid namespace and not
+# offered separately: a fresh procfs without a pid namespace would still list outer pids.
+PROC_FLAG=''
+[[ "$pidns" = 1 ]] && PROC_FLAG='--mount-proc'
+
+# WSL interop is a door OUT of the fence, and NO_NEW_PRIVS does not survive it: a confined
+# command can launch a WINDOWS program, and that program can start a fresh
+# `wsl.exe -d <distro> -e bash` — a new Linux process in the INITIAL mount namespace
+# carrying no NNP, free to use the passwordless sudo grant this runner itself requires.
+# The door is opened by environment variables, so they are removed on the one invocation
+# every root-phase descendant hangs off. /mnt/c stays mounted read-only under the fence
+# and interop was the way around that write fence, not a way through it.
+#
 # -p stops OUR bash from processing BASH_ENV, but it does NOT remove the variable from
 # the environment, and every descendant inherits it. The drop-side `bash -lc
 # "$DROP_COMMAND"` is NOT privileged and does process it (measured: it sourced the
-# caller's file as the session user, inside the fence). Drop it HERE, on the one
-# invocation every root-phase descendant hangs off, so no descendant can be made to
-# source a caller's file.
+# caller's file as the session user, inside the fence). Drop it HERE.
 #
 # -p on THIS file's bash also stops the import of functions from the environment
 # into THIS shell only. The fence body is a separate `bash -c`, so without -p there a
@@ -243,7 +275,8 @@ PID_FLAG=''
 # therefore launched with -p as well: the same privileged-mode rule that skips
 # BASH_ENV skips the function import, so a coordinated override becomes a no-op
 # instead of a fence that lies.
-exec unshare --mount --propagation private $PID_FLAG env -u BASH_ENV \
+exec unshare --mount --propagation private $PID_FLAG $PROC_FLAG \
+  env -u BASH_ENV -u WSL_INTEROP -u WSLENV -u WSL_DISTRO_NAME \
   DROP_UID="$uid" DROP_GID="$gid" DROP_HOME="$home" DROP_USER="${SUDO_USER:-root}" \
   DROP_CWD="$cwd" DROP_WORKSPACE="$workspace" DROP_COMMAND="${ARGS[*]}" \
   DROP_EXEMPT="$EXEMPT_PATTERN" \

package/lib/wsl/fs.js

@@ -162,7 +162,39 @@ export class WslFileSystem extends LocalFileSystem {
       // the share refuses that one step transiently (see ./publish.js for the
       // measurement). The publication is waited out rather than reported as a
       // failure the caller cannot tell apart from a real one.
+      //
+      // The containment re-test lives HERE, next to the syscall, because that is the only
+      // place it can see a component swapped after `checkedTarget`: the fence's own
+      // documentation records that a rename through such a component lands the file AT THE
+      // LINK'S TARGET, so the window is a content escape, not just an out-of-bounds
+      // directory. Refusing here reports the same structured denial the entry check uses.
       replaceFile: async (replaced, replacement) => {
+        // Resolve the policy HERE rather than carrying a snapshot. The primitive's signature
+        // is `(replaced: string, replacement: string)`, so no per-call context can reach it,
+        // and an instance field would be shared by every concurrent write — task B's roots
+        // would judge task A's publication. Resolving at the syscall is also the sounder
+        // semantic: the re-test answers "is this path inside a writable root RIGHT NOW",
+        // and a policy that changed since the entry check should narrow the write, not be
+        // ignored in favour of a stale grant.
+        const policy = this.ctx.sandboxPolicy.resolve()
+        if (policy.mode !== 'danger-full-access') {
+          // `replaced` is a HOST spelling (a UNC or a drive path), so its parent is a win32
+          // concern, not a POSIX one.
+          const parent = await this.resolve(win32.dirname(replaced))
+          let contained = false
+          for (const root of this.writableHostRoots(policy)) {
+            if (await isUnderHost(parent.targetKey, root)) {
+              contained = true
+              break
+            }
+          }
+          if (!contained) {
+            throw new FsError(
+              `cannot write "${replaced}": the destination left the writable roots between the check and the publication`,
+              'FS_SANDBOX_DENIED',
+            )
+          }
+        }
         await publishReplace(replaced, replacement)
       },
       // The share exposes no settable DACL, and staging is already private.

package/lib/wsl/preset.js

@@ -57,6 +57,13 @@ export const WORLD_MODULE_NAMES = new Set([
   '@deepseek-ai/dsh-tool-pwsh-persistent',
   '@deepseek-ai/dsh-terminal-bash',
   '@deepseek-ai/dsh-terminal',
+  // Added when harness 0.2.1-rc.3 shipped it (measured: a `wsl-ptc` preset row
+  // survived unclassified). It is a HOST-execution row: it injects `ptcRuntime` and
+  // runs programs through `runtime.run(...)`, and this plugin provides no WSL
+  // `ptcRuntime` implementation — the host's own (`dsh-ptc-runtime-node`) would run
+  // the program on WINDOWS inside a WSL session. That is the leak this set exists to
+  // close, so it is removed rather than kept.
+  '@deepseek-ai/dsh-tool-executor-ptc',
 ])
 
 /**

package/lib/wsl/proc.js

@@ -0,0 +1,182 @@
+/**
+ * Process-level helpers shared by the two halves of the WSL seam.
+ *
+ * `world.js` is split into "how a distribution is discovered" and "how a command
+ * runs in it", but both halves decode `wsl.exe` output and validate distro names,
+ * and the suites import the decoder from `world.js` directly. Putting those two
+ * in either half would make the halves import each other; they live here instead,
+ * and `world.js` re-exports the decoder so its public surface does not change.
+ *
+ * Extracted verbatim from `lib/wsl/world.js` (C3).
+ * @module dsh-wsl-desktop/wsl/proc
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { DISTRO_NAME } from './paths.js'
+
+/** Promise-returning `execFile`, used by every discovery call. */
+export const execFileAsync = promisify(execFile)
+
+/**
+ * Refuse option values that cannot be safe single argv tokens for wsl.exe
+ * (-d/-u), independent of wsl.exe's external tokenization rules.
+ * @param {string} distro - the distribution name about to be spawned with.
+ */
+export function assertDistroName(distro) {
+  if (typeof distro !== 'string' || !DISTRO_NAME.test(distro)) {
+    throw new Error(`wsl: 非法的发行版名 ${JSON.stringify(distro ?? null)}`)
+  }
+}
+
+/**
+ * Decode `wsl.exe` output.
+ *
+ * Every `wsl.exe` this plugin spawns is asked for UTF-8 (`WSL_UTF8`, see
+ * {@link ENV_OVERRIDES}), so this is normally a plain UTF-8 decode — including the
+ * diagnostics wsl.exe prints for its OWN failures, which are UTF-16LE without that
+ * variable and were the whole reason this decoder used to guess between encodings.
+ *
+ * The fallback covers two things a WSL build that ignores the variable can send:
+ * an explicit UTF-16LE BOM, and UTF-16LE whose code units are below U+0100 (their
+ * high bytes are NUL — Latin-1 counts, not only ASCII).
+ *
+ * NUL-framed DATA is the awkward case, and a RATIO alone cannot settle it:
+ * measured, `find . -print0` scores 0.500, the real Chinese diagnostic 0.636, and
+ * `ls --zero` with single-character names reaches 1.000 — where the bytes ARE
+ * `Buffer.from('abc', 'utf16le')`, byte for byte. Hence the layering above: a
+ * partial interleave must also fail UTF-8 validity, which drops the framing
+ * payloads (valid UTF-8) and keeps the diagnostic (invalid); an all-odd
+ * interleave is honoured regardless, because that is the shape `listDistros`
+ * depends on when a build ignores the switch.
+ *
+ * The irreducible residue is exactly that byte-identical pair: no test can
+ * separate two readings of the same bytes. A consumer whose protocol frames with
+ * NUL must therefore opt out with `raw` — `listLinuxDir` does, and `execInWsl`,
+ * the only consumer of ARBITRARY command output, takes `raw` for the same reason.
+ *
+ * Three attempts at a smarter heuristic (interleave ratios, replacement-character
+ * densities, UTF-8 validity) each traded one failure class for another: every
+ * listing empty, then a >1 MiB CJK stream mojibake, then valid buffers flipped.
+ * Guessing between encodings was the wrong shape; asking for UTF-8 removed the
+ * need to guess, and this fallback covers the builds that predate the variable.
+ * @param {Buffer} buffer - raw captured stream.
+ * @returns {string} the decoded text.
+ */
+export function decodeWslOutput(buffer) {
+  return looksUtf16le(buffer) ? buffer.toString('utf16le') : buffer.toString('utf8')
+}
+
+/**
+ * Whether a buffer is UTF-16LE whose code units are mostly below U+0100 — the
+ * fallback shape.
+ *
+ * The class counted is NOT "ASCII": the pick is `oddNuls * 2 >= pairs`, i.e. at
+ * least half the CODE UNITS must have a NUL high byte, and EVERY code unit below
+ * U+0100 encodes with one — Latin-1 included. Measured: a UTF-16LE buffer of
+ * U+00E9 and U+00FF (e-acute, y-diaeresis) is counted exactly like ASCII and
+ * decodes as UTF-16LE. For a pure-ASCII text the two readings coincide, which is
+ * why this used to be described as an "ASCII share"; for a Latin-1 text they do
+ * not, and the rate below is the binomial tail of the share of code units BELOW
+ * U+0100 — 100% for a text entirely below it, about 60% at half, about 8% at 35%
+ * (two independent generators measured 62.2%/52.8% and 8.0%/6.8% on those same
+ * anchors, which is the point: quote the mechanism, not a rate). The real wsl.exe
+ * diagnostics captured here happen to be majority-ASCII (0.636-0.662) and are
+ * caught; a message that is mostly CJK is not, and no threshold fixes that
+ * without also admitting NUL-framed data. That is why the switch is requested at
+ * the source instead.
+ *
+ * The test is the INTERLEAVED NUL pattern, not "contains a NUL": a Linux-side
+ * producer may emit NUL bytes as DATA (`printf 'a\\0b'`), and a bare NUL test
+ * decoded that as UTF-16LE and silently dropped the byte after it. Three code
+ * units minimum, or the pattern is a coincidence — `'a\\0b'` is one pair and
+ * satisfies any ratio.
+ *
+ * This deliberately does NOT try to recognise UTF-16LE whose code units are
+ * ABOVE U+00FF (there the high byte is not NUL, so nothing distinguishes it from
+ * text) — with ONE exception, the explicit BOM below, which is a declaration
+ * rather than a statistic. Everything else is handled at the SOURCE instead: every spawn asks
+ * wsl.exe for UTF-8 (WSL_UTF8), so a Chinese-locale diagnostic arrives as UTF-8
+ * rather than as UTF-16LE whose only distinguishing feature is a
+ * replacement-character count. Three heuristics were written for that case and
+ * each traded one failure class for another.
+ * @param {Buffer} buffer - raw captured stream.
+ * @returns {boolean} true when the buffer looks like ASCII-heavy UTF-16LE.
+ */
+export function looksUtf16le(buffer) {
+  // An explicit BOM is a DECLARATION, not a guess: a file saved by a Windows
+  // editor starts FF FE, and decoding it as UTF-8 is mojibake for certain. It is
+  // checked BEFORE the parity guard on purpose, so a truncated BOM'd buffer
+  // (FF FE 41) is still read as UTF-16LE and loses its trailing byte, rather than
+  // being read as UTF-8 — the declaration wins over the shape.
+  if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) return true
+  // A UTF-16LE stream is always an EVEN number of bytes, so an odd-length buffer
+  // cannot be one — and `toString('utf16le')` would silently DROP the trailing byte
+  // (measured: `printf 'a\\0b\\0c\\0d'` is 7 bytes and decoded to "abc").
+  if (buffer.length % 2 !== 0) return false
+  const pairs = Math.floor(buffer.length / 2)
+  if (pairs < 3) return false
+  let oddNuls = 0
+  let evenNuls = 0
+  for (let index = 0; index < pairs * 2; index += 2) {
+    if (buffer[index] === 0) evenNuls += 1
+    if (buffer[index + 1] === 0) oddNuls += 1
+  }
+  // The predicate is EXACTLY `oddNuls > evenNuls && oddNuls * 2 >= pairs`. An
+  // earlier version of this comment called it "a majority of the odd positions and
+  // nothing else", which was wrong twice: the first conjunct is real — a buffer
+  // whose code units are mostly U+xx00 has as many even NULs as odd ones and is
+  // rejected, e.g. Buffer.from([0,0,0,0,0,1,0,2,0x61,0,0x62,0]) — and where
+  // evenNuls is 0 it fires at EXACTLY one half, not a majority.
+  //
+  // The populations OVERLAP, so this is a heuristic and not a proof — measured:
+  //   real UTF-16LE diagnostics              0.636 - 0.662   -> fires, correctly
+  //   real 'wsl.exe -l -q' UTF-16LE          1.000           -> fires (listDistros needs it)
+  //   real 'find . -print0', long names      0.026 - 0.415   -> does not fire, correctly
+  //   one-char entries './a\0./b\0./c\0'   0.500 EXACTLY   -> FIRES, WRONGLY
+  //   'ls --zero', one-char names            1.000           -> fires; byte-identical
+  //                                                             to UTF-16LE, inherent
+  // (A real capture scored 0.529 on that one-char shape only because UTF-16LE text
+  // was mixed into the stream; the pure listing is 0.5000 and still fires.)
+  // That shape is the one that breaks: it puts a NUL on most odd byte positions, and
+  // no threshold separates it from a diagnostic at 0.636 without dropping the
+  // diagnostics that score below it. Three refinements
+  // were tried and ALL were falsified, so none is kept:
+  //   - a 0.75 threshold excluded the real diagnostics themselves;
+  //   - "a partial interleave must also fail UTF-8 validity" excluded UTF-16LE whose
+  //     bytes ARE valid UTF-8 (Buffer.from('abc不','utf16le')) while still admitting
+  //     NUL-framed bytes that are not (printf 'a\\0b\\0c\\xff');
+  //   - a 0.6 threshold fits exactly the sample above — which is the sample it was
+  //     measured on, while a diagnostic that is mostly non-ASCII scores lower.
+  // A ratio cannot prove an encoding. The OPT-OUTS can, and they are the answer:
+  // listLinuxDir and execInWsl(raw:true) never reach this test at all.
+  return oddNuls > evenNuls && oddNuls * 2 >= pairs
+}
+
+/**
+ * The environment every `wsl.exe` child must be started with, wherever it is
+ * spawned from.
+ *
+ * `WSL_UTF8` is load-bearing, not cosmetic: wsl.exe reads it from its OWN
+ * environment to decide the encoding of its diagnostics. Without it a missing
+ * distribution emits 258 bytes of UTF-16LE, which is what forced the decoder to
+ * guess between encodings — and every guess traded one failure class for another.
+ * With it the same message arrives as 223 bytes of UTF-8.
+ *
+ * It lives here, as one exported constant, because there are four spawn sites
+ * (the probe path, the shell executor, the subprocess provider's spawn and its
+ * terminal allocation) and a site that forgets it silently gets unreadable
+ * messages again. Linux-side output is unaffected; only wsl.exe's own text changes.
+ */
+export const WSL_CHILD_ENV = { WSL_UTF8: '1' }
+
+/**
+ * Environment overrides that keep command output model-readable.
+ *
+ * ONE owner, shared with the shell executor (which spreads it into every
+ * command it runs) — an override added to one copy and not the other used to be
+ * a silent divergence two modules could not see. Frozen so a shared object stays
+ * shared on purpose: an accidental write now throws instead of leaking into the
+ * other consumer's environment.
+ */
+export const ENV_OVERRIDES = Object.freeze({ ...WSL_CHILD_ENV, NO_COLOR: '1', TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat' })

package/lib/wsl/sandbox.js

@@ -51,10 +51,17 @@ export const Config = z.object({
   /**
    * Add a PID namespace to the fence. OFF for this provider's consumers on purpose: the
    * argv it wraps is an INTERACTIVE shell on a PTY, and a PID namespace re-parents that
-   * shell to PID 1 with a process group the PTY's own foreground queries
-   * (`terminal-bridge.py`'s `tcgetpgrp`) can no longer address — the reason the shipped
-   * helper carries `--no-pidns` at all. The shell executor's one-shot commands keep the
-   * namespace (its own default); this is the terminal path only.
+   * shell to PID 1, which the PTY path cannot live with. Re-measured while closing the
+   * /proc escape: `tcgetpgrp` alone DOES still resolve under `--pid --fork --mount-proc`
+   * (TPGID names the shell's own pid), but driving the real `terminal-bridge.py` through
+   * the same namespace HANGS — it never completes its start, so the terminal is dead.
+   * The one-shot shell executor keeps the namespace (its own default); this is the
+   * terminal path only.
+   *
+   * The /proc consequence is accepted HERE and closed on the one-shot path: with the
+   * namespace off, a fresh procfs would still list the outer pids, so this arm carries no
+   * `--mount-proc` either — mounting one would buy nothing. What the terminal path cannot
+   * have, `shell.js` and the direct runner do have.
    */
   isolateProcesses: z.boolean().default(false),
 })

package/lib/wsl/shell.js

@@ -41,7 +41,8 @@ import {
   workspaceRootInLinux,
 } from './confinement.js'
 import { parseWslUnc, shellQuote, windowsToMntPath } from './paths.js'
-import { ENV_OVERRIDES, planWsl, runWslShell, withWslEnvFlags } from './world.js'
+import { planWsl, runWslShell, withWslEnvFlags } from './world.js'
+import { ENV_OVERRIDES } from './proc.js'
 
 /** Default foreground timeout in milliseconds. */
 const DEFAULT_TIMEOUT_MS = 120_000

package/lib/wsl/subprocess.js

@@ -30,7 +30,8 @@ import z from '@deepseek-ai/schemastery'
 import { requireLocalSubprocess } from './host-refs.js'
 import { shellQuote } from './paths.js'
 import { describeArgv, spawnWslTerminal, termLog } from './pty.js'
-import { LoginShellUnresolvedError, WSL_CHILD_ENV, buildWslExecArgv, planWsl, resolveLoginShell, runWslShell, withWslEnvFlags } from './world.js'
+import { LoginShellUnresolvedError, buildWslExecArgv, planWsl, resolveLoginShell, runWslShell, withWslEnvFlags } from './world.js'
+import { WSL_CHILD_ENV } from './proc.js'
 
 /**
  * The executable lookup's ceiling, on the documented probe policy.