@jinn-network/client 0.1.6 → 0.1.7-canary.0a586ca9

package/dist/adapters/mech/adapter.js

@@ -4,11 +4,23 @@ import { privateKeyToAccount } from 'viem/accounts';
 import { base, baseSepolia } from 'viem/chains';
 import { PermanentError, parseTask } from '../../types/index.js';
 import { createClients } from './safe.js';
+/**
+ * Coalesce a string-or-array RPC input down to the head URL for display in
+ * error contexts (`formatRpcError` expects a single host). The adapter
+ * accepts the full fallback chain at the type level; this helper exists so
+ * the error-formatting call sites can keep their old signature.
+ */
+function rpcUrlForDisplay(rpcUrl) {
+    return Array.isArray(rpcUrl) ? rpcUrl[0] : rpcUrl;
+}
 import { buildResultPayload, uploadToIpfs, cidToDigestHex, fetchFromIpfs, fetchSignedTaskFromIpfs, fetchSignedEnvelopeFromIpfs, } from './ipfs.js';
 import { canonicalJson } from '../../harnesses/engine/canonical-json.js';
-import { SignedEnvelopeSchema } from '../../types/envelope.js';
+import { normalizeEnvelopeRole, SignedEnvelopeSchema } from '../../types/envelope.js';
 import { submitTask, claimTask as claimTaskOnchain, claimEvaluation as claimEvaluationOnchain, claimDelivery, getMechDeliveryRate, getTimeoutBounds, decodeTaskCreatedLogs, decodeSolutionDeliveryClaimedLogs, decodeDeliverLogs, findLatestDeliveryDataHexForRequest, getMarketplaceRequestDeliveryMech, getTaskCidDigest, callDeliverToMarketplace, canClaimTask, canClaimEvaluation, } from './contracts.js';
+import { SafeInnerRevertError, formatDecodedRevert, isNonRecoverableInnerRevert, } from './safe-revert.js';
+import { verdictCodeFromValue } from './verdict-code.js';
 import { manifestDigestForCid } from './digest.js';
+import { emitStructured } from '../../events/emitter.js';
 import { withRecoverableRetry } from '../../tx-retry.js';
 import { formatRpcError } from '../../rpc-error-context.js';
 import { SOLUTION_ENVELOPE_CID_CONTEXT_KEY, SOLUTION_TASK_CID_CONTEXT_KEY, RESTORATION_TASK_CID_CONTEXT_KEY, } from '../../harnesses/impls/evaluation-context.js';
@@ -16,6 +28,41 @@ import { signTaskV1 } from '../../tasks/signing.js';
 const ROUTER_REQUEST_CURSOR_CONFIG_KEY = 'mech_router_request_block_cursor_v1';
 const PENDING_EVALUATION_SOLUTIONS_CONFIG_KEY = 'mech_pending_evaluation_solutions_v1';
 const DEFAULT_MECH_DELIVER_BACKFILL_LOOKBACK_BLOCKS = 100000n;
+/** Yield to the event loop every N evaluation opportunities so a large retry
+ *  backlog can't starve the HTTP API mid-cycle. */
+const EVALUATION_RETRY_YIELD_EVERY = 10;
+/**
+ * Bound the number of consecutive transient/uncaught failures for a single
+ * pending evaluation solution. Once exceeded, the solution is pruned from
+ * `pendingEvaluationSolutions` to stop unbounded log spam (#645). At default
+ * pollIntervalMs=5000, twenty cycles ≈ 100 s — comfortably above a normal
+ * transient RPC outage window, well below "spamming the log forever".
+ *
+ * The signal-driven prunes (terminal claimability, `null` delivery-envelope
+ * CID per #553, !isDiscoveryTaskAllowed) still fire on their own conditions;
+ * this counter is the backstop for failure modes that don't surface a clean
+ * terminal signal.
+ */
+const MAX_EVALUATION_RETRY_ATTEMPTS = 20;
+/**
+ * Decide whether a `canClaimEvaluation` failure means the opportunity can NEVER
+ * become claimable (terminal, prune it) versus one that could still clear later
+ * (transient, keep retrying).
+ *
+ * Classification is done on the *structured* `revertName` decoded straight from
+ * the inner revert data — not by regex-unformatting the operator-facing `reason`
+ * string. The format→regex round-trip was fragile: an arg value containing a
+ * `(` corrupted the strip, and the `flattenErrorMessage` fallback produced
+ * arbitrary text the regex mangled, silently mis-classifying opportunities.
+ *
+ * A false-keep (re-checking a dead opportunity) only costs one more RPC; a
+ * false-prune (dropping a still-claimable opportunity) loses real work — so
+ * when in doubt we keep. Anything without a known non-recoverable revert name
+ * is treated as transient.
+ */
+function isTerminalEvaluationReason(revertName) {
+    return isNonRecoverableInnerRevert(revertName);
+}
 const DEFAULT_ROUTER_LOG_CHUNK_BLOCKS = 9999n;
 /**
  * Floor block for the on-chain TaskCreated backlog scan, per chain.
@@ -81,8 +128,18 @@ export class MechAdapter {
     deliveryBlockCursor = 0n;
     pendingEvaluations = new Map();
     observedTasks = new Map();
+    /**
+     * Read-through cache for `restorationAnnouncementForTaskId` — the restoration
+     * task body looked up *while building an evaluation opportunity*. Kept
+     * SEPARATE from `observedTasks` (the `watchForTasks` discovery dedup set) on
+     * purpose: writing the restoration body into `observedTasks` made the
+     * TaskCreated scan skip that taskId as a *restoration* opportunity just
+     * because the daemon had built an *evaluation* opportunity for someone
+     * else's attempt on it. That blocked the creator's own daemon from claiming
+     * its own attempt on a multi-attempt (`maxClaims > 1`) task it posted.
+     */
+    restorationBodyCache = new Map();
     requestKinds = new Map();
-    claimedRestorationTaskIds = new Set();
     evaluationOpportunities = new Map();
     pendingEvaluationSolutions = new Map();
     // Original Tasks keyed by request ID (restoration and evaluation)
@@ -104,7 +161,7 @@ export class MechAdapter {
                     formatRpcError(message, {
                         operation: 'getBlockNumber',
                         chain: this.config.chainId === 84532 ? 'base-sepolia' : 'base',
-                        rpcUrl: this.config.rpcUrl,
+                        rpcUrl: rpcUrlForDisplay(this.config.rpcUrl),
                     }));
             },
         });
@@ -214,6 +271,13 @@ export class MechAdapter {
                         ? item.transactionHash
                         : undefined,
                     blockNumber: typeof item.blockNumber === 'number' ? item.blockNumber : undefined,
+                    // #645: clamp to a non-negative integer. A tampered or corrupted
+                    // store row carrying a negative or fractional failedAttempts could
+                    // otherwise underflow the prune budget (e.g. -1_000_000_000 would
+                    // defeat the bound for ~10^9 cycles).
+                    failedAttempts: typeof item.failedAttempts === 'number' && Number.isFinite(item.failedAttempts)
+                        ? Math.max(0, Math.floor(item.failedAttempts))
+                        : 0,
                 };
                 this.pendingEvaluationSolutions.set(solution.requestId, solution);
             }
@@ -236,6 +300,90 @@ export class MechAdapter {
             return;
         this.persistPendingEvaluationSolutions();
     }
+    /**
+     * Increment the per-solution failure counter and prune when it exceeds the
+     * MAX_EVALUATION_RETRY_ATTEMPTS budget. Persistence runs on every increment
+     * so a crash mid-cycle does not lose the count (and let a wedge resume
+     * log-spamming after a restart).
+     *
+     * Call sites: ONLY the two paths that fail to make progress on this specific
+     * solution — the transient `canClaimEvaluation` branch in
+     * evaluationAnnouncementForSolution, and the `catch (err)` arm of
+     * retryPendingEvaluationSolutions. Do NOT call from the signal-driven prune
+     * paths (terminal claimability, null delivery-envelope CID,
+     * !isDiscoveryTaskAllowed) — those already prune cleanly.
+     *
+     * Returns true when the solution was pruned (caller should stop work on it).
+     */
+    recordEvaluationFailureAndMaybePrune(solution) {
+        const next = (solution.failedAttempts ?? 0) + 1;
+        solution.failedAttempts = next;
+        if (next > MAX_EVALUATION_RETRY_ATTEMPTS) {
+            console.log(`[mech] pruning evaluation opportunity ${solution.requestId} for task ${solution.taskId}/${solution.attemptIndex}: ` +
+                `exceeded retry budget (${MAX_EVALUATION_RETRY_ATTEMPTS}) — pruned`);
+            this.forgetPendingEvaluationSolution(solution.requestId);
+            return true;
+        }
+        this.persistPendingEvaluationSolutions();
+        return false;
+    }
+    /** Prune terminal evaluation state so the poll loop stops retrying (#512). */
+    pruneTerminalEvaluationOpportunity(params) {
+        const { opportunityId, solutionRequestId, reason } = params;
+        const target = opportunityId ?? solutionRequestId ?? 'unknown';
+        console.log(`[mech] pruning evaluation opportunity ${target}: ${reason} (terminal — pruned)`);
+        if (opportunityId) {
+            this.evaluationOpportunities.delete(opportunityId);
+            this.observedTasks.delete(opportunityId);
+        }
+        if (solutionRequestId) {
+            this.forgetPendingEvaluationSolution(solutionRequestId);
+        }
+    }
+    async claimEvaluationWithTerminalPrune(opportunityId, evaluationOpportunity, evaluationTaskCidDigest) {
+        try {
+            return await this.claimEvaluation(evaluationOpportunity.taskId, evaluationOpportunity.attemptIndex, evaluationTaskCidDigest);
+        }
+        catch (err) {
+            if (err instanceof SafeInnerRevertError && isNonRecoverableInnerRevert(err.decodedName)) {
+                this.pruneTerminalEvaluationOpportunity({
+                    opportunityId,
+                    solutionRequestId: evaluationOpportunity.task.restorationRequestId,
+                    reason: formatDecodedRevert(err.decodedName, err.decodedArgs),
+                });
+            }
+            throw err;
+        }
+    }
+    clearPendingDeliveryRecoveryState(requestId) {
+        this.originalStates.delete(requestId);
+        this.pendingEvaluations.delete(requestId);
+        this.requestKinds.delete(requestId);
+    }
+    recoveryDeliveryExpirySeconds(requestId) {
+        const task = this.originalStates.get(requestId) ?? this.pendingEvaluations.get(requestId);
+        const claimPolicy = task?.claimPolicy ?? DEFAULT_MECH_CLAIM_POLICY;
+        const normalizeTsToSeconds = (value) => {
+            if (value == null)
+                return undefined;
+            return value > 10_000_000_000 ? Math.floor(value / 1000) : value;
+        };
+        const submissionDeadlineSeconds = normalizeTsToSeconds(claimPolicy.submissionDeadlineTs);
+        if (submissionDeadlineSeconds != null)
+            return submissionDeadlineSeconds;
+        const claimWindowEndSeconds = normalizeTsToSeconds(claimPolicy.claimWindowEndTs ?? task?.window?.endTs);
+        if (claimWindowEndSeconds == null)
+            return undefined;
+        return claimWindowEndSeconds + claimPolicy.claimLeaseTtlSeconds;
+    }
+    shouldSkipExpiredRecoveryDelivery(requestId, currentChainTimestampSeconds, recoveryExpirySeconds) {
+        if (currentChainTimestampSeconds <= recoveryExpirySeconds)
+            return false;
+        console.error(`[mech] skipping recovery delivery for ${requestId}: ` +
+            `submission deadline expired at ${new Date(recoveryExpirySeconds * 1000).toISOString()}`);
+        this.clearPendingDeliveryRecoveryState(requestId);
+        return true;
+    }
     async postTask(state) {
         const restorationState = {
             ...state,
@@ -264,18 +412,21 @@ export class MechAdapter {
         const manifestDigest = keccak256(toBytes(signedTask.solverNetManifestCid));
         const policy = this.contractPolicyForTask(restorationState);
         const taskSubmission = await submitTask(this.publicClient, this.walletClient, this.config.safeAddress, this.config.routerAddress, restorationDataHex, manifestDigest, policy, deliveryRate, deliveryRate, maxTimeout, this.config.evictionRecovery);
-        const announcement = {
-            taskId: taskSubmission.taskId,
-            task: {
-                ...restorationState,
-                signedTask,
-                context: { ...(restorationState.context ?? {}), [SOLUTION_TASK_CID_CONTEXT_KEY]: restorationTaskCid },
-            },
-            taskCid: restorationTaskCid,
-            onchainCreationTx: taskSubmission.txHash,
-            onchainCreationBlock: taskSubmission.blockNumber,
-        };
-        this.observedTasks.set(taskSubmission.taskId, announcement);
+        // Deliberately do NOT seed `observedTasks` with the task we just posted.
+        // `observedTasks` is the dedup set for `watchForTasks`: the on-chain
+        // TaskCreated scan skips any taskId already in it (so a task is announced
+        // to the engine-watcher at most once). Seeding it here marked the
+        // creator's own task as "already announced" before it was ever yielded —
+        // which permanently prevented the *creator's own daemon* from discovering,
+        // claiming, and solving a task it posted. On a multi-attempt task
+        // (`maxClaims > 1`) the creator running the solver role is legitimate
+        // (the protocol forbids only self-*evaluation*, and that on a per-attempt
+        // basis), and on testnet it is the intended single-operator dogfood path
+        // — post → claim → solve → grade → settle from one daemon. The dedup is
+        // still correct: it now keys only on tasks `watchForTasks` actually
+        // yielded. `restorationAnnouncementForTaskId` re-hydrates from chain/IPFS
+        // on a cache miss, so dropping the pre-seed costs at most one redundant
+        // fetch if the creator later claims its own task.
         return {
             taskId: taskSubmission.taskId,
             taskCid: restorationTaskCid,
@@ -348,7 +499,14 @@ export class MechAdapter {
             maxClaimsPerOperator: claimPolicy.maxClaimsPerOperator,
             policyHook: (claimPolicy.policyHook ?? zeroAddress),
             evaluationPolicy: {
-                requiredVerdicts: 1,
+                // `requiredVerdicts` defaults to 1 but is overridable via the task's
+                // claim policy. A value > 1 opens additional verdict claim slots per
+                // attempt; combined with the per-evaluator cap below (1), it
+                // guarantees an honest evaluator can still claim and deliver a slot
+                // even when other evaluators have squatted some — the structural fix
+                // for a shared/adversarial testnet where a non-delivering claimer
+                // would otherwise permanently lock a single-slot attempt.
+                requiredVerdicts: claimPolicy.requiredVerdicts ?? 1,
                 passThreshold: 1,
                 evaluationDeadline: submissionDeadline + BigInt(claimPolicy.claimLeaseTtlSeconds),
                 maxVerdictsPerEvaluator: 1,
@@ -381,7 +539,11 @@ export class MechAdapter {
         };
     }
     async restorationAnnouncementForTaskId(taskId) {
-        const cached = this.observedTasks.get(taskId);
+        // Read-through `restorationBodyCache` — NOT `observedTasks`. This helper is
+        // an evaluation-path lookup of a task's restoration body; caching it into
+        // the `watchForTasks` discovery dedup set would suppress the creator's own
+        // restoration-claim discovery for the same taskId (see field comment).
+        const cached = this.restorationBodyCache.get(taskId) ?? this.observedTasks.get(taskId);
         if (cached)
             return cached;
         const taskCidDigest = await getTaskCidDigest(this.publicClient, this.config.routerAddress, taskId);
@@ -394,7 +556,7 @@ export class MechAdapter {
             task,
             taskCid,
         };
-        this.observedTasks.set(taskId, announcement);
+        this.restorationBodyCache.set(taskId, announcement);
         return announcement;
     }
     async restorationAnnouncementFromDigest(params) {
@@ -440,8 +602,6 @@ export class MechAdapter {
         for (const candidate of candidates) {
             if (!this.isDiscoveryTaskAllowed(candidate.taskId))
                 continue;
-            if (this.claimedRestorationTaskIds.has(candidate.taskId))
-                continue;
             // gh #300 ghost-task floor — same floor as the on-chain TaskCreated
             // backlog scan, applied to the DiscoveryAPI path too. Without this,
             // the Ponder indexer (or onchain floor's listClaimableTasks) returns
@@ -465,19 +625,40 @@ export class MechAdapter {
                 continue;
             }
             try {
+                // Yield every hydrated candidate per cycle rather than returning after
+                // the first. The engine-watcher (daemon._runEngineWatcherLoop) is the
+                // single point of skip-state truth — when its in-flight admission gate
+                // fast-skips a candidate (~30s TTL), that skip state never flows back
+                // into the adapter's iteration cursor. Yielding only the first
+                // candidate per cycle meant a fast-skipped slot starved every
+                // subsequent candidate in the round-robin (`fc05f686`) ordering for
+                // the duration of the TTL. By driving the full candidate list per
+                // cycle we let the engine apply its gate to each one, preserving the
+                // round-robin fairness across joined SolverNets. See task 212 live
+                // verification in the fix's commit body.
                 yield await this.restorationAnnouncementFromDigest({
                     taskId: candidate.taskId,
                     taskCidDigest: candidate.taskCidDigest,
                     transactionHash: candidate.createdAtTx,
                     blockNumber: candidate.createdAtBlock,
                 });
-                return;
             }
             catch (err) {
                 console.error(`[mech] failed to hydrate subgraph task ${candidate.taskId}:`, err instanceof Error ? err.message : err);
             }
         }
     }
+    /**
+     * Look up the Deliver-event envelope CID for a pending evaluation solution.
+     *
+     * Returns `null` when the Deliver event is not present in the configured
+     * lookback window. This is a terminal signal for the caller — re-running the
+     * same lookup later is deterministically futile when `solution.blockNumber`
+     * is set (toBlock is fixed at the SolutionDeliveryClaimed block), and is
+     * monotonically less likely to find the event when toBlock follows chain head
+     * (the window slides forward, away from any older Deliver event). Callers
+     * should prune the pending solution on `null` rather than retry — see #553.
+     */
     async deliveryEnvelopeCidForSolution(solution) {
         const deliveryMech = await getMarketplaceRequestDeliveryMech(this.publicClient, this.config.mechMarketplaceAddress, solution.requestId);
         const toBlock = solution.blockNumber != null
@@ -488,8 +669,7 @@ export class MechAdapter {
         const fromBlock = toBlock > lookback ? toBlock - lookback : 0n;
         const deliveryDataHex = await findLatestDeliveryDataHexForRequest(this.publicClient, deliveryMech, solution.requestId, fromBlock, toBlock);
         if (!deliveryDataHex) {
-            throw new Error(`No Deliver event data found for solution ${solution.requestId} on mech ${deliveryMech} ` +
-                `between blocks ${fromBlock} and ${toBlock}`);
+            return null;
         }
         const digest = deliveryDataHex.startsWith('0x') ? deliveryDataHex.slice(2) : deliveryDataHex;
         return `f01551220${digest}`;
@@ -500,14 +680,43 @@ export class MechAdapter {
             this.forgetPendingEvaluationSolution(solution.requestId);
             return undefined;
         }
-        const restoration = await this.restorationAnnouncementForTaskId(solution.taskId);
+        // Cheap claimability gate FIRST — before the restoration lookup + IPFS
+        // fetch. A backlog of terminal opportunities (finalized / evaluation
+        // deadline passed / max verdicts reached) must not pay the expensive
+        // restoration-announcement cost on every poll cycle. Terminal reasons are
+        // pruned from the working set so the loop never re-scans on-chain history;
+        // transient reasons are left in place to be retried next cycle.
         const claimable = await canClaimEvaluation(this.publicClient, this.config.safeAddress, this.config.routerAddress, solution.taskId, solution.attemptIndex, this.config.mechContractAddress);
         if (!claimable.ok) {
-            console.log(`[mech] skipping evaluation opportunity ${solution.requestId} for task ${solution.taskId}/${solution.attemptIndex}: ${claimable.reason}`);
-            this.forgetPendingEvaluationSolution(solution.requestId);
+            const terminal = isTerminalEvaluationReason(claimable.revertName);
+            console.log(`[mech] skipping evaluation opportunity ${solution.requestId} for task ${solution.taskId}/${solution.attemptIndex}: ${claimable.reason}` +
+                (terminal ? ' (terminal — pruned)' : ' (transient — will retry)'));
+            if (terminal) {
+                this.pruneTerminalEvaluationOpportunity({
+                    solutionRequestId: solution.requestId,
+                    reason: claimable.reason,
+                });
+            }
+            else {
+                // #645 backstop: bound retries on transient/unclassified claimability
+                // failures so a wedged opportunity can't log-spam forever.
+                this.recordEvaluationFailureAndMaybePrune(solution);
+            }
             return undefined;
         }
+        const restoration = await this.restorationAnnouncementForTaskId(solution.taskId);
         const solutionEnvelopeCid = await this.deliveryEnvelopeCidForSolution(solution);
+        if (solutionEnvelopeCid == null) {
+            // #553: Deliver event is not within the configured lookback window. A
+            // retry with the same toBlock cannot reach an older event, so this is
+            // terminal — prune so the loop never re-pays the canClaimEvaluation +
+            // restoration lookup cost on a deterministically-failing opportunity.
+            this.pruneTerminalEvaluationOpportunity({
+                solutionRequestId: solution.requestId,
+                reason: `no Deliver event found within configured lookback for task ${solution.taskId}/${solution.attemptIndex}`,
+            });
+            return undefined;
+        }
         const resultPayload = await fetchFromIpfs(this.config.ipfsGatewayUrl, solutionEnvelopeCid);
         const resultData = resultPayload.data ?? JSON.stringify(resultPayload);
         const evaluationTask = this.buildEvaluationTask({
@@ -532,21 +741,39 @@ export class MechAdapter {
             task: evaluationTask,
         });
         this.observedTasks.set(opportunityId, announcement);
+        // #645: a successful announcement means the candidate has made progress;
+        // reset the transient-failure counter so that subsequent transient errors
+        // (e.g. IPFS hiccups in the announce → claim window) don't accumulate
+        // across the candidate's lifetime and silently false-prune legitimate work.
+        if (solution.failedAttempts) {
+            solution.failedAttempts = 0;
+            this.persistPendingEvaluationSolutions();
+        }
         return announcement;
     }
     async *retryPendingEvaluationSolutions() {
+        let processed = 0;
         for (const [requestId, solution] of Array.from(this.pendingEvaluationSolutions)) {
+            // Yield to the event loop periodically so a large backlog of pending
+            // evaluation solutions can't starve the HTTP API mid-cycle.
+            if (processed > 0 && processed % EVALUATION_RETRY_YIELD_EVERY === 0) {
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+            processed++;
             try {
                 const announcement = await this.evaluationAnnouncementForSolution(solution);
                 if (announcement) {
                     yield announcement;
                 }
-                else {
-                    this.forgetPendingEvaluationSolution(requestId);
-                }
+                // No announcement does NOT mean "forget" — pruning is owned by
+                // evaluationAnnouncementForSolution, which only removes terminal cases.
             }
             catch (err) {
                 console.error(`[mech] evaluation opportunity retry failed for ${requestId}:`, err);
+                // #645 backstop: bound retries on any uncaught failure so a wedged
+                // requestId (e.g. an RPC failure path that re-throws every cycle)
+                // can't log-spam forever.
+                this.recordEvaluationFailureAndMaybePrune(solution);
             }
         }
     }
@@ -576,7 +803,7 @@ export class MechAdapter {
                     for (const { taskId, taskCidDigest, manifestDigest, transactionHash, blockNumber } of createdTasks) {
                         if (!this.isDiscoveryTaskAllowed(taskId))
                             continue;
-                        if (this.claimedRestorationTaskIds.has(taskId) || this.observedTasks.has(taskId))
+                        if (this.observedTasks.has(taskId))
                             continue;
                         if (joinedManifestDigests.size > 0 && !joinedManifestDigests.has(manifestDigest.toLowerCase()))
                             continue;
@@ -605,7 +832,7 @@ export class MechAdapter {
                 console.error('[mech] Error polling for tasks:', formatRpcError(err, {
                     operation: 'pollTaskCreated',
                     chain: this.config.chainId === 84532 ? 'base-sepolia' : 'base',
-                    rpcUrl: this.config.rpcUrl,
+                    rpcUrl: rpcUrlForDisplay(this.config.rpcUrl),
                     contract: this.config.routerAddress,
                     fromBlock: this.requestBlockCursor + 1n,
                 }));
@@ -619,7 +846,7 @@ export class MechAdapter {
             const signedEvaluationTask = await this.signTaskDocument(evaluationOpportunity.task);
             const evaluationCid = await uploadToIpfs(this.config.ipfsRegistryUrl, signedEvaluationTask);
             const evaluationTaskCidDigest = cidToDigestHex(evaluationCid);
-            const claimed = await this.claimEvaluation(evaluationOpportunity.taskId, evaluationOpportunity.attemptIndex, evaluationTaskCidDigest);
+            const claimed = await this.claimEvaluationWithTerminalPrune(taskId, evaluationOpportunity, evaluationTaskCidDigest);
             this.pendingEvaluations.set(claimed.requestId, evaluationOpportunity.task);
             this.originalStates.set(claimed.requestId, evaluationOpportunity.task);
             this.requestKinds.set(claimed.requestId, 'verdict');
@@ -644,7 +871,6 @@ export class MechAdapter {
         }
         const claimed = await claimTaskOnchain(this.publicClient, this.walletClient, this.config.safeAddress, this.config.routerAddress, taskId, this.config.mechContractAddress, this.config.evictionRecovery);
         const task = announcement.task;
-        this.claimedRestorationTaskIds.add(claimed.taskId);
         this.pendingEvaluations.set(claimed.requestId, task);
         this.originalStates.set(claimed.requestId, { ...task, role: task.role ?? 'restoration' });
         this.requestKinds.set(claimed.requestId, 'solution');
@@ -676,9 +902,13 @@ export class MechAdapter {
     async submitVerdictDelivery(requestId, verdictDigest, verdictCode) {
         await claimDelivery(this.publicClient, this.walletClient, this.config.safeAddress, this.config.routerAddress, requestId, { variant: 'v3', kind: 'verdict', evidenceHash: verdictDigest, verdictCode }, this.config.evictionRecovery);
     }
-    async evidenceHashForDelivery(requestId, deliveryDataHex) {
+    async deliveryClaimForDelivery(requestId, deliveryDataHex) {
+        const fallbackKind = this.requestKinds.get(requestId) ?? 'solution';
         if (this.config.routerClaimDeliveryVariant !== 'v2' && this.config.routerClaimDeliveryVariant !== 'v3') {
-            return undefined;
+            return {
+                evidenceHash: undefined,
+                kind: fallbackKind,
+            };
         }
         const deliveryDigest = deliveryDataHex.startsWith('0x')
             ? deliveryDataHex.slice(2)
@@ -686,11 +916,6 @@ export class MechAdapter {
         const envelopeCid = `f01551220${deliveryDigest}`;
         const rawEnvelope = await fetchSignedEnvelopeFromIpfs(this.config.ipfsGatewayUrl, envelopeCid);
         const parsed = SignedEnvelopeSchema.parse(rawEnvelope);
-        // Strip signature to recompute the hash over the unsigned body.
-        //
-        // Important: compute over the fetched wire object, not over the parsed
-        // schema result. The schema normalizes some nested objects and may strip
-        // extension metadata that was present when the envelope was signed.
         const rawSigned = rawEnvelope;
         const { signature: _rawSignature, ...unsignedBody } = rawSigned;
         const signature = parsed.signature;
@@ -699,22 +924,36 @@ export class MechAdapter {
         if (recomputed !== signature.hash) {
             throw new Error(`recomputed hash ${recomputed} !== envelope.signature.hash ${signature.hash}`);
         }
-        return recomputed;
+        const role = normalizeEnvelopeRole(parsed.role);
+        if (role === 'capture') {
+            throw new Error(`unsupported delivery envelope role=capture for requestId ${requestId}`);
+        }
+        const kind = role === 'verdict' ? 'verdict' : 'solution';
+        const payload = rawSigned['payload'];
+        const rawVerdict = payload != null && typeof payload === 'object'
+            ? payload['verdict']
+            : undefined;
+        return {
+            evidenceHash: recomputed,
+            kind,
+            verdictCode: kind === 'verdict' ? verdictCodeFromValue(rawVerdict) : undefined,
+        };
     }
     async ensureDeliveryClaimed(requestId, deliveryDataHex) {
-        let evidenceHash;
+        let claimOptions;
         try {
-            evidenceHash = await this.evidenceHashForDelivery(requestId, deliveryDataHex);
+            claimOptions = await this.deliveryClaimForDelivery(requestId, deliveryDataHex);
         }
         catch (err) {
-            console.error(`[mech] evidenceHash derivation failed for ${requestId} — skipping claim, will retry on next loop:`, err);
+            console.error(`[mech] delivery claim metadata derivation failed for ${requestId} — skipping claim, will retry on next loop:`, err);
             return 'retry';
         }
         try {
             await claimDelivery(this.publicClient, this.walletClient, this.config.safeAddress, this.config.routerAddress, requestId, {
                 variant: this.config.routerClaimDeliveryVariant,
-                kind: this.requestKinds.get(requestId) ?? 'solution',
-                evidenceHash,
+                kind: claimOptions.kind,
+                evidenceHash: claimOptions.evidenceHash,
+                verdictCode: claimOptions.verdictCode,
             }, this.config.evictionRecovery);
             return 'claimed';
         }
@@ -728,22 +967,66 @@ export class MechAdapter {
                 return 'already-claimed';
             }
             console.error(`[mech] claimDelivery failed for ${requestId}:`, err);
+            // Paired SSE signal for the operator-app `claim_failed` notification
+            // (OPERATOR-APP-SPEC §2.10). The early-return branches above
+            // (`skipped` / `already-claimed`) are not failures and intentionally do not emit.
+            emitStructured({
+                kind: 'intent',
+                message: 'Delivery claim failed',
+                requestId,
+                errorCode: 'claim_failed',
+                details: {
+                    kind: claimOptions.kind,
+                    source: 'mech.claimDelivery',
+                    error: message,
+                },
+            });
             return 'retry';
         }
     }
+    /**
+     * Paginate `getLogs` over `[deliveryBlockCursor+1, currentBlock]` chunked by
+     * `DEFAULT_ROUTER_LOG_CHUNK_BLOCKS` to honor RPC provider block-range limits
+     * (Tenderly base-sepolia caps at 100k; sepolia.base.org ~1k). Advances +
+     * persists `deliveryBlockCursor` per chunk so a mid-scan RPC failure on a
+     * later chunk does not strand the cursor at the pre-poll value (#552).
+     *
+     * Yields each chunk's decoded Deliver entries so the consumer can process
+     * them with the live "current block" context (needed for the recovery-
+     * delivery timestamp cache).
+     */
+    async *scanDeliveryLogChunks(currentBlock) {
+        while (currentBlock > this.deliveryBlockCursor) {
+            const chunkStart = this.deliveryBlockCursor + 1n;
+            const chunkEnd = chunkStart + DEFAULT_ROUTER_LOG_CHUNK_BLOCKS > currentBlock
+                ? currentBlock
+                : chunkStart + DEFAULT_ROUTER_LOG_CHUNK_BLOCKS;
+            const logs = await this.publicClient.getLogs({
+                address: this.config.mechContractAddress,
+                fromBlock: chunkStart,
+                toBlock: chunkEnd,
+            });
+            // Advance + persist BEFORE yielding so partial progress is durable even
+            // if a downstream throw escapes back through the for-await consumer.
+            this.deliveryBlockCursor = chunkEnd;
+            if (this.store) {
+                this.store.setLastProcessedBlock(this.deliveryBlockCursor);
+            }
+            yield decodeDeliverLogs(logs);
+        }
+    }
     async *watchForDeliveries() {
         while (!this.stopped) {
             try {
                 const currentBlock = await this.publicClient.getBlockNumber();
-                if (currentBlock > this.deliveryBlockCursor) {
-                    const logs = await this.publicClient.getLogs({
-                        address: this.config.mechContractAddress,
-                        fromBlock: this.deliveryBlockCursor + 1n,
-                        toBlock: currentBlock,
-                    });
-                    this.deliveryBlockCursor = currentBlock;
-                    const decoded = decodeDeliverLogs(logs);
-                    for (const { requestId, deliveryDataHex, mechAddress } of decoded) {
+                // Caches scoped to the whole poll iteration: the "current block"
+                // reference does not change across chunks.
+                const blockTimestampSecondsByNumber = new Map();
+                let currentBlockTimestampSeconds;
+                for await (const decoded of this.scanDeliveryLogChunks(currentBlock)) {
+                    if (this.stopped)
+                        break;
+                    for (const { requestId, deliveryDataHex, mechAddress, blockNumber } of decoded) {
                         // Two concerns, independent:
                         //   (a) Did this Safe DELIVER this? → claim it (counter credit goes to msg.sender)
                         //       The Deliver event's mechAddress is mechServiceMultisig (the Safe that owns
@@ -753,6 +1036,30 @@ export class MechAdapter {
                         const iCreatedRestoration = this.pendingEvaluations.has(requestId);
                         if (!iDelivered && !iCreatedRestoration)
                             continue;
+                        if (iCreatedRestoration) {
+                            const recoveryExpirySeconds = this.recoveryDeliveryExpirySeconds(requestId);
+                            if (recoveryExpirySeconds != null) {
+                                let deliveryTimestampSeconds;
+                                if (blockNumber != null) {
+                                    deliveryTimestampSeconds = blockTimestampSecondsByNumber.get(blockNumber);
+                                    if (deliveryTimestampSeconds == null) {
+                                        const deliveryBlockData = await this.publicClient.getBlock({ blockNumber });
+                                        deliveryTimestampSeconds = Number(deliveryBlockData.timestamp);
+                                        blockTimestampSecondsByNumber.set(blockNumber, deliveryTimestampSeconds);
+                                    }
+                                }
+                                else {
+                                    if (currentBlockTimestampSeconds == null) {
+                                        const currentBlockData = await this.publicClient.getBlock({ blockNumber: currentBlock });
+                                        currentBlockTimestampSeconds = Number(currentBlockData.timestamp);
+                                    }
+                                    deliveryTimestampSeconds = currentBlockTimestampSeconds;
+                                }
+                                if (this.shouldSkipExpiredRecoveryDelivery(requestId, deliveryTimestampSeconds, recoveryExpirySeconds)) {
+                                    continue;
+                                }
+                            }
+                        }
                         // (a) Deliverer-side claim path: if this Safe delivered the request,
                         //     claim it first so router counters credit the deliverer.
                         let deliveryClaimStatus;
@@ -788,9 +1095,7 @@ export class MechAdapter {
                                 deliveryMechAddress: mechAddress,
                             };
                             // Clean up after yielding
-                            this.originalStates.delete(requestId);
-                            this.pendingEvaluations.delete(requestId);
-                            this.requestKinds.delete(requestId);
+                            this.clearPendingDeliveryRecoveryState(requestId);
                         }
                         catch (err) {
                             console.error(`[mech] Failed to parse delivery ${requestId}:`, err);
@@ -802,15 +1107,13 @@ export class MechAdapter {
                 console.error('[mech] Error polling for deliveries:', formatRpcError(err, {
                     operation: 'pollDeliveries',
                     chain: this.config.chainId === 84532 ? 'base-sepolia' : 'base',
-                    rpcUrl: this.config.rpcUrl,
+                    rpcUrl: rpcUrlForDisplay(this.config.rpcUrl),
                     contract: this.config.mechContractAddress,
                     fromBlock: this.deliveryBlockCursor + 1n,
                 }));
             }
-            // Persist block cursor for crash recovery
-            if (this.store && this.deliveryBlockCursor > 0n) {
-                this.store.setLastProcessedBlock(this.deliveryBlockCursor);
-            }
+            // Cursor persistence is per-chunk inside the loop above (#552). A poll
+            // that did no chunked work has no progress to persist.
             await new Promise(r => setTimeout(r, this.config.pollIntervalMs));
         }
     }