zk-credits 0.2.12 → 0.2.14

package/README.md

@@ -85,7 +85,7 @@ can observe traffic metadata. This does not hide your IP address.
 
 Base Sepolia test credits only. The circuit is not independently audited.
 
-### Coding-task evidence (0.2.12 candidate)
+### Coding-task evidence (0.2.14 candidate)
 
 After setup, `zk-credits codex --task-evidence` launches Codex against a fresh,
 dedicated local sidecar and prints aggregate payment counters when Codex exits.
@@ -100,10 +100,10 @@ zk-credits codex --task-evidence
 ```
 
 Enter your task, review the change and tests, then exit Codex to see the summary.
-Version 0.2.12 is prepared for owner publication; 0.2.11 lacks this command.
+Version 0.2.12 includes this command; 0.2.11 lacks it.
 See the [indexer sample](https://github.com/mangekyou-labs/haze-api/tree/main/examples/base-usdc-indexer).
 
-### Transaction investigator (0.2.12 candidate)
+### Transaction investigator (0.2.14 candidate)
 
 After closing Codex, run `zk-credits investigate --chain base <transaction-hash>`
 with the same configured credential. It fetches public execution evidence and
@@ -112,8 +112,19 @@ the investigated chain; credit funding remains on Base Sepolia and consumption
 is offchain. It does not purchase external traces. Keep missing-evidence notices
 visible and distinguish observed errors from model hypotheses.
 
-Repeating a transaction hash recovers its existing local task; it need not make
-a new paid call or return a complete report. Do not delete task journals or reset
+Version 0.2.14 fixes the investigator's packaged payment recipient pin and refuses
+builds with missing or placeholder treasury addresses. Payment requirements must
+still match the reviewed deployment before any proof is authorized.
+
+Repeating a transaction hash recovers its existing local task without authorizing
+a new paid call. The report shows the original stopping reason and labels prior
+accounting separately from current invocation counters, including when the saved
+run authorized no credits. Upgrading does not resume a stopped investigation.
+Do not delete task journals or reset
 credential accounting to force a fresh exchange. Unknown payment outcomes must
 be reconciled before another paid task. A saved report must be labeled as a prior
 run, with its own payment summary.
+
+`challengeObserved` counts challenges presented for authorization, including
+refused terms. A challenge alone does not imply a proof or consumed credit;
+check confirmed, failed, unknown and retired counters separately.

package/circuits/manifest.json

@@ -33,6 +33,7 @@
   "deployment": {
     "chainId": 84532,
     "bondAddress": "0xcc1909dD30485d6D9a46e3d33cf04C1378b586Ab",
+    "treasuryAddress": "0xa8b9b38e748563AF7FbAA276e8a843Da417D7Bc1",
     "deploymentBlock": "47372040",
     "deploymentDomain": "84532",
     "circuitId": "private-credit-spend-bn254-dev",

package/dist/activated-credential-setup.d.ts

@@ -0,0 +1,18 @@
+import { type CredentialStore } from './credential-store.js';
+import { type ResolveSetupInputsOptions, type SetupConfig } from './setup-config.js';
+export interface ActivatedCredentialSetupOptions {
+    environment?: NodeJS.ProcessEnv;
+    homeDirectory?: string;
+    stateDirectory?: string;
+    credentialStore?: CredentialStore;
+    chooseCandidate?: ResolveSetupInputsOptions['chooseCandidate'];
+    /** The caller owns hidden terminal input for explicit legacy import. */
+    readLegacyPassword?(): Promise<string>;
+}
+/**
+ * Imports or loads the credential and prepares validated runtime configuration.
+ * Configuration is saved only after all checks pass. Credential import, artifact
+ * acquisition and witness synchronization may persist progress on failure so a
+ * retry can reuse it. Applies RPC and successful setup paths to the environment.
+ */
+export declare function setupActivatedCredential(options?: ActivatedCredentialSetupOptions): Promise<SetupConfig>;

package/dist/activated-credential-setup.js

@@ -0,0 +1,64 @@
+/** Interactive credential preparation; runtime loading and launch remain separate. */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadCircuitManifest } from './artifact-bundle.js';
+import { validateBaseCreditWitness } from './base-sidecar.js';
+import { importCredentialPath, nativeCredentialStore, readStoredCredential, } from './credential-store.js';
+import { requireGatewayKnownRoot, resolveGatewayOrigin } from './gateway-root-check.js';
+import { createPinnedBaseProofGenerator } from './proof-coordinator.js';
+import { createBaseProofMetrics } from './proof-metrics.js';
+import { applyRpcConfig, checkBaseSepoliaRpc, resolveBaseSepoliaRpc } from './rpc-config.js';
+import { applySetupConfig, readSetupConfig, resolveSetupInputs, writeSetupConfig, } from './setup-config.js';
+import { witnessProviderForSource } from './sidecar-runtime.js';
+/**
+ * Imports or loads the credential and prepares validated runtime configuration.
+ * Configuration is saved only after all checks pass. Credential import, artifact
+ * acquisition and witness synchronization may persist progress on failure so a
+ * retry can reuse it. Applies RPC and successful setup paths to the environment.
+ */
+export async function setupActivatedCredential(options = {}) {
+    const environment = options.environment ?? process.env;
+    const homeDirectory = options.homeDirectory ?? homedir();
+    const stateDirectory = options.stateDirectory ?? (environment.ZK_CREDITS_HOME || join(homeDirectory, '.zk-credits'));
+    const configPath = join(stateDirectory, 'config.json');
+    const credentialStore = options.credentialStore ?? nativeCredentialStore(stateDirectory);
+    await applyRpcConfig(environment, stateDirectory);
+    const saved = await readSetupConfig(configPath);
+    const rpc = resolveBaseSepoliaRpc(environment, saved?.witness.kind === 'base-events' ? saved.witness.rpcUrl : undefined);
+    await checkBaseSepoliaRpc(rpc);
+    environment.BASE_RPC_URL = rpc;
+    const credentialPath = environment.ZK_CREDITS_CREDENTIAL_PATH;
+    const legacyPassword = await options.readLegacyPassword?.();
+    const credential = credentialPath
+        ? await importCredentialPath(credentialPath, credentialStore, legacyPassword)
+        : await readStoredCredential(credentialStore);
+    const manifest = await loadCircuitManifest();
+    const config = await resolveSetupInputs({
+        environment,
+        homeDirectory,
+        stateDirectory,
+        configPath,
+        manifest,
+        validateWitness: async (source) => {
+            const provider = await witnessProviderForSource(source, join(stateDirectory, 'base-event-sync.json'));
+            const witness = validateBaseCreditWitness(await provider.witnessForCredential(credential));
+            if (manifest.deployment)
+                await requireGatewayKnownRoot(witness.root, resolveGatewayOrigin(environment));
+        },
+        chooseCandidate: options.chooseCandidate,
+    });
+    try {
+        await createPinnedBaseProofGenerator({
+            artifactDirectory: config.artifactDirectory,
+            metrics: createBaseProofMetrics(),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw new Error(`Pinned proving bundle check failed: ${error.message}`);
+        throw new Error('Pinned proving bundle check failed. Reinstall the bundle from your pilot invite.');
+    }
+    await writeSetupConfig(configPath, config);
+    applySetupConfig(environment, config);
+    return config;
+}

package/dist/base-event-sync.js

@@ -13,6 +13,7 @@ import { baseSepolia } from 'viem/chains';
 import { createPublicClient, http, parseAbi } from 'viem';
 import { BASE_MEMBERSHIP_TREE_CAPACITY, BN254_FIELD_ORDER, computeCreditLeaf, deriveSparseCreditWitness, } from '@zk-credits/shared/base';
 import { RPC_GUIDANCE } from './rpc-config.js';
+import { rpcFetch } from './rpc-transport.js';
 const BUNDLE_FUNDED_ABI = parseAbi([
     'event BundleFunded(bytes32 indexed commitment, uint8 indexed tierId, uint64 expiry, uint256 leafIndex, uint256 bondAmount, bytes32 root)',
 ]);
@@ -82,12 +83,15 @@ function serializeLeaves(leaves) {
 }
 /** Creates a witness provider that syncs finalized BundleFunded events. */
 export function createBaseEventWitnessProvider(options) {
-    const client = options.client ?? createPublicClient({ chain: baseSepolia, transport: http(options.rpcUrl) });
+    const client = options.client ?? createPublicClient({ chain: baseSepolia,
+        transport: http(options.rpcUrl, { fetchFn: rpcFetch, retryCount: 0, timeout: 30_000 }),
+    });
     const contract = address(options.contractAddress);
     const confirmations = options.confirmations ?? 3n;
     const maxBlockRange = options.maxBlockRange ?? 2000n;
     let cache;
     let leaves = new Map();
+    let pendingSync;
     async function rpcCall(operation) {
         try {
             return await operation;
@@ -150,7 +154,8 @@ export function createBaseEventWitnessProvider(options) {
     }
     return {
         async witnessForCredential(credential) {
-            await synchronize();
+            pendingSync ??= synchronize().finally(() => { pendingSync = undefined; });
+            await pendingSync;
             const commitment = field(credential.commitment, 'credential commitment');
             const entry = [...leaves.entries()].find(([, value]) => value.commitment === commitment);
             if (!entry)

package/dist/cli.js

@@ -1,33 +1,30 @@
 #!/usr/bin/env node
 import { homedir } from 'node:os';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { codingTaskEvidence, codingTaskProviderArgs, validateCodingTaskArgs } from './task-evidence.js';
 import { launchCodexProcess } from './codex-launcher.js';
 import { launchClineProcess } from './cline-launcher.js';
 import { isCodexProfileInstalled, resolveCodexHome, writeCodexProfile, } from './codex-profile.js';
-import { validateBaseCreditWitness } from './base-sidecar.js';
-import { createSidecarRuntime, RuntimeCredentialError, witnessProviderForSource } from './sidecar-runtime.js';
+import { createSidecarRuntime, RuntimeCredentialError } from './sidecar-runtime.js';
+import { setupActivatedCredential } from './activated-credential-setup.js';
 import { createLocalX402Agent } from './local-x402-agent.js';
-import { createPinnedBaseProofGenerator } from './proof-coordinator.js';
-import { createBaseProofMetrics } from './proof-metrics.js';
-import { nativeCredentialStore, importCredentialPath, readStoredCredential } from './credential-store.js';
-import { applyRpcConfig, checkBaseSepoliaRpc, writeRpcConfig, RPC_GUIDANCE, resolveBaseSepoliaRpc } from './rpc-config.js';
+import { nativeCredentialStore } from './credential-store.js';
+import { applyRpcConfig, checkBaseSepoliaRpc, writeRpcConfig, RPC_GUIDANCE } from './rpc-config.js';
 import { diagnoseSidecar, stopSidecar } from './sidecar-diagnostics.js';
 import { runCliCommand } from './cli-runtime.js';
 import { createNodeSidecarLifecycle } from './node-sidecar-lifecycle.js';
 import { activateSidecarServer } from './server-startup.js';
 import { createLoopbackToken, sidecarStatePaths } from './sidecar-config.js';
-import { applySetupConfig, readSetupConfig, resolveSetupInputs, writeSetupConfig, } from './setup-config.js';
+import { applySetupConfig, readSetupConfig, } from './setup-config.js';
 import { ensureSidecarReady } from './sidecar-lifecycle.js';
 import { readLoopbackToken, writeLoopbackToken } from './sidecar-state.js';
 import { createSidecarServer } from './sidecar.js';
 import { buildBaseRegisteredTrialRequestBody } from './base-registered-trial.js';
-import { loadCircuitManifest } from './artifact-bundle.js';
 import { BASE_SEPOLIA_NETWORK } from '@zk-credits/x402-zk-prepaid';
-import { requireGatewayKnownRoot as checkGatewayKnownRoot } from './gateway-root-check.js';
+import { DEFAULT_GATEWAY_URL, resolveGatewayOrigin } from './gateway-root-check.js';
 import { evaluateGatewayReadiness, isGatewayStatusFresh } from './gateway-trial-status.js';
-const DEFAULT_GATEWAY_URL = 'https://zk-credits-gateway.onrender.com';
 const DEFAULT_PORT = 3210;
 function stateDirectory() {
     return process.env.ZK_CREDITS_HOME || join(homedir(), '.zk-credits');
@@ -120,6 +117,7 @@ async function readHiddenValue(prompt) {
 }
 function printHelp() {
     console.log(`Usage:
+  zk-credits --version
   zk-credits cline [cline arguments...]
   zk-credits config rpc
   zk-credits setup [codex|x402] [--legacy] [--model <model>]
@@ -200,11 +198,7 @@ function safeCount(value) {
     return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
 }
 function gatewayOrigin() {
-    const origin = new URL(process.env.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL);
-    if (origin.protocol !== 'https:' || origin.username || origin.password || origin.search || origin.hash || origin.pathname !== '/') {
-        throw new Error('The internal trial requires a plain HTTPS gateway origin');
-    }
-    return origin;
+    return resolveGatewayOrigin(process.env);
 }
 async function readGatewayJson(url, headers) {
     try {
@@ -222,9 +216,6 @@ async function readGatewayJson(url, headers) {
         return { status: null };
     }
 }
-async function requireGatewayKnownRoot(root) {
-    await checkGatewayKnownRoot(root, gatewayOrigin());
-}
 async function gatewayReadiness(origin) {
     const response = await readGatewayJson(new URL('/ready', origin), { accept: 'application/json' });
     const gate = evaluateGatewayReadiness(response.status, response.body);
@@ -591,6 +582,11 @@ async function runCodingTask(args) {
 }
 async function main() {
     const args = process.argv.slice(2);
+    if (args[0] === '--version' || args[0] === '-v') {
+        const metadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        console.log(metadata.version);
+        return;
+    }
     const localHelp = ['doctor', 'stop', 'status', 'serve', 'setup', 'config', 'investigate'].includes(args[0] ?? '')
         && args.slice(1).some((arg) => arg === '--help' || arg === '-h');
     if (args[0] === '--help' || args[0] === '-h' || !args[0] || localHelp) {
@@ -670,45 +666,14 @@ async function main() {
             return Boolean(await credentialStore.read());
         },
         validateSetupPrerequisites: async () => {
-            await applyRpcConfig(process.env, sidecarHome);
-            const saved = await readSetupConfig(setupConfigPath(sidecarHome));
-            const rpc = resolveBaseSepoliaRpc(process.env, saved?.witness.kind === 'base-events' ? saved.witness.rpcUrl : undefined);
-            await checkBaseSepoliaRpc(rpc);
-            process.env.BASE_RPC_URL = rpc;
-            const credentialPath = process.env.ZK_CREDITS_CREDENTIAL_PATH;
-            const legacyPassword = args.includes('--legacy') ? await readHiddenValue('Legacy export password: ') : undefined;
-            const credential = credentialPath
-                ? await importCredentialPath(credentialPath, credentialStore, legacyPassword)
-                : await readStoredCredential(credentialStore);
-            const manifest = await loadCircuitManifest();
-            const config = await resolveSetupInputs({
+            await setupActivatedCredential({
                 environment: process.env,
                 homeDirectory: homedir(),
                 stateDirectory: sidecarHome,
-                configPath: setupConfigPath(sidecarHome),
-                manifest,
-                validateWitness: async (source) => {
-                    const provider = await witnessProviderForSource(source, join(stateDirectory(), 'base-event-sync.json'));
-                    const witness = validateBaseCreditWitness(await provider.witnessForCredential(credential));
-                    if (manifest.deployment)
-                        await requireGatewayKnownRoot(witness.root);
-                },
+                credentialStore,
                 chooseCandidate: chooseSetupCandidate,
+                ...(args.includes('--legacy') ? { readLegacyPassword: () => readHiddenValue('Legacy export password: ') } : {}),
             });
-            const artifactDirectory = config.artifactDirectory;
-            try {
-                await createPinnedBaseProofGenerator({
-                    artifactDirectory,
-                    metrics: createBaseProofMetrics(),
-                });
-            }
-            catch (error) {
-                if (error instanceof Error)
-                    throw new Error(`Pinned proving bundle check failed: ${error.message}`);
-                throw new Error('Pinned proving bundle check failed. Reinstall the bundle from your pilot invite.');
-            }
-            await writeSetupConfig(setupConfigPath(sidecarHome), config);
-            applySetupConfig(process.env, config);
             console.log('Pinned proving bundle and witness validated for this activated credential.');
             console.log('Local setup paths saved to ' + setupConfigPath(sidecarHome));
         },

package/dist/gateway-root-check.d.ts

@@ -1,2 +1,5 @@
+export declare const DEFAULT_GATEWAY_URL = "https://zk-credits-gateway.onrender.com";
+/** Shared gateway origin validation for setup and the internal trial. */
+export declare function resolveGatewayOrigin(environment: NodeJS.ProcessEnv): URL;
 /** Public setup check. It sends the public root only and never needs an admin credential. */
 export declare function requireGatewayKnownRoot(root: string, origin: URL, fetcher?: typeof fetch): Promise<void>;

package/dist/gateway-root-check.js

@@ -1,28 +1,60 @@
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+export const DEFAULT_GATEWAY_URL = 'https://zk-credits-gateway.onrender.com';
+/** Shared gateway origin validation for setup and the internal trial. */
+export function resolveGatewayOrigin(environment) {
+    const origin = new URL(environment.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL);
+    if (origin.protocol !== 'https:' || origin.username || origin.password || origin.search || origin.hash || origin.pathname !== '/') {
+        throw new Error('The internal trial requires a plain HTTPS gateway origin');
+    }
+    return origin;
+}
 /** Public setup check. It sends the public root only and never needs an admin credential. */
 export async function requireGatewayKnownRoot(root, origin, fetcher = fetch) {
-    let response;
-    try {
-        response = await fetcher(new URL('/v1/root-known', origin), {
-            method: 'POST',
-            headers: { accept: 'application/json', 'content-type': 'application/json' },
-            body: JSON.stringify({ root }),
-            signal: AbortSignal.timeout(10_000),
-        });
-    }
-    catch {
-        throw new Error('The gateway could not confirm that the activated credential root is known');
-    }
-    let body;
-    try {
-        body = await response.json();
-    }
-    catch {
-        body = undefined;
-    }
-    if (response.status !== 200 || !isRecord(body) || body.known !== true) {
-        throw new Error('The activated credential root is not in the gateway known-root set; stop setup and reconcile the V2 activation');
+    const deadline = AbortSignal.timeout(60_000);
+    for (let attempt = 0; attempt < 3 && !deadline.aborted; attempt += 1) {
+        let response;
+        let body;
+        try {
+            response = await fetcher(new URL('/v1/root-known', origin), {
+                method: 'POST',
+                headers: { accept: 'application/json', 'content-type': 'application/json' },
+                body: JSON.stringify({ root }),
+                signal: AbortSignal.any([deadline, AbortSignal.timeout(30_000)]),
+            });
+            if (response.status === 200)
+                body = await response.json();
+        }
+        catch { /* Reachability/body failures remain uncertain, never unknown. */ }
+        if (response?.status === 200 && isRecord(body) && body.known === true)
+            return;
+        if (response?.status === 200 && isRecord(body) && body.known === false) {
+            throw new Error('The activated credential root is not in the gateway known-root set; stop setup and reconcile the V2 activation');
+        }
+        if (response && ![429, 500, 502, 503, 504].includes(response.status))
+            break;
+        if (attempt === 2)
+            break;
+        const retry = response?.headers.get('Retry-After');
+        const providerDelay = retry ? (/^\d+$/u.test(retry) ? Number(retry) * 1000 : Date.parse(retry) - Date.now()) : 0;
+        const delay = Math.max(500 * 2 ** attempt, Number.isFinite(providerDelay) ? providerDelay : 0);
+        await response?.body?.cancel().catch(() => { });
+        try {
+            await waitForGateway(delay, deadline);
+        }
+        catch {
+            break;
+        }
     }
+    throw new Error('The gateway is temporarily unavailable and could not confirm the activated credential root. Retry zk-credits setup codex; changing the local RPC does not change the gateway connection.');
+}
+function waitForGateway(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); reject(signal.reason); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve(); }, ms);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
 }

package/dist/investigator.mjs

@@ -2450,7 +2450,7 @@ async function persistJournal(stateDir, journalPath, nextRecords) {
 }
 
 // ../../examples/base-transaction-investigator/.generated/live-defaults.mjs
-var LIVE_DEFAULTS = { "build": "14533b1ebbca1bf21194fd289539ab08dbaeac711c2e6f2719e453bb874f972e", "inference": { "gateway": "https://zk-credits-gateway.onrender.com/v1/chat/completions", "deploymentDomain": "84532", "contract": "0xcc1909dD30485d6D9a46e3d33cf04C1378b586Ab", "recipient": "0xa8b9b38e748563AF7FbAA276e8a843Da417D7Bc1", "circuit": "private-credit-spend-bn254-dev", "verifyingKey": "private-credit-spend-vk-dev-sepolia-v2", "serviceClass": "coding-deepseek-v4-flash-v1" } };
+var LIVE_DEFAULTS = { "build": "67ef6dc5b0f4270103c0c4128a6fc85cf88148513c5d88ad7f471aa5637b4a55", "inference": { "gateway": "https://zk-credits-gateway.onrender.com/v1/chat/completions", "deploymentDomain": "84532", "contract": "0xcc1909dD30485d6D9a46e3d33cf04C1378b586Ab", "recipient": "0xa8b9b38e748563AF7FbAA276e8a843Da417D7Bc1", "circuit": "private-credit-spend-bn254-dev", "verifyingKey": "private-credit-spend-vk-dev-sepolia-v2", "serviceClass": "coding-deepseek-v4-flash-v1" } };
 
 // ../../examples/base-transaction-investigator/live.mjs
 var CHAINS = { base: 8453, "base-sepolia": 84532 };
@@ -2538,10 +2538,10 @@ async function runLiveInvestigation(args, options = {}) {
   const inferenceFactory = async ({ authorization }) => {
     const agent = await prepared.open({
       async beforeProof(request) {
+        challengeObserved++;
         if ([...observations.values()].some((a) => a.state === "retired" && a.outcome === "unknown"))
           throw Error("unknown_inference_outcome");
         await authorization.beforeProof(request);
-        challengeObserved++;
         observations.set(request.attemptId, { state: "reserved", outcome: "unknown" });
       },
       async observe(event) {
@@ -2588,7 +2588,7 @@ async function runLiveInvestigation(args, options = {}) {
       unknown: attempts.filter((a) => a.state !== "released" && a.outcome === "unknown").length,
       retired: attempts.filter((a) => a.state === "retired").length,
       modelDeliveryObserved,
-      recoveredPriorTask: attempts.length === 0 && report.inference.authorizedAllocation > 0,
+      recoveredPriorTask: report.stoppingReason === "recovered_stopped",
       build: LIVE_DEFAULTS.build
     };
     return report;
@@ -2605,6 +2605,8 @@ function formatLiveReport(report) {
     `Result: ${report.completion} (${report.stoppingReason})`,
     ""
   ];
+  if (report.stoppingReason === "recovered_stopped" && report.previousStoppingReason)
+    lines.push(`Original stopping reason: ${report.previousStoppingReason}`);
   for (const [label, items] of [
     ["Observed", report.observedFacts],
     ["Supported", report.supportedDiagnoses],
@@ -2615,10 +2617,12 @@ function formatLiveReport(report) {
   }
   for (const gap of [...report.missingEvidence ?? [], ...report.uncertainty ?? []]) lines.push(`Uncertainty: ${gap}`);
   if (report.paymentEvidence.unknown > 0 || report.inference?.unknownOutcomes > 0) lines.push("Action: preserve this task and credential state; resolve the unknown outcome before starting another paid task. Repeating this hash only recovers the local report.");
-  if (report.stoppingReason === "inference_unavailable") lines.push("Action: run zk-credits doctor and check gateway/model availability. A useful model diagnosis is unavailable; inspect the separate payment counters.");
-  if (["rpc_unavailable", "evidence_unavailable", "insufficient_evidence", "unsupported_input"].includes(report.stoppingReason)) lines.push("Action: check transaction availability on the selected chain and public RPC access; missing evidence cannot be replaced with fixtures.");
+  const cause = report.stoppingReason === "recovered_stopped" ? report.previousStoppingReason : report.stoppingReason;
+  if (cause === "inference_terms_refused") lines.push("Action: payment terms did not match the pinned deployment. Update zk-credits and check gateway configuration before starting a new investigation; repeating this hash only recovers the saved report.");
+  if (cause === "inference_unavailable") lines.push("Action: run zk-credits doctor and check gateway/model availability. A useful model diagnosis is unavailable; inspect the separate payment counters.");
+  if (["rpc_unavailable", "evidence_unavailable", "insufficient_evidence", "unsupported_input"].includes(cause)) lines.push("Action: check transaction availability on the selected chain and public RPC access; missing evidence cannot be replaced with fixtures.");
   for (const entry of report.evidence ?? []) lines.push(`[${entry.id}] ${entry.operation}: ${entry.provenance}; SHA-256 ${entry.contentDigest}`);
-  if (report.paymentEvidence.recoveredPriorTask) lines.push(`Recovered prior task accounting; no new inference was authorized. Prior confirmed credits: ${report.inference.confirmedCommitted}; prior unknown outcomes: ${report.inference.unknownOutcomes}.`);
+  if (report.paymentEvidence.recoveredPriorTask) lines.push(`Recovered saved investigation; no new inference was authorized. Prior confirmed credits: ${report.inference.confirmedCommitted}; prior unknown outcomes: ${report.inference.unknownOutcomes}.`);
   lines.push(
     "",
     "Payment: custom zk-prepaid; bundle funding on Base Sepolia, credit consumption offchain.",