@heyanon-arp/cli 0.0.3 → 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
@@ -431,9 +456,7 @@ var init_api = __esm({
        * known but has never been party to an event.
        */
       async getActivitySummary(did) {
-        return this.get(
-          `/v1/agents/${encodeURIComponent(did)}/activity-summary`
-        );
+        return this.get(`/v1/agents/${encodeURIComponent(did)}/activity-summary`);
       }
       /**
        * Signed `GET /v1/agents/:did/sender-sequence`. Returns the highest
@@ -712,27 +735,17 @@ var import_simple_update_notifier = __toESM(require("simple-update-notifier"));
 // package.json
 var package_default = {
   name: "@heyanon-arp/cli",
-  version: "0.0.3",
+  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"
-  ],
+  keywords: ["arp", "agent-relationship-protocol", "did", "solana", "escrow", "ed25519", "agents", "a2a", "cli"],
   bin: {
     heyarp: "./dist/cli.js"
   },
   publishConfig: {
     access: "public"
   },
-  files: ["dist", "LICENSE", "README.md"],
+  files: ["dist", "examples", "LICENSE", "README.md"],
   engines: {
     node: ">=22"
   },
@@ -765,9 +778,6 @@ var package_default = {
   }
 };
 
-// src/cli.ts
-init_api();
-
 // src/commands/agents.ts
 var import_chalk2 = __toESM(require("chalk"));
 init_api();
@@ -789,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);
@@ -837,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)");
@@ -876,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;
@@ -1111,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);
@@ -1145,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);
@@ -1177,8 +1242,8 @@ function listAgents() {
 }
 
 // src/commands/delegation.ts
-var import_sdk4 = require("@heyanon-arp/sdk");
 var import_node_fs4 = require("fs");
+var import_sdk4 = require("@heyanon-arp/sdk");
 var import_chalk6 = __toESM(require("chalk"));
 init_api();
 
@@ -1256,14 +1321,6 @@ ${verb}.`));
   console.log(formatJson(agent));
 }
 
-// src/commands/wallet.ts
-var import_sdk3 = require("@heyanon-arp/sdk");
-var import_utils = require("@noble/hashes/utils");
-var import_web3 = require("@solana/web3.js");
-var import_node_fs3 = require("fs");
-init_api();
-init_config();
-
 // src/commands/status.ts
 var import_sdk2 = require("@heyanon-arp/sdk");
 var import_chalk5 = __toESM(require("chalk"));
@@ -1349,6 +1406,25 @@ async function runStatus(relationshipId, opts) {
     process.exitCode = 124;
   }
 }
+async function awaitFsmTransitionAfterAction(input) {
+  const { api, signerDid, signer, relationshipId, untilPhase, waitIntervalSec, waitTimeoutSec, waitVerbose, json } = input;
+  if (!json) {
+    console.log(import_chalk5.default.dim(`
+[--wait-until ${untilPhase}] polling relationship ${relationshipId} (interval=${waitIntervalSec}s timeout=${waitTimeoutSec}s)`));
+  }
+  const outcome = await runWaitLoop({
+    fetchSummary: () => composeStatus(api, signerDid, relationshipId, signer),
+    waitIntervalSec,
+    waitTimeoutSec,
+    waitVerbose: !!waitVerbose,
+    json: !!json,
+    log: (line) => console.log(line),
+    until: untilPhase
+  });
+  if (outcome.timedOut) {
+    process.exitCode = 124;
+  }
+}
 async function runWaitLoop(opts) {
   const isTerminal = (s) => s.cycleComplete || s.relationshipState === "closed" || s.relationshipState === "not_found";
   const isActionable = (s) => {
@@ -1382,8 +1458,12 @@ async function runWaitLoop(opts) {
     if (opts.json) opts.log(JSON.stringify(terminalUnmatchedJson ? { ...initial, _waitTimedOut: true } : initial));
     else {
       if (opts.until !== void 0) {
-        opts.log(import_chalk5.default.yellow(`
-[--wait] Terminal state (${initial.relationshipState}, cycleComplete=${initial.cycleComplete}) reached before phase '${opts.until}' \u2014 exiting; phase unreachable.`));
+        opts.log(
+          import_chalk5.default.yellow(
+            `
+[--wait] Terminal state (${initial.relationshipState}, cycleComplete=${initial.cycleComplete}) reached before phase '${opts.until}' \u2014 exiting; phase unreachable.`
+          )
+        );
       } else {
         opts.log(import_chalk5.default.dim(`
 [--wait] Already terminal \u2014 exiting.`));
@@ -1433,7 +1513,11 @@ async function runWaitLoop(opts) {
           if (phaseReached) {
             opts.log(import_chalk5.default.green(`[--wait] Phase '${opts.until}' reached.`));
           } else {
-            opts.log(import_chalk5.default.yellow(`[--wait] Terminal state (${next.relationshipState}, cycleComplete=${next.cycleComplete}) reached before phase '${opts.until}' \u2014 phase unreachable.`));
+            opts.log(
+              import_chalk5.default.yellow(
+                `[--wait] Terminal state (${next.relationshipState}, cycleComplete=${next.cycleComplete}) reached before phase '${opts.until}' \u2014 phase unreachable.`
+              )
+            );
           }
         } else {
           opts.log(import_chalk5.default.green(`[--wait] ${isTerminal(next) ? "Cycle terminated" : `Your turn (owner=${next.nextActionOwner})`}.`));
@@ -1448,11 +1532,17 @@ async function runWaitLoop(opts) {
     opts.log(JSON.stringify({ ...last, _waitTimedOut: true }));
   } else {
     if (opts.until !== void 0) {
-      opts.log(import_chalk5.default.yellow(`
-[--wait] Timed out after ${opts.waitTimeoutSec}s without reaching phase '${opts.until}' (latest state: ${last.relationshipState}, hint: ${last.nextActionHint}).`));
+      opts.log(
+        import_chalk5.default.yellow(
+          `
+[--wait] Timed out after ${opts.waitTimeoutSec}s without reaching phase '${opts.until}' (latest state: ${last.relationshipState}, hint: ${last.nextActionHint}).`
+        )
+      );
     } else {
-      opts.log(import_chalk5.default.yellow(`
-[--wait] Timed out after ${opts.waitTimeoutSec}s without an actionable or terminal transition (your turn never came, cycle still in flight).`));
+      opts.log(
+        import_chalk5.default.yellow(`
+[--wait] Timed out after ${opts.waitTimeoutSec}s without an actionable or terminal transition (your turn never came, cycle still in flight).`)
+      );
     }
   }
   return { timedOut: true, last };
@@ -1533,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([
@@ -1574,13 +1664,7 @@ async function composeStatus(api, signerDid, relationshipId, signer) {
   const delegations = latestContract ? await fetchAllPages(
     (after) => api.listDelegations(relationshipId, signer, { limit: 100, contractId: latestContract.contractId, ...after ? { after } : {} })
   ) : [];
-  const latestDelegation = pickLatestLive(delegations, [
-    "proposed",
-    "offered",
-    "pending_lock_finalization",
-    "accepted",
-    "awaiting_release_finalization"
-  ]);
+  const latestDelegation = pickLatestLive(delegations, ["proposed", "offered", "pending_lock_finalization", "accepted", "awaiting_release_finalization"]);
   const [workLogs, receipts] = await Promise.all([
     latestDelegation ? fetchAllPages(
       (after) => api.listWorkLogs(relationshipId, signer, { limit: 100, delegationId: latestDelegation.delegationId, ...after ? { after } : {} })
@@ -1650,9 +1734,7 @@ function findReceiptForWorkLog(receipts, workLog, allWorkLogs = [workLog]) {
   const expectedResponseHash = (0, import_sdk2.canonicalSha256Hex)(responseBody);
   const matches = receipts.filter((r) => r.requestHash === expectedRequestHash && r.responseHash === expectedResponseHash);
   if (matches.length > 0) return pickLatest(matches);
-  const respondedSiblings = allWorkLogs.filter(
-    (wl) => wl.delegationId === workLog.delegationId && (wl.responseOutput !== void 0 || wl.responseError !== void 0)
-  ).length;
+  const respondedSiblings = allWorkLogs.filter((wl) => wl.delegationId === workLog.delegationId && (wl.responseOutput !== void 0 || wl.responseError !== void 0)).length;
   if (respondedSiblings > 1) return null;
   const sameDelegation = receipts.filter((r) => r.delegationId === workLog.delegationId);
   return pickLatest(sameDelegation);
@@ -1878,6 +1960,12 @@ function stateColor(state) {
 }
 
 // src/commands/wallet.ts
+var import_node_fs3 = require("fs");
+var import_sdk3 = require("@heyanon-arp/sdk");
+var import_utils = require("@noble/hashes/utils");
+var import_web3 = require("@solana/web3.js");
+init_api();
+init_config();
 function bytesToBase64(bytes) {
   return Buffer.from(bytes).toString("base64");
 }
@@ -1967,22 +2055,10 @@ function registerDerivePdas(cmd) {
   ).requiredOption("--delegation-id <id>", "Delegation UUID (canonical `del_<uuid>` or bare `<uuid>` \u2014 both accepted)").option("--server <url>", "Override server URL (used only for --program-id auto-discovery)").option(
     "--program-id <pubkey>",
     `Deployed ARP escrow program id. Precedence: --program-id flag > ARP_ESCROW_PROGRAM_ID env > GET /v1/escrow/protocol-fee (auto-discover) > hardcoded fallback (${FALLBACK_PROGRAM_ID}).`
-  ).option(
-    "--rpc-url <url>",
-    "Accepted for symmetry with `wallet verify-release` but never read \u2014 PDAs are derived locally from `program_id + delegation_id`; no RPC needed."
-  ).option(
+  ).option("--rpc-url <url>", "Accepted for symmetry with `wallet verify-release` but never read \u2014 PDAs are derived locally from `program_id + delegation_id`; no RPC needed.").option(
     "--recipient-pubkey <base58>",
     "Accepted for symmetry with `wallet create-lock` but never read \u2014 PDAs depend ONLY on program_id + delegation_id; recipient pubkey has no derivation role."
-  ).option(
-    "--condition-hash <hex>",
-    "Accepted for symmetry with `wallet create-lock` but never read \u2014 PDAs depend ONLY on program_id + delegation_id."
-  ).option(
-    "--amount-lamports <int>",
-    "Accepted for symmetry with `wallet create-lock` but never read \u2014 PDAs depend ONLY on program_id + delegation_id."
-  ).option(
-    "--expiry-secs <int>",
-    "Accepted for symmetry with `wallet create-lock` but never read \u2014 PDAs depend ONLY on program_id + delegation_id."
-  ).option("--json", "Emit JSON instead of human text (jq-pipeable: `.lock_pda`, `.escrow_pda`, `.config_pda`, `.lock_id_hex`).", false).action(async (opts) => {
+  ).option("--condition-hash <hex>", "Accepted for symmetry with `wallet create-lock` but never read \u2014 PDAs depend ONLY on program_id + delegation_id.").option("--amount-lamports <int>", "Accepted for symmetry with `wallet create-lock` but never read \u2014 PDAs depend ONLY on program_id + delegation_id.").option("--expiry-secs <int>", "Accepted for symmetry with `wallet create-lock` but never read \u2014 PDAs depend ONLY on program_id + delegation_id.").option("--json", "Emit JSON instead of human text (jq-pipeable: `.lock_pda`, `.escrow_pda`, `.config_pda`, `.lock_id_hex`).", false).action(async (opts) => {
     try {
       const out = await derivePdasHandler(opts);
       if (opts.json) {
@@ -1997,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);
     }
   });
@@ -2059,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);
     }
   });
@@ -2100,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;
@@ -2240,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);
     }
   });
@@ -2260,7 +2336,7 @@ async function preflightLockCurrency(api, agent, normalisedDelegationId, contrac
       })
     ]);
   } catch (err) {
-    if (err instanceof Error && err.message.includes("NF-R13-05")) throw err;
+    if (err instanceof Error && err.message.includes("LOCK_CURRENCY_NON_NATIVE_SOL")) throw err;
   } finally {
     if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
   }
@@ -2284,7 +2360,9 @@ async function preflightLockCurrencyInner(api, agent, normalisedDelegationId, si
     if (contractId !== void 0) {
       let activeContracts;
       try {
-        activeContracts = await fetchAllPages((after) => api.listContracts(r.relationshipId, signer, { limit: 100, state: "active", ...after ? { after } : {} }, signal));
+        activeContracts = await fetchAllPages(
+          (after) => api.listContracts(r.relationshipId, signer, { limit: 100, state: "active", ...after ? { after } : {} }, signal)
+        );
       } catch {
         activeContracts = [];
       }
@@ -2293,7 +2371,7 @@ async function preflightLockCurrencyInner(api, agent, normalisedDelegationId, si
         const directAssetId = directContract.rateCurrency?.assetId;
         if (typeof directAssetId === "string" && !directAssetId.endsWith("/slip44:501")) {
           throw new Error(
-            `wallet create-lock pre-flight (NF-R13-05): contract ${contractId} is priced in '${directAssetId}' (NOT native SOL). This command only builds native-SOL locks (isNativeSol=1, no SPL Token-2022 path) \u2014 the resulting tx blob would be rejected server-side with ESC_LOCK_CURRENCY_MISMATCH or ESC_LOCK_AMOUNT_DELEGATION_MISMATCH after \`delegation offer\` ships it. Use a SOL-priced contract (e.g. \`--rate-currency 'SOL:solana-mainnet'\` on \`contract propose\`) or wait for SPL-token lock support to land.`
+            `wallet create-lock pre-flight (LOCK_CURRENCY_NON_NATIVE_SOL): contract ${contractId} is priced in '${directAssetId}' (NOT native SOL). This command only builds native-SOL locks (isNativeSol=1, no SPL Token-2022 path) \u2014 the resulting tx blob would be rejected server-side with ESC_LOCK_CURRENCY_MISMATCH or ESC_LOCK_AMOUNT_DELEGATION_MISMATCH after \`delegation offer\` ships it. Use a SOL-priced contract (e.g. \`--rate-currency 'SOL:solana-mainnet'\` on \`contract propose\`) or wait for SPL-token lock support to land.`
           );
         }
       }
@@ -2308,7 +2386,9 @@ async function preflightLockCurrencyInner(api, agent, normalisedDelegationId, si
     if (!match) continue;
     let contracts = [];
     try {
-      contracts = await fetchAllPages((after) => api.listContracts(r.relationshipId, signer, { limit: 100, state: "active", ...after ? { after } : {} }, signal));
+      contracts = await fetchAllPages(
+        (after) => api.listContracts(r.relationshipId, signer, { limit: 100, state: "active", ...after ? { after } : {} }, signal)
+      );
     } catch {
     }
     const contract = contracts.find((c) => c.contractId === match.contractId);
@@ -2323,7 +2403,7 @@ async function preflightLockCurrencyInner(api, agent, normalisedDelegationId, si
     const offendingAssetId = isContractNonNative ? contractAssetId : delegationAssetId;
     const sourceLabel = isContractNonNative ? `contract ${match.contractId}` : `delegation ${normalisedDelegationId}`;
     throw new Error(
-      `wallet create-lock pre-flight (NF-R13-05): ${sourceLabel} is priced in '${offendingAssetId}' (NOT native SOL). This command only builds native-SOL locks (isNativeSol=1, no SPL Token-2022 path) \u2014 the resulting tx blob would be rejected server-side with ESC_LOCK_CURRENCY_MISMATCH or ESC_LOCK_AMOUNT_DELEGATION_MISMATCH after \`delegation offer\` ships it. Use a SOL-priced contract (e.g. \`--rate-currency 'SOL:solana-mainnet'\` on \`contract propose\`) or wait for SPL-token lock support to land.`
+      `wallet create-lock pre-flight (LOCK_CURRENCY_NON_NATIVE_SOL): ${sourceLabel} is priced in '${offendingAssetId}' (NOT native SOL). This command only builds native-SOL locks (isNativeSol=1, no SPL Token-2022 path) \u2014 the resulting tx blob would be rejected server-side with ESC_LOCK_CURRENCY_MISMATCH or ESC_LOCK_AMOUNT_DELEGATION_MISMATCH after \`delegation offer\` ships it. Use a SOL-priced contract (e.g. \`--rate-currency 'SOL:solana-mainnet'\` on \`contract propose\`) or wait for SPL-token lock support to land.`
     );
   }
 }
@@ -2451,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);
     }
   });
@@ -2607,10 +2687,23 @@ function registerOffer(parent) {
   parent.command("offer").description("Open a new delegation under <contract-id> (must be ACTIVE) addressed to <recipient-did>.").argument("<recipient-did>", "Recipient agent DID (did:arp:...)").argument("<contract-id>", "Contract id this delegation operates under (must be ACTIVE)").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("--delegation-id <uuid>", "Override the auto-generated delegation id (UUID). Useful for replay / scripting.").option("--title <s>", "Required: human-readable title for the offer").option("--brief <json>", "Optional structured brief (JSON object)").option("--criterion <s>", "acceptance_criteria \u2014 repeatable; pass --criterion once per bullet", collectRepeated, []).option("--deadline <rfc3339>", 'Optional RFC 3339 deadline (e.g. "2026-12-31T23:59:59Z")').option("--amount <s>", 'Optional decimal-as-string amount (e.g. "10.00"). REQUIRES --currency if set.').option("--currency <s>", `Asset identifier: shorthand (${import_sdk4.WELL_KNOWN_ASSET_KEYS.join("|")}) OR raw CAIP-19 string.`).option("--currency-decimals <n>", "Decimal places for base-unit conversion (0-18). Required only when --currency is raw CAIP-19.").option("--currency-symbol <s>", 'Optional UI hint ("USDC", "SOL"). Max 16 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(
     "--escrow-lock-from-file <path>",
     "Path to JSON output of `heyarp wallet create-lock` (recommended). Contains all 5 escrow_lock fields: signed_tx_blob, lock_id, amount, asset_id, expiry. Mutually exclusive with the inline --escrow-lock-* flags below."
-  ).option("--escrow-lock-blob <base64>", "INLINE alternative: the signed Solana tx blob (base64). Requires --escrow-lock-id, --escrow-lock-amount, --escrow-lock-asset-id, --escrow-lock-expiry together.").option("--escrow-lock-id <hex32>", "INLINE lock_id (32-byte hex). Used with --escrow-lock-blob.").option("--escrow-lock-amount <int>", "INLINE lock amount in base units (e.g. lamports for native SOL). Used with --escrow-lock-blob.").option("--escrow-lock-asset-id <caip19>", "INLINE currency CAIP-19 asset_id (e.g. solana:<cluster_id>/slip44:501). Used with --escrow-lock-blob.").option("--escrow-lock-expiry <unix>", "INLINE expiry as unix seconds. Used with --escrow-lock-blob.").option(
+  ).option(
+    "--escrow-lock-blob <base64>",
+    "INLINE alternative: the signed Solana tx blob (base64). Requires --escrow-lock-id, --escrow-lock-amount, --escrow-lock-asset-id, --escrow-lock-expiry together."
+  ).option("--escrow-lock-id <hex32>", "INLINE lock_id (32-byte hex). Used with --escrow-lock-blob.").option("--escrow-lock-amount <int>", "INLINE lock amount in base units (e.g. lamports for native SOL). Used with --escrow-lock-blob.").option("--escrow-lock-asset-id <caip19>", "INLINE currency CAIP-19 asset_id (e.g. solana:<cluster_id>/slip44:501). Used with --escrow-lock-blob.").option("--escrow-lock-expiry <unix>", "INLINE expiry as unix seconds. Used with --escrow-lock-blob.").option(
     "--program-id <pubkey>",
     "Expected ARP escrow program id for pre-flight against the lock file's embedded `program_id`. Precedence: this flag > ARP_ESCROW_PROGRAM_ID env > server protocol-fee endpoint. Mismatch throws BEFORE the envelope ships, so a wrong-program lock never silently fails on chain after the offer was already delivered. Pre-flight is skipped only for old lock files lacking `program_id`, or when no expected value can be resolved."
-  ).option("--no-escrow", "Opt-out for test_mode servers. Default REQUIRES the escrow_lock attachment; without --no-escrow, missing flags throw BEFORE the envelope is sent (avoids ESC_LOCK_MISSING POST_COMMIT consuming sender_sequence).").action(async (recipientDid, contractId, opts) => {
+  ).option(
+    "--no-escrow",
+    "Opt-out for test_mode servers. Default REQUIRES the escrow_lock attachment; without --no-escrow, missing flags throw BEFORE the envelope is sent (avoids ESC_LOCK_MISSING POST_COMMIT consuming sender_sequence)."
+  ).option(
+    "--wait-until <phase>",
+    'Block after delivery until the named FSM phase is reached (e.g. delegation.accepted). One of the UNTIL_PHASES from `heyarp status --help`. Exit code 124 on --wait-timeout. Recovers the "sub-agent exits before counterparty accepts" antipattern.'
+  ).option("--wait-timeout <seconds>", "When --wait-until is set: max wall-clock wait (default 300). Exit code 124 on timeout.").option("--wait-interval <seconds>", "When --wait-until is set: poll cadence (default 3, bound [1, 60]).").option(
+    "--wait-verbose",
+    'When --wait-until is set: emit one dim line per poll tick showing the current FSM state. Useful for "is it alive or stuck?" diagnosis on long blocks.',
+    false
+  ).action(async (recipientDid, contractId, opts) => {
     await runOffer(recipientDid, contractId, opts);
   });
 }
@@ -2633,9 +2726,7 @@ function assembleEscrowLockAttachment(opts) {
   const someInlineSet = inlineFlags.some((f) => f !== void 0 && f !== "");
   const allInlineSet = inlineFlags.every((f) => f !== void 0 && f !== "");
   if (fromFile && someInlineSet) {
-    throw new Error(
-      "delegation offer: --escrow-lock-from-file and --escrow-lock-blob/--escrow-lock-* are mutually exclusive. Pick one path."
-    );
+    throw new Error("delegation offer: --escrow-lock-from-file and --escrow-lock-blob/--escrow-lock-* are mutually exclusive. Pick one path.");
   }
   if (!fromFile && !someInlineSet) {
     if (opts.escrow === false) return void 0;
@@ -2677,7 +2768,9 @@ function assembleEscrowLockAttachment(opts) {
     } else if (typeof expiryRaw === "string") {
       expiryNum2 = Number(expiryRaw);
       if (String(expiryNum2) !== expiryRaw.trim()) {
-        throw new Error(`delegation offer: --escrow-lock-from-file '${fromFile}' has invalid 'expiry' (must be positive integer unix seconds): ${JSON.stringify(expiryRaw)}.`);
+        throw new Error(
+          `delegation offer: --escrow-lock-from-file '${fromFile}' has invalid 'expiry' (must be positive integer unix seconds): ${JSON.stringify(expiryRaw)}.`
+        );
       }
     } else {
       throw new Error(`delegation offer: --escrow-lock-from-file '${fromFile}' has invalid 'expiry' (must be positive integer unix seconds): ${JSON.stringify(expiryRaw)}.`);
@@ -2688,9 +2781,7 @@ function assembleEscrowLockAttachment(opts) {
     let delegationIdFromLock;
     if (p.delegation_id !== void 0) {
       if (typeof p.delegation_id !== "string" || !UUID_RE.test(p.delegation_id)) {
-        throw new Error(
-          `delegation offer: --escrow-lock-from-file '${fromFile}' has invalid 'delegation_id' (must be a UUID): ${JSON.stringify(p.delegation_id)}.`
-        );
+        throw new Error(`delegation offer: --escrow-lock-from-file '${fromFile}' has invalid 'delegation_id' (must be a UUID): ${JSON.stringify(p.delegation_id)}.`);
       }
       delegationIdFromLock = p.delegation_id.toLowerCase();
     }
@@ -2800,9 +2891,34 @@ Reference this delegation on subsequent calls with:`));
   console.log(import_chalk6.default.dim(`  heyarp delegation accept ${result.relationshipId} ${delegationId}`));
   console.log(import_chalk6.default.dim(`  heyarp delegation decline ${result.relationshipId} ${delegationId}`));
   console.log(import_chalk6.default.dim(`  heyarp delegation cancel  ${result.relationshipId} ${delegationId}`));
+  if (opts.waitUntil) {
+    const untilPhase = parseUntilPhase(opts.waitUntil);
+    if (untilPhase === void 0) {
+      throw new Error(`delegation offer: --wait-until requires a phase value (got ${JSON.stringify(opts.waitUntil)})`);
+    }
+    await awaitFsmTransitionAfterAction({
+      api,
+      signerDid: sender.did,
+      signer: makeSigner(sender),
+      relationshipId: result.relationshipId,
+      untilPhase,
+      waitIntervalSec: parseWaitInterval(opts.waitInterval),
+      waitTimeoutSec: parseWaitTimeout(opts.waitTimeout),
+      waitVerbose: !!opts.waitVerbose,
+      json: false
+      // delegation offer is a human-text command (printIngestResult is human-text); JSON mode would be a follow-up.
+    });
+  }
 }
 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).action(async (relationshipId, delegationId, opts) => {
+  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) => {
     await runFollowupAction(relationshipId, delegationId, "accept", opts);
   });
 }
@@ -2812,20 +2928,33 @@ function registerDecline(parent) {
     // surface the closed enum at help time so operators
     // don't have to read source to find acceptable values.
     `Required: decline reason code (one of: ${import_sdk4.DECLINE_REASONS.join(", ")}). Carried in body.content.reason so the counterparty's reactor can branch on it.`
-  ).option("--reason-detail <s>", 'Optional free-text elaboration alongside --reason (e.g. "rate floor 0.20 USDC"). Max 512 chars.').option("--verbose", "Print the full envelope before sending and the full server response", false).action(async (relationshipId, delegationId, opts) => {
+  ).option("--reason-detail <s>", 'Optional free-text elaboration alongside --reason (e.g. "rate floor 0.20 USDC"). Max 512 chars.').option("--verbose", "Print the full envelope before sending and the full server response", 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) => {
     await runFollowupAction(relationshipId, delegationId, "decline", opts);
   });
 }
 function registerCancel(parent) {
-  parent.command("cancel").description("Cancel a PROPOSED delegation \u2014 moves to CANCELED. Offerer-only (the OTHER side uses decline).").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).action(async (relationshipId, delegationId, opts) => {
+  parent.command("cancel").description("Cancel a PROPOSED delegation \u2014 moves to CANCELED. Offerer-only (the OTHER side uses decline).").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(
+    "--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) => {
     await runFollowupAction(relationshipId, delegationId, "cancel", opts);
   });
 }
 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);
+  const lockWaitTimeoutSec = parseLockWaitTimeout(cmdName, opts.lockWaitTimeout);
+  const lockWaitIntervalSec = parseLockWaitInterval(cmdName, opts.lockWaitInterval);
   let declinePayload = null;
   if (action === "decline") {
     const reason = parseDeclineReason(cmdName, opts.reason);
@@ -2836,6 +2965,19 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
   const sender = resolveSenderAgent(cmdName, opts.server, opts.fromDid);
   const signer = makeSigner(sender);
   const resolved = await resolveDelegationRefs(cmdName, api, signer, { relationshipId, delegationId, action, selfDid: sender.did, contractIdOverride: opts.contractId });
+  if (resolved.state === "pending_lock_finalization" && opts.waitForLock !== false) {
+    await awaitDelegationLockFinalized(cmdName, api, signer, {
+      relationshipId,
+      delegationId,
+      action,
+      timeoutSec: lockWaitTimeoutSec,
+      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 = {
     action,
     delegation_id: delegationId,
@@ -2846,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,
@@ -2859,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) {
@@ -2939,7 +3096,96 @@ async function resolveDelegationRefs(cmdName, api, signer, args) {
   } else {
     recipientDid = row.offererDid;
   }
-  return { contractId, recipientDid };
+  return { contractId, recipientDid, state: row.state };
+}
+async function awaitDelegationLockFinalized(cmdName, api, signer, args) {
+  const log = args.log ?? ((line) => console.log(line));
+  log(
+    import_chalk6.default.dim(
+      `
+[--wait-for-lock] delegation ${args.delegationId} is awaiting on-chain lock confirmation; polling until ready (interval=${args.intervalSec}s timeout=${args.timeoutSec}s)`
+    )
+  );
+  const fetchRow = async () => {
+    let after;
+    for (; ; ) {
+      const page = await api.listDelegations(args.relationshipId, signer, { limit: 100, after });
+      const found = page.find((d) => d.delegationId === args.delegationId);
+      if (found) return found;
+      if (page.length < 100) return null;
+      after = page[page.length - 1].id;
+    }
+  };
+  const outcome = await (0, import_sdk4.pollUntil)({
+    fetch: fetchRow,
+    // Match on either "row not found at all" OR "state moved
+    // past pending_lock_finalization". The post-poll branch
+    // disambiguates which condition fired — missing rows error
+    // loud (operator typo or row pruned), present-but-terminal
+    // rows error with the new state, and present-and-actionable
+    // rows return cleanly. Polling on null would loop pointlessly
+    // until the deadline fires and surface a misleading "timed
+    // out" message for what's actually a wrong-id problem.
+    predicate: (row2) => row2 === null || row2.state !== "pending_lock_finalization",
+    intervalMs: args.intervalSec * 1e3,
+    timeoutMs: args.timeoutSec * 1e3,
+    // Swallow ONLY transient errors. A 4xx during the poll is a
+    // new race (auth lost, relationship deleted, shape bug) and
+    // should surface immediately — without this branch the loop
+    // would spin until timeout and report a misleading
+    // "still pending_lock_finalization" reason. 5xx + network
+    // errors are the actual transients we want to ride out.
+    swallowFetchErrors: true,
+    onFetchError: (err) => {
+      if (err instanceof ApiError && err.status >= 400 && err.status < 500) {
+        throw err;
+      }
+      log(import_chalk6.default.dim(`  poll: transient fetch error (${err instanceof Error ? err.message : String(err)})`));
+    }
+  });
+  if (outcome.kind === "timeout") {
+    throw new Error(
+      `${cmdName}: --wait-for-lock timed out after ${args.timeoutSec}s; delegation ${args.delegationId} still in pending_lock_finalization. Retry the command (the lock may have confirmed in the meantime), bump --lock-wait-timeout, or pass --no-wait-for-lock to skip the pre-flight and surface the 409 directly.`
+    );
+  }
+  if (outcome.kind === "aborted") {
+    throw new Error(`${cmdName}: --wait-for-lock aborted before delegation ${args.delegationId} exited pending_lock_finalization`);
+  }
+  const row = outcome.value;
+  if (row === null) {
+    throw new Error(
+      `${cmdName}: delegation ${args.delegationId} disappeared from relationship ${args.relationshipId} during --wait-for-lock pre-flight. Re-check the delegation id with \`heyarp delegations ${args.relationshipId}\`.`
+    );
+  }
+  if (row.state !== "offered" && row.state !== "proposed") {
+    throw new Error(
+      `${cmdName}: delegation ${args.delegationId} transitioned to '${row.state}' while waiting for on-chain lock confirmation; cannot ${args.action}. Re-read the delegation timeline with \`heyarp delegations ${args.relationshipId}\` to see the latest state.`
+    );
+  }
+  log(import_chalk6.default.dim(`[--wait-for-lock] delegation ${args.delegationId} ready (state=${row.state}); proceeding with ${args.action}.`));
+  return row;
+}
+function parseLockWaitTimeout(cmdName, raw) {
+  if (raw === void 0) return 300;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+    throw new Error(`${cmdName}: --lock-wait-timeout must be a positive integer number of seconds (got '${raw}')`);
+  }
+  if (n > 3600) {
+    throw new Error(`${cmdName}: --lock-wait-timeout must be <= 3600 seconds (1h). Got ${n}; if the on-chain lock is taking that long something else is broken.`);
+  }
+  return n;
+}
+function parseLockWaitInterval(cmdName, raw) {
+  if (raw === void 0) return 3;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+    throw new Error(`${cmdName}: --lock-wait-interval must be a positive integer number of seconds (got '${raw}')`);
+  }
+  if (n < 1 || n > 60) {
+    throw new Error(`${cmdName}: --lock-wait-interval must be in [1, 60] seconds (got ${n}). Sub-second polling spams the server; > 60s defeats the point of the pre-flight.`);
+  }
+  return n;
 }
 function printIngestResult(result) {
   console.log(import_chalk6.default.green("\nDelivered."));
@@ -3071,7 +3317,13 @@ function registerPropose(parent) {
   ).option(
     "--rate-decimals <n>",
     "Decimal places for base-unit conversion (0-18). Required only when --rate-currency is raw CAIP-19; shorthand presets bring their own (USDC=6, SOL=9)."
-  ).option("--rate-symbol <s>", 'Optional UI hint ("USDC", "SOL"). Free text, max 16 chars. Shorthand presets set this automatically.').option("--rate-unit <s>", "rate_unit (task|thread|handoff)").option("--pricing <s>", "pricing_model (flat|usage_based). `quote` + `subscription` were dropped from the enum because they had no settlement-layer behaviour; add them back when real semantics ship.").option("--settlement <s>", "settlement_model (prepaid|escrow)").option("--delegation-tag <s>", "allowed_delegation_tags \u2014 repeatable; pass --delegation-tag once per tag", collectRepeated2, []).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) => {
+  ).option("--rate-symbol <s>", 'Optional UI hint ("USDC", "SOL"). Free text, max 16 chars. Shorthand presets set this automatically.').option("--rate-unit <s>", "rate_unit (task|thread|handoff)").option(
+    "--pricing <s>",
+    "pricing_model (flat|usage_based). `quote` + `subscription` were dropped from the enum because they had no settlement-layer behaviour; add them back when real semantics ship."
+  ).option("--settlement <s>", "settlement_model (prepaid|escrow)").option("--delegation-tag <s>", "allowed_delegation_tags \u2014 repeatable; pass --delegation-tag once per tag", collectRepeated2, []).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(
+    "--wait-until <phase>",
+    'Block after delivery until the named FSM phase is reached (e.g. contract.active). One of the UNTIL_PHASES from `heyarp status --help`. Exit code 124 on --wait-timeout. Makes "wait for counterparty to sign" a one-liner instead of a separate `heyarp status --wait --until contract.active` invocation.'
+  ).option("--wait-timeout <seconds>", "When --wait-until is set: max wall-clock wait (default 300). Exit code 124 on timeout.").option("--wait-interval <seconds>", "When --wait-until is set: poll cadence (default 3, bound [1, 60]).").option("--wait-verbose", "When --wait-until is set: emit one dim line per poll tick.", false).action(async (recipientDid, opts) => {
     await runPropose(recipientDid, opts);
   });
 }
@@ -3102,9 +3354,29 @@ async function runPropose(recipientDid, opts) {
 Reference this contract on subsequent calls with: heyarp contract <action> ${result.relationshipId} ${contractId}`));
   console.log(import_chalk7.default.dim(`  e.g. (counterparty signs)   : heyarp contract sign ${result.relationshipId} ${contractId}`));
   console.log(import_chalk7.default.dim(`  e.g. (counterparty counters): heyarp contract counter ${result.relationshipId} ${contractId} --rate-amount <new>`));
+  if (opts.waitUntil) {
+    const untilPhase = parseUntilPhase(opts.waitUntil);
+    if (untilPhase === void 0) {
+      throw new Error(`contract propose: --wait-until requires a phase value (got ${JSON.stringify(opts.waitUntil)})`);
+    }
+    await awaitFsmTransitionAfterAction({
+      api,
+      signerDid: sender.did,
+      signer: makeSigner(sender),
+      relationshipId: result.relationshipId,
+      untilPhase,
+      waitIntervalSec: parseWaitInterval(opts.waitInterval),
+      waitTimeoutSec: parseWaitTimeout(opts.waitTimeout),
+      waitVerbose: !!opts.waitVerbose,
+      json: false
+    });
+  }
 }
 function registerCounter(parent) {
-  parent.command("counter").description("Reply with revised terms to the latest PROPOSED version of <contract-id> in <relationship-id>.").argument("<relationship-id>", "Relationship UUID").argument("<contract-id>", "Contract UUID (proposed earlier in this relationship)").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 previous version explicitly (default: auto-resolve to the latest PROPOSED)").option("--scope <s>", "scope_summary \u2014 short prose describing the revised terms").option("--rate-amount <s>", "rate_amount \u2014 decimal as string. REQUIRES --rate-currency if set.").option("--rate-currency <s>", `Asset identifier: shorthand (${import_sdk5.WELL_KNOWN_ASSET_KEYS.join("|")}) OR raw CAIP-19 string.`).option("--rate-decimals <n>", "Decimal places for base-unit conversion (0-18). Required only when --rate-currency is raw CAIP-19.").option("--rate-symbol <s>", 'Optional UI hint ("USDC", "SOL"). Max 16 chars.').option("--rate-unit <s>", "rate_unit (task|thread|handoff)").option("--pricing <s>", "pricing_model (flat|usage_based). `quote` + `subscription` were dropped from the enum because they had no settlement-layer behaviour; add them back when real semantics ship.").option("--settlement <s>", "settlement_model (prepaid|escrow)").option("--delegation-tag <s>", "allowed_delegation_tags \u2014 repeatable", collectRepeated2, []).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("counter").description("Reply with revised terms to the latest PROPOSED version of <contract-id> in <relationship-id>.").argument("<relationship-id>", "Relationship UUID").argument("<contract-id>", "Contract UUID (proposed earlier in this relationship)").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 previous version explicitly (default: auto-resolve to the latest PROPOSED)").option("--scope <s>", "scope_summary \u2014 short prose describing the revised terms").option("--rate-amount <s>", "rate_amount \u2014 decimal as string. REQUIRES --rate-currency if set.").option("--rate-currency <s>", `Asset identifier: shorthand (${import_sdk5.WELL_KNOWN_ASSET_KEYS.join("|")}) OR raw CAIP-19 string.`).option("--rate-decimals <n>", "Decimal places for base-unit conversion (0-18). Required only when --rate-currency is raw CAIP-19.").option("--rate-symbol <s>", 'Optional UI hint ("USDC", "SOL"). Max 16 chars.').option("--rate-unit <s>", "rate_unit (task|thread|handoff)").option(
+    "--pricing <s>",
+    "pricing_model (flat|usage_based). `quote` + `subscription` were dropped from the enum because they had no settlement-layer behaviour; add them back when real semantics ship."
+  ).option("--settlement <s>", "settlement_model (prepaid|escrow)").option("--delegation-tag <s>", "allowed_delegation_tags \u2014 repeatable", collectRepeated2, []).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) => {
     await runCounter(relationshipId, contractId, opts);
   });
 }
@@ -3144,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);
   });
 }
@@ -3162,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);
@@ -3186,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,
@@ -3199,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) {
@@ -3549,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;
@@ -3561,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) {
@@ -3667,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");
@@ -3901,7 +4284,9 @@ function registerEscrowCommands(root) {
   cmd.command("info").description("Show the on-chain protocol fee config + cluster + pause state. Public read; no auth.").option("--server <url>", "Override ARP server base URL").option("--json", "Machine-readable JSON output", false).action(async (opts) => {
     await runEscrowInfo(opts);
   });
-  cmd.command("derive-condition-hash").description("Compute canonical condition_hash (32-byte hex) for `heyarp wallet create-lock --condition-hash <hex>`. Fetches the contract row, projects to the canonical subset, and hashes via SDK deriveConditionHash. Mirrors what the on-chain create_lock instruction binds.").argument("<relationship-id>", "Relationship UUID hosting the contract").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>", "Pin a specific contract version (default: latest non-replaced row)").option("--json", "Machine-readable JSON: {contract_id, version, condition_hash_hex, projected_subset}", false).action(async (relationshipId, contractId, opts) => {
+  cmd.command("derive-condition-hash").description(
+    "Compute canonical condition_hash (32-byte hex) for `heyarp wallet create-lock --condition-hash <hex>`. Fetches the contract row, projects to the canonical subset, and hashes via SDK deriveConditionHash. Mirrors what the on-chain create_lock instruction binds."
+  ).argument("<relationship-id>", "Relationship UUID hosting the contract").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>", "Pin a specific contract version (default: latest non-replaced row)").option("--json", "Machine-readable JSON: {contract_id, version, condition_hash_hex, projected_subset}", false).action(async (relationshipId, contractId, opts) => {
     await runDeriveConditionHash(relationshipId, contractId, opts);
   });
   cmd.command("recover-sequence").description(
@@ -3914,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));
   }
@@ -4005,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);
@@ -4018,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}`));
@@ -4065,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}`));
@@ -4244,191 +4628,539 @@ 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"));
-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);
+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;
+    }
   });
 }
-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"),
-  "   `heyarp inbox --tail` opens an SSE stream and prints each new envelope",
-  "   as it arrives. Use this for long-running worker processes \u2014 DO NOT",
-  "   bash-loop `heyarp inbox` every 5s, that's self-DDoS at scale.",
-  "   `stream ended unexpectedly` (exit \u2260 0) = server EOF; re-run to reconnect.",
-  "   `stream closed.` (exit 0) = your Ctrl-C / SIGTERM; nothing to fix.",
-  "   For scripted phase-anchored waits, prefer `status --wait --until`:",
-  "     heyarp status <rel-id> --wait --until contract.active --wait-timeout 600",
-  "     heyarp status <rel-id> --wait --until delegation.accepted",
-  "     heyarp status <rel-id> --wait --until receipt.cosigned",
-  "   Exits 0 on transition, 124 on timeout or terminal-without-match.",
-  "   If you must poll (no SSE, no --wait), persist a cursor:",
-  "     heyarp inbox --since <last-ts> --since-event-id <last-evt> --json",
-  "   Without it, restarted pollers re-fire on already-handled events.",
-  "",
-  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 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/homes.ts
-var import_node_fs6 = require("fs");
-var import_node_path5 = require("path");
+// src/commands/guide.ts
 var import_chalk15 = __toESM(require("chalk"));
-var import_prompts = __toESM(require("prompts"));
 
-// src/homes.ts
-var import_node_fs5 = require("fs");
-var import_node_path4 = 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: [] };
-  let raw;
-  try {
-    raw = (0, import_node_fs5.readFileSync)(path, "utf8");
-  } catch (err) {
-    throw new Error(`Failed to read homes registry at ${path}: ${err.message}`);
-  }
-  if (raw.trim().length === 0) return { homes: [] };
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new Error(`homes registry at ${path} is not valid JSON. Move or delete it before running again.`);
-  }
-  if (parsed === null || typeof parsed !== "object") return { homes: [] };
-  const obj = parsed;
+// 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(
+    "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));
+  });
+}
+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_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_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_fs6.existsSync)(path)) return { homes: [] };
+  let raw;
+  try {
+    raw = (0, import_node_fs6.readFileSync)(path, "utf8");
+  } catch (err) {
+    throw new Error(`Failed to read homes registry at ${path}: ${err.message}`);
+  }
+  if (raw.trim().length === 0) return { homes: [] };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`homes registry at ${path} is not valid JSON. Move or delete it before running again.`);
+  }
+  if (parsed === null || typeof parsed !== "object") return { homes: [] };
+  const obj = parsed;
   const homes = Array.isArray(obj.homes) ? obj.homes : [];
   const clean = homes.filter((h) => {
     return h !== null && typeof h === "object" && typeof h.path === "string" && typeof h.lastSeenAt === "string";
@@ -4437,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 {
   }
 }
@@ -4470,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
@@ -4497,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",
@@ -4527,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)) {
@@ -4566,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
@@ -4599,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 = {
@@ -4646,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;
@@ -4661,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("");
@@ -4676,21 +5408,17 @@ 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(
-        `
-${events.length} event(s).${addressedToMeHint} Paginate with --before <serverTimestamp> --before-event-id <eventId> using the LAST row above.`
-      )
-    );
+    console.log(import_chalk17.default.dim(`
+${events.length} event(s).${addressedToMeHint} Paginate with --before <serverTimestamp> --before-event-id <eventId> using the LAST row above.`));
   }
 }
 async function runInboxTail(did, local, opts) {
@@ -4702,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."
         )
       );
@@ -4713,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;
@@ -4734,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") {
@@ -4748,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.");
@@ -4756,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;
@@ -4776,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)}...`;
 }
@@ -4799,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) {
@@ -4844,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();
@@ -4861,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 }))));
     }
   });
@@ -4869,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.");
@@ -4922,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,
@@ -4957,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;
@@ -4987,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 {
@@ -5023,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) {
@@ -5031,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}`));
   }
 }
@@ -5039,12 +5768,15 @@ 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("<entry-id>", 'Memory entry `id` (24-hex string). Get this from `heyarp memory list <rel-id> --json | jq ".[].id"`. The public DTO surfaces Mongo `_id` as the `id` field.').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("--json", "Machine-readable: emit only the JSON object on stdout (no chalk).", false).action(async (entryId, opts) => {
+  parent.command("show").description("Fetch one memory entry by its server `_id`.").argument(
+    "<entry-id>",
+    'Memory entry `id` (24-hex string). Get this from `heyarp memory list <rel-id> --json | jq ".[].id"`. The public DTO surfaces Mongo `_id` as the `id` field.'
+  ).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("--json", "Machine-readable: emit only the JSON object on stdout (no chalk).", false).action(async (entryId, opts) => {
     await runShow(entryId, opts);
   });
 }
@@ -5057,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) {
@@ -5095,14 +5827,15 @@ function parseLimit6(cmdName, raw) {
 }
 
 // src/commands/receipt.ts
+var import_node_fs8 = require("fs");
 var import_sdk11 = require("@heyanon-arp/sdk");
-var import_chalk20 = __toESM(require("chalk"));
-var import_node_fs7 = require("fs");
+var import_chalk21 = __toESM(require("chalk"));
 init_api();
 function registerReceiptCommands(root) {
   const cmd = root.command("receipt").description("Receipt envelopes \u2014 payee proposes, caller cosigns");
   registerPropose2(cmd);
   registerCosign(cmd);
+  registerSendPayeeSig(cmd);
 }
 var POST_COMMIT_ERROR_CODES4 = /* @__PURE__ */ new Set([
   "RECEIPT_ALREADY_EXISTS",
@@ -5116,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
@@ -5156,7 +5898,32 @@ var POST_COMMIT_ERROR_CODES4 = /* @__PURE__ */ new Set([
   // lock.amount. Same lifecycle classification as MISMATCH — event
   // committed, body action rejected, CLI advances
   // lastSenderSequence.
-  "ESC_USAGE_COMPUTED_AMOUNT_EXCEEDS_LOCK"
+  "ESC_USAGE_COMPUTED_AMOUNT_EXCEEDS_LOCK",
+  // `settlement_signature` envelope handler rejection codes. ALL
+  // fire AFTER the event row is committed but BEFORE the
+  // receipt.payeeSettlement is set (server-side
+  // PRE_MATERIALIZATION_REJECTION_CODES classification). Sender
+  // sequence is consumed regardless — the envelope row sits in the
+  // chain with readModelStatus='rejected'. Without these on the
+  // allowlist, a CLI retry after fixing the sig would reuse the
+  // old sequence and trip ENV_SEQUENCE_BACKWARDS.
+  //
+  // Sourced via:
+  // grep "'SETTLEMENT_SIG_" apps/arp-server/src/message/services/settlement-signature-handler.service.ts \
+  //   | sed -E "s/.*'(SETTLEMENT_SIG_[A-Z_]+)'.*/\1/" | sort -u
+  "SETTLEMENT_SIG_RECEIPT_NOT_FOUND",
+  "SETTLEMENT_SIG_RECEIPT_INVALID_STATE",
+  "SETTLEMENT_SIG_SENDER_NOT_PAYEE",
+  "SETTLEMENT_SIG_VERDICT_NOT_PAYABLE",
+  "SETTLEMENT_SIG_PURPOSE_INVALID",
+  "SETTLEMENT_SIG_PAYEE_AMOUNT_MISMATCH_USAGE",
+  "SETTLEMENT_SIG_LOCK_NOT_FOUND",
+  "SETTLEMENT_SIG_LOCK_INVALID_STATE",
+  "SETTLEMENT_SIG_PUBKEY_MISMATCH",
+  "SETTLEMENT_SIG_PAYEE_AMOUNT_EXCEEDS_LOCK",
+  "SETTLEMENT_SIG_EXPIRES_AT_PAST",
+  "SETTLEMENT_SIG_EXPIRES_AT_TOO_SOON",
+  "SETTLEMENT_SIG_EXPIRES_AT_EXCEEDS_LOCK"
 ]);
 var VERDICT_VALUES = ["accepted", "accepted_with_notes", "rejected"];
 var SHA256_RE = /^sha256:[0-9a-f]{64}$/;
@@ -5171,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");
@@ -5193,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);
@@ -5206,7 +5985,12 @@ 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(`[auto-request-id] resolved --request-id=${opts.requestId} (unique 'responded' work_log under this delegation; pass --request-id explicitly to override)`));
+      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)`
+        )
+      );
     }
     requireUuid3("receipt propose", opts.relId, "--rel-id");
     const computed = await computeWorkLogHashes(api, sender, opts.relId, delegationId, opts.requestId);
@@ -5222,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)");
@@ -5243,23 +6027,39 @@ 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);
-  const rows = await fetchAllPages(
-    (after) => api.listDelegations(relationshipId, signer, { limit: 100, ...after ? { after } : {} })
-  );
+  const rows = await fetchAllPages((after) => api.listDelegations(relationshipId, signer, { limit: 100, ...after ? { after } : {} }));
   const delegation = rows.find((d) => d.delegationId === delegationId);
   if (!delegation) {
     return;
@@ -5272,9 +6072,7 @@ async function assertSenderIsReceiptPayee(api, sender, relationshipId, delegatio
 }
 async function assertSenderIsReceiptCaller(api, sender, relationshipId, delegationId) {
   const signer = makeSigner(sender);
-  const rows = await fetchAllPages(
-    (after) => api.listDelegations(relationshipId, signer, { limit: 100, ...after ? { after } : {} })
-  );
+  const rows = await fetchAllPages((after) => api.listDelegations(relationshipId, signer, { limit: 100, ...after ? { after } : {} }));
   const delegation = rows.find((d) => d.delegationId === delegationId);
   if (!delegation) {
     return;
@@ -5311,7 +6109,9 @@ async function resolveAutoRelId(api, sender, delegationId) {
 }
 async function resolveAutoRequestId(api, sender, relationshipId, delegationId) {
   const signer = makeSigner(sender);
-  const logs = await fetchAllPages((after) => api.listWorkLogs(relationshipId, signer, { delegationId, state: "responded", limit: 100, ...after ? { after } : {} }));
+  const logs = await fetchAllPages(
+    (after) => api.listWorkLogs(relationshipId, signer, { delegationId, state: "responded", limit: 100, ...after ? { after } : {} })
+  );
   if (logs.length === 0) {
     throw new Error(
       `receipt propose --auto-hashes: no 'responded' work_log under delegation ${delegationId} in relationship ${relationshipId} \u2014 the payee must send \`work respond\` before a receipt can be proposed. Pass --request-id explicitly if you have a known one.`
@@ -5366,25 +6166,43 @@ function registerCosign(parent) {
   ).option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).option(
     "--settlement-purpose <s>",
     "Settlement digest purpose: `ARP-SOLANA-RELEASE-v1.5` (full) or `ARP-SOLANA-PARTIAL-RELEASE-v1.5` (partial; requires --settlement-payee-amount)."
-  ).option("--settlement-expires-at <unix>", "Settlement expires_at (unix seconds) \u2014 must match the value signed by BOTH parties when they ran `heyarp wallet sign-settlement-release`.").option("--payer-settlement-pubkey <b58>", "Payer settlement pubkey (base58) \u2014 must equal `lock.payer`. Mutually exclusive with --payer-sig-from-file.").option("--payer-settlement-sig <base64>", "Payer Ed25519 settlement signature (raw base64, NO `ed25519:` prefix). Mutually exclusive with --payer-sig-from-file.").option("--payee-settlement-pubkey <b58>", "Payee settlement pubkey (base58) \u2014 must equal `lock.payee`. Mutually exclusive with --payee-sig-from-file.").option("--payee-settlement-sig <base64>", "Payee Ed25519 settlement signature (raw base64, NO `ed25519:` prefix). Mutually exclusive with --payee-sig-from-file.").option(
+  ).option(
+    "--settlement-expires-at <unix>",
+    "Settlement expires_at (unix seconds) \u2014 must match the value signed by BOTH parties when they ran `heyarp wallet sign-settlement-release`."
+  ).option("--payer-settlement-pubkey <b58>", "Payer settlement pubkey (base58) \u2014 must equal `lock.payer`. Mutually exclusive with --payer-sig-from-file.").option("--payer-settlement-sig <base64>", "Payer Ed25519 settlement signature (raw base64, NO `ed25519:` prefix). Mutually exclusive with --payer-sig-from-file.").option("--payee-settlement-pubkey <b58>", "Payee settlement pubkey (base58) \u2014 must equal `lock.payee`. Mutually exclusive with --payee-sig-from-file.").option("--payee-settlement-sig <base64>", "Payee Ed25519 settlement signature (raw base64, NO `ed25519:` prefix). Mutually exclusive with --payee-sig-from-file.").option(
+    "--auto-resolve-payee-sig",
+    "Read the payee's settlement signature from `receipt.payeeSettlement` (populated by the worker's `heyarp receipt send-payee-sig` envelope) instead of requiring --payee-settlement-pubkey + --payee-settlement-sig + --settlement-purpose + --settlement-expires-at + --settlement-payee-amount flags. Closes the cross-host-coordination gap that earlier flows worked around via shared /tmp/*.json files. Mutually exclusive with --payee-sig-from-file and the explicit --payee-settlement-* flags. Buyer still supplies the PAYER side themselves (--payer-sig-from-file or --payer-settlement-* flags).",
+    false
+  ).option(
     "--payer-sig-from-file <path>",
     "Read `{settlement_pubkey, sig}` for the PAYER side from the JSON file produced by `heyarp wallet sign-settlement-release --write-to <path>`. Populates --payer-settlement-pubkey + --payer-settlement-sig."
   ).option(
     "--payee-sig-from-file <path>",
     "Read `{settlement_pubkey, sig}` for the PAYEE side from the JSON file produced by `heyarp wallet sign-settlement-release --write-to <path>`. Populates --payee-settlement-pubkey + --payee-settlement-sig."
-  ).option("--settlement-payee-amount <int>", "Required ONLY when --settlement-purpose=ARP-SOLANA-PARTIAL-RELEASE-v1.5. Payee receives this many base units; payer is refunded `lock.amount - payee_amount`.").option("--no-settlement", "Opt out of settlement_signatures attachment. Default behavior REQUIRES the full settlement flag set; without --no-settlement, omitting flags errors loud BEFORE the envelope is sent. Use --no-settlement only against a server running in test_mode.").action(async (relationshipId, delegationId, requestHashArg, responseHashArg, opts, cmd) => {
-    try {
-      await runCosign(relationshipId, delegationId, requestHashArg, responseHashArg, opts);
-    } catch (err) {
-      console.error(formatActionError(err, cmd));
-      process.exitCode = 1;
+  ).option(
+    "--settlement-payee-amount <int>",
+    "Required ONLY when --settlement-purpose=ARP-SOLANA-PARTIAL-RELEASE-v1.5. Payee receives this many base units; payer is refunded `lock.amount - payee_amount`."
+  ).option(
+    "--no-settlement",
+    "Opt out of settlement_signatures attachment. Default behavior REQUIRES the full settlement flag set; without --no-settlement, omitting flags errors loud BEFORE the envelope is sent. Use --no-settlement only against a server running in test_mode."
+  ).option(
+    "--wait-until <phase>",
+    "Block after cosign-delivery until the named FSM phase is reached (e.g. cycle.released \u2014 strongest, waits for on-chain settlement; cycle.complete \u2014 weaker, waits only for the cosigned-receipt row). One of UNTIL_PHASES from `heyarp status --help`. Exit 124 on --wait-timeout."
+  ).option("--wait-timeout <seconds>", "When --wait-until is set: max wall-clock wait (default 300). Exit code 124 on timeout.").option("--wait-interval <seconds>", "When --wait-until is set: poll cadence (default 3, bound [1, 60]).").option("--wait-verbose", "When --wait-until is set: emit one dim line per poll tick.", false).action(
+    async (relationshipId, delegationId, requestHashArg, responseHashArg, opts, cmd) => {
+      try {
+        await runCosign(relationshipId, delegationId, requestHashArg, responseHashArg, opts);
+      } catch (err) {
+        emitActionError(err, cmd);
+        process.exitCode = 1;
+      }
     }
-  });
+  );
 }
 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}`);
   }
@@ -5403,7 +6221,9 @@ function loadSettlementSigFromFile(path, flagPrefix) {
   const digestHex = p.digest_hex;
   const purpose = p.purpose;
   if (typeof pubkey !== "string" || pubkey.length === 0) {
-    throw new Error(`receipt cosign: ${flagPrefix} '${path}' missing required field 'settlement_pubkey' (string). Expected JSON output of \`heyarp wallet sign-settlement-release\`.`);
+    throw new Error(
+      `receipt cosign: ${flagPrefix} '${path}' missing required field 'settlement_pubkey' (string). Expected JSON output of \`heyarp wallet sign-settlement-release\`.`
+    );
   }
   if (typeof sig !== "string" || sig.length === 0) {
     throw new Error(`receipt cosign: ${flagPrefix} '${path}' missing required field 'sig' (string). Expected JSON output of \`heyarp wallet sign-settlement-release\`.`);
@@ -5416,6 +6236,43 @@ function loadSettlementSigFromFile(path, flagPrefix) {
   }
   return { settlement_pubkey: pubkey, sig, digest_hex: digestHex, purpose };
 }
+function applyAutoResolvePayeeSig(cmdName, opts, payeeSettlement) {
+  if (opts.payeeSigFromFile !== void 0 && opts.payeeSigFromFile !== "") {
+    throw new Error(`${cmdName}: --auto-resolve-payee-sig is mutually exclusive with --payee-sig-from-file. Pass either the auto-resolve flag OR the file path, not both.`);
+  }
+  if (opts.payeeSettlementPubkey !== void 0 && opts.payeeSettlementPubkey !== "" || opts.payeeSettlementSig !== void 0 && opts.payeeSettlementSig !== "") {
+    throw new Error(
+      `${cmdName}: --auto-resolve-payee-sig is mutually exclusive with --payee-settlement-pubkey / --payee-settlement-sig. Pass either the auto-resolve flag OR the explicit values, not both.`
+    );
+  }
+  if (!payeeSettlement) {
+    throw new Error(
+      `${cmdName}: --auto-resolve-payee-sig requires receipt.payeeSettlement to be populated, but the field is unset. The worker hasn't sent its 'heyarp receipt send-payee-sig' envelope yet \u2014 wait for it OR fall back to --payee-sig-from-file / --payee-settlement-* flags for out-of-band coordination.`
+    );
+  }
+  opts.payeeSettlementPubkey = payeeSettlement.settlement_pubkey;
+  opts.payeeSettlementSig = payeeSettlement.sig;
+  if (opts.settlementPurpose !== void 0 && opts.settlementPurpose !== "" && opts.settlementPurpose !== payeeSettlement.purpose) {
+    throw new Error(
+      `${cmdName}: --settlement-purpose='${opts.settlementPurpose}' disagrees with the auto-resolved purpose from receipt.payeeSettlement ('${payeeSettlement.purpose}'). Drop --settlement-purpose to use the auto-resolved value, or drop --auto-resolve-payee-sig to use the manual flag.`
+    );
+  }
+  opts.settlementPurpose = payeeSettlement.purpose;
+  if (opts.settlementExpiresAt !== void 0 && opts.settlementExpiresAt !== "" && opts.settlementExpiresAt !== String(payeeSettlement.expires_at)) {
+    throw new Error(
+      `${cmdName}: --settlement-expires-at='${opts.settlementExpiresAt}' disagrees with the auto-resolved expires_at from receipt.payeeSettlement (${payeeSettlement.expires_at}). Drop --settlement-expires-at to use the auto-resolved value, or drop --auto-resolve-payee-sig.`
+    );
+  }
+  opts.settlementExpiresAt = String(payeeSettlement.expires_at);
+  if (payeeSettlement.payee_amount !== void 0) {
+    if (opts.settlementPayeeAmount !== void 0 && opts.settlementPayeeAmount !== "" && opts.settlementPayeeAmount !== payeeSettlement.payee_amount) {
+      throw new Error(
+        `${cmdName}: --settlement-payee-amount='${opts.settlementPayeeAmount}' disagrees with the auto-resolved payee_amount from receipt.payeeSettlement ('${payeeSettlement.payee_amount}'). Drop --settlement-payee-amount to use the auto-resolved value, or drop --auto-resolve-payee-sig.`
+      );
+    }
+    opts.settlementPayeeAmount = payeeSettlement.payee_amount;
+  }
+}
 function assembleSettlementSignaturesAttachment(opts) {
   let payerPubkey = opts.payerSettlementPubkey;
   let payerSig = opts.payerSettlementSig;
@@ -5463,14 +6320,7 @@ function assembleSettlementSignaturesAttachment(opts) {
       `receipt cosign: --settlement-purpose='${opts.settlementPurpose}' disagrees with the purpose signed in the sig file ('${filePurpose}'). Either drop --settlement-purpose (the file's value will be used) or re-sign with the desired purpose.`
     );
   }
-  const settlementFlags = [
-    opts.settlementPurpose,
-    opts.settlementExpiresAt,
-    payerPubkey,
-    payerSig,
-    payeePubkey,
-    payeeSig
-  ];
+  const settlementFlags = [opts.settlementPurpose, opts.settlementExpiresAt, payerPubkey, payerSig, payeePubkey, payeeSig];
   const someSet = settlementFlags.some((f) => f !== void 0 && f !== "");
   const allSet = settlementFlags.every((f) => f !== void 0 && f !== "");
   if (!someSet) {
@@ -5489,9 +6339,7 @@ function assembleSettlementSignaturesAttachment(opts) {
   }
   const purpose = opts.settlementPurpose;
   if (purpose !== "ARP-SOLANA-RELEASE-v1.5" && purpose !== "ARP-SOLANA-PARTIAL-RELEASE-v1.5") {
-    throw new Error(
-      `receipt cosign: --settlement-purpose must be 'ARP-SOLANA-RELEASE-v1.5' or 'ARP-SOLANA-PARTIAL-RELEASE-v1.5', got '${purpose}'.`
-    );
+    throw new Error(`receipt cosign: --settlement-purpose must be 'ARP-SOLANA-RELEASE-v1.5' or 'ARP-SOLANA-PARTIAL-RELEASE-v1.5', got '${purpose}'.`);
   }
   const isPartial = purpose === "ARP-SOLANA-PARTIAL-RELEASE-v1.5";
   if (isPartial && (opts.settlementPayeeAmount === void 0 || opts.settlementPayeeAmount === "")) {
@@ -5601,22 +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_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,
@@ -5629,6 +6483,147 @@ async function runCosign(relationshipId, delegationId, requestHashArg, responseH
     server: opts.server
   });
   printIngestResult3(result);
+  if (opts.waitUntil) {
+    const untilPhase = parseUntilPhase(opts.waitUntil);
+    if (untilPhase === void 0) {
+      throw new Error(`receipt cosign: --wait-until requires a phase value (got ${JSON.stringify(opts.waitUntil)})`);
+    }
+    await awaitFsmTransitionAfterAction({
+      api,
+      signerDid: sender.did,
+      signer: makeSigner(sender),
+      relationshipId: result.relationshipId,
+      untilPhase,
+      waitIntervalSec: parseWaitInterval(opts.waitInterval),
+      waitTimeoutSec: parseWaitTimeout(opts.waitTimeout),
+      waitVerbose: !!opts.waitVerbose,
+      json: false
+    });
+  }
+}
+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(
+    "--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(
+    "--sig-from-file <path>",
+    "JSON file produced by `heyarp wallet sign-settlement-release --write-to <path>`. Reads `{settlement_pubkey, sig, purpose, digest_hex}` \u2014 the digest_hex is bound through for cross-file consistency (catches truncated or hand-edited files)."
+  ).requiredOption(
+    "--expires-at <unix>",
+    "Unix-seconds expires_at value baked into the signed digest \u2014 MUST match the value passed to `--expires-at` on `heyarp wallet sign-settlement-release`. Server cross-checks against the buyer-side value at cosign time; wrong value \u2192 ESC_SETTLEMENT_EXPIRES_AT_PAST/_TOO_SOON."
+  ).option(
+    "--payee-amount <int>",
+    "Base-unit decimal-integer payee_amount \u2014 REQUIRED when the sig file's purpose is `ARP-SOLANA-PARTIAL-RELEASE-v1.5` (usage_based contracts). Same value passed to `--partial-payee-amount` on sign-settlement-release. FORBIDDEN for `ARP-SOLANA-RELEASE-v1.5` (full release settles the whole lock)."
+  ).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 (= payee)").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).action(async (recipientDid, opts, cmd) => {
+    try {
+      await runSendPayeeSig(recipientDid, opts);
+    } catch (err) {
+      emitActionError(err, cmd);
+      process.exitCode = 1;
+    }
+  });
+}
+async function runSendPayeeSig(recipientDid, opts) {
+  const cmdName = "receipt send-payee-sig";
+  requireDid3(cmdName, recipientDid, "<recipient-did>");
+  const delegationId = requireUuidNormalised2(cmdName, opts.delegationId, "--delegation-id");
+  requireSha256(cmdName, opts.receiptEventHash, "--receipt-event-hash");
+  const expiresAtSeconds = parseInteger(cmdName, "--expires-at", opts.expiresAt);
+  if (expiresAtSeconds <= 0) {
+    throw new Error(`${cmdName}: --expires-at must be a positive unix-seconds integer (got ${opts.expiresAt})`);
+  }
+  const ttlSeconds = parseTtl4(cmdName, opts.ttl);
+  const sigFile = loadSettlementSigFromFile(opts.sigFromFile, "--sig-from-file");
+  const isPartial = sigFile.purpose === "ARP-SOLANA-PARTIAL-RELEASE-v1.5";
+  const isFull = sigFile.purpose === "ARP-SOLANA-RELEASE-v1.5";
+  if (!isPartial && !isFull) {
+    throw new Error(
+      `${cmdName}: sig file at '${opts.sigFromFile}' has purpose='${sigFile.purpose}' but only ARP-SOLANA-RELEASE-v1.5 and ARP-SOLANA-PARTIAL-RELEASE-v1.5 are valid on a settlement_signature envelope. (REFUND-v1 sigs ride other paths \u2014 they don't bind to receipt_event_hash, so this envelope isn't the right channel for them.)`
+    );
+  }
+  if (isPartial && (opts.payeeAmount === void 0 || opts.payeeAmount === "")) {
+    throw new Error(
+      `${cmdName}: --payee-amount is REQUIRED when the sig file's purpose is ARP-SOLANA-PARTIAL-RELEASE-v1.5 (the server reconstructs the same digest at cosign and binds payee_amount into it; missing here = unverifiable digest).`
+    );
+  }
+  if (isFull && opts.payeeAmount !== void 0 && opts.payeeAmount !== "") {
+    throw new Error(
+      `${cmdName}: --payee-amount must be OMITTED when the sig file's purpose is ARP-SOLANA-RELEASE-v1.5 (full release settles the whole lock; supplying an amount alongside the RELEASE purpose is almost certainly a wrong-purpose-flag bug).`
+    );
+  }
+  if (opts.payeeAmount !== void 0 && opts.payeeAmount !== "" && !/^[0-9]+$/.test(opts.payeeAmount)) {
+    throw new Error(
+      `${cmdName}: --payee-amount must be a decimal-integer base-unit string (got '${opts.payeeAmount}'); hex/empty/signed/decimal forms are rejected \u2014 same invariant as receipt.usage.computed_amount.`
+    );
+  }
+  const sender = resolveSenderAgent(cmdName, opts.server, opts.fromDid);
+  const api = new ArpApiClient(opts.server);
+  const content = {
+    delegation_id: delegationId,
+    receipt_event_hash: opts.receiptEventHash,
+    purpose: sigFile.purpose,
+    payee_settlement_pubkey: sigFile.settlement_pubkey,
+    sig: sigFile.sig,
+    expires_at: expiresAtSeconds,
+    ...isPartial ? { payee_amount: opts.payeeAmount } : {}
+  };
+  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_chalk21.default.dim(`Payee amount: ${opts.payeeAmount}`));
+  }
+  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,
+    recipientDid,
+    content,
+    ttlSeconds,
+    verbose: opts.verbose,
+    server: opts.server
+  });
+  printIngestResult3(result);
+}
+async function sendSettlementSignatureEnvelope(args) {
+  const nextSequence = (args.sender.lastSenderSequence ?? 0) + 1;
+  const protectedBlock = {
+    protocol_version: "arp/0.1",
+    purpose: import_sdk11.Purpose.ENVELOPE,
+    message_id: (0, import_sdk11.uuidV4)(),
+    sender_did: args.sender.did,
+    recipient_did: args.recipientDid,
+    relationship_id: null,
+    sender_sequence: nextSequence,
+    sender_nonce: (0, import_sdk11.senderNonce)(),
+    timestamp: (0, import_sdk11.rfc3339)(),
+    expires_at: (0, import_sdk11.expiresAt)(args.ttlSeconds),
+    delivery_id: null
+  };
+  const signer = makeSigner(args.sender);
+  const envelope = (0, import_sdk11.signEnvelope)({
+    protected: protectedBlock,
+    body: { type: "settlement_signature", content: args.content },
+    identitySecretKey: signer.identitySecretKey
+  });
+  if (args.verbose) {
+    console.log(import_chalk21.default.bold("\nEnvelope (pre-send):"));
+    console.log(formatJson(envelope));
+  }
+  try {
+    const result = await args.api.ingest(envelope);
+    updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
+    return result;
+  } catch (err) {
+    if (err instanceof ApiError && POST_COMMIT_ERROR_CODES4.has(err.payload.code)) {
+      updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
+    }
+    throw err;
+  }
 }
 async function sendReceiptEnvelope(args) {
   const nextSequence = (args.sender.lastSenderSequence ?? 0) + 1;
@@ -5653,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 {
@@ -5703,15 +6698,21 @@ async function resolveCosignTargets(cmdName, api, signer, args) {
   if (row.callerDid !== args.selfDid) {
     throw new Error(`${cmdName}: this receipt's caller is ${row.callerDid}; only the caller can cosign. Switch with --from-did.`);
   }
-  return { payeeDid: row.payeeDid, receiptEventHash: row.receiptEventHash, verdictProposed: row.verdictProposed, notesHash: row.notesHash };
+  return {
+    payeeDid: row.payeeDid,
+    receiptEventHash: row.receiptEventHash,
+    verdictProposed: row.verdictProposed,
+    notesHash: row.notesHash,
+    payeeSettlement: row.payeeSettlement
+  };
 }
 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";
@@ -5764,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) {
@@ -5793,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;
@@ -5808,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("");
@@ -5826,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() {
@@ -5857,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) {
@@ -5894,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();
@@ -5956,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);
@@ -6045,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 });
@@ -6061,30 +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(`
-\u26A0 Auto-publish failed (${err.message}). Agent saved as DRAFT \u2014 run \`heyarp publish ${result.did}\` to make it discoverable.`));
+      if (!opts.json)
+        console.log(
+          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(
@@ -6169,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);
     }
   }) : {};
@@ -6192,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
@@ -6214,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"
     )
   );
@@ -6238,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}`);
   }
@@ -6285,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) {
@@ -6305,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) {
@@ -6331,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;
@@ -6356,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"];
@@ -6374,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",
@@ -6384,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;
     }
   }
@@ -6460,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, "/");
@@ -6485,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) => {
@@ -6498,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;
@@ -6527,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) {
@@ -6565,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) {
@@ -6576,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
@@ -6585,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}')`);
   }
@@ -6597,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 {
@@ -6614,10 +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).`));
-          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(`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(`Last event index: ${existing.lastEventIndex}, last server event hash: ${existing.lastServerEventHash ?? "(none)"}`));
           return;
         }
         throw new Error(
@@ -6628,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 };
@@ -6658,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) {
@@ -6732,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) => {
@@ -6744,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;
@@ -6765,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") {
@@ -6779,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.`);
@@ -6787,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;
@@ -6801,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)}...`;
 }
@@ -6826,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(
@@ -6861,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}`);
         }
@@ -6876,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");
@@ -6935,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(
@@ -6970,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);
 }
@@ -6984,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 {
@@ -7042,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;
@@ -7085,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}`);
@@ -7139,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`);
@@ -7160,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) {
@@ -7187,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;
@@ -7202,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("");
@@ -7219,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;
@@ -7292,11 +8962,14 @@ async function checkForUpdates() {
 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.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);
@@ -7307,6 +8980,7 @@ async function main() {
   registerDidDocCommand(program);
   registerDoctorCommand(program);
   registerEscrowCommands(program);
+  registerExamplesCommand(program);
   registerWhoamiCommand(program);
   registerLifecycleCommands(program);
   registerRotateCommand(program);
@@ -7328,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) => {