@cello-protocol/daemon 0.0.46 → 0.0.48

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,EAQrB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAU/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAsB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAQ/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;AA2CD,eAAO,MAAM,sBAAsB,QAAsB,CAAC;AAE1D,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA64L7E"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EAQrB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAU/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAsB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAQ/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;AA2CD,eAAO,MAAM,sBAAsB,QAAsB,CAAC;AAE1D,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA4gM7E"}

package/dist/daemon.js

@@ -31,6 +31,7 @@ import { dirname, join } from "node:path";
 import { loadAgents } from "./agent-loader.js";
 import { acquireLock, removeLock } from "./lock-file.js";
 import { createIpcServer } from "./ipc-server.js";
+import { renderForSurface } from "./vocabulary.js";
 import { SessionNodeManager } from "./session-node-manager.js";
 import { TIER, isKnownTierValue } from "./contacts-tier-migration.js";
 import { isValidSettingKey, allSettingKeys, validateSettingValue, AWAY_MESSAGE_MAX_LEN } from "./agent-settings-keys.js";
@@ -786,6 +787,24 @@ export async function startDaemon(config) {
             cursor += 1;
         advanceConnectionCursor(connectionId, sessionId, cursor);
     }
+    /**
+     * DOD-CURSOR-DURABLE-1: the same hole-safe walk, applied to the PERSISTED per-(agent, session)
+     * read watermark. Used by cello_get_transcript, whose delivery covers BOTH directions.
+     *
+     * Walks a CONTIGUOUS run from the agent's current watermark, stopping at the first gap — for the
+     * identical reason safeCursorAdvance does: leaf indices are contiguous across both directions, so
+     * a gap can hide an unread RECEIVED message (e.g. a row that failed to decrypt is absent from
+     * `messages`). Advancing past it would mark unseen counterparty content as read and unblock a
+     * send that never saw it — defeating the very guarantee this gate exists to enforce. Monotonic:
+     * advanceLastDeliveredSeq takes MAX, so this can never lower a watermark.
+     */
+    function safeWatermarkAdvance(agentName, sessionId, deliveredSeqs) {
+        let frontier = sessionNodeManager.getLastDeliveredSeq(agentName, sessionId);
+        while (deliveredSeqs.has(frontier + 1))
+            frontier += 1;
+        if (frontier >= 0)
+            sessionNodeManager.advanceLastDeliveredSeq(agentName, sessionId, frontier);
+    }
     // M8C-AWAY-1: away response — an unattended Primary auto-answers session requests + messages
     // with the default transparent away text and queues them (the DoD's own mandated default).
     // CORE ships now; the operator-configurable custom-text / opaque-privacy-mode SWITCH is PARKED
@@ -1779,7 +1798,7 @@ export async function startDaemon(config) {
     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.` };
+            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_agents.` };
         }
         if (onlineAgents.has(name)) {
             // Idempotent — already online, no event
@@ -1856,7 +1875,7 @@ export async function startDaemon(config) {
         }
         const store = new DbIdentityStore(sessionNodeManager.getDb(), logger);
         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.` };
+            return { ok: false, reason: "agent_already_exists", guidance: `Agent '${name}' already exists. Choose a different name, or see cello_agents.` };
         }
         let pubkeyHex;
         let agentId;
@@ -1966,7 +1985,7 @@ export async function startDaemon(config) {
         // 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.` };
+            return { ok: false, reason: "agent_not_found", guidance: `No agent named '${name}'. Check cello_agents.` };
         }
         const wasActive = target.state !== "retired";
         const agentId = target.localAgentId;
@@ -2064,7 +2083,7 @@ 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.` };
+            return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' does not exist. Check agent names with cello_agents.` };
         }
         if (!onlineAgents.has(name)) {
             // Idempotent — already registered/offline, no event
@@ -2095,7 +2114,7 @@ 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. Create it with 'cello create-agent ${name}', register it, then retry — or check names with cello_list_agents.` };
+            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_agents.` };
         }
         const connState = perConnectionState.get(connectionId);
         if (!connState) {
@@ -2148,7 +2167,7 @@ export async function startDaemon(config) {
             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.`;
+                result["warning_guidance"] = `Agent '${name}' is now selected but is not registered with the directory — run 'cello register-agent ${name}' to enable sessions with peers. Run 'cello status' to watch registration complete.`;
             }
         }
         catch (err) {
@@ -2201,11 +2220,11 @@ export async function startDaemon(config) {
             return { ok: false, reason: "missing_params", guidance: "Provide 'agent' (the agent name to register) and 'preAuthToken' (the pre-authorization ticket from the CELLO Operations Agent)." };
         }
         if (!preAuthToken) {
-            return { ok: false, reason: "missing_preauth_token", guidance: "Registration requires a 'preAuthToken' issued by the CELLO Operations Agent (Telegram). Obtain one, then retry cello_register." };
+            return { ok: false, reason: "missing_preauth_token", guidance: "Registration requires a 'preAuthToken' issued by the CELLO Operations Agent (Telegram). Obtain one, then retry 'cello register-agent'." };
         }
         const keyProvider = keyProviders.get(name);
         if (!keyProvider) {
-            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.` };
+            return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' does not exist. Create it first with 'cello create-agent ${name}', then retry 'cello register-agent'.` };
         }
         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." };
@@ -2255,7 +2274,7 @@ export async function startDaemon(config) {
                 return {
                     ok: false,
                     reason: "directory_signaling_timeout",
-                    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.`,
+                    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-agent'.`,
                 };
             }
             const persistence = getPersistence(name);
@@ -3074,7 +3093,7 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 reason: "session_not_found",
-                guidance: "No session found with this ID. Check cello_list_sessions for active and interrupted sessions.",
+                guidance: "No session found with this ID. Check cello_sessions for active and interrupted sessions.",
             };
         }
         // Ownership: redundant now that the lookup is agent-scoped (record.agent_name === currentAgent),
@@ -3083,7 +3102,7 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 reason: "session_not_owned",
-                guidance: "This session belongs to a different agent. Call cello_use_agent to switch to the agent that owns it (see cello_list_sessions), then retry.",
+                guidance: "This session belongs to a different agent. Call cello_use_agent to switch to the agent that owns it (see cello_sessions), then retry.",
             };
         }
         // AC-010: already sealed
@@ -3091,7 +3110,7 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 reason: "session_already_sealed",
-                guidance: "This session is already sealed. No further action is needed — check cello_list_sessions to view its sealed record and the FROST notarization.",
+                guidance: "This session is already sealed. No further action is needed — check cello_sessions to view its sealed record and the FROST notarization.",
             };
         }
         // CC-5/F21 terminal-escape: force-abandon a session that can never be bilaterally sealed — a
@@ -3336,7 +3355,7 @@ export async function startDaemon(config) {
                 return {
                     ok: false,
                     reason: uniResult.reason,
-                    guidance: "The unilateral seal did not complete (the directory could not verify the reported root, or the certificate failed verification). Confirm your messages reached the relay (cello_list_sessions) before retrying cello_close_session.",
+                    guidance: "The unilateral seal did not complete (the directory could not verify the reported root, or the certificate failed verification). Confirm your messages reached the relay (cello_sessions) before retrying cello_close_session.",
                 };
             }
             finally {
@@ -3356,7 +3375,7 @@ export async function startDaemon(config) {
         return {
             ok: false,
             reason: "session_not_closeable",
-            guidance: `Session is in status '${record.status}', which cannot be closed via cello_close_session. Check cello_list_sessions; a seal_interrupted_pending session is awaiting FROST notarization.`,
+            guidance: `Session is in status '${record.status}', which cannot be closed via cello_close_session. Check cello_sessions; a seal_interrupted_pending session is awaiting FROST notarization.`,
         };
     });
     // ─── MCP-001: stubs for tools registered in cello-mcp.ts but not yet implemented ───
@@ -3378,7 +3397,7 @@ export async function startDaemon(config) {
         // cello-mcp forwards this as { session_id } (snake_case, matching the other session tools).
         const sessionId = params?.["session_id"];
         if (!sessionId || typeof sessionId !== "string") {
-            return { ok: false, reason: "missing_session_id", guidance: "Provide the session_id (hex) of the sealed session. Check cello_list_sessions for sealed sessions." };
+            return { ok: false, reason: "missing_session_id", guidance: "Provide the session_id (hex) of the sealed session. Check cello_sessions for sealed sessions." };
         }
         // DOD-LOOP-1: the certificate is keyed by (agent, session_id) — read the current agent's.
         const connState = perConnectionState.get(connectionId);
@@ -3410,7 +3429,7 @@ export async function startDaemon(config) {
             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.`,
+                guidance: `This session belongs to agent '${owner.name}', not the current agent '${agentName}'. Call cello_use_agent('${owner.name}') then retry cello_sealed_receipt.`,
             };
         }
         // A truncated paste: the id is a strict prefix of one of this agent's real session ids.
@@ -3421,13 +3440,13 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 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.",
+                guidance: "That looks like a truncated session id. cello_sessions and cello status show the FULL id — copy the complete id and retry.",
             };
         }
         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.",
+            guidance: "No session with this id belongs to the current agent. Run cello_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 —
@@ -3437,7 +3456,7 @@ export async function startDaemon(config) {
     handlers.set("cello_get_transcript", async (params, connectionId) => {
         const sessionId = params?.["session_id"];
         if (!sessionId || typeof sessionId !== "string") {
-            return { ok: false, reason: "missing_session_id", guidance: "Provide the session_id (hex) whose transcript to read. See cello_list_sessions." };
+            return { ok: false, reason: "missing_session_id", guidance: "Provide the session_id (hex) whose transcript to read. See cello_sessions." };
         }
         const connState = perConnectionState.get(connectionId);
         // CC-3 / M8C-AUTOSTART-1 F18: explicit { name } > this connection's current > sole online agent.
@@ -3455,7 +3474,16 @@ export async function startDaemon(config) {
         // reviewer HIGH finding (aa5928e2/a9099571): recordTranscriptMessage swallows a DB write
         // failure without rolling back the tree's leaf count, so a hole in `messages` is possible in
         // principle; the contiguous-run walk refuses to vault the cursor past such a hole even here.
-        safeCursorAdvance(connectionId, sessionId, new Set(messages.map((m) => m.sequence)));
+        const deliveredSeqs = new Set(messages.map((m) => m.sequence));
+        safeCursorAdvance(connectionId, sessionId, deliveredSeqs);
+        // DOD-CURSOR-DURABLE-1 (AC3): reading the full history IS reading — so this must advance the
+        // PERSISTED watermark too, not just this connection's in-memory cursor. Previously it advanced
+        // only the cursor, which made the gate's own guidance ("call cello_get_transcript, then retry")
+        // a dead end for any stateless client: a fresh process reads the transcript, exits, and the next
+        // process still presents an unread count. Same contiguous-run safety as the cursor — never vault
+        // past a gap (an undecryptable row is absent from `messages`, so the walk stops there and those
+        // messages correctly stay unread).
+        safeWatermarkAdvance(agentName, sessionId, deliveredSeqs);
         return { ok: true, session_id: sessionId, messages, undecryptable };
     });
     // cello_list_sessions: the discovery surface — every persisted session for the
@@ -4716,7 +4744,7 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 reason: "seal_interrupted_counterparty_unavailable",
-                guidance: "The counterparty is not currently reachable to complete the seal-interrupted flow. Retry when the counterparty is online — check their connection status via cello_list_connections.",
+                guidance: "The counterparty is not currently reachable to complete the seal-interrupted flow. Retry when the counterparty is online — check their connection status via cello_status.",
             };
         }
         // Wait for counterparty ack/rejection via the shared signaling await machinery.
@@ -4732,7 +4760,7 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 reason: "seal_interrupted_counterparty_unavailable",
-                guidance: "The counterparty is not currently reachable to complete the seal-interrupted flow. Retry when the counterparty is online — check their connection status via cello_list_connections.",
+                guidance: "The counterparty is not currently reachable to complete the seal-interrupted flow. Retry when the counterparty is online — check their connection status via cello_status.",
             };
         }
         if (ackResult.type === "seal_interrupted_rejection") {
@@ -4928,7 +4956,7 @@ export async function startDaemon(config) {
                 ok: false,
                 reason,
                 guidance: ackResult.type === "timeout"
-                    ? "The counterparty did not acknowledge the seal in time. Retry when they are online — check cello_list_connections. The session remains active and usable."
+                    ? "The counterparty did not acknowledge the seal in time. Retry when they are online — check cello_status. The session remains active and usable."
                     : "The counterparty rejected the seal request. Their session state may be inconsistent. Ask them to check cello status before retrying.",
             };
         }
@@ -5003,7 +5031,7 @@ export async function startDaemon(config) {
         // DOD-LOOP-1: the (agent, session_id) lookup is itself the ownership scope.
         const record = sessionNodeManager.getSessionRecord(agentName, sessionId);
         if (!record) {
-            return { ok: false, reason: "session_not_found", guidance: "No session found with this ID. Check cello_list_sessions for active sessions." };
+            return { ok: false, reason: "session_not_found", guidance: "No session found with this ID. Check cello_sessions for active sessions." };
         }
         if (record.agent_name !== agentName) {
             return { ok: false, reason: "session_not_owned", guidance: "This session belongs to a different agent. Call cello_use_agent to switch to the agent that owns it, then retry." };
@@ -5019,18 +5047,57 @@ export async function startDaemon(config) {
         // rather than let it send blind — the WhatsApp-group-chat model. Runs BEFORE M9's
         // governance-decisions parsing below — an access-control gate should short-circuit before any
         // unrelated prep work for a send that may not even be allowed to proceed.
+        // DOD-CURSOR-DURABLE-1: the gate now consults TWO authorities and passes if EITHER says the
+        // caller is caught up.
+        //
+        //   1. the connection cursor (in-memory, per-connection) — today's rule, UNCHANGED. A
+        //      long-lived client (the MCP shim, one socket for the whole session) satisfies this
+        //      exactly as before, so the shipped single-connection path is byte-for-byte identical.
+        //
+        //   2. the persisted per-(agent, session) read watermark — NEW. A STATELESS client (the `cello`
+        //      CLI runs a fresh process, and therefore a fresh connection, per command) always presents
+        //      cursor -1, so authority 1 can never be satisfied by it: after the counterparty spoke
+        //      once, every CLI send was refused forever, even though the agent had demonstrably read
+        //      the message. That made a two-way conversation impossible from bash — and it silently hit
+        //      any RECONNECTING MCP client too, whose fresh connectionId also resets the cursor to -1.
+        //
+        // What the gate protects, precisely: an agent must never reply to COUNTERPARTY content nobody
+        // on its side has seen. That guarantee is preserved and is now durable — it survives the socket.
+        //
+        // What it deliberately no longer protects (the approved trade — see
+        // 2026-07-11_cursor-durable-read-before-write-design.md §6, Andre's go): a message this agent
+        // SENT from a DIFFERENT local connection no longer blocks. Two attended windows on one agent
+        // used to gate each other; now they do not, because a locally-authored message is not "unread
+        // counterparty content" — the AGENT wrote it. The principal here is the agent, not the socket,
+        // and the daemon cannot referee which of an operator's own windows a human is looking at.
         const currentSeq = record.message_count - 1;
-        const lastReadSeq = getConnectionCursor(connectionId, sessionId);
-        if (lastReadSeq < currentSeq) {
+        const connectionCursor = getConnectionCursor(connectionId, sessionId);
+        const unreadReceived = sessionNodeManager.getUnreadReceivedCount(agentName, sessionId);
+        const caughtUp = connectionCursor >= currentSeq || unreadReceived === 0;
+        if (!caughtUp) {
             // M8C-CURSOR-1 (reviewer MEDIUM fix): every sibling rejection in this handler logs; this
             // gate must too — a security-relevant control-flow path with no observability is a gap.
-            logger.warn("session.send.blocked", { sessionId, currentSeq, lastReadSeq, connectionId });
+            // Both authorities are logged, so the next reader can tell WHICH one refused.
+            logger.warn("session.send.blocked", {
+                sessionId,
+                currentSeq,
+                lastReadSeq: connectionCursor,
+                unreadReceived,
+                connectionId,
+                agentName,
+            });
             return {
                 ok: false,
                 reason: "session_not_current",
                 current_seq: currentSeq,
-                last_read_seq: lastReadSeq,
-                guidance: `This connection hasn't caught up on session ${sessionId} — ${currentSeq - lastReadSeq} message(s) unread (this may include messages authored by another connection on this same agent). Call cello_get_transcript to read the full history (covers both sent and received), then retry the send.`,
+                last_read_seq: connectionCursor,
+                unread_received: unreadReceived,
+                // DOD-ONBOARD-HELP-1 §5: say what is wrong and what to do, in that order, in plain words.
+                // The old text opened with the internal noun ("this agent hasn't read…"); a refused send is
+                // the most common wall a new operator hits, so it leads with the COUNT and the FIX. The
+                // session id is interpolated so the remedy is copy-pasteable, not a template to fill in.
+                // Rendered per surface at the IPC boundary — a CLI caller sees `cello receive <id>`.
+                guidance: `${unreadReceived} unread message(s) — run cello_receive ${sessionId} first to read them, then send again. (Or cello_transcript ${sessionId} for the whole conversation.) You are blocked from replying to something you haven't read.`,
             };
         }
         // M9-FEED-001 §6: the agent's governance re-send decisions, keyed by the flagId a prior `warn`
@@ -5153,7 +5220,7 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 reason: sendResult.reason,
-                guidance: "The content could not be delivered over the session stream right now. It has been queued in the durable retry queue and will be retried when the counterparty reconnects. The session remains usable — check cello_list_connections for the counterparty's status.",
+                guidance: "The content could not be delivered over the session stream right now. It has been queued in the durable retry queue and will be retried when the counterparty reconnects. The session remains usable — check cello_status for the counterparty's status.",
             };
         }
         // Delivered directly OR dispatched to relay (DOD-LEAVEMSG-1) — either way the content is now
@@ -5252,7 +5319,7 @@ export async function startDaemon(config) {
         let transcriptOnly = false;
         if (!record) {
             if (sessionNodeManager.readTranscript(agentName, sessionId).messages.length === 0) {
-                return { ok: false, reason: "session_not_found", guidance: "No session found with this ID. Check cello_list_sessions." };
+                return { ok: false, reason: "session_not_found", guidance: "No session found with this ID. Check cello_sessions." };
             }
             transcriptOnly = true;
         }
@@ -5299,7 +5366,7 @@ export async function startDaemon(config) {
             return {
                 ok: false,
                 reason: "session_not_live",
-                guidance: "This session exists only as a durable transcript (no live session — it was never established or predates this daemon). Read it with cello_receive { since_seq } (e.g. since_seq: -1 for everything) or cello_get_transcript.",
+                guidance: "This session exists only as a durable transcript (no live session — it was never established or predates this daemon). Read it with cello_receive { since_seq } (e.g. since_seq: -1 for everything) or cello_transcript.",
             };
         }
         const rawTimeout = params?.timeout_ms;
@@ -5340,8 +5407,8 @@ export async function startDaemon(config) {
                     ...(sealedRoot ? { sealed_root: sealedRoot } : {}),
                     unread_count: terminal.unreadCount,
                     guidance: terminal.unreadCount > 0
-                        ? `The session has been sealed by both parties. ${terminal.unreadCount} message(s) arrived that were not read live — call cello_get_transcript to retrieve the full sealed history. No further actions are required on this session.`
-                        : "The session has been sealed by both parties. The full history is available via cello_get_transcript. No further actions are required on this session.",
+                        ? `The session has been sealed by both parties. ${terminal.unreadCount} message(s) arrived that were not read live — call cello_transcript to retrieve the full sealed history. No further actions are required on this session.`
+                        : "The session has been sealed by both parties. The full history is available via cello_transcript. No further actions are required on this session.",
                 };
             }
             // 3) Out of time — non-blocking-equivalent empty answer.
@@ -5359,7 +5426,7 @@ export async function startDaemon(config) {
                         guidance: "The counterparty's session connection has dropped (liveness: gone) — it may have crashed or gone offline. No more content will arrive on the direct path. Call cello_close_session to seal the session; if the counterparty never co-closes, a unilateral seal becomes available after the directory's delivery-grace window.",
                     };
                 }
-                return { ok: true, content: null, guidance: "No content arrived within timeout_ms. Call cello_receive again to keep waiting, or read cello_get_transcript for the full session history." };
+                return { ok: true, content: null, guidance: "No content arrived within timeout_ms. Call cello_receive again to keep waiting, or read cello_transcript for the full session history." };
             }
             await new Promise((r) => setTimeout(r, Math.min(20, remaining)));
         }
@@ -5416,6 +5483,11 @@ export async function startDaemon(config) {
                 noticed_at: n.noticed_at,
                 // Names the contact by the operator's OWN pet name (AC3); the self-declared name is a quoted,
                 // untrusted claim; the adopt command carries its arguments so it is copy-pasteable.
+                // The MCP call form below is translated WHOLE (arguments and all) for a CLI caller by
+                // vocabulary.ts's CALL_FORMS — rewriting only the tool name would leave the tool's JSON
+                // bolted onto a CLI verb, which looks like a command and is not one. `claimed_name` above
+                // carries the peer's self-declared name UNTOUCHED, so the operator always has the raw value
+                // even though the prose copy passes through the renderer.
                 notice: `Your contact ${n.moniker !== null ? `"${n.moniker}" ` : ""}(${n.pubkey.slice(0, 16)}…) now calls themselves ` +
                     `"${n.offered_name}" (self-declared — unverified). Adopt it: cello_contact_set_moniker ` +
                     `{ pubkey: "${n.pubkey}", moniker: "${n.offered_name}" }, or ignore.`,
@@ -5433,6 +5505,30 @@ export async function startDaemon(config) {
     // M8C-CONTACT-1: cello contact add/remove/list [--agent <name>]. All three resolve the target
     // agent the same way — an explicit params.agent, else this connection's current/sole-online
     // agent (F18) — so a CLI/AI operator gets the same no_current_agent guidance INBOX already uses.
+    /**
+     * Review finding 7 — a contact pubkey must LOOK like a pubkey, or the row can never work.
+     *
+     * The address-book handlers took `params.pubkey` as any string and stored it. So
+     * `cello contact tier add` — a plausible slip under the new `contact <pubkey> <op>` shape, where
+     * the FIRST positional is the pubkey — persisted a contact whose pubkey is the literal text
+     * "tier", and answered ok:true. Nothing would ever match it: it is not a key, so it can never be
+     * a counterparty. The operator is told they added someone; they added a typo.
+     *
+     * A key is 32 bytes, hex: 64 characters. Anything else is refused, loudly, with the value echoed
+     * so the slip is obvious. Returns null when the pubkey is absent — the caller's own
+     * missing_params check owns that case and says something more useful.
+     */
+    function invalidPubkey(pubkey) {
+        if (pubkey === undefined)
+            return null; // absent → the caller's missing_params check owns it
+        if (/^[0-9a-fA-F]{64}$/.test(pubkey))
+            return null;
+        return {
+            ok: false,
+            reason: "invalid_pubkey",
+            guidance: `'${pubkey}' is not a public key. A CELLO public key is 64 hex characters (32 bytes). Nothing was changed — storing it would create an address-book entry that can never match anyone. Note the argument order is 'cello contact <pubkey> <operation>'.`,
+        };
+    }
     function resolveContactAgent(connState, params) {
         const explicit = typeof params?.agent === "string" ? params.agent : undefined;
         if (explicit)
@@ -5449,6 +5545,9 @@ export async function startDaemon(config) {
     }
     handlers.set("cello_contact_add", async (params, connectionId) => {
         const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
+        const badPubkey = invalidPubkey(pubkey);
+        if (badPubkey)
+            return badPubkey;
         if (!pubkey) {
             return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) — the contact to add." };
         }
@@ -5486,6 +5585,9 @@ export async function startDaemon(config) {
     // key is NOT a clear (Entry-66-F3): a request that omits it is malformed and rejected.
     handlers.set("cello_contact_set_moniker", async (params, connectionId) => {
         const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
+        const badPubkey = invalidPubkey(pubkey);
+        if (badPubkey)
+            return badPubkey;
         if (!pubkey || !params || !("moniker" in params)) {
             return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) and 'moniker' — a string to set the pet name, or null to clear it." };
         }
@@ -5511,6 +5613,9 @@ export async function startDaemon(config) {
     // (0..4) — an unknown value is REFUSED, never coerced. Emits contact.tier.changed (old→new).
     handlers.set("cello_contact_set_tier", async (params, connectionId) => {
         const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
+        const badPubkey = invalidPubkey(pubkey);
+        if (badPubkey)
+            return badPubkey;
         const tier = typeof params?.tier === "number" ? params.tier : undefined;
         if (!pubkey || tier === undefined) {
             return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) and 'tier' (0=blocked, 1=unknown, 2=known, 3=whitelisted, 4=vip)." };
@@ -5536,6 +5641,9 @@ export async function startDaemon(config) {
     // on the outbound path at send time (SI), never here.
     handlers.set("cello_contact_set_away", async (params, connectionId) => {
         const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
+        const badPubkey = invalidPubkey(pubkey);
+        if (badPubkey)
+            return badPubkey;
         if (!pubkey || !params || !("message" in params)) {
             return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) and 'message' — a string away text, or null to clear it." };
         }
@@ -5559,6 +5667,11 @@ export async function startDaemon(config) {
         return { ok: true, agent: resolved.agent, pubkey };
     });
     handlers.set("cello_contact_remove", async (params, connectionId) => {
+        // Deliberately NOT shape-gated. `remove` is the ESCAPE HATCH, and gating it would trap the very
+        // rows the gate exists to prevent: a junk contact written by the older, unvalidated code (pubkey
+        // = the literal text "tier") could never be deleted, because deleting it requires naming it.
+        // Validation belongs on the paths that CREATE or MUTATE a row, never on the one that removes it.
+        // Removing a key that was never stored is a harmless not_found.
         const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
         if (!pubkey) {
             return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) — the contact to remove." };
@@ -5653,7 +5766,7 @@ export async function startDaemon(config) {
         }
         const store = new DbIdentityStore(sessionNodeManager.getDb(), logger);
         if (!store.setMoniker(resolved.agent, moniker)) {
-            return { ok: false, reason: "agent_not_found", guidance: `No active agent named '${resolved.agent}'. See cello_list_agents.` };
+            return { ok: false, reason: "agent_not_found", guidance: `No active agent named '${resolved.agent}'. See cello_agents.` };
         }
         logger.info("agent.moniker.set", { agentName: resolved.agent, cleared: moniker === null });
         return { ok: true, agent: resolved.agent, moniker };
@@ -5683,8 +5796,28 @@ export async function startDaemon(config) {
         }
         return { acknowledged: true };
     });
+    // DOD-ONBOARD-HELP-1 §5 — render every response for the surface that asked.
+    //
+    // The daemon is where an operator actually MEETS the tool names: a refused send says "call
+    // cello_receive first". Those strings are written with the canonical MCP names, so an MCP caller
+    // gets them verbatim — but a CLI caller must be told `cello receive`, the thing they can type.
+    // (P2-7 was the one-off report of this; it is a whole CLASS, and this closes the class.)
+    //
+    // Wrapping the handler map is the ONE choke point that has both the response and the connection's
+    // clientType. Doing it per-handler would mean 60+ call sites, and the 61st would forget.
+    const renderedHandlers = new Map();
+    for (const [method, handler] of handlers) {
+        renderedHandlers.set(method, async (params, connectionId) => {
+            const result = await handler(params, connectionId);
+            // Default to "cli": a connection that never sent ipc.connect has no recorded surface, and the
+            // CLI verb is the safe answer — it is at least a real command an operator can run, whereas an
+            // MCP tool name is useless in a terminal.
+            const surface = perConnectionState.get(connectionId)?.clientType === "mcp" ? "mcp" : "cli";
+            return renderForSurface(result, surface);
+        });
+    }
     // Create and start IPC server
-    const ipcServer = createIpcServer({ socketPath, maxConnections, logger }, handlers);
+    const ipcServer = createIpcServer({ socketPath, maxConnections, logger }, renderedHandlers);
     try {
         await ipcServer.start();
     }