@cello-protocol/daemon 0.0.52 → 0.0.54

package/dist/session-content-handlers.js

@@ -0,0 +1,436 @@
+/**
+ * cello_send and cello_receive — the content path.
+ *
+ * The two biggest handlers in the daemon, and the two I had put on a DO-NOT-CUT list. That list was
+ * written before anything had been measured, and it was wrong: these close over eleven things, not
+ * the whole daemon. They are listed below, which is the point of the move.
+ *
+ * They stay TOGETHER because they are two halves of one state machine — the read cursor. cello_send
+ * appends to the daemon-owned tree; cello_receive advances the per-connection cursor and the durable
+ * watermark. Splitting them would put the cursor's writer and its reader in different modules.
+ */
+import { randomUUID, createHash } from "node:crypto";
+import { MAX_CONTENT_BYTES } from "@cello-protocol/protocol-types";
+import { TIER } from "./contacts-tier-migration.js";
+import { GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT } from "@cello-protocol/gateway";
+export function registerSessionContentHandlers(deps) {
+    const { handlers, logger, sessionNodeManager, securityGateway, retryQueue, getConnState, resolveCurrentAgent, NO_CURRENT_AGENT_RESPONSE, getConnectionCursor, advanceConnectionCursor, safeCursorAdvance, clearTelegramRung, } = deps;
+    // ─── CELLO-M7-DAEMON-004: cello_send (live send + daemon-owned tree append) ──
+    handlers.set("cello_send", async (params, connectionId) => {
+        const connState = getConnState(connectionId);
+        // CC-3 / M8C-AUTOSTART-1 F18: explicit { agent } > current > sole online agent.
+        const agentName = resolveCurrentAgent(connState, params?.agent);
+        if (!agentName)
+            return NO_CURRENT_AGENT_RESPONSE;
+        // round-2 BLOCKING: read the snake_case public field cello-mcp.ts actually sends.
+        const sessionId = params?.session_id;
+        const contentStr = typeof params?.content === "string" ? params.content : undefined;
+        if (!sessionId || contentStr === undefined) {
+            return { ok: false, reason: "missing_params", guidance: "Provide 'session_id' (hex) and 'content' (string) parameters." };
+        }
+        // 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_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." };
+        }
+        if (record.status !== "active") {
+            return { ok: false, reason: "session_not_active", guidance: `Session is '${record.status}', not active. Content can only be sent on an active session. If it is interrupted, call cello_close_session to seal it.` };
+        }
+        // M8C-CURSOR-1: read-before-write gate. current_seq is the tree's highest leaf index
+        // (message_count is kept in sync with leafCount on every append, both directions — DAEMON-004
+        // finding #2), so it reflects EVERY message in the session regardless of which connection sent
+        // or received it. If this connection hasn't read up to current_seq (e.g. a second attended
+        // session on the same agent that hasn't polled since the other connection's last send), refuse
+        // rather than let it send blind — the WhatsApp-group-chat model. Runs BEFORE the
+        // governance-decisions parsing below: an access-control gate must short-circuit before any
+        // unrelated prep work for a send that may not be allowed to proceed at all.
+        //
+        // The gate consults TWO authorities and passes if EITHER says the caller is caught up:
+        //
+        //   1. the connection cursor (in-memory, per-connection) — satisfied by a long-lived client
+        //      like the MCP shim, which holds one socket for the whole session.
+        //
+        //   2. the persisted per-(agent, session) read watermark. A STATELESS client CANNOT satisfy
+        //      authority 1: the `cello` CLI runs a fresh process, and therefore a fresh connection, per
+        //      command, so it always presents cursor -1. Without the watermark, every CLI send is
+        //      refused forever once the counterparty has spoken — as is every send from a RECONNECTING
+        //      MCP client, whose new connectionId also resets the cursor to -1. Do not remove it.
+        //
+        // What the gate protects, precisely: an agent must never reply to COUNTERPARTY content nobody
+        // on its side has seen. That guarantee is durable — it survives the socket.
+        //
+        // What it deliberately does NOT protect: a message this agent SENT from a different local
+        // connection does not block. Two attended windows on one agent do not gate each other, because
+        // locally-authored content is not "unread counterparty content" — the AGENT wrote it. The
+        // principal is the agent, not the socket, and the daemon cannot referee which of an operator's
+        // own windows a human is looking at. This is deliberate; do not "fix" it.
+        const currentSeq = record.message_count - 1;
+        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.
+            // 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: 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`
+        // returned. Optional; validated shape only (the gateway re-scans + applies them, INV-4). A
+        // malformed map is ignored rather than failing the send (the gateway will just re-warn).
+        const rawDecisions = params?.governance_decisions;
+        let governanceDecisions;
+        if (rawDecisions && typeof rawDecisions === "object" && !Array.isArray(rawDecisions)) {
+            const valid = {};
+            for (const [k, v] of Object.entries(rawDecisions)) {
+                if (v === "redact" || v === "allow_once" || v === "allow_always")
+                    valid[k] = v;
+            }
+            if (Object.keys(valid).length > 0)
+                governanceDecisions = valid;
+        }
+        const correlationId = randomUUID();
+        const contentBytes = new TextEncoder().encode(contentStr);
+        // CELLO-M7-MSG-001 (AC-013/AC-018/AC-021): enforce the 1 MB application content cap
+        // BEFORE any transmission or hash/leaf production. This replaces the silent oversize
+        // decode-failure → desync: the send is rejected with a distinct, diagnosable reason
+        // and actionable guidance; no content frame is transmitted, no leaf is appended, and
+        // the session stays usable.
+        if (contentBytes.length > MAX_CONTENT_BYTES) {
+            logger.warn("content.rejected.too_large", {
+                sessionId,
+                contentSize: contentBytes.length,
+                cap: MAX_CONTENT_BYTES,
+                correlationId,
+            });
+            return {
+                ok: false,
+                reason: "content_too_large",
+                guidance: `This message is ${contentBytes.length} bytes, over the ${MAX_CONTENT_BYTES}-byte (1 MB) per-message content cap. Split it into multiple messages each under the cap, or use the large-object/file transfer path for large payloads (not cello_send). Nothing was sent and the session is still active — retry with smaller content.`,
+            };
+        }
+        const recipientPubkey = record.counterparty_pubkey;
+        // M9 outbound screening seam (INV-5/SI-001). Screen BEFORE anything reaches the wire. The
+        // gateway verdict drives the four cello_send outcomes (M9-FEED-001): block / warn → NOT sent;
+        // allow → sent as-is; redact → sent in ALTERED form. A configured-but-unreachable gateway fails
+        // closed (block, gateway_unavailable), so a screening outage can never let content out ungated.
+        const outboundVerdict = await securityGateway.screenOutbound(contentBytes, {
+            direction: "outbound",
+            agentName: record.agent_name,
+            sessionId,
+            correlationId,
+            ...(governanceDecisions !== undefined ? { governanceDecisions } : {}),
+        });
+        if (outboundVerdict.disposition === "block") {
+            if (outboundVerdict.reason === GOVERNANCE_TIMEOUT) {
+                logger.error("security.gateway.timeout", { sessionId, reason: outboundVerdict.reason, correlationId });
+            }
+            else if (outboundVerdict.reason === GATEWAY_UNAVAILABLE) {
+                logger.error("security.gateway.unavailable", { direction: "outbound", reason: outboundVerdict.reason, correlationId });
+            }
+            else {
+                logger.info("security.verdict.returned", { disposition: "block", sessionId, reason: outboundVerdict.reason, correlationId });
+            }
+            return {
+                ok: false,
+                reason: outboundVerdict.reason ?? "blocked_by_governance",
+                guidance: outboundVerdict.guidance ??
+                    "This message was blocked by the security gateway and was NOT sent. The session is still active.",
+                blocks: (outboundVerdict.events ?? []).filter((e) => e.disposition === "block"),
+            };
+        }
+        if (outboundVerdict.disposition === "warn") {
+            logger.info("security.verdict.returned", { disposition: "warn", sessionId, correlationId });
+            return {
+                ok: false,
+                reason: "governance_warn",
+                guidance: outboundVerdict.guidance ??
+                    "This message was held for a governance decision and was NOT sent. Re-send the same content with a " +
+                        "governance_decisions map ({flagId: redact | allow_once | allow_always}) to resolve each flagged item.",
+                flags: (outboundVerdict.events ?? []).filter((e) => e.disposition === "warn"),
+            };
+        }
+        // FAIL-CLOSED (code-review MED): a `redact` verdict MUST carry the redacted content. If it ever
+        // arrives without it, sending the original `contentBytes` would leak the pre-redaction draft — the
+        // one place M9 could fail OPEN. Treat it as a block, never an allow-original. (Unreachable today:
+        // the gateway always includes content on redact; this is the defensive floor.)
+        if (outboundVerdict.disposition === "redact" && outboundVerdict.content === undefined) {
+            logger.error("security.verdict.redact_without_content", { sessionId, correlationId });
+            return {
+                ok: false,
+                reason: "redact_without_content",
+                guidance: "The security gateway returned a redact verdict without the redacted content. To avoid " +
+                    "leaking the original, nothing was sent. This is a gateway fault — check the gateway logs and retry.",
+            };
+        }
+        // allow or redact → send. On redact the ALTERED bytes are what go on the wire AND what the leaf
+        // hash binds — the transcript records what was actually sent, not the pre-redaction draft.
+        const modified = outboundVerdict.disposition === "redact" && outboundVerdict.content !== undefined;
+        const sendBytes = modified ? new Uint8Array(outboundVerdict.content) : contentBytes;
+        const contentHash = createHash("sha256").update(new Uint8Array([0x00])).update(sendBytes).digest();
+        const contentHashHex = Buffer.from(contentHash).toString("hex");
+        const sendResult = await sessionNodeManager.sendContent(record.agent_name, sessionId, sendBytes, new Uint8Array(contentHash), correlationId);
+        if (!sendResult.ok) {
+            // DB-001 / dead-channel contract: never silently drop, never desync. Preserve
+            // the content in the durable retry_queue so it is retried on reconnect, and
+            // surface a named, diagnosable failure.
+            const nonce = randomUUID();
+            try {
+                retryQueue.enqueue(sessionId, new TextEncoder().encode(nonce), sendBytes);
+            }
+            catch (err) {
+                logger.error("session.content.queue.failed", {
+                    sessionId,
+                    error: err instanceof Error ? err.message : String(err),
+                    correlationId,
+                });
+            }
+            logger.warn("session.content.send.failed", {
+                sessionId,
+                recipientPubkey,
+                reason: sendResult.reason,
+                errorMessage: sendResult.error,
+                correlationId,
+            });
+            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_status for the counterparty's status.",
+            };
+        }
+        // Delivered directly OR dispatched to relay (DOD-LEAVEMSG-1) — either way the content is now
+        // part of the daemon-owned tree: the relay witness (R1) already assigned it a sequence before
+        // direct delivery was even attempted, so a parked message occupies the SAME leaf position it
+        // would have taken if delivered live. Append once, for both outcomes.
+        const { leafIndex, newRootHex } = sessionNodeManager.appendSessionLeaf(record.agent_name, sessionId, "msg", contentHashHex, correlationId);
+        // DOD-LOG-1: persist the readable SENT plaintext to the durable transcript, keyed by the
+        // canonical leaf sequence so it joins the committed hash chain (survives restart).
+        // M9 merge fix: use sendBytes (the ALTERED bytes on a redact verdict), never the pre-redaction
+        // contentBytes — the leaf hash above already binds sendBytes; the transcript must match what
+        // actually went on the wire, not the pre-redaction draft (M9's own stated seam invariant).
+        sessionNodeManager.recordTranscriptMessage(record.agent_name, sessionId, leafIndex, "sent", sendBytes, correlationId);
+        // M8C-CURSOR-1: the sender authored this leaf — advance ITS OWN cursor so it doesn't get
+        // blocked by session_not_current on its own just-sent message.
+        advanceConnectionCursor(connectionId, sessionId, leafIndex);
+        void newRootHex;
+        // CC-1 (2026-07-07): operator engagement promotes the counterparty to a known contact. A
+        // committed reply — past the read-before-write gate, content now on the wire AND in the tree —
+        // IS the operator choosing to trust this sender; the inbound-accept path deliberately no longer
+        // auto-adds (that defeated screening + anti-spam). For an OUTBOUND session the counterparty is
+        // already a contact (cello_initiate_session added it), so this is an idempotent no-op there; it
+        // matters for inbound-originated sessions, where the reply is the trust signal. addContact is
+        // INSERT OR IGNORE — it never refreshes added_at. DOD-TIER-4 AC3: engaging (a committed reply into
+        // an inbound session I accepted) makes the counterparty KNOWN, provenance 'accepted'. For an
+        // OUTBOUND session the row already exists ('initiated', KNOWN) and INSERT OR IGNORE leaves it
+        // untouched — 'initiated' correctly wins there.
+        sessionNodeManager.addContact(record.agent_name, recipientPubkey, undefined, "accepted", TIER.KNOWN);
+        if (modified) {
+            logger.info("security.verdict.returned", { disposition: "redact", sessionId, sequenceNumber: leafIndex, correlationId });
+        }
+        if (!sendResult.delivered) {
+            // DOD-LEAVEMSG-1 (sender half): direct delivery failed but the sealed, hashed content was
+            // successfully deposited at the relay (pickup_queue) — this is a SUCCESS outcome, not a
+            // failure. The recipient's daemon pulls it via RELAYWAKE on next reconnect. Reporting this
+            // as ok:false (the pre-LEAVEMSG-1 behavior) misrepresented an in-flight message as lost.
+            logger.info("session.content.dispatched_to_relay", {
+                sessionId,
+                recipientPubkey,
+                contentHashHex,
+                sequenceNumber: leafIndex,
+                correlationId,
+            });
+            return {
+                ok: true,
+                sequence_number: leafIndex,
+                delivered: false,
+                reason: "dispatched_to_relay",
+                modified,
+                guidance: "The counterparty is not directly reachable right now, so this message was sealed and dispatched to relay store-and-forward. It will be delivered the next time the counterparty's daemon reconnects — no further action is needed.",
+                ...(modified ? { transformations: (outboundVerdict.events ?? []).filter((e) => e.disposition === "redact") } : {}),
+            };
+        }
+        logger.info("session.content.sent", {
+            sessionId,
+            recipientPubkey,
+            contentHashHex,
+            sequenceNumber: leafIndex,
+            correlationId,
+        });
+        return {
+            ok: true,
+            sequence_number: leafIndex,
+            delivered: true,
+            modified,
+            // On a redact, tell the agent exactly what was transformed (the §6 sender-side surface).
+            ...(modified ? { transformations: (outboundVerdict.events ?? []).filter((e) => e.disposition === "redact") } : {}),
+        };
+    });
+    // ─── 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). 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 = getConnState(connectionId);
+        // CC-3 / M8C-AUTOSTART-1 F18: explicit { agent } > current > sole online agent.
+        const agentName = resolveCurrentAgent(connState, params?.agent);
+        if (!agentName)
+            return NO_CURRENT_AGENT_RESPONSE;
+        // Read the snake_case public field cello-mcp.ts actually sends.
+        const sessionId = params?.session_id;
+        if (!sessionId) {
+            return { ok: false, reason: "missing_params", guidance: "Provide 'session_id' (hex) to receive content for a specific session." };
+        }
+        const record = sessionNodeManager.getSessionRecord(agentName, sessionId);
+        // DOD-UNREAD-1 D4b: a TRANSCRIPT-ONLY session — received rows exist but no sessions row (the
+        // pre-D3/D4a phantom residue: the counterparty's reply landed while this side refused the
+        // session). Those rows are counted unread by getUnreadSummary, so cello_receive MUST be able
+        // to read them or the badge can never clear. Reading is a transcript operation: the since_seq
+        // catch-up below works from the durable transcript alone. Only a session with NEITHER a row
+        // NOR transcript rows is truly not found.
+        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_sessions." };
+            }
+            transcriptOnly = true;
+        }
+        // (D4 review F3: the old `record.agent_name !== agentName` → session_not_owned branch was dead
+        // code — getSessionRecord is keyed by (agent_name, session_id), so a record can never belong to
+        // a different agent. A cross-agent session id simply has no record under this agent.)
+        // M8C-SINCESEQ-1: stateless catch-up. When since_seq is provided, return a BATCH of received
+        // transcript messages with sequence > since_seq (durable transcript, not the ephemeral buffer —
+        // so concurrent arrivals don't shift what a given since_seq returns; no replay race). Replaces
+        // the cello_get_transcript workaround for away-then-return. Received-direction only (the messages
+        // you'd have gotten live). Advances the read watermark (delivery marks read — clears INBOX
+        // unread). A distinct early branch: the plain (no since_seq) receive is entirely unchanged.
+        const rawSince = params?.since_seq;
+        if (typeof rawSince === "number" && Number.isFinite(rawSince)) {
+            const sinceSeq = rawSince;
+            // D4b AC2: a transcript-only session has no record to attribute from — `from` is null,
+            // NEVER the string "unknown" (the transcript stores no counterparty; don't invent one).
+            const from = record ? record.counterparty_pubkey : null;
+            const { messages } = sessionNodeManager.readTranscript(agentName, sessionId);
+            const received = messages.filter((m) => m.direction === "received" && m.sequence > sinceSeq);
+            if (received.length > 0) {
+                // readTranscript is ordered by sequence ASC → the last is the max.
+                const maxSeq = received[received.length - 1].sequence;
+                sessionNodeManager.advanceLastDeliveredSeq(agentName, sessionId, maxSeq);
+                clearTelegramRung(agentName, sessionId); // M8C-TGDOOR-1: read clears the ring
+            }
+            // M8C-CURSOR-1 (reviewer HIGH fix): only advance through the CONTIGUOUS run this batch
+            // actually delivered — if a sent leaf from another local connection sits in a gap, this
+            // correctly refuses to advance past it (cello_get_transcript is still required to catch up).
+            safeCursorAdvance(connectionId, sessionId, new Set(received.map((m) => m.sequence)));
+            logger.info("session.receive.since_seq", { sessionId, agentName, since_seq: sinceSeq, count: received.length });
+            return {
+                ok: true,
+                since_seq: sinceSeq,
+                count: received.length,
+                messages: received.map((m) => ({ sequence: m.sequence, content: m.text, from })),
+            };
+        }
+        // D4b AC3: the plain (blocking) receive waits on a LIVE session's buffer — a transcript-only
+        // session has no live node and nothing will ever arrive. Waiting to a null timeout would be
+        // misleading and session_not_found would be a lie (the transcript exists). A distinct reason
+        // points the caller at the read that works.
+        if (transcriptOnly) {
+            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_transcript.",
+            };
+        }
+        const rawTimeout = params?.timeout_ms;
+        const timeoutMs = typeof rawTimeout === "number" && Number.isFinite(rawTimeout) && rawTimeout >= 0
+            ? rawTimeout
+            : RECEIVE_DEFAULT_TIMEOUT_MS;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            // 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);
+                clearTelegramRung(agentName, sessionId); // M8C-TGDOOR-1: read clears the ring
+                // M8C-CURSOR-1 (reviewer HIGH fix): a single delivered message only proves THIS sequence
+                // was read — safeCursorAdvance refuses to vault past a gap (e.g. an unread sent leaf from
+                // another local connection) even though this specific sequence number is now known.
+                safeCursorAdvance(connectionId, sessionId, new Set([entry.sequenceNumber]));
+                return {
+                    ok: true,
+                    content: Buffer.from(entry.contentHex, "hex").toString("utf8"),
+                    sessionId,
+                    sequence_number: entry.sequenceNumber,
+                    senderPubkey: entry.senderPubkey,
+                };
+            }
+            // 2) F1-b: the session sealed while we were (or before we started) waiting — return the
+            //    terminal answer instead of hanging to timeout. unread_count reports messages that
+            //    were evicted unread (still durable — recoverable via cello_get_transcript).
+            const terminal = sessionNodeManager.peekTerminalMarker(agentName, sessionId);
+            if (terminal) {
+                const sealedRoot = sessionNodeManager.getSealedRootHex(agentName, sessionId);
+                return {
+                    ok: true,
+                    type: "session_sealed",
+                    session_id: sessionId,
+                    ...(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_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.
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                // M8B F16: a dead session must not return the SAME null timeout as a
+                // quiet-but-healthy one. The liveness signal (session.liveness.changed → gone,
+                // tracked per session by the node manager) finally reaches the MCP surface here.
+                if (sessionNodeManager.getSessionLiveness(agentName, sessionId) === "gone") {
+                    return {
+                        ok: true,
+                        content: null,
+                        reason: "counterparty_gone",
+                        liveness: "gone",
+                        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_transcript for the full session history." };
+            }
+            await new Promise((r) => setTimeout(r, Math.min(20, remaining)));
+        }
+    };
+    handlers.set("cello_receive", handleReceive);
+}
+//# sourceMappingURL=session-content-handlers.js.map

package/dist/session-content-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-content-handlers.js","sourceRoot":"","sources":["../src/session-content-handlers.ts"],"names":[],"mappings":"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"}

package/dist/session-name.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DOD-SESSION-NAME-1 — validation for a session's human-readable name.
+ *
+ * This lives in the DAEMON, not in protocol-types, and that is deliberate: a session name is local
+ * and cosmetic. protocol-types holds the wire encoders and the TBS builders — putting a validator
+ * there would say the name is protocol, and the next reader would reasonably wire it into a frame.
+ * It is a sticky note on your own copy of the folder.
+ *
+ * It is NOT handle-shaped. Do not reach for MONIKER_RE: a moniker is a handle a counterparty sees,
+ * so it is deliberately narrow; this is a DESCRIPTION ("Q3 budget review with Bob") that only its
+ * author reads. Letters, digits, spaces, punctuation, accents, CJK and emoji are all legal.
+ */
+/** Free text, but bounded: long enough for a sentence, short enough to list in a terminal. */
+export declare const SESSION_NAME_MAX_LENGTH = 200;
+export type SessionNameResult = {
+    ok: true;
+    value: string | null;
+} | {
+    ok: false;
+    reason: "session_name_not_a_string" | "session_name_control_chars" | "session_name_too_long";
+    guidance: string;
+};
+/**
+ * Validate a session name.
+ *
+ * Returns the trimmed name, or `null` for "no name" — which is a legal, meaningful value, not a
+ * failure. `null`, `undefined` and an all-whitespace string all mean CLEAR.
+ *
+ * Rejects rather than repairs. A 201-character name is refused, not truncated, and a name carrying
+ * a newline is refused, not stripped: silently altering what the operator typed and then storing it
+ * under their name is worse than telling them it was wrong. Each refusal names its own cause, so
+ * "why was my name rejected" never requires reading the daemon log.
+ */
+export declare function validateSessionName(raw: unknown): SessionNameResult;
+//# sourceMappingURL=session-name.d.ts.map

package/dist/session-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-name.d.ts","sourceRoot":"","sources":["../src/session-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAK3C,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,2BAA2B,GAAG,4BAA4B,GAAG,uBAAuB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAElI;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAkCnE"}

package/dist/session-name.js

@@ -0,0 +1,60 @@
+/**
+ * DOD-SESSION-NAME-1 — validation for a session's human-readable name.
+ *
+ * This lives in the DAEMON, not in protocol-types, and that is deliberate: a session name is local
+ * and cosmetic. protocol-types holds the wire encoders and the TBS builders — putting a validator
+ * there would say the name is protocol, and the next reader would reasonably wire it into a frame.
+ * It is a sticky note on your own copy of the folder.
+ *
+ * It is NOT handle-shaped. Do not reach for MONIKER_RE: a moniker is a handle a counterparty sees,
+ * so it is deliberately narrow; this is a DESCRIPTION ("Q3 budget review with Bob") that only its
+ * author reads. Letters, digits, spaces, punctuation, accents, CJK and emoji are all legal.
+ */
+/** Free text, but bounded: long enough for a sentence, short enough to list in a terminal. */
+export const SESSION_NAME_MAX_LENGTH = 200;
+/** C0 (including \n, \r, \t, \0), DEL, and C1. Rejected, never stripped. */
+const CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/;
+/**
+ * Validate a session name.
+ *
+ * Returns the trimmed name, or `null` for "no name" — which is a legal, meaningful value, not a
+ * failure. `null`, `undefined` and an all-whitespace string all mean CLEAR.
+ *
+ * Rejects rather than repairs. A 201-character name is refused, not truncated, and a name carrying
+ * a newline is refused, not stripped: silently altering what the operator typed and then storing it
+ * under their name is worse than telling them it was wrong. Each refusal names its own cause, so
+ * "why was my name rejected" never requires reading the daemon log.
+ */
+export function validateSessionName(raw) {
+    if (raw === null || raw === undefined)
+        return { ok: true, value: null };
+    if (typeof raw !== "string") {
+        return {
+            ok: false,
+            reason: "session_name_not_a_string",
+            guidance: "A session name must be a string (or null to clear it).",
+        };
+    }
+    // Control characters are checked BEFORE trimming: trim() would silently eat a leading \n or \t
+    // and let a name through that the operator never meant to type — and a name that renders across
+    // two lines corrupts every listing it appears in.
+    if (CONTROL_CHARS.test(raw)) {
+        return {
+            ok: false,
+            reason: "session_name_control_chars",
+            guidance: "A session name cannot contain control characters (newlines, tabs, NUL). It is a single-line label — spaces, punctuation, accents and emoji are all fine.",
+        };
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return { ok: true, value: null };
+    if (trimmed.length > SESSION_NAME_MAX_LENGTH) {
+        return {
+            ok: false,
+            reason: "session_name_too_long",
+            guidance: `A session name is at most ${SESSION_NAME_MAX_LENGTH} characters (this one is ${trimmed.length}). It is refused rather than truncated — a half-name is a name you did not choose.`,
+        };
+    }
+    return { ok: true, value: trimmed };
+}
+//# sourceMappingURL=session-name.js.map

package/dist/session-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-name.js","sourceRoot":"","sources":["../src/session-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C,4EAA4E;AAC5E,MAAM,aAAa,GAAG,8BAA8B,CAAC;AAMrD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAExE,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,2BAA2B;YACnC,QAAQ,EAAE,wDAAwD;SACnE,CAAC;IACJ,CAAC;IAED,+FAA+F;IAC/F,gGAAgG;IAChG,kDAAkD;IAClD,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,4BAA4B;YACpC,QAAQ,EAAE,0JAA0J;SACrK,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAE3D,IAAI,OAAO,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QAC7C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,uBAAuB;YAC/B,QAAQ,EAAE,6BAA6B,uBAAuB,4BAA4B,OAAO,CAAC,MAAM,oFAAoF;SAC7L,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACtC,CAAC"}