@twinsearth/w2m-dsh-plugin 0.8.3 → 0.8.5

package/CHANGELOG.md

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

package/package.json

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

@@ -121,7 +121,9 @@ import { mintPunchId, punchSession } from '../agent/p2p.mjs';
 // rather than reimplemented: the dispatcher and the executor have to derive the *same* keys, and two
 // implementations of a handshake are two chances to disagree about it.
 import { DeviceKey } from '../agent/crypto.mjs';
-import { loadOrCreateIdentity } from '../agent/identity.mjs';
+import { loadOrCreateIdentity, saveDeviceToken } from '../agent/identity.mjs';
+import { probeCapsDetailed, detectPlatform } from '../agent/caps.mjs';
+import { resolveStateDir } from '../util/cli.mjs';
 import { parseServer } from '../agent/stun.mjs';
 // The result-deduplication identity the relay mints. Imported rather than re-implemented: the value
 // is compared byte for byte by the executor, so a second copy of the formula that drifted by one
@@ -4230,6 +4232,24 @@ export async function apply(ctx, config = {}) {
   // -------------------------------------------------------------------------------------------
   if (cfg.autoStartAgent) {
     ctx.effect?.(() => startLocalStack(ctx, cfg));
+  } else {
+    /**
+     * v0.8.5: **say it out loud.**
+     *
+     * This branch is the whole reason a machine can run v0.8.4 with the account-derived fleet key,
+     * hold a valid signed-in account, reach the relay over HTTP 200, and still be in no fleet —
+     * with nothing anywhere reporting a problem. The eight tools register, the plugin looks
+     * healthy, and the join sequence simply never runs.
+     *
+     * A silent no-op that looks like success is the worst failure mode this plugin has had. One
+     * line at warn level turns *"why is this machine not in my fleet"* from an investigation into a
+     * log search.
+     */
+    ctx.logger?.warn?.(
+      'w2m: no agent is running on this machine, so it is in no fleet and will receive no work. '
+      + 'Set autoStartAgent: true to join (the fleet key is derived from the signed-in account), '
+      + 'or run w2m-localside yourself and point it at the relay.',
+    );
   }
 
   // ---------------------------------------------------------------------------------------------
@@ -4620,6 +4640,25 @@ async function startLocalStack(ctx, cfg) {
      * So: pair by the **account fleet key** when one is available, fall back to a pairing code, and
      * only stand up a local relay when the configured URL actually is local.
      */
+    /**
+     * v0.8.5: a usable state directory, because an empty one THROWS.
+     *
+     * `createAgent` rejects a falsy `stateDir` (`createAgent: stateDir is required`), and the
+     * plugin's resolved default is the empty string. So `autoStartAgent: true` with `stateDir`
+     * unset threw as well -- a SECOND gate behind the first, and the two together meant the
+     * join sequence could not run even when someone flipped the switch.
+     *
+     * Resolved here rather than left to the caller because `w2m_status` reports `cfg.stateDir`
+     * verbatim: showing the resolved path is what makes "where did it write device.json"
+     * answerable instead of a guess.
+     */
+    const resolvedStateDir =
+      typeof cfg.stateDir === 'string' && cfg.stateDir.trim() !== ''
+        ? cfg.stateDir.trim()
+        : resolveStateDir(null, 'localside');
+    if (cfg.stateDir !== resolvedStateDir) {
+      ctx.logger?.info?.(`w2m: stateDir was unset; using ${resolvedStateDir}`);
+
     const target = cfg.rabbitUrl ? new URL(cfg.rabbitUrl) : null;
     const isLocalRelay =
       target === null || ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(target.hostname);
@@ -4629,7 +4668,7 @@ async function startLocalStack(ctx, cfg) {
       relay = await createRelay({
         host: target?.hostname ?? '127.0.0.1',
         port: target?.port ? Number(target.port) : 8787,
-        stateDir: cfg.stateDir,
+        stateDir: resolvedStateDir,
         pairingCode: cfg.pairingCode ?? undefined,
       });
       ctx.logger?.info?.(`w2m: relay listening at ${relay.url ?? '(unknown url)'}`);
@@ -4639,30 +4678,178 @@ async function startLocalStack(ctx, cfg) {
       ctx.logger?.info?.(`w2m: joining the relay at ${cfg.rabbitUrl}`);
     }
 
+    }
+
+    /**
+     * v0.8.6: the identity, and the options needed to WRITE IT BACK.
+     *
+     * loadOrCreateIdentity is read-only. The token it gains at pairing lives only in memory
+     * unless something calls saveDeviceToken -- and nothing in this path did, so a machine could
+     * pair successfully, appear in the relay's device table, and then answer 401 to every
+     * authenticated request after the next restart, because device.json still said device_token:
+     * null.
+     *
+     * The CLI has always done this (in/w2m-localside.mjs: saveDeviceToken(paired.device_token)).
+     * The in-process path was written without it, which is why the symptom looked like a permission
+     * fault rather than a missing line.
+     */
+    const identityOptions = { name: cfg.machineName, rabbitUrl: cfg.rabbitUrl ?? undefined };
+    const loaded = loadOrCreateIdentity(identityOptions);
+
+    /**
+     * v0.8.8: report what this machine IS, not just that it exists.
+     *
+     * `createAgent` accepts `platform` and `caps`, and the CLI has always supplied them. This path
+     * did not, so a machine that joined through the plugin appeared in the relay complete and
+     * correct except for `os: null` and `caps: {}` -- and the capability gate then had nothing to
+     * filter on, which decides what work the machine is offered.
+     *
+     * The same shape as the other defects in this series: the record was created, and the part
+     * that makes it USEFUL was not filled in.
+     */
+    const [{ caps, detail: capDetail }, platform] = await Promise.all([
+      probeCapsDetailed({}),
+      detectPlatform({}),
+    ]);
+    if (capDetail?.notes?.length) {
+      ctx.logger?.info?.(`w2m: capability probe notes: ${capDetail.notes.join('; ')}`);
+    }
+
     const agent = await createAgent({
       rabbitUrl: relay?.url ?? cfg.rabbitUrl,
       // `project`, not `projectDir`: the option `createAgent` documents, and the one it requires.
       project: cfg.projectDir,
-      stateDir: cfg.stateDir,
+      stateDir: resolvedStateDir,
       // The identity the agent announces itself under. Loaded from the same file the CLI uses, so
       // a machine has ONE identity whether the agent runs in-process or as its own process --
       // otherwise each would mint its own keypair and overwrite the other's announcement under a
       // shared machine_id (the v0.6.2 defect, in a new place).
-      identity: loadOrCreateIdentity({ name: cfg.machineName, rabbitUrl: cfg.rabbitUrl ?? undefined }).identity,
+      // The identity options are kept in a variable because the SAME options must be used to write
+      // the device token back. Reading with one set and writing with another is how the plugin and
+      // the CLI ended up each minting a keypair under one machine_id (the v0.6.2 defect).
+      identity: identityOptions.identity,
+      identityPath: loaded.path,
+      caps,
+      platform,
       allowedCommands: cfg.allowedCommands,
     });
+    /**
+     * v0.8.9: derive the fleet key, RETRYING until the account actually answers.
+     *
+     * The account profile is LAZILY loaded: `getPlatformSession().userId` is null until a
+     * successful `getProfile` has happened, and this runs at mount -- before any model call has
+     * touched the profile. So a single read at startup returns "signed out" on a machine that is
+     * signed in, and the fleet key is never derived.
+     *
+     * That also explains an earlier confusing result: v0.8.4 DID pair once, because the profile
+     * happened to be cached by then. A timing-dependent success is the worst kind to debug,
+     * because 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, since a machine that missed at startup never
+     * retried. Re-pairing was the only thing that had been rescuing it.
+     *
+     * So: back off and retry until a real key appears or the budget runs out, and REPORT EVERY
+     * OUTCOME -- including the one that used to say nothing at all. `resolve()` on the stored-SN
+     * path returns ok:true with a null fleetKey, which the old code checked for neither truthy
+     * nor falsy, so that shape produced no log line anywhere. A silent branch in the exact place
+     * that was failing is how this took several rounds to find.
+     */
+    let fleetKey = cfg.fleetKey ?? null;
+    let fleetKeySource = fleetKey === null ? null : 'config';
+    if (fleetKey === null) {
+      const ATTEMPTS = 6;
+      let last = null;
+      for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+        try {
+          const { createAccountIdentity } = await import('../chatops/account.mjs');
+          last = await createAccountIdentity({ ctx, platform: process.platform }).resolve();
+        } catch (error) {
+          last = { ok: false, reason: 'threw', detail: error instanceof Error ? error.message : String(error) };
+        }
+        const key = last && last.ok === true ? last.fleetKey : null;
+        if (typeof key === 'string' && key !== '') {
+          fleetKey = key;
+          fleetKeySource = 'account';
+          ctx.logger?.info?.(`w2m: fleet key derived from the signed-in account on attempt ${attempt} (fleet ${last.accountCode})`);
+          break;
+        }
+        if (attempt < ATTEMPTS) {
+          const waitMs = Math.min(2000 * 2 ** (attempt - 1), 30000);
+          ctx.logger?.info?.(`w2m: no fleet key yet (${describeIdentityFailure(last)}); retrying in ${waitMs}ms`);
+          await new Promise((resolve) => setTimeout(resolve, waitMs));
+        }
+      }
+      if (fleetKey === null) {
+        // Loud, and it names which failure it was: a machine in no fleet must never be quiet.
+        ctx.logger?.warn?.(
+          `w2m: could not derive a fleet key after ${ATTEMPTS} attempts (${describeIdentityFailure(last)}) -- `
+          + 'this machine is in NO fleet and will receive no work', 
+        );
+      }
+    }
+
+    /**
+     * Name what actually went wrong, including the shape that used to say nothing.
+     *
+     * `ok: true` with a null key is the stored-SN path, and it was invisible before: the old code
+     * only logged when `ok === false`, so the one branch that was firing had no output.
+     */
+    function describeIdentityFailure(identity) {
+      if (!identity) return 'no result';
+      if (identity.ok === true) return 'signed in, but the account returned no fleet key (the profile may not be loaded yet)';
+      return `${identity.reason}${identity.detail ? `: ${identity.detail}` : ''}`;
+    }
 
     /**
-     * Pair before starting, because an unpaired agent can fetch no offers.
+     * v0.8.7: **pair only when there is no token**, because the relay rate-limits pairing.
      *
-     * The fleet key is tried first: it needs no operator step and no code to hand over, which is
-     * the whole point of v0.8.1. A pairing code is the fallback for a relay that has no fleet of
-     * its own.
+     * The previous version paired on EVERY start: the fleet key is derived unconditionally, so
+     * `pairBy` was never null and the branch always ran. The relay allows
+     * `pair_rate_limit: 5` per minute, so five restarts inside a minute would hit the limit --
+     * and a rate-limit refusal reads as a pairing failure, which reads as a fleet problem.
+     * 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.
+     *
+     * So the condition is the token: absent -> pair once and persist; present -> leave it alone.
+     * That is also what 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 were the same defect seen from two sides.
      */
-    const pairBy = cfg.fleetKey ? 'fleet key' : cfg.pairingCode ? 'pairing code' : null;
-    if (pairBy !== null) {
+    const existingToken = loaded.identity.device_token;
+    const alreadyPaired = typeof existingToken === 'string' && existingToken !== '';
+
+    const pairBy = fleetKey !== null ? `fleet key (${fleetKeySource})` : cfg.pairingCode ? 'pairing code' : null;
+    if (alreadyPaired) {
+      ctx.logger?.info?.(`w2m: already paired (token in ${loaded.path}); not pairing again`);
+    } else if (pairBy !== null) {
       try {
-        await agent.pair(cfg.pairingCode ?? null, undefined, cfg.fleetKey ?? null);
+        const paired = await agent.pair(cfg.pairingCode ?? null, undefined, fleetKey);
+        /**
+         * v0.8.6: **persist the token.** Without this the pairing is thrown away.
+         *
+         * `agent.pair` sets `identity.device_token` on its in-memory object only. Nothing in this
+         * path wrote it back, so the observable behaviour was: the relay registers the device, the
+         * machine appears in `w2m_devices`, and then every authenticated call 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 CLI has always done this; the in-process path was written without it.
+         * `saveDeviceToken` throws on an empty token rather than storing one, which is the right
+         * shape: a silent null here is exactly the state this line removes.
+         */
+        try {
+          saveDeviceToken(paired?.device_token, identityOptions);
+          ctx.logger?.info?.(`w2m: device token persisted to ${loaded.path}`);
+        } catch (error) {
+          // Named rather than silent: a machine that paired but cannot authenticate is the exact
+          // failure this release exists to remove, and it must not be quiet a second time.
+          ctx.logger?.warn?.(
+            'w2m: paired but the device token could NOT be persisted ('
+            + `${error instanceof Error ? error.message : String(error)}) -- this machine will answer `
+            + '401 to every authenticated call until that is fixed',
+          );
+        }
         ctx.logger?.info?.(`w2m: paired by ${pairBy}`);
       } catch (error) {
         // Named rather than swallowed: an agent that failed to pair runs and does nothing, which