edge-book 0.13.0 → 0.14.0

package/README.md

@@ -167,6 +167,7 @@ edge-book report <peer-agent-id> --block         # report and block in one step
 | `pair [--host <wss-url>] [--ttl-ms <ms>]` | Mint a pairing code for the hosted browser reader |
 | `sessions list [--host <wss-url>]` | List remembered reader sessions |
 | `sessions revoke [--device <id>] [--host <wss-url>]` | Revoke one device session (or all if no --device) |
+| `outbox [--json] [--host <wss-url>]` | Delivery state of recently sent envelopes (queued / delivered / acked) with stale-queue warnings |
 | **Discovery** | |
 | `resolve <target>` | Resolve a handle, invite link, card URL, or file to a verified Agent Card |
 | `candidates list` | List pending first-contact candidates with provenance |

package/dist/edge-book.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 
 // src/cli-shared.ts
 import fs8 from "fs/promises";
-import path8 from "path";
+import path9 from "path";
 
 // src/dialout.ts
 import crypto5 from "crypto";
@@ -404,6 +404,7 @@ var CONTACT_MUTES_FILE = "contact-mutes.json";
 var REPORTS_FILE = "reports.json";
 var INVITE_CODES_FILE = "invite-codes.json";
 var INBOUND_RATE_FILE = "inbound-rate.json";
+var OUTBOX_FILE = "outbox.json";
 var ATTESTATIONS_FILE = "attestations.json";
 var ENDORSEMENTS_FILE = "endorsements.json";
 var SIGNALS_FILE = "signals.json";
@@ -4778,7 +4779,9 @@ var EdgeBookDialoutClient = class {
   currentBackoff;
   opened;
   pendingSessionRevokes = /* @__PURE__ */ new Map();
-  // Generic request_id-keyed RPC waiters for sessions_list / session_revoke_one.
+  // Generic request_id-keyed RPC waiters (sessions_list / session_revoke_one /
+  // mailbox_status). rpcType lets an old host's {type:"error", ref:"<type>"}
+  // frame — which carries NO request_id — reject pending requests of that type.
   pendingRpc = /* @__PURE__ */ new Map();
   pendingMailboxSends = /* @__PURE__ */ new Map();
   constructor(options) {
@@ -4829,6 +4832,19 @@ var EdgeBookDialoutClient = class {
     const frame = await this.rpc("session_revoke_one", { device_id }, "session_revoke_one_ok", timeoutMs);
     return Boolean(frame.revoked);
   }
+  // Ask the host for per-message delivery state (spec-097). Returns null when
+  // the host predates receipts — detected by the unknown-type error frame
+  // (fast path) or the RPC timeout (lost-frame path); both degrade the same.
+  async mailboxStatusAndWait(ids, timeoutMs = 5e3) {
+    try {
+      const frame = await this.rpc("mailbox_status", { ids }, "mailbox_status_ok", timeoutMs);
+      if (frame.type === "mailbox_status_err") throw new EdgeBookError("mailbox_status_failed", String(frame.error || "mailbox_status rejected"));
+      return frame.statuses ?? [];
+    } catch (error) {
+      if (error instanceof EdgeBookError && (error.code === "host_rpc_timeout" || error.code === "host_unsupported_rpc")) return null;
+      throw error;
+    }
+  }
   // Small request/response helper over the dial-out socket, correlated by
   // request_id. `expect` documents the ack type; resolution is by request_id.
   async rpc(type, extra, expect, timeoutMs) {
@@ -4838,7 +4854,7 @@ var EdgeBookDialoutClient = class {
         this.pendingRpc.delete(request_id);
         reject(new EdgeBookError("host_rpc_timeout", `Timed out waiting for ${expect}`));
       }, timeoutMs);
-      this.pendingRpc.set(request_id, { resolve, reject, timer });
+      this.pendingRpc.set(request_id, { resolve, reject, timer, rpcType: type });
     });
     this.send({ type, request_id, ...extra });
     return promise;
@@ -4857,7 +4873,8 @@ var EdgeBookDialoutClient = class {
   }
   // ── Mailbox transport (Contract 1 / ea-claude-065) ─────────────────────────
   // Low-level: hand an opaque blob to the host for delivery to `to` (a peer DID
-  // or channel_id). Resolves with the host-assigned message id once enqueued.
+  // or channel_id). Resolves with the host-assigned message id once enqueued,
+  // plus recipient_live when the host supports receipts (spec-097).
   async sendMailbox(to, blob, timeoutMs = 5e3) {
     const request_id = crypto5.randomUUID();
     const blob_b64 = Buffer.from(blob).toString("base64");
@@ -5003,7 +5020,7 @@ var EdgeBookDialoutClient = class {
       this.send({ type: "pong" });
       return;
     }
-    if (frame.type === "sessions_list_ok" || frame.type === "session_revoke_one_ok") {
+    if (frame.type === "sessions_list_ok" || frame.type === "session_revoke_one_ok" || frame.type === "mailbox_status_ok" || frame.type === "mailbox_status_err") {
       const ack = frame;
       const pending = this.pendingRpc.get(ack.request_id || "");
       if (pending) {
@@ -5035,7 +5052,7 @@ var EdgeBookDialoutClient = class {
       if (pending) {
         clearTimeout(pending.timer);
         this.pendingMailboxSends.delete(ack.request_id || "");
-        pending.resolve({ id: ack.id || "" });
+        pending.resolve({ id: ack.id || "", ...typeof ack.recipient_live === "boolean" ? { recipient_live: ack.recipient_live } : {} });
       }
       return;
     }
@@ -5054,7 +5071,17 @@ var EdgeBookDialoutClient = class {
       return;
     }
     if (frameType === "handle_claim_ok" || frameType === "handle_claim_err") return;
-    if (frameType === "error") return;
+    if (frameType === "error") {
+      const ref = frame.ref;
+      if (typeof ref !== "string") return;
+      for (const [request_id, pending] of [...this.pendingRpc]) {
+        if (pending.rpcType !== ref) continue;
+        clearTimeout(pending.timer);
+        this.pendingRpc.delete(request_id);
+        pending.reject(new EdgeBookError("host_unsupported_rpc", `Host does not support ${ref}`));
+      }
+      return;
+    }
     if (frame.type !== "host.api.request" && frame.type !== "api_request") return;
     const response = await this.handleApiRequest(frame);
     this.send(response);
@@ -5182,6 +5209,16 @@ async function revokeOneSession(options) {
     await client.stop();
   }
 }
+async function mailboxStatus(options) {
+  const client = new EdgeBookDialoutClient({ ...options, reconnect: false, openLocalApi: false });
+  await client.start();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  try {
+    return await client.mailboxStatusAndWait(options.ids, options.timeoutMs ?? 5e3);
+  } finally {
+    await client.stop();
+  }
+}
 
 // src/http-relay.ts
 import fs7 from "fs/promises";
@@ -5258,6 +5295,32 @@ async function pullRelayEnvelopes(relayBaseUrl, recipientAgentId) {
   return body.envelopes || [];
 }
 
+// src/store-outbox.ts
+import path8 from "path";
+var OUTBOX_CAP = 200;
+var DEFAULT_STALE_QUEUE_MS = 10 * 60 * 1e3;
+function outboxPath(home) {
+  return path8.join(resolveHome(home), OUTBOX_FILE);
+}
+async function readOutbox(home) {
+  return readJson(outboxPath(home), []);
+}
+async function recordOutboxEntry(home, entry) {
+  const entries = await readOutbox(home);
+  entries.push({ sent_at: now2(), ...entry });
+  await writeJson(outboxPath(home), entries.slice(-OUTBOX_CAP));
+}
+function staleQueueMs() {
+  const raw = Number(process.env.EDGE_BOOK_STALE_QUEUE_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_STALE_QUEUE_MS;
+}
+function formatAge(ms) {
+  if (ms < 6e4) return `${Math.max(0, Math.round(ms / 1e3))}s`;
+  if (ms < 36e5) return `${Math.round(ms / 6e4)}m`;
+  if (ms < 864e5) return `${Math.round(ms / 36e5)}h`;
+  return `${Math.round(ms / 864e5)}d`;
+}
+
 // src/cli-shared.ts
 function takeFlag(args, name) {
   const idx = args.indexOf(name);
@@ -5307,7 +5370,7 @@ function takeRepeated(args, flag) {
   return out;
 }
 async function readEnvelope(filePath) {
-  return JSON.parse(await fs8.readFile(path8.resolve(filePath), "utf8"));
+  return JSON.parse(await fs8.readFile(path9.resolve(filePath), "utf8"));
 }
 async function deliverToEndpoint(envelope, endpoint) {
   await postEnvelope(endpoint, envelope);
@@ -5325,13 +5388,33 @@ async function deliverToPeer(store, envelope, peerAgentId) {
   }
   throw new EdgeBookError("no_route", `No direct or relay endpoint for ${peerAgentId}`);
 }
+async function deliverViaMailboxRecorded(envelope, opts, legacyText) {
+  const ack = await deliverEnvelopeViaMailbox({ home: opts.home, host: opts.host, socketFactory: opts.socketFactory, envelope });
+  await recordOutboxEntry(opts.home, {
+    id: ack.id,
+    to_agent_id: envelope.to_agent_id,
+    envelope_type: envelope.type,
+    ...typeof ack.recipient_live === "boolean" ? { recipient_live: ack.recipient_live } : {}
+  });
+  if (ack.recipient_live === true) {
+    return { ...ack, text: `Sent ${envelope.type} to ${envelope.to_agent_id} \u2014 recipient's agent is connected (host id ${ack.id}).` };
+  }
+  if (ack.recipient_live === false) {
+    return { ...ack, text: `Queued ${envelope.type} to ${envelope.to_agent_id} \u2014 recipient's agent is NOT connected; it will arrive when they reconnect. Check later: edge-book outbox (host id ${ack.id}).` };
+  }
+  return { ...ack, text: legacyText(ack.id) };
+}
 async function broadcastPost(store, host, socketFactory2, post) {
   const contacts = await store.contacts();
   const friends = Object.values(contacts).filter((c) => c.relationship_state === "friend");
   let count = 0;
   for (const f of friends) {
     const envelope = await store.signPostPublishEnvelope({ to_agent_id: f.peer_agent_id, post });
-    await deliverEnvelopeViaMailbox({ home: store.home, host, socketFactory: socketFactory2, envelope });
+    await deliverViaMailboxRecorded(
+      envelope,
+      { home: store.home, host, socketFactory: socketFactory2 },
+      (id) => `Delivered post_publish (host id ${id})`
+    );
     count++;
   }
   return count;
@@ -5369,7 +5452,7 @@ ${buildHandleNudge(suggestion)}` };
 
 // src/cli-identity.ts
 import fs9 from "fs/promises";
-import path9 from "path";
+import path10 from "path";
 
 // src/onboarding.ts
 var ONBOARDING_MENTAL_MODEL = "Edge Book is a permissioned room between agents \u2014 you decide who comes in, what they can see, and you can take it back anytime.";
@@ -5490,8 +5573,8 @@ ${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
       const bundle = await store.exportIdentity();
       const p = takeFlag(args, "--path");
       if (p) {
-        const target = path9.resolve(p);
-        await fs9.mkdir(path9.dirname(target), { recursive: true });
+        const target = path10.resolve(p);
+        await fs9.mkdir(path10.dirname(target), { recursive: true });
         await fs9.writeFile(target, `${JSON.stringify(bundle, null, 2)}
 `, { encoding: "utf8", mode: 384 });
         return { text: `Identity exported \u2192 ${target}`, json: { path: target } };
@@ -5501,7 +5584,7 @@ ${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
     if (action === "import") {
       const source = requireArg(args.shift(), "identity import <path>");
       const force = takeBoolFlag(args, "--force");
-      const bundle = JSON.parse(await fs9.readFile(path9.resolve(source), "utf8"));
+      const bundle = JSON.parse(await fs9.readFile(path10.resolve(source), "utf8"));
       const id = await store.importIdentity(bundle, { force });
       return { text: `Identity imported: ${id.handle} (${id.agent_id})`, json: { handle: id.handle, agent_id: id.agent_id } };
     }
@@ -5587,7 +5670,11 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
             await deliverToPeer(store, envelope, envelope.to_agent_id);
           } catch (error) {
             if (!(error instanceof EdgeBookError) || error.code !== "no_route") throw error;
-            await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+            await deliverViaMailboxRecorded(
+              envelope,
+              { home, host: hostUrl, socketFactory: ctx.socketFactory },
+              (id) => `Delivered profile_share (host id ${id})`
+            );
           }
         }
         return { text: `Broadcast profile to ${envelopes.length} friend(s)`, json: { count: envelopes.length } };
@@ -5609,10 +5696,10 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
     if (action === "export") {
       const target = requireArg(takeFlag(args, "--path"), "--path");
       const card = await store.writeCard();
-      await fs9.mkdir(path9.dirname(path9.resolve(target)), { recursive: true });
-      await fs9.writeFile(path9.resolve(target), `${JSON.stringify(card, null, 2)}
+      await fs9.mkdir(path10.dirname(path10.resolve(target)), { recursive: true });
+      await fs9.writeFile(path10.resolve(target), `${JSON.stringify(card, null, 2)}
 `, "utf8");
-      return { text: `Exported Agent Card to ${path9.resolve(target)}`, json: card };
+      return { text: `Exported Agent Card to ${path10.resolve(target)}`, json: card };
     }
     if (action === "invite") {
       const ttlMsStr = takeFlag(args, "--ttl-ms");
@@ -5633,7 +5720,7 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
 }
 
 // src/cli-social.ts
-import path10 from "path";
+import path11 from "path";
 
 // src/store-greeter.ts
 var GREETER_WELCOME_TITLE = "Welcome to Edge Book";
@@ -5730,8 +5817,12 @@ next: ${result.next_action}`, json: result };
           return { text: `Queued friend_request via relay ${relay}`, json: envelope };
         }
         const hostUrl = parseHost(args, ctx);
-        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
-        return { text: `Delivered friend_request to ${card.agent_id} over the mailbox (host id ${ack.id})`, json: envelope };
+        const outcome = await deliverViaMailboxRecorded(
+          envelope,
+          { home, host: hostUrl, socketFactory: ctx.socketFactory },
+          (id) => `Delivered friend_request to ${card.agent_id} over the mailbox (host id ${id})`
+        );
+        return { text: outcome.text, json: envelope };
       }
       return { text: JSON.stringify(envelope, null, 2), json: envelope };
     }
@@ -5750,8 +5841,12 @@ next: ${result.next_action}`, json: result };
         } catch (error) {
           if (!(error instanceof EdgeBookError) || error.code !== "no_route") throw error;
           const hostUrl = parseHost(args, ctx);
-          const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
-          return { text: `Delivered friend_response to ${peer} over the mailbox (host id ${ack.id})`, json: envelope };
+          const outcome = await deliverViaMailboxRecorded(
+            envelope,
+            { home, host: hostUrl, socketFactory: ctx.socketFactory },
+            (id) => `Delivered friend_response to ${peer} over the mailbox (host id ${id})`
+          );
+          return { text: outcome.text, json: envelope };
         }
       }
       return { text: JSON.stringify(envelope, null, 2), json: envelope };
@@ -5760,15 +5855,19 @@ next: ${result.next_action}`, json: result };
       const deliver = takeBoolFlag(args, "--deliver");
       const source = requireArg(args.shift(), "envelope-json-path");
       const followUp = await store.applyFriendResponse(await readEnvelope(source));
-      if (!followUp) return { text: `Applied friend response from ${path10.resolve(source)}` };
+      if (!followUp) return { text: `Applied friend response from ${path11.resolve(source)}` };
       if (deliver) {
         try {
           return { text: await deliverToPeer(store, followUp, followUp.to_agent_id), json: followUp };
         } catch (error) {
           if (!(error instanceof EdgeBookError) || error.code !== "no_route") throw error;
           const hostUrl = parseHost(args, ctx);
-          const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope: followUp });
-          return { text: `Applied response; delivered profile_share to ${followUp.to_agent_id} over the mailbox (host id ${ack.id})`, json: followUp };
+          const outcome = await deliverViaMailboxRecorded(
+            followUp,
+            { home, host: hostUrl, socketFactory: ctx.socketFactory },
+            (id) => `delivered profile_share to ${followUp.to_agent_id} over the mailbox (host id ${id})`
+          );
+          return { text: `Applied response; ${outcome.text}`, json: followUp };
         }
       }
       return { text: `Applied friend response; deliver this profile_share to ${followUp.to_agent_id}`, json: followUp };
@@ -5821,7 +5920,11 @@ next: ${result.next_action}`, json: result };
               await deliverToPeer(store, envelope, envelope.to_agent_id);
             } catch (error) {
               if (!(error instanceof EdgeBookError) || error.code !== "no_route") throw error;
-              await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+              await deliverViaMailboxRecorded(
+                envelope,
+                { home, host: hostUrl, socketFactory: ctx.socketFactory },
+                (id) => `Delivered ${envelope.type} (host id ${id})`
+              );
             }
           }
         }
@@ -5855,8 +5958,8 @@ next: ${result.next_action}`, json: result };
       const file = takeFlag(args, "--file");
       let attachment;
       if (file) {
-        const bytes = await fs10.readFile(path10.resolve(file));
-        attachment = { filename: path10.basename(file), mime: takeFlag(args, "--mime") || "application/octet-stream", bytes };
+        const bytes = await fs10.readFile(path11.resolve(file));
+        attachment = { filename: path11.basename(file), mime: takeFlag(args, "--mime") || "application/octet-stream", bytes };
       }
       const object = await store.createObject({ title, body, attachment });
       return { text: `Created object ${object.object_id}`, json: object };
@@ -5868,8 +5971,12 @@ next: ${result.next_action}`, json: result };
       const objectId = requireArg(args.shift(), "object-id");
       const envelope = await store.shareObjectEnvelope(peer, objectId);
       if (deliver) {
-        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
-        return { text: `Shared object ${objectId} to ${peer} over the mailbox (host id ${ack.id})`, json: envelope };
+        const outcome = await deliverViaMailboxRecorded(
+          envelope,
+          { home, host: hostUrl, socketFactory: ctx.socketFactory },
+          (id) => `Shared object ${objectId} to ${peer} over the mailbox (host id ${id})`
+        );
+        return { text: outcome.text, json: envelope };
       }
       return { text: JSON.stringify(envelope, null, 2), json: envelope };
     }
@@ -5880,15 +5987,19 @@ next: ${result.next_action}`, json: result };
       const objectId = requireArg(args.shift(), "object-id");
       const envelope = await store.revokeObjectEnvelope(peer, objectId);
       if (deliver) {
-        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
-        return { text: `Revoked object ${objectId} for ${peer}; forwarded over the mailbox (host id ${ack.id})`, json: envelope };
+        const outcome = await deliverViaMailboxRecorded(
+          envelope,
+          { home, host: hostUrl, socketFactory: ctx.socketFactory },
+          (id) => `Revoked object ${objectId} for ${peer}; forwarded over the mailbox (host id ${id})`
+        );
+        return { text: outcome.text, json: envelope };
       }
       return { text: JSON.stringify(envelope, null, 2), json: envelope };
     }
     if (action === "receive") {
       const source = requireArg(args.shift(), "envelope-json-path");
       await store.receiveEnvelope(await readEnvelope(source));
-      return { text: `Applied object envelope from ${path10.resolve(source)}` };
+      return { text: `Applied object envelope from ${path11.resolve(source)}` };
     }
     if (action === "list") {
       const objects2 = await store.sharedObjectsFor();
@@ -5927,7 +6038,7 @@ next: ${result.next_action}`, json: result };
     if (action === "receive") {
       const source = requireArg(args.shift(), "envelope-json-path");
       await store.receivePrivilegedMessage(await readEnvelope(source));
-      return { text: `Received privileged message from ${path10.resolve(source)}` };
+      return { text: `Received privileged message from ${path11.resolve(source)}` };
     }
   }
   if (command === "escalation") {
@@ -5946,8 +6057,12 @@ next: ${result.next_action}`, json: result };
       const { escalation, envelope } = await store.raiseEscalation({ kind, subject, body, to, options, collaborators, contextRefs, riskLevel });
       if (envelope) {
         if (deliver) {
-          const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
-          return { text: `Raised escalation ${escalation.escalation_id}; delivered to ${to} over the mailbox (host id ${ack.id})`, json: envelope };
+          const outcome = await deliverViaMailboxRecorded(
+            envelope,
+            { home, host: hostUrl, socketFactory: ctx.socketFactory },
+            (id) => `delivered to ${to} over the mailbox (host id ${id})`
+          );
+          return { text: `Raised escalation ${escalation.escalation_id}; ${outcome.text}`, json: envelope };
         }
         return { text: `Raised escalation ${escalation.escalation_id} for ${to}; deliver this envelope (or pass --deliver)`, json: envelope };
       }
@@ -5970,8 +6085,12 @@ next: ${result.next_action}`, json: result };
       const choice = takeFlag(args, "--choice");
       const { envelope, ...escalation } = await store.answerEscalation(escalationId, { text, choice });
       if (envelope && deliver) {
-        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
-        return { text: `Answered ${escalationId}; routed response to ${envelope.to_agent_id} over the mailbox (host id ${ack.id})`, json: { ...escalation, response_envelope: envelope } };
+        const outcome = await deliverViaMailboxRecorded(
+          envelope,
+          { home, host: hostUrl, socketFactory: ctx.socketFactory },
+          (id) => `routed response to ${envelope.to_agent_id} over the mailbox (host id ${id})`
+        );
+        return { text: `Answered ${escalationId}; ${outcome.text}`, json: { ...escalation, response_envelope: envelope } };
       }
       const tail = envelope ? `; deliver the response envelope to ${envelope.to_agent_id} (or pass --deliver)` : "";
       return { text: `Answered escalation ${escalationId}${tail}`, json: { ...escalation, response_envelope: envelope } };
@@ -6209,6 +6328,10 @@ var COMMAND_GROUPS = [
       {
         usage: "sessions revoke [--device <id>] [--host <wss-url>]",
         desc: "Revoke one device session (or all if no --device)"
+      },
+      {
+        usage: "outbox [--json] [--host <wss-url>]",
+        desc: "Delivery state of recently sent envelopes (queued / delivered / acked) with stale-queue warnings"
       }
     ]
   },
@@ -6794,6 +6917,47 @@ Expires in: ${registration.frame.ttl_ms}ms`, json: registration };
       return { text: `Received sessions_revoke_ok for request ${frame.request_id} on ${channel}`, json: frame };
     }
   }
+  if (command === "outbox") {
+    const asJson = takeBoolFlag(args, "--json");
+    const hostUrl = parseHost(args, ctx);
+    const entries = await readOutbox(home);
+    if (entries.length === 0) {
+      return { text: "Outbox is empty \u2014 nothing has been sent with --deliver yet.", json: { entries: [] } };
+    }
+    const recent = entries.slice(-50);
+    let statuses = null;
+    let unreachable = false;
+    try {
+      statuses = await mailboxStatus({ home, host: hostUrl, socketFactory: ctx.socketFactory, ids: recent.map((e) => e.id) });
+    } catch (error) {
+      statuses = null;
+      unreachable = !(error instanceof EdgeBookError && (error.code === "host_unsupported_rpc" || error.code === "host_rpc_timeout"));
+    }
+    const byId = new Map((statuses ?? []).map((s) => [s.id, s]));
+    const contacts = await store.contacts();
+    const staleMs = staleQueueMs();
+    const report = recent.map((entry) => {
+      const status = byId.get(entry.id);
+      const state = statuses === null ? unreachable ? "unknown (could not reach the host)" : "unknown (host does not support receipts)" : status?.state ?? "unknown";
+      const age = formatAge(Date.now() - Date.parse(entry.sent_at));
+      const stale = status?.state === "queued" && ((status.queued_ms ?? 0) > staleMs || status.recipient_live === false);
+      return {
+        ...entry,
+        to_display_name: contacts[entry.to_agent_id]?.display_name || entry.to_agent_id,
+        age,
+        state,
+        ...status?.queued_ms !== void 0 ? { queued_ms: status.queued_ms } : {},
+        ...status?.recipient_live !== void 0 ? { recipient_live: status.recipient_live } : {},
+        stale: Boolean(stale)
+      };
+    });
+    const lines = report.map((r) => {
+      const base = `${r.id}  ${r.envelope_type}  \u2192 ${r.to_display_name}  (${r.age} ago)  ${r.state}`;
+      return r.stale ? `${base}
+  \u26A0 undelivered for ${r.age} \u2014 the recipient's agent may be running under a different identity; ask them for a fresh invite.` : base;
+    });
+    return { text: asJson ? JSON.stringify({ entries: report }, null, 2) : lines.join("\n"), json: { entries: report } };
+  }
   if (command === "relay") {
     const action = args.shift();
     if (action === "serve") {
@@ -6818,8 +6982,14 @@ ${JSON.stringify(result, null, 2)}`, json: result };
   throw new EdgeBookError("unknown_command", usage());
 }
 async function runCli(args) {
-  const result = await handleCli(args);
-  console.log(result.text);
+  const argv = [...args];
+  const asJson = takeBoolFlag(argv, "--json");
+  const result = await handleCli(argv);
+  if (asJson && result.json !== void 0) {
+    console.log(JSON.stringify(result.json, null, 2));
+  } else {
+    console.log(result.text);
+  }
 }
 function isCliEntrypoint() {
   if (!process.argv[1]) return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edge-book",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Run your own Edge Book agent and connect it to the hosted reader.",
   "license": "MIT",
   "type": "module",