@cello-protocol/daemon 0.0.27 → 0.0.29

package/dist/cross-node-negotiation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Cross-node session establishment — discovery outcome types + the pure online-result classifier
+ * (Story B, item 2).
+ *
+ * The daemon's discovery step produces a DiscoveryOutcome; the retry loop handles the transport /
+ * directory-fault / no-reply variants attempt-aware (each with its own log + terminal reason), and
+ * defers the actual 3-state routing decision to classifyOnlineResult — kept pure so the branch and
+ * error-code mapping are unit-testable in isolation (mirrors the directory-side resolveDiscoveryState).
+ *
+ * Design: docs/planning/discussion_logs/2026-07-04_1730_cross-node-session-topology.md §"Item 2".
+ */
+export type DiscoveryOutcome = {
+    kind: "result";
+    state: "online" | "offline" | "unknown_agent";
+    owningNodeIds: string[];
+} | {
+    kind: "error";
+    reason: string;
+} | {
+    kind: "malformed";
+} | {
+    kind: "timeout";
+} | {
+    kind: "send_failed";
+    reason: string;
+};
+export type ResultAction = {
+    kind: "same_node";
+} | {
+    kind: "cross_node";
+    owningNodeId: string;
+} | {
+    kind: "unknown_agent";
+} | {
+    kind: "offline";
+} | {
+    kind: "retry";
+};
+/**
+ * Route a 3-state discovery RESULT into the next action. Pure. Retry counting, backoff, transport /
+ * directory-fault / timeout handling, and the actual I/O live in the daemon loop.
+ */
+export declare function classifyOnlineResult(state: "online" | "offline" | "unknown_agent", owningNodeIds: string[], homeNodeId: string | null): ResultAction;
+//# sourceMappingURL=cross-node-negotiation.d.ts.map

package/dist/cross-node-negotiation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-negotiation.d.ts","sourceRoot":"","sources":["../src/cross-node-negotiation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GAExB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,eAAe,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,GAG1F;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAEjC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GAGrB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAGnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,eAAe,EAC7C,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,YAAY,CAcd"}

package/dist/cross-node-negotiation.js

@@ -0,0 +1,34 @@
+/**
+ * Cross-node session establishment — discovery outcome types + the pure online-result classifier
+ * (Story B, item 2).
+ *
+ * The daemon's discovery step produces a DiscoveryOutcome; the retry loop handles the transport /
+ * directory-fault / no-reply variants attempt-aware (each with its own log + terminal reason), and
+ * defers the actual 3-state routing decision to classifyOnlineResult — kept pure so the branch and
+ * error-code mapping are unit-testable in isolation (mirrors the directory-side resolveDiscoveryState).
+ *
+ * Design: docs/planning/discussion_logs/2026-07-04_1730_cross-node-session-topology.md §"Item 2".
+ */
+/**
+ * Route a 3-state discovery RESULT into the next action. Pure. Retry counting, backoff, transport /
+ * directory-fault / timeout handling, and the actual I/O live in the daemon loop.
+ */
+export function classifyOnlineResult(state, owningNodeIds, homeNodeId) {
+    if (state === "unknown_agent")
+        return { kind: "unknown_agent" };
+    if (state === "offline")
+        return { kind: "offline" };
+    // state === "online": pick the owning node (list-valued; length 1 until the k>1 homing knob).
+    const owningNodeId = owningNodeIds[0];
+    // Online but no owner named is malformed — treat as transiently unresolved, retry (never dial a
+    // fabricated node).
+    if (!owningNodeId)
+        return { kind: "retry" };
+    // Same-node shortcut requires KNOWING our own node id (step-6 identity). Without it (homeNodeId
+    // null), we cannot prove co-location, so we take the cross-node path (which validates the owning
+    // node through the signed manifest before dialing).
+    if (homeNodeId !== null && owningNodeId === homeNodeId)
+        return { kind: "same_node" };
+    return { kind: "cross_node", owningNodeId };
+}
+//# sourceMappingURL=cross-node-negotiation.js.map

package/dist/cross-node-negotiation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-node-negotiation.js","sourceRoot":"","sources":["../src/cross-node-negotiation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwBH;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAA6C,EAC7C,aAAuB,EACvB,UAAyB;IAEzB,IAAI,KAAK,KAAK,eAAe;QAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IAChE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAEpD,8FAA8F;IAC9F,MAAM,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IACtC,gGAAgG;IAChG,oBAAoB;IACpB,IAAI,CAAC,YAAY;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC5C,gGAAgG;IAChG,iGAAiG;IACjG,oDAAoD;IACpD,IAAI,UAAU,KAAK,IAAI,IAAI,YAAY,KAAK,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACrF,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AAC9C,CAAC"}

package/dist/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EASrB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAM/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAsB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAM/G,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AA0InF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,SAAS,IAAI,oBAAoB,CAAC;IAClC;;;;OAIG;IACH,qBAAqB,IAAI,kBAAkB,CAAC;IAC5C;;;;;;;;OAQG;IACH,gBAAgB,IAAI,SAAS,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,oBAAoB,IAAI,kBAAkB,CAAC;IAC3C;;;OAGG;IACH,iBAAiB,IAAI,eAAe,CAAC;CACtC;AAyCD,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAwwI7E"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EASrB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAM/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAsB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAO/G,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AA0InF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,SAAS,IAAI,oBAAoB,CAAC;IAClC;;;;OAIG;IACH,qBAAqB,IAAI,kBAAkB,CAAC;IAC5C;;;;;;;;OAQG;IACH,gBAAgB,IAAI,SAAS,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,oBAAoB,IAAI,kBAAkB,CAAC;IAC3C;;;OAGG;IACH,iBAAiB,IAAI,eAAe,CAAC;CACtC;AAyCD,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAs/I7E"}

package/dist/daemon.js

@@ -51,7 +51,8 @@ import { upgradeAbsentToRecovered, hasAbsentParticipant } from "./seal-receipt-u
 import { MAX_CONTENT_BYTES, computeGenesisPrevRoot, buildAgentRevocationTbs } from "@cello-protocol/protocol-types";
 import { resolveCelloEnv, createTransportSelector, isProductionVariant, } from "./transport-composition.js";
 import { selectAdvertisedAddress } from "./transport-selector.js";
-import { parseSessionAssignment, sessionRequestErrorReason } from "./session-assignment-parser.js";
+import { parseSessionAssignment, sessionRequestErrorReason, parseDiscoveryLookupResult, discoveryLookupErrorReason } from "./session-assignment-parser.js";
+import { classifyOnlineResult } from "./cross-node-negotiation.js";
 import { wireSessionCeremonyHandler, wireSessionOfferHandler, wireSealCeremonyHandler, verifyUnilateralCertificate, verifyBilateralSealCertificate, runAgentRefresh } from "./session-ceremony.js";
 import { reDeriveFrontiers, findInflatedFrontier, checkUnilateralFrontier } from "./seal-frontier-verify.js";
 import { LocalAutoNatStub } from "@cello-protocol/transport";
@@ -749,6 +750,193 @@ export async function startDaemon(config) {
     // agent concurrency is unaffected (separate streams). A directory-side echoed request id
     // would allow true concurrency later; this is the correct minimum.
     const negotiationInProgress = new Set();
+    // ─── Cross-node session establishment (Story B, item 2) ──────────────────────
+    // Helpers the negotiator composes: discover the target's home from replicated presence, then run
+    // the session_request over the RIGHT connection — the existing home stream when same-node, or a
+    // transient VISITING connection into the target's home node when cross-node. Directories never talk
+    // to each other; the client spans nodes on demand.
+    const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+    /**
+     * Issue a discovery_lookup on `signaling` and await the 3-state answer (bounded). Distinguishes,
+     * for the caller's retry logic and truthful error surface:
+     *  - send_failed (home stream down — TRANSPORT, never "old directory"),
+     *  - timeout (no reply — old directory OR a slow/dropped reply on a new one; retry, fall back last),
+     *  - error (directory DB fault — retryable, a DIRECTORY fault, not the counterparty being offline),
+     *  - malformed (a reply that didn't parse — protocol anomaly, retryable, surfaced distinctly),
+     *  - result (the 3-state answer).
+     * Emits the mandated observability events: directory.discovery.lookup on a result,
+     * directory.discovery.lookup.failed on a directory error / malformed reply.
+     */
+    async function runDiscoveryLookup(signaling, targetHex, timeoutMs, correlationId) {
+        let resolveFrame;
+        const pending = new Promise((r) => { resolveFrame = r; });
+        const unregister = signaling.registerInboundHandler((frame) => {
+            const t = frame["type"];
+            if (t === "discovery_lookup_result" || t === "discovery_lookup_error")
+                resolveFrame(frame);
+        });
+        try {
+            const sent = await signaling.sendRaw({
+                type: "discovery_lookup",
+                target_pubkey: new Uint8Array(Buffer.from(targetHex, "hex")),
+            });
+            if (!sent.ok) {
+                // The home stream is down — cannot look up (and today's local-only fallback would fail the
+                // same way). Surface the real transport reason, not an "old directory" misdiagnosis.
+                return { kind: "send_failed", reason: sent.reason ?? "signaling_unavailable" };
+            }
+            let timer;
+            const timeoutP = new Promise((r) => { timer = setTimeout(() => r({ type: "__timeout__" }), timeoutMs); });
+            const frame = await Promise.race([pending, timeoutP]);
+            clearTimeout(timer);
+            if (frame["type"] === "__timeout__")
+                return { kind: "timeout" };
+            if (frame["type"] === "discovery_lookup_error") {
+                const reason = discoveryLookupErrorReason(frame);
+                logger.warn("directory.discovery.lookup.failed", { target: targetHex.slice(0, 16), reason, correlationId });
+                return { kind: "error", reason };
+            }
+            const parsed = parseDiscoveryLookupResult(frame);
+            if (!parsed) {
+                // A reply came back but did not parse — a protocol/version anomaly on a directory that DID
+                // respond. Surface it distinctly from a clean directory DB error, and never as availability.
+                logger.warn("directory.discovery.lookup.failed", { target: targetHex.slice(0, 16), reason: "malformed_reply", correlationId });
+                return { kind: "malformed" };
+            }
+            logger.info("directory.discovery.lookup", {
+                target: targetHex.slice(0, 16),
+                state: parsed.state,
+                owningNode: parsed.owningNodeIds[0] ?? null,
+                correlationId,
+            });
+            return { kind: "result", state: parsed.state, owningNodeIds: parsed.owningNodeIds };
+        }
+        finally {
+            unregister();
+        }
+    }
+    /** Send a session_request over `signaling` and await the assignment / error (the extracted core). */
+    async function runSessionRequestOverSignaling(signaling, targetHex, sr, correlationId, agentName) {
+        let resolveFrame;
+        const pending = new Promise((r) => { resolveFrame = r; });
+        const unregister = signaling.registerInboundHandler((frame) => {
+            const t = frame["type"];
+            if (t === "session_assignment" || t === "session_request_error")
+                resolveFrame(frame);
+        });
+        try {
+            const sent = await signaling.sendRaw({
+                type: "session_request",
+                target_pubkey: new Uint8Array(Buffer.from(targetHex, "hex")),
+                initiator_session_peer_id: sr.peerId,
+                initiator_session_addrs: sr.addrs,
+                wants_session_offer: true,
+            });
+            if (!sent.ok) {
+                return { ok: false, reason: sent.reason ?? "directory_unreachable", guidance: sent.guidance ?? "Could not send session_request over the directory signaling stream." };
+            }
+            let timer;
+            const timeoutP = new Promise((r) => { timer = setTimeout(() => r({ type: "__timeout__" }), 30_000); });
+            const frame = await Promise.race([pending, timeoutP]);
+            clearTimeout(timer);
+            if (frame["type"] === "__timeout__") {
+                return { ok: false, reason: "timeout", guidance: "The directory did not return a session assignment within 30s. Retry once cello status shows directory_signaling connected." };
+            }
+            if (frame["type"] === "session_request_error") {
+                const reason = sessionRequestErrorReason(frame);
+                return { ok: false, reason, guidance: `The directory refused the session request (${reason}). Ensure the counterparty is registered and online.` };
+            }
+            const raw = frame["assignment"];
+            const assignment = raw ? parseSessionAssignment(raw) : null;
+            if (!assignment) {
+                return { ok: false, reason: "assignment_parse_failed", guidance: "The directory's session_assignment was missing or malformed." };
+            }
+            logger.info("session.negotiate.assignment.received", { agentName, correlationId, signatureType: assignment.signature_type });
+            return { ok: true, assignment };
+        }
+        finally {
+            unregister();
+        }
+    }
+    /**
+     * Open a transient VISITING signaling connection into a specific directory node (the target's home)
+     * and wire ONLY what a cross-node initiator needs there: the delegated-signer ceremony handler (the
+     * broker asks the initiator to co-sign the assignment over THIS connection). Seal + inbound handlers
+     * are NOT wired — the seal is client-coordinated over the agent's own roster, and this connection is
+     * initiator-only and transient. Caller MUST stop() it after the assignment arrives.
+     */
+    function openVisitingConnection(agentName, agentKeyProvider, agentPubkeyHex, endpoint, correlationId, nodeId) {
+        let nodeRef = null;
+        const connect = createSignalingConnect({
+            getDirectoryEndpoint: () => endpoint,
+            getAuthIdentity: () => ({ keyProvider: agentKeyProvider, pubkeyHex: agentPubkeyHex }),
+            logger,
+            challengeVerifier,
+            getManifestVersion: () => verifiedManifestVersion,
+            visiting: true, // cross-node item 3: the directory must NOT write presence for this connection
+            publishNode: (n) => { nodeRef = n; },
+        });
+        // maxReconnectAttempts: 1 — a transient connection should fail fast, not reconnect-loop forever.
+        const mgr = new SignalingManager({ connect, logger, maxReconnectAttempts: 1, maxBackoffMs: 3_000 });
+        wireSessionCeremonyHandler({
+            agentName,
+            persistence: getPersistence(agentName),
+            agentPubkeyHex,
+            getNode: () => nodeRef,
+            getDirectoryEndpoint: getFailoverEndpoint,
+            getConsortiumEndpoints: resolveConsortiumRoster,
+            signaling: mgr,
+            logger,
+        });
+        logger.info("signaling.visiting.connected", { agentName, node: nodeId, correlationId });
+        return {
+            mgr,
+            stop: async (reason) => {
+                logger.info("signaling.visiting.released", { agentName, node: nodeId, reason, correlationId });
+                await mgr.stop();
+            },
+        };
+    }
+    /**
+     * Resolve `owningNodeId` through the signed manifest and run the session_request over a transient
+     * visiting connection there. A node id that doesn't resolve in the roster is a hard error
+     * (discovery_node_unresolvable) — never a dial to an unvalidated endpoint.
+     */
+    async function runCrossNodeSetup(agentName, agentKeyProvider, agentPubkeyHex, owningNodeId, targetHex, sr, correlationId) {
+        const roster = await resolveConsortiumRoster();
+        const target = roster?.find((e) => e.nodeId === owningNodeId) ?? null;
+        if (!target) {
+            // Manifest MISS — the node genuinely isn't in the signed roster. A hard, non-retryable cause
+            // (distinct from a reachable-but-unconnectable node below).
+            logger.warn("session.crossnode.failed", { agentName, brokerNode: owningNodeId, reason: "discovery_node_unresolvable", correlationId });
+            return { ok: false, reason: "discovery_node_unresolvable", guidance: `The counterparty's home node (${owningNodeId}) is not in the signed consortium manifest. It may have left the consortium.` };
+        }
+        logger.info("session.crossnode.initiated", { agentName, brokerNode: owningNodeId, correlationId });
+        const visiting = openVisitingConnection(agentName, agentKeyProvider, agentPubkeyHex, { peerId: target.peerId, multiaddr: target.multiaddr }, correlationId, owningNodeId);
+        // Track the release reason across the finally (result is block-scoped in the try).
+        let releaseReason = "failure";
+        try {
+            if (!(await waitForSignalingConnected(visiting.mgr, 10_000))) {
+                // The node RESOLVED but the visiting dial/auth didn't complete in time — a TRANSIENT
+                // cross-region condition (latency, blip, cold handshake), NOT a manifest miss. Distinct
+                // reason, and the caller's retry loop treats it as retryable (re-discover → retry).
+                logger.warn("session.crossnode.failed", { agentName, brokerNode: owningNodeId, reason: "visiting_connection_unreachable", correlationId });
+                return { ok: false, reason: "visiting_connection_unreachable", guidance: `Could not establish a visiting connection to the counterparty's home node (${owningNodeId}) within 10s. Retry.` };
+            }
+            const result = await runSessionRequestOverSignaling(visiting.mgr, targetHex, sr, correlationId, agentName);
+            if (result.ok) {
+                releaseReason = "handoff-complete";
+                logger.info("session.crossnode.established", { agentName, brokerNode: owningNodeId, correlationId });
+            }
+            else {
+                logger.warn("session.crossnode.failed", { agentName, brokerNode: owningNodeId, reason: result.reason, correlationId });
+            }
+            return result;
+        }
+        finally {
+            await visiting.stop(releaseReason);
+        }
+    }
     const resolvedSessionNegotiator = sessionNegotiator ?? {
         negotiate: async (ctx) => {
             const kp = keyProviders.get(ctx.agentName);
@@ -791,62 +979,96 @@ export async function startDaemon(config) {
                     guidance: `Agent '${ctx.agentName}' could not establish its directory signaling stream within 10s. Check CELLO_DIRECTORY_URL and that the directory is reachable, then retry.`,
                 };
             }
-            // Single-flight claimed (above) → safe to register one inbound handler for this
-            // agent's reply; unregistered + slot released in finally.
+            // Single-flight claimed → the discover-first flow (one discovery + up to 3 session_request
+            // attempts, possibly over a transient visiting connection) runs under ONE slot; released in
+            // finally. A single directory-side echoed request id would allow true concurrency later.
             negotiationInProgress.add(ctx.agentName);
-            let resolveFrame;
-            const pending = new Promise((r) => {
-                resolveFrame = r;
-            });
-            const unregister = signaling.registerInboundHandler((frame) => {
-                const t = frame["type"];
-                if (t === "session_assignment" || t === "session_request_error")
-                    resolveFrame(frame);
-            });
             try {
-                const sent = await signaling.sendRaw({
-                    type: "session_request",
-                    target_pubkey: new Uint8Array(Buffer.from(targetHex, "hex")),
-                    initiator_session_peer_id: sr.peerId,
-                    initiator_session_addrs: sr.addrs,
-                    // WIRE-002 opt-in: ask the directory to run the session_offer→accept round-trip so
-                    // the assignment carries the counterparty's reachable session endpoint.
-                    wants_session_offer: true,
-                });
-                if (!sent.ok) {
-                    return {
-                        ok: false,
-                        reason: sent.reason ?? "directory_unreachable",
-                        guidance: sent.guidance ?? "Could not send session_request over the directory signaling stream.",
-                    };
-                }
-                let timer;
-                const timeoutP = new Promise((r) => {
-                    timer = setTimeout(() => r({ type: "__timeout__" }), 30_000);
-                });
-                const frame = await Promise.race([pending, timeoutP]);
-                clearTimeout(timer);
-                if (frame["type"] === "__timeout__") {
-                    return { ok: false, reason: "timeout", guidance: "The directory did not return a session assignment within 30s. Retry once cello status shows directory_signaling connected." };
-                }
-                if (frame["type"] === "session_request_error") {
-                    const reason = sessionRequestErrorReason(frame);
-                    return { ok: false, reason, guidance: `The directory refused the session request (${reason}). Ensure the counterparty is registered and online.` };
-                }
-                const raw = frame["assignment"];
-                const assignment = raw ? parseSessionAssignment(raw) : null;
-                if (!assignment) {
-                    return { ok: false, reason: "assignment_parse_failed", guidance: "The directory's session_assignment was missing or malformed." };
+                // DISCOVER FIRST. Because identity + presence are fully replicated, the agent's OWN home
+                // stream answers "where is the target?" authoritatively-enough (advisory — the target node's
+                // live #streams check stays the authority; a stale answer just triggers the retry below).
+                const homeNodeId = signaling.currentDirectoryNodeId;
+                const backoffs = [1_000, 3_000]; // between attempts — covers re-home + replication lag
+                const MAX_ATTEMPTS = 3;
+                for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+                    const disc = await runDiscoveryLookup(signaling, targetHex, 5_000, ctx.correlationId);
+                    // TRANSPORT: the home stream is down — retry (it may reconnect); local-only fallback would
+                    // fail the same way. Exhausted → the TRUTHFUL transport reason, never a false "offline".
+                    if (disc.kind === "send_failed") {
+                        logger.warn("session.discovery.send_failed", { agentName: ctx.agentName, attempt, reason: disc.reason, correlationId: ctx.correlationId });
+                        if (attempt < MAX_ATTEMPTS) {
+                            await sleepMs(backoffs[attempt - 1]);
+                            continue;
+                        }
+                        return { ok: false, reason: "directory_unreachable", guidance: "The home directory stream is not connected, so the counterparty's location could not be looked up. Check cello status (directory_signaling), then retry." };
+                    }
+                    // NO REPLY: an old directory (predates discovery) OR a slow/dropped reply on a new one. Retry;
+                    // fall back to today's local-only behavior ONLY as a last resort (after the retries), so a
+                    // single dropped reply no longer misroutes a reachable cross-node peer to the home node.
+                    if (disc.kind === "timeout") {
+                        logger.warn("session.discovery.no_reply", { agentName: ctx.agentName, attempt, correlationId: ctx.correlationId });
+                        if (attempt < MAX_ATTEMPTS) {
+                            await sleepMs(backoffs[attempt - 1]);
+                            continue;
+                        }
+                        logger.info("session.discovery.unsupported_fallback", { agentName: ctx.agentName, correlationId: ctx.correlationId });
+                        return await runSessionRequestOverSignaling(signaling, targetHex, sr, ctx.correlationId, ctx.agentName);
+                    }
+                    // DIRECTORY-SIDE lookup fault (DB error / malformed reply): RETRYABLE — but a DIRECTORY fault,
+                    // reported truthfully as directory_unreachable, NEVER as the counterparty being offline.
+                    if (disc.kind === "error" || disc.kind === "malformed") {
+                        logger.info("directory.discovery.lookup.retry", { agentName: ctx.agentName, attempt, kind: disc.kind, correlationId: ctx.correlationId });
+                        if (attempt < MAX_ATTEMPTS) {
+                            await sleepMs(backoffs[attempt - 1]);
+                            continue;
+                        }
+                        return { ok: false, reason: "directory_unreachable", guidance: "The directory could not resolve the counterparty's location (a directory-side lookup error) after several attempts. Retry shortly." };
+                    }
+                    // A 3-state RESULT. Route it (pure classifier).
+                    const action = classifyOnlineResult(disc.state, disc.owningNodeIds, homeNodeId);
+                    // State 3: no such agent — a bad address, not a transient outage. NO retry (distinct code).
+                    if (action.kind === "unknown_agent") {
+                        return { ok: false, reason: "unknown_agent", guidance: "No agent is registered under that public key — the counterparty address is unknown. Verify the pubkey with the counterparty's operator." };
+                    }
+                    // State 2: known but offline. Definitive — NO retry storm.
+                    if (action.kind === "offline") {
+                        return { ok: false, reason: "counterparty_offline", guidance: "The counterparty exists but is not currently online. Have its operator bring it online (cello_status), then retry." };
+                    }
+                    // Online but no owner named — transient, re-discover.
+                    if (action.kind === "retry") {
+                        logger.info("directory.discovery.lookup.retry", { agentName: ctx.agentName, attempt, kind: "online_no_owner", correlationId: ctx.correlationId });
+                        if (attempt < MAX_ATTEMPTS) {
+                            await sleepMs(backoffs[attempt - 1]);
+                            continue;
+                        }
+                        return { ok: false, reason: "counterparty_offline", guidance: "The directory reported the counterparty online but named no home node. Retry shortly." };
+                    }
+                    const result = action.kind === "same_node"
+                        // SAME-NODE: the target is on the node we're already connected to. The existing path runs
+                        // unchanged — ZERO visiting connections, ZERO new frames beyond the one discovery_lookup.
+                        ? await runSessionRequestOverSignaling(signaling, targetHex, sr, ctx.correlationId, ctx.agentName)
+                        // CROSS-NODE: reach into the target's home over a transient visiting connection.
+                        : await runCrossNodeSetup(ctx.agentName, kp, agentRec.pubkey, action.owningNodeId, targetHex, sr, ctx.correlationId);
+                    // RETRY triggers: (a) the broker reported target_offline (stale replicated presence or a
+                    // re-home between discovery and the request); (b) a transient visiting-connection failure
+                    // (cross-region blip). Both re-discover → retry, bounded.
+                    if (!result.ok && (result.reason === "target_offline" || result.reason === "visiting_connection_unreachable")) {
+                        logger.info("session.crossnode.stale_discovery_retry", { agentName: ctx.agentName, attempt, reason: result.reason, correlationId: ctx.correlationId });
+                        if (attempt < MAX_ATTEMPTS) {
+                            await sleepMs(backoffs[attempt - 1]);
+                            continue;
+                        }
+                        // Exhausted: keep the truthful transient-connection reason; a stale target_offline surfaces
+                        // as counterparty_offline (state 2).
+                        return result.reason === "visiting_connection_unreachable"
+                            ? { ok: false, reason: "visiting_connection_unreachable", guidance: "The counterparty's home node was reachable at discovery but its visiting connection could not be established after several attempts. Retry shortly." }
+                            : { ok: false, reason: "counterparty_offline", guidance: "The counterparty was online at discovery but not reachable at its home node after several attempts (it may be re-homing). Retry shortly." };
+                    }
+                    return result;
                 }
-                logger.info("session.negotiate.assignment.received", {
-                    agentName: ctx.agentName,
-                    correlationId: ctx.correlationId,
-                    signatureType: assignment.signature_type,
-                });
-                return { ok: true, assignment };
+                return { ok: false, reason: "counterparty_offline", guidance: "Session establishment did not succeed after several attempts. Retry shortly." };
             }
             finally {
-                unregister();
                 negotiationInProgress.delete(ctx.agentName);
             }
         },