cascrow-sdk 0.1.0 → 0.4.0

package/dist/client.js

@@ -1,17 +1,216 @@
-function makeApiError(status, body) {
-    const message = typeof body === "object" && body !== null && "error" in body && typeof body.error === "string"
-        ? body.error
-        : `HTTP ${status}`;
+/**
+ * Client deadlines, mirrored from `src/lib/latency-budget.ts` (SEC-073).
+ *
+ * A published package cannot import from the app, so these are copies by
+ * necessity. `standalone-client-deadline.test.ts` is what keeps every copy in the
+ * tree equal — a number typed in FOUR places (this file, `cascrow-mcp`,
+ * `cascrow-cli`, and the owner in `src/lib/latency-budget.ts`) is four numbers
+ * that agree today.
+ */
+/** `/api/verify` streams under a 240 s function cap; one step below its kill. */
+const CLIENT_ABORT_MS = 235_000;
+/** `/api/verify/standalone` is capped at 120 s. */
+const STANDALONE_CLIENT_ABORT_MS = 115_000;
+/**
+ * The default for every other call. The longest `maxDuration` any route in this
+ * API declares is 240 s, so this cannot cut a legitimately slow on-chain call
+ * short — it only bounds a connection nobody is on the other end of.
+ */
+const REQUEST_TIMEOUT_MS = 240_000;
+/**
+ * `/api/proof/upload`: its 30 s function cap plus a transfer allowance for a
+ * 20 MB body. Mirrors `UPLOAD_CLIENT_ABORT_MS` in src/lib/latency-budget.ts;
+ * `client-deadline-mirrors.test.ts` keeps the two equal. `submitProof` had NO
+ * deadline before T11.
+ */
+const UPLOAD_CLIENT_ABORT_MS = 120_000;
+/**
+ * An API error a caller can branch on (T11-A2): the HTTP status, the stable `code`
+ * (see the API's error codes — plus `UPSTREAM_NON_JSON`, which this client sets when
+ * the server answered with something that is not JSON), and how long the server
+ * asked us to wait (`Retry-After`, else `retry_after_seconds`). Additive: `status`,
+ * `body` and the message are what they always were.
+ */
+function makeApiError(status, body, headers) {
+    const b = (typeof body === "object" && body !== null ? body : {});
+    const message = typeof b.error === "string" ? b.error : `HTTP ${status}`;
     const err = new Error(message);
     err.status = status;
     err.body = body;
+    err.code = typeof b.code === "string" ? b.code : null;
+    const header = headers?.get("retry-after") ?? null;
+    err.retryAfterSeconds =
+        header !== null && /^\d+$/.test(header.trim())
+            ? Number(header.trim())
+            : typeof b.retry_after_seconds === "number"
+                ? b.retry_after_seconds
+                : null;
+    // The lost-claim 409 (VERIFICATION_IN_PROGRESS) says whether a run is going and
+    // where to watch it — `waitForProof(proofId)` is the call to make then.
+    if (typeof b.phase === "string")
+        err.phase = b.phase;
+    if (typeof b.watch_url === "string")
+        err.watchUrl = b.watch_url;
+    if (typeof b.expected_done_in_seconds === "number")
+        err.expectedDoneInSeconds = b.expected_done_in_seconds;
     return err;
 }
+/** A body parsed without trusting it to be JSON: an HTML 502 is "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" };
+    }
+}
+/** True when `value` is the non-JSON marker `readJsonSafe` produced. */
+function isNonJson(value) {
+    return typeof value === "object" && value !== null && value.code === "UPSTREAM_NON_JSON";
+}
+// ─── The bar a milestone is judged against ────────────────────────────────────
+// COPY of normalizeMilestoneChecklist / normalizeCriteria in src/lib/milestone-bar-input.ts
+// (a published package cannot import the app). 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((raw, i) => {
+        const it = raw;
+        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;
+}
 /**
  * Typed client for the Cascrow API. Wraps the same REST endpoints used by
  * the cascrow-mcp server and the Cascrow web app — this is the plain-code
  * equivalent for applications that don't go through an MCP/LLM tool call.
  */
+/** Every `action` the verification stream can send. Kept next to the check so the
+ *  two cannot drift: adding a value to `VerificationResult["action"]` without adding
+ *  it here makes this file fail to compile. */
+const STREAM_ACTIONS = ["VERIFIED", "PENDING_REVIEW", "REJECTED", "COMPLETED", "SUPERSEDED"];
+/**
+ * The stream's `action`, or a thrown error — never an invented verdict.
+ *
+ * SEC-059. This used to be `(msg.action as VerificationResult["action"]) ?? "REJECTED"`,
+ * twice. Two things were wrong with it. The cast accepted `COMPLETED` and `SUPERSEDED`
+ * — real values the stream sends — while the declared union listed neither, so the
+ * returned object was outside its own type and nothing said so. And the fallback
+ * invented `REJECTED` for an absent field: a missing `action` is a protocol violation,
+ * not a rejection, and defaulting it in the one direction that costs the builder their
+ * reputation is the worst available choice. Every `complete` frame the route sends
+ * carries an action, so this cannot fire against a healthy server; when it does fire,
+ * it throws the way a malformed frame already does rather than guessing.
+ */
+function requireAction(value) {
+    if (typeof value === "string" && STREAM_ACTIONS.includes(value)) {
+        return value;
+    }
+    throw new Error(`Verification stream sent an action this client does not know: ${JSON.stringify(value)}. ` +
+        `Expected one of ${STREAM_ACTIONS.join(", ")} — upgrade cascrow-sdk.`);
+}
+/**
+ * The terminal status of the row a proof settles against, or null while it is open.
+ * `milestoneClosed` is derived from the row by `/api/agent/proof-status`;
+ * `milestoneStatus` is the fallback for a server that predates the field.
+ */
+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 reported a proof whose
+    // contract had EXPIRED as open.
+    const row = s.milestoneStatus ?? s.contractStatus;
+    return row === "EXPIRED" || row === "COMPLETED" ? row : null;
+}
+/**
+ * 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). Nothing
+ * is left for this proof to decide: `/api/verify`'s claim excludes VERIFIED and
+ * COMPLETED for every verdict, so a pending proof there never gets one, and the loop
+ * below used to burn its whole timeout on it. Same predicate as both MCP surfaces.
+ */
+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);
+}
+/**
+ * Parked for a human: no verdict, the milestone at `PENDING_REVIEW`, and no panel running
+ * on this proof. A RUNNING proof on a PENDING_REVIEW row is not parked — a sibling proof
+ * in the 60-85 band put the milestone there while this one's panel still runs, and this
+ * one can still take it to COMPLETED. Same test as `parkedForHuman` at both MCP surfaces;
+ * without `running` (an older server) the old reading stays.
+ */
+function parkedForHuman(s) {
+    return Boolean(s.pending) && s.running !== true && s.milestoneStatus === "PENDING_REVIEW";
+}
 export class CascrowClient {
     apiKey;
     baseUrl;
@@ -22,19 +221,84 @@ export class CascrowClient {
     authHeaders() {
         return this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {};
     }
-    async request(method, path, body) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method,
-            headers: {
-                ...this.authHeaders(),
-                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
-            },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
-        const data = await res.json().catch(() => ({}));
-        if (!res.ok)
-            throw makeApiError(res.status, data);
-        return data;
+    /**
+     * Every non-streaming call carries a deadline (SEC-073).
+     *
+     * Before this, the only `AbortController` in the SDK was inside `verify()`, the
+     * streaming method — so `verifyWork()`, which waits on a route the platform
+     * kills at 120 s, waited forever and then surfaced a torn connection. The
+     * default is the longest cap any route in this API declares (240 s), so it
+     * cannot cut a legitimately slow on-chain call short; `verifyWork` passes the
+     * tighter one because its own route is capped lower.
+     *
+     * An `AbortError` is re-thrown as a sentence, not as the DOM error: a caller
+     * cannot tell "we stopped waiting" from "the panel said no" out of an
+     * exception whose message is "This operation was aborted" (F-72).
+     */
+    async request(method, path, body, timeoutMs = REQUEST_TIMEOUT_MS) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const isForm = typeof FormData !== "undefined" && body instanceof FormData;
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    ...this.authHeaders(),
+                    ...(body !== undefined && !isForm ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body === undefined ? undefined : isForm ? body : JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new Error(`cascrow did not answer ${method} ${path} within ${Math.round(timeoutMs / 1000)}s. ` +
+                    "This client stopped waiting; the server may still be working on it.");
+            }
+            clearTimeout(timer);
+            throw err;
+        }
+        // Cleared AFTER the body, not in a `finally` around the header fetch: a
+        // server that sends headers and then stalls the body was otherwise
+        // unbounded, and the promise below is what the caller actually waits on.
+        // The streaming path in this same file learned this already — its abort
+        // "only became load-bearing when the clearTimeout moved below the read loop".
+        try {
+            let data;
+            try {
+                data = await readJsonSafe(res);
+            }
+            catch (err) {
+                // The deadline can fire during the body read too; say so the same way as
+                // at the header fetch, with the code a caller branches on.
+                if (err instanceof Error && err.name === "AbortError") {
+                    const e = new Error(`cascrow did not finish answering ${method} ${path} within ${Math.round(timeoutMs / 1000)}s. ` +
+                        "This client stopped waiting; the server may still be working on it.");
+                    e.status = res.status;
+                    e.body = null;
+                    e.code = "CLIENT_TIMEOUT";
+                    e.retryAfterSeconds = null;
+                    throw e;
+                }
+                throw err;
+            }
+            // A 200 that is not JSON is not a success anyone can read.
+            if (!res.ok || isNonJson(data)) {
+                const err = makeApiError(res.status, data, res.headers);
+                // A platform error page on a POST (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.
+                if (method !== "GET" && res.status >= 500 && isNonJson(data)) {
+                    err.message += ". The request may still have completed on the server — check the contract (getContract) before repeating it.";
+                }
+                throw err;
+            }
+            return data;
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     // ─── Auth ───────────────────────────────────────────────────────────────────
     /** Self-register an agent account. No CAPTCHA, no email verification. Returns an API key — save it, it is shown only once. */
@@ -57,11 +321,27 @@ export class CascrowClient {
             return d.toISOString();
         };
         const data = await this.request("POST", "/api/contracts", {
-            milestones: input.milestones.map((m) => ({
-                title: m.title,
-                amountUSD: m.amountUSD ?? 0,
-                cancelAfter: cancelAfter(m.daysUntilDeadline),
-            })),
+            milestones: input.milestones.map((m, i) => {
+                // T07. Normalised here so a bad item is refused with its milestone and
+                // item index, not as a 400 on the whole contract. Nothing given → the
+                // body is what it always was.
+                let criteria;
+                let checklist;
+                try {
+                    criteria = normalizeCriteria(m.verificationCriteria);
+                    checklist = normalizeMilestoneChecklist(m.verificationChecklist);
+                }
+                catch (e) {
+                    throw new Error(`milestones[${i}]: ${e instanceof Error ? e.message : String(e)}`);
+                }
+                return {
+                    title: m.title,
+                    amountUSD: m.amountUSD ?? 0,
+                    cancelAfter: cancelAfter(m.daysUntilDeadline),
+                    ...(criteria !== undefined ? { verificationCriteria: criteria } : {}),
+                    ...(checklist !== undefined ? { verificationChecklist: checklist } : {}),
+                };
+            }),
             agentReviewMode: input.agentReviewMode,
         });
         return {
@@ -83,9 +363,52 @@ export class CascrowClient {
     async joinContract(inviteCode) {
         return this.request("POST", "/api/contracts/join", { inviteCode });
     }
-    /** Approve or reject a borderline (PENDING_REVIEW) contract. Only valid when agentReviewMode is MANUAL or MANUAL_AUTO. */
-    async reviewContract(contractId, decision) {
-        return this.request("POST", "/api/contracts/review", { contractId, decision });
+    /**
+     * Approve or reject a borderline (PENDING_REVIEW) MILESTONE. Only valid when
+     * agentReviewMode is MANUAL or MANUAL_AUTO.
+     *
+     * The CONTRACT row need not be PENDING_REVIEW: funding a later milestone
+     * overwrites that column, and such a contract is still reviewable. Only a
+     * terminal contract (COMPLETED, EXPIRED, DECLINED) is refused.
+     *
+     * `milestoneId` is optional while exactly one milestone of the contract is
+     * pending review and REQUIRED once more than one is — the API answers 400
+     * "Multiple milestones are pending review — specify milestoneId to
+     * disambiguate". Until this parameter existed an SDK caller had no way to
+     * comply with that refusal, which is exactly the case SEC-076 is about: a
+     * multi-milestone contract where a second proof lands while the first is
+     * still under review (SEC-120, F-72).
+     *
+     * Additive optional third argument — every existing call site still compiles.
+     */
+    async reviewContract(contractId, decision, milestoneId) {
+        return this.request("POST", "/api/contracts/review", milestoneId ? { contractId, decision, milestoneId } : { contractId, decision });
+    }
+    /**
+     * The contracts on which THIS agent, as funder, still owes a manual verdict.
+     *
+     * The pull behind the `manual_review.required` webhook. A webhook that does
+     * not arrive — the agent was down, the endpoint 500'd, the subscription was
+     * never made — is a decision that never gets made, and `cron/cancel-expired`
+     * then auto-approves the milestone after 48 h (agent contracts) or 14 days
+     * (human) and releases the escrow. The whole point of the 60–85 confidence
+     * band is that somebody looks.
+     *
+     * Every browser surface the funder has for this asks
+     * `funderReviewQueueWhere()`; so does this route, so the queue an agent polls
+     * and the queue `reviewContract` accepts a verdict on cannot come apart.
+     *
+     * `reviewMilestoneId` is what to pass to {@link reviewContract}: non-null when
+     * exactly one milestone of that contract is pending, `null` for the legacy
+     * contract-level population that is reviewed by `contractId` alone. When
+     * `pendingMilestones` holds more than one entry the milestone has to be chosen
+     * — `POST /api/contracts/review` answers 400 otherwise.
+     *
+     * `truncated` says the list is capped while `total` is not, so a poller does
+     * not read a short list as "that was all".
+     */
+    async reviewQueue() {
+        return this.request("GET", "/api/agent/review-queue");
     }
     /** Check for pending contract invites sent to this agent. */
     async checkInvites() {
@@ -100,25 +423,42 @@ export class CascrowClient {
     async fundMilestone(contractId, milestoneId) {
         return this.request("POST", "/api/agent/fund-milestone", milestoneId ? { contractId, milestoneId } : { contractId });
     }
-    /** Fund a milestone with real on-chain RLUSD escrow using the agent's own EVM private key. */
+    /**
+     * Fund a milestone with real on-chain RLUSD escrow using the agent's own EVM
+     * private key.
+     *
+     * **The escrowed amount is the milestone's own `amountUSD`.** The route
+     * destructures `{ contractId, milestoneId, agentPrivateKey }` and funds
+     * `milestone.amountUSD`; a body `amountUSD` has never been read.
+     *
+     * SEC-120 removed the parameter from both MCP tool schemas, the OpenAPI spec
+     * and the CLI — and stopped here, at the one surface where the demand was
+     * enforced by the COMPILER rather than merely written down: `amountUSD:
+     * number`, no `?`, and `input` forwarded whole. That is the same defect the
+     * removal was about, at the door that states it most strongly, and it
+     * survived because the correction was checked against the places that
+     * document the parameter rather than against the places that require it.
+     *
+     * It is deprecated rather than deleted: deleting it would break compilation
+     * for every existing caller, which is a worse answer than telling them the
+     * truth. It is no longer forwarded, so the request body now says what the
+     * server actually reads.
+     */
     async escrowFund(input) {
-        return this.request("POST", "/api/agent/escrow-fund", input);
+        const { contractId, agentPrivateKey, milestoneId } = input;
+        return this.request("POST", "/api/agent/escrow-fund", { contractId, agentPrivateKey, milestoneId });
     }
     // ─── Proof & verification ───────────────────────────────────────────────────
-    /** Submit a text proof report for a milestone. Automatically triggers AI verification. */
+    /**
+     * Submit a text proof report for a milestone. Verification starts by itself —
+     * wait for the verdict with `waitForProof(proofId)`; do not call `verify()` for it,
+     * that run is already going.
+     */
     async submitProof(input) {
         const form = new FormData();
         form.append("milestoneId", input.milestoneId);
         form.append("file", new Blob([input.content], { type: "text/plain" }), input.filename ?? "proof-report.txt");
-        const res = await fetch(`${this.baseUrl}/api/proof/upload`, {
-            method: "POST",
-            headers: this.authHeaders(),
-            body: form,
-        });
-        const data = await res.json().catch(() => ({}));
-        if (!res.ok)
-            throw makeApiError(res.status, data);
-        return data;
+        return this.request("POST", "/api/proof/upload", form, UPLOAD_CLIENT_ABORT_MS);
     }
     /** Check the AI verification result for a submitted proof (poll after submitProof). */
     async getProofStatus(proofId) {
@@ -126,11 +466,21 @@ export class CascrowClient {
     }
     /**
      * Stream live 5-model AI verification results for a submitted proof.
-     * Resolves once the final result event arrives (up to ~180s).
+     *
+     * By default resolves once the final result arrives, i.e. after the on-chain
+     * release, so `txHash` is populated. Pass `{ resolveOn: "decision" }` to
+     * resolve as soon as the AI verdict is known instead — typically several
+     * seconds earlier, since the release waits for a sidechain block. `txHash` is
+     * then null and the release is still in flight; use a webhook or
+     * `getProofStatus` if you need to observe it landing.
      */
-    async verify(proofId) {
+    async verify(proofId, options = {}) {
+        const resolveOn = options.resolveOn ?? "complete";
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 180_000);
+        // SEC-073: 235_000, and it only became load-bearing when the clearTimeout
+        // moved below the read loop — see src/lib/latency-budget.ts:CLIENT_ABORT_MS.
+        // Kept as a numeric literal because this package cannot import from src/.
+        const timeout = setTimeout(() => controller.abort(), CLIENT_ABORT_MS);
         let res;
         try {
             res = await fetch(`${this.baseUrl}/api/verify`, {
@@ -140,12 +490,28 @@ export class CascrowClient {
                 signal: controller.signal,
             });
         }
-        finally {
+        catch (e) {
+            clearTimeout(timeout);
+            if (e instanceof Error && e.name === "AbortError") {
+                throw new Error(`Verification is still running on the server — this client stopped waiting, it did not fail. Poll GET /api/agent/proof-status/${proofId} for the verdict.`);
+            }
+            throw e;
+        }
+        if (!res.ok) {
             clearTimeout(timeout);
+            // A 409 with code VERIFICATION_IN_PROGRESS and phase "running" means a run is
+            // already going (usually the one upload started): the error carries `phase`,
+            // `watchUrl` and `expectedDoneInSeconds` — call `waitForProof(proofId)`. Its
+            // `retryAfterSeconds` is the ~1 h takeover cutoff, NOT a backoff.
+            throw makeApiError(res.status, await readJsonSafe(res), res.headers);
         }
-        if (!res.ok || !res.body) {
-            const d = await res.json().catch(() => ({}));
-            throw makeApiError(res.status, d);
+        // Split from the line above, which was `!res.ok || !res.body`. A 200 with no
+        // body then produced `makeApiError(200, {})` — an "API error" carrying a
+        // success status, and the one door of six without the separate branch the
+        // other five have.
+        if (!res.body) {
+            clearTimeout(timeout);
+            throw new Error("Verification stream had no body");
         }
         const votes = [];
         const reader = res.body.getReader();
@@ -175,14 +541,48 @@ export class CascrowClient {
                     if (msg.type === "model_vote") {
                         votes.push(msg);
                     }
+                    else if (msg.type === "decision" && resolveOn === "decision") {
+                        return {
+                            decision: msg.decision ?? "NO",
+                            confidence: msg.confidence ?? 0,
+                            action: requireAction(msg.action),
+                            reasoning: msg.reasoning ?? "",
+                            modelVotes: votes,
+                            txHash: null,
+                        };
+                        // `reasoning` here is MODEL OUTPUT over evidence the counterparty
+                        // submitted, and it reaches you RAW. The MCP servers prefix it with an
+                        // explicit untrusted-content marker; this SDK does not, deliberately —
+                        // its return value may equally end up in a UI, where a marker is noise
+                        // on a page, and a library cannot know which.
+                        //
+                        // That asymmetry was justified in the app for a while with a sentence
+                        // that is FALSE of this file: "an agent reaching the SSE frames does so
+                        // through an MCP server that marks at its own end". A review pass found
+                        // this door — `verify()`/`verifyAndWait` hand the field to a
+                        // TypeScript agent with no MCP server in the path. The decision is
+                        // unchanged; the reason is now stated where it is true. If you feed this
+                        // into a model, treat it as data and not as instructions.
+                    }
                     else if (msg.type === "complete") {
                         return {
                             decision: msg.decision ?? "NO",
                             confidence: msg.confidence ?? 0,
-                            action: msg.action ?? "REJECTED",
+                            action: requireAction(msg.action),
                             reasoning: msg.reasoning ?? "",
                             modelVotes: votes,
                             txHash: msg.txHash ?? null,
+                            // Forwarded because `action` alone does not answer "did the money move":
+                            // a VERIFIED with a hold or a compliance block did not, and a COMPLETED
+                            // that someone else released did. SEC-058 / SEC-059.
+                            ...(msg.alreadyReleased === true ? { alreadyReleased: true } : {}),
+                            ...(typeof msg.releaseHoldUntil === "string" ? { releaseHoldUntil: msg.releaseHoldUntil } : {}),
+                            ...(msg.complianceBlocked === true ? { complianceBlocked: true } : {}),
+                            ...(msg.timedOut === true ? { timedOut: true } : {}),
+                            // With `action: "SUPERSEDED"`: the milestone was closed (e.g. EXPIRED)
+                            // before this verification could settle it, rather than decided by
+                            // another proof.
+                            ...(typeof msg.settledAs === "string" ? { settledAs: msg.settledAs } : {}),
                         };
                     }
                     else if (msg.type === "error") {
@@ -190,8 +590,26 @@ export class CascrowClient {
                     }
                 }
             }
+            // SEC-073. The abort timer is cleared HERE, after the read loop — not in a
+            // `finally` around the `fetch`. `fetch` resolves on response HEADERS, about
+            // 12 s into `/api/verify`, and the entire 205 s retry ladder arrives
+            // afterwards out of `res.body`. Clearing it at the fetch made this a
+            // time-to-first-byte deadline over a twelve-second phase, so the number
+            // bounded nothing that mattered and could sit below the server's worst
+            // case unnoticed.
+        }
+        catch (e) {
+            // SEC-073. Live deadline, so this can fire mid-read; and per
+            // latency-budget.ts the abort can land after releaseMilestone(), which
+            // makes a bare "aborted" not merely unhelpful but possibly false about
+            // whether the money moved.
+            if (e instanceof Error && 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("Verification stream ended without a complete event");
@@ -212,48 +630,179 @@ export class CascrowClient {
                 custom_fields: input.evidence.customFields,
             },
         });
+        // Ordered so the two verdict-less responses are classified before the field that
+        // is missing on both is read. A `?? "rejected"` here would be the same
+        // wrong-direction default `requireAction` above was written to remove.
+        const verdict = data.decided === "elsewhere"
+            ? "decided_elsewhere"
+            : data.panelUnavailable
+                ? "panel_unavailable"
+                : data.verdict;
+        if (!verdict) {
+            throw new Error("mcp/submit answered 200 with no verdict and no known refusal state — upgrade cascrow-sdk.");
+        }
         return {
-            verdict: data.verdict,
-            confidence: data.confidence,
-            reasoning: data.reasoning,
-            onChainUrl: data.on_chain_url,
-            proofId: data.proof_id,
+            verdict,
+            confidence: data.confidence ?? null,
+            reasoning: data.reasoning ?? "",
+            onChainUrl: data.on_chain_url ?? null,
+            proofId: data.proof_id ?? null,
+            releaseHoldUntil: data.release_hold_until ?? null,
+            settledAs: verdict === "decided_elsewhere" && typeof data.settledAs === "string" ? data.settledAs : null,
         };
     }
     /**
      * Verify AI-generated work with no escrow contract — a task description
-     * plus a GitHub PR URL or pasted code. Works without an API key (3 free
-     * anonymous verifications per IP per 24h); pass an apiKey for more credits.
+     * plus a GitHub PR URL or pasted code. Works without an API key: 3 free
+     * verifications per IP per 24h. An API key attributes the result to your
+     * account but does not raise that allowance today — there is no paid tier
+     * yet, so do not treat a key as a way to get more runs.
      */
     async verifyWork(input) {
-        return this.request("POST", "/api/verify/standalone", input);
+        return this.request("POST", "/api/verify/standalone", input, STANDALONE_CLIENT_ABORT_MS);
+    }
+    /**
+     * True when a thrown `CascrowApiError` means "cascrow could not run the panel",
+     * not "the work was not verified" (SEC-128).
+     *
+     * `verifyWork` resolves ONLY when a verdict exists. When fewer than three of the
+     * five models answer, the endpoint answers 503 with `panelUnavailable: true` and
+     * carries NO decision and NO confidence, so `request` throws — deliberately, and
+     * that is the whole repair: the previous behaviour was a 200 carrying
+     * `decision: "NO", confidence: 65`, which every consumer rendered as a rejection
+     * of the submitted work. An outage is not a verdict, and a retry is the right
+     * next move rather than a resubmission with "stronger" evidence.
+     *
+     * A thrown 500 from the same endpoint is NOT this: it reports `false` here,
+     * because "the models did not answer" is a claim about the panel and a crash is
+     * not evidence for it.
+     */
+    static isPanelUnavailable(err) {
+        const body = err?.body;
+        return typeof body === "object" && body !== null && body.panelUnavailable === true;
     }
     /**
      * Submit a proof and wait for AI verification to complete — combines
      * submitProof + polling into a single call. Times out after ~100s and
      * returns { pending: true, proofId } so you can poll manually.
+     *
+     * Returns early, with `milestoneClosed: true`, when the milestone is already
+     * terminal — including when no verdict was recorded, which on a closed milestone
+     * will never change. Check `milestoneClosed` before `decision`: a `"YES"` on a
+     * closed, `EXPIRED` milestone is the panel's opinion of the proof and moved no funds.
+     *
+     * Also returns early, with `approvedWithoutThisVerdict: true`, when the milestone is
+     * VERIFIED or COMPLETED without a YES from this proof (another proof won it, or the
+     * funder approved it in review): `decision` is then `"NO"` or `null`, and the
+     * milestone's outcome is NOT this proof's.
+     *
+     * A proof parked for a human (no verdict, milestone at `PENDING_REVIEW`) returns
+     * `{ pending: true, proofId, awaitingHumanReview: true }` on the first poll instead of
+     * after the full timeout: no poll will change it, the funder decides.
+     *
+     * Neither early return is taken while the server reports `running: true` on a
+     * VERIFIED or PENDING_REVIEW milestone: this proof's panel is still running and can
+     * still decide the row, so the loop keeps polling. A server that predates `running`
+     * cannot say so, and there the early returns stay as described.
      */
     async watchVerification(input) {
         const { proofId } = await this.submitProof(input);
-        const MAX_WAIT_MS = 100_000;
-        const POLL_MS = 5_000;
+        return this.waitForProof(proofId);
+    }
+    /**
+     * Wait for the verification of a proof that is already submitted — the call to
+     * make after `submitProof`, and after `verify()` threw a 409 VERIFICATION_IN_PROGRESS
+     * with `phase: "running"` (T01-7). Same results as `watchVerification`, which is
+     * this plus the upload.
+     *
+     * Stops early, by throwing, when waiting cannot help: 401 / 403 (the key or the
+     * account does not change by waiting) and 404 (permanent — upload answers only
+     * after the proof exists and proof-status reads the primary database, so a 404
+     * means deleted or erased). Returns `{ pending: true, interrupted: true }` when the
+     * run that held the proof died (`claimPhase: "orphaned"`). On 429 / 503 it waits at
+     * least the server's Retry-After, never past `timeoutMs`; network errors and other
+     * 5xx are transient and it polls again.
+     */
+    async waitForProof(proofId, options = {}) {
+        const MAX_WAIT_MS = options.timeoutMs ?? 100_000;
+        const POLL_MS = options.intervalMs ?? 5_000;
         const started = Date.now();
+        let waitMs = POLL_MS;
         while (Date.now() - started < MAX_WAIT_MS) {
-            await new Promise((r) => setTimeout(r, POLL_MS));
-            const status = await this.getProofStatus(proofId).catch(() => null);
-            if (status && !status.pending) {
+            await new Promise((r) => setTimeout(r, waitMs));
+            waitMs = POLL_MS;
+            let status = null;
+            try {
+                status = await this.getProofStatus(proofId);
+            }
+            catch (e) {
+                const err = e;
+                if (err.status === 401 || err.status === 403 || err.status === 404)
+                    throw e;
+                if ((err.status === 429 || err.status === 503) && typeof err.retryAfterSeconds === "number") {
+                    waitMs = Math.min(Math.max(POLL_MS, err.retryAfterSeconds * 1000), Math.max(0, MAX_WAIT_MS - (Date.now() - started)));
+                }
+                continue;
+            }
+            // A closed milestone ends the wait whether or not a verdict landed: an outage
+            // that lost to EXPIRED leaves `pending: true` for good, and the loop used to burn
+            // its full timeout on it. `milestoneStatus` is the fallback for a server that
+            // predates `milestoneClosed`.
+            const closed = status ? closedMilestoneStatus(status) : null;
+            // Approved or paid without a YES from this proof: nothing is left for it to
+            // decide, whether or not it has a verdict of its own.
+            const elsewhere = status ? approvedWithoutThisVerdict(status) : false;
+            if (status && (!status.pending || closed || elsewhere)) {
                 return {
                     pending: false,
-                    decision: (status.decision ?? "NO"),
+                    // `?? "NO"` before: an ABSENT decision was reported as a rejection, the one
+                    // direction that costs the builder their reputation. `null` says "the route
+                    // reported none", which is the truth and forces the caller to look at
+                    // `milestoneStatus`.
+                    decision: status.decision ?? null,
                     confidence: status.confidence ?? null,
+                    // Both forwarded, because `decision` answers a question about the PROOF and
+                    // these answer the one about the MILESTONE. Dropping them is how a scheduled,
+                    // contestable, unpaid approval reached a caller as a completed payout
+                    // (SEC-058, at the fourth door of three that were fixed).
+                    milestoneStatus: status.milestoneStatus,
+                    releaseHoldUntil: status.releaseHoldUntil ?? null,
+                    milestoneClosed: closed !== null,
+                    terminalStatus: closed,
+                    terminalReason: closed ? (status.terminalReason ?? null) : null,
+                    approvedWithoutThisVerdict: elsewhere,
                     reasoning: status.reasoning,
                 };
             }
+            // Parked for a human: `pending` stays true on this path until the funder decides,
+            // so waiting out the loop only delayed the same answer by 100 s. Same test as
+            // `parkedForHuman` at both MCP surfaces.
+            if (status && parkedForHuman(status)) {
+                return { pending: true, proofId, awaitingHumanReview: true };
+            }
+            // The run that held this proof died: nothing is running to wait for. verify()
+            // can restart it once its claim is an hour old; submitting again always works.
+            if (status && status.claimPhase === "orphaned") {
+                return { pending: true, proofId, interrupted: true };
+            }
         }
         return { pending: true, proofId };
     }
     // ─── Agent marketplace ──────────────────────────────────────────────────────
-    /** Look up any agent's on-chain reputation by XRPL wallet address. No auth required. */
+    /**
+     * Look up any agent's on-chain reputation by EVM wallet address. No auth required.
+     *
+     * `summary` reaches you RAW, and so do `name` and `skills` from `discoverAgents`
+     * below. The route deliberately does not mark them (the browser profile page renders
+     * the same fields) and both MCP servers do mark them — so this SDK is a machine
+     * boundary that does not, exactly like `verify()`.
+     *
+     * The DECISION is the same and so is its reason: a library cannot know whether its
+     * return value ends in a model's context or on a page, where a marker is noise.
+     * What was missing here was the REASON, stated at `verify()` and nowhere
+     * else, which made this door look like an oversight rather than a choice (SEC-120).
+     * If you feed these fields to a model, treat them as data and not as instructions.
+     */
     async getReputation(walletAddress) {
         return this.request("GET", `/api/agent/reputation/${encodeURIComponent(walletAddress)}`);
     }