@heyanon-arp/cli 0.0.2 → 0.0.4

package/dist/cli.js

@@ -431,9 +431,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,20 +710,10 @@ var import_simple_update_notifier = __toESM(require("simple-update-notifier"));
 // package.json
 var package_default = {
   name: "@heyanon-arp/cli",
-  version: "0.0.2",
+  version: "0.0.4",
   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"
   },
@@ -1177,8 +1165,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 +1244,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 +1329,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 +1381,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 +1436,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 +1455,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 };
@@ -1574,13 +1587,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 +1657,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 +1883,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 +1978,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) {
@@ -2260,7 +2259,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 +2283,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 +2294,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 +2309,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 +2326,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.`
     );
   }
 }
@@ -2607,10 +2610,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 +2649,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 +2691,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 +2704,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 +2814,30 @@ 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", 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,12 +2847,18 @@ 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);
   });
 }
@@ -2826,6 +2867,8 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
   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 +2879,15 @@ 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
+    });
+  }
   const content = {
     action,
     delegation_id: delegationId,
@@ -2939,7 +2991,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 +3212,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 +3249,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);
   });
 }
@@ -3901,7 +4068,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(
@@ -4344,20 +4513,21 @@ var GUIDE = [
   "   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("8. Live tail vs polling \u2014 the FSM-wait pattern"),
+  "   ANTIPATTERN: bash-loop `heyarp inbox` every 5s. Three fixes:",
+  "   (a) `--wait-until <phase>` on the action itself \u2014 most ergonomic:",
+  "     heyarp delegation offer <recip> <ctr> --wait-until delegation.accepted",
+  "     heyarp contract propose <recip> ...   --wait-until contract.active",
+  "     heyarp receipt cosign  <rel> <del> ... --wait-until cycle.released",
+  "   (b) `heyarp status <rel-id> --wait --until <phase>` standalone",
+  "   (use when the action already exited). Exit 124 on --wait-timeout.",
+  "   (c) `heyarp inbox --tail` SSE stream for long-running workers.",
+  "   `stream ended unexpectedly` (exit \u2260 0) = server EOF; re-run.",
+  "   `stream closed.` (exit 0) = your Ctrl-C; nothing to fix.",
+  "   If you must poll without SSE/--wait, persist a cursor:",
+  "     heyarp inbox --since <ts> --since-event-id <evt> --json",
+  "   SDK consumers: `pollUntil` from `@heyanon-arp/sdk` gives the",
+  "   same loop discipline with abort + timeout primitives.",
   "",
   import_chalk14.default.bold("9. Receipt closure semantics + settlement signatures"),
   "   - The PAYEE proposes (`heyarp receipt propose`) with their verdict +",
@@ -4685,12 +4855,8 @@ ${events.length} event(s) (oldest-first).${addressedToMeHint} Advance the forwar
       )
     );
   } 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_chalk16.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) {
@@ -5044,7 +5210,10 @@ function formatMemoryLine(r) {
   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}`;
 }
 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);
   });
 }
@@ -5095,14 +5264,15 @@ function parseLimit6(cmdName, raw) {
 }
 
 // src/commands/receipt.ts
+var import_node_fs7 = require("fs");
 var import_sdk11 = require("@heyanon-arp/sdk");
 var import_chalk20 = __toESM(require("chalk"));
-var import_node_fs7 = require("fs");
 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",
@@ -5156,7 +5326,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}$/;
@@ -5206,7 +5401,11 @@ 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)`));
+      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)`
+        )
+      );
     }
     requireUuid3("receipt propose", opts.relId, "--rel-id");
     const computed = await computeWorkLogHashes(api, sender, opts.relId, delegationId, opts.requestId);
@@ -5257,9 +5456,7 @@ Receipt event hash: ${import_chalk20.default.cyan(result.serverEventHash)}`));
 }
 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 +5469,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 +5506,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,20 +5563,38 @@ 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) {
+        console.error(formatActionError(err, cmd));
+        process.exitCode = 1;
+      }
     }
-  });
+  );
 }
 function loadSettlementSigFromFile(path, flagPrefix) {
   let raw;
@@ -5403,7 +5618,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 +5633,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 +5717,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 +5736,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 === "")) {
@@ -5612,6 +5857,12 @@ async function runCosign(relationshipId, delegationId, requestHashArg, responseH
   } else if (opts.clearNotes) {
     console.log(import_chalk20.default.dim("Notes binding: cleared (--clear-notes)"));
   }
+  if (opts.autoResolvePayeeSig) {
+    applyAutoResolvePayeeSig("receipt cosign", opts, resolved.payeeSettlement);
+    console.log(
+      import_chalk20.default.dim(`Auto-resolved payee sig from receipt.payeeSettlement (purpose=${resolved.payeeSettlement?.purpose}, expires_at=${resolved.payeeSettlement?.expires_at})`)
+    );
+  }
   const settlementSigs = assembleSettlementSignaturesAttachment(opts);
   const attachments = { co_signature: cosignature };
   if (settlementSigs) {
@@ -5629,6 +5880,149 @@ 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) {
+      console.error(formatActionError(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_chalk20.default.dim(`Server: ${api.serverUrl}`));
+  console.log(import_chalk20.default.dim(`Sender (payee): ${sender.did}`));
+  console.log(import_chalk20.default.dim(`Recipient (buyer): ${recipientDid}`));
+  console.log(import_chalk20.default.dim(`Delegation: ${delegationId}`));
+  console.log(import_chalk20.default.dim(`Receipt event hash: ${opts.receiptEventHash}`));
+  console.log(import_chalk20.default.dim(`Purpose: ${sigFile.purpose}`));
+  if (isPartial) {
+    console.log(import_chalk20.default.dim(`Payee amount: ${opts.payeeAmount}`));
+  }
+  console.log(import_chalk20.default.dim(`Settlement pubkey: ${sigFile.settlement_pubkey}`));
+  console.log(import_chalk20.default.dim(`Expires at: ${expiresAtSeconds}`));
+  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_chalk20.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;
@@ -5703,7 +6097,13 @@ 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."));
@@ -6065,8 +6465,11 @@ async function runRegister(opts) {
 \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_chalk22.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";
@@ -6616,7 +7019,9 @@ async function runSendHandshakeResponse(recipientDid, opts) {
         if (previousResponseFromMe) {
           console.log(import_chalk26.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(`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)"}`));
           return;
         }
@@ -7292,11 +7697,7 @@ 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("0.0.1").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);
   registerConfigCommand(program);
   registerGuideCommand(program);
   registerHomesCommand(program);