@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/ws/sidecar-handler.js

@@ -6,8 +6,8 @@
 import { getLogger } from "@intx/log";
 import { verifyEd25519 } from "@intx/crypto";
 import { chunkPack, createPackReceiver } from "@intx/pack-transport";
-import { hexDecode, hexEncode } from "@intx/types";
-import { isWorkflowDerivedAddress } from "@intx/workflow-deploy";
+import { base64Decode, deriveMessageId, deriveWorkflowRunId, hexDecode, hexEncode, isRunAddress, } from "@intx/types";
+import { deriveWorkflowRunRepoId } from "@intx/workflow-deploy";
 import { type } from "arktype";
 import { SidecarFrame, } from "@intx/types/sidecar";
 import { createSidecarEmitter, } from "./sidecar-events.js";
@@ -24,22 +24,48 @@ const logger = getLogger(["hub", "ws", "sidecar"]);
 function connOwnsAddress(conn, address) {
     return (conn.agentAddresses.has(address) || conn.workflowAddresses.has(address));
 }
+/**
+ * Bind pack writes to the repository implied by the authenticated address.
+ * An allocated credential is narrower still: it may only write its one
+ * deployment's workflow-run repository and never a standalone agent-state
+ * repository.
+ */
+function connCanPushRepo(conn, agentAddress, repoId) {
+    if (conn.identity.kind === "allocated" &&
+        agentAddress !== conn.identity.workflowRunAddress) {
+        return false;
+    }
+    if (repoId.kind === "agent-state") {
+        return conn.identity.kind === "shared" && repoId.id === agentAddress;
+    }
+    return (repoId.kind === "workflow-run" &&
+        repoId.id === deriveWorkflowRunRepoId(agentAddress));
+}
 /** The deduped set of every address this connection owns (session + workflow). */
 function ownedAddresses(conn) {
     return new Set([...conn.agentAddresses, ...conn.workflowAddresses]);
 }
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_CHALLENGE_TIMEOUT_MS = 30_000;
+// A probe fetches a workflow's dependency closure from a registry and
+// evaluates it on the sidecar, so it runs longer than a routine request; its
+// default timeout is correspondingly wider than DEFAULT_REQUEST_TIMEOUT_MS.
+export const DEFAULT_PROBE_TIMEOUT_MS = 60_000;
 const DEFAULT_DISCONNECT_QUEUE_MAX_SIZE = 100;
 const DEFAULT_DISCONNECT_QUEUE_TTL_MS = 5 * 60 * 1000;
 const DEFAULT_PING_TIMEOUT_MS = 60_000;
+const DEFAULT_MAIL_ACK_RETRY_INTERVAL_MS = 10_000;
+const DEFAULT_MAIL_ACK_MAX_RETRIES = 5;
 export function createSidecarRouter(config) {
-    const { requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, challengeTimeoutMs = DEFAULT_CHALLENGE_TIMEOUT_MS, hubPublicKey: hubPublicKeyHex, authenticateSidecar, disconnectQueueMaxSize = DEFAULT_DISCONNECT_QUEUE_MAX_SIZE, disconnectQueueTTLMs = DEFAULT_DISCONNECT_QUEUE_TTL_MS, pingTimeoutMs = DEFAULT_PING_TIMEOUT_MS, lookups = {}, } = config;
+    const { requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, challengeTimeoutMs = DEFAULT_CHALLENGE_TIMEOUT_MS, probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS, hubPublicKey: hubPublicKeyHex, authenticateSidecar, validateSidecarIdentity = async () => true, disconnectQueueMaxSize = DEFAULT_DISCONNECT_QUEUE_MAX_SIZE, disconnectQueueTTLMs = DEFAULT_DISCONNECT_QUEUE_TTL_MS, pingTimeoutMs = DEFAULT_PING_TIMEOUT_MS, mailAckRetryIntervalMs = DEFAULT_MAIL_ACK_RETRY_INTERVAL_MS, mailAckMaxRetries = DEFAULT_MAIL_ACK_MAX_RETRIES, lookups = {}, } = config;
     // Receiver-dispatch surface. Wire-layer callsites emit events here;
     // host code subscribes via `router.events`.
     const events = createSidecarEmitter();
     // ws handle → registered connection
     const connections = new Map();
+    const allocatedConnections = new Map();
+    const allocationFences = new Map();
+    const allocationWaiters = new Map();
     // agentAddress → ws handle (routing table)
     const addressIndex = new Map();
     // requestId → pending promise
@@ -47,6 +73,14 @@ export function createSidecarRouter(config) {
     const pendingDeploys = new Map();
     const pendingChallenges = new Map();
     const disconnectedAgents = new Map();
+    const pendingMail = new Map();
+    // agentAddress → retention TTL timer for un-acked pending mail held across a
+    // disconnect. On close the per-entry retry timers are cleared (the socket is
+    // gone) but the entries are RETAINED so a verified reconnect can redeliver
+    // them; this timer bounds that retention so a sidecar that never reconnects
+    // does not leak entries. Cleared when the address reconnects (redelivery) or
+    // its last pending entry is acked.
+    const pendingMailRetention = new Map();
     // agentAddress → set of subscriber callbacks for agent events
     const agentSubscribers = new Map();
     // agentAddress → cached connector-thread state, populated by
@@ -69,6 +103,7 @@ export function createSidecarRouter(config) {
     const pendingPacks = new Map();
     let packCounter = 0;
     const pendingUndeploys = new Map();
+    const pendingProbes = new Map();
     // Receives agent-state packs pushed from sidecars. The wire frames
     // (`repo.pack.push` / `repo.pack.done`) are shared with the
     // workflow-run flow; dispatch on `repoId.kind` picks which receiver
@@ -125,6 +160,183 @@ export function createSidecarRouter(config) {
             logger.info `Flushed ${String(entry.queue.length)} queued message(s) to ${agentAddress}`;
         }
     }
+    // Track a connected-window `mail.inbound` for redelivery until the sidecar
+    // acks its durable inbox write. Replaces any prior entry for the same
+    // (agentAddress, messageId) -- clearing its timer first so no timer leaks --
+    // which keeps a re-sent delivery from arming a second concurrent retry loop.
+    function trackPendingMail(agentAddress, messageId, frame, runGrants, allocatedTarget) {
+        let byId = pendingMail.get(agentAddress);
+        if (byId === undefined) {
+            byId = new Map();
+            pendingMail.set(agentAddress, byId);
+        }
+        const existing = byId.get(messageId);
+        if (existing !== undefined)
+            clearTimeout(existing.timer);
+        byId.set(messageId, {
+            agentAddress,
+            messageId,
+            frame,
+            attempts: 0,
+            timer: setTimeout(() => retryPendingMail(agentAddress, messageId), mailAckRetryIntervalMs),
+            ...(runGrants !== undefined ? { runGrants } : {}),
+            ...(allocatedTarget !== undefined ? { allocatedTarget } : {}),
+        });
+    }
+    // Replay a mail-triggered run's grants ahead of a redelivery of its trigger
+    // mail. Same-connection FIFO lands the `run.grants` frame before the mail, so
+    // the redelivered run resolves its onRunStart barrier instead of failing
+    // closed on missing grants.
+    function replayRunGrantsAhead(conn, entry) {
+        if (entry.runGrants === undefined)
+            return;
+        conn.send({
+            type: "run.grants",
+            agentAddress: entry.agentAddress,
+            runId: entry.runGrants.runId,
+            stepGrants: entry.runGrants.stepGrants,
+        });
+    }
+    function deletePendingMail(byId, agentAddress, messageId) {
+        byId.delete(messageId);
+        if (byId.size === 0) {
+            pendingMail.delete(agentAddress);
+            // The retention TTL guards a non-empty pending set; drop it once the set
+            // is empty so it never outlives the entries it was bounding.
+            const retention = pendingMailRetention.get(agentAddress);
+            if (retention !== undefined) {
+                clearTimeout(retention);
+                pendingMailRetention.delete(agentAddress);
+            }
+        }
+    }
+    function retryPendingMail(agentAddress, messageId) {
+        const byId = pendingMail.get(agentAddress);
+        if (byId === undefined)
+            return;
+        const entry = byId.get(messageId);
+        if (entry === undefined)
+            return;
+        if (entry.attempts >= mailAckMaxRetries) {
+            // The sidecar never acked within the retry budget. The ack is withheld
+            // precisely because the sidecar's durable inbox write failed, so the
+            // mail was NOT delivered: surface it as undelivered so the host can relay
+            // it onto an external transport, then drop the pending entry so its timer
+            // does not leak.
+            if (entry.frame.type === "mail.inbound") {
+                events.emit("mail.outbound.undelivered", {
+                    rawMessage: entry.frame.rawMessage,
+                    recipients: [agentAddress],
+                });
+            }
+            deletePendingMail(byId, agentAddress, messageId);
+            logger.warn `Gave up redelivering mail ${messageId} to ${agentAddress} after ${String(entry.attempts)} un-acked attempt(s)`;
+            return;
+        }
+        // Redeliver over the address's CURRENT owner: a verified reconnect may have
+        // moved the address to a new connection since the original delivery.
+        const ws = addressIndex.get(agentAddress);
+        const conn = ws !== undefined ? connections.get(ws) : undefined;
+        const allocated = entry.allocatedTarget === undefined
+            ? undefined
+            : allocatedConnections.get(entry.allocatedTarget.allocationId);
+        const targetStillOwnsAddress = entry.allocatedTarget === undefined ||
+            (allocated !== undefined &&
+                allocated.identity.generation === entry.allocatedTarget.generation &&
+                allocated.ws === ws);
+        if (conn === undefined || !targetStillOwnsAddress) {
+            // No live connection to recover into. Connected-window redelivery only
+            // applies while the address is routable; a disconnected address is not
+            // retried here.
+            deletePendingMail(byId, agentAddress, messageId);
+            logger.warn `Dropping un-acked mail ${messageId} for ${agentAddress}: no live connection to redeliver over`;
+            return;
+        }
+        entry.attempts += 1;
+        replayRunGrantsAhead(conn, entry);
+        conn.send(entry.frame);
+        entry.timer = setTimeout(() => retryPendingMail(agentAddress, messageId), mailAckRetryIntervalMs);
+    }
+    function resolvePendingMail(agentAddress, messageId) {
+        const byId = pendingMail.get(agentAddress);
+        if (byId === undefined)
+            return;
+        const entry = byId.get(messageId);
+        if (entry === undefined)
+            return;
+        clearTimeout(entry.timer);
+        deletePendingMail(byId, agentAddress, messageId);
+    }
+    // Hold an address's un-acked pending mail across a disconnect. The per-entry
+    // retry timers are cleared -- retrying over the dead socket is pointless --
+    // but the entries are KEPT so a verified reconnect can redeliver them. A
+    // retention TTL (the disconnect-queue horizon) bounds the hold so a sidecar
+    // that never reconnects does not leak; on expiry the still-un-acked entries
+    // are surfaced as `mail.outbound.undelivered` so the host can relay them,
+    // since a withheld ack means the sidecar's durable write never landed.
+    function retainPendingMailForAddress(agentAddress) {
+        const byId = pendingMail.get(agentAddress);
+        if (byId === undefined)
+            return;
+        for (const entry of byId.values())
+            clearTimeout(entry.timer);
+        const existing = pendingMailRetention.get(agentAddress);
+        if (existing !== undefined)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            pendingMailRetention.delete(agentAddress);
+            const expired = pendingMail.get(agentAddress);
+            pendingMail.delete(agentAddress);
+            if (expired !== undefined && expired.size > 0) {
+                for (const entry of expired.values()) {
+                    if (entry.frame.type !== "mail.inbound")
+                        continue;
+                    events.emit("mail.outbound.undelivered", {
+                        rawMessage: entry.frame.rawMessage,
+                        recipients: [agentAddress],
+                    });
+                }
+                logger.warn `Dropping ${String(expired.size)} un-acked message(s) for ${agentAddress}: pending-mail retention TTL expired`;
+            }
+        }, disconnectQueueTTLMs);
+        pendingMailRetention.set(agentAddress, timer);
+    }
+    // Redeliver an address's retained un-acked pending mail on a verified
+    // reconnect. Replays identical bytes (same messageId) over the new
+    // connection, so the sidecar's inbox dedups a message it already wrote
+    // (effectively-once) and processes one it had dropped (no loss). Re-arms the
+    // connected-window retry over the new connection with a fresh per-generation
+    // budget, so a redelivery that is itself dropped before its ack is retried.
+    function redeliverPendingMail(agentAddress, conn) {
+        const retention = pendingMailRetention.get(agentAddress);
+        if (retention !== undefined) {
+            clearTimeout(retention);
+            pendingMailRetention.delete(agentAddress);
+        }
+        const byId = pendingMail.get(agentAddress);
+        if (byId === undefined)
+            return;
+        for (const entry of [...byId.values()]) {
+            if (entry.allocatedTarget !== undefined &&
+                (conn.identity.kind !== "allocated" ||
+                    conn.identity.allocationId !== entry.allocatedTarget.allocationId ||
+                    conn.identity.generation !== entry.allocatedTarget.generation)) {
+                // The Hub-owned dispatch row survives generation replacement and will
+                // be requeued by the allocation-ready callback. Do not leak or replay
+                // this generation-local retry entry onto a different worker.
+                clearTimeout(entry.timer);
+                deletePendingMail(byId, agentAddress, entry.messageId);
+                continue;
+            }
+            replayRunGrantsAhead(conn, entry);
+            conn.send(entry.frame);
+            entry.attempts = 0;
+            entry.timer = setTimeout(() => retryPendingMail(agentAddress, entry.messageId), mailAckRetryIntervalMs);
+        }
+        if (byId.size > 0) {
+            logger.info `Redelivered ${String(byId.size)} un-acked message(s) to ${agentAddress} on reconnect`;
+        }
+    }
     function resetLivenessTimer(ws) {
         const existing = livenessTimers.get(ws);
         if (existing !== undefined)
@@ -213,6 +425,8 @@ export function createSidecarRouter(config) {
             case "agent.undeploy.ack":
             case "repo.pack.ack":
             case "repo.pack.reject":
+            case "workflow.probe.result":
+            case "workflow.probe.error":
                 return true;
             case "register":
             case "reconnect":
@@ -220,6 +434,8 @@ export function createSidecarRouter(config) {
             case "mail.outbound":
             case "agent.event":
             case "connector.state.changed":
+            case "mail.inbound.ack":
+            case "signal.correlation.register":
             case "repo.pack.push":
             case "repo.pack.done":
                 return false;
@@ -246,21 +462,20 @@ export function createSidecarRouter(config) {
             case "challenge.response":
                 return handleChallengeResponse(ws, frame.responses);
             case "agent.deploy.ack":
-                return handleDeployAck(frame.agentAddress, frame.publicKey);
+                return handleDeployAck(ws, frame);
             case "agent.error":
-                rejectDeployPending(frame.agentAddress, frame.error);
-                rejectUndeployPending(frame.agentAddress, frame.error);
+                rejectDeployPendingFromFrame(ws, frame.agentAddress, frame.error);
+                rejectUndeployPending(ws, frame.agentAddress, frame.error);
                 return;
             case "agent.undeploy.ack":
-                resolveUndeployPending(frame.agentAddress);
+                resolveUndeployPending(ws, frame.agentAddress);
                 return;
             case "ping":
                 handlePing(ws);
                 return;
             case "mail.outbound":
                 if (frame.delivered !== true) {
-                    handleMailOutbound(frame.rawMessage, frame.recipients);
-                    return;
+                    return handleMailOutbound(frame.rawMessage, frame.recipients);
                 }
                 if (lookups.persistMail && frame.senderAddress) {
                     return handleMailPersist(lookups.persistMail, frame.rawMessage, frame.senderAddress, frame.recipients);
@@ -294,6 +509,38 @@ export function createSidecarRouter(config) {
                     connectorState: frame.connectorState,
                 });
                 return;
+            case "mail.inbound.ack": {
+                // Terminal receipt for a connected-window `mail.inbound`: the sidecar
+                // has durably written the message to its inbox. Gate on ownership --
+                // like connector.state.changed and signal.correlation.register -- so a
+                // sidecar cannot clear another sidecar's pending mail. The messageId is
+                // a hub-minted id only the owning sidecar ever received on the frame,
+                // so the ownership check is defense-in-depth, not the sole guard.
+                const conn = connections.get(ws);
+                if (conn === undefined)
+                    return;
+                if (!connOwnsAddress(conn, frame.agentAddress)) {
+                    logger.warn `Dropping mail.inbound.ack for ${frame.agentAddress}: not registered to this sidecar`;
+                    return;
+                }
+                resolvePendingMail(frame.agentAddress, frame.messageId);
+                events.emit("mail.inbound.acknowledged", {
+                    agentAddress: frame.agentAddress,
+                    messageId: frame.messageId,
+                    ...(conn.identity.kind === "allocated"
+                        ? {
+                            allocated: {
+                                allocationId: conn.identity.allocationId,
+                                anchorRunId: conn.identity.anchorRunId,
+                                generation: conn.identity.generation,
+                            },
+                        }
+                        : {}),
+                });
+                return;
+            }
+            case "signal.correlation.register":
+                return handleSignalCorrelationRegister(ws, frame);
             case "session.ack":
                 resolvePending(frame.requestId);
                 return;
@@ -301,16 +548,27 @@ export function createSidecarRouter(config) {
                 rejectPending(frame.requestId, frame.error);
                 return;
             case "repo.pack.ack":
-                resolvePackPending(frame.transferId);
+                resolvePackPending(ws, frame);
                 return;
             case "repo.pack.reject":
-                rejectPackPending(frame.transferId, frame.reason);
+                rejectPackPending(ws, frame);
                 return;
             case "repo.pack.push":
                 handlePackPush(ws, frame);
                 return;
             case "repo.pack.done":
                 return handlePackDone(ws, frame);
+            case "workflow.probe.result":
+                resolveProbe(frame.requestId, {
+                    projection: frame.projection,
+                    grants: frame.grants,
+                    grantWalkSnapshot: frame.grantWalkSnapshot,
+                    wireHash: frame.wireHash,
+                });
+                return;
+            case "workflow.probe.error":
+                rejectProbe(frame.requestId, frame.error);
+                return;
             default:
                 return assertNever(frame);
         }
@@ -343,9 +601,107 @@ export function createSidecarRouter(config) {
         if (identity.sidecarId !== frame.sidecarId) {
             logger.warn `Sidecar ${frame.type} claimed id ${frame.sidecarId} but token verifies as ${identity.sidecarId}; keying off the verified id`;
         }
+        if (!(await validateSidecarIdentity(identity, "registration"))) {
+            logger.warn `Rejected ${frame.type} from sidecar ${identity.sidecarId}: credential identity is no longer current`;
+            ws.close();
+            return;
+        }
         await run(identity);
     }
+    async function notifyAllocationWaiters(allocationId) {
+        const waiters = allocationWaiters.get(allocationId);
+        const current = allocatedConnections.get(allocationId);
+        if (waiters === undefined || current === undefined)
+            return;
+        if (!(await validateSidecarIdentity(current.identity, "readiness")))
+            return;
+        for (const waiter of [...waiters]) {
+            if (waiter.generation !== current.identity.generation)
+                continue;
+            clearTimeout(waiter.timer);
+            waiters.delete(waiter);
+            waiter.resolve();
+        }
+        if (waiters.size === 0)
+            allocationWaiters.delete(allocationId);
+    }
+    async function handleAllocatedRegister(ws, identity, agentAddresses) {
+        if (allocationFences.get(identity.allocationId) !== identity.generation) {
+            logger.warn `Rejected allocated sidecar ${identity.sidecarId}: allocation ${identity.allocationId} generation ${String(identity.generation)} is not fenced as current`;
+            ws.close();
+            return;
+        }
+        if (agentAddresses.length > 0 &&
+            !(await validateSidecarIdentity(identity, "routing"))) {
+            logger.warn `Rejected allocated sidecar ${identity.sidecarId}: allocation ${identity.allocationId} is not ready to reclaim routes`;
+            ws.close();
+            return;
+        }
+        const existingOnSocket = connections.get(ws);
+        const newlyRoutedAddresses = new Set();
+        for (const address of agentAddresses) {
+            const alreadyOwned = existingOnSocket?.identity.kind === "allocated" &&
+                existingOnSocket.identity.allocationId === identity.allocationId &&
+                addressIndex.get(address) === ws &&
+                connOwnsAddress(existingOnSocket, address);
+            if (!alreadyOwned && address !== identity.workflowRunAddress) {
+                logger.warn `Rejected allocated sidecar ${identity.sidecarId}: allocation ${identity.allocationId} claimed unrelated address ${address}`;
+                ws.close();
+                return;
+            }
+            if (!alreadyOwned)
+                newlyRoutedAddresses.add(address);
+        }
+        if (allocationFences.get(identity.allocationId) !== identity.generation) {
+            ws.close();
+            return;
+        }
+        const current = allocatedConnections.get(identity.allocationId);
+        if (current !== undefined && current.ws !== ws) {
+            // A current-generation takeover is a reconnect, not a capacity loss.
+            // Remove the old socket from the allocation index before closing it so
+            // handleClose does not emit a false allocated-disconnect event.
+            allocatedConnections.delete(identity.allocationId);
+            handleClose(current.ws);
+            current.ws.close();
+        }
+        const conn = existingOnSocket ?? {
+            sidecarId: identity.sidecarId,
+            identity,
+            agentAddresses: new Set(),
+            workflowAddresses: new Set(),
+            send(frame) {
+                ws.send(JSON.stringify(frame));
+            },
+        };
+        if (conn.identity.kind !== "allocated" ||
+            conn.identity.allocationId !== identity.allocationId ||
+            conn.identity.generation !== identity.generation) {
+            logger.warn `Rejected allocated sidecar ${identity.sidecarId}: socket identity changed during registration`;
+            ws.close();
+            return;
+        }
+        connections.set(ws, conn);
+        for (const address of agentAddresses) {
+            conn.workflowAddresses.add(address);
+            addressIndex.set(address, ws);
+        }
+        allocatedConnections.set(identity.allocationId, { ws, identity });
+        for (const address of newlyRoutedAddresses) {
+            redeliverPendingMail(address, conn);
+        }
+        logger.info `Allocated sidecar ${identity.sidecarId} registered for allocation ${identity.allocationId} generation ${String(identity.generation)}`;
+        await notifyAllocationWaiters(identity.allocationId);
+        events.emit("sidecar.allocated.connected", {
+            allocationId: identity.allocationId,
+            generation: identity.generation,
+        });
+    }
     async function handleRegister(ws, identity, agentAddresses) {
+        if (identity.kind === "allocated") {
+            await handleAllocatedRegister(ws, identity, agentAddresses);
+            return;
+        }
         const sidecarId = identity.sidecarId;
         // Key-existence gate. A register frame is token-authenticated but carries
         // no per-address ownership proof, so it may route an address ONLY if that
@@ -434,6 +790,7 @@ export function createSidecarRouter(config) {
         const workflowSet = inheritedWorkflow;
         const conn = {
             sidecarId,
+            identity,
             agentAddresses: addrSet,
             workflowAddresses: workflowSet,
             send(frame) {
@@ -466,6 +823,10 @@ export function createSidecarRouter(config) {
         logger.info `Sidecar ${sidecarId} registered; routed ${String(addrSet.size)} of ${String(agentAddresses.length)} address(es) (keyless first-deploy only)`;
     }
     async function handleReconnect(ws, identity, agentAddresses, deployRefs = {}) {
+        if (identity.kind === "allocated") {
+            await handleAllocatedRegister(ws, identity, agentAddresses);
+            return;
+        }
         const sidecarId = identity.sidecarId;
         const lookupKey = lookups.lookupPublicKey;
         if (lookupKey === undefined) {
@@ -534,7 +895,7 @@ export function createSidecarRouter(config) {
                 conn.send({
                     type: "challenge.failed",
                     address,
-                    reason: "Unknown agent address",
+                    reason: "Unknown run address",
                 });
                 continue;
             }
@@ -657,14 +1018,17 @@ export function createSidecarRouter(config) {
                     prevConn.agentAddresses.delete(addr);
                 }
             }
-            // Track the address on the set that matches its lifecycle so
-            // handleClose reclaims it correctly: a workflow-derived deployment
-            // address goes on the workflow set (no disconnect queue -- its
-            // in-flight state is reconstructed sidecar-locally on the next
-            // reconnect), a launched agent on the session set (queued for
-            // reconnect). The routing pointer is the same either way; only now
-            // it is written behind a passed challenge.
-            if (isWorkflowDerivedAddress(addr)) {
+            // A run address goes on the workflow set (no disconnect queue -- its
+            // in-flight state is reconstructed sidecar-locally on the next reconnect),
+            // so handleClose reclaims it correctly. The routing pointer is the same
+            // either way; only now it is written behind a passed challenge.
+            //
+            // The `else` (session set, queued for reconnect) is the retired
+            // launched-agent path: launched agents no longer exist (the folded-launch
+            // route was removed), so no current producer reaches it. It is left in
+            // place for the reconnect-subsystem teardown to remove as its own
+            // reviewable change, not folded into this collapse.
+            if (isRunAddress(addr)) {
                 conn.workflowAddresses.add(addr);
             }
             else {
@@ -675,14 +1039,17 @@ export function createSidecarRouter(config) {
         const ready = [];
         const failed = [];
         for (const addr of verified) {
-            // The `agent.reconnected` reaction is session lifecycle -- instance
-            // status flip, event-collector restore -- owned by the agent_instance
-            // concept. A workflow-derived deployment address has no agent_instance
-            // row, so the reaction's `requireInstance` would throw and roll the
-            // just-verified address back out of routing. It needs routing + queue
-            // flush only, which the passed challenge has now made safe; skip the
-            // session reaction for it.
-            if (isWorkflowDerivedAddress(addr)) {
+            // A workflow run needs routing + queue flush only, which the passed
+            // challenge has now made safe: its in-flight state is reconstructed
+            // sidecar-locally, so it does not enrol in the `agent.reconnected` session
+            // reaction (event-collector restore). Skip the reaction for it.
+            //
+            // The reaction below was the retired launched-agent path (restore a
+            // launched agent's collector). Launched agents no longer exist, so no
+            // current producer reaches it; the `agent.reconnected` listener is gone,
+            // so `listenerCount` is 0 and the emit is inert. Left for the
+            // reconnect-subsystem teardown to remove.
+            if (isRunAddress(addr)) {
                 ready.push(addr);
                 continue;
             }
@@ -715,9 +1082,14 @@ export function createSidecarRouter(config) {
             conn.agentAddresses.delete(addr);
             addressIndex.delete(addr);
         }
-        // Flush queued messages only for ready addresses.
+        // Flush queued messages and redeliver retained un-acked mail, only for
+        // ready addresses. The disconnect queue carries mail that arrived WHILE
+        // disconnected; pending-mail redelivery carries mail that was delivered
+        // over the prior live connection but never acked (the connected-window
+        // drop). Both replay over the verified new connection.
         for (const addr of ready) {
             flushDisconnectedQueue(addr, conn);
+            redeliverPendingMail(addr, conn);
         }
         // Re-deploy agents whose deploy ref is stale or absent. Fire-and-forget
         // so reconnect completion is not blocked on pack transfer. The
@@ -728,15 +1100,17 @@ export function createSidecarRouter(config) {
             for (const addr of ready) {
                 // Workflow deployments are pinned-forever: a deployment keeps its
                 // deploy-time definition until an explicit undeploy/redeploy, so the
-                // deploy-ref freshness catch-up is deliberately NOT run for a
-                // workflow-derived address. A definition edited on the hub while the
-                // sidecar was disconnected does not reconcile on reconnect; it affects
-                // only newly created deployments. The deployment's in-flight run state
-                // is reconstructed sidecar-locally at restore, not re-fetched here. Do
-                // NOT add a reconcile path for these addresses -- see the "Workflow
+                // deploy-ref freshness catch-up is deliberately NOT run for a run
+                // address. A definition edited on the hub while the sidecar was
+                // disconnected does not reconcile on reconnect; it affects only newly
+                // created deployments. The deployment's in-flight run state is
+                // reconstructed sidecar-locally at restore, not re-fetched here. Do NOT
+                // add a reconcile path for these addresses -- see the "Workflow
                 // Definition Versioning: Pinned-Forever" note under "Reconnect
-                // Sequencing" in docs/IMPLEMENTATION.md.
-                if (isWorkflowDerivedAddress(addr))
+                // Sequencing" in docs/IMPLEMENTATION.md. (Every routable address is a
+                // run address now; the fall-through was the retired launched-agent
+                // catch-up path.)
+                if (isRunAddress(addr))
                     continue;
                 void (async () => {
                     try {
@@ -779,30 +1153,44 @@ export function createSidecarRouter(config) {
         }
         logger.info `Sidecar ${challenge.sidecarId} reconnected with ${String(ready.length)} verified agent(s)${failed.length > 0 ? `, ${String(failed.length)} rejected` : ""}`;
     }
-    function handleMailOutbound(rawMessage, recipients) {
+    async function handleMailOutbound(rawMessage, recipients) {
+        // A mail addressed to more than one workflow deployment would birth a
+        // run per recipient from a single inbound mail. The stable runId
+        // removed the Message-ID collision that originally forced this guard --
+        // each recipient now derives its own per-deployment runId (its mail
+        // address), so it is no longer a runId-collision guard. It stays a
+        // deliberate one-workflow-recipient-per-mail restriction because the
+        // fan-out is not verified end-to-end: per-recipient grants
+        // materialization, consumed-tracking, and reply-addressing all assume a
+        // single workflow recipient today. Lifting it means proving those three
+        // hold per recipient, not just relaxing this check -- so fail loudly
+        // rather than materialize a partial set. The guard only applies when a
+        // materializer is wired -- absent one, no run is born from the mail, so
+        // there is nothing to restrict.
+        if (lookups.materializeMailTriggeredRunGrants !== undefined) {
+            // A workflow recipient is one this hub owns: its address parses as a run
+            // address. An external/federated address does not, and is not ours to
+            // materialize a run for.
+            const workflowRecipients = recipients.filter(isRunAddress);
+            if (workflowRecipients.length > 1) {
+                throw new Error(`mail addressed to multiple workflow-derived recipients (${workflowRecipients.join(", ")}); materializing a run for more than one workflow deployment from a single mail is unsupported`);
+            }
+        }
         // Route to locally connected sidecars first, then try disconnect queues.
         const unrouted = [];
         for (const recipient of recipients) {
-            const targetWs = addressIndex.get(recipient);
-            if (targetWs !== undefined) {
-                const conn = connections.get(targetWs);
-                if (conn !== undefined) {
-                    conn.send({
-                        type: "mail.inbound",
-                        agentAddress: recipient,
-                        rawMessage,
-                    });
-                    continue;
-                }
+            // Each recipient is isolated: a materialization failure or a
+            // fail-closed rejection for one must not drop the mail for its
+            // co-recipients. The catch fails THIS recipient closed (its run never
+            // starts under-authorized) and continues to the rest.
+            try {
+                const outcome = await deliverMailToRecipient(recipient, rawMessage);
+                if (outcome === "unrouted")
+                    unrouted.push(recipient);
+            }
+            catch (err) {
+                logger.error `Failed to deliver mail to ${recipient}: ${err instanceof Error ? err.message : String(err)}`;
             }
-            const frame = {
-                type: "mail.inbound",
-                agentAddress: recipient,
-                rawMessage,
-            };
-            if (enqueueForDisconnected(recipient, frame))
-                continue;
-            unrouted.push(recipient);
         }
         // Anything not routed locally is emitted as a notification. The
         // host decides whether to relay onto an external transport, log,
@@ -814,6 +1202,69 @@ export function createSidecarRouter(config) {
             });
         }
     }
+    // Deliver an inbound mail to one recipient, materializing a
+    // mail-triggered run's grants first when the recipient is a workflow
+    // deployment. Returns:
+    //   - `routed`: the mail reached a live connection or disconnect queue.
+    //   - `unrouted`: the mail was locally undeliverable and should be
+    //     relayed externally by the host.
+    //   - `failed-closed`: the run's grants could not be materialized safely,
+    //     so the mail is deliberately DROPPED for this recipient (not relayed)
+    //     to keep its run from starting under-authorized.
+    //
+    // A workflow deployment is the only recipient whose inbound mail can first
+    // fire its stable run. Its grants are reserved, and the `run.grants` frame is
+    // sent BEFORE the mail. Same-address FIFO guarantees it lands ahead of the
+    // mail that dispatches the run, so the run's `onRunStart` barrier resolves its
+    // grants rather than failing closed. Reservation happens before routing so
+    // concurrent first deliveries cannot send different snapshots; a routing
+    // failure leaves a grants-only, still-unfired run.
+    async function deliverMailToRecipient(recipient, rawMessage) {
+        if (lookups.materializeMailTriggeredRunGrants !== undefined &&
+            isRunAddress(recipient)) {
+            const runId = deriveWorkflowRunId(recipient);
+            const result = await lookups.materializeMailTriggeredRunGrants({
+                agentAddress: recipient,
+                runId,
+            });
+            if (result.outcome === "rejected") {
+                // The run's grants could not be materialized with sufficient
+                // authority or it is already terminal. Fail the mail closed for this
+                // recipient: routing or external relay would bypass that decision.
+                logger.error `Refusing mail-triggered run ${runId} for ${recipient}: grant materialization rejected (${result.code}): ${result.message}`;
+                return "failed-closed";
+            }
+            if (result.outcome === "materialized") {
+                // Send the run's grants ahead of the mail. A `false` here means the
+                // deployment is unroutable. Do not route the mail that would dispatch
+                // it; the grants-only reservation remains the canonical snapshot for a
+                // later first-delivery attempt.
+                if (!sendRunGrants(recipient, runId, result.stepGrants)) {
+                    logger.error `Deployment ${recipient} is not routable for run ${runId}; retaining the unfired run's grant reservation for retry`;
+                    return "unrouted";
+                }
+                // Route through the messageId handshake `routeMail` -- NOT a
+                // fire-and-forget send. This branch COMMITS a run, so a mail dropped in
+                // the connected window (a socket that half-dies before the sidecar's
+                // durable-write ack) would otherwise leave the run row "running"
+                // forever with no body and no error. `routeMail` tracks the delivery
+                // and redelivers identical bytes on reconnect, bringing the mail-relay
+                // run-trigger to parity with the HTTP-trigger path. The messageId is the
+                // mail's own id (derived over the same bytes the sidecar derives), so a
+                // redelivery replays identically and the downstream RunStarted /
+                // stable-runId dedup makes it effectively-once.
+                const messageId = await deriveMessageId(base64Decode(rawMessage));
+                const outcome = routeMail(recipient, rawMessage, messageId, { runId, stepGrants: result.stepGrants })
+                    ? "routed"
+                    : "unrouted";
+                return outcome;
+            }
+            // `skip`: the address named no deployed workflow deployment. Forward
+            // the mail without grants -- the run, if any, is not ours to
+            // authorize. No run is committed here, so no ack handshake is needed.
+        }
+        return routeMail(recipient, rawMessage) ? "routed" : "unrouted";
+    }
     async function handleMailPersist(persist, rawMessage, senderAddress, recipients) {
         let results;
         let raw;
@@ -835,15 +1286,60 @@ export function createSidecarRouter(config) {
                 raw,
                 createdAt: result.createdAt,
                 direction: result.direction,
-                instanceId: result.instanceId,
+                runId: result.runId,
                 address: result.address,
             });
         }
     }
+    async function handleSignalCorrelationRegister(ws, frame) {
+        // Gate the co-write on the sending sidecar actually owning the named
+        // deployment address, mirroring the connector.state.changed and pack
+        // handlers. A workflow deployment routes on the keyless workflow set, so
+        // ownership is the union check, not addressIndex identity alone. Without
+        // it a misbehaving sidecar that knows another deployment's address could
+        // register a spurious correlation against it.
+        const conn = connections.get(ws);
+        if (conn === undefined)
+            return;
+        if (!connOwnsAddress(conn, frame.agentAddress)) {
+            logger.warn `Dropping signal.correlation.register for ${frame.agentAddress}: not registered to this sidecar`;
+            return;
+        }
+        const register = lookups.registerSignalCorrelation;
+        if (register === undefined) {
+            logger.warn `Dropping signal.correlation.register for ${frame.agentAddress}: no registerSignalCorrelation lookup configured`;
+            return;
+        }
+        try {
+            await register({
+                correlationId: frame.correlationId,
+                runId: frame.runId,
+                anchorRunId: frame.anchorRunId,
+                agentAddress: frame.agentAddress,
+                kind: frame.kind,
+                approvalSnapshot: frame.snapshot,
+            });
+            // The co-write resolves only when a row exists -- freshly inserted or
+            // already present (both stores are idempotent on the correlationId). Ack
+            // so the sidecar's link stops retrying a register whose frame may have
+            // been lost on an open socket. A thrown co-write (undeployed deployment,
+            // id mismatch) means no row, so no ack: the sidecar keeps retrying and
+            // the reconnect re-emit remains the ultimate backstop.
+            conn.send({
+                type: "signal.correlation.register.ack",
+                agentAddress: frame.agentAddress,
+                correlationId: frame.correlationId,
+            });
+        }
+        catch (err) {
+            logger.error `Failed to register signal correlation ${frame.correlationId} for ${frame.agentAddress}: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
     function handleClose(ws) {
         const conn = connections.get(ws);
         if (conn === undefined)
             return;
+        let allocated;
         for (const addr of conn.agentAddresses) {
             // Only remove routing and pending state if this connection still
             // owns the address. A reconnected sidecar may have already claimed it.
@@ -855,12 +1351,12 @@ export function createSidecarRouter(config) {
                 // reconnect re-bootstraps via the router's
                 // restore-fires-callback path.
                 connectorStates.delete(addr);
-                const deployReq = pendingDeploys.get(addr);
-                if (deployReq !== undefined && deployReq.ws === ws) {
-                    clearTimeout(deployReq.timer);
-                    pendingDeploys.delete(addr);
-                    deployReq.reject(`Sidecar ${conn.sidecarId} disconnected`);
-                }
+                // Retain this address's un-acked pending mail across the disconnect:
+                // its in-flight retry timers target a dead socket (cleared), but the
+                // entries are held so a verified reconnect redelivers them, closing the
+                // connected-window drop rather than losing the mail. Bounded by a
+                // retention TTL.
+                retainPendingMailForAddress(addr);
                 // Create a queue entry so messages can accumulate while the
                 // sidecar is disconnected. Skip if the agent is being undeployed --
                 // there is no point queuing messages for an agent being torn down.
@@ -885,6 +1381,22 @@ export function createSidecarRouter(config) {
         for (const addr of conn.workflowAddresses) {
             if (addressIndex.get(addr) === ws) {
                 addressIndex.delete(addr);
+                // Retain un-acked workflow trigger mail across the disconnect for the
+                // same reason as the session loop above -- a challenged reconnect
+                // redelivers it. This is un-acked TRIGGER mail, distinct from the
+                // deployment's in-flight run state (reconstructed sidecar-locally); the
+                // "no disconnect queue" note above is about that run state, not this.
+                retainPendingMailForAddress(addr);
+            }
+        }
+        if (conn.identity.kind === "allocated") {
+            const current = allocatedConnections.get(conn.identity.allocationId);
+            if (current?.ws === ws) {
+                allocatedConnections.delete(conn.identity.allocationId);
+                allocated = {
+                    allocationId: conn.identity.allocationId,
+                    generation: conn.identity.generation,
+                };
             }
         }
         connections.delete(ws);
@@ -910,6 +1422,16 @@ export function createSidecarRouter(config) {
             pending.delete(requestId);
             req.reject(`Sidecar ${conn.sidecarId} disconnected`);
         }
+        // Reject every deploy issued on this socket, including allocated
+        // workflow deployments stored in `workflowAddresses` rather than
+        // `agentAddresses`.
+        for (const [agentAddress, req] of pendingDeploys) {
+            if (req.ws !== ws)
+                continue;
+            clearTimeout(req.timer);
+            pendingDeploys.delete(agentAddress);
+            req.reject(`Sidecar ${conn.sidecarId} disconnected`);
+        }
         // Reject any in-flight pack transfers for this sidecar.
         for (const [transferId, pack] of pendingPacks) {
             if (pack.ws !== ws)
@@ -926,6 +1448,17 @@ export function createSidecarRouter(config) {
             pendingUndeploys.delete(addr);
             req.reject(`Sidecar ${conn.sidecarId} disconnected`);
         }
+        // Reject any in-flight probes sent to this sidecar. A probe never enters
+        // the address maps, so this ws-keyed sweep is its ONLY disconnect cleanup:
+        // without it a probe whose sidecar drops mid-flight would hang until its
+        // own timeout instead of failing fast on the disconnect.
+        for (const [requestId, probe] of pendingProbes) {
+            if (probe.ws !== ws)
+                continue;
+            clearTimeout(probe.timer);
+            pendingProbes.delete(requestId);
+            probe.reject(`Sidecar ${conn.sidecarId} disconnected`);
+        }
         // Cancel any in-flight inbound pack transfers from this sidecar
         // across both receivers. The two receivers track their own in-
         // flight transferIds, so a pending workflow-run transfer for an
@@ -944,6 +1477,7 @@ export function createSidecarRouter(config) {
         }
         events.emit("sidecar.disconnect", {
             ownedAddresses: [...owned],
+            ...(allocated !== undefined ? { allocated } : {}),
         });
         logger.info `Sidecar ${conn.sidecarId} disconnected`;
     }
@@ -994,40 +1528,78 @@ export function createSidecarRouter(config) {
         pending.delete(requestId);
         req.reject(error);
     }
-    function resolvePackPending(transferId) {
-        const entry = pendingPacks.get(transferId);
+    function packResponseMatches(entry, ws, frame) {
+        return (entry.ws === ws &&
+            entry.agentAddress === frame.agentAddress &&
+            entry.repoId.kind === frame.repoId.kind &&
+            entry.repoId.id === frame.repoId.id);
+    }
+    function resolvePackPending(ws, frame) {
+        const entry = pendingPacks.get(frame.transferId);
         if (entry === undefined)
             return;
+        if (!packResponseMatches(entry, ws, frame)) {
+            logger.warn `Ignoring repo.pack.ack for transfer ${frame.transferId} from a connection that does not own the pending transfer`;
+            return;
+        }
         clearTimeout(entry.timer);
-        pendingPacks.delete(transferId);
+        pendingPacks.delete(frame.transferId);
         entry.resolve();
     }
-    function rejectPackPending(transferId, reason) {
-        const entry = pendingPacks.get(transferId);
+    function rejectPackPending(ws, frame) {
+        const entry = pendingPacks.get(frame.transferId);
         if (entry === undefined)
             return;
+        if (!packResponseMatches(entry, ws, frame)) {
+            logger.warn `Ignoring repo.pack.reject for transfer ${frame.transferId} from a connection that does not own the pending transfer`;
+            return;
+        }
         clearTimeout(entry.timer);
-        pendingPacks.delete(transferId);
-        entry.reject(reason);
+        pendingPacks.delete(frame.transferId);
+        // Surface the receiver's specific cause when it carried one, so the awaiting
+        // push sees "corrupt: <detail>" rather than only the coarse reason.
+        entry.reject(frame.detail !== undefined
+            ? `${frame.reason}: ${frame.detail}`
+            : frame.reason);
     }
-    function resolveUndeployPending(agentAddress) {
+    function resolveUndeployPending(ws, agentAddress) {
         const req = pendingUndeploys.get(agentAddress);
         if (req === undefined) {
             logger.warn `Received agent.undeploy.ack for "${agentAddress}" with no pending undeploy`;
             return;
         }
+        if (req.ws !== ws)
+            return;
         clearTimeout(req.timer);
         pendingUndeploys.delete(agentAddress);
         req.resolve();
     }
-    function rejectUndeployPending(agentAddress, error) {
+    function rejectUndeployPending(ws, agentAddress, error) {
         const req = pendingUndeploys.get(agentAddress);
         if (req === undefined)
             return;
+        if (req.ws !== ws)
+            return;
         clearTimeout(req.timer);
         pendingUndeploys.delete(agentAddress);
         req.reject(error);
     }
+    function resolveProbe(requestId, result) {
+        const req = pendingProbes.get(requestId);
+        if (req === undefined)
+            return;
+        clearTimeout(req.timer);
+        pendingProbes.delete(requestId);
+        req.resolve(result);
+    }
+    function rejectProbe(requestId, error) {
+        const req = pendingProbes.get(requestId);
+        if (req === undefined)
+            return;
+        clearTimeout(req.timer);
+        pendingProbes.delete(requestId);
+        req.reject(error);
+    }
     // Routing rule: pick the receiver dedicated to the repoId.kind the
     // frame carries. The receivers' in-flight state is independent, so a
     // workflow-run transferId can never collide with or evict an
@@ -1048,6 +1620,8 @@ export function createSidecarRouter(config) {
     function pickReceivePackLookup(repoId) {
         switch (repoId.kind) {
             case "agent-state":
+                // The agent-state lookup ignores the `source` argument the workflow-run
+                // lookup takes; the two are otherwise the same contract.
                 return lookups.receiveAgentStatePack;
             case "workflow-run":
                 return lookups.receiveWorkflowRunPack;
@@ -1063,6 +1637,17 @@ export function createSidecarRouter(config) {
             logger.warn `Received repo.pack.push for unrouted agent ${frame.agentAddress}`;
             return;
         }
+        if (!connCanPushRepo(conn, frame.agentAddress, frame.repoId)) {
+            logger.warn `Rejected repo.pack.push outside sidecar ${conn.sidecarId}'s authenticated repository scope`;
+            conn.send({
+                type: "repo.pack.reject",
+                agentAddress: frame.agentAddress,
+                repoId: frame.repoId,
+                transferId: frame.transferId,
+                reason: "path_violation",
+            });
+            return;
+        }
         const picked = pickPackReceiver(frame.repoId);
         if (picked === null) {
             logger.warn `Received repo.pack.push with unsupported repoId.kind ${frame.repoId.kind}`;
@@ -1094,6 +1679,17 @@ export function createSidecarRouter(config) {
             logger.warn `Received repo.pack.done for unrouted agent ${frame.agentAddress}`;
             return;
         }
+        if (!connCanPushRepo(conn, frame.agentAddress, frame.repoId)) {
+            logger.warn `Rejected repo.pack.done outside sidecar ${conn.sidecarId}'s authenticated repository scope`;
+            conn.send({
+                type: "repo.pack.reject",
+                agentAddress: frame.agentAddress,
+                repoId: frame.repoId,
+                transferId: frame.transferId,
+                reason: "path_violation",
+            });
+            return;
+        }
         const picked = pickPackReceiver(frame.repoId);
         if (picked === null) {
             logger.warn `Received repo.pack.done with unsupported repoId.kind ${frame.repoId.kind}`;
@@ -1127,7 +1723,15 @@ export function createSidecarRouter(config) {
             });
             return;
         }
-        const verdict = await receivePackLookup(frame.repoId, result.pack, result.ref, result.commitSha);
+        const verdict = await receivePackLookup(frame.repoId, result.pack, result.ref, result.commitSha, conn.identity.kind === "allocated"
+            ? {
+                kind: "allocated",
+                agentAddress: frame.agentAddress,
+                allocationId: conn.identity.allocationId,
+                anchorRunId: conn.identity.anchorRunId,
+                generation: conn.identity.generation,
+            }
+            : { kind: "shared", agentAddress: frame.agentAddress });
         // Connection may have closed during async verification.
         const currentConn = connections.get(ws);
         if (currentConn === undefined)
@@ -1164,6 +1768,110 @@ export function createSidecarRouter(config) {
      * never persisted into the reconnect set and never resurrected on
      * reconnect.
      */
+    function fenceAllocation(allocationId, generation) {
+        const existing = allocationFences.get(allocationId);
+        if (existing !== undefined && generation < existing) {
+            throw new Error(`Cannot move allocation ${allocationId} fence backward from ${String(existing)} to ${String(generation)}`);
+        }
+        allocationFences.set(allocationId, generation);
+        const current = allocatedConnections.get(allocationId);
+        if (current !== undefined && current.identity.generation !== generation) {
+            handleClose(current.ws);
+            current.ws.close();
+        }
+        const waiters = allocationWaiters.get(allocationId);
+        if (waiters === undefined)
+            return;
+        for (const waiter of [...waiters]) {
+            if (waiter.generation === generation)
+                continue;
+            clearTimeout(waiter.timer);
+            waiters.delete(waiter);
+            waiter.reject(new Error(`Allocation ${allocationId} advanced to generation ${String(generation)}`));
+        }
+        if (waiters.size === 0)
+            allocationWaiters.delete(allocationId);
+    }
+    async function getAllocatedConnection(target, use) {
+        if (allocationFences.get(target.allocationId) !== target.generation) {
+            throw new Error(`Allocation ${target.allocationId} generation ${String(target.generation)} is not current`);
+        }
+        const current = allocatedConnections.get(target.allocationId);
+        if (current === undefined ||
+            current.identity.generation !== target.generation) {
+            throw new Error(`Allocated sidecar is not connected for allocation ${target.allocationId} generation ${String(target.generation)}`);
+        }
+        if (!(await validateSidecarIdentity(current.identity, use))) {
+            if (allocatedConnections.get(target.allocationId) === current) {
+                handleClose(current.ws);
+                current.ws.close();
+            }
+            throw new Error(`Allocated sidecar identity is no longer current for allocation ${target.allocationId}`);
+        }
+        if (allocatedConnections.get(target.allocationId) !== current) {
+            throw new Error(`Allocated sidecar connection changed for allocation ${target.allocationId}`);
+        }
+        const conn = connections.get(current.ws);
+        if (conn === undefined ||
+            conn.identity.kind !== "allocated" ||
+            conn.identity.allocationId !== target.allocationId ||
+            conn.identity.generation !== target.generation) {
+            throw new Error(`Allocated sidecar is not connected for allocation ${target.allocationId}`);
+        }
+        return { ws: current.ws, conn };
+    }
+    async function isAllocatedSidecarReady(target) {
+        try {
+            await getAllocatedConnection(target, "readiness");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function isAllocatedWorkflowActive(target) {
+        try {
+            const { conn } = await getAllocatedConnection(target, "readiness");
+            if (conn.identity.kind !== "allocated")
+                return false;
+            return conn.workflowAddresses.has(conn.identity.workflowRunAddress);
+        }
+        catch {
+            return false;
+        }
+    }
+    async function waitForAllocatedSidecar(target, timeoutMs) {
+        if (await isAllocatedSidecarReady(target))
+            return;
+        if (allocationFences.get(target.allocationId) !== target.generation) {
+            throw new Error(`Allocation ${target.allocationId} generation ${String(target.generation)} is not current`);
+        }
+        if (timeoutMs <= 0) {
+            throw new Error(`Timed out waiting for allocated sidecar ${target.allocationId}`);
+        }
+        await new Promise((resolve, reject) => {
+            const waiter = {
+                generation: target.generation,
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    const current = allocationWaiters.get(target.allocationId);
+                    current?.delete(waiter);
+                    if (current?.size === 0) {
+                        allocationWaiters.delete(target.allocationId);
+                    }
+                    reject(new Error(`Timed out waiting for allocated sidecar ${target.allocationId} generation ${String(target.generation)}`));
+                }, timeoutMs),
+            };
+            let waiters = allocationWaiters.get(target.allocationId);
+            if (waiters === undefined) {
+                waiters = new Set();
+                allocationWaiters.set(target.allocationId, waiters);
+            }
+            waiters.add(waiter);
+            void notifyAllocationWaiters(target.allocationId);
+        });
+    }
     function bindStepRoute(stepAddress) {
         const ws = addressIndex.get(stepAddress) ?? findSidecarForNewAgent(stepAddress);
         if (ws === undefined) {
@@ -1173,6 +1881,18 @@ export function createSidecarRouter(config) {
         if (conn === undefined) {
             throw new Error(`No sidecar connected to stage workflow step "${stepAddress}"`);
         }
+        if (conn.identity.kind !== "shared") {
+            throw new Error(`Allocated sidecar ${conn.sidecarId} cannot receive ordinary workflow step ${stepAddress}`);
+        }
+        conn.workflowAddresses.add(stepAddress);
+        addressIndex.set(stepAddress, ws);
+    }
+    async function bindAllocatedStepRoute(target, stepAddress) {
+        const { ws, conn } = await getAllocatedConnection(target, "routing");
+        const existing = addressIndex.get(stepAddress);
+        if (existing !== undefined && existing !== ws) {
+            throw new Error(`Workflow step ${stepAddress} is already routed to another sidecar`);
+        }
         conn.workflowAddresses.add(stepAddress);
         addressIndex.set(stepAddress, ws);
     }
@@ -1191,6 +1911,17 @@ export function createSidecarRouter(config) {
         }
         addressIndex.delete(stepAddress);
     }
+    function unbindAllocatedStepRoute(target, stepAddress) {
+        const current = allocatedConnections.get(target.allocationId);
+        if (current === undefined ||
+            current.identity.generation !== target.generation) {
+            return;
+        }
+        if (addressIndex.get(stepAddress) !== current.ws)
+            return;
+        connections.get(current.ws)?.workflowAddresses.delete(stepAddress);
+        addressIndex.delete(stepAddress);
+    }
     // Pack transfers may take longer than session requests due to data volume.
     const PACK_TIMEOUT_MS = requestTimeoutMs * 4;
     function sendPack(agentAddress, pack, ref, commitSha, options) {
@@ -1202,6 +1933,12 @@ export function createSidecarRouter(config) {
         if (conn === undefined) {
             return Promise.reject(new Error(`No sidecar connected for agent "${agentAddress}"`));
         }
+        if (conn.identity.kind !== "shared") {
+            return Promise.reject(new Error(`Allocated sidecar ${conn.sidecarId} requires allocation-bound pack routing for "${agentAddress}"`));
+        }
+        return sendPackOnConnection(ws, conn, agentAddress, pack, ref, commitSha, options);
+    }
+    function sendPackOnConnection(ws, conn, agentAddress, pack, ref, commitSha, options) {
         const transferId = `pack-${++packCounter}`;
         // For the agent-state flow the destination agent and the source repo
         // are the same entity, so `repoId.id === agentAddress`. Asset packs
@@ -1222,6 +1959,8 @@ export function createSidecarRouter(config) {
             pendingPacks.set(transferId, {
                 transferId,
                 ws,
+                agentAddress,
+                repoId,
                 resolve,
                 reject(error) {
                     reject(new Error(`Pack rejected: ${error}`));
@@ -1251,65 +1990,167 @@ export function createSidecarRouter(config) {
             });
         });
     }
-    function routeMail(agentAddress, rawMessage) {
+    async function sendPackToAllocation(target, agentAddress, pack, ref, commitSha, options) {
+        const { ws, conn } = await getAllocatedConnection(target, "routing");
+        if (addressIndex.get(agentAddress) !== ws) {
+            throw new Error(`Address ${agentAddress} is not routed on allocation ${target.allocationId}`);
+        }
+        return sendPackOnConnection(ws, conn, agentAddress, pack, ref, commitSha, options);
+    }
+    async function sendWorkflowRunPackToAllocation(target, agentAddress, pack, ref, commitSha) {
+        const { ws, conn } = await getAllocatedConnection(target, "routing");
+        if (conn.identity.kind !== "allocated") {
+            throw new Error(`Allocation ${target.allocationId} resolved to a shared sidecar`);
+        }
+        if (agentAddress !== conn.identity.workflowRunAddress) {
+            throw new Error(`Allocation ${target.allocationId} cannot restore unrelated address ${agentAddress}`);
+        }
+        if (conn.workflowAddresses.has(agentAddress)) {
+            throw new Error(`Allocation ${target.allocationId} already hosts active workflow ${agentAddress}; refusing to overwrite its run history`);
+        }
+        return sendPackOnConnection(ws, conn, agentAddress, pack, ref, commitSha, {
+            repoId: {
+                kind: "workflow-run",
+                id: deriveWorkflowRunRepoId(agentAddress),
+            },
+        });
+    }
+    function routeMail(agentAddress, rawMessage, messageId, runGrants) {
+        // Carry the hub-minted messageId on the frame so the sidecar's durable-
+        // receipt ack (`mail.inbound.ack`) keys on the same id the hub tracks, and
+        // a redelivery replays identical bytes for the downstream RunStarted dedup.
+        // Optional: the workflow-trigger and session-conversation callers supply
+        // it (they participate in the ack/retry handshake); a caller without a
+        // hub-minted id omits it and the delivery is not tracked for redelivery.
+        const frame = {
+            type: "mail.inbound",
+            agentAddress,
+            rawMessage,
+            ...(messageId !== undefined ? { messageId } : {}),
+        };
         const ws = addressIndex.get(agentAddress);
         if (ws !== undefined) {
             const conn = connections.get(ws);
             if (conn !== undefined) {
-                conn.send({
-                    type: "mail.inbound",
-                    agentAddress,
-                    rawMessage,
-                });
+                conn.send(frame);
+                // Track the delivery for redelivery until the sidecar acks its durable
+                // inbox write. Only mail carrying a hub-minted messageId participates
+                // in the ack handshake; relayed agent-to-agent mail omits it and is
+                // delivered fire-and-forget as before. A mail that triggered a workflow
+                // run carries the run's grants so redelivery can replay them ahead of
+                // the mail.
+                if (messageId !== undefined) {
+                    trackPendingMail(agentAddress, messageId, frame, runGrants);
+                }
                 return true;
             }
         }
         // If the agent recently disconnected, queue for delivery on reconnect.
-        const frame = { type: "mail.inbound", agentAddress, rawMessage };
         return enqueueForDisconnected(agentAddress, frame);
     }
-    async function handleDeployAck(agentAddress, publicKey) {
-        if (!pendingDeploys.has(agentAddress)) {
-            logger.warn `Received agent.deploy.ack for "${agentAddress}" with no pending deploy`;
+    function sendRunGrants(agentAddress, runId, stepGrants) {
+        const frame = {
+            type: "run.grants",
+            agentAddress,
+            runId,
+            stepGrants,
+        };
+        const ws = addressIndex.get(agentAddress);
+        if (ws !== undefined) {
+            const conn = connections.get(ws);
+            if (conn !== undefined) {
+                conn.send(frame);
+                return true;
+            }
+        }
+        // Mirror routeMail: if the address has a live disconnect queue, ride it
+        // so a run.grants issued in the window between deploy and the first
+        // reconnect survives the same way the dispatching trigger mail does.
+        // A queue exists only while the deployment address is still on
+        // agentAddresses (pre-first-reconnect); after a challenged reconnect it
+        // moves to workflowAddresses, which handleClose leaves unqueued because
+        // that generation's in-flight run state is reconstructed sidecar-locally.
+        // Returning without enqueueing there is correct; enqueueing is what keeps
+        // grants and mail from diverging in the pre-reconnect window.
+        return enqueueForDisconnected(agentAddress, frame);
+    }
+    async function sendWorkflowRunDispatchToAllocation(target, agentAddress, runId, stepGrants, rawMessage, messageId) {
+        const { ws, conn } = await getAllocatedConnection(target, "routing");
+        if (addressIndex.get(agentAddress) !== ws) {
+            throw new Error(`Address ${agentAddress} is not routed on allocation ${target.allocationId}`);
+        }
+        const runGrants = { runId, stepGrants };
+        conn.send({
+            type: "run.grants",
+            agentAddress,
+            runId,
+            stepGrants,
+        });
+        const frame = {
+            type: "mail.inbound",
+            agentAddress,
+            rawMessage,
+            messageId,
+        };
+        conn.send(frame);
+        trackPendingMail(agentAddress, messageId, frame, runGrants, target);
+    }
+    async function handleDeployAck(ws, frame) {
+        const req = pendingDeploys.get(frame.agentAddress);
+        if (req === undefined) {
+            logger.warn `Received agent.deploy.ack for "${frame.agentAddress}" with no pending deploy`;
             return;
         }
+        if (req.ws !== ws)
+            return;
         if (events.listenerCount("agent.deploy.ack") > 0) {
             try {
+                const identity = connections.get(ws)?.identity;
                 await events.emitAndAwait("agent.deploy.ack", {
-                    agentAddress,
-                    publicKey,
+                    agentAddress: frame.agentAddress,
+                    publicKey: frame.publicKey,
+                    ...(identity?.kind === "allocated"
+                        ? {
+                            allocated: {
+                                allocationId: identity.allocationId,
+                                anchorRunId: identity.anchorRunId,
+                                generation: identity.generation,
+                            },
+                        }
+                        : {}),
                 });
             }
             catch (err) {
-                rejectDeployPending(agentAddress, `Failed to store public key: ${err instanceof Error ? err.message : String(err)}`);
+                rejectDeployPending(req, `Failed to store public key: ${err instanceof Error ? err.message : String(err)}`);
                 return;
             }
         }
-        resolveDeployPending(agentAddress);
+        resolveDeployPending(req, frame.publicKey);
     }
-    function resolveDeployPending(agentAddress) {
-        const req = pendingDeploys.get(agentAddress);
-        if (req === undefined)
+    function resolveDeployPending(req, publicKey) {
+        if (pendingDeploys.get(req.agentAddress) !== req)
             return;
         clearTimeout(req.timer);
-        pendingDeploys.delete(agentAddress);
-        req.resolve();
+        pendingDeploys.delete(req.agentAddress);
+        req.resolve(publicKey);
     }
-    function rejectDeployPending(agentAddress, error) {
-        const req = pendingDeploys.get(agentAddress);
-        if (req === undefined)
+    function rejectDeployPending(req, error) {
+        if (pendingDeploys.get(req.agentAddress) !== req)
             return;
         clearTimeout(req.timer);
-        pendingDeploys.delete(agentAddress);
+        pendingDeploys.delete(req.agentAddress);
         req.reject(error);
     }
+    function rejectDeployPendingFromFrame(ws, agentAddress, error) {
+        const req = pendingDeploys.get(agentAddress);
+        if (req === undefined || req.ws !== ws)
+            return;
+        rejectDeployPending(req, error);
+    }
     async function sendAgentDeploy(agentAddress, harnessConfig, workflow) {
         if (hubPublicKeyHex === undefined) {
             throw new Error("Hub signing key is required for agent deployment");
         }
-        if (pendingDeploys.has(agentAddress)) {
-            throw new Error(`Deploy already in progress for agent "${agentAddress}"`);
-        }
         const ws = addressIndex.get(agentAddress) ?? findSidecarForNewAgent(agentAddress);
         if (ws === undefined) {
             throw new Error(`No sidecar available for agent "${agentAddress}"`);
@@ -1318,26 +2159,28 @@ export function createSidecarRouter(config) {
         if (conn === undefined) {
             throw new Error(`No sidecar connected for agent "${agentAddress}"`);
         }
-        conn.agentAddresses.add(agentAddress);
+        if (conn.identity.kind !== "shared") {
+            throw new Error(`Allocated sidecar ${conn.sidecarId} requires allocation-bound deploy routing`);
+        }
+        return sendAgentDeployOnConnection(ws, conn, agentAddress, harnessConfig, workflow);
+    }
+    function sendAgentDeployOnConnection(ws, conn, agentAddress, harnessConfig, workflow) {
+        if (hubPublicKeyHex === undefined) {
+            throw new Error("Hub signing key is required for agent deployment");
+        }
+        if (pendingDeploys.has(agentAddress)) {
+            throw new Error(`Deploy already in progress for agent "${agentAddress}"`);
+        }
+        const addressSet = conn.identity.kind === "allocated"
+            ? conn.workflowAddresses
+            : conn.agentAddresses;
+        addressSet.add(agentAddress);
         addressIndex.set(agentAddress, ws);
         return new Promise((resolve, reject) => {
-            // The deploy-ack handler does not currently thread the
-            // sidecar-reported public key back through the pending-deploy
-            // resolver; it only fires `agent.deploy.ack` listeners and then
-            // resolves the pending deploy. Capture the key via a one-shot
-            // listener so the return value carries it without a wire-shape
-            // change to `agent.deploy.ack`.
-            let capturedPublicKey;
-            const detachListener = events.on("agent.deploy.ack", (payload) => {
-                if (payload.agentAddress === agentAddress) {
-                    capturedPublicKey = payload.publicKey;
-                }
-            });
             const timer = setTimeout(() => {
-                detachListener();
                 pendingDeploys.delete(agentAddress);
                 if (addressIndex.get(agentAddress) === ws) {
-                    conn.agentAddresses.delete(agentAddress);
+                    addressSet.delete(agentAddress);
                     addressIndex.delete(agentAddress);
                 }
                 reject(new Error(`Deploy of "${agentAddress}" timed out after ${requestTimeoutMs}ms`));
@@ -1345,18 +2188,12 @@ export function createSidecarRouter(config) {
             pendingDeploys.set(agentAddress, {
                 agentAddress,
                 ws,
-                resolve() {
-                    detachListener();
-                    if (capturedPublicKey === undefined) {
-                        reject(new Error(`Deploy of "${agentAddress}" resolved without an agent.deploy.ack publicKey payload`));
-                        return;
-                    }
-                    resolve({ publicKey: capturedPublicKey });
+                resolve(publicKey) {
+                    resolve({ publicKey });
                 },
                 reject(error) {
-                    detachListener();
                     if (addressIndex.get(agentAddress) === ws) {
-                        conn.agentAddresses.delete(agentAddress);
+                        addressSet.delete(agentAddress);
                         addressIndex.delete(agentAddress);
                     }
                     reject(new Error(error));
@@ -1373,6 +2210,20 @@ export function createSidecarRouter(config) {
             });
         });
     }
+    async function sendAgentDeployToAllocation(target, agentAddress, harnessConfig, workflow) {
+        const { ws, conn } = await getAllocatedConnection(target, "routing");
+        if (conn.identity.kind !== "allocated") {
+            throw new Error(`Allocation ${target.allocationId} resolved to a shared sidecar`);
+        }
+        if (agentAddress !== conn.identity.workflowRunAddress) {
+            throw new Error(`Allocation ${target.allocationId} cannot deploy unrelated address ${agentAddress}`);
+        }
+        const existing = addressIndex.get(agentAddress);
+        if (existing !== undefined && existing !== ws) {
+            throw new Error(`Deployment ${agentAddress} is already routed to another sidecar`);
+        }
+        return sendAgentDeployOnConnection(ws, conn, agentAddress, harnessConfig, workflow);
+    }
     /**
      * Provision one step of a multi-step deploy on the sidecar WITHOUT
      * spawning: the sidecar initializes the step's agent-state repo and
@@ -1388,12 +2239,6 @@ export function createSidecarRouter(config) {
      * the caller owns tearing the route down via `unbindStepRoute`.
      */
     function sendProvisionStep(agentAddress, harnessConfig) {
-        if (hubPublicKeyHex === undefined) {
-            throw new Error("Hub signing key is required for step provisioning");
-        }
-        if (pendingDeploys.has(agentAddress)) {
-            throw new Error(`Deploy already in progress for agent "${agentAddress}"`);
-        }
         const ws = addressIndex.get(agentAddress);
         if (ws === undefined) {
             throw new Error(`Step route for "${agentAddress}" is not bound; call bindStepRoute before provisioning`);
@@ -1402,6 +2247,18 @@ export function createSidecarRouter(config) {
         if (conn === undefined) {
             throw new Error(`No sidecar connected for agent "${agentAddress}"`);
         }
+        if (conn.identity.kind !== "shared") {
+            throw new Error(`Allocated sidecar ${conn.sidecarId} requires allocation-bound step provisioning`);
+        }
+        return sendProvisionStepOnConnection(ws, conn, agentAddress, harnessConfig);
+    }
+    function sendProvisionStepOnConnection(ws, conn, agentAddress, harnessConfig) {
+        if (hubPublicKeyHex === undefined) {
+            throw new Error("Hub signing key is required for step provisioning");
+        }
+        if (pendingDeploys.has(agentAddress)) {
+            throw new Error(`Deploy already in progress for agent "${agentAddress}"`);
+        }
         const hubKey = hubPublicKeyHex;
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -1415,7 +2272,7 @@ export function createSidecarRouter(config) {
             pendingDeploys.set(agentAddress, {
                 agentAddress,
                 ws,
-                resolve() {
+                resolve(_publicKey) {
                     resolve();
                 },
                 reject(error) {
@@ -1433,11 +2290,58 @@ export function createSidecarRouter(config) {
             });
         });
     }
+    async function sendProvisionStepToAllocation(target, agentAddress, harnessConfig) {
+        const { ws, conn } = await getAllocatedConnection(target, "routing");
+        if (addressIndex.get(agentAddress) !== ws) {
+            throw new Error(`Step route ${agentAddress} is not bound to allocation ${target.allocationId}`);
+        }
+        return sendProvisionStepOnConnection(ws, conn, agentAddress, harnessConfig);
+    }
     function findSidecarForNewAgent(_agentAddress) {
-        const first = connections.entries().next();
-        if (first.done)
-            return undefined;
-        return first.value[0];
+        for (const [ws, conn] of connections) {
+            if (conn.identity.kind === "shared")
+                return ws;
+        }
+        return undefined;
+    }
+    function sendProbe(args) {
+        // Select any connected sidecar, exactly as the pre-deploy window does.
+        // A probe runs in the sidecar's pre-deploy state, so it targets a
+        // connection, not an address -- `findSidecarForNewAgent` ignores its
+        // argument and returns the first connection. Throw immediately on an empty
+        // registry rather than register a probe that could only time out.
+        const ws = findSidecarForNewAgent("");
+        if (ws === undefined) {
+            return Promise.reject(new Error("No sidecar available to probe workflow"));
+        }
+        const conn = connections.get(ws);
+        if (conn === undefined) {
+            return Promise.reject(new Error("No sidecar connected to probe workflow"));
+        }
+        const requestId = nextRequestId();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pendingProbes.delete(requestId);
+                reject(new Error(`Probe ${requestId} timed out after ${probeTimeoutMs}ms`));
+            }, probeTimeoutMs);
+            pendingProbes.set(requestId, {
+                requestId,
+                ws,
+                resolve,
+                reject(error) {
+                    reject(new Error(error));
+                },
+                timer,
+            });
+            conn.send({
+                type: "workflow.probe.request",
+                requestId,
+                source: args.source,
+                closure: args.closure,
+                entry: args.entry,
+                ...(args.assets !== undefined ? { assets: args.assets } : {}),
+            });
+        });
     }
     function sendAgentUndeploy(agentAddress, reason) {
         const ws = addressIndex.get(agentAddress);
@@ -1529,6 +2433,14 @@ export function createSidecarRouter(config) {
             defaultSource,
         }));
     }
+    async function sendCredentialsUpdate(agentAddress, delivery) {
+        await sendRequest(agentAddress, (requestId) => ({
+            type: "credentials.update",
+            requestId,
+            agentAddress,
+            delivery,
+        }));
+    }
     function sendSyncRequest(agentAddress) {
         const ws = addressIndex.get(agentAddress);
         if (ws === undefined) {
@@ -1563,6 +2475,13 @@ export function createSidecarRouter(config) {
             payload: opts.payload,
         });
     }
+    async function sendSignalDeliverToAllocation(target, opts) {
+        const { ws, conn } = await getAllocatedConnection(target, "routing");
+        if (addressIndex.get(opts.agentAddress) !== ws) {
+            throw new Error(`Address ${opts.agentAddress} is not routed on allocation ${target.allocationId}`);
+        }
+        conn.send({ type: "signal.deliver", ...opts });
+    }
     function sendDrain(opts) {
         const ws = addressIndex.get(opts.agentAddress);
         if (ws === undefined) {
@@ -1583,15 +2502,30 @@ export function createSidecarRouter(config) {
         handleMessage,
         handleClose,
         routeMail,
+        sendRunGrants,
         sendAgentDeploy,
+        sendProbe,
         sendAgentUndeploy,
         sendSourcesUpdate,
+        sendCredentialsUpdate,
         sendPack,
+        sendPackToAllocation,
+        sendWorkflowRunPackToAllocation,
+        fenceAllocation,
+        waitForAllocatedSidecar,
+        isAllocatedSidecarReady,
+        isAllocatedWorkflowActive,
+        sendAgentDeployToAllocation,
         bindStepRoute,
+        bindAllocatedStepRoute,
         unbindStepRoute,
+        unbindAllocatedStepRoute,
         sendProvisionStep,
+        sendProvisionStepToAllocation,
+        sendWorkflowRunDispatchToAllocation,
         sendSyncRequest,
         sendSignalDeliver,
+        sendSignalDeliverToAllocation,
         sendDrain,
         subscribeAgent,
         dispatchAgentEvent: dispatchToSubscribers,