cascrow-mcp 1.7.0 → 3.0.0

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. " +
@@ -43,47 +146,123 @@ if (ANONYMOUS_MODE) {
 
 const authHeader = API_KEY ? { "Authorization": `Bearer ${API_KEY}` } : {};
 
-async function apiPost(path, body) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: {
-      ...authHeader,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-  const data = await res.json();
-  if (!res.ok) {
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+// Client deadlines. This package cannot import src/, so the two that have an owner
+// are MIRRORED here and checked against it by client-deadline-mirrors.test.ts:
+//   UPLOAD_CLIENT_ABORT_MS      mirrors UPLOAD_CLIENT_ABORT_MS in src/lib/latency-budget.ts
+//   MCP_SUBMIT_CLIENT_ABORT_MS  mirrors MCP_SUBMIT_CLIENT_ABORT_MS in src/lib/latency-budget.ts
+// Every other call gets REQUEST_CLIENT_ABORT_MS — the longest maxDuration any route
+// has, so it only ever stops a request the platform has already given up on. Before
+// T11 these calls had no deadline at all: a hung connection hung the tool call.
+const UPLOAD_CLIENT_ABORT_MS = 120_000;
+const MCP_SUBMIT_CLIENT_ABORT_MS = 235_000;
+const REQUEST_CLIENT_ABORT_MS = 300_000;
+
+/**
+ * An error from the API with what a caller needs to decide what to do next: the
+ * HTTP status, the stable `code` (src/lib/api-error.ts — or `UPSTREAM_NON_JSON` /
+ * `CLIENT_TIMEOUT`, which this client produces itself), and how long the server
+ * asked us to wait (`Retry-After`, else `retry_after_seconds`).
+ */
+class CascrowApiError extends Error {
+  constructor(message, { status, code = null, retryAfterSeconds = null, body = null } = {}) {
+    super(message);
+    this.name = "CascrowApiError";
+    this.status = status;
+    this.code = code;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.body = body;
   }
-  return data;
 }
 
-async function apiGet(path) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    headers: { ...authHeader },
-  });
-  const data = await res.json();
+function retryAfterOf(res, data) {
+  const header = res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : null;
+  const fromHeader = header !== null && /^\d+$/.test(header.trim()) ? Number(header.trim()) : null;
+  if (fromHeader !== null) return fromHeader;
+  return typeof data?.retry_after_seconds === "number" ? data.retry_after_seconds : null;
+}
+
+/**
+ * The one way this server talks to the API (T11-A3).
+ *
+ * The body is read as TEXT and parsed in a try: an HTML 502 from the platform used
+ * to reach `res.json()` and surface as "Unexpected token '<'", naming neither the
+ * status nor anything to do about it. The deadline covers the body read too — the
+ * timer is cleared after it, not after the headers (SEC-073's lesson). No retry
+ * here: a single call either answers or throws; only the poll loop waits and asks
+ * again.
+ */
+async function fetchJson(method, path, { json, form, deadlineMs = REQUEST_CLIENT_ABORT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), deadlineMs);
+  let res;
+  let text;
+  try {
+    res = await fetch(`${BASE_URL}${path}`, {
+      method,
+      headers: { ...authHeader, ...(json !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(json !== undefined ? { body: JSON.stringify(json) } : form !== undefined ? { body: form } : {}),
+      signal: controller.signal,
+    });
+    text = await res.text();
+  } catch (e) {
+    if (e && e.name === "AbortError") {
+      throw new CascrowApiError(
+        `No answer from ${path} within ${Math.round(deadlineMs / 1000)} s. The request may still complete on the server — check its result before repeating it.`,
+        { status: 0, code: "CLIENT_TIMEOUT" }
+      );
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { error: `HTTP ${res.status} (non-JSON response from server)`, code: "UPSTREAM_NON_JSON" };
+    // A 200 that is not JSON is not a success anyone can read.
+    if (res.ok) throw new CascrowApiError(data.error, { status: res.status, code: data.code });
+  }
   if (!res.ok) {
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+    const code = typeof data?.code === "string" ? data.code : null;
+    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 — 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` : ""}` +
+        (mayHaveCompleted ? ". The request may still have completed on the server — check the contract (cascrow_get_contract) before repeating it." : ""),
+      { status: res.status, code, retryAfterSeconds, body: data }
+    );
   }
   return data;
 }
 
-async function apiPatch(path, body) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "PATCH",
-    headers: {
-      ...authHeader,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-  const data = await res.json();
-  if (!res.ok) {
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+/** A response body parsed without trusting it to be JSON (see fetchJson). */
+async function readJsonSafe(res) {
+  const text = await res.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: `HTTP ${res.status} (non-JSON response from server)`, code: "UPSTREAM_NON_JSON" };
   }
-  return data;
+}
+
+// The names the handlers (and the tests that extract them) use. Thin wrappers.
+async function apiPost(path, body, deadlineMs) {
+  return fetchJson("POST", path, { json: body, deadlineMs });
+}
+
+async function apiGet(path) {
+  return fetchJson("GET", path);
+}
+
+async function apiPatch(path, body) {
+  return fetchJson("PATCH", path, { json: body });
 }
 
 async function uploadProof(milestoneId, filename, content) {
@@ -91,17 +270,7 @@ async function uploadProof(milestoneId, filename, content) {
   const form = new FormData();
   form.append("file", blob, filename);
   form.append("milestoneId", milestoneId);
-
-  const res = await fetch(`${BASE_URL}/api/proof/upload`, {
-    method: "POST",
-    headers: { ...authHeader },
-    body: form,
-  });
-  const data = await res.json();
-  if (!res.ok) {
-    throw new Error(data.error ?? `HTTP ${res.status}`);
-  }
-  return data;
+  return fetchJson("POST", "/api/proof/upload", { form, deadlineMs: UPLOAD_CLIENT_ABORT_MS });
 }
 
 // Stream verify with a 235s deadline that covers the WHOLE read, quorum retries
@@ -153,8 +322,24 @@ async function streamVerify(proofId) {
     // long-lived MCP server that holds the event loop and later aborts a fetch
     // that finished minutes ago.
     clearTimeout(timeout);
-    const data = await res.json().catch(() => ({}));
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+    const text = await res.text().catch(() => "");
+    let data;
+    try { data = text ? JSON.parse(text) : {}; } catch { data = { error: `HTTP ${res.status} (non-JSON response from server)`, code: "UPSTREAM_NON_JSON" }; }
+    // T01-5. Upload starts verification by itself, so a start that lost the claim to
+    // a RUNNING run is the normal case, not a failure: wait for that run instead.
+    // Never read this 409's Retry-After as a wait — it is the ~1 h takeover cutoff
+    // (SEC-093); `expected_done_in_seconds` is how long the run needs.
+    if (res.status === 409 && data.code === "VERIFICATION_IN_PROGRESS" && data.phase === "running") {
+      const budgetMs = Math.max(30_000, Math.min(235_000, ((data.expected_done_in_seconds ?? 200) + 30) * 1000));
+      const watch = await pollUntilSettled(proofId, budgetMs);
+      return { attached: true, watch: watch ?? stillRunningResult(proofId) };
+    }
+    throw new CascrowApiError(`${data.error ?? `HTTP ${res.status}`}${data.code ? ` [${data.code}]` : ""}`, {
+      status: res.status,
+      code: typeof data.code === "string" ? data.code : null,
+      retryAfterSeconds: retryAfterOf(res, data),
+      body: data,
+    });
   }
   if (!res.body) {
     clearTimeout(timeout);
@@ -223,18 +408,90 @@ async function streamVerify(proofId) {
 
 // ─── Tool definitions ─────────────────────────────────────────────────────────
 
+// ─── The bar a milestone is judged against ────────────────────────────────────
+// COPY of normalizeMilestoneChecklist / normalizeCriteria in src/lib/milestone-bar-input.ts
+// (this package cannot import src/). milestone-bar-input-parity.test.ts runs this copy
+// against the owner over the same case matrix — change both, or that test goes red.
+const CHECKLIST_MAX_ITEMS = 20;
+const CHECKLIST_TITLE_MAX = 200;
+const CHECKLIST_ID_MAX = 100;
+const CRITERIA_MAX = 4000;
+const CHECKLIST_SEVERITIES = ["CRITICAL", "HIGH", "MEDIUM", "LOW"];
+
+function normalizeMilestoneChecklist(items) {
+  if (items === undefined || items === null) return undefined;
+  if (!Array.isArray(items)) throw new Error("verificationChecklist: must be an array of { title, severity?, id? }");
+  if (items.length === 0) return undefined;
+  if (items.length > CHECKLIST_MAX_ITEMS) throw new Error(`verificationChecklist: at most ${CHECKLIST_MAX_ITEMS} items`);
+  items.forEach((raw, i) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error(`verificationChecklist[${i}]: must be an object with a title`);
+    }
+  });
+  const withId = items.filter((it) => it.id !== undefined).length;
+  if (withId !== 0 && withId !== items.length) {
+    throw new Error("verificationChecklist: either give every item an id or none (ids are then assigned 1..n)");
+  }
+  const seen = new Set();
+  return items.map((it, i) => {
+    const title = typeof it.title === "string" ? it.title.trim() : "";
+    if (title.length === 0) throw new Error(`verificationChecklist[${i}]: title is required`);
+    if (title.length > CHECKLIST_TITLE_MAX) throw new Error(`verificationChecklist[${i}]: title must be at most ${CHECKLIST_TITLE_MAX} characters`);
+    let id = i + 1;
+    if (withId) {
+      if (typeof it.id !== "number" || !Number.isInteger(it.id) || it.id < 1 || it.id > CHECKLIST_ID_MAX) {
+        throw new Error(`verificationChecklist[${i}]: id must be an integer from 1 to ${CHECKLIST_ID_MAX}`);
+      }
+      if (seen.has(it.id)) throw new Error(`verificationChecklist[${i}]: duplicate id ${it.id}`);
+      seen.add(it.id);
+      id = it.id;
+    }
+    const out = { id, title };
+    if (it.severity !== undefined && it.severity !== null && it.severity !== "") {
+      const sev = typeof it.severity === "string" ? it.severity.trim().toUpperCase() : "";
+      if (!CHECKLIST_SEVERITIES.includes(sev)) {
+        throw new Error(`verificationChecklist[${i}]: severity must be one of ${CHECKLIST_SEVERITIES.join(", ")}`);
+      }
+      out.severity = sev;
+    }
+    return out;
+  });
+}
+
+function normalizeCriteria(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new Error("verificationCriteria: must be a string");
+  const v = value.trim();
+  if (v.length === 0) return undefined;
+  if (v.length > CRITERIA_MAX) throw new Error(`verificationCriteria: at most ${CRITERIA_MAX} characters (got ${v.length})`);
+  return v;
+}
+
 const TOOLS = [
   {
     name: "cascrow_create_contract",
     description:
       "Create a Cascrow verification contract with one or more milestones. " +
-      "Each milestone defines a deliverable, its acceptance criteria, and a deadline. " +
-      "Returns contractId, milestoneIds, and a link to view the contract. " +
+      "Each milestone has a short title, a deadline and — separately — the bar the AI panel judges it against: " +
+      "verificationCriteria (prose) and/or verificationChecklist (items). Put acceptance criteria THERE, not in the title: " +
+      "the title is printed on the public certificate. " +
+      "Returns contractId, an inviteCode and a link to view the contract. " +
       "Use this BEFORE starting any work so the user can see the plan.",
     inputSchema: {
       type: "object",
       required: ["milestones"],
       properties: {
+        agentReviewMode: {
+          type: "string",
+          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, 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",
           minItems: 1,
@@ -245,7 +502,30 @@ const TOOLS = [
             properties: {
               title: {
                 type: "string",
-                description: "Milestone title including acceptance criteria, e.g. 'Hero section with CTA — must be responsive down to 320px, LCP < 2s'",
+                description: "Short milestone title, e.g. 'Landing page hero section'. Printed on the public certificate — put the acceptance criteria in verificationCriteria / verificationChecklist instead.",
+              },
+              verificationCriteria: {
+                type: "string",
+                maxLength: 4000,
+                description:
+                  "What the AI panel checks the proof against, in prose, e.g. 'Responsive down to 320px, LCP under 2 s on mobile, CTA links to /signup'. " +
+                  "The panel judges the proof against this text; without it, it judges against the title alone.",
+              },
+              verificationChecklist: {
+                type: "array",
+                maxItems: 20,
+                description:
+                  "Optional checklist the panel scores item by item on TEXT proofs (a YES then needs every item addressed — stricter than criteria alone). " +
+                  "Image proofs are judged against the criteria, not the checklist. Give every item an id (1–100, unique) or none (ids are assigned 1..n).",
+                items: {
+                  type: "object",
+                  required: ["title"],
+                  properties: {
+                    id: { type: "integer", minimum: 1, maximum: 100 },
+                    title: { type: "string", maxLength: 200 },
+                    severity: { type: "string", enum: ["CRITICAL", "HIGH", "MEDIUM", "LOW"] },
+                  },
+                },
               },
               deadlineDays: {
                 type: "number",
@@ -253,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).",
               },
             },
           },
@@ -261,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:
@@ -303,8 +548,9 @@ const TOOLS = [
       "Write a detailed, specific proof report describing exactly what was built, " +
       "with verifiable evidence (URLs, metrics, specific implementation details). " +
       "The more specific and verifiable the proof, the higher the AI confidence score. " +
-      "NOTE: After submitting, the backend automatically triggers AI verification. " +
-      "You can call cascrow_verify afterwards to stream the live results.",
+      "NOTE: After submitting, the backend starts AI verification by itself. " +
+      "Wait for the verdict with cascrow_watch_verification { proofId } (or poll cascrow_get_proof_status). " +
+      "Do NOT call cascrow_verify for a proof you just submitted — its verification is already running.",
     inputSchema: {
       type: "object",
       required: ["milestoneId", "proof"],
@@ -324,10 +570,11 @@ const TOOLS = [
   {
     name: "cascrow_verify",
     description:
-      "Stream live AI verification results for a submitted proof. " +
+      "Start (or re-run) AI verification for a proof and return the result. " +
       "5 AI models vote in parallel (Claude, GPT-4o, Gemini, Mistral, Cerebras). " +
       "Returns decision, confidence score, action (VERIFIED/PENDING_REVIEW/REJECTED), and per-model votes. " +
-      "Call this after cascrow_submit_proof to get live results. " +
+      "Upload already starts verification by itself: for a proof you just submitted use cascrow_watch_verification { proofId } instead. " +
+      "If a verification of this proof is already running, this call waits for it rather than failing. " +
       "Confidence > 85 + YES = VERIFIED. Confidence 60–85 = PENDING_REVIEW (manual review needed). Confidence < 60 = REJECTED.",
     inputSchema: {
       type: "object",
@@ -353,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"],
@@ -405,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 " +
@@ -499,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: {
@@ -517,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." },
       },
     },
@@ -543,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.",
@@ -636,17 +978,22 @@ const TOOLS = [
   {
     name: "cascrow_watch_verification",
     description:
-      "Submit a proof and wait for AI verification to complete — all in one call. " +
-      "Combines cascrow_submit_proof + polling into a single blocking tool. " +
+      "Wait for AI verification to complete — either submit a proof and wait (milestoneId + content), " +
+      "or wait for a proof you already submitted (proofId). Give one mode, not both. " +
       "Returns the final YES/NO decision, confidence score, and per-model votes once verification is done. " +
-      "Times out after ~100 seconds and returns the proofId so you can poll manually with cascrow_get_proof_status.",
+      "Stops early when waiting cannot help (proof deleted, no access, run interrupted) and says why. " +
+      "Times out after ~100 seconds and returns the proofId so you can call it again or poll cascrow_get_proof_status.",
     inputSchema: {
       type: "object",
-      required: ["milestoneId", "content"],
+      required: [],
       properties: {
+        proofId: {
+          type: "string",
+          description: "Wait for this already-submitted proof (e.g. from cascrow_submit_proof). Omit milestoneId and content in this mode.",
+        },
         milestoneId: {
           type: "string",
-          description: "The milestone ID to submit proof for",
+          description: "Submit mode: the milestone ID to submit proof for",
         },
         content: {
           type: "string",
@@ -663,7 +1010,7 @@ const TOOLS = [
 
 // ─── Tool handlers ────────────────────────────────────────────────────────────
 
-async function handleCreateContract({ milestones }) {
+async function handleCreateContract({ milestones, agentReviewMode }) {
   const deadline = (days) => {
     const d = new Date();
     d.setDate(d.getDate() + (days ?? 7));
@@ -671,11 +1018,26 @@ async function handleCreateContract({ milestones }) {
   };
 
   const payload = {
-    milestones: milestones.map((m) => ({
-      title: m.title,
-      amountUSD: m.amountUSD ?? 0,
-      cancelAfter: deadline(m.deadlineDays),
-    })),
+    milestones: milestones.map((m, i) => {
+      // Normalised here so a bad item is refused with its milestone and item index,
+      // not as a 400 on the whole contract. Copy of src/lib/milestone-bar-input.ts;
+      // milestone-bar-input-parity.test.ts runs this copy against the owner.
+      let criteria, checklist;
+      try {
+        criteria = normalizeCriteria(m.verificationCriteria);
+        checklist = normalizeMilestoneChecklist(m.verificationChecklist);
+      } catch (e) {
+        throw new Error(`milestones[${i}]: ${e.message}`);
+      }
+      return {
+        title: m.title,
+        amountUSD: m.amountUSD ?? 0,
+        cancelAfter: deadline(m.deadlineDays),
+        ...(criteria !== undefined ? { verificationCriteria: criteria } : {}),
+        ...(checklist !== undefined ? { verificationChecklist: checklist } : {}),
+      };
+    }),
+    ...(agentReviewMode !== undefined ? { agentReviewMode } : {}),
   };
 
   const data = await apiPost("/api/contracts", payload);
@@ -694,31 +1056,6 @@ async function handleCreateContract({ milestones }) {
   };
 }
 
-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,
@@ -727,12 +1064,17 @@ async function handleSubmitProof({ milestoneId, proof, filename }) {
   );
   return {
     proofId: data.proofId,
-    message: `Proof submitted (proofId: ${data.proofId}). AI verification has been triggered automatically. Call cascrow_verify with this proofId to stream the live results.`,
+    message:
+      `Proof submitted (proofId: ${data.proofId}). AI verification has started automatically. ` +
+      `Wait for the verdict with cascrow_watch_verification { proofId: "${data.proofId}" } — do not call cascrow_verify, it is already running.`,
   };
 }
 
 async function handleVerify({ proofId }) {
   const result = await streamVerify(proofId);
+  // The run was already going (usually the one upload started): its result, read
+  // from proof-status through the same formatters as cascrow_watch_verification.
+  if (result && result.attached) return result.watch;
   const decision   = result.decision ?? "?";
   const confidence = result.confidence ?? 0;
   const action     = result.action ?? "?";
@@ -769,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.
@@ -808,23 +1152,34 @@ 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) {
-    statusLine = `ℹ️ 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.`;
+  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;
+    statusLine = settledAs
+      ? `ℹ️ SUPERSEDED — this milestone was closed (${settledAs}) before this verification could settle it, so this verification changed nothing and moved no funds. Your evidence was recorded. Do not resubmit to this milestone.`
+      : `ℹ️ 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) {
@@ -844,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
@@ -853,7 +1213,10 @@ async function handleVerify({ proofId }) {
     released,
     alreadyReleased,
     superseded,
-    releaseHoldUntil,
+    // 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 } : {}),
+    notCompletableWithoutEscrow: notCompletable,
     reasoning,
     totalModels: TOTAL_MODELS,
     modelsResponded: votes.length,
@@ -871,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),
   };
 }
 
@@ -912,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
@@ -1068,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
@@ -1087,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,
@@ -1095,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);
@@ -1164,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
@@ -1173,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
@@ -1188,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",
@@ -1205,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 } = {}) {
@@ -1250,22 +1708,105 @@ 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
+  // cannot be moved by this proof's verdict. Since 2026-09-23 `/api/verify` leaves a
+  // row that went EXPIRED mid-panel EXPIRED and still persists the verdict, so a YES
+  // 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"
-      ? "✅ COMPLETED — funds released"
-      : s.milestoneStatus === "VERIFIED" && s.releaseHoldUntil
-        ? `⏸️ APPROVED — payout scheduled for ${s.releaseHoldUntil}, no funds have moved yet`
-        : s.decision === "YES"
+    s.milestoneStatus === "COMPLETED" || closed === "COMPLETED"
+      ? `✅ 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}%)` : ""}`;
 }
 
+/**
+ * The terminal status of the row this proof settles against, or null while it is open.
+ *
+ * `milestoneClosed` is what `/api/agent/proof-status` derives from the row (the
+ * milestone, or the contract on the legacy contract-level path). `milestoneStatus` is
+ * the fallback for a server that predates the field — the same two statuses, so an
+ * older deployment does not reopen the defect this exists for.
+ */
+function closedMilestoneStatus(s) {
+  if (s.milestoneClosed === true) return s.terminalStatus || s.milestoneStatus || s.contractStatus || "EXPIRED";
+  // A legacy contract-level proof has no milestone: an older server reports its row only
+  // as `contractStatus`, and reading `milestoneStatus` alone printed APPROVED for a
+  // proof whose contract had EXPIRED.
+  const row = s.milestoneStatus ?? s.contractStatus;
+  return row === "EXPIRED" || row === "COMPLETED" ? row : null;
+}
+
+/**
+ * What happened to the money, from `terminalReason`. EXPIRED is not one story:
+ * `RELEASED_ON_CHAIN` means the chain shows the builder WAS paid (just not by this
+ * verification); the others mean the funder got the escrow back, or none existed. The
+ * vocabulary is `src/lib/terminal-reason.ts`; an absent or unknown value says so
+ * rather than guessing.
+ */
+function terminalStory(reason, row) {
+  switch (reason) {
+    case "RELEASED_ON_CHAIN":
+      return "The chain shows this milestone's escrow WAS released to the builder before it was closed — the builder was paid, but not by this verification.";
+    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 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 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.`;
+  }
+}
+
+/** The outcome line for a proof whose milestone is terminal and not COMPLETED. */
+function closedOutcomeLine(s, closed) {
+  const row = proofRowNoun(s);
+  const verdict = s.decision
+    ? `The panel's verdict on this proof was ${s.decision}${s.confidence != null ? ` (confidence: ${s.confidence}%)` : ""}, and it changed nothing.`
+    : "No verdict was recorded for this proof.";
+  return (
+    `⛔ CLOSED — the ${row} was closed (${closed}) while the panel ran or after it decided, so this verification moved no funds. ` +
+    `${terminalStory(s.terminalReason, row)} ${verdict} There is nothing to poll for and nothing to resubmit to this ${row}.`
+  );
+}
+
 
 /**
  * One `verify/standalone` call under a client deadline (SEC-073).
@@ -1304,13 +1845,75 @@ async function withStandaloneDeadline(run) {
 }
 
 /**
- * `pending` means `aiDecision === null`, which has two causes that read the same and
- * are NOT the same thing: verification is still running, or the panel never reached a
- * verdict and the proof was parked for human review with `aiDecision` deliberately
- * left null. Told to keep polling, an agent polls FOREVER on the second one.
+ * "milestone", or "contract" for a legacy contract-level proof — which has no milestone,
+ * so a message telling the agent to "check the milestone" sent it looking for nothing.
+ * `milestoneStatus` is null exactly when the proof has no milestone row.
+ */
+function proofRowNoun(s) {
+  return s.milestoneStatus == null ? "contract" : "milestone";
+}
+
+/**
+ * True when the milestone is approved (VERIFIED) or paid (COMPLETED) and this proof has
+ * no YES of its own: another proof won it, or the funder approved it in review — which
+ * leaves this proof's `aiDecision` untouched (NO, or null after a panel outage).
+ *
+ * Either way nothing is left for THIS proof to decide. `/api/verify`'s claim excludes
+ * VERIFIED and COMPLETED for every verdict, so a pending proof here can never move the
+ * row: polling it burned the whole watch timeout, and `get_proof_status` said "poll
+ * again" for good. `/api/verify`'s SSE answered SUPERSEDED for the same state.
+ */
+function approvedWithoutThisVerdict(s) {
+  // Except while this proof's panel is RUNNING on a VERIFIED row. VERIFIED is not sticky:
+  // a definite release failure rolls it back, `contracts/review` hands it back to
+  // PENDING_REVIEW and the cron's hand-back blocks do the same, and a running claim then
+  // decides the row after all. COMPLETED is terminal and stays final either way.
+  // `running` is absent on a server that predates it, which keeps the old reading.
+  const row = closedMilestoneStatus(s) === "COMPLETED" ? "COMPLETED" : (s.milestoneStatus ?? s.contractStatus);
+  if (s.decision === "YES") return false;
+  return row === "COMPLETED" || (row === "VERIFIED" && s.running !== true);
+}
+
+/** Final: no later poll can change what this proof status says. */
+function nothingLeftToDecide(s) {
+  return closedMilestoneStatus(s) !== null || s.notCompletableWithoutEscrow === true || approvedWithoutThisVerdict(s);
+}
+
+/** The outcome line for `approvedWithoutThisVerdict`. It never says THIS proof was approved. */
+function approvedWithoutThisVerdictLine(s) {
+  const row = proofRowNoun(s);
+  const ROW = row.toUpperCase();
+  const head =
+    closedMilestoneStatus(s) === "COMPLETED"
+      ? `✅ ${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}%` : ""}).`
+      : "This proof has no panel verdict of its own.";
+  return (
+    `${head}, but not on this proof's verdict: another proof on this ${row}, or the funder's review, approved it. ` +
+    `${verdict} Nothing is left for this proof to decide — do not poll it and do not resubmit to this ${row}.`
+  );
+}
+
+/**
+ * `pending` means "no verdict on this proof": `aiDecision` is null (not claimed yet, or
+ * the panel never reached a verdict and the proof was parked for human review with
+ * `aiDecision` deliberately left null) or the claim sentinel "PENDING" (`/api/verify`'s
+ * panel is running on it). Those are NOT the same thing: told to keep polling, an agent
+ * polls FOREVER on a parked proof — and told to stop, it abandons a running one.
+ *
+ * `running` separates them. A proof whose panel is RUNNING is not parked even on a
+ * PENDING_REVIEW row: a sibling proof in the 60-85 band parked the milestone there while
+ * this one's panel still runs, and this one's claim can overwrite PENDING_REVIEW and go
+ * on to COMPLETED. Only a server that sends `running` can say so; without it the old
+ * reading stays.
  */
 function parkedForHuman(s) {
-  return Boolean(s.pending) && 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 =
@@ -1321,18 +1924,35 @@ const PARKED_MESSAGE =
 async function handleGetProofStatus({ proofId }) {
   const data = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`);
 
-  // `pending` means `aiDecision === null`, which has two causes that read the same and
-  // are NOT the same thing: verification is still running, or the panel never reached a
-  // verdict and the proof was parked for human review with `aiDecision` deliberately
-  // left null (`agent/proof-status` keeps it null by design there). Told to "poll again
-  // in a few seconds", an agent polls FOREVER on the second one. `milestoneStatus`
-  // separates them: a milestone already at PENDING_REVIEW is not waiting on a panel
-  // run, it is waiting on a person. `src/app/api/mcp/route.ts` has split these since
-  // SEC-010; this file, the published one, did not.
-  if (data.pending) {
+  // `pending` means "no verdict on this proof", which has two causes that read the same
+  // and are NOT the same thing: verification is still running (the claim sentinel, or
+  // not claimed yet), or the panel never reached a verdict and the proof was parked for
+  // human review with `aiDecision` deliberately left null (`agent/proof-status` keeps it
+  // null by design there). Told to "poll again in a few seconds", an agent polls FOREVER
+  // on the second one. `milestoneStatus` separates them: a milestone already at
+  // PENDING_REVIEW is waiting on a person — unless `running` says this proof's own panel
+  // is still going, which can still decide that row (`parkedForHuman`).
+  // `src/app/api/mcp/route.ts` has split these since SEC-010; this file, the published
+  // one, did not.
+  //
+  // A CLOSED milestone is asked first: an outage that lost to EXPIRED leaves
+  // `aiDecision` null for good on a row no verdict can move, and "poll again" would
+  // loop forever on it exactly like the parked case.
+  if (data.pending && !nothingLeftToDecide(data)) {
     if (parkedForHuman(data)) {
       return { ...data, message: `Proof ${proofId}: ${PARKED_MESSAGE}` };
     }
+    // An interrupted run (claimPhase "orphaned") reads as `pending` too, and "poll
+    // again" would send the agent into a loop nothing ends — the poll loops stop on
+    // it; this single read has to say it as well (F-50: same field, two doors).
+    if (data.claimPhase === "orphaned") {
+      return {
+        ...data,
+        message:
+          `The last verification run for proof ${proofId} was interrupted and nothing is running now. ` +
+          "Once its claim is an hour old, cascrow_verify can start it again — or submit the proof again, which always works.",
+      };
+    }
     return {
       ...data,
       message: `Proof ${proofId} is still being processed by the AI. Poll again in a few seconds.`,
@@ -1342,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 = [
@@ -1360,13 +1980,27 @@ async function handleGetProofStatus({ proofId }) {
 }
 
 async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
-  const data = await apiPost("/api/mcp/submit", { contract_id, milestone_id, evidence });
+  const data = await apiPost("/api/mcp/submit", { contract_id, milestone_id, evidence }, MCP_SUBMIT_CLIENT_ABORT_MS);
 
   const confidence = data.confidence ?? 0;
   const onChainUrl = data.on_chain_url ?? null;
   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.
@@ -1376,19 +2010,25 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
   // `src/app/api/mcp/route.ts` has handled this since someone hit it once already;
   // this file, the published one, never did.
   if (data.decided === "elsewhere") {
+    // `settledAs` names a TERMINAL row (EXPIRED, COMPLETED). EXPIRED is a funder cancel or
+    // the deadline cron, not "the investor's review, or a concurrent submission" — and the
+    // wording must not claim WHEN it closed relative to this submission.
+    const settledAs = typeof data.settledAs === "string" ? data.settledAs : null;
     return {
       verdict: "decided_elsewhere",
+      ...(settledAs ? { settledAs } : {}),
       confidence: null,
       reasoning: "",
       ...markVerificationResult({ model_votes: [] }),
       on_chain_url: null,
       proof_id: proofId,
-      release_hold_until: null,
       signed_at: null,
-      message:
-        "ℹ️ This milestone was decided by another request while your proof was being verified — " +
-        "by the investor's review, or by a concurrent submission. Your evidence was recorded. " +
-        "Check the milestone status before resubmitting; a resubmission will be refused if it is already settled.",
+      message: settledAs
+        ? `ℹ️ This milestone was closed (${settledAs}) before this submission could settle it, so this submission changed nothing and moved no funds itself. ` +
+          "Your evidence was recorded. Do not resubmit to this milestone."
+        : "ℹ️ This milestone was decided by another request while your proof was being verified — " +
+          "by the investor's review, or by a concurrent submission. Your evidence was recorded. " +
+          "Check the milestone status before resubmitting; a resubmission will be refused if it is already settled.",
     };
   }
 
@@ -1409,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: ` +
@@ -1420,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 {
@@ -1449,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)}` : ""}`,
   };
@@ -1489,7 +2123,7 @@ async function handleVerifyWork({ taskDescription, prUrl, codeText, imageBase64,
       // The body is read INSIDE the deadline. A response whose headers arrived
       // and whose body then stalls is otherwise unbounded — a deadline that ends
       // at the headers bounds time-to-first-byte and nothing else (SEC-073).
-      return { res: r, data: await r.json() };
+      return { res: r, data: await readJsonSafe(r) };
     });
     if (!res.ok) throw standaloneFailure(res.status, body);
     // Assigned to the OUTER `data`, not shadowing it: `const { data }` inside the
@@ -1511,7 +2145,7 @@ async function handleVerifyWork({ taskDescription, prUrl, codeText, imageBase64,
       // The body is read INSIDE the deadline. A response whose headers arrived
       // and whose body then stalls is otherwise unbounded — a deadline that ends
       // at the headers bounds time-to-first-byte and nothing else (SEC-073).
-      return { res: r, data: await r.json() };
+      return { res: r, data: await readJsonSafe(r) };
     });
     if (!res.ok) throw standaloneFailure(res.status, body);
     // Assigned to the OUTER `data`, not shadowing it: `const { data }` inside the
@@ -1545,28 +2179,52 @@ async function handleVerifyWork({ taskDescription, prUrl, codeText, imageBase64,
   };
 }
 
-async function handleWatchVerification({ milestoneId, content, filename }) {
-  // Submit proof using existing multipart upload helper
-  const submitData = await uploadProof(milestoneId, filename ?? "proof-report.txt", content);
-  const proofId = submitData.proofId;
-  if (!proofId) {
-    throw new Error(submitData.error ?? "Proof submission failed — no proofId returned");
-  }
-
-  // Poll until verification completes (max 100s, every 5s)
-  const MAX_WAIT_MS = 100_000;
-  const POLL_MS = 5_000;
+/**
+ * Poll proof-status until the proof has an outcome worth returning, or `maxMs` runs
+ * out (then `null`). Shared by cascrow_watch_verification (both modes) and by
+ * cascrow_verify when its start lost to a run already going (T01-5).
+ *
+ * What stops the loop early, and why each is safe:
+ *   - 401 / 403: waiting does not change who you are.
+ *   - 404: permanent. proof/upload answers with a proofId only after the Proof row
+ *     exists, and proof-status reads the primary database (there is no replica), so
+ *     a 404 means the proof was deleted or erased, not "not there yet".
+ *   - `claimPhase: "orphaned"`: the run that held the claim is dead; nothing is
+ *     running to wait for.
+ * 429 / 503 wait at least what the server asked (Retry-After), never past `maxMs`.
+ * Anything else — a network error, a 5xx — is transient: poll again.
+ */
+async function pollUntilSettled(proofId, maxMs = 100_000, pollMs = 5_000) {
   const started = Date.now();
-
-  while (Date.now() - started < MAX_WAIT_MS) {
-    await new Promise((r) => setTimeout(r, POLL_MS));
+  let waitMs = pollMs;
+  while (Date.now() - started < maxMs) {
+    await new Promise((r) => setTimeout(r, waitMs));
+    waitMs = pollMs;
     let status;
     try {
       status = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`);
-    } catch {
-      continue; // transient error — keep polling
+    } catch (e) {
+      const code = e && typeof e.status === "number" ? e.status : null;
+      if (code === 401 || code === 403 || code === 404) {
+        return {
+          pending: true,
+          proofId,
+          stopped: { status: code, code: e.code ?? null },
+          message:
+            code === 404
+              ? `Stopped waiting: proof ${proofId} no longer exists (it was deleted or erased). Nothing will verify it.`
+              : `Stopped waiting for proof ${proofId}: ${e.message}. Waiting does not change this — check the API key and that this account is a party to the contract.`,
+        };
+      }
+      if ((code === 429 || code === 503) && typeof e.retryAfterSeconds === "number") {
+        // At least what the server asked, never past this loop's own budget.
+        waitMs = Math.min(Math.max(pollMs, e.retryAfterSeconds * 1000), Math.max(0, maxMs - (Date.now() - started)));
+      }
+      continue; // transient — keep polling
     }
-    if (!status.pending) {
+    // A closed milestone is terminal whether or not a verdict landed: waiting out the
+    // loop on a row no verdict can move burns the whole budget and then says "poll again".
+    if (!status.pending || nothingLeftToDecide(status)) {
       return {
         ...status,
         proofId,
@@ -1574,24 +2232,68 @@ async function handleWatchVerification({ milestoneId, content, filename }) {
       };
     }
     // Parked for a human: `pending` stays true forever on this path, so without this
-    // the loop burns its whole 100s and then tells the agent to poll some more.
+    // the loop burns its whole budget and then tells the agent to poll some more.
     if (parkedForHuman(status)) {
       return { ...status, proofId, message: `Proof ${proofId}: ${PARKED_MESSAGE}` };
     }
+    if (status.claimPhase === "orphaned") {
+      return {
+        ...status,
+        proofId,
+        message:
+          `The last verification run for proof ${proofId} was interrupted and nothing is running now. ` +
+          "Once its claim is an hour old, cascrow_verify can start it again — or submit the proof again, which always works. " +
+          "(If cascrow_verify then refuses with \"cannot be restarted automatically\", submit the proof again or contact support.)",
+      };
+    }
   }
+  return null;
+}
+
+function stillRunningResult(proofId) {
+  return {
+    pending: true,
+    proofId,
+    message: `Verification is still in progress. Wait for it with cascrow_watch_verification { proofId: "${proofId}" } or poll cascrow_get_proof_status.`,
+  };
+}
+
+async function handleWatchVerification({ milestoneId, content, filename, proofId: existingProofId } = {}) {
+  // Two modes, exactly one per call: SUBMIT (milestoneId + content) uploads and then
+  // waits; ATTACH (proofId) only waits — for a proof already submitted, whose
+  // verification upload started by itself.
+  const attach = typeof existingProofId === "string" && existingProofId.length > 0;
+  const submit = typeof content === "string" && typeof milestoneId === "string";
+  if (attach === submit) {
+    throw new Error(
+      "Give EITHER proofId (wait for a proof already submitted) OR milestoneId + content (submit, then wait) — not both, not neither."
+    );
+  }
+
+  let proofId = existingProofId;
+  if (submit) {
+    const submitData = await uploadProof(milestoneId, filename ?? "proof-report.txt", content);
+    proofId = submitData.proofId;
+    if (!proofId) {
+      throw new Error(submitData.error ?? "Proof submission failed — no proofId returned");
+    }
+  }
+
+  const settled = await pollUntilSettled(proofId, 100_000);
+  if (settled) return settled;
 
   // Timed out — return proofId so agent can poll manually
   return {
     pending: true,
     proofId,
-    message: `Verification still in progress after ~100s. Poll the result with cascrow_get_proof_status using proofId: ${proofId}`,
+    message: `Verification still in progress after ~100s. Wait again with cascrow_watch_verification { proofId: "${proofId}" } or poll cascrow_get_proof_status.`,
   };
 }
 
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "cascrow", version: "1.6.2" },
+  { name: "cascrow", version: "3.0.0" },
   { capabilities: { tools: {} } }
 );
 
@@ -1602,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,
@@ -1618,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;
@@ -1632,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;
@@ -1645,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,
     };
   }