@reclaimprotocol/agent 0.1.35 → 0.1.36

package/lib/mcp/api/operations.gen.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:de7373741e35).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:96339e8dff91).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.

package/lib/mcp/tools/verification/proxy-callback-events.d.ts

@@ -13,7 +13,20 @@ type Recent = {
     httpStatus?: number;
     at: string;
 };
+/** A session whose oldest pending event the app has not accepted. */
+type Blocked = {
+    sessionId: string;
+    event: string;
+    eventId: string;
+    httpStatus?: number;
+    attempts: number;
+    lastError?: string;
+    /** When the first attempt failed, as an ISO timestamp. */
+    since: string;
+};
 export interface ProxyDeps extends CallbackDeps {
+    /** The clock, in milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
     /** Delivers an event to the app. Defaults to global `fetch`. */
     forwardFetch?: typeof globalThis.fetch;
     /** Waits between polls. Resolves early, without error, on abort. */
@@ -23,9 +36,13 @@ export interface ProxyDeps extends CallbackDeps {
 /**
  * Polls the org's pending pull events and POSTs each envelope to a local
  * route, like `stripe listen --forward-to`. 2xx responses are acknowledged;
- * anything else (redirects included) stays pending and is retried with
- * exponential backoff. After a failure the batch stops, so events reach the
- * app in order.
+ * anything else (redirects included) stays pending.
+ *
+ * Order holds per session. When an event fails, its session is held: its later
+ * events are not sent or acknowledged, and the failed event is retried with
+ * exponential backoff (2 s, 4 s, ... 30 s). Other sessions keep flowing at the
+ * normal poll rate. Held sessions appear in `status().blocked`, and clear when
+ * the app accepts the event.
  */
 declare class Forwarder {
     #private;
@@ -34,6 +51,7 @@ declare class Forwarder {
     constructor(client: ReclaimClient, listener: ListenerInfo, target: Target, deps: ProxyDeps);
     status(): {
         recent: Recent[];
+        blocked: Blocked[];
         lastError?: string | undefined;
         forwarding: boolean;
         target: string;

package/lib/mcp/tools/verification/proxy-callback-events.js

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Forwarder_instances, _Forwarder_client, _Forwarder_deps, _Forwarder_abort, _Forwarder_forwarded, _Forwarder_failed, _Forwarder_lastError, _Forwarder_recent, _Forwarder_unacked, _Forwarder_host, _Forwarder_running, _Forwarder_loop, _Forwarder_tick, _Forwarder_forward, _ForwarderRegistry_forwarders;
+var _Forwarder_instances, _Forwarder_client, _Forwarder_deps, _Forwarder_abort, _Forwarder_forwarded, _Forwarder_failed, _Forwarder_lastError, _Forwarder_recent, _Forwarder_unacked, _Forwarder_held, _Forwarder_host, _Forwarder_running, _Forwarder_loop, _Forwarder_tick, _Forwarder_hold, _Forwarder_forward, _ForwarderRegistry_forwarders;
 import { badRequest } from '@hapi/boom';
 import assert from 'node:assert';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -21,15 +21,25 @@ const POLL_MS = 2000;
 const MAX_BACKOFF_MS = 30000;
 const FORWARD_TIMEOUT_MS = 10000;
 const BATCH = 50;
+/**
+ * Pages read per poll. A page is `BATCH` events, so a poll can look past up to
+ * 500 pending events. That is enough to reach other sessions behind several
+ * held ones, and still bounds the work of one poll.
+ */
+const MAX_PAGES = 10;
 const RECENT = 10;
 /** Loopback addresses, in the order tried. Dev servers often bind only one. */
 const HOSTS = ['127.0.0.1', '[::1]'];
 /**
  * Polls the org's pending pull events and POSTs each envelope to a local
  * route, like `stripe listen --forward-to`. 2xx responses are acknowledged;
- * anything else (redirects included) stays pending and is retried with
- * exponential backoff. After a failure the batch stops, so events reach the
- * app in order.
+ * anything else (redirects included) stays pending.
+ *
+ * Order holds per session. When an event fails, its session is held: its later
+ * events are not sent or acknowledged, and the failed event is retried with
+ * exponential backoff (2 s, 4 s, ... 30 s). Other sessions keep flowing at the
+ * normal poll rate. Held sessions appear in `status().blocked`, and clear when
+ * the app accepts the event.
  */
 class Forwarder {
     constructor(client, listener, target, deps) {
@@ -44,7 +54,11 @@ class Forwarder {
         /** Delivered to the app but not yet acknowledged; never POSTed twice. */
         );
         /** Delivered to the app but not yet acknowledged; never POSTed twice. */
-        _Forwarder_unacked.set(this, new Set());
+        _Forwarder_unacked.set(this, new Set()
+        /** Held sessions by session id, with the time of their next attempt. */
+        );
+        /** Held sessions by session id, with the time of their next attempt. */
+        _Forwarder_held.set(this, new Map());
         _Forwarder_host.set(this, HOSTS[0]);
         _Forwarder_running.set(this, void 0);
         __classPrivateFieldSet(this, _Forwarder_client, client, "f");
@@ -62,6 +76,7 @@ class Forwarder {
             failed: __classPrivateFieldGet(this, _Forwarder_failed, "f"),
             ...(__classPrivateFieldGet(this, _Forwarder_lastError, "f") ? { lastError: __classPrivateFieldGet(this, _Forwarder_lastError, "f") } : {}),
             recent: [...__classPrivateFieldGet(this, _Forwarder_recent, "f")],
+            blocked: [...__classPrivateFieldGet(this, _Forwarder_held, "f").values()].map((h) => h.blocked),
         };
     }
     async stop() {
@@ -69,16 +84,16 @@ class Forwarder {
         await __classPrivateFieldGet(this, _Forwarder_running, "f");
     }
 }
-_Forwarder_client = new WeakMap(), _Forwarder_deps = new WeakMap(), _Forwarder_abort = new WeakMap(), _Forwarder_forwarded = new WeakMap(), _Forwarder_failed = new WeakMap(), _Forwarder_lastError = new WeakMap(), _Forwarder_recent = new WeakMap(), _Forwarder_unacked = new WeakMap(), _Forwarder_host = new WeakMap(), _Forwarder_running = new WeakMap(), _Forwarder_instances = new WeakSet(), _Forwarder_loop = async function _Forwarder_loop() {
+_Forwarder_client = new WeakMap(), _Forwarder_deps = new WeakMap(), _Forwarder_abort = new WeakMap(), _Forwarder_forwarded = new WeakMap(), _Forwarder_failed = new WeakMap(), _Forwarder_lastError = new WeakMap(), _Forwarder_recent = new WeakMap(), _Forwarder_unacked = new WeakMap(), _Forwarder_held = new WeakMap(), _Forwarder_host = new WeakMap(), _Forwarder_running = new WeakMap(), _Forwarder_instances = new WeakSet(), _Forwarder_loop = async function _Forwarder_loop() {
     const sleep = __classPrivateFieldGet(this, _Forwarder_deps, "f").sleep || sleepFor;
     const signal = __classPrivateFieldGet(this, _Forwarder_abort, "f").signal;
     let backoff = 0;
     while (!signal.aborted) {
         let wait = POLL_MS;
         try {
-            const { ok, count } = await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_tick).call(this);
-            backoff = ok ? 0 : nextBackoff(backoff);
-            wait = ok ? (count >= BATCH ? 0 : POLL_MS) : backoff;
+            const more = await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_tick).call(this);
+            backoff = 0;
+            wait = more ? 0 : POLL_MS;
         }
         catch (err) {
             __classPrivateFieldSet(this, _Forwarder_lastError, err instanceof Error ? err.message : String(err), "f");
@@ -90,37 +105,96 @@ _Forwarder_client = new WeakMap(), _Forwarder_deps = new WeakMap(), _Forwarder_a
             await sleep(wait, signal);
         }
     }
-}, _Forwarder_tick = async function _Forwarder_tick() {
-    const { data } = await __classPrivateFieldGet(this, _Forwarder_client, "f").call('ListCallbackEvents', {
-        query: { pending: true, limit: BATCH },
-    });
-    const ack = [];
-    let ok = true;
-    for (const item of data.items) {
-        if (__classPrivateFieldGet(this, _Forwarder_abort, "f").signal.aborted) {
-            break;
-        }
-        if (__classPrivateFieldGet(this, _Forwarder_unacked, "f").has(item.id) || await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_forward).call(this, item)) {
-            ack.push(item.id);
-        }
-        else {
-            // Stop the batch so later events don't overtake the failed one.
-            ok = false;
-            break;
+}, _Forwarder_tick = 
+/**
+ * Forwards one poll's worth of pending events. Returns whether to poll again
+ * at once: the page limit was hit with events still unread, and progress was
+ * made (so held sessions alone never cause a busy loop).
+ */
+async function _Forwarder_tick() {
+    const now = (__classPrivateFieldGet(this, _Forwarder_deps, "f").now || Date.now)();
+    // Sessions whose later events are skipped in this poll.
+    const skip = new Set();
+    const seen = new Set();
+    let after;
+    let page = 0;
+    let full = false;
+    let progress = false;
+    do {
+        const { data } = await __classPrivateFieldGet(this, _Forwarder_client, "f").call('ListCallbackEvents', {
+            query: { pending: true, limit: BATCH, ...(after ? { after } : {}) },
+        });
+        const ack = [];
+        for (const item of data.items) {
+            if (__classPrivateFieldGet(this, _Forwarder_abort, "f").signal.aborted) {
+                break;
+            }
+            seen.add(item.sessionId);
+            const held = __classPrivateFieldGet(this, _Forwarder_held, "f").get(item.sessionId);
+            if (skip.has(item.sessionId)
+                || (held && held.retryAt > now && !__classPrivateFieldGet(this, _Forwarder_unacked, "f").has(item.id))) {
+                skip.add(item.sessionId);
+                continue;
+            }
+            if (__classPrivateFieldGet(this, _Forwarder_unacked, "f").has(item.id)) {
+                ack.push(item.id);
+                continue;
+            }
+            const outcome = await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_forward).call(this, item);
+            if (outcome.ok) {
+                __classPrivateFieldGet(this, _Forwarder_held, "f").delete(item.sessionId);
+                ack.push(item.id);
+            }
+            else {
+                // Hold the session so its later events don't overtake this one.
+                __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_hold).call(this, item, outcome, now);
+                skip.add(item.sessionId);
+            }
         }
-    }
-    if (ack.length) {
-        for (const id of ack) {
-            __classPrivateFieldGet(this, _Forwarder_unacked, "f").add(id);
+        if (ack.length) {
+            progress = true;
+            for (const id of ack) {
+                __classPrivateFieldGet(this, _Forwarder_unacked, "f").add(id);
+            }
+            await __classPrivateFieldGet(this, _Forwarder_client, "f").call('AcknowledgeCallbackEvents', {
+                body: { ids: ack },
+            });
+            for (const id of ack) {
+                __classPrivateFieldGet(this, _Forwarder_unacked, "f").delete(id);
+            }
         }
-        await __classPrivateFieldGet(this, _Forwarder_client, "f").call('AcknowledgeCallbackEvents', {
-            body: { ids: ack },
-        });
-        for (const id of ack) {
-            __classPrivateFieldGet(this, _Forwarder_unacked, "f").delete(id);
+        // `next` skips what this page returned, including held events.
+        after = data.next;
+        full = data.items.length >= BATCH;
+        page += 1;
+    } while (full && page < MAX_PAGES && !__classPrivateFieldGet(this, _Forwarder_abort, "f").signal.aborted);
+    if (!full) {
+        // The listing was read to its end: forget sessions with nothing pending.
+        for (const sessionId of __classPrivateFieldGet(this, _Forwarder_held, "f").keys()) {
+            if (!seen.has(sessionId)) {
+                __classPrivateFieldGet(this, _Forwarder_held, "f").delete(sessionId);
+            }
         }
     }
-    return { ok, count: data.items.length };
+    return full && progress;
+}, _Forwarder_hold = function _Forwarder_hold(item, outcome, now) {
+    const prev = __classPrivateFieldGet(this, _Forwarder_held, "f").get(item.sessionId);
+    const delay = nextBackoff(prev?.delay || 0);
+    __classPrivateFieldGet(this, _Forwarder_held, "f").set(item.sessionId, {
+        blocked: {
+            sessionId: item.sessionId,
+            event: item.event,
+            eventId: item.id,
+            ...(outcome.httpStatus === undefined
+                ? {}
+                : { httpStatus: outcome.httpStatus }),
+            attempts: (prev?.blocked.attempts || 0) + 1,
+            lastError: outcome.error,
+            since: prev?.blocked.since || new Date(now).toISOString(),
+        },
+        retryAt: now + delay,
+        delay,
+    });
 }, _Forwarder_forward = async function _Forwarder_forward(item) {
     const doFetch = __classPrivateFieldGet(this, _Forwarder_deps, "f").forwardFetch || globalThis.fetch;
     const record = (status, httpStatus) => {
@@ -150,7 +224,7 @@ _Forwarder_client = new WeakMap(), _Forwarder_deps = new WeakMap(), _Forwarder_a
             if (res.ok) {
                 __classPrivateFieldSet(this, _Forwarder_forwarded, __classPrivateFieldGet(this, _Forwarder_forwarded, "f") + 1, "f");
                 record('delivered', res.status);
-                return true;
+                return { ok: true };
             }
             __classPrivateFieldSet(this, _Forwarder_failed, __classPrivateFieldGet(this, _Forwarder_failed, "f") + 1, "f");
             const url = targetUrl(this.target, host);
@@ -159,7 +233,7 @@ _Forwarder_client = new WeakMap(), _Forwarder_deps = new WeakMap(), _Forwarder_a
                     + 'followed; call again with the redirect target\'s `path`.'
                 : `${url} returned HTTP ${res.status}`, "f");
             record('failed', res.status);
-            return false;
+            return { ok: false, httpStatus: res.status, error: __classPrivateFieldGet(this, _Forwarder_lastError, "f") };
         }
         catch (err) {
             __classPrivateFieldSet(this, _Forwarder_lastError, err instanceof Error ? err.message : String(err), "f");
@@ -168,7 +242,7 @@ _Forwarder_client = new WeakMap(), _Forwarder_deps = new WeakMap(), _Forwarder_a
     // No loopback address accepted the connection.
     __classPrivateFieldSet(this, _Forwarder_failed, __classPrivateFieldGet(this, _Forwarder_failed, "f") + 1, "f");
     record('failed');
-    return false;
+    return { ok: false, error: __classPrivateFieldGet(this, _Forwarder_lastError, "f") || 'Connection failed' };
 };
 /** The forwarders of one MCP process, one per org key. */
 export class ForwarderRegistry {
@@ -207,17 +281,26 @@ export function proxyCallbackEventsTool(deps = {}) {
             + 'to a local route, like `stripe listen --forward-to`. Call it '
             + 'when the app\'s callback route runs locally. It POSTs each '
             + 'envelope as JSON to `http://127.0.0.1:<port><path>` (loopback '
-            + 'only; also tries `[::1]`) in order, acknowledges 2xx '
-            + 'responses, and retries anything else, redirects included, '
-            + 'with backoff. Creates the listener on first use, so it is not '
+            + 'only; also tries `[::1]`) and acknowledges 2xx responses. '
+            + 'Events of one session arrive in order. When the app rejects '
+            + 'an event, including with a redirect, that session is held and '
+            + 'retried with backoff (2 s up to 30 s) while other sessions '
+            + 'keep flowing. Creates the listener on first use, so it is not '
             + 'read-only. One forwarder runs per org: call again to read '
             + 'status, or with another `port` or `path` to retarget. '
             + '`stop: true` stops forwarding only. Forwarding lasts only '
             + 'while this MCP server runs; production needs '
             + '`create_org_callback_subscription`. Returns `{ forwarding, '
-            + 'target, listener, forwarded, failed, lastError?, recent }`; '
-            + '`listener.expiresAt` is the lease end, and `recent` lists the '
-            + 'last events with `status` and `httpStatus`.',
+            + 'target, listener, forwarded, failed, lastError?, recent, '
+            + 'blocked }`. `listener.expiresAt` is the lease end, and '
+            + '`recent` lists the last events with `status` and '
+            + '`httpStatus`. `blocked` lists each held session as '
+            + '`{ sessionId, event, eventId, httpStatus?, attempts, '
+            + 'lastError?, since }`, and is `[]` when none is held. When '
+            + '`blocked` is not empty, check the app\'s response and logs '
+            + 'for that session. The app must return 2xx for a result that '
+            + 'failed verification, and 5xx only for a temporary error. '
+            + 'Fix the app, and the session resumes on the next retry.',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.35",
+	"version": "0.1.36",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -83,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.1.5",
-		"@reclaimprotocol/client": "0.1.35",
+		"@reclaimprotocol/client": "0.1.36",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/builder-mode.md

@@ -75,9 +75,17 @@ TEE binding. Edit the app with your file tools. Use the HTTP API
 `@reclaimprotocol/client`. The only exception is `results.receive` on the
 callback, or when the developer asks for the client package.
 
+The app's frontend renders every state and every failure, never only a
+spinner. Follow "UI states" in `how_it_works({ topic: "integration" })`. The
+callback route responds `error.retryable ? 503 : 200` for a thrown
+`ResultVerificationError`; a result that failed verification gets 2xx.
+
 For local development, call `proxy_callback_events({ port, path })` to forward
 events to the app's callback route on localhost. The local listener works only
-while this MCP server runs. Production needs a webhook:
+while this MCP server runs. It keeps events in order per session and retries
+a session the app rejects with backoff, so other sessions keep flowing. When
+its status lists `blocked` sessions, read that session's callback route
+response and logs, and fix the app. Production needs a webhook:
 `create_org_callback_subscription` with the deployed app's public URL. Without
 one, session creation returns 409.
 

package/skill/start-integration.md

@@ -32,8 +32,9 @@ Without subagents, do step 2 first.
 - [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
 - [ ] Call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it. Never print or commit the key. Confirm the env file is in `.gitignore`.
 - [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) and returns `verificationUrl`. Read the provider ID from server config (an env variable such as `RECLAIM_PROVIDER_ID`), so the route works before the provider exists.
-- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points.
-- [ ] Add a frontend Verify button that opens `verificationUrl`, and shows the stored result when it arrives.
+- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points. Store every failure on the verification session record and log it server-side: a failure event (`verification_rejected`, `verification_error`, `verification_cancelled`, `session_expired`), or a thrown `ResultVerificationError` (`error.reason` plus each failing proof's `reason`). Respond `error.retryable ? 503 : 200`. A result that failed verification gets 2xx, because retrying can't fix it. Read the exact pattern in `how_it_works({ topic: "integration" })`.
+- [ ] Add a status route the frontend polls. It returns the stored status, data points, and failure reason. While the app has no result, it also reads `GET /verifications/sessions/{sessionId}`, so a session that ended in Builder never stays pending.
+- [ ] Add a frontend Verify button that opens `verificationUrl`, and render every state in "UI states" in `how_it_works({ topic: "integration" })`: idle, waiting in the other tab, verifying, verified (with the data points), failed (plain-language reason and **Try again**), and expired or cancelled (**Try again**). Never leave a spinner as the only feedback.
 - [ ] Start the app. Call `proxy_callback_events({ port, path })` with the callback route's port and path. It forwards the org's verification events to that route on localhost, with no public URL.
 <!-- ifnot:providerIds -->
 - [ ] Call `check_attestor` once. If it fails, tell the developer before they spend time on the provider build: this machine cannot reach the attestor.
@@ -67,8 +68,8 @@ Build a new organization-private provider for exactly "{{goal}}". Do not search
 ## 4. Wire the provider and test end to end
 
 - [ ] Set the provider ID in the app's server config.
-- [ ] Confirm the callback route is forwarding: `proxy_callback_events` with no `stop` returns its status.
-- [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result.
-- [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, call `list_verification_deliveries` and fix the cause. Repeat until the app shows the stored result.
+- [ ] Confirm the callback route is forwarding: `proxy_callback_events` with no `stop` returns its status. If `blocked` is not empty, the app rejected that session's event: read the callback route's response and logs, fix the app, and check again.
+- [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result. Also test one failure, such as cancelling in the verification tab, and confirm the app shows the failed state with **Try again**.
+- [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, or the app shows an unexpected failure, call `list_verification_deliveries` and fix the cause. Repeat until the app shows the stored result.
 - [ ] Ask the developer to set up the production callback. The local listener works only while this coding agent's MCP server runs; once it stops, the deployed app receives no results. Call `create_org_callback_subscription` with the deployed app's public callback route URL for all five session-ending events: `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`.
 - [ ] If they have no deployed URL yet, tell them: "When you deploy, ask me to run `create_org_callback_subscription` with your public callback URL, or results will not reach the app."

package/skill/verification-client-integration.md

@@ -47,12 +47,22 @@ server), or migrate to the session flow below. When migrating, remove
    is not proof of success. Use `@reclaimprotocol/client`
    (`ReclaimVerification.create({ orgSecret })`, `sessions.create`) only when
    the developer asks for it.
-5. Add a backend callback endpoint. Persist each delivery idempotently and load
+5. Add a backend callback route. Persist each delivery idempotently and load
    the expected session ID and org ID from app storage. To verify the result on
-   your callback, install `@reclaimprotocol/client` in the backend and call
+   your callback route, install `@reclaimprotocol/client` in the backend and call
    `reclaim.results.receive(body, { reclaimSessionId, expectedAud,
    orgEthPrivateKey })`. Use the verified proof data to update app state.
-   Handle callback retries and terminal failure outcomes.
+   Store every failure on the verification session record: failure events, and
+   a thrown `ResultVerificationError` (`error.reason` and each
+   `error.outcome.proofs[].reason`). Respond `error.retryable ? 503 : 200`.
+   A result that failed verification gets 2xx: retrying can't fix it, and an
+   unacknowledged delivery holds back that session's later events. Respond 5xx
+   for any other temporary problem too, such as a database outage.
+   Add a status route that returns the stored status, data points, and failure
+   reason. While the app has no result, it also reads
+   `GET /verifications/sessions/{sessionId}`, so a session Builder has ended
+   never stays pending in the app. Render the frontend per
+   [UI states](#ui-states).
 6. Exercise one session through the selected registered Verification Client,
    inspect its Builder events, and test the app's success and failure paths.
    Omit `verificationClientUrl` to use the Portal, or select another client
@@ -125,16 +135,37 @@ Receive and verify the result on the callback route. This is the one place the
 client package is needed:
 
 ```js
-import { ReclaimVerification } from '@reclaimprotocol/client'
+import { ReclaimVerification, ResultVerificationError } from '@reclaimprotocol/client'
 
 const reclaim = ReclaimVerification.create({
   orgSecret: process.env.RECLAIM_ORG_SECRET,
 })
 
 app.post('/reclaim/callback', async(req, res) => {
-  const outcome = await reclaim.results.receive(req.body, {
-    reclaimSessionId: sessionId, // the id you stored
-  })
+  let outcome
+  try {
+    outcome = await reclaim.results.receive(req.body, {
+      reclaimSessionId: sessionId, // the id you stored
+    })
+  } catch(error) {
+    if(!(error instanceof ResultVerificationError)) {
+      throw error
+    }
+
+    if(error.retryable) {
+      return res.sendStatus(503) // temporary: Builder retries the delivery
+    }
+
+    // Retrying can't fix a result that failed verification. Store the failure
+    // where the status route returns it, then acknowledge the delivery.
+    const proofReasons = (error.outcome.proofs ?? [])
+      .filter((proof) => !proof.proofValid)
+      .map((proof) => proof.reason)
+    console.warn('result failed verification', error.reason, proofReasons)
+    await markSessionFailed(sessionId, error.reason) // your app's storage
+    return res.sendStatus(200)
+  }
+
   if(outcome.kind === 'result') {
     console.log(outcome.result.payload) // verified
   }
@@ -143,8 +174,34 @@ app.post('/reclaim/callback', async(req, res) => {
 })
 ```
 
-Check or investigate a session, from the backend (optional, e.g. a status
-endpoint the frontend polls) or by hand with `curl`. All take the org key:
+### UI states
+
+Apply these rules when you write the frontend. Test each state, including one
+failure.
+
+| State | Render |
+| --- | --- |
+| Idle | The **Verify** button. |
+| Waiting in the other tab | The current step ("Finish verifying in the new tab") and a way to reopen `verificationUrl`. After about 30 seconds, say what is happening and offer **Cancel** or **Try again**. |
+| Verifying | "Checking your result". |
+| Verified | The requested data points. |
+| Failed | A plain-language reason and what to do next, near the **Verify** button, with **Try again**. |
+| Expired or cancelled | Say which, with **Try again**. |
+
+- Show the current step, never an indefinite spinner (Nielsen heuristic 1,
+  visibility of system status).
+- Write errors in plain language that says what happened and what to do next,
+  visible next to the action, with a recovery action (Nielsen Norman Group
+  error-message guidelines).
+- Send reason codes (`error.reason`, proof `reason`) to logs or an expandable
+  **Details** section, not the headline.
+- Announce changes: `role="status"` (or `aria-live="polite"`) for progress,
+  `role="alert"` for failures (WCAG 2.2 SC 4.1.3).
+- Pair color with text or an icon (WCAG 2.2 SC 1.4.1).
+- Stop the waiting state when the status route reports a terminal status.
+
+Check or investigate a session from the status route or by hand with `curl`.
+All routes take the org key:
 
 | Route | Use |
 | --- | --- |

package/src/mcp/api/operations.gen.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:de7373741e35).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:96339e8dff91).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.

package/src/mcp/tools/verification/proxy-callback-events.ts

@@ -17,6 +17,12 @@ const POLL_MS = 2_000
 const MAX_BACKOFF_MS = 30_000
 const FORWARD_TIMEOUT_MS = 10_000
 const BATCH = 50
+/**
+ * Pages read per poll. A page is `BATCH` events, so a poll can look past up to
+ * 500 pending events. That is enough to reach other sessions behind several
+ * held ones, and still bounds the work of one poll.
+ */
+const MAX_PAGES = 10
 const RECENT = 10
 /** Loopback addresses, in the order tried. Dev servers often bind only one. */
 const HOSTS = ['127.0.0.1', '[::1]']
@@ -42,7 +48,25 @@ type Recent = {
 	at: string
 }
 
+/** A session whose oldest pending event the app has not accepted. */
+type Blocked = {
+	sessionId: string
+	event: string
+	eventId: string
+	httpStatus?: number
+	attempts: number
+	lastError?: string
+	/** When the first attempt failed, as an ISO timestamp. */
+	since: string
+}
+
+type Held = { blocked: Blocked, retryAt: number, delay: number }
+
+type Outcome = { ok: true } | { ok: false, httpStatus?: number, error: string }
+
 export interface ProxyDeps extends CallbackDeps {
+	/** The clock, in milliseconds. Defaults to `Date.now`. */
+	now?: () => number
 	/** Delivers an event to the app. Defaults to global `fetch`. */
 	forwardFetch?: typeof globalThis.fetch
 	/** Waits between polls. Resolves early, without error, on abort. */
@@ -53,9 +77,13 @@ export interface ProxyDeps extends CallbackDeps {
 /**
  * Polls the org's pending pull events and POSTs each envelope to a local
  * route, like `stripe listen --forward-to`. 2xx responses are acknowledged;
- * anything else (redirects included) stays pending and is retried with
- * exponential backoff. After a failure the batch stops, so events reach the
- * app in order.
+ * anything else (redirects included) stays pending.
+ *
+ * Order holds per session. When an event fails, its session is held: its later
+ * events are not sent or acknowledged, and the failed event is retried with
+ * exponential backoff (2 s, 4 s, ... 30 s). Other sessions keep flowing at the
+ * normal poll rate. Held sessions appear in `status().blocked`, and clear when
+ * the app accepts the event.
  */
 class Forwarder {
 	target: Target
@@ -69,6 +97,8 @@ class Forwarder {
 	#recent: Recent[] = []
 	/** Delivered to the app but not yet acknowledged; never POSTed twice. */
 	#unacked = new Set<string>()
+	/** Held sessions by session id, with the time of their next attempt. */
+	#held = new Map<string, Held>()
 	#host = HOSTS[0]
 	#running: Promise<void>
 
@@ -94,6 +124,7 @@ class Forwarder {
 			failed: this.#failed,
 			...(this.#lastError ? { lastError: this.#lastError } : {}),
 			recent: [...this.#recent],
+			blocked: [...this.#held.values()].map((h) => h.blocked),
 		}
 	}
 
@@ -109,9 +140,9 @@ class Forwarder {
 		while(!signal.aborted) {
 			let wait = POLL_MS
 			try {
-				const { ok, count } = await this.#tick()
-				backoff = ok ? 0 : nextBackoff(backoff)
-				wait = ok ? (count >= BATCH ? 0 : POLL_MS) : backoff
+				const more = await this.#tick()
+				backoff = 0
+				wait = more ? 0 : POLL_MS
 			} catch(err) {
 				this.#lastError = err instanceof Error ? err.message : String(err)
 				LOGGER.warn({ err }, 'callback proxy poll failed')
@@ -125,43 +156,113 @@ class Forwarder {
 		}
 	}
 
+	/**
+	 * Forwards one poll's worth of pending events. Returns whether to poll again
+	 * at once: the page limit was hit with events still unread, and progress was
+	 * made (so held sessions alone never cause a busy loop).
+	 */
 	async #tick() {
-		const { data } = await this.#client.call('ListCallbackEvents', {
-			query: { pending: true, limit: BATCH },
-		})
-		const ack: string[] = []
-		let ok = true
-		for(const item of data.items) {
-			if(this.#abort.signal.aborted) {
-				break
-			}
+		const now = (this.#deps.now || Date.now)()
+		// Sessions whose later events are skipped in this poll.
+		const skip = new Set<string>()
+		const seen = new Set<string>()
+		let after: string | undefined
+		let page = 0
+		let full = false
+		let progress = false
+		do {
+			const { data } = await this.#client.call('ListCallbackEvents', {
+				query: { pending: true, limit: BATCH, ...(after ? { after } : {}) },
+			})
+			const ack: string[] = []
+			for(const item of data.items) {
+				if(this.#abort.signal.aborted) {
+					break
+				}
+
+				seen.add(item.sessionId)
+				const held = this.#held.get(item.sessionId)
+				if(
+					skip.has(item.sessionId)
+					|| (held && held.retryAt > now && !this.#unacked.has(item.id))
+				) {
+					skip.add(item.sessionId)
+					continue
+				}
+
+				if(this.#unacked.has(item.id)) {
+					ack.push(item.id)
+					continue
+				}
 
-			if(this.#unacked.has(item.id) || await this.#forward(item)) {
-				ack.push(item.id)
-			} else {
-				// Stop the batch so later events don't overtake the failed one.
-				ok = false
-				break
+				const outcome = await this.#forward(item)
+				if(outcome.ok) {
+					this.#held.delete(item.sessionId)
+					ack.push(item.id)
+				} else {
+					// Hold the session so its later events don't overtake this one.
+					this.#hold(item, outcome, now)
+					skip.add(item.sessionId)
+				}
 			}
-		}
 
-		if(ack.length) {
-			for(const id of ack) {
-				this.#unacked.add(id)
+			if(ack.length) {
+				progress = true
+				for(const id of ack) {
+					this.#unacked.add(id)
+				}
+
+				await this.#client.call('AcknowledgeCallbackEvents', {
+					body: { ids: ack },
+				})
+				for(const id of ack) {
+					this.#unacked.delete(id)
+				}
 			}
 
-			await this.#client.call('AcknowledgeCallbackEvents', {
-				body: { ids: ack },
-			})
-			for(const id of ack) {
-				this.#unacked.delete(id)
+			// `next` skips what this page returned, including held events.
+			after = data.next
+			full = data.items.length >= BATCH
+			page += 1
+		} while(full && page < MAX_PAGES && !this.#abort.signal.aborted)
+
+		if(!full) {
+			// The listing was read to its end: forget sessions with nothing pending.
+			for(const sessionId of this.#held.keys()) {
+				if(!seen.has(sessionId)) {
+					this.#held.delete(sessionId)
+				}
 			}
 		}
 
-		return { ok, count: data.items.length }
+		return full && progress
+	}
+
+	#hold(
+		item: CallbackEvent,
+		outcome: Extract<Outcome, { ok: false }>,
+		now: number,
+	) {
+		const prev = this.#held.get(item.sessionId)
+		const delay = nextBackoff(prev?.delay || 0)
+		this.#held.set(item.sessionId, {
+			blocked: {
+				sessionId: item.sessionId,
+				event: item.event,
+				eventId: item.id,
+				...(outcome.httpStatus === undefined
+					? {}
+					: { httpStatus: outcome.httpStatus }),
+				attempts: (prev?.blocked.attempts || 0) + 1,
+				lastError: outcome.error,
+				since: prev?.blocked.since || new Date(now).toISOString(),
+			},
+			retryAt: now + delay,
+			delay,
+		})
 	}
 
-	async #forward(item: CallbackEvent) {
+	async #forward(item: CallbackEvent): Promise<Outcome> {
 		const doFetch = this.#deps.forwardFetch || globalThis.fetch
 		const record = (status: Recent['status'], httpStatus?: number) => {
 			this.#recent.push({
@@ -191,7 +292,7 @@ class Forwarder {
 				if(res.ok) {
 					this.#forwarded += 1
 					record('delivered', res.status)
-					return true
+					return { ok: true }
 				}
 
 				this.#failed += 1
@@ -201,7 +302,7 @@ class Forwarder {
 						+ 'followed; call again with the redirect target\'s `path`.'
 					: `${url} returned HTTP ${res.status}`
 				record('failed', res.status)
-				return false
+				return { ok: false, httpStatus: res.status, error: this.#lastError }
 			} catch(err) {
 				this.#lastError = err instanceof Error ? err.message : String(err)
 			}
@@ -210,7 +311,7 @@ class Forwarder {
 		// No loopback address accepted the connection.
 		this.#failed += 1
 		record('failed')
-		return false
+		return { ok: false, error: this.#lastError || 'Connection failed' }
 	}
 }
 
@@ -257,17 +358,26 @@ export function proxyCallbackEventsTool(deps: ProxyDeps = {}): RegisteredTool {
 				+ 'to a local route, like `stripe listen --forward-to`. Call it '
 				+ 'when the app\'s callback route runs locally. It POSTs each '
 				+ 'envelope as JSON to `http://127.0.0.1:<port><path>` (loopback '
-				+ 'only; also tries `[::1]`) in order, acknowledges 2xx '
-				+ 'responses, and retries anything else, redirects included, '
-				+ 'with backoff. Creates the listener on first use, so it is not '
+				+ 'only; also tries `[::1]`) and acknowledges 2xx responses. '
+				+ 'Events of one session arrive in order. When the app rejects '
+				+ 'an event, including with a redirect, that session is held and '
+				+ 'retried with backoff (2 s up to 30 s) while other sessions '
+				+ 'keep flowing. Creates the listener on first use, so it is not '
 				+ 'read-only. One forwarder runs per org: call again to read '
 				+ 'status, or with another `port` or `path` to retarget. '
 				+ '`stop: true` stops forwarding only. Forwarding lasts only '
 				+ 'while this MCP server runs; production needs '
 				+ '`create_org_callback_subscription`. Returns `{ forwarding, '
-				+ 'target, listener, forwarded, failed, lastError?, recent }`; '
-				+ '`listener.expiresAt` is the lease end, and `recent` lists the '
-				+ 'last events with `status` and `httpStatus`.',
+				+ 'target, listener, forwarded, failed, lastError?, recent, '
+				+ 'blocked }`. `listener.expiresAt` is the lease end, and '
+				+ '`recent` lists the last events with `status` and '
+				+ '`httpStatus`. `blocked` lists each held session as '
+				+ '`{ sessionId, event, eventId, httpStatus?, attempts, '
+				+ 'lastError?, since }`, and is `[]` when none is held. When '
+				+ '`blocked` is not empty, check the app\'s response and logs '
+				+ 'for that session. The app must return 2xx for a result that '
+				+ 'failed verification, and 5xx only for a temporary error. '
+				+ 'Fix the app, and the session resumes on the next retry.',
 			inputSchema: {
 				type: 'object',
 				properties: {