@uuaid/pillar 0.2.0-alpha.6

package/bin/pillar-responder.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * pillar-responder — always-on auto-attendant for the Pillar Interaction
+ * Convention.  Runs as a standalone process (with its own identity/home, so
+ * it never races a live agent daemon on the same mailbox) and answers
+ * kind=request envelopes IMMEDIATELY — no waiting for a live agent turn:
+ *
+ *   request → journal → ack (inReplyTo = request id) → reply (thread + inReplyTo + text)
+ *
+ * Reply text comes from, in order:
+ *   1. --reply-text / config responder.replyText  (static text)
+ *   2. --command / config responder.command       (spawn hook: JSON request on
+ *      stdin, stdout = reply text, non-zero exit or timeout → status:"error"
+ *      with the stderr tail as reason) — LLM-agnostic, any program works
+ *   3. builtin default text
+ *
+ * Optional --forward-to <uuaid> --forward-pubkey <hex> re-sends the request
+ * payload as kind=message to an owner identity so a live agent picks it up.
+ *
+ * At-least-once delivery: every request is journaled to
+ * <home>/responder-journal.jsonl BEFORE the ack; on startup, journaled
+ * requests without a done record from the last 24h get ack+reply re-sent
+ * (default text — the hook is not re-run, so a restart never double-executes
+ * a side-effecting command).  Duplicate acks/replies are harmless: the
+ * convention is idempotent by envelope id.
+ *
+ * Carrier-only by default (outbound HTTPS only — runs on any machine or
+ * webserver; no inbound ports, no libp2p).  Pass --libp2p to also listen.
+ *
+ *   pillar-responder --home ~/.pillar-fleet/zz-master-responder \
+ *     --reply-text "zz-master is away — left a message" \
+ *     --forward-to uuaid:foundation:agent:… --forward-pubkey <hex>
+ */
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { argv, exit } from "node:process";
+import { spawn } from "node:child_process";
+import { Keychain } from "../src/identity/keychain.mjs";
+import { Pillar } from "../src/pillar.mjs";
+
+const DEFAULT_REPLY = "pillar-responder: request acked — owner will respond through the normal channel";
+const MAX_REPLY_BYTES = 8192;
+const HOOK_TIMEOUT_MS = 60_000;
+const REPLAY_WINDOW_MS = 24 * 3600_000;
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, ...rest] = a.slice(2).split("=");
+      args[k] = rest.length ? rest.join("=") : (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true);
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function homePath(args) {
+  return args.home || process.env.PILLAR_HOME || join(homedir(), ".pillar");
+}
+
+// --- journal (at-least-once) -------------------------------------------------
+
+function journalPath(home) {
+  return join(home, "responder-journal.jsonl");
+}
+
+function journalRequest(home, env) {
+  appendFileSync(journalPath(home), JSON.stringify({
+    ts: new Date().toISOString(),
+    event: "request",
+    id: env.id,
+    sender: env.sender,
+    senderPublicKey: env.transportSignature.publicKey,
+    payload: env.payload,
+  }) + "\n");
+}
+
+function journalDone(home, id, reply) {
+  appendFileSync(journalPath(home), JSON.stringify({
+    ts: new Date().toISOString(),
+    event: "done",
+    id,
+    replyText: reply.text,
+    replyStatus: reply.status,
+  }) + "\n");
+}
+
+// Requests journaled but never completed, within the replay window.
+function loadPending(home) {
+  const p = journalPath(home);
+  if (!existsSync(p)) return [];
+  const done = new Set();
+  const requests = new Map();
+  for (const line of readFileSync(p, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e.event === "done") done.add(e.id);
+      else if (e.event === "request") requests.set(e.id, e);
+    } catch (_e) { /* skip torn line */ }
+  }
+  const cutoff = Date.now() - REPLAY_WINDOW_MS;
+  return [...requests.values()].filter((r) => !done.has(r.id) && Date.parse(r.ts) > cutoff);
+}
+
+// --- command hook -------------------------------------------------------------
+
+function runHook(cmd, req, { timeoutMs, maxBytes }) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, { shell: true, stdio: ["pipe", "pipe", "pipe"] });
+    let out = Buffer.alloc(0);
+    let err = Buffer.alloc(0);
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.stdout.on("data", (d) => { out = Buffer.concat([out, d]); });
+    child.stderr.on("data", (d) => { err = Buffer.concat([err, d]); });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolve({ ok: false, reason: `hook spawn failed: ${e.message}` });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        const text = out.toString("utf-8").trim();
+        resolve({ ok: true, text: text ? text.slice(0, maxBytes) : null });
+      } else if (code === null) {
+        resolve({ ok: false, reason: "hook timed out" });
+      } else {
+        resolve({ ok: false, reason: (err.toString("utf-8").trim() || `hook exited ${code}`).slice(0, 300) });
+      }
+    });
+    child.stdin.write(JSON.stringify(req));
+    child.stdin.end();
+  });
+}
+
+// --- main ----------------------------------------------------------------------
+
+const args = parseArgs(process.argv.slice(2));
+const home = homePath(args);
+const kcPath = join(home, "keychain.json");
+const cfgPath = join(home, "config.json");
+
+if (!existsSync(kcPath)) {
+  console.error(`no pillar identity at ${home}. run: pillar init --home ${home}`);
+  exit(2);
+}
+const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, "utf-8")) : {};
+const rcfg = cfg.responder ?? {};
+
+const carriers = args.carrier
+  ? [args.carrier]
+  : (process.env.PILLAR_CARRIERS ? process.env.PILLAR_CARRIERS.split(",") : (cfg.carriers ?? []));
+const enableLibp2p = args["libp2p"] === true;
+if (!carriers.length && !enableLibp2p) {
+  console.error("responder needs at least one carrier (--carrier URL or carriers[] in config.json) or --libp2p");
+  exit(2);
+}
+
+const replyText = args["reply-text"] ?? rcfg.replyText ?? DEFAULT_REPLY;
+const hookCmd = args.command ?? rcfg.command ?? null;
+const hookTimeoutMs = Number(args["timeout-ms"] ?? rcfg.timeoutMs ?? HOOK_TIMEOUT_MS);
+const hookMaxBytes = Number(args["max-reply-bytes"] ?? MAX_REPLY_BYTES);
+const fwd = args["forward-to"] || rcfg.forwardTo?.uuaid
+  ? { uuaid: args["forward-to"] ?? rcfg.forwardTo?.uuaid, publicKey: args["forward-pubkey"] ?? rcfg.forwardTo?.publicKey }
+  : null;
+if (fwd && (!fwd.uuaid || !fwd.publicKey)) {
+  console.error("--forward-to needs both a UUAID and --forward-pubkey (encryption is mandatory)");
+  exit(2);
+}
+
+const kc = new Keychain(kcPath);
+kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+const p = new Pillar({
+  keychain: kc,
+  mailboxPath: join(home, "mailbox.db"),
+  listenAddrs: cfg.listenAddrs ?? ["/ip4/127.0.0.1/tcp/0"],
+  bootstrapPeers: cfg.bootstrapPeers ?? [],
+  enableRelay: cfg.enableRelay ?? false,
+  dhtClientMode: cfg.dhtClientMode ?? true,
+  carriers,
+  enableLibp2p,
+});
+
+await p.start();
+
+console.log(`pillar-responder up — ${p.uuaid}`);
+console.log(`  pubkey:    ${p.publicKeyHex}`);
+console.log(`  carriers:  ${carriers.length ? carriers.join(", ") : "(none — libp2p only)"}`);
+console.log(`  reply:     ${hookCmd ? `hook ${hookCmd}` : "builtin text"}`);
+if (fwd) console.log(`  forwardTo: ${fwd.uuaid}`);
+
+// Replay journaled-but-unfinished requests first (at-least-once).
+for (const r of loadPending(home)) {
+  try {
+    await p.send({ recipient: r.sender, recipientPublicKey: r.senderPublicKey, kind: "ack", payload: { inReplyTo: r.id } });
+    const replyPayload = { thread: r.payload?.thread ?? r.id, inReplyTo: r.id, status: "ok", text: replyText };
+    await p.send({ recipient: r.sender, recipientPublicKey: r.senderPublicKey, kind: "reply", payload: replyPayload });
+    journalDone(home, r.id, replyPayload);
+    console.log(`  replay: ack+reply re-sent for ${r.id.slice(0, 16)}…`);
+  } catch (e) {
+    console.error(`  replay failed for ${r.id.slice(0, 16)}…: ${e.message}`);
+  }
+}
+
+// Register the handler BEFORE polling starts so fast deliveries are caught.
+p.onEnvelope(async (env) => {
+  if (env.kind !== "request") return; // ack/reply/message stay passive (owner daemon handles them)
+  const senderKey = env.transportSignature.publicKey; // open() F1: sender derives from this key
+  try {
+    journalRequest(home, env);
+    const thread = env.payload?.thread ?? env.id;
+    let status = "ok";
+    let text = replyText;
+    if (hookCmd) {
+      const r = await runHook(hookCmd, {
+        id: env.id,
+        sender: env.sender,
+        senderPublicKey: senderKey,
+        payload: env.payload,
+        thread,
+      }, { timeoutMs: hookTimeoutMs, maxBytes: hookMaxBytes });
+      if (r.ok) {
+        if (r.text) text = r.text;
+      } else {
+        status = "error";
+        text = r.reason;
+      }
+    }
+    await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
+    const replyPayload = { thread, inReplyTo: env.id, status, text };
+    await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: replyPayload });
+    journalDone(home, env.id, replyPayload);
+    console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → ack + reply (${status})`);
+    if (fwd) {
+      await p.send({
+        recipient: fwd.uuaid,
+        recipientPublicKey: fwd.publicKey,
+        kind: "message",
+        payload: { ...env.payload, _forwarded: { from: env.sender, requestId: env.id, thread } },
+      });
+    }
+  } catch (e) {
+    console.error(`  request ${env.id.slice(0, 16)}… failed: ${e.message} (journaled — replayed on restart)`);
+  }
+});
+
+// p.start() does NOT poll on its own — the pillar-ask trap.  waitS=20 keeps us
+// inside the carrier's MAX_WAIT_S=30 long-poll cap + the 30s ack window.
+if (p.carrierClient) p.startCarrierPolling({ waitS: 20 });
+console.log("  polling started — Ctrl-C to stop");
+
+const shutdown = async () => {
+  if (p.carrierClient) p.stopCarrierPolling();
+  process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/bin/pillar-seed.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * pillar-seed — run a pillar seed: a carrier server that makes you part of
+ * the p2p store-and-forward mesh, like a LimeWire/BitTorrent seed peer.
+ *
+ *   pillar-seed --port 8799 --db /opt/pillar-seed/seed.db
+ *
+ * A seed IS a carrier server with a public URL — nothing else.  Agents
+ * anywhere list your URL in their carriers[] and then:
+ *   - deliver() replicates every envelope to you (so messages survive any
+ *     single seed dying — the BitTorrent property), and
+ *   - poll you for their inbox in parallel with every other seed.
+ * Minimal ongoing requirements: one process, one SQLite file, outbound-free
+ * (all traffic comes TO you).  That is the whole contract.
+ *
+ * Defaults to loopback (RedTeam F5).  To become a real seed, put it behind a
+ * TLS-terminating proxy (nginx/Caddy) and advertise the PUBLIC https:// URL —
+ * never the loopback one — as a seeds[] entry in a pillar directory.json:
+ *
+ *   { "url": "https://<your-host>", "operator": "<you>", "region": "<region>", "since": "<ISO date>" }
+ *
+ * Anyone running `pillar init --directory <directory-url>` then picks you up
+ * automatically as one of their carriers.  You can also be someone's ENTIRE
+ * carrier set (`--carriers https://<your-host>`) — two agents can talk with
+ * only your seed between them, no official carrier involved.
+ */
+import { CarrierServer } from "../src/net/carrier-server.mjs";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      args[k] = (argv[i + 1] && !argv[i + 1].startsWith("--")) ? argv[++i] : true;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const port = Number(args.port ?? process.env.SEED_PORT ?? 8799);
+const host = args.host ?? process.env.SEED_HOST ?? "127.0.0.1";
+const dbPath = args.db ?? process.env.SEED_DB ?? "pillar-seed.db";
+const ttlDays = Number(args.ttl ?? process.env.SEED_TTL_DAYS ?? 14);
+
+const server = new CarrierServer({ dbPath, ttlDays });
+const addr = await server.listen(port, host);
+console.log(`pillar-seed listening on http://${addr.address}:${addr.port}`);
+console.log(`  db:  ${dbPath}`);
+console.log(`  ttl: ${ttlDays} days`);
+
+// Boot self-check on the address we actually serve — verify before claim.
+try {
+  const probeHost = addr.address === "0.0.0.0" || addr.address === "::" ? "127.0.0.1" : addr.address;
+  const res = await fetch(`http://${probeHost}:${addr.port}/v1/health`);
+  if (res.ok) console.log(`  health: ok (${res.status})`);
+  else console.log(`  health: WARN ${res.status}`);
+} catch (e) {
+  console.log(`  health: unreachable — ${e.message}`);
+}
+
+if (host === "127.0.0.1") {
+  console.log(`\n  loopback seed — reachable only from this machine.`);
+  console.log(`  To join the mesh as a real seed: TLS-terminate a public URL and list it:`);
+  console.log(`    { "url": "https://<your-host>", "operator": "<you>", "region": "<region>", "since": "${new Date().toISOString().slice(0, 10)}" }`);
+  console.log(`  in the seeds[] array of your pillar directory.json.`);
+}
+
+// Vacuum expired envelopes hourly.
+const vacuumTimer = setInterval(() => {
+  const n = server.vacuum();
+  if (n > 0) console.log(`vacuumed ${n} expired envelopes`);
+}, 3600_000);
+
+const shutdown = async () => {
+  clearInterval(vacuumTimer);
+  await server.close();
+  process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/bin/pillar.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+/**
+ * pillar — one-command CLI.
+ *
+ *   pillar init  [--home ~/.pillar]              first-time setup: mint UUAID + keys
+ *   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 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.).
+ */
+import { mkdirSync, existsSync, readFileSync, writeFileSync } 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 { Pillar } from "../src/pillar.mjs";
+import { loadFleetAddressBook } from "../src/address-book.mjs";
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, ...rest] = a.slice(2).split("=");
+      args[k] = rest.length ? rest.join("=") : (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true);
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function homePath(args) {
+  return args.home || process.env.PILLAR_HOME || join(homedir(), ".pillar");
+}
+
+// Address book default: <home>/fleet.json unless --fleet points elsewhere.
+function fleetPath(args) {
+  return args.fleet || join(homePath(args), "fleet.json");
+}
+
+function loadPillar(args) {
+  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 kc = new Keychain(kcPath);
+  kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  const carriers = args.carrier
+    ? [args.carrier]
+    : (process.env.PILLAR_CARRIERS ? process.env.PILLAR_CARRIERS.split(",") : (cfg.carriers ?? []));
+  return new Pillar({
+    keychain: kc,
+    mailboxPath: mbPath,
+    listenAddrs: cfg.listenAddrs ?? ["/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/tcp/0/ws"],
+    bootstrapPeers: cfg.bootstrapPeers ?? [],
+    enableRelay: cfg.enableRelay ?? false,
+    dhtClientMode: cfg.dhtClientMode ?? true,
+    carriers,
+    enableLibp2p: !(args["carrier-only"] || cfg.carrierOnly === true),
+  });
+}
+
+function loadGroups(args) {
+  // groups.json lives next to fleet.json by default:
+  // { "groups": { "<name>": { "members": ["uuaid:...", ...] } } }
+  const p = args.groups || (args.fleet ? join(dirname(args.fleet), "groups.json") : null);
+  if (!p || !existsSync(p)) return { path: p, groups: {} };
+  return { path: p, groups: JSON.parse(readFileSync(p, "utf-8")).groups ?? {} };
+}
+
+function writeRuntimeFile(pillar, home) {
+  if (!pillar.node) return;
+  const rt = {
+    uuaid: pillar.uuaid,
+    peerId: pillar.node.peerId.toString(),
+    addrs: pillar.node.getMultiaddrs().map(a => a.toString()),
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+  };
+  writeFileSync(join(home, "runtime.json"), JSON.stringify(rt, null, 2));
+}
+
+async function cmdInit(args) {
+  const home = homePath(args);
+  mkdirSync(home, { recursive: true });
+  const kcPath = join(home, "keychain.json");
+  if (existsSync(kcPath) && !args.force) {
+    console.error(`keychain already exists at ${kcPath}. use --force to overwrite.`);
+    exit(1);
+  }
+  const kc = new Keychain(kcPath);
+  const id = Keychain.generate();
+  kc.save(id, { passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  const cfg = {
+    listenAddrs: ["/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/tcp/0/ws"],
+    bootstrapPeers: [],
+    enableRelay: false,
+    dhtClientMode: true,
+  };
+  // P2P seed discovery: --directory fetches a pillar directory.json and wires
+  // the primary carrier plus every seeds[] entry as carriers (the LimeWire
+  // seed model — poll all, replicate to all); --carriers sets them directly.
+  if (typeof args.directory === "string") {
+    const res = await fetch(args.directory);
+    if (!res.ok) {
+      console.error(`init: directory fetch failed: ${args.directory} -> ${res.status}`);
+      exit(1);
+    }
+    const d = await res.json();
+    const list = [d.carrier, ...(Array.isArray(d.seeds) ? d.seeds.map(s => s.url) : [])].filter(Boolean);
+    if (!list.length) {
+      console.error(`init: directory ${args.directory} lists no carrier and no seeds`);
+      exit(1);
+    }
+    cfg.carriers = list;
+    console.log(`carriers from directory (${args.directory}): ${list.join(", ")}`);
+    // Seed the address book from the directory's agents[] so a fresh agent can
+    // `pillar ask`/`pillar send` with zero key plumbing (keys required for E2E).
+    // Merge — never clobber a hand-curated fleet.json.
+    if (Array.isArray(d.agents)) {
+      const fleetPath = join(home, "fleet.json");
+      const prev = existsSync(fleetPath) ? JSON.parse(readFileSync(fleetPath, "utf-8")).fleet ?? {} : {};
+      const fleet = { ...prev };
+      let added = 0;
+      for (const a of d.agents) {
+        if (!a.uuaid || !a.publicKey) continue;
+        const key = typeof a.role === "string" && a.role ? a.role : a.uuaid;
+        fleet[key] = {
+          uuaid: a.uuaid,
+          publicKey: a.publicKey,
+          ...(prev[key]?.addrs ? { addrs: prev[key].addrs } : {}),
+          ...(prev[key]?.peerId ? { peerId: prev[key].peerId } : {}),
+        };
+        if (!prev[key]) added++;
+      }
+      writeFileSync(fleetPath, JSON.stringify({ fleet }, null, 2));
+      console.log(`address book: ${Object.keys(fleet).length} peers in ${fleetPath} (${added} new from directory)`);
+    }
+  } else if (args.carriers) {
+    cfg.carriers = args.carriers.split(",").map(s => s.trim()).filter(Boolean);
+  }
+  writeFileSync(join(home, "config.json"), JSON.stringify(cfg, null, 2));
+  console.log(`initialized pillar at ${home}`);
+  console.log(`uuaid: ${id.uuaid}`);
+  console.log(`publicKey: ${id.publicKeyHex}`);
+  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.`);
+}
+
+async function cmdId(args) {
+  const p = loadPillar(args);
+  await p.start();
+  console.log(`uuaid:     ${p.uuaid}`);
+  console.log(`publicKey: ${p.publicKeyHex}`);
+  if (p.node) {
+    console.log(`peerId:    ${p.node.peerId.toString()}`);
+    console.log(`addrs:`);
+    for (const a of p.node.getMultiaddrs()) console.log(`  ${a.toString()}`);
+  } else {
+    console.log(`mode:      carrier-only (no libp2p)`);
+  }
+  if (p.carriers?.length) console.log(`carriers:  ${p.carriers.join(", ")}`);
+  await p.stop();
+}
+
+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]");
+    exit(2);
+  }
+  const payload = jsonStr ? JSON.parse(jsonStr) : {};
+  const p = loadPillar(args);
+  await p.start();
+  const n = loadFleetAddressBook(fleetPath(args), p);
+  if (n > 0) console.log(`address book: ${n} peers`);
+  try {
+    const { envelope, delivery } = await p.send({
+      recipient, kind, payload,
+      recipientPublicKey: args["to-pubkey"],  // explicit key for peers outside fleet.json
+      resolveTimeoutMs: 5000,
+    });
+    console.log(`sent envelope ${envelope.id}`);
+    console.log(`  to:   ${recipient}`);
+    console.log(`  kind: ${kind}`);
+    if (delivery?.peerId) console.log(`  via peerId: ${delivery.peerId}`);
+  } finally {
+    await p.stop();
+  }
+}
+
+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]");
+    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);
+  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}  ${r.error}`); }
+    }
+    console.log(`group "${groupName}": ${results.length - failed}/${results.length} delivered`);
+    if (failed) exit(1);
+  } finally {
+    await p.stop();
+  }
+}
+
+async function cmdGroups(args) {
+  const { path: gPath, groups } = loadGroups(args);
+  const names = Object.keys(groups);
+  if (!names.length) { console.log(`no groups defined (${gPath ?? "no groups file"})`); return; }
+  for (const n of names) {
+    console.log(`${n} (${groups[n].members.length} members):`);
+    for (const m of groups[n].members) console.log(`  ${m}`);
+  }
+}
+
+async function cmdRecv(args) {
+  const p = loadPillar(args);
+  await p.start();
+  writeRuntimeFile(p, homePath(args)); // warm handoff: publish live addr for senders
+  const n = loadFleetAddressBook(fleetPath(args), p);
+  console.log(`listening as ${p.uuaid}`);
+  if (p.node) {
+    console.log(`peerId ${p.node.peerId.toString()}`);
+    for (const a of p.node.getMultiaddrs()) console.log(`  ${a.toString()}`);
+  } else {
+    console.log(`(carrier-only mode: no libp2p listener)`);
+  }
+  if (p.carrierClient) {
+    p.startCarrierPolling();
+    console.log(`polling carriers: ${p.carriers.join(", ")}`);
+  }
+  if (n > 0) console.log(`address book: ${n} peers from ${fleetPath(args)}`);
+
+  let bridge = null;
+  if (args["zestro-bridge"] || process.env.PILLAR_ZESTRO_URL) {
+    const { ZestroBridge } = await import("../src/bridges/zestro.mjs");
+    bridge = new ZestroBridge({
+      url:       process.env.PILLAR_ZESTRO_URL   ?? args["zestro-url"],
+      token:     process.env.PILLAR_ZESTRO_TOKEN ?? args["zestro-token"],
+      sessionId: process.env.PILLAR_ZESTRO_AGENT ?? args["zestro-agent"],
+    });
+    await bridge.connect();
+    // Never log the full URL — it embeds the auth token.
+    console.log(`zestro bridge connected to ${bridge.url.replace(/\/[0-9a-f-]{36}\/ws$/, "/<token>/ws")}`);
+  }
+
+  p.onEnvelope(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;
+    console.log(JSON.stringify(line));
+    if (bridge) {
+      try {
+        const result = await bridge.sendCommand({ command: JSON.stringify({ kind: env.kind, payload: env.payload, sender: env.sender }) });
+        console.log(`  → zestro result: ${JSON.stringify(result).slice(0, 200)}`);
+      } catch (e) {
+        // command_result only arrives when the target agent's TURN completes —
+        // a busy agent (long turn) exceeds any sane timeout while the command
+        // is already queued in its tab. Timeout = accepted-unconfirmed, not failure.
+        if (/timed out/.test(e.message)) {
+          console.log(`  → zestro: queued (command_result pending — agent busy)`);
+        } else {
+          console.error(`  → zestro bridge error: ${e.message}`);
+        }
+      }
+    }
+  });
+
+  const shutdown = async () => { if (bridge) bridge.close(); await p.stop(); exit(0); };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  await new Promise(() => {});
+}
+
+async function cmdPeers(args) {
+  const p = loadPillar(args);
+  await p.start();
+  const peers = p.node.getPeers();
+  console.log(`${peers.length} connected peers:`);
+  for (const peer of peers) console.log(`  ${peer.toString()}`);
+  await p.stop();
+}
+
+async function main() {
+  const args = parseArgs(argv.slice(2));
+  const cmd = args._[0];
+  switch (cmd) {
+    case "init":  return cmdInit(args);
+    case "id":    return cmdId(args);
+    case "send":  return cmdSend(args);
+    case "send-group": return cmdSendGroup(args);
+    case "groups": return cmdGroups(args);
+    case "recv":  return cmdRecv(args);
+    case "peers": return cmdPeers(args);
+    default:
+      console.error(`usage: pillar <init|id|send|send-group|groups|recv|peers> [--home DIR]`);
+      exit(2);
+  }
+}
+
+main().catch(e => { console.error(e); exit(1); });