@twinsearth/w2m-dsh-plugin 0.59.0 → 1.0.1

package/CHANGELOG.md

@@ -1,9 +1,246 @@
 # Changelog
 
-All notable changes to this project are documented here. The format follows
+All notable changes to this project are documented here.
+
+## [1.0.1] — 2026-10-16
+
+**The first stable release. Three defects fixed, two of them mine and one of them published 56 times.**
+
+### The command allow-list could not admit the interpreter DSH itself runs on
+
+Twelve end-to-end tests failed with `COMMAND_EXECUTABLE_PATH_MISMATCH`, and **the refusal was correct** —
+the identity check was reading the wrong machine.
+
+    bundled node : E:\DS\resources\runtime\primary-runtime\dependencies\node\bin\node.exe
+    PATH         : E:\Unity3D\Tuanjie Cowork\cli\bin\win32-x64\node.exe      <- a different program
+    PATH contains the bundled directory : False
+
+The tests dispatch `[process.execPath, '-e', …]` against an allow-list entry of the bare name `node`. **DSH runs
+on the bundled interpreter and does not put its directory on PATH**, so the bare name resolved to an unrelated
+`node.exe` shipped by another application, and an absolute path to the bundled copy was refused as "a different
+file".
+
+**Fixed by answering the right question.** `resolveCommand` still keeps PATH ahead of the bundled tree — a test
+guards that precedence, and it is about *which file a name means*. The new `bundledExecutable()` answers a
+different question: *is this path the bundled copy of that tool?* **The bundled copy of a tool is that tool**, so
+identity holds, and **nothing is weakened**: it only ever returns files under `<deps>`, so
+`E:\Temp\evil\node.exe` is still refused.
+
+**The runtime is now discovered rather than assumed.** `dshDependenciesDir()` tried exactly one path,
+`$DSH_HOME/dsh-runtimes/<runtime>/dependencies`, which stopped existing when the application moved its runtime
+inside the bundle. It now tries the explicit override, then that documented layout, then **the directory implied
+by `process.execPath`** — a bundled interpreter lives at `<deps>/node/bin/node`, so its own path states where
+`<deps>` is. **That cannot go stale when the installation moves again.**
+
+### 56 of 66 release scripts published v0.1.3's commit message under an unrelated title
+
+Found because a test plan written against v0.60.0 reported its release notes as "highly duplicated" with several
+earlier releases. **The scripts state the right intention and then read the wrong file:**
+
+    /** The release notes reuse the commit message */
+    const NOTES = fs.readFileSync('…\\commit-0103b.txt', 'utf8');          // v0.1.3's message
+    name: 'v0.60.0 — approval index, fleet sync, service health, tiered storage',   // hardcoded
+
+`scripts/github-release.mjs` **derives both fields from the repository's own record** — the title from the commit
+subject, the body from the CHANGELOG entry — **so neither can be copied by accident.** It refuses to publish a
+version with no CHANGELOG entry, and reads the release back after writing. **The five most-read releases
+(v0.60.0, v0.59.0, v0.58.0, v0.57.1, v0.57.0) are corrected**, each verified by reading it back.
+
+### My mount-row advice broke the client twice, and §3.2 withdraws it
+
+**An installed plugin mounts itself**, from its own bundle patch — so adding a row to `cordis.patch.yml` inserts
+a **second** entry with the same `id`, and the client stops opening. Measured: **0 rows before install, exactly 1
+after, 2 with the manual row, 1 again once removed.**
+
+### Also in this release
+
+**Two client failures had one cause, and it was this repository's own advice: do not add a mount row.**
+
+### The plugin mounts itself
+
+`package.json` declares `dsh.bundle.patch`, so **the host composes an installed package from the patch shipped
+inside the package**. Nothing needs to be written into the profile — and writing it anyway inserts a **second**
+entry with the same `id`, which stops the client from opening.
+
+**Measured on a throwaway profile**, because the desktop profile cannot be previewed (`rejectElectronProfile`)
+and that is exactly where the failures happened:
+
+| State | `id: w2m` rows |
+|---|---|
+| profile created, plugin not installed | 0 |
+| **plugin installed, nothing else done** | **1** |
+| a correctly written `insert:` row added as well | **2** ← the failure |
+| that row removed | **1** |
+
+**The symptom is worth stating precisely, because it is not a crash:** the client does not open, there is no
+error message, and deleting `cordis.patch.yml` restores it immediately. **That is what pointed at configuration
+rather than code.**
+
+### §3.2, and why the old advice is withdrawn
+
+The section now leads with the rule — **install, and change nothing else** — then covers the three ways an edit
+goes wrong:
+
+* **`insert:` is an append.** Appending a row whose `id` already exists is the failure. To change configuration,
+  address the row the bundle patch created, as a non-insert patch.
+* **`Add-Content` onto this file is always wrong.** It is a YAML list; a fresh profile ships `[]`, and a second
+  document after it is a parse error. **The measured exception message is in the section**, because "failed to
+  parse overlay" alone sends people looking at the wrong thing.
+* **The desktop profile has no safe preview.** `--dump-config` composes and exits without starting anything, and
+  it is the right tool — but the CLI refuses the desktop profile, so for that one the only protection is writing
+  the row correctly. **Which in practice means not writing one.**
+
+### What I got wrong, since the section exists because of it
+
+I added the row to a live profile without a way to test it that did not involve the user's client, and the
+backup went with the profile when it was reset. **The cost was two client failures and a profile reset.**
+
+**I also formed a plausible hypothesis and disproved it before writing any of this**: I suspected
+`Add-Content -Encoding utf8` had written a mid-file BOM. Measured on PowerShell 5.1 — a 45-byte file with the
+BOM only at offset 0. **Not the cause, and recorded so it is not repeated.**
+
+**The experiment that settled it took one command and started nothing**: `dsh --profile <probe> --dump-config`,
+which prints the composed tree and exits. **It would have caught this before the first restart had I run it
+first.**
+
+**No code change and no test count change** — a documentation release. It is versioned rather than left
+unreleased because the incorrect procedure was published in `TROUBLESHOOTING.md`, and a user following it would
+break their client.
+
+**56 of 66 release scripts published the wrong text, and this is the fix that makes it impossible to repeat.**
+
+### The defect, found while checking someone else's test plan
+
+A test plan written against v0.60.0 reported that its GitHub release notes were *"highly duplicated"* with
+v0.59.0, v0.58.0 and several earlier releases, and concluded they were probably template-generated. **That
+conclusion was right and the cause was mine:**
+
+    // publish-0600-github.mjs
+    /** The release notes reuse the commit message: it already states the cause, the fix and the evidence. */
+    const NOTES = fs.readFileSync('E:\\GPT\\scripts\\commit-0103b.txt', 'utf8');   // <- v0.1.3's message
+    name: 'v0.60.0 — approval index, fleet sync, service health, tiered storage',      // <- hardcoded
+
+**The script states the right intention in its own comment and then reads the wrong file.** Measured: **56 of 66
+`publish-*-github.mjs` scripts read that same stale file, and 57 carry that same title** -- four roadmap
+keywords that describe none of those releases.
+
+### What I got wrong twice while investigating
+
+**First** I said the `health` module did not exist and that the test plan was testing a fiction. **It exists:**
+`src/agent/health.mjs`, whose own header records the macOS mistake and its fix
+(`darwin: ['/var/log', '/Library/Logs', '/tmp']`). **It was in the code and missing from my CHANGELOG, and I
+read the CHANGELOG as if it were the record.** The test plan was more accurate than my denial of it.
+
+**Second**, having been wrong, the honest correction is that the plan is right about `health` and wrong about
+three counts, which are now measured rather than quoted: **89 suites (not 82), 2352 tests (not 2228), 15
+pre-flight checks (not 12), and six aggregation verdicts (not nine)** -- `degraded`, `timeout` and
+`cancelled` do not exist, so the three rows testing them would report false failures.
+
+### The fix is a module, not another corrected copy
+
+`scripts/github-release.mjs` **derives both fields from the repository's own record**: the title from the commit
+subject, the body from the CHANGELOG entry for that version. **Neither is written by hand, so neither can be
+copied by accident** -- which was the actual failure mode, since each release was a copy of the previous script
+and the two constants that must change were the two easiest to forget.
+
+**It refuses to publish when the CHANGELOG has no entry for the version.** A release whose body cannot be derived
+is a release that would otherwise be published under the previous one's text, which is precisely what happened 56
+times. **It also reads back after writing and compares**, because `PATCH` returning 200 is not evidence that the
+field changed.
+
+Verified: a version with no CHANGELOG entry is refused (exit 1); a version with one yields the commit subject as
+its title and a 3024-character body (exit 0, dry run); the exported helpers split CHANGELOG sections correctly,
+return null for an unknown version, and import without side effects.
+
+**The token comes from `GITHUB_TOKEN` rather than being embedded**, which all 66 older scripts do.
+
+### The five most-read releases are corrected
+
+Titles and bodies rewritten from their own CHANGELOG entries, **each verified by reading the release back**
+rather than by trusting the response:
+
+| Release | Title now |
+|---|---|
+| v0.60.0 | `docs(troubleshooting) + feat(script): the lock rule, and an out-of-band session bound` |
+| v0.59.0 | `fix(bin): every published bin can be imported without killing the importing process` |
+| v0.58.0 | `feat(bridge): report what arrived instead of guessing what an image looks like` |
+| v0.57.1 | `docs(bridge): correct a comment that implied a sequence the file does not have` |
+| v0.57.0 | `feat(vision): an image path becomes text evidence, and the credential never touches argv` |
+
+Each was 2044 characters -- one identical body -- before the repair.
+
+**The remaining 51 are left as they are**, which is a decision rather than an oversight: they are old enough that
+nobody reads them, and the module means the next release is correct without anyone remembering to check.
+
+ format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.60.0] — 2026-10-16
+
+**Two things learned from a client that would not start, neither of which was a crash in this plugin.**
+
+### §3.1 in `TROUBLESHOOTING.md`: check the lock before you check the plugin
+
+A launch that leaves **no process at all** is a different failure from one that starts and reports something, and
+the existing §3 procedure will mislead anyone who skips that distinction — it assumes the application *ran*.
+
+**The mechanism is one function in `@deepseek-ai/dsh-desktop`'s `lib/main.js`:**
+
+```js
+function claimDesktopSingleInstance(application, focusOwner) {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit();          // no dialog, no error, no window
+    return false;
+  }
+```
+
+**A second launch is silently discarded while the first instance holds the lock.** Electron registers it against
+the *application*, not a directory — which is why the two natural remedies both fail, and why the section now says
+so before offering any plugin diagnosis:
+
+| What was tried | Why it did nothing |
+|---|---|
+| disable third-party plugins before restarting | the new process quits at the lock, before plugin loading |
+| reinstall the client (new folder, new exe) | a new directory does not release an application-scoped lock |
+
+**Deleting `~/.dsh` fixed it — not because anything in it was corrupt, but because the deletion took down the
+process still holding the lock.** The section now leads with the measurement that costs nothing:
+
+```powershell
+Get-Process -Name 'DeepSeek Harness' | Select-Object Id, StartTime
+```
+
+**Processes listed → it is the lock, end them and retry. Nothing listed → the failure really is pre-lock, and §3's
+procedure applies.** The deleted directory carried session history and profile configuration; **`Stop-Process`
+would have cost nothing.**
+
+### `scripts/session-retention.mjs`: the store is bounded, out-of-band, as DSH says it must be
+
+`@deepseek-ai/dsh-session-persistence`'s README, under *Known Limitations*:
+
+> **No deletion or retention API** — pruning stored sessions is **out-of-band backend maintenance**.
+
+**So this is not a workaround for a missing feature: the host states retention is the operator's job.** The
+measurement that motivated it is that **one session reached 18.03 MiB of an 18.07 MiB store**, nothing bounds it,
+and every start reads the store.
+
+Three refusals are built in, and each is a deliberate limit rather than an omission:
+
+* **The newest session of every workspace is never removed.** DSH writes to it, and *which* process is writing
+  cannot be checked reliably from outside — so the rule is the one that needs no knowledge of the running
+  process.
+* **`--apply` is required.** The default prints the plan and exits 0. **A tool that removes conversation history
+  shows what it will remove before it removes it.**
+* **A directory that is not a session is reported, not touched**, because the layout is read from the filesystem
+  rather than assumed.
+
+**Verified against the real store:** at a 256 MiB cap it reports *"under the cap — nothing to remove"*; at a
+1 MiB cap it plans two removals and leaves the 18 MiB live session alone.
+
+**No test count change** — both additions are a document and a script, and the script is exercised by hand against
+the store it bounds rather than by a fixture that would not resemble it.
+
 ## [0.59.0] — 2026-10-16
 
 **Every published bin can now be imported without killing the importing process — measured, not reasoned about.**

package/TROUBLESHOOTING.md

@@ -258,6 +258,162 @@ after removal, remove the `w2m` row from `cordis.patch.yml` by hand (§2) before
 **Not us.** If the failure is in a _different_ plugin's entry and this one is merely in the same
 profile, the loader reports the package name in the same line — read it before assuming it is ours.
 
+### 3.1 First rule: if a double-click produces NO process, it is not a plugin
+
+**This section's decision procedure below will mislead you if you skip this step.** It assumes the
+application *ran and reported something*. A launch that leaves **no process at all** — nothing in Task
+Manager, no window, no dialog — is a different failure, and the plugin is not the cause.
+
+**The mechanism**, read out of `@deepseek-ai/dsh-desktop`'s `lib/main.js`:
+
+```js
+function claimDesktopSingleInstance(application, focusOwner) {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit();          // no dialog, no error, no window
+    return false;
+  }
+  application.on("second-instance", focusOwner);
+  return true;
+}
+```
+
+**A second launch is silently discarded while the first instance holds the lock.** Electron registers that
+lock against the *application*, not against a directory, which is why the two most natural remedies both
+fail:
+
+| What you try | Why it does nothing |
+|---|---|
+| **Disable third-party plugins before restarting** | The new process never reaches plugin loading — it quits at the lock |
+| **Reinstall the client (new folder, new exe)** | A new directory does not release a lock registered against the application |
+
+**Check the lock before touching anything else:**
+
+```powershell
+# Windows
+Get-Process -Name 'DeepSeek Harness' | Select-Object Id, StartTime
+```
+
+```bash
+# macOS / Linux
+pgrep -fl "DeepSeek Harness"
+```
+
+* **Processes listed** → it is the lock, and the app is not broken. **End them and start again.** On
+  Windows: `Stop-Process -Name 'DeepSeek Harness' -Force`. Do **not** delete `~/.dsh`.
+* **Nothing listed** → the failure really is before the lock, and *then* §3's procedure below applies.
+
+**A measured case, so the cost is on record.** A restart after upgrading to **v0.58.0** produced no
+process. Disabling third-party plugins and reinstalling the client both changed nothing; **deleting the
+entire `~/.dsh` directory fixed it** — not because anything in that directory was corrupt, but because
+**the deletion took down the process still holding the lock**, and the next launch then became the first
+instance. **Killing that process is the smaller, safer step, and it is the one to try first.**
+
+**What this cost, stated plainly:** the deleted directory carried session history and profile
+configuration that no longer exists. **`Stop-Process` would have cost nothing.**
+
+### 3.2 Never add a mount row: an installed plugin mounts itself
+
+**This section exists because two client failures were caused by following advice that used to be in this
+repository.** A mount row in `cordis.patch.yml` is **not necessary, and adding one breaks the client.**
+
+**The plugin mounts itself when the package is installed.** The host composes an installed package from **the
+plugin's own bundle patch** — `package.json`'s `dsh.bundle.patch`, which points at the `cordis.patch.yml` shipped
+*inside this package*. Nothing has to be written into the profile.
+
+**Confirmed by experiment.** On a throwaway profile created from the shipped `web` template, `--dump-config`
+reports **exactly one** `w2m` row with the plugin installed and **nothing** added to the profile:
+
+```
+# == @twinsearth/w2m-dsh-plugin
+- id: w2m
+  name: '@twinsearth/w2m-dsh-plugin'
+  config:
+    rabbitUrl: ''
+    autoStartAgent: false
+```
+
+**Adding a row inserts a second entry with the same `id`:**
+
+```
+1260: # == @twinsearth/w2m-dsh-plugin                      <- automatic
+1261: - id: w2m
+
+1271: # == ...\profiles\<name>\cordis.patch.yml              <- the manual one
+1272: - id: w2m                                               <- SAME id, twice
+```
+
+**Two rows with one `id` is what made the client stop responding.** The symptom is not a crash and not an
+error message — **the client does not open at all.**
+
+#### The rule
+
+```bash
+# Install. That is the whole procedure.
+dsh plugin --profile <name> add @twinsearth/w2m-dsh-plugin@<version>
+```
+
+**Do not edit `cordis.patch.yml` for this plugin.** If you have already added a row, delete that row — **and
+delete the row, not the `~/.dsh` directory.**
+
+#### To change configuration, target the existing row
+
+**Do not insert.** Address the row that the bundle patch already created:
+
+```yaml
+- id: w2m                    # a non-insert patch: replaces fields on the existing entry
+  config:
+    autoStartAgent: true
+```
+
+**An `insert:` is an append.** Appending a row whose `id` already exists is the failure described above.
+
+#### `Add-Content` onto this file is always wrong
+
+It is a YAML **list**, so the file's root is a sequence:
+
+```
+Error: dsh: failed to parse overlay ...\cordis.patch.yml:
+YAMLException: end of the stream or a document separator is expected (6:1)
+
+  4 | []
+  6 | - insert:
+  -----^
+```
+
+`[]` is a complete document; a `- insert:` list after it is a second one. **Rewrite the file with a list root;
+never append to it.** A freshly created profile ships `[]`, so this bites on the first edit.
+
+#### Verify before you restart, when you can
+
+`--dump-config` **composes the configuration and exits without starting an application**, which makes it the
+safe way to check an edit:
+
+```bash
+dsh --profile <name> --dump-config      # then search the output for this package's name
+```
+
+**The desktop profile is the one case where this is unavailable.** The CLI refuses it
+(`rejectElectronProfile`): Desktop manages that profile exclusively. **So for the desktop profile there is no
+safe preview — the only protection is writing the row correctly, which in practice means not writing one at all,
+because the plugin mounts itself.**
+
+If you must test a row, **create a separate profile and try it there first**:
+
+```bash
+dsh probe --from-default-profile web --dump-config
+dsh plugin --profile probe add @twinsearth/w2m-dsh-plugin@<version>
+dsh --profile probe --dump-config        # count the rows naming this package: expect exactly one
+```
+
+**The measured sequence, so the expectation is on record:**
+
+| State | `id: w2m` rows |
+|---|---|
+| profile created, plugin not installed | 0 |
+| **plugin installed, nothing else done** | **1** |
+| a correct `insert:` row added as well | **2** ← the failure |
+| that row removed | **1** |
+
 ---
 
 ## 4. A machine is listed but never answers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.59.0",
+  "version": "1.0.1",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "0.59.0",
+  "version": "1.0.1",
   "description": "Cross-platform fleet execution between Windows and macOS: one DeepSeek Harness account, a Rabbit relay, and signed device identity. Ships four Agent Skills describing fleet dispatch, field-level memory acceptance, session references, and resource scheduling.",
   "license": "MIT",
   "keywords": [

package/src/agent/allowed-commands.mjs

@@ -58,7 +58,7 @@
 
 import { basename, extname } from 'node:path';
 
-import { hasPathSeparator, isRelativePath, resolveCommand, sameFile } from './resolve.mjs';
+import { bundledExecutable, hasPathSeparator, isRelativePath, resolveCommand, sameFile } from './resolve.mjs';
 
 /**
  * Parse `--allowed-commands`.
@@ -474,6 +474,24 @@ function executableIdentity(argv0, prefix0, options) {
     return { kind: 'no-match', detail: null };
   }
   if (sameFile(resolvedArgv, resolvedPrefix)) return { kind: 'match', detail: null };
+
+  /**
+   * Second identity path, and the one that matters on a machine where the bundled tree is not on PATH.
+   *
+   * A bare entry names a tool; **the bundled copy of that tool is that tool**, whether or not PATH happens to
+   * point at it. This is what admits `process.execPath` for the entry `node` without weakening anything: it
+   * **only ever** returns a file under `<deps>`, so `E:\Temp\evil\node.exe` is still refused, and it does not
+   * touch the search order, so `keeps PATH ahead of the bundled runtime` still holds.
+   *
+   * It also fixes a real case rather than a test-only one: **DSH runs on the bundled interpreter and does not
+   * put its directory on PATH**, so an allow-list entry of `node` could not be satisfied by the very interpreter
+   * the host executes.
+   */
+  if (!prefixIsPath && argvIsPath) {
+    const bundled = bundledExecutable(prefix0, options.env ?? process.env);
+    if (bundled !== null && sameFile(argv0, bundled)) return { kind: 'match', detail: null };
+  }
+
   return {
     kind: 'path-mismatch',
     detail:

package/src/agent/resolve.mjs

@@ -18,7 +18,7 @@
 
 import { accessSync, constants, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { delimiter, isAbsolute, join } from 'node:path';
+import { basename, delimiter, dirname, isAbsolute, join } from 'node:path';
 
 /** The DSH runtime directory layout we fall back to (task-8, measured). */
 export const DSH_RUNTIME_RELATIVE = join('dsh-runtimes', 'dsh-primary-runtime', 'dependencies');
@@ -34,22 +34,72 @@ export function dshHome(env = process.env) {
   return explicit ?? join(homedir(), '.dsh');
 }
 
+/**
+ * The dependency directory implied by the interpreter that is running this code, or `null`.
+ *
+ * ## Why this exists, and why it is the first fallback
+ *
+ * `DSH_HOME/dsh-runtimes/<runtime>/dependencies` was the only layout this module knew. **The application moved
+ * and that assumption stopped holding**: the runtime now ships inside the bundle at
+ * `E:\DS\resources\runtime\primary-runtime\dependencies`, so `$DSH_HOME` contains no `dsh-runtimes/` at all, and
+ * every lookup that fell back to it found nothing.
+ *
+ * **The measurement that located it:** twelve end-to-end tests refused with `COMMAND_EXECUTABLE_PATH_MISMATCH`.
+ * They dispatch `[process.execPath, '-e', ...]` against an allow-list entry of the bare name `node`, so the
+ * identity check resolves `node` and compares the two files. `process.execPath` is the **bundled** interpreter --
+ * `...\dependencies\node\bin\node.exe` -- while the bare name resolved to whatever PATH held. Two different
+ * files, so the refusal was correct and the lookup was wrong.
+ *
+ * **So the fix is discovery rather than another hardcoded path**: a bundled interpreter lives at
+ * `<deps>/node/bin/node`, which means its own path *states* where `<deps>` is. That holds wherever the
+ * application is installed, and it cannot go stale when the installation moves again.
+ *
+ * @returns {string|null}
+ */
+function depsDirFromExecutable() {
+  const exe = process.execPath;
+  if (typeof exe !== 'string' || exe === '') return null;
+  const binDir = dirname(exe);
+  // `<deps>/node/bin/node[.exe]` is the shipped shape on every platform.
+  if (basename(binDir) !== 'bin' || basename(dirname(binDir)) !== 'node') return null;
+  const deps = dirname(dirname(binDir));
+  try {
+    return statSync(deps).isDirectory() ? deps : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Absolute path of the bundled DSH dependency directory, or `null` when absent.
  *
- * `DSH_RUNTIME_DEPS` overrides the guess, which keeps tests hermetic.
+ * Candidates are tried in order and the **first that exists** wins:
+ *
+ *   1. `DSH_RUNTIME_DEPS`, the explicit override that keeps tests hermetic;
+ *   2. `$DSH_HOME/dsh-runtimes/<runtime>/dependencies`, the shipped layout this module documented;
+ *   3. the directory implied by `process.execPath`, which is how the bundled layout is found now that the
+ *      application carries its runtime inside the bundle instead of under the home directory.
+ *
+ * Returning the first *existing* candidate rather than a single computed path is the part that matters: a
+ * stale first guess must not shadow a real second one.
  *
  * @param {Record<string,string|undefined>} [env]
  * @returns {string|null}
  */
 export function dshDependenciesDir(env = process.env) {
   const override = env.DSH_RUNTIME_DEPS && env.DSH_RUNTIME_DEPS.trim() !== '';
-  const dir = override ? env.DSH_RUNTIME_DEPS : join(dshHome(env), DSH_RUNTIME_RELATIVE);
-  try {
-    return statSync(dir).isDirectory() ? dir : null;
-  } catch {
-    return null;
+  const candidates = [
+    override ? env.DSH_RUNTIME_DEPS : join(dshHome(env), DSH_RUNTIME_RELATIVE),
+    depsDirFromExecutable(),
+  ].filter((dir) => typeof dir === 'string' && dir !== '');
+  for (const dir of candidates) {
+    try {
+      if (statSync(dir).isDirectory()) return dir;
+    } catch {
+      // Try the next candidate; an absent guess is not an error.
+    }
   }
+  return null;
 }
 
 /**
@@ -123,6 +173,53 @@ export function bundledBinDirs(env = process.env) {
   });
 }
 
+/**
+ * The file a bare tool name would name *inside DSH's bundled runtime*, or `null`.
+ *
+ * ## Why the identity check needs this and the search order must not
+ *
+ * `resolveCommand` keeps PATH ahead of the bundled tree, and a test guards that precedence
+ * (`keeps PATH ahead of the bundled runtime`). **The two are not in conflict**: PATH decides which file a
+ * *name* means, while this answers a different question -- *is this path the bundled copy of that tool?*
+ *
+ * **The measurement that required it:** twelve end-to-end tests refused with
+ * `COMMAND_EXECUTABLE_PATH_MISMATCH`. They dispatch `[process.execPath, '-e', ...]` against an allow-list entry
+ * of the bare name `node`. `process.execPath` is the bundled interpreter
+ * (`<deps>\node\bin\node.exe`), but that directory is **not on this machine's PATH**, so the bare name resolved
+ * to an unrelated `node.exe` shipped by another application and the two files differed.
+ *
+ * **The refusal was correct and the identity was wrong.** An absolute path that *is* the bundled copy of the
+ * tool the entry names is the tool the entry names -- which is exactly the rule the header states, and the
+ * reason `E:\Temp\evil\node.exe` must still be refused: that is a different directory, and this only ever
+ * returns files under `<deps>`.
+ *
+ * @param {string} name Bare command name, e.g. `node`.
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {string|null} Absolute path when the bundled copy exists.
+ */
+export function bundledExecutable(name, env = process.env) {
+  if (typeof name !== 'string' || name === '' || hasPathSeparator(name)) return null;
+  const depsDir = dshDependenciesDir(env);
+  if (depsDir === null) return null;
+  const isWin = process.platform === 'win32';
+  const exts = isWin ? ['', ...WIN_EXTENSIONS] : [''];
+  const bases = [
+    join(depsDir, name, 'bin'),
+    join(depsDir, name),
+  ];
+  for (const base of bases) {
+    for (const ext of exts) {
+      const candidate = join(base, name + ext);
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        /* keep looking */
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Resolve `argv[0]` the way the capability probe resolves a tool.
  *

package/src/plugin/tools.mjs

@@ -208,7 +208,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.59.0';
+const PLUGIN_VERSION = '1.0.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;