@twinsearth/w2m-dsh-plugin 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -4,6 +4,103 @@ 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.**
+
+Two shapes that look alike and are not:
+
+| `approvalRequestFor()` produces | `index.register()` wants |
+|---|---|
+| `subject_level` (flat) | `subject: { id, level }` (nested) |
+| `capability` | `action` |
+| `task_id`, `requested_by` | `sessionKey`, `subject.id` |
+
+A caller hand-mapping these at the call site would get it right once and wrong later, and **the failure would
+be a request registered against the wrong subject — the one field the whole decision rests on.** So
+`raiseApproval()` owns the mapping and lives beside the thing it maps from.
+
+### It does not smooth anything over
+
+`register()` refuses a subject level that is not an integer 0..100, and the adapter **passes the index's own
+`reason_code` and `detail` through unchanged**. A bridge that substituted a default level to make registration
+succeed would be **inventing the single fact the approver's decision rests on, and would look like success
+while doing it.** Tested directly: a request whose level is `'captain'` is refused, and the queue stays empty.
+
+The `approvalId` is **required from the caller, not generated here**, because an id invented at this layer
+could not be correlated with whoever is waiting on the decision.
+
+### The end-to-end property is asserted, not described
+
+A real `createApprovalIndex()` is constructed in the suite and an escalation is raised into it: the request
+appears in `index.all()`, `subjectLevel` survives the mapping as `49`, and after an approver at level 50
+settles it, **the subject level is still 49** — settling must not rewrite it.
+
+### Two of my own errors, both caught by the suite rather than by reading
+
+* I asserted `INDEX_NO_SUBJECT_LEVEL`. The value is `APPROVAL_NO_SUBJECT_LEVEL` — **every code in
+  `INDEX_REFUSAL` carries the `APPROVAL_` prefix.** The implementation was right and had passed the index's
+  own code through faithfully, which is exactly what the test was there to check. The assertion now reads the
+  value **out of the table** so it cannot drift again.
+* The generator script's escape handling produced a stray `$` inside a template literal in a *failure message*,
+  which threw at runtime rather than at parse time. Caught by running the suite, not by `node --check`.
+
+### Still not wired to a live queue
+
+`createApprovalIndex` has **no caller in the plugin** — it was built in 0.10.0 and is exported from
+`approval-index.mjs` alone. This release makes the gate and the index meet **on a real object**, with an
+end-to-end test, but no dispatch path yet constructs a queue. So `W2M_PERMISSION_NEEDS_APPROVAL` still
+refuses rather than queuing, and it still says so.
+
+**6 new tests, 0 failures.**
+
 ## [0.23.0] — 2026-10-15
 
 **The gate is on the dispatch path. "分权限" now executes, and a machine that has not opted in behaves exactly as before.**

package/package.json

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

@@ -255,6 +255,82 @@ export function approvalRequestFor(decision, context = {}) {
   };
 }
 
+/**
+ * Turn an approval request into the entry the approval index accepts, and register it.
+ *
+ * ## Why this adapter exists rather than a direct call
+ *
+ * The two shapes are close and **not identical**, which is precisely where a defect would live:
+ *
+ * | `approvalRequestFor` produces | `index.register` wants |
+ * |---|---|
+ * | `subject_level` (flat) | `subject: { id, level }` (nested) |
+ * | `capability` | `action` |
+ * | `task_id` / `requested_by` | `sessionKey` / `subject.id` |
+ *
+ * A caller hand-mapping these at the call site would get it right once and wrong later, and the failure would
+ * be a request registered against the wrong subject — the one field the whole decision rests on. So the
+ * mapping lives here, beside the thing it maps from.
+ *
+ * ## What it refuses, and why it does not smooth anything over
+ *
+ * `register` refuses a subject level that is not an integer 0..100, and this adapter **passes the index's own
+ * `reason_code` and `detail` through unchanged**. A bridge that substituted a default level to make
+ * registration succeed would be inventing the single fact the approver's decision rests on, and would look
+ * like success while doing it.
+ *
+ * @param {{register: (entry: object) => {ok: boolean, reason_code?: string, detail?: string}}} index
+ * @param {object} request from {@link approvalRequestFor}
+ * @param {{approvalId: string, sessionKey?: string|null, toolName?: string|null,
+ *   deadlineAt?: number|null, now?: number}} context
+ * @returns {{ok: boolean, approval_id: string|null, reason_code: string|null, detail: string}}
+ */
+export function raiseApproval(index, request, context = {}) {
+  if (index === null || typeof index !== 'object' || typeof index.register !== 'function') {
+    return { ok: false, approval_id: null, reason_code: 'APPROVAL_NO_INDEX', detail: 'no approval index was supplied, so nothing was registered' };
+  }
+  if (request === null || typeof request !== 'object') {
+    return { ok: false, approval_id: null, reason_code: 'APPROVAL_NO_REQUEST', detail: 'no approval request was supplied, so nothing was registered' };
+  }
+  const approvalId = context.approvalId;
+  if (typeof approvalId !== 'string' || approvalId === '') {
+    // Required from the caller rather than generated here: an id invented at this layer could not be
+    // correlated with whoever is waiting for the decision.
+    return {
+      ok: false,
+      approval_id: null,
+      reason_code: 'APPROVAL_NO_ID',
+      detail: 'raiseApproval needs a caller-supplied approvalId, so the request can be correlated with whoever waits on it',
+    };
+  }
+
+  const result = index.register({
+    approvalId,
+    sessionKey: context.sessionKey ?? null,
+    subject: { id: request.requested_by ?? null, level: request.subject_level },
+    action: request.capability,
+    toolName: context.toolName ?? null,
+    reason: request.detail ?? null,
+    ...(Number.isFinite(context.now) ? { openedAt: context.now } : {}),
+    deadlineAt: Number.isFinite(context.deadlineAt) ? context.deadlineAt : null,
+  });
+
+  if (result?.ok !== true) {
+    return {
+      ok: false,
+      approval_id: null,
+      reason_code: result?.reason_code ?? 'APPROVAL_REFUSED',
+      detail: result?.detail ?? 'the approval index refused the request without saying why',
+    };
+  }
+  return {
+    ok: true,
+    approval_id: approvalId,
+    reason_code: null,
+    detail: `registered ${approvalId} for ${request.capability} at subject level ${request.subject_level}`,
+  };
+}
+
 /**
  * Whether a decision may be settled automatically.
  *

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.23.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,
             },
           );