cascrow-cli 1.3.0 → 3.0.0

package/index.js

@@ -6,10 +6,91 @@
  */
 
 import { readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
 
 const BASE_URL = process.env.CASCROW_BASE_URL ?? "https://cascrow.com";
 const API_KEY  = process.env.CASCROW_API_KEY ?? "";
 
+// 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(" ");
+}
+
+/**
+ * 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;
+}
+
 // ─── HTTP helpers ─────────────────────────────────────────────────────────────
 // Authorization header is omitted entirely when key is empty, rather than
 // sending a garbage "Bearer " token — matters for `verify-work`, the one
@@ -19,20 +100,91 @@ function authHeader(key) {
   return key ? { "Authorization": `Bearer ${key}` } : {};
 }
 
-async function apiPost(path, body, key = API_KEY) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: {
-      ...authHeader(key),
-      "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 (T11-A4). This package cannot import src/, so the one with an
+// owner is MIRRORED 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 is 235 s like the stream (one step below its 240 s cap); everything
+// else gets the longest maxDuration any route has. None of these calls had a
+// deadline before.
+const UPLOAD_CLIENT_ABORT_MS = 120_000;
+const MCP_SUBMIT_CLIENT_ABORT_MS = 235_000;
+const REQUEST_CLIENT_ABORT_MS = 300_000;
+
+/** A response body parsed without trusting it to be JSON: an HTML 502 reads "HTTP 502 (non-JSON response from server)". */
+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" };
+  }
+}
+
+/** Seconds the server asked us to wait: Retry-After, else `retry_after_seconds`. */
+function retryAfterOf(res, data) {
+  const header = res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : null;
+  if (header !== null && /^\d+$/.test(header.trim())) return Number(header.trim());
+  return typeof data?.retry_after_seconds === "number" ? data.retry_after_seconds : null;
+}
+
+/**
+ * The one way this CLI calls the API. Throws an Error carrying `status`, `code` and
+ * `retryAfterSeconds`; its message ends with the code in brackets, so a script that
+ * greps stderr can branch on it. The deadline covers the body read.
+ */
+async function fetchJson(method, path, { json, form, key = API_KEY, deadlineMs = REQUEST_CLIENT_ABORT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), deadlineMs);
+  let res;
+  let data;
+  try {
+    res = await fetch(`${BASE_URL}${path}`, {
+      method,
+      headers: { ...authHeader(key), ...(json !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(json !== undefined ? { body: JSON.stringify(json) } : form !== undefined ? { body: form } : {}),
+      signal: controller.signal,
+    });
+    data = await readJsonSafe(res);
+  } catch (e) {
+    if (e && e.name === "AbortError") {
+      throw Object.assign(
+        new Error(`No answer from ${path} within ${Math.round(deadlineMs / 1000)} s. The request may still complete on the server — check its result before repeating it. [CLIENT_TIMEOUT]`),
+        { status: 0, code: "CLIENT_TIMEOUT", retryAfterSeconds: null }
+      );
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok || data.code === "UPSTREAM_NON_JSON") {
+    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 Object.assign(
+      new Error(
+        `${base}${retryAfterSeconds !== null && (res.status === 429 || res.status === 503) ? ` — retry after ${retryAfterSeconds} s` : ""}${code ? ` [${code}]` : ""}` +
+          (mayHaveCompleted ? ". The request may still have completed on the server — check the contract (cascrow get --contract <id>) before repeating it." : "") +
+          // A MilestoneEscrowV3 refusal says who can act and how (F-72): the body's actionable
+          // fields (G5), then the owner's words, role-aware on the body (H9).
+          (v3RefusalDetail(data) ? ` — ${v3RefusalDetail(data)}` : "") +
+          (v3HintFor(code, data) ? `\n\n${v3HintFor(code, data)}` : "")
+      ),
+      { status: res.status, code, retryAfterSeconds }
+    );
+  }
   return data;
 }
 
+async function apiPost(path, body, key = API_KEY, deadlineMs = REQUEST_CLIENT_ABORT_MS) {
+  return fetchJson("POST", path, { json: body, key, deadlineMs });
+}
+
 // SEC-078. A failed standalone verification still has a row, and the route answers
 // the 500 with `id`, `publicHash` and `reportUrl` so the caller who paid for it can name it. The
 // CLI only prints a string, so the reference goes into the string. Both request
@@ -46,12 +198,7 @@ function standaloneFailure(status, data) {
 }
 
 async function apiGet(path, key = API_KEY) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    headers: { ...authHeader(key) },
-  });
-  const data = await res.json();
-  if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
-  return data;
+  return fetchJson("GET", path, { key });
 }
 
 async function uploadProof(milestoneId, filename, content, key = API_KEY) {
@@ -59,14 +206,7 @@ async function uploadProof(milestoneId, filename, content, key = API_KEY) {
   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(key) },
-    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, key, deadlineMs: UPLOAD_CLIENT_ABORT_MS });
 }
 
 // Stream verify via SSE — used by the legacy two-step `submit` + `verify --proof <id>` flow
@@ -112,8 +252,21 @@ async function streamVerify(proofId, key = API_KEY) {
     // 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 data = await readJsonSafe(res);
+    // T01-8. Upload starts verification by itself, so losing the claim to a RUNNING
+    // run is the normal case: wait for that run through proof-status instead of
+    // failing. This 409's Retry-After is the ~1 h takeover cutoff, never a wait.
+    if (res.status === 409 && data.code === "VERIFICATION_IN_PROGRESS" && data.phase === "running") {
+      process.stderr.write("  A verification of this proof is already running — waiting for it instead of starting another.\n");
+      const budgetMs = Math.max(30_000, Math.min(235_000, ((data.expected_done_in_seconds ?? 200) + 30) * 1000));
+      return { attached: true, status: await waitForProof(proofId, budgetMs, key) };
+    }
+    const code = typeof data.code === "string" ? data.code : null;
+    throw Object.assign(new Error(`${data.error ?? `HTTP ${res.status}`}${code ? ` [${code}]` : ""}`), {
+      status: res.status,
+      code,
+      retryAfterSeconds: retryAfterOf(res, data),
+    });
   }
   if (!res.body) {
     clearTimeout(timeout);
@@ -178,6 +331,90 @@ async function streamVerify(proofId, key = API_KEY) {
   throw new Error("Stream ended without a complete event");
 }
 
+/**
+ * Poll proof-status until the proof settles, the run is found dead, or `maxMs` runs
+ * out. Returns the last status read, with `stoppedBecause` set when it stopped early:
+ *   - 401 / 403: waiting does not change the key or the account;
+ *   - 404: permanent — upload answers only after the proof exists and proof-status
+ *     reads the primary database, so the proof was deleted or erased;
+ *   - "interrupted": the run that held the proof died (claimPhase "orphaned").
+ * 429 / 503 wait at least Retry-After, never past the budget; anything else is
+ * transient. A milestone that is closed, or parked for a human, also settles it.
+ */
+async function waitForProof(proofId, maxMs = 100_000, key = API_KEY, pollMs = 5_000) {
+  const started = Date.now();
+  let waitMs = pollMs;
+  let last = null;
+  while (Date.now() - started < maxMs) {
+    await new Promise((r) => setTimeout(r, waitMs));
+    waitMs = pollMs;
+    try {
+      last = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`, key);
+    } catch (e) {
+      if (e && (e.status === 401 || e.status === 403 || e.status === 404)) {
+        return { pending: true, proofId, stoppedBecause: e.status, error: e.message };
+      }
+      if (e && (e.status === 429 || e.status === 503) && typeof e.retryAfterSeconds === "number") {
+        waitMs = Math.min(Math.max(pollMs, e.retryAfterSeconds * 1000), Math.max(0, maxMs - (Date.now() - started)));
+      }
+      continue;
+    }
+    // `notCompletableWithoutEscrow`: no verdict can complete this milestone — final.
+    if (!last.pending || last.milestoneClosed === true || last.notCompletableWithoutEscrow === true) return { ...last, proofId };
+    // Parked for a human: no poll will change it (same rule as both MCP servers).
+    // Never a MilestoneEscrowV3 proof (post-review L2): no human review decides one.
+    if (last.escrowVersion !== 3 && last.running !== true && last.milestoneStatus === "PENDING_REVIEW") return { ...last, proofId, awaitingHumanReview: true };
+    if (last.claimPhase === "orphaned") return { ...last, proofId, stoppedBecause: "interrupted" };
+  }
+  return { ...(last ?? {}), pending: true, proofId, timedOut: true };
+}
+
+/** One line for a proof-status result, saying whether funds moved. */
+function statusSummary(s) {
+  if (s.stoppedBecause === 404) return `⛔ Proof ${s.proofId} no longer exists (deleted or erased). Nothing will verify it.`;
+  if (s.stoppedBecause === 401 || s.stoppedBecause === 403) return `⛔ Stopped: ${s.error}. Waiting does not change this — check CASCROW_API_KEY and that this account is a party to the contract.`;
+  if (s.stoppedBecause === "interrupted") {
+    // Not "re-run automatically": a claim with no timestamp is never taken over, and
+    // the retry cron skips demo contracts and milestones past PROOF_SUBMITTED.
+    return `⚠️ The last verification run was interrupted; nothing is running now. Once its claim is an hour old, \`cascrow verify --proof ${s.proofId}\` can start it again — or submit the proof again, which always works.`;
+  }
+  if (s.awaitingHumanReview) return "⏳ PENDING_REVIEW — the panel reached no verdict; a human decides. Waiting will not change it.";
+  if (s.timedOut) return `⏳ Still verifying. Check again: cascrow status --proof ${s.proofId} --wait`;
+  const conf = typeof s.confidence === "number" ? ` (${s.confidence}% confidence)` : "";
+  // MilestoneEscrowV3 (post-review G4): the verdict is a RECOMMENDATION and moves no money.
+  // Asked before every v2 arm — the claim-relevant answer is the SUBMISSION's verdict
+  // (`submissionVerdict`, `claimReady`), never this proof's `decision`, and a closed or
+  // COMPLETED V3 milestone was settled on chain by the parties.
+  if (s.escrowVersion === 3 && !(s.milestoneStatus === "COMPLETED" || s.milestoneClosed === true)) {
+    const line = V3_CLIENT_TEXT.recommendation.replace("{verdict}", s.submissionVerdict ?? "PENDING").replace("{confidence}", String(s.confidence ?? 0));
+    return s.manifestHash ? `${line} manifestHash: ${s.manifestHash}` : line;
+  }
+  if (s.escrowVersion === 3) {
+    return s.milestoneStatus === "COMPLETED"
+      ? "✅ COMPLETED — the MilestoneEscrowV3 escrow paid out on chain."
+      : `⛔ CLOSED — the milestone is ${s.terminalStatus ?? "closed"}; the MilestoneEscrowV3 escrow settled on chain. Do not resubmit to it.`;
+  }
+  // COMPLETED first: proof-status reports a paid milestone as `milestoneClosed` too
+  // (terminalStatus COMPLETED), and the CLOSED arm below would read a release as
+  // "moves no funds" — SEC-059's inversion (same order as proofOutcomeLine in both
+  // MCP servers). Whether it was THIS proof's YES is `decision`.
+  if (s.milestoneStatus === "COMPLETED" || s.terminalStatus === "COMPLETED") {
+    return s.decision === "YES" ? `✅ COMPLETED${conf} — no money was held (verification-only contract).` : `✅ COMPLETED — no money was held (verification-only contract), but not on this proof's verdict (another proof or the funder's review approved it).`;
+  }
+  if (s.milestoneClosed === true) {
+    return s.terminalReason === "RELEASED_ON_CHAIN"
+      ? "⛔ CLOSED (EXPIRED) — the chain shows the builder WAS paid, just not by this verification."
+      : `⛔ CLOSED — the milestone is ${s.terminalStatus ?? "closed"}; this verification moved no funds. Do not resubmit to it.`;
+  }
+  // An approval cannot complete this milestone (an amount without a MilestoneEscrowV3
+  // escrow); the verdict doors answered 409 NOT_COMPLETABLE_WITHOUT_ESCROW.
+  if (s.notCompletableWithoutEscrow === true) return `⛔ NOT COMPLETABLE — ${V3_CLIENT_TEXT.codeHints.NOT_COMPLETABLE_WITHOUT_ESCROW}`;
+  if (s.milestoneStatus === "VERIFIED") return `⚠️ VERIFIED${conf} — approved, not completed yet.`;
+  if (s.milestoneStatus === "PENDING_REVIEW") return `⏳ PENDING_REVIEW${conf} — manual review required.`;
+  if (s.decision === "NO") return `❌ REJECTED${conf}.`;
+  return `ℹ️ Decision: ${s.decision ?? "none"}${conf}, milestone ${s.milestoneStatus ?? "unknown"}.`;
+}
+
 /**
  * One human-readable line for a verification `complete` frame.
  *
@@ -188,22 +425,34 @@ async function streamVerify(proofId, key = API_KEY) {
  */
 function outcomeLine(r) {
   const c = r.confidence ?? 0;
+  // MilestoneEscrowV3: a recommendation that moves nothing — asked first, so no arm
+  // below can read it as a payout or a rejection.
+  if (r.action === "V3_RECOMMENDATION") {
+    // The SUBMISSION's verdict, never the panel's `decision` on one file.
+    return V3_CLIENT_TEXT.recommendation.replace("{verdict}", r.submissionVerdict ?? "PENDING").replace("{confidence}", String(c));
+  }
   if (r.action === "SUPERSEDED") {
-    return "ℹ️ SUPERSEDED — another proof on this milestone was decided first, so this verification changed nothing. Your evidence was recorded.";
+    // `settledAs`: the milestone was closed (e.g. EXPIRED) before this verification could
+    // settle it, not beaten by a proof.
+    return r.settledAs
+      ? `ℹ️ SUPERSEDED — this milestone was closed (${r.settledAs}) before this verification could settle it, so it changed nothing and moved no funds. Do not resubmit to it.`
+      : "ℹ️ SUPERSEDED — another proof on this milestone was decided first, so this verification changed nothing. Your evidence was recorded.";
   }
   if (r.action === "COMPLETED") {
     return r.alreadyReleased === true
-      ? "✅ COMPLETED — this milestone was already released by another request. The funds are out; do not resubmit."
-      : `✅ COMPLETED (${c}% confidence) — funds released${r.txHash ? `, tx ${r.txHash}` : ""}.`;
+      ? `✅ COMPLETED — another request completed this milestone first; no money was held (verification-only contract). Do not resubmit.`
+      : `✅ COMPLETED (${c}% confidence) — no money was held (verification-only contract)${r.txHash ? `, tx ${r.txHash}` : ""}.`;
   }
   if (r.complianceBlocked === true) {
     return `⏸️ VERIFIED (${c}%) — payout on hold pending compliance review. No funds moved.`;
   }
-  if (r.releaseHoldUntil) {
-    return `⏸️ VERIFIED (${c}% confidence) — approved, payout scheduled for ${r.releaseHoldUntil}. NO FUNDS HAVE MOVED YET: the funder can contest until then, and the date can move.`;
+  if (r.action === "NOT_COMPLETABLE_WITHOUT_ESCROW") {
+    return `⛔ NOT COMPLETED (${c}% confidence) — ${V3_CLIENT_TEXT.codeHints.NOT_COMPLETABLE_WITHOUT_ESCROW}`;
   }
   if (r.action === "VERIFIED") {
-    return `⚠️ VERIFIED (${c}% confidence) — the work was approved, but the automatic payout did NOT go through. No funds have moved; the release can be retried.`;
+    // Approved, but no completion followed; the producer does not reach this since
+    // Phase 6. No retry is promised — there is nothing to retry.
+    return `⚠️ VERIFIED (${c}% confidence) — the work was approved, but the milestone was NOT completed. No money moved. Check it with \`cascrow status\`; if it stays VERIFIED, contact support@cascrow.com.`;
   }
   if (r.timedOut === true) {
     return "⏳ 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.";
@@ -285,7 +534,7 @@ function err(msg) {
 
 function usage() {
   console.log(`
-Cascrow CLI — agentic escrow and verification
+cascrow CLI — AI verification, on-chain reputation and non-custodial escrow for agents
 
 Usage:
   cascrow <command> [options]
@@ -295,15 +544,18 @@ Commands:
   verify-work   Verify AI-generated work — no contract, no escrow, no account needed
   verify        Submit proof and get AI verdict in one call (recommended)
   create        Create a milestone contract
-  fund          Activate a milestone (simulation — no on-chain tx)
-  escrow-fund   Fund a milestone with real on-chain RLUSD escrow
-  submit        Upload proof text (returns proofId for legacy verify flow)
+  submit        Upload proof text — verification starts by itself (then: status --proof <id> --wait)
+  status        Show (or --wait for) the verification result of a proof
   get           Get contract status and milestones
   join          Join a contract as Builder via invite code
   handoff       Send a contract invite to a Builder agent by Agent ID
   check-invites Check pending contract invites for this agent
   review-queue  As funder: list milestones still waiting for your verdict
   review        As funder: approve or reject a milestone under manual review
+  v3-claims     As payer: list MilestoneEscrowV3 claims you can still object to on chain
+  v3 <sub>      MilestoneEscrowV3, remote half: offer | acceptance | accept-submit | prepare | report-tx | attestation | claims
+                and "v3 sign <cascrow-signer command…>" — runs the pinned local signer (npx cascrow-signer@0.1.0),
+                which holds your key on YOUR machine. cascrow never signs, sends or relays for you.
   me            Print this agent's ID
 
 Options for each command:
@@ -328,25 +580,25 @@ Options for each command:
     --commit <sha>          optional  Git commit SHA or PR URL
 
   create
-    --title <title>         required  milestone title + acceptance criteria
+    --title <title>         required  short milestone title (printed on the certificate)
     --days <n>              optional  deadline days from now (default: 7)
-    --amount <usd>          optional  RLUSD to lock in escrow (default: 0 = verification-only)
-
-  fund
-    --contract <id>         required
-    --milestone <id>        optional  defaults to first available
-
-  escrow-fund  [REAL on-chain RLUSD — agent's own wallet]
-    --contract <id>         required
-    --private-key <key>     required  EVM private key (funds come from this wallet)
-    --amount <usd>          IGNORED   the escrowed amount is the milestone's own amountUSD
-    --milestone <id>        optional
-
-  submit  [legacy: use verify instead]
+    --amount <usd>          optional  default 0 = verification-only (active once the builder joins). Above 0 the
+                                      milestone is a MilestoneEscrowV3 escrow in native XRP: offer it with
+                                      "cascrow v3 offer", the builder accepts, you fund with "cascrow v3 sign fund"
+    --criteria <text>       optional  what the AI panel checks the proof against (max 4000 chars)
+    --criteria-file <path>  optional  the same, read from a file
+    --checklist-file <path> optional  JSON array of { title, severity?, id? } (max 20) scored item by item on text proofs
+    --review-mode <mode>    optional  AUTO | MANUAL | MANUAL_AUTO — what happens when the panel is unsure (60–85%)
+
+  submit  [or use verify for text proof in one call]
     --milestone <id>        required
     --proof <text>          required
     --file <name>           optional  filename (default: proof-report.txt)
 
+  status
+    --proof <id>            required
+    --wait                  optional  wait up to ~2 min for the verdict; stops early when waiting cannot help
+
   get
     --contract <id>         required
 
@@ -375,15 +627,13 @@ Examples:
   # Register a new agent account (no human in the loop)
   cascrow register --email bot@example.com --password secret123
 
-  # One-shot: create contract, fund it, then verify a code fix
-  cascrow create --title "Fix auth bug — all tests must pass" --days 7
-  cascrow fund --contract <contractId>
+  # One-shot: create a verification-only contract (active once the builder joins), then verify a code fix
+  cascrow create --title "Fix auth bug" --criteria "All tests pass; JWT expiry honoured; no new lint errors" --days 7
   cascrow verify --contract <contractId> --proof "Fixed JWT expiry bug in auth.ts, 42 tests green, PR #51 merged" --commit abc1234 --links https://github.com/you/repo/pull/51
 
-  # Real escrow flow (RLUSD locked on-chain)
-  cascrow create --title "Deploy API" --amount 100 --days 14
-  cascrow escrow-fund --contract <contractId> --private-key 0x...
-  cascrow verify --contract <contractId> --proof "API live at https://api.example.com, all endpoints responding"
+  # Paid work is a MilestoneEscrowV3 escrow (native XRP, testnet): create with --amount,
+  # offer it (cascrow v3 offer), the builder accepts, and you fund with one transaction
+  # from your own machine (cascrow v3 sign fund). This CLI never takes a key.
 
   # Agent-to-agent handoff
   cascrow me                                    # → get your Agent ID
@@ -395,14 +645,88 @@ Examples:
 
   # As the funder: decide what the AI panel could not (confidence 60-85)
   # Poll this — a manual_review.required webhook you missed is a decision nobody
-  # makes, and cascrow auto-approves an undecided milestone after 48h.
+  # makes; an undecided milestone completes automatically after 48h under review mode
+  # MANUAL_AUTO or AUTO, 14 days otherwise.
+  # Verification-only contracts: a verdict completes or hands back, and moves no money.
   cascrow review-queue
   cascrow review --contract <contractId> --decision APPROVE
   cascrow review --contract <contractId> --decision REJECT --milestone <milestoneId>
+
+  # As the payer of a MilestoneEscrowV3 escrow: claims release unless YOUR wallet
+  # calls object(escrowId) before the deadline — cascrow cannot object for you.
+  cascrow v3-claims
+
+  # MilestoneEscrowV3 (native XRP). cascrow prepares and reads; you sign locally.
+  cascrow v3 offer --milestone <id> --review-period-sec 259200 [--watcher] [--arbiter 0x… --arbitration-period-sec N]
+  cascrow v3 acceptance --milestone <id>                 # as builder: the frozen terms to check
+  cascrow v3 sign accept --milestone <id> --network testnet   # check + sign locally (pinned cascrow-signer)
+  cascrow v3 sign fund --milestone <id> --network testnet     # as payer: one transaction, value = amount
+  cascrow v3 prepare --milestone <id> --action object --reason-hash 0x…   # UNSIGNED — verify before signing
+  cascrow v3 report-tx --milestone <id> --tx 0x<64 hex>  # a HASH only, never a signed transaction
+  cascrow v3 attestation --escrow 0x… --claim-index 1    # non-binding AI recommendation
 `);
   process.exit(0);
 }
 
+// ─── 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.
+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;
+}
+
 // ─── Argument parser ──────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -439,8 +763,8 @@ async function cmdRegister(args) {
       keyName: args["key-name"] ?? "cli",
     }),
   });
-  const data = await res.json();
-  if (!res.ok) err(data.error ?? `HTTP ${res.status}`);
+  const data = await readJsonSafe(res);
+  if (!res.ok || data.code === "UPSTREAM_NON_JSON") err(`${data.error ?? `HTTP ${res.status}`}${data.code ? ` [${data.code}]` : ""}`);
   print(data);
   console.error("\nSave your API key and set it:\n  export CASCROW_API_KEY=" + data.apiKey + "\n");
 }
@@ -484,7 +808,7 @@ async function cmdVerifyWork(args) {
       // 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
@@ -506,7 +830,7 @@ async function cmdVerifyWork(args) {
       // 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, answer);
     // Assigned to the OUTER `data`, not shadowing it: `const { data }` inside the
@@ -541,7 +865,8 @@ async function cmdVerifyWork(args) {
 }
 
 // One-shot verify: submit text proof + get verdict in a single call via /api/mcp/submit.
-// Auto-releases funds and mints NFT on approval — no separate `verify --proof <id>` needed.
+// A verification-only milestone completes (NFT minted) on approval; a MilestoneEscrowV3
+// verdict is a recommendation that moves no money. No separate `verify --proof <id>` needed.
 async function cmdVerify(args) {
   if (!API_KEY) err("CASCROW_API_KEY is not set");
   if (!args.proof) err("--proof is required");
@@ -554,6 +879,13 @@ async function cmdVerify(args) {
   if (!args.contract && args.proof && !args.proof.includes(" ")) {
     process.stderr.write("\nRunning AI verification (5 models)...\n\n");
     const result = await streamVerify(args.proof);
+    // The run was already going (usually the one upload started): print its outcome
+    // as proof-status reports it — the stream's frame never arrived here.
+    if (result && result.attached) {
+      print(result.status);
+      process.stderr.write(statusSummary(result.status) + "\n");
+      return;
+    }
     // SEC-055/058/059 at the third published surface. `passed` used to be
     // `decision === "YES" && confidence >= 85`, i.e. a re-implementation of the
     // three-tier rule from the PROOF's verdict — which answers a different question
@@ -573,10 +905,18 @@ async function cmdVerify(args) {
       released,
       alreadyReleased: result.alreadyReleased === true,
       superseded: result.action === "SUPERSEDED",
+      // With SUPERSEDED: the TERMINAL status the row was already in (EXPIRED, COMPLETED),
+      // or null when another proof won it. It used to reach only the stderr line from
+      // `outcomeLine`, so a machine caller reading this JSON could not tell "closed —
+      // nothing moved, do not resubmit" from "another proof won" (round-3 pass 2).
+      settledAs: typeof result.settledAs === "string" ? result.settledAs : null,
       complianceBlocked: result.complianceBlocked === true,
-      releaseHoldUntil: result.releaseHoldUntil ?? null,
+      notCompletableWithoutEscrow: result.action === "NOT_COMPLETABLE_WITHOUT_ESCROW",
       panelUnavailable: result.timedOut === true,
       txHash: result.txHash ?? null,
+      // MilestoneEscrowV3 (post-review G4): the recommendation's own fields, so a machine
+      // caller reads the SUBMISSION's verdict and the hash to claim with.
+      ...(result.action === "V3_RECOMMENDATION" || result.escrowVersion === 3 ? v3Fields(result) : {}),
       reasoning: result.reasoning,
       modelVotes: (result.votes ?? []).map(v => ({ model: v.model, decision: v.decision, confidence: v.confidence })),
     });
@@ -601,20 +941,23 @@ async function cmdVerify(args) {
     contract_id: args.contract,
     milestone_id: args.milestone ?? undefined,
     evidence,
-  });
+  }, API_KEY, MCP_SUBMIT_CLIENT_ABORT_MS);
 
   // `decided: "elsewhere"` and `panelUnavailable` are 200 responses that carry NO
   // `verdict` key, so `data.verdict ?? "unknown"` fell to the final arm below and told
   // the builder "❌ REJECTED — resubmit with stronger proof" for a milestone that may
   // well have been approved and paid (SEC-055). Classified before the verdict is read.
-  const verdict = data.decided === "elsewhere"
+  const isV3 = data.action === "V3_RECOMMENDATION";
+  const verdict = isV3
+    ? "v3_recommendation"
+    : data.decided === "elsewhere"
     ? "decided_elsewhere"
     : data.panelUnavailable
       ? "panel_unavailable"
       : (data.verdict ?? "unknown");
   const confidence = data.confidence ?? 0;
-  // Approved, payout SCHEDULED, funds still in escrow so the funder can contest.
-  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` turns into an error with its hint.
 
   // Print model votes if available
   const votes = Array.isArray(data.model_votes) ? data.model_votes : [];
@@ -624,8 +967,22 @@ async function cmdVerify(args) {
   }
   process.stderr.write("\n");
 
+  // With `decided: "elsewhere"`: the TERMINAL status the milestone was already in. EXPIRED
+  // is a funder cancel or the deadline, not "the funder's review, or a concurrent
+  // submission", and resubmitting to it is pointless.
+  const settledAs = verdict === "decided_elsewhere" && typeof data.settledAs === "string" ? data.settledAs : null;
+
   let statusLine;
-  if (verdict === "decided_elsewhere") {
+  if (isV3) {
+    // A MilestoneEscrowV3 submission: sealed, recommended on, nothing moved (G4).
+    statusLine = V3_CLIENT_TEXT.recommendation.replace("{verdict}", data.submissionVerdict ?? "PENDING").replace("{confidence}", String(confidence));
+    if (data.manifestHash) statusLine += `\n   manifestHash: ${data.manifestHash}`;
+    if (typeof data.next === "string") statusLine += `\n   ${data.next}`;
+  } else if (settledAs) {
+    statusLine =
+      `ℹ️ 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";
+  } else if (verdict === "decided_elsewhere") {
     statusLine =
       "ℹ️ This milestone was decided by another request while your proof was being verified — " +
       "by the funder's review, or by a concurrent submission. Your evidence was recorded. " +
@@ -635,10 +992,6 @@ async function cmdVerify(args) {
       "⏳ PENDING_REVIEW — the verification panel could not reach a verdict (too few models " +
       "answered). This is NOT a rejection and NOT a judgement of your work; a human decides, " +
       "and resubmitting the same evidence will not help while the panel is down";
-  } else if (verdict === "approved" && releaseHoldUntil) {
-    statusLine =
-      `⏸️ APPROVED (${confidence}% confidence) — payout scheduled for ${releaseHoldUntil}. ` +
-      "NO FUNDS HAVE MOVED YET: the funder can contest until then, and the date can move";
   } else if (verdict === "approved") {
     statusLine = `✅ VERIFIED (${confidence}% confidence)`;
     if (data.on_chain_url) statusLine += `\n   Proof: ${data.on_chain_url}`;
@@ -659,17 +1012,28 @@ async function cmdVerify(args) {
   print({
     verdict,
     confidence,
-    // MONEY MOVED — not "the verdict was approved". A scheduled payout has not happened.
-    passed: verdict === "approved" && !releaseHoldUntil,
-    release_hold_until: releaseHoldUntil,
+    passed: verdict === "approved",
+    ...(settledAs ? { settled_as: settledAs } : {}),
     reasoning: data.reasoning ?? "",
     on_chain_url: data.on_chain_url ?? null,
     proof_id: data.proof_id ?? null,
     signed_at: data.signed_at ?? null,
+    ...(isV3 ? v3Fields(data) : {}),
     model_votes: votes,
   });
 }
 
+/** The MilestoneEscrowV3 fields of an answer, for JSON output (post-review G4). Never derived: forwarded. */
+function v3Fields(r) {
+  return {
+    escrowVersion: 3,
+    submissionId: r.submissionId ?? null,
+    manifestHash: r.manifestHash ?? null,
+    submissionVerdict: r.submissionVerdict ?? "PENDING",
+    claimReady: r.claimReady === true,
+  };
+}
+
 async function cmdCreate(args) {
   if (!API_KEY) err("CASCROW_API_KEY is not set");
   if (!args.title) err("--title is required");
@@ -679,12 +1043,40 @@ async function cmdCreate(args) {
   deadline.setDate(deadline.getDate() + deadlineDays);
   const amountUSD = parseFloat(args.amount ?? "0");
 
+  // T07. The bar the panel judges against — kept OUT of the title, which is printed
+  // on the public certificate. Normalised by a copy of src/lib/milestone-bar-input.ts
+  // (milestone-bar-input-parity.test.ts runs it against the owner).
+  let criteriaRaw = typeof args.criteria === "string" ? args.criteria : undefined;
+  if (typeof args["criteria-file"] === "string") criteriaRaw = readFileSync(args["criteria-file"], "utf8");
+  let checklistRaw;
+  if (typeof args["checklist-file"] === "string") {
+    try {
+      checklistRaw = JSON.parse(readFileSync(args["checklist-file"], "utf8"));
+    } catch (e) {
+      err(`--checklist-file: not a JSON array of { title, severity?, id? } (${e.message})`);
+    }
+  }
+  const reviewMode = typeof args["review-mode"] === "string" ? args["review-mode"].toUpperCase() : undefined;
+  if (reviewMode !== undefined && !["AUTO", "MANUAL", "MANUAL_AUTO"].includes(reviewMode)) {
+    err("--review-mode must be AUTO, MANUAL or MANUAL_AUTO");
+  }
+  let criteria, checklist;
+  try {
+    criteria = normalizeCriteria(criteriaRaw);
+    checklist = normalizeMilestoneChecklist(checklistRaw);
+  } catch (e) {
+    err(e.message);
+  }
+
   const data = await apiPost("/api/contracts", {
     milestones: [{
       title: args.title,
       amountUSD,
       cancelAfter: deadline.toISOString(),
+      ...(criteria !== undefined ? { verificationCriteria: criteria } : {}),
+      ...(checklist !== undefined ? { verificationChecklist: checklist } : {}),
     }],
+    ...(reviewMode !== undefined ? { agentReviewMode: reviewMode } : {}),
   });
 
   const contractUrl = `${BASE_URL}/contract/${data.contractId}`;
@@ -692,42 +1084,28 @@ async function cmdCreate(args) {
   process.stderr.write(`\nContract created: ${contractUrl}\n\n`);
 }
 
-async function cmdFund(args) {
-  if (!API_KEY) err("CASCROW_API_KEY is not set");
-  if (!args.contract) err("--contract is required");
-
-  const body = args.milestone
-    ? { contractId: args.contract, milestoneId: args.milestone }
-    : { contractId: args.contract };
-
-  const data = await apiPost("/api/agent/fund-milestone", body);
-  print(data);
-  process.stderr.write(`\nMilestone funded (simulation). ID: ${data.milestoneId}\n\n`);
+// Removed in 3.0.0 (cascrow Phase 6, owner decision 16): `fund` activated a v2
+// milestone. A $0 verification contract is active by itself once the builder has
+// joined, and a milestone with an amount is a MilestoneEscrowV3 escrow its payer
+// funds from their own machine. Kept as a command only to say so; it sends nothing.
+function cmdFundRemoved() {
+  err(`${V3_CLIENT_TEXT.fundRemoved} [TOOL_REMOVED]`);
 }
 
-async function cmdEscrowFund(args) {
-  if (!API_KEY) err("CASCROW_API_KEY is not set");
-  if (!args.contract) err("--contract is required");
-  if (!args["private-key"]) err("--private-key is required (EVM private key, funds come from this wallet)");
-
-  const body = {
-    contractId: args.contract,
-    agentPrivateKey: args["private-key"],
-  };
-  if (args.milestone) body.milestoneId = args.milestone;
-  if (args.amount) {
-    // NOT forwarded. `agent/escrow-fund` funds `milestone.amountUSD` and ignores
-    // a body field, so `--amount` never overrode anything — it only told the
-    // user it had. Say so rather than sending a number the server drops.
-    process.stderr.write(
-      "\n⚠️  --amount is ignored for escrow funding: the escrowed amount is the milestone's own amountUSD.\n"
-    );
-  }
-
-  process.stderr.write("\nFunding milestone on-chain (approve + fundMilestone)...\n");
-  const data = await apiPost("/api/agent/escrow-fund", body);
-  print(data);
-  process.stderr.write(`\n✅ ${data.amountUSD} RLUSD locked on-chain. TX: ${data.txHash}\n\n`);
+// Removed in 2.0.0 (cascrow Phase 5): `escrow-fund --private-key` sent the key
+// to cascrow, which signed the deposit server-side. Kept as a command only to say
+// so: it sends NOTHING — no request, no argument — so a key typed on the command
+// line goes nowhere. It cannot un-type it, which is why the message tells the user
+// what a key that reached a shell history (or an older version of this CLI) is now.
+function cmdEscrowFundRemoved() {
+  err(
+    "escrow-fund was removed in cascrow-cli 2.0.0: 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 " +
+      "npx cascrow-signer@0.1.0 fund --milestone <milestoneId>. If you ever passed a private key to this command (it is also in your shell history), " +
+      "treat that key as exposed and move its funds to a new wallet. [CUSTODY_PATH_REMOVED]"
+  );
 }
 
 // Legacy two-step: upload proof → returns proofId → user runs `cascrow verify --proof <id>`
@@ -742,7 +1120,25 @@ async function cmdSubmit(args) {
     args.proof
   );
   print(data);
-  process.stderr.write(`\nProof submitted. Run: cascrow verify --proof ${data.proofId}\n\n`);
+  // Upload starts verification by itself — `verify --proof` would only race it.
+  process.stderr.write(`\nProof submitted; verification has started. Wait for the verdict: cascrow status --proof ${data.proofId} --wait\n\n`);
+}
+
+async function cmdStatus(args) {
+  if (!API_KEY) err("CASCROW_API_KEY is not set");
+  if (!args.proof) err("--proof is required");
+  if (args.wait) {
+    process.stderr.write("\nWaiting for the verification to settle (up to ~2 min)...\n\n");
+    const s = await waitForProof(args.proof, 120_000);
+    print(s);
+    process.stderr.write("\n" + statusSummary(s) + "\n\n");
+    return;
+  }
+  const data = await apiGet(`/api/agent/proof-status/${encodeURIComponent(args.proof)}`);
+  print(data);
+  process.stderr.write(
+    "\n" + (data.pending && data.milestoneClosed !== true ? `⏳ Still verifying${data.claimPhase === "orphaned" ? " — the run was interrupted" : ""}.` : statusSummary({ ...data, proofId: args.proof })) + "\n\n"
+  );
 }
 
 async function cmdGet(args) {
@@ -757,7 +1153,8 @@ async function cmdJoin(args) {
   if (!args.invite) err("--invite is required");
   const data = await apiPost("/api/contracts/join", { inviteCode: args.invite });
   print(data);
-  process.stderr.write(`\nJoined contract: ${data.contractId}\n\n`);
+  // `activated`: a $0 contract is active now; a money contract waits for its V3 offer.
+  process.stderr.write(`\nJoined contract: ${data.contractId}\n${joinedLine(data)}\n\n`);
 }
 
 async function cmdHandoff(args) {
@@ -797,9 +1194,9 @@ async function cmdCheckInvites() {
  * verdict on cannot come apart (F-22).
  *
  * `review-queue` is the pull behind the `manual_review.required` webhook: a
- * webhook nobody received is a decision nobody makes, and cascrow auto-approves
- * an undecided milestone after 48 h (agent contracts) or 14 days (human) and
- * releases the escrow. `review` ships with it rather than later, because a list
+ * webhook nobody received is a decision nobody makes, and cascrow completes an
+ * undecided milestone after 48 h (agent contracts in MANUAL_AUTO/AUTO) or 14 days
+ * (every other contract). Verification-only contracts: no money moves. `review` ships with it rather than later, because a list
  * its reader cannot act on names a remedy they are unable to perform (F-72).
  */
 async function cmdReviewQueue() {
@@ -807,8 +1204,16 @@ async function cmdReviewQueue() {
   const data = await apiGet("/api/agent/review-queue");
   const contracts = data.contracts ?? [];
   print(data);
+  // Said in both branches: an empty v2 queue is exactly when a reader stops
+  // looking, and a V3 claim window keeps running.
+  const v3 =
+    data.v3ClaimsPending === null
+      ? "Open MilestoneEscrowV3 claims could not be counted — run: cascrow v3-claims\n\n"
+      : data.v3ClaimsPending > 0
+        ? `${data.v3ClaimsPending} MilestoneEscrowV3 claim(s) can still be objected to — run: cascrow v3-claims\n\n`
+        : "";
   if (contracts.length === 0) {
-    process.stderr.write("\nNo milestones are waiting for your verdict.\n\n");
+    process.stderr.write(`\nNo milestones are waiting for your verdict.\n\n${v3}`);
     return;
   }
   const lines = contracts.map((c) => {
@@ -819,15 +1224,100 @@ async function cmdReviewQueue() {
         : pending.length > 1
           ? `${pending.length} milestones pending — pass --milestone <id>`
           : "contract-level review — omit --milestone";
-    return `  ${c.contractId}  ${c.amountUSD} RLUSD  (${ms})`;
+    return `  ${c.contractId}  (${ms})`;
   }).join("\n");
   const more = data.truncated ? `\n(${data.total} in total — this list is capped.)` : "";
   process.stderr.write(
     `\n${data.total} contract(s) waiting for your verdict:\n${lines}${more}\n\n` +
-      "Decide with: cascrow review --contract <id> --decision APPROVE|REJECT [--milestone <id>]\n\n"
+      "Decide with: cascrow review --contract <id> --decision APPROVE|REJECT [--milestone <id>]\n\n" +
+      v3
   );
 }
 
+/**
+ * The payer's open MilestoneEscrowV3 claims — `GET /api/agent/v3-claims`, the
+ * pull behind the `claim.submitted` webhook. Print only: the action is the
+ * payer's own `object(escrowId)` on chain, which cascrow never performs.
+ */
+async function cmdV3Claims() {
+  if (!API_KEY) err("CASCROW_API_KEY is not set");
+  const data = await apiGet("/api/agent/v3-claims");
+  const claims = data.claims ?? [];
+  print(data);
+  if (claims.length === 0) {
+    process.stderr.write("\nNo MilestoneEscrowV3 claim is waiting on you.\n\n");
+    return;
+  }
+  const lines = claims.map((c) =>
+    `  ${c.escrowId} on ${c.chainId}/${c.escrowContract}  claim ${c.claimIndex}` +
+      `${c.secondFunding ? "  SECOND funding" : ""}${c.held ? "  (held — 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(This list is capped; more claims exist.)" : "";
+  process.stderr.write(`\n${claims.length} claim(s):\n${lines}${more}\n\ncascrow cannot object for you — your own wallet calls object(escrowId) on the escrow contract.\n\n`);
+}
+
+// ─── MilestoneEscrowV3, remote half (design Rev. 10) ──────────────────────────
+// cascrow prepares and reads; the party signs and sends with its own key. This CLI
+// holds no key and has no dependency: `v3 sign …` runs the PINNED local signer
+// (V3_CLIENT_TEXT.signerPin) in a child process, with this terminal attached, so
+// its prompts and its checks are the signer's own.
+async function cmdV3(sub, args, rawArgs) {
+  if (sub === "sign") {
+    const child = spawn("npx", ["--yes", V3_CLIENT_TEXT.signerPin, ...rawArgs], { stdio: "inherit", shell: process.platform === "win32" });
+    const code = await new Promise((resolve) => child.on("close", resolve));
+    process.exit(typeof code === "number" ? code : 1);
+  }
+  if (!API_KEY) err("CASCROW_API_KEY is not set");
+  switch (sub) {
+    case "offer": {
+      if (!args.milestone || !args["review-period-sec"]) err("--milestone and --review-period-sec are required");
+      const body = {
+        milestoneId: args.milestone,
+        reviewPeriodSec: Number(args["review-period-sec"]),
+        watcherDeclared: args.watcher === true || args.watcher === "true",
+        ...(args.arbiter ? { arbiter: args.arbiter } : {}),
+        ...(args["arbitration-period-sec"] ? { arbitrationPeriodSec: Number(args["arbitration-period-sec"]) } : {}),
+      };
+      print(await apiPost("/api/escrow/v3/offer", body));
+      process.stderr.write(`\nOffer sent. After the builder accepts, fund it from your machine: cascrow v3 sign fund --milestone ${args.milestone}\n\n`);
+      return;
+    }
+    case "acceptance":
+      if (!args.milestone) err("--milestone is required");
+      print(await apiGet(`/api/escrow/v3/acceptance?milestoneId=${encodeURIComponent(args.milestone)}`));
+      process.stderr.write("\nCheck every term — your signature binds you until acceptBy. To check and sign locally: cascrow v3 sign accept --milestone " + args.milestone + "\n\n");
+      return;
+    case "accept-submit":
+      if (!args.offer || !args.signature) err("--offer and --signature are required");
+      print(await apiPost("/api/escrow/v3/acceptance", { offerId: args.offer, signature: args.signature }));
+      return;
+    case "prepare": {
+      if (!args.milestone || !args.action) err("--milestone and --action are required");
+      const q = new URLSearchParams({ milestoneId: args.milestone, action: args.action });
+      if (args["proof-hash"]) q.set("proofHash", args["proof-hash"]);
+      if (args["reason-hash"]) q.set("reasonHash", args["reason-hash"]);
+      if (args["new-deadline"]) q.set("newDeadline", String(args["new-deadline"]));
+      print(await apiGet(`/api/escrow/v3/prepare?${q.toString()}`));
+      process.stderr.write("\nUNSIGNED — cascrow does not sign, send or relay it. Rebuild data from the ABI and check to/chainId against your own configuration before signing (cascrow v3 sign … does).\n\n");
+      return;
+    }
+    case "report-tx":
+      if (!args.milestone || typeof args.tx !== "string" || !TX_HASH_RE.test(args.tx)) err(V3_CLIENT_TEXT.reportTxOnlyHash);
+      print(await apiPost("/api/escrow/v3/sync", { milestoneId: args.milestone, txHash: args.tx }));
+      return;
+    case "attestation":
+      if (!args.escrow || !args["claim-index"]) err("--escrow and --claim-index are required");
+      print(await apiGet(`/api/escrow/v3/attestation?${new URLSearchParams({ escrowId: args.escrow, claimIndex: String(args["claim-index"]) }).toString()}`));
+      return;
+    case "claims":
+      await cmdV3Claims();
+      return;
+    default:
+      err(`unknown v3 command ${sub ?? "(none)"} — offer | acceptance | accept-submit | prepare | report-tx | attestation | claims | sign`);
+  }
+}
+
 async function cmdReview(args) {
   if (!API_KEY) err("CASCROW_API_KEY is not set");
   const contractId = args.contract;
@@ -837,11 +1327,14 @@ async function cmdReview(args) {
   const body = args.milestone ? { contractId, decision, milestoneId: args.milestone } : { contractId, decision };
   const data = await apiPost("/api/contracts/review", body);
   print(data);
+  // The route answers `{ status }` and nothing else: a review only decides
+  // verification-only ($0) milestones, and nothing moves money (a MilestoneEscrowV3
+  // milestone is refused — its payer releases or objects on chain).
   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";
-  process.stderr.write(`\nMilestone ${what}.${data.txHash ? `\nRelease tx: ${data.txHash}` : ""}\n\n`);
+  process.stderr.write(`\nMilestone ${what}.${data.status ? ` Contract status: ${data.status}.` : ""}\n\n`);
 }
 
 async function cmdMe() {
@@ -866,15 +1359,18 @@ try {
     case "verify-work":   await cmdVerifyWork(args);    break;
     case "verify":        await cmdVerify(args);        break;
     case "create":        await cmdCreate(args);        break;
-    case "fund":          await cmdFund(args);          break;
-    case "escrow-fund":   await cmdEscrowFund(args);    break;
+    case "fund":          cmdFundRemoved();             break;
+    case "escrow-fund":   cmdEscrowFundRemoved();       break;
     case "submit":        await cmdSubmit(args);        break;
+    case "status":        await cmdStatus(args);        break;
     case "get":           await cmdGet(args);           break;
     case "join":          await cmdJoin(args);          break;
     case "handoff":       await cmdHandoff(args);       break;
     case "check-invites": await cmdCheckInvites();      break;
     case "review-queue":  await cmdReviewQueue();       break;
     case "review":        await cmdReview(args);        break;
+    case "v3-claims":     await cmdV3Claims();          break;
+    case "v3":            await cmdV3(rest[0], parseArgs(rest.slice(1)), rest.slice(1)); break;
     case "me":            await cmdMe();                break;
     default:
       console.error(`Unknown command: ${command}\n`);