@heyanon-arp/cli 0.0.5 → 0.0.7

package/examples/README.md

@@ -19,14 +19,14 @@ network access or a checkout of the source repository — `npm i -g
 
 | File | Subject | Status |
 |---|---|---|
-| [`worker-template.py`](./worker-template.py) | Autonomous Python worker (handshake → contract → delegation → work → receipt → settlement, all auto-mediated; you fill in `handle_work_request()`) | Reference; FLAT pricing + full-release settlement only. MIT. |
+| [`worker-template.py`](./worker-template.py) | Autonomous Python worker (handshake → delegation → work → receipt → settlement, all auto-mediated; terms ride inline on the offer, you fill in `handle_work_request()`) | Reference; FLAT pricing + full-release settlement only. MIT. |
 
 ## How to use the worker template
 
 1. Register an agent (one-time):
 
    ```bash
-   heyarp register --name "MyWorker" --tag my-service --endpoint-url https://my-agent.example/inbox
+   heyarp register --name "MyWorker" --tag my-service
    ```
 
 2. Copy the template:
@@ -50,10 +50,10 @@ network access or a checkout of the source repository — `npm i -g
    The worker refuses to start while the placeholder is still in place
    (so funds can never accidentally route to the template's default).
    It also refuses if the value does not match your agent's actual
-   settlement key: `settlement auto-sign-and-deliver` signs with the
-   agent's stored key, so a mismatch would route funds to the agent's
-   address rather than the one you set here. The preflight resolves the
-   real key via `heyarp whoami --local` and compares.
+   settlement key: the `receipt propose` escrow settlement step signs
+   with the agent's stored key, so a mismatch would route funds to the
+   agent's address rather than the one you set here. The preflight
+   resolves the real key via `heyarp whoami --local` and compares.
 
 5. Pick your cluster. Defaults to **mainnet-beta** (cluster tag `1`).
    Override for devnet testing:
@@ -88,29 +88,39 @@ Docker / launchd).
 
 ## Caveats
 
-- **Pricing model coverage — FLAT by the template's choice.** The
-  template's `auto_sign_contract` refuses to sign non-flat contracts
-  (a full-release signature on a `usage_based` lock would let the
-  buyer drain it). The settlement step itself —
-  `heyarp settlement auto-sign-and-deliver` — DOES handle
-  both: it auto-detects full (flat) vs partial (`usage_based`, from
-  the receipt's `usage.computed_amount`) release and signs the right
-  digest (`ARP-SOLANA-RELEASE-v1.5` / `ARP-SOLANA-PARTIAL-RELEASE-v1.5`).
-  To support `usage_based` work, TWO changes are needed — not just
-  one: (1) relax the FLAT-only gate in `auto_sign_contract`, AND
-  (2) compute the per-task amount and pass `--computed-amount` on the
-  `receipt propose` call (the settlement command binds the partial
-  release to the receipt's `usage.computed_amount` and refuses to
-  settle a usage_based receipt that lacks it).
-- **Settlement is one command now.** The ~90-line payee settlement
-  ritual (resolve buyer key → derive condition_hash → fetch
-  amount/decimals/deadline → compute expiry → sign → deliver)
-  collapses to `heyarp settlement auto-sign-and-deliver
-  --delegation-id <id> --cluster-tag <0|1>`. It auto-resolves the rest
-  from the delegation id, signs the release digest (reusing `wallet
-  sign-settlement-release`), and delivers via a `settlement_signature`
-  envelope the buyer consumes with `receipt cosign
-  --auto-resolve-payee-sig`. Idempotent — safe to re-run.
+- **Pricing model coverage — FLAT by the template's choice.** Terms
+  ride inline on the delegation offer (there is no separate contract
+  step), so the template's `auto_accept_delegation` reads the offer's
+  `pricingModel` straight off the delegation row and refuses non-flat
+  offers (a full-release signature on a `usage_based` lock would let
+  the buyer drain it). The settlement step folded into `receipt
+  propose` (escrow) DOES handle both: it auto-detects full (flat) vs
+  partial (`usage_based`, from the receipt's `usage.computed_amount`)
+  release and signs the right digest (`ARP-SOLANA-RELEASE-v1.5` /
+  `ARP-SOLANA-PARTIAL-RELEASE-v1.5`). To support `usage_based` work,
+  TWO changes are needed — not just one: (1) relax the FLAT-only gate
+  in `auto_accept_delegation`, AND (2) compute the per-task amount and
+  pass `--computed-amount` on the `receipt propose` call (the folded
+  settlement step binds the partial release to the receipt's
+  `usage.computed_amount` and refuses to settle a usage_based receipt
+  that lacks it).
+- **Settlement is folded into `receipt propose` now.** For an escrow
+  delegation the ~90-line payee settlement ritual (resolve buyer key →
+  derive condition_hash → fetch amount/decimals/deadline → compute
+  expiry → sign → deliver) runs automatically as part of `heyarp
+  receipt propose ... --cluster-tag <0|1>`, right after the receipt
+  commits — so a worker can't forget the separate step (which would
+  strand the buyer's cosign on `ESC_SETTLEMENT_SIGS_MISSING`). It
+  auto-resolves the rest from the delegation id, signs the release
+  digest (reusing `wallet sign-settlement-release`), and delivers via a
+  `settlement_signature` envelope the buyer consumes with `receipt
+  cosign --auto-resolve-payee-sig`. Idempotent — safe to re-run.
+  `--cluster-tag` is REQUIRED for escrow (propose fails fast before
+  committing if it's missing). On partial failure (no RPC / lock not
+  yet visible) the receipt stays committed and the `--json` result's
+  `settlement` block reports `{delivered: false, error, recovery}`;
+  recover with `heyarp receipt send-payee-sig` (the no-RPC primitive)
+  or re-run propose once the lock is reachable.
 - **Policy is hard-coded.** The auto-accept criteria live inline in
   the Python file. A future `heyarp worker run --policy worker-policy.yaml`
   worker daemon would move those into a
@@ -118,7 +128,7 @@ Docker / launchd).
   Until that ships, treat this template as a quick way to validate
   the protocol against your business logic, not as a production
   runner — at minimum, add a price ceiling check in
-  `auto_sign_contract()` before signing.
+  `auto_accept_delegation()` before accepting.
 - **Single-tenant.** Events are processed serially in the SSE loop;
   if you need parallelism, run multiple workers under **distinct DIDs**
   (running two against the same identity will fight over

package/examples/worker-template.py

@@ -4,16 +4,15 @@ ARP Worker Template
 ===================
 Plug-and-play template for building autonomous ARP (Agent Relationship
 Protocol) workers. Drop your business logic into `handle_work_request()`
-— everything else (handshake → contract → delegation → work → receipt
-→ settlement) is auto-mediated.
+— everything else (handshake → delegation → work → receipt →
+settlement) is auto-mediated.
 
 What this template does:
   handshake         → auto-accept
-  contract proposal → auto-sign
-  delegation offer  → auto-accept (idempotent, escrow-aware)
+  delegation offer  → auto-accept (terms inline, idempotent, escrow-aware)
   work_request      → YOUR CUSTOM HANDLER → work_response
-                    → auto receipt propose
-                    → settlement auto-sign-and-deliver (one command)
+                    → auto receipt propose (for escrow, the SAME command
+                      also signs + delivers the payee settlement signature)
 
 Quick start:
   1. Register your agent:  heyarp register --name "MyWorker" --tag my-service ...
@@ -29,13 +28,15 @@ Requirements:
   - Registered ARP agent identity
 
 Scope and limitations (V1 alpha):
-  - **FLAT pricing only — by THIS template's choice.** `auto_sign_contract`
-    below refuses to sign non-flat contracts (a full-release signature on
-    a usage_based lock would let the buyer drain it). The underlying
-    `heyarp settlement auto-sign-and-deliver` command DOES handle partial
-    release (it auto-detects from the receipt's usage.computed_amount), so
-    to support usage_based work, relax the pricing gate in
-    `auto_sign_contract` — the settlement step already does the right thing.
+  - **FLAT pricing only — by THIS template's choice.** `auto_accept_delegation`
+    below refuses to accept non-flat offers (the delegation carries its
+    pricing_model inline now; a full-release signature on a usage_based
+    lock would let the buyer drain it). The folded settlement step in
+    `heyarp receipt propose` (escrow) DOES handle partial release (it
+    auto-detects from the receipt's usage.computed_amount), so to support
+    usage_based work, relax the pricing gate in `auto_accept_delegation`
+    AND pass `--computed-amount` on the propose call — the settlement step
+    then signs the right (partial) digest.
   - **Native SOL only by default.** SPL-token settlement requires
     setting `ARP_MINT_PUBKEY` to the token's mint address (passed through
     to the settlement command).
@@ -140,8 +141,8 @@ _SETTLEMENT_SENTINEL = "REPLACE_WITH_YOUR_SETTLEMENT_PUBKEY"
 MY_SETTLEMENT_PUBKEY = os.environ.get("ARP_SETTLEMENT_PUBKEY", _SETTLEMENT_SENTINEL)
 
 # Cluster tag baked into the on-chain settlement digest. Must match
-# the cluster the contract's `create_lock` was submitted on, otherwise
-# `release_lock` rejects the signature.
+# the cluster the escrow program's `create_lock` was submitted on,
+# otherwise `release_lock` rejects the signature.
 #   0 = devnet
 #   1 = mainnet-beta
 # Default is `1` (mainnet) so a production worker is safe by default;
@@ -229,9 +230,9 @@ def error_code(r: dict) -> str | None:
 # FSM AUTO-RESPONDERS — handle the protocol state machine
 # ═══════════════════════════════════════════════════════════════
 #
-# The ARP work cycle is: handshake → contract → delegation → work →
-# receipt. These handlers auto-accept every non-terminal phase so your
-# worker runs without human intervention.
+# The ARP work cycle is: handshake → delegation → work → receipt.
+# These handlers auto-accept every non-terminal phase so your worker
+# runs without human intervention.
 #
 # All acceptors are IDEMPOTENT — they safely skip already-processed
 # states (SSE re-delivers events, so retries are normal).
@@ -240,14 +241,14 @@ def auto_accept_handshake(sender_did: str):
     """
     Auto-accept an inbound handshake.
 
-    Accepting establishes the relationship and unlocks contract
-    proposals from the buyer.
+    Accepting establishes the relationship and unlocks the delegation
+    offer from the buyer.
     """
     print(f"[worker] Auto-accepting handshake from {sender_did[:30]}...")
     r = shell([
         HEYARP, "send-handshake-response", sender_did,
         "--decision", "accept",
-        "--notes", "Auto-accepted. Ready for work. Send contract proposal.",
+        "--notes", "Auto-accepted. Ready for work. Send a delegation offer.",
         "--json",
     ], timeout=30)
     if r["ok"]:
@@ -289,133 +290,38 @@ def fetch_delegation_row(rel_id: str, delegation_id: str) -> dict | None:
     return None
 
 
-def fetch_contract_row(rel_id: str, contract_id: str) -> dict | None:
-    """
-    Look up the latest-version row for `contract_id` and return it
-    (dict with `state`, `pricingModel`, `version`, ...). Returns None
-    if the row is missing or the server rejects the list call.
-
-    Paginates through `contracts --json` with the maximum page size
-    (100). The CLI default is 20, which would miss a contract on a
-    long-lived relationship — this loop walks until pages exhaust,
-    bounded at 50 pages × 100 rows = 5000 contracts (any real-world
-    relationship beyond that is anomalous and worth manual inspection).
-    """
-    matches = []
-    after = None
-    for _ in range(50):
-        cmd = [HEYARP, "contracts", rel_id, "--json", "--limit", "100"]
-        if after:
-            cmd += ["--after", after]
-        rows = shell_json(cmd, timeout=15)
-        if rows is None:
-            return None
-        if not rows:
-            break
-        matches.extend(r for r in rows if r.get("contractId") == contract_id)
-        if len(rows) < 100:
-            break
-        after = rows[-1].get("id")
-    if not matches:
-        return None
-    # Pick the LATEST version of this contract id (matches the same
-    # rule `escrow derive-condition-hash` uses).
-    return max(matches, key=lambda r: r.get("version", 0))
-
-
-def fetch_contract_pricing(rel_id: str, contract_id: str) -> str:
-    """`pricingModel` of the latest contract version ("" if missing)."""
-    row = fetch_contract_row(rel_id, contract_id)
-    return str(row.get("pricingModel") or "") if row else ""
-
-
-def auto_sign_contract(rel_id: str, contract_id: str):
-    """
-    Auto-sign a contract proposal.
-
-    Pricing-model guard: this template only handles `flat` contracts
-    (full-release settlement). For `usage_based` contracts the
-    on-chain `partial_release` ix needs a different digest
-    (`ARP-SOLANA-PARTIAL-RELEASE-v1.5` + `--partial-payee-amount`)
-    that this template doesn't generate — auto-signing one of those
-    here would let the buyer release the FULL lock amount via the
-    payee signature we ship in `auto_settlement_sign`. **Refuse to
-    sign so funds can't be misrouted.**
-
-    Other policy gates (price ceiling, scope match, deadline window)
-    should go here too — this template signs anything `flat`.
-    """
-    row = fetch_contract_row(rel_id, contract_id)
-    if row is None:
-        # Couldn't fetch the row — refuse rather than guess. The
-        # operator can investigate (e.g. server rejected the list)
-        # and sign manually.
-        print(
-            f"[worker] ✗ refusing to sign contract {contract_id[:20]} — "
-            "couldn't fetch the contract row from contracts --json. "
-            "Run `heyarp contracts <rel-id>` manually to investigate."
-        )
-        return
-    # Proactive idempotency: a contract that's already `active` was
-    # signed by a previous (re-delivered) event. Detecting it here by
-    # STATE is cleaner than reacting to a sign-time error — `contract
-    # sign` with no `--version` fails inside resolveTargetVersion (no
-    # PROPOSED row) with a generic CLI_ERROR that can't be told apart
-    # from a real failure. `replaced` (superseded by a counter) and
-    # `declined` are also terminal — nothing to sign.
-    state = row.get("state")
-    if state in ("active", "replaced", "declined"):
-        print(f"[worker] - contract already {state} (idempotent skip)")
-        return
-    pricing = str(row.get("pricingModel") or "")
-    if pricing != "flat":
-        print(
-            f"[worker] ✗ refusing to sign contract {contract_id[:20]} — "
-            f"pricingModel={pricing!r}; this template only handles `flat`. "
-            "Decline manually or upgrade to a template that signs "
-            "ARP-SOLANA-PARTIAL-RELEASE-v1.5 digests."
-        )
-        return
-    print(f"[worker] Auto-signing FLAT contract {contract_id[:20]}...")
-    # Pin the exact version we just read as PROPOSED. Without
-    # `--version`, `contract sign` auto-resolves the latest PROPOSED
-    # row — and if a concurrent signer flipped it to active in the
-    # gap, that auto-resolve fails with an ambiguous CLI_ERROR (no
-    # PROPOSED row) that's indistinguishable from a real failure.
-    # Pinning the version turns that race into a clean contract-state
-    # reject the handler below recognises.
-    cmd = [HEYARP, "contract", "sign", rel_id, contract_id, "--json"]
-    version = row.get("version")
-    if version is not None:
-        cmd += ["--version", str(version)]
-    r = shell(cmd, timeout=30)
-    if r["ok"]:
-        print("[worker] ✓ contract signed")
-    else:
-        # Rare race: a concurrent signer flipped the pinned version to
-        # active between our state read and our sign. The server
-        # rejects with a contract-state code; anything else is a
-        # genuine failure.
-        code = error_code(r)
-        if code in ("CONTRACT_INVALID_STATE", "DOM_INVALID_TRANSITION"):
-            print("[worker] - contract signed concurrently (race; idempotent skip)")
-        else:
-            print(f"[worker] ✗ contract sign failed: {code or r.get('stderr', '')[:200]}")
-
-
 def auto_accept_delegation(rel_id: str, delegation_id: str):
     """
     Auto-accept a delegation offer.
 
+    Terms are INLINE on the offer (there is no separate contract step):
+    the delegation row carries `pricingModel`, `scopeSummary`,
+    `settlementModel`, rate, amount, currency, and `deadline` — the
+    same terms the `condition_hash` binds to the escrow lock. So both
+    policy gates below (pricing model + settleable deadline) read
+    straight off the delegation row.
+
+    Pricing-model gate: this template only handles `flat` offers
+    (full-release settlement). For `usage_based` offers the on-chain
+    `partial_release` ix needs a different digest
+    (`ARP-SOLANA-PARTIAL-RELEASE-v1.5` + `--partial-payee-amount`).
+    The folded settlement step in `receipt propose` DOES generate it
+    (auto-detected from the receipt's usage.computed_amount), but this
+    template's `receipt propose` call doesn't pass `--computed-amount`,
+    so a usage_based settle would refuse downstream and strand the work
+    — refuse the offer up-front instead. To support usage_based work,
+    relax this gate AND pass `--computed-amount` on the propose call.
+
     Settleability policy gate: this template auto-settles each receipt
-    with `settlement auto-sign-and-deliver`, which derives the payee
-    signature's `expires_at` from the delegation's `deadline` (+ the
-    server-side buffer). A delegation with NO deadline can't be
-    auto-settled — the settle command refuses to fabricate an expiry
-    that might exceed the on-chain lock (a post-commit server reject
-    that burns a sender_sequence). If we accepted a deadline-less offer
-    we'd do the work, propose a receipt, then fail to settle and strand
-    it — so we read the delegation row and refuse deadline-less offers.
+    via the settlement step folded into `receipt propose` (escrow),
+    which derives the payee signature's `expires_at` from the
+    delegation's `deadline` (+ the server-side buffer). A delegation
+    with NO deadline can't be auto-settled — propose refuses to
+    fabricate an expiry that might exceed the on-chain lock (a
+    post-commit server reject that burns a sender_sequence). If we
+    accepted a deadline-less offer we'd do the work, propose a receipt,
+    then fail to settle and strand it — so we read the delegation row
+    and refuse deadline-less offers.
 
     Read-model lag: the offer SSE event can arrive BEFORE the
     `delegations` read-model row materializes, so a missing row is
@@ -449,8 +355,21 @@ def auto_accept_delegation(rel_id: str, delegation_id: str):
             f"[worker] ✗ refusing delegation {delegation_id[:20]} — "
             "no deadline set; this template auto-settles via "
             "deadline+buffer and can't derive a safe settlement expiry. "
-            "Accept manually + run `settlement auto-sign-and-deliver "
-            "--expires-at <unix-secs>` to handle it."
+            "Accept manually + run `heyarp receipt propose ... "
+            "--cluster-tag <0|1> --expires-at <unix-secs>` to handle it."
+        )
+        return
+    # Pricing-model gate: terms ride inline on the offer, so the
+    # delegation row carries `pricingModel` directly (no contract
+    # lookup). Default to 'flat' when absent (no-escrow / unpriced
+    # offers). Refuse usage_based — see the docstring for why.
+    if row is not None and str(row.get("pricingModel") or "flat") != "flat":
+        print(
+            f"[worker] ✗ refusing delegation {delegation_id[:20]} — "
+            f"pricingModel={row.get('pricingModel')!r}; this template only "
+            "handles `flat`. Decline manually, or relax this gate AND pass "
+            "`--computed-amount` on the receipt propose call to support "
+            "ARP-SOLANA-PARTIAL-RELEASE-v1.5 settlement."
         )
         return
     if row is None:
@@ -553,26 +472,32 @@ def handle_work_request(params: dict, rel_id: str, del_id: str,
 # SETTLEMENT
 # ═══════════════════════════════════════════════════════════════
 #
-# After receipt propose, the buyer needs BOTH parties' settlement
-# signatures to release escrow on Solana. The payee (us) must
-# generate its signature and deliver it to the buyer.
-#
-# A single command collapses the whole ~90-line ritual (resolve buyer
-# key → derive condition_hash → fetch amount/decimals/deadline →
-# compute expiry → sign release digest → deliver via
-# settlement_signature envelope) into ONE command:
+# To release escrow on Solana the buyer needs BOTH parties' settlement
+# signatures. The payee (us) must generate its signature and deliver it
+# to the buyer.
 #
-#     heyarp settlement auto-sign-and-deliver --delegation-id <id>
-#
-# The main loop below calls it directly after `receipt propose` —
-# there's nothing left to hand-orchestrate here. The command:
+# This is now FOLDED into `receipt propose`: for an escrow delegation,
+# the SAME `heyarp receipt propose ... --cluster-tag <0|1>` command that
+# commits the receipt also signs + delivers the payee settlement
+# signature right after — collapsing the whole ~90-line ritual (resolve
+# buyer key → derive condition_hash → fetch amount/decimals/deadline →
+# compute expiry → sign release digest → deliver via settlement_signature
+# envelope) so a worker can't forget the separate step. The main loop
+# below just reads the `settlement` block off the propose --json result.
+# The folded step:
 #   - auto-resolves rel-id, buyer DID, condition_hash, amount,
-#     decimals, deadline, and the receipt hashes from --delegation-id
+#     decimals, deadline, and the receipt hashes
 #   - auto-detects FULL (flat) vs PARTIAL (usage_based, from the
 #     receipt's usage.computed_amount) release
 #   - is idempotent (skips when the payee sig was already delivered)
+#   - on partial failure (no RPC / lock not visible) leaves the receipt
+#     committed and reports {delivered: false, error, recovery}; recover
+#     with `heyarp receipt send-payee-sig` (the no-RPC primitive) or
+#     re-run propose once the lock is reachable.
 #
-# Requires `@heyanon-arp/cli` ≥ 0.0.5.
+# Requires `@heyanon-arp/cli` with the folded `receipt propose` escrow
+# settlement (the standalone `settlement auto-sign-and-deliver` command
+# was removed).
 
 
 # ═══════════════════════════════════════════════════════════════
@@ -682,14 +607,14 @@ def _preflight():
             file=sys.stderr,
         )
         sys.exit(2)
-    # Settlement is now signed by `settlement auto-sign-and-deliver`
+    # Settlement is now signed by the `receipt propose` escrow step
     # using the AGENT's stored settlement key (resolved from local
     # heyarp state), NOT the MY_SETTLEMENT_PUBKEY constant. So this
     # value is only meaningful as an assertion: verify it matches the
     # key the worker will actually be paid on, otherwise funds would
     # arrive at the agent's address and you'd only find out after a job
     # settles. Uses the same sole-agent resolution as the settlement
-    # command (run a single worker per DID — see README caveats).
+    # step (run a single worker per DID — see README caveats).
     who = shell_json([HEYARP, "whoami", "--local", "--json"], timeout=15)
     if who is None:
         print(
@@ -705,7 +630,7 @@ def _preflight():
         print(
             f"[worker] FATAL: MY_SETTLEMENT_PUBKEY ({MY_SETTLEMENT_PUBKEY})\n"
             f"  does not match your heyarp agent's settlement key ({agent_key}).\n"
-            "  `settlement auto-sign-and-deliver` signs with the AGENT's key, so\n"
+            "  `receipt propose` (escrow) signs with the AGENT's key, so\n"
             "  funds would route to the agent's address, not the one set here.\n"
             "  Fix ARP_SETTLEMENT_PUBKEY to match `heyarp whoami --local`, or\n"
             "  re-register the agent with the intended settlement key.",
@@ -734,8 +659,8 @@ def main():
     print(f"[worker] Cluster tag:   {CLUSTER_TAG} ({'mainnet-beta' if CLUSTER_TAG == '1' else 'devnet'})")
     print(f"[worker] Mint:          {MINT_PUBKEY} ({'native SOL' if MINT_PUBKEY == NATIVE_SOL_MINT else 'SPL token'})")
     print(f"[worker] Working dir:   {WORK_DIR}")
-    print("[worker] Auto-accept:   handshake ✓ | contract ✓ | delegation ✓")
-    print("[worker] Auto-settle:   receipt → sign → memory → buyer\n")
+    print("[worker] Auto-accept:   handshake ✓ | delegation ✓")
+    print("[worker] Auto-settle:   receipt → sign → deliver → buyer\n")
 
     proc = _spawn_inbox()
 
@@ -776,14 +701,6 @@ def main():
                 print(f"\n[worker] >>> Handshake from {sender_did[:30]}...")
                 auto_accept_handshake(sender_did)
 
-            elif body_type == "contract":
-                content = body.get("content", {})
-                if content.get("action") == "proposal":
-                    rel_id = envelope.get("relationshipId", "")
-                    contract_id = content.get("contract_id", "")
-                    print(f"\n[worker] >>> Contract proposal {contract_id[:20]}...")
-                    auto_sign_contract(rel_id, contract_id)
-
             elif body_type == "delegation":
                 content = body.get("content", {})
                 if content.get("action") == "offer":
@@ -814,53 +731,76 @@ def main():
                         print("[worker] - receipt already exists for delegation, skipping")
                         continue
 
-                    # 4. Auto-propose receipt (--json output).
-                    print("[worker] Auto-proposing receipt...")
-                    receipt = shell_json([
-                        HEYARP, "receipt", "propose", sender,
-                        del_id, "--auto-hashes", "--rel-id", rel_id,
-                        "--request-id", req_id, "--verdict", "accepted",
-                        "--json",
-                    ], timeout=30)
-                    if receipt is None:
-                        print("[worker] - receipt propose failed")
-                        continue
-                    print("[worker] ✓ receipt proposed")
-
-                    # 5. Sign + deliver the payee settlement signature in
-                    #    ONE command. It resolves the buyer key,
-                    #    condition hash, amount/decimals/deadline, and the
-                    #    receipt hashes itself, signs the release digest,
-                    #    and delivers it to the buyer via a
-                    #    settlement_signature envelope. Idempotent:
-                    #    re-running after delivery is a no-op. Auto-detects
-                    #    full (flat) vs partial (usage_based) release.
+                    # 4. Auto-propose receipt AND deliver the payee
+                    #    settlement signature in ONE command (--json output).
+                    #    For an ESCROW delegation, `receipt propose` signs +
+                    #    delivers the payee settlement signature itself right
+                    #    after committing the receipt — the worker can no
+                    #    longer forget a separate step (an undelivered sig
+                    #    would strand the buyer's cosign on
+                    #    ESC_SETTLEMENT_SIGS_MISSING). It resolves the buyer
+                    #    key, condition hash, amount/decimals/deadline, and
+                    #    the receipt hashes itself, signs the release digest,
+                    #    and delivers via a settlement_signature envelope.
+                    #    Idempotent on re-run; auto-detects full (flat) vs
+                    #    partial (usage_based) release.
                     #
-                    #    Pass --receipt-event-hash from the propose result
-                    #    so the command targets the EXACT receipt we just
-                    #    created — required when a delegation has more than
-                    #    one proposed receipt (multiple work requests).
+                    #    --cluster-tag is REQUIRED for an escrow delegation
+                    #    (binds the cluster into the signed release digest;
+                    #    a wrong/defaulted cluster fails at the buyer cosign).
                     #    --fee-bps-at-lock 0: this template targets no-fee
                     #    deployments (see README). The release digest binds
                     #    the lock's fee snapshot; passing 0 makes that
                     #    assumption explicit. On a fee-CHARGING deployment
                     #    you must pass the lock's actual fee_bps_at_lock +
                     #    --fee-recipient-at-lock instead.
-                    settle_cmd = [
-                        HEYARP, "settlement", "auto-sign-and-deliver",
-                        "--delegation-id", del_id, "--rel-id", rel_id,
+                    print("[worker] Auto-proposing receipt (+ delivering settlement sig for escrow)...")
+                    # Use shell() (not shell_json) so we still capture the
+                    # JSON on a PARTIAL-FAILURE exit: an escrow propose that
+                    # commits the receipt but fails to deliver the settlement
+                    # sig (no RPC / lock not yet visible) exits non-zero while
+                    # still emitting the `settlement` block on stdout. Gating
+                    # on `is None` (shell_json) would skip the recovery handler
+                    # below and loop into RECEIPT_ALREADY_EXISTS.
+                    proposal = shell([
+                        HEYARP, "receipt", "propose", sender,
+                        del_id, "--auto-hashes", "--rel-id", rel_id,
+                        "--request-id", req_id, "--verdict", "accepted",
                         "--cluster-tag", CLUSTER_TAG, "--mint-pubkey", MINT_PUBKEY,
                         "--fee-bps-at-lock", "0",
                         "--json",
-                    ]
-                    if receipt.get("receiptEventHash"):
-                        settle_cmd += ["--receipt-event-hash", receipt["receiptEventHash"]]
-                    settle = shell_json(settle_cmd, timeout=30)
-                    if settle is not None:
+                    ], timeout=30)
+                    receipt = None
+                    if proposal["stdout"]:
+                        try:
+                            receipt = json.loads(proposal["stdout"])
+                        except Exception:
+                            receipt = None
+                    if receipt is None:
+                        print(f"[worker] - receipt propose failed: {proposal.get('stderr') or proposal.get('error') or 'no parseable output'}")
+                        continue
+                    print("[worker] ✓ receipt proposed" + ("" if proposal["ok"] else " (settlement step reported a problem — see below)"))
+
+                    # 5. Report the folded settlement outcome. For an escrow
+                    #    delegation `receipt propose` returns a `settlement`
+                    #    block: {delivered, purpose, ...} on success, or
+                    #    {delivered: false, error, recovery} on partial
+                    #    failure (no RPC / lock not yet visible). The receipt
+                    #    is committed either way; on partial failure re-run
+                    #    propose once the lock is reachable, or follow the
+                    #    `recovery` hint (`heyarp receipt send-payee-sig`).
+                    settle = receipt.get("settlement")
+                    if settle is None:
+                        # Prepaid (non-escrow) delegation — no settlement step.
+                        print("[worker] ✓ no settlement step (prepaid delegation)")
+                    elif settle.get("delivered"):
                         tag = " (idempotent)" if settle.get("idempotent") else ""
                         print(f"[worker] ✓ settlement signed + delivered: {settle.get('purpose')}{tag}")
                     else:
-                        print("[worker] - settlement auto-sign-and-deliver failed (see stderr)")
+                        print(
+                            "[worker] ✗ receipt proposed but settlement sig NOT delivered: "
+                            f"{settle.get('error', 'unknown')}. Recover: {settle.get('recovery', '')}"
+                        )
 
                 except Exception as e:
                     print(f"[worker] ✗ Error: {e}")
@@ -877,9 +817,9 @@ def main():
                             pass
 
             else:
-                # Other event types (receipt cosign, memory_delta,
-                # dispute, etc.) — logged but not auto-handled. Add
-                # handlers here if you need them.
+                # Other event types (receipt cosign, dispute, etc.) —
+                # logged but not auto-handled. Add handlers here if you
+                # need them.
                 if body_type:
                     print(f"[worker] event: {body_type}", end="\r")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyanon-arp/cli",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Command-line client for the Agent Relationship Protocol — register agents, sign envelopes, run escrowed work cycles on Solana.",
   "license": "MIT",
   "keywords": [
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "examples",
+    "scripts/postinstall.mjs",
     "LICENSE",
     "README.md"
   ],
@@ -36,7 +37,8 @@
     "commander": "^12.1.0",
     "prompts": "^2.4.2",
     "simple-update-notifier": "^2.0.0",
-    "@heyanon-arp/sdk": "0.0.4"
+    "@heyanon-arp/sdk": "0.0.6",
+    "@heyanon-arp/shield": "0.0.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.2",
@@ -52,6 +54,7 @@
     "build": "tsup",
     "start": "node dist/cli.js",
     "test": "jest --runInBand --detectOpenHandles --forceExit --passWithNoTests",
-    "lint": "biome check . --write"
+    "lint": "biome check . --write",
+    "postinstall": "node scripts/postinstall.mjs"
   }
 }