@relaycast/engine 8.11.2 → 8.11.4

package/dist/engine/node.js

@@ -6,8 +6,7 @@ import { actionInvocations, agents, agentNodeBindings, channelMembers, channels,
 import { randomHex, sha256Hex } from '../lib/crypto.js';
 import { codedError } from '../lib/httpError.js';
 import { acceptTaskInvocation, completeTaskInvocation } from './taskInvocation.js';
-import { runAtomic } from '../ports/database.js';
-import { isProviderAgentDeliveryReady } from '../ports/realtime.js';
+import { runAtomic, runAtomicWrites } from '../ports/database.js';
 import { generateId } from './snowflake.js';
 import { assertRegistrableAgentName } from './agent.js';
 import { rotateAgentIdentity } from './agentIdentity.js';
@@ -31,6 +30,35 @@ function directNodeNameForAgent(agentId) {
 function isImplicitDirectLocation(agent) {
     return agent.locationNodeId === directNodeIdForAgent(agent.id);
 }
+/**
+ * An agent adopted onto a node keeps a provider identity that node can serve:
+ * deliveries are pushed to the `(node, provider)` socket named by
+ * `agents.provider_name`, so a provider the node does not serve is a silent
+ * dead end. Precedence, most specific first:
+ *
+ *  1. The node already serves the agent's provider — keep it. It routes today,
+ *     and it is the closest thing to evidence of which provider owns the agent;
+ *     rewriting it would hand the agent to a sibling provider on the same host.
+ *  2. The node serves exactly one provider — adopt it; there is no other answer.
+ *  3. The node serves the synthetic `default` — adopt it as the generic
+ *     fallback, since the agent's own provider is not served here.
+ *  4. Otherwise (several named providers, none of them the agent's) nothing
+ *     identifies the owner, so the existing provider stands rather than guessing.
+ *
+ * A node with no live providers at all falls through to (4): no socket exists
+ * to adopt, and rewriting to a name nobody serves would not help. Callers pass
+ * only live provider names — a persisted-but-offline row is a historical
+ * manifest entry, not a connection deliveries can reach.
+ */
+function adoptNodeProviderName(current, nodeProviderNames) {
+    if (nodeProviderNames.includes(current))
+        return current;
+    if (nodeProviderNames.length === 1)
+        return nodeProviderNames[0];
+    if (nodeProviderNames.includes(DEFAULT_PROVIDER_NAME))
+        return DEFAULT_PROVIDER_NAME;
+    return current;
+}
 function normalizeCapabilities(capabilities) {
     return capabilities.map((capability) => (typeof capability === 'string' ? { name: capability } : capability));
 }
@@ -95,6 +123,69 @@ function supportsProviderDeliveryReadiness(registry) {
         && typeof registry.markProviderAgentsDeliveryReady === 'function'
         && typeof registry.isProviderAgentDeliveryReady === 'function';
 }
+/**
+ * Whether a provider's current registration advertised the delivery-cursor
+ * capability. Registration persists the advertised set, so later frames on the
+ * same provider can recover the handshake `node.register` negotiated without
+ * the client re-asserting it.
+ */
+async function providerAdvertisesDeliveryCursor(db, workspaceId, nodeId, providerName) {
+    const [provider] = await db
+        .select({ capabilities: nodeProviders.capabilities })
+        .from(nodeProviders)
+        .where(and(eq(nodeProviders.workspaceId, workspaceId), eq(nodeProviders.nodeId, nodeId), eq(nodeProviders.name, providerName)));
+    return provider?.capabilities?.some((capability) => capability.name === FLEET_DELIVERY_CURSOR_CAPABILITY) ?? false;
+}
+/**
+ * Capabilities that are NEGOTIATED at `node.register` (answered in its
+ * acceptance list and wired into the connection's delivery mode) rather than
+ * merely advertised. A heartbeat refreshes the provider's roster of spawn /
+ * action capacity; it is not a renegotiation, so it may neither drop nor
+ * introduce one of these. Dropping would demote a live cursor-gated connection
+ * that was deliberately denied the register-time flush — stranding its backlog;
+ * introducing would promote an immediate connection and replay frames that
+ * flush already sent. The registered value stands until the next
+ * `node.register`.
+ */
+const NEGOTIATED_PROTOCOL_CAPABILITIES = [FLEET_DELIVERY_CURSOR_CAPABILITY];
+function isNegotiatedProtocolCapability(capability) {
+    return NEGOTIATED_PROTOCOL_CAPABILITIES.includes(capability.name);
+}
+function withRegisteredProtocolCapabilities(heartbeatCapabilities, registeredCapabilities) {
+    return [
+        ...heartbeatCapabilities.filter((capability) => !isNegotiatedProtocolCapability(capability)),
+        ...registeredCapabilities.filter(isNegotiatedProtocolCapability),
+    ];
+}
+/**
+ * Whether the provider's LIVE connection negotiated cursor-gated delivery at
+ * `node.register` — i.e. whether it was denied the register-time flush and so
+ * depends on a later certification to replay.
+ *
+ * The registry owns that answer: `node.register` hands it the negotiated mode
+ * per connection, and a reconnect starts a fresh one. Ask it first. Only a
+ * registry that does not expose the mode (an out-of-process owner on an older
+ * contract) falls back to the persisted advertisement — which heartbeats keep
+ * off-limits (see `heartbeatNode`) precisely so the fallback answers for the
+ * registration rather than for the latest roster snapshot.
+ *
+ * When the method DOES exist, its `undefined` is an answer too: the connection
+ * asking is not the provider's current owner (a superseded connection whose
+ * frame queued behind the replacement's register). Reading the persisted
+ * advertisement then would classify a stale connection's sync by whichever
+ * registration owns the provider now — replaying certified deliveries to a
+ * connection that has not certified those sessions. A registry that can
+ * answer gets the last word; the fallback is only for one that cannot.
+ */
+async function connectionNegotiatedDeliveryCursor(db, registry, workspaceId, nodeId, providerName, connectionId) {
+    if (!supportsProviderDeliveryReadiness(registry))
+        return false;
+    if (registry.providerDeliveryReadinessMode) {
+        return registry.providerDeliveryReadinessMode(workspaceId, nodeId, providerName, connectionId)
+            === 'agent_scoped';
+    }
+    return providerAdvertisesDeliveryCursor(db, workspaceId, nodeId, providerName);
+}
 function requestId(message) {
     return message.id ?? generateId();
 }
@@ -540,11 +631,16 @@ export async function heartbeatNode(db, workspaceId, nodeId, providerName, messa
     }
     await runAtomic(db, async (tx) => {
         if (message.capabilities !== undefined) {
-            const caps = normalizeCapabilities(message.capabilities);
             const [existingProvider] = await tx
-                .select({ instanceId: nodeProviders.instanceId, maxAgents: nodeProviders.maxAgents, version: nodeProviders.version })
+                .select({
+                instanceId: nodeProviders.instanceId,
+                maxAgents: nodeProviders.maxAgents,
+                version: nodeProviders.version,
+                capabilities: nodeProviders.capabilities,
+            })
                 .from(nodeProviders)
                 .where(and(eq(nodeProviders.workspaceId, workspaceId), eq(nodeProviders.nodeId, nodeId), eq(nodeProviders.name, providerName)));
+            const caps = withRegisteredProtocolCapabilities(normalizeCapabilities(message.capabilities), existingProvider?.capabilities ?? []);
             await upsertProvider(tx, workspaceId, nodeId, {
                 name: providerName,
                 instanceId: existingProvider?.instanceId ?? `${providerName}:heartbeat`,
@@ -733,44 +829,73 @@ async function autoJoinGeneral(db, workspaceId, agentId) {
         }).onConflictDoNothing();
     }
 }
-async function upsertAgentNodeBinding(db, workspaceId, agent, nodeId, opts = {}) {
-    if (opts.deactivateExisting ?? true) {
-        await db
-            .update(agentNodeBindings)
-            .set({ status: 'inactive', updatedAt: new Date() })
-            .where(and(eq(agentNodeBindings.workspaceId, workspaceId), eq(agentNodeBindings.agentId, agent.id), eq(agentNodeBindings.status, 'active'), ne(agentNodeBindings.nodeId, nodeId)));
-    }
-    await db
-        .insert(agentNodeBindings)
-        .values({
-        id: `anb_${generateId()}`,
-        workspaceId,
-        agentId: agent.id,
-        nodeId,
-        status: 'active',
-        sessionRef: opts.sessionRef ?? null,
-        priority: opts.priority ?? 0,
-        updatedAt: new Date(),
-    })
-        .onConflictDoUpdate({
-        target: [agentNodeBindings.agentId, agentNodeBindings.nodeId],
-        set: {
+/**
+ * Statements that bind `agent` to `nodeId` and move its routable location onto
+ * that node. Built, not executed: a caller that owns the whole move hands them
+ * to {@link runAtomicWrites} so the binding row, the location move and the
+ * retirement of the bindings left behind commit as one unit — on D1 too, where
+ * there is no interactive transaction to roll a half-applied move back.
+ *
+ * Statement order is the last-resort story for a caller that still runs them
+ * one at a time inside its own transaction: every prefix has to leave the agent
+ * routable, so the new binding is inserted first (inert on its own — delivery
+ * joins bindings only where `agents.location_node_id` matches), then the agent
+ * moves onto it, then the bindings it left behind are retired (inert once the
+ * agent has moved off them). Deactivating first, or moving the agent before its
+ * binding exists, would strand the agent with no active binding at its
+ * location. Callers that mutate `agents` themselves must write through
+ * `providerName`/`originNodeId` here rather than updating the row up front,
+ * for the same reason.
+ */
+function agentNodeBindingWrites(db, workspaceId, agent, nodeId, opts = {}) {
+    const now = new Date();
+    const writes = [
+        db
+            .insert(agentNodeBindings)
+            .values({
+            id: `anb_${generateId()}`,
+            workspaceId,
+            agentId: agent.id,
+            nodeId,
             status: 'active',
             sessionRef: opts.sessionRef ?? null,
             priority: opts.priority ?? 0,
-            updatedAt: new Date(),
-        },
-    });
-    await db
-        .update(agents)
-        .set({
-        locationType: 'via_node',
-        locationNodeId: nodeId,
-        sessionRef: opts.sessionRef ?? undefined,
-        status: 'active',
-        lastSeen: new Date(),
-    })
-        .where(and(eq(agents.workspaceId, workspaceId), eq(agents.id, agent.id)));
+            updatedAt: now,
+        })
+            .onConflictDoUpdate({
+            target: [agentNodeBindings.agentId, agentNodeBindings.nodeId],
+            set: {
+                status: 'active',
+                sessionRef: opts.sessionRef ?? null,
+                priority: opts.priority ?? 0,
+                updatedAt: now,
+            },
+        }),
+        db
+            .update(agents)
+            .set({
+            locationType: 'via_node',
+            locationNodeId: nodeId,
+            sessionRef: opts.sessionRef ?? undefined,
+            providerName: opts.providerName ?? undefined,
+            originNodeId: opts.originNodeId ?? undefined,
+            status: 'active',
+            lastSeen: now,
+        })
+            .where(and(eq(agents.workspaceId, workspaceId), eq(agents.id, agent.id))),
+    ];
+    if (opts.deactivateExisting ?? true) {
+        writes.push(db
+            .update(agentNodeBindings)
+            .set({ status: 'inactive', updatedAt: now })
+            .where(and(eq(agentNodeBindings.workspaceId, workspaceId), eq(agentNodeBindings.agentId, agent.id), eq(agentNodeBindings.status, 'active'), ne(agentNodeBindings.nodeId, nodeId))));
+    }
+    return writes;
+}
+/** Run {@link agentNodeBindingWrites} one statement at a time. */
+async function upsertAgentNodeBinding(db, workspaceId, agent, nodeId, opts = {}) {
+    for (const write of agentNodeBindingWrites(db, workspaceId, agent, nodeId, opts))
+        await write;
 }
 async function activeBindingNodeIdsForAgent(db, workspaceId, agentId) {
     const rows = await db
@@ -834,16 +959,28 @@ async function rejectMigrationCanceledSpawnRegistration(db, workspaceId, registr
         throw codedError(`Spawn invocation "${canceled.id}" was canceled during migration`, 'spawn_invocation_canceled', 409);
     }
 }
-async function releaseNodeAgentSlots(db, workspaceId, nodeIds) {
+/**
+ * The statement (at most one) that gives back one agent slot on each of
+ * `nodeIds`. Built, not executed, so a caller can commit the decrement in the
+ * same atomic unit as the binding retirement that justifies it: a decrement
+ * that lands without the retirement lets the node overshoot `maxAgents`, and a
+ * retirement that lands without the decrement charges capacity to a binding
+ * nothing will ever release.
+ */
+function releaseNodeAgentSlotWrites(db, workspaceId, nodeIds) {
     const uniqueNodeIds = [...new Set(nodeIds)];
     if (uniqueNodeIds.length === 0)
-        return;
-    await db
-        .update(nodes)
-        .set({
-        activeAgents: sql `CASE WHEN ${nodes.activeAgents} > 0 THEN ${nodes.activeAgents} - 1 ELSE 0 END`,
-    })
-        .where(and(eq(nodes.workspaceId, workspaceId), inArray(nodes.id, uniqueNodeIds)));
+        return [];
+    return [db
+            .update(nodes)
+            .set({
+            activeAgents: sql `CASE WHEN ${nodes.activeAgents} > 0 THEN ${nodes.activeAgents} - 1 ELSE 0 END`,
+        })
+            .where(and(eq(nodes.workspaceId, workspaceId), inArray(nodes.id, uniqueNodeIds)))];
+}
+async function releaseNodeAgentSlots(db, workspaceId, nodeIds) {
+    for (const write of releaseNodeAgentSlotWrites(db, workspaceId, nodeIds))
+        await write;
 }
 export async function ensureDirectNodeForAgent(db, workspaceId, agent, opts = {}) {
     return runAtomic(db, (tx) => ensureDirectNodeForAgentInTx(tx, workspaceId, agent, opts));
@@ -1004,11 +1141,24 @@ function serializeBinding(row) {
         status: row.status,
         session_ref: row.sessionRef,
         priority: row.priority,
+        // Only the bind response selects this: it hands the caller the agent's
+        // authoritative delivery cursor, the same contract `agent.register` and
+        // `agent.recover` replies carry for cursor-aware providers.
+        ...(row.deliveryAckSeq !== undefined && row.deliveryAckSeq !== null
+            ? { delivery_ack_seq: row.deliveryAckSeq }
+            : {}),
         created_at: row.createdAt.toISOString(),
         updated_at: row.updatedAt?.toISOString() ?? null,
     };
 }
 export async function bindAgentToNode(db, workspaceId, nodeName, agentName, opts = {}) {
+    // `runAtomic` below already owns a transaction on an adapter that has one, so
+    // the move's statements must not re-enter `withTransaction` (the shared
+    // connection serializes transactions and would deadlock on itself) — they run
+    // in order inside it instead. Without one, the move has to be a D1 batch, and
+    // a handle offering neither is refused before a single statement lands rather
+    // than committing half a move it cannot undo.
+    const hasInteractiveTransaction = typeof db.withTransaction === 'function';
     return runAtomic(db, async (tx) => {
         const node = await getNodeByName(tx, workspaceId, nodeName);
         if (!node)
@@ -1019,6 +1169,43 @@ export async function bindAgentToNode(db, workspaceId, nodeName, agentName, opts
             .where(and(eq(agents.workspaceId, workspaceId), eq(agents.name, agentName)));
         if (!agent)
             throw codedError(`Agent "${agentName}" not found`, 'agent_not_found', 404);
+        // A bind moves the agent's routable location onto this node. Delivery
+        // routing joins bindings only where `agents.location_node_id` matches the
+        // bound node, so a binding row alone leaves an HTTP-registered agent
+        // stranded on its implicit `direct-*` pseudo-node and never woken — the
+        // exact shape of the broker's create-only register falling back to this
+        // endpoint. `unbindAgentFromNode` already assumes this move happened.
+        if (agent.status === 'active'
+            && agent.locationNodeId
+            && agent.locationNodeId !== node.id
+            && !isImplicitDirectLocation(agent)) {
+            const [locatedNode] = await tx
+                .select()
+                .from(nodes)
+                .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, agent.locationNodeId)));
+            // A dead or missing prior location is not a conflict — it is exactly what
+            // a bind is for. Only a live one still owns the identity.
+            if (locatedNode && isNodeLive(locatedNode)) {
+                throw codedError(`Agent "${agentName}" is already active on another live location`, 'agent_location_conflict', 409);
+            }
+        }
+        // Provider rows persist after a disconnect so the node keeps its capability
+        // manifest; they are history, not sockets. Adopt only among providers that
+        // can actually receive a push right now — keeping or choosing an offline
+        // row while a live sibling serves the node would point the agent at a
+        // provider connection that does not exist.
+        const liveProviderNames = (await tx
+            .select({
+            name: nodeProviders.name,
+            status: nodeProviders.status,
+            handlersLive: nodeProviders.handlersLive,
+            lastHeartbeatAt: nodeProviders.lastHeartbeatAt,
+        })
+            .from(nodeProviders)
+            .where(and(eq(nodeProviders.workspaceId, workspaceId), eq(nodeProviders.nodeId, node.id))))
+            .filter((provider) => isProviderLive(provider))
+            .map((row) => row.name);
+        const adoptedProviderName = adoptNodeProviderName(agent.providerName, liveProviderNames);
         const activeNodeIds = await activeBindingNodeIdsForAgent(tx, workspaceId, agent.id);
         const targetWasActive = activeNodeIds.includes(node.id);
         let reservedTargetSlot = false;
@@ -1027,13 +1214,33 @@ export async function bindAgentToNode(db, workspaceId, nodeName, agentName, opts
                 await reserveNodeAgentSlot(tx, workspaceId, node);
                 reservedTargetSlot = true;
             }
-            await upsertAgentNodeBinding(tx, workspaceId, agent, node.id, {
-                sessionRef: opts.session_ref ?? null,
-                priority: opts.priority ?? 0,
-            });
-            await releaseNodeAgentSlots(tx, workspaceId, activeNodeIds.filter((nodeId) => nodeId !== node.id));
+            // The binding row, the location move, the provider adoption, the
+            // retirement of the bindings left behind and the slots those bindings
+            // held are one mutation. Committing any subset is a corruption that no
+            // retry repairs: a binding without its reservation lets the node exceed
+            // `maxAgents`, and a retired binding whose slot was never given back
+            // charges the old node forever, because the retry that would fix either
+            // reads the half-applied state as already done.
+            const buildMoveWrites = (writeDb) => [
+                ...agentNodeBindingWrites(writeDb, workspaceId, agent, node.id, {
+                    sessionRef: opts.session_ref ?? null,
+                    priority: opts.priority ?? 0,
+                    providerName: adoptedProviderName,
+                    originNodeId: agent.originNodeId ?? node.id,
+                }),
+                ...releaseNodeAgentSlotWrites(writeDb, workspaceId, activeNodeIds.filter((nodeId) => nodeId !== node.id)),
+            ];
+            if (hasInteractiveTransaction) {
+                for (const write of buildMoveWrites(tx))
+                    await write;
+            }
+            else {
+                await runAtomicWrites(tx, buildMoveWrites, { requireAtomic: true });
+            }
         }
         catch (err) {
+            // Every statement of the move either landed or did not, so a throw means
+            // none of it did and the slot reserved for it belongs to nobody.
             if (reservedTargetSlot) {
                 await releaseNodeAgentSlots(tx, workspaceId, [node.id]);
             }
@@ -1051,6 +1258,7 @@ export async function bindAgentToNode(db, workspaceId, nodeName, agentName, opts
             status: agentNodeBindings.status,
             sessionRef: agentNodeBindings.sessionRef,
             priority: agentNodeBindings.priority,
+            deliveryAckSeq: agents.deliveryAckSeq,
             createdAt: agentNodeBindings.createdAt,
             updatedAt: agentNodeBindings.updatedAt,
         })
@@ -1058,7 +1266,25 @@ export async function bindAgentToNode(db, workspaceId, nodeName, agentName, opts
             .innerJoin(agents, eq(agentNodeBindings.agentId, agents.id))
             .innerJoin(nodes, eq(agentNodeBindings.nodeId, nodes.id))
             .where(and(eq(agentNodeBindings.workspaceId, workspaceId), eq(agentNodeBindings.agentId, agent.id), eq(agentNodeBindings.nodeId, node.id)));
-        return serializeBinding(binding);
+        return {
+            binding: serializeBinding(binding),
+            move: { nodeId: node.id, agentId: agent.id, providerName: adoptedProviderName },
+        };
+    });
+}
+/**
+ * The second half of a bind, run by the caller only after the cursor-bearing
+ * response is on the wire — `agent.register`/`agent.recover` order their
+ * cursor reply ahead of the ready mark and replay for the same reason.
+ * Cursor-aware providers gate every delivery on a per-identity ready mark,
+ * so a bound agent needs this transition or it points at a socket that will
+ * never push to it; immediate-mode providers treat the mark as a no-op.
+ */
+export async function completeBoundAgentDelivery(db, registry, workspaceId, move) {
+    registry.markProviderAgentsDeliveryReady?.(workspaceId, move.nodeId, move.providerName, undefined, [move.agentId]);
+    await deliverPendingToNode(db, registry, workspaceId, move.nodeId, {
+        providerName: move.providerName,
+        agentIds: [move.agentId],
     });
 }
 export async function unbindAgentFromNode(db, workspaceId, nodeName, agentName) {
@@ -1126,11 +1352,8 @@ export async function registerAgentViaNode(db, workspaceId, nodeId, providerName
             .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
         if (!node)
             throw codedError(`Node "${nodeId}" not found`, 'node_not_found', 404);
-        const [provider] = await tx
-            .select({ capabilities: nodeProviders.capabilities })
-            .from(nodeProviders)
-            .where(and(eq(nodeProviders.workspaceId, workspaceId), eq(nodeProviders.nodeId, nodeId), eq(nodeProviders.name, providerName)));
-        const cursorHandshake = (options.deliveryCursorSupported ?? true) && (provider?.capabilities?.some((capability) => capability.name === FLEET_DELIVERY_CURSOR_CAPABILITY) ?? false);
+        const cursorHandshake = (options.deliveryCursorSupported ?? true)
+            && await providerAdvertisesDeliveryCursor(tx, workspaceId, nodeId, providerName);
         // Preserve the established identity conflict even when this node is full.
         // A concurrent create after this read is still caught by the unique insert
         // below, whose reserved slot is then compensated in the catch path.
@@ -1230,11 +1453,8 @@ export async function recoverAgentViaNode(db, workspaceId, nodeId, providerName,
             .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
         if (!node)
             throw codedError(`Node "${nodeId}" not found`, 'node_not_found', 404);
-        const [provider] = await tx
-            .select({ capabilities: nodeProviders.capabilities })
-            .from(nodeProviders)
-            .where(and(eq(nodeProviders.workspaceId, workspaceId), eq(nodeProviders.nodeId, nodeId), eq(nodeProviders.name, providerName)));
-        const cursorHandshake = (options.deliveryCursorSupported ?? true) && (provider?.capabilities?.some((capability) => capability.name === FLEET_DELIVERY_CURSOR_CAPABILITY) ?? false);
+        const cursorHandshake = (options.deliveryCursorSupported ?? true)
+            && await providerAdvertisesDeliveryCursor(tx, workspaceId, nodeId, providerName);
         const [target] = await tx
             .select()
             .from(agents)
@@ -2009,14 +2229,40 @@ export async function handleNodeControlMessage(args) {
                     });
                     if (!replySent)
                         return;
-                    const newlyReadyAgentIds = result.reconciledAgentIds.filter((agentId) => (!isProviderAgentDeliveryReady(args.registry, args.workspaceId, args.nodeId, frameProviderName, agentId)));
                     args.registry.markProviderAgentsDeliveryReady?.(args.workspaceId, args.nodeId, frameProviderName, args.connectionId, result.reconciledAgentIds);
                     // Inventory represents sessions that survived a transport reconnect and
-                    // therefore retain their in-memory cursors. Restrict replay to exactly
-                    // those provider-owned identities; restarted sessions not in inventory
-                    // become ready individually through `agent.register`.
-                    const replayAgentIds = [...new Set([...newlyReadyAgentIds, ...result.newlyRoutedAgentIds])];
-                    await deliverPendingToNode(args.db, args.registry, args.workspaceId, args.nodeId, { providerName: frameProviderName, agentIds: replayAgentIds });
+                    // therefore retain their in-memory cursors. Restarted sessions not in
+                    // the inventory stay excluded either way — they become ready
+                    // individually through `agent.register`.
+                    //
+                    // A cursor-negotiated connection receives NO replay at `node.register`
+                    // (each identity is seeded by its own cursor-bearing reply), so this
+                    // certification is the whole node's only reconnect-replay trigger and
+                    // must cover every certified identity. Scoping it to a readiness/routing
+                    // TRANSITION instead stranded a reconnecting node's entire outage
+                    // backlog whenever the socket owner already reported those identities as
+                    // delivery-ready — an out-of-process owner whose ready-set is keyed per
+                    // node+provider rather than per connection. The diff came back empty,
+                    // the drain ran with an empty scope, and rows queued during the outage
+                    // sat unsent until their mailbox TTL.
+                    //
+                    // A legacy immediate-delivery connection already had the whole node
+                    // flushed to it at `node.register` and gates nothing afterwards, so only
+                    // identities this sync newly routed here still need a push; re-sending
+                    // the rest would duplicate that flush.
+                    //
+                    // Either way replay stays bounded, ordered oldest-first, gated per
+                    // identity on delivery readiness inside the drain, and deduped by the
+                    // cumulative delivery cursor, so an identity that is already drained and
+                    // acked re-sends nothing.
+                    // The mode is the CONNECTION's, recovered from the registry that
+                    // `node.register` configured it on — not re-derived from roster state
+                    // that a heartbeat can rewrite between registration and certification.
+                    const cursorGated = await connectionNegotiatedDeliveryCursor(args.db, args.registry, args.workspaceId, args.nodeId, frameProviderName, args.connectionId);
+                    await deliverPendingToNode(args.db, args.registry, args.workspaceId, args.nodeId, {
+                        providerName: frameProviderName,
+                        agentIds: cursorGated ? result.reconciledAgentIds : result.newlyRoutedAgentIds,
+                    });
                     return;
                 }
                 case 'action.accept': {