@twinsearth/w2m-dsh-plugin 0.8.0 → 0.8.3

package/CHANGELOG.md

@@ -4,6 +4,213 @@ 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.8.3] — 2026-10-14
+
+**The last wire, and the reason it was never there.**
+
+### `autoStartAgent` was dead code
+
+The option existed, was documented, and **threw on its first call**. `startLocalStack` built its
+`createAgent` arguments as `projectDir` (the option is `project`), omitted `identity` (which is
+required), and passed a `pairingCode` that `createAgent` does not accept.
+
+Verified rather than inferred — calling `createAgent` with that exact shape:
+
+```
+createAgent THREW: createAgent: project is required
+```
+
+**So the code path that was supposed to bring an agent up had never run.** That is why the
+fleet-join wire appeared to be missing: the place it was meant to live could not be reached at all.
+An option that exists, is documented, and cannot execute is worse than one that is absent — it
+reads as a feature.
+
+### Two more things wrong with the shape
+
+* **It created a local relay unconditionally.** For a machine joining a shared fleet that is the
+  opposite of what is wanted: the machine must connect to the relay that already exists, not mint
+  another one — and with `rabbitUrl` pointing at a remote host it would have tried to bind a relay
+  on that hostname. It now stands up a local relay **only when the configured URL actually is
+  local**, and otherwise logs that it is joining the relay at the given address.
+* **Nothing paired the agent.** Even a started agent could fetch no offers, which looks identical to
+  a fleet with no work.
+
+### Now
+
+`startLocalStack` passes the option names `createAgent` actually documents, loads the identity from
+the **same file the CLI uses** — so one machine has one identity whether the agent runs in-process
+or as its own process, rather than each minting a keypair and overwriting the other's announcement
+under a shared `machine_id` (the v0.6.2 defect, in a new place) — and **pairs by the account fleet
+key**, falling back to a pairing code.
+
+Pairing is attempted **before** `agent.start()`, and a failure is **named at warn level** rather than
+swallowed: an agent that failed to pair runs and does nothing, which is indistinguishable from a
+quiet fleet.
+
+### Config
+
+`fleetKey` is read from the config layer or `W2M_FLEET_KEY`. The key must be **handed down** rather
+than computed where it is used, because a standalone agent cannot read the signed-in account — which
+is why it comes from the host.
+
+### Verified
+
+**132 cases** across the tools, apply and fleet-join suites. `tools.mjs` loads. The 12 agent-suite
+failures remain pre-existing and environmental, measured against an untouched clone of the same
+commit.
+
+### ⚠️ Not yet proven on real hardware
+
+The wiring is fixed and the mechanism was verified end to end in v0.8.2, but **no machine has yet
+joined a fleet through this path in a live run**. That is the next check, and it needs a machine
+that is not already paired.
+
+## [0.8.2] — 2026-10-14
+
+**The client half of the auto-join.** v0.8.1 landed the credential and the relay's acceptance of
+it; this is the wiring that makes a real machine use them.
+
+### What is now connected
+
+| piece | what it does |
+|---|---|
+| `account.mjs` | derives the fleet key on **every** resolve, including the stored-SN path |
+| `index.mjs` | exposes it as `fleetKey` — the key, never the account id |
+| `agent.mjs` | `pair(code, userId, fleetKey)`, sending only the discriminator that was given |
+| `w2m-localside` | `--fleet-key`, a peer of `--pair` |
+| relay | derives the fleet from the key; never believes a claimed one |
+
+**Verified end to end:** an agent given **only** `--fleet-key`, against a relay with **no fleet of
+its own**, pairs and lands in the account-derived fleet (`d5bb1b9ddf3faad4`, `source=fleet_key`).
+
+### The bug that would have made it work exactly once
+
+`resolve()` returned early when an SN was already stored and never read the account at all. That is
+right for the SN — it must not be regenerated, or every restart looks like a new device — and
+**wrong for the key**: a machine has a stored SN from its *second* start onward, so it would have
+derived a fleet key once and never again.
+
+**The auto-join would have worked on a machine's first boot and silently stopped afterwards** — the
+hardest kind of bug to see, because it works when you test it. Found by asking what the stored-SN
+path actually does, rather than by reading the happy path.
+
+### The bug in this release's own patch
+
+The fleet-key handling was first inserted **inside `if (flags.pair)`**, so the key path could only
+run when a pairing code was also supplied — precisely the case it exists to avoid. **It worked
+whenever anyone tested it with a code, and did nothing in the case that mattered.** The end-to-end
+test is what caught it, not review.
+
+### A provenance bug, also caught by testing
+
+A device that paired by key was recorded as `fleet_source: 'pairing_code'`, because the relay builds
+a synthetic code record so the binding reads from one place. That matters: `fleet_source` is what an
+operator reads in `devices.json` to answer *"how did this machine get into my fleet?"*, and
+answering "a pairing code" when there was none sends them looking for a code never issued.
+
+### Also
+
+`HANDOFF.md` records the state, the single reachable path to the Mac, and the traps this codebase
+has already fallen into.
+
+### Verified
+
+**585 chatops cases pass.** The 12 agent-suite failures are **pre-existing and environmental** —
+measured against an untouched clone of the same commit, both give **147 tests / 133 pass / 12 fail /
+2 skipped**, identical, so this change is not the cause.
+
+### ⚠️ Still not user-facing
+
+**The plugin does not yet spawn the agent or hand it the key**, so with the default configuration a
+new PC still will not auto-join. The mechanism is complete and verified; that last wire is what
+makes it something a user experiences rather than something a test proves.
+
+## [0.8.1] — 2026-10-14
+
+**A machine on the same account joins the same fleet with no human step** — the requirement that
+had no implementation behind it, and the bug that made it visible.
+
+### The reported bug, and what it actually was
+
+A new PC signed into the same DeepSeek account did **not** join the same fleet. Traced rather than
+guessed, the cause was four gaps stacked:
+
+* the plugin computed its SN, derived `fleet` from the account code, **logged it, and never used it
+  for anything**;
+* nothing called `/v1/pair`;
+* `autoStartAgent` defaults to **false**, so no agent started;
+* and even with an agent, membership needed a **human-typed one-time pairing code**.
+
+So "same account joins the same fleet automatically" was a stated requirement with no code path.
+
+### Why the obvious fix is the wrong one
+
+The obvious fix is to use `accountCode` as the credential. `account.mjs` documents the trade
+honestly — *"the cost of 32 bits, stated rather than hidden"* — and for **grouping** 32 bits is
+fine. As a **secret** it is not: 2^32 is brute-forceable, so authorising a join with it would let
+anyone enumerate their way into any fleet.
+
+**The bug was a conflation: a grouping identifier was doing duty as a secret.**
+
+### The fix
+
+The machines of one account share something an outsider cannot obtain — the ability to read
+`userId` — so the fleet secret is derived from it:
+
+```
+fleetKey = HMAC-SHA256(userId, "w2m-fleet-v1")     256 bits, same-account machines only
+fleetId  = SHA-256(fleetKey)                       what the relay groups by
+```
+
+**Presenting the key is the proof.** The relay *computes* a fleet id from the key it is given
+rather than believing a claimed one, so a device can only land in the fleet whose key it holds.
+No trust-on-first-use, no operator configuration, no account lookup, nothing to forge — and a
+device without the key forms a different, empty fleet instead of joining someone else's.
+
+`deriveAccountFleetKey` **refuses anything shorter than 16 characters**, and the refusal is asserted
+in a test rather than left to a comment: passing the 8-hex account code by mistake would otherwise
+produce a key that *looks* strong and is not — the worst kind of credential failure, because it is
+silent.
+
+### The relay side
+
+`deviceFleetFields` gains a third source, ordered by authority:
+
+| source | who decided |
+|---|---|
+| `pairing_code` | the operator, by issuing the code |
+| **`fleet_key`** | **the account, by derivation** — the auto-join path |
+| `request` | the relay operator, via `--fleet` |
+
+A **malformed key does not fall through** to the relay's own fleet. Falling through would be the
+silent wrong answer: a device that meant to join its account would be placed in an unrelated fleet
+and told nothing. It is refused, with the reason recorded on the device record.
+
+This also removes the deployment problem recorded in v0.7.9: `--fleet` no longer needs an operator
+to compute and hand-carry a 32-bit code, because the relay needs to know **nothing** about any
+account.
+
+### Verified
+
+* **21 cases** for the derivation: same account agrees, different accounts differ, the 32-bit code
+  is refused, the wire form round-trips, a client and a relay independently derive the same id, and
+  comparison is constant-time.
+* The derived bytes are **pinned**, not self-compared — a regression would silently split every
+  existing fleet into two halves that cannot see each other, with no error anywhere.
+* **223 cases** across the relay, wiring, scoping and join suites, unchanged.
+
+### ⚠️ What is still not wired
+
+The **derivation and the relay's acceptance** are done. The pieces that make a real machine use
+them are not:
+
+* `index.mjs` does not yet derive or expose the fleet key;
+* the agent does not yet present it at pairing;
+* `autoStartAgent` still defaults to false.
+
+**Until those land, a new PC still will not auto-join.** The credential exists and is accepted; the
+client does not yet offer it.
+
 ## [0.8.0] — 2026-10-14
 
 **The first release on npm since 0.6.3.** Eight versions of work — account identity, fleet

package/HANDOFF.md

@@ -0,0 +1,173 @@
+# Handoff — where this stands, and what to do next
+
+Written at the point of switching development from the Windows machine to the Mac. Everything here
+is **committed and pushed**; nothing depends on the machine that wrote it.
+
+---
+
+## The Mac is reachable by exactly one path
+
+Discovered the hard way — four blind attempts failed first, each diagnosed by encoding state into
+an **exit code**, because `unverifiable` tasks do not return their stdout and that is the only
+readable channel from that machine:
+
+| target | from the Mac |
+|---|---|
+| `raw.githubusercontent.com` | ❌ |
+| `github.com` release tarball | ❌ |
+| `http://202.182.123.154:8899/pub` | ❌ |
+| `http://202.182.123.154:8787` | ❌ |
+| **`http://geefish.cn/pub/...`** | ✅ **the only one** |
+
+Port 80, behind the nginx that already fronts the relay. A `location ^~ /pub/` was added to that
+same server block, so releases travel the one path already proven to work. The nginx change is
+tested with `nginx -t` **before** loading and restores its backup on any failure, because a broken
+config there takes the whole fleet down, not just a download.
+
+## Updating the Mac
+
+```bash
+curl -fsSL http://geefish.cn/pub/mac-self-update.mjs -o ~/w2m-self-update.mjs
+curl -fsSL http://geefish.cn/pub/w2m-0.8.2.tgz -o ~/w2m-0.8.2.tgz
+node ~/w2m-self-update.mjs --tarball ~/w2m-0.8.2.tgz \
+  --sha256 8ff593845612a4699c11c03ab22bbd81afa02f93b865d2e444badc8b62cfb60a
+```
+
+`--sha256` is not optional in spirit: the supervisor **refuses** a tarball whose checksum differs,
+before it touches anything.
+
+The supervisor is **detached** on purpose — it has to survive the DSH it restarts. Seven steps,
+ordered so the previous state is restorable **without the network**: verify the checksum, back up in
+place, check the staged tree for its entry point, swap, restart, self-check, and **roll back
+automatically** on failure. Every step is appended to `~/w2m-self-update-report.json` as it happens,
+so a process killed mid-way still says where it stopped.
+
+---
+
+## Current version, everywhere
+
+| machine | version |
+|---|---|
+| Windows | 0.8.1 |
+| **Linux relay host** | **0.8.2** |
+| **Mac** | **0.8.0 — needs the update above** |
+| npm | 0.8.0 |
+| GitHub | v0.8.0 released; 0.8.1 and 0.8.2 committed, **no release tag yet** |
+
+---
+
+## What was fixed, and the bug that is now closed
+
+**The reported bug:** a new PC signed into the same DeepSeek account did not join the same fleet.
+
+**The cause, traced rather than guessed** — four gaps stacked:
+
+1. the plugin computed its SN, derived `fleet` from the account code, **logged it, and never used
+   it for anything**;
+2. nothing called `/v1/pair`;
+3. `autoStartAgent` defaults to **false**;
+4. and even with an agent, membership needed a **human-typed one-time pairing code**.
+
+So *"same account joins the same fleet automatically"* was a requirement with **no code path**.
+
+**Why the obvious fix would have been wrong:** using `accountCode` as the credential. It is
+`sha256(userId)` truncated to **32 bits** — documented as fine for *grouping*, brute-forceable as a
+*secret*. The bug was a **conflation: a grouping identifier doing duty as a secret.**
+
+**The fix** derives the secret from what same-account machines share and outsiders cannot obtain —
+the ability to read `userId`:
+
+```
+fleetKey = HMAC-SHA256(userId, "w2m-fleet-v1")     256 bits
+fleetId  = SHA-256(fleetKey)                       what the relay groups by
+```
+
+**Presenting the key is the proof.** The relay *computes* a fleet id from the key rather than
+believing a claimed one, so a device can only land in the fleet whose key it holds. No
+trust-on-first-use, no operator configuration, no account lookup, nothing to forge — and a device
+without the key forms a different, empty fleet rather than joining someone else's.
+
+This also removes the deployment problem recorded in v0.7.9: **`--fleet` no longer needs an operator
+to compute and hand-carry a 32-bit code**, because the relay needs to know *nothing* about any
+account.
+
+**Verified end to end:** an agent given **only** `--fleet-key`, against a relay with **no fleet of
+its own**, pairs and lands in the account-derived fleet (`d5bb1b9ddf3faad4`, `source=fleet_key`).
+
+### The bug that would have made it work exactly once
+
+`resolve()` returned early when an SN was already stored and never read the account at all. Right
+for the SN — it must not be regenerated, or every restart looks like a new device — and **wrong for
+the key**: a machine has a stored SN from its *second* start onward, so it would have derived a key
+once and never again.
+
+**The auto-join would have worked on a machine's first boot and silently stopped afterwards** — the
+hardest kind of bug to see, because it works when you test it. Found by asking what the stored-SN
+path actually does, not by reading the happy path.
+
+---
+
+## What is wired, and the one thing that is not
+
+| piece | state |
+|---|---|
+| `account.mjs` derives the key on **every** resolve, both paths | ✅ |
+| `index.mjs` exposes it as `fleetKey` (the key, never the account id) | ✅ |
+| `agent.mjs` `pair(code, userId, fleetKey)` | ✅ |
+| `w2m-localside --fleet-key` | ✅ |
+| relay derives the fleet from the key | ✅ |
+| **the plugin spawns the agent and passes its key** | ❌ **not wired** |
+
+**So with the default configuration a new PC still will not auto-join.** The mechanism is complete
+and verified; the plugin does not yet start the agent or hand it the key. Until that lands, either:
+
+```bash
+w2m-localside --rabbit http://geefish.cn --fleet-key <KEY> --project <dir> --name <name> --state <dir>
+```
+
+or set `autoStartAgent` and wire the key through.
+
+**This is the next task.** It is also the last one: after it, installing the plugin and signing into
+the same account is the whole of the user-facing procedure.
+
+---
+
+## Traps this codebase has already fallen into — worth knowing before editing
+
+Each of these cost a debugging round, and most were **silent**:
+
+* **A presence check reads `undefined` as "provided".** `createILinkChannel` passed
+  `{ fetch: undefined }` and threw on mount (v0.7.0). The same shape appears in the pairing body:
+  an absent code must be an **absent key**, not a `null` one.
+* **An anchor in a `patch` file is an assertion, not a rename.** A mismatched `name:` makes the
+  Loader skip the whole patch *silently*.
+* **`statSync` on an injected path defeats the injection.** The secrets guard called it
+  unconditionally, so an injected reader was never reached and the scan reported **zero findings
+  across zero files** — a guard that is silently off.
+* **`createHmac('sha256', Buffer.alloc(0))` is not `createHash('sha256')`.** A signature over the
+  wrong bytes verifies nowhere and says nothing about why.
+* **A test that hard-codes a rule name measures the name, not the behaviour** — renaming broke it.
+* **`login` confirms as `confirmed`, not `scaned`.** Waiting on `scaned` misses the token entirely.
+* **The relay needs two credentials.** The operator token dispatches; the **device token** reads the
+  verdict. Supplying one gives a *confident wrong answer* — `判定：unknown` — rather than an error.
+
+## Reading the Mac without stdout
+
+Exit codes are the only channel. Encode state into them and probe:
+
+```js
+// on the Mac, via node -e
+process.exit(tgzSize < 700000 ? 10 : sup.done ? (sup.ok ? 0 : 13) : 12);
+```
+
+## Ground rules that have held
+
+* `deploy/server/` holds the units **as the live host runs them**; the deploy script's step order
+  *is* the safety argument.
+* `/var/lib/w2m/rabbit/` — `operator-token.txt` and the ledger — **must never be committed**.
+  `.gitignore` refuses the paths; `scripts/scan-for-secrets.mjs` reads the **content** of every
+  tracked file, because a `.gitignore` refuses a path while the ways a credential escapes are
+  pasting one into a source file, a fixture, or an example.
+* **A deploy cannot be an outage.** The relay runs **unscoped**, so its four devices keep working.
+  Scoping it requires an account code and a re-pair of every device.
+* **Never publish to npm without the token**, and rotate it: it has been pasted into a chat log.