@cello-protocol/daemon 0.0.29 → 0.0.31

package/dist/daemon.d.ts.map

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

package/dist/daemon.js

@@ -859,11 +859,16 @@ export async function startDaemon(config) {
         }
     }
     /**
-     * Open a transient VISITING signaling connection into a specific directory node (the target's home)
-     * and wire ONLY what a cross-node initiator needs there: the delegated-signer ceremony handler (the
-     * broker asks the initiator to co-sign the assignment over THIS connection). Seal + inbound handlers
-     * are NOT wired — the seal is client-coordinated over the agent's own roster, and this connection is
-     * initiator-only and transient. Caller MUST stop() it after the assignment arrives.
+     * Open a transient VISITING signaling connection into a specific directory node (the target's home /
+     * broker) and wire what a cross-node initiator needs there:
+     *  - the delegated-signer ceremony handler (the broker asks the initiator to co-sign the assignment
+     *    over THIS connection); and
+     *  - Fix #1 (cross-node seal-liveness): the seal ceremony handler + session_sealed/unilateral
+     *    listeners, because for a cross-node CLOSE the broker ALSO pushes seal_verified then session_sealed
+     *    over the connection the initiator holds to it. The seal FROST still runs over the agent's OWN
+     *    roster (getNode: () => nodeRef) — only the control frames traverse this stream.
+     * Transient and initiator-only. The caller MUST stop() it after the assignment (setup path) or after
+     * the seal reaches a terminal outcome (close path).
      */
     function openVisitingConnection(agentName, agentKeyProvider, agentPubkeyHex, endpoint, correlationId, nodeId) {
         let nodeRef = null;
@@ -888,6 +893,24 @@ export async function startDaemon(config) {
             signaling: mgr,
             logger,
         });
+        // Fix #1 (cross-node seal-liveness): a visiting connection must ALSO be able to complete the SEAL.
+        // The broker (the node this visiting connection targets) pushes seal_verified then session_sealed to
+        // whichever stream the initiator holds to it — for a cross-node close that is THIS visiting stream.
+        // Run the seal FROST ceremony over the agent's own node (getNode: () => nodeRef, exactly as the
+        // session ceremony above) and reply/resolve on this stream. Harmless on a setup-only visiting
+        // connection: these frames never arrive before it is released after handoff.
+        wireSealCeremonyHandler({
+            agentName,
+            persistence: getPersistence(agentName),
+            agentPubkeyHex,
+            getNode: () => nodeRef,
+            getDirectoryEndpoint: getFailoverEndpoint,
+            getConsortiumEndpoints: resolveConsortiumRoster,
+            signaling: mgr,
+            logger,
+        });
+        registerSessionSealedListener(mgr, agentName, agentPubkeyHex);
+        registerUnilateralConfirmedListener(mgr, agentName, agentPubkeyHex);
         logger.info("signaling.visiting.connected", { agentName, node: nodeId, correlationId });
         return {
             mgr,
@@ -897,6 +920,16 @@ export async function startDaemon(config) {
             },
         };
     }
+    // Fix #1 (cross-node seal-liveness): the broker node (the counterparty's home) for each cross-node
+    // session we initiated, keyed `${agentName}:${sessionIdHex}`. Set when runCrossNodeSetup establishes
+    // the session; read by cello_close_session so it can re-open a visiting connection to the broker and
+    // complete the seal there. The broker pushes seal_verified/session_sealed, but the initiator RELEASES
+    // its visiting connection after setup — so without reconnecting, the close times out
+    // (seal_unilateral_timeout) and the seal only completes whenever the daemon next happens to reconnect.
+    // Presence of an entry means the session is cross-node (same-node sessions never go through
+    // runCrossNodeSetup). In-memory only: a close in the SAME process (the common case) is covered; a close
+    // after a daemon restart falls back to the pre-fix behavior (deferred hardening: persist on the row).
+    const crossNodeBrokerBySession = new Map();
     /**
      * Resolve `owningNodeId` through the signed manifest and run the session_request over a transient
      * visiting connection there. A node id that doesn't resolve in the roster is a hard error
@@ -926,6 +959,9 @@ export async function startDaemon(config) {
             const result = await runSessionRequestOverSignaling(visiting.mgr, targetHex, sr, correlationId, agentName);
             if (result.ok) {
                 releaseReason = "handoff-complete";
+                // Fix #1: remember the broker for this session so cello_close_session can reconnect to complete the seal.
+                const brokerSessionIdHex = Buffer.from(result.assignment.session_id).toString("hex");
+                crossNodeBrokerBySession.set(`${agentName}:${brokerSessionIdHex}`, owningNodeId);
                 logger.info("session.crossnode.established", { agentName, brokerNode: owningNodeId, correlationId });
             }
             else {
@@ -1218,19 +1254,16 @@ export async function startDaemon(config) {
         return agents
             .filter((a) => a.state !== "load_failed")
             .map((a) => {
-            let state;
-            if (a.name === currentAgent && onlineAgents.has(a.name)) {
-                state = "current";
-            }
-            else if (onlineAgents.has(a.name)) {
-                state = "online";
-            }
-            else {
-                state = "registered";
-            }
+            // M8C-AUTOSTART-1 (F5): `state` reports readiness only (online vs registered); selection
+            // is a SEPARATE `selected` flag. Previously `state = "current"` overloaded the current
+            // agent, making it read as a different readiness level than a second healthy online agent.
+            const online = onlineAgents.has(a.name);
+            const state = online ? "online" : "registered";
+            const selected = online && a.name === currentAgent;
             return {
                 name: a.name,
                 state,
+                selected,
                 pubkey: a.pubkey,
                 // M8B F14 (fix 5): per-agent standing-receiver readiness on the MCP surface
                 // (cello_status / cello_list_agents), so a deaf agent is visible to the operator.
@@ -1312,11 +1345,13 @@ export async function startDaemon(config) {
         return { connectionId };
     });
     // ─── MCP-001: cello_start_agent handler ───
-    handlers.set("cello_start_agent", async (params, _connectionId) => {
-        const name = params?.name;
-        if (!name) {
-            return { ok: false, reason: "missing_params", guidance: "Provide 'name' parameter with the agent name to start." };
-        }
+    // M8C-AUTOSTART-1 (A2): the shared start path. Extracted from cello_start_agent so cello_use_agent
+    // can AUTO-START an offline agent through the exact same code (idempotent, same signaling +
+    // standing-receiver setup, same agent_state_changed event) — never a divergent shim-side retry.
+    // Permissive by design (D12): an agent that exists goes online regardless of directory
+    // registration state (online-without-registration is an established contract). Returns a
+    // structured failure so callers can surface agent_start_failed with a real reason + guidance.
+    function startAgentInternal(name) {
         const agent = agents.find((a) => a.name === name);
         if (!agent || agent.state === "load_failed") {
             return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' does not exist. Run 'cello login' to register agents, or check agent names with cello_list_agents.` };
@@ -1361,6 +1396,29 @@ export async function startDaemon(config) {
         // MCP-002: Broadcast agent_state_changed to ALL connections
         notificationDispatcher.dispatchAgentStateChanged(name, "online", "started");
         return { ok: true };
+    }
+    // M8C-AUTOSTART-1 (F18): resolve which agent a name-defaulting tool should act on for this
+    // connection: an explicit name wins; else the connection's current agent; else — when EXACTLY one
+    // agent is online daemon-wide — that sole agent (removes the "why did it forget my agent" moment
+    // after a /mcp reconnect). Two-or-more online with none selected stays ambiguous → null (the
+    // caller returns no_current_agent), because guessing between peers would misroute.
+    function resolveCurrentAgent(connState, explicitName) {
+        if (explicitName)
+            return explicitName;
+        if (connState?.currentAgent)
+            return connState.currentAgent;
+        if (onlineAgents.size === 1)
+            return [...onlineAgents][0];
+        return null;
+    }
+    // ─── MCP-001: cello_start_agent handler ───
+    // Bring a registered agent online WITHOUT claiming it as this connection's current agent.
+    handlers.set("cello_start_agent", async (params, _connectionId) => {
+        const name = params?.name;
+        if (!name) {
+            return { ok: false, reason: "missing_params", guidance: "Provide 'name' parameter with the agent name to start." };
+        }
+        return startAgentInternal(name);
     });
     // ─── 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
@@ -1612,15 +1670,36 @@ export async function startDaemon(config) {
         }
         const agent = agents.find((a) => a.name === name);
         if (!agent || agent.state === "load_failed") {
-            return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' does not exist. Check agent names with cello_list_agents.` };
-        }
-        if (!onlineAgents.has(name)) {
-            return { ok: false, reason: "agent_not_online", guidance: `Agent '${name}' exists but is not online. Call cello_start_agent('${name}') first to bring it online, then retry cello_use_agent.` };
+            return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' does not exist. Create it with 'cello create-agent ${name}', register it, then retry — or check names with cello_list_agents.` };
         }
         const connState = perConnectionState.get(connectionId);
         if (!connState) {
             return { ok: false, reason: "connection_not_registered", guidance: "Send ipc.connect frame before calling agent tools." };
         }
+        // M8C-AUTOSTART-1 (A1): auto-start the agent if it is not online, so the incantation collapses
+        // to `login → use_agent` (no separate cello_start_agent). On a start failure, return a
+        // structured agent_start_failed and leave the current selection UNCHANGED — no half-selected
+        // state (A3). cello_start_agent stays available for bring-online-without-claiming.
+        if (!onlineAgents.has(name)) {
+            logger.info("agent.autostart.attempted", { connectionId, agentName: name });
+            const startRes = startAgentInternal(name);
+            if (!startRes.ok) {
+                // Structured failure envelope (D6). Today `startAgentInternal` is permissive (D12) and its
+                // only failure — agent_not_found — is already caught by the existence pre-check above, so
+                // this branch is currently unreachable. It is the RESERVED structured-failure surface for
+                // when auto-start gains a synchronous failure mode (e.g. D12's reverse: a bounded
+                // waitForSignalingConnected making `directory_unreachable` a real start failure). Kept so
+                // that extension surfaces the reason + guidance here with the selection left unchanged.
+                // See M8C-DECISIONS D12 + BUILD-JOURNAL Entry 8.
+                logger.warn("agent.autostart.failed", { connectionId, agentName: name, reason: startRes.reason });
+                return {
+                    ok: false,
+                    reason: "agent_start_failed",
+                    start_reason: startRes.reason,
+                    guidance: `Could not start agent '${name}' to select it: ${startRes.guidance} Your current agent is unchanged.`,
+                };
+            }
+        }
         if (connState.currentAgent === name) {
             return { ok: false, reason: "agent_already_current", guidance: `Agent '${name}' is already the current agent for this connection. No action needed — you can proceed with session operations.` };
         }
@@ -1630,7 +1709,26 @@ export async function startDaemon(config) {
         notificationDispatcher.setCurrentAgent(connectionId, name);
         notificationDispatcher.dispatchAgentCurrentChanged(connectionId, fromAgent, name);
         logger.info("agent.current.switched", { connectionId, fromAgent, toAgent: name });
-        return { ok: true };
+        // M8C-AUTOSTART-1 (A3, D12): not_registered is a NON-BLOCKING warning — the agent is selected
+        // and usable locally, but it cannot establish directory sessions until registered. Surface the
+        // next step (ONBOARD-NEXTSTEP style) without stranding the selection. One-row read.
+        const result = { ok: true };
+        try {
+            const reg = await new DbRegistrationPersistence({ db: sessionNodeManager.getDb(), agentName: name, logger }).loadRegistrationState();
+            if (!reg || reg.status !== "active") {
+                result["warning"] = "not_registered";
+                result["warning_guidance"] = `Agent '${name}' is now selected but is not registered with the directory — run 'cello register ${name}' to enable sessions with peers. Run 'cello status' to watch registration complete.`;
+            }
+        }
+        catch (err) {
+            // A failed registration read must not break selection (the agent IS selected). Log the real
+            // reason, and surface a softer `registration_unknown` warning so the operator's surface is NOT
+            // falsely clean — we could not confirm registration, so don't imply it is fine (Finding 3).
+            logger.warn("agent.registration.read.failed", { agentName: name, reason: err instanceof Error ? err.message : String(err) });
+            result["warning"] = "registration_unknown";
+            result["warning_guidance"] = `Agent '${name}' is selected, but its registration status could not be read — run 'cello status' to check whether it is registered with the directory.`;
+        }
+        return result;
     });
     // ─── MCP-001: cello_list_agents handler ───
     handlers.set("cello_list_agents", async (_params, connectionId) => {
@@ -2268,7 +2366,7 @@ export async function startDaemon(config) {
     // ─── M8B DOD-REFRESH-1: cello_refresh_shares — proactive share refresh / epoch rollover ───
     handlers.set("cello_refresh_shares", async (params, connectionId) => {
         const connState = perConnectionState.get(connectionId);
-        const agentName = params?.name ?? connState?.currentAgent;
+        const agentName = resolveCurrentAgent(connState, params?.name); // M8C-AUTOSTART-1 F18: sole-online fallback
         if (!agentName) {
             return { ok: false, reason: "no_current_agent", guidance: "Select an agent with cello_use_agent, or pass { name }." };
         }
@@ -2300,7 +2398,7 @@ export async function startDaemon(config) {
     // ─── M8B DOD-RELAYSIG-1: cello_get_relay_receipts — the agent's stored relay ordering receipts ───
     handlers.set("cello_get_relay_receipts", async (params, connectionId) => {
         const connState = perConnectionState.get(connectionId);
-        const agentName = params?.name ?? connState?.currentAgent;
+        const agentName = resolveCurrentAgent(connState, params?.name); // M8C-AUTOSTART-1 F18: sole-online fallback
         if (!agentName) {
             return { ok: false, reason: "no_current_agent", guidance: "Select an agent with cello_use_agent, or pass { name }." };
         }
@@ -2584,7 +2682,43 @@ export async function startDaemon(config) {
         if (record.status === "active") {
             sealInterruptedInProgress.add(sealKey(record.agent_name, sessionId));
             const correlationId = randomUUID();
+            // Fix #1 (cross-node seal-liveness): if this session was brokered by another node, the seal_verified
+            // + session_sealed frames are pushed by that BROKER — but the initiator released its visiting
+            // connection after setup, so on the home stream they never arrive and close times out. Re-open a
+            // transient visiting connection to the broker (seal-capable — openVisitingConnection now wires the
+            // seal handlers) for the duration of the seal, then release it in finally. Same-node sessions have
+            // no entry here and use the home stream unchanged.
+            let sealBrokerConn = null;
             try {
+                const brokerNodeForSeal = crossNodeBrokerBySession.get(`${record.agent_name}:${sessionId}`);
+                if (brokerNodeForSeal) {
+                    const sealKp = keyProviders.get(record.agent_name);
+                    if (!sealKp) {
+                        // Fallback-finder #1: never skip the cross-node reconnect silently — without a key provider
+                        // we cannot open the broker connection, so the seal will revert to the pre-fix timeout. Log
+                        // WHY so it is not indistinguishable from a normal counterparty-didn't-close timeout.
+                        logger.warn("session.seal.broker.no_keyprovider", { agentName: record.agent_name, brokerNode: brokerNodeForSeal, correlationId });
+                    }
+                    else {
+                        const sealPubHex = Buffer.from(await sealKp.getPublicKey()).toString("hex");
+                        const roster = await resolveConsortiumRoster();
+                        const brokerTarget = roster?.find((e) => e.nodeId === brokerNodeForSeal) ?? null;
+                        if (!brokerTarget) {
+                            logger.warn("session.seal.broker.unresolved", { agentName: record.agent_name, brokerNode: brokerNodeForSeal, correlationId });
+                        }
+                        else {
+                            const conn = openVisitingConnection(record.agent_name, sealKp, sealPubHex, { peerId: brokerTarget.peerId, multiaddr: brokerTarget.multiaddr }, correlationId, brokerNodeForSeal);
+                            if (await waitForSignalingConnected(conn.mgr, 10_000)) {
+                                sealBrokerConn = conn;
+                                logger.info("session.seal.broker.reconnected", { agentName: record.agent_name, brokerNode: brokerNodeForSeal, correlationId });
+                            }
+                            else {
+                                await conn.stop("seal-broker-unreachable");
+                                logger.warn("session.seal.broker.unreachable", { agentName: record.agent_name, brokerNode: brokerNodeForSeal, correlationId });
+                            }
+                        }
+                    }
+                }
                 // M7 DOD-SPINE-7: relay-mediated bilateral seal. Submit our SEAL ctrl leaf to the
                 // relay witness; when the counterparty ALSO closes, the relay's #maybeProcessSeal
                 // fires → directory processSeal rebuilds + verifies the signed chain → FROST
@@ -2623,6 +2757,7 @@ export async function startDaemon(config) {
                 pendingSealWaiters.delete(sealKey(record.agent_name, sessionId));
                 if (sealedCompletion !== null) {
                     logger.info("session.seal.completed", { sessionId, sealedRoot: sealedCompletion.rootHex, role: "bilateral", correlationId });
+                    crossNodeBrokerBySession.delete(`${record.agent_name}:${sessionId}`); // Fix #1 review: evict on terminal seal success (a FAILED close keeps the entry so a retry can still reconnect).
                     // M7-SESSION-004 (AC-006): return the legibility certificate on the seal completion so
                     // a reader gets it on the same surface that proves the seal — receipt-not-assent,
                     // per-party frontiers, attestation modes, and final_message.answered.
@@ -2698,6 +2833,7 @@ export async function startDaemon(config) {
                 pendingUnilateralWaiters.delete(sessionId);
                 if (uniResult.ok) {
                     logger.info("session.seal.completed", { sessionId, sealedRoot: uniResult.sealedRootHex, role: "unilateral", correlationId });
+                    crossNodeBrokerBySession.delete(`${record.agent_name}:${sessionId}`); // Fix #1 review: evict on terminal seal success (a FAILED close keeps the entry so a retry can still reconnect).
                     // M8B FINDING-3 (cascade-2): return the legibility certificate inline — same shape as the
                     // bilateral close (AC-006) — so the operator gets the receipt on the surface that proves
                     // the seal, not just a bare root. It is also persisted (above) for cello_get_sealed_receipt.
@@ -2726,6 +2862,15 @@ export async function startDaemon(config) {
                 };
             }
             finally {
+                // Fix #1: release the transient broker seal-connection (best-effort; the seal result stands).
+                if (sealBrokerConn) {
+                    try {
+                        await sealBrokerConn.stop("seal-complete");
+                    }
+                    catch (err) {
+                        logger.warn("session.seal.broker.release_failed", { sessionId, reason: err instanceof Error ? err.message : String(err) });
+                    }
+                }
                 sealInterruptedInProgress.delete(sealKey(record.agent_name, sessionId));
             }
         }
@@ -2762,15 +2907,47 @@ export async function startDaemon(config) {
         if (!connState || !connState.currentAgent) {
             return NO_CURRENT_AGENT_RESPONSE;
         }
-        const cert = sessionNodeManager.getSealCertificate(connState.currentAgent, sessionId);
-        if (!cert) {
+        const agentName = connState.currentAgent;
+        const cert = sessionNodeManager.getSealCertificate(agentName, sessionId);
+        if (cert) {
+            return { ok: true, session_id: sessionId, sealed_root: cert.sealed_root, legibility: cert.legibility };
+        }
+        // M8C-INBOX-1 (F4): the single `sealed_receipt_not_found` conflated four distinct causes, so a
+        // caller could not tell a typo from a not-sealed-yet session from a wrong-agent selection.
+        // Split them (full session ids on cello_list_sessions / cello_status already let a pasted id match).
+        if (sessionNodeManager.getSessionRecord(agentName, sessionId)) {
+            // The session is THIS agent's — it simply has no seal certificate yet.
+            return {
+                ok: false,
+                reason: "not_sealed_yet",
+                guidance: "This session exists but is not sealed yet. Close it with cello_close_session and confirm it reports sealed (or wait for the counterparty to co-seal), then retry.",
+            };
+        }
+        // Owned by a DIFFERENT loaded agent → the caller has the wrong current agent selected.
+        const owner = loadedAgents.find((a) => a.name !== agentName && sessionNodeManager.getSessionRecord(a.name, sessionId));
+        if (owner) {
+            return {
+                ok: false,
+                reason: "wrong_agent",
+                guidance: `This session belongs to agent '${owner.name}', not the current agent '${agentName}'. Call cello_use_agent('${owner.name}') then retry cello_get_sealed_receipt.`,
+            };
+        }
+        // A truncated paste: the id is a strict prefix of one of this agent's real session ids.
+        const truncated = sessionNodeManager
+            .getSessionsForAgent(agentName)
+            .some((s) => s.session_id.startsWith(sessionId) && s.session_id.length > sessionId.length);
+        if (truncated) {
             return {
                 ok: false,
-                reason: "sealed_receipt_not_found",
-                guidance: "No sealed certificate is recorded for this session. It may not be sealed yet, or the session_id is wrong — close it with cello_close_session and confirm it reports sealed, then retry.",
+                reason: "session_id_too_short",
+                guidance: "That looks like a truncated session id. cello_list_sessions and cello status show the FULL id — copy the complete id and retry.",
             };
         }
-        return { ok: true, session_id: sessionId, sealed_root: cert.sealed_root, legibility: cert.legibility };
+        return {
+            ok: false,
+            reason: "unknown_session",
+            guidance: "No session with this id belongs to the current agent. Run cello_list_sessions to see the full ids of this agent's sessions.",
+        };
     });
     // DOD-LOG-1 (PERSIST-LOG-001): read the durable, decrypted conversation transcript for a session —
     // the readable sent+received messages in canonical-sequence order, recovered AFTER a daemon restart
@@ -3117,6 +3294,32 @@ export async function startDaemon(config) {
             }
             return { ok: true };
         });
+        // M8C-INBOX-1: test hook to enqueue a pending inbound session request (mirrors the real inbound
+        // flow's enqueueInboundSession) so cello_check_notifications' pending_session_requests is testable
+        // without standing up the full libp2p inbound path.
+        handlers.set("__test_enqueue_inbound_session", async (params, _connectionId) => {
+            const agentName = params?.agentName;
+            const sessionIdHex = params?.sessionId;
+            const counterpartyPubkeyHex = params?.counterpartyPubkey ?? "";
+            if (!agentName || !sessionIdHex) {
+                return { error: "missing_params", guidance: "Provide agentName and sessionId." };
+            }
+            enqueueInboundSession(agentName, { sessionIdHex, counterpartyPubkeyHex, genesisPrevRootHex: "" });
+            return { ok: true };
+        });
+        // M8C-INBOX-1 (reviewer F1): buffer a received message so a test can drive a live cello_receive
+        // and assert the watermark advances (the N3 delivery-marks-read coupling), without a session tree.
+        handlers.set("__test_buffer_received", async (params, _connectionId) => {
+            const agentName = params?.agentName;
+            const sessionId = params?.sessionId;
+            const seq = params?.seq;
+            const content = params?.content ?? "hello";
+            if (!agentName || !sessionId || typeof seq !== "number") {
+                return { error: "missing_params", guidance: "Provide agentName, sessionId, seq." };
+            }
+            sessionNodeManager.pushReceivedContentForTest(agentName, sessionId, seq, content, params?.senderPubkey ?? "cp");
+            return { ok: true };
+        });
     } // end CELLO_ENV=test guard
     // ─── M7-SESSION-001 (H-1): seal-interrupted bilateral RESPONDER ────────────
     //
@@ -4224,6 +4427,9 @@ export async function startDaemon(config) {
             // 1) Deliverable content wins — drain one buffered message per call (FIFO).
             const entry = sessionNodeManager.takeReceivedContent(agentName, sessionId);
             if (entry) {
+                // M8C-INBOX-1 (N3): delivery marks read — advance the persisted read watermark so this
+                // message no longer counts as unread in cello_check_notifications. Monotonic (never lowers).
+                sessionNodeManager.advanceLastDeliveredSeq(agentName, sessionId, entry.sequenceNumber);
                 return {
                     ok: true,
                     content: Buffer.from(entry.contentHex, "hex").toString("utf8"),
@@ -4271,6 +4477,45 @@ export async function startDaemon(config) {
     };
     handlers.set("cello_receive", handleReceive);
     handlers.set("cello_receive_session", handleReceive);
+    // ─── M8C-INBOX-1 (N1/N4): cello_check_notifications — push-loss reconciler + poll-only inbox ───
+    // Notifications are fire-and-forget (no ack, no redelivery); this is how a client discovers what
+    // it missed while its shim was down/busy, and the primary inbox for poll-only clients (Bedrock,
+    // cron). Content-free: pending session requests (from the in-memory queue, READ non-destructively —
+    // cello_await_session owns draining) + unread message counts (derived from the persisted read
+    // watermark, N2). No separate notification store; no ack verb (N4).
+    handlers.set("cello_check_notifications", async (params, connectionId) => {
+        const connState = perConnectionState.get(connectionId);
+        const scope = params?.scope === "all" ? "all" : "current";
+        let agentNames;
+        if (scope === "all") {
+            agentNames = loadedAgents.map((a) => a.name);
+        }
+        else {
+            // F18: an explicit current agent, else the sole-online agent; ambiguous → no_current_agent.
+            const current = resolveCurrentAgent(connState);
+            if (!current) {
+                return {
+                    ok: false,
+                    reason: "no_current_agent",
+                    guidance: "No current agent for this connection. Call cello_use_agent to select one, or use scope:\"all\" to check every loaded agent.",
+                };
+            }
+            agentNames = [current];
+        }
+        const agents = agentNames.map((agent) => {
+            const pending = (inboundSessionQueues.get(agent) ?? []).map((e) => ({
+                session_id: e.sessionIdHex,
+                from: e.counterpartyPubkeyHex,
+            }));
+            const unread = sessionNodeManager.getUnreadSummary(agent);
+            const total_unread = unread.reduce((sum, u) => sum + u.unread_count, 0);
+            return { agent, pending_session_requests: pending, unread, total_unread };
+        });
+        const totalUnread = agents.reduce((sum, a) => sum + a.total_unread, 0);
+        const totalPending = agents.reduce((sum, a) => sum + a.pending_session_requests.length, 0);
+        logger.info("inbox.checked", { connectionId, scope, agentCount: agents.length, totalUnread, totalPending });
+        return { ok: true, scope, agents };
+    });
     let shutdownPromise = null;
     handlers.set("shutdown", async (_params, _connectionId) => {
         if (!shutdownPromise) {