@twinsearth/w2m-dsh-plugin 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ 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.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.**
+
+### The queue belongs to the plugin, not to the call
+
+`apply()` now constructs **one** `createApprovalIndex()` for the plugin's lifetime, lazily. A queue built at
+the call site would be **empty every time**, so a request raised by one dispatch could never be found by the
+decision that answers it — **it would look wired and behave as if it were not.** Same reasoning as the P2P
+runtime beside it: something that must outlive a single call belongs to the plugin.
+
+### Measured, end to end, before it was written down
+
+| Step | Result |
+|---|---|
+| an ordinary actor (49) asks to write | `needs_approval`, `enforced: true` |
+| the request is raised | `ok`, id issued, `subjectLevel` **49** |
+| a captain (50) lists the queue | `may_act: true`, `required_level: 50` |
+| a peer (10) lists the same queue | **sees it**, `may_act: false`, `APPROVAL_INSUFFICIENT_AUTHORITY` |
+| the captain settles it | `ok` |
+| after settling | `approved`, **`subjectLevel` still 49** |
+| the requester approves their own request | **`APPROVAL_SELF_APPROVAL`** |
+
+The fourth row is the one worth naming: **a peer can see work that is above their authority and is not theirs
+to answer.** A filtered list would make the fleet look idle at the moment it is most blocked.
+
+### A queue that refuses is not a queue that needs approval
+
+If `raiseApproval` fails, the dispatch is refused with **`W2M_PERMISSION_APPROVAL_NOT_RAISED`**, a different
+code from `W2M_PERMISSION_NEEDS_APPROVAL`. A caller told "await approval" for a request that was never stored
+would **wait forever for a decision nobody can make.**
+
+### Still true, and stated rather than glossed
+
+The dispatch still **does not run** when approval is required — an escalation is a request to be allowed, not
+a permission. There is **no tool yet for an approver to settle a pending request**; `decide()` exists and is
+exercised by the suite, and wiring it to a tool is the next step. So the chain is closed in code and testable
+end to end, while remaining **unreachable by an operator in the running plugin.**
+
+### My probe was wrong before the code was
+
+The first end-to-end run threw on `listFor(...).requests.length`. `listFor` returns a **row array**, not an
+object with a `requests` field. **The code was right; my assumption about a shape I had not read was wrong**
+— the fifth time in this project, and the same failure as the parse-prefix mistake early on.
+
+**3 new chain tests, 0 failures.**
+
 ## [0.24.0] — 2026-10-15
 
 **The escalation reaches the approval index — and the bridge between them is where the defect would have been.**

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.24.0",
+  "version": "0.26.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

@@ -89,7 +89,7 @@
  */
 
 import { execFile } from 'node:child_process';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -125,8 +125,11 @@ import { mintPunchId, punchSession } from '../agent/p2p.mjs';
 // v0.22.0: the permission gate. Imported rather than reimplemented for the same reason as everything else
 // here -- a second copy of the escalation rule is a second chance to disagree with the first about how far
 // below a requirement an actor may still ask.
-import { gateDispatch, approvalRequestFor } from '../agent/permission.mjs';
-import { isAuthorityLevel } from '../agent/authority.mjs';
+import { gateDispatch, approvalRequestFor, raiseApproval } from '../agent/permission.mjs';
+// 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 { 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.
@@ -190,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.24.0';
+const PLUGIN_VERSION = '0.26.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3202,6 +3205,29 @@ export async function apply(ctx, config = {}) {
     return { machine_id: device.machine_id, machine_name: device.machine_name, machineName: cfg.machineName };
   });
 
+  /**
+   * v0.24.0: the approval queue, one per plugin lifetime.
+   *
+   * ## Why it lives here and not inside the dispatch
+   *
+   * A queue constructed at the call site would be **empty every time**, so a request raised by one dispatch
+   * could never be found by the decision that answers it — the queue would look wired and behave as if it were
+   * not. This is the same reasoning as `p2p` above: something that has to outlive a single call belongs to the
+   * plugin, not to the call.
+   *
+   * Lazy, because a machine that never trips the permission gate should not pay for a queue, and built through
+   * the effect system so a decision still pending at unload does not keep the plugin alive.
+   */
+  let approvals = null;
+  const approvalQueue = () => {
+    if (approvals === null) {
+      approvals = createApprovalIndex({
+        audit: (event, detail) => ctx.logger?.debug?.(`w2m: ${event} ${JSON.stringify(detail ?? {})}`),
+      });
+    }
+    return approvals;
+  };
+
   // v0.6.1: the two browser routes behind the composer's target control. Additive and optional: a
   // host without `connection.fetch` still gets every tool, and `w2m_status` reports the absence  -   // which is the honest place for it, since a host that has no Connection at all is simply not a web
   // composition and does not need a warning on every headless run.
@@ -3725,16 +3751,33 @@ export async function apply(ctx, config = {}) {
           );
         }
         if (gate.decision.verdict === 'needs_approval') {
+          // v0.24.0: the request is QUEUED now, not merely refused with a description of a queue. The
+          // dispatch still does not run -- an escalation is a request to be allowed, not a permission --
+          // but the request is a real entry an approver can find and settle, and its id comes back so the
+          // caller can name what it is waiting on.
           const request = approvalRequestFor(gate.decision, {
             taskId: null,
             machineId: null,
             requestedBy: cfg.machineName,
           });
+          const approvalId = randomUUID();
+          const raised = raiseApproval(approvalQueue(), request, { approvalId, toolName: 'w2m_run' });
+          if (!raised.ok) {
+            // The queue refused it, which is a different failure from needing approval and must not be
+            // reported as one: a caller told "await approval" for a request that was never stored would wait
+            // forever for a decision nobody can make.
+            throw new W2MError(
+              'W2M_PERMISSION_APPROVAL_NOT_RAISED',
+              'W2M_PERMISSION_APPROVAL_NOT_RAISED: ' + raised.reason_code + ': ' + raised.detail,
+              { hint: 'the approval request could not be queued, so this dispatch is refused rather than left waiting', request },
+            );
+          }
           throw new W2MError(
             'W2M_PERMISSION_NEEDS_APPROVAL',
             'W2M_PERMISSION_NEEDS_APPROVAL: ' + gate.decision.detail,
             {
-              hint: 'this dispatch needs an approver; it is refused rather than queued because no approval queue is wired to this call yet',
+              hint: 'this dispatch is queued awaiting an approver; approve or reject it with w2m_approvals, then dispatch again',
+              approval_id: raised.approval_id,
               request,
             },
           );
@@ -5045,6 +5088,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',
+      });
+    },
+  }));
 }
 
 /**