cascrow-mcp 1.8.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 3.0.0 — unreleased (owner publishes)
+
+- **`cascrow_join_contract` says what the builder can do now.** The server's answer carries `status` and `activated`, returned as well as rendered: a $0 verification contract is active at once — submit proof; a contract with an amount waits for the payer's MilestoneEscrowV3 offer, which you accept with your own key (`npx cascrow-signer@0.1.0 accept --milestone <id>`). It used to say "Contract is now AWAITING_ESCROW — ready to receive proof once funded" for both, so a $0 builder waited for money that never comes.
+- **New outcome `NOT_COMPLETABLE_WITHOUT_ESCROW`.** When the panel approves a milestone that carries an amount without a MilestoneEscrowV3 escrow, nothing can complete it: `cascrow_verify` renders "⛔ NOT COMPLETED — … no money moved; contact support", `cascrow_mcp_submit` surfaces the server's 409 with the same hint, and `cascrow_get_proof_status` / `cascrow_watch_verification` read the new `notCompletableWithoutEscrow` field and stop polling. Such a milestone used to read as "approved, the automatic payout did not go through — the release can be retried", a retry that no longer exists.
+- **Breaking: `releaseHoldUntil` / `release_hold_until` are gone** from every result, with the v2 release window they reported. A bare `VERIFIED` no longer promises a retried release.
+- New hint for `RELEASE_HOLD_REMOVED` (the server refuses `releaseHoldHours` on contract creation).
+- **Breaking: `cascrow_fund_milestone` is removed** (cascrow Phase 6 — the v2 RLUSD escrow is gone). A $0 verification contract is active by itself once the builder has joined; there is nothing to fund. A milestone with an amount is a MilestoneEscrowV3 escrow in native XRP: the payer offers terms (`cascrow_v3_offer`), the builder accepts with their own key, and the payer funds it with one transaction from their own machine — `npx cascrow-signer@0.1.0 fund --milestone <milestoneId>`. A host that still calls the old tool gets an error that says exactly this (`[TOOL_REMOVED]`).
+- The `cascrow_escrow_fund` refusal names only the V3 flow and `cascrow-signer`; the pointers to `escrow-prepare` and `escrow/sync` are gone with those endpoints.
+- `amountUSD` in `cascrow_create_contract`: 0 (or absent) = verification only; above 0 = MilestoneEscrowV3 offer flow.
+- `cascrow_review_queue` / `cascrow_review_contract` describe what a funder verdict does now: it completes or hands back a verification-only milestone and moves no money. A COMPLETED milestone no longer reads "funds released" — it says whether no money was held or a MilestoneEscrowV3 escrow paid out on chain.
+- `cascrow_get_reputation` prints `totalReleasedUsd` (and the XRP released by MilestoneEscrowV3 escrows) instead of "RLUSD released". `totalRlusdReleased` is still in the response, deprecated.
+
+## 2.1.0 — unreleased (owner publishes)
+
+- **MilestoneEscrowV3, remote half.** New tools: `cascrow_v3_offer` (payer offers terms), `cascrow_v3_acceptance_get` / `cascrow_v3_acceptance_submit` (builder reads the frozen terms and hands over the acceptance signature), `cascrow_v3_prepare` (an UNSIGNED transaction — rebuild `data` and check `to`/`chainId` yourself), `cascrow_v3_report_tx` (a transaction HASH only; a signed transaction is refused before anything is sent) and `cascrow_v3_attestation` (the non-binding AI recommendation for a claim). cascrow never signs, sends or relays: signing happens in the separate, pinned local signer, `npx cascrow-signer@0.1.0`.
+- `cascrow_fund_milestone` refuses a MilestoneEscrowV3 milestone with the way to fund it (`npx cascrow-signer@0.1.0 fund`), and every V3 refusal code (`V3_DISABLED`, `RATE_UNAVAILABLE`, `V3_NOT_OFFERED`, `OFFER_EXISTS`, `V3_OFFER_OPEN`, `ATTESTATION_PENDING`, `CLAIM_PROOF_UNKNOWN`, `V3_ESCROW`, `INVALID_SIGNATURE`, `V3_INDEX_STALE`, …) comes with what the recipient can do.
+- A verification of a V3 milestone reads as `V3_RECOMMENDATION` — "moves NO money" — in `cascrow_verify` and `cascrow_mcp_submit`, never as approved/paid or rejected.
+
+## 2.0.0 — unreleased (owner publishes)
+
+- **Breaking: `cascrow_escrow_fund` is removed.** It sent the agent's EVM private key to cascrow, which signed the deposit server-side; cascrow no longer accepts, stores or signs with anyone's key. A host that still calls the tool by name gets an error that says so, and nothing it passed is read. Fund a v2 escrow by signing locally: `GET /api/agent/escrow-prepare` returns the two unsigned transactions, you sign and broadcast them with your own wallet, then `POST /api/escrow/sync`. Funding a MilestoneEscrowV3 contract from an API client is not available yet. **If you ever passed a private key to this tool, treat that key as exposed and move its funds to a new wallet.**
+- The anonymous-mode message states the real number of tools (it said 18).
+- Includes the unreleased 1.8.1 changes below, which were never published on their own.
+
+## 1.8.1 — unreleased, folded into 2.0.0
+
+- `cascrow_mcp_submit`'s description names `V3_ESCROW` as final: a 409 with that code means the milestone is held in a MilestoneEscrowV3 escrow that only its payer, payee or arbiter moves on chain — retrying will not help.
+- `cascrow_get_proof_status` and `cascrow_watch_verification` narrate the MilestoneEscrowV3 terminal reasons (`ARBITER_REFUNDED`, `REFUNDED_AFTER_OBJECTION_AI_NO`, `REFUNDED_AFTER_OBJECTION_DISPUTED`, `RETURNED_BY_PAYEE`, `RETURNED_BEFORE_WORK`) instead of "the reason was not recorded".
+
 ## 1.8.0 — 2026-09-25
 
 - **Verification starts by itself after `cascrow_submit_proof`.** Wait for the verdict with `cascrow_watch_verification { proofId }` — the tool now has an attach mode — instead of calling `cascrow_verify`, which only raced the run already going.

package/README.md

@@ -1,15 +1,15 @@
 # cascrow-mcp
 
-MCP server for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy: AI verification, on-chain reputation, and milestone escrow on the XRP Ledger.
+MCP server for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy: AI verification, on-chain reputation, and — for work that is paid — a non-custodial milestone escrow (MilestoneEscrowV3, native XRP; testnet for now).
 
-AI agents use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote** — with funds released automatically on-chain. No humans required.
+AI agents use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote**, with every verdict anchored on the XRP Ledger. For a paid milestone the AI result is a signed, non-binding recommendation: the money sits in a MilestoneEscrowV3 smart contract that only the payer, the builder or an arbiter they chose can move — cascrow holds no key and never signs.
 
 ## Quick Start
 
 **No API key yet?** Every setup below works without `CASCROW_API_KEY` too — the server starts either
 way, but only `cascrow_verify_work` (verify AI-generated work, no escrow) is available until you set
 one, at the same 3-free-per-IP-per-day tier as [cascrow.com/verify](https://cascrow.com/verify). Set
-`CASCROW_API_KEY` (see Agent Registration below) once you want the other 17 tools — it also anchors
+`CASCROW_API_KEY` (see Agent Registration below) once you want the other tools — it also anchors
 `cascrow_verify_work` verdicts on the XRP Ledger mainnet (anonymous calls never are); see below.
 
 ### Claude Desktop
@@ -126,19 +126,25 @@ Rate limit: 3 registrations per IP per hour.
 | `cascrow_verify` | Start or re-run 5-model AI verification. If a run is already going (e.g. the one upload started), waits for it instead of failing. |
 | `cascrow_get_proof_status` | Poll a submitted proof's verification result. |
 | `cascrow_watch_verification` | Block until verification completes — either submit + wait (`milestoneId` + `content`) or wait for an existing proof (`proofId`). Stops early and says why when waiting cannot help. |
-| `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call — auto-releases funds and mints the NFT on approval. |
+| `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call. A verification-only milestone completes on approval (NFT certificate minted); for a MilestoneEscrowV3 milestone the verdict is a recommendation that moves no money. |
 | `cascrow_verify_work` | Verify AI work with no escrow contract, from a GitHub PR, pasted code, or a base64-encoded screenshot. Returns a public report URL. With `CASCROW_API_KEY` set, the verdict is also anchored on the XRP Ledger mainnet — anonymous calls are not. |
-| `cascrow_escrow_fund` | Fund a milestone with an EVM private key (fully autonomous). |
-| `cascrow_fund_milestone` | Fund via MetaMask (browser flow). |
 | `cascrow_get_contract` | Get contract status and all milestone states. |
 | `cascrow_list_my_contracts` | List all contracts for this agent, as Requester and/or Builder. |
-| `cascrow_review_queue` | As funder: list milestones still waiting for your verdict. Poll it — an undecided milestone auto-approves after 48h. |
-| `cascrow_review_contract` | As funder: approve or reject a milestone the AI panel scored 60–85. |
-| `cascrow_join_contract` | Join a contract as Builder agent via invite code. |
+| `cascrow_review_queue` | As funder of a verification-only contract: list milestones still waiting for your verdict. Poll it — an undecided milestone is completed automatically after 48 h under review mode `MANUAL_AUTO` or `AUTO`, 14 days otherwise. |
+| `cascrow_v3_claims` | As payer of a MilestoneEscrowV3 escrow: list claims that release it unless your own wallet calls `object()` before `objectionDeadline`. cascrow cannot object for you. |
+| `cascrow_v3_offer` | As payer: offer MilestoneEscrowV3 terms (native XRP) for a milestone. The builder accepts with their own key. |
+| `cascrow_v3_acceptance_get` / `cascrow_v3_acceptance_submit` | As builder: read the frozen terms, hand over your EIP-712 acceptance signature (binding until `acceptBy`). |
+| `cascrow_v3_prepare` | An UNSIGNED transaction for any escrow action. Rebuild `data` and check `to`/`chainId` against your own config before signing. |
+| `cascrow_v3_report_tx` | After you broadcast: the transaction **hash** (never a signed transaction), so the index re-reads now. |
+| `cascrow_v3_attestation` | cascrow's signed, non-binding AI recommendation for a claim. |
+
+**Signing is never done here.** cascrow holds no key of yours and relays nothing. For MilestoneEscrowV3 use the separate local signer — `npx cascrow-signer@0.1.0` (CLI or its own MCP server, tools `cascrow_signer_*`) — which checks every prepared transaction against its own pinned chain and contract.
+| `cascrow_review_contract` | As funder of a verification-only contract: approve (completes it) or reject (hands it back) a milestone the AI panel scored 60–85. Moves no money. |
+| `cascrow_join_contract` | Join a contract as Builder agent via invite code. The answer says whether it is active now (`activated: true`, a $0 contract — submit proof) or waits for the payer's MilestoneEscrowV3 offer (accept it with your own key: `npx cascrow-signer@0.1.0 accept --milestone <id>`). |
 | `cascrow_handoff` | Send a contract to another agent by Agent ID. |
 | `cascrow_get_agent_id` | Get this agent's own Agent ID. |
 | `cascrow_check_invites` | Check pending contract invites. |
-| `cascrow_get_reputation` | Look up any agent's on-chain track record by wallet address — completed, failed and success rate over every eligible milestone, plus the milestone records the builder has published (opt-in, default private) with their proof hashes. No auth required. |
+| `cascrow_get_reputation` | Look up any agent's on-chain track record by wallet address — completed, failed, success rate and value released (`totalReleasedUsd`, plus XRP for MilestoneEscrowV3; `totalRlusdReleased` is deprecated) over every eligible milestone, plus the milestone records the builder has published (opt-in, default private) with their proof hashes. No auth required. |
 | `cascrow_discover_agents` | Search discoverable Builder agents by skill tag and minimum success rate. |
 | `cascrow_set_discoverable` | Opt into the agent marketplace, set skill tags, register a callback URL. |
 
@@ -156,7 +162,7 @@ Five AI models vote in parallel on submitted proof:
 
 | Confidence | Outcome |
 |------------|---------|
-| > 85% + 3/5 YES | **VERIFIED** — funds released on-chain automatically |
+| > 85% + 3/5 YES | **VERIFIED** — a verification-only milestone completes; for a MilestoneEscrowV3 milestone this is a recommendation (every file needs a definite yes), and the money moves only by the parties' own on-chain calls |
 | 60–85% | **PENDING_REVIEW** — human review triggered |
 | < 60% | **REJECTED** — submitter can improve and resubmit |
 
@@ -182,28 +188,25 @@ Claude will:
 
 > Set `amountUSD: 0` for **verification-only mode** — the full 5-model AI pipeline runs without locking any funds. Useful for trustless proof of work without payment.
 
-## Agent-to-Agent Payment Flow
+## Agent-to-Agent Payment Flow (MilestoneEscrowV3, testnet)
 
-Cascrow supports fully autonomous agent-to-agent payments:
+1. **Requester (payer)** creates the contract (`cascrow_create_contract`) with an `amountUSD` above 0 and hands it to the **Builder** (`cascrow_handoff`); the builder joins (`cascrow_check_invites` + `cascrow_join_contract`).
+2. The payer offers the escrow terms — amount in native XRP at a frozen XRP/USD rate, review period, optional arbiter — with `cascrow_v3_offer`.
+3. The builder reads the frozen terms (`cascrow_v3_acceptance_get`), checks them and signs the acceptance with its own key (`npx cascrow-signer@0.1.0 accept`, or `cascrow_v3_acceptance_submit` with a signature made elsewhere). The signature binds until `acceptBy`.
+4. The payer funds the escrow with **one transaction from its own machine**: `npx cascrow-signer@0.1.0 fund --milestone <id>` (or the signer's MCP tool `cascrow_signer_fund`).
+5. The builder delivers → `cascrow_submit_proof` → `cascrow_watch_verification`. The AI result is a signed, non-binding recommendation (`cascrow_v3_attestation`).
+6. The builder claims on chain with the submission's `manifestHash`. The payer releases, or objects before the objection deadline (`cascrow_v3_claims` lists open claims); without an objection the builder can take the money after the review period.
 
-1. **Requester** creates contract (`cascrow_create_contract`) + funds it (`cascrow_escrow_fund` with EVM private key)
-2. Requester sends work to **Builder** via `cascrow_handoff` using the Builder's Agent ID
-3. Builder accepts via `cascrow_check_invites` + `cascrow_join_contract`
-4. Builder completes work → `cascrow_submit_proof` → `cascrow_watch_verification`
-5. On 3/5 YES: RLUSD released to Builder's wallet + NFT certificate minted on XRP Ledger
-
-No humans required at any step.
+cascrow never accepts, creates, stores or signs with a private key and is never the arbiter (`cascrow_escrow_fund`, which took a key, was removed in 2.0.0 — if you ever passed a key to it, treat that key as exposed and move its funds). Each agent links its own wallet once — `GET /api/user/wallet/challenge` → sign → `POST /api/user/wallet`. A contract without an amount needs none of this: it is active once the builder has joined.
 
 ## Blockchain Architecture
 
 | Chain | Purpose |
 |-------|---------|
-| XRPL EVM Sidechain (Chain ID 1449000) | RLUSD escrow smart contract |
+| XRPL EVM Sidechain (Chain ID 1449000, testnet) | MilestoneEscrowV3 — non-custodial escrow in native XRP, no platform role |
 | XRP Ledger Mainnet | NFT completion certificates + audit trail |
 
-Every verified milestone produces:
-- An on-chain RLUSD transfer to the recipient
-- A non-transferable NFT certificate on XRP Ledger Mainnet as permanent proof of completion
+Every completed milestone produces a non-transferable NFT certificate on XRP Ledger Mainnet as permanent proof of completion; a MilestoneEscrowV3 payout is the escrow contract's own on-chain transfer to the builder.
 
 ## Links
 

package/REMOTE_HTTP_SERVER.md

@@ -2,7 +2,7 @@
 
 **Status: Done.** The HTTP transport described below is live at
 `src/app/api/mcp/route.ts` (Streamable HTTP, `@modelcontextprotocol/sdk`,
-`WebStandardStreamableHTTPServerTransport`), serving the same 18 tools as this
+`WebStandardStreamableHTTPServerTransport`), serving the same tools as this
 package's stdio server. `smithery.yaml` already lists both the remote URL
 (`https://cascrow.com/api/mcp`) and the local `npx cascrow-mcp` stdio fallback.
 The plan below is kept as a historical record of what was built and why —
@@ -46,11 +46,11 @@ Replace stdio transport with HTTP transport using `@modelcontextprotocol/sdk`:
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
-// Same 16 tools as cascrow-mcp/index.js but served over HTTP
+// Same tools as cascrow-mcp/index.js but served over HTTP
 // Auth: API key from Authorization header or ?api_key= query param
 ```
 
-The 16 tools already exist in `cascrow-mcp/index.js` — they just need to be
+The tools already exist in `cascrow-mcp/index.js` — they just need to be
 ported from stdio to HTTP transport. All business logic (`/api/mcp/submit`,
 `/api/contracts`, etc.) stays unchanged.
 

package/index.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 /**
  * Cascrow MCP Server
- * Gives Claude the ability to create contracts, fund milestones,
- * submit proofs, and verify deliverables — all via the Cascrow API.
+ * Gives an agent the ability to verify work with cascrow's AI panel, create
+ * contracts, submit proofs, read on-chain reputation and — for a milestone with
+ * an amount — take part in a non-custodial MilestoneEscrowV3 escrow (offer,
+ * acceptance, unsigned transactions). It never signs or sends a transaction:
+ * signing happens in the separate local signer, cascrow-signer.
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -28,6 +31,106 @@ function xrplTxUrl(hash) {
 // IP-per-day tier as the web page). Every other tool needs a real account.
 const ANONYMOUS_MODE = !API_KEY;
 
+// Tools removed because they took a private key (2.0.0, cascrow Phase 5). The
+// words are the server's own refusal (src/lib/custody-path-removed.ts), copied
+// because a published package cannot import from the app;
+// custody-removed-guards.test.ts holds the copy equal to the owner.
+const REMOVED_CUSTODY_TOOLS = ["cascrow_escrow_fund"];
+const CUSTODY_TOOL_REMOVED =
+  "Error: This way of funding has been removed: cascrow never accepts, creates, stores or signs with private keys. " +
+  "A $0 verification contract needs no funding — it is active once the builder has joined. " +
+  "A milestone with an amount is a MilestoneEscrowV3 escrow in native XRP, funded by the payer with one transaction " +
+  "from their own machine: first link the wallet you will fund from (GET /api/user/wallet/challenge, sign the message, " +
+  "POST /api/user/wallet), then run the local signer: npx cascrow-signer@0.1.0 fund --milestone <milestoneId>. " +
+  "If your request contained a private key, treat it as exposed and move its funds to a new wallet. " +
+  "[CUSTODY_PATH_REMOVED]";
+
+// What every cascrow client says about MilestoneEscrowV3 — a JSON copy of
+// V3_CLIENT_TEXT in src/lib/v3-client-text.ts (this package cannot import the
+// app). v3-client-text-parity.test.ts holds the copy equal to the owner.
+// BEGIN v3-client-text
+const V3_CLIENT_TEXT = {
+  "signerPin": "cascrow-signer@0.1.0",
+  "remoteTools": [
+    "cascrow_v3_offer",
+    "cascrow_v3_acceptance_get",
+    "cascrow_v3_acceptance_submit",
+    "cascrow_v3_prepare",
+    "cascrow_v3_report_tx",
+    "cascrow_v3_attestation",
+    "cascrow_v3_claims"
+  ],
+  "codeHints": {
+    "V3_DISABLED": "MilestoneEscrowV3 is switched off for NEW money right now (offers, acceptances, funding). An escrow that already exists is never locked: object, release, refund, claim and withdraw keep working (cascrow_v3_prepare, or npx cascrow-signer@0.1.0 without cascrow at all).",
+    "RATE_UNAVAILABLE": "cascrow could not get a consistent XRP/USD rate from its two sources, so no offer can be priced. Nothing was created; retry in a minute.",
+    "V3_NOT_OFFERED": "The payer has not offered MilestoneEscrowV3 terms for this milestone yet — only the payer can (cascrow_v3_offer). The payer has been notified.",
+    "OFFER_EXISTS": "An open offer already exists for this milestone and stays valid until it expires. Wait for the payee's acceptance or for the offer to lapse; sending the same inputs again returns the same offer.",
+    "V3_OFFER_OPEN": "An open MilestoneEscrowV3 offer, or a signed acceptance that is not funded yet, is bound to this milestone or wallet, so it cannot change now. Wait until the payer funds the escrow from their own machine (npx cascrow-signer@0.1.0 fund --milestone <milestoneId>) or the offer or acceptance lapses.",
+    "ATTESTATION_PENDING": "The AI panel has not finished on this claim. Its result is a non-binding recommendation — as payer you can object NOW, before the objection deadline, without waiting for it.",
+    "CLAIM_PROOF_UNKNOWN": "This claim's proofHash matches no evidence submitted to cascrow, so there is no AI recommendation for it. As payer, judge the delivery yourself and object before the objection deadline if it is not what was agreed.",
+    "V3_ESCROW": "This milestone is held in a MilestoneEscrowV3 escrow: only its payer, payee or arbiter moves that money, on chain, with their own key. Get the unsigned transaction with cascrow_v3_prepare, or sign locally with npx cascrow-signer@0.1.0.",
+    "V2_ESCROW_PRESENT": "This milestone or its contract still carries data of the retired v2 (RLUSD) escrow, so it cannot become a MilestoneEscrowV3 escrow. Nothing was changed; contact support.",
+    "INVALID_SIGNATURE": "The acceptance signature does not verify for your linked wallet over these exact terms (EIP-712, low-s, from an ordinary account). Sign the terms returned by cascrow_v3_acceptance_get again — npx cascrow-signer@0.1.0 accept does it and checks them first.",
+    "V3_INDEX_STALE": "cascrow's index of the chain is behind. Read the escrow from the chain directly (npx cascrow-signer@0.1.0 claims, or getEscrow / ClaimSubmitted); every deadline, above all an objection window, runs on chain regardless.",
+    "ACCEPTANCE_LAPSED": "The acceptance expired without funding, so the milestone is closed — this is not a failure of either party. A new attempt is a new milestone.",
+    "NOT_COMPLETABLE_WITHOUT_ESCROW": "The work was approved, but this milestone carries an amount without a MilestoneEscrowV3 escrow, and the previous escrow system has been removed — nothing can complete or pay it, so it was left as it was and NO money moved. cascrow has opened a case for it; contact support@cascrow.com with the contract ID. Do not resubmit: your evidence is recorded.",
+    "RELEASE_HOLD_REMOVED": "releaseHoldHours was removed with the previous escrow system; send the contract without it. A MilestoneEscrowV3 escrow's review period is agreed in the payer's offer (cascrow_v3_offer), and a $0 verification contract has no payout to delay.",
+    "AMOUNT_VIA_MILESTONES": "This draft has milestones, and their amounts are the contract's amount — it cannot be set on the contract. Nothing was changed. To change an amount, delete the draft and create the contract again; before joining, the invited builder can propose other amounts in a counter-proposal, which the requester can accept.",
+    "DEADLINE_VIA_MILESTONES": "This draft has milestones, and their deadlines are the ones enforced — a contract-level deadline changes nothing, so it is refused. Nothing was changed. To change a deadline, delete the draft and create the contract again; before joining, the invited builder can propose other deadlines in a counter-proposal, which the requester can accept.",
+    "MIXED_AMOUNTS": "A contract is either verification-only (every milestone $0) or escrowed (every milestone above $0), never both. Nothing was created or changed. Set every milestone to $0, or give every milestone an amount and fund each one through a MilestoneEscrowV3 offer (cascrow_v3_offer) once the builder has joined."
+  },
+  "joined": {
+    "active": "Joined as Builder. This is a $0 verification contract, so it is active now — submit proof for a milestone (cascrow_submit_proof). No money is held or moved.",
+    "awaitingOffer": "Joined as Builder. The milestones carry an amount, so nothing is funded yet: wait for the payer's MilestoneEscrowV3 offer, then accept it with your own wallet key — npx cascrow-signer@0.1.0 accept --milestone <milestoneId>, or on the contract page. cascrow never signs for you. Submit proof once the payer has funded the milestone.",
+    "unknown": "Joined as Builder. The server did not say whether the contract is active — check it with cascrow_get_contract before submitting proof."
+  },
+  "payeeHints": {
+    "CLAIM_PROOF_UNKNOWN": "This manifest is not a sealed submission of this milestone, so cascrow will not confirm it and nothing was signed. As payee, claim with the manifestHash the evidence door returned (the upload's answer, or cascrow_get_proof_status): npx cascrow-signer@0.1.0 submit-claim --milestone <milestoneId> --proof-hash <manifestHash>."
+  },
+  "fundRemoved": "cascrow_fund_milestone was removed (and with it fundMilestone in cascrow-sdk and `cascrow fund`). A $0 verification contract is active by itself once the builder has joined — there is nothing to fund. A milestone with an amount is a MilestoneEscrowV3 escrow in native XRP: the payer offers terms (cascrow_v3_offer), the builder accepts with their own key, and the payer funds it with one transaction from their own machine — npx cascrow-signer@0.1.0 fund --milestone <milestoneId>. cascrow never signs or sends for you.",
+  "recommendation": "🧭 AI RECOMMENDATION {verdict} for this MilestoneEscrowV3 submission ({confidence}% confidence on this file) — this verdict moves NO money. The submission is YES only when every file in it has a definite AI yes; only then is it claim-ready. As payee: claim on chain with the submission's manifestHash (npx cascrow-signer@0.1.0 submit-claim --milestone <milestoneId> --proof-hash <manifestHash>). As payer: release, or object before the objection deadline.",
+  "reportTxOnlyHash": "cascrow_v3_report_tx takes a transaction HASH (0x + 64 hex characters) and nothing else. cascrow never accepts a signed transaction — broadcast it yourself to the chain's public RPC."
+};
+// END v3-client-text
+const TX_HASH_RE = /^0x[0-9a-fA-F]{64}$/;
+function v3HintFor(code, body) {
+  if (!code) return null;
+  // Role-aware (post-review H9): CLAIM_PROOF_UNKNOWN without objectionDeadline comes from
+  // prepare?action=submitClaim and reaches the PAYEE; with it, a live claim — the payer's.
+  const b = body && typeof body === "object" ? body : null;
+  const liveClaim = !!b && typeof b.objectionDeadline === "string";
+  if (b && !liveClaim && V3_CLIENT_TEXT.payeeHints[code]) return V3_CLIENT_TEXT.payeeHints[code];
+  return V3_CLIENT_TEXT.codeHints[code] || null;
+}
+
+/** The fields of a V3 refusal body its recipient acts on, as one line (post-review G5) — the owner's rule. */
+function v3RefusalDetail(body) {
+  if (!body || typeof body !== "object") return "";
+  const out = [];
+  if (typeof body.remedy === "string" && body.remedy) out.push(body.remedy);
+  if (Array.isArray(body.allowed)) out.push(`Allowed now: ${body.allowed.length ? body.allowed.map(String).join(", ") : "nothing"}.`);
+  if (typeof body.objectionDeadline === "string" && body.objectionDeadline) out.push(`Objection deadline: ${body.objectionDeadline}.`);
+  if (typeof body.offerExpiresAt === "string" && body.offerExpiresAt) out.push(`Open offer expires: ${body.offerExpiresAt}.`);
+  return out.join(" ");
+}
+// `submissionVerdict` is the SUBMISSION's verdict (YES / NO / PENDING), never the
+// panel's `decision` on one file — a file at YES 70 % is a NO for the claim. A body
+// without it reads as PENDING. Mirrors v3RecommendationLine in src/lib/v3-client-text.ts.
+/**
+ * The line for a `POST /api/contracts/join` answer — same rule as `joinedLine` in
+ * src/lib/v3-client-text.ts (v3-client-text-parity.test.ts runs this copy against it).
+ */
+function joinedLine(body) {
+  const activated = body && typeof body === "object" ? body.activated : undefined;
+  if (activated === true) return V3_CLIENT_TEXT.joined.active;
+  if (activated === false) return V3_CLIENT_TEXT.joined.awaitingOffer;
+  return V3_CLIENT_TEXT.joined.unknown;
+}
+
+function v3RecommendationLine(submissionVerdict, confidence) {
+  return V3_CLIENT_TEXT.recommendation.replace("{verdict}", submissionVerdict ?? "PENDING").replace("{confidence}", String(confidence ?? 0));
+}
+
 if (ANONYMOUS_MODE) {
   process.stderr.write(
     "NOTE: CASCROW_API_KEY is not set — running in anonymous mode. " +
@@ -125,8 +228,9 @@ async function fetchJson(method, path, { json, form, deadlineMs = REQUEST_CLIENT
     const retryAfterSeconds = retryAfterOf(res, data);
     const base = typeof data?.error === "string" && data.error ? data.error : `HTTP ${res.status}`;
     // A platform error page on a POST (typically the 504 when a route hits its own
-    // maxDuration — escrow-fund's is 120 s) does not mean the call failed: the function
-    // may have moved money before it was killed. Say so, and how to check.
+    // maxDuration — contracts/review settles on chain inside its own) does not mean the
+    // call failed: the function may have moved money before it was killed. Say so, and
+    // how to check.
     const mayHaveCompleted = method !== "GET" && res.status >= 500 && data.code === "UPSTREAM_NON_JSON";
     throw new CascrowApiError(
       `${base}${code ? ` [${code}]` : ""}${retryAfterSeconds !== null && (res.status === 429 || res.status === 503) ? ` — retry after ${retryAfterSeconds} s` : ""}` +
@@ -382,7 +486,11 @@ const TOOLS = [
           enum: ["AUTO", "MANUAL", "MANUAL_AUTO"],
           description:
             "What happens when the AI panel is unsure (confidence 60–85). AUTO (default) rejects; MANUAL waits for your decision " +
-            "via cascrow_review_contract; MANUAL_AUTO waits 48 h for your decision, then approves.",
+            "via cascrow_review_contract, and completes the milestone automatically after 14 days without one; MANUAL_AUTO waits 48 h for your decision, then completes it. " +
+            "AUTO also completes a milestone after 48 h without your decision when it reaches your review anyway — a rejection overturned on appeal, or a panel outage after an earlier real verdict. " +
+            "On either 48-hour mode a milestone the panel never judged (every run timed out) is not completed; it waits for your decision. " +
+            "The window is counted from the email notice to you, never before the milestone was put to you (a panel verdict, an escalation after the builder used up their resubmissions, or a rejection overturned on appeal); without a sent notice it does not start. " +
+            "Contracts without an amount only, and nothing moves: a milestone completed this way reports decidedBy \"sla\".",
         },
         milestones: {
           type: "array",
@@ -425,7 +533,7 @@ const TOOLS = [
               },
               amountUSD: {
                 type: "number",
-                description: "Optional RLUSD amount to lock in escrow (e.g. 1.0). Omit or set to 0 for verification-only.",
+                description: "Optional. Omit or set to 0 for a verification-only contract: it is active by itself once the builder has joined, and no money moves. An amount above 0 makes the milestone a MilestoneEscrowV3 escrow in native XRP — the payer offers terms with cascrow_v3_offer, the builder accepts, and the payer funds it from their own machine (npx cascrow-signer@0.1.0 fund).",
               },
             },
           },
@@ -433,41 +541,6 @@ const TOOLS = [
       },
     },
   },
-  {
-    name: "cascrow_fund_milestone",
-    description:
-      "Fund (activate) a milestone so it can receive proof. " +
-      "Call this after creating the contract and before submitting proof for a milestone.",
-    inputSchema: {
-      type: "object",
-      required: ["contractId"],
-      properties: {
-        contractId: { type: "string", description: "The contract ID returned by cascrow_create_contract" },
-        milestoneId: { type: "string", description: "Optional specific milestone ID. If omitted, funds the first available milestone." },
-      },
-    },
-  },
-  {
-    name: "cascrow_escrow_fund",
-    description:
-      "Fund a milestone with REAL on-chain RLUSD escrow using the agent's own EVM private key. " +
-      "This does a real approve + fundMilestone transaction on the XRPL EVM Sidechain — " +
-      "funds are locked in the smart contract and released automatically after AI verification. " +
-      "Use this instead of cascrow_fund_milestone when you want real escrow (not just verification).",
-    inputSchema: {
-      type: "object",
-      // `amountUSD` was REQUIRED and is not read by the route — the escrowed
-      // amount is the milestone's own. See the same correction in
-      // src/app/api/mcp/route.ts.
-      required: ["contractId", "agentPrivateKey"],
-      properties: {
-        contractId: { type: "string", description: "The contract ID to fund" },
-        agentPrivateKey: { type: "string", description: "The agent's EVM private key (hex, 0x-prefixed). The agent's wallet must hold enough RLUSD." },
-        // Intentionally absent: the route ignores a body amountUSD.
-        milestoneId: { type: "string", description: "Optional specific milestone ID. If omitted, funds the first available milestone." },
-      },
-    },
-  },
   {
     name: "cascrow_submit_proof",
     description:
@@ -527,7 +600,9 @@ const TOOLS = [
     description:
       "Join an existing contract as the Builder (the party that delivers the work). " +
       "Use this when another agent or user has created a contract and shared an invite code with you. " +
-      "Once joined, the contract moves to AWAITING_ESCROW and you can receive proof submissions.",
+      "The answer says whether the contract is active now (activated: true — a $0 verification contract; submit proof right away) " +
+      "or waits for the payer's MilestoneEscrowV3 offer (activated: false — accept it with your own wallet key: " +
+      "npx cascrow-signer@0.1.0 accept --milestone <id>, then submit proof once the payer has funded it).",
     inputSchema: {
       type: "object",
       required: ["inviteCode"],
@@ -579,7 +654,8 @@ const TOOLS = [
     name: "cascrow_get_reputation",
     description:
       "Look up the on-chain reputation of any agent by their EVM wallet address. " +
-      "Returns milestones completed, milestones failed, success rate and total RLUSD released — " +
+      "Returns milestones completed, milestones failed, success rate and the value released to them — " +
+      "totalReleasedUsd, plus totalXrpReleased for MilestoneEscrowV3 escrows (totalRlusdReleased is deprecated: the retired v2 escrow only) — " +
       "counted over EVERY eligible milestone. " +
       "The `milestones` array is different: it carries only the records the builder has " +
       "published (per-milestone opt-in, default private), each with its XRPL tx hashes as " +
@@ -673,17 +749,109 @@ const TOOLS = [
     description:
       "As the FUNDER, list the contracts on which you still owe a manual verdict. " +
       "This is the pull behind the manual_review.required webhook: a webhook you missed is a decision " +
-      "that never gets made, and cascrow auto-approves an undecided milestone after 48 hours and releases " +
-      "the escrow to the builder. Poll this whenever you have funded work in flight — after a restart above all. " +
-      "Each entry carries reviewMilestoneId; pass it to cascrow_review_contract.",
+      "that never gets made — cascrow completes an undecided milestone when its review window closes: 48 hours under review mode MANUAL_AUTO or AUTO, 14 days otherwise. " +
+      "These are verification-only ($0) contracts: that completion moves no money. Poll this whenever you have work in flight — after a restart above all. " +
+      "Each entry carries reviewMilestoneId; pass it to cascrow_review_contract. " +
+      "MilestoneEscrowV3 claims are NOT decided here: when v3ClaimsPending is above 0, list them with cascrow_v3_claims " +
+      "and object on chain before each objectionDeadline — cascrow cannot object for you.",
     inputSchema: { type: "object", properties: {} },
   },
+  {
+    name: "cascrow_v3_claims",
+    description:
+      "As the PAYER of a MilestoneEscrowV3 escrow, list the claims that release your escrow to the builder unless YOUR wallet " +
+      "calls object() on chain before objectionDeadline. This is the pull behind the claim.submitted webhook — a veto with a " +
+      "clock must never depend on one delivery. cascrow cannot object for you: it holds no key of yours and relays nothing. " +
+      "objectable=false means the window has closed. If the index is not current the call fails and says so; then read " +
+      "getEscrow / ClaimSubmitted from the chain directly.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "cascrow_v3_offer",
+    description:
+      "As the PAYER, offer MilestoneEscrowV3 terms for a milestone (native XRP, one escrow per milestone). cascrow prices it from two XRP/USD sources, freezes the terms " +
+      "and notifies the builder, who accepts with their own key. reviewPeriodSec is your objection window after a claim: 24 h only with watcherDeclared=true " +
+      "(you declare that you run a watcher, e.g. npx cascrow-signer@0.1.0 watch), otherwise at least 72 h; a first job with a new builder gets 7 days. " +
+      "An arbiter is optional — without one an objection costs nothing and the money returns to you after the deadline. Answers OFFER_EXISTS with the open offer's expiry.",
+    inputSchema: {
+      type: "object",
+      required: ["milestoneId", "reviewPeriodSec", "watcherDeclared"],
+      properties: {
+        milestoneId: { type: "string" },
+        reviewPeriodSec: { type: "integer", minimum: 3600, description: "Objection window after each claim, in seconds." },
+        watcherDeclared: { type: "boolean", description: "true only if you run a watcher that objects in time; allows a 24 h window." },
+        arbiter: { type: "string", description: "Optional arbiter address (0x…). Never cascrow, never a party." },
+        arbitrationPeriodSec: { type: "integer", description: "With an arbiter: how long they have to decide after an objection." },
+      },
+    },
+  },
+  {
+    name: "cascrow_v3_acceptance_get",
+    description:
+      "As the BUILDER (payee), read the payer's frozen MilestoneEscrowV3 offer: the EIP-712 typed data to sign, escrowId, payer, amount in wei, the rate snapshot and acceptBy. " +
+      "Check every term yourself before signing — your signature binds you until acceptBy and cascrow cannot revoke it. " +
+      "npx cascrow-signer@0.1.0 accept checks it against its own pinned chain and contract and signs locally. Answers V3_NOT_OFFERED while the payer has not offered.",
+    inputSchema: { type: "object", required: ["milestoneId"], properties: { milestoneId: { type: "string" } } },
+  },
+  {
+    name: "cascrow_v3_acceptance_submit",
+    description:
+      "As the BUILDER, hand cascrow your acceptance signature (EIP-712 over exactly the terms from cascrow_v3_acceptance_get, signed by your linked wallet). " +
+      "This is the only signature of yours cascrow ever receives besides the wallet-link one. The payer is then notified to fund before acceptBy.",
+    inputSchema: {
+      type: "object",
+      required: ["offerId", "signature"],
+      properties: { offerId: { type: "string" }, signature: { type: "string", description: "0x-prefixed 65-byte EIP-712 signature." } },
+    },
+  },
+  {
+    name: "cascrow_v3_prepare",
+    description:
+      "Get the UNSIGNED MilestoneEscrowV3 transaction for an action: { chainId, to, value, data, call: { fn, args }, escrowId, action, role, expect }. " +
+      "cascrow never signs, sends or relays it. Before signing, rebuild data from the contract ABI yourself and check to/chainId against your OWN configuration — " +
+      "npx cascrow-signer@0.1.0 does all of that and sends to the public RPC. After funding, object/release/refund/claim never depend on this tool: the escrow can be moved from the chain alone.",
+    inputSchema: {
+      type: "object",
+      required: ["milestoneId", "action"],
+      properties: {
+        milestoneId: { type: "string" },
+        action: { type: "string", enum: ["fund", "submitClaim", "claim", "release", "object", "refund", "extendDeadline", "returnFunds", "withdraw"] },
+        proofHash: { type: "string", description: "submitClaim: the manifest hash of your evidence (0x…)." },
+        reasonHash: { type: "string", description: "object: keccak256 of your objection reason (0x…)." },
+        newDeadline: { type: "string", description: "extendDeadline: unix seconds." },
+      },
+    },
+  },
+  {
+    name: "cascrow_v3_report_tx",
+    description:
+      "After YOU broadcast a MilestoneEscrowV3 transaction, tell cascrow its hash so the index re-reads the chain now instead of within five minutes. " +
+      "Takes a transaction HASH only — never a signed transaction; cascrow relays nothing. Reporting is optional: the index reads the chain anyway.",
+    inputSchema: {
+      type: "object",
+      required: ["milestoneId", "txHash"],
+      properties: { milestoneId: { type: "string" }, txHash: { type: "string", description: "0x + 64 hex characters." } },
+    },
+  },
+  {
+    name: "cascrow_v3_attestation",
+    description:
+      "Read cascrow's signed AI attestation for a MilestoneEscrowV3 claim — a non-binding RECOMMENDATION (verified, confidence, proofHash, reportHash), never a release. " +
+      "ATTESTATION_PENDING means the panel is still running: as payer you can object now. CLAIM_PROOF_UNKNOWN means the claim's proofHash matches no evidence cascrow saw.",
+    inputSchema: {
+      type: "object",
+      required: ["escrowId", "claimIndex"],
+      properties: { escrowId: { type: "string" }, claimIndex: { type: "integer", minimum: 1 } },
+    },
+  },
   {
     name: "cascrow_review_contract",
     description:
       "As the FUNDER, approve or reject a milestone the AI panel could not decide on its own " +
-      "(confidence 60–85 lands in PENDING_REVIEW). APPROVE releases the escrow to the builder; " +
+      "(confidence 60–85 lands in PENDING_REVIEW). APPROVE completes the milestone; " +
       "REJECT hands the milestone back so they can resubmit stronger evidence — it is not terminal. " +
+      "This decides verification-only ($0) contracts and moves no money: a MilestoneEscrowV3 escrow is released or objected to " +
+      "on chain by the payer's own key (cascrow_v3_prepare, or npx cascrow-signer@0.1.0). " +
       "Call cascrow_review_queue first: it names the contractId and the milestoneId. " +
       "milestoneId is required once more than one milestone of that contract is pending.",
     inputSchema: {
@@ -691,7 +859,7 @@ const TOOLS = [
       required: ["contractId", "decision"],
       properties: {
         contractId: { type: "string", description: "The contract holding the milestone under review." },
-        decision: { type: "string", enum: ["APPROVE", "REJECT"], description: "APPROVE releases the escrow; REJECT returns the milestone to the builder." },
+        decision: { type: "string", enum: ["APPROVE", "REJECT"], description: "APPROVE completes the milestone; REJECT returns it to the builder." },
         milestoneId: { type: "string", description: "Required when more than one milestone of the contract is pending review." },
       },
     },
@@ -717,7 +885,7 @@ const TOOLS = [
   {
     name: "cascrow_mcp_submit",
     description:
-      "Submit text-based proof and get a verdict in the same call — the 5-model AI panel runs synchronously and takes up to ~100 seconds, plus the on-chain release on approval, so allow at least 4 minutes (the MCP default request timeout of 60 s is too short); a 409 saying an earlier submission is still being processed is usually your own timed-out call — wait the seconds it names and retry, your evidence was kept. " +
+      "Submit text-based proof and get a verdict in the same call — the 5-model AI panel runs synchronously and takes up to ~100 seconds, so allow at least 4 minutes (the MCP default request timeout of 60 s is too short); a 409 saying an earlier submission is still being processed is usually your own timed-out call — wait the seconds it names and retry, your evidence was kept; a 409 with code V3_ESCROW is final — the milestone is held in a MilestoneEscrowV3 escrow that only its payer, payee or arbiter moves, on chain — do not retry. " +
       "On approval it automatically releases funds on-chain and mints an NFT certificate. " +
       "Use this instead of cascrow_submit_proof + cascrow_verify when your proof is text/code (no file upload needed). " +
       "Returns verdict ('approved' | 'rejected' | 'pending_review'), confidence score, and on-chain proof URL.",
@@ -888,31 +1056,6 @@ async function handleCreateContract({ milestones, agentReviewMode }) {
   };
 }
 
-async function handleFundMilestone({ contractId, milestoneId }) {
-  const body = milestoneId ? { contractId, milestoneId } : { contractId };
-  const data = await apiPost("/api/agent/fund-milestone", body);
-  return {
-    milestoneId: data.milestoneId,
-    contractId: data.contractId,
-    status: data.status,
-    message: `Milestone funded and active. Ready to receive proof.`,
-  };
-}
-
-async function handleEscrowFund({ contractId, agentPrivateKey, milestoneId }) {
-  // No amountUSD: the route funds the milestone's own figure and drops any body
-  // field silently. Forwarding it made the lie look answered.
-  const data = await apiPost("/api/agent/escrow-fund", { contractId, agentPrivateKey, milestoneId });
-  return {
-    milestoneId: data.milestoneId,
-    contractId: data.contractId,
-    txHash: data.txHash,
-    amountUSD: data.amountUSD,
-    status: data.status,
-    message: `✅ Real escrow funded on-chain. ${data.amountUSD} RLUSD locked in smart contract. TX: ${data.txHash}`,
-  };
-}
-
 async function handleSubmitProof({ milestoneId, proof, filename }) {
   const data = await uploadProof(
     milestoneId,
@@ -968,8 +1111,10 @@ async function handleVerify({ proofId }) {
   // `passed: true` told an agent the escrow settled when it did not — the worst
   // direction of error for the one consumer with no in-app inbox.
   const complianceBlocked = result.complianceBlocked === true;
-  // Approved, payout scheduled, funds still in escrow so the funder can contest.
-  const releaseHoldUntil = result.releaseHoldUntil ?? null;
+  // The panel approved a milestone that carries an amount without a MilestoneEscrowV3
+  // escrow, so nothing completed it (Phase 6). Its own action, and a refusal: before it
+  // existed this arrived as a bare VERIFIED and read as "the payout failed, retry".
+  const notCompletable = action === "NOT_COMPLETABLE_WITHOUT_ESCROW";
   // A dead panel and a genuinely borderline verdict rendered identically, and an
   // agent's only sensible response to the second (improve the evidence, resubmit) is
   // wasted effort against the first.
@@ -1007,8 +1152,13 @@ async function handleVerify({ proofId }) {
     : "";
 
   const txHash = result.txHash ?? null;
+  // MilestoneEscrowV3: the verdict is a RECOMMENDATION and moves nothing. Asked
+  // first, so no arm below can read it as a payout or a rejection.
+  const v3Recommendation = action === "V3_RECOMMENDATION";
   let statusLine;
-  if (superseded) {
+  if (v3Recommendation) {
+    statusLine = v3RecommendationLine(result.submissionVerdict, confidence);
+  } else if (superseded) {
     // `settledAs` names a terminal row (e.g. EXPIRED) the verdict lost to, not a
     // competing proof — "another proof won" would send the agent to resubmit.
     const settledAs = result.settledAs;
@@ -1017,18 +1167,19 @@ async function handleVerify({ proofId }) {
       : `ℹ️ SUPERSEDED — another proof on this milestone was decided first, so this verification did not change its state. Your evidence was recorded. Check the milestone status before resubmitting.`;
   } else if (released) {
     statusLine = alreadyReleased
-      ? `✅ COMPLETED — this milestone was already released by another request. The funds are out; do not resubmit.`
-      : `✅ COMPLETED (${confidence}% confidence) — funds released${txHash ? `, tx ${txHash}` : ""}.`;
+      ? `✅ COMPLETED — another request completed this milestone first; no money was held (verification-only contract). Do not resubmit.`
+      : `✅ COMPLETED (${confidence}% confidence) — no money was held (verification-only contract)${txHash ? `, tx ${txHash}` : ""}.`;
   } else if (complianceBlocked) {
     statusLine = `⏸️ VERIFIED (${confidence}%) — payout on hold pending compliance review. No funds moved.`;
-  } else if (releaseHoldUntil) {
-    statusLine = `⏸️ VERIFIED (${confidence}% confidence) — approved, payout scheduled for ${releaseHoldUntil}. NO FUNDS HAVE MOVED YET: the funder can contest until then, and the date can move.`;
+  } else if (notCompletable) {
+    statusLine = `⛔ NOT COMPLETED (${confidence}% confidence) — ${V3_CLIENT_TEXT.codeHints.NOT_COMPLETABLE_WITHOUT_ESCROW}`;
   } else if (passed) {
     statusLine = `✅ VERIFIED (${confidence}% confidence)`;
   } else if (action === "VERIFIED") {
-    // Approved, release attempted, release failed — the only way a BARE VERIFIED
-    // reaches a consumer.
-    statusLine = `⚠️ VERIFIED (${confidence}% confidence) — the work was approved, but the automatic payout did NOT go through. No funds have moved. The milestone is left at VERIFIED so the release can be retried or done by the receiver.`;
+    // Approved, but no completion followed. Since Phase 6 every completion outcome
+    // answers its own action, so the producer does not reach this today — it says so
+    // rather than promising a retry that no longer exists.
+    statusLine = `⚠️ VERIFIED (${confidence}% confidence) — the work was approved, but the milestone was NOT completed. No money moved. Check it with cascrow_get_contract; if it stays VERIFIED, contact support@cascrow.com.`;
   } else if (panelUnavailable) {
     statusLine = `⏳ PENDING_REVIEW — the verification panel did not answer (too few models responded). This is NOT a rejection and NOT a judgement of the work; a human decides. Resubmitting the same evidence will not help while the panel is down.`;
   } else if (pendingReview) {
@@ -1048,6 +1199,11 @@ async function handleVerify({ proofId }) {
     decision,
     confidence,
     action,
+    v3Recommendation,
+    // MilestoneEscrowV3: the claim-relevant fields, structured as well as rendered.
+    ...(v3Recommendation
+      ? { manifestHash: result.manifestHash ?? null, submissionVerdict: result.submissionVerdict ?? "PENDING", claimReady: result.claimReady === true }
+      : {}),
     passed,
     pendingReview,
     // Returned as well as rendered: a client that reads the structured fields rather
@@ -1060,7 +1216,7 @@ async function handleVerify({ proofId }) {
     // Returned as well as rendered, as the hosted route does: with SUPERSEDED it says
     // the row was CLOSED rather than won by another proof.
     ...(result.settledAs ? { settledAs: result.settledAs } : {}),
-    releaseHoldUntil,
+    notCompletableWithoutEscrow: notCompletable,
     reasoning,
     totalModels: TOTAL_MODELS,
     modelsResponded: votes.length,
@@ -1078,9 +1234,14 @@ async function handleGetContract({ contractId }) {
 
 async function handleJoinContract({ inviteCode }) {
   const data = await apiPost("/api/contracts/join", { inviteCode });
+  // `activated` is the join's own activation result: a $0 contract is active now, a
+  // money contract waits for its V3 offer. It said "AWAITING_ESCROW — ready to receive
+  // proof once funded" for both, which sent a $0 builder waiting for money that never comes.
   return {
     contractId: data.contractId,
-    message: `Joined contract as Builder. Contract is now AWAITING_ESCROW — ready to receive proof once funded.`,
+    status: data.status ?? null,
+    activated: typeof data.activated === "boolean" ? data.activated : null,
+    message: joinedLine(data),
   };
 }
 
@@ -1119,9 +1280,8 @@ async function handleCheckInvites() {
 // counterparty wrote about it: `name`, `skills` (PATCH /api/agent/settings,
 // 20 x 50 chars, no charset restriction) and a milestone `summary`. These tools
 // hand that straight into a DIFFERENT principal's model context while it is
-// choosing who to hire — a model whose session may also hold
-// `cascrow_escrow_fund`. Unmarked, cascrow is the transport for whatever the
-// text says.
+// choosing who to hire and about to fund them. Unmarked, cascrow is the
+// transport for whatever the text says.
 //
 // Why it is copied here rather than imported: this package ships to npm with
 // one dependency (@modelcontextprotocol/sdk) and cannot reach into the web
@@ -1275,7 +1435,7 @@ async function handleGetReputation({ walletAddress }) {
       .filter(([, hash]) => hash)
       .map(([k, hash]) => `${k}: ${xrplTxUrl(hash)}`)
       .join(", ");
-    return `  - ${m.summary ?? "Completed milestone"} ($${m.amountUSD} RLUSD)${proofLinks ? ` — ${proofLinks}` : ""}`;
+    return `  - ${m.summary ?? "Completed milestone"} ($${m.amountUSD})${proofLinks ? ` — ${proofLinks}` : ""}`;
   }).join("\n");
 
   // An empty `milestones` array has two different causes and the agent has to be
@@ -1294,7 +1454,7 @@ async function handleGetReputation({ walletAddress }) {
     message: [
       `Agent reputation for ${walletAddress}:`,
       `  Completed: ${stats.milestonesCompleted} milestones`,
-      `  RLUSD released: $${stats.totalRlusdReleased}`,
+      releasedLine(stats),
       `  Success rate: ${successPct}`,
       skills.length > 0 ? `  Skills: ${skills.join(", ")}` : null,
       milestones.length > 0 ? `\nPublished milestones:\n${milestoneLines}` : noPublishedNote,
@@ -1302,6 +1462,17 @@ async function handleGetReputation({ walletAddress }) {
   };
 }
 
+/**
+ * The value released to the builder (owner decision 18, 2026-09-26): `totalReleasedUsd`
+ * over every escrow version, the XRP a MilestoneEscrowV3 escrow paid next to it.
+ * `totalRlusdReleased` is deprecated — the retired v2 escrow only — and is the
+ * fallback for a server that predates the new field. Same line as the hosted server.
+ */
+function releasedLine(stats) {
+  const xrp = stats.totalXrpReleased && Number(stats.totalXrpReleased) > 0 ? ` (${stats.totalXrpReleased} XRP from MilestoneEscrowV3 escrows)` : "";
+  return `  Released to this builder: $${stats.totalReleasedUsd ?? stats.totalRlusdReleased}${xrp}`;
+}
+
 async function handleDiscoverAgents({ skill, minRate, limit } = {}) {
   const params = new URLSearchParams();
   if (skill)   params.set("skill",   skill);
@@ -1371,7 +1542,9 @@ async function handleSetDiscoverable({ discoverable, skills, callbackUrl } = {})
  *
  * The queue exists because a push without a pull is not a channel: an agent that
  * was down when `manual_review.required` fired has no way back to the decision,
- * and `cron/cancel-expired` auto-approves it after 48 h and releases the escrow.
+ * and `cron/cancel-expired` completes it when its review window closes — 48 h
+ * under MANUAL_AUTO/AUTO, 14 days otherwise (a verification-only contract: no
+ * money moves, and nobody decided it — `decidedBy: "sla"`).
  * The verdict ships in the same change rather than later, because a list its
  * recipient cannot act on is the shape this project has already been burned by
  * (F-72). This server and the hosted one at `src/app/api/mcp/route.ts` carry both
@@ -1380,9 +1553,12 @@ async function handleSetDiscoverable({ discoverable, skills, callbackUrl } = {})
 async function handleReviewQueue() {
   const data = await apiGet("/api/agent/review-queue");
   const contracts = data.contracts ?? [];
+  // The V3 hint is said in BOTH branches: an empty v2 queue is exactly when an
+  // agent stops reading, and a claim window keeps running (post-review of 6faf3fdc).
+  const v3 = v3ClaimsHint(data.v3ClaimsPending);
 
   if (contracts.length === 0) {
-    return { contracts: [], total: 0, truncated: false, message: "No milestones are waiting for your verdict." };
+    return { ...data, contracts: [], total: 0, truncated: false, message: `No milestones are waiting for your verdict.${v3}` };
   }
 
   // The titles arrive already marked as counterparty-written by the route
@@ -1395,16 +1571,92 @@ async function handleReviewQueue() {
         : pending.length > 1
           ? ` — ${pending.length} milestones pending; name one with milestoneId`
           : " — contract-level review (omit milestoneId)";
-    return `  - ${c.contractId} (${c.amountUSD} RLUSD) ${c.projectTitle}${ms}`;
+    return `  - ${c.contractId} ${c.projectTitle}${ms}`;
   }).join("\n");
 
   const more = data.truncated ? `\n\n(${data.total} in total — this list is capped.)` : "";
   return {
     ...data,
-    message: `${data.total} contract(s) waiting for your verdict:\n${lines}${more}\n\nDecide with cascrow_review_contract.`,
+    message: `${data.total} contract(s) waiting for your verdict:\n${lines}${more}\n\nDecide with cascrow_review_contract.${v3}`,
+  };
+}
+
+function v3ClaimsHint(n) {
+  if (n === null) return "\n\nOpen MilestoneEscrowV3 claims could not be counted — check cascrow_v3_claims.";
+  if (typeof n === "number" && n > 0) return `\n\n${n} MilestoneEscrowV3 claim(s) can still be objected to — list them with cascrow_v3_claims.`;
+  return "";
+}
+
+/**
+ * The payer's open MilestoneEscrowV3 claims — `GET /api/agent/v3-claims`, the
+ * same owner the review-queue count asks (design Rev. 8 final C). Pull only: the
+ * action is the payer's own `object()` on chain (rule I9). The hosted twin is
+ * `handleV3Claims` in `src/app/api/mcp/route.ts`.
+ */
+async function handleV3Claims() {
+  const data = await apiGet("/api/agent/v3-claims");
+  const claims = data.claims ?? [];
+  if (claims.length === 0) return { ...data, claims: [], message: "No MilestoneEscrowV3 claim is waiting on you." };
+  const lines = claims
+    .map((c) => `  - escrow ${c.escrowId} on ${c.chainId}/${c.escrowContract} — ${c.milestoneTitle}, claim ${c.claimIndex}` +
+      `${c.secondFunding ? " (SECOND funding)" : ""}${c.held ? " (held by the indexer — verify on chain)" : ""}: ` +
+      (c.objectable === null ? "claim state unknown here — read getEscrow on chain" : c.objectable ? `object() before ${c.objectionDeadline}` : `window closed at ${c.objectionDeadline}`))
+    .join("\n");
+  const more = data.truncated ? "\n\n(This list is capped; more claims exist.)" : "";
+  return { ...data, message: `${claims.length} claim(s):\n${lines}${more}\n\ncascrow cannot object for you — your own wallet calls object(escrowId) on the escrow contract.` };
+}
+
+// ── MilestoneEscrowV3, remote half (design Rev. 10). cascrow prepares and reads; the
+// party signs and sends with its own key — nothing here signs, sends or relays. The
+// hosted twins are the handleV3* functions in src/app/api/mcp/route.ts.
+async function handleV3Offer(args) {
+  const data = await apiPost("/api/escrow/v3/offer", args);
+  return { ...data, message: "Offer frozen and sent to the builder. They accept with their own key; you then fund with one transaction from your machine: npx cascrow-signer@0.1.0 fund --milestone " + args.milestoneId + "." };
+}
+
+async function handleV3AcceptanceGet({ milestoneId }) {
+  const data = await apiGet(`/api/escrow/v3/acceptance?milestoneId=${encodeURIComponent(milestoneId)}`);
+  return {
+    ...data,
+    message:
+      "These are the payer's frozen terms. Check them yourself — your signature binds you until acceptBy, and nothing in cascrow revokes it. " +
+      "npx cascrow-signer@0.1.0 accept --milestone " + milestoneId + " checks them against its own pinned chain and contract and signs on your machine.",
+  };
+}
+
+async function handleV3AcceptanceSubmit({ offerId, signature }) {
+  const data = await apiPost("/api/escrow/v3/acceptance", { offerId, signature });
+  return { ...data, message: "Acceptance recorded. The payer can now fund these exact terms until acceptBy." };
+}
+
+async function handleV3Prepare({ milestoneId, action, proofHash, reasonHash, newDeadline }) {
+  const q = new URLSearchParams({ milestoneId, action });
+  if (proofHash) q.set("proofHash", proofHash);
+  if (reasonHash) q.set("reasonHash", reasonHash);
+  if (newDeadline) q.set("newDeadline", String(newDeadline));
+  const data = await apiGet(`/api/escrow/v3/prepare?${q.toString()}`);
+  return {
+    ...data,
+    message:
+      "UNSIGNED transaction — cascrow does not sign, send or relay it. Before signing: rebuild data from the contract ABI, and check to and chainId against your OWN configuration, not this answer. " +
+      "Then broadcast it yourself and report the hash with cascrow_v3_report_tx. npx cascrow-signer@0.1.0 does all of this locally.",
   };
 }
 
+async function handleV3ReportTx({ milestoneId, txHash }) {
+  // Refused BEFORE anything is sent: a signed transaction pasted here would be
+  // cascrow receiving a transaction to relay, which it never does (rule I9).
+  if (typeof txHash !== "string" || !TX_HASH_RE.test(txHash)) throw new CascrowApiError(V3_CLIENT_TEXT.reportTxOnlyHash, { status: 0, code: "NOT_A_TX_HASH" });
+  const data = await apiPost("/api/escrow/v3/sync", { milestoneId, txHash });
+  return { ...data, message: "Reported. cascrow re-reads the chain for this milestone; the transaction itself is only what the chain says it is." };
+}
+
+async function handleV3Attestation({ escrowId, claimIndex }) {
+  const q = new URLSearchParams({ escrowId, claimIndex: String(claimIndex) });
+  const data = await apiGet(`/api/escrow/v3/attestation?${q.toString()}`);
+  return { ...data, message: "A non-binding AI recommendation, signed by cascrow. It moves no money: only the payer's release, an unobjected claim running out its window, or the arbiter pays." };
+}
+
 async function handleReviewContract({ contractId, decision, milestoneId }) {
   const data = await apiPost(
     "/api/contracts/review",
@@ -1412,10 +1664,9 @@ async function handleReviewContract({ contractId, decision, milestoneId }) {
   );
   const what =
     decision === "APPROVE"
-      ? "approved — the escrow is being released to the builder"
+      ? "approved and completed (a verification-only contract: no money moves)"
       : "rejected — the milestone is back with the builder, who can resubmit";
-  const tx = data.txHash ? `\nRelease tx: ${data.txHash}` : "";
-  return { ...data, message: `Milestone ${what}.${tx}` };
+  return { ...data, message: `Milestone ${what}.` };
 }
 
 async function handleListMyContracts({ role } = {}) {
@@ -1457,9 +1708,9 @@ async function handleListMyContracts({ role } = {}) {
  *
  * `decision` answers a question about the PROOF. What an agent needs is the state of
  * the MILESTONE, and the two come apart three ways that all used to read as plain
- * "APPROVED": the funds are already out (COMPLETED), the payout is scheduled and the
- * funder can still contest it (VERIFIED + releaseHoldUntil), or this proof lost to
- * another one and the milestone is in someone else's terminal state.
+ * "APPROVED": the milestone is already done (COMPLETED), it carries an amount nothing can
+ * complete (`notCompletableWithoutEscrow`), or this proof lost to another one and the
+ * milestone is in someone else's terminal state.
  */
 function proofOutcomeLine(s) {
   // FIRST, before `decision` is read at all: a milestone that is already terminal
@@ -1468,17 +1719,22 @@ function proofOutcomeLine(s) {
   // here used to print "✅ APPROVED" for money that may be back with the funder.
   const closed = closedMilestoneStatus(s);
   if (closed && closed !== "COMPLETED") return closedOutcomeLine(s, closed);
+  // Before any verdict is read: an approval cannot complete this milestone (it carries
+  // an amount without a MilestoneEscrowV3 escrow). A YES here is not "done" — the
+  // verdict doors answered 409 NOT_COMPLETABLE_WITHOUT_ESCROW and a case is open.
+  if (s.notCompletableWithoutEscrow === true) return `⛔ NOT COMPLETABLE — ${V3_CLIENT_TEXT.codeHints.NOT_COMPLETABLE_WITHOUT_ESCROW}`;
   // SECOND: the milestone is approved (VERIFIED) or paid (COMPLETED), and not on a YES
   // from this proof. Its `decision` is then NO or absent, and printing it next to
   // "COMPLETED — funds released" or "APPROVED — payout scheduled" read as THIS proof
   // having been approved.
   if (approvedWithoutThisVerdict(s)) return approvedWithoutThisVerdictLine(s);
+  // MilestoneEscrowV3, not yet paid: a RECOMMENDATION that moves nothing, judged by
+  // the SUBMISSION's verdict — never "✅ APPROVED" off this file's `decision`.
+  if (s.escrowVersion === 3 && s.milestoneStatus !== "COMPLETED") return v3RecommendationLine(s.submissionVerdict, s.confidence);
   const head =
     s.milestoneStatus === "COMPLETED" || closed === "COMPLETED"
-      ? "✅ COMPLETED — funds released"
-      : s.milestoneStatus === "VERIFIED" && s.releaseHoldUntil
-        ? `⏸️ APPROVED — payout scheduled for ${s.releaseHoldUntil}, no funds have moved yet`
-        : s.decision === "YES"
+      ? `✅ COMPLETED — ${s.escrowVersion === 3 ? "paid out on chain from its MilestoneEscrowV3 escrow" : "no money was held (verification-only contract)"}`
+      : s.decision === "YES"
           ? "✅ APPROVED"
           : "❌ REJECTED";
   return `${head}${s.confidence != null ? ` (confidence: ${s.confidence}%)` : ""}`;
@@ -1515,13 +1771,25 @@ function terminalStory(reason, row) {
     case "CANCELLED_AFTER_APPROVAL":
       return "An earlier approval lost the race to the funder's on-chain cancel; the escrow was refunded to the funder.";
     case "DEADLINE_EXPIRED":
-      return "The deadline passed and the escrow was cancelled, refunding the funder.";
+      return "The deadline passed before the milestone was completed; any escrow it held went back to the funder (refunding the funder is the funder's own on-chain call for a MilestoneEscrowV3 escrow).";
     case "RENEGOTIATION_REJECTED":
-      return "A requested extension was rejected and the escrow was cancelled, refunding the funder.";
+      return "A requested extension was rejected and the milestone was closed; any escrow it held went back to the funder.";
     case "NO_FUNDED_ESCROW":
       return "No funded escrow existed on-chain for this milestone.";
     case "CONTRACT_DECLINED":
       return "The contract was declined or expired before anything was escrowed.";
+    case "ARBITER_REFUNDED":
+      return "The named arbiter decided for the funder, and the escrow was refunded to the funder.";
+    case "REFUNDED_AFTER_OBJECTION_AI_NO":
+      return "The funder objected to the builder's claim, the panel had not approved it, and the escrow was refunded to the funder.";
+    case "REFUNDED_AFTER_OBJECTION_DISPUTED":
+      return "The funder objected to a claim the panel had approved, and the escrow was refunded to the funder — recorded as a dispute, not as the builder's failure.";
+    case "RETURNED_BY_PAYEE":
+      return "The builder returned the escrow to the funder.";
+    case "RETURNED_BEFORE_WORK":
+      return "The builder returned the escrow to the funder before any work was claimed.";
+    case "ACCEPTANCE_LAPSED":
+      return "The builder accepted the escrow terms, but the funder did not fund them before the acceptance expired; the milestone ended with no money escrowed, and it does not count against the builder.";
     default:
       return `The reason was not recorded — check the ${row} before assuming where the funds are.`;
   }
@@ -1608,7 +1876,7 @@ function approvedWithoutThisVerdict(s) {
 
 /** Final: no later poll can change what this proof status says. */
 function nothingLeftToDecide(s) {
-  return closedMilestoneStatus(s) !== null || approvedWithoutThisVerdict(s);
+  return closedMilestoneStatus(s) !== null || s.notCompletableWithoutEscrow === true || approvedWithoutThisVerdict(s);
 }
 
 /** The outcome line for `approvedWithoutThisVerdict`. It never says THIS proof was approved. */
@@ -1617,10 +1885,8 @@ function approvedWithoutThisVerdictLine(s) {
   const ROW = row.toUpperCase();
   const head =
     closedMilestoneStatus(s) === "COMPLETED"
-      ? `✅ ${ROW} COMPLETED — funds released`
-      : s.releaseHoldUntil
-        ? `⏸️ ${ROW} VERIFIED — payout scheduled for ${s.releaseHoldUntil}, no funds have moved yet (the funder can contest until then)`
-        : `✅ ${ROW} VERIFIED — the payout is not confirmed yet`;
+      ? `✅ ${ROW} COMPLETED — ${s.escrowVersion === 3 ? "paid out on chain from its MilestoneEscrowV3 escrow" : "no money was held (verification-only contract)"}`
+      : `✅ ${ROW} VERIFIED — approved, not completed yet`;
   const verdict =
     s.decision === "NO"
       ? `The panel did NOT approve this proof (NO${s.confidence != null ? `, confidence: ${s.confidence}%` : ""}).`
@@ -1645,7 +1911,9 @@ function approvedWithoutThisVerdictLine(s) {
  * reading stays.
  */
 function parkedForHuman(s) {
-  return Boolean(s.pending) && s.running !== true && s.milestoneStatus === "PENDING_REVIEW";
+  // Never a MilestoneEscrowV3 proof (post-review L2): no human review decides one — its
+  // milestone status is the chain fold's, and a PENDING_REVIEW there is no queue.
+  return s.escrowVersion !== 3 && Boolean(s.pending) && s.running !== true && s.milestoneStatus === "PENDING_REVIEW";
 }
 
 const PARKED_MESSAGE =
@@ -1694,8 +1962,8 @@ async function handleGetProofStatus({ proofId }) {
   // SEC-058 / SEC-059, the polling door. `decision === "YES" ? APPROVED : REJECTED`
   // answers a question about the PROOF; what an agent needs is the state of the
   // MILESTONE, and those come apart in three ways that all read as plain "APPROVED":
-  // the funds are already out (COMPLETED), the payout is scheduled and the funder can
-  // still contest it (VERIFIED + releaseHoldUntil), or another proof owns the
+  // the milestone is already done (COMPLETED), it carries an amount nothing can
+  // complete (notCompletableWithoutEscrow), or another proof owns the
   // milestone and this verdict changed nothing (SUPERSEDED upstream, which leaves the
   // milestone in someone else's terminal state).
   const parts = [
@@ -1719,6 +1987,20 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
   const proofId = data.proof_id ?? null;
   const votes = Array.isArray(data.model_votes) ? data.model_votes : [];
 
+  // MilestoneEscrowV3: a recommendation, never a payout — asked before every verdict
+  // branch below, none of which may read it as approved or rejected.
+  if (data.action === "V3_RECOMMENDATION") {
+    return {
+      ...markVerificationResult({ ...data, model_votes: votes }),
+      verdict: "v3_recommendation",
+      v3Recommendation: true,
+      manifestHash: data.manifestHash ?? null,
+      claimReady: data.claimReady ?? null,
+      submissionVerdict: data.submissionVerdict ?? "PENDING",
+      message: v3RecommendationLine(data.submissionVerdict, data.confidence ?? null),
+    };
+  }
+
   // SEC-055, first divergence. `/api/mcp/submit` answers `{ ok: true, decided:
   // "elsewhere", … }` at status **200 with no `verdict` key** when the milestone was
   // settled by a concurrent request — the investor's review, or a second submission.
@@ -1740,7 +2022,6 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
       ...markVerificationResult({ model_votes: [] }),
       on_chain_url: null,
       proof_id: proofId,
-      release_hold_until: null,
       signed_at: null,
       message: settledAs
         ? `ℹ️ This milestone was closed (${settledAs}) before this submission could settle it, so this submission changed nothing and moved no funds itself. ` +
@@ -1768,7 +2049,6 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
       confidence: data.confidence ?? null,
       on_chain_url: null,
       proof_id: proofId,
-      release_hold_until: null,
       message:
         `⏳ PENDING_REVIEW — the verification panel could not reach a verdict on this submission ` +
         `(too few models answered). This is NOT a rejection and NOT a judgement of your work: ` +
@@ -1779,17 +2059,13 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
   }
 
   const verdict = data.verdict ?? "unknown";
-  // SEC-058. Returned by the route on the approved-but-held path and read by neither
-  // MCP surface, so both rendered "✅ APPROVED" for a milestone whose funds have not
-  // moved. The hold exists precisely so a funder can contest, and the agent otherwise
-  // finds out by polling balances — or not at all.
-  const releaseHoldUntil = data.release_hold_until ?? null;
+  // An approved milestone that cannot complete is not a 200: the route answers 409
+  // NOT_COMPLETABLE_WITHOUT_ESCROW, which `apiPost` throws and the error formatter
+  // renders with its hint (`codeHints`).
 
   let statusLine;
   if (verdict === "approved") {
-    statusLine = releaseHoldUntil
-      ? `⏸️ APPROVED (${confidence}% confidence) — payout scheduled for ${releaseHoldUntil}. NO FUNDS HAVE MOVED YET: the funder can contest until then, and the date can move.`
-      : `✅ APPROVED (${confidence}% confidence)${onChainUrl ? ` — proof: ${onChainUrl}` : ""}`;
+    statusLine = `✅ APPROVED (${confidence}% confidence)${onChainUrl ? ` — proof: ${onChainUrl}` : ""}`;
   } else if (verdict === "pending_review") {
     statusLine = `⏳ PENDING_REVIEW (${confidence}% confidence) — manual review triggered.`;
   } else {
@@ -1808,7 +2084,6 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
     ...markVerificationResult({ reasoning: data.reasoning ?? "", model_votes: votes }),
     on_chain_url: onChainUrl,
     proof_id: proofId,
-    release_hold_until: releaseHoldUntil,
     signed_at: data.signed_at ?? null,
     message: `${statusLine}${voteSummary ? `\n\n${voteSummary}` : ""}${data.reasoning ? `\n\n${excerptMarked(data.reasoning, 400)}` : ""}`,
   };
@@ -2018,7 +2293,7 @@ async function handleWatchVerification({ milestoneId, content, filename, proofId
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "cascrow", version: "1.8.0" },
+  { name: "cascrow", version: "3.0.0" },
   { capabilities: { tools: {} } }
 );
 
@@ -2029,12 +2304,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
+  // Removed in 2.0.0 (cascrow Phase 5): the tool sent the agent's private key to
+  // the server. A host with a cached tool list may still call it. Answered before
+  // `args` is touched and in anonymous mode too — the arguments may hold a key,
+  // and nothing here logs, echoes or forwards them.
+  if (REMOVED_CUSTODY_TOOLS.includes(name)) {
+    return { content: [{ type: "text", text: CUSTODY_TOOL_REMOVED }], isError: true };
+  }
+  // Removed in 3.0.0 (cascrow Phase 6, owner decision 16): a $0 contract activates by
+  // itself, and a milestone with an amount is a MilestoneEscrowV3 escrow its payer
+  // funds from their own machine. A cached tool list still calls the old name.
+  if (name === "cascrow_fund_milestone") {
+    return { content: [{ type: "text", text: `Error: ${V3_CLIENT_TEXT.fundRemoved} [TOOL_REMOVED]` }], isError: true };
+  }
+
   if (ANONYMOUS_MODE && name !== "cascrow_verify_work") {
     return {
       content: [{
         type: "text",
         text: `Error: "${name}" requires a Cascrow account. Register free at https://cascrow.com/register ` +
-          `(or POST /api/agent/register), then set CASCROW_API_KEY to unlock all 18 tools. ` +
+          `(or POST /api/agent/register), then set CASCROW_API_KEY to unlock all ${TOOLS.length} tools. ` +
           `Only cascrow_verify_work works anonymously (3 free verifications/day).`,
       }],
       isError: true,
@@ -2045,8 +2334,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let result;
     switch (name) {
       case "cascrow_create_contract":  result = await handleCreateContract(args);  break;
-      case "cascrow_fund_milestone":   result = await handleFundMilestone(args);   break;
-      case "cascrow_escrow_fund":      result = await handleEscrowFund(args);      break;
       case "cascrow_submit_proof":     result = await handleSubmitProof(args);     break;
       case "cascrow_verify":           result = await handleVerify(args);          break;
       case "cascrow_get_contract":     result = await handleGetContract(args);     break;
@@ -2059,6 +2346,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "cascrow_set_discoverable":  result = await handleSetDiscoverable(args);      break;
       case "cascrow_list_my_contracts": result = await handleListMyContracts(args);      break;
       case "cascrow_review_queue":     result = await handleReviewQueue();              break;
+      case "cascrow_v3_claims":        result = await handleV3Claims();                 break;
+      case "cascrow_v3_offer":         result = await handleV3Offer(args);              break;
+      case "cascrow_v3_acceptance_get": result = await handleV3AcceptanceGet(args);     break;
+      case "cascrow_v3_acceptance_submit": result = await handleV3AcceptanceSubmit(args); break;
+      case "cascrow_v3_prepare":       result = await handleV3Prepare(args);            break;
+      case "cascrow_v3_report_tx":     result = await handleV3ReportTx(args);           break;
+      case "cascrow_v3_attestation":   result = await handleV3Attestation(args);        break;
       case "cascrow_review_contract":  result = await handleReviewContract(args);       break;
       case "cascrow_get_proof_status":  result = await handleGetProofStatus(args);       break;
       case "cascrow_mcp_submit":        result = await handleMcpSubmit(args);            break;
@@ -2072,8 +2366,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
   } catch (err) {
+    // A V3 refusal says who can act and how (F-72) — the body's actionable fields (G5),
+    // then the owner's hint, role-aware on the body (H9); the owner's words, copied above.
+    const detail = err instanceof CascrowApiError ? v3RefusalDetail(err.body) : "";
+    const hint = err instanceof CascrowApiError ? v3HintFor(err.code, err.body) : null;
     return {
-      content: [{ type: "text", text: `Error: ${err.message}` }],
+      content: [{ type: "text", text: `Error: ${err.message}${detail && !err.message.includes(detail) ? ` — ${detail}` : ""}${hint && !err.message.includes(hint) ? `\n\n${hint}` : ""}` }],
       isError: true,
     };
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cascrow-mcp",
-  "version": "1.8.0",
-  "description": "MCP server for Cascrow — trust infrastructure for the agent economy: AI verification, on-chain reputation, and milestone escrow on the XRP Ledger",
+  "version": "3.0.0",
+  "description": "MCP server for Cascrow — trust infrastructure for the agent economy: AI verification, on-chain reputation, and non-custodial milestone escrow (MilestoneEscrowV3, native XRP)",
   "type": "module",
   "main": "index.js",
   "bin": {

package/server.json

@@ -9,13 +9,13 @@
     "source": "github",
     "subfolder": "cascrow-mcp"
   },
-  "version": "1.8.0",
+  "version": "3.0.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "cascrow-mcp",
-      "version": "1.8.0",
+      "version": "3.0.0",
       "transport": {
         "type": "stdio"
       },

package/smithery.yaml

@@ -10,7 +10,7 @@ startCommand:
     properties:
       CASCROW_API_KEY:
         type: string
-        description: "Optional. Your cascrow API key (starts with csk_) — get one at cascrow.com/register or POST /api/agent/register. Without it, the server still starts but only cascrow_verify_work is available (3 free AI-verified checks per IP per day, no account needed). Set this to unlock all 18 tools."
+        description: "Optional. Your cascrow API key (starts with csk_) — get one at cascrow.com/register or POST /api/agent/register. Without it, the server still starts but only cascrow_verify_work is available (3 free AI-verified checks per IP per day, no account needed). Set this to unlock every other tool."
         pattern: "^csk_"
       CASCROW_BASE_URL:
         type: string