@uuaid/pillar 2.0.2 → 2.2.0

package/bin/pillar.mjs

@@ -2,32 +2,54 @@
 /**
  * pillar — one-command CLI.
  *
- *   pillar init  [--home ~/.pillar]              first-time setup: mint UUAID + keys
+ *   pillar init  [--home ~/.pillar] [--namespace pillar|agentnet|foundation]
+ *                                                first-time setup: mint UUAID + keys (default namespace: foundation in 2.2.0)
  *   pillar init --refresh [--directory URL]      re-sync carriers + address book (keychain untouched)
+ *   pillar init --force --confirm <current uuaid> REPLACE the identity (new UUAID); the old one is archived
  *   pillar id    [--home ~/.pillar]              print our UUAID + PeerId + addrs
- *   pillar send  <recipient> <kind> <json>       send a signed envelope
- *   pillar recv  [--home ~/.pillar] [--follow]   listen for envelopes and print them
- *   pillar inbox [--home ~/.pillar] [--unread] [--notify CMD] [--mark-read]
+ *   pillar send  <recipient|name> <kind> <json> [--wait-ack S]
+ *                                                send a signed envelope; optionally wait for the recipient's signed ack
+ *   pillar recv  [--home ~/.pillar] [--reader NAME]  listen for envelopes and print them
+ *   pillar inbox [--home ~/.pillar] [--reader NAME] [--unread] [--notify CMD] [--mark-read]
  *                                                one-shot: pull pending mail, print, exit
+ *   pillar wait  [--reader NAME] [--timeout S]   sleep until there is mail, print the count, exit 0 (3 on timeout)
+ *   pillar readers                               every reader of this home, its cursor and any live lease
+ *   pillar status [envelope-id] [--wait S]       outbox: carrier acceptance and the recipient's signed receipts
+ *   pillar receipts [on|off|delivered on|off|read on|off]   send signed acks / read receipts (off by default)
+ *   pillar group create|send|add|rename|leave|accept|show   group threads (pillar-group v1)
+ *   pillar group create --v2 | invite|remove|ext|transfer|list|queue|sync, and any verb
+ *                naming a pillar-group/2 group      signed rosters (src/group-v2-cli.mjs)
+ *   pillar groups                                list this home's groups
  *   pillar trust [set|allow|block|unlist|quarantine]   recipient consent policy
  *   pillar tier  [issue|install|verify]          signed volume/size tier grants
  *   pillar peers                                 list currently connected peers
  *
  * All commands respect --home to point at an alternate pillar directory,
  * useful for running multiple pillars on one machine (Zestro dogfood etc.).
+ * More than one process reading ONE home: give each its own --reader NAME
+ * (or PILLAR_READER) so each has its own cursor; see src/readers.mjs.
  */
 import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
-import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { argv, exit } from "node:process";
-import { Keychain } from "../src/identity/keychain.mjs";
+import { Keychain, mintNamespace, SELF_CERTIFYING_NAMESPACES } from "../src/identity/keychain.mjs";
 import { Pillar } from "../src/pillar.mjs";
-import { loadFleetAddressBook } from "../src/address-book.mjs";
+import { loadFleetAddressBook, inspectFleetFile, resolveRecipient, explainMissingKey } from "../src/address-book.mjs";
 import { loadTrustPolicy, POLICIES } from "../src/identity/trust.mjs";
 import { parseLinkOffer, isLinkOfferLive, LINK_GRANT_KINDS } from "../src/net/link-offer.mjs";
 import { mintDelegationDoc } from "../src/net/delegation.mjs";
 import { refusalLine } from "../src/net/refusals.mjs";
+import {
+  readerKey, processContext, otherLiveLeases, describeProcess, describeReader, initialCursor, handleInOrder,
+  LEASE_TTL_MS, LEASE_HEARTBEAT_MS,
+} from "../src/readers.mjs";
+import { extractGroupTag, findGroup, normalizeMembers } from "../src/groups.mjs";
+import { describeOutboundStatus, receiptFor } from "../src/receipts.mjs";
+import { groupCommandRoute, groupRouteLookups, RosterStore } from "../src/groups-v2.mjs";
+import { runGroupV2 } from "../src/group-v2-cli.mjs";
+import { Mailbox } from "../src/mailbox/mailbox.mjs";
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -52,16 +74,34 @@ function fleetPath(args) {
   return args.fleet || join(homePath(args), "fleet.json");
 }
 
-function loadPillar(args) {
+function readConfig(home) {
+  const cfgPath = join(home, "config.json");
+  if (!existsSync(cfgPath)) return {};
+  try { return JSON.parse(readFileSync(cfgPath, "utf-8")); }
+  catch (e) {
+    console.error(`${cfgPath} is not valid JSON (${e.message}) — fix it, or re-create it with pillar init --refresh --directory <url>`);
+    exit(2);
+  }
+}
+
+// Receipts are opt-in: config.json `receipts: { delivered, read }` (pillar
+// receipts on|off), overridden per run by --ack (delivery acks on) and
+// --no-receipts (both off).
+function receiptsFor(args, cfg) {
+  if (args["no-receipts"]) return { delivered: false, read: false };
+  const r = cfg.receipts ?? {};
+  return { delivered: !!r.delivered || !!args.ack, read: !!r.read };
+}
+
+function loadPillar(args, { reader = null } = {}) {
   const home = homePath(args);
   const kcPath = join(home, "keychain.json");
   const mbPath = join(home, "mailbox.db");
-  const cfgPath = join(home, "config.json");
   if (!existsSync(kcPath)) {
     console.error(`no pillar found at ${home}. run: pillar init`);
     exit(2);
   }
-  const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, "utf-8")) : {};
+  const cfg = readConfig(home);
   const kc = new Keychain(kcPath);
   kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
   const carriers = args.carrier
@@ -91,9 +131,69 @@ function loadPillar(args) {
     enableLibp2p: !(args["carrier-only"] || cfg.carrierOnly === true),
     trust,
     tierGrant,
+    reader,
+    receipts: receiptsFor(args, cfg),
   });
 }
 
+/**
+ * Load the address book into `p`, printing every problem with it on stderr
+ * (once), and return the inspection so a later error can say exactly why a
+ * contact is unusable instead of "no public key known".
+ */
+function loadContacts(args, p) {
+  const path = fleetPath(args);
+  const info = inspectFleetFile(path);
+  const n = loadFleetAddressBook(path, p, { onProblem: (msg) => console.error(`warning: ${msg}`) });
+  return { info, n, path };
+}
+
+// ── readers ───────────────────────────────────────────────────────────────────
+
+function readerFor(args) {
+  const name = args.reader ?? process.env.PILLAR_READER;
+  try { return readerKey(name); }
+  catch (e) { console.error(e.message); exit(2); }
+}
+
+/**
+ * Tell this reader, on stderr, about any live process that will pull its
+ * mail first. Unnamed readers share a view with every other process, so any
+ * live consumer matters; a named reader only collides with its own name.
+ * `showsUnread`: an unnamed reader printing the unread backlog (--unread)
+ * loses nothing to a recv (recv never marks mail read), so it is not warned.
+ */
+function warnAboutLiveReaders(p, rk, ctx, { showsUnread = false } = {}) {
+  const leases = otherLiveLeases(p.mailbox, ctx);
+  const clash = rk.named ? leases.filter((l) => l.reader === rk.key) : (showsUnread ? [] : leases);
+  for (const l of clash) {
+    if (rk.named) {
+      console.error(`warning: reader "${rk.key}" is also held by ${describeProcess(l)}. Two processes under one reader name share one cursor, so each sees only part of the mail. Give each its own --reader NAME.`);
+    } else {
+      console.error(`warning: ${describeProcess(l)} is reading this home${l.reader.startsWith("ctx:") ? "" : ` as reader "${l.reader}"`}. It pulls mail as it arrives, so that mail will not be listed as new here. Give each reader its own cursor with --reader NAME (or PILLAR_READER).`);
+    }
+  }
+}
+
+function inboxLine(env, payload, extra = {}) {
+  const line = { ...extra, id: env.id, from: env.sender, fromPublicKey: env.transportSignature?.publicKey ?? null, kind: env.kind, at: env.createdAt, payload };
+  const tag = extractGroupTag(payload);
+  if (tag) {
+    line.group = tag.name;
+    line.groupId = tag.id;
+    if (tag.msgId) line.msgId = tag.msgId;
+    if (tag.op !== "message") line.op = tag.op;
+  }
+  return line;
+}
+
+function viewOfRow(p, row, decrypt) {
+  const env = JSON.parse(row.envelope_json);
+  let payload;
+  try { payload = decrypt(p.keychain, env); } catch (_e) { payload = { error: "decrypt failed" }; }
+  return { env, payload, seq: row.seq, groupId: row.group_id ?? null, pulledBy: row.pulled_by ?? null };
+}
+
 function loadGroups(args) {
   // groups.json lives next to fleet.json by default:
   // { "groups": { "<name>": { "members": ["uuaid:...", ...] } } }
@@ -186,14 +286,26 @@ async function cmdInit(args) {
   }
 
   const kcPath = join(home, "keychain.json");
-  if (existsSync(kcPath) && !args.force) {
-    console.error(`keychain already exists at ${kcPath}. use --force to overwrite.`);
-    exit(1);
+  let rotated = null;
+  if (existsSync(kcPath)) {
+    const old = new Keychain(kcPath).publicView();
+    if (!args.force) {
+      console.error(`this home already has an identity: ${old?.uuaid ?? kcPath}`);
+      console.error(`  re-sync carriers and contacts, keeping it:  pillar init --refresh --directory <url> --home ${home}`);
+      console.error(`  replace it with a NEW identity (new UUAID): pillar init --force --confirm <current uuaid> --home ${home}`);
+      exit(1);
+    }
+    rotated = await confirmAndArchiveIdentity(home, old, args);
   }
+  let uuaidNamespace;
+  try { uuaidNamespace = mintNamespace(args.namespace === undefined ? undefined : args.namespace); }
+  catch { console.error(`init: --namespace must be one of ${SELF_CERTIFYING_NAMESPACES.join(", ")}`); exit(1); }
   const kc = new Keychain(kcPath);
-  const id = Keychain.generate();
+  const id = Keychain.generate({ uuaidNamespace });
   kc.save(id, { passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
-  const cfg = {
+  // A rotation keeps the home's settings (carriers, receipts, …); only the
+  // identity and what is bound to it were archived.
+  const cfg = rotated ? readConfig(home) : {
     listenAddrs: ["/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/tcp/0/ws"],
     bootstrapPeers: [],
     enableRelay: false,
@@ -223,10 +335,70 @@ async function cmdInit(args) {
   console.log(`initialized pillar at ${home}`);
   console.log(`uuaid: ${id.uuaid}`);
   console.log(`publicKey: ${id.publicKeyHex}`);
+  if (rotated) {
+    console.log(`\nreplaced identity ${rotated.uuaid}`);
+    console.log(`  archived to ${rotated.dir} (keychain, mailbox, tier grant): the old key still opens the old mail there`);
+    console.log(`  every contact and directory listing still names the OLD uuaid: send them the new uuaid + publicKey, and re-list it`);
+    if (cfg.carriers?.length) console.log(`  carriers kept: ${cfg.carriers.join(", ")}`);
+    return;
+  }
   console.log(`\nconfig: ${join(home, "config.json")}`);
   console.log(`edit bootstrapPeers to join a network, or run again with --directory <url> / --carriers a,b to wire seeds.`);
 }
 
+/**
+ * `init --force` replaces an identity, which silently breaks every contact
+ * that knows the old UUAID. So it must be confirmed, and it is never lossy:
+ *
+ *   - interactive: type the current UUAID's last 8 characters;
+ *     non-interactive: --confirm <current uuaid, or its last 8 characters>
+ *   - refused while a live `pillar recv` holds this home (it would keep
+ *     writing into the archived mailbox)
+ *   - everything bound to the old identity (keychain, mailbox, tier grant,
+ *     runtime file) is MOVED to <home>/rotated/<time>-<old id>/, not deleted
+ *
+ * Returns { uuaid, dir }.
+ */
+async function confirmAndArchiveIdentity(home, old, args) {
+  const current = old?.uuaid ?? "";
+  const tail = current.replace(/-/g, "").slice(-8);
+  const accepted = (v) => typeof v === "string" && (v === current || v.replace(/-/g, "").toLowerCase() === tail.toLowerCase());
+  let answer = typeof args.confirm === "string" ? args.confirm : null;
+  if (answer === null && process.stdin.isTTY && process.stderr.isTTY) {
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    console.error(`This REPLACES the identity of ${home}:`);
+    console.error(`  ${current}`);
+    console.error(`with a new key and a new UUAID. Contacts that know the old one will no longer reach you.`);
+    answer = (await rl.question(`Type the last 8 characters of the current UUAID (${tail}) to continue: `)).trim();
+    rl.close();
+  }
+  if (!accepted(answer)) {
+    console.error(answer === null
+      ? `init --force replaces ${current} with a NEW identity. Confirm it: pillar init --force --confirm ${current}`
+      : `confirmation "${answer}" does not match ${current}; nothing was changed`);
+    exit(1);
+  }
+  const { Mailbox } = await import("../src/mailbox/mailbox.mjs");
+  const mbPath = join(home, "mailbox.db");
+  if (existsSync(mbPath)) {
+    const mb = new Mailbox(mbPath);
+    const live = otherLiveLeases(mb);
+    mb.close();
+    if (live.length) {
+      console.error(`refusing to replace the identity while ${live.map(describeProcess).join("; ")} is reading this home — stop it first`);
+      exit(1);
+    }
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dir = join(home, "rotated", `${stamp}-${(current.split(":")[3] ?? "unknown").slice(0, 8)}`);
+  mkdirSync(dir, { recursive: true });
+  for (const f of ["keychain.json", "mailbox.db", "mailbox.db-wal", "mailbox.db-shm", "tier-grant.json", "runtime.json"]) {
+    if (existsSync(join(home, f))) renameSync(join(home, f), join(dir, f));
+  }
+  return { uuaid: current, dir };
+}
+
 async function cmdId(args) {
   const p = loadPillar(args);
   await p.start();
@@ -244,31 +416,85 @@ async function cmdId(args) {
 }
 
 async function cmdSend(args) {
-  const [recipient, kind, jsonStr] = args._.slice(1);
-  if (!recipient || !kind) {
-    console.error("usage: pillar send <recipient-uuaid> <kind> [json-payload] [--fleet FLEET.json]");
+  const [recipientArg, kind, jsonStr] = args._.slice(1);
+  if (!recipientArg || !kind) {
+    console.error("usage: pillar send <recipient-uuaid|contact-name> <kind> [json-payload] [--to-pubkey HEX] [--wait-ack SECONDS] [--fleet FLEET.json]");
     exit(2);
   }
-  const payload = jsonStr ? JSON.parse(jsonStr) : {};
+  let payload = {};
+  if (jsonStr) {
+    try { payload = JSON.parse(jsonStr); }
+    catch (e) { console.error(`the payload is not valid JSON (${e.message}): ${jsonStr.slice(0, 120)}`); exit(2); }
+  }
   const p = loadPillar(args);
   await p.start();
-  const n = loadFleetAddressBook(fleetPath(args), p);
+  const { info, n } = loadContacts(args, p);
   if (n > 0) console.log(`address book: ${n} peers`);
+  let recipient;
+  try { recipient = resolveRecipient(recipientArg, info).uuaid; }
+  catch (e) { await p.stop(); console.error(e.message); exit(2); }
+  const toKey = typeof args["to-pubkey"] === "string" ? args["to-pubkey"] : undefined;
+  // Say WHY there is no key before the library says only that there is none
+  // (a malformed contacts file used to surface as "no public key known").
+  if (!toKey && !p.addressBook?.get(recipient)?.publicKey && !p.node) {
+    await p.stop();
+    console.error(explainMissingKey(recipient, info));
+    exit(1);
+  }
   try {
     const { envelope, delivery } = await p.send({
       recipient, kind, payload,
-      recipientPublicKey: args["to-pubkey"],  // explicit key for peers outside fleet.json
+      recipientPublicKey: toKey,  // explicit key for peers outside fleet.json
       resolveTimeoutMs: 5000,
     });
     console.log(`sent envelope ${envelope.id}`);
-    console.log(`  to:   ${recipient}`);
+    console.log(`  to:   ${recipient}${recipient !== recipientArg ? ` (${recipientArg})` : ""}`);
     console.log(`  kind: ${kind}`);
     if (delivery?.peerId) console.log(`  via peerId: ${delivery.peerId}`);
+    if (delivery?.carrier) console.log(`  accepted by carrier ${delivery.carrier} (seq ${delivery.seq}) — that is the carrier's receipt, not the recipient's`);
+    if (args["wait-ack"] !== undefined) {
+      const secs = args["wait-ack"] === true ? 60 : Number(args["wait-ack"]);
+      if (!Number.isFinite(secs) || secs <= 0) { console.error("--wait-ack takes a number of seconds"); exit(2); }
+      const r = await waitForAck(p, envelope.id, recipient, Date.now() + secs * 1000);
+      if (r.acked) {
+        console.log(`  acknowledged: signed by ${recipient} (${r.how}, ${r.at})`);
+      } else {
+        console.error(`  no signed ack from ${recipient} within ${secs}s. The carrier holds the envelope; the recipient has not acknowledged it (acks are opt-in on their side: pillar receipts on).`);
+        exit(4);
+      }
+    }
+  } catch (e) {
+    if (/no public key known/.test(e.message)) { console.error(explainMissingKey(recipient, info)); exit(1); }
+    throw e;
   } finally {
     await p.stop();
   }
 }
 
+/**
+ * Wait for the recipient's signed ack of `envelopeId` without consuming any
+ * other mail: the carriers are PEEKED (nothing stored, no cursor moved), so
+ * whoever reads this home next still sees everything as new. A row another
+ * process of this home already acked (it pulled the ack) counts too.
+ */
+async function waitForAck(p, envelopeId, recipient, deadlineMs) {
+  const acked = () => p.mailbox.getOutbound(envelopeId)?.recipient_ack_at ?? null;
+  if (acked()) return { acked: true, how: "already recorded", at: acked() };
+  if (!p.carrierClient) return { acked: false };
+  const hits = await p.peekCarrierInbox({
+    deadlineMs,
+    stopWhen: () => !!acked(),
+    match: (v) => receiptFor(v, envelopeId, recipient, { read: p.receipts.read }) !== null,
+  });
+  if (hits.length) {
+    const h = hits[0];
+    const said = receiptFor(h, envelopeId, recipient, { read: p.receipts.read });
+    if (said === "delivered") p.mailbox.markOutboundAcked(envelopeId, { from: recipient, ackId: h.id, at: h.createdAt });
+    else p.mailbox.markOutboundRead([envelopeId], { at: h.createdAt });
+    return { acked: true, how: said === "read" ? "read receipt" : "delivery ack", at: h.createdAt };
+  }
+  return acked() ? { acked: true, how: "recorded by another reader of this home", at: acked() } : { acked: false };
+}
 
 // ── delegate ──────────────────────────────────────────────────────────────────
 // The desktop-link ceiling enforced by chat-web (browser-chat-session.ts,
@@ -388,42 +614,214 @@ async function cmdSendGroup(args) {
   const [groupName, kind, jsonStr] = args._.slice(1);
   if (!groupName || !kind) {
     console.error("usage: pillar send-group <group> <kind> [json-payload] --fleet FLEET.json [--groups GROUPS.json]");
+    console.error("  (or keep the thread in this home: pillar group create / pillar group send)");
     exit(2);
   }
   const { path: gPath, groups } = loadGroups(args);
   const group = groups[groupName];
-  if (!group?.members?.length) {
-    console.error(`group "${groupName}" not found or empty (looked in ${gPath ?? "no groups file"})`);
-    exit(2);
-  }
   const payload = jsonStr ? JSON.parse(jsonStr) : {};
   const p = loadPillar(args);
   await p.start();
-  loadFleetAddressBook(fleetPath(args), p);
+  loadContacts(args, p);
   try {
-    const { results } = await p.sendGroup({ group: groupName, members: group.members, kind, payload });
-    let failed = 0;
-    for (const r of results) {
-      if (r.ok) console.log(`  ✓ ${r.member}  via ${r.via}  ${r.envelopeId}`);
-      else { failed++; console.error(`  ✗ ${r.member}  ${refusalLine(r) ?? r.error}`); }
-    }
-    console.log(`group "${groupName}": ${results.length - failed}/${results.length} delivered`);
-    if (failed) exit(1);
+    let spec;
+    if (group?.members?.length) {
+      spec = { group: groupName, members: group.members };
+    } else {
+      let g;
+      try { g = findGroup(p.mailbox, groupName); }
+      catch (e) {
+        console.error(`group "${groupName}" not found or empty (looked in ${gPath ?? "no groups file"} and in this home's groups: ${e.message})`);
+        exit(2);
+      }
+      spec = { groupId: g.id };
+    }
+    const r = await p.sendGroup({ ...spec, kind, payload });
+    printGroupResults(r);
   } finally {
     await p.stop();
   }
 }
 
+function printGroupResults({ group, groupId, msgId, results }) {
+  let failed = 0;
+  for (const r of results) {
+    if (r.ok) console.log(`  ✓ ${r.member}  via ${r.via}  ${r.envelopeId}`);
+    else {
+      failed++;
+      const why = refusalLine(r) ?? (/no public key known/.test(r.error ?? "")
+        ? `no public key known — add it to fleet.json, or ask a member to post in the group (its key hint is then learned)`
+        : r.error);
+      console.error(`  ✗ ${r.member}  ${why}`);
+    }
+  }
+  console.log(`group "${group}" ${groupId} msg ${msgId}: ${results.length - failed}/${results.length} accepted by carrier`);
+  if (failed) exit(1);
+}
+
 async function cmdGroups(args) {
+  const home = homePath(args);
+  const { Mailbox } = await import("../src/mailbox/mailbox.mjs");
+  const mine = existsSync(join(home, "mailbox.db")) ? (() => {
+    const mb = new Mailbox(join(home, "mailbox.db"));
+    try { return mb.listGroups(); } finally { mb.close(); }
+  })() : [];
   const { path: gPath, groups } = loadGroups(args);
   const names = Object.keys(groups);
-  if (!names.length) { console.log(`no groups defined (${gPath ?? "no groups file"})`); return; }
+  if (!mine.length && !names.length) { console.log(`no groups (create one: pillar group create <name> <member>...)`); return; }
+  for (const g of mine) {
+    const flags = [g.pending ? "PENDING invitation — pillar group accept " + g.id : null, g.left ? "left" : null].filter(Boolean);
+    console.log(`${g.id}  ${g.name} (${g.members.length} members)${flags.length ? `  [${flags.join(", ")}]` : ""}`);
+    for (const m of g.members) console.log(`  ${m}`);
+  }
   for (const n of names) {
-    console.log(`${n} (${groups[n].members.length} members):`);
+    console.log(`${n} (${groups[n].members.length} members, from ${gPath}):`);
     for (const m of groups[n].members) console.log(`  ${m}`);
   }
 }
 
+/**
+ * pillar group <create|send|add|rename|leave|accept|show> — group threads.
+ *
+ * The roster lives in this home (mailbox `groups`); every member keeps its
+ * own copy and applies the pillar-group v1 rules (src/groups.mjs). Members
+ * can be given as UUAIDs or as contact names from fleet.json.
+ */
+async function cmdGroup(args) {
+  const sub = args._[1];
+  const usage = () => {
+    console.error(`usage:
+  pillar group create <name> <member>... [--text TEXT]
+  pillar group send   <group> <text> | --json '{...}' [--kind KIND]
+  pillar group add    <group> <member>...
+  pillar group rename <group> <new name>
+  pillar group leave  <group>
+  pillar group accept <group>
+  pillar group show   <group> [--limit N]
+<group> is a grp-… id or a unique group name; <member> is a uuaid or a fleet.json contact name.`);
+    exit(2);
+  };
+  if (!["create", "send", "add", "rename", "leave", "accept", "show"].includes(sub)) usage();
+  args["carrier-only"] = args["carrier-only"] ?? true;
+  const p = loadPillar(args);
+  await p.start();
+  const { info } = loadContacts(args, p);
+  const members = (list) => list.map((m) => {
+    try { return resolveRecipient(m, info).uuaid; }
+    catch (e) { console.error(e.message); exit(2); }
+  });
+  const group = (ref) => {
+    if (!ref) usage();
+    try { return findGroup(p.mailbox, ref); }
+    catch (e) { console.error(e.message); exit(2); }
+  };
+  try {
+    if (sub === "create") {
+      const [name, ...rest] = args._.slice(2);
+      if (!name || !rest.length) usage();
+      const roster = normalizeMembers([p.uuaid, ...members(rest)]);
+      const r = await p.sendGroup({ group: name, members: roster, payload: { text: typeof args.text === "string" ? args.text : "" }, op: "create" });
+      printGroupResults(r);
+      return;
+    }
+    if (sub === "send") {
+      const g = group(args._[2]);
+      let payload;
+      if (typeof args.json === "string") {
+        try { payload = JSON.parse(args.json); } catch (e) { console.error(`--json is not valid JSON: ${e.message}`); exit(2); }
+      } else {
+        const text = args._.slice(3).join(" ");
+        if (!text) usage();
+        payload = { text };
+      }
+      printGroupResults(await p.sendGroup({ groupId: g.id, kind: typeof args.kind === "string" ? args.kind : "message", payload }));
+      return;
+    }
+    if (sub === "add") {
+      const g = group(args._[2]);
+      const added = members(args._.slice(3)).filter((m) => !g.members.includes(m));
+      if (!added.length) { console.log(`nothing to add: every one of them is already in ${g.id}`); return; }
+      p.mailbox.putGroup({ ...g, members: [...g.members, ...added] });
+      printGroupResults(await p.sendGroup({ groupId: g.id, payload: { text: added.join(",") }, op: "add" }));
+      return;
+    }
+    if (sub === "rename") {
+      const g = group(args._[2]);
+      const name = args._.slice(3).join(" ").trim();
+      if (!name) usage();
+      p.mailbox.putGroup({ ...g, name });
+      printGroupResults(await p.sendGroup({ groupId: g.id, payload: { text: "" }, op: "rename" }));
+      return;
+    }
+    if (sub === "leave") {
+      const g = group(args._[2]);
+      if (g.left) { console.log(`already left ${g.id}`); return; }
+      if (!g.pending) {
+        const r = await p.sendGroup({ groupId: g.id, payload: { text: "" }, op: "leave" });
+        for (const x of r.results) if (!x.ok) console.error(`  ✗ ${x.member}  ${x.error}`);
+      }
+      p.mailbox.putGroup({ ...g, left: true, pending: false });
+      console.log(`left ${g.id} (${g.name}); its history stays in this home`);
+      return;
+    }
+    if (sub === "accept") {
+      const g = group(args._[2]);
+      if (!g.pending) { console.log(`${g.id} is not a pending invitation`); return; }
+      p.mailbox.putGroup({ ...g, pending: false });
+      console.log(`accepted ${g.id} (${g.name}), created by ${g.createdBy}`);
+      console.log(`note: messages from members who are not your contacts still follow trust.json (pillar trust allow <uuaid>)`);
+      return;
+    }
+    if (sub === "show") {
+      const g = group(args._[2]);
+      const limit = Number(args.limit ?? 30);
+      const { decrypt } = await import("../src/net/envelope.mjs");
+      // A local view: it never pulls from carriers (that would take "new" away
+      // from the next inbox run). Pull with pillar inbox first.
+      console.log(JSON.stringify({ group: g.id, name: g.name, members: g.members, pending: g.pending, left: g.left, createdBy: g.createdBy, view: "local — pull new mail with pillar inbox" }));
+      const items = [];
+      for (const row of p.mailbox.groupInbound(g.id, limit)) {
+        const { env, payload } = viewOfRow(p, row, decrypt);
+        const tag = extractGroupTag(payload);
+        items.push({ at: env.createdAt, line: { dir: "in", id: env.id, from: env.sender, kind: env.kind, msgId: tag?.msgId ?? null, op: tag?.op ?? "message", text: typeof payload?.text === "string" ? payload.text : undefined, payload: typeof payload?.text === "string" ? undefined : payload } });
+      }
+      // Our own messages: one line per group message (its fan-out copies
+      // collapsed by msgId). The outbox is sealed to each member, so we hold
+      // no plaintext for it — only who it went to and what they signed back.
+      const byMsg = new Map();
+      for (const row of p.mailbox.groupOutbound(g.id)) {
+        const k = row.group_msg_id ?? row.envelope_id;
+        const m = byMsg.get(k) ?? { at: row.created_at, to: 0, carrier: 0, acked: 0, read: 0 };
+        m.to++; if (row.status === "delivered") m.carrier++; if (row.recipient_ack_at) m.acked++; if (row.recipient_read_at) m.read++;
+        byMsg.set(k, m);
+      }
+      for (const [msgId, m] of byMsg) items.push({ at: m.at, line: { dir: "out", msgId, at: m.at, members: m.to, acceptedByCarrier: m.carrier, acknowledged: m.acked, read: m.read } });
+      items.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+      for (const it of items.slice(-limit)) console.log(JSON.stringify(it.line));
+      return;
+    }
+  } finally {
+    await p.stop();
+  }
+}
+
+// `pillar group` runs pillar-group/2 (src/group-v2-cli.mjs) for its own verbs, for
+// create --v2, and for any group the v2 store holds or whose row the v2 sync marked
+// (groupCommandRoute). Everything else runs cmdGroup above, unchanged.
+function wantsGroupV2(args) {
+  const home = homePath(args);
+  const mbPath = join(home, "mailbox.db");
+  const mb = existsSync(mbPath) ? new Mailbox(mbPath) : null;
+  try { return groupCommandRoute(args, groupRouteLookups(new RosterStore(home), mb)) === "v2"; }
+  finally { mb?.close(); }
+}
+
+async function cmdGroupV2(args) {
+  args["carrier-only"] = args["carrier-only"] ?? true;
+  const code = await runGroupV2(args, { home: homePath(args), openPillar: async () => loadPillar(args) });
+  if (code) exit(code);
+}
+
 // Extract human-readable text from a zestro command_result. The server-side
 // payload fields are unverified — defensively try the common shapes, cap at
 // 8192 bytes (pillar-responder's MAX_REPLY_BYTES convention).
@@ -438,10 +836,29 @@ function replyTextFromResult(result) {
 }
 
 async function cmdRecv(args) {
-  const p = loadPillar(args);
+  const rk = readerFor(args);
+  const ctx = processContext({ command: rk.named ? `pillar recv --reader ${rk.key}` : "pillar recv" });
+  // A daemon with no contacts quarantines every fleet message under an
+  // allowlist or directory policy and moves the carrier cursor past it. A
+  // contacts file that exists but yields nothing at all stops recv instead.
+  const fleetInfo = inspectFleetFile(fleetPath(args));
+  if (fleetInfo.error) { console.error(`recv: ${fleetInfo.error}`); exit(1); }
+  const p = loadPillar(args, { reader: rk.key });
   await p.start();
   writeRuntimeFile(p, homePath(args)); // warm handoff: publish live addr for senders
-  const n = loadFleetAddressBook(fleetPath(args), p);
+  const { n } = loadContacts(args, p);
+  // Lease: other readers of this home are told a live recv is pulling mail.
+  warnAboutLiveReaders(p, rk, ctx);
+  const prevReader = p.mailbox.getReader(rk.key);
+  // A NEW named reader of a bridged recv starts at the tip: its unread
+  // backlog would otherwise reach the bridge as fresh agent turns.
+  const bridged = !!(args["zestro-bridge"] || process.env.PILLAR_ZESTRO_URL);
+  const start = bridged ? p.mailbox.inboxTipSeq() : initialCursor(p.mailbox);
+  p.mailbox.touchReader(rk.key, { ...ctx, cursor: prevReader ? 0 : start });
+  const lease = () => p.mailbox.holdLease(rk.key, { ...ctx, ttlMs: LEASE_TTL_MS });
+  lease();
+  const heartbeat = setInterval(() => { try { lease(); } catch (_e) {} }, LEASE_HEARTBEAT_MS);
+  heartbeat.unref?.();
   console.log(`listening as ${p.uuaid}`);
   if (p.node) {
     console.log(`peerId ${p.node.peerId.toString()}`);
@@ -472,9 +889,14 @@ async function cmdRecv(args) {
     console.log(`zestro bridge connected to ${bridge.url.replace(/\/[0-9a-f-]{36}\/ws$/, "/<token>/ws")}`);
   }
 
-  p.onEnvelope(async (env) => {
+  // With delivery acks on, the library already acked every envelope; the
+  // bridge must not send a second ack for a request.
+  const autoAcks = p.receipts.delivered;
+  const handle = async (env) => {
     const line = { at: new Date().toISOString(), from: env.sender, kind: env.kind, payload: env.payload };
-    if (env.payload?._group?.name) line.group = env.payload._group.name;
+    const tag = extractGroupTag(env.payload);
+    if (tag) { line.group = tag.name; line.groupId = tag.id; if (tag.msgId) line.msgId = tag.msgId; if (tag.op !== "message") line.op = tag.op; }
+    if (rk.named) line.id = env.id;
     console.log(JSON.stringify(line));
     if (bridge && env.kind === "request") {
       // Interaction-convention return leg: ack FIRST — pillar-ask allows 120s
@@ -489,7 +911,7 @@ async function cmdRecv(args) {
       const thread = env.payload?.thread ?? env.id;
       const senderKey = env.transportSignature.publicKey; // open() F1: sender derives from this key
       try {
-        await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
+        if (!autoAcks) await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
         const result = await bridge.sendCommand({ command: JSON.stringify({ kind: env.kind, payload: env.payload, sender: env.sender }) });
         const hasText = result && typeof result === "object" &&
           ["text", "result", "output", "response", "message"].some(k => k in result);
@@ -532,9 +954,46 @@ async function cmdRecv(args) {
       // inject a Zestro agent turn per receipt. Print-only (line above).
       console.log(`  → zestro: not bridged (kind=${env.kind} is a receipt)`);
     }
-  });
+  };
 
-  const shutdown = async () => { if (bridge) bridge.close(); await p.stop(); exit(0); };
+  let tail = null;
+  if (rk.named) {
+    // A named reader follows its own cursor over the LOCAL inbox, so it also
+    // sees rows another process of this home pulled first. Rows are handled
+    // strictly in order, at most once: the cursor moves past a row whose
+    // handler threw (handleInOrder), as an unnamed recv's handlers do.
+    const { decrypt } = await import("../src/net/envelope.mjs");
+    let busy = false;
+    const drainLocal = async () => {
+      if (busy) return;
+      busy = true;
+      try {
+        const cursor = p.mailbox.getReader(rk.key)?.cursor ?? 0;
+        await handleInOrder(p.mailbox.inboxAfter(cursor, 200), async (row) => {
+          const { env, payload } = viewOfRow(p, row, decrypt);
+          await handle({ ...env, payload });
+        }, {
+          advance: (row) => p.mailbox.setReaderCursor(rk.key, row.seq),
+          onError: (row, e) => console.error(`reader ${rk.key}: row ${row.seq} not handled, not retried: ${e.message}`),
+        });
+      } finally { busy = false; }
+    };
+    p.onEnvelope(() => drainLocal());
+    tail = setInterval(() => { drainLocal().catch((e) => console.error(`reader ${rk.key}: ${e.message}`)); }, 1000);
+    await drainLocal();
+    console.log(`reader "${rk.key}": cursor ${p.mailbox.getReader(rk.key)?.cursor ?? 0}`);
+  } else {
+    p.onEnvelope(handle);
+  }
+
+  const shutdown = async () => {
+    clearInterval(heartbeat);
+    if (tail) clearInterval(tail);
+    try { p.mailbox.releaseLease(rk.key, ctx); } catch (_e) {}
+    if (bridge) bridge.close();
+    await p.stop();
+    exit(0);
+  };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
   await new Promise(() => {});
@@ -545,47 +1004,99 @@ async function cmdInbox(args) {
   // minted the uuaid.  Pulls pending envelopes from the carrier (no long-poll),
   // prints them decrypted, reports unread backlog, exits.  --notify CMD runs a
   // shell hook when there is mail (cron/launchd-friendly); --mark-read stamps
-  // read_at on everything printed.
+  // read_at on everything printed (and sends read receipts when they are on).
+  //
+  // Readers. Without --reader the output is exactly what it always was: "new"
+  // is what THIS run pulled. With --reader NAME (or PILLAR_READER) this reader
+  // has its own cursor over the local inbox and "new" is every row after it,
+  // whoever pulled it, so several processes can share one home safely.
   args["carrier-only"] = true; // inbox check needs the carrier only — no libp2p listener
-  const p = loadPillar(args);
+  const rk = readerFor(args);
+  const ctx = processContext({ command: `pillar inbox${rk.named ? ` --reader ${rk.key}` : ""}` });
+  const p = loadPillar(args, { reader: rk.key });
   const fresh = [];
   p.onEnvelope((env) => { fresh.push(env); });
   await p.start();
   // Address book BEFORE the drain: the trust "directory" policy needs known
   // senders loaded, or every fresh envelope counts as a stranger.
-  loadFleetAddressBook(fleetPath(args), p);
+  loadContacts(args, p);
+  warnAboutLiveReaders(p, rk, ctx, { showsUnread: !!args.unread });
+  const prev = p.mailbox.getReader(rk.key);
+  // A new named reader starts before the oldest unread row, computed BEFORE
+  // this run's pull so that what it pulls is new to it too.
+  const startCursor = prev ? prev.cursor : (rk.named ? initialCursor(p.mailbox) : p.mailbox.inboxTipSeq());
+  p.mailbox.touchReader(rk.key, { ...ctx, cursor: startCursor });
   const pulled = await p.drainCarrierInbox();
-  // fromPublicKey: the sender's verified Ed25519 key (transportSignature —
-  // open() binds it to `from`). Lets a drain-and-reply consumer (the fleet
-  // courier's auto-ack, a bot) seal back to a sender who is NOT in fleet.json
-  // via `pillar send … --to-pubkey <fromPublicKey>`. Additive field.
-  for (const env of fresh) {
-    console.log(JSON.stringify({ new: true, id: env.id, from: env.sender, fromPublicKey: env.transportSignature?.publicKey ?? null, kind: env.kind, at: env.createdAt, payload: env.payload }));
-  }
-  // Backlog: rows stored earlier (e.g. by a recv daemon) but never surfaced.
   const { decrypt } = await import("../src/net/envelope.mjs");
-  const freshIds = new Set(fresh.map(e => e.id));
-  const backlog = (p.mailbox.inboxUnread?.(500) ?? []).filter(r => !freshIds.has(r.envelope_id));
-  if (args.unread) {
-    for (const row of backlog) {
-      const env = JSON.parse(row.envelope_json);
-      let payload = null;
-      try { payload = decrypt(p.keychain, env); } catch (_e) { payload = { error: "decrypt failed" }; }
-      console.log(JSON.stringify({ new: false, id: env.id, from: env.sender, fromPublicKey: env.transportSignature?.publicKey ?? null, kind: env.kind, at: env.createdAt, payload }));
-    }
-  }
-  const qCount = (p.mailbox.inboxQuarantined?.(500) ?? []).length;
-  console.log(`inbox: ${fresh.length} new, ${backlog.length} older unread${args.unread ? "" : " (--unread to print)"}${qCount ? `, ${qCount} quarantined (pillar trust quarantine)` : ""}`);
+  const printed = []; // { id, sender, kind, payload, groupId } — for read receipts
+
+  let backlog = [];
+  if (rk.named) {
+    const rows = p.mailbox.inboxAfter(startCursor, 1000);
+    for (const row of rows) {
+      const { env, payload, groupId } = viewOfRow(p, row, decrypt);
+      console.log(JSON.stringify(inboxLine(env, payload, { new: true })));
+      printed.push({ id: env.id, sender: env.sender, kind: env.kind, payload, groupId });
+    }
+    if (rows.length && !args.peek) p.mailbox.setReaderCursor(rk.key, rows.at(-1).seq);
+    const qCount = (p.mailbox.inboxQuarantined?.(500) ?? []).length;
+    console.log(`inbox: ${rows.length} new for reader "${rk.key}" (${pulled} pulled from carriers by this run)${args.peek ? ", cursor not moved (--peek)" : ""}${qCount ? `, ${qCount} quarantined (pillar trust quarantine)` : ""}`);
+  } else {
+    // fromPublicKey: the sender's verified Ed25519 key (transportSignature —
+    // open() binds it to `from`). Lets a drain-and-reply consumer (the fleet
+    // courier's auto-ack, a bot) seal back to a sender who is NOT in fleet.json
+    // via `pillar send … --to-pubkey <fromPublicKey>`. Additive field.
+    for (const env of fresh) {
+      console.log(JSON.stringify(inboxLine(env, env.payload, { new: true })));
+      printed.push({ id: env.id, sender: env.sender, kind: env.kind, payload: env.payload, groupId: extractGroupTag(env.payload)?.id ?? null });
+    }
+    // Backlog: rows stored earlier (e.g. by a recv daemon) but never surfaced.
+    const freshIds = new Set(fresh.map(e => e.id));
+    backlog = (p.mailbox.inboxUnread?.(500) ?? []).filter(r => !freshIds.has(r.envelope_id));
+    if (args.unread) {
+      for (const row of backlog) {
+        const { env, payload, groupId } = viewOfRow(p, row, decrypt);
+        console.log(JSON.stringify(inboxLine(env, payload, { new: false })));
+        printed.push({ id: env.id, sender: env.sender, kind: env.kind, payload, groupId });
+      }
+    }
+    // Mail another process of this home pulled since this reader last looked:
+    // it is not "new" here, and with --mark-read over there it is not even
+    // unread. Say so, and who took it, instead of letting it vanish.
+    // With --unread the unread ones were just printed, so only the ones some
+    // other reader already marked read are missing.
+    if (prev) {
+      const taken = p.mailbox.inboxAfter(prev.cursor, 1000)
+        .filter((r) => !freshIds.has(r.envelope_id) && r.pulled_by !== rk.key && (!args.unread || r.read_at));
+      if (taken.length) {
+        const by = new Map();
+        for (const r of taken) by.set(r.pulled_by ?? null, (by.get(r.pulled_by ?? null) ?? 0) + 1);
+        const readAlready = taken.filter((r) => r.read_at).length;
+        for (const [who, count] of by) {
+          console.error(`warning: ${count} envelope(s) reached this home since this reader last checked, pulled by ${describeReader(p.mailbox, who)}; they are not listed as new here.`);
+        }
+        const how = args.unread
+          ? "Give each reader its own cursor with --reader NAME (or PILLAR_READER)."
+          : "Print them with --unread, or give each reader its own cursor with --reader NAME (or PILLAR_READER).";
+        console.error(`  ${readAlready ? `${readAlready} of them are already marked read (only --reader shows those). ` : ""}${how}`);
+      }
+    }
+    p.mailbox.setReaderCursor(rk.key, p.mailbox.inboxTipSeq());
+    const qCount = (p.mailbox.inboxQuarantined?.(500) ?? []).length;
+    console.log(`inbox: ${fresh.length} new, ${backlog.length} older unread${args.unread ? "" : " (--unread to print)"}${qCount ? `, ${qCount} quarantined (pillar trust quarantine)` : ""}`);
+  }
   if (args["mark-read"]) {
-    for (const env of fresh) p.mailbox.markInboxRead?.(env.id);
-    if (args.unread) for (const row of backlog) p.mailbox.markInboxRead?.(row.envelope_id);
+    for (const v of printed) p.mailbox.markInboxRead?.(v.id);
+    const r = await p.sendReadReceipts(printed);
+    if (r.sent || r.dropped) console.error(`read receipts: ${r.sent} sent${r.dropped ? `, ${r.dropped} not sent (per-run cap)` : ""}`);
   }
-  if (args.notify && typeof args.notify === "string" && (pulled > 0 || backlog.length > 0)) {
+  const newCount = rk.named ? printed.length : pulled;
+  if (args.notify && typeof args.notify === "string" && (newCount > 0 || backlog.length > 0)) {
     const { spawnSync } = await import("node:child_process");
     const r = spawnSync(args.notify, {
       shell: true,
-      input: JSON.stringify({ uuaid: p.uuaid, new: pulled, unread: backlog.length }) + "\n",
-      env: { ...process.env, PILLAR_NEW: String(pulled), PILLAR_UNREAD: String(backlog.length), PILLAR_UUAID: p.uuaid },
+      input: JSON.stringify({ uuaid: p.uuaid, new: newCount, unread: backlog.length }) + "\n",
+      env: { ...process.env, PILLAR_NEW: String(newCount), PILLAR_UNREAD: String(backlog.length), PILLAR_UUAID: p.uuaid },
       stdio: ["pipe", "inherit", "inherit"],
     });
     if (r.status !== 0) console.error(`notify hook exited ${r.status}`);
@@ -594,6 +1105,142 @@ async function cmdInbox(args) {
   exit(0);
 }
 
+/**
+ * pillar wait — sleep until there is mail, then exit 0 with the count.
+ *
+ * The wake signal for homes that cannot take a push (no open ports): one
+ * outbound long-poll per carrier at zero CPU, woken by the carrier the moment
+ * mail lands. It only PEEKS — nothing is stored, no cursor moves — so the
+ * reader run it wakes still sees every message as new:
+ *
+ *   while pillar wait --reader bot; do pillar inbox --reader bot --mark-read | my-agent; done
+ *
+ * Counts only mail that would reach the reader: quarantine-bound envelopes
+ * (trust.json) never wake anyone. With --reader, rows another process already
+ * pulled into this home after the reader's cursor count too.
+ *
+ * Prints {"uuaid","pending","carrier","local","kinds"}; exit 0 mail, 3 timeout.
+ */
+async function cmdWait(args) {
+  args["carrier-only"] = true;
+  const rk = readerFor(args);
+  const ctx = processContext({ command: `pillar wait${rk.named ? ` --reader ${rk.key}` : ""}` });
+  const p = loadPillar(args, { reader: rk.key });
+  await p.start();
+  loadContacts(args, p);
+  warnAboutLiveReaders(p, rk, ctx);
+  const timeoutS = args.timeout !== undefined ? Number(args.timeout) : null;
+  if (timeoutS !== null && (!Number.isFinite(timeoutS) || timeoutS < 0)) { console.error("--timeout takes a number of seconds"); exit(2); }
+  const deadlineMs = timeoutS === null ? null : Date.now() + timeoutS * 1000;
+  const cursor = () => {
+    const r = p.mailbox.getReader(rk.key);
+    return r ? r.cursor : initialCursor(p.mailbox);
+  };
+  const localRows = () => (rk.named ? p.mailbox.inboxAfter(cursor(), 1000) : []);
+  const report = (carrierViews, local) => {
+    const kinds = {};
+    for (const k of [...carrierViews.map((v) => v.kind), ...local.map((r) => JSON.parse(r.envelope_json).kind)]) kinds[k] = (kinds[k] ?? 0) + 1;
+    console.log(JSON.stringify({ uuaid: p.uuaid, ...(rk.named ? { reader: rk.key } : {}), pending: carrierViews.length + local.length, carrier: carrierViews.length, local: local.length, kinds }));
+  };
+  let local = localRows();
+  if (local.length) { report([], local); await p.stop(); exit(0); }
+  if (!p.carrierClient) { console.error("wait: this home has no carriers configured (pillar init --refresh --directory <url>)"); exit(2); }
+  const views = await p.peekCarrierInbox({ deadlineMs, stopWhen: () => localRows().length > 0 });
+  local = localRows();
+  await p.stop();
+  if (views.length || local.length) { report(views, local); exit(0); }
+  console.log(JSON.stringify({ uuaid: p.uuaid, pending: 0, timedOut: true }));
+  exit(3);
+}
+
+/** pillar readers — every reader of this home, its cursor, and live leases. */
+async function cmdReaders(args) {
+  const home = homePath(args);
+  const { Mailbox } = await import("../src/mailbox/mailbox.mjs");
+  if (!existsSync(join(home, "mailbox.db"))) { console.log(`no mailbox at ${home} yet`); return; }
+  const mb = new Mailbox(join(home, "mailbox.db"));
+  try {
+    const tip = mb.inboxTipSeq();
+    const live = otherLiveLeases(mb);
+    const readers = mb.listReaders();
+    if (!readers.length) console.log("no readers recorded yet");
+    for (const r of readers) {
+      const behind = mb.inboxAfter(r.cursor, 100000).length;
+      const leases = live.filter((l) => l.reader === r.name);
+      console.log(JSON.stringify({
+        reader: r.name, named: !r.name.startsWith("ctx:"), cursor: r.cursor, unseen: behind,
+        last: describeProcess(r), live: leases.map(describeProcess),
+      }));
+    }
+    console.log(`inbox tip seq ${tip}; ${live.length} live lease(s)`);
+  } finally { mb.close(); }
+}
+
+/**
+ * pillar status [envelope-id] [--limit N] [--wait S]
+ *
+ * The outbox as the sender can prove it: whether a carrier accepted each
+ * envelope, and whether the RECIPIENT'S KEY signed an ack or a read receipt
+ * for it. A carrier receipt is not delivery; a signed ack is the recipient's
+ * mailbox saying it stored the envelope; neither says anyone acted on it.
+ */
+async function cmdStatus(args) {
+  const id = args._[1];
+  args["carrier-only"] = true;
+  const p = loadPillar(args);
+  await p.start();
+  try {
+    if (id && args.wait !== undefined) {
+      const row = p.mailbox.getOutbound(id);
+      if (!row) { console.error(`no envelope ${id} in this home's outbox`); exit(2); }
+      loadContacts(args, p);
+      const secs = args.wait === true ? 60 : Number(args.wait);
+      if (!Number.isFinite(secs) || secs <= 0) { console.error("--wait takes a number of seconds"); exit(2); }
+      await waitForAck(p, id, row.recipient, Date.now() + secs * 1000);
+    }
+    const rows = id ? [p.mailbox.getOutbound(id)].filter(Boolean) : p.mailbox.outboxRecent(Number(args.limit ?? 20));
+    if (id && !rows.length) { console.error(`no envelope ${id} in this home's outbox`); exit(2); }
+    for (const r of rows) {
+      console.log(JSON.stringify({
+        id: r.envelope_id, to: r.recipient, kind: r.kind ?? null, at: r.created_at,
+        ...(r.group_id ? { groupId: r.group_id, msgId: r.group_msg_id ?? null } : {}),
+        acceptedByCarrier: r.status === "delivered" ? (r.delivered_at ?? true) : null,
+        acknowledged: r.recipient_ack_at ?? null,
+        read: r.recipient_read_at ?? null,
+        status: describeOutboundStatus(r),
+      }));
+    }
+    if (id && args.wait !== undefined && !rows[0].recipient_ack_at) exit(4);
+  } finally {
+    await p.stop();
+  }
+}
+
+/** pillar receipts [on|off|delivered on|off|read on|off] — config.json `receipts`. */
+async function cmdReceipts(args) {
+  const home = homePath(args);
+  const cfgPath = join(home, "config.json");
+  if (!existsSync(join(home, "keychain.json"))) { console.error(`no pillar found at ${home}. run: pillar init`); exit(2); }
+  const cfg = readConfig(home);
+  const r = { delivered: !!cfg.receipts?.delivered, read: !!cfg.receipts?.read };
+  const [a, b] = args._.slice(1);
+  const onoff = (v) => (v === "on" ? true : v === "off" ? false : null);
+  if (a === undefined) {
+    // show only
+  } else if (onoff(a) !== null && b === undefined) {
+    r.delivered = r.read = onoff(a);
+  } else if ((a === "delivered" || a === "read") && onoff(b) !== null) {
+    r[a] = onoff(b);
+  } else {
+    console.error("usage: pillar receipts [on|off] | [delivered on|off] | [read on|off]");
+    exit(2);
+  }
+  if (a !== undefined) { cfg.receipts = r; writeFileSync(cfgPath, JSON.stringify(cfg, null, 2)); }
+  console.log(`delivery acks: ${r.delivered ? "on" : "off"}   read receipts: ${r.read ? "on" : "off"}   (${cfgPath})`);
+  console.log(`sent only to contacts (fleet.json, trust allow, members of groups you accepted); read receipts go out on --mark-read.`);
+  console.log(`read receipts are symmetric: with them off, incoming read receipts are ignored too. Delivery acks from others are always recorded.`);
+}
+
 async function cmdTrust(args) {
   // pillar trust                          show policy + lists + quarantine count
   // pillar trust set <open|directory|allowlist>
@@ -756,8 +1403,15 @@ async function main() {
     case "tier":  return cmdTier(args);
     case "peers": return cmdPeers(args);
     case "delegate": return cmdDelegate(args);
+    case "wait": return cmdWait(args);
+    case "readers": return cmdReaders(args);
+    case "status": return cmdStatus(args);
+    case "receipts": return cmdReceipts(args);
+    case "group":
+      if (wantsGroupV2(args)) return cmdGroupV2(args); // @rule P-cli-dispatch-v2
+      return cmdGroup(args);
     default:
-      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|trust|tier|peers|delegate> [--home DIR]`);
+      console.error(`usage: pillar <init|id|send|send-group|group|groups|recv|inbox|wait|readers|status|receipts|trust|tier|peers|delegate> [--home DIR]`);
       exit(2);
   }
 }