@twinsearth/w2m-dsh-plugin 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -4,6 +4,134 @@ 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.31.0] — 2026-10-15
+
+**The approval gate got a caller, and a draft acceptance definition for 1.0.0.**
+
+### The defect this round started by finding, in the release that had just criticised it
+
+`approval-gate.mjs` shipped in 0.30.0 with a full suite and **no caller** — which is exactly the shape of the
+two defects 0.30.0 had just finished writing into `ROADMAP.md`. **Building a mechanism and wiring it are
+separate acts**, and a mechanism with no caller cannot be told from a finished feature by reading either the
+tests or the source.
+
+It is now on the raise path, and the wiring is asserted rather than described: a real dispatch raises once,
+the queue holds one request, a second raise is **refused by the front door before a request exists**, and the
+queue still holds exactly one. Two more tests pin the asymmetry — reading the queue five times past any raise
+budget, and settling the request — because a gate that also metered *those* would pass a flooding test and
+quietly break the queue.
+
+`approvalRaiseLimitPerMinute` is configurable so a host can set it and so a test can reach the refusal without
+raising thirty requests first. Unset, the gate's own default governs.
+
+### `docs/1.0.0-ACCEPTANCE.md` — a draft for objection
+
+The goal names **分模块 / 分层级 / 分权限**, and a version number means nothing without a definition that can
+fail. The draft lists 21 criteria across the three, each with **where it is checked and whether that check is
+actually running**, under one rule: **a criterion nothing measures is not a criterion.**
+
+Its two honest admissions are the point of writing it:
+
+* **§1.5 — reachability is NOT checked.** Three mechanisms shipped fully tested and completely uncalled in
+  this span. The `claims` suite catches *documentation* drift and **cannot** catch this, because the document
+  and the code can agree while neither is reachable.
+* **§3.11 — the permission gate is OFF by default.** An unset `actorAuthorityLevel` means `enforced: false`
+  and no change, so **a default install dispatches exactly as it did before the permission model existed.**
+  Treating unset as `0` would break every machine that never opted in, so the current behaviour is defensible
+  — but **"off unless configured" cannot be part of a 1.0.0 that claims 分权限.** The draft puts the choice to
+  a reader rather than resolving it: **require a level and refuse to start without one, or ship with the gate
+  off and say so in the README.** Silence is the one option that is not defensible.
+
+It also records what is **not** claimed: no scale statement (3 usable machines of 5), no restart durability for
+the queue, no MacMini verification beyond the four suites measured in 0.28.0, and `P2P_PUNCH_FAILED` still
+UNVERIFIED.
+
+**2 new tests, 0 failures.**
+
+## [0.30.0] — 2026-10-15
+
+**The same ruler on the other two entries: v4.9.0 had the same defect, v4.10.0 did not.**
+
+After 0.29.0 found that v4.8.0's *"driven by the authority model"* was a phrase rather than a mechanism, the
+next two ROADMAP sentences were checked the same way rather than assumed sound.
+
+| Entry | Claim | Verdict |
+|---|---|---|
+| v4.9.0 | cross-session pending-approval index | **real**, substantial |
+| v4.9.0 | **"with the already-shipped rate limiter as its front door"** | **never built** |
+| v4.10.0 | ordered phases, a phase cannot be skipped | **real**, asserted by name |
+| v4.10.0 | weights reproducible from stored inputs | **real**, plus tamper detection |
+| v4.10.0 | dissent retrievable *with* the decision | **real**, and the dissent is inside the seal |
+
+Measured for the missing half: **`approval-index.mjs` imports `authority.mjs` and nothing else** — no
+limiter, no window, no cooldown anywhere in the file — while the shipped `SlidingWindowRateLimiter` sat in
+`relay/server.mjs` with **no approval caller**. Two entries, one defect, and the third entry was genuine:
+**the pattern was not assumed, it was tested.**
+
+### `src/agent/approval-gate.mjs`
+
+**It limits raising and nothing else.** That asymmetry is the design:
+
+* limiting the **view** would limit *knowing what is waiting*, which is the one thing the queue exists for;
+* limiting **settling** would punish the supervisor clearing the backlog — a limit there is a limit on fixing
+  the problem;
+* **raising** is the surface, because the threat is not brute force but **queue flooding**: an agent in a
+  retry loop can raise hundreds of requests and drown out the work that needs attention.
+
+Two more decisions worth naming:
+
+* **The key is an identity, not an address.** A fleet's agents frequently share a host, so an address-keyed
+  budget would apply one allowance to everybody on it — refusing the well-behaved because a neighbour
+  misbehaved. An anonymous caller gets a **shared named budget rather than none**, because *"no id, no key, no
+  limit"* would make forgetting to identify yourself the way to escape the limit.
+* **The default is not the pairing limit.** `DEFAULT_PAIR_RATE_LIMIT_PER_MINUTE` is 5 because pairing is rare
+  and a wrong guess is an attack; raising approvals is ordinary work done in bursts. Inheriting a number built
+  for a different threat would have been the easy mistake.
+
+It composes the shipped `SlidingWindowRateLimiter` rather than writing a second sliding window — the roadmap's
+word was *"already-shipped"*, and two windows in one codebase are two chances to disagree about what a minute
+is. A test asserts the composition.
+
+The absence of `mayList` / `maySettle` / `mayDecide` is asserted **as an absence**, because their presence is
+the defect and a test about flooding would never notice them.
+
+### One error of mine
+
+I looked for the "shared anonymous budget" wording on the **refusal**; it is on the **allow** branch, which is
+where a caller learns which budget they are spending from. The implementation was right and the assertion was
+in the wrong half — seventh time in this project, and the same remedy worked: measuring instead of predicting.
+
+### The layer checker refused my first version, and it was right
+
+Importing the limiter from `relay/server.mjs` made an **`agent` module depend on the `relay` layer**:
+
+```
+relay -> util is not in ALLOWED_EDGES (undeclared)   ← after the first fix attempt
+agent -> relay                                        ← the original refusal
+```
+
+`agent` is rank 2 and `relay` is rank 3, so that edge **points up**. The tempting fix was to add
+`['agent', 'relay']` to the allow-list, which would have **legalised an inversion**. The right fix was to
+notice that `SlidingWindowRateLimiter` **never used anything from the relay** — it holds a `Map` and reads a
+clock — so it belonged in `util` (rank 0, a leaf) all along.
+
+The move cost nothing at runtime, and that is measured rather than assumed: **the relay's own construction
+site already passed `limit` explicitly**, so the class's defaults had never been used. Its `limit` is now
+**required** instead of defaulting to `DEFAULT_PAIR_RATE_LIMIT_PER_MINUTE` — keeping that default would mean
+this leaf importing a relay constant, **the same inversion one level down**.
+
+Two edges are declared, both downward: `['agent', 'util']` and `['relay', 'util']`. The layer model is now
+`clean: every cross-layer edge is declared`.
+
+### Two more of my own errors
+
+* `export { DEFAULT_WINDOW_MS as RATE_LIMIT_WINDOW_MS } from '...'` **re-exports without creating a local
+  binding**, so the relay's constructor threw `RATE_LIMIT_WINDOW_MS is not defined` while the module's public
+  surface looked perfectly correct. **106 tests failed at once**, which is how it was found.
+* I looked for the "shared anonymous budget" wording on the refusal; it is on the allow branch.
+
+**12 tests, 0 failures**, and 197 across the five affected suites.
+
 ## [0.29.0] — 2026-10-15
 
 **v4.8.0 was half shipped, and the ROADMAP said otherwise. The missing half is now built.**

package/ROADMAP.md

@@ -81,14 +81,25 @@ chooser is ever asked about them.
 The lesson is recorded rather than tidied away: **a roadmap sentence is a claim, and this one was checkable
 in one grep.** It stood for several releases because nothing tested the sentence itself.
 
-### v4.9.0 — approval queue and scheduling
+### v4.9.0 — approval queue and scheduling  **shipped in 0.10.0 (index); the rate-limiter front door added in 0.30.0**
 
 **Deliverable.** A cross-session pending-approval index (§4.2's "supervisor reviews every agent's pending
 approvals from one queue"), with the already-shipped rate limiter as its front door. Scheduling stays
 out of scope here — MARL is not buildable at five machines, and pretending otherwise would be the most
 expensive kind of dishonesty in this roadmap.
 
-### v4.10.0 — committee governance
+**Correction, 0.30.0.** The index shipped and is substantial. **"With the already-shipped rate limiter as its
+front door" did not**: measured, `approval-index.mjs` imports `authority.mjs` and nothing else, and the file
+contains no limiter, window or cooldown — while the shipped `SlidingWindowRateLimiter` sat in
+`relay/server.mjs` with no approval caller. The front door was a phrase, exactly as v4.8.0's authority half
+was.
+
+It now exists in `src/agent/approval-gate.mjs`, and **it limits raising and nothing else**. That asymmetry is
+the design, not an omission: limiting the *view* would limit knowing what is waiting, and limiting *settling*
+would punish the supervisor clearing the backlog. The key is the requester's identity rather than an address,
+because a fleet's agents often share a host and an address-keyed budget would blame the wrong machine.
+
+### v4.10.0 — committee governance  **shipped in 0.11.0, and verified against this entry in 0.30.0**
 
 **Deliverable.** The AURA six-role council as a *single* decision engine with the seven phases, weighted
 voting whose weights come from v4.7.0's authority plus reputation, and **dissent retention** — the losing
@@ -98,6 +109,16 @@ a decision auditable later.
 **Falsifying tests.** a phase cannot be skipped; a vote's weights are reproducible from stored inputs; a
 decision with recorded dissent is retrievable *with* the dissent.
 
+**Verification, 0.30.0.** All three are asserted in `test/council.test.mjs`, by name: *"starts in convene and
+moves exactly one phase per advance"* and *"exposes no way to name a destination phase"*; *"reproduces a
+recorded outcome from the stored ballots alone"*, *"is a pure function: same inputs, same weight, no hidden
+state"* and *"detects a tampered weight instead of reproducing it"*; *"retains the losing arguments alongside
+the outcome"* and *"keeps the dissent in the value the seal covers, so it cannot be dropped later"*.
+
+**This entry is the reason the two above it were checked.** v4.8.0 and v4.9.0 each described something that
+was not built; this one described something that was. Rather than assume the pattern, each sentence was
+treated as a claim and tested — which is the practice the two corrections exist to record.
+
 ### v4.11.0–v4.13.0 — scale, defence, integration
 
 Named for completeness, not planned in detail, because planning them now would produce fiction. The

package/docs/1.0.0-ACCEPTANCE.md

@@ -0,0 +1,109 @@
+# What 1.0.0 would have to prove — a draft for objection
+
+**Status: DRAFT, and deliberately incomplete.** Nothing here is an announcement that 1.0.0 is close. This file
+exists because the goal names three properties — **分模块 / 分层级 / 分权限** — and a version number means
+nothing without a definition that can fail. It is written to be argued with, and every row says **where the
+claim is checked and whether that check is actually running**.
+
+The rule applied throughout: **a criterion that nothing measures is not a criterion.** Where a check exists
+but has no caller, that is stated in its own column rather than hidden behind a tick.
+
+---
+
+## 1. 分模块 — modules with a declared identity
+
+| # | Criterion | Checked by | Enforced? |
+|---|---|---|---|
+| 1.1 | Every source module belongs to exactly one declared layer | `scripts/layer-check.mjs` | **yes** — `clean: every cross-layer edge is declared` |
+| 1.2 | Every dependency edge is declared, and every declared edge is used | `scripts/layer-check.mjs` | **yes** |
+| 1.3 | Every suite on disk is named by a script | pre-flight `test wiring`, `claims` | **yes** — reported, not silently ignored |
+| 1.4 | Every document's claim about the artifact matches the artifact | `test/claims.test.mjs` | **yes** — 48 claims, and it has caught real drift |
+| 1.5 | No module is unreachable — every declared thing has a caller | *nothing* | **NO — see §4** |
+
+`1.5` is the row that matters most and is the one **not** satisfied. This span shipped three mechanisms that
+were, for a round each, fully tested and completely uncalled: `field-authority.mjs`, `approval-gate.mjs`, and
+before them `createApprovalIndex`. **A tested mechanism with no caller is indistinguishable from a finished
+feature by reading either the tests or the source.** `1.4` catches *documentation* drift and cannot catch this,
+because the document and the code can agree while neither is reachable.
+
+---
+
+## 2. 分层级 — layers, with a direction
+
+| # | Criterion | Checked by | Enforced? |
+|---|---|---|---|
+| 2.1 | Ranked layer model, declared as data | `scripts/layer-model.mjs` | **yes** |
+| 2.2 | An allow-list of edges, not a denylist | `layer-model.mjs` | **yes** — a new edge is refused and forces a decision |
+| 2.3 | No upward edge | `layer-check.mjs` | **yes** — it refused `agent → relay` in 0.30.0 |
+| 2.4 | The layer a module sits in matches what it uses | `layer-check.mjs` | **yes** — it is how `SlidingWindowRateLimiter` was found mis-layered |
+
+**`2.3` and `2.4` have each caught a real defect in this span**, which is the only evidence that a check is
+worth its place. `2.3` fired when the approval gate reached for a relay module; the fix was to move the shared
+limiter down to `util`, **not** to add the edge.
+
+---
+
+## 3. 分权限 — declared capabilities, and something that consults them
+
+| # | Criterion | Checked by | Enforced? |
+|---|---|---|---|
+| 3.1 | Capabilities declared with a cost and a destructiveness flag | `authority.mjs` (`CAPABILITIES`) | **yes** |
+| 3.2 | Every declared capability is reachable by some band | `auditCapabilities()`, asserted | **yes** |
+| 3.3 | A decision is reached from a real dispatch's own facts | `gateDispatch`, `capabilityForDispatch` | **yes** |
+| 3.4 | The dispatch path consults it | `tools.mjs`, asserted end to end | **yes** — since 0.23.0 |
+| 3.5 | An undeclared capability is refused, not granted or escalated | `permission.test.mjs` | **yes** |
+| 3.6 | Escalation is exactly one band | asserted across the whole table | **yes** |
+| 3.7 | Nothing destructive auto-settles, at any level | `mayAutoSettle`, asserted | **yes** |
+| 3.8 | An escalated dispatch reaches a queue an approver can answer | `w2m_approvals`, asserted end to end | **yes** |
+| 3.9 | The queue's front door meters **raising only** | `approval-gate.mjs`, wired in 0.31.0 | **yes** |
+| 3.10 | Field-level memory acceptance is driven by the same model | `field-authority.mjs` | **mechanism yes, caller NO — see §4** |
+| 3.11 | **The gate is ON by default** | *nothing — it is off* | **NO — see below** |
+
+### `3.11` is the load-bearing gap, and it is a decision rather than an oversight
+
+`actorAuthorityLevel` is **unset by default**, and an unset level means the gate reports `enforced: false` and
+changes nothing. So today, **a default install dispatches exactly as it did before the permission model
+existed.** The reasoning is in `permission.mjs` and it is sound as far as it goes: treating an unset level as
+`0` would refuse every writing dispatch on every machine that never opted in, breaking a working fleet to
+enforce a policy nobody asked for.
+
+**But "off unless configured" cannot be part of a 1.0.0 that claims 分权限**, because a permission system that
+is off is a permission system that is untested in production. The question this file puts to a reader is
+therefore concrete:
+
+> **Should 1.0.0 require `actorAuthorityLevel` to be set, refusing to start without one — or should it ship
+> with the gate off and say so in the README?**
+
+Both are defensible. Silence is not, and neither is claiming 分权限 while it is off.
+
+---
+
+## 4. What is explicitly NOT claimed
+
+Recorded here so that absence is a decision rather than an omission:
+
+| Not claimed | Why |
+|---|---|
+| **Reachability of every module** | nothing measures it (§1.5). Three uncalled mechanisms were shipped in this span. |
+| **The gate is active** | `actorAuthorityLevel` is unset by default (§3.11). |
+| **Field authority reaches the memory layer** | `field-authority.mjs` has no production caller; `w2m_memory` does not use it. |
+| **The queue survives a restart** | it is per-plugin-lifetime by design, and is **not** an audit log. |
+| **Any scale claim** | this fleet is 3 usable machines of 5 paired. `ROADMAP.md` refuses to plan v4.11.0+ for exactly this reason, and `fleet-scale.mjs` refuses to extrapolate from five. |
+| **MacMini verification of everything** | four suites were verified on that machine in 0.28.0; the other 69 were not. |
+| **`P2P_PUNCH_FAILED`** | cause UNVERIFIED; three hypotheses measured and excluded. |
+
+---
+
+## 5. What would make this file finished
+
+1. **A reachability check** — every exported function has a non-test caller, or is declared as
+   interface-only with a reason. Without it, §1.5 stays open and the class of defect that produced three
+   dead mechanisms stays invisible.
+2. **A decision on §3.11**, whichever way it goes, reflected in `README.md` and in the pre-flight.
+3. **Every row above promoted to a check that runs**, so this document becomes a description of the
+   pre-flight rather than a parallel list that can drift from it. **A document that restates what the
+   pre-flight does is a second source of truth, and this project has already paid for one of those.**
+
+This draft deliberately stops short of those three, because each is a decision about what 1.0.0 must be
+rather than a defect to fix, and the person who owns it has not answered the question this session asked in
+round 12: **write the acceptance definition, or keep advancing the roadmap?**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "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",
@@ -113,13 +113,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/layer-model.test.mjs test/memory.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": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/layer-model.test.mjs test/memory.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/memory.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/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/layer-model.test.mjs test/memory.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",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/layer-model.test.mjs test/memory.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 .",
@@ -147,7 +147,8 @@
     "test:installed-version": "node --test --test-force-exit test/installed-version.test.mjs",
     "test:permission": "node --test --test-force-exit test/permission.test.mjs",
     "test:packet": "node --test --test-force-exit test/machine-test-packet.test.mjs",
-    "test:field-authority": "node --test --test-force-exit test/field-authority.test.mjs"
+    "test:field-authority": "node --test --test-force-exit test/field-authority.test.mjs",
+    "test:approval-gate": "node --test --test-force-exit test/approval-gate.test.mjs"
   },
   "keywords": [
     "dsh-bundle",

package/src/agent/approval-gate.mjs

@@ -0,0 +1,112 @@
+/**
+ * The approval queue's front door — the rate limiter v4.9.0 promised and did not have.
+ *
+ * ## What was missing
+ *
+ * `ROADMAP.md` describes v4.9.0 as *"a cross-session pending-approval index …, **with the already-shipped
+ * rate limiter as its front door**"*. The index is real and substantial. Measured: **`approval-index.mjs`
+ * imports `authority.mjs` and nothing else** — the file contains no limiter, no window, no cooldown — while
+ * the shipped `SlidingWindowRateLimiter` sat in `relay/server.mjs` with no approval caller. The front door
+ * was a phrase rather than a mechanism, the same defect as v4.8.0's missing authority half.
+ *
+ * The limiter now lives in `src/util/rate-limit.mjs`. Reaching for it where it was written would have made
+ * this `agent` module depend on the `relay` layer -- an upward edge the layer model refuses, correctly -- so
+ * the shared piece moved down to `util` instead of the edge being legalised.
+ *
+ * ## Why the limit is on raising and not on reading or answering
+ *
+ * The threat is not brute force; it is **queue flooding**. A misbehaving agent in a retry loop can raise
+ * hundreds of requests, and the queue's whole purpose is that the work needing attention is visible. So the
+ * surface to protect is `register`.
+ *
+ * Deliberately **not** limited:
+ *
+ *   * **reading the queue** — limiting the *view* limits *knowing what is waiting*, which is the one thing
+ *     the queue exists to provide;
+ *   * **settling a request** — a supervisor working through a backlog should be able to clear it, and a
+ *     limit there would punish the person fixing the problem.
+ *
+ * ## Why the key is an identity and not an address
+ *
+ * A fleet's agents are frequently on one host, so an address-keyed limit would apply one budget to everybody
+ * on it — refusing the well-behaved because a neighbour misbehaved, which is the wrong machine to blame. The
+ * key is therefore the requester's identity, and an anonymous requester gets its own shared budget rather
+ * than none: **an unidentifiable caller must not be the one caller with no limit.**
+ *
+ * ## Why the default is not the pairing limit
+ *
+ * `DEFAULT_PAIR_RATE_LIMIT_PER_MINUTE` is **5**: pairing is rare and a wrong guess is an attack. Raising
+ * approvals is ordinary work, done in bursts when a machine comes back from being offline. The default here
+ * is higher, and the number is stated as a decision rather than inherited from a limiter built for something
+ * else.
+ */
+// `DEFAULT_WINDOW_MS` is deliberately NOT imported: the limiter applies its own default window when the
+// caller does not name one, and importing it here only to pass it straight back through would be a second
+// place for the same number to live. eslint's no-unused-vars is what surfaced the redundancy.
+import { SlidingWindowRateLimiter } from '../util/rate-limit.mjs';
+
+/** Raising approvals is ordinary work; pairing is not. The two do not share a number. */
+export const DEFAULT_RAISE_LIMIT_PER_MINUTE = 30;
+
+/** The key used for a caller that did not say who it is. Named so it cannot collide with a real identity. */
+export const ANONYMOUS_KEY = 'anonymous';
+
+/** Why a raise was refused. */
+export const GATE_REFUSAL = Object.freeze({
+  RATE_LIMITED: 'APPROVAL_RAISE_RATE_LIMITED',
+});
+
+/**
+ * The front door to an approval index.
+ *
+ * Composes the shipped limiter rather than reimplementing a window — the promise in the roadmap was that the
+ * *already-shipped* limiter would be this, and two sliding windows in one codebase is two chances to disagree
+ * about what a minute is.
+ *
+ * @param {{limit?: number, windowMs?: number, now?: () => number}} [options]
+ */
+export function createApprovalGate(options = {}) {
+  const limiter = new SlidingWindowRateLimiter({
+    limit: Number.isFinite(options.limit) ? options.limit : DEFAULT_RAISE_LIMIT_PER_MINUTE,
+    ...(Number.isFinite(options.windowMs) ? { windowMs: options.windowMs } : {}),
+    ...(typeof options.now === 'function' ? { now: options.now } : {}),
+  });
+
+  /**
+   * Whether one more request may be raised by this requester.
+   *
+   * @param {{id?: string|null, level?: number|null}} requester
+   * @returns {{allowed: boolean, reason_code: string|null, retry_after_seconds: number, detail: string}}
+   */
+  function mayRaise(requester) {
+    const id = typeof requester?.id === 'string' && requester.id.trim() !== '' ? requester.id.trim() : ANONYMOUS_KEY;
+    const verdict = limiter.hit(id);
+    if (verdict.allowed) {
+      return {
+        allowed: true,
+        reason_code: null,
+        retry_after_seconds: 0,
+        detail: id === ANONYMOUS_KEY
+          ? `raised under the shared anonymous budget (${verdict.remaining} left in this window)`
+          : `${id} may raise (${verdict.remaining} left in this window)`,
+      };
+    }
+    return {
+      allowed: false,
+      reason_code: GATE_REFUSAL.RATE_LIMITED,
+      retry_after_seconds: verdict.retry_after_seconds,
+      detail:
+        `${id} has raised ${verdict.limit} request(s) in the last ${limiter.windowSeconds}s; ` +
+        `wait ${verdict.retry_after_seconds}s. The queue is not cleared -- existing requests are untouched and still answerable.`,
+    };
+  }
+
+  /** How much of this requester's budget is left, without spending any of it. */
+  function budgetFor(requester) {
+    const id = typeof requester?.id === 'string' && requester.id.trim() !== '' ? requester.id.trim() : ANONYMOUS_KEY;
+    const hits = limiter.buckets.get(id) ?? [];
+    return { key: id, limit: limiter.limit, window_seconds: limiter.windowSeconds, used: hits.length, remaining: Math.max(0, limiter.limit - hits.length) };
+  }
+
+  return { mayRaise, budgetFor, limiter, raiseLimitPerMinute: limiter.limit, windowSeconds: limiter.windowSeconds };
+}

package/src/plugin/tools.mjs

@@ -129,6 +129,8 @@ import { gateDispatch, approvalRequestFor, raiseApproval } from '../agent/permis
 // v0.24.0: the queue an escalation is raised into. Imported from `src/`, never from `scripts/` -- a
 // `src/` module reaching above itself breaks the published package (see CHANGELOG 0.23.0).
 import { createApprovalIndex } from '../agent/approval-index.mjs';
+// v0.31.0: the approval queue's front door. Written in 0.30.0 and given a caller here.
+import { createApprovalGate } from '../agent/approval-gate.mjs';
 import { AUTHORITY_MAX, isAuthorityLevel } from '../agent/authority.mjs';
 // v0.6.0: the device keypair and the offer's key distribution (`docs/P2P-CRYPTO.md` §4). Imported
 // rather than reimplemented: the dispatcher and the executor have to derive the *same* keys, and two
@@ -193,7 +195,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.29.0';
+const PLUGIN_VERSION = '0.31.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3246,6 +3248,28 @@ export async function apply(ctx, config = {}) {
     return approvals;
   };
 
+  /**
+   * v0.31.0: the rate limiter that is the approval queue's front door.
+   *
+   * ## Why this took a round to arrive
+   *
+   * `approval-gate.mjs` was written in 0.30.0 with a full suite and **no caller** — which is precisely the
+   * defect that same release had just finished documenting in `ROADMAP.md` twice. Building the mechanism and
+   * wiring it are separate acts, and a mechanism with no caller is the thing a reader cannot tell from a
+   * finished feature.
+   *
+   * It guards **raising only**. Reading the queue and settling a request are deliberately unmetered: limiting
+   * the view would limit knowing what is waiting, and limiting the answer would punish the supervisor
+   * clearing the backlog. The threat is queue flooding by a runaway retry loop, and that is a threat against
+   * the raise path.
+   */
+  const approvalGate = createApprovalGate(
+    // Configurable so a host can tighten or loosen it, and so a test can reach the refusal without raising
+    // thirty requests first. Omitted entirely when unset, which leaves the gate's own default in charge --
+    // passing `undefined` through would be the same thing with more ways to be wrong.
+    Number.isInteger(config.approvalRaiseLimitPerMinute) ? { limit: config.approvalRaiseLimitPerMinute } : {},
+  );
+
   // v0.6.1: the two browser routes behind the composer's target control. Additive and optional: a
   // host without `connection.fetch` still gets every tool, and `w2m_status` reports the absence  -   // which is the honest place for it, since a host that has no Connection at all is simply not a web
   // composition and does not need a warning on every headless run.
@@ -3778,6 +3802,24 @@ export async function apply(ctx, config = {}) {
             machineId: null,
             requestedBy: cfg.machineName,
           });
+          // v0.31.0: the raise path passes the front door BEFORE a request exists. A flood of raises is
+          // what the limiter is for, so a refused raise must not have already created the request it was
+          // refused for.
+          const permission = approvalGate.mayRaise({ id: cfg.machineName, level: cfg.actorAuthorityLevel });
+          if (!permission.allowed) {
+            throw new W2MError(
+              'W2M_PERMISSION_APPROVAL_RATE_LIMITED',
+              'W2M_PERMISSION_APPROVAL_RATE_LIMITED: ' + permission.detail,
+              {
+                hint: 'wait for the window to pass and dispatch again; the queue was not cleared and existing requests are still answerable',
+                detail: {
+                  reason_code: permission.reason_code,
+                  retry_after_seconds: permission.retry_after_seconds,
+                  budget: approvalGate.budgetFor({ id: cfg.machineName, level: cfg.actorAuthorityLevel }),
+                },
+              },
+            );
+          }
           const approvalId = randomUUID();
           const raised = raiseApproval(approvalQueue(), request, { approvalId, toolName: 'w2m_run' });
           if (!raised.ok) {

package/src/relay/server.mjs

@@ -38,7 +38,12 @@ import {
 export const DEFAULT_SSE_KEEPALIVE_MS = 15_000; // §3.2: every 15s a `: keepalive` line
 export const DEFAULT_SWEEP_INTERVAL_MS = 1_000;
 export const DEFAULT_PAIR_RATE_LIMIT_PER_MINUTE = 5; // v0.1.2 §6
-export const RATE_LIMIT_WINDOW_MS = 60_000;
+// The window length is a unit and lives with the limiter. Both names are kept: `DEFAULT_WINDOW_MS` is the
+// local binding this module uses, and `RATE_LIMIT_WINDOW_MS` is the name this module has always exported.
+// `export ... from` would NOT have worked here -- it re-exports without creating a local binding, so the
+// constructor below saw `RATE_LIMIT_WINDOW_MS is not defined` while the export itself looked fine.
+import { DEFAULT_WINDOW_MS, SlidingWindowRateLimiter } from '../util/rate-limit.mjs';
+export { DEFAULT_WINDOW_MS as RATE_LIMIT_WINDOW_MS };
 export const DEFAULT_STATE_DIR = path.join(os.homedir(), '.w2m');
 
 /**
@@ -278,62 +283,18 @@ function readSecretValue(value, label) {
  * Per-IP sliding window. Successful pairs count too, otherwise a working pairing
  * code could be used to flush the failure budget.
  */
-export class SlidingWindowRateLimiter {
-  constructor({ limit = DEFAULT_PAIR_RATE_LIMIT_PER_MINUTE, windowMs = RATE_LIMIT_WINDOW_MS, now = Date.now } = {}) {
-    this.limit = limit;
-    this.windowMs = windowMs;
-    this._now = now;
-    /** @type {Map<string, number[]>} */
-    this.buckets = new Map();
-  }
-
-  get windowSeconds() { return Math.round(this.windowMs / 1000); }
-
-  /** Records one attempt and reports whether it is allowed. */
-  hit(key) {
-    if (this.limit <= 0) {
-      return { allowed: true, retry_after_seconds: 0, limit: 0, window_seconds: this.windowSeconds, remaining: Infinity };
-    }
-    const now = this._now();
-    const cutoff = now - this.windowMs;
-    let hits = this.buckets.get(key);
-    if (!hits) {
-      hits = [];
-      this.buckets.set(key, hits);
-    }
-    while (hits.length > 0 && hits[0] <= cutoff) hits.shift();
-
-    if (hits.length >= this.limit) {
-      const retryMs = hits[0] + this.windowMs - now;
-      return {
-        allowed: false,
-        retry_after_seconds: Math.max(1, Math.ceil(retryMs / 1000)),
-        limit: this.limit,
-        window_seconds: this.windowSeconds,
-        remaining: 0,
-      };
-    }
-    hits.push(now);
-    return {
-      allowed: true,
-      retry_after_seconds: 0,
-      limit: this.limit,
-      window_seconds: this.windowSeconds,
-      remaining: this.limit - hits.length,
-    };
-  }
-
-  /** Drop idle buckets so a long-running relay cannot leak memory. */
-  prune() {
-    const cutoff = this._now() - this.windowMs;
-    for (const [key, hits] of this.buckets) {
-      while (hits.length > 0 && hits[0] <= cutoff) hits.shift();
-      if (hits.length === 0) this.buckets.delete(key);
-    }
-  }
-
-  reset() { this.buckets.clear(); }
-}
+/*
+ * The limiter MOVED to `src/util/rate-limit.mjs` in v0.30.0.
+ *
+ * It never used anything from this file, and when the approval gate needed the same window, importing it
+ * from here made an `agent` module depend on the `relay` layer -- which `scripts/layer-model.mjs` refused,
+ * correctly. `agent` is rank 2 and `relay` is rank 3, so the edge points up; moving the class to `util`
+ * (rank 0, a leaf) lets both depend on it in the only direction the model allows.
+ *
+ * Re-exported rather than merely imported, because `SlidingWindowRateLimiter` and `RATE_LIMIT_WINDOW_MS` are
+ * part of this module's published surface and `test/relay.test.mjs` imports the class from here.
+ */
+export { SlidingWindowRateLimiter };
 
 /* ------------------------------------------------------------------ */
 /* server                                                              */
@@ -420,7 +381,7 @@ export class RelayServer {
     /* ---- /v1/pair rate limit (§6) ---- */
     this.pairLimiter = new SlidingWindowRateLimiter({
       limit: this.pairRateLimitPerMinute,
-      windowMs: RATE_LIMIT_WINDOW_MS,
+      windowMs: DEFAULT_WINDOW_MS,
       now: () => this.state.nowMs(),
     });
 

package/src/util/rate-limit.mjs

@@ -0,0 +1,105 @@
+/**
+ * A per-key sliding-window rate limiter, shared by the relay and the agent.
+ *
+ * ## Why this moved here
+ *
+ * It was written inside `src/relay/server.mjs` for pairing, and it does not use anything from the relay — it
+ * holds a `Map` and reads a clock. When the approval gate needed the same window, importing it from `relay`
+ * made an **`agent` module depend on the `relay` layer**, which `scripts/layer-model.mjs` refused:
+ *
+ *   ALLOWED_EDGES: plugin→agent, plugin→util, plugin→relay, relay→chatops, agent→shared, relay→shared
+ *
+ * The checker was right, and the interesting part is what the right fix turned out to be. Adding
+ * `['agent', 'relay']` would have legalised an inversion — `agent` is rank 2 and `relay` is rank 3, so that
+ * edge points *up*. Moving the class down to `util` (rank 0, a leaf) lets both layers depend on it in the
+ * only direction the model allows, and **cost nothing at runtime**: measured, the relay's own construction
+ * site already passed `limit` explicitly, so the defaults here had never been used.
+ *
+ * ## Why the limit has no default
+ *
+ * It used to default to `DEFAULT_PAIR_RATE_LIMIT_PER_MINUTE`. Keeping that would mean this leaf importing a
+ * relay constant, which is the same inversion one level down. It is now required, and the two callers state
+ * their own numbers — which is the honest arrangement, because pairing and raising approvals are limited for
+ * **different reasons** and should not share a figure by inheritance.
+ */
+
+/** One minute, the window both current callers use. Named here because it is a unit, not a policy. */
+export const DEFAULT_WINDOW_MS = 60_000;
+
+/**
+ * Per-key sliding window.
+ *
+ * A key is whatever the caller decides identifies a budget — an address, an account, a machine. This class
+ * does not care which, deliberately: an address-keyed limit and an identity-keyed limit are different
+ * policies, and a limiter that assumed one would make the other awkward.
+ */
+export class SlidingWindowRateLimiter {
+  /**
+   * @param {{limit: number, windowMs?: number, now?: () => number}} options
+   *   `limit` is required. `limit <= 0` disables the limiter, which is a supported configuration and is why
+   *   the check is `<= 0` rather than a truthiness test.
+   */
+  constructor({ limit, windowMs = DEFAULT_WINDOW_MS, now = Date.now } = {}) {
+    if (!Number.isFinite(limit)) {
+      // Refused rather than defaulted. A limiter that silently picks its own figure is a policy nobody wrote,
+      // and the two callers want opposite orders of magnitude (5 for pairing, 30 for approvals).
+      throw new TypeError('SlidingWindowRateLimiter needs a numeric `limit`; the two callers want different ones and neither should be inherited');
+    }
+    this.limit = limit;
+    this.windowMs = windowMs;
+    this._now = now;
+    /** @type {Map<string, number[]>} */
+    this.buckets = new Map();
+  }
+
+  get windowSeconds() {
+    return Math.round(this.windowMs / 1000);
+  }
+
+  /** Records one attempt and reports whether it is allowed. */
+  hit(key) {
+    if (this.limit <= 0) {
+      return { allowed: true, retry_after_seconds: 0, limit: 0, window_seconds: this.windowSeconds, remaining: Infinity };
+    }
+    const now = this._now();
+    const cutoff = now - this.windowMs;
+    let hits = this.buckets.get(key);
+    if (!hits) {
+      hits = [];
+      this.buckets.set(key, hits);
+    }
+    while (hits.length > 0 && hits[0] <= cutoff) hits.shift();
+
+    if (hits.length >= this.limit) {
+      const retryMs = hits[0] + this.windowMs - now;
+      return {
+        allowed: false,
+        retry_after_seconds: Math.max(1, Math.ceil(retryMs / 1000)),
+        limit: this.limit,
+        window_seconds: this.windowSeconds,
+        remaining: 0,
+      };
+    }
+    hits.push(now);
+    return {
+      allowed: true,
+      retry_after_seconds: 0,
+      limit: this.limit,
+      window_seconds: this.windowSeconds,
+      remaining: this.limit - hits.length,
+    };
+  }
+
+  /** Drop idle buckets so a long-running process cannot leak memory. */
+  prune() {
+    const cutoff = this._now() - this.windowMs;
+    for (const [key, hits] of this.buckets) {
+      while (hits.length > 0 && hits[0] <= cutoff) hits.shift();
+      if (hits.length === 0) this.buckets.delete(key);
+    }
+  }
+
+  reset() {
+    this.buckets.clear();
+  }
+}