@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/wire-content-hash.js

@@ -0,0 +1,116 @@
+/**
+ * THE content hash every session content frame carries on the wire.
+ *
+ * `sha256(0x00 || content)`. The `0x00` is a domain-separation prefix, and it is NOT the leaf kind:
+ * the receiver recomputes with `0x00` for every frame regardless of what the content turns out to
+ * be (`session-node-manager.ts` cross-check), and the leaf KIND — `msg`, `doc`, `ctrl` — is decided
+ * afterwards, when the leaf is appended. Confusing the two is the mistake this module exists to
+ * stop, because it produces a hash that is individually plausible and rejected by every peer.
+ *
+ * ── WHY IT IS A MODULE ────────────────────────────────────────────────────────────────────────
+ *
+ * The expression was written out at five call sites. The two DOCUMENT senders — added last — wrote
+ * `sha256(content)` without the prefix, and the failure is the least debuggable shape there is:
+ * the send succeeds, `parked: false`, the sender's log says the frame left, and the receiver
+ * discards it at the authenticity check with `content_hash_mismatch` before the document layer is
+ * ever consulted. The receiving side logs nothing about documents at all, so the evidence points at
+ * classification, at the router, at the gateway — everywhere except the sender's hash.
+ *
+ * No unit test could see it: both sides of every in-process test compute the hash with the same
+ * function, so they agree with each other whether or not either agrees with the wire. It took two
+ * real daemons.
+ */
+import { createHash } from "node:crypto";
+import { saltedContentHash } from "@cello-protocol/crypto";
+/**
+ * ─── THE ALGORITHM TRAVELS WITH THE HASH — `DOD-M15-SEALWIRE-1` part B1 ───────────────────────
+ *
+ * A salted content hash and an unsalted one are both 32 bytes in the same wire field. Nothing in
+ * the bytes distinguishes them, so a receiver handed one and told nothing has no way to know which
+ * it is holding — and gets `content_hash_mismatch` on every frame, which is the exact
+ * silent-discard failure this module's header says cost two real daemons.
+ *
+ * Hence a NAME on the wire, and three cases that must stay apart (Decisions Carried #15):
+ *
+ *   ABSENT            → `sha256`. A peer that predates the field. We know what it computed.
+ *   NAMED and KNOWN   → verify under that name.
+ *   NAMED and UNKNOWN → **refuse.** Not a legacy peer — an unreadable one. There is no correct hash
+ *                       to compare against, and falling back to `sha256` would compare two
+ *                       unrelated values and report a TAMPER for a version skew.
+ *
+ * ⚠️ RECEIVER FIRST — the ROLLOUT ORDER, which is still the rule. Every peer must be able to
+ * understand a salted frame before any peer sends one. Reversed, the first upgraded sender breaks
+ * every conversation it has with a peer that has not upgraded.
+ *
+ * > **⛔ THIS PARAGRAPH USED TO END "`no sender salts yet`", AND THAT IS NO LONGER TRUE.** It was
+ * > written during part B1, when the receiver had been taught to read the name and nothing produced
+ * > a salted one. **B2b-2 flipped it: a session holding an agreed salt now hashes under
+ * > `HMAC_SALT_V1`.** The sentence is rewritten rather than deleted because it is exactly the shape
+ * > `DOD-M15-CLAIM-COMMENTS-1` exists to catch — a comment asserting a property the code no longer
+ * > has — and deleting it would remove the evidence that someone reasoned from it.
+ * >
+ * > It was still being read as current on 2026-08-24: a spine test's park deposit declared `sha256`
+ * > on this comment's authority, the recipient recomputed under the name it was given, and the
+ * > mismatch surfaced as `content_hash_mismatch` — **a tamper verdict on a message nobody touched**,
+ * > which is precisely the failure the ALGORITHM-TRAVELS-WITH-THE-HASH rule above exists to prevent.
+ */
+export const CONTENT_HASH_ALGS = {
+    /** `sha256(0x00 ‖ content)` — what every build before the salt computes, and the absent-field default. */
+    SHA256: "sha256",
+    /** `hmac-sha256(salt, 0x00 ‖ content)` — Decision #9. HMAC, never `sha256(salt ‖ content)`. */
+    HMAC_SALT_V1: "hmac-sha256-salt-v1",
+};
+const KNOWN_ALGS = new Set(Object.values(CONTENT_HASH_ALGS));
+/** Whether this daemon can reproduce a hash under the given name. */
+export function isKnownContentHashAlg(alg) {
+    return KNOWN_ALGS.has(alg);
+}
+/**
+ * What a frame says it used, or a refusal naming the value.
+ *
+ * ABSENT is deliberately `undefined`/`null` ONLY — not "falsy". An empty string is a peer that sent
+ * a name we cannot read, not a peer that sent no name, and folding the two together would verify a
+ * malformed frame as legacy instead of telling its sender the frame is unreadable.
+ */
+export function resolveContentHashAlg(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, alg: CONTENT_HASH_ALGS.SHA256 };
+    if (typeof raw !== "string" || !isKnownContentHashAlg(raw)) {
+        return { ok: false, value: typeof raw === "string" ? raw : `(${typeof raw})` };
+    }
+    return { ok: true, alg: raw };
+}
+/**
+ * The content hash under a named algorithm.
+ *
+ * THROWS rather than substituting, in both failure cases, and that is the point of the function. A
+ * 32-byte value returned for an unknown algorithm — or an unsalted one returned because the salt was
+ * missing — flows straight into the cross-check and surfaces as `content_hash_mismatch`: a TAMPER
+ * REPORT for what is really a version skew or a missing salt. The caller must handle those as what
+ * they are.
+ */
+export function contentHashFor(content, opts) {
+    if (opts.alg === CONTENT_HASH_ALGS.SHA256)
+        return wireContentHash(content);
+    if (opts.alg === CONTENT_HASH_ALGS.HMAC_SALT_V1) {
+        if (!opts.salt) {
+            throw new Error(`CONTENT HASH: ${CONTENT_HASH_ALGS.HMAC_SALT_V1} was requested with no session salt. Refusing rather ` +
+                "than computing the unsalted form — that would put bytes on the wire under a label they do not match, " +
+                "and the peer would report a tamper on a message nobody touched.");
+        }
+        return saltedContentHash(opts.salt, content);
+    }
+    throw new Error(`CONTENT HASH: unknown algorithm "${opts.alg}". This daemon cannot reproduce it, so there is no value to ` +
+        "compare against. Refusing rather than falling back to sha256, which would compare two unrelated hashes " +
+        "and report a tamper for what is a version difference.");
+}
+/**
+ * Domain-separation prefix. Fixed at `0x00` for ALL content frames — see the header on why this is
+ * not the leaf kind.
+ */
+const CONTENT_HASH_DOMAIN = new Uint8Array([0x00]);
+/** The hash a sender puts on the wire and the receiver recomputes to authenticate it. */
+export function wireContentHash(content) {
+    return new Uint8Array(createHash("sha256").update(CONTENT_HASH_DOMAIN).update(content).digest());
+}
+//# sourceMappingURL=wire-content-hash.js.map

package/dist/wire-content-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-content-hash.js","sourceRoot":"","sources":["../src/wire-content-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,0GAA0G;IAC1G,MAAM,EAAE,QAAQ;IAChB,+FAA+F;IAC/F,YAAY,EAAE,qBAAqB;CAC3B,CAAC;AAIX,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAErE,qEAAqE;AACrE,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,OAAO,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA8B;IAE9B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,iBAAiB,CAAC,MAAM,EAAE,CAAC;IAC1F,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAmB,EACnB,IAA8C;IAE9C,IAAI,IAAI,CAAC,GAAG,KAAK,iBAAiB,CAAC,MAAM;QAAE,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;IAC3E,IAAI,IAAI,CAAC,GAAG,KAAK,iBAAiB,CAAC,YAAY,EAAE,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,iBAAiB,iBAAiB,CAAC,YAAY,uDAAuD;gBACtG,uGAAuG;gBACvG,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,IAAI,KAAK,CACb,oCAAoC,IAAI,CAAC,GAAG,8DAA8D;QAC1G,yGAAyG;QACzG,uDAAuD,CACxD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,mBAAmB,GAAG,IAAI,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAEnD,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAAC,OAAmB;IACjD,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACnG,CAAC"}

package/dist/withheld-content.d.ts

@@ -0,0 +1,13 @@
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+/** The close-time form: the check guards a close, so it must never be the thing that breaks one. */
+export declare function withheldPositionsOrNone(db: DaemonDatabase | null | undefined, logger: {
+    warn(event: string, ctx?: Record<string, unknown>): void;
+}, args: () => Parameters<typeof withheldPositions>[1]): number[];
+export declare function withheldPositions(db: DaemonDatabase, a: {
+    agentId: string;
+    agentPubkeyHex: string;
+    sessionId: string;
+    relaySessionHex: string;
+    upToSeq: number;
+}): number[];
+//# sourceMappingURL=withheld-content.d.ts.map

package/dist/withheld-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withheld-content.d.ts","sourceRoot":"","sources":["../src/withheld-content.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKxD,oGAAoG;AACpG,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EACrC,MAAM,EAAE;IAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAAE,EACpE,IAAI,EAAE,MAAM,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAClD,MAAM,EAAE,CAQV;AAED,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,cAAc,EAClB,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1G,MAAM,EAAE,CAqBV"}

package/dist/withheld-content.js

@@ -0,0 +1,46 @@
+/**
+ * Positions the other side filed with the relay whose MESSAGE this side never received.
+ *
+ * The relay announces a leaf (its hash and the author's signed Structure 1) separately from the
+ * message itself. If the other side files a hash and withholds the content, this side's
+ * "last seen" can move past a message it does not hold. A close signed then claims that position
+ * while the local tree lacks the message, so both seals fail at the directory. Checking before the
+ * close is signed lets it refuse by name instead.
+ */
+import { decodeStructure1 } from "@cello-protocol/protocol-types";
+import { extractErrorMessage } from "./error-message.js";
+const LEAF_KIND_MSG = 0;
+/** The close-time form: the check guards a close, so it must never be the thing that breaks one. */
+export function withheldPositionsOrNone(db, logger, args) {
+    if (!db)
+        return [];
+    try {
+        return withheldPositions(db, args());
+    }
+    catch (err) {
+        logger.warn("session.seal.withheld_check.failed", { reason: extractErrorMessage(err) });
+        return [];
+    }
+}
+export function withheldPositions(db, a) {
+    for (const t of ["session_seal_leaves", "session_tree_leaves"]) {
+        if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(t) === undefined)
+            return [];
+    }
+    const held = new Set(db.prepare("SELECT leaf_hash_hex AS h FROM session_tree_leaves WHERE agent_id = ? AND session_id = ?")
+        .all(a.agentId, a.sessionId).map((r) => r.h));
+    const missing = [];
+    for (const r of db
+        .prepare(`SELECT sequence_number AS seq, structure1_cbor AS s1 FROM session_seal_leaves
+        WHERE agent_pubkey = ? AND session_id = ? AND leaf_kind = ? AND sequence_number <= ?
+        ORDER BY sequence_number`)
+        .all(a.agentPubkeyHex, a.relaySessionHex, LEAF_KIND_MSG, a.upToSeq)) {
+        const d = decodeStructure1(r.s1 instanceof Uint8Array ? r.s1 : new Uint8Array(r.s1));
+        if (!d.ok || Buffer.from(d.fields.senderPubkey).toString("hex") === a.agentPubkeyHex)
+            continue;
+        if (!held.has(Buffer.from(d.fields.contentHash).toString("hex")))
+            missing.push(r.seq);
+    }
+    return missing;
+}
+//# sourceMappingURL=withheld-content.js.map

package/dist/withheld-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withheld-content.js","sourceRoot":"","sources":["../src/withheld-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,oGAAoG;AACpG,MAAM,UAAU,uBAAuB,CACrC,EAAqC,EACrC,MAAoE,EACpE,IAAmD;IAEnD,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IACnB,IAAI,CAAC;QACH,OAAO,iBAAiB,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC,oCAAoC,EAAE,EAAE,MAAM,EAAE,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,EAAkB,EAClB,CAA2G;IAE3G,KAAK,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,EAAE,CAAC;QAC/D,IAAI,EAAE,CAAC,OAAO,CAAC,+DAA+D,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;IAClH,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CACjB,EAAE,CAAC,OAAO,CAAC,0FAA0F,CAAC;SACpG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CACxE,CAAC;IACF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,EAAE;SACf,OAAO,CACN;;iCAE2B,CAC5B;SACA,GAAG,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,eAAe,EAAE,aAAa,EAAE,CAAC,CAAC,OAAO,CAA2C,EAAE,CAAC;QAChH,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,EAAE,YAAY,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrF,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,cAAc;YAAE,SAAS;QAC/F,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/witness-alerts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * CELLO Daemon — WHAT A RELAY SAID IT SAW, AND WHETHER IT AGREES WITH US
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE. A relay witnesses message order; when
+ * what it reports does not reconcile with this side's record, that is an alert an operator has to be
+ * able to read.
+ *
+ * Moved verbatim, comments included.
+ *
+ * ⚠️ THE LIST IS BOUNDED AND IT IS FED BY A REMOTE PARTY, which is why it is capped and why the cap
+ * reports its own truncation rather than silently dropping the tail. An alert list that quietly
+ * stopped growing would understate exactly the situation it exists to report.
+ */
+import type { Logger } from "./types.js";
+import type { WitnessAlertNotice } from "./session-node-types.js";
+import type { RelayWitnessAlert } from "./session-relay-client.js";
+/** What the witness-alert record needs from the manager. */
+export interface WitnessAlertContext {
+    readonly logger: Logger;
+}
+export declare class WitnessAlerts {
+    #private;
+    constructor(ctx: WitnessAlertContext);
+    /**
+     * Record what one relay says it saw on one of this agent's sessions, for the operator to read.
+     *
+     * ⚠️ **IT DOES NOT FREEZE THE SESSION, AND THAT IS THE DESIGN.** A client freezing on its OWN
+     * verification is safe: it limits only what that client trusts. Freezing on a REMOTE party's
+     * say-so hands any single relay the power to end any conversation it carries, and to write an
+     * accusatory record about a counterparty who did nothing. The identity freeze stays where it is —
+     * on this daemon's own check of an inbound frame — and this surfaces a second, independent
+     * observation next to it. One witness reports; it does not rule.
+     */
+    recordRelayWitnessAlert(agentName: string, alert: RelayWitnessAlert): void;
+    /** The witness alerts an agent has been told about, oldest first, one row per witness+session. */
+    getWitnessAlerts(agentName: string): ReadonlyArray<WitnessAlertNotice>;
+    /** Whether this agent's alert list hit its cap, so the inbox can say the list is incomplete. */
+    witnessAlertsTruncated(agentName: string): boolean;
+}
+//# sourceMappingURL=witness-alerts.d.ts.map

package/dist/witness-alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness-alerts.d.ts","sourceRoot":"","sources":["../src/witness-alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAaD,qBAAa,aAAa;;gBAGZ,GAAG,EAAE,mBAAmB;IAwBpC;;;;;;;;;OASG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI;IA6C1E,kGAAkG;IAClG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,kBAAkB,CAAC;IAGtE,gGAAgG;IAChG,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CAGnD"}

package/dist/witness-alerts.js

@@ -0,0 +1,102 @@
+/**
+ * ⚠️ **THE CAP KEEPS THE FIRST, NOT THE LAST** — review F1, and the direction is the whole point.
+ *
+ * The relay's own queue drops the NEWEST when full, precisely so a flood cannot push the first
+ * real observation out. This list did the opposite (`slice(-20)`), which handed the mute button
+ * straight back one layer up: at the relay's 120-submits-per-minute limit, about ten seconds of
+ * fabricated alerts evicted the genuine one before any operator read it. Repeats of one event also
+ * collapse — see the dedupe in `recordRelayWitnessAlert` — so a flood cannot even fill it.
+ */
+const WITNESS_ALERT_CAP = 20;
+export class WitnessAlerts {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /**
+     * DOD-M15-CORROBORATE-1: witness alerts this agent's relays have reported, oldest first, capped.
+     *
+     * ⚠️ **IN MEMORY, AND A DAEMON RESTART LOSES THEM** — review F4. This comment used to say a relay
+     * that still holds the observation re-delivers it on the next connection. It does not:
+     * `drainWitnessAlerts` splices, so once an alert has been delivered the relay no longer holds it.
+     * Nothing here is a durable record of anything; the relay operator's own log is, and so is the
+     * signature on the alert, which the operator can keep. Said plainly rather than left as an implied
+     * guarantee.
+     *
+     * Nothing clears the list before that restart, and that is deliberate: an alert an operator can
+     * silence is one an attacker can wait out.
+     */
+    #witnessAlerts = new Map();
+    /**
+     * Agents whose alert list hit the cap — fallback-finder LOW 2. Without this the inbox renders a
+     * full list that looks complete, and "twenty alerts" is indistinguishable from "twenty of some
+     * larger number". A marker the operator can see costs one boolean.
+     */
+    #witnessTruncated = new Set();
+    /**
+     * Record what one relay says it saw on one of this agent's sessions, for the operator to read.
+     *
+     * ⚠️ **IT DOES NOT FREEZE THE SESSION, AND THAT IS THE DESIGN.** A client freezing on its OWN
+     * verification is safe: it limits only what that client trusts. Freezing on a REMOTE party's
+     * say-so hands any single relay the power to end any conversation it carries, and to write an
+     * accusatory record about a counterparty who did nothing. The identity freeze stays where it is —
+     * on this daemon's own check of an inbound frame — and this surfaces a second, independent
+     * observation next to it. One witness reports; it does not rule.
+     */
+    recordRelayWitnessAlert(agentName, alert) {
+        const list = this.#witnessAlerts.get(agentName) ?? [];
+        /**
+         * ONE ROW PER (WITNESS, SESSION) — review F1's second half. A relay reports every refused
+         * submission, and a determined submitter can produce a great many; twenty rows saying the same
+         * thing is not twenty facts, it is one fact and nineteen ways to push another one off the list.
+         * The repeat updates the count and the last-seen time and leaves the row where it is.
+         */
+        /**
+         * Keyed on the relay's PEER ID, not on `relayId` — fallback-finder LOW 1. `relayId` is absent
+         * for any relay that could not sign, so two DIFFERENT such relays reporting on one session
+         * collapsed into a single row and the operator read one witness where there were two. The peer
+         * id is the transport identity this client is actually talking to and is always known.
+         */
+        const key = `${alert.witnessPeerId}::${alert.sessionIdHex}`;
+        const existing = list.find((n) => n.key === key);
+        if (existing) {
+            existing.occurrences += 1;
+            existing.lastObservedAt = alert.observedAt;
+            // A later repeat that IS verifiable upgrades the row: the operator should end up holding the
+            // strongest form of the claim they were sent, never the weakest one that arrived first.
+            existing.alert = alert.verifiable ? alert : existing.alert;
+            // `firstObservedAt` is deliberately untouched — see its note on the type.
+        }
+        else if (list.length >= WITNESS_ALERT_CAP) {
+            // Keep the first. See the cap's own note for why this direction is load-bearing.
+            this.#witnessTruncated.add(agentName);
+            this.#ctx.logger.warn("session.witness.alert.list_full", {
+                agentName, held: list.length,
+                impact: "this alert was not recorded; the earlier ones are kept and still shown, and the " +
+                    "inbox now says the list is incomplete rather than looking whole",
+            });
+            return;
+        }
+        else {
+            list.push({ key, alert, occurrences: 1, firstObservedAt: alert.observedAt, lastObservedAt: alert.observedAt });
+        }
+        this.#witnessAlerts.set(agentName, list);
+        this.#ctx.logger.error("session.witness.alert.recorded", {
+            agentName,
+            sessionId: alert.sessionIdHex,
+            relayId: alert.relayId ?? "(unnamed)",
+            submitterIsCounterparty: alert.submitterIsCounterparty,
+            verifiable: alert.verifiable,
+            impact: "surfaced to the operator on the next cello_inbox; the session is NOT frozen by it",
+        });
+    }
+    /** The witness alerts an agent has been told about, oldest first, one row per witness+session. */
+    getWitnessAlerts(agentName) {
+        return this.#witnessAlerts.get(agentName) ?? [];
+    }
+    /** Whether this agent's alert list hit its cap, so the inbox can say the list is incomplete. */
+    witnessAlertsTruncated(agentName) {
+        return this.#witnessTruncated.has(agentName);
+    }
+}
+//# sourceMappingURL=witness-alerts.js.map

package/dist/witness-alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness-alerts.js","sourceRoot":"","sources":["../src/witness-alerts.ts"],"names":[],"mappings":"AAsBA;;;;;;;;GAQG;AACH,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,MAAM,OAAO,aAAa;IACf,IAAI,CAAsB;IAEnC,YAAY,GAAwB;QAClC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;OAYG;IACM,cAAc,GAAG,IAAI,GAAG,EAAgC,CAAC;IAClE;;;;OAIG;IACM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/C;;;;;;;;;OASG;IACH,uBAAuB,CAAC,SAAiB,EAAE,KAAwB;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACtD;;;;;WAKG;QACH;;;;;WAKG;QACH,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,aAAa,KAAK,KAAK,CAAC,YAAY,EAAE,CAAC;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;QACjD,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,WAAW,IAAI,CAAC,CAAC;YAC1B,QAAQ,CAAC,cAAc,GAAG,KAAK,CAAC,UAAU,CAAC;YAC3C,6FAA6F;YAC7F,wFAAwF;YACxF,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;YAC3D,0EAA0E;QAC5E,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,IAAI,iBAAiB,EAAE,CAAC;YAC5C,iFAAiF;YACjF,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE;gBACvD,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM;gBAC5B,MAAM,EAAE,kFAAkF;oBACxF,iEAAiE;aACpE,CAAC,CAAC;YACH,OAAO;QACT,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,UAAU,EAAE,cAAc,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QACjH,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE;YACvD,SAAS;YACT,SAAS,EAAE,KAAK,CAAC,YAAY;YAC7B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,WAAW;YACrC,uBAAuB,EAAE,KAAK,CAAC,uBAAuB;YACtD,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,mFAAmF;SAC5F,CAAC,CAAC;IACL,CAAC;IACD,kGAAkG;IAClG,gBAAgB,CAAC,SAAiB;QAChC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IAClD,CAAC;IACD,gGAAgG;IAChG,sBAAsB,CAAC,SAAiB;QACtC,OAAO,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cello-protocol/daemon",
-  "version": "0.0.227",
+  "version": "0.0.229",
   "private": false,
   "type": "module",
   "engines": {
@@ -35,10 +35,10 @@
     "@signalapp/sqlcipher": "^3.3.5",
     "cbor-x": "^1.6.0",
     "it-length-prefixed": "^10.0.1",
-    "@cello-protocol/crypto": "0.0.95",
-    "@cello-protocol/transport": "0.0.101",
-    "@cello-protocol/gateway": "0.0.80",
-    "@cello-protocol/protocol-types": "0.0.99"
+    "@cello-protocol/crypto": "0.0.97",
+    "@cello-protocol/protocol-types": "0.0.101",
+    "@cello-protocol/transport": "0.0.103",
+    "@cello-protocol/gateway": "0.0.82"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",