@twinsearth/w2m-dsh-plugin 0.5.9 → 0.6.1

package/docs/AUDIT.md

@@ -10,6 +10,15 @@ whose evidence cannot be told apart from its assumptions is worse than no audit:
 
 Re-run the checks in §5 rather than trusting this file; it records a moment, not a guarantee.
 
+> **SUPERSEDED — kept as the historical record.** This audit covers **v0.4.1 … v0.5.1**, and it is
+> superseded by **v0.6.0 (2026-10-11)**. It is not being rewritten: what it recorded was true of the
+> build it measured, and a reader who wants to know what that build did should still read it. Two
+> figures in it were **already stale when it was written**, and are called out here rather than
+> silently corrected below: §1's npm row says `@0.5.1, latest`, and §2 says `v0.5.0 installed` — the
+> audit describes the session that built v0.4.1 … v0.5.1, and both rows name a version that had
+> already been superseded by the time a reader could act on them. For the current state, use
+> `CHANGELOG.md` and `README.md`.
+
 ## 1. Designed features: implemented?
 
 | Designed feature | State | Evidence |
@@ -29,7 +38,7 @@ Re-run the checks in §5 rather than trusting this file; it records a moment, no
 | Delivery-ladder documentation + acceptance script | ✅ | **[M]** `deploy/networking/acceptance.mjs` ran against the live fleet; baseline recorded (all three machines on rung 5 for a relay-dispatched task) |
 | npm publication with Trusted Publishing | ✅ | **[M]** `@twinsearth/w2m-dsh-plugin@0.5.1`, latest, with a SLSA provenance attestation |
 | dsh-plugin.org listing | ✅ | **[M]** listed and marked *Verified*; the page's own snapshot is stale (submission issue #141 asks for a re-scan) |
-| TUN/VPN mode | ❌ **deliberately not built** | Decision and reasoning in `deploy/networking/LESSONS.md`: a tunnel is hub-and-spoke, so it would make "the data path is peer-to-peer" false for exactly the traffic a tunnel exists to carry |
+| TUN/VPN mode | ❌ **deliberately not built** | Decision and reasoning in `deploy/networking/LESSONS.md`: a tunnel is hub-and-spoke, so it would make "the data path is peer-to-peer" false for exactly the traffic a tunnel exists to carry. That reasoning applies to adding a **TUN** adapter. It does not describe rung 4, which **is** deployed: a self-hosted WireGuard hub whose tunnelled traffic is named explicitly rather than passed off as server-free. See `deploy/networking/README.md`. |
 
 **Also not built, and known:** the ladder is not yet ordered *data* with per-rung budgets; the
 plugin has no `p2pPort` of its own (only the agent CLI needs one, since a dispatcher only dials out).

package/docs/DEPLOY.md

@@ -141,14 +141,27 @@ real one):
 [w2m-rabbit] trust_proxy=false (X-Forwarded-* ignored)
 [w2m-rabbit] pair_rate_limit=5/min/IP
 [w2m-rabbit] persistence=on dir=/var/lib/w2m revived_devices=0 revived_tasks=0
-  ... plus a banner repeating the OPERATOR TOKEN, which is also written to
-      <state>/operator-token.txt with mode 0600
+  ... plus the OPERATOR TOKEN **on the start that generated it**, and otherwise
+      only where it is stored: <state>/operator-token.txt with mode 0600.
+      Later starts print "operator token (restored) ... NOT printed" instead,
+      because this banner lands in journald / a container log / CI output and
+      that token authorises dispatching to the whole fleet. Print it anyway with
+      --print-operator-token (or W2M_PRINT_OPERATOR_TOKEN=1).
 ```
 
+On that one generating start the value appears **twice, deliberately**: once in
+the `[w2m-rabbit]` line above (stderr — the log copy) and once in the CLI's
+`OPERATOR TOKEN` box (stdout — the handoff a human reads). Two sinks on the start
+that minted the token is not the defect this behaviour fixes; printing it on
+*every* start, restored ones included, was. Every other start prints it in
+neither place unless the opt-in above asks for it.
+
 With `--json`, all of the above goes to **stderr** and stdout carries exactly
 one JSON line; the operator token is reported only as
 `"operatorTokenPresent": true`. Read the token from
-`<state>/operator-token.txt`, never from stdout.
+`<state>/operator-token.txt`, never from stdout — the one exception is the start
+that generated it, which prints it once so a first-time operator is not left
+without it.
 
 - the **pairing code** (`PAIR-XXXXXXXX`) — hand this to each machine, once. It
   **rotates after every successful pairing**, and the new one is printed, so you

package/docs/P2P-CRYPTO.md

@@ -30,7 +30,9 @@ that is actually valuable here and needs no privileges: **its cryptography and i
 * A passive observer anywhere on the path between two machines: task offers, results and file
   fingerprints on the direct UDP channel become unreadable.
 * An off-path attacker who knows a peer's address: without the peer's static private key a forged
-  `HELLO` cannot complete the handshake.
+  `HELLO` cannot complete the handshake, and a forged `REFUSE` cannot be sealed with `k_ref` either.
+  What such an attacker *can* still do is send an unsealed refusal if they can also spoof the punched
+  peer's source address and port — see the does-not-protect list below, which is where that belongs.
 * Replay and reordering of data frames: counters plus a replay window, not hope.
 * A *curious relay operator* reading task data **that travels over the direct channel**. Note the
   relay still sees the control plane — see below.
@@ -42,6 +44,17 @@ that is actually valuable here and needs no privileges: **its cryptography and i
   when, and the aggregate verdict. Metadata is not hidden by this work, and pretending otherwise would
   be worse than saying so.
 * Traffic analysis, or an attacker who can drop packets (availability is the relay's job).
+* **An active attacker who can inject a datagram at a punch address.** `REFUSE` is what tells a
+  dialler "the handshake is impossible, here is why", and the unknown-peer form of it (`NO_PEER_KEY`,
+  `NO_KEY`) is sent precisely when the sender holds no key for the dialler — so it can carry no `k0`
+  proof, and an attacker who can put one such datagram on the wire *from the punched peer's own
+  address and port* can force the recorded outcome: a plaintext channel with `P2P_CRYPTO_NO_KEY`, or —
+  with a terminal refusal — the relay fallback. The v0.6.0 guard (`REFUSE_GUARD` in `src/agent/p2p.mjs`)
+  narrows this to exactly that attacker: a refusal that names another session, arrives from any other
+  address, or carries a `k_ref` seal that does not verify changes nothing, and a sealed refusal cannot
+  be forged without the peer's static private key. A peer that *can* seal its refusal is therefore not
+  downgradable at all; a peer running an older build cannot seal one, and its plaintext fallback has to
+  stay reachable.
 * Any traffic that falls back to the relay, **unless** the relay leg is separately protected. Stage 1
   leaves the relay leg as it is and says so in the ledger (`encrypted: false` for that machine).
 
@@ -96,7 +109,28 @@ session key             k  = HKDF( ECDH(e_i, e_r) ‖ ECDH(s_i, e_r) ‖ ECDH(e_
 * A replayed `HELLO` cannot produce a session key, because the responder's fresh `e_r` never existed
   at the time the original was captured.
 * A machine that does not know the initiator's static key cannot verify `mac` and refuses, naming the
-  reason — never silently downgrading to plaintext.
+  reason. It does **not** silently downgrade to plaintext, and that sentence is narrower than it reads
+  — see the guard below and the residual in §2. What it means precisely is that a *failed handshake*
+  never falls back into the clear by itself: a plaintext channel is only handed back when the peer
+  named `NO_KEY`/`NO_PEER_KEY` **and** that refusal either came with proof or came from the address
+  that answered the punch. The v0.5.9 review broke the earlier, absolute wording with one 13-byte
+  datagram from a third socket, so the absolute wording is gone.
+
+**Refusals, and what makes one evidence rather than a claim.** A `REFUSE` may carry a trailing 48-byte
+MAC, sealed with `k_ref = HKDF(ECDH(e_i, s_r))` — the initiator's ephemeral (public on the wire) and
+the responder's static key (which the responder always holds). Both ends derive it, neither needs the
+other's *static* public key on file, and nobody else can. `NO_PEER_KEY`, `UNKNOWN_PEER`, `BAD_MAC` and
+`REPLAY` are sealed when the sender can; a `VERSION` mismatch is not, because the peer that needs it
+speaks a body layout this build cannot vouch for. A dialler drops a refusal that does not name the
+agreed session, or that arrives from an address the punch never dialled, and it drops a **sealed**
+refusal that would choose a plaintext channel while its seal does not verify. A plaintext-choosing
+refusal with *no* seal is honoured only when it comes from the endpoint that acknowledged the punch —
+that is the form an older build sends, and the reason it is still reachable. A terminal refusal
+(`BAD_MAC`, `REPLAY`, a version mismatch) is honoured from a dialled address whether or not it is
+sealed, and the outcome records which it was (`refusal_authenticated`: `true` proof, `null` no seal,
+`false` a seal that did not verify) so a claim is never mistaken for proof. A dropped refusal is
+recorded (`crypto.ignored_refusals`) and never fails the punch, because a datagram an attacker can
+forge must not be able to deny service either.
 
 **Transport.** ChaCha20-Poly1305 per frame; nonce = four zero bytes followed by a 64-bit
 little-endian counter, per direction (WireGuard's layout). A 64-message sliding replay window. Rekey
@@ -110,7 +144,12 @@ untouched.
 **Fallback, and it is not optional.** If the handshake fails — an older peer, an unknown key, a
 tampered packet — the task proceeds **exactly as today**, over the relay, and the ledger records
 `p2p.encrypted: false` together with the reason. A fleet must never lose a machine because a security
-upgrade could not complete; it must only *say* that it did not.
+upgrade could not complete; it must only *say* that it did not. The one outcome that is not a failure
+is the peer saying it cannot take part at all (`NO_KEY`/`NO_PEER_KEY`): that is a plaintext channel,
+recorded with its reason and with whether the refusal was sealed, and it is the documented outcome
+rather than a downgrade. What §4 does **not** promise is that no datagram can produce it: an
+unsealed refusal from the punched peer's own address can, which is the §2 residual and the reason the
+guard exists.
 
 **Compatibility.** Additive: an older peer ignores the unknown offer fields (that property is already
 pinned by tests) and its frames are plaintext, which the newer peer accepts while recording
@@ -128,7 +167,11 @@ window carry over unchanged.
 
 Unchanged from `deploy/networking/`: the hub makes machines reachable regardless of NAT, and it does
 **not** make them peers — traffic between two clients is forwarded by the hub. It stays a fallback for
-reachability, and the ledger must never label tunnelled traffic as direct.
+reachability. When it carries a task, the ledger's `transport` may describe the socket path — rung 4
+really is a socket between the two machines — but the tunnel **must be named explicitly** wherever it
+carried the traffic (the `p2p` block's `opened_by` / `offer_path`, or an equivalent field), and
+**"direct" must never be read as "the bytes avoided a server"**: here it means "a socket between the two
+machines, forwarded by the hub". Naming the tunnel is the requirement, not falsifying the socket.
 
 ## 7. How any of this is believed
 
@@ -223,3 +266,61 @@ decision nobody has needed yet.
   rediscovered.
 * A v0.4.x/v0.5.x peer is unaffected: it gets the plain channel it always had, and our side records
   `encrypted: false` with a reason. Never silently downgraded, never dropped from the fleet.
+
+### Added by the v0.5.9 review (MEDIUM-4)
+
+The review reproduced a downgrade with one datagram: a third socket on loopback sending a 13-byte
+`HELLO_ACK` whose body is `REFUSE(NO_PEER_KEY)`. Without it the punch refused with
+`P2P_CRYPTO_HANDSHAKE_TIMEOUT` and returned no channel; with it the same punch returned `ok: true` with
+a plaintext channel and recorded `P2P_CRYPTO_NO_KEY` — a live channel where the text of §4 and the
+`cryptoOutcome` comment said none could exist, and a ledger entry blaming the peer. The fix is
+`REFUSE_GUARD` (`src/agent/p2p.mjs`) plus the `k_ref` seal (`src/agent/crypto.mjs`), and it is stated
+here rather than folded into §4 because §4 is the contract as it was agreed:
+
+* a refusal must name the session the punch agreed, and arrive from an address that punch dialled;
+* a **sealed** refusal that would choose a plaintext channel and whose `k_ref` seal does not verify is
+  dropped — an honest peer either seals correctly or sends no seal at all;
+* an *unsealed* refusal that would choose plaintext must come from the endpoint that acknowledged the
+  punch — which is how an older peer, one that cannot seal, keeps its fallback;
+* a *terminal* refusal is honoured from a dialled address sealed or not, and `refusal_authenticated`
+  records whether its seal was proof;
+* a dropped refusal is recorded with a `reason_code` (`P2P_CRYPTO_REFUSE_SESSION_MISMATCH`,
+  `P2P_CRYPTO_REFUSE_UNPUNCHED_SOURCE`, `P2P_CRYPTO_REFUSE_BAD_MAC`,
+  `P2P_CRYPTO_REFUSE_UNCORROBORATED`) and never fails the punch, so forging one is not a cheap denial
+  of service;
+* the outcome now says whether a refusal was proof or a claim (`refusal_authenticated`), because a
+  ledger that cannot tell those apart is the part of the defect that outlives the packet.
+
+**Residual, and it is the honest version of §2's new bullet**: an attacker who can send an unsealed
+refusal *from the punched peer's own address and port* can still force the recorded plaintext outcome,
+or the relay fallback with a terminal refusal, against a peer old enough not to seal. Against a peer
+that seals, it cannot. What no longer works at all is a datagram from anywhere else, one naming
+another session, or a sealed downgrade that does not verify.
+
+**Why a sealed downgrade that does not verify is dropped, and what that costs.** Sealing is not optional
+for a peer that can do it — `k_ref` needs only the ephemeral it already received and the static key it
+already holds — so a *plaintext-choosing* refusal that arrives sealed and fails verification is not a
+peer whose records disagree with ours; it is a datagram somebody assembled. Honouring it as a claim
+would let anyone who can spoof the punched address force plaintext, which is the defect this section
+exists to close. The cost is stated rather than hidden: when **our** stored key for the peer is stale,
+the peer seals its honest refusal with a `k_ref` we cannot reproduce, and what happens next depends on
+which refusal it is. If it is a *downgrade* — the peer also holds no key for us, so it answers
+`NO_PEER_KEY` — the seal fails and the refusal is dropped, so that misconfigured pair falls back to the
+**relay** instead of a plaintext direct channel. If it is *terminal* — the peer does hold a good key for
+us, so the mismatch shows up as `BAD_MAC` — the refusal is still honoured and still named, with
+`refusal_authenticated: false` recording that its seal proved nothing. Either way the task completes,
+the ledger records a fact that is true (`P2P_CRYPTO_HANDSHAKE_TIMEOUT`, or the peer's own named
+refusal) rather than a plaintext channel an attacker could have chosen, and the staleness is the
+operator's to fix. `refusal_authenticated` is what keeps the rest honest, and it is deliberately
+three-valued on the outcome: `true` (a `k_ref` seal verified — proof), `null` (no seal at all: the form
+an older build sends, which proves nothing), `false` (a seal was present and did not verify — the
+stale-key `BAD_MAC` just described, which fails the punch honestly and is simply never counted as
+proof). A reader of the ledger can therefore never mistake "somebody said the peer refused" for "the
+peer proved it refused".
+
+One collision was found and closed while adding the seal: `decodeRefuse` accepted one length and
+validated nothing else, so a genuine `HELLO_ACK` could be read as a refusal — `body[6]` (the first byte
+of a random ephemeral) as the code and `body[7]` as an id length — roughly once in 256 handshakes,
+which would have refused an honest punch. The parse now checks the version byte, both legal lengths and
+that the machine id holds no control bytes; a test bends a real acknowledgement's length byte into the
+collision and asserts it is still not a refusal.

package/docs/PIPELINE-DESIGN.md

@@ -1,11 +1,19 @@
 # Pipeline mode: the design question that has to be answered first
 
-Status: **unresolved, and `pipeline` is deliberately not implemented.** The relay rejects
-`mode: "pipeline"` with `BAD_REQUEST` rather than guessing.
-
-This file exists because the question is not obvious until you try to answer it, and writing the
-analysis down is cheaper than re-deriving it — or than shipping a guess that half the system then
-depends on.
+> **Status: resolved and implemented — keep reading for the reasoning, not for a to-do list.**
+> `pipeline` shipped in **v0.3.4** as **Option C** below (`replicate` applied to a sequence): every
+> machine runs the whole `stages` chain in order, stopping at the first stage that fails, with no
+> cross-machine data flow. `src/relay/state.mjs`'s `createTask` accepts `mode: 'pipeline'`, requires a
+> non-empty `stages` array of at most `MAX_PIPELINE_STAGES` (16) entries, and refuses `index_total > 1`.
+> `CHANGELOG.md`'s `[0.3.4]` entry is the record, and `test/pipeline-e2e.test.mjs` drives a real relay
+> and a real agent over it.
+>
+> **This header used to say "unresolved, and `pipeline` is deliberately not implemented", and that had
+> been false since v0.3.4.** The sections below are left as they were written — the analysis is the
+> reason the answer is Option C and not Option B, and editing the argument to match its conclusion would
+> destroy the only thing this file is good for. Two things in it are now historical rather than
+> current: the recommendation was **Option A**, and Option A is **not** what shipped; and "what
+> implementing Option A requires" describes a plan, not the implementation.
 
 ## What is already settled
 
@@ -71,6 +79,12 @@ it is `replicate` applied to a sequence.
 
 **Option A**, with Option C as a cheap follow-on if useful.
 
+> **What shipped was Option C, not Option A.** v0.3.4 implemented the chain as `replicate` applied to a
+> sequence: no `executor_machine_id`, every machine runs every stage. Option A — "one machine runs the
+> whole chain, composed with `broadcast`" — remains **unbuilt**. The recommendation below is kept as
+> written, because the reasons it gives are still the reasons Option B was refused; the divergence
+> between this recommendation and the shipped behaviour is recorded rather than smoothed over.
+
 Reasons, in order of weight:
 
 1. Option B is the only one that needs cross-machine data flow, and it is the only one whose
@@ -82,14 +96,25 @@ Reasons, in order of weight:
 
 ## What implementing Option A requires
 
+**None of this is a to-do list: Option C was implemented instead (v0.3.4), and it met four of these
+five points on the way.** It is kept because it is still the checklist for Option A if that is ever
+built, and because it records which parts of the system a chain touches.
+
 - `state.mjs`: accept `mode: 'pipeline'` with `stages: [{command_argv, cwd_rel, ...}]`; keep
   `executor_machine_id` meaningful; reject `index_total > 1` for the same reason `broadcast` does.
+  — **Done in v0.3.4 for Option C.** One difference: `executor_machine_id` is *not* used by a
+  pipeline, so a chain cannot be pinned to one machine this way.
 - `agent.mjs`: execute stages in order, stop on the first non-`ok` stage, and report per-stage
   outcomes. This is the substantial part — the envelope currently describes exactly one command.
-- `report.mjs`: a chain failure must be distinguishable from a chain that never started.
-- `tools.mjs`: `w2m_run` gains `stages`.
-- `PROTOCOL`: the new field, and a compatibility note.
+  — **Done in v0.3.4.** The per-stage record travels in the envelope, and `command_hash` binds
+  **every** stage rather than stage 0 alone.
+- `report.mjs`: a chain failure must be distinguishable from a chain that never started. — **Done.**
+- `tools.mjs`: `w2m_run` gains `stages`. — **Done**, and `stages` is refused rather than ignored
+  under any other mode.
+- `PROTOCOL`: the new field, and a compatibility note. — **Done**; the mode enum is in §5.1 and the
+  chain semantics are in §4.1.
 
 **Not verified, and it cannot be verified here:** whether Option A is what was actually wanted. That
 is a product question, not a technical one, and guessing it is how a fleet ends up with a chained
-mode nobody asked for.
+mode nobody asked for. As shipped, the question is answered for Option C by the fact that it exists
+and is tested; whether Option A is *also* wanted is still open.

package/docs/TROUBLESHOOTING.md

@@ -550,9 +550,28 @@ Two consequences that are easy to walk into:
   [["C:\\Program Files\\nodejs\\node.exe", "-e"]]
   ```
 
-  (This is why the pipeline end-to-end suite passes on CI runners — Node lives at
-  a path without spaces there — and can fail locally on a Windows box where Node
-  is installed under `C:\Program Files`.)
+  (This is why the pipeline end-to-end suite used to fail locally and pass on CI
+  runners — Node lives at a path without spaces there — until the entry in that
+  suite was written as an array entry, the form above.)
+
+Three more refusals look like this section's symptom, and each has its own code
+because each has its own remedy:
+
+* `COMMAND_REPARSING_ARGUMENT` — the entry matched, but a **trailing** argument
+  would make the tool load code the entry never named: `node --test
+  --test-reporter=file:///tmp/evil.mjs`, `--import`, `--require`, `-e`, `python -c`,
+  `bash -c`, `git --exec-path`, `make -f`, `tar --to-command`, … Name the argument
+  in the entry if this machine is meant to run it (`["node --test
+  --test-reporter=tap"]`); an entry that merely names the tool is not read as
+  permission to eval.
+* `COMMAND_EXECUTABLE_PATH_MISMATCH` — `argv[0]` is a path, and it is not the
+  file the entry's executable resolves to. `C:\Program Files\nodejs\node.exe` is
+  admitted for the entry `node` only when that is what `node` resolves to; a copy
+  of another program at `E:\Temp\evil\node.exe` is refused, because a copy under an
+  allowed name is a different program.
+* `COMMAND_EXECUTABLE_RELATIVE_PATH` — `argv[0]` is a relative path
+  (`./node.exe`). The working directory comes from the offer, so the path names a
+  different file in every directory; use the bare name or an absolute path.
 
 To see what the machine actually received, ask the relay for the last task and
 read the machine's `refusal_reason`, or run the agent in the foreground: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.5.9",
+  "version": "0.6.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",
@@ -101,11 +101,11 @@
   "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: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/relay.test.mjs",
-    "test:agent": "node --test test/agent.test.mjs",
-    "test:tools": "node --test test/tools.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: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",
     "pack": "node scripts/pack.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/src/agent/agent.mjs

@@ -23,7 +23,7 @@
 
 import { Readable } from 'node:stream';
 import { access, constants as fsConstants } from 'node:fs/promises';
-import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
@@ -141,6 +141,24 @@ export const AGENT_STATE_SCHEMA_VERSION = 1;
  */
 export const AGENT_STATE_PUBLISH_INTERVAL_MS = 30_000;
 
+/**
+ * How many times `publishState()` tries the final `renameSync` before giving up, and the base of
+ * the synchronous backoff between tries (attempt N waits N * base).
+ *
+ * The publish renames a temp file *over* `agent-state.json` while another process may be reading
+ * it -- the plugin in the DSH host, an editor, a backup agent, or an antivirus scanner. On Windows
+ * that contention comes back as `EPERM`/`EACCES` from the rename even though both paths are fine,
+ * and the condition clears within milliseconds; without a retry the publish is lost, and (before
+ * v0.5.10) its temp file was left behind, which is how one live state directory accumulated 266
+ * `agent-state.json.tmp-*` files.
+ *
+ * Bounded on purpose: 5 attempts, and only a retryable error is retried, so a permanent failure
+ * (the destination is a directory, the volume is gone, the paths are on different devices) costs at
+ * most 30ms of synchronous backoff on a diagnostics-only path.
+ */
+export const STATE_RENAME_ATTEMPTS = 5;
+export const STATE_RENAME_BACKOFF_MS = 3;
+
 /**
  * How many times a relay identity change may trigger an *immediate* cursor-less
  * re-attach before the agent falls back to the normal backoff ladder. A healthy
@@ -857,6 +875,56 @@ export class Heartbeat {
   }
 }
 
+/**
+ * Block the current thread for a few milliseconds.
+ *
+ * Only for {@link renameStateFile}'s backoff, and only on the failing path: `publishState()` is
+ * synchronous by design (an async publish would need a queue to keep two publishes from
+ * interleaving), and `Atomics.wait` on a throwaway shared buffer is the one way to wait without
+ * either a busy loop or an async boundary. There is no `await` here to yield at, and each wait is
+ * a handful of milliseconds.
+ *
+ * @param {number} ms
+ */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Is this rename failure the transient Windows-contention kind, rather than a real one? */
+function isRetryableRenameError(error) {
+  const code = error?.code;
+  return code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+
+/**
+ * `renameSync` over the state file, retried briefly while the failure is transient.
+ *
+ * See {@link STATE_RENAME_ATTEMPTS} for why this exists at all. Only a retryable error is retried
+ * and only a bounded number of times, so the caller's "never throws" contract is preserved: the
+ * last error is rethrown for a permanent failure, exactly as a bare `renameSync` would have.
+ *
+ * @param {string} from The temp file this call created.
+ * @param {string} to The published path.
+ * @returns {number} The 1-based attempt that succeeded (a caller-visible fact for tests).
+ */
+function renameStateFile(from, to) {
+  /** @type {unknown} */
+  let lastError = null;
+  for (let attempt = 1; attempt <= STATE_RENAME_ATTEMPTS; attempt += 1) {
+    try {
+      renameSync(from, to);
+      return attempt;
+    } catch (error) {
+      lastError = error;
+      if (attempt === STATE_RENAME_ATTEMPTS || !isRetryableRenameError(error)) throw error;
+      sleepSync(STATE_RENAME_BACKOFF_MS * attempt);
+    }
+  }
+  // Unreachable: the loop either returns or throws. Kept so a future edit cannot make this
+  // function fall off the end and return `undefined` to a caller that expects a count.
+  throw lastError;
+}
+
 // ---------------------------------------------------------------------------
 // The agent
 // ---------------------------------------------------------------------------
@@ -1929,19 +1997,47 @@ export function createAgent(options) {
    * the agent (or a running task) down -- the file is a diagnostic, not a
    * delivery guarantee -- so failure is logged once and otherwise ignored.
    *
+   * v0.5.10 adds the two halves of "the temp file is ours to clean up": the rename is retried
+   * briefly (see {@link renameStateFile}), and a publish that fails outright unlinks its own temp
+   * file. Before that, every failed rename left a `agent-state.json.tmp-*` behind, and a live state
+   * directory that could not rename for a few hours had accumulated 266 of them / 187 KB with the
+   * agent still warning once and carrying on.
+   *
    * @returns {object|null} The snapshot written, or null when the write failed.
    */
   function publishState() {
     const snapshot = agentStateSnapshot();
+    /** @type {string|null} The temp file this call created; null once it has been renamed away. */
+    let tmp = null;
     try {
       mkdirSync(stateDir, { recursive: true, mode: 0o700 });
-      const tmp = `${stateFilePath}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
+      tmp = `${stateFilePath}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
       writeFileSync(tmp, `${JSON.stringify(snapshot, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-      renameSync(tmp, stateFilePath);
+      const attempts = renameStateFile(tmp, stateFilePath);
+      // Renamed: the temp name is gone, so the catch below must not be handed it.
+      tmp = null;
+      if (attempts > 1) {
+        // Named, not silent: contention on this path was invisible before v0.5.10, and the only
+        // trace of it was a growing pile of temp files. One line per publish that needed a retry
+        // is the evidence an operator needs to recognise "something is holding the state file".
+        log('info', `published ${AGENT_STATE_FILE} after ${attempts} rename attempts`, {
+          path: stateFilePath,
+        });
+      }
       state.statePublishedAt = snapshot.updated_at;
       statePublishWarned = false;
       return snapshot;
     } catch (error) {
+      // A publish that failed is a publish whose temp file must not survive it. The unlink is
+      // itself best-effort and never rethrows: this function's contract is "never throws", and the
+      // file it is trying to remove is by definition one nobody wants.
+      if (tmp !== null) {
+        try {
+          unlinkSync(tmp);
+        } catch {
+          /* already gone, or the directory is unwritable -- nothing left to do here */
+        }
+      }
       if (!statePublishWarned) {
         statePublishWarned = true;
         log('warn', `could not publish ${AGENT_STATE_FILE} (diagnostics only; continuing)`, {
@@ -2692,9 +2788,14 @@ export function createAgent(options) {
       }
 
       // ---- 5. allow-list (default-deny) -----------------------------------
+      //
+      // `commandArgv` is the offer's own command line, which for a `pipeline` the relay sets to
+      // `stages[0].command_argv` -- so this check covers the first stage and nothing else. Every
+      // stage is checked below, before any of them runs; see the note there for why the second check
+      // has to exist even though the plugin's pre-flight also checks every stage.
       const allowed = matchAllowedCommand(commandArgv, allowedCommands);
       if (!allowed.allowed) {
-        log('warn', `refused ${offer.task_id}: COMMAND_NOT_ALLOWED`, { argv: commandArgv });
+        log('warn', `refused ${offer.task_id}: ${allowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED}`, { argv: commandArgv });
         await finish({
           offer,
           cwdRel,
@@ -2703,7 +2804,11 @@ export function createAgent(options) {
           anchorsAfter: null,
           execution: null,
           status: 'refused',
-          refusalReason: REFUSAL.COMMAND_NOT_ALLOWED,
+          // The matcher's own code, not a second spelling of it: the plugin's dispatch pre-flight
+          // reports the same literal for the same argv, and `COMMAND_REPARSING_ARGUMENT` and the two
+          // executable-identity codes have to travel the same way or the two ends would disagree
+          // about *why* one command was refused.
+          refusalReason: allowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED,
           warnings,
           startedAt,
           endedAt: new Date().toISOString(),
@@ -2744,6 +2849,48 @@ export function createAgent(options) {
         }))
         : [{ index: 0, command_argv: [...offer.command_argv], cwd_rel: offer.cwd_rel ?? '.', continue_on_failure: false }];
 
+      // ---- 6a. allow-list, again, for **every** stage ----------------------
+      //
+      // Step 5 checked the offer's `command_argv`, which the relay sets to `stages[0].command_argv`
+      // (src/relay/state.mjs) -- so on a chain it vouched for the first stage alone. The plugin's
+      // dispatch-time pre-flight does check every stage (src/plugin/tools.mjs), and its comment says
+      // why: "the allow-list is a default-deny control, and a chain is not an exemption from it".
+      // But that pre-flight runs on the *dispatcher*, and a dispatcher that posts straight to
+      // `/v1/task` with the operator token never calls it. Enforcement on the machine that executes
+      // is the only control that survives a hostile dispatcher, so it has to be here as well.
+      //
+      // The whole chain is refused before anything runs, not at the offending stage: running stages
+      // 1..n-1 of a chain that will not finish would leave side effects from work the caller was
+      // never allowed to ask for, and the plugin's pre-flight refuses the dispatch as a whole for the
+      // same reason. The refusal names the stage index, because "this chain is not allowed" is not
+      // actionable without knowing which stage.
+      for (const stage of plannedStages) {
+        const stageAllowed = matchAllowedCommand(stage.command_argv, allowedCommands);
+        if (stageAllowed.allowed) continue;
+        const code = stageAllowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED;
+        log('warn', `refused ${offer.task_id}: ${code} at stage ${stage.index}`, {
+          argv: stage.command_argv,
+        });
+        await finish({
+          offer,
+          cwdRel,
+          commandArgv,
+          anchorsBefore,
+          anchorsAfter: null,
+          execution: null,
+          status: 'refused',
+          refusalReason: code,
+          warnings,
+          startedAt,
+          endedAt: new Date().toISOString(),
+          // `protocol_violations` is the field a reader already finds a refused stage in (see the
+          // cwd refusal below), and the stage index is the fact that makes it actionable. The
+          // top-level `refusal_reason` carries the code the plugin's pre-flight would have reported.
+          protocolViolations: [`stage ${stage.index}: ${code} - ${stageAllowed.detail}`],
+        });
+        return;
+      }
+
       // The task's timeout is a budget for the whole chain, not per stage. Giving each stage the full
       // timeout would let a 16-stage pipeline run 16x longer than the caller asked for, and the relay
       // would have given up long before.