@twinsearth/w2m-dsh-plugin 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -4,6 +4,69 @@ 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.33.0] — 2026-10-15
+
+**The authority level is chosen by name. Nobody types a number.**
+
+`actorAuthorityLevel` is an integer in `0..100` whose four bands have names and gaps. Asking a person to type
+it asks them to hold all of that in their head, and **getting it wrong fails silently**: `69` and `70` look
+equally arbitrary and land in different bands, so a machine configured one point low **refuses a dispatch it
+should have run and never says a threshold was the reason.**
+
+`src/agent/authority-choice.mjs` turns the number into a choice:
+
+| Choice | Level | What picking it permits |
+|---|---|---|
+| `ordinary` | **0** | create goals and session data within its own scope |
+| `captain` | **50** | create team goals, manage team membership |
+| `org_admin` | **70** | create organisation goals, register actors, set overrides |
+| `system_admin` | **90** | create global goals, configure across organisations, override any lower constraint |
+
+The options are **built from `AUTHORITY_BANDS`**, so a band added to the model appears here without anybody
+remembering — and a band cannot be described in two places differently.
+
+### A name resolves to its band FLOOR, and the consequence is stated
+
+The floor is where the band's own description becomes true, and it is what `bandOf` answers with. Resolving to
+a midpoint would mean **a choice labelled "captain" silently granting more than captain.**
+
+The practical consequence is worth writing down because it decides what a machine may do: **`ordinary`
+resolves to `0` and `dispatch_writing` costs `50`, so a machine whose operator picks "ordinary" cannot
+dispatch a write at all** — it escalates and an approver must answer. Measured, all four:
+
+```
+ordinary     level   0  ->  write dispatch: needs_approval
+captain      level  50  ->  write dispatch: allow
+org_admin    level  70  ->  write dispatch: allow
+system_admin level  90  ->  write dispatch: allow
+```
+
+### Two vocabularies, and two different callers
+
+**A number is refused by the selector**, because a selector that also accepts integers is a text field with a
+helpful hint and every reason above applies again. **A number is accepted by the config**, because a profile
+patch written by an earlier version must keep loading — and breaking every existing machine on upgrade is a
+worse failure than accepting a number from a file nobody is looking at. The two rules are stated in one place
+and tested against each other, including that the selector refuses `'captain '` while the config trims it.
+
+### A misconfigured level no longer degrades in silence
+
+`w2m_status` now reports `actor_authority` — whether it resolved, from which vocabulary, and **why not when it
+did not, with the four choices attached**. A level that failed to parse used to become `null`, which reads
+exactly like a machine that never chose one, and **those two need opposite responses.**
+
+### Three of my own errors
+
+* I asserted `UNKNOWN` for the integer `70`; it is `NOT_A_STRING`, because the codes distinguish "a number was
+  given" from "a string that did not match" — **on purpose, so a caller can message them differently.**
+* I reused the selector's message in the config resolver, so a config author was told about names only while
+  **that function's own contract promised numbers too.** The implementation was changed, not the test.
+* My captain test asserted success and instead reached the network, because it installed no fetch stub. **That
+  failure was the proof**: it did *not* throw `W2M_PERMISSION_*`. The assertion now checks the kind of failure
+  rather than the absence of one, which is what the test was always about.
+
+**18 new tests, 0 failures.**
+
 ## [0.32.0] — 2026-10-15
 
 **Widening real-machine verification: eight suites tried, none passed, and the cause is a hypothesis.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.32.0",
+  "version": "0.33.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/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": "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/authority-choice.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/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",
+    "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/authority-choice.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 .",
@@ -148,7 +148,8 @@
     "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:approval-gate": "node --test --test-force-exit test/approval-gate.test.mjs"
+    "test:approval-gate": "node --test --test-force-exit test/approval-gate.test.mjs",
+    "test:authority-choice": "node --test --test-force-exit test/authority-choice.test.mjs"
   },
   "keywords": [
     "dsh-bundle",

package/src/agent/authority-choice.mjs

@@ -0,0 +1,172 @@
+/**
+ * Choosing an authority level by name, so nobody has to remember what 70 means.
+ *
+ * ## Why this exists
+ *
+ * `actorAuthorityLevel` is an integer in `0..100`, and the four bands it falls into have names, prose about
+ * what each may do, and *gaps*. Asking a person to type a number means asking them to hold all of that in
+ * their head, and the failure mode of getting it wrong is silent: `69` and `70` look equally arbitrary and
+ * land in different bands, and a machine configured one point low **refuses a dispatch it should have run**
+ * with no indication that a threshold was the reason.
+ *
+ * This module turns the number into a choice. A caller presents {@link AUTHORITY_CHOICES} — four names with
+ * the sentence each one means — and gets back the level. **The number is never asked for.**
+ *
+ * ## Why a name resolves to its band FLOOR
+ *
+ * Each band spans a range and this picks the bottom of it, deliberately. The floor is the level at which the
+ * band's own description becomes true, and it is what `bandOf` answers with: a machine at the floor is *in*
+ * that band and no higher. Resolving to the midpoint or the ceiling would mean a choice labelled "captain"
+ * silently granted more than captain.
+ *
+ * **The consequence is worth stating plainly, because it decides what a machine can do:** `ordinary` resolves
+ * to `0`, and `dispatch_writing` costs `50`. So a machine whose operator picks "ordinary" **cannot dispatch a
+ * write at all** — it escalates, and an approver must answer. That is the intended reading of the label. It
+ * is also why this is a policy decision rather than a convenience: **the name a person picks decides what the
+ * machine is allowed to do.**
+ *
+ * ## Why a number is refused rather than accepted alongside the names
+ *
+ * A selector that also accepted integers would be a text field with a helpful hint, and every reason above
+ * would apply again. Refusing them keeps one way in, and the refusal names the four that exist.
+ */
+import { AUTHORITY_BANDS, AUTHORITY_BAND_FLOORS, AUTHORITY_MAX, isAuthorityLevel } from './authority.mjs';
+
+/** Why a choice was refused. */
+export const CHOICE_REFUSAL = Object.freeze({
+  UNKNOWN: 'AUTHORITY_CHOICE_UNKNOWN',
+  NOT_A_STRING: 'AUTHORITY_CHOICE_NOT_A_STRING',
+  NOT_CHOSEN: 'AUTHORITY_CHOICE_NOT_CHOSEN',
+});
+
+/**
+ * The options to present, in ascending order, each with the sentence it stands for.
+ *
+ * Built from `AUTHORITY_BANDS` rather than written out, so a band added to the model appears here without
+ * anybody remembering to add it — and, more importantly, **a band cannot be described in two places
+ * differently**.
+ */
+export const AUTHORITY_CHOICES = Object.freeze(
+  AUTHORITY_BANDS.map((band) => ({
+    /** The value a caller stores. Never a number. */
+    value: band.name,
+    /** What to show a person. */
+    label: band.name.replace(/_/g, ' '),
+    /** The level this resolves to, and the reason it is that one. */
+    level: AUTHORITY_BAND_FLOORS[band.name.toUpperCase()],
+    /** What picking this permits, in the model's own words. */
+    may: band.may,
+    /** The range, so a caller can show it without reading the model. */
+    range: band.max === null ? `${band.min}+` : `${band.min}–${band.max}`,
+  })),
+);
+
+/**
+ * Resolve a named choice to a level.
+ *
+ * @param {string|null|undefined} choice
+ * @returns {{ok: boolean, level: number|null, choice: string|null, code: string|null, detail: string,
+ *   options: string[]}}
+ */
+export function resolveAuthorityChoice(choice) {
+  const options = AUTHORITY_CHOICES.map((c) => c.value);
+
+  if (choice === null || choice === undefined || choice === '') {
+    // Not the same as a wrong answer. "Nobody chose" is a state a caller has to be able to tell from "somebody
+    // chose badly", because only one of them is a mistake.
+    return {
+      ok: false,
+      level: null,
+      choice: null,
+      code: CHOICE_REFUSAL.NOT_CHOSEN,
+      detail: `no authority level was chosen; pick one of ${options.join(', ')}`,
+      options,
+    };
+  }
+
+  if (typeof choice !== 'string') {
+    return {
+      ok: false,
+      level: null,
+      choice: null,
+      code: CHOICE_REFUSAL.NOT_A_STRING,
+      detail: `${JSON.stringify(choice)} is not a choice; pick one of ${options.join(', ')} by name`,
+      options,
+    };
+  }
+
+  const found = AUTHORITY_CHOICES.find((c) => c.value === choice);
+  if (found === undefined) {
+    return {
+      ok: false,
+      level: null,
+      choice: null,
+      code: CHOICE_REFUSAL.UNKNOWN,
+      detail: `${JSON.stringify(choice)} is not one of ${options.join(', ')}; if it looks like a number, note that levels are chosen by name and not typed`,
+      options,
+    };
+  }
+
+  return {
+    ok: true,
+    level: found.level,
+    choice: found.value,
+    code: null,
+    detail: `${found.value} resolves to level ${found.level} (${found.range}): ${found.may}`,
+    options,
+  };
+}
+
+/**
+ * Resolve a plugin configuration value, which may be a name or already a level.
+ *
+ * ## Why this one DOES accept a number, when the selector does not
+ *
+ * These are different callers with different constraints. A person choosing is asked to choose, and the whole
+ * point is that they are not asked for a number. A **profile patch** is written by hand or by an earlier
+ * version of this plugin, and a config that used to hold `70` must not start refusing to load because the
+ * interface changed — that would break every existing machine on upgrade, which is the failure this module's
+ * own docstring warns about.
+ *
+ * So: a `string` is resolved as a choice, an integer is accepted as-is **only if it is a usable level**, and
+ * anything else is refused with a message naming both vocabularies.
+ *
+ * @param {unknown} value
+ * @returns {{ok: boolean, level: number|null, source: string|null, code: string|null, detail: string}}
+ */
+export function resolveConfiguredLevel(value) {
+  if (typeof value === 'string' && value.trim() !== '') {
+    const r = resolveAuthorityChoice(value.trim());
+    if (r.ok) return { ok: true, level: r.level, source: 'name', code: null, detail: r.detail };
+    // A config may hold EITHER vocabulary, so a string that is not a band name is not simply unknown -- the
+    // caller is told both what the names are and that an integer would also have worked. Reusing the
+    // selector's message here was the first version's mistake: it told a config author about names only,
+    // while the function's own contract promised numbers too.
+    return {
+      ok: false,
+      level: null,
+      source: null,
+      code: r.code === CHOICE_REFUSAL.NOT_CHOSEN ? CHOICE_REFUSAL.NOT_CHOSEN : CHOICE_REFUSAL.UNKNOWN,
+      detail: `${JSON.stringify(value)} is neither a choice nor a level; choose one of ${AUTHORITY_CHOICES.map((c) => c.value).join(', ')}, or a direct level as an integer 0..${AUTHORITY_MAX}`,
+    };
+  }
+  if (isAuthorityLevel(value)) {
+    return {
+      ok: true,
+      level: value,
+      source: 'number',
+      code: null,
+      detail: `level ${value} was configured directly; it is in the "${(AUTHORITY_BANDS.find((b) => value >= b.min && (b.max === null || value <= b.max)) ?? {}).name ?? 'unknown'}" band`,
+    };
+  }
+  if (value === null || value === undefined || value === '') {
+    return { ok: false, level: null, source: null, code: CHOICE_REFUSAL.NOT_CHOSEN, detail: 'no authority level is configured, so the permission gate is not enforced' };
+  }
+  return {
+    ok: false,
+    level: null,
+    source: null,
+    code: CHOICE_REFUSAL.UNKNOWN,
+    detail: `${JSON.stringify(value)} is neither a choice nor a level; choose one of ${AUTHORITY_CHOICES.map((c) => c.value).join(', ')}, or an integer 0..${AUTHORITY_MAX}`,
+  };
+}

package/src/plugin/tools.mjs

@@ -132,6 +132,9 @@ 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.33.0: the level is chosen by NAME rather than typed. `resolveConfiguredLevel` also accepts a plain
+// integer, because a profile patch written by an earlier version must keep loading.
+import { AUTHORITY_CHOICES, resolveConfiguredLevel } from '../agent/authority-choice.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
 // implementations of a handshake are two chances to disagree about it.
@@ -195,7 +198,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.32.0';
+const PLUGIN_VERSION = '0.33.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -700,11 +703,34 @@ function readConfig(config = {}) {
      * null is not 0. An unset level means there is no actor to judge, and the gate reports that as
      * unenforced rather than refusing every writing dispatch on a machine that never opted in.
      */
-    actorAuthorityLevel: isAuthorityLevel(config.actorAuthorityLevel)
-      ? config.actorAuthorityLevel
-      : (Number.isInteger(Number(process.env.W2M_ACTOR_AUTHORITY)) && isAuthorityLevel(Number(process.env.W2M_ACTOR_AUTHORITY))
-        ? Number(process.env.W2M_ACTOR_AUTHORITY)
-        : null),
+    /**
+     * v0.33.0: the level, chosen by NAME or configured as a number.
+     *
+     * The plugin config takes either, through {@link resolveConfiguredLevel} — a name because nobody should
+     * have to remember what 70 means, and a number because a profile patch written by an earlier version
+     * must keep loading. `W2M_ACTOR_AUTHORITY` takes a name too, so a machine can be pointed at a band
+     * without editing a profile.
+     *
+     * `actorAuthorityChoice` carries the resolution — including WHY it failed, when it did — so `w2m_status`
+     * can report a level it refused instead of silently dispatching unenforced. A misconfigured level that
+     * degrades to `null` in silence is the failure this pair exists to prevent.
+     */
+    ...(() => {
+      const fromEnv = typeof process.env.W2M_ACTOR_AUTHORITY === 'string' && process.env.W2M_ACTOR_AUTHORITY.trim() !== ''
+        ? process.env.W2M_ACTOR_AUTHORITY.trim()
+        : undefined;
+      const resolved = resolveConfiguredLevel(fromEnv !== undefined ? fromEnv : config.actorAuthorityLevel);
+      return {
+        actorAuthorityLevel: resolved.ok ? resolved.level : null,
+        actorAuthorityChoice: {
+          ok: resolved.ok,
+          level: resolved.level,
+          source: resolved.source,
+          reason_code: resolved.code,
+          detail: resolved.detail,
+        },
+      };
+    })(),
     defaultTimeoutMs: shared.values.defaultTimeoutMs,
     sharedConfig: shared,
     pairingCode: typeof config.pairingCode === 'string' && config.pairingCode.trim() !== ''
@@ -4519,6 +4545,17 @@ export async function apply(ctx, config = {}) {
               : targetRoutes.reason,
             sessions_with_a_target: defaultSelectionStore.list().length,
           },
+          /**
+           * v0.33.0: how the authority level was resolved, and why it failed when it did.
+           *
+           * A misconfigured level used to degrade to `null` in silence, which reads exactly like a machine
+           * that never chose one -- and those need opposite responses. This reports the difference, and
+           * carries the four choices so a reader can fix it without being told what they are elsewhere.
+           */
+          actor_authority: {
+            ...cfg.actorAuthorityChoice,
+            ...(cfg.actorAuthorityChoice.ok ? {} : { choices: AUTHORITY_CHOICES.map((c) => ({ value: c.value, may: c.may, range: c.range })) }),
+          },
           approvals: approvalsBlock,
           notes: statusNotes(relay, rtt, cfg, p2pStatus, approvalsBlock),
         },