@twinsearth/w2m-dsh-plugin 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ 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.**

package/package.json

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

@@ -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.26.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,