@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/signaling-wiring.d.ts

@@ -0,0 +1,105 @@
+/**
+ * One directory signaling stream per agent, authenticated as that agent.
+ *
+ * The directory routes EVERY frame — `dkg_complete`, `register_success`, an inbound
+ * `session_assignment`, a seal — by the pubkey that authenticated the stream it arrived on. So each
+ * agent must hold its own; there is no shared connection borrowing one agent's identity. The single
+ * shared manager that appears below exists only for the in-process test path.
+ *
+ * ⚠️ NINETEEN DEPENDENCIES — seven over the order's bound, and the number is COUNTED, not typed:
+ * `signaling-wiring-deps.test.ts` asserts it against the interface, because the first two versions
+ * of this sentence said fourteen and eighteen and disagreed with each other.
+ *
+ * It is one constructor, not a missed seam. `getAgentSignaling` is the sole entry point that touches
+ * all nineteen, and it is not a lookup: for an unknown agent it CONSTRUCTS a manager and wires seven
+ * things onto it in one uninterruptible sequence — connect, session ceremony, seal ceremony, seal
+ * listeners, session offer, and the two inbound handlers. Any split leaves a manager observably
+ * half-wired between two calls, which is the failure the CONN-001 comments below spend forty lines
+ * describing. The four small returns look separable and are not: three of them read
+ * `perAgentSignaling`, which only `getAgentSignaling` fills, so extracting them means exporting the
+ * map instead.
+ *
+ * ⚠️ TWO VALUES ARE GETTERS, AND THE REASON IS **CORRECTNESS, NOT BLAST RADIUS**.
+ * `getWirePerAgentSessionInbound` and `getHandleTrustSignalPickup` come from `createInboundSessions`,
+ * built ~1,200 lines BELOW this wiring. They are `const`, so passing them by value does not go
+ * quiet — it throws `ReferenceError: Cannot access ... before initialization` and the daemon dies at
+ * boot with the right name in the message. **The silent shape is a `let x;` that is still
+ * `undefined`**, which is what unit 4 hit and why its defect survived 5,003 green tests. Do not read
+ * this comment as "late binding is always silent"; the detection rule is the DECLARATION, and `let`
+ * is the one that hides.
+ *
+ * ⚠️ ONE CONSUMER IS BUILT BEFORE THIS MODULE. `createSealFlows` takes `signalingFor` and `sendOver`,
+ * and it is constructed above this call, so those two arrive as lambdas that resolve here at call
+ * time. `dropAgentSignaling` is passed by value — its consumers are built ~1,900 lines below, so
+ * there is nothing to defer.
+ */
+import { SignalingManager } from "@cello-protocol/transport";
+import type { CelloNode, IDirectoryChallengeVerifier } from "@cello-protocol/transport";
+import type { SessionNodeManager } from "./session-node-manager.js";
+import type { LoadedAgent } from "./agent-loader.js";
+import type { DirectorySignalingState, Logger } from "./types.js";
+import { type DbRegistrationPersistence } from "./db-identity-store.js";
+import type { ConsortiumEndpoint } from "./directory-bootstrap.js";
+import type { DirectoryEndpoint } from "./signaling-connect.js";
+import type { SubmissionRetryQueue } from "./submission-retry.js";
+import type { SealFailureStore } from "./seal-failure-store.js";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import { type TrustSignalPickupHandler } from "./trust-signal-pickup-listener.js";
+/** One agent's directory stream and the libp2p node behind it. */
+export interface AgentSignaling {
+    signaling: SignalingManager;
+    getNode: () => CelloNode | null;
+}
+export interface SignalingWiringDeps {
+    logger: Logger;
+    sessionNodeManager: SessionNodeManager;
+    /** The LIVE registry — a manager is built for an agent created after boot without a restart. */
+    loadedAgents: ReadonlyArray<LoadedAgent>;
+    keyProviders: Map<string, KeyProvider>;
+    /** Present ONLY on the in-process test path; undefined in production, where every agent dials. */
+    sharedSignaling: SignalingManager | undefined;
+    noSharedDirectoryNode: () => CelloNode | null;
+    verifiedManifestVersion: number;
+    getPersistence: (agentName: string) => DbRegistrationPersistence;
+    onSignalingConnected: (agentName: string) => void | Promise<void>;
+    /** C2, late-bound; built in outbound-sessions. See trust-signal-sweep.ts. */
+    getSweepTrustSignals: () => ((n: string, k: KeyProvider, p: string) => Promise<unknown>) | undefined;
+    resolveConsortiumRoster: () => Promise<ConsortiumEndpoint[] | null>;
+    failoverEndpointResolver: (() => Promise<DirectoryEndpoint | null>) | undefined;
+    /** Wired onto each new manager so a seal that arrives on it is heard. */
+    registerSealListeners: (mgr: SignalingManager, agentName: string, agentPubkeyHex: string) => void;
+    getFailoverEndpoint: () => Promise<{
+        peerId: string;
+        multiaddr?: string;
+    } | null>;
+    sealFailures: SealFailureStore;
+    submissionRetries: SubmissionRetryQueue;
+    challengeVerifier: IDirectoryChallengeVerifier | undefined;
+    directoryEndpointResolver: (() => Promise<DirectoryEndpoint | null>) | undefined;
+    /**
+     * ⚠️ GETTERS, NOT VALUES, AND THE REASON IS THE DEFECT UNIT 4 SHIPPED. Both come from
+     * `createInboundSessions`, constructed roughly 1,200 lines BELOW this wiring, so at construction
+     * they do not exist. `getAgentSignaling` reads them only when it BUILDS a manager, which is always
+     * later, so resolving at call time is both correct and the only thing that works. Passed by value
+     * they would be `undefined` forever, and a non-primary agent would never receive an inbound session
+     * on its own stream — the exact failure the CONN-001 block below exists to prevent.
+     */
+    getWirePerAgentSessionInbound: () => (mgr: SignalingManager, agentName: string) => void;
+    /** Resolved at FRAME time: the handler is built after this wiring, so an eager read is undefined. */
+    getHandleTrustSignalPickup: () => TrustSignalPickupHandler;
+}
+export declare function createSignalingWiring(deps: SignalingWiringDeps): {
+    perAgentSignaling: Map<string, AgentSignaling>;
+    getAgentSignaling: (agentName: string, agentKeyProvider: import("@cello-protocol/crypto").KeyProvider, agentPubkeyHex: string) => AgentSignaling;
+    waitForSignalingConnected: (mgr: SignalingManager, timeoutMs: number) => Promise<boolean>;
+    dropAgentSignaling: (agentName: string) => Promise<void>;
+    signalingFor: (agentName: string) => SignalingManager | undefined;
+    sendOver: (agentName: string, frame: Record<string, unknown>) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    directorySignalingStatus: () => DirectorySignalingState;
+    stopAllSignaling: () => Promise<void>;
+    registerPickupListener: import("./trust-signal-pickup-listener.js").PickupListenerRegistrar;
+};
+//# sourceMappingURL=signaling-wiring.d.ts.map

package/dist/signaling-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signaling-wiring.d.ts","sourceRoot":"","sources":["../src/signaling-wiring.ts"],"names":[],"mappings":"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"}

package/dist/signaling-wiring.js

@@ -0,0 +1,393 @@
+/**
+ * One directory signaling stream per agent, authenticated as that agent.
+ *
+ * The directory routes EVERY frame — `dkg_complete`, `register_success`, an inbound
+ * `session_assignment`, a seal — by the pubkey that authenticated the stream it arrived on. So each
+ * agent must hold its own; there is no shared connection borrowing one agent's identity. The single
+ * shared manager that appears below exists only for the in-process test path.
+ *
+ * ⚠️ NINETEEN DEPENDENCIES — seven over the order's bound, and the number is COUNTED, not typed:
+ * `signaling-wiring-deps.test.ts` asserts it against the interface, because the first two versions
+ * of this sentence said fourteen and eighteen and disagreed with each other.
+ *
+ * It is one constructor, not a missed seam. `getAgentSignaling` is the sole entry point that touches
+ * all nineteen, and it is not a lookup: for an unknown agent it CONSTRUCTS a manager and wires seven
+ * things onto it in one uninterruptible sequence — connect, session ceremony, seal ceremony, seal
+ * listeners, session offer, and the two inbound handlers. Any split leaves a manager observably
+ * half-wired between two calls, which is the failure the CONN-001 comments below spend forty lines
+ * describing. The four small returns look separable and are not: three of them read
+ * `perAgentSignaling`, which only `getAgentSignaling` fills, so extracting them means exporting the
+ * map instead.
+ *
+ * ⚠️ TWO VALUES ARE GETTERS, AND THE REASON IS **CORRECTNESS, NOT BLAST RADIUS**.
+ * `getWirePerAgentSessionInbound` and `getHandleTrustSignalPickup` come from `createInboundSessions`,
+ * built ~1,200 lines BELOW this wiring. They are `const`, so passing them by value does not go
+ * quiet — it throws `ReferenceError: Cannot access ... before initialization` and the daemon dies at
+ * boot with the right name in the message. **The silent shape is a `let x;` that is still
+ * `undefined`**, which is what unit 4 hit and why its defect survived 5,003 green tests. Do not read
+ * this comment as "late binding is always silent"; the detection rule is the DECLARATION, and `let`
+ * is the one that hides.
+ *
+ * ⚠️ ONE CONSUMER IS BUILT BEFORE THIS MODULE. `createSealFlows` takes `signalingFor` and `sendOver`,
+ * and it is constructed above this call, so those two arrive as lambdas that resolve here at call
+ * time. `dropAgentSignaling` is passed by value — its consumers are built ~1,900 lines below, so
+ * there is nothing to defer.
+ */
+import { SignalingManager } from "@cello-protocol/transport";
+import { channelAgentLookup } from "./db-identity-store.js";
+import { createPickupListenerRegistrar } from "./trust-signal-pickup-listener.js";
+import { extractErrorMessage } from "./error-message.js";
+import { createSignalingConnect } from "./signaling-connect.js";
+import { wireSessionCeremonyHandler, wireSessionOfferHandler, wireSealCeremonyHandler } from "./session-ceremony.js";
+import { relayOnlyState } from "./relay-only.js";
+export function createSignalingWiring(deps) {
+    const { logger, sessionNodeManager, loadedAgents, keyProviders, sharedSignaling, noSharedDirectoryNode, verifiedManifestVersion, getPersistence, onSignalingConnected, resolveConsortiumRoster, failoverEndpointResolver, getFailoverEndpoint, sealFailures, submissionRetries, challengeVerifier, directoryEndpointResolver, registerSealListeners, getWirePerAgentSessionInbound, getHandleTrustSignalPickup, getSweepTrustSignals, } = deps;
+    const registerPickupListener = createPickupListenerRegistrar(getHandleTrustSignalPickup);
+    // ─── Per-agent directory signaling (CONN-001: one signaling stream per agent) ──
+    // CELLO-M7-CONN-001 (DOD-CONN-1): the directory routes EVERY signaling frame —
+    // dkg_complete, register_success, inbound session_assignment, seal — by the pubkey that
+    // AUTHENTICATED the stream it arrived on. So each agent MUST get its OWN directory stream,
+    // authenticated as itself. There is no shared "keystone" connection borrowing one agent's
+    // identity. In production every agent has its own manager (built below); the only shared
+    // manager is the in-process test path's `sharedSignaling`. Managers are created lazily (on
+    // first registration / online / create) and kept connected for the agent's directory presence.
+    const perAgentSignaling = new Map();
+    /**
+     * Return the directory signaling stream for `agentName`, authenticated as that agent.
+     * Production: a dedicated per-agent manager (created + cached on first use). Test /
+     * backward-compat path (no directoryEndpointResolver): the single shared manager.
+     *
+     * CONN-001 (DOD-CONN-2): the per-agent manager wires BOTH registration AND inbound session
+     * handlers (session_assignment / seal_interrupted_request) via wirePerAgentSessionInbound,
+     * so a non-primary agent RECEIVES inbound sessions on its own stream. Attaching them to the
+     * primary (keystone) only would leave every other agent unable to receive.
+     */
+    function getAgentSignaling(agentName, agentKeyProvider, agentPubkeyHex) {
+        // CONN-001: test / backward-compat path — a single shared manager (no per-agent isolation;
+        // a single injected signalingConnect). In production sharedSignaling is undefined and every
+        // agent builds its own dedicated manager below.
+        if (sharedSignaling) {
+            return { signaling: sharedSignaling, getNode: noSharedDirectoryNode };
+        }
+        const existing = perAgentSignaling.get(agentName);
+        if (existing)
+            return existing;
+        // Unreachable in practice: sharedSignaling is defined iff directoryEndpointResolver is absent, and
+        // the sharedSignaling branch above already returned. This narrows the resolver for the type-checker
+        // and is a defensive guard.
+        if (!directoryEndpointResolver) {
+            throw new Error("getAgentSignaling: no directory endpoint resolver configured (and no shared manager)");
+        }
+        // FINDING-4: dial through the roster-aware failover resolver so this agent's signaling
+        // stream routes around a down primary node. (failoverEndpointResolver is defined here
+        // because it is built iff directoryEndpointResolver is — guarded non-null just above.)
+        const resolver = failoverEndpointResolver ?? directoryEndpointResolver;
+        let nodeRef = null;
+        const connect = createSignalingConnect({
+            getDirectoryEndpoint: resolver,
+            getAuthIdentity: () => ({ keyProvider: agentKeyProvider, pubkeyHex: agentPubkeyHex }),
+            logger,
+            challengeVerifier,
+            getManifestVersion: () => verifiedManifestVersion,
+            publishNode: (n) => {
+                nodeRef = n;
+            },
+            // DOD-NAT-REACHABILITY-1 (Phase 2): the directory's relay pool arrives with signaling_auth_ok.
+            // 056-SLOTDEAD — this used to say the receiver "reserves with those relays (and rebuilds if it
+            // came up deaf)". It does neither since 055-ONDEMAND: the pool is a CANDIDATE LIST, and a slot
+            // is taken at offer time. Nothing is reserved on receipt of it.
+            onRelayEndpoints: (endpoints) => {
+                sessionNodeManager.setDirectoryRelayEndpoints(agentName, endpoints.map((e) => ({ relayPeerId: e.peerId, relayAddrs: e.addrs })));
+            },
+            // DOD-M15-RELAYSLOTS-1: and the credential those relays require. Same frame, same cadence as
+            // the endpoints above — every connect and every reconnect, which is what keeps a token that
+            // expires within the hour current for a receiver that lives much longer than that.
+            onOnlineToken: (token) => {
+                sessionNodeManager.setDirectoryOnlineToken(agentName, token);
+            },
+            // Review M1: and when there is none, WHY — so the operator surface can say "this directory
+            // does not know this agent" instead of "check your directory connection" about a connection
+            // that just succeeded.
+            onOnlineTokenAbsent: (reason) => {
+                sessionNodeManager.setDirectoryOnlineTokenAbsent(agentName, reason);
+            },
+        });
+        const mgr = new SignalingManager({
+            connect,
+            logger,
+            maxReconnectAttempts: Number.MAX_SAFE_INTEGER,
+            maxBackoffMs: 30_000,
+            // Two things happen when this agent's directory signaling reaches 'connected' (the first
+            // connect AND every reconnect after a drop), and the ORDER is the contract — see
+            // reconnect-drain.ts.
+            //
+            // RE-REGISTER THE STANDING RECEIVER (2026-07-31 incident). The receiver's LIFETIME is tied to
+            // this daemon; its REGISTRATION is tied to this stream, and the stream turns over roughly
+            // every 70 seconds. ensureStandingReceiverForAgent ran only at agent start, so 46 of 48
+            // reconnects in one hour left every agent unregistered — the directory then answers
+            // `targetStreamFound: false` and a session request fails with `target_offline`, while
+            // `cello status`, `agent.online` and the directory's own agent_presence all still report the
+            // agent healthy. Only a daemon restart recovered it.
+            //
+            // THEN DRAIN (M8C-RELAYWAKE-1, "check relay on wakeup"): re-pull this agent's parked mailbox
+            // from every relay it has session history with, so a message parked while signaling was down
+            // is not left until the next agent start. The drain needs the node the ensure builds.
+            //
+            // AND THIRD, DOD-M15-ENDORSE-RETRY-1: re-send any sealed submission that reached no node.
+            // After `createReconnectDrain`: the drain needs the receiver the ensure rebuilds; this does not.
+            onConnected: () => {
+                onSignalingConnected(agentName);
+                submissionRetries.onSignalingConnected(agentName);
+                // C2: background, never awaited; the catch LOGS — silence is what hid this bug for weeks.
+                void getSweepTrustSignals()?.(agentName, agentKeyProvider, agentPubkeyHex)?.catch((e) => logger.warn("trust_signal.sweep.failed", { agentName, reason: extractErrorMessage(e) }));
+            },
+        });
+        const entry = { signaling: mgr, getNode: () => nodeRef };
+        perAgentSignaling.set(agentName, entry);
+        logger.info("agent.signaling.created", { agentName, agentPubkey: agentPubkeyHex });
+        // DOD-SPINE-5: answer the directory's delegated-signing `ceremony_request` on THIS
+        // agent's stream (the session FROST ceremony — the per-agent counterpart to SPINE-4's
+        // registration routing). Unregistered implicitly when the manager is stopped.
+        wireSessionCeremonyHandler({
+            agentName,
+            persistence: getPersistence(agentName),
+            agentPubkeyHex,
+            // DOD-M15-SEALWIRE-1 bullet 2 (review F1): the co-sign path must check the root before this
+            // agent's key endorses it. Same predicate as the receiving path — one implementation, so the
+            // two halves cannot drift about what a mismatch is.
+            verifyCertifiedRoot: (pub, sid, root, leaves, evidence) => sessionNodeManager.verifyCertifiedRoot(pub, sid, root, leaves, evidence),
+            keyProvider: agentKeyProvider,
+            getNode: entry.getNode,
+            getDirectoryEndpoint: getFailoverEndpoint,
+            getConsortiumEndpoints: resolveConsortiumRoster,
+            signaling: mgr,
+            logger,
+            // DOD-M15-SEALPARTIES-1: where a dead seal ceremony leaves its mark, so `cello_sealed_receipt`
+            // can say it FAILED and why instead of falling through to "no receipt yet".
+            recordSealFailure: (name, sid, reason, kind) => sealFailures.record(name, sid, reason, new Date().toISOString(), kind),
+        });
+        // DOD-SPINE-7: coordinate the SEAL FROST ceremony on this agent's stream too.
+        wireSealCeremonyHandler({
+            agentName,
+            persistence: getPersistence(agentName),
+            agentPubkeyHex,
+            // DOD-M15-SEALWIRE-1 bullet 2 (review F1): the co-sign path must check the root before this
+            // agent's key endorses it. Same predicate as the receiving path — one implementation, so the
+            // two halves cannot drift about what a mismatch is.
+            verifyCertifiedRoot: (pub, sid, root, leaves, evidence) => sessionNodeManager.verifyCertifiedRoot(pub, sid, root, leaves, evidence),
+            keyProvider: agentKeyProvider,
+            getNode: entry.getNode,
+            getDirectoryEndpoint: getFailoverEndpoint,
+            getConsortiumEndpoints: resolveConsortiumRoster,
+            signaling: mgr,
+            logger,
+            // DOD-M15-SEALPARTIES-1: where a dead seal ceremony leaves its mark, so `cello_sealed_receipt`
+            // can say it FAILED and why instead of falling through to "no receipt yet".
+            recordSealFailure: (name, sid, reason, kind) => sealFailures.record(name, sid, reason, new Date().toISOString(), kind),
+        });
+        // DOD-SPINE-7: and resolve session_sealed for this agent's sessions on its own stream.
+        registerSealListeners(mgr, agentName, agentPubkeyHex);
+        // WIRE-002: answer the directory's session_offer on this agent's stream (advertise the
+        // standing-receiver session endpoint so the assignment carries a reachable counterparty).
+        wireSessionOfferHandler({
+            agentName,
+            getStandingReceiverEndpoint: () => sessionNodeManager.getStandingReceiverInfo(agentName),
+            admitOfferedDialer: (peerId, sessionIdHex) => sessionNodeManager.admitOfferedDialer(agentName, peerId, sessionIdHex),
+            // RELAYONLY-1: tells "relay-only emptied the addresses" from "none yet" — opposite answers. M16: a channel rejects first.
+            reserveOnDemand: (c, sid) => sessionNodeManager.takeReservationForSession(agentName, c, sid, sid), isChannelAgent: () => channelAgentLookup(sessionNodeManager, logger)(agentName),
+            isRelayOnly: () => relayOnlyState((key) => sessionNodeManager.getSetting(agentName, key), sessionNodeManager.hasDatabase()) !== "off",
+            signaling: mgr,
+            logger,
+        });
+        // CELLO-M8-TRUST-001: sealed trust signals pushed from the directory pickup queue. Open with
+        // k_local, verify the hash against the anchor, store, ACK. Shared registrar (C) so the visiting
+        // stream gets the identical listener.
+        registerPickupListener(mgr, agentName, agentKeyProvider, "home");
+        /**
+         * DOD-M15-SEALPARTIES-1 Part 0: take the relay credential off `register_success`.
+         *
+         * `onOnlineToken` above catches every signaling auth and reconnect, and misses the one case that
+         * matters most: a brand-new agent. Its daemon opens this very stream in order TO register (the
+         * DKG runs over it), so the auth that created the stream happened while the directory still had
+         * no profile for the key and correctly issued nothing. A healthy stream never re-authenticates,
+         * so without this the agent holds no relay credential for the life of the daemon — no circuit
+         * reservation, unwitnessed leaves, and a close that fails with `seal_persist_failed`.
+         *
+         * A frame with no token is left alone rather than clearing what is held: the directory that
+         * issues here is the same one whose auth_ok issues, so overwriting a good token with an absence
+         * would turn one directory's minting failure into a reachability outage the operator cannot
+         * explain. The absence is already reported by the directory's own `online_token.failed`.
+         */
+        mgr.registerInboundHandler((frame) => {
+            if (frame["type"] !== "register_success")
+                return;
+            const raw = frame["online_token"];
+            const token = raw instanceof Uint8Array ? raw : Buffer.isBuffer(raw) ? new Uint8Array(raw) : undefined;
+            if (token && token.length > 0) {
+                sessionNodeManager.setDirectoryOnlineToken(agentName, token);
+                logger.info("directory.online_token.received", { agentName, source: "register_success", bytes: token.length });
+                return;
+            }
+            logger.warn("directory.online_token.absent", {
+                agentName,
+                source: "register_success",
+                impact: "this agent just registered and was handed no relay online token, so no relay will " +
+                    "let it hold a circuit reservation until its directory signaling stream reconnects and " +
+                    "re-issues one. Until then it is reachable only over a direct connection, and a session " +
+                    "it does hold cannot get its leaves witnessed.",
+            });
+        });
+        // CELLO-M7-CONN-001 (DOD-CONN-2): inbound session_assignment + seal_interrupted_request
+        // on THIS agent's own stream, so a non-primary agent receives inbound sessions (SPINE-5).
+        getWirePerAgentSessionInbound()(mgr, agentName);
+        return entry;
+    }
+    /** Resolve once `mgr` reaches "connected", or false on timeout. */
+    async function waitForSignalingConnected(mgr, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (mgr.status !== "connected" && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        return mgr.status === "connected";
+    }
+    /**
+     * Stop and forget a dedicated per-agent signaling manager. Called when an agent's
+     * registration fails terminally — otherwise the lazily-created manager (and its
+     * libp2p node + effectively-unbounded reconnect loop) would keep reconnecting forever
+     * for an agent that is not registered/online. No-op on the test path (the shared manager is not
+     * stored in perAgentSignaling) and for agents with no dedicated manager. On a later retry,
+     * getAgentSignaling re-creates it.
+     */
+    async function dropAgentSignaling(agentName) {
+        const entry = perAgentSignaling.get(agentName);
+        if (!entry)
+            return;
+        perAgentSignaling.delete(agentName);
+        await entry.signaling.stop();
+        logger.info("agent.signaling.dropped", { agentName });
+    }
+    // CONN-001: wire a manager's session/seal/offer handlers for `agent`. Used ONLY for the
+    // in-process test path's shared manager — production wires these PER-AGENT in getAgentSignaling.
+    function wireSharedHandlers(agent, mgr) {
+        wireSessionCeremonyHandler({
+            agentName: agent.name,
+            persistence: getPersistence(agent.name),
+            agentPubkeyHex: agent.pubkey,
+            // DOD-M15-SEALWIRE-1 bullet 2 (review F1): gate the co-signature on the root check.
+            verifyCertifiedRoot: (pub, sid, root, leaves, evidence) => sessionNodeManager.verifyCertifiedRoot(pub, sid, root, leaves, evidence),
+            keyProvider: agent.keyProvider,
+            getNode: noSharedDirectoryNode,
+            getDirectoryEndpoint: getFailoverEndpoint,
+            getConsortiumEndpoints: resolveConsortiumRoster,
+            signaling: mgr,
+            logger,
+            // DOD-M15-SEALPARTIES-1: where a dead seal ceremony leaves its mark, so `cello_sealed_receipt`
+            // can say it FAILED and why instead of falling through to "no receipt yet".
+            recordSealFailure: (name, sid, reason, kind) => sealFailures.record(name, sid, reason, new Date().toISOString(), kind),
+        });
+        wireSealCeremonyHandler({
+            agentName: agent.name,
+            persistence: getPersistence(agent.name),
+            agentPubkeyHex: agent.pubkey,
+            // DOD-M15-SEALWIRE-1 bullet 2 (review F1): gate the co-signature on the root check.
+            verifyCertifiedRoot: (pub, sid, root, leaves, evidence) => sessionNodeManager.verifyCertifiedRoot(pub, sid, root, leaves, evidence),
+            keyProvider: agent.keyProvider,
+            getNode: noSharedDirectoryNode,
+            getDirectoryEndpoint: getFailoverEndpoint,
+            getConsortiumEndpoints: resolveConsortiumRoster,
+            signaling: mgr,
+            logger,
+            // DOD-M15-SEALPARTIES-1: where a dead seal ceremony leaves its mark, so `cello_sealed_receipt`
+            // can say it FAILED and why instead of falling through to "no receipt yet".
+            recordSealFailure: (name, sid, reason, kind) => sealFailures.record(name, sid, reason, new Date().toISOString(), kind),
+        });
+        wireSessionOfferHandler({
+            agentName: agent.name,
+            getStandingReceiverEndpoint: () => sessionNodeManager.getStandingReceiverInfo(agent.name),
+            admitOfferedDialer: (peerId, sessionIdHex) => sessionNodeManager.admitOfferedDialer(agent.name, peerId, sessionIdHex),
+            reserveOnDemand: (c, sid) => sessionNodeManager.takeReservationForSession(agent.name, c, sid, sid), isChannelAgent: () => channelAgentLookup(sessionNodeManager, logger)(agent.name), // 055-ONDEMAND + M16: both sites
+            isRelayOnly: () => relayOnlyState((key) => sessionNodeManager.getSetting(agent.name, key), sessionNodeManager.hasDatabase()) !== "off",
+            signaling: mgr,
+            logger,
+        });
+        registerSealListeners(mgr, agent.name, agent.pubkey);
+    }
+    // CONN-001: the directory signaling manager that OWNS operations for `agentName`. In production
+    // that is the agent's OWN per-agent manager (authenticated as itself); on the in-process test
+    // path it is the single shared manager (agentName ignored). Returns undefined only when the agent
+    // is not loaded in production (e.g. removed mid-flow) — callers treat that as a send failure.
+    function signalingFor(agentName) {
+        if (sharedSignaling)
+            return sharedSignaling;
+        const kp = keyProviders.get(agentName);
+        const agent = loadedAgents.find((a) => a.name === agentName);
+        if (!kp || !agent)
+            return undefined;
+        return getAgentSignaling(agentName, kp, agent.pubkey).signaling;
+    }
+    // CONN-001: send a frame over the OWNING agent's directory manager (per-agent in production, the
+    // shared manager in tests). If the agent has no manager (e.g. removed mid-flow), return a send
+    // failure rather than throw — callers already branch on `!result.ok`.
+    async function sendOver(agentName, frame) {
+        const mgr = signalingFor(agentName);
+        if (!mgr)
+            return { ok: false, reason: "directory_unreachable" };
+        return mgr.sendRaw(frame);
+    }
+    // CONN-001: aggregate directory signaling status for `cello status`. Test path → the shared
+    // manager's status. Production → connected if ANY online agent's connection is connected; else
+    // reconnecting if any per-agent connection exists; else disconnected (no agents online → no
+    // connections, which is correct — there is no shared connection to be "reconnecting").
+    function directorySignalingStatus() {
+        if (sharedSignaling)
+            return sharedSignaling.status;
+        const managers = [...perAgentSignaling.values()];
+        // CONN-001 (fallback-finder MED): a single daemon-level field cannot fully represent N independent
+        // per-agent connections, but it must NOT show "connected" while any agent is severed (that would
+        // mask a partial directory outage — the severed agent silently never receives inbound). So report
+        // "connected" ONLY when every per-agent manager is connected; otherwise "reconnecting" (degraded or
+        // none). No managers (no agent online) → "reconnecting", matching pre-CONN-001 fresh-install
+        // behavior. (Per-agent connection state is the future faithful surface.)
+        if (managers.length === 0)
+            return "reconnecting";
+        return managers.every((m) => m.signaling.status === "connected") ? "connected" : "reconnecting";
+    }
+    // CONN-001: stop every directory signaling connection on shutdown — the shared test manager AND
+    // every per-agent manager — so no reconnect loop is orphaned past shutdown.
+    async function stopAllSignaling() {
+        if (sharedSignaling) {
+            try {
+                await sharedSignaling.stop();
+            }
+            catch { /* best-effort */ }
+        }
+        for (const entry of perAgentSignaling.values()) {
+            try {
+                await entry.signaling.stop();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    // CONN-001: test path only — wire the shared manager's session/seal handlers for the first loaded
+    // agent. Production wires them per-agent (getAgentSignaling). There is NO keystone identity to
+    // elect and no re-election machinery: the shared test manager is never removed, and in production
+    // a fresh create-agent brings up that agent's OWN connection (no shared door to elect into).
+    if (sharedSignaling && loadedAgents.length > 0) {
+        const first = [...loadedAgents].sort((a, b) => a.name.localeCompare(b.name))[0];
+        wireSharedHandlers(first, sharedSignaling);
+    }
+    return {
+        perAgentSignaling,
+        getAgentSignaling,
+        waitForSignalingConnected,
+        dropAgentSignaling,
+        signalingFor,
+        sendOver,
+        directorySignalingStatus,
+        stopAllSignaling,
+        // 043-SIGNALDELIVERY C: handed out so the VISITING connection registers the identical listener.
+        // It had none, so a visited node's pickups were pushed and dropped on every visit.
+        registerPickupListener,
+    };
+}
+//# sourceMappingURL=signaling-wiring.js.map

package/dist/signaling-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signaling-wiring.js","sourceRoot":"","sources":["../src/signaling-wiring.ts"],"names":[],"mappings":"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"}

package/dist/singleton-lock.d.ts

@@ -0,0 +1,85 @@
+/**
+ * DOD-SINGLE-DAEMON-1 — the daemon singleton, enforced by the kernel.
+ *
+ * `daemon.lock` is a JSON file, and a file cannot answer "is a daemon running?". Anyone may delete
+ * it; a `kill -9` leaves it behind naming a pid that is dead — or, worse, one the OS has since REUSED
+ * for an unrelated process, which makes `isProcessAlive()` say "yes" forever. Every stale-lock
+ * heuristic ever written is an attempt to guess what only the kernel actually knows.
+ *
+ * So we ask the kernel. The daemon takes a real POSIX write lock (`fcntl`) on a dedicated file and
+ * holds it for its entire lifetime. Two processes cannot hold it at once, and the kernel drops it the
+ * instant the holder dies — SIGKILL, panic, `kill -9`, however it goes. There is no stale state to
+ * clean up and no recovery step to get wrong.
+ *
+ * ## Why SQLite is the lock
+ *
+ * Node has no `flock`. `fs.constants.O_EXLOCK` exists only on macOS/BSD — using it would leave every
+ * Linux operator (including the EC2 demo agent) with NO lock at all, which is worse than none because
+ * it looks like one. A native `flock` addon (`fs-ext`) compiles from source, and install time is a
+ * cost every operator pays on every version bump (see CLAUDE.md — the client is a heavy local node,
+ * not a thin wrapper).
+ *
+ * `@signalapp/sqlcipher` is already a daemon dependency, ships prebuilt (no compile), and SQLite's
+ * whole business is taking correct `fcntl` locks on every POSIX platform. `locking_mode = exclusive`
+ * plus one header write acquires the exclusive lock and holds it until the connection closes. A
+ * second process gets SQLITE_BUSY immediately (`busy_timeout = 0`). SQLite also tracks locks per
+ * inode inside the process, so this correctly refuses a second daemon in the SAME process too —
+ * which raw `fcntl`, whose locks are per-process, would not.
+ *
+ * The lock database holds no rows and never will. It is a mutex that happens to be spelled in SQL.
+ *
+ * ## The division of labour with daemon.lock (AC4)
+ *
+ * The OS lock DECIDES whether a daemon may start. `daemon.lock` only SUPPLIES METADATA — it is how we
+ * learn the holder's pid to name in the error, because `fcntl` will not tell us. If the JSON is
+ * missing, stale, or lying, the worst outcome is a less specific error message. It can never admit a
+ * second daemon, and it can never wedge a legitimate one out.
+ *
+ * ## The one constraint
+ *
+ * `~/.cello` must live on a LOCAL filesystem. POSIX `fcntl` locks are advisory-but-honoured on local
+ * filesystems (APFS, ext4, xfs — macOS and the Linux hosts we run on); on NFSv3 without a working
+ * `lockd`, and on some 9p/WSL2 setups, they can silently degrade to no-ops. There, two daemons would
+ * both "acquire" and the singleton would be absent while appearing present. We do not attempt to
+ * detect this — a real self-test needs a second process, which is far too much to do at every startup.
+ * The lock path is logged in `daemon.singleton.acquired` so an operator debugging a two-daemon
+ * situation can see exactly which file the kernel was asked about.
+ */
+import type { Logger } from "./types.js";
+/** The file the kernel lock is taken on. Holds no data — see the note above. */
+export declare const SINGLETON_LOCK_FILENAME = "daemon.singleton";
+export declare class DaemonAlreadyRunningError extends Error {
+    /** The pid from `daemon.lock`, or null when that file is absent/unreadable/malformed. */
+    readonly holderPid: number | null;
+    constructor(holderPid: number | null);
+}
+export interface SingletonLock {
+    /** Release the lock. The kernel would do this on process exit anyway; this is for in-process use. */
+    release(): void;
+}
+/** The daemon binary's exit code when it loses the singleton race — distinct from 1 = "broken". */
+export declare const EXIT_ALREADY_RUNNING = 3;
+export declare function acquireSingletonLock(celloDir: string, logger: Logger, busyTimeoutMs?: number): SingletonLock;
+/**
+ * Is a daemon holding the lock for `celloDir` right now?
+ *
+ *   "held"    — a daemon is alive. Connect to it; never spawn beside it.
+ *   "free"    — no daemon is running, whatever `daemon.lock` claims. Spawning is correct.
+ *   "unknown" — we could not ask the kernel (native module missing, directory unreadable).
+ *
+ * The third answer is the point. "I could not determine whether a daemon is running" and "no daemon is
+ * running" are different facts, and collapsing them into one boolean means the caller spawns on both —
+ * so the one case where we are blind becomes the one case we start a second daemon. Callers must
+ * refuse to spawn on "unknown" and surface the underlying error instead.
+ *
+ * Asking the kernel rather than trusting `daemon.lock` is also what makes a REUSED pid harmless: a
+ * stale lock file naming a live-but-unrelated process would otherwise wedge `cello login` forever.
+ *
+ * The probe takes the lock and immediately drops it. The gap between the probe and a subsequent spawn
+ * is safe: the daemon we spawn acquires the lock authoritatively and exits EXIT_ALREADY_RUNNING if it
+ * loses that race — and the caller reads that exit code as "someone else won, connect to them", never
+ * as a failure. Two probes can therefore both say "free" and both spawn, and exactly one daemon
+ * survives.
+ */
+export declare function probeSingletonLock(celloDir: string, logger: Logger): "held" | "free" | "unknown";
+//# sourceMappingURL=singleton-lock.d.ts.map

package/dist/singleton-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton-lock.d.ts","sourceRoot":"","sources":["../src/singleton-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEtB,SAAS,EAAE,MAAM,GAAG,IAAI;CASrC;AAED,MAAM,WAAW,aAAa;IAC5B,qGAAqG;IACrG,OAAO,IAAI,IAAI,CAAC;CACjB;AA0DD,mGAAmG;AACnG,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAgBtC,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,aAAa,GAAE,MAAuC,GACrD,aAAa,CAyCf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAqBhG"}