@cello-protocol/daemon 0.0.182 → 0.0.183

package/dist/daemon.js

@@ -72,7 +72,7 @@ import { resolveDirectoryUrl } from "./directory-bootstrap.js";
 import { registerContactHandlers } from "./contact-handlers.js";
 import { createSealCoordinator } from "./seal-coordinator.js";
 import { createTelegramDoorbell } from "./telegram-doorbell.js";
-import { registerSessionContentHandlers } from "./session-content-handlers.js";
+import { registerSessionContentHandlers, sentAuthorship } from "./session-content-handlers.js";
 import { createDocumentLayer, agentPublicKeyFromId } from "./document-layer.js";
 import { isDocumentFrame } from "./document-frame-router.js";
 import { INBOUND_INJECTION_BLOCKED } from "@cello-protocol/gateway";
@@ -110,6 +110,7 @@ import { countAttendance, ContentTakeLedger } from "./co-attendance.js";
 import { isOwnAwayAutoReply, AWAY_AUTO_REPLY_TEXTS, markAsAutoReply, isAutoReplyMarked } from "./away-detection.js";
 import { createDeliveryOpenRegistry } from "./delivery-open-registry.js";
 import { FrontierMismatchStore, renderFrontierMismatch } from "./frontier-mismatch.js";
+import { relayOnlyState } from "./relay-only.js";
 import { decodeCbor } from "@cello-protocol/protocol-types";
 // Minimal no-op KeyProvider stub for session nodes.
 // Session nodes don't need signing keys — libp2p generates its own fresh
@@ -162,9 +163,15 @@ export class ProductionSessionNodeFactory {
             listenAddresses: [listenAddr, ...(config.circuitRelayListenAddrs ?? [])],
             ...(announce ? { announceAddresses: announce } : {}),
             connectionGater: config.connectionGater,
+            // DOD-M15-RELAYONLY-1: an agent that asked never to be directly reachable must not hole-punch
+            // its way to a direct connection. dcutr's job is to UPGRADE a relayed connection, and the
+            // INBOUND side starts that upgrade — which is precisely the standing receiver. So filtering
+            // what the directory publishes is not enough on its own: the address a peer cannot be TOLD, a
+            // hole-punch still REVEALS, and it happens inside libp2p after every assertion has passed.
+            ...(config.relayOnly === true ? { holePunch: { enabled: false } } : {}),
             // Forward the role. After DOD-NAT-REACHABILITY-1, dcutr is on every node
-            // type; nodeType's remaining transport effect is the HOP gate (client
-            // types never advertise circuit-relay HOP).
+            // type unless relay-only turns it off above; nodeType's remaining transport effect is the HOP
+            // gate (client types never advertise circuit-relay HOP).
             nodeType: config.nodeType,
             // DOD-M12B-SESSION-SEED-1: forward the caller's transport seed when it supplied one, so a
             // rebuilt session node returns at the peer id the counterparty already holds. Omitted (rather
@@ -589,6 +596,11 @@ async function startDaemonHoldingLock(config, singletonLock) {
     for (const a of loadedAgents) {
         keyProviders.set(a.name, a.keyProvider);
     }
+    // DOD-M15-EPHEMERAL-AUTH-1: the session manager signs each session's throwaway key with the
+    // agent's identity, so it needs the same providers. Injected here rather than through the
+    // constructor because this map is built after the manager exists — the same reason
+    // `setParkedDrainHook` is a setter.
+    sessionNodeManager.setKeyProviderResolver((agentName) => keyProviders.get(agentName));
     // Constructed HERE, before ANY boot-time caller. autoRecoverForAgent is invoked from an agent's
     // onConnected and from the seal-upgrade content gate — both of which run long before the IPC
     // handler map exists. Its handlers register later (phase 2), which is what lets this sit up here.
@@ -799,6 +811,18 @@ async function startDaemonHoldingLock(config, singletonLock) {
             onRelayEndpoints: (endpoints) => {
                 sessionNodeManager.setDirectoryRelayEndpoints(agentName, endpoints.map((e) => ({ relayPeerId: e.peerId, relayAddrs: e.addrs })));
             },
+            // DOD-M15-RELAYSLOTS-1: and the credential those relays require. Same frame, same cadence as
+            // the endpoints above — every connect and every reconnect, which is what keeps a token that
+            // expires within the hour current for a receiver that lives much longer than that.
+            onOnlineToken: (token) => {
+                sessionNodeManager.setDirectoryOnlineToken(agentName, token);
+            },
+            // Review M1: and when there is none, WHY — so the operator surface can say "this directory
+            // does not know this agent" instead of "check your directory connection" about a connection
+            // that just succeeded.
+            onOnlineTokenAbsent: (reason) => {
+                sessionNodeManager.setDirectoryOnlineTokenAbsent(agentName, reason);
+            },
         });
         const mgr = new SignalingManager({
             connect,
@@ -870,6 +894,9 @@ async function startDaemonHoldingLock(config, singletonLock) {
             agentName,
             getStandingReceiverEndpoint: () => sessionNodeManager.getStandingReceiverInfo(agentName),
             admitOfferedDialer: (peerId, sessionIdHex) => sessionNodeManager.admitOfferedDialer(agentName, peerId, sessionIdHex),
+            // DOD-M15-RELAYONLY-1: lets the handler tell "no addresses because relay-only filtered them"
+            // from "no addresses yet", which need opposite answers — a refusal, and the pre-existing path.
+            isRelayOnly: () => relayOnlyState((key) => sessionNodeManager.getSetting(agentName, key), sessionNodeManager.hasDatabase()) !== "off",
             signaling: mgr,
             logger,
         });
@@ -944,6 +971,8 @@ async function startDaemonHoldingLock(config, singletonLock) {
             agentName: agent.name,
             getStandingReceiverEndpoint: () => sessionNodeManager.getStandingReceiverInfo(agent.name),
             admitOfferedDialer: (peerId, sessionIdHex) => sessionNodeManager.admitOfferedDialer(agent.name, peerId, sessionIdHex),
+            // DOD-M15-RELAYONLY-1 — see the note on the sibling call site above.
+            isRelayOnly: () => relayOnlyState((key) => sessionNodeManager.getSetting(agent.name, key), sessionNodeManager.hasDatabase()) !== "off",
             signaling: mgr,
             logger,
         });
@@ -1280,9 +1309,12 @@ async function startDaemonHoldingLock(config, singletonLock) {
                         // 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.
-                        const placed = sessionNodeManager.placeOwnLeaf(agentName, sessionId, rejectHashHex, rejectBytes, sendResult.sequenceNumber, randomUUID());
+                        // 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());
+                            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 });
                     }
@@ -1503,9 +1535,12 @@ async function startDaemonHoldingLock(config, singletonLock) {
                 // 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.
-                const placedQueued = sessionNodeManager.placeOwnLeaf(agentName, sessionId, contentHashHex, contentBytes, sendResult.sequenceNumber, randomUUID());
+                // 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());
+                    sessionNodeManager.recordTranscriptMessage(agentName, sessionId, placedQueued.leafIndex, "sent", contentBytes, randomUUID(), sentAuthorship(sendResult));
                 }
                 logger.info("session.away.response.deferred", {
                     agentName, sessionId, kind, isKnown,
@@ -1517,9 +1552,9 @@ async function startDaemonHoldingLock(config, singletonLock) {
             }
             // 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());
+            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());
+                sessionNodeManager.recordTranscriptMessage(agentName, sessionId, placedReply.leafIndex, "sent", contentBytes, randomUUID(), sentAuthorship(sendResult));
             }
             logger.info("session.away.response.sent", {
                 agentName, sessionId, kind, isKnown,
@@ -1752,6 +1787,9 @@ async function startDaemonHoldingLock(config, singletonLock) {
             // seal depends on — silently, while reporting success.
             receiptStore: stores.receiptStore,
             sealLeafStore: stores.sealLeafStore,
+            // DOD-M15-RELAYSLOTS-1: the manager owns the current token and hands the accessor down, so
+            // this client reads a fresh one at every auth instead of a snapshot taken here at build time.
+            onlineToken: stores.onlineToken,
         });
     });
     // DOD-RETRYQ-STRAND-1: a direct-resend row is reachable only by drainSession, which has no
@@ -1847,6 +1885,54 @@ async function startDaemonHoldingLock(config, singletonLock) {
         logger.warn("session.seal.autoack.broker.unreachable", { agentName, brokerNode, correlationId });
         return null;
     });
+    /**
+     * DOD-M15-RELAYABUSE-1: scheduled park-retry timers, tracked so shutdown can clear them.
+     *
+     * ⚠️ Every other daemon timer is cleared in `stop()`; an untracked one lets an in-process restart
+     * leave a stale timer that drains into a torn-down manager. Unref'd already, so it cannot hold the
+     * process open — this is about a clean teardown, not about exiting.
+     */
+    const parkRetryTimers = new Set();
+    /**
+     * DOD-M15-RELAYABUSE-1: schedule ONE drain at the delay the relay asked for.
+     *
+     * ⚠️ ONE implementation, used by both park paths. The live-send path and the drain path both need
+     * this and a second copy is how the clamp ends up on only one of them — which is exactly the shape
+     * review found here (the number had a consumer on one path and was dropped on the other).
+     *
+     * CLAMPED, because the value comes from another party's software and an unclamped one inverts the
+     * fix: Node's `setTimeout` holds an int32, so a relay reporting `3_000_000_000` overflows it and
+     * fires in about ONE MILLISECOND — re-parking instantly into the limit that just refused, and
+     * printing a `TimeoutOverflowWarning` from a daemon whose convention forbids console output.
+     */
+    function scheduleParkRetry(retryAfterMs, filterAgentName, source) {
+        const MIN_RETRY_MS = 1_000;
+        const MAX_RETRY_MS = 5 * 60_000;
+        const delay = Math.min(Math.max(retryAfterMs, MIN_RETRY_MS), MAX_RETRY_MS);
+        if (delay !== retryAfterMs) {
+            logger.warn("content.park.retry.clamped", {
+                source,
+                requestedMs: retryAfterMs,
+                usedMs: delay,
+                impact: "the relay asked for a retry delay outside the range this daemon will schedule, so it was " +
+                    "clamped — an unclamped value can overflow the timer and fire immediately, which would " +
+                    "re-park straight into the limit that just refused",
+            });
+        }
+        logger.info("content.park.retry.scheduled", { source, delayMs: delay, ...(filterAgentName !== undefined ? { agentName: filterAgentName } : {}) });
+        const timer = setTimeout(() => {
+            parkRetryTimers.delete(timer);
+            void flushAwaitingContent(filterAgentName).catch((err) => {
+                logger.warn("content.park.retry.timer.failed", {
+                    source,
+                    reason: err instanceof Error ? err.message : String(err),
+                    impact: "the scheduled drain threw; the ordinary event triggers (boot, agent start, reconnect) still apply",
+                });
+            });
+        }, delay);
+        timer.unref?.();
+        parkRetryTimers.add(timer);
+    }
     sessionNodeManager.setContentParkHook(async ({ agentName, sessionId, recipientPubkeyHex, relayPeerId, relayAddrs, contentHashHex, content, structure1Cbor, structure2Cbor, contentHashAlg }) => {
         const node = sessionNodeManager.getStandingReceiverNode();
         if (!node) {
@@ -1885,8 +1971,15 @@ async function startDaemonHoldingLock(config, singletonLock) {
         // `DOD-M15-SEALWIRE-1` PART B2b — the algorithm is threaded through, and it is the value THIS
         // MESSAGE was hashed under, never one re-derived from the session's current row. Whether a hash
         // is salted is a fact about the message that was sent; what this side holds now says nothing
-        // about it. Still `sha256` everywhere, because no send path salts yet — the plumbing is proven
-        // carrying the value that cannot break anything, and only then does the value change.
+        // about it.
+        //
+        // ⛔ THIS COMMENT USED TO SAY "Still `sha256` everywhere, because no send path salts yet — the
+        // plumbing is proven carrying the value that cannot break anything, and only then does the value
+        // change." That described B2b, and B2b-2 then CHANGED THE VALUE: a session holding an agreed
+        // salt hashes under `hmac-sha256-salt-v1`, so this path really does carry a salted algorithm
+        // now. Rewritten rather than deleted — a stale reassurance is what `CLAIM-COMMENTS-1` is for,
+        // and on 2026-08-24 a test declared `sha256` on the strength of this sentence and got a tamper
+        // verdict on an honest message.
         const ciphertext = await sealParkEnvelope({
             signer: senderKp,
             sessionIdHex: sessionId,
@@ -1910,8 +2003,48 @@ async function startDaemonHoldingLock(config, singletonLock) {
             logger.info("content.park.deposited", { sessionId, contentHash: contentHashHex, recipientPubkey: recipientPubkeyHex.slice(0, 16) });
             return { ok: true };
         }
-        logger.warn("content.park.deposit.failed", { sessionId, contentHash: contentHashHex, reason: res.reason });
-        return { ok: false, reason: res.reason ?? "relay_deposit_failed" };
+        logger.warn("content.park.deposit.failed", {
+            sessionId,
+            contentHash: contentHashHex,
+            reason: res.reason,
+            ...(res.retryAfterMs !== undefined ? { retryAfterMs: res.retryAfterMs } : {}),
+        });
+        /**
+         * DOD-M15-RELAYABUSE-1 — **GIVE THE RELAY'S "WHEN" A CONSUMER.**
+         *
+         * A deferred park is otherwise retried only on EVENTS — boot, agent start, the drain hook, a
+         * signaling reconnect. None of those is coming for a throttle: the relay is healthy, the link
+         * never dropped, and the condition clears on a timer nobody is watching. So the one refusal that
+         * self-heals in about a minute was the one that waited longest, purely because the number the
+         * relay had already computed had no reader.
+         *
+         * Scheduled ONCE per refusal, unref'd so it can never hold the process open, and best-effort:
+         * the existing event triggers remain the guarantee, and this is a shortcut on top of them. It
+         * deliberately does not retry-on-retry — a timer that reschedules itself on failure is a
+         * self-inflicted flood, which is what the limiter exists to stop.
+         */
+        if (res.retryAfterMs !== undefined && res.retryAfterMs > 0) {
+            /**
+             * ⚠️ CLAMPED, because the number comes from ANOTHER PARTY'S SOFTWARE and an unclamped one is
+             * not merely wrong — it inverts the fix. Node's `setTimeout` holds an int32: a relay reporting
+             * `3_000_000_000` overflows it and the timer fires in about **one millisecond**, re-parking
+             * instantly into the limit that just refused, and printing a `TimeoutOverflowWarning` on
+             * stderr from a daemon whose convention forbids console output. A reported `1` does the same
+             * thing 250 ms later.
+             *
+             * The floor is a second and the ceiling five minutes: long enough that a shortcut is a
+             * shortcut, short enough that it stays one. A clamp is announced rather than silent — a relay
+             * asking us to wait 35 days is a fact an operator wants.
+             */
+            scheduleParkRetry(res.retryAfterMs, agentName, "send");
+        }
+        return {
+            ok: false,
+            reason: res.reason ?? "relay_deposit_failed",
+            // DOD-M15-RELAYABUSE-1 review MEDIUM-6: the guidance quotes the relay's OWN window instead of
+            // guessing "about a minute", which is a hardcoded assumption about a configurable value.
+            ...(res.retryAfterMs !== undefined ? { retryAfterMs: res.retryAfterMs } : {}),
+        };
     });
     // CELLO-M7-MSG-001 (AC-004/AC-005, D-d): startup flush of locally-persisted un-acked
     // content (the crash backstop). Runs HERE — before the IPC socket opens, consistent
@@ -1972,8 +2105,15 @@ async function startDaemonHoldingLock(config, singletonLock) {
         // `DOD-M15-SEALWIRE-1` PART B2b — the algorithm is threaded through, and it is the value THIS
         // MESSAGE was hashed under, never one re-derived from the session's current row. Whether a hash
         // is salted is a fact about the message that was sent; what this side holds now says nothing
-        // about it. Still `sha256` everywhere, because no send path salts yet — the plumbing is proven
-        // carrying the value that cannot break anything, and only then does the value change.
+        // about it.
+        //
+        // ⛔ THIS COMMENT USED TO SAY "Still `sha256` everywhere, because no send path salts yet — the
+        // plumbing is proven carrying the value that cannot break anything, and only then does the value
+        // change." That described B2b, and B2b-2 then CHANGED THE VALUE: a session holding an agreed
+        // salt hashes under `hmac-sha256-salt-v1`, so this path really does carry a salted algorithm
+        // now. Rewritten rather than deleted — a stale reassurance is what `CLAIM-COMMENTS-1` is for,
+        // and on 2026-08-24 a test declared `sha256` on the strength of this sentence and got a tamper
+        // verdict on an honest message.
         const ciphertext = await sealParkEnvelope({
             signer: senderKp,
             sessionIdHex: entry.sessionId,
@@ -1997,7 +2137,12 @@ async function startDaemonHoldingLock(config, singletonLock) {
             logger.info("content.park.deposited", { sessionId: entry.sessionId, contentHash: entry.contentHashHex, source: "startup_flush" });
             return { parked: true };
         }
-        return { parked: false, error: res.reason ?? "deposit_failed" };
+        return {
+            parked: false,
+            error: res.reason ?? "deposit_failed",
+            // DOD-M15-RELAYABUSE-1 review HIGH-2: carry the relay's own "when" out of the DRAIN path too.
+            ...(res.retryAfterMs !== undefined ? { retryAfterMs: res.retryAfterMs } : {}),
+        };
     };
     // Re-park un-acked awaiting content to the relay store-and-forward queue. Runs once pre-IPC
     // (the crash backstop) and again per-agent when an agent comes online — because post-DOD-LOOP-1
@@ -2055,7 +2200,23 @@ async function startDaemonHoldingLock(config, singletonLock) {
         let parkedTotal = 0;
         for (const s of sessions) {
             try {
-                parkedTotal += await retryQueue.drainAwaitingToPark(s.agentId, s.sessionId, parkFn);
+                parkedTotal += await retryQueue.drainAwaitingToPark(s.agentId, s.sessionId, parkFn, (retryAfterMs) => {
+                    /**
+                     * DOD-M15-RELAYABUSE-1 review HIGH-2 — **the drain path can now schedule its own
+                     * follow-up, which is what makes the retry work for a BACKLOG rather than one message.**
+                     *
+                     * Before this, only the live send path heard the relay's delay. With a backlog larger than
+                     * one rate-limit window, the drain deposited what the window allowed, every remaining item
+                     * was refused, and all of them fell back to waiting for an unrelated reconnect — the exact
+                     * condition the retry timer was added to remove.
+                     *
+                     * ONE timer per pass (the drain reports the largest delay it saw, not one per item), and
+                     * it deliberately does not chain beyond that: the next pass schedules the next one only if
+                     * it is refused again, so a permanently-full relay costs one timer per window rather than
+                     * an accelerating stream of them.
+                     */
+                    scheduleParkRetry(retryAfterMs, filterAgentName, "drain");
+                });
             }
             catch (err) {
                 logger.error("content.park.flush.failed", {
@@ -2163,6 +2324,19 @@ async function startDaemonHoldingLock(config, singletonLock) {
                 // (cello_status / cello_list_agents), so a deaf agent is visible to the operator.
                 standing_receiver_ready: sessionNodeManager.getStandingReceiverReady(a.name),
                 standing_receiver_reachability: sessionNodeManager.getStandingReceiverReachability(a.name),
+                /**
+                 * DOD-M15-RELAYSLOTS-1: WHY it is not reachable, and what to do about it.
+                 *
+                 * `standing_receiver_reachability` says `retrying` or `unreachable` and stops there, which
+                 * for the person reading it is indistinguishable from the product being broken. The relay
+                 * now refuses for reasons someone can act on — no token from a directory yet, too many
+                 * sessions still open, this relay is misconfigured — each with a different next step, and
+                 * every one of them is wasted if it only reaches a log file. Absent when the last attempt
+                 * succeeded.
+                 */
+                ...(sessionNodeManager.getStandingReceiverRefusal(a.name)
+                    ? { standing_receiver_refusal: sessionNodeManager.getStandingReceiverRefusal(a.name) }
+                    : {}),
                 // DOD-COATTEND-VISIBLE-1 AC2: how many sessions are driving this agent, including this
                 // one. Live, not a high-water mark — it drops when a session disconnects. `selected` says
                 // whether YOU hold it; this says whether anyone else does too.
@@ -2403,6 +2577,11 @@ async function startDaemonHoldingLock(config, singletonLock) {
                 state: agentStateFor(a),
                 standing_receiver_ready: sessionNodeManager.getStandingReceiverReady(a.name),
                 standing_receiver_reachability: sessionNodeManager.getStandingReceiverReachability(a.name),
+                // DOD-M15-RELAYSLOTS-1: the same cause-and-advice on the daemon-wide surface — see the note
+                // on the MCP one above. Two surfaces, one reason to exist.
+                ...(sessionNodeManager.getStandingReceiverRefusal(a.name)
+                    ? { standing_receiver_refusal: sessionNodeManager.getStandingReceiverRefusal(a.name) }
+                    : {}),
             })),
             standing_receiver_ready: sessionNodeManager.getStandingReceiverReady(),
             retryQueueDepth: retryQueue.getTotalDepth(),
@@ -2434,14 +2613,37 @@ async function startDaemonHoldingLock(config, singletonLock) {
     // Permissive by design (D12): an agent that exists goes online regardless of directory
     // registration state (online-without-registration is an established contract). Returns a
     // structured failure so callers can surface agent_start_failed with a real reason + guidance.
+    /**
+     * `standing_receiver` is part of the SUCCESS shape, not an optional extra — `DOD-M15-START-AGENT-
+     * UNAWAITED-1`. A bare `{ ok: true }` claimed the agent was started and reachable when only the
+     * first half was known, and the union makes the two states impossible to conflate at a call site.
+     */
     function startAgentInternal(name) {
         const agent = agents.find((a) => a.name === name);
         if (!agent || agent.state === "load_failed") {
             return { ok: false, reason: "agent_not_found", guidance: `Agent '${name}' does not exist. Run 'cello login' to register agents, or check agent names with cello_agents.` };
         }
         if (onlineAgents.has(name)) {
-            // Idempotent — already online, no event
-            return { ok: true };
+            // Idempotent — already online, no event.
+            //
+            // It still reports REAL readiness rather than a bare ok. "Already online" says this daemon
+            // marked the agent online at some earlier moment; it says nothing about whether the receiver
+            // that ensure was firing ever came up. An operator who calls start twice — which is exactly
+            // what someone does when the first one seemed not to work — would otherwise get the most
+            // reassuring answer in the run on the attempt where something is actually wrong.
+            const readyNow = sessionNodeManager.getStandingReceiverInfo(name) !== null;
+            if (readyNow)
+                return { ok: true, standing_receiver: "ready" };
+            const cause = sessionNodeManager.standingReceiverAbsenceReason(name);
+            return {
+                ok: true,
+                standing_receiver: "starting",
+                standing_receiver_cause: cause,
+                guidance: `'${name}' was already online, and its standing receiver is not up (${cause}). Outbound ` +
+                    `sends and cello_initiate_session ensure it on demand. An inbound session arriving before ` +
+                    `it is ready is refused with 'standing_receiver_unavailable' — this daemon, not the ` +
+                    `counterparty. If it stays this way, stop the agent and start it again.`,
+            };
         }
         onlineAgents.add(name);
         // Pressing start clears the deliberate-offline mark — that is what makes the switch reversible.
@@ -2467,7 +2669,18 @@ async function startDaemonHoldingLock(config, singletonLock) {
         void sessionNodeManager.ensureStandingReceiverForAgent(name)
             .then(() => flushAwaitingContent(name))
             .catch((err) => {
-            logger.warn("session.standing_receiver.ensure.failed", { agentName: name, reason: extractErrorMessage(err) });
+            logger.warn("session.standing_receiver.ensure.failed", {
+                agentName: name,
+                reason: extractErrorMessage(err),
+                // `DOD-M15-START-AGENT-UNAWAITED-1`. The operator has ALREADY been told `ok: true` — this
+                // handler answered before this promise settled — so nothing corrects that answer if this
+                // is permanent. Say what it costs them here, because this line is the only account.
+                impact: "cello_start_agent already answered ok for this agent, and its standing receiver did not " +
+                    "come up. The agent is online to the directory and CANNOT accept an inbound session: a " +
+                    "counterparty dialling it is refused standing_receiver_unavailable. Initiate and accept " +
+                    "each re-ensure on demand, so this may still recover on the next attempt; if it does not, " +
+                    "stop and restart the agent.",
+            });
         })
             // DOD-MSG-4 (auto-recover-on-reconnect): RECEIVER drains its parked mailbox from every relay it
             // has sessions on (symmetric to the sender re-park). Its own stage so a failure is labelled
@@ -2477,10 +2690,51 @@ async function startDaemonHoldingLock(config, singletonLock) {
             .catch((err) => {
             logger.warn("content.recover.auto.failed", { agentName: name, stage: "agent_start", error: extractErrorMessage(err) });
         });
-        logger.info("agent.online", { agentName: name, agentPubkey: agent.pubkey ?? "" });
+        /**
+         * `DOD-M15-START-AGENT-UNAWAITED-1` — SAY WHETHER THE AGENT CAN ACTUALLY HEAR YET.
+         *
+         * The ensure above is fire-and-forget and that is deliberate: initiate and accept both ensure on
+         * demand, and awaiting it here would turn a transient network failure into a failed start. **The
+         * defect was never the timing — it was the CLAIM.** `{ ok: true }` with nothing else reads as
+         * "your agent is running and reachable", and a session landing in the window before the receiver
+         * exists is refused `standing_receiver_unavailable` — a precondition on OUR side, surfacing to
+         * the operator as though the counterparty or the directory were at fault.
+         *
+         * ⚠️ **This field is only worth having because it can genuinely say `ready`.** Computed one line
+         * after firing an async ensure, a naive readiness flag would be `starting` on every call — a
+         * field that can never take its other value, which is the same defect as a log line reporting a
+         * verdict its producer cannot have. It escapes that because `ensureStandingReceiverForAgent` is
+         * IDEMPOTENT: an agent that already holds a receiver (a repeat start, or one whose receiver
+         * survived) has one at this instant and reports `ready` truthfully.
+         *
+         * `cause` is read from the same four-way answer the refusal path uses, so the response and the
+         * eventual error agree instead of describing the same state in two vocabularies.
+         */
+        const receiverReady = sessionNodeManager.getStandingReceiverInfo(name) !== null;
+        const startingCause = receiverReady ? undefined : sessionNodeManager.standingReceiverAbsenceReason(name);
+        logger.info("agent.online", {
+            agentName: name,
+            agentPubkey: agent.pubkey ?? "",
+            standingReceiver: receiverReady ? "ready" : "starting",
+            ...(startingCause !== undefined ? { standingReceiverCause: startingCause } : {}),
+        });
         // MCP-002: Broadcast agent_state_changed to ALL connections
         notificationDispatcher.dispatchAgentStateChanged(name, "online", "started");
-        return { ok: true };
+        if (receiverReady)
+            return { ok: true, standing_receiver: "ready" };
+        return {
+            ok: true,
+            standing_receiver: "starting",
+            standing_receiver_cause: startingCause,
+            // Invariant: an agent-facing response carries an affordance. Naming the refusal text is the
+            // load-bearing half — an operator who hits it in the next second can otherwise only conclude
+            // the other side is broken.
+            guidance: `'${name}' is online and its standing receiver is still being built. Outbound sends and ` +
+                `cello_initiate_session ensure it on demand, so ordinary use is fine. A session arriving in ` +
+                `the next moment can be refused with 'standing_receiver_unavailable' — that is this daemon ` +
+                `not being ready yet, NOT the counterparty being unreachable. It clears on its own; ` +
+                `cello_status reports the receiver once it is up.`,
+        };
     }
     // M8C-AUTOSTART-1 (F18): resolve which agent an agent-defaulting tool should act on for this
     // connection: an explicit { agent } wins; else the connection's current agent; else — when EXACTLY one
@@ -4535,7 +4789,31 @@ async function startDaemonHoldingLock(config, singletonLock) {
                 // (deliberate — f75ea09), so it obeys the same discipline a message does — including
                 // being HELD when the position is ahead of the tail, which is why the real frame bytes
                 // have to travel with it.
-                const placed = sessionNodeManager.placeOwnLeaf(agent, sessionId, Buffer.from(contentHash).toString("hex"), frameBytes, assignedSeq, correlationId, "doc");
+                const placed = sessionNodeManager.placeOwnLeaf(agent, sessionId, Buffer.from(contentHash).toString("hex"), frameBytes, assignedSeq, correlationId, "doc", 
+                /**
+                 * No proof — and the reason I first wrote here was FALSE, which review traced rather
+                 * than read.
+                 *
+                 * ⚠️ IT SAID *"the document transport does not go through `sendContent`, so no Structure-1
+                 * was signed."* Both halves are wrong. `document-delivery-transport.ts` calls
+                 * `deps.sendContent(...)`, wired straight to `sessionNodeManager.sendContent` a few lines
+                 * above this; and `session-relay-client.ts` signs the Structure-1 with no `leafKind` gate
+                 * at all, so a `0x04` doc leaf is signed exactly like a message. **A proof exists and is
+                 * discarded here.**
+                 *
+                 * That matters more than a wrong comment usually would, because this unit's whole thesis
+                 * is *"`undefined` is a claim the author made rather than one the signature made for
+                 * them"* — and the first claim made under the new signature was untrue.
+                 *
+                 * THE TRUE REASON, which is a better one: **no consumer.** A doc leaf released from a
+                 * hold writes no transcript row — `#releaseHeld` skips `recordTranscriptMessage` for
+                 * `kind === "doc"` — so there is nothing for the proof to reach. Discarding it is
+                 * no-consumer-no-ship, deliberately.
+                 *
+                 * **If doc rows ever reach the transcript, `appendLeaf` needs an authorship parameter**
+                 * and this `undefined` becomes a defect rather than a decision.
+                 */
+                undefined);
                 return { placed: placed.placed, leafIndex: placed.placed ? placed.leafIndex : null };
             },
         });
@@ -4781,6 +5059,11 @@ async function startDaemonHoldingLock(config, singletonLock) {
     async function stop(reason) {
         clearInterval(reconcileSweepTimer);
         clearInterval(revivalBoundSweepTimer);
+        // DOD-M15-RELAYABUSE-1: scheduled park retries. Unref'd, so they never held the process open —
+        // cleared so an in-process restart cannot leave one draining into a torn-down manager.
+        for (const t of parkRetryTimers)
+            clearTimeout(t);
+        parkRetryTimers.clear();
         // DOD-M12B-SHUTDOWN-1: clearing the timer only stops the NEXT tick. The pass already running
         // walks every agent, and each step dials a peer and opens a session — which is why a daemon
         // reported down, with its socket already removed, was still logging `document.reconcile.sweep`