@twinsearth/w2m-dsh-plugin 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -4,8 +4,141 @@ 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.5.5] — 2026-10-11
+
+### Fixed
+
+* **The v0.5.4 loader failure, with the cause the loader actually reported** rather than the hypothesis
+  that stood in for it:
+
+  ```
+  w2m (@twinsearth/w2m-dsh-plugin/tools): Error: cannot get property "connection" without inject
+    at registerTargetRoutes (src/plugin/fleet-target.mjs:483:25)
+  ```
+
+  cordis throws on reading a service property the fiber never declared, so the entry died and took all
+  eight tools with it. **Every existing test was blind to this**, because they drive the plugin with a
+  plain-object context where an undeclared read merely yields `undefined` — the fake was more forgiving
+  than the runtime. Fixed with `ctx.inject(['connection'], …)`, which is also the only shape that can
+  work: in the real composition the service is genuinely absent while `apply()` runs, and siblings are
+  mounted concurrently.
+* **The client half was never composed either, for a second and independent reason:** the bundle row
+  named the subpath `@twinsearth/w2m-dsh-plugin/tools` instead of the package, and a client package is
+  identified by its Loader row specifier — a subpath resolves to no `package.json`, so `dsh.client` was
+  never read and no boot-graph row was built. The row now names the package.
+* **A silent route rejection:** the control fetched `/w2m/target`, but fetch routes are validated
+  against `/api/`, and the refusal failed only a child fiber, so nothing surfaced. Now
+  `/api/w2m/target`, mirrored in the shipped bundle.
+
+### Added
+
+* **`test/loader-entry.test.mjs`** — the test that would have caught v0.5.4: it packs the tree, installs
+  the tarball with the installation's own `dsh plugin add` into a throwaway profile under a throwaway
+  `DSH_HOME`, and boots it with the real `runProfile` under the Harness runtime, asserting that the
+  entry activates, all eight tools are registered, the boot-graph row is composed from the shipped
+  bundle, and no failed entry names the package. **Proved in both directions**: 6/6 pass on the fixed
+  tree and 6/6 fail against the preserved v0.5.4 tarball, failing on precisely the loader error quoted
+  above. It skips loudly, naming the probes it tried, when no installation is found.
+* Cheap always-on guards in `test/client-bundle.test.mjs` that need no Harness: the platform field, the
+  client export, the row must be the bare package name, and the bundle's route must equal the host's.
+
+### Notes
+
+* **An upgrade from v0.5.4 requires one edit outside this package:** `cordis.patch.yml` in the profile
+  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 — silently reverting `rabbitUrl`,
+  `operatorToken`, `stateDir`, `projectDir`, `machineName`, `p2pMode` and `allowedCommands` to their
+  shipped defaults. Measured both ways with `--dump-config`.
+* **0.5.4 remains DO NOT INSTALL.** This release exists so that a rebuilt artifact is distinguishable
+  from the broken one by version alone.
+* 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
+> include:@twinsearth/w2m-dsh-plugin/tools reports iberPhase: failed, so **all eight tools
+> disappear** and the client half never registers. The package verifies in isolation
+> (scripts/verify-installed.mjs reports 8 tools registered) and its exports map is complete, so the
+> failure is in the real loader path -- the newly declared dsh.client half being composed there, with
+> lib/client.js being browser code that has no window under a host-side load. That cause is a
+> hypothesis, not a measurement; the loader's own error is still to be read. 0.5.5 fixes it and adds the
+> test that should have caught it: **load the packed artifact through the real loader path**, which is
+> the step this release skipped. The tag and the npm version stay as published history; they are simply
+> not installable.
+
+
 ### Added
 
 * **A dispatch-target control inside the chat composer.** A client half registers into

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/cordis.patch.yml

@@ -1,7 +1,30 @@
 # This file is the bundle patch declared by package.json's `dsh.bundle.patch`.
-# It mounts the plugin explicitly at `./tools` rather than relying on a
-# "root export is the plugin" convention, so reading this file tells you which
-# module of the package becomes the plugin.
+# It mounts the plugin by its package name, whose root export is the plugin
+# (`lib/index.js` re-exports `./tools.js`), so reading this file tells you which
+# package becomes the plugin.
+#
+# ---------------------------------------------------------------------------
+# Why the row names the package and not the `/tools` subpath (v0.5.4)
+# ---------------------------------------------------------------------------
+# Until v0.5.4 this row said `name: '@twinsearth/w2m-dsh-plugin/tools'`, and for a
+# host-only plugin that was fine. It stops being fine the moment the package also
+# ships a browser half, because the client module system identifies a package by
+# the *package specifier* its Loader row carries:
+#
+#   client-modules: resolveMeta(loaderName, baseUrl)   (dsh-client-modules)
+#     exactPackageSpecifier('@twinsearth/w2m-dsh-plugin/tools') -> undefined
+#     ... -> locatePkgJson returns undefined -> the entry is not a client package
+#
+# A subpath specifier resolves to no package manifest at all, so a `/tools` row is
+# invisible to the scan: `lib/client.js` is never composed into `__DSH_BOOT__`, and
+# the composer control can never register -- whatever else is fixed. Measured on the
+# 0.5.4 tarball through the real Loader: the composed boot graph held rows for
+# `@deepseek-ai/dsh-typert-registry` and `@deepseek-ai/dsh-api-gateway` and none for
+# this package. Naming the bare package fixes it, because the root export already
+# re-exports exactly what `/tools` exports (`test/tools.test.mjs` asserts the two
+# carry the same `inject`), so the host half is unchanged. `./tools` remains a
+# supported mount point for anyone who wants it -- it is simply not the one this
+# bundle uses.
 #
 # ---------------------------------------------------------------------------
 # Why this is an `insert:` list and not a bare `- id: w2m`
@@ -83,7 +106,7 @@
 # is visible rather than assumed.
 - insert:
     - id: w2m
-      name: '@twinsearth/w2m-dsh-plugin/tools'
+      name: '@twinsearth/w2m-dsh-plugin'
       config:
         rabbitUrl: ''
         operatorToken: ''

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:
  *
@@ -52,10 +70,12 @@ window.__ModuleLoader__.load({
     // Wire
     // -------------------------------------------------------------------------------------------
     //
-    // Mirrors TARGET_ROUTE_PATH in src/plugin/fleet-target.mjs. Plain same-origin `fetch` rather
-    // than a Remote method: the route is mounted inside the host's authentication fence, so the
-    // page's own cookie is the credential and there is no descriptor to keep in sync.
-    const ROUTE = '/w2m/target';
+    // Mirrors TARGET_ROUTE_PATH in src/plugin/fleet-target.mjs, `/api` prefix included: the host's
+    // Connection service mounts its exact-fetch-route registry under that channel and refuses any
+    // path that does not start with `/api/`. Plain same-origin `fetch` rather than a Remote method:
+    // the route is mounted inside the host's authentication fence, so the page's own cookie is the
+    // credential and there is no descriptor to keep in sync.
+    const ROUTE = '/api/w2m/target';
 
     /**
      * The locale namespace and its two dictionaries.
@@ -107,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);
@@ -122,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;
@@ -461,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
@@ -475,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
@@ -500,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/lib/index.js

@@ -3,22 +3,27 @@
  *
  * TWO READERS, ONE EXPORT LIST
  *
- * `cordis.patch.yml` names the `tools` subpath explicitly, and that stays true: mounting this
- * profile reads the patch, sees `@twinsearth/w2m-dsh-plugin/tools`, and loads `./tools.js`. Nothing
- * about the mounted plugin changes because of this file.
+ * `cordis.patch.yml` mounts this file: the profile reads the patch, sees
+ * `@twinsearth/w2m-dsh-plugin`, and loads `./index.js`. It names the *package* rather than the
+ * `tools` subpath on purpose, and the reason is measured rather than stylistic: the client module
+ * system (`@deepseek-ai/dsh-client-modules`) identifies a client package by the specifier its Loader
+ * row carries (`exactPackageSpecifier`), so a row naming `…/tools` resolves to no package.json at all
+ * — `dsh.client` is never read and the browser half is never composed into `__DSH_BOOT__`. The host
+ * would keep working and the composer control would silently never arrive; that is what v0.5.4
+ * shipped, and `test/loader-entry.test.mjs` now catches it through the real Loader.
  *
- * But the root entry is what everything else looks at. The DSH plugin listing requirements -- and
- * the marketplace checklists that copy them -- ask for a package that "exports an `apply(ctx)`
- * module", and a package that does not is one of the most common reasons a submission is refused.
- * This file used to be documentation only, so importing the package root yielded **no exports at
- * all** (`Object.keys() === []`): a plugin that works perfectly when mounted by its patch and looks
- * like an empty package to every tool that inspects it. That is a bad trade for one re-export line.
+ * `./tools.js` remains a supported mount point for anyone who wants it, and it is still what the
+ * DSH plugin listing requirements look at: the checklist asks for a package that "exports an
+ * `apply(ctx)` module", and this root is that module. It used to be documentation only, so importing
+ * the package root yielded **no exports at all** (`Object.keys() === []`): a plugin that works
+ * perfectly when mounted by its patch and looks like an empty package to every tool that inspects it.
+ * That is a bad trade for one re-export line.
  *
  * WHY NOT MOVE THE PLUGIN HERE
  *
  * Re-exporting is not relocating: `./tools.js` stays the single definition, so there is still
  * exactly one implementation of the plugin surface to keep in sync. Mounting *both* this entry and
- * the subpath would register the eight tools twice, which is why the patch keeps naming the subpath
- * instead of falling back to the "the root is the plugin" convention.
+ * the subpath would register the eight tools twice, which is why the patch mounts exactly one of
+ * them.
  */
 export { apply, inject, resetDefineToolCacheForTests } from './tools.js';

package/lib/tools.js

@@ -1,9 +1,15 @@
 /**
  * Package-facing plugin entry: `@twinsearth/w2m-dsh-plugin/tools`.
  *
- * This is the module named by `cordis.patch.yml`, so it is the seam between the
- * published package layout (`lib/`, what npm ships as the documented entry) and
- * the implementation (`src/`, where the code is actually readable).
+ * The documented subpath entry point, and the seam between the published package
+ * layout (`lib/`, what npm ships as the documented entry) and the implementation
+ * (`src/`, where the code is actually readable).
+ *
+ * `cordis.patch.yml` mounts the package *root* (`lib/index.js`), which re-exports
+ * this file, because the client module system only recognises a package whose
+ * Loader row carries the bare package specifier. Both paths land on the same
+ * `apply` and `inject` -- `test/tools.test.mjs` asserts that -- so this remains a
+ * supported mount point for a profile that prefers it.
  *
  * Nothing is re-implemented here on purpose: a second definition of the plugin
  * surface would be a second thing to keep in sync.

package/package.json

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