cascrow-cli 1.2.2 → 1.4.0

package/index.js

@@ -19,27 +19,100 @@ 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
+// 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) },
-  });
-  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) {
@@ -47,21 +120,17 @@ 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
 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,13 +144,47 @@ 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) {
-    const data = await res.json().catch(() => ({}));
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+    // 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 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);
+    throw new Error("Verification stream had no body");
   }
 
   const votes = [];
@@ -117,15 +220,198 @@ 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");
 }
 
+/**
+ * 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.
+ *
+ * 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") {
+    // `settledAs`: the milestone was closed (e.g. EXPIRED) before this verification could
+    // settle it, not beaten by a proof.
+    return r.settledAs
+      ? `ℹ️ SUPERSEDED — this milestone was closed (${r.settledAs}) before this verification could settle it, so it changed nothing and moved no funds. Do not resubmit to it.`
+      : "ℹ️ SUPERSEDED — another proof on this milestone was decided first, so this verification changed nothing. Your evidence was recorded.";
+  }
+  if (r.action === "COMPLETED") {
+    return r.alreadyReleased === true
+      ? "✅ COMPLETED — this milestone was already released by another request. The funds are out; do not resubmit."
+      : `✅ COMPLETED (${c}% confidence) — funds released${r.txHash ? `, tx ${r.txHash}` : ""}.`;
+  }
+  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));
 }
@@ -149,11 +435,14 @@ 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
   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:
@@ -178,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
@@ -189,14 +482,18 @@ 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]
+  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
 
@@ -226,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
 
@@ -242,10 +539,76 @@ 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);
 }
 
+// ─── 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) {
@@ -282,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");
 }
@@ -317,18 +680,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 readJsonSafe(r) };
     });
-    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 readJsonSafe(r) };
+    });
+    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 +750,60 @@ 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;
+    // 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
+    // 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",
+      // 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,
+      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)
@@ -393,10 +819,20 @@ async function cmdVerify(args) {
     contract_id: args.contract,
     milestone_id: args.milestone ?? undefined,
     evidence,
-  });
-
-  const verdict = data.verdict ?? "unknown";
+  }, API_KEY, MCP_SUBMIT_CLIENT_ABORT_MS);
+
+  // `decided: "elsewhere"` and `panelUnavailable` are 200 responses that carry NO
+  // `verdict` key, so `data.verdict ?? "unknown"` fell to the final arm below and told
+  // the builder "❌ REJECTED — resubmit with stronger proof" for a milestone that may
+  // well have been approved and paid (SEC-055). Classified before the verdict is read.
+  const verdict = data.decided === "elsewhere"
+    ? "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 : [];
@@ -406,21 +842,54 @@ 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 === "approved") {
+  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. " +
+      "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,
+    ...(settledAs ? { settled_as: settledAs } : {}),
     reasoning: data.reasoning ?? "",
     on_chain_url: data.on_chain_url ?? null,
     proof_id: data.proof_id ?? null,
@@ -438,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}`;
@@ -474,7 +971,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);
@@ -494,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) {
@@ -540,6 +1062,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");
@@ -565,10 +1143,13 @@ 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;
     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`);