@serfab/cadre-core 0.7.1 → 0.9.0

package/dist/cadre-node.js

@@ -1,15 +1,38 @@
 import debug from 'debug';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { generateKeyPair, privateKeyToProtobuf, privateKeyFromProtobuf } from '@libp2p/crypto/keys';
+import { peerIdFromString } from '@libp2p/peer-id';
 import { createLibp2pNode } from '@optimystic/db-p2p';
+import { multiaddr } from '@multiformats/multiaddr';
+import { DEFAULT_CHECKIN_WINDOW_MS } from './types.js';
+import { sign } from '@optimystic/quereus-plugin-crypto';
+import { ed25519KeyPairFromLibp2p } from './ed25519-key.js';
+import { DEFAULT_IDENTITY_KEY_ID } from './key-store.js';
+import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
+import { signPeerRecord, verifyPeerRecordSignature, isPeerRecordFresh, orderSignalingFirst, isSignalingAddr, 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 { EnrollmentService } from './enrollment.js';
 import { HibernationManager } from './hibernation-manager.js';
 import { ControlDatabase } from './control-database.js';
 import { SeedBootstrapService } from './seed-bootstrap.js';
 import { StrandSolicitationService } from './strand-solicitation.js';
+import { StrandWakeService, dialWake } from './strand-wake-protocol.js';
+import { StrandAddrService, collectStrandAddrs } from './strand-addr-protocol.js';
+import { PushFanoutService } from './push-fanout.js';
+import { summarizeConnectionPaths, classifyTransport } from './diagnostics/connection-path.js';
+import { TurnRelayTracker } from './diagnostics/webrtc-turn-tracker.js';
 const log = debug('sereus:cadre:node');
 const timing = debug('sereus:cadre:timing');
+/**
+ * Window (ms) within which a queued TURN-relay settlement is correlated to a
+ * `connection:open`. Generous relative to the tight async gap between an
+ * `RTCPeerConnection` reaching `connected` and libp2p surfacing the connection.
+ */
+const TURN_CONSUME_WINDOW_MS = 1000;
 /**
  * CadreNode is the main entry point for a cadre member.
  * It manages:
@@ -26,10 +49,125 @@ export class CadreNode {
         this.strandWatcher = null;
         this.seedBootstrapService = null;
         this.strandSolicitationService = null;
-        this.running = false;
+        this.strandWakeService = null;
+        /**
+         * Control-network strand-address responder. Answers a co-cadre sibling's
+         * on-demand request for this node's live strand-network multiaddrs so the
+         * sibling can seed a strand mesh from us — the read side of the seed path that
+         * stops conflating control addresses with strand seeding.
+         */
+        this.strandAddrService = null;
+        /**
+         * Server-side push-wake fan-out. Constructed by {@link start} only when
+         * `config.push` (an injected `PushNotifier` + policy) is present — without it
+         * the node behaves exactly as before (no notifier, no fan-out). Owns who/when
+         * to wake hibernating mobile peers on strand activity.
+         */
+        this.pushFanoutService = null;
+        /** Backing field for the {@link running} / {@link isRunning} getters. */
+        this._running = false;
+        /**
+         * In-flight {@link serviceWake} operations keyed by strandId. Coalesces
+         * concurrent on-demand wakes for the same strand into one runtime build + one
+         * window + one re-hibernate decision (a second caller joins the first's
+         * promise), complementing {@link HibernationManager}'s wake coalescing.
+         */
+        this.serviceWakePromises = new Map();
+        /**
+         * Live wake-window waiters (see {@link holdWakeWindow}). Tracked so
+         * {@link cleanup} can clear the timer AND resolve the promise on teardown — a
+         * window must never fire (or hang an in-flight serviceWake) after stop().
+         */
+        this.windowWaiters = new Set();
         this.eventHandlers = new Map();
         /** Map of strandId -> sAppConfig for sAppId filtering and management */
         this.sAppConfigs = new Map();
+        /**
+         * Most-recently pushed invite addresses (see {@link setInviteAddresses}).
+         * When non-null these take priority over `libp2pNode.getMultiaddrs()` when
+         * minting invites — the host pushes NAT-resolved addresses here so the
+         * control-network node never needs to dial back to the manager.
+         */
+        this.latestInviteAddresses = null;
+        /** Initial self-registration timer (see {@link scheduleSelfRegistration}). */
+        this.selfRegistrationTimer = null;
+        /** TTL heartbeat that re-publishes the self record before it goes stale. */
+        this.recordRefreshTimer = null;
+        /** Listener that re-publishes the self record when reachable addresses change. */
+        this.selfPeerUpdateHandler = null;
+        /**
+         * Recurring proactive control-cohort dial cadence (see
+         * {@link reconcileControlCohort}). Wired alongside {@link recordRefreshTimer}
+         * in {@link startRecordRefresh} and torn down symmetrically in
+         * {@link stopRecordRefresh}; `.unref()`'d so it never keeps the loop alive.
+         */
+        this.controlCohortReconcileTimer = null;
+        /**
+         * Single-flight guard for {@link reconcileControlCohort}. The eager start pass,
+         * the recurring interval, and the `self:peer:update` trigger can fire close
+         * together; collapsing concurrent passes into one in-flight run prevents two
+         * passes from double-dialing the same siblings (mirrors {@link registerSelfInFlight}).
+         */
+        this.reconcileControlCohortInFlight = null;
+        /**
+         * Single-flight guard for {@link registerSelf}. Concurrent callers (the explicit
+         * CLI `--owner` publish, the 1s startup timer, the TTL heartbeat, and the
+         * address-change listener) share one in-flight publish so two of them can never
+         * both read "no row yet" and race a duplicate INSERT (a `CadrePeer` PK conflict).
+         */
+        this.registerSelfInFlight = null;
+        // ── Write-while-alone re-replication (control-write-ensure-replicated) ──────
+        /**
+         * Re-replication queue for owner control writes that committed while this
+         * node was alone — `controlNode.getConnections().length === 0` at write time
+         * means the Optimystic commit was local-only (the block's cluster was ≤1) and
+         * never broadcast. Maps the affected subject peerId → the write to re-issue once
+         * the cohort grows. A later op for the same subject overwrites an earlier one
+         * (authorize then remove → remove wins). Drained on the 0→≥1 control-connection
+         * transition by {@link drainPendingControlReplication}.
+         */
+        this.pendingPeerWrites = new Map();
+        /** This node's own `CadrePeer` self-write committed local-only (re-touched on growth). */
+        this.pendingSelfPeerWrite = false;
+        /** This node's own `DeviceToken` self-write committed local-only (re-touched on growth). */
+        this.pendingSelfDeviceWrite = false;
+        /**
+         * Guards the one-shot, first-cohort-growth reconstruction: an owner re-touches
+         * every membership row it may have authored that could be unreplicated (covering
+         * writes made before this process started, which the in-memory queue cannot know).
+         * Set true after the first drain so later passes only drain the in-memory queue.
+         */
+        this.reconstructedLocalOnlyWrites = false;
+        /** Single-flight guard for the re-replication drain (mirrors {@link registerSelfInFlight}). */
+        this.drainControlReplicationInFlight = null;
+        /**
+         * Tracks the control-connection presence edge so the drain fires only on the
+         * 0→≥1 transition (the earliest point a re-issue can broadcast), not on every
+         * subsequent `connection:open`. Re-armed to false once connections return to 0.
+         */
+        this.hasControlConnection = false;
+        /** `connection:open` listener driving the growth-triggered drain (teardown in {@link stopRecordRefresh}). */
+        this.controlConnectionOpenHandler = null;
+        /** `connection:close` listener re-arming the growth edge (teardown in {@link stopRecordRefresh}). */
+        this.controlConnectionCloseHandler = null;
+        // ── WebRTC TURN-relay detection (turn-relayed-path-metrics) ─────────────────
+        /**
+         * Hooks `globalThis.RTCPeerConnection` to observe whether ICE selected a TURN
+         * relay candidate for each WebRTC session. Installed in {@link start}, disposed
+         * in {@link cleanup}; inert on Node.js (no `RTCPeerConnection`).
+         */
+        this.turnTracker = new TurnRelayTracker();
+        /**
+         * Peer IDs whose current WebRTC connection was observed to be TURN-relayed.
+         * Populated by {@link handleTurnConnectionOpen} (drains the tracker queue on a
+         * `/webrtc` `connection:open`), cleared per-peer on `connection:close`. Read by
+         * {@link getConnectionPaths} to promote `webrtc` → `webrtc-turn` (relayed).
+         */
+        this.turnRelayedPeers = new Set();
+        /** `connection:open` listener feeding TURN detection (teardown in {@link stopRecordRefresh}). */
+        this.turnConnectionOpenHandler = null;
+        /** `connection:close` listener clearing a peer's TURN flag (teardown in {@link stopRecordRefresh}). */
+        this.turnConnectionCloseHandler = null;
         this.config = config;
         this.strandManager = new StrandInstanceManager();
         this.enrollmentService = new EnrollmentService();
@@ -37,7 +175,8 @@ export class CadreNode {
         const hibernationCallbacks = {
             onIdle: async (strandId) => this.handleStrandIdle(strandId),
             onHibernate: async (strandId) => this.handleStrandHibernate(strandId),
-            onWake: async (strandId) => this.handleStrandWake(strandId)
+            onWake: async (strandId) => this.handleStrandWake(strandId),
+            onCheckIn: async (strandId) => this.handleStrandCheckIn(strandId)
         };
         this.hibernationManager = new HibernationManager(config.hibernation ?? { enabled: false }, hibernationCallbacks);
         log('CadreNode created for party: %s', config.controlNetwork.partyId);
@@ -54,6 +193,12 @@ export class CadreNode {
     get peerId() {
         return this.controlNode?.peerId;
     }
+    /**
+     * The party ID this node serves (control-network identity).
+     */
+    get partyId() {
+        return this.config.controlNetwork.partyId;
+    }
     /**
      * Get the multiaddrs of this node (available after start)
      */
@@ -66,7 +211,49 @@ export class CadreNode {
      * Check if the node is running
      */
     get isRunning() {
-        return this.running;
+        return this._running;
+    }
+    /**
+     * Synchronous lifecycle snapshot for headless callers (a mobile
+     * `BackgroundRunner` that boots in a background task and must *query* state
+     * rather than subscribe to `control:connected`/`control:disconnected`).
+     * Equivalent to {@link isRunning}.
+     */
+    get running() {
+        return this._running;
+    }
+    /**
+     * Synchronous readiness snapshot: whether the control network is currently
+     * connected (the node is running and its control-network libp2p node is up).
+     * Tracks the same edge the `control:connected`/`control:disconnected` events
+     * announce, but pollable.
+     */
+    get controlConnected() {
+        return this._running && this.controlNode !== null;
+    }
+    /**
+     * Classify every open control-network connection as relayed
+     * (`/p2p-circuit`) vs direct, tag its transport, and summarise counts plus a
+     * stuck-on-relay condition. Pure, read-only snapshot over
+     * `controlNode.getConnections()`. Returns an empty (all-zero) summary when
+     * the node has not been started.
+     *
+     * @param settleWindowMs - grace period before a relayed connection with no
+     *   direct sibling is considered stuck (default 10_000ms)
+     */
+    getConnectionPaths(settleWindowMs) {
+        const conns = this.controlNode?.getConnections() ?? [];
+        // Annotate each connection with the TURN-relay hint so a WebRTC session whose
+        // ICE selected a TURN candidate classifies as relayed/webrtc-turn rather than
+        // direct/webrtc (the multiaddr alone cannot reveal it).
+        const annotated = conns.map((c) => ({
+            remotePeer: c.remotePeer,
+            remoteAddr: c.remoteAddr,
+            direction: c.direction,
+            timeline: c.timeline,
+            turnRelayed: this.turnRelayedPeers.has(c.remotePeer.toString()),
+        }));
+        return summarizeConnectionPaths(annotated, settleWindowMs);
     }
     /**
      * Get all strand instances
@@ -90,13 +277,21 @@ export class CadreNode {
      * Start the cadre node
      */
     async start() {
-        if (this.running) {
+        if (this._running) {
             log('CadreNode already running');
             return;
         }
         log('Starting CadreNode for party: %s', this.config.controlNetwork.partyId);
         try {
             const tTotal = performance.now();
+            // Install the WebRTC TURN-relay tracker BEFORE any libp2p bring-up, so it
+            // wraps globalThis.RTCPeerConnection before the control node can create one.
+            // Inert on Node.js (no RTCPeerConnection); disposed in cleanup().
+            this.turnTracker.install();
+            // Resolve the node identity (keyStore | privateKey | ephemeral) BEFORE any
+            // libp2p/network bring-up, so a misconfiguration or an access-denied secure
+            // store fails closed before a node is created.
+            await this.resolveIdentityKey();
             // Create the control network libp2p node
             let t0 = performance.now();
             this.controlNode = await this.createControlNode();
@@ -131,10 +326,38 @@ export class CadreNode {
             timing('[start] strandWatcher.start: %dms', Math.round(performance.now() - t0));
             // Start hibernation manager
             this.hibernationManager.start();
-            this.running = true;
+            // Register the control-network push-wake receiver: a same-cadre peer can
+            // signal us to bring a hibernating strand online. Gated on AUTHORIZED
+            // membership (not the addressable surface); the wake routes through the same
+            // path as a local wake.
+            this.strandWakeService = new StrandWakeService({
+                isMember: (peerId) => this.isAuthorizedMember(peerId),
+                getStrand: (strandId) => this.strandManager.getInstance(strandId),
+                wake: (strandId) => this.wakeStrand(strandId),
+            });
+            this.strandWakeService.initialize(this.controlNode);
+            // Register the control-network strand-address responder: a same-cadre peer
+            // resolving a strand's bootstrap seed asks us for our live strand-network
+            // multiaddrs (its CadrePeer row only knows our *control* address). Gated on
+            // AUTHORIZED membership; answers only for strands we are actively meshing.
+            this.strandAddrService = new StrandAddrService({
+                isMember: (peerId) => this.isAuthorizedMember(peerId),
+                getStrandMultiaddrs: (strandId) => this.getStrandMultiaddrs(strandId),
+            });
+            this.strandAddrService.initialize(this.controlNode);
+            // Server-side push-wake fan-out: only when push is configured.
+            if (this.config.push) {
+                this.pushFanoutService = this.buildPushFanout(this.config.push);
+                log('Push-wake fan-out enabled (injected notifier)');
+            }
+            this._running = true;
             this.emit('control:connected', undefined);
             timing('[start] total: %dms', Math.round(performance.now() - tTotal));
             log('CadreNode started successfully');
+            // Wire the control-connection growth listeners immediately (not via the
+            // delayed refresh path) so no early `connection:open` is missed — the
+            // write-while-alone re-replication drain must fire on the first 0→≥1 edge.
+            this.wireControlConnectionListeners();
             // Schedule self-registration in background
             this.scheduleSelfRegistration();
         }
@@ -144,17 +367,42 @@ export class CadreNode {
             throw error;
         }
     }
+    /**
+     * Build the server-side push-wake fan-out over an injected {@link PushNotifier}.
+     *
+     * The notifier reaches for `node:http2`/`node:crypto`, so the cross-platform
+     * core never constructs it — the Node host builds it from
+     * `@serfab/cadre-core/push-node` and passes the instance in
+     * `CadreNodeConfig.push`. This node owns that instance's lifecycle from here:
+     * {@link cleanup} closes the fan-out, which closes the notifier (freeing the
+     * APNs HTTP/2 session). Every other primitive the fan-out needs (member
+     * enumeration, participation, direct dial, token resolve/expire) is an
+     * import-clean closure over this node.
+     */
+    buildPushFanout(push) {
+        return new PushFanoutService({
+            listMembers: () => this.listMembers(),
+            getStrand: (strandId) => this.strandManager.getInstance(strandId),
+            selfPeerId: () => this.controlNode?.peerId.toString(),
+            pushWake: (peerId, strandId, reason) => this.pushWake(peerId, strandId, reason),
+            resolveDeviceToken: (peerId) => this.resolveDeviceToken(peerId),
+            expireDeviceToken: (peerId) => this.expireDeviceToken(peerId),
+            notifier: push.notifier,
+            cooldownMs: push.cooldownMs,
+            debounceMs: push.debounceMs,
+        });
+    }
     /**
      * Stop the cadre node
      */
     async stop() {
-        if (!this.running) {
+        if (!this._running) {
             log('CadreNode not running');
             return;
         }
         log('Stopping CadreNode');
         await this.cleanup();
-        this.running = false;
+        this._running = false;
         this.emit('control:disconnected', undefined);
         log('CadreNode stopped');
     }
@@ -183,8 +431,58 @@ export class CadreNode {
             }
         });
     }
+    /**
+     * Resolve the node identity into {@link identityKey} exactly once, fail-closed,
+     * before any network bring-up. Resolution order:
+     *
+     * 1. Both `keyStore` and `privateKey` set ⇒ configuration error (throws).
+     * 2. `keyStore` set ⇒ load protobuf bytes from `identityKeyId` (default
+     *    {@link DEFAULT_IDENTITY_KEY_ID}). Found ⇒ deserialize; empty ⇒ generate a
+     *    fresh Ed25519 key, persist it, and use it. A rejected `get` (access denied
+     *    / backend failure) PROPAGATES — we never generate a new key on a read
+     *    error, which would silently orphan the real identity.
+     * 3. `privateKey` set ⇒ use it directly.
+     * 4. Neither ⇒ leave undefined; libp2p generates an ephemeral key.
+     *
+     * Idempotent: a second call (or a stop()→start() cycle) reuses the already
+     * resolved key rather than regenerating or re-persisting.
+     */
+    async resolveIdentityKey() {
+        if (this.identityKey) {
+            return;
+        }
+        const { keyStore, privateKey, identityKeyId } = this.config;
+        if (keyStore && privateKey) {
+            throw new Error('CadreNodeConfig: `keyStore` and `privateKey` are mutually exclusive — ' +
+                'configure at most one source for the node identity');
+        }
+        if (keyStore) {
+            const keyId = identityKeyId ?? DEFAULT_IDENTITY_KEY_ID;
+            // A rejection here (e.g. KeyStoreAccessError) must propagate — do NOT fall
+            // through to generation, which would orphan an existing but unreadable key.
+            const bytes = await keyStore.get(keyId);
+            if (bytes) {
+                // Corrupt/garbage bytes throw here; surface loudly rather than
+                // regenerating (which would orphan the real identity).
+                this.identityKey = privateKeyFromProtobuf(bytes);
+                log('Identity key loaded from key store (slot present)');
+                return;
+            }
+            const generated = await generateKeyPair('Ed25519');
+            await keyStore.set(keyId, privateKeyToProtobuf(generated));
+            this.identityKey = generated;
+            log('Identity key generated and persisted to key store (first run)');
+            return;
+        }
+        if (privateKey) {
+            this.identityKey = privateKey;
+            return;
+        }
+        // Neither configured: libp2p generates an ephemeral key internally.
+    }
     async createControlNode() {
-        const { controlNetwork, network, storage, profile, privateKey } = this.config;
+        const { controlNetwork, network, storage, profile } = this.config;
+        const identityKey = this.identityKey;
         // 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');
@@ -205,9 +503,10 @@ export class CadreNode {
             clusterSize: 3,
             clusterPolicy: { allowDownsize: true, sizeTolerance: 0.5 },
             arachnode: { enableRingZulu: this.config.profile === 'storage' },
-            ...(privateKey && { privateKey }),
+            ...(identityKey && { privateKey: identityKey }),
             ...(network?.transports && { transports: network.transports }),
-            ...(network?.listenAddrs && { listenAddrs: network.listenAddrs })
+            ...(network?.listenAddrs && { listenAddrs: network.listenAddrs }),
+            ...(network?.connectionGater && { connectionGater: network.connectionGater })
         };
         return await createLibp2pNode(nodeOptions);
     }
@@ -224,74 +523,1007 @@ export class CadreNode {
         };
     }
     /**
-     * Schedule self-registration in the CadrePeer table.
-     * This runs as a background task after the node is started.
+     * Schedule the node's initial self-record publish + ongoing refresh shortly
+     * after start (non-blocking). {@link registerSelf} is idempotent and safely
+     * no-ops when it cannot yet sign/insert (e.g. owner key not installed),
+     * so the timer is harmless even when registration only becomes possible later.
      */
     scheduleSelfRegistration() {
-        // Run in background - don't block start()
-        setTimeout(async () => {
+        this.selfRegistrationTimer = setTimeout(() => {
+            void (async () => {
+                try {
+                    await this.registerSelf();
+                }
+                catch (error) {
+                    // Background task — a failed publish must not crash the node.
+                    log('Self-registration failed: %o', error);
+                }
+                // Wire the ongoing refresh + control-cohort reconcile cadence, then run
+                // an eager reconcile pass once the node has settled (the recurring
+                // interval was just armed inside startRecordRefresh).
+                this.startRecordRefresh();
+                void this.reconcileControlCohort().catch((error) => log('Control-cohort reconcile (start) failed: %o', error));
+            })();
+        }, 1000); // Small delay to ensure node is fully started
+        // Node-only: don't keep the event loop alive solely for this timer.
+        this.selfRegistrationTimer?.unref?.();
+    }
+    /**
+     * Publish (or refresh) this node's own signed `CadrePeer` address record so
+     * other members can resolve its current signaling/relay multiaddrs from its
+     * PeerId alone. Public, awaitable, and idempotent.
+     *
+     * - Builds a `PeerAddressRecord` from the node's current dialable addrs
+     *   (signaling/`p2p-circuit` first), signed with the ed25519 key behind its
+     *   PeerId (the resolved node identity from `keyStore`/`config.privateKey`).
+     * - If the row already exists: a self-signed UPDATE bumping `UpdatedAt`.
+     * - If not, and the node is its own owner: an owner-signed INSERT that
+     *   also carries the self-signature.
+     * - Otherwise: logs and returns (a non-owner node with no row yet must
+     *   wait for an owner to insert it; it can then self-refresh).
+     *
+     * Safe to call repeatedly (heartbeat / address-change driven); each successful
+     * publish strictly increases `UpdatedAt`. Concurrent calls are collapsed into a
+     * single in-flight publish (see {@link registerSelfInFlight}) so the explicit
+     * startup publish and the background timers can never race a duplicate INSERT.
+     *
+     * @returns what the publish did — `inserted`, `refreshed`, or `skipped`.
+     */
+    async registerSelf() {
+        // Join an in-flight publish rather than starting a second one. Without this,
+        // the explicit CLI call and the 1s timer could both observe "no row yet" and
+        // both attempt the INSERT — the loser hits a CadrePeer PK conflict.
+        if (this.registerSelfInFlight) {
+            return this.registerSelfInFlight;
+        }
+        const op = this.publishSelfRecord();
+        this.registerSelfInFlight = op;
+        try {
+            return await op;
+        }
+        finally {
+            this.registerSelfInFlight = null;
+        }
+    }
+    /** The body of {@link registerSelf}; serialised by its single-flight guard. */
+    async publishSelfRecord() {
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            log('Cannot register self - node or database not initialized');
+            return 'skipped';
+        }
+        const signingKey = this.getSelfSigningKey();
+        if (!signingKey) {
+            log('registerSelf: no self-signing key available (node identity unavailable or not matching peerId); skipping');
+            return 'skipped';
+        }
+        const peerId = this.controlNode.peerId.toString();
+        const addrs = await this.collectSelfAddrs();
+        const existing = await this.controlDatabase.queryPeerRecord(peerId);
+        // Strictly increase UpdatedAt even on a same-millisecond re-publish.
+        const updatedAt = Math.max(Date.now(), (existing?.updatedAt ?? 0) + 1);
+        const record = signPeerRecord({ peerId, publicKey: signingKey.publicKeyB64, addrs, updatedAt }, signingKey.privateKeyB64);
+        if (existing) {
+            await this.controlDatabase.updateSelfPeerRecord(record);
+            if (this.committedAlone())
+                this.pendingSelfPeerWrite = true;
+            log('registerSelf: refreshed own CadrePeer record (updatedAt=%d, %d addrs)', updatedAt, addrs.length);
+            return 'refreshed';
+        }
+        if (this.seedBootstrapService) {
+            // First-time row: requires an owner signature (the node is its own
+            // owner). insertSelfPeerRecord throws if no owner key is present.
+            await this.seedBootstrapService.insertSelfPeerRecord(record);
+            if (this.committedAlone())
+                this.pendingSelfPeerWrite = true;
+            log('registerSelf: inserted own CadrePeer record (owner-signed, updatedAt=%d, %d addrs)', updatedAt, addrs.length);
+            return 'inserted';
+        }
+        log('registerSelf: not yet a CadrePeer member and no owner service to self-insert; skipping (an owner must add this peer first)');
+        return 'skipped';
+    }
+    /**
+     * The ed25519 keypair (base64url) the node signs its own record with — the key
+     * behind its libp2p PeerId. Sourced from the resolved {@link identityKey}
+     * (which a `keyStore` or `config.privateKey` supplies); returns null when
+     * absent (ephemeral identity) or (defensively) when it does not match the
+     * control node's PeerId, in which case self-publish is skipped rather than
+     * producing an unresolvable row.
+     */
+    getSelfSigningKey() {
+        const peerId = this.controlNode?.peerId.toString();
+        if (!peerId || !this.identityKey) {
+            return null;
+        }
+        try {
+            const { privateKeyB64, publicKeyB64 } = ed25519KeyPairFromLibp2p(this.identityKey);
+            if (publicKeyB64 === ed25519PublicKeyB64FromPeerId(peerId)) {
+                return { privateKeyB64, publicKeyB64 };
+            }
+            log('getSelfSigningKey: resolved identity key does not match control node peerId; cannot self-sign');
+        }
+        catch (error) {
+            // Logs the error shape only; ed25519KeyPairFromLibp2p never embeds key material.
+            log('getSelfSigningKey: failed to derive ed25519 key from identity key: %o', error);
+        }
+        return null;
+    }
+    /**
+     * The owner keypair (base64url Ed25519) derived from this node's resolved
+     * identity key. In the single-key reference model the owner signing key is
+     * *derived from* the node identity (see {@link ed25519KeyPairFromLibp2p}), so the
+     * same key material protected in a secure enclave backs both.
+     *
+     * Exposed so the hosting app retains control of owner genesis: cadre-core
+     * resolves + protects the identity, then the app sources this pair to drive
+     * `ensureOwnerKey(pub)` + `initializeSeedBootstrap(priv)` itself — cadre-core
+     * never silently runs genesis. A future separate-owner slot would return a
+     * distinct key here instead of the identity-derived one.
+     *
+     * @returns The base64url seed/public-key owner pair.
+     * @throws If called before {@link start} has resolved the identity, or when the
+     *   node runs on an ephemeral libp2p key (no `keyStore`/`privateKey` configured),
+     *   since that key is internal to libp2p and not exposed.
+     */
+    getIdentityOwnerKey() {
+        if (!this.identityKey) {
+            throw new Error('getIdentityOwnerKey: node identity not resolved — call start() first, and ' +
+                'configure `keyStore` or `privateKey` (an ephemeral libp2p identity exposes no owner key)');
+        }
+        return ed25519KeyPairFromLibp2p(this.identityKey);
+    }
+    /**
+     * Collect this node's current dialable addresses for publication, signaling
+     * (`/p2p-circuit`) first. Prefers the best invite/NAT-resolved set and folds
+     * in the relay/signaling address (the WebRTC dial input) when not already
+     * present.
+     */
+    async collectSelfAddrs() {
+        const resolved = await this.resolveInviteAddresses();
+        const relay = await this.getRelayAddress();
+        const merged = relay && !resolved.includes(relay) ? [...resolved, relay] : resolved;
+        return orderSignalingFirst([...new Set(merged)]);
+    }
+    /**
+     * Wire the ongoing self-record refresh: re-publish whenever libp2p reports an
+     * address change (relay reservation rotation, NAT change) and on a TTL
+     * heartbeat at half the freshness ceiling. Idempotent — repeated calls do not
+     * stack listeners/timers.
+     */
+    startRecordRefresh() {
+        if (!this.controlNode || this.recordRefreshTimer) {
+            return;
+        }
+        const republish = (reason) => {
+            void this.registerSelf().catch((error) => log('Record refresh (%s) failed: %o', reason, error));
+        };
+        const reconcile = (reason) => {
+            void this.reconcileControlCohort().catch((error) => log('Control-cohort reconcile (%s) failed: %o', reason, error));
+        };
+        // Address churn re-publishes the self record AND re-checks the control cohort:
+        // a relay-reservation rotation / NAT change can drop a sibling connection, so
+        // the next pass should re-observe and re-dial it.
+        this.selfPeerUpdateHandler = () => {
+            republish('self:peer:update');
+            reconcile('self:peer:update');
+        };
+        this.controlNode.addEventListener('self:peer:update', this.selfPeerUpdateHandler);
+        this.recordRefreshTimer = setInterval(() => republish('heartbeat'), DEFAULT_PEER_RECORD_HEARTBEAT_MS);
+        this.recordRefreshTimer?.unref?.();
+        const reconcileMs = this.config.network?.controlCohort?.reconcileMs ?? DEFAULT_CONTROL_COHORT_RECONCILE_MS;
+        this.controlCohortReconcileTimer = setInterval(() => reconcile('interval'), reconcileMs);
+        this.controlCohortReconcileTimer?.unref?.();
+        log('Record refresh wired (heartbeat=%dms, cohortReconcile=%dms)', DEFAULT_PEER_RECORD_HEARTBEAT_MS, reconcileMs);
+    }
+    /** Tear down the self-record refresh timers + listener (see {@link cleanup}). */
+    stopRecordRefresh() {
+        if (this.selfRegistrationTimer) {
+            clearTimeout(this.selfRegistrationTimer);
+            this.selfRegistrationTimer = null;
+        }
+        if (this.recordRefreshTimer) {
+            clearInterval(this.recordRefreshTimer);
+            this.recordRefreshTimer = null;
+        }
+        if (this.controlCohortReconcileTimer) {
+            clearInterval(this.controlCohortReconcileTimer);
+            this.controlCohortReconcileTimer = null;
+        }
+        if (this.controlNode) {
+            if (this.selfPeerUpdateHandler) {
+                this.controlNode.removeEventListener('self:peer:update', this.selfPeerUpdateHandler);
+            }
+            if (this.controlConnectionOpenHandler) {
+                this.controlNode.removeEventListener('connection:open', this.controlConnectionOpenHandler);
+            }
+            if (this.controlConnectionCloseHandler) {
+                this.controlNode.removeEventListener('connection:close', this.controlConnectionCloseHandler);
+            }
+            if (this.turnConnectionOpenHandler) {
+                this.controlNode.removeEventListener('connection:open', this.turnConnectionOpenHandler);
+            }
+            if (this.turnConnectionCloseHandler) {
+                this.controlNode.removeEventListener('connection:close', this.turnConnectionCloseHandler);
+            }
+        }
+        this.selfPeerUpdateHandler = null;
+        this.controlConnectionOpenHandler = null;
+        this.controlConnectionCloseHandler = null;
+        this.turnConnectionOpenHandler = null;
+        this.turnConnectionCloseHandler = null;
+        // Reset the write-while-alone re-replication state so a stop()→start() cycle
+        // re-arms the growth edge and re-runs the first-growth reconstruction. Any
+        // queued local-only writes are moot once the node is torn down; owner
+        // inserts are re-covered by reconstruction on the next start, and the
+        // (already-loudly-logged) delete gap is tracked for follow-up.
+        this.hasControlConnection = false;
+        this.reconstructedLocalOnlyWrites = false;
+        this.pendingPeerWrites.clear();
+        this.pendingSelfPeerWrite = false;
+        this.pendingSelfDeviceWrite = false;
+    }
+    /**
+     * Resolve a peer's current, signed, trust-checkable multiaddrs from only its
+     * PeerId — the transport-agnostic input a NAT-to-NAT WebRTC (or any) dial path
+     * consumes, with no copy/paste of a relayed dial string.
+     *
+     * Reads the peer's `CadrePeer` record and gates it through, in order:
+     *   1. record present (else `[]`),
+     *   2. `publicKey <-> peerId` binding (the stored key's libp2p identity must be
+     *      the requested peerId),
+     *   3. self-signature verifies against `publicKey`,
+     *   4. freshness — rejected once older than `maxAgeMs` (never a dead relay
+     *      reservation),
+     *   5. the pluggable trust gate (`opts.trustPolicy`).
+     * Survivors are returned signaling (`/p2p-circuit`) first, filtered to
+     * signaling-only when requested, as parsed `Multiaddr`s (unparsable addrs
+     * dropped). Any gate failure yields an empty array rather than throwing.
+     */
+    async resolvePeerAddrs(peerId, opts = {}) {
+        if (!this.controlDatabase) {
+            throw new Error('CadreNode must be started before resolving peer addrs');
+        }
+        const record = await this.controlDatabase.queryPeerRecord(peerId);
+        if (!record) {
+            log('resolvePeerAddrs: no record for %s', peerId);
+            return [];
+        }
+        // publicKey <-> peerId binding: the stored key must be the one embedded in
+        // the requested Ed25519 peer id (also rejects a non-Ed25519 / missing key).
+        if (!record.publicKey || ed25519PublicKeyB64FromPeerId(peerId) !== record.publicKey) {
+            log('resolvePeerAddrs: publicKey does not match peerId for %s', peerId);
+            return [];
+        }
+        // Self-signature over (peerId, addrs, updatedAt).
+        if (!verifyPeerRecordSignature(record)) {
+            log('resolvePeerAddrs: signature verification failed for %s', peerId);
+            return [];
+        }
+        // Freshness: never hand back a dead relay reservation.
+        const maxAgeMs = opts.maxAgeMs ?? DEFAULT_PEER_RECORD_MAX_AGE_MS;
+        if (!isPeerRecordFresh(record.updatedAt, maxAgeMs, Date.now())) {
+            log('resolvePeerAddrs: record for %s is stale (updatedAt=%d, maxAgeMs=%d)', peerId, record.updatedAt, maxAgeMs);
+            return [];
+        }
+        // Pluggable trust gate (defaults to current-member).
+        const trustPolicy = opts.trustPolicy ?? currentMemberTrustPolicy();
+        const trusted = await trustPolicy.evaluate({
+            peerId,
+            publicKey: record.publicKey,
+            partyId: this.partyId,
+            record,
+        });
+        if (!trusted) {
+            log('resolvePeerAddrs: trust policy rejected %s', peerId);
+            return [];
+        }
+        // Order signaling-first (the on-record order was what we verified above),
+        // optionally restrict to signaling addrs, then parse — dropping any addr
+        // that does not parse as a multiaddr.
+        let addrs = orderSignalingFirst(record.addrs);
+        if (opts.signalingOnly) {
+            addrs = addrs.filter(isSignalingAddr);
+        }
+        return this.parseMultiaddrs(addrs);
+    }
+    /** Parse multiaddr strings, dropping (and logging) any that fail to parse. */
+    parseMultiaddrs(addrs) {
+        const out = [];
+        for (const addr of addrs) {
             try {
-                await this.registerSelf();
+                out.push(multiaddr(addr));
             }
             catch (error) {
-                log('Self-registration failed: %o', error);
-                // Don't emit error event - this is a background task
-                // The node can still function without self-registration
+                log('resolvePeerAddrs: dropping unparsable multiaddr %s: %o', addr, error);
             }
-        }, 1000); // Small delay to ensure node is fully started
+        }
+        return out;
     }
+    // ============================================================================
+    // Proactive control-cohort dial
+    //
+    // The control collections only replicate once a party's nodes are
+    // transport-connected (so FRET seats each peer in the others' keyspace cohort)
+    // AND a write happens while that cohort has ≥2 members. There is no production
+    // mechanism that makes a party's control nodes actively connect to each other;
+    // the convergence test does it by hand with a manual dial(). reconcileControlCohort
+    // productionizes that: each node resolves its known siblings' control addresses
+    // and proactively dials a bounded, backbone-preferential set, re-observing and
+    // re-dialing dropped connections on each pass. See docs/architecture.md (Control
+    // Network) and control-cohort.ts for the selection policy.
+    // ============================================================================
     /**
-     * Register this peer in the CadrePeer table.
-     * This allows other cadre members to discover this node.
+     * Run one proactive control-cohort dial pass to keep this node connected to its
+     * cadre siblings (so the `CadreControl` collections form a replicating cohort).
+     * Public so the cohort-growth-driven re-replication path
+     * (`control-write-ensure-replicated`) and tests can trigger a pass on demand;
+     * normally driven by the eager start pass, the recurring interval, and
+     * `self:peer:update` (all wired in {@link startRecordRefresh}).
+     *
+     * Concurrent triggers collapse into a single in-flight pass
+     * (see {@link reconcileControlCohortInFlight}) so two passes never double-dial.
+     * Best-effort throughout: a failure to resolve/dial any one sibling is logged
+     * and the pass continues; the whole pass is a no-op when the node is alone.
      */
-    async registerSelf() {
-        if (!this.controlNode || !this.controlDatabase) {
-            log('Cannot register self - node or database not initialized');
+    async reconcileControlCohort() {
+        if (this.reconcileControlCohortInFlight) {
+            return this.reconcileControlCohortInFlight;
+        }
+        const op = this.runReconcileControlCohort();
+        this.reconcileControlCohortInFlight = op;
+        try {
+            await op;
+        }
+        finally {
+            this.reconcileControlCohortInFlight = null;
+        }
+    }
+    /** Body of {@link reconcileControlCohort}; serialised by its single-flight guard. */
+    async runReconcileControlCohort() {
+        // Shutdown / not-yet-started guard (mirrors publishSelfRecord). A pass that
+        // fires after stop() began must early-return rather than touch a torn-down node.
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            return;
+        }
+        const selfPeerId = this.controlNode.peerId.toString();
+        // 1. Enumerate known siblings. This membership read is itself a pull-on-read
+        //    that helps the CadrePeer table converge — a reader-only node converges
+        //    purely by these reads.
+        const members = await this.listMembers();
+        const siblings = members.filter((m) => m.peerId !== selfPeerId);
+        if (siblings.length === 0) {
+            // Genuinely alone (cold start with no rows, or a solo cadre): nothing to
+            // dial. Must not throw or busy-loop.
+            return;
+        }
+        // Re-guard after the await: a stop() may have raced the membership read.
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            return;
+        }
+        // 2. Classify backbone (owner) members and select a bounded dial set.
+        const ownerKeys = await this.controlDatabase.getOwnerKeys();
+        if (!this._running || !this.controlNode) {
+            return;
+        }
+        const targetDegree = this.config.network?.controlCohort?.targetDegree
+            ?? DEFAULT_CONTROL_COHORT_TARGET_DEGREE;
+        const { dials, cappedNonOwner } = selectControlCohortDials(siblings, ownerKeys, targetDegree);
+        if (cappedNonOwner > 0) {
+            // 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).
+        const connected = new Set(this.controlNode.getConnections().map((c) => c.remotePeer.toString()));
+        // 4. Resolve + dial each selected, not-yet-connected sibling, best-effort.
+        let dialed = 0;
+        for (const sibling of dials) {
+            if (!this._running || !this.controlNode) {
+                return;
+            }
+            if (connected.has(sibling.peerId)) {
+                continue;
+            }
+            if (await this.dialControlSibling(sibling)) {
+                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).
+     *
+     * 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.
+     */
+    async dialControlSibling(sibling) {
+        const controlNode = this.controlNode;
+        if (!controlNode) {
+            return false;
+        }
+        const addrs = await this.resolveControlDialAddrs(sibling.peerId);
+        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);
+            return true;
+        }
+        catch (error) {
+            log('reconcileControlCohort: dial of sibling %s failed (continuing): %o', sibling.peerId, error);
+            return false;
+        }
+    }
+    /**
+     * Resolve 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);
+        if (resolved.length > 0) {
+            return resolved;
+        }
+        return this.peerStoreAddrs(peerId);
+    }
+    /**
+     * Cold-start fallback: the libp2p peerStore multiaddrs for `peerId` (seeded by
+     * {@link SeedBootstrapService.applySeed}). Returns `[]` on a missing entry or any
+     * parse/lookup failure — never throws.
+     */
+    async peerStoreAddrs(peerId) {
+        if (!this.controlNode) {
+            return [];
+        }
+        try {
+            const peer = await this.controlNode.peerStore.get(peerIdFromString(peerId));
+            // Re-parse through the top-level multiaddr parser so the returned type matches
+            // resolvePeerAddrs (the peerStore bundles its own @multiformats/multiaddr copy).
+            return this.parseMultiaddrs(peer.addresses.map((a) => a.multiaddr.toString()));
+        }
+        catch (error) {
+            log('reconcileControlCohort: peerStore lookup for %s failed: %o', peerId, error);
+            return [];
+        }
+    }
+    // ============================================================================
+    // Write-while-alone re-replication (control-write-ensure-replicated)
+    //
+    // Optimystic's coordinator commits a control write WITHOUT broadcasting when the
+    // block's cluster has ≤1 member. An owner that authorizes/removes a peer or
+    // (re)publishes its own record while no sibling is connected therefore writes a
+    // row that exists ONLY in its local control DB — a sibling that connects later
+    // never observes it (pull-on-read routes to the block's cluster, which never
+    // learned of the write). reconcileControlCohort shrinks the alone window but
+    // cannot close it (a write in the instant before any sibling connects is still
+    // local-only). The remedy: detect "wrote while alone" (0 connections is a sound
+    // lower bound), queue the affected row, and RE-ISSUE the write once the cohort
+    // grows (0→≥1 connection), as an idempotent monotonic update that now broadcasts.
+    // See docs/architecture.md (Control Network → write-while-alone durability).
+    // ============================================================================
+    /**
+     * Whether a control write happening now would commit local-only. A sound lower
+     * bound is "no connected control peers": 0 connections ⇒ the block's cluster is
+     * ≤1 ⇒ Optimystic commits without broadcasting. This is the pragmatic proxy for
+     * the precise signal (the block's `getClusterSize`); it over-approximates safely
+     * — a connected-but-not-in-this-block's-cluster write may still be local-only and
+     * is caught by the cohort's periodic pull-on-read instead. Re-issuing an already-
+     * replicated row is harmless (an idempotent monotonic bump), so the coarse proxy
+     * is acceptable as the agreed first cut.
+     */
+    committedAlone() {
+        return (this.controlNode?.getConnections().length ?? 0) === 0;
+    }
+    /**
+     * Record (or clear) a just-committed owner membership write in the
+     * write-while-alone re-replication queue. If the control node had no connections
+     * at commit, the Optimystic write was local-only and must be re-issued once the
+     * cohort grows; otherwise the write replicated and any stale queue entry for this
+     * subject is dropped.
+     *
+     * A `remove` that commits alone is a security-relevant durability gap (a revoked
+     * peer may persist as a member elsewhere), so it is logged loudly — and, because
+     * a physical delete leaves no local trace to re-issue from, its on-growth
+     * re-issue is best-effort only (see {@link drainPendingPeerWrites}).
+     */
+    noteControlWrite(peerId, kind) {
+        if (!this.committedAlone()) {
+            this.pendingPeerWrites.delete(peerId);
+            return;
+        }
+        this.pendingPeerWrites.set(peerId, kind);
+        if (kind === 'remove') {
+            log('removePeer(%s) committed while ALONE (0 control connections): the deletion is ' +
+                'local-only, so a revoked peer may persist in the cohort until re-replication. The ' +
+                'on-growth re-issue is best-effort (a physical delete cannot be replayed without a ' +
+                'schema tombstone — see control-delete-while-alone-tombstone).', peerId);
+        }
+        else {
+            log('authorizePeer(%s) committed while alone (0 control connections); queued for ' +
+                're-replication on cohort growth', peerId);
+        }
+    }
+    /**
+     * Drain the write-while-alone re-replication queue: re-issue the writes that
+     * committed local-only now that the cohort can broadcast them. Public so the
+     * 0→≥1 growth trigger ({@link handleControlConnectionChange}) and tests can drive
+     * it; concurrent calls collapse into one in-flight drain
+     * ({@link drainControlReplicationInFlight}) so two growth signals never
+     * double-issue. Best-effort throughout — a per-row failure leaves that entry
+     * queued for the next growth rather than aborting the drain.
+     */
+    async drainPendingControlReplication(reason) {
+        if (this.drainControlReplicationInFlight) {
+            return this.drainControlReplicationInFlight;
+        }
+        const op = this.runDrainControlReplication(reason);
+        this.drainControlReplicationInFlight = op;
+        try {
+            await op;
+        }
+        finally {
+            this.drainControlReplicationInFlight = null;
+        }
+    }
+    /** Body of {@link drainPendingControlReplication}; serialised by its single-flight guard. */
+    async runDrainControlReplication(reason) {
+        // Shutdown / not-yet-started guard (mirrors runReconcileControlCohort).
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            return;
+        }
+        const firstGrowth = !this.reconstructedLocalOnlyWrites;
+        log('Draining control re-replication (reason=%s, firstGrowth=%s, pendingPeers=%d, self=%s, deviceToken=%s)', reason, firstGrowth, this.pendingPeerWrites.size, this.pendingSelfPeerWrite, this.pendingSelfDeviceWrite);
+        // 1. Self rows. On the first growth always re-touch (covers a self row carried
+        //    over from a prior process that committed local-only before this start);
+        //    afterwards only when a self-write-while-alone was recorded this session.
+        //    registerSelf is idempotent + single-flight, so this never races a
+        //    duplicate publish with the heartbeat republish.
+        if (firstGrowth || this.pendingSelfPeerWrite) {
+            await this.registerSelf().catch((error) => log('drain: registerSelf failed: %o', error));
+            this.pendingSelfPeerWrite = false;
+        }
+        if (firstGrowth || this.pendingSelfDeviceWrite) {
+            await this.retouchSelfDeviceToken();
+            this.pendingSelfDeviceWrite = false;
+        }
+        // 2. First growth: an owner reconstructs membership rows it may have
+        //    authored that never replicated (covers writes from before this process
+        //    started). Rows already tracked in the in-memory queue are handled by
+        //    step 3 — skipped here to avoid a double re-touch.
+        if (firstGrowth) {
+            this.reconstructedLocalOnlyWrites = true;
+            await this.reconstructAuthoredMembership();
+        }
+        // 3. In-session pending owner membership writes (authorize / remove).
+        await this.drainPendingPeerWrites();
+    }
+    /**
+     * Re-touch this node's own `DeviceToken` row (re-sign + bump `UpdatedAt` via
+     * {@link registerDeviceToken}) so a self device-token that committed local-only
+     * re-broadcasts on cohort growth. No-op when no row exists (nothing to
+     * re-replicate) or the stored platform is unknown. Best-effort — never throws to
+     * the drain.
+     */
+    async retouchSelfDeviceToken() {
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
             return;
         }
         const peerId = this.controlNode.peerId.toString();
-        const multiaddrs = this.controlNode.getMultiaddrs();
-        if (multiaddrs.length === 0) {
-            log('No multiaddrs available for self-registration');
-            return;
-        }
-        // Use the first available multiaddr (typically the one with the peer ID)
-        const multiaddr = multiaddrs[0].toString();
-        log('Registering self: peerId=%s, multiaddr=%s', peerId, multiaddr);
-        // TODO: This requires signing the update to satisfy the AuthorizedUpdate constraint
-        // For now, we log what would happen. Full implementation requires:
-        // 1. Either an authority key to authorize the insert
-        // 2. Or the peer's private key to sign the update
-        log('Self-registration requires authorization - skipping for now');
-        // const db = this.controlDatabase.getDatabase();
-        // await db.exec(
-        //   'insert or replace into CadrePeer (PeerId, Multiaddr) values (?, ?)',
-        //   [peerId, multiaddr]
-        // );
+        try {
+            const existing = await this.controlDatabase.queryDeviceToken(peerId);
+            if (!existing || !isPushPlatform(existing.platform)) {
+                return;
+            }
+            await this.registerDeviceToken(existing.platform, existing.token);
+        }
+        catch (error) {
+            log('drain: retouch self DeviceToken failed: %o', error);
+        }
+    }
+    /**
+     * One-shot, first-cohort-growth reconstruction of the write-while-alone queue for
+     * an OWNER node: re-touch every membership row that may be an unreplicated
+     * owner insert. A row is a candidate iff it is not self (handled by
+     * {@link registerSelf}), is not already tracked in the in-memory queue (handled by
+     * {@link drainPendingPeerWrites}), and carries no self-`Sig` yet (an
+     * owner-authored row the peer has not self-published — the only kind safe to
+     * bump without invalidating a self-signature). O(rows) on the small control
+     * tables; safe to over-apply (a monotonic owner bump on an already-replicated
+     * row is a no-op-equivalent).
+     *
+     * A node with no owner private key skips this entirely — it cannot re-sign
+     * rows for other peers, and rows it merely holds are not its to re-issue. DELETEs
+     * cannot be reconstructed here (a removed row leaves no local trace and the schema
+     * carries no tombstone) — see the delete-path note in {@link drainPendingPeerWrites}.
+     */
+    async reconstructAuthoredMembership() {
+        if (!this.controlDatabase || !this.controlNode) {
+            return;
+        }
+        if (!this.seedBootstrapService?.canAuthorize()) {
+            return;
+        }
+        const selfPeerId = this.controlNode.peerId.toString();
+        const members = await this.controlDatabase.queryCadrePeers();
+        let touched = 0;
+        for (const member of members) {
+            if (!this._running || !this.controlNode || !this.controlDatabase) {
+                return;
+            }
+            if (member.peerId === selfPeerId || this.pendingPeerWrites.has(member.peerId)) {
+                continue;
+            }
+            try {
+                const record = await this.controlDatabase.queryPeerRecord(member.peerId);
+                // Missing (raced a delete) or peer-owned (self-Sig present) → not ours to bump.
+                if (!record || record.sig) {
+                    continue;
+                }
+                await this.reissuePeerAuthorize(member.peerId, record.updatedAt);
+                touched++;
+            }
+            catch (error) {
+                log('drain: reconstruction re-touch of %s failed (continuing): %o', member.peerId, error);
+            }
+        }
+        if (touched > 0) {
+            log('drain: reconstructed %d owner-authored membership row(s) on first cohort growth', touched);
+        }
+    }
+    /**
+     * Drain the in-session write-while-alone queue: re-issue each pending owner
+     * membership write now that the cohort can broadcast it. Sequential (no fan-out)
+     * to avoid a thundering re-touch; an entry is cleared only on success, so a
+     * failure (or a still-alone re-commit) leaves it queued for the next growth.
+     *
+     * - `authorize`: re-issue as an idempotent monotonic owner UPDATE
+     *   ({@link reissuePeerAuthorize}). Skipped (and cleared) if the row vanished
+     *   (raced a delete) or now carries a self-`Sig` (the peer self-published and owns
+     *   its republish).
+     * - `remove` (security-relevant): a removePeer-while-alone physically removed the
+     *   row locally, so a re-issued DELETE matches nothing and does NOT propagate —
+     *   full delete durability requires a schema tombstone (deferred:
+     *   `control-delete-while-alone-tombstone`). We still attempt the re-issue
+     *   (harmless, and it propagates in the row-still-present case); the commit-alone
+     *   was already logged loudly in {@link noteControlWrite}.
+     */
+    async drainPendingPeerWrites() {
+        if (this.pendingPeerWrites.size === 0) {
+            return;
+        }
+        if (!this.seedBootstrapService?.canAuthorize()) {
+            // A non-owner node cannot have authored these writes; drop any stray entries.
+            this.pendingPeerWrites.clear();
+            return;
+        }
+        for (const [peerId, kind] of [...this.pendingPeerWrites]) {
+            if (!this._running || !this.controlNode || !this.controlDatabase) {
+                return;
+            }
+            try {
+                if (kind === 'authorize') {
+                    const record = await this.controlDatabase.queryPeerRecord(peerId);
+                    if (!record || record.sig) {
+                        // Removed since, or peer self-published — nothing for the owner to re-issue.
+                        this.pendingPeerWrites.delete(peerId);
+                        continue;
+                    }
+                    await this.reissuePeerAuthorize(peerId, record.updatedAt);
+                }
+                else {
+                    // Best-effort delete re-issue (see method doc): propagates only if the row
+                    // is somehow still present locally.
+                    await this.seedBootstrapService.removePeer(peerId);
+                }
+                this.pendingPeerWrites.delete(peerId);
+            }
+            catch (error) {
+                log('drain: re-issue of %s (%s) failed; leaving queued for next growth: %o', peerId, kind, error);
+            }
+        }
+    }
+    /**
+     * Re-issue an owner membership row as a monotonic owner UPDATE: bump
+     * `UpdatedAt` strictly above the stored value (and the wall clock) and re-sign via
+     * the owner branch of `CadrePeer.AuthorizedUpdate`. The row already exists
+     * locally (it committed there, just local-only), so this is an UPDATE, not the
+     * original INSERT.
+     */
+    async reissuePeerAuthorize(peerId, currentUpdatedAt) {
+        if (!this.seedBootstrapService) {
+            return;
+        }
+        const updatedAt = Math.max(Date.now(), (currentUpdatedAt ?? 0) + 1);
+        await this.seedBootstrapService.reauthorizePeer(peerId, updatedAt);
+    }
+    /**
+     * On a control connection opening, detect the 0→≥1 transition and drain the
+     * write-while-alone re-replication queue (single-flight; fires only on the edge,
+     * not on every subsequent `connection:open`). Best-effort — a drain failure is
+     * logged, not thrown.
+     */
+    handleControlConnectionChange() {
+        if (!this._running || !this.controlNode) {
+            return;
+        }
+        const connected = this.controlNode.getConnections().length > 0;
+        if (!connected || this.hasControlConnection) {
+            return;
+        }
+        this.hasControlConnection = true;
+        log('Control cohort grew (0 → ≥1 connection); draining write-while-alone re-replication queue');
+        void this.drainPendingControlReplication('connection:open')
+            .catch((error) => log('Control re-replication drain (connection:open) failed: %o', error));
+    }
+    /** Re-arm the growth edge once all control connections drop, so a later reconnect re-drains. */
+    handleControlConnectionClose() {
+        if (!this.controlNode) {
+            return;
+        }
+        if (this.controlNode.getConnections().length === 0) {
+            this.hasControlConnection = false;
+        }
+    }
+    /**
+     * Wire the control-connection growth listeners that drive write-while-alone
+     * re-replication. Wired in {@link start} (not the delayed refresh path) so no
+     * early `connection:open` is missed; torn down in {@link stopRecordRefresh}.
+     * Idempotent.
+     */
+    wireControlConnectionListeners() {
+        if (!this.controlNode || this.controlConnectionOpenHandler) {
+            return;
+        }
+        this.controlConnectionOpenHandler = () => this.handleControlConnectionChange();
+        this.controlConnectionCloseHandler = () => this.handleControlConnectionClose();
+        this.controlNode.addEventListener('connection:open', this.controlConnectionOpenHandler);
+        this.controlNode.addEventListener('connection:close', this.controlConnectionCloseHandler);
+        // TURN-relay detection: tag/untag peers whose WebRTC ICE used a TURN candidate.
+        this.turnConnectionOpenHandler = (evt) => this.handleTurnConnectionOpen(evt.detail);
+        this.turnConnectionCloseHandler = (evt) => this.handleTurnConnectionClose(evt.detail);
+        this.controlNode.addEventListener('connection:open', this.turnConnectionOpenHandler);
+        this.controlNode.addEventListener('connection:close', this.turnConnectionCloseHandler);
+    }
+    /**
+     * On a control connection opening: if it is a WebRTC connection, drain the TURN
+     * tracker for the just-settled ICE verdict and, when it relayed, mark the peer
+     * so {@link getConnectionPaths} classifies it `webrtc-turn` (relayed). The
+     * settlement↔open correlation is timing-based and best-effort; an unknown
+     * verdict degrades to not-relayed. Never throws to the event loop.
+     */
+    handleTurnConnectionOpen(conn) {
+        try {
+            const addr = conn.remoteAddr?.toString() ?? '';
+            // Only a genuine `/webrtc` (ICE) session can be TURN-relayed and promoted to
+            // webrtc-turn. Use the classifier (which checks `/webrtc-direct` first) rather
+            // than a bare substring — `'/webrtc-direct'.includes('/webrtc')` is true, and a
+            // webrtc-direct open must not drain a settlement meant for a real webrtc dial.
+            if (classifyTransport(addr).transport !== 'webrtc') {
+                return;
+            }
+            if (this.turnTracker.consume(TURN_CONSUME_WINDOW_MS) === true) {
+                const peerId = conn.remotePeer.toString();
+                this.turnRelayedPeers.add(peerId);
+                log('TURN-relayed WebRTC connection detected for peer %s', peerId);
+            }
+        }
+        catch (error) {
+            log('handleTurnConnectionOpen failed: %o', error);
+        }
+    }
+    /** On a control connection closing, drop any TURN-relayed flag for its peer. */
+    handleTurnConnectionClose(conn) {
+        try {
+            this.turnRelayedPeers.delete(conn.remotePeer.toString());
+        }
+        catch (error) {
+            log('handleTurnConnectionClose failed: %o', error);
+        }
+    }
+    // ============================================================================
+    // Device-token registry (control-network push-token publish + resolve)
+    //
+    // The control network is the only network a hibernating peer keeps connected,
+    // so it is where a mobile peer self-publishes its FCM/APNs push token and where
+    // a server peer resolves it to deliver a push-wake to a suspended app. The write
+    // + gate paths mirror registerSelf / resolvePeerAddrs (see DeviceToken in
+    // control-schema.ts and device-token.ts).
+    // ============================================================================
+    /**
+     * Publish (or refresh) this node's own self-signed `DeviceToken` row so a server
+     * peer can resolve its FCM/APNs push token from its PeerId alone. Mirrors
+     * {@link registerSelf}:
+     *
+     * - If the row already exists: a self-signed UPDATE bumping `UpdatedAt` (works
+     *   for any member — the `AuthorizedUpdate` self-branch verifies the new `Sig`
+     *   against the bound `CadrePeer.PublicKey`). Platform/Token may change here
+     *   (rotation / platform switch / reinstall are all normal self-updates).
+     * - If not, and the node holds an owner service: an owner-signed INSERT
+     *   that also carries the self-signature.
+     * - Otherwise: throws. Like `CadrePeer`, the first `DeviceToken` row requires an
+     *   owner signature; a non-owner peer (e.g. a phone) must have its row
+     *   seeded by an owner — typically the server it enrolled with — before it
+     *   can self-refresh. (Establishing that phone→server registration handshake is
+     *   the downstream "RN registration" ticket; this node only owns the cadre-core
+     *   write path.)
+     *
+     * `UpdatedAt` strictly increases on every publish (even a same-millisecond
+     * re-publish), so a replayed older record is rejected by the schema.
+     *
+     * @param platform - `'fcm'` (Android/Firebase) or `'apns'` (Apple).
+     * @param token - the opaque platform device/registration token.
+     * @throws if the node is not started, exposes no self-signing key, or has no
+     *   existing row and no owner service to self-insert.
+     */
+    async registerDeviceToken(platform, token) {
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            throw new Error('CadreNode must be started before registering a device token');
+        }
+        const signingKey = this.getSelfSigningKey();
+        if (!signingKey) {
+            throw new Error('Cannot register device token: no self-signing key available ' +
+                '(node identity unavailable or not matching the node PeerId).');
+        }
+        const peerId = this.controlNode.peerId.toString();
+        const existing = await this.controlDatabase.queryDeviceToken(peerId);
+        // Strictly increase UpdatedAt even on a same-millisecond re-publish (rotation).
+        const updatedAt = Math.max(Date.now(), (existing?.updatedAt ?? 0) + 1);
+        const record = signDeviceTokenRecord({ peerId, platform, token, updatedAt }, signingKey.privateKeyB64);
+        if (existing) {
+            await this.controlDatabase.updateSelfDeviceToken(record);
+            if (this.committedAlone())
+                this.pendingSelfDeviceWrite = true;
+            log('registerDeviceToken: refreshed own DeviceToken (platform=%s, updatedAt=%d)', platform, updatedAt);
+            return;
+        }
+        if (this.seedBootstrapService) {
+            await this.seedBootstrapService.insertSelfDeviceToken(record);
+            if (this.committedAlone())
+                this.pendingSelfDeviceWrite = true;
+            log('registerDeviceToken: inserted own DeviceToken (owner-signed, platform=%s, updatedAt=%d)', platform, updatedAt);
+            return;
+        }
+        throw new Error(`Cannot register device token for ${peerId}: no existing row to self-update and no ` +
+            'owner service to self-insert. An owner must seed this peer\'s DeviceToken ' +
+            'row first (mirrors CadrePeer enrollment).');
+    }
+    /**
+     * Resolve a cadre peer's FCM/APNs push token from only its PeerId — the input a
+     * server's push-wake fan-out consumes to deliver a platform push to a suspended
+     * app. Applies the same gating shape as {@link resolvePeerAddrs}, returning
+     * `null` (never throwing) on any failure:
+     *
+     *   1. membership — the peer has a `CadrePeer` row with a `PublicKey`,
+     *   2. `publicKey <-> peerId` binding — the stored key's libp2p identity is the
+     *      requested peerId,
+     *   3. a `DeviceToken` row exists with a known {@link PushPlatform},
+     *   4. self-signature verifies against the bound `CadrePeer.PublicKey`,
+     *   5. freshness — `updatedAt` is positive and within `opts.maxAgeMs` (default:
+     *      no ceiling, since a push token is valid until it rotates).
+     *
+     * A peer that is not a current member, or whose token has no backing `CadrePeer`
+     * record, resolves to `null` — a server must not attempt to push to a non-cadre
+     * peer.
+     */
+    async resolveDeviceToken(peerId, opts = {}) {
+        if (!this.controlDatabase) {
+            throw new Error('CadreNode must be started before resolving a device token');
+        }
+        // Membership + publicKey<->peerId binding: read the peer's CadrePeer row and
+        // confirm the stored key is the one embedded in the requested Ed25519 peer id.
+        const peerRecord = await this.controlDatabase.queryPeerRecord(peerId);
+        if (!peerRecord || !peerRecord.publicKey) {
+            log('resolveDeviceToken: no CadrePeer/PublicKey for %s', peerId);
+            return null;
+        }
+        if (ed25519PublicKeyB64FromPeerId(peerId) !== peerRecord.publicKey) {
+            log('resolveDeviceToken: publicKey does not match peerId for %s', peerId);
+            return null;
+        }
+        const record = await this.controlDatabase.queryDeviceToken(peerId);
+        if (!record) {
+            log('resolveDeviceToken: no device token for %s', peerId);
+            return null;
+        }
+        if (!isPushPlatform(record.platform)) {
+            log('resolveDeviceToken: unknown platform %s for %s', record.platform, peerId);
+            return null;
+        }
+        // Self-signature over (peerId, platform, token, updatedAt), verified against the
+        // CadrePeer.PublicKey bound to this peerId.
+        if (!verifyDeviceTokenSignature(record, peerRecord.publicKey)) {
+            log('resolveDeviceToken: signature verification failed for %s', peerId);
+            return null;
+        }
+        // Freshness: a positive stamp, optionally bounded. No ceiling by default — a
+        // suspended phone's token must stay resolvable for push-wake long after publish.
+        const maxAgeMs = opts.maxAgeMs ?? Number.POSITIVE_INFINITY;
+        if (!isPeerRecordFresh(record.updatedAt, maxAgeMs, Date.now())) {
+            log('resolveDeviceToken: record for %s is stale (updatedAt=%d, maxAgeMs=%d)', peerId, record.updatedAt, maxAgeMs);
+            return null;
+        }
+        return record;
+    }
+    /**
+     * Delete this node's own `DeviceToken` row (logout / token invalidation). No-op
+     * when no row exists. Like {@link registerDeviceToken}'s first insert, the delete
+     * is gated on an owner signature (`DeviceToken.AuthorizedInsert` covers insert
+     * AND delete), so it requires this node's owner service; a non-owner peer
+     * must route the clear through its owner (downstream RN registration path).
+     *
+     * @throws if the node is not started, or a row exists but no owner service is
+     *   available to sign the delete.
+     */
+    async clearDeviceToken() {
+        if (!this._running || !this.controlNode || !this.controlDatabase) {
+            throw new Error('CadreNode must be started before clearing a device token');
+        }
+        const peerId = this.controlNode.peerId.toString();
+        const existing = await this.controlDatabase.queryDeviceToken(peerId);
+        if (!existing) {
+            log('clearDeviceToken: no DeviceToken row for %s; no-op', peerId);
+            return;
+        }
+        if (!this.seedBootstrapService) {
+            throw new Error(`Cannot clear device token for ${peerId}: delete requires an owner signature ` +
+                'and no owner service is initialized.');
+        }
+        await this.seedBootstrapService.deleteDeviceToken(peerId);
+        log('clearDeviceToken: deleted DeviceToken for %s', peerId);
+    }
+    /**
+     * Expire ANOTHER peer's stale `DeviceToken` after a platform reported it
+     * unregistered during a push-wake fan-out. Unlike {@link clearDeviceToken}
+     * (self-only — it hardcodes the local peerId), this takes an arbitrary peerId.
+     *
+     * - When this node holds an owner seed service, it deletes the row
+     *   (`deleteDeviceToken` is owner-gated and accepts any peerId), so the peer
+     *   is not retried until it re-registers.
+     * - When this node is NOT an owner it cannot delete the row, so it only logs
+     *   that a re-registration is needed. The fan-out's own in-memory dead-token set
+     *   is what actually stops re-pushing to the dead token this process — see
+     *   {@link PushFanoutService}. That set is acceptably lossy across restarts (a
+     *   restart re-learns staleness on the next failed send).
+     *
+     * Best-effort: never throws to the (best-effort) fan-out caller.
+     */
+    async expireDeviceToken(peerId) {
+        if (this.seedBootstrapService) {
+            try {
+                await this.seedBootstrapService.deleteDeviceToken(peerId);
+                log('expireDeviceToken: owner-deleted stale DeviceToken for %s', peerId);
+            }
+            catch (error) {
+                log('expireDeviceToken: owner delete for %s failed: %o', peerId, error);
+            }
+            return;
+        }
+        log('expireDeviceToken: %s token is stale but this node is not an owner; re-registration required', peerId);
     }
     async handleStrandAdded(strand) {
         log('Handling strand added from control network: %s', strand.Id);
         // Check if we have sApp config for this strand
         const sAppConfig = this.sAppConfigs.get(strand.Id);
         if (!sAppConfig) {
-            log('No sAppConfig registered for strand %s - skipping auto-start', strand.Id);
-            // Strand detected in control network but not yet configured via addStrand
-            // This is normal - the app will call addStrand with the config
+            log('No sAppConfig registered for strand %s - emitting strand:discovered', strand.Id);
+            // Strand created by another member and not yet configured locally. Surface
+            // it as a discovery event so the hosting app can decide whether to join
+            // (register a config + addStrand); the strand-agnostic seam keeps this
+            // class free of any app's join policy. A self-configured strand (config
+            // already present) keeps auto-starting below, unchanged.
+            this.emit('strand:discovered', { strandId: strand.Id, strand });
             return;
         }
         try {
-            const instance = await this.strandManager.startStrand({
-                strandRow: strand,
-                sAppConfig,
-                storage: this.config.storage,
-                network: this.config.network,
-                profile: this.config.profile,
-                defaultLatencyHint: this.config.hibernation?.defaultLatencyHint ?? 'interactive',
-                privateKey: this.config.privateKey
-            });
-            // Register with hibernation manager
-            this.hibernationManager.trackStrand(instance);
-            this.emit('strand:started', { strandId: strand.Id });
+            // Discovery path: no explicit mode — infer from cohort membership.
+            await this.launchStrand(strand, sAppConfig);
         }
         catch (error) {
             log('Error starting strand %s: %o', strand.Id, error);
@@ -320,6 +1552,16 @@ export class CadreNode {
         }
     }
     async cleanup() {
+        // Resolve + clear any in-flight wake windows first, so an in-flight check-in
+        // or serviceWake unblocks and tears down cleanly rather than firing a stale
+        // window timer (or hanging) after the strand manager is stopped below.
+        this.clearWindowWaiters();
+        // Stop self-record refresh timers + address-change listener (before the
+        // control node is torn down, so removeEventListener has a live target).
+        this.stopRecordRefresh();
+        // Restore the wrapped globalThis.RTCPeerConnection and drop TURN-relay state.
+        this.turnTracker.dispose();
+        this.turnRelayedPeers.clear();
         // Stop hibernation manager
         this.hibernationManager.stop();
         // Stop seed bootstrap service
@@ -327,6 +1569,22 @@ export class CadreNode {
             await this.seedBootstrapService.shutdown();
             this.seedBootstrapService = null;
         }
+        // Stop strand wake service (unregister the WAKE_PROTOCOL handler)
+        if (this.strandWakeService) {
+            await this.strandWakeService.shutdown();
+            this.strandWakeService = null;
+        }
+        // Stop strand-addr service (unregister the STRAND_ADDR_PROTOCOL handler so a
+        // restart does not hit DuplicateProtocolHandlerError).
+        if (this.strandAddrService) {
+            await this.strandAddrService.shutdown();
+            this.strandAddrService = null;
+        }
+        // Tear down the push-wake fan-out (releases the notifier's APNs HTTP/2 session).
+        if (this.pushFanoutService) {
+            await this.pushFanoutService.close().catch((err) => log('Push fan-out close failed: %o', err));
+            this.pushFanoutService = null;
+        }
         // Unregister strand solicitation service
         if (this.strandSolicitationService && this.controlNode) {
             this.strandSolicitationService.unregisterResponder(this.controlNode);
@@ -361,57 +1619,373 @@ export class CadreNode {
             this.emit('strand:idle', { strandId });
         }
     }
+    /**
+     * Hibernate a strand: release its strand-network resources via the strand
+     * manager (stop the libp2p node, close the StrandDatabase) and mark it
+     * `hibernating`. A quiesced strand holds no open strand-network connections,
+     * transports, or DB handles. No-ops if the strand is missing; if already
+     * quiesced (defensive), just marks status and emits.
+     */
     async handleStrandHibernate(strandId) {
         const instance = this.strandManager.getInstance(strandId);
-        if (instance) {
+        if (!instance) {
+            log('handleStrandHibernate: strand %s not found', strandId);
+            return;
+        }
+        if (!instance.libp2pNode && !instance.database) {
+            // Already quiesced — only the status flag needs updating.
             instance.status = 'hibernating';
-            // Optionally disconnect libp2p to save resources
-            // For now we keep it connected but could stop it here
-            log('Strand %s transitioned to hibernating', strandId);
+            log('Strand %s already quiesced; marked hibernating', strandId);
             this.emit('strand:hibernating', { strandId });
+            return;
         }
+        log('Hibernating strand %s — releasing strand-network resources', strandId);
+        await this.strandManager.quiesceStrand(strandId);
+        instance.status = 'hibernating';
+        this.emit('strand:hibernating', { strandId });
+        log('Strand %s hibernating (resources released)', strandId);
     }
+    /**
+     * 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
+     * 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
+     * per wake; `resumeStrand` is itself idempotent as a backstop.
+     */
     async handleStrandWake(strandId) {
         const instance = this.strandManager.getInstance(strandId);
-        if (instance) {
+        if (!instance) {
+            log('handleStrandWake: strand %s not found', strandId);
+            return;
+        }
+        // Still live (idle wake, or defensive double-wake): no rebuild needed.
+        if (instance.libp2pNode || instance.database) {
             instance.status = 'active';
             instance.lastActivity = new Date();
-            log('Strand %s woke up', strandId);
+            log('Strand %s woke (already live)', strandId);
             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.
+        log('Waking strand %s — rebuilding strand-network resources', strandId);
+        await this.resumeStrandRuntime(strandId);
+        instance.lastActivity = new Date();
+        this.emit('strand:waking', { strandId });
+        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
+     * the wake (`handleStrandWake`) and check-in (`handleStrandCheckIn`) paths so
+     * both apply the same fresh seed/mode resolution. `resumeStrand` is idempotent
+     * (returns the live instance unchanged) as a backstop against double-resume.
+     */
+    async resumeStrandRuntime(strandId) {
+        const seed = await this.resolveCohortSeed(strandId);
+        const mode = selectStrandMode(undefined, seed.hasOtherPeers);
+        await this.strandManager.resumeStrand(strandId, {
+            bootstrapNodes: seed.bootstrapNodes,
+            mode
+        });
+    }
+    /**
+     * Real cohort check-in for a hibernating strand (the `onCheckIn` callback).
+     *
+     * Optimystic syncs pull-on-read, not on connect, and exposes no cheap
+     * repo-level "pull pending" hook (`IRepo` is get/pend/commit/cancel only —
+     * see the review handoff). So "query the cohort for pending activity" is
+     * 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
+     *      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.
+     *   3. If activity was recorded during the window, leave the strand `active`
+     *      (the idle/hibernate timers + backoff reset take over). Otherwise
+     *      quiesce again and leave it `hibernating`, so `HibernationManager`
+     *      schedules the next, longer-delayed check-in.
+     *
+     * No-ops unless the strand is currently `hibernating` — a concurrent wake may
+     * have already resumed it.
+     */
+    async handleStrandCheckIn(strandId) {
+        const instance = this.strandManager.getInstance(strandId);
+        if (!instance) {
+            log('handleStrandCheckIn: strand %s not found', strandId);
+            return;
+        }
+        if (instance.status !== 'hibernating') {
+            log('handleStrandCheckIn: strand %s not hibernating (status=%s); skipping', strandId, instance.status);
+            return;
+        }
+        try {
+            // 1. Resume exactly as a wake does: re-resolve the (possibly grown) cohort
+            //    seed + mode, 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,
+            //      then re-hibernate-if-idle. Shared with the on-demand serviceWake.
+            const windowMs = this.config.hibernation?.checkInWindowMs ?? DEFAULT_CHECKIN_WINDOW_MS;
+            await this.runWakeWindow(instance, windowMs);
+        }
+        catch (err) {
+            // A check-in that throws part-way — resume failing on a flaky network (the
+            // very scenario hibernation targets), the window rejecting, or quiesce
+            // throwing — must leave the strand HIBERNATING, not in the `error` status
+            // that `resumeStrand` sets on failure. `HibernationManager.runCheckIn`
+            // decides wake-vs-escalate purely from `instance.status` after this
+            // resolves: an `error` status reads as "woke", which STOPS the check-in
+            // chain and strands the strand with no runtime and no future check-in.
+            // Forcing it back to `hibernating` (after a best-effort quiesce to release
+            // any partially-rebuilt runtime) makes the manager escalate the backoff and
+            // retry on the next tick.
+            log('Check-in failed for strand %s; re-hibernating to retry on backoff: %o', strandId, err);
+            await this.strandManager.quiesceStrand(strandId).catch((cleanupErr) => {
+                log('Check-in cleanup quiesce for strand %s failed: %o', strandId, cleanupErr);
+            });
+            instance.status = 'hibernating';
         }
     }
+    /**
+     * Window-then-decide for a just-resumed strand, shared by the check-in timer
+     * path ({@link handleStrandCheckIn}) and the on-demand {@link serviceWake}:
+     *
+     *   1. Capture the post-resume activity marker. `recordActivity` assigns a
+     *      FRESH `Date`, so a changed reference after the window means real
+     *      activity landed during it — not millisecond-resolution noise.
+     *   2. Hold the strand live for `windowMs` so its strand network reaches the
+     *      cohort and the app can drive pull-on-read activity.
+     *   3. If activity landed, leave the strand `active` (return `true`); otherwise
+     *      quiesce and mark it `hibernating` again (return `false`).
+     *
+     * @returns whether activity was observed during the window (strand left active).
+     */
+    async runWakeWindow(instance, windowMs) {
+        const strandId = instance.strandId;
+        const activityMark = instance.lastActivity;
+        await this.holdWakeWindow(instance, windowMs);
+        const sawActivity = instance.lastActivity !== activityMark;
+        if (sawActivity) {
+            instance.status = 'active';
+            this.emit('strand:waking', { strandId });
+            log('Wake window: strand %s saw activity during the window; staying active', strandId);
+            return true;
+        }
+        log('Wake window: no activity for strand %s; re-hibernating', strandId);
+        await this.strandManager.quiesceStrand(strandId);
+        instance.status = 'hibernating';
+        return false;
+    }
+    /**
+     * Hold a just-resumed strand live for `windowMs` (default
+     * {@link DEFAULT_CHECKIN_WINDOW_MS} is applied by callers). A non-positive
+     * window resolves immediately. The pending timer is tracked in
+     * {@link windowWaiters} so {@link cleanup} can both clear it and resolve the
+     * promise on teardown — a `stop()` during an in-flight window must neither fire
+     * the timer afterward nor hang the awaiting check-in/serviceWake. Extracted as
+     * its own method so tests can stub the wait (and inject activity during it).
+     */
+    async holdWakeWindow(_instance, windowMs) {
+        if (windowMs <= 0)
+            return;
+        await new Promise((resolve) => {
+            const waiter = { timer: undefined, resolve };
+            waiter.timer = setTimeout(() => {
+                this.windowWaiters.delete(waiter);
+                resolve();
+            }, windowMs);
+            this.windowWaiters.add(waiter);
+        });
+    }
+    /**
+     * Clear every in-flight wake window: cancel its timer and resolve its promise
+     * so any awaiting check-in/serviceWake completes promptly rather than hanging
+     * past teardown. Called from {@link cleanup}.
+     */
+    clearWindowWaiters() {
+        for (const waiter of this.windowWaiters) {
+            clearTimeout(waiter.timer);
+            waiter.resolve();
+        }
+        this.windowWaiters.clear();
+    }
     /**
      * Add a strand with its sApp configuration.
      * The hosting application must provide the sApp schema when creating a strand.
      */
     async addStrand(config) {
-        if (!this.running) {
+        if (!this._running) {
             throw new Error('CadreNode not running');
         }
-        const { strandRow, sAppConfig, mode } = config;
+        const { strandRow, sAppConfig, mode, founder } = config;
         // Store sApp config for this strand
         this.sAppConfigs.set(strandRow.Id, sAppConfig);
-        log('Registered sAppConfig for strand %s (sApp: %s, mode: %s)', strandRow.Id, sAppConfig.id, mode ?? 'networked');
+        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.
+        // `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);
+    }
+    /**
+     * Publish a strand row to the shared control database under this node's own
+     * owner identity, so other cadre members discover it via control-network
+     * sync (their {@link StrandWatcher} fires `strand:discovered`).
+     *
+     * This is the owner-signed `Strand` INSERT that {@link addStrand}
+     * deliberately omits: `addStrand` only starts the LOCAL strand instance,
+     * whereas publishing makes the strand visible cadre-wide. A typical creator
+     * does both (start locally + publish); a discovering peer only does
+     * `addStrand` (the row already exists).
+     *
+     * The insert is signed with the ed25519 key behind this node's PeerId — which
+     * {@link ed25519KeyPairFromLibp2p} also exposes as the node's owner keypair,
+     * so peer identity and owner key are one and the same. That key must be
+     * enrolled in `OwnerKey` (e.g. via {@link ControlDatabase.ensureOwnerKey}
+     * at genesis) or the schema's `Strand.Authorized` constraint rejects the write.
+     * Failing loudly here is intentional: a silently-unpublished strand would run
+     * as a local-only island that no peer could ever discover or join.
+     *
+     * @param strandId - Unique strand identifier (typically the same id passed to
+     *   {@link addStrand}).
+     * @param type - `'o'` for open (default) or `'c'` for closed.
+     * @param memberPrivateKey - Optional membership key for a closed strand.
+     * @throws if the node is not started, exposes no owner signing key, or the
+     *   control DB rejects the (unauthorized) insert.
+     */
+    async publishStrand(strandId, type = 'o', memberPrivateKey) {
+        if (!this._running || !this.controlDatabase) {
+            throw new Error('CadreNode must be started before publishing a strand');
+        }
+        const signingKey = this.getSelfSigningKey();
+        if (!signingKey) {
+            throw new Error(`Cannot publish strand ${strandId}: no owner signing key available ` +
+                '(node identity is unavailable or does not match the node PeerId). Run owner ' +
+                'genesis (ensureOwnerKey + initializeSeedBootstrap) before publishing.');
+        }
+        // insertStrand hands this callback the canonical row-bound message BYTES (see
+        // buildAuthorizationMessage); ed25519-sign them directly (no pre-hash) with
+        // the owner private key, returning a base64url signature.
+        const signMessage = (message) => sign(message, signingKey.privateKeyB64, 'ed25519', 'bytes', 'base64url', 'base64url');
+        await this.controlDatabase.insertStrand(strandId, type, signingKey.publicKeyB64, signMessage, memberPrivateKey);
+        log('Published strand %s (type %s) to control DB under owner %s', strandId, type, signingKey.publicKeyB64);
+    }
+    /**
+     * Publish an owner-signed `FormationInvite` (open-invitation token) to the
+     * shared control database, so a later {@link formStrand} redemption can be
+     * validated against it (the consent branch of `Strand.Authorized`).
+     *
+     * Counterpart to {@link createOpenInvitation}, which only mints the
+     * out-of-band {@link OpenInvitation} envelope: persisting the matching
+     * `FormationInvite` row is what makes the token *redeemable* — the host's
+     * {@link ControlFormationUsageRecorder} answers `isTokenValid`/`isTokenUsed`
+     * from this row. A host minting a closed-strand invite does both (mint +
+     * publish), exactly as the integration harness's `createInvitation` does.
+     *
+     * Signs with the same self-owner key as {@link publishStrand} (the ed25519
+     * key behind this node's PeerId, which must be an enrolled `OwnerKey`).
+     * Throws loudly if the node isn't started or exposes no signing key.
+     *
+     * @param token - Invitation token (the `FormationInvite` primary key); use the
+     *   `token` of the {@link OpenInvitation} from {@link createOpenInvitation}.
+     * @param sAppId - The sApp a redeemed strand will use.
+     * @param options - Optional `expiresAtMs` (epoch ms), `totalUses`, `validationUrl`,
+     *   `strandId` (bind a closed/pre-existing host strand for provision-then-record).
+     */
+    async publishFormationInvite(token, sAppId, options = {}) {
+        if (!this._running || !this.controlDatabase) {
+            throw new Error('CadreNode must be started before publishing a formation invite');
+        }
+        const signingKey = this.getSelfSigningKey();
+        if (!signingKey) {
+            throw new Error(`Cannot publish formation invite ${token}: no owner signing key available ` +
+                '(node identity is unavailable or does not match the node PeerId). Run owner ' +
+                'genesis (ensureOwnerKey + initializeSeedBootstrap) before publishing.');
+        }
+        const signMessage = (message) => sign(message, signingKey.privateKeyB64, 'ed25519', 'bytes', 'base64url', 'base64url');
+        await this.controlDatabase.insertFormationInvite(token, sAppId, signingKey.publicKeyB64, signMessage, options);
+        log('Published formation invite %s (sApp %s) under owner %s', token, sAppId, signingKey.publicKeyB64);
+    }
+    /**
+     * 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`.
+     */
+    async launchStrand(strand, sAppConfig, explicitMode, founder) {
+        const seed = await this.resolveCohortSeed(strand.Id);
+        const mode = selectStrandMode(explicitMode, seed.hasOtherPeers);
         const instance = await this.strandManager.startStrand({
-            strandRow,
+            strandRow: strand,
             sAppConfig,
             storage: this.config.storage,
             network: this.config.network,
             profile: this.config.profile,
             defaultLatencyHint: this.config.hibernation?.defaultLatencyHint ?? 'interactive',
-            privateKey: this.config.privateKey,
-            mode
+            privateKey: this.identityKey,
+            bootstrapNodes: seed.bootstrapNodes,
+            mode,
+            requireSignedSchemas: this.config.requireSignedSchemas,
+            founder
         });
-        // Register with hibernation manager
         this.hibernationManager.trackStrand(instance);
-        this.emit('strand:started', { strandId: strandRow.Id });
+        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.
+     *
+     * 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).
+     */
+    async resolveCohortSeed(strandId) {
+        if (!this.controlDatabase || !this.controlNode) {
+            return { bootstrapNodes: [], hasOtherPeers: false };
+        }
+        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));
+        const bootstrapNodes = targets.length
+            ? await collectStrandAddrs(this.controlNode, targets.map((peerId) => ({ peerId })), strandId)
+            : [];
+        return { bootstrapNodes, hasOtherPeers };
+    }
+    /**
+     * The local strand instance's dialable strand-network multiaddrs for the
+     * strand-addr RPC, ordered signaling-first (reusing the control node's
+     * {@link orderSignalingFirst}). Returns `[]` when the strand is not running
+     * locally or has no live libp2p node (hibernating / quiescing / never
+     * participated) — a node only answers for a strand it is actively meshing,
+     * regardless of the strand's mode. A `bootstrap`-mode first node still has a
+     * live node, so it answers and a later sibling can dial in.
+     */
+    getStrandMultiaddrs(strandId) {
+        const node = this.strandManager.getInstance(strandId)?.libp2pNode;
+        if (!node) {
+            return [];
+        }
+        return orderSignalingFirst(node.getMultiaddrs().map((ma) => ma.toString()));
+    }
     /**
      * Remove a strand
      */
     async removeStrand(strandId) {
-        if (!this.running) {
+        if (!this._running) {
             throw new Error('CadreNode not running');
         }
         // Untrack from hibernation
@@ -422,13 +1996,34 @@ export class CadreNode {
         this.emit('strand:stopped', { strandId });
     }
     /**
-     * Record activity on a strand (resets hibernation timer)
+     * Record activity on a strand (resets hibernation timer).
+     *
+     * Also drives the server push-wake fan-out: whatever already drives activity on
+     * this node's strand (its relay/app layer doing pull-on-read) additionally wakes
+     * hibernating mobile peers — the same imperative seam local-wake uses, with no
+     * new contract. No-op for the fan-out when push is not configured.
      */
     recordStrandActivity(strandId) {
         const instance = this.strandManager.getInstance(strandId);
         if (instance) {
             this.hibernationManager.recordActivity(instance);
         }
+        this.notifyStrandActivity(strandId);
+    }
+    /**
+     * Explicit fan-out trigger: an always-on host/relay/sApp calls this when it
+     * observes activity for a strand this node participates in, to wake hibernating
+     * mobile members over a direct control-network dial (falling back to FCM/APNs
+     * for suspended phones). This is the supported, honest v1 trigger — Optimystic
+     * exposes no passive repo-level "new transaction" hook to drive it automatically
+     * (see the deferred passive-detector follow-up). No-op when push is not
+     * configured; best-effort (never throws — the check-in wake is the backstop).
+     *
+     * @param strandId - the strand that saw activity.
+     * @param reason - free-form cause hint carried in the wake (default `activity`).
+     */
+    notifyStrandActivity(strandId, reason) {
+        void this.pushFanoutService?.notify(strandId, reason);
     }
     /**
      * Force wake a hibernating strand
@@ -436,6 +2031,144 @@ export class CadreNode {
     async wakeStrand(strandId) {
         await this.hibernationManager.wakeStrand(strandId);
     }
+    // ============================================================================
+    // Mobile background lifecycle primitives
+    //
+    // Imperative control a mobile BackgroundRunner drives from OS app-state and
+    // push events, rather than from the internal idle/hibernate/check-in timers.
+    // ============================================================================
+    /**
+     * Force a single strand to hibernate immediately, bypassing the idle/hibernate
+     * timers — the background-entry path. No-op if the strand is realtime
+     * (never-hibernate latency hint), already hibernating, or unknown.
+     *
+     * Routes through {@link HibernationManager.forceHibernate}, which cancels the
+     * strand's pending idle/hibernate (and check-in) timers — so a stale timer
+     * can't re-fire on or resurrect the strand — then runs the same `onHibernate`
+     * path as the timer (`quiesceStrand` + `status='hibernating'` +
+     * `strand:hibernating`). Unlike the timer path it does NOT re-arm check-ins:
+     * the strand stays down until the caller drives a wake (e.g. {@link serviceWake}).
+     */
+    async hibernateStrand(strandId) {
+        const instance = this.strandManager.getInstance(strandId);
+        if (!instance) {
+            log('hibernateStrand: strand %s unknown; no-op', strandId);
+            return;
+        }
+        if (!this.hibernationManager.hibernates(instance)) {
+            log('hibernateStrand: strand %s is realtime; no-op', strandId);
+            return;
+        }
+        if (instance.status === 'hibernating') {
+            log('hibernateStrand: strand %s already hibernating; no-op', strandId);
+            return;
+        }
+        await this.hibernationManager.forceHibernate(instance);
+    }
+    /**
+     * Force-hibernate every tracked strand whose latency hint is not realtime,
+     * tolerating per-strand failure (one strand failing to quiesce never aborts
+     * the others). Realtime strands are left running — the caller keeps the control
+     * connection and realtime strands alive for as long as the OS permits.
+     *
+     * @returns the strandIds actually hibernated (now in `hibernating` status);
+     *   realtime strands are excluded.
+     */
+    async hibernateAll() {
+        const hibernated = [];
+        for (const [strandId, instance] of this.strandManager.getInstances()) {
+            if (!this.hibernationManager.hibernates(instance)) {
+                log('hibernateAll: skipping realtime strand %s', strandId);
+                continue;
+            }
+            try {
+                await this.hibernateStrand(strandId);
+                if (instance.status === 'hibernating') {
+                    hibernated.push(strandId);
+                }
+            }
+            catch (error) {
+                // Collect-and-continue: a single strand's quiesce failure must not strand
+                // the rest of the background-entry sweep.
+                log('hibernateAll: strand %s failed to hibernate (continuing): %o', strandId, error);
+            }
+        }
+        log('hibernateAll: hibernated %d strand(s)', hibernated.length);
+        return hibernated;
+    }
+    /**
+     * On-demand equivalent of a check-in cycle, for a push-delivered wake on
+     * mobile: resume the strand, hold it live for `windowMs` so its strand network
+     * reaches the cohort and the app can pull pending activity, then re-hibernate
+     * if no activity was recorded (else leave it active).
+     *
+     * Idempotent / coalesced two ways: concurrent `serviceWake`s for the same
+     * strand share one in-flight operation ({@link serviceWakePromises}), and the
+     * underlying resume coalesces with a racing push-wake via
+     * {@link HibernationManager}'s wake coalescing — one runtime build, one window,
+     * one re-hibernate decision. Returns `{ serviced: false }` (never throws) when
+     * the node is not running or the strand is unknown, and surfaces a resume
+     * failure as `{ serviced: true, hadActivity: false }` after re-hibernating.
+     *
+     * @param strandId - the strand a push said has pending activity.
+     * @param opts.windowMs - override the live-window duration (defaults to the
+     *   configured `checkInWindowMs` / {@link DEFAULT_CHECKIN_WINDOW_MS}).
+     */
+    async serviceWake(strandId, opts) {
+        const existing = this.serviceWakePromises.get(strandId);
+        if (existing) {
+            log('serviceWake: joining in-flight wake for strand %s', strandId);
+            return existing;
+        }
+        const op = this.runServiceWake(strandId, opts);
+        this.serviceWakePromises.set(strandId, op);
+        try {
+            return await op;
+        }
+        finally {
+            this.serviceWakePromises.delete(strandId);
+        }
+    }
+    /** Body of {@link serviceWake}; serialised per-strand by its coalescing guard. */
+    async runServiceWake(strandId, opts) {
+        // Not-running / control-absent guard (mirrors pushWake): a background task
+        // must get a branchable result, never a throw.
+        if (!this._running || !this.controlNode) {
+            log('serviceWake: node not running; not serviced (strand %s)', strandId);
+            return { strandId, serviced: false, hadActivity: false };
+        }
+        const instance = this.strandManager.getInstance(strandId);
+        if (!instance) {
+            log('serviceWake: strand %s unknown to this node; not serviced', strandId);
+            return { strandId, serviced: false, hadActivity: false };
+        }
+        // Already live (active or idle — both retain their runtime): servicing is a
+        // no-op success. Do NOT run a window that would re-hibernate a strand the app
+        // may be actively using, and do NOT rebuild a second runtime.
+        if (instance.libp2pNode || instance.database) {
+            log('serviceWake: strand %s already live; no-op success', strandId);
+            return { strandId, serviced: true, hadActivity: true };
+        }
+        try {
+            // Coalesced resume: routes through wakeStrand → HibernationManager.beginWake
+            // so a racing push-wake shares this single runtime build.
+            await this.wakeStrand(strandId);
+            const windowMs = opts?.windowMs ?? this.config.hibernation?.checkInWindowMs ?? DEFAULT_CHECKIN_WINDOW_MS;
+            const hadActivity = await this.runWakeWindow(instance, windowMs);
+            return { strandId, serviced: true, hadActivity };
+        }
+        catch (error) {
+            // Resume failing mid-window (network unreachable inside a Doze grant, etc.)
+            // must not throw out of a background task: re-hibernate and report no
+            // activity, mirroring handleStrandCheckIn's re-hibernate-on-error.
+            log('serviceWake: strand %s failed during wake window; re-hibernating: %o', strandId, error);
+            await this.strandManager.quiesceStrand(strandId).catch((cleanupErr) => {
+                log('serviceWake cleanup quiesce for strand %s failed: %o', strandId, cleanupErr);
+            });
+            instance.status = 'hibernating';
+            return { strandId, serviced: true, hadActivity: false };
+        }
+    }
     /**
      * Get the control network node (for advanced use)
      */
@@ -464,21 +2197,20 @@ export class CadreNode {
     // Seed Bootstrap API
     // ============================================================================
     /**
-     * Initialize the seed bootstrap service with an authority key.
+     * Initialize the seed bootstrap service with an owner key.
      * Must be called before using seed-related methods that require signing.
      *
-     * @param authorityPrivateKey - The authority's private key (base64url encoded)
+     * @param ownerPrivateKey - The owner's private key (base64url encoded)
      */
-    initializeSeedBootstrap(authorityPrivateKey) {
+    initializeSeedBootstrap(ownerPrivateKey) {
         if (!this.controlNode || !this.controlDatabase) {
             throw new Error('CadreNode must be started before initializing seed bootstrap');
         }
         this.seedBootstrapService = new SeedBootstrapService({
             partyId: this.config.controlNetwork.partyId,
-            authorityPrivateKey,
-            ...(this.config.network?.inviteAddressResolver
-                ? { inviteAddressResolver: this.config.network.inviteAddressResolver }
-                : {}),
+            ownerPrivateKey,
+            inviteAddressResolver: () => this.resolveInviteAddresses(),
+            trustPolicy: this.config.seedTrustPolicy,
         });
         this.seedBootstrapService.setEventCallbacks({
             onSeedReceived: (partyId, peerId) => this.emit('seed:received', { partyId, peerId }),
@@ -488,10 +2220,105 @@ export class CadreNode {
         this.seedBootstrapService.initialize(this.controlNode, this.controlDatabase);
         log('Seed bootstrap service initialized');
     }
+    /**
+     * Push the multiaddrs that future invites should advertise. Pass `null` to
+     * revert to the libp2p-reported addresses (the default). The host calls this
+     * at spawn and on every NAT change.
+     */
+    setInviteAddresses(addresses) {
+        this.latestInviteAddresses = addresses;
+        log('Invite addresses updated: %s', addresses ? `${addresses.length} pushed` : 'cleared (libp2p fallback)');
+    }
+    /**
+     * Resolve the addresses to embed in invites. Prefers pushed addresses, then
+     * any config-supplied resolver, then the libp2p-observed multiaddrs.
+     */
+    async resolveInviteAddresses() {
+        if (this.latestInviteAddresses !== null) {
+            return this.latestInviteAddresses;
+        }
+        if (this.config.network?.inviteAddressResolver) {
+            return this.config.network.inviteAddressResolver();
+        }
+        return this.getMultiaddrs();
+    }
+    /**
+     * Enumerate the cadre's `CadrePeer` membership.
+     */
+    async listMembers() {
+        if (!this.controlDatabase) {
+            throw new Error('CadreNode must be started before listing members');
+        }
+        return this.controlDatabase.queryCadrePeers();
+    }
+    /**
+     * Probe whether a given peer is a `CadrePeer` member.
+     *
+     * This is the ADDRESSABLE surface ("do I have a dialable address record for this
+     * peer") — it includes this node's own self-published row. Address resolution and
+     * push fan-out use this. The trust-facing gate is {@link isAuthorizedMember}.
+     */
+    async isMember(peerId) {
+        const members = await this.listMembers();
+        return members.some(m => m.peerId === peerId);
+    }
+    /**
+     * Enumerate the party's AUTHORIZED members — the trust-facing set, distinct from
+     * the addressable set ({@link listMembers}). Excludes this node itself: a node
+     * publishes its own `CadrePeer` address row so its dialable address rides in seeds,
+     * but "self" is not a peer this node authorized. The control-network wake and
+     * strand-address gates consult this set, NOT the addressable one.
+     *
+     * NOTE: this is the addressable set minus self for now. The real trust predicate
+     * (voucher recorded on the row ∈ node-local trusted-owner anchor, signature
+     * verified) lands with the `membership-node-local-owner-anchor` /
+     * `membership-authorized-predicate-and-gates` tickets; keeping the filter in this one
+     * method means that change touches a single place.
+     */
+    async listAuthorizedMembers() {
+        const selfPeerId = this.peerId?.toString();
+        const members = await this.listMembers();
+        return members.filter(m => m.peerId !== selfPeerId);
+    }
+    /**
+     * Probe whether a given peer is an AUTHORIZED party member (see
+     * {@link listAuthorizedMembers}) — the gate the control-network wake and
+     * strand-address responders consult, NOT {@link isMember} (the addressable surface).
+     */
+    async isAuthorizedMember(peerId) {
+        const members = await this.listAuthorizedMembers();
+        return members.some(m => m.peerId === peerId);
+    }
+    /**
+     * Push-wake a hibernating cadre peer over the control network.
+     *
+     * Resolves the target's signed control-network address from its `CadrePeer`
+     * record (via {@link resolvePeerAddrs}, signaling/relay first — so a NAT'd peer
+     * is reachable through its circuit-relay address), dials `WAKE_PROTOCOL`, sends
+     * the {@link WakeRequest}, and returns the peer's {@link WakeAck}. The receiver
+     * gates the request on cadre membership and only resumes a strand it already
+     * participates in.
+     *
+     * @param targetPeerId - The hibernating cadre peer to wake.
+     * @param strandId - The strand the caller knows has pending activity.
+     * @param reason - Optional cause hint, e.g. `"activity"` or `"manual"`.
+     * @throws if the node is not started or the target has no dialable address.
+     */
+    async pushWake(targetPeerId, strandId, reason) {
+        if (!this.controlNode) {
+            throw new Error('CadreNode must be started before pushing wakes');
+        }
+        const addrs = await this.resolvePeerAddrs(targetPeerId);
+        if (addrs.length === 0) {
+            throw new Error(`No dialable control-network address for peer ${targetPeerId}`);
+        }
+        const request = { strandId, reason };
+        return await dialWake(this.controlNode, addrs, request);
+    }
     /**
      * Enable the seed listener for receiving seeds via the /sereus/seed/1.0.0 protocol.
-     * This is for drone nodes that need to receive seeds without being an authority.
-     * Does not require an authority key.
+     * This is for drone nodes that need to receive seeds without being an owner.
+     * Does not require an owner key.
      */
     enableSeedListener() {
         if (!this.controlNode || !this.controlDatabase) {
@@ -504,10 +2331,9 @@ export class CadreNode {
         }
         this.seedBootstrapService = new SeedBootstrapService({
             partyId: this.config.controlNetwork.partyId,
-            // No authority key - this node only receives seeds
-            ...(this.config.network?.inviteAddressResolver
-                ? { inviteAddressResolver: this.config.network.inviteAddressResolver }
-                : {}),
+            // No owner key - this node only receives seeds
+            inviteAddressResolver: () => this.resolveInviteAddresses(),
+            trustPolicy: this.config.seedTrustPolicy,
         });
         this.seedBootstrapService.setEventCallbacks({
             onSeedReceived: (partyId, peerId) => this.emit('seed:received', { partyId, peerId }),
@@ -525,7 +2351,7 @@ export class CadreNode {
     }
     /**
      * Authorize a new peer to join the cadre.
-     * Signs the peer ID with the authority key and inserts into CadrePeer table.
+     * Signs the peer ID with the owner key and inserts into CadrePeer table.
      *
      * @param peerId - The peer ID to authorize
      * @param multiaddrs - Optional multiaddrs for the peer
@@ -535,10 +2361,12 @@ export class CadreNode {
             throw new Error('Seed bootstrap service not initialized. Call initializeSeedBootstrap() first.');
         }
         await this.seedBootstrapService.authorizePeer({ peerId, multiaddrs });
+        // Queue for re-replication if this committed local-only (no connected cohort).
+        this.noteControlWrite(peerId, 'authorize');
     }
     /**
      * Remove a previously-authorized peer from the cadre.
-     * Signs the peer ID with the authority key and deletes the CadrePeer row.
+     * Signs the peer ID with the owner key and deletes the CadrePeer row.
      *
      * @param peerId - The peer ID to remove
      */
@@ -547,10 +2375,12 @@ export class CadreNode {
             throw new Error('Seed bootstrap service not initialized. Call initializeSeedBootstrap() first.');
         }
         await this.seedBootstrapService.removePeer(peerId);
+        // Track + loudly flag a delete that committed local-only (security-relevant).
+        this.noteControlWrite(peerId, 'remove');
     }
     /**
      * Create a seed from the current control network state.
-     * The seed contains peer information and is signed by an authority.
+     * The seed contains peer information and is signed by an owner.
      */
     async createSeed() {
         if (!this.seedBootstrapService) {
@@ -560,20 +2390,36 @@ export class CadreNode {
     }
     /**
      * Apply a seed to populate the peer cache and enable connections.
-     * Validates the seed signature before applying.
+     *
+     * Validates the seed signature, then evaluates a trust anchor for the signer
+     * key (see `SeedTrustPolicy`). An enrollment caller can pass a per-seed
+     * `trustPolicy` override — e.g. a `pinnedKeyTrustPolicy` built from a
+     * `CadreInvite.ownerKeys` — so a cold-start node can accept its first
+     * seed without reconfiguring the service.
      */
-    async applySeed(seed) {
+    async applySeed(seed, options) {
         if (!this.seedBootstrapService) {
-            // Create a temporary service for applying seeds (doesn't need authority key)
+            // Create a temporary service for applying seeds (doesn't need owner key).
+            // partyId is the attacker-influenced seed.partyId — it only labels logs; the
+            // trust decision rests solely on signerKey vs the anchor set (configured
+            // default below, or the per-call options.trustPolicy override).
+            //
+            // This temp service is discarded after the call, so it must NOT own the shared
+            // node's inbound seed handler: pass { registerHandler: false }. That keeps
+            // repeated service-less applySeed/dialInvite idempotent (no handler leak, no
+            // DuplicateProtocolHandlerError). The temp service still applies this seed; a
+            // node that wants to RECEIVE inbound seeds needs a persistent service
+            // (enableSeedListener / initializeSeedBootstrap) to own the handler.
             const tempService = new SeedBootstrapService({
                 partyId: seed.partyId,
+                trustPolicy: this.config.seedTrustPolicy,
             });
             if (this.controlNode && this.controlDatabase) {
-                tempService.initialize(this.controlNode, this.controlDatabase);
+                tempService.initialize(this.controlNode, this.controlDatabase, { registerHandler: false });
             }
-            return await tempService.applySeed(seed);
+            return await tempService.applySeed(seed, options);
         }
-        return await this.seedBootstrapService.applySeed(seed);
+        return await this.seedBootstrapService.applySeed(seed, options);
     }
     /**
      * Deliver a seed directly to a peer via the /sereus/seed/1.0.0 protocol.
@@ -672,16 +2518,23 @@ export class CadreNode {
         return JSON.parse(json);
     }
     /**
-     * Dial an authority from an invite (for phone joining via invite).
+     * Dial an owner from an invite (for phone joining via invite).
      */
     async dialInvite(invite) {
         if (!this.seedBootstrapService) {
-            // Create a temporary service for dialing
+            // Create a temporary service that only dials the invite. It is discarded after
+            // the call, so it does NOT own the shared node's inbound seed handler:
+            // initialize with { registerHandler: false }. This temp dialInvite never
+            // applies a seed itself — a node that wants to RECEIVE an inbound seed back
+            // must have a persistent service (enableSeedListener / initializeSeedBootstrap)
+            // own the /sereus/seed/1.0.0 handler. trustPolicy is therefore effectively dead
+            // on this dial-only path; it is kept for symmetry with the applySeed temp site.
             const tempService = new SeedBootstrapService({
                 partyId: invite.partyId,
+                trustPolicy: this.config.seedTrustPolicy,
             });
             if (this.controlNode && this.controlDatabase) {
-                tempService.initialize(this.controlNode, this.controlDatabase);
+                tempService.initialize(this.controlNode, this.controlDatabase, { registerHandler: false });
             }
             await tempService.dialInvite(invite);
             return;
@@ -689,7 +2542,7 @@ export class CadreNode {
         await this.seedBootstrapService.dialInvite(invite);
     }
     // ============================================================================
-    // Strand Solicitation API (strand-proto integration)
+    // Strand Solicitation API (native cadre-core formation transport)
     // ============================================================================
     /**
      * Initialize the strand solicitation service.