@twinsearth/w2m-dsh-plugin 0.58.0 → 0.60.0

package/CHANGELOG.md

@@ -4,6 +4,134 @@ 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.60.0] — 2026-10-16
+
+**Two things learned from a client that would not start, neither of which was a crash in this plugin.**
+
+### §3.1 in `TROUBLESHOOTING.md`: check the lock before you check the plugin
+
+A launch that leaves **no process at all** is a different failure from one that starts and reports something, and
+the existing §3 procedure will mislead anyone who skips that distinction — it assumes the application *ran*.
+
+**The mechanism is one function in `@deepseek-ai/dsh-desktop`'s `lib/main.js`:**
+
+```js
+function claimDesktopSingleInstance(application, focusOwner) {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit();          // no dialog, no error, no window
+    return false;
+  }
+```
+
+**A second launch is silently discarded while the first instance holds the lock.** Electron registers it against
+the *application*, not a directory — which is why the two natural remedies both fail, and why the section now says
+so before offering any plugin diagnosis:
+
+| What was tried | Why it did nothing |
+|---|---|
+| disable third-party plugins before restarting | the new process quits at the lock, before plugin loading |
+| reinstall the client (new folder, new exe) | a new directory does not release an application-scoped lock |
+
+**Deleting `~/.dsh` fixed it — not because anything in it was corrupt, but because the deletion took down the
+process still holding the lock.** The section now leads with the measurement that costs nothing:
+
+```powershell
+Get-Process -Name 'DeepSeek Harness' | Select-Object Id, StartTime
+```
+
+**Processes listed → it is the lock, end them and retry. Nothing listed → the failure really is pre-lock, and §3's
+procedure applies.** The deleted directory carried session history and profile configuration; **`Stop-Process`
+would have cost nothing.**
+
+### `scripts/session-retention.mjs`: the store is bounded, out-of-band, as DSH says it must be
+
+`@deepseek-ai/dsh-session-persistence`'s README, under *Known Limitations*:
+
+> **No deletion or retention API** — pruning stored sessions is **out-of-band backend maintenance**.
+
+**So this is not a workaround for a missing feature: the host states retention is the operator's job.** The
+measurement that motivated it is that **one session reached 18.03 MiB of an 18.07 MiB store**, nothing bounds it,
+and every start reads the store.
+
+Three refusals are built in, and each is a deliberate limit rather than an omission:
+
+* **The newest session of every workspace is never removed.** DSH writes to it, and *which* process is writing
+  cannot be checked reliably from outside — so the rule is the one that needs no knowledge of the running
+  process.
+* **`--apply` is required.** The default prints the plan and exits 0. **A tool that removes conversation history
+  shows what it will remove before it removes it.**
+* **A directory that is not a session is reported, not touched**, because the layout is read from the filesystem
+  rather than assumed.
+
+**Verified against the real store:** at a 256 MiB cap it reports *"under the cap — nothing to remove"*; at a
+1 MiB cap it plans two removals and leaves the 18 MiB live session alone.
+
+**No test count change** — both additions are a document and a script, and the script is exercised by hand against
+the store it bounds rather than by a fixture that would not resemble it.
+
+## [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.**

package/TROUBLESHOOTING.md

@@ -258,6 +258,59 @@ after removal, remove the `w2m` row from `cordis.patch.yml` by hand (§2) before
 **Not us.** If the failure is in a _different_ plugin's entry and this one is merely in the same
 profile, the loader reports the package name in the same line — read it before assuming it is ours.
 
+### 3.1 First rule: if a double-click produces NO process, it is not a plugin
+
+**This section's decision procedure below will mislead you if you skip this step.** It assumes the
+application *ran and reported something*. A launch that leaves **no process at all** — nothing in Task
+Manager, no window, no dialog — is a different failure, and the plugin is not the cause.
+
+**The mechanism**, read out of `@deepseek-ai/dsh-desktop`'s `lib/main.js`:
+
+```js
+function claimDesktopSingleInstance(application, focusOwner) {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit();          // no dialog, no error, no window
+    return false;
+  }
+  application.on("second-instance", focusOwner);
+  return true;
+}
+```
+
+**A second launch is silently discarded while the first instance holds the lock.** Electron registers that
+lock against the *application*, not against a directory, which is why the two most natural remedies both
+fail:
+
+| What you try | Why it does nothing |
+|---|---|
+| **Disable third-party plugins before restarting** | The new process never reaches plugin loading — it quits at the lock |
+| **Reinstall the client (new folder, new exe)** | A new directory does not release a lock registered against the application |
+
+**Check the lock before touching anything else:**
+
+```powershell
+# Windows
+Get-Process -Name 'DeepSeek Harness' | Select-Object Id, StartTime
+```
+
+```bash
+# macOS / Linux
+pgrep -fl "DeepSeek Harness"
+```
+
+* **Processes listed** → it is the lock, and the app is not broken. **End them and start again.** On
+  Windows: `Stop-Process -Name 'DeepSeek Harness' -Force`. Do **not** delete `~/.dsh`.
+* **Nothing listed** → the failure really is before the lock, and *then* §3's procedure below applies.
+
+**A measured case, so the cost is on record.** A restart after upgrading to **v0.58.0** produced no
+process. Disabling third-party plugins and reinstalling the client both changed nothing; **deleting the
+entire `~/.dsh` directory fixed it** — not because anything in that directory was corrupt, but because
+**the deletion took down the process still holding the lock**, and the next launch then became the first
+instance. **Killing that process is the smaller, safer step, and it is the one to try first.**
+
+**What this cost, stated plainly:** the deleted directory carried session history and profile
+configuration that no longer exists. **`Stop-Process` would have cost nothing.**
+
 ---
 
 ## 4. A machine is listed but never answers

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.58.0",
+  "version": "0.60.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/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "0.58.0",
+  "version": "0.60.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

@@ -135,7 +135,7 @@ export function textOf(message) {
  * @param {{maxKeys?: number, maxDepth?: number}} [options]
  * @returns {string} a compact, content-free description
  */
-export function describeItems(message, { maxKeys = 24, maxDepth = 3 } = {}) {
+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';
 

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