@twinsearth/w2m-dsh-plugin 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -2,7 +2,89 @@
 
 All notable changes to this project are documented here.
 
-## [1.0.7] — 2026-10-17
+## [1.0.9] — 2026-10-17
+
+**Discovery: a machine can now ask the relay which blob its fleet published last, instead of a human relaying a
+64-character hash between machines.**
+
+### Why the channel needed this before it was usable
+
+v1.0.7/1.0.8 gave the fleet a content-addressed channel -- anyone in the fleet can `pull <hash>`. **But a hash is
+only useful to someone who already has it**, and the only place one appeared was `publish`'s output on the machine
+that ran it. That makes the channel work exactly as well as a person copying a string, which is a demo, not a sync.
+
+So the relay keeps **one pointer per fleet**: the blob that fleet published most recently.
+
+| Piece | Where |
+|---|---|
+| pointer store | `<state>/blobs/latest.json`, shape `{ "<fleet_id>": { hash, bytes, published_at_ms, published_by } }` |
+| advanced by | `putBlob`, together with the ownership record -- a publish that succeeded but did not advance the pointer would leave the fleet advertising a stale document |
+| route | `GET /v1/fleet/blobs/latest`, scoped through the same `scopeBlobFleet` as the blobs themselves |
+| tool | `w2m_memory {"action":"latest"}`, and `{"action":"pull","hash":"latest"}` |
+
+**`hash: "latest"` is the ergonomic point**: a joining machine runs one call, and it is the form that survives a
+teammate republishing. A stored hash goes stale; `latest` follows.
+
+**Resolving a pointer does not weaken verification.** The re-hash in `pull` is unchanged, because a pointer is
+metadata -- exactly the thing a relay is allowed to be wrong about -- while the hash is what the bytes must match.
+
+### A pointer is a hint, not a guarantee
+
+Eviction is oldest-first and can take the current document on a busy fleet. So `latest` may name a blob that no
+longer exists, and a pull of it answers `404`. **That is the honest outcome**: keeping a document alive because it
+is pointed at would make eviction depend on a second, unstated rule. The route says so in its own payload.
+
+### The defect a test caught, recorded because it is easy to reintroduce
+
+The first version of `advanceFleetLatest` skipped `fleetId === null`, reasoning that a fleetless device has no
+fleet to advertise to. **That skipped the most common deployment.** On a relay with no fleet configured,
+`scopeFleetId` returns `{fleetId: null, legacy: true}` -- and `null` there means **one shared scope**, the
+pre-v0.7.7 behaviour that fleet scoping's own comment insists a migration must not change. The pointer was therefore
+never written on an unclaimed relay, and `latest` answered `404` for every machine on the default single-relay
+setup. **The feature worked nowhere it was most likely to be used**, and the test that asserted 200 is the only
+reason this is a comment in the source rather than a bug report.
+
+The genuinely fleetless case on a **claimed** relay never reaches that code: `scopeFleetId` refuses it outright, so
+the blob is rejected before a pointer could exist.
+
+### Verified
+
+Four new tests in `test/relay.test.mjs` run against a real relay: the pointer advances on publish and follows the
+newest one; it is scoped per fleet (B sees `404` while A sees its own); **the pointer survives eviction while the
+pull does not** -- the pointer still names the removed blob, the payload says "hint, not a guarantee", and the read
+answers `404` without resurrecting it; and a second fleet re-publishing identical bytes **cannot claim the pointer**.
+
+Full suite **2360 tests, 2346 pass, 0 fail, 14 skip**. Pre-flight **GREEN, 15 of 15 checks**.
+
+### NOT verified
+
+The `latest` and `pull latest` tool actions **end to end** -- same gap as v1.0.7's publish/pull: they are
+type-correct and lint-clean, but no test executes them, because that needs a profile with a `fleet-memory.md` and a
+live relay.
+
+### And still absent
+
+Merge (#2). Two machines publishing produce two blobs, and the pointer names whichever published last -- **the
+earlier document is not lost, it is merely no longer `latest`**. That visibility is the input merge needs, and
+nothing yet says who wins when two machines assert different facts.
+
+## [1.0.8] — 2026-10-17
+
+**The fleet sync channel, both directions: a machine can publish its collective memory to the relay and another
+machine in the same fleet can fetch it back by hash.**
+
+> **Why 1.0.7 and 1.0.8 are both published, and what that records.** `pnpm publish 1.0.7` succeeded; a verification
+> read a minute later answered `version not found: 1.0.7`, a retry answered
+> `409 Cannot publish over previously staged version "1.0.7"`, and `npm stage list` reported nothing -- so 1.0.7 was
+> concluded to have failed and 1.0.8 was cut. **The registry was simply lagging: both versions are published, and
+> their contents are identical apart from the version string.** The 409 was the retry racing a publish that was
+> still in flight, not evidence that nothing had been accepted.
+>
+> **The mistake worth keeping is the conclusion, not the retry.** A freshness read that disagrees with a successful
+> write is evidence of lag, not of failure -- and the way to tell them apart is to wait and re-read, which is
+> cheaper than re-cutting a release. 1.0.8 stands as the current version because it is already published and is the
+> one `latest` names; 1.0.7 is deprecated pointing here rather than left to look like a distinct release.
+
 
 **The fleet sync channel, both directions: a machine can publish its collective memory to the relay and another
 machine in the same fleet can fetch it back by hash.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "main": "lib/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

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 = '1.0.7';
+const PLUGIN_VERSION = '1.0.9';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -5141,12 +5141,13 @@ export async function apply(ctx, config = {}) {
        */
       action: {
         type: 'string',
-        enum: ['read', 'publish', 'pull'],
+        enum: ['read', 'publish', 'pull', 'latest'],
         description:
           'read (default) = answer from memory. publish = upload the curated collective memory '
-          + '(`fleet-memory.md`) to the relay as a content-addressed blob and return its SHA-256. pull = fetch one '
-          + 'blob by its SHA-256 and return its text, re-hashing what came back against the name it was asked for. '
-          + 'Neither publish nor pull modifies the local file.',
+          + '(`fleet-memory.md`) to the relay as a content-addressed blob and return its SHA-256. latest = ask the '
+          + 'relay which blob this fleet published last (the discovery half of the channel). pull = fetch one blob '
+          + 'by SHA-256 -- or by "latest" -- and return its text, re-hashing what came back against the name it was '
+          + 'asked for. None of these modifies the local file.',
         default: 'read',
       },
       hash: {
@@ -5332,17 +5333,88 @@ export async function apply(ctx, config = {}) {
        * content is re-hashed here, and a mismatch is a failure rather than a warning -- accepting unverified bytes
        * under a name they do not match would make every later reader's check decorative too.
        */
+      /**
+       * v1.0.9: which blob this fleet published last -- **the discovery half of the channel**.
+       *
+       * Without it the channel only works if a human reads a 64-character hash off one machine and types it into
+       * another, which is a demo rather than a sync.
+       */
+      if (typeof args?.action === 'string' && args.action === 'latest') {
+        const base = requireRabbit(cfg);
+        const token = await resolveToken(cfg);
+        const pointer = await request({
+          rabbitUrl: base,
+          token,
+          pathname: '/v1/fleet/blobs/latest',
+          signal: exec?.signal,
+        });
+        if (pointer.status === 404) {
+          throw new W2MError(
+            'W2M_NOT_FOUND',
+            'W2M_NOT_FOUND: this fleet has published no blob yet',
+            { hint: 'run `action: "publish"` on a machine in this fleet first' },
+          );
+        }
+        if (pointer.status !== 200) {
+          throw new W2MError(
+            'W2M_RABBIT_REFUSED',
+            `W2M_RABBIT_REFUSED: GET /v1/fleet/blobs/latest answered HTTP ${pointer.status}`,
+            { http_status: pointer.status, detail: pointer.error ?? null },
+          );
+        }
+        return JSON.stringify({
+          ok: true,
+          hash: pointer.json?.hash ?? null,
+          bytes: pointer.json?.bytes ?? null,
+          published_at: pointer.json?.published_at ?? null,
+          published_by: pointer.json?.published_by ?? null,
+          next: 'w2m_memory {"action":"pull","hash":"latest"} fetches it and verifies it against this hash',
+        });
+      }
+
       if (typeof args?.action === 'string' && args.action === 'pull') {
-        const wanted = typeof args?.hash === 'string' ? args.hash.trim().toLowerCase() : '';
+        let wanted = typeof args?.hash === 'string' ? args.hash.trim().toLowerCase() : '';
+        const base = requireRabbit(cfg);
+        const token = await resolveToken(cfg);
+        /**
+         * `"latest"` resolves the fleet pointer first.
+         *
+         * **The pointer is trusted only to name a hash; the bytes are still verified against that hash.** Resolving
+         * must not weaken the re-hash below, or the pointer becomes the thing trusted instead of the content -- and
+         * a pointer is metadata, which is exactly what a relay is allowed to be wrong about.
+         */
+        let viaLatest = false;
+        if (wanted === 'latest') {
+          viaLatest = true;
+          const pointer = await request({
+            rabbitUrl: base,
+            token,
+            pathname: '/v1/fleet/blobs/latest',
+            signal: exec?.signal,
+          });
+          if (pointer.status === 404) {
+            throw new W2MError(
+              'W2M_NOT_FOUND',
+              'W2M_NOT_FOUND: this fleet has published no blob to follow',
+              { hint: 'publish from a machine in this fleet first, or pass an explicit hash' },
+            );
+          }
+          if (pointer.status !== 200) {
+            throw new W2MError(
+              'W2M_RABBIT_REFUSED',
+              `W2M_RABBIT_REFUSED: GET /v1/fleet/blobs/latest answered HTTP ${pointer.status}`,
+              { http_status: pointer.status, detail: pointer.error ?? null },
+            );
+          }
+          wanted = String(pointer.json?.hash ?? '');
+        }
         if (!/^[0-9a-f]{64}$/.test(wanted)) {
           throw new W2MError(
             'W2M_CONFIG',
-            'W2M_CONFIG: `action: "pull"` needs `hash`, a SHA-256 of 64 lowercase hex characters',
-            { hint: 'the hash is what `action: "publish"` returned for the document you want' },
+            'W2M_CONFIG: `action: "pull"` needs `hash` -- 64 lowercase hex characters, or the word "latest"',
+            { hint: 'the hash is what `action: "publish"` returned, and "latest" follows this fleet\'s own pointer' },
           );
         }
-        const base = requireRabbit(cfg);
-        const token = await resolveToken(cfg);
         const result = await request({
           rabbitUrl: base,
           token,
@@ -5385,6 +5457,7 @@ export async function apply(ctx, config = {}) {
           ok: true,
           pulled: true,
           hash: wanted,
+          via_latest: viaLatest,
           bytes: Buffer.byteLength(body, 'utf8'),
           verified: true,
           content: body,

package/src/relay/persistence.mjs

@@ -39,6 +39,28 @@ export const MAX_BLOBS = 256;
  */
 export const BLOB_INDEX_FILE = 'index.json';
 
+/**
+ * v1.0.9: **which blob is each fleet's current document** -- the discovery half of the channel.
+ *
+ * ## Why a hash alone is not enough
+ *
+ * v1.0.7/1.0.8 gave the fleet a content-addressed channel: anyone in the fleet can `pull <hash>`. **A hash is only
+ * useful to someone who already has it**, and the only way to get one was to read `publish`'s output on another
+ * machine. That makes the channel work exactly as well as a human relaying a 64-character string.
+ *
+ * So the relay keeps one pointer per fleet: four fields of metadata it was already entitled to hold, because it
+ * already holds `fleet_id` for every blob.
+ *
+ * ## A pointer is a hint, not a guarantee
+ *
+ * Eviction is oldest-first and can take the current document on a busy fleet. `latest` may therefore name a blob
+ * that no longer exists, and a pull of it answers `404`. **That is the honest outcome**: keeping a document alive
+ * because it is pointed at would make eviction depend on a second, unstated rule.
+ *
+ * Shape: `{ "<fleet_id>": { hash, bytes, published_at_ms, published_by } }`.
+ */
+export const BLOB_LATEST_FILE = 'latest.json';
+
 /** Ledger entry types understood by `RabbitState#restore`. */
 export const LEDGER_TYPES = Object.freeze([
   'task.created',
@@ -335,6 +357,12 @@ export class Persistence {
       if (entry === undefined) {
         index[hash] = { fleet_id: fleetId, added_at_ms: this._now() };
         this.writeBlobIndex(index);
+        this.advanceFleetLatest(fleetId, hash, bytes.length, options.publishedBy);
+      } else if (entry.fleet_id === fleetId) {
+        // Re-publishing the same bytes is a statement that this is the current document, so the pointer advances
+        // even though the path did not change. Only for the **owner**: pointing another fleet's pointer at a blob it
+        // cannot read would advertise a document that answers 404 to the very fleet being told about it.
+        this.advanceFleetLatest(fleetId, hash, bytes.length, options.publishedBy);
       }
       return { ok: true, hash, bytes: bytes.length, evicted: [] };
     }
@@ -352,6 +380,7 @@ export class Persistence {
     }
     index[hash] = { fleet_id: fleetId, added_at_ms: this._now() };
     this.writeBlobIndex(index);
+    this.advanceFleetLatest(fleetId, hash, bytes.length, options.publishedBy);
     return { ok: true, hash, bytes: bytes.length, evicted };
   }
 
@@ -486,6 +515,81 @@ export class Persistence {
     }
   }
 
+  /** Read the fleet -> latest-blob pointer map. Missing or corrupt reads as empty, never throws. */
+  readBlobLatest() {
+    if (!this.enabled) return {};
+    try {
+      const raw = fs.readFileSync(path.join(this.dir, BLOB_DIR, BLOB_LATEST_FILE), 'utf8');
+      const parsed = JSON.parse(raw);
+      return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+
+  /** Atomically replace the pointer map. Best-effort, like the ownership index. */
+  writeBlobLatest(latest) {
+    if (!this.enabled) return false;
+    const file = path.join(this.dir, BLOB_DIR, BLOB_LATEST_FILE);
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const tmp = `${file}.tmp-${process.pid}-${this._now()}`;
+      fs.writeFileSync(tmp, `${JSON.stringify(latest)}\n`, 'utf8');
+      fs.renameSync(tmp, file);
+      return true;
+    } catch (error) {
+      this.warn(BLOB_DIR, `blob latest-pointer write failed: ${error?.message ?? String(error)}`);
+      return false;
+    }
+  }
+
+  /**
+   * Point a fleet at the blob it just published.
+   *
+   * ## `null` is a real scope, not a missing value
+   *
+   * The first version of this method skipped `fleetId === null`, reasoning that a fleetless device has no fleet to
+   * advertise to. **That was wrong for the most common deployment.** On a relay with no fleet configured,
+   * `scopeFleetId` returns `{fleetId: null, legacy: true}` -- and `null` there means **one shared scope**, which
+   * is exactly the pre-v0.7.7 behaviour that fleet scoping's own comment insists a migration must not change:
+   * *"a migration must not change behaviour for devices that were never asked to change."*
+   *
+   * Skipping it meant the pointer was never written on an unclaimed relay, so `latest` answered 404 for every
+   * machine on the default single-relay setup -- the feature worked nowhere it was most likely to be used. A test
+   * caught it, which is the only reason this is a comment instead of a bug report.
+   *
+   * The genuinely fleetless case on a **claimed** relay never reaches here: `scopeFleetId` refuses it outright
+   * (`REQUESTER_HAS_NO_FLEET`), so the blob is rejected before any pointer could be written.
+   *
+   * @param {string|null} fleetId `null` means the relay-wide legacy scope
+   * @param {string} hash
+   * @param {number} bytes
+   * @param {string|null} [publishedBy]
+   */
+  advanceFleetLatest(fleetId, hash, bytes, publishedBy = null) {
+    if (!this.enabled || fleetId === undefined) return false;
+    const latest = this.readBlobLatest();
+    latest[fleetId] = {
+      hash,
+      bytes,
+      published_at_ms: this._now(),
+      published_by: typeof publishedBy === 'string' && publishedBy !== '' ? publishedBy : null,
+    };
+    return this.writeBlobLatest(latest);
+  }
+
+  /**
+   * The blob `fleetId` last published, or `null`.
+   *
+   * **A returned pointer is a hint.** It may name a blob that eviction has since removed, and the caller is expected
+   * to read it and answer not-found rather than being told a comfortable lie here.
+   */
+  fleetLatest(fleetId) {
+    if (!this.enabled || fleetId === undefined) return null;
+    const entry = this.readBlobLatest()[fleetId];
+    return entry !== undefined && typeof entry.hash === 'string' ? entry : null;
+  }
+
   /** `<state>/blobs/<aa>/<sha256>`, or `null` when persistence is off or the hash is not a sha256. */
   blobFile(hash) {
     if (!this.enabled) return null;

package/src/relay/server.mjs

@@ -787,6 +787,32 @@ export class RelayServer {
      * fleet is **not readable by another**, and the read refusal is a 404 rather than a 403: a distinguishable
      * "not yours" tells a prober that the hash exists here.
      */
+    /**
+     * v1.0.9: **which blob this fleet published last** -- the discovery half of the channel.
+     *
+     * Checked **before** the `<sha256>` matcher deliberately. The matcher only accepts 64 hex characters, so
+     * `latest` cannot collide with it today; **the ordering is asserted anyway**, because "these two patterns cannot
+     * conflict" is exactly the reasoning that produces a shadowed route the day one of them is relaxed.
+     *
+     * A fleet that has never published gets a 404 rather than an empty object: "there is no current document" and
+     * "the current document is nothing" are different statements, and only one of them is true here.
+     */
+    if (method === 'GET' && path === '/v1/fleet/blobs/latest') {
+      const latest = this.state.latestFleetBlob(device);
+      if (latest === null) {
+        throw new ProtocolError('NOT_FOUND', 'this fleet has published no blob', {});
+      }
+      return sendJson(res, 200, {
+        protocol_version: PROTOCOL_VERSION,
+        hash: latest.hash,
+        bytes: latest.bytes,
+        published_at: new Date(latest.published_at_ms).toISOString(),
+        published_by: latest.published_by ?? null,
+        // Stated in the payload, not only in the docs: a pointer can outlive its blob under oldest-first eviction.
+        hint: 'a hint, not a guarantee -- a pull may answer 404 if the blob has since been evicted',
+      });
+    }
+
     const blobMatch = /^\/v1\/fleet\/blobs\/([0-9a-f]{64})$/.exec(path);
     if (blobMatch !== null) {
       const hash = blobMatch[1];

package/src/relay/state.mjs

@@ -579,6 +579,22 @@ export class RabbitState {
     return this._persist.getBlob(hash, { fleetId: scope.fleetId });
   }
 
+  /**
+   * Which blob this device's fleet published most recently, or `null`.
+   *
+   * **This is the discovery half of the channel** (v1.0.9): without it a hash is only useful to whoever read
+   * `publish`'s output, so a "sync" would need a human relaying a 64-character string between machines.
+   *
+   * Scoped by the same rule as the blobs themselves -- a fleetless device on a claimed relay gets `null`, not a
+   * shared pointer it could never read.
+   */
+  latestFleetBlob(device) {
+    if (!this._persist) return null;
+    const scope = this.scopeBlobFleet(device);
+    if (scope.ok !== true) return null;
+    return this._persist.fleetLatest(scope.fleetId);
+  }
+
   /** Snapshot the device table; failures must never break the request path. */
   _saveDevices() {
     if (this._restoring || !this._persist) return false;