@twinsearth/w2m-dsh-plugin 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -2,6 +2,119 @@
 
 All notable changes to this project are documented here.
 
+## [1.0.6] — 2026-10-17
+
+**DSH-GPW now ships *findable*: installed with the package, present in the plugin list, and off until an operator
+turns it on.**
+
+### What v1.0.5 got wrong
+
+It shipped the subpath export `@twinsearth/w2m-dsh-plugin/gpw` and no config row. **A plugin the composed tree does
+not mention is a plugin the plugin manager cannot list** -- so "enable it manually" had **nothing to click**, and
+the only way in was hand-editing a profile patch.
+
+**An optional component nobody can find is not optional, it is absent.** That is the same distinction as the seven
+written-but-unreachable modules in this repository, seen from the user's side instead of the code's.
+
+### The shape that fixes it
+
+The package's own bundle patch now carries a second entry:
+
+    - id: dsh-gpw
+      name: '@twinsearth/w2m-dsh-plugin/gpw'
+      disabled: true
+      config:
+        maxPerWindow: 10
+        windowMs: 60000
+        minGapMs: 3000
+
+**`disabled: true` is the load-bearing field.** The row exists, so the component appears; the toggle is off, so
+nothing answers `approval/request`; and **flipping it in the UI is the whole enablement step** -- no file edit, no
+restart of anything but the client.
+
+**It stays in the same `insert:` list as the w2m row**, and that is still the correct form: this is an insert
+because no earlier layer creates a `dsh-gpw` row. (A *bare* `- id:` patch aimed at a nonexistent row is skipped
+silently -- the failure recorded in this file and in TROUBLESHOOTING 3.2.)
+
+### The distinction the two releases now make
+
+| | v1.0.5 | v1.0.6 |
+|---|---|---|
+| Installs with the package | yes | yes |
+| Appears in the plugin manager | **no** | **yes** |
+| Enabled by default | no | no |
+| How you turn it on | hand-edit a profile patch | **click its toggle** |
+
+**Not verified: that the toggle actually flips it on and that it then intercepts.** That needs a live host. The
+observable evidence is its own startup line followed by its counted line --
+
+    approval-ratelimit: active -- at most 10 auto-approvals per 60 s, at least 3000 ms apart, process-wide
+    approval-ratelimit: N auto-approved, M deferred to the human
+
+-- **because without the second line, "mounted and working" and "mounted and doing nothing" are the same picture**,
+which is the failure this watchdog's own counters exist to prevent.
+
+## [1.0.5] — 2026-10-17
+
+**DSH-GPW ships as an optional sub-plugin, and the reason it never activated is fixed.**
+
+### What DSH-GPW is
+
+**Global Permission Watchdog.** It answers permission requests on the `approval/request` waterfall with a hard global
+budget: **at most 10 auto-approvals per rolling 60 s, at least 3000 ms apart.** Past either limit it returns
+`next()` -- *"no opinion"* -- so the request falls through to the human prompt **and waits**. It never refuses, and
+it never changes what is being asked.
+
+### Optional means optional, which decides where it lives
+
+The package declares **one** `dsh.bundle.patch`, and that is what makes the w2m plugin mount itself on install. **A
+second plugin in the same patch would mount for everyone**, and this one changes how permissions are answered -- that
+is an operator's decision, not a default.
+
+So it is exposed as `@twinsearth/w2m-dsh-plugin/gpw` and mounted by one explicit row:
+
+    - insert:
+        - id: dsh-gpw
+          name: '@twinsearth/w2m-dsh-plugin/gpw'
+
+**`insert:` is required and the reason is recorded in this package's own patch file**: no earlier layer creates a
+`dsh-gpw` row, and a bare `- id:` patch aimed at a nonexistent row is **skipped silently**. Removing the row
+disables it again.
+
+**It is deliberately not re-exported from `lib/index.js`.** A permission-answering plugin must not arrive because
+someone installed a fleet tool.
+
+### The defect that kept it from ever activating
+
+The standalone copy declared:
+
+    export const inject = { required: ['approval'] };
+
+**The host reads `inject` as an array of service names.** Measured across the shipped tree: **283 array-shaped
+declarations, 0 object-shaped.** So the host took the object's *key* and waited for a service literally named
+`required`:
+
+    pending (waiting for service: required)
+
+-- indefinitely, and the client reported the component as `等待依赖`. It is now `['approval']`, and `approval`
+does exist: `@deepseek-ai/dsh-base`'s patch mounts `@deepseek-ai/dsh-user-approval` as id `approval`.
+
+**The error message named its own cause**, which is why this took one measurement instead of an investigation: it
+said `required`, and `required` is the key.
+
+### What is verified, and what is not
+
+**Verified:** `lib/gpw.js` loads; `name` is `dsh-gpw`; `inject` is an array; `apply` is a function;
+`approval/request` and `allowed-once` both exist in the host (9 and 22 files respectively).
+
+**Not verified: that it mounts and intercepts.** That needs a live host with the row added. The observable evidence
+after a restart is its own startup line --
+
+    approval-ratelimit: active -- at most 10 auto-approvals per 60 s, at least 3000 ms apart, process-wide
+
+-- **and then the periodic counted line, without which "mounted and working" and "mounted and doing nothing" look
+identical.** That distinction is the reason those counters exist.
+
 ## [1.0.4] — 2026-10-17
 
 **The description described a different package, and it is the only thing many readers see.**

package/cordis.patch.yml

@@ -115,3 +115,23 @@
         allowedCommands: []
         p2pMode: auto
         stunServers: []
+    # DSH-GPW (Global Permission Watchdog) ships with this package and is **off until an operator turns it on**.
+    #
+    # It is in this insert list rather than left out of the tree entirely, because a plugin the composed tree does
+    # not mention is a plugin the plugin manager cannot list -- and then "enable it manually" has no control to
+    # click. **A row with `disabled: true` is the shape that makes it installable with the package and switchable
+    # from the UI**: the component shows up, its toggle is off, and flipping it needs no file edit.
+    #
+    # Found this way, not assumed: v1.0.5 shipped the subpath export but no row, so the watchdog was reachable only
+    # by hand-editing a profile patch. **An optional component nobody can find is not optional, it is absent.**
+    #
+    # What it does once enabled: answers `approval/request` with at most 10 auto-approvals per rolling 60 s, at
+    # least 3000 ms apart, and defers everything past that to the human prompt, where it waits.
+    - id: dsh-gpw
+      name: '@twinsearth/w2m-dsh-plugin/gpw'
+      disabled: true
+      config:
+        maxPerWindow: 10
+        windowMs: 60000
+        minGapMs: 3000
+

package/lib/gpw.js

@@ -0,0 +1,10 @@
+/**
+ * Package-facing entry for DSH-GPW: `@twinsearth/w2m-dsh-plugin/gpw`.
+ *
+ * The documented subpath a profile row names to enable the watchdog. A seam, not a second implementation -- the code
+ * lives in `src/plugin/gpw.mjs`, which is where it is readable.
+ *
+ * **It is deliberately not re-exported from `lib/index.js`.** The package root is what installs by default, and a
+ * permission-answering plugin must not arrive because someone installed a fleet tool.
+ */
+export { apply, inject, name } from '../src/plugin/gpw.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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",
@@ -16,7 +16,8 @@
     "./rabbit": "./bin/w2m-rabbit.mjs",
     "./localside": "./bin/w2m-localside.mjs",
     "./stun": "./bin/w2m-stun.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./gpw": "./lib/gpw.js"
   },
   "files": [
     "mcp.json",

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.4",
+  "version": "1.0.6",
   "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/gpw.mjs

@@ -0,0 +1,205 @@
+/**
+ * DSH-GPW -- Global Permission Watchdog (v1.0.5), shipped as an OPTIONAL sub-plugin of @twinsearth/w2m-dsh-plugin.
+ *
+ * ## What it does, in one paragraph
+ *
+ * It answers permission requests on the `approval/request` waterfall with a hard global budget: **at most 10
+ * auto-approvals per rolling 60 s, at least 3000 ms apart.** Anything past either limit returns `next()`, which is
+ * *"no opinion"* -- the request falls through to the human prompt and **waits**. It never refuses, and it never
+ * changes what is being asked; it only decides who answers and how fast.
+ *
+ * ## Why the budget exists
+ *
+ * Every auto-approval is a permission decision made without a human reading it. A watchdog with no ceiling is a
+ * plugin that grants everything and is indistinguishable from one that is working correctly -- the failure mode this
+ * repository has recorded seven times. The two counters it logs (`allowedTotal`, `deferredTotal`) exist so that
+ * "mounted and doing nothing" and "mounted and working" look different.
+ *
+ * ## How it is enabled -- it is NOT on by default
+ *
+ * Installing this package does **not** mount the watchdog: its own `dsh.bundle.patch` mounts only the w2m plugin.
+ * To enable it, add ONE `insert:` to the profile's `cordis.patch.yml`:
+ *
+ *     - insert:
+ *         - id: dsh-gpw
+ *           name: '@twinsearth/w2m-dsh-plugin/gpw'
+ *           config:
+ *             maxPerWindow: 10      # optional; these are the defaults
+ *             windowMs: 60000
+ *             minGapMs: 3000
+ *
+ * `insert:` is required: no earlier layer creates a `dsh-gpw` row, and a bare `- id:` patch aimed at a
+ * non-existent row is skipped **silently**. Remove the row to disable it again -- no other change is needed.
+ *
+ * ## Its dependency, and the bug that shipped in the standalone copy
+ *
+ * `inject = ['approval']`. The first version of this module declared `{ required: ['approval'] }`; the host reads
+ * `inject` as an array (**283 array-shaped declarations across the shipped tree, 0 object-shaped**), so it waited
+ * for a service named `required` and stayed `pending (waiting for service: required)` forever. `approval` itself
+ * exists: `@deepseek-ai/dsh-base`'s patch mounts `@deepseek-ai/dsh-user-approval` as id `approval`.
+ *
+ * ## Provenance
+ *
+ * Written as a standalone package `dsh-approval-ratelimit@1.0.0`, then folded in here so a fleet operator installs
+ * one thing. The logic is unchanged apart from the name and the `inject` fix; every comment explaining a decision is
+ * the original.
+ */
+
+/** @type {import('node:timers').Timeout | null} */
+let logTimer = null;
+
+export const name = 'dsh-gpw';
+
+export const inject = ['approval'];
+
+/**
+ * @param {object} ctx Cordis context.
+ * @param {object} [config]
+ * @param {number} [config.maxPerWindow] Auto-approvals allowed per rolling window. Default 10.
+ * @param {number} [config.windowMs] Window length in ms. Default 60000.
+ * @param {number} [config.minGapMs] Minimum gap between two auto-approvals, in ms. Default 3000.
+ */
+export function apply(ctx, config = {}) {
+  const maxPerWindow = positiveInt(config.maxPerWindow, 10);
+  const windowMs = positiveInt(config.windowMs, 60_000);
+  const minGapMs = positiveInt(config.minGapMs, 3_000);
+
+  /** Timestamps of the auto-approvals inside the current window, oldest first. */
+  const approvals = [];
+  /** Timestamp of the most recent auto-approval, or null. */
+  let lastApprovalAt = null;
+  /** Counters for the periodic line, so the operator can see this thing working. */
+  let deferredTotal = 0;
+  let allowedTotal = 0;
+
+  /**
+   * Drop approvals that have aged out of the window.
+   *
+   * A rolling window is the requirement; a fixed one would allow a burst of `2 * maxPerWindow`
+   * straddling a boundary (ten at the end of one minute, ten at the start of the next).
+   *
+   * @param {number} now
+   */
+  function prune(now) {
+    const cutoff = now - windowMs;
+    while (approvals.length > 0 && approvals[0] <= cutoff) approvals.shift();
+  }
+
+  /**
+   * Decide one request, without ever rejecting.
+   *
+   * @param {number} now
+   * @returns {{ allow: boolean, reason: string, inWindow: number }}
+   */
+  function decide(now) {
+    prune(now);
+    if (lastApprovalAt !== null && now - lastApprovalAt < minGapMs) {
+      return {
+        allow: false,
+        reason: `only ${now - lastApprovalAt} ms since the last auto-approval (needs ${minGapMs} ms)`,
+        inWindow: approvals.length,
+      };
+    }
+    if (approvals.length >= maxPerWindow) {
+      return {
+        allow: false,
+        reason: `${approvals.length} auto-approvals already in the last ${Math.round(windowMs / 1000)} s (limit ${maxPerWindow})`,
+        inWindow: approvals.length,
+      };
+    }
+    return { allow: true, reason: 'within both limits', inWindow: approvals.length };
+  }
+
+  /**
+   * One line per window of real activity, so a silent plugin and a broken plugin look different.
+   *
+   * The failure mode this guards against is the one this whole session keeps meeting: a component
+   * that is mounted, doing nothing, and indistinguishable from a healthy one. `allowedTotal` and
+   * `deferredTotal` are the two numbers that tell them apart.
+   */
+  function startReporter() {
+    if (logTimer !== null) return () => {};
+    logTimer = setInterval(() => {
+      if (allowedTotal === 0 && deferredTotal === 0) return;
+      ctx.logger?.info?.(
+        `approval-ratelimit: ${allowedTotal} auto-approved, ${deferredTotal} deferred to the human `
+        + `(limit ${maxPerWindow}/${Math.round(windowMs / 1000)}s, gap ${minGapMs}ms, ${approvals.length} in the current window)`,
+      );
+    }, windowMs);
+    logTimer.unref?.();
+    return () => {
+      if (logTimer !== null) {
+        clearInterval(logTimer);
+        logTimer = null;
+      }
+    };
+  }
+
+  /**
+   * The answerer.
+   *
+   * Registered on the `approval/request` waterfall. Returning `'allowed-once'` grants this one
+   * request; returning `next()` is "no opinion" and hands the decision to whoever answers next --
+   * which is the human prompt, and it *waits* there rather than being refused.
+   */
+  const disposeListener = ctx.on('approval/request', (request, next) => {
+    const now = Date.now();
+    const verdict = decide(now);
+    if (!verdict.allow) {
+      deferredTotal += 1;
+      // Debug, not warn: deferring is the designed behaviour of this plugin, and warning about the
+      // normal path trains an operator to ignore the line that would matter.
+      ctx.logger?.debug?.(
+        `approval-ratelimit: deferring to the human -- ${verdict.reason}`
+        + (request?.toolName ? ` (tool ${request.toolName})` : ''),
+      );
+      return next();
+    }
+    approvals.push(now);
+    lastApprovalAt = now;
+    allowedTotal += 1;
+    ctx.logger?.info?.(
+      `approval-ratelimit: auto-approved (${approvals.length}/${maxPerWindow} in the current window)`
+      + (request?.toolName ? ` tool ${request.toolName}` : '')
+      + (request?.reason ? ` -- ${request.reason}` : ''),
+    );
+    return 'allowed-once';
+  });
+
+  const stopReporter = startReporter();
+
+  // Reversible: the host owns this effect, so an unload removes the answerer and the timer with it.
+  // A listener that outlived its plugin would keep approving requests with nobody watching.
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => () => {
+      disposeListener?.();
+      stopReporter();
+    });
+  } else {
+    // No effect seam: say so rather than pretending the cleanup is guaranteed.
+    ctx.logger?.warn?.(
+      'approval-ratelimit: the context provides no ctx.effect, so the answerer and its reporter '
+      + 'cannot be released on unload',
+    );
+  }
+
+  ctx.logger?.info?.(
+    `approval-ratelimit: active -- at most ${maxPerWindow} auto-approvals per ${Math.round(windowMs / 1000)} s, `
+    + `at least ${minGapMs} ms apart, process-wide; everything else waits for the human`,
+  );
+}
+
+/**
+ * Coerce a config value to a positive integer, falling back to the default.
+ *
+ * A misconfigured limit must not silently become "0", which would disable the plugin while looking
+ * like it was on -- and must not become a non-finite number, which would break the comparison.
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function positiveInt(value, fallback) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return fallback;
+  return Math.floor(value);
+}

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

package/src/relay/persistence.mjs

@@ -4,6 +4,7 @@
  * `<state>/devices.json`  atomic snapshot (tmp file + rename)
  * `<state>/ledger.jsonl`  append-only, one JSON object per line
  * `<state>/operator-token.txt`  single line, 0600
+ * `<state>/blobs/<aa>/<sha256>`  content-addressed bytes, v1.0.7 (see `putBlob`)
  *
  * This is the only relay module allowed to touch the filesystem.
  * Corruption is never silent: every skipped line / unreadable snapshot is
@@ -12,12 +13,31 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
 import { rfc3339 } from './state.mjs';
 
 export const DEVICES_FILE = 'devices.json';
 export const LEDGER_FILE = 'ledger.jsonl';
 export const OPERATOR_TOKEN_FILE = 'operator-token.txt';
+/** v1.0.7: the content-addressed blob directory, and the two caps that keep it bounded. */
+export const BLOB_DIR = 'blobs';
+export const MAX_BLOB_BYTES = 8 * 1024 * 1024;
+export const MAX_BLOBS = 256;
+/**
+ * v1.0.7: **which fleet wrote each blob.**
+ *
+ * Content addressing keys a blob by its own hash, and a hash knows nothing about fleets. So two fleets that store
+ * the same bytes land at the same path -- and without this index, the second one could read the first one's content.
+ * **A content-addressed store with no ownership record is not isolated, it is shared.**
+ *
+ * The index is a separate document rather than part of the path (`blobs/<fleet>/<aa>/<hash>`) for one concrete
+ * reason: **deduplication is only sound when the content is identical**, and identical bytes stored twice would
+ * otherwise occupy two entries. The path stays a pure function of the content; the fleet is metadata.
+ *
+ * Shape: `{ "<sha256>": { fleet_id: string|null, added_at_ms: number } }`.
+ */
+export const BLOB_INDEX_FILE = 'index.json';
 
 /** Ledger entry types understood by `RabbitState#restore`. */
 export const LEDGER_TYPES = Object.freeze([
@@ -250,8 +270,232 @@ export class Persistence {
     return true;
   }
 
+  /* ------------------------------------------------------------------------------------------- */
+  /* v1.0.7: content-addressed blobs — the fleet sync channel (#1)                               */
+  /* ------------------------------------------------------------------------------------------- */
+
+  /**
+   * Store bytes under their own SHA-256, and read them back by that hash.
+   *
+   * ## Why the relay may carry bytes at all, when it deliberately carries none today
+   *
+   * The relay persists `stdout_sha256` and never the text, and `src/agent/storage.mjs` records why that matters:
+   * `memory.jsonl` on each machine is the only durable copy of what a command printed. **That invariant is about
+   * the relay not becoming a document store** — it never interprets content and never asserts that content is
+   * authentic.
+   *
+   * A blob keyed by **its own hash** preserves both halves. The relay still interprets nothing; **the hash is what
+   * says the bytes are the bytes**, exactly as `stdout_sha256` does for a result. The only thing that is new is
+   * that a hash the relay already holds can now have its bytes fetched from the same place.
+   *
+   * ## The two limits, because an uncapped writer is what caused the original incident
+   *
+   * `storage.mjs`'s header records the incident that produced its whole design: a single uncapped writer reached
+   * 100% filesystem at 14.7 GB/day. A blob channel with no ceiling reproduces that on the relay, so:
+   *
+   *   * **8 MiB per blob** — a `fleet-memory.md` is tens of KB; this is three orders of magnitude of headroom.
+   *     Larger content is an archive, not a memory.
+   *   * **256 blobs** — bounded *count* matters as much as bounded size: 256 × 8 MiB caps a fleet's share at
+   *     2 GiB regardless of what it writes.
+   *
+   * Eviction is oldest-first and **never takes the last blob**: deleting the only copy of a fact is the failure
+   * `UNDELETABLE_TIERS` exists to prevent locally.
+   *
+   * @param {Buffer} bytes
+   * @param {{fleetId?: string|null}} [options] the owning fleet, recorded so another fleet cannot read it back
+   * @returns {{ok:true, hash:string, bytes:number, evicted:string[]}|{ok:false, reason:string, detail:string}}
+   */
+  putBlob(bytes, options = {}) {
+    if (!this.enabled) return { ok: false, reason: 'PERSISTENCE_DISABLED', detail: 'the relay has no state directory' };
+    if (!Buffer.isBuffer(bytes) || bytes.length === 0) {
+      return { ok: false, reason: 'BLOB_EMPTY', detail: 'an empty blob is a caller bug, not content' };
+    }
+    if (bytes.length > MAX_BLOB_BYTES) {
+      return {
+        ok: false,
+        reason: 'BLOB_TOO_LARGE',
+        detail: `${bytes.length} bytes exceeds the ${MAX_BLOB_BYTES}-byte limit`,
+      };
+    }
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    const file = this.blobFile(hash);
+    if (file === null) return { ok: false, reason: 'PERSISTENCE_DISABLED', detail: 'no blob directory' };
+
+    const index = this.readBlobIndex();
+    const fleetId = typeof options.fleetId === 'string' && options.fleetId !== '' ? options.fleetId : null;
+
+    // Content addressing makes the write idempotent: the same bytes always land at the same path.
+    if (fs.existsSync(file)) {
+      /**
+       * Already stored. **The first writer's fleet keeps ownership** -- re-assigning it on a second write would let
+       * one fleet claim a blob another fleet already owns by simply PUT-ting the same bytes, which is the same
+       * failure as having no index at all.
+       */
+      const entry = index[hash];
+      if (entry === undefined) {
+        index[hash] = { fleet_id: fleetId, added_at_ms: this._now() };
+        this.writeBlobIndex(index);
+      }
+      return { ok: true, hash, bytes: bytes.length, evicted: [] };
+    }
+
+    const evicted = this.evictBlobsFor(1);
+    for (const gone of evicted) delete index[gone];
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const tmp = `${file}.tmp-${process.pid}-${this._now()}`;
+      fs.writeFileSync(tmp, bytes);
+      fs.renameSync(tmp, file);
+    } catch (error) {
+      this.warn(BLOB_DIR, `blob write failed: ${error?.message ?? String(error)}`);
+      return { ok: false, reason: 'BLOB_WRITE_FAILED', detail: error?.message ?? String(error) };
+    }
+    index[hash] = { fleet_id: fleetId, added_at_ms: this._now() };
+    this.writeBlobIndex(index);
+    return { ok: true, hash, bytes: bytes.length, evicted };
+  }
+
+  /**
+   * The bytes for a hash, or `null`.
+   *
+   * Never throws -- an unreadable blob is a miss, not a crash -- and **when `fleetId` is supplied, a blob owned by a
+   * different fleet is a miss too.** The caller cannot distinguish "no such blob" from "not yours", which is
+   * deliberate: a distinguishable refusal tells a prober that a hash exists on this relay.
+   *
+   * @param {string} hash
+   * @param {{fleetId?: string|null|undefined}} [options] omit `fleetId` entirely for an unscoped read
+   */
+  getBlob(hash, options = {}) {
+    const file = this.blobFile(hash);
+    if (file === null) return null;
+    if (options.fleetId !== undefined) {
+      const entry = this.readBlobIndex()[hash];
+      // A blob with no recorded owner predates the index or was written unscoped; it is not this fleet's.
+      if (entry === undefined || entry.fleet_id !== options.fleetId) return null;
+    }
+    try {
+      return fs.readFileSync(file);
+    } catch {
+      return null;
+    }
+  }
+
+  hasBlob(hash) {
+    const file = this.blobFile(hash);
+    if (file === null) return false;
+    try {
+      return fs.statSync(file).isFile();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Every stored blob, newest last, with the size and mtime needed to enforce the count cap.
+   *
+   * @returns {{hash:string, bytes:number, mtimeMs:number}[]}
+   */
+  listBlobs() {
+    if (!this.enabled) return [];
+    const root = path.join(this.dir, BLOB_DIR);
+    let shards;
+    try {
+      shards = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const shard of shards) {
+      if (!shard.isDirectory()) continue;
+      const shardPath = path.join(root, shard.name);
+      let names;
+      try {
+        names = fs.readdirSync(shardPath, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of names) {
+        if (!entry.isFile() || entry.name.includes('.tmp-')) continue;
+        try {
+          const stat = fs.statSync(path.join(shardPath, entry.name));
+          out.push({ hash: entry.name, bytes: stat.size, mtimeMs: stat.mtimeMs });
+        } catch {
+          /* a blob that vanished mid-scan is not a failure */
+        }
+      }
+    }
+    out.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    return out;
+  }
+
+  /**
+   * Make room for `incoming` more blobs, oldest first, and never take the last one.
+   *
+   * **The caller must prune the index for the returned hashes** -- this method deletes files, and the index is a
+   * separate document. `putBlob` does that pruning; a future caller that evicts for another reason owes the same.
+   *
+   * @param {number} incoming
+   * @returns {string[]} the hashes evicted
+   */
+  evictBlobsFor(incoming) {
+    const existing = this.listBlobs();
+    const over = existing.length + incoming - MAX_BLOBS;
+    if (over <= 0) return [];
+    const evicted = [];
+    let count = existing.length;
+    for (const blob of existing) {
+      if (count <= 1) break; // never delete the only copy of anything
+      try {
+        fs.rmSync(path.join(this.dir, BLOB_DIR, blob.hash.slice(0, 2), blob.hash), { force: true });
+        evicted.push(blob.hash);
+        count -= 1;
+      } catch {
+        /* leave it; the caller will see the count did not drop */
+      }
+      if (evicted.length >= over) break;
+    }
+    if (evicted.length > 0) this.warn(BLOB_DIR, `evicted ${evicted.length} blob(s) to stay within ${MAX_BLOBS}`);
+    return evicted;
+  }
+
+  /** Read the hash -> owner map. A missing or corrupt index reads as empty rather than taking the relay down. */
+  readBlobIndex() {
+    if (!this.enabled) return {};
+    try {
+      const raw = fs.readFileSync(path.join(this.dir, BLOB_DIR, BLOB_INDEX_FILE), 'utf8');
+      const parsed = JSON.parse(raw);
+      return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+
+  /** Atomically replace the index. Best-effort: a failure is warned about, never thrown at the caller. */
+  writeBlobIndex(index) {
+    if (!this.enabled) return false;
+    const file = path.join(this.dir, BLOB_DIR, BLOB_INDEX_FILE);
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const tmp = `${file}.tmp-${process.pid}-${this._now()}`;
+      fs.writeFileSync(tmp, `${JSON.stringify(index)}\n`, 'utf8');
+      fs.renameSync(tmp, file);
+      return true;
+    } catch (error) {
+      this.warn(BLOB_DIR, `blob index write failed: ${error?.message ?? String(error)}`);
+      return false;
+    }
+  }
+
+  /** `<state>/blobs/<aa>/<sha256>`, or `null` when persistence is off or the hash is not a sha256. */
+  blobFile(hash) {
+    if (!this.enabled) return null;
+    if (typeof hash !== 'string' || !/^[0-9a-f]{64}$/.test(hash)) return null;
+    return path.join(this.dir, BLOB_DIR, hash.slice(0, 2), hash);
+  }
+
   /** Redacted view for `/healthz` — never contains tokens. */
   describe() {
+    const blobs = this.listBlobs();
     return {
       enabled: this.enabled,
       dir: this.dir,
@@ -261,6 +505,11 @@ export class Persistence {
       devices_missing: this.devicesMissing,
       ledger_lines_read: this.ledgerLinesRead,
       ledger_lines_skipped: this.ledgerLinesSkipped,
+      /** v1.0.7: the fleet sync channel's occupancy, reported as counts and bytes — never contents. */
+      blobs: blobs.length,
+      blob_bytes: blobs.reduce((sum, b) => sum + b.bytes, 0),
+      blobs_limit: MAX_BLOBS,
+      blob_bytes_limit: MAX_BLOB_BYTES,
       /**
        * v0.6.2. `degraded: true` means the relay is answering requests while failing to record them,
        * which is the one relay failure that looks exactly like health from the outside.