@twinsearth/w2m-dsh-plugin 0.8.99-tokenprobe.1 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,173 @@ 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.1] — 2026-10-14
+
+**A powered-off machine stayed `online` and selectable in every fleet view, because `online` was never derived from contact.**
+
+### The report
+
+> *"Another Windows machine, clearly shut down and offline for a long time, is still online and active — not greyed out, still selectable."* And, in the same breath: *"is the fleet heartbeat not synchronised, not updated, not broadcast?"*
+
+All three of those turned out to be one defect with three faces, and the report was exactly right. The relay's own data at the time:
+
+| machine | `online` | `last_heartbeat_at` |
+|---|---|---|
+| `jp-shared` | true | `11:15:55Z` |
+| `macmini` | true | `11:15:41Z` |
+| **`win-desktop` (`549b9fde`)** | **true** | **`null`** |
+| `ToFuture` (here) | true | `11:16:32Z` |
+
+A machine reported `online: true` while `last_heartbeat_at` was `null` — meaning it had **never sent a heartbeat at all**. Two fields in one row contradicted each other and nothing reconciled them.
+
+### The cause
+
+`device.online` was written in exactly two places, and both were the SSE stream:
+
+```js
+device.streams === 0 && this.state.setOnline(sub.machineId, false, 'stream_closed');  // detach
+this.state.setOnline(machineId, true, 'stream_open');                                 // attach
+```
+
+`/v1/devices` then read the flag back:
+
+```js
+online: device.online === true,
+```
+
+**Nothing derived liveness from contact.** So the machine's state was really "is there a TCP connection", and a **half-open stream** — a killed process, a pulled cable, a closed lid; anything that ends the agent without a clean socket close — left `online: true` for as long as the socket survived, which is indefinitely. That is the reported machine: powered off, still listed, still a dispatch target.
+
+The "not broadcast" half is the same cause. `peer.bye` *is* broadcast to every other machine — but it is emitted **by the detach that never came**, so no other machine was ever told either, and every machine picker in the fleet kept offering a departed host.
+
+And the "heartbeat not synchronised" half is the third face: a heartbeat alone could not fix the flag, because the flag did not read heartbeats.
+
+### The fix
+
+**Presence is now expired, next to lease expiry.** A new `sweepSilentDevices()`, driven by the relay's existing 1 s maintenance timer, declares a device silent once nothing has contacted it for `DEFAULT_SILENCE_MS`, and goes through the **existing** `setOnline(id, false, 'silent')` — which both flips the flag and emits `peer.bye`. Going through that path rather than setting the flag directly is the point: correcting only the flag would fix `/v1/devices` on the relay while every agent's own view, and therefore every picker, still showed the departed machine.
+
+**Reads agree between sweeps.** `online` in both `deviceStatus` and `publicDevice` is now derived as well as stored, so nothing has to wait up to a second for a background timer to be told that a machine which stopped talking is gone.
+
+**The threshold is two idle heartbeats (120 s).** An idle agent heartbeats every 60 s and a busy one every 10 s, so the slowest healthy cadence is 60 s and 120 s cannot be reached by a live machine. Deliberately *not* the 20 s lease rule (`heartbeatIntervalMs × missedHeartbeats`): that one guards a task index, where being wrong costs a duplicated execution, while this one guards a display and a target list, where being wrong costs a wasted dispatch. Same reasoning, different price. A test pins the invariant `DEFAULT_SILENCE_MS >= DEFAULT_IDLE_HEARTBEAT_MS * 2`, because a threshold at or below one beat would flap every healthy idle machine.
+
+**`offline_reason` and `silent_ms` are now reported** (`stream_closed` | `silent` | `null`), on `/v1/devices`, in `/v1/status`, and through `w2m_stats`. "Offline" without a reason is precisely the shape that hid this: a departed machine looked identical to a quiet one, and a reader had no field to check.
+
+### What the tests had to be told, twice
+
+Both mistakes are recorded in the test file because both are traps a future reader will fall into:
+
+1. **`RelayServer.handle` calls `touchDevice` on every authenticated request.** The first version of the wire test polled `/v1/devices` *with the token of the machine under test* — so the silent machine refreshed its own `last_seen_at` by asking, and the test read it as online. The observer must be a different device.
+2. **The threshold has to exceed the heartbeat cadence used by the test.** The first version used `silenceMs: 5_000` against a witness that heartbeated every 60 s, so the witness was legitimately swept alongside the machine under test.
+
+A third correction was to the fix itself, and it is the subtle one: `offline_reason` originally tested `device.online !== true` **first**, which reports `stream_closed` for exactly the half-open case — the stream *is* still attached. Silence has to be tested first, or the reason names the wrong thing on the one case that matters.
+
+### Verified
+
+- `test/relay.test.mjs` — **150 tests, 0 failures** (4 new: the sweep plus its broadcast, the pre-sweep read, the healthy-quiet distinction, and the threshold invariant).
+- The 13 suites that touch device or fleet state — **398 tests, 0 failures**.
+- `eslint .` — **0 errors**, 127 warnings.
+
+### Deployment note — this fix is on the wrong side of the wire
+
+The defect lives in the **relay**, so upgrading the plugin does **not** fix a running relay: a machine running v0.9.1 still shows every other machine's stale `online` flag until the relay itself is restarted on v0.9.1. The relay at the shared default address was still serving the stale view when this was written. Restarting it is an operator action, and the relay's own operator token is not something this repository holds.
+
+## [0.9.0] — 2026-10-14
+
+**Three defects that were mounted, wired, and doing nothing — and the lint gate that had stopped being able to say so.**
+
+### The shape all three share
+
+Each was, in the words an earlier release note already used for this class: *the record was created,
+and the part that makes it useful was not filled in*. All three were invisible to the suite, and all
+three were found by reading lint output rather than by running anything.
+
+### 1. `ReferenceError: all is not defined` — on the path an operator actually reaches
+
+`src/relay/state.mjs` threw an undefined identifier while *building a refusal*:
+
+```js
+if (targets.length === 0) {
+  throw new ProtocolError('NO_ONLINE_DEVICE', 'no paired device available for this task', {
+    known_devices: all.length,          // ← `all` exists nowhere in the file
+  });
+}
+```
+
+`targets` is empty exactly when the fleet has nothing to dispatch to — a freshly configured machine
+before its first peer joins, or a fleet whose machines are all scoped out. So the one case where the
+operator needs the detail most answered with a `ReferenceError` instead of the refusal. The count they
+need is the **unfiltered** device set, because the answer distinguishes *"nothing is paired"* from
+*"something is paired but scoped out"*; that is `this.devices`, the same collection handed to
+`targetsFor` a few lines above.
+
+The project's own lint audit records `no-undef` as the rule that "caught the one real defect" of its
+round, and notes why it matters: *an unbound identifier in an ESM module is a `ReferenceError` at
+evaluation time, not an `undefined` that quietly takes a branch.* This is the same defect one release
+later.
+
+### 2. The in-process agent's status was built and then dropped
+
+`src/plugin/tools.mjs` documented a feature and never performed it:
+
+```js
+// §8.2: when the agent runs inside this process its `rttMs` is reachable directly, so `w2m_status`
+// can report it without a file.
+const statusGetter = agent.status ?? agent.state ?? null;      // ← and nothing else
+```
+
+`readRtt` opens with `if (inProcessAgentStatus)` and skips the whole in-process branch when it is
+null. Nothing ever assigned it, so on a machine whose agent *is* in that process the tool fell through
+to reading a state file and reported:
+
+```
+no agent round-trip time is available: the agent is not running in this process and no agent
+state file was found under <stateDir>
+```
+
+— wrong twice, and wrong in the direction that costs most: it tells the reader to doubt the agent, on
+the one call they make to find out what is actually happening. The getter is now assigned.
+
+### 3. A parameter that promised a binding it never made
+
+`src/chatops/bridge.mjs` had `function actionsFor(windowKey)` under a doc line claiming the window was
+"bound in", and a body that never mentioned `windowKey`. The real binding is per call
+(`pending: (window) => broker.listFor(window)`), so the parameter is gone rather than renamed: a
+caller passing a window there was reading a promise the signature did not keep.
+
+### The lint gate, which is why nobody saw any of this
+
+`eslint .` reported **155 errors**, and the release pre-flight requires zero — so the gate was red, and
+a gate that is red for 117 pieces of noise is a gate nobody reads. Which is how three defects sat in
+the tree.
+
+| Rule | Count | Disposition |
+|---|---|---|
+| `no-console` | 117 | **Configuration.** Every one is in `scripts/` — `ilink-*.mjs` operator probes whose entire output *is* a transcribed QR flow, and `chatops-*-e2e.mjs` end-to-end drivers whose value is their trace. The rule's rationale ("a leftover debug statement") does not describe a file that returns nothing to a caller. `scripts/**` joins `bin/**` and `deploy/**` in the existing exception; `src/` and `test/` keep it at error. |
+| `no-unused-vars` | 20 | 13 dead imports removed; 7 unused **bindings** annotated with a leading underscore, per the config's own convention. Two of those are load-bearing calls whose *result* is unused — `stats = await lstat(lexical)` is how a missing file is detected — so the call stays and the binding is annotated. |
+| `no-promise-executor-return` | 4 | The idiomatic `new Promise((r) => setTimeout(r, ms))`. The rule is right that the executor returns a value; braces remove it without changing what the promise does. |
+| `prefer-const` | 2 | Both real; one (`cursor`) carried a `let` that suggested a resumption the script does not implement. |
+| `no-sequences` | 4 | Comma-operator arrows in a test, rewritten as block bodies — same order, same value, readable without knowing the operator. |
+| `no-loss-of-precision` | 2 | **Dispositioned, not fixed.** These are the nineteen-digit measured `message_id` values the iLink contract fixture exists to demonstrate: JavaScript rounds them on parse, and a production path recovers the exact digits from the raw text *because* of that. Quoting the literals would delete the case under test, so they carry a scoped `eslint-disable` with the reason inline. |
+
+Result: **0 errors**, measured with the repository's own config and `--report-unused-disable-directives`,
+so a suppression that no longer suppresses anything fails the run instead of sitting there looking
+like it does.
+
+`docs/LINT-AUDIT.md` keeps its measurements as written and gains an addendum for this round, because
+an audit document that silently disagrees with the tree is worse than no audit document.
+
+### Verified
+
+- `node scripts/verify-join.mjs` — 16/16, unchanged by the edits above.
+- `node scripts/check-entrypoints.mjs` — all entry points import.
+- The four touched suites — **119 tests / 25 suites / 0 failures** (`chatops-commands`,
+  `chatops-ilink-contract`, `chatops-approval`, `chatops-durability`).
+- `eslint .` — 0 errors.
+
+The three defects do **not** carry new tests, and that is a stated gap rather than an oversight: each
+sits on a path the existing suite does not construct (an empty target set at dispatch, an in-process
+agent status getter, a bridge action set built with an argument). They were found by lint and fixed by
+reading the surrounding contract; a test for each is the honest next step.
+
 ## [0.8.11] — 2026-10-14
 
 **The in-process join threw before it could pair — and a missing fingerprint took the fleet key with it.**

package/deploy/mac/mac-self-update.mjs

@@ -31,8 +31,8 @@
  * Usage: node mac-self-update.mjs --tarball <path> --sha256 <hex> [--verify-fleet <url>]
  */
 
-import { execFileSync, spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, rmSync, readdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -120,7 +120,7 @@ function findDshProcess() {
  * `machineName` is read from the environment the agent was started with, falling back to the
  * hostname — the relay lists machines by the name they paired under.
  */
-async function fleetHasMachine(url, name) {
+async function fleetHasMachine(url, _name) {
   try {
     const res = await fetch(new URL('/healthz', url).toString(), { signal: AbortSignal.timeout(10_000) });
     const body = await res.json();
@@ -133,7 +133,7 @@ async function fleetHasMachine(url, name) {
   }
 }
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
 
 async function main() {
   const install = findInstall();

package/docs/LINT-AUDIT.md

@@ -12,6 +12,51 @@
 
 ---
 
+## Addendum — v0.9.0: the gate was cleared, and this document is why it had to be
+
+*The measurements above are left exactly as written. They were correct for 2026-10-08 and they are
+the record of a real decision. But they no longer describe the tree, and a reader arriving at this
+file today would draw the wrong conclusion from it — so the change is recorded here rather than by
+editing the numbers.*
+
+**What happened between then and v0.9.0.** The audit's disposition for most findings was "report, do
+not fix", on the reasoning that ~30 findings were rule noise on idiomatic code and that rewriting
+working code to satisfy a heuristic is the wrong trade. That reasoning still holds. What changed is
+volume: the tree grew `scripts/ilink-*.mjs` and `scripts/chatops-*-e2e.mjs`, which between them added
+**117 `no-console` errors** — every one of them a CLI script for which the console *is* the output
+channel. `eslint .` went from 31 blocking errors to **155**.
+
+The consequence is the one this document could not have anticipated: a lint gate that is red for 117
+pieces of noise is a gate nobody reads, and **three real defects then sat in the tree undetected** —
+including `ReferenceError: all is not defined` in `src/relay/state.mjs`, thrown while building a
+refusal on the exact path an operator reaches when their fleet has nothing to dispatch to. §3.1's
+claim that `no-undef` is "what caught the one real defect" was true, and it stayed true: `no-undef`
+caught this one too, once anyone was reading.
+
+**What v0.9.0 did about it**, per rule (full reasoning in `CHANGELOG.md`):
+
+| Rule | Then | Now |
+|---|---|---|
+| `no-console` | 31 blocking, all in `test/`+`src/` as errors | 117 moved to **configuration**: `scripts/**` joins `bin/**`+`deploy/**` in the existing `no-console: off` block. `src/` and `test/` unchanged. |
+| `no-unused-vars` | 21 | 13 dead imports removed, 7 unused bindings annotated `_`-prefixed. |
+| `no-promise-executor-return` | 31 (demoted to warn in `test/`+`scripts/`) | The 4 **errors** in `src/`/`deploy/` given braces. The warnings are untouched. |
+| `prefer-const` | — | 2 fixed. The rule's report on `scripts/ilink-talk.mjs`'s `cursor` was correct: the `let` implied a resumption the script does not implement. |
+| `no-sequences` | — | 4 fixed in `test/chatops-commands.test.mjs`. |
+| `no-loss-of-precision` | — | 2 **dispositioned**, not fixed: the nineteen-digit measured ids that the iLink fixture exists to demonstrate. Scoped `eslint-disable` with the reason inline. |
+| `no-useless-assignment`, `no-control-regex` | off / left as error (§1.2) | Unchanged. `no-control-regex` still has no occurrence to fire on. |
+
+**Current state: 0 errors, 127 warnings.** Measured with this repository's config plus
+`--report-unused-disable-directives`, so a suppression that has stopped suppressing anything fails the
+run rather than remaining as decoration.
+
+**What §1.1 still costs, and it is not fixed by any of this.** Type-aware rules remain unavailable,
+so `@typescript-eslint/no-floating-promises` — the canonical "you forgot `await`" check — is still
+absent. Two of the three defects v0.9.0 fixed were *unused* things (an unassigned variable read
+nowhere, a parameter mentioned nowhere), which `no-unused-vars` catches; the third was `no-undef`. A
+missing `await` would still be invisible. That conclusion is unchanged.
+
+---
+
 ## 0. TL;DR
 
 | Question | Answer |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.8.99-tokenprobe.1",
-  "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.",
+  "version": "0.9.1",
+  "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",
   "bin": {
@@ -110,6 +110,23 @@
       "optional": true
     }
   },
+  "scripts": {
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.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: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/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 .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "verify": "node scripts/check-entrypoints.mjs && node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/tools.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/p2p-node.test.mjs test/p2p-agent.test.mjs test/client-bundle.test.mjs test/loader-entry.test.mjs",
+    "test:p2p": "node --test --test-force-exit test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/stun-server.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs"
+  },
   "keywords": [
     "dsh-bundle",
     "dsh-plugin",
@@ -134,22 +151,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT",
-  "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.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: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/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 .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "verify": "node scripts/check-entrypoints.mjs && node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/tools.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/p2p-node.test.mjs test/p2p-agent.test.mjs test/client-bundle.test.mjs test/loader-entry.test.mjs",
-    "test:p2p": "node --test --test-force-exit test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/stun-server.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs"
-  }
-}
+  "license": "MIT"
+}

package/src/chatops/bridge.mjs

@@ -241,8 +241,16 @@ export function createBridge(options) {
     return { action: routed.kind, name: routed.name, refusal: routed.refusal, taskId: routed.taskId };
   }
 
-  /** The action set the command table sees, with the window bound in. */
-  function actionsFor(windowKey) {
+  /**
+   * The action set the command table sees.
+   *
+   * v0.9.0: this took a `windowKey` and never used it. The doc line above used to claim the window
+   * was "bound in", which was not true of the body -- the real binding is that `pending` takes the
+   * window per call (`broker.listFor(window)`), so the injected set is window-independent by design.
+   * The parameter is gone rather than renamed: a caller passing a window here was reading a promise
+   * the signature did not keep.
+   */
+  function actionsFor() {
     const injected = options.actions ?? {};
     return {
       ...injected,

package/src/chatops/file-safety.mjs

@@ -164,9 +164,13 @@ export function createFileReader(options) {
     // Cheap refusal first, so a traversal never even reaches the filesystem.
     if (!contains(root, lexical)) return refuse(FILE_REFUSAL.ESCAPED, `lexical: ${lexical}`);
 
-    let stats;
+    // The binding is unused by design: the *call* is the check. A missing path must be refused with
+    // `MISSING` here rather than surfacing as a `realpath` failure below, because the two are
+    // different answers for the caller -- "there is no such file" versus "there is one and it escapes
+    // the root". Underscored, per the config's own convention for an unused binding.
+    let _stats;
     try {
-      stats = await lstat(lexical);
+      _stats = await lstat(lexical);
     } catch {
       return refuse(FILE_REFUSAL.MISSING, relPath);
     }

package/src/chatops/fleet.mjs

@@ -111,7 +111,7 @@ export function createFleetExecutor(options) {
   const timeoutMs = options.timeoutMs ?? 30_000;
   const doFetch = options.fetch ?? globalThis.fetch;
   const now = options.now ?? (() => Date.now());
-  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => { setTimeout(r, ms); }));
   const audit = options.audit ?? (() => {});
 
   /** One relay call. Resolves for every HTTP status: a refusal is an answer, not an exception. */

package/src/chatops/ilink.mjs

@@ -36,17 +36,7 @@ import { CHANNEL_STATE, CHANNEL_FEATURE } from './channel.mjs';
 // from here; the definitions live in ilink-protocol.mjs, which is what the contract suite pins.
 export * from './ilink-protocol.mjs';
 import { createTransport } from './ilink-transport.mjs';
-import {
-  QR_BASE_URL,
-  ENDPOINTS,
-  BOT_TYPE,
-  LOGIN_STATUS,
-  MESSAGE,
-  baseInfo,
-  isAllowedApiUrl,
-  extractText,
-  messageId,
-} from './ilink-protocol.mjs';
+import { QR_BASE_URL, ENDPOINTS, BOT_TYPE, MESSAGE, baseInfo, isAllowedApiUrl, extractText, messageId } from './ilink-protocol.mjs';
 
 /** Long poll: the platform holds the request open this long, so the deadline must exceed it. */
 const LONG_POLL_MS = 35_000;
@@ -117,7 +107,7 @@ export function createILinkChannel(options = {}) {
     return apiBase;
   }
 
-  const url = (endpoint) => new URL(endpoint, QR_BASE_URL).toString();
+  const _url = (endpoint) => new URL(endpoint, QR_BASE_URL).toString();
 
   /** One request, with the outcome returned as data. Never throws on a business refusal. */
   async function call(endpoint, body, { base = null, authenticated = true, timeoutMs = 20_000, signal } = {}) {

package/src/chatops/index.mjs

@@ -37,7 +37,7 @@ import { createILinkChannel } from './ilink.mjs';
 import { isAllowedApiUrl } from './ilink-protocol.mjs';
 import { createFleetExecutor } from './fleet.mjs';
 import { createChatopsActions } from './actions.mjs';
-import { createAccountIdentity, parseSn, fleetOf, SN_STATE_KEY } from './account.mjs';
+import { createAccountIdentity, SN_STATE_KEY } from './account.mjs';
 import { helpText, commandTable } from './commands.mjs';
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';

package/src/chatops/outbound-queue.mjs

@@ -120,7 +120,7 @@ export function createOutboundQueue(options) {
   const random = options.random ?? Math.random;
   const audit = options.audit ?? (() => {});
 
-  const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const realSleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
   const sleep = options.sleep ?? realSleep;
 
   /** window -> lane -> { tail, pending, lastSentAt } */

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.8.11';
+const PLUGIN_VERSION = '0.9.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -4621,6 +4621,17 @@ export async function apply(ctx, config = {}) {
                 machine_id: d?.machine_id ?? null,
                 machine_name: d?.machine_name ?? null,
                 online: d?.online === true,
+                /**
+                 * v0.9.1: why a machine is not usable, when it is not.
+                 *
+                 * Passed through rather than summarised, because "offline" alone was the shape that
+                 * hid the reported defect: a machine powered off for hours was listed `online` and
+                 * selectable, and there was no field anywhere that would have said otherwise. A
+                 * relay older than v0.9.1 sends no such field, so this reads `null` there rather than
+                 * inventing a reason.
+                 */
+                offline_reason: d?.offline_reason ?? null,
+                silent_ms: d?.silent_ms ?? null,
                 rtt_ms: d?.rtt_ms ?? null,
                 rtt_stale: d?.rtt_stale ?? null,
                 last_heartbeat_at: d?.last_heartbeat_at ?? null,
@@ -4930,7 +4941,7 @@ async function startLocalStack(ctx, cfg) {
         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));
+          await new Promise((resolve) => { setTimeout(resolve, waitMs); });
         }
       }
       // Not fatal: the caller may pair by code, and a later attempt may still succeed.
@@ -5057,7 +5068,6 @@ async function startLocalStack(ctx, cfg) {
     /** True when the last attempt failed without sending anything to the relay. */
     let joinLastWasKeyless = false;
     let joinSucceeded = false;
-    let joinAttempts = 0;
     let joinLastError = null;
     async function joinFleet() {
       if (joinSucceeded) return { paired: true, by: 'existing token' };
@@ -5067,7 +5077,6 @@ async function startLocalStack(ctx, cfg) {
       if (coolingDown) return joinPromise;
       joinPromiseAt = Date.now();
       joinPromise = (async () => {
-        joinAttempts += 1;
         if (alreadyPaired) {
           joinSucceeded = true;
           ctx.logger?.info?.(`w2m: already paired (token in ${loaded.path}); not pairing again`);
@@ -5190,10 +5199,29 @@ async function startLocalStack(ctx, cfg) {
     }
     if (!alreadyPaired) scheduleJoinRetry();
 
-    // §8.2: when the agent runs inside this process its `rttMs` is reachable directly, so `w2m_status`
+    // §8.2: when the agent runs inside this process its `rttMs` is reachable directly, so `w2m_status`
     // can report it without a file. When the agent is its own process this stays null and the tool
     // says so instead of guessing.
+    //
+    // v0.9.0: **this assignment is the whole feature, and it was missing.**
+    //
+    // The getter was built and then dropped on the floor, so `inProcessAgentStatus` stayed `null` for
+    // the life of the process. `readRtt` opens with `if (inProcessAgentStatus)` and skips the entire
+    // in-process branch when it is null -- so it fell through to reading a state file, and reported
+    //
+    //   no agent round-trip time is available: the agent is not running in this process and no agent
+    //   state file was found under <stateDir>
+    //
+    // on a machine whose agent *was* in that process and *was* publishing that file. The wording is
+    // wrong twice over, and it is wrong in the direction that costs the most: it tells the reader to
+    // doubt the agent, on the one call they make to find out what is actually happening.
+    //
+    // This is the defect shape the release notes keep recording -- *the record was created and the
+    // part that makes it useful was not filled in* -- and it is the same shape as the identity line
+    // fixed above. ESLint's `no-unused-vars` is what surfaced it: the variable was read nowhere
+    // because nothing was ever assigned to the thing it was meant to feed.
     const statusGetter = agent.status ?? agent.state ?? null;
+    if (typeof statusGetter === 'function') inProcessAgentStatus = statusGetter;
 
   return async () => {
     clearJoinRetry();

package/src/relay/server.mjs

@@ -1086,6 +1086,18 @@ export class RelayServer {
   /** Periodic maintenance, called by the sweep timer. */
   maintenance() {
     const expired = this.sweep();
+    /**
+     * v0.9.1: presence expiry, alongside lease expiry.
+     *
+     * `this.sweep()` writes off lease *holds*; this writes off *presence*. They were conflated, so a
+     * machine that stopped existing was only ever noticed when its SSE stream detached — and a
+     * half-open stream never detaches.
+     */
+    const silent = this.state.sweepSilentDevices();
+    if (silent.length > 0) {
+      this._log(`[w2m-rabbit] marked ${silent.length} silent device(s) offline: `
+        + silent.map((s) => `${s.machine_name} (${Math.round(s.silent_ms / 1000)}s)`).join(', '));
+    }
     this.pairLimiter.prune();
     this.peers.sweep();
     // Keep the nonce cache from growing without bound in a long-running process.

package/src/relay/state.mjs

@@ -16,7 +16,7 @@ import { createHash, randomBytes } from 'node:crypto';
 // v0.7.7: fleet scoping. Imported rather than inlined so the rule has one home with its own
 // exhaustive tests — three lines inside this object would be untestable without a live relay.
 import { targetsFor } from '../chatops/fleet-wiring.mjs';
-import { fleetForPairingCode, deviceFleetFields } from '../chatops/fleet-wiring.mjs';
+import { deviceFleetFields } from '../chatops/fleet-wiring.mjs';
 // v0.8.1: the account-derived fleet key, so a machine can join with no pairing code.
 import { planJoin } from '../chatops/fleet-join.mjs';
 
@@ -121,6 +121,37 @@ export const MAX_RTT_MS = 24 * 60 * 60 * 1000;
 export const DEFAULT_RTT_STALE_MS = 180_000;
 /** v0.3.0: recommended cadence for an agent with no lease (reference for the agent side). */
 export const DEFAULT_IDLE_HEARTBEAT_MS = 60_000;
+
+/**
+ * v0.9.1: how long a device may stay `online` without any contact before the relay calls it silent.
+ *
+ * ## The defect this closes
+ *
+ * `online` was written in exactly two places, both driven by the SSE stream: set true when a
+ * subscriber attached, false when it detached. **Nothing derived it from contact.** So a machine
+ * whose process died without the TCP connection closing — a half-open stream, which is what a killed
+ * process or a yanked network path leaves behind — stayed `online: true` in `/v1/devices`
+ * indefinitely, and stayed selectable as a dispatch target. Reported from a real fleet: a Windows
+ * machine powered off hours earlier was still listed online, with `last_heartbeat_at: null` to say it
+ * had never heartbeated at all.
+ *
+ * `peer.bye` did not help either, because it is emitted *by* the stream closing (`setOnline(…, false)`
+ * on detach). With no close there is no bye, so the machine was never removed from any other
+ * machine's fleet view either — which is the "not broadcast" half of the same report.
+ *
+ * ## The threshold
+ *
+ * An idle agent heartbeats every {@link DEFAULT_IDLE_HEARTBEAT_MS} (60 s), and a busy one renews its
+ * lease every {@link DEFAULT_HEARTBEAT_INTERVAL_MS} (10 s), so the *slowest* healthy cadence is 60 s.
+ * Two skipped idle beats is therefore 120 s: a live machine cannot reach it, and a dead one is
+ * noticed within two cycles plus the sweep tick.
+ *
+ * Deliberately longer than `heartbeatIntervalMs * missedHeartbeats` (the 20 s lease rule): that rule
+ * is about holding a *task index*, where being wrong costs a duplicated execution. This one is about
+ * a display and a target list, where being wrong costs a wasted dispatch. Same reasoning, different
+ * price, so not the same number.
+ */
+export const DEFAULT_SILENCE_MS = DEFAULT_IDLE_HEARTBEAT_MS * 2;
 export const ENVELOPE_VERSION = '1.0';
 export const FINGERPRINT_ALGO = 'git-temp-index-tree/v1';
 
@@ -416,6 +447,11 @@ export class RabbitState {
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
     this.missedHeartbeats = options.missedHeartbeats ?? DEFAULT_MISSED_HEARTBEATS;
     this.leaseGraceMs = options.leaseGraceMs ?? DEFAULT_LEASE_GRACE_MS;
+    /**
+     * v0.9.1: how long an `online` device may go without contact before it is declared silent.
+     * See {@link DEFAULT_SILENCE_MS} for why this is not the lease number.
+     */
+    this.silenceMs = options.silenceMs ?? DEFAULT_SILENCE_MS;
     /**
      * v0.4.0: how long the relay holds its own offer back when the dispatcher says it will push the
      * offer over the direct path (`origin_machine_id` + `p2p.mode`).
@@ -1049,6 +1085,67 @@ export class RabbitState {
     };
   }
 
+  /**
+   * v0.9.1: how long since this device last made any contact, or null when it never has.
+   *
+   * `last_seen_at_ms` is the right field rather than `last_heartbeat_at_ms`: `touchDevice` advances it
+   * on every contact the relay accepts — a heartbeat, a task poll, a lease renewal — so it measures
+   * "is anything there", while `last_heartbeat_at_ms` measures "has it ever heartbeated", which is
+   * null for an agent old enough not to send them.
+   *
+   * Falls back to `paired_at_ms` so that a device which paired but has not spoken since is judged
+   * from the moment it arrived rather than from `null`, which would have read as "silent forever" and
+   * marked it offline the instant it appeared.
+   *
+   * @param {object} device
+   * @param {number} nowMs
+   * @returns {number|null}
+   */
+  silenceAgeMs(device, nowMs = this.nowMs()) {
+    const seen = device.last_seen_at_ms ?? device.last_heartbeat_at_ms ?? device.paired_at_ms ?? null;
+    if (seen === null || seen === undefined) return null;
+    return Math.max(0, nowMs - seen);
+  }
+
+  /**
+   * v0.9.1 §4.3 companion: declare a device silent once nothing has contacted the relay for
+   * {@link DEFAULT_SILENCE_MS}.
+   *
+   * ## Why this exists next to `sweepExpired`
+   *
+   * `sweepExpired` writes off lease *holds*; this writes off *presence*. Both are expiry, and they
+   * were conflated: a machine that stopped existing was only noticed when its SSE stream actually
+   * detached, so a half-open stream — a killed process, a pulled cable, a laptop lid — left it
+   * `online: true` and selectable for as long as the socket stayed open, which can be hours or
+   * indefinitely.
+   *
+   * Going through {@link setOnline} is the point rather than an implementation detail: it flips the
+   * flag **and emits `peer.bye`**, which is what tells every other machine in the fleet. Fixing only
+   * the flag would correct `/v1/devices` on the relay while leaving every agent's own view — and
+   * therefore every machine picker — still showing a departed machine.
+   *
+   * @param {number} [nowMs]
+   * @returns {Array<{machine_id: string, machine_name: string, silent_ms: number}>} what was swept
+   */
+  sweepSilentDevices(nowMs = this.nowMs()) {
+    const went = [];
+    for (const device of this.devices.values()) {
+      if (device.online !== true) continue;
+      const age = this.silenceAgeMs(device, nowMs);
+      if (age === null || age < this.silenceMs) continue;
+      this.emit('notice', {
+        level: 'info',
+        code: 'DEVICE_SILENT',
+        message: `machine ${device.machine_name} (${device.machine_id}) stopped making contact; marking it offline`,
+        machine_id: device.machine_id,
+        silent_ms: age,
+      });
+      this.setOnline(device.machine_id, false, 'silent');
+      went.push({ machine_id: device.machine_id, machine_name: device.machine_name, silent_ms: age });
+    }
+    return went;
+  }
+
   /**
    * v0.3.0 single-machine status view.
    *
@@ -1056,19 +1153,37 @@ export class RabbitState {
    * between them is the whole point: a machine can be heartbeating (alive) while
    * its RTT number is old (a v0.2.3 agent that never sends `rtt_ms`), and a
    * machine can be gone while a plausible-looking RTT is still on file.
+   *
+   * v0.9.1: `online` is additionally cross-checked against silence, so a direct call to this method
+   * (a test, or a caller that never runs the sweep) cannot report a departed machine as present.
+   * The sweep is still what fixes the flag and broadcasts; this only refuses to repeat a stale `true`.
    */
   deviceStatus(machineId, nowMs = this.nowMs()) {
     const device = this.devices.get(machineId);
     if (!device) return null;
     const rttAt = device.rtt_at_ms ?? null;
     const lastHeartbeat = device.last_heartbeat_at_ms ?? null;
+    const silentMs = this.silenceAgeMs(device, nowMs);
+    const silent = device.online === true && silentMs !== null && silentMs >= this.silenceMs;
     return {
       machine_id: device.machine_id,
       machine_name: device.machine_name,
       relay_id: this.relayId,
       connected: (device.streams ?? 0) > 0,
       streams: device.streams ?? 0,
-      online: device.online === true,
+      online: device.online === true && !silent,
+      /**
+       * Why this machine is not usable, when it is not. `null` for a healthy one.
+       *
+       * Added because "offline" without a reason is exactly the shape that made this defect hard to
+       * see: a machine that had been powered off for hours was listed `online`, and a machine that is
+       * correctly offline still gives no clue whether it is gone or merely quiet.
+       *
+       * `silent` first, for the same reason as in `publicDevice`: the stored flag is `true` in the
+       * half-open case, so the silence is the finding.
+       */
+      offline_reason: silent ? 'silent' : (device.online !== true ? 'stream_closed' : null),
+      silent_ms: silentMs,
       rtt_ms: device.rtt_ms ?? null,
       rtt_at: rttAt === null ? null : rfc3339(rttAt),
       rtt_age_ms: this.rttAgeMs(device, nowMs),
@@ -1089,6 +1204,9 @@ export class RabbitState {
 
   /** Public device view — never leaks device_token. */
   publicDevice(device) {
+    // Computed once, so the three fields below cannot disagree with each other.
+    const silentMs = this.silenceAgeMs(device);
+    const silent = silentMs !== null && silentMs >= this.silenceMs;
     return {
       machine_id: device.machine_id,
       machine_name: device.machine_name,
@@ -1114,8 +1232,28 @@ export class RabbitState {
         // list is read by every device, and there is no reason to hand every machine every other
         // machine's key when the verification happens relay-side.
         public_key_present: typeof device.public_key === 'string' && device.public_key !== '',
-      online: device.online,
+      /**
+       * v0.9.1: `online` is derived, not just read.
+       *
+       * It used to be the raw stored flag, which is only ever written by the SSE stream attaching or
+       * detaching. A half-open stream therefore reported `online: true` for a machine that was gone,
+       * and `/v1/devices` handed that to every machine picker in the fleet. The sweep is what flips
+       * the stored flag and broadcasts `peer.bye`; this expression makes the read agree with it even
+       * between sweeps, so no caller can observe the stale value at all.
+       */
+      online: device.online === true && !silent,
       streams: device.streams,
+      /**
+       * v0.9.1: why this machine is not usable, when it is not.
+       *
+       * `silent` is tested FIRST, and that order is the whole subtlety: a half-open stream leaves the
+       * stored `online` flag `true`, so testing `device.online !== true` first reported
+       * `stream_closed` for a machine whose stream was precisely the thing still attached. The
+       * reported defect in one line -- the flag says connected, the truth says gone, and the reason
+       * has to name the truth.
+       */
+      offline_reason: silent ? 'silent' : (device.online !== true ? 'stream_closed' : null),
+      silent_ms: silentMs,
       paired_at: rfc3339(device.paired_at_ms),
       last_seen_at: rfc3339(device.last_seen_at_ms),
       // v0.3.0: `null` means "never measured", which is NOT the same as 0ms.
@@ -1488,7 +1626,25 @@ export class RabbitState {
 
     if (targets.length === 0) {
       throw new ProtocolError('NO_ONLINE_DEVICE', 'no paired device available for this task', {
-        known_devices: all.length,
+        /**
+         * v0.9.0: `all` was never defined here — this threw `ReferenceError: all is not defined`
+         * instead of the refusal it was written to be, and it did so on **the one path an operator
+         * actually reaches**: `targets` is empty exactly when the fleet has nothing to dispatch to,
+         * which is what a freshly configured machine sees before its first peer joins.
+         *
+         * The count an operator needs there is "how many devices does this relay know at all",
+         * because the answer distinguishes *"nothing is paired"* from *"something is paired but
+         * scoped out"* — and `targets` being fleet-filtered cannot answer that. `this.devices` is
+         * the unfiltered set the same call hands to `targetsFor` a few lines above (see the
+         * `devices: [...this.devices.values()]` there), so its size is that number.
+         *
+         * ESLint's `no-undef` found this, which is the rule the project's own lint audit credits as
+         * "what caught the one real defect" of that round. This is the same class of defect one
+         * release later, and the audit's note about it is worth repeating: an unbound identifier in
+         * an ESM module is a `ReferenceError` at evaluation time, not an `undefined` that quietly
+         * takes a branch.
+         */
+        known_devices: this.devices.size,
       });
     }