@twinsearth/w2m-dsh-plugin 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -54,6 +54,77 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 * Still unverified, and not claimed: how the control *renders*. No browser was opened. What is proven is
   the entire host side — the entry activates, the eight tools register, the boot-graph row is composed
   from the shipped bundle, the route is registered and attached — plus the seat shape in a VM test.
+## [0.5.6] — 2026-10-11
+
+### Fixed
+
+* **The client entry could not activate, and that made the whole application refuse to start.**
+  v0.5.4 and v0.5.5 were withdrawn for it. The real cause, taken from the page itself rather than
+  guessed:
+
+  ```
+  w2m-client-probe: apply threw for @twinsearth/w2m-dsh-plugin: cannot get property "locale" without inject
+  Error: web boot: 1 entry did not activate
+  ```
+
+  Cordis throws for any `ctx.<name>` a fiber reads without declaring it, and the client half declared
+  `inject = []`. **The first throw was `locale`, not `slots`** — so declaring the seat alone, or guarding
+  the locale alone, would each still have died. Now `inject = ['slots']` (a declared name is a *required*
+  dependency, which is why `locale` is deliberately not among them), the optional carrier is read
+  inject-free with `ctx.get('locale')` while its dictionary registration rides a child fiber, a context
+  with no usable seat becomes a **no-op with a diagnostic** instead of taking the page down, and `apply`
+  prints the inner message to the error-level renderer console — the channel the crash log reads — and
+  then rethrows, because a swallow would boot a healthy-looking page with no control.
+* **A failed entry was invisible unless you read fiber state.** `cordis-plugin-loader` no longer
+  propagates a failed mount to `await ctx.loader.await()`, and the loader driver inspected only the one
+  entry it knew about — so a failure landing on a **child** fiber (our silently-refused route) went
+  unseen. The driver now sweeps the whole registry and reports `failedFibers`.
+
+### Added
+
+* **A gate that would have caught all of it**: `test/loader-entry.test.mjs` packs the tree, installs the
+  tarball with the installation's own `dsh plugin add` into a throwaway profile under a throwaway
+  `DSH_HOME`, boots it with the real `runProfile`, activates the client entries through the real module
+  system, and — when a browser is present — boots the profile's own page and asserts our control renders.
+  Proven in both directions: **10/10 on this tree, 2 failures against the preserved pre-fix tarball, 9
+  against the v0.5.4 one**, and with a deliberately injected route defect it names the **child** fiber
+  while "entry active" and "eight tools" still pass. It reports one stage per line, so a failure names
+  its cause.
+* **`test/claims.test.mjs`** — 22 checks that our own published claims match the artifact, with the
+  registered tool set *measured* by importing the entry. It caught a stale claim in our README on its
+  **first run** (`README.md` said the installer asserts 5 tools; it asserts 8), and its author's own
+  mutation proof caught two false greens in its first draft — a scan that extracted zero tool names and
+  a lookahead that invented one out of a metric.
+* **`TROUBLESHOOTING.md`** — 17 symptom-indexed sections that name the culprit when it is not us (pnpm's
+  `minimumReleaseAge`, carrier-grade NAT, the OS firewall, an installer that rewrites the profile patch),
+  ending with a data-location table and a reason-code table.
+* **`SECURITY.md`** — a private reporting channel and **no public-issue route**, an honest support table,
+  and the consent model written out: what a paired machine may and may not do, and that we never write to
+  another machine's `authorized_keys`.
+* **`CONTRIBUTING.md`** — one page of falsifiable conventions, including **"a test that would pass
+  against a broken artifact is not evidence"** and **"run mutation proofs in a copy, never in the shared
+  tree"** (both learned the hard way).
+* **Opt-in LAN discovery** (`src/agent/mdns-wire.mjs`, `src/agent/mdns.mjs`, `src/plugin/mdns-discover.mjs`):
+  a bounded, hand-written DNS/mDNS codec with parse hardening (a pointer may only name a *prior* offset, so
+  termination is a property of the format; a 128-hop budget reported separately from a loop; label, name,
+  record and packet caps; every read bounds-checked) and a discovery source exposed through
+  `w2m_devices`' new `include_discovered` (default `false`). **Discovery is a hint, never an
+  authorisation**: a discovered device is refused as a dispatch target unless the relay already lists it
+  and it is online, and the positive control is tested so the rule cannot pass by refusing everything.
+
+### Notes
+
+* **v0.5.4 and v0.5.5 remain DO NOT INSTALL.** This release also exists so that `latest` on the registry,
+  which still pointed at v0.5.5, stops handing out a version that prevents the application from starting.
+* **Upgrading from v0.5.4 needs one edit outside this package**: the profile's `cordis.patch.yml` must
+  name the package (`@twinsearth/w2m-dsh-plugin`), not the `/tools` subpath. With the corrected bundle row
+  a mismatch makes the loader skip the whole patch and silently revert every configured value to its
+  default. The claims gate now checks this.
+* **LAN discovery is unverified on a real network.** Every socket in its suite is loopback and no packet
+  left the host, so it says nothing about whether a switch forwards `224.0.0.251` or how a real
+  Bonjour/Avahi peer answers. There is **no third-party interoperability test**, no probing or conflict
+  resolution, IPv4 only, and the responder is **built and tested but not started** by the plugin —
+  loading a plugin should not silently multicast on the host's network.
 ## [0.5.4] — 2026-10-11
 
 > **DO NOT INSTALL 0.5.4.** It fails to load in the Harness: the loader entry

package/README.md

@@ -535,7 +535,7 @@ the plugin:
 
 ```bash
 node scripts/check-entrypoints.mjs   # imports lib/tools.js, the exact specifier cordis.patch.yml mounts
-node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 5 tools
+node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 8 tools
 ```
 
 **Not verified:**
@@ -588,6 +588,8 @@ Issues and pull requests are welcome. If you change observable behaviour, update
 `PROTOCOL.md` in the same commit — that file is the contract three components
 agree on.
 
+When something does not work, start from the symptom: [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
 ## License
 
 [MIT](LICENSE)

package/lib/client.js

@@ -8,7 +8,25 @@
  * web shell's loader consumes (`window.__ModuleLoader__.load({ id, factory })`, a lazy CJS table
  * whose factory runs at materialization). `package.json` declares it with
  * `dsh.client: { platform: 'web' }` and `exports['./client'] = './lib/client.js'`, which is what the
- * host scans for; `src/client/w2m-target.mjs` is the same code laid out for a human reader.
+ * host scans for. There is no second copy to keep in sync: this file **is** the source, and
+ * `test/client-bundle.test.mjs` is where its entry shape is read.
+ *
+ * # A failed client entry is fatal, and silence is not a neutral failure
+ *
+ * Measured twice in production: when this entry's `apply` throws, the page does not degrade — the
+ * shell audits every entry after activation and refuses to boot with
+ * `web boot: 1 entry did not activate / @twinsearth/w2m-dsh-plugin: failed`, which in the desktop
+ * app is forwarded to the main process and written as a `web-boot` crash: **the app does not start**.
+ * The audit prints the entry's *name* and its fiber state and nothing else, so the cause has to be
+ * carried by the failing code itself; {@link apply} therefore reports its own error to
+ * `console.error`, which is the error-level renderer console the crash log already captures.
+ *
+ * The failure that cost those two outages was a single property read. Cordis resolves `ctx.<name>`
+ * through the fiber's `inject` list: a service the fiber never declared **throws**
+ * (`cannot get property "locale" without inject`) whether or not some plugin provides it, and every
+ * name that *is* declared becomes a required dependency the entry waits for. Both halves of that rule
+ * are load-bearing here — see {@link inject} for what this bundle declares, and how the optional
+ * locale carrier is read instead.
  *
  * Two consequences, both deliberate:
  *
@@ -109,12 +127,18 @@ window.__ModuleLoader__.load({
      * `{name}` substitution is deliberately the only templating: these strings have one variable
      * each, and a message format would be a dependency this package does not have.
      *
-     * @param ctx - the client plugin context.
+     * @param localeOf - the shell's locale service, or a function returning it (read at lookup time).
+     *   Passed in rather than read from `ctx` here: the service is optional, and reading an optional
+     *   service off the context is the one operation in this file that can kill the page (see
+     *   {@link readOptionalService}). A function is accepted because the service may arrive *after*
+     *   this entry activates — the shell's `bind()` is live, so a deferred read still localises.
      * @returns {(key: string, values?: object) => string}
      */
-    function makeTranslator(ctx) {
-      const bound = typeof ctx?.locale?.bind === 'function' ? ctx.locale.bind(NS) : null;
+    function makeTranslator(localeOf) {
+      const resolveLocale = () => (typeof localeOf === 'function' ? localeOf() : localeOf);
       return (key, values) => {
+        const locale = resolveLocale();
+        const bound = typeof locale?.bind === 'function' ? locale.bind(NS) : null;
         const template = bound === null
           ? (DICT.zh[key] ?? DICT.en[key] ?? key)
           : bound(key, values);
@@ -124,6 +148,50 @@ window.__ModuleLoader__.load({
       };
     }
 
+    /**
+     * Read a service the composition may or may not provide, without the inject requirement.
+     *
+     * `ctx.get(name)` is Cordis's inject-free lookup, and it is the only correct way to read an
+     * *optional* service from a plugin: `ctx[name]` throws for anything the fiber did not declare as
+     * a dependency, and declaring it would make the service *required* — an entry whose declared
+     * dependency never arrives never activates either, which is fatal in exactly the same way. So a
+     * carrier that must not be able to block the control (`locale`) is read here, and a service the
+     * control cannot work without (`slots`) is declared in {@link inject}.
+     *
+     * @param ctx - the client plugin context.
+     * @param name - the service name.
+     * @returns the service, or undefined when the composition has none (or this is not a Cordis
+     *   context at all, which is how `test/client-bundle.test.mjs` applies this bundle).
+     */
+    function readOptionalService(ctx, name) {
+      return typeof ctx?.get === 'function' ? ctx.get(name) : undefined;
+    }
+
+    /**
+     * Register {@link DICT} with the shell's locale service whenever that service exists.
+     *
+     * Two paths, one outcome. When the service is already up, the registration is an effect of this
+     * entry and goes away with it. When it is not up yet, the registration rides a **child fiber**
+     * (`ctx.inject`) that waits for `locale` without holding this entry back: declaring `locale` in
+     * {@link inject} instead would make it required, and a composition without a locale service
+     * would then report this entry as `pending` — which the shell's audit treats exactly like
+     * `failed`, i.e. the page does not boot. A missing localisation service must never cost an
+     * operator the control, and must never cost them the app.
+     *
+     * @param ctx - the client plugin context.
+     * @param locale - the shell's locale service, or undefined when the composition has none.
+     */
+    function registerDictionaries(ctx, locale) {
+      if (typeof locale?.register === 'function') {
+        ctx.effect(() => locale.register(NS, DICT), 'w2m: composer target control dictionaries');
+        return;
+      }
+      if (typeof ctx?.inject !== 'function') return;
+      ctx.inject(['locale'], (localeCtx) => {
+        localeCtx.effect(() => localeCtx.locale.register(NS, DICT), 'w2m: composer target control dictionaries');
+      });
+    }
+
     /** One JSON call to the host half, folded into a value: a refusal is never an exception here. */
     async function callHost(options) {
       let response;
@@ -463,7 +531,33 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Client plugin body.
+     * Client plugin body: install the stylesheet, register the dictionaries, take the seat.
+     *
+     * @param ctx - the client root context.
+     */
+    function apply(ctx) {
+      try {
+        mount(ctx);
+      } catch (error) {
+        // The audit that decides whether the app boots reports the entry's name and the word
+        // "failed" and nothing else, so this is where the cause has to be said out loud. The
+        // renderer console at error level is the channel the desktop crash log already carries
+        // (`--- renderer console (error level, oldest first) ---`), which makes this the one place a
+        // browser half can put its own diagnosis next to the failure it caused.
+        console.error(
+          '@twinsearth/w2m-dsh-plugin: the client entry failed to activate, so this page will not boot: ' +
+            `${error instanceof Error ? error.message : String(error)}`,
+          error,
+        );
+        // Deliberately rethrown. A swallowed failure would boot a page that looks healthy with no
+        // target control in it — the silent-half-arrival failure this package has already shipped
+        // once (v0.5.4) and refuses to ship again.
+        throw error;
+      }
+    }
+
+    /**
+     * The body of {@link apply}, wrapped so no failure can escape without a diagnostic.
      *
      * `slots.inject` (not a bare `register`) is what the slot's declaration requires of an entry
      * from a package that does not own the seat: the parent declared `conversation.input.left`, and
@@ -477,17 +571,30 @@ window.__ModuleLoader__.load({
      *
      * @param ctx - the client root context.
      */
-    function apply(ctx) {
+    function mount(ctx) {
+      // `ctx.slots` is legal to read because {@link inject} declares it — and declaring it is also
+      // what makes this entry wait for the seat instead of racing it. The shape check is for callers
+      // that are not a Cordis fiber at all (`test/client-bundle.test.mjs`): a missing or foreign
+      // registry is a control that cannot be mounted, and a control that cannot be mounted must not
+      // be allowed to take the whole page down with it.
+      const slots = ctx?.slots;
+      if (typeof slots?.inject !== 'function' || typeof slots?.register !== 'function') {
+        console.error(
+          '@twinsearth/w2m-dsh-plugin: the client half found no slot registry on this context, so the ' +
+            'dispatch-target control is not mounted; the rest of the page is unaffected',
+        );
+        return;
+      }
       const styleDisposer = injectStyle(typeof document === 'undefined' ? null : document);
       if (styleDisposer !== null && typeof ctx.effect === 'function') {
         ctx.effect(() => styleDisposer, 'w2m: composer target control styles');
       }
-      // Dictionaries first: a namespace registered after the UI has mounted is still picked up.
-      if (typeof ctx.locale?.register === 'function') {
-        ctx.effect(() => ctx.locale.register(NS, DICT), 'w2m: composer target control dictionaries');
-      }
-      const t = makeTranslator(ctx);
-      ctx.slots.inject('conversation.input.left', () => ctx.slots.register({
+      // Dictionaries as early as the composition allows: a namespace registered after the UI has
+      // mounted is still picked up, and the service is optional, so nothing here may block.
+      const locale = readOptionalService(ctx, 'locale');
+      registerDictionaries(ctx, locale);
+      const t = makeTranslator(() => readOptionalService(ctx, 'locale'));
+      slots.inject('conversation.input.left', () => slots.register({
         name: 'conversation.input.left',
         id: 'w2m-target',
         // After the shipped permission control and the plan control, which sit earlier in the
@@ -502,8 +609,26 @@ window.__ModuleLoader__.load({
       }, TargetSelect));
     }
 
-    /** Cordis services this entry needs; `ctx.slots` is read directly, as every client plugin does. */
-    const inject = [];
+    /**
+     * Cordis services this entry depends on, read by the fiber that mounts this bundle.
+     *
+     * `slots` is the seat: the control is registered into `conversation.input.left` through the
+     * slot registry, and a fiber that cannot see `slots` has nowhere to register. Declaring it is
+     * not bookkeeping. Cordis resolves `ctx.<name>` against this list, so reading an undeclared
+     * service **throws** (`cannot get property "slots" without inject`) even when the service is
+     * provided — measured in production: this bundle shipped with `inject = []` while reading
+     * `ctx.locale` and `ctx.slots`, the first read threw, and the app refused to boot.
+     *
+     * `locale` is deliberately absent, and that is the other half of the same rule: **every**
+     * declared name is a required dependency, so an entry that declares a service the composition
+     * does not provide never reaches `active` either — the audit then reports it as
+     * `pending (waiting for service: locale)`, which is just as fatal. Optional carriers are read
+     * with {@link readOptionalService} instead, and waited for by a child fiber when waiting is
+     * useful ({@link registerDictionaries}). Keep those two decisions in step with the reads in
+     * {@link mount}: `test/client-bundle.test.mjs` mounts this bundle behind a context that throws
+     * on any undeclared service read, exactly as Cordis does.
+     */
+    const inject = ['slots'];
 
     exports.apply = apply;
     exports.inject = inject;

package/package.json

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