@cello-protocol/daemon 0.0.47 → 0.0.49

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,CAy8L7E"}
+{"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,CAkhM7E"}

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";
@@ -1797,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
@@ -1874,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;
@@ -1984,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;
@@ -2082,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
@@ -2113,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) {
@@ -2166,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) {
@@ -2219,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." };
@@ -2273,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);
@@ -2903,9 +2904,13 @@ export async function startDaemon(config) {
     // NOTE: cello_await_session is NOT in this stub list — Seam 2 registers a real
     // handler for it below (inbound session establishment), with its own inline
     // no_current_agent guard.
-    // F1-a2: cello_receive_session is NO LONGER stubbed here — it is registered below as a true
-    // alias of the real (blocking) cello_receive handler. Kept as an (empty) extension point for
-    // future tools that need the plain no_current_agent guard without their own handler.
+    // DOD-ONBOARD-HELP-1: cello_receive_session is DELETED (Andre, 2026-07-11). It was a literal
+    // alias — the same handler object as cello_receive — that claimed an "accept/join" step CELLO
+    // does not have (inbound sessions are auto-accepted by the standing receiver). No alias, no
+    // deprecated shim, no dead handler.
+    //
+    // The list below stays as an (empty) extension point: a future tool that needs only the plain
+    // no_current_agent guard, with no handler of its own, is registered here.
     const SESSION_TOOLS_REQUIRING_AGENT = [];
     const NO_CURRENT_AGENT_RESPONSE = {
         ok: false,
@@ -3092,7 +3097,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),
@@ -3101,7 +3106,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
@@ -3109,7 +3114,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
@@ -3354,7 +3359,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 {
@@ -3374,7 +3379,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 ───
@@ -3396,7 +3401,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);
@@ -3428,7 +3433,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.
@@ -3439,13 +3444,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 —
@@ -3455,7 +3460,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.
@@ -4743,7 +4748,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.
@@ -4759,7 +4764,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") {
@@ -4955,7 +4960,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.",
             };
         }
@@ -5030,7 +5035,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." };
@@ -5091,7 +5096,12 @@ export async function startDaemon(config) {
                 current_seq: currentSeq,
                 last_read_seq: connectionCursor,
                 unread_received: unreadReceived,
-                guidance: `This agent hasn't read ${unreadReceived} received message(s) on session ${sessionId}. Call cello_receive (or cello_get_transcript for the full history) to read them, then retry the send.`,
+                // 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`
@@ -5214,7 +5224,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
@@ -5286,11 +5296,14 @@ export async function startDaemon(config) {
     });
     // ─── CELLO-M7-DAEMON-004 / F1-a: cello_receive (BLOCKING, session-scoped) ────────
     // F1-a fix: the daemon port had dropped the blocking receive (the handler was a
-    // non-blocking buf.shift and cello_receive_session was a not_implemented stub). It now
-    // BLOCKS up to timeout_ms, polling the received-content buffer — resolved by the next
-    // arrival, a terminal seal answer (F1-b), or timeout. This is the "blocking receive
-    // variant" the guidance names. Registered under both cello_receive and cello_receive_session
-    // (F1-a2: one implementation, both names — the redundant tools are collapsed).
+    // non-blocking buf.shift). It now BLOCKS up to timeout_ms, polling the received-content
+    // buffer — resolved by the next arrival, a terminal seal answer (F1-b), or timeout. This is
+    // the "blocking receive variant" the guidance names.
+    //
+    // ONE name (DOD-ONBOARD-HELP-1, Andre 2026-07-11). This was briefly registered under
+    // `cello_receive_session` as well — one implementation behind two names. That alias is DELETED:
+    // it accepted or joined nothing (inbound sessions are auto-accepted by the standing receiver),
+    // so it was a second name for a step that does not exist, and its help said otherwise.
     const RECEIVE_DEFAULT_TIMEOUT_MS = 30000; // matches the cello-mcp shim's documented default
     const handleReceive = async (params, connectionId) => {
         const connState = perConnectionState.get(connectionId);
@@ -5313,7 +5326,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;
         }
@@ -5360,7 +5373,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;
@@ -5401,8 +5414,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.
@@ -5420,13 +5433,12 @@ 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)));
         }
     };
     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,
@@ -5477,6 +5489,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.`,
@@ -5494,6 +5511,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)
@@ -5510,6 +5551,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." };
         }
@@ -5547,6 +5591,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." };
         }
@@ -5572,6 +5619,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)." };
@@ -5597,6 +5647,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." };
         }
@@ -5620,6 +5673,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." };
@@ -5714,7 +5772,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 };
@@ -5744,8 +5802,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();
     }