@serfab/cadre-core 0.10.0 → 0.11.0

package/dist/cadre-node.js

@@ -2,6 +2,7 @@ import debug from 'debug';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
 import { peerIdFromString, peerIdFromPrivateKey } from '@libp2p/peer-id';
 import { createLibp2pNode } from '@optimystic/db-p2p';
+import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { multiaddr } from '@multiformats/multiaddr';
 import { CONTROL_CLUSTER_POLICY, CONTROL_REPLICATION_BREADTH, DEFAULT_CHECKIN_WINDOW_MS } from './types.js';
 import { sign } from '@optimystic/quereus-plugin-crypto';
@@ -11,14 +12,16 @@ import { DEFAULT_IDENTITY_KEY_ID } from './key-store.js';
 import { loadOrCreateIdentityKey } from './identity-key.js';
 import { MemoryTrustedOwnerStore } from './trusted-owner-store.js';
 import { MemoryBootstrapPeerStore } from './bootstrap-peer-store.js';
+import { mergePeerAddrs, groupAddrsByPeerId } from './peer-addr-book.js';
 import { verifyCadrePeerVoucher } from './peer-authorization.js';
 import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
 import { signPeerRecord, verifyPeerRecordSignature, isPeerRecordFresh, orderSignalingFirst, isSignalingAddr, trailingPeerId, currentMemberTrustPolicy, DEFAULT_PEER_RECORD_MAX_AGE_MS, DEFAULT_PEER_RECORD_HEARTBEAT_MS } from './peer-record.js';
 import { signDeviceTokenRecord, verifyDeviceTokenSignature, isPushPlatform } from './device-token.js';
 import { StrandWatcher } from './strand-watcher.js';
 import { StrandInstanceManager } from './strand-instance-manager.js';
-import { deriveCohortMembers, selectStrandMode } from './strand-cohort.js';
-import { selectControlCohortDials, DEFAULT_CONTROL_COHORT_RECONCILE_MS, DEFAULT_CONTROL_COHORT_TARGET_DEGREE } from './control-cohort.js';
+import { deriveCohortMembers } from './strand-cohort.js';
+import { selectControlCohortDials, DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS, DEFAULT_CONTROL_COHORT_RECONCILE_MS, DEFAULT_CONTROL_COHORT_TARGET_DEGREE } from './control-cohort.js';
+import { withDeadline } from './control-stream.js';
 import { EnrollmentService } from './enrollment.js';
 import { HibernationManager } from './hibernation-manager.js';
 import { ControlDatabase } from './control-database.js';
@@ -41,6 +44,18 @@ const timing = debug('sereus:cadre:timing');
  * `RTCPeerConnection` reaching `connected` and libp2p surfacing the connection.
  */
 const TURN_CONSUME_WINDOW_MS = 1000;
+/**
+ * How often a running strand re-resolves its siblings' strand-network addresses
+ * and re-merges them into its own libp2p address book
+ * ({@link CadreNode.refreshStrandPeerAddrs}). Overridable per node via
+ * `network.controlCohort.strandAddrRefreshMs`.
+ *
+ * Ten minutes sits comfortably inside the peerStore's one-hour address expiry
+ * (`MAX_ADDRESS_AGE`, see `peer-addr-book.ts`) with headroom for several missed
+ * passes, and far above the 15 s reconcile cadence the refresh rides on, so the
+ * strand-addr RPC fan-out stays cheap.
+ */
+export const STRAND_PEER_ADDR_REFRESH_MS = 10 * 60 * 1000;
 /**
  * A circuit relay as a strand-addr RPC target: dialed by peerId, with its
  * direct addr riding along as the fallback for a relay we hold no connection to.
@@ -110,6 +125,14 @@ export class CadreNode {
         this.pushFanoutService = null;
         /** Backing field for the {@link running} / {@link isRunning} getters. */
         this._running = false;
+        /**
+         * The control database's own raw storage (cache-wrapped), resolved once per
+         * `start()` and released in {@link cleanup}. Owning it is what keeps
+         * `config.storage.provider('control')` a once-per-runtime call: a `stop()` then
+         * `start()` cycle on this object re-resolves against a live cache, and never
+         * orphans the previous wrapper's registration in the shared cache pool.
+         */
+        this.controlStorage = null;
         /**
          * In-flight {@link serviceWake} operations keyed by strandId. Coalesces
          * concurrent on-demand wakes for the same strand into one runtime build + one
@@ -218,6 +241,16 @@ export class CadreNode {
          * strand is no longer running are pruned on each reconcile pass.
          */
         this.delegateAnnounceAt = new Map();
+        /**
+         * When each running strand last had its siblings' strand addresses re-resolved
+         * into its own address book, keyed by strandId. Throttles
+         * {@link refreshStrandPeerAddrs} to once per {@link STRAND_PEER_ADDR_REFRESH_MS}
+         * per strand so the 15 s reconcile tick never becomes per-tick RPC chatter.
+         * Entries for strands that are no longer running are pruned on each pass, so a
+         * hibernated-then-resumed strand refreshes immediately rather than inheriting a
+         * stale stamp.
+         */
+        this.strandPeerAddrRefreshAt = new Map();
         /**
          * Cold-start bootstrap dial targets: the owner-flagged peers of every seed
          * this node has applied, keyed by peer id, valued by the seed's multiaddr
@@ -805,6 +838,36 @@ export class CadreNode {
     async createControlNode() {
         return await createLibp2pNode(this.buildControlNodeOptions());
     }
+    /**
+     * The control database's cache-wrapped raw storage, resolved from
+     * `config.storage.provider` on first use and then held in {@link controlStorage}
+     * for the rest of this runtime.
+     *
+     * Resolving once is the contract `RawStorageProvider` (types.ts) states: a provider is
+     * called once per scope per runtime lifetime. Re-entering it per call would mint a
+     * second store over one backend — a fresh, cold cache, with the previous wrapper's
+     * registration orphaned in the process-wide pool.
+     *
+     * Lazy rather than eager in `start()` so the pure-unit call path
+     * (`cadre-node-control-node-options.spec.ts` calls `buildControlNodeOptions` on a
+     * bare `new CadreNode`) still resolves — and, on that path too, only once.
+     *
+     * Wrapped in the write-through raw-storage cache (quereus-plugin-sereus's
+     * `cached-storage.ts`) because a control start's cost is its raw-storage
+     * operation count.
+     */
+    resolveControlStorage() {
+        if (this.controlStorage) {
+            return this.controlStorage;
+        }
+        const provider = this.config.storage?.provider;
+        if (!provider) {
+            return undefined;
+        }
+        const resolved = typeof provider === 'function' ? provider('control') : provider;
+        this.controlStorage = wrapStorageWithCache(resolved, 'control');
+        return this.controlStorage;
+    }
     /**
      * Map this node's config onto the control network's libp2p node options.
      *
@@ -814,19 +877,15 @@ export class CadreNode {
      * only caller in production is `createControlNode`.
      */
     buildControlNodeOptions() {
-        const { controlNetwork, network, storage, profile } = this.config;
+        const { controlNetwork, network, profile } = this.config;
         const identityKey = this.identityKey;
         const listenAddrs = resolveListenAddrs(network);
         // Determine relay mode: if explicitly set in config, use that;
         // otherwise default to true for storage profile nodes (better connectivity/uptime)
         const enableRelay = network?.enableRelay ?? (profile === 'storage');
-        // Create storage provider for control network
-        // Uses the factory function pattern if provided to create control-network-specific storage
-        const controlStorageProvider = storage?.provider
-            ? (typeof storage.provider === 'function'
-                ? storage.provider('control')
-                : storage.provider)
-            : undefined;
+        // The control node's own storage, resolved once per runtime (see
+        // {@link resolveControlStorage}) rather than per call.
+        const controlStorageProvider = this.resolveControlStorage();
         const nodeOptions = {
             port: 0,
             bootstrapNodes: controlNetwork.bootstrapNodes,
@@ -1203,7 +1262,11 @@ export class CadreNode {
         const existing = await this.controlDatabase.queryPeerRecord(peerId);
         if (!existing) {
             if (!this.seedBootstrapService) {
-                log('registerSelf: not yet a CadrePeer member and no owner service to self-insert; skipping (an owner must add this peer first)');
+                // "No row" also covers "revoked": queryPeerRecord reads a row whose StampId is
+                // retired in Revocation as absent, so a removed node lands here every heartbeat
+                // and stops refreshing its own record — correct, but say so, or the message reads
+                // as "never added" for a node that was removed.
+                log('registerSelf: no readable CadrePeer row for self (never added, or removed and its stamp retired) and no owner service to self-insert; skipping');
                 return 'skipped';
             }
             // First-time row: requires an owner signature (the node is its own
@@ -1225,9 +1288,10 @@ export class CadreNode {
             // first publish", add a fourth SelfRegistrationOutcome rather than re-labelling.
             log('registerSelf: own CadrePeer row appeared mid-publish (concurrent authorize); self-updating to carry the signature');
         }
-        // Null only on the fall-through above, where the pre-race read missed the row a
+        // Reached on the fall-through above, where the pre-race read missed the row a
         // concurrent authorize then seated — so re-read to get that row's `UpdatedAt`, which
-        // the strictly-greater self-update rule is measured against.
+        // the strictly-greater self-update rule is measured against. The re-read can still
+        // come back null (see the branch below).
         //
         // NOTE: when `existing` is set it predates this publish, so a removePeer(self) racing
         // in would leave the UPDATE below matching no rows while still reporting 'refreshed'.
@@ -1235,7 +1299,13 @@ export class CadreNode {
         // if removing self ever becomes something that happens concurrently in practice.
         const current = existing ?? await this.controlDatabase.queryPeerRecord(peerId);
         if (!current) {
-            log('registerSelf: own CadrePeer row vanished mid-publish; skipping (next refresh re-inserts)');
+            // Two causes, and the second is a steady state rather than a race: the row really
+            // vanished mid-publish (next refresh re-inserts), or this node was REVOKED — its row
+            // is physically present, so insertCadrePeer's in-lock existence check no-op'd above,
+            // but queryPeerRecord reads it as absent because its stamp is retired. The revoked
+            // case repeats every heartbeat and never re-inserts; that is intended (a revoked node
+            // has nothing to publish), so this stays a skip, not an error.
+            log('registerSelf: own CadrePeer row not readable (vanished mid-publish, or this node is revoked and its stamp retired); skipping');
             return 'skipped';
         }
         const record = this.signSelfRecord(peerId, signingKey, addrs, current);
@@ -1530,8 +1600,11 @@ export class CadreNode {
         // than a local write) are picked up here, bounding the snapshot's staleness
         // to the reconcile interval.
         // NOTE: this refresh and the sibling enumeration below each run their own
-        // CadrePeer query (two reads per pass); if those reads ever get costly,
-        // share one row-set across both.
+        // CadrePeer query (two reads per pass), plus a third from
+        // `refreshStrandPeerAddrs` on the passes where a strand is due AND this node
+        // holds a control connection (one read for the whole pass, not one per
+        // strand); if those reads ever get costly, share one row-set across all
+        // three.
         await this.refreshMembershipGate('reconcile');
         if (!this._running || !this.controlNode || !this.controlDatabase) {
             return;
@@ -1544,6 +1617,14 @@ export class CadreNode {
         if (!this._running || !this.controlNode || !this.controlDatabase) {
             return;
         }
+        // Then re-warm each running strand's own address book from its siblings, on
+        // its own (much longer) throttle. Same reasoning as warmSiblingAddrBook
+        // below, one layer down: replication runs on the STRAND network, and every
+        // layer under cadre-core dials strand peers by bare peer id.
+        await this.refreshStrandPeerAddrs();
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            return;
+        }
         const selfPeerId = this.controlNode.peerId.toString();
         // Reap guarded rows this node still holds for incarnations an already-committed
         // Revocation tombstone retires — the half of a removal replication cannot carry
@@ -1622,9 +1703,16 @@ export class CadreNode {
             // Don't silently bound coverage — surface what the out-degree cap dropped.
             log('reconcileControlCohort: capped %d non-owner sibling(s) at targetDegree=%d', cappedNonOwner, targetDegree);
         }
-        // 3. Skip already-connected peers (no re-dial / churn for live connections).
+        // 3. Warm the libp2p address book with EVERY sibling's verified addresses,
+        //    keeping what resolved for the dial loop below.
+        const resolved = await this.warmSiblingAddrBook(siblings);
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            return;
+        }
+        // 4. Skip already-connected peers (no re-dial / churn for live connections).
         const connected = new Set(this.controlNode.getConnections().map((c) => c.remotePeer.toString()));
-        // 4. Resolve + dial each selected, not-yet-connected sibling, best-effort.
+        // 5. Dial each selected, not-yet-connected sibling, best-effort, from the
+        //    addresses step 3 already resolved for it.
         let dialed = 0;
         for (const sibling of dials) {
             if (!this._running || !this.controlNode) {
@@ -1633,34 +1721,109 @@ export class CadreNode {
             if (connected.has(sibling.peerId)) {
                 continue;
             }
-            if (await this.dialControlSibling(sibling)) {
+            if (await this.dialControlSibling(sibling, resolved.get(sibling.peerId) ?? [])) {
                 dialed++;
             }
         }
         log('reconcileControlCohort: pass complete (siblings=%d, selected=%d, dialed=%d)', siblings.length, dials.length, dialed);
     }
     /**
-     * Resolve one sibling's control-network dial addresses and dial it, best-effort.
-     * Returns whether a dial was attempted (false when no address resolves).
+     * Resolve every sibling's signed address record once and merge what resolves
+     * into the control node's libp2p **address book** (peerStore). Returns the
+     * resolved addresses per sibling so the dial loop reuses them rather than
+     * re-resolving — one `queryPeerRecord` per sibling per pass, not two.
+     *
+     * Deliberately every sibling, not the {@link selectControlCohortDials} subset,
+     * and deliberately including already-connected ones: everything below
+     * cadre-core dials by bare peer id (Optimystic's cluster/repo clients, FRET
+     * ping/announce), so the address book has to be warm BEFORE a live connection
+     * drops, and a sibling the out-degree cap declines to dial is still one those
+     * layers may need to reach.
      *
-     * A per-peer failure (NAT, offline, relay down, connection-gater denial) is
-     * logged and swallowed so one unreachable sibling never aborts the pass —
-     * exactly like {@link SeedBootstrapService.applySeed}'s owner-dial loop. A
-     * failed dial is simply retried on the next pass.
+     * Only `resolvePeerAddrs` output is merged — never the cold-start
+     * `peerStoreAddrs` fallback, which came out of the address book to begin with
+     * and would restamp unverified seed addresses indefinitely. A sibling that
+     * resolves to nothing (revoked, stale, untrusted) is not written at all, so its
+     * existing entry ages out on its own.
+     *
+     * NOTE: this resolves EVERY sibling serially before the dial loop below runs,
+     * so it costs one record query per sibling per reconcile pass (~15s) and each
+     * one delays the pass's first dial. A cadre is a handful of devices, so today
+     * that is a few extra local reads; if cadres ever grow large, batch the records
+     * into one query, merge only on change, or move the warm pass after the dials.
+     */
+    async warmSiblingAddrBook(siblings) {
+        const resolved = new Map();
+        const counts = { merged: 0, restamped: 0, skipped: 0, failed: 0 };
+        for (const sibling of siblings) {
+            if (!this._running || !this.controlNode) {
+                break;
+            }
+            const addrs = await this.resolveSiblingAddrs(sibling.peerId);
+            resolved.set(sibling.peerId, addrs);
+            // Re-guarded after the resolve await as well as before it: the write is
+            // the half that matters, and a torn-down node must never be written to.
+            const controlNode = this.controlNode;
+            if (!this._running || !controlNode) {
+                break;
+            }
+            // `mergePeerAddrs` owns the whole best-effort contract — including parsing
+            // a malformed `CadrePeer.PeerId` — so one bad row cannot abort the pass.
+            counts[await mergePeerAddrs(controlNode, sibling.peerId, addrs)]++;
+        }
+        log('reconcileControlCohort: address book warmed (siblings=%d, merged=%d, restamped=%d, skipped=%d, failed=%d)', resolved.size, counts.merged, counts.restamped, counts.skipped, counts.failed);
+        return resolved;
+    }
+    /**
+     * {@link resolvePeerAddrs} for one sibling, best-effort: a control-DB read
+     * failure yields `[]` (and the cold-start fallback then gets its turn) rather
+     * than aborting the whole pass, like every other step here.
      */
-    async dialControlSibling(sibling) {
+    async resolveSiblingAddrs(peerId) {
+        try {
+            return await this.resolvePeerAddrs(peerId);
+        }
+        catch (error) {
+            log('reconcileControlCohort: resolving addrs for %s failed (continuing): %o', peerId, error);
+            return [];
+        }
+    }
+    /**
+     * Budget for ONE proactive dial of the reconcile pass — steady-state sibling
+     * ({@link dialControlSibling}) and cold-start bootstrap peer
+     * ({@link dialBootstrapPeer}) alike, since both feed a whole address list to
+     * one `dial()` and both run in a sequential loop that the next entry waits on.
+     *
+     * See {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} for why the pass bounds
+     * this itself rather than inheriting each address's libp2p attempt timeout.
+     */
+    controlDialTimeoutMs() {
+        return this.config.network?.controlCohort?.dialTimeoutMs
+            ?? DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS;
+    }
+    /**
+     * Dial one sibling from its already-resolved addresses, best-effort. Returns
+     * whether a dial was attempted (false when no address resolves).
+     *
+     * A per-peer failure (NAT, offline, relay down, connection-gater denial, or
+     * the {@link controlDialTimeoutMs} budget expiring) is logged and swallowed so
+     * one unreachable sibling never aborts the pass — exactly like
+     * {@link SeedBootstrapService.applySeed}'s owner-dial loop. A failed dial is
+     * simply retried on the next pass.
+     */
+    async dialControlSibling(sibling, resolved) {
         const controlNode = this.controlNode;
         if (!controlNode) {
             return false;
         }
-        const addrs = await this.resolveControlDialAddrs(sibling.peerId);
+        const addrs = await this.resolveControlDialAddrs(sibling.peerId, resolved);
         if (addrs.length === 0) {
             log('reconcileControlCohort: no dialable control address for sibling %s; skipping', sibling.peerId);
             return false;
         }
         try {
             log('reconcileControlCohort: dialing sibling %s (%d addr(s))', sibling.peerId, addrs.length);
-            await controlNode.dial(addrs);
+            await withDeadline(this.controlDialTimeoutMs(), `reconcileControlCohort dial of sibling ${sibling.peerId}`, (signal) => controlNode.dial(addrs, { signal }));
             return true;
         }
         catch (error) {
@@ -1669,16 +1832,16 @@ export class CadreNode {
         }
     }
     /**
-     * Resolve a sibling's control-network dial addresses for the reconcile pass.
+     * A sibling's control-network dial addresses for the reconcile pass.
      *
-     * Primary (steady state): the signed, fresh, trust-gated control addresses from
-     * the converged `CadrePeer` record via {@link resolvePeerAddrs}. Fallback (cold
-     * start): the libp2p peerStore entries `applySeed` populated, used only while the
-     * record is not yet resolvable. Returns `[]` (never throws) when neither yields
-     * an address — that sibling is skipped this pass.
-     */
-    async resolveControlDialAddrs(peerId) {
-        const resolved = await this.resolvePeerAddrs(peerId);
+     * Primary (steady state): the signed, fresh, trust-gated control addresses
+     * `resolved` for it by {@link warmSiblingAddrBook} — passed in rather than
+     * re-resolved, so the pass makes one record query per sibling. Fallback (cold
+     * start): the libp2p peerStore entries `applySeed` populated, used only while
+     * the record is not yet resolvable. Returns `[]` (never throws) when neither
+     * yields an address — that sibling is skipped this pass.
+     */
+    async resolveControlDialAddrs(peerId, resolved) {
         if (resolved.length > 0) {
             return resolved;
         }
@@ -1839,7 +2002,7 @@ export class CadreNode {
         }
         try {
             log('reconcileControlCohort(cold-start): dialing bootstrap peer %s (%d addr(s))', peerId, parsed.length);
-            await controlNode.dial(parsed);
+            await withDeadline(this.controlDialTimeoutMs(), `reconcileControlCohort cold-start dial of bootstrap peer ${peerId}`, (signal) => controlNode.dial(parsed, { signal }));
             return true;
         }
         catch (error) {
@@ -2510,7 +2673,6 @@ export class CadreNode {
             return;
         }
         try {
-            // Discovery path: no explicit mode — infer from cohort membership.
             await this.launchStrand(strand, sAppConfig);
         }
         catch (error) {
@@ -2611,6 +2773,16 @@ export class CadreNode {
             await this.controlNode.stop();
             this.controlNode = null;
         }
+        // Release the control store's cache registration LAST — after the database and
+        // node that write through it are down. Dropping the field is what lets a
+        // stop()/start() cycle re-resolve the provider against a live cache instead of
+        // handing the restarted node a retired wrapper. Logged, never thrown: a
+        // cache-bookkeeping failure must not abort a teardown.
+        if (this.controlStorage) {
+            const controlStorage = this.controlStorage;
+            this.controlStorage = null;
+            await disposeStorageCache(controlStorage).catch((err) => log('Failed to dispose control storage cache: %o', err));
+        }
     }
     // Hibernation callbacks
     async handleStrandIdle(strandId) {
@@ -2649,7 +2821,7 @@ export class CadreNode {
     }
     /**
      * Wake a strand. If it was hibernating (quiesced — no libp2p node), re-resolve
-     * the cohort discovery seed and mode exactly as `launchStrand` does and rebuild
+     * the cohort discovery seed exactly as `launchStrand` does and rebuild
      * its runtime via the strand manager. If it is still live (e.g. waking an idle
      * strand, which retains its resources), just flip the status. Overlapping wake
      * triggers are coalesced upstream by `HibernationManager`, so this runs once
@@ -2669,8 +2841,8 @@ export class CadreNode {
             this.emit('strand:waking', { strandId });
             return;
         }
-        // Quiesced: re-resolve volatile cohort inputs (the seed may have grown, the
-        // mode may have shifted bootstrap → networked) and rebuild the runtime.
+        // Quiesced: re-resolve the volatile cohort input (the seed may have grown)
+        // and rebuild the runtime.
         log('Waking strand %s — rebuilding strand-network resources', strandId);
         await this.resumeStrandRuntime(strandId);
         instance.lastActivity = new Date();
@@ -2678,11 +2850,10 @@ export class CadreNode {
         log('Strand %s awake (resources rebuilt)', strandId);
     }
     /**
-     * Rebuild a quiesced strand's runtime, re-resolving the volatile cohort inputs
-     * first: the discovery seed may have grown and cohort membership may have
-     * shifted the mode `bootstrap → networked` since the strand last ran. Shared by
+     * Rebuild a quiesced strand's runtime, re-resolving the volatile cohort input
+     * first: the discovery seed may have grown since the strand last ran. Shared by
      * the wake (`handleStrandWake`) and check-in (`handleStrandCheckIn`) paths so
-     * both apply the same fresh seed/mode resolution. `resumeStrand` is idempotent
+     * both apply the same fresh seed resolution. `resumeStrand` is idempotent
      * (returns the live instance unchanged) as a backstop against double-resume.
      */
     async resumeStrandRuntime(strandId) {
@@ -2692,12 +2863,13 @@ export class CadreNode {
         const delegatePeerId = this.identityKey
             ? peerIdFromPrivateKey(await strandTransportKey(this.identityKey, strandId)).toString()
             : undefined;
-        const seed = await this.resolveCohortSeed(strandId, delegatePeerId);
-        const mode = selectStrandMode(undefined, seed.hasOtherPeers);
-        await this.strandManager.resumeStrand(strandId, {
-            bootstrapNodes: seed.bootstrapNodes,
-            mode
-        });
+        const bootstrapNodes = await this.resolveCohortSeed(strandId, delegatePeerId);
+        const instance = await this.strandManager.resumeStrand(strandId, { bootstrapNodes });
+        // Same reason as the launch path: `bootstrapNodes` only reaches the address
+        // book through @libp2p/bootstrap discovery, so merge it directly as well.
+        if (instance.libp2pNode) {
+            await this.mergeStrandPeerAddrs(instance.libp2pNode, bootstrapNodes, strandId);
+        }
     }
     /**
      * Real cohort check-in for a hibernating strand (the `onCheckIn` callback).
@@ -2708,7 +2880,7 @@ export class CadreNode {
      * realized as a resume → bounded window → re-hibernate-if-idle cycle that
      * reuses the existing quiesce/resume primitives rather than a bespoke probe:
      *
-     *   1. Resume the strand (rebuild node + db, re-resolve cohort seed/mode) so
+     *   1. Resume the strand (rebuild node + db, re-resolve the cohort seed) so
      *      its strand network can reach cohort peers — exactly as a wake does.
      *   2. Hold it resumed for a bounded window, during which the app may drive
      *      reads (pull-on-read) and record activity.
@@ -2732,7 +2904,7 @@ export class CadreNode {
         }
         try {
             // 1. Resume exactly as a wake does: re-resolve the (possibly grown) cohort
-            //    seed + mode, then rebuild the runtime.
+            //    seed, then rebuild the runtime.
             log('Check-in: resuming strand %s to probe the cohort for pending activity', strandId);
             await this.resumeStrandRuntime(strandId);
             // 2-3. Bounded window for the strand network to connect + the app to act,
@@ -2837,15 +3009,13 @@ export class CadreNode {
         if (!this._running) {
             throw new Error('CadreNode not running');
         }
-        const { strandRow, sAppConfig, mode, founder } = config;
+        const { strandRow, sAppConfig, founder } = config;
         // Store sApp config for this strand
         this.sAppConfigs.set(strandRow.Id, sAppConfig);
-        log('Registered sAppConfig for strand %s (sApp: %s, mode: %s, founder: %s)', strandRow.Id, sAppConfig.id, mode ?? 'inferred', founder ?? false);
-        // Pass `mode` (possibly undefined) through: an explicit mode wins, while a
-        // caller that omits it gets the same cohort-inferred mode as the discovery path.
+        log('Registered sAppConfig for strand %s (sApp: %s, founder: %s)', strandRow.Id, sAppConfig.id, founder ?? false);
         // `founder` only flows from the explicit addStrand path — the control-discovered
         // join path never founds, so its rows arrive via sync (see handleStrandAdded).
-        return await this.launchStrand(strandRow, sAppConfig, mode, founder);
+        return await this.launchStrand(strandRow, sAppConfig, founder);
     }
     /**
      * Publish a strand row to the shared control database under this node's own
@@ -3081,8 +3251,8 @@ export class CadreNode {
     /**
      * Shared strand launch path for both the explicit (`addStrand`) and the
      * control-discovered (`handleStrandAdded`) entry points. Resolves the cohort
-     * seed, selects the mode, starts the strand, and registers it with the
-     * hibernation manager before emitting `strand:started`.
+     * seed, starts the strand, and registers it with the hibernation manager
+     * before emitting `strand:started`.
      *
      * Idempotent no-op when the strand manager already tracks `strand.Id` — the
      * ordinary founding sequence is `addStrand` (starts it locally) followed by
@@ -3093,7 +3263,7 @@ export class CadreNode {
      * instance that never stopped. The guard runs before the cohort-seed RPC
      * fan-out, so a rediscovery costs nothing beyond the map lookup.
      */
-    async launchStrand(strand, sAppConfig, explicitMode, founder) {
+    async launchStrand(strand, sAppConfig, founder) {
         const existing = this.strandManager.getInstance(strand.Id);
         if (existing) {
             log('launchStrand: strand %s already tracked locally — skipping re-launch', strand.Id);
@@ -3122,8 +3292,7 @@ export class CadreNode {
         // `libp2p.start()` (the responder records the grant before replying; the
         // client awaits the replies).
         const delegatePeerId = transportKey ? peerIdFromPrivateKey(transportKey).toString() : undefined;
-        const seed = await this.resolveCohortSeed(strand.Id, delegatePeerId);
-        const mode = selectStrandMode(explicitMode, seed.hasOtherPeers);
+        const bootstrapNodes = await this.resolveCohortSeed(strand.Id, delegatePeerId);
         const instance = await this.strandManager.startStrand({
             strandRow: strand,
             sAppConfig,
@@ -3132,30 +3301,37 @@ export class CadreNode {
             profile: this.config.profile,
             defaultLatencyHint: this.config.hibernation?.defaultLatencyHint ?? 'interactive',
             privateKey: transportKey,
-            bootstrapNodes: seed.bootstrapNodes,
-            mode,
+            bootstrapNodes,
             requireSignedSchemas: this.config.requireSignedSchemas,
             clusterSize: this.config.strandClusterSize,
             backfill: this.config.strandBackfill,
             founder
         });
+        // The seed reached the node as `bootstrapNodes`, which only enters the
+        // address book via @libp2p/bootstrap discovery. Merge it directly too, so a
+        // sibling is dialable by bare peer id from the first moment (see
+        // mergeStrandPeerAddrs; refreshStrandPeerAddrs keeps it warm from here on).
+        if (instance.libp2pNode) {
+            await this.mergeStrandPeerAddrs(instance.libp2pNode, bootstrapNodes, strand.Id);
+        }
         this.hibernationManager.trackStrand(instance);
         this.emit('strand:started', { strandId: strand.Id });
         return instance;
     }
     /**
-     * Resolve a strand's discovery seed. Membership (and thus mode) comes from the
-     * control network's CadrePeer rows; the **strand-network** bootstrap addresses
-     * are resolved on demand over the control mesh via the strand-addr RPC —
-     * deliberately NOT from `CadrePeer.Multiaddr`, which carries *control*
-     * addresses that must not seed the strand mesh.
+     * Resolve a strand's discovery seed — the dialable strand-network multiaddr
+     * strings for cohort siblings. Membership comes from the control network's
+     * CadrePeer rows; the **strand-network** bootstrap addresses are resolved on
+     * demand over the control mesh via the strand-addr RPC — deliberately NOT
+     * from `CadrePeer.Multiaddr`, which carries *control* addresses that must not
+     * seed the strand mesh.
      *
      * Only siblings we already hold an open control connection to are RPC'd: they
      * are the ones that can answer right now, and dialing them by peerId reuses the
      * live connection. When no connected sibling yet runs the strand the seed is
-     * empty (`[]`) — mode still follows membership, and the empty seed self-heals
-     * on the next resume / check-in pass. Returns an empty seed when the control DB
-     * or node is absent (not yet started / torn down).
+     * empty (`[]`) — the empty seed self-heals on the next resume / check-in pass.
+     * Returns an empty seed when the control DB or node is absent (not yet
+     * started / torn down).
      *
      * When `delegatePeerId` is given (a strand launch/resume is imminent), the
      * pass doubles as the delegate ANNOUNCEMENT: our circuit relays are merged
@@ -3170,16 +3346,9 @@ export class CadreNode {
      */
     async resolveCohortSeed(strandId, delegatePeerId) {
         if (!this.controlDatabase || !this.controlNode) {
-            return { bootstrapNodes: [], hasOtherPeers: false };
+            return [];
         }
-        const peers = await this.controlDatabase.queryCadrePeers();
-        const { otherPeerIds, hasOtherPeers } = deriveCohortMembers(peers, this.controlNode.peerId.toString());
-        // RPC only siblings we already have a control connection to — they can answer
-        // now, and `dialProtocol` by peerId reuses the open connection.
-        const connected = new Set(this.controlNode.getConnections().map((c) => c.remotePeer.toString()));
-        const targets = otherPeerIds
-            .filter((id) => connected.has(id))
-            .map((peerId) => ({ peerId }));
+        const targets = await this.connectedSiblingTargets();
         const relays = delegatePeerId === undefined ? [] : this.circuitRelayTargets();
         for (const relay of relays) {
             if (!targets.some((t) => t.peerId === relay.relayPeerId)) {
@@ -3192,7 +3361,48 @@ export class CadreNode {
         // Throttle state for the RELAY targets only — refreshDelegateGrants never
         // looks up a sibling key, so recording one would only be dead weight.
         this.recordDelegateAnnounces(relays.map((r) => r.relayPeerId), strandId);
-        return { bootstrapNodes, hasOtherPeers };
+        return bootstrapNodes;
+    }
+    /**
+     * The co-cadre siblings worth sending a strand-addr RPC to right now: cohort
+     * members (self excluded) we already hold an open control connection to. They
+     * are the ones that can answer immediately, and dialing them by peerId reuses
+     * the live connection instead of opening a second one.
+     *
+     * Shared by {@link resolveCohortSeed} (launch/resume) and
+     * {@link refreshStrandPeerAddrs} (the periodic pass) so both ask the same set.
+     * Empty when the control DB or node is absent (not yet started / torn down).
+     *
+     * The read below is issued even when the node holds no control connection and
+     * the answer is therefore empty by construction. That is deliberate on the
+     * launch path: `control-database-solo-warm-start.spec.ts` exists to prove this
+     * exact read does not stall as an embedder's FIRST awaited control operation,
+     * on a warm cohort no one can reach. A caller that re-enters often enough for
+     * the read to matter should skip the call itself, as
+     * {@link refreshStrandPeerAddrs} does.
+     *
+     * NOTE: this read is UNBOUNDED and sits on the critical path an embedding app
+     * awaits during startup — `addStrand` cannot resolve until it does, and it is
+     * the first control operation an embedder's boot order issues (before genesis,
+     * before seed bootstrap). Measured fine today: the warm-start-alone shape a
+     * report pointed at — a `CadrePeer` list naming peers that are all gone, read
+     * off real files after a restart — completes in milliseconds, and
+     * `control-database-solo-warm-start.spec.ts` covers it under a deadline. If a
+     * control read ever CAN stall (a transactor change that consults the network
+     * for a local row, a storage backend with blocking I/O), give this one a
+     * timeout — and decide then whether the breach fails `addStrand` or degrades
+     * to an empty seed, because those promise callers different things.
+     */
+    async connectedSiblingTargets() {
+        const controlNode = this.controlNode;
+        if (!this.controlDatabase || !controlNode) {
+            return [];
+        }
+        const peers = await this.controlDatabase.queryCadrePeers();
+        const connected = new Set(controlNode.getConnections().map((c) => c.remotePeer.toString()));
+        return deriveCohortMembers(peers, controlNode.peerId.toString())
+            .filter((id) => connected.has(id))
+            .map((peerId) => ({ peerId }));
     }
     /**
      * The circuit relays this node's strand nodes would reserve through: the
@@ -3277,6 +3487,157 @@ export class CadreNode {
         await collectStrandAddrs(controlNode, due.map(relayStrandAddrPeer), strandId, { delegatePeerId });
         this.recordDelegateAnnounces(due.map((relay) => relay.relayPeerId), strandId, now);
     }
+    /**
+     * Re-resolve each running strand's SIBLING addresses over the control mesh and
+     * merge them into that strand's own libp2p address book, throttled to once per
+     * {@link STRAND_PEER_ADDR_REFRESH_MS} per strand.
+     *
+     * Without this, a strand's address book is written exactly once — the
+     * launch/resume seed — and everything below cadre-core that dials a strand peer
+     * by bare peer id (Optimystic's cluster and repo clients, FRET ping/announce)
+     * loses its address for any sibling it is not currently connected to: a sibling
+     * that restarted its strand node or rotated its relay reservation is never
+     * re-resolved, and even the original seed addresses fall off at the peerStore's
+     * one-hour expiry (see `peer-addr-book.ts`).
+     *
+     * Distinct from {@link refreshDelegateGrants}, deliberately: that pass covers
+     * RELAYS on a `DELEGATE_GRANT_TTL_MS / 2` throttle to keep circuit-relay
+     * admission grants alive, this one covers SIBLINGS on an address-expiry
+     * throttle to keep the address book warm. They overlap only in that both carry
+     * `delegatePeerId`, so a sibling that also runs a relay gets its grant
+     * refreshed here as a side effect. Merging them would tie an admission-grant
+     * TTL to an address-expiry window that has nothing to do with it.
+     *
+     * Strands refresh CONCURRENTLY, like `refreshDelegateGrants`, so one
+     * unreachable sibling's dial timeout does not stack up per strand.
+     */
+    async refreshStrandPeerAddrs(now = Date.now()) {
+        if (!this._running || !this.controlNode) {
+            return;
+        }
+        // A hibernating / quiescing strand has no node to seed, so it is not running
+        // for this pass's purposes even though its instance is still tracked.
+        const running = new Set();
+        for (const [strandId, instance] of this.strandManager.getInstances()) {
+            if (instance.libp2pNode) {
+                running.add(strandId);
+            }
+        }
+        // Drop stamps for strands no longer running: the map must not grow for the
+        // node's lifetime, and a resumed strand should refresh immediately rather
+        // than inherit the stamp its previous incarnation left.
+        for (const strandId of this.strandPeerAddrRefreshAt.keys()) {
+            if (!running.has(strandId)) {
+                this.strandPeerAddrRefreshAt.delete(strandId);
+            }
+        }
+        const refreshMs = this.config.network?.controlCohort?.strandAddrRefreshMs ?? STRAND_PEER_ADDR_REFRESH_MS;
+        const due = [...running].filter((strandId) => now - (this.strandPeerAddrRefreshAt.get(strandId) ?? 0) >= refreshMs);
+        if (due.length === 0) {
+            return;
+        }
+        // A due strand with nobody to ask leaves its throttle unstamped (see below),
+        // so this pass re-enters on EVERY 15 s reconcile tick for as long as the node
+        // is alone — which is the steady state of a solo node running a strand.
+        // `connectedSiblingTargets`' membership read is unbounded, and with zero
+        // connections its answer is empty whatever the table holds, so decide it here
+        // from the connection list instead of paying for the read once a tick.
+        if (this.controlNode.getConnections().length === 0) {
+            return;
+        }
+        // NOTE: one strand-addr RPC per (due strand × connected sibling) per refresh
+        // interval — each a tiny request/response on an already-open control
+        // connection. If a node ever runs MANY strands at once, batch the RPC to
+        // carry several strand ids per request rather than one fan-out per strand.
+        const targets = await this.connectedSiblingTargets().catch((error) => {
+            log('refreshStrandPeerAddrs: sibling enumeration failed (skipping pass): %o', error);
+            return [];
+        });
+        // No sibling to ask (or a shutdown landed mid-enumeration): leave every stamp
+        // untouched so the next reconcile tick retries, rather than sitting out the
+        // whole refresh interval having asked nobody.
+        if (targets.length === 0 || !this._running || !this.controlNode) {
+            return;
+        }
+        await Promise.all(due.map((strandId) => this.refreshOneStrandPeerAddrs(strandId, targets, now)));
+    }
+    /**
+     * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings, then
+     * merge their answers into this strand's address book. Errors are logged and
+     * swallowed so one strand's failure never costs the others their refresh.
+     */
+    async refreshOneStrandPeerAddrs(strandId, targets, now) {
+        const controlNode = this.controlNode;
+        const strandNode = this.strandManager.getInstance(strandId)?.libp2pNode;
+        if (!controlNode || !strandNode) {
+            return;
+        }
+        try {
+            // The running strand node's own peerId is the delegate to announce — see
+            // the relationship note on refreshStrandPeerAddrs.
+            const addrs = await collectStrandAddrs(controlNode, [...targets], strandId, {
+                delegatePeerId: strandNode.peerId.toString()
+            });
+            // Stamped on the RPC having happened, not on its answer: the fan-out is
+            // what the throttle exists to bound, and an all-empty round is a normal
+            // steady state for a strand no connected sibling currently runs.
+            this.strandPeerAddrRefreshAt.set(strandId, now);
+            // Re-read the instance after the await — a strand stopped mid-pass (or one
+            // already restarted onto a new node) must never have its store written to.
+            if (!this._running || this.strandManager.getInstance(strandId)?.libp2pNode !== strandNode) {
+                return;
+            }
+            await this.mergeStrandPeerAddrs(strandNode, addrs, strandId);
+        }
+        catch (error) {
+            log('refreshStrandPeerAddrs: strand %s refresh failed (continuing): %o', strandId, error);
+        }
+    }
+    /**
+     * Merge strand-network addresses into ONE strand node's libp2p address book,
+     * attributed per peer. Best-effort throughout: an address-book write must never
+     * fail a launch, a resume, or a reconcile pass.
+     *
+     * `addrs` is the peer-agnostic union the strand-addr RPC returns, so
+     * {@link groupAddrsByPeerId} attributes each entry to the **strand transport**
+     * peerId in its final `/p2p/` component — never the sibling's control peerId,
+     * which names a different libp2p node entirely. Entries that name no peer are
+     * dropped there and counted here, once per pass.
+     *
+     * NOTE: a member could answer with arbitrary multiaddrs bound to arbitrary peer
+     * ids and poison this address book. That is the same exposure the launch-time
+     * `bootstrapNodes` seeding already accepts, and the cost is bounded: an address
+     * grants no authority, the dialed peer authenticates by peer id at the
+     * handshake, and a bad entry costs one failed dial that ages out at the
+     * peerStore's one-hour expiry. No new gating here — cross-party strand trust is
+     * `backlog/strand-network-nat-relay-reachability`.
+     */
+    async mergeStrandPeerAddrs(strandNode, addrs, strandId) {
+        const counts = { merged: 0, restamped: 0, skipped: 0, failed: 0 };
+        let grouped = 0;
+        let peers = 0;
+        try {
+            const groups = groupAddrsByPeerId(addrs);
+            peers = groups.size;
+            const selfId = strandNode.peerId.toString();
+            for (const [peerId, peerAddrs] of groups) {
+                grouped += peerAddrs.length;
+                // We never RPC ourselves, so self should never appear — belt and braces:
+                // a node must not write its own addresses into its own address book.
+                if (peerId === selfId) {
+                    continue;
+                }
+                counts[await mergePeerAddrs(strandNode, peerId, peerAddrs)]++;
+            }
+        }
+        catch (error) {
+            // `mergePeerAddrs` folds its own failures, so reaching here means the node
+            // itself is unusable (torn down mid-merge). Never fail a launch/resume or a
+            // reconcile pass over an address book.
+            log('strand %s address book merge failed (continuing): %o', strandId, error);
+        }
+        log('strand %s address book merged (peers=%d, merged=%d, restamped=%d, skipped=%d, failed=%d, dropped=%d)', strandId, peers, counts.merged, counts.restamped, counts.skipped, counts.failed, addrs.length - grouped);
+    }
     /**
      * The local strand instance's dialable strand-network multiaddrs for the
      * strand-addr RPC, ordered signaling-first (reusing the control node's