@heyanon-arp/cli 0.0.8 → 0.0.10

package/dist/cli.js

@@ -643,6 +643,22 @@ function formatGenericError(err, verbose = false) {
   return `${import_chalk.default.red("Error")} ${message}
 ${import_chalk.default.gray(err.stack)}`;
 }
+function onboardingHelpFooter() {
+  return [
+    "",
+    "New here? The guides ship inside the CLI \u2014 read them first, no docs site needed:",
+    `  ${import_chalk.default.cyan("heyarp guide")}                 ${import_chalk.default.dim("role-based walkthrough (worker / buyer)")}`,
+    `  ${import_chalk.default.cyan("heyarp guide --setup")}         ${import_chalk.default.dim("one-time setup: keys, server, multi-agent isolation")}`,
+    `  ${import_chalk.default.cyan("heyarp guide --troubleshoot")}  ${import_chalk.default.dim("common errors \u2192 fixes")}`,
+    "",
+    `${import_chalk.default.bold("Driving heyarp from an AI agent?")} Pipe YOUR role's guide into its system prompt`,
+    import_chalk.default.dim("(role is per-deal: BUYER if you send the offer + pay; WORKER if an offer comes to you):"),
+    `  ${import_chalk.default.cyan("heyarp guide --role worker --format prompt")}   ${import_chalk.default.dim("# you do tasks, get paid")}`,
+    `  ${import_chalk.default.cyan("heyarp guide --role buyer  --format prompt")}   ${import_chalk.default.dim("# you order tasks, pay")}`,
+    "",
+    `${import_chalk.default.dim("Then:")} ${import_chalk.default.cyan("heyarp register")} ${import_chalk.default.dim("\u2192 handshake \u2192 delegation \u2192 work \u2192 receipt \u2192 settlement.")}`
+  ].join("\n");
+}
 function toCliErrorJson(err, includeStack = false) {
   const { ApiError: ApiError2 } = (init_api(), __toCommonJS(api_exports));
   if (err instanceof ApiError2) {
@@ -3547,9 +3563,15 @@ async function readOnChainLock(api, opts, delegationId) {
     const programId = new import_web33.PublicKey(resolved.programId);
     const { lockPda } = deriveLockPda(programId, delegationId);
     const conn = new import_web33.Connection(rpcUrl, "confirmed");
-    const info = await conn.getAccountInfo(lockPda);
+    let info = await conn.getAccountInfo(lockPda);
+    for (let attempt = 1; attempt <= LOCK_READ_NOT_VISIBLE_RETRIES && !info; attempt++) {
+      await new Promise((r) => setTimeout(r, LOCK_READ_RETRY_DELAY_MS));
+      info = await conn.getAccountInfo(lockPda);
+    }
     if (!info) {
-      return { skipReason: `lock account ${lockPda.toBase58()} not visible on this RPC yet (create_lock may still be confirming)` };
+      return {
+        skipReason: `lock account ${lockPda.toBase58()} not visible on this RPC yet after ${LOCK_READ_NOT_VISIBLE_RETRIES + 1} attempts (create_lock may still be confirming / RPC lag)`
+      };
     }
     const lock = decodeLockAccount(info.data);
     if (!lock) {
@@ -3832,7 +3854,7 @@ async function autoSignAndDeliverPayeeSig(opts, cmdName = "receipt propose") {
     serverTimestamp: result.serverTimestamp
   };
 }
-var import_sdk10, import_utils3, import_web33, import_chalk17, NATIVE_SOL_MINT2, SETTLEMENT_MIN_EXPIRY_HEADROOM_SECS, SETTLEMENT_REFRESH_HEADROOM_SECS;
+var import_sdk10, import_utils3, import_web33, import_chalk17, NATIVE_SOL_MINT2, SETTLEMENT_MIN_EXPIRY_HEADROOM_SECS, SETTLEMENT_REFRESH_HEADROOM_SECS, LOCK_READ_NOT_VISIBLE_RETRIES, LOCK_READ_RETRY_DELAY_MS;
 var init_settlement = __esm({
   "src/commands/settlement.ts"() {
     import_sdk10 = require("@heyanon-arp/sdk");
@@ -3852,6 +3874,8 @@ var init_settlement = __esm({
     NATIVE_SOL_MINT2 = "11111111111111111111111111111111";
     SETTLEMENT_MIN_EXPIRY_HEADROOM_SECS = 120;
     SETTLEMENT_REFRESH_HEADROOM_SECS = 600;
+    LOCK_READ_NOT_VISIBLE_RETRIES = 3;
+    LOCK_READ_RETRY_DELAY_MS = 2e3;
   }
 });
 
@@ -3907,6 +3931,14 @@ function registerPropose(parent) {
       await runPropose(recipientDid, delegationId, requestHash, responseHash, opts);
     } catch (err) {
       emitActionError(err, cmd);
+      if (!opts.json && err instanceof ApiError && err.payload.code === "RECEIPT_ALREADY_EXISTS") {
+        console.error(
+          import_chalk18.default.dim(
+            `  This receipt already exists (a prior propose committed it). Do NOT re-propose \u2014 to (re)deliver the payee settlement signature, run:
+    'heyarp receipt send-payee-sig ${recipientDid} --delegation-id ${delegationId} --auto --cluster-tag ${opts.clusterTag ?? "<0|1>"}'`
+          )
+        );
+      }
       process.exitCode = 1;
     }
   });
@@ -4054,7 +4086,12 @@ async function runPropose(recipientDid, delegationId, requestHashArg, responseHa
       json.settlement = {
         delivered: false,
         error: settlementError.message,
-        recovery: `heyarp receipt send-payee-sig ${recipientDid} --delegation-id ${delegationId} --receipt-event-hash ${result.serverEventHash} --sig-from-file <path> --expires-at <unix> (after signing with 'heyarp wallet sign-settlement-release')`
+        // Authoritative recovery (SR-2/SR-3): re-sign + re-deliver via
+        // --auto, which resolves condition_hash + the on-chain lock
+        // snapshot itself — no hand-typed hashes, no sig file, no
+        // lock_id/condition_hash trap. Do NOT re-run `receipt propose`
+        // (the receipt already exists; a second propose is a duplicate).
+        recovery: `heyarp receipt send-payee-sig ${recipientDid} --delegation-id ${delegationId} --auto --cluster-tag ${opts.clusterTag ?? "<0|1>"} (do NOT re-run 'receipt propose' \u2014 the receipt already exists, a second propose is rejected as a duplicate)`
       };
     } else if (settlementResult) {
       json.settlement = {
@@ -4079,14 +4116,9 @@ Receipt event hash: ${import_chalk18.default.cyan(result.serverEventHash)}`));
   if (settlementError) {
     console.error(import_chalk18.default.yellow("\nWARNING: receipt proposed, but the payee settlement signature was NOT delivered."));
     console.error(import_chalk18.default.yellow(`  reason: ${settlementError.message}`));
-    console.error(import_chalk18.default.dim("  The receipt stays committed \u2014 re-running `receipt propose` will NOT help (it hits RECEIPT_ALREADY_EXISTS)."));
-    console.error(import_chalk18.default.dim("  Recover by signing + delivering the payee sig directly, once the on-chain lock / RPC is reachable:"));
-    console.error(
-      import_chalk18.default.dim(
-        `    'heyarp wallet sign-settlement-release ... --write-to <path>' then
-    'heyarp receipt send-payee-sig ${recipientDid} --delegation-id ${delegationId} --receipt-event-hash ${result.serverEventHash} --sig-from-file <path> --expires-at <unix>'`
-      )
-    );
+    console.error(import_chalk18.default.dim("  The receipt stays committed \u2014 do NOT re-run `receipt propose` (the receipt already exists; a second propose is rejected as a duplicate)."));
+    console.error(import_chalk18.default.dim("  Recover authoritatively \u2014 this resolves condition_hash + the on-chain lock snapshot for you (no manual hashes, no sig file):"));
+    console.error(import_chalk18.default.dim(`    'heyarp receipt send-payee-sig ${recipientDid} --delegation-id ${delegationId} --auto --cluster-tag ${opts.clusterTag ?? "<0|1>"}'`));
   } else if (settlementResult?.delivered) {
     console.log(import_chalk18.default.green("\nPayee settlement signature signed + delivered (escrow)."));
     console.log(
@@ -4551,18 +4583,32 @@ async function runCosign(relationshipId, delegationId, requestHashArg, responseH
   }
 }
 function registerSendPayeeSig(parent) {
-  parent.command("send-payee-sig").description("Send the payee's settlement signature to the buyer via a settlement_signature envelope. Replaces /tmp/*.json coordination for cross-host escrow cycles.").argument("<recipient-did>", "Buyer DID (= caller / offerer of the parent delegation; the cycle sends the sig to the side that will cosign)").requiredOption("--delegation-id <id>", "Parent delegation UUID \u2014 must match what was passed to `heyarp wallet sign-settlement-release`.").requiredOption(
+  parent.command("send-payee-sig").description(
+    "Send the payee's settlement signature to the buyer via a settlement_signature envelope. Replaces /tmp/*.json coordination for cross-host escrow cycles. Two modes: (1) MANUAL \u2014 supply --receipt-event-hash + --sig-from-file + --expires-at from a prior `wallet sign-settlement-release`; (2) --auto (RECOMMENDED for recovery) \u2014 resolves condition_hash + the on-chain lock snapshot AUTHORITATIVELY and re-signs (force), so you pass NO --sig-from-file and NO hand-typed hashes. Use --auto to recover when `receipt propose` did not deliver the sig (e.g. the just-confirmed lock was not yet RPC-visible); do NOT re-run `receipt propose` (the receipt already exists \u2014 a second propose is rejected as a duplicate)."
+  ).argument(
+    "[recipient-did]",
+    "Buyer DID (= caller / offerer of the parent delegation; the cycle sends the sig to the side that will cosign). Optional under --auto \u2014 the buyer is resolved from the delegation/receipt."
+  ).requiredOption("--delegation-id <id>", "Parent delegation UUID \u2014 must match what was passed to `heyarp wallet sign-settlement-release`.").option(
+    "--auto",
+    "Authoritative recovery: resolve condition_hash (over the delegation terms) + the on-chain lock snapshot (mint / amount / expiry / fee) and re-sign the release digest (force), then deliver it. Use this to recover when `receipt propose` did not deliver the sig \u2014 you do NOT pass --sig-from-file or --receipt-event-hash with --auto, and there is no lock_id/condition_hash trap. Requires --cluster-tag; mutually exclusive with --sig-from-file. Do NOT re-run `receipt propose` (the receipt already exists; a second propose is rejected as a duplicate)."
+  ).option(
+    "--cluster-tag <0|1>",
+    "REQUIRED under --auto: 0 = devnet, 1 = mainnet-beta. Binds the cluster into the signed release digest (no safe default; a wrong cluster fails at the buyer cosign)."
+  ).option(
+    "--rpc-url <url>",
+    "Solana RPC endpoint for the --auto on-chain lock read (resolves mint / amount / expiry / fee). Falls back to ARP_ESCROW_RPC_URL then `heyarp config get rpcUrl`; when none is set the on-chain check is skipped and the server stays the boundary."
+  ).option("--program-id <pubkey>", "Escrow program id for the --auto on-chain lock read (auto-discovered from the server when omitted).").option("--rel-id <id>", "Relationship UUID \u2014 under --auto, auto-derived from the delegation when omitted.").option(
     "--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(
+    "MANUAL path: 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. NOT needed with --auto (the helper resolves the receipt; pass it only to disambiguate >1 proposed receipt)."
+  ).option(
     "--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(
+    "MANUAL 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). MUTUALLY EXCLUSIVE with --auto."
+  ).option(
     "--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."
+    "MANUAL path: 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. Under --auto this is optional (derived from the delegation deadline; pass it only to override)."
   ).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 delegations). Same value passed to `--partial-payee-amount` on sign-settlement-release. FORBIDDEN for `ARP-SOLANA-RELEASE-v1.5` (full release settles the whole lock)."
+    "Base-unit decimal-integer payee_amount \u2014 REQUIRED on the MANUAL path when the sig file's purpose is `ARP-SOLANA-PARTIAL-RELEASE-v1.5` (usage_based delegations). Same value passed to `--partial-payee-amount` on sign-settlement-release. FORBIDDEN for `ARP-SOLANA-RELEASE-v1.5` (full release settles the whole lock). Under --auto the partial amount is bound from the receipt; pass it only as a confirmation that must match."
   ).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);
@@ -4574,20 +4620,85 @@ function registerSendPayeeSig(parent) {
 }
 async function runSendPayeeSig(recipientDid, opts) {
   const cmdName = "receipt send-payee-sig";
+  if (opts.auto) {
+    if (opts.sigFromFile !== void 0 && opts.sigFromFile !== "") {
+      throw new Error(
+        `${cmdName}: --auto and --sig-from-file are mutually exclusive. --auto re-signs the release digest AUTHORITATIVELY (it resolves condition_hash + the on-chain lock itself); a --sig-from-file is the MANUAL path's pre-signed input. Pick one: --auto for recovery, or the manual --sig-from-file + --receipt-event-hash + --expires-at trio.`
+      );
+    }
+    if (opts.clusterTag === void 0 || opts.clusterTag === "") {
+      throw new Error(
+        `${cmdName}: --cluster-tag is required with --auto (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.clusterTag !== "0" && opts.clusterTag !== "1") {
+      throw new Error(`${cmdName}: --cluster-tag must be '0' (devnet) or '1' (mainnet-beta), got '${opts.clusterTag}'`);
+    }
+    const delegationIdAuto = requireUuidNormalised2(cmdName, opts.delegationId, "--delegation-id");
+    if (recipientDid !== void 0 && recipientDid !== "") {
+      requireDid2(cmdName, recipientDid, "[recipient-did]");
+    }
+    const { autoSignAndDeliverPayeeSig: autoSignAndDeliverPayeeSig2 } = await Promise.resolve().then(() => (init_settlement(), settlement_exports));
+    await autoSignAndDeliverPayeeSig2(
+      {
+        server: opts.server,
+        fromDid: opts.fromDid,
+        delegationId: delegationIdAuto,
+        ...opts.relId !== void 0 ? { relId: opts.relId } : {},
+        clusterTag: opts.clusterTag,
+        ...opts.expiresAt !== void 0 ? { expiresAt: opts.expiresAt } : {},
+        ...opts.rpcUrl !== void 0 ? { rpcUrl: opts.rpcUrl } : {},
+        ...opts.programId !== void 0 ? { programId: opts.programId } : {},
+        ...opts.payeeAmount !== void 0 ? { partialPayeeAmount: opts.payeeAmount } : {},
+        ...opts.receiptEventHash !== void 0 ? { receiptEventHash: opts.receiptEventHash } : {},
+        // Recovery semantics: re-sign + re-deliver even if a (bad) sig
+        // already exists. The helper short-circuits a cosigned receipt.
+        force: true
+        // `send-payee-sig` has no --json flag (the manual path prints a
+        // plain human block); leave the helper in its human-output mode.
+        // Do NOT pass silent — the helper owns + prints the recovery output.
+      },
+      cmdName
+    );
+    return;
+  }
+  if (recipientDid === void 0 || recipientDid === "") {
+    throw new Error(
+      `${cmdName}: <recipient-did> (the buyer DID) is required on the manual path. Pass it, or use --auto --cluster-tag <0|1> to resolve the buyer + re-sign authoritatively.`
+    );
+  }
   requireDid2(cmdName, recipientDid, "<recipient-did>");
+  const recipient = recipientDid;
   const delegationId = requireUuidNormalised2(cmdName, opts.delegationId, "--delegation-id");
+  if (opts.sigFromFile === void 0 || opts.sigFromFile === "") {
+    throw new Error(
+      `${cmdName}: --sig-from-file is required (the MANUAL path's pre-signed input). For authoritative recovery without a sig file, use --auto --cluster-tag <0|1> instead.`
+    );
+  }
+  if (opts.receiptEventHash === void 0 || opts.receiptEventHash === "") {
+    throw new Error(
+      `${cmdName}: --receipt-event-hash is required on the manual path. For authoritative recovery without hand-typed hashes, use --auto --cluster-tag <0|1> instead.`
+    );
+  }
+  if (opts.expiresAt === void 0 || opts.expiresAt === "") {
+    throw new Error(
+      `${cmdName}: --expires-at is required on the manual path (must match the value signed). For authoritative recovery, use --auto --cluster-tag <0|1> instead.`
+    );
+  }
   requireSha256(cmdName, opts.receiptEventHash, "--receipt-event-hash");
+  const receiptEventHash = opts.receiptEventHash;
+  const sigFromFile = opts.sigFromFile;
   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 = parseTtl2(cmdName, opts.ttl);
-  const sigFile = loadSettlementSigFromFile(opts.sigFromFile, "--sig-from-file");
+  const sigFile = loadSettlementSigFromFile(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.)`
+      `${cmdName}: sig file at '${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 === "")) {
@@ -4609,7 +4720,7 @@ async function runSendPayeeSig(recipientDid, opts) {
   const api = new ArpApiClient(opts.server);
   const content = {
     delegation_id: delegationId,
-    receipt_event_hash: opts.receiptEventHash,
+    receipt_event_hash: receiptEventHash,
     purpose: sigFile.purpose,
     payee_settlement_pubkey: sigFile.settlement_pubkey,
     sig: sigFile.sig,
@@ -4618,9 +4729,9 @@ async function runSendPayeeSig(recipientDid, opts) {
   };
   console.log(import_chalk18.default.dim(`Server: ${api.serverUrl}`));
   console.log(import_chalk18.default.dim(`Sender (payee): ${sender.did}`));
-  console.log(import_chalk18.default.dim(`Recipient (buyer): ${recipientDid}`));
+  console.log(import_chalk18.default.dim(`Recipient (buyer): ${recipient}`));
   console.log(import_chalk18.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk18.default.dim(`Receipt event hash: ${opts.receiptEventHash}`));
+  console.log(import_chalk18.default.dim(`Receipt event hash: ${receiptEventHash}`));
   console.log(import_chalk18.default.dim(`Purpose: ${sigFile.purpose}`));
   if (isPartial) {
     console.log(import_chalk18.default.dim(`Payee amount: ${opts.payeeAmount}`));
@@ -4630,7 +4741,7 @@ async function runSendPayeeSig(recipientDid, opts) {
   const result = await sendSettlementSignatureEnvelope({
     api,
     sender,
-    recipientDid,
+    recipientDid: recipient,
     content,
     ttlSeconds,
     verbose: opts.verbose,
@@ -4934,7 +5045,7 @@ var import_simple_update_notifier = __toESM(require("simple-update-notifier"));
 // package.json
 var package_default = {
   name: "@heyanon-arp/cli",
-  version: "0.0.8",
+  version: "0.0.10",
   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"],
@@ -4944,7 +5055,7 @@ var package_default = {
   publishConfig: {
     access: "public"
   },
-  files: ["dist", "scripts/postinstall.mjs", "LICENSE", "README.md"],
+  files: ["dist", "LICENSE", "README.md"],
   engines: {
     node: ">=22"
   },
@@ -4954,8 +5065,7 @@ var package_default = {
     test: "jest --runInBand --detectOpenHandles --forceExit --passWithNoTests",
     lint: "biome check . --write",
     prepublishOnly: "pnpm run build",
-    prepare: "pnpm run build",
-    postinstall: "node scripts/postinstall.mjs"
+    prepare: "pnpm run build"
   },
   dependencies: {
     "@heyanon-arp/sdk": "workspace:*",
@@ -5820,7 +5930,7 @@ var GUIDE_SECTIONS = [
       { 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 AND deliver your settlement signature in ONE command: `heyarp receipt propose <buyer-did> <del-id> --auto-hashes --rel-id <rel-id> --request-id <req-id> --verdict accepted --cluster-tag <0|1>`. Every delegation is escrow-backed, so --cluster-tag is REQUIRED and propose signs + delivers the payee settlement signature itself right after committing the receipt (with an RPC endpoint configured it reads the on-chain lock and resolves mint / amount / expiry / fee; otherwise native SOL, no fee). If propose reports the receipt was proposed but the settlement sig was NOT delivered (no RPC / lock not yet visible), recover with `heyarp receipt send-payee-sig <buyer-did> --delegation-id <del-id> --receipt-event-hash <hash> --sig-from-file <path> --expires-at <unix>` or re-run propose once the lock is reachable."
+        then: "propose the receipt AND deliver your settlement signature in ONE command: `heyarp receipt propose <buyer-did> <del-id> --auto-hashes --rel-id <rel-id> --request-id <req-id> --verdict accepted --cluster-tag <0|1>`. Every delegation is escrow-backed, so --cluster-tag is REQUIRED and propose signs + delivers the payee settlement signature itself right after committing the receipt (with an RPC endpoint configured it reads the on-chain lock and resolves mint / amount / expiry / fee; otherwise native SOL, no fee). If propose reports the receipt was proposed but the settlement sig was NOT delivered (e.g. the just-confirmed lock was not yet RPC-visible), recover AUTHORITATIVELY with `heyarp receipt send-payee-sig <buyer-did> --delegation-id <del-id> --auto --cluster-tag <0|1>` \u2014 it resolves condition_hash + the on-chain lock snapshot itself, so you hand-type NO hashes and supply NO sig file. Do NOT re-run `receipt propose` (the receipt already exists; a second propose is rejected as a duplicate)."
       },
       { when: "the buyer cosigns (cycle released)", then: "you are paid \u2014 the cycle is done; wait for the next offer" }
     ],
@@ -6016,7 +6126,17 @@ var GUIDE_SECTIONS = [
       "   `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`.",
+      "   `ARP-SOLANA-PARTIAL-RELEASE-v1.5`. WARNING: `--condition-hash` here is",
+      "   the SAME value `heyarp escrow derive-condition-hash` produces (the hash",
+      "   OVER THE TERMS) / the condition_hash on the on-chain lock \u2014 it is NOT",
+      "   the `lock_id` from `delegation.fund` attachments. lock_id",
+      '   (`sha256("arp-lock-v1"||delegation_id)`) and condition_hash',
+      "   (`sha256(terms)`) are DIFFERENT 32-byte values; the release digest binds",
+      "   condition_hash, so passing lock_id signs a digest the buyer cosign",
+      "   rejects (ESC_SETTLEMENT_SIG_INVALID). For the payee side, prefer",
+      "   `heyarp receipt send-payee-sig <buyer> --delegation-id <id> --auto`,",
+      "   which resolves condition_hash + the on-chain lock for you instead of",
+      "   hand-signing.",
       "   `heyarp receipt cosign` attaches both parties' signatures into",
       "   `attachments.settlement_signatures` via --settlement-purpose,",
       "   --settlement-expires-at, --payer-settlement-{pubkey,sig},",
@@ -6231,6 +6351,13 @@ var GUIDE_SECTIONS = [
       "     account for that mint exists.",
       "   \u2022 handshake stuck `pending` / delegation stuck `offered` \u2192 the COUNTERPARTY",
       "     has not acted; block on it with `heyarp status <rel-id> --wait --until <state>`.",
+      "   \u2022 `ESC_SETTLEMENT_SIG_INVALID` at `receipt cosign` \u2192 the payee signed the",
+      "     WRONG release digest \u2014 usually `--condition-hash` was set to the `lock_id`",
+      "     from a `delegation.fund` attachment (lock_id \u2260 condition_hash; the digest",
+      "     binds condition_hash). The payee re-delivers a correct sig with `heyarp",
+      "     receipt send-payee-sig <buyer> --delegation-id <id> --auto --cluster-tag",
+      "     <0|1>`, which resolves condition_hash from the on-chain lock (no manual",
+      "     hashes). Do NOT re-run `receipt propose` (the receipt already exists).",
       '   \u2022 "wrong move for my role" \u2192 you mixed up buyer vs worker; role is',
       '     PER-RELATIONSHIP \u2014 re-check with `heyarp guide` ("Which role am I?").',
       "   More: README at https://www.npmjs.com/package/@heyanon-arp/cli"
@@ -7069,13 +7196,11 @@ async function runRegister(opts, deps = defaultRegisterDeps) {
   });
   const settlementPublicKeyB58 = (0, import_sdk12.base58btcEncode)(keys.settlementPublicKey);
   const scryptSaltId = (0, import_sdk12.uuidV4)();
-  const ownerId = (0, import_sdk12.uuidV4)();
   const payload = {
     purpose: "ARP-KEY-LINK-v1",
     agent_did: did,
     identity_public_key: identityPublicKeyB58,
     settlement_public_key: settlementPublicKeyB58,
-    owner_id: ownerId,
     owner_signing_method: "scrypt_password_proof",
     link_method: "manual",
     created_at: (0, import_sdk12.rfc3339)(),
@@ -7108,7 +7233,6 @@ async function runRegister(opts, deps = defaultRegisterDeps) {
     scryptKeyB64: Buffer.from(scryptKey).toString("base64"),
     scryptSaltB64: Buffer.from(scryptSalt).toString("base64"),
     scryptSaltId,
-    ownerId,
     // Placeholder until the server confirms registration and returns
     // the canonical attestation id (finalized in Step 8 below).
     currentAttestationId: "",
@@ -8293,6 +8417,7 @@ async function main() {
       process.stderr.write(str);
     }
   });
+  program.addHelpText("after", () => onboardingHelpFooter());
   registerConfigCommand(program);
   registerGuideCommand(program);
   registerHomesCommand(program);