@uuaid/pillar 2.0.3 → 2.2.0

package/src/pillar.mjs

@@ -22,7 +22,17 @@ import { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex }
 import { seal, open, decrypt, envelopeSha, mkEnvelopeId, ENVELOPE_VERSION } from "./net/envelope.mjs";
 import { Mailbox } from "./mailbox/mailbox.mjs";
 import { CarrierClient } from "./net/carrier-client.mjs";
+import { REFUSAL_FIXES } from "./net/refusals.mjs";
 import { Observability } from "./observability.mjs";
+import { evaluateTrust } from "./identity/trust.mjs";
+import { keyDerivesUuaid } from "./identity/keychain.mjs";
+import {
+  extractGroupTag, buildGroupTag, absorbGroupTag, newGroupId, newGroupMsgId, normalizeMembers, isGroupId,
+} from "./groups.mjs";
+import { applyReceipt, answersOurSend, deliveryAck, planReadReceipts, readReceipt } from "./receipts.mjs";
+import { GroupReceiver, RosterStore, isGroupIdV2, adminOf, buildGroupTag as buildGroupTagV2, manifestHash as manifestHashOf, loadGroupForCommand } from "./groups-v2.mjs";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
 import {
   BLOB_KIND, MAX_INLINE_BODY_BYTES, BlobError, BlobSizeError, envelopeBodyBytes, preflightBodyBytes,
   prepareBlobSend, fetchAndDecryptBlob, prepareBrokerBlobSend, fetchBrokerBlob,
@@ -49,6 +59,9 @@ export class Pillar {
     blobBroker = null, // challenge broker for blob reserve/finalize/redeem
     blobClient = null, // PillarBlobHttpClient for the production S3 broker path
     senderKeyCheck = null, // registry gate for senders not derived from their key: (uuaid, pubkeyHex) => status
+    reader = null, // reader key recorded on every row this process stores (src/readers.mjs)
+    receipts = null, // { delivered, read }: send signed acks / read receipts (receipts.mjs); null = neither
+    groupsV2Home = null, // where groups-v2/ lives (pillar-group/2 store); default: the mailbox's directory
   }) {
     if (!keychain?._identity) throw new Error("Pillar: keychain must be loaded before construction");
     this.keychain = keychain;
@@ -72,7 +85,17 @@ export class Pillar {
     this.blobTier = tierGrant?.tier ?? "community";
     this.blobMaxBodyBytes = Number.isInteger(tierGrant?.maxBodyBytes) ? tierGrant.maxBodyBytes : null;
     this.senderKeyCheck = senderKeyCheck;
+    this.reader = reader;
+    this.receipts = { delivered: !!receipts?.delivered, read: !!receipts?.read };
     this._envelopeHandlers = new Set();
+    // pillar-group/2. Starting the receiver re-syncs every stored group's
+    // mailbox row from the verified store. Its `sends` are NOT executed: no
+    // send path reads the v2 store until that policy is decided.
+    this.groupsV2 = new GroupReceiver({
+      self: { uuaid: keychain._identity.uuaid, key: keychain._identity.publicKeyHex },
+      store: new RosterStore(groupsV2Home ?? dirname(mailboxPath)),
+      mailbox: this.mailbox,
+    });
     this._openStreams = new Map(); // peerIdString -> pushable
   }
 
@@ -219,11 +242,7 @@ export class Pillar {
       const providerPubKey = provider.id.publicKey;
       if (!providerPubKey) continue; // shouldn't happen for Ed25519 PeerIds but be safe
       const publicKeyHex = Buffer.from(providerPubKey.raw).toString("hex");
-      // Recompute the UUAID that this key would mint.
-      const { Keychain } = await import("./identity/keychain.mjs");
-      const localId = Keychain._localIdFromKey(Buffer.from(publicKeyHex, "hex"));
-      const expectedUuaid = `uuaid:foundation:agent:${localId}`;
-      if (expectedUuaid !== uuaid) continue; // provider is squatting on someone else's key
+      if (!keyDerivesUuaid(publicKeyHex, uuaid, "agent")) continue; // provider is squatting on someone else's key
       // Remember addrs so future dials succeed even if the provider drops off DHT.
       if (provider.multiaddrs?.length) {
         try { await this.node.peerStore.patch(provider.id, { multiaddrs: provider.multiaddrs }); } catch (_e) {}
@@ -285,7 +304,14 @@ export class Pillar {
       this.metrics.inc("send.error.direct-cap");
       throw new BlobSizeError(`envelope ${hardCap.bytes}B exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: hardCap.bytes, max: MAX_INLINE_BODY_BYTES });
     }
-    const persisted = this.mailbox.appendOutbound(envelope);
+    // Receipt matching needs the thread and group of this row, and the sealed
+    // envelope cannot tell us later: we cannot decrypt our own outbox.
+    const groupTag = extractGroupTag(payload);
+    const persisted = this.mailbox.appendOutbound(envelope, {
+      thread: typeof payload?.thread === "string" && payload.thread ? payload.thread : null,
+      groupId: groupTag && !groupTag.derivedId ? groupTag.id : null,
+      groupMsgId: groupTag?.msgId ?? null,
+    });
 
     // 1. Address book path: direct libp2p dial (lowest latency, no third party).
     if (this.node && book?.peerId && book?.multiaddr) {
@@ -335,23 +361,51 @@ export class Pillar {
    * There is deliberately NO group key: each member gets their own sealed
    * envelope (same guarantees as 1:1 send), so membership changes never
    * require rekeying and the carrier still can't read anything.  The group
-   * context travels INSIDE the sealed payload as `_group: { name, members }`
-   * so every recipient can reply to the whole group without extra lookups.
+   * travels INSIDE the sealed payload as a `pillar-group` v1 tag (groups.mjs,
+   * INTERACTION-CONVENTION.md): a stable `id`, the roster, one `msgId` shared
+   * by every copy, the `op`, and binding-checkable sealing `keys`, so every
+   * member files the message under one thread and can answer the whole group.
+   *
+   * `groupId` names a group from this home's roster (mailbox `groups`). Without
+   * one, the group is found by name + identical roster, or created, so repeat
+   * sends to the same named roster stay one thread.
    *
    * Failures are isolated: one undeliverable member never blocks the rest.
-   * Returns { group, results: [{ member, ok, via?, envelopeId?, error?, code?, fix? }] }.
+   * Refused (code group-v2-use-v2-send) for a pillar-group/2 group.
+   * Returns { group, groupId, msgId, results: [{ member, ok, via?, envelopeId?, error?, code?, fix? }] }.
    */
-  async sendGroup({ group, members, kind = "message", payload = {}, resolveTimeoutMs = 5000 }) {
-    if (!Array.isArray(members) || members.length === 0) {
-      throw new Error(`sendGroup: group "${group}" has no members`);
+  async sendGroup({ group, groupId = null, members, kind = "message", payload = {}, op = "message", resolveTimeoutMs = 5000 }) {
+    let g = groupId ? this.mailbox.getGroup(groupId) : null;
+    if (groupId && !g) throw new Error(`sendGroup: no group ${groupId} in this home`);
+    if (!g) {
+      const roster = normalizeMembers([...(Array.isArray(members) ? members : []), this.uuaid]);
+      if (roster.length < 2) throw new Error(`sendGroup: group "${group}" has no members`);
+      const sorted = [...roster].sort().join(",");
+      g = this.mailbox.listGroups().find((x) => x.name === group && [...x.members].sort().join(",") === sorted && !x.left)
+        ?? this.mailbox.putGroup({ id: newGroupId(), name: String(group ?? "Group"), members: roster, keys: {}, createdBy: this.uuaid });
+    }
+    // A pillar-group/2 group (held, or its row marked by the v2 sync) takes no v1 send,
+    // whichever way it was reached (id, name + roster, a groups file): sendGroupV2 sends it.
+    if (isGroupIdV2(g.id) && (this.groupsV2.store.has(g.id) || this.mailbox.isGroupV2Marked(g.id))) throw Object.assign(new Error(`sendGroup: ${g.id} is a pillar-group/2 group and takes no v1 send`), { code: "group-v2-use-v2-send", fix: REFUSAL_FIXES["group-v2-use-v2-send"] }); // @rule P-v1-send-refuses-v2
+    if (g.pending) throw new Error(`sendGroup: group ${g.id} is a pending invitation — accept it first (pillar group accept ${g.id})`);
+    if (g.left && op !== "leave") throw new Error(`sendGroup: you left group ${g.id}`);
+    // Sealing hints for the members: every key we know that really owns its uuaid.
+    const keys = { [this.uuaid]: this.publicKeyHex };
+    for (const m of g.members) {
+      const k = this.addressBook?.get(m)?.publicKey ?? g.keys?.[m];
+      if (k) keys[m] = k;
     }
-    const others = members.filter(m => m !== this.uuaid);
+    const msgId = newGroupMsgId();
     // _group goes last so a payload can never override the group it travels in.
-    const wrapped = { ...payload, _group: { name: group, members } };
+    const wrapped = { ...payload, _group: buildGroupTag(g, { msgId, keys, op }) };
+    const others = g.members.filter(m => m !== this.uuaid);
     const results = [];
     for (const member of others) {
       try {
-        const r = await this.send({ recipient: member, kind, payload: wrapped, resolveTimeoutMs });
+        const r = await this.send({
+          recipient: member, recipientPublicKey: this.addressBook?.get(member)?.publicKey ?? g.keys?.[member],
+          kind, payload: wrapped, resolveTimeoutMs,
+        });
         results.push({ member, ok: true, via: r.via, envelopeId: r.envelope.id });
       } catch (e) {
         results.push({ member, ok: false, error: e.message, ...(typeof e.code === "string" ? { code: e.code } : {}), ...(typeof e.fix === "string" ? { fix: e.fix } : {}) });
@@ -360,7 +414,44 @@ export class Pillar {
     this.metrics.inc("sendGroup");
     const failed = results.filter((r) => !r.ok).length;
     if (failed) this.metrics.inc("sendGroup.failed", failed);
-    return { group, results };
+    return { group: g.name, groupId: g.id, msgId, results };
+  }
+
+  /**
+   * pillar-group/2 send. Recipients come from the mailbox `groups` row (the
+   * verified head minus anyone leaving, which is what an egress filter
+   * reads), never from the v2 store; the store gives only the tag's `mv`.
+   *   message, leave.request   every member in the row except self
+   *   accept.request, rename.request   the admin only
+   * Refused for a group this home does not hold, a frozen or cleared row, and
+   * any op but accept.request from a member who is only invited.
+   * Returns { group, groupId, msgId, results } like sendGroup.
+   */
+  async sendGroupV2({ groupId, op = "message", payload = {}, kind = "message", resolveTimeoutMs = 5000 }) {
+    if (!["message", "leave.request", "accept.request", "rename.request"].includes(op)) throw new Error(`sendGroupV2: op ${op} is not sent from here`);
+    const rec = loadGroupForCommand(this.groupsV2.store, groupId); // throws for a group it does not hold, or one that no longer verifies
+    const row = this.mailbox.getGroup(groupId);
+    const refuse = (why) => { const e = new Error(`sendGroupV2: ${groupId}: ${why}`); e.code = "group-v2-refused"; throw e; };
+    if (!row || row.left) refuse("its mailbox row is cleared (frozen, removed, or never written)"); // @rule P-send-row-live
+    const head = rec.chain[rec.chain.length - 1];
+    const me = head.members.find((r) => r.uuaid === this.uuaid);
+    const admin = adminOf(head).uuaid;
+    if (me?.status !== "active" && !(me?.status === "invited" && op === "accept.request")) refuse(`this member is ${me?.status ?? "not in the roster"}`); // @rule P-send-active-only
+    let to = row.members.filter((m) => m !== this.uuaid);
+    if (op === "accept.request" || op === "rename.request") to = to.filter((m) => m === admin);
+    const tag = buildGroupTagV2(rec, { op });
+    const wrapped = { text: "", ...payload, _group: tag };
+    const results = [];
+    for (const member of to) {
+      try {
+        const r = await this.send({ recipient: member, recipientPublicKey: this.addressBook?.get(member)?.publicKey ?? row.keys?.[member], kind, payload: wrapped, resolveTimeoutMs });
+        results.push({ member, ok: true, via: r.via, envelopeId: r.envelope.id });
+      } catch (e) {
+        results.push({ member, ok: false, error: e.message, ...(typeof e.code === "string" ? { code: e.code } : {}), ...(typeof e.fix === "string" ? { fix: e.fix } : {}) });
+      }
+    }
+    this.metrics.inc("sendGroupV2");
+    return { group: head.name, groupId, msgId: tag.msgId, results };
   }
 
   /**
@@ -577,6 +668,273 @@ export class Pillar {
     }
   }
 
+  /**
+   * Judge a pillar-group/2 message (src/groups-v2.mjs) and file its inbox row.
+   * Returns true when the row is delivered to handlers now.
+   *
+   *   accepted / invitation / recovered   filed under the group, delivered
+   *   warning (v1 line in a v2 group)     delivered, never filed under the group
+   *   held                                quarantined `group-v2:held` until released
+   *   anything else                       quarantined `group-v2:<reason>` (kept as evidence)
+   *
+   * Held messages released by this step are filed and delivered, or
+   * re-quarantined with their reason. The receiver's `sends` are counted and
+   * dropped: nothing leaves this process from here.
+   */
+  async _receiveGroupV2(envelope, payload) {
+    const env = { from: envelope.sender, transportKey: envelope.transportSignature?.publicKey, payload, ref: envelope.id };
+    if (envelope.delegation) env.delegation = { rootKey: envelope.delegation.principalPublicKey };
+    const r = this.groupsV2.receive(env, Date.now());
+    this.metrics.inc(`received.group-v2.${r.verdict}`);
+    const groupId = payload._group.id;
+    if (r.sends.length) {
+      const keyed = r.sends.map((s) => ({ ...s, key: this._groupV2KeyFor(groupId, s.to, envelope) }));
+      let ids = [];
+      ids = this.mailbox.enqueueGroupV2Sends(groupId, keyed, { newId: () => `gq-${randomBytes(12).toString("hex")}` }); // @rule Q-enqueue
+      this.metrics.inc("group-v2.sends.queued", ids.length);
+      if (ids.length < r.sends.length) this.metrics.inc("group-v2.sends.queue-full", r.sends.length - ids.length);
+    }
+    for (const x of r.released) await this._settleHeldGroupV2(x.ref, x.verdict, x.reason, groupId);
+    for (const x of r.dropped) if (x.ref) this.mailbox.markQuarantined(x.ref, `group-v2:${x.reason}`);
+    if (["accepted", "invitation", "recovered"].includes(r.verdict)) {
+      this.mailbox.setInboundGroup(envelope.id, groupId);
+      return true;
+    }
+    if (r.verdict === "warning") return true;
+    // Verdict "v1" (a v1 tag for a group the store does not hold) reaches here only
+    // for a marked row whose store file is gone: no verified chain, nothing to file under.
+    this.mailbox.markQuarantined(envelope.id, `group-v2:${r.verdict === "v1" ? "no-chain" : (r.reason ?? r.verdict)}`);
+    return false;
+  }
+
+  /**
+   * The key to seal a queued send to `uuaid`: its row in the verified chain
+   * (any version, so a removed member and an invitee resolve too); else, for
+   * the sender of the envelope that caused it, its verified key (the
+   * delegation's root key for a delegated envelope); else the address book.
+   */
+  _groupV2KeyFor(groupId, uuaid, envelope) {
+    if (this.groupsV2.store.has(groupId)) {
+      try {
+        const rec = this.groupsV2.store.load(groupId);
+        for (let i = rec.chain.length - 1; i >= 0; i--) {
+          const row = rec.chain[i].members.find((r) => r.uuaid === uuaid);
+          if (row) return row.key;
+        }
+      } catch { /* an unreadable record: fall through */ }
+    }
+    if (envelope && uuaid === envelope.sender) return envelope.delegation?.principalPublicKey ?? envelope.transportSignature?.publicKey ?? null;
+    return this.addressBook?.get(uuaid)?.publicKey ?? null;
+  }
+
+  /**
+   * Send what the v2 receiver queued, for one group or all. This is the only
+   * path that sends a queued row; nothing calls it on receive. Each row is
+   * sealed to its recipient alone. Final states: `sent` (with the envelope
+   * id) or `dropped` (with a reason). A failed attempt stays `queued`.
+   * A frozen group sends only its equivocation proof.
+   * Returns [{ id, groupId, to, op, state, envelopeId?, reason? }].
+   */
+  async syncGroupV2({ groupId = null, resolveTimeoutMs = 5000 } = {}) {
+    const ZERO = "0".repeat(64);
+    const out = [];
+    for (const q of this.mailbox.queuedGroupV2Sends(groupId)) {
+      const done = (state, extra = {}) => { this.mailbox.markGroupV2Send(q.id, state, extra); out.push({ id: q.id, groupId: q.group_id, to: q.recipient, op: q.op, state, ...extra }); };
+      let rec = null;
+      if (this.groupsV2.store.has(q.group_id)) {
+        try { rec = this.groupsV2.store.load(q.group_id); } catch (e) { done("dropped", { reason: `store: ${e.message}` }); continue; }
+      }
+      if (rec?.frozen && q.op !== "equivocation") { done("dropped", { reason: "frozen" }); continue; } // @rule Q-sync-frozen-only-proof
+      const msgId = `gm-${randomBytes(16).toString("hex")}`;
+      const tag = rec
+        ? buildGroupTagV2(rec, { op: q.op, msgId })
+        : { v: 2, id: q.group_id, name: "", members: [], msgId, op: q.op, mv: { version: 0, hash: ZERO } };
+      let text;
+      if (q.op === "manifest.request") {
+        tag.want = { from: q.want_from, to: q.want_to };
+        text = `asks for group manifests ${q.want_from}..${q.want_to ?? "newest"}`;
+      } else if (q.op === "manifest") {
+        const m = rec?.chain.find((x) => manifestHashOf(x) === q.manifest_hash);
+        if (!m) { done("dropped", { reason: "manifest-not-held" }); continue; }
+        tag.manifest = m;
+        text = `group manifest v${m.version} (${m.transition.action})`;
+      } else if (q.op === "equivocation") {
+        const m = rec?.frozen?.manifests.find((x) => manifestHashOf(x) === q.manifest_hash);
+        if (!m) { done("dropped", { reason: "proof-not-held" }); continue; }
+        tag.manifest = m;
+        tag.conflictsWith = q.conflicts_with;
+        text = `the group admin signed two versions ${m.version}: this group is frozen`;
+      } else { done("dropped", { reason: `op ${q.op} is not queued` }); continue; }
+      const key = q.recipient_key ?? this.addressBook?.get(q.recipient)?.publicKey;
+      if (!key) { done("dropped", { reason: "no key for the recipient" }); continue; }
+      try {
+        const r = await this.send({ recipient: q.recipient, recipientPublicKey: key, kind: "message", payload: { text, _group: tag }, resolveTimeoutMs });
+        done("sent", { envelopeId: r.envelope.id }); // @rule Q-sync-marks-sent
+      } catch (e) {
+        this.mailbox.markGroupV2Send(q.id, "queued", { reason: e.message });
+        out.push({ id: q.id, groupId: q.group_id, to: q.recipient, op: q.op, state: "queued", reason: e.message });
+      }
+    }
+    this.metrics.inc("group-v2.sync", out.length);
+    return out;
+  }
+
+  async _settleHeldGroupV2(envelopeId, verdict, reason, groupId) {
+    if (!envelopeId) return;
+    if (verdict !== "accepted") { this.mailbox.markQuarantined(envelopeId, `group-v2:${reason ?? verdict}`); return; }
+    this.mailbox.clearQuarantine(envelopeId);
+    this.mailbox.setInboundGroup(envelopeId, groupId);
+    const row = this.mailbox.getInbound(envelopeId);
+    if (!row) return;
+    const envelope = JSON.parse(row.envelope_json);
+    let payload;
+    try { payload = decrypt(this.keychain, envelope); } catch { return; }
+    const view = { ...envelope, payload };
+    for (const h of this._envelopeHandlers) {
+      try { await h(view, { duplicate: false, envelopeId, released: true }); }
+      catch (e) { this.metrics.inc("received.handler-error"); console.error("pillar: envelope handler threw", e); }
+    }
+  }
+
+  /**
+   * Would the trust gate deliver this (already verified, decrypted) envelope?
+   * Shared by the receive path and the no-side-effect peek. { deliver, reason? }
+   */
+  _trustVerdict(envelope, payload) {
+    if (!this.trust) return { deliver: true };
+    if (answersOurSend(this.mailbox, envelope, payload)) return { deliver: true };
+    return evaluateTrust(this.trust, envelope.sender, new Set(this.addressBook?.keys() ?? []));
+  }
+
+  /** A peer we may send delivery signals to: never a stranger (no liveness oracle). */
+  _isReceiptPeer(uuaid, tag) {
+    if (this.addressBook?.get(uuaid)?.publicKey) return true;
+    if (this.trust?.allow?.includes(uuaid)) return true;
+    if (tag) {
+      const g = this.mailbox.getGroup(tag.id);
+      if (g && !g.pending && !g.left && g.members.includes(uuaid)) return true;
+    }
+    return false;
+  }
+
+  _sealKeyFor(uuaid, envelope = null, tag = null) {
+    return this.addressBook?.get(uuaid)?.publicKey
+      ?? (tag ? this.mailbox.getGroup(tag.id)?.keys?.[uuaid] : undefined)
+      // The verified transport key: open() already bound it to the sender
+      // (for a delegated envelope it is the device key, and seal() refuses it).
+      ?? envelope?.transportSignature?.publicKey;
+  }
+
+  async _autoAck(envelope, payload, tag) {
+    if (envelope.sender === this.uuaid || !this._isReceiptPeer(envelope.sender, tag)) return;
+    try {
+      const ack = deliveryAck(envelope, payload);
+      await this.send({ recipient: envelope.sender, recipientPublicKey: this._sealKeyFor(envelope.sender, envelope, tag), ...ack });
+      this.metrics.inc("receipts.ack.sent");
+    } catch (e) {
+      this.metrics.inc("receipts.ack.failed");
+      // eslint-disable-next-line no-console
+      console.warn(`pillar: could not ack ${envelope.id} to ${envelope.sender}: ${e.message}`);
+    }
+  }
+
+  /**
+   * Send read receipts for inbound messages the caller has just marked read.
+   * One receipt per (sender, conversation), only to receipt peers, only when
+   * read receipts are on. `views`: [{ id, sender, kind, payload, groupId? }].
+   * Returns { sent, skipped, dropped }.
+   */
+  async sendReadReceipts(views) {
+    if (!this.receipts.read) return { sent: 0, skipped: 0, dropped: 0 };
+    const { receipts, dropped } = planReadReceipts(views, { self: this.uuaid });
+    let sent = 0, skipped = 0;
+    for (const r of receipts) {
+      const source = views.find((v) => v.id === r.upTo);
+      const tag = source?.groupId ? { id: source.groupId } : null;
+      if (!this._isReceiptPeer(r.to, tag)) { skipped++; continue; }
+      try {
+        await this.send({ recipient: r.to, recipientPublicKey: this._sealKeyFor(r.to, source, tag), ...readReceipt(r) });
+        sent++;
+      } catch (e) {
+        skipped++;
+        // eslint-disable-next-line no-console
+        console.warn(`pillar: could not send a read receipt to ${r.to}: ${e.message}`);
+      }
+    }
+    this.metrics.inc("receipts.read.sent", sent);
+    return { sent, skipped, dropped };
+  }
+
+  /**
+   * Look at the carriers WITHOUT storing anything or moving a cursor: long-poll
+   * every carrier from the stored cursor and resolve with the verified,
+   * decrypted envelopes that would reach handlers (trust gate applied;
+   * quarantine-bound, foreign, undecryptable and already-stored envelopes are
+   * passed over) as soon as at least one matches, or when the deadline passes.
+   *
+   * This is the wake signal: a process can sleep on it at zero CPU and hand
+   * the mail to whoever reads the home next, which still sees it as new.
+   *
+   *   match(view)  optional filter; only matching views count and are returned
+   *   stopWhen()   optional; checked after every round (e.g. "already acked")
+   *   deadlineMs   absolute epoch ms; null = wait for ever
+   *
+   * Throws the last carrier error when every carrier refuses outright.
+   */
+  async peekCarrierInbox({ match = null, stopWhen = null, deadlineMs = null, waitS = 25 } = {}) {
+    if (!this.carrierClient) throw new Error("peek: no carriers configured");
+    const cursors = this.mailbox.getCarrierCursors?.() ?? {};
+    const found = new Map();
+    const ctl = new AbortController();
+    let stop = false;
+    const dead = new Map(); // carrier -> error
+    const FATAL = new Set(["uuaid-pubkey-mismatch", "clock-skew", "bad-pubkey", "bad-signature", "missing-auth-headers"]);
+    const loop = async (base) => {
+      // drainCarrierInbox keys cursors by the configured URL, the polling loop
+      // by the normalised one; start past whichever is further along.
+      let since = Math.max(cursors[base] ?? 0, cursors[String(base).replace(/\/+$/, "")] ?? 0);
+      let asked = false; // every carrier is asked once, even at timeout 0
+      while (!stop) {
+        if (stopWhen?.()) { stop = true; break; }
+        const left = deadlineMs == null ? Infinity : deadlineMs - Date.now();
+        if (left <= 0 && asked) break;
+        asked = true;
+        const w = Math.max(0, Math.min(waitS, Math.floor(left / 1000)));
+        let r;
+        try {
+          r = await this.carrierClient.fetchInbox(base, { since, waitS: w, timeoutMs: (w + 15) * 1000, signal: ctl.signal });
+        } catch (e) {
+          if (stop || ctl.signal.aborted) break;
+          if (FATAL.has(e.code)) { dead.set(base, e); break; }
+          dead.set(base, e);
+          await new Promise((res) => setTimeout(res, Math.min(2000, Math.max(0, left))));
+          continue;
+        }
+        dead.delete(base);
+        for (const { seq, envelope } of r.envelopes) {
+          since = Math.max(since, seq);
+          if (found.has(envelope.id) || this.mailbox.getInbound(envelope.id)) continue;
+          const v = open(envelope, { cryptoInventory: this.cryptoInventory });
+          if (!v.ok || envelope.recipient !== this.uuaid) continue;
+          let payload;
+          try { payload = decrypt(this.keychain, envelope); } catch { continue; }
+          if (!this._trustVerdict(envelope, payload).deliver) continue;
+          const view = { ...envelope, payload };
+          if (match && !match(view)) continue;
+          found.set(envelope.id, view);
+        }
+        if (found.size) { stop = true; ctl.abort(); }
+        else if (w === 0 && !r.envelopes.length) {
+          // Nothing and no time left to long-poll: the deadline governs.
+          if (deadlineMs != null && Date.now() >= deadlineMs) break;
+        }
+      }
+    };
+    await Promise.all(this.carriers.map((base) => loop(base)));
+    if (!found.size && dead.size === this.carriers.length) throw [...dead.values()].at(-1);
+    return [...found.values()];
+  }
+
   async _receive(rawLine, connection) {
     let envelope;
     try { envelope = JSON.parse(rawLine); }
@@ -607,7 +965,7 @@ export class Pillar {
       console.warn("pillar: envelope decrypt failed (dropping)", envelope.id, e.message);
       return;
     }
-    const persisted = this.mailbox.appendInbound(envelope);
+    const persisted = this.mailbox.appendInbound(envelope, { pulledBy: this.reader });
     if (persisted.duplicate) {
       this.metrics.inc("received.duplicate");
       return; // replay: do not re-fire handlers
@@ -615,25 +973,48 @@ export class Pillar {
     this.metrics.inc(`received.kind.${envelope.kind}`);
     // Trust gate (recipient consent): quarantine-not-drop. The envelope is
     // already persisted (chain-hashed evidence); a gated sender just never
-    // reaches handlers. An ack/reply passes the gate ONLY if its inReplyTo
-    // names an envelope in OUR outbox — a genuine receipt for our own send.
-    // (kind alone is spoofable; the outbox check is not.)
-    if (this.trust) {
-      const isReceipt = (envelope.kind === "ack" || envelope.kind === "reply") &&
-        typeof payload?.inReplyTo === "string" && this.mailbox.hasOutbound(payload.inReplyTo);
-      if (!isReceipt) {
-        const { evaluateTrust } = await import("./identity/trust.mjs");
-        const known = new Set(this.addressBook?.keys() ?? []);
-        const verdict = evaluateTrust(this.trust, envelope.sender, known);
-        if (!verdict.deliver) {
-          this.mailbox.markQuarantined(envelope.id, verdict.reason);
-          this.metrics.inc(`received.quarantined.${verdict.reason}`);
-          // eslint-disable-next-line no-console
-          console.warn(`pillar: quarantined ${envelope.id} from ${envelope.sender} (${verdict.reason})`);
-          return;
-        }
-      }
+    // reaches handlers. An ack/reply (or a read receipt) passes the gate ONLY
+    // when it answers an envelope in OUR outbox that was sent TO ITS SENDER —
+    // a genuine receipt for our own send. (kind alone is spoofable, and so is
+    // an envelope id: ids are visible to every carrier. Sent-to-this-sender
+    // is not.)
+    const verdict2 = this._trustVerdict(envelope, payload);
+    if (!verdict2.deliver) {
+      this.mailbox.markQuarantined(envelope.id, verdict2.reason);
+      this.metrics.inc(`received.quarantined.${verdict2.reason}`);
+      // eslint-disable-next-line no-console
+      console.warn(`pillar: quarantined ${envelope.id} from ${envelope.sender} (${verdict2.reason})`);
+      return;
+    }
+    // The recipient's own signed word about something we sent.
+    if (envelope.kind === "ack") {
+      const r = applyReceipt(this.mailbox, envelope, payload, { applyRead: this.receipts.read });
+      if (r.kind) this.metrics.inc(`received.receipt.${r.kind}${r.marked ? "" : ".unmatched"}`);
+    }
+    // Group threads: fold the roster, and file the row under its group only
+    // when its sender is a member (before this tag, for a `leave`; after it,
+    // for the tag that created the group). A blocked sender reaches here
+    // through the receipt pass-through above, and never touches a roster.
+    // pillar-group/2 first: a v2 tag, or a v1 tag naming a group the v2 store
+    // holds or whose row the v2 sync marked, never reaches the v1 roster
+    // (spec §5.0, §7). An unmarked row is v1's, whatever its id's shape.
+    const g = payload?._group;
+    let route = null;
+    if (g && typeof g === "object" && !Array.isArray(g) && !this.trust?.block?.includes(envelope.sender)) {
+      if (g.v === 2) route = "v2"; // @rule P-route-v2-tag
+      if (route === null && isGroupIdV2(g.id) && this.groupsV2.store.has(g.id)) route = "v2"; // @rule P-route-held-id
+      if (route === null && isGroupIdV2(g.id) && this.mailbox.isGroupV2Marked(g.id)) route = "v2"; // @rule P-route-marked-id
+    }
+    if (route === "v2" && !(await this._receiveGroupV2(envelope, payload))) return;
+    const tag = route === "v2" ? null : extractGroupTag(payload);
+    if (tag && !this.trust?.block?.includes(envelope.sender)) {
+      const fromContact = !!this.addressBook?.get(envelope.sender) || !!this.trust?.allow?.includes(envelope.sender);
+      const before = this.mailbox.getGroup(tag.id);
+      const after = absorbGroupTag(this.mailbox, tag, { sender: envelope.sender, self: this.uuaid, text: payload?.text ?? "", fromContact });
+      if ((before ?? after)?.members.includes(envelope.sender)) this.mailbox.setInboundGroup(envelope.id, tag.id);
+      else this.metrics.inc("received.group.non-member");
     }
+    if (this.receipts.delivered && envelope.kind !== "ack") await this._autoAck(envelope, payload, tag);
     const view = { ...envelope, payload };
     for (const h of this._envelopeHandlers) {
       try { await h(view, persisted); }

package/src/readers.mjs

@@ -0,0 +1,120 @@
+/**
+ * Readers — more than one consumer of one pillar home.
+ *
+ * A home's mailbox.db holds ONE carrier cursor per carrier: fetching is
+ * idempotent on envelope id, so it does not matter which process pulls. What
+ * used to matter is who SEES a message: `pillar inbox` printed only what that
+ * run itself pulled, so when two readers shared a home, whichever ran first
+ * was the only one that saw the mail as new (and with --mark-read, the other
+ * never saw it at all).
+ *
+ * Two fixes live here:
+ *
+ *   1. Named readers (`--reader NAME` or PILLAR_READER). Each has its own
+ *      cursor over the LOCAL inbox table, so every reader sees every row after
+ *      its cursor no matter which process stored it.
+ *
+ *   2. Warnings for everyone else. A reader without a name gets an implicit
+ *      key per (host, uid, working directory), so its output stays exactly
+ *      what it always was, but it is told on stderr when another reader
+ *      pulled its mail, and when a live `pillar recv` is consuming the home.
+ */
+import { createHash } from "node:crypto";
+import { hostname, userInfo } from "node:os";
+
+export const READER_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+export const IMPLICIT_PREFIX = "ctx:";
+export const LEASE_TTL_MS = 90_000;
+export const LEASE_HEARTBEAT_MS = 30_000;
+
+function uid() {
+  try { return String(userInfo().uid); } catch { return "?"; }
+}
+
+/** The calling process, as a reader row records it. */
+export function processContext({ command } = {}) {
+  return {
+    host: hostname(),
+    pid: process.pid,
+    cwd: process.cwd(),
+    command: command ?? null,
+  };
+}
+
+/**
+ * The reader key for this invocation. A name is validated; without one the
+ * key is derived from (host, uid, cwd), so repeated runs of the same cron job
+ * or agent are one reader, and a second agent working elsewhere is another.
+ */
+export function readerKey(name, ctx = processContext()) {
+  if (name !== undefined && name !== null && name !== true && name !== "") {
+    const n = String(name);
+    if (!READER_NAME_RE.test(n)) {
+      const e = new Error(`reader name "${n}" is not allowed: use 1-64 letters, digits, ".", "_" or "-", starting with a letter or digit`);
+      e.code = "bad-reader-name";
+      throw e;
+    }
+    return { key: n, named: true };
+  }
+  const h = createHash("sha256").update(`${ctx.host}|${uid()}|${ctx.cwd}`).digest("hex").slice(0, 8);
+  return { key: `${IMPLICIT_PREFIX}${h}`, named: false };
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === "EPERM"; } // exists, just not ours to signal
+}
+
+/**
+ * Leases held by OTHER live processes. On this host a pid that no longer
+ * exists is dead whatever its lease says (a crashed recv never released it);
+ * on another host the lease's own expiry is all there is to go on.
+ */
+export function otherLiveLeases(mailbox, ctx = processContext()) {
+  return mailbox.unexpiredLeases().filter((l) => {
+    if (l.host === ctx.host && l.pid === ctx.pid) return false;
+    if (l.host === ctx.host) return pidAlive(l.pid);
+    return true;
+  });
+}
+
+/** "pillar recv (pid 4242 on mac, /work/bot, since 2026-09-28T…)" */
+export function describeProcess(row) {
+  const where = [row.pid != null ? `pid ${row.pid}` : null, row.host ? `on ${row.host}` : null, row.cwd ?? null]
+    .filter(Boolean).join(", ");
+  const when = row.started_at ? `since ${row.started_at}` : row.last_seen ? `last seen ${row.last_seen}` : null;
+  return `${row.command ?? "a pillar process"} (${[where, when].filter(Boolean).join(", ")})`;
+}
+
+/** The reader a row was pulled by, for a warning line. */
+export function describeReader(mailbox, key) {
+  if (!key) return "a process that did not record itself (pillar older than this one, or the library)";
+  const r = mailbox.getReader(key);
+  const label = key.startsWith(IMPLICIT_PREFIX) ? "an unnamed reader" : `reader "${key}"`;
+  return r ? `${label}: ${describeProcess(r)}` : label;
+}
+
+/**
+ * Where a brand-new named reader starts: just before the oldest row nobody
+ * has marked read, so it sees everything still unread and nothing older;
+ * at the tip when everything has been read.
+ */
+export function initialCursor(mailbox) {
+  const row = mailbox.db.prepare("select min(seq) as s from inbox where read_at is null and quarantined is null").get();
+  return row?.s ? row.s - 1 : mailbox.inboxTipSeq();
+}
+
+/**
+ * Hand a named reader's rows to `handle` in order, advancing the cursor past
+ * each row whether or not its handler threw: at most once, exactly like an
+ * unnamed recv's handlers. A handler that fails because the carrier is down
+ * (its reply cannot go out) would otherwise hold the cursor, and the next
+ * tick would forward the same request again, once a second.
+ */
+export async function handleInOrder(rows, handle, { advance, onError }) {
+  for (const row of rows) {
+    try { await handle(row); }
+    catch (e) { onError(row, e); }
+    advance(row);
+  }
+}