cascrow-cli 1.2.2 → 1.3.0

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
 
@@ -55,6 +58,8 @@ contract, no escrow, no wallet.
 | `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.
@@ -109,7 +114,7 @@ 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
 ```
 
@@ -146,6 +151,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

@@ -50,25 +50,62 @@ async function uploadProof(milestoneId, content) {
   return data;
 }
 
+// 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) {
+    clearTimeout(timeout);
     const data = await res.json().catch(() => ({}));
     throw new Error(data.error ?? `HTTP ${res.status}`);
   }
+  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 +132,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");
 }
 
@@ -173,25 +225,72 @@ VERIFICATION CRITERIA MET:
     // 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...`);
+    // 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).
+    const TERMINAL_PROOF_STATES = ["VERIFIED", "COMPLETED", "REJECTED", "PENDING_REVIEW"];
     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}`);
+      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)) {
+        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.action === "SUPERSEDED") {
+    console.log(`ℹ️ 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(`   View contract: ${BASE_URL}/contract/${invite.contractId}`);
@@ -210,13 +309,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`
+      );
     }
   }
 

package/index.js

@@ -33,6 +33,18 @@ async function apiPost(path, body, key = API_KEY) {
   return data;
 }
 
+// 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
+// shapes (multipart image, JSON) throw through here.
+function standaloneFailure(status, data) {
+  const d = data ?? {};
+  const base = typeof d.error === "string" ? d.error : `HTTP ${status}`;
+  const report = typeof d.reportUrl === "string" ? d.reportUrl : typeof d.publicHash === "string" ? d.publicHash : null;
+  const ref = typeof d.id === "string" && report ? ` (verification id: ${d.id}, report: ${report})` : "";
+  return new Error(base + ref);
+}
+
 async function apiGet(path, key = API_KEY) {
   const res = await fetch(`${BASE_URL}${path}`, {
     headers: { ...authHeader(key) },
@@ -60,8 +72,11 @@ async function uploadProof(milestoneId, filename, content, key = API_KEY) {
 // Stream verify via SSE — used by the legacy two-step `submit` + `verify --proof <id>` flow
 async function streamVerify(proofId, key = API_KEY) {
   const controller = new AbortController();
-  // Below the 240s maxDuration of /api/verify — see src/lib/latency-budget.ts.
-  const timeout = setTimeout(() => controller.abort(), 200_000);
+  // 235s: one step below the 240s maxDuration of /api/verify, not above its
+  // worst case — the tail reaches ~239s, so no value is both. See
+  // VERIFY_TAIL_WORST_CASE_MS in src/lib/latency-budget.ts. Cleared after the read loop, not at the fetch
+  // (SEC-073), which is what makes the number mean anything.
+  const timeout = setTimeout(() => controller.abort(), 235_000);
 
   let res;
   try {
@@ -75,14 +90,35 @@ async function streamVerify(proofId, key = API_KEY) {
       body: JSON.stringify({ proofId }),
       signal: controller.signal,
     });
-  } finally {
+  } 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) {
+    // SEC-073, second pass. Replacing the fetch's `finally` with a `catch` left
+    // THIS exit uncovered: a 409 from /api/verify (already verified, panel in
+    // progress, resubmit limit) returned with a 235 s timer still pending. In a
+    // 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}`);
   }
+  if (!res.body) {
+    clearTimeout(timeout);
+    throw new Error("Verification stream had no body");
+  }
 
   const votes = [];
   const reader = res.body.getReader();
@@ -117,15 +153,127 @@ async function streamVerify(proofId, key = API_KEY) {
         }
       }
     }
+  // SEC-073. Cleared HERE, after the read loop — not in a `finally` around the
+  // `fetch`, which resolves on response HEADERS about 12 s into `/api/verify`
+  // while the whole 205 s retry ladder arrives afterwards out of `res.body`.
+  // At the fetch this was a time-to-first-byte deadline over a twelve-second
+  // phase, so its value bounded nothing and could sit below the server's worst
+  // case unnoticed. CLIENT_ABORT_MS was raised to 235_000 in the same commit.
+  } 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 a complete event");
 }
 
+/**
+ * One human-readable line for a verification `complete` frame.
+ *
+ * Every arm says whether FUNDS MOVED, because that is the one thing a caller cannot
+ * find out any other way. `action === "VERIFIED"` alone never means they did: a hold and
+ * a compliance block carry their own flag, a success arrives as `COMPLETED`, and a BARE
+ * `VERIFIED` is reachable only when the automatic release was attempted and FAILED.
+ */
+function outcomeLine(r) {
+  const c = r.confidence ?? 0;
+  if (r.action === "SUPERSEDED") {
+    return "ℹ️ 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}` : ""}.`;
+  }
+  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 === "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.`;
+  }
+  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.";
+  }
+  if (r.action === "PENDING_REVIEW") {
+    return `⏳ PENDING_REVIEW (${c}%) — manual review required.`;
+  }
+  if (r.action === "REJECTED") {
+    return `❌ REJECTED (${c}%) — resubmit with stronger proof.`;
+  }
+  return `⚠️ This verification finished with an outcome this CLI does not recognise (action: ${r.action}). NO conclusion was drawn — check the milestone status and upgrade cascrow-cli.`;
+}
+
 // ─── Output helpers ───────────────────────────────────────────────────────────
 
+
+/**
+ * One `verify/standalone` call under a client deadline (SEC-073).
+ *
+ * The route declares `maxDuration = 120`; without this the only signal a hung
+ * call gives is the platform tearing the connection down, which reaches the
+ * caller as a transport error with nothing in it to act on. One function rather
+ * than a copy per shape: the two fetches it wraps are twenty lines apart in the
+ * same handler, and a guard reading either in isolation would have reported the
+ * pair as protected (F-12/F-60).
+ *
+ * Mirrors `STANDALONE_CLIENT_ABORT_MS` in `src/lib/latency-budget.ts`. A
+ * published package cannot import from the app, so this is a copy by necessity;
+ * `standalone-client-deadline.test.ts` is what keeps the FOUR copies equal — this
+ * file, the other published package, the SDK, and the owner in
+ * `src/lib/latency-budget.ts`.
+ */
+const STANDALONE_CLIENT_ABORT_MS = 115_000;
+
+async function withStandaloneDeadline(run) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), STANDALONE_CLIENT_ABORT_MS);
+  try {
+    return await run(controller.signal);
+  } catch (err) {
+    if (err && err.name === "AbortError") {
+      throw new Error(
+        `Verification did not answer within ${Math.round(STANDALONE_CLIENT_ABORT_MS / 1000)}s. ` +
+          "The server may still be working on it — retry, and if it keeps timing out the panel is degraded."
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * MACHINE OUTPUT ON stdout, and that is the point of this comment.
+ *
+ * `SEC-116-INVENTORY` exempted this CLI with the reason "schreibt nach stdout/stderr
+ * für einen Menschen". That is true of `err()` below and of the human summaries — and
+ * FALSE of this function, which emits `JSON.stringify` for the "CI pipelines and
+ * subprocesses" the README names as the target. An exemption whose reason holds for
+ * one half of its own subject is F-70, and it is recorded here rather than left in a
+ * document nobody reads next to the code.
+ *
+ * No marker is added, and that is a decision rather than an omission: this CLI's JSON
+ * is a published output shape, and prefixing fields inside it would change what every
+ * existing parser reads. The honest statement instead — any free text in this output
+ * (`reasoning`, `summary`, per-model votes) is MODEL OUTPUT over evidence a
+ * counterparty submitted, and reaches you RAW. If you pipe it into a model, treat it
+ * as data and not as instructions; the marked surfaces are the two MCP servers and the
+ * `/api/agent/verify/*` routes.
+ */
 function print(obj) {
   console.log(JSON.stringify(obj, null, 2));
 }
@@ -154,6 +302,8 @@ Commands:
   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
   me            Print this agent's ID
 
 Options for each command:
@@ -189,7 +339,7 @@ Options for each command:
   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>          optional  override milestone amount
+    --amount <usd>          IGNORED   the escrowed amount is the milestone's own amountUSD
     --milestone <id>        optional
 
   submit  [legacy: use verify instead]
@@ -242,6 +392,13 @@ Examples:
   # (Builder agent runs:)
   cascrow check-invites
   cascrow join --invite <code>
+
+  # 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.
+  cascrow review-queue
+  cascrow review --contract <contractId> --decision APPROVE
+  cascrow review --contract <contractId> --decision REJECT --milestone <milestoneId>
 `);
   process.exit(0);
 }
@@ -317,18 +474,46 @@ async function cmdVerifyWork(args) {
     form.append("taskDescription", args.task);
     form.append("image", new Blob([imageBuffer], { type: imageMimeType }), args.image.split("/").pop());
 
-    const res = await fetch(`${BASE_URL}/api/verify/standalone`, {
-      method: "POST",
-      headers: { ...authHeader(API_KEY) },
-      body: form,
+    const { res, data: body } = await withStandaloneDeadline(async (signal) => {
+      const r = await fetch(`${BASE_URL}/api/verify/standalone`, {
+        method: "POST",
+        headers: { ...authHeader(API_KEY) },
+        body: form,
+        signal,
+      });
+      // 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() };
     });
-    data = await res.json();
-    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+    if (!res.ok) throw standaloneFailure(res.status, body);
+    // Assigned to the OUTER `data`, not shadowing it: `const { data }` inside the
+    // branch left the function-scoped variable undefined and the next line read
+    // `data.decision` off it. `node --check` accepts a shadow happily.
+    data = body;
   } else {
     const body = { taskDescription: args.task };
     if (args.pr) body.prUrl = args.pr;
     if (args.code) body.codeText = args.code;
-    data = await apiPost("/api/verify/standalone", body);
+    // Not `apiPost`: its generic throw drops the row reference the 500 carries.
+    const { res, data: answer } = await withStandaloneDeadline(async (signal) => {
+      const r = await fetch(`${BASE_URL}/api/verify/standalone`, {
+        method: "POST",
+        headers: { ...authHeader(API_KEY), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      // 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() };
+    });
+    if (!res.ok) throw standaloneFailure(res.status, answer);
+    // Assigned to the OUTER `data`, not shadowing it: `const { data }` inside the
+    // branch left the function-scoped variable undefined and the next line read
+    // `data.decision` off it. `answer` rather than `body` because this branch
+    // already has a `body` — the REQUEST payload — twelve lines up.
+    data = answer;
   }
 
   const votes = Array.isArray(data.modelVotes) ? data.modelVotes : [];
@@ -359,25 +544,48 @@ async function cmdVerifyWork(args) {
 // Auto-releases funds and mints NFT on approval — no separate `verify --proof <id>` needed.
 async function cmdVerify(args) {
   if (!API_KEY) err("CASCROW_API_KEY is not set");
-  if (!args.contract) err("--contract is required");
   if (!args.proof) err("--proof is required");
 
-  // Legacy mode: --proof looks like a proof ID (prf_...) and no --contract — use stream verify
+  // Legacy mode: --proof looks like a proof ID (prf_...) and no --contract — use stream verify.
+  // Checked BEFORE the --contract requirement below: that check used to run
+  // first and process.exit(1) whenever --contract was missing, which made
+  // this branch (and streamVerify()) permanently unreachable — exactly the
+  // invocation cmdSubmit's own output tells users to run.
   if (!args.contract && args.proof && !args.proof.includes(" ")) {
     process.stderr.write("\nRunning AI verification (5 models)...\n\n");
     const result = await streamVerify(args.proof);
-    const passed = result.decision === "YES" && (result.confidence ?? 0) >= 85;
+    // 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
+    // from the one a caller is asking. `COMPLETED`, `SUPERSEDED`, a compliance block
+    // and a release hold all rendered as verified, and a panel outage
+    // (`decision: "PENDING"`) rendered as "NOT VERIFIED 0%", i.e. our own outage read
+    // back to the builder as a rejection.
+    //
+    // `passed` now means MONEY MOVED, and only `COMPLETED` says that.
+    const released = result.action === "COMPLETED";
+    const passed = released;
     print({
       decision: result.decision,
       confidence: result.confidence,
       passed,
       action: result.action,
+      released,
+      alreadyReleased: result.alreadyReleased === true,
+      superseded: result.action === "SUPERSEDED",
+      complianceBlocked: result.complianceBlocked === true,
+      releaseHoldUntil: result.releaseHoldUntil ?? null,
+      panelUnavailable: result.timedOut === true,
+      txHash: result.txHash ?? null,
       reasoning: result.reasoning,
       modelVotes: (result.votes ?? []).map(v => ({ model: v.model, decision: v.decision, confidence: v.confidence })),
     });
+    process.stderr.write(outcomeLine(result) + "\n");
     return;
   }
 
+  if (!args.contract) err("--contract is required");
+
   // One-shot mode: text proof → /api/mcp/submit → verdict + auto-release
   const links = args.links
     ? args.links.split(",").map(l => l.trim()).filter(Boolean)
@@ -395,8 +603,18 @@ async function cmdVerify(args) {
     evidence,
   });
 
-  const verdict = data.verdict ?? "unknown";
+  // `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"
+    ? "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;
 
   // Print model votes if available
   const votes = Array.isArray(data.model_votes) ? data.model_votes : [];
@@ -407,20 +625,43 @@ async function cmdVerify(args) {
   process.stderr.write("\n");
 
   let statusLine;
-  if (verdict === "approved") {
+  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. " +
+      "Check the milestone status before resubmitting";
+  } else if (verdict === "panel_unavailable") {
+    statusLine =
+      "⏳ 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}`;
   } else if (verdict === "pending_review") {
     statusLine = `⏳ PENDING_REVIEW (${confidence}% confidence) — manual review triggered`;
-  } else {
+  } else if (verdict === "rejected") {
     statusLine = `❌ REJECTED (${confidence}% confidence) — resubmit with stronger proof`;
+  } else {
+    // Not a rejection: an outcome this version does not know. Drawing no conclusion is
+    // the one answer that cannot be wrong, and it makes the next value visible instead
+    // of silently a rejection.
+    statusLine =
+      `⚠️ This submission finished with an outcome this CLI does not recognise (verdict: ${verdict}). ` +
+      "No conclusion was drawn — check the milestone status and upgrade cascrow-cli";
   }
   process.stderr.write(statusLine + "\n\n");
 
   print({
     verdict,
     confidence,
-    passed: verdict === "approved",
+    // MONEY MOVED — not "the verdict was approved". A scheduled payout has not happened.
+    passed: verdict === "approved" && !releaseHoldUntil,
+    release_hold_until: releaseHoldUntil,
     reasoning: data.reasoning ?? "",
     on_chain_url: data.on_chain_url ?? null,
     proof_id: data.proof_id ?? null,
@@ -474,7 +715,14 @@ async function cmdEscrowFund(args) {
     agentPrivateKey: args["private-key"],
   };
   if (args.milestone) body.milestoneId = args.milestone;
-  if (args.amount) body.amountUSD = parseFloat(args.amount);
+  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);
@@ -540,6 +788,62 @@ async function cmdCheckInvites() {
   }
 }
 
+/**
+ * The funder's pending-verdict queue, and the verdict itself.
+ *
+ * Both go through the routes every other surface uses — `GET
+ * /api/agent/review-queue` and `POST /api/contracts/review` — which ask the same
+ * owner module, so the queue this prints and the queue the door accepts a
+ * 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
+ * its reader cannot act on names a remedy they are unable to perform (F-72).
+ */
+async function cmdReviewQueue() {
+  if (!API_KEY) err("CASCROW_API_KEY is not set");
+  const data = await apiGet("/api/agent/review-queue");
+  const contracts = data.contracts ?? [];
+  print(data);
+  if (contracts.length === 0) {
+    process.stderr.write("\nNo milestones are waiting for your verdict.\n\n");
+    return;
+  }
+  const lines = contracts.map((c) => {
+    const pending = c.pendingMilestones ?? [];
+    const ms =
+      pending.length === 1
+        ? `milestone ${pending[0].milestoneId}`
+        : pending.length > 1
+          ? `${pending.length} milestones pending — pass --milestone <id>`
+          : "contract-level review — omit --milestone";
+    return `  ${c.contractId}  ${c.amountUSD} RLUSD  (${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"
+  );
+}
+
+async function cmdReview(args) {
+  if (!API_KEY) err("CASCROW_API_KEY is not set");
+  const contractId = args.contract;
+  const decision = (args.decision ?? "").toUpperCase();
+  if (!contractId) err("--contract <id> is required (see: cascrow review-queue)");
+  if (decision !== "APPROVE" && decision !== "REJECT") err("--decision must be APPROVE or REJECT");
+  const body = args.milestone ? { contractId, decision, milestoneId: args.milestone } : { contractId, decision };
+  const data = await apiPost("/api/contracts/review", body);
+  print(data);
+  const what =
+    decision === "APPROVE"
+      ? "approved — the escrow is being released to the builder"
+      : "rejected — the milestone is back with the builder, who can resubmit";
+  process.stderr.write(`\nMilestone ${what}.${data.txHash ? `\nRelease tx: ${data.txHash}` : ""}\n\n`);
+}
+
 async function cmdMe() {
   if (!API_KEY) err("CASCROW_API_KEY is not set");
   const data = await apiGet("/api/agent/me");
@@ -569,6 +873,8 @@ try {
     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 "me":            await cmdMe();                break;
     default:
       console.error(`Unknown command: ${command}\n`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cascrow-cli",
-  "version": "1.2.2",
-  "description": "CLI for Cascrow — agentic escrow and verification on the XRP Ledger",
+  "version": "1.3.0",
+  "description": "CLI for Cascrow — trust infrastructure for the agent economy: AI verification, on-chain reputation, and milestone escrow on the XRP Ledger",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -20,7 +20,10 @@
     "milestone",
     "agent",
     "agentic",
-    "verification"
+    "verification",
+    "reputation",
+    "trust",
+    "agent-economy"
   ],
   "author": "Cascrow <dev@cascrow.com>",
   "license": "MIT",