dsh-plugin-wsl-env 0.8.0 → 0.10.0

package/docs/UPSTREAM-FSIO-EXPORT.md

@@ -1,54 +1,90 @@
-# Upstream proposal: export the fsio module from `dsh-fs-local`
+# Upstream proposal: export the fsio text helpers from `dsh-fs-local`
 
-Status: draft, targeting `deepseek-harness` @ `packages/fs/fs-local` (version
-line `0.2.0-rc.x`). This is the Shape-A upstream half of the in-distro I/O
-refactor: with the fsio module exported, `dsh-plugin-wsl-env` deletes its
-in-plugin replicas (`lib/fsio-text.js`) and imports the originals.
+Status: draft, not yet filed upstream — no discussion link yet (the filing
+convention is [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md)).
+Targeting `deepseek-harness` @ `packages/fs/fs-local`, the `0.2.1-rc.x` line
+this plugin pins exactly (`@deepseek-ai/dsh-fs-local@0.2.1-rc.2`, in both the
+dev and peer dependency blocks of `package.json`). This is the Shape-A
+upstream half of the in-distro I/O refactor: with the fsio text mechanics
+importable, `dsh-plugin-wsl-env` deletes its copies of them.
 
 ## The change
 
-The fsio module already exists, is fully documented, and is pure (no peers
-beyond types). It is only not reachable: `package.json` exports `"."` and
-`"./package.json"`, and `lib/index.js` does not re-export the helpers. Two
-lines of surface, no behaviour change:
+The fsio module already exists and is fully documented in the shipped
+declarations (`lib/types/fsio.d.ts`). Two facts keep it out of reach:
 
-```diff
---- a/packages/fs/fs-local/package.json
-+++ b/packages/fs/fs-local/package.json
-@@
-   "exports": {
-     ".": {
-       "types": "./lib/types/index.d.ts",
-       "default": "./lib/index.js"
-     },
-+    "./fsio": {
-+      "types": "./lib/types/fsio.d.ts",
-+      "default": "./lib/fsio.js"
-+    },
-     "./src/*": "./src/*",
-     "./package.json": "./package.json"
-   },
-```
+- `package.json` exports exactly three entries — `"."`, `"./src/*"` and
+  `"./package.json"` (lines 16–23). `"./src/*"` is not a way in: `files` is
+  `["lib/index.js", "lib/types/**/*.d.ts"]` (lines 24–27), so the sources are
+  in the repository but not in the tarball (`npm pack --dry-run` lists nine
+  files, none of them under `src/`).
+- The published runtime is one bundled file. The fsio code is a region of
+  `lib/index.js` (`//#region lib/types/fsio.js`, line 90) — there is no
+  `lib/fsio.js` — and that file's only export statement is
+  `export { LocalFileSystem, LocalFileSystem as default };` (line 909).
+
+So the reachable seam is the package entry, not a new subpath: re-export the
+four text helpers from it, in the runtime and in the declarations.
+
+(A `"./fsio"` subpath does not work as-is — the runtime file it would name does
+not exist. Pointing its `types` at `lib/types/fsio.d.ts` instead would publish
+the whole fsio surface — `readWholeText`, `readWholeBytes`, `readByteWindow`,
+`streamWholeText`, `writeFileAtomic`, `probe`, `probeNoFollow`,
+`listDirectory`, `resolveLocalTarget`, `readForEdit`, `readTextForDiff`, … —
+while the runtime side offered four names. Types and runtime must promise the
+same surface.)
 
 ```diff
 --- a/packages/fs/fs-local/lib/index.js
 +++ b/packages/fs/fs-local/lib/index.js
-@@
+@@ -906,4 +906,11 @@
+ 	}
+ };
+ //#endregion
 -export { LocalFileSystem, LocalFileSystem as default };
 +export {
-+  LocalFileSystem,
-+  LocalFileSystem as default,
-+  applyLiteralEdit,
-+  detectLineEndings,
-+  normalizeLineEndings,
-+  restoreLineEndings,
++	LocalFileSystem,
++	LocalFileSystem as default,
++	applyLiteralEdit,
++	detectLineEndings,
++	normalizeLineEndings,
++	restoreLineEndings,
 +};
 ```
 
-(The module layout differs between the repo's `src/` and the built `lib/`;
-the export list is what matters. `readForEdit` and `readTextForDiff` stay
-internal — they are I/O orchestration, which the plugin drives against its own
-substrate — only the pure text mechanics are needed.)
+```diff
+--- a/packages/fs/fs-local/lib/types/index.d.ts
++++ b/packages/fs/fs-local/lib/types/index.d.ts
+@@ -66,4 +66,5 @@
+     private versionAfterWrite;
+ }
+ export default LocalFileSystem;
++export { applyLiteralEdit, detectLineEndings, normalizeLineEndings, restoreLineEndings } from './fsio.ts';
+ //# sourceMappingURL=index.d.ts.map
+
+```
+
+Both files are generated; the change itself belongs in the sources that emit
+them (`src/index.ts` re-exporting from the fsio module, and that module
+exporting `detectLineEndings`). The artifact diffs are shown because they are
+what a consumer resolves — and they apply as-is to the published `0.2.1-rc.2`
+files.
+
+`detectLineEndings` is the one genuinely new name: it is not in
+`lib/types/fsio.d.ts` at all — in the bundle it is a non-exported function
+(`function detectLineEndings(raw)`, line 587). Declaring it is a
+`declare function detectLineEndings(raw: string): LineEndings;` beside its two
+siblings, plus the name in the export list at `fsio.d.ts:223` (`LineEndings`
+itself is already exported, `:166`). The other three are already declared
+there: `normalizeLineEndings` (`:173`), `restoreLineEndings` (`:182`),
+`applyLiteralEdit` (`:219`), with the first two exported at `:223`. If upstream
+would rather not widen the surface at all, leave `detectLineEndings` out and the
+consumer keeps its four-line local copy.
+
+`readForEdit` and `readTextForDiff` are not part of this. They are exported by
+the fsio module (`fsio.d.ts:191`, `:207`), but they are I/O orchestration —
+which the plugin drives against its own substrate — so the proposal simply does
+not re-export them.
 
 ## Why the plugin needs it
 
@@ -56,27 +92,100 @@ substrate — only the pure text mechanics are needed.)
 `lib/fs-substrate.js`) re-runs fsio's orchestration inside a WSL distro: reads,
 writes, identities and edits execute where the files live, and the host side
 keeps only the validation and edit mechanics. Those mechanics —
-`applyLiteralEdit`, the line-ending trio, the binary NUL sample, the fatal UTF-8
-decode — are replicated today (`lib/fsio-text.js`) because the package does not
-export them. The replica is byte-for-byte faithful, including error messages,
-because the tool layer matches on both the code and the text the model reads;
-but a replica is a fork surface: every upstream change to the edit algorithm
-has to be re-ported by hand.
+`applyLiteralEdit`, the line-ending trio, the binary NUL sample, the fatal
+UTF-8 decode — are replicated today in `src/fsio-text.ts` (built to
+`lib/fsio-text.js`) because the package does not export them. The replica is
+byte-for-byte faithful, including error messages, because the tool layer
+matches on both the code and the text the model reads — and that faithfulness
+is verified, not assumed: [PEER-PARITY.md](PEER-PARITY.md) records the
+function-by-function and string-by-string comparison against the pinned peer's
+shipped code (verified 2026-10-03; the read/edit split re-verified
+2026-10-06). But a replica is a fork surface: every upstream change to the edit
+algorithm has to be re-ported by hand.
 
-With the export in place the plugin deletes `lib/fsio-text.js` and imports:
+With the export in place the plugin imports the four functions and deletes its
+copies:
 
 ```js
-import { applyLiteralEdit, detectLineEndings, normalizeLineEndings, restoreLineEndings } from "@deepseek-ai/dsh-fs-local/fsio";
+import { applyLiteralEdit, detectLineEndings, normalizeLineEndings, restoreLineEndings } from "@deepseek-ai/dsh-fs-local";
 ```
 
+The rest of the module stays. `BINARY_SAMPLE_BYTES`, `FsCodedError`,
+`notTextError`, `decodeUtf8`, `decodeUtf8Stream` and `throwIfAborted`
+(`src/fsio-text.ts:23`, `:30`, `:53`, `:67`, `:86`, `:179`) have no counterpart
+in the fsio declarations, and the module's other consumers keep importing them
+locally (`src/fsio-agent.ts:27-36`, `src/fs-substrate.ts:37`,
+`src/index.ts:57`). `lib/fsio-text.js` is not deleted; four of its ten exports
+are.
+
+Importing from the entry costs this consumer nothing new: it already imports
+`LocalFileSystem` from the same entry (`src/index.ts:45`,
+`src/fs-routing.ts:35`) and `@deepseek-ai/dsh-fs` (`src/index.ts:46`). The
+entry's non-builtin static imports are `chokidar` (`lib/index.js:3`),
+`@deepseek-ai/schemastery` (`:6`) and the `@deepseek-ai/dsh-fs` peer (`:7`) —
+all three already in this consumer's graph; `koffi` loads lazily (`await
+import("koffi")`, `:25`), so no native dependency is evaluated at import time.
+
 ## Why this is safe upstream
 
-- No new API surface beyond re-exporting functions that already exist and are
-  documented in `lib/types/fsio.d.ts`.
+- Additive: three of the four names are already declared in the shipped
+  `lib/types/fsio.d.ts`; `detectLineEndings` is one new pure function the edit
+  path already calls (`readForEdit`, `lib/index.js:629` — the class reaches it
+  through `editText`).
 - No behaviour change: the class's own call sites are untouched.
-- The functions are pure (text in, text out, structured errors), so exporting
-  them cannot widen the I/O contract.
-- Semver: additive export, a minor bump.
+- The functions do no I/O and hold no state — text in, text out, structured
+  errors — so exporting them cannot widen the I/O contract.
+- They are pure but **not peer-free**: the module they live in imports
+  `FsError`, `FsTargetKey` and `FsVersion` from the `@deepseek-ai/dsh-fs` peer
+  (`lib/index.js:7`) and uses them throughout (`FsError` thrown at `:700`,
+  `:703`, `:704`; `FsTargetKey` at `:175`, `:196`, `:207`; `FsVersion` at
+  `:146`), so importers of these helpers take that peer at runtime. They do not
+  take cordis — the bundle imports none. The plugin accepts the peer
+  dependency: both packages are already runtime imports of it, and its tool
+  layer maps the `code` token and the message, not the error class.
+- Semver: an additive export. On the `0.2.0-rc.x` line it ships in the next
+  pre-release — the `0.2` position does not move, so this is not a minor bump
+  of a released line; and because the consuming plugin pins the exact version,
+  adoption is an explicit pin bump, never an automatic upgrade.
+
+## Landing it (consumer side)
+
+1. Bump both pins in `package.json` (`devDependencies` and `peerDependencies`)
+   to the peer that carries the export.
+2. `pnpm run build` — `lib/` is committed, and `test/build-freshness.mjs`
+   enforces that it is a byte-identical, closed image of `src/`.
+3. Re-run the comparison in [PEER-PARITY.md](PEER-PARITY.md) (its Maintenance
+   section) against the new pin before trusting anything else.
+4. Delete the four replicas and point the call sites at the peer, then
+   `pnpm test`.
+
+Files that move with it:
+
+- `src/fsio-text.ts` — drop `applyLiteralEdit`, `detectLineEndings`,
+  `normalizeLineEndings`, `restoreLineEndings`; keep the rest.
+- `src/fsio-agent.ts` (imports `:27-36`, `detectLineEndings` used at `:528`)
+  and `src/fs-substrate.ts` (`:37`) — take the four from the peer. Where they
+  land decides the module's peer story: importing them directly keeps
+  `src/fsio-text.ts` peer-free — and `test/fsio-text.test.mjs`, which imports
+  nothing but node builtins and the local module (`:9-18`), runnable without
+  the peer — while re-exporting them through it does not. Either way the
+  "peer-free" self-descriptions in `src/fsio-agent.ts:14-16` and
+  `src/fs-substrate.ts:25` need a pass.
+- `lib/*` — the rebuilt artifacts.
+- `test/fsio-text.test.mjs` (the replica's tests, including the
+  `detectLineEndings` checks at `:69-72`) and `test/fsio-agent.test.mjs:22`,
+  which imports two of the four from `lib/fsio-text.js`. If that test file is
+  dropped or renamed, also the `test:coverage` and `test:unit` lists at
+  `package.json:114` and `:116`.
+- The documents that describe the replica as current: `docs/ARCHITECTURE.md:173`
+  and `:416` (the two entries marked "replicated … pending the … export"),
+  `docs/PEER-PARITY.md:3` and `:17` (plus its Maintenance section),
+  `docs/upstream/promotion-map.md:82` — and this file, whose status then becomes
+  "landed".
+
+Done when: the pinned peer resolves the four names from both its runtime entry
+and its declarations, the plugin imports them there, `pnpm test` passes, and no
+document still calls `lib/fsio-text.js` a replica of them.
 
 ## Follow-up (separate proposal, not required)
 

package/docs/UPSTREAM-TERMINAL-TITLE.md

@@ -2,17 +2,28 @@
 
 Status: proposed upstream as
 [deepseek-ai/deepseek-harness#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
-(targeting `packages/api/terminal-controller`, version line `0.2.0-rc.x`). This
-is the record of a gap this plugin worked around, could not work around, and
-now documents: the GUI terminal titles every tab from the composition's single
-shell profile, so a per-session shell choice is invisible in the title.
+(targeting `packages/api/terminal-controller`, version line `0.2.1-rc.x`; the
+gap was re-checked against `dsh-v0.2.1-rc.2` on 2026-10-17 and is unchanged —
+`packages/api/terminal-controller/src/index.ts:327` still builds the terminal
+info with `title: shell.name`, and the spawn spec still carries no display-name
+field). The
+plugin worked around the execution half of this gap — a Windows-folder
+session's terminal runs a host shell (`subprocess-wsl.hostSessions`) — and
+could not work around the title half. This is the record: the GUI titles every
+tab from the composition's single shell profile, so a per-session shell choice
+is invisible in the title.
 
 ## The gap
 
-`TerminalController.spawn` fixes a terminal's display title from the resolved
-shell profile before the provider is ever consulted:
+The display title is fixed from the resolved shell profile and never revisited.
+The private `TerminalController.spawn` builds `info`, with `title: shell.name`,
+only after `await subprocess.spawnTerminal(...)` has returned, and it does not
+read back what that call started:
 
 ```ts
+const handle = await subprocess.spawnTerminal({
+  argv: [shell.path, ...shell.args], cwd: environment.cwd, cols: request.cols, ...
+})
 const info: WebTerminalInfo = {
   id: request.id, shell, title: shell.name, cwd: environment.cwd, ...
 }
@@ -48,10 +59,18 @@ Three escape hatches were evaluated against `0.2.0-rc.2` and each is closed:
    inserts `terminal-controller`, and the client model that the
    `dsh-client-ui-sidebar-terminal` entry waits for mounts with
    `inject = ['remote', 'remote.terminal']` — the `terminal` namespace the host
-   controller registers in its constructor. Disabling the row fails web boot:
-   `1 entry did not activate: @deepseek-ai/dsh-client-ui-sidebar-terminal:
-   pending (waiting for service: webTerminals)`. Verified live against
-   `dsh-desktop 0.2.0-rc.2`.
+   controller registers in its constructor. Disabling the row fails web boot
+   with this two-line error:
+
+   ```text
+   web boot: 1 entry did not activate
+   @deepseek-ai/dsh-client-ui-sidebar-terminal: pending (waiting for service: webTerminals)
+   ```
+
+   Verified live against `dsh-desktop 0.2.0-rc.2` (Electron 44.0.0); the
+   row-id and `inject` facts the argument rests on are readable in the
+   `dsh-v0.2.1-rc.2` tree and did not change with the terminal controller's
+   0.2.1 rework (`attach`/`write` → sequenced `TerminalInput`).
 3. **Per-session config.** The `shell` profile is composition state; `!!js`
    expressions evaluate once at config resolution and reach no Session
    identity.
@@ -62,7 +81,7 @@ Any one of these closes the gap; the first is the smallest and keeps the
 profile name as the fallback:
 
 - `SubprocessTerminalSpawnSpec` gains an optional `displayTitle` (or the handle
-  exposes the launched `argv`), and `create()` uses it for `info.title` when
+  exposes the launched `argv`), and `spawn()` uses it for `info.title` when
   present — falling back to `shell.name`. A provider that rewrites a launch
   states the program it started; every other launch keeps the profile name.
 - Alternatively, the controller derives the title from the effective program
@@ -71,11 +90,34 @@ profile name as the fallback:
 
 With either, this plugin deletes the limitation paragraph in
 [LIMITATIONS.md](LIMITATIONS.md) and the `WSL`-over-PowerShell title, for any
-provider that rewrites launches — not just WSL.
+provider that rewrites launches — not just WSL. The same limitation is stated
+as current fact in four places. Three go stale the day the proposal lands; the
+fourth is already out of step and needs the corrections above whenever it is
+next touched:
+
+- the GUI-terminal comment block in [`cordis.patch.yml`](../cordis.patch.yml);
+- the closing paragraph of "Why the terminal provider is app-level" in
+  [ARCHITECTURE.md](ARCHITECTURE.md);
+- R4's `残差` (residual) column in [REQUIREMENTS.zh.md](REQUIREMENTS.zh.md);
+- the `WSL` tab-title bullet under "Terminals" in
+  [LIMITATIONS.md](LIMITATIONS.md) — the paragraph named just above. It says
+  the controller titles a tab *before* the provider rewrites the launch, the
+  reverse of the ordering corrected at the top of this file, and it carries the
+  one-line `shellCandidates` workaround that drops the row's `shell` block.
 
 ## Workarounds until then
 
 - Double-click a tab's title to rename it (a shipped client feature; the
   controller's `rename` Remote API accepts 1–120 characters).
-- Add `shellCandidates` to the `terminal-controller` row in a user layer: a
-  manually selected shell is titled after itself.
+- Re-declare the `terminal-controller` row in a user layer with a non-empty
+  `shellCandidates`: a manually selected shell is titled after itself. A patch
+  config replaces the whole config rather than deep-merging it
+  (`packages/boot/app-boot/src/config-schema/document.ts`), so the override has
+  to carry this plugin's `shell` block verbatim — `path: wsl.exe`, `name: WSL`,
+  `args: []` — or the terminal stops being a distro terminal. Expect the menu
+  to grow the host shells discovery finds on the root provider, which receives
+  no directory: executables this terminal never starts (the second bullet of
+  the GUI-terminal comment in [`cordis.patch.yml`](../cordis.patch.yml)).
+  [LIMITATIONS.md](LIMITATIONS.md) still carries the older one-line form of
+  this tip, which drops the `shell` block; the version above is the one that
+  works.

package/examples/preset-wsl-session-sandbox.cordis.patch.yml

@@ -0,0 +1,178 @@
+# A profile-patch fragment for `$DSH_HOME/profiles/<name>/cordis.patch.yml`.
+# It is the plugin's ENTIRE `preset-wsl` row (a row's config is replaced whole,
+# never deep-merged) with `sessionSandbox: true` on the `wsl-shell` AND
+# `wsl-fs` plugins.
+#
+# Paste it in place of any existing `- id: preset-wsl` entry in that profile
+# layer, then restart the app. Regenerate it from the plugin's
+# `cordis.patch.yml` whenever the shipped preset changes.
+
+- id: preset-wsl
+  name: '@deepseek-ai/dsh-agent-preset'
+  config:
+    id: wsl
+    order: 2
+    plugins:
+      - id: wsl-env
+        name: cordis:group
+        group: true
+        isolate:
+          shell: true
+          fs: true
+        config:
+          # ── the WSL environment for this preset only ────────────────────
+          # No `cwd`: an empty default workdir means the distro user's home,
+          # asked of the distro itself. Pin a directory here to override it —
+          # a value that is right on one machine is wrong on every other.
+          #
+          # Commands run in one persistent systemd user scope per session
+          # (ADR 0001): a background dev server survives the command that
+          # started it, `/tmp` is the distro's real `/tmp`, and `ps` sees the
+          # session. This needs systemd as PID 1 (`[boot] systemd=true` in
+          # /etc/wsl.conf) and a lingering user manager (`loginctl
+          # enable-linger <user>`); the preflight refuses with those remedies
+          # when one is missing. Set `sessionSandbox: false` for the old
+          # per-command shape. Bubblewrap is still required for the mount
+          # profile; without it the providers fail closed.
+          - id: wsl-shell
+            name: 'dsh-plugin-wsl-env'
+            config:
+              distro: ''
+              loginShell: true
+              timeoutMs: 120000
+              maxTimeoutMs: 600000
+              sessionSandbox: true
+              agentBackend: auto
+          - id: wsl-fs
+            name: 'dsh-plugin-wsl-env/fs'
+            config:
+              distro: ''
+              restrictToDistro: true
+              # agent (the default): reads/writes/identities run inside the
+              # distro over the resident agent (lib/fs-substrate.js) —
+              # native symlinks and mode bits, the write guard survives to
+              # publication, and confined mutations are kernel-enforced.
+              # share: the opt-out — the Windows-side host fs stack over
+              # the 9p share.
+              substrate: agent
+              # Confined writes ride the session runtime (ADR 0001), so they
+              # share the command's real /tmp and workspace mounts.
+              sessionSandbox: true
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: You are a coding agent powered by the {{model}} model.
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: false
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: true
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+          - id: tool-schedule
+            name: '@deepseek-ai/dsh-tool-schedule'
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: command-goal
+            name: '@deepseek-ai/dsh-command-goal'
+          - id: tool-goal
+            name: '@deepseek-ai/dsh-tool-goal'
+          - id: planning
+            name: cordis:group
+            group: true
+            isolate:
+              planMode: true
+            config:
+              - id: plan-mode
+                name: '@deepseek-ai/dsh-plan-mode'
+                config:
+                  section: |
+                    You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+                    Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+                    The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+                    Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+                    Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+                    When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 8192
+                  headChars: 4096
+                  tailChars: 1024
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+          - id: tool-plugin-manager
+            name: '@deepseek-ai/dsh-plugin-manager/tools'
+            disabled: true
+          - id: tool-plugin-market
+            name: '@deepseek-ai/dsh-plugin-market/tools'
+            disabled: true

package/lib/agent-protocol.d.ts

@@ -14,7 +14,7 @@
  * @module dsh-plugin-wsl/agent-protocol
  */
 /** The protocol version this host side speaks; the agent must match. */
-export declare const PROTOCOL_VERSION = 4;
+export declare const PROTOCOL_VERSION = 5;
 /**
  * Upper bound on one `read` op's payload, set by the HOST looping over windowed
  * requests. Keeping each frame's decoded payload here means the agent's RES
@@ -127,15 +127,21 @@ export interface FsFrameRequest {
  */
 export declare function encodeFsFrame({ id, op, args, timeoutMs }: FsFrameRequest): string[];
 /**
- * `HELLO|name|version|digest` — `digest` is the sha256 of the script file the
- * agent is executing (empty when it could not hash it); the host compares it
- * against its own shipped copy.
+ * `HELLO|name|version|digest|pid` — `digest` is the sha256 of the script file
+ * the agent is executing (empty when it could not hash it); the host compares
+ * it against its own shipped copy. `pid` is the agent shell's PID inside the
+ * distro, present from protocol 5 on: the host uses it to deliver an
+ * out-of-band `USR1` cancellation while the agent is blocked in `wait`, which
+ * the serial stdin loop cannot do by frame. It is absent when the agent
+ * itself runs inside a PID namespace (the confined resident), where that PID
+ * is not addressable from a second `wsl.exe`.
  */
 export interface HelloMessage {
     type: "hello";
     name: string;
     version: number;
     digest: string;
+    pid?: number;
 }
 /** `PONG` — the liveness answer to `PING`. */
 export interface PongMessage {

package/lib/agent-protocol.js

@@ -14,7 +14,7 @@
  * @module dsh-plugin-wsl/agent-protocol
  */
 /** The protocol version this host side speaks; the agent must match. */
-export const PROTOCOL_VERSION = 4;
+export const PROTOCOL_VERSION = 5;
 /**
  * Upper bound on one `read` op's payload, set by the HOST looping over windowed
  * requests. Keeping each frame's decoded payload here means the agent's RES
@@ -124,8 +124,15 @@ export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
  */
 export function parseAgentLine(line) {
     if (line.startsWith("HELLO|")) {
-        const [, name, version, digest] = line.split("|");
-        return { type: "hello", name: name ?? "", version: Number(version), digest: digest ?? "" };
+        const [, name, version, digest, pid] = line.split("|");
+        const agentPid = Number(pid);
+        return {
+            type: "hello",
+            name: name ?? "",
+            version: Number(version),
+            digest: digest ?? "",
+            ...(Number.isSafeInteger(agentPid) && agentPid > 0 ? { pid: agentPid } : {}),
+        };
     }
     if (line === "PONG")
         return { type: "pong" };