@cello-protocol/daemon 0.0.31 → 0.0.33

package/dist/daemon.js

@@ -33,8 +33,10 @@ import { acquireLock, removeLock } from "./lock-file.js";
 import { createIpcServer } from "./ipc-server.js";
 import { SessionNodeManager } from "./session-node-manager.js";
 import { classifySession } from "./session-category.js";
+import { PassthroughGatewayClient, GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT } from "@cello-protocol/gateway";
 import { RetryQueue } from "./retry-queue.js";
 import { NonceDedupStore } from "./nonce-dedup.js";
+import { HttpTelegramBotClient } from "./telegram-bot-client.js";
 import { ContentParkClient } from "./content-park-client.js";
 import { NotificationDispatcher } from "./notification-dispatcher.js";
 import { createNode, SignalingManager } from "@cello-protocol/transport";
@@ -174,8 +176,11 @@ class ProductionSessionNodeFactory {
         });
     }
 }
+// M8C-TTL-1: receiver-side session-request TTL. CORE ships the DoD's own 24h default;
+// per-agent configurability is PARKED on M9-CFG-001 (D17 — same pattern as D14/D15/D16).
+export const INBOUND_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
 export async function startDaemon(config) {
-    const { celloDir, socketPath, lockFilePath, maxConnections, version, logger, manifestProvider, manifestRootKeys, manifestThreshold, manifestVersionStore: injectedManifestVersionStore, manifestPollScheduler, directoryHttpUrl, signalingConnect, challengeVerifier, directoryEndpointResolver, sessionNodeFactory, sessionNegotiator, getRelayCircuitAddress, } = config;
+    const { celloDir, socketPath, lockFilePath, maxConnections, version, logger, manifestProvider, manifestRootKeys, manifestThreshold, manifestVersionStore: injectedManifestVersionStore, manifestPollScheduler, directoryHttpUrl, signalingConnect, challengeVerifier, directoryEndpointResolver, sessionNodeFactory, sessionNegotiator, getRelayCircuitAddress, telegramBotClient: injectedTelegramBotClient, } = config;
     // CELLO-M7-TRANSPORT-001: composition-root selection of the transport selector.
     // Driven by CELLO_ENV; fails fast at startup (here, not at first session) when a
     // production environment is missing the required transport dialer (AC-010).
@@ -203,12 +208,24 @@ export async function startDaemon(config) {
     await mkdir(celloDir, { recursive: true });
     await mkdir(dirname(socketPath), { recursive: true });
     await acquireLock(lockFilePath, { pid: process.pid, socketPath, version });
+    // M9-CORE-001: one security-gateway client, shared by both seams — the outbound screen in
+    // cello_send and the inbound screen inside SessionNodeManager. Absent config falls back to a
+    // PassthroughGatewayClient (always-allow), so pre-M9 daemons behave exactly as before while
+    // still returning a verdict (SI-001).
+    const securityGateway = config.securityGateway ?? new PassthroughGatewayClient();
+    // M9-CORE-001 observability: announce the gateway mode at startup. The sidecar socket connects
+    // lazily on the first screen, so this records which adapter is wired (sidecar vs the always-allow
+    // passthrough default), not a live socket handshake.
+    logger.info("security.gateway.connected", {
+        mode: config.securityGateway ? "sidecar" : "passthrough",
+    });
     const sessionNodeManager = new SessionNodeManager({
         factory: sessionNodeFactory ?? new ProductionSessionNodeFactory(),
         logger,
         dbPath: join(celloDir, "sessions.db"),
         contentTtfMs: config.contentTtfMs,
         autoNatProbers: () => [],
+        securityGateway,
     });
     await sessionNodeManager.initialize();
     // AC-008: the manifest version store is DB-backed by default (encrypted manifest_state table). A
@@ -525,6 +542,14 @@ export async function startDaemon(config) {
             logger,
             maxReconnectAttempts: Number.MAX_SAFE_INTEGER,
             maxBackoffMs: 30_000,
+            // M8C-RELAYWAKE-1: "check relay on wakeup" — every time this agent's directory signaling
+            // reaches 'connected' (the first connect AND every reconnect after a drop), re-drain its
+            // parked mailbox from every relay it has session history with. Without this, a message
+            // parked while signaling was down (network blip, directory node restart, daemon offline)
+            // is only ever discovered at the NEXT agent start, not on the reconnect that actually
+            // brings the agent back — this closes that gap. Fire-and-forget; autoRecoverForAgent
+            // already catches its own per-relay errors internally.
+            onConnected: () => { void autoRecoverForAgent(agentName); },
         });
         const entry = { signaling: mgr, getNode: () => nodeRef };
         perAgentSignaling.set(agentName, entry);
@@ -721,6 +746,237 @@ export async function startDaemon(config) {
     const perConnectionState = new Map();
     // Set of agents currently in "online" state (transitioned via cello_start_agent)
     const onlineAgents = new Set();
+    // M8C-CURSOR-1: per-connection, per-session read cursor (read-before-write gating).
+    // Distinct from message_watermarks (INBOX-1, per-AGENT delivery watermark, persisted) — this is
+    // per-CONNECTION, in-memory only, and intentionally dies with the connection (a fresh connection
+    // has read nothing yet, so it must catch up before it may send — the WhatsApp-group-chat model
+    // for two attended sessions on one agent). Key = connectionId → sessionId → highest sequence this
+    // connection has read (or authored). Absent entry = -1 (nothing read yet).
+    const connectionCursors = new Map();
+    function getConnectionCursor(connectionId, sessionId) {
+        return connectionCursors.get(connectionId)?.get(sessionId) ?? -1;
+    }
+    function advanceConnectionCursor(connectionId, sessionId, seq) {
+        let byId = connectionCursors.get(connectionId);
+        if (!byId) {
+            byId = new Map();
+            connectionCursors.set(connectionId, byId);
+        }
+        const prior = byId.get(sessionId) ?? -1;
+        if (seq > prior)
+            byId.set(sessionId, seq); // monotonic — never lowers
+    }
+    // M8C-CURSOR-1 (cello-unit-reviewer HIGH finding, confirmed by live reproduction): a
+    // received-only delivery (since_seq / live-drain cello_receive) must NOT blindly advance the
+    // cursor to the max sequence it happened to see — leaf indices are shared and strictly
+    // contiguous across BOTH directions (appendSessionLeaf always assigns leafCount, no gaps), so a
+    // gap between the connection's actual cursor and that max can hide an unread SENT leaf authored
+    // by a DIFFERENT local connection. Advancing past it would silently let this connection send
+    // without ever having seen it — defeating the read-before-write guarantee (C4/C5). Only advance
+    // through a CONTIGUOUS run of sequence numbers that were actually in this delivery, starting
+    // right after the connection's current cursor; stop at the first gap.
+    function safeCursorAdvance(connectionId, sessionId, deliveredSeqs) {
+        let cursor = getConnectionCursor(connectionId, sessionId);
+        while (deliveredSeqs.has(cursor + 1))
+            cursor += 1;
+        advanceConnectionCursor(connectionId, sessionId, cursor);
+    }
+    // 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
+    // on M9-CFG-001, journaled as D15 (M8C-DECISIONS.md, mirrors D14) — a genuine per-agent operator
+    // preference that needs the deferred config store, whereas transparent is already the correct,
+    // non-fake default this unit must ship regardless.
+    // "Attended" per the design doc (2026-07-01 command-surface discussion, Agent State Model):
+    // Primary + a live client session has claimed the agent via use_agent. Scanning
+    // perConnectionState is cheap (a handful of connections) and needs no separate tracked state.
+    function isAttended(agentName) {
+        for (const s of perConnectionState.values())
+            if (s.currentAgent === agentName)
+                return true;
+        return false;
+    }
+    const AWAY_TEXT = {
+        request: "Agent is currently away. Your session request has been received and queued.",
+        message: "Agent is currently away. Your message has been received and will be read when the operator returns.",
+    };
+    // M8C-CONTACT-1: "unknown senders learn only 'dispatched' by default" — a single shared,
+    // deliberately minimal template regardless of kind, distinct from AWAY-1's richer per-type text.
+    const STRANGER_TEXT = "Dispatched.";
+    // Coalescing: one away ack per (agent, session, kind) per away period — cleared when the agent
+    // becomes attended again (cello_use_agent) so the NEXT away period gets a fresh ack rather than
+    // staying silent forever. Known imprecision (journaled, not silent): clearing fires on ANY
+    // use_agent selecting this name, even if another connection kept it attended throughout — an
+    // edge case, not a correctness gap in the core "queue + one calm ack while genuinely away" promise.
+    const awayAckSent = new Set();
+    async function sendAwayResponse(agentName, sessionId, kind) {
+        if (isAttended(agentName))
+            return;
+        const dedupKey = `${agentName}:${sessionId}:${kind}`;
+        if (awayAckSent.has(dedupKey))
+            return;
+        const record = sessionNodeManager.getSessionRecord(agentName, sessionId);
+        if (!record || record.status !== "active")
+            return;
+        // M8C-CONTACT-1: this check MUST run synchronously (before any await below) — the caller of
+        // sendAwayResponse for a fresh inbound request fires this THEN calls addContact right after
+        // (D6: "accepting X's request adds X"), relying on this line executing first so a stranger's
+        // VERY FIRST contact is correctly judged unknown, not already-added.
+        const isKnown = sessionNodeManager.isContact(agentName, record.counterparty_pubkey);
+        awayAckSent.add(dedupKey); // guard BEFORE the async send — concurrent arrivals must not double-ack
+        try {
+            const contentBytes = new TextEncoder().encode(isKnown ? AWAY_TEXT[kind] : STRANGER_TEXT);
+            const contentHash = createHash("sha256").update(new Uint8Array([0x00])).update(contentBytes).digest();
+            const sendResult = await sessionNodeManager.sendContent(agentName, sessionId, contentBytes, new Uint8Array(contentHash), randomUUID());
+            if (!sendResult.ok) {
+                // Reviewer MEDIUM fix: a transient failure must NOT permanently silence the rest of this
+                // away period — clear the guard so the next inbound arrival retries the ack.
+                awayAckSent.delete(dedupKey);
+                logger.warn("session.away.response.failed", { agentName, sessionId, kind, reason: sendResult.reason });
+                return;
+            }
+            const contentHashHex = Buffer.from(contentHash).toString("hex");
+            const { leafIndex } = sessionNodeManager.appendSessionLeaf(agentName, sessionId, "msg", contentHashHex, randomUUID());
+            sessionNodeManager.recordTranscriptMessage(agentName, sessionId, leafIndex, "sent", contentBytes, randomUUID());
+            logger.info("session.away.response.sent", { agentName, sessionId, kind, isKnown, sequenceNumber: leafIndex });
+        }
+        catch (err) {
+            // Reviewer MEDIUM fix: same as above — an unexpected throw must not permanently lock out
+            // future retries for the rest of this away period.
+            awayAckSent.delete(dedupKey);
+            logger.warn("session.away.response.failed", { agentName, sessionId, kind, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // M8C-TGDOOR-1: Telegram Mode 1 doorbell — a daemon-owned bot pushes discrete, content-free
+    // events (session request / message-waiting / state change) to one allowlisted operator chat.
+    // "NO channel machinery" (DoD) — this talks to the Telegram Bot API directly, unrelated to the
+    // claude/channel MCP capability from Tiers 1-2. Inert until telegram_settings exist.
+    let telegramBotClient = injectedTelegramBotClient ?? null;
+    let telegramChatId = null;
+    let telegramBotToken = null; // tracked only to detect an actual token CHANGE
+    // Generation counter, NOT a shared boolean — a boolean flip-to-false-then-true-again (e.g. a
+    // settings update that restarts the poller) would let the OLD loop's `while` condition still
+    // read true on its next check, running TWO concurrent loops. Each loop instance captures its
+    // OWN generation at start and exits the instant the counter no longer matches (a new start, or
+    // shutdown, both just bump it).
+    let telegramPollerGeneration = 0;
+    let telegramUpdateOffset = 0;
+    // Coalescing: ring once for the FIRST message-waiting event since a session was last fully
+    // read; cleared on read (cello_receive/since_seq advancing that session's watermark). Session
+    // requests and state changes bypass this Set entirely — DoD says they always ring.
+    const telegramRungUnread = new Set();
+    async function sendTelegramDoorbell(agentName, sessionId, kind, detail) {
+        if (!telegramBotClient || !telegramChatId)
+            return; // TGDOOR not configured — inert, not an error
+        if (kind === "message_waiting") {
+            const rungKey = `${agentName}:${sessionId}`;
+            if (telegramRungUnread.has(rungKey))
+                return; // already rung, still unread — coalesced
+            telegramRungUnread.add(rungKey);
+        }
+        // DOD-INV-CONTENTFREE: `detail` is a fixed, content-free label per kind — NEVER message text.
+        const text = `[${agentName} · ${sessionId.slice(0, 8)}] ${detail}`;
+        try {
+            const result = await telegramBotClient.sendMessage(telegramChatId, text);
+            if (!result.ok) {
+                logger.warn("telegram.doorbell.send.failed", { agentName, sessionId, kind, reason: result.error });
+                return;
+            }
+            logger.info("telegram.doorbell.sent", { agentName, sessionId, kind });
+        }
+        catch (err) {
+            logger.warn("telegram.doorbell.send.failed", { agentName, sessionId, kind, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // Read clears the ring (DoD: "ring-once-until-read") — called wherever a receive advances a
+    // session's read watermark, mirroring AWAY-1's own dedup-clear-on-attend pattern.
+    function clearTelegramRung(agentName, sessionId) {
+        telegramRungUnread.delete(`${agentName}:${sessionId}`);
+    }
+    // Wraps notificationDispatcher.dispatchSessionStateChanged so every call site gets the
+    // Telegram state-change doorbell for free (DoD: state changes ALWAYS ring, never coalesced) —
+    // one wrapper rather than hooking each of the several existing call sites individually.
+    function dispatchSessionStateChangedWithTelegram(agentName, sessionId, state, counterpartyPubkey) {
+        notificationDispatcher.dispatchSessionStateChanged(agentName, sessionId, state, counterpartyPubkey);
+        void sendTelegramDoorbell(agentName, sessionId, "state_change", `Session ${state}`);
+        // Reviewer HIGH fix (a60d68ed): telegramRungUnread had NO cleanup at all — a session that
+        // rings once and is never read via cello_receive/since_seq (e.g. the operator only ever uses
+        // cello_get_transcript, which does not advance the read watermark) left a permanent entry for
+        // the life of the daemon process. Every state change is a natural point to drop it — the
+        // worst case if the session is still genuinely active is one possible extra ring later, far
+        // preferable to an unbounded leak (the exact class of bug fixed for TTL-1's expired-log at
+        // af8a701 in this same milestone).
+        clearTelegramRung(agentName, sessionId);
+    }
+    async function handleInboundTelegramUpdate(update, client) {
+        const chatId = update.message?.chat?.id !== undefined ? String(update.message.chat.id) : undefined;
+        if (!chatId)
+            return;
+        if (chatId !== telegramChatId) {
+            // D6: any other chat is silently dropped — nothing enters CELLO content paths.
+            logger.info("telegram.inbound.rejected", { chatId });
+            return;
+        }
+        logger.info("telegram.inbound.acknowledged", { chatId });
+        try {
+            await client.sendMessage(chatId, "CELLO doesn't process messages here — this channel only sends you notifications. Use your CELLO client to reply.");
+        }
+        catch (err) {
+            logger.warn("telegram.inbound.ack.failed", { chatId, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // Single long-lived getUpdates poller (DoD) — one in-flight loop per daemon; started once
+    // settings exist, stopped on daemon shutdown. A network hiccup backs off and retries rather
+    // than killing the poller (best-effort — the doorbell is a convenience, never load-bearing).
+    // Reviewer MEDIUM fix (a60d68ed): the loop previously read the SHARED, reassignable
+    // telegramBotClient/telegramUpdateOffset fresh each iteration — only myGeneration was truly
+    // loop-local. A settings update mid-await could let a stale response from the OLD client (1)
+    // still be processed once (the generation check only blocks the loop's NEXT iteration, not an
+    // in-flight call) and (2) stomp telegramUpdateOffset with the OLD bot's update_id numbering,
+    // which is meaningless to a new token (Telegram scopes update_id per bot). Fix: capture the
+    // client as a PARAMETER (never re-read from the shared variable) and re-check the generation
+    // immediately after every await before acting on its result or touching shared state.
+    async function runTelegramPollerLoop(myGeneration, myClient) {
+        let myOffset = telegramUpdateOffset;
+        while (telegramPollerGeneration === myGeneration) {
+            try {
+                const updates = await myClient.getUpdates(myOffset, 25);
+                if (telegramPollerGeneration !== myGeneration)
+                    break; // superseded while awaiting — drop stale results
+                for (const u of updates) {
+                    myOffset = u.update_id + 1;
+                    telegramUpdateOffset = myOffset;
+                    if (u.message)
+                        void handleInboundTelegramUpdate(u, myClient);
+                }
+            }
+            catch (err) {
+                if (telegramPollerGeneration !== myGeneration)
+                    break; // superseded — don't retry under a dead generation
+                logger.warn("telegram.poller.error", { error: err instanceof Error ? err.message : String(err) });
+                await new Promise((r) => setTimeout(r, 2000)); // back off before retrying
+            }
+        }
+    }
+    // Always bumps the generation (invalidating any prior loop, which exits on its next check) and
+    // starts a fresh one — correct both for the first start AND a settings-change restart.
+    function startTelegramPollerIfConfigured() {
+        const settings = sessionNodeManager.getTelegramSettings();
+        if (!settings)
+            return; // not configured — TGDOOR stays inert
+        // Reviewer MEDIUM fix: reset the offset on an actual token/chat CHANGE — a prior bot's
+        // update_id numbering is meaningless to a new one (Telegram scopes it per bot token).
+        if (telegramBotToken !== settings.botToken || telegramChatId !== settings.allowlistedChatId) {
+            telegramUpdateOffset = 0;
+        }
+        telegramBotToken = settings.botToken;
+        telegramChatId = settings.allowlistedChatId;
+        const client = injectedTelegramBotClient ?? new HttpTelegramBotClient(settings.botToken);
+        telegramBotClient = client;
+        telegramPollerGeneration += 1;
+        void runTelegramPollerLoop(telegramPollerGeneration, client);
+        logger.info("telegram.poller.started", {});
+    }
     // SessionNodeManager was constructed + initialized at the top of startDaemon (PERSIST-002 — the
     // encrypted store must open before agents load from the `agents` table). Its standing receiver +
     // interrupted-session detection are already ready here, before the IPC socket opens.
@@ -1705,6 +1961,12 @@ export async function startDaemon(config) {
         }
         const fromAgent = connState.currentAgent;
         connState.currentAgent = name;
+        // M8C-AWAY-1: this agent just became attended — clear its away-ack dedup entries so the NEXT
+        // away period (after this attended stretch ends) gets a fresh ack instead of staying silent.
+        for (const key of Array.from(awayAckSent)) {
+            if (key.startsWith(`${name}:`))
+                awayAckSent.delete(key);
+        }
         // MCP-002: Update dispatcher's routing table and send notification to this connection only
         notificationDispatcher.setCurrentAgent(connectionId, name);
         notificationDispatcher.dispatchAgentCurrentChanged(connectionId, fromAgent, name);
@@ -2577,6 +2839,9 @@ export async function startDaemon(config) {
                 });
             }
         }
+        // M8C-CONTACT-1 (D6): "initiating a session to X adds X" — pin at the pubkey the negotiator
+        // actually used (not re-resolved later).
+        sessionNodeManager.addContact(agentName, counterpartyPubkey);
         // AC-007: the session is usable immediately upon (relay) connection — the dcutr
         // upgrade runs in the background and is intentionally NOT awaited here.
         return { ok: true, sessionId, transportMode: result.mode, correlationId };
@@ -2965,6 +3230,14 @@ export async function startDaemon(config) {
         const { messages, undecryptable } = sessionNodeManager.readTranscript(connState.currentAgent, sessionId);
         // undecryptable > 0 means some rows failed GCM auth (tamper / wrong key) — surfaced, not hidden,
         // so the reader can tell a real gap from an empty transcript.
+        // M8C-CURSOR-1: this is the ONLY reader that covers BOTH directions (sent + received), so it's
+        // the correct general catch-up path — e.g. a second attended connection on the same agent
+        // catching up on a message a DIFFERENT local connection sent (since_seq is received-only and
+        // would never surface it). Route through safeCursorAdvance rather than trusting the raw max —
+        // 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)));
         return { ok: true, session_id: sessionId, messages, undecryptable };
     });
     // cello_list_sessions: the discovery surface — every persisted session for the
@@ -3183,13 +3456,25 @@ export async function startDaemon(config) {
             if (env.structure1Cbor && env.structure2Cbor) {
                 sessionNodeManager.recordOrderingRecord(recipientAgent.name, e.sessionIdHex, env.structure1Cbor, env.structure2Cbor, contentHashBytes);
             }
-            const ingest = sessionNodeManager.ingestReceivedContent(recipientAgent.name, e.sessionIdHex, env.content, contentHashBytes);
+            const ingest = await sessionNodeManager.ingestReceivedContent(recipientAgent.name, e.sessionIdHex, env.content, contentHashBytes);
             if (ingest.ok && ingest.held) {
                 // DOD-MSG-4 (review finding #4): a held entry is NOT yet an appended leaf — its sequence is
                 // the FUTURE canonical index, not a completed recovery. Do not count it as recovered; log it
                 // distinctly so the tally reflects leaves actually written, not content still queued in memory.
                 logger.info("content.recover.held", { sessionId: e.sessionIdHex, contentHash: e.contentHashHex, canonicalSeq: ingest.sequenceNumber });
             }
+            else if (ingest.ok && ingest.screenedOut) {
+                // M9 (code-review LOW-3): a terminal-screened recovered entry IS durably leafed (so it must be
+                // confirm-deleted, below) but was NEVER delivered to the agent — do not count it as a delivered
+                // recovery, and log it distinctly so observability separates "delivered" from "leafed-but-screened".
+                logger.info("content.recover.screened_out", { sessionId: e.sessionIdHex, contentHash: e.contentHashHex, sequenceNumber: ingest.sequenceNumber });
+                try {
+                    await client.confirm(node, Buffer.from(recipientPubkey, "hex"), contentHashBytes, kp);
+                }
+                catch (err) {
+                    logger.warn("content.recover.confirm.failed", { sessionId: e.sessionIdHex, contentHash: e.contentHashHex, error: err instanceof Error ? err.message : String(err) });
+                }
+            }
             else if (ingest.ok) {
                 // DOD-MSG-4 (review #3): count leaves ACTUALLY written — the directly-ingested leaf PLUS any
                 // held out-of-order entries this ingest unblocked (appendedCount), not just 1.
@@ -3284,13 +3569,13 @@ export async function startDaemon(config) {
                 const sessionPeerId = params?.sessionPeerId ?? "";
                 const correlationId = params?.correlationId ?? "";
                 logger.info("session.node.created", { sessionId, agentName, sessionPeerId, correlationId });
-                notificationDispatcher.dispatchSessionStateChanged(agentName, sessionId, "created", counterpartyPubkey);
+                dispatchSessionStateChangedWithTelegram(agentName, sessionId, "created", counterpartyPubkey);
             }
             else if (type === "destroyed") {
                 const state = params?.state ?? "interrupted";
                 const reason = params?.reason ?? state;
                 logger.info("session.node.destroyed", { sessionId, agentName, reason });
-                notificationDispatcher.dispatchSessionStateChanged(agentName, sessionId, state, counterpartyPubkey);
+                dispatchSessionStateChangedWithTelegram(agentName, sessionId, state, counterpartyPubkey);
             }
             return { ok: true };
         });
@@ -3305,6 +3590,15 @@ export async function startDaemon(config) {
                 return { error: "missing_params", guidance: "Provide agentName and sessionId." };
             }
             enqueueInboundSession(agentName, { sessionIdHex, counterpartyPubkeyHex, genesisPrevRootHex: "" });
+            // M8C-TTL-1: let a test backdate the just-enqueued entry's timestamp (simulating age) without
+            // waiting real hours or faking global timers — enqueueInboundSession always stamps Date.now().
+            const enqueuedAtOverride = params?.enqueuedAtOverride;
+            if (enqueuedAtOverride !== undefined) {
+                const q = inboundSessionQueues.get(agentName);
+                const entry = q?.[q.length - 1];
+                if (entry)
+                    entry.enqueuedAt = enqueuedAtOverride;
+            }
             return { ok: true };
         });
         // M8C-INBOX-1 (reviewer F1): buffer a received message so a test can drive a live cello_receive
@@ -3461,6 +3755,9 @@ export async function startDaemon(config) {
             correlationId,
         });
     }
+    // Expired requests move HERE (from inboundSessionQueues) rather than vanishing — visible via
+    // cello_check_notifications so the operator can see what they missed, not just silence.
+    const expiredSessionRequests = new Map();
     // Per-agent FIFO queue (events accepted while no cello_await_session is blocked) and
     // the per-agent list of blocked waiters. Inbound sessions are addressed to a specific
     // local agent (participant_b), so both are keyed by agent name.
@@ -3486,9 +3783,45 @@ export async function startDaemon(config) {
             return;
         }
         const q = inboundSessionQueues.get(agentName) ?? [];
-        q.push(event);
+        q.push({ ...event, enqueuedAt: Date.now() }); // M8C-TTL-1: stamp queue entry time
         inboundSessionQueues.set(agentName, q);
     }
+    // M8C-TTL-1 (reviewer HIGH fix, aed2d71f, D19): expiredSessionRequests is a lasting log, not a
+    // consumed queue (unlike inboundSessionQueues, nothing ever drains it) — a whitelisted CONTACT-1
+    // contact is EXEMPT from ABUSE-1's acceptance bounds ("bounded only by disk"), so they can push
+    // unlimited accepted sessions the operator never claims, each becoming a permanent, unremovable
+    // entry every 24h for the life of the daemon process. Capped the same way STATUS_RESUMABLE_CAP
+    // bounds the interrupted-sessions list — keep only the MOST RECENT N per agent.
+    const EXPIRED_SESSION_REQUESTS_CAP = 20;
+    // M8C-TTL-1: move any queue entries past the TTL into expiredSessionRequests (visible via
+    // INBOX), instead of leaving them to sit forever or vanish silently. Called lazily on every
+    // read of the queue (cello_await_session's immediate-check, cello_check_notifications) rather
+    // than on a timer — no background sweep needed, and it's always correct-as-of-the-read.
+    function reapExpiredInboundSessions(agentName) {
+        const q = inboundSessionQueues.get(agentName);
+        if (!q || q.length === 0)
+            return;
+        const now = Date.now();
+        const live = [];
+        let expiredList = expiredSessionRequests.get(agentName);
+        for (const e of q) {
+            if (e.enqueuedAt !== undefined && now - e.enqueuedAt > INBOUND_SESSION_TTL_MS) {
+                if (!expiredList) {
+                    expiredList = [];
+                    expiredSessionRequests.set(agentName, expiredList);
+                }
+                expiredList.push({ sessionIdHex: e.sessionIdHex, counterpartyPubkeyHex: e.counterpartyPubkeyHex, expiredAt: now });
+                if (expiredList.length > EXPIRED_SESSION_REQUESTS_CAP) {
+                    expiredList.splice(0, expiredList.length - EXPIRED_SESSION_REQUESTS_CAP); // keep newest N
+                }
+                logger.info("session.request.expired", { agentName, sessionId: e.sessionIdHex, enqueuedAt: e.enqueuedAt });
+            }
+            else {
+                live.push(e);
+            }
+        }
+        inboundSessionQueues.set(agentName, live);
+    }
     // CBOR-decoded byte fields arrive as Uint8Array or Buffer; a field may also already be
     // a hex string. Hex strings are lowercased so the case-sensitive agent-pubkey match
     // (agents store lowercase hex) cannot silently miss (review L2).
@@ -3614,6 +3947,20 @@ export async function startDaemon(config) {
     }
     async function acceptInboundAssignment(parsed, agentName, correlationId) {
         try {
+            // M8C-ABUSE-1 (anti-drip-feed / anti-swarm): bound acceptance from unknown (non-contact)
+            // senders — a per-sender cap (many sessions from ONE stranger) and a global cap (many
+            // sessions across ALL strangers combined). Known contacts are exempt ("bounded only by
+            // disk" — DoD). Checked FIRST, before any standing-receiver work, so a refusal is cheap.
+            const bound = sessionNodeManager.checkUnknownSenderAcceptanceBound(agentName, parsed.participantAPubkeyHex);
+            if (!bound.ok) {
+                logger.warn("session.inbound.accept.failed", {
+                    sessionId: parsed.sessionIdHex,
+                    agentName,
+                    reason: bound.reason,
+                    correlationId,
+                });
+                return;
+            }
             // M8B F14 (fix 2): KICK creation before polling — an inbound offer arriving while no
             // receiver exists and none is being created must trigger the ensure itself (the doc
             // comment's "retries on demand" made true), instead of polling a creation nobody
@@ -3682,7 +4029,17 @@ export async function startDaemon(config) {
                 counterpartyPubkeyHex: parsed.participantAPubkeyHex,
                 genesisPrevRootHex,
             });
-            notificationDispatcher.dispatchSessionStateChanged(agentName, parsed.sessionIdHex, "created", parsed.participantAPubkeyHex);
+            dispatchSessionStateChangedWithTelegram(agentName, parsed.sessionIdHex, "created", parsed.participantAPubkeyHex);
+            // M8C-TGDOOR-1: session requests ALWAYS ring (DoD) — no coalescing, unlike message-waiting.
+            void sendTelegramDoorbell(agentName, parsed.sessionIdHex, "session_request", "New session request");
+            // M8C-AWAY-1: an unattended agent auto-acks a fresh inbound session request. Fire-and-forget
+            // (sendAwayResponse never throws) — best-effort, must not delay/block acceptance completion.
+            // ORDER MATTERS: sendAwayResponse's isContact check runs synchronously (before any await) as
+            // soon as it's invoked, so calling addContact on the NEXT line still lets a stranger's very
+            // first contact be judged correctly unknown (M8C-CONTACT-1 D6: "accepting X's request adds X"
+            // — they become known immediately after, for every subsequent interaction).
+            void sendAwayResponse(agentName, parsed.sessionIdHex, "request");
+            sessionNodeManager.addContact(agentName, parsed.participantAPubkeyHex);
         }
         finally {
             inboundInFlight.delete(parsed.sessionIdHex);
@@ -3882,6 +4239,7 @@ export async function startDaemon(config) {
             counterparty_pubkey: e.counterpartyPubkeyHex,
             genesis_prev_root: e.genesisPrevRootHex,
         });
+        reapExpiredInboundSessions(agentName); // M8C-TTL-1: don't hand back a stale expired entry
         const queued = inboundSessionQueues.get(agentName);
         if (queued && queued.length > 0) {
             return toResponse(queued.shift());
@@ -4326,6 +4684,42 @@ export async function startDaemon(config) {
         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 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.
+        const currentSeq = record.message_count - 1;
+        const lastReadSeq = getConnectionCursor(connectionId, sessionId);
+        if (lastReadSeq < currentSeq) {
+            // 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 });
+            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.`,
+            };
+        }
+        // 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
@@ -4346,17 +4740,74 @@ export async function startDaemon(config) {
                 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 contentHash = createHash("sha256").update(new Uint8Array([0x00])).update(contentBytes).digest();
-        const contentHashHex = Buffer.from(contentHash).toString("hex");
         const recipientPubkey = record.counterparty_pubkey;
-        const sendResult = await sessionNodeManager.sendContent(record.agent_name, sessionId, contentBytes, new Uint8Array(contentHash), correlationId);
+        // 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), contentBytes);
+                retryQueue.enqueue(sessionId, new TextEncoder().encode(nonce), sendBytes);
             }
             catch (err) {
                 logger.error("session.content.queue.failed", {
@@ -4378,11 +4829,46 @@ export async function startDaemon(config) {
                 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.",
             };
         }
-        // Delivered — append the message leaf to the daemon-owned tree (advances root).
+        // 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).
-        sessionNodeManager.recordTranscriptMessage(record.agent_name, sessionId, leafIndex, "sent", contentBytes, correlationId);
+        // 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;
+        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,
@@ -4390,8 +4876,14 @@ export async function startDaemon(config) {
             sequenceNumber: leafIndex,
             correlationId,
         });
-        void newRootHex;
-        return { ok: true, sequence_number: leafIndex };
+        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
@@ -4418,6 +4910,36 @@ export async function startDaemon(config) {
         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." };
         }
+        // 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;
+            const from = record.counterparty_pubkey;
+            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 })),
+            };
+        }
         const rawTimeout = params?.timeout_ms;
         const timeoutMs = typeof rawTimeout === "number" && Number.isFinite(rawTimeout) && rawTimeout >= 0
             ? rawTimeout
@@ -4430,6 +4952,11 @@ export async function startDaemon(config) {
                 // 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"),
@@ -4503,19 +5030,91 @@ export async function startDaemon(config) {
             agentNames = [current];
         }
         const agents = agentNames.map((agent) => {
+            reapExpiredInboundSessions(agent); // M8C-TTL-1: expired ones surface below, not as "pending"
             const pending = (inboundSessionQueues.get(agent) ?? []).map((e) => ({
                 session_id: e.sessionIdHex,
                 from: e.counterpartyPubkeyHex,
             }));
+            // M8C-TTL-1: expired requests stay VISIBLE (not silently dropped) — the operator can see
+            // what they missed rather than a request just vanishing from the pending list.
+            const expired = (expiredSessionRequests.get(agent) ?? []).map((e) => ({
+                session_id: e.sessionIdHex,
+                from: e.counterpartyPubkeyHex,
+                expired_at: e.expiredAt,
+            }));
             const unread = sessionNodeManager.getUnreadSummary(agent);
             const total_unread = unread.reduce((sum, u) => sum + u.unread_count, 0);
-            return { agent, pending_session_requests: pending, unread, total_unread };
+            return { agent, pending_session_requests: pending, expired_session_requests: expired, unread, total_unread };
         });
         const totalUnread = agents.reduce((sum, a) => sum + a.total_unread, 0);
         const totalPending = agents.reduce((sum, a) => sum + a.pending_session_requests.length, 0);
-        logger.info("inbox.checked", { connectionId, scope, agentCount: agents.length, totalUnread, totalPending });
+        // M8C-TTL-1 (reviewer finding, D19): surface expired-log size so unbounded growth (were the
+        // cap ever removed or misconfigured) would be visible here, not just in an internal Map.
+        const totalExpired = agents.reduce((sum, a) => sum + a.expired_session_requests.length, 0);
+        logger.info("inbox.checked", { connectionId, scope, agentCount: agents.length, totalUnread, totalPending, totalExpired });
         return { ok: true, scope, agents };
     });
+    // 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.
+    function resolveContactAgent(connState, params) {
+        const explicit = typeof params?.agent === "string" ? params.agent : undefined;
+        if (explicit)
+            return { ok: true, agent: explicit };
+        const current = resolveCurrentAgent(connState);
+        if (!current) {
+            return {
+                ok: false,
+                reason: "no_current_agent",
+                guidance: "No current agent for this connection. Pass --agent <name>, or call cello_use_agent to select one first.",
+            };
+        }
+        return { ok: true, agent: current };
+    }
+    handlers.set("cello_contact_add", async (params, connectionId) => {
+        const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
+        if (!pubkey) {
+            return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) — the contact to add." };
+        }
+        const resolved = resolveContactAgent(perConnectionState.get(connectionId), params);
+        if (!resolved.ok)
+            return resolved;
+        sessionNodeManager.addContact(resolved.agent, pubkey);
+        logger.info("contact.added", { agent: resolved.agent, pubkey });
+        return { ok: true, agent: resolved.agent, pubkey };
+    });
+    handlers.set("cello_contact_remove", async (params, connectionId) => {
+        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." };
+        }
+        const resolved = resolveContactAgent(perConnectionState.get(connectionId), params);
+        if (!resolved.ok)
+            return resolved;
+        const removed = sessionNodeManager.removeContact(resolved.agent, pubkey);
+        logger.info("contact.removed", { agent: resolved.agent, pubkey, removed });
+        return { ok: true, agent: resolved.agent, pubkey, removed };
+    });
+    handlers.set("cello_contact_list", async (params, connectionId) => {
+        const resolved = resolveContactAgent(perConnectionState.get(connectionId), params);
+        if (!resolved.ok)
+            return resolved;
+        const contacts = sessionNodeManager.listContacts(resolved.agent);
+        return { ok: true, agent: resolved.agent, contacts };
+    });
+    // M8C-TGDOOR-1: cello_telegram_set_token — persist the daemon-wide bot token + allowlisted
+    // operator chat ID, then start the poller immediately (no restart needed).
+    handlers.set("cello_telegram_set_token", async (params, _connectionId) => {
+        const botToken = typeof params?.bot_token === "string" ? params.bot_token : undefined;
+        const chatId = typeof params?.allowlisted_chat_id === "string" ? params.allowlisted_chat_id : undefined;
+        if (!botToken || !chatId) {
+            return { ok: false, reason: "missing_params", guidance: "Provide 'bot_token' and 'allowlisted_chat_id'." };
+        }
+        sessionNodeManager.setTelegramSettings(botToken, chatId);
+        startTelegramPollerIfConfigured(); // always bumps the generation — restarts even if already running
+        logger.info("telegram.settings.updated", {});
+        return { ok: true };
+    });
     let shutdownPromise = null;
     handlers.set("shutdown", async (_params, _connectionId) => {
         if (!shutdownPromise) {
@@ -4549,12 +5148,23 @@ export async function startDaemon(config) {
     // used because the dispatcher is constructed AFTER the SessionNodeManager
     // (it depends on the IPC server), so constructor injection would be circular.
     sessionNodeManager.setOnSessionStateChanged((agentName, sessionId, state, counterpartyPubkey) => {
-        notificationDispatcher.dispatchSessionStateChanged(agentName, sessionId, state, counterpartyPubkey);
+        dispatchSessionStateChangedWithTelegram(agentName, sessionId, state, counterpartyPubkey);
+    });
+    // M8C-MSGWAKE-1 (channel stage 2): per-message wake — a verified inbound message fires a
+    // content-free `cello_message` doorbell to the current-agent connection(s). The shim's generic
+    // bridge (WAKE) forwards it to a live --channels session as notifications/claude/channel.
+    sessionNodeManager.setOnContentArrived((agentName, sessionId, senderPubkey) => {
+        notificationDispatcher.dispatchCelloMessage(agentName, sessionId, senderPubkey);
+        // M8C-AWAY-1: an unattended agent auto-acks an inbound message on an existing session.
+        void sendAwayResponse(agentName, sessionId, "message");
+        // M8C-TGDOOR-1: message-waiting — coalesced (ring-once-until-read) inside sendTelegramDoorbell.
+        void sendTelegramDoorbell(agentName, sessionId, "message_waiting", "New message waiting");
     });
     // MCP-001: Clean up per-connection state when a connection disconnects
     // MCP-002: Also unregister from notification dispatcher
     ipcServer.onDisconnect((connectionId) => {
         perConnectionState.delete(connectionId);
+        connectionCursors.delete(connectionId); // M8C-CURSOR-1: cursor is connection-scoped, dies with it
         notificationDispatcher.unregisterConnection(connectionId);
         // Seam 2 (review H2): evict any cello_await_session waiters owned by this connection.
         // Otherwise enqueueInboundSession would hand the next inbound session to a closed
@@ -4592,6 +5202,9 @@ export async function startDaemon(config) {
     // lifecycle is the daemon's, not any agent connection's — so it polls even with zero agents.
     // Graceful shutdown
     async function stop(reason) {
+        // M8C-TGDOOR-1: stop the single long-lived getUpdates poller (no-op if never started) — bump
+        // the generation so the running loop's while-condition fails on its next check.
+        telegramPollerGeneration += 1;
         // CELLO-M7-CONN-001: stop the HTTP manifest poll (sets the stopped flag so an in-flight
         // tick cannot re-arm, and cancels the scheduler). Belt-and-suspenders cancel for the
         // no-poll case (scheduler present but poll not started).
@@ -4618,6 +5231,9 @@ export async function startDaemon(config) {
     function getAutoNatService() {
         return autoNatService;
     }
+    // M8C-TGDOOR-1: cold-capable — start the poller if a token was already configured from a
+    // prior run, without waiting for any agent to come online or any client to attach.
+    startTelegramPollerIfConfigured();
     return { stop, getStatus, getSessionNodeManager, getDirectoryNode, getTransportSelector, getAutoNatService };
 }
 //# sourceMappingURL=daemon.js.map