@twinsearth/w2m-dsh-plugin 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -4,6 +4,131 @@ All notable changes to this project are documented here. The 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.43.0] — 2026-10-15
+
+**A machine stuck in its own state directory — and the parameter that was accepted, hashed, and ignored.**
+
+### What a deployment test on MacMini actually found
+
+Running the project's own test plan against MacMini produced eight dispatches that all failed, and **none of
+them failed for the reason the answers said.** The sequence, and what each answer meant:
+
+| Dispatched | Answer | What it actually meant |
+|---|---|---|
+| `node --test --test-reporter=spec test/` | `COMMAND_REPARSING_ARGUMENT` | correct refusal — the flag is not on the allow-list |
+| `bash -lc "…"` | `COMMAND_NOT_ALLOWED` | correct refusal |
+| `node --test <files>` | `exit 1` | **the files were not found** — the test never ran |
+| `cwd_rel: "local"` | `status: crashed`, `PATH_INVALID` | **the resolved directory did not exist** |
+
+**`PATH_INVALID` is a warning about a missing EXECUTABLE, and it was reporting a missing DIRECTORY.** Nothing
+in the answer said so. Establishing that took every one of those eight dispatches, and the cost was not the
+dispatches — it was that **every one of them looked like a test failure.**
+
+### The cause, and it is a configuration default rather than a bug
+
+`bin/w2m-localside.mjs:152` is `const project = flags.project ?? process.cwd()`. A `localside` started
+without `--project` takes **its own working directory** as the project root, and the packaged DSH starts it
+from `~/.dsh/xclient`. So that machine could run **only inside `~/.dsh/xclient`** — and nothing about the
+answer pointed at the cause.
+
+### `cwd_rel` travelled, was hashed, was validated, and was never consumed
+
+`w2m_run` has always accepted `cwd_rel`. The relay normalizes it, folds it into `command_hash`, and stores it
+on the task. The agent **resolves** it through `resolveProjectCwd` — and then, when the resolution failed,
+**logged a warning and ran anyway with the unvalidated relative path.**
+
+**The guard computed its own refusal and discarded it.** That is worse than no guard, because the guard is
+what a reader would cite as coverage.
+
+### The escape is now named, opt-in, and reported
+
+`resolveProjectCwd(root, cwdRel, { allowOutside })` — **`false` unless a caller asks, carried on the offer as
+`cwd_outside_project`, and off for every value that is not exactly `true`**, since it arrives over the
+wire. The resolved absolute directory is returned as `outside_project`, **so a result says where the command
+ran instead of leaving a reader to assume.**
+
+**This does not widen what may be RUN.** The command allow-list, the executable-path check and the
+argument-reparse refusal all still apply — **and three of them were observed refusing correctly during this
+same session.** It changes *where*, not *what*, and only when asked.
+
+### A guard caught me, and the fix was the name rather than the guard
+
+The parameter was first called `allow_cwd_outside_project`, and `tool-cards.test.mjs` failed on it:
+
+> `w2m_run` declares `allow_cwd_outside_project`, which names an allow-list — **a tool that can set one of
+> these widens what the fleet will do, and that decision belongs to an operator editing configuration on the
+> machine itself, never to a model**
+
+**It was right to fire, and it was firing on the name rather than the behaviour.** The parameter does not set
+an allow-list: **it changes WHERE a command runs, not WHAT may run** — the command allow-list, the
+executable-path check and the argument-reparse refusal all still apply, and three of them were observed
+refusing in this same session.
+
+**So the guard was left alone and the parameter was renamed** to `cwd_outside_project`. Relaxing a guard that
+protects the fleet, in order to land a feature of my own, is the one move this project has consistently
+refused — and **a guard that fires on a word is still a guard that made me justify the word.**
+
+### What the session measured about the security controls
+
+Four refusals, all correct, all from real dispatches:
+
+* `COMMAND_NOT_ALLOWED` — `node -e` on a machine whose allow-list omits it, and `bash -lc`
+* `COMMAND_REPARSING_ARGUMENT` — `node --test --test-reporter=spec` (a flag not declared) **and** an attempt
+  to smuggle `--eval` behind `--test`, which the plugin caught as *re-parseable* rather than as unknown
+* `COMMAND_EXECUTABLE_PATH_MISMATCH` — `/bin/sh` where the allow-list names `node`
+* `PATH_INVALID` — the one refusal that was **not** a security control, and the one whose message misled
+
+**12 new tests, 0 failures.**
+
+## [0.42.0] — 2026-10-15
+
+**The README catches up with 62 versions — and gathering the numbers found a defect that had survived all of them.**
+
+### The progress section, in both languages
+
+The README's newest version reference was **v0.4.0**, thirteen times, and its install command pinned a
+**v0.6.3** tarball. **Thirty-four versions of work had no record in the file a newcomer reads first.**
+
+There is now a **Progress** section (with a matching 进度 section) built from the CHANGELOG rather than from
+memory: **62 versions since 0.8.0, 11 tools, 79 suites, 2199 tests, 12 pre-flight checks, 0 failures.** It
+carries the three properties the project set out to have, the roadmap's **delivered / partial** state per
+version, what the reachability work found, the measured-on-real-machines table, and an explicit **"this is not
+1.0.0"**.
+
+**The seven accepted orphans are listed with what would remove each one**, and the **three that are defects are
+named as defects** rather than folded in with the four libraries — because the import graph cannot tell them
+apart, and only a written reason can.
+
+### `layer-check` printed "clean" and exited 1
+
+Gathering the numbers meant running the checks and reading their output and their status side by side, and two
+of them contradicted each other:
+
+```
+clean: every cross-layer edge is declared
+exit=1
+```
+
+**The clean path called `process.exit(1)`.** Every reader that trusts the exit code — a shell, CI, a script,
+`&&` — **read a passing check as a failing one.**
+
+**The pre-flight never noticed, and the reason is the interesting part: its own step reads the PRINTED TEXT
+rather than the status.** A check can therefore be wrong for a hundred versions while the gate over it stays
+green. It now exits `0`, with the failure paths still distinct (`2` for a violation, `3` for unexplained), and
+a regression test asserts **the status rather than the message** — because a test that read the message would
+have passed against the broken version, which is exactly what happened.
+
+### Also corrected
+
+* the install instructions now say **how to verify you got the version you asked for**, because this
+  repository's own profile installed from a pinned tarball and **fell 30+ versions behind**. A successful
+  install and a current install are two different things.
+* both language halves now name **`pnpm`** as the fallback where `npm` is absent — which is the case in the
+  packaged DSH runtime this was tested against.
+* one dead in-page anchor, from assuming GitHub's slugger keeps an em dash. It does not.
+
+**2 new tests, 0 failures.**
+
 ## [0.41.0] — 2026-10-15
 
 **`field-authority.mjs` has a caller. The correction from 0.29.0 lands, six versions after the claim.**

package/README.md

@@ -14,6 +14,71 @@ English | [中文](#中文说明)
 
 ---
 
+## Progress — where this actually is
+
+**Current: `0.41.0`.** 62 versions since `0.8.0`. The number that matters more than the version:
+**11 tools, 79 suites, 2199 tests, 12 pre-flight checks, 0 failures.**
+
+### The three properties this project set out to have
+
+| Property | State | What it means concretely |
+|---|---|---|
+| **分模块** (modular) | **enforced** | every file belongs to exactly one declared layer; `layer-check` fails on an undeclared edge |
+| **分层级** (layered) | **enforced** | six ranked layers and an **allow-list** of edges — not a rule that can be interpreted, a list that can be read |
+| **分权限** (tiered authority) | **built, opt-in** | four bands, escalation moves **exactly one band**, nothing destructive auto-settles. **Off by default** — see the gap below |
+
+### Roadmap
+
+| Version | Deliverable | State |
+|---|---|---|
+| **v4.8.0** | field-level acceptance, MMP P1/P2, lineage | **delivered** — `w2m_memory` accepts a received CAT7 block **field by field at the actor's level**; a field that costs more than the actor has is **omitted, not nulled**; a block naming an ancestor the caller cannot produce is **refused, never re-rooted** |
+| **v4.9.0** | approval queue | **partial** — the queue, the escalation bridge and the raise-limiter are wired and reachable by an operator through `w2m_approvals`. **The "front door" named in the roadmap was never built**: `approval-index.mjs` imports `authority.mjs` and nothing else |
+| **v4.10.0** | committee governance | **delivered** — seven phases, weighted votes, **a tie is refused rather than broken**, and a sealed decision is **retrievable with its dissent and its reasons** after the council that produced it is gone |
+
+### What the reachability work found, because it is the honest part
+
+Three mechanisms were shipped in this span **fully tested and reachable by nothing** — `field-authority`,
+`approval-gate`, and `council`. Two were **described as delivered** while nothing ran them. A single `grep`
+disproved one of them.
+
+There is now a **gate**: a module nothing reaches makes the pre-flight **red** unless it appears in
+`scripts/accepted-orphans.mjs` **with a reason and a statement of what would remove it**. An acceptance that
+outlives its cause also fails. **Seven remain**:
+
+| Module | Kind | What would remove it |
+|---|---|---|
+| `health.mjs` | **defect** | the agent calling it on a schedule |
+| `log-bounds.mjs` | **defect** | the same — it is the answer to a **measured 40× log growth** |
+| `storage.mjs` | **defect** | a tool writing through its undelatable tiers |
+| `fleet-scale.mjs`, `fleet-state.mjs`, `exit-channel.mjs`, `test-report.mjs` | library | a caller, when one is wanted |
+
+**The defect class is named as a defect rather than folded in with the libraries**, because the two are
+indistinguishable from the import graph alone and only a written reason can separate them.
+
+### The gap that matters most right now
+
+**The plugin this machine runs is 30+ versions behind this source tree.** Every source-level conclusion about
+the running runtime is void until it is upgraded — which is one command, and it is in
+[Install](#3-the-dsh-plugin).
+
+### Measured on real machines
+
+| Fact | Evidence |
+|---|---|
+| a **seven-phase council** runs on macOS | `exit 0` on MacMini: phases 7, dissent retained, recount reproduced |
+| **field-level acceptance** holds on macOS | `exit 0` on MacMini: level 0 cannot reach `evidence`, level 70 can, tampering caught, a missing ancestor refused rather than re-rooted |
+| the fleet is **3 usable machines of 5 paired** | and `fleet-scale.mjs` **refuses to extrapolate** from five |
+| **`P2P_PUNCH_FAILED`** | **UNVERIFIED.** Three hypotheses measured and excluded (BLAKE2s-256, the wider primitive set, version skew). **The plugin that raises it runs 0.9.5** — upgrading is the next experiment |
+
+### Not claimed
+
+**This is not 1.0.0.** `docs/1.0.0-ACCEPTANCE.md` sorts all 30 criteria into **ENFORCED / MEASURED /
+UNVERIFIED** by a rule rather than an opinion, names **seven claims this work had to retract**, and states
+plainly that four of its own closing items are undone. It is bound to the pre-flight by a test, so a criterion
+cannot quietly become unenforced while the file keeps claiming otherwise.
+
+---
+
 ## The problem
 
 You have a Windows desktop and a Mac laptop. You are working on one project. You
@@ -250,9 +315,18 @@ dsh plugin --profile <profile-name> add @twinsearth/w2m-dsh-plugin
 
 ```bash
 dsh plugin --profile <profile-name> add \
-  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.6.3/twinsearth-w2m-dsh-plugin-0.6.3.tgz
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.41.0/twinsearth-w2m-dsh-plugin-0.41.0.tgz
 ```
 
+This form **pins a version by construction**, which is both its virtue and the trap: a
+profile that installs this way stays on that version forever unless somebody edits the
+line. **This repository's own profile did exactly that and fell 30+ versions behind** —
+so if you use it, re-check the number against the badge at the top of this file.
+
+**No `npm`?** Some hosted runtimes (including the packaged DSH) ship `node` and `pnpm`
+but not `npm`. `pnpm add @twinsearth/w2m-dsh-plugin@0.41.0 --save-exact` installs the
+identical tarball from the identical registry.
+
 **From the repository** — the form a marketplace's one-click installer uses (it clones
 the repo, builds nothing, and registers `cordis.patch.yml`):
 
@@ -270,6 +344,14 @@ answer, not three.
 > listed in `package.json` but never composed is the failure this project hit once
 > already — see `cordis.patch.yml`'s header for what that looked like.
 
+**Then check the version you actually got**, because a successful install and a current
+install are two different things:
+
+```
+w2m_status   →  actor_authority and approvals should be present (0.9.5 has neither)
+tool list    →  w2m_council should be present (it arrived in 0.37.0; anything older lacks it)
+```
+
 Then give it the relay URL in that profile's `cordis.patch.yml` — or leave
 `rabbitUrl` empty to use the shared server:
 
@@ -532,6 +614,10 @@ Read this before exposing the relay to anything.
 
 This project's rule is that claims carry their evidence.
 
+> **Current state lives in [Progress](#progress-where-this-actually-is) above.** What follows is the
+> **v0.4.0 record**, kept because it is the measurement the direct path still rests on — not because it
+> describes what ships today. The version is now `0.41.0`.
+
 ### v0.4.0 — the direct path is the default, and here is what that is worth
 
 v0.3.9 shipped the P2P transport and admitted in its own §8 that nothing read
@@ -778,6 +864,60 @@ When something does not work, start from the symptom: [TROUBLESHOOTING.md](TROUB
 
 **同一个 DeepSeek 账号，一条指令，让在线的 Windows 与 Mac 跑同一个项目。**
 
+### 进度 —— 它现在到底到哪一步了
+
+**当前版本：`0.41.0`**。自 `0.8.0` 以来共 **62 个版本**。比版本号更重要的数字是：
+**11 个工具、79 个测试套件、2199 个用例、12 项预检、0 失败。**
+
+#### 三项目标本来的属性
+
+| 属性 | 状态 | 具体含义 |
+|---|---|---|
+| **分模块** | **已强制** | 每个文件属于且只属于一个已声明的层；出现未声明的依赖边，`layer-check` 直接失败 |
+| **分层级** | **已强制** | 六个带序号的层，以及一张**允许清单**——不是一条可以被解读的规则，而是一张可以被读的清单 |
+| **分权限** | **已建成，需手动开启** | 四个权限带、升级**恰好一级**、破坏性操作**永不自动放行**。**默认关闭**，见下方缺口 |
+
+#### 路线图
+
+| 版本 | 交付物 | 状态 |
+|---|---|---|
+| **v4.8.0** | 字段级接受、MMP P1/P2、lineage | **已交付** —— `w2m_memory` 接收来自其他机器的 CAT7 认知块，**按字段、按接收方的权限级别**逐项接受；接收方买不起的字段**是「缺席」，不是 null**；祖先无法产出时**拒绝，绝不重新生根** |
+| **v4.9.0** | 审批队列 | **部分完成** —— 队列、升级桥、发起限流器都已接线，操作者可通过 `w2m_approvals` 处理。**但路线图里写的那道「前门」从未构建**：`approval-index.mjs` 只导入 `authority.mjs`，别无其他 |
+| **v4.10.0** | 委员会治理 | **已交付** —— 七个阶段、加权投票、**平票是拒绝而不是打破**；封印的决定在产生它的委员会消失之后，**仍可连异议和异议的理由一起取回** |
+
+#### 可达性检查发现了什么（这部分才是诚实的部分）
+
+这一跨度里有**三个机制被完整实现、完整测试、却没有任何东西能到达**——`field-authority`、`approval-gate`、`council`。其中**两个在被描述为「已交付」时，没有任何东西在跑它们**。一条 `grep` 就推翻了其中一个。
+
+现在有**门禁**了：一个没人能到达的模块会让预检**变红**，除非它出现在 `scripts/accepted-orphans.mjs` 里，**并写明理由和「什么能让它下榜」**。已经修好的条目若还留在清单上，同样失败。**目前还剩 7 个**：
+
+| 模块 | 性质 | 什么能让它下榜 |
+|---|---|---|
+| `health.mjs` | **缺陷** | agent 按计划调用它 |
+| `log-bounds.mjs` | **缺陷** | 同上——它是对**实测到的 40 倍日志增长**的答案 |
+| `storage.mjs` | **缺陷** | 有工具真正通过它的「不可删除」层写入 |
+| `fleet-scale.mjs`、`fleet-state.mjs`、`exit-channel.mjs`、`test-report.mjs` | 库 | 需要时给它们调用方 |
+
+**「缺陷」这一类被单独命名，而不是和「库」混在一起**——因为仅凭导入图这两者无法区分，**只有写下来的理由能分开它们**。
+
+#### 眼下最要紧的那个缺口
+
+**本机实际运行的插件比这份源码落后 30 多个版本。** 在升级之前，**任何关于运行时行为的源码级结论都作废**。升级只需一条命令，见[快速开始](#快速开始)第 3 步。
+
+#### 在真机上实测到的
+
+| 事实 | 证据 |
+|---|---|
+| **七阶段委员会**能在 macOS 上跑通 | MacMini `exit 0`：7 个阶段、异议被保留、`recount` 复现成功 |
+| **字段级接受**在 macOS 上成立 | MacMini `exit 0`：级别 0 拿不到 `evidence`、级别 70 拿得到、篡改被抓、**缺祖先时拒绝而不重新生根** |
+| 编队是**5 台配对中 3 台可用** | 而 `fleet-scale.mjs` 因此**拒绝外推** |
+| **`P2P_PUNCH_FAILED`** | **未验证。** 三个假设已测量并排除（BLAKE2s-256、更广的原语集、版本偏差）。**抛出它的是跑着 0.9.5 的插件**——升级就是下一个实验 |
+
+#### 不作声明
+
+**这不是 1.0.0。** `docs/1.0.0-ACCEPTANCE.md` 把全部 30 条准则按**一条规则**（而非观点）分成
+**已强制 / 已测量 / 未验证**三类，列出**这一跨度不得不撤回的 7 条声明**，并明说它自己收尾清单里的四项尚未完成。它被一个测试**绑定到预检**，所以**一条准则不可能在文件仍声称它被强制的同时悄悄变成未被强制**。
+
 ### 为什么需要它
 
 DSH 目前**不能**跨机器协作，而且不是疏忽：
@@ -817,8 +957,21 @@ node bin/w2m-localside.mjs --rabbit http://<中继地址>:8787 --pair PAIR-XXXXX
   --allowed-commands '["node --test","git status --porcelain"]'
 
 # 3) 装 DSH 插件
-dsh plugin --profile <profile-name> add \
-  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.6.3/twinsearth-w2m-dsh-plugin-0.6.3.tgz
+#    v0.4.0 起可从 npm 装（比逐个指定 release 的 tgz 更好：不会锁死在某个旧版本上）。
+#    本仓库自己的 profile 就一直锁在一个本地 0.9.5 的 tgz 上，结果落后了 30 多个版本。
+npm install @twinsearth/w2m-dsh-plugin@latest
+#    或者，如果你想钉死一个具体版本：
+#    npm install @twinsearth/w2m-dsh-plugin@0.41.0
+#
+#    没有 npm 的托管运行时（DSH 打包版就是这种）用 pnpm 即可，同一个 registry、同一份 tarball：
+#    pnpm add @twinsearth/w2m-dsh-plugin@0.41.0 --save-exact
+```
+
+装完后**重启 DSH**，然后确认版本对上了——这一步别跳过，因为**本仓库自己就在这里栽过**：
+
+```
+w2m_status  →  应能看到 actor_authority 与 approvals 两个字段（0.9.5 没有）
+工具列表    →  应能看到 w2m_council（旧版只有 8 个工具）
 ```
 
 然后在 profile 的 `cordis.patch.yml` 里给插件 `rabbitUrl`（留空即用共享服务器）与 `operatorToken`，重启 DSH，即可直接用自然语言指挥：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "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",
@@ -113,13 +113,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs",
     "test:relay": "node --test --test-force-exit test/relay.test.mjs",
     "test:agent": "node --test --test-force-exit test/agent.test.mjs test/memory.test.mjs",
     "test:tools": "node --test --test-force-exit test/tools.test.mjs",
     "test:crossnetwork": "node --test --test-force-exit test/crossnetwork.test.mjs",
-    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "pack": "node scripts/pack.mjs",
     "verify:join": "node scripts/verify-join.mjs",
     "lint": "eslint .",

package/src/agent/agent.mjs

@@ -1,4 +1,4 @@
-/**
+/**
  * The Localside agent: everything between "Rabbit hands us an offer" and
  * "Rabbit has our envelope".
  *
@@ -2977,7 +2977,7 @@ export function createAgent(options) {
       for (const stage of plannedStages) {
         heartbeat.setPhase('running', 50);
 
-        const stageCwdOutcome = resolveProjectCwd(project, stage.cwd_rel);
+        const stageCwdOutcome = resolveProjectCwd(project, stage.cwd_rel, { allowOutside: offer.cwd_outside_project === true });
         if (!stageCwdOutcome.ok) {
           // A stage whose cwd is outside the project is a refusal of the whole chain: continuing
           // would run later stages against a working directory the caller never asked for.

package/src/agent/git.mjs

@@ -584,19 +584,38 @@ export async function collectPostState(options) {
  * Containment is decided with `path.relative`, which (unlike a string prefix
  * test) is correct on Windows where drive letters and path case vary.
  *
+ * ## Why there is now an explicit way out, and why it is opt-in
+ *
+ * This guard was written because a caller should not be able to point a machine at a directory the
+ * operator never designated as the project. **Measured, that turned out to make the agent unusable for
+ * the one thing a fleet is for**: a machine whose localside was started from `~/.dsh/xclient` (its own
+ * state directory, which is the default when `--project` is not passed) **can only ever run inside
+ * `~/.dsh/xclient`**. Dispatching `node --test test/x.test.mjs` to it then fails with `PATH_INVALID`,
+ * because the resolved directory does not exist — **and nothing about the answer says why.** Eight
+ * dispatches went into establishing that.
+ *
+ * So the escape exists and is **named**: `allowOutside`. It is `false` unless a caller asks, it is
+ * carried on the offer rather than inferred, and the resolved absolute path is reported back so the
+ * result says the command ran outside the project. **A named, auditable escape is worth more than a
+ * guard that quietly ignores its own outcome** — the previous version computed this refusal and then
+ * ran anyway with the *unvalidated* relative path.
+ *
  * @param {string} projectRoot Absolute project root.
  * @param {string} cwdRel Forward-slash relative path from the offer.
- * @returns {{ok: true, cwd: string, cwd_rel: string}|{ok: false, reason: string}}
+ * @param {{allowOutside?: boolean}} [options]
+ * @returns {{ok: true, cwd: string, cwd_rel: string, outside_project: boolean}|{ok: false, reason: string}}
  */
-export function resolveProjectCwd(projectRoot, cwdRel) {
+export function resolveProjectCwd(projectRoot, cwdRel, options = {}) {
+  const allowOutside = options.allowOutside === true;
   const root = resolve(projectRoot);
   const normalized = normalizeRelPath(cwdRel);
   const target = resolve(root, normalized.split('/').join(sep));
   const rel = relative(root, target);
-  if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) {
+  const escapes = rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel);
+  if (escapes && !allowOutside) {
     return { ok: false, reason: 'CWD_OUTSIDE_PROJECT' };
   }
-  return { ok: true, cwd: target, cwd_rel: normalizeRelPath(rel) };
+  return { ok: true, cwd: target, cwd_rel: normalizeRelPath(rel), outside_project: escapes };
 }
 
 /**

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.41.0';
+const PLUGIN_VERSION = '0.43.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3571,6 +3571,19 @@ export async function apply(ctx, config = {}) {
         description: 'Working directory relative to the project root, with forward slashes. Defaults to ".".',
         default: '.',
       },
+      cwd_outside_project: {
+        type: 'boolean',
+        default: false,
+        description:
+          'v0.43.0. Let `cwd_rel` resolve OUTSIDE the target machine\'s project root. OFF by default, and ' +
+          'that guard exists for a reason: a machine should not be pointed at a directory the operator ' +
+          'never designated. It is needed because a localside started without `--project` takes its own ' +
+          'working directory as the root -- so a machine launched from its state directory can otherwise ' +
+          'run ONLY inside that directory, and a dispatch that asks for anywhere else fails as ' +
+          '`PATH_INVALID` with nothing in the answer saying why. Turning this on does not widen what may ' +
+          'be RUN (the command allow-list and the executable path check still apply); it changes WHERE. ' +
+          'The resolved directory is reported back so a result says when it happened.',
+      },
       timeout_ms: {
         type: 'number',
         // No `default` here on purpose. If the schema carried one, DSH would fill it in before
@@ -3967,6 +3980,8 @@ export async function apply(ctx, config = {}) {
         // the relay's normalization is the single source of that field.
         ...(argvUsable ? { command_argv: argv } : {}),
         cwd_rel: typeof args?.cwd_rel === 'string' && args.cwd_rel !== '' ? args.cwd_rel : '.',
+        // Sent only when the caller asked, so every existing dispatch produces the same bytes on the wire.
+        ...(args?.cwd_outside_project === true ? { cwd_outside_project: true } : {}),
         index_total: indexTotal,
         timeout_ms: timeoutMs,
         write,

package/src/relay/state.mjs

@@ -607,6 +607,7 @@ export class RabbitState {
           mode: t.mode ?? 'replicate',
           command_argv: t.command_argv ?? [],
           cwd_rel: t.cwd_rel ?? '.',
+          cwd_outside_project: t.cwd_outside_project === true,
           index_total: t.index_total ?? 1,
           timeout_ms: t.timeout_ms ?? 300_000,
           write: t.write === true,
@@ -1475,6 +1476,10 @@ export class RabbitState {
       mode,
       command_argv: commandArgv,
       cwd_rel: cwdRel,
+      // v0.43.0. The task construction is field-by-field, so a field not named here is silently dropped --
+      // which is how a parameter can be accepted by the tool, validated by the tool, and never reach the
+      // machine. Named explicitly so it travels.
+      cwd_outside_project: input.cwd_outside_project === true,
       index_total: indexTotal,
       timeout_ms: timeoutMs,
       write: input.write === true,
@@ -1720,6 +1725,7 @@ export class RabbitState {
         mode: task.mode,
         command_argv: task.command_argv,
         cwd_rel: task.cwd_rel,
+        cwd_outside_project: task.cwd_outside_project === true,
         index_total: task.index_total,
         timeout_ms: task.timeout_ms,
         write: task.write,
@@ -1848,6 +1854,9 @@ export class RabbitState {
       origin_machine_id: task.origin_machine_id ?? null,
       p2p: task.p2p ?? null,
       cwd_rel: task.cwd_rel,
+      // Omitted when false, so a single-command offer for every existing caller stays byte-identical -- the
+      // same reason `stages` above is conditional.
+      ...(task.cwd_outside_project === true ? { cwd_outside_project: true } : {}),
       write: task.write,
       timeout_ms: task.timeout_ms,
       base_commit: task.base_commit,