@heyanon-arp/cli 0.0.15 → 0.0.17

package/dist/cli.js

@@ -34,10 +34,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 function arpHomeDir() {
   const fromEnv = process.env.HEYARP_HOME;
   if (fromEnv && fromEnv.length > 0) return fromEnv;
-  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".arp");
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".heyarp");
 }
 function homesRegistryPath() {
-  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".arp", "homes.json");
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".heyarp", "homes.json");
 }
 var import_node_os, import_node_path;
 var init_paths = __esm({
@@ -354,9 +354,8 @@ var init_api = __esm({
       }
       /**
        * Signed-request authenticated GET /v1/agents/:did. Owner-only on
-       * the server side, but in V1 it returns the same shape as
-       * /did-document — useful as a sanity check that a stored secret
-       * key still verifies.
+       * the server side; it returns the same shape as /did-document —
+       * useful as a sanity check that a stored secret key still verifies.
        */
       async getAgent(did, signer) {
         return this.signedRequest("GET", `/v1/agents/${encodeURIComponent(did)}`, null, signer);
@@ -723,17 +722,17 @@ var import_simple_update_notifier = __toESM(require("simple-update-notifier"));
 // package.json
 var package_default = {
   name: "@heyanon-arp/cli",
-  version: "0.0.15",
+  version: "0.0.17",
   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"],
   bin: {
-    heyarp: "./dist/cli.js"
+    heyarp: "./bin/heyarp.cjs"
   },
   publishConfig: {
     access: "public"
   },
-  files: ["dist", "LICENSE", "README.md"],
+  files: ["dist", "bin", "LICENSE", "README.md"],
   engines: {
     node: ">=22"
   },
@@ -805,6 +804,14 @@ function onboardingHelpFooter() {
     `${import_chalk.default.dim("Then:")} ${import_chalk.default.cyan("heyarp register")} ${import_chalk.default.dim("\u2192 handshake \u2192 delegation \u2192 work \u2192 receipt \u2192 on-chain claim.")}`
   ].join("\n");
 }
+function optionPlacementHelpNote() {
+  return [
+    "",
+    `${import_chalk.default.bold("Option placement:")} only ${import_chalk.default.cyan("--trace")}, ${import_chalk.default.cyan("--help")}, ${import_chalk.default.cyan("--version")} are global (before the command).`,
+    `Everything else \u2014 ${import_chalk.default.cyan("--json")}, ${import_chalk.default.cyan("--from-did")}, ${import_chalk.default.cyan("--verbose")}, ${import_chalk.default.cyan("--server")}, \u2026 \u2014 is a command option and goes AFTER the command:`,
+    `  ${import_chalk.default.cyan("heyarp <command> [options]")}   ${import_chalk.default.dim("e.g. heyarp relationships --json --from-did did:arp:\u2026")}`
+  ].join("\n");
+}
 function toCliErrorJson(err, includeStack = false) {
   const { ApiError: ApiError2 } = (init_api(), __toCommonJS(api_exports));
   if (err instanceof ApiError2) {
@@ -822,7 +829,9 @@ function toCliErrorJson(err, includeStack = false) {
 }
 function emitError(err, opts) {
   if (opts.json) {
-    console.error(JSON.stringify(toCliErrorJson(err, opts.verbose)));
+    const obj = toCliErrorJson(err, opts.verbose);
+    if (opts.hint) obj.hint = opts.hint;
+    console.error(JSON.stringify(obj));
     return;
   }
   const { ApiError: ApiError2 } = (init_api(), __toCommonJS(api_exports));
@@ -831,6 +840,7 @@ function emitError(err, opts) {
   } else {
     console.error(formatGenericError(err, opts.verbose));
   }
+  if (opts.hint) console.error(`${import_chalk.default.yellow("hint")}: ${opts.hint}`);
 }
 function emitActionError(err, command) {
   let root = command;
@@ -1163,19 +1173,28 @@ function listAgents() {
 var import_chalk2 = __toESM(require("chalk"));
 init_api();
 function registerLifecycleCommands(root) {
-  root.command("update").description("Update an agent profile (name / description / tags). At least one flag is required.").argument("<did>").option("--server <url>", "Override ARP server base URL").option("--name <s>", "New display name").option("--description <s>", "New description").option("--tag <s>", "Capability tag \u2014 REPLACES the existing list. Repeatable: --tag translation --tag fr", accumulate, []).option("--clear-tags", "Drop all tags (cannot be combined with --tag)", false).action(
+  root.command("update").description("Update an agent profile (name / description / tags). At least one flag is required.").argument("[did]", "Agent DID (did:arp:...) \u2014 optional when --from-did is given OR exactly one agent is registered for the resolved server.").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Alias for the positional <did> \u2014 accepted for consistency with other signed commands. Must match the positional if both are given.").option("--name <s>", "New display name").option("--description <s>", "New description").option("--tag <s>", "Capability tag \u2014 REPLACES the existing list. Repeatable: --tag translation --tag fr", accumulate, []).option("--clear-tags", "Drop all tags (cannot be combined with --tag)", false).option("--json", "Machine-readable mode \u2014 emit the updated profile as a single JSON object on stdout (AgentPublic). Prelude moves to stderr. ", false).action(
     async (did, opts) => {
+      if (did !== void 0 && opts.fromDid !== void 0 && did !== opts.fromDid) {
+        throw new Error(`update: positional <did> (${did}) and --from-did (${opts.fromDid}) disagree \u2014 pass only one`);
+      }
+      const explicitDid = did ?? opts.fromDid;
+      const targetDid = (explicitDid !== void 0 ? loadAgentOrThrow(opts.server, explicitDid) : resolveSenderAgent("update", opts.server, void 0)).did;
       const body = buildUpdateBody(opts);
       if (Object.keys(body).length === 0) {
         throw new Error("update: pass at least one of --name / --description / --tag / --clear-tags");
       }
-      const agent = await actSigned(did, opts.server, (api, signer) => api.updateAgent(did, body, signer));
-      updateAgentLocal(opts.server, did, {
+      const agent = await actSigned(targetDid, opts.server, opts.json, (api, signer) => api.updateAgent(targetDid, body, signer));
+      updateAgentLocal(opts.server, targetDid, {
         name: agent.name,
         description: agent.description,
         tags: agent.tags
       });
-      printAgent("Updated", agent);
+      if (opts.json) {
+        jsonOut(agent);
+      } else {
+        printAgent("Updated", agent);
+      }
     }
   );
 }
@@ -1196,11 +1215,11 @@ function buildUpdateBody(opts) {
   }
   return body;
 }
-async function actSigned(did, serverOverride, act) {
+async function actSigned(did, serverOverride, json, act) {
   const local = loadAgentOrThrow(serverOverride, did);
   const api = new ArpApiClient(serverOverride);
-  console.log(import_chalk2.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk2.default.dim(`Signer: ${local.did}`));
+  progress(json, import_chalk2.default.dim(`Server: ${api.serverUrl}`));
+  progress(json, import_chalk2.default.dim(`Signer: ${local.did}`));
   const signer = makeSigner(local);
   return act(api, signer);
 }
@@ -1246,10 +1265,10 @@ function registerAgentsCommand(root) {
 }
 async function runAgents(opts) {
   const limit = parseLimit(opts.limit);
-  if (opts.sort && opts.sort !== "reputation" && opts.sort !== "recent" && opts.sort !== "created") {
+  if (opts.sort && opts.sort !== import_sdk2.DiscoverySorts.REPUTATION && opts.sort !== import_sdk2.DiscoverySorts.RECENT && opts.sort !== import_sdk2.DiscoverySorts.CREATED) {
     throw new Error(`agents: --sort must be 'reputation', 'recent', or 'created' (got '${opts.sort}')`);
   }
-  const sort = opts.sort === "recent" ? "recent" : opts.sort === "created" ? "created" : "reputation";
+  const sort = opts.sort === import_sdk2.DiscoverySorts.RECENT ? import_sdk2.DiscoverySorts.RECENT : opts.sort === import_sdk2.DiscoverySorts.CREATED ? import_sdk2.DiscoverySorts.CREATED : import_sdk2.DiscoverySorts.REPUTATION;
   const api = new ArpApiClient(opts.server);
   progress(opts.json, import_chalk3.default.dim(`Server: ${api.serverUrl}`));
   const query = { limit, sort };
@@ -1258,7 +1277,7 @@ async function runAgents(opts) {
   if (opts.accountId) query.accountId = opts.accountId;
   if (opts.accepts) query.accepts = resolveAcceptsAsset(opts.accepts);
   if (opts.online) query.online = true;
-  if (sort === "created") {
+  if (sort === import_sdk2.DiscoverySorts.CREATED) {
     if (opts.after) query.after = opts.after;
   } else {
     query.page = parsePage(opts.page);
@@ -1297,10 +1316,10 @@ ${rule}`);
 `);
   }
   if (pagination.hasMore) {
-    if (sort === "created" && pagination.nextCursor) {
+    if (sort === import_sdk2.DiscoverySorts.CREATED && pagination.nextCursor) {
       console.log(import_chalk3.default.dim(`
 Next page: re-run with --after ${pagination.nextCursor}`));
-    } else if (sort !== "created") {
+    } else if (sort !== import_sdk2.DiscoverySorts.CREATED) {
       console.log(import_chalk3.default.dim(`
 Next page: re-run with --page ${parsePage(opts.page) + 1}`));
     }
@@ -1496,13 +1515,14 @@ function registerAssetsCommand(root) {
 }
 
 // src/commands/block.ts
+var import_sdk4 = require("@heyanon-arp/sdk");
 var import_chalk5 = __toESM(require("chalk"));
 init_api();
 function resolveSigningAgent(opts) {
   return opts.fromDid !== void 0 ? loadAgentOrThrow(opts.server, opts.fromDid) : resolveSenderAgent("block", opts.server, void 0);
 }
 function formatBlockRow(b) {
-  const scope = b.scope === "account" ? import_chalk5.default.yellow("account") : import_chalk5.default.cyan("did");
+  const scope = b.scope === import_sdk4.InboxBlockScopes.ACCOUNT ? import_chalk5.default.yellow("account") : import_chalk5.default.cyan("did");
   const reason = b.reason ? import_chalk5.default.dim(` \u2014 ${b.reason}`) : "";
   return `${scope.padEnd(7)}  ${b.did}${reason}  ${import_chalk5.default.dim(b.blockedAt)}`;
 }
@@ -1527,7 +1547,7 @@ async function runAdd(did, opts) {
     jsonOut(result);
     return;
   }
-  const what = result.scope === "account" ? `the owner account of ${did} (all its agents)` : did;
+  const what = result.scope === import_sdk4.InboxBlockScopes.ACCOUNT ? `the owner account of ${did} (all its agents)` : did;
   console.log(import_chalk5.default.green(`\u2713 Blocked ${what}.`));
 }
 async function runRemove(did, opts) {
@@ -1564,7 +1584,7 @@ var import_chalk6 = __toESM(require("chalk"));
 init_api();
 init_config();
 function registerConfigCommand(root) {
-  const config = root.command("config").description("Read/write persistent CLI configuration (~/.arp/config.json)").option("--server <url>", "Override the server URL whose bucket per-server keys (e.g. defaultDid) read/write to");
+  const config = root.command("config").description("Read/write persistent CLI configuration (~/.heyarp/config.json)").option("--server <url>", "Override the server URL whose bucket per-server keys (e.g. defaultDid) read/write to");
   config.command("set <key> <value>").description(`Persist a config value. Global keys: ${GLOBAL_CONFIG_KEYS.join(", ")}. Per-server keys: ${SERVER_CONFIG_KEYS.join(", ")}`).action((key, value) => {
     const opts = config.opts();
     if (isGlobalConfigKey(key)) {
@@ -1643,14 +1663,15 @@ function unknownKey(key) {
 
 // src/commands/delegation.ts
 var import_node_fs4 = require("fs");
-var import_sdk7 = require("@heyanon-arp/sdk");
+var import_sdk10 = require("@heyanon-arp/sdk");
 var import_chalk8 = __toESM(require("chalk"));
 init_api();
 
 // src/id-format.ts
+var import_sdk5 = require("@heyanon-arp/sdk");
 var UUID_RE = /^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/;
 var OBJECT_ID_24_HEX_RE = /^[0-9a-f]{24}$/;
-var SHA256_PREFIX_RE = /^sha256:[0-9a-f]{64}$/;
+var SHA256_PREFIX_RE = import_sdk5.SHA256_HEX_RE;
 var UUID_NO_DASHES_RE = /^[a-fA-F0-9]{32}$/;
 function describeNonUuidShape(raw) {
   if (raw === "") return "empty string";
@@ -1682,11 +1703,11 @@ function requireUuid(cmdName, raw, label) {
 }
 
 // src/commands/status.ts
-var import_sdk4 = require("@heyanon-arp/sdk");
+var import_sdk6 = require("@heyanon-arp/sdk");
 var import_chalk7 = __toESM(require("chalk"));
 init_api();
 var UNTIL_PHASES = [
-  "delegation.proposed",
+  "delegation.offered",
   "delegation.accepted",
   "delegation.locked",
   "delegation.disputing",
@@ -1695,7 +1716,6 @@ var UNTIL_PHASES = [
   "work.requested",
   "work.responded",
   "receipt.proposed",
-  "receipt.cosigned",
   "relationship.pending",
   "relationship.active",
   "relationship.paused",
@@ -1784,13 +1804,13 @@ async function awaitFsmTransitionAfterAction(input) {
   }
 }
 async function runWaitLoop(opts) {
-  const isTerminal = (s) => s.cycleComplete || s.relationshipState === "closed" || s.relationshipState === "not_found";
+  const isTerminal = (s) => s.cycleComplete || s.relationshipState === import_sdk6.RelationshipStates.CLOSED || s.relationshipState === "not_found";
   const isActionable = (s) => {
     if (s.nextActionOwner === "me") {
       if (s.relationshipState === "unknown") return false;
       return true;
     }
-    if (s.nextActionOwner === "either" && s.relationshipState === "active") {
+    if (s.nextActionOwner === "either" && s.relationshipState === import_sdk6.RelationshipStates.ACTIVE) {
       return true;
     }
     return false;
@@ -1926,43 +1946,41 @@ function parseUntilPhase(raw) {
 function isPhaseTerminallyUnreachable(phase, s) {
   if (untilPhaseMatched(phase, s)) return false;
   if (s.relationshipState === "not_found") return true;
-  if (s.relationshipState === "closed" && phase !== "relationship.closed") return true;
+  if (s.relationshipState === import_sdk6.RelationshipStates.CLOSED && phase !== "relationship.closed") return true;
   return false;
 }
 function untilPhaseMatched(phase, s) {
   switch (phase) {
-    case "delegation.proposed":
-      return s.latestDelegation?.state === "proposed" || s.latestDelegation?.state === "offered";
+    case "delegation.offered":
+      return s.latestDelegation?.state === import_sdk6.DelegationStates.OFFERED;
     case "delegation.accepted":
-      return s.latestDelegation?.state === "accepted";
+      return s.latestDelegation?.state === import_sdk6.DelegationStates.ACCEPTED;
     case "delegation.locked":
-      return s.latestDelegation?.state === "locked";
+      return s.latestDelegation?.state === import_sdk6.DelegationStates.LOCKED;
     case "delegation.disputing":
-      return s.latestDelegation?.state === "disputing";
+      return s.latestDelegation?.state === import_sdk6.DelegationStates.DISPUTING;
     case "delegation.canceled":
-      return s.latestDelegation?.state === "canceled";
+      return s.latestDelegation?.state === import_sdk6.DelegationStates.CANCELED;
     case "delegation.declined":
-      return s.latestDelegation?.state === "declined";
+      return s.latestDelegation?.state === import_sdk6.DelegationStates.DECLINED;
     case "work.requested":
-      return s.latestWorkLog?.state === "requested";
+      return s.latestWorkLog?.state === import_sdk6.WorkLogStates.REQUESTED;
     case "work.responded":
-      return s.latestWorkLog?.state === "responded";
+      return s.latestWorkLog?.state === import_sdk6.WorkLogStates.RESPONDED;
     case "receipt.proposed":
-      return s.latestReceipt?.state === "proposed";
-    case "receipt.cosigned":
-      return s.latestReceipt?.state === "cosigned";
+      return s.latestReceipt != null;
     case "relationship.pending":
-      return s.relationshipState === "pending";
+      return s.relationshipState === import_sdk6.RelationshipStates.PENDING;
     case "relationship.active":
-      return s.relationshipState === "active";
+      return s.relationshipState === import_sdk6.RelationshipStates.ACTIVE;
     case "relationship.paused":
-      return s.relationshipState === "paused";
+      return s.relationshipState === import_sdk6.RelationshipStates.PAUSED;
     case "relationship.closed":
-      return s.relationshipState === "closed";
+      return s.relationshipState === import_sdk6.RelationshipStates.CLOSED;
     case "cycle.complete":
       return s.cycleComplete;
     case "cycle.released":
-      return s.latestDelegation?.state === "completed";
+      return s.latestDelegation?.state === import_sdk6.DelegationStates.COMPLETED;
   }
 }
 function parseWaitInterval(raw) {
@@ -2013,7 +2031,7 @@ async function composeStatus(api, signerDid, relationshipId, signer) {
   const relationship = relationships.find((r) => r.relationshipId === relationshipId);
   const counterpartyDid = relationship ? relationship.pairDidA === signerDid ? relationship.pairDidB : relationship.pairDidA : inferCounterpartyFromEntities(signerDid, allDelegations);
   const delegations = allDelegations;
-  const latestDelegation = pickLatestLive(delegations, ["proposed", "offered", "accepted", "pending_lock_finalization", "locked"]);
+  const latestDelegation = pickLatestLive(delegations, [...import_sdk6.DELEGATION_ACTIVE_STATES]);
   const [workLogs, receipts] = await Promise.all([
     latestDelegation ? fetchAllPages(
       (after) => api.listWorkLogs(relationshipId, signer, { limit: 100, delegationId: latestDelegation.delegationId, ...after ? { after } : {} })
@@ -2077,8 +2095,8 @@ function findReceiptForWorkLog(receipts, workLog, allWorkLogs = [workLog]) {
   };
   const responseBody = workLog.responseOutput !== void 0 ? { type: "work_response", content: { delegation_id: workLog.delegationId, request_id: workLog.requestId, output: workLog.responseOutput } } : workLog.responseError !== void 0 ? { type: "work_response", content: { delegation_id: workLog.delegationId, request_id: workLog.requestId, error: workLog.responseError } } : null;
   if (!responseBody) return null;
-  const expectedRequestHash = (0, import_sdk4.canonicalSha256Hex)(requestBody);
-  const expectedResponseHash = (0, import_sdk4.canonicalSha256Hex)(responseBody);
+  const expectedRequestHash = (0, import_sdk6.canonicalSha256Hex)(requestBody);
+  const expectedResponseHash = (0, import_sdk6.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;
@@ -2120,49 +2138,49 @@ function nextAction(input) {
       complete: false
     };
   }
-  if (relationship.state === "pending") {
+  if (relationship.state === import_sdk6.RelationshipStates.PENDING) {
     return {
       hint: "Relationship is PENDING \u2014 one side owes `heyarp send-handshake-response <peer> --decision accept | decline`",
       owner: "either",
       complete: false
     };
   }
-  if (relationship.state === "paused") {
+  if (relationship.state === import_sdk6.RelationshipStates.PAUSED) {
     return { hint: "Relationship is PAUSED \u2014 owner must `heyarp unpause` before any envelopes flow", owner: "either", complete: false };
   }
-  if (relationship.state === "closed") {
+  if (relationship.state === import_sdk6.RelationshipStates.CLOSED) {
     return { hint: "Relationship is CLOSED \u2014 terminal state, no further action possible. Start a fresh handshake to reopen.", owner: "none", complete: false };
   }
-  if (!latestDelegation || latestDelegation.state === "declined" || latestDelegation.state === "canceled") {
+  if (!latestDelegation || latestDelegation.state === import_sdk6.DelegationStates.DECLINED || latestDelegation.state === import_sdk6.DelegationStates.CANCELED) {
     return {
       hint: "No live delegation \u2014 buyer offers (terms only, no lock) `heyarp delegation offer <peer> --delegation-id <new-uuid> --title \u2026 --scope \u2026 --amount \u2026 --currency SOL:solana-devnet --deadline \u2026`, then funds the escrow lock AFTER the worker accepts via `heyarp delegation fund <del-id> --escrow-lock-from-file <path>`",
       owner: "either",
       complete: false
     };
   }
-  if (latestDelegation.state === "disputing") {
+  if (latestDelegation.state === import_sdk6.DelegationStates.DISPUTING) {
     return {
       hint: `Delegation ${latestDelegation.delegationId} is DISPUTING \u2014 the buyer opened an on-chain dispute (their stake is escrowed too). The operator may rule until the dispute window lapses; after that either party closes with \`heyarp escrow dispute close ${latestDelegation.delegationId}\` (escrow returns to the buyer, both stakes return). Deadline: \`heyarp escrow show ${latestDelegation.delegationId}\`. No envelopes to send meanwhile.`,
       owner: "none",
       complete: false
     };
   }
-  if (latestDelegation.state === "completed") {
+  if (latestDelegation.state === import_sdk6.DelegationStates.COMPLETED) {
     return {
       hint: "Cycle COMPLETE \u2014 payment claimed on chain (lock paid; the receipt carries releaseStatus=paid)",
       owner: "none",
       complete: true
     };
   }
-  if (latestDelegation.state === "failed" || latestDelegation.state === "refunded" || latestDelegation.state === "dispute_resolved") {
+  if (latestDelegation.state === import_sdk6.DelegationStates.FAILED || latestDelegation.state === import_sdk6.DelegationStates.REFUNDED || latestDelegation.state === import_sdk6.DelegationStates.DISPUTE_RESOLVED) {
     const stateLabel = latestDelegation.state.toUpperCase();
-    const reason = latestDelegation.state === "failed" ? "on-chain escrow lock failed to finalise (typical causes: insufficient payer funds, wrong program-id, ProgramState PDA uninitialised \u2014 check `heyarp delegations <rel-id> --json | jq .[].escrowError` for the worker-side reason)" : latestDelegation.state === "refunded" ? (
+    const reason = latestDelegation.state === import_sdk6.DelegationStates.FAILED ? "on-chain escrow lock failed to finalise (typical causes: insufficient payer funds, wrong program-id, ProgramState PDA uninitialised \u2014 check `heyarp delegations <rel-id> --json | jq .[].escrowError` for the worker-side reason)" : latestDelegation.state === import_sdk6.DelegationStates.REFUNDED ? (
       // Keyed on the DELEGATION row's releaseStatus, not the
       // receipt's: in the claim-expired path the worker never
       // submitted anything, so no receipt row exists to carry
       // the outcome — the delegation copy is always present
       // on indexer-driven terminals.
-      latestDelegation.releaseStatus === "dispute_closed" ? "the dispute window lapsed without an operator ruling and the dispute was closed \u2014 escrow returned to the buyer, both stakes returned (work was delivered but not paid)" : latestDelegation.releaseStatus === "revoked" ? "the work window lapsed without an on-chain submit \u2014 the buyer reclaimed the escrow AND the worker stake (claim_expired_work)" : "lock was refunded after expiry \u2014 no work was delivered against this delegation"
+      latestDelegation.releaseStatus === import_sdk6.LockStates.DISPUTE_CLOSED ? "the dispute window lapsed without an operator ruling and the dispute was closed \u2014 escrow returned to the buyer, both stakes returned (work was delivered but not paid)" : latestDelegation.releaseStatus === import_sdk6.LockStates.REVOKED ? "the work window lapsed without an on-chain submit \u2014 the buyer reclaimed the escrow AND the worker stake (claim_expired_work)" : "lock was refunded after expiry \u2014 no work was delivered against this delegation"
     ) : "admin closed the delegation via the dispute-resolution path";
     return {
       hint: `Delegation ${latestDelegation.delegationId} is ${stateLabel} (terminal) \u2014 ${reason}. Issue a fresh \`heyarp delegation offer <peer> --delegation-id <new-uuid> \u2026\` to retry (FSM does not auto-retry).`,
@@ -2170,16 +2188,16 @@ function nextAction(input) {
       complete: false
     };
   }
-  if (latestDelegation.state === "proposed" || latestDelegation.state === "offered") {
+  if (latestDelegation.state === import_sdk6.DelegationStates.OFFERED) {
     const iAmOfferer = latestDelegation.offererDid === signerDid;
-    const stateLabel = latestDelegation.state === "proposed" ? "PROPOSED" : `${latestDelegation.state.toUpperCase()} (\u2261 proposed)`;
+    const stateLabel = "OFFERED";
     return {
       hint: iAmOfferer ? `Delegation ${latestDelegation.delegationId} is ${stateLabel} \u2014 counterparty owes \`heyarp delegation accept\` / \`decline\`` : `Delegation ${latestDelegation.delegationId} is ${stateLabel} \u2014 you owe \`heyarp delegation accept\` / \`decline\``,
       owner: iAmOfferer ? "counterparty" : "me",
       complete: false
     };
   }
-  if (latestDelegation.state === "accepted" && !latestWorkLog) {
+  if (latestDelegation.state === import_sdk6.DelegationStates.ACCEPTED && !latestWorkLog) {
     const iAmOfferer = latestDelegation.offererDid === signerDid;
     return {
       hint: iAmOfferer ? `Delegation ${latestDelegation.delegationId} is ACCEPTED \u2014 you (buyer) owe \`heyarp wallet create-lock --delegation-id ${latestDelegation.delegationId} --condition-hash <hex> ... > lock.json\` then \`heyarp delegation fund ${latestDelegation.delegationId} --escrow-lock-from-file lock.json\` (fund the escrow lock; work begins once it is LOCKED on chain)` : `Delegation ${latestDelegation.delegationId} is ACCEPTED \u2014 counterparty (the buyer) owes \`heyarp delegation fund\` to lock the escrow; wait for the delegation to reach LOCKED before working`,
@@ -2187,7 +2205,7 @@ function nextAction(input) {
       complete: false
     };
   }
-  if (latestDelegation.state === "pending_lock_finalization" && !latestWorkLog) {
+  if (latestDelegation.state === import_sdk6.DelegationStates.PENDING_LOCK_FINALIZATION && !latestWorkLog) {
     return {
       hint: `Delegation ${latestDelegation.delegationId} is PENDING_LOCK_FINALIZATION \u2014 the escrow lock was funded and is awaiting on-chain confirmation; both sides wait (auto-advances to LOCKED). Poll with \`heyarp status ${relationship.relationshipId} --wait --until delegation.locked\`.`,
       owner: "none",
@@ -2202,7 +2220,7 @@ function nextAction(input) {
       complete: false
     };
   }
-  if (latestWorkLog.state === "requested") {
+  if (latestWorkLog.state === import_sdk6.WorkLogStates.REQUESTED) {
     const iAmPayee = latestWorkLog.payeeDid === signerDid;
     return {
       hint: iAmPayee ? `work_request ${latestWorkLog.requestId} is REQUESTED \u2014 you owe \`heyarp work respond\` (output OR --error)` : `work_request ${latestWorkLog.requestId} is REQUESTED \u2014 counterparty (payee) owes \`heyarp work respond\``,
@@ -2233,24 +2251,21 @@ function nextAction(input) {
       complete: false
     };
   }
-  if (latestReceipt.state === "proposed") {
-    const iAmCaller = latestReceipt.callerDid === signerDid;
-    return {
-      // V2: there is NO cosign — buyer consent is the on-chain
-      // claim_work_payment tx, worker recourse is the
-      // review-window self-claim.
-      hint: iAmCaller ? `Receipt PROPOSED \u2014 you (caller): review the deliverable and approve payment ON-CHAIN with \`heyarp escrow claim ${latestReceipt.delegationId}\` (irreversible release; \`heyarp escrow dispute open ${latestReceipt.delegationId}\` within the review window if the work is unacceptable)` : `Receipt PROPOSED \u2014 counterparty (the buyer) owes the on-chain approval (\`heyarp escrow claim\`); once the review window lapses you may self-claim with \`heyarp escrow claim ${latestReceipt.delegationId}\``,
-      owner: iAmCaller ? "me" : "counterparty",
-      complete: false
-    };
-  }
-  return { hint: "Cycle COMPLETE \u2014 settlement recorded", owner: "none", complete: true };
+  const iAmCaller = latestReceipt.callerDid === signerDid;
+  return {
+    // There is no cosign step — buyer consent is the on-chain
+    // claim_work_payment tx, worker recourse is the
+    // review-window self-claim.
+    hint: iAmCaller ? `Receipt PROPOSED \u2014 you (caller): review the deliverable and approve payment ON-CHAIN with \`heyarp escrow claim ${latestReceipt.delegationId}\` (irreversible release; \`heyarp escrow dispute open ${latestReceipt.delegationId}\` within the review window if the work is unacceptable)` : `Receipt PROPOSED \u2014 counterparty (the buyer) owes the on-chain approval (\`heyarp escrow claim\`); once the review window lapses you may self-claim with \`heyarp escrow claim ${latestReceipt.delegationId}\``,
+    owner: iAmCaller ? "me" : "counterparty",
+    complete: false
+  };
 }
 function formatPhaseSnapshot(s) {
   const parts = [];
   parts.push(`delegation=${s.latestDelegation?.state ?? "\u2205"}`);
   if (s.latestWorkLog) parts.push(`work=${s.latestWorkLog.state}`);
-  if (s.latestReceipt) parts.push(`receipt=${s.latestReceipt.state}`);
+  if (s.latestReceipt) parts.push("receipt=proposed");
   return parts.join(", ");
 }
 function formatStatusReport(s) {
@@ -2280,7 +2295,7 @@ function formatStatusReport(s) {
   lines.push("");
   lines.push(import_chalk7.default.bold("Latest receipt"));
   if (s.latestReceipt) {
-    lines.push(`  state=${stateColor(s.latestReceipt.state)}  verdict=${s.latestReceipt.verdictFinal ?? s.latestReceipt.verdictProposed}`);
+    lines.push(`  ${stateColor("proposed")}  verdict=${s.latestReceipt.verdictProposed}`);
   } else {
     lines.push(import_chalk7.default.dim("  (none)"));
   }
@@ -2294,26 +2309,26 @@ function formatStatusReport(s) {
 }
 function cycleHeadline(s) {
   if (s.cycleComplete) {
-    return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.green.bold("COMPLETE")} ${import_chalk7.default.dim("\u2014 receipt cosigned, payment proven on chain")}`;
+    return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.green.bold("COMPLETE")} ${import_chalk7.default.dim("\u2014 payment proven on chain")}`;
   }
   switch (s.relationshipState) {
     case "not_found":
       return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.red.bold("NOT FOUND")} ${import_chalk7.default.dim("\u2014 relationship missing or signer is not a member")}`;
     case "unknown":
       return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.yellow.bold("UNKNOWN")} ${import_chalk7.default.dim("\u2014 state probe inconclusive; hint below is advisory")}`;
-    case "closed":
+    case import_sdk6.RelationshipStates.CLOSED:
       return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.red.bold("CLOSED")} ${import_chalk7.default.dim("\u2014 relationship terminal, no further protocol action")}`;
-    case "paused":
+    case import_sdk6.RelationshipStates.PAUSED:
       return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.yellow.bold("PAUSED")} ${import_chalk7.default.dim("\u2014 relationship soft-disabled, resume to continue")}`;
-    case "pending":
+    case import_sdk6.RelationshipStates.PENDING:
       return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.yellow.bold("PENDING")} ${import_chalk7.default.dim("\u2014 awaiting handshake_response")}`;
-    case "active":
+    case import_sdk6.RelationshipStates.ACTIVE:
     default:
       return `${import_chalk7.default.bold("Cycle:")} ${import_chalk7.default.cyan.bold("ACTIVE")} ${import_chalk7.default.dim('\u2014 work in progress; see "Next action" below')}`;
   }
 }
 function stateColor(state) {
-  const c = state === "active" || state === "accepted" || state === "locked" || state === "cosigned" || state === "responded" || state === "completed" ? import_chalk7.default.green : state === "pending" || state === "proposed" || state === "requested" || state === "offered" || state === "pending_lock_finalization" ? import_chalk7.default.yellow : state === "closed" || state === "declined" || state === "canceled" || state === "replaced" || state === "not_found" || // Terminal failure states deserve the same red
+  const c = state === "active" || state === "accepted" || state === "locked" || state === "responded" || state === "completed" ? import_chalk7.default.green : state === "pending" || state === "requested" || state === "offered" || state === "pending_lock_finalization" ? import_chalk7.default.yellow : state === "closed" || state === "declined" || state === "canceled" || state === "replaced" || state === "not_found" || // Terminal failure states deserve the same red
   // treatment as declined/canceled so an operator
   // scanning `heyarp status` immediately sees
   // "this is dead, don't follow the hint blindly".
@@ -2322,41 +2337,41 @@ function stateColor(state) {
 }
 
 // src/commands/wallet.ts
-var import_sdk6 = require("@heyanon-arp/sdk");
+var import_sdk9 = require("@heyanon-arp/sdk");
 var import_utils = require("@noble/hashes/utils");
 var import_web32 = require("@solana/web3.js");
 init_api();
 init_config();
 
 // src/solana/escrow-ix.ts
-var import_sdk5 = require("@heyanon-arp/sdk");
+var import_sdk7 = require("@heyanon-arp/sdk");
 var import_web3 = require("@solana/web3.js");
-var SPL_TOKEN_PROGRAM_ID = new import_web3.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
-var ASSOCIATED_TOKEN_PROGRAM_ID = new import_web3.PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
-var NATIVE_SOL_MINT = new import_web3.PublicKey(new Uint8Array(32));
+var SPL_TOKEN_PROGRAM_ID = new import_web3.PublicKey(import_sdk7.SPL_TOKEN_PROGRAM_ID_BASE58);
+var ASSOCIATED_TOKEN_PROGRAM_ID = new import_web3.PublicKey(import_sdk7.ASSOCIATED_TOKEN_PROGRAM_ID_BASE58);
+var NATIVE_SOL_MINT = new import_web3.PublicKey(import_sdk7.NATIVE_SOL_MINT_BASE58);
 function deriveLockPda(programId, lockId) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.LOCK), Buffer.from(lockId)], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.LOCK), Buffer.from(lockId)], programId)[0];
 }
 function deriveEscrowPda(programId, lockId) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.ESCROW), Buffer.from(lockId)], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.ESCROW), Buffer.from(lockId)], programId)[0];
 }
 function deriveConfigPda(programId) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.CONFIG)], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.CONFIG)], programId)[0];
 }
 function deriveStakeVaultPda(programId) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.STAKE_VAULT)], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.STAKE_VAULT)], programId)[0];
 }
 function deriveCollateralConfigPda(programId, mint) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.COLLATERAL), mint.toBuffer()], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.COLLATERAL), mint.toBuffer()], programId)[0];
 }
 function deriveDisputeResolutionPda(programId, lockId) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.DISPUTE_RESOLUTION), Buffer.from(lockId)], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.DISPUTE_RESOLUTION), Buffer.from(lockId)], programId)[0];
 }
 function deriveOperatorAuthPda(programId, operator) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.OPERATOR_AUTH), operator.toBuffer()], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.OPERATOR_AUTH), operator.toBuffer()], programId)[0];
 }
 function deriveEventAuthorityPda(programId) {
-  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk5.ESCROW_PDA_SEEDS.EVENT_AUTHORITY)], programId)[0];
+  return import_web3.PublicKey.findProgramAddressSync([Buffer.from(import_sdk7.ESCROW_PDA_SEEDS.EVENT_AUTHORITY)], programId)[0];
 }
 function deriveAta(owner, mint) {
   return import_web3.PublicKey.findProgramAddressSync([owner.toBuffer(), SPL_TOKEN_PROGRAM_ID.toBuffer(), mint.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID)[0];
@@ -2371,12 +2386,12 @@ function meta(pubkey, opts = {}) {
   return { pubkey, isSigner: opts.signer === true, isWritable: opts.writable === true };
 }
 function noArgIx(programId, name, keys) {
-  return new import_web3.TransactionInstruction({ programId, keys, data: Buffer.from((0, import_sdk5.buildLifecycleIxData)(name)) });
+  return new import_web3.TransactionInstruction({ programId, keys, data: Buffer.from((0, import_sdk7.buildLifecycleIxData)(name)) });
 }
 function buildCreateLockIx(input) {
   const { programId, lockId } = input;
   const native = input.mint === null;
-  const data = Buffer.from((0, import_sdk5.buildCreateLockIxData)({ lockId, amount: input.amount, conditionHash: input.conditionHash }, { native }));
+  const data = Buffer.from((0, import_sdk7.buildCreateLockIxData)({ lockId, amount: input.amount, conditionHash: input.conditionHash }, { native }));
   const head = [
     meta(input.payer, { signer: true, writable: true }),
     meta(input.payee),
@@ -2512,7 +2527,7 @@ function buildOpenDisputeIx(input) {
 function buildResolveDisputeIx(input) {
   const { programId, lockId } = input;
   const native = input.mint === null;
-  const data = Buffer.from((0, import_sdk5.buildResolveDisputeIxData)(input.args, { native }));
+  const data = Buffer.from((0, import_sdk7.buildResolveDisputeIxData)(input.args, { native }));
   if (native) {
     return new import_web3.TransactionInstruction({
       programId,
@@ -2589,16 +2604,17 @@ function buildCloseDisputeIx(input) {
   ]);
 }
 async function fetchLockAccount(conn, programId, delegationId) {
-  const lockId = (0, import_sdk5.deriveLockId)(delegationId);
+  const lockId = (0, import_sdk7.deriveLockId)(delegationId);
   const lockPda = deriveLockPda(programId, lockId);
   const info = await conn.getAccountInfo(lockPda);
   if (!info) return null;
-  return { lockId, lockPda, lock: (0, import_sdk5.decodeLockAccount)(Uint8Array.from(info.data)) };
+  return { lockId, lockPda, lock: (0, import_sdk7.decodeLockAccount)(Uint8Array.from(info.data)) };
 }
 
 // src/commands/token-amount.ts
+var import_sdk8 = require("@heyanon-arp/sdk");
 function toBaseUnits(amountDecimal, decimals) {
-  if (!/^[0-9]+(\.[0-9]+)?$/.test(amountDecimal)) {
+  if (!(0, import_sdk8.isDecimalAmountString)(amountDecimal)) {
     throw new Error(`amount '${amountDecimal}' is not a non-negative decimal number`);
   }
   if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) {
@@ -2627,8 +2643,8 @@ function normaliseDelegationId(raw) {
   }
   throw new Error(`wallet: --delegation-id must be either 'del_<uuid>' or a bare canonical-lowercase UUID (got '${raw}')`);
 }
-var SPL_TOKEN_PROGRAM_ID2 = new import_web32.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
-var ASSOCIATED_TOKEN_PROGRAM_ID2 = new import_web32.PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+var SPL_TOKEN_PROGRAM_ID2 = new import_web32.PublicKey(import_sdk9.SPL_TOKEN_PROGRAM_ID_BASE58);
+var ASSOCIATED_TOKEN_PROGRAM_ID2 = new import_web32.PublicKey(import_sdk9.ASSOCIATED_TOKEN_PROGRAM_ID_BASE58);
 var FALLBACK_RPC_URL = "https://api.mainnet-beta.solana.com";
 function resolveRpcUrl(opts) {
   if (opts.rpcUrl !== void 0 && opts.rpcUrl !== "") return opts.rpcUrl;
@@ -2639,7 +2655,16 @@ function resolveRpcUrl(opts) {
   if (fromConfig !== void 0 && fromConfig.length > 0) return fromConfig;
   return FALLBACK_RPC_URL;
 }
-var FALLBACK_PROGRAM_ID = "7trAdKybX4kMKARia9nrRPj9rBuUjDTxRzExzwFTvvXg";
+function redactRpcUrl(url) {
+  try {
+    const u = new URL(url);
+    const hasSecret = u.pathname !== "" && u.pathname !== "/" || u.search !== "" || u.username !== "" || u.password !== "";
+    return hasSecret ? `${u.protocol}//${u.host}/<redacted>` : url;
+  } catch {
+    return "<redacted>";
+  }
+}
+var FALLBACK_PROGRAM_ID = import_sdk9.ESCROW_PROGRAM_ID_BASE58;
 async function resolveProgramIdWithSource(api, opts) {
   if (opts.programId !== void 0 && opts.programId !== "") {
     return { programId: opts.programId, source: "flag" };
@@ -2699,10 +2724,7 @@ 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/config (auto-discover). NO hardcoded fallback \u2014 wrong-program PDAs are silently wrong, so resolution failure is a loud error."
-  ).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("--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) {
@@ -2726,7 +2748,7 @@ async function derivePdasHandler(opts) {
   const normalisedDelegationId = normaliseDelegationId(opts.delegationId);
   const api = new ArpApiClient(opts.server);
   const programId = new import_web32.PublicKey(await resolveProgramIdStrict(api, opts, "wallet derive-pdas"));
-  const lockIdBytes = (0, import_sdk6.deriveLockId)(normalisedDelegationId);
+  const lockIdBytes = (0, import_sdk9.deriveLockId)(normalisedDelegationId);
   const lockIdSeed = Buffer.from(lockIdBytes);
   const lockIdHex = Buffer.from(lockIdBytes).toString("hex");
   const [lockPda] = import_web32.PublicKey.findProgramAddressSync([Buffer.from("lock"), lockIdSeed], programId);
@@ -2738,30 +2760,29 @@ async function derivePdasHandler(opts) {
     lock_id_hex: lockIdHex,
     program_id: programId.toBase58(),
     lock_pda: lockPda.toBase58(),
-    // Single escrow PDA replaces the V1.5 vault + vault_authority
-    // pair in the new contract.
+    // Single escrow PDA at `[b"escrow", lock_id]`.
     escrow_pda: escrowPda.toBase58(),
     config_pda: configPda.toBase58(),
     event_authority_pda: eventAuthorityPda.toBase58()
   };
 }
 var TERMINAL_METHOD = {
-  paid: "claim_work_payment",
-  canceled: "cancel_lock",
-  revoked: "claim_expired_work",
-  dispute_resolved: "resolve_dispute",
-  dispute_closed: "close_dispute"
+  [import_sdk9.LockStates.PAID]: "claim_work_payment",
+  [import_sdk9.LockStates.CANCELED]: "cancel_lock",
+  [import_sdk9.LockStates.REVOKED]: "claim_expired_work",
+  [import_sdk9.LockStates.DISPUTE_RESOLVED]: "resolve_dispute",
+  [import_sdk9.LockStates.DISPUTE_CLOSED]: "close_dispute"
 };
 function registerVerifyRelease(cmd) {
   cmd.command("verify-release").description(
-    "Post-cycle on-chain assertion. Decodes the Lock account and reports the V2 state verdict: `released: true` IFF the lock is `paid` (the payee was paid via claim_work_payment); exits non-zero otherwise so `set -euo pipefail` scripts catch incomplete cycles. For the full decoded Lock use `heyarp escrow show`."
+    "Post-cycle on-chain assertion. Decodes the Lock account and reports the state verdict: `released: true` IFF the lock is `paid` (the payee was paid via claim_work_payment); exits non-zero otherwise so `set -euo pipefail` scripts catch incomplete cycles. For the full decoded Lock use `heyarp escrow show`."
   ).requiredOption("--delegation-id <id>", "Delegation UUID (canonical `del_<uuid>` or bare `<uuid>` \u2014 both accepted)").option("--server <url>", "Override ARP server URL (used only for --program-id auto-discovery)").option(
     "--rpc-url <url>",
     "Solana RPC URL. STRICT: --rpc-url flag > ARP_ESCROW_RPC_URL env > `heyarp config set rpcUrl` > FAIL \u2014 a wrong-cluster read would silently report lock_never_created."
   ).option(
     "--program-id <pubkey>",
     "Deployed ARP escrow program id. STRICT: flag > ARP_ESCROW_PROGRAM_ID env > GET /v1/escrow/config > FAIL \u2014 a wrong-program read would silently report lock_never_created."
-  ).option("--no-sig-retry", "V1 leftover, tolerated no-op \u2014 V2 locks are never closed, so there is no signature-index race to retry around.").option("--json", "Emit JSON instead of human text. jq-pipeable.", false).action(async (opts) => {
+  ).option("--from-did <did>", "Accepted for scripting symmetry with the signing commands; verify-release reads on-chain state only and needs no signer, so this is ignored.").option("--json", "Emit JSON instead of human text. jq-pipeable.", false).action(async (opts) => {
     try {
       const out = await verifyReleaseHandler(opts);
       if (opts.json) {
@@ -2790,16 +2811,13 @@ function registerVerifyRelease(cmd) {
   });
 }
 async function verifyReleaseHandler(opts) {
-  if (opts.noSigRetry) {
-    process.stderr.write("wallet verify-release: --no-sig-retry is a no-op on V2 (locks are never closed) \u2014 ignoring\n");
-  }
   const normalisedDelegationId = normaliseDelegationId(opts.delegationId);
   const api = new ArpApiClient(opts.server);
   const programId = new import_web32.PublicKey(await resolveProgramIdStrict(api, opts));
   const rpcUrl = resolveRpcUrlStrict(opts);
   const conn = new import_web32.Connection(rpcUrl, "confirmed");
   const fetched = await fetchLockAccount(conn, programId, normalisedDelegationId);
-  const lockId = (0, import_sdk6.deriveLockId)(normalisedDelegationId);
+  const lockId = (0, import_sdk9.deriveLockId)(normalisedDelegationId);
   const lockPda = deriveLockPda(programId, lockId);
   const escrowPda = deriveEscrowPda(programId, lockId);
   if (!fetched) {
@@ -2810,7 +2828,7 @@ async function verifyReleaseHandler(opts) {
       lock_account_exists: false,
       released: false,
       status: "lock_never_created",
-      rpc_url: rpcUrl
+      rpc_url: redactRpcUrl(rpcUrl)
     };
   }
   const lock = fetched.lock;
@@ -2820,7 +2838,7 @@ async function verifyReleaseHandler(opts) {
     lock_pda: lockPda.toBase58(),
     escrow_pda: escrowPda.toBase58(),
     lock_account_exists: true,
-    released: status === "paid",
+    released: status === import_sdk9.LockStates.PAID,
     status,
     ...TERMINAL_METHOD[status] !== void 0 ? { release_method: TERMINAL_METHOD[status] } : {},
     lock_state: lock.stateByte,
@@ -2830,23 +2848,23 @@ async function verifyReleaseHandler(opts) {
 }
 function renderStatusLine(status) {
   switch (status) {
-    case "paid":
+    case import_sdk9.LockStates.PAID:
       return "\u2713 paid \u2014 claim_work_payment landed (buyer approval or post-review self-claim); the payee was paid net of any protocol fee";
-    case "created":
+    case import_sdk9.LockStates.CREATED:
       return "\u2717 created \u2014 funded, awaiting the worker accept_lock (stake) \u2014 or a buyer cancel";
-    case "in_progress":
+    case import_sdk9.LockStates.IN_PROGRESS:
       return "\u2717 in_progress \u2014 worker accepted + staked; work window running";
-    case "submitted":
+    case import_sdk9.LockStates.SUBMITTED:
       return "\u2717 submitted \u2014 work delivered on-chain; review window running (buyer claims to approve, disputes to refuse; worker self-claims after expiry)";
-    case "disputing":
+    case import_sdk9.LockStates.DISPUTING:
       return "\u2717 disputing \u2014 buyer disputed; operator has the dispute window to rule, after that either party can close";
-    case "canceled":
+    case import_sdk9.LockStates.CANCELED:
       return "\u2717 canceled \u2014 buyer canceled pre-accept; escrow returned";
-    case "revoked":
+    case import_sdk9.LockStates.REVOKED:
       return "\u2717 revoked \u2014 work window lapsed unsubmitted; buyer reclaimed the escrow + the worker stake";
-    case "dispute_resolved":
+    case import_sdk9.LockStates.DISPUTE_RESOLVED:
       return "\u2717 dispute_resolved \u2014 operator ruled; winner took the escrow per the on-chain split";
-    case "dispute_closed":
+    case import_sdk9.LockStates.DISPUTE_CLOSED:
       return "\u2717 dispute_closed \u2014 dispute window lapsed unresolved; escrow returned to the buyer, stakes returned";
     case "lock_never_created":
       return "\u2717 lock_never_created \u2014 no Lock PDA on this cluster/program; create_lock never fired (or wrong --rpc-url/--program-id)";
@@ -2854,14 +2872,11 @@ function renderStatusLine(status) {
 }
 function registerCreateLock(cmd) {
   cmd.command("create-lock").description(
-    "Build + sign a create_lock Solana tx (native SOL or an SPL token); output JSON ready for attachments.escrow_lock. This command does NOT submit the tx to chain \u2014 it only signs the blob locally. M6 lock-at-accept: run this AFTER the worker accepts your offer; the actual on-chain submission happens inside `heyarp delegation fund <delegation-id> --escrow-lock-from-file <path>` (the server's escrow worker picks up the signed blob from the fund envelope's attachments and posts it). Watch for the `lock_id` appearing on-chain only AFTER `delegation fund` runs, not after this command."
+    "Build + sign a create_lock Solana tx (native SOL or an SPL token); output JSON ready for attachments.escrow_lock. This command does NOT submit the tx to chain \u2014 it only signs the blob locally. Run this AFTER the worker accepts your offer; the actual on-chain submission happens inside `heyarp delegation fund <delegation-id> --escrow-lock-from-file <path>` (the server's escrow worker picks up the signed blob from the fund envelope's attachments and posts it). Watch for the `lock_id` appearing on-chain only AFTER `delegation fund` runs, not after this command."
   ).option("--server <url>", "Override server URL for sender-key resolution").option("--from-did <did>", "Sender DID (= payer of the lock). Required when more than one agent on the host.").requiredOption("--delegation-id <id>", "Delegation UUID (drives the lock_id derivation)").requiredOption("--recipient-pubkey <base58>", "Payee Solana pubkey (recipient agent's settlement_pubkey)").option("--amount-lamports <int>", "NATIVE SOL: lock amount in lamports (1 SOL = 1_000_000_000). Required when --mint-pubkey is omitted; not allowed with it.").option("--mint-pubkey <base58>", "SPL token mint to lock. Omit for native SOL. Must be a legacy SPL Token mint (Token-2022 is not supported).").option("--amount-base-units <int>", "SPL: lock amount in the mint's base units (e.g. 1000000 = 1 USDC at 6 decimals). Canonical SPL amount input.").option(
     "--amount <decimal>",
     "SPL: lock amount as a human decimal (e.g. 1.5); converted using the mint's on-chain decimals. Convenience alternative to --amount-base-units."
   ).requiredOption("--condition-hash <hex>", "32-byte hex condition_hash from `heyarp escrow derive-condition-hash` (binds the delegation terms)").option(
-    "--expiry-secs <int>",
-    "DEPRECATED no-op \u2014 V2 derives deadlines from the on-chain Config windows; the flag is tolerated so old scripts keep running and dies with the V2 builder rewrite."
-  ).option(
     "--rpc-url <url>",
     `Solana RPC URL. Default precedence: --rpc-url flag > ARP_ESCROW_RPC_URL env > \`heyarp config set rpcUrl\` > built-in fallback (${FALLBACK_RPC_URL}).`
   ).option(
@@ -3029,16 +3044,13 @@ async function createLockHandler(opts) {
   const normalisedDelegationId = normaliseDelegationId(opts.delegationId);
   const payee = parsePubkey(opts.recipientPubkey, "--recipient-pubkey");
   const conditionHash = parseHex32(opts.conditionHash, "--condition-hash");
-  if (opts.expirySecs !== void 0) {
-    process.stderr.write("wallet create-lock: --expiry-secs is a no-op on V2 (deadlines come from the on-chain Config windows) \u2014 ignoring\n");
-  }
   const api = new ArpApiClient(opts.server);
   const offlineMode = typeof opts.programId === "string" && opts.programId !== "" || typeof process.env.ARP_ESCROW_PROGRAM_ID === "string" && process.env.ARP_ESCROW_PROGRAM_ID !== "";
   const clusterTag = opts.clusterTag !== void 0 ? Number.parseInt(opts.clusterTag, 10) : 0;
   if (clusterTag !== 0 && clusterTag !== 1) {
     throw new Error(`--cluster-tag must be 0 (devnet) or 1 (mainnet) (got ${clusterTag})`);
   }
-  const clusterCaip2 = clusterTag === 1 ? import_sdk6.SOLANA_CLUSTER_IDS["solana-mainnet"] : import_sdk6.SOLANA_CLUSTER_IDS["solana-devnet"];
+  const clusterCaip2 = clusterTag === 1 ? import_sdk9.SOLANA_CLUSTER_IDS["solana-mainnet"] : import_sdk9.SOLANA_CLUSTER_IDS["solana-devnet"];
   const expectedLockAsset = typeof opts.mintPubkey === "string" && opts.mintPubkey !== "" ? { kind: "spl", mint: parsePubkey(opts.mintPubkey, "--mint-pubkey").toBase58(), cluster: clusterCaip2 } : { kind: "native" };
   if (!offlineMode) {
     await preflightLockCurrency(api, agent, normalisedDelegationId, expectedLockAsset);
@@ -3048,7 +3060,7 @@ async function createLockHandler(opts) {
   const conn = new import_web32.Connection(rpcUrl, "confirmed");
   const asset = await resolveCreateLockAsset(conn, opts, payerKp.publicKey, clusterCaip2);
   const amount = asset.amount;
-  const lockIdBytes = (0, import_sdk6.deriveLockId)(normalisedDelegationId);
+  const lockIdBytes = (0, import_sdk9.deriveLockId)(normalisedDelegationId);
   const ix = buildCreateLockIx({
     programId,
     lockId: lockIdBytes,
@@ -3132,63 +3144,12 @@ function registerDelegationCommands(root) {
   registerDecline(cmd);
   registerCancel(cmd);
 }
-var POST_COMMIT_ERROR_CODES = /* @__PURE__ */ new Set([
-  "DELEGATION_ALREADY_EXISTS",
-  "DELEGATION_INVALID_STATE",
-  "DELEGATION_NOT_FOUND",
-  "DELEGATION_RELATIONSHIP_MISMATCH",
-  "DELEGATION_ACCEPTER_IS_OFFERER",
-  "DELEGATION_DECLINER_IS_OFFERER",
-  "DELEGATION_CANCELER_NOT_OFFERER",
-  // PricingPolicy: the offer's terms fell outside the RECIPIENT's
-  // published accept-prefs. Fires in `handleOffer` AFTER the event
-  // row commit (pre-materialization on the server), so the sequence
-  // was consumed — advance it or the corrected re-offer trips
-  // ENV_SEQUENCE_BACKWARDS.
-  // Asset whitelist gate: the offer currency is not a whitelisted
-  // payment asset on this server (or its decimals diverge from the
-  // canonical entry). Same lifecycle as the pricing gate — sequence
-  // consumed. Fix the --currency and re-offer.
-  "DELEGATION_ASSET_NOT_ALLOWED",
-  "DELEGATION_PRICING_MISMATCH",
-  // Capacity gate: the recipient is at its published
-  // maxActiveDelegations cap (or closed with 0). Same lifecycle as
-  // the pricing gate — sequence consumed. TRANSIENT: retry later.
-  "DELEGATION_CAPACITY_EXCEEDED",
-  // `DELEGATION_PENDING_LOCK` fires from the body handler's
-  // `requireDelegationInState` AFTER the event row is persisted
-  // (same code path as DELEGATION_INVALID_STATE), so an accept
-  // against a PENDING_LOCK delegation consumes sender_sequence
-  // even though it rejects.
-  "DELEGATION_PENDING_LOCK",
-  // M6 lock-at-accept: the `fund` body handler (`handleFund`) emits
-  // these AFTER the event row is committed (same lifecycle as
-  // DELEGATION_INVALID_STATE). `DELEGATION_FUNDER_NOT_OFFERER` (403)
-  // when a non-offerer attempts the fund; `DELEGATION_ALREADY_FUNDED`
-  // (409) on a re-fund of a delegation that already moved into the
-  // lock lifecycle (pending_lock_finalization / locked, or an
-  // in-flight create_lock op). Both consume sender_sequence, so the
-  // CLI must advance `lastSenderSequence` or a retry trips
-  // `ENV_SEQUENCE_BACKWARDS`.
-  "DELEGATION_FUNDER_NOT_OFFERER",
-  "DELEGATION_ALREADY_FUNDED",
-  // V1.5 lock-validator mint.owner pre-flight — kept here for
-  // documentation, but the `isPostCommitErrorCode` helper below
-  // also matches any `ESC_LOCK_*` prefix. The full lock-validator
-  // cross-check set (ID_MISMATCH, CONDITION_HASH_MISMATCH,
-  // AMOUNT_DELEGATION_MISMATCH, EXPIRY_TOO_*, PDA_*, etc.) ALSO
-  // fires after the delegation event is committed; missing
-  // entries here would leave `lastSenderSequence` stale and stall
-  // retries on ENV_SEQUENCE_BACKWARDS.
-  "ESC_LOCK_MINT_RPC_FAILED",
-  "ESC_LOCK_MINT_NOT_FOUND",
-  "ESC_LOCK_MINT_OWNER_MISMATCH"
-]);
-function isPostCommitErrorCode(code) {
-  return POST_COMMIT_ERROR_CODES.has(code) || code.startsWith("ESC_LOCK_") || code.startsWith("SDK_");
-}
 function registerOffer(parent) {
-  parent.command("offer").description("Open a new delegation addressed to <recipient-did> with the agreed terms INLINE (no escrow lock \u2014 fund AFTER acceptance via `delegation fund`).").argument("<recipient-did>", "Recipient agent DID (did:arp:...)").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--delegation-id <uuid>", "Override the auto-generated delegation id (UUID). Reuse the SAME id at `heyarp delegation fund` time. 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("--scope <text>", "scope_summary \u2014 short prose describing the agreed work. Required.").option("--amount <s>", 'Optional decimal-as-string amount (e.g. "10.00"). REQUIRES --currency if set.').option("--currency <s>", `Asset identifier: shorthand (${import_sdk7.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(
+  parent.command("offer").description("Open a new delegation addressed to <recipient-did> with the agreed terms INLINE (no escrow lock \u2014 fund AFTER acceptance via `delegation fund`).").argument("<recipient-did>", "Recipient agent DID (did:arp:...)").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--delegation-id <uuid>", "Override the auto-generated delegation id (UUID). Reuse the SAME id at `heyarp delegation fund` time. 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("--scope <text>", "scope_summary \u2014 short prose describing the agreed work. Required.").option("--amount <s>", 'Optional decimal-as-string amount (e.g. "10.00"). REQUIRES --currency if set.').option("--currency <s>", `Asset identifier: shorthand (${import_sdk10.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 ${import_sdk10.MAX_ENVELOPE_TTL_SECONDS} = 24h)`, "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"offer", delegationId, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude + the "reference this delegation" hints move to stderr; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
+    false
+  ).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(
@@ -3294,6 +3255,11 @@ function assembleEscrowLockAttachment(opts) {
   };
 }
 async function runOffer(recipientDid, opts) {
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      "delegation offer: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds dumps that would break `--json | jq`."
+    );
+  }
   requireDid("delegation offer", recipientDid, "<recipient-did>");
   const ttlSeconds = parseTtl("delegation offer", opts.ttl);
   if (!opts.title || opts.title.length === 0) {
@@ -3301,7 +3267,7 @@ async function runOffer(recipientDid, opts) {
   }
   const terms = parseOfferTerms("delegation offer", opts);
   const offeredAssetId = terms.currency?.asset_id;
-  if (offeredAssetId && !(0, import_sdk7.isWhitelistedAssetId)(offeredAssetId)) {
+  if (offeredAssetId && !(0, import_sdk10.isWhitelistedAssetId)(offeredAssetId)) {
     console.error(
       import_chalk8.default.yellow(
         `warning: currency '${offeredAssetId}' is not in the static payment whitelist \u2014 the server will reject the offer (DELEGATION_ASSET_NOT_ALLOWED) unless its deploy registers this asset. See 'heyarp assets'.`
@@ -3322,21 +3288,21 @@ async function runOffer(recipientDid, opts) {
   const api = new ArpApiClient(opts.server);
   const sender = resolveSenderAgent("delegation offer", opts.server, opts.fromDid);
   const content = {
-    action: "offer",
+    action: import_sdk10.DelegationActions.OFFER,
     delegation_id: delegationId,
     title: opts.title,
     ...terms
   };
   const body = { type: "delegation", content };
-  console.log(import_chalk8.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk8.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk8.default.dim(`Recipient: ${recipientDid}`));
-  console.log(import_chalk8.default.dim(`Delegation: ${delegationId}`));
+  progress(opts.json, import_chalk8.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk8.default.dim(`Sender: ${sender.did}`));
+  progress(opts.json, import_chalk8.default.dim(`Recipient: ${recipientDid}`));
+  progress(opts.json, import_chalk8.default.dim(`Delegation: ${delegationId}`));
   let result;
   try {
     result = await sendDelegationEnvelope({ api, sender, recipientDid, body, ttlSeconds, verbose: opts.verbose, server: opts.server });
   } catch (err) {
-    if (err instanceof ApiError && err.payload.code === "DELEGATION_ASSET_NOT_ALLOWED") {
+    if (err instanceof ApiError && err.payload.code === import_sdk10.DelegationOfferRejectionCodes.ASSET_NOT_ALLOWED) {
       const d = err.payload.details;
       console.error(import_chalk8.default.yellow(`
 The server's payment-asset whitelist rejected this currency.`));
@@ -3349,7 +3315,7 @@ See the whitelist (shorthand keys + canonical decimals):
   heyarp assets
 then re-offer with a whitelisted --currency.`));
     }
-    if (err instanceof ApiError && err.payload.code === "DELEGATION_PRICING_MISMATCH") {
+    if (err instanceof ApiError && err.payload.code === import_sdk10.DelegationOfferRejectionCodes.PRICING_MISMATCH) {
       const d = err.payload.details;
       console.error(import_chalk8.default.yellow(`
 The recipient's published accept-prefs rejected this offer${d?.reason ? ` (mismatch: ${d.reason})` : ""}.`));
@@ -3366,7 +3332,7 @@ then re-run with matching --currency / --amount.`
         )
       );
     }
-    if (err instanceof ApiError && err.payload.code === "DELEGATION_CAPACITY_EXCEEDED") {
+    if (err instanceof ApiError && err.payload.code === import_sdk10.DelegationOfferRejectionCodes.CAPACITY_EXCEEDED) {
       const d = err.payload.details;
       const cap = d?.maxActive === 0 ? "closed for new offers (busy)" : `at capacity (${d?.currentActive}/${d?.maxActive} active delegations)`;
       console.error(import_chalk8.default.yellow(`
@@ -3375,17 +3341,31 @@ The recipient is ${cap}.`));
     }
     throw err;
   }
-  printIngestResult(result);
-  console.log(import_chalk8.default.dim(`
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      action: "offer",
+      delegationId,
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp,
+      serverEventHash: result.serverEventHash,
+      prevServerEventHash: result.prevServerEventHash ?? null
+    });
+  } else {
+    printIngestResult(result);
+    console.log(import_chalk8.default.dim(`
 Reference this delegation on subsequent calls with:`));
-  console.log(import_chalk8.default.dim(`  heyarp delegation accept ${result.relationshipId} ${delegationId}`));
-  console.log(import_chalk8.default.dim(`  heyarp delegation decline ${result.relationshipId} ${delegationId}`));
-  console.log(import_chalk8.default.dim(`  heyarp delegation cancel  ${result.relationshipId} ${delegationId}`));
-  console.log(import_chalk8.default.dim(`
+    console.log(import_chalk8.default.dim(`  heyarp delegation accept ${result.relationshipId} ${delegationId}`));
+    console.log(import_chalk8.default.dim(`  heyarp delegation decline ${result.relationshipId} ${delegationId}`));
+    console.log(import_chalk8.default.dim(`  heyarp delegation cancel  ${result.relationshipId} ${delegationId}`));
+    console.log(import_chalk8.default.dim(`
 After the worker accepts, fund the escrow lock:`));
-  console.log(import_chalk8.default.dim(`  heyarp wallet create-lock --delegation-id ${delegationId} --condition-hash <hex> ... > lock.json`));
-  console.log(import_chalk8.default.dim(`  heyarp delegation fund ${delegationId} --escrow-lock-from-file lock.json`));
-  if (opts.waitUntil) {
+    console.log(import_chalk8.default.dim(`  heyarp wallet create-lock --delegation-id ${delegationId} --condition-hash <hex> ... > lock.json`));
+    console.log(import_chalk8.default.dim(`  heyarp delegation fund ${delegationId} --escrow-lock-from-file lock.json`));
+  }
+  if (opts.waitUntil && !opts.json) {
     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)})`);
@@ -3405,7 +3385,7 @@ After the worker accepts, fund the escrow lock:`));
   }
 }
 function registerFund(parent) {
-  parent.command("fund").description("Fund an ACCEPTED delegation with the escrow lock (buyer-only). Run AFTER the worker accepts the offer.").argument("<delegation-id>", "Delegation UUID (the one you offered + the worker accepted)").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("--ttl <seconds>", "Envelope TTL in seconds (max 86400 = 24h)", "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+  parent.command("fund").description("Fund an ACCEPTED delegation with the escrow lock (buyer-only). Run AFTER the worker accepts the offer.").argument("<delegation-id>", "Delegation UUID (the one you offered + the worker accepted)").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("--ttl <seconds>", `Envelope TTL in seconds (max ${import_sdk10.MAX_ENVELOPE_TTL_SECONDS} = 24h)`, "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
     "--json",
     'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"fund", delegationId, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude moves off stdout; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
     false
@@ -3469,7 +3449,7 @@ async function runFund(delegationId, opts) {
       );
     }
   }
-  const content = { action: "fund", delegation_id: delegationId };
+  const content = { action: import_sdk10.DelegationActions.FUND, delegation_id: delegationId };
   const body = { type: "delegation", content };
   const attachments = { escrow_lock: escrowResult.attachment };
   progress(opts.json, import_chalk8.default.dim(`Server: ${api.serverUrl}`));
@@ -3570,8 +3550,12 @@ function registerDecline(parent) {
     "--reason <code>",
     // 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_sdk7.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).option(
+    `Required: decline reason code (one of: ${import_sdk10.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. Mutually exclusive with --json.", false).option(
+    "--json",
+    'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"decline", delegationId, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude + pending-lock poll chatter move off stdout; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
+    false
+  ).option(
     "--no-wait-for-lock",
     "Opt-out of the pending-lock pre-flight poll. Default is ON: when the resolved delegation is in `pending_lock_finalization`, the CLI polls until the on-chain lock is confirmed before signing the envelope (avoids the racy DELEGATION_PENDING_LOCK 409 that consumes sender_sequence)."
   ).option("--lock-wait-timeout <seconds>", "Max wall-clock seconds to wait for pending-lock pre-flight (default 300).", "300").option("--lock-wait-interval <seconds>", "Poll cadence for pending-lock pre-flight in seconds. Bound to [1, 60].", "3").action(async (relationshipId, delegationId, opts) => {
@@ -3579,7 +3563,11 @@ function registerDecline(parent) {
   });
 }
 function registerCancel(parent) {
-  parent.command("cancel").description("Cancel an OFFERED 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("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).option(
+  parent.command("cancel").description("Cancel an OFFERED 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("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"cancel", delegationId, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude + pending-lock poll chatter move off stdout; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
+    false
+  ).option(
     "--no-wait-for-lock",
     "Opt-out of the pending-lock pre-flight poll. Default is ON: when the resolved delegation is in `pending_lock_finalization`, the CLI polls until the on-chain lock is confirmed before signing the envelope (avoids the racy DELEGATION_PENDING_LOCK 409 that consumes sender_sequence)."
   ).option("--lock-wait-timeout <seconds>", "Max wall-clock seconds to wait for pending-lock pre-flight (default 300).", "300").option("--lock-wait-interval <seconds>", "Poll cadence for pending-lock pre-flight in seconds. Bound to [1, 60].", "3").action(async (relationshipId, delegationId, opts) => {
@@ -3599,7 +3587,7 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
   const lockWaitTimeoutSec = parseLockWaitTimeout(cmdName, opts.lockWaitTimeout);
   const lockWaitIntervalSec = parseLockWaitInterval(cmdName, opts.lockWaitInterval);
   let declinePayload = null;
-  if (action === "decline") {
+  if (action === import_sdk10.DelegationActions.DECLINE) {
     const reason = parseDeclineReason(cmdName, opts.reason);
     const validatedDetail = parseReasonDetail(cmdName, opts.reasonDetail);
     declinePayload = validatedDetail ? { reason, reasonDetail: validatedDetail } : { reason };
@@ -3608,7 +3596,7 @@ 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 });
-  if (resolved.state === "pending_lock_finalization" && opts.waitForLock !== false) {
+  if (resolved.state === import_sdk10.DelegationStates.PENDING_LOCK_FINALIZATION && opts.waitForLock !== false) {
     await awaitDelegationLockFinalized(cmdName, api, signer, {
       relationshipId,
       delegationId,
@@ -3633,7 +3621,7 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
   progress(opts.json, import_chalk8.default.dim(`Server: ${api.serverUrl}`));
   progress(opts.json, import_chalk8.default.dim(`Sender: ${sender.did}`));
   progress(opts.json, import_chalk8.default.dim(`Relationship: ${relationshipId}`));
-  progress(opts.json, import_chalk8.default.dim(`Delegation: ${delegationId} (action=${action}${action === "decline" ? `, reason=${content.reason}` : ""})`));
+  progress(opts.json, import_chalk8.default.dim(`Delegation: ${delegationId} (action=${action}${action === import_sdk10.DelegationActions.DECLINE ? `, reason=${content.reason}` : ""})`));
   const result = await sendDelegationEnvelope({
     api,
     sender,
@@ -3662,9 +3650,9 @@ async function runFollowupAction(relationshipId, delegationId, action, opts) {
 async function sendDelegationEnvelope(args) {
   const nextSequence = (args.sender.lastSenderSequence ?? 0) + 1;
   const protectedBlock = {
-    protocol_version: "arp/0.1",
-    purpose: import_sdk7.Purpose.ENVELOPE,
-    message_id: (0, import_sdk7.uuidV4)(),
+    protocol_version: import_sdk10.CURRENT_PROTOCOL_VERSION,
+    purpose: import_sdk10.Purpose.ENVELOPE,
+    message_id: (0, import_sdk10.uuidV4)(),
     sender_did: args.sender.did,
     recipient_did: args.recipientDid,
     // `relationship_id: null` matches the handshake
@@ -3673,13 +3661,13 @@ async function sendDelegationEnvelope(args) {
     // existing relationship row.
     relationship_id: null,
     sender_sequence: nextSequence,
-    sender_nonce: (0, import_sdk7.senderNonce)(),
-    timestamp: (0, import_sdk7.rfc3339)(),
-    expires_at: (0, import_sdk7.expiresAt)(args.ttlSeconds),
+    sender_nonce: (0, import_sdk10.senderNonce)(),
+    timestamp: (0, import_sdk10.rfc3339)(),
+    expires_at: (0, import_sdk10.expiresAt)(args.ttlSeconds),
     delivery_id: null
   };
   const signer = makeSigner(args.sender);
-  const envelope = (0, import_sdk7.signEnvelope)({
+  const envelope = (0, import_sdk10.signEnvelope)({
     protected: protectedBlock,
     body: args.body,
     identitySecretKey: signer.identitySecretKey,
@@ -3694,7 +3682,7 @@ async function sendDelegationEnvelope(args) {
     updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
     return result;
   } catch (err) {
-    if (err instanceof ApiError && isPostCommitErrorCode(err.payload.code)) {
+    if (err instanceof ApiError && (0, import_sdk10.isPostCommitErrorCode)(err.payload.code)) {
       updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
     }
     throw err;
@@ -3716,7 +3704,7 @@ async function resolveDelegationRefs(cmdName, api, signer, args) {
     );
   }
   let recipientDid;
-  if (args.action === "cancel") {
+  if (args.action === import_sdk10.DelegationActions.CANCEL) {
     const firstEvents = await api.listEvents(args.relationshipId, signer, { since: 0, limit: 1 });
     const handshake = firstEvents[0];
     if (!handshake) {
@@ -3756,7 +3744,7 @@ async function awaitDelegationLockFinalized(cmdName, api, signer, args) {
       after = page[page.length - 1].id;
     }
   };
-  const outcome = await (0, import_sdk7.pollUntil)({
+  const outcome = await (0, import_sdk10.pollUntil)({
     fetch: fetchRow,
     // Match on either "row not found at all" OR "state moved
     // past pending_lock_finalization". The post-poll branch
@@ -3766,7 +3754,7 @@ async function awaitDelegationLockFinalized(cmdName, api, signer, args) {
     // 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",
+    predicate: (row2) => row2 === null || row2.state !== import_sdk10.DelegationStates.PENDING_LOCK_FINALIZATION,
     intervalMs: args.intervalSec * 1e3,
     timeoutMs: args.timeoutSec * 1e3,
     // Swallow ONLY transient errors. A 4xx during the poll is a
@@ -3797,7 +3785,7 @@ async function awaitDelegationLockFinalized(cmdName, api, signer, args) {
       `${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") {
+  if (row.state !== import_sdk10.DelegationStates.OFFERED) {
     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.`
     );
@@ -3857,7 +3845,7 @@ function parseOfferTerms(cmdName, opts) {
   if (opts.amount) {
     out.amount = opts.amount;
     if (!opts.currency) {
-      throw new Error(`${cmdName}: --amount requires --currency. Shorthand: ${import_sdk7.WELL_KNOWN_ASSET_KEYS.join(", ")}, or raw CAIP-19 + --currency-decimals.`);
+      throw new Error(`${cmdName}: --amount requires --currency. Shorthand: ${import_sdk10.WELL_KNOWN_ASSET_KEYS.join(", ")}, or raw CAIP-19 + --currency-decimals.`);
     }
     out.currency = buildAssetIdentifier(cmdName, DELEGATION_CURRENCY_FLAGS, opts.currency, opts.currencyDecimals, opts.currencySymbol);
   } else if (opts.currency) {
@@ -3880,7 +3868,7 @@ function resolveOfferDelegationId(rawCliId, escrow) {
     cliId = rawCliId.toLowerCase();
   }
   if (escrow === void 0) {
-    return cliId ?? (0, import_sdk7.uuidV4)();
+    return cliId ?? (0, import_sdk10.uuidV4)();
   }
   if (escrow.delegationIdFromLock !== void 0) {
     const fileId = escrow.delegationIdFromLock;
@@ -3915,10 +3903,10 @@ function collectRepeated(value, previous) {
 }
 function parseDeclineReason(cmdName, raw) {
   if (raw === void 0 || raw === "") {
-    throw new Error(`${cmdName}: --reason is required when declining (one of: ${import_sdk7.DECLINE_REASONS.join(", ")})`);
+    throw new Error(`${cmdName}: --reason is required when declining (one of: ${import_sdk10.DECLINE_REASONS.join(", ")})`);
   }
-  if (!(0, import_sdk7.isDeclineReason)(raw)) {
-    throw new Error(`${cmdName}: --reason must be one of ${import_sdk7.DECLINE_REASONS.join(", ")} (got '${raw}')`);
+  if (!(0, import_sdk10.isDeclineReason)(raw)) {
+    throw new Error(`${cmdName}: --reason must be one of ${import_sdk10.DECLINE_REASONS.join(", ")} (got '${raw}')`);
   }
   return raw;
 }
@@ -3933,10 +3921,10 @@ function parseReasonDetail(cmdName, raw) {
   return raw;
 }
 function buildAssetIdentifier(cmdName, labels, rawCurrency, rawDecimals, rawSymbol) {
-  const resolved = (0, import_sdk7.resolveAsset)(rawCurrency);
+  const resolved = (0, import_sdk10.resolveAsset)(rawCurrency);
   if (!resolved) {
     throw new Error(
-      `${cmdName}: ${labels.currencyFlag} '${rawCurrency}' is not a known shorthand or a valid CAIP-19 string. Shorthand: ${import_sdk7.WELL_KNOWN_ASSET_KEYS.join(", ")}. Or pass a raw CAIP-19 id (e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v") with ${labels.decimalsFlag}.`
+      `${cmdName}: ${labels.currencyFlag} '${rawCurrency}' is not a known shorthand or a valid CAIP-19 string. Shorthand: ${import_sdk10.WELL_KNOWN_ASSET_KEYS.join(", ")}. Or pass a raw CAIP-19 id (e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v") with ${labels.decimalsFlag}.`
     );
   }
   let decimals = resolved.decimals;
@@ -3945,20 +3933,20 @@ function buildAssetIdentifier(cmdName, labels, rawCurrency, rawDecimals, rawSymb
       throw new Error(`${cmdName}: ${labels.currencyFlag} is a raw CAIP-19 string; ${labels.decimalsFlag} (0-18) is required to convert amounts to base units.`);
     }
     const parsed = Number(rawDecimals);
-    if (!Number.isInteger(parsed) || parsed < 0 || parsed > 18) {
+    if (!Number.isInteger(parsed) || parsed < import_sdk10.ASSET_DECIMALS_MIN || parsed > import_sdk10.ASSET_DECIMALS_MAX) {
       throw new Error(`${cmdName}: ${labels.decimalsFlag} must be an integer in [0, 18] (got '${rawDecimals}').`);
     }
     decimals = parsed;
   } else if (rawDecimals !== void 0) {
     const parsed = Number(rawDecimals);
-    if (!Number.isInteger(parsed) || parsed < 0 || parsed > 18) {
+    if (!Number.isInteger(parsed) || parsed < import_sdk10.ASSET_DECIMALS_MIN || parsed > import_sdk10.ASSET_DECIMALS_MAX) {
       throw new Error(`${cmdName}: ${labels.decimalsFlag} must be an integer in [0, 18] (got '${rawDecimals}').`);
     }
     decimals = parsed;
   }
   let symbol = resolved.symbol;
   if (rawSymbol !== void 0) {
-    if (rawSymbol.length === 0 || rawSymbol.length > 16) {
+    if (rawSymbol.length < import_sdk10.ASSET_SYMBOL_MIN_LEN || rawSymbol.length > import_sdk10.ASSET_SYMBOL_MAX_LEN) {
       throw new Error(`${cmdName}: ${labels.symbolFlag} must be 1-16 chars (got length ${rawSymbol.length}).`);
     }
     symbol = rawSymbol;
@@ -3972,9 +3960,10 @@ var DELEGATION_CURRENCY_FLAGS = {
 };
 
 // src/commands/delegations.ts
+var import_sdk11 = require("@heyanon-arp/sdk");
 var import_chalk9 = __toESM(require("chalk"));
 init_api();
-var ALLOWED_STATES = /* @__PURE__ */ new Set(["offered", "accepted", "declined", "canceled"]);
+var ALLOWED_STATES = /* @__PURE__ */ new Set([import_sdk11.DelegationStates.OFFERED, import_sdk11.DelegationStates.ACCEPTED, import_sdk11.DelegationStates.DECLINED, import_sdk11.DelegationStates.CANCELED]);
 function registerDelegationsCommand(root) {
   root.command("delegations").description("List delegations for a relationship (one row per delegationId, oldest-first)").argument("<relationship-id>", "Relationship UUID").option("--server <url>", "Override ARP server base URL").option("--state <s>", "Filter by exact state (offered|accepted|declined|canceled)").option("--after <id>", "Cursor: pass the previous page's last `id` to fetch the next page").option("--limit <n>", "Max rows to return (1..100)", "20").option("--from-did <did>", "Signer DID \u2014 required only if multiple agents are registered against this server").option(
     "--verbose",
@@ -4033,7 +4022,7 @@ function formatDelegationLine(d, selfDid, opts = {}) {
   const amount = formatAmount(d);
   const title = d.title ? import_chalk9.default.dim(`"${truncate2(d.title, 40)}"`) : import_chalk9.default.dim("(no title)");
   let declineSuffix = "";
-  if (d.state === "declined" && d.declineReason) {
+  if (d.state === import_sdk11.DelegationStates.DECLINED && d.declineReason) {
     const detail = d.declineReasonDetail ? `: ${truncate2(d.declineReasonDetail, 40)}` : "";
     declineSuffix = `  ${import_chalk9.default.dim(`(reason: ${d.declineReason}${detail})`)}`;
   }
@@ -4041,8 +4030,6 @@ function formatDelegationLine(d, selfDid, opts = {}) {
 }
 function colorState(s) {
   switch (s) {
-    case "proposed":
-      return import_chalk9.default.yellow("proposed");
     // `offered` is the server's actual emitted state immediately
     // after `delegation offer`; `pending_lock_finalization` is the
     // transient state while the relayer submits create_lock. Both
@@ -4050,34 +4037,34 @@ function colorState(s) {
     // returns `undefined` and `formatDelegationLine` crashes with
     // `TypeError: Cannot read properties of undefined (reading
     // 'padEnd')` on any listing containing such a row.
-    case "offered":
+    case import_sdk11.DelegationStates.OFFERED:
       return import_chalk9.default.yellow("offered");
-    case "pending_lock_finalization":
+    case import_sdk11.DelegationStates.PENDING_LOCK_FINALIZATION:
       return import_chalk9.default.yellow("pending_lock");
-    case "accepted":
+    case import_sdk11.DelegationStates.ACCEPTED:
       return import_chalk9.default.green("accepted");
-    // M6 lock-at-accept: the on-chain escrow lock is confirmed.
-    // Distinct branch so a LOCKED row renders without hitting the
-    // defensive fallback (which would otherwise echo the raw state).
-    case "locked":
+    // The on-chain escrow lock is confirmed. Distinct branch so a
+    // LOCKED row renders without hitting the defensive fallback
+    // (which would otherwise echo the raw state).
+    case import_sdk11.DelegationStates.LOCKED:
       return import_chalk9.default.green("locked");
-    case "declined":
+    case import_sdk11.DelegationStates.DECLINED:
       return import_chalk9.default.red("declined");
-    case "canceled":
+    case import_sdk11.DelegationStates.CANCELED:
       return import_chalk9.default.dim("canceled");
-    // Terminal escrow outcomes (V2): completed = payee paid;
+    // Terminal escrow outcomes: completed = payee paid;
     // failed = create_lock never landed; refunded = funds returned
     // to the buyer (work expired / dispute closed);
     // dispute_resolved = operator ruled.
-    case "completed":
+    case import_sdk11.DelegationStates.COMPLETED:
       return import_chalk9.default.green("completed");
-    case "failed":
+    case import_sdk11.DelegationStates.FAILED:
       return import_chalk9.default.red("failed");
-    case "refunded":
+    case import_sdk11.DelegationStates.REFUNDED:
       return import_chalk9.default.red("refunded");
-    case "disputing":
+    case import_sdk11.DelegationStates.DISPUTING:
       return import_chalk9.default.yellow("disputing");
-    case "dispute_resolved":
+    case import_sdk11.DelegationStates.DISPUTE_RESOLVED:
       return import_chalk9.default.red("dispute_resolved");
     default: {
       const _exhaustive = s;
@@ -4123,7 +4110,7 @@ function parseLimit2(raw) {
 }
 
 // src/commands/did-doc.ts
-var import_sdk8 = require("@heyanon-arp/sdk");
+var import_sdk12 = require("@heyanon-arp/sdk");
 init_api();
 function registerDidDocCommand(root) {
   root.command("did-doc").description(
@@ -4132,7 +4119,7 @@ function registerDidDocCommand(root) {
     "--field <path>",
     "Extract a single value via a dotted path. Supports object property access (`id`), numeric array indexes (`verificationMethod.0`), and `#fragment` array selectors that match a verification-method or service entry by its `id` suffix (`verificationMethod.#settlement.publicKeyMultibase`). Two well-known shortcuts skip the path entirely AND strip the multibase prefix: `settlementPublicKey` / `identityPublicKey` emit the raw base58 pubkey ready for flags like `--recipient-pubkey`. Scalar values (string / number / boolean) emit raw to stdout for shell composition (`KEY=$(heyarp did-doc ... --field ...)`); objects / arrays emit as pretty-printed JSON. Mutually exclusive with `--json` since `--field` already controls the shape."
   ).action(async (did, opts) => {
-    if (!(0, import_sdk8.isValidDid)(did)) {
+    if (!(0, import_sdk12.isValidDid)(did)) {
       throw new Error(`'${did}' is not a syntactically valid did:arp identifier`);
     }
     if (opts.json && opts.field !== void 0) {
@@ -4244,7 +4231,7 @@ function describeShape(value) {
 }
 
 // src/commands/doctor.ts
-var import_sdk9 = require("@heyanon-arp/sdk");
+var import_sdk13 = require("@heyanon-arp/sdk");
 var import_chalk10 = __toESM(require("chalk"));
 init_api();
 function registerDoctorCommand(root) {
@@ -4254,7 +4241,7 @@ function registerDoctorCommand(root) {
 }
 var LISTENING_THRESHOLD_SECONDS = 15 * 60;
 async function runDoctor(did, opts) {
-  if (!(0, import_sdk9.isValidDid)(did)) {
+  if (!(0, import_sdk13.isValidDid)(did)) {
     throw new Error(`'${did}' is not a syntactically valid did:arp identifier`);
   }
   const api = new ArpApiClient(opts.server);
@@ -4407,14 +4394,14 @@ function formatHints(event) {
 }
 
 // src/commands/escrow.ts
-var import_sdk11 = require("@heyanon-arp/sdk");
+var import_sdk15 = require("@heyanon-arp/sdk");
 var import_utils2 = require("@noble/hashes/utils");
 var import_chalk12 = __toESM(require("chalk"));
 init_api();
 
 // src/commands/escrow-actions.ts
 var import_node_crypto = require("crypto");
-var import_sdk10 = require("@heyanon-arp/sdk");
+var import_sdk14 = require("@heyanon-arp/sdk");
 var import_web33 = require("@solana/web3.js");
 init_api();
 var FEE_BUFFER_LAMPORTS = 10000000n;
@@ -4428,7 +4415,7 @@ async function setup(cmd, delegationIdArg, opts) {
   const delegationId = normaliseDelegationId(delegationIdArg);
   const fetched = await fetchLockAccount(conn, programId, delegationId);
   if (!fetched) {
-    const lockPda = deriveLockPda(programId, (0, import_sdk10.deriveLockId)(delegationId)).toBase58();
+    const lockPda = deriveLockPda(programId, (0, import_sdk14.deriveLockId)(delegationId)).toBase58();
     throw new Error(
       `${cmd}: no on-chain Lock for delegation ${delegationId} (PDA ${lockPda} not found on ${rpcUrl}). Either the buyer hasn't funded yet (delegation fund \u2192 server relays create_lock), or you're pointing at the wrong cluster/program.`
     );
@@ -4453,7 +4440,7 @@ function nowSecs() {
 function deadlinePassed(ctx) {
   return ctx.lock.expiry > 0n && nowSecs() >= ctx.lock.expiry;
 }
-var SYSTEM_PROGRAM_B58 = "11111111111111111111111111111111";
+var SYSTEM_PROGRAM_B58 = import_sdk14.SYSTEM_PROGRAM_ID_BASE58;
 function effectiveFeeRecipient(lock) {
   if (lock.feeRecipientAtLock !== SYSTEM_PROGRAM_B58) return new import_web33.PublicKey(lock.feeRecipientAtLock);
   if (lock.treasuryAtLock && lock.treasuryAtLock !== SYSTEM_PROGRAM_B58) return new import_web33.PublicKey(lock.treasuryAtLock);
@@ -4503,7 +4490,7 @@ function emit(ctx, action, signature, extra = {}) {
     lock_id: ctx.lock.lockId,
     state_before: ctx.lock.state,
     signature,
-    rpc_url: ctx.rpcUrl,
+    rpc_url: redactRpcUrl(ctx.rpcUrl),
     ...extra
   };
   if (ctx.opts.json) {
@@ -4515,7 +4502,7 @@ function emit(ctx, action, signature, extra = {}) {
 }
 async function acceptHandler(delegationId, opts) {
   const ctx = await setup("escrow accept", delegationId, opts);
-  requireState(ctx, ["created"], "Accept is only possible before any other transition; if it shows in_progress you already accepted.");
+  requireState(ctx, [import_sdk14.LockStates.CREATED], "Accept is only possible before any other transition; if it shows in_progress you already accepted.");
   requireSigner(ctx, "payee", ctx.lock.payee);
   const stake = ctx.lock.workerStakeAtLock;
   await preflightLamports(ctx, stake, `the worker stake (${stake} lamports, returned when the lock settles in your favour)`);
@@ -4525,7 +4512,7 @@ async function acceptHandler(delegationId, opts) {
 }
 async function submitWorkHandler(delegationId, opts) {
   const ctx = await setup("escrow submit-work", delegationId, opts);
-  requireState(ctx, ["in_progress"], "Submit needs an accepted lock ('created' \u2192 run `heyarp escrow accept` first; terminal \u2192 the cycle already ended).");
+  requireState(ctx, [import_sdk14.LockStates.IN_PROGRESS], "Submit needs an accepted lock ('created' \u2192 run `heyarp escrow accept` first; terminal \u2192 the cycle already ended).");
   requireSigner(ctx, "payee", ctx.lock.payee);
   if (deadlinePassed(ctx)) {
     throw new Error(
@@ -4536,7 +4523,7 @@ async function submitWorkHandler(delegationId, opts) {
   let reviewDeadline = null;
   try {
     const fresh = await fetchLockAccount(ctx.conn, ctx.programId, ctx.delegationId);
-    if (fresh && fresh.lock.state === "submitted" && fresh.lock.expiry > 0n) {
+    if (fresh && fresh.lock.state === import_sdk14.LockStates.SUBMITTED && fresh.lock.expiry > 0n) {
       reviewDeadline = new Date(Number(fresh.lock.expiry) * 1e3).toISOString();
     }
   } catch {
@@ -4549,22 +4536,25 @@ async function submitWorkHandler(delegationId, opts) {
 }
 async function claimHandler(delegationId, opts) {
   const ctx = await setup("escrow claim", delegationId, opts);
-  requireState(ctx, ["submitted"], "Claim needs submitted work ('in_progress' \u2192 the worker must `escrow submit-work` first; 'paid' \u2192 already claimed).");
+  requireState(ctx, [import_sdk14.LockStates.SUBMITTED], "Claim needs submitted work ('in_progress' \u2192 the worker must `escrow submit-work` first; 'paid' \u2192 already claimed).");
   const me = ctx.keypair.publicKey.toBase58();
   let role;
   if (me === ctx.lock.payer) {
-    role = "buyer_approved";
+    role = import_sdk14.EscrowReleaseMethods.BUYER_APPROVED;
   } else if (me === ctx.lock.payee) {
     if (!deadlinePassed(ctx)) {
       throw new Error(
         `escrow claim: the review window is still open (until ${expiryIso(ctx)}). As the worker you can self-claim only AFTER it lapses; before that the buyer must approve (or dispute).`
       );
     }
-    role = "review_timeout";
+    role = import_sdk14.EscrowReleaseMethods.REVIEW_TIMEOUT;
   } else {
     throw new Error(`escrow claim: your settlement key ${me} is neither the payer (${ctx.lock.payer}) nor the payee (${ctx.lock.payee}) of this lock.`);
   }
-  progress(ctx.opts.json, role === "buyer_approved" ? "approving payment as the buyer \u2014 this RELEASES the escrow and is irreversible" : "self-claiming after review timeout");
+  progress(
+    ctx.opts.json,
+    role === import_sdk14.EscrowReleaseMethods.BUYER_APPROVED ? "approving payment as the buyer \u2014 this RELEASES the escrow and is irreversible" : "self-claiming after review timeout"
+  );
   const sig = await sendIx(
     ctx,
     buildClaimWorkPaymentIx({
@@ -4581,7 +4571,7 @@ async function claimHandler(delegationId, opts) {
 }
 async function cancelHandler(delegationId, opts) {
   const ctx = await setup("escrow cancel", delegationId, opts);
-  requireState(ctx, ["created"], "Cancel is the pre-accept exit only \u2014 once the worker accepted ('in_progress') the windows model governs.");
+  requireState(ctx, [import_sdk14.LockStates.CREATED], "Cancel is the pre-accept exit only \u2014 once the worker accepted ('in_progress') the windows model governs.");
   requireSigner(ctx, "payer", ctx.lock.payer);
   const sig = await sendIx(
     ctx,
@@ -4596,7 +4586,7 @@ async function cancelHandler(delegationId, opts) {
 }
 async function claimExpiredHandler(delegationId, opts) {
   const ctx = await setup("escrow claim-expired", delegationId, opts);
-  requireState(ctx, ["in_progress"], "Claim-expired recovers an accepted-but-never-submitted lock; 'submitted' work goes through claim/dispute instead.");
+  requireState(ctx, [import_sdk14.LockStates.IN_PROGRESS], "Claim-expired recovers an accepted-but-never-submitted lock; 'submitted' work goes through claim/dispute instead.");
   requireSigner(ctx, "payer", ctx.lock.payer);
   if (!deadlinePassed(ctx)) {
     throw new Error(`escrow claim-expired: the work window is still open (until ${expiryIso(ctx)}). The worker can still submit; the chain will reject this claim until then.`);
@@ -4614,7 +4604,7 @@ async function claimExpiredHandler(delegationId, opts) {
 }
 async function disputeOpenHandler(delegationId, opts) {
   const ctx = await setup("escrow dispute open", delegationId, opts);
-  requireState(ctx, ["submitted"], "Disputes open against SUBMITTED work, inside the review window.");
+  requireState(ctx, [import_sdk14.LockStates.SUBMITTED], "Disputes open against SUBMITTED work, inside the review window.");
   requireSigner(ctx, "payer", ctx.lock.payer);
   if (deadlinePassed(ctx)) {
     throw new Error(
@@ -4629,7 +4619,7 @@ async function disputeOpenHandler(delegationId, opts) {
 }
 async function disputeCloseHandler(delegationId, opts) {
   const ctx = await setup("escrow dispute close", delegationId, opts);
-  requireState(ctx, ["disputing"], "Close only applies to an OPEN dispute that the operator never resolved.");
+  requireState(ctx, [import_sdk14.LockStates.DISPUTING], "Close only applies to an OPEN dispute that the operator never resolved.");
   const me = ctx.keypair.publicKey.toBase58();
   if (me !== ctx.lock.payer && me !== ctx.lock.payee) {
     throw new Error(`escrow dispute close: your settlement key ${me} is neither party of this lock.`);
@@ -4654,7 +4644,7 @@ async function disputeCloseHandler(delegationId, opts) {
 }
 async function disputeResolveHandler(delegationId, opts) {
   const ctx = await setup("escrow dispute resolve", delegationId, opts);
-  requireState(ctx, ["disputing"], "Resolve only applies to an OPEN dispute, inside the dispute window.");
+  requireState(ctx, [import_sdk14.LockStates.DISPUTING], "Resolve only applies to an OPEN dispute, inside the dispute window.");
   if (deadlinePassed(ctx)) {
     throw new Error(
       `escrow dispute resolve: the dispute window lapsed at ${expiryIso(ctx)} \u2014 the chain rejects late rulings (LockExpired); either party can now \`escrow dispute close\` instead.`
@@ -4695,7 +4685,12 @@ async function showHandler(delegationId, opts) {
   const normalised = normaliseDelegationId(delegationId);
   const fetched = await fetchLockAccount(conn, programId, normalised);
   if (!fetched) {
-    jsonOut({ delegation_id: normalised.slice("del_".length), lock_exists: false, lock_pda: deriveLockPda(programId, (0, import_sdk10.deriveLockId)(normalised)).toBase58(), rpc_url: rpcUrl });
+    jsonOut({
+      delegation_id: normalised.slice("del_".length),
+      lock_exists: false,
+      lock_pda: deriveLockPda(programId, (0, import_sdk14.deriveLockId)(normalised)).toBase58(),
+      rpc_url: redactRpcUrl(rpcUrl)
+    });
     return;
   }
   const l = fetched.lock;
@@ -4714,7 +4709,7 @@ async function showHandler(delegationId, opts) {
     fee_bps_at_lock: l.feeBpsAtLock,
     worker_stake_at_lock: l.workerStakeAtLock.toString(),
     operator_dispute_fee_at_lock: l.operatorDisputeFeeAtLock.toString(),
-    rpc_url: rpcUrl
+    rpc_url: redactRpcUrl(rpcUrl)
   });
 }
 function sharedFlags(cmd) {
@@ -4770,7 +4765,7 @@ function registerEscrowCommands(root) {
     "Compute canonical condition_hash (32-byte hex) for `heyarp wallet create-lock --condition-hash <hex>` from the DELEGATION terms. Projects the flags to the canonical subset and hashes via SDK deriveDelegationConditionHash \u2014 no server fetch. The SAME terms MUST go into `delegation offer` or the server rejects the lock (ESC_LOCK_CONDITION_HASH_MISMATCH)."
   ).requiredOption("--delegation-id <id>", "Delegation UUID this lock binds (drives the on-chain lock_id + the condition_hash identity binding)").requiredOption("--scope <text>", "scope_summary \u2014 short prose describing the agreed work").option(
     "--currency <s>",
-    `Asset identifier bound into the hash: shorthand (${import_sdk11.WELL_KNOWN_ASSET_KEYS.join("|")}) OR raw CAIP-19 string. Optional but must match the offer's --currency.`
+    `Asset identifier bound into the hash: shorthand (${import_sdk15.WELL_KNOWN_ASSET_KEYS.join("|")}) OR raw CAIP-19 string. Optional but must match the offer's --currency.`
   ).option("--currency-decimals <n>", "Decimal places (0-18). Required only when --currency is raw CAIP-19.").option("--currency-symbol <s>", 'Optional UI hint ("USDC", "SOL"). Max 16 chars.').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("--json", "Machine-readable JSON: {delegation_id, condition_hash_hex, projected_subset}", false).action(async (opts) => {
     await runDeriveConditionHash(opts);
   });
@@ -4849,7 +4844,7 @@ async function runDeriveConditionHash(opts) {
   progress(opts.json, import_chalk12.default.dim(`Server: ${api.serverUrl}`));
   progress(opts.json, import_chalk12.default.dim(`Signer: ${sender.did}`));
   const subset = projectDelegationForHash(cmdName, opts, delegationId);
-  const hashBytes = (0, import_sdk11.deriveDelegationConditionHash)(subset);
+  const hashBytes = (0, import_sdk15.deriveDelegationConditionHash)(subset);
   const hex = (0, import_utils2.bytesToHex)(hashBytes);
   if (opts.json) {
     jsonOut({
@@ -4931,6 +4926,7 @@ async function runRecoverSequence(opts) {
 }
 
 // src/commands/events.ts
+var import_sdk16 = require("@heyanon-arp/sdk");
 var import_chalk13 = __toESM(require("chalk"));
 init_api();
 function registerEventsCommand(root) {
@@ -4949,7 +4945,7 @@ function registerEventsCommand(root) {
     false
   ).option(
     "--full-ids",
-    "Print eventId, DIDs and serverEventHash in full (no truncation). The eventId column in the default human row is truncated to `evt_<head>...<tail>` \u2014 pass --full-ids to read the full UUID for `heyarp envelope <evt-id>`. NOTE: `serverEventHash` is the hash-chain anchor, NOT the value `receipt propose / cosign` require \u2014 those want `requestHash` / `responseHash`, which are exposed by `heyarp receipts <rel-id> --full-ids`, or auto-derived via `receipt propose --auto-hashes --rel-id --request-id` / `receipt cosign --auto-hashes [--request-id]`.",
+    "Print eventId, DIDs and serverEventHash in full (no truncation). The eventId column in the default human row is truncated to `evt_<head>...<tail>` \u2014 pass --full-ids to read the full UUID for `heyarp envelope <evt-id>`. NOTE: `serverEventHash` is the hash-chain anchor, NOT the value `receipt propose` requires \u2014 that wants `requestHash` / `responseHash`, which are exposed by `heyarp receipts <rel-id> --full-ids`, or auto-derived via `receipt propose --auto-hashes --rel-id --request-id`.",
     false
   ).option(
     "--success-only",
@@ -4981,8 +4977,8 @@ async function runEvents(relationshipId, opts) {
   }
   const query = { limit };
   if (since !== void 0) query.since = since;
-  if (opts.successOnly) query.readModelStatus = "materialized";
-  else if (opts.rejectedOnly) query.readModelStatus = "rejected";
+  if (opts.successOnly) query.readModelStatus = import_sdk16.ReadModelStatuses.MATERIALIZED;
+  else if (opts.rejectedOnly) query.readModelStatus = import_sdk16.ReadModelStatuses.REJECTED;
   const signer = makeSigner(sender);
   const events = await api.listEvents(relationshipId, signer, query);
   if (opts.json) {
@@ -5001,8 +4997,7 @@ async function runEvents(relationshipId, opts) {
     printVerbose(events, "Full event envelopes:", (ev) => ({
       primary: `#${ev.relationshipEventIndex} ${ev.type ?? "<unknown>"}`,
       // Surface BOTH the full eventId (used by `heyarp envelope
-      // <evt-id>`) and the full serverEventHash (used by
-      // `receipt propose` / `receipt cosign`).
+      // <evt-id>`) and the full serverEventHash.
       secondary: `eventId=${ev.eventId} serverEventHash=${ev.serverEventHash}`
     }));
   }
@@ -5018,8 +5013,8 @@ function formatEventLine(ev, selfDid, opts = {}) {
   const hash = opts.fullIds ? ev.serverEventHash : hashHead(ev.serverEventHash);
   const extra = extraDetail(ev);
   const tail = extra ? `   ${import_chalk13.default.dim(`(${extra})`)}` : "";
-  const status = ev.readModelStatus ?? "materialized";
-  const statusGlyph = status === "rejected" ? `${import_chalk13.default.red("\u2717")} ` : "  ";
+  const status = ev.readModelStatus ?? import_sdk16.ReadModelStatuses.MATERIALIZED;
+  const statusGlyph = status === import_sdk16.ReadModelStatuses.REJECTED ? `${import_chalk13.default.red("\u2717")} ` : "  ";
   return `${statusGlyph}${idx}  ${import_chalk13.default.cyan(eventId)}  ${type}  ${direction}    ${import_chalk13.default.cyan(hash)}${tail}`;
 }
 function eventIdHead(eventId) {
@@ -5310,7 +5305,7 @@ var GUIDE_SECTIONS = [
     title: "Identity",
     body: [
       "   \u2022 Each agent has a `did:arp:<base58btc>` DID + an Ed25519 identity key.",
-      "   \u2022 Keys live in `~/.arp/agents.json` (or $HEYARP_HOME/agents.json).",
+      "   \u2022 Keys live in `~/.heyarp/agents.json` (or $HEYARP_HOME/agents.json).",
       "   \u2022 State file = identity. If two agents share one home dir, EITHER can sign as",
       "     the other. For multi-agent setups on one host, set HEYARP_HOME per agent:",
       "       HEYARP_HOME=/tmp/agent-alice  heyarp register \u2026",
@@ -5337,8 +5332,8 @@ var GUIDE_SECTIONS = [
       "",
       "   (There is no separate terms-agreement step \u2014 the delegation offer",
       "   carries the agreed terms inline and the condition_hash binds them.",
-      "   M6 lock-at-accept: the escrow lock is funded AFTER acceptance via",
-      "   `delegation fund`, so an un-accepted offer never strands funds.)",
+      "   The escrow lock is funded AFTER acceptance via `delegation fund`,",
+      "   so an un-accepted offer never strands funds.)",
       "   Skipping any stage = the next stage rejects with a state-machine error.",
       "   On-chain claim_work_payment is the closure: the buyer approves, or the",
       "   worker self-claims after the review window expires."
@@ -5350,13 +5345,13 @@ var GUIDE_SECTIONS = [
     overview: true,
     title: "Escrow (how funds actually move)",
     body: [
-      "   M6 lock-at-accept: the buyer funds escrow AFTER the worker accepts.",
+      "   The buyer funds escrow AFTER the worker accepts.",
       "   `delegation offer` carries terms only (no lock). Once the worker",
       "   accepts, `delegation fund` attaches the signed Solana `create_lock`",
       "   tx blob; the worker waits for the lock to confirm (LOCKED) before",
       "   starting work, knowing the cash is locked. An un-accepted offer has",
       "   no lock to strand.",
-      "   Payment consent is ON-CHAIN (V2): the payer sends claim_work_payment to",
+      "   Payment consent is ON-CHAIN: the payer sends claim_work_payment to",
       "   approve, or the payee self-claims after the review window. Exit paths:",
       "     \u2022 cancel_lock         \u2014 buyer cancels while the lock is unaccepted",
       "     \u2022 claim_expired_work  \u2014 buyer reclaims if the work window lapses",
@@ -5557,7 +5552,7 @@ var GUIDE_SECTIONS = [
       "     relationship     : status <rel> --json \u2192 .relationshipState (NOT .state)",
       "     delegation       : status <rel> --json \u2192 .latestDelegation.state",
       "                        (or delegations <rel> --json \u2192 .[].state)",
-      "     receipt          : receipts <rel> --json \u2192 .[].state / .verdictFinal / .receiptEventHash",
+      "     receipt          : receipts <rel> --json \u2192 .[].state / .verdictProposed / .receiptEventHash",
       "     incoming events  : inbox --json \u2192 .[].body.type / .eventId / .serverTimestamp /",
       "                        .senderDid (NOT .signer)",
       "     worker pay key   : did-doc <worker-did> --field settlementPublicKey",
@@ -6067,9 +6062,9 @@ async function runInbox(positionalDid, opts) {
     printVerbose(events, "Full event envelopes:", (ev) => ({
       primary: `#${ev.relationshipEventIndex} ${ev.type ?? "<unknown>"}`,
       // eventId is the cursor used by `--before-event-id`;
-      // serverEventHash is what `receipt propose` / `cosign`
-      // requires. Surface BOTH inline so a copy-paste workflow
-      // doesn't have to dig into the JSON below.
+      // serverEventHash is what `receipt propose` requires.
+      // Surface BOTH inline so a copy-paste workflow doesn't have
+      // to dig into the JSON below.
       secondary: `eventId=${ev.eventId} serverEventHash=${ev.serverEventHash}`
     }));
   }
@@ -6194,7 +6189,7 @@ function parseLimit4(raw) {
 // src/commands/keys.ts
 var import_node_crypto2 = require("crypto");
 var import_node_fs7 = require("fs");
-var import_sdk12 = require("@heyanon-arp/sdk");
+var import_sdk17 = require("@heyanon-arp/sdk");
 var import_chalk17 = __toESM(require("chalk"));
 function writeSecretFile(path, body) {
   const tmp = `${path}.tmp.${(0, import_node_crypto2.randomBytes)(8).toString("hex")}`;
@@ -6221,25 +6216,22 @@ function writeSecretFile(path, body) {
 }
 function registerKeysCommand(root) {
   const keys = root.command("keys").description("Local key utilities");
-  keys.command("gen").description("Generate a fresh identity + settlement keypair (no save by default)").option("--save", "Reserved for future scratch-key storage; currently a no-op with a notice", false).action((opts) => {
-    const identity = (0, import_sdk12.generateKeyPair)();
-    const settlement = (0, import_sdk12.generateKeyPair)();
+  keys.command("gen").description("Generate a fresh identity + settlement keypair (no save by default)").action(() => {
+    const identity = (0, import_sdk17.generateKeyPair)();
+    const settlement = (0, import_sdk17.generateKeyPair)();
     const out = [
       import_chalk17.default.bold("Identity key (Ed25519)"),
-      `  public  (base58btc): ${import_chalk17.default.cyan((0, import_sdk12.base58btcEncode)(identity.publicKey))}`,
+      `  public  (base58btc): ${import_chalk17.default.cyan((0, import_sdk17.base58btcEncode)(identity.publicKey))}`,
       `  secret  (base64)   : ${import_chalk17.default.yellow(Buffer.from(identity.secretKey).toString("base64"))}`,
       "",
       import_chalk17.default.bold("Settlement key (Ed25519)"),
-      `  public  (base58btc): ${import_chalk17.default.cyan((0, import_sdk12.base58btcEncode)(settlement.publicKey))}`,
+      `  public  (base58btc): ${import_chalk17.default.cyan((0, import_sdk17.base58btcEncode)(settlement.publicKey))}`,
       `  secret  (base64)   : ${import_chalk17.default.yellow(Buffer.from(settlement.secretKey).toString("base64"))}`,
       "",
       import_chalk17.default.bold("Resulting DID"),
-      `  ${import_chalk17.default.cyan((0, import_sdk12.formatDid)(identity.publicKey))}`
+      `  ${import_chalk17.default.cyan((0, import_sdk17.formatDid)(identity.publicKey))}`
     ];
     console.log(out.join("\n"));
-    if (opts.save) {
-      console.log(import_chalk17.default.yellow("\nNote: --save is not yet implemented. Capture the secret keys above before they scroll off-screen."));
-    }
   });
   keys.command("export <did>").description("Export an agent\u2019s key backup bundle (SECRETS) so you can recover it on another machine with `heyarp recover`. Writes to --out (mode 0600) or stdout.").option("--server <url>", "Override ARP server base URL").option("--out <file>", "Write the bundle to this file (mode 0600) instead of stdout").action((did, opts) => {
     const agent = loadAgentOrThrow(opts.server, did);
@@ -6256,10 +6248,10 @@ function registerKeysCommand(root) {
   });
   keys.command("whoami").description("Print the DID derived from a base64-encoded identity secret key").argument("<secret-key-b64>", "32-byte Ed25519 seed, base64").action((secretKeyB64) => {
     const seed = decodeSeed(secretKeyB64);
-    const pub = (0, import_sdk12.getPublicKey)(seed);
-    const did = (0, import_sdk12.formatDid)(pub);
+    const pub = (0, import_sdk17.getPublicKey)(seed);
+    const did = (0, import_sdk17.formatDid)(pub);
     console.log(`${import_chalk17.default.bold("DID")}: ${import_chalk17.default.cyan(did)}`);
-    console.log(`${import_chalk17.default.bold("Identity public key (base58btc)")}: ${import_chalk17.default.cyan((0, import_sdk12.base58btcEncode)(pub))}`);
+    console.log(`${import_chalk17.default.bold("Identity public key (base58btc)")}: ${import_chalk17.default.cyan((0, import_sdk17.base58btcEncode)(pub))}`);
   });
 }
 function decodeSeed(b64) {
@@ -6278,8 +6270,12 @@ function decodeSeed(b64) {
 // src/commands/list.ts
 var import_chalk18 = __toESM(require("chalk"));
 function registerListCommand(root) {
-  root.command("list").description("List agents registered locally (~/.arp/agents.json)").action(() => {
+  root.command("list").description("List agents registered locally (~/.heyarp/agents.json)").option("--json", "Machine-readable mode \u2014 emit the local agents as a single JSON array on stdout ({serverUrl, did, name, tags, registeredAt}[]).", false).action((opts) => {
     const rows = listAgents();
+    if (opts.json) {
+      jsonOut(rows.map(({ serverUrl, agent }) => ({ serverUrl, did: agent.did, name: agent.name ?? null, tags: agent.tags ?? [], registeredAt: agent.registeredAt })));
+      return;
+    }
     if (rows.length === 0) {
       console.log(import_chalk18.default.dim(`No local agents. State file: ${stateFilePath()}`));
       return;
@@ -6418,12 +6414,12 @@ function registerLogoutCommand(root) {
 }
 
 // src/commands/profile.ts
-var import_sdk13 = require("@heyanon-arp/sdk");
+var import_sdk18 = require("@heyanon-arp/sdk");
 var import_chalk21 = __toESM(require("chalk"));
 init_api();
 function registerProfileCommand(root) {
   root.command("profile").description("Composed agent profile: public fields + reputation + liveness, in one read.").argument("<did>", "did:arp:<base58btc> identifier").option("--server <url>", "Override ARP server base URL").option("--json", "Emit the profile as JSON on stdout.", false).action(async (did, opts) => {
-    if (!(0, import_sdk13.isValidDid)(did)) {
+    if (!(0, import_sdk18.isValidDid)(did)) {
       throw new Error(`'${did}' is not a syntactically valid did:arp identifier`);
     }
     const api = new ArpApiClient(opts.server);
@@ -6451,45 +6447,16 @@ function registerProfileCommand(root) {
 }
 
 // src/commands/receipt.ts
-var import_sdk14 = require("@heyanon-arp/sdk");
+var import_sdk19 = require("@heyanon-arp/sdk");
 var import_shield2 = require("@heyanon-arp/shield");
 var import_chalk22 = __toESM(require("chalk"));
 init_api();
 function registerReceiptCommands(root) {
-  const cmd = root.command("receipt").description("Receipt envelopes \u2014 the payee proposes a delivery record (V2: payment consent is on-chain via claim_work_payment)");
+  const cmd = root.command("receipt").description("Receipt envelopes \u2014 the payee proposes a delivery record (payment consent is on-chain via claim_work_payment)");
   registerPropose(cmd);
 }
-var POST_COMMIT_ERROR_CODES2 = /* @__PURE__ */ new Set([
-  "RECEIPT_ALREADY_EXISTS",
-  "RECEIPT_DELEGATION_NOT_FOUND",
-  "RECEIPT_DELEGATION_NOT_ACTIVE",
-  "RECEIPT_RELATIONSHIP_MISMATCH",
-  "RECEIPT_ISSUER_IS_CALLER",
-  "RECEIPT_NOT_FOUND",
-  "RECEIPT_INVALID_STATE",
-  // M6 lock-at-accept: the receipt-propose handler's LOCKED gate emits
-  // `DELEGATION_PENDING_LOCK` (409) when the delegation is funded but
-  // the on-chain lock isn't confirmed yet (state
-  // `pending_lock_finalization`). It fires from the body handler AFTER
-  // the event row is committed — same lifecycle as
-  // `RECEIPT_DELEGATION_NOT_ACTIVE` — so the CLI must advance
-  // `lastSenderSequence`, otherwise a retry once the lock confirms
-  // reuses the consumed sequence and trips `ENV_SEQUENCE_BACKWARDS`.
-  "DELEGATION_PENDING_LOCK",
-  // response_hash / request_hash / deliverable_hash content
-  // verification. Server commits the receipt envelope row BEFORE
-  // running the canonical-hash lookup, so a rejection here still
-  // consumes the sender sequence — must be in the allowlist or
-  // a retry after fixing the hashes would trip
-  // `ENV_SEQUENCE_BACKWARDS`.
-  "RECEIPT_RESPONSE_HASH_NOT_FOUND",
-  "RECEIPT_REQUEST_HASH_NOT_FOUND",
-  "RECEIPT_DELIVERABLE_HASH_MISMATCH"
-]);
-var VERDICT_VALUES = ["accepted", "accepted_with_notes", "rejected"];
-var SHA256_RE = /^sha256:[0-9a-f]{64}$/;
 function registerPropose(parent) {
-  parent.command("propose").description("Send a receipt envelope as the PAYEE. Row lands PROPOSED; caller cosigns to flip to COSIGNED.").argument("<recipient-did>", "Recipient agent DID (= caller / offerer of the parent delegation)").argument("<delegation-id>", "Parent delegation id (UUID, must be ACCEPTED)").argument("[request-hash]", "sha256:<64 hex> \u2014 SHA-256 of the work_request payload being settled. Omit when --auto-hashes is set.").argument("[response-hash]", "sha256:<64 hex> \u2014 SHA-256 of the work_response payload being settled. Omit when --auto-hashes is set.").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("--verdict <s>", "verdict_proposed (accepted | accepted_with_notes | rejected)", "accepted").option("--notes-hash <sha256>", "Optional sha256:<64 hex> notes hash").option("--deliverable-hash <sha256>", "Optional sha256:<64 hex> deliverable hash").option("--input-tokens <n>", "Optional usage.input_tokens").option("--output-tokens <n>", "Optional usage.output_tokens").option("--latency-ms <n>", "Optional usage.latency_ms").option("--model <name>", "Optional usage.model").option("--computed-amount <s>", "Optional usage.computed_amount").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option(
+  parent.command("propose").description("Send a receipt envelope as the PAYEE. Row lands PROPOSED; the buyer approves payment on-chain via claim_work_payment.").argument("<recipient-did>", "Recipient agent DID (= caller / offerer of the parent delegation)").argument("<delegation-id>", "Parent delegation id (UUID, must be ACCEPTED)").argument("[request-hash]", "sha256:<64 hex> \u2014 SHA-256 of the work_request payload being settled. Omit when --auto-hashes is set.").argument("[response-hash]", "sha256:<64 hex> \u2014 SHA-256 of the work_response payload being settled. Omit when --auto-hashes is set.").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("--verdict <s>", "verdict_proposed (accepted | accepted_with_notes | rejected)", "accepted").option("--notes-hash <sha256>", "Optional sha256:<64 hex> notes hash").option("--deliverable-hash <sha256>", "Optional sha256:<64 hex> deliverable hash").option("--input-tokens <n>", "Optional usage.input_tokens").option("--output-tokens <n>", "Optional usage.output_tokens").option("--latency-ms <n>", "Optional usage.latency_ms").option("--model <name>", "Optional usage.model").option("--computed-amount <s>", "Optional usage.computed_amount").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option(
     "--auto-hashes",
     "Compute request_hash + response_hash automatically from the work-log row at (--rel-id, <delegation-id>, --request-id). Positional <request-hash>/<response-hash> become optional; if supplied they must match the computed values (consistency check). --rel-id and --request-id auto-resolve from local state when unambiguous \u2014 pass them explicitly only if the lookup finds multiple candidates.",
     false
@@ -6630,7 +6597,7 @@ async function assertSenderIsReceiptPayee(api, sender, relationshipId, delegatio
   }
   if (delegation.offererDid === sender.did) {
     throw new Error(
-      `receipt propose: ${sender.did} is the CALLER on delegation ${delegationId} (matches delegation.offererDid). Only the PAYEE \u2014 the counterparty who accepted the delegation offer \u2014 can issue a receipt; as the caller your role is to COSIGN the receipt the payee proposes. Wait for it via \`heyarp status ${relationshipId} --wait --until receipt.proposed\` then run \`heyarp receipt cosign ${relationshipId} ${delegationId} --auto-hashes [--request-id <id>] --settlement-purpose <p> --settlement-expires-at <unix> --payer-sig-from-file <path> --payee-sig-from-file <path>\`.`
+      `receipt propose: ${sender.did} is the CALLER on delegation ${delegationId} (matches delegation.offererDid). Only the PAYEE \u2014 the counterparty who accepted the delegation offer \u2014 can issue a receipt; as the caller your role is to approve payment ON-CHAIN via claim_work_payment once the payee proposes the receipt. Wait for it via \`heyarp status ${relationshipId} --wait --until receipt.proposed\`.`
     );
   }
   return delegation;
@@ -6687,7 +6654,7 @@ async function computeWorkLogHashes(api, sender, relationshipId, delegationId, r
       `receipt propose --auto-hashes: no work-log row found for (relationshipId=${relationshipId}, delegationId=${delegationId}, requestId=${requestId}). Did the work_request envelope land yet?`
     );
   }
-  if (workLog.state !== "responded") {
+  if (workLog.state !== import_sdk19.WorkLogStates.RESPONDED) {
     throw new Error(
       `receipt propose --auto-hashes: work-log row ${requestId} is in state '${workLog.state}', not 'responded'. The payee must \`work respond\` before a receipt can be proposed.`
     );
@@ -6703,27 +6670,27 @@ async function computeWorkLogHashes(api, sender, relationshipId, delegationId, r
   };
   const responseBody = workLog.responseOutput !== void 0 ? { type: "work_response", content: { delegation_id: workLog.delegationId, request_id: workLog.requestId, output: workLog.responseOutput } } : { type: "work_response", content: { delegation_id: workLog.delegationId, request_id: workLog.requestId, error: workLog.responseError } };
   return {
-    requestHash: (0, import_sdk14.canonicalSha256Hex)(requestBody),
-    responseHash: (0, import_sdk14.canonicalSha256Hex)(responseBody)
+    requestHash: (0, import_sdk19.canonicalSha256Hex)(requestBody),
+    responseHash: (0, import_sdk19.canonicalSha256Hex)(responseBody)
   };
 }
 async function sendReceiptEnvelope(args) {
   const nextSequence = (args.sender.lastSenderSequence ?? 0) + 1;
   const protectedBlock = {
-    protocol_version: "arp/0.1",
-    purpose: import_sdk14.Purpose.ENVELOPE,
-    message_id: (0, import_sdk14.uuidV4)(),
+    protocol_version: import_sdk19.CURRENT_PROTOCOL_VERSION,
+    purpose: import_sdk19.Purpose.ENVELOPE,
+    message_id: (0, import_sdk19.uuidV4)(),
     sender_did: args.sender.did,
     recipient_did: args.recipientDid,
     relationship_id: null,
     sender_sequence: nextSequence,
-    sender_nonce: (0, import_sdk14.senderNonce)(),
-    timestamp: (0, import_sdk14.rfc3339)(),
-    expires_at: (0, import_sdk14.expiresAt)(args.ttlSeconds),
+    sender_nonce: (0, import_sdk19.senderNonce)(),
+    timestamp: (0, import_sdk19.rfc3339)(),
+    expires_at: (0, import_sdk19.expiresAt)(args.ttlSeconds),
     delivery_id: null
   };
   const signer = makeSigner(args.sender);
-  const envelope = (0, import_sdk14.signEnvelope)({
+  const envelope = (0, import_sdk19.signEnvelope)({
     protected: protectedBlock,
     body: args.body,
     identitySecretKey: signer.identitySecretKey,
@@ -6738,7 +6705,7 @@ async function sendReceiptEnvelope(args) {
     updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
     return result;
   } catch (err) {
-    if (err instanceof ApiError && POST_COMMIT_ERROR_CODES2.has(err.payload.code)) {
+    if (err instanceof ApiError && (0, import_sdk19.isPostCommitErrorCode)(err.payload.code)) {
       updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
     }
     throw err;
@@ -6753,9 +6720,9 @@ function printIngestResult2(result) {
   console.log(`${import_chalk22.default.bold("Server event hash")}: ${import_chalk22.default.cyan(result.serverEventHash)}`);
 }
 function parseVerdict(cmdName, raw) {
-  if (raw === void 0 || raw === "") return "accepted";
-  if (!VERDICT_VALUES.includes(raw)) {
-    throw new Error(`${cmdName}: --verdict must be one of ${VERDICT_VALUES.join(" | ")} (got '${raw}')`);
+  if (raw === void 0 || raw === "") return import_sdk19.ReceiptVerdicts.ACCEPTED;
+  if (!import_sdk19.RECEIPT_VERDICTS.includes(raw)) {
+    throw new Error(`${cmdName}: --verdict must be one of ${import_sdk19.RECEIPT_VERDICTS.join(" | ")} (got '${raw}')`);
   }
   return raw;
 }
@@ -6792,7 +6759,7 @@ function requireUuid3(cmdName, raw, label) {
   requireUuid(cmdName, raw, label);
 }
 function requireSha256(cmdName, raw, label) {
-  if (!SHA256_RE.test(raw)) {
+  if (!(0, import_sdk19.isSha256Hex)(raw)) {
     throw new Error(`${cmdName}: ${label} must match 'sha256:<64 lowercase hex>' (got '${raw}')`);
   }
 }
@@ -6803,21 +6770,17 @@ function requireDid2(cmdName, did, label) {
 }
 
 // src/commands/receipts.ts
+var import_sdk20 = require("@heyanon-arp/sdk");
 var import_chalk23 = __toESM(require("chalk"));
 init_api();
-var ALLOWED_STATES2 = /* @__PURE__ */ new Set(["proposed", "cosigned"]);
 function registerReceiptsCommand(root) {
   root.command("receipts").description(
     "List receipts for a relationship (one row per (delegationId, requestHash, responseHash), oldest-first). Receipt rows expose the chain hash as `receiptEventHash` (NOT `serverEventHash` \u2014 that field is the wider envelope identifier on `heyarp events` rows). Scripts using `--json | jq .receiptEventHash` get the value; `jq .serverEventHash` silently returns null because the row doesn't carry that key."
-  ).argument("<relationship-id>", "Relationship UUID").option("--server <url>", "Override ARP server base URL").option("--state <s>", "Filter by exact state (proposed|cosigned)").option("--delegation-id <uuid>", "Narrow to receipts under a specific delegation id").option("--after <id>", "Cursor: pass the previous page's last `id` to fetch the next page").option("--limit <n>", "Max rows to return (1..100)", "20").option("--from-did <did>", "Signer DID \u2014 required only if multiple agents are registered against this server").option(
+  ).argument("<relationship-id>", "Relationship UUID").option("--server <url>", "Override ARP server base URL").option("--delegation-id <uuid>", "Narrow to receipts under a specific delegation id").option("--after <id>", "Cursor: pass the previous page's last `id` to fetch the next page").option("--limit <n>", "Max rows to return (1..100)", "20").option("--from-did <did>", "Signer DID \u2014 required only if multiple agents are registered against this server").option(
     "--verbose",
-    'After the one-line summaries, print a framed "Full receipt payloads (N rows)" block \u2014 each row labelled with full delegationId + requestHash + responseHash (the values `receipt cosign` requires) and dumped as JSON. Mutually exclusive with --json.',
-    false
-  ).option("--json", "Machine-readable mode \u2014 emit a single JSON array of receipt rows, no chalk, no summary. Pipe-safe. Mutually exclusive with --verbose.", false).option(
-    "--full-ids",
-    "Print delegationId / requestHash / responseHash / DIDs in full (no truncation). REQUIRED for piping into `receipt cosign` which needs the full sha256s.",
+    'After the one-line summaries, print a framed "Full receipt payloads (N rows)" block \u2014 each row labelled with full delegationId + requestHash + responseHash and dumped as JSON. Mutually exclusive with --json.',
     false
-  ).action(async (relationshipId, opts) => {
+  ).option("--json", "Machine-readable mode \u2014 emit a single JSON array of receipt rows, no chalk, no summary. Pipe-safe. Mutually exclusive with --verbose.", false).option("--full-ids", "Print delegationId / requestHash / responseHash / DIDs in full (no truncation).", false).action(async (relationshipId, opts) => {
     await runReceipts(relationshipId, opts);
   });
 }
@@ -6828,7 +6791,6 @@ async function runReceipts(relationshipId, opts) {
     );
   }
   const limit = parseLimit5(opts.limit);
-  const state = parseState2(opts.state);
   const api = new ArpApiClient(opts.server);
   const sender = resolveSenderAgent("receipts", opts.server, opts.fromDid);
   if (!opts.json) {
@@ -6837,7 +6799,6 @@ async function runReceipts(relationshipId, opts) {
     console.log(import_chalk23.default.dim(`Relationship: ${relationshipId}`));
   }
   const query = { limit };
-  if (state) query.state = state;
   if (opts.delegationId) query.delegationId = opts.delegationId;
   if (opts.after) query.after = opts.after;
   const signer = makeSigner(sender);
@@ -6856,11 +6817,10 @@ async function runReceipts(relationshipId, opts) {
   }
   if (opts.verbose) {
     printVerbose(rows, "Full receipt payloads:", (r) => ({
-      primary: `state=${r.state} verdict=${r.verdictFinal ?? r.verdictProposed}`,
-      // `receipt cosign` requires the FULL `requestHash` and
-      // `responseHash` plus `delegationId`. Putting all three on
-      // one inline label keeps the cosign flow grep-able without
-      // dropping into `--json | jq`.
+      primary: `verdict=${r.verdictProposed}`,
+      // Surface the FULL `requestHash` + `responseHash` + `delegationId`
+      // on one inline label so the receipt-correlation flow stays
+      // grep-able without dropping into `--json | jq`.
       secondary: `delegationId=${r.delegationId} requestHash=${r.requestHash} responseHash=${r.responseHash}`
     }));
   }
@@ -6872,34 +6832,21 @@ function formatReceiptLine(r, selfDid, opts = {}) {
   const delegationPart = opts.fullIds ? r.delegationId : idHead2(r.delegationId);
   const requestHashPart = opts.fullIds ? r.requestHash : hashHead3(r.requestHash);
   const id = import_chalk23.default.bold(`${delegationPart}/${requestHashPart}`);
-  const state = colorState2(r.state).padEnd(stateColumnWidth2());
   const callerHead = opts.fullIds ? r.callerDid : didHead3(r.callerDid);
   const payeeHead = opts.fullIds ? r.payeeDid : didHead3(r.payeeDid);
   const direction = r.payeeDid === selfDid ? `${import_chalk23.default.bold("me")}(payee) \u2192 ${import_chalk23.default.dim(callerHead)}` : `${import_chalk23.default.dim(payeeHead)}(payee) \u2192 ${import_chalk23.default.bold("me")}`;
   const verdict = formatVerdict(r);
   const responseTail = opts.fullIds ? `
   ${import_chalk23.default.dim("responseHash:")} ${import_chalk23.default.cyan(r.responseHash)}` : "";
-  return `${id}  ${state}  ${direction}  ${verdict}${responseTail}`;
-}
-function colorState2(s) {
-  switch (s) {
-    case "proposed":
-      return import_chalk23.default.yellow("proposed");
-    case "cosigned":
-      return import_chalk23.default.green("cosigned");
-  }
-}
-function stateColumnWidth2() {
-  return 8;
+  return `${id}  ${direction}  ${verdict}${responseTail}`;
 }
 function formatVerdict(r) {
-  const final = r.verdictFinal ?? r.verdictProposed;
-  switch (final) {
-    case "accepted":
+  switch (r.verdictProposed) {
+    case import_sdk20.ReceiptVerdicts.ACCEPTED:
       return import_chalk23.default.green("accepted");
-    case "accepted_with_notes":
+    case import_sdk20.ReceiptVerdicts.ACCEPTED_WITH_NOTES:
       return import_chalk23.default.yellow("accepted_with_notes");
-    case "rejected":
+    case import_sdk20.ReceiptVerdicts.REJECTED:
       return import_chalk23.default.red("rejected");
   }
 }
@@ -6915,13 +6862,6 @@ function didHead3(did) {
   if (did.length <= 20) return did;
   return `${did.slice(0, 20)}...`;
 }
-function parseState2(raw) {
-  if (raw === void 0) return void 0;
-  if (!ALLOWED_STATES2.has(raw)) {
-    throw new Error(`receipts: --state must be one of proposed|cosigned (got '${raw}')`);
-  }
-  return raw;
-}
 function parseLimit5(raw) {
   if (raw === void 0) return 20;
   const n = Number(raw);
@@ -6933,7 +6873,7 @@ function parseLimit5(raw) {
 
 // src/commands/recover.ts
 var import_node_fs8 = require("fs");
-var import_sdk15 = require("@heyanon-arp/sdk");
+var import_sdk21 = require("@heyanon-arp/sdk");
 var import_chalk24 = __toESM(require("chalk"));
 init_api();
 function registerRecoverCommand(root) {
@@ -6954,18 +6894,18 @@ async function runRecover(opts) {
   }
   const bundle = validateKeyBundle(raw);
   const identitySecret = new Uint8Array(Buffer.from(bundle.identitySecretKeyB64, "base64"));
-  const identityPub = (0, import_sdk15.base58btcDecode)(bundle.identityPublicKeyB58);
-  const derivedDid = (0, import_sdk15.formatDid)(identityPub);
+  const identityPub = (0, import_sdk21.base58btcDecode)(bundle.identityPublicKeyB58);
+  const derivedDid = (0, import_sdk21.formatDid)(identityPub);
   if (derivedDid !== bundle.did) {
     throw new Error(`recover: key file is inconsistent \u2014 its DID (${bundle.did}) does not match its identity public key (${derivedDid})`);
   }
   const probe2 = new TextEncoder().encode("heyarp-recover-keycheck");
-  if (!(0, import_sdk15.verify)((0, import_sdk15.sign)(probe2, identitySecret), probe2, identityPub)) {
+  if (!(0, import_sdk21.verify)((0, import_sdk21.sign)(probe2, identitySecret), probe2, identityPub)) {
     throw new Error("recover: the identity secret key does not match the public key in this bundle");
   }
   const settlementSecret = new Uint8Array(Buffer.from(bundle.settlementSecretKeyB64, "base64"));
-  const settlementPub = (0, import_sdk15.base58btcDecode)(bundle.settlementPublicKeyB58);
-  if (!(0, import_sdk15.verify)((0, import_sdk15.sign)(probe2, settlementSecret), probe2, settlementPub)) {
+  const settlementPub = (0, import_sdk21.base58btcDecode)(bundle.settlementPublicKeyB58);
+  if (!(0, import_sdk21.verify)((0, import_sdk21.sign)(probe2, settlementSecret), probe2, settlementPub)) {
     throw new Error("recover: the settlement secret key does not match the settlement public key in this bundle");
   }
   if (bundle.ownerWallet && bundle.ownerWallet !== credential.wallet) {
@@ -6987,8 +6927,10 @@ async function runRecover(opts) {
     lastSenderSequence = seq.lastSenderSequence;
   } catch (err) {
     process.stderr.write(
-      import_chalk24.default.yellow(`\u26A0 could not read the sender sequence from the server (${err.message}). If sends are rejected as backwards, run \`heyarp escrow recover-sequence --apply\`.
-`)
+      import_chalk24.default.yellow(
+        `\u26A0 could not read the sender sequence from the server (${err.message}). If sends are rejected as backwards, run \`heyarp escrow recover-sequence --apply\`.
+`
+      )
     );
   }
   const state = {
@@ -7019,7 +6961,7 @@ async function runRecover(opts) {
 // src/commands/register.ts
 var import_node_crypto4 = require("crypto");
 var import_node_fs9 = require("fs");
-var import_sdk16 = require("@heyanon-arp/sdk");
+var import_sdk22 = require("@heyanon-arp/sdk");
 var import_chalk25 = __toESM(require("chalk"));
 var import_prompts2 = __toESM(require("prompts"));
 init_api();
@@ -7040,13 +6982,12 @@ function registerRegisterCommand(root) {
     // logged by CI runners (e.g. GitHub Actions echoes the
     // full command). Safer alternatives:
     // • interactive prompt (default) — never written anywhere
-    // • `HEYARP_PASSWORD` env var (V1.5 — tracked) reads
-    //   from env so the secret stays out of argv even in
-    //   scripts
+    // • `HEYARP_PASSWORD` env var (tracked) reads from env so
+    //   the secret stays out of argv even in scripts
     // Treat `--password <s>` as a one-off local-dev affordance;
     // do NOT use it in CI pipelines without a secret-redacting
     // runner.
-    "Owner password \u2014 MUST be at least 8 characters. REQUIRED when --yes is set; otherwise the CLI prompts for it. WARNING: --password puts the secret in process argv (visible in `ps`, /proc/<pid>/cmdline, and CI logs that echo commands). Prefer the interactive prompt unless your CI runner redacts secrets in command echoes. V1.5: HEYARP_PASSWORD env var support tracked."
+    "Owner password \u2014 MUST be at least 8 characters. REQUIRED when --yes is set; otherwise the CLI prompts for it. WARNING: --password puts the secret in process argv (visible in `ps`, /proc/<pid>/cmdline, and CI logs that echo commands). Prefer the interactive prompt unless your CI runner redacts secrets in command echoes. HEYARP_PASSWORD env var support is tracked."
   ).option(
     "--yes",
     "Strict non-interactive: fail if any required field is still missing after merging flags. With --yes, --password must be supplied explicitly (>= 8 chars).",
@@ -7057,7 +6998,6 @@ function registerRegisterCommand(root) {
     // success prints. Output shape:
     // {did, settlementPublicKeyB58, identityPublicKeyB58,
     //  localStatePath, didDocument}
-    // (V1-alpha: `accountId` parked from the output.)
     // REQUIRES --yes (interactive prompts would corrupt the
     // single-doc contract).
     "Machine-readable mode \u2014 emit `{did, settlementPublicKeyB58, \u2026, didDocument}` JSON instead of human prints. REQUIRES --yes (interactive prompts would corrupt the single-doc JSON output).",
@@ -7083,41 +7023,39 @@ async function runRegister(opts, deps = defaultRegisterDeps) {
     warnIfOrphanHomesPresent();
   }
   const keys = opts.fromKeys ? loadKeysFromFile(opts.fromKeys) : freshKeys();
-  const did = (0, import_sdk16.formatDid)(keys.identityPublicKey);
+  const did = (0, import_sdk22.formatDid)(keys.identityPublicKey);
   if (!opts.json) console.log(import_chalk25.default.dim(`DID will be: ${did}`));
   const answers = await mergeAnswers(opts);
   const scryptSalt = (0, import_node_crypto4.randomBytes)(16);
   if (!opts.json) console.log(import_chalk25.default.dim("Deriving scrypt key, this may take a moment..."));
-  const scryptKey = (0, import_sdk16.deriveScryptKey)(answers.password, new Uint8Array(scryptSalt));
+  const scryptKey = (0, import_sdk22.deriveScryptKey)(answers.password, new Uint8Array(scryptSalt));
   const challenge = await api.issueChallenge("register");
   const challengeBytes = base64UrlNoPadDecode(challenge.challengeB64);
   if (challengeBytes.length !== 32) {
     throw new Error(`Server returned a ${challengeBytes.length}-byte challenge; expected 32`);
   }
-  const challengeSig = (0, import_sdk16.signChallenge)(challengeBytes, keys.identitySecretKey);
-  const identityPublicKeyB58 = (0, import_sdk16.base58btcEncode)(keys.identityPublicKey);
+  const challengeSig = (0, import_sdk22.signChallenge)(challengeBytes, keys.identitySecretKey);
+  const identityPublicKeyB58 = (0, import_sdk22.base58btcEncode)(keys.identityPublicKey);
   await api.submitChallengeResponse({
     challengeId: challenge.challengeId,
     identityPublicKey: identityPublicKeyB58,
     signature: Buffer.from(challengeSig).toString("base64")
   });
-  const settlementPublicKeyB58 = (0, import_sdk16.base58btcEncode)(keys.settlementPublicKey);
-  const scryptSaltId = (0, import_sdk16.uuidV4)();
+  const settlementPublicKeyB58 = (0, import_sdk22.base58btcEncode)(keys.settlementPublicKey);
+  const scryptSaltId = (0, import_sdk22.uuidV4)();
   const payload = {
-    purpose: "ARP-KEY-LINK-v1",
+    purpose: import_sdk22.Purpose.KEY_LINK,
     agent_did: did,
     identity_public_key: identityPublicKeyB58,
     settlement_public_key: settlementPublicKeyB58,
-    owner_signing_method: "scrypt_password_proof",
+    owner_signing_method: import_sdk22.OWNER_SIGNING_METHODS[0],
     link_method: "manual",
-    created_at: (0, import_sdk16.rfc3339)(),
-    nonce: (0, import_sdk16.senderNonce)()
+    created_at: (0, import_sdk22.rfc3339)(),
+    nonce: (0, import_sdk22.senderNonce)()
   };
-  const attestation = (0, import_sdk16.signKeyLinkAttestation)({ payload, scryptKey, scryptSaltId });
+  const attestation = (0, import_sdk22.signKeyLinkAttestation)({ payload, scryptKey, scryptSaltId });
   const body = {
     challengeId: challenge.challengeId,
-    // V1-alpha: accountId parked — server's DTO no longer accepts it.
-    // accountId: answers.accountId,
     identityPublicKey: identityPublicKeyB58,
     settlementPublicKey: settlementPublicKeyB58,
     ownerAttestation: {
@@ -7158,7 +7096,7 @@ async function runRegister(opts, deps = defaultRegisterDeps) {
   try {
     result = await api.register(body, credential.token);
   } catch (err) {
-    if (err instanceof ApiError && (err.payload.code === "AUTH_TOKEN_INVALID" || err.payload.code === "AUTH_TOKEN_REQUIRED")) {
+    if (err instanceof ApiError && (err.payload.code === import_sdk22.CliAuthTokenErrorCodes.INVALID || err.payload.code === import_sdk22.CliAuthTokenErrorCodes.REQUIRED)) {
       throw new Error(
         `register: the stored login token for ${api.serverUrl} was rejected (${err.payload.message}) \u2014 run 'heyarp login' again. Your keys are saved locally; re-running register with --from-keys is safe.`
       );
@@ -7210,20 +7148,11 @@ Local state saved to ${arpHomeDir()}/agents.json (mode 0600).`));
   }
 }
 async function mergeAnswers(opts) {
-  const need = opts.yes ? {
-    password: false,
-    name: false,
-    description: false,
-    tagsCsv: false
-    /* accountId parked V1-alpha */
-  } : {
+  const need = opts.yes ? { password: false, name: false, description: false, tagsCsv: false } : {
     password: opts.password === void 0,
     name: opts.name === void 0,
     description: opts.description === void 0,
     tagsCsv: opts.tag === void 0 || opts.tag.length === 0
-    // V1-alpha: accountId parked. Uncomment + restore the prompt
-    // below when launchpad↔ARP join lands.
-    // accountId: opts.accountId === undefined,
   };
   if (opts.yes) {
     const missing = [];
@@ -7275,7 +7204,6 @@ async function mergeAnswers(opts) {
     password: opts.password ?? prompted.password,
     name: opts.name ?? prompted.name,
     description: opts.description ?? prompted.description ?? "",
-    // accountId, // V1-alpha parked — see RegisterAnswers above.
     tags
   };
 }
@@ -7311,7 +7239,7 @@ function warnIfAgentsAlreadyRegistered(serverOverride) {
   const existing = listAgents().filter((row) => row.serverUrl === targetServer);
   if (existing.length === 0) return;
   const list = existing.map((row) => `   \u2022 ${import_chalk25.default.cyan(row.agent.did)}${row.agent.name ? import_chalk25.default.dim(` (${row.agent.name})`) : ""}`).join("\n");
-  console.log(import_chalk25.default.yellow("\n\u26A0  ~/.arp/agents.json already has agent(s) for this server:"));
+  console.log(import_chalk25.default.yellow("\n\u26A0  ~/.heyarp/agents.json already has agent(s) for this server:"));
   console.log(list);
   console.log(
     import_chalk25.default.dim(
@@ -7324,8 +7252,8 @@ function parseTagsCsv(raw) {
   return raw.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
 }
 function freshKeys() {
-  const identity = (0, import_sdk16.generateKeyPair)();
-  const settlement = (0, import_sdk16.generateKeyPair)();
+  const identity = (0, import_sdk22.generateKeyPair)();
+  const settlement = (0, import_sdk22.generateKeyPair)();
   return {
     identityPublicKey: identity.publicKey,
     identitySecretKey: identity.secretKey,
@@ -7351,9 +7279,9 @@ function loadKeysFromFile(path) {
   if (identitySecret.length !== 32) throw new Error("--from-keys: identitySecretKeyB64 is not a 32-byte Ed25519 seed");
   if (settlementSecret.length !== 32) throw new Error("--from-keys: settlementSecretKeyB64 is not a 32-byte Ed25519 seed");
   return {
-    identityPublicKey: (0, import_sdk16.getPublicKey)(identitySecret),
+    identityPublicKey: (0, import_sdk22.getPublicKey)(identitySecret),
     identitySecretKey: identitySecret,
-    settlementPublicKey: (0, import_sdk16.getPublicKey)(settlementSecret),
+    settlementPublicKey: (0, import_sdk22.getPublicKey)(settlementSecret),
     settlementSecretKey: settlementSecret
   };
 }
@@ -7369,19 +7297,29 @@ function assertJsonRequiresYes(opts) {
 }
 
 // src/commands/relationships.ts
+var import_sdk23 = require("@heyanon-arp/sdk");
 var import_chalk26 = __toESM(require("chalk"));
 init_api();
-var ALLOWED_STATES3 = /* @__PURE__ */ new Set(["pending", "active", "paused", "closed"]);
+var ALLOWED_STATES2 = new Set(import_sdk23.RELATIONSHIP_STATE_NAMES);
 function registerRelationshipsCommand(root) {
   root.command("relationships").description(
     "List relationships <did> belongs to (live + closed pairs, ordered by lastEventAt desc). DID can be passed positionally OR via --from-did; if both are omitted the resolver picks the sole local agent for the server (see `heyarp config set server` + multi-DID disambiguation rules)."
-  ).argument("[did]", "Agent DID (did:arp:...) \u2014 must have local state. Optional when --from-did is given OR exactly one agent is registered for the resolved server.").option("--server <url>", "Override ARP server base URL").option("--state <s>", "Filter by relationship state (pending|active|paused|closed)").option("--limit <n>", "Max relationships to return (1..100)", "20").option("--verbose", "Print the full JSON for each relationship in addition to the table", false).option("--from-did <did>", "Alias for the positional <did> argument \u2014 accepted for consistency with other signed commands. Must match the positional if both are given.").action(async (did, opts) => {
+  ).argument("[did]", "Agent DID (did:arp:...) \u2014 must have local state. Optional when --from-did is given OR exactly one agent is registered for the resolved server.").option("--server <url>", "Override ARP server base URL").option("--state <s>", "Filter by relationship state (pending|active|paused|closed)").option("--limit <n>", "Max relationships to return (1..100)", "20").option("--verbose", "Print the full JSON for each relationship in addition to the table. Mutually exclusive with --json.", false).option(
+    "--json",
+    "Machine-readable mode \u2014 emit the relationships as a single JSON array on stdout (RelationshipPublic[]). Prelude + table move to stderr. Mutually exclusive with --verbose.",
+    false
+  ).option("--from-did <did>", "Alias for the positional <did> argument \u2014 accepted for consistency with other signed commands. Must match the positional if both are given.").action(async (did, opts) => {
     await runRelationships(did, opts);
   });
 }
 async function runRelationships(positionalDid, opts) {
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      "relationships: --verbose and --json are mutually exclusive. --json emits the rows as a clean array; --verbose adds per-row dumps that would break `--json | jq`."
+    );
+  }
   const limit = parseLimit6(opts.limit);
-  const state = parseState3(opts.state);
+  const state = parseState2(opts.state);
   if (positionalDid !== void 0 && opts.fromDid !== void 0 && positionalDid !== opts.fromDid) {
     throw new Error(`relationships: positional <did> (${positionalDid}) and --from-did (${opts.fromDid}) disagree \u2014 pass only one`);
   }
@@ -7389,12 +7327,16 @@ async function runRelationships(positionalDid, opts) {
   const local = explicitDid !== void 0 ? loadAgentOrThrow(opts.server, explicitDid) : resolveSenderAgent("relationships", opts.server, void 0);
   const did = local.did;
   const api = new ArpApiClient(opts.server);
-  console.log(import_chalk26.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk26.default.dim(`Signer: ${local.did}`));
+  progress(opts.json, import_chalk26.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk26.default.dim(`Signer: ${local.did}`));
   const query = { limit };
   if (state) query.state = state;
   const signer = makeSigner(local);
   const rows = await api.listRelationships(did, signer, query);
+  if (opts.json) {
+    jsonOut(rows);
+    return;
+  }
   if (rows.length === 0) {
     console.log(import_chalk26.default.dim("\n(no relationships)"));
     return;
@@ -7422,9 +7364,9 @@ function otherPair(r, selfDid) {
   if (r.pairDidB === selfDid) return r.pairDidA;
   return `${r.pairDidA} \u2194 ${r.pairDidB}`;
 }
-function parseState3(raw) {
+function parseState2(raw) {
   if (raw === void 0) return void 0;
-  if (!ALLOWED_STATES3.has(raw)) {
+  if (!ALLOWED_STATES2.has(raw)) {
     throw new Error(`relationships: --state must be one of pending|active|paused|closed (got '${raw}')`);
   }
   return raw;
@@ -7439,12 +7381,12 @@ function parseLimit6(raw) {
 }
 
 // src/commands/reputation.ts
-var import_sdk17 = require("@heyanon-arp/sdk");
+var import_sdk24 = require("@heyanon-arp/sdk");
 var import_chalk27 = __toESM(require("chalk"));
 init_api();
 function registerReputationCommand(root) {
   root.command("reputation").description("Show an agent's informational reputation (composite + component scores + raw counters). Public, no auth. NOT a money/eligibility gate.").argument("<did>", "did:arp:<base58btc> identifier").option("--server <url>", "Override ARP server base URL").option("--json", "Emit the reputation as JSON on stdout.", false).action(async (did, opts) => {
-    if (!(0, import_sdk17.isValidDid)(did)) {
+    if (!(0, import_sdk24.isValidDid)(did)) {
       throw new Error(`'${did}' is not a syntactically valid did:arp identifier`);
     }
     const api = new ArpApiClient(opts.server);
@@ -7486,44 +7428,53 @@ function bar(score) {
 }
 
 // src/commands/send-handshake.ts
-var import_sdk18 = require("@heyanon-arp/sdk");
+var import_sdk25 = require("@heyanon-arp/sdk");
 var import_chalk28 = __toESM(require("chalk"));
 init_api();
 function registerSendHandshakeCommand(root) {
-  root.command("send-handshake").description("Send a handshake envelope to <recipient-did>. Server creates the relationship row on first contact.").argument("<recipient-did>", "Recipient agent DID (did:arp:...)").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--greeting <s>", "Optional greeting text included in body.content").option("--intent <s>", "Optional intent text included in body.content").option("--ttl <seconds>", "Envelope TTL in seconds (max 86400 = 24h)", "3600").option("--verbose", "Print the full envelope before sending and the full server response", false).action(async (recipientDid, opts) => {
+  root.command("send-handshake").description("Send a handshake envelope to <recipient-did>. Server creates the relationship row on first contact.").argument("<recipient-did>", "Recipient agent DID (did:arp:...)").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--greeting <s>", "Optional greeting text included in body.content").option("--intent <s>", "Optional intent text included in body.content").option("--ttl <seconds>", `Envelope TTL in seconds (max ${import_sdk25.MAX_ENVELOPE_TTL_SECONDS} = 24h)`, "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    "Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, eventId, relationshipId, relationshipEventIndex, serverTimestamp, signedMessageHash, serverEventHash, prevServerEventHash, senderSequence}). The Server/Sender/Recipient prelude moves to stderr so `--json | jq` stays byte-pure. Mutually exclusive with --verbose.",
+    false
+  ).action(async (recipientDid, opts) => {
     await runSendHandshake(recipientDid, opts);
   });
 }
 async function runSendHandshake(recipientDid, opts) {
-  if (!isDid(recipientDid)) {
-    throw new Error(`send-handshake: <recipient-did> must look like 'did:arp:...' (got '${recipientDid}')`);
+  if (!(0, import_sdk25.isValidDid)(recipientDid)) {
+    throw new Error(`send-handshake: <recipient-did> must be a valid did:arp identifier (base58btc-encoded 32-byte Ed25519 pubkey) (got '${recipientDid}')`);
+  }
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      "send-handshake: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds envelope + response dumps that would break `--json | jq`."
+    );
   }
   const ttlSeconds = parseTtl3(opts.ttl);
   const api = new ArpApiClient(opts.server);
-  console.log(import_chalk28.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk28.default.dim(`Server: ${api.serverUrl}`));
   const sender = resolveSenderAgent("send-handshake", opts.server, opts.fromDid);
-  console.log(import_chalk28.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk28.default.dim(`Recipient: ${recipientDid}`));
+  progress(opts.json, import_chalk28.default.dim(`Sender: ${sender.did}`));
+  progress(opts.json, import_chalk28.default.dim(`Recipient: ${recipientDid}`));
   const content = {};
   if (opts.greeting) content.greeting = opts.greeting;
   if (opts.intent) content.intent = opts.intent;
   const body = { type: "handshake", content };
   const nextSequence = (sender.lastSenderSequence ?? 0) + 1;
   const protectedBlock = {
-    protocol_version: "arp/0.1",
-    purpose: import_sdk18.Purpose.ENVELOPE,
-    message_id: (0, import_sdk18.uuidV4)(),
+    protocol_version: import_sdk25.CURRENT_PROTOCOL_VERSION,
+    purpose: import_sdk25.Purpose.ENVELOPE,
+    message_id: (0, import_sdk25.uuidV4)(),
     sender_did: sender.did,
     recipient_did: recipientDid,
     relationship_id: null,
     sender_sequence: nextSequence,
-    sender_nonce: (0, import_sdk18.senderNonce)(),
-    timestamp: (0, import_sdk18.rfc3339)(),
-    expires_at: (0, import_sdk18.expiresAt)(ttlSeconds),
+    sender_nonce: (0, import_sdk25.senderNonce)(),
+    timestamp: (0, import_sdk25.rfc3339)(),
+    expires_at: (0, import_sdk25.expiresAt)(ttlSeconds),
     delivery_id: null
   };
   const signer = makeSigner(sender);
-  const envelope = (0, import_sdk18.signEnvelope)({
+  const envelope = (0, import_sdk25.signEnvelope)({
     protected: protectedBlock,
     body,
     identitySecretKey: signer.identitySecretKey
@@ -7534,6 +7485,21 @@ async function runSendHandshake(recipientDid, opts) {
   }
   const result = await api.ingest(envelope);
   updateAgentLocal(opts.server, sender.did, { lastSenderSequence: nextSequence });
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      action: "handshake",
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp,
+      signedMessageHash: result.signedMessageHash,
+      serverEventHash: result.serverEventHash,
+      prevServerEventHash: result.prevServerEventHash ?? null,
+      senderSequence: nextSequence
+    });
+    return;
+  }
   console.log(import_chalk28.default.green("\nDelivered."));
   console.log(`${import_chalk28.default.bold("Event id")}: ${import_chalk28.default.cyan(result.eventId)}`);
   console.log(`${import_chalk28.default.bold("Relationship id")}: ${import_chalk28.default.cyan(result.relationshipId)}`);
@@ -7561,15 +7527,12 @@ function parseTtl3(raw) {
   }
   return n;
 }
-function isDid(s) {
-  return typeof s === "string" && s.startsWith("did:arp:") && s.length > "did:arp:".length;
-}
 
 // src/commands/send-handshake-response.ts
-var import_sdk19 = require("@heyanon-arp/sdk");
+var import_sdk26 = require("@heyanon-arp/sdk");
 var import_chalk29 = __toESM(require("chalk"));
 init_api();
-var ALLOWED_DECISIONS = /* @__PURE__ */ new Set(["accept", "decline"]);
+var ALLOWED_DECISIONS = new Set(import_sdk26.HANDSHAKE_DECISIONS);
 function registerSendHandshakeResponseCommand(root) {
   root.command("send-handshake-response").description("Accept or decline an inbound handshake from <recipient-did>. Server reuses the existing relationship row.").argument("<recipient-did>", "Recipient agent DID (did:arp:...) \u2014 the original handshake sender").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("--decision <s>", "REQUIRED: accept or decline").option("--notes <s>", "Optional notes included in body.content").option(
     "--reason <code>",
@@ -7577,8 +7540,8 @@ function registerSendHandshakeResponseCommand(root) {
     // We don't use commander's requiredOption because it
     // would fire for the accept path too; validate manually
     // after decision is parsed.
-    `When --decision=decline: required reason code (one of: ${import_sdk19.DECLINE_REASONS.join(", ")}). Carried in body.content.reason.`
-  ).option("--reason-detail <s>", "Optional free-text elaboration alongside --reason (max 512 chars).").option("--ttl <seconds>", "Envelope TTL in seconds (max 86400 = 24h)", "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    `When --decision=decline: required reason code (one of: ${import_sdk26.DECLINE_REASONS.join(", ")}). Carried in body.content.reason.`
+  ).option("--reason-detail <s>", "Optional free-text elaboration alongside --reason (max 512 chars).").option("--ttl <seconds>", `Envelope TTL in seconds (max ${import_sdk26.MAX_ENVELOPE_TTL_SECONDS} = 24h)`, "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
     "--json",
     "Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, decision, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash, prevServerEventHash}; idempotent short-circuit adds {idempotent:true}). Prelude + banners move off stdout; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.",
     false
@@ -7596,13 +7559,13 @@ async function runSendHandshakeResponse(recipientDid, opts) {
       "send-handshake-response: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds envelope + response dumps that would break `--json | jq`."
     );
   }
-  if (!isDid2(recipientDid)) {
-    throw new Error(`send-handshake-response: <recipient-did> must look like 'did:arp:...' (got '${recipientDid}')`);
+  if (!(0, import_sdk26.isValidDid)(recipientDid)) {
+    throw new Error(`send-handshake-response: <recipient-did> must be a valid did:arp identifier (base58btc-encoded 32-byte Ed25519 pubkey) (got '${recipientDid}')`);
   }
   const decision = parseDecision(opts.decision);
   const ttlSeconds = parseTtl4(opts.ttl);
   let declinePayload = null;
-  if (decision === "decline") {
+  if (decision === import_sdk26.HandshakeDecisions.DECLINE) {
     const reason = parseDeclineReason("send-handshake-response", opts.reason);
     const detail = parseReasonDetail("send-handshake-response", opts.reasonDetail);
     declinePayload = detail ? { reason, reasonDetail: detail } : { reason };
@@ -7628,6 +7591,7 @@ async function runSendHandshakeResponse(recipientDid, opts) {
           if (opts.json) {
             jsonOut({
               ok: true,
+              action: "handshake_response",
               idempotent: true,
               decision,
               eventId: previousResponseFromMe.eventId,
@@ -7670,19 +7634,19 @@ async function runSendHandshakeResponse(recipientDid, opts) {
   const body = { type: "handshake_response", content };
   const nextSequence = (sender.lastSenderSequence ?? 0) + 1;
   const protectedBlock = {
-    protocol_version: "arp/0.1",
-    purpose: import_sdk19.Purpose.ENVELOPE,
-    message_id: (0, import_sdk19.uuidV4)(),
+    protocol_version: import_sdk26.CURRENT_PROTOCOL_VERSION,
+    purpose: import_sdk26.Purpose.ENVELOPE,
+    message_id: (0, import_sdk26.uuidV4)(),
     sender_did: sender.did,
     recipient_did: recipientDid,
     relationship_id: null,
     sender_sequence: nextSequence,
-    sender_nonce: (0, import_sdk19.senderNonce)(),
-    timestamp: (0, import_sdk19.rfc3339)(),
-    expires_at: (0, import_sdk19.expiresAt)(ttlSeconds),
+    sender_nonce: (0, import_sdk26.senderNonce)(),
+    timestamp: (0, import_sdk26.rfc3339)(),
+    expires_at: (0, import_sdk26.expiresAt)(ttlSeconds),
     delivery_id: null
   };
-  const envelope = (0, import_sdk19.signEnvelope)({
+  const envelope = (0, import_sdk26.signEnvelope)({
     protected: protectedBlock,
     body,
     identitySecretKey: signer.identitySecretKey
@@ -7696,6 +7660,7 @@ async function runSendHandshakeResponse(recipientDid, opts) {
   if (opts.json) {
     jsonOut({
       ok: true,
+      action: "handshake_response",
       decision,
       eventId: result.eventId,
       relationshipId: result.relationshipId,
@@ -7744,13 +7709,10 @@ function parseTtl4(raw) {
   }
   return n;
 }
-function isDid2(s) {
-  return typeof s === "string" && s.startsWith("did:arp:") && s.length > "did:arp:".length;
-}
 function classifyIdempotencyOutcome(decision, existing) {
   if (!existing) return { kind: "proceed" };
-  if (existing.state === "active") {
-    if (decision === "decline") {
+  if (existing.state === import_sdk26.RelationshipStates.ACTIVE) {
+    if (decision === import_sdk26.HandshakeDecisions.DECLINE) {
       return {
         kind: "error",
         message: `send-handshake-response: relationship ${existing.relationshipId} is already 'active' from a previous ACCEPT. A decline cannot reverse that \u2014 the active relationship is now under FSM control. If you want to terminate, close the relationship explicitly; pass --force to ignore this check and send the decline (which the server will reject with DOM_INVALID_TRANSITION).`
@@ -7758,7 +7720,7 @@ function classifyIdempotencyOutcome(decision, existing) {
     }
     return { kind: "short-circuit" };
   }
-  if (existing.state === "closed") {
+  if (existing.state === import_sdk26.RelationshipStates.CLOSED) {
     return {
       kind: "error",
       message: `send-handshake-response: relationship ${existing.relationshipId} is CLOSED. Cannot respond to handshake on a terminated relationship \u2014 start a fresh handshake instead.`
@@ -7883,8 +7845,7 @@ function registerWhoamiCommand(root) {
     // `--payer-settlement-pubkey` / on-chain ops without a
     // server round-trip. `--local` short-circuits the signed
     // GET, prints just the resolved DID + pubkeys from local
-    // state. (V1-alpha: accountId parked, no longer in --local
-    // output.)
+    // state.
     "Print local-state info only (DID + settlement + identity pubkeys). Skips the signed server fetch \u2014 useful for scripts that need the local pubkey before the server is up, or to grep from a shell without burning a network round-trip.",
     false
   ).option("--json", "JSON output (jq-pipeable). Combines local + server data when --local is unset, or just local when --local is set.", false).action(async (didArg, opts, cmd) => {
@@ -7897,10 +7858,6 @@ function registerWhoamiCommand(root) {
         did: local.did,
         settlementPublicKeyB58: local.settlementPublicKeyB58,
         identityPublicKeyB58: local.identityPublicKeyB58,
-        // V1-alpha: accountId parked — local-state type no
-        // longer carries the field. Uncomment when launchpad↔ARP
-        // join lands.
-        // accountId: local.accountId,
         name: local.name
       };
       if (opts.local) {
@@ -7953,7 +7910,7 @@ function registerWhoamiCommand(root) {
 }
 
 // src/commands/work.ts
-var import_sdk20 = require("@heyanon-arp/sdk");
+var import_sdk27 = require("@heyanon-arp/sdk");
 var import_chalk32 = __toESM(require("chalk"));
 init_api();
 function registerWorkCommands(root) {
@@ -7961,25 +7918,6 @@ function registerWorkCommands(root) {
   registerRequest(cmd);
   registerRespond(cmd);
 }
-var POST_COMMIT_ERROR_CODES3 = /* @__PURE__ */ new Set([
-  "WORK_DELEGATION_NOT_FOUND",
-  "WORK_DELEGATION_NOT_ACTIVE",
-  "WORK_RELATIONSHIP_MISMATCH",
-  "WORK_REQUESTER_NOT_OFFERER",
-  "WORK_REQUEST_ALREADY_EXISTS",
-  "WORK_REQUEST_NOT_FOUND",
-  "WORK_RESPONDER_IS_CALLER",
-  "WORK_INVALID_STATE",
-  // M6 lock-at-accept: the work handler's LOCKED gate emits
-  // `DELEGATION_PENDING_LOCK` (409) when the delegation is funded but
-  // the on-chain lock isn't confirmed yet (state
-  // `pending_lock_finalization`). It fires from the body handler AFTER
-  // the event row is committed — same lifecycle as
-  // `WORK_DELEGATION_NOT_ACTIVE` — so the CLI must advance
-  // `lastSenderSequence`, otherwise a retry once the lock confirms
-  // reuses the consumed sequence and trips `ENV_SEQUENCE_BACKWARDS`.
-  "DELEGATION_PENDING_LOCK"
-]);
 function registerRequest(parent) {
   parent.command("request").description("Send a work_request to <recipient-did> under <delegation-id> (must be ACCEPTED).").argument("<recipient-did>", "Recipient agent DID (the payee \u2014 the OTHER side of the delegation pair)").argument("<delegation-id>", "Parent delegation id (UUID, must be ACCEPTED)").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("--request-id <id>", "Override the auto-generated request id (must be unique within the delegation)").option(
     "--params <json>",
@@ -7987,11 +7925,20 @@ function registerRequest(parent) {
   ).option(
     "--params-file <path>",
     "Read the JSON payload from a file. Mutually exclusive with --params. Use this for any payload large or quote-heavy enough that `--params '{...}'` would fight your shell."
-  ).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, delegationId, opts) => {
+  ).option("--ttl <seconds>", `Envelope TTL in seconds (max ${import_sdk27.MAX_ENVELOPE_TTL_SECONDS} = 24h)`, "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"work_request", requestId, delegationId, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude + reply hints move to stderr; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
+    false
+  ).action(async (recipientDid, delegationId, opts) => {
     await runRequest(recipientDid, delegationId, opts);
   });
 }
 async function runRequest(recipientDid, delegationId, opts) {
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      "work request: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds dumps that would break `--json | jq`."
+    );
+  }
   requireDid3("work request", recipientDid, "<recipient-did>");
   delegationId = requireUuidNormalised3("work request", delegationId, "<delegation-id>");
   const ttlSeconds = parseTtl5("work request", opts.ttl);
@@ -8005,27 +7952,51 @@ async function runRequest(recipientDid, delegationId, opts) {
     params
   };
   const body = { type: "work_request", content };
-  console.log(import_chalk32.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk32.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk32.default.dim(`Recipient: ${recipientDid}`));
-  console.log(import_chalk32.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk32.default.dim(`Request id: ${requestId}`));
+  progress(opts.json, import_chalk32.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk32.default.dim(`Sender: ${sender.did}`));
+  progress(opts.json, import_chalk32.default.dim(`Recipient: ${recipientDid}`));
+  progress(opts.json, import_chalk32.default.dim(`Delegation: ${delegationId}`));
+  progress(opts.json, import_chalk32.default.dim(`Request id: ${requestId}`));
   const result = await sendWorkEnvelope({ api, sender, recipientDid, body, ttlSeconds, verbose: opts.verbose, server: opts.server });
-  printIngestResult3(result);
-  console.log(import_chalk32.default.dim(`
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      action: "work_request",
+      requestId,
+      delegationId,
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp,
+      serverEventHash: result.serverEventHash,
+      prevServerEventHash: result.prevServerEventHash ?? null
+    });
+  } else {
+    printIngestResult3(result);
+    console.log(import_chalk32.default.dim(`
 The payee can reply with:`));
-  console.log(import_chalk32.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --output '<json>'`));
-  console.log(import_chalk32.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --error CODE:message`));
+    console.log(import_chalk32.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --output '<json>'`));
+    console.log(import_chalk32.default.dim(`  heyarp work respond ${result.relationshipId} ${delegationId} ${requestId} --error CODE:message`));
+  }
 }
 function registerRespond(parent) {
   parent.command("respond").description("Send a work_response under <relationship-id> for <delegation-id> / <request-id>. Payee-only.").argument("<relationship-id>", "Relationship UUID").argument("<delegation-id>", "Parent delegation id (UUID)").argument("<request-id>", "Request id supplied on the work_request").option("--server <url>", "Override ARP server base URL").option("--from-did <did>", "Sender DID \u2014 required only if multiple agents are registered against this server").option("--output <json>", "Success payload as a JSON object literal. Mutually exclusive with --error and --output-file.").option(
     "--output-file <path>",
     "Read the success payload from a file. Mutually exclusive with --output and --error. Use this for any payload large or quote-heavy enough to fight your shell."
-  ).option("--error <code:message>", "Failure payload as `CODE:message`. Mutually exclusive with --output / --output-file.").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, requestId, opts) => {
+  ).option("--error <code:message>", "Failure payload as `CODE:message`. Mutually exclusive with --output / --output-file.").option("--ttl <seconds>", "Envelope TTL in seconds", "3600").option("--verbose", "Print the full envelope before sending and the full server response. Mutually exclusive with --json.", false).option(
+    "--json",
+    'Machine-readable mode \u2014 emit a single JSON object on stdout ({ok, action:"work_response", requestId, delegationId, eventId, relationshipId, relationshipEventIndex, serverTimestamp, serverEventHash}). Prelude moves to stderr; on failure stderr carries `{code, message}`. Mutually exclusive with --verbose.',
+    false
+  ).action(async (relationshipId, delegationId, requestId, opts) => {
     await runRespond(relationshipId, delegationId, requestId, opts);
   });
 }
 async function runRespond(relationshipId, delegationId, requestId, opts) {
+  if (opts.verbose && opts.json) {
+    throw new Error(
+      "work respond: --verbose and --json are mutually exclusive. --json emits the structured server response; --verbose adds dumps that would break `--json | jq`."
+    );
+  }
   relationshipId = requireUuidNormalised3("work respond", relationshipId, "<relationship-id>");
   delegationId = requireUuidNormalised3("work respond", delegationId, "<delegation-id>");
   const ttlSeconds = parseTtl5("work respond", opts.ttl);
@@ -8040,33 +8011,48 @@ async function runRespond(relationshipId, delegationId, requestId, opts) {
     ...responsePayload
   };
   const body = { type: "work_response", content };
-  console.log(import_chalk32.default.dim(`Server: ${api.serverUrl}`));
-  console.log(import_chalk32.default.dim(`Sender: ${sender.did}`));
-  console.log(import_chalk32.default.dim(`Recipient: ${recipientDid}`));
-  console.log(import_chalk32.default.dim(`Relationship: ${relationshipId}`));
-  console.log(import_chalk32.default.dim(`Delegation: ${delegationId}`));
-  console.log(import_chalk32.default.dim(`Request id: ${requestId}`));
-  console.log(import_chalk32.default.dim(`Outcome: ${responsePayload.output ? "success" : "error"}`));
+  progress(opts.json, import_chalk32.default.dim(`Server: ${api.serverUrl}`));
+  progress(opts.json, import_chalk32.default.dim(`Sender: ${sender.did}`));
+  progress(opts.json, import_chalk32.default.dim(`Recipient: ${recipientDid}`));
+  progress(opts.json, import_chalk32.default.dim(`Relationship: ${relationshipId}`));
+  progress(opts.json, import_chalk32.default.dim(`Delegation: ${delegationId}`));
+  progress(opts.json, import_chalk32.default.dim(`Request id: ${requestId}`));
+  progress(opts.json, import_chalk32.default.dim(`Outcome: ${responsePayload.output ? "success" : "error"}`));
   const result = await sendWorkEnvelope({ api, sender, recipientDid, body, ttlSeconds, verbose: opts.verbose, server: opts.server });
-  printIngestResult3(result);
+  if (opts.json) {
+    jsonOut({
+      ok: true,
+      action: "work_response",
+      requestId,
+      delegationId,
+      eventId: result.eventId,
+      relationshipId: result.relationshipId,
+      relationshipEventIndex: result.relationshipEventIndex,
+      serverTimestamp: result.serverTimestamp,
+      serverEventHash: result.serverEventHash,
+      prevServerEventHash: result.prevServerEventHash ?? null
+    });
+  } else {
+    printIngestResult3(result);
+  }
 }
 async function sendWorkEnvelope(args) {
   const nextSequence = (args.sender.lastSenderSequence ?? 0) + 1;
   const protectedBlock = {
-    protocol_version: "arp/0.1",
-    purpose: import_sdk20.Purpose.ENVELOPE,
-    message_id: (0, import_sdk20.uuidV4)(),
+    protocol_version: import_sdk27.CURRENT_PROTOCOL_VERSION,
+    purpose: import_sdk27.Purpose.ENVELOPE,
+    message_id: (0, import_sdk27.uuidV4)(),
     sender_did: args.sender.did,
     recipient_did: args.recipientDid,
     relationship_id: null,
     sender_sequence: nextSequence,
-    sender_nonce: (0, import_sdk20.senderNonce)(),
-    timestamp: (0, import_sdk20.rfc3339)(),
-    expires_at: (0, import_sdk20.expiresAt)(args.ttlSeconds),
+    sender_nonce: (0, import_sdk27.senderNonce)(),
+    timestamp: (0, import_sdk27.rfc3339)(),
+    expires_at: (0, import_sdk27.expiresAt)(args.ttlSeconds),
     delivery_id: null
   };
   const signer = makeSigner(args.sender);
-  const envelope = (0, import_sdk20.signEnvelope)({
+  const envelope = (0, import_sdk27.signEnvelope)({
     protected: protectedBlock,
     body: args.body,
     identitySecretKey: signer.identitySecretKey
@@ -8080,7 +8066,7 @@ async function sendWorkEnvelope(args) {
     updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
     return result;
   } catch (err) {
-    if (err instanceof ApiError && POST_COMMIT_ERROR_CODES3.has(err.payload.code)) {
+    if (err instanceof ApiError && (0, import_sdk27.isPostCommitErrorCode)(err.payload.code)) {
       updateAgentLocal(args.server, args.sender.did, { lastSenderSequence: nextSequence });
     }
     throw err;
@@ -8092,7 +8078,7 @@ async function resolveResponseRecipient(cmdName, api, signer, args) {
     const page = await api.listWorkLogs(args.relationshipId, signer, { delegationId: args.delegationId, limit: 100, after });
     const row = page.find((w) => w.requestId === args.requestId);
     if (row) {
-      if (row.state !== "requested") {
+      if (row.state !== import_sdk27.WorkLogStates.REQUESTED) {
         throw new Error(
           `${cmdName}: work_request ${args.requestId} for delegation ${args.delegationId} is already in state '${row.state}' \u2014 only requests in state 'requested' can be responded to.`
         );
@@ -8209,7 +8195,7 @@ function parseTtl5(cmdName, raw) {
 }
 function parseRequestId(cmdName, raw) {
   if (raw === void 0 || raw === "") {
-    return (0, import_sdk20.uuidV4)();
+    return (0, import_sdk27.uuidV4)();
   }
   if (raw.length === 0) {
     throw new Error(`${cmdName}: --request-id must be a non-empty string`);
@@ -8230,9 +8216,10 @@ function requireDid3(cmdName, did, label) {
 }
 
 // src/commands/work-list.ts
+var import_sdk28 = require("@heyanon-arp/sdk");
 var import_chalk33 = __toESM(require("chalk"));
 init_api();
-var ALLOWED_STATES4 = /* @__PURE__ */ new Set(["requested", "responded"]);
+var ALLOWED_STATES3 = new Set(import_sdk28.WORK_LOG_STATES);
 function registerWorkListCommand(root) {
   root.command("work-list").description("List work-log rows for a relationship (one row per (delegationId, requestId), oldest-first)").argument("<relationship-id>", "Relationship UUID").option("--server <url>", "Override ARP server base URL").option("--state <s>", "Filter by exact state (requested|responded)").option("--delegation-id <uuid>", "Narrow to work-logs operating under a specific delegation id").option("--after <id>", "Cursor: pass the previous page's last `id` to fetch the next page").option("--limit <n>", "Max rows to return (1..100)", "20").option("--from-did <did>", "Signer DID \u2014 required only if multiple agents are registered against this server").option(
     "--verbose",
@@ -8253,7 +8240,7 @@ async function runWorkList(relationshipId, opts) {
     );
   }
   const limit = parseLimit7(opts.limit);
-  const state = parseState4(opts.state);
+  const state = parseState3(opts.state);
   const api = new ArpApiClient(opts.server);
   const sender = resolveSenderAgent("work-list", opts.server, opts.fromDid);
   if (!opts.json) {
@@ -8296,26 +8283,26 @@ function formatWorkLogLine(w, selfDid, opts = {}) {
   const delegationPart = opts.fullIds ? w.delegationId : idHead3(w.delegationId);
   const requestPart = opts.fullIds ? w.requestId : truncate3(w.requestId, 16);
   const id = import_chalk33.default.bold(`${delegationPart}/${requestPart}`);
-  const state = colorState3(w.state).padEnd(stateColumnWidth3());
+  const state = colorState2(w.state).padEnd(stateColumnWidth2());
   const peerCallerHead = opts.fullIds ? w.callerDid : didHead5(w.callerDid);
   const peerPayeeHead = opts.fullIds ? w.payeeDid : didHead5(w.payeeDid);
   const direction = w.callerDid === selfDid ? `${import_chalk33.default.bold("me")} \u2192 ${import_chalk33.default.dim(peerPayeeHead)}` : `${import_chalk33.default.dim(peerCallerHead)} \u2192 ${import_chalk33.default.bold("me")}`;
   const outcome = formatOutcome(w);
   return `${id}  ${state}  ${direction}  ${outcome}`;
 }
-function colorState3(s) {
+function colorState2(s) {
   switch (s) {
-    case "requested":
+    case import_sdk28.WorkLogStates.REQUESTED:
       return import_chalk33.default.yellow("requested");
-    case "responded":
+    case import_sdk28.WorkLogStates.RESPONDED:
       return import_chalk33.default.green("responded");
   }
 }
-function stateColumnWidth3() {
+function stateColumnWidth2() {
   return 9;
 }
 function formatOutcome(w) {
-  if (w.state === "requested") return import_chalk33.default.dim("(in flight)");
+  if (w.state === import_sdk28.WorkLogStates.REQUESTED) return import_chalk33.default.dim("(in flight)");
   if (w.responseError) return import_chalk33.default.red(`error ${w.responseError.code}: ${truncate3(w.responseError.message, 32)}`);
   if (w.responseOutput) return import_chalk33.default.cyan("ok");
   return import_chalk33.default.dim("(empty response)");
@@ -8332,9 +8319,9 @@ function truncate3(s, max) {
   if (s.length <= max) return s;
   return `${s.slice(0, max - 3)}...`;
 }
-function parseState4(raw) {
+function parseState3(raw) {
   if (raw === void 0) return void 0;
-  if (!ALLOWED_STATES4.has(raw)) {
+  if (!ALLOWED_STATES3.has(raw)) {
     throw new Error(`work-list: --state must be one of requested|responded (got '${raw}')`);
   }
   return raw;
@@ -8348,6 +8335,43 @@ function parseLimit7(raw) {
   return n;
 }
 
+// src/option-hint.ts
+function unknownOptionHint(program, err) {
+  try {
+    if (err.code !== "commander.unknownOption" || !err.message) return null;
+    const m = /unknown option '([^']+)'/.exec(err.message);
+    if (!m) return null;
+    const raw = m[1];
+    const flag = raw.split("=")[0];
+    const owners = [];
+    const walk = (cmd, path) => {
+      for (const opt of cmd.options) {
+        if (opt.long === flag || opt.short === flag) owners.push(path.join(" "));
+      }
+      for (const sub of cmd.commands) walk(sub, [...path, sub.name()]);
+    };
+    for (const sub of program.commands) walk(sub, [sub.name()]);
+    if (owners.length === 0) return null;
+    owners.sort((a, b) => a.split(" ").length - b.split(" ").length);
+    const argv = process.argv.slice(2);
+    const commandNames = /* @__PURE__ */ new Set();
+    for (const c of program.commands) {
+      commandNames.add(c.name());
+      for (const a of c.aliases()) commandNames.add(a);
+    }
+    const flagIdx = argv.findIndex((t) => t === raw || t.split("=")[0] === flag);
+    const cmdIdx = argv.findIndex((t) => commandNames.has(t));
+    const placedBeforeCommand = cmdIdx === -1 || flagIdx !== -1 && flagIdx < cmdIdx;
+    if (placedBeforeCommand) {
+      return `'${flag}' is a command option, not a global one \u2014 put it AFTER the command (e.g. \`heyarp ${owners[0]} ${flag} \u2026\`), not before it.`;
+    }
+    const list = owners.slice(0, 4).join(", ") + (owners.length > 4 ? ", \u2026" : "");
+    return `'${flag}' isn't valid for that command \u2014 it's an option of: ${list}.`;
+  } catch {
+    return null;
+  }
+}
+
 // src/cli.ts
 async function checkForUpdates() {
   if (package_default.private === true) return;
@@ -8362,7 +8386,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(package_default.version).option("--trace", "Surface stack traces and error details on failure.", false);
+  program.name("heyarp").description("ARP \u2014 Agent Relationship Protocol CLI (talks to apps/arp-server)").version(package_default.version).usage("[global-options] <command> [options]").option("--trace", "Surface stack traces and error details on failure.", false);
   program.exitOverride();
   program.configureOutput({
     writeErr: (str) => {
@@ -8370,6 +8394,7 @@ async function main() {
       process.stderr.write(str);
     }
   });
+  program.addHelpText("after", () => optionPlacementHelpNote());
   program.addHelpText("after", () => onboardingHelpFooter());
   registerConfigCommand(program);
   registerGuideCommand(program);
@@ -8417,10 +8442,13 @@ async function main() {
     const json = process.argv.includes("--json");
     const verbose = process.argv.includes("--trace");
     const exitCode = typeof cerr.exitCode === "number" && cerr.exitCode !== 0 ? cerr.exitCode : 1;
+    const hint = unknownOptionHint(program, cerr);
     if (isCommanderError && !json) {
+      if (hint) process.stderr.write(`hint: ${hint}
+`);
       process.exit(exitCode);
     }
-    emitError(err, { json, verbose });
+    emitError(err, { json, verbose, hint: hint ?? void 0 });
     process.exit(exitCode);
   }
 }