@cello-protocol/daemon 0.0.9 → 0.0.11

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,EAKrB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAK/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAoB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAM/G,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAmInF,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,CAk5G7E"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAK/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAoB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAM/G,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAmInF,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,CAulH7E"}

package/dist/daemon.js

@@ -46,7 +46,7 @@ import { verify as ed25519Verify, sealToRecipient, generateKLocalSeed, InMemoryK
 import { attemptSealUpgrade as attemptSealUpgradeImpl, verifyUpgradeConfirmedCert } from "./seal-upgrade.js";
 // CELLO-M7-MSG-001 (AC-013/AC-018): the single application content-size cap, enforced
 // at the send point here (the receive point lives in the transport content decode).
-import { MAX_CONTENT_BYTES, computeGenesisPrevRoot } from "@cello-protocol/protocol-types";
+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";
@@ -348,7 +348,11 @@ export async function startDaemon(config) {
     // L4: sort by name so the "primary" agent is STABLE across restarts — readdir
     // order (agent-loader) is platform-dependent and unsorted, which would otherwise
     // let the authenticating identity change between daemon restarts.
-    const primaryAgent = [...loadedAgents].sort((a, b) => a.name.localeCompare(b.name))[0];
+    // CELLO-M7-ONBOARD-001: `primaryAgent` is mutable so the FIRST agent created at runtime
+    // (cello_create_agent on a fresh install) can be elected as the keystone identity — otherwise the
+    // directory door stays `reconnecting` forever until a restart. getAuthIdentity reads it on every
+    // reconnect attempt, so electing it makes the already-running reconnect loop authenticate + connect.
+    let primaryAgent = [...loadedAgents].sort((a, b) => a.name.localeCompare(b.name))[0];
     const getAuthIdentity = () => {
         if (!primaryAgent)
             return null;
@@ -518,36 +522,63 @@ export async function startDaemon(config) {
         await entry.signaling.stop();
         logger.info("agent.signaling.dropped", { agentName });
     }
-    // DOD-SPINE-5: the PRIMARY agent registers + initiates over the keystone signaling
-    // stream (not a per-agent one), so wire its ceremony_request handler on the keystone
-    // manager too — otherwise a primary-agent initiator's session ceremony would time out.
-    if (primaryAgent) {
-        wireSessionCeremonyHandler({
-            agentName: primaryAgent.name,
-            persistence: getPersistence(primaryAgent.name),
-            agentPubkeyHex: primaryAgent.pubkey,
+    // DOD-SPINE-5/7: the PRIMARY agent registers + initiates + coordinates the session/seal FROST
+    // ceremonies over the keystone signaling stream (not a per-agent one), so its ceremony/seal/offer
+    // handlers must be wired on the keystone manager — otherwise a primary-agent initiator's session
+    // ceremony would time out. CELLO-M7-ONBOARD-001: extracted into a function so it can also be wired
+    // when the first agent is elected at runtime (cello_create_agent), not only at startup.
+    // Returns a disposer that UNREGISTERS the six keystone listeners. Each wire*/register* helper returns
+    // its own unregister fn; the keystone manager is shared and never stopped, so (unlike the per-agent
+    // managers, which unregister implicitly on stop) these MUST be unregistered explicitly when the
+    // primary is cleared or re-elected — otherwise removing-then-recreating the primary STACKS a second
+    // full set of listeners on the shared stream, double-firing every ceremony/seal frame (review HIGH).
+    function wireKeystonePrimary(agent) {
+        const unregister = [];
+        unregister.push(wireSessionCeremonyHandler({
+            agentName: agent.name,
+            persistence: getPersistence(agent.name),
+            agentPubkeyHex: agent.pubkey,
             getNode: getDirectoryNode,
             getDirectoryEndpoint: async () => (directoryEndpointResolver ? (await directoryEndpointResolver()) ?? null : null),
             signaling: signalingManager,
             logger,
-        });
-        // DOD-SPINE-7: the primary agent also coordinates the SEAL FROST ceremony on the keystone.
-        wireSealCeremonyHandler({
-            agentName: primaryAgent.name,
-            persistence: getPersistence(primaryAgent.name),
-            agentPubkeyHex: primaryAgent.pubkey,
+        }));
+        unregister.push(wireSealCeremonyHandler({
+            agentName: agent.name,
+            persistence: getPersistence(agent.name),
+            agentPubkeyHex: agent.pubkey,
             getNode: getDirectoryNode,
             getDirectoryEndpoint: async () => (directoryEndpointResolver ? (await directoryEndpointResolver()) ?? null : null),
             signaling: signalingManager,
             logger,
-        });
-        wireSessionOfferHandler({
-            agentName: primaryAgent.name,
-            getStandingReceiverEndpoint: () => sessionNodeManager.getStandingReceiverInfo(primaryAgent.name),
+        }));
+        unregister.push(wireSessionOfferHandler({
+            agentName: agent.name,
+            getStandingReceiverEndpoint: () => sessionNodeManager.getStandingReceiverInfo(agent.name),
             signaling: signalingManager,
             logger,
-        });
+        }));
+        // The primary closes its OWN sessions over the keystone stream, so the directory routes its
+        // session_sealed / seal_unilateral_confirmed / seal_unilateral_notification frames there. These
+        // seal-completion listeners MUST be registered for the keystone primary (startup OR runtime
+        // election) — otherwise the close waiter never resolves and the seal silently never finalizes
+        // (review HIGH: previously these were a separate startup-only block, skipped on a fresh install).
+        // The register* functions are hoisted declarations within startDaemon, so callable here.
+        unregister.push(registerSessionSealedListener(signalingManager, agent.name, agent.pubkey));
+        unregister.push(registerUnilateralConfirmedListener(signalingManager, agent.name, agent.pubkey));
+        unregister.push(registerUnilateralUpgradeListener(signalingManager, agent.name, agent.pubkey));
+        return () => { for (const u of unregister) {
+            try {
+                u();
+            }
+            catch { /* unregister is best-effort */ }
+        } };
     }
+    // Disposer for the currently-wired keystone primary listeners (CELLO-M7-REMOVE-001): call it before
+    // clearing or re-electing the primary so the shared stream never carries a stale/duplicate set.
+    let keystoneDispose;
+    if (primaryAgent)
+        keystoneDispose = wireKeystonePrimary(primaryAgent);
     // Per-connection state: tracks which agent is "current" for each IPC connection.
     // Key = connectionId (assigned by IPC server), Value = current agent name or null.
     const perConnectionState = new Map();
@@ -935,21 +966,40 @@ export async function startDaemon(config) {
             return { ok: false, reason: "invalid_agent_name", guidance: "Provide a 'name' (1-64 chars: letters, digits, '-' or '_') for the new agent." };
         }
         const store = new DbIdentityStore(sessionNodeManager.getDb(), logger);
-        if (store.hasAgent(name) || agents.some((a) => a.name === name)) {
+        if (store.hasActiveAgent(name) || agents.some((a) => a.name === name)) {
             return { ok: false, reason: "agent_already_exists", guidance: `Agent '${name}' already exists. Choose a different name, or see cello_list_agents.` };
         }
         let pubkeyHex;
+        let agentId;
         try {
             const seed = generateKLocalSeed();
             const keyProvider = new InMemoryKeyProvider(seed);
             pubkeyHex = Buffer.from(await keyProvider.getPublicKey()).toString("hex");
-            // SI-001: createAgent stores the seed in the encrypted DB and logs only the pubkey.
-            store.createAgent(name, seed, pubkeyHex);
+            // SI-001: createAgent stores the seed in the encrypted DB and logs only the pubkey + agent_id.
+            agentId = store.createAgent(name, seed, pubkeyHex);
             // Runtime-add: make the agent immediately registrable/usable (the register handler resolves
             // identity from keyProviders/loadedAgents; per-agent signaling is created lazily on register).
             keyProviders.set(name, keyProvider);
-            loadedAgents.push({ name, pubkey: pubkeyHex, keyProvider });
+            const loaded = { name, pubkey: pubkeyHex, keyProvider };
+            loadedAgents.push(loaded);
             agents.push({ name, state: "registered", pubkey: pubkeyHex });
+            // CELLO-M7-ONBOARD-001: on a FRESH install the daemon started with no agents, so there was no
+            // keystone identity and the directory door is stuck `reconnecting`. Elect this first agent as the
+            // keystone primary + wire its ceremony/seal handlers; the running reconnect loop then
+            // authenticates with it (getAuthIdentity now returns it) and connects on its next attempt — no
+            // restart needed. Only the FIRST agent is elected (loadedAgents is empty here, so it is also the
+            // name-sort min). NOTE (accepted LOW, review): if the operator then creates a lexicographically
+            // SMALLER second agent before any restart, the keystone primary stays this one until the next
+            // restart, where it re-derives to sort[0] — benign (each agent authenticates its own stream; the
+            // demoted agent gets fully wired via the per-agent path on restart), and not worth runtime
+            // re-election (un-wire/re-wire) churn.
+            if (!primaryAgent) {
+                // Dispose any prior keystone wiring before re-electing, so listeners never stack (REMOVE-001).
+                keystoneDispose?.();
+                primaryAgent = loaded;
+                keystoneDispose = wireKeystonePrimary(loaded);
+                logger.info("directory.keystone.elected", { agentName: name, agentPubkey: pubkeyHex });
+            }
         }
         catch (err) {
             logger.error("persist.identity.persist.failed", { agentName: name, error: err instanceof Error ? err.message : String(err) });
@@ -957,8 +1007,173 @@ export async function startDaemon(config) {
         }
         // Creation is not an online/offline transition — the agent appears (cello_list_agents) but is
         // not online until cello_start_agent. Just record it.
-        logger.info("agent.created", { agentName: name, agentPubkey: pubkeyHex });
-        return { ok: true, name, pubkey: pubkeyHex };
+        logger.info("agent.created", { agentName: name, agentId, agentPubkey: pubkeyHex });
+        return { ok: true, name, pubkey: pubkeyHex, agentId };
+    });
+    // ─── CELLO-M7-REMOVE-001 (DOD-REMOVE-1): cello_remove_agent handler ───
+    // RETIRE-AND-KEEP: flip the agent's local row to state='retired' (its row, keys, and history are
+    // KEPT for accountability — never hard-deleted, SI-002) and FREE the human name for reuse. Purge the
+    // retired identity from the live runtime so it stops operating and the name is immediately available
+    // to a NEW `cello_create_agent`. One-way. (DEC-4: the signed DIRECTORY revocation is DOD-REMOVE-2 —
+    // not built here; this unit is the local record shape only.)
+    // CELLO-M7-REMOVE-001 (DOD-REMOVE-2): build + self-sign an agent revocation and submit it to the
+    // directory on the agent's K_local-authenticated signaling stream. Self-authorized — the directory
+    // verifies the signature against the agent's registered K_local before appending. Best-effort: returns
+    // { recorded:false, reason } if the directory is unreachable / rejects (DB-001 — the caller still
+    // applies the one-way local retire and surfaces a distinct status).
+    async function submitAgentRevocation(opts) {
+        const { agentName, signer, kLocalPubkeyHex, regAgentId } = opts;
+        const epochId = "";
+        const reason = "voluntary";
+        const revokedAt = Date.now();
+        const tbs = buildAgentRevocationTbs(regAgentId, kLocalPubkeyHex, epochId, reason, revokedAt);
+        const sigHex = Buffer.from(await signer.sign(tbs)).toString("hex");
+        // If the agent has no live signaling (e.g. a re-push of an already-retired agent), getAgentSignaling
+        // lazily creates a dedicated manager — drop it again afterwards so we don't leak a reconnect loop.
+        const hadSignaling = perAgentSignaling.has(agentName) || primaryAgent?.name === agentName;
+        const { signaling } = getAgentSignaling(agentName, signer, kLocalPubkeyHex);
+        const createdSignaling = !hadSignaling && primaryAgent?.name !== agentName;
+        try {
+            const connected = await waitForSignalingConnected(signaling, 10_000);
+            if (!connected)
+                return { recorded: false, reason: "directory_unreachable" };
+            let resolveFrame;
+            const pending = new Promise((r) => { resolveFrame = r; });
+            // Match the reply by agent_id so a revocation on the shared keystone is never cross-wired.
+            const unregister = signaling.registerInboundHandler((frame) => {
+                const t = frame["type"];
+                if ((t === "agent_revocation_ack" || t === "agent_revocation_error") && frame["agent_id"] === regAgentId)
+                    resolveFrame(frame);
+            });
+            try {
+                const sent = await signaling.sendRaw({ type: "revoke_agent", agent_id: regAgentId, epoch_id: epochId, reason, revoked_at: revokedAt, signature: sigHex });
+                if (!sent.ok)
+                    return { recorded: false, reason: sent.reason ?? "directory_unreachable" };
+                let timer;
+                const timeoutP = new Promise((r) => { timer = setTimeout(() => r({ type: "__timeout__" }), 15_000); });
+                const frame = await Promise.race([pending, timeoutP]);
+                clearTimeout(timer);
+                if (frame["type"] === "__timeout__")
+                    return { recorded: false, reason: "timeout" };
+                if (frame["type"] === "agent_revocation_error")
+                    return { recorded: false, reason: String(frame["reason"] ?? "rejected") };
+                logger.info("agent.revocation.submitted", { agentName, agentId: regAgentId });
+                return { recorded: true };
+            }
+            finally {
+                unregister();
+            }
+        }
+        finally {
+            if (createdSignaling) {
+                await dropAgentSignaling(agentName).catch((err) => {
+                    logger.warn("agent.revocation.signaling_teardown_failed", { agentName, error: err instanceof Error ? err.message : String(err) });
+                });
+            }
+        }
+    }
+    handlers.set("cello_remove_agent", async (params, _connectionId) => {
+        const name = params?.name;
+        if (!name || typeof name !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(name)) {
+            return { ok: false, reason: "invalid_agent_name", guidance: "Provide the 'name' of the agent to remove (1-64 chars: letters, digits, '-' or '_')." };
+        }
+        const store = new DbIdentityStore(sessionNodeManager.getDb(), logger);
+        // The active row (a fresh removal) OR the most-recent retired row (a DB-001 re-push). Captured BEFORE
+        // any retire — the active-only accessors filter retired rows out once state is flipped.
+        const target = store.getAgentForRevocation(name);
+        if (!target) {
+            return { ok: false, reason: "agent_not_found", guidance: `No agent named '${name}'. Check cello_list_agents.` };
+        }
+        const wasActive = target.state !== "retired";
+        const agentId = target.localAgentId;
+        // An already-retired agent that was never registered has nothing to do — no local retire (one-way,
+        // already done) and no directory revocation to push. Treat a repeat removal as agent_not_found (a
+        // tombstone is never re-retired). A retired agent WITH a directory id falls through to the DB-001
+        // re-push below.
+        if (!wasActive && !target.regAgentId) {
+            return { ok: false, reason: "agent_not_found", guidance: `No active agent named '${name}'. Removal is one-way; '${name}' is already retired.` };
+        }
+        // DOD-REMOVE-2: build + self-sign + submit the directory revocation. Done for a fresh removal AND a
+        // re-push of an already-retired agent (DB-001). Skipped only if the agent was never registered (no
+        // directory-known id to revoke). The signer is re-derived from the kept K_local seed, so it works
+        // even for an already-retired agent whose runtime keyProvider was purged.
+        let directoryRevocation = "skipped";
+        let revocationReason;
+        if (target.regAgentId) {
+            const signer = new InMemoryKeyProvider(target.kLocalSeed);
+            const kLocalPubkeyHex = Buffer.from(await signer.getPublicKey()).toString("hex");
+            const res = await submitAgentRevocation({ agentName: name, signer, kLocalPubkeyHex, regAgentId: target.regAgentId });
+            directoryRevocation = res.recorded ? "recorded" : "deferred";
+            revocationReason = res.reason;
+            if (!res.recorded) {
+                logger.error("agent.removal.failed", { agentName: name, error: res.reason ?? "directory_unreachable" });
+            }
+            else {
+                logger.info("agent.revocation.recorded", { agentId: target.regAgentId });
+            }
+        }
+        else if (target.state === "registered") {
+            // Anomaly (fallback-finder MEDIUM): the agent is locally marked registered but has no
+            // directory-known id, so the revocation cannot be pushed. Do NOT report the benign "never
+            // registered" — surface it loudly so a registered-but-unrevocable agent is visible.
+            revocationReason = "registered_without_directory_id";
+            logger.error("agent.removal.failed", { agentName: name, error: "registered_without_directory_id" });
+        }
+        // Local retire (one-way) + runtime purge — only for a fresh removal. An already-retired re-push does
+        // not re-retire (and has nothing loaded to purge).
+        if (wasActive) {
+            store.retireAgent(name);
+            // Tear down the retired identity's live runtime so it can no longer receive or re-authenticate.
+            // AWAITED + LOGGED on failure (review HIGH-1 / fallback-finder MEDIUM): a teardown that didn't
+            // happen must be visible.
+            if (onlineAgents.has(name)) {
+                onlineAgents.delete(name);
+                await sessionNodeManager.removeStandingReceiverForAgent(name).catch((err) => {
+                    logger.warn("agent.removal.receiver_teardown_failed", { agentName: name, agentId, error: err instanceof Error ? err.message : String(err) });
+                });
+            }
+            // Stop+forget the retired agent's dedicated per-agent signaling manager (review HIGH-1).
+            await dropAgentSignaling(name).catch((err) => {
+                logger.warn("agent.removal.signaling_teardown_failed", { agentName: name, agentId, error: err instanceof Error ? err.message : String(err) });
+            });
+            keyProviders.delete(name);
+            const li = loadedAgents.findIndex((a) => a.name === name);
+            if (li >= 0)
+                loadedAgents.splice(li, 1);
+            const ai = agents.findIndex((a) => a.name === name);
+            if (ai >= 0)
+                agents.splice(ai, 1);
+            // If the retired agent was the directory keystone, UNWIRE its keystone listeners + clear it
+            // (review HIGH-2: the listeners were never unregistered → double-wire on re-election).
+            if (primaryAgent && primaryAgent.name === name) {
+                keystoneDispose?.();
+                keystoneDispose = undefined;
+                primaryAgent = undefined;
+                logger.info("directory.keystone.cleared", { agentName: name, agentId });
+            }
+            // Drop the retired agent as any connection's current agent.
+            for (const [connId, state] of perConnectionState) {
+                if (state.currentAgent === name) {
+                    state.currentAgent = null;
+                    notificationDispatcher.setCurrentAgent(connId, null);
+                    notificationDispatcher.dispatchAgentCurrentChanged(connId, name, null);
+                }
+            }
+            // agent.removal.retired (observability): never log key material — only the name + agent_id.
+            logger.info("agent.removal.retired", { agentName: name, agentId });
+            notificationDispatcher.dispatchAgentStateChanged(name, "offline", "removed");
+        }
+        const baseLine = wasActive
+            ? "Agent retired. This is one-way: its identity and history are kept for accountability, but it can no longer connect. The name is now free to reuse with cello create-agent."
+            : "Agent was already retired locally.";
+        const dirLine = directoryRevocation === "recorded"
+            ? " A signed revocation was recorded at the directory — peers will see it as revoked."
+            : directoryRevocation === "deferred"
+                ? ` The directory could NOT be reached to record the revocation (${revocationReason ?? "directory_unreachable"}) — peers do not yet see it as revoked. Re-run 'cello remove-agent ${name}' when the directory is reachable to push it.`
+                : revocationReason === "registered_without_directory_id"
+                    ? " WARNING: this agent appears registered but has no directory id recorded locally, so its revocation could NOT be pushed — peers may still see it as reachable. Check the daemon logs (agent.removal.failed)."
+                    : " It was never registered with a directory, so there is no directory revocation to record.";
+        return { ok: true, name, agentId, oneWay: true, directoryRevocation, guidance: baseLine + dirLine };
     });
     // ─── MCP-001: cello_stop_agent handler ───
     handlers.set("cello_stop_agent", async (params, _connectionId) => {
@@ -2603,25 +2818,11 @@ export async function startDaemon(config) {
         handleInboundSessionAssignment(frame);
     });
     // M7 DOD-SPINE-7: session_sealed listener. The directory delivers this over the SESSION-OWNING
-    // agent's signaling stream after the relay-mediated bilateral seal notarizes. Registered on the
-    // keystone (primary agent) here AND per-agent in getAgentSignaling — for a non-primary agent the
-    // directory routes session_sealed to its per-agent stream, so a keystone-only listener would
-    // leave that agent's close waiter unresolved (reviewer finding). Resolve the close waiter with
-    // the sealed_root and mark the session sealed. Guarded on primaryAgent: the keystone listener now
-    // needs the primary agent's name/pubkey to verify the seal signature (legibility-TBS-binding), and
-    // with no agents there are no keystone sessions to seal anyway.
-    if (primaryAgent) {
-        registerSessionSealedListener(signalingManager, primaryAgent.name, primaryAgent.pubkey);
-        // SESSION-002: the keystone counterpart for the unilateral certificate listener — the
-        // primary agent closes over the keystone stream, so the directory routes its
-        // seal_unilateral_confirmed there (mirrors the session_sealed keystone listener above).
-        registerUnilateralConfirmedListener(signalingManager, primaryAgent.name, primaryAgent.pubkey);
-        // DOD-UP-1: the keystone counterpart for the absent-party upgrade listener. The directory
-        // PUSHES the queued seal_unilateral_notification during the keystone's auth/reconnect drain —
-        // BEFORE any cello_start_agent runs — so the handler MUST be registered here at startup, not only
-        // in startAgent, or B (the returning absent party) would miss its own ratification trigger.
-        registerUnilateralUpgradeListener(signalingManager, primaryAgent.name, primaryAgent.pubkey);
-    }
+    // CELLO-M7-ONBOARD-001: the keystone primary's seal-completion listeners (session_sealed /
+    // seal_unilateral_confirmed / seal_unilateral_notification) are now registered inside
+    // wireKeystonePrimary — at startup for a loaded primary AND at runtime when the first agent is
+    // elected (cello_create_agent on a fresh install). They must NOT be a separate startup-only block,
+    // or a fresh-install primary's seals would silently never finalize (review HIGH).
     // cello_await_session — the counterparty's blocking pull for the next inbound session.
     // Returns immediately if one is already queued for the current agent (FIFO), otherwise
     // blocks until one arrives or timeout_ms elapses. Response shape matches the established