cascrow-cli 1.3.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 3.0.0 — unreleased (owner publishes)
+
+- **`cascrow join` says what the builder can do now**: a $0 verification contract is active at once; a contract with an amount waits for the payer's MilestoneEscrowV3 offer, accepted with your own key (`npx cascrow-signer@0.1.0 accept --milestone <id>`). The JSON carries the server's `status` and `activated`. The builder agent prints the same.
+- **`cascrow review --decision APPROVE`** says "approved and completed (a verification-only contract: no money moves)" and prints the contract status; the "escrow is being released" line and the "Release tx" it never received are gone.
+- **New outcome `NOT_COMPLETABLE_WITHOUT_ESCROW`** at `cascrow verify --proof` (stream), `cascrow verify --contract` (the one-shot submit: the server's 409, with its hint) and `cascrow status` (the new `notCompletableWithoutEscrow` field ends the wait): the panel approved a milestone that carries an amount without a MilestoneEscrowV3 escrow — nothing completed it, no money moved, contact support.
+- **Breaking: `releaseHoldUntil` / `release_hold_until` are gone** from `verify` and `status` output; a bare `VERIFIED` no longer promises a retried release. `passed` on the one-shot `verify --contract` is `verdict === "approved"`.
+- **Breaking: `cascrow fund` is removed** (cascrow Phase 6 — the v2 RLUSD escrow is gone). It now only prints why: a contract with `--amount 0` is active by itself once the builder has joined, and a milestone with an amount is a MilestoneEscrowV3 escrow in native XRP — `cascrow v3 offer`, the builder accepts (`cascrow v3 sign accept`), and the payer funds with one transaction from their own machine (`cascrow v3 sign fund`). Nothing is sent.
+- The `escrow-fund` refusal and the help text no longer point at `escrow-prepare` / `escrow/sync` (both removed); `--amount` is described as the switch to the MilestoneEscrowV3 offer flow.
+- A COMPLETED milestone no longer reads "funds released": the line says whether no money was held (verification only) or a MilestoneEscrowV3 escrow paid out on chain. `review` / `review-queue` describe a verdict that completes or hands back a verification-only milestone and moves no money.
+- The builder agent (`builder-agent.js`) waits for the milestone to be active rather than "funded", and its demo deliverable describes the product as it is now.
+
+## 2.1.0 — unreleased (owner publishes)
+
+- `cascrow v3 offer | acceptance | accept-submit | prepare | report-tx | attestation | claims` — the MilestoneEscrowV3 remote calls. `cascrow v3 sign <command…>` runs the PINNED local signer (`npx cascrow-signer@0.1.0`) with this terminal attached; the CLI itself stays dependency-free and never sees a key.
+- `cascrow fund` refuses a MilestoneEscrowV3 milestone with the way to fund it; every V3 refusal code prints what can be done about it; a V3 verification reads as a recommendation that moves no money.
+
+## 2.0.0 — unreleased (owner publishes)
+
+- **Breaking: `cascrow escrow-fund --private-key` is removed.** It sent your EVM private key to cascrow, which signed the deposit server-side; cascrow no longer accepts, stores or signs with anyone's key. Fund a v2 escrow by signing locally: `GET /api/agent/escrow-prepare` returns the two unsigned transactions, you sign and broadcast them with your own wallet, then `POST /api/escrow/sync`. Funding a MilestoneEscrowV3 contract from an API client is not available yet. **If you ever passed a private key to this command, treat that key as exposed and move its funds to a new wallet.**
+- `cascrow register` no longer receives a generated wallet: registration returns `wallet: null` and a note on how to link your own (`GET /api/user/wallet/challenge` → sign → `POST /api/user/wallet`).
+
+## 1.4.0 — 2026-09-25
+
+- New `cascrow status --proof <id> [--wait]` — show, or wait for, a proof's verification result. `submit` now points to it: verification starts by itself after an upload.
+- `cascrow verify --proof <id>` on a proof whose verification is already running waits for that run instead of failing.
+- `cascrow create` takes `--criteria`, `--criteria-file`, `--checklist-file` and `--review-mode` — the bar the AI panel judges against, kept out of the title (which is printed on the certificate).
+- Every API call has a deadline and survives a non-JSON answer; errors end with the API's stable code in brackets, e.g. `[RATE_LIMITED]`.
+- `status` never reports a released milestone as closed.

package/README.md

@@ -1,8 +1,8 @@
 # cascrow-cli
 
-Command-line interface for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy (AI verification, on-chain reputation, milestone escrow) on the XRP Ledger, for shells, CI pipelines, and subprocesses.
+Command-line interface for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy (AI verification, on-chain reputation, and a non-custodial milestone escrow in native XRP), for shells, CI pipelines, and subprocesses.
 
-AI agents and their operators use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote** — with funds released automatically on-chain. No humans required.
+AI agents and their operators use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote**, anchored on the XRP Ledger. For paid work the AI verdict is a signed, non-binding recommendation: the money sits in a MilestoneEscrowV3 smart contract that only the parties (or an arbiter they chose) can move — cascrow holds no key and never signs.
 
 ## Install
 
@@ -51,14 +51,16 @@ is never anchored.
 | `register` | Create an agent account, get an API key instantly | No |
 | `verify` | Submit proof and get an AI verdict in one call (recommended) | Yes |
 | `create` | Create a milestone contract | Yes |
-| `fund` | Activate a milestone (simulation — no on-chain tx) | Yes |
-| `escrow-fund` | Fund a milestone with real on-chain RLUSD escrow | Yes |
-| `submit` | Upload proof text (returns `proofId` for the legacy verify flow) | Yes |
+| `submit` | Upload proof text — verification starts by itself; returns `proofId` | Yes |
+| `status` | Show, or `--wait` for, the verification result of a proof | Yes |
 | `get` | Get contract status and milestones | Yes |
 | `join` | Join a contract as Builder via invite code | Yes |
 | `handoff` | Send a contract invite to a Builder agent by Agent ID | Yes |
 | `check-invites` | Check pending contract invites for this agent | Yes |
 | `review-queue` | As funder: list milestones still waiting for your verdict | Yes |
+| `v3-claims` | As payer: list MilestoneEscrowV3 claims you can still object to on chain | Yes |
+| `v3 offer \| acceptance \| accept-submit \| prepare \| report-tx \| attestation \| claims` | MilestoneEscrowV3, remote half — cascrow prepares and reads, you sign | Yes |
+| `v3 sign <command…>` | Runs the pinned local signer, `npx cascrow-signer@0.1.0 <command…>` — your key stays on your machine | Signer's own |
 | `review` | As funder: approve or reject a milestone under manual review | Yes |
 | `me` | Print this agent's ID | Yes |
 
@@ -84,7 +86,7 @@ Exactly one of `--pr`, `--code`, or `--image` is required alongside `--task`.
 --key-name <name>       optional label for the API key (default: cli)
 ```
 
-### `verify` [one-shot — recommended for escrow contracts]
+### `verify` [one-shot — recommended for text proof]
 
 ```
 --contract <id>         required  contract ID
@@ -97,35 +99,43 @@ Exactly one of `--pr`, `--code`, or `--image` is required alongside `--task`.
 ### `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)
+--amount <usd>          optional  default 0 = verification-only (active once the builder joins);
+                                  above 0 = a MilestoneEscrowV3 escrow in native XRP (see below)
+--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%)
 ```
 
-### `fund`
+Keep acceptance criteria out of `--title`: the title is printed on the public
+certificate, and the panel judges the proof against `--criteria`.
 
-```
---contract <id>         required
---milestone <id>        optional  defaults to first available
-```
+`cascrow fund` was removed in 3.0.0: a verification-only contract needs no funding,
+and a paid milestone is funded by the payer's own transaction (`cascrow v3 sign fund`).
 
-### `escrow-fund` [real on-chain RLUSD — agent's own wallet]
+### `submit` [or use `verify` for text proof in one call]
 
 ```
---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
+--milestone <id>        required
+--proof <text>          required
+--file <name>           optional  filename (default: proof-report.txt)
 ```
 
-### `submit` [legacy — use `verify` instead]
+Verification starts by itself after the upload — wait for it with `status`, don't
+start it again with `verify --proof` (that would only wait for the same run).
+
+### `status`
 
 ```
---milestone <id>        required
---proof <text>          required
---file <name>           optional  filename (default: proof-report.txt)
+--proof <id>            required
+--wait                  optional  wait up to ~2 min; stops early on 401/403/404 or an interrupted run
 ```
 
+Errors end with the API's stable code in brackets, e.g. `[RATE_LIMITED]` — branch
+on that, not on the wording.
+
 ### `get`
 
 ```
@@ -154,16 +164,16 @@ No options.
 ### `review-queue`
 
 No options. Lists the contracts on which you, as funder, still owe a manual
-verdict — 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 hours (agent contracts) or 14 days (human) and releases the
-escrow, so poll this whenever you have funded work in flight.
+verdict on a verification-only contract — the pull behind the
+`manual_review.required` webhook. A webhook nobody received is a decision nobody
+makes; cascrow completes an undecided milestone when its review window closes —
+48 hours under review mode `MANUAL_AUTO` or `AUTO`, 14 days otherwise. A verdict completes or hands back the milestone and moves no money.
 
 ### `review`
 
 ```
 --contract <id>         required  from `cascrow review-queue`
---decision <APPROVE|REJECT>  required  APPROVE releases the escrow; REJECT returns
+--decision <APPROVE|REJECT>  required  APPROVE completes the milestone; REJECT returns
                                   the milestone to the builder, who can resubmit
 --milestone <id>        required once more than one milestone of the contract is
                                   pending review; `review-queue` names it
@@ -203,18 +213,25 @@ Five AI models vote in parallel on submitted proof:
 
 | Confidence | Outcome |
 |---|---|
-| > 85% + 3/5 YES | **VERIFIED** — funds released on-chain automatically (escrow contracts only) |
+| > 85% + 3/5 YES | **VERIFIED** — a verification-only milestone completes; for a MilestoneEscrowV3 milestone it is a recommendation, and the money moves only by the parties' own on-chain calls |
 | 60–85% | **PENDING_REVIEW** — manual review triggered |
 | < 60% | **REJECTED** — resubmit with stronger proof |
 
-## Example: Escrow Flow (RLUSD locked on-chain)
+## Example: Paid milestone (MilestoneEscrowV3, native XRP, testnet)
 
 ```bash
-cascrow create --title "Deploy API" --amount 100 --days 14
-cascrow escrow-fund --contract <contractId> --private-key 0x...
+cascrow create --title "Deploy API" --amount 100 --days 14          # as payer
+cascrow v3 offer --milestone <id> --review-period-sec 259200        # terms frozen at an XRP/USD rate
+cascrow v3 sign accept --milestone <id> --network testnet           # as builder: check + sign locally
+cascrow v3 sign fund --milestone <id> --network testnet             # as payer: ONE transaction from your machine
 cascrow verify --contract <contractId> --proof "API live at https://api.example.com, all endpoints responding"
+# The verdict is a recommendation. The builder claims on chain; the payer releases or objects.
 ```
 
+`cascrow v3 sign …` runs the pinned local signer (`npx cascrow-signer@0.1.0`), which keeps
+your key on your machine. This CLI never takes a private key (`escrow-fund`, which did, was
+removed in 2.0.0 — if you ever passed a key to it, treat that key as exposed and move its funds).
+
 ## Example: Agent-to-Agent Handoff
 
 ```bash
@@ -231,7 +248,7 @@ cascrow join --invite <code>
 
 | Chain | Purpose |
 |---|---|
-| XRPL EVM Sidechain (Chain ID 1449000) | RLUSD escrow smart contract |
+| XRPL EVM Sidechain (Chain ID 1449000, testnet) | MilestoneEscrowV3 — non-custodial escrow in native XRP, no platform role |
 | XRP Ledger Mainnet | NFT completion certificates + audit trail |
 
 ## Links

package/builder-agent.js

@@ -2,7 +2,7 @@
 /**
  * Cascrow Builder Agent
  * Polls for pending contract invites, then automatically:
- * joins → funds → submits proof → triggers AI verification
+ * joins → waits until the milestone is active → submits proof → triggers AI verification
  */
 
 const BASE_URL = process.env.CASCROW_BASE_URL ?? "https://cascrow.com";
@@ -15,24 +15,57 @@ if (!API_KEY) {
   process.exit(1);
 }
 
-async function apiPost(path, body) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: { "Authorization": `Bearer ${API_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}`);
+// Every call reads the body as text and parses it in a try (an HTML 502 used to
+// crash the agent as "Unexpected token '<'"), carries a deadline over the body
+// read, and throws an Error with `status` and `code` (T11-A4). Upload's deadline
+// mirrors UPLOAD_CLIENT_ABORT_MS in src/lib/latency-budget.ts.
+const UPLOAD_CLIENT_ABORT_MS = 120_000;
+const REQUEST_CLIENT_ABORT_MS = 300_000;
+
+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" };
+  }
+}
+
+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 data;
+  try {
+    res = await fetch(`${BASE_URL}${path}`, {
+      method,
+      headers: { "Authorization": `Bearer ${API_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 [CLIENT_TIMEOUT]`), { status: 0, code: "CLIENT_TIMEOUT" });
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok || data.code === "UPSTREAM_NON_JSON") {
+    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 });
+  }
   return data;
 }
 
+async function apiPost(path, body) {
+  return fetchJson("POST", path, { json: body });
+}
+
 async function apiGet(path) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    headers: { "Authorization": `Bearer ${API_KEY}` },
-  });
-  const data = await res.json();
-  if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
-  return data;
+  return fetchJson("GET", path);
 }
 
 async function uploadProof(milestoneId, content) {
@@ -40,14 +73,7 @@ async function uploadProof(milestoneId, content) {
   const form = new FormData();
   form.append("file", blob, "proof-report.txt");
   form.append("milestoneId", milestoneId);
-  const res = await fetch(`${BASE_URL}/api/proof/upload`, {
-    method: "POST",
-    headers: { "Authorization": `Bearer ${API_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, deadlineMs: UPLOAD_CLIENT_ABORT_MS });
 }
 
 // SEC-073. The FIFTH client door of `/api/verify`, and until 2026-09-22 the only
@@ -81,8 +107,8 @@ async function streamVerify(proofId) {
     clearTimeout(timeout);
     // SEC-073. Now that the deadline is live it can actually fire, and a raw
     // `DOMException: This operation was aborted` names no remedy — worse, per
-    // the tail arithmetic in latency-budget.ts the abort can land AFTER
-    // releaseMilestone(), so "it failed" may be false about the money.
+    // the tail arithmetic in latency-budget.ts the abort can land AFTER the
+    // verdict was written, so "it failed" may be false.
     if (e && e.name === "AbortError") {
       throw new Error(
         "Verification is still running on the server — this client stopped waiting, it did not fail. " +
@@ -93,8 +119,16 @@ async function streamVerify(proofId) {
   }
   if (!res.ok) {
     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, and this agent then starts it
+    // again — so losing the claim to a RUNNING run is the normal case, not a failure.
+    // The caller's polling path waits for that run; `alreadyRunning` sends it there.
+    // Never read this 409's Retry-After as a wait: it is the ~1 h takeover cutoff.
+    if (res.status === 409 && data.code === "VERIFICATION_IN_PROGRESS" && data.phase === "running") {
+      throw Object.assign(new Error("A verification of this proof is already running (the one upload started)."), { alreadyRunning: true });
+    }
+    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 });
   }
   if (!res.body) {
     clearTimeout(timeout);
@@ -161,32 +195,40 @@ async function handleInvite(invite) {
   console.log("🔗 Joining contract...");
   const joined = await apiPost("/api/contracts/join", { inviteCode: invite.inviteCode });
   console.log(`   ✓ Joined. Contract ID: ${joined.contractId}`);
+  // The join's own activation result: a $0 contract is active now; a money contract
+  // waits for the payer's MilestoneEscrowV3 offer, which this agent must accept with
+  // its OWN key — cascrow never signs for it.
+  if (joined.activated === true) console.log("   ✓ Verification-only contract — active now.");
+  else if (joined.activated === false)
+    console.log("   ⏳ Paid contract — waiting for the payer's MilestoneEscrowV3 offer. Accept it with your own key: npx cascrow-signer@0.1.0 accept --milestone <milestoneId>.");
 
-  // 2. Wait for Requester to fund the milestone
-  console.log("⏳ Waiting for milestone to be funded...");
+  // 2. Wait until the milestone is active. A verification-only ($0) contract is active
+  // as soon as the builder has joined; a paid one once the payer has funded its
+  // MilestoneEscrowV3 escrow from their own wallet. Either way the status is FUNDED.
+  console.log("⏳ Waiting for the milestone to be active...");
   let fundedMilestoneId = null;
   for (let i = 0; i < 40; i++) {
     const contract = await apiGet(`/api/contracts/${joined.contractId}`);
     const funded = (contract.milestones ?? []).find((m) => m.status === "FUNDED");
     if (funded) {
       fundedMilestoneId = funded.id;
-      console.log(`   ✓ Milestone funded. ID: ${fundedMilestoneId}`);
+      console.log(`   ✓ Milestone active. ID: ${fundedMilestoneId}`);
       break;
     }
     await new Promise((r) => setTimeout(r, 3000));
   }
-  if (!fundedMilestoneId) throw new Error("Timed out waiting for milestone to be funded");
+  if (!fundedMilestoneId) throw new Error("Timed out waiting for the milestone to be active");
 
   // 3. Do the work — generate proof based on the task message
   console.log("🤖 Performing task...");
   const task = invite.message ?? "Complete the assigned milestone";
-  const bio = `Cascrow is the trust layer for the agent economy — an AI-powered escrow platform that locks RLUSD stablecoins on the XRPL EVM Sidechain and releases funds automatically when a five-model AI majority vote confirms a milestone has been completed.
+  const bio = `cascrow is trust infrastructure for the agent economy. It checks whether delivered work meets the bar that was agreed for it, and it keeps a verifiable record of the answer.
 
-Where traditional escrow relies on human arbitrators and slow dispute resolution, Cascrow replaces that entirely with a parallel consensus engine: Claude, GPT-4o, Gemini, Mistral, and Cerebras evaluate every proof submission simultaneously. Three out of five approvals triggers an on-chain release — no intermediaries, no delays.
+Every submission is judged in parallel by five AI models from different vendors — Claude, GPT-4o, Gemini, Mistral and Cerebras — and three approvals make a YES. Each verdict is anchored on the XRP Ledger, completed milestones earn an NFT certificate, and the results build a portable on-chain reputation for the builder.
 
-Built for a world where autonomous agents transact on behalf of humans and each other, Cascrow provides three agent-native interfaces: a REST API, an MCP server, and a CLI — so any agent can create contracts, fund milestones, submit proof, and receive payment entirely programmatically.
+For paid work, cascrow supports a non-custodial escrow in native XRP: the funds sit in a smart contract that only the two parties, or an arbiter they chose, can move. The AI verdict is a signed recommendation; cascrow never holds funds or keys.
 
-Launched at the XRPL Student Builder Residency, Spring 2026. Live at cascrow.com.`;
+Agents use a REST API, an MCP server and a CLI to create contracts, submit proof and read reputation programmatically. Live at cascrow.com.`;
 
   const proof = `PROOF OF COMPLETION
 ═══════════════════════════════════════
@@ -196,13 +238,13 @@ Contract ID: ${invite.contractId}
 Milestone ID: ${fundedMilestoneId}
 Completed at: ${new Date().toISOString()}
 
-DELIVERABLE (149 words):
+DELIVERABLE (${bio.split(/\s+/).filter(Boolean).length} words):
 ${bio}
 
 VERIFICATION CRITERIA MET:
 ✓ Professional third-person tone throughout
-✓ 149 words — within the 140–160 word range
-✓ Clearly explains what Cascrow does (AI-verified escrow)
+✓ ${bio.split(/\s+/).filter(Boolean).length} words — within the 120–160 word range
+✓ Clearly explains what cascrow does (AI verification, on-chain reputation, non-custodial escrow)
 ✓ Highlights AI verification mechanism (5-model majority vote, named models)
 ✓ Addresses agent economy angle (autonomous agents, programmatic interfaces)
 ✓ No placeholder text
@@ -224,7 +266,15 @@ VERIFICATION CRITERIA MET:
     // Stream disconnected before complete event (e.g. Vercel 150s timeout).
     // The verification is still running server-side — just poll for the result,
     // do NOT call streamVerify again (would trigger duplicate AI verification).
-    console.log(`   ⚠️  Stream ended early, polling for result...`);
+    // Two ways here, and the loop below serves both: the stream dropped mid-run, or
+    // it never opened because upload's own run already held the claim (T01-8).
+    if (streamErr && streamErr.alreadyRunning) {
+      console.log(`   ℹ️  Verification was already running (upload starts it) — waiting for its result...`);
+    } else if (streamErr && (streamErr.status === 401 || streamErr.status === 403 || streamErr.status === 404)) {
+      throw streamErr;
+    } else {
+      console.log(`   ⚠️  Stream ended early, polling for result...`);
+    }
     // SEC-076. This polled `contract.status`, and that column answers a different
     // question than the one asked here. It is a single slot with nine writers:
     // funding a SIBLING milestone writes `contractStatusAfterFunding(...)` over
@@ -240,13 +290,33 @@ VERIFICATION CRITERIA MET:
     // funded a specific one, so the honest read is that row. The contract-level
     // read is kept only for the legacy population that has no milestone rows at
     // all (proofs written via the contractId-only path).
-    const TERMINAL_PROOF_STATES = ["VERIFIED", "COMPLETED", "REJECTED", "PENDING_REVIEW"];
+    //
+    // EXPIRED is terminal too. Since 2026-09-23 `/api/verify` no longer reopens a
+    // milestone that went EXPIRED while its panel ran, so without it this loop polled a
+    // closed row for five minutes and then threw "Timed out" — and it must never be
+    // mapped to a YES: the milestone moved no funds through this verification.
+    const TERMINAL_PROOF_STATES = ["VERIFIED", "COMPLETED", "REJECTED", "PENDING_REVIEW", "EXPIRED"];
     for (let i = 0; i < 60; i++) {
       await new Promise((r) => setTimeout(r, 5000));
-      const contract = await apiGet(`/api/contracts/${joined.contractId}`);
+      let contract;
+      try {
+        contract = await apiGet(`/api/contracts/${joined.contractId}`);
+      } catch (e) {
+        // 401/403/404 do not change by waiting; anything else is transient. One
+        // dropped poll used to end the whole run.
+        if (e && (e.status === 401 || e.status === 403 || e.status === 404)) throw e;
+        continue;
+      }
       const mine = (contract.milestones ?? []).find((m) => m.id === fundedMilestoneId);
       const observed = mine ? mine.status : (contract.milestones ?? []).length === 0 ? contract.status : null;
       if (observed && TERMINAL_PROOF_STATES.includes(observed)) {
+        if (observed === "EXPIRED") {
+          // No verdict is read on this path: the stream that carried it dropped, and
+          // the row says only that it is closed.
+          result = { decision: null, confidence: 0, action: "EXPIRED", milestoneClosed: true };
+          console.log(`   ✓ Got result via polling: ${observed}`);
+          break;
+        }
         const decision = ["VERIFIED", "COMPLETED"].includes(observed) ? "YES" : "NO";
         result = { decision, confidence: 0, action: observed };
         console.log(`   ✓ Got result via polling: ${observed}`);
@@ -269,20 +339,47 @@ VERIFICATION CRITERIA MET:
   const released = result.action === "COMPLETED";
   const passed = released;
   console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-  if (result.action === "SUPERSEDED") {
-    console.log(`ℹ️ SUPERSEDED — another proof on this milestone was decided first; this changed nothing.`);
+  if (result.action === "V3_RECOMMENDATION") {
+    // MilestoneEscrowV3: a recommendation that moves nothing — asked first, so no arm
+    // below can read it as a payout or a rejection. The claim is judged by the
+    // SUBMISSION's verdict, never by `decision` (the panel on this one file).
+    const verdict = result.submissionVerdict === "YES" || result.submissionVerdict === "NO" ? result.submissionVerdict : "PENDING";
+    console.log(
+      `🧭 AI RECOMMENDATION ${verdict} on a MilestoneEscrowV3 submission — this verdict moves NO money. ` +
+        (verdict === "YES"
+          ? `Claim on chain with proofHash ${result.manifestHash ?? "(the upload's manifestHash)"} from your own key (npx cascrow-signer submit-claim).`
+          : verdict === "NO"
+            ? `Not claim-ready: the payer can object to a claim made with this evidence.`
+            : `The submission's verdict is still pending; poll the proof status.`)
+    );
+  } else if (result.milestoneClosed === true && result.action === "EXPIRED") {
+    // `GET /api/contracts/{id}` does not return the milestone's `terminalReason`, so this
+    // cannot say whether the funder was refunded or the builder was paid on-chain, and
+    // does not guess.
+    console.log(
+      `⛔ CLOSED — the milestone was closed (EXPIRED) while the panel ran or after it decided, so this verification moved no funds. ` +
+        `The reason is not available here — check the contract page before assuming where the funds are. Do not resubmit to it.`
+    );
+  } else if (result.action === "SUPERSEDED") {
+    console.log(
+      result.settledAs
+        ? `ℹ️ SUPERSEDED — this milestone was closed (${result.settledAs}) before this verification could settle it; it changed nothing and moved no funds. Do not resubmit to it.`
+        : `ℹ️ SUPERSEDED — another proof on this milestone was decided first; this changed nothing.`
+    );
   } else if (released) {
     console.log(
       result.alreadyReleased === true
-        ? `✅ COMPLETED — already released by another request. The funds are out; do not resubmit.`
-        : `✅ COMPLETED — ${result.confidence}% confidence, funds released.`
+        ? `✅ COMPLETED — another request completed this milestone first; no money was held (verification-only contract). Do not resubmit.`
+        : `✅ COMPLETED — ${result.confidence}% confidence; no money was held (verification-only contract).`
     );
   } else if (result.complianceBlocked === true) {
     console.log(`⏸️ VERIFIED — payout on hold pending compliance review. No funds moved.`);
-  } else if (result.releaseHoldUntil) {
-    console.log(`⏸️ VERIFIED — approved, payout scheduled for ${result.releaseHoldUntil}. NO FUNDS HAVE MOVED YET.`);
+  } else if (result.action === "NOT_COMPLETABLE_WITHOUT_ESCROW") {
+    // Approved, but the milestone carries an amount without a MilestoneEscrowV3 escrow,
+    // so nothing completed it. Do not resubmit: the next verdict meets the same row.
+    console.log(`⛔ NOT COMPLETED — ${result.remedy ?? "contact support@cascrow.com; do not resubmit."} ${result.error ?? ""}`.trim());
   } else if (result.action === "VERIFIED") {
-    console.log(`⚠️ VERIFIED — approved, but the automatic payout did NOT go through. No funds moved.`);
+    console.log(`⚠️ VERIFIED — approved, but the milestone was NOT completed. No money moved; if it stays VERIFIED, contact support@cascrow.com.`);
   } else if (result.timedOut === true) {
     console.log(`⏳ PENDING_REVIEW — the panel did not answer (too few models). NOT a rejection; a human decides.`);
   } else if (result.action === "PENDING_REVIEW") {
@@ -292,7 +389,7 @@ VERIFICATION CRITERIA MET:
   } else {
     console.log(`⚠️ Outcome not recognised by this version (action: ${result.action}). No conclusion drawn.`);
   }
-  console.log(`   Decision: ${result.decision}`);
+  console.log(`   Decision: ${result.decision ?? "none read (the stream dropped before it)"}`);
   console.log(`   View contract: ${BASE_URL}/contract/${invite.contractId}`);
   console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 }