deepseek-coordination 0.1.1 → 0.1.5

package/README.md

@@ -68,15 +68,24 @@ deepseek-coordination/
 ├─ src/host/docs/os-spec.md        full specification: contracts, error codes, golden matrix
 ├─ src/host/docs/permission-model.md  the authorization model and its residual risk
 ├─ src/plugin/index.js             host plugin: registers the `dsh_os` tool
+├─ src/plugin/invoke.js            shared invocation layer: artefact/edition resolution, spawn, envelope parsing
+├─ src/plugin/settings.js          settings service + the panel's two HTTP routes (`/api/dsh-os/*`)
+├─ src/plugin/takeover.js          `tools/execute` interception: answers the built-in read/write/edit/pwsh through dsh-os
+├─ src/plugin/workflow.js          intent-first workflow: the `workflow_plan` tool, its phase gates and its prompt section
+├─ client.js                       browser half: the `dsh.client` artifact that renders the settings panel
 ├─ src/permission/index.js         consent delegate: the only writer of permission.json, registers five `os_permission_*` tools
 ├─ tools/build.ps1                 assembles the three generated scripts; `-Check` fails on drift
 ├─ tools/parse-check.ps1           parse-checks each module under the runtime that will execute it, and reports non-ASCII bytes and a BOM
 ├─ tools/json-field.mjs            reads one field of an envelope by dotted path (used by the shell suites; `sed` cannot see into a nested object)
-├─ tools/verify-bundle.mjs         verifies the loader's resolution contract (10 cases)
-├─ tools/verify-plugin-load.mjs    runs the real `apply()` path (13 cases)
+├─ tools/verify-bundle.mjs         verifies the loader's resolution contract (16 cases)
+├─ tools/verify-plugin-load.mjs    runs the real `apply()` path, including the workflow state machine (30 cases)
+├─ tools/verify-package.mjs        packs the package and asserts every runtime-resolved file ships (21 cases)
 ├─ tools/verify-editions.mjs       proves both PowerShell artefacts are reachable (14 cases)
-├─ tests/                          golden (Windows/POSIX/desktop injection), table conformance, encoding, plugin, permission suites
+├─ tools/probe-pipeline.mjs        drives the interception end to end against a stubbed verb layer (23 cases)
+├─ tests/                          golden (Windows/POSIX/desktop injection), table conformance, encoding, plugin, permission, takeover, workflow suites
 │  ├─ conformance.ps1              command.txt and spec/verbs.tsv must describe the same surface (5 cases)
+│  ├─ takeover.test.mjs            byte-level format preservation, read windowing, eligibility (41 cases)
+│  ├─ workflow.test.mjs            phase gates, the user's choice, and the KV-cache invariant (30 cases)
 │  ├─ smoke-desktop-sh.sh          what the POSIX desktop verbs actually inject (52 cases)
 │  └─ fake-xdotool, fake-wmctrl    recording stand-ins, so the desktop verbs can be verified with no X server
 └─ permission.json                 authorization data (an empty file in the repository; that is the initial state)
@@ -115,8 +124,13 @@ precisely the class of encoding fault this project exists to remove.
 
 ## Getting started
 
-Not yet published to npm, so use it from source:
+Published on npm, so a DSH profile can install it as a bundle:
 
+```console
+dsh plugin install deepseek-coordination
+```
+
+Or work from source:
 ```console
 git clone https://github.com/eloyhere/deepseek-coordination.git
 cd deepseek-coordination
@@ -145,11 +159,25 @@ because batch-file argument handling is itself a source of quoting bugs.
 ### Using it from the harness
 
 `package.json` declares `dsh.bundle.patch`, so the package installs into a DSH profile as a bundle and
-registers one model-facing tool:
+inserts five rows:
+
+| Row | Entry | What it does |
+|---|---|---|
+| `dsh-os` | `.` | registers the `dsh_os` tool |
+| `dsh-os-settings` | `./settings` | the settings the panel edits, plus its two HTTP routes |
+| `dsh-os-takeover` | `./takeover` | answers the built-in `read`/`write`/`edit`/`pwsh` through dsh-os while enabled |
+| `dsh-os-permission` | `./permission` | the consent delegate, the only writer of `permission.json` |
+| `dsh-os-workflow` | `./workflow` | the intent-first workflow tool and its system-prompt section |
+
+The rows must name **different module specifiers**: `name` is resolved as a package specifier, and giving
+two rows the bare package name loads the same module twice, which throws `tool "dsh_os" is already
+registered` and aborts the whole entry. That is why the subpath exports exist.
 
 | Tool | Purpose |
 |---|---|
 | `dsh_os` | Run one verb of the surface and return its JSON envelope verbatim |
+| `os_permission_*` | Read, grant, revoke and audit durable authorization decisions |
+| `workflow_plan` | Run one phase of the intent-first workflow (see [The workflow](#the-workflow)) |
 
 One tool rather than one per verb, for three reasons: the verb table is the contract and lives in
 `src/host/spec/verbs.tsv`, so no schema needs regenerating when a verb is added; an agent discovers the
@@ -165,6 +193,48 @@ shape, so there is no second contract to drift from the script's.
 The implementation is spawned by absolute path with an argv array, never through a shell string, so a
 value containing spaces stays one value.
 
+### Taking over the built-in operations
+
+`dsh_os` is a tool an agent has to be *told* to use, and it never is: the built-in `read`/`write`/`edit`/
+`pwsh` tools are right there, they overlap almost completely, and nothing in the prompt prefers one over
+the other. The guarantees this project exists for therefore stay unexercised — the plugin is installed
+and imperceptible.
+
+**Takeover** removes the choice. Enable it in **Settings → DSH OS** and the built-in calls are answered
+by the same machinery, whether or not the agent cooperates. Per-tool switches let you redirect only
+`write`, or only `edit`, and leave the rest alone.
+
+It works through the `tools/execute` around-dispatch waterfall: a handler returns `{ value }` without
+calling `next()`, and that value is then validated against the **built-in** tool's own `output.schema`
+and rendered by the **built-in** `output.render`. The model-facing text, the diff cards and the
+presentation metadata are therefore unchanged; only the byte-level source of the value is.
+
+**What it does not take over, and why:**
+
+* `glob` and `grep`. This surface has no content-search verb at all — `file search` matches *names* — so
+  `grep`'s `lineNumber`/`line` cannot be produced, and glob's ignore rules and mtime ordering have no
+  equivalent. Redirecting them would silently return a different result set.
+* Background commands and sandbox escalations. A background call's result is a harness job id, which
+  this surface cannot mint, and `sandbox_permissions` is the harness's own approval seam.
+* Relative paths. The built-in tools resolve them against the session workspace through `ctx.fs`; this
+  plugin has no equivalent resolution, and guessing the process working directory would read a different
+  file than the one named.
+
+**Two properties are deliberately given up, and you should know them before enabling it:**
+
+1. **The filesystem sandbox does not bound a redirected call.** The built-in write path goes through
+   `ctx.fs`, which is where the sandbox policy and the read-before-write observation guard live. A
+   redirected write runs the verb directly, so dsh-os's own protected-path check is what remains. This
+   is a real reduction in defence, not a detail.
+2. **The reported text and the bytes on disk can differ.** With the default *follow the target* format, a
+   CRLF file stays CRLF and a BOM stays a BOM, while `value.after` is normalised LF text — which is what
+   the built-in `read` would show and what the diff card compares. Choose *same as built-in* if you would
+   rather the takeover change nothing about the bytes.
+
+Every redirected call falls back to the built-in implementation on any failure, so takeover can change
+how a result is produced but never whether the caller gets one. The panel's activity feed shows what was
+actually taken over and why anything fell back.
+
 **Choosing the PowerShell edition.** The default remains the 5.1 artefact (`bin/dsh-os.ps1`),
 **deliberately unchanged**: a deployment that already works should not change behaviour underneath
 itself because a plugin was upgraded. To select the 7.6 artefact (`bin/dsh-os7.ps1`):
@@ -179,13 +249,177 @@ install locations, because `pwsh` is not always on `PATH` — it is not on this
 environment, while 7.6.6 is plainly installed in the standard location.
 
 > [!IMPORTANT]
-> **The bundle now loads in a live desktop session.** The plugin has since been installed into the
-> active profile, and the six tools it registers — `dsh_os` plus the five `os_permission_*` tools —
+> **The bundle now loads in a live desktop session.** The plugin is installed into the active profile as
+> a published npm package, and the tools it registers — `dsh_os` plus the five `os_permission_*` tools —
 > are present and callable in a running session. What is still **not** proven is the part that
 > `tools/verify-bundle.mjs` cannot cover: that the *harness's own loader* composes the bundle by the
 > same contract the verifier checks, rather than by a shortcut that happens to work here. The
 > verifier remains the evidence; the live session is corroboration.
 
+### The workflow
+
+Every other row in this package makes an OS call **correct**. This one makes a *request* decided before it
+is executed. The failure mode it removes is a request that was never a specification: the model starts
+editing files, and the divergence is discovered at review — after the tokens have been spent.
+
+`dsh-os-workflow` registers one tool, `workflow_plan`, and one system-prompt section.
+
+```
+intake -> plan -> choose -> run -> done
+```
+
+| Phase | Action | What it establishes |
+|---|---|---|
+| intake | `start` | the prompt **verbatim**, plus 1–3 questions about intent *or* the assumptions being made |
+| plan | `plan` | the approach and process, **at least two** alternatives with pros and cons, the criteria, and a recommendation |
+| choose | `choose` | **the user's decision**, taken through `ctx.userQuestions` inside the call |
+| run | `run` | execution, its steps, and — in the same call — the outcome that closes the workflow |
+| — | `note` | a remark or a decision made during execution |
+| — | `checkpoint` | folds the record into one file and reports a summary |
+| — | `status`, `reset` | read the state; discard it and start again |
+
+> [!IMPORTANT]
+> **The tool is named `workflow_plan`, not `workflow`, and the reason is a real collision.** A host
+> composition already exposes a built-in `workflow` tool — the JavaScript multi-agent orchestrator from
+> `@deepseek-ai/dsh-tool-workflow`. Two tools sharing one name in one scope collide: the second
+> registration aborts, or both resolve and the model is offered two unrelated tools under one name. Since
+> this row's tool lives in the host plane while `workflow` is mounted per agent preset, no test in this
+> repository would have caught it; it was caught by reading the live tool catalog. `_plan` also says what
+> this tool is: the planning half of a workflow.
+
+**The gates are real.** A phase whose entry has not been recorded is refused, and the refusal names the
+phase that must run first. `choose` cannot be answered by the model: the question goes to the user through
+the same seam `ask_user_question` uses, and nothing else can move the workflow into `run`.
+
+**Four calls, one question.** The unavoidable path is `start` → `plan` → `choose` → `run`. It was
+originally eight calls and two questions, and the difference is three deliberate fusions — each of which
+removes a round-trip without removing a decision:
+
+* **design and options are one call**, because they are one decision. This is the QOC shape (Questions,
+  Options, Criteria) and the ADR shape (Context, Decision, Consequences): a decision record holds the
+  alternatives it was chosen between and the criteria it was judged against. Splitting them made the
+  second call re-derive the first and made the user read the same architecture twice.
+* **a clear request costs zero questions.** `start` accepts `assumptions` instead of `questions`, so an
+  unambiguous prompt is not interrupted — and the assumption is on record where the user can correct it,
+  which is cheaper than the question it replaced. The evidence for *minimal, relevant* questions over
+  interrogation is the Ask-to-Act line of work ([arXiv:2504.00907](https://arxiv.org/abs/2504.00907)).
+* **a single-step execution closes in the same call it opens.** Passing `outcome` to `run` finishes the
+  workflow; only multi-step work needs a second call.
+
+**The compression is the other half.** A plan narrated into the conversation is re-sent with every later
+step, which is what makes a short task expensive. So it never enters the conversation: each phase writes a
+real document and returns a line — phase, summary, file path, one next call. `tests/workflow.test.mjs`
+measures it and holds every phase envelope under 2000 characters; in the current build the four calls of a
+full workflow total about 1.8 kB, roughly 500 tokens, for a plan document measured in kilobytes. This shape
+is measured, not stylistic: pruning plus summarisation improves completion while cutting tokens and runtime
+([Less Context, Better Agents](https://export.arxiv.org/pdf/2608.16370)), and a planner/executor split
+matches interleaved reasoning at a fraction of the token cost
+([Plan Once, Ground Locally](https://zenodo.org/records/22904595)).
+
+**Where the cost goes**, stated as complexity because that is what it is:
+
+| Path | Cost |
+|---|---|
+| reading state | once per workflow call, cached on the file's mtime — and **never** on a model step, because the prompt section reads no state at all |
+| a phase transition | one atomic state write; the first version wrote it three times per action |
+| a note during execution | one `appendFileSync` append, O(1), bounded by compaction — not the read-push-rewrite that is O(n²) over a workflow |
+| the prompt section | a **constant**: no read, no lookup, no formatting, identical at every phase of every workflow |
+
+### The KV cache effect, which is why the prompt section is a constant
+
+The section this row registers into the system prompt is a **constant string**. That is not tidiness; it is
+the design, and the reason is that the prompt is the worst possible place for anything that moves.
+
+**What this package measured.** `tools/measure-cache.mjs` drives the real endpoint
+(`deepseek-flash`, `max_tokens: 1`, one request per variant after one warm request on the same lineage) and
+reports `cache_read_input_tokens` for the shapes this plugin actually produces. Measured twice, with
+identical results:
+
+| Shape | Cache read | Total input | Hit |
+|---|---:|---:|---:|
+| an unchanged request (control) | 5,632 | 5,780 | 97.4% |
+| appending a user message | 5,632 | 5,784 | 97.4% |
+| appending a tool result | 5,632 | 5,853 | 96.2% |
+| **one workflow: four appended calls** | 5,632 → 5,888 | ~5,900 each | **96.6% mean** |
+
+So the row's own shape is measured warm: four calls, 23,040 cached tokens, every call above 96%.
+
+**What this package did NOT manage to measure, and will not claim.** The experiment also tries the
+counterfactual — rewrite the leading system prompt, edit a tool description, reorder two tools — and those
+readings are **not reproducible**: the first run reported 0.0% for all of them, the second reported 97%. The
+provider documents the reason and it is worth knowing: it persists a **common prefix detected across
+requests**, so by the second run the repeated identical prefixes had been learned and a mutation still
+matched. Per-variant A/B isolation on a shared account cannot settle the mutation side, so
+`tools/measure-cache.mjs` asserts only the append side, which is stable, and prints the rest as
+observations rather than claims.
+
+**The counterfactual rests on independent evidence instead**, and it is strong:
+
+* the provider's own rule is that a cache hit requires a request to **fully match a persisted cache prefix
+  unit**, and the system prompt sits before the tool catalog and the entire history
+  ([Context Caching](https://api-docs.deepseek.com/guides/kv_cache/));
+* a ten-variant experiment on the same endpoint found appending a message kept a **98.7%** hit while adding
+  one line at the **end** of the system prompt produced **0.0%**
+  ([prefix-stability chapter](https://github.com/diguike/book-deepseek-harness/blob/main/book/11-prefix-stability.md));
+* the harness itself paid for this lesson: the sandbox policy used to live in the system prompt, and one
+  permission switch dropped cache reads from **~14,700 tokens to 256**. The fix was to move the changing
+  fact out of the prompt into the message sequence
+  ([DSH agent note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.md)).
+
+**The first version of this row rendered the current phase into that section**, so a four-call workflow
+re-wrote the system prompt three times. Whether or not the provider happens to forgive that on a given day,
+the row has no business depending on it — so the fix is structural, not cosmetic:
+
+* the section is a constant, so this row's **cache effect is `prefix-stable`**: zero prompt changes per
+  workflow, asserted by `tests/workflow.test.mjs` against the registered text at every phase, and again
+  after deleting `state.json` outright;
+* the phase and the **one next call** travel in the `workflow_plan` tool's own result instead — appended
+  history, measured above at 96–97%;
+* a step taken out of order is refused, and the refusal names the phase to record first, so the model can
+  recover from a stale plan without the prompt having told it anything;
+* the tool **description** carries the discovery text. It lives in the tool catalog: inside the cached
+  prefix, sent once, and unchanged for the life of the session.
+
+> [!IMPORTANT]
+> **The consequence a reader should draw for their own plugins.** Anything that changes per step — the
+> time, the current directory, a branch, a permission, a phase — must not be written into a prompt section.
+> This harness gives that content its own path: register it with `ctx.systemPrompt.context()` and it is
+> delivered as an appended user message, re-projected only when it changes. A section is for text that is
+> stable for the session.
+
+**Where the state lives.** `$DSH_HOME/dsh-os/workflows/<session>/`, beside the settings document and for
+the same reason: the package directory is replaced on upgrade, and the workspace belongs to the user.
+`state.json` is the compact record; every other file is the detail. A finished workflow is archived rather
+than overwritten, so the next one starts clean and the last one stays readable.
+
+```
+state.json          the compact record: phase, intent, decisions, steps, artifact paths
+journal.jsonl       append-only: notes and steps, bounded, folded in by a checkpoint
+01-intent.md        the prompt verbatim, then the questions and answers (or the assumptions)
+02-plan.md          approach and process, alternatives with pros and cons, criteria, the decision
+03-execution.md     chosen option, goal, steps, files in scope, constraints
+04-outcome.md       what was delivered, and any step left open
+05-checkpoint.md    the fold: everything decided so far, written when a compaction is wanted
+```
+
+**What is configured.** `workflowRoot` moves the directory; `autoCompact` (default `true`) controls
+whether a checkpoint reports the compaction the engine may perform, and `maxCheckpoints` bounds it. The
+structural half — detail to disk, one line back — is **not** configurable, because it is the reason the
+feature saves anything.
+
+> [!WARNING]
+> **This row asks the user questions, so the deployment must be able to answer them.** It injects
+> `userQuestions`; a host without it registers nothing rather than registering a tool that would fail on
+> its second call. Two calls block on a human: `start` when questions are given, and `choose` always.
+
+> [!NOTE]
+> **What this row does not do: it does not invoke the engine's compaction service.** `ctx.compaction`
+> exists, and calling it from here would mean constructing a session-shaped context whose contract is not
+> published — a guess dressed up as a feature. What the plugin does instead is deterministic and
+> inspectable: the detail leaves the conversation for a file, and `checkpoint` records the boundary where a
+> compaction is safe. That is why the compression is measurable by `tests/workflow.test.mjs` rather than
+> merely asserted.
+
 ---
 
 ## JSON contract
@@ -546,7 +780,7 @@ been closed by three verifiers, and they found one real defect:
 | Verifier | What it proves | Cases |
 |---|---|---|
 | `tools/verify-bundle.mjs` | the loader's **resolution** contract: the manifest header, the patch file, every row resolving from a profile-style `node_modules`, every resolved module exporting the Cordis shape the loader calls (`apply`/`inject`/`name`), the two rows resolving to **different** modules (a shared specifier registers the same tool twice and aborts the whole entry), and the version gate | 10 |
-| `tools/verify-plugin-load.mjs` | the real `apply()` path: the host plugin registers `dsh_os` with a parameters schema whose **root type is `object`**, the permission plugin registers its five tools, and **the registered handler really does spawn the script** and return a real envelope (`selfcheck` → ok, `verbCount` 86); a mutating verb without `allow` is refused with a typed `E_PERMISSION` rather than throwing | 13 |
+| `tools/verify-plugin-load.mjs` | the real `apply()` path: the host plugin registers `dsh_os` with a parameters schema whose **root type is `object`**, the permission plugin registers its five tools, and **the registered handler really does spawn the script** and return a real envelope (`selfcheck` → ok, `verbCount` 86); a mutating verb without `allow` is refused with a typed `E_PERMISSION` rather than throwing. It also covers the workflow row, whose failure would otherwise be silent: the tool and its prompt section **are** registered, and `start → plan → choose → run` runs through the real handler with its gates intact | 30 |
 | `tools/verify-editions.mjs` | edition selection: the default is still PowerShell 5.1; `powershellEdition: '7.6'` and `DSH_OS_POWERSHELL_EDITION` select the 7.6 artefact; `'auto'` uses 7.6 only when the artefact and a working `pwsh` are present **together**; configuration beats the environment; an explicit `scriptPath` disables the choice. `-ExecutionPolicy` is passed only to the 5.1 executable | 14 |
 
 The bundle verifier links the package into a throwaway profile sandbox by junction, so resolution
@@ -572,7 +806,7 @@ by a **later** case.
 
 That defect is **fixed**: the parser case in `tests/golden.ps1` now creates its own fixture
 (`$fixtureDir = Join-Path $sandbox 'parser\verify'`, then `New-Item` and `Set-Content`) and asserts
-against it. The current measurement is **49 passed, 0 failed**.
+against it. The current measurement is **50 passed, 0 failed**.
 
 ### Two real POSIX defects found by `tests/smoke-desktop-sh.sh`
 
@@ -638,10 +872,19 @@ stand-in tools exposed both:
   no acceptance step depends on it. (The plugin's *installation* path does: the package manager
   resolves the repository with `git ls-remote`, so a machine where the harness cannot find `git` on
   `PATH` cannot install the bundle.)
+* **PowerShell 7.6 is exercised, but not across the whole surface.** The 7.6 artefact definitely runs:
+  driving the plugin's real `resolveInvocation` path with `DSH_OS_POWERSHELL_EDITION=7.6` selects
+  `bin/dsh-os7.ps1` and the runtime that answers is **PowerShell 7.6.6**, while the default stays on
+  5.1.19041.3031 — that is what `tools/verify-editions.mjs` asserts and what the 14 cases measured here
+  confirm. What has *not* been done is a run of every verb against `dsh-os7.ps1`; its fidelity as a port
+  rests on the identical 82-verb dispatch sets, a per-module function-name comparison and the window
+  group's golden cases. That is a real gap in the evidence, not a claim of full parity.
 
 ### What is not proven
 
-* That the DSH loader composes this bundle and makes `dsh_os` appear in an active session.
+* That the loader composes the bundle **by the contract `tools/verify-bundle.mjs` checks**, rather than
+  by a path that happens to work on this machine. The weaker claim — that `dsh_os` and the five
+  `os_permission_*` tools appear and are callable in an active session — has since been observed.
 * Complete verb parity between the two platforms — in neither direction.
 * The enforcement effect of layer A on a machine where the harness and the delegate share one identity
   — by construction that case degrades to layer B.
@@ -665,15 +908,29 @@ npm run test:all        # runs everything below, in order
 |---|---|---|---|
 | Table conformance | `powershell -File tests/conformance.ps1` | 5 | **5 passed, 0 failed** |
 | Encoding contracts | `powershell -File tests/encoding.ps1` | 32 build modules | **all contracts hold** |
-| Windows golden | `powershell -File tests/golden.ps1` | 49 | **49 passed, 0 failed** |
+| Windows golden | `powershell -File tests/golden.ps1` | 50 | **50 passed, 0 failed** |
 | POSIX golden | `bash tests/golden-sh.sh` | 116 | **116 passed, 0 failed** |
 | POSIX desktop injection | `bash tests/smoke-desktop-sh.sh` | 52 | **52 passed, 0 failed** |
 | Plugin | `node tests/plugin.test.mjs` | 13 | **13 passed, 0 failed** |
+| Takeover interceptions | `node tests/takeover.test.mjs` | 41 | **41 passed, 0 failed** |
 | Permission delegate | `node tests/permission.test.mjs` | 18 | **18 passed, 0 failed** |
-| Bundle resolution | `node tools/verify-bundle.mjs` | 10 | **10 passed, 0 failed** |
-| Plugin load | `node tools/verify-plugin-load.mjs` | 13 | **13 passed, 0 failed** |
+| Workflow | `node tests/workflow.test.mjs` | 30 | **30 passed, 0 failed** |
+| Bundle resolution | `node tools/verify-bundle.mjs` | 16 | **16 passed, 0 failed** |
+| Package completeness | `node tools/verify-package.mjs` | 21 | **21 passed, 0 failed** |
+| Plugin load | `node tools/verify-plugin-load.mjs` | 30 | **30 passed, 0 failed** |
 | Edition selection | `node tools/verify-editions.mjs` | 14 | **14 passed, 0 failed** |
 | Build drift | `powershell -File tools/build.ps1 -Check` | 3 artefacts | **no drift** |
+| Prefix cache (`npm run measure:cache`) | `node tools/measure-cache.mjs` | 2 claims | **PASS — 96.6% mean hit over four workflow calls** |
+
+`measure:cache` is **not** part of `test:all`: it calls the real provider, so it needs
+`DEEPSEEK_API_KEY` (read from `$DSH_HOME/.credentials.yaml`) and it costs tokens. It exits non-zero only
+when a measured claim does not hold.
+
+> [!NOTE]
+> **`test:desktop` needs `bash`, and this machine has none.** `npm run test:all` therefore ends with
+> `'bash' is not recognized` on a Windows host without Git Bash or WSL on `PATH`. That is an environment
+> gap in the runner, not a failing assertion: every suite above it ran and passed in the same invocation.
+> The POSIX suites remain unverified here for the same reason they always were — they need a POSIX host.
 
 ### Conformance of the two tables
 
@@ -812,7 +1069,7 @@ Copyright (c) 2026 Eloy Kim
 
 The licence file is pure ASCII, LF-terminated and BOM-free, consistent with the rest of the
 repository's encoding contracts. One earlier description needs correcting: it is **not** listed in
-`package.json`'s `files` whitelist (which has 14 entries; it includes `src/host/bin/dsh-os7.ps1` but
+`package.json`'s `files` whitelist (which has 20 entries; it includes `src/host/bin/dsh-os7.ps1` but
 neither `LICENSE` nor `README.zh-CN.md`), so the file stays in a checkout but is not distributed with
 the published package.