cascrow-sdk 0.2.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.7.0 — unreleased (owner publishes)
+
+- **`joinContract()` returns `{ contractId, status, activated }`**, and the new export `joinedLine(result)` renders it: `activated: true` — a $0 contract, active now; `false` — wait for the payer's MilestoneEscrowV3 offer and accept it with your own key.
+- **`reviewContract()` returns `{ status }`** — the `txHash` in its type never existed: a review completes a verification-only milestone and moves no money.
+- **New stream action `NOT_COMPLETABLE_WITHOUT_ESCROW`** (with `error` and `remedy`): the panel approved a milestone that carries an amount without a MilestoneEscrowV3 escrow, so nothing completed it and no money moved — contact support, do not resubmit. `mcpSubmit` throws the server's 409 with that code and its hint; `watchVerification` / `waitForProof` return on the first poll with `notCompletableWithoutEscrow: true`. An exhaustive `switch` over `action` will ask for the new arm — that is intended.
+- **Breaking: `releaseHoldUntil` is removed** from `VerificationResult`, `ProofStatus`, `WatchResult` and the `mcpSubmit` result, with the v2 release window it reported.
+- New hint for `RELEASE_HOLD_REMOVED` (the server refuses `releaseHoldHours` on contract creation).
+- **Breaking: `fundMilestone()` is removed** (cascrow Phase 6 — the v2 RLUSD escrow is gone). A contract whose milestones have `amountUSD` 0 is active by itself once the builder has joined; there is nothing to fund. A milestone with an amount above 0 is a MilestoneEscrowV3 escrow in native XRP: the payer offers terms with `client.v3.offer`, the builder accepts with its own key, and the payer funds it with one transaction from its own machine — `npx cascrow-signer@0.1.0 fund --milestone <id>`. The SDK signs nothing.
+- `ReputationResult.stats.totalReleasedUsd` (the value released over every escrow version) and `totalXrpReleased` (native XRP released by MilestoneEscrowV3 escrows). `totalRlusdReleased` is deprecated — the retired v2 escrow only, same value — and goes at the next major.
+- Doc comments no longer say "funds released" for a COMPLETED milestone: a verification-only milestone held no money, and a MilestoneEscrowV3 milestone is paid out on chain by its parties.
+
+## 0.6.0 — unreleased (owner publishes)
+
+- `client.v3.offer / acceptance / submitAcceptance / prepare / reportTx / attestation / claims` — the MilestoneEscrowV3 remote calls. The SDK signs nothing and has no keystore or file access; signing is the separate, pinned `cascrow-signer` package (`CASCROW_SIGNER_PIN`). `reportTx` accepts a transaction hash only.
+- `V3Signer` is deliberately NOT part of the SDK: the one implementation of the signer's checks lives in `cascrow-signer` (import its API directly, `import { createSigner } from "cascrow-signer"`), so a browser bundle of this SDK can never pull in a keystore.
+- The verification stream's `action` may be `V3_RECOMMENDATION` (a MilestoneEscrowV3 verdict — a recommendation that moves no money); `mcpSubmit` returns `verdict: "v3_recommendation"` with `decision` and `manifestHash`. Errors with a V3 code carry `.hint` (who can act, and how), also appended to the message.
+
+## 0.5.0 — unreleased (owner publishes)
+
+- **Breaking: `escrowFund()` is removed.** It sent the agent's EVM private key to cascrow, which signed the deposit server-side; cascrow no longer accepts, stores or signs with anyone's key. Fund a v2 escrow by signing locally: `GET /api/agent/escrow-prepare` returns the two unsigned transactions, you sign and broadcast them with your own wallet, then `POST /api/escrow/sync`. Funding a MilestoneEscrowV3 contract from an API client is not available yet. **If you ever passed a private key to `escrowFund`, treat that key as exposed and move its funds to a new wallet.**
+- `register()` returns `wallet: null` and `walletNote`: cascrow no longer generates a wallet at registration. Link your own with `GET /api/user/wallet/challenge` → sign → `POST /api/user/wallet`.
+
+## 0.4.0 — 2026-09-25
+
+- `waitForProof(proofId, { timeoutMs, intervalMs })` — wait for a proof already submitted. Upload starts verification by itself, so this, not `verify()`, is the call after `submitProof`. Stops by throwing on 401 / 403 / 404 (waiting does not change them), returns `{ pending: true, interrupted: true }` when the run died, and honours `Retry-After` on 429 / 503.
+- `watchVerification` is `submitProof` + `waitForProof`, with the same stop rules (it used to swallow every error and poll out its full timeout).
+- Errors carry `.code` (the API's stable code, or `UPSTREAM_NON_JSON` for a non-JSON answer such as a platform error page) and `.retryAfterSeconds`; a 409 `VERIFICATION_IN_PROGRESS` also carries `.phase`, `.watchUrl` and `.expectedDoneInSeconds`.
+- `submitProof` has a deadline (120 s); before, a stalled upload never returned.
+- `MilestoneInput` takes `verificationCriteria` and `verificationChecklist` — the bar the AI panel judges against — normalised client-side (a bad item is refused with its index before any request).
+- `getProofStatus` types `claimPhase` and `expectedDoneInSeconds`.

package/README.md

@@ -1,6 +1,6 @@
 # cascrow-sdk
 
-TypeScript client for [Cascrow](https://cascrow.com) — agentic escrow and verification on the XRP Ledger.
+TypeScript client for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy: AI verification, on-chain reputation, and — for paid work — the remote half of a non-custodial milestone escrow (MilestoneEscrowV3, native XRP).
 
 For AI agents connecting through Claude, Cursor, or Codex, use [`cascrow-mcp`](https://www.npmjs.com/package/cascrow-mcp) instead — it's the same API, exposed as MCP tools. This package is for plain application code (backends, scripts, other platforms) that want to call Cascrow directly without going through an LLM tool call.
 
@@ -18,7 +18,19 @@ import { CascrowClient } from "cascrow-sdk";
 const client = new CascrowClient({ apiKey: "csk_..." });
 
 const { contractId, inviteLink } = await client.createContract({
-  milestones: [{ title: "Ship the landing page", amountUSD: 500, daysUntilDeadline: 7 }],
+  milestones: [
+    {
+      title: "Ship the landing page", // printed on the certificate — keep it short
+      // 0 / absent = verification only, active once the builder joins. Above 0 = a
+      // MilestoneEscrowV3 escrow in native XRP (see "Agent-to-agent flow" below).
+      amountUSD: 0,
+      daysUntilDeadline: 7,
+      // The bar the AI panel judges the proof against:
+      verificationCriteria: "Responsive down to 320px, LCP under 2 s on mobile, CTA links to /signup",
+      verificationChecklist: [{ title: "Mobile layout", severity: "HIGH" }, { title: "Signup CTA" }],
+    },
+  ],
+  agentReviewMode: "MANUAL", // what happens when the panel is unsure (60–85 % confidence)
 });
 
 console.log(`Contract created: ${contractId}, invite: ${inviteLink}`);
@@ -28,7 +40,7 @@ Get an API key via `client.register({ email, password })` (no CAPTCHA, no email
 
 ## Sandbox
 
-Escrow currently settles on the XRPL EVM Testnet (chain 1449000) using MockRLUSD, a freely mintable test token — every `amountUSD` you see in the examples below moves test funds, not real money. AI verification is real (live calls to the 5-model panel), and NFT certificates are issued on XRP Ledger Mainnet. See the [Guide](https://cascrow.com/guide) for wallet setup and getting test RLUSD from the faucet.
+MilestoneEscrowV3 runs on the XRPL EVM Sidechain **testnet** (chain 1449000) with native test XRP from the faucet — an `amountUSD` above 0 in the examples below moves test XRP, not real money. The escrow is a smart contract with no platform role: cascrow holds no key, never signs and is never the arbiter. AI verification is real (live calls to the 5-model panel), and NFT certificates are issued on XRP Ledger Mainnet. See the [Guide](https://cascrow.com/guide) for wallet setup and test XRP.
 
 ## Verification without escrow
 
@@ -47,6 +59,8 @@ console.log(result.decision, result.confidence, result.reportUrl);
 
 Verification is rate-limited to 3 per IP per 24h. Passing an `apiKey` attributes each result to your account (so it shows up in your usage) but does not currently raise that allowance — account-based verification credits are not yet purchasable.
 
+Passing an `apiKey` also anchors the verdict on the XRP Ledger mainnet — a content-free commitment hash written into an on-chain memo, independently recomputable from the report (see `GET /api/verify/result/{hash}` in the [API reference](https://cascrow.com/api-docs)). Anonymous calls are never anchored. `result.id`, `result.reportUrl`, and the anchor fields you'd poll for (`anchorHash`, `xrplTxHash`, `anchoredAt`) live at that report URL, not in the `verifyWork()` response — anchoring happens asynchronously after the call returns.
+
 ## Agent-to-agent flow
 
 ```ts
@@ -56,14 +70,26 @@ const builder = new CascrowClient({ apiKey: builderKey });
 const { contractId, inviteLink } = await requester.createContract({
   milestones: [{ title: "Build the API", amountUSD: 1000 }],
 });
-await requester.escrowFund({ contractId, agentPrivateKey: requesterEvmKey, amountUSD: 1000 }); // testnet MockRLUSD, not real funds — see Sandbox above
-
 await builder.joinContract(inviteLink!);
-const { proofId } = await builder.submitProof({ milestoneId, content: "Done — see PR #12, all tests pass." });
-const result = await builder.verify(proofId);
 
-if (result.action === "VERIFIED") {
-  console.log("Funds released automatically:", result.txHash);
+// MilestoneEscrowV3 (native XRP, testnet): the payer offers terms, the builder accepts with
+// its own key, the payer funds with ONE transaction from its own machine. The SDK signs
+// nothing — signing is the separate, pinned local signer (npx cascrow-signer@0.1.0):
+await requester.v3.offer({ milestoneId, reviewPeriodSec: 72 * 3600, watcherDeclared: false });
+//   builder:   npx cascrow-signer@0.1.0 accept --milestone <milestoneId>
+//   requester: npx cascrow-signer@0.1.0 fund --milestone <milestoneId>
+// cascrow never accepts, creates, stores or signs with a private key (escrowFund(), which
+// took one, was removed in 0.5.0 — if you ever passed a key to it, treat that key as exposed).
+// A contract with amountUSD 0 needs none of this: it is active once the builder has joined.
+
+const { proofId } = await builder.submitProof({ milestoneId, content: "Done — see PR #12, all tests pass." });
+// Upload starts verification by itself — wait for it, don't start it again.
+const result = await builder.waitForProof(proofId);
+// For a MilestoneEscrowV3 milestone the AI verdict is a signed, non-binding recommendation:
+// the builder claims on chain (npx cascrow-signer@0.1.0 submit-claim --milestone <id> --proof-hash <manifestHash>),
+// the payer releases or objects before the objection deadline.
+if (!result.pending && result.milestoneStatus === "COMPLETED") {
+  console.log("Milestone complete.");
 }
 ```
 
@@ -79,14 +105,16 @@ if (result.action === "VERIFIED") {
 | `getContract` | `GET /api/contracts/{id}` |
 | `listMyContracts` | `GET /api/agent/my-contracts` |
 | `joinContract` | `POST /api/contracts/join` |
-| `reviewContract` | `POST /api/contracts/review` |
+| `reviewContract` | `POST /api/contracts/review` — pass `milestoneId` when more than one milestone is pending review |
+| `reviewQueue` | `GET /api/agent/review-queue` — the contracts on which you, as funder, still owe a verdict. The pull behind the `manual_review.required` webhook: verification-only ($0) contracts; an undecided milestone is completed automatically after 48 h under review mode `MANUAL_AUTO` or `AUTO`, 14 days otherwise. Moves no money |
+| `v3Claims` | `GET /api/agent/v3-claims` — as payer of a MilestoneEscrowV3 escrow, the claims that release it unless your own wallet calls `object(escrowId)` before `objectionDeadline`. Throws `V3_INDEX_STALE` (503) while the index is not current: read the chain then |
+| `v3.offer` / `v3.acceptance` / `v3.submitAcceptance` / `v3.prepare` / `v3.reportTx` / `v3.attestation` / `v3.claims` | MilestoneEscrowV3, remote half. `prepare` returns an UNSIGNED transaction — rebuild `data` and check `to`/`chainId` yourself before signing; `reportTx` takes a hash only. This SDK signs nothing: use the separate local signer, pinned — `npx cascrow-signer@0.1.0` (or `import { createSigner } from "cascrow-signer"` in Node). There is deliberately no `V3Signer` in this package. |
 | `checkInvites` | `GET /api/agent/pending-invites` |
 | `handoff` | `POST /api/agent/handoff` |
-| `fundMilestone` | `POST /api/agent/fund-milestone` |
-| `escrowFund` | `POST /api/agent/escrow-fund` |
 | `submitProof` | `POST /api/proof/upload` |
 | `getProofStatus` | `GET /api/agent/proof-status/{proofId}` |
-| `verify` | `POST /api/verify` (streamed) |
+| `waitForProof` | poll `getProofStatus` until the proof settles — the call to make after `submitProof` |
+| `verify` | `POST /api/verify` (streamed) — start or re-run a verification by hand |
 | `mcpSubmit` | `POST /api/mcp/submit` |
 | `verifyWork` | `POST /api/verify/standalone` |
 | `watchVerification` | `submitProof` + poll |
@@ -96,7 +124,9 @@ if (result.action === "VERIFIED") {
 
 ## Errors
 
-Failed requests throw an `Error` with `.status` (HTTP status code) and `.body` (parsed JSON error response) attached.
+Failed requests throw an `Error` with `.status` (HTTP status code), `.body` (parsed JSON error response), `.code` (the stable error code — branch on this, not on the message; `UPSTREAM_NON_JSON` when the server answered with something that is not JSON) and `.retryAfterSeconds` (how long the server asked you to wait) attached.
+
+`verify(proofId)` on a proof whose verification is already running (usually the one upload started) throws `code: "VERIFICATION_IN_PROGRESS"` with `phase: "running"` — call `waitForProof(proofId)`. Its `retryAfterSeconds` is when an abandoned run could be taken over (about an hour), not a backoff.
 
 ```ts
 try {

package/dist/client.d.ts

@@ -1,20 +1,114 @@
-import type { Contract, CreateContractInput, CreateContractResult, DiscoverAgentsResult, MyContractSummary, RegisterInput, RegisterResult, ReputationResult, VerificationResult, VerifyWorkInput, VerifyWorkResult } from "./types.js";
+import type { Contract, CreateContractInput, CreateContractResult, DiscoverAgentsResult, MyContractSummary, ReviewQueueResult, V3ClaimsResult, RegisterInput, RegisterResult, ReputationResult, VerificationResult, VerifyWorkInput, VerifyWorkResult } from "./types.js";
+import type { V3AcceptanceData, V3Action, V3Attestation, V3OfferInput, V3PreparedTx } from "./v3.js";
 export interface CascrowClientOptions {
     /** API key starting with csk_. Omit only for endpoints that support anonymous use (register, getReputation, verifyWork). */
     apiKey?: string;
     /** Override the API base URL. Defaults to https://cascrow.com. */
     baseUrl?: string;
 }
-/**
- * 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.
- */
+/** What `watchVerification` and `waitForProof` resolve to. */
+export type WatchResult = {
+    pending: false;
+    /** The verdict on this proof, or `null` when the route reported none. */
+    decision: "YES" | "NO" | null;
+    confidence: number | null;
+    /** `"COMPLETED"`: the milestone is complete (see `escrowVersion` for whether money was held). */
+    milestoneStatus?: string;
+    /**
+     * The milestone carries an amount without a MilestoneEscrowV3 escrow, so no
+     * verdict can complete it (cascrow has a case open; contact support, do not
+     * resubmit). Read it BEFORE `decision`: a YES here is not done.
+     */
+    notCompletableWithoutEscrow: boolean;
+    /**
+     * The milestone is TERMINAL (`terminalStatus`: EXPIRED or COMPLETED) and this
+     * proof's verdict cannot move it. Read this BEFORE `decision`.
+     */
+    milestoneClosed: boolean;
+    terminalStatus: string | null;
+    /** See `getProofStatus` — `"RELEASED_ON_CHAIN"` means the builder WAS paid on-chain. */
+    terminalReason: string | null;
+    /**
+     * The milestone is VERIFIED or COMPLETED, but not on a YES from this proof —
+     * another proof won it, or the funder approved it in review. `decision` is
+     * this proof's `"NO"` or `null`; the payout, if any, is not this proof's.
+     */
+    approvedWithoutThisVerdict: boolean;
+    /**
+     * `3` for a MilestoneEscrowV3 milestone, `2` otherwise (absent on an older server).
+     * On `3` the verdict is a RECOMMENDATION and moves no money: read
+     * `submissionVerdict` / `claimReady`, and claim on chain with `manifestHash`
+     * (`npx cascrow-signer submit-claim --proof-hash <manifestHash>`).
+     */
+    escrowVersion?: 2 | 3;
+    /** V3 only: the sealed submission this proof belongs to (one evidence request = one submission). */
+    submissionId?: string | null;
+    /** V3 only: the submission's manifest hash — the proofHash a claim names on chain. */
+    manifestHash?: string | null;
+    /** V3 only: the SUBMISSION's write-once verdict — YES only when every proof in it has a definite yes. */
+    submissionVerdict?: "YES" | "NO" | "PENDING" | null;
+    /** V3 only: `submissionVerdict === "YES"` — the claim cascrow recommends. */
+    claimReady?: boolean;
+    reasoning?: string;
+} | {
+    pending: true;
+    proofId: string;
+    /**
+     * Set when the panel produced no verdict and the milestone is at
+     * `PENDING_REVIEW`: a human decides, and polling will not change that.
+     */
+    awaitingHumanReview?: true;
+    /** The run that held this proof died; nothing is running. Submitting the proof again always works; `verify()` can restart it once its claim is an hour old. */
+    interrupted?: true;
+};
 export declare class CascrowClient {
     private readonly apiKey?;
     private readonly baseUrl;
     constructor(options?: CascrowClientOptions);
+    /**
+     * MilestoneEscrowV3 — the remote half. cascrow prepares and reads; YOU sign and
+     * send with your own key. This SDK never signs: use the separate, pinned
+     * `cascrow-signer` package (`npx cascrow-signer@<pin> …`, see CASCROW_SIGNER_PIN),
+     * which checks every prepared transaction against its own chain and contract.
+     */
+    readonly v3: {
+        /** As PAYER: offer terms for a milestone. 409 `OFFER_EXISTS` names the open offer. */
+        offer: (input: V3OfferInput) => Promise<Record<string, unknown>>;
+        /** As PAYEE: the frozen offer to check and sign (EIP-712). 409 `V3_NOT_OFFERED` before the payer offered. */
+        acceptance: (milestoneId: string) => Promise<V3AcceptanceData>;
+        /** As PAYEE: hand over the acceptance signature — binding until acceptBy. */
+        submitAcceptance: (offerId: string, signature: string) => Promise<{
+            escrowId: string;
+            acceptBy: string;
+        }>;
+        /** An UNSIGNED transaction. Rebuild `data` and check `to`/`chainId` yourself before signing. */
+        prepare: (milestoneId: string, action: V3Action, extra?: {
+            proofHash?: string;
+            reasonHash?: string;
+            newDeadline?: string | number;
+        }) => Promise<V3PreparedTx>;
+        /** After YOU broadcast: the hash as a hint to re-read the chain. Only a hash — never a signed transaction. */
+        reportTx: (milestoneId: string, txHash: string) => Promise<Record<string, unknown>>;
+        /** cascrow's signed, NON-BINDING AI recommendation for a claim. 409 `ATTESTATION_PENDING` while the panel runs. */
+        attestation: (escrowId: string, claimIndex: number) => Promise<V3Attestation>;
+        /** As PAYER: open claims you can still object to (same as `v3Claims()`). */
+        claims: () => Promise<V3ClaimsResult>;
+    };
     private authHeaders;
+    /**
+     * 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).
+     */
     private request;
     /** Self-register an agent account. No CAPTCHA, no email verification. Returns an API key — save it, it is shown only once. */
     register(input: RegisterInput): Promise<RegisterResult>;
@@ -33,15 +127,80 @@ export declare class CascrowClient {
         contracts: MyContractSummary[];
         total: number;
     }>;
-    /** Join an existing contract as the Builder using an invite code. */
+    /**
+     * Join an existing contract as the Builder using an invite code.
+     *
+     * `activated: true` — a $0 verification contract: it is active (`status: "FUNDED"`)
+     * and you can submit proof now. `activated: false` — the milestones carry an amount:
+     * wait for the payer's MilestoneEscrowV3 offer and accept it with your own wallet key
+     * (`npx cascrow-signer@0.1.0 accept --milestone <id>`, or `client.v3.acceptance` +
+     * `client.v3.submitAcceptance`); proof is accepted once the payer has funded it.
+     * `joinedLine(result)` renders that as one sentence.
+     */
     joinContract(inviteCode: string): Promise<{
         contractId: string;
+        status: string;
+        activated: boolean;
     }>;
-    /** Approve or reject a borderline (PENDING_REVIEW) contract. Only valid when agentReviewMode is MANUAL or MANUAL_AUTO. */
-    reviewContract(contractId: string, decision: "APPROVE" | "REJECT"): Promise<{
+    /**
+     * 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.
+     */
+    reviewContract(contractId: string, decision: "APPROVE" | "REJECT", milestoneId?: string): Promise<{
+        /**
+         * The contract's status after the decision. APPROVE completes a verification-only
+         * ($0) milestone — no money moves; there is no transaction. A MilestoneEscrowV3
+         * milestone is refused here: its payer releases or objects on chain.
+         */
         status: string;
-        txHash: string | null;
     }>;
+    /**
+     * 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 completes the milestone after 48 h (agent contracts in MANUAL_AUTO or
+     * AUTO) or 14 days (every other contract) — verification-only contracts, so
+     * no money moves, and nobody decided it. 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".
+     */
+    reviewQueue(): Promise<ReviewQueueResult>;
+    /**
+     * As the PAYER of a MilestoneEscrowV3 escrow: the claims that release it to the
+     * builder unless your own wallet calls `object(escrowId)` before
+     * `objectionDeadline` — the pull behind the `claim.submitted` webhook. cascrow
+     * cannot object for you. Throws with code `V3_INDEX_STALE` (503) while the index
+     * is not current; read the chain directly then.
+     */
+    v3Claims(): Promise<V3ClaimsResult>;
     /** Check for pending contract invites sent to this agent. */
     checkInvites(): Promise<{
         invites: unknown[];
@@ -55,26 +214,11 @@ export declare class CascrowClient {
     }): Promise<{
         handoffId: string;
     }>;
-    /** Fund (activate) a milestone via MetaMask/browser flow so it can receive proof. */
-    fundMilestone(contractId: string, milestoneId?: string): Promise<{
-        milestoneId: string;
-        contractId: string;
-        status: string;
-    }>;
-    /** Fund a milestone with real on-chain RLUSD escrow using the agent's own EVM private key. */
-    escrowFund(input: {
-        contractId: string;
-        agentPrivateKey: string;
-        amountUSD: number;
-        milestoneId?: string;
-    }): Promise<{
-        milestoneId: string;
-        contractId: string;
-        txHash: string;
-        amountUSD: number;
-        status: string;
-    }>;
-    /** 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.
+     */
     submitProof(input: {
         milestoneId: string;
         content: string;
@@ -85,11 +229,73 @@ export declare class CascrowClient {
     /** Check the AI verification result for a submitted proof (poll after submitProof). */
     getProofStatus(proofId: string): Promise<{
         pending?: boolean;
+        /**
+         * `true` while the verification panel is running on this proof right now. A running
+         * proof is never final, whatever `milestoneStatus` says: a `PENDING_REVIEW` a sibling
+         * proof set, or a `VERIFIED` that a failed release or a review hands back, can still
+         * be decided by it. `pending` without `running` is the other cause: not claimed yet,
+         * or a panel that produced no verdict. Absent on a server that predates the field.
+         */
+        running?: boolean;
+        /**
+         * `"running"` — a live run holds the proof (wait for it); `"orphaned"` — the run
+         * died, nothing is running; `"unclaimed"` / `"decided"`. Absent on an older server.
+         */
+        claimPhase?: "unclaimed" | "running" | "orphaned" | "decided";
+        /** While `claimPhase` is `"running"`: roughly when the verdict is due. */
+        expectedDoneInSeconds?: number;
+        /** The verdict on THIS PROOF. It does not say whether the money moved. */
         decision?: "YES" | "NO";
         confidence?: number | null;
         contractStatus?: string;
         milestoneTitle?: string;
+        /**
+         * The MILESTONE's state, which is the question most callers are actually asking.
+         * `"COMPLETED"`: the milestone is complete — a verification-only milestone held no
+         * money; a MilestoneEscrowV3 milestone was paid out on chain by its parties.
+         */
         milestoneStatus?: string;
+        /**
+         * `true`: this proof's milestone carries an amount without a MilestoneEscrowV3
+         * escrow, so no verdict can complete it — the verdict doors answer 409
+         * `NOT_COMPLETABLE_WITHOUT_ESCROW` and cascrow has a case open. Stop polling,
+         * contact support, do not resubmit. (Replaces `releaseHoldUntil`, which reported
+         * the removed v2 release window.)
+         */
+        notCompletableWithoutEscrow?: boolean;
+        /**
+         * `true` when the milestone (or, for a legacy contract-level proof, the contract)
+         * is TERMINAL — `EXPIRED` or `COMPLETED` — so no verdict on this proof can move it
+         * any more. Check it BEFORE `decision` and `pending`: a milestone the funder
+         * cancelled, or the deadline cron closed, while the panel ran stays `EXPIRED` with
+         * this proof's `decision` still recorded (YES or NO) — or with `pending: true` for
+         * good, when the panel could not reach a verdict. A YES here moved no funds.
+         */
+        milestoneClosed?: boolean;
+        /** `"EXPIRED"` or `"COMPLETED"` when `milestoneClosed`, else null. */
+        terminalStatus?: string | null;
+        /**
+         * Why an `EXPIRED` milestone ended, when recorded. `"RELEASED_ON_CHAIN"` means the
+         * chain shows the builder WAS paid — just not by this verification; the other
+         * values (`DEADLINE_EXPIRED`, `CANCELLED_AFTER_APPROVAL`, …) mean the funder was
+         * refunded or no escrow existed. Null when not recorded.
+         */
+        terminalReason?: string | null;
+        /**
+         * `3` for a MilestoneEscrowV3 milestone, `2` otherwise (absent on an older server).
+         * On `3` the verdict is a RECOMMENDATION and moves no money: read
+         * `submissionVerdict` / `claimReady`, and claim on chain with `manifestHash`
+         * (`npx cascrow-signer submit-claim --proof-hash <manifestHash>`).
+         */
+        escrowVersion?: 2 | 3;
+        /** V3 only: the sealed submission this proof belongs to (one evidence request = one submission). */
+        submissionId?: string | null;
+        /** V3 only: the submission's manifest hash — the proofHash a claim names on chain. */
+        manifestHash?: string | null;
+        /** V3 only: the SUBMISSION's write-once verdict — YES only when every proof in it has a definite yes. */
+        submissionVerdict?: "YES" | "NO" | "PENDING" | null;
+        /** V3 only: `submissionVerdict === "YES"` — the claim cascrow recommends. */
+        claimReady?: boolean;
         reasoning?: string;
     }>;
     /**
@@ -107,7 +313,9 @@ export declare class CascrowClient {
     }): Promise<VerificationResult>;
     /**
      * Submit proof and get an immediate verdict in one call — runs the full
-     * 5-model pipeline and, on approval, releases funds and mints the NFT.
+     * 5-model pipeline. On approval a verification-only milestone completes and its NFT
+     * is minted; for a MilestoneEscrowV3 milestone the verdict is a recommendation
+     * (`verdict: "v3_recommendation"`) and moves no money.
      */
     mcpSubmit(input: {
         contractId: string;
@@ -120,11 +328,50 @@ export declare class CascrowClient {
             customFields?: Record<string, unknown>;
         };
     }): Promise<{
-        verdict: "approved" | "rejected" | "pending_review";
-        confidence: number;
+        /**
+         * SEC-059's shape at a fourth consumer, found by deriving the set of readers from
+         * what the route SENDS rather than from the two MCP servers a finding compared.
+         *
+         * The route has two 200 responses that carry NO `verdict` key at all, and this
+         * union claimed three values:
+         *
+         *  - `decided_elsewhere` — the milestone was settled by a concurrent request or by
+         *    the investor's review while this proof was being verified. The route answers
+         *    `{ ok: true, decided: "elsewhere" }`; `verdict` was simply `undefined` here,
+         *    outside its own declared type, and a consumer treating it as falsy read it as
+         *    a rejection.
+         *  - `panel_unavailable` — fewer than three of the five models answered. OUR
+         *    outage, not a judgement of the work, and resubmitting will not help.
+         *
+         * An approved milestone that nothing can complete (an amount without a
+         * MilestoneEscrowV3 escrow) is not a 200: the route answers 409
+         * `NOT_COMPLETABLE_WITHOUT_ESCROW`, thrown as a `CascrowApiError` with its hint.
+         */
+        /**
+         * `v3_recommendation`: the milestone is a MilestoneEscrowV3 escrow and the panel's
+         * verdict is a RECOMMENDATION — it moves no money. `decision` carries it; the payee
+         * claims on chain with the same evidence (`manifestHash`), the payer releases or objects.
+         */
+        verdict: "approved" | "rejected" | "pending_review" | "decided_elsewhere" | "panel_unavailable" | "v3_recommendation";
+        /** With `v3_recommendation`: the panel's YES/NO on this one file — NOT the claim verdict; read `submissionVerdict`. */
+        decision?: string | null;
+        /** With `v3_recommendation`: the sealed submission's manifest hash (the claim's proofHash). */
+        manifestHash?: string | null;
+        /** With `v3_recommendation`: the submission's verdict — YES only when every file has a definite AI yes. */
+        submissionVerdict?: "YES" | "NO" | "PENDING";
+        /** With `v3_recommendation`: true exactly when `submissionVerdict` is YES. */
+        claimReady?: boolean;
+        confidence: number | null;
         reasoning: string;
         onChainUrl: string | null;
         proofId: string | null;
+        /**
+         * With `decided_elsewhere`: the TERMINAL status the milestone was already in
+         * (`"EXPIRED"`, `"COMPLETED"`) — it was closed before this submission could settle
+         * it, e.g. by the funder's cancel or the deadline, and resubmitting is pointless.
+         * Null when it was decided by the investor's review or a concurrent submission.
+         */
+        settledAs: string | null;
     }>;
     /**
      * Verify AI-generated work with no escrow contract — a task description
@@ -134,25 +381,84 @@ export declare class CascrowClient {
      * yet, so do not treat a key as a way to get more runs.
      */
     verifyWork(input: VerifyWorkInput): Promise<VerifyWorkResult>;
+    /**
+     * 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: unknown): boolean;
     /**
      * 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.
      */
     watchVerification(input: {
         milestoneId: string;
         content: string;
         filename?: string;
-    }): Promise<{
-        pending: false;
-        decision: "YES" | "NO";
-        confidence: number | null;
-        reasoning?: string;
-    } | {
-        pending: true;
-        proofId: string;
-    }>;
-    /** Look up any agent's on-chain reputation by EVM wallet address. No auth required. */
+    }): Promise<WatchResult>;
+    /**
+     * 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.
+     */
+    waitForProof(proofId: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<WatchResult>;
+    /**
+     * 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.
+     */
     getReputation(walletAddress: string): Promise<ReputationResult>;
     /** Search for discoverable Builder agents by skill tag and minimum success rate. */
     discoverAgents(options?: {