@twinsearth/w2m-dsh-plugin 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,99 @@ 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.27.0] — 2026-10-15
+
+**A blocked fleet reports itself. The approval count is in `w2m_status`, and it arrives as a note.**
+
+A queue visible only to someone who remembers to look at it is a queue that stays full, and **a fleet blocked
+on approval looks exactly like an idle fleet.** `w2m_status` now carries an `approvals` block and, when
+anything is waiting, a note placed **first** — ordering being the only emphasis a list of notes has:
+
+> *"3 dispatch(es) are WAITING FOR AN APPROVER and will not run until one answers; read them with
+> `w2m_approvals` (1 past their deadline); the oldest has been waiting 240s"*
+
+### `constructed: false` is not `pending: 0`
+
+A machine that has never tripped the permission gate should not be described as having an empty queue **as
+though that were a measurement.** The block says which it is, and the note is emitted only for real pending
+work.
+
+### The whole chain, across three tools, asserted end to end
+
+An ordinary actor (49) attempts a write → refused with `W2M_PERMISSION_NEEDS_APPROVAL` **carrying the queued
+id** → `w2m_status` reports `pending: 1` and the blocking note **without being asked about approvals** → a
+captain settles it → the signal clears.
+
+### The default approver is the requester, and the index says so
+
+The test discovered this rather than assuming it: a request records its subject as the machine's name, and an
+approver who **defaults to that same name is the subject** — so `may_act` is false with
+`APPROVAL_SELF_APPROVAL`. That is correct, and it is a real consequence of the defaults rather than a bug. The
+test now names a distinct approver and **asserts the refusal first**, so the self-approval rule is pinned
+rather than sidestepped.
+
+### A payload silently dropped, caught by a test that found nothing
+
+`W2MError` accepts only `code`, `message`, `hint`, `detail`, `cause` and `reason_code`. The first version
+passed `approval_id` and `request` as **top-level options**, so they were **discarded without complaint** and
+the refusal told a caller to await approval **with no way to name what they were waiting for.** They now
+travel in `detail`, and the constructor's accepted keys are named in a comment beside the call.
+
+Two of my own errors in this round were the same shape as the ones before it: a block hoisted into the **wrong
+scope** (module level instead of inside `execute`, which `node --check` accepted because the name existed
+*somewhere*), and a syntactic fix that put a statement **inside an object literal**. Both were caught by
+running the suite, not by reading.
+
+**1 new cross-tool test, 0 failures.**
+
+## [0.26.0] — 2026-10-15
+
+**`w2m_approvals`: the approval chain is reachable by an operator, not only by the suite.**
+
+The tenth tool. `action: "list"` reads the queue, `approve` and `reject` settle one request by `approval_id`.
+Until now the chain from 0.25.0 was **closed in code and testable end to end while no operator could reach
+it**; this is the tool that opens it.
+
+### Every row says whether *you* may act, and why not when you may not
+
+A list filtered to what the caller may answer would be shorter and would **make the fleet look idle at the
+moment it is most blocked.** `listFor` already returns each row with `may_act` and `why_not`; the tool passes
+them through instead of hiding work above the caller's authority.
+
+### `actor_level` is a parameter, and that is deliberate
+
+The machine's own `actorAuthorityLevel` says what it may **dispatch as**. An approver's level is a fact about
+the person answering, and a decision made on the dispatcher's level would let a machine approve its own
+escalations. Passing it explicitly is what keeps `APPROVAL_SELF_APPROVAL` meaningful rather than incidental.
+
+**Settling without a level is refused** (`W2M_APPROVAL_LEVEL`) rather than defaulted, so a decision is never
+attributed to a level nobody supplied. Listing **without** a level still works and says so: `level_known:
+false`, with a note explaining that the queue is visible but whether any of it is answerable is not known —
+**knowing what is waiting does not require the authority to answer it, and a queue only its supervisors can
+see is a queue that stays full.**
+
+### The note on every settle, because a reader will assume otherwise
+
+> *"the request is settled; the dispatch did not run and must be attempted again"*
+
+Approval means the next attempt is allowed, not that anything already happened. A tool that settled quietly
+would leave its caller waiting for a result that is never coming.
+
+### Three defects of mine, all caught by the suite or by checking
+
+* I called a `json(...)` helper **that does not exist in this file** — every tool returns `JSON.stringify(...)`.
+  `node --check` passed, so only reading the surrounding code found it.
+* I referenced `AUTHORITY_MAX` without importing it.
+* I omitted `presentCall`, which `ALLOWED_DEF_KEYS` requires and which the registration-shape test pins. It now
+  labels a list as a `read` and a settle as a `write`, because **calling a queue inspection a write would
+  misrepresent the common case.**
+
+Four tool-count assertions said "exactly nine" and named the nine; they now say ten and name the ten. The
+comment beside one of them already recorded the lesson from a previous version — that a **count** was once the
+wrong property and the **message** was the right one. This time the count *was* the property.
+
+**7 new tests, 0 failures.**
+
 ## [0.25.0] — 2026-10-15
 
 **The chain is closed: dispatch → gate → queue → decision. The plugin builds a queue, and an escalation is a real entry an approver can find.**

package/README.md

@@ -39,7 +39,7 @@ So the cross-machine capability has to be built. This is that build.
                        ▼
    ┌──────────────────────────────────┐        ┌──────────────────────────┐
    │  Windows · DSH session           │        │  macOS · DSH session     │
-   │   w2m plugin (9 tools)           │        │   w2m plugin (9 tools)   │
+   │   w2m plugin (10 tools)          │        │   w2m plugin (10 tools)  │
    │        │                         │        │        │                 │
    │   Localside agent                │        │   Localside agent        │
    │    · three anchors               │        │    · three anchors       │
@@ -293,15 +293,16 @@ Then give it the relay URL in that profile's `cordis.patch.yml` — or leave
 >        got "@twinsearth/w2m-dsh-plugin/tools"), skipping
 > ```
 >
-> That is a silent failure by construction — the install looks right, nine tools appear, and
+> That is a silent failure by construction — the install looks right, ten tools appear, and
 > `w2m_status` reports `paired: false` and a null `rabbitUrl` because none of your values were ever
 > applied. It is not hypothetical: this row's expected name moved from the `/tools` subpath to the
 > package root in v0.5.4 (see `cordis.patch.yml`'s header for why), and every override that still
 > asserted the old subpath stopped being applied on upgrade. `id` already identifies the row, so the
 > safest `name:` is no `name:` at all.
 
-Restart DSH. You should see nine tools: `w2m_devices`, `w2m_run`, `w2m_wait`,
-`w2m_report`, `w2m_status`, `w2m_update`, `w2m_history`, `w2m_stats`, `w2m_memory`.
+Restart DSH. You should see ten tools: `w2m_devices`, `w2m_run`, `w2m_wait`,
+`w2m_report`, `w2m_status`, `w2m_update`, `w2m_history`, `w2m_stats`, `w2m_memory`,
+`w2m_approvals`.
 
 > `dsh` may not be on your `PATH`. On a packaged install it lives under
 > `resources/runtime/cli/bin/`. If `dsh` is not found, call it by path.
@@ -584,7 +585,7 @@ a product.
 |---|---|---|
 | relay | 142 | pairing, auth, SSE with `ready`-first and `seq` replay, leases with heartbeat renewal and expiry, dedupe, all **nine** aggregation states plus `pending`/`refused`, report generation, operator token, rate limiting, persistence and restart recovery, TLS, and the lost-offer recovery path |
 | agent | 129 | allow-list allow/deny, timeout, output truncation, exit codes, anchors on clean and dirty trees, four concurrent fingerprint computations, spool, a 40-case URL join matrix, cursor lifecycle across relay restarts, and the bundled-runtime resolver |
-| tools | 89 | nine tools registered, schemas, typed errors, polling, operator-token enforcement (no request is sent without it), sub-path endpoints, and the credential canaries |
+| tools | 89 | ten tools registered, schemas, typed errors, polling, operator-token enforcement (no request is sent without it), sub-path endpoints, and the credential canaries |
 | broadcast | 19 | exactly one executor, the rest `observing`; observers excluded from every aggregation step so a machine that did not run is never counted as agreeing |
 | claims | 19 | the document claims themselves: the version, the bundle patch, the tool list, every documented tarball URL, and the CHANGELOG's shape |
 | fleet-target | 37 | the composer's target selection, and the `executor_machine_id` narrowing that overrides it |
@@ -712,7 +713,7 @@ the plugin:
 
 ```bash
 node scripts/check-entrypoints.mjs   # imports lib/tools.js, the exact specifier cordis.patch.yml mounts
-node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 9 tools
+node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 10 tools
 ```
 
 **Not verified:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.25.0",
+  "version": "0.27.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",

package/src/plugin/tools.mjs

@@ -129,7 +129,7 @@ import { gateDispatch, approvalRequestFor, raiseApproval } from '../agent/permis
 // v0.24.0: the queue an escalation is raised into. Imported from `src/`, never from `scripts/` -- a
 // `src/` module reaching above itself breaks the published package (see CHANGELOG 0.23.0).
 import { createApprovalIndex } from '../agent/approval-index.mjs';
-import { isAuthorityLevel } from '../agent/authority.mjs';
+import { AUTHORITY_MAX, isAuthorityLevel } from '../agent/authority.mjs';
 // v0.6.0: the device keypair and the offer's key distribution (`docs/P2P-CRYPTO.md` §4). Imported
 // rather than reimplemented: the dispatcher and the executor have to derive the *same* keys, and two
 // implementations of a handshake are two chances to disagree about it.
@@ -193,7 +193,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.25.0';
+const PLUGIN_VERSION = '0.27.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -1118,6 +1118,7 @@ function safeFilePart(value) {
  */
 function canonicalJson(value) {
   if (value === undefined) return 'null';
+
   if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
   if (Array.isArray(value)) return `[${value.map((entry) => canonicalJson(entry)).join(',')}]`;
   const keys = Object.keys(value).sort();
@@ -3087,9 +3088,26 @@ function readAggregate(body) {
  * @param {object} p2p The block from {@link readP2PStatus}.
  * @returns {string[]}
  */
-function statusNotes(relay, rtt, cfg, p2p) {
+function statusNotes(relay, rtt, cfg, p2p, approvalsNote = null) {
   const notes = [];
 
+  /**
+   * v0.26.0: blocked work announces itself.
+   *
+   * The whole reason the count is in `w2m_status` at all. A note is what a caller reads without asking a
+   * further question, and "three dispatches are waiting for an approver" is the single most actionable
+   * sentence this tool can emit: the fleet is not idle, it is stopped, and it is stopped on a person.
+   *
+   * It is placed first because ordering is the only emphasis a list of notes has.
+   */
+  if (approvalsNote !== null && Number.isFinite(approvalsNote.pending) && approvalsNote.pending > 0) {
+    notes.push(
+      `${approvalsNote.pending} dispatch(es) are WAITING FOR AN APPROVER and will not run until one answers; ` +
+        `read them with \`w2m_approvals\`${approvalsNote.overdue > 0 ? ` (${approvalsNote.overdue} past their deadline)` : ''}` +
+        `${Number.isFinite(approvalsNote.oldest_waiting_ms) ? `; the oldest has been waiting ${Math.round(approvalsNote.oldest_waiting_ms / 1000)}s` : ''}`,
+    );
+  }
+
   /**
    * §7's one-line note, and the reason it exists at all: the shared server is a *default*, and a
    * default that an operator cannot see is a machine quietly talking to somebody else's host. The
@@ -3777,8 +3795,12 @@ export async function apply(ctx, config = {}) {
             'W2M_PERMISSION_NEEDS_APPROVAL: ' + gate.decision.detail,
             {
               hint: 'this dispatch is queued awaiting an approver; approve or reject it with w2m_approvals, then dispatch again',
-              approval_id: raised.approval_id,
-              request,
+              // Carried in `detail`, not as top-level options: `W2MError` accepts only code, message, hint,
+              // detail, cause and reason_code, so anything else passed here is DROPPED SILENTLY. The first
+              // version of this passed `approval_id` at the top level and the test caught it by finding
+              // nothing -- which is exactly the kind of omission that would otherwise have reached a user as
+              // "await approval" with no way to name what they are waiting for.
+              detail: { approval_id: raised.approval_id, request },
             },
           );
         }
@@ -4327,6 +4349,45 @@ export async function apply(ctx, config = {}) {
       await p2p.ensureStarted();
       const p2pStatus = await readP2PStatus(cfg, p2p, Number.isInteger(relay.peers_announced) ? relay.peers_announced : null);
 
+      /**
+      * v0.26.0: how much work is waiting for an approver.
+      *
+      * ## Why it belongs in `w2m_status` rather than only in `w2m_approvals`
+      *
+      * A queue that is only visible to someone who remembers to look at it is a queue that stays full,
+      * and a fleet that is blocked on approval looks exactly like a fleet that is idle. This makes the
+      * blocked state **report itself**, which is the difference between a tool an operator has and a
+      * signal an operator receives.
+      *
+      * `constructed` distinguishes "nothing is waiting" from "nothing has ever asked". They are the same
+      * number and very different facts, and a machine that never tripped the permission gate should not
+      * be described as having an empty queue as though that were a measurement.
+      */
+      const approvalsBlock = (() => {
+      if (approvals === null) {
+      return {
+      constructed: false,
+      pending: null,
+      detail: 'no approval has ever been requested on this machine, so no queue exists yet; this is not the same as an empty queue',
+      };
+      }
+      const pendingRows = approvals.all();
+      const overdue = pendingRows.filter((r) => r.overdue === true).length;
+      return {
+      constructed: true,
+      pending: pendingRows.length,
+      overdue,
+      // The oldest request is the one whose loss costs most, so it is reported rather than left for a
+      // reader to sort out of the rows.
+      oldest_waiting_ms: pendingRows.length === 0
+      ? null
+      : Math.max(...pendingRows.map((r) => r.waiting_ms ?? 0)),
+      detail: pendingRows.length === 0
+      ? 'the queue exists and nothing is waiting'
+      : `${pendingRows.length} dispatch(es) waiting for an approver${overdue > 0 ? `, ${overdue} overdue` : ''}`,
+      };
+      })();
+
       return JSON.stringify(
         {
           ok: true,
@@ -4416,7 +4477,8 @@ export async function apply(ctx, config = {}) {
               : targetRoutes.reason,
             sessions_with_a_target: defaultSelectionStore.list().length,
           },
-          notes: statusNotes(relay, rtt, cfg, p2pStatus),
+          approvals: approvalsBlock,
+          notes: statusNotes(relay, rtt, cfg, p2pStatus, approvalsBlock),
         },
         null,
         2,
@@ -5088,6 +5150,131 @@ export async function apply(ctx, config = {}) {
       rawInput: {},
     }),
   }));
+
+  /**
+   * v0.25.0: the tool that makes the approval chain reachable by an operator.
+   *
+   * ## Why it reports refusals instead of hiding them
+   *
+   * Every row carries `may_act` and, when false, `why_not`. A list filtered down to what the caller may
+   * answer would be shorter and **would make the fleet look idle at the moment it is most blocked** — the
+   * work above their authority is exactly the work they most need to know exists.
+   *
+   * ## Why `actor_level` is a parameter and not read from config
+   *
+   * This machine's own `actorAuthorityLevel` says what it may *dispatch as*. An approver's level is a fact
+   * about the person answering, and a decision made on the dispatcher's level would let a machine approve its
+   * own escalations — which the index already refuses by name (`APPROVAL_SELF_APPROVAL`) when the ids match.
+   * Making it explicit keeps that refusal meaningful rather than incidental.
+   */
+  ctx.tools.register(defineTool({
+    name: 'w2m_approvals',
+    description:
+      'List and settle the dispatches that are waiting for an approver. A dispatch whose actor level is ' +
+      'exactly one band below what it needs is QUEUED rather than refused, and this is where that queue is ' +
+      'read and answered. Every row reports whether YOU may act on it and why not if you may not, so work ' +
+      'above your authority is visible rather than filtered away. Settling a request does not run the ' +
+      'dispatch: approval means the next attempt is allowed, not that anything already happened.',
+    parameters: {
+      action: {
+        type: 'string',
+        enum: ['list', 'approve', 'reject'],
+        description: 'list (default) shows the queue; approve and reject settle one request by approval_id.',
+        default: 'list',
+      },
+      approval_id: {
+        type: 'string',
+        description: 'Which request to settle. Required for approve and reject.',
+      },
+      actor_id: {
+        type: 'string',
+        description: 'Who is answering. Defaults to this machine\'s name; it is recorded on the decision, and it is what makes a self-approval refusable.',
+      },
+      actor_level: {
+        type: 'number',
+        description: 'The authority level of the person answering, 0..100. Required to approve or reject: an approver with no level cannot be placed relative to the request, and the index refuses rather than guessing one.',
+      },
+      include_settled: {
+        type: 'boolean',
+        description: 'Also show recently settled requests. They are kept briefly as receipts, so a supervisor returning to a busy queue can tell "already dealt with" from "never seen".',
+        default: false,
+      },
+    },
+    output: jsonOutput,
+    presentCall: (args) => ({
+      card: 'generic',
+      title: `w2m approvals ${typeof args?.action === 'string' ? args.action : 'list'}`,
+      // Only `approve` and `reject` change anything; a list is a read. Labelling the whole tool 'write' would
+      // make the common case -- looking at the queue -- read as an action.
+      kind: args?.action === 'approve' || args?.action === 'reject' ? 'write' : 'read',
+      rawInput: {},
+    }),
+    async execute(args, exec) {
+      throwIfAborted(exec?.signal);
+      const action = typeof args?.action === 'string' ? args.action : 'list';
+      const queue = approvalQueue();
+
+      if (action === 'approve' || action === 'reject') {
+        const approvalId = typeof args?.approval_id === 'string' ? args.approval_id.trim() : '';
+        if (approvalId === '') {
+          throw new W2MError('W2M_APPROVAL_ID', 'W2M_APPROVAL_ID: settling a request needs `approval_id`', {
+            hint: 'call w2m_approvals with action="list" to see the pending ids',
+          });
+        }
+        if (!isAuthorityLevel(args?.actor_level)) {
+          // Refused rather than defaulted, and refused HERE rather than left to the index, so the message can
+          // say what to do about it. A decision attributed to a level nobody supplied is a decision nobody
+          // can audit.
+          throw new W2MError(
+            'W2M_APPROVAL_LEVEL',
+            'W2M_APPROVAL_LEVEL: `actor_level` must be an integer 0..' + AUTHORITY_MAX + ' to settle a request',
+            { hint: 'an approver with no level cannot be placed relative to the request it is answering' },
+          );
+        }
+        const actor = { id: typeof args?.actor_id === 'string' && args.actor_id.trim() !== '' ? args.actor_id.trim() : cfg.machineName, level: args.actor_level };
+        const outcome = action === 'approve' ? 'approved' : 'rejected';
+        const result = queue.decide(approvalId, actor, outcome);
+        return JSON.stringify({
+          ok: result.ok === true,
+          action,
+          approval_id: approvalId,
+          settled: result.ok === true ? outcome : null,
+          reason_code: result.reason_code ?? null,
+          detail: result.detail ?? null,
+          acted_by: actor,
+          // Said every time, because a reader who assumes approval ran the dispatch will wait for a result
+          // that is never coming.
+          note: result.ok === true
+            ? 'the request is settled; the dispatch did not run and must be attempted again'
+            : 'the decision was refused; the request is unchanged and still waiting',
+        });
+      }
+
+      const actor = {
+        id: typeof args?.actor_id === 'string' && args.actor_id.trim() !== '' ? args.actor_id.trim() : cfg.machineName,
+        level: isAuthorityLevel(args?.actor_level) ? args.actor_level : null,
+      };
+      // An actor with no level still gets the list: knowing what is waiting does not require the authority to
+      // answer it, and a queue only its supervisors can see is a queue that stays full.
+      const rows = queue.listFor(
+        actor.level === null ? { id: actor.id, level: 0 } : actor,
+        { includeSettled: args?.include_settled === true },
+      );
+      const summary = queue.summary(actor.level === null ? { id: actor.id, level: 0 } : actor);
+      return JSON.stringify({
+        ok: true,
+        action: 'list',
+        as: actor,
+        level_known: actor.level !== null,
+        summary,
+        count: rows.length,
+        rows,
+        note: actor.level === null
+          ? 'no actor_level was supplied, so may_act is reported as if the level were 0: the queue is visible, but whether you may answer any of it is not known'
+          : 'may_act reflects the actor_level supplied',
+      });
+    },
+  }));
 }
 
 /**