@twinsearth/w2m-dsh-plugin 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -2,6 +2,121 @@
 
 All notable changes to this project are documented here.
 
+## [1.0.3] — 2026-10-17
+
+**The warning that predicted this failure now says what to do about it.**
+
+### What was wrong with the old line
+
+    w2m: no agent is running on this machine, so it is in no fleet and will receive no work.
+         Set autoStartAgent: true to join (the fleet key is derived from the signed-in account),
+         or run w2m-localside yourself and point it at the relay.
+
+**Accurate, and insufficient.** It names **one** of the two things required and does not say *where* to set it.
+
+**Measured on a real machine:** plugin installed, activated, **no error anywhere**, and
+`device_token: null` with `autoStartAgent: false`. The operator's own summary was *"it installed but the machine
+is not in the fleet"* -- **exactly what this warning predicts, and nothing in it resolved that.** The line was
+written for the v0.8.5 failure mode and the operator still had to discover both steps.
+
+### The guidance is now a procedure, and it is ordered
+
+```
+      This machine is NOT paired yet, so both steps below are required.
+      To join, two things are needed:
+        1. a one-time pairing code. `w2m-rabbit` prints it once, in its startup banner:
+             [w2m-rabbit] listening on <url>  pairing code: PAIR-XXXXXXXX
+           It lives in memory only and is never written to the state directory...
+        2. `autoStartAgent: true` plus that code, on the `w2m` row that ALREADY EXISTS...
+               - id: w2m
+                 config:
+                   autoStartAgent: true
+                   pairingCode: PAIR-XXXXXXXX
+           Do NOT add an `insert:` for it. An insert appends a SECOND entry with the same id, and the
+           client then refuses to open -- measured on this project, not theorised.
+```
+
+**It states the current pairing state, because the two cases need different first steps.** An unpaired machine
+must fetch a code; a paired one only has to turn the switch on, and **sending that machine after a code would send
+it somewhere it has no business.** Verifying that branch required reading `device.json` and finding
+`device_token: null`, which is exactly what the rendered warning then said.
+
+**Why pairing cannot be automatic, stated where the operator will read it:** the relay's own header says *"the
+pairing code is the only credential that grants admission"*, and **a plugin able to join unattended would be one
+that lets any machine holding the package into the fleet.** So the fix is guidance, not auto-joining.
+
+### A parameter I wrote into the text before checking that it exists
+
+The first draft told the operator to use **`--print-pairing-code`**. **There is no such flag.** Measured from
+`w2m-rabbit --help`, the real options are:
+
+    --pairing-code <c>     Use a fixed pairing code instead of a generated one.
+    --pair-rate-limit <n>  Pairing attempts per IP per minute. Default 5. 0 = off.
+
+**And `--pairing-code` does the opposite of what I described**: it *chooses* a known code rather than printing an
+existing one. The text now says that, **because a command in an error message is read as an instruction and is
+followed.**
+
+The warning was also **rendered and read** rather than assumed -- a warning nobody has printed is a warning whose
+formatting is guesswork.
+
+## [1.0.2] — 2026-10-16
+
+**One missing line made the whole plugin fail to mount, and it had been missing since v0.41.0.**
+
+### The defect
+
+    JsonSchemaError: unsupported JSON schema:
+      parameters.accept_block.additionalProperties must be explicitly true or false at authorError
+        at parameterSchemaSpecToJsonSchema (dsh-tools/lib/index.js:803)
+        at defineTool (dsh-tools/lib/index.js:848)
+        at Object.apply (src/plugin/tools.mjs:5025)
+
+`w2m_memory`'s `accept_block` was declared as `type: 'object'` **without `additionalProperties`**, and DSH's
+compiler requires it to be explicit. **The throw happens while the tool is being defined, so the entire fiber fails
+to mount** — the client shows the package as `异常`, **all eleven tools disappear**, and the message is visible
+only if something gets far enough to print it.
+
+**That single parameter is the whole failure.** Checked across the entire tool surface: **one `type: 'object'`
+parameter exists in this file, and it was the one.**
+
+### Verified against the real compiler, not the shim
+
+`verify-installed.mjs` runs against an offline shim that checks shape only, **which is why it reported
+`PASS: 11 tools registered` for every broken version**. The real `@deepseek-ai/dsh-tools` was extracted from
+`app.asar` — 10,913 entries, preserving the `node_modules` layout so bare specifiers resolve — and the same call
+was made against it both ways:
+
+    WITHOUT additionalProperties -> THREW JsonSchemaError: ... must be explicitly true or false
+    WITH    additionalProperties -> ACCEPTED
+
+**Same error, same code path as the client reported.** That is the first measurement in this session taken from the
+compiler that actually runs.
+
+### `true`, not `false`
+
+`verifyBlock()` and `acceptWithAuthority()` already validate the block's structure and its hash, **so the schema
+is not the guard here**. A peer that adds a field outside the seven would be refused **for a reason that has nothing
+to do with trust**, and refusing a legitimate block is the worse of the two errors.
+
+### Why this took so long to find, stated plainly
+
+**The error was invisible until the installer was used.** When the package was installed with `pnpm` and then
+removed, the client failed *earlier*, with `cannot resolve profile bundle`, which names a resolution problem and
+not a schema one. **Installing through the plugin manager took it far enough to reach `defineTool` and print the
+real cause.**
+
+**So the user's instinct was right in the way that mattered**: not that the official path behaves differently, but
+that it is the path which gets far enough to report the truth. Four earlier rounds of diagnosis — a fabricated
+incompatibility with the host, a mount-row duplicate, a release-notes defect, a runtime-discovery defect — were all
+real, and **none of them was this**.
+
+### The method that worked
+
+I extracted the host's own compiler from `app.asar` and called it directly. **Every previous attempt had tested
+against a shim, a clone, or an inference**, and each of those agreed with the broken declaration. **The only
+measurement that disagreed was the one taken from the code that throws.**
+
 ## [1.0.1] — 2026-10-16
 
 **The first stable release. Three defects fixed, two of them mine and one of them published 56 times.**

package/package.json

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Cross-platform fleet execution between Windows and macOS: one DeepSeek Harness account, a Rabbit relay, and signed device identity. Ships four Agent Skills describing fleet dispatch, field-level memory acceptance, session references, and resource scheduling.",
   "license": "MIT",
   "keywords": [

package/src/plugin/tools.mjs

@@ -149,7 +149,7 @@ import { AUTHORITY_CHOICES, resolveConfiguredLevel } from '../agent/authority-ch
 // 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.
 import { DeviceKey } from '../agent/crypto.mjs';
-import { loadOrCreateIdentity, saveDeviceToken } from '../agent/identity.mjs';
+import { loadIdentity, loadOrCreateIdentity, saveDeviceToken } from '../agent/identity.mjs';
 import { probeCapsDetailed, detectPlatform } from '../agent/caps.mjs';
 import { resolveStateDir } from '../util/cli.mjs';
 import { parseServer } from '../agent/stun.mjs';
@@ -208,7 +208,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 = '1.0.1';
+const PLUGIN_VERSION = '1.0.3';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -4655,11 +4655,91 @@ export async function apply(ctx, config = {}) {
      * A silent no-op that looks like success is the worst failure mode this plugin has had. One
      * line at warn level turns *"why is this machine not in my fleet"* from an investigation into a
      * log search.
+     *
+     * ## v1.0.3: the line was accurate and still left the operator stuck
+     *
+     * "Set `autoStartAgent: true` to join" names **one** of the two things required and does not say where to set
+     * it. **Both omissions were measured on a real machine**: installed, activated, no error anywhere, and
+     * `device_token: null` with `autoStartAgent: false`. The operator's own summary was *"it installed but the
+     * machine is not in the fleet"* -- exactly what this warning predicts, and nothing in it resolves that.
+     *
+     * So the guidance is now **a procedure, and the procedure is ordered**:
+     *
+     *   1. Pairing needs a **one-time code the operator obtains**. It cannot be self-issued, and that is design
+     *      rather than oversight -- the relay's own header says *"the pairing code is the only credential that
+     *      grants admission"*, and a plugin able to join unattended would be one that lets any machine holding
+     *      the package into the fleet.
+     *   2. `autoStartAgent: true` goes on **the `w2m` row that already exists**, matched by `id` -- **not** as an
+     *      `insert:`, which appends a second row with the same `id` and stops the client from opening.
+     *
+     * **The warning also states the current pairing state, because the two cases need different first steps.**
+     * An unpaired machine must fetch a code; a paired one only has to turn the switch on, and sending *that*
+     * machine after a code would send it somewhere it has no business.
+     */
+    let paired = false;
+    /**
+     * Read the pairing state, **read-only**, and only when a state directory is configured.
+     *
+     * ## Two defects this line caused before it was right, both measured
+     *
+     * **First it called `loadOrCreateIdentity({ dir: cfg.stateDir ?? undefined })`.**
+     *
+     *   * With `stateDir` unset -- the default -- that `undefined` falls back to `~/.dsh/xclient/device.json`,
+     *     **the operator's real file**, and `loadOrCreateIdentity` **creates it when absent**. A message about
+     *     the machine's state must not be able to change it. Four tests in `test/update-wiring.test.mjs` failed
+     *     because the plugin read the real home instead of the profile they supplied.
+     *   * Guarding on `stateDir` fixed those, **and broke a different one**: `test/tools.test.mjs:593` sets an
+     *     empty `stateDir` and asserts `reason_code: DEVICE_NOT_PAIRED` for an **absent** `device.json`.
+     *     `loadOrCreateIdentity` **created that file**, so the very next read found it present-but-unpaired and
+     *     reported `DEVICE_TOKEN_ABSENT` instead. Isolated both ways: `tools.mjs` at 1.0.2 gives `115 pass,
+     *     0 fail`; the version with this call gave `114 pass, 1 fail`.
+     *
+     * **`loadIdentity` is the read-only one** -- `ENOENT` returns `exists: false` and creates nothing -- which is
+     * the only behaviour a diagnostic is entitled to.
+     *
+     * With nothing configured there is no location to consult, so the state is reported as unknown rather than
+     * guessed at, which is what `w2m_status` already says for the same reason (`"stateDir is not set, so no agent
+     * state could be located"`).
      */
+    let stateDirConfigured = false;
+    try {
+      stateDirConfigured = typeof cfg.stateDir === 'string' && cfg.stateDir.trim() !== '';
+      if (stateDirConfigured) {
+        const { identity } = loadIdentity({ dir: cfg.stateDir });
+        paired = typeof identity?.device_token === 'string' && identity.device_token !== '';
+      }
+    } catch {
+      // An unreadable identity is `w2m_status`' business; this line is about joining, so it stays quiet.
+      stateDirConfigured = false;
+    }
     ctx.logger?.warn?.(
-      'w2m: no agent is running on this machine, so it is in no fleet and will receive no work. '
-      + 'Set autoStartAgent: true to join (the fleet key is derived from the signed-in account), '
-      + 'or run w2m-localside yourself and point it at the relay.',
+      'w2m: no agent is running on this machine, so it is in no fleet, will receive no work, and no dispatch '
+      + 'will ever reach it.\n'
+      + `      ${stateDirConfigured
+        ? (paired
+          ? 'This machine IS paired, so step 1 is already done -- only the switch is missing.'
+          : 'This machine is NOT paired yet, so both steps below are required.')
+        : 'No stateDir is configured, so this machine\'s pairing state could not be read; assume it is not '
+          + 'paired and treat both steps below as required.'}\n`
+      + '      To join, two things are needed:\n'
+      + '        1. a one-time pairing code. `w2m-rabbit` prints it once, in its startup banner:\n'
+      + '             [w2m-rabbit] listening on <url>  pairing code: PAIR-XXXXXXXX\n'
+      + '           It lives in memory only and is never written to the state directory, so it is read from\n'
+      + '           the relay\'s console. There is no flag that prints an existing code; starting the relay\n'
+      + '           with `--pairing-code <c>` chooses a KNOWN code instead of a generated one, which is the\n'
+      + '           supported way to make pairing repeatable.\n'
+      + '        2. `autoStartAgent: true` plus that code, on the `w2m` row that ALREADY EXISTS in the\n'
+      + '           profile\'s cordis.patch.yml, matched by id:\n'
+      + '               - id: w2m\n'
+      + '                 config:\n'
+      + '                   autoStartAgent: true\n'
+      + '                   pairingCode: PAIR-XXXXXXXX\n'
+      + '           Do NOT add an `insert:` for it. An insert appends a SECOND entry with the same id, and the\n'
+      + '           client then refuses to open -- measured on this project, not theorised.\n'
+      + '      Or pair without touching this profile at all: run\n'
+      + '          w2m-localside --rabbit <url> --pair <CODE>\n'
+      + '      `w2m_status` reports both facts this line is about -- `identity.paired` and\n'
+      + '      `config.autoStartAgent` -- and is the first thing to read when it appears.',
     );
   }
 
@@ -5067,6 +5147,33 @@ export async function apply(ctx, config = {}) {
       },
       accept_block: {
         type: 'object',
+        /**
+         * `true`, and it has to be stated.
+         *
+         * ## The defect this closes, and why it took so long to see
+         *
+         * DSH's `parameterSchemaSpecToJsonSchema` **requires an explicit `additionalProperties` on every
+         * `type: 'object'` parameter** and throws otherwise:
+         *
+         *     JsonSchemaError: unsupported JSON schema:
+         *       parameters.accept_block.additionalProperties must be explicitly true or false at authorError
+         *         at parameterSchemaSpecToJsonSchema (dsh-tools/lib/index.js:803)
+         *         at defineTool (dsh-tools/lib/index.js:848)
+         *         at Object.apply (src/plugin/tools.mjs:5025)
+         *
+         * **The throw happens while the tool is being defined, so the whole fiber fails to mount** -- the client
+         * reports the package as `异常`, none of the eleven tools appear, and **the message is only visible if
+         * something gets far enough to print it.** This parameter has had that shape since v0.41.0, so the
+         * failure dates from then.
+         *
+         * **`true` rather than `false`:** `verifyBlock()` and `acceptWithAuthority()` already validate the block's
+         * structure and hash, so the schema is not the guard here, and a peer that adds a field outside the seven
+         * would be **refused for a reason that has nothing to do with trust**. Refusing a legitimate block is the
+         * worse error of the two.
+         *
+         * Only one parameter in this file had the shape -- checked across the whole tool surface, not just here.
+         */
+        additionalProperties: true,
         description:
           'v0.41.0. Accept a CAT7 cognitive block received from another machine, per field, DRIVEN BY AN ' +
           'AUTHORITY LEVEL (actor_authority below) rather than accepted whole. A field the level cannot ' +