@twinsearth/w2m-dsh-plugin 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -4,6 +4,393 @@ 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.9] — 2026-10-14
+
+**The account answers lazily, and we asked once.**
+
+### The defect
+
+`getPlatformSession().userId` repeats the stable account id **from the most recent successful
+`getProfile`**, and is `null` until one has happened. The account profile is a **lazy cache**, and
+`startLocalStack` reads it **at mount** — before any model call has touched the profile.
+
+So on a signed-in machine the first read returns *signed out*, the fleet key is never derived, no
+pairing happens, and **nothing is written**. The evidence that pins it is `device.json`'s **mtime**:
+unchanged since the first boot, so `saveDeviceToken` was not merely ineffective, it was **never
+reached**.
+
+**That also explains an earlier result that made no sense at the time:** v0.8.4 *did* pair once,
+because by then the profile happened to be cached. **A timing-dependent success is the worst kind to
+debug — the code is right and the outcome still varies.**
+
+### v0.8.7 made it worse, without meaning to
+
+*"Already paired → do not pair again"* turned an **intermittent miss into a permanent one**. A
+machine that missed at startup never retried, and re-pairing had been the only thing rescuing it.
+The rate-limit fix was correct and exposed a defect it did not create.
+
+### Fixed
+
+Derivation now **backs off and retries** (6 attempts, 2s doubling to a 30s cap) until a real key
+appears or the budget runs out.
+
+### And the silent branch that hid it
+
+`resolve()` on the **stored-SN path** returns `ok: true` with `fleetKey: null`. The old code logged
+only when `ok === false` — so the shape that was actually firing **produced no output anywhere**.
+
+That is the same *silent no-op* class fixed in 0.8.5, reappearing **in the exact branch that was
+failing**. Every outcome is now named:
+
+| shape | reported as |
+|---|---|
+| `ok: true`, key present | `fleet key derived … on attempt N (fleet …)` |
+| **`ok: true`, key null** | **`signed in, but the account returned no fleet key (the profile may not be loaded yet)`** |
+| `ok: false` | the reason and detail, verbatim |
+| budget exhausted | **`this machine is in NO fleet and will receive no work`** |
+
+A machine in no fleet must never be quiet about it.
+
+### Verified
+
+**174 cases**. `tools.mjs` loads; the describer was exercised against all five shapes including the
+one that previously said nothing.
+
+## [0.8.8] — 2026-10-14
+
+**A machine that joined without saying what it is — and a fix that was computed and never used.**
+
+### `platform` and `caps` were never sent
+
+`createAgent` accepts `platform` and `caps`, and `bin/w2m-localside.mjs` has always supplied them.
+`startLocalStack` did not, so a machine that joined **through the plugin** appeared in the relay
+complete and correct except for:
+
+```
+"os": null, "arch": null, "caps": {}
+```
+
+**The capability gate then had nothing to filter on — and that gate decides what work a machine is
+offered.** So the device was registered, reachable, and unusable for anything the gate would have
+matched it to.
+
+Same shape as the rest of this series: the record was created and **the part that makes it useful was
+not filled in**.
+
+### The v0.8.5 fix was computed and never used
+
+Worse, and found while making the change above:
+
+```js
+const resolvedStateDir = cfg.stateDir.trim() !== '' ? cfg.stateDir.trim() : resolveStateDir(...);
+if (cfg.stateDir !== resolvedStateDir) { ctx.logger?.info?.(`w2m: stateDir was unset; using ...`); }
+...
+const agent = await createAgent({ stateDir: cfg.stateDir, ... });   // ← the EMPTY string
+```
+
+**v0.8.5 computed the resolved directory, logged it, and then passed the original empty string to
+`createAgent`** — the exact call that throws `createAgent: stateDir is required`. So the second gate
+v0.8.5 claimed to open was **still shut**, and the only evidence was a log line saying the resolved
+path was being used.
+
+*The log said the right thing while the code did the wrong thing* — which is worse than silence,
+because silence sends you looking and a confident wrong log sends you away.
+
+Both `createRelay` and `createAgent` now receive `resolvedStateDir`, and its definition was moved
+**above** its first use: as a `const` used earlier in the same block it would have thrown
+`ReferenceError: Cannot access 'resolvedStateDir' before initialization` at runtime, which
+`node --check` cannot see because it is not a syntax error. Caught by checking the **order**, not the
+syntax.
+
+### Also sent now
+
+`identityPath: loaded.path` — the device key belongs **beside the `device.json` this process actually
+loaded**, not in a directory the agent guesses. Without it the in-process and standalone paths can
+mint separate keypairs under one `machine_id` and overwrite each other's announcement (the v0.6.2
+defect, which this path would have reintroduced).
+
+### Verified
+
+**174 cases**. `tools.mjs` loads; the ordering was confirmed by comparing line numbers rather than by
+reading.
+
+## [0.8.7] — 2026-10-14
+
+**Pair only when there is no token — because the relay rate-limits pairing.**
+
+### The defect
+
+v0.8.6 made the token persist; it still **paired on every start**. The fleet key is derived
+unconditionally, so `pairBy` was never null and the pairing branch always ran.
+
+The relay allows `pair_rate_limit: 5` per minute. **Five restarts inside a minute hit the limit — and
+a rate-limit refusal reads as a pairing failure, which reads as a fleet problem.** The symptom would
+have pointed at the network, the relay, or the account, none of which would be at fault.
+
+A machine that already holds a token has nothing to gain from pairing again: the relay would re-issue
+one and invalidate the old, for no reason.
+
+### Fixed
+
+```js
+const existingToken = loaded.identity.device_token;
+const alreadyPaired = typeof existingToken === 'string' && existingToken !== '';
+
+if (alreadyPaired) {
+  ctx.logger?.info?.(`w2m: already paired (token in ${loaded.path}); not pairing again`);
+} else if (pairBy !== null) {
+  // pair once, then persist
+}
+```
+
+**This also makes the persisted token load-bearing rather than an optimisation.** Without it every
+start is a fresh pairing — which is why *the missing write in v0.8.5* and *the unconditional pairing
+here* are **the same defect seen from two sides**: one threw the token away, the other had to
+re-create it every time.
+
+### A note on how this was found
+
+Reported, with reasoning and a rate-limit number from the relay's own configuration — not from a
+failing test. The distinction matters for what it implies: **nothing in the suite would have caught
+it**, because every case starts from a fresh state and none of them restart the plugin in a loop.
+
+### Verified
+
+**174 cases** across the tools, apply, account and fleet-join suites.
+
+## [0.8.6] — 2026-10-14
+
+**The pairing worked and the token was thrown away.**
+
+### The defect
+
+`startLocalStack` called `agent.pair(...)` and **never persisted the result**. `agent.pair` sets
+`identity.device_token` on its **in-memory object only**, so the observable behaviour was:
+
+1. the account-derived key is computed ✅
+2. the relay **accepts** the pair and registers the device ✅
+3. the machine appears in `w2m_devices` ✅
+4. **every authenticated call then answers `401 UNAUTHORIZED`** — `w2m_devices`, the P2P announce,
+   all of it — because `device.json` still said `device_token: null` ❌
+
+It reads as a permission failure and is **a missing write**.
+
+The evidence that settles it is the shape of the value: not an empty string, not a truncated token —
+**`null`**. A write that failed would leave the previous value; a write that never happened leaves
+what the identity was created with.
+
+### Why the CLI never had this bug
+
+`bin/w2m-localside.mjs` has always done it:
+
+```js
+const paired = await agent.pair(flags.pair ?? null, undefined, fleetKey);
+saveDeviceToken(paired.device_token, {});     // ← the CLI persists it
+```
+
+**The in-process path was written without that line.** So the two paths diverged in exactly the way
+that produces a symptom in one and not the other — which is why it looked like a relay or permission
+problem rather than a missing statement.
+
+### Fixed
+
+`saveDeviceToken(paired.device_token, identityOptions)` now runs after a successful pair, using the
+**same options object** that loaded the identity. Reading with one set of options and writing with
+another is how the plugin and the CLI once ended up each minting a keypair under one `machine_id`
+(the v0.6.2 defect), so the options are captured once and used for both.
+
+A failure to persist is **named at warn level**, including what it means: *"this machine will answer
+401 to every authenticated call until that is fixed."* That exact condition was silent once already.
+
+### The pattern this is the third instance of
+
+* v0.8.4 wired the **derivation** but the gate in front of it was closed.
+* v0.8.5 fixed the **second gate** (`stateDir`) but not the write behind it.
+* v0.8.6 fixes the **write**.
+
+Each time, the action was connected and its **persistence or precondition** was not. Worth stating
+plainly because it is the shape of every bug in this series: **the thing that makes the result
+survive is the thing that gets forgotten.**
+
+### Verified
+
+**174 cases** across the tools, apply, account and fleet-join suites.
+
+## [0.8.5] — 2026-10-14
+
+**Two gates, not one — and the silence that hid both.**
+
+### The second gate
+
+v0.8.4's analysis said the join sequence was blocked by `autoStartAgent` defaulting to false. That
+was right and incomplete: **an unset `stateDir` threw as well**, so flipping the switch would have
+failed too.
+
+```
+stateDir=empty string -> THREW: createAgent: stateDir is required
+```
+
+`createAgent` rejects a falsy `stateDir`; the plugin's resolved default is the empty string; and
+`startLocalStack` passed it straight through. **Two gates in series, and the analysis found the one
+in front.**
+
+`stateDir` now resolves to a real path (`$DSH_HOME/xclient/localside`) when unset, resolved in
+`startLocalStack` so `w2m_status` reports the path actually used — which is what makes *"where did it
+write `device.json`"* answerable rather than a guess.
+
+### The silence, which is the real defect
+
+A machine could run v0.8.4, hold a valid signed-in account, reach the relay over **HTTP 200**, and
+be in **no fleet** — with nothing anywhere reporting a problem. The eight tools registered, the
+plugin looked healthy, and the join sequence simply never ran.
+
+**A silent no-op that looks like success is the worst failure mode this plugin has had**, because
+every diagnostic signal a person would reach for says the system is fine. The evidence that finally
+settled it was an *absence* — no `device.json`, no `xclient`, no listening ports — and an absence
+is only readable once you know what should have been there.
+
+So the disabled branch now says so, at warn level, naming what it means and how to change it:
+
+> `w2m: no agent is running on this machine, so it is in no fleet and will receive no work. Set autoStartAgent: true to join …`
+
+One line turns *"why is this machine not in my fleet"* from an investigation into a log search.
+
+### A test that measured a count instead of a message
+
+`tools.test.mjs` asserted `warnings.length === 1` for the `dsh-tools` shim warning — a claim about
+**every** warning the plugin will ever emit, so the new one broke a test about something else
+entirely. It now matches the message it is about. **The count was never the property.**
+
+### What is still required, stated plainly
+
+The switch does not default to on, deliberately: a control machine that only *dispatches* to others
+has no reason to be in the fleet itself. So joining requires `autoStartAgent: true` **and** a
+`w2m` row in the profile — and the profile having no such row is the state every fresh install
+starts in.
+
+### Verified
+
+**174 cases** across the tools, apply, account and fleet-join suites.
+
+## [0.8.4] — 2026-10-14
+
+**The last connection — the one that makes the feature user-facing.**
+
+### The gap
+
+The `chatops` half derived the fleet key from `userId` and exposed it. The `plugin/tools.mjs` half
+accepted a key and handed it to the agent. **Neither knew about the other**, so the plugin read
+`fleetKey` from config or `W2M_FLEET_KEY` — and a machine with a signed-in account still joined
+nothing without a human setting a variable.
+
+Two halves that each work, with no wire between them, is the same failure as v0.8.1's: the capability
+existed and nothing exercised it.
+
+### Now
+
+`startLocalStack` derives the key itself, from the account, via the same
+`createAccountIdentity({ ctx }).resolve()` the rest of the plugin uses. The derivation belongs there
+because **the host is the only layer that can read the account** — a standalone agent cannot — so the
+key must be produced where `ctx` is available rather than where it is used.
+
+Verified with DSH's own context shape:
+
+```
+ctx.get('deepseekAccount') -> createAccountIdentity({ ctx }).resolve()
+  -> fleetKey (43 chars) -> fleetId d5bb1b9ddf3faad4     (matches the existing derivation)
+  signed-out                 -> named reason, no key invented
+  no account service         -> named reason
+```
+
+### Two failure modes, handled differently on purpose
+
+* A **derivation failure is caught and logged, not thrown** — an unpaired agent still runs and can be
+  paired later, whereas a thrown start is a machine that never appears at all.
+* **`signed-out` is logged at info, not warn** — being signed out is a normal state, and the design
+  says a machine with no account must not be given a random fleet. Warning about it would train an
+  operator to ignore the line that matters.
+
+An explicitly configured `fleetKey` still wins, and the log names which source was used — `paired by
+fleet key (account)` or `(config)` — so nobody has to guess where the key came from.
+
+### A defect in this patch, caught by the compiler
+
+The first edit consumed the `} catch (error) {` line and left the catch body inside the `try`, which
+`node --check` reported immediately. Worth recording because the same edit pattern — replacing a
+block by line range — corrupted a function in v0.8.1 as well.
+
+### Verified
+
+**174 cases** across the tools, apply, account and fleet-join suites.
+
+### This is what closes the reported bug
+
+A new machine, installed and signed into the same account, derives its fleet key, presents it at
+pairing, and lands in the same fleet — **with no key to copy and no operator step**. That is the
+behaviour the original report asked for, and it is now reachable by configuration rather than by
+convention.
+
+## [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

package/package.json

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