@twinsearth/w2m-dsh-plugin 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.24.0",
+  "version": "0.25.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,7 +125,10 @@ 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 { 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 { 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
@@ -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.25.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,
             },
           );