@twinsearth/w2m-dsh-plugin 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -4,6 +4,120 @@ 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.9.3] — 2026-10-14
+
+**An undeclared anchor was compared against the literal `null`, so every dispatch from a non-git machine was `unverifiable` — including the ones that succeeded.**
+
+### The report, and why it read as a lie
+
+A relay was asked what happened to a task, and every answer came back the same way:
+
+```
+status : unverifiable
+reasons: ["base_commit \"a1e7dc042913b96da3ad68… != expected null"]
+notes  : ["aggregation refused: Step 1 anchor violation"]
+```
+
+while the machine's own record said `lease_state: done`, `status: ok`, `exit_code: 0`. A reader has no way
+to prefer either half, so a task that ran perfectly was reported as one that could not be trusted — and
+the same verdict came back for **every** dispatch.
+
+### The cause
+
+`report.mjs` Step 1 compared the anchor unconditionally:
+
+```js
+if (canon(valueOf(env, 'base_commit')) !== canon(expected.base_commit)) {
+```
+
+`expected.base_commit` comes from `task.base_commit ?? null`, and a dispatcher whose own tree is not a
+git work tree — the ordinary case for the plugin running out of its profile directory — sends `null`. So
+the comparison was *"the machine's real commit **equals null**"*, which no machine with an anchor can
+satisfy. **A machine was marked untrustworthy for reporting its commit truthfully.**
+
+That the two anchors disagree is the whole story. `base_tree` six lines below has always read:
+
+```js
+if (expected.base_tree !== null && canon(valueOf(env, 'pre_tree_fingerprint')) !== canon(expected.base_tree)) {
+```
+
+— it tolerates absence. `base_commit` did not. Same kind of statement, opposite handling, and the
+asymmetry is the bug. The protocol cannot even distinguish the two cases: `state.mjs` normalises both an
+absent field and an explicit `null` with `input.base_commit ?? null`, so "no anchor" and "anchor is null"
+arrive identically and must be treated identically.
+
+### The fix
+
+`base_commit` is enforced only when the dispatcher declared one, matching `base_tree`. The relaxation is
+**reported, not silent**: an `unanchored: true` field on the aggregate plus a note saying
+
+> no base_commit was declared, so the anchor check did not run: machine agreement here is agreement with
+> each other, not with a tree the dispatcher named
+
+because *"these machines agreed"* and *"nobody said what they should have agreed on"* must not read the
+same to an operator. `consistent: true` from an unanchored run says the machines matched; it does not say
+they ran the tree you meant.
+
+### Verified
+
+- `test/relay.test.mjs` — **152 tests, 0 failures**, including two new ones: the undeclared anchor is
+  skipped and reported, and a **declared** anchor mismatch still refuses aggregation. The second exists
+  because the first is a relaxation, and a relaxation without a falsifying test is how a check quietly
+  disappears.
+- `eslint .` — 0 errors.
+- The rest of the pre-flight — gate inventory, test wiring, workflow wiring, entry points, packed tarball,
+  claims, CHANGELOG shape — all green. The one red gate is `declared suite`, whose 38 failures on this host
+  are 38 tests that shell out to `git`, which is not installed here.
+
+### Note on where task output lives
+
+Investigating this also settled a question that had cost real time: the relay stores **no** task output. A
+task record carries `machine_id`, `lease_state`, `outcome`, `status`, `exit_code`, `transport`, `p2p` and
+`reasons` — and no `stdout`, no `stderr`, not even `stdout_sha256`, despite `COMPARABLE_FIELDS` naming
+those fields. So "sync the output home" cannot be solved at the relay, by any port or proxy: the text was
+never kept. Any durable record of what a command printed has to be written **on the machine that ran it** —
+which is exactly where the fleet-memory work begins.
+
+## [0.9.2] — 2026-10-14
+
+**The gate added in v0.8.11 pointed at a file that had never been committed, so it failed on all four CI platforms.**
+
+### What was broken
+
+`verify:join` was wired in three places across two releases:
+
+| where | when |
+|---|---|
+| `package.json` → `"verify:join": "node scripts/verify-join.mjs"` | v0.8.11 |
+| `.github/workflows/ci.yml` → `- run: npm run verify:join` | (pushed in v0.9.1) |
+| `.github/workflows/release.yml` → `- run: npm run verify:join` | (pushed in v0.9.1) |
+
+**`scripts/verify-join.mjs` itself was never in the repository.** It existed only in the working tree that built the tarballs, so every CI platform failed with the least interesting error available:
+
+```
+Error: Cannot find module '/home/runner/work/dsh-windows2macos/dsh-windows2macos/scripts/verify-join.mjs'
+code: 'MODULE_NOT_FOUND'
+```
+
+On `ubuntu-latest/22`, `windows-latest/22`, `windows-latest/20` and `macos-latest/22` alike. A file-existence check would have caught it; a review of the diff would not, because the diff was of files that existed.
+
+### How it was found
+
+By reading the CI failure logs rather than the CI summary. The summary said *"The fleet join reaches a token (stub agent, no relay)"* failed — which reads like the check *ran and disagreed*. It had not run at all. The summary named the step; only the log said `MODULE_NOT_FOUND`.
+
+The same class of mistake as the four files an earlier push left behind (see v0.9.1), and it is worth naming the shared root cause: **the v0.8.x tarballs were packed from a working tree, while the repository was written to by listing files individually.** A pack packs everything; an explicit list omits what the author forgets. The durable fix is to stop enumerating — but until this release the enumeration is what the tree had.
+
+So this release does the one thing v0.9.1 should have: it diffs the working tree against the repository in **both** directions. Exactly one file was present locally and absent remotely, and it was this one.
+
+### Verified
+
+- `node scripts/verify-join.mjs` — 16/16 locally, which it always was; the defect was never in the script.
+- The script is now in the repository, which is the only place `verify:join` can run from: `claims.test.mjs` pins
+  `FORBIDDEN_IN_RELEASE = ['test', 'scripts', ...]`, so `scripts/` is deliberately **not** in `package.json#files` and
+  a published tarball carries no `scripts/` directory by design. `verify:join`, `pack` and `verify` are source-tree
+  and CI commands, not consumer commands. An earlier draft of this entry called the absent `scripts/` a packaging
+  defect; that was wrong, and the constraint above is why.
+
 ## [0.9.1] — 2026-10-14
 
 **A powered-off machine stayed `online` and selectable in every fleet view, because `online` was never derived from contact.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "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/src/plugin/tools.mjs

@@ -180,7 +180,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.9.1';
+const PLUGIN_VERSION = '0.9.3';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;

package/src/relay/report.mjs

@@ -216,7 +216,34 @@ export function aggregate(task, resultRecords = [], opts = {}) {
       m.reasons.push('envelope status = unverifiable');
     }
     if (missing.length > 0) m.reasons.push(`missing required fields: ${missing.join(',')}`);
-    if (canon(valueOf(env, 'base_commit')) !== canon(expected.base_commit)) {
+    /**
+     * v0.9.3: `base_commit` is enforced only when the dispatcher declared one.
+     *
+     * The check used to be unconditional, so a dispatcher with **no** anchor -- one whose own tree is
+     * not a git work tree, which is the ordinary case for a machine that runs the plugin from its
+     * profile directory -- sent `base_commit: null`, and every result was then compared against the
+     * literal `null`. Any machine that *did* have an anchor reported its real commit and was marked
+     * `unverifiable` for telling the truth:
+     *
+     *     expected.base_commit : null
+     *     machine reported     : a1e7dc042913b96da3ad68…
+     *     reasons              : ["base_commit \"a1e7dc04…\" != expected null"]
+     *     notes                : ["aggregation refused: Step 1 anchor violation"]
+     *
+     * which downgraded **every** dispatch from such a machine, including a wholly successful one, and
+     * made the verdict unreadable. The anchor exists to answer "did these machines run the same tree";
+     * with nothing declared there is no such question, and the honest verdict is that the run is
+     * unanchored -- not that it disagreed with `null`.
+     *
+     * `base_tree` three lines below has always read this way (`expected.base_tree !== null && …`), and
+     * the asymmetry was the bug: the two anchors are the same kind of statement and one of them
+     * tolerated absence while the other did not.
+     *
+     * An absent anchor is still *reported* rather than silently ignored -- `unanchored: true` on the
+     * aggregate and in the machine's own record -- because "these two machines agreed" and "nobody
+     * said what they should have agreed on" must not read the same to an operator.
+     */
+    if (expected.base_commit !== null && canon(valueOf(env, 'base_commit')) !== canon(expected.base_commit)) {
       m.reasons.push(`base_commit ${truncate(canon(env.base_commit), 24)} != expected ${truncate(canon(expected.base_commit), 24)}`);
     }
     if (expected.base_tree !== null && canon(valueOf(env, 'pre_tree_fingerprint')) !== canon(expected.base_tree)) {
@@ -429,6 +456,18 @@ export function aggregate(task, resultRecords = [], opts = {}) {
     created_by: task.created_by ?? null,
     cancelled: task.cancelled === true,
     expected,
+    /**
+     * v0.9.3: whether this task ran against a declared tree at all.
+     *
+     * `expected.base_commit === null` means the dispatcher declared no anchor -- its own tree is not a
+     * git work tree, which is the ordinary case for the plugin running out of a profile directory. The
+     * anchor check is therefore skipped rather than compared against the literal `null` (see Step 1).
+     *
+     * Reported explicitly because the two situations must not look alike: `consistent: true` from an
+     * unanchored run says "these machines agreed with each other", **not** "these machines ran the
+     * tree you meant". An operator comparing results needs to know which of those they are holding.
+     */
+    unanchored: expected.base_commit === null,
     machines: machines.map((m) => ({
       machine_id: m.machine_id,
       machine_name: m.machine_name,
@@ -451,7 +490,10 @@ export function aggregate(task, resultRecords = [], opts = {}) {
     })),
     steps,
     differences: step3.differences ?? [],
-    notes,
+    notes: expected.base_commit === null
+      ? [...notes, 'no base_commit was declared, so the anchor check did not run: machine agreement here is '
+        + 'agreement with each other, not with a tree the dispatcher named']
+      : notes,
     counts: {
       refused: step0.refused.length,
       unverifiable: step1.violations.length,