@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/relay-receipt-store.js

@@ -0,0 +1,284 @@
+/**
+ * CELLO Daemon — RelayReceiptStore (DOD-M15-ORDERPROOF-1, was M8B DOD-RELAYSIG-1)
+ *
+ * The relay is the ordering/witness authority: it assigns a canonical sequence number to each submitted
+ * content-hash leaf and signs an ATTESTATION over it (relay-node `buildRelayAckTbs`). This store is the
+ * client's IMMUTABLE record of those signed attestations — durable evidence that the relay assigned a
+ * specific sequence to a specific hash at a specific time. The receipt is what lets the client later prove
+ * (or dispute) the relay's ordering, and is the building block the client carries to the directory at seal
+ * time (OPTIONB-SEAL-1) instead of the directory dialing the relay.
+ *
+ * Verification is an Ed25519 check that MUST stay byte-compatible with the relay's signer.
+ *
+ * ⚠️ **THE KEY IT IS CHECKED AGAINST IS THE POINT — 069-ORDERPROOF.** This module used to verify the
+ * signature against `relay_id`, a key carried inside the very frame being checked, and its own comment
+ * called that "SELF-CONSISTENCY". It is not a check: anyone who can write the frame can mint a key, sign
+ * any ordering they like with it, and put the key in the field we verify against. The key now comes from
+ * `relay_id` on the **directory-signed `SessionAssignment`**, which is inside the FROST-signed TBS the
+ * client already verifies — something neither the relay nor either participant can rewrite.
+ *
+ * ⚠️ **AND ABSENT IS NOT FINE.** Missing, malformed and mismatched are ONE outcome (`refused`), because
+ * a party holding no attestation for a message is in exactly the state a corrupted one leaves them in.
+ * Whoever can cause the absence must not get a softer answer than whoever can cause the corruption — and
+ * the party who can cause the absence is the relay, the party the check exists to constrain.
+ *
+ * IMMUTABILITY (SI-003): the unique unit of a relay attestation is a POSITION — (agent, session, sequence)
+ * — not a content hash. The same plaintext ("ok") legitimately produces the same content hash at DIFFERENT
+ * sequences (per-session relay counter; repeated content within a session), so the table is keyed on the
+ * position with the hash as payload. `INSERT OR IGNORE` then defends the real threat — a relay rewriting the
+ * hash it recorded for an already-assigned (session, sequence) — while never dropping a legitimate
+ * attestation for repeated content (code review HIGH).
+ *
+ * Crypto: Ed25519 (RFC 8032), SHA-256 (FIPS 180-4). TBS = SHA-256(hash_bytes || seq_BE4 || ts_BE8).
+ */
+import { verify, buildRelayAckTbs } from "@cello-protocol/crypto";
+import { decodeStructure1 } from "@cello-protocol/protocol-types";
+/**
+ * Verify a relay ordering attestation against a relay pubkey the CALLER supplies — and the caller
+ * must have got it from the directory-signed assignment, never from the frame.
+ *
+ * Returns true iff every field is well-formed and the 64-byte Ed25519 signature verifies over
+ * TBS = SHA-256(DOMAIN ‖ session_id ‖ content_hash ‖ seq_BE4 ‖ running_root ‖ ts_BE8) — the same
+ * statement the relay signs. A forged sequence, a swapped session or a rewritten prefix all change
+ * the TBS, so each fails.
+ *
+ * A wrong-length field returns FALSE rather than throwing: these bytes come off a wire the relay
+ * controls, and a malformed length must refuse this attestation, not take down the frame handler.
+ */
+export function verifyRelayAck(sessionId, contentHash, sequenceNumber, runningRoot, timestamp, signature, relayPubkey) {
+    if (signature.length !== 64)
+        return false;
+    if (sessionId.length !== 16 || contentHash.length !== 32 || runningRoot.length !== 32)
+        return false;
+    const tbs = buildRelayAckTbs(sessionId, contentHash, sequenceNumber, runningRoot, timestamp);
+    return verify(relayPubkey, tbs, signature);
+}
+/**
+ * Read back the leaf we just submitted, so the relay's attestation has something to be checked
+ * against — the step BEFORE `evaluateRelayAck`, and the one that decides whether the check can run
+ * at all.
+ *
+ * ⚠️ "COULD NOT RUN THE CHECK" IS NOT "THE CHECK PASSED" — 069-ORDERPROOF.
+ *
+ * Both failures here used to be waved through by the caller, which settled the send `ok` having
+ * verified nothing: the absent-versus-verified collapse this unit exists to remove, reproduced at
+ * the one point where nothing was left to verify with. These are our OWN just-signed bytes, so a
+ * hostile relay cannot steer into either — unreachable in practice, which is a different claim from
+ * safe to wave through, and the distinction is the one that decays under later edits.
+ *
+ * `"none"` is the honest third answer: no submit was made, so no attestation is owed and none is
+ * missing. It is the only one of the three that does not reject.
+ */
+export function readSubmittedLeaf(structure1Cbor, seq) {
+    if (seq < 0)
+        return { kind: "none" };
+    if (!structure1Cbor)
+        return { kind: "unreadable", event: "relay.receipt.leaf_absent" };
+    // Structure 1 = [version, content_hash(32), sender_pubkey(32), session_id(16), last_seen_seq, ts],
+    // plus last_seen_hash(32) at index 6 on a v2 claim (020-ACKHASH). content_hash is index 1 and
+    // session_id index 3 in both.
+    const s1 = decodeStructure1(structure1Cbor);
+    // The reason is carried because "we cannot read what we just wrote" and "we wrote a layout we
+    // cannot name" are different faults with the same symptom.
+    if (!s1.ok)
+        return { kind: "unreadable", event: "relay.receipt.undecodable_leaf", reason: s1.reason };
+    return { kind: "ok", contentHash: s1.fields.contentHash, sessionId: s1.fields.sessionId };
+}
+/**
+ * Evaluate a relay ordering attestation: decide whether it yields a storable, signature-verified
+ * receipt. This is the verify-gates-store decision in isolation, so it is unit-testable without the
+ * relay stream.
+ *
+ * `expectedRelayPubkeyHex` is the anchor and it is REQUIRED in substance: `undefined` refuses. It
+ * must come from `relay_id` on an assignment whose FROST signature has been verified.
+ */
+export function evaluateRelayAck(params) {
+    const { sessionId, contentHash, runningRoot, sessionIdHex, agentPubkeyHex, expectedRelayPubkeyHex, relayId, relaySignature, timestamp, sequenceNumber, } = params;
+    if (!expectedRelayPubkeyHex || !/^[0-9a-fA-F]{64}$/.test(expectedRelayPubkeyHex)) {
+        return { kind: "refused", cause: "no_anchor" };
+    }
+    /**
+     * THE FRAME'S OWN CLAIM IS COMPARED, NEVER TRUSTED. The signature below is verified against the
+     * directory's key regardless, so this comparison adds no security on its own — what it adds is a
+     * NAMED cause. A relay that has been replaced mid-session produces a valid signature under a key
+     * the directory never named, and "this is not the relay you were assigned" is the sentence an
+     * operator can act on. `undefined` is not a mismatch: a relay omitting the field does not get to
+     * skip the check, it simply gets checked against the anchor with no label.
+     */
+    if (relayId !== undefined) {
+        if (!/^[0-9a-fA-F]{64}$/.test(relayId))
+            return { kind: "refused", cause: "bad_relay_id" };
+        if (relayId.toLowerCase() !== expectedRelayPubkeyHex.toLowerCase()) {
+            return { kind: "refused", cause: "relay_not_assigned" };
+        }
+    }
+    if (!relaySignature || timestamp === undefined || !runningRoot) {
+        return { kind: "refused", cause: "attestation_absent" };
+    }
+    const relayPubkey = new Uint8Array(Buffer.from(expectedRelayPubkeyHex, "hex"));
+    if (!verifyRelayAck(sessionId, contentHash, sequenceNumber, runningRoot, timestamp, relaySignature, relayPubkey)) {
+        return { kind: "refused", cause: "signature_invalid" };
+    }
+    return {
+        kind: "store",
+        receipt: {
+            hashHex: Buffer.from(contentHash).toString("hex"),
+            agentPubkeyHex,
+            sessionIdHex,
+            relayId: expectedRelayPubkeyHex,
+            relayPubkeyHex: expectedRelayPubkeyHex,
+            sequenceNumber,
+            timestamp,
+            signatureHex: Buffer.from(relaySignature).toString("hex"),
+            runningRootHex: Buffer.from(runningRoot).toString("hex"),
+        },
+    };
+}
+const CREATE_RELAY_RECEIPTS_SQL = `
+  CREATE TABLE IF NOT EXISTS relay_ack_receipts (
+    agent_pubkey     TEXT    NOT NULL,
+    session_id       TEXT    NOT NULL,
+    sequence_number  INTEGER NOT NULL,
+    hash_hex         TEXT    NOT NULL,
+    relay_id         TEXT    NOT NULL,
+    relay_pubkey_hex TEXT    NOT NULL,
+    relay_timestamp  INTEGER NOT NULL,
+    signature_hex    TEXT    NOT NULL,
+    stored_at        INTEGER NOT NULL,
+    -- 069-ORDERPROOF: the running root the relay signed alongside the position (nullable — rows
+    -- written before this order have none, and they stay readable and sealable exactly as they are).
+    running_root_hex TEXT,
+    -- FED-OPTIONB-SEAL-001: per-leaf carry bytes for the unilateral-seal offline rebuild (nullable).
+    structure2_cbor  BLOB,
+    structure1_cbor  BLOB,
+    leaf_kind        INTEGER,
+    PRIMARY KEY (agent_pubkey, session_id, sequence_number)
+  );
+`;
+export class RelayReceiptStore {
+    #db;
+    #logger;
+    constructor(db, logger) {
+        this.#db = db;
+        this.#logger = logger;
+        this.#db.exec(CREATE_RELAY_RECEIPTS_SQL);
+        this.#migrateSealCarryColumns();
+    }
+    /**
+     * FED-OPTIONB-SEAL-001: add the per-leaf carry columns to a relay_ack_receipts table created before the
+     * seal-carry feature (CREATE TABLE IF NOT EXISTS leaves an existing table untouched). Idempotent + safe:
+     * each column is added only if absent (checked via PRAGMA table_info), and all three are NULLABLE so the
+     * ALTER never rewrites or invalidates existing rows. Pre-migration receipts simply have no carry bytes
+     * (getSealLeaves omits them). No data is read/destroyed — pure additive schema evolution.
+     */
+    #migrateSealCarryColumns() {
+        const cols = new Set(this.#db.prepare(`PRAGMA table_info(relay_ack_receipts)`).all().map((c) => c.name));
+        for (const [name, decl] of [
+            ["structure2_cbor", "BLOB"],
+            ["structure1_cbor", "BLOB"],
+            ["leaf_kind", "INTEGER"],
+            // 069-ORDERPROOF. NULLABLE, like the three above: a session that predates this order keeps
+            // every receipt it already holds, opens, reads and seals unchanged, and simply has no root
+            // recorded for those positions.
+            ["running_root_hex", "TEXT"],
+        ]) {
+            if (!cols.has(name)) {
+                this.#db.exec(`ALTER TABLE relay_ack_receipts ADD COLUMN ${name} ${decl}`);
+            }
+        }
+    }
+    /**
+     * Persist a VERIFIED receipt. IMMUTABLE: keyed on the attestation POSITION (agent, session, sequence) —
+     * `INSERT OR IGNORE` keeps the FIRST hash recorded for a position, so a relay cannot rewrite the hash it
+     * already attested at that (session, sequence). Returns true if a new row was written, false if the
+     * position was already recorded (logged distinctly when the existing hash DIFFERS — a relay equivocation).
+     */
+    store(receipt, storedAtMs) {
+        const existing = this.get(receipt.agentPubkeyHex, receipt.sessionIdHex, receipt.sequenceNumber);
+        const info = this.#db
+            .prepare(`INSERT OR IGNORE INTO relay_ack_receipts
+           (agent_pubkey, session_id, sequence_number, hash_hex, relay_id, relay_pubkey_hex, relay_timestamp, signature_hex, stored_at, structure2_cbor, structure1_cbor, leaf_kind, running_root_hex)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(receipt.agentPubkeyHex, receipt.sessionIdHex, receipt.sequenceNumber, receipt.hashHex, receipt.relayId, receipt.relayPubkeyHex, receipt.timestamp, receipt.signatureHex, storedAtMs, 
+        // FED-OPTIONB-SEAL-001: carry bytes (null when absent — receipt-only rows).
+        receipt.structure2Cbor ? Buffer.from(receipt.structure2Cbor) : null, receipt.structure1Cbor ? Buffer.from(receipt.structure1Cbor) : null, receipt.leafKind ?? null, receipt.runningRootHex ?? null);
+        const wrote = Number(info.changes) > 0;
+        if (!wrote && existing && existing.hashHex !== receipt.hashHex) {
+            // EQUIVOCATION: a relay re-attesting a DIFFERENT hash at an already-recorded position. The first
+            // verified receipt stands; surface the conflict loudly (it is an attack/misbehavior signal).
+            this.#logger.warn("relay.receipt.equivocation", {
+                agentShort: receipt.agentPubkeyHex.slice(0, 16),
+                sessionShort: receipt.sessionIdHex.slice(0, 16),
+                seq: receipt.sequenceNumber,
+                recordedHashShort: existing.hashHex.slice(0, 16),
+                conflictingHashShort: receipt.hashHex.slice(0, 16),
+            });
+        }
+        return wrote;
+    }
+    /** The stored receipt at an attestation position (agent, session, sequence), or undefined. */
+    get(agentPubkeyHex, sessionIdHex, sequenceNumber) {
+        const row = this.#db
+            .prepare(`SELECT agent_pubkey, session_id, sequence_number, hash_hex, relay_id, relay_pubkey_hex, relay_timestamp, signature_hex, running_root_hex
+           FROM relay_ack_receipts WHERE agent_pubkey = ? AND session_id = ? AND sequence_number = ?`)
+            .get(agentPubkeyHex, sessionIdHex, sequenceNumber);
+        return row ? this.#rowToReceipt(row) : undefined;
+    }
+    /** All receipts for an agent (optionally a single session), in canonical sequence order (ascending). */
+    getAll(agentPubkeyHex, sessionIdHex) {
+        const rows = sessionIdHex
+            ? this.#db
+                .prepare(`SELECT agent_pubkey, session_id, sequence_number, hash_hex, relay_id, relay_pubkey_hex, relay_timestamp, signature_hex, running_root_hex
+               FROM relay_ack_receipts WHERE agent_pubkey = ? AND session_id = ? ORDER BY sequence_number ASC`)
+                .all(agentPubkeyHex, sessionIdHex)
+            : this.#db
+                .prepare(`SELECT agent_pubkey, session_id, sequence_number, hash_hex, relay_id, relay_pubkey_hex, relay_timestamp, signature_hex, running_root_hex
+               FROM relay_ack_receipts WHERE agent_pubkey = ? ORDER BY session_id, sequence_number ASC`)
+                .all(agentPubkeyHex);
+        return rows.map((r) => this.#rowToReceipt(r));
+    }
+    /**
+     * FED-OPTIONB-SEAL-001: the complete carried leaf chain for a session's UNILATERAL seal — every receipt
+     * that has its Structure2/Structure1 carry bytes, ordered by canonical sequence. The directory rebuilds +
+     * verifies this tree OFFLINE (no directory→relay getSealLeaves dial). Rows without carry bytes
+     * (pre-migration / receipt-only) are omitted: the caller carries only what the directory can rebuild.
+     */
+    getSealLeaves(agentPubkeyHex, sessionIdHex) {
+        const rows = this.#db
+            .prepare(`SELECT agent_pubkey, session_id, sequence_number, hash_hex, relay_id, relay_pubkey_hex, relay_timestamp, signature_hex, running_root_hex, structure2_cbor, structure1_cbor, leaf_kind
+           FROM relay_ack_receipts
+          WHERE agent_pubkey = ? AND session_id = ? AND structure2_cbor IS NOT NULL AND structure1_cbor IS NOT NULL AND leaf_kind IS NOT NULL
+          ORDER BY sequence_number ASC`)
+            .all(agentPubkeyHex, sessionIdHex);
+        return rows.map((r) => ({
+            ...this.#rowToReceipt(r),
+            structure2Cbor: toU8(r.structure2_cbor),
+            structure1Cbor: toU8(r.structure1_cbor),
+            leafKind: r.leaf_kind,
+        }));
+    }
+    #rowToReceipt(row) {
+        return {
+            hashHex: row.hash_hex,
+            agentPubkeyHex: row.agent_pubkey,
+            sessionIdHex: row.session_id,
+            relayId: row.relay_id,
+            relayPubkeyHex: row.relay_pubkey_hex,
+            sequenceNumber: row.sequence_number,
+            timestamp: row.relay_timestamp,
+            signatureHex: row.signature_hex,
+            ...(typeof row.running_root_hex === "string" ? { runningRootHex: row.running_root_hex } : {}),
+        };
+    }
+}
+/** Normalize a SQLite BLOB column (Buffer/Uint8Array/ArrayBuffer) to a Uint8Array. */
+function toU8(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (Buffer.isBuffer(v))
+        return new Uint8Array(v);
+    if (v instanceof ArrayBuffer)
+        return new Uint8Array(v);
+    return new Uint8Array();
+}
+//# sourceMappingURL=relay-receipt-store.js.map

package/dist/relay-receipt-store.js.map

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

package/dist/relay-reconnect.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Keep re-dialling a lost relay stream while something still depends on it.
+ *
+ * The relay client made ONE reconnect attempt when its reader ended. Live 2026-09-15: a laptop woke,
+ * the reader ended, and that attempt ran before the network was back. Nothing dialled again — only
+ * a send re-dials, and a receiving agent has nothing to send — so three messages sent during the
+ * sleep never arrived as `leaf_deliver`. The delay doubles to a one-minute ceiling: one dial a minute
+ * per relay costs nothing, and a stream that never returns is a conversation that silently stops.
+ *
+ * A REFUSAL is not a network drop, and must not read like one. When the relay answered and said no,
+ * it is logged at error (once per distinct reason) and the loop drops straight to the ceiling. It
+ * does not stop: the commonest refusal is an expired online token, which the next signaling
+ * reconnect replaces, and the client reads the token fresh at every auth.
+ */
+import type { Logger } from "./types.js";
+export declare const RELAY_RECONNECT_BASE_MS = 2000;
+export declare const RELAY_RECONNECT_MAX_MS = 60000;
+export declare function reconnectWithBackoff(opts: {
+    relayPeerId: string;
+    logger: Logger;
+    /** One pass over every node that could dial. True when the stream is back. */
+    connectOnce: () => Promise<boolean>;
+    /** The refusal the last attempt ended on, if the relay answered at all. */
+    refusal: () => {
+        reason: string;
+        advice: string;
+    } | null;
+    /** Closed, already connected, or no session left to deliver to. */
+    shouldStop: () => boolean;
+    baseMs: number;
+}): Promise<void>;
+//# sourceMappingURL=relay-reconnect.d.ts.map

package/dist/relay-reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-reconnect.d.ts","sourceRoot":"","sources":["../src/relay-reconnect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,2EAA2E;IAC3E,OAAO,EAAE,MAAM;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,mEAAmE;IACnE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB"}

package/dist/relay-reconnect.js

@@ -0,0 +1,29 @@
+export const RELAY_RECONNECT_BASE_MS = 2_000;
+export const RELAY_RECONNECT_MAX_MS = 60_000;
+export async function reconnectWithBackoff(opts) {
+    const { relayPeerId, logger } = opts;
+    // Floored at 1ms: a zero base doubles to zero and the loop would spin flat out.
+    let delay = Math.max(opts.baseMs, 1);
+    let lastRefusal;
+    for (let attempt = 1; !opts.shouldStop(); attempt++) {
+        if (await opts.connectOnce())
+            return;
+        const refused = opts.refusal();
+        if (refused) {
+            if (refused.reason !== lastRefusal) {
+                logger.error("session.relay.reconnect.refused", {
+                    relayPeerId, reason: refused.reason, advice: refused.advice,
+                    impact: "the relay answered and refused, so this is not a network drop; retrying once a minute in case it clears",
+                });
+            }
+            lastRefusal = refused.reason;
+            delay = RELAY_RECONNECT_MAX_MS;
+        }
+        if (opts.shouldStop())
+            return;
+        logger.info("session.relay.reconnect.scheduled", { relayPeerId, attempt, retryInMs: delay });
+        await new Promise((r) => { setTimeout(r, delay).unref?.(); });
+        delay = Math.min(delay * 2, RELAY_RECONNECT_MAX_MS);
+    }
+}
+//# sourceMappingURL=relay-reconnect.js.map

package/dist/relay-reconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-reconnect.js","sourceRoot":"","sources":["../src/relay-reconnect.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAC7C,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAU1C;IACC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACrC,gFAAgF;IAChF,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrC,IAAI,WAA+B,CAAC;IACpC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,MAAM,IAAI,CAAC,WAAW,EAAE;YAAE,OAAO;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBACnC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;oBAC9C,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM;oBAC3D,MAAM,EAAE,yGAAyG;iBAClH,CAAC,CAAC;YACL,CAAC;YACD,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;YAC7B,KAAK,GAAG,sBAAsB,CAAC;QACjC,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,EAAE;YAAE,OAAO;QAC9B,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7F,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,GAAG,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

package/dist/reply-lag.d.ts

@@ -0,0 +1,11 @@
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+export interface ReplyLag {
+    /** How many of their latest replies in a row were written before they saw your message. */
+    replies: number;
+    /** The last position those replies say they had seen. */
+    their_last_seen_seq: number;
+    /** Your newest message they had not seen. */
+    your_unseen_seq: number;
+}
+export declare function replyLag(db: DaemonDatabase, agentPubkeyHex: string, sessionIdHex: string): ReplyLag | undefined;
+//# sourceMappingURL=reply-lag.d.ts.map

package/dist/reply-lag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply-lag.d.ts","sourceRoot":"","sources":["../src/reply-lag.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKxD,MAAM,WAAW,QAAQ;IACvB,2FAA2F;IAC3F,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CA4B/G"}

package/dist/reply-lag.js

@@ -0,0 +1,46 @@
+/**
+ * Is the other side replying to an old message?
+ *
+ * Every message signs the last position its author had seen. Reading the other side's latest
+ * replies against this side's newest message tells the operator, during the conversation, that they
+ * are answering something older. One crossed reply is ordinary back-and-forth; two in a row is the
+ * signal. Reads the seal leaf store, which holds both sides' signed Structure 1.
+ */
+import { decodeStructure1 } from "@cello-protocol/protocol-types";
+const LEAF_KIND_MSG = 0;
+const LAG_THRESHOLD = 2;
+export function replyLag(db, agentPubkeyHex, sessionIdHex) {
+    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'session_seal_leaves'").get() === undefined)
+        return undefined;
+    const rows = db
+        .prepare(`SELECT sequence_number AS seq, structure1_cbor AS s1 FROM session_seal_leaves
+        WHERE agent_pubkey = ? AND session_id = ? AND leaf_kind = ? ORDER BY sequence_number ASC`)
+        .all(agentPubkeyHex, sessionIdHex, LEAF_KIND_MSG);
+    const mine = [];
+    const theirs = [];
+    for (const r of rows) {
+        const d = decodeStructure1(r.s1 instanceof Uint8Array ? r.s1 : new Uint8Array(r.s1));
+        if (!d.ok)
+            continue;
+        if (Buffer.from(d.fields.senderPubkey).toString("hex") === agentPubkeyHex)
+            mine.push(r.seq);
+        else
+            theirs.push({ seq: r.seq, lastSeen: d.fields.lastSeenSeq });
+    }
+    if (mine.length === 0 || theirs.length < LAG_THRESHOLD)
+        return undefined;
+    let replies = 0;
+    let unseen = 0;
+    for (let i = theirs.length - 1; i >= 0; i--) {
+        const t = theirs[i];
+        const newestMineBefore = mine.filter((m) => m < t.seq).at(-1);
+        if (newestMineBefore === undefined || t.lastSeen >= newestMineBefore)
+            break;
+        replies += 1;
+        unseen = Math.max(unseen, newestMineBefore);
+    }
+    if (replies < LAG_THRESHOLD)
+        return undefined;
+    return { replies, their_last_seen_seq: theirs[theirs.length - 1].lastSeen, your_unseen_seq: unseen };
+}
+//# sourceMappingURL=reply-lag.js.map

package/dist/reply-lag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply-lag.js","sourceRoot":"","sources":["../src/reply-lag.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,aAAa,GAAG,CAAC,CAAC;AAWxB,MAAM,UAAU,QAAQ,CAAC,EAAkB,EAAE,cAAsB,EAAE,YAAoB;IACvF,IAAI,EAAE,CAAC,OAAO,CAAC,mFAAmF,CAAC,CAAC,GAAG,EAAE,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1I,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN;iGAC2F,CAC5F;SACA,GAAG,CAAC,cAAc,EAAE,YAAY,EAAE,aAAa,CAA2C,CAAC;IAC9F,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,MAAM,GAA6C,EAAE,CAAC;IAC5D,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,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;YAAE,SAAS;QACpB,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,cAAc;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;;YACvF,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,aAAa;QAAE,OAAO,SAAS,CAAC;IACzE,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;QACrB,MAAM,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,IAAI,gBAAgB,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,IAAI,gBAAgB;YAAE,MAAM;QAC5E,OAAO,IAAI,CAAC,CAAC;QACb,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,GAAG,aAAa;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;AACxG,CAAC"}

package/dist/resolve-named-agent.d.ts

@@ -0,0 +1,49 @@
+/**
+ * One guard for "the caller named an agent" — shared, so the third copy never gets written.
+ *
+ * DOD-INBOX-AGENT-1 closed a defect where `cello_check_notifications` accepted an `agent` parameter
+ * and silently dropped it, answering as whatever agent the CONNECTION held. Reviewing that fix found
+ * the same shape in three more places, including the one next door in `contact-handlers.ts`, where
+ * it is worse because that path WRITES: `cello_contact_add({ agent: "", pubkey })` fell through to
+ * the connection's selection and filed the contact under the wrong desk, and `{ agent: "carol" }`
+ * with no carol wrote a row keyed to an agent that does not exist. Both `ok: true`.
+ *
+ * The three ways a named agent goes wrong, and why each must REFUSE rather than fall back:
+ *
+ *  1. **A non-string** (`{ agent: 123 }`). MCP callers are shielded by zod; direct-IPC callers are
+ *     not. §5a is explicit that unreachability is a property of today's call graph, not of the code.
+ *  2. **An empty string.** `""` is falsy but not nullish, so a bare truthiness test reads it as "no
+ *     name given" and runs as the connection's selection — the exact misroute, reintroduced through
+ *     the guard meant to prevent it. `{ agent: someUnsetVar }` produces it, and so does an
+ *     unsubstituted `<exact name>` placeholder in a prompt.
+ *  3. **A name that is not here.** Falling back answers a question about carol with alice's data.
+ *
+ * And one that is NOT "not found": an agent whose identity FAILED TO LOAD exists. Saying "does not
+ * exist" sends the operator to `cello_agents`, which filters `load_failed` out — so they see nothing,
+ * confirm the wrong diagnosis, and never reach `cello_status`, which would have shown the real error.
+ * That is an exit-point label standing in for the cause.
+ */
+export interface NamedAgentRefusal {
+    ok: false;
+    reason: "invalid_agent_value" | "missing_agent_value" | "agent_not_found" | "agent_load_failed";
+    guidance: string;
+}
+/** What the resolver needs to know about the agents on this machine. */
+export interface KnownAgent {
+    name: string;
+    state?: string;
+    error?: string;
+}
+/**
+ * Validate an explicitly-named agent.
+ *
+ * Returns `{ ok: true, agent }` when the caller named a real agent, `{ ok: true, agent: null }` when
+ * the caller named NOTHING (so the caller should fall back to its own connection-scoped resolution),
+ * and a refusal otherwise. The three-way return is the point: "named nothing" and "named something
+ * unusable" are different, and collapsing them is the whole defect class.
+ */
+export declare function resolveNamedAgent(rawAgent: unknown, known: ReadonlyArray<KnownAgent>): {
+    ok: true;
+    agent: string | null;
+} | NamedAgentRefusal;
+//# sourceMappingURL=resolve-named-agent.d.ts.map

package/dist/resolve-named-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-named-agent.d.ts","sourceRoot":"","sources":["../src/resolve-named-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;IAChG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAOD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,iBAAiB,CAwCxD"}

package/dist/resolve-named-agent.js

@@ -0,0 +1,77 @@
+/**
+ * One guard for "the caller named an agent" — shared, so the third copy never gets written.
+ *
+ * DOD-INBOX-AGENT-1 closed a defect where `cello_check_notifications` accepted an `agent` parameter
+ * and silently dropped it, answering as whatever agent the CONNECTION held. Reviewing that fix found
+ * the same shape in three more places, including the one next door in `contact-handlers.ts`, where
+ * it is worse because that path WRITES: `cello_contact_add({ agent: "", pubkey })` fell through to
+ * the connection's selection and filed the contact under the wrong desk, and `{ agent: "carol" }`
+ * with no carol wrote a row keyed to an agent that does not exist. Both `ok: true`.
+ *
+ * The three ways a named agent goes wrong, and why each must REFUSE rather than fall back:
+ *
+ *  1. **A non-string** (`{ agent: 123 }`). MCP callers are shielded by zod; direct-IPC callers are
+ *     not. §5a is explicit that unreachability is a property of today's call graph, not of the code.
+ *  2. **An empty string.** `""` is falsy but not nullish, so a bare truthiness test reads it as "no
+ *     name given" and runs as the connection's selection — the exact misroute, reintroduced through
+ *     the guard meant to prevent it. `{ agent: someUnsetVar }` produces it, and so does an
+ *     unsubstituted `<exact name>` placeholder in a prompt.
+ *  3. **A name that is not here.** Falling back answers a question about carol with alice's data.
+ *
+ * And one that is NOT "not found": an agent whose identity FAILED TO LOAD exists. Saying "does not
+ * exist" sends the operator to `cello_agents`, which filters `load_failed` out — so they see nothing,
+ * confirm the wrong diagnosis, and never reach `cello_status`, which would have shown the real error.
+ * That is an exit-point label standing in for the cause.
+ */
+/** Agent-name length cap, matching the moniker convention — the name is echoed back into guidance. */
+const MAX_NAME_ECHO = 64;
+/** Truncate a caller-supplied name before echoing it into an operator-facing string. */
+function echoName(name) {
+    return name.length <= MAX_NAME_ECHO ? name : `${name.slice(0, MAX_NAME_ECHO)}…`;
+}
+/**
+ * Validate an explicitly-named agent.
+ *
+ * Returns `{ ok: true, agent }` when the caller named a real agent, `{ ok: true, agent: null }` when
+ * the caller named NOTHING (so the caller should fall back to its own connection-scoped resolution),
+ * and a refusal otherwise. The three-way return is the point: "named nothing" and "named something
+ * unusable" are different, and collapsing them is the whole defect class.
+ */
+export function resolveNamedAgent(rawAgent, known) {
+    if (rawAgent === undefined || rawAgent === null)
+        return { ok: true, agent: null };
+    if (typeof rawAgent !== "string") {
+        return {
+            ok: false,
+            reason: "invalid_agent_value",
+            guidance: `The 'agent' parameter must be an agent name (a string), but got ${Array.isArray(rawAgent) ? "an array" : typeof rawAgent}. Nothing was read or written. Pass the name, or omit 'agent' to use this connection's current agent.`,
+        };
+    }
+    if (rawAgent.trim() === "") {
+        return {
+            ok: false,
+            reason: "missing_agent_value",
+            guidance: "The 'agent' parameter was empty (an unset variable, or an unsubstituted placeholder?). Nothing was read or written — an empty name is NOT treated as 'no agent given', because that would silently run as whichever agent this connection happens to hold. Name an agent, or omit 'agent' entirely.",
+        };
+    }
+    const match = known.find((a) => a.name === rawAgent);
+    if (!match) {
+        return {
+            ok: false,
+            reason: "agent_not_found",
+            guidance: `Agent '${echoName(rawAgent)}' does not exist on this machine, so nothing was read or written. Check the name with cello_agents, or omit 'agent' to use this connection's current agent.`,
+        };
+    }
+    // It EXISTS but its identity could not be loaded. Reported as itself: cello_agents hides
+    // load_failed agents, so "does not exist" would send the operator to the one surface that
+    // confirms the wrong answer. cello_status shows the state and the underlying error.
+    if (match.state === "load_failed") {
+        return {
+            ok: false,
+            reason: "agent_load_failed",
+            guidance: `Agent '${echoName(rawAgent)}' exists but its identity failed to load, so nothing was read or written${match.error ? ` (${match.error})` : ""}. Run cello_status to see the error — note cello_agents omits agents in this state, so it will look like the agent is missing.`,
+        };
+    }
+    return { ok: true, agent: rawAgent };
+}
+//# sourceMappingURL=resolve-named-agent.js.map

package/dist/resolve-named-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-named-agent.js","sourceRoot":"","sources":["../src/resolve-named-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,sGAAsG;AACtG,MAAM,aAAa,GAAG,EAAE,CAAC;AAezB,wFAAwF;AACxF,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC;AAClF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAiB,EACjB,KAAgC;IAEhC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAElF,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,qBAAqB;YAC7B,QAAQ,EAAE,mEAAmE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,QAAQ,uGAAuG;SAC3O,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,qBAAqB;YAC7B,QAAQ,EAAE,qSAAqS;SAChT,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACrD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,iBAAiB;YACzB,QAAQ,EAAE,UAAU,QAAQ,CAAC,QAAQ,CAAC,6JAA6J;SACpM,CAAC;IACJ,CAAC;IAED,yFAAyF;IACzF,0FAA0F;IAC1F,oFAAoF;IACpF,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;QAClC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,mBAAmB;YAC3B,QAAQ,EAAE,UAAU,QAAQ,CAAC,QAAQ,CAAC,2EAA2E,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,gIAAgI;SACxR,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACvC,CAAC"}