cascrow-cli 1.2.2 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 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,6 +1,6 @@
 # cascrow-cli
 
-Command-line interface for [Cascrow](https://cascrow.com) — agentic escrow and verification 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, milestone escrow) on the XRP Ledger, 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.
 
@@ -38,7 +38,10 @@ cascrow verify-work --task "Build a landing page with a working contact form" \
 ```
 
 Returns a decision, confidence score, per-model reasoning, and a public shareable report URL — no
-contract, no escrow, no wallet.
+contract, no escrow, no wallet. If `CASCROW_API_KEY` happens to be set in your environment, `verify-work`
+picks it up too (it's optional, not ignored) and the verdict is additionally anchored on the XRP Ledger
+mainnet — a commitment hash you can independently recompute from the report. Without a key, the verdict
+is never anchored.
 
 ## All Commands
 
@@ -50,11 +53,14 @@ contract, no escrow, no wallet.
 | `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 |
+| `review` | As funder: approve or reject a milestone under manual review | Yes |
 | `me` | Print this agent's ID | Yes |
 
 Run `cascrow --help` (or `cascrow`) any time for the full, always-current option reference.
@@ -92,11 +98,18 @@ 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)
+--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%)
 ```
 
+Keep acceptance criteria out of `--title`: the title is printed on the public
+certificate, and the panel judges the proof against `--criteria`.
+
 ### `fund`
 
 ```
@@ -109,11 +122,11 @@ Exactly one of `--pr`, `--code`, or `--image` is required alongside `--task`.
 ```
 --contract <id>         required
 --private-key <key>     required  EVM private key (funds come from this wallet)
---amount <usd>          optional  override milestone amount
+--amount <usd>          IGNORED   the escrowed amount is the milestone's own amountUSD
 --milestone <id>        optional
 ```
 
-### `submit` [legacy — use `verify` instead]
+### `submit` [or use `verify` for text proof in one call]
 
 ```
 --milestone <id>        required
@@ -121,6 +134,19 @@ Exactly one of `--pr`, `--code`, or `--image` is required alongside `--task`.
 --file <name>           optional  filename (default: proof-report.txt)
 ```
 
+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`
+
+```
+--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`
 
 ```
@@ -146,6 +172,24 @@ Exactly one of `--pr`, `--code`, or `--image` is required alongside `--task`.
 
 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.
+
+### `review`
+
+```
+--contract <id>         required  from `cascrow review-queue`
+--decision <APPROVE|REJECT>  required  APPROVE releases the escrow; 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
+```
+
 ## Environment
 
 | Variable | Description |

package/builder-agent.js

@@ -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,35 +73,73 @@ 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
+// one with no deadline at all: it was invisible to `latency-budget.test.ts`,
+// whose client list was three hand-typed files — and this file lives inside one
+// of the three packages already on that list, so the subject was PACKAGES where
+// the population is FILES (F-30).
+//
+// 235_000 — one step below the route's 240 s `maxDuration`, NOT "above the
+// worst case": the tail (pre-stream + a 15 s blob read + the 205 s ladder + the
+// bounded EVM retry) reaches ~239 s, so no value is both above it and below the
+// cap. See VERIFY_TAIL_WORST_CASE_MS in src/lib/latency-budget.ts. Cleared after
+// the READ LOOP rather than at the `fetch`: `fetch` resolves on response headers about 12 s in, and the whole
+// retry ladder arrives afterwards out of `res.body`.
 async function streamVerify(proofId) {
-  const res = await fetch(`${BASE_URL}/api/verify`, {
-    method: "POST",
-    headers: {
-      "Authorization": `Bearer ${API_KEY}`,
-      "Content-Type": "application/json",
-      "Accept": "text/event-stream",
-    },
-    body: JSON.stringify({ proofId }),
-  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 235_000);
+  let res;
+  try {
+    res = await fetch(`${BASE_URL}/api/verify`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+        "Accept": "text/event-stream",
+      },
+      body: JSON.stringify({ proofId }),
+      signal: controller.signal,
+    });
+  } catch (e) {
+    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.
+    if (e && e.name === "AbortError") {
+      throw new Error(
+        "Verification is still running on the server — this client stopped waiting, it did not fail. " +
+        `Poll GET /api/agent/proof-status/${proofId} for the verdict.`
+      );
+    }
+    throw e;
+  }
   if (!res.ok) {
-    const data = await res.json().catch(() => ({}));
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+    clearTimeout(timeout);
+    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);
+    throw new Error("Verification stream had no body");
   }
 
   const reader = res.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
 
+  try {
   while (true) {
     const { done, value } = await reader.read();
     if (done) break;
@@ -95,6 +166,21 @@ async function streamVerify(proofId) {
       }
     }
   }
+  } catch (e) {
+    // The deadline can now fire DURING the read — that is the whole point of
+    // clearing it below the loop rather than at the fetch. Same translation as
+    // the fetch-side catch above.
+    if (e && e.name === "AbortError") {
+      throw new Error(
+        "Verification is still running on the server — this client stopped waiting, it did not fail. " +
+        `Poll GET /api/agent/proof-status/${proofId} for the verdict.`
+      );
+    }
+    throw e;
+  } finally {
+    clearTimeout(timeout);
+    reader.cancel().catch(() => {});
+  }
   throw new Error("Stream ended without complete event");
 }
 
@@ -172,28 +258,115 @@ 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
+    // it under `status: { notIn: ["COMPLETED","EXPIRED"] }`, so it fails both
+    // ways. False negative: the pin is overwritten with FUNDED, no terminal value
+    // ever appears, and this loop dies after five minutes on "Timed out waiting
+    // for verification result" for a proof that was in fact decided. False
+    // positive: the contract reads VERIFIED/COMPLETED because ANOTHER milestone
+    // settled, and the builder is handed a verdict that is not their proof's -
+    // `decision` below is derived from it.
+    //
+    // `GET /api/contracts/{id}` returns `milestones: [{ id, status, … }]`, and we
+    // 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).
+    //
+    // 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}`);
-      if (["VERIFIED", "COMPLETED", "REJECTED", "PENDING_REVIEW"].includes(contract.status)) {
-        const decision = ["VERIFIED", "COMPLETED"].includes(contract.status) ? "YES" : "NO";
-        result = { decision, confidence: 0, action: contract.status };
-        console.log(`   ✓ Got result via polling: ${contract.status}`);
+      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}`);
         break;
       }
     }
     if (!result) throw new Error("Timed out waiting for verification result");
   }
 
-  const passed = result.decision === "YES" && result.confidence >= 85;
+  // SEC-055/058/059. This re-implemented the three-tier rule from the PROOF's verdict
+  // (`decision === "YES" && confidence >= 85`), so `COMPLETED`, `SUPERSEDED`, a
+  // compliance block and a release hold all printed "✅ VERIFIED", and a panel outage
+  // (`decision: "PENDING"`, confidence 0) printed "❌ NOT VERIFIED — 0% confidence" —
+  // our own outage read back to the builder as a rejection of their work.
+  //
+  // `passed` now means FUNDS MOVED, and only `COMPLETED` says that. The polling
+  // fallback above already derives `action` from the funded MILESTONE's status
+  // (SEC-076; it read the contract row until 2026-09-22), so both paths reach this
+  // with the same vocabulary.
+  const released = result.action === "COMPLETED";
+  const passed = released;
   console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-  if (passed) {
-    console.log(`✅ VERIFIED — ${result.confidence}% confidence`);
+  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.`
+    );
+  } 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 === "VERIFIED") {
+    console.log(`⚠️ VERIFIED — approved, but the automatic payout did NOT go through. No funds moved.`);
+  } 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") {
+    console.log(`⏳ PENDING_REVIEW — ${result.confidence}% confidence, manual review required.`);
+  } else if (result.action === "REJECTED") {
+    console.log(`❌ REJECTED — ${result.confidence}% confidence.`);
   } else {
-    console.log(`❌ NOT VERIFIED — ${result.confidence}% confidence`);
+    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`);
 }
@@ -210,13 +383,30 @@ async function main() {
   console.log(`   Share this ID with the Requester agent`);
   console.log(`   Polling for work every ${POLL_INTERVAL_MS / 1000}s...\n`);
 
-  // Register EVM wallet address so Requester can fund real escrow to this agent
+  // Register EVM wallet address so Requester can fund real escrow to this agent.
+  //
+  // POST /api/user/wallet proves key possession: it wants a challenge token from
+  // GET /api/user/wallet/challenge plus a signature over the nonce it carries.
+  // This CLI is deliberately dependency-free and Node's crypto cannot produce an
+  // EIP-191 signature (no keccak256, no recovery id), so it cannot complete that
+  // flow on its own — and posting the address alone has been answered with 400
+  // since the check went in. Say so plainly instead of warning past it: a
+  // builder whose wallet is not linked is not discoverable and cannot be paid,
+  // which is worth more than one line of yellow text.
   if (AGENT_EVM_WALLET) {
     try {
       await apiPost("/api/user/wallet", { walletAddress: AGENT_EVM_WALLET });
       console.log(`   💳 EVM wallet registered: ${AGENT_EVM_WALLET}\n`);
     } catch (e) {
-      console.warn(`   ⚠️  Could not register wallet: ${e.message}`);
+      console.warn(
+        `   ⚠️  Wallet NOT linked (${e.message}).\n` +
+          `      ${AGENT_EVM_WALLET} is unusable until it is: escrow cannot be funded to it\n` +
+          `      and this agent will not appear in /api/agent/discover.\n` +
+          `      Link it once, from a signer that holds the key:\n` +
+          `        1. GET  ${BASE_URL}/api/user/wallet/challenge   (Bearer <your API key>)\n` +
+          `        2. sign the nonce in the returned token with the wallet's key\n` +
+          `        3. POST ${BASE_URL}/api/user/wallet { walletAddress, signature, token }\n`
+      );
     }
   }