dsh-plugin-wsl-env 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -16,6 +16,462 @@ were part of the record.
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-18
+
+The shared read agent is the native binary (A7): unconfined reads now use the
+packaged static-musl agent with the shell as the fallback, cutting 16
+concurrent reads from 342-614 ms to 2.4-8.2 ms. The A6 FS measurement and
+metrics ship with it.
+
+### Added
+
+- **The shared read agent is native (A7).** `WslAgent` gained an async
+  `prepare()` hook; `sharedAgent` uses it to select the packaged native binary
+  through `agentBackend` (`auto`/`native`), with the shell as the fallback
+  (`shell`, a failed preparation, or a native HELLO/runtime failure; the reads
+  never fail closed). The A6 probe measures 16 concurrent shared reads at
+  2.4-8.2 ms, down from 342-614 ms on the shell. The native shared agent also
+  serves the picker, the subprocess activity probes and the non-session
+  command path, so those inherit EXEC concurrency.
+
+- **`WslAgent.metrics()`.** Per-kind queue wait (sent -> ACK), execution time
+  (ACK -> settle), in-flight peak, rejected and cancelled counters; the
+  47-check lifecycle suite covers the counters and the reset.
+
+- **`test/probe/fs-queue.mjs`.** A live measurement of both FS agents. The A6
+  run showed the shared shell reads were the batch bottleneck (16 concurrent
+  `stat`/`read`/`list` at 342-614 ms, queue up to 583 ms) while native FS ops
+  execute in 0.2-0.3 ms; the A7 run measures the native shared reads at
+  2.4-8.2 ms. v6's lock removal only takes 16 native writes from 7.7 ms to
+  ~5 ms, so it stays deferred.
+
+### Changed
+
+- **The plan after the A6 measurement: A7 (native shared reads) landed, v6
+  deferred.** [`docs/ROADMAP.md`](docs/ROADMAP.md) records the done, next and
+  deferred steps; ADR 0002, LIMITATIONS and the READMEs describe the native
+  shared reads and the v6 deferral.
+
+- `test/probe/fs-queue.mjs` and the README/LIMITATIONS/ROADMAP describe the
+  native shared reads; `test/agent-shared.test.mjs` covers the shell selection.
+
+## [0.10.0] - 2026-10-18
+
+The native in-distro agent is the default session-runtime backend: `agentBackend: auto`
+selects the packaged static-musl binary for the distro's architecture, the shipped
+shell agent stays as the fallback, and `native`/`shell` keep the strict and forced
+modes. The peer line moves to DeepSeek Harness `0.2.1-rc.2`, which is the desktop
+app's own version line. No module under `src/` changed, and that is the
+finding, not an omission: every peer artifact this plugin subclasses or
+replicates is byte-identical to the one shipped for `0.2.0-rc.2`, except one
+added field in the `dsh-api-workspace-files` class that `WorkspaceFilesWsl`
+extends (and that package's regenerated typert artifacts), so the seams the
+code is built on did not move. What did move is the shipped composition — the
+standard agent preset — and the plugin's embedded `preset-wsl` is regenerated
+from it.
+
+### Added
+
+- **The watcher uses inotify when it can.** With `inotifywait` installed and an
+  unbounded directory target, the in-distro watcher now uses recursive inotify
+  watches and coalesces events to one callback per 0.5s instead of polling
+  `find`. A file target, a positive `watchMaxDepth`, or a missing
+  `inotify-tools` keeps the polling fallback, so the backend is optional. The
+  polling mtime-old blind spot does not apply to the inotify path.
+
+- **`sessionSandbox` runs one session's commands in one scope.** With the key
+  on, the shell executor acquires the runtime for `(distro, workspace,
+  policy)` on the first command, reuses it for the session, runs the command
+  WITHOUT the per-command bwrap wrap (the runtime's own mounts confine it),
+  and releases it from the preset scope's disposer — closing the agent and
+  stopping the unit, whose cgroup reaps the session's leftovers. On in the
+  shipped preset; requires `agent: true`, systemd as PID 1, a reachable user
+  manager, `systemd-run` and `Linger`. The preflight refuses with the remedy
+  when one is missing (only a success is cached, so following the remedy
+  needs no app restart); set `sessionSandbox: false` for the per-command
+  shape. Validated on a live session: `ps -p 1` is systemd, the command's
+  cgroup is the `dsh-wsl-*.scope`, a background process and `/tmp` survive
+  across commands, and the unit disappears after the session ends.
+
+- **The session-runtime registry.** `src/session-runtime.ts` refcounts one
+  agent per `(distro, workspace, policy)`, composes the systemd user scope
+  prefix with a bwrap mount profile that avoids a PID namespace (and binds the
+  real `/tmp` under `workspace-write`), and tears a runtime down by closing the
+  agent and then stopping the scope. `--unshare-pid` is now a profile option
+  (default true), and the agent accepts an explicit lease independent of the
+  idle close. Tests cover the refcount, the mode-specific mounts, the mask in
+  the key, the explicit lease, and the close-then-stop order. It is wired into
+  the shell executor behind `sessionSandbox`, with a preflight that refuses
+  with a remedy; the filesystem provider's unification is next.
+
+- **The session-scoped sandbox's launcher primitives.** `src/session-scope.ts`
+  builds the systemd user unit name, the `systemd-run --user --scope` prefix,
+  the stop argv and the preflight probe argv; unit tests pin the shapes and the
+  sanitization. ADR 0001 records the runtime-ownership decision the wiring
+  still has to make (the agent is a per-distro singleton today). No behavior
+  change yet.
+
+- **`docs/VALUE.zh.md` states what the plugin is worth, in Chinese**, for a
+  reader deciding whether to install it: the three misalignments it removes,
+  six values each with its mechanism and the evidence that backs it, the
+  comparison against no integration / desktop remoting / putting the CLI in
+  WSL, the costs and limits stated before the sale, how the claims are
+  proven, and a rule for when not to use it. It is linked from both readme
+  indexes and sits beside the reference docs, never in place of them.
+
+### Changed
+
+- **The peer pins move to the `0.2.1-rc.2` line**: `@deepseek-ai/dsh-*` at
+  `0.2.1-rc.2`, `@deepseek-ai/cordis` at `~4.0.5`, `@deepseek-ai/schemastery`
+  at `~3.18.5`, with `pnpm-lock.yaml` refreshed. pnpm's release-age policy
+  records the exact closure it had to exempt in `pnpm-workspace.yaml`, the way
+  the harness repository does. The three seam packages were compared byte for
+  byte against the previous pin: `dsh-fs-local`'s `lib/index.js` (the fsio
+  dialect this plugin replicates), `dsh-fs`'s, and `dsh-bash-local`'s (the
+  spill machinery and the `spawnSpec` seam) are identical files, so every line
+  reference in `docs/PEER-PARITY.md` and `docs/UPSTREAM-SPAWN-SEAM.md` still
+  names the same code — only the tarballs' digests changed, and
+  `docs/PEER-PARITY.md` now carries the `0.2.1-rc.2` ones. `cordis@4.0.5` and
+  `schemastery@3.18.5` likewise publish the same bytes as `4.0.4` and
+  `3.18.4` except for their manifests. Elsewhere: `dsh-fs@0.2.1-rc.2` drops its
+  unpublished `./invariant` export subpath (nothing here imported it),
+  `dsh-subprocess-local`'s new code is Linux systemd scope selection (this
+  plugin spawns `wsl.exe` from a Windows host), `dsh-api-workspace-files` adds
+  one `resource` field to its own lookup registration, and the typert protocol
+  gained modules.
+- **`preset-wsl` is regenerated from the shipped standard preset.** The rows
+  that arrived are the clock-reading `time-context` row, `tool-schedule`, and
+  the disabled `tool-plugin-market/tools` row; the rows that left are
+  `tool-ralph` and the disabled `subagent_codex` / `subagent_claude_code`
+  entries, whose providers the preset no longer declares anywhere. The two
+  `tool-subagent` rows drop `backgroundMode`, the plan-mode section's first
+  sentence now says the plan is approved *through* `exit_plan_mode`, and
+  `persona.suffix` is gone: the host plane's new `working-directory` row
+  reports the Session's cwd, so the "Your working directory is …" suffix is no
+  longer the mechanism. The three deliberate deviations from the shipped copy
+  — the `wsl-env` realm wrapping every row, the fixed shell-tool choice, and
+  the preset's identity — are unchanged, and the transformation is now
+  [scripts/build-preset-wsl.mjs](scripts/build-preset-wsl.mjs) rather than the
+  machine-local generator the block used to name: it takes the shipped file and
+  prints the row, and its output is the committed block byte for byte.
+- `docs/UPSTREAM-TERMINAL-FONT.md` closes: the `0.2.1-rc.2` line made the
+  terminal font a user setting (`--dsh-font-family-terminal` /
+  `--dsh-terminal-font-size`), so the hardcoded stack it argued against is now
+  only the fallback appended after the user's list.
+  `docs/UPSTREAM-TERMINAL-TITLE.md` was re-checked against the new tag and is
+  unchanged, including after the terminal controller's 0.2.1 rework: the tab
+  title is still built from `shell.name` alone.
+
+### Fixed
+
+- **The GUI file service loads again from a linked install** (`workspace-files-wsl`
+  failed to import, and the Desktop host then died on a `write EOF`). The module
+  imports `@deepseek-ai/dsh-api-workspace-files` and
+  `@deepseek-ai/dsh-typert-protocol` at runtime, but both were declared only as
+  dev dependencies. The runtime's linked-plugin resolver routes a bare import
+  to the installation package only when the plugin's own manifest lists that
+  name under `peerDependencies` (`dsh-app-boot`'s `readPeerNames` /
+  `routeLinked`), so the import missed, the entry never activated, and Desktop
+  exited 1; the fatal `write EOF` is the shell writing to that already-exited
+  host. Both names are peers now, and `test/peers.test.mjs` scans every
+  `lib/*.js` import so an undeclared runtime package fails the check chain
+  instead of the app.
+
+- **A warm native-agent cache no longer kills the Host on startup.** The
+  in-distro copy script prints the cache path and exits *without reading stdin*
+  when the digest already matches. `copyBinary` still streamed the packaged
+  binary into that closed pipe and left stdin's `error` event unhandled; on
+  Windows the write surfaced as `write EOF` and took the Host down before the
+  UI could load, so the first run (cold cache) worked and every later start
+  crashed. The write error is absorbed now — the exit code and stdout already
+  decide the result — and a POSIX regression check runs an early-exit script
+  against a payload larger than any pipe buffer.
+
+- **The root-plane router survives its first distro target, and that path now
+  has a regression test.** Three defects sat behind the same runtime failure:
+  - `WslRoutingFileSystem` kept its state in ES `#private` fields. Cordis
+    invokes a service method with a shadow receiver (the traceable proxy
+    `ReflectService` builds), and private members do not cross it, so the first
+    routed call threw `Cannot read private member #distro from an object whose
+    class did not declare it`. The fields are plain now, exactly like the host
+    backend's own `config` and `locks`.
+  - Constructing the distro backend with the router's context re-registered
+    `fs` in the same scope (`service "fs" has been registered`). The backend
+    now receives an `fs`-isolated child scope, while `sandboxPolicy` still
+    resolves from the parent. The router captures its construction context,
+    because `this.ctx` inside a method is the *caller's* context, not its own.
+  - The row dropped the `static inject = ["sandboxPolicy"]` declaration the
+    shipped `fs-sandbox` row carries, although the backend it constructs reads
+    `ctx.sandboxPolicy.defaultMode`. That service is provided by a sibling row,
+    not an ancestor, so the fiber could not resolve it and construction failed
+    with `cannot get property "sandboxPolicy" without inject`. The declaration
+    is restored.
+
+  The `0.2.1-rc.2` line's new `working-directory` row resolves the session cwd
+  through the root `ctx.fs`, which is what first exercised the distro branch.
+  `test/composition.test.mjs` now boots the takeover row through the Loader
+  and drives the whole routing table through the service proxy — distro side
+  stubbed at the backend surface, host side over a temp workspace, with the
+  policy supplied from a sibling fiber as in the app — so all three defects
+  fail the unit suite instead of a session.
+
+- **The GUI file service confines every read to the workspace, not just
+  listings.** `stat`, `read` and `readBytes` passed the joined Linux path
+  straight to `stat`/`sed`/`tail`, so an absolute path outside the workspace,
+  a `..` traversal, a symlink leaving it, or another distro's UNC name were
+  served — while `list` already resolved the real path and refused escapes
+  with `workspace-file/outside-workspace`. All four ops now share one guard:
+  `realpath -L` on the target and the root, then the same root/under-root
+  test, so an escape is the same refusal whichever op asks. The new checks
+  drive the real `sh` guard against a temp root (absolute sibling, `..`,
+  symlink out, symlink in, the root itself) and assert the refusal mapping in
+  all three ops.
+
+- **The resident transport owns its generation and its pipes.** Three
+  lifecycle leaks shared one cause — state keyed by "the current process"
+  instead of by the process that actually emitted the event:
+  - Every spawn now owns a generation; its `error`, `exit`, `stdout` and
+    `stderr` handlers return unless `this.process` is still that child, so a
+    stale exit can no longer settle a newer start, null a newer transport, or
+    let a stale watchdog kill it. `handshakeTimer`, the ACK-armed watchdog and
+    the frame-cap kill all bind to their own child.
+  - `close()` settles the requests it interrupts, fails a start it interrupts,
+    and destroys the host's ends of `stdin`/`stdout`/`stderr` after the exit.
+    A descendant that inherited a pipe's write end can no longer keep the
+    read side — and the fd — open until it exits.
+  - The agent's lease and timeout watchdogs now spawn with `/dev/null` stdio,
+    so their `sleep` children do not hold the protocol pipes after the agent
+    exits. Without this, killing the watchdog subshell left the `sleep` as an
+    orphan holding the write ends for up to the full lease window (12 minutes
+    at the shipped 720 s), which is what kept a test process alive after every
+    check had already passed.
+
+  The fake transport covers the stale-exit and stdio-teardown checks; the real
+  `sh` agent is spawned with a 720 s lease and asserted to close its pipes
+  immediately after `SHUTDOWN`.
+
+- **Cancellation reaches the command the agent is blocked on.** The stdin loop
+  is serial: a `KILL` frame written while a command ran sat in the pipe until
+  that command finished, and by then the id no longer matched, so the frame
+  was dropped. A request aborted mid-flight kept running to its own timeout; a
+  request aborted while queued ran in full later, with its answer discarded as
+  noise. Protocol 5 adds the agent shell's PID to `HELLO`; on abort the host
+  delivers `SIGUSR1` from a second `wsl.exe`, and the agent's trap kills the
+  request's process group — TERM, then KILL after the same 3 s grace the
+  timeout watcher uses. A request cancelled while it was still queued stays in
+  the pending map and is signalled on its `ACK`, so it is killed the moment it
+  becomes the running one; its late `RES` only cleans up. A PID-namespaced
+  confined resident is never signalled by its HELLO pid (that PID does not
+  exist in the distro and could name an unrelated process) — there the KILL
+  frame remains the fallback, and filesystem ops are short by construction.
+  The `KILL` frame stays as the fallback everywhere.
+
+  The fake transport covers the started, queued and confined cases; the real
+  `sh` agent is asked to run `sleep 30`, receives `USR1` after its ACK, and is
+  asserted to answer with a non-zero exit well before the sleep ends.
+
+- **The agent's ACK is emitted only once the request's child exists.** It used
+  to be printed just before `run_capture`, i.e. before `CURRENT_PID` was set.
+  The host arms its execution watchdog and delivers `USR1` on the ACK, so both
+  could race the spawn: a cancellation right after the ACK found an empty
+  `CURRENT_PID`, dropped the signal, and the command ran to its own timeout.
+  `run_capture` now prints the ACK after `CURRENT_PID=$!`, which is what the
+  host's comment always claimed it meant.
+
+- **The GUI page contract no longer returns its EOF probe line.** `pageArgv`
+  reads one line past the requested page so EOF is decidable from the yield;
+  `distroRead` returned every line it got and derived `lines`/`eof` from the
+  probe, so an N-line page carried N+1 lines, a page ending exactly at the file
+  reported `eof: false`, and `bytes` added the line count on top of the UTF-8
+  length (over-charging CRLF files and refusing pages that fit). The probe is
+  split off before counting, `eof` means "no line past the page", and `bytes`
+  is the page's own UTF-8 length. Tests cover truncation, exact EOF, and the
+  byte cap.
+
+- **The resident's pending queue is bounded.** One resident refuses a request
+  past `maxPending` (64 by default) with a clear "requests in flight" error
+  instead of growing its map — and the retained frame lines — without bound.
+  A single frame's size is still the caller's.
+
+- **The output budget now bounds the capture while the command runs.** The
+  agent wrote stdout and stderr to two unbounded files and applied
+  `maxOutputBytes` only while encoding the `RES`, so a chatty command could
+  fill the distro's `/tmp` — and a huge answer could exceed the 256 MiB frame
+  cap and kill the shared agent. With a budget, both streams are captured
+  through FIFOs drained by a bounded `dd` reader; the rest is discarded, so
+  the files stay within a block or two of the budget. The readers are given a
+  one-second grace once the request's own process is gone and then stopped, so
+  a background descendant holding the FIFO cannot delay the answer — and the
+  grace lets a just-exited command's output reach the file before the reader
+  is stopped. The block slack is what distinguishes "exactly at the cap" from
+  "cut". The unbounded path (`FS` frames) still writes files directly. Tests
+  cover `yes` capped at 1 KiB (`truncated: true`) and `sleep & echo` answered
+  without waiting for the background child.
+
+- **Confined file mutations share the session runtime.** With `wsl-fs`
+  `sessionSandbox: true` (the shipped preset), a confined `writeText`/`editText`
+  acquires the same `(distro, workspace, policy)` runtime as the shell
+  executor: one agent, one mount profile, one real `/tmp`, and the same scope
+  lifecycle. Reads stay on the plain shared agent; the app-level `fs-routing`
+  backend keeps the mode off because it is not session-owned. A failed
+  preflight refuses the write with the systemd/linger remedy.
+
+- **A closed watcher signals its loop by PID.** The heartbeat alone cannot
+  rely on the pipe closing when the host kills `wsl.exe`, so the loop now
+  announces its shell PID (`P <pid>`) before READY and `close()` sends it
+  `TERM` through a second `wsl.exe`; the TERM trap removes the stamp. The
+  real-machine watch probe now asserts the loop is gone, matching the script's
+  own argv rather than the `pgrep` wrapper. This is the fix the probe found
+  when the heartbeat-only version was tried on the real transport.
+
+- **A failed port scan keeps the last successful snapshot.** The ports
+  environment fact was set to an empty list on any scan failure, which the
+  model reads as "nothing is listening". A failed scan (agent out, non-zero
+  exit) now leaves the previous list in place and logs a debug line; only a
+  successful empty scan produces an empty list.
+
+- **The stale-scope sweep recognizes the native agent.** It looked only for
+  `wsl-agent.sh` in the scope's cgroup, so a live native session scope (whose
+  agent is `dsh-wsl-agent`) could be stopped at the next session preflight.
+  The liveness check now accepts either marker; a scope with only leftover
+  background processes is still reaped.
+
+- **The native EXEC timeout is seconds.** The spike read the v5 EXEC frame's
+  timeout field as milliseconds, so a 120 s budget killed every command after
+  120 ms; longer commands exited 143 on the native session. It now converts
+  seconds (`Duration::from_secs`), and the spike's check runs a 300 ms command
+  under a 2 s budget so the unit cannot regress silently.
+
+- **The inotify watcher is reaped promptly on close and on a vanished
+  directory.** The blocking FIFO read is woken by a one-second marker, so the
+  TERM trap runs and the target check reports `E` within a second of the
+  directory disappearing. The real-machine probe's close and vanished-target
+  checks now pass with `inotify-tools` installed; the pre-watch creation check
+  was also corrected (a file created before the watch is not the polling
+  mtime blind spot).
+
+- **A closed watcher no longer leaks its distro-side loop.** `close()` kills
+  `wsl.exe` but cannot signal the loop inside the distro, and a loop that only
+  writes on changes would sleep and poll forever. Each tick now writes an
+  ignored `H` heartbeat; a `PIPE` trap turns the closed pipe's SIGPIPE into a
+  clean exit through the stamp-removing EXIT trap. The host ignores `H`; the
+  real-`sh` check closes the pipe and asserts the loop exits and the stamp is
+  gone.
+
+- **A distro target contains only targets in the same distro.** `contains()`
+  compared Linux path strings, so another distro's share (or a `..`-bearing
+  key) could test as contained when the spelling lined up. It now compares the
+  distro coordinate and lexically normalizes the paths; the resolver remains
+  the canonicalizer for symlinks.
+
+- **A `notdir` failure reports `FS_NOT_DIRECTORY`.** The wire reason was
+  mapped to `FS_NOT_FOUND`, so a path whose parent is a regular file looked
+  like a missing path. It now carries the specific code the tool layer already
+  knows, so the model gets the right remedy.
+
+- **Stale session scopes are swept.** A hard kill of the app can leave a
+  `dsh-wsl-*.scope` and its background processes behind. The session preflight
+  now lists those units and stops one only when its cgroup has no
+  `wsl-agent.sh`; a live agent means another session still owns it. The sweep
+  runs once per distro per process (a failed spawn re-arms it) and is a no-op
+  without a user manager. Validated on a live user manager: two
+  `dsh-wsl-test-sweep*` scopes with only a `sleep` were stopped while the
+  session's own scope (with its live agent) stayed active.
+
+- **`watch()` accepts a file target.** The poll loop treated every
+  non-directory as vanished, so `ctx.fs.watch` on a regular file failed
+  immediately with "no longer exists". A file is now watched by its
+  `mtime:size` fingerprint — a rename-over or an in-place write fires — and a
+  removal reports the target as gone. Directory watching is unchanged. A
+  real-`sh` check runs the loop against a temp file (READY, a size change, a
+  removal).
+
+### Notes
+
+- **The native-session probe.** `test/probe/native-session.mjs` (also in the
+  real-machine suite and the self-hosted probes job) exercises the packaged
+  native binary end to end: the cache/digest, the session scope, EXEC, FS
+  write/read, a KILL that reaps the request group while the agent survives, a
+  wrong HELLO digest failing the handshake, and the scope/cache teardown. It
+  is 8/8 on the live machine. The probe found two integration bugs, both
+  fixed here: a valid cache is now reused instead of rewritten (rewriting a
+  binary a live session is running fails with ETXTBSY), and the agent's stdin
+  now has an error listener so `close()` after a failed handshake (EPIPE) does
+  not crash the host.
+
+- **Static musl packages for x86_64 and aarch64.** The package now ships
+  `agent/native/linux-x86_64/dsh-wsl-agent` (static-pie musl, 635,752 bytes,
+  sha256 `5920bdd5…`) and `agent/native/linux-aarch64/dsh-wsl-agent` (static
+  musl, 535,136 bytes, sha256 `cf7dd150…`), both stripped. One static binary
+  runs on glibc and musl distros, so Alpine no longer depends on the shell
+  fallback. A CI job builds both (x86_64 via musl-gcc, aarch64 via
+  cargo-zigbuild), tests the x86_64 build and uploads the `native-package`
+  artifact; the committed binaries are the reviewed result.
+
+- **The native HELLO binds the process to the binary.** The native agent
+  hashes `/proc/self/exe` and puts the sha256 in its HELLO digest; the host
+  passes the digest it copied into the cache as `expectedDigest`, so a binary
+  swapped after the copy check fails the handshake before accepting a request.
+  The spike is 18/18 (the new check compares the handshake to the file's
+  sha256). The shell agent's script digest is unchanged.
+
+- **The packaged native binary.** `agent/native/linux-x86_64/dsh-wsl-agent`
+  ships in the npm `files`; `agentBackend: auto` resolves it for a distro whose
+  `uname -m` is x86_64/amd64 (aarch64 is mapped but has no binary yet), with
+  `DSH_WSL_AGENT_NATIVE` still the development override. After the sha256 copy
+  the host executes the binary once with `</dev/null` and only then selects it,
+  so a glibc/musl mismatch falls back to the shell agent. The CI builds the
+  spike from source and runs its suite against both that build and the
+  committed package binary. The musl and aarch64 builds are the next step.
+
+- Added **`wsl-shell.agentBackend`**: `auto` (the default) uses the native
+  in-distro agent when a verified source is available — the development
+  override `DSH_WSL_AGENT_NATIVE`, and later the packaged per-arch binary —
+  else the shipped shell agent; `native` fails the first command instead of
+  falling back; `shell` forces the shell agent. Commands and confined writes
+  share the session runtime, so both follow the selection. With no source and
+  the default, behavior is unchanged (shell).
+
+- Added the opt-in **native agent host wiring**: `DSH_WSL_AGENT_NATIVE=<host
+  path>` makes the session runtime sha256 the binary into
+  `~/.cache/dsh-wsl/agent/<sha>/dsh-wsl-agent` (never from `/mnt/c`), verify
+  the distro-side digest, and spawn it under the session scope/bwrap with USR1
+  off (the native reads KILL frames). The shared FS-read agent, the one-shot
+  fallback and the default remain the shell agent; only x86_64 is accepted.
+  `scripts/native-wiring-check.mjs` verifies the copy + real runtime + EXEC/FS
+  end to end. Packaging/musl/default rollout is still pending.
+
+- Added the **native agent spike** (ADR 0002 stage 2) under
+  `agent/native/spike`: a std-only Rust event loop for HELLO/PING/SHUTDOWN/
+  SETENV/EXEC/KILL with per-request process groups, plus the FS
+  `stat`/`lstat`/`read`/`write`/`list`/`realpath` surface (mode, no-replace,
+  expected version, staging + fsync + atomic publication; the `dsh-fs` side
+  channel in the RES stderr). Its manual check passes 16/16 (concurrent EXECs,
+  KILL without a second `wsl.exe`, timeout group kill, output cut with the pipe
+  still drained, FS stat/lstat/read/list/realpath matching the shell,
+  write/refusal, side channel, dot-dot refusal, expected-version stale replace,
+  setuid mode, EXEC differential). The host wiring remains; the shell agent
+  stays the shipped peer.
+
+- Added **ADR 0002 — native in-distro agent (design)**: goals and non-goals,
+  language/distribution options (Rust static binaries, copied to the user's
+  cache), the v5-compatible spike and v6 concurrency protocol, the event-loop
+  process model, the host integration/copy/verify path, the security and test
+  matrix, the migration stages, and the triggers that would justify building
+  it. Implementation is deferred; the shell agent remains the shipped peer.
+
+- Documented the one-shot fallback's timeout boundary: the host deadline kills
+  `wsl.exe`, not the distro-side tree; the session runtime's scope is the
+  cleanup path, and a systemd-scoped one-shot is not shipped.
+
+
+- Gates on the new pins: style 9/9, syntax 7/7 members and 3/3 chain members
+  against `schemastery@3.18.5`, build freshness 74 artifacts, `tsc --noEmit`
+  clean, unit suite 30/30 files, coverage 98.42% lines / 84.20% branches /
+  96.01% functions. The real-machine probes were not re-run: they need
+  Windows and WSL, and their peer-verify legs are covered by the byte
+  comparison above.
+
 ## [0.9.0] - 2026-10-06
 
 A usability round over the sandbox failure path: the failure stops being a

package/CONTRIBUTING.md

@@ -24,8 +24,8 @@ algorithm, and the boot test starts a row through the real Loader — so a fresh
 checkout needs one `pnpm install` before the gates pass.
 
 Those pins are deliberate, and they move with the harness rather than on their
-own: the `@deepseek-ai/dsh-*` peers sit at `0.2.0-rc.2`, `@deepseek-ai/cordis`
-at `~4.0.4` and `@deepseek-ai/schemastery` at `~3.18.4`. The plugin subclasses
+own: the `@deepseek-ai/dsh-*` peers sit at `0.2.1-rc.2`, `@deepseek-ai/cordis`
+at `~4.0.5` and `@deepseek-ai/schemastery` at `~3.18.5`. The plugin subclasses
 peer classes and mirrors peer protocol, so raising one pin alone is how the
 seams drift: bump them in the commit that matches a harness release, re-run the
 comparison `docs/PEER-PARITY.md` describes, and let the gate chain and the