@cello-protocol/daemon 0.0.8 → 0.0.10

package/dist/daemon.js

@@ -40,8 +40,9 @@ import { createNode, SignalingManager } from "@cello-protocol/transport";
 import { createSignalingConnect } from "./signaling-connect.js";
 import { RegistrationManager } from "./registration-manager.js";
 import { DaemonRegistrationContext } from "./registration-context.js";
-import { FileRegistrationPersistence } from "./registration-persistence.js";
-import { verify as ed25519Verify, sealToRecipient } from "@cello-protocol/crypto";
+import { DbRegistrationPersistence, DbIdentityStore } from "./db-identity-store.js";
+import { DbManifestVersionStore } from "./manifest-version-store-db.js";
+import { verify as ed25519Verify, sealToRecipient, generateKLocalSeed, InMemoryKeyProvider } from "@cello-protocol/crypto";
 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).
@@ -169,7 +170,7 @@ class ProductionSessionNodeFactory {
     }
 }
 export async function startDaemon(config) {
-    const { celloDir, socketPath, lockFilePath, maxConnections, version, logger, manifestProvider, manifestRootKeys, manifestThreshold, manifestVersionStore, manifestPollScheduler, signalingConnect, challengeVerifier, directoryEndpointResolver, sessionNodeFactory, sessionNegotiator, getRelayCircuitAddress, } = config;
+    const { celloDir, socketPath, lockFilePath, maxConnections, version, logger, manifestProvider, manifestRootKeys, manifestThreshold, manifestVersionStore: injectedManifestVersionStore, manifestPollScheduler, signalingConnect, challengeVerifier, directoryEndpointResolver, sessionNodeFactory, sessionNegotiator, getRelayCircuitAddress, } = config;
     // CELLO-M7-TRANSPORT-001: composition-root selection of the transport selector.
     // Driven by CELLO_ENV; fails fast at startup (here, not at first session) when a
     // production environment is missing the required transport dialer (AC-010).
@@ -183,6 +184,31 @@ export async function startDaemon(config) {
         env: celloEnv,
         selector: isProductionVariant(celloEnv) ? "real" : "stub",
     });
+    // ADV-006 + ADV-008 (hoisted — code-review MED): pure config validation runs BEFORE any disk side
+    // effect (lock, the irreversible one-time migration, DB open). A misconfigured daemon must fail
+    // before mutating state. If manifestProvider is set, manifestRootKeys + a positive threshold are
+    // required.
+    if (manifestProvider && (!manifestRootKeys || !manifestThreshold || manifestThreshold <= 0)) {
+        throw new Error("DaemonConfig: manifestProvider requires manifestRootKeys (non-empty) and manifestThreshold (positive integer >= 1)");
+    }
+    // ── PERSIST-002: open the encrypted store FIRST (runs the one-time flat-file → SQLCipher migration
+    // (AC-006) + creates the agents/manifest_state schema), under the single-instance lock. This must
+    // precede the manifest verification below because the manifest version is now stored in the
+    // encrypted DB (AC-008), not a manifest-version.json file. ──
+    await mkdir(celloDir, { recursive: true });
+    await mkdir(dirname(socketPath), { recursive: true });
+    await acquireLock(lockFilePath, { pid: process.pid, socketPath, version });
+    const sessionNodeManager = new SessionNodeManager({
+        factory: sessionNodeFactory ?? new ProductionSessionNodeFactory(),
+        logger,
+        dbPath: join(celloDir, "sessions.db"),
+        contentTtfMs: config.contentTtfMs,
+        autoNatProbers: () => [],
+    });
+    await sessionNodeManager.initialize();
+    // AC-008: the manifest version store is DB-backed by default (encrypted manifest_state table). A
+    // test may inject an override (e.g. InMemoryManifestVersionStore) via config.
+    const manifestVersionStore = injectedManifestVersionStore ?? new DbManifestVersionStore(sessionNodeManager.getDb(), logger);
     // M7-MANIFEST-002: Load and verify consortium manifest BEFORE any directory connection.
     //
     // Pseudocode for manifest loading:
@@ -197,12 +223,6 @@ export async function startDaemon(config) {
     // M7 Keystone: the version of the verified manifest, surfaced in ConnectResult.
     // Stays 0 when no manifestProvider is configured (the M6 backward-compat path).
     let verifiedManifestVersion = 0;
-    // ADV-006 + ADV-008: If manifestProvider is set, manifestRootKeys and a positive
-    // manifestThreshold are required. Fail loudly on misconfiguration rather than
-    // silently proceeding unverified.
-    if (manifestProvider && (!manifestRootKeys || !manifestThreshold || manifestThreshold <= 0)) {
-        throw new Error("DaemonConfig: manifestProvider requires manifestRootKeys (non-empty) and manifestThreshold (positive integer >= 1)");
-    }
     if (manifestProvider && manifestRootKeys && manifestThreshold !== undefined) {
         try {
             const manifest = await manifestProvider.loadAndVerify(manifestRootKeys, manifestThreshold);
@@ -223,26 +243,16 @@ export async function startDaemon(config) {
                 });
             }
             else {
-                // Check version monotonicity if version store is provided
-                if (manifestVersionStore) {
-                    const lastSeen = await manifestVersionStore.getLastSeenVersion();
-                    if (lastSeen !== null && manifest.version < lastSeen) {
-                        logger.error("directory.auth.manifest.version.rollback", {
-                            manifestVersion: manifest.version,
-                            lastSeenVersion: lastSeen,
-                        });
-                    }
-                    else {
-                        await manifestVersionStore.persistVersion(manifest.version);
-                        manifestVerified = true;
-                        verifiedManifestVersion = manifest.version;
-                        logger.info("directory.auth.manifest.verified", {
-                            manifestVersion: manifest.version,
-                            signerCount: manifest.signatures.length,
-                        });
-                    }
+                // Anti-rollback monotonicity (manifestVersionStore is always present now — DB-backed default).
+                const lastSeen = await manifestVersionStore.getLastSeenVersion();
+                if (lastSeen !== null && manifest.version < lastSeen) {
+                    logger.error("directory.auth.manifest.version.rollback", {
+                        manifestVersion: manifest.version,
+                        lastSeenVersion: lastSeen,
+                    });
                 }
                 else {
+                    await manifestVersionStore.persistVersion(manifest.version);
                     manifestVerified = true;
                     verifiedManifestVersion = manifest.version;
                     logger.info("directory.auth.manifest.verified", {
@@ -262,21 +272,24 @@ export async function startDaemon(config) {
     // failed, the daemon must refuse to proceed. Operators who configure
     // manifestProvider have opted into manifest enforcement.
     if (manifestProvider && !manifestVerified) {
+        // code-review MED: this refuse now runs AFTER the DB is open + the lock is held (the DB had to
+        // open for the anti-rollback check). Release both before rethrowing so an in-process caller does
+        // not leak the DB handle / lock (in production the process exits, but be tidy).
+        try {
+            sessionNodeManager.getDb().close();
+        }
+        catch { /* ignore */ }
+        await removeLock(lockFilePath, logger).catch(() => { });
         throw new Error("Manifest verification failed. The daemon cannot start with an unverified manifest when manifestProvider is configured. " +
             "Check the logs for the specific failure reason (manifest_signature_invalid, manifest_expired, or manifest_version_rollback).");
     }
-    // Ensure the cello directory exists
-    await mkdir(celloDir, { recursive: true });
-    // Ensure the socket parent directory exists
-    await mkdir(dirname(socketPath), { recursive: true });
-    // Load agent identities
-    const { loaded: loadedAgents, failed: failedAgents } = await loadAgents(celloDir, logger);
-    // Acquire lock file
-    await acquireLock(lockFilePath, {
-        pid: process.pid,
-        socketPath,
-        version,
-    });
+    // Load agent identities from the encrypted `agents` table (PERSIST-002 AC-007 — one path).
+    // (The encrypted store + lock were established above, before manifest verification.)
+    const { loaded: loadedAgents, failed: failedAgents } = await loadAgents(sessionNodeManager.getDb(), logger);
+    // PERSIST-002: per-agent DB-backed identity persistence. The registration handler and the
+    // ceremony/seal signer-reconstruction load the FROST share (and persist the identity) through this
+    // seam — the encrypted `agents` row, never a flat file.
+    const getPersistence = (agentName) => new DbRegistrationPersistence({ db: sessionNodeManager.getDb(), agentName, logger });
     // Build agent state (all start in 'registered' state — no auto-start)
     const agents = [
         ...loadedAgents.map((a) => ({
@@ -335,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;
@@ -446,7 +463,7 @@ export async function startDaemon(config) {
         // registration routing). Unregistered implicitly when the manager is stopped.
         wireSessionCeremonyHandler({
             agentName,
-            agentDir: join(celloDir, "agents", agentName),
+            persistence: getPersistence(agentName),
             agentPubkeyHex,
             getNode: entry.getNode,
             getDirectoryEndpoint: async () => (directoryEndpointResolver ? (await directoryEndpointResolver()) ?? null : null),
@@ -456,7 +473,7 @@ export async function startDaemon(config) {
         // DOD-SPINE-7: coordinate the SEAL FROST ceremony on this agent's stream too.
         wireSealCeremonyHandler({
             agentName,
-            agentDir: join(celloDir, "agents", agentName),
+            persistence: getPersistence(agentName),
             agentPubkeyHex,
             getNode: entry.getNode,
             getDirectoryEndpoint: async () => (directoryEndpointResolver ? (await directoryEndpointResolver()) ?? null : null),
@@ -505,57 +522,56 @@ 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) {
+    // 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.
+    function wireKeystonePrimary(agent) {
         wireSessionCeremonyHandler({
-            agentName: primaryAgent.name,
-            agentDir: join(celloDir, "agents", primaryAgent.name),
-            agentPubkeyHex: primaryAgent.pubkey,
+            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,
-            agentDir: join(celloDir, "agents", primaryAgent.name),
-            agentPubkeyHex: primaryAgent.pubkey,
+            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),
+            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.
+        registerSessionSealedListener(signalingManager, agent.name, agent.pubkey);
+        registerUnilateralConfirmedListener(signalingManager, agent.name, agent.pubkey);
+        registerUnilateralUpgradeListener(signalingManager, agent.name, agent.pubkey);
     }
+    if (primaryAgent)
+        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();
     // Set of agents currently in "online" state (transitioned via cello_start_agent)
     const onlineAgents = new Set();
-    // Initialize SessionNodeManager (DAEMON-002: composition root — AC-011).
-    // This runs before the IPC socket opens so:
-    //   1. The standing receiver is ready before any cello_await_session call.
-    //   2. Interrupted session detection runs before any tool call can race.
-    const sessionNodeManager = new SessionNodeManager({
-        factory: sessionNodeFactory ?? new ProductionSessionNodeFactory(),
-        logger,
-        dbPath: join(celloDir, "sessions.db"),
-        contentTtfMs: config.contentTtfMs,
-        // CELLO-M7-TRANSPORT-001: directory-node AutoNAT probers (SI-002). The
-        // directory connection (SIGNAL-001) is not yet wired into the daemon, so the
-        // prober set is empty — AutoNAT cannot run and the standing receiver reports
-        // the conservative default + transport.autonat.unavailable (AC-004/DB-001).
-        autoNatProbers: () => [],
-    });
-    await sessionNodeManager.initialize();
+    // SessionNodeManager was constructed + initialized at the top of startDaemon (PERSIST-002 — the
+    // encrypted store must open before agents load from the `agents` table). Its standing receiver +
+    // interrupted-session detection are already ready here, before the IPC socket opens.
     // CELLO-M7-TRANSPORT-001: the daemon's runtime AutoNAT service is the one
     // wrapping the standing receiver node (it emits transport.autonat.result /
     // transport.autonat.unavailable and its dialability drives the SessionAssignment
@@ -687,7 +703,7 @@ export async function startDaemon(config) {
     // DAEMON-003: Initialize RetryQueue and NonceDedupStore (AC-008).
     // Both use the same SQLite DB as the SessionNodeManager (daemon.db equivalent).
     // loadFromDb() must complete BEFORE IPC socket opens (AC-007).
-    const retryQueue = new RetryQueue(sessionNodeManager.getDb(), logger, sessionNodeManager.getTranscriptCipher());
+    const retryQueue = new RetryQueue(sessionNodeManager.getDb(), logger);
     retryQueue.loadFromDb();
     // CELLO-M7-MSG-001 (AC-001/AC-003/AC-019): wire the awaiting-ACK lifecycle's durable
     // side effects to the retry_queue. A `persisted` delivery ACK clears the durable
@@ -925,6 +941,57 @@ export async function startDaemon(config) {
         notificationDispatcher.dispatchAgentStateChanged(name, "online", "started");
         return { ok: true };
     });
+    // ─── PERSIST-002 (AC-004): cello_create_agent handler ───
+    // The explicit agent-creation path: generate a fresh K_local seed, write it as an `agents` row in
+    // the encrypted DB (NO key file), and wire the agent into the live daemon so it can be registered
+    // and used WITHOUT a restart. Creation is explicit — cello_start_agent never auto-creates on a typo.
+    handlers.set("cello_create_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 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)) {
+            return { ok: false, reason: "agent_already_exists", guidance: `Agent '${name}' already exists. Choose a different name, or see cello_list_agents.` };
+        }
+        let pubkeyHex;
+        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);
+            // 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);
+            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) {
+                primaryAgent = loaded;
+                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) });
+            return { ok: false, reason: "agent_create_failed", guidance: "Could not create the agent. Check the daemon log and that the CELLO directory is writable, then retry." };
+        }
+        // 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 };
+    });
     // ─── MCP-001: cello_stop_agent handler ───
     handlers.set("cello_stop_agent", async (params, _connectionId) => {
         const name = params?.name;
@@ -1028,7 +1095,7 @@ export async function startDaemon(config) {
         }
         const keyProvider = keyProviders.get(name);
         if (!keyProvider) {
-            return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' has no local K_local key loaded. Its key must exist at ~/.cello/agents/${name}/key before registration — create it and restart the daemon, then retry cello_register.` };
+            return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' does not exist. Create it first with cello_create_agent('${name}') (or 'cello create-agent ${name}'), then retry cello_register.` };
         }
         if (!directoryEndpointResolver) {
             return { ok: false, reason: "directory_unreachable", guidance: "The daemon has no directory endpoint resolver configured, so it cannot reach the directory to register." };
@@ -1074,7 +1141,7 @@ export async function startDaemon(config) {
                     guidance: `Agent '${name}' could not establish its directory signaling stream within 10s. Check CELLO_DIRECTORY_URL and that the directory is reachable, then retry cello_register.`,
                 };
             }
-            const persistence = new FileRegistrationPersistence({ agentDir: join(celloDir, "agents", name), logger });
+            const persistence = getPersistence(name);
             const ctx = new DaemonRegistrationContext({
                 signaling: agentSignaling,
                 getDirectoryNode: agentGetNode,
@@ -1092,6 +1159,10 @@ export async function startDaemon(config) {
                     await dropAgentSignaling(name);
                     return { ok: false, reason: result.error, guidance: registrationGuidance(result.error) };
                 }
+                // PERSIST-002 (AC-013): the identity row (K_local + share + ML-DSA + registration) is durably
+                // committed at this point (RegistrationManager awaits the persist before returning success).
+                // SI-001: never log a secret — only the agent name + PUBLIC key.
+                logger.info("persist.identity.persisted", { agentName: name, agentPubkey: agentPubkeyHex });
                 // Capture-now-or-lose-it: persist the agent→user link (using it is future
                 // trust-layer work). L1: the agent is already registered at this point —
                 // a link-write failure must NOT be reported as a registration failure.
@@ -1168,7 +1239,7 @@ export async function startDaemon(config) {
                         return;
                     }
                     const record = sessionNodeManager.getSessionRecord(agentName, sidHex);
-                    const verdict = await verifyBilateralSealCertificate({ agentDir: join(celloDir, "agents", agentName), agentPubkeyHex, logger, counterpartyPrimaryHex: record?.counterparty_primary_pubkey ?? null }, {
+                    const verdict = await verifyBilateralSealCertificate({ persistence: getPersistence(agentName), agentPubkeyHex, logger, counterpartyPrimaryHex: record?.counterparty_primary_pubkey ?? null }, {
                         sessionId: sessionIdBytes,
                         sealedRoot: sealedRootBytes,
                         leafCount,
@@ -1318,7 +1389,7 @@ export async function startDaemon(config) {
                     waiter({ ok: false, reason: "malformed_certificate" });
                     return;
                 }
-                const result = await verifyUnilateralCertificate({ agentDir: join(celloDir, "agents", agentName), agentPubkeyHex, logger }, { sessionId, sealedRoot, leafCount, closeTimestamp: closeTs, frostSignature: frostSig, signatureType: sigType });
+                const result = await verifyUnilateralCertificate({ persistence: getPersistence(agentName), agentPubkeyHex, logger }, { sessionId, sealedRoot, leafCount, closeTimestamp: closeTs, frostSignature: frostSig, signatureType: sigType });
                 pendingUnilateralWaiters.delete(sidHex);
                 if (!result.ok) {
                     // SI-003: do NOT mark sealed when the certificate signature does not verify.
@@ -1374,7 +1445,7 @@ export async function startDaemon(config) {
     // ONLY on ok. Never trust the directory's "bilateral" claim.
     async function verifyAndApplyUpgradeConfirmed(agentName, agentPubkeyHex, sidHex, frame) {
         const result = await verifyUpgradeConfirmedCert({
-            logger, agentName, agentPubkeyHex, celloDir,
+            logger, agentName, agentPubkeyHex, persistence: getPersistence(agentName),
             getCounterpartyHex: (a, s) => sessionNodeManager.getSessionRecord(a, s)?.counterparty_pubkey ?? null,
         }, sidHex, frame);
         if (!result.ok)
@@ -2564,25 +2635,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