@jinn-network/client 0.1.7 → 0.1.8-canary.026c5503

package/README.md

@@ -312,7 +312,7 @@ JINN_PASSWORD=secret jinn run --config ./my-config.json
 | Config key | Env override | Default |
 |---|---|---|
 | network | JINN_NETWORK | `testnet` (Phase 1b default; flips to `mainnet` at Phase 2 launch) |
-| rpcUrl | BASE_RPC_URL / JINN_RPC_URL | network-appropriate public RPC |
+| rpcUrl | BASE_RPC_URL / JINN_RPC_URL | testnet: two-provider fallback chain `[publicnode, sepolia.base.org]`; mainnet: single `mainnet.base.org`. Accepts string OR array; env values split on commas. See "RPC fallback chain" below. |
 | claudeModel | JINN_CLAUDE_MODEL | claude-haiku-4-5-20251001 |
 | claudePath | JINN_CLAUDE_PATH | claude |
 | pollIntervalMs | JINN_POLL_INTERVAL_MS | 5000 |
@@ -325,6 +325,72 @@ JINN_PASSWORD=secret jinn run --config ./my-config.json
 
 `JINN_PASSWORD` is env-only (keystore encryption, never in config files). Alternatively, use `--password-fd <N>` to read from a file descriptor.
 
+### RPC fallback chain
+
+Out of the box on testnet, `jinn run` uses a two-provider fallback chain —
+no key required, zero config:
+
+```text
+slot 0  https://base-sepolia.publicnode.com   (no-auth, 50k-block getLogs cap)
+slot 1  https://sepolia.base.org              (free public Coinbase, 2k cap)
+```
+
+If the primary returns a network error or HTTP 429 / 5xx, viem
+transparently falls through to the next slot. When every slot fails the
+daemon throws `AllRpcsFailedError` (visible in the dashboard's NetworkSection
+and in stderr).
+
+#### Bring your own paid primary
+
+Operators with a paid Alchemy / Tenderly / QuickNode endpoint should
+**prepend** their URL — the public free chain stays as automatic backup:
+
+```json
+{
+  "rpcUrl": [
+    "https://my-alchemy-key.example",
+    "https://base-sepolia.publicnode.com",
+    "https://sepolia.base.org"
+  ]
+}
+```
+
+Or via env (comma-separated, same chain capped at 4 providers):
+
+```bash
+JINN_RPC_URL='https://my-alchemy-key.example,https://base-sepolia.publicnode.com,https://sepolia.base.org' jinn run
+```
+
+The chain is built with viem's `fallback({ rank: false })` so operator slot
+order is preserved (no latency-based reshuffling).
+
+#### Automatic failure modes
+
+| Failure                                     | What used to happen           | What now happens                                |
+|---------------------------------------------|--------------------------------|-------------------------------------------------|
+| Primary RPC returns HTTP 429 (rate limit)   | Daemon hot-loops on every call | viem falls through to slot 1; daemon continues  |
+| Primary RPC unreachable                     | Daemon errors silently         | viem falls through to slot 1; daemon continues  |
+| Primary's API key quota exhausted           | Daemon silently degraded       | viem falls through to slot 1; daemon continues  |
+| Every slot fails (rare)                     | Daemon errors silently         | `AllRpcsFailedError` thrown with masked host list — surfaces as a state message in the operator app |
+
+On boot the daemon emits one log line per slot followed by the canonical
+summary line:
+
+```text
+[rpc] L2 base-sepolia.publicnode.com ok latency=87ms
+[rpc] L2 sepolia.base.org ok latency=141ms
+[rpc] L2 transport: fallback chain (2 providers) — primary=base-sepolia.publicnode.com
+```
+
+The probe is **log-only** — secondary-slot 429s warn but never gate
+startup. Only chain-id mismatch against the head URL is fail-loud
+(`checkRpcNetwork`).
+
+Note this is the JSON-RPC transport layer. It is distinct from
+`discovery.fallbackToOnchain`, which is a separate flag at the read-API
+layer (Ponder indexer → direct `eth_getLogs` floor). The RPC fallback chain
+operates beneath both.
+
 ## Tokens
 
 | Role | Phase 1b (testnet, Base Sepolia) | Phase 2 (mainnet, Base) |

package/dist/adapters/mech/adapter.d.ts

@@ -45,7 +45,6 @@ export declare class MechAdapter implements ExecutionAdapter {
      */
     private restorationBodyCache;
     private requestKinds;
-    private claimedRestorationTaskIds;
     private evaluationOpportunities;
     private pendingEvaluationSolutions;
     private originalStates;
@@ -53,7 +52,26 @@ export declare class MechAdapter implements ExecutionAdapter {
     constructor(config: MechAdapterConfig, store?: Store);
     initialize(): Promise<void>;
     private recoverPendingState;
-    private onchainTaskDiscoveryFromBlock;
+    /**
+     * The gh #300 scorability admission floor: tasks created before this block are
+     * "ghosts" from a prior eval-semantics regime and are rejected — including on
+     * the `DiscoveryAPI` (indexer) path. Fixed per chain; an explicit operator
+     * `onchainFromBlock` raises it. Returns `undefined` when no SolverNet is joined
+     * (the daemon claims nothing, so there is no floor to apply).
+     *
+     * This is deliberately NOT the on-chain scan start — see `onchainScanFromBlock`.
+     * Bounding the scan for RPC cost must never narrow which tasks are admitted.
+     */
+    private taskAdmissionFloorBlock;
+    /**
+     * Start block for the on-chain TaskCreated backlog scan (the secondary backstop
+     * behind `DiscoveryAPI.findClaimableTasks`). Defaults to a bounded rolling
+     * window `head − DEFAULT_ONCHAIN_SCAN_WINDOW_BLOCKS`, never below the admission
+     * floor (scanning pre-floor blocks only surfaces rejected ghosts). An explicit
+     * `onchainFromBlock` override pins an absolute start, honored as the operator's
+     * choice. Returns `undefined` when no SolverNet is joined.
+     */
+    private onchainScanFromBlock;
     private joinedManifestDigestSet;
     private allowedDiscoveryTaskIds;
     private isDiscoveryTaskAllowed;
@@ -62,6 +80,25 @@ export declare class MechAdapter implements ExecutionAdapter {
     private persistPendingEvaluationSolutions;
     private rememberPendingEvaluationSolution;
     private forgetPendingEvaluationSolution;
+    /**
+     * 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).
+     */
+    private recordEvaluationFailureAndMaybePrune;
+    /** Prune terminal evaluation state so the poll loop stops retrying (#512). */
+    private pruneTerminalEvaluationOpportunity;
+    private claimEvaluationWithTerminalPrune;
     private clearPendingDeliveryRecoveryState;
     private recoveryDeliveryExpirySeconds;
     private shouldSkipExpiredRecoveryDelivery;

package/dist/adapters/mech/adapter.js

@@ -4,13 +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 { 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 { isNonRecoverableInnerRevert } from './safe-revert.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';
@@ -21,6 +31,19 @@ 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
@@ -41,6 +64,20 @@ function isTerminalEvaluationReason(revertName) {
     return isNonRecoverableInnerRevert(revertName);
 }
 const DEFAULT_ROUTER_LOG_CHUNK_BLOCKS = 9999n;
+/**
+ * Default rolling-window size for the on-chain TaskCreated backlog scan (#801).
+ *
+ * The scan is a *backstop* behind `DiscoveryAPI.findClaimableTasks` (the indexer
+ * on testnet, the newest-first RPC floor on mainnet), which is the primary
+ * discovery path on every chain. Without a bound the scan replays from the fixed
+ * admission floor to head on *every* restart, a range that grows monotonically
+ * with the chain — the startup-stall regression #801 documents. Bounding it to
+ * `head − N` makes restart cost fixed regardless of chain age while still
+ * re-observing a generous recent window (~28h on Base at ~2s/block) for tasks
+ * and SolutionDeliveryClaimed events the indexer might have lagged on. Operators
+ * who want a wider net pin an absolute start via `taskDiscoveryOnchainFromBlock`.
+ */
+const DEFAULT_ONCHAIN_SCAN_WINDOW_BLOCKS = 50000n;
 /**
  * Floor block for the on-chain TaskCreated backlog scan, per chain.
  *
@@ -117,7 +154,6 @@ export class MechAdapter {
      */
     restorationBodyCache = new Map();
     requestKinds = new Map();
-    claimedRestorationTaskIds = new Set();
     evaluationOpportunities = new Map();
     pendingEvaluationSolutions = new Map();
     // Original Tasks keyed by request ID (restoration and evaluation)
@@ -139,7 +175,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),
                     }));
             },
         });
@@ -151,7 +187,7 @@ export class MechAdapter {
             await this.recoverPendingState(blockNumber);
         }
         else {
-            const fromBlock = this.onchainTaskDiscoveryFromBlock();
+            const fromBlock = this.onchainScanFromBlock(blockNumber);
             if (fromBlock && fromBlock <= blockNumber) {
                 this.requestBlockCursor = fromBlock - 1n;
             }
@@ -171,17 +207,27 @@ export class MechAdapter {
         if (routerFromBlock < currentBlock) {
             this.requestBlockCursor = routerFromBlock;
         }
-        const scanFromBlock = this.onchainTaskDiscoveryFromBlock();
+        const scanFromBlock = this.onchainScanFromBlock(currentBlock);
         if (scanFromBlock && scanFromBlock <= currentBlock) {
             const canonicalCursor = scanFromBlock - 1n;
             if (canonicalCursor < this.requestBlockCursor) {
                 this.requestBlockCursor = canonicalCursor;
             }
-            console.error(`[mech] TaskCreated canonical backlog scan enabled from block ${scanFromBlock}; ` +
-                'subgraph discovery is optional acceleration only');
+            console.error(`[mech] TaskCreated backlog scan (bounded backstop) enabled from block ${scanFromBlock}; ` +
+                'DiscoveryAPI.findClaimableTasks is the primary discovery path');
         }
     }
-    onchainTaskDiscoveryFromBlock() {
+    /**
+     * The gh #300 scorability admission floor: tasks created before this block are
+     * "ghosts" from a prior eval-semantics regime and are rejected — including on
+     * the `DiscoveryAPI` (indexer) path. Fixed per chain; an explicit operator
+     * `onchainFromBlock` raises it. Returns `undefined` when no SolverNet is joined
+     * (the daemon claims nothing, so there is no floor to apply).
+     *
+     * This is deliberately NOT the on-chain scan start — see `onchainScanFromBlock`.
+     * Bounding the scan for RPC cost must never narrow which tasks are admitted.
+     */
+    taskAdmissionFloorBlock() {
         const discovery = this.config.taskDiscovery;
         const hasJoinedSolverNet = (discovery?.solverNetManifestCids?.length ?? 0) > 0;
         if (!hasJoinedSolverNet)
@@ -193,6 +239,24 @@ export class MechAdapter {
         }
         return DEFAULT_TASK_DISCOVERY_FROM_BLOCK[this.config.chainId];
     }
+    /**
+     * Start block for the on-chain TaskCreated backlog scan (the secondary backstop
+     * behind `DiscoveryAPI.findClaimableTasks`). Defaults to a bounded rolling
+     * window `head − DEFAULT_ONCHAIN_SCAN_WINDOW_BLOCKS`, never below the admission
+     * floor (scanning pre-floor blocks only surfaces rejected ghosts). An explicit
+     * `onchainFromBlock` override pins an absolute start, honored as the operator's
+     * choice. Returns `undefined` when no SolverNet is joined.
+     */
+    onchainScanFromBlock(head) {
+        const floor = this.taskAdmissionFloorBlock();
+        if (floor === undefined)
+            return undefined;
+        // An explicit override is reflected verbatim in `floor`; honor it as the pin.
+        if (this.config.taskDiscovery?.onchainFromBlock !== undefined)
+            return floor;
+        const window = head - DEFAULT_ONCHAIN_SCAN_WINDOW_BLOCKS;
+        return window > floor ? window : floor;
+    }
     joinedManifestDigestSet() {
         const cids = this.config.taskDiscovery?.solverNetManifestCids ?? [];
         return new Set(cids
@@ -249,6 +313,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);
             }
@@ -271,6 +342,61 @@ 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);
@@ -514,12 +640,10 @@ export class MechAdapter {
             console.error('[mech] task discovery (DiscoveryAPI) failed:', err instanceof Error ? err.message : err);
             return;
         }
-        const discoveryFloorBlock = this.onchainTaskDiscoveryFromBlock();
+        const discoveryFloorBlock = this.taskAdmissionFloorBlock();
         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
@@ -610,7 +734,15 @@ export class MechAdapter {
             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.forgetPendingEvaluationSolution(solution.requestId);
+                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;
         }
@@ -621,9 +753,10 @@ export class MechAdapter {
             // 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.
-            console.log(`[mech] pruning evaluation opportunity ${solution.requestId} for task ${solution.taskId}/${solution.attemptIndex}: ` +
-                `no Deliver event found within configured lookback (terminal — pruned)`);
-            this.forgetPendingEvaluationSolution(solution.requestId);
+            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);
@@ -650,6 +783,14 @@ 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() {
@@ -671,6 +812,10 @@ export class MechAdapter {
             }
             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);
             }
         }
     }
@@ -700,7 +845,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;
@@ -729,7 +874,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,
                 }));
@@ -743,7 +888,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');
@@ -768,7 +913,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');
@@ -865,6 +1009,20 @@ 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';
         }
     }
@@ -991,7 +1149,7 @@ 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,
                 }));