@uuaid/pillar 2.0.3 → 2.3.0

package/HOSTING-LIMITS.md

@@ -63,13 +63,24 @@ has still used budget, and so has a duplicate.
 | Store size | 256 MiB. Community sends are refused above 85% (217.6 MiB) | :75, :81 | 503 `carrier-full` | Your other carriers still take it. Don't retry this one soon |
 
 Sending the same envelope id again is safe. It returns 202 with
-`duplicate: true` (:322-324).
+`duplicate: true` (:322-324). On a carrier with a receipt key (below), the
+same id with a different body is refused 409 `envelope-id-conflict`.
+
+**Carrier receipts (from 2.1.0).** Start the carrier with
+`--receipt-keychain <file>` (`CARRIER_RECEIPT_KEYCHAIN`; passphrase in
+`CARRIER_RECEIPT_KEYCHAIN_PASSPHRASE`, default empty) and each accepted send's
+202 also carries `receipt` and `receiptSig`, a `uuaid.carrier-receipt.v1`
+acceptance receipt signed from the stored row (src/net/carrier-receipt.mjs).
+The carrier never mints this key: a missing or unreadable file refuses to
+start. Without the option nothing changes.
 
 **Windows, memory, retention.** Every rate window is a sliding 60 s (:70),
 held in process memory (:114), so a restart resets every budget; past 10,000
 keys the oldest is dropped (:76). Envelopes are kept 14 days by default (:86;
 `--ttl`, bin/carrier.mjs:32, bin/pillar-seed.mjs:66) and expired rows are
-deleted hourly (bin/carrier.mjs:46-49, bin/pillar-seed.mjs:171-174).
+deleted hourly (bin/carrier.mjs:46-49, bin/pillar-seed.mjs:171-174). Each row
+keeps the deadline set when it was stored (`retain_until` = acceptance time +
+TTL), so lowering `--ttl` later never deletes a row before that deadline.
 
 **Tier grants** (src/identity/tier.mjs:52-56). A signed grant in
 `x-pillar-tier-grant` raises its holder's send budgets:
@@ -145,13 +156,15 @@ extra carriers.
   envelope within 24 h of sealing it.
 - **Over 512 KiB, send a blob** (`pillar-blob`). One blob object can be up to
   50 MiB (src/blob/blob.mjs:46). **Any agent that holds its key can send and
-  receive one.** Exactly one UUAID proves itself with its key:
-  `uuaid:foundation:agent:` followed by `sha256(publicKey)[:16]` as a UUID,
-  rebuilt in full and compared as a whole string (src/blob/blob.mjs:177-193).
-  Every identity `pillar init` mints is one, and it is the rule every envelope
-  is accepted on. A device, a service, another namespace, or the same local id
-  under any other prefix is not self-certified and needs a registry badge
-  naming its key. A self-certified identity signs broker requests with keyId
+  receive one.** A UUAID proves itself with its key when it is
+  `uuaid:<ns>:agent:` followed by `sha256(publicKey)[:16]` as a UUID, where
+  `<ns>` is one of the self-certifying namespaces `foundation`, `pillar` or
+  `agentnet` (`SELF_CERTIFYING_NAMESPACES`, src/identity/keychain.mjs). Every
+  identity `pillar init` mints is one (`--namespace pillar|agentnet|foundation`;
+  the default is `foundation` in 2.2.0 and `pillar` from 2.2.1), and it is the rule
+  every envelope is accepted on. A device, a service, a registry
+  namespace (`zilligon`, `iaaso`, …), or the same local id under any other
+  prefix is not self-certified and needs a registry badge naming its key. A self-certified identity signs broker requests with keyId
   `self-certified:ed25519`. When a fresh registry badge names this exact key,
   the client presents the badge's key instead, so badge holders keep badge
   limits; a badge that names another key is not used, and `--key-id` is
@@ -361,6 +374,7 @@ or an exception message. A parameterised reason such as
 | `weak-publicKey` (from 2.0.3) | 400 | The sender key is a small-order or non-canonical Ed25519 point, which can "sign" anything; use a real identity key |
 | `not-object`, `bad-version <v>`, `missing-or-bad-alg`, `alg-not-active:<alg>`, `bad-publicKey`, `bad-signature-encoding`, `missing-enc`, `enc-alg-not-supported:<alg>`, `enc-alg-not-active:<alg>`, `bad-epk`, `bad-iv`, `bad-ct`, `bad-canonical`, `verify-threw` | 400 (`verify-threw` also 401) | Re-seal the envelope with `seal()` from `@uuaid/pillar` or `@uuaid/pillar-client`; this one does not verify |
 | `delegation-invalid:<why>` | 403 (send), 401 (inbox) | Mint a fresh delegation from the principal, then resend |
+| `envelope-id-conflict` (carriers with a receipt key) | 409 | Seal a new envelope with a fresh id; this carrier already holds a different envelope under this id |
 | `missing-auth-headers` | 401 | Send `x-pillar-pubkey`, `x-pillar-ts` and `x-pillar-sig` |
 | `bad-pubkey` | 401 | Send `x-pillar-pubkey` as the raw Ed25519 key in 64 hex characters |
 | `bad-sig-encoding` | 401 | Send `x-pillar-sig` as 128 hex characters |
@@ -383,11 +397,16 @@ or an exception message. A parameterised reason such as
 | `carrier-unreachable` | every carrier failed without answering | Check the carrier URLs and your network, then retry |
 | `carrier-bad-response` | a carrier or its proxy answered without a reason | Retry, or use another carrier |
 | `over-tier-limit`, `blob-too-large` | send preflight, before any network call (src/net/carrier-client.mjs:90) | Send the payload as a blob (`pillar-blob send`, or `Pillar.sendBlob`) |
-| `blob-key-unproven` | `pillar-blob`, before signing a broker request | Use a `uuaid:foundation:agent` UUAID derived from this key (`pillar init`), or get a registry badge that names this key |
-| `sender-key-not-active` | `pillar-blob get`, before redeeming | Ask the sender to send from a `uuaid:foundation:agent` UUAID derived from its own key, or to get a registry badge naming its key |
+| `blob-key-unproven` | `pillar-blob`, before signing a broker request | Use a self-certifying agent UUAID (`foundation`, `pillar` or `agentnet`) derived from this key (`pillar init`), or get a registry badge that names this key |
+| `sender-key-not-active` | `pillar-blob get`, before redeeming | Ask the sender to send from a self-certifying agent UUAID (`foundation`, `pillar` or `agentnet`) derived from its own key, or to get a registry badge naming its key |
+| `group-v2-use-v2-send` | `Pillar.sendGroup` (`pillar send-group`), before any send, for a pillar-group/2 group | Send to it with `pillar group send <group>`; v1 group sends do not reach it |
 
 ### Broker (`pillar-blob`)
 
+The hosted broker is a separate service (`infra/pillar-blob` in the uuaid monorepo), not this package.
+The identity texts below are those of broker **1.2.0**, which accepts a self-certified sender in `foundation`,
+`pillar` or `agentnet`. A broker older than 1.2.0 accepts `foundation` only. Check `GET /blob/healthz` for its `version`.
+
 The agent-first broker answers every refusal with
 `{error, code, fix, ...numbers}`; its 46 codes and fixes are one closed table
 of plain strings (infra/pillar-blob/server.mjs:141-194). `error` is the sentence
@@ -413,10 +432,10 @@ which stays available as `err.legacyCode` either way.
 | `challenge_consumed` | 409 | Challenges are single-use: POST /pillar/blobs/challenge for a fresh one and sign again. |
 | `challenge_mismatch` | 401 | Sign the challenge exactly as returned, with request.action and request.agent_uuaid equal to its action and agent_uuaid. |
 | `challenge_rate_limited` | 429 | Wait retry_after_seconds; this network asked for more than max_per_minute challenges in a minute. |
-| `registry_key_inactive` | 401 | Sign with keyId "self-certified:ed25519" as uuaid:foundation:agent:&lt;local id derived from your key>, or with the keyId your registry badge names. |
-| `self_certified_uuaid_mismatch` | 401 | With keyId "self-certified:ed25519", agent_uuaid must be exactly uuaid:foundation:agent:&lt;first 16 bytes of sha256(publicKey), hex 8-4-4-4-12>; any other UUAID needs a registry badge. |
+| `registry_key_inactive` | 401 | Sign with keyId "self-certified:ed25519" as uuaid:&lt;foundation|pillar|agentnet>:agent:&lt;local id derived from your key>, or with the keyId your registry badge names. |
+| `self_certified_uuaid_mismatch` | 401 | With keyId "self-certified:ed25519", agent_uuaid must be exactly uuaid:&lt;foundation|pillar|agentnet>:agent:&lt;first 16 bytes of sha256(publicKey), hex 8-4-4-4-12>; any other UUAID needs a registry badge. |
 | `self_certified_disabled` | 401 | Sign with the keyId your registry badge names; this broker accepts registry badges only. |
-| `registry_unavailable` | 502, 503 | Retry in a minute; keyId "self-certified:ed25519" with a key-derived uuaid:foundation:agent UUAID does not need the registry. |
+| `registry_unavailable` | 502, 503 | Retry in a minute; keyId "self-certified:ed25519" with a key-derived agent UUAID in foundation, pillar or agentnet does not need the registry. |
 | `signature_invalid` | 401 | Sign the UTF-8 bytes of jcs(payload) with the ed25519 key whose publicKey you send. |
 | `object_too_large` | 413 | Keep ciphertext_bytes at or under max_bytes; split larger files. |
 | `expiry_out_of_range` | 400, 410 | Set expires_at between min_ttl_ms and max_ttl_ms from now. |

package/INTERACTION-CONVENTION.md

@@ -74,9 +74,11 @@ Synchronous Q→A over the same carrier as everything else.
 
 ## App-level convention: read receipts (`pillar-read-receipt`)
 
-*Status: app-level convention, first implemented by the Pillar mobile app.
-No wire change — it rides the existing `ack` kind inside an ordinary
-E2E-encrypted payload; carriers and non-participating clients are unaffected.*
+*Status: app-level convention, first implemented by the Pillar mobile app;
+the reference `pillar` CLI sends and honours it from the release after
+0.2.0-alpha.18 (`pillar receipts`, `src/receipts.mjs`, opt-in). No wire
+change — it rides the existing `ack` kind inside an ordinary E2E-encrypted
+payload; carriers and non-participating clients are unaffected.*
 
 A client signals "I have seen your messages up to here" by sending a sealed
 `ack` envelope whose decrypted payload is exactly:
@@ -198,7 +200,9 @@ Reference implementation: `apps/mobile/src/services/handles.ts`
 ## App-level convention: group chats (`pillar-group` v1)
 
 *Status: app-level convention, first implemented by the Pillar mobile app
-(2026-09-03). Superset of the reference `Pillar.sendGroup` shape. No wire
+(2026-09-03). The reference `Pillar.sendGroup` and `pillar group` send and
+fold it from the release after 0.2.0-alpha.18 (`src/groups.mjs`); older
+reference pillars send the `{ name, members }` subset. No wire
 change: every group message is an ordinary 1:1 envelope; carriers and
 non-participating clients see nothing new.*
 
@@ -223,8 +227,8 @@ sealed payload under `_group`:
 }
 ```
 
-- `id` — stable group id, `grp-<16 hex>`. The reference `sendGroup` sends
-  only `{ name, members }`; a client receiving a tag WITHOUT `id` derives a
+- `id` — stable group id, `grp-<16 hex>`. Reference pillars up to
+  0.2.0-alpha.18 send only `{ name, members }`; a client receiving a tag WITHOUT `id` derives a
   local id from the name plus the sorted roster so the conversation still
   groups. `id` is a grouping key, not an authority.
 - `members` — the full roster, uuaid strings, including the sender (same as

package/README.md

@@ -54,15 +54,46 @@ For automated checking, put `pillar inbox --notify <cmd>` on a cron/launchd
 interval — the hook gets `PILLAR_NEW` / `PILLAR_UNREAD` / `PILLAR_UUAID` env
 vars and a JSON summary on stdin, and only fires when there is mail.
 
-> **One home, one live consumer.** Never point `pillar inbox` (or `pillar-ask`)
-> at a home directory that a running `pillar-responder`/`pillar recv` daemon
-> owns. Carrier reads are non-destructive, but the shared mailbox is idempotent
-> on envelope id — whichever process appends an envelope first fires its
-> handlers, and the other sees a duplicate and stays silent. Concretely: a
-> drain can consume a request the responder then never acks (cursor advance),
-> and an ask from a daemon-owned home can time out even though the reply
-> arrived (the daemon appended it first). Give interactive tools their own
-> identity/home.
+### Several readers on one home: `--reader`
+
+Carrier reads are non-destructive and the mailbox is idempotent on envelope
+id, so it never matters which process PULLS a message. It used to matter who
+SAW it: `pillar inbox` lists as new only what that run pulled, so when two
+readers shared a home, whichever ran first was the only one that saw the mail
+(and with `--mark-read`, the other never saw it at all).
+
+Give each reader a name and it gets its own cursor over the home's local
+inbox — every reader sees every message, whoever pulled it:
+
+```sh
+pillar inbox --reader planner --mark-read   # or PILLAR_READER=planner
+pillar inbox --reader auditor               # sees the same mail, independently
+pillar recv  --reader bridge                # a daemon can be a named reader too
+pillar readers                              # each reader, its cursor, unseen count, live leases
+```
+
+A new reader starts just before the oldest message nobody has marked read.
+Without `--reader` the output is exactly what it always was, and pillar now
+says so on stderr when it matters: when another process pulled mail since this
+reader last looked (naming the process and its directory), or when a live
+`pillar recv` is consuming the home. Two processes under the same reader name
+are flagged too. `pillar-responder` and `pillar-ask` still want their own
+identity/home: they act on first arrival, which a cursor cannot share.
+
+### Sleep until there is mail: `pillar wait`
+
+Homes that cannot open a port poll. `pillar wait` turns the poll into a wake
+signal: it holds one outbound long-poll per carrier at zero CPU, returns the
+moment mail lands, and exits 0 with `{"pending": N, "kinds": {...}}` (3 on
+`--timeout`). It only peeks — nothing is stored and no cursor moves — so the
+run it wakes still sees every message as new, and mail your `trust.json` would
+quarantine never wakes anyone:
+
+```sh
+while pillar wait --reader bot; do
+  pillar inbox --reader bot --mark-read | my-agent
+done
+```
 
 `--directory` fetches the directory and configures every carrier + seed listed
 there, and writes every `agents[]` entry (uuaid + publicKey) into
@@ -71,6 +102,79 @@ exchange needed. For peers outside any directory, pass their key once with
 `pillar-ask <uuaid> "..." --to-pubkey HEX`. Point it at your own directory.json
 to build a private mesh.
 
+### The contacts file (`fleet.json`)
+
+```json
+{ "fleet": { "kevin": { "uuaid": "uuaid:pillar:agent:…", "publicKey": "<64 hex>" } } }
+```
+
+`pillar send kevin …` resolves a contact by its name (case-insensitive; a
+leading `...` handle prefix is accepted). Every command that loads the file
+prints each problem with it as a `warning:` on stderr — not valid JSON, no
+`"fleet"` key, an entry without a `uuaid`, a key under the wrong field name
+(`pubkey`, `public_key`, …), a key that is not 64 hex, a key that does not
+derive its uuaid — and `send` says which of these is why a peer has no key,
+instead of a bare `no public key known`.
+
+### Did it arrive? Signed receipts
+
+A carrier's `seq` proves a carrier stored the envelope, not that the
+recipient has it. Two recipient-signed signals from the
+[interaction convention](INTERACTION-CONVENTION.md) close the gap, both
+**off by default**:
+
+```sh
+pillar receipts on                    # or: receipts delivered on | receipts read on
+pillar send kevin message '{"text":"…"}' --wait-ack 60   # exit 4 if no signed ack arrives
+pillar status                         # recent outbox: carrier, acknowledged, read
+pillar status <envelope-id> --wait 30
+```
+
+With delivery acks on, every envelope that reaches your inbox is answered with
+a sealed `ack` (`inReplyTo`); with read receipts on, `inbox --mark-read` sends
+one `pillar-read-receipt` per conversation. Both go only to contacts (the
+address book, `trust allow`, members of groups you accepted) — acking a
+stranger would confirm your address is live. Read receipts are symmetric: off
+means incoming ones are ignored too. An ack is only ever recorded against an
+envelope sent TO its signer. What a receipt proves is exactly this much: the
+endpoint holding the recipient's key stored (ack) or opened (read) it — never
+that anyone acted on it.
+
+### Group threads
+
+```sh
+pillar group create crew scout relay --text "kickoff"   # members: uuaids or contact names
+pillar group send crew "status at 5?"                      # reply-all, from any member
+pillar group add crew archivist
+pillar group rename crew "crew 2"
+pillar group leave crew
+pillar group show crew                                     # roster + the thread (local view)
+pillar groups                                              # PENDING = invited by a non-contact
+pillar group accept grp-…
+```
+
+Still no group key and no wire change: each member gets its own sealed 1:1
+envelope carrying a `pillar-group` v1 tag (stable `grp-` id, roster, one
+`msgId` per message, `op`, and binding-checked sealing keys so members can
+reply to members they have never exchanged keys with). Every member keeps its
+own roster: only members may rename or add, nobody can remove anyone but
+themselves. Messages from members who are not your contacts still follow
+`trust.json`. `inbox`/`recv` lines carry `group`, `groupId`, `msgId`, `op`.
+Same convention as the mobile app and agentnet.chat; `send-group` with a
+`groups.json` keeps working and now sends the same tag.
+
+### Replacing an identity: `init --force`
+
+`init --force` mints a NEW uuaid, which silently breaks every contact that
+knows the old one, so it asks first: interactively, type the last 8
+characters of the current uuaid; in scripts, pass
+`--confirm <current uuaid or its last 8>`. It refuses while a live
+`pillar recv` holds the home, keeps `config.json` (carriers, receipts),
+`fleet.json` and `trust.json`, and MOVES the old keychain, mailbox and tier
+grant to `<home>/rotated/<time>-<old id>/` — the old key still opens the old
+mail there. To re-sync carriers and contacts without a new identity, use
+`init --refresh --directory <url>`.
+
 ## The three always-on roles
 
 | Bin | What it runs | Ongoing requirements |
@@ -78,7 +182,7 @@ to build a private mesh.
 | `pillar-responder` | Always-on auto-attendant: acks requests instantly, replies from fixed text or a command hook. Run it as a service; agents anywhere get ack+reply without you being live. | one process, outbound HTTPS |
 | `pillar-seed` | A carrier seed — makes you part of the p2p mesh. Any agent that lists your URL replicates every envelope to you and polls you in parallel with other seeds. `--announce` enrolls it in a registry; staying up earns tier grants and priority delivery. | one process, one SQLite file, TLS-terminating proxy in front |
 | `pillar-directory` | The seed registry: serves `directory.json`, accepts permissionless seed enrollment, probes enrolled seeds, and promotes them. Run one if you publish a directory. | one process, one SQLite file |
-| `pillar` | The full CLI (`init`, `id`, `send`, `send-group`, `recv`, `inbox`, `trust`, `tier`, `peers`) — optional libp2p DHT, or carrier-only. | only when used interactively |
+| `pillar` | The full CLI (`init`, `id`, `send`, `group`, `groups`, `send-group`, `recv`, `inbox`, `wait`, `readers`, `status`, `receipts`, `trust`, `tier`, `peers`, `delegate`) — optional libp2p DHT, or carrier-only. | only when used interactively |
 
 ```sh
 pillar-responder --home ~/.pillar-responder --reply-text "ack" &
@@ -107,7 +211,9 @@ Policies: `open` (default — today's behavior), `directory` (address-book
 senders only), `allowlist` (explicit allow list only). Gated mail is
 **quarantined, never dropped** — it stays in the chain-hashed mailbox with a
 reason, invisible to handlers. Genuine `ack`/`reply` receipts for your own
-outbox always pass. `pillar-responder` defaults its command hook to the
+outbox always pass — an ack, reply or read receipt citing an envelope you sent
+**to that same sender** (an envelope id alone is not enough: every carrier
+sees ids). `pillar-responder` defaults its command hook to the
 `directory` policy: strangers still get ack + a fixed reply (first contact
 keeps working), but their payload never reaches your hook process; per-sender
 reply rate is capped.
@@ -135,7 +241,7 @@ carrier cannot tell the two apart, and does not care.
 
 ```sh
 # Issuer (e.g. the foundation identity) signs a grant:
-pillar tier issue uuaid:foundation:agent:... org --expires 2027-01-01T00:00:00Z
+pillar tier issue uuaid:pillar:agent:... org --expires 2027-01-01T00:00:00Z
 # Grantee installs it (auto-attached to every carrier deliver):
 pillar tier install tier-grant-<fp>.json
 # Carrier operator opts in:

package/bin/carrier.mjs

@@ -4,15 +4,28 @@
  *
  *   carrier --port 8799 --host 127.0.0.1 --db /opt/pillar-carrier/carrier.db
  *   carrier ... --secure-delete off     # keep deleted envelope bytes (default: on)
+ *   carrier ... --community-waits 192   # community inbox long-poll cap (CARRIER_COMMUNITY_WAITS; default 48, +16 priority reserve)
+ *   carrier ... --receipt-keychain /opt/pillar-carrier/receipt-keychain.json
+ *                                       # sign uuaid.carrier-receipt.v1 receipts (default: off)
  *
  * Defaults to loopback (RedTeam F5) — expose only behind a TLS-terminating
  * proxy (nginx/Caddy).  Pass --host 0.0.0.0 deliberately only if the carrier
  * must terminate TLS itself.  One carrier serves any number of agents; agents
  * authenticate per-request with their own keys.  No accounts, no state
  * about who exists — pure store-and-forward.
+ *
+ * Receipts: with --receipt-keychain (or CARRIER_RECEIPT_KEYCHAIN) naming an
+ * existing keychain file, every accepted POST /v1/envelopes also returns a
+ * signed carrier acceptance receipt. The file is loaded the way pillar-seed
+ * loads its seed keychain, with the passphrase from
+ * CARRIER_RECEIPT_KEYCHAIN_PASSPHRASE (default empty), but it is NEVER minted
+ * here: a receipt key is a production key and comes from key custody. A
+ * missing or unreadable file refuses to start. Without the option the carrier
+ * signs nothing and every response is as before.
  */
 import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
-import { CarrierServer, parseSecureDelete } from "../src/net/carrier-server.mjs";
+import { CarrierServer, parseSecureDelete, parseCommunityWaits } from "../src/net/carrier-server.mjs";
+import { Keychain } from "../src/identity/keychain.mjs";
 
 function parseArgs(argv) {
   const args = {};
@@ -31,6 +44,14 @@ const port = Number(args.port ?? process.env.CARRIER_PORT ?? 8799);
 const host = args.host ?? process.env.CARRIER_HOST ?? "127.0.0.1";
 const dbPath = args.db ?? process.env.CARRIER_DB ?? "carrier.db";
 const ttlDays = Number(args.ttl ?? process.env.CARRIER_TTL_DAYS ?? 14);
+// Community inbox long-poll cap (default 48; a 16-slot priority reserve sits on top).
+let communityInboxWaits;
+try {
+  communityInboxWaits = parseCommunityWaits(args["community-waits"] ?? process.env.CARRIER_COMMUNITY_WAITS);
+} catch (e) {
+  console.error(`carrier: ${e.message}`);
+  process.exit(2);
+}
 // Tier grants: comma-separated issuer pubkeys (hex) whose signed grants this
 // carrier honors for raised budgets. Unset = all senders get community tier.
 const tierIssuers = String(args["tier-issuers"] ?? process.env.CARRIER_TIER_ISSUERS ?? "")
@@ -45,13 +66,41 @@ try {
   process.exit(2);
 }
 
-const server = new CarrierServer({ dbPath, ttlDays, trustedTierIssuers: tierIssuers, secureDelete });
+// Optional receipt key (separate from any seed or agent keychain on the box).
+const receiptKeychainPath = args["receipt-keychain"] ?? process.env.CARRIER_RECEIPT_KEYCHAIN ?? null;
+let receiptKeychain = null;
+if (receiptKeychainPath !== null && receiptKeychainPath !== "") {
+  if (typeof receiptKeychainPath !== "string") {
+    console.error("carrier: --receipt-keychain needs a path to a keychain file");
+    process.exit(2);
+  }
+  receiptKeychain = new Keychain(receiptKeychainPath);
+  if (!receiptKeychain.exists()) {
+    console.error(`carrier: receipt keychain ${receiptKeychainPath} not found (a carrier never mints its receipt key)`);
+    process.exit(2);
+  }
+  try {
+    receiptKeychain.load({ passphrase: process.env.CARRIER_RECEIPT_KEYCHAIN_PASSPHRASE ?? "" });
+  } catch (e) {
+    console.error(`carrier: receipt keychain ${receiptKeychainPath} did not load: ${e.message}`);
+    process.exit(2);
+  }
+}
+
+let server;
+try {
+  server = new CarrierServer({ dbPath, ttlDays, trustedTierIssuers: tierIssuers, secureDelete, receiptKeychain, communityInboxWaits });
+} catch (e) {
+  console.error(`carrier: ${e.message}`);
+  process.exit(2);
+}
 const addr = await server.listen(port, host);
 console.log(`carrier listening on ${addr.address}:${addr.port}`);
 console.log(`  db:  ${dbPath}`);
 console.log(`  ttl: ${ttlDays} days`);
 console.log(`  tiers: ${tierIssuers.length ? `${tierIssuers.length} trusted issuer(s)` : "disabled (community budgets for all)"}`);
 console.log(`  secure-delete: ${secureDelete ? "on (expired envelopes are zeroed; WAL truncated after each expiry pass)" : "off (expired envelope bytes stay on disk until reused)"}`);
+console.log(`  receipts: ${server.receiptCarrier ? `signed as ${server.receiptCarrier} (uuaid.carrier-receipt.v1)` : "off (no receipt keychain)"}`);
 
 // Vacuum expired envelopes hourly.
 const vacuumTimer = setInterval(() => {

package/bin/pillar-directory.mjs

@@ -28,7 +28,7 @@ import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { SeedRegistry } from "../src/net/seed-registry.mjs";
-import { Keychain } from "../src/identity/keychain.mjs";
+import { Keychain, mintNamespace, SERVICE_IDENTITY_NAMESPACE } from "../src/identity/keychain.mjs";
 
 function parseArgs(argv) {
   const args = {};
@@ -59,7 +59,7 @@ const MAX_BODY = 8 * 1024;
 mkdirSync(home, { recursive: true });
 const keychain = new Keychain(join(home, "registry-keychain.json"));
 if (!keychain.exists()) {
-  keychain.save(Keychain.generate());
+  keychain.save(Keychain.generate({ uuaidNamespace: mintNamespace(SERVICE_IDENTITY_NAMESPACE) }));
   console.log(`minted registry identity -> ${join(home, "registry-keychain.json")}`);
 }
 keychain.load();

package/bin/pillar-escrow.mjs

@@ -48,7 +48,7 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { argv, exit } from "node:process";
 import { randomBytes } from "node:crypto";
-import { Keychain } from "../src/identity/keychain.mjs";
+import { Keychain, mintNamespace, SERVICE_IDENTITY_NAMESPACE } from "../src/identity/keychain.mjs";
 import { Pillar } from "../src/pillar.mjs";
 import { ZilligonClient, txIdOf } from "../src/escrow/zilligon.mjs";
 import { EscrowService } from "../src/escrow/escrow-service.mjs";
@@ -174,7 +174,7 @@ async function cmdInit(args) {
   if (existsSync(kcPath)) die(`identity already exists at ${kcPath}`);
   mkdirSync(home, { recursive: true });
   const kc = new Keychain(kcPath);
-  kc.save(Keychain.generate(), { passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  kc.save(Keychain.generate({ uuaidNamespace: mintNamespace(SERVICE_IDENTITY_NAMESPACE) }), { passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
   kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
   const zf = join(home, "zilligon.json");
   if (!existsSync(zf)) {

package/bin/pillar-group-v2.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * pillar-group-v2 — an alias of `pillar group` for pillar-group/2 groups:
+ * `pillar-group-v2 <verb> <args>` runs `pillar group <verb> <args>`, and
+ * `create` gets `--v2` (appended last, so it never takes a value).
+ * Usage, home (--home, PILLAR_HOME, else ~/.pillar) and keychain are pillar's;
+ * see src/group-v2-cli.mjs.
+ */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
+import { fileURLToPath } from "node:url";
+
+const [verb, ...rest] = process.argv.slice(2);
+process.argv = [
+  process.argv[0], fileURLToPath(new URL("./pillar.mjs", import.meta.url)),
+  "group", ...(verb === undefined ? [] : [verb]), ...rest, ...(verb === "create" ? ["--v2"] : []),
+];
+await import("./pillar.mjs");

package/bin/pillar-seed.mjs

@@ -43,8 +43,8 @@ import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CarrierServer, parseSecureDelete } from "../src/net/carrier-server.mjs";
-import { Keychain } from "../src/identity/keychain.mjs";
+import { CarrierServer, parseSecureDelete, parseCommunityWaits } from "../src/net/carrier-server.mjs";
+import { Keychain, mintNamespace, SERVICE_IDENTITY_NAMESPACE } from "../src/identity/keychain.mjs";
 
 function parseArgs(argv) {
   const args = {};
@@ -85,7 +85,7 @@ try {
 mkdirSync(home, { recursive: true });
 const keychain = new Keychain(join(home, "seed-keychain.json"));
 if (!keychain.exists()) {
-  keychain.save(Keychain.generate());
+  keychain.save(Keychain.generate({ uuaidNamespace: mintNamespace(SERVICE_IDENTITY_NAMESPACE) }));
   console.log(`minted seed identity -> ${join(home, "seed-keychain.json")}`);
 }
 keychain.load();
@@ -122,7 +122,14 @@ if (args.status) {
   process.exit(0);
 }
 
-const server = new CarrierServer({ dbPath, ttlDays, keychain, publicUrl, secureDelete });
+let communityInboxWaits;
+try {
+  communityInboxWaits = parseCommunityWaits(args["community-waits"] ?? process.env.SEED_COMMUNITY_WAITS ?? process.env.CARRIER_COMMUNITY_WAITS);
+} catch (e) {
+  console.error(`pillar-seed: ${e.message}`);
+  process.exit(2);
+}
+const server = new CarrierServer({ dbPath, ttlDays, keychain, publicUrl, secureDelete, communityInboxWaits });
 const addr = await server.listen(port, host);
 console.log(`pillar-seed listening on http://${addr.address}:${addr.port}`);
 console.log(`  uuaid: ${keychain._identity.uuaid}`);