@serfab/cadre-core 1.7.0 → 1.8.0

package/dist/cadre-node.d.ts

@@ -17,10 +17,10 @@ import { type RelayReservationState, type RelayReservationSupervisorOptions } fr
 import type { WakeAck } from './types.js';
 import { type ConnectionPathSummary } from './diagnostics/connection-path.js';
 /**
- * How often a running strand re-resolves its siblings' strand-network addresses
- * and re-merges them into its own libp2p address book
- * ({@link CadreNode.refreshStrandPeerAddrs}). Overridable per node via
- * `network.controlCohort.strandAddrRefreshMs`.
+ * How often a running strand re-asks each connected sibling that last ANSWERED
+ * (even with nothing) for its strand-network addresses, and re-merges them into
+ * its own libp2p address book ({@link CadreNode.refreshStrandPeerAddrs}).
+ * Overridable per node via `network.controlCohort.strandAddrRefreshMs`.
  *
  * Ten minutes sits comfortably inside the peerStore's one-hour address expiry
  * (`MAX_ADDRESS_AGE`, see `peer-addr-book.ts`) with headroom for several missed
@@ -28,6 +28,16 @@ import { type ConnectionPathSummary } from './diagnostics/connection-path.js';
  * strand-addr RPC fan-out stays cheap.
  */
 export declare const STRAND_PEER_ADDR_REFRESH_MS: number;
+/**
+ * How soon {@link CadreNode.refreshStrandPeerAddrs} re-asks a sibling that did NOT
+ * answer — unreachable, `unavailable`, or `refused`. A refusal matters most: a
+ * phone asking before its `CadrePeer` row has replicated to the sibling is refused
+ * and its delegate grant goes unrecorded, and waiting the full
+ * {@link STRAND_PEER_ADDR_REFRESH_MS} for the next try is the delay this bounds.
+ * Four reconcile ticks, so a sibling that keeps failing costs one timed-out RPC a
+ * minute rather than one a tick.
+ */
+export declare const STRAND_PEER_ADDR_RETRY_MS: number;
 type EventHandler<T> = (data: T) => void;
 /**
  * CadreNode is the main entry point for a cadre member.
@@ -161,6 +171,28 @@ export declare class CadreNode implements SAppIdLookup {
      * {@link getDiscoveredStrands}.
      */
     private discoveredStrands;
+    /**
+     * Whether an unclaimed strand the filter admits is launched as a storage replica
+     * ({@link CadreNodeConfig.hostUnclaimedStrands}), resolved once from the config.
+     *
+     * NOTE: a replica host stores every admitted strand of its party with no quota (Arachnode
+     * quotas are unimplemented). Fine at a party's handful of strands; if always-on nodes come
+     * to host strands by the hundred, per-strand quotas or a narrower default filter is the lever.
+     */
+    private readonly hostUnclaimedStrands;
+    /**
+     * The sApp id each storage replica read from its own `Strand.Header` — {@link getSAppId}'s
+     * answer for a strand no local config claims, so an `sAppId` strand filter can reject a
+     * replica of some other app instead of admitting it provisionally forever.
+     *
+     * Cleared by {@link cleanup} only, deliberately NOT by {@link detachStrand}: the watcher's
+     * filter rejection stops a replica through that very method, and forgetting the id there
+     * would have the next poll find it unknown again, re-admit the strand provisionally and
+     * relaunch the replica — once every other poll, forever. A strand id's sApp never changes,
+     * and the map is bounded by the strands this party has published, like
+     * {@link discoveredStrands}.
+     */
+    private replicaSAppIds;
     /**
      * Most-recently pushed invite addresses (see {@link setInviteAddresses}).
      * When non-null these take priority over `libp2pNode.getMultiaddrs()` when
@@ -235,9 +267,20 @@ export declare class CadreNode implements SAppIdLookup {
      * `denyInboundRelayReservation` policy); authorized members and announced
      * delegates are admitted before it and never counted. Cap from
      * `network.unauthorizedRelayReservationCap` (default
-     * `MAX_UNAUTHORIZED_RELAY_RESERVATIONS`).
+     * `MAX_UNAUTHORIZED_RELAY_RESERVATIONS`); entries expire on the relay
+     * server's own resolved `reservationTtl` ({@link relayServer}).
      */
     private readonly unauthorizedRelayReservations;
+    /**
+     * Does this node's CONTROL libp2p run the circuit-relay server, and with which
+     * init? Resolved once from `network` and `profile` by the same function every
+     * strand node's build uses (`relay-server.ts`). Read by
+     * {@link buildControlNodeOptions} (which configures the server from it),
+     * {@link admitInboundControlConnection} (whose deny/admit-for-relay branch must
+     * agree with whether a reservation is even servable here), and the
+     * unauthorized budget above (whose TTL is the server's).
+     */
+    private readonly relayServer;
     /**
      * When this node last ANNOUNCED a delegate, keyed `<targetPeerId>\n<strandId>`
      * (the peer announced TO, not the delegate). Throttles
@@ -248,15 +291,18 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private readonly delegateAnnounceAt;
     /**
-     * When each running strand last had its siblings' strand addresses re-resolved
-     * into its own address book, keyed by strandId. Throttles
-     * {@link refreshStrandPeerAddrs} to once per {@link STRAND_PEER_ADDR_REFRESH_MS}
-     * per strand so the 15 s reconcile tick never becomes per-tick RPC chatter.
-     * Entries for strands that are no longer running are pruned on each pass, so a
-     * hibernated-then-resumed strand refreshes immediately rather than inheriting a
-     * stale stamp.
+     * When each connected sibling is next due a strand-addr RPC for each running
+     * strand, keyed `peerStrandKey(siblingControlPeerId, strandId)` → epoch ms; a
+     * missing key is due. Bounds {@link refreshStrandPeerAddrs}'s fan-out per
+     * (sibling, strand) rather than per strand, so a sibling that connects after a
+     * pass is asked on the next 15 s tick instead of waiting out a stamp another
+     * sibling's answer set. An answer (even an empty one) makes the sibling due again
+     * in {@link STRAND_PEER_ADDR_REFRESH_MS}; no answer, in
+     * {@link STRAND_PEER_ADDR_RETRY_MS}. Keys whose strand stopped running or whose
+     * sibling is no longer connected are pruned every pass, so a resumed strand and a
+     * reconnected sibling are both asked at once.
      */
-    private readonly strandPeerAddrRefreshAt;
+    private readonly strandAddrAskDueAt;
     /**
      * Node-local strand peer book (see `strand-peer-book.ts`): per strand, the strand
      * peers this node has met and their last-known strand-network addresses. Three
@@ -387,22 +433,22 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private enrolledMachineStore;
     /**
-     * Node-local record of the strands this node joined from ANOTHER party (see
-     * `joined-strand-store.ts`) — the only thing that names them after a restart, since
-     * this party's control database holds no row for them. Written by {@link formStrand}
-     * and by an {@link addStrand} of a foreign row; forgotten by {@link forgetJoinedStrand}
-     * and on self-revocation. Adopted from `config.joinedStrands.store`, else built over
+     * Node-local record of the strands this node joined from ANOTHER party and has not yet
+     * published party-wide (see `joined-strand-store.ts`). Written by {@link formStrand}
+     * and by an {@link addStrand} of a foreign row; drained once the party-wide
+     * `JoinedStrand` row is visible. Adopted from `config.joinedStrands.store`, else built over
      * `config.keyStore`, else in-memory, by {@link initializeJoinedStrandStore}. Like
      * {@link bootstrapPeerStore} it is deliberately NOT cleared by {@link cleanup}.
      */
     private joinedStrandStore;
     /**
-     * The strand watcher's view of {@link joinedStrandStore}: its records unioned with the
-     * control rows each poll. Per SESSION, unlike the store — rebuilt at every
+     * This session's joined strands: {@link joinedStrandStore} and the party-wide
+     * `JoinedStrand` table, unioned with the control rows each watcher poll, published and
+     * removed by the reconcile pass. Per SESSION, unlike the store — rebuilt at every
      * {@link start}, which is what ends a revoked join's "keep offering until this session
-     * ends" (see `JoinedStrandRows.forgetAfterThisSession`).
+     * ends" (see `JoinedStrandSession.forgetAfterThisSession`).
      */
-    private joinedStrandRows;
+    private joinedStrands;
     /**
      * The enrolled-machine count this node's CONTROL libp2p node was (or will be)
      * built with — read out of {@link enrolledMachineStore} during {@link start},
@@ -544,7 +590,8 @@ export declare class CadreNode implements SAppIdLookup {
     private turnConnectionCloseHandler;
     constructor(config: CadreNodeConfig);
     /**
-     * SAppIdLookup implementation - get sAppId for a strand
+     * SAppIdLookup implementation - get sAppId for a strand: the claiming config's, else
+     * the one a storage replica read from the strand's own `Strand.Header`.
      */
     getSAppId(strandId: string): string | undefined;
     /**
@@ -712,7 +759,7 @@ export declare class CadreNode implements SAppIdLookup {
     private initializeEnrolledMachineStore;
     /**
      * Construct (or adopt) the node-local joined-strand store (see
-     * {@link joinedStrandStore}) and this session's watcher view over it.
+     * {@link joinedStrandStore}) and this session's {@link joinedStrands} over it.
      *
      * The store instance is kept across stop()→start(); the view is rebuilt. A store
      * scoped to a different party is a configuration error, fail closed: its joins
@@ -867,14 +914,12 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private buildControlNodeOptions;
     /**
-     * Does this node's CONTROL libp2p run the circuit-relay server? An explicit
-     * `network.enableRelay` wins; otherwise storage-profile nodes default to on
-     * (better connectivity/uptime). Shared by {@link buildControlNodeOptions}
-     * (which configures the server from it) and
-     * {@link admitInboundControlConnection} (whose deny/admit-for-relay branch
-     * must agree with whether a reservation is even servable here).
+     * One debug line naming what this machine's relay server forwards and holds —
+     * the same fields the dedicated relay container prints at boot
+     * (`ops/docker/libp2p-infra/src/main.ts`). Once per start, not per strand:
+     * strand nodes resolve the same settings from the same config.
      */
-    private relayServerEnabled;
+    private logRelayServerSettings;
     /**
      * Decide whether an inbound CONTROL-network connection from `remotePeerId`
      * should be admitted — the policy behind the connection gater wired in
@@ -922,7 +967,7 @@ export declare class CadreNode implements SAppIdLookup {
      *    accepted it, exactly like the unreplicated-membership-row case below.
      *
      * When every check falls through, the verdict depends on whether this node
-     * runs the circuit-relay server ({@link relayServerEnabled}): without one,
+     * runs the circuit-relay server ({@link relayServer}): without one,
      * `'deny'`; with one, `'admit-for-relay'` — a circuit-relay reservation is
      * established by the reserving peer DIALING the relay, so a connection deny
      * here kills the reservation, and that deny is NOT self-healing: an outbound
@@ -1089,11 +1134,24 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private getBootstrapPeerIds;
     /**
-     * What the strand watcher polls: this party's control rows plus a row per remembered
-     * cross-party join (see {@link joinedStrandRows}), so a joined strand is re-offered
-     * and relaunched on the same path as the party's own.
+     * What the strand watcher polls: this party's control rows plus a row per cross-party
+     * join (see {@link joinedStrands}), so a joined strand is offered and relaunched on
+     * the same path as the party's own.
      */
     private createStrandQueryable;
+    /**
+     * The party-wide `JoinedStrand` table as {@link joinedStrands} reads and writes it.
+     * Reads {@link controlDatabase} at call time, so start-up order does not matter.
+     */
+    private createPartyJoinedStrandLedger;
+    /**
+     * This machine's owner signing key when it can make owner-gated control writes: its seed
+     * bootstrap holds an owner key (`SeedBootstrapService.canAuthorize`) and the party's
+     * `OwnerKey` table enrolls it. A phone that ran self-genesis after another machine
+     * founded the party passes the first test and not the second (`runOwnerGenesis` in the
+     * reference apps), and a write it signed would only be refused.
+     */
+    private enrolledOwnerSigningKey;
     /**
      * Schedule the node's initial self-record publish + ongoing refresh shortly
      * after start (non-blocking). {@link registerSelf} is idempotent and safely
@@ -1417,6 +1475,17 @@ export declare class CadreNode implements SAppIdLookup {
      * test that drives dead addresses on purpose keeps the duration it chose.
      */
     private controlDialBudget;
+    /**
+     * The link-derived limits shared by every {@link SeedBootstrapService} this node builds: its
+     * owner and invite dials ({@link controlDialBudget}) and its seed delivery deadline, derived
+     * from `network.linkRoundTripMs`. One helper so the four construction sites cannot drift.
+     */
+    private seedServiceBudgets;
+    /**
+     * {@link collectStrandAddrs} at this node's declared `network.linkRoundTripMs`, so each ask's
+     * deadline derives from it. One helper so the four call sites cannot drift.
+     */
+    private collectSiblingStrandAddrs;
     /**
      * Dial one sibling from its already-resolved addresses, best-effort. Returns
      * whether the dial resolved (false when no address resolves or the dial fails).
@@ -1425,7 +1494,9 @@ export declare class CadreNode implements SAppIdLookup {
      * the {@link controlDialBudget} expiring) is logged and swallowed so one
      * unreachable sibling never aborts the pass — exactly like
      * {@link SeedBootstrapService.applySeed}'s owner-dial loop. A failed dial is
-     * simply retried on the next pass.
+     * simply retried on the next pass. A sibling whose every address relays
+     * through this node ({@link SelfRelayOnlyError}) is not dialed at all and gets
+     * a one-line log instead: only the sibling can reconnect.
      */
     private dialControlSibling;
     /**
@@ -1815,6 +1886,37 @@ export declare class CadreNode implements SAppIdLookup {
      */
     expireDeviceToken(peerId: string): Promise<void>;
     private handleStrandAdded;
+    /**
+     * Offer a strand no local config claims to the hosting app as `strand:discovered`, so
+     * it can decide whether to join (register a config + addStrand); the strand-agnostic
+     * seam keeps this class free of any app's join policy.
+     *
+     * Once per strand: a storage-replica launch that fails is retried by the watcher
+     * (`StrandWatcher.forgetStrand` + backoff), and each retry comes back through
+     * {@link handleStrandAdded} with no config — the app must still see one announcement.
+     * The other thing that un-retains a strand in the watcher (a failed `addStrand`) leaves
+     * the sApp config registered, so that retry takes the claimed branch instead.
+     *
+     * Recorded BEFORE the emit so a handler that synchronously drains
+     * `getDiscoveredStrands()` sees this strand too. So this map — not the event — is what
+     * a late subscriber reads. See the `strand:discovered` doc in types.ts.
+     *
+     * NOTE: a replica launch that keeps failing leaves the watcher not tracking the strand,
+     * so if its control row is removed during the backoff no `handleStrandRemoved` arrives
+     * and this entry outlives the row. Needs a persistently failing launch AND a removal
+     * inside the backoff; if it is ever seen, have the watcher report removal of rows it
+     * forgot, since `detachStrand` is already a no-op for an untracked instance.
+     */
+    private announceDiscoveredStrand;
+    /**
+     * Record the sApp id a storage replica's `Strand.Header` names, for {@link getSAppId}.
+     * Runs whenever a replica's database may have just been published (launch, the
+     * first-sync gate opening, a wake); a no-op for a claimed strand, an unpublished
+     * database, or an id already recorded. Never throws: a failed read logs and leaves the
+     * id unknown, so an `sAppId` filter keeps the strand provisionally admitted — a
+     * syncing replica, which is harmless.
+     */
+    private recordReplicaSAppId;
     private handleStrandRemoved;
     /**
      * Return this node to its pre-{@link start} state. The ONE teardown — `stop()` and
@@ -1835,10 +1937,10 @@ export declare class CadreNode implements SAppIdLookup {
     private handleStrandIdle;
     /**
      * Hibernate a strand: release its strand-network resources via the strand
-     * manager (stop the libp2p node, close the StrandDatabase) and mark it
+     * manager (stop the libp2p node, close the StrandDatabase), which marks 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.
+     * transports, or DB handles. No-ops if the strand is missing; one already quiesced
+     * is only marked, and still emits.
      */
     private handleStrandHibernate;
     /**
@@ -1847,15 +1949,42 @@ export declare class CadreNode implements SAppIdLookup {
      * 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.
+     * per wake; a wake racing a check-in joins the check-in's rebuild in `resumeStrand`.
+     *
+     * A failed rebuild re-hibernates the strand (see {@link rehibernateIfResumeFailed});
+     * every failure rethrows, so the waker still sees the error.
+     *
+     * Records no activity itself: whoever asked for the wake did ({@link wakeStrand},
+     * `HibernationManager.recordActivity`), and {@link serviceWake}'s own probe must not.
      */
     private handleStrandWake;
+    /**
+     * Undo a failed {@link resumeStrandRuntime}, but only when the rebuild itself failed — this
+     * caller's, or the one it joined in `resumeStrand` — which leaves the instance `'error'`. A
+     * failure before the rebuild (the cohort seed read) built nothing, and may find the strand
+     * mid-build or just brought up by a concurrent wake or check-in; that runtime belongs to
+     * whoever is building or holding it, so quiescing it here would stop a node still in use.
+     */
+    private rehibernateIfResumeFailed;
+    /**
+     * Put a strand whose rebuild or wake window failed back to `'hibernating'`, through a
+     * best-effort quiesce that releases any runtime left up. `resumeStrand` leaves a failed
+     * strand `'error'`, which nothing retries: `HibernationManager` wakes only
+     * `idle`/`hibernating` strands, and reads any other status after a check-in as "woke",
+     * ending its chain. Safe to run twice for one failure (a wake that joined a failed
+     * check-in's rebuild): quiescing a quiesced strand only marks it.
+     *
+     * The quiesce writes the status itself, ordered before any resume requested meanwhile;
+     * this writes it only when the quiesce failed, since a failed release leaves the status
+     * alone.
+     */
+    private rehibernateAfterFailedResume;
     /**
      * Rebuild a quiesced strand's runtime, re-resolving the volatile cohort input
      * first: the discovery seed may have grown since the strand last ran. Shared by
      * the wake (`handleStrandWake`) and check-in (`handleStrandCheckIn`) paths so both
-     * apply the same fresh resolution. `resumeStrand` is idempotent
-     * (returns the live instance unchanged) as a backstop against double-resume.
+     * apply the same fresh resolution. `resumeStrand` returns a live instance unchanged
+     * and joins a rebuild already in flight, so the two paths never build twice.
      */
     private resumeStrandRuntime;
     /**
@@ -1884,15 +2013,17 @@ export declare class CadreNode implements SAppIdLookup {
      * 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
+     *   1. 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`).
+     *   2. If activity landed since `activityMark`, leave the strand `active` (return
+     *      `true`); otherwise quiesce it, which marks it `hibernating` again (return `false`).
+     *      A wake or activity that lands during that quiesce rebuilds the strand after it.
      *
-     * @returns whether activity was observed during the window (strand left active).
+     * @param activityMark - `instance.lastActivity` as the caller read it BEFORE bringing the
+     *   strand up. The bring-up records none, and every writer assigns a FRESH `Date`, so a
+     *   changed reference means a wake or activity landed during the resume or the window —
+     *   not millisecond-resolution noise.
+     * @returns whether activity was observed (strand left active).
      */
     private runWakeWindow;
     /**
@@ -1923,9 +2054,10 @@ export declare class CadreNode implements SAppIdLookup {
      * published (e.g. re-attaching its own orphan after a restart) founds it, and attaching
      * anyone else's row joins, without the caller needing to know which it is.
      *
-     * A joined row (no `founder: true`) this party's control database does not hold — a
-     * strand joined from another party — is remembered in the node's joined-strand store, so it is re-offered as
-     * `strand:discovered` after a restart (see {@link forgetJoinedStrand}).
+     * A joined row (no `founder: true`) this party's control database does not name — a
+     * strand joined from another party — is remembered in the node's joined-strand store, so it
+     * is re-offered as `strand:discovered` after a restart, and published party-wide by an
+     * owner machine's reconcile pass (see {@link forgetJoinedStrand}).
      *
      * A rejected call leaves nothing running but DOES leave the sApp config
      * registered, deliberately: both an explicit retry and the {@link StrandWatcher}'s
@@ -2104,7 +2236,7 @@ export declare class CadreNode implements SAppIdLookup {
      * — and with it the consent re-seat foreclosure — does propagate; but the physical row
      * deletion cannot be replayed, and `queryStrands` reads raw (no retired-stamp filter),
      * so siblings that already hold the row keep running the strand until the collection
-     * itself converges (logged loudly; see the delete-while-alone durability note in
+     * itself converges (logged loudly; see "Deletes made while alone" in
      * docs/architecture.md).
      *
      * A no-op (no throw, no tombstone) when the row is already absent — but a
@@ -2167,10 +2299,10 @@ export declare class CadreNode implements SAppIdLookup {
      * NOTE: "founding machine" here is the ROW's provenance, not the launch's resolved
      * `founder` flag — so an explicit `founder: false` over a row this machine published
      * still mints, an owner-signed write a caller that said "I am not founding" did not ask
-     * for. Harmless (the party needs that identity for the strand either way, and the mint
-     * is insert-if-absent) and unreachable today: the one explicit `founder: false` caller
-     * passes a row with a null `FounderOwnerKey`. If a caller ever pairs `founder: false`
-     * with its own published row, gate the mint on the resolved flag too.
+     * for. Reached by a storage replica of a row this machine published (always a joiner,
+     * see {@link launchStrand}) and kept on purpose: the party needs that identity for the
+     * strand either way, the mint is insert-if-absent, and a closed-strand replica runs its
+     * membership reconciler — which seats its own `MemberPeer` binding — only with a party key.
      */
     private resolveStrandPartyKey;
     /**
@@ -2291,6 +2423,15 @@ export declare class CadreNode implements SAppIdLookup {
      * A founder launch refused as pre-split (`PreSplitStrandIdentityError`) is recorded in
      * {@link strandLaunchRefusals} for the formation arm, then rethrown; a founder launch
      * that succeeds clears the record (it ran the bootstrap's pre-split check and passed).
+     *
+     * An absent `sAppConfig` launches a storage replica ({@link CadreNodeConfig.hostUnclaimedStrands}),
+     * which is ALWAYS a joiner whatever the row says: the founder bootstrap writes the sApp
+     * into `Strand.Header`, and a replica has none. So a self-founded row whose watcher poll
+     * wins the race against its app's `addStrand` after a restart comes up as a replica — and
+     * so does a `foundStrand` whose publish a watcher poll saw before its attach. A claim
+     * that finds a tracked replica upgrades it in place, over the same node and store
+     * ({@link StrandInstanceManager.attachSApp}), BEFORE any founding: the founder bootstrap
+     * needs the sApp the attach supplies.
      */
     private launchStrand;
     /**
@@ -2298,6 +2439,19 @@ export declare class CadreNode implements SAppIdLookup {
      * tracked instance in place, or start a fresh one.
      */
     private startOrFoundStrand;
+    /**
+     * {@link startOrFoundStrand} for a strand the manager already tracks: a claim of a
+     * storage replica gives it the app's schema in place, then a founder request founds it,
+     * waking a quiesced instance so the bootstrap has run before this resolves. Emits
+     * nothing — `strand:started` fired when the instance launched.
+     *
+     * A launch of the strand still in flight (the watcher's launch racing an app's
+     * `addStrand`, in either order) is waited out first: until its build settles the tracked
+     * instance is `'starting'` with no database, and returning it would resolve `addStrand`
+     * with a strand the app cannot use — and skip that call's first-sync wait, which only a
+     * `'syncing'` instance gets. If that launch fails, this rejects too: its record is gone.
+     */
+    private claimTrackedStrand;
     /**
      * Resolve a strand's discovery seed — the dialable strand-network multiaddr
      * strings for cohort siblings. Membership comes from the control network's
@@ -2320,7 +2474,7 @@ export declare class CadreNode implements SAppIdLookup {
      * relay reservation — the gate denial there is fatal, not degraded. A
      * party-member relay answers the RPC (its control node admits us as a
      * member); a dedicated ops/ relay does not speak the protocol and the
-     * per-peer failure folds to `[]` — harmless, it has no membership gate and
+     * per-peer failure comes back `unreachable` — harmless, it has no membership gate and
      * needs no grant. The relay's direct addr rides along as the dial fallback
      * for a relay we are not yet connected to.
      */
@@ -2401,9 +2555,10 @@ export declare class CadreNode implements SAppIdLookup {
      * Record the announce timestamps {@link refreshDelegateGrants} throttles on,
      * for every relay a delegate-carrying announce pass dialed.
      *
-     * Recorded OPTIMISTICALLY at announce time: `collectStrandAddrs` folds
-     * per-peer failure to `[]` and reports no per-peer success, and threading
-     * success out would change its API for little gain. A failed INITIAL announce
+     * Recorded OPTIMISTICALLY at announce time, whatever `collectStrandAddrs`
+     * reports per peer: a dedicated `ops/` relay never speaks the strand-addr
+     * protocol, so recording only on success would re-announce to it on every
+     * reconcile tick, one wasted protocol negotiation each. A failed INITIAL announce
      * costs the strand supervisor its first attempt only (the relay denies the
      * reservation; every re-drive re-announces first through
      * {@link announceDelegateToRelay}); a failed REFRESH retries within
@@ -2441,16 +2596,16 @@ export declare class CadreNode implements SAppIdLookup {
      * again right away.
      *
      * Against a dedicated ops relay (no strand-addr RPC) the request fails per-peer
-     * and `collectStrandAddrs` folds it to `[]`: one wasted protocol negotiation per
+     * and `collectStrandAddrs` reports it `unreachable`: one wasted protocol negotiation per
      * re-drive attempt, bounded by the supervisor's backoff. Never throws on that
      * path; a relay addr that names no peer id is logged and skipped (the hook's
      * caller runs the drive regardless).
      *
      * NOTE: against a relay that is DOWN this hook costs up to two strand-addr
-     * timeouts (10 s each: dial by peer id, then by addr) before the reservation drive even
-     * starts, so one failed re-drive holds the supervisor `driving` for those 20 s plus the
-     * drive's own deadline — 34 s at the default declared link round trip, and longer on a host
-     * that declared a slower one (`link-budget.ts`).
+     * timeouts (dial by peer id, then by addr; 23 s each at the default declared link round trip)
+     * before the reservation drive even starts, so one failed re-drive holds the supervisor
+     * `driving` for those 46 s plus the drive's own deadline — 64 s at the default, and longer on
+     * a host that declared a slower one (`link-budget.ts`).
      * Bounded and harmless while the relay is unreachable anyway; if recovery
      * latency after a relay comes back ever matters, skip the announce when the
      * control node holds no connection to the relay (the drive's own dial fails
@@ -2460,9 +2615,10 @@ export declare class CadreNode implements SAppIdLookup {
     /** One strand's share of {@link refreshDelegateGrants}: announce to the relays whose grant is due. */
     private announceDelegateToDueRelays;
     /**
-     * Re-resolve each running strand's SIBLING addresses over the control mesh and
-     * merge them into that strand's own libp2p address book, throttled to once per
-     * {@link STRAND_PEER_ADDR_REFRESH_MS} per strand.
+     * Keep each running strand's own libp2p address book warm: re-merge its strand
+     * peer book on every pass, and re-ask each connected SIBLING for its strand
+     * addresses over the control mesh when that (sibling, strand) is due
+     * ({@link strandAddrAskDueAt}).
      *
      * Without this, a strand's address book is written exactly once — the
      * launch/resume seed — and everything below cadre-core that dials a strand peer
@@ -2472,6 +2628,12 @@ export declare class CadreNode implements SAppIdLookup {
      * re-resolved, and even the original seed addresses fall off at the peerStore's
      * one-hour expiry (see `peer-addr-book.ts`).
      *
+     * Due times are per (sibling, strand) and set from each sibling's own outcome, so
+     * a sibling that connects late — a phone joining after the party's always-on
+     * machines — is asked on the next tick, and one that could not answer or refused
+     * (its view of the membership may not include us yet) is retried within
+     * {@link STRAND_PEER_ADDR_RETRY_MS} rather than {@link STRAND_PEER_ADDR_REFRESH_MS}.
+     *
      * Distinct from {@link refreshDelegateGrants}, deliberately: that pass covers
      * RELAYS on a `DELEGATE_GRANT_TTL_MS / 2` throttle to keep circuit-relay
      * admission grants alive, this one covers SIBLINGS on an address-expiry
@@ -2485,20 +2647,49 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private refreshStrandPeerAddrs;
     /**
-     * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings, union their
-     * answers with this strand's peer-book addresses, and merge the lot into the strand's
-     * address book. Errors are logged and swallowed so one strand's failure never costs
-     * the others their refresh.
+     * The siblings {@link refreshStrandPeerAddrs} may ask this pass: the connected
+     * cohort, or none when enumeration fails (logged, never thrown).
+     *
+     * `connectedSiblingTargets`' membership read is unbounded, and with zero
+     * connections its answer is empty whatever the table holds, so decide it from the
+     * connection list instead of paying for the read once a tick.
+     *
+     * NOTE: otherwise the read runs on EVERY tick with a running strand, not only when
+     * some (sibling, strand) is due: pruning a departed sibling needs the current
+     * target set, and whether anyone is due cannot be told without it (a connected
+     * non-member never gets a due time to compare). One more `CadrePeer` read per 15 s
+     * tick, on top of the two `runReconcileControlCohort` already makes; if those reads
+     * get costly, share one row-set across the pass (see the NOTE there) rather than
+     * skipping ticks here.
+     *
+     * NOTE: one strand-addr RPC per (running strand × due sibling) — each a tiny
+     * request/response on an already-open control connection. If a node ever runs
+     * MANY strands at once, batch the RPC to carry several strand ids per request
+     * rather than one fan-out per strand.
+     */
+    private strandAddrRefreshTargets;
+    /**
+     * One strand's share of {@link refreshStrandPeerAddrs}: RPC the siblings that are
+     * due, union their answers with this strand's peer-book addresses, and merge the
+     * lot into the strand's address book. Errors are logged and swallowed so one
+     * strand's failure never costs the others their refresh.
      *
-     * `targets` may be EMPTY — a solo node, or one whose only control peers are strangers.
-     * The peer-book addresses still have to be re-merged in that case: nothing re-resolves
-     * another party's addresses, so this periodic re-merge is the ONLY thing standing
-     * between them and the peerStore's one-hour expiry. A strand with neither a sibling to
-     * ask nor a book entry does nothing and leaves its throttle unstamped, so the next
-     * reconcile tick retries rather than sitting out the whole refresh interval having
-     * done nothing.
+     * The peer book merges on EVERY pass, whether or not any sibling is due or
+     * connected: nothing re-resolves another party's addresses, so this re-merge is the
+     * ONLY thing standing between them and the peerStore's one-hour expiry — and it is
+     * also how a re-formation's freshly carried addresses reach a running strand on the
+     * next tick. A strand with nobody due and no book entry does nothing.
      */
     private refreshOneStrandPeerAddrs;
+    /**
+     * RPC `due` siblings for `strandId` and set each one's next due time from its own
+     * outcome: an answer, even an empty one, waits the full refresh interval; anything
+     * else retries in {@link STRAND_PEER_ADDR_RETRY_MS} (or the refresh interval, if
+     * configured shorter). Stamped before the caller
+     * re-checks that the strand is still running, so a strand torn down mid-pass still
+     * records who was asked.
+     */
+    private askSiblingsForStrandAddrs;
     /**
      * Merge strand-network addresses into ONE strand node's libp2p address book,
      * attributed per peer. Best-effort throughout: an address-book write must never
@@ -2539,20 +2730,28 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private getStrandMultiaddrs;
     /**
-     * Leave a strand joined from another party: forget its remembered join, so no later
-     * start re-offers it, then {@link stopStrand} it here. The "leave" a joiner has, since it
-     * cannot {@link unpublishStrand} a row its party's control database never held. For one
-     * of this party's own strands the forget is a no-op and this is just {@link stopStrand}.
+     * Leave a strand joined from another party, for the whole party: remove its party-wide
+     * `JoinedStrand` row (owner-signed, with a `Revocation` tombstone), then this machine's
+     * unpublished record, its strand peer book entries and any session-kept entry, then
+     * {@link stopStrand} it here. Every other machine's watcher then sees the row gone and
+     * detaches the strand, a storage replica included; a machine offline at the time reaps the
+     * row once the tombstone reaches it. The joiner's counterpart of {@link unpublishStrand},
+     * which only works on a row the party's own `Strand` table holds. For one of those, or for
+     * a join still local-only, there is no party-wide row and this is a local forget plus
+     * {@link stopStrand}.
+     *
+     * The other members of the strand are not told, and this party's membership row in the
+     * strand stays, so a later re-formation reuses the same identity.
      *
-     * Touches nothing beyond this node — the other members are not told, and this party's
-     * membership row in the strand stays.
+     * @throws when a party-wide row exists and this machine cannot sign its removal (not an
+     *   enrolled owner) — {@link stopStrand} stops the strand on this machine only — or when
+     *   the party-wide table cannot be read.
      */
     forgetJoinedStrand(strandId: string): Promise<void>;
     /**
-     * Record `row` as a join from another party when this party's control database holds no
-     * row for it — the one case nothing else would re-offer after a restart. Skips the write
-     * when an identical record is already there (an app re-claiming a remembered join on
-     * every start), and keeps the first `joinedAt`.
+     * Record `row` as a join from another party when this party's control database names it
+     * neither as its own strand nor as a party-wide join — the one case nothing else would
+     * re-offer after a restart (`JoinedStrandSession.rememberForeign`).
      *
      * Best-effort, for {@link addStrand}: a failure costs the strand its re-offer after the
      * next restart, not this attach, so it is reported and the attach goes on.
@@ -2567,16 +2766,25 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private rememberForeignStrand;
     /**
-     * Self-revocation arm of the joined-strand record: a party removed from a strand must
-     * not re-attach it on every launch. The strand keeps running this session — the
-     * `strand:revoked` contract is that nothing is torn down for the app — and is gone
-     * after the next start. The join record is a no-op for this party's own strands, which
-     * have none; the strand peer book is forgotten either way, since a removed party must
-     * not keep dialing the strand's peers.
+     * Self-revocation arm of the joined-strand records: a party removed from a strand must
+     * not re-attach it on every launch of every machine. The strand keeps running this
+     * session here — the `strand:revoked` contract is that nothing is torn down for the app —
+     * and its party-wide row is queued for removal by the next connected owner reconcile pass
+     * (`JoinedStrandSession.forgetAfterThisSession`). A no-op for this party's own strands,
+     * which have neither record; the strand peer book is forgotten either way, since a
+     * removed party must not keep dialing the strand's peers.
+     *
+     * NOTE: accepted tradeoff — a sibling machine that has not raised `strand:revoked` itself
+     * detaches the strand (`strand:stopped`) when the party-wide removal reaches it, instead
+     * of keeping it for the session, which weakens "nothing is stopped on the removed
+     * machine's behalf" for siblings. Weighed against a party-wide row that brings a revoked
+     * strand back on every start of every machine. Revisit if apps need the "you were
+     * removed" screen on every device: the sibling could re-check its own revocation state
+     * (`refreshRevocationEnforcement`) before detaching a vanished joined row.
      *
      * NOTE: a manager can re-admit a removed party directly (`addMemberByManager`), and the
-     * membership loop then finishes the join on its own — but the record is gone by then, so
-     * the next start does not re-attach the strand. Re-forming records it again. If direct
+     * membership loop then finishes the join on its own — but the records are gone by then,
+     * so the next start does not re-attach the strand. Re-forming records it again. If direct
      * re-admission becomes a routine flow, re-record the join when the revoked-peer gate
      * clears for this node.
      */
@@ -2661,7 +2869,10 @@ export declare class CadreNode implements SAppIdLookup {
      */
     notifyStrandActivity(strandId: string, reason?: string): void;
     /**
-     * Force wake a hibernating strand
+     * Force wake a hibernating strand. A requested wake is activity, recorded before the
+     * wake starts: a check-in holding the strand — or rebuilding it, a rebuild this wake then
+     * joins — leaves it up instead of re-quiescing it at the end of its window. Once awake the
+     * strand's idle countdown runs, so it hibernates again if nothing uses it.
      */
     wakeStrand(strandId: string): Promise<void>;
     /**
@@ -2672,7 +2883,7 @@ export declare class CadreNode implements SAppIdLookup {
      * 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'` +
+     * path as the timer (`quiesceStrand`, which marks it `hibernating`, then
      * `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}).
      */
@@ -2697,9 +2908,14 @@ export declare class CadreNode implements SAppIdLookup {
      * 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.
+     * one re-hibernate decision. A wake or activity from elsewhere that lands during
+     * the resume or the window leaves the strand up; this call's own wake does not.
+     * Afterwards a strand left up has its idle countdown running, and a re-hibernated one
+     * gets back the check-in chain this call interrupted — it never gains one it lacked,
+     * so a strand the mobile runner force-hibernated stays down until the next push.
+     * Returns `{ serviced: false }` (never throws) when
+     * the node is not running or the strand is unknown, and surfaces a wake or
+     * window failure as `{ serviced: true, hadActivity: false }`.
      *
      * @param strandId - the strand a push said has pending activity.
      * @param opts.windowMs - override the live-window duration (defaults to the
@@ -2710,6 +2926,12 @@ export declare class CadreNode implements SAppIdLookup {
     }): Promise<ServiceWakeResult>;
     /** Body of {@link serviceWake}; serialised per-strand by its coalescing guard. */
     private runServiceWake;
+    /**
+     * The wake and window of {@link runServiceWake}. A failure in either — the network
+     * unreachable inside a Doze grant, say — must not throw out of a background task, so it
+     * reports no activity. Each stage cleans up only what it owns.
+     */
+    private wakeAndHoldForService;
     /**
      * Get the control network node (for advanced use)
      */
@@ -2737,8 +2959,8 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * BUDGET: the supervisor's first attempt is what `start()` waits on — deliberately the drive's
      * ordinary deadline rather than a boot-specific one. That deadline is now COUNTED, four link
-     * round trips at the declared `network.linkRoundTripMs` (14 s at its default, where it was a
-     * fixed 10 s): a healthy dial-plus-reserve is sub-second even over a WAN, so this is slack for
+     * round trips at the declared `network.linkRoundTripMs` plus the relay's two admission
+     * decisions (18 s at its default, where it was a fixed 10 s): a healthy dial-plus-reserve is sub-second even over a WAN, so this is slack for
      * a slow link, while going much longer would make a dead relay indistinguishable from a hung
      * start and much shorter would fail nodes on links that were merely slow. A host that declares
      * a slower link lengthens it without touching this path — `link-budget.ts`. The retries carry
@@ -2819,7 +3041,7 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * @param ownerPrivateKey - The owner's private key (base64url encoded)
      */
-    initializeSeedBootstrap(ownerPrivateKey: string): void;
+    initializeSeedBootstrap(ownerPrivateKey: string): Promise<void>;
     /**
      * Push the multiaddrs that future invites should advertise. Pass `null` to
      * revert to the libp2p-reported addresses (the default). The host calls this
@@ -2954,7 +3176,8 @@ export declare class CadreNode implements SAppIdLookup {
      * 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.
+     * participates in; it acks once it has decided, before the strand is up. The
+     * dial deadlines derive from this node's `network.linkRoundTripMs`.
      *
      * @param targetPeerId - The hibernating cadre peer to wake.
      * @param strandId - The strand the caller knows has pending activity.
@@ -2967,11 +3190,23 @@ export declare class CadreNode implements SAppIdLookup {
      * This is for drone nodes that need to receive seeds without being an owner.
      * Does not require an owner key.
      */
-    enableSeedListener(): void;
+    enableSeedListener(): Promise<void>;
     /**
      * Get the seed bootstrap service (for advanced use)
      */
     getSeedBootstrapService(): SeedBootstrapService | null;
+    /**
+     * Make `service` this node's seed service and register its inbound seed handler.
+     * The field is set before the registration is awaited, so a concurrent
+     * {@link enableSeedListener} finds it and does not register a second handler; a
+     * failed registration puts the previous service back and rethrows.
+     *
+     * NOTE: libp2p's registrar stores the handler before its peer-store merge, so a
+     * failed merge leaves SEED_PROTOCOL registered with no service owning it and a retry
+     * here rejects as a duplicate; if peer-store writes can fail in practice, unhandle on
+     * a non-duplicate failure (never on a duplicate — that handler belongs to someone else).
+     */
+    private installSeedBootstrapService;
     /**
      * The event callbacks every {@link SeedBootstrapService} this node owns is
      * wired with — shared by the owner-capable service ({@link initializeSeedBootstrap})
@@ -3162,7 +3397,7 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * @param options - Configuration for the solicitation service
      */
-    initializeStrandSolicitation(options?: StrandSolicitationServiceOptions): void;
+    initializeStrandSolicitation(options?: StrandSolicitationServiceOptions): Promise<void>;
     /**
      * Get the strand solicitation service (for advanced use)
      */
@@ -3185,7 +3420,9 @@ export declare class CadreNode implements SAppIdLookup {
     formStrand(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<FormStrandResult>;
     /**
      * Remember the strand a formation just joined (see {@link joinedStrandStore}), so it
-     * is re-offered after a restart even when the app is killed before its `addStrand`.
+     * is re-offered after a restart even when the app is killed before its `addStrand`, and
+     * published party-wide by the next connected owner reconcile pass. A re-join also
+     * cancels a party-wide removal a self-revocation queued for the strand.
      * Last in {@link formStrand}, after the membership adoption, so a failure here leaves
      * the party key and staged invitation in place for the re-formation it asks for.
      *
@@ -3249,9 +3486,15 @@ export declare class CadreNode implements SAppIdLookup {
      *   founder's publish/launch paths mint it, so this is a not-yet-converged sibling.)
      *   The manager maps the throw to a clean retryable rejection BEFORE the formation
      *   token is spent.
-     * - Closed host strand with no running local instance/database → throw, same mapping:
-     *   a joiner admitted without an invitation would look joined and never become a
-     *   member, and a responder not running the strand cannot serve its sync anyway.
+     * - Closed host strand whose runtime is HIBERNATING or being quiesced → woken first
+     *   ({@link wakeHostStrandForFormation}, bounded by `signal`), then issued as below. In
+     *   every state the redemption counts as activity, so the host stays up for the
+     *   joiner's first sync.
+     * - Closed host strand with no running local instance/database (never launched, still
+     *   starting, or a hibernating one whose wake failed or outran `signal`) →
+     *   throw, same mapping: a joiner admitted without an invitation would look joined and
+     *   never become a member, and a responder not running the strand cannot serve its sync
+     *   anyway.
      * - Closed host strand whose LIVE rows carry the pre-split fingerprint
      *   (`assertNotPreSplitStrand`) → throw `PreSplitStrandIdentityError`, same mapping as
      *   the recorded refusal. Covers the responders that never ran a refused founder launch:
@@ -3261,7 +3504,12 @@ export declare class CadreNode implements SAppIdLookup {
      * permanent diagnosis. Identity is checked BEFORE the runtime: it is the cheaper read
      * and the more actionable diagnosis when both are missing (a missing runtime is
      * transient, a missing identity is not), and it keeps the branch reachable without
-     * standing a strand runtime up.
+     * standing a strand runtime up. For the same reason every control-database check runs
+     * before a wake: a strand that cannot issue anyway is not woken.
+     *
+     * `signal` is the formation's provisioning budget. Once it has aborted nothing is
+     * issued — the joiner has already been told to retry, and an invitation written now
+     * would only sit in the strand until it expires.
      *
      * The invitation expires `MEMBERSHIP_INVITE_TTL_MS` from now — see that constant for
      * the slow-joiner / lost-result tradeoff.
@@ -3277,6 +3525,30 @@ export declare class CadreNode implements SAppIdLookup {
      * not a retry.
      */
     private issueStrandMembershipInvite;
+    /**
+     * Count a bound closed-strand redemption as activity on the host strand, and wake the
+     * strand when it is HIBERNATING or being quiesced (its database is closing) so the
+     * membership invitation can be issued. Only reached after the formation manager has
+     * authorized the redemption (token, disclosure, outside approval, seat pre-check), so only
+     * a caller already entitled to the strand's member key can cause a wake. No other state is
+     * woken — never launched or still starting is not something this node recovers from on
+     * demand; the caller's live-database check refuses those.
+     *
+     * The activity is recorded in every state, through the hibernation manager rather than
+     * {@link recordStrandActivity}, whose push fan-out would wake this party's phones for
+     * nothing. It keeps the host up for the joiner's first sync: a live strand's idle timer
+     * restarts, a check-in window that happens to have the strand live sees activity and
+     * leaves it up instead of re-quiescing it, and a hibernating strand has its idle →
+     * hibernate timers re-armed once the wake leaves it `active`. The explicit
+     * {@link wakeStrand} coalesces onto the wake `recordActivity` began, and still wakes when
+     * `recordActivity` is a no-op (hibernation disabled but the strand force-hibernated, or
+     * the manager stopped).
+     *
+     * Bounded by `signal` (the formation's provisioning budget): when it aborts first this
+     * throws — a retryable rejection, token unspent — and leaves the wake running, so the
+     * joiner's retry finds the strand live.
+     */
+    private wakeHostStrandForFormation;
     /**
      * Remember the responder's strand-network addresses for a strand this node just
      * formed in the strand peer book (see {@link strandPeerBookStore}), so the strand's