@twinsearth/w2m-dsh-plugin 0.9.6 → 0.9.8

package/CHANGELOG.md

@@ -4,6 +4,123 @@ 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.8] — 2026-10-14
+
+**The numeric authority model — the layer four of the five roadmap layers depend on — plus a roadmap and a memory write that reports its own outcome.**
+
+### `ROADMAP.md`
+
+The operator's architecture document specifies five layers across v4.7.0–v4.13.0. It lives in the
+repository now, and it states the delta honestly before it states the plan: this repository has **one
+relay and five machines**, against a target of 1,000+ agents. Every release row carries both a
+deliverable and **the observation that would falsify it**, because a row without the second is a feature
+list rather than a plan.
+
+It also refuses three things on the record: it does not adopt a named protocol (InterMesh, A2A, NLIP,
+AIX, MMP) before a line of its wire format exists; it does not build BFT consensus among five machines on
+one relay, where it would add latency and failure modes without adding trust; and it does not specify
+1,000-agent behaviour, because the source document's own §6.4 reports 30–50 agents as the practical limit
+and superlinear "coordination collapse" beyond 100 — **a design not measured at 50 cannot honestly
+specify 1,000.**
+
+### `src/agent/authority.mjs` — v4.7.0
+
+An integer `authority_level` on every actor, the four bands (0–49 ordinary, 50–69 captain, 70–89 org
+admin, 90+ system admin), `matching_exempt_level` as the Unix-root-style exemption, and a decision
+function returning `allow | needs_approval | deny` **with the rule that produced it**.
+
+Why an integer rather than role names: authority appears in four of the five layers — permissions, the
+approval flow, committee voting weights, and the defence hierarchy where a Coordinator outranks an
+Analyst. An enumerated set of names would be re-partitioned by each layer, and every re-partition is a
+place for two of them to disagree.
+
+Three decisions are load-bearing and each is pinned by a test:
+
+- **A rule with no `matching_exempt_level` exempts nobody.** The tempting default is "absent means
+  unconstrained", and it is wrong in the one direction that matters: a rule author who forgets the field
+  would silently create an unrestricted action.
+- **An exemption bypasses membership, not the level floor.** The Unix analogy is exact — root bypasses a
+  file's permission bits, not the requirement that the file exists. A rule that says both is
+  self-contradictory, and the strict half wins.
+- **A derived actor never exceeds its parent.** No rule in the source design grants delegation, and the
+  default an implementation reaches for — "a captain's delegate is a captain" — turns one compromised
+  actor into an escalation path. Where the source is silent, the narrow reading is the safe one.
+
+### `evaluateAll` — a design corrected by its own test
+
+The first draft evaluated every rule and returned the strictest verdict. A test asserting that the rules
+after a gate are not evaluated failed, and the failure was right. `decisive` must be **unique**, or a
+list can hold several non-allow decisions and whichever the caller picks, the *stated* reason for a
+refusal stops being the reason. And a gate is a gate whether it says `deny` or `needs_approval`: in both
+cases the caller's next action is determined and the remaining rules are decoration. It now stops at the
+first non-allow.
+
+### `envelope.memory` — a silent write that now reports
+
+`appendMemory`'s result was deliberately unchecked, so a memory write could not fail a task. That remains
+true — but leaving it entirely *silent* was the right call for the control flow and the wrong one for the
+reader: **a machine whose memory is not being written is indistinguishable from one that has nothing to
+remember**, which is precisely the class of invisible failure this layer exists to end. The envelope now
+carries `memory: {written, file, rotated}` or `{written: false, reason_code}`. It is not a comparable
+field, so no verdict moves and two machines cannot disagree over it.
+
+### Verified
+
+- `test/authority.test.mjs` — **27 tests, 0 failures.** Every one is about a boundary, because the only
+  interesting thing an authority model can get wrong is being off by one: a level too permissive is an
+  escalation and one too strict is an outage, so the band edges and the exemption boundary are asserted
+  **from both sides** rather than by a middle value that would pass either way.
+- Band partition is proven total and non-overlapping across 0..100 by walking every level, so a seam that
+  belongs to two bands — a bug that only appears once someone is assigned that level — cannot exist.
+- `eslint .` — 0 errors on the new module and test.
+
+## [0.9.7] — 2026-10-14
+
+**`w2m_memory` gains the collective layer and the one write a machine may not make for itself.**
+
+### `scope: "fleet"` — the collective memory
+
+Reads the curated `fleet-memory.md` that §3.2 of the design puts on the archive host, beside the profile
+that mounted this plugin. It returns the document **as text, with its section list**, and does not parse
+it into facts — deliberately. Hand-written prose has no schema, so a parser would silently drop whatever
+shape it did not recognise, and what it dropped would be exactly what a human judged worth writing down.
+The section list is there so a reader can see what the collective memory covers before paying for all of
+it.
+
+An absent file is answered honestly rather than as an empty document: `MEMORY_NO_COLLECTIVE`, with the
+path that was looked at. *"Nothing has been curated yet"* and *"the memory is empty"* are different
+facts, and only one of them means someone should start writing.
+
+### `record` — a conclusion, which only a reader may assert
+
+`memoryRecord` always emits `conclusion: null`, because a machine that invented one would be asserting an
+interpretation it cannot have. This is the path by which a reader supplies it: the conclusion is appended
+as a **new record naming the task it is about**, never written into the existing line.
+
+Append-only is the point. In-place editing would break the property that makes the log trustworthy — what
+was written is what happened, and an amendment is a later statement *about* it — and it would destroy the
+original text, which is the thing a reader most needs when a conclusion turns out to be wrong.
+
+### A defect this found in its own first draft
+
+`collectivePath()` was `path.join(resolveProfileDir(cfg), COLLECTIVE_FILE)`. `resolveProfileDir`
+legitimately returns `null` — a bare test context, or a host whose layout it cannot read — and the first
+version passed that straight into `path.join`, which threw `ERR_INVALID_ARG_TYPE`. **A read tool that
+crashes on a missing directory is worse than one that says the directory is missing:** the caller was
+asking a question, and an exception is not an answer. It now resolves to `null`, reports
+`MEMORY_NO_COLLECTIVE`, and says which of the two reasons applies.
+
+### Verified
+
+- `eslint .` — 0 errors.
+- The contract suites — `memory`, `tools`, `tool-cards`, `claims`, `loader-entry`, `update-wiring`,
+  `p2p-plugin` — **230 pass, 0 fail, 11 platform skips**.
+- Every scope exercised against a real temporary profile: `fleet` found the seeded document and listed
+  its five sections; `record` wrote a conclusion against a task and reported that no task existed when
+  none did; an absent collective file produced `MEMORY_NO_COLLECTIVE` rather than a throw.
+- The tool count is unchanged at nine, so this release moves no contract: the same nine tools, two of them
+  wider.
+
 ## [0.9.6] — 2026-10-14
 
 **Individual memory: the fleet can now answer "what did we already try on this machine, and what happened?" — a question nothing in it could answer before.**

package/ROADMAP.md

@@ -0,0 +1,135 @@
+# Fleet roadmap — from a 5-machine fleet to a governed multi-agent system
+
+Status: **plan, with one consumer already written.** This file exists so the roadmap lives in the
+repository rather than in a conversation, and so each version's deliverable can be measured against
+something rather than remembered.
+
+Source: the operator's architecture document (2026-10-14), which specifies five layers — coordination,
+memory, authority/scheduling, committee governance, and defence — across releases v4.7.0 to v4.13.0.
+
+---
+
+## 0. What this repository already is, stated honestly
+
+Before the roadmap, the delta, because a plan that does not say where it starts is a wish.
+
+| Layer | This repository today | The document's target |
+|---|---|---|
+| Networking | one relay, one fleet, five machines; P2P direct path when NAT allows | InterMesh/A2A/NATS-MQTT/libp2p/NLIP federation |
+| Memory | **individual per-machine (shipped 0.9.6), collective curated document (0.9.7), conclusions (0.9.7)** | three-layer memory with field-level acceptance, lineage, consolidation and forgetting |
+| Authority | one operator token; write scope; a global approval rate limiter | numeric `authority_level`, `matching_exempt_level`, a pending-approval index |
+| Governance | none | AURA seven-phase council, weighted voting, recursive Sentinel/MetaSentinel |
+| Scale | five machines, tasks in the hundreds | 1,000+ agents, sub-10 ms coordination, "coordination collapse" mitigation |
+| Defence | hash-only ledger, HMAC signing, BFT-free consensus | three-tier sensor/analyst/coordinator with BFT |
+
+**The gap is four to six orders of magnitude in agent count.** Nothing below claims otherwise, and the
+roadmap is ordered so that what is built first is what the larger system would still need.
+
+---
+
+## 1. The one thing to build first, and why it is the only honest starting point
+
+The document's own structure gives the answer: `authority_level` appears in **four of its five layers**.
+It is in the permission model (§4.1), the approval flow (§4.2), the committee's weighted voting (§5.3,
+weight includes authority) and the defence hierarchy (§2.3, where a Coordinator outranks an Analyst).
+Nothing in the roadmap can be built without it, and building any of the rest first would mean inventing
+authority implicitly — twice, differently.
+
+**And it already has a consumer waiting.** §3.3's P1 is *field-level acceptance*: each agent decides
+per field what to take from a peer, rather than accepting or rejecting a whole message. That is a
+permission decision about a *field*, which is exactly what a numeric authority model expresses. The
+memory layer shipped in 0.9.6/0.9.7 accepts everything or nothing today; `authority_level` is what turns
+it into P1. So this is not a foundation poured in advance of a use — the use is already written.
+
+## 2. Release plan
+
+Each row states its **deliverable** and its **falsifying test** — the observation that would show it is
+not working. A row without the second is a feature list, not a plan.
+
+### v4.7.0 — authority model  ← **next**
+
+**Deliverable.** `src/agent/authority.mjs`: an integer `authority_level` on every actor, the four bands
+(0–49 ordinary, 50–69 captain, 70–89 org admin, 90+ system admin), a rule evaluator carrying
+`matching_exempt_level`, and a decision function returning `allow | needs_approval | deny` with the rule
+that produced it.
+
+**Falsifying tests.**
+- an actor at exactly `matching_exempt_level` bypasses the membership check, and one level below does not
+  (an off-by-one here is an escalation, so the boundary is tested from both sides);
+- an actor never inherits another's level by acting on its behalf — delegation is not assumed, because
+  the document does not grant it and inventing it would be the worst possible default;
+- a rule with no `matching_exempt_level` exempts nobody, rather than exempting everybody.
+
+### v4.8.0 — memory: field-level acceptance (MMP P1/P2)
+
+**Deliverable.** Extend the shipped memory layer: a CAT7 seven-field cognitive block, per-field
+acceptance driven by §2's authority model, and lineage — each accepted claim records the content hash of
+its parent, so a returned claim is identifiable as the receiver's own earlier thought.
+
+**Falsifying tests.** a field refused by policy is *absent* from the stored block rather than null; a
+claim's ancestor chain survives a round trip; a claim whose parent is missing is refused rather than
+silently re-rooted.
+
+### v4.9.0 — approval queue and scheduling
+
+**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
+
+**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
+arguments are stored, because §5.1's "preserves dissenting agents' arguments" is the property that makes
+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.
+
+### v4.11.0–v4.13.0 — scale, defence, integration
+
+Named for completeness, not planned in detail, because planning them now would produce fiction. The
+document's own §6.4 is the reason: it reports 30–50 agents as the practical limit of current frameworks
+and describes superlinear "coordination collapse" beyond 100. **A design that has not been measured at 50
+cannot honestly specify 1,000**, and the bitmask/sub-10 ms claims are targets to be tested, not facts to
+be designed around.
+
+## 3. What this roadmap deliberately refuses
+
+- **It does not adopt a protocol by name.** InterMesh, A2A, NLIP, AIX and MMP are cited in the source
+  document; none is implemented here yet, and listing one as "chosen" before a line of its wire format
+  exists would be a claim no test could falsify. What is implementable now is the *semantics* they share
+  — identity, authority, field-level acceptance, lineage — and that is what v4.7.0 and v4.8.0 build.
+- **It does not build consensus where there is nothing to agree on.** BFT among five machines on one
+  relay adds latency and failure modes without adding trust. It becomes meaningful when there are
+  mutually-distrusting organisations, which is a v4.12.0 precondition, not a v4.7.0 one.
+- **It does not put a governance layer above a fleet that has no disagreements yet.** A council that
+  decides nothing is indistinguishable from a delay. The council earns its place when two fleets want the
+  same machine — and that is measurable, so it can wait for the measurement.
+- **It does not scale the agent count by declaring it scaled.** §6.4's collapse is a real reported
+  phenomenon; the response here is a benchmark before a design, not the reverse.
+
+## 4. Where the numbers in the source document are treated as claims, not facts
+
+Several figures in the source (20–40% faster convergence, 45% storage reduction, 37% stability
+improvement, 85–120 ms decision latency at 100+ agents, 35–42% cache hit rates, 35–78% token reduction)
+come from cited literature on other systems. They are recorded as *expectations to test at this fleet's
+scale*, and no roadmap item above is justified by them. The one number this repository has measured
+itself — the ~50 s task ceiling, from `heartbeatIntervalMs × missedHeartbeats + leaseGraceMs` — is in
+`fleet-memory.md` with its three measurements, and it is the reason every long job here is started
+detached.
+
+## 5. Relationship to the memory layer already shipped
+
+The shipped layer is not a detour from this roadmap; it is §3.1's L2 and part of L3, built early because
+it was cheap and the gap it closed had been paid for repeatedly. Concretely:
+
+- `memory.jsonl` per machine = **L2 individual memory**, persisted, owned by the machine.
+- `fleet-memory.md` on the archive host = **L3 collective memory**, curated rather than generated.
+- `w2m_memory` = the retrieval entry point for both, plus `record` for conclusions.
+- **L1 conversation memory** and §3.2's *emergent* collective memory (environment traces) are **not**
+  built.
+
+The honest summary: the memory layer is at the point where the next thing it needs is authority, which is
+why v4.7.0 is the next thing this roadmap builds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "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",
@@ -28,6 +28,7 @@
     "README.md",
     "CHANGELOG.md",
     "HANDOFF.md",
+    "ROADMAP.md",
     "LICENSE",
     "PROTOCOL.md",
     "PROTOCOL-v0.1.2.md",
@@ -111,13 +112,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.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/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/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/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 .",
@@ -126,7 +127,8 @@
     "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",
-    "test:memory": "node --test --test-force-exit test/memory.test.mjs"
+    "test:memory": "node --test --test-force-exit test/memory.test.mjs",
+    "test:authority": "node --test --test-force-exit test/authority.test.mjs"
   },
   "keywords": [
     "dsh-bundle",

package/src/agent/agent.mjs

@@ -1,4 +1,4 @@
-/**
+/**
  * The Localside agent: everything between "Rabbit hands us an offer" and
  * "Rabbit has our envelope".
  *
@@ -48,7 +48,7 @@ import {
   resolveProjectCwd,
 } from './git.mjs';
 import { createSpool } from './spool.mjs';
-import { appendMemory, memoryRecord } from './memory.mjs';
+import { MEMORY_FILE, appendMemory, memoryRecord } from './memory.mjs';
 import { matchAllowedCommand, parseAllowedCommands } from './allowed-commands.mjs';
 import { CRYPTO_REASON, DEVICE_KEY_FILE, DeviceKey, PeerKeyStore } from './crypto.mjs';
 import { DEFAULT_P2P_MODE, P2P_DEFAULTS, P2PNode, normalizeP2PMode, normalizeP2PPort } from './p2p-node.mjs';
@@ -1094,7 +1094,7 @@ export function createAgent(options) {
   // Loaded here, at construction, rather than lazily at `start()`: the key file is also what a
   // *dispatcher* publishes in an offer, and "which key will this machine present" must not depend on
   // whether a particular code path happened to have run yet. `loadOrCreate` is the documented rule
-  // ("generated the first time a machine pairs"), and a failure is never fatal — see `deviceKeyError`.
+  // ("generated the first time a machine pairs"), and a failure is never fatal  - see `deviceKeyError`.
   const deviceKeyOutcome = loadDeviceKey(options.deviceKey ?? null, stateDir, identity.machine_id, identityPath);
   /** @type {object|null} This machine's static keypair, or null when there is none. */
   const deviceKey = deviceKeyOutcome.key;
@@ -1103,7 +1103,7 @@ export function createAgent(options) {
   /**
    * A key adopted from the pre-v0.6.2 location (`--state/device.key`). Reported once at startup,
    * because a machine whose key moved is a machine whose public key a peer may have learned under the
-   * old file — silence here would make "my peers stopped talking to me" have no visible cause.
+   * old file  - silence here would make "my peers stopped talking to me" have no visible cause.
    */
   const deviceKeyMigratedFrom = deviceKeyOutcome.migratedFrom ?? null;
   /**
@@ -1120,7 +1120,7 @@ export function createAgent(options) {
    * What each task's direct channel actually was, for the result envelope.
    *
    * Keyed by `task_id`, alongside the channel map rather than on the channel itself, because the
-   * envelope is built *after* `planDirectDelivery` may have released the channel — and
+   * envelope is built *after* `planDirectDelivery` may have released the channel  - and
    * `p2p.encrypted` has to describe the channel that carried this attempt, not whichever channel
    * happens to be live when the envelope is written.
    *
@@ -1166,7 +1166,7 @@ export function createAgent(options) {
   const p2pPeers = new Map();
 
   /**
-   * One reverse-dial attempt per `task_id` — the executor's own half of a two-way punch.
+   * One reverse-dial attempt per `task_id`  - the executor's own half of a two-way punch.
    *
    * A record exists for every offer this agent takes on, including the ones it decides *not* to
    * dial for, and that is deliberate: "we did not try, because a channel was already live" and "we
@@ -1444,8 +1444,8 @@ export function createAgent(options) {
    * happened rather than what was possible. `reason` is the named code from that same channel, so
    * `p2p.encrypted: false` always arrives with a *why*.
    *
-   * It is called from both places a channel becomes a task's channel — the offer that arrived on one
-   * and the dial that opened one — and the most recent call wins, which is right: a task's result
+   * It is called from both places a channel becomes a task's channel  - the offer that arrived on one
+   * and the dial that opened one  - and the most recent call wins, which is right: a task's result
    * travels over the channel that is live *now*.
    *
    * @param {string} taskId
@@ -1479,7 +1479,7 @@ export function createAgent(options) {
    *
    * Without this, a task executed entirely over the relay reports `encrypted: false` with no
    * explanation, and a reader cannot tell "this machine has no crypto" from "no direct channel was the
-   * answer for this task" — entirely different operational facts. The reason is the *same* string
+   * answer for this task"  - entirely different operational facts. The reason is the *same* string
    * `offerTransportOf` puts in `p2p.reason`, deliberately: one sentence, decided in one place.
    *
    * It never overwrites a channel's own record: once a channel carried something for this task, which
@@ -2118,7 +2118,7 @@ export function createAgent(options) {
    * Signing headers for one request, or nothing at all.
    *
    * The signed `path` is the **API-relative** path plus its query
-   * (`/v1/stream?machine_id=…&seq=5`), never the URL as sent.
+   * (`/v1/stream?machine_id= - seq=5`), never the URL as sent.
    *
    * That looks backwards -- surely the signature should cover the bytes on the
    * wire? -- so here is the case that settles it. With `rabbitUrl =
@@ -2283,7 +2283,7 @@ export function createAgent(options) {
    *   * a **pairing code** is the operator saying *"let this machine in"*, and it is the only way to
    *     place a device in a fleet the device could not compute for itself;
    *   * a **fleet key** is the account saying *"this machine is mine"*, and the relay derives the
-   *     fleet from it — so it can only ever reach a fleet its holder is already entitled to.
+   *     fleet from it  - so it can only ever reach a fleet its holder is already entitled to.
    *
    * Passing neither remains allowed: the relay answers `PAIRING_INVALID` and the caller reports it,
    * which is the pre-v0.8.1 behaviour for an unpaired machine.
@@ -2298,8 +2298,7 @@ export function createAgent(options) {
     /**
      * Send only the discriminator that was actually given.
      *
-     * `pairing_code: null` would be *present*, and a presence check reads a null as "provided" —
-     * the same trap that made `createILinkChannel` pass `{ fetch: undefined }` and throw on mount in
+     * `pairing_code: null` would be *present*, and a presence check reads a null as "provided"  -      * the same trap that made `createILinkChannel` pass `{ fetch: undefined }` and throw on mount in
      * v0.7.0. An absent code must be an absent key, not a null one.
      */
     if (typeof pairingCode === 'string' && pairingCode !== '') body.pairing_code = pairingCode;
@@ -2419,7 +2418,7 @@ export function createAgent(options) {
    *                   states, and a bound nobody measures is a claim: this is the number that says
    *                   whether the result path really stayed inside it.
    *   * `result_error` -- why the direct copy of *this result* did not land, when one was attempted
-   *                   and not acknowledged (`P2P_ACK_TIMEOUT: …`). Null otherwise; this is the
+   *                   and not acknowledged (`P2P_ACK_TIMEOUT:  - ). Null otherwise; this is the
    *                   `delivery.error` that `p2pDeliveryMark` has always carried and the envelope
    *                   never reported.
    *
@@ -2438,8 +2437,7 @@ export function createAgent(options) {
      *
      * Read from what the agent *recorded* when it held the channel, not from a live object: by the
      * time the envelope is built the channel may have been released, and `p2p.encrypted` has to
-     * describe the channel that carried this attempt. `null` means no channel was ever involved —
-     * a task executed entirely over the relay — which reports `encrypted: false` because that is the
+     * describe the channel that carried this attempt. `null` means no channel was ever involved  -      * a task executed entirely over the relay  - which reports `encrypted: false` because that is the
      * truth about this task's data plane, whatever this machine's keypair could have done.
      */
     const encryption = encryptionFor(offer?.task_id);
@@ -2653,17 +2651,25 @@ export function createAgent(options) {
      * The write happens **after** the envelope is complete, so the record it stores is the same one the
      * relay will judge -- not a second, independently assembled opinion about what happened.
      *
-     * `appendMemory` never throws and its result is deliberately not returned or checked: the task is
-     * the work and this is a note about it, so a full disk or an unwritable directory must not turn a
-     * successful command into a failed task. A memory that can fail work is worse than no memory, and
-     * the failure mode is silent here on purpose -- the envelope's own fields already say what happened.
+     * `appendMemory` never throws and its result never changes the verdict: the task is the work and
+     * this is a note about it, so a full disk or an unwritable directory must not turn a successful
+     * command into a failed task. A memory that can fail work is worse than no memory.
+     *
+     * v0.9.8: its *outcome* is nonetheless reported, as `memory` on the envelope. Leaving it entirely
+     * silent was the right call for the control flow and the wrong one for the reader -- a machine whose
+     * memory is not being written is indistinguishable from one that has nothing to remember, which is
+     * exactly the class of invisible failure this layer exists to end. One optional field, no verdict
+     * moved: it is not a comparable field, so two machines cannot disagree over it.
      */
-    appendMemory(stateDir, memoryRecord({
+    const memoryWrite = appendMemory(stateDir, memoryRecord({
       envelope,
       commandArgv,
       cwdRel,
       ms: (Date.parse(endedAt) - Date.parse(startedAt)) || 0,
     }));
+    envelope.memory = memoryWrite.ok === true
+      ? { written: true, file: MEMORY_FILE, rotated: memoryWrite.rotated === true }
+      : { written: false, reason_code: memoryWrite.error };
 
     return buildEnvelope(envelope);
   }
@@ -3220,7 +3226,7 @@ export function createAgent(options) {
     }
 
     if (channelFor(offer?.task_id) === null) {
-      // No channel at all, so nothing about this task's data plane was ever sealed — and the reason
+      // No channel at all, so nothing about this task's data plane was ever sealed  - and the reason
       // recorded here is the one `offerTransportOf` already decided for `p2p.reason`.
       rememberNoChannel(offer?.task_id, offerTransportOf(offer, p2pStatusSnapshot()).reason);
       return p2pDeliveryMark();
@@ -3282,7 +3288,7 @@ export function createAgent(options) {
 
     const startedAt = process.hrtime.bigint();
     // `machine_id` travels with the notice because the dispatcher has to be able to say *which*
-    // machine finished without waiting for the relay's copy — the plugin names its direct-result
+    // machine finished without waiting for the relay's copy  - the plugin names its direct-result
     // inbox file after it. The frame still carries no envelope: `result_path` is decided by the
     // acknowledgement this frame is waiting for, and `envelope_sha256` covers `result_path`, so
     // sending the envelope first and stamping it afterwards would break the hash it is signed with.
@@ -3415,7 +3421,7 @@ export function createAgent(options) {
         code = null;
       }
       const error = new Error(`stream HTTP ${response.status} ${body.slice(0, 200)}`.trim());
-      // Preserve the relay's own code (SIGNATURE_REQUIRED, SIGNATURE_EXPIRED, …)
+      // Preserve the relay's own code (SIGNATURE_REQUIRED, SIGNATURE_EXPIRED,  - 
       // so a signed link can be diagnosed without guessing.
       error.code = code ?? `HTTP_${response.status}`;
       state.lastRelayError = {
@@ -3568,7 +3574,7 @@ export function createAgent(options) {
         // peer tried to put on the wire is overwritten, so a relay frame can never claim the
         // direct path -- the only thing that sets `'p2p'` here is the channel having delivered it.
         const offer = { ...payload, p2p_transport: source.transport };
-        // v0.6.0: the block's `static_keys` is the *entire* key-distribution mechanism — a machine
+        // v0.6.0: the block's `static_keys` is the *entire* key-distribution mechanism  - a machine
         // learns the keys of exactly the peers it was asked to talk to, from the offer that asked it,
         // and never from a config file. Learned here, before the offer is queued, because the reverse
         // dial starts inside `handleOffer` and a key merged any later would miss the handshake this
@@ -4127,8 +4133,8 @@ export function createAgent(options) {
 /**
  * Load this machine's static keypair, or explain why there is none (v0.6.0).
  *
- * Never throws. A machine whose key file is unreadable is still a working W2M machine — every task
- * still travels over the relay — and `agent.state.p2p.encryption.error` names the file that could not
+ * Never throws. A machine whose key file is unreadable is still a working W2M machine  - every task
+ * still travels over the relay  - and `agent.state.p2p.encryption.error` names the file that could not
  * be read so an operator can fix it. Refusing to start an agent because a *security upgrade* could not
  * complete is exactly the fleet-losing failure `docs/P2P-CRYPTO.md` §4 forbids.
  *
@@ -4138,15 +4144,15 @@ export function createAgent(options) {
  * used to break it: it loaded from the `--state` directory, justified by a comment claiming that
  * `identity.mjs` puts `device.json` there "when the agent is run with `--state`". That claim is false.
  * `device.json` is fixed at `<DSH_HOME>/xclient/device.json` by the identity contract and `--state`
- * does not move it — which is why an agent run as `--state ~/.dsh/xclient/localside-mac` had its
+ * does not move it  - which is why an agent run as `--state ~/.dsh/xclient/localside-mac` had its
  * identity one directory *above* its key.
  *
  * The measured consequence, on one machine running both halves of W2M: the plugin (which loads the key
  * correctly, from `dirname(device.json)`) and the agent each generated a *different* pair, and both
- * announced to the one `/v1/peer/{machine_id}` slot — the relay's record alternated between the two
+ * announced to the one `/v1/peer/{machine_id}` slot  - the relay's record alternated between the two
  * nodes' ports every few seconds, and the `static_key` a dispatcher read was one node's or the other's.
  * A dispatcher that learns the wrong key cannot arm a handshake, so every direct channel came back
- * `P2P_CRYPTO_PLAINTEXT_PEER` — reported as "the peer is an older build" when both ends were the same
+ * `P2P_CRYPTO_PLAINTEXT_PEER`  - reported as "the peer is an older build" when both ends were the same
  * build on the same host.
  *
  * MIGRATION. `DeviceKey.load` warns that "silently generating a replacement key would make every peer
@@ -4168,7 +4174,7 @@ function loadDeviceKey(injected, stateDir, machineId, deviceFile = undefined) {
     return { key: injected, error: null, migratedFrom: null };
   }
 
-  // Beside `device.json` — the documented rule. `identityPath` is the path the caller actually
+  // Beside `device.json`  - the documented rule. `identityPath` is the path the caller actually
   // loaded, never a fresh global resolution: resolving `DSH_HOME` here would make a test (or any
   // caller with an injected identity) read and *create* a key in the real user's home.
   let canonicalDir = null;
@@ -4179,7 +4185,7 @@ function loadDeviceKey(injected, stateDir, machineId, deviceFile = undefined) {
   /**
    * Candidates in order. `mayCreate` is the whole subtlety: only a location that is *the* documented
    * home may mint a key. A legacy directory is consulted to adopt a key that is already there, never
-   * to create one — `DeviceKey.load` warns that generating a replacement "would make every peer that
+   * to create one  - `DeviceKey.load` warns that generating a replacement "would make every peer that
    * knows the old one refuse this machine", so an upgrade must not silently change this machine's
    * public key.
    *

package/src/agent/authority.mjs

@@ -0,0 +1,305 @@
+/**
+ * Numeric authority: who may do what, expressed as an integer.
+ *
+ * ## Why an integer rather than a list of names
+ *
+ * The roadmap has authority appearing in four of its five layers -- the permission model, the approval
+ * flow, committee voting weights, and the defence hierarchy where a Coordinator outranks an Analyst. An
+ * enumerated set of role names would have to be re-partitioned by each of those layers, and each
+ * re-partition would be a place for two of them to disagree. An integer orders every actor on one axis,
+ * so "does A outrank B" is a comparison rather than a lookup table that has to be kept in step.
+ *
+ * The model is Unix-like on purpose: `matching_exempt_level` mirrors root's exemption from file
+ * permission checks. That is a *deliberate* hole in the rules, so it is the most carefully bounded thing
+ * in this file -- see `evaluate`.
+ *
+ * ## The four bands
+ *
+ * | Band | Range | May |
+ * |---|---|---|
+ * | ordinary | 0–49 | create goals and session data within its own scope |
+ * | captain | 50–69 | create team goals, manage team membership |
+ * | org admin | 70–89 | create organisation goals, register actors, set overrides |
+ * | system admin | 90+ | create global goals, configure across organisations, override any lower constraint |
+ *
+ * ## What this module deliberately does not do
+ *
+ * It does not decide *what* an action is, only whether an actor's level satisfies a stated rule. Action
+ * classification -- is this a write, a scope change, a registration -- belongs to whatever knows the
+ * action, and putting it here would mean this file had to be edited every time a new action appeared.
+ * That is how an authority model becomes a bottleneck and then gets bypassed.
+ */
+
+/** The bands, as data rather than as branches, so a reader can enumerate them. */
+export const AUTHORITY_BANDS = Object.freeze([
+  { name: 'ordinary', min: 0, max: 49, may: 'create goals and session data within its own scope' },
+  { name: 'captain', min: 50, max: 69, may: 'create team goals, manage team membership' },
+  { name: 'org_admin', min: 70, max: 89, may: 'create organisation goals, register actors, set overrides' },
+  { name: 'system_admin', min: 90, max: null, may: 'create global goals, configure across organisations, override any lower constraint' },
+]);
+
+/** The highest level this model will accept. Above it, a level is a mistake rather than a promotion. */
+export const AUTHORITY_MAX = 100;
+
+/** Verdicts an authority check can reach. */
+export const AUTHORITY_VERDICT = Object.freeze({
+  ALLOW: 'allow',
+  NEEDS_APPROVAL: 'needs_approval',
+  DENY: 'deny',
+});
+
+/**
+ * Is this a usable authority level?
+ *
+ * Rejects non-integers as well as out-of-range values. `50.5` is not "between captain and org admin"; it
+ * is a value nobody defined, and accepting it would make band boundaries behave differently for actors
+ * that are supposed to be equal.
+ *
+ * @param {unknown} level
+ * @returns {boolean}
+ */
+export function isAuthorityLevel(level) {
+  return Number.isInteger(level) && level >= 0 && level <= AUTHORITY_MAX;
+}
+
+/**
+ * Which band a level falls in, or `null` for a value that is not a level.
+ *
+ * @param {unknown} level
+ * @returns {{name: string, min: number, max: number|null, may: string}|null}
+ */
+export function bandOf(level) {
+  if (!isAuthorityLevel(level)) return null;
+  for (const band of AUTHORITY_BANDS) {
+    if (level >= band.min && (band.max === null || level <= band.max)) return band;
+  }
+  return null;
+}
+
+/**
+ * A rule about an action.
+ *
+ * `minLevel` is the floor for performing it at all. `matchingExemptLevel`, when present, is the level at
+ * or above which the *membership* part of the rule is skipped -- the Unix-root analogy. `scope` names what
+ * the action is performed against, so a refusal can say which rule refused it.
+ *
+ * @typedef {object} AuthorityRule
+ * @property {string} action
+ * @property {number} minLevel
+ * @property {number|null} [matchingExemptLevel]
+ * @property {string|null} [scope]
+ * @property {string} [why]
+ */
+
+/**
+ * Cheap structural validation, separate from evaluation.
+ *
+ * A malformed rule is a configuration defect and should be caught where it is written, not silently
+ * treated as a rule that permits nothing -- "denied" and "misconfigured" look identical from the outside
+ * and only one of them means someone should fix something.
+ *
+ * @param {unknown} rule
+ * @returns {string|null} a reason, or `null` when the rule is well formed.
+ */
+export function ruleProblem(rule) {
+  if (rule === null || typeof rule !== 'object') return 'rule must be an object';
+  if (typeof rule.action !== 'string' || rule.action.trim() === '') return 'rule.action must be a non-empty string';
+  if (!isAuthorityLevel(rule.minLevel)) return `rule.minLevel must be an integer 0..${AUTHORITY_MAX}`;
+  if (rule.matchingExemptLevel !== undefined && rule.matchingExemptLevel !== null
+    && !isAuthorityLevel(rule.matchingExemptLevel)) {
+    return `rule.matchingExemptLevel must be an integer 0..${AUTHORITY_MAX} or null`;
+  }
+  return null;
+}
+
+/**
+ * Evaluate one rule against one actor.
+ *
+ * The order of the three checks is the whole security property, so it is stated rather than implied:
+ *
+ *   1. **Exemption**, and only when the rule names one. An exempt actor skips the *membership* check --
+ *      not the level check, and not the existence of the rule. This is the Unix-root analogy: root
+ *      bypasses a file's permission bits, not the fact that the file must exist.
+ *   2. **Membership**, when the rule has a scope and the caller supplied one. An actor outside the scope
+ *      needs a supervisor, not a refusal, which is why this yields `needs_approval` rather than `deny`.
+ *   3. **Level**, the plain floor.
+ *
+ * A rule with no `matchingExemptLevel` exempts **nobody**. That is the decision most worth stating: the
+ * tempting default is "absent means unconstrained", and it is wrong in the one direction that matters --
+ * a rule author who forgets the field would silently create an unrestricted action.
+ *
+ * @param {AuthorityRule} rule
+ * @param {{level: number, inScope?: boolean|null, id?: string|null}} actor
+ * @returns {{verdict: string, action: string|null, level: number|null, exempt: boolean, reason: string}}
+ */
+export function evaluate(rule, actor) {
+  const problem = ruleProblem(rule);
+  if (problem !== null) {
+    return {
+      verdict: AUTHORITY_VERDICT.DENY,
+      action: rule?.action ?? null,
+      level: actor?.level ?? null,
+      exempt: false,
+      reason: `malformed rule: ${problem}`,
+    };
+  }
+  if (!isAuthorityLevel(actor?.level)) {
+    return {
+      verdict: AUTHORITY_VERDICT.DENY,
+      action: rule.action,
+      level: actor?.level ?? null,
+      exempt: false,
+      reason: `actor has no usable authority level (got ${JSON.stringify(actor?.level ?? null)})`,
+    };
+  }
+
+  const exemptLevel = rule.matchingExemptLevel ?? null;
+  const exempt = exemptLevel !== null && actor.level >= exemptLevel;
+
+  // 2. Membership, skipped entirely for an exempt actor.
+  if (!exempt && rule.scope !== undefined && rule.scope !== null && actor.inScope === false) {
+    return {
+      verdict: AUTHORITY_VERDICT.NEEDS_APPROVAL,
+      action: rule.action,
+      level: actor.level,
+      exempt: false,
+      reason: `outside the scope of "${rule.action}" (${rule.scope}); a supervisor within it may approve`,
+    };
+  }
+
+  // 3. The floor. Checked even for an exempt actor -- see the header.
+  if (actor.level < rule.minLevel) {
+    return {
+      verdict: AUTHORITY_VERDICT.NEEDS_APPROVAL,
+      action: rule.action,
+      level: actor.level,
+      exempt,
+      reason: `level ${actor.level} is below the minimum ${rule.minLevel} for "${rule.action}"`,
+    };
+  }
+
+  return {
+    verdict: AUTHORITY_VERDICT.ALLOW,
+    action: rule.action,
+    level: actor.level,
+    exempt,
+    reason: exempt
+      ? `allowed: level ${actor.level} meets the exemption ${exemptLevel} for "${rule.action}"`
+      : `allowed: level ${actor.level} meets the minimum ${rule.minLevel} for "${rule.action}"`,
+  };
+}
+
+/**
+ * Evaluate several rules, stopping at the first one that is not a plain allow.
+ *
+ * ## Why it stops, rather than evaluating everything
+ *
+ * An earlier draft evaluated all rules and returned the strictest verdict. It is the more obvious design
+ * and the less useful one, for two reasons that both matter to the person reading the answer:
+ *
+ *   * **`decisive` must be unique.** With every rule evaluated, a list can hold several non-allow
+ *     decisions and the caller has to pick one -- and whichever it picks, the *stated* reason for a
+ *     refusal stops being the reason. An operator asking "why was this not allowed" needs one rule.
+ *   * **The unevaluated rules may not even apply.** A rule is evaluated against an actor, and an actor's
+ *     scope can be learned from the outcome of an earlier rule; continuing past a gate would evaluate
+ *     later rules against a context the gate had already made moot.
+ *
+ * Stopping at the *first* non-allow -- not merely at the first deny -- follows from the same argument. A
+ * gate is a gate whether it says `deny` or `needs_approval`, and in both cases the caller's next action
+ * is determined and the rest of the list is decoration.
+ *
+ * @param {AuthorityRule[]} rules
+ * @param {{level: number, inScope?: boolean|null, id?: string|null}} actor
+ * @returns {{verdict: string, decisions: object[], decisive: object|null}}
+ */
+export function evaluateAll(rules, actor) {
+  const decisions = [];
+  for (const rule of Array.isArray(rules) ? rules : []) {
+    const decision = evaluate(rule, actor);
+    decisions.push(decision);
+    if (decision.verdict !== AUTHORITY_VERDICT.ALLOW) {
+      return { verdict: decision.verdict, decisions, decisive: decision };
+    }
+  }
+  return { verdict: AUTHORITY_VERDICT.ALLOW, decisions, decisive: null };
+}
+
+/**
+ * The level required to sign off on a refusal.
+ *
+ * One band up, floored at the captain band, because the document's approval flow is a chain --
+ * captain, then org admin, then system admin -- and a chain that can be satisfied by the actor's own peer
+ * group is not a chain. An actor already at the top band has no higher approver, so the top band signs
+ * for itself; saying otherwise would make a system-admin action unapprovable.
+ *
+ * @param {number} level
+ * @returns {number|null}
+ */
+export function requiredApproverLevel(level) {
+  const band = bandOf(level);
+  if (band === null) return null;
+  if (band.name === 'system_admin') return 90;
+  const higher = AUTHORITY_BANDS[AUTHORITY_BANDS.indexOf(band) + 1];
+  return higher === undefined ? null : higher.min;
+}
+
+/**
+ * Is `approver` allowed to sign off on `subject`'s pending action?
+ *
+ * Strictly higher, not equal-or-higher. Two captains approving each other is a peer ring, and the whole
+ * point of the chain is that a decision can be escalated past the level that wanted it. Self-approval is
+ * refused for the same reason, stated separately because it is the case an implementation is most likely
+ * to let through by comparing only levels.
+ *
+ * @param {{level: number, id?: string|null}} approver
+ * @param {{level: number, id?: string|null}} subject
+ * @returns {{ok: boolean, reason: string, required: number|null}}
+ */
+export function mayApprove(approver, subject) {
+  const required = requiredApproverLevel(subject?.level);
+  if (required === null) {
+    return { ok: false, required: null, reason: `subject has no usable authority level (got ${JSON.stringify(subject?.level ?? null)})` };
+  }
+  if (!isAuthorityLevel(approver?.level)) {
+    return { ok: false, required, reason: `approver has no usable authority level (got ${JSON.stringify(approver?.level ?? null)})` };
+  }
+  if (approver.id !== undefined && approver.id !== null && approver.id === subject?.id) {
+    return { ok: false, required, reason: 'an actor may not approve its own request' };
+  }
+  if (approver.level < required) {
+    return { ok: false, required, reason: `approver level ${approver.level} is below the required ${required}` };
+  }
+  return { ok: true, required, reason: `approver level ${approver.level} meets the required ${required}` };
+}
+
+/**
+ * Compose a child actor's authority from its parent's.
+ *
+ * **This never increases it.** No rule in the source design grants delegation, and the default an
+ * implementation reaches for -- "a captain's delegate is a captain" -- turns any single compromised
+ * actor into an escalation path. Where the source is silent, the safe reading is the narrow one, and the
+ * `reason` says which of the two rules applied so a later reader can tell a deliberate cap from a bug.
+ *
+ * @param {{level: number, id?: string|null}} parent
+ * @param {{level?: number, cap?: number|null, id?: string|null}} child
+ * @returns {{level: number|null, capped: boolean, reason: string}}
+ */
+export function deriveAuthority(parent, child = {}) {
+  if (!isAuthorityLevel(parent?.level)) {
+    return { level: null, capped: false, reason: `parent has no usable authority level (got ${JSON.stringify(parent?.level ?? null)})` };
+  }
+  if (child.level !== undefined && !isAuthorityLevel(child.level)) {
+    return { level: null, capped: false, reason: `child level is not usable (got ${JSON.stringify(child.level)})` };
+  }
+  const asked = child.level ?? parent.level;
+  const cap = isAuthorityLevel(child.cap) ? child.cap : parent.level;
+  const ceiling = Math.min(parent.level, cap);
+  const level = Math.min(asked, ceiling);
+  return {
+    level,
+    capped: level < asked,
+    reason: level < asked
+      ? `reduced from ${asked} to ${level}: a derived actor never exceeds its parent (${parent.level}) or its cap (${cap})`
+      : `granted ${level}: within parent (${parent.level}) and cap (${cap})`,
+  };
+}

package/src/plugin/tools.mjs

@@ -97,7 +97,7 @@ import path from 'node:path';
 // file here: the reader carries the rules that matter -- newest-first by file position, a malformed line
 // skipped rather than fatal, and the rotated generation reachable -- and a second implementation would
 // drift from the writer's shape without anything failing.
-import { readMemorySync } from '../agent/memory.mjs';
+import { appendMemory, readMemorySync } from '../agent/memory.mjs';
 
 // The base-address rules live in one place (§2), shared with the agent side. Importing the - rather
 // than re-deriving them her - is what stops the plugin and the agent from disagreeing about what
@@ -185,7 +185,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.9.6';
+const PLUGIN_VERSION = '0.9.8';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -4687,15 +4687,48 @@ export async function apply(ctx, config = {}) {
    * fleet's roster still comes from the relay, so the answer distinguishes "no such machine" from "that
    * machine keeps its own memory and this build cannot fetch it".
    */
+  /**
+   * The collective layer's filename, beside the profile that mounted this plugin.
+   *
+   * §3.2 of the design puts curated fleet knowledge on the archive host. This is the read half of it, and
+   * it deliberately reads a *markdown document* rather than a store: the design's own argument is that a
+   * memory which is merely a log is one nobody reads, so the collective layer is written for a person and
+   * this tool returns it as text rather than pretending to have parsed it into facts. A parser over
+   * hand-written prose would silently drop whatever it did not recognise, and the dropped part would be
+   * exactly the part a human thought was worth writing down.
+   */
+  const COLLECTIVE_FILE = 'fleet-memory.md';
+  /**
+   * The collective document's path, or `null` when there is no profile to resolve it against.
+   *
+   * `resolveProfileDir` legitimately returns `null` -- a bare test context, or a host whose layout it
+   * cannot read -- and the first version of this passed that straight into `path.join`, which threw
+   * `ERR_INVALID_ARG_TYPE`. A read tool that crashes on a missing directory is worse than one that says
+   * the directory is missing: the caller was asking a question, and an exception is not an answer.
+   */
+  const collectivePath = () => {
+    const dir = resolveProfileDir(cfg);
+    return typeof dir === 'string' && dir !== '' ? path.join(dir, COLLECTIVE_FILE) : null;
+  };
+
   ctx.tools.register(defineTool({
     name: 'w2m_memory',
     description:
-      'Ask what this machine has already done: its individual memory, one line per finished task, ' +
-      'recording the command, exit code, duration, transport and the tail of stdout/stderr. Use it ' +
-      'before re-running work to find out whether it has been tried and what happened. The relay keeps ' +
-      'only hashes, so this local file is the only place a command\'s output survives. Reads only this ' +
-      'machine\'s memory; for another machine it reports where that memory lives rather than guessing.',
+      'Ask what the fleet already knows and what this machine has already done. scope="local" reads ' +
+      'this machine\'s individual memory: one line per finished task with the command, exit code, ' +
+      'duration, transport and the tails of stdout/stderr. scope="fleet" reads the curated collective ' +
+      'memory: measured facts with their dates, decisions with their reasoning, and open problems. The ' +
+      'relay keeps only hashes, so these files are the only place a command\'s output survives. Use it ' +
+      'before re-running work -- it is what turns a dozen rediscovery dispatches into one lookup.',
     parameters: {
+      scope: {
+        type: 'string',
+        enum: ['local', 'fleet'],
+        description:
+          'local (default) = what this machine did; fleet = what the fleet knows, from the curated ' +
+          'collective memory.',
+        default: 'local',
+      },
       machine: {
         type: 'string',
         description:
@@ -4714,6 +4747,13 @@ export async function apply(ctx, config = {}) {
           'memory question about anything older than the current file needs this.',
         default: false,
       },
+      record: {
+        type: 'string',
+        description:
+          'Record a conclusion against the most recent task: what its result meant. This is the only ' +
+          'field a machine is not allowed to write itself -- the machine stores the fact, a reader ' +
+          'asserts the meaning. Written as a new record so nothing already written is rewritten.',
+      },
     },
     output: jsonOutput,
     async execute(args, exec) {
@@ -4726,6 +4766,120 @@ export async function apply(ctx, config = {}) {
       const self = identity?.machine_name ?? null;
       const selfId = identity?.machine_id ?? null;
 
+      /**
+       * The collective layer, returned as the document it is.
+       *
+       * No parsing, on purpose. The file is written for a person -- facts with their evidence and the date
+       * they were measured, decisions with the reasoning that produced them -- and a parser over prose
+       * would silently drop whatever shape it did not expect. What it dropped would be exactly what a
+       * human judged worth writing down, so the honest answer is the text plus where it came from.
+       */
+      if (args?.scope === 'fleet') {
+        const file = collectivePath();
+        let text = null;
+        let error = null;
+        if (file === null) {
+          error = 'MEMORY_NO_COLLECTIVE';
+        } else {
+          try {
+            text = await fs.readFile(file, 'utf8');
+          } catch (readError) {
+            error = readError?.code === 'ENOENT' ? 'MEMORY_NO_COLLECTIVE' : `MEMORY_READ_FAILED: ${readError?.code}`;
+          }
+        }
+        const headings = text === null
+          ? []
+          : text.split('\n').filter((line) => /^#{1,3} /.test(line)).map((line) => line.replace(/^#+\s*/, '').trim());
+        return JSON.stringify(
+          {
+            ok: true,
+            scope: 'fleet',
+            path: file,
+            found: text !== null,
+            bytes: text === null ? null : Buffer.byteLength(text, 'utf8'),
+            // The section list is what makes a long document usable: a reader can see what the collective
+            // memory covers without paying for the whole of it first.
+            sections: headings,
+            body: text,
+            ...(error === null ? {} : { reason_code: error }),
+            notes: [
+              error === 'MEMORY_NO_COLLECTIVE'
+                ? (file === null
+                  ? 'no profile directory could be resolved, so the collective memory has no known location'
+                  : `no collective memory at ${file}; it is written by hand on the archive host, and its absence means nothing has been curated there yet`)
+                : null,
+              'this document is curated, not generated: every fact in it should carry the date it was measured and how',
+            ].filter((n) => n !== null),
+          },
+          null,
+          2,
+        );
+      }
+
+      /**
+       * Recording a conclusion.
+       *
+       * The one field a machine may not write for itself. `memoryRecord` always emits `conclusion: null`
+       * because a machine that invented one would be asserting an interpretation it cannot have; this is
+       * the path by which a reader -- a person, or the agent acting on their instruction -- supplies it.
+       *
+       * Appended as a new record rather than by rewriting the existing line. The log is append-only, and
+       * in-place editing would break the property that makes it trustworthy: what was written is what
+       * happened, and an amendment is a later statement about it. Rewriting would also lose the original
+       * text, which is the thing a reader most needs when a conclusion turns out to be wrong.
+       */
+      const conclusionText = typeof args?.record === 'string' && args.record.trim() !== '' ? args.record.trim() : null;
+      if (conclusionText !== null) {
+        const stateDirForRecord = cfg.stateDir ?? null;
+        if (stateDirForRecord === null) {
+          return JSON.stringify(
+            {
+              ok: false,
+              scope: 'local',
+              reason_code: 'MEMORY_NO_STATE_DIR',
+              detail: 'this plugin has no stateDir configured, so a conclusion has nowhere to be written',
+            },
+            null,
+            2,
+          );
+        }
+        const recent = readMemorySync(stateDirForRecord, { limit: 1 });
+        const subject = recent.records[0] ?? null;
+        const written = appendMemory(stateDirForRecord, {
+          at: new Date().toISOString(),
+          kind: 'conclusion',
+          task_id: subject?.task_id ?? null,
+          machine_id: selfId,
+          machine_name: self,
+          // The conclusion is about the record named by `task_id`; the fields below repeat enough of it
+          // that a reader does not have to join two lines to know what is being talked about.
+          about: subject === null
+            ? null
+            : { argv: subject.argv ?? null, exit_code: subject.exit_code ?? null, at: subject.at ?? null },
+          conclusion: conclusionText,
+          tags: [],
+        });
+        return JSON.stringify(
+          {
+            ok: written.ok === true,
+            scope: 'local',
+            recorded: written.ok === true,
+            task_id: subject?.task_id ?? null,
+            conclusion: conclusionText,
+            path: written.ok === true ? written.path : null,
+            ...(written.ok === true ? {} : { reason_code: written.error }),
+            notes: [
+              subject === null
+                ? 'no task has been recorded here yet, so this conclusion names no task; it is still kept, with about: null'
+                : `recorded against task ${subject.task_id}`,
+              'appended, never rewritten: the original record is left as it was written',
+            ],
+          },
+          null,
+          2,
+        );
+      }
+
       // A query about another machine is answered honestly rather than with an empty list, which would
       // read as "that machine has done nothing" -- the opposite conclusion from "this build cannot see".
       if (requested !== null && requested !== self && requested !== selfId) {