cascrow-cli 1.3.0 → 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

@@ -53,7 +53,8 @@ is never anchored.
 | `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 |
@@ -97,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`
 
 ```
@@ -118,7 +126,7 @@ Exactly one of `--pr`, `--code`, or `--image` is required alongside `--task`.
 --milestone <id>        optional
 ```
 
-### `submit` [legacy — use `verify` instead]
+### `submit` [or use `verify` for text proof in one call]
 
 ```
 --milestone <id>        required
@@ -126,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`
 
 ```

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,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
@@ -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);
@@ -224,7 +258,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 +282,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,8 +331,20 @@ 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.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
@@ -292,7 +366,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`);
 }

package/index.js

@@ -19,20 +19,86 @@ function authHeader(key) {
   return key ? { "Authorization": `Bearer ${key}` } : {};
 }
 
-async function apiPost(path, body, key = API_KEY) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: {
-      ...authHeader(key),
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-  const data = await res.json();
-  if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+// Client deadlines (T11-A4). This package cannot import src/, so the one with an
+// owner is MIRRORED and checked against it by client-deadline-mirrors.test.ts:
+//   UPLOAD_CLIENT_ABORT_MS  mirrors UPLOAD_CLIENT_ABORT_MS in src/lib/latency-budget.ts
+// mcp/submit is 235 s like the stream (one step below its 240 s cap); everything
+// else gets the longest maxDuration any route has. None of these calls had a
+// deadline before.
+const UPLOAD_CLIENT_ABORT_MS = 120_000;
+const MCP_SUBMIT_CLIENT_ABORT_MS = 235_000;
+const REQUEST_CLIENT_ABORT_MS = 300_000;
+
+/** A response body parsed without trusting it to be JSON: an HTML 502 reads "HTTP 502 (non-JSON response from server)". */
+async function readJsonSafe(res) {
+  const text = await res.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: `HTTP ${res.status} (non-JSON response from server)`, code: "UPSTREAM_NON_JSON" };
+  }
+}
+
+/** Seconds the server asked us to wait: Retry-After, else `retry_after_seconds`. */
+function retryAfterOf(res, data) {
+  const header = res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : null;
+  if (header !== null && /^\d+$/.test(header.trim())) return Number(header.trim());
+  return typeof data?.retry_after_seconds === "number" ? data.retry_after_seconds : null;
+}
+
+/**
+ * The one way this CLI calls the API. Throws an Error carrying `status`, `code` and
+ * `retryAfterSeconds`; its message ends with the code in brackets, so a script that
+ * greps stderr can branch on it. The deadline covers the body read.
+ */
+async function fetchJson(method, path, { json, form, key = API_KEY, deadlineMs = REQUEST_CLIENT_ABORT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), deadlineMs);
+  let res;
+  let data;
+  try {
+    res = await fetch(`${BASE_URL}${path}`, {
+      method,
+      headers: { ...authHeader(key), ...(json !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(json !== undefined ? { body: JSON.stringify(json) } : form !== undefined ? { body: form } : {}),
+      signal: controller.signal,
+    });
+    data = await readJsonSafe(res);
+  } catch (e) {
+    if (e && e.name === "AbortError") {
+      throw Object.assign(
+        new Error(`No answer from ${path} within ${Math.round(deadlineMs / 1000)} s. The request may still complete on the server — check its result before repeating it. [CLIENT_TIMEOUT]`),
+        { status: 0, code: "CLIENT_TIMEOUT", retryAfterSeconds: null }
+      );
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok || data.code === "UPSTREAM_NON_JSON") {
+    const code = typeof data.code === "string" ? data.code : null;
+    const retryAfterSeconds = retryAfterOf(res, data);
+    const base = typeof data.error === "string" && data.error ? data.error : `HTTP ${res.status}`;
+    // A platform error page on a POST (typically the 504 when a route hits its own
+    // maxDuration — escrow-fund's is 120 s) does not mean the call failed: the function
+    // may have moved money before it was killed. Say so, and how to check.
+    const mayHaveCompleted = method !== "GET" && res.status >= 500 && data.code === "UPSTREAM_NON_JSON";
+    throw Object.assign(
+      new Error(
+        `${base}${retryAfterSeconds !== null && (res.status === 429 || res.status === 503) ? ` — retry after ${retryAfterSeconds} s` : ""}${code ? ` [${code}]` : ""}` +
+          (mayHaveCompleted ? ". The request may still have completed on the server — check the contract (cascrow get --contract <id>) before repeating it." : "")
+      ),
+      { status: res.status, code, retryAfterSeconds }
+    );
+  }
   return data;
 }
 
+async function apiPost(path, body, key = API_KEY, deadlineMs = REQUEST_CLIENT_ABORT_MS) {
+  return fetchJson("POST", path, { json: body, key, deadlineMs });
+}
+
 // SEC-078. A failed standalone verification still has a row, and the route answers
 // the 500 with `id`, `publicHash` and `reportUrl` so the caller who paid for it can name it. The
 // CLI only prints a string, so the reference goes into the string. Both request
@@ -46,12 +112,7 @@ function standaloneFailure(status, data) {
 }
 
 async function apiGet(path, key = API_KEY) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    headers: { ...authHeader(key) },
-  });
-  const data = await res.json();
-  if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
-  return data;
+  return fetchJson("GET", path, { key });
 }
 
 async function uploadProof(milestoneId, filename, content, key = API_KEY) {
@@ -59,14 +120,7 @@ async function uploadProof(milestoneId, filename, content, key = API_KEY) {
   const form = new FormData();
   form.append("file", blob, filename);
   form.append("milestoneId", milestoneId);
-  const res = await fetch(`${BASE_URL}/api/proof/upload`, {
-    method: "POST",
-    headers: { ...authHeader(key) },
-    body: form,
-  });
-  const data = await res.json();
-  if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
-  return data;
+  return fetchJson("POST", "/api/proof/upload", { form, key, deadlineMs: UPLOAD_CLIENT_ABORT_MS });
 }
 
 // Stream verify via SSE — used by the legacy two-step `submit` + `verify --proof <id>` flow
@@ -112,8 +166,21 @@ async function streamVerify(proofId, key = API_KEY) {
     // long-lived MCP server that holds the event loop and later aborts a fetch
     // that finished minutes ago.
     clearTimeout(timeout);
-    const data = await res.json().catch(() => ({}));
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+    const data = await readJsonSafe(res);
+    // T01-8. Upload starts verification by itself, so losing the claim to a RUNNING
+    // run is the normal case: wait for that run through proof-status instead of
+    // failing. This 409's Retry-After is the ~1 h takeover cutoff, never a wait.
+    if (res.status === 409 && data.code === "VERIFICATION_IN_PROGRESS" && data.phase === "running") {
+      process.stderr.write("  A verification of this proof is already running — waiting for it instead of starting another.\n");
+      const budgetMs = Math.max(30_000, Math.min(235_000, ((data.expected_done_in_seconds ?? 200) + 30) * 1000));
+      return { attached: true, status: await waitForProof(proofId, budgetMs, key) };
+    }
+    const code = typeof data.code === "string" ? data.code : null;
+    throw Object.assign(new Error(`${data.error ?? `HTTP ${res.status}`}${code ? ` [${code}]` : ""}`), {
+      status: res.status,
+      code,
+      retryAfterSeconds: retryAfterOf(res, data),
+    });
   }
   if (!res.body) {
     clearTimeout(timeout);
@@ -178,6 +245,73 @@ async function streamVerify(proofId, key = API_KEY) {
   throw new Error("Stream ended without a complete event");
 }
 
+/**
+ * Poll proof-status until the proof settles, the run is found dead, or `maxMs` runs
+ * out. Returns the last status read, with `stoppedBecause` set when it stopped early:
+ *   - 401 / 403: waiting does not change the key or the account;
+ *   - 404: permanent — upload answers only after the proof exists and proof-status
+ *     reads the primary database, so the proof was deleted or erased;
+ *   - "interrupted": the run that held the proof died (claimPhase "orphaned").
+ * 429 / 503 wait at least Retry-After, never past the budget; anything else is
+ * transient. A milestone that is closed, or parked for a human, also settles it.
+ */
+async function waitForProof(proofId, maxMs = 100_000, key = API_KEY, pollMs = 5_000) {
+  const started = Date.now();
+  let waitMs = pollMs;
+  let last = null;
+  while (Date.now() - started < maxMs) {
+    await new Promise((r) => setTimeout(r, waitMs));
+    waitMs = pollMs;
+    try {
+      last = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`, key);
+    } catch (e) {
+      if (e && (e.status === 401 || e.status === 403 || e.status === 404)) {
+        return { pending: true, proofId, stoppedBecause: e.status, error: e.message };
+      }
+      if (e && (e.status === 429 || e.status === 503) && typeof e.retryAfterSeconds === "number") {
+        waitMs = Math.min(Math.max(pollMs, e.retryAfterSeconds * 1000), Math.max(0, maxMs - (Date.now() - started)));
+      }
+      continue;
+    }
+    if (!last.pending || last.milestoneClosed === true) return { ...last, proofId };
+    // Parked for a human: no poll will change it (same rule as both MCP servers).
+    if (last.running !== true && last.milestoneStatus === "PENDING_REVIEW") return { ...last, proofId, awaitingHumanReview: true };
+    if (last.claimPhase === "orphaned") return { ...last, proofId, stoppedBecause: "interrupted" };
+  }
+  return { ...(last ?? {}), pending: true, proofId, timedOut: true };
+}
+
+/** One line for a proof-status result, saying whether funds moved (they did only at COMPLETED). */
+function statusSummary(s) {
+  if (s.stoppedBecause === 404) return `⛔ Proof ${s.proofId} no longer exists (deleted or erased). Nothing will verify it.`;
+  if (s.stoppedBecause === 401 || s.stoppedBecause === 403) return `⛔ Stopped: ${s.error}. Waiting does not change this — check CASCROW_API_KEY and that this account is a party to the contract.`;
+  if (s.stoppedBecause === "interrupted") {
+    // Not "re-run automatically": a claim with no timestamp is never taken over, and
+    // the retry cron skips demo contracts and milestones past PROOF_SUBMITTED.
+    return `⚠️ The last verification run was interrupted; nothing is running now. Once its claim is an hour old, \`cascrow verify --proof ${s.proofId}\` can start it again — or submit the proof again, which always works.`;
+  }
+  if (s.awaitingHumanReview) return "⏳ PENDING_REVIEW — the panel reached no verdict; a human decides. Waiting will not change it.";
+  if (s.timedOut) return `⏳ Still verifying. Check again: cascrow status --proof ${s.proofId} --wait`;
+  const conf = typeof s.confidence === "number" ? ` (${s.confidence}% confidence)` : "";
+  // COMPLETED first: proof-status reports a paid milestone as `milestoneClosed` too
+  // (terminalStatus COMPLETED), and the CLOSED arm below would read a release as
+  // "moves no funds" — SEC-059's inversion (same order as proofOutcomeLine in both
+  // MCP servers). Whether it was THIS proof's YES is `decision`.
+  if (s.milestoneStatus === "COMPLETED" || s.terminalStatus === "COMPLETED") {
+    return s.decision === "YES" ? `✅ COMPLETED${conf} — funds released.` : "✅ COMPLETED — funds released, but not on this proof's verdict (another proof or the funder's review approved it).";
+  }
+  if (s.milestoneClosed === true) {
+    return s.terminalReason === "RELEASED_ON_CHAIN"
+      ? "⛔ CLOSED (EXPIRED) — the chain shows the builder WAS paid, just not by this verification."
+      : `⛔ CLOSED — the milestone is ${s.terminalStatus ?? "closed"}; this verification moved no funds. Do not resubmit to it.`;
+  }
+  if (s.milestoneStatus === "VERIFIED" && s.releaseHoldUntil) return `⏸️ VERIFIED${conf} — payout scheduled for ${s.releaseHoldUntil}. NO FUNDS HAVE MOVED YET.`;
+  if (s.milestoneStatus === "VERIFIED") return `⚠️ VERIFIED${conf} — approved, no funds moved yet.`;
+  if (s.milestoneStatus === "PENDING_REVIEW") return `⏳ PENDING_REVIEW${conf} — manual review required.`;
+  if (s.decision === "NO") return `❌ REJECTED${conf}.`;
+  return `ℹ️ Decision: ${s.decision ?? "none"}${conf}, milestone ${s.milestoneStatus ?? "unknown"}.`;
+}
+
 /**
  * One human-readable line for a verification `complete` frame.
  *
@@ -189,7 +323,11 @@ async function streamVerify(proofId, key = API_KEY) {
 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.";
+    // `settledAs`: the milestone was closed (e.g. EXPIRED) before this verification could
+    // settle it, not beaten by a proof.
+    return r.settledAs
+      ? `ℹ️ SUPERSEDED — this milestone was closed (${r.settledAs}) before this verification could settle it, so it changed nothing and moved no funds. Do not resubmit to it.`
+      : "ℹ️ SUPERSEDED — another proof on this milestone was decided first, so this verification changed nothing. Your evidence was recorded.";
   }
   if (r.action === "COMPLETED") {
     return r.alreadyReleased === true
@@ -297,7 +435,8 @@ Commands:
   create        Create a milestone contract
   fund          Activate a milestone (simulation — no on-chain tx)
   escrow-fund   Fund a milestone with real on-chain RLUSD escrow
-  submit        Upload proof text (returns proofId for legacy verify flow)
+  submit        Upload proof text — verification starts by itself (then: status --proof <id> --wait)
+  status        Show (or --wait for) the verification result of a proof
   get           Get contract status and milestones
   join          Join a contract as Builder via invite code
   handoff       Send a contract invite to a Builder agent by Agent ID
@@ -328,9 +467,13 @@ Options for each command:
     --commit <sha>          optional  Git commit SHA or PR URL
 
   create
-    --title <title>         required  milestone title + acceptance criteria
+    --title <title>         required  short milestone title (printed on the certificate)
     --days <n>              optional  deadline days from now (default: 7)
     --amount <usd>          optional  RLUSD to lock in escrow (default: 0 = verification-only)
+    --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
     --contract <id>         required
@@ -342,11 +485,15 @@ Options for each command:
     --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
     --proof <text>          required
     --file <name>           optional  filename (default: proof-report.txt)
 
+  status
+    --proof <id>            required
+    --wait                  optional  wait up to ~2 min for the verdict; stops early when waiting cannot help
+
   get
     --contract <id>         required
 
@@ -376,7 +523,7 @@ Examples:
   cascrow register --email bot@example.com --password secret123
 
   # One-shot: create contract, fund it, then verify a code fix
-  cascrow create --title "Fix auth bug — all tests must pass" --days 7
+  cascrow create --title "Fix auth bug" --criteria "All tests pass; JWT expiry honoured; no new lint errors" --days 7
   cascrow fund --contract <contractId>
   cascrow verify --contract <contractId> --proof "Fixed JWT expiry bug in auth.ts, 42 tests green, PR #51 merged" --commit abc1234 --links https://github.com/you/repo/pull/51
 
@@ -403,6 +550,65 @@ Examples:
   process.exit(0);
 }
 
+// ─── The bar a milestone is judged against ────────────────────────────────────
+// COPY of normalizeMilestoneChecklist / normalizeCriteria in src/lib/milestone-bar-input.ts
+// (this package cannot import src/). milestone-bar-input-parity.test.ts runs this copy
+// against the owner over the same case matrix.
+const CHECKLIST_MAX_ITEMS = 20;
+const CHECKLIST_TITLE_MAX = 200;
+const CHECKLIST_ID_MAX = 100;
+const CRITERIA_MAX = 4000;
+const CHECKLIST_SEVERITIES = ["CRITICAL", "HIGH", "MEDIUM", "LOW"];
+
+function normalizeMilestoneChecklist(items) {
+  if (items === undefined || items === null) return undefined;
+  if (!Array.isArray(items)) throw new Error("verificationChecklist: must be an array of { title, severity?, id? }");
+  if (items.length === 0) return undefined;
+  if (items.length > CHECKLIST_MAX_ITEMS) throw new Error(`verificationChecklist: at most ${CHECKLIST_MAX_ITEMS} items`);
+  items.forEach((raw, i) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error(`verificationChecklist[${i}]: must be an object with a title`);
+    }
+  });
+  const withId = items.filter((it) => it.id !== undefined).length;
+  if (withId !== 0 && withId !== items.length) {
+    throw new Error("verificationChecklist: either give every item an id or none (ids are then assigned 1..n)");
+  }
+  const seen = new Set();
+  return items.map((it, i) => {
+    const title = typeof it.title === "string" ? it.title.trim() : "";
+    if (title.length === 0) throw new Error(`verificationChecklist[${i}]: title is required`);
+    if (title.length > CHECKLIST_TITLE_MAX) throw new Error(`verificationChecklist[${i}]: title must be at most ${CHECKLIST_TITLE_MAX} characters`);
+    let id = i + 1;
+    if (withId) {
+      if (typeof it.id !== "number" || !Number.isInteger(it.id) || it.id < 1 || it.id > CHECKLIST_ID_MAX) {
+        throw new Error(`verificationChecklist[${i}]: id must be an integer from 1 to ${CHECKLIST_ID_MAX}`);
+      }
+      if (seen.has(it.id)) throw new Error(`verificationChecklist[${i}]: duplicate id ${it.id}`);
+      seen.add(it.id);
+      id = it.id;
+    }
+    const out = { id, title };
+    if (it.severity !== undefined && it.severity !== null && it.severity !== "") {
+      const sev = typeof it.severity === "string" ? it.severity.trim().toUpperCase() : "";
+      if (!CHECKLIST_SEVERITIES.includes(sev)) {
+        throw new Error(`verificationChecklist[${i}]: severity must be one of ${CHECKLIST_SEVERITIES.join(", ")}`);
+      }
+      out.severity = sev;
+    }
+    return out;
+  });
+}
+
+function normalizeCriteria(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new Error("verificationCriteria: must be a string");
+  const v = value.trim();
+  if (v.length === 0) return undefined;
+  if (v.length > CRITERIA_MAX) throw new Error(`verificationCriteria: at most ${CRITERIA_MAX} characters (got ${v.length})`);
+  return v;
+}
+
 // ─── Argument parser ──────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -439,8 +645,8 @@ async function cmdRegister(args) {
       keyName: args["key-name"] ?? "cli",
     }),
   });
-  const data = await res.json();
-  if (!res.ok) err(data.error ?? `HTTP ${res.status}`);
+  const data = await readJsonSafe(res);
+  if (!res.ok || data.code === "UPSTREAM_NON_JSON") err(`${data.error ?? `HTTP ${res.status}`}${data.code ? ` [${data.code}]` : ""}`);
   print(data);
   console.error("\nSave your API key and set it:\n  export CASCROW_API_KEY=" + data.apiKey + "\n");
 }
@@ -484,7 +690,7 @@ async function cmdVerifyWork(args) {
       // The body is read INSIDE the deadline. A response whose headers arrived
       // and whose body then stalls is otherwise unbounded — a deadline that ends
       // at the headers bounds time-to-first-byte and nothing else (SEC-073).
-      return { res: r, data: await r.json() };
+      return { res: r, data: await readJsonSafe(r) };
     });
     if (!res.ok) throw standaloneFailure(res.status, body);
     // Assigned to the OUTER `data`, not shadowing it: `const { data }` inside the
@@ -506,7 +712,7 @@ async function cmdVerifyWork(args) {
       // The body is read INSIDE the deadline. A response whose headers arrived
       // and whose body then stalls is otherwise unbounded — a deadline that ends
       // at the headers bounds time-to-first-byte and nothing else (SEC-073).
-      return { res: r, data: await r.json() };
+      return { res: r, data: await readJsonSafe(r) };
     });
     if (!res.ok) throw standaloneFailure(res.status, answer);
     // Assigned to the OUTER `data`, not shadowing it: `const { data }` inside the
@@ -554,6 +760,13 @@ async function cmdVerify(args) {
   if (!args.contract && args.proof && !args.proof.includes(" ")) {
     process.stderr.write("\nRunning AI verification (5 models)...\n\n");
     const result = await streamVerify(args.proof);
+    // The run was already going (usually the one upload started): print its outcome
+    // as proof-status reports it — the stream's frame never arrived here.
+    if (result && result.attached) {
+      print(result.status);
+      process.stderr.write(statusSummary(result.status) + "\n");
+      return;
+    }
     // SEC-055/058/059 at the third published surface. `passed` used to be
     // `decision === "YES" && confidence >= 85`, i.e. a re-implementation of the
     // three-tier rule from the PROOF's verdict — which answers a different question
@@ -573,6 +786,11 @@ async function cmdVerify(args) {
       released,
       alreadyReleased: result.alreadyReleased === true,
       superseded: result.action === "SUPERSEDED",
+      // With SUPERSEDED: the TERMINAL status the row was already in (EXPIRED, COMPLETED),
+      // or null when another proof won it. It used to reach only the stderr line from
+      // `outcomeLine`, so a machine caller reading this JSON could not tell "closed —
+      // nothing moved, do not resubmit" from "another proof won" (round-3 pass 2).
+      settledAs: typeof result.settledAs === "string" ? result.settledAs : null,
       complianceBlocked: result.complianceBlocked === true,
       releaseHoldUntil: result.releaseHoldUntil ?? null,
       panelUnavailable: result.timedOut === true,
@@ -601,7 +819,7 @@ async function cmdVerify(args) {
     contract_id: args.contract,
     milestone_id: args.milestone ?? undefined,
     evidence,
-  });
+  }, API_KEY, MCP_SUBMIT_CLIENT_ABORT_MS);
 
   // `decided: "elsewhere"` and `panelUnavailable` are 200 responses that carry NO
   // `verdict` key, so `data.verdict ?? "unknown"` fell to the final arm below and told
@@ -624,8 +842,17 @@ async function cmdVerify(args) {
   }
   process.stderr.write("\n");
 
+  // With `decided: "elsewhere"`: the TERMINAL status the milestone was already in. EXPIRED
+  // is a funder cancel or the deadline, not "the funder's review, or a concurrent
+  // submission", and resubmitting to it is pointless.
+  const settledAs = verdict === "decided_elsewhere" && typeof data.settledAs === "string" ? data.settledAs : null;
+
   let statusLine;
-  if (verdict === "decided_elsewhere") {
+  if (settledAs) {
+    statusLine =
+      `ℹ️ This milestone was closed (${settledAs}) before this submission could settle it, so this submission ` +
+      "changed nothing and moved no funds itself. Your evidence was recorded. Do not resubmit to this milestone";
+  } else if (verdict === "decided_elsewhere") {
     statusLine =
       "ℹ️ This milestone was decided by another request while your proof was being verified — " +
       "by the funder's review, or by a concurrent submission. Your evidence was recorded. " +
@@ -662,6 +889,7 @@ async function cmdVerify(args) {
     // MONEY MOVED — not "the verdict was approved". A scheduled payout has not happened.
     passed: verdict === "approved" && !releaseHoldUntil,
     release_hold_until: releaseHoldUntil,
+    ...(settledAs ? { settled_as: settledAs } : {}),
     reasoning: data.reasoning ?? "",
     on_chain_url: data.on_chain_url ?? null,
     proof_id: data.proof_id ?? null,
@@ -679,12 +907,40 @@ async function cmdCreate(args) {
   deadline.setDate(deadline.getDate() + deadlineDays);
   const amountUSD = parseFloat(args.amount ?? "0");
 
+  // T07. The bar the panel judges against — kept OUT of the title, which is printed
+  // on the public certificate. Normalised by a copy of src/lib/milestone-bar-input.ts
+  // (milestone-bar-input-parity.test.ts runs it against the owner).
+  let criteriaRaw = typeof args.criteria === "string" ? args.criteria : undefined;
+  if (typeof args["criteria-file"] === "string") criteriaRaw = readFileSync(args["criteria-file"], "utf8");
+  let checklistRaw;
+  if (typeof args["checklist-file"] === "string") {
+    try {
+      checklistRaw = JSON.parse(readFileSync(args["checklist-file"], "utf8"));
+    } catch (e) {
+      err(`--checklist-file: not a JSON array of { title, severity?, id? } (${e.message})`);
+    }
+  }
+  const reviewMode = typeof args["review-mode"] === "string" ? args["review-mode"].toUpperCase() : undefined;
+  if (reviewMode !== undefined && !["AUTO", "MANUAL", "MANUAL_AUTO"].includes(reviewMode)) {
+    err("--review-mode must be AUTO, MANUAL or MANUAL_AUTO");
+  }
+  let criteria, checklist;
+  try {
+    criteria = normalizeCriteria(criteriaRaw);
+    checklist = normalizeMilestoneChecklist(checklistRaw);
+  } catch (e) {
+    err(e.message);
+  }
+
   const data = await apiPost("/api/contracts", {
     milestones: [{
       title: args.title,
       amountUSD,
       cancelAfter: deadline.toISOString(),
+      ...(criteria !== undefined ? { verificationCriteria: criteria } : {}),
+      ...(checklist !== undefined ? { verificationChecklist: checklist } : {}),
     }],
+    ...(reviewMode !== undefined ? { agentReviewMode: reviewMode } : {}),
   });
 
   const contractUrl = `${BASE_URL}/contract/${data.contractId}`;
@@ -742,7 +998,25 @@ async function cmdSubmit(args) {
     args.proof
   );
   print(data);
-  process.stderr.write(`\nProof submitted. Run: cascrow verify --proof ${data.proofId}\n\n`);
+  // Upload starts verification by itself — `verify --proof` would only race it.
+  process.stderr.write(`\nProof submitted; verification has started. Wait for the verdict: cascrow status --proof ${data.proofId} --wait\n\n`);
+}
+
+async function cmdStatus(args) {
+  if (!API_KEY) err("CASCROW_API_KEY is not set");
+  if (!args.proof) err("--proof is required");
+  if (args.wait) {
+    process.stderr.write("\nWaiting for the verification to settle (up to ~2 min)...\n\n");
+    const s = await waitForProof(args.proof, 120_000);
+    print(s);
+    process.stderr.write("\n" + statusSummary(s) + "\n\n");
+    return;
+  }
+  const data = await apiGet(`/api/agent/proof-status/${encodeURIComponent(args.proof)}`);
+  print(data);
+  process.stderr.write(
+    "\n" + (data.pending && data.milestoneClosed !== true ? `⏳ Still verifying${data.claimPhase === "orphaned" ? " — the run was interrupted" : ""}.` : statusSummary({ ...data, proofId: args.proof })) + "\n\n"
+  );
 }
 
 async function cmdGet(args) {
@@ -869,6 +1143,7 @@ try {
     case "fund":          await cmdFund(args);          break;
     case "escrow-fund":   await cmdEscrowFund(args);    break;
     case "submit":        await cmdSubmit(args);        break;
+    case "status":        await cmdStatus(args);        break;
     case "get":           await cmdGet(args);           break;
     case "join":          await cmdJoin(args);          break;
     case "handoff":       await cmdHandoff(args);       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cascrow-cli",
-  "version": "1.3.0",
+  "version": "1.4.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",