cascrow-mcp 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.8.0 — 2026-09-25
+
+- **Verification starts by itself after `cascrow_submit_proof`.** Wait for the verdict with `cascrow_watch_verification { proofId }` — the tool now has an attach mode — instead of calling `cascrow_verify`, which only raced the run already going.
+- `cascrow_verify` on a proof whose verification is already running waits for that run and returns its result, instead of failing with a 409.
+- `cascrow_create_contract` takes `verificationCriteria` and `verificationChecklist` per milestone (the bar the AI panel judges against — keep it out of the title, which is printed on the certificate) and `agentReviewMode`. A bad checklist item is refused locally with its index.
+- Every API call has a deadline and survives a non-JSON answer: a platform error page reads `HTTP 502 (non-JSON response from server) [UPSTREAM_NON_JSON]` instead of `Unexpected token '<'`. Errors carry the API's stable code and the server's Retry-After.
+- Waiting stops early — and says why — when it cannot help: 401 / 403, a deleted proof (404), an interrupted run. 429 / 503 wait at least Retry-After.
+- The server reports its real version (it said 1.6.2).

package/README.md

@@ -121,11 +121,11 @@ Rate limit: 3 registrations per IP per hour.
 
 | Tool | Description |
 |------|-------------|
-| `cascrow_create_contract` | Create a milestone contract. Returns `contractId` + `inviteCode`. |
-| `cascrow_submit_proof` | Submit proof text — auto-triggers AI verification. Returns `proofId`. |
-| `cascrow_verify` | Stream live 5-model AI verification results. |
+| `cascrow_create_contract` | Create a milestone contract. Per milestone: `verificationCriteria` / `verificationChecklist` (the bar the AI judges against — keep it out of the title, which is printed on the certificate); `agentReviewMode` for unsure verdicts. Returns `contractId` + `inviteCode`. |
+| `cascrow_submit_proof` | Submit proof text — verification starts by itself. Returns `proofId`; wait with `cascrow_watch_verification { proofId }`. |
+| `cascrow_verify` | Start or re-run 5-model AI verification. If a run is already going (e.g. the one upload started), waits for it instead of failing. |
 | `cascrow_get_proof_status` | Poll a submitted proof's verification result. |
-| `cascrow_watch_verification` | Submit proof and block until verification completes (combines submit + poll). |
+| `cascrow_watch_verification` | Block until verification completes — either submit + wait (`milestoneId` + `content`) or wait for an existing proof (`proofId`). Stops early and says why when waiting cannot help. |
 | `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call — auto-releases funds and mints the NFT on approval. |
 | `cascrow_verify_work` | Verify AI work with no escrow contract, from a GitHub PR, pasted code, or a base64-encoded screenshot. Returns a public report URL. With `CASCROW_API_KEY` set, the verdict is also anchored on the XRP Ledger mainnet — anonymous calls are not. |
 | `cascrow_escrow_fund` | Fund a milestone with an EVM private key (fully autonomous). |
@@ -177,7 +177,7 @@ Show me the contract link and confidence scores at the end.
 
 Claude will:
 1. `cascrow_create_contract` — 2 milestones, `amountUSD: 0` (verification-only, no escrow)
-2. Build each section → `cascrow_submit_proof` → `cascrow_verify`
+2. Build each section → `cascrow_submit_proof` → `cascrow_watch_verification`
 3. Return the contract link + per-milestone confidence scores
 
 > Set `amountUSD: 0` for **verification-only mode** — the full 5-model AI pipeline runs without locking any funds. Useful for trustless proof of work without payment.
@@ -189,7 +189,7 @@ Cascrow supports fully autonomous agent-to-agent payments:
 1. **Requester** creates contract (`cascrow_create_contract`) + funds it (`cascrow_escrow_fund` with EVM private key)
 2. Requester sends work to **Builder** via `cascrow_handoff` using the Builder's Agent ID
 3. Builder accepts via `cascrow_check_invites` + `cascrow_join_contract`
-4. Builder completes work → `cascrow_submit_proof` → `cascrow_verify`
+4. Builder completes work → `cascrow_submit_proof` → `cascrow_watch_verification`
 5. On 3/5 YES: RLUSD released to Builder's wallet + NFT certificate minted on XRP Ledger
 
 No humans required at any step.

package/index.js

@@ -43,47 +43,122 @@ if (ANONYMOUS_MODE) {
 
 const authHeader = API_KEY ? { "Authorization": `Bearer ${API_KEY}` } : {};
 
-async function apiPost(path, body) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: {
-      ...authHeader,
-      "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. This package cannot import src/, so the two that have an owner
+// are MIRRORED here 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_CLIENT_ABORT_MS  mirrors MCP_SUBMIT_CLIENT_ABORT_MS in src/lib/latency-budget.ts
+// Every other call gets REQUEST_CLIENT_ABORT_MS — the longest maxDuration any route
+// has, so it only ever stops a request the platform has already given up on. Before
+// T11 these calls had no deadline at all: a hung connection hung the tool call.
+const UPLOAD_CLIENT_ABORT_MS = 120_000;
+const MCP_SUBMIT_CLIENT_ABORT_MS = 235_000;
+const REQUEST_CLIENT_ABORT_MS = 300_000;
+
+/**
+ * An error from the API with what a caller needs to decide what to do next: the
+ * HTTP status, the stable `code` (src/lib/api-error.ts — or `UPSTREAM_NON_JSON` /
+ * `CLIENT_TIMEOUT`, which this client produces itself), and how long the server
+ * asked us to wait (`Retry-After`, else `retry_after_seconds`).
+ */
+class CascrowApiError extends Error {
+  constructor(message, { status, code = null, retryAfterSeconds = null, body = null } = {}) {
+    super(message);
+    this.name = "CascrowApiError";
+    this.status = status;
+    this.code = code;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.body = body;
   }
-  return data;
 }
 
-async function apiGet(path) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    headers: { ...authHeader },
-  });
-  const data = await res.json();
+function retryAfterOf(res, data) {
+  const header = res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : null;
+  const fromHeader = header !== null && /^\d+$/.test(header.trim()) ? Number(header.trim()) : null;
+  if (fromHeader !== null) return fromHeader;
+  return typeof data?.retry_after_seconds === "number" ? data.retry_after_seconds : null;
+}
+
+/**
+ * The one way this server talks to the API (T11-A3).
+ *
+ * The body is read as TEXT and parsed in a try: an HTML 502 from the platform used
+ * to reach `res.json()` and surface as "Unexpected token '<'", naming neither the
+ * status nor anything to do about it. The deadline covers the body read too — the
+ * timer is cleared after it, not after the headers (SEC-073's lesson). No retry
+ * here: a single call either answers or throws; only the poll loop waits and asks
+ * again.
+ */
+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 text;
+  try {
+    res = await fetch(`${BASE_URL}${path}`, {
+      method,
+      headers: { ...authHeader, ...(json !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(json !== undefined ? { body: JSON.stringify(json) } : form !== undefined ? { body: form } : {}),
+      signal: controller.signal,
+    });
+    text = await res.text();
+  } catch (e) {
+    if (e && e.name === "AbortError") {
+      throw new CascrowApiError(
+        `No answer from ${path} within ${Math.round(deadlineMs / 1000)} s. The request may still complete on the server — check its result before repeating it.`,
+        { status: 0, code: "CLIENT_TIMEOUT" }
+      );
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { error: `HTTP ${res.status} (non-JSON response from server)`, code: "UPSTREAM_NON_JSON" };
+    // A 200 that is not JSON is not a success anyone can read.
+    if (res.ok) throw new CascrowApiError(data.error, { status: res.status, code: data.code });
+  }
   if (!res.ok) {
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+    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 new CascrowApiError(
+      `${base}${code ? ` [${code}]` : ""}${retryAfterSeconds !== null && (res.status === 429 || res.status === 503) ? ` — retry after ${retryAfterSeconds} s` : ""}` +
+        (mayHaveCompleted ? ". The request may still have completed on the server — check the contract (cascrow_get_contract) before repeating it." : ""),
+      { status: res.status, code, retryAfterSeconds, body: data }
+    );
   }
   return data;
 }
 
-async function apiPatch(path, body) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "PATCH",
-    headers: {
-      ...authHeader,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-  const data = await res.json();
-  if (!res.ok) {
-    throw new Error(data.error ?? `HTTP ${res.status}`);
+/** A response body parsed without trusting it to be JSON (see fetchJson). */
+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" };
   }
-  return data;
+}
+
+// The names the handlers (and the tests that extract them) use. Thin wrappers.
+async function apiPost(path, body, deadlineMs) {
+  return fetchJson("POST", path, { json: body, deadlineMs });
+}
+
+async function apiGet(path) {
+  return fetchJson("GET", path);
+}
+
+async function apiPatch(path, body) {
+  return fetchJson("PATCH", path, { json: body });
 }
 
 async function uploadProof(milestoneId, filename, content) {
@@ -91,17 +166,7 @@ async function uploadProof(milestoneId, filename, content) {
   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 },
-    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 });
 }
 
 // Stream verify with a 235s deadline that covers the WHOLE read, quorum retries
@@ -153,8 +218,24 @@ async function streamVerify(proofId) {
     // 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 text = await res.text().catch(() => "");
+    let data;
+    try { data = text ? JSON.parse(text) : {}; } catch { data = { error: `HTTP ${res.status} (non-JSON response from server)`, code: "UPSTREAM_NON_JSON" }; }
+    // T01-5. Upload starts verification by itself, so a start that lost the claim to
+    // a RUNNING run is the normal case, not a failure: wait for that run instead.
+    // Never read this 409's Retry-After as a wait — it is the ~1 h takeover cutoff
+    // (SEC-093); `expected_done_in_seconds` is how long the run needs.
+    if (res.status === 409 && data.code === "VERIFICATION_IN_PROGRESS" && data.phase === "running") {
+      const budgetMs = Math.max(30_000, Math.min(235_000, ((data.expected_done_in_seconds ?? 200) + 30) * 1000));
+      const watch = await pollUntilSettled(proofId, budgetMs);
+      return { attached: true, watch: watch ?? stillRunningResult(proofId) };
+    }
+    throw new CascrowApiError(`${data.error ?? `HTTP ${res.status}`}${data.code ? ` [${data.code}]` : ""}`, {
+      status: res.status,
+      code: typeof data.code === "string" ? data.code : null,
+      retryAfterSeconds: retryAfterOf(res, data),
+      body: data,
+    });
   }
   if (!res.body) {
     clearTimeout(timeout);
@@ -223,18 +304,86 @@ async function streamVerify(proofId) {
 
 // ─── Tool definitions ─────────────────────────────────────────────────────────
 
+// ─── 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 — change both, or that test goes red.
+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;
+}
+
 const TOOLS = [
   {
     name: "cascrow_create_contract",
     description:
       "Create a Cascrow verification contract with one or more milestones. " +
-      "Each milestone defines a deliverable, its acceptance criteria, and a deadline. " +
-      "Returns contractId, milestoneIds, and a link to view the contract. " +
+      "Each milestone has a short title, a deadline and — separately — the bar the AI panel judges it against: " +
+      "verificationCriteria (prose) and/or verificationChecklist (items). Put acceptance criteria THERE, not in the title: " +
+      "the title is printed on the public certificate. " +
+      "Returns contractId, an inviteCode and a link to view the contract. " +
       "Use this BEFORE starting any work so the user can see the plan.",
     inputSchema: {
       type: "object",
       required: ["milestones"],
       properties: {
+        agentReviewMode: {
+          type: "string",
+          enum: ["AUTO", "MANUAL", "MANUAL_AUTO"],
+          description:
+            "What happens when the AI panel is unsure (confidence 60–85). AUTO (default) rejects; MANUAL waits for your decision " +
+            "via cascrow_review_contract; MANUAL_AUTO waits 48 h for your decision, then approves.",
+        },
         milestones: {
           type: "array",
           minItems: 1,
@@ -245,7 +394,30 @@ const TOOLS = [
             properties: {
               title: {
                 type: "string",
-                description: "Milestone title including acceptance criteria, e.g. 'Hero section with CTA — must be responsive down to 320px, LCP < 2s'",
+                description: "Short milestone title, e.g. 'Landing page hero section'. Printed on the public certificate — put the acceptance criteria in verificationCriteria / verificationChecklist instead.",
+              },
+              verificationCriteria: {
+                type: "string",
+                maxLength: 4000,
+                description:
+                  "What the AI panel checks the proof against, in prose, e.g. 'Responsive down to 320px, LCP under 2 s on mobile, CTA links to /signup'. " +
+                  "The panel judges the proof against this text; without it, it judges against the title alone.",
+              },
+              verificationChecklist: {
+                type: "array",
+                maxItems: 20,
+                description:
+                  "Optional checklist the panel scores item by item on TEXT proofs (a YES then needs every item addressed — stricter than criteria alone). " +
+                  "Image proofs are judged against the criteria, not the checklist. Give every item an id (1–100, unique) or none (ids are assigned 1..n).",
+                items: {
+                  type: "object",
+                  required: ["title"],
+                  properties: {
+                    id: { type: "integer", minimum: 1, maximum: 100 },
+                    title: { type: "string", maxLength: 200 },
+                    severity: { type: "string", enum: ["CRITICAL", "HIGH", "MEDIUM", "LOW"] },
+                  },
+                },
               },
               deadlineDays: {
                 type: "number",
@@ -303,8 +475,9 @@ const TOOLS = [
       "Write a detailed, specific proof report describing exactly what was built, " +
       "with verifiable evidence (URLs, metrics, specific implementation details). " +
       "The more specific and verifiable the proof, the higher the AI confidence score. " +
-      "NOTE: After submitting, the backend automatically triggers AI verification. " +
-      "You can call cascrow_verify afterwards to stream the live results.",
+      "NOTE: After submitting, the backend starts AI verification by itself. " +
+      "Wait for the verdict with cascrow_watch_verification { proofId } (or poll cascrow_get_proof_status). " +
+      "Do NOT call cascrow_verify for a proof you just submitted — its verification is already running.",
     inputSchema: {
       type: "object",
       required: ["milestoneId", "proof"],
@@ -324,10 +497,11 @@ const TOOLS = [
   {
     name: "cascrow_verify",
     description:
-      "Stream live AI verification results for a submitted proof. " +
+      "Start (or re-run) AI verification for a proof and return the result. " +
       "5 AI models vote in parallel (Claude, GPT-4o, Gemini, Mistral, Cerebras). " +
       "Returns decision, confidence score, action (VERIFIED/PENDING_REVIEW/REJECTED), and per-model votes. " +
-      "Call this after cascrow_submit_proof to get live results. " +
+      "Upload already starts verification by itself: for a proof you just submitted use cascrow_watch_verification { proofId } instead. " +
+      "If a verification of this proof is already running, this call waits for it rather than failing. " +
       "Confidence > 85 + YES = VERIFIED. Confidence 60–85 = PENDING_REVIEW (manual review needed). Confidence < 60 = REJECTED.",
     inputSchema: {
       type: "object",
@@ -636,17 +810,22 @@ const TOOLS = [
   {
     name: "cascrow_watch_verification",
     description:
-      "Submit a proof and wait for AI verification to complete — all in one call. " +
-      "Combines cascrow_submit_proof + polling into a single blocking tool. " +
+      "Wait for AI verification to complete — either submit a proof and wait (milestoneId + content), " +
+      "or wait for a proof you already submitted (proofId). Give one mode, not both. " +
       "Returns the final YES/NO decision, confidence score, and per-model votes once verification is done. " +
-      "Times out after ~100 seconds and returns the proofId so you can poll manually with cascrow_get_proof_status.",
+      "Stops early when waiting cannot help (proof deleted, no access, run interrupted) and says why. " +
+      "Times out after ~100 seconds and returns the proofId so you can call it again or poll cascrow_get_proof_status.",
     inputSchema: {
       type: "object",
-      required: ["milestoneId", "content"],
+      required: [],
       properties: {
+        proofId: {
+          type: "string",
+          description: "Wait for this already-submitted proof (e.g. from cascrow_submit_proof). Omit milestoneId and content in this mode.",
+        },
         milestoneId: {
           type: "string",
-          description: "The milestone ID to submit proof for",
+          description: "Submit mode: the milestone ID to submit proof for",
         },
         content: {
           type: "string",
@@ -663,7 +842,7 @@ const TOOLS = [
 
 // ─── Tool handlers ────────────────────────────────────────────────────────────
 
-async function handleCreateContract({ milestones }) {
+async function handleCreateContract({ milestones, agentReviewMode }) {
   const deadline = (days) => {
     const d = new Date();
     d.setDate(d.getDate() + (days ?? 7));
@@ -671,11 +850,26 @@ async function handleCreateContract({ milestones }) {
   };
 
   const payload = {
-    milestones: milestones.map((m) => ({
-      title: m.title,
-      amountUSD: m.amountUSD ?? 0,
-      cancelAfter: deadline(m.deadlineDays),
-    })),
+    milestones: milestones.map((m, i) => {
+      // Normalised here so a bad item is refused with its milestone and item index,
+      // not as a 400 on the whole contract. Copy of src/lib/milestone-bar-input.ts;
+      // milestone-bar-input-parity.test.ts runs this copy against the owner.
+      let criteria, checklist;
+      try {
+        criteria = normalizeCriteria(m.verificationCriteria);
+        checklist = normalizeMilestoneChecklist(m.verificationChecklist);
+      } catch (e) {
+        throw new Error(`milestones[${i}]: ${e.message}`);
+      }
+      return {
+        title: m.title,
+        amountUSD: m.amountUSD ?? 0,
+        cancelAfter: deadline(m.deadlineDays),
+        ...(criteria !== undefined ? { verificationCriteria: criteria } : {}),
+        ...(checklist !== undefined ? { verificationChecklist: checklist } : {}),
+      };
+    }),
+    ...(agentReviewMode !== undefined ? { agentReviewMode } : {}),
   };
 
   const data = await apiPost("/api/contracts", payload);
@@ -727,12 +921,17 @@ async function handleSubmitProof({ milestoneId, proof, filename }) {
   );
   return {
     proofId: data.proofId,
-    message: `Proof submitted (proofId: ${data.proofId}). AI verification has been triggered automatically. Call cascrow_verify with this proofId to stream the live results.`,
+    message:
+      `Proof submitted (proofId: ${data.proofId}). AI verification has started automatically. ` +
+      `Wait for the verdict with cascrow_watch_verification { proofId: "${data.proofId}" } — do not call cascrow_verify, it is already running.`,
   };
 }
 
 async function handleVerify({ proofId }) {
   const result = await streamVerify(proofId);
+  // The run was already going (usually the one upload started): its result, read
+  // from proof-status through the same formatters as cascrow_watch_verification.
+  if (result && result.attached) return result.watch;
   const decision   = result.decision ?? "?";
   const confidence = result.confidence ?? 0;
   const action     = result.action ?? "?";
@@ -810,7 +1009,12 @@ async function handleVerify({ proofId }) {
   const txHash = result.txHash ?? null;
   let statusLine;
   if (superseded) {
-    statusLine = `ℹ️ SUPERSEDED — another proof on this milestone was decided first, so this verification did not change its state. Your evidence was recorded. Check the milestone status before resubmitting.`;
+    // `settledAs` names a terminal row (e.g. EXPIRED) the verdict lost to, not a
+    // competing proof — "another proof won" would send the agent to resubmit.
+    const settledAs = result.settledAs;
+    statusLine = settledAs
+      ? `ℹ️ SUPERSEDED — this milestone was closed (${settledAs}) before this verification could settle it, so this verification changed nothing and moved no funds. Your evidence was recorded. Do not resubmit to this milestone.`
+      : `ℹ️ SUPERSEDED — another proof on this milestone was decided first, so this verification did not change its state. Your evidence was recorded. Check the milestone status before resubmitting.`;
   } else if (released) {
     statusLine = alreadyReleased
       ? `✅ COMPLETED — this milestone was already released by another request. The funds are out; do not resubmit.`
@@ -853,6 +1057,9 @@ async function handleVerify({ proofId }) {
     released,
     alreadyReleased,
     superseded,
+    // Returned as well as rendered, as the hosted route does: with SUPERSEDED it says
+    // the row was CLOSED rather than won by another proof.
+    ...(result.settledAs ? { settledAs: result.settledAs } : {}),
     releaseHoldUntil,
     reasoning,
     totalModels: TOTAL_MODELS,
@@ -1255,8 +1462,19 @@ async function handleListMyContracts({ role } = {}) {
  * another one and the milestone is in someone else's terminal state.
  */
 function proofOutcomeLine(s) {
+  // FIRST, before `decision` is read at all: a milestone that is already terminal
+  // cannot be moved by this proof's verdict. Since 2026-09-23 `/api/verify` leaves a
+  // row that went EXPIRED mid-panel EXPIRED and still persists the verdict, so a YES
+  // here used to print "✅ APPROVED" for money that may be back with the funder.
+  const closed = closedMilestoneStatus(s);
+  if (closed && closed !== "COMPLETED") return closedOutcomeLine(s, closed);
+  // SECOND: the milestone is approved (VERIFIED) or paid (COMPLETED), and not on a YES
+  // from this proof. Its `decision` is then NO or absent, and printing it next to
+  // "COMPLETED — funds released" or "APPROVED — payout scheduled" read as THIS proof
+  // having been approved.
+  if (approvedWithoutThisVerdict(s)) return approvedWithoutThisVerdictLine(s);
   const head =
-    s.milestoneStatus === "COMPLETED"
+    s.milestoneStatus === "COMPLETED" || closed === "COMPLETED"
       ? "✅ COMPLETED — funds released"
       : s.milestoneStatus === "VERIFIED" && s.releaseHoldUntil
         ? `⏸️ APPROVED — payout scheduled for ${s.releaseHoldUntil}, no funds have moved yet`
@@ -1266,6 +1484,61 @@ function proofOutcomeLine(s) {
   return `${head}${s.confidence != null ? ` (confidence: ${s.confidence}%)` : ""}`;
 }
 
+/**
+ * The terminal status of the row this proof settles against, or null while it is open.
+ *
+ * `milestoneClosed` is what `/api/agent/proof-status` derives from the row (the
+ * milestone, or the contract on the legacy contract-level path). `milestoneStatus` is
+ * the fallback for a server that predates the field — the same two statuses, so an
+ * older deployment does not reopen the defect this exists for.
+ */
+function closedMilestoneStatus(s) {
+  if (s.milestoneClosed === true) return s.terminalStatus || s.milestoneStatus || s.contractStatus || "EXPIRED";
+  // A legacy contract-level proof has no milestone: an older server reports its row only
+  // as `contractStatus`, and reading `milestoneStatus` alone printed APPROVED for a
+  // proof whose contract had EXPIRED.
+  const row = s.milestoneStatus ?? s.contractStatus;
+  return row === "EXPIRED" || row === "COMPLETED" ? row : null;
+}
+
+/**
+ * What happened to the money, from `terminalReason`. EXPIRED is not one story:
+ * `RELEASED_ON_CHAIN` means the chain shows the builder WAS paid (just not by this
+ * verification); the others mean the funder got the escrow back, or none existed. The
+ * vocabulary is `src/lib/terminal-reason.ts`; an absent or unknown value says so
+ * rather than guessing.
+ */
+function terminalStory(reason, row) {
+  switch (reason) {
+    case "RELEASED_ON_CHAIN":
+      return "The chain shows this milestone's escrow WAS released to the builder before it was closed — the builder was paid, but not by this verification.";
+    case "CANCELLED_AFTER_APPROVAL":
+      return "An earlier approval lost the race to the funder's on-chain cancel; the escrow was refunded to the funder.";
+    case "DEADLINE_EXPIRED":
+      return "The deadline passed and the escrow was cancelled, refunding the funder.";
+    case "RENEGOTIATION_REJECTED":
+      return "A requested extension was rejected and the escrow was cancelled, refunding the funder.";
+    case "NO_FUNDED_ESCROW":
+      return "No funded escrow existed on-chain for this milestone.";
+    case "CONTRACT_DECLINED":
+      return "The contract was declined or expired before anything was escrowed.";
+    default:
+      return `The reason was not recorded — check the ${row} before assuming where the funds are.`;
+  }
+}
+
+/** The outcome line for a proof whose milestone is terminal and not COMPLETED. */
+function closedOutcomeLine(s, closed) {
+  const row = proofRowNoun(s);
+  const verdict = s.decision
+    ? `The panel's verdict on this proof was ${s.decision}${s.confidence != null ? ` (confidence: ${s.confidence}%)` : ""}, and it changed nothing.`
+    : "No verdict was recorded for this proof.";
+  return (
+    `⛔ CLOSED — the ${row} was closed (${closed}) while the panel ran or after it decided, so this verification moved no funds. ` +
+    `${terminalStory(s.terminalReason, row)} ${verdict} There is nothing to poll for and nothing to resubmit to this ${row}.`
+  );
+}
+
 
 /**
  * One `verify/standalone` call under a client deadline (SEC-073).
@@ -1304,13 +1577,75 @@ async function withStandaloneDeadline(run) {
 }
 
 /**
- * `pending` means `aiDecision === null`, which has two causes that read the same and
- * are NOT the same thing: verification is still running, or the panel never reached a
- * verdict and the proof was parked for human review with `aiDecision` deliberately
- * left null. Told to keep polling, an agent polls FOREVER on the second one.
+ * "milestone", or "contract" for a legacy contract-level proof — which has no milestone,
+ * so a message telling the agent to "check the milestone" sent it looking for nothing.
+ * `milestoneStatus` is null exactly when the proof has no milestone row.
+ */
+function proofRowNoun(s) {
+  return s.milestoneStatus == null ? "contract" : "milestone";
+}
+
+/**
+ * True when the milestone is approved (VERIFIED) or paid (COMPLETED) and this proof has
+ * no YES of its own: another proof won it, or the funder approved it in review — which
+ * leaves this proof's `aiDecision` untouched (NO, or null after a panel outage).
+ *
+ * Either way nothing is left for THIS proof to decide. `/api/verify`'s claim excludes
+ * VERIFIED and COMPLETED for every verdict, so a pending proof here can never move the
+ * row: polling it burned the whole watch timeout, and `get_proof_status` said "poll
+ * again" for good. `/api/verify`'s SSE answered SUPERSEDED for the same state.
+ */
+function approvedWithoutThisVerdict(s) {
+  // Except while this proof's panel is RUNNING on a VERIFIED row. VERIFIED is not sticky:
+  // a definite release failure rolls it back, `contracts/review` hands it back to
+  // PENDING_REVIEW and the cron's hand-back blocks do the same, and a running claim then
+  // decides the row after all. COMPLETED is terminal and stays final either way.
+  // `running` is absent on a server that predates it, which keeps the old reading.
+  const row = closedMilestoneStatus(s) === "COMPLETED" ? "COMPLETED" : (s.milestoneStatus ?? s.contractStatus);
+  if (s.decision === "YES") return false;
+  return row === "COMPLETED" || (row === "VERIFIED" && s.running !== true);
+}
+
+/** Final: no later poll can change what this proof status says. */
+function nothingLeftToDecide(s) {
+  return closedMilestoneStatus(s) !== null || approvedWithoutThisVerdict(s);
+}
+
+/** The outcome line for `approvedWithoutThisVerdict`. It never says THIS proof was approved. */
+function approvedWithoutThisVerdictLine(s) {
+  const row = proofRowNoun(s);
+  const ROW = row.toUpperCase();
+  const head =
+    closedMilestoneStatus(s) === "COMPLETED"
+      ? `✅ ${ROW} COMPLETED — funds released`
+      : s.releaseHoldUntil
+        ? `⏸️ ${ROW} VERIFIED — payout scheduled for ${s.releaseHoldUntil}, no funds have moved yet (the funder can contest until then)`
+        : `✅ ${ROW} VERIFIED — the payout is not confirmed yet`;
+  const verdict =
+    s.decision === "NO"
+      ? `The panel did NOT approve this proof (NO${s.confidence != null ? `, confidence: ${s.confidence}%` : ""}).`
+      : "This proof has no panel verdict of its own.";
+  return (
+    `${head}, but not on this proof's verdict: another proof on this ${row}, or the funder's review, approved it. ` +
+    `${verdict} Nothing is left for this proof to decide — do not poll it and do not resubmit to this ${row}.`
+  );
+}
+
+/**
+ * `pending` means "no verdict on this proof": `aiDecision` is null (not claimed yet, or
+ * the panel never reached a verdict and the proof was parked for human review with
+ * `aiDecision` deliberately left null) or the claim sentinel "PENDING" (`/api/verify`'s
+ * panel is running on it). Those are NOT the same thing: told to keep polling, an agent
+ * polls FOREVER on a parked proof — and told to stop, it abandons a running one.
+ *
+ * `running` separates them. A proof whose panel is RUNNING is not parked even on a
+ * PENDING_REVIEW row: a sibling proof in the 60-85 band parked the milestone there while
+ * this one's panel still runs, and this one's claim can overwrite PENDING_REVIEW and go
+ * on to COMPLETED. Only a server that sends `running` can say so; without it the old
+ * reading stays.
  */
 function parkedForHuman(s) {
-  return Boolean(s.pending) && s.milestoneStatus === "PENDING_REVIEW";
+  return Boolean(s.pending) && s.running !== true && s.milestoneStatus === "PENDING_REVIEW";
 }
 
 const PARKED_MESSAGE =
@@ -1321,18 +1656,35 @@ const PARKED_MESSAGE =
 async function handleGetProofStatus({ proofId }) {
   const data = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`);
 
-  // `pending` means `aiDecision === null`, which has two causes that read the same and
-  // are NOT the same thing: verification is still running, or the panel never reached a
-  // verdict and the proof was parked for human review with `aiDecision` deliberately
-  // left null (`agent/proof-status` keeps it null by design there). Told to "poll again
-  // in a few seconds", an agent polls FOREVER on the second one. `milestoneStatus`
-  // separates them: a milestone already at PENDING_REVIEW is not waiting on a panel
-  // run, it is waiting on a person. `src/app/api/mcp/route.ts` has split these since
-  // SEC-010; this file, the published one, did not.
-  if (data.pending) {
+  // `pending` means "no verdict on this proof", which has two causes that read the same
+  // and are NOT the same thing: verification is still running (the claim sentinel, or
+  // not claimed yet), or the panel never reached a verdict and the proof was parked for
+  // human review with `aiDecision` deliberately left null (`agent/proof-status` keeps it
+  // null by design there). Told to "poll again in a few seconds", an agent polls FOREVER
+  // on the second one. `milestoneStatus` separates them: a milestone already at
+  // PENDING_REVIEW is waiting on a person — unless `running` says this proof's own panel
+  // is still going, which can still decide that row (`parkedForHuman`).
+  // `src/app/api/mcp/route.ts` has split these since SEC-010; this file, the published
+  // one, did not.
+  //
+  // A CLOSED milestone is asked first: an outage that lost to EXPIRED leaves
+  // `aiDecision` null for good on a row no verdict can move, and "poll again" would
+  // loop forever on it exactly like the parked case.
+  if (data.pending && !nothingLeftToDecide(data)) {
     if (parkedForHuman(data)) {
       return { ...data, message: `Proof ${proofId}: ${PARKED_MESSAGE}` };
     }
+    // An interrupted run (claimPhase "orphaned") reads as `pending` too, and "poll
+    // again" would send the agent into a loop nothing ends — the poll loops stop on
+    // it; this single read has to say it as well (F-50: same field, two doors).
+    if (data.claimPhase === "orphaned") {
+      return {
+        ...data,
+        message:
+          `The last verification run for proof ${proofId} was interrupted and nothing is running now. ` +
+          "Once its claim is an hour old, cascrow_verify can start it again — or submit the proof again, which always works.",
+      };
+    }
     return {
       ...data,
       message: `Proof ${proofId} is still being processed by the AI. Poll again in a few seconds.`,
@@ -1360,7 +1712,7 @@ async function handleGetProofStatus({ proofId }) {
 }
 
 async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
-  const data = await apiPost("/api/mcp/submit", { contract_id, milestone_id, evidence });
+  const data = await apiPost("/api/mcp/submit", { contract_id, milestone_id, evidence }, MCP_SUBMIT_CLIENT_ABORT_MS);
 
   const confidence = data.confidence ?? 0;
   const onChainUrl = data.on_chain_url ?? null;
@@ -1376,8 +1728,13 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
   // `src/app/api/mcp/route.ts` has handled this since someone hit it once already;
   // this file, the published one, never did.
   if (data.decided === "elsewhere") {
+    // `settledAs` names a TERMINAL row (EXPIRED, COMPLETED). EXPIRED is a funder cancel or
+    // the deadline cron, not "the investor's review, or a concurrent submission" — and the
+    // wording must not claim WHEN it closed relative to this submission.
+    const settledAs = typeof data.settledAs === "string" ? data.settledAs : null;
     return {
       verdict: "decided_elsewhere",
+      ...(settledAs ? { settledAs } : {}),
       confidence: null,
       reasoning: "",
       ...markVerificationResult({ model_votes: [] }),
@@ -1385,10 +1742,12 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
       proof_id: proofId,
       release_hold_until: null,
       signed_at: null,
-      message:
-        "ℹ️ This milestone was decided by another request while your proof was being verified — " +
-        "by the investor's review, or by a concurrent submission. Your evidence was recorded. " +
-        "Check the milestone status before resubmitting; a resubmission will be refused if it is already settled.",
+      message: settledAs
+        ? `ℹ️ 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."
+        : "ℹ️ This milestone was decided by another request while your proof was being verified — " +
+          "by the investor's review, or by a concurrent submission. Your evidence was recorded. " +
+          "Check the milestone status before resubmitting; a resubmission will be refused if it is already settled.",
     };
   }
 
@@ -1489,7 +1848,7 @@ async function handleVerifyWork({ taskDescription, prUrl, codeText, imageBase64,
       // 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
@@ -1511,7 +1870,7 @@ async function handleVerifyWork({ taskDescription, prUrl, codeText, imageBase64,
       // 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
@@ -1545,28 +1904,52 @@ async function handleVerifyWork({ taskDescription, prUrl, codeText, imageBase64,
   };
 }
 
-async function handleWatchVerification({ milestoneId, content, filename }) {
-  // Submit proof using existing multipart upload helper
-  const submitData = await uploadProof(milestoneId, filename ?? "proof-report.txt", content);
-  const proofId = submitData.proofId;
-  if (!proofId) {
-    throw new Error(submitData.error ?? "Proof submission failed — no proofId returned");
-  }
-
-  // Poll until verification completes (max 100s, every 5s)
-  const MAX_WAIT_MS = 100_000;
-  const POLL_MS = 5_000;
+/**
+ * Poll proof-status until the proof has an outcome worth returning, or `maxMs` runs
+ * out (then `null`). Shared by cascrow_watch_verification (both modes) and by
+ * cascrow_verify when its start lost to a run already going (T01-5).
+ *
+ * What stops the loop early, and why each is safe:
+ *   - 401 / 403: waiting does not change who you are.
+ *   - 404: permanent. proof/upload answers with a proofId only after the Proof row
+ *     exists, and proof-status reads the primary database (there is no replica), so
+ *     a 404 means the proof was deleted or erased, not "not there yet".
+ *   - `claimPhase: "orphaned"`: the run that held the claim is dead; nothing is
+ *     running to wait for.
+ * 429 / 503 wait at least what the server asked (Retry-After), never past `maxMs`.
+ * Anything else — a network error, a 5xx — is transient: poll again.
+ */
+async function pollUntilSettled(proofId, maxMs = 100_000, pollMs = 5_000) {
   const started = Date.now();
-
-  while (Date.now() - started < MAX_WAIT_MS) {
-    await new Promise((r) => setTimeout(r, POLL_MS));
+  let waitMs = pollMs;
+  while (Date.now() - started < maxMs) {
+    await new Promise((r) => setTimeout(r, waitMs));
+    waitMs = pollMs;
     let status;
     try {
       status = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`);
-    } catch {
-      continue; // transient error — keep polling
+    } catch (e) {
+      const code = e && typeof e.status === "number" ? e.status : null;
+      if (code === 401 || code === 403 || code === 404) {
+        return {
+          pending: true,
+          proofId,
+          stopped: { status: code, code: e.code ?? null },
+          message:
+            code === 404
+              ? `Stopped waiting: proof ${proofId} no longer exists (it was deleted or erased). Nothing will verify it.`
+              : `Stopped waiting for proof ${proofId}: ${e.message}. Waiting does not change this — check the API key and that this account is a party to the contract.`,
+        };
+      }
+      if ((code === 429 || code === 503) && typeof e.retryAfterSeconds === "number") {
+        // At least what the server asked, never past this loop's own budget.
+        waitMs = Math.min(Math.max(pollMs, e.retryAfterSeconds * 1000), Math.max(0, maxMs - (Date.now() - started)));
+      }
+      continue; // transient — keep polling
     }
-    if (!status.pending) {
+    // A closed milestone is terminal whether or not a verdict landed: waiting out the
+    // loop on a row no verdict can move burns the whole budget and then says "poll again".
+    if (!status.pending || nothingLeftToDecide(status)) {
       return {
         ...status,
         proofId,
@@ -1574,24 +1957,68 @@ async function handleWatchVerification({ milestoneId, content, filename }) {
       };
     }
     // Parked for a human: `pending` stays true forever on this path, so without this
-    // the loop burns its whole 100s and then tells the agent to poll some more.
+    // the loop burns its whole budget and then tells the agent to poll some more.
     if (parkedForHuman(status)) {
       return { ...status, proofId, message: `Proof ${proofId}: ${PARKED_MESSAGE}` };
     }
+    if (status.claimPhase === "orphaned") {
+      return {
+        ...status,
+        proofId,
+        message:
+          `The last verification run for proof ${proofId} was interrupted and nothing is running now. ` +
+          "Once its claim is an hour old, cascrow_verify can start it again — or submit the proof again, which always works. " +
+          "(If cascrow_verify then refuses with \"cannot be restarted automatically\", submit the proof again or contact support.)",
+      };
+    }
   }
+  return null;
+}
+
+function stillRunningResult(proofId) {
+  return {
+    pending: true,
+    proofId,
+    message: `Verification is still in progress. Wait for it with cascrow_watch_verification { proofId: "${proofId}" } or poll cascrow_get_proof_status.`,
+  };
+}
+
+async function handleWatchVerification({ milestoneId, content, filename, proofId: existingProofId } = {}) {
+  // Two modes, exactly one per call: SUBMIT (milestoneId + content) uploads and then
+  // waits; ATTACH (proofId) only waits — for a proof already submitted, whose
+  // verification upload started by itself.
+  const attach = typeof existingProofId === "string" && existingProofId.length > 0;
+  const submit = typeof content === "string" && typeof milestoneId === "string";
+  if (attach === submit) {
+    throw new Error(
+      "Give EITHER proofId (wait for a proof already submitted) OR milestoneId + content (submit, then wait) — not both, not neither."
+    );
+  }
+
+  let proofId = existingProofId;
+  if (submit) {
+    const submitData = await uploadProof(milestoneId, filename ?? "proof-report.txt", content);
+    proofId = submitData.proofId;
+    if (!proofId) {
+      throw new Error(submitData.error ?? "Proof submission failed — no proofId returned");
+    }
+  }
+
+  const settled = await pollUntilSettled(proofId, 100_000);
+  if (settled) return settled;
 
   // Timed out — return proofId so agent can poll manually
   return {
     pending: true,
     proofId,
-    message: `Verification still in progress after ~100s. Poll the result with cascrow_get_proof_status using proofId: ${proofId}`,
+    message: `Verification still in progress after ~100s. Wait again with cascrow_watch_verification { proofId: "${proofId}" } or poll cascrow_get_proof_status.`,
   };
 }
 
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "cascrow", version: "1.6.2" },
+  { name: "cascrow", version: "1.8.0" },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cascrow-mcp",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "MCP server 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",

package/server.json

@@ -9,13 +9,13 @@
     "source": "github",
     "subfolder": "cascrow-mcp"
   },
-  "version": "1.6.0",
+  "version": "1.8.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "cascrow-mcp",
-      "version": "1.6.0",
+      "version": "1.8.0",
       "transport": {
         "type": "stdio"
       },