@twinsearth/w2m-dsh-plugin 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -4,6 +4,82 @@ 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.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.42.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.42.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,