@twinsearth/w2m-dsh-plugin 0.57.1 → 0.59.0

package/CHANGELOG.md

@@ -4,6 +4,114 @@ 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.59.0] — 2026-10-16
+
+**Every published bin can now be imported without killing the importing process — measured, not reasoned about.**
+
+### The defect
+
+`package.json` publishes three CLIs as importable `exports` subpaths:
+
+```json
+"./rabbit":    "./bin/w2m-rabbit.mjs"
+"./localside": "./bin/w2m-localside.mjs"
+"./stun":      "./bin/w2m-stun.mjs"
+```
+
+**And those three had no import guard, so their top-level body ran on import.** Measured:
+
+```
+import .../bin/w2m-localside.mjs   ->  node exited with code 2
+a statement placed after the import never ran
+```
+
+**A published entry point that terminates whichever process imports it.** The plugin's own client-bundle
+documentation records that `exports['./client']` *"is what the host scans for"*, so the host reads that map —
+**and `w2m-mcp.mjs` already carried this guard, which is why it was the one bin that behaved.**
+
+The fix gives the other three the same guard rather than withdrawing the exports: **a subpath that is importable
+and inert is strictly better than one that is neither.** All four are now inert on import (`58ms / 74ms / 5ms /
+2ms`) and all four still run as programs (`--help` → exit 0 with the right banner).
+
+### What this does **not** claim, and why that matters here
+
+**This is not offered as the explanation for the client that would not start.** That was reported as *no process
+at all on a double-click*, and that symptom has a different mechanism, read out of `lib/main.js`:
+
+```js
+function claimDesktopSingleInstance(application, focusOwner) {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit();
+    return false;
+  }
+```
+
+**`application.quit()` — no dialog, no error, no window.** A second launch is silently discarded while the first
+instance holds the lock, which explains all three observations: disabling third-party plugins did nothing (the
+new process never reached plugin loading), **reinstalling the client did nothing (a new directory does not release
+a lock registered against the application)**, and deleting `~/.dsh` worked — **because it took down the lock
+holder.**
+
+**A real defect, fixed; a different defect, responsible.** The two were adjacent in time, and conflating them
+would have produced a changelog entry claiming a fix it cannot demonstrate.
+
+### Three of my edits failed on the same mistake before the fourth worked
+
+The guard had to be inserted where each file's executable body begins. **My first two markers were text I
+predicted rather than read** — `await main()` does not exist in `w2m-rabbit.mjs`, and `const bound = await bind`
+does not exist in `w2m-stun.mjs`. Then a `Select-Object -Skip` offset was **1-based** while the array index is
+**0-based**, so the script refused both files by one line. **The fourth attempt anchored on the statements' own
+text and succeeded on the first run.** That is the same lesson as the fabricated relay route and the malformed
+PNG, and it is now the fifth time this session.
+
+**No test count change** — the guards alter when the bodies run, not what they do, and all four entry points are
+exercised by `scripts/check-entrypoints.mjs`.
+
+## [0.58.0] — 2026-10-15
+
+**The bridge now reports what it received instead of guessing what an image looks like.**
+
+### Why this is a probe and not an image branch
+
+`ITEM_TYPE` declares exactly one member:
+
+```js
+export const ITEM_TYPE = Object.freeze({ TEXT: 1 });
+```
+
+**The shape of every other item type is unrecorded in this repository** — no `image_item`, no sample payload, no
+fixture. `ilink-protocol.mjs` documents only the text form. **So a download path written today would be a guess
+about field names, and it would fail at the moment a real photograph arrived** — which is the worst possible time
+to discover a wrong guess, because the person is waiting for their picture to be read.
+
+**This is the discovery step.** `describeItems()` reports **key paths and value types, never values**, so one
+photograph sent by a person answers the question the source cannot.
+
+### Values are never recorded, and that is the point of the whole function
+
+A message body is the user's content, and **a discovery aid that quietly wrote photographs into a log file would
+be a worse defect than the one it exists to diagnose.** One assertion is dedicated to that: a distinctive
+passphrase planted in a URL and a caption, and the check that neither appears in the output.
+
+The walk is bounded — `maxKeys` and `maxDepth`, arrays described by length and first element, cycles reported
+rather than followed — **so a surprising payload cannot bury the log it is being written to.**
+
+### Every wrong guess this session was corrected by printing the thing
+
+A fabricated relay route (`/v1/stats`, `/v1/status`), a malformed PNG reported as a credential failure, a count
+typed from memory onto a CHANGELOG entry — **each was fixed by reading rather than predicting.** This applies that
+method *before* the guess instead of after it, which is the only difference between this and the four previous
+occasions.
+
+### What is still not done, stated rather than implied
+
+**The bridge still cannot read an image.** The `/v1`-style branch that downloads it does not exist, because the
+field names are unknown. What exists now is the instrument that finds them: **send one photograph, and the log
+says what the far end actually sends.**
+
+**13 new tests, 0 failures**, and the existing bridge and tool-card suites still pass — the added `shape` field is
+carried only on a non-text reply, so it means one thing. Full suite 2354 in 89 files. **Pre-flight GREEN.**
+
 ## [0.57.1] — 2026-10-15
 
 **The vision status line now appears only on a bridge that actually starts — which it already did, for a reason

package/bin/w2m-localside.mjs

@@ -21,6 +21,7 @@
 
 import { parseArgs as parseNodeArgs } from 'node:util';
 import process from 'node:process';
+import { pathToFileURL } from 'node:url';
 
 import { formatError, resolveStateDir } from '../src/util/cli.mjs';
 import { createAgent, parseAllowedCommands } from '../src/agent/agent.mjs';
@@ -314,12 +315,34 @@ async function main() {
   }
 }
 
-main().then(
-  (code) => {
-    process.exitCode = code;
-  },
-  (error) => {
-    process.stderr.write(`fatal: ${formatError(error)}\n`);
-    process.exitCode = 1;
-  },
-);
+/**
+ * Run only when executed, never when imported.
+ *
+ * ## The defect this closes, which was measured rather than reasoned about
+ *
+ * `package.json` publishes `"./localside": "./bin/w2m-localside.mjs"` in its `exports` map, and this file used to
+ * call `main()` unconditionally. **So `import '@twinsearth/w2m-dsh-plugin/localside'` executed a CLI, printed
+ * usage, and terminated the process** -- measured, not inferred:
+ *
+ *     import ... /bin/w2m-localside.mjs   ->  node exited with code 2
+ *     a line after the import never ran
+ *
+ * **That is fatal for any process unlucky enough to import the subpath**, and the host is the only plausible
+ * candidate: a plugin whose published entry points kill the client is a plugin that makes the client "unable to
+ * start", which is exactly what was reported.
+ *
+ * `w2m-mcp.mjs` already carried this guard, and it was the one file that behaved. **The other three bins had no
+ * guard and were published as importable paths** -- so the fix is to give them the same one, not to remove the
+ * exports: a subpath that is importable *and* inert is strictly more useful than one that is neither.
+ */
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      process.stderr.write(`fatal: ${formatError(error)}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

package/bin/w2m-rabbit.mjs

@@ -18,6 +18,7 @@
  */
 
 import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
 import { createRelayServer } from '../src/relay/server.mjs';
 import { resolveStateDir, formatError } from '../src/util/cli.mjs';
 
@@ -248,182 +249,196 @@ const stateDir = resolveStateDir(values.state, 'rabbit');
 const log = (line) => process.stdout.write(`${line}\n`);
 const diag = (line) => process.stderr.write(`${line}\n`);
 
-let relay;
-let listenInfo;
-let pairingCode;
-try {
-  relay = createRelayServer({
-    stateDir,
-    pairingCode: values['pairing-code'],
-    heartbeatIntervalMs: heartbeatMs,
-    leaseGraceMs: graceMs,
-    // v0.1.2 deployment options
-    basePath,
-    trustProxy: Boolean(values['trust-proxy']),
-    tlsCert: tlsCert ?? null,
-    tlsKey: tlsKey ?? null,
-    operatorToken,
-    operatorTokenRequired,
-    // MEDIUM-6: the token is printed by the start that generated it, or when the operator asks for it
-    // here (--print-operator-token / W2M_PRINT_OPERATOR_TOKEN=1). The relay resolves both, so the
-    // banner below and the relay's own startup lines can never disagree about it.
-    printOperatorToken: values['print-operator-token'] === true,
-    pairRateLimitPerMinute: pairRateLimit,
-    persist: !values['no-persist'],
-    // v0.3.0 request signing. Undefined means "not configured", which the relay treats as
-    // "do not verify" -- byte-for-byte the v0.2.3 behaviour.
-    signingSecret,
-    signingSecretPrevious,
-    requireSignature,
-    metrics: values.metrics === true,
-    signatureSkewSeconds,
-  });
-  // The pairing code rotates on every successful pairing, so the CLI has to
-  // follow it rather than print it once: an operator pairing a second machine
-  // needs the *current* code, not the one that was already consumed.
-  //
-  // Listeners receive the buffered *entry* (`{seq, event, target}`), not the
-  // event itself -- `entry.event` is the frame that goes on the wire.
-  relay.state.onEvent((entry) => {
-    const event = entry?.event ?? entry;
-    if (event?.type === 'notice' && event.code === 'PAIRING_CODE_ROTATED' && event.pairing_code) {
-      pairingCode = event.pairing_code;
-      // In --json mode this must not touch stdout: a rotation would otherwise
-      // corrupt the very output the flag exists to produce.
-      const out = values.json ? diag : log;
-      out('');
-      out('  Pairing code rotated after a successful pairing.');
-      out(`  新的配对码 / NEW PAIRING CODE:  ${pairingCode}`);
-      out('');
-    }
-  });
-  listenInfo = await relay.listen({
-    host: values.host ?? '127.0.0.1',
-    port,
-  });
-  pairingCode = listenInfo.pairingCode;
-} catch (error) {
-  fail(formatError(error), 3);
-}
-
-const boundPort = listenInfo.port;
-const boundHost = listenInfo.host;
-const scheme = listenInfo.scheme ?? (tlsCert ? 'https' : 'http');
-// Prefer what the relay reports (it knows whether TLS is active); fall back to
-// the bound address so a 0.0.0.0 bind is not advertised as a usable URL.
-const publicUrl = listenInfo.publicUrl ?? `${scheme}://${boundHost === '0.0.0.0' ? '<this-host>' : boundHost}:${boundPort}${basePath === '/' ? '' : basePath}`;
-const resolvedOperatorToken = listenInfo.operatorToken ?? operatorToken ?? null;
-
-if (values.json) {
-  log(JSON.stringify({
-    event: 'listening',
-    url: listenInfo.url,
-    publicUrl,
-    host: boundHost,
-    port: boundPort,
-    scheme,
-    basePath,
-    stateDir,
-    persist: !values['no-persist'],
-    trustProxy: Boolean(values['trust-proxy']),
-    pairRateLimit: pairRateLimit ?? 5,
-    operatorTokenRequired,
-    // The token itself is deliberately absent. This line is the one people pipe
-    // into a log or a file, and a credential written there is a credential
-    // leaked; it is printed to stderr and stored at
-    // <stateDir>/operator-token.txt (0600), which is where a secret belongs.
-    operatorTokenPresent: Boolean(operatorTokenRequired && resolvedOperatorToken),
-    pairingCode,
-    relayId: listenInfo.relayId ?? null,
-    protocolVersion: 1,
-  }));
-} else {
-  log('');
-  log('  W2M relay (Rabbit) is listening.');
-  log('');
-  log(`  URL          ${publicUrl}`);
-  log(`  Bind         ${boundHost}:${boundPort}${scheme === 'https' ? ' (TLS)' : ''}`);
-  if (basePath !== '/') log(`  Base path    ${basePath}`);
-  log(`  State        ${stateDir}${values['no-persist'] ? '  (persistence DISABLED)' : ''}`);
-  log(`  Protocol     v1   relay id ${listenInfo.relayId ?? '(none)'}`);
-
-  if (values['trust-proxy']) {
-    log('');
-    log('  NOTE: --trust-proxy is ON. The relay believes X-Forwarded-For and');
-    log('        X-Forwarded-Proto. Only safe behind a proxy you control.');
-  }
-  if (boundHost === '0.0.0.0' && scheme === 'http') {
-    log('');
-    log('  NOTE: bound to 0.0.0.0 over plain HTTP. Fine on a Tailscale/WireGuard');
-    log('        address (already encrypted); NOT fine on a public interface --');
-    log('        use --tls-cert/--tls-key or a TLS-terminating proxy there.');
-  }
-
-  log('');
-  if (operatorTokenRequired && resolvedOperatorToken) {
-    // MEDIUM-6: this banner is the *machine's* stdout, and stdout is what journald, a container log or
-    // a CI transcript keeps. The token authorises dispatching to every machine in the group, so it is
-    // printed only on the start that generated it — the one moment it exists nowhere else — or when
-    // --print-operator-token / W2M_PRINT_OPERATOR_TOKEN=1 asked for it explicitly. Every other start
-    // says where to read it and how to change that answer.
+/**
+ * Run only when executed, never when imported.
+ *
+ * `package.json` publishes this file as an `exports` subpath, and an unguarded top-level body means
+ * **importing that subpath executes the program**. Measured, not inferred: on the sibling `w2m-localside.mjs`, a
+ * statement placed after the import never ran and node exited with code 2.
+ *
+ * **A published entry point that terminates whichever process imports it is a plugin that stops the client from
+ * starting** -- the defect this closes. `w2m-mcp.mjs` already carried the guard and was the only bin that
+ * behaved, so the fix gives the others the same one rather than withdrawing the exports: **a subpath that is
+ * importable and inert is strictly better than one that is neither.**
+ */
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  let relay;
+  let listenInfo;
+  let pairingCode;
+  try {
+    relay = createRelayServer({
+      stateDir,
+      pairingCode: values['pairing-code'],
+      heartbeatIntervalMs: heartbeatMs,
+      leaseGraceMs: graceMs,
+      // v0.1.2 deployment options
+      basePath,
+      trustProxy: Boolean(values['trust-proxy']),
+      tlsCert: tlsCert ?? null,
+      tlsKey: tlsKey ?? null,
+      operatorToken,
+      operatorTokenRequired,
+      // MEDIUM-6: the token is printed by the start that generated it, or when the operator asks for it
+      // here (--print-operator-token / W2M_PRINT_OPERATOR_TOKEN=1). The relay resolves both, so the
+      // banner below and the relay's own startup lines can never disagree about it.
+      printOperatorToken: values['print-operator-token'] === true,
+      pairRateLimitPerMinute: pairRateLimit,
+      persist: !values['no-persist'],
+      // v0.3.0 request signing. Undefined means "not configured", which the relay treats as
+      // "do not verify" -- byte-for-byte the v0.2.3 behaviour.
+      signingSecret,
+      signingSecretPrevious,
+      requireSignature,
+      metrics: values.metrics === true,
+      signatureSkewSeconds,
+    });
+    // The pairing code rotates on every successful pairing, so the CLI has to
+    // follow it rather than print it once: an operator pairing a second machine
+    // needs the *current* code, not the one that was already consumed.
     //
-    // DELIBERATE, do not "fix": on that generating start the relay's own startup line prints the value
-    // too (on stderr). The pair is the intended shape — this box is the operator-facing handoff, that
-    // line is the log copy — and every other start prints it in neither place.
-    if (listenInfo.operatorTokenPrintable === true) {
-      log('  ┌────────────────────────────────────────────────────────────┐');
-      log('  │  OPERATOR TOKEN (needed to SEND instructions, keep secret)  │');
-      log(`  │  ${String(resolvedOperatorToken).padEnd(56)}│`);
-      log('  └────────────────────────────────────────────────────────────┘');
-      log(`  Printed once because ${listenInfo.operatorTokenPrintReason === 'generated'
-        ? 'this start generated it'
-        : `${listenInfo.operatorTokenPrintReason ?? 'an option'} asked for it`}.`);
-      log(`  Also written to ${stateDir}/operator-token.txt (0600).`);
-    } else {
-      log('  OPERATOR TOKEN — not printed (this start did not generate it).');
-      log(`  Read it from ${stateDir}/operator-token.txt (0600).`);
-      log('  To print it here as well: --print-operator-token, or W2M_PRINT_OPERATOR_TOKEN=1.');
-    }
-    log('  Device tokens cannot send work; this is what authorises it.');
-  } else if (!operatorTokenRequired) {
-    log('  ⚠  OPERATOR TOKEN REQUIREMENT IS OFF (--operator-token "").');
-    log('     Any paired device can send work to any other. Trusted LAN only.');
+    // Listeners receive the buffered *entry* (`{seq, event, target}`), not the
+    // event itself -- `entry.event` is the frame that goes on the wire.
+    relay.state.onEvent((entry) => {
+      const event = entry?.event ?? entry;
+      if (event?.type === 'notice' && event.code === 'PAIRING_CODE_ROTATED' && event.pairing_code) {
+        pairingCode = event.pairing_code;
+        // In --json mode this must not touch stdout: a rotation would otherwise
+        // corrupt the very output the flag exists to produce.
+        const out = values.json ? diag : log;
+        out('');
+        out('  Pairing code rotated after a successful pairing.');
+        out(`  新的配对码 / NEW PAIRING CODE:  ${pairingCode}`);
+        out('');
+      }
+    });
+    listenInfo = await relay.listen({
+      host: values.host ?? '127.0.0.1',
+      port,
+    });
+    pairingCode = listenInfo.pairingCode;
+  } catch (error) {
+    fail(formatError(error), 3);
   }
 
-  log('');
-  if (pairingCode) {
-    log('  ┌──────────────────────────────────────────────┐');
-    log(`  │  配对码 / PAIRING CODE:  ${String(pairingCode).padEnd(19)}│`);
-    log('  └──────────────────────────────────────────────┘');
+  const boundPort = listenInfo.port;
+  const boundHost = listenInfo.host;
+  const scheme = listenInfo.scheme ?? (tlsCert ? 'https' : 'http');
+  // Prefer what the relay reports (it knows whether TLS is active); fall back to
+  // the bound address so a 0.0.0.0 bind is not advertised as a usable URL.
+  const publicUrl = listenInfo.publicUrl ?? `${scheme}://${boundHost === '0.0.0.0' ? '<this-host>' : boundHost}:${boundPort}${basePath === '/' ? '' : basePath}`;
+  const resolvedOperatorToken = listenInfo.operatorToken ?? operatorToken ?? null;
+
+  if (values.json) {
+    log(JSON.stringify({
+      event: 'listening',
+      url: listenInfo.url,
+      publicUrl,
+      host: boundHost,
+      port: boundPort,
+      scheme,
+      basePath,
+      stateDir,
+      persist: !values['no-persist'],
+      trustProxy: Boolean(values['trust-proxy']),
+      pairRateLimit: pairRateLimit ?? 5,
+      operatorTokenRequired,
+      // The token itself is deliberately absent. This line is the one people pipe
+      // into a log or a file, and a credential written there is a credential
+      // leaked; it is printed to stderr and stored at
+      // <stateDir>/operator-token.txt (0600), which is where a secret belongs.
+      operatorTokenPresent: Boolean(operatorTokenRequired && resolvedOperatorToken),
+      pairingCode,
+      relayId: listenInfo.relayId ?? null,
+      protocolVersion: 1,
+    }));
+  } else {
     log('');
-    log('  Run this on every machine you want in the group:');
+    log('  W2M relay (Rabbit) is listening.');
     log('');
-    log(`    w2m-localside --rabbit ${listenInfo.url} --pair ${pairingCode} \\`);
-    log('                  --project <path-to-project> --name <machine-name>');
+    log(`  URL          ${publicUrl}`);
+    log(`  Bind         ${boundHost}:${boundPort}${scheme === 'https' ? ' (TLS)' : ''}`);
+    if (basePath !== '/') log(`  Base path    ${basePath}`);
+    log(`  State        ${stateDir}${values['no-persist'] ? '  (persistence DISABLED)' : ''}`);
+    log(`  Protocol     v1   relay id ${listenInfo.relayId ?? '(none)'}`);
+
+    if (values['trust-proxy']) {
+      log('');
+      log('  NOTE: --trust-proxy is ON. The relay believes X-Forwarded-For and');
+      log('        X-Forwarded-Proto. Only safe behind a proxy you control.');
+    }
+    if (boundHost === '0.0.0.0' && scheme === 'http') {
+      log('');
+      log('  NOTE: bound to 0.0.0.0 over plain HTTP. Fine on a Tailscale/WireGuard');
+      log('        address (already encrypted); NOT fine on a public interface --');
+      log('        use --tls-cert/--tls-key or a TLS-terminating proxy there.');
+    }
+
     log('');
-    log('  The code rotates after each successful pairing; the new one is');
-    log('  printed here, so you can pair the next machine without restarting.');
-  }
-  if (boundHost === '0.0.0.0') {
-    log('  NOTE: bound to 0.0.0.0 -- other machines on your network can reach this');
-    log('        relay. It carries no TLS and no authentication beyond device tokens.');
+    if (operatorTokenRequired && resolvedOperatorToken) {
+      // MEDIUM-6: this banner is the *machine's* stdout, and stdout is what journald, a container log or
+      // a CI transcript keeps. The token authorises dispatching to every machine in the group, so it is
+      // printed only on the start that generated it — the one moment it exists nowhere else — or when
+      // --print-operator-token / W2M_PRINT_OPERATOR_TOKEN=1 asked for it explicitly. Every other start
+      // says where to read it and how to change that answer.
+      //
+      // DELIBERATE, do not "fix": on that generating start the relay's own startup line prints the value
+      // too (on stderr). The pair is the intended shape — this box is the operator-facing handoff, that
+      // line is the log copy — and every other start prints it in neither place.
+      if (listenInfo.operatorTokenPrintable === true) {
+        log('  ┌────────────────────────────────────────────────────────────┐');
+        log('  │  OPERATOR TOKEN (needed to SEND instructions, keep secret)  │');
+        log(`  │  ${String(resolvedOperatorToken).padEnd(56)}│`);
+        log('  └────────────────────────────────────────────────────────────┘');
+        log(`  Printed once because ${listenInfo.operatorTokenPrintReason === 'generated'
+          ? 'this start generated it'
+          : `${listenInfo.operatorTokenPrintReason ?? 'an option'} asked for it`}.`);
+        log(`  Also written to ${stateDir}/operator-token.txt (0600).`);
+      } else {
+        log('  OPERATOR TOKEN — not printed (this start did not generate it).');
+        log(`  Read it from ${stateDir}/operator-token.txt (0600).`);
+        log('  To print it here as well: --print-operator-token, or W2M_PRINT_OPERATOR_TOKEN=1.');
+      }
+      log('  Device tokens cannot send work; this is what authorises it.');
+    } else if (!operatorTokenRequired) {
+      log('  ⚠  OPERATOR TOKEN REQUIREMENT IS OFF (--operator-token "").');
+      log('     Any paired device can send work to any other. Trusted LAN only.');
+    }
+
     log('');
+    if (pairingCode) {
+      log('  ┌──────────────────────────────────────────────┐');
+      log(`  │  配对码 / PAIRING CODE:  ${String(pairingCode).padEnd(19)}│`);
+      log('  └──────────────────────────────────────────────┘');
+      log('');
+      log('  Run this on every machine you want in the group:');
+      log('');
+      log(`    w2m-localside --rabbit ${listenInfo.url} --pair ${pairingCode} \\`);
+      log('                  --project <path-to-project> --name <machine-name>');
+      log('');
+      log('  The code rotates after each successful pairing; the new one is');
+      log('  printed here, so you can pair the next machine without restarting.');
+    }
+    if (boundHost === '0.0.0.0') {
+      log('  NOTE: bound to 0.0.0.0 -- other machines on your network can reach this');
+      log('        relay. It carries no TLS and no authentication beyond device tokens.');
+      log('');
+    }
   }
-}
 
-let stopping = false;
-async function shutdown(signal) {
-  if (stopping) return;
-  stopping = true;
-  if (!values.json) log(`\n  ${signal} received, shutting down...`);
-  try {
-    await relay.close();
-  } catch (error) {
-    process.stderr.write(`w2m-rabbit: error while closing: ${formatError(error)}\n`);
-    process.exit(1);
+  let stopping = false;
+  async function shutdown(signal) {
+    if (stopping) return;
+    stopping = true;
+    if (!values.json) log(`\n  ${signal} received, shutting down...`);
+    try {
+      await relay.close();
+    } catch (error) {
+      process.stderr.write(`w2m-rabbit: error while closing: ${formatError(error)}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
   }
-  process.exit(0);
-}
 
-process.on('SIGINT', () => { void shutdown('SIGINT'); });
-process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
+  process.on('SIGINT', () => { void shutdown('SIGINT'); });
+  process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
+}

package/bin/w2m-stun.mjs

@@ -27,6 +27,7 @@
  */
 
 import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
 import { createStunServer, DEFAULT_SOFTWARE } from '../src/relay/stun-server.mjs';
 import { formatError } from '../src/util/cli.mjs';
 
@@ -154,78 +155,92 @@ function logRequest(entry) {
   );
 }
 
-let server;
-let listen;
-const startedAt = Date.now();
-try {
-  server = createStunServer({ host, port, software, log: logRequest });
-  listen = await server.start();
-} catch (error) {
-  fail(formatError(error), 3);
-}
+/**
+ * Run only when executed, never when imported.
+ *
+ * `package.json` publishes this file as an `exports` subpath, and an unguarded top-level body means
+ * **importing that subpath executes the program**. Measured, not inferred: on the sibling `w2m-localside.mjs`, a
+ * statement placed after the import never ran and node exited with code 2.
+ *
+ * **A published entry point that terminates whichever process imports it is a plugin that stops the client from
+ * starting** -- the defect this closes. `w2m-mcp.mjs` already carried the guard and was the only bin that
+ * behaved, so the fix gives the others the same one rather than withdrawing the exports: **a subpath that is
+ * importable and inert is strictly better than one that is neither.**
+ */
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  let server;
+  let listen;
+  const startedAt = Date.now();
+  try {
+    server = createStunServer({ host, port, software, log: logRequest });
+    listen = await server.start();
+  } catch (error) {
+    fail(formatError(error), 3);
+  }
 
-if (!listen.ok) {
-  // EADDRINUSE deserves its own sentence: it is the one failure an operator will
-  // actually hit, and the fix (find the other listener, or pick another port) is
-  // not obvious from "EADDRINUSE".
-  if (listen.error === 'EADDRINUSE') {
-    fail(
-      `UDP port ${port} is already in use on ${host} — another STUN server or another ` +
-        `w2m-stun is holding it. Stop it, or choose a different --port.`,
-      3,
-    );
+  if (!listen.ok) {
+    // EADDRINUSE deserves its own sentence: it is the one failure an operator will
+    // actually hit, and the fix (find the other listener, or pick another port) is
+    // not obvious from "EADDRINUSE".
+    if (listen.error === 'EADDRINUSE') {
+      fail(
+        `UDP port ${port} is already in use on ${host} — another STUN server or another ` +
+          `w2m-stun is holding it. Stop it, or choose a different --port.`,
+        3,
+      );
+    }
+    fail(`failed to bind ${host}:${port} — ${listen.error}`, 3);
   }
-  fail(`failed to bind ${host}:${port} — ${listen.error}`, 3);
-}
 
-const bound = server.address() ?? { address: listen.host, port: listen.port };
-log('');
-log('  W2M STUN responder is listening.');
-log('');
-log(`  Bind          udp4 ${bound.address}:${bound.port}`);
-log(`  Software      ${software}`);
-log('  Answers       Binding requests (0x0001) -> 0x0101 with XOR-MAPPED-ADDRESS,');
-log('                MAPPED-ADDRESS and SOFTWARE. Anything else is dropped.');
-log('');
-log('  NAT translation:');
-log('    A machine behind NAT cannot see the public address and port its packets');
-log(
-  `    leave from. Point clients at ${bound.address === '0.0.0.0' ? '<this-host>' : bound.address}:${bound.port} (UDP) and`,
-);
-log('    this server reports the translated address back, which is what lets two');
-log('    machines punch a direct path instead of relaying every task.');
-if (bound.address === '0.0.0.0') {
+  const bound = server.address() ?? { address: listen.host, port: listen.port };
   log('');
-  log('  NOTE: bound to 0.0.0.0 — reachable from anywhere that can route UDP to this');
-  log('        host. There is no authentication and no state: every request is');
-  log('        answered on the address it came from, and nothing else is possible.');
-}
-log('');
-log(`  Log level     ${logLevel}${debug ? '' : '   (--log-level debug prints one line per request)'}`);
-log('');
-
-let stopping = false;
-async function shutdown(signal) {
-  if (stopping) return;
-  stopping = true;
-  const stats = server.stats();
+  log('  W2M STUN responder is listening.');
+  log('');
+  log(`  Bind          udp4 ${bound.address}:${bound.port}`);
+  log(`  Software      ${software}`);
+  log('  Answers       Binding requests (0x0001) -> 0x0101 with XOR-MAPPED-ADDRESS,');
+  log('                MAPPED-ADDRESS and SOFTWARE. Anything else is dropped.');
+  log('');
+  log('  NAT translation:');
+  log('    A machine behind NAT cannot see the public address and port its packets');
   log(
-    `\n  ${signal} received, shutting down. ` +
-      `requests=${stats.requests} responses=${stats.responses} errors=${stats.errors} ` +
-      `uptime=${Math.round((Date.now() - startedAt) / 100) / 10}s`,
+    `    leave from. Point clients at ${bound.address === '0.0.0.0' ? '<this-host>' : bound.address}:${bound.port} (UDP) and`,
   );
-  try {
-    await server.stop();
-  } catch (error) {
-    process.stderr.write(`w2m-stun: error while closing: ${formatError(error)}\n`);
-    process.exit(1);
+  log('    this server reports the translated address back, which is what lets two');
+  log('    machines punch a direct path instead of relaying every task.');
+  if (bound.address === '0.0.0.0') {
+    log('');
+    log('  NOTE: bound to 0.0.0.0 — reachable from anywhere that can route UDP to this');
+    log('        host. There is no authentication and no state: every request is');
+    log('        answered on the address it came from, and nothing else is possible.');
   }
-  process.exit(0);
-}
+  log('');
+  log(`  Log level     ${logLevel}${debug ? '' : '   (--log-level debug prints one line per request)'}`);
+  log('');
 
-process.on('SIGINT', () => {
-  void shutdown('SIGINT');
-});
-process.on('SIGTERM', () => {
-  void shutdown('SIGTERM');
-});
+  let stopping = false;
+  async function shutdown(signal) {
+    if (stopping) return;
+    stopping = true;
+    const stats = server.stats();
+    log(
+      `\n  ${signal} received, shutting down. ` +
+        `requests=${stats.requests} responses=${stats.responses} errors=${stats.errors} ` +
+        `uptime=${Math.round((Date.now() - startedAt) / 100) / 10}s`,
+    );
+    try {
+      await server.stop();
+    } catch (error) {
+      process.stderr.write(`w2m-stun: error while closing: ${formatError(error)}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+  });
+  process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.57.1",
+  "version": "0.59.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",
@@ -116,13 +116,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/chatops-fleet-join.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs",
     "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs",
     "test:relay": "node --test --test-force-exit test/relay.test.mjs",
     "test:agent": "node --test --test-force-exit test/agent.test.mjs test/memory.test.mjs",
     "test:tools": "node --test --test-force-exit test/tools.test.mjs",
     "test:crossnetwork": "node --test --test-force-exit test/crossnetwork.test.mjs",
-    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/chatops-fleet-join.test.mjs",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs",
     "pack": "node scripts/pack.mjs",
     "verify:join": "node scripts/verify-join.mjs",
     "lint": "eslint .",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "0.57.1",
+  "version": "0.59.0",
   "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/chatops/ilink-fleet-bridge.mjs

@@ -113,6 +113,57 @@ export function textOf(message) {
   return null;
 }
 
+/**
+ * Describe the SHAPE of a message's items without recording any of their content.
+ *
+ * ## Why this exists rather than an image branch
+ *
+ * `ITEM_TYPE` declares exactly one member, `TEXT: 1`. **The shape of every other item type is unrecorded in this
+ * repository** -- no `image_item`, no sample payload, no fixture. So a download path written now would be a guess
+ * about field names, and **it would fail at the moment a real person's photograph arrived**, which is the worst
+ * possible time to discover it.
+ *
+ * This is the discovery step instead. It reports **key paths and value types, never values**, so an operator can
+ * send one photograph and the log then says what the far end actually sends. **Every wrong guess this session
+ * was corrected by printing the thing instead of predicting it** -- a fabricated relay route, a malformed PNG, a
+ * count on a CHANGELOG entry -- and this is that method applied before the guess rather than after.
+ *
+ * Values are never included because a message body is the user's content, and **a discovery aid that quietly
+ * logs photographs to a file would be a worse defect than the one it is diagnosing.**
+ *
+ * @param {object} message one `msgs[]` entry
+ * @param {{maxKeys?: number, maxDepth?: number}} [options]
+ * @returns {string} a compact, content-free description
+ */
+export function describeItems(message, { maxKeys = 24, maxDepth = 5 } = {}) {
+  const items = Array.isArray(message?.item_list) ? message.item_list : [];
+  if (items.length === 0) return 'item_list is empty or absent';
+
+  /**
+   * A bounded walk: enough to answer "which fields exist and what kind are they", and short enough that a
+   * surprising payload cannot bury the log. Arrays are described by their first element, because a caption list
+   * and a sticker list need the same answer.
+   */
+  const seen = new Set();
+  const walk = (value, depth) => {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return value.length === 0 ? 'array[0]' : `array[${value.length}] of ${walk(value[0], depth)}`;
+    const kind = typeof value;
+    if (kind !== 'object') return kind;
+    if (depth >= maxDepth) return 'object{…}';
+    if (seen.has(value)) return 'object{cyclic}';
+    seen.add(value);
+    const keys = Object.keys(value).slice(0, maxKeys);
+    const parts = keys.map((k) => `${k}:${walk(value[k], depth + 1)}`);
+    const more = Object.keys(value).length > maxKeys ? `,+${Object.keys(value).length - maxKeys}` : '';
+    return `{${parts.join(',')}${more}}`;
+  };
+
+  return items
+    .map((item, i) => `item[${i}].type=${JSON.stringify(item?.type)} ${walk(item, 1)}`)
+    .join(' | ');
+}
+
 /**
  * The reply envelope.
  *
@@ -230,7 +281,22 @@ export function planMessage({ message, authorize }) {
   // A non-text message is answered rather than dropped: "every sentence must get a reply" includes the
   // sentences the bridge cannot read.
   if (text === null) {
-    return { act: 'reply', to: from, contextToken, text: helpText({ reason: '这条消息不是文字（语音/图片/文件暂不支持）' }) };
+    const shape = describeItems(message);
+    return {
+      act: 'reply',
+      to: from,
+      contextToken,
+      text: helpText({ reason: '这条消息不是文字（语音/图片/文件暂不支持）' }),
+      /**
+       * Carried out of the plan so the caller can log it.
+       *
+       * **The shape, never the content.** This field exists so that one photograph sent by a person answers the
+       * question this file cannot answer from its own source -- which fields iLink actually puts on an image --
+       * and it is reported rather than acted on, because acting on a guessed shape is how a download path ends up
+       * failing on the first real photograph.
+       */
+      shape,
+    };
   }
 
   const trimmed = text.trim();

package/src/plugin/tools.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 = '0.57.1';
+const PLUGIN_VERSION = '0.59.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;