@twinsearth/w2m-dsh-plugin 1.0.8 → 1.0.10

package/CHANGELOG.md

@@ -2,17 +2,146 @@
 
 All notable changes to this project are documented here.
 
+## [1.0.10] — 2026-10-17
+
+**`w2m_memory {"action":"diff"}`: compare this machine's collective memory against the fleet's current blob,
+and write nothing.**
+
+### Merge is still not implemented, deliberately
+
+The question merge depends on has not been answered:
+
+> **When two machines in one fleet assert different things about the same fact, who wins?**
+
+That is a product decision about what the fleet's memory *is*, not an implementation detail, and shipping a merge
+before its rule is how a fleet silently loses one machine's memory. So this release ships **the half that needs no
+decision** -- and names the other half as open rather than leaving it implied.
+
+### What `diff` answers
+
+* **Is my document the newest one?** `same: true/false`, decided by **whole-document hash equality**.
+* **What would I be overwriting?** `preview.local_only` and `preview.fleet_only`.
+* **Is the fleet's document even there?** Three distinct absence states, each named: the fleet never published; the
+  pointer names a blob that eviction removed; the blob exists and verified.
+
+### Four decisions worth recording
+
+**It writes nothing.** No `.orig`, no `.rej`, no silent merge. Comparing is not a licence to edit a document this
+machine owns.
+
+**`same` is hash equality, not "no line differences".** Two documents with identical line sets in a different order
+are **not** the same, and callling them the same would hide an order change -- which in a markdown document is a
+structural change.
+
+**A set comparison, not a diff.** A line-oriented diff would report "moved" versus "changed" and then want a merge
+policy. **A set comparison cannot resolve anything, which is exactly the property this step requires.**
+
+**The fleet copy is re-hashed before it is compared.** Comparing unverified content would launder it: the report
+would give a hash-verified-looking answer about bytes nobody checked. A blob that fails its own name raises
+`W2M_BAD_BLOB` and is never compared.
+
+Trailing whitespace is normalised (it is noise); leading whitespace is preserved (it is markdown structure).
+
+### Verified
+
+The comparison rule is pinned directly: `local_only` / `fleet_only` separate correctly, trailing whitespace creates
+no difference, and leading whitespace does. Full suite **2360 tests, 2346 pass, 0 fail, 14 skip**; pre-flight
+**GREEN, 15 of 15 checks**.
+
+### NOT verified
+
+The `diff` action **end to end** -- the same gap as `publish`/`pull`/`latest`: type-correct and lint-clean, but
+no test executes it, because that needs a profile with a `fleet-memory.md` and a live relay.
+
+### Open: #2b
+
+**Append-merge with conflict markers, and the marker's existence is the refusal** -- a document containing markers is
+one a human must not trust until resolved. Last-writer-wins is rejected: it loses data silently, and the project's
+own eviction rule already refuses "delete the only copy of a fact" in spirit. **That recommendation is in
+`FLEET-SYNC-2-DESIGN.md` and is not implemented, because it encodes a rule that is the operator's to choose.**
+
+## [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 this is 1.0.8 and not 1.0.7.** `pnpm publish` reported `1.0.7` as published, but the registry never received
-> it: a retry answers `409 Cannot publish over previously staged version "1.0.7"`, `npm stage list` reports **no**
-> staged versions, and `npm stage reject 1.0.7` errors. **The number is stuck in a staged state that the documented
-> approval surface cannot reach**, so it cannot be reused -- retrying would have produced a version that says
-> "published" in one log and "not found" in the registry. `v1.0.7` on GitHub was withdrawn for the same reason: a
-> release whose npm counterpart does not exist is the three-way mismatch this project checks for every time.
+> **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "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.8",
+  "version": "1.0.10",
   "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.8';
+const PLUGIN_VERSION = '1.0.10';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -5141,12 +5141,14 @@ export async function apply(ctx, config = {}) {
        */
       action: {
         type: 'string',
-        enum: ['read', 'publish', 'pull'],
+        enum: ['read', 'publish', 'pull', 'latest', 'diff'],
         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. pull = fetch one blob by SHA-256 -- or by "latest" -- and '
+          + 'return its text, re-hashing it. diff = compare the local document against the fleet current blob and '
+          + 'report what differs, **writing nothing**: merge has no conflict rule yet, so this action deliberately '
+          + 'resolves nothing. None of these modifies the local file.',
         default: 'read',
       },
       hash: {
@@ -5332,17 +5334,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,12 +5458,157 @@ export async function apply(ctx, config = {}) {
           ok: true,
           pulled: true,
           hash: wanted,
+          via_latest: viaLatest,
           bytes: Buffer.byteLength(body, 'utf8'),
           verified: true,
           content: body,
         });
       }
 
+      /**
+       * v1.0.10 (#2a): **compare** this machine's collective memory against the fleet's current blob. Writes nothing.
+       *
+       * ## Why this exists before merge does
+       *
+       * "Merge" needs a conflict rule -- *when two machines assert different facts, who wins?* -- and that is a
+       * product decision, not an implementation detail. Shipping a merge before its rule is how a fleet silently
+       * loses one machine's memory.
+       *
+       * What needs no decision is the half that **prevents harm**: telling a caller whether their local document is
+       * the newest one, and what would be lost if they published over the fleet's copy. That is this action.
+       *
+       * ## Why a set comparison instead of a diff
+       *
+       * `same` is decided by **whole-document hash equality**, not by the absence of line differences: two documents
+       * with identical line sets in a different order are not the same, and reporting them as the same would hide an
+       * order change. The line sets are then reported as `local_only` / `fleet_only` -- deliberately *not* a diff,
+       * because a diff would report "moved" versus "changed" and then want a merge policy. **A set comparison cannot
+       * resolve anything, which is the property this step needs.**
+       *
+       * ## Why it re-hashes the fleet copy
+       *
+       * Comparing unverified content would launder it: the report would give a hash-verified-looking answer about
+       * bytes nobody checked. A blob that fails its own name is reported as unverified, never compared.
+       */
+      if (typeof args?.action === 'string' && args.action === 'diff') {
+        const file = collectivePath();
+        if (file === null) {
+          throw new W2MError('W2M_CONFIG', 'W2M_CONFIG: there is no profile to compare collective memory from', {
+            hint: 'the collective layer lives beside the profile that mounted this plugin',
+          });
+        }
+        let localBytes;
+        try {
+          localBytes = await fs.readFile(file);
+        } catch {
+          throw new W2MError('W2M_NOT_FOUND', `W2M_NOT_FOUND: no collective memory to compare at ${file}`, {
+            hint: 'write measured facts to it first; this action compares, it does not create',
+          });
+        }
+        const localHash = createHash('sha256').update(localBytes).digest('hex');
+        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) {
+          // No fleet document yet: nothing to differ from. Reported as a state, not as an error.
+          return JSON.stringify({
+            ok: true,
+            same: false,
+            local: { hash: localHash, bytes: localBytes.length, file },
+            fleet: { present: false, reason: 'this fleet has published no blob yet' },
+            merged: false,
+            wrote_anything: false,
+          });
+        }
+        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 },
+          );
+        }
+        const fleetHash = String(pointer.json?.hash ?? '');
+        const fleetRes = await request({
+          rabbitUrl: base,
+          token,
+          pathname: `/v1/fleet/blobs/${fleetHash}`,
+          accept: 'application/octet-stream',
+          signal: exec?.signal,
+        });
+        if (fleetRes.status === 404) {
+          // The pointer is a hint (see #3): eviction can take the document it names.
+          return JSON.stringify({
+            ok: true,
+            same: false,
+            local: { hash: localHash, bytes: localBytes.length, file },
+            fleet: {
+              present: false,
+              pointed_at: fleetHash,
+              reason: 'the pointer names a blob that no longer exists (oldest-first eviction)',
+            },
+            merged: false,
+            wrote_anything: false,
+          });
+        }
+        if (fleetRes.status !== 200) {
+          throw new W2MError(
+            'W2M_RABBIT_REFUSED',
+            `W2M_RABBIT_REFUSED: GET /v1/fleet/blobs/${fleetHash} answered HTTP ${fleetRes.status}`,
+            { http_status: fleetRes.status, detail: fleetRes.error ?? null },
+          );
+        }
+        const fleetText = fleetRes.text ?? '';
+        const fleetActual = createHash('sha256').update(fleetText, 'utf8').digest('hex');
+        if (fleetActual !== fleetHash) {
+          throw new W2MError(
+            'W2M_BAD_BLOB',
+            `W2M_BAD_BLOB: the fleet blob ${fleetHash} hashes to ${fleetActual} instead`,
+            {
+              hint: 'refusing to compare unverified content -- a comparison over bytes nobody checked would '
+                + 'launder them',
+              expected: fleetHash,
+              actual: fleetActual,
+            },
+          );
+        }
+
+        const localText = localBytes.toString('utf8');
+        // Trailing whitespace only: leading whitespace is markdown structure, not noise.
+        const norm = (text) => new Set(text.split('\n').map((line) => line.replace(/\s+$/, '')));
+        const localLines = norm(localText);
+        const fleetLines = norm(fleetText);
+        const localOnly = [...localLines].filter((line) => !fleetLines.has(line));
+        const fleetOnly = [...fleetLines].filter((line) => !localLines.has(line));
+        return JSON.stringify({
+          ok: true,
+          same: localHash === fleetHash,
+          local: { hash: localHash, bytes: localBytes.length, lines: localLines.size, file },
+          fleet: {
+            present: true,
+            hash: fleetHash,
+            bytes: Buffer.byteLength(fleetText, 'utf8'),
+            lines: fleetLines.size,
+            published_at: pointer.json?.published_at ?? null,
+            published_by: pointer.json?.published_by ?? null,
+          },
+          differing_lines: localOnly.length + fleetOnly.length,
+          preview: {
+            local_only: localOnly.slice(0, 20),
+            fleet_only: fleetOnly.slice(0, 20),
+            truncated: localOnly.length > 20 || fleetOnly.length > 20,
+          },
+          merged: false,
+          wrote_anything: false,
+          note: 'a comparison only. Merge has no conflict rule yet, so nothing is resolved and nothing is written.',
+        });
+      }
+
       const limitRaw = Number(args?.limit);
       const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(Math.floor(limitRaw), 500) : 20;
 

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;