@cello-protocol/daemon 0.0.196 → 0.0.198

package/dist/attendance-wiring.js

@@ -0,0 +1,432 @@
+/**
+ * What an UNATTENDED agent does when someone reaches it: answer once, say so plainly, and — if the
+ * caller keeps talking to an empty room — close the conversation rather than leave it open forever.
+ *
+ * "Attended" means a live client has claimed the agent with `cello_use_agent`. Several sessions
+ * attending one agent at once is legitimate and permanent — co-attendance, not exclusivity — which
+ * is why the COUNT is kept separate from the boolean and both read the same `currentAgent` map the
+ * doorbell routes on. They cannot disagree about who is present.
+ *
+ * Eleven dependencies, under the order's bound of ~12 — counted, because the first version of
+ * this line said seven. This block was never entangled with the boot
+ * sequence; it just happened to be written in the middle of it.
+ *
+ * ⚠️ IT PLACES ITS OWN LEAVES. The one-shot rejection sends content, appends the leaf and records
+ * the transcript row, so this file belongs in the seal call-site enforcer's CALLERS list — it is
+ * added there in the same commit, because that guard stops SCANNING a file that leaves the list
+ * rather than going red.
+ */
+import { randomUUID } from "node:crypto";
+import { countAttendance, ContentTakeLedger } from "./co-attendance.js";
+import { isOwnAwayAutoReply, AWAY_AUTO_REPLY_TEXTS, markAsAutoReply, isAutoReplyMarked } from "./away-detection.js";
+import { LEAF_KIND_MSG } from "./session-relay-client.js";
+import { sentAuthorship } from "./session-content-handlers.js";
+import { escalateToUnilateralSeal as runUnilateralEscalation, UNILATERAL_SEAL_TIMEOUT_MS } from "./seal-escalation.js";
+export function createAttendanceWiring(deps) {
+    const { logger, sessionNodeManager, perConnectionState, keyProviders, securityGateway, handleActiveSealFlow, sealKey, sealInterruptedInProgress, pendingSealWaiters, pendingUnilateralWaiters, sendOver, } = deps;
+    // 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;
+    }
+    // DOD-COATTEND-VISIBLE-1: the COUNT, deliberately kept separate from the boolean above. Several
+    // sessions attending one agent is legitimate and permanent (co-attendance, not exclusivity — spec
+    // §3); what was missing is that nobody was ever TOLD. `isAttended` is left byte-identical because
+    // M8C-AWAY-1's auto-ack suppression hangs off its early return, and both read the same
+    // `currentAgent` map the doorbell routes on, so the count can never disagree with who gets woken.
+    function attendanceCount(agentName) {
+        return countAttendance(perConnectionState, agentName);
+    }
+    // Which connection consumed which leaf, so the session that finds an empty buffer can be told
+    // whether its counterparty is quiet or its sibling was faster. Written at the destructive drain in
+    // session-content-handlers; read at that handler's timeout. Delivery itself is unchanged.
+    const contentTakes = new ContentTakeLedger();
+    /**
+     * In-flight background seal ceremonies — `DOD-M15-CLOSEWAIT-1` review MEDIUM-6.
+     *
+     * The close now answers at commitment and finishes the ceremony detached. Without this the tail
+     * was the ONE background task `stop()` could cut at an arbitrary point, while it cancels or awaits
+     * every other one.
+     */
+    const backgroundSeals = new Set();
+    // DOD-AWAY-WRAP-1 AC1: request text is a leave-a-message greeting; agentName is spliced in at
+    // the call site so it names the specific away agent.
+    // DOD-AWAY-ACK-ONESHOT-TEXT-1 (live defect 2026-07-24): the ack must state the one-shot rule —
+    // without it a cooperative caller LLM has no reason to stop, sends a follow-up, and eats the
+    // DOD-INBOX-ONESHOT-1 rejection the design itself invited.
+    // ONE definition, shared with the detector in away-detection.ts. A second copy here is how a
+    // reworded away message stops being recognised as machine traffic and the mutual-seal loop
+    // (DOD-AWAY-MUTUAL-SEAL-1) quietly comes back.
+    const AWAY_MESSAGE_TEXT = AWAY_AUTO_REPLY_TEXTS.oneShot;
+    // 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;
+        // DOD-AWAY-WRAP-1 AC2: if the triggering message carries [[WRAP]], the caller is done — skip the
+        // away reply entirely and let the seal ceremony proceed. The dedupKey is intentionally NOT added
+        // here: the WRAP path is a silent close, not an away period that should be deduped.
+        if (kind === "message") {
+            const latestHex = sessionNodeManager.peekLatestReceivedContentHex(agentName, sessionId);
+            if (latestHex !== null) {
+                const text = Buffer.from(latestHex, "hex").toString("utf8");
+                // DOD-WRAP-SUBSTRING-1: match the APPENDED token, not any substring —
+                // DOD-SIGNAL-TOKEN-1 always appends the real token at the END of the body. A substring
+                // match would classify a mere mention of [[WRAP]] (sent signal:"over") as a close
+                // signal, silently skipping both the away reply and the oneshot rejection.
+                if (text.trimEnd().endsWith("[[WRAP]]")) {
+                    logger.info("session.away.response.skipped_wrap", { agentName, sessionId });
+                    return;
+                }
+                // DOD-AWAY-MUTUAL-SEAL-1: an away responder must not answer ANOTHER away responder, and
+                // must not count one toward the one-shot rule.
+                //
+                // When both agents are unattended, each side's auto-reply arrives at the other as an inbound
+                // message. The second such arrival looks exactly like "a caller who ignored the
+                // leave-a-message instruction" — so the one-shot fires on BOTH sides, each sends a [[WRAP]]
+                // rejection and initiates a seal, and two distinct-sender SEAL ctrl leaves is precisely what
+                // notarizes a session.
+                //
+                // Measured from the relay's own log 2026-08-09: sealed THREE SECONDS after opening, its
+                // entire content two machines telling each other nobody was home. Neither daemon learned —
+                // the seal completion is pushed with no pull twin — so both showed `active`, and the
+                // operators returned and talked into a closed room for 68 minutes before finding out.
+                //
+                // Returned silently rather than answered: a reply would continue the ping-pong, and there is
+                // nobody on the far side to read one.
+                if (isOwnAwayAutoReply(text)) {
+                    logger.info("session.away.mutual.skipped", {
+                        agentName,
+                        sessionId,
+                        // DOD-M12B-AWAY-MARK-1: WHICH branch matched. The marker is in-band and therefore
+                        // typeable, so prefixing every message with it skips the one-shot auto-close for free —
+                        // the cost of that attack fell from "reproduce the exact away wording" to "type 15
+                        // characters". This field is what makes a peer doing it on every message visible;
+                        // without it the line reads as routine machine-to-machine traffic.
+                        matched: isAutoReplyMarked(text) ? "marker" : "legacy_exact",
+                        impact: "no away reply and no one-shot seal — two away agents must not notarize a conversation nobody had",
+                    });
+                    return;
+                }
+            }
+        }
+        const dedupKey = `${agentName}:${sessionId}:${kind}`;
+        // F3 fix: a dedicated guard prevents re-entry after the rejection fires — without it a
+        // rapid-fire sender could trigger multiple rejection sends and concurrent seal submits while
+        // the session remains active (seal failed). This key is never cleared (no re-attend resets
+        // it — once rejected, the session is closing regardless).
+        const rejectedKey = `${agentName}:${sessionId}:rejected`;
+        if (awayAckSent.has(dedupKey)) {
+            // DOD-INBOX-ONESHOT-1: a second inbound message while the first away ack is still live means
+            // the caller ignored the leave-a-message instruction. Send one [[WRAP]]-bearing rejection and
+            // immediately initiate the seal so the session closes without operator intervention.
+            if (kind === "message" && !awayAckSent.has(rejectedKey)) {
+                awayAckSent.add(rejectedKey); // guard BEFORE async work — concurrent arrivals must not re-enter
+                const record2 = sessionNodeManager.getSessionRecord(agentName, sessionId);
+                if (record2 && record2.status === "active") {
+                    // Reviewer F2: token at the END — the daemon's own output must honor the
+                    // DOD-SIGNAL-TOKEN-1 append-at-end contract that DOD-WRAP-SUBSTRING-1 detection
+                    // is anchored on (a counterparty daemon's end-anchored detector must see this close).
+                    // DOD-M12B-AWAY-MARK-1: machine-generated, so it is marked — and the marker goes at the
+                    // FRONT precisely so [[WRAP]] keeps the end position the counterparty's detector anchors on.
+                    const rejectText = markAsAutoReply("This inbox only accepts one message per visit. Closing. [[WRAP]]");
+                    const rejectBytes = new TextEncoder().encode(rejectText);
+                    // B2b: one decision point for the hash AND its algorithm — see `contentHashForSession`.
+                    const reject = await sessionNodeManager.contentHashForSession(agentName, sessionId, rejectBytes);
+                    // Best-effort: a send failure still triggers the seal — we are closing regardless.
+                    const sendResult = await sessionNodeManager.sendContent(agentName, sessionId, rejectBytes, new Uint8Array(reject.hash), randomUUID(), LEAF_KIND_MSG, reject.alg);
+                    // M12-P13: commit the leaf when the rejection went out OR when it is durably queued —
+                    // either way the relay already witnessed its sequence. This caller is the sharpest case
+                    // of the three: the seal is initiated immediately below, so a hole here does not merely
+                    // stall the far side, it seals a tree that is one leaf short of a sequence the
+                    // counterparty will still receive content at. The roots then cannot agree, and the
+                    // session is unsealable for good.
+                    if (sendResult.ok || sendResult.durable) {
+                        const rejectHashHex = Buffer.from(reject.hash).toString("hex");
+                        // DOD-M12B-INDEX-1: at the relay's position, not the tail. This is the riskiest append
+                        // in the codebase for that — the seal is initiated a few lines below, so a leaf at the
+                        // wrong index does not merely stall the far side, it seals a tree the counterparty can
+                        // never agree with.
+                        // The proof travels with the leaf, not only with the transcript row below: when this
+                        // append is HELD behind a gap, the `recordTranscriptMessage` call is skipped entirely
+                        // and the held entry is the only thing that reaches the row on release.
+                        const placed = sessionNodeManager.placeOwnLeaf(agentName, sessionId, rejectHashHex, rejectBytes, sendResult.sequenceNumber, randomUUID(), "msg", sentAuthorship(sendResult));
+                        if (placed.placed) {
+                            sessionNodeManager.recordTranscriptMessage(agentName, sessionId, placed.leafIndex, "sent", rejectBytes, randomUUID(), sentAuthorship(sendResult));
+                        }
+                        logger.info("session.away.inbox.oneshot.rejected", { agentName, sessionId, sequenceNumber: placed.placed ? placed.leafIndex : placed.heldAt, committed: placed.placed, queued: !sendResult.ok });
+                    }
+                    else {
+                        // Not queued anywhere — the rejection is gone. We still seal (we are closing regardless),
+                        // and the counterparty simply never learns why, so say that plainly rather than at warn.
+                        logger.error("session.away.inbox.oneshot.reject_send_failed", {
+                            agentName, sessionId, reason: sendResult.reason, cause: sendResult.cause,
+                            impact: "the rejection is lost and was NOT queued — the session seals with no explanation to the counterparty",
+                        });
+                    }
+                    // DOD-INBOX-ONESHOT-1 / DOD-SEAL-BILATERAL-TIMEOUT-1: initiate the seal via the
+                    // relay-mediated path (submitSealLeaf → bilateral wait → unilateral escalation).
+                    // The signaling-only path (handleActiveSealFlow) suffers a leaf_count_mismatch race:
+                    // this party's tree includes the just-sent rejection, but the counterparty's tree may
+                    // not have ingested it yet when the seal request arrives over the signaling channel.
+                    // The relay path avoids this entirely — it posts a SEAL ctrl leaf and waits for the
+                    // counterparty to independently co-seal; no bilateral leaf-count comparison needed.
+                    /**
+                     * DOD-M15-DIVERGE-1 (review HIGH-3) — the gate has to hold on the path with no operator.
+                     *
+                     * `cello_close_session` refuses a diverged record, but this autonomous path never
+                     * consulted `sealReadiness` at all: it read `placed.placed` and discarded
+                     * `placed.diverged`, then initiated the seal directly. So "a diverged session is blocked
+                     * from sealing" held for the close a human drives and not for the one that runs itself —
+                     * which is the worse of the two, because the append two lines above is, by its own
+                     * comment, "the riskiest append in the codebase" for exactly this reason.
+                     *
+                     * THE LOG IS THE SURFACE HERE, and that is not a weakening of Invariant 2. There is no
+                     * caller to answer — nothing is awaiting a response on this path — so the log carries the
+                     * whole warning rather than half of it.
+                     */
+                    const oneshotReadiness = sessionNodeManager.sealReadiness(agentName, sessionId);
+                    if (oneshotReadiness.diverged) {
+                        logger.warn("session.away.inbox.oneshot.seal_skipped_diverged", {
+                            agentName, sessionId,
+                            treeSize: oneshotReadiness.treeSize, highWaterSeq: oneshotReadiness.highWaterSeq,
+                            impact: "this side's tree parted from the relay's ordering, so the seal was NOT initiated — the session stays closeable by hand, where the operator is told what parted and can compare counts with the counterparty before deciding",
+                        });
+                    }
+                    else {
+                        void (async () => {
+                            const correlationId = randomUUID();
+                            const sk = sealKey(agentName, sessionId);
+                            if (sealInterruptedInProgress.has(sk))
+                                return;
+                            sealInterruptedInProgress.add(sk);
+                            try {
+                                // DOD-M15-SEALWIRE-1 bullet 2 (review F4): SealCompletion is now a union — a refused
+                                // certificate resolves the waiter rather than dropping it, so this path must handle it
+                                // too rather than treating a refusal as a seal.
+                                let resolveSeal;
+                                const sealedP = new Promise((r) => { resolveSeal = r; });
+                                pendingSealWaiters.set(sk, resolveSeal);
+                                const submit = await sessionNodeManager.submitSealLeaf(agentName, sessionId, correlationId);
+                                if (!submit.ok && submit.reason !== "responder_seal_already_submitted") {
+                                    pendingSealWaiters.delete(sk);
+                                    if (submit.reason === "relay_unavailable") {
+                                        const fallback = await handleActiveSealFlow(sessionId, record2, correlationId);
+                                        if (fallback.ok) {
+                                            logger.info("session.away.inbox.oneshot.seal_initiated", { agentName, sessionId, path: "signaling_fallback" });
+                                        }
+                                        else {
+                                            logger.warn("session.away.inbox.oneshot.seal_initiate_failed", { agentName, sessionId, reason: fallback.reason, path: "signaling_fallback" });
+                                        }
+                                    }
+                                    else {
+                                        logger.warn("session.away.inbox.oneshot.seal_initiate_failed", { agentName, sessionId, reason: submit.reason });
+                                    }
+                                    return;
+                                }
+                                logger.info("session.away.inbox.oneshot.seal_initiated", { agentName, sessionId, path: "relay" });
+                                const bilateralTimeoutMs = Number(process.env["CELLO_SEAL_BILATERAL_TIMEOUT_MS"]) || 660_000;
+                                let timer;
+                                const timeoutP = new Promise((r) => { timer = setTimeout(() => r(null), bilateralTimeoutMs); });
+                                const sealedCompletion = await Promise.race([sealedP, timeoutP]);
+                                clearTimeout(timer);
+                                pendingSealWaiters.delete(sk);
+                                if (sealedCompletion !== null) {
+                                    // DOD-M15-SEALWIRE-1 bullet 2 (review F4): a REFUSED certificate resolves the waiter
+                                    // now rather than being dropped, so this path must tell the two apart — logging a
+                                    // refusal as "sealed" would be the silent acceptance the whole bullet exists to stop.
+                                    if ("refused" in sealedCompletion) {
+                                        logger.error("session.away.inbox.oneshot.seal_refused", {
+                                            agentName, sessionId, reason: sealedCompletion.reason, detail: sealedCompletion.detail,
+                                            impact: "the away auto-seal was REFUSED: the directory returned a validly signed root " +
+                                                "that does not describe this conversation. The session is NOT sealed and nothing " +
+                                                "was signed with this agent's key.",
+                                        });
+                                        return;
+                                    }
+                                    logger.info("session.away.inbox.oneshot.sealed", { agentName, sessionId, sealedRoot: sealedCompletion.rootHex });
+                                    return;
+                                }
+                                // Bilateral timeout — escalate to unilateral seal.
+                                const escalation = submit.ok
+                                    ? { reportedRootHex: submit.reportedRootHex, sequenceNumber: submit.sequenceNumber }
+                                    : submit.reason === "responder_seal_already_submitted" &&
+                                        typeof submit.reportedRootHex === "string" &&
+                                        typeof submit.sequenceNumber === "number"
+                                        ? { reportedRootHex: submit.reportedRootHex, sequenceNumber: submit.sequenceNumber }
+                                        : null;
+                                if (!escalation) {
+                                    logger.warn("session.away.inbox.oneshot.seal_pending", { agentName, sessionId });
+                                    return;
+                                }
+                                // DOD-M12B-SEAL-ESCALATE-DUP-1: THE SHARED ESCALATION, not a second copy.
+                                //
+                                // This used to be a line-for-line duplicate with its own hardcoded 30 s timeout, and
+                                // it missed every refusal the other one gained: an empty carry, a gappy chain, two of
+                                // our own ctrl leaves (permanently unsealable), and a bilateral seal already running.
+                                // It spent the full timeout on each and then reported `seal_unilateral_timeout` — the
+                                // label that names our own wait. Sharing the body is what stops that drifting again.
+                                const uni = await runUnilateralEscalation({
+                                    logger, sessionNodeManager, sendOver, pendingUnilateralWaiters, sealKey,
+                                    getKeyProvider: (a) => keyProviders.get(a),
+                                    timeoutMs: UNILATERAL_SEAL_TIMEOUT_MS,
+                                }, agentName, sessionId, escalation, correlationId, { refuseOnUnusableCarry: true });
+                                if (uni.ok) {
+                                    logger.info("session.away.inbox.oneshot.sealed", { agentName, sessionId, sealedRoot: uni.sealed_root, sealType: "unilateral" });
+                                }
+                                else {
+                                    // CARRY THE GUIDANCE. The four refusals this path just gained come with the
+                                    // sentence that tells an operator whether to retry or force-abandon — and the log
+                                    // is this path's ONLY surface, so dropping it leaves a nameable cause with no
+                                    // action attached. The old reasons had no guidance to lose; these do.
+                                    logger.warn("session.away.inbox.oneshot.seal_unilateral_failed", {
+                                        agentName, sessionId, reason: uni.reason, guidance: uni.guidance,
+                                    });
+                                }
+                            }
+                            finally {
+                                sealInterruptedInProgress.delete(sealKey(agentName, sessionId));
+                            }
+                        })();
+                    }
+                }
+            }
+            return;
+        }
+        const record = sessionNodeManager.getSessionRecord(agentName, sessionId);
+        if (!record || record.status !== "active")
+            return;
+        // Select the ack wording by whether the sender is a known contact — STRANGER_TEXT
+        // ("Dispatched.") for unknown, system default for known. The inbound accept path does NOT
+        // auto-add the sender: an unattended stranger STAYS unknown across every inbound interaction.
+        // Promotion requires operator engagement — an outbound initiate, a cello_send reply, or an
+        // explicit contact add. This is a plain read of current contact state; nothing downstream
+        // depends on its ordering.
+        const isKnown = sessionNodeManager.isKnown(agentName, record.counterparty_pubkey);
+        // DOD-AWAY-WRAP-1 AC1: request kind uses a leave-a-message greeting that names the away agent.
+        const systemDefault = kind === "request"
+            ? AWAY_AUTO_REPLY_TEXTS.offerFor(agentName)
+            : AWAY_MESSAGE_TEXT;
+        awayAckSent.add(dedupKey); // guard BEFORE the async send — concurrent arrivals must not double-ack
+        try {
+            // DOD-AWAY-TIER-1: resolve most-specific-first — per-contact away_message → per-tier away
+            // (settings) → agent default (settings) → the system default (code, per kind). Total.
+            // DOD-M12B-AWAY-MARK-1: THE choke point. Every away reply this daemon sends passes through
+            // this one expression — the per-contact message, the per-tier message, the agent default, the
+            // system default and the stranger ack — so marking here is what makes "an operator's
+            // CONFIGURED away message is indistinguishable from a person" go away, which is the half
+            // exact-text matching could not reach by construction. markAsAutoReply is idempotent, so the
+            // system defaults (already marked at their source) do not pick up a second token.
+            const awayText = sessionNodeManager.resolveAwayMessage(agentName, record.counterparty_pubkey)
+                ?? (isKnown ? systemDefault : STRANGER_TEXT);
+            const draftBytes = new TextEncoder().encode(awayText);
+            // SI (AWAY-TIER-1): an away message is now operator-configurable, i.e. an outbound DISCLOSURE.
+            // Screen it on the outbound path like any content — it does NOT bypass the gateway. A block/warn
+            // verdict means it is not sent (the dedup guard stays set — one screen per away period, no spam);
+            // a redact verdict sends the ALTERED bytes.
+            const awayVerdict = await securityGateway.screenOutbound(draftBytes, {
+                direction: "outbound", agentName, sessionId, correlationId: randomUUID(),
+            });
+            if (awayVerdict.disposition === "block" || awayVerdict.disposition === "warn") {
+                logger.info("session.away.response.screened_out", { agentName, sessionId, kind, disposition: awayVerdict.disposition });
+                return;
+            }
+            if (awayVerdict.disposition === "redact" && awayVerdict.content === undefined) {
+                logger.error("session.away.response.redact_without_content", { agentName, sessionId, kind });
+                return;
+            }
+            // DOD-M12B-AWAY-MARK-1: mark AFTER screening, never before. A redact verdict REPLACES the
+            // bytes, and marking the draft would let that replacement silently strip the marker — an away
+            // reply back on the wire indistinguishable from a person, with no log line saying so. Marking
+            // here also means the gateway screens the operator's actual disclosure rather than a daemon
+            // token bolted to the front of it. markAsAutoReply is idempotent and the system defaults are
+            // marked at their source, so nothing gains a second token.
+            const screenedBytes = awayVerdict.disposition === "redact" && awayVerdict.content !== undefined
+                ? new Uint8Array(awayVerdict.content)
+                : draftBytes;
+            const contentBytes = new TextEncoder().encode(markAsAutoReply(new TextDecoder().decode(screenedBytes)));
+            // B2b: one decision point for the hash AND its algorithm — see `contentHashForSession`.
+            const away = await sessionNodeManager.contentHashForSession(agentName, sessionId, contentBytes);
+            const sendResult = await sessionNodeManager.sendContent(agentName, sessionId, contentBytes, new Uint8Array(away.hash), randomUUID(), LEAF_KIND_MSG, away.alg);
+            if (!sendResult.ok && !sendResult.durable) {
+                // 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);
+                // M12-P13: this branch now means the reply is GONE, not merely late (the queued case is
+                // handled below), so it is an error and it says what the consequence is. It was a bare warn
+                // when it fired live on 2026-08-05 and read as routine churn.
+                logger.error("session.away.response.failed", {
+                    agentName, sessionId, kind, reason: sendResult.reason, cause: sendResult.cause,
+                    impact: "the away reply is lost and was NOT queued — the counterparty gets no acknowledgement",
+                });
+                return;
+            }
+            const contentHashHex = Buffer.from(away.hash).toString("hex");
+            if (!sendResult.ok) {
+                // M12-P13 (found live 2026-08-05, M12 Entry 89): the reply is durably queued and already
+                // owns the sequence the relay witnessed for it, so its leaf MUST be committed here. Without
+                // it this side's tree stays one short of that sequence, and since `nextExpected` is the tree
+                // size, every message the counterparty sends afterwards is held behind a gap nothing can
+                // fill. That is exactly how the receiver stranded its own session at sequence 0.
+                //
+                // The dedup guard deliberately STAYS SET: a queued reply is coming, and re-sending on the
+                // next arrival would mint a second greeting at a second sequence.
+                // DOD-M12B-INDEX-1: the queued reply owns the position the relay witnessed for it, and
+                // that is where its leaf goes.
+                // Witnessed and SIGNED — only the direct hand-off failed — so the proof exists and must
+                // reach the leaf. This is the site `sentAuthorship`'s own comment calls dead-by-construction
+                // under an `ok`-gated read; the same reasoning applies to the leaf, not just the row.
+                const placedQueued = sessionNodeManager.placeOwnLeaf(agentName, sessionId, contentHashHex, contentBytes, sendResult.sequenceNumber, randomUUID(), "msg", sentAuthorship(sendResult));
+                if (placedQueued.placed) {
+                    sessionNodeManager.recordTranscriptMessage(agentName, sessionId, placedQueued.leafIndex, "sent", contentBytes, randomUUID(), sentAuthorship(sendResult));
+                }
+                logger.info("session.away.response.deferred", {
+                    agentName, sessionId, kind, isKnown,
+                    sequenceNumber: placedQueued.placed ? placedQueued.leafIndex : placedQueued.heldAt,
+                    committed: placedQueued.placed,
+                    reason: sendResult.reason, cause: sendResult.cause,
+                });
+                return;
+            }
+            // DOD-M12B-INDEX-1: the away responder fires while inbound is still arriving, so it is the
+            // path most likely to have a gap open under it — exactly where a tail append does damage.
+            const placedReply = sessionNodeManager.placeOwnLeaf(agentName, sessionId, contentHashHex, contentBytes, sendResult.sequenceNumber, randomUUID(), "msg", sentAuthorship(sendResult));
+            if (placedReply.placed) {
+                sessionNodeManager.recordTranscriptMessage(agentName, sessionId, placedReply.leafIndex, "sent", contentBytes, randomUUID(), sentAuthorship(sendResult));
+            }
+            logger.info("session.away.response.sent", {
+                agentName, sessionId, kind, isKnown,
+                sequenceNumber: placedReply.placed ? placedReply.leafIndex : placedReply.heldAt,
+                committed: placedReply.placed,
+            });
+        }
+        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) });
+        }
+    }
+    // `isAttended` is NOT returned: its only caller in the repo is `sendAwayResponse`, which moved
+    // with it. Returning it would make a private local reachable through an exported factory for no
+    // consumer — new surface, which Rule D forbids.
+    return { attendanceCount, sendAwayResponse, contentTakes, backgroundSeals, awayAckSent };
+}
+//# sourceMappingURL=attendance-wiring.js.map

package/dist/attendance-wiring.js.map

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

package/dist/backup-restore-handlers.d.ts

@@ -0,0 +1,10 @@
+import type { IpcHandler } from "./ipc-server.js";
+import type { Logger } from "./types.js";
+export interface BackupRestoreDeps {
+    handlers: Map<string, IpcHandler>;
+    logger: Logger;
+    /** Where the daemon keeps its data — the database this writes out and reads back sits under it. */
+    celloDir: string;
+}
+export declare function registerBackupRestoreHandlers(deps: BackupRestoreDeps): void;
+//# sourceMappingURL=backup-restore-handlers.d.ts.map

package/dist/backup-restore-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-restore-handlers.d.ts","sourceRoot":"","sources":["../src/backup-restore-handlers.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAuE3E"}

package/dist/backup-restore-handlers.js

@@ -0,0 +1,82 @@
+/**
+ * Backup and restore: write this machine's agent to a file, and put one back.
+ *
+ * Three dependencies — the handler map, a logger, and where the daemon keeps its data. That is the
+ * whole reason this is its own module rather than sitting with the other admin verbs: it touches
+ * files and nothing else, so it needs none of the signaling, consortium or ceremony machinery they
+ * do, and merging them would push one context over the bound to save one call site.
+ *
+ * The backup file is as sensitive as a private key. `VACUUM INTO` takes a consistent snapshot with
+ * the database still open, which is what makes this safe to run against the daemon serving the call.
+ */
+import { join } from "node:path";
+import { createBackup, inspectBackup } from "./backup-restore.js";
+export function registerBackupRestoreHandlers(deps) {
+    const { handlers, logger, celloDir } = deps;
+    /**
+     * DOD-M15-BACKUP-1 — export the agent, so losing the machine does not lose the identity.
+     *
+     * `VACUUM INTO` takes a consistent snapshot with the database still open, so this is safe to call
+     * on a running daemon — which matters, because the daemon is what serves the tool.
+     */
+    handlers.set("cello_backup", async (params, _connectionId) => {
+        const outPath = typeof params?.["path"] === "string" ? params["path"] : "";
+        if (!outPath) {
+            return {
+                ok: false,
+                reason: "missing_path",
+                guidance: "Give an absolute path to write the backup to, e.g. { path: \"/Users/you/cello-agent.cello-backup\" }. " +
+                    "It is not written to a default location on purpose: the file contains the key to your agent, " +
+                    "so where it lands is a decision you should make deliberately.",
+            };
+        }
+        const res = await createBackup({
+            dbPath: join(celloDir, "sessions.db"),
+            outPath,
+            logger,
+            ...(params?.["overwrite"] === true ? { overwrite: true } : {}),
+        });
+        return res.ok
+            ? { ok: true, path: res.path, bytes: res.bytes, guidance: res.guidance }
+            : { ok: false, reason: res.reason, guidance: res.guidance };
+    });
+    /**
+     * RESTORE IS REFUSED WHILE THIS DAEMON IS RUNNING, and that is not a limitation to apologise for.
+     *
+     * The daemon holds the database open with a write lock. Overwriting the file underneath an open
+     * SQLite handle risks the handle flushing its own pages back over the restored ones — the restore
+     * appears to succeed and the database is a hybrid of two identities, which is worse than either
+     * failing cleanly.
+     *
+     * The capability itself lives in `backup-restore.ts` (a daemon module, per the DoD), and the CLI
+     * calls it with the daemon stopped. So the honest answer here is the exact sequence, not an
+     * attempt.
+     */
+    handlers.set("cello_restore", async (params, _connectionId) => {
+        const archivePath = typeof params?.["path"] === "string" ? params["path"] : "";
+        const inspected = archivePath ? await inspectBackup(archivePath) : null;
+        return {
+            ok: false,
+            reason: "daemon_running",
+            ...(inspected?.ok
+                ? { archive_verified: true, backup_created_at: new Date(inspected.createdAt).toISOString() }
+                : inspected
+                    ? { archive_verified: false, archive_problem: inspected.reason }
+                    : {}),
+            guidance: (inspected?.ok
+                ? `That archive is valid (taken ${new Date(inspected.createdAt).toISOString()}). `
+                : inspected
+                    ? `WARNING: that archive did not validate (${inspected.reason}) — fix that before going further. `
+                    : "") +
+                "Restoring REPLACES this machine's agent database, and it cannot be done while the daemon " +
+                "is holding it open — the running daemon could flush its own pages back over the restored " +
+                "ones and leave a database that is half one identity and half another. Stop the daemon " +
+                "first:\n\n  cello logout\n  cello restore " +
+                (archivePath || "<archive>") +
+                "\n  cello login\n\n" +
+                "Anything that happened on this machine since the backup was taken will be gone — restore " +
+                "replaces, it does not merge.",
+        };
+    });
+}
+//# sourceMappingURL=backup-restore-handlers.js.map

package/dist/backup-restore-handlers.js.map

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