@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/group-peer-manager.js

@@ -1,27 +1,33 @@
 import { getDelegationStore } from '@kubun/store-delegation';
 import { getP2PStore } from '@kubun/store-p2p';
-import { createGroupPeer } from '@kumiai/rpc';
+import { readGroupAnchor } from '@kumiai/mls';
+import { createGroupPeer, RecoveryRequiredError } from '@kumiai/rpc';
 import { createHubLike } from '../hub/hub-like.js';
-import { readGroupAnchor } from './group-anchor.js';
+import { createLoopbackLogHub } from '../hub/loopback-log-hub.js';
+import { createHubServerDIDResolver } from '../hub/server-did.js';
+import { createTunnelListeners } from '../sync/tunnel-listeners.js';
+import { createAnchorStore } from './anchor-store.js';
+import { createAppCursorStore } from './app-cursor-store.js';
+import { applyAccessDefaultSetToken, bootstrapGroupLedger, processBroadcast } from './broadcast.js';
+import { reprojectGroupSettings } from './circle-projection.js';
+import { adoptCommitJournalBlob, readJournalRequestID, settleLostControlRequest } from './commit-adoption.js';
+import { createCommitJournal } from './commit-journal.js';
+import { settleControlRequest } from './control-request.js';
 import { createGroupCrypto } from './group-crypto.js';
 import { buildGroupHandlers } from './group-handlers.js';
 import { createGroupMLS } from './group-mls.js';
 import { groupProtocols } from './group-protocols.js';
+import { ledgerEntryDigest } from './ledger.js';
+import { createPeerPresence } from './peer-presence.js';
 const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
 /**
  * Send-side union → procedure mapping — the inverse of `buildGroupHandlers`.
  *
  * Translates a {@link GroupBroadcastMessage} into the matching group-rpc
  * `dispatch` on a peer's control/sync protocol surface. Variants with no carried
- * procedure (catalog control) and the legacy catch-up variants (now a `gather`,
- * not a dispatch) are logged and no-op'd, matching the receive side.
+ * procedure (catalog control) are logged and no-op'd, matching the receive side.
  */ export async function dispatchMessage(peer, message, logger) {
     switch(message.type){
-        case 'ledger:entry':
-            await peer.protocol('control').dispatch('control/ledgerEntry', {
-                token: message.token
-            });
-            return;
         case 'delegation:share':
             await peer.protocol('control').dispatch('control/delegationShare', {
                 token: message.token,
@@ -40,11 +46,44 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
                 hlc: message.hlc
             });
             return;
+        case 'access-default:set':
+            // Every signed field rides the wire. The token covers the operation, not
+            // just its author, so a payload that drops or renames one produces a frame
+            // the receiver verifies and correctly rejects.
+            await peer.protocol('control').dispatch('control/accessDefaultSet', {
+                modelID: message.modelID,
+                permissionType: message.permissionType,
+                rule: message.rule,
+                ownerDID: message.ownerDID,
+                hlc: message.hlc,
+                auth: message.auth
+            });
+            return;
+        case 'access-default:remove':
+            await peer.protocol('control').dispatch('control/accessDefaultRemove', {
+                modelID: message.modelID,
+                permissionTypes: message.permissionTypes,
+                ownerDID: message.ownerDID,
+                hlc: message.hlc,
+                auth: message.auth
+            });
+            return;
         case 'mutation:apply':
             await peer.protocol('sync').dispatch('sync/mutationApply', {
                 entries: message.entries
             });
             return;
+        case 'peer:announce':
+            // `announcerDID` is deliberately NOT sent. It is what the receiver's own
+            // lane resolved the sender to; putting it on the wire would create the
+            // self-asserted DID field the whole design exists to avoid.
+            await peer.protocol('peer').dispatch('peer/announce', {
+                label: message.label,
+                availability: message.availability,
+                capabilities: message.capabilities,
+                hlc: message.hlc
+            });
+            return;
         case 'catalog:create':
         case 'catalog:update':
         case 'catalog:delete':
@@ -52,54 +91,347 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
                 type: message.type
             });
             return;
-        case 'ledger-catchup:request':
-        case 'ledger-catchup:reply':
-            logger?.warn('dispatchMessage: unsupported via broadcast (catch-up uses gather)', {
-                type: message.type
+        default:
+            {
+                // Exhaustiveness gate. A broadcast type with no case here used to fall off
+                // the switch and vanish without a log — which is how the access-default
+                // frames were assembled, signed, and silently dropped on the sender.
+                const unhandled = message;
+                throw new Error(`dispatchMessage: unrouted message type ${unhandled.type}`);
+            }
+    }
+}
+/**
+ * True while a rotation has torn the per-epoch protocol runtimes down and not yet
+ * rebuilt them.
+ *
+ * `createGroupPeer.rebuildEpoch` clears its runtime map synchronously and repopulates
+ * it after awaiting every teardown, and `dispatch` takes no mutex — upstream says so
+ * where it re-reads the anchor around a seal. So a broadcast that arrives inside that
+ * window reaches `surfaceFor` with an empty map and gets `Unknown protocol: <name>`,
+ * which is a transient rotation artefact and not a routing mistake. It is matched on
+ * the message because the throw is a bare `Error`.
+ *
+ * Announce-on-epoch-change is exactly the trigger that publishes at a rotation, so
+ * this window is on its normal path rather than at its edge.
+ */ function isEpochRebuilding(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.startsWith('Unknown protocol: ');
+}
+/** Attempt delays for {@link throughRotation}, ms. Bounded: a rebuild is local work. */ const ROTATION_RETRY_DELAYS = [
+    10,
+    30,
+    90,
+    270
+];
+/**
+ * Run one lane operation, retrying only while the peer's runtimes are mid-rebuild.
+ *
+ * Safe to retry because the throw happens BEFORE anything is sealed or published:
+ * `surfaceFor` is what fails, so a retry cannot duplicate a frame. Every other
+ * failure — a refused publish, an unrouted message type — propagates on the first
+ * attempt, which is what keeps this from papering over a real fault.
+ */ export async function throughRotation(op, label, logger) {
+    let attempt = 0;
+    while(true){
+        try {
+            return await op();
+        } catch (error) {
+            const delay = ROTATION_RETRY_DELAYS[attempt];
+            if (delay == null || !isEpochRebuilding(error)) {
+                throw error;
+            }
+            attempt++;
+            logger?.debug('lane operation met an epoch rebuild; retrying', {
+                label,
+                attempt
             });
-            return;
+            await new Promise((resolve)=>setTimeout(resolve, delay));
+        }
+    }
+}
+/**
+ * Pull the signed entry tokens out of an untyped `control/ledgerCatchup` reply.
+ * The gather surface hands back `unknown`, so validate defensively: a
+ * non-conforming reply (version skew, a malicious responder) contributes no
+ * entries rather than throwing. Non-string items are filtered — the token
+ * verification downstream is the real authority.
+ */ /**
+ * The signed access-default tokens a `control/policyCatchup` reply carried, or
+ * null when the reply was not that shape. Only the envelope is read here; every
+ * token is verified where it is applied.
+ */ function extractPolicyDefaults(value) {
+    if (value == null || typeof value !== 'object') {
+        return null;
+    }
+    const defaults = value.defaults;
+    if (!Array.isArray(defaults) || defaults.some((entry)=>typeof entry !== 'string')) {
+        return null;
+    }
+    return defaults;
+}
+function extractLedgerEntries(value) {
+    if (value == null || typeof value !== 'object') {
+        return null;
     }
+    const entries = value.entries;
+    if (!Array.isArray(entries)) {
+        return null;
+    }
+    return entries.filter((entry)=>typeof entry === 'string');
+}
+/**
+ * Filter signed ledger tokens against the group's current ledger by content
+ * digest, then rebuild any survivors into ONE fresh commit through the same peer.
+ * Reports whether anything was re-issued, so a caller can tell an empty filter
+ * from a re-issue.
+ *
+ * An already-held token is NEVER re-appended: kubun's ledger is position-keyed
+ * with no dedup, so a second copy lands at a later position and can silently
+ * revert a newer admin write over that role.
+ *
+ * `requestID` rides the rebuilt commit, so its own `onAccepted` settles the
+ * request — this helper never settles. Single attempt: the re-issue's own
+ * {@link LaneResult} is deliberately not re-processed, because a further loss
+ * resurfaces on the next `commit()`.
+ */ async function reissueLedgerTokens(peer, tokens, deps, requestID) {
+    const held = await deps.registry.readHandle(deps.groupID, (handle)=>handle.getLedger());
+    const heldDigests = new Set(held.map((token)=>ledgerEntryDigest(token)));
+    const surviving = tokens.filter((token)=>!heldDigests.has(ledgerEntryDigest(token)));
+    if (surviving.length === 0) {
+        return false;
+    }
+    const rebuild = deps.buildLedgerRedrive(deps.groupID, surviving, requestID);
+    await peer.commit(rebuild);
+    return true;
+}
+/**
+ * Re-drive a lost `ledger` commit through {@link reissueLedgerTokens}, once.
+ *
+ * Filtering can empty the set (everything already landed): settle `committed`
+ * directly rather than re-entering the lane. Otherwise the re-issued commit's own
+ * `onAccepted` settles, so this path adds no second settle. No request id means
+ * no request rode this commit — the tokens still re-drive, nothing settles.
+ */ async function redriveLostLedgerCommit(peer, lost, deps) {
+    const requestID = readJournalRequestID(lost.journal);
+    const reissued = await reissueLedgerTokens(peer, lost.tokens, deps, requestID);
+    if (!reissued && requestID != null) {
+        await settleControlRequest({
+            stores: deps.stores,
+            requestID,
+            outcome: 'committed',
+            ...deps.emitter != null ? {
+                emitter: deps.emitter
+            } : {},
+            ...deps.logger != null ? {
+                logger: deps.logger
+            } : {}
+        });
+    }
+}
+/**
+ * Publish a commit through the peer and act on what the lane hands back.
+ *
+ * A `LaneResult` can carry both a `lost` and a `reenact`; handle each
+ * independently. A lost `ledger` is re-issuable from its tokens, an `invite` or
+ * `remove` is not, so those settle `lost` here.
+ *
+ * The housekeeping is CONTAINED — never let it throw. By the time it runs THIS
+ * commit has landed and its request is settled, while `lost` and `reenact` name
+ * other work; an escaping throw would have the producer's per-request catch
+ * settle the terminal request `rejected`, writing a failure over a success and
+ * nulling the artifact for a member who really was added. That covers
+ * `RecoveryRequiredError` too: reaching {@link commitWithRecovery} would re-run
+ * the ORIGINAL `build` after its commit landed, publishing a second copy outside
+ * the never-re-append filter.
+ */ export async function commitThroughPeer(peer, build, deps) {
+    const result = await peer.commit(build);
+    try {
+        const lost = result.lost;
+        if (lost != null) {
+            if (lost.kind === 'invite' || lost.kind === 'remove') {
+                await settleLostControlRequest(lost.journal, deps);
+            } else if (lost.kind === 'ledger') {
+                await redriveLostLedgerCommit(peer, lost, deps);
+            }
+        }
+        const reenact = result.reenact;
+        if (reenact != null && reenact.length > 0) {
+            await reissueLedgerTokens(peer, reenact, deps);
+        }
+    } catch (error) {
+        deps.logger?.warn('post-commit housekeeping failed; the accepted commit stands', {
+            groupID: deps.groupID,
+            error
+        });
+    }
+    return result;
+}
+/**
+ * True when a caught error is the lane's stranded/incomplete-ledger gate. The
+ * error crosses the hub transport and is rebuilt from a wire code, so a peer
+ * talking to a real hub holds a RECONSTRUCTED instance whose prototype chain no
+ * longer passes `instanceof` — the same hazard `isHeadMismatch` documents. Match
+ * on the name as well, or a remote strand reads as an unknown failure and the
+ * heal never fires.
+ */ function isRecoveryRequired(error) {
+    if (error instanceof RecoveryRequiredError) {
+        return true;
+    }
+    return typeof error === 'object' && error != null && error.name === 'RecoveryRequiredError';
+}
+/**
+ * Publish a commit and, on the lane's stranded/incomplete-ledger gate, self-heal.
+ *
+ * The gate conflates an incomplete ledger — repaired by a plain ledger GATHER —
+ * with a true strand, repaired only by a full rejoin via `recover()`, so the
+ * cheaper remedy runs first: gather + retry once, then `recover()` + retry once,
+ * then propagate. Each remedy runs AT MOST ONCE (≤3 commit attempts): upstream
+ * forbids a tight retry loop, and `recover()` already bounds itself with its own
+ * deadline loop. When `recover()` cannot advance, rethrow the ORIGINAL gate error
+ * so the caller settles against the real cause. The retry carries the original
+ * `requestID`, so a healed commit settles `committed` through its own
+ * `onAccepted` rather than surfacing as a failure.
+ */ export async function commitWithRecovery(params) {
+    const { peer, build, deps, gatherLedger } = params;
+    try {
+        return await commitThroughPeer(peer, build, deps);
+    } catch (error) {
+        if (!isRecoveryRequired(error)) {
+            throw error;
+        }
+        // Cheaper remedy first: gather the ledger, then retry once.
+        await gatherLedger();
+        try {
+            return await commitThroughPeer(peer, build, deps);
+        } catch (afterGather) {
+            if (!isRecoveryRequired(afterGather)) {
+                throw afterGather;
+            }
+            // The gather did not clear it — a true strand. Recover once.
+            const recovery = await peer.recover();
+            if (recovery.reenact.length > 0) {
+                await reissueLedgerTokens(peer, recovery.reenact, deps);
+            }
+            if (!recovery.advanced) {
+                // No live responder healed the strand: settle the original outcome.
+                throw error;
+            }
+            // Retry once more; a further gate throw is NOT recovered again.
+            return await commitThroughPeer(peer, build, deps);
+        }
+    }
+}
+/**
+ * Rejoin the group through `GroupPeer.recover()` and map its outcome to a
+ * {@link RejoinResult}. `recover()` publishes the external commit under a head
+ * compare-and-set and bootstraps the ledger; it bounds itself, so it is never
+ * wrapped in a loop. Any `reenact` tokens it hands back — held here but absent
+ * from the authenticated ledger after the rejoin — are re-issued through the
+ * same {@link reissueLedgerTokens} filter every lane outcome uses. `advanced`
+ * maps to `recovered`; a peer that could not advance (no live responder) maps to
+ * `recovery-failed` without throwing.
+ */ export async function recoverThroughPeer(peer, deps) {
+    const result = await peer.recover();
+    if (result.reenact.length > 0) {
+        await reissueLedgerTokens(peer, result.reenact, deps);
+    }
+    return result.advanced ? {
+        status: 'recovered'
+    } : {
+        status: 'recovery-failed'
+    };
 }
 export function createGroupPeerManager(params) {
     // One reconnecting HubLike per hub URL (shared across that hub's groups).
     const hubLikes = new Map();
     // One peer per (group, hub), keyed `${groupID}|${hubURL}`.
     const peers = new Map();
+    // groupID → the peer over its in-process loopback log, for a group with no hub
+    // bound. Kept out of `bindings`/`hubGroups`: it is a commit lane of last
+    // resort, not a binding, so it never joins a broadcast fan-out (there is no
+    // co-member on the other side to reach).
+    const loopbackPeers = new Map();
     // Groups the device currently belongs to.
     const joined = new Set();
     // Active bindings: groupID → set of hub URLs that have a live peer.
     const bindings = new Map();
     // Reverse index for GC: hub URL → set of groupIDs with a peer on it.
     const hubGroups = new Map();
+    // Trigger subscriptions this manager holds (the registry's epoch notice, each
+    // hub adapter's lifecycle), released on stop.
+    const triggerUnsubscribes = [];
     const { logger } = params;
+    // Owns the hub-DID cache for every hub this manager dials: the row is read (and
+    // discovery written) here rather than in the client factory, because an adopted
+    // DID has to outlive the connection that resolved it and a rotation has to reach
+    // the application.
+    const serverDIDs = createHubServerDIDResolver({
+        stores: params.stores,
+        emitter: params.emitter,
+        fetch: params.runtime?.fetch ?? globalThis.fetch,
+        ...logger != null ? {
+            logger
+        } : {}
+    });
     const getHubLike = (hubURL)=>{
         const existing = hubLikes.get(hubURL);
         if (existing != null) {
             return existing;
         }
         const hub = createHubLike({
-            // Resolved per (re)connect: the pinned server DID is read fresh from the
-            // local hub row so a row update re-arms TOFU on the next reconnect.
-            createClient: async ()=>{
-                const store = await getP2PStore(params.stores);
-                const row = await store.getHubByURL(hubURL);
-                return params.createHubClient(hubURL, {
-                    ...params.onServerDIDObserved != null ? {
-                        onServerDID: (serverDID)=>params.onServerDIDObserved?.({
-                                hubURL,
-                                serverDID
-                            })
-                    } : {},
-                    ...row?.server_did != null ? {
-                        expectedServerDID: row.server_did
-                    } : {}
+            // Resolved per (re)connect, so a DID adopted after a rotation is picked up
+            // by the very next dial. Nothing verifies the signer of what comes back:
+            // the earlier build pinned the first response's `iss` and hard-failed any
+            // later mismatch, which turned a redeployed hub into an outage. Discovery
+            // plus the refresh below replaced it.
+            createClient: async (signal)=>{
+                const serverID = await serverDIDs.resolve(hubURL, signal);
+                return params.createHubClient(hubURL, serverID == null ? {} : {
+                    serverID
                 });
             },
+            // The hub refused us. Either the audience we signed is stale or we are not
+            // welcome; `/info` is what tells the two apart.
+            onAccessDenied: ()=>serverDIDs.refresh(hubURL),
             localDID: params.localDID,
             ...logger != null ? {
                 logger
+            } : {},
+            ...params.hubReconnectBackoff?.baseMs != null ? {
+                backoffBaseMs: params.hubReconnectBackoff.baseMs
+            } : {},
+            ...params.hubReconnectBackoff?.maxMs != null ? {
+                backoffMaxMs: params.hubReconnectBackoff.maxMs
+            } : {},
+            ...params.hubReconnectBackoff?.jitter != null ? {
+                backoffJitter: params.hubReconnectBackoff.jitter
             } : {}
         });
+        // TRIGGER — hub connect. Fires on the first connect and on every reconnect,
+        // for every group this hub carries: a device that has just (re)appeared has to
+        // say so and ask who else is here, because nothing else will tell it.
+        //
+        // The listener is awaited by the adapter's state machine, so the work is
+        // scheduled rather than done here.
+        const unsubscribe = hub.events?.on('status', (event)=>{
+            if (event.type !== 'connected') {
+                return;
+            }
+            for (const groupID of hubGroups.get(hubURL) ?? []){
+                presence.scheduleRefresh(groupID, 'hub-connected');
+                // Policy rides this trigger as well, and it cannot ride the pruned-window
+                // one alone. A gap is only REPORTED when this device already held a read
+                // position on the topic; a device that never processed a control frame
+                // before it went away holds none, so it reads from the hub's oldest
+                // retained frame and is told nothing is missing. It has lost exactly the
+                // same rules, so returning is itself a reason to ask.
+                schedulePolicyCatchup(groupID, 'hub-connected');
+            }
+        });
+        if (unsubscribe != null) {
+            triggerUnsubscribes.push(unsubscribe);
+        }
         hubLikes.set(hubURL, hub);
         return hub;
     };
@@ -114,57 +446,191 @@ export function createGroupPeerManager(params) {
             graphStore: params.graphStore,
             graph: params.graph,
             selfDID: params.localDID,
+            identity: params.identity,
             storeUnreadable: params.storeUnreadable,
             defaultAccessLevel: params.defaultAccessLevel,
-            // Forwarding is dropped in this cutover — the receive path applies locally
-            // only and never re-broadcasts to other groups.
-            forwarding: undefined,
+            // Both halves or neither: the apply path treats a `forwarding` config with
+            // no `scheduleBroadcast` as disabled, silently.
+            forwarding: params.forwarding,
+            scheduleBroadcast: params.scheduleBroadcast,
             emitter: params.emitter,
             hlc: params.hlc,
             // Reads the genesis anchor baked into the MLS GroupContext so role
             // projection on a received ledger entry runs against the authenticated
             // epoch-0 creator. Null for a group with no anchor (e.g. external).
             getGroupAnchor: (groupID)=>params.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle)),
+            // The ledger every control projection folds from, read off the same handle
+            // under the same lock.
+            getGroupLedger: (groupID)=>params.registry.readHandle(groupID, async (handle)=>handle.ledger),
+            // The registry's published scalar, not a handle read: an announce stamps
+            // the epoch it was heard at, and taking the group mutex for a number the
+            // registry already publishes would serialize the apply behind whatever
+            // holds it.
+            getGroupEpoch: (groupID)=>params.registry.groupEpoch(groupID) ?? undefined,
+            // Only the projection rebuild is transactional. The reads that precede it
+            // take the registry's per-group mutex, and an install or gather waits on
+            // the network — a transaction spanning either holds kubun's single SQLite
+            // connection across it.
+            withProjectionTransaction: (run)=>params.stores.withTransaction(async (tx)=>await run(await getP2PStore(tx))),
             logger
         };
     };
-    // Create a peer for one (group, hub) pair, idempotent on the key. The peer is
-    // eager (createGroupPeer restores the anchored MLS handle + opens the receive
-    // drain in its constructor), so it must only be called once the group's MLS
-    // state is seeded (i.e. after `groupJoined`).
-    const createPeer = async (groupID, hubURL)=>{
-        const key = peerKey(groupID, hubURL);
-        if (peers.has(key)) {
-            return;
+    // The epoch the group's MLS handle is at right now, for seeding a peer's
+    // crypto port. A group with no restorable handle answers 0 — the same value
+    // the port would have started from — so a peer for a group whose MLS state is
+    // missing still constructs rather than failing the whole binding.
+    const readGroupEpoch = async (groupID)=>{
+        try {
+            return await params.registry.readHandle(groupID, (handle)=>Number(handle.epoch));
+        } catch (error) {
+            logger?.warn('could not read group epoch for peer seeding', {
+                groupID,
+                error
+            });
+            return 0;
         }
-        const processParams = await buildProcessParams();
-        // Re-check after the await: a concurrent call may have installed this peer,
-        // or `removeGroup` may have left the group, while the store resolved. The
-        // emitter handlers (groupJoined/groupLeft/hubBound/hubUnbound) are not
-        // serialized, so installing a live peer for a no-longer-joined group here
-        // would leak a drain + apply mutations for a left group.
-        if (peers.has(key) || !joined.has(groupID)) {
-            return;
+    };
+    // Re-materialize the group's folded commit-hub designation onto the local
+    // `is_commit_hub` flag from the handle's current ledger. A designation folds
+    // before this device binds the hub it names — a joiner folds the invite's
+    // settings, then binds the suggested hub — and a fold naming an unbound hub
+    // clears the flag, so the newly-bound row stays unflagged until an unrelated
+    // settings fold unless the bind itself re-runs the projection. This is that
+    // re-run: fold-authoritative and idempotent, it flags the just-bound hub the
+    // moment it matches the standing designation. A group with no readable anchor
+    // (e.g. external, or MLS state not yet seeded) has nothing to fold.
+    const reprojectSettingsForGroup = async (groupID)=>{
+        try {
+            const anchor = await params.registry.readHandle(groupID, (handle)=>readGroupAnchor(handle));
+            if (anchor == null) {
+                return;
+            }
+            const ledger = await params.registry.readHandle(groupID, (handle)=>handle.ledger);
+            // Atomic: the settings reproject writes the group row, every circle's
+            // `open` flag and the commit-hub designation from one fold, and a crash
+            // part-way leaves the three disagreeing — a device with no flagged commit
+            // hub cannot commit at all.
+            await params.stores.withTransaction(async (tx)=>{
+                await reprojectGroupSettings({
+                    store: await getP2PStore(tx),
+                    groupID,
+                    anchor,
+                    ledger,
+                    ...logger != null ? {
+                        logger
+                    } : {}
+                });
+            });
+        } catch (error) {
+            logger?.warn('could not re-materialize commit-hub designation on bind', {
+                groupID,
+                error
+            });
         }
-        const peer = createGroupPeer({
-            hub: getHubLike(hubURL),
-            crypto: createGroupCrypto(params.registry, groupID),
+    };
+    // Instantiate a peer for a group over a given log. The peer is eager
+    // (createGroupPeer restores the anchored MLS handle + opens the receive drain
+    // in its constructor), so this must only run once the group's MLS state is
+    // seeded (i.e. after `groupJoined`).
+    const instantiatePeer = ({ groupID, hub, processParams, initialEpoch })=>createGroupPeer({
+            hub,
+            crypto: createGroupCrypto({
+                registry: params.registry,
+                groupID,
+                initialEpoch,
+                ...params.runtime != null ? {
+                    runtime: params.runtime
+                } : {}
+            }),
             mls: createGroupMLS({
                 registry: params.registry,
                 stores: params.stores,
+                identity: params.identity,
                 hlc: params.hlc,
                 groupID,
+                // A received commit's control entries fold into this device's
+                // projections, so the changes they carry reach subscribers as the same
+                // domain events a broadcast-delivered entry fires.
+                emitter: params.emitter,
                 ...logger != null ? {
                     logger
                 } : {}
             }),
+            journal: createCommitJournal(params.stores, groupID),
+            anchorStore: createAnchorStore(params.stores, groupID),
+            appCursorStore: createAppCursorStore(params.stores, groupID),
+            adoptJournalled: (blob)=>adoptCommitJournalBlob(blob, {
+                    registry: params.registry,
+                    groupID,
+                    stores: params.stores,
+                    // A commit adopted after a restart settles the request it was for, and
+                    // the app is subscribed on this device's emitter — the same one the
+                    // inline `onAccepted` settle announces on, so a replayed settle and a
+                    // live one are indistinguishable to a subscriber.
+                    ...params.emitter != null ? {
+                        emitter: params.emitter
+                    } : {},
+                    ...logger != null ? {
+                        logger
+                    } : {}
+                }),
             localDID: params.localDID,
             protocols: groupProtocols,
             handlers: buildGroupHandlers(processParams, groupID),
-            ...params.getRandomID != null ? {
-                getRandomID: params.getRandomID
+            // App frames published while this device was away aged out of the hub's
+            // retention before it came back for them. The frames themselves are gone
+            // for good — nothing here replays them.
+            //
+            // TRIGGER — a gap below the retention floor. It is not an error: what the
+            // gap means is "someone may have said something I will never read", and the
+            // repair for the peer lane is to re-announce and re-ask rather than to
+            // reconstruct the lost frames. An announcement is idempotent state, so a
+            // fresh one supersedes every lost one.
+            onAppWindowPruned: (event)=>{
+                logger?.warn('app frames aged out below the hub retention floor', {
+                    groupID: event.groupID,
+                    protocol: event.protocol,
+                    cursor: event.cursor,
+                    oldest: event.oldest
+                });
+                presence.scheduleRefresh(groupID, 'app-window-pruned');
+                // Policy has no idempotent re-announce to fall back on — a rule is its
+                // owner's statement and nobody else can restate it — so the repair is to
+                // ask. Fire-and-forget: this runs on the receive path, and a gather
+                // awaited here would stall the very lane it is repairing.
+                schedulePolicyCatchup(event.groupID, 'app-window-pruned');
+            },
+            ...params.runtime != null ? {
+                runtime: params.runtime
             } : {}
         });
+    // Create a peer for one (group, hub) pair, idempotent on the key.
+    const createPeer = async (groupID, hubURL)=>{
+        const key = peerKey(groupID, hubURL);
+        if (peers.has(key)) {
+            return;
+        }
+        const processParams = await buildProcessParams();
+        // Re-check after the await: a concurrent call may have installed this peer,
+        // or `removeGroup` may have left the group, while the store resolved. The
+        // emitter handlers (groupJoined/groupLeft/hubBound/hubUnbound) are not
+        // serialized, so installing a live peer for a no-longer-joined group here
+        // would leak a drain + apply mutations for a left group.
+        if (peers.has(key) || !joined.has(groupID)) {
+            return;
+        }
+        const initialEpoch = await readGroupEpoch(groupID);
+        // Re-check once more: the epoch read takes the group's handle mutex, so it
+        // is another suspension point a concurrent create/leave can slip through.
+        if (peers.has(key) || !joined.has(groupID)) {
+            return;
+        }
+        const peer = instantiatePeer({
+            groupID,
+            hub: getHubLike(hubURL),
+            processParams,
+            initialEpoch
+        });
         peers.set(key, peer);
         let groupSet = bindings.get(groupID);
         if (groupSet == null) {
@@ -179,6 +645,67 @@ export function createGroupPeerManager(params) {
         }
         hubSet.add(groupID);
     };
+    // Resolve the group's loopback peer, creating it on first demand and reusing
+    // it thereafter. A group with no hub bound has no other member and therefore
+    // exactly one writer — this device — so its commit lane compares-and-sets a
+    // head against an in-process log rather than skipping the lane entirely. The
+    // log is ephemeral: what survives a restart is the MLS handle and the
+    // CommitJournal, both durable elsewhere.
+    //
+    // Creation is deferred to the first commit rather than done when the group is
+    // joined, because instantiating a peer restores the MLS handle from the store,
+    // and no DB transaction may span a lane operation. Joining is driven from
+    // inside the engine's write transaction (a device booting with a pre-existing
+    // group re-runs it), which on a single-connection SQLite would deadlock
+    // against the handle read. Committing is already outside any transaction, so
+    // creating here is safe — and a group that never commits constructs nothing.
+    const ensureLoopbackPeer = async (groupID)=>{
+        const existing = loopbackPeers.get(groupID);
+        if (existing != null) {
+            return existing;
+        }
+        if (!joined.has(groupID)) {
+            return undefined;
+        }
+        const processParams = await buildProcessParams();
+        // Re-check after the await, as in `createPeer`: a concurrent caller may have
+        // installed the loopback already (two must never be constructed), or the
+        // group may have been left while the store resolved.
+        const raced = loopbackPeers.get(groupID);
+        if (raced != null) {
+            return raced;
+        }
+        if (!joined.has(groupID)) {
+            return undefined;
+        }
+        const initialEpoch = await readGroupEpoch(groupID);
+        // Re-check once more: the epoch read takes the group's handle mutex, so it
+        // is another suspension point a concurrent caller or leave can slip through.
+        const racedOnEpoch = loopbackPeers.get(groupID);
+        if (racedOnEpoch != null) {
+            return racedOnEpoch;
+        }
+        if (!joined.has(groupID)) {
+            return undefined;
+        }
+        const peer = instantiatePeer({
+            groupID,
+            hub: createLoopbackLogHub(),
+            processParams,
+            initialEpoch
+        });
+        loopbackPeers.set(groupID, peer);
+        return peer;
+    };
+    // Dispose the group's loopback peer if it has one.
+    const disposeLoopbackPeer = async (groupID)=>{
+        const peer = loopbackPeers.get(groupID);
+        if (peer == null) {
+            return;
+        }
+        loopbackPeers.delete(groupID);
+        await peer.dispose();
+    };
     // Dispose one (group, hub) peer, updating both indexes, and GC the hub's
     // HubLike once its last peer is gone.
     const disposePeer = async (groupID, hubURL)=>{
@@ -245,14 +772,117 @@ export function createGroupPeerManager(params) {
             throw rejected[0]?.reason;
         }
     };
+    const broadcastToPeers = async (groupID, message)=>{
+        await fanOutToPeers(groupID, (peer)=>throughRotation(()=>dispatchMessage(peer, message, logger), `broadcast ${message.type}`, logger), 'broadcast');
+    };
+    // Declared ahead of the presence it is triggered from, and assigned below once
+    // the hub lookup it needs exists.
+    let tunnelListeners;
+    const presence = createPeerPresence({
+        stores: params.stores,
+        localDID: params.localDID,
+        hlc: params.hlc,
+        // Declaring a profile is what puts this device in co-members' projections,
+        // so it is also what makes it dialable — the listeners come up here rather
+        // than waiting for the next epoch.
+        onProfileSet: ()=>{
+            for (const groupID of joined){
+                void tunnelListeners?.reconcile(groupID);
+            }
+        },
+        getGroupEpoch: (groupID)=>params.registry.groupEpoch(groupID) ?? undefined,
+        publish: broadcastToPeers,
+        // Gathered over every hub-peer of the group, concurrently: `timeoutMs` bounds
+        // each window, so in sequence a dark hub burns its whole window before the
+        // next is tried. A member reachable via two hubs answers on both; the
+        // duplicate is dropped by DID, not counted twice.
+        query: async (groupID, param, options)=>{
+            const groupSet = bindings.get(groupID);
+            if (groupSet == null || groupSet.size === 0) {
+                return [];
+            }
+            const gatherOptions = {
+                ...options.timeoutMs != null ? {
+                    timeoutMs: options.timeoutMs
+                } : {},
+                ...options.quorum != null ? {
+                    quorum: options.quorum
+                } : {}
+            };
+            const gathered = await Promise.all(Array.from(groupSet, async (hubURL)=>{
+                const peer = peers.get(peerKey(groupID, hubURL));
+                if (peer == null) {
+                    return [];
+                }
+                try {
+                    return await throughRotation(()=>peer.protocol('peer').gather('peer/query', param, gatherOptions), 'gather peer/query', logger);
+                } catch (error) {
+                    logger?.warn('peer query gather failed on a hub', {
+                        groupID,
+                        hubURL,
+                        error
+                    });
+                    return [];
+                }
+            }));
+            return gathered.flat();
+        },
+        applyAnnouncement: async (groupID, message)=>{
+            const applyParams = await buildProcessParams();
+            await processBroadcast(applyParams, message, groupID);
+        },
+        joinedGroupIDs: ()=>[
+                ...joined
+            ],
+        ...logger != null ? {
+            logger
+        } : {}
+    });
+    // Needs the host runtime as well as the handlers: every spawned session mints
+    // its own id, and this package runs where the Node defaults are not available.
+    const tunnelRuntime = params.runtime;
+    tunnelListeners = params.syncHandlers == null || tunnelRuntime == null ? undefined : createTunnelListeners({
+        stores: params.stores,
+        registry: params.registry,
+        identity: params.identity,
+        localDID: params.localDID,
+        runtime: tunnelRuntime,
+        syncHandlers: params.syncHandlers,
+        tunnelHub: (groupID)=>{
+            const hubURL = bindings.get(groupID)?.values().next().value;
+            return hubURL == null ? undefined : getHubLike(hubURL);
+        },
+        ...logger != null ? {
+            logger
+        } : {},
+        ...params.tunnelIdleTimeoutMs != null ? {
+            idleTimeoutMs: params.tunnelIdleTimeoutMs
+        } : {}
+    });
+    // TRIGGER — epoch change. A member added at this epoch was never on the old
+    // topic, so every earlier announcement is unreachable to it: the rotation is
+    // exactly when the group needs to be told again who is here.
+    //
+    // The notice arrives INSIDE the group mutex and inside the advancing
+    // operation's transaction, so the announce is scheduled and coalesced rather
+    // than run here — a device walking a catch-up of many commits would otherwise
+    // announce once per commit.
+    //
+    // The same rotation is when the roster changed and when the inbox topics moved,
+    // so the tunnel listeners are re-derived here too: a member added at this epoch
+    // has nobody answering it until this runs, and a removed one keeps a listener
+    // for a peer that may no longer decrypt.
+    triggerUnsubscribes.push(params.registry.onEpochChanged((groupID)=>{
+        presence.scheduleAnnounce(groupID, 'epoch-changed');
+        void tunnelListeners?.reconcile(groupID);
+    }));
     const addGroup = async (groupID)=>{
         joined.add(groupID);
         const store = await getP2PStore(params.stores);
         const hubs = await store.listHubsByGroupID(groupID);
         if (hubs.length === 0) {
-            logger?.warn('group has no hub bindings, no peer created', {
-                groupID
-            });
+            // No peer to bring up: a hubless group's loopback lane is created on its
+            // first commit, so joining stays free of any MLS handle restore.
             return;
         }
         const results = await Promise.allSettled(hubs.map((hub)=>createPeer(groupID, hub.url)));
@@ -265,8 +895,126 @@ export function createGroupPeerManager(params) {
                 });
             }
         });
+        // After the peers, so the binding the listeners read exists.
+        await tunnelListeners?.reconcile(groupID);
+    };
+    /** Groups with a catch-up round already open, so the triggers cannot stack. */ const policyCatchupInFlight = new Set();
+    /** Groups already asked once on connect — see {@link schedulePolicyCatchup}. */ const policyCatchupAsked = new Set();
+    /**
+   * Run a policy catch-up off the trigger's own stack.
+   *
+   * Both triggers fire from inside lane machinery — a hub lifecycle listener the
+   * adapter awaits, and the drain's pruned-window callback — and this reads the
+   * store before it publishes anything. A store read taken there can land inside
+   * a write transaction the setup path still holds, which on single-connection
+   * SQLite is a deadlock, not a slow query. Presence defers for the same reason.
+   */ const schedulePolicyCatchup = (groupID, reason)=>{
+        if (reason === 'hub-connected') {
+            // Once per group for the life of this process. A reconnect is only
+            // evidence of a gap the FIRST time — after that this device has been
+            // draining the lane, so a gap would be reported as a pruned window and
+            // asking again on every reconnect would be chatter with no question
+            // behind it.
+            if (policyCatchupAsked.has(groupID)) {
+                return;
+            }
+            policyCatchupAsked.add(groupID);
+        }
+        setTimeout(()=>{
+            void requestPolicyCatchup(groupID).catch((error)=>{
+                logger?.warn('policy catch-up failed', {
+                    groupID,
+                    reason,
+                    error
+                });
+            });
+        }, 0);
     };
-    return {
+    /**
+   * Ask the group's reachable co-members to restate their OWN access-defaults.
+   *
+   * The repair for rules this device can no longer read: an access-default frame
+   * is retained, but only as far as the hub's retention floor, and below it the
+   * frame is gone for good. Presence repairs the same gap by re-announcing —
+   * that works because an announcement is a device's statement about itself. A
+   * rule is its owner's statement about its own models and nobody else can make
+   * it, so policy can only be repaired by ASKING.
+   *
+   * Bounded by who is live: an owner that is offline right now leaves its stale
+   * rule in place until it can answer. That is the same bound `peer/query` has,
+   * and it is a property of the design rather than of this implementation.
+   */ const requestPolicyCatchup = async (groupID)=>{
+        if (policyCatchupInFlight.has(groupID)) {
+            // The triggers overlap deliberately (a reconnect may also report a pruned
+            // window), and a second round would ask the same members the same question
+            // inside the first one's window.
+            return 0;
+        }
+        policyCatchupInFlight.add(groupID);
+        try {
+            // The group's DESIGNATED commit lane, never every bound hub. A device can
+            // be bound to a hub the designation does not name, and the point of the
+            // designation is that the group's control traffic stays off it — a repair
+            // fanning out to every binding would put frames on a hub the group agreed
+            // not to use.
+            //
+            // Resolved here rather than through `selectCommitPeer`, which falls back to
+            // creating the group's loopback lane: that is right for a commit, which
+            // must land somewhere, and wrong for a repair — a group with no hub has no
+            // co-member to ask, and building a lane to discover that is a side effect
+            // this has no business having.
+            const p2pStore = await getP2PStore(params.stores);
+            const commitHub = await p2pStore.getCommitHub(groupID);
+            const commitPeer = commitHub == null ? undefined : peers.get(peerKey(groupID, commitHub.url));
+            if (commitPeer == null) {
+                return 0;
+            }
+            const replies = await commitPeer.protocol('control').gather('control/policyCatchup', {});
+            // Every reply is applied, unlike the ledger's: a member restates only its
+            // own rules, so two replies are two owners' policies rather than two
+            // accounts of one thing. Nothing here chooses between them — each token is
+            // verified, bound to its issuer, and applied only if strictly newer than
+            // the stored anchor.
+            const graphStore = params.graphStore;
+            let applied = 0;
+            for (const reply of replies){
+                const defaults = extractPolicyDefaults(reply.value);
+                if (defaults == null) {
+                    continue;
+                }
+                for (const token of defaults){
+                    try {
+                        const landed = await applyAccessDefaultSetToken({
+                            graphStore,
+                            token,
+                            groupID,
+                            ...logger != null ? {
+                                logger
+                            } : {}
+                        });
+                        if (landed) {
+                            applied++;
+                        }
+                    } catch (error) {
+                        logger?.warn('policy catch-up entry failed to apply', {
+                            groupID,
+                            error
+                        });
+                    }
+                }
+            }
+            return applied;
+        } catch (error) {
+            logger?.warn('policy catch-up gather failed', {
+                groupID,
+                error
+            });
+            return 0;
+        } finally{
+            policyCatchupInFlight.delete(groupID);
+        }
+    };
+    const manager = {
         async start (groupIDs) {
             const results = await Promise.allSettled(groupIDs.map((id)=>addGroup(id)));
             results.forEach((result, index)=>{
@@ -279,8 +1027,10 @@ export function createGroupPeerManager(params) {
             });
         },
         addGroup,
+        presence,
         async removeGroup (groupID) {
             joined.delete(groupID);
+            await tunnelListeners?.removeGroup(groupID);
             const groupSet = bindings.get(groupID);
             const urls = groupSet != null ? [
                 ...groupSet
@@ -288,6 +1038,10 @@ export function createGroupPeerManager(params) {
             for (const hubURL of urls){
                 await disposePeer(groupID, hubURL);
             }
+            await disposeLoopbackPeer(groupID);
+        },
+        async reconcileTunnelListeners (groupID) {
+            await tunnelListeners?.reconcile(groupID);
         },
         async addBinding (groupID, hubURL) {
             if (!joined.has(groupID)) {
@@ -297,36 +1051,273 @@ export function createGroupPeerManager(params) {
                 });
                 return;
             }
+            // The group now has a real hub, so it stops using its loopback: dispose it
+            // before the real peer exists, so no window lets a commit pick the
+            // loopback while a hub-backed lane is coming up.
+            await disposeLoopbackPeer(groupID);
             await createPeer(groupID, hubURL);
+            // If the standing designation names the hub just bound, flag it now rather
+            // than waiting for the next settings fold.
+            await reprojectSettingsForGroup(groupID);
+            // A group with no hub could not be dialled at all, so this is where its
+            // members become answerable.
+            await tunnelListeners?.reconcile(groupID);
         },
         async removeBinding (groupID, hubURL) {
             await disposePeer(groupID, hubURL);
+            // The listeners hold the drain of whichever hub is bound; the one they were
+            // built on may be the one that just left.
+            await tunnelListeners?.reconcile(groupID);
         },
-        async broadcast (groupID, message) {
-            await fanOutToPeers(groupID, (peer)=>dispatchMessage(peer, message, logger), 'broadcast');
+        broadcast: broadcastToPeers,
+        async selectCommitPeer (groupID) {
+            const groupSet = bindings.get(groupID);
+            if (groupSet == null || groupSet.size === 0) {
+                // No hub-backed peer: a hubless group commits against its loopback log,
+                // created here on first demand.
+                return await ensureLoopbackPeer(groupID);
+            }
+            const store = await getP2PStore(params.stores);
+            const commitHub = await store.getCommitHub(groupID);
+            if (commitHub != null) {
+                const designated = peers.get(peerKey(groupID, commitHub.url));
+                if (designated != null) {
+                    return designated;
+                }
+                logger?.warn('designated commit hub has no live peer; using lowest-URL fallback', {
+                    groupID,
+                    hubURL: commitHub.url
+                });
+            } else {
+                logger?.warn('group has no commit-hub designation; using lowest-URL fallback', {
+                    groupID
+                });
+            }
+            // Deterministic fallback for a legacy group (or a designated hub with no
+            // live peer): of the bound hubs that have a live peer, the one whose URL
+            // sorts first. Determinism has to hold ACROSS devices — every device must
+            // pick the same hub, or two devices commit to two logs and fork the group —
+            // so the key is the hub's shared identity, its URL, which every device that
+            // bound it holds the same string for. `created_at` is stamped locally at
+            // bind time, so two devices that bound the same hubs in a different order
+            // would order them differently and each pick its own. Compared by code unit
+            // rather than `localeCompare`, whose collation is a property of the host.
+            const hubs = await store.listHubsByGroupID(groupID);
+            const ordered = [
+                ...hubs
+            ].sort((a, b)=>a.url < b.url ? -1 : a.url > b.url ? 1 : 0);
+            for (const hub of ordered){
+                const peer = peers.get(peerKey(groupID, hub.url));
+                if (peer != null) {
+                    return peer;
+                }
+            }
+            // Every bound hub's peer is gone. NOT the loopback: this group is
+            // hub-backed, so a co-member reads its commits from a hub, and a commit
+            // written to the loopback log is unrecoverable — that log is ephemeral and
+            // never replayed, and binding a hub later carries nothing forward. The
+            // device would report a promotion or a circle it alone believes in. No
+            // lane is the honest answer; the callers surface it and the operator
+            // retries when a hub answers again.
+            logger?.warn('no live peer on any bound hub; refusing to commit', {
+                groupID
+            });
+            return undefined;
         },
-        async sendCommit (groupID, commit) {
-            await fanOutToPeers(groupID, (peer)=>peer.localCommitted(commit), 'sendCommit');
+        async commit (groupID, build) {
+            const peer = await this.selectCommitPeer(groupID);
+            if (peer == null) {
+                throw new Error(`cannot commit to group ${groupID}: no live commit-hub peer to publish through`);
+            }
+            // A user-initiated commit that hits the lane's stranded/incomplete-ledger
+            // gate heals itself and settles rather than surfacing the throw: gather the
+            // ledger first, then `recover()` only if the strand persists. The gather is
+            // a manager method, so the layered remedy lives here (where it is reachable)
+            // rather than in the standalone `commitThroughPeer`.
+            return await commitWithRecovery({
+                peer,
+                build,
+                deps: {
+                    stores: params.stores,
+                    groupID,
+                    registry: params.registry,
+                    buildLedgerRedrive: params.buildLedgerRedrive,
+                    ...params.emitter != null ? {
+                        emitter: params.emitter
+                    } : {},
+                    ...logger != null ? {
+                        logger
+                    } : {}
+                },
+                gatherLedger: ()=>this.requestLedgerCatchup(groupID)
+            });
         },
-        async rejoinGroup (_groupID) {
-            // INERT stub: deep recovery is deferred. `mls.applyRecovery` deliberately
-            // throws (a GroupInfo lacks the missed path secrets → applying it forks the
-            // group), and tier-1 replay via `processCommit` is automatic, so there is
-            // nothing to drive here. The real path is Welcome re-admission — see
-            // docs/agents/plans/backlog/welcome-based-deep-recovery.md.
+        async rejoinGroup (groupID) {
+            // Rejoin the group's canonical commit hub through `recover()`: it mints a
+            // recovery request on the non-rotating rendezvous topic, a live member seals
+            // its GroupInfo, and the requester publishes the resulting external commit
+            // under a head compare-and-set — adopting nothing until the head accepts it,
+            // then gathering and head-verifying the ledger. `recover()` bounds itself,
+            // so it is not wrapped in a loop here. `recovery-failed` when no live
+            // responder answers (or the group has no lane); `recovered` once the rejoin
+            // landed and the ledger bootstrapped.
+            const peer = await this.selectCommitPeer(groupID);
+            if (peer == null) {
+                return {
+                    status: 'recovery-failed'
+                };
+            }
+            return await recoverThroughPeer(peer, {
+                stores: params.stores,
+                groupID,
+                registry: params.registry,
+                buildLedgerRedrive: params.buildLedgerRedrive,
+                ...params.emitter != null ? {
+                    emitter: params.emitter
+                } : {},
+                ...logger != null ? {
+                    logger
+                } : {}
+            });
+        },
+        requestPolicyCatchup,
+        async requestLedgerCatchup (groupID, options) {
+            const empty = {
+                applied: 0,
+                rejected: 0,
+                responders: 0
+            };
+            const groupSet = bindings.get(groupID);
+            if (groupSet == null || groupSet.size === 0) {
+                return empty;
+            }
+            const gatherOptions = {
+                ...options?.timeoutMs != null ? {
+                    timeoutMs: options.timeoutMs
+                } : {},
+                ...options?.quorum != null ? {
+                    quorum: options.quorum
+                } : {}
+            };
+            // Gather over every hub-peer of the group. A member reachable via two hubs
+            // replies on both; the duplicates are harmless because the first reply that
+            // reproduces the authenticated head ends the round and the install replaces
+            // the ledger wholesale — a second hub's copy is never reached. A single
+            // hub's failure is logged, not fatal — the reachable hubs still contribute
+            // their replies.
+            //
+            // The hubs are gathered CONCURRENTLY: `timeoutMs` bounds each gather, so in
+            // sequence an unreachable hub burns its whole timeout before the next one
+            // is even tried, and `joinPeerGroup` waits on this. Concurrently the round
+            // costs one timeout no matter how many hubs are dark.
+            const gathered = await Promise.all(Array.from(groupSet, async (hubURL)=>{
+                const peer = peers.get(peerKey(groupID, hubURL));
+                if (peer == null) {
+                    return [];
+                }
+                try {
+                    return await peer.protocol('control').gather('control/ledgerCatchup', {}, gatherOptions);
+                } catch (error) {
+                    logger?.warn('ledger catch-up gather failed on a hub', {
+                        groupID,
+                        hubURL,
+                        error
+                    });
+                    return [];
+                }
+            }));
+            const replies = gathered.flat();
+            if (replies.length === 0) {
+                return empty;
+            }
+            // Each reply is a WHOLE ledger, adopted or refused as one: it is checked
+            // against the authenticated head before a single entry folds, so a
+            // responder that withholds or transposes entries is dropped rather than
+            // merged. That is why the replies are tried in turn and the first one that
+            // reproduces the head ends the round — a second responder's list can only
+            // be the same ledger or a rejected one, never an addition to it.
+            //
+            // Run outside any transaction — the install and the durable append read
+            // the anchor through the shared-connection registry, so there is no
+            // single-connection SQLite deadlock (unlike an in-transaction apply).
+            const applyParams = await buildProcessParams();
+            const bootstrapParams = {
+                ...applyParams,
+                installGroupLedger: (id, tokens)=>params.registry.withHandle(id, async (handle)=>{
+                        await handle.bootstrapLedger(tokens);
+                        // Read under the same hold as the install: this is the roster that
+                        // install folded, not whatever a later operation may have left.
+                        return handle.roster;
+                    })
+            };
+            let responders = 0;
+            for (const reply of replies){
+                const entries = extractLedgerEntries(reply.value);
+                if (entries == null) {
+                    continue;
+                }
+                responders++;
+                try {
+                    const result = await bootstrapGroupLedger(bootstrapParams, entries, groupID);
+                    return {
+                        applied: result.applied,
+                        rejected: result.rejected,
+                        responders
+                    };
+                } catch (error) {
+                    // This responder's ledger did not reproduce the authenticated head —
+                    // it is incomplete or reordered. Nothing was written; try the next.
+                    logger?.warn('ledger catch-up responder rejected: ledger does not match the head', {
+                        groupID,
+                        entries: entries.length,
+                        error
+                    });
+                }
+            }
             return {
-                status: 'recovery-failed'
+                applied: 0,
+                rejected: 0,
+                responders
             };
         },
         peer (groupID, hubURL) {
             return peers.get(peerKey(groupID, hubURL));
         },
         getHubLike,
+        tunnelHub (groupID) {
+            const hubURL = bindings.get(groupID)?.values().next().value;
+            return hubURL == null ? undefined : getHubLike(hubURL);
+        },
+        async retryHubs () {
+            const live = [
+                ...hubLikes.values()
+            ];
+            if (live.length === 0) {
+                // Nothing is bound, so there is nothing to retry — and answering `true`
+                // here would tell a person their hub is reachable when no hub exists.
+                return false;
+            }
+            const outcomes = await Promise.all(live.map((hub)=>hub.retryNow().catch(()=>false)));
+            return outcomes.some((connected)=>connected);
+        },
         async stop () {
+            await presence.dispose();
+            // Before the hubs go: each listener holds a subscription on one of them,
+            // and its spawn loop re-arms until it is told to stop.
+            await tunnelListeners?.dispose();
+            for (const off of triggerUnsubscribes.splice(0)){
+                try {
+                    off();
+                } catch  {
+                // ignore
+                }
+            }
             const livePeers = [
-                ...peers.values()
+                ...peers.values(),
+                ...loopbackPeers.values()
             ];
             peers.clear();
+            loopbackPeers.clear();
             bindings.clear();
             hubGroups.clear();
             joined.clear();
@@ -341,4 +1332,5 @@ export function createGroupPeerManager(params) {
             await this.stop();
         }
     };
+    return manager;
 }