dsh-plugin-wsl-env 0.16.0 → 0.17.1

package/docs/LIMITATIONS.md

@@ -1,336 +1,170 @@
 # Limitations
 
+*A Chinese translation lives at [LIMITATIONS.zh](LIMITATIONS.zh.md); the English version is authoritative.*
+
 What the plugin does not do, and why. A limitation that is documented is a design
-boundary; one that is not is a bug report waiting to happen.
+boundary; one that is not is a bug report waiting to happen. Each entry states the
+limit and the remedy; the reasoning lives in [ARCHITECTURE.md](ARCHITECTURE.md) and
+the documents it links.
 
 ## The filesystem substrate (`wsl-fs`)
 
-The WSL-routed file tools use one substrate: the resident in-distro agent —
-reads, writes and identities happen on the filesystem backing the target path
-(typically ext4 for a distro's own files, but other mounts are possible). The former
-Windows-side share backend (`substrate: "share"`) is retired: a profile still
-carrying the value is refused at boot with the migration, and WSL-routed file
-operations do not use the Windows-side 9p share. What to know about the substrate:
-
-- **A new file publishes with mode 0600.** That is the host backend's own POSIX
-  publication semantics (a private 0600 staging file, renamed into place), which
-  a Linux-host DSH session has always had; the share dropped mode sets and took
-  the umask default instead, and that behaviour is gone with the share.
-  Overwrites and edits keep the original bits. Run `chmod` (or ask the model to)
-  when a new file must be executable.
-- **When the agent is out, file operations fail closed.** The distro stopped, or
-  the resident crashed through its revive budget: `FS_IO_ERROR` naming the
-  substrate, with the recovery path in the message. A single crash rides the
-  one rebuild (read-only ops only); a spent rebuild enters the bounded revival
-  (2/4/8 s), and three deaths make the state permanent with the restart remedy. There is no fallback I/O to degrade
-  into — deliberately; the old failure message pointed at the share, and the
-  share is what this plugin exists to keep the model off.
-- **The mutation guard survives to the write.** `createIfAbsent` publishes with
-  a no-replace link inside the distro, which closes the check-then-write window
-  for creates outright. An overwrite or edit carries the version it was based
-  on into the write op, and the agent re-verifies it against a fresh stat before
-  the rename. A mismatch returns `FS_STALE_VERSION`, but a change between the
-  check and rename can still be overwritten; this is not an atomic
-  compare-and-swap.
-- **A cancelled write can have an unknown outcome.** Cancellation is reported
-  before the agent necessarily finishes. A write already being published may
-  still take effect; inspect the file before retrying. The native agent refuses
-  queued writes when it processes their cancellation before they start. The
-  serial shell fallback removes requests cancelled while waiting on the host;
-  a request already sent to the agent may still take effect even if it has not
-  yet acknowledged the request.
-- **A successful write is not guaranteed durable across a crash.** The native
-  agent syncs the staged file before publication; the shell agent attempts
-  `sync -f` but ignores failure. Neither syncs the containing directory after
-  the rename or link. A kernel panic or power loss can therefore lose data or
-  the published directory entry; the operation is not a crash-consistent store.
-- **A Linux filename containing a backslash cannot be addressed.** The UNC
-  display form (`\\wsl.localhost\<distro>\...`) is the file's identity
-  everywhere - the session header, the GUI, the caches - and the backslash is
-  the UNC's separator, so `a\b.ts` in the distro round-trips to `a/b.ts`: the
-  tools would silently address a different path. This is the coordinate
-  system's own limit — a backslash-delimited identity cannot spell a name
-  containing a backslash — not a defect of the substrate; a rename away from
-  backslash names is the workaround.
-- **Stage two routes mutations through a confined resident.** A write or edit
-  under a confined policy runs on its own long-lived agent, spawned inside the
-  bwrap profile that binds exactly what the mode grants — so the kernel, not
-  just the host-side check, refuses a write outside the workspace, and the
-  refusal carries `FS_SANDBOX_DENIED` (the command path's dialect). Costs to
-  know: `bubblewrap` becomes required for confined writes (a distro without it
-  refuses them with the bootstrap command, rather than downgrading); a policy
-  change addresses a different resident, so the first write after switching the
-  Permissions selector pays one agent startup; and a write the policy grants to
-  the distro's `/tmp` lands in the distro's real `/tmp`, because the
-  file-writes resident binds it read-write — where the read tools, the plain
-  resident and the user's own shell all see it. The ephemeral tmpfs belongs to
-  the command side alone, so a file handed over from a command still goes
-  through the session workspace.
-- **`glob` and `grep` run the distro's own rg** (`lib/search-route.js`): the
-  tool's arguments are forwarded verbatim, so results, output format and exit
-  codes are rg's own — at ext4 speed, with the distro's `.gitignore` rules.
-  A distro without rg fails the search outright: exit 127, with the message
-  from the exec launcher and never from rg itself (which is the missing
-  program) — `setsid: failed to execute rg: No such file or directory` where
-  the distro has `setsid`, the script shell's `rg: not found` where it does
-  not. The install command `scripts/bootstrap.sh` prints — `wsl.exe -d <distro>
-  -u root -- apt-get install -y bubblewrap git ripgrep inotify-tools`, or the
-  detected family's spelling — installs it. `--install` runs that command only
-  when `bubblewrap` itself is missing, so a distro that has bwrap but not rg
-  needs the printed line run by hand. A search whose directory is a Windows
-  folder keeps the host binary, which is native there.
-- **`watch()` prefers inotify, with a polling fallback.** When `inotifywait`
-  is installed and the target is an unbounded directory, the watcher uses
-  recursive inotify watches and coalesces events to one callback per 0.5s.
-  Otherwise — a file target, a positive `maxDepth`, or no `inotify-tools` — it
-  is the `find -newer` poll loop (a `stat` fingerprint for a file), so the
-  coarse-invalidation caveats below apply.
-- **With `sessionSandbox: false`, a confined command's `/tmp` is not the write
-  tool's `/tmp`.** `workspace-write` mounts a fresh tmpfs at `/tmp` for the
-  command — that is what makes it ephemeral — while the file tools' fence grants
-  the distro's *real* `/tmp`. Both are writable, so neither side is refused, but a
-  file the write tool puts in `/tmp` is invisible to `bash` and vice versa. Hand
-  a file between them through the session workspace. The shipped preset turns
-  the session runtime on, and `wsl-fs` shares it for confined writes, so
-  commands and writes bind the same real `/tmp` and workspace.
-- A distro that is stopped or unregistered while the app runs takes the file
-  tools' substrate with it: reads and writes report the substrate-unavailable
-  error naming the cause. A death with nothing in flight costs nothing — the
-  next call starts a fresh transport, so a distro that comes back is served
-  again. A death with a request in flight spends the resident's one permitted
-  rebuild, and when that rebuild cannot complete — the distro is still down, or
-  gone — the resident is permanently out: every later file operation fails the
-  same way until the app restarts.
-- `watch()` observes from inside the distro, so callbacks are coarse
-  invalidation, not per-file notifications. With inotify they arrive as events
-  (coalesced to 0.5s); with the polling fallback they arrive on the poll
-  cadence, not instantly. In the polling path a creation is seen even when the
-  new file's own mtime is old: creating it bumps the containing directory's
-  mtime, and the scan includes the watched directory itself (deletions are seen
-  the same way). What escapes the polling stamp is a change that leaves every
-  scanned mtime older than it — an in-place `cp -p` onto an existing file (new
-  content, a copied-back mtime), or a `tar -x` whose archive restores the
-  containing directory's own mtime. That blind spot does not apply to the
-  inotify path. A FILE target is watched by its `mtime:size` fingerprint: a
-  rename-over or an in-place write fires, a removal reports the target as gone,
-  and a change that preserves both mtime and size escapes it. Watching a 9p
-  share from the Windows side remains unsupported — the loop runs where the
-  kernel can actually report change.
+One substrate: the resident in-distro agent (ext4 for distro files). The retired
+Windows-side share backend (`substrate: "share"`) is refused at boot; WSL-routed
+operations never use the 9p share.
+
+- **A new file publishes with mode 0600.** Overwrites and edits keep the original
+  bits; `chmod` when a new file must be executable.
+- **When the agent is out, file operations fail closed** — `FS_IO_ERROR` naming the
+  substrate, with the recovery path. One crash rides a single rebuild; a spent
+  rebuild enters bounded revival (2/4/8 s); three deaths are permanent until the app
+  restarts. There is no fallback I/O — deliberately.
+- **The mutation guard is not atomic compare-and-swap.** Creates use a no-replace
+  link; overwrites re-verify the version before the rename. A mismatch returns
+  `FS_STALE_VERSION`, but a change between check and rename can still be overwritten.
+- **A cancelled write can have an unknown outcome** — inspect the file before
+  retrying.
+- **A successful write is not crash-durable.** The staged file is synced, the
+  containing directory is not: a power loss can lose the entry.
+- **A Linux filename containing a backslash cannot be addressed** — the backslash is
+  the UNC separator, so `a\b.ts` round-trips to `a/b.ts`. Rename away from backslash
+  names; this is the coordinate system's own limit.
+- **Confined writes run on their own bwrap-confined resident** — kernel-enforced,
+  refusing outside the workspace with `FS_SANDBOX_DENIED`. Costs: `bubblewrap`
+  required; a policy change pays one agent startup; a write granted to `/tmp` lands
+  in the distro's real `/tmp`.
+- **`glob`/`grep` run the distro's rg**; a distro without rg fails the search
+  (exit 127). Install: `wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap
+  git ripgrep inotify-tools` (or the detected family's spelling). `--install` runs it
+  only for a missing `bubblewrap`.
+- **`watch()` is coarse invalidation, not per-file notifications**: inotify events
+  coalesced to 0.5 s, or a `find -newer` poll loop otherwise. The polling path misses
+  an in-place `cp -p` or a `tar -x` that restores older mtimes; a FILE target watches
+  an `mtime:size` fingerprint. 9p watching from Windows stays unsupported.
+- **With `sessionSandbox: false`, a confined command's `/tmp` differs from the write
+  tools' `/tmp`** — hand files over through the session workspace. The shipped
+  preset (`sessionSandbox: true`) shares one real `/tmp` and has no such split.
 - `editText` reads the whole file into memory before writing it back.
+- A distro that dies with a request in flight spends the resident's one rebuild;
+  still down, the resident stays out until the app restarts.
 
 ## The GUI workspace-files service
 
-- **The GUI file tree and previews use the shipped `workspace-files` row.** The
-  plugin deliberately does not replace it: its client half is the browser `file`
-  resource provider the Sidebar previews need, and a server-only replacement
-  drops it (the earlier `workspace-files-wsl` takeover did exactly that). The
-  shipped service reads WSL paths through the routed root filesystem
-  (`fs-routing`), so the file tree and previews still run inside the distro.
-
-- **That path costs extra agent round trips.** A listing, `stat` or page read
-  goes through `ctx.fs` before reaching the resident agent: roughly four to six
-  round trips instead of one, and a deep page read streams the preceding lines
-  through the pipe before cutting. Expect the GUI file tree and previews to be
-  slower than a direct agent call, especially on large files; the model's own
-  file operations are unaffected — they use the preset filesystem and the
-  resident agent directly. Measured 2026-10-19 with
-  [`test/probe/gui-preview.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/gui-preview.sh) (20 iterations on
-  this machine): the routed backend's `stat` p95 2.7 ms, `listDir` p95 5.1 ms,
-  and a 1 MiB `readByteRange` p95 **63.5 ms/MiB** — the service's own round
-  trips sit on top of those, and the 1 s/MiB budget has a wide margin. No
-  optimization is justified by these numbers; revisit only with a measured
-  regression.
-
-- **`fs-routing` is the seam.** The shipped service depends on the routed root
-  filesystem staying enabled and faithful to the `ctx.fs` contract (`resolve`,
-  `lstat`, `stat`, `listDir`, `streamText`, `readBytes`, `watch`, `contains`,
-  `processPath`). Disabling `fs-routing` restores the host 9p-backed root
-  filesystem, and the GUI file service then crosses 9p for WSL workspaces. The
-  shipped row's own caps (`maxBytes`, `maxFileBytes`, `maxLines`, `maxEntries`)
-  can be overridden on the `workspace-files` row.
+- The GUI file tree and previews use the shipped `workspace-files` row, reading WSL
+  paths through the routed root filesystem — deliberately not replaced (a server-only
+  takeover would drop the browser `file` provider the Sidebar previews need).
+- **Expect extra round trips** (roughly 4-6 per listing/stat/page; measured p95:
+  `stat` 2.7 ms, `listDir` 5.1 ms, 1 MiB read 63.5 ms/MiB — 2026-10-19,
+  [probe](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/gui-preview.sh)).
+  The model's own file operations are unaffected.
+- `fs-routing` is the seam: disabling it restores the host 9p-backed root filesystem.
+  The shipped row's caps can be overridden on the `workspace-files` row.
 
 ## `@` completion
 
-- **`@` references still walk the 9p share.** The shipped
-  `file-reference-local` service uses `node:fs/promises` from the Windows
-  harness process, so a WSL workspace pays a 9p `readdir`/`lstat` per
-  directory. On a 20-directory / 520-file tree the walk was **84.7 ms**
-  median over 9p versus **1.5 ms** on ext4 (~56×;
-  [`probe:file-reference`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/file-reference-9p.sh), 2026-10-19).
-  [`src/file-reference-wsl.ts`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/src/file-reference-wsl.ts) is the distro-side
-  traversal (built and unit-tested) but is **not** in `cordis.patch.yml`: the
-  funnels it would replace are module-internal. The fallback is the 9p walk
-  until upstream exposes `FileReferenceTraversal`. Cost, seam and wire
-  trigger: [UPSTREAM-FILE-REFERENCE-SEAM.md](UPSTREAM-FILE-REFERENCE-SEAM.md).
+- **`@` references walk the 9p share** (~56× slower than ext4 on a probed tree,
+  2026-10-19). The distro-side traversal is built but not mounted — it needs the
+  upstream `FileReferenceTraversal` seam:
+  [UPSTREAM-FILE-REFERENCE-SEAM.md](UPSTREAM-FILE-REFERENCE-SEAM.md).
 
 ## The sandbox
 
-- **The one-shot fallback has only the host deadline.** With `agent: false`, or
-  when the resident is out of service, a command runs through a fresh
-  `wsl.exe`. The host kills `wsl.exe` at the timeout, but WSL does not relay
-  that kill into the distro, so the Linux-side process tree can outlive the
-  call. The session runtime path — the shipped default — is cleaned by its
-  scope. A systemd-scoped one-shot (with explicit environment pass-through) is
-  not shipped; prefer `agent: true` and the session runtime for long commands.
-- **Batch file reads share one agent per distro.** Since A7 the shared read
-  agent is the native binary, so 16 concurrent `stat`/`read`/`list` calls
-  complete in 2.4-4.1 ms (A6 measured 342-614 ms on the shell). The first call
-  pays the native preparation/cache cost (~70 ms once); `agentBackend: shell`
-  forces the shell reads. v6's FS concurrency would only shave the native
-  runtime's 7.7 ms/16 writes and is deferred.
-- **The native backend is the default; aarch64 is executed under qemu in CI.**
-  The `native packages` job builds static-musl x86_64 and aarch64 binaries and
-  runs the 18-check suite against both the freshly built aarch64 artifact and
-  the committed `agent/native/linux-aarch64/dsh-wsl-agent` under qemu-user.
-  Physical aarch64 WSL is out of scope (no Windows-on-ARM machine in reach);
-  see [COMPATIBILITY.md](COMPATIBILITY.md#scope-decisions).
-  `agentBackend: auto` still selects the packaged binary on an aarch64 distro;
-  `native` refuses if preparation fails, and `shell` forces the shell agent.
-- **The session runtime needs systemd and a lingering user manager.** The
-  shipped preset sets `sessionSandbox: true`; a distro without systemd as PID 1,
-  a reachable `systemd --user`, `systemd-run`, or `Linger` is refused on the
-  first command with the remedy. Set `sessionSandbox: false` on the preset's
-  `wsl-shell` to keep the per-command shape. A **hard crash** of the app can
-  leave a stale `dsh-wsl-*.scope` and its background processes behind; a
-  graceful session end stops the scope (validated). The session preflight
-  sweeps stale scopes when the next WSL session opens: it stops a
-  `dsh-wsl-*.scope` only when its cgroup has no agent process (`wsl-agent.sh`
-  or the native `dsh-wsl-agent`), so another live session's runtime is never
-  touched.
-- **The sandbox does not govern WSL interop.** A confined command can still run a
-  Windows program, which escapes the Linux-side boundary. The plugin reports this as
-  `enforcement: partial`. See [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
-  The `maskWindowsDrive` key on `wsl-shell`, `wsl-fs` and `fs-routing` narrows the
-  hole: the confined profile shadows `/mnt` with an empty tmpfs, so files and
-  executables at paths under `/mnt` are hidden. Other mounts, alternate access
-  paths and unrestricted file reads are not covered by this mask. It is not a
-  closure — a command that can write the workspace can write an executable there and
-  run it (binfmt interop dispatches on file content, not location) — so enforcement
-  stays `partial`, the result's sandbox fact reports `windowsDrive: "masked"`, and
-  distro-level disabling of WSL interop (`[interop] enabled=false` in
-  `wsl.conf`) must be configured separately. On `wsl-shell`, an explicitly set
-  `interopVisibility` takes precedence over `maskWindowsDrive`.
-- **`bubblewrap` must be installed**, or both providers fail immediately. The
-  usability probe re-runs after a failure, so installing bubblewrap while the app
-  runs is believed on the next command; only a success is cached. The refusal
-  classifies the probe's failure — missing versus present-but-failing — and the
-  direct install command follows the distro's package family; a probe failure
-  with no recognisable shape falls back to the install remedy with the raw
-  output quoted. A session-start preflight (`wsl-preflight`) surfaces the same
-  text as a warning; it is advisory and never installs.
-- `workspace-write` binds the workspace root as writable, and bubblewrap refuses a
-  bind whose source directory does not exist, so a session whose workspace directory was
-  deleted fails with a runner error; the plugin does not recreate it. A workdir that
-  does not exist — a configured `cwd` pointing at a deleted directory, for instance — is
-  a separate case and is now reported as an error naming that directory, because
-  `wsl.exe` would otherwise run the command in `/` and exit 0.
+- **The one-shot fallback has only the host deadline** — a killed `wsl.exe` does not
+  relay the kill into the distro, so the Linux process tree can outlive the call.
+  Prefer `agent: true` and the session runtime for long commands.
+- **Batch reads share one native agent per distro** (16 concurrent calls in
+  2.4-4.1 ms; first call pays ~70 ms preparation).
+- **aarch64 runs under qemu in CI only** (no Windows-on-ARM machine in reach —
+  [COMPATIBILITY.md](COMPATIBILITY.md#scope-decisions)). `auto` still selects the
+  packaged binary; `native` refuses on preparation failure; `shell` forces the shell
+  agent.
+- **The session runtime needs systemd and a lingering user manager** — refused on the
+  first command with the remedy otherwise; `sessionSandbox: false` keeps the old
+  per-command shape. A hard app crash can leave a stale `dsh-wsl-*.scope`; the
+  preflight sweeps stale scopes on the next WSL session (never another live
+  session's).
+- **The sandbox does not govern WSL interop** — reported as `enforcement: partial`.
+  `maskWindowsDrive` narrows `/mnt` but is not a closure; distro-level
+  `[interop] enabled=false` in `wsl.conf` must be configured separately.
+  [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
+- **`bubblewrap` must be installed**, or both providers fail with the install
+  command; a session-start preflight surfaces the same text as an advisory warning.
+- A workspace directory deleted mid-session fails with a runner error; the plugin
+  does not recreate it. A configured `cwd` that does not exist is reported as an
+  error naming the directory.
+
+## Shell startup semantics (`wsl-shell`)
+
+Commands run as `<shell> -lc <command>` — login (profile scripts sourced, so version
+managers work) and **non-interactive** (no prompt/plugin output in the model's
+streams).
+
+- **`~/.zshrc` / `~/.bashrc` are never read.** Move machine-level PATH setup
+  (`fnm`, nvm, cargo) into `~/.zprofile` or `~/.zshenv`; keep prompts and completion
+  in the rc file.
+- **fnm's multishell PATH cannot form inside the sandbox** (`/run` is read-only) —
+  use the fallback recipe in
+  [Configuration](CONFIGURATION.md#zshfnm-recipe-for-model-run-commands).
 
 ## Agent diagnostics
 
-- **The doctor's `agent.handshake` check probes a fresh resident, not the live
-  one.** It starts `agent/wsl-agent.sh` in the distro, reads its HELLO (pid,
-  protocol, script digest) and stops it, so it proves that the agent path can
-  start and that the file the distro reads is the shipped one. It cannot read
-  the running app resident's last error — there is no IPC channel from a plugin
-  script to the app process — so that error stays in the app log. In-process,
-  `WslAgent.status()` exposes state, pid, lastError, deaths and pending.
-- **`dsh-wsl-*.scope` counts are point-in-time.** The doctor lists and inspects
-  the user scopes once; a scope created or stopped a moment later is not
-  reflected. `--fix` runs the same sweep the session preflight uses.
-
-## The doctor's sessions table
-
-- **The sessions table shows distro-side facts only.** The cross-distro view
-  (`distro → scope → state → resident pids`) attests what the distro can see:
-  which scopes exist and which pids inside them are agent processes. A
-  resident's idle countdown and its `lastError` live in the host process that
-  owns it — there is no IPC channel from a plugin script to the app, so the
-  table cannot show them (`WSL-313`'s upstream ask). The agent.handshake
-  check notes a live resident's presence when the scope survey sees one, and
-  says that its own probe starts a fresh one.
+- **The doctor's `agent.handshake` probes a fresh resident**, not the live one —
+  a running resident's `lastError` stays in the app log (`WslAgent.status()` exposes
+  it in-process).
+- **`dsh-wsl-*.scope` counts are point-in-time**; `--fix` runs the preflight's sweep.
+- **The doctor's `git.win-safe` probe reports the Windows git trust through interop
+  `git.exe`** — the `safe.directory` whitelist that WSL change review needs when
+  Windows git is installed (see Terminals below).
 
 ## Session-start advisories
 
-- **There is no session-UI notice seam in DSH 0.2.1.** When a distro session
-  opens, `wsl-preflight` checks `bubblewrap`, systemd as PID 1, the user
-  manager, `systemd-run` and Linger. A failure is advisory: it never installs
-  anything, never cancels the session and never changes the fail-closed
-  behavior of the first command. The finding goes to the host log
-  (`logger.warn`) and into the session's runtime context as a `wsl-preflight`
-  entry — model-visible on the next assembly — but the GUI today has no
-  toast/banner service a plugin can publish to. `pnpm run doctor` is the
-  deterministic human-facing check; the exact upstream ask is
+- **There is no session-UI notice seam in DSH 0.2.1.** `wsl-preflight` failures go
+  to the host log and the session's runtime context (model-visible next assembly) —
+  advisory only, never installing or cancelling. The upstream ask:
   [UPSTREAM-SESSION-NOTICE.md](UPSTREAM-SESSION-NOTICE.md).
 - **The runtime-context entry is a repeated snapshot, not a dismissible
-  notification.** It appears in every assembly until the environment is fixed;
-  it has no severity decoration and no dismiss control. Removing the
-  `wsl-preflight` row (or setting `sandbox: false` on it) silences the probe
-  entirely.
+  notification.** Removing the `wsl-preflight` row silences the probe entirely.
 
 ## Ports
 
-- **The port poller keeps the resident agent permanently warm.** The
-  `DSH_WSL_PORTS` snapshot refreshes through the shared resident agent every
-  `portsRefreshMs` (10 s by default, well inside the agent's idle timeout), so
-  while a distro's session is active the agent never idles out: one `wsl.exe`
-  and one in-distro agent process stay resident per active distro even with no
-  command in flight. The poller starts only for a distro a session actually
-  uses; raising `portsRefreshMs` past the agent's idle timeout restores idle
-  shutdown, at the cost of staler port facts.
+- **The port poller keeps the resident agent permanently warm** per active distro
+  (refresh 10 s). Raising `portsRefreshMs` past the agent's idle timeout restores
+  idle shutdown, at the cost of staler port facts.
 
 ## The directory picker
 
-- The directory picker lists distro levels from inside the distro — the
-  resident's `find -L <dir> -maxdepth 1 -mindepth 1 -type d -print0` in one
-  round trip, a one-shot `wsl.exe --exec find` when it is out, never the 9p
-  walk the host used to pay per entry. Entries arrive NUL-separated, so a
-  directory name containing a newline lists as one exact row (WSL-306 retired
-  the `ls -1ALp` line parse that used to split such a name into two rows or
-  drop it).
+- Distro levels list from inside the distro in one round trip (NUL-separated, so
+  newline-bearing directory names list exactly — WSL-306); a one-shot `wsl.exe --exec
+  find` when the resident is out.
 
 ## Terminals
 
-- Terminal routing is per-session by workspace coordinates (`subprocess-wsl.hostSessions`,
-  default on): a WSL-folder session gets the distro shell, a Windows-folder session gets
-  `powershell.exe` in its own directory. The shell MENU remains the single configured
-  profile, and a directory-less launch still lands in the distro.
-- A host session's TAB TITLE still reads `WSL`, the composition's shell profile
-  name, over a PowerShell process. The controller titles a tab from that profile
-  before the provider rewrites the launch, and a plugin cannot correct it: a
-  patch layer asserts rather than renames a row's module, and the row's id is
-  load-bearing for the web composition (disabling it fails web boot with
-  "waiting for service: webTerminals"). The full account and the proposed
-  upstream change are in [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
-  Meanwhile, double-click a tab's title to rename it, or add `shellCandidates`
-  to the `terminal-controller` row in your own profile layer — a manually
-  selected shell is titled after itself.
-- Distro terminals ARE reclaimed when idle — the observation is distro-side:
-  each terminal is launched with a `DSH_TERMINAL_ID` marker, and the handle's
-  `inspectActivity` counts the marked processes through the resident agent
-  (`lib/terminal-activity.js`). Exactly one (the shell at its prompt) is
-  `idle`; more than one (a command, a pipeline, a nested shell) is `busy`;
-  `unknown` — the agent out, the distro stopped — pauses reclamation, because
-  a probe that cannot answer must not authorize a close. Consequences to
-  know: a nested shell keeps the terminal busy by design (closing it would
-  lose that shell), so does any process the shell's startup files spawn with
-  the inherited marker (an `ssh-agent` launched in `.bashrc` reads as busy);
-  the idle threshold is the controller's `unattendedTimeoutMs` (2 h by
-  default); and the host-side shell-activity integration is still not armed
-  for these launches — `wsl.exe` on win32 fails its gate — which is why the
-  observation is a scan rather than shell cooperation. `terminalIdleReclaim:
-  false` on the `subprocess-wsl` row restores close-by-hand: the launch then
-  carries no `DSH_TERMINAL_ID` marker, and the handle keeps the shipped
-  `unknown` activity, which never accumulates idle.
-- Windows-folder host terminals (the `powershell.exe` branch) keep the shipped
-  behaviour: `unknown` activity, no reclamation.
+- Terminal routing is per-session by workspace coordinates: a WSL-folder session gets
+  the distro shell, a Windows-folder session gets `powershell.exe` in its own
+  directory. The shell MENU's default entry stays the configured profile; a
+  directory-less launch lands in the distro.
+- **Windows git must trust the share** (`safe.directory`), or WSL workspaces'
+  changed-files cards silently disappear (the discovery call answers
+  `detected dubious ownership`). One-time remedy on Windows:
+  `git config --global --add safe.directory "//wsl.localhost/*"`, then restart the
+  app. Two alternatives: the doctor's `git.win-safe` probe reports the state, and a
+  machine **without** Windows git needs nothing — the provider routes discovery into
+  the distro and translates the output into UNC form.
+- **A NEW tab's title reads `WSL`** whatever it runs — the controller titles from the
+  composition's profile before the provider rewrites the launch, and a plugin cannot
+  correct the default ([UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md)).
+  The menu ships host candidates (`powershell`, `cmd`): a manually selected shell is
+  titled after itself; double-click rename also works.
+- **Distro terminals ARE reclaimed when idle** — the handle counts the marked
+  processes through the resident agent (exactly one at its prompt = `idle`; a nested
+  shell or an `ssh-agent` from startup files reads `busy` by design). Threshold: the
+  controller's `unattendedTimeoutMs` (2 h). `terminalIdleReclaim: false` restores
+  close-by-hand. Windows-folder host terminals keep the shipped no-reclamation
+  behaviour.
 
 ## Host "Open in app"
 
-- **Opening VS Code (or another Electron editor) from the host "Open in app"
-  menu can fail independently of this plugin.** The DSH Host process runs with
-  `ELECTRON_RUN_AS_NODE=1`. The open-in-app launcher inherits that variable, so
-  `Code.exe` starts as Node, exits 1, and the UI reports launch-failed. File
-  Explorer and other non-Electron launchers are unaffected; the failure is the
-  same on a Windows folder and on a WSL UNC workspace. This repository does
-  not own that spawn path. The record and the upstream fix are in
+- **Opening VS Code from "Open in app" can fail independently of this plugin** — the
+  Host runs with `ELECTRON_RUN_AS_NODE=1`, which the launcher inherits, so
+  `Code.exe` starts as Node and exits 1. Not owned by this repository:
   [UPSTREAM-OPEN-IN-APP.md](UPSTREAM-OPEN-IN-APP.md).