@heyanon-arp/cli 0.0.4 → 0.0.5

package/dist/cli.js

@@ -333,6 +333,31 @@ var init_api = __esm({
       async rotateIdentityKey(did, body, signer) {
         return this.signedRequest("POST", `/v1/agents/${encodeURIComponent(did)}/rotate-identity-key`, body, signer);
       }
+      // ─── Webhook config + secret ────────────────────────────────────
+      //
+      // All routes are `/me/...` — the server derives the agent from
+      // the signer DID, so the CLI never sends a `:did` path parameter.
+      // The signedRequest helper signs the canonical request (method +
+      // path + query + body) with the agent's identity key; that's the
+      // auth contract the SignedRequestGuard checks server-side.
+      async getMyWebhookConfig(signer) {
+        return this.signedRequest("GET", "/v1/agents/me/webhook-config", null, signer);
+      }
+      async setMyWebhookConfig(body, signer) {
+        return this.signedRequest("POST", "/v1/agents/me/webhook-config", body, signer);
+      }
+      async getMyWebhookSecretStatus(signer) {
+        return this.signedRequest("GET", "/v1/agents/me/webhook-secret", null, signer);
+      }
+      async initMyWebhookSecret(signer) {
+        return this.signedRequest("POST", "/v1/agents/me/webhook-secret/init", {}, signer);
+      }
+      async rotateStageMyWebhookSecret(signer) {
+        return this.signedRequest("POST", "/v1/agents/me/webhook-secret/rotate-stage", {}, signer);
+      }
+      async rotateCommitMyWebhookSecret(body, signer) {
+        return this.signedRequest("POST", "/v1/agents/me/webhook-secret/rotate-commit", body, signer);
+      }
       /**
        * Ingest a signed envelope. Endpoint is public (no
        * `X-ARP-Signer-DID` headers) — authentication is the envelope's
@@ -710,7 +735,7 @@ var import_simple_update_notifier = __toESM(require("simple-update-notifier"));
 // package.json
 var package_default = {
   name: "@heyanon-arp/cli",
-  version: "0.0.4",
+  version: "0.0.5",
   description: "Command-line client for the Agent Relationship Protocol \u2014 register agents, sign envelopes, run escrowed work cycles on Solana.",
   license: "MIT",
   keywords: ["arp", "agent-relationship-protocol", "did", "solana", "escrow", "ed25519", "agents", "a2a", "cli"],
@@ -720,7 +745,7 @@ var package_default = {
   publishConfig: {
     access: "public"
   },
-  files: ["dist", "LICENSE", "README.md"],
+  files: ["dist", "examples", "LICENSE", "README.md"],
   engines: {
     node: ">=22"
   },
@@ -753,9 +778,6 @@ var package_default = {
   }
 };
 
-// src/cli.ts
-init_api();
-
 // src/commands/agents.ts
 var import_chalk2 = __toESM(require("chalk"));
 init_api();
@@ -777,15 +799,39 @@ function formatGenericError(err, verbose = false) {
   return `${import_chalk.default.red("Error")} ${message}
 ${import_chalk.default.gray(err.stack)}`;
 }
-function formatActionError(err, command) {
-  let cmd = command;
-  while (cmd.parent) cmd = cmd.parent;
-  const verbose = !!cmd.opts().trace;
+function toCliErrorJson(err, includeStack = false) {
+  const { ApiError: ApiError2 } = (init_api(), __toCommonJS(api_exports));
+  if (err instanceof ApiError2) {
+    const { code, message: message2, details } = err.payload;
+    const out2 = { code, message: message2 };
+    if (details !== void 0) out2.details = details;
+    return out2;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const out = { code: "CLI_ERROR", message };
+  if (includeStack && err instanceof Error && err.stack) {
+    out.details = { stack: err.stack };
+  }
+  return out;
+}
+function emitError(err, opts) {
+  if (opts.json) {
+    console.error(JSON.stringify(toCliErrorJson(err, opts.verbose)));
+    return;
+  }
   const { ApiError: ApiError2 } = (init_api(), __toCommonJS(api_exports));
   if (err instanceof ApiError2) {
-    return formatApiError(err.payload, verbose);
+    console.error(formatApiError(err.payload, opts.verbose));
+  } else {
+    console.error(formatGenericError(err, opts.verbose));
   }
-  return formatGenericError(err, verbose);
+}
+function emitActionError(err, command) {
+  let root = command;
+  while (root.parent) root = root.parent;
+  const verbose = !!root.opts().trace;
+  const json = !!command.opts().json;
+  emitError(err, { json, verbose });
 }
 function formatJson(value) {
   return JSON.stringify(value, null, 2);
@@ -825,7 +871,18 @@ function supportsUnicodeFrame() {
   return probe2.includes("UTF-8") || probe2.includes("UTF8");
 }
 function printJsonArray(rows) {
-  console.log(JSON.stringify(rows, null, 2));
+  jsonOut(rows);
+}
+function jsonOut(value) {
+  console.log(formatJson(value));
+}
+function progress(jsonMode, ...args) {
+  if (jsonMode) return;
+  console.log(...args);
+}
+function warn(jsonMode, ...args) {
+  if (jsonMode) return;
+  console.error(...args);
 }
 function formatAgentsTable(rows) {
   if (rows.length === 0) return import_chalk.default.dim("(no agents registered locally)");
@@ -864,11 +921,7 @@ function registerAgentsCommand(root) {
 async function runAgents(opts) {
   const limit = parseLimit(opts.limit);
   const api = new ArpApiClient(opts.server);
-  if (opts.json) {
-    console.error(import_chalk2.default.dim(`Server: ${api.serverUrl}`));
-  } else {
-    console.log(import_chalk2.default.dim(`Server: ${api.serverUrl}`));
-  }
+  progress(opts.json, import_chalk2.default.dim(`Server: ${api.serverUrl}`));
   const query = { limit };
   if (opts.tag && opts.tag.length > 0) query.tag = opts.tag.map((t) => t.trim().toLowerCase());
   if (opts.query) query.q = opts.query;
@@ -1099,18 +1152,42 @@ function writeStateFile(state) {
     (0, import_node_fs2.mkdirSync)(dir, { recursive: true, mode: 448 });
   }
   const body = JSON.stringify(state, null, 2);
-  (0, import_node_fs2.writeFileSync)(path, body, { encoding: "utf8", mode: 384 });
+  const tmpPath = `${path}.tmp.${process.pid}`;
+  const fd = (0, import_node_fs2.openSync)(tmpPath, "w", 384);
+  try {
+    (0, import_node_fs2.writeSync)(fd, body, 0, "utf8");
+    (0, import_node_fs2.fsyncSync)(fd);
+  } finally {
+    (0, import_node_fs2.closeSync)(fd);
+  }
+  let chmodOk = true;
+  try {
+    (0, import_node_fs2.chmodSync)(tmpPath, 384);
+  } catch {
+    chmodOk = false;
+  }
+  try {
+    (0, import_node_fs2.renameSync)(tmpPath, path);
+  } catch (err) {
+    try {
+      (0, import_node_fs2.unlinkSync)(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
   try {
     (0, import_node_fs2.chmodSync)(path, 384);
   } catch {
+    chmodOk = false;
   }
+  return { chmodOk };
 }
 function saveAgent(serverOverride, agent) {
   const key = resolveServerUrl(serverOverride);
   const state = readStateFile();
   if (!state.servers[key]) state.servers[key] = { agents: {} };
   state.servers[key].agents[agent.did] = agent;
-  writeStateFile(state);
+  return writeStateFile(state);
 }
 function loadAgent(serverOverride, did) {
   const key = resolveServerUrl(serverOverride);
@@ -1133,7 +1210,7 @@ function updateAgentLocal(serverOverride, did, patch) {
     throw new Error(`Cannot update local state \u2014 no record for ${did} on ${key}.`);
   }
   server.agents[did] = { ...server.agents[did], ...patch };
-  writeStateFile(state);
+  return writeStateFile(state);
 }
 function resolveSenderAgent(cmdName, serverOverride, explicitFromDid) {
   const resolvedServerUrl = resolveServerUrl(serverOverride);
@@ -1546,7 +1623,7 @@ function parseWaitInterval(raw) {
   return n;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function composeStatus(api, signerDid, relationshipId, signer) {
   const [relationshipsOrNull, contractsOrError] = await Promise.all([
@@ -1996,7 +2073,7 @@ function registerDerivePdas(cmd) {
         console.log(`EventAuthPDA:     ${out.event_authority_pda}`);
       }
     } catch (err) {
-      console.error(err.message);
+      emitError(err, { json: opts.json, verbose: process.argv.includes("--trace") });
       process.exit(1);
     }
   });
@@ -2058,7 +2135,7 @@ function registerVerifyRelease(cmd) {
         process.exitCode = 1;
       }
     } catch (err) {
-      console.error(err.message);
+      emitError(err, { json: opts.json, verbose: process.argv.includes("--trace") });
       process.exit(1);
     }
   });
@@ -2099,7 +2176,7 @@ async function verifyReleaseHandler(opts) {
   if (shouldRetrySigCheck) {
     const retryDelaysMs = [3e3, 3e3];
     for (const delay of retryDelaysMs) {
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await new Promise((resolve2) => setTimeout(resolve2, delay));
       const retriedSigs = await conn.getSignaturesForAddress(lockPda, { limit: 5 });
       if (retriedSigs.length > 0) {
         lockSeenInSignatures = true;
@@ -2239,7 +2316,7 @@ function registerCreateLock(cmd) {
       const out = await createLockHandler(opts);
       console.log(JSON.stringify(out, null, 2));
     } catch (err) {
-      console.error(err.message);
+      emitError(err, { json: opts.json, verbose: process.argv.includes("--trace") });
       process.exit(1);
     }
   });
@@ -2454,7 +2531,7 @@ function registerSignSettlement(cmd) {
       const out = await signSettlementHandler(opts);
       console.log(JSON.stringify(out, null, 2));
     } catch (err) {
-      console.error(err.message);
+      emitError(err, { json: opts.json, verbose: process.argv.includes("--trace") });
       process.exit(1);
     }
   });
@@ -2834,7 +2911,11 @@ Reference this delegation on subsequent calls with:`));
   }
 }
 function registerAccept(parent) {
-  parent.command("accept").description("Accept a PROPOSED delegation \u2014 promotes to ACCEPTED. Counterparty-only.").argument("<relationship-id>", "Relationship UUID").argument("<delegation-id>", "Delegation UUID").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--contract-id <uuid>", "Override the auto-resolved contract id (default: read from the delegation row)").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).option(
+  parent.command("accept").description("Accept a PROPOSED delegation \u2014 promotes to ACCEPTED. Counterparty-only.").argument("<relationship-id>", "Relationship UUID").argument("<delegation-id>", "Delegation UUID").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--contract-id <uuid>", "Override the auto-resolved contract id (default: read from the delegation row)").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"accept", delegationId, contractId, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude + pending-lock poll chatter move off stdout; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
+    false
+  ).option(
     "--no-wait-for-lock",
     "Opt-out of the pending-lock pre-flight poll. Default is ON: when the resolved delegation is in `pending_lock_finalization`, the CLI polls until the on-chain lock is confirmed before signing the envelope (avoids the racy DELEGATION_PENDING_LOCK 409 that consumes sender_sequence)."
   ).option("--lock-wait-timeout <seconds>", "Max wall-clock seconds to wait for pending-lock pre-flight (default 300).", "300").option("--lock-wait-interval <seconds>", "Poll cadence for pending-lock pre-flight in seconds. Bound to [1, 60].", "3").action(async (relationshipId, delegationId, opts) => {
@@ -2864,6 +2945,11 @@ function registerCancel(parent) {
 }
 async function runFollowupAction(relationshipId, delegationId, action, opts) {
   const cmdName = `delegation ${action}`;
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      `${cmdName}: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds dumps that would break \`--json | jq\`.`
+    );
+  }
   relationshipId = requireUuidNormalised(cmdName, relationshipId, "<relationship-id>");
   delegationId = requireUuidNormalised(cmdName, delegationId, "<delegation-id>");
   const ttlSeconds = parseTtl(cmdName, opts.ttl);
@@ -2885,7 +2971,11 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
       delegationId,
       action,
       timeoutSec: lockWaitTimeoutSec,
-      intervalSec: lockWaitIntervalSec
+      intervalSec: lockWaitIntervalSec,
+      // Route poll chatter through `progress` so it's suppressed
+      // in --json mode (keeps stdout pure + stderr reserved for
+      // the structured error object).
+      log: (line) => progress(opts.json, line)
     });
   }
   const content = {
@@ -2898,10 +2988,10 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
     if (declinePayload.reasonDetail) content.reason_detail = declinePayload.reasonDetail;
   }
   const body = { type: "delegation", content };
-  console.log(import_chalk6.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk6.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk6.default.dim(`Relationship: ${relationshipId}`));
-  console.log(import_chalk6.default.dim(`Delegation: ${delegationId} (action=${action}${action === "decline" ? `, reason=${content.reason}` : ""})`));
+  progress(opts.json, import_chalk6.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk6.default.dim(`Sender: ${sender.did}`));
+  progress(opts.json, import_chalk6.default.dim(`Relationship: ${relationshipId}`));
+  progress(opts.json, import_chalk6.default.dim(`Delegation: ${delegationId} (action=${action}${action === "decline" ? `, reason=${content.reason}` : ""})`));
   const result = await sendDelegationEnvelope({
     api,
     sender,
@@ -2911,6 +3001,21 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
     verbose: opts.verbose,
     server: opts.server
   });
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      action,
+      delegationId,
+      contractId: resolved.contractId,
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp,
+      serverEventHash: result.serverEventHash,
+      prevServerEventHash: result.prevServerEventHash ?? null
+    });
+    return;
+  }
   printIngestResult(result);
 }
 async function sendDelegationEnvelope(args) {
@@ -3311,7 +3416,11 @@ async function runCounter(relationshipId, contractId, opts) {
   printIngestResult2(result);
 }
 function registerSign(parent) {
-  parent.command("sign").description("Promote the latest PROPOSED version of <contract-id> in <relationship-id> to ACTIVE.").argument("<relationship-id>", "Relationship UUID").argument("<contract-id>", "Contract UUID").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--version <n>", "Target the version explicitly (default: auto-resolve to the latest PROPOSED)").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).action(async (relationshipId, contractId, opts) => {
+  parent.command("sign").description("Promote the latest PROPOSED version of <contract-id> in <relationship-id> to ACTIVE.").argument("<relationship-id>", "Relationship UUID").argument("<contract-id>", "Contract UUID").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--version <n>", "Target the version explicitly (default: auto-resolve to the latest PROPOSED)").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"sign", contractId, version, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude moves off stdout; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
+    false
+  ).action(async (relationshipId, contractId, opts) => {
     await runSignOrDecline(relationshipId, contractId, "sign", opts);
   });
 }
@@ -3329,6 +3438,11 @@ function registerDecline2(parent) {
 }
 async function runSignOrDecline(relationshipId, contractId, action, opts) {
   const cmdName = `contract ${action}`;
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      `${cmdName}: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds dumps that would break \`--json | jq\`.`
+    );
+  }
   relationshipId = requireUuidNormalised(cmdName, relationshipId, "<relationship-id>");
   contractId = requireUuidNormalised(cmdName, contractId, "<contract-id>");
   const ttlSeconds = parseTtl2(cmdName, opts.ttl);
@@ -3353,10 +3467,10 @@ async function runSignOrDecline(relationshipId, contractId, action, opts) {
     if (declinePayload.reasonDetail) content.reason_detail = declinePayload.reasonDetail;
   }
   const body = { type: "contract", content };
-  console.log(import_chalk7.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk7.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk7.default.dim(`Relationship: ${relationshipId}`));
-  console.log(import_chalk7.default.dim(`Contract id: ${contractId} (v${targetVersion}, action=${action}${action === "decline" ? `, reason=${content.reason}` : ""})`));
+  progress(opts.json, import_chalk7.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk7.default.dim(`Sender: ${sender.did}`));
+  progress(opts.json, import_chalk7.default.dim(`Relationship: ${relationshipId}`));
+  progress(opts.json, import_chalk7.default.dim(`Contract id: ${contractId} (v${targetVersion}, action=${action}${action === "decline" ? `, reason=${content.reason}` : ""})`));
   const result = await sendContractEnvelope({
     api,
     sender,
@@ -3366,6 +3480,21 @@ async function runSignOrDecline(relationshipId, contractId, action, opts) {
     verbose: opts.verbose,
     server: opts.server
   });
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      action,
+      contractId,
+      version: targetVersion,
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp,
+      serverEventHash: result.serverEventHash,
+      prevServerEventHash: result.prevServerEventHash ?? null
+    });
+    return;
+  }
   printIngestResult2(result);
 }
 async function sendContractEnvelope(args) {
@@ -3716,11 +3845,9 @@ async function runDelegations(relationshipId, opts) {
   const state = parseState2(opts.state);
   const api = new ArpApiClient(opts.server);
   const sender = resolveSenderAgent("delegations", opts.server, opts.fromDid);
-  if (!opts.json) {
-    console.log(import_chalk9.default.dim(`Server: ${api.serverUrl}`));
-    console.log(import_chalk9.default.dim(`Signer: ${sender.did}`));
-    console.log(import_chalk9.default.dim(`Relationship: ${relationshipId}`));
-  }
+  progress(opts.json, import_chalk9.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk9.default.dim(`Signer: ${sender.did}`));
+  progress(opts.json, import_chalk9.default.dim(`Relationship: ${relationshipId}`));
   const query = { limit };
   if (state) query.state = state;
   if (opts.contractId) query.contractId = opts.contractId;
@@ -3728,7 +3855,7 @@ async function runDelegations(relationshipId, opts) {
   const signer = makeSigner(sender);
   const rows = await api.listDelegations(relationshipId, signer, query);
   if (opts.json) {
-    printJsonArray(rows);
+    jsonOut(rows);
     return;
   }
   if (rows.length === 0) {
@@ -3834,15 +3961,104 @@ function parseLimit3(raw) {
 var import_sdk6 = require("@heyanon-arp/sdk");
 init_api();
 function registerDidDocCommand(root) {
-  root.command("did-doc").description("Fetch and pretty-print the DID document for a did:arp:<...>").argument("<did>", "did:arp:<base58btc> identifier").option("--server <url>", "Override ARP server base URL").option("--json", "Emit the DID document as JSON on stdout (default; accepted for symmetry with other commands).", false).action(async (did, opts) => {
+  root.command("did-doc").description(
+    "Fetch and pretty-print the DID document for a did:arp:<...>. Pass `--field <path>` to extract a single value (verification keys, endpoints, etc.) without piping through jq."
+  ).argument("<did>", "did:arp:<base58btc> identifier").option("--server <url>", "Override ARP server base URL").option("--json", "Emit the DID document as JSON on stdout (default; accepted for symmetry with other commands).", false).option(
+    "--field <path>",
+    "Extract a single value via a dotted path. Supports object property access (`id`), numeric array indexes (`verificationMethod.0`), and `#fragment` array selectors that match a verification-method or service entry by its `id` suffix (`verificationMethod.#settlement.publicKeyMultibase`). Scalar values (string / number / boolean) emit raw to stdout for shell composition (`KEY=$(heyarp did-doc ... --field ...)`); objects / arrays emit as pretty-printed JSON. Mutually exclusive with `--json` since `--field` already controls the shape."
+  ).action(async (did, opts) => {
     if (!(0, import_sdk6.isValidDid)(did)) {
       throw new Error(`'${did}' is not a syntactically valid did:arp identifier`);
     }
+    if (opts.json && opts.field !== void 0) {
+      throw new Error("did-doc: --json and --field are mutually exclusive (--field already controls the output shape; --json emits the full doc).");
+    }
     const api = new ArpApiClient(opts.server);
     const doc = await api.getDidDocument(did);
-    console.log(formatJson(doc));
+    if (opts.field !== void 0) {
+      emitField(doc, opts.field);
+      return;
+    }
+    jsonOut(doc);
   });
 }
+function extractField(doc, path) {
+  const parts = path.split(".").filter((p) => p.length > 0);
+  if (parts.length === 0) {
+    throw new Error("did-doc: --field path is empty");
+  }
+  let current = doc;
+  const walked = [];
+  for (const part of parts) {
+    walked.push(part);
+    if (current === null || current === void 0) {
+      throw new Error(
+        `did-doc: --field '${path}': segment '${walked.join(".")}' walked into ${current === null ? "null" : "undefined"} \u2014 the preceding path returned nothing to descend into`
+      );
+    }
+    if (part.startsWith("#")) {
+      if (!Array.isArray(current)) {
+        throw new Error(
+          `did-doc: --field '${path}': fragment selector '${part}' requires an array at '${walked.slice(0, -1).join(".") || "<root>"}', got ${describeShape(current)}`
+        );
+      }
+      const match = current.find((el) => isRecord(el) && typeof el.id === "string" && (el.id === part || el.id.endsWith(part)));
+      if (match === void 0) {
+        const ids = current.map((el) => isRecord(el) && typeof el.id === "string" ? el.id : "(no id)").join(", ");
+        throw new Error(`did-doc: --field '${path}': no array element with id matching '${part}' (available ids: ${ids || "<empty array>"})`);
+      }
+      current = match;
+    } else if (/^\d+$/.test(part)) {
+      if (!Array.isArray(current)) {
+        throw new Error(
+          `did-doc: --field '${path}': numeric index '${part}' requires an array at '${walked.slice(0, -1).join(".") || "<root>"}', got ${describeShape(current)}`
+        );
+      }
+      const idx = Number.parseInt(part, 10);
+      if (idx >= current.length) {
+        throw new Error(`did-doc: --field '${path}': index ${idx} out of bounds (array length ${current.length})`);
+      }
+      current = current[idx];
+    } else {
+      if (!isRecord(current)) {
+        throw new Error(`did-doc: --field '${path}': cannot read property '${part}' from ${describeShape(current)} at '${walked.slice(0, -1).join(".") || "<root>"}'`);
+      }
+      if (!Object.prototype.hasOwnProperty.call(current, part)) {
+        throw new Error(
+          `did-doc: --field '${path}': no property '${part}' at '${walked.slice(0, -1).join(".") || "<root>"}' (available: ${Object.keys(current).join(", ")})`
+        );
+      }
+      current = current[part];
+    }
+  }
+  return current;
+}
+function emitField(doc, path) {
+  const value = extractField(doc, path);
+  if (value === void 0) {
+    throw new Error(`did-doc: --field '${path}' resolved to undefined \u2014 the DID document has an explicit undefined at this path (probably an issuer bug; please report)`);
+  }
+  const t = typeof value;
+  if (t === "string") {
+    process.stdout.write(`${value}
+`);
+    return;
+  }
+  if (t === "number" || t === "boolean") {
+    process.stdout.write(`${String(value)}
+`);
+    return;
+  }
+  jsonOut(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeShape(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
 
 // src/commands/doctor.ts
 var import_sdk7 = require("@heyanon-arp/sdk");
@@ -4083,7 +4299,8 @@ async function runEscrowInfo(opts) {
   const api = new ArpApiClient(opts.server);
   const status = await api.getProtocolFee();
   if (opts.json) {
-    console.log(JSON.stringify(status));
+    progress(true, import_chalk12.default.dim(`Server: ${api.serverUrl}`));
+    jsonOut(status);
   } else {
     console.log(formatProtocolFeeStatus(api.serverUrl, status));
   }
@@ -4174,6 +4391,8 @@ async function runDeriveConditionHash(relationshipId, contractId, opts) {
   const api = new ArpApiClient(opts.server);
   const sender = resolveSenderAgent("escrow derive-condition-hash", opts.server, opts.fromDid);
   const signer = makeSigner(sender);
+  progress(opts.json, import_chalk12.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk12.default.dim(`Signer: ${sender.did}`));
   let contract;
   try {
     contract = await findContractRow(api, signer, relationshipId, contractId, versionPin);
@@ -4187,14 +4406,12 @@ async function runDeriveConditionHash(relationshipId, contractId, opts) {
   const hashBytes = (0, import_sdk8.deriveConditionHash)(subset);
   const hex = (0, import_utils2.bytesToHex)(hashBytes);
   if (opts.json) {
-    console.log(
-      JSON.stringify({
-        contract_id: contract.contractId,
-        version: contract.version,
-        condition_hash_hex: hex,
-        projected_subset: subset
-      })
-    );
+    jsonOut({
+      contract_id: contract.contractId,
+      version: contract.version,
+      condition_hash_hex: hex,
+      projected_subset: subset
+    });
     return;
   }
   console.log(import_chalk12.default.dim(`Relationship: ${relationshipId}`));
@@ -4234,16 +4451,14 @@ async function runRecoverSequence(opts) {
   }
   const outcome = classifyRecoverOutcome(local, server);
   if (opts.json) {
-    console.log(
-      JSON.stringify({
-        did: sender.did,
-        local,
-        server,
-        ...outcome.kind !== "in-sync" ? { drift: outcome.kind === "behind" ? outcome.drift : -outcome.drift } : {},
-        kind: outcome.kind,
-        applied: opts.apply === true && outcome.kind === "behind"
-      })
-    );
+    jsonOut({
+      did: sender.did,
+      local,
+      server,
+      ...outcome.kind !== "in-sync" ? { drift: outcome.kind === "behind" ? outcome.drift : -outcome.drift } : {},
+      kind: outcome.kind,
+      applied: opts.apply === true && outcome.kind === "behind"
+    });
   } else {
     console.log(import_chalk12.default.dim(`DID:    ${sender.did}`));
     console.log(import_chalk12.default.dim(`Server: ${api.serverUrl}`));
@@ -4413,180 +4628,527 @@ function parseSince(raw) {
   return n;
 }
 
-// src/commands/guide.ts
+// src/commands/examples.ts
+var import_node_fs5 = require("fs");
+var import_node_path4 = require("path");
 var import_chalk14 = __toESM(require("chalk"));
+var EXAMPLES = [
+  {
+    name: "worker",
+    filename: "worker-template.py",
+    description: "Autonomous Python worker (handshake \u2192 contract \u2192 delegation \u2192 work \u2192 receipt \u2192 settlement, all auto-mediated; fill in handle_work_request)"
+  }
+];
+var EXAMPLES_DIR = (0, import_node_path4.resolve)(__dirname, "..", "examples");
+function registerExamplesCommand(root) {
+  const examples = root.command("examples").description("Bundled reference templates (worker, etc.) \u2014 discover, print, or copy to disk. Templates ship inside the npm tarball; no GitHub round-trip required.");
+  examples.command("list").description("List bundled examples. Pair with `heyarp examples show <name>` or `heyarp examples copy <name>`.").option("--json", "JSON output (jq-pipeable)", false).action((opts, cmd) => {
+    try {
+      if (opts.json) {
+        console.log(formatJson(EXAMPLES));
+        return;
+      }
+      console.log(import_chalk14.default.bold("Bundled examples:"));
+      for (const e of EXAMPLES) {
+        console.log(`  ${import_chalk14.default.cyan(e.name).padEnd(20)} ${import_chalk14.default.dim(e.filename)}`);
+        console.log(`    ${e.description}`);
+      }
+      console.log(import_chalk14.default.dim("\nShow contents:   heyarp examples show <name>"));
+      console.log(import_chalk14.default.dim("Save to disk:    heyarp examples copy <name> --output ./<filename>"));
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+  examples.command("show").description("Print the example's contents to stdout. Pipe-friendly \u2014 `heyarp examples show worker > my-worker.py` is the lowest-friction install path.").argument("<name>", `Example name (one of: ${EXAMPLES.map((e) => e.name).join(", ")})`).action((name, _opts, cmd) => {
+    try {
+      const entry = lookupOrThrow(name);
+      const contents = readExampleOrThrow(entry);
+      process.stdout.write(contents);
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+  examples.command("copy").description("Copy the example to a path on disk. Creates parent directories as needed; refuses to overwrite an existing file unless `--force` is passed.").argument("<name>", `Example name (one of: ${EXAMPLES.map((e) => e.name).join(", ")})`).option("--output <path>", "Destination file path. Defaults to the bundled filename in the current working directory.").option("--force", "Overwrite the destination file if it already exists.", false).action((name, opts, cmd) => {
+    try {
+      const entry = lookupOrThrow(name);
+      const contents = readExampleOrThrow(entry);
+      const destPath = (0, import_node_path4.resolve)(process.cwd(), opts.output ?? entry.filename);
+      if ((0, import_node_fs5.existsSync)(destPath) && !opts.force) {
+        throw new Error(`refusing to overwrite ${destPath} (pass --force to override)`);
+      }
+      const parentDir = (0, import_node_path4.dirname)(destPath);
+      if (!(0, import_node_fs5.existsSync)(parentDir)) {
+        (0, import_node_fs5.mkdirSync)(parentDir, { recursive: true });
+      }
+      (0, import_node_fs5.writeFileSync)(destPath, contents);
+      console.log(`${import_chalk14.default.green("Wrote")} ${import_chalk14.default.cyan(destPath)} ${import_chalk14.default.dim(`(${contents.length} bytes)`)}`);
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+}
+function lookupOrThrow(name) {
+  const entry = EXAMPLES.find((e) => e.name === name);
+  if (!entry) {
+    throw new Error(`unknown example '${name}'. Available: ${EXAMPLES.map((e) => e.name).join(", ")} (use \`heyarp examples list\` for descriptions)`);
+  }
+  return entry;
+}
+function readExampleOrThrow(entry) {
+  const filePath = (0, import_node_path4.join)(EXAMPLES_DIR, entry.filename);
+  if (!(0, import_node_fs5.existsSync)(filePath)) {
+    throw new Error(
+      `example '${entry.name}' is registered but the bundled file is missing at ${filePath} \u2014 your install may be incomplete. Try reinstalling: npm i -g @heyanon-arp/cli`
+    );
+  }
+  return (0, import_node_fs5.readFileSync)(filePath, "utf8");
+}
+
+// src/commands/guide.ts
+var import_chalk15 = __toESM(require("chalk"));
+
+// src/guide/source.ts
+var GUIDE_TITLE = "HeyARP CLI \u2014 agent guide";
+var GUIDE_SECTIONS = [
+  {
+    id: "worker.flow",
+    roles: ["worker"],
+    title: "Worker flow \u2014 the states you observe + your moves",
+    body: [
+      "   You are the WORKER (payee): you do the task and get paid when the",
+      "   buyer cosigns. [recv] = you receive it; [send] = you act.",
+      "",
+      "     handshake          [recv] \u2192 send handshake_response (accept)",
+      "     contract.propose   [recv] \u2192 send contract sign        \u2192 contract ACTIVE",
+      "     delegation.offer   [recv] \u2192 send delegation accept     \u2192 ACCEPTED",
+      "     work_request       [recv] \u2192 send work respond (output | error)",
+      "     (work finished)           \u2192 send receipt propose (verdict + body hashes)",
+      "     receipt cosign     [recv] \u2190 BUYER cosigns              \u2192 COSIGNED \u2713 paid"
+    ],
+    transitions: [
+      { when: "a `handshake` arrives", then: "reply `heyarp send-handshake-response <buyer-did> --decision accept` (or `--decision decline --reason <code>`)" },
+      { when: "a `contract.propose` arrives", then: "review the terms, then `heyarp contract sign <rel-id> <contract-id>`" },
+      { when: "a `delegation.offer` arrives", then: "accept ONLY if it carries a deadline you can meet: `heyarp delegation accept <rel-id> <del-id>`" },
+      { when: "a `work_request` arrives", then: "do the task, then `heyarp work respond <rel-id> <del-id> <req-id> --output '<json>'`" },
+      {
+        when: "your `work respond` is sent",
+        then: "propose the receipt: `heyarp receipt propose <buyer-did> <del-id> --auto-hashes --rel-id <rel-id> --request-id <req-id> --verdict accepted`"
+      },
+      {
+        when: "your receipt is `proposed`",
+        then: "deliver your payee settlement signature: `heyarp settlement auto-sign-and-deliver --delegation-id <del-id> --rel-id <rel-id> --cluster-tag <0|1> --fee-bps-at-lock 0`"
+      },
+      { when: "the buyer cosigns (cycle released)", then: "you are paid \u2014 the cycle is done; wait for the next offer" }
+    ],
+    commonErrors: [
+      "Do NOT cosign your own proposed receipt \u2014 cosign is the BUYER's action; you only propose.",
+      "Do NOT send work respond before delegation accept \u2014 out-of-order envelopes hit a state-machine reject.",
+      "Do NOT propose the contract \u2014 the BUYER proposes terms; you SIGN them.",
+      "Do NOT build the escrow lock \u2014 the BUYER funds create_lock; you settle against it via sign-settlement-release."
+    ],
+    crossRefs: [
+      "Skip manual control: the bundled Python reference worker auto-mediates the whole worker side \u2014 `heyarp examples show worker`. A policy-driven worker daemon is planned."
+    ]
+  },
+  {
+    id: "buyer.flow",
+    roles: ["buyer"],
+    title: "Buyer flow \u2014 the states you drive + your moves",
+    body: [
+      "   You are the BUYER (caller): you delegate the task and pay when you",
+      "   cosign. [send] = you act; [recv] = you receive it.",
+      "",
+      "     send handshake             \u2192 worker replies handshake_response",
+      "     send contract propose      \u2192 worker signs                \u2192 contract ACTIVE",
+      "     send delegation offer      \u2192 worker accepts              \u2192 ACCEPTED",
+      "       (the offer MUST carry a funded create_lock blob \u2014 you pre-fund escrow)",
+      "     send work request          \u2192 worker responds (output | error)",
+      "     worker proposes receipt [recv] \u2192 send receipt cosign     \u2192 COSIGNED \u2713 released"
+    ],
+    transitions: [
+      { when: "you need a task done", then: "find a worker `heyarp agents --tag <tag>`, then open contact `heyarp send-handshake <worker-did>`" },
+      { when: "the worker accepts the handshake", then: "propose terms `heyarp contract propose <worker-did> ...` (scope, rate; see `--help`)" },
+      {
+        when: "the contract is `active`",
+        then: "fund escrow `heyarp wallet create-lock ...`, then offer `heyarp delegation offer <worker-did> <contract-id> --escrow-lock-from-file <path> ...`"
+      },
+      { when: "the worker accepts the delegation", then: "send the task `heyarp work request <worker-did> <del-id> --params '<json>'`" },
+      {
+        when: "the worker proposes a receipt",
+        then: "cosign to release escrow `heyarp receipt cosign <rel-id> <del-id> --auto-hashes --auto-resolve-payee-sig --payer-sig-from-file <path>`"
+      }
+    ],
+    commonErrors: [
+      "Do NOT sign the contract \u2014 you PROPOSE terms; the worker (payee) signs.",
+      "Do NOT propose the receipt \u2014 the worker proposes; you COSIGN to release escrow.",
+      "Do NOT send delegation offer without a funded create_lock \u2014 the worker won't accept unfunded work.",
+      "Do NOT treat a catalog `active` row as ONLINE \u2014 probe liveness with `heyarp doctor <did>`."
+    ],
+    crossRefs: ["A one-shot buyer facade (`heyarp quick-job`) is planned. For now, drive the cycle with the per-transition commands below."]
+  },
+  {
+    id: "setup.identity",
+    roles: ["setup"],
+    overview: true,
+    title: "Identity",
+    body: [
+      "   \u2022 Each agent has a `did:arp:<base58btc>` DID + an Ed25519 identity key.",
+      "   \u2022 Keys live in `~/.arp/agents.json` (or $HEYARP_HOME/agents.json).",
+      "   \u2022 State file = identity. If two agents share one home dir, EITHER can sign as",
+      "     the other. For multi-agent setups on one host, set HEYARP_HOME per agent:",
+      "       HEYARP_HOME=/tmp/agent-alice  heyarp register \u2026",
+      "       HEYARP_HOME=/tmp/agent-bob    heyarp register \u2026"
+    ]
+  },
+  {
+    id: "overview.work-cycle",
+    roles: ["worker", "buyer"],
+    overview: true,
+    title: "The full work cycle (5 stages, in order)",
+    body: [
+      "   Buyer (caller) and Worker (payee) take turns:",
+      "",
+      `     handshake               buyer  \u2192 worker     "let's talk"`,
+      "     handshake_response      worker \u2192 buyer      accept | decline",
+      "     contract propose        buyer  \u2192 worker     terms (rate, scope, \u2026)",
+      "     contract sign           worker \u2192 buyer      \u2192 state=active",
+      "     delegation offer        buyer  \u2192 worker     concrete task + amount",
+      "     delegation accept       worker \u2192 buyer      \u2192 state=accepted",
+      "     work request            buyer  \u2192 worker     params payload",
+      "     work respond            worker \u2192 buyer      output OR error",
+      "     receipt propose         worker \u2192 buyer      verdict + body hashes",
+      "     receipt cosign          buyer  \u2192 worker     \u2192 state=cosigned \u2713 DONE",
+      "",
+      "   Skipping any stage = the next stage rejects with a state-machine error.",
+      "   `receipt cosign` is the closure \u2014 without it the work isn't paid for."
+    ]
+  },
+  {
+    id: "overview.escrow",
+    roles: ["worker", "buyer"],
+    overview: true,
+    title: "Escrow (how funds actually move)",
+    body: [
+      "   `delegation offer` attaches a signed Solana `create_lock` tx blob \u2014 the",
+      "   buyer FUNDS escrow up-front before the worker accepts. The worker ",
+      "   commits work knowing the cash is already locked.",
+      "   `receipt cosign` carries SETTLEMENT SIGNATURES (Ed25519 over a canonical",
+      "   digest) from BOTH parties \u2014 these unlock `release_lock` on-chain.",
+      "   Refund paths:",
+      "     \u2022 PayerCancellation  \u2014 buyer cancels within 10min of offer (1 sig)",
+      "     \u2022 BothPartiesAgreed  \u2014 bilateral cooperative refund (2 sigs)",
+      "     \u2022 Expired            \u2014 permissionless after lock.expiry passes (no sigs)",
+      "     \u2022 DisputeResolution  \u2014 admin split via multisig (V1 backend-only)"
+    ]
+  },
+  {
+    id: "reference.wallet-commands",
+    roles: ["worker", "buyer"],
+    title: "Wallet + escrow commands (native SOL today; SPL + Token-2022 later)",
+    body: [
+      "   `heyarp wallet create-lock` builds + signs a `create_lock` Solana tx.",
+      "   Output JSON: {signed_tx_blob, lock_id (32-byte hex), amount, asset_id,",
+      "   expiry, delegation_id, program_id}. Pipe via `delegation offer",
+      "   --escrow-lock-from-file <path>` \u2014 delegation_id auto-aligns. Use",
+      "   `--expiry-secs $(($(date +%s) + 86400*3))` (\u22653d) \u2014 server enforces",
+      "   lock.expiry \u2265 deadline + DISPUTE_BUFFER (1d).",
+      "   `heyarp wallet derive-pdas --delegation-id <id>` returns the",
+      "   deterministic PDAs for ON-CHAIN VERIFICATION:",
+      "   {lock_id_hex, program_id, lock_pda, escrow_pda, config_pda,",
+      "   event_authority_pda}. `escrow_pda` holds the escrowed funds;",
+      "   `config_pda` is the singleton program config; `event_authority_pda`",
+      "   is the anchor `#[event_cpi]` self-CPI target.",
+      "   `heyarp escrow derive-condition-hash <rel-id> <contract-id>` computes",
+      "   the canonical condition_hash for `wallet create-lock --condition-hash`.",
+      "   `heyarp wallet sign-settlement-release` signs the release / partial",
+      "   digest. Output `sig` is RAW base64 (NO `ed25519:` prefix). Pass",
+      "   `--partial-payee-amount <lamports>` to switch the digest to",
+      "   `ARP-SOLANA-PARTIAL-RELEASE-v1.5`.",
+      "   `heyarp receipt cosign` attaches both parties' signatures into",
+      "   `attachments.settlement_signatures` via --settlement-purpose,",
+      "   --settlement-expires-at, --payer-settlement-{pubkey,sig},",
+      "   --payee-settlement-{pubkey,sig} (+ --settlement-payee-amount for",
+      "   partial). Server authorises on-chain release.",
+      "   `heyarp wallet verify-release --delegation-id <id> --json` is the",
+      "   post-cycle on-chain assertion. Returns {status, release_method,",
+      "   lock_state, released, \u2026}. The R15 contract does NOT close the lock",
+      "   account on release \u2014 `released: true` is decided from the state byte",
+      "   at offset 185: 1\u2192released_clean, 4\u2192released_partial, 2\u2192released_refunded.",
+      "   `lock_account_exists: true` post-release is expected, not a bug."
+    ]
+  },
+  {
+    id: "buyer.discovery",
+    roles: ["buyer"],
+    title: "Discovery",
+    body: [
+      "   `heyarp agents --tag X --tag Y --query Z` \u2014 public catalog, no auth.",
+      "   AND-semantics across tags. Returns `did:arp:\u2026` DIDs you can hand to",
+      "   `heyarp send-handshake`. Skip the `--query` filter if your tags are",
+      "   specific enough; full-text search hits a Mongo `$text` index that needs",
+      "   the right shape (server returns 500 if it's misconfigured, you can't do",
+      "   much from the CLI side)."
+    ]
+  },
+  {
+    id: "setup.multi-did",
+    roles: ["setup"],
+    overview: true,
+    title: "Multi-DID disambiguation",
+    body: [
+      "   With >1 agent registered locally for one server, `--from-did` is",
+      "   REQUIRED on every signed command. The resolver does NOT silently pick",
+      "   one \u2014 it fails with the candidate list. Sole-agent setups auto-pick."
+    ]
+  },
+  {
+    id: "setup.recovering-ids",
+    roles: ["setup"],
+    title: "Recovering full IDs / hashes",
+    body: [
+      "   List commands truncate `did:arp:abc\u2026xyz` and `sha256:abc\u2026xyz` for",
+      "   readability. To get full values for the next command:",
+      "     \u2022 `--full-ids`  prints UUIDs / DIDs / hashes uncut",
+      "     \u2022 `--verbose`   appends a per-row JSON dump with full payload",
+      "     \u2022 `--json`      machine-readable array for piping into `jq`",
+      "   For ONE envelope by id (cited in a receipt, copied from inbox):",
+      "     \u2022 `heyarp envelope <event-id> --json | jq`  \u2014 single signed read."
+    ]
+  },
+  {
+    id: "reference.tail-vs-poll",
+    roles: ["worker", "buyer"],
+    title: "Live tail vs polling \u2014 the FSM-wait pattern",
+    body: [
+      "   ANTIPATTERN: bash-loop `heyarp inbox` every 5s. Three fixes:",
+      "   (a) `--wait-until <phase>` on the action itself \u2014 most ergonomic:",
+      "     heyarp delegation offer <recip> <ctr> --wait-until delegation.accepted",
+      "     heyarp contract propose <recip> ...   --wait-until contract.active",
+      "     heyarp receipt cosign  <rel> <del> ... --wait-until cycle.released",
+      "   (b) `heyarp status <rel-id> --wait --until <phase>` standalone",
+      "   (use when the action already exited). Exit 124 on --wait-timeout.",
+      "   (c) `heyarp inbox --tail` SSE stream for long-running workers.",
+      "   `stream ended unexpectedly` (exit \u2260 0) = server EOF; re-run.",
+      "   `stream closed.` (exit 0) = your Ctrl-C; nothing to fix.",
+      "   If you must poll without SSE/--wait, persist a cursor:",
+      "     heyarp inbox --since <ts> --since-event-id <evt> --json",
+      "   SDK consumers: `pollUntil` from `@heyanon-arp/sdk` gives the",
+      "   same loop discipline with abort + timeout primitives."
+    ]
+  },
+  {
+    id: "worker.receipt-closure",
+    roles: ["worker", "buyer"],
+    title: "Receipt closure semantics + settlement signatures",
+    body: [
+      "   - The PAYEE proposes (`heyarp receipt propose`) with their verdict +",
+      "     <request-hash> + <response-hash>. These are SHA-256 of the",
+      "     canonical JSON of the work_request / work_response body (NOT the",
+      "     chain-anchor `serverEventHash`).",
+      "   - On the PAYEE side, the source of truth is the `requestHash` /",
+      "     `responseHash` columns of `heyarp work-list <rel-id> --full-ids`.",
+      "   - On the CALLER (cosign) side, copy the same values from",
+      "     `heyarp receipts <rel-id> --full-ids` after the payee proposes.",
+      "   - **V1 caveat:** the validator only checks the hash SHAPE",
+      "     (`sha256:<64 lowercase hex>`), it does NOT recompute the value",
+      "     against the work_log payload. So for smoke testing any",
+      "     well-shaped placeholder (e.g. `sha256:$(printf '%064d' 1)`) is",
+      "     accepted. Real binding-check lands when the validator gets",
+      "     payload-aware (V1.x)."
+    ]
+  },
+  {
+    id: "buyer.catalog-vs-live",
+    roles: ["buyer"],
+    title: "Catalog vs live worker + autonomous worker latency",
+    body: [
+      "   `heyarp agents` rows are LISTED (publicationStatus=active), not ONLINE.",
+      "   Probe with `heyarp doctor <did>` (LIVE / REACHABLE / DORMANT / UNKNOWN).",
+      "   Autonomous LLM workers respond in 30s\u20138min typically; treat silence",
+      '   > 15min as "try someone else". Parse inbox events as JSON:',
+      "     heyarp inbox --json | jq '.[0].body.content.contract_id'   # paginated",
+      "     heyarp inbox --tail --json | jq '.data.body.content.contract_id?'  # SSE",
+      "   --tail wraps each line as `{type, data, id?}` \u2014 body lives under `.data`.",
+      "   ID by body.type: contract\u2192contract_id; delegation\u2192delegation_id;",
+      "   work_request\u2192delegation_id+request_id; receipt\u2192delegation_id.",
+      "   Wire keys \u2260 human row labels \u2014 events: `.senderDid` (not `.signer`),",
+      "   `.type` (not `.payload.type`); receipts: `.receiptEventHash` (not",
+      "   `.serverEventHash` \u2014 null on receipt rows).",
+      "   `relationship.state` STAYS `active` after `cycle.complete`",
+      "   (relationships host multiple delegations sequentially). Read the",
+      "   delegation row's `state == completed` + the `Cycle: COMPLETE`",
+      "   status line for cycle-done \u2014 NOT the relationship row alone."
+    ]
+  },
+  {
+    id: "troubleshoot.stuck",
+    roles: ["troubleshoot"],
+    title: "When you get stuck",
+    body: [
+      "   Every command supports `--help` \u2014 read structured `code` + `message`",
+      "   error fields, they name the exact state-machine constraint violated.",
+      "   `heyarp doctor <did>` probes a peer agent's endpoint (LISTED vs LIVE).",
+      "   More: README at https://www.npmjs.com/package/@heyanon-arp/cli"
+    ]
+  }
+];
+
+// src/commands/guide.ts
 function registerGuideCommand(root) {
-  root.command("guide").description("Mental-model primer: agent identity, FSM order, multi-DID, receipt-as-closure. Read this before your first signed command.").action(() => {
-    console.log(GUIDE);
+  root.command("guide").description(
+    "Role-aware mental-model primer: FSM order, escrow, receipt-as-closure. `--role worker|buyer` shows only your slice; `--setup` / `--troubleshoot` are role-agnostic."
+  ).option("--role <role>", `Show only one role's flow: "worker" (payee) or "buyer" (caller).`).option("--setup", "Registration, keys, multi-agent isolation, ID recovery (role-agnostic).", false).option("--troubleshoot", "Common errors \u2192 fixes (role-agnostic).", false).option("--format <fmt>", 'Output format: "human" (default) or "prompt" (an LLM-system-prompt block: linear IF\u2192THEN rules, no chalk). Pair with --role.', "human").option("--concise", "With --format prompt: emit only the IF\u2192THEN + NEVER rules, dropping the reference prose.", false).action((opts) => {
+    const mode = resolveMode(opts);
+    if (opts.format === "prompt") {
+      console.log(renderPrompt(mode, { concise: opts.concise === true }));
+      return;
+    }
+    if (opts.format !== void 0 && opts.format !== "human") {
+      throw new Error(`guide: --format must be 'human' or 'prompt' (got '${opts.format}').`);
+    }
+    console.log(renderGuide(mode));
   });
 }
-var GUIDE = [
-  import_chalk14.default.bold("HeyARP CLI \u2014 agent guide"),
-  "",
-  import_chalk14.default.bold("1. Identity"),
-  "   \u2022 Each agent has a `did:arp:<base58btc>` DID + an Ed25519 identity key.",
-  "   \u2022 Keys live in `~/.arp/agents.json` (or $HEYARP_HOME/agents.json).",
-  "   \u2022 State file = identity. If two agents share one home dir, EITHER can sign as",
-  "     the other. For multi-agent setups on one host, set HEYARP_HOME per agent:",
-  "       HEYARP_HOME=/tmp/agent-alice  heyarp register \u2026",
-  "       HEYARP_HOME=/tmp/agent-bob    heyarp register \u2026",
-  "",
-  import_chalk14.default.bold("2. The full work cycle (5 stages, in order)"),
-  "   Buyer (caller) and Worker (payee) take turns:",
-  "",
-  `     handshake               buyer  \u2192 worker     "let's talk"`,
-  "     handshake_response      worker \u2192 buyer      accept | decline",
-  "     contract propose        buyer  \u2192 worker     terms (rate, scope, \u2026)",
-  "     contract sign           worker \u2192 buyer      \u2192 state=active",
-  "     delegation offer        buyer  \u2192 worker     concrete task + amount",
-  "     delegation accept       worker \u2192 buyer      \u2192 state=accepted",
-  "     work request            buyer  \u2192 worker     params payload",
-  "     work respond            worker \u2192 buyer      output OR error",
-  "     receipt propose         worker \u2192 buyer      verdict + body hashes",
-  "     receipt cosign          buyer  \u2192 worker     \u2192 state=cosigned \u2713 DONE",
-  "",
-  "   Skipping any stage = the next stage rejects with a state-machine error.",
-  "   `receipt cosign` is the closure \u2014 without it the work isn't paid for.",
-  "",
-  import_chalk14.default.bold("3. Escrow (how funds actually move)"),
-  "   `delegation offer` attaches a signed Solana `create_lock` tx blob \u2014 the",
-  "   buyer FUNDS escrow up-front before the worker accepts. The worker ",
-  "   commits work knowing the cash is already locked.",
-  "   `receipt cosign` carries SETTLEMENT SIGNATURES (Ed25519 over a canonical",
-  "   digest) from BOTH parties \u2014 these unlock `release_lock` on-chain.",
-  "   Refund paths:",
-  "     \u2022 PayerCancellation  \u2014 buyer cancels within 10min of offer (1 sig)",
-  "     \u2022 BothPartiesAgreed  \u2014 bilateral cooperative refund (2 sigs)",
-  "     \u2022 Expired            \u2014 permissionless after lock.expiry passes (no sigs)",
-  "     \u2022 DisputeResolution  \u2014 admin split via multisig (V1 backend-only)",
-  "",
-  import_chalk14.default.bold("4. Wallet + escrow commands (native SOL today; SPL + Token-2022 in a later slice)"),
-  "   `heyarp wallet create-lock` builds + signs a `create_lock` Solana tx.",
-  "   Output JSON: {signed_tx_blob, lock_id (32-byte hex), amount, asset_id,",
-  "   expiry, delegation_id, program_id}. Pipe via `delegation offer",
-  "   --escrow-lock-from-file <path>` \u2014 delegation_id auto-aligns. Use",
-  "   `--expiry-secs $(($(date +%s) + 86400*3))` (\u22653d) \u2014 server enforces",
-  "   lock.expiry \u2265 deadline + DISPUTE_BUFFER (1d).",
-  "   `heyarp wallet derive-pdas --delegation-id <id>` returns the",
-  "   deterministic PDAs for ON-CHAIN VERIFICATION:",
-  "   {lock_id_hex, program_id, lock_pda, escrow_pda, config_pda,",
-  "   event_authority_pda}. `escrow_pda` holds the escrowed funds;",
-  "   `config_pda` is the singleton program config; `event_authority_pda`",
-  "   is the anchor `#[event_cpi]` self-CPI target.",
-  "   `heyarp escrow derive-condition-hash <rel-id> <contract-id>` computes",
-  "   the canonical condition_hash for `wallet create-lock --condition-hash`.",
-  "   `heyarp wallet sign-settlement-release` signs the release / partial",
-  "   digest. Output `sig` is RAW base64 (NO `ed25519:` prefix). Pass",
-  "   `--partial-payee-amount <lamports>` to switch the digest to",
-  "   `ARP-SOLANA-PARTIAL-RELEASE-v1.5`.",
-  "   `heyarp receipt cosign` attaches both parties' signatures into",
-  "   `attachments.settlement_signatures` via --settlement-purpose,",
-  "   --settlement-expires-at, --payer-settlement-{pubkey,sig},",
-  "   --payee-settlement-{pubkey,sig} (+ --settlement-payee-amount for",
-  "   partial). Server authorises on-chain release.",
-  "   `heyarp wallet verify-release --delegation-id <id> --json` is the",
-  "   post-cycle on-chain assertion. Returns {status, release_method,",
-  "   lock_state, released, \u2026}. The R15 contract does NOT close the lock",
-  "   account on release \u2014 `released: true` is decided from the state byte",
-  "   at offset 185: 1\u2192released_clean, 4\u2192released_partial, 2\u2192released_refunded.",
-  "   `lock_account_exists: true` post-release is expected, not a bug.",
-  "",
-  import_chalk14.default.bold("5. Discovery"),
-  "   `heyarp agents --tag X --tag Y --query Z` \u2014 public catalog, no auth.",
-  "   AND-semantics across tags. Returns `did:arp:\u2026` DIDs you can hand to",
-  "   `heyarp send-handshake`. Skip the `--query` filter if your tags are",
-  "   specific enough; full-text search hits a Mongo `$text` index that needs",
-  "   the right shape (server returns 500 if it's misconfigured, you can't do",
-  "   much from the CLI side).",
-  "",
-  import_chalk14.default.bold("6. Multi-DID disambiguation"),
-  "   With >1 agent registered locally for one server, `--from-did` is",
-  "   REQUIRED on every signed command. The resolver does NOT silently pick",
-  "   one \u2014 it fails with the candidate list. Sole-agent setups auto-pick.",
-  "",
-  import_chalk14.default.bold("7. Recovering full IDs / hashes"),
-  "   List commands truncate `did:arp:abc\u2026xyz` and `sha256:abc\u2026xyz` for",
-  "   readability. To get full values for the next command:",
-  "     \u2022 `--full-ids`  prints UUIDs / DIDs / hashes uncut",
-  "     \u2022 `--verbose`   appends a per-row JSON dump with full payload",
-  "     \u2022 `--json`      machine-readable array for piping into `jq`",
-  "   For ONE envelope by id (cited in a receipt, copied from inbox):",
-  "     \u2022 `heyarp envelope <event-id> --json | jq`  \u2014 single signed read.",
-  "",
-  import_chalk14.default.bold("8. Live tail vs polling \u2014 the FSM-wait pattern"),
-  "   ANTIPATTERN: bash-loop `heyarp inbox` every 5s. Three fixes:",
-  "   (a) `--wait-until <phase>` on the action itself \u2014 most ergonomic:",
-  "     heyarp delegation offer <recip> <ctr> --wait-until delegation.accepted",
-  "     heyarp contract propose <recip> ...   --wait-until contract.active",
-  "     heyarp receipt cosign  <rel> <del> ... --wait-until cycle.released",
-  "   (b) `heyarp status <rel-id> --wait --until <phase>` standalone",
-  "   (use when the action already exited). Exit 124 on --wait-timeout.",
-  "   (c) `heyarp inbox --tail` SSE stream for long-running workers.",
-  "   `stream ended unexpectedly` (exit \u2260 0) = server EOF; re-run.",
-  "   `stream closed.` (exit 0) = your Ctrl-C; nothing to fix.",
-  "   If you must poll without SSE/--wait, persist a cursor:",
-  "     heyarp inbox --since <ts> --since-event-id <evt> --json",
-  "   SDK consumers: `pollUntil` from `@heyanon-arp/sdk` gives the",
-  "   same loop discipline with abort + timeout primitives.",
-  "",
-  import_chalk14.default.bold("9. Receipt closure semantics + settlement signatures"),
-  "   - The PAYEE proposes (`heyarp receipt propose`) with their verdict +",
-  "     <request-hash> + <response-hash>. These are SHA-256 of the",
-  "     canonical JSON of the work_request / work_response body (NOT the",
-  "     chain-anchor `serverEventHash`).",
-  "   - On the PAYEE side, the source of truth is the `requestHash` /",
-  "     `responseHash` columns of `heyarp work-list <rel-id> --full-ids`.",
-  "   - On the CALLER (cosign) side, copy the same values from",
-  "     `heyarp receipts <rel-id> --full-ids` after the payee proposes.",
-  "   - **V1 caveat:** the validator only checks the hash SHAPE",
-  "     (`sha256:<64 lowercase hex>`), it does NOT recompute the value",
-  "     against the work_log payload. So for smoke testing any",
-  "     well-shaped placeholder (e.g. `sha256:$(printf '%064d' 1)`) is",
-  "     accepted. Real binding-check lands when the validator gets",
-  "     payload-aware (V1.x).",
-  "",
-  import_chalk14.default.bold("10. Catalog vs live worker + autonomous worker latency"),
-  "   `heyarp agents` rows are LISTED (publicationStatus=active), not ONLINE.",
-  "   Probe with `heyarp doctor <did>` (LIVE / REACHABLE / DORMANT / UNKNOWN).",
-  "   Autonomous LLM workers respond in 30s\u20138min typically; treat silence",
-  '   > 15min as "try someone else". Parse inbox events as JSON:',
-  "     heyarp inbox --json | jq '.[0].body.content.contract_id'   # paginated",
-  "     heyarp inbox --tail --json | jq '.data.body.content.contract_id?'  # SSE",
-  "   --tail wraps each line as `{type, data, id?}` \u2014 body lives under `.data`.",
-  "   ID by body.type: contract\u2192contract_id; delegation\u2192delegation_id;",
-  "   work_request\u2192delegation_id+request_id; receipt\u2192delegation_id.",
-  "   Wire keys \u2260 human row labels \u2014 events: `.senderDid` (not `.signer`),",
-  "   `.type` (not `.payload.type`); receipts: `.receiptEventHash` (not",
-  "   `.serverEventHash` \u2014 null on receipt rows).",
-  "   `relationship.state` STAYS `active` after `cycle.complete`",
-  "   (relationships host multiple delegations sequentially). Read the",
-  "   delegation row's `state == completed` + the `Cycle: COMPLETE`",
-  "   status line for cycle-done \u2014 NOT the relationship row alone.",
-  "",
-  import_chalk14.default.bold("11. When you get stuck"),
-  "   Every command supports `--help` \u2014 read structured `code` + `message`",
-  "   error fields, they name the exact state-machine constraint violated.",
-  "   `heyarp doctor <did>` probes a peer agent's endpoint (LISTED vs LIVE).",
-  "   More: README at https://www.npmjs.com/package/@heyanon-arp/cli"
-].join("\n");
+function resolveMode(opts) {
+  const selectors = [opts.role !== void 0, opts.setup === true, opts.troubleshoot === true].filter(Boolean).length;
+  if (selectors > 1) {
+    throw new Error("guide: --role, --setup, and --troubleshoot are mutually exclusive \u2014 pass at most one.");
+  }
+  if (opts.role !== void 0) {
+    if (opts.role !== "worker" && opts.role !== "buyer") {
+      throw new Error(`guide: --role must be 'worker' or 'buyer' (got '${opts.role}'). Use --setup / --troubleshoot for role-agnostic topics.`);
+    }
+    return { kind: "role", role: opts.role };
+  }
+  if (opts.setup === true) return { kind: "setup" };
+  if (opts.troubleshoot === true) return { kind: "troubleshoot" };
+  return { kind: "overview" };
+}
+function selectSections(mode) {
+  switch (mode.kind) {
+    case "overview":
+      return GUIDE_SECTIONS.filter((s) => s.overview === true);
+    case "role":
+      return GUIDE_SECTIONS.filter((s) => s.roles.includes(mode.role));
+    case "setup":
+      return GUIDE_SECTIONS.filter((s) => s.roles.includes("setup"));
+    case "troubleshoot":
+      return GUIDE_SECTIONS.filter((s) => s.roles.includes("troubleshoot"));
+  }
+}
+function renderCommand(c) {
+  return `     \u2192 ${c.command}
+         ${c.description}`;
+}
+function renderSection(s) {
+  const lines = [import_chalk15.default.bold(s.title)];
+  if (s.body && s.body.length > 0) lines.push(...s.body);
+  if (s.nextActions && s.nextActions.length > 0) {
+    lines.push("   Commands:");
+    for (const c of s.nextActions) lines.push(renderCommand(c));
+  }
+  if (s.commonErrors && s.commonErrors.length > 0) {
+    lines.push("   Avoid:");
+    for (const e of s.commonErrors) lines.push(`     \u2717 ${e}`);
+  }
+  if (s.crossRefs && s.crossRefs.length > 0) {
+    for (const x of s.crossRefs) lines.push(`   \u2192 ${x}`);
+  }
+  return lines.join("\n");
+}
+function modeHeader(mode) {
+  switch (mode.kind) {
+    case "overview":
+      return [
+        "Pick your path:",
+        "   \u2022 Worker (you do tasks, get paid):   heyarp guide --role worker",
+        "   \u2022 Buyer  (you delegate tasks, pay):   heyarp guide --role buyer",
+        "   \u2022 Setup / keys / multi-agent:         heyarp guide --setup",
+        "   \u2022 Common errors \u2192 fixes:              heyarp guide --troubleshoot",
+        ""
+      ];
+    case "role":
+      return [import_chalk15.default.dim(`(${mode.role} guide \u2014 your slice only; run \`heyarp guide\` for the overview)`), ""];
+    case "setup":
+      return [import_chalk15.default.dim("(setup \u2014 role-agnostic; run `heyarp guide` for the overview)"), ""];
+    case "troubleshoot":
+      return [import_chalk15.default.dim("(troubleshooting \u2014 role-agnostic)"), ""];
+  }
+}
+function modeFooter(mode) {
+  if (mode.kind === "overview") {
+    return ["", import_chalk15.default.dim("Full reference per role: `heyarp guide --role worker|buyer`. Docs: https://www.npmjs.com/package/@heyanon-arp/cli")];
+  }
+  return [];
+}
+function renderGuide(mode = { kind: "overview" }) {
+  const blocks = [import_chalk15.default.bold(GUIDE_TITLE), "", ...modeHeader(mode)];
+  for (const s of selectSections(mode)) {
+    blocks.push(renderSection(s), "");
+  }
+  blocks.push(...modeFooter(mode));
+  return blocks.join("\n").replace(/\n+$/, "");
+}
+function renderPrompt(mode, opts = { concise: false }) {
+  if (mode.kind !== "role") {
+    throw new Error(
+      "guide: --format prompt requires --role worker|buyer \u2014 the LLM operating-rules prompt is role-specific (overview/setup/troubleshoot have no IF\u2192THEN rules)."
+    );
+  }
+  const sections = selectSections(mode);
+  const label = mode.role;
+  const out = [];
+  out.push(`# ARP ${label.toUpperCase()} \u2014 operating rules`);
+  out.push(
+    "You act over the ARP protocol using the `heyarp` CLI. Follow these rules exactly; do not invent envelope types or commands. Replace <placeholders> with the real ids from the envelope you are reacting to."
+  );
+  out.push("");
+  const transitions = sections.flatMap((s) => s.transitions ?? []);
+  if (transitions.length > 0) {
+    out.push("## React to each envelope (IF \u2192 THEN)");
+    transitions.forEach((t, i) => out.push(`${i + 1}. IF ${t.when} THEN ${t.then}`));
+    out.push("");
+  }
+  const constraints = sections.flatMap((s) => s.commonErrors ?? []);
+  if (constraints.length > 0) {
+    out.push("## Hard constraints (NEVER violate)");
+    for (const c of constraints) out.push(`- ${c}`);
+    out.push("");
+  }
+  if (!opts.concise) {
+    const refSections = sections.filter((s) => !(s.transitions && s.transitions.length > 0));
+    if (refSections.length > 0) {
+      out.push("## Reference");
+      for (const s of refSections) {
+        out.push(`### ${s.title}`);
+        if (s.body && s.body.length > 0) out.push(...s.body);
+        out.push("");
+      }
+    }
+  }
+  return out.join("\n").replace(/\n+$/, "");
+}
 
 // src/commands/homes.ts
-var import_node_fs6 = require("fs");
-var import_node_path5 = require("path");
-var import_chalk15 = __toESM(require("chalk"));
+var import_node_fs7 = require("fs");
+var import_node_path6 = require("path");
+var import_chalk16 = __toESM(require("chalk"));
 var import_prompts = __toESM(require("prompts"));
 
 // src/homes.ts
-var import_node_fs5 = require("fs");
-var import_node_path4 = require("path");
+var import_node_fs6 = require("fs");
+var import_node_path5 = require("path");
 init_paths();
 var REGISTRY_WARNING = "DO NOT COMMIT \u2014 paths to home dirs may be sensitive (e.g. encrypted-volume mounts).";
 function readRegistry() {
   const path = homesRegistryPath();
-  if (!(0, import_node_fs5.existsSync)(path)) return { homes: [] };
+  if (!(0, import_node_fs6.existsSync)(path)) return { homes: [] };
   let raw;
   try {
-    raw = (0, import_node_fs5.readFileSync)(path, "utf8");
+    raw = (0, import_node_fs6.readFileSync)(path, "utf8");
   } catch (err) {
     throw new Error(`Failed to read homes registry at ${path}: ${err.message}`);
   }
@@ -4607,12 +5169,12 @@ function readRegistry() {
 }
 function writeRegistry(file) {
   const path = homesRegistryPath();
-  const dir = (0, import_node_path4.dirname)(path);
-  if (!(0, import_node_fs5.existsSync)(dir)) (0, import_node_fs5.mkdirSync)(dir, { recursive: true, mode: 448 });
+  const dir = (0, import_node_path5.dirname)(path);
+  if (!(0, import_node_fs6.existsSync)(dir)) (0, import_node_fs6.mkdirSync)(dir, { recursive: true, mode: 448 });
   const body = JSON.stringify({ _warning: REGISTRY_WARNING, homes: file.homes }, null, 2);
-  (0, import_node_fs5.writeFileSync)(path, body, { encoding: "utf8", mode: 384 });
+  (0, import_node_fs6.writeFileSync)(path, body, { encoding: "utf8", mode: 384 });
   try {
-    (0, import_node_fs5.chmodSync)(path, 384);
+    (0, import_node_fs6.chmodSync)(path, 384);
   } catch {
   }
 }
@@ -4640,7 +5202,7 @@ function forgetHome(homePath) {
   return true;
 }
 function homeStillExists(homePath) {
-  return (0, import_node_fs5.existsSync)(`${homePath}/agents.json`);
+  return (0, import_node_fs6.existsSync)(`${homePath}/agents.json`);
 }
 
 // src/commands/homes.ts
@@ -4667,27 +5229,27 @@ function runHomes(opts) {
     return;
   }
   if (rows.length === 0) {
-    console.log(import_chalk15.default.dim("(no HEYARP_HOME directories registered yet \u2014 run `heyarp register` once and the registry populates itself)"));
-    console.log(import_chalk15.default.dim(`   registry path: ${homesRegistryPath()}`));
+    console.log(import_chalk16.default.dim("(no HEYARP_HOME directories registered yet \u2014 run `heyarp register` once and the registry populates itself)"));
+    console.log(import_chalk16.default.dim(`   registry path: ${homesRegistryPath()}`));
     return;
   }
   const header = ["Path", "Agents", "Last seen", "Status"];
   const data = rows.map((r) => [
-    r.path + (r.isCurrent ? import_chalk15.default.green(" (current)") : ""),
+    r.path + (r.isCurrent ? import_chalk16.default.green(" (current)") : ""),
     String(r.agentCount),
     formatRelativeTime(r.lastSeenAt),
-    r.exists ? import_chalk15.default.green("ok") : import_chalk15.default.red("missing")
+    r.exists ? import_chalk16.default.green("ok") : import_chalk16.default.red("missing")
   ]);
   console.log("");
   console.log(formatTable(header, data));
-  console.log(import_chalk15.default.dim(`
+  console.log(import_chalk16.default.dim(`
 Registry path: ${homesRegistryPath()}`));
-  console.log(import_chalk15.default.dim(`Set HEYARP_HOME=<path> in a shell to switch between homes; run \`heyarp homes forget <path>\` to drop a stale entry.`));
+  console.log(import_chalk16.default.dim(`Set HEYARP_HOME=<path> in a shell to switch between homes; run \`heyarp homes forget <path>\` to drop a stale entry.`));
 }
 async function runForget(path, opts) {
   if (!opts.yes) {
-    console.log(import_chalk15.default.yellow(`About to remove '${path}' from the homes registry.`));
-    console.log(import_chalk15.default.dim("   Note: this only forgets the registry entry; the directory + its agents.json are NOT touched."));
+    console.log(import_chalk16.default.yellow(`About to remove '${path}' from the homes registry.`));
+    console.log(import_chalk16.default.dim("   Note: this only forgets the registry entry; the directory + its agents.json are NOT touched."));
     const answer = await (0, import_prompts.default)(
       {
         type: "confirm",
@@ -4697,28 +5259,28 @@ async function runForget(path, opts) {
       },
       {
         onCancel: () => {
-          console.log(import_chalk15.default.yellow("Aborted."));
+          console.log(import_chalk16.default.yellow("Aborted."));
           process.exit(130);
         }
       }
     );
     if (!answer.confirm) {
-      console.log(import_chalk15.default.dim("Aborted (no changes)."));
+      console.log(import_chalk16.default.dim("Aborted (no changes)."));
       return;
     }
   }
   const removed = forgetHome(path);
   if (removed) {
-    console.log(import_chalk15.default.green(`\u2713 forgot ${path}`));
+    console.log(import_chalk16.default.green(`\u2713 forgot ${path}`));
   } else {
-    console.log(import_chalk15.default.dim(`(no entry for ${path} in the registry \u2014 already absent)`));
+    console.log(import_chalk16.default.dim(`(no entry for ${path} in the registry \u2014 already absent)`));
   }
 }
 function countAgents(homePath) {
-  const file = (0, import_node_path5.join)(homePath, "agents.json");
-  if (!(0, import_node_fs6.existsSync)(file)) return 0;
+  const file = (0, import_node_path6.join)(homePath, "agents.json");
+  if (!(0, import_node_fs7.existsSync)(file)) return 0;
   try {
-    const parsed = JSON.parse((0, import_node_fs6.readFileSync)(file, "utf8"));
+    const parsed = JSON.parse((0, import_node_fs7.readFileSync)(file, "utf8"));
     if (!parsed || typeof parsed !== "object" || !parsed.servers) return 0;
     let total = 0;
     for (const server of Object.values(parsed.servers)) {
@@ -4736,13 +5298,13 @@ function formatTable(header, data) {
     const padding = " ".repeat(Math.max(0, widths[i] - lengths[i]));
     return cell + padding;
   }).join("  ");
-  const headerLine = import_chalk15.default.bold(
+  const headerLine = import_chalk16.default.bold(
     pad(
       header,
       header.map((s) => s.length)
     )
   );
-  const sepLine = import_chalk15.default.dim(
+  const sepLine = import_chalk16.default.dim(
     pad(
       widths.map((w) => "-".repeat(w)),
       widths
@@ -4769,7 +5331,7 @@ function formatRelativeTime(iso) {
 }
 
 // src/commands/inbox.ts
-var import_chalk16 = __toESM(require("chalk"));
+var import_chalk17 = __toESM(require("chalk"));
 init_api();
 function formatTailStartedPing(input) {
   const ping = {
@@ -4816,8 +5378,8 @@ async function runInbox(positionalDid, opts) {
   }
   const api = new ArpApiClient(opts.server);
   if (!opts.json) {
-    console.log(import_chalk16.default.dim(`Server: ${api.serverUrl}`));
-    console.log(import_chalk16.default.dim(`Signer: ${local.did}`));
+    console.log(import_chalk17.default.dim(`Server: ${api.serverUrl}`));
+    console.log(import_chalk17.default.dim(`Signer: ${local.did}`));
   }
   const query = { limit };
   if (opts.before) query.before = opts.before;
@@ -4831,7 +5393,7 @@ async function runInbox(positionalDid, opts) {
     return;
   }
   if (events.length === 0) {
-    console.log(import_chalk16.default.dim("\n(no events addressed to me \u2014 `heyarp events <relationship-id>` shows the chain-wide listing)"));
+    console.log(import_chalk17.default.dim("\n(no events addressed to me \u2014 `heyarp events <relationship-id>` shows the chain-wide listing)"));
     return;
   }
   console.log("");
@@ -4846,16 +5408,16 @@ async function runInbox(positionalDid, opts) {
       secondary: `eventId=${ev.eventId} serverEventHash=${ev.serverEventHash}`
     }));
   }
-  const addressedToMeHint = import_chalk16.default.dim(" (envelopes addressed to me \u2014 for the full chain see `heyarp events <relationship-id>`)");
+  const addressedToMeHint = import_chalk17.default.dim(" (envelopes addressed to me \u2014 for the full chain see `heyarp events <relationship-id>`)");
   if (opts.since && !opts.before) {
     console.log(
-      import_chalk16.default.dim(
+      import_chalk17.default.dim(
         `
 ${events.length} event(s) (oldest-first).${addressedToMeHint} Advance the forward cursor with --since <serverTimestamp> --since-event-id <eventId> using the LAST row above.`
       )
     );
   } else {
-    console.log(import_chalk16.default.dim(`
+    console.log(import_chalk17.default.dim(`
 ${events.length} event(s).${addressedToMeHint} Paginate with --before <serverTimestamp> --before-event-id <eventId> using the LAST row above.`));
   }
 }
@@ -4868,8 +5430,9 @@ async function runInboxTail(did, local, opts) {
       setBlocking.call(handle, true);
       stdoutBlockingApplied = true;
     } else {
-      console.error(
-        import_chalk16.default.yellow(
+      warn(
+        opts.json,
+        import_chalk17.default.yellow(
           "\u26A0 inbox --tail: stdout is piped but `process.stdout._handle.setBlocking` is unavailable in this Node runtime. Buffered writes may delay event delivery. Fall back to polling (`heyarp inbox --json`) if events stop arriving."
         )
       );
@@ -4879,9 +5442,9 @@ async function runInboxTail(did, local, opts) {
   if (opts.json) {
     console.log(formatTailStartedPing({ server: api.serverUrl, signer: local.did, stdoutBlockingApplied }));
   } else {
-    console.log(import_chalk16.default.dim(`Server: ${api.serverUrl}`));
-    console.log(import_chalk16.default.dim(`Signer: ${local.did}`));
-    console.log(import_chalk16.default.dim("Mode: --tail (live SSE, Ctrl-C to stop)"));
+    console.log(import_chalk17.default.dim(`Server: ${api.serverUrl}`));
+    console.log(import_chalk17.default.dim(`Signer: ${local.did}`));
+    console.log(import_chalk17.default.dim("Mode: --tail (live SSE, Ctrl-C to stop)"));
   }
   const controller = new AbortController();
   let userAborted = false;
@@ -4900,7 +5463,7 @@ async function runInboxTail(did, local, opts) {
       }
       if (event.type === "heartbeat") continue;
       if (event.type === "connected") {
-        console.log(import_chalk16.default.green("\u25CF stream open \u2014 listening for envelopes..."));
+        console.log(import_chalk17.default.green("\u25CF stream open \u2014 listening for envelopes..."));
         continue;
       }
       if (event.type === "envelope") {
@@ -4914,7 +5477,7 @@ async function runInboxTail(did, local, opts) {
         }
         continue;
       }
-      console.log(import_chalk16.default.dim(`(unknown event: ${event.type})`));
+      console.log(import_chalk17.default.dim(`(unknown event: ${event.type})`));
     }
     if (!userAborted) {
       throw new Error("inbox --tail: stream ended unexpectedly (server may have restarted, or change stream errored). Re-run to reconnect.");
@@ -4922,7 +5485,7 @@ async function runInboxTail(did, local, opts) {
   } catch (err) {
     const name = err.name;
     if (name === "AbortError" || userAborted) {
-      if (!opts.json) console.log(import_chalk16.default.dim("\nstream closed."));
+      if (!opts.json) console.log(import_chalk17.default.dim("\nstream closed."));
       return;
     }
     throw err;
@@ -4942,15 +5505,15 @@ function formatInboxTable(events, opts = {}) {
   ]);
   const widths = header.map((h, i) => Math.max(h.length, ...data.map((row) => row[i].length)));
   const pad = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ");
-  const lines = [import_chalk16.default.bold(pad(header)), import_chalk16.default.dim(pad(widths.map((w) => "-".repeat(w)))), ...data.map((row) => pad(row))];
-  const detail = events.map((ev) => `  ${import_chalk16.default.dim("eventId:")} ${import_chalk16.default.cyan(ev.eventId)}  ${import_chalk16.default.dim("serverTimestamp:")} ${import_chalk16.default.cyan(ev.serverTimestamp)}`).join("\n");
+  const lines = [import_chalk17.default.bold(pad(header)), import_chalk17.default.dim(pad(widths.map((w) => "-".repeat(w)))), ...data.map((row) => pad(row))];
+  const detail = events.map((ev) => `  ${import_chalk17.default.dim("eventId:")} ${import_chalk17.default.cyan(ev.eventId)}  ${import_chalk17.default.dim("serverTimestamp:")} ${import_chalk17.default.cyan(ev.serverTimestamp)}`).join("\n");
   return `${lines.join("\n")}
 
-${import_chalk16.default.bold("Pagination cursors")} (last \u2192 first):
+${import_chalk17.default.bold("Pagination cursors")} (last \u2192 first):
 ${detail}`;
 }
 function hashHead2(hash) {
-  if (!hash) return import_chalk16.default.dim("(none)");
+  if (!hash) return import_chalk17.default.dim("(none)");
   if (hash.length <= 14) return hash;
   return `${hash.slice(0, 14)}...`;
 }
@@ -4965,35 +5528,35 @@ function parseLimit5(raw) {
 
 // src/commands/keys.ts
 var import_sdk9 = require("@heyanon-arp/sdk");
-var import_chalk17 = __toESM(require("chalk"));
+var import_chalk18 = __toESM(require("chalk"));
 function registerKeysCommand(root) {
   const keys = root.command("keys").description("Local key utilities");
   keys.command("gen").description("Generate a fresh identity + settlement keypair (no save by default)").option("--save", "Reserved for future scratch-key storage; currently a no-op with a notice", false).action((opts) => {
     const identity = (0, import_sdk9.generateKeyPair)();
     const settlement = (0, import_sdk9.generateKeyPair)();
     const out = [
-      import_chalk17.default.bold("Identity key (Ed25519)"),
-      `  public  (base58btc): ${import_chalk17.default.cyan((0, import_sdk9.base58btcEncode)(identity.publicKey))}`,
-      `  secret  (base64)   : ${import_chalk17.default.yellow(Buffer.from(identity.secretKey).toString("base64"))}`,
+      import_chalk18.default.bold("Identity key (Ed25519)"),
+      `  public  (base58btc): ${import_chalk18.default.cyan((0, import_sdk9.base58btcEncode)(identity.publicKey))}`,
+      `  secret  (base64)   : ${import_chalk18.default.yellow(Buffer.from(identity.secretKey).toString("base64"))}`,
       "",
-      import_chalk17.default.bold("Settlement key (Ed25519)"),
-      `  public  (base58btc): ${import_chalk17.default.cyan((0, import_sdk9.base58btcEncode)(settlement.publicKey))}`,
-      `  secret  (base64)   : ${import_chalk17.default.yellow(Buffer.from(settlement.secretKey).toString("base64"))}`,
+      import_chalk18.default.bold("Settlement key (Ed25519)"),
+      `  public  (base58btc): ${import_chalk18.default.cyan((0, import_sdk9.base58btcEncode)(settlement.publicKey))}`,
+      `  secret  (base64)   : ${import_chalk18.default.yellow(Buffer.from(settlement.secretKey).toString("base64"))}`,
       "",
-      import_chalk17.default.bold("Resulting DID"),
-      `  ${import_chalk17.default.cyan((0, import_sdk9.formatDid)(identity.publicKey))}`
+      import_chalk18.default.bold("Resulting DID"),
+      `  ${import_chalk18.default.cyan((0, import_sdk9.formatDid)(identity.publicKey))}`
     ];
     console.log(out.join("\n"));
     if (opts.save) {
-      console.log(import_chalk17.default.yellow("\nNote: --save is not yet implemented. Capture the secret keys above before they scroll off-screen."));
+      console.log(import_chalk18.default.yellow("\nNote: --save is not yet implemented. Capture the secret keys above before they scroll off-screen."));
     }
   });
   keys.command("whoami").description("Print the DID derived from a base64-encoded identity secret key").argument("<secret-key-b64>", "32-byte Ed25519 seed, base64").action((secretKeyB64) => {
     const seed = decodeSeed(secretKeyB64);
     const pub = (0, import_sdk9.getPublicKey)(seed);
     const did = (0, import_sdk9.formatDid)(pub);
-    console.log(`${import_chalk17.default.bold("DID")}: ${import_chalk17.default.cyan(did)}`);
-    console.log(`${import_chalk17.default.bold("Identity public key (base58btc)")}: ${import_chalk17.default.cyan((0, import_sdk9.base58btcEncode)(pub))}`);
+    console.log(`${import_chalk18.default.bold("DID")}: ${import_chalk18.default.cyan(did)}`);
+    console.log(`${import_chalk18.default.bold("Identity public key (base58btc)")}: ${import_chalk18.default.cyan((0, import_sdk9.base58btcEncode)(pub))}`);
   });
 }
 function decodeSeed(b64) {
@@ -5010,12 +5573,12 @@ function decodeSeed(b64) {
 }
 
 // src/commands/list.ts
-var import_chalk18 = __toESM(require("chalk"));
+var import_chalk19 = __toESM(require("chalk"));
 function registerListCommand(root) {
   root.command("list").description("List agents registered locally (~/.arp/agents.json)").action(() => {
     const rows = listAgents();
     if (rows.length === 0) {
-      console.log(import_chalk18.default.dim(`No local agents. State file: ${stateFilePath()}`));
+      console.log(import_chalk19.default.dim(`No local agents. State file: ${stateFilePath()}`));
       return;
     }
     const grouped = /* @__PURE__ */ new Map();
@@ -5027,7 +5590,7 @@ function registerListCommand(root) {
     for (const [serverUrl, group] of grouped) {
       if (!first) console.log("");
       first = false;
-      console.log(import_chalk18.default.bold(`Server: ${serverUrl}`));
+      console.log(import_chalk19.default.bold(`Server: ${serverUrl}`));
       console.log(formatAgentsTable(group.map(({ agent }) => ({ did: agent.did, name: agent.name, tags: agent.tags, registeredAt: agent.registeredAt }))));
     }
   });
@@ -5035,7 +5598,7 @@ function registerListCommand(root) {
 
 // src/commands/memory.ts
 var import_sdk10 = require("@heyanon-arp/sdk");
-var import_chalk19 = __toESM(require("chalk"));
+var import_chalk20 = __toESM(require("chalk"));
 init_api();
 function registerMemoryCommands(root) {
   const cmd = root.command("memory").description("Memory deltas: write, list, fetch one.");
@@ -5088,7 +5651,7 @@ function parseAddOptions(cmdName, opts) {
     throw new Error(`${cmdName}: --commit-after=${commitAfter} requires --delegation-id <uuid> (the delegation whose settlement gates the commit).`);
   }
   if (commitAfter === "immediate" && opts.delegationId !== void 0) {
-    console.error(import_chalk19.default.yellow(`${cmdName}: --delegation-id is set but --commit-after=immediate; the delegation_id will be persisted but not used as a settlement gate.`));
+    console.error(import_chalk20.default.yellow(`${cmdName}: --delegation-id is set but --commit-after=immediate; the delegation_id will be persisted but not used as a settlement gate.`));
   }
   const out = {
     kind: opts.kind,
@@ -5123,13 +5686,13 @@ async function runAdd(recipientDid, opts) {
     server: opts.server
   });
   if (opts.verbose) {
-    console.log(import_chalk19.default.bold("\nServer response:"));
+    console.log(import_chalk20.default.bold("\nServer response:"));
     console.log(formatJson(result));
   }
-  console.log(import_chalk19.default.green(`
+  console.log(import_chalk20.default.green(`
 memory_delta event ${result.eventId} accepted (commit_after=${bodyContent.commit_after ?? "immediate"})`));
-  console.log(import_chalk19.default.dim(`relationshipId: ${result.relationshipId}`));
-  console.log(import_chalk19.default.dim(`serverEventHash: ${result.serverEventHash}`));
+  console.log(import_chalk20.default.dim(`relationshipId: ${result.relationshipId}`));
+  console.log(import_chalk20.default.dim(`serverEventHash: ${result.serverEventHash}`));
 }
 async function sendMemoryEnvelope(args) {
   const nextSequence = (args.sender.lastSenderSequence ?? 0) + 1;
@@ -5153,7 +5716,7 @@ async function sendMemoryEnvelope(args) {
     identitySecretKey: signer.identitySecretKey
   });
   if (args.verbose) {
-    console.log(import_chalk19.default.bold("\nEnvelope (pre-send):"));
+    console.log(import_chalk20.default.bold("\nEnvelope (pre-send):"));
     console.log(formatJson(envelope));
   }
   try {
@@ -5189,7 +5752,7 @@ async function runList(relationshipId, opts) {
     return;
   }
   if (rows.length === 0) {
-    console.log(import_chalk19.default.dim("(no memory entries)"));
+    console.log(import_chalk20.default.dim("(no memory entries)"));
     return;
   }
   for (const r of rows) {
@@ -5197,7 +5760,7 @@ async function runList(relationshipId, opts) {
   }
   if (rows.length === limitN) {
     const lastId = rows[rows.length - 1].id;
-    console.log(import_chalk19.default.dim(`
+    console.log(import_chalk20.default.dim(`
 Page may not be complete \u2014 paginate with --after ${lastId}`));
   }
 }
@@ -5205,9 +5768,9 @@ function formatMemoryLine(r) {
   const idHead5 = `${r.id.slice(0, 8)}...${r.id.slice(-4)}`;
   const authorTail = r.authorDid.length > 20 ? `${r.authorDid.slice(0, 14)}...${r.authorDid.slice(-4)}` : r.authorDid;
   const contentPreview = r.content.length > 60 ? `${r.content.slice(0, 57)}...` : r.content;
-  const cosignedTag = r.isCosigned ? import_chalk19.default.yellow(" (cosigned)") : "";
-  const gatedTag = r.delegationId ? import_chalk19.default.cyan(" (settlement-gated)") : "";
-  return `${import_chalk19.default.dim(idHead5)} | ${import_chalk19.default.magenta(r.kind)} | ${import_chalk19.default.dim(r.scope)} | ${import_chalk19.default.dim(authorTail)} | ${import_chalk19.default.cyan(`"${contentPreview}"`)}${cosignedTag}${gatedTag}`;
+  const cosignedTag = r.isCosigned ? import_chalk20.default.yellow(" (cosigned)") : "";
+  const gatedTag = r.delegationId ? import_chalk20.default.cyan(" (settlement-gated)") : "";
+  return `${import_chalk20.default.dim(idHead5)} | ${import_chalk20.default.magenta(r.kind)} | ${import_chalk20.default.dim(r.scope)} | ${import_chalk20.default.dim(authorTail)} | ${import_chalk20.default.cyan(`"${contentPreview}"`)}${cosignedTag}${gatedTag}`;
 }
 function registerShow(parent) {
   parent.command("show").description("Fetch one memory entry by its server `_id`.").argument(
@@ -5226,18 +5789,18 @@ async function runShow(entryId, opts) {
     console.log(JSON.stringify(row));
     return;
   }
-  console.log(import_chalk19.default.bold("Memory entry:"));
+  console.log(import_chalk20.default.bold("Memory entry:"));
   console.log(formatJson(row));
   console.log("");
-  console.log(`${import_chalk19.default.dim("id:")}             ${import_chalk19.default.cyan(row.id)}`);
-  console.log(`${import_chalk19.default.dim("relationshipId:")} ${import_chalk19.default.cyan(row.relationshipId)}`);
-  console.log(`${import_chalk19.default.dim("authorDid:")}      ${import_chalk19.default.cyan(row.authorDid)}`);
-  console.log(`${import_chalk19.default.dim("kind / scope:")}   ${import_chalk19.default.cyan(`${row.kind} / ${row.scope}`)}`);
+  console.log(`${import_chalk20.default.dim("id:")}             ${import_chalk20.default.cyan(row.id)}`);
+  console.log(`${import_chalk20.default.dim("relationshipId:")} ${import_chalk20.default.cyan(row.relationshipId)}`);
+  console.log(`${import_chalk20.default.dim("authorDid:")}      ${import_chalk20.default.cyan(row.authorDid)}`);
+  console.log(`${import_chalk20.default.dim("kind / scope:")}   ${import_chalk20.default.cyan(`${row.kind} / ${row.scope}`)}`);
   if (row.delegationId) {
-    console.log(`${import_chalk19.default.dim("delegationId:")}   ${import_chalk19.default.cyan(row.delegationId)} (settlement-gated)`);
+    console.log(`${import_chalk20.default.dim("delegationId:")}   ${import_chalk20.default.cyan(row.delegationId)} (settlement-gated)`);
   }
   if (row.supersedesId) {
-    console.log(`${import_chalk19.default.dim("supersedes:")}     ${import_chalk19.default.cyan(row.supersedesId)}`);
+    console.log(`${import_chalk20.default.dim("supersedes:")}     ${import_chalk20.default.cyan(row.supersedesId)}`);
   }
 }
 function parseTtl3(cmdName, raw) {
@@ -5264,9 +5827,9 @@ function parseLimit6(cmdName, raw) {
 }
 
 // src/commands/receipt.ts
-var import_node_fs7 = require("fs");
+var import_node_fs8 = require("fs");
 var import_sdk11 = require("@heyanon-arp/sdk");
-var import_chalk20 = __toESM(require("chalk"));
+var import_chalk21 = __toESM(require("chalk"));
 init_api();
 function registerReceiptCommands(root) {
   const cmd = root.command("receipt").description("Receipt envelopes \u2014 payee proposes, caller cosigns");
@@ -5286,6 +5849,15 @@ var POST_COMMIT_ERROR_CODES4 = /* @__PURE__ */ new Set([
   "RECEIPT_COSIGN_AGENT_MISMATCH",
   "RECEIPT_COSIGN_PURPOSE_INVALID",
   "RECEIPT_COSIGN_INVALID",
+  // response_hash / request_hash / deliverable_hash content
+  // verification. Server commits the receipt envelope row BEFORE
+  // running the canonical-hash lookup, so a rejection here still
+  // consumes the sender sequence — must be in the allowlist or
+  // a retry after fixing the hashes would trip
+  // `ENV_SEQUENCE_BACKWARDS`.
+  "RECEIPT_RESPONSE_HASH_NOT_FOUND",
+  "RECEIPT_REQUEST_HASH_NOT_FOUND",
+  "RECEIPT_DELIVERABLE_HASH_MISMATCH",
   // Settlement-side rejections from the receipt cosign path.
   // Receipt-handler invokes
   // `ReceiptCosignValidatorService.enqueueReleaseOp` AFTER the
@@ -5366,16 +5938,25 @@ function registerPropose2(parent) {
   ).option(
     "--request-id <r>",
     'work_request id (the same value you passed to `heyarp work request --request-id`). Required when --auto-hashes is set AND the delegation has >1 outstanding "responded" work_log. When omitted, the CLI auto-resolves to the unique responded work_log.'
-  ).option("--verbose", "Print the full envelope before sending and the full server response", false).action(async (recipientDid, delegationId, requestHash, responseHash, opts, cmd) => {
+  ).option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    "Machine-readable mode \u2014 emit a single JSON object to stdout with `{receiptEventHash, delegationId, requestHash, responseHash, deliverableHash?, notesHash?, verdictProposed, usage?, eventId, relationshipId, relationshipEventIndex, serverTimestamp}`. Prelude + auto-resolution hints + cosign-next-step hint move to stderr. Pipe-safe: `heyarp receipt propose ... --json | jq` returns parseable JSON. Mutually exclusive with --verbose.",
+    false
+  ).action(async (recipientDid, delegationId, requestHash, responseHash, opts, cmd) => {
     try {
       await runPropose2(recipientDid, delegationId, requestHash, responseHash, opts);
     } catch (err) {
-      console.error(formatActionError(err, cmd));
+      emitActionError(err, cmd);
       process.exitCode = 1;
     }
   });
 }
 async function runPropose2(recipientDid, delegationId, requestHashArg, responseHashArg, opts) {
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      "receipt propose: --verbose and --json are mutually exclusive. --json already emits the full server response as a structured payload; --verbose adds an envelope + response dump on top that would break `--json | jq`."
+    );
+  }
   requireDid3("receipt propose", recipientDid, "<recipient-did>");
   delegationId = requireUuidNormalised2("receipt propose", delegationId, "<delegation-id>");
   if (opts.relId) opts.relId = requireUuidNormalised2("receipt propose", opts.relId, "--rel-id");
@@ -5388,7 +5969,10 @@ async function runPropose2(recipientDid, delegationId, requestHashArg, responseH
   const sender = resolveSenderAgent("receipt propose", opts.server, opts.fromDid);
   if (opts.autoHashes && !opts.relId) {
     opts.relId = await resolveAutoRelId(api, sender, delegationId);
-    console.log(import_chalk20.default.dim(`[auto-rel-id] resolved --rel-id=${opts.relId} (delegation found in exactly one of your relationships; pass --rel-id explicitly to override)`));
+    progress(
+      opts.json,
+      import_chalk21.default.dim(`[auto-rel-id] resolved --rel-id=${opts.relId} (delegation found in exactly one of your relationships; pass --rel-id explicitly to override)`)
+    );
   }
   if (opts.relId) {
     await assertSenderIsReceiptPayee(api, sender, opts.relId, delegationId);
@@ -5401,8 +5985,9 @@ async function runPropose2(recipientDid, delegationId, requestHashArg, responseH
     }
     if (!opts.requestId) {
       opts.requestId = await resolveAutoRequestId(api, sender, opts.relId, delegationId);
-      console.log(
-        import_chalk20.default.dim(
+      progress(
+        opts.json,
+        import_chalk21.default.dim(
           `[auto-request-id] resolved --request-id=${opts.requestId} (unique 'responded' work_log under this delegation; pass --request-id explicitly to override)`
         )
       );
@@ -5421,8 +6006,8 @@ async function runPropose2(recipientDid, delegationId, requestHashArg, responseH
     }
     requestHash = computed.requestHash;
     responseHash = computed.responseHash;
-    console.log(import_chalk20.default.dim(`[auto-hashes] request_hash:  ${requestHash} (from work-log ${opts.relId}/${delegationId}/${opts.requestId})`));
-    console.log(import_chalk20.default.dim(`[auto-hashes] response_hash: ${responseHash}`));
+    progress(opts.json, import_chalk21.default.dim(`[auto-hashes] request_hash:  ${requestHash} (from work-log ${opts.relId}/${delegationId}/${opts.requestId})`));
+    progress(opts.json, import_chalk21.default.dim(`[auto-hashes] response_hash: ${responseHash}`));
   } else {
     if (requestHashArg === void 0 || responseHashArg === void 0) {
       throw new Error("receipt propose: <request-hash> and <response-hash> are required (or pass --auto-hashes + --rel-id + --request-id to derive them from the work-log)");
@@ -5442,17 +6027,35 @@ async function runPropose2(recipientDid, delegationId, requestHashArg, responseH
   if (opts.deliverableHash) content.deliverable_hash = opts.deliverableHash;
   if (usage) content.usage = usage;
   const body = { type: "receipt", content };
-  console.log(import_chalk20.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk20.default.dim(`Sender (payee): ${sender.did}`));
-  console.log(import_chalk20.default.dim(`Recipient (caller): ${recipientDid}`));
-  console.log(import_chalk20.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk20.default.dim(`Verdict (proposed): ${verdict}`));
+  progress(opts.json, import_chalk21.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk21.default.dim(`Sender (payee): ${sender.did}`));
+  progress(opts.json, import_chalk21.default.dim(`Recipient (caller): ${recipientDid}`));
+  progress(opts.json, import_chalk21.default.dim(`Delegation: ${delegationId}`));
+  progress(opts.json, import_chalk21.default.dim(`Verdict (proposed): ${verdict}`));
   const result = await sendReceiptEnvelope({ api, sender, recipientDid, body, attachments: void 0, ttlSeconds, verbose: opts.verbose, server: opts.server });
+  if (opts.json) {
+    const json = {
+      receiptEventHash: result.serverEventHash,
+      delegationId,
+      requestHash,
+      responseHash,
+      verdictProposed: verdict,
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp
+    };
+    if (content.deliverable_hash) json.deliverableHash = content.deliverable_hash;
+    if (content.notes_hash) json.notesHash = content.notes_hash;
+    if (content.usage) json.usage = content.usage;
+    jsonOut(json);
+    return;
+  }
   printIngestResult3(result);
-  console.log(import_chalk20.default.dim(`
-Receipt event hash: ${import_chalk20.default.cyan(result.serverEventHash)}`));
-  console.log(import_chalk20.default.dim(`The caller cosigns with:`));
-  console.log(import_chalk20.default.dim(`  heyarp receipt cosign ${result.relationshipId} ${delegationId} ${requestHash} ${responseHash} --verdict ${verdict}`));
+  console.log(import_chalk21.default.dim(`
+Receipt event hash: ${import_chalk21.default.cyan(result.serverEventHash)}`));
+  console.log(import_chalk21.default.dim(`The caller cosigns with:`));
+  console.log(import_chalk21.default.dim(`  heyarp receipt cosign ${result.relationshipId} ${delegationId} ${requestHash} ${responseHash} --verdict ${verdict}`));
 }
 async function assertSenderIsReceiptPayee(api, sender, relationshipId, delegationId) {
   const signer = makeSigner(sender);
@@ -5590,7 +6193,7 @@ function registerCosign(parent) {
       try {
         await runCosign(relationshipId, delegationId, requestHashArg, responseHashArg, opts);
       } catch (err) {
-        console.error(formatActionError(err, cmd));
+        emitActionError(err, cmd);
         process.exitCode = 1;
       }
     }
@@ -5599,7 +6202,7 @@ function registerCosign(parent) {
 function loadSettlementSigFromFile(path, flagPrefix) {
   let raw;
   try {
-    raw = (0, import_node_fs7.readFileSync)(path, "utf8");
+    raw = (0, import_node_fs8.readFileSync)(path, "utf8");
   } catch (err) {
     throw new Error(`receipt cosign: failed to read ${flagPrefix} '${path}': ${err.message}`);
   }
@@ -5846,28 +6449,28 @@ async function runCosign(relationshipId, delegationId, requestHashArg, responseH
     content.notes_hash = cosignNotesHash;
   }
   const body = { type: "receipt", content };
-  console.log(import_chalk20.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk20.default.dim(`Sender (caller): ${sender.did}`));
-  console.log(import_chalk20.default.dim(`Recipient (payee): ${resolved.payeeDid}`));
-  console.log(import_chalk20.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk20.default.dim(`Verdict (final): ${verdict}`));
-  console.log(import_chalk20.default.dim(`Receipt event hash bound: ${resolved.receiptEventHash}`));
+  console.log(import_chalk21.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk21.default.dim(`Sender (caller): ${sender.did}`));
+  console.log(import_chalk21.default.dim(`Recipient (payee): ${resolved.payeeDid}`));
+  console.log(import_chalk21.default.dim(`Delegation: ${delegationId}`));
+  console.log(import_chalk21.default.dim(`Verdict (final): ${verdict}`));
+  console.log(import_chalk21.default.dim(`Receipt event hash bound: ${resolved.receiptEventHash}`));
   if (cosignNotesHash !== null) {
-    console.log(import_chalk20.default.dim(`Notes hash bound: ${cosignNotesHash}`));
+    console.log(import_chalk21.default.dim(`Notes hash bound: ${cosignNotesHash}`));
   } else if (opts.clearNotes) {
-    console.log(import_chalk20.default.dim("Notes binding: cleared (--clear-notes)"));
+    console.log(import_chalk21.default.dim("Notes binding: cleared (--clear-notes)"));
   }
   if (opts.autoResolvePayeeSig) {
     applyAutoResolvePayeeSig("receipt cosign", opts, resolved.payeeSettlement);
     console.log(
-      import_chalk20.default.dim(`Auto-resolved payee sig from receipt.payeeSettlement (purpose=${resolved.payeeSettlement?.purpose}, expires_at=${resolved.payeeSettlement?.expires_at})`)
+      import_chalk21.default.dim(`Auto-resolved payee sig from receipt.payeeSettlement (purpose=${resolved.payeeSettlement?.purpose}, expires_at=${resolved.payeeSettlement?.expires_at})`)
     );
   }
   const settlementSigs = assembleSettlementSignaturesAttachment(opts);
   const attachments = { co_signature: cosignature };
   if (settlementSigs) {
     attachments.settlement_signatures = settlementSigs;
-    console.log(import_chalk20.default.dim(`Settlement signatures attached: purpose=${settlementSigs.purpose}`));
+    console.log(import_chalk21.default.dim(`Settlement signatures attached: purpose=${settlementSigs.purpose}`));
   }
   const result = await sendReceiptEnvelope({
     api,
@@ -5899,9 +6502,7 @@ async function runCosign(relationshipId, delegationId, requestHashArg, responseH
   }
 }
 function registerSendPayeeSig(parent) {
-  parent.command("send-payee-sig").description(
-    "Send the payee's settlement signature to the buyer via a settlement_signature envelope. Replaces /tmp/*.json coordination for cross-host escrow cycles."
-  ).argument("<recipient-did>", "Buyer DID (= caller / offerer of the parent delegation; the cycle sends the sig to the side that will cosign)").requiredOption("--delegation-id <id>", "Parent delegation UUID \u2014 must match what was passed to `heyarp wallet sign-settlement-release`.").requiredOption(
+  parent.command("send-payee-sig").description("Send the payee's settlement signature to the buyer via a settlement_signature envelope. Replaces /tmp/*.json coordination for cross-host escrow cycles.").argument("<recipient-did>", "Buyer DID (= caller / offerer of the parent delegation; the cycle sends the sig to the side that will cosign)").requiredOption("--delegation-id <id>", "Parent delegation UUID \u2014 must match what was passed to `heyarp wallet sign-settlement-release`.").requiredOption(
     "--receipt-event-hash <sha256:hex>",
     "Server-assigned `serverEventHash` of the receipt-propose envelope this signature settles. Read it from the JSON response of `heyarp receipt propose` (the field is `Server event hash` in human output, or `.serverEventHash` in --json). MUST equal the value the digest was signed over \u2014 the server cross-checks against `Receipt.receiptEventHash` and rejects with SETTLEMENT_SIG_RECEIPT_NOT_FOUND otherwise."
   ).requiredOption(
@@ -5917,7 +6518,7 @@ function registerSendPayeeSig(parent) {
     try {
       await runSendPayeeSig(recipientDid, opts);
     } catch (err) {
-      console.error(formatActionError(err, cmd));
+      emitActionError(err, cmd);
       process.exitCode = 1;
     }
   });
@@ -5966,17 +6567,17 @@ async function runSendPayeeSig(recipientDid, opts) {
     expires_at: expiresAtSeconds,
     ...isPartial ? { payee_amount: opts.payeeAmount } : {}
   };
-  console.log(import_chalk20.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk20.default.dim(`Sender (payee): ${sender.did}`));
-  console.log(import_chalk20.default.dim(`Recipient (buyer): ${recipientDid}`));
-  console.log(import_chalk20.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk20.default.dim(`Receipt event hash: ${opts.receiptEventHash}`));
-  console.log(import_chalk20.default.dim(`Purpose: ${sigFile.purpose}`));
+  console.log(import_chalk21.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk21.default.dim(`Sender (payee): ${sender.did}`));
+  console.log(import_chalk21.default.dim(`Recipient (buyer): ${recipientDid}`));
+  console.log(import_chalk21.default.dim(`Delegation: ${delegationId}`));
+  console.log(import_chalk21.default.dim(`Receipt event hash: ${opts.receiptEventHash}`));
+  console.log(import_chalk21.default.dim(`Purpose: ${sigFile.purpose}`));
   if (isPartial) {
-    console.log(import_chalk20.default.dim(`Payee amount: ${opts.payeeAmount}`));
+    console.log(import_chalk21.default.dim(`Payee amount: ${opts.payeeAmount}`));
   }
-  console.log(import_chalk20.default.dim(`Settlement pubkey: ${sigFile.settlement_pubkey}`));
-  console.log(import_chalk20.default.dim(`Expires at: ${expiresAtSeconds}`));
+  console.log(import_chalk21.default.dim(`Settlement pubkey: ${sigFile.settlement_pubkey}`));
+  console.log(import_chalk21.default.dim(`Expires at: ${expiresAtSeconds}`));
   const result = await sendSettlementSignatureEnvelope({
     api,
     sender,
@@ -6010,7 +6611,7 @@ async function sendSettlementSignatureEnvelope(args) {
     identitySecretKey: signer.identitySecretKey
   });
   if (args.verbose) {
-    console.log(import_chalk20.default.bold("\nEnvelope (pre-send):"));
+    console.log(import_chalk21.default.bold("\nEnvelope (pre-send):"));
     console.log(formatJson(envelope));
   }
   try {
@@ -6047,7 +6648,7 @@ async function sendReceiptEnvelope(args) {
     attachments: args.attachments
   });
   if (args.verbose) {
-    console.log(import_chalk20.default.bold("\nEnvelope (pre-send):"));
+    console.log(import_chalk21.default.bold("\nEnvelope (pre-send):"));
     console.log(formatJson(envelope));
   }
   try {
@@ -6106,12 +6707,12 @@ async function resolveCosignTargets(cmdName, api, signer, args) {
   };
 }
 function printIngestResult3(result) {
-  console.log(import_chalk20.default.green("\nDelivered."));
-  console.log(`${import_chalk20.default.bold("Event id")}: ${import_chalk20.default.cyan(result.eventId)}`);
-  console.log(`${import_chalk20.default.bold("Relationship id")}: ${import_chalk20.default.cyan(result.relationshipId)}`);
-  console.log(`${import_chalk20.default.bold("Chain index")}: ${import_chalk20.default.cyan(String(result.relationshipEventIndex))}`);
-  console.log(`${import_chalk20.default.bold("Server timestamp")}: ${import_chalk20.default.cyan(result.serverTimestamp)}`);
-  console.log(`${import_chalk20.default.bold("Server event hash")}: ${import_chalk20.default.cyan(result.serverEventHash)}`);
+  console.log(import_chalk21.default.green("\nDelivered."));
+  console.log(`${import_chalk21.default.bold("Event id")}: ${import_chalk21.default.cyan(result.eventId)}`);
+  console.log(`${import_chalk21.default.bold("Relationship id")}: ${import_chalk21.default.cyan(result.relationshipId)}`);
+  console.log(`${import_chalk21.default.bold("Chain index")}: ${import_chalk21.default.cyan(String(result.relationshipEventIndex))}`);
+  console.log(`${import_chalk21.default.bold("Server timestamp")}: ${import_chalk21.default.cyan(result.serverTimestamp)}`);
+  console.log(`${import_chalk21.default.bold("Server event hash")}: ${import_chalk21.default.cyan(result.serverEventHash)}`);
 }
 function parseVerdict(cmdName, raw) {
   if (raw === void 0 || raw === "") return "accepted";
@@ -6164,7 +6765,7 @@ function requireDid3(cmdName, did, label) {
 }
 
 // src/commands/receipts.ts
-var import_chalk21 = __toESM(require("chalk"));
+var import_chalk22 = __toESM(require("chalk"));
 init_api();
 var ALLOWED_STATES3 = /* @__PURE__ */ new Set(["proposed", "cosigned"]);
 function registerReceiptsCommand(root) {
@@ -6193,9 +6794,9 @@ async function runReceipts(relationshipId, opts) {
   const api = new ArpApiClient(opts.server);
   const sender = resolveSenderAgent("receipts", opts.server, opts.fromDid);
   if (!opts.json) {
-    console.log(import_chalk21.default.dim(`Server: ${api.serverUrl}`));
-    console.log(import_chalk21.default.dim(`Signer: ${sender.did}`));
-    console.log(import_chalk21.default.dim(`Relationship: ${relationshipId}`));
+    console.log(import_chalk22.default.dim(`Server: ${api.serverUrl}`));
+    console.log(import_chalk22.default.dim(`Signer: ${sender.did}`));
+    console.log(import_chalk22.default.dim(`Relationship: ${relationshipId}`));
   }
   const query = { limit };
   if (state) query.state = state;
@@ -6208,7 +6809,7 @@ async function runReceipts(relationshipId, opts) {
     return;
   }
   if (rows.length === 0) {
-    console.log(import_chalk21.default.dim("\n(no receipts for this relationship)"));
+    console.log(import_chalk22.default.dim("\n(no receipts for this relationship)"));
     return;
   }
   console.log("");
@@ -6226,28 +6827,28 @@ async function runReceipts(relationshipId, opts) {
     }));
   }
   const lastId = rows[rows.length - 1].id;
-  console.log(import_chalk21.default.dim(`
+  console.log(import_chalk22.default.dim(`
 ${rows.length} receipt row(s). Paginate with --after ${lastId}.`));
 }
 function formatReceiptLine(r, selfDid, opts = {}) {
   const delegationPart = opts.fullIds ? r.delegationId : idHead3(r.delegationId);
   const requestHashPart = opts.fullIds ? r.requestHash : hashHead3(r.requestHash);
-  const id = import_chalk21.default.bold(`${delegationPart}/${requestHashPart}`);
+  const id = import_chalk22.default.bold(`${delegationPart}/${requestHashPart}`);
   const state = colorState3(r.state).padEnd(stateColumnWidth3());
   const callerHead = opts.fullIds ? r.callerDid : didHead4(r.callerDid);
   const payeeHead = opts.fullIds ? r.payeeDid : didHead4(r.payeeDid);
-  const direction = r.payeeDid === selfDid ? `${import_chalk21.default.bold("me")}(payee) \u2192 ${import_chalk21.default.dim(callerHead)}` : `${import_chalk21.default.dim(payeeHead)}(payee) \u2192 ${import_chalk21.default.bold("me")}`;
+  const direction = r.payeeDid === selfDid ? `${import_chalk22.default.bold("me")}(payee) \u2192 ${import_chalk22.default.dim(callerHead)}` : `${import_chalk22.default.dim(payeeHead)}(payee) \u2192 ${import_chalk22.default.bold("me")}`;
   const verdict = formatVerdict(r);
   const responseTail = opts.fullIds ? `
-  ${import_chalk21.default.dim("responseHash:")} ${import_chalk21.default.cyan(r.responseHash)}` : "";
+  ${import_chalk22.default.dim("responseHash:")} ${import_chalk22.default.cyan(r.responseHash)}` : "";
   return `${id}  ${state}  ${direction}  ${verdict}${responseTail}`;
 }
 function colorState3(s) {
   switch (s) {
     case "proposed":
-      return import_chalk21.default.yellow("proposed");
+      return import_chalk22.default.yellow("proposed");
     case "cosigned":
-      return import_chalk21.default.green("cosigned");
+      return import_chalk22.default.green("cosigned");
   }
 }
 function stateColumnWidth3() {
@@ -6257,11 +6858,11 @@ function formatVerdict(r) {
   const final = r.verdictFinal ?? r.verdictProposed;
   switch (final) {
     case "accepted":
-      return import_chalk21.default.green("accepted");
+      return import_chalk22.default.green("accepted");
     case "accepted_with_notes":
-      return import_chalk21.default.yellow("accepted_with_notes");
+      return import_chalk22.default.yellow("accepted_with_notes");
     case "rejected":
-      return import_chalk21.default.red("rejected");
+      return import_chalk22.default.red("rejected");
   }
 }
 function idHead3(id) {
@@ -6294,9 +6895,9 @@ function parseLimit7(raw) {
 
 // src/commands/register.ts
 var import_node_crypto = require("crypto");
-var import_node_fs8 = require("fs");
+var import_node_fs9 = require("fs");
 var import_sdk12 = require("@heyanon-arp/sdk");
-var import_chalk22 = __toESM(require("chalk"));
+var import_chalk23 = __toESM(require("chalk"));
 var import_prompts2 = __toESM(require("prompts"));
 init_api();
 init_paths();
@@ -6356,17 +6957,17 @@ async function runRegister(opts) {
   const publication = parsePublicationMode(opts.publication ?? "active");
   assertJsonRequiresYes(opts);
   const api = new ArpApiClient(opts.server);
-  if (!opts.json) console.log(import_chalk22.default.dim(`Server: ${api.serverUrl}`));
+  if (!opts.json) console.log(import_chalk23.default.dim(`Server: ${api.serverUrl}`));
   if (!opts.json) {
     warnIfAgentsAlreadyRegistered(opts.server);
     warnIfOrphanHomesPresent();
   }
   const keys = opts.fromKeys ? loadKeysFromFile(opts.fromKeys) : freshKeys();
   const did = (0, import_sdk12.formatDid)(keys.identityPublicKey);
-  if (!opts.json) console.log(import_chalk22.default.dim(`DID will be: ${did}`));
+  if (!opts.json) console.log(import_chalk23.default.dim(`DID will be: ${did}`));
   const answers = await mergeAnswers(opts);
   const scryptSalt = (0, import_node_crypto.randomBytes)(16);
-  if (!opts.json) console.log(import_chalk22.default.dim("Deriving scrypt key, this may take a moment..."));
+  if (!opts.json) console.log(import_chalk23.default.dim("Deriving scrypt key, this may take a moment..."));
   const scryptKey = (0, import_sdk12.deriveScryptKey)(answers.password, new Uint8Array(scryptSalt));
   const challenge = await api.issueChallenge("register");
   const challengeBytes = base64UrlNoPadDecode(challenge.challengeB64);
@@ -6445,13 +7046,13 @@ async function runRegister(opts) {
   try {
     recordHome(arpHomeDir());
   } catch (registryErr) {
-    if (!opts.json) console.log(import_chalk22.default.dim(`(homes registry write failed: ${registryErr.message})`));
+    if (!opts.json) console.log(import_chalk23.default.dim(`(homes registry write failed: ${registryErr.message})`));
   }
   if (!opts.json) {
-    console.log(import_chalk22.default.green("\nRegistered."));
-    console.log(`${import_chalk22.default.bold("DID")}: ${import_chalk22.default.cyan(result.did)}`);
-    console.log(`${import_chalk22.default.bold("Settlement pubkey")} ${import_chalk22.default.dim("(fund with SOL)")}: ${import_chalk22.default.cyan(settlementPublicKeyB58)}`);
-    console.log(import_chalk22.default.bold("DID document:"));
+    console.log(import_chalk23.default.green("\nRegistered."));
+    console.log(`${import_chalk23.default.bold("DID")}: ${import_chalk23.default.cyan(result.did)}`);
+    console.log(`${import_chalk23.default.bold("Settlement pubkey")} ${import_chalk23.default.dim("(fund with SOL)")}: ${import_chalk23.default.cyan(settlementPublicKeyB58)}`);
+    console.log(import_chalk23.default.bold("DID document:"));
     console.log(formatJson(result.didDocument));
   }
   const decision = decideAutoPublish({ publication, defaultEndpointUrl: answers.defaultEndpointUrl });
@@ -6461,33 +7062,33 @@ async function runRegister(opts) {
       const signer = makeSignerFromSecret(keys.identitySecretKey, result.did);
       await api.publishAgent(result.did, signer);
       publicationOutcome = "published";
-      if (!opts.json) console.log(import_chalk22.default.green(`
+      if (!opts.json) console.log(import_chalk23.default.green(`
 \u2713 Published \u2014 discoverable now via \`heyarp agents\`.`));
     } catch (err) {
       publicationOutcome = `failed: ${err.message}`;
       if (!opts.json)
         console.log(
-          import_chalk22.default.yellow(`
+          import_chalk23.default.yellow(`
 \u26A0 Auto-publish failed (${err.message}). Agent saved as DRAFT \u2014 run \`heyarp publish ${result.did}\` to make it discoverable.`)
         );
     }
   } else if (decision === "skip-no-endpoint") {
     publicationOutcome = "skip-no-endpoint";
     if (!opts.json) {
-      console.log(import_chalk22.default.dim(`
+      console.log(import_chalk23.default.dim(`
 Auto-publish skipped: no --endpoint-url supplied (buyer-only registration). Agent is saved as DRAFT.`));
-      console.log(import_chalk22.default.dim(`If this agent should also accept work, re-register with \`--endpoint-url <https://\u2026>\` OR run`));
-      console.log(import_chalk22.default.dim(`\`heyarp rotate ${result.did} --endpoint-url <https://\u2026>\` then \`heyarp publish ${result.did}\`.`));
+      console.log(import_chalk23.default.dim(`If this agent should also accept work, re-register with \`--endpoint-url <https://\u2026>\` OR run`));
+      console.log(import_chalk23.default.dim(`\`heyarp rotate ${result.did} --endpoint-url <https://\u2026>\` then \`heyarp publish ${result.did}\`.`));
     }
   } else {
     publicationOutcome = "draft";
     if (!opts.json) {
-      console.log(import_chalk22.default.dim(`
+      console.log(import_chalk23.default.dim(`
 Publication mode: DRAFT. Agent is registered but NOT discoverable via \`heyarp agents\`.`));
-      console.log(import_chalk22.default.dim(`Run \`heyarp publish ${result.did}\` when ready to appear in the catalog.`));
+      console.log(import_chalk23.default.dim(`Run \`heyarp publish ${result.did}\` when ready to appear in the catalog.`));
     }
   }
-  if (!opts.json) console.log(import_chalk22.default.dim(`
+  if (!opts.json) console.log(import_chalk23.default.dim(`
 Local state saved to ${arpHomeDir()}/agents.json (mode 0600).`));
   if (opts.json) {
     console.log(
@@ -6572,7 +7173,7 @@ async function mergeAnswers(opts) {
   }
   const prompted = promptDefs.length > 0 ? await (0, import_prompts2.default)(promptDefs, {
     onCancel: () => {
-      console.log(import_chalk22.default.yellow("\nAborted."));
+      console.log(import_chalk23.default.yellow("\nAborted."));
       process.exit(130);
     }
   }) : {};
@@ -6595,16 +7196,16 @@ function warnIfOrphanHomesPresent() {
   try {
     others = listHomes().filter((h) => h.path !== current);
   } catch (registryErr) {
-    console.log(import_chalk22.default.dim(`(homes registry unreadable, skipping orphan-home check: ${registryErr.message})`));
+    console.log(import_chalk23.default.dim(`(homes registry unreadable, skipping orphan-home check: ${registryErr.message})`));
     return;
   }
   if (others.length === 0) return;
-  const list = others.map((h) => `   \u2022 ${import_chalk22.default.cyan(h.path)} ${import_chalk22.default.dim(`(last seen ${h.lastSeenAt})`)}`).join("\n");
-  console.log(import_chalk22.default.yellow(`
+  const list = others.map((h) => `   \u2022 ${import_chalk23.default.cyan(h.path)} ${import_chalk23.default.dim(`(last seen ${h.lastSeenAt})`)}`).join("\n");
+  console.log(import_chalk23.default.yellow(`
 \u26A0  HEYARP_HOME is unset, but other agent homes are registered on this machine:`));
   console.log(list);
   console.log(
-    import_chalk22.default.dim(
+    import_chalk23.default.dim(
       `   Registering will create a NEW agent under ${current}.
    If you meant to add to an existing home, abort (Ctrl-C) and re-run with:
      HEYARP_HOME=<path> heyarp register \u2026
@@ -6617,11 +7218,11 @@ function warnIfAgentsAlreadyRegistered(serverOverride) {
   const targetServer = resolveServerUrl(serverOverride);
   const existing = listAgents().filter((row) => row.serverUrl === targetServer);
   if (existing.length === 0) return;
-  const list = existing.map((row) => `   \u2022 ${import_chalk22.default.cyan(row.agent.did)}${row.agent.name ? import_chalk22.default.dim(` (${row.agent.name})`) : ""}`).join("\n");
-  console.log(import_chalk22.default.yellow("\n\u26A0  ~/.arp/agents.json already has agent(s) for this server:"));
+  const list = existing.map((row) => `   \u2022 ${import_chalk23.default.cyan(row.agent.did)}${row.agent.name ? import_chalk23.default.dim(` (${row.agent.name})`) : ""}`).join("\n");
+  console.log(import_chalk23.default.yellow("\n\u26A0  ~/.arp/agents.json already has agent(s) for this server:"));
   console.log(list);
   console.log(
-    import_chalk22.default.dim(
+    import_chalk23.default.dim(
       "   After this register completes, you will have multiple local DIDs sharing one state file.\n   To keep their state isolated, run with HEYARP_HOME pointing at a per-agent dir, e.g.\n     HEYARP_HOME=/tmp/agent-alice heyarp register \u2026\n   Otherwise, pass --from-did <did> explicitly on every signed command.\n"
     )
   );
@@ -6641,12 +7242,12 @@ function freshKeys() {
   };
 }
 function loadKeysFromFile(path) {
-  if (!(0, import_node_fs8.existsSync)(path)) {
+  if (!(0, import_node_fs9.existsSync)(path)) {
     throw new Error(`--from-keys: file not found at ${path}`);
   }
   let parsed;
   try {
-    parsed = JSON.parse((0, import_node_fs8.readFileSync)(path, "utf8"));
+    parsed = JSON.parse((0, import_node_fs9.readFileSync)(path, "utf8"));
   } catch (err) {
     throw new Error(`--from-keys: ${path} is not valid JSON: ${err.message}`);
   }
@@ -6688,7 +7289,7 @@ function makeSignerFromSecret(identitySecretKey, did) {
 }
 
 // src/commands/relationships.ts
-var import_chalk23 = __toESM(require("chalk"));
+var import_chalk24 = __toESM(require("chalk"));
 init_api();
 var ALLOWED_STATES4 = /* @__PURE__ */ new Set(["pending", "active", "paused", "closed"]);
 function registerRelationshipsCommand(root) {
@@ -6708,25 +7309,25 @@ async function runRelationships(positionalDid, opts) {
   const local = explicitDid !== void 0 ? loadAgentOrThrow(opts.server, explicitDid) : resolveSenderAgent("relationships", opts.server, void 0);
   const did = local.did;
   const api = new ArpApiClient(opts.server);
-  console.log(import_chalk23.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk23.default.dim(`Signer: ${local.did}`));
+  console.log(import_chalk24.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk24.default.dim(`Signer: ${local.did}`));
   const query = { limit };
   if (state) query.state = state;
   const signer = makeSigner(local);
   const rows = await api.listRelationships(did, signer, query);
   if (rows.length === 0) {
-    console.log(import_chalk23.default.dim("\n(no relationships)"));
+    console.log(import_chalk24.default.dim("\n(no relationships)"));
     return;
   }
   console.log("");
   console.log(formatRelationshipsTable(rows, did));
   if (opts.verbose) {
-    console.log(import_chalk23.default.bold("\nFull relationships:"));
+    console.log(import_chalk24.default.bold("\nFull relationships:"));
     for (const r of rows) {
       console.log(formatJson(r));
     }
   }
-  console.log(import_chalk23.default.dim(`
+  console.log(import_chalk24.default.dim(`
 ${rows.length} relationship(s).`));
 }
 function formatRelationshipsTable(rows, selfDid) {
@@ -6734,7 +7335,7 @@ function formatRelationshipsTable(rows, selfDid) {
   const data = rows.map((r) => [r.relationshipId, otherPair(r, selfDid), r.state, r.lastEventAt ?? "(none)", String(r.lastEventIndex)]);
   const widths = header.map((h, i) => Math.max(h.length, ...data.map((row) => row[i].length)));
   const pad = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ");
-  return [import_chalk23.default.bold(pad(header)), import_chalk23.default.dim(pad(widths.map((w) => "-".repeat(w)))), ...data.map((row) => pad(row))].join("\n");
+  return [import_chalk24.default.bold(pad(header)), import_chalk24.default.dim(pad(widths.map((w) => "-".repeat(w)))), ...data.map((row) => pad(row))].join("\n");
 }
 function otherPair(r, selfDid) {
   if (r.pairDidA === selfDid) return r.pairDidB;
@@ -6759,7 +7360,7 @@ function parseLimit8(raw) {
 
 // src/commands/rotate.ts
 var import_sdk13 = require("@heyanon-arp/sdk");
-var import_chalk24 = __toESM(require("chalk"));
+var import_chalk25 = __toESM(require("chalk"));
 var import_prompts3 = __toESM(require("prompts"));
 init_api();
 var ROTATION_REASONS = ["scheduled", "compromise", "lost_device", "other"];
@@ -6777,8 +7378,8 @@ async function runRotate(did, opts) {
     throw new Error("rotate: local state is missing ownerId / currentAttestationId. State predates the rotation flow \u2014 please re-register.");
   }
   const api = new ArpApiClient(opts.server);
-  console.log(import_chalk24.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk24.default.dim(`Rotating: ${local.did}`));
+  console.log(import_chalk25.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk25.default.dim(`Rotating: ${local.did}`));
   if (!opts.yes) {
     const confirm = await (0, import_prompts3.default)({
       type: "confirm",
@@ -6787,7 +7388,7 @@ async function runRotate(did, opts) {
       initial: false
     });
     if (!confirm.go) {
-      console.log(import_chalk24.default.yellow("Aborted."));
+      console.log(import_chalk25.default.yellow("Aborted."));
       return;
     }
   }
@@ -6863,22 +7464,22 @@ async function runRotate(did, opts) {
       pendingRotation: void 0
     });
   } catch (err) {
-    console.error(import_chalk24.default.red("\nServer rotation succeeded but local state write failed."));
-    console.error(import_chalk24.default.red("Capture these values now \u2014 the new key is already live server-side:"));
-    console.error(`  ${import_chalk24.default.bold("identityPublicKeyB58")}  : ${newIdentityPublicKeyB58}`);
-    console.error(`  ${import_chalk24.default.bold("identitySecretKeyB64")}  : ${newIdentitySecretKeyB64}`);
-    console.error(`  ${import_chalk24.default.bold("currentAttestationId")}  : ${updated.currentAttestationId}`);
-    console.error(import_chalk24.default.dim(`(Also persisted in pendingRotation at ~/.arp/agents.json before the server call.)`));
-    console.error(import_chalk24.default.dim(`Underlying error: ${err.message}`));
+    console.error(import_chalk25.default.red("\nServer rotation succeeded but local state write failed."));
+    console.error(import_chalk25.default.red("Capture these values now \u2014 the new key is already live server-side:"));
+    console.error(`  ${import_chalk25.default.bold("identityPublicKeyB58")}  : ${newIdentityPublicKeyB58}`);
+    console.error(`  ${import_chalk25.default.bold("identitySecretKeyB64")}  : ${newIdentitySecretKeyB64}`);
+    console.error(`  ${import_chalk25.default.bold("currentAttestationId")}  : ${updated.currentAttestationId}`);
+    console.error(import_chalk25.default.dim(`(Also persisted in pendingRotation at ~/.arp/agents.json before the server call.)`));
+    console.error(import_chalk25.default.dim(`Underlying error: ${err.message}`));
     throw err;
   }
-  console.log(import_chalk24.default.green("\nRotated."));
-  console.log(`${import_chalk24.default.bold("DID")}: ${import_chalk24.default.cyan(updated.did)} ${import_chalk24.default.dim("(unchanged)")}`);
-  console.log(`${import_chalk24.default.bold("New identity public key")}: ${import_chalk24.default.cyan(newIdentityPublicKeyB58)}`);
-  console.log(`${import_chalk24.default.bold("New attestation id")}: ${import_chalk24.default.cyan(updated.currentAttestationId)}`);
-  console.log(import_chalk24.default.bold("\nAgent profile:"));
+  console.log(import_chalk25.default.green("\nRotated."));
+  console.log(`${import_chalk25.default.bold("DID")}: ${import_chalk25.default.cyan(updated.did)} ${import_chalk25.default.dim("(unchanged)")}`);
+  console.log(`${import_chalk25.default.bold("New identity public key")}: ${import_chalk25.default.cyan(newIdentityPublicKeyB58)}`);
+  console.log(`${import_chalk25.default.bold("New attestation id")}: ${import_chalk25.default.cyan(updated.currentAttestationId)}`);
+  console.log(import_chalk25.default.bold("\nAgent profile:"));
   console.log(formatJson(updated));
-  console.log(import_chalk24.default.dim("\nLocal state updated; old private key is no longer valid."));
+  console.log(import_chalk25.default.dim("\nLocal state updated; old private key is no longer valid."));
 }
 function base64UrlNoPadDecode2(s) {
   const replaced = s.replace(/-/g, "+").replace(/_/g, "/");
@@ -6888,7 +7489,7 @@ function base64UrlNoPadDecode2(s) {
 
 // src/commands/send-handshake.ts
 var import_sdk14 = require("@heyanon-arp/sdk");
-var import_chalk25 = __toESM(require("chalk"));
+var import_chalk26 = __toESM(require("chalk"));
 init_api();
 function registerSendHandshakeCommand(root) {
   root.command("send-handshake").description("Send a handshake envelope to <recipient-did>. Server creates the relationship row on first contact.").argument("<recipient-did>", "Recipient agent DID (did:arp:...)").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--greeting <s>", "Optional greeting text included in body.content").option("--intent <s>", "Optional intent text included in body.content").option("--ttl <seconds>", "Envelope TTL in seconds (max 86400 = 24h)", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).action(async (recipientDid, opts) => {
@@ -6901,10 +7502,10 @@ async function runSendHandshake(recipientDid, opts) {
   }
   const ttlSeconds = parseTtl5(opts.ttl);
   const api = new ArpApiClient(opts.server);
-  console.log(import_chalk25.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk26.default.dim(`Server: ${api.serverUrl}`));
   const sender = resolveSenderAgent("send-handshake", opts.server, opts.fromDid);
-  console.log(import_chalk25.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk25.default.dim(`Recipient: ${recipientDid}`));
+  console.log(import_chalk26.default.dim(`Sender: ${sender.did}`));
+  console.log(import_chalk26.default.dim(`Recipient: ${recipientDid}`));
   const content = {};
   if (opts.greeting) content.greeting = opts.greeting;
   if (opts.intent) content.intent = opts.intent;
@@ -6930,28 +7531,28 @@ async function runSendHandshake(recipientDid, opts) {
     identitySecretKey: signer.identitySecretKey
   });
   if (opts.verbose) {
-    console.log(import_chalk25.default.bold("\nEnvelope (pre-send):"));
+    console.log(import_chalk26.default.bold("\nEnvelope (pre-send):"));
     console.log(formatJson(envelope));
   }
   const result = await api.ingest(envelope);
   updateAgentLocal(opts.server, sender.did, { lastSenderSequence: nextSequence });
-  console.log(import_chalk25.default.green("\nDelivered."));
-  console.log(`${import_chalk25.default.bold("Event id")}: ${import_chalk25.default.cyan(result.eventId)}`);
-  console.log(`${import_chalk25.default.bold("Relationship id")}: ${import_chalk25.default.cyan(result.relationshipId)}`);
-  console.log(`${import_chalk25.default.bold("Chain index")}: ${import_chalk25.default.cyan(String(result.relationshipEventIndex))}`);
-  console.log(`${import_chalk25.default.bold("Server timestamp")}: ${import_chalk25.default.cyan(result.serverTimestamp)}`);
-  console.log(`${import_chalk25.default.bold("Signed message hash")}: ${import_chalk25.default.cyan(result.signedMessageHash)}`);
-  console.log(`${import_chalk25.default.bold("Server event hash")}: ${import_chalk25.default.cyan(result.serverEventHash)}`);
+  console.log(import_chalk26.default.green("\nDelivered."));
+  console.log(`${import_chalk26.default.bold("Event id")}: ${import_chalk26.default.cyan(result.eventId)}`);
+  console.log(`${import_chalk26.default.bold("Relationship id")}: ${import_chalk26.default.cyan(result.relationshipId)}`);
+  console.log(`${import_chalk26.default.bold("Chain index")}: ${import_chalk26.default.cyan(String(result.relationshipEventIndex))}`);
+  console.log(`${import_chalk26.default.bold("Server timestamp")}: ${import_chalk26.default.cyan(result.serverTimestamp)}`);
+  console.log(`${import_chalk26.default.bold("Signed message hash")}: ${import_chalk26.default.cyan(result.signedMessageHash)}`);
+  console.log(`${import_chalk26.default.bold("Server event hash")}: ${import_chalk26.default.cyan(result.serverEventHash)}`);
   if (result.prevServerEventHash) {
-    console.log(`${import_chalk25.default.bold("Prev server event hash")}: ${import_chalk25.default.cyan(result.prevServerEventHash)}`);
+    console.log(`${import_chalk26.default.bold("Prev server event hash")}: ${import_chalk26.default.cyan(result.prevServerEventHash)}`);
   } else {
-    console.log(`${import_chalk25.default.bold("Prev server event hash")}: ${import_chalk25.default.dim("(null \u2014 first event of this relationship)")}`);
+    console.log(`${import_chalk26.default.bold("Prev server event hash")}: ${import_chalk26.default.dim("(null \u2014 first event of this relationship)")}`);
   }
   if (opts.verbose) {
-    console.log(import_chalk25.default.bold("\nFull server response:"));
+    console.log(import_chalk26.default.bold("\nFull server response:"));
     console.log(formatJson(result));
   }
-  console.log(import_chalk25.default.dim(`
+  console.log(import_chalk26.default.dim(`
 Local sender_sequence advanced to ${nextSequence}.`));
 }
 function parseTtl5(raw) {
@@ -6968,7 +7569,7 @@ function isDid(s) {
 
 // src/commands/send-handshake-response.ts
 var import_sdk15 = require("@heyanon-arp/sdk");
-var import_chalk26 = __toESM(require("chalk"));
+var import_chalk27 = __toESM(require("chalk"));
 init_api();
 var ALLOWED_DECISIONS = /* @__PURE__ */ new Set(["accept", "decline"]);
 function registerSendHandshakeResponseCommand(root) {
@@ -6979,7 +7580,11 @@ function registerSendHandshakeResponseCommand(root) {
     // would fire for the accept path too; validate manually
     // after decision is parsed.
     `When --decision=decline: required reason code (one of: ${import_sdk15.DECLINE_REASONS.join(", ")}). Carried in body.content.reason.`
-  ).option("--reason-detail <s>", "Optional free-text elaboration alongside --reason (max 512 chars).").option("--ttl <seconds>", "Envelope TTL in seconds (max 86400 = 24h)", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).option(
+  ).option("--reason-detail <s>", "Optional free-text elaboration alongside --reason (max 512 chars).").option("--ttl <seconds>", "Envelope TTL in seconds (max 86400 = 24h)", "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    "Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, decision, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash, prevServerEventHash}; idempotent short-circuit adds {idempotent:true}). Prelude + banners move off stdout; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.",
+    false
+  ).option(
     "--force",
     "Skip the pre-send relationship-state probe. Default: when the relationship with <recipient-did> is already 'active', the command short-circuits successfully (the previous response already landed). Pass --force to re-send anyway \u2014 the server still gates with DOM_INVALID_TRANSITION, so this is mostly useful for FSM-guard tests.",
     false
@@ -6988,6 +7593,11 @@ function registerSendHandshakeResponseCommand(root) {
   });
 }
 async function runSendHandshakeResponse(recipientDid, opts) {
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      "send-handshake-response: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds envelope + response dumps that would break `--json | jq`."
+    );
+  }
   if (!isDid2(recipientDid)) {
     throw new Error(`send-handshake-response: <recipient-did> must look like 'did:arp:...' (got '${recipientDid}')`);
   }
@@ -7000,11 +7610,11 @@ async function runSendHandshakeResponse(recipientDid, opts) {
     declinePayload = detail ? { reason, reasonDetail: detail } : { reason };
   }
   const api = new ArpApiClient(opts.server);
-  console.log(import_chalk26.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk27.default.dim(`Server: ${api.serverUrl}`));
   const sender = resolveSenderAgent("send-handshake-response", opts.server, opts.fromDid);
-  console.log(import_chalk26.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk26.default.dim(`Recipient: ${recipientDid}`));
-  console.log(import_chalk26.default.dim(`Decision: ${decision}`));
+  progress(opts.json, import_chalk27.default.dim(`Sender: ${sender.did}`));
+  progress(opts.json, import_chalk27.default.dim(`Recipient: ${recipientDid}`));
+  progress(opts.json, import_chalk27.default.dim(`Decision: ${decision}`));
   const signer = makeSigner(sender);
   if (!opts.force) {
     try {
@@ -7017,12 +7627,29 @@ async function runSendHandshakeResponse(recipientDid, opts) {
         const events = await api.listEvents(existing.relationshipId, signer);
         const previousResponseFromMe = events.find((e) => e.senderDid === sender.did && e.type === "handshake_response");
         if (previousResponseFromMe) {
-          console.log(import_chalk26.default.yellow(`
+          if (opts.json) {
+            jsonOut({
+              ok: true,
+              idempotent: true,
+              decision,
+              eventId: previousResponseFromMe.eventId,
+              relationshipId: existing.relationshipId,
+              relationshipEventIndex: previousResponseFromMe.relationshipEventIndex,
+              serverTimestamp: previousResponseFromMe.serverTimestamp,
+              signedMessageHash: previousResponseFromMe.signedMessageHash,
+              serverEventHash: previousResponseFromMe.serverEventHash,
+              prevServerEventHash: previousResponseFromMe.prevServerEventHash ?? null,
+              senderSequence: previousResponseFromMe.senderSequence
+            });
+            return;
+          }
+          progress(opts.json, import_chalk27.default.yellow(`
 [--idempotency] Relationship ${existing.relationshipId} with ${recipientDid} is already 'active'.`));
-          console.log(
-            import_chalk26.default.dim(`A previous accept from this signer (event ${previousResponseFromMe.eventId}) landed successfully. Skipping re-send (use --force to override).`)
+          progress(
+            opts.json,
+            import_chalk27.default.dim(`A previous accept from this signer (event ${previousResponseFromMe.eventId}) landed successfully. Skipping re-send (use --force to override).`)
           );
-          console.log(import_chalk26.default.dim(`Last event index: ${existing.lastEventIndex}, last server event hash: ${existing.lastServerEventHash ?? "(none)"}`));
+          progress(opts.json, import_chalk27.default.dim(`Last event index: ${existing.lastEventIndex}, last server event hash: ${existing.lastServerEventHash ?? "(none)"}`));
           return;
         }
         throw new Error(
@@ -7033,7 +7660,7 @@ async function runSendHandshakeResponse(recipientDid, opts) {
       if (probeErr instanceof Error && /CLOSED|terminated|already 'active' from a previous ACCEPT|original initiator/i.test(probeErr.message)) {
         throw probeErr;
       }
-      console.log(import_chalk26.default.dim(`(idempotency probe failed; proceeding anyway: ${probeErr.message})`));
+      progress(opts.json, import_chalk27.default.dim(`(idempotency probe failed; proceeding anyway: ${probeErr.message})`));
     }
   }
   const content = { decision };
@@ -7063,28 +7690,43 @@ async function runSendHandshakeResponse(recipientDid, opts) {
     identitySecretKey: signer.identitySecretKey
   });
   if (opts.verbose) {
-    console.log(import_chalk26.default.bold("\nEnvelope (pre-send):"));
+    console.log(import_chalk27.default.bold("\nEnvelope (pre-send):"));
     console.log(formatJson(envelope));
   }
   const result = await api.ingest(envelope);
   updateAgentLocal(opts.server, sender.did, { lastSenderSequence: nextSequence });
-  console.log(import_chalk26.default.green("\nDelivered."));
-  console.log(`${import_chalk26.default.bold("Event id")}: ${import_chalk26.default.cyan(result.eventId)}`);
-  console.log(`${import_chalk26.default.bold("Relationship id")}: ${import_chalk26.default.cyan(result.relationshipId)}`);
-  console.log(`${import_chalk26.default.bold("Chain index")}: ${import_chalk26.default.cyan(String(result.relationshipEventIndex))}`);
-  console.log(`${import_chalk26.default.bold("Server timestamp")}: ${import_chalk26.default.cyan(result.serverTimestamp)}`);
-  console.log(`${import_chalk26.default.bold("Signed message hash")}: ${import_chalk26.default.cyan(result.signedMessageHash)}`);
-  console.log(`${import_chalk26.default.bold("Server event hash")}: ${import_chalk26.default.cyan(result.serverEventHash)}`);
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      decision,
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp,
+      signedMessageHash: result.signedMessageHash,
+      serverEventHash: result.serverEventHash,
+      prevServerEventHash: result.prevServerEventHash ?? null,
+      senderSequence: nextSequence
+    });
+    return;
+  }
+  console.log(import_chalk27.default.green("\nDelivered."));
+  console.log(`${import_chalk27.default.bold("Event id")}: ${import_chalk27.default.cyan(result.eventId)}`);
+  console.log(`${import_chalk27.default.bold("Relationship id")}: ${import_chalk27.default.cyan(result.relationshipId)}`);
+  console.log(`${import_chalk27.default.bold("Chain index")}: ${import_chalk27.default.cyan(String(result.relationshipEventIndex))}`);
+  console.log(`${import_chalk27.default.bold("Server timestamp")}: ${import_chalk27.default.cyan(result.serverTimestamp)}`);
+  console.log(`${import_chalk27.default.bold("Signed message hash")}: ${import_chalk27.default.cyan(result.signedMessageHash)}`);
+  console.log(`${import_chalk27.default.bold("Server event hash")}: ${import_chalk27.default.cyan(result.serverEventHash)}`);
   if (result.prevServerEventHash) {
-    console.log(`${import_chalk26.default.bold("Prev server event hash")}: ${import_chalk26.default.cyan(result.prevServerEventHash)}`);
+    console.log(`${import_chalk27.default.bold("Prev server event hash")}: ${import_chalk27.default.cyan(result.prevServerEventHash)}`);
   } else {
-    console.log(`${import_chalk26.default.bold("Prev server event hash")}: ${import_chalk26.default.dim("(null \u2014 first event of this relationship)")}`);
+    console.log(`${import_chalk27.default.bold("Prev server event hash")}: ${import_chalk27.default.dim("(null \u2014 first event of this relationship)")}`);
   }
   if (opts.verbose) {
-    console.log(import_chalk26.default.bold("\nFull server response:"));
+    console.log(import_chalk27.default.bold("\nFull server response:"));
     console.log(formatJson(result));
   }
-  console.log(import_chalk26.default.dim(`
+  console.log(import_chalk27.default.dim(`
 Local sender_sequence advanced to ${nextSequence}.`));
 }
 function parseDecision(raw) {
@@ -7137,8 +7779,356 @@ async function findExistingRelationship(api, signer, senderDid, recipientDid) {
   return void 0;
 }
 
+// src/commands/settlement.ts
+var import_sdk16 = require("@heyanon-arp/sdk");
+var import_utils3 = require("@noble/hashes/utils");
+var import_chalk28 = __toESM(require("chalk"));
+init_api();
+var NATIVE_SOL_MINT2 = "11111111111111111111111111111111";
+var SETTLEMENT_MIN_EXPIRY_HEADROOM_SECS = 120;
+var SETTLEMENT_REFRESH_HEADROOM_SECS = 600;
+function registerSettlementCommands(root) {
+  const cmd = root.command("settlement").description("Settlement helpers \u2014 sign + deliver escrow-release signatures in one shot.");
+  cmd.command("auto-sign-and-deliver").description(
+    "As the PAYEE, sign the escrow-release digest for a delegation and deliver the signature to the buyer via a settlement_signature envelope \u2014 one command instead of the did-doc \u2192 derive-condition-hash \u2192 delegations \u2192 wallet sign-settlement-release \u2192 memory ritual. Run it after `heyarp receipt propose`."
+  ).requiredOption("--delegation-id <id>", "Delegation UUID whose receipt is being settled.").option("--rel-id <id>", "Relationship UUID. Auto-resolved from --delegation-id when omitted (the delegation must live in exactly one of your relationships).").option("--mint-pubkey <base58>", `Lock mint. Default native SOL (${NATIVE_SOL_MINT2}); set to the SPL token mint for token-denominated locks.`, NATIVE_SOL_MINT2).option(
+    "--cluster-tag <int>",
+    "Solana cluster the lock lives on: 0 = devnet, 1 = mainnet-beta. MUST match the create_lock cluster or the server-reconstructed release digest will not verify. REQUIRED \u2014 there is no default (a defaulted/wrong cluster silently signs an invalid settlement digest that fails at cosign)."
+  ).option(
+    "--settlement-buffer-secs <int>",
+    "Seconds added to the delegation deadline for the settlement digest expires_at (dispute buffer). Default 86400 (1 day). Ignored when --expires-at is given.",
+    "86400"
+  ).option(
+    "--expires-at <unix>",
+    "Explicit settlement digest expires_at (unix seconds). Overrides deadline+buffer. REQUIRED when the delegation has no deadline (a guessed value risks exceeding the on-chain lock expiry \u2192 server reject). Must be \u2264 the lock's on-chain expiry."
+  ).option(
+    "--partial-payee-amount <int>",
+    "Base-unit payee_amount for a PARTIAL release (usage_based). Default: the receipt's usage.computed_amount when set. Omit for a full release of a flat contract."
+  ).option(
+    "--fee-bps-at-lock <int>",
+    "fee_bps_at_lock denormalised on the Lock at create_lock time (default 0 \u2014 no protocol fee). Pass the lock's actual value on fee-enabled deployments."
+  ).option("--fee-recipient-at-lock <base58>", "fee_recipient_at_lock denormalised on the Lock (default native = 1...1).").option("--server <url>", "Override ARP server base URL.").option("--from-did <did>", "Sender DID (= the payee) \u2014 required only if multiple agents are registered against this server.").option(
+    "--receipt-event-hash <sha256:hex>",
+    "Disambiguate when a delegation has more than one PROPOSED receipt (e.g. multiple work requests). Selects the exact receipt to settle."
+  ).option(
+    "--force",
+    "Re-sign and re-deliver even when a payee settlement signature already exists on the receipt. Use to REPAIR a previously-delivered sig built with wrong digest inputs (fee/mint/cluster); the server replaces the stored payee sig with the later envelope. Default is an idempotent skip.",
+    false
+  ).option(
+    "--json",
+    "Machine-readable mode \u2014 emit a single JSON object on stdout {ok, delegationId, relationshipId, buyerDid, purpose, settlementPubkey, payeeAmount?, expiresAt, eventId, serverEventHash, ...}; idempotent re-run adds {idempotent:true}. Prelude moves to stderr; failures emit {code, message}.",
+    false
+  ).action(async (opts, cmd2) => {
+    try {
+      await runAutoSignAndDeliver(opts);
+    } catch (err) {
+      emitActionError(err, cmd2);
+      process.exitCode = 1;
+    }
+  });
+}
+function toBaseUnits(amountDecimal, decimals) {
+  if (!/^[0-9]+(\.[0-9]+)?$/.test(amountDecimal)) {
+    throw new Error(`settlement: amount '${amountDecimal}' is not a non-negative decimal number`);
+  }
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 18) {
+    throw new Error(`settlement: currency decimals must be an integer 0..18 (got ${decimals})`);
+  }
+  const [intPart, fracPart = ""] = amountDecimal.split(".");
+  if (fracPart.length > decimals) {
+    throw new Error(
+      `settlement: amount '${amountDecimal}' has ${fracPart.length} fractional digits but the currency only has ${decimals} decimals \u2014 refusing to truncate a money value`
+    );
+  }
+  const fracPadded = fracPart.padEnd(decimals, "0");
+  const combined = `${intPart}${fracPadded}`.replace(/^0+/, "");
+  return combined === "" ? "0" : combined;
+}
+async function findDelegationRow(api, signer, relationshipId, delegationId) {
+  let after;
+  for (let page = 0; page < 50; page++) {
+    const rows = await api.listDelegations(relationshipId, signer, { limit: 100, after });
+    if (rows.length === 0) return void 0;
+    const match = rows.find((d) => d.delegationId === delegationId);
+    if (match) return match;
+    if (rows.length < 100) return void 0;
+    after = rows[rows.length - 1].id;
+  }
+  return void 0;
+}
+function selectReceipt(matches, receiptEventHash, cmdName) {
+  if (matches.length === 0) return void 0;
+  if (receiptEventHash !== void 0 && receiptEventHash !== "") {
+    const exact = matches.find((r) => r.receiptEventHash === receiptEventHash);
+    if (!exact) {
+      throw new Error(
+        `${cmdName}: no receipt with receiptEventHash=${receiptEventHash} for this delegation (available: ${matches.map((r) => r.receiptEventHash).join(", ")})`
+      );
+    }
+    return exact;
+  }
+  const proposed = matches.filter((r) => r.state === "proposed");
+  if (proposed.length > 1) {
+    throw new Error(
+      `${cmdName}: ${proposed.length} PROPOSED receipts exist for this delegation \u2014 disambiguate with --receipt-event-hash <sha256:hex> (one of: ${proposed.map((r) => r.receiptEventHash).join(", ")})`
+    );
+  }
+  if (proposed.length === 1) return proposed[0];
+  return matches.reduce((latest, cur) => cur.createdAt > latest.createdAt ? cur : latest);
+}
+async function collectReceiptRows(api, signer, relationshipId, delegationId) {
+  const matches = [];
+  let after;
+  for (let page = 0; page < 50; page++) {
+    const rows = await api.listReceipts(relationshipId, signer, { limit: 100, after, delegationId });
+    if (rows.length === 0) break;
+    for (const r of rows) {
+      if (r.delegationId === delegationId) matches.push(r);
+    }
+    if (rows.length < 100) break;
+    after = rows[rows.length - 1].id;
+  }
+  return matches;
+}
+function settlementKeyFromDidDoc(didDoc, buyerDid) {
+  const mb = extractField(didDoc, "verificationMethod.#settlement.publicKeyMultibase");
+  if (typeof mb !== "string" || mb.length === 0) {
+    throw new Error(`settlement: buyer ${buyerDid} DID document has no usable #settlement verification key`);
+  }
+  return mb.startsWith("z") ? mb.slice(1) : mb;
+}
+async function runAutoSignAndDeliver(opts) {
+  const cmdName = "settlement auto-sign-and-deliver";
+  const delegationId = requireUuidNormalised(cmdName, opts.delegationId, "--delegation-id");
+  if (opts.relId) opts.relId = requireUuidNormalised(cmdName, opts.relId, "--rel-id");
+  const clusterTag = opts.clusterTag;
+  if (clusterTag !== void 0 && clusterTag !== "0" && clusterTag !== "1") {
+    throw new Error(`${cmdName}: --cluster-tag must be '0' (devnet) or '1' (mainnet-beta), got '${clusterTag}'`);
+  }
+  const bufferRaw = opts.settlementBufferSecs ?? "86400";
+  if (!/^[0-9]+$/.test(bufferRaw)) {
+    throw new Error(`${cmdName}: --settlement-buffer-secs must be a non-negative integer (got '${opts.settlementBufferSecs}')`);
+  }
+  const bufferSecs = Number.parseInt(bufferRaw, 10);
+  const api = new ArpApiClient(opts.server);
+  const sender = resolveSenderAgent(cmdName, opts.server, opts.fromDid);
+  const signer = makeSigner(sender);
+  progress(opts.json, import_chalk28.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk28.default.dim(`Signer (payee): ${sender.did}`));
+  const relId = opts.relId ?? await resolveAutoRelId(api, sender, delegationId);
+  progress(opts.json, import_chalk28.default.dim(`Relationship: ${relId}`));
+  const receiptMatches = await collectReceiptRows(api, signer, relId, delegationId);
+  const receipt = selectReceipt(receiptMatches, opts.receiptEventHash, cmdName);
+  if (!receipt) {
+    throw new Error(`${cmdName}: no receipt found for delegation ${delegationId} under relationship ${relId}. Run \`heyarp receipt propose\` first.`);
+  }
+  if (receipt.payeeDid !== sender.did) {
+    throw new Error(
+      `${cmdName}: signer ${sender.did} is not the payee on this receipt (payee is ${receipt.payeeDid}). The settlement signature must be signed by the PAYEE \u2014 pass --from-did <payee-did> or run as the payee agent.`
+    );
+  }
+  if (receipt.verdictProposed === "rejected" || receipt.verdictFinal === "rejected") {
+    throw new Error(
+      `${cmdName}: receipt verdict is 'rejected' \u2014 a rejected receipt is not payable; there is no settlement signature to send. (If this is wrong, the payee should re-propose the receipt with an accepting verdict.)`
+    );
+  }
+  if (receipt.state === "cosigned") {
+    if (opts.json) {
+      jsonOut({ ok: true, idempotent: true, alreadyCosigned: true, delegationId, relationshipId: relId, buyerDid: receipt.callerDid });
+      return;
+    }
+    progress(opts.json, import_chalk28.default.yellow("\n[idempotent] Receipt already cosigned \u2014 escrow release is settled. Nothing to send."));
+    return;
+  }
+  if (receipt.payeeSettlement && !opts.force) {
+    const ps = receipt.payeeSettlement;
+    const nowSecs = Math.floor(Date.now() / 1e3);
+    if (ps.expires_at > nowSecs + SETTLEMENT_REFRESH_HEADROOM_SECS) {
+      if (opts.json) {
+        jsonOut({
+          ok: true,
+          idempotent: true,
+          delegationId,
+          relationshipId: relId,
+          buyerDid: receipt.callerDid,
+          purpose: ps.purpose,
+          settlementPubkey: ps.settlement_pubkey,
+          ...ps.payee_amount !== void 0 ? { payeeAmount: ps.payee_amount } : {},
+          expiresAt: ps.expires_at
+        });
+        return;
+      }
+      progress(opts.json, import_chalk28.default.yellow("\n[idempotent] Payee settlement signature already delivered + still valid for this receipt \u2014 skipping re-send."));
+      progress(opts.json, import_chalk28.default.dim(`  purpose=${ps.purpose} settlement_pubkey=${ps.settlement_pubkey} expires_at=${ps.expires_at}`));
+      return;
+    }
+    progress(
+      opts.json,
+      import_chalk28.default.yellow(`
+[refresh] Existing payee settlement sig expires at ${ps.expires_at} (\u2264 now+${SETTLEMENT_REFRESH_HEADROOM_SECS}s) \u2014 re-signing with a fresh expiry.`)
+    );
+  }
+  const buyerDid = receipt.callerDid;
+  const receiptEventHash = receipt.receiptEventHash;
+  const deliverableHash = receipt.deliverableHash ?? receipt.responseHash;
+  progress(opts.json, import_chalk28.default.dim(`Buyer (payer): ${buyerDid}`));
+  progress(opts.json, import_chalk28.default.dim(`Receipt event hash: ${receiptEventHash}`));
+  const delegation = await findDelegationRow(api, signer, relId, delegationId);
+  if (!delegation) {
+    throw new Error(`${cmdName}: delegation ${delegationId} not found under relationship ${relId} (paginated 5000 rows).`);
+  }
+  if (delegation.state !== "accepted") {
+    throw new Error(
+      `${cmdName}: delegation ${delegationId} is in state '${delegation.state ?? "unknown"}' \u2014 only an 'accepted' delegation is settleable (its escrow lock is still LOCKED). A non-accepted delegation's lock has been released / refunded / canceled, so the server would reject the settlement signature post-commit (SETTLEMENT_SIG_LOCK_INVALID_STATE). Nothing to settle.`
+    );
+  }
+  if (!delegation.amount) {
+    throw new Error(`${cmdName}: delegation ${delegationId} has no amount \u2014 cannot derive the lock amount for the release digest.`);
+  }
+  const decimals = delegation.currency?.decimals ?? 9;
+  const lockAmount = toBaseUnits(delegation.amount, decimals);
+  let expiresAt8;
+  if (opts.expiresAt !== void 0 && opts.expiresAt !== "") {
+    if (!/^[0-9]+$/.test(opts.expiresAt)) {
+      throw new Error(`${cmdName}: --expires-at must be a positive unix-seconds integer (got '${opts.expiresAt}')`);
+    }
+    expiresAt8 = Number.parseInt(opts.expiresAt, 10);
+    if (!Number.isInteger(expiresAt8) || expiresAt8 <= 0) {
+      throw new Error(`${cmdName}: --expires-at must be a positive unix-seconds integer (got '${opts.expiresAt}')`);
+    }
+  } else if (delegation.deadline) {
+    expiresAt8 = Math.floor(new Date(delegation.deadline).getTime() / 1e3) + bufferSecs;
+  } else {
+    throw new Error(
+      `${cmdName}: delegation ${delegationId} has no deadline, so a safe settlement expires_at can't be derived (a guessed value risks exceeding the on-chain lock expiry \u2192 post-commit server reject). Pass --expires-at <unix-seconds> \u2264 the lock's expiry.`
+    );
+  }
+  const nowSecsForExpiry = Math.floor(Date.now() / 1e3);
+  const minSafeExpiry = nowSecsForExpiry + SETTLEMENT_MIN_EXPIRY_HEADROOM_SECS;
+  if (!Number.isFinite(expiresAt8) || expiresAt8 <= minSafeExpiry) {
+    const fromExplicit = opts.expiresAt !== void 0 && opts.expiresAt !== "";
+    throw new Error(
+      `${cmdName}: settlement expires_at (${Number.isFinite(expiresAt8) ? expiresAt8 : "NaN"}) is not far enough in the future \u2014 it must be > now+${SETTLEMENT_MIN_EXPIRY_HEADROOM_SECS}s (${minSafeExpiry}) or the server rejects it post-commit (SETTLEMENT_SIG_EXPIRES_AT_*), burning a sender_sequence. ${fromExplicit ? "Pass a later --expires-at <unix-seconds> (still \u2264 the lock's on-chain expiry)." : `Derived from deadline ${JSON.stringify(delegation.deadline)} + buffer ${bufferSecs}s \u2014 the deadline is too close or in the past. Increase --settlement-buffer-secs or pass --expires-at <unix-seconds> \u2264 the lock's expiry.`}`
+    );
+  }
+  const contract = await findContractRow(api, signer, relId, delegation.contractId, void 0);
+  if (contract.settlementModel === "prepaid") {
+    throw new Error(
+      `${cmdName}: contract ${contract.contractId} settlementModel is 'prepaid' (non-escrow). This command delivers an on-chain escrow-release signature; a prepaid contract has no lock to settle and the server would reject post-commit (SETTLEMENT_SIG_LOCK_NOT_FOUND). Nothing to settle on-chain.`
+    );
+  }
+  const subset = projectContractForHash(contract);
+  const conditionHash = (0, import_utils3.bytesToHex)((0, import_sdk16.deriveConditionHash)(subset));
+  const buyerDidDoc = await api.getDidDocument(buyerDid);
+  const payerSettlementPubkey = settlementKeyFromDidDoc(buyerDidDoc, buyerDid);
+  const isUsageBased = contract.pricingModel === "usage_based";
+  let partialPayeeAmount;
+  if (isUsageBased) {
+    const computed = receipt.usage?.computed_amount;
+    if (computed === void 0 || computed === "" || !/^[0-9]+$/.test(computed)) {
+      throw new Error(
+        `${cmdName}: contract ${contract.contractId} is usage_based but the receipt has no usable usage.computed_amount (got ${computed === void 0 ? "unset" : `'${computed}'`}). The server binds the PARTIAL-RELEASE amount to that field; re-propose the receipt with a computed_amount.`
+      );
+    }
+    if (opts.partialPayeeAmount !== void 0 && opts.partialPayeeAmount !== "") {
+      if (!/^[0-9]+$/.test(opts.partialPayeeAmount)) {
+        throw new Error(`${cmdName}: --partial-payee-amount must be a base-unit decimal-integer string (got '${opts.partialPayeeAmount}')`);
+      }
+      if (BigInt(opts.partialPayeeAmount) !== BigInt(computed)) {
+        throw new Error(
+          `${cmdName}: --partial-payee-amount ${opts.partialPayeeAmount} does not match the receipt's usage.computed_amount ${computed}. The server binds the settlement amount to the receipt \u2014 they must be equal; drop the flag or fix the value.`
+        );
+      }
+    }
+    partialPayeeAmount = computed;
+  } else {
+    if (opts.partialPayeeAmount !== void 0 && opts.partialPayeeAmount !== "") {
+      throw new Error(
+        `${cmdName}: contract ${contract.contractId} is ${contract.pricingModel ?? "flat"} (full-release only) \u2014 --partial-payee-amount is not allowed. A PARTIAL-RELEASE digest would be rejected by the server; drop the flag for a full release.`
+      );
+    }
+    partialPayeeAmount = void 0;
+  }
+  if (clusterTag === void 0) {
+    throw new Error(
+      `${cmdName}: --cluster-tag is required (0 = devnet, 1 = mainnet-beta). It binds the cluster into the signed release digest; there is no safe default \u2014 pass the cluster where the create_lock lives.`
+    );
+  }
+  if (opts.feeBpsAtLock !== void 0) {
+    if (!/^[0-9]+$/.test(opts.feeBpsAtLock)) {
+      throw new Error(`${cmdName}: --fee-bps-at-lock must be a non-negative integer (got '${opts.feeBpsAtLock}')`);
+    }
+    if (Number.parseInt(opts.feeBpsAtLock, 10) > 0 && (opts.feeRecipientAtLock === void 0 || opts.feeRecipientAtLock === "")) {
+      throw new Error(
+        `${cmdName}: --fee-bps-at-lock=${opts.feeBpsAtLock} is non-zero, so --fee-recipient-at-lock is also required. Both fee fields are bound into the release digest; defaulting the recipient to native would sign a digest the buyer's cosign rejects. Pass --fee-recipient-at-lock <the lock's fee_recipient_at_lock>.`
+      );
+    }
+  }
+  const signOpts = {
+    server: opts.server,
+    fromDid: opts.fromDid,
+    delegationId,
+    payerSettlementPubkey,
+    payeeSettlementPubkey: sender.settlementPublicKeyB58,
+    mintPubkey: opts.mintPubkey ?? NATIVE_SOL_MINT2,
+    lockAmount,
+    conditionHash,
+    receiptEventHash,
+    deliverableHash,
+    expiresAt: String(expiresAt8),
+    clusterTag,
+    ...opts.feeBpsAtLock !== void 0 ? { feeBpsAtLock: opts.feeBpsAtLock } : {},
+    ...opts.feeRecipientAtLock !== void 0 ? { feeRecipientAtLock: opts.feeRecipientAtLock } : {},
+    ...partialPayeeAmount !== void 0 ? { partialPayeeAmount } : {}
+  };
+  progress(
+    opts.json,
+    import_chalk28.default.dim(`Signing ${partialPayeeAmount !== void 0 ? "PARTIAL" : "full"} release: lock_amount=${lockAmount}, expires_at=${expiresAt8}, cluster_tag=${clusterTag}`)
+  );
+  const signed = await signSettlementHandler(signOpts);
+  const content = {
+    delegation_id: delegationId,
+    receipt_event_hash: receiptEventHash,
+    purpose: signed.purpose,
+    payee_settlement_pubkey: signed.settlement_pubkey,
+    sig: signed.sig,
+    expires_at: expiresAt8,
+    ...partialPayeeAmount !== void 0 ? { payee_amount: partialPayeeAmount } : {}
+  };
+  const result = await sendSettlementSignatureEnvelope({ api, sender, recipientDid: buyerDid, content, ttlSeconds: 3600, verbose: false, server: opts.server });
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      delegationId,
+      relationshipId: relId,
+      buyerDid,
+      purpose: signed.purpose,
+      settlementPubkey: signed.settlement_pubkey,
+      ...partialPayeeAmount !== void 0 ? { payeeAmount: partialPayeeAmount } : {},
+      lockAmount,
+      expiresAt: expiresAt8,
+      receiptEventHash,
+      eventId: result.eventId,
+      serverEventHash: result.serverEventHash,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp
+    });
+    return;
+  }
+  console.log(import_chalk28.default.green("\nSettlement signature signed + delivered."));
+  console.log(`${import_chalk28.default.bold("Delegation")}: ${import_chalk28.default.cyan(delegationId)}`);
+  console.log(`${import_chalk28.default.bold("Buyer")}: ${import_chalk28.default.cyan(buyerDid)}`);
+  console.log(`${import_chalk28.default.bold("Purpose")}: ${import_chalk28.default.cyan(signed.purpose)}`);
+  if (partialPayeeAmount !== void 0) {
+    console.log(`${import_chalk28.default.bold("Payee amount")}: ${import_chalk28.default.cyan(partialPayeeAmount)} (partial release)`);
+  }
+  console.log(`${import_chalk28.default.bold("Expires at")}: ${import_chalk28.default.cyan(String(expiresAt8))}`);
+  console.log(`${import_chalk28.default.bold("Delivered event")}: ${import_chalk28.default.cyan(result.serverEventHash)}`);
+  console.log(import_chalk28.default.dim("\nThe buyer cosigns with: heyarp receipt cosign <rel-id> <del-id> --auto-hashes --auto-resolve-payee-sig --payer-sig-from-file <path>"));
+}
+
 // src/commands/watch.ts
-var import_chalk27 = __toESM(require("chalk"));
+var import_chalk29 = __toESM(require("chalk"));
 init_api();
 function registerWatchCommand(root) {
   root.command("watch").description("Live tail filtered to a single relationship (SSE). Server-side $match; only envelopes belonging to <rel-id> are streamed.").argument("<relationship-id>", "Relationship UUID to watch").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Signer DID \u2014 required only if multiple agents are registered against this server").option("--verbose", "After each envelope, print the full JSON with a per-row label including eventId + serverEventHash", false).option("--json", "Machine-readable: one NDJSON object per line. Pipe-safe into `jq -c`.", false).option("--full-ids", "Print DIDs + serverEventHash in full (no truncation).", false).action(async (relationshipId, opts) => {
@@ -7149,9 +8139,9 @@ async function runWatch(relationshipId, opts) {
   const local = resolveSenderAgent("watch", opts.server, opts.fromDid);
   const api = new ArpApiClient(opts.server);
   if (!opts.json) {
-    console.log(import_chalk27.default.dim(`Server: ${api.serverUrl}`));
-    console.log(import_chalk27.default.dim(`Signer: ${local.did}`));
-    console.log(import_chalk27.default.dim(`Watching: ${relationshipId}`));
+    console.log(import_chalk29.default.dim(`Server: ${api.serverUrl}`));
+    console.log(import_chalk29.default.dim(`Signer: ${local.did}`));
+    console.log(import_chalk29.default.dim(`Watching: ${relationshipId}`));
   }
   const controller = new AbortController();
   let userAborted = false;
@@ -7170,7 +8160,7 @@ async function runWatch(relationshipId, opts) {
       }
       if (event.type === "heartbeat") continue;
       if (event.type === "connected") {
-        console.log(import_chalk27.default.green(`\u25CF stream open \u2014 watching ${relationshipId}`));
+        console.log(import_chalk29.default.green(`\u25CF stream open \u2014 watching ${relationshipId}`));
         continue;
       }
       if (event.type === "envelope") {
@@ -7184,7 +8174,7 @@ async function runWatch(relationshipId, opts) {
         }
         continue;
       }
-      console.log(import_chalk27.default.dim(`(unknown event: ${event.type})`));
+      console.log(import_chalk29.default.dim(`(unknown event: ${event.type})`));
     }
     if (!userAborted) {
       throw new Error(`watch ${relationshipId}: stream ended unexpectedly (server may have restarted, or the change stream errored). Re-run to reconnect.`);
@@ -7192,7 +8182,7 @@ async function runWatch(relationshipId, opts) {
   } catch (err) {
     const name = err.name;
     if (name === "AbortError" || userAborted) {
-      if (!opts.json) console.log(import_chalk27.default.dim("\nstream closed."));
+      if (!opts.json) console.log(import_chalk29.default.dim("\nstream closed."));
       return;
     }
     throw err;
@@ -7206,21 +8196,21 @@ function formatWatchLine(ev, selfDid, opts = {}) {
   const type = ev.type.padEnd(20);
   const direction = directionLabel2(ev, selfDid, opts);
   const hash = opts.fullIds ? ev.serverEventHash : hashHead4(ev.serverEventHash);
-  return `${import_chalk27.default.dim(`[${ts}]`)}  ${type}  ${direction}    ${import_chalk27.default.cyan(hash)}`;
+  return `${import_chalk29.default.dim(`[${ts}]`)}  ${type}  ${direction}    ${import_chalk29.default.cyan(hash)}`;
 }
 function directionLabel2(ev, selfDid, opts = {}) {
   const senderHead = opts.fullIds ? ev.senderDid : didHead5(ev.senderDid);
   const recipientHead = opts.fullIds ? ev.recipientDid : didHead5(ev.recipientDid);
-  if (ev.senderDid === selfDid) return `${import_chalk27.default.bold("me")} \u2192 ${import_chalk27.default.dim(recipientHead)}`;
-  if (ev.recipientDid === selfDid) return `${import_chalk27.default.dim(senderHead)} \u2192 ${import_chalk27.default.bold("me")}`;
-  return `${import_chalk27.default.dim(senderHead)} \u2192 ${import_chalk27.default.dim(recipientHead)}`;
+  if (ev.senderDid === selfDid) return `${import_chalk29.default.bold("me")} \u2192 ${import_chalk29.default.dim(recipientHead)}`;
+  if (ev.recipientDid === selfDid) return `${import_chalk29.default.dim(senderHead)} \u2192 ${import_chalk29.default.bold("me")}`;
+  return `${import_chalk29.default.dim(senderHead)} \u2192 ${import_chalk29.default.dim(recipientHead)}`;
 }
 function didHead5(did) {
   if (did.length <= 20) return did;
   return `${did.slice(0, 20)}...`;
 }
 function hashHead4(hash) {
-  if (!hash) return import_chalk27.default.dim("(none)");
+  if (!hash) return import_chalk29.default.dim("(none)");
   if (hash.length <= 14) return hash;
   return `${hash.slice(0, 14)}...`;
 }
@@ -7231,8 +8221,283 @@ function formatClock(iso) {
   return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
 }
 
+// src/commands/webhook.ts
+var import_promises = require("timers/promises");
+var import_chalk30 = __toESM(require("chalk"));
+init_api();
+function registerWebhookCommand(root) {
+  const webhook = root.command("webhook").description("Manage outbound webhook delivery \u2014 URL + HMAC secret lifecycle for the calling agent.");
+  registerUrlSubcommands(webhook);
+  registerSecretSubcommands(webhook);
+}
+function registerUrlSubcommands(parent) {
+  const url = parent.command("url").description("Outbound webhook URL \u2014 the address the server POSTs deliveries to.");
+  url.command("set").description(
+    "Set / replace the outbound webhook URL. Server validates the URL (scheme + non-private IP) and fires an unsigned probe POST (X-ARP-Probe: 1, 5s timeout) before persisting \u2014 non-2xx response \u2192 400 WEBHOOK_PROBE_FAILED, no persistence."
+  ).argument("<url>", "HTTPS URL the server should POST webhook deliveries to").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Explicit sender DID \u2014 required when more than one local agent exists").option("--json", "JSON output (jq-pipeable)", false).action(async (webhookUrl, opts, cmd) => {
+    try {
+      const local = resolveSenderAgent("webhook url set", opts.server, opts.fromDid);
+      const api = new ArpApiClient(opts.server);
+      const signer = makeSigner(local);
+      const out = await api.setMyWebhookConfig({ webhookUrl }, signer);
+      if (opts.json) {
+        console.log(formatJson(out));
+        return;
+      }
+      console.log(import_chalk30.default.dim(`Server: ${api.serverUrl}`));
+      console.log(import_chalk30.default.dim(`Signer: ${local.did}`));
+      console.log(`${import_chalk30.default.green("Webhook URL set:")} ${import_chalk30.default.cyan(out.webhookUrl ?? "(cleared)")}`);
+      if (!out.webhookSecretRegistered) {
+        console.log(import_chalk30.default.yellow("\nNo HMAC secret registered yet. Run: heyarp webhook secret init"));
+      }
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+  url.command("show").description("Show the calling agent's outbound webhook URL + whether an HMAC secret is registered. Read-only.").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Explicit sender DID \u2014 required when more than one local agent exists").option("--json", "JSON output (jq-pipeable)", false).action(async (opts, cmd) => {
+    try {
+      const local = resolveSenderAgent("webhook url show", opts.server, opts.fromDid);
+      const api = new ArpApiClient(opts.server);
+      const signer = makeSigner(local);
+      const out = await api.getMyWebhookConfig(signer);
+      if (opts.json) {
+        console.log(formatJson(out));
+        return;
+      }
+      console.log(import_chalk30.default.dim(`Server: ${api.serverUrl}`));
+      console.log(import_chalk30.default.dim(`Signer: ${local.did}`));
+      console.log(`${import_chalk30.default.bold("Webhook URL:")}      ${out.webhookUrl ? import_chalk30.default.cyan(out.webhookUrl) : import_chalk30.default.dim("(unset \u2014 poll/SSE only)")}`);
+      console.log(`${import_chalk30.default.bold("Secret registered:")} ${out.webhookSecretRegistered ? import_chalk30.default.green("yes") : import_chalk30.default.yellow("no")}`);
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+  url.command("clear").description(
+    "Unset the outbound webhook URL. Disables webhook delivery on the next outbox enqueue; in-flight deliveries finish naturally. Agent reverts to poll / SSE without losing data."
+  ).option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Explicit sender DID \u2014 required when more than one local agent exists").option("--yes", "Skip the destructive-action confirmation prompt", false).option("--json", "JSON output (jq-pipeable)", false).action(async (opts, cmd) => {
+    try {
+      const local = resolveSenderAgent("webhook url clear", opts.server, opts.fromDid);
+      const api = new ArpApiClient(opts.server);
+      const signer = makeSigner(local);
+      if (!opts.yes) {
+        const answer = await promptYesNo("Clear the webhook URL? Outbound delivery will stop on next outbox enqueue.");
+        if (!answer) {
+          console.log(import_chalk30.default.dim("Aborted."));
+          return;
+        }
+      }
+      const out = await api.setMyWebhookConfig({ webhookUrl: null }, signer);
+      if (opts.json) {
+        console.log(formatJson(out));
+        return;
+      }
+      console.log(`${import_chalk30.default.green("Webhook URL cleared.")} Agent reverts to poll / SSE for new events.`);
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+}
+var REDACTED_SECRET_MARKER = "<REDACTED \u2014 read ~/.arp/agents.json>";
+function parseNonNegativeInt(raw, fieldName) {
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(`${fieldName}: must be a non-negative integer (got '${raw}')`);
+  }
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isSafeInteger(n) || n > 86400) {
+    throw new Error(`${fieldName}: out of range (got '${raw}', max 86400)`);
+  }
+  return n;
+}
+function warnIfChmodFailed(result) {
+  if (!result.chmodOk) {
+    console.error(import_chalk30.default.red("WARNING: failed to chmod 0600 on ~/.arp/agents.json \u2014 the file may be world-readable. Check filesystem permissions and re-run."));
+  }
+}
+function registerSecretSubcommands(parent) {
+  const secret = parent.command("secret").description("HMAC secret used to sign outbound webhook deliveries (X-ARP-Signature header).");
+  secret.command("init").description(
+    "Generate the calling agent's first HMAC secret. Server returns the plaintext value ONCE; the CLI persists it to ~/.arp/agents.json under `webhookSecretB64` (chmod 600). 409 WEBHOOK_SECRET_ALREADY_REGISTERED if a secret already exists \u2014 use `webhook secret rotate` to change."
+  ).option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Explicit sender DID \u2014 required when more than one local agent exists").option(
+    "--json",
+    "JSON output (jq-pipeable). Plaintext secret is REDACTED from --json output to keep it out of shell history / CI logs \u2014 the persisted copy in ~/.arp/agents.json is the only retained source.",
+    false
+  ).action(async (opts, cmd) => {
+    try {
+      const local = resolveSenderAgent("webhook secret init", opts.server, opts.fromDid);
+      const api = new ArpApiClient(opts.server);
+      const signer = makeSigner(local);
+      const out = await api.initMyWebhookSecret(signer);
+      const writeResult = updateAgentLocal(opts.server, local.did, { webhookSecretB64: out.webhookSecretB64 });
+      warnIfChmodFailed(writeResult);
+      if (opts.json) {
+        console.log(formatJson({ ...out, webhookSecretB64: REDACTED_SECRET_MARKER, persisted: true }));
+        return;
+      }
+      console.log(import_chalk30.default.dim(`Server: ${api.serverUrl}`));
+      console.log(import_chalk30.default.dim(`Signer: ${local.did}`));
+      console.log(import_chalk30.default.green("Webhook HMAC secret registered + persisted locally."));
+      console.log(import_chalk30.default.dim("  Stored in ~/.arp/agents.json under `webhookSecretB64` (chmod 600)."));
+      console.log(import_chalk30.default.dim("  Your handler reads this on startup to verify X-ARP-Signature."));
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+  secret.command("status").description(
+    "Show the calling agent's server-side webhook-secret lifecycle: which slots are populated (`current`, `pending`, `previous`) and the post-commit grace expiry. Read-only \u2014 does NOT return any secret material. Use during rotation to verify the recipient handler picks up the new secret before commit."
+  ).option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Explicit sender DID \u2014 required when more than one local agent exists").option("--json", "JSON output (jq-pipeable)", false).action(async (opts, cmd) => {
+    try {
+      const local = resolveSenderAgent("webhook secret status", opts.server, opts.fromDid);
+      const api = new ArpApiClient(opts.server);
+      const signer = makeSigner(local);
+      const out = await api.getMyWebhookSecretStatus(signer);
+      if (opts.json) {
+        console.log(formatJson(out));
+        return;
+      }
+      console.log(import_chalk30.default.dim(`Server: ${api.serverUrl}`));
+      console.log(import_chalk30.default.dim(`Signer: ${local.did}`));
+      console.log(`${import_chalk30.default.bold("Current:")}  ${out.currentRegistered ? import_chalk30.default.green("registered") : import_chalk30.default.yellow("NONE \u2014 run `heyarp webhook secret init`")}`);
+      console.log(`${import_chalk30.default.bold("Pending:")}  ${out.pendingStaged ? import_chalk30.default.cyan("staged \u2014 awaiting --commit") : import_chalk30.default.dim("\u2014")}`);
+      if (out.previousActive) {
+        console.log(
+          `${import_chalk30.default.bold("Previous:")} ${import_chalk30.default.cyan("grace-active")} (handler should keep verifying against it until ${import_chalk30.default.cyan(out.previousSecretExpiresAt ?? "?")})`
+        );
+      } else {
+        console.log(`${import_chalk30.default.bold("Previous:")} ${import_chalk30.default.dim("\u2014")}`);
+      }
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+  secret.command("rotate").description(
+    "Two-phase HMAC secret rotation with a recipient-grace window. Phase 1 (--stage) primes the recipient handler with the new secret while the server keeps signing with the old one; phase 2 (--commit) flips the server-side signing key and starts a 1h grace window where the old secret is still valid. Run with no sub-flag to do both phases with --wait-before-commit between them."
+  ).option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Explicit sender DID \u2014 required when more than one local agent exists").option(
+    "--stage",
+    "Phase 1 only \u2014 stage a new secret without flipping the server signing key. CLI writes the new secret to `webhookSecretB64Next` for the handler to pre-load.",
+    false
+  ).option("--commit", "Phase 2 only \u2014 flip the server signing key. Requires a prior --stage (rotationId comes from local state).", false).option(
+    "--wait-before-commit <s>",
+    "Auto-mode only: seconds to wait between phase 1 (stage) and phase 2 (commit). Default 30 \u2014 enough for a pm2 / systemd handler restart to pick up `webhookSecretB64Next`. Pass 0 to commit immediately (UNSAFE \u2014 guarantees a brief HMAC-verification gap unless the handler is already running in dual-key mode).",
+    "30"
+  ).option("--json", "JSON output for the commit-phase response", false).action(async (opts, cmd) => {
+    try {
+      if (opts.stage && opts.commit) {
+        throw new Error("webhook secret rotate: --stage and --commit are mutually exclusive");
+      }
+      const local = resolveSenderAgent("webhook secret rotate", opts.server, opts.fromDid);
+      const api = new ArpApiClient(opts.server);
+      const signer = makeSigner(local);
+      if (opts.stage) {
+        await doStage(api, signer, local.did, opts.server, !!opts.json);
+        return;
+      }
+      if (opts.commit) {
+        await doCommitFromLocalState(api, signer, local.did, opts.server, !!opts.json);
+        return;
+      }
+      const waitSeconds = parseNonNegativeInt(opts.waitBeforeCommit ?? "30", "webhook secret rotate --wait-before-commit");
+      const staged = await doStage(api, signer, local.did, opts.server, !!opts.json);
+      if (waitSeconds > 0) {
+        console.log(import_chalk30.default.dim(`Waiting ${waitSeconds}s for the recipient handler to pick up the new secret before commit\u2026`));
+        await (0, import_promises.setTimeout)(waitSeconds * 1e3);
+      } else {
+        console.log(
+          import_chalk30.default.yellow(
+            "--wait-before-commit=0: committing immediately. Recipient must already be running in dual-key mode (verifying against [current, next]) or HMAC verification will gap until the handler restarts."
+          )
+        );
+      }
+      await doCommitWithStaged(api, signer, local.did, opts.server, staged, !!opts.json);
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+}
+async function doStage(api, signer, did, server, asJson) {
+  const out = await api.rotateStageMyWebhookSecret(signer);
+  if (out.slot !== "pending" || !out.rotationId) {
+    throw new Error(
+      `webhook secret rotate-stage: unexpected server response \u2014 expected slot='pending' + rotationId, got slot='${out.slot}' rotationId='${out.rotationId ?? ""}'`
+    );
+  }
+  const writeResult = updateAgentLocal(server, did, {
+    webhookSecretB64Next: out.webhookSecretB64,
+    webhookRotationId: out.rotationId
+  });
+  warnIfChmodFailed(writeResult);
+  if (asJson) {
+    console.log(formatJson({ ...out, webhookSecretB64: REDACTED_SECRET_MARKER, persisted: true }));
+  } else {
+    console.log(import_chalk30.default.green("Phase 1 (stage) complete:"));
+    console.log(import_chalk30.default.dim("  New secret staged server-side; server still signs with the CURRENT secret."));
+    console.log(import_chalk30.default.dim("  Stored locally under `webhookSecretB64Next` \u2014 your handler should now verify against BOTH current + next."));
+    console.log(import_chalk30.default.dim(`  rotationId: ${out.rotationId} (threaded into the matching commit call).`));
+  }
+  return { rotationId: out.rotationId, pendingSecretB64: out.webhookSecretB64 };
+}
+async function doCommitWithStaged(api, signer, did, server, staged, asJson) {
+  const fresh = resolveSenderAgent("webhook secret rotate --commit", server, did);
+  await runCommitAndSwap(api, signer, fresh, server, did, staged.rotationId, staged.pendingSecretB64, asJson);
+}
+async function doCommitFromLocalState(api, signer, did, server, asJson) {
+  const fresh = resolveSenderAgent("webhook secret rotate --commit", server, did);
+  if (!fresh.webhookSecretB64Next || !fresh.webhookRotationId) {
+    throw new Error(
+      "webhook secret rotate --commit: no staged secret found in local state. Run `webhook secret rotate --stage` first, or use the no-flag form to do both phases in one invocation."
+    );
+  }
+  await runCommitAndSwap(api, signer, fresh, server, did, fresh.webhookRotationId, fresh.webhookSecretB64Next, asJson);
+}
+async function runCommitAndSwap(api, signer, fresh, server, did, rotationId, pendingSecretB64, asJson) {
+  let out;
+  try {
+    out = await api.rotateCommitMyWebhookSecret({ rotationId }, signer);
+  } catch (err) {
+    if (err instanceof ApiError && err.payload.code === "WEBHOOK_SECRET_ROTATION_ID_MISMATCH") {
+      throw new Error(
+        `webhook secret rotate --commit: rotationId mismatch (a concurrent --stage ran). Run \`webhook secret rotate --stage\` again, then commit with the fresh token. Local state PRESERVED \u2014 your current secret still works.`
+      );
+    }
+    throw err;
+  }
+  const writeResult = updateAgentLocal(server, did, {
+    webhookSecretB64Previous: fresh.webhookSecretB64,
+    webhookSecretB64: pendingSecretB64,
+    webhookSecretB64Next: void 0,
+    webhookRotationId: void 0,
+    webhookSecretPreviousExpiresAt: out.previousSecretExpiresAt
+  });
+  warnIfChmodFailed(writeResult);
+  if (asJson) {
+    console.log(formatJson(out));
+    return;
+  }
+  console.log(import_chalk30.default.green("Phase 2 (commit) complete:"));
+  console.log(import_chalk30.default.dim("  Server now signs with the NEW secret. Old secret kept in `webhookSecretB64Previous` for the grace window."));
+  console.log(`  ${import_chalk30.default.bold("Grace expires:")} ${import_chalk30.default.cyan(out.previousSecretExpiresAt)} \u2014 after this, your handler can drop the previous secret on next restart.`);
+}
+async function promptYesNo(question) {
+  process.stdout.write(`${question} (y/N): `);
+  return new Promise((resolve2) => {
+    const onData = (chunk) => {
+      const answer = chunk.toString("utf8").trim().toLowerCase();
+      process.stdin.pause();
+      process.stdin.off("data", onData);
+      resolve2(answer === "y" || answer === "yes");
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+
 // src/commands/whoami.ts
-var import_chalk28 = __toESM(require("chalk"));
+var import_chalk31 = __toESM(require("chalk"));
 init_api();
 function registerWhoamiCommand(root) {
   root.command("whoami").description(
@@ -7266,10 +8531,10 @@ function registerWhoamiCommand(root) {
         if (opts.json) {
           console.log(formatJson(localJson));
         } else {
-          console.log(import_chalk28.default.bold("Local agent:"));
-          console.log(`  DID:                ${import_chalk28.default.cyan(local.did)}`);
-          console.log(`  Settlement pubkey:  ${import_chalk28.default.cyan(local.settlementPublicKeyB58)}`);
-          console.log(`  Identity pubkey:    ${import_chalk28.default.cyan(local.identityPublicKeyB58)}`);
+          console.log(import_chalk31.default.bold("Local agent:"));
+          console.log(`  DID:                ${import_chalk31.default.cyan(local.did)}`);
+          console.log(`  Settlement pubkey:  ${import_chalk31.default.cyan(local.settlementPublicKeyB58)}`);
+          console.log(`  Identity pubkey:    ${import_chalk31.default.cyan(local.identityPublicKeyB58)}`);
           console.log(`  Key mode:           ${local.keyMode}`);
           if (local.name) console.log(`  Name:               ${local.name}`);
         }
@@ -7281,24 +8546,24 @@ function registerWhoamiCommand(root) {
       if (opts.json) {
         console.log(formatJson({ local: localJson, server: agent }));
       } else {
-        console.log(import_chalk28.default.dim(`Server: ${api.serverUrl}`));
-        console.log(import_chalk28.default.bold("\nLocal agent:"));
-        console.log(`  DID:                ${import_chalk28.default.cyan(local.did)}`);
-        console.log(`  Settlement pubkey:  ${import_chalk28.default.cyan(local.settlementPublicKeyB58)}`);
-        console.log(`  Identity pubkey:    ${import_chalk28.default.cyan(local.identityPublicKeyB58)}`);
-        console.log(import_chalk28.default.bold("\nServer profile:"));
+        console.log(import_chalk31.default.dim(`Server: ${api.serverUrl}`));
+        console.log(import_chalk31.default.bold("\nLocal agent:"));
+        console.log(`  DID:                ${import_chalk31.default.cyan(local.did)}`);
+        console.log(`  Settlement pubkey:  ${import_chalk31.default.cyan(local.settlementPublicKeyB58)}`);
+        console.log(`  Identity pubkey:    ${import_chalk31.default.cyan(local.identityPublicKeyB58)}`);
+        console.log(import_chalk31.default.bold("\nServer profile:"));
         console.log(formatJson(agent));
       }
     } catch (err) {
-      console.error(formatActionError(err, cmd));
+      emitActionError(err, cmd);
       process.exitCode = 1;
     }
   });
 }
 
 // src/commands/work.ts
-var import_sdk16 = require("@heyanon-arp/sdk");
-var import_chalk29 = __toESM(require("chalk"));
+var import_sdk17 = require("@heyanon-arp/sdk");
+var import_chalk32 = __toESM(require("chalk"));
 init_api();
 function registerWorkCommands(root) {
   const cmd = root.command("work").description("Work envelopes inside an ACCEPTED delegation: request / respond");
@@ -7340,17 +8605,17 @@ async function runRequest(recipientDid, delegationId, opts) {
     params
   };
   const body = { type: "work_request", content };
-  console.log(import_chalk29.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk29.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk29.default.dim(`Recipient: ${recipientDid}`));
-  console.log(import_chalk29.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk29.default.dim(`Request id: ${requestId}`));
+  console.log(import_chalk32.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk32.default.dim(`Sender: ${sender.did}`));
+  console.log(import_chalk32.default.dim(`Recipient: ${recipientDid}`));
+  console.log(import_chalk32.default.dim(`Delegation: ${delegationId}`));
+  console.log(import_chalk32.default.dim(`Request id: ${requestId}`));
   const result = await sendWorkEnvelope({ api, sender, recipientDid, body, ttlSeconds, verbose: opts.verbose, server: opts.server });
   printIngestResult4(result);
-  console.log(import_chalk29.default.dim(`
+  console.log(import_chalk32.default.dim(`
 The payee can reply with:`));
-  console.log(import_chalk29.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --output '<json>'`));
-  console.log(import_chalk29.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --error CODE:message`));
+  console.log(import_chalk32.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --output '<json>'`));
+  console.log(import_chalk32.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --error CODE:message`));
 }
 function registerRespond(parent) {
   parent.command("respond").description("Send a work_response under <relationship-id> for <delegation-id> / <request-id>. Payee-only.").argument("<relationship-id>", "Relationship UUID").argument("<delegation-id>", "Parent delegation id (UUID)").argument("<request-id>", "Request id supplied on the work_request").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--output <json>", "Success payload as a JSON object literal. Mutually exclusive with --error and --output-file.").option(
@@ -7375,13 +8640,13 @@ async function runRespond(relationshipId, delegationId, requestId, opts) {
     ...responsePayload
   };
   const body = { type: "work_response", content };
-  console.log(import_chalk29.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk29.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk29.default.dim(`Recipient: ${recipientDid}`));
-  console.log(import_chalk29.default.dim(`Relationship: ${relationshipId}`));
-  console.log(import_chalk29.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk29.default.dim(`Request id: ${requestId}`));
-  console.log(import_chalk29.default.dim(`Outcome: ${responsePayload.output ? "success" : "error"}`));
+  console.log(import_chalk32.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk32.default.dim(`Sender: ${sender.did}`));
+  console.log(import_chalk32.default.dim(`Recipient: ${recipientDid}`));
+  console.log(import_chalk32.default.dim(`Relationship: ${relationshipId}`));
+  console.log(import_chalk32.default.dim(`Delegation: ${delegationId}`));
+  console.log(import_chalk32.default.dim(`Request id: ${requestId}`));
+  console.log(import_chalk32.default.dim(`Outcome: ${responsePayload.output ? "success" : "error"}`));
   const result = await sendWorkEnvelope({ api, sender, recipientDid, body, ttlSeconds, verbose: opts.verbose, server: opts.server });
   printIngestResult4(result);
 }
@@ -7389,25 +8654,25 @@ async function sendWorkEnvelope(args) {
   const nextSequence = (args.sender.lastSenderSequence ?? 0) + 1;
   const protectedBlock = {
     protocol_version: "arp/0.1",
-    purpose: import_sdk16.Purpose.ENVELOPE,
-    message_id: (0, import_sdk16.uuidV4)(),
+    purpose: import_sdk17.Purpose.ENVELOPE,
+    message_id: (0, import_sdk17.uuidV4)(),
     sender_did: args.sender.did,
     recipient_did: args.recipientDid,
     relationship_id: null,
     sender_sequence: nextSequence,
-    sender_nonce: (0, import_sdk16.senderNonce)(),
-    timestamp: (0, import_sdk16.rfc3339)(),
-    expires_at: (0, import_sdk16.expiresAt)(args.ttlSeconds),
+    sender_nonce: (0, import_sdk17.senderNonce)(),
+    timestamp: (0, import_sdk17.rfc3339)(),
+    expires_at: (0, import_sdk17.expiresAt)(args.ttlSeconds),
     delivery_id: null
   };
   const signer = makeSigner(args.sender);
-  const envelope = (0, import_sdk16.signEnvelope)({
+  const envelope = (0, import_sdk17.signEnvelope)({
     protected: protectedBlock,
     body: args.body,
     identitySecretKey: signer.identitySecretKey
   });
   if (args.verbose) {
-    console.log(import_chalk29.default.bold("\nEnvelope (pre-send):"));
+    console.log(import_chalk32.default.bold("\nEnvelope (pre-send):"));
     console.log(formatJson(envelope));
   }
   try {
@@ -7447,12 +8712,12 @@ async function resolveResponseRecipient(cmdName, api, signer, args) {
   );
 }
 function printIngestResult4(result) {
-  console.log(import_chalk29.default.green("\nDelivered."));
-  console.log(`${import_chalk29.default.bold("Event id")}: ${import_chalk29.default.cyan(result.eventId)}`);
-  console.log(`${import_chalk29.default.bold("Relationship id")}: ${import_chalk29.default.cyan(result.relationshipId)}`);
-  console.log(`${import_chalk29.default.bold("Chain index")}: ${import_chalk29.default.cyan(String(result.relationshipEventIndex))}`);
-  console.log(`${import_chalk29.default.bold("Server timestamp")}: ${import_chalk29.default.cyan(result.serverTimestamp)}`);
-  console.log(`${import_chalk29.default.bold("Server event hash")}: ${import_chalk29.default.cyan(result.serverEventHash)}`);
+  console.log(import_chalk32.default.green("\nDelivered."));
+  console.log(`${import_chalk32.default.bold("Event id")}: ${import_chalk32.default.cyan(result.eventId)}`);
+  console.log(`${import_chalk32.default.bold("Relationship id")}: ${import_chalk32.default.cyan(result.relationshipId)}`);
+  console.log(`${import_chalk32.default.bold("Chain index")}: ${import_chalk32.default.cyan(String(result.relationshipEventIndex))}`);
+  console.log(`${import_chalk32.default.bold("Server timestamp")}: ${import_chalk32.default.cyan(result.serverTimestamp)}`);
+  console.log(`${import_chalk32.default.bold("Server event hash")}: ${import_chalk32.default.cyan(result.serverEventHash)}`);
 }
 function parseJsonObject(cmdName, flagName, raw) {
   let parsed;
@@ -7490,13 +8755,13 @@ function parseParamsInput(cmdName, opts) {
   return parseJsonObject(cmdName, "--params", opts.params ?? "{}");
 }
 function readJsonObjectFile(cmdName, flagName, path) {
-  const { existsSync: existsSync6, readFileSync: readFileSync8 } = require("fs");
-  if (!existsSync6(path)) {
+  const { existsSync: existsSync7, readFileSync: readFileSync9 } = require("fs");
+  if (!existsSync7(path)) {
     throw new Error(`${cmdName}: ${flagName} file not found at ${path}`);
   }
   let raw;
   try {
-    raw = readFileSync8(path, "utf8");
+    raw = readFileSync9(path, "utf8");
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
     throw new Error(`${cmdName}: failed to read ${flagName} (${path}): ${detail}`);
@@ -7544,7 +8809,7 @@ function parseTtl7(cmdName, raw) {
 }
 function parseRequestId(cmdName, raw) {
   if (raw === void 0 || raw === "") {
-    return (0, import_sdk16.uuidV4)();
+    return (0, import_sdk17.uuidV4)();
   }
   if (raw.length === 0) {
     throw new Error(`${cmdName}: --request-id must be a non-empty string`);
@@ -7565,7 +8830,7 @@ function requireDid4(cmdName, did, label) {
 }
 
 // src/commands/work-list.ts
-var import_chalk30 = __toESM(require("chalk"));
+var import_chalk33 = __toESM(require("chalk"));
 init_api();
 var ALLOWED_STATES5 = /* @__PURE__ */ new Set(["requested", "responded"]);
 function registerWorkListCommand(root) {
@@ -7592,9 +8857,9 @@ async function runWorkList(relationshipId, opts) {
   const api = new ArpApiClient(opts.server);
   const sender = resolveSenderAgent("work-list", opts.server, opts.fromDid);
   if (!opts.json) {
-    console.log(import_chalk30.default.dim(`Server: ${api.serverUrl}`));
-    console.log(import_chalk30.default.dim(`Signer: ${sender.did}`));
-    console.log(import_chalk30.default.dim(`Relationship: ${relationshipId}`));
+    console.log(import_chalk33.default.dim(`Server: ${api.serverUrl}`));
+    console.log(import_chalk33.default.dim(`Signer: ${sender.did}`));
+    console.log(import_chalk33.default.dim(`Relationship: ${relationshipId}`));
   }
   const query = { limit };
   if (state) query.state = state;
@@ -7607,7 +8872,7 @@ async function runWorkList(relationshipId, opts) {
     return;
   }
   if (rows.length === 0) {
-    console.log(import_chalk30.default.dim("\n(no work-logs for this relationship)"));
+    console.log(import_chalk33.default.dim("\n(no work-logs for this relationship)"));
     return;
   }
   console.log("");
@@ -7624,36 +8889,36 @@ async function runWorkList(relationshipId, opts) {
     }));
   }
   const lastId = rows[rows.length - 1].id;
-  console.log(import_chalk30.default.dim(`
+  console.log(import_chalk33.default.dim(`
 ${rows.length} work-log row(s). Paginate with --after ${lastId}.`));
 }
 function formatWorkLogLine(w, selfDid, opts = {}) {
   const delegationPart = opts.fullIds ? w.delegationId : idHead4(w.delegationId);
   const requestPart = opts.fullIds ? w.requestId : truncate4(w.requestId, 16);
-  const id = import_chalk30.default.bold(`${delegationPart}/${requestPart}`);
+  const id = import_chalk33.default.bold(`${delegationPart}/${requestPart}`);
   const state = colorState4(w.state).padEnd(stateColumnWidth4());
   const peerCallerHead = opts.fullIds ? w.callerDid : didHead6(w.callerDid);
   const peerPayeeHead = opts.fullIds ? w.payeeDid : didHead6(w.payeeDid);
-  const direction = w.callerDid === selfDid ? `${import_chalk30.default.bold("me")} \u2192 ${import_chalk30.default.dim(peerPayeeHead)}` : `${import_chalk30.default.dim(peerCallerHead)} \u2192 ${import_chalk30.default.bold("me")}`;
+  const direction = w.callerDid === selfDid ? `${import_chalk33.default.bold("me")} \u2192 ${import_chalk33.default.dim(peerPayeeHead)}` : `${import_chalk33.default.dim(peerCallerHead)} \u2192 ${import_chalk33.default.bold("me")}`;
   const outcome = formatOutcome(w);
   return `${id}  ${state}  ${direction}  ${outcome}`;
 }
 function colorState4(s) {
   switch (s) {
     case "requested":
-      return import_chalk30.default.yellow("requested");
+      return import_chalk33.default.yellow("requested");
     case "responded":
-      return import_chalk30.default.green("responded");
+      return import_chalk33.default.green("responded");
   }
 }
 function stateColumnWidth4() {
   return 9;
 }
 function formatOutcome(w) {
-  if (w.state === "requested") return import_chalk30.default.dim("(in flight)");
-  if (w.responseError) return import_chalk30.default.red(`error ${w.responseError.code}: ${truncate4(w.responseError.message, 32)}`);
-  if (w.responseOutput) return import_chalk30.default.cyan("ok");
-  return import_chalk30.default.dim("(empty response)");
+  if (w.state === "requested") return import_chalk33.default.dim("(in flight)");
+  if (w.responseError) return import_chalk33.default.red(`error ${w.responseError.code}: ${truncate4(w.responseError.message, 32)}`);
+  if (w.responseOutput) return import_chalk33.default.cyan("ok");
+  return import_chalk33.default.dim("(empty response)");
 }
 function idHead4(id) {
   if (id.length <= 12) return id;
@@ -7698,6 +8963,13 @@ async function main() {
   void checkForUpdates();
   const program = new import_commander.Command();
   program.name("heyarp").description("ARP \u2014 Agent Relationship Protocol CLI (talks to apps/arp-server)").version(package_default.version).option("--trace", "Surface stack traces and error details on failure.", false);
+  program.exitOverride();
+  program.configureOutput({
+    writeErr: (str) => {
+      if (process.argv.includes("--json")) return;
+      process.stderr.write(str);
+    }
+  });
   registerConfigCommand(program);
   registerGuideCommand(program);
   registerHomesCommand(program);
@@ -7708,6 +8980,7 @@ async function main() {
   registerDidDocCommand(program);
   registerDoctorCommand(program);
   registerEscrowCommands(program);
+  registerExamplesCommand(program);
   registerWhoamiCommand(program);
   registerLifecycleCommands(program);
   registerRotateCommand(program);
@@ -7729,16 +9002,24 @@ async function main() {
   registerReceiptsCommand(program);
   registerMemoryCommands(program);
   registerWalletCommands(program);
+  registerWebhookCommand(program);
+  registerSettlementCommands(program);
   try {
     await program.parseAsync(process.argv);
   } catch (err) {
-    const verbose = !!program.opts().trace;
-    if (err instanceof ApiError) {
-      console.error(formatApiError(err.payload, verbose));
-    } else {
-      console.error(formatGenericError(err, verbose));
-    }
-    process.exit(1);
+    const cerr = err;
+    const isCommanderError = typeof cerr.code === "string" && cerr.code.startsWith("commander.");
+    if (isCommanderError && cerr.exitCode === 0) {
+      process.exit(0);
+    }
+    const json = process.argv.includes("--json");
+    const verbose = process.argv.includes("--trace");
+    const exitCode = typeof cerr.exitCode === "number" && cerr.exitCode !== 0 ? cerr.exitCode : 1;
+    if (isCommanderError && !json) {
+      process.exit(exitCode);
+    }
+    emitError(err, { json, verbose });
+    process.exit(exitCode);
   }
 }
 process.on("unhandledRejection", (reason) => {