Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

201 KB
Raw Blame
/**
 * Cron dispatcher — single Vercel serverless function for every /api/cron/* job.
 *
 * Vercel routes /api/cron/<name> to this file via the [name] dynamic segment;
 * `req.query.name` carries the kebab-case job id. Each branch below is a
 * verbatim move of the original per-file handler body — no logic changes,
 * especially around auth / CRON_SECRET checks.
 *
 * ROUTING — READ THIS BEFORE ADDING A HANDLER. This project uses a legacy
 * `routes` array in vercel.json, which does NOT auto-route dynamic [name]
 * segments: every job name in HANDLERS must ALSO appear in the explicit
 * `/api/cron/(name-a|name-b|…)` → `/api/cron/[name]?name=$1` route there, or
 * the job 404s in production while working fine in local dev. That exact gap
 * silently killed all 30+ dispatcher jobs (payouts, subscriptions, buybacks,
 * pumpfun monitors) until July 2026. tests/cron-dispatcher-routing.test.js
 * fails the suite if the map and the route drift — keep both in sync.
 *
 * Cron paths handled (kebab-case → handler):
 *   audit-log-cleanup             → handleAuditLogCleanup
 *   erc8004-crawl                 → handleErc8004Crawl
 *   index-delegations             → handleIndexDelegations
 *   process-subscriptions         → handleProcessSubscriptions
 *   pump-agent-stats              → handlePumpAgentStats
 *   pumpfun-monitor               → handlePumpfunMonitor
 *   pumpfun-signals               → handlePumpfunSignals
 *   pumpfun-graduations-sync      → handlePumpfunGraduationsSync
 *   run-buyback                   → handleRunBuyback
 *   run-three-buyback             → handleRunThreeBuyback
 *   run-dca                       → handleRunDca
 *   run-distribute-payments       → handleRunDistributePayments
 *   run-subscriptions             → handleRunSubscriptions
 *   solana-attest-event-cleanup   → handleSolanaAttestEventCleanup
 *   solana-attestations-crawl     → handleSolanaAttestationsCrawl
 */

import { Interface } from 'ethers';
import { createPublicClient, encodeFunctionData, parseAbi } from 'viem';
import { evmTransport } from '../_lib/evm/rpc.js';
import { baseSepolia, base } from 'viem/chains';

import { sql } from '../_lib/db.js';
import { matchedSlurStem } from '../_lib/display-name-safety.js';
import { submitProtected } from '../_lib/execution-engine.js';
import { cors, error, json, method, wrapCron } from '../_lib/http.js';
import { fetchUpstream } from '../_lib/upstream-fetch.js';
import { env } from '../_lib/env.js';
import { llmComplete } from '../_lib/llm.js';
import { CHAINS } from '../_lib/erc8004-chains.js';
import { REGISTRY_TOPICS, decodeRegistryLog } from '../_lib/erc8004-registry-events.js';
import { REPUTATION_TOPICS, decodeReputationLog, reputationRegistryFor } from '../_lib/erc8004-reputation-events.js';
import { agentRef, recordEvents } from '../_lib/onchain-events.js';
import { DELEGATION_MANAGER_DEPLOYMENTS, DELEGATION_MANAGER_ABI } from '../../src/erc7710/abi.js';
import {
	getPumpAgent,
	getPumpAgentOffline,
	getConnection,
	getRpcFallback,
	getPumpSdk,
	getAmmPoolState,
	buildUnsignedTxBase64,
	solanaPubkey,
} from '../_lib/pump.js';
import { mintAttestation, deriveEventId, loadAttesterKeypair } from '../_lib/attest-event.js';
import { pumpfunMcp, pumpfunBotEnabled } from '../_lib/pumpfun-mcp.js';
import { getMints, getWhales, getClaims } from '../_lib/channel-feed-sources.js';
import { crawlAgentAttestations } from '../_lib/solana-attestations.js';
import { SOLANA_USDC_MINT, SOLANA_USDC_MINT_DEVNET, EVM_USDC } from '../payments/_config.js';
import { chargeSubscription, failPayment } from '../_lib/subscription-billing.js';
import { sendEmail } from '../_lib/email.js';
import { fetchSafePublicUrl } from '../_lib/ssrf-guard.js';
import { runPumpAlertRules } from '../_lib/pump-alert-runner.js';
import { publishUserEvent } from '../_lib/feed.js';
import { confirmSkillPurchase } from '../_lib/purchase-confirm.js';
import { requireCron } from '../_lib/cron-auth.js';
import { acquireLock } from '../_lib/cache.js';
import { resolveURI } from '../../src/ipfs.js';
import {
	OUTCOME,
	applyChargeFailure,
	chargeStatusFor,
	classifyChargeFailure,
} from '../_lib/recurring.js';
import {
	adoptLegacyDcaStrategies,
	claimEvmDca,
	dueEvmDca,
	recordEvmDcaFailure,
	recordEvmDcaSuccess,
} from '../_lib/dca-unified.js';

// ─── Dispatcher ──────────────────────────────────────────────────────────────

const HANDLERS = {
	'erc8004-crawl': handleErc8004Crawl,
	'solana-agents-crawl': handleSolanaAgentsCrawl,
	'index-delegations': handleIndexDelegations,
	'process-subscriptions': handleProcessSubscriptions,
	'pump-agent-stats': handlePumpAgentStats,
	'pumpfun-monitor': handlePumpfunMonitor,
	'pumpfun-signals': handlePumpfunSignals,
	'pumpfun-graduations-sync': handlePumpfunGraduationsSync,
	'run-buyback': handleRunBuyback,
	'run-three-buyback': handleRunThreeBuyback,
	'run-dca': handleRunDca,
	'run-distribute-payments': handleRunDistributePayments,
	'run-subscriptions': handleRunSubscriptions,
	'audit-log-cleanup': handleAuditLogCleanup,
	'settle-royalties': handleSettleRoyalties,
	'solana-attest-event-cleanup': handleSolanaAttestEventCleanup,
	'solana-attestations-crawl': handleSolanaAttestationsCrawl,
	'expire-pending-purchases': handleExpirePendingPurchases,
	'confirm-pending-purchases': handleConfirmPendingPurchases,
	'cleanup-csrf-tokens': handleCleanupCsrfTokens,
	'process-withdrawals': handleProcessWithdrawals,
	'monetization-payouts': handleProcessWithdrawals,
	'run-x-scheduled-posts': handleRunXScheduledPosts,
	'run-x-triggers': handleRunXTriggers,
	'x-mentions': handleXMentions,
	'fetch-x-metrics': handleFetchXMetrics,
	'run-coin-cycle': handleRunCoinCycle,
	'run-coin-payouts': handleRunCoinPayouts,
	'club-payouts': handleClubPayouts,
	'siwx-gc': handleSiwxGc,
	'unstoppable-tick': handleUnstoppableTick,
	'cosmetic-splits-sweep': handleCosmeticSplitsSweep,
	'treasury-autopilot': handleTreasuryAutopilot,
	'irl-drops-refund': handleIrlDropsRefund,
};

// ═══════════════════════════════════════════════════════════════════════════
// irl-drops-refund — auto-refund expired, unclaimed IRL money drops
// ═══════════════════════════════════════════════════════════════════════════
// A drop placed in a spot nobody visits, or with claims left over at expiry,
// returns its remaining escrow balance to the creator. Idempotent: markRefunding
// CAS-es the drop to 'refunded' so a second pass can't double-sweep; an empty
// escrow (fully claimed, or never funded) is marked 'expired' and skipped.
async function handleIrlDropsRefund(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!requireCron(req, res)) return;

	const {
		listExpiredRefundable, getDropRow, markRefunding, sweepRefund, recordRefundTx, markExpired, readDropBalance, fundingConfigured,
	} = await import('../_lib/irl-drops.js');

	const report = { refunded: 0, expired: 0, errors: [] };
	let ids = [];
	try {
		ids = await listExpiredRefundable(40);
	} catch (err) {
		report.errors.push({ stage: 'list', error: err.message || String(err) });
		return json(res, 200, report);
	}

	for (const id of ids) {
		try {
			const row = await getDropRow(id);
			if (!row) continue;

			// Nothing on-chain to return (never funded, or fully claimed) → mark expired.
			const bal = await readDropBalance({ address: row.escrow_address, asset: row.asset });
			if (bal.atomics != null && BigInt(bal.atomics) <= 0n) {
				await markExpired({ dropId: id });
				report.expired += 1;
				continue;
			}
			if (!row.refund_address || !fundingConfigured()) {
				// Can't sweep yet (no refund address on file, or payout wallet
				// unconfigured) — leave it for a later pass rather than losing track.
				continue;
			}

			// These are already past expiry; CAS to 'refunded' is idempotent so a
			// second pass returns null rather than double-sweeping.
			const locked = await markRefunding({ dropId: id, allowActive: true });
			if (!locked) continue; // already refunded / not in a refundable state
			const refundTx = await sweepRefund({ drop: locked });
			await recordRefundTx({ dropId: id, refundTx });
			report.refunded += 1;
		} catch (err) {
			report.errors.push({ id, error: err.message || String(err) });
		}
	}
	return json(res, 200, report);
}

// vercel.json grants this route 300s (`functions["api/cron/[name].js"].maxDuration`);
// without passing maxDurationMs here, wrapCron falls back to its 120s default and
// races every job behind this shared dispatcher against that instead, truncating
// anything that legitimately needs more than 120s (e.g. run-buyback, solana-agents-crawl).
export const maxDuration = 300;

export default wrapCron(
	async (req, res) => {
		const name = req.query?.name;
		const handler = typeof name === 'string' ? HANDLERS[name] : null;
		if (!handler) return error(res, 404, 'not_found', 'unknown cron');
		return handler(req, res);
	},
	{ maxDurationMs: maxDuration * 1000 },
);

// ═══════════════════════════════════════════════════════════════════════════
// solana-agents-crawl — index external Solana agents (Metaplex + AgenC)
// ═══════════════════════════════════════════════════════════════════════════
// Enumerates every agent in the Metaplex Agent Registry and the AgenC
// coordination protocol into solana_agents_index, so /agents lists the whole
// Solana ecosystem — not just three.ws-launched agents. Each source is isolated:
// a failing registry (RPC disables getProgramAccounts, IDL drift) is reported in
// its own block and never aborts the other.
async function handleSolanaAgentsCrawl(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!requireCron(req, res)) return;

	const { crawlMetaplexAgents, crawlAgencAgents } = await import('../_lib/solana-agents-crawl.js');

	// Hard budget split across the two registries so a slow first scan can't
	// starve the second before Vercel's function limit.
	const start = Date.now();
	const BUDGET_MS = 240_000;
	const report = { metaplex: null, agenc: null, errors: [] };

	try {
		report.metaplex = await crawlMetaplexAgents({ deadline: start + BUDGET_MS / 2 });
	} catch (err) {
		report.errors.push({ source: 'metaplex', error: err.message || String(err) });
	}
	try {
		report.agenc = await crawlAgencAgents({ deadline: start + BUDGET_MS });
	} catch (err) {
		report.errors.push({ source: 'agenc', error: err.message || String(err) });
	}

	return json(res, 200, report);
}

// ═══════════════════════════════════════════════════════════════════════════
// erc8004-crawl
// ═══════════════════════════════════════════════════════════════════════════

// Blocks scanned per chain per cron invocation. Public RPCs typically allow
// 2000-block ranges; lower this if a chain's RPC rejects with "block range".
const ERC8004_BLOCK_CHUNK = 1_000;

// On first run (no cursor), scan this many recent blocks. Keep small so the
// initial cron run stays well under Vercel's 300s limit. Set
// ERC8004_CRAWL_LOOKBACK=50000 in Vercel env only for a one-time manual backfill.
const ERC8004_DEFAULT_LOOKBACK = parseInt(process.env.ERC8004_CRAWL_LOOKBACK || '2000', 10);

// Metadata enrichment per invocation.
const ERC8004_METADATA_BATCH = 25;

const ERC8004_FETCH_TIMEOUT_MS = 10_000;

// Headers sent on every EVM JSON-RPC POST. Node/undici's fetch sends no
// `User-Agent` by default, and PublicNode's gateway (ethereum.publicnode.com,
// base.publicnode.com, the *-sepolia-rpc.publicnode.com testnet hosts) hard-403s
// any request without an identifiable UA — which blanked the last lane of the
// failover chain and surfaced as the "RPC HTTP 403 from …publicnode.com" storm in
// the index-delegations and erc8004 crawl stages. A descriptive bot UA satisfies
// the gateway; `accept` keeps strict providers from negotiating a non-JSON body.
const EVM_RPC_HEADERS = {
	'content-type': 'application/json',
	accept: 'application/json',
	'user-agent': 'three.ws-onchain-indexer/1.0 (+https://three.ws)',
};

// Metadata URLs are external, user-controlled (on-chain agentURI) and often
// point at slow IPFS gateways. Cap each fetch tighter than RPC calls so a single
// hung gateway can't stall the whole enrichment batch toward Vercel's 300s kill.
const ERC8004_METADATA_TIMEOUT_MS = 5_000;

// Hard budget: stop processing and return before Vercel's 300s limit.
const CRAWL_BUDGET_MS = 240_000;

async function handleErc8004Crawl(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const crawlStart = Date.now();
	const report = { chains: [], enriched: 0, errors: [], skipped: 0 };

	// Neediest chain first, never the array order. The budget below cuts the
	// sweep short on a slow tick, and with a fixed order that always cuts the
	// SAME tail: the chains at the end of CHAINS were starved every single tick,
	// which is how one cursor reached 107 days stale while the chains above it
	// stayed current. Ordering by backlog turns a truncated tick into "the worst
	// chains got served" instead of "the last chains got skipped again".
	const order = await erc8004CrawlOrder();

	for (const chain of order) {
		if (Date.now() - crawlStart > CRAWL_BUDGET_MS) {
			report.skipped += 1;
			continue;
		}
		try {
			const r = await erc8004CrawlChain(chain);
			report.chains.push({ chainId: chain.id, name: chain.name, ...r });
		} catch (err) {
			report.errors.push({ chainId: chain.id, error: err.message || String(err) });
			await sql`
				UPDATE erc8004_crawl_cursor
				SET last_error = ${String(err.message || err).slice(0, 500)}
				WHERE chain_id = ${chain.id}
			`.catch(() => {});
		}
	}

	// Second pass: spend whatever budget the first pass left on the chains that
	// are still behind head. One chunk per chain per tick is enough to HOLD a
	// slow chain but cannot DRAIN a fast one, and the arithmetic is not close.
	// Measured on 2026-08-28: Arbitrum One sat 18,375,509 blocks behind at a
	// 8,000-block window. The cron runs every 15 minutes, so one chunk per tick
	// buys 768,000 blocks a day against a chain that produces roughly 345,600,
	// which drains the backlog in about six weeks. Meanwhile a tick that found
	// every other chain at head returned with most of its 240 seconds unspent.
	// This pass hands that idle budget to the worst backlog instead of throwing
	// it away, and does nothing at all on a tick where every chain is current.
	report.catchUp = await erc8004CatchUp(order, report, crawlStart);

	if (Date.now() - crawlStart <= CRAWL_BUDGET_MS) {
		try {
			report.enriched = await erc8004EnrichMetadata(
				ERC8004_METADATA_BATCH,
				crawlStart + CRAWL_BUDGET_MS,
			);
		} catch (err) {
			report.errors.push({ stage: 'metadata', error: err.message || String(err) });
		}
	}

	return json(res, 200, report);
}

// The first pass must always finish, so the catch-up pass only starts once the
// sweep has left at least this much of the budget unspent, and it stops itself
// this far from the deadline so metadata enrichment still gets its turn.
const CRAWL_CATCHUP_RESERVE_MS = 45_000;

/**
 * Chains the catch-up pass should feed more chunks to, worst backlog first.
 * A chain is a candidate only when its first-pass result says it is genuinely
 * behind head AND that pass actually moved the cursor: a chain that scanned
 * nothing hit its provider's floor or errored, and re-asking it in the same
 * tick would just spin on the same rejection.
 * Pure: no clock, no DB. This is the seam the tests drive.
 * @param {object[]} results the first pass's report.chains entries
 * @returns {object[]}
 */
export function catchUpCandidates(results) {
	return (results || [])
		.filter((r) => Number(r?.blocksBehind) > 0 && Number(r?.scanned) > 0)
		.sort((a, b) => Number(b.blocksBehind) - Number(a.blocksBehind));
}

/**
 * Feed extra chunks to the chains still behind head until the budget runs out.
 * Re-reads the neediest chain each round rather than draining one to completion,
 * so a single enormous backlog cannot starve the others of the same idle budget.
 * @param {object[]} order the chain configs the first pass walked
 * @param {{ chains: object[], errors: object[] }} report mutated in place
 * @param {number} crawlStart
 * @returns {Promise<{ rounds: number, scanned: number, chains: number[] }>}
 */
async function erc8004CatchUp(order, report, crawlStart) {
	const summary = { rounds: 0, scanned: 0, chains: [] };
	const byId = new Map(order.map((c) => [c.id, c]));
	// Behind-ness as the first pass measured it, updated in place each round so
	// the next round re-picks the worst without re-querying the cursor table.
	const behind = new Map(
		catchUpCandidates(report.chains).map((r) => [r.chainId, Number(r.blocksBehind)]),
	);

	while (behind.size) {
		if (Date.now() - crawlStart > CRAWL_BUDGET_MS - CRAWL_CATCHUP_RESERVE_MS) break;
		const [chainId] = [...behind.entries()].sort((a, b) => b[1] - a[1])[0];
		const chain = byId.get(chainId);
		if (!chain) {
			behind.delete(chainId);
			continue;
		}
		try {
			const r = await erc8004CrawlChain(chain);
			report.chains.push({ chainId: chain.id, name: chain.name, catchUp: true, ...r });
			summary.rounds += 1;
			summary.scanned += Number(r.scanned) || 0;
			if (!summary.chains.includes(chain.id)) summary.chains.push(chain.id);
			// Nothing scanned means the provider refused even the floor window, so
			// drop the chain rather than spin on the same rejection for the rest of
			// the budget.
			if (Number(r.blocksBehind) > 0 && Number(r.scanned) > 0) behind.set(chainId, Number(r.blocksBehind));
			else behind.delete(chainId);
		} catch (err) {
			report.errors.push({ chainId: chain.id, stage: 'catch-up', error: err.message || String(err) });
			behind.delete(chainId);
		}
	}
	return summary;
}

/**
 * Every configured chain, worst backlog first. A chain with no cursor row has
 * never been crawled at all and outranks everything, since it contributes no
 * coverage whatsoever until its first tick.
 * @returns {Promise<object[]>}
 */
async function erc8004CrawlOrder() {
	let cursors = [];
	try {
		cursors = await sql`SELECT chain_id, blocks_behind, updated_at FROM erc8004_crawl_cursor`;
	} catch {
		// An unreadable cursor table must not stop the crawl; fall back to the
		// declared order, which is what ran before this ordering existed.
		return [...CHAINS];
	}
	const by = new Map(cursors.map((c) => [Number(c.chain_id), c]));
	return [...CHAINS].sort((a, b) => rank(by.get(b.id)) - rank(by.get(a.id)));
}

// Ceiling on how far cursor age alone can lift a chain that reports no backlog.
// It has to be high enough that a cursor stale for days outranks one crawled
// minutes ago, and low enough that it never preempts a chain with a real
// backlog to clear.
const STALE_RANK_CAP = 10_000;

/**
 * Sweep priority for one chain's cursor. Never-crawled sorts above every
 * backlog; otherwise the backlog itself ranks, and a chain reporting no backlog
 * ranks by how long its cursor has been standing still.
 *
 * That last clause used to be `Math.min(ageMin, 1)`, which silently disabled
 * itself. The cron runs every 15 minutes, so by the time it reads the table
 * EVERY caught-up chain is older than the 1-minute cap and they all return
 * exactly 1. The sort then falls through to the declared array order on every
 * single tick, which is the starvation the tie-break was added to prevent.
 *
 * It also hid broken chains. blocks_behind is only written by a SUCCESSFUL
 * crawl, so a chain erroring on every tick keeps reporting whatever its last
 * good crawl left, which is 0, and reads as caught up forever. Measured
 * 2026-08-28: Polygon's cursor had not advanced in 122 days and BNB Chain's in
 * 89, both still reporting 0 blocks behind, both sorted to the bottom of every
 * sweep. Ranking them by age puts the most-starved chains at the front of a
 * tick that runs out of budget, which is the only time the order matters.
 * Pure: the clock is injected. This is the seam the tests drive.
 * @param {{ blocks_behind?: number|string|null, updated_at?: string|Date|null }|null|undefined} cursor
 * @param {number} [now]
 * @returns {number}
 */
export function rank(cursor, now = Date.now()) {
	if (!cursor) return Number.MAX_SAFE_INTEGER;
	const behind = Number(cursor.blocks_behind || 0);
	if (behind > 0) return behind;
	const ageMin = cursor.updated_at ? (now - new Date(cursor.updated_at).getTime()) / 60_000 : 0;
	return Math.min(Math.max(ageMin, 0), STALE_RANK_CAP);
}

// Concurrent eth_getBlockByNumber calls while stamping a range's event blocks.
// See the loop in erc8004CrawlChain for why this is bounded rather than a single
// Promise.all over every block in the window.
const ERC8004_BLOCKTIME_CONCURRENCY = 8;

// Ceiling for the adaptive window. Public RPCs commonly cap eth_getLogs at
// 2,000 to 10,000 blocks; the crawl walks up toward this and backs off the
// moment a provider says no, so no chain needs its limit hardcoded here.
const ERC8004_MAX_BLOCK_CHUNK = 8_000;
const ERC8004_MIN_BLOCK_CHUNK = 100;
// Ceiling on how long erc8004CrawlChain's shrink-retry loop may run for ONE
// chain before it must checkpoint. Comfortably under CRAWL_BUDGET_MS (240s) so
// a single stuck chain can never consume the whole tick, and short enough that
// an external request timeout around this cron cannot kill the process before
// a write happens. Measured 2026-10-25: Base's cursor sat frozen for 2+ days
// because this loop had no time bound at all, only the backoffChunkSize fixed
// point at the floor, which a slow or rejecting lane could take minutes to
// reach, with nothing written until it did.
const ERC8004_CHAIN_BUDGET_MS = 60_000;
// Range rejections name the range rather than a stable error code, and every
// provider words it differently.
//
// A bare "limit exceeded" is deliberately NOT here. It is the wording of the
// JSON-RPC -32005 rate/compute limit (bnbchain data-seed, zan.top), which no
// smaller range fixes: matching it made the crawl read a plan limit as a range
// ceiling and shrink to the floor forever instead of surfacing the real fault.
// Every entry below names a range or a result volume, which shrinking does fix.
//
// `ranges? over N blocks` is dRPC's free tier, and its number is wrong: on
// 2026-10-08 a testnet's dRPC lane answered "ranges over 10000 blocks are not
// supported on free plan" to every window from 8,000 down to 200 and served 101.
// It is still a range ceiling that shrinking reaches, which is all this asks.
const RANGE_REJECTED = /block range|range is too large|too wide|too many blocks|ranges? over \d+ blocks|query returned more than|exceed maximum block range|limited to|response size|logs matched|exceeds? max(?:imum)? results|retry with the range/i;

/**
 * Is this RPC failure the provider refusing the width of the requested range?
 * Only those are worth retrying smaller; everything else is a real fault.
 * @param {unknown} message
 * @returns {boolean}
 */
export function isRangeRejection(message) {
	return RANGE_REJECTED.test(String(message ?? ''));
}

// Blocks the provider no longer holds at all. Distinct from a range rejection
// in the one way that matters: no smaller window fixes it, because the data is
// gone rather than the request being too wide. Narrow on purpose, so a node
// that is merely busy is never mistaken for one that has pruned.
// `archive request` and its siblings belong here rather than under a range
// rejection: a keyless public node that will serve the last few thousand blocks
// and answers anything older with "archive requests require a personal token"
// has drawn the same retention wall a pruning node draws, just with a paywall
// behind it. Measured on 2026-09-02, that wording is what two of the three
// stalled chains were sitting on, and shrinking the window walked straight into
// it at every size down to the 100-block floor.
const PRUNED_HISTORY =
	/has been pruned|pruned history|missing trie node|state is not available|do not have the state|archive request|requires? an archive|archive node (?:is )?required/i;

/**
 * Is this RPC failure the provider saying it no longer retains the blocks the
 * cursor points at?
 *
 * This is the EVM twin of the Solana unresolvable-cursor stall, and it fails the
 * same way: the crawl resumes at `last_block + 1`, the provider has pruned that
 * height, the whole call errors, and the cursor is only written on the success
 * path, so every later tick asks for the same dead blocks forever. Measured on
 * 2026-09-02, one chain's cursor had not moved since 2026-04-28 for exactly this
 * reason while the range backoff, which cannot help here, retried around it.
 * @param {unknown} message
 * @returns {boolean}
 */
export function isPrunedHistoryRejection(message) {
	return PRUNED_HISTORY.test(String(message ?? ''));
}

/**
 * The block window to request for a chain this tick.
 *
 * A fixed window is the reason five chains could never catch up: it is a bet
 * that every chain produces blocks slower than the crawl consumes them, and on
 * Arbitrum One (0.28x of the cron period per 1,000 blocks) that bet loses every
 * tick, forever. So grow the window while a chain is behind and shrink it when
 * the provider objects, letting each lane settle at the largest range it will
 * actually serve.
 *
 * Pure, so the growth and backoff curves are testable without an RPC.
 * @param {{ stored?: number|null, configured?: number|null, behind: number }} a
 * @returns {number}
 */
export function nextChunkSize({ stored, configured, behind }) {
	const floor = Math.max(ERC8004_MIN_BLOCK_CHUNK, 1);
	const base = Number(stored) > 0 ? Number(stored) : configured || ERC8004_BLOCK_CHUNK;
	// Caught up: hold the window rather than growing it for no reason.
	if (behind <= base) return clampChunk(base, floor);
	// Behind: double, but never overshoot the backlog itself.
	return clampChunk(Math.min(base * 2, behind), floor);
}

/** Halve the window after a provider rejects the range, never below the floor. */
export function backoffChunkSize(current) {
	return clampChunk(Math.floor((Number(current) || ERC8004_BLOCK_CHUNK) / 2), ERC8004_MIN_BLOCK_CHUNK);
}

function clampChunk(n, floor) {
	return Math.max(floor, Math.min(ERC8004_MAX_BLOCK_CHUNK, Math.trunc(n)));
}

export async function erc8004CrawlChain(chain, { now = Date.now } = {}) {
	const [cursor] = await sql`
		SELECT last_block, chunk_size FROM erc8004_crawl_cursor WHERE chain_id = ${chain.id}
	`;

	const latestHex = await erc8004RpcCall(chain.rpcUrls ?? chain.rpcUrl, 'eth_blockNumber', []);
	const latestBlock = Number.parseInt(latestHex, 16);

	let fromBlock = cursor
		? Number(cursor.last_block) + 1
		: Math.max(0, latestBlock - ERC8004_DEFAULT_LOOKBACK);

	if (fromBlock > latestBlock) {
		await erc8004RecordHead(chain.id, latestBlock, latestBlock);
		return { inserted: 0, scanned: 0, lastBlock: latestBlock, fromBlock, blocksBehind: 0 };
	}

	// Adaptive per chain, seeded by the declared override for a restrictive RPC.
	// See nextChunkSize: a fixed window is why fast chains never caught up.
	let chunkSize = nextChunkSize({
		stored: cursor?.chunk_size,
		configured: chain.blockChunk,
		behind: latestBlock - fromBlock + 1,
	});

	let toBlock;
	let logs;
	let reputationLogs;
	// A rejected range is the growth loop finding this chain's ceiling, not an
	// outage, so shrink and retry the SAME blocks now rather than ending the tick
	// empty. Retrying only on the next tick deadlocks a chain forever: the
	// rejection stores the halved window, then nextChunkSize sees a backlog wider
	// than it and doubles straight back to the size that was just refused, so the
	// cursor never moves. Measured on 2026-08-14: BSC Testnet and Moonbeam sat at
	// scanned=0 across four consecutive ticks while their backlogs grew.
	let narrowedFrom = null;
	let prunedSkip = null;
	const loopStart = now();
	for (;;) {
		if (now() - loopStart > ERC8004_CHAIN_BUDGET_MS) {
			// The shrink loop has run long enough that something downstream (a slow
			// or rate-limited lane, a dense block range needing many halvings) is
			// costing more wall-clock time than this chain may safely hold the tick
			// hostage for. Persist whatever progress exists so the NEXT tick resumes
			// from here instead of silently retrying the exact same blocks forever.
			await sql`
				INSERT INTO erc8004_crawl_cursor (chain_id, last_block, updated_at, head_block, blocks_behind, chunk_size, last_error)
				VALUES (${chain.id}, ${Math.max(0, fromBlock - 1)}, now(), ${latestBlock},
				        ${Math.max(0, latestBlock - fromBlock + 1)}, ${chunkSize}, ${'shrink loop exceeded ' + ERC8004_CHAIN_BUDGET_MS + 'ms budget at chunk ' + chunkSize})
				ON CONFLICT (chain_id) DO UPDATE SET
					updated_at    = now(),
					head_block    = excluded.head_block,
					blocks_behind = excluded.blocks_behind,
					chunk_size    = excluded.chunk_size,
					last_error    = excluded.last_error
			`;
			return {
				inserted: 0,
				scanned: 0,
				lastBlock: fromBlock - 1,
				fromBlock,
				blocksBehind: Math.max(0, latestBlock - fromBlock + 1),
				chunkSize,
				loopBudgetExceeded: true,
			};
		}
		toBlock = Math.min(fromBlock + chunkSize - 1, latestBlock);
		const range = {
			fromBlock: '0x' + fromBlock.toString(16),
			toBlock: '0x' + toBlock.toString(16),
		};
		try {
			// Topic OR-set, not the single Registered topic: an agent's row used to
			// freeze at its registration block because ownership transfers, URI updates
			// and metadata writes were never requested from the RPC at all. See the
			// coverage census in api/_lib/erc8004-registry-events.js.
			logs = await erc8004RpcCall(chain.rpcUrls ?? chain.rpcUrl, 'eth_getLogs', [
				{ address: chain.registry, topics: [REGISTRY_TOPICS], ...range },
			]);

			// The reputation registry lives at its own CREATE2 address on the same
			// network class; scan the identical block range so an agent's trust signals
			// (feedback, revocations, responses) reach the index alongside its identity
			// history. A chain with no reputation deployment yields an empty log list,
			// not an error.
			reputationLogs = await erc8004RpcCall(chain.rpcUrls ?? chain.rpcUrl, 'eth_getLogs', [
				{ address: reputationRegistryFor(chain.testnet), topics: [REPUTATION_TOPICS], ...range },
			]);
			break;
		} catch (err) {
			// Pruned blocks are unreachable at every window size, so shrinking is
			// the wrong move and waiting is worse: the cursor stays parked on data
			// the provider will never serve, and the chain indexes nothing again,
			// forever. Resume at the head instead, once per tick so a provider that
			// keeps saying no cannot spin here.
			//
			// The skipped span is a real, permanent gap in this chain's history: it
			// can only be recovered from an archive node, which the keyless failover
			// tail is not. Report it rather than closing over it, so the gap is a
			// number someone can act on instead of a silence.
			if (isPrunedHistoryRejection(err?.message || err) && prunedSkip === null) {
				const resumeAt = Math.max(0, latestBlock - ERC8004_DEFAULT_LOOKBACK);
				if (resumeAt > fromBlock) {
					prunedSkip = { from: fromBlock, to: resumeAt, blocks: resumeAt - fromBlock };
					fromBlock = resumeAt;
					continue;
				}
			}
			// Any RPC failure that is not the provider refusing the range is a genuine
			// error and propagates to the per-chain handler above. The head is already
			// known here, so bank the real backlog first: blocks_behind is otherwise
			// written only on success, and a chain that errors every tick keeps the 0
			// its last good crawl left behind and reads as caught up forever.
			if (!isRangeRejection(err?.message || err)) {
				await erc8004RecordBacklog(chain.id, latestBlock, fromBlock).catch(() => {});
				throw err;
			}
			const reduced = backoffChunkSize(chunkSize);
			if (reduced >= chunkSize) {
				// Already at the floor: the provider will not serve even the smallest
				// window this tick. Record it and leave the cursor untouched so the next
				// tick retries the same blocks against the failover RPC.
				await sql`
					INSERT INTO erc8004_crawl_cursor (chain_id, last_block, updated_at, head_block, blocks_behind, chunk_size, last_error)
					VALUES (${chain.id}, ${Math.max(0, fromBlock - 1)}, now(), ${latestBlock},
					        ${Math.max(0, latestBlock - fromBlock + 1)}, ${chunkSize}, ${'range rejected at ' + chunkSize + ' blocks (floor)'})
					ON CONFLICT (chain_id) DO UPDATE SET
						updated_at    = now(),
						head_block    = excluded.head_block,
						blocks_behind = excluded.blocks_behind,
						chunk_size    = excluded.chunk_size,
						last_error    = excluded.last_error
				`;
				return {
					inserted: 0,
					scanned: 0,
					lastBlock: fromBlock - 1,
					fromBlock,
					blocksBehind: Math.max(0, latestBlock - fromBlock + 1),
					chunkSize,
					rangeRejected: true,
				};
			}
			narrowedFrom = narrowedFrom ?? chunkSize;
			chunkSize = reduced;
		}
	}

	// Fetch block timestamps for any blocks that produced events.
	const blockTimes = {};
	const allLogs = [...logs, ...reputationLogs];
	if (allLogs.length > 0) {
		const uniqueBlockHexes = [...new Set(allLogs.map((l) => l.blockNumber))];
		// Bounded fan-out, not one request per block all at once. The window this
		// crawl asks for grows while a chain is behind, so a catching-up chain can
		// return several hundred distinct event blocks in a single tick, and firing
		// that many concurrent eth_getBlockByNumber calls is the reliable way to
		// get rate-limited off every lane at once. A log whose timestamp cannot be
		// read is still applied to the agent row; it just does not enter the event
		// index, which refuses to invent a time.
		for (let i = 0; i < uniqueBlockHexes.length; i += ERC8004_BLOCKTIME_CONCURRENCY) {
			await Promise.all(
				uniqueBlockHexes.slice(i, i + ERC8004_BLOCKTIME_CONCURRENCY).map(async (bn) => {
					try {
						const block = await erc8004RpcCall(
							chain.rpcUrls ?? chain.rpcUrl,
							'eth_getBlockByNumber',
							[bn, false],
						);
						blockTimes[bn] = block ? Number.parseInt(block.timestamp, 16) : null;
					} catch {
						// registered_at will be null for this block
					}
				}),
			);
		}
	}

	let inserted = 0;
	const byClass = { registration: 0, metadata: 0, transfer: 0, reputation: 0 };
	const events = [];

	for (const log of logs) {
		try {
			const ev = decodeRegistryLog(log);
			if (!ev) continue;

			const ts = blockTimes[log.blockNumber];
			const occurredAt = ts ? new Date(ts * 1000).toISOString() : null;
			// Absolute on-chain time only. A log whose block timestamp could not be
			// read is still applied to the agent row, but is NOT written to the event
			// index, because a timeline entry stamped with ingestion time is a lie.
			if (occurredAt) {
				events.push({
					chain: 'evm',
					chainId: chain.id,
					network: chain.testnet ? 'testnet' : 'mainnet',
					agentRef: agentRef({ chain: 'evm', chainId: chain.id, agentId: ev.agentId }),
					eventClass: ev.eventClass,
					eventName: ev.eventName,
					tx: ev.tx,
					logIndex: ev.logIndex,
					blockNumber: ev.blockNumber,
					occurredAt,
					actor: ev.type === 'transfer' ? ev.from : ev.owner || null,
					counterparty: ev.type === 'transfer' ? ev.to : null,
					payload: erc8004EventPayload(ev, chain),
				});
			}

			if (ev.type === 'registered') {
				await sql`
					INSERT INTO erc8004_agents_index
						(chain_id, agent_id, owner, registry, agent_uri,
						 registered_block, registered_tx, registered_at, last_seen_at)
					VALUES
						(${chain.id}, ${ev.agentId}, ${ev.owner}, ${chain.registry.toLowerCase()},
						 ${ev.agentUri || null}, ${ev.blockNumber}, ${ev.tx},
						 ${occurredAt}, now())
					ON CONFLICT (chain_id, agent_id) DO UPDATE SET
						owner = excluded.owner,
						agent_uri = COALESCE(excluded.agent_uri, erc8004_agents_index.agent_uri),
						last_seen_at = now()
				`;
				inserted += 1;
				byClass.registration += 1;
			} else if (ev.type === 'uri_updated') {
				// A new agentURI invalidates every enriched field. Clearing
				// last_metadata_at re-queues the row for the enrichment pass instead
				// of serving the old name and image for the next seven days.
				await sql`
					UPDATE erc8004_agents_index
					SET agent_uri = ${ev.agentUri || null},
					    last_metadata_at = null,
					    metadata_error = null,
					    last_seen_at = now()
					WHERE chain_id = ${chain.id} AND agent_id = ${ev.agentId}
				`;
				byClass.metadata += 1;
			} else if (ev.type === 'metadata_set') {
				byClass.metadata += 1;
			} else if (ev.type === 'transfer' && !ev.isMint) {
				// The reason an agent's indexed owner could never change: nothing
				// watched Transfer. Only a row that already exists is updated; a
				// transfer of an agent registered before the crawl window is
				// recorded as history and reconciled when Registered is backfilled.
				await sql`
					UPDATE erc8004_agents_index
					SET owner = ${ev.to}, last_seen_at = now()
					WHERE chain_id = ${chain.id} AND agent_id = ${ev.agentId}
				`;
				byClass.transfer += 1;
			}
		} catch (decodeErr) {
			console.warn('[crawl] decode failed', chain.id, log.transactionHash, decodeErr.message);
		}
	}

	// Reputation logs were fetched from every chain on every tick and then used
	// only to look up block timestamps: nothing decoded them, so the entire EVM
	// trust dimension was discarded on arrival. A census of the index on
	// 2026-08-14 found 9,231 EVM events across metadata, registration and
	// transfer and exactly ZERO reputation events, while a 1,000-block sample of
	// Base alone carried 8 NewFeedback logs. Decode them into the same batch.
	for (const log of reputationLogs) {
		try {
			const ev = decodeReputationLog(log);
			if (!ev) continue;
			const ts = blockTimes[log.blockNumber];
			if (!ts) continue; // absolute on-chain time or nothing, same rule as above
			events.push({
				chain: 'evm',
				chainId: chain.id,
				network: chain.testnet ? 'testnet' : 'mainnet',
				agentRef: agentRef({ chain: 'evm', chainId: chain.id, agentId: ev.agentId }),
				eventClass: ev.eventClass,
				eventName: ev.eventName,
				tx: ev.tx,
				logIndex: ev.logIndex,
				blockNumber: ev.blockNumber,
				occurredAt: new Date(ts * 1000).toISOString(),
				// The client is who left the feedback; a response is written by the
				// responder, which is the agent's side of the exchange.
				actor: ev.responder || ev.client || null,
				counterparty: ev.responder ? ev.client || null : null,
				payload: erc8004ReputationPayload(ev, chain),
			});
			byClass.reputation += 1;
		} catch (decodeErr) {
			console.warn('[crawl] reputation decode failed', chain.id, log.transactionHash, decodeErr.message);
		}
	}

	const recorded = events.length ? await recordEvents(events) : { inserted: 0, rejected: 0 };

	// Always advance cursor to toBlock so the next run continues from here.
	// blocks_behind is the honest freshness signal: updated_at only says the cron
	// ran, and a chain producing blocks faster than the crawl consumes them keeps
	// a fresh updated_at forever while falling further behind every tick.
	const blocksBehind = Math.max(0, latestBlock - toBlock);
	// A skip closes the backlog, which is exactly why the gap has to be banked
	// here. The moment the cursor reaches the head this chain reports zero blocks
	// behind and reads as perfectly healthy, so the span it jumped over would
	// otherwise exist only in one cron response that rotates out of the logs.
	// Accumulated, never overwritten: a provider that keeps pruning under the
	// crawl shows up as a number that grows.
	const gapBlocks = prunedSkip ? prunedSkip.blocks : 0;
	await sql`
		INSERT INTO erc8004_crawl_cursor (
			chain_id, last_block, updated_at, head_block, blocks_behind, chunk_size, last_error,
			history_gap_blocks, history_gap_to, history_gap_at
		)
		VALUES (
			${chain.id}, ${toBlock}, now(), ${latestBlock}, ${blocksBehind}, ${chunkSize}, null,
			${gapBlocks}, ${prunedSkip ? prunedSkip.to : null}, ${prunedSkip ? new Date() : null}
		)
		ON CONFLICT (chain_id) DO UPDATE SET
			last_block    = GREATEST(erc8004_crawl_cursor.last_block, ${toBlock}),
			updated_at    = now(),
			head_block    = excluded.head_block,
			blocks_behind = excluded.blocks_behind,
			chunk_size    = excluded.chunk_size,
			last_error    = null,
			history_gap_blocks = erc8004_crawl_cursor.history_gap_blocks + excluded.history_gap_blocks,
			history_gap_to     = COALESCE(excluded.history_gap_to, erc8004_crawl_cursor.history_gap_to),
			history_gap_at     = COALESCE(excluded.history_gap_at, erc8004_crawl_cursor.history_gap_at)
	`;

	return {
		inserted,
		scanned: toBlock - fromBlock + 1,
		lastBlock: toBlock,
		fromBlock,
		logs: logs.length,
		events: recorded.inserted,
		byClass,
		headBlock: latestBlock,
		blocksBehind,
		// Present only when the tick overshot the provider's ceiling and recovered
		// by shrinking in place, so the report distinguishes "settled at its real
		// window" from "asked for too much and still delivered".
		...(narrowedFrom ? { narrowedFrom } : {}),
		// Present only when the provider had pruned the blocks the cursor pointed
		// at and the crawl resumed at the head. Names the span that is now a
		// permanent gap for this chain.
		...(prunedSkip ? { prunedSkip } : {}),
		chunkSize,
	};
}

/**
 * Record how far behind head a chain is on a tick that failed to advance it.
 *
 * Deliberately leaves updated_at and last_block alone: the cursor did not move,
 * and the lag monitor reads updated_at as "last time this chain advanced". Only
 * the backlog is refreshed, so a chain stuck on a dead lane shows the blocks it
 * is missing instead of the 0 from its last successful crawl. Measured on
 * 2026-10-08: one testnet had not advanced in 26 days (its first lane's
 * hostname no longer resolves) and still reported 0 blocks behind against a
 * head 2.3 million blocks past its cursor.
 * @param {number} chainId
 * @param {number} headBlock
 * @param {number} fromBlock the first block the failed tick tried to read
 */
async function erc8004RecordBacklog(chainId, headBlock, fromBlock) {
	await sql`
		UPDATE erc8004_crawl_cursor
		SET head_block    = ${headBlock},
		    blocks_behind = ${Math.max(0, headBlock - fromBlock + 1)}
		WHERE chain_id = ${chainId}
	`;
}

/**
 * Stamp a caught-up chain's head so the lag monitor can tell "0 blocks behind"
 * apart from "never measured". A chain with nothing to scan still reports.
 * @param {number} chainId
 * @param {number} headBlock
 * @param {number} lastBlock
 */
async function erc8004RecordHead(chainId, headBlock, lastBlock) {
	await sql`
		INSERT INTO erc8004_crawl_cursor (chain_id, last_block, updated_at, head_block, blocks_behind, last_error)
		VALUES (${chainId}, ${lastBlock}, now(), ${headBlock}, 0, null)
		ON CONFLICT (chain_id) DO UPDATE SET
			updated_at    = now(),
			head_block    = excluded.head_block,
			blocks_behind = 0,
			last_error    = null
	`;
}

// Per-class payload for the event index. Keeps the raw on-chain detail that the
// agent-row columns cannot hold (which metadata key changed, the URI at the time
// of the event, whether a transfer was the registration mint).
// Per-class payload for a reputation event. Keeps the score with its decimals
// (an int128 rendered as a decimal string, so nothing rounds), the tags that
// say what the score is about, and the off-chain URI the attestation points at.
function erc8004ReputationPayload(ev, chain) {
	const base = {
		registry: reputationRegistryFor(chain.testnet),
		agentId: ev.agentId,
		client: ev.client || null,
		feedbackIndex: ev.feedbackIndex ?? null,
	};
	if (ev.type === 'feedback') {
		return {
			...base,
			value: ev.value,
			valueDecimals: ev.valueDecimals,
			tag1: ev.tag1,
			tag2: ev.tag2,
			endpoint: ev.endpoint,
			feedbackUri: ev.feedbackUri,
			feedbackHash: ev.feedbackHash,
		};
	}
	if (ev.type === 'feedback_response') {
		return { ...base, responder: ev.responder, responseUri: ev.responseUri, responseHash: ev.responseHash };
	}
	return base;
}

function erc8004EventPayload(ev, chain) {
	const base = { registry: chain.registry.toLowerCase(), agentId: ev.agentId };
	if (ev.type === 'registered' || ev.type === 'uri_updated') {
		return { ...base, agentUri: ev.agentUri || null, owner: ev.owner };
	}
	if (ev.type === 'metadata_set') {
		return { ...base, key: ev.key, value: ev.value };
	}
	return { ...base, from: ev.from, to: ev.to, mint: ev.isMint };
}

async function erc8004EnrichMetadata(limit, deadline) {
	const rows = await sql`
		SELECT chain_id, agent_id, agent_uri
		FROM erc8004_agents_index
		WHERE agent_uri IS NOT NULL
		  AND (last_metadata_at IS NULL OR last_metadata_at < now() - interval '7 days')
		ORDER BY last_metadata_at NULLS FIRST, registered_at DESC NULLS LAST
		LIMIT ${limit}
	`;

	let done = 0;
	for (const row of rows) {
		// Each row may fetch a slow external URL; stop before the cron's hard
		// budget so a long IPFS tail can't push the function into a 504.
		if (deadline && Date.now() > deadline) break;
		try {
			const meta = await erc8004FetchAgentMetadata(row.agent_uri);
			if (!meta) {
				await sql`
					UPDATE erc8004_agents_index
					SET metadata_error = 'fetch failed',
					    last_metadata_at = now()
					WHERE chain_id = ${row.chain_id} AND agent_id = ${row.agent_id}
				`;
				continue;
			}
			const name = erc8004Truncate(meta.name || '', 200);
			const description = erc8004Truncate(meta.description || '', 1000);
			const image = erc8004ResolveGateway(meta.image || '');
			const services = Array.isArray(meta.services) ? meta.services : [];
			const avatarSvc = services.find(
				(s) => String(s?.name || '').toLowerCase() === 'avatar' && s?.endpoint,
			);
			const glbUrl = avatarSvc ? erc8004ResolveGateway(avatarSvc.endpoint) : null;
			const has3d = !!glbUrl;
			// `meta` is attacker-controlled — it is whatever the agent's owner published
			// on-chain. Letting `meta.active` alone decide visibility means a third party
			// chooses what name three.ws renders: one Base-registered agent's name was a
			// racial slur, active and shown on /marketplace. Withhold those rows.
			// Every public feed already filters `active = true`, so this single flag
			// covers explore, marketplace, agents and search. Slurs only, never general
			// profanity — a false positive silently delists a legitimate agent.
			const slur = matchedSlurStem(`${name} ${description}`);
			if (slur) {
				console.warn('[crawl] withholding agent: slur in on-chain metadata', {
					chain_id: row.chain_id,
					agent_id: row.agent_id,
					matched: slur,
				});
			}
			const active = meta.active !== false && !slur;
			const x402 = !!(meta.x402Support || meta.x402);

			await sql`
				UPDATE erc8004_agents_index
				SET name = ${name || null},
				    description = ${description || null},
				    image = ${image || null},
				    glb_url = ${glbUrl},
				    services = ${JSON.stringify(services)}::jsonb,
				    has_3d = ${has3d},
				    active = ${active},
				    x402_support = ${x402},
				    metadata_error = null,
				    last_metadata_at = now()
				WHERE chain_id = ${row.chain_id} AND agent_id = ${row.agent_id}
			`;
			done += 1;
		} catch (err) {
			await sql`
				UPDATE erc8004_agents_index
				SET metadata_error = ${erc8004Truncate(err.message || String(err), 500)},
				    last_metadata_at = now()
				WHERE chain_id = ${row.chain_id} AND agent_id = ${row.agent_id}
			`;
		}
	}
	return done;
}

async function erc8004RpcCall(urls, method, params) {
	const urlList = Array.isArray(urls) ? urls : [urls];
	let lastErr;
	// The one lane failure the caller can act on, kept across the whole chain of
	// lanes. Reporting only the LAST lane's error buries it: on 2026-09-02 one
	// chain's first lane said plainly that it no longer holds the blocks the
	// cursor points at, its final lane answered a generic `limit exceeded`, and
	// the crawl saw only the second. So the cursor never learned to skip the
	// unreachable span and the chain sat stale for eight days. A retention wall
	// outranks a busy provider because it is the diagnosis that ends the stall.
	let retentionErr = null;
	for (const url of urlList) {
		const ac = new AbortController();
		const t = setTimeout(() => ac.abort(), ERC8004_FETCH_TIMEOUT_MS);
		try {
			const res = await fetch(url, {
				method: 'POST',
				headers: EVM_RPC_HEADERS,
				body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
				signal: ac.signal,
			});
			// Read the body BEFORE the status. Providers that gate archive ranges
			// answer with a real JSON-RPC error under a 403, and throwing on the
			// status alone reduced that to "HTTP 403 from <host>", which no
			// rejection predicate can classify and no recovery can act on.
			const data = await res.json().catch(() => null);
			if (data?.error) throw new Error(`RPC ${data.error.code}: ${data.error.message}`);
			if (!res.ok) throw new Error(`HTTP ${res.status} from ${url}`);
			if (!data) throw new Error(`unreadable JSON-RPC body from ${url}`);
			return data.result;
		} catch (err) {
			lastErr = err;
			if (retentionErr === null && isPrunedHistoryRejection(err?.message || err)) retentionErr = err;
		} finally {
			clearTimeout(t);
		}
	}
	throw retentionErr ?? lastErr;
}

async function erc8004FetchAgentMetadata(uri) {
	const url = erc8004ResolveGateway(uri);
	if (!url) return null;
	try {
		// agentURI is attacker-controllable on-chain data — SSRF-guard the fetch
		// (and every redirect hop) exactly like the alert-webhook path below.
		const res = await fetchSafePublicUrl(url, {
			signal: AbortSignal.timeout(ERC8004_METADATA_TIMEOUT_MS),
		});
		if (!res.ok) return null;
		return await res.json();
	} catch {
		return null;
	}
}

function erc8004ResolveGateway(uri) {
	if (!uri || typeof uri !== 'string') return '';
	const url = resolveURI(uri);
	return url.startsWith('http://') || url.startsWith('https://') ? url : '';
}

function erc8004Truncate(s, max) {
	if (!s) return '';
	return s.length > max ? s.slice(0, max) : s;
}

// ═══════════════════════════════════════════════════════════════════════════
// index-delegations
// ═══════════════════════════════════════════════════════════════════════════

// Topic hashes are derived from the ABI so they stay in sync with contract changes.
const dmIface = new Interface(DELEGATION_MANAGER_ABI);
const DISABLED_TOPIC = dmIface.getEvent('DisabledDelegation').topicHash;
const REDEEMED_TOPIC = dmIface.getEvent('RedeemedDelegation').topicHash;

// Max blocks per eth_getLogs call. Public RPCs 429 above ~2000.
// Ethereum mainnet (chainId 1) nodes cap eth_getLogs at 50 blocks; use 25 to
// stay safely under the limit and avoid 504s.
const IDX_BLOCK_CAP = 2000;
const IDX_MAINNET_BLOCK_CAP = 25; // ETH mainnet is far more restrictive
const IDX_RPC_TIMEOUT_MS = 10_000;
// Stay this many blocks behind the chain tip. Two reasons:
//   1. idxRpc rotates across a pool of public RPCs, and they are not perfectly
//      in sync — eth_blockNumber may resolve on a node at head N while a sibling
//      serves eth_getLogs with a head of N-2, which rejects toBlock=N with
//      "block range extends beyond current head block". A small buffer keeps the
//      queried range valid on every node in the pool.
//   2. It avoids indexing blocks that can still be reorged out near the tip.
// The next tick advances the cursor and picks up the buffered blocks once they
// are safely confirmed.
const IDX_HEAD_CONFIRMATIONS = 5;
// Hard time budget per cron invocation, leaving 8 s headroom before the 30 s
// serverless limit. It covers the WHOLE tick, so it is divided across the chains
// still to be indexed rather than consumed by whichever one runs first (see
// idxChainDeadline).
const IDX_TIME_BUDGET_MS = 22_000;
// Floor on one chain's slice of that budget. Ethereum mainnet is both first in
// DELEGATION_MANAGER_DEPLOYMENTS and the slowest (its nodes cap eth_getLogs at 25
// blocks), so with a single shared deadline it spent the entire budget and every
// later chain returned zero batches on every tick. A chain that indexes nothing
// also never writes an indexer_state cursor, so it re-derived its start block from
// the head each tick and never made progress at all: Base delegation revocations
// went permanently unindexed. Each chain now gets an equal share of whatever is
// left, never less than this.
const IDX_MIN_CHAIN_SLICE_MS = 2_500;
// One cron period, matching this job's `*/5` schedule in vercel.json. Used only
// to rotate which chain is indexed first, so the offset advances by exactly one
// per tick and every chain leads once per full rotation.
const IDX_ROTATION_PERIOD_MS = 5 * 60_000;

// Wall-clock deadline for the chain about to be indexed: an even split of the
// budget that remains across the chains that remain.
function idxChainDeadline(started, chainsRemaining) {
	const left = Math.max(0, IDX_TIME_BUDGET_MS - (Date.now() - started));
	return Date.now() + Math.max(IDX_MIN_CHAIN_SLICE_MS, Math.floor(left / Math.max(1, chainsRemaining)));
}

// Approximate blocks per day, used only to seed the cursor on first run.
const BLOCKS_PER_DAY = {
	84532: 43200, // Base Sepolia ~2 s/block
	11155111: 7200, // Sepolia ~12 s/block
};

// Public RPC fallbacks per chain — tried in order. Override primary via env
// RPC_URL_<chainId> with a keyed provider (Alchemy/Infura/Quicknode); the env
// URL is always tried first (see idxRpcUrls). The public fallbacks below are a
// best-effort safety net only, so prod SHOULD still set RPC_URL_1 / RPC_URL_8453
// for the most reliable indexing — but the keyless set is curated to ones that
// actually answer eth_getLogs from a serverless datacenter IP.
//
// Why these and not the "obvious" ones — every endpoint below was probed live for
// eth_blockNumber AND eth_getLogs from a datacenter host:
//   • eth.llamarpc.com / base.llamarpc.com / *.llamarpc.com → now sit behind a
//     Cloudflare "Just a moment…" bot challenge that hard-403s every server-side
//     POST (no browser to solve the JS challenge). They were the FIRST entry in
//     the old chain 1 list, so every tick burned an attempt on a guaranteed 403.
//   • cloudflare-eth.com → endpoint sunset (-32046 "Cannot fulfill request").
//   • rpc.sepolia.org / rpc2.sepolia.org → dead (404 / no route).
//   • rpc.ankr.com/<chain> keyless → "Unauthorized: authenticate with an API key"
//     (handled in idxRpcUrls: rewritten to the keyed form when ANKR_API_KEY is
//     set, dropped otherwise so it never wastes an attempt).
//   • *.publicnode.com → answers fine from most hosts but 403s from Vercel's IAD
//     egress range, so it is demoted to LAST (best-effort) rather than relied on —
//     it was the surfaced "RPC HTTP 403 from …publicnode.com" storm.
// Leading providers (dRPC, 1rpc, mevblocker, ethpandaops, tenderly) are
// independent operators verified serving eth_getLogs keyless from a datacenter,
// so a single one being throttled or blocked still leaves a working lane.
const PUBLIC_RPCS = {
	1: [
		'https://eth.drpc.org',
		'https://1rpc.io/eth',
		'https://rpc.mevblocker.io',
		'https://rpc.ankr.com/eth',
		'https://ethereum-rpc.publicnode.com',
	],
	8453: [
		'https://mainnet.base.org',
		'https://base.drpc.org',
		'https://1rpc.io/base',
		'https://rpc.ankr.com/base',
		'https://base-rpc.publicnode.com',
	],
	84532: [
		'https://sepolia.base.org',
		'https://base-sepolia.drpc.org',
		'https://base-sepolia.gateway.tenderly.co',
		'https://rpc.ankr.com/base_sepolia',
		'https://base-sepolia-rpc.publicnode.com',
	],
	11155111: [
		'https://sepolia.drpc.org',
		'https://1rpc.io/sepolia',
		'https://rpc.sepolia.ethpandaops.io',
		'https://sepolia.gateway.tenderly.co',
		'https://rpc.ankr.com/eth_sepolia',
		'https://ethereum-sepolia-rpc.publicnode.com',
	],
	421614: [
		'https://sepolia-rollup.arbitrum.io/rpc',
		// PublicNode serves testnets at the `<chain>-rpc` subdomain (cf. the working
		// base-/ethereum-sepolia entries above). The bare `arbitrum-sepolia.publicnode.com`
		// host has no RPC service and answered every request with a hard 403 — fixed
		// to the canonical `-rpc` form so failover lands on a live node.
		'https://arbitrum-sepolia-rpc.publicnode.com',
		// Tenderly's keyless public gateway — an independent provider so a single
		// node's outage/throttle doesn't blank the rotation.
		'https://arbitrum-sepolia.gateway.tenderly.co',
		'https://rpc.ankr.com/arbitrum_sepolia',
	],
	11155420: [
		'https://sepolia.optimism.io',
		// Same PublicNode testnet `-rpc` correction as Arbitrum Sepolia above.
		'https://optimism-sepolia-rpc.publicnode.com',
		'https://optimism-sepolia.gateway.tenderly.co',
		'https://rpc.ankr.com/optimism_sepolia',
	],
};

function idxRpcUrls(chainId) {
	const envUrl = process.env[`RPC_URL_${chainId}`];
	// Paid metered reserve (e.g. a Quicknode credit-funded endpoint) appended
	// AFTER every free public fallback: it bills against a monthly quota, so it
	// should only serve when the whole free chain is down or throttled — the
	// inverse of RPC_URL_<chainId>, which is tried first.
	const lastResortUrl = process.env[`RPC_URL_${chainId}_LAST_RESORT`];
	const ankrKey = process.env.ANKR_API_KEY;
	// Ankr sunset keyless access: every https://rpc.ankr.com/<chain> call now
	// returns "Unauthorized: authenticate with an API key", so a keyless entry
	// is a guaranteed failed attempt + error log each run. With a key, rewrite
	// to Ankr's authenticated form (…/<chain>/<KEY>); without one, drop it so
	// failover lands on a working public node instead.
	// PublicNode hard-403s from Vercel's egress range (see PUBLIC_RPCS note). On a
	// Vercel deployment that endpoint is a guaranteed failed attempt — it both
	// wastes a failover slot and is the source of the "RPC HTTP 403 from
	// …publicnode.com" error storm — so drop it there. It stays in the rotation for
	// self-hosted / non-Vercel runs where it answers normally.
	const onVercel = !!process.env.VERCEL;
	const fallbacks = (PUBLIC_RPCS[chainId] ?? [])
		.map((url) => {
			if (onVercel && url.includes('.publicnode.com')) return null;
			if (!url.startsWith('https://rpc.ankr.com/')) return url;
			return ankrKey ? `${url}/${ankrKey}` : null;
		})
		.filter(Boolean);
	const urls = envUrl ? [envUrl, ...fallbacks] : fallbacks;
	if (lastResortUrl && !urls.includes(lastResortUrl)) urls.push(lastResortUrl);
	return urls;
}

async function handleIndexDelegations(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const started = Date.now();
	const report = { chains: [], skippedChains: [], expiredSwept: 0, errors: [] };

	// Index each chain independently — one chain's RPC failure must not abort others.
	//
	// The lead position is rotated per tick. Every chain is guaranteed at least one
	// batch once it is started (a chain that indexes nothing never writes a cursor,
	// so it would re-derive its start block from the head forever and never make
	// progress), which means a slow chain can push the tail of the list past the
	// budget. Rotating puts a different chain at the front each tick, so the tail
	// is never the same chain twice and the budget stays a real ceiling.
	const deployments = Object.entries(DELEGATION_MANAGER_DEPLOYMENTS);
	const offset = Math.floor(started / IDX_ROTATION_PERIOD_MS) % deployments.length;
	const ordered = deployments.map((_, i) => deployments[(i + offset) % deployments.length]);

	for (const [i, [chainIdStr, contract]] of ordered.entries()) {
		const chainId = Number(chainIdStr);
		// Budget spent: leave the rest for the next tick, which will lead with a
		// chain further along the rotation.
		if (i > 0 && Date.now() - started > IDX_TIME_BUDGET_MS) {
			report.skippedChains.push(chainId);
			continue;
		}
		const t0 = Date.now();
		try {
			const r = await idxIndexChain(chainId, contract, idxChainDeadline(started, ordered.length - i));
			const summary = { chainId, ...r, elapsedMs: Date.now() - t0 };
			report.chains.push(summary);
			console.log(JSON.stringify({ stage: 'index-delegations', ...summary }));
		} catch (err) {
			const entry = { chainId, error: err.message || String(err) };
			report.errors.push(entry);
			console.error(JSON.stringify({ stage: 'index-delegations', ...entry }));
		}
	}

	// Expiry sweep — idempotent, catches expirations missed between grant and indexer.
	try {
		const swept = await sql`
			UPDATE agent_delegations
			SET status = 'expired'
			WHERE status = 'active' AND expires_at < NOW()
			RETURNING id
		`;
		report.expiredSwept = swept.length;
	} catch (err) {
		report.errors.push({ stage: 'expiry-sweep', error: err.message || String(err) });
		console.error(JSON.stringify({ stage: 'expiry-sweep', error: err.message }));
	}

	// Emit summary to usage_events (best-effort — non-fatal if table shape differs).
	try {
		await sql`
			INSERT INTO usage_events (kind, tool, status, latency_ms)
			VALUES ('permissions.indexer.tick', 'index-delegations', 'ok', ${Date.now() - started})
		`;
	} catch {
		/* non-fatal */
	}

	return json(res, 200, report);
}

async function idxIndexChain(chainId, contract, deadline = Date.now() + IDX_TIME_BUDGET_MS) {
	const urls = idxRpcUrls(chainId);
	if (!urls.length) throw new Error(`no RPC URL configured for chain ${chainId}`);

	// Per-chain batch size: ETH mainnet nodes cap eth_getLogs at 50 blocks.
	const BATCH = chainId === 1 ? IDX_MAINNET_BLOCK_CAP : IDX_BLOCK_CAP;

	const headHex = await idxRpc(urls, 'eth_blockNumber', []);
	// Index only up to a confirmed head, never the raw tip — see
	// IDX_HEAD_CONFIRMATIONS for why (cross-RPC head skew + reorg safety).
	const latestBlock = Math.max(0, parseInt(headHex, 16) - IDX_HEAD_CONFIRMATIONS);

	const [cursor] = await sql`
		SELECT last_indexed_block FROM indexer_state
		WHERE contract = ${contract.toLowerCase()} AND chain_id = ${chainId}
	`;
	const initialFrom = cursor
		? Number(cursor.last_indexed_block) + 1
		: Math.max(0, latestBlock - (BLOCKS_PER_DAY[chainId] ?? 7200));

	let fromBlock = initialFrom;
	// Seeded one block BEFORE the start so a chain that runs no batch at all
	// reports the empty range it actually covered. Seeding it to latestBlock made
	// a starved chain's summary read as a full successful scan.
	let toBlock = initialFrom - 1; // updated each iteration; reflects final processed range
	let batches = 0;
	let revokedCount = 0;
	let redeemedCount = 0;
	let logErrorCount = 0;
	let earlyExit = false;

	while (fromBlock <= latestBlock) {
		// Time budget: save cursor and break before the function times out. Checked
		// at the top of the loop, so a chain always gets at least one batch even
		// when the earlier chains overran.
		if (batches > 0 && Date.now() > deadline) {
			console.warn(
				JSON.stringify({
					stage: 'index-delegations',
					chainId,
					warning: 'time-budget-exceeded',
					overrunMs: Date.now() - deadline,
					stoppedAtBlock: fromBlock,
				}),
			);
			earlyExit = true;
			break;
		}
		batches += 1;

		toBlock = Math.min(fromBlock + BATCH - 1, latestBlock);

		let logs;
		try {
			logs = await idxRpc(urls, 'eth_getLogs', [
				{
					address: contract,
					topics: [[DISABLED_TOPIC, REDEEMED_TOPIC]],
					fromBlock: '0x' + fromBlock.toString(16),
					toBlock: '0x' + toBlock.toString(16),
				},
			]);
		} catch (fetchErr) {
			// AbortError (batch timed out) or a transient block-range/head-skew
			// error (a lagging RPC in the rotation pool rejecting a range it
			// hasn't synced yet) — save the cursor at the start of this batch so
			// the next invocation retries it, then stop. These are not failures:
			// the cron resumes from here next tick.
			const transient =
				fetchErr.name === 'AbortError' ||
				fetchErr.name === 'TimeoutError' ||
				/beyond (the )?current head|block range|range is too large|exceeds/i.test(
					fetchErr.message || '',
				);
			if (transient) {
				console.warn(
					JSON.stringify({
						stage: 'index-delegations',
						chainId,
						warning: 'rpc-transient',
						message: fetchErr.message,
						stoppedAtBlock: fromBlock,
					}),
				);
				// Rewind cursor to fromBlock-1 so the next run retries this batch.
				await sql`
					INSERT INTO indexer_state (contract, chain_id, last_indexed_block, updated_at)
					VALUES (${contract.toLowerCase()}, ${chainId}, ${fromBlock - 1}, NOW())
					ON CONFLICT (contract, chain_id) DO UPDATE SET
						last_indexed_block = LEAST(indexer_state.last_indexed_block, ${fromBlock - 1}),
						updated_at = NOW()
				`;
				earlyExit = true;
				break;
			}
			throw fetchErr;
		}

		if (logs.length > 0) {
			// Fetch block timestamps only for blocks that have events.
			const uniqueBlocks = [...new Set(logs.map((l) => l.blockNumber))];
			const blockTs = {};
			for (const bn of uniqueBlocks) {
				const block = await idxRpc(urls, 'eth_getBlockByNumber', [bn, false]);
				blockTs[bn] = new Date(parseInt(block.timestamp, 16) * 1000).toISOString();
			}

			for (const log of logs) {
				try {
					const ts = blockTs[log.blockNumber];
					const topic = log.topics[0];

					if (topic === DISABLED_TOPIC) {
						// DisabledDelegation indexes delegationHash as topics[1].
						const delegationHash = log.topics[1];
						const rows = await sql`
							UPDATE agent_delegations
							SET status = 'revoked',
							    revoked_at = ${ts}::timestamptz,
							    tx_hash_revoke = ${log.transactionHash}
							WHERE delegation_hash = ${delegationHash} AND status = 'active'
							RETURNING id
						`;
						revokedCount += rows.length;
					} else if (topic === REDEEMED_TOPIC) {
						// RedeemedDelegation does not index delegationHash. Decode the
						// non-indexed `delegation` tuple from log.data and defer to the
						// contract's getDelegationHash() rather than reimplementing the
						// EIP-712 struct hash locally — provably matches the on-chain
						// value and survives any future ABI change to the struct.
						const parsed = dmIface.parseLog({
							topics: log.topics,
							data: log.data,
						});
						const callData = dmIface.encodeFunctionData('getDelegationHash', [
							parsed.args.delegation,
						]);
						const raw = await idxRpc(urls, 'eth_call', [
							{ to: contract, data: callData },
							'latest',
						]);
						const [delegationHash] = dmIface.decodeFunctionResult(
							'getDelegationHash',
							raw,
						);
						const rows = await sql`
							UPDATE agent_delegations
							SET redemption_count = redemption_count + 1,
							    last_redeemed_at = ${ts}::timestamptz
							WHERE delegation_hash = ${delegationHash}
							RETURNING id
						`;
						redeemedCount += rows.length;
					} else {
						// eth_getLogs filter restricts to the two topics above, so this
						// branch is unreachable under current configuration. Guard
						// anyway so future filter widening fails loudly in logs
						// rather than silently miscategorizing events.
						logErrorCount++;
						console.warn(
							JSON.stringify({
								stage: 'index-delegations',
								chainId,
								warning: 'unknown-topic',
								topic,
								tx: log.transactionHash,
							}),
						);
					}
				} catch (err) {
					// Isolate per-log failures so one bad event doesn't abort the
					// batch and force a full re-scan on the next tick.
					logErrorCount++;
					console.error(
						JSON.stringify({
							stage: 'index-delegations',
							chainId,
							error: 'log-process-failed',
							message: err.message || String(err),
							tx: log.transactionHash,
							topic: log.topics?.[0],
						}),
					);
				}
			}
		}

		// Advance cursor after each batch so a timeout preserves partial progress.
		await sql`
			INSERT INTO indexer_state (contract, chain_id, last_indexed_block, updated_at)
			VALUES (${contract.toLowerCase()}, ${chainId}, ${toBlock}, NOW())
			ON CONFLICT (contract, chain_id) DO UPDATE SET
				last_indexed_block = GREATEST(indexer_state.last_indexed_block, excluded.last_indexed_block),
				updated_at = NOW()
		`;

		fromBlock = toBlock + 1;
	}

	return {
		fromBlock: initialFrom,
		toBlock,
		batches,
		revokedCount,
		redeemedCount,
		logErrorCount,
		earlyExit,
	};
}

async function idxRpc(urls, method, params) {
	let lastErr;
	for (const url of urls) {
		const ac = new AbortController();
		const t = setTimeout(() => ac.abort(), IDX_RPC_TIMEOUT_MS);
		try {
			const res = await fetch(url, {
				method: 'POST',
				headers: EVM_RPC_HEADERS,
				body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
				signal: ac.signal,
			});
			if (!res.ok) throw new Error(`RPC HTTP ${res.status} from ${url}`);
			const data = await res.json();
			if (data.error) {
				throw new Error(
					`RPC ${method} error: ${data.error.message ?? JSON.stringify(data.error)}`,
				);
			}
			return data.result;
		} catch (err) {
			lastErr = err;
		} finally {
			clearTimeout(t);
		}
	}
	throw lastErr;
}

// ═══════════════════════════════════════════════════════════════════════════
// pump-agent-stats
// ═══════════════════════════════════════════════════════════════════════════

// Keep small: each mint makes 2-3 Solana RPC calls; public RPC rate-limits at
// 429 immediately, so large batches reliably 504 within Vercel's 30s window.
const PUMP_STATS_MAX_PER_RUN = 20;
// Per-mint cap so one stuck mint can't eat the whole run. A healthy private RPC
// answers each of the 2-3 sequential calls in a few hundred ms (~1s/mint), so a
// 4s cap is generous for real work while failing fast on a hung endpoint. The
// 22s DEADLINE below is the real total-run guard; this only bounds one mint.
const PUMP_STATS_MINT_TIMEOUT_MS = 4_000;

// Pump.fun graduation threshold (mainnet curve). Used only as a UI hint —
// progress_pct is a coarse bar, not financial advice.
const GRADUATION_REAL_SOL = 85_000_000_000n; // ~85 SOL in lamports

async function handlePumpAgentStats(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	if (!requireCron(req, res)) return;

	const mints = await sql`
		select id, mint, network, user_id, name from pump_agent_mints
		order by id limit ${PUMP_STATS_MAX_PER_RUN}
	`;

	const DEADLINE = Date.now() + 22_000;
	const report = {
		scanned: mints.length,
		updated: 0,
		errors: 0,
		graduations: 0,
		timeouts: 0,
		rate_limited: 0,
		skipped: 0,
	};
	let consecutiveRateLimit = 0;

	for (const m of mints) {
		if (Date.now() >= DEADLINE) {
			report.skipped += mints.length - mints.indexOf(m);
			break;
		}
		if (consecutiveRateLimit >= 3) {
			report.skipped += mints.length - mints.indexOf(m);
			console.log(
				JSON.stringify({
					event: 'pump_agent_stats.circuit_open',
					consecutive_429: consecutiveRateLimit,
				}),
			);
			break;
		}

		try {
			const stats = await Promise.race([
				pumpStatsSnapshotMint(m),
				new Promise((_, rej) =>
					setTimeout(
						() =>
							rej(Object.assign(new Error('snapshot timeout'), { code: 'TIMEOUT' })),
						PUMP_STATS_MINT_TIMEOUT_MS,
					),
				),
			]);

			consecutiveRateLimit = 0;

			// Detect graduation flip false→true vs prior snapshot.
			const [prior] = await sql`
				select graduated from pump_agent_stats where mint_id=${m.id} limit 1
			`;
			const justGraduated = stats.graduated && prior && !prior.graduated;

			await sql`
				insert into pump_agent_stats
					(mint_id, network, mint, graduated, bonding_curve, amm,
					 last_signature, last_signature_at, recent_tx_count, refreshed_at, error)
				values (
					${m.id}, ${m.network}, ${m.mint}, ${stats.graduated},
					${stats.bonding_curve ? JSON.stringify(stats.bonding_curve) : null}::jsonb,
					${stats.amm ? JSON.stringify(stats.amm) : null}::jsonb,
					${stats.last_signature}, ${stats.last_signature_at},
					${stats.recent_tx_count}, now(), null
				)
				on conflict (mint_id) do update set
					graduated         = excluded.graduated,
					bonding_curve     = excluded.bonding_curve,
					amm               = excluded.amm,
					last_signature    = excluded.last_signature,
					last_signature_at = excluded.last_signature_at,
					recent_tx_count   = excluded.recent_tx_count,
					refreshed_at      = now(),
					error             = null
			`;

			// Price-point time series.
			const price = pumpStatsDerivePrice(stats);
			if (price) {
				await sql`
					insert into pump_agent_price_points (mint_id, sol_per_token, market_cap_lamports, source)
					values (${m.id}, ${price.sol_per_token}, ${price.market_cap_lamports?.toString() ?? null}, ${price.source})
				`;
			}

			// Emit a self-sourced graduation signal (no upstream bot needed).
			if (justGraduated) {
				report.graduations++;
				try {
					await sql`
						insert into pumpfun_signals (wallet, agent_asset, kind, weight, payload, tx_signature)
						values (
							null, ${m.mint}, 'graduation', 0.3,
							${JSON.stringify({ source: 'pump-agent-stats', network: m.network })}::jsonb,
							${`graduated:${m.mint}:${Date.now()}`}
						)
						on conflict (tx_signature, kind) do nothing
					`;
				} catch {
					// pumpfun_signals table optional
				}

				// Tell the launch owner their coin filled its bonding curve and
				// migrated — the platform already knew this the instant the flip
				// happened but had no way to surface it until now.
				if (m.user_id) {
					publishUserEvent(m.user_id, {
						type: 'pump_launch_filled',
						name: m.name || null,
						mint: m.mint,
						link: `/launches/${encodeURIComponent(m.mint)}`,
					});
				}
			}

			report.updated++;
		} catch (e) {
			if (e.code === 'TIMEOUT') {
				report.timeouts++;
			} else if (e.code === 'RATE_LIMITED' || /429/.test(e.message)) {
				report.rate_limited++;
				consecutiveRateLimit++;
			} else {
				report.errors++;
				consecutiveRateLimit = 0;
			}
			await sql`
				insert into pump_agent_stats (mint_id, network, mint, error, refreshed_at)
				values (${m.id}, ${m.network}, ${m.mint}, ${e.message || 'snapshot failed'}, now())
				on conflict (mint_id) do update set error = excluded.error, refreshed_at = now()
			`.catch(() => {});
		}
	}

	return json(res, 200, report);
}

async function pumpStatsSnapshotMint({ network, mint }) {
	const mintPk = solanaPubkey(mint);
	if (!mintPk) throw new Error('invalid mint pubkey');

	const out = {
		graduated: false,
		bonding_curve: null,
		amm: null,
		last_signature: null,
		last_signature_at: null,
		recent_tx_count: 0,
	};

	// Bonding curve
	let curve = null;
	try {
		const { sdk } = await getPumpSdk({ network });
		if (sdk.fetchBuyState) {
			const state = await sdk.fetchBuyState(mintPk, mintPk);
			curve = state.bondingCurve;
		} else if (sdk.fetchBondingCurve) {
			curve = await sdk.fetchBondingCurve(mintPk);
		}
	} catch (e) {
		// The bonding-curve fetch is the dominant source of production 429s
		// (it runs through the single getConnection endpoint). Propagate rate
		// limiting so the outer loop's circuit breaker actually trips instead
		// of silently recording a null curve and burning the per-mint budget.
		if (/429|rate.limit|max usage/i.test(e?.message || '')) {
			throw Object.assign(new Error(`RPC 429: ${e.message}`), { code: 'RATE_LIMITED' });
		}
		curve = null;
	}

	if (curve && !curve.complete) {
		const realSol = BigInt(curve.realSolReserves?.toString?.() ?? '0');
		const pct =
			GRADUATION_REAL_SOL > 0n
				? Number((realSol * 10000n) / GRADUATION_REAL_SOL) / 100
				: null;
		out.bonding_curve = {
			real_sol: realSol.toString(),
			real_token: curve.realTokenReserves?.toString?.() ?? null,
			virtual_sol: curve.virtualSolReserves?.toString?.() ?? null,
			virtual_token: curve.virtualTokenReserves?.toString?.() ?? null,
			complete: curve.complete ?? false,
			progress_pct: pct != null ? Math.min(100, Math.max(0, pct)) : null,
		};
	} else {
		// Try AMM pool
		try {
			const amm = await getAmmPoolState({ network, mint: mintPk });
			out.graduated = true;
			out.amm = {
				pool: amm.poolKey.toString(),
				base_reserve: amm.baseReserve.toString(),
				quote_reserve: amm.quoteReserve.toString(),
				// Quotes price against vault + virtual; expose both so a consumer
				// of this snapshot can reproduce the same numbers.
				virtual_quote_reserves: amm.virtualQuoteReserves.toString(),
				effective_quote_reserve: amm.effectiveQuoteReserve.toString(),
				lp_supply: amm.pool.lpSupply?.toString?.() ?? null,
			};
		} catch (e) {
			if (e.code !== 'pool_not_found') throw e;
			// graduated state inferred from curve.complete only
			if (curve?.complete) out.graduated = true;
		}
	}

	// Recent activity snapshot via RPC. withFallback is the wrapper's call
	// surface — it rotates across SOLANA_RPC_FALLBACK_URLS on 429/5xx. Calling
	// RPC methods directly on the RpcFallback instance is a TypeError (the
	// wrapper has no such method), so this must go through withFallback.
	try {
		const rpc = getRpcFallback({ network });
		const sigs = await rpc.withFallback((conn) =>
			conn.getSignaturesForAddress(mintPk, { limit: 50 }),
		);
		out.recent_tx_count = sigs.length;
		if (sigs.length > 0) {
			out.last_signature = sigs[0].signature;
			if (sigs[0].blockTime) {
				out.last_signature_at = new Date(sigs[0].blockTime * 1000).toISOString();
			}
		}
	} catch (e) {
		if (/429|rate.limit|max usage/i.test(e?.message || '')) {
			throw Object.assign(new Error(`RPC 429: ${e.message}`), { code: 'RATE_LIMITED' });
		}
		// Other RPC hiccup — leave activity fields null
	}

	return out;
}

// Compute coarse sol-per-token + market_cap_lamports from a stats snapshot.
// Bonding curve: virtual_sol / virtual_token (the AMM-style invariant pump uses).
// AMM: quote_reserve / base_reserve.
function pumpStatsDerivePrice(stats) {
	if (stats.bonding_curve) {
		const vSol = Number(stats.bonding_curve.virtual_sol || 0);
		const vTok = Number(stats.bonding_curve.virtual_token || 0);
		if (vSol > 0 && vTok > 0) {
			const sol_per_token = vSol / vTok;
			// total supply ≈ virtual_token + real_token (heuristic, sufficient for charting)
			const totalTok =
				BigInt(stats.bonding_curve.virtual_token || 0) +
				BigInt(stats.bonding_curve.real_token || 0);
			const market_cap_lamports =
				totalTok > 0n ? BigInt(Math.floor(sol_per_token * Number(totalTok))) : null;
			return { sol_per_token, market_cap_lamports, source: 'bonding_curve' };
		}
	}
	if (stats.amm) {
		const q = Number(stats.amm.quote_reserve || 0);
		const b = Number(stats.amm.base_reserve || 0);
		if (q > 0 && b > 0) {
			return { sol_per_token: q / b, market_cap_lamports: null, source: 'amm' };
		}
	}
	return null;
}

// ═══════════════════════════════════════════════════════════════════════════
// pumpfun-monitor
// ═══════════════════════════════════════════════════════════════════════════

const PUMPFUN_MONITOR_MAX_PER_RUN = 50;
const WHALE_TRADE_USD_FLOOR = 1_000;

async function handlePumpfunMonitor(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	// Heartbeat + per-user alert evaluation run on every tick regardless of
	// attester provisioning, so /api/healthz reports real bot status and the
	// dashboard's server-side alerts fire even when no tab is open.
	await writeBotHeartbeat();
	const alertReport = await runPumpAlertRules().catch((e) => ({
		error: e?.message || String(e),
	}));

	if (!process.env.ATTEST_AGENT_SECRET_KEY) {
		// Skip the attestation work cleanly when the attester key isn't
		// provisioned — returning 503 every 3 min would mark the cron job as
		// failing in the dashboard. Heartbeat + alerts above already ran.
		return json(res, 200, {
			skipped: true,
			reason: 'attester_not_configured',
			heartbeat: true,
			alerts: alertReport,
		});
	}

	// Pull the latest stats joined with the agent's Metaplex Core asset and
	// the prior cursor state. Only consider mints whose stats have changed
	// since the last cursor checkpoint.
	const rows = await sql`
		select
			m.id            as mint_id,
			m.mint          as token_mint,
			m.network,
			m.agent_id,
			m.agent_authority,
			s.graduated,
			s.last_signature,
			s.last_signature_at,
			a.id            as agent_row_id,
			a.user_id,
			coalesce(a.meta->'onchain'->>'sol_asset', a.meta->>'sol_mint_address') as agent_asset,
			c.last_graduated,
			c.last_authority,
			c.last_trade_signature
		from pump_agent_mints m
		join pump_agent_stats  s on s.mint_id = m.id
		join agent_identities  a on a.id = m.agent_id
		left join pumpfun_monitor_cursor c on c.mint_id = m.id
		where coalesce(a.meta->'onchain'->>'sol_asset', a.meta->>'sol_mint_address') is not null
		  and (
		     c.mint_id is null
		  or c.last_graduated      is distinct from s.graduated
		  or c.last_authority      is distinct from m.agent_authority
		  or c.last_trade_signature is distinct from s.last_signature
		  )
		order by s.refreshed_at desc nulls last
		limit ${PUMPFUN_MONITOR_MAX_PER_RUN}
	`;

	let attester;
	try {
		attester = loadAttesterKeypair();
	} catch (e) {
		// Key is present but undecodable (wrong encoding). Skip the attestation
		// work cleanly rather than 500-ing every run and marking the cron job as
		// failing — heartbeat + alerts above already ran. Surface the reason so
		// the misconfiguration is visible in the cron response/logs.
		return json(res, 200, {
			skipped: true,
			reason: e?.code === 'attester_key_undecodable' ? 'attester_key_undecodable' : 'attester_load_failed',
			detail: e?.message || String(e),
			heartbeat: true,
			alerts: alertReport,
		});
	}
	const report = {
		scanned: rows.length,
		minted: 0,
		deduped: 0,
		in_progress: 0,
		errors: 0,
		events: [],
	};

	for (const r of rows) {
		const events = detectEvents(r);
		for (const ev of events) {
			try {
				const result = await mintAttestation({
					...ev,
					agent_asset: r.agent_asset,
					network: r.network,
					token_mint: r.token_mint,
					attester,
				});
				report[
					result.status === 'minted'
						? 'minted'
						: result.status === 'deduped'
							? 'deduped'
							: 'in_progress'
				]++;
				report.events.push({
					mint: r.token_mint,
					type: ev.event_type,
					status: result.status,
					signature: result.signature,
				});
			} catch (e) {
				report.errors++;
				report.events.push({
					mint: r.token_mint,
					type: ev.event_type,
					status: 'error',
					error: e?.message || String(e),
				});
			}
		}

		// Always update the cursor — even when nothing was emitted — so we
		// don't re-scan unchanged rows next tick.
		await sql`
			insert into pumpfun_monitor_cursor (mint_id, last_graduated, last_authority, last_trade_signature, last_processed_at)
			values (${r.mint_id}, ${r.graduated}, ${r.agent_authority}, ${r.last_signature}, now())
			on conflict (mint_id) do update set
				last_graduated       = excluded.last_graduated,
				last_authority       = excluded.last_authority,
				last_trade_signature = excluded.last_trade_signature,
				last_processed_at    = now()
		`;
	}

	report.alerts = alertReport;
	report.heartbeat = true;
	return json(res, 200, report);
}

// ── Bot heartbeat ───────────────────────────────────────────────────────────
// Records that the monitor ran so /api/healthz can report real bot status.
// Best-effort: a heartbeat failure must never fail the cron run.
async function writeBotHeartbeat() {
	try {
		await sql`
			insert into bot_heartbeat (worker, mode, last_beat_at)
			values ('pumpfun-monitor', 'cron', now())
			on conflict (worker) do update set last_beat_at = now(), mode = excluded.mode
		`;
	} catch (e) {
		console.error('[pumpfun-monitor] heartbeat failed:', e?.message || e);
	}
}

// ── Server-side alert delivery ──────────────────────────────────────────────
// Pump dashboard alert rules are evaluated and delivered by the dedicated runner
// module (api/_lib/pump-alert-runner.js), invoked as runPumpAlertRules() at the
// top of handlePumpfunMonitor. It matches every enabled pump_alert_rules row
// against the live pump.fun event stream (graduations, agent mints, prices,
// whale buys), honors each rule's cooldown, dedupes, and fans matches out across
// the in-app / webhook / Telegram delivery channels with per-channel isolation.

/** Map a single (stats, cursor) row to the attestation events to emit. */
function detectEvents(r) {
	const out = [];
	const slot_or_ts = r.last_signature_at ? new Date(r.last_signature_at).getTime() : Date.now();

	// Graduation flip false -> true.
	if (r.graduated === true && r.last_graduated !== true) {
		out.push({
			event_type: 'graduation',
			source: 'pumpfun.graduation',
			event_id: deriveEventId({
				event_type: 'graduation',
				mint: r.token_mint,
				slot_or_ts: 'final',
			}),
			task_id: `pumpfun:${r.token_mint}:graduation`,
			detail: { network: r.network },
		});
	}

	// CTO: agent_authority changed (creator takeover).
	if (r.agent_authority && r.last_authority && r.agent_authority !== r.last_authority) {
		out.push({
			event_type: 'cto_detected',
			source: 'pumpfun.cto',
			event_id: deriveEventId({
				event_type: 'cto',
				mint: r.token_mint,
				slot_or_ts: `${r.last_authority}->${r.agent_authority}`,
			}),
			task_id: `pumpfun:${r.token_mint}:cto:${slot_or_ts}`,
			detail: { from: r.last_authority, to: r.agent_authority, network: r.network },
		});
	}

	return out;
}

// Exported for tests.
export { detectEvents, WHALE_TRADE_USD_FLOOR };

// ═══════════════════════════════════════════════════════════════════════════
// pumpfun-signals
// ═══════════════════════════════════════════════════════════════════════════

const CLAIMS_PER_RUN = 200;
const GRADS_PER_RUN = 50;
const WHALES_PER_RUN = 100;
const MINTS_PER_RUN = 100;
// Leave headroom under Vercel's function limit. The sources are cheap (Redis
// lrange + one Postgres read), but the per-signal inserts are sequential, so a
// budget keeps a large backlog from running long on a cold DB.
const SIGNALS_TIME_BUDGET_MS = 22_000;

const SIGNAL_WEIGHT = {
	first_claim: +0.2,
	graduation: +0.3,
	influencer: +0.2,
	whale_buy: +0.1,
	launch: +0.05,
	new_account: -0.2,
	fake_claim: -0.6,
};

async function handlePumpfunSignals(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	// Every source below is real and bot-independent:
	//   • graduations — pumpfunMcp.graduations() reads the WS-fed
	//     pumpfun_graduations table (kept live by pumpfun-graduations-sync), or
	//     the upstream bot when PUMPFUN_BOT_URL is set.
	//   • claims      — the bot's getRecentClaims (rich tier/age intel) when
	//     configured, merged with the pf:claims Redis lane the channel feed uses.
	//   • whales      — pf:whales Redis lane (first whale-buy events).
	//   • mints       — pf:mints Redis lane (new token launches).
	// The cron emits whatever is live and degrades gracefully when a lane is
	// empty; it never fabricates events.
	const botEnabled = pumpfunBotEnabled();
	const deadline = Date.now() + SIGNALS_TIME_BUDGET_MS;

	const [claimsBot, grads, redisClaims, whales, mints] = await Promise.all([
		botEnabled
			? pumpfunMcp.recentClaims({ limit: CLAIMS_PER_RUN }).catch((e) => ({ ok: false, error: e?.message }))
			: Promise.resolve({ ok: false }),
		pumpfunMcp.graduations({ limit: GRADS_PER_RUN }).catch((e) => ({ ok: false, error: e?.message })),
		getClaims(CLAIMS_PER_RUN).catch(() => []),
		getWhales(WHALES_PER_RUN).catch(() => []),
		getMints(MINTS_PER_RUN).catch(() => []),
	]);

	// Bot claims carry richer intel (tier, github_account_age_days); the Redis
	// lane is a bot-free fallback. Merge with bot enrichment winning on tx
	// collisions.
	const claimItems = pumpfunMergeBySig(
		pumpfunArr(claimsBot.ok ? claimsBot.data : null),
		Array.isArray(redisClaims) ? redisClaims : [],
	);
	const gradItems = pumpfunArr(grads.ok ? grads.data : null);
	const whaleItems = Array.isArray(whales) ? whales : [];
	const mintItems = Array.isArray(mints) ? mints : [];

	const report = {
		bot: botEnabled,
		sources: {
			claims: claimItems.length,
			graduations: gradItems.length,
			whales: whaleItems.length,
			mints: mintItems.length,
		},
		inserted: 0,
		skipped_unlinked: 0,
		skipped_by_cursor: 0,
		errors: [],
	};

	// Resolve every actor wallet → linked agent asset in a single query, and load
	// the per-source cursors so we only evaluate events newer than last run.
	const wallets = pumpfunCollectWallets({
		claims: claimItems,
		grads: gradItems,
		whales: whaleItems,
		mints: mintItems,
	});
	const [linked, cursors] = await Promise.all([
		pumpfunLinkedWalletMap(wallets),
		pumpfunLoadCursors(),
	]);

	// Process each source through its cursor. Graduations are the highest-signal,
	// always-on lane, so they run first within the time budget.
	await pumpfunProcessSource({
		source: 'graduations', items: gradItems, cursors, linked, report, deadline,
		walletOf: (ev) => ev.creator || ev.dev_wallet,
		signalsOf: (ev) => [{
			kind: 'graduation',
			payload: { mint: ev.mint, symbol: ev.symbol, name: ev.name },
			tx_signature: ev.tx_signature || ev.signature,
		}],
	});
	await pumpfunProcessSource({
		source: 'claims', items: claimItems, cursors, linked, report, deadline,
		walletOf: (ev) => ev.claimer || ev.github_wallet,
		signalsOf: (ev) => pumpfunSignalsFromClaim(ev),
	});
	await pumpfunProcessSource({
		source: 'whales', items: whaleItems, cursors, linked, report, deadline,
		walletOf: (ev) => ev.buyer || ev.trader || ev.traderPublicKey,
		signalsOf: (ev) => [{
			kind: 'whale_buy',
			payload: { mint: ev.mint, amount_sol: ev.amount_sol ?? ev.sol_amount ?? null },
			tx_signature: ev.signature || ev.tx_signature,
		}],
	});
	await pumpfunProcessSource({
		source: 'mints', items: mintItems, cursors, linked, report, deadline,
		walletOf: (ev) => ev.creator || ev.traderPublicKey,
		signalsOf: (ev) => [{
			kind: 'launch',
			payload: { mint: ev.mint, symbol: ev.symbol, name: ev.name },
			tx_signature: ev.signature || ev.tx_signature,
		}],
	});

	return json(res, 200, report);
}

// Normalize a feed event's timestamp to epoch milliseconds. pump.fun lanes use
// epoch seconds; the graduations table may surface ISO strings. Falls back to
// now() so an event without a timestamp is still treated as fresh (processed
// once, then skipped by the cursor next run).
function pumpfunTsMs(ev) {
	const t = ev?.timestamp ?? ev?.created_at ?? ev?._seen_at ?? ev?.seen_at ?? null;
	if (t == null) return Date.now();
	if (typeof t === 'number') return t < 1e12 ? Math.round(t * 1000) : Math.round(t);
	const parsed = Date.parse(t);
	return Number.isFinite(parsed) ? parsed : Date.now();
}

// Walk a newest-first event list, emitting signals only for events at or after
// the stored cursor and only for wallets linked to an agent. Advances the
// cursor to the newest event timestamp seen (never backwards) so the next run
// skips everything older. Events strictly older than the cursor are counted in
// report.skipped_by_cursor and never re-inserted.
async function pumpfunProcessSource({ source, items, cursors, linked, report, deadline, walletOf, signalsOf }) {
	const cursorMs = cursors.get(source) ?? 0;
	let maxMs = cursorMs;
	let newestSig = null;

	for (const ev of items) {
		if (Date.now() > deadline) break;

		const tsMs = pumpfunTsMs(ev);
		if (tsMs < cursorMs) {
			report.skipped_by_cursor++;
			continue;
		}
		// Track the high-water mark across all events (linked or not) so we don't
		// re-evaluate already-seen events next run.
		if (tsMs > maxMs) {
			maxMs = tsMs;
			newestSig = ev.signature || ev.tx_signature || newestSig;
		}

		const wallet = walletOf(ev);
		if (!wallet || !linked.has(wallet)) {
			report.skipped_unlinked++;
			continue;
		}

		try {
			for (const sig of signalsOf(ev)) {
				if (!sig.tx_signature) continue;
				const ok = await pumpfunInsertSignal({
					wallet,
					agent_asset: linked.get(wallet) || null,
					kind: sig.kind,
					weight: SIGNAL_WEIGHT[sig.kind] ?? 0,
					payload: sig.payload,
					tx_signature: sig.tx_signature,
				});
				if (ok) report.inserted++;
			}
		} catch (err) {
			report.errors.push({ source, tx: ev.signature || ev.tx_signature, error: err.message });
		}
	}

	if (maxMs > cursorMs) {
		await pumpfunSaveCursor(source, maxMs, newestSig).catch((e) =>
			report.errors.push({ source, stage: 'cursor', error: e?.message || String(e) }),
		);
	}
}

// Merge two event lists, deduping by signature with `primary` winning. Used to
// fold the bot's rich claims over the bot-free Redis lane.
function pumpfunMergeBySig(primary, secondary) {
	const seen = new Set();
	const out = [];
	for (const e of [...primary, ...secondary]) {
		const sig = e?.signature || e?.tx_signature;
		if (!sig || seen.has(sig)) continue;
		seen.add(sig);
		out.push(e);
	}
	return out;
}

// Load every source cursor in one read. Returns source → last_seen_ms. A missing
// cursor table (not migrated yet) degrades to "no cursor" so the cron still runs.
async function pumpfunLoadCursors() {
	const map = new Map();
	try {
		const rows = await sql`select source, last_seen_ms from pumpfun_signals_cursor`;
		for (const r of rows) map.set(r.source, Number(r.last_seen_ms) || 0);
	} catch {
		// cursor table absent — process once, then it's created on first save.
	}
	return map;
}

async function pumpfunSaveCursor(source, lastSeenMs, lastSignature) {
	await sql`
		insert into pumpfun_signals_cursor (source, last_seen_ms, last_signature, updated_at)
		values (${source}, ${Math.floor(lastSeenMs)}, ${lastSignature || null}, now())
		on conflict (source) do update set
			last_seen_ms   = greatest(pumpfun_signals_cursor.last_seen_ms, excluded.last_seen_ms),
			last_signature = excluded.last_signature,
			updated_at     = now()
	`;
}

// ═══════════════════════════════════════════════════════════════════════════
// pumpfun-graduations-sync
// ═══════════════════════════════════════════════════════════════════════════
//
// Keeps the `pumpfun_graduations` table fresh independently of browser traffic.
//
// The live feed (api/_lib/pumpfun-ws-feed.js) only persists graduations while a
// /api/pump SSE stream is open — on a serverless platform that means the table
// goes stale whenever nobody is watching the feed. This cron opens the same
// real PumpPortal migration stream for a bounded window each run; the feed's
// own persistGraduation() writes any graduations it observes, so
// /api/pump/recent-graduations and the MCP graduations tool stay live. No
// external bot or API key required — it's the public PumpPortal WebSocket.

// Must finish inside economy-tick's 60s per-engine budget (CALL_TIMEOUT_MS in
// api/cron/economy-tick.js) — the every-minute heartbeat is this handler's only
// real scheduler (its own vercel.json cron entry sits past Vercel's 40-cron
// cutoff and never fires). A 100s window here read as `failed: timeout` on
// every tick and stacked overlapping PumpPortal sockets.
const GRAD_SYNC_WINDOW_MS = 45_000;

async function handlePumpfunGraduationsSync(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const { connectPumpFunFeed } = await import('../_lib/pumpfun-ws-feed.js');

	const controller = new AbortController();
	const seen = new Map(); // tx signature → { mint, symbol }

	const stop = connectPumpFunFeed({
		kind: 'graduation',
		signal: controller.signal,
		onEvent: ({ kind, data }) => {
			if (kind !== 'graduation') return;
			const sig = data?.tx_signature || data?.signature;
			if (sig && !seen.has(sig)) seen.set(sig, { mint: data.mint, symbol: data.symbol || null });
		},
	});

	const before = await gradTableCount();
	await sleep(GRAD_SYNC_WINDOW_MS);
	controller.abort();
	try {
		stop?.();
	} catch {
		// stop() is best-effort — the abort already halted the feed.
	}
	// Let any in-flight enrich→persist writes settle before counting rows.
	await sleep(750);
	const after = await gradTableCount();

	return json(res, 200, {
		windowMs: GRAD_SYNC_WINDOW_MS,
		observed: seen.size,
		mints: [...seen.values()].map((v) => v.symbol || v.mint).slice(0, 25),
		table_total: after,
		inserted: before == null || after == null ? null : Math.max(0, after - before),
	});
}

async function gradTableCount() {
	try {
		const rows = await sql`select count(*)::int as n from pumpfun_graduations`;
		return rows?.[0]?.n ?? null;
	} catch (err) {
		console.warn('[pumpfun-graduations-sync] count failed:', err?.message);
		return null;
	}
}

function sleep(ms) {
	return new Promise((resolve) => setTimeout(resolve, ms));
}

function pumpfunArr(x) {
	if (!x) return [];
	return Array.isArray(x) ? x : x.items || [];
}

function pumpfunCollectWallets({ claims = [], grads = [], whales = [], mints = [] }) {
	const out = new Set();
	const add = (w) => { if (w) out.add(w); };
	for (const c of claims) { add(c.claimer); add(c.github_wallet); }
	for (const g of grads) { add(g.creator); add(g.dev_wallet); }
	for (const w of whales) { add(w.buyer); add(w.trader); add(w.traderPublicKey); }
	for (const m of mints) { add(m.creator); add(m.traderPublicKey); }
	return [...out];
}

async function pumpfunLinkedWalletMap(wallets) {
	const map = new Map();
	if (wallets.length === 0) return map;
	const rows = await sql`
		select uw.address, ai.meta->>'sol_mint_address' as agent_asset
		from user_wallets uw
		left join agent_identities ai
			on ai.user_id = uw.user_id
			and ai.deleted_at is null
			and ai.meta->>'chain_type' = 'solana'
		where uw.chain_type = 'solana'
		  and uw.address = any(${wallets})
	`;
	for (const r of rows) map.set(r.address, r.agent_asset);
	return map;
}

function pumpfunSignalsFromClaim(ev) {
	const out = [];
	// Bot claims carry tx_signature; the pf:claims Redis lane carries signature.
	const base = { tx_signature: ev.tx_signature || ev.signature, payload: ev };
	const attribution = ev.attribution_status || ev.attribution;
	const verifiedRelationship = attribution === 'verified_repository'
		|| attribution === 'verified_creator_wallet'
		|| (!attribution && (ev.verified === true || ev.signal_verified === true));
	// A first withdrawal is positive reputation only when the coin relationship
	// is verified. Raw, mismatched, or pooled claims remain visible as evidence
	// but must not boost an agent/token trust score.
	if (ev.first_time_claim && verifiedRelationship) out.push({ kind: 'first_claim', ...base });
	if (ev.fake_claim) out.push({ kind: 'fake_claim', ...base });
	if (verifiedRelationship && (ev.tier === 'mega' || ev.tier === 'influencer')) {
		out.push({ kind: 'influencer', ...base });
	}
	if (ev.github_account_age_days != null && ev.github_account_age_days < 30) {
		out.push({ kind: 'new_account', ...base });
	}
	return out;
}

async function pumpfunInsertSignal({ wallet, agent_asset, kind, weight, payload, tx_signature }) {
	if (!tx_signature) return false;
	const result = await sql`
		insert into pumpfun_signals (wallet, agent_asset, kind, weight, payload, tx_signature)
		values (${wallet}, ${agent_asset}, ${kind}, ${weight}, ${JSON.stringify(payload)}::jsonb, ${tx_signature})
		on conflict (tx_signature, kind) do nothing
		returning id
	`;
	return result.length > 0;
}

// ═══════════════════════════════════════════════════════════════════════════
// run-buyback
// ═══════════════════════════════════════════════════════════════════════════

async function buybackLoadRelayer() {
	const b64 = process.env.PUMP_CRON_RELAYER_SECRET_KEY_B64;
	if (!b64) return null;
	const [{ Keypair }] = await Promise.all([import('@solana/web3.js')]);
	return Keypair.fromSecretKey(Buffer.from(b64, 'base64'));
}

/**
 * Resolve the quote currency a coin's autonomous lanes (buyback, distribute) must
 * operate in. A coin's vaults, swaps, and burns all settle in its quote asset:
 * USDC for USDC-paired coins, native SOL (wSOL) for SOL-paired coins. The
 * authoritative source is the on-chain bonding curve — the same field the trade
 * builders read — so this stays correct even for coins launched before the
 * `quote_mint` column existed (their DB value is null but their curve is not).
 *
 * Falls back to the recorded `dbQuoteMint`, then to USDC (the agent earn
 * currency), when the curve can't be read — so a transient RPC miss never
 * silently switches a USDC coin onto the SOL vault.
 *
 * @returns {Promise<{ currencyStr: string, quoteSymbol: 'SOL'|'USDC'|'OTHER', source: 'chain'|'db'|'fallback' }>}
 */
async function resolveCoinQuoteCurrency({ network, mint, dbQuoteMint = null }) {
	const { resolveCustodialQuote } = await import('../_lib/pump-trade-args.js');
	try {
		const { bondingCurvePda, PUMP_SDK } = await import('@pump-fun/pump-sdk');
		const info = await getConnection({ network }).getAccountInfo(
			bondingCurvePda(solanaPubkey(mint)),
		);
		if (info) {
			const bc = PUMP_SDK.decodeBondingCurve(info);
			const q = resolveCustodialQuote(bc.quoteMint, network);
			return { currencyStr: q.quoteMint, quoteSymbol: q.quoteSymbol, source: 'chain' };
		}
	} catch {
		// fall through to the DB hint / USDC default below
	}
	if (dbQuoteMint) {
		const q = resolveCustodialQuote(dbQuoteMint, network);
		return { currencyStr: q.quoteMint, quoteSymbol: q.quoteSymbol, source: 'db' };
	}
	const usdc = network === 'devnet' ? SOLANA_USDC_MINT_DEVNET : SOLANA_USDC_MINT;
	return { currencyStr: usdc, quoteSymbol: 'USDC', source: 'fallback' };
}

// Same over-invocation disease already fixed for economy-reconcile: this
// route is also one of economy-tick.js's fan-out TARGETS, fired every minute,
// on top of its own dedicated vercel.json `0 * * * *` Cloud Scheduler job,
// with nothing stopping the two callers from overlapping. Each run reads and
// can swap/burn up to 200 coins' buyback vaults, so an overlapping run risks
// racing itself on the same vault balance, not just running long. The lease
// makes the hourly cadence durable regardless of how often the route fires;
// its TTL IS the cadence and is never explicitly released.
const BUYBACK_LEASE_KEY = 'cron:run-buyback:lease';
const BUYBACK_LEASE_SECONDS = 55 * 60;

async function handleRunBuyback(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	if (!requireCron(req, res)) return;

	if (!(await acquireLock(BUYBACK_LEASE_KEY, BUYBACK_LEASE_SECONDS))) {
		return json(res, 200, { ok: true, skipped: true, reason: 'lease_held' });
	}

	const relayer = await buybackLoadRelayer();

	// Honor per-coin autopilot policy. A missing pump_autopilot row preserves the
	// legacy "always eligible, burn-only" behaviour via coalesce, so existing
	// coins keep working until an owner opts into autopilot from /autopilot.
	const mints = await sql`
		select m.id, m.mint, m.network, m.slippage_bps, m.quote_mint,
		       coalesce(ap.buyback_full_swap, m.full_swap) as full_swap,
		       coalesce(ap.buyback_min_atomics, 0)         as buyback_min_atomics
		from pump_agent_mints m
		left join pump_autopilot ap on ap.mint_id = m.id
		where coalesce(ap.enabled, true) = true
		  and coalesce(ap.buyback_enabled, true) = true
		limit 200
	`;

	const results = [];
	for (const m of mints) {
		// Operate in the coin's quote asset — the currency its vault holds and its
		// curve swaps. USDC coins buy back with USDC, SOL coins with SOL. Anything
		// the lane can't operate in still records a run row below (never a silent
		// no-op): empty vaults → 'skipped', build/swap errors → 'failed'.
		const { currencyStr } = await resolveCoinQuoteCurrency({
			network: m.network,
			mint: m.mint,
			dbQuoteMint: m.quote_mint,
		});
		const currency = solanaPubkey(currencyStr);
		const fullSwap = m.full_swap === true;
		const minAtomics = BigInt(m.buyback_min_atomics ?? 0);

		try {
			const { agent } = await getPumpAgent({ network: m.network, mint: m.mint });
			const balances = await agent.getBalances(currency);
			const buyback = BigInt(balances.buybackVault?.balance ?? 0);

			if (buyback === 0n || buyback < minAtomics) {
				const [run] = await sql`
					insert into pump_buyback_runs (mint_id, currency_mint, status)
					values (${m.id}, ${currencyStr}, 'skipped') returning id
				`;
				results.push({
					mint: m.mint,
					status: 'skipped',
					run_id: run.id,
					reason: buyback === 0n ? 'empty' : 'below_threshold',
				});
				continue;
			}

			const { offline } = await getPumpAgentOffline({ network: m.network, mint: m.mint });
			const [{ PUMP_PROGRAM_ID }] = await Promise.all([import('@three-ws/agent-payments')]);

			const payerPk = relayer ? relayer.publicKey : solanaPubkey(m.mint);
			const params = {
				globalBuybackAuthority: payerPk, // gated by globalConfig — for skipped-swap form, can be relayer
				currencyMint: currency,
				swapProgramToInvoke: PUMP_PROGRAM_ID, // pump bonding-curve program (same for burn-only and full-swap)
				swapInstructionData: Buffer.alloc(0), // empty = skip swap, just burn
				remainingAccounts: [],
			};

			if (fullSwap) {
				const { buildPumpSwapInnerIx } = await import('../_lib/pump-swap-ix.js');
				const inner = await buildPumpSwapInnerIx({
					mint: m.mint,
					currency,
					amountIn: buyback,
					slippageBps: m.slippage_bps ?? 500,
					cluster: m.network,
				});
				params.swapInstructionData = inner.data;
				params.remainingAccounts = inner.accounts;
			}

			let ix;
			try {
				ix = await offline.buybackTrigger(params);
			} catch (e) {
				const [run] = await sql`
					insert into pump_buyback_runs (mint_id, currency_mint, swap_program, status, error)
					values (${m.id}, ${currencyStr}, ${PUMP_PROGRAM_ID.toBase58()}, 'failed', ${'buybackTrigger build failed: ' + e.message})
					returning id
				`;
				results.push({ mint: m.mint, status: 'failed', error: e.message, run_id: run.id });
				continue;
			}

			if (!relayer) {
				const txBase64 = await buildUnsignedTxBase64({
					network: m.network,
					payer: payerPk,
					instructions: [ix],
				});
				const [run] = await sql`
					insert into pump_buyback_runs (mint_id, currency_mint, swap_program, status, burn_amount)
					values (${m.id}, ${currencyStr}, ${PUMP_PROGRAM_ID.toBase58()}, 'pending', ${buyback.toString()})
					returning id
				`;
				results.push({
					mint: m.mint,
					status: 'pending',
					run_id: run.id,
					tx_base64: txBase64,
				});
				continue;
			}

			const connection = getConnection({ network: m.network });
			// Protected send: priority fee + CU estimate, rebroadcast with blockhash
			// refresh, hard throw on an on-chain revert.
			const { signature: sig } = await submitProtected({ network: m.network, connection, payer: relayer, instructions: [ix] });

			const [run] = await sql`
				insert into pump_buyback_runs
					(mint_id, currency_mint, swap_program, tx_signature, status, burn_amount)
				values
					(${m.id}, ${currencyStr}, ${PUMP_PROGRAM_ID.toBase58()}, ${sig}, 'confirmed', ${buyback.toString()})
				returning id
			`;
			results.push({ mint: m.mint, status: 'confirmed', tx_signature: sig, run_id: run.id });
		} catch (err) {
			await sql`
				insert into pump_buyback_runs (mint_id, currency_mint, status, error)
				values (${m.id}, ${currencyStr}, 'failed', ${err.message || String(err)})
			`;
			results.push({ mint: m.mint, status: 'failed', error: err.message });
		}
	}

	return json(res, 200, { ok: true, processed: results.length, results });
}

// ═══════════════════════════════════════════════════════════════════════════
// run-three-buyback — programmatic $THREE buyback (revenue → buy → treasury)
//
// Converts accumulated platform USDC revenue into onchain buy pressure: market-buy
// $THREE on Jupiter and route the bought tokens into the treasury. This is the
// documented economy policy ("the treasury funds buybacks … buy pressure without
// deflation", api/_lib/token/config.js) made programmatic, onchain, and publicly
// auditable. NO platform burn — supply is never destroyed by this lane.
//
// Every run records a row in three_buyback_runs (never a silent no-op). Execution
// is gated by THREE_BUYBACK_ENABLED + THREE_BUYBACK_SECRET_KEY_B64; `?dry_run=1`
// sizes + quotes the buy without signing, so the wiring is verifiable before a
// single dollar moves.
// ═══════════════════════════════════════════════════════════════════════════

// Same over-invocation disease fixed above for run-buyback: economy-tick.js
// fires /api/cron/run-three-buyback every minute (fan-out TARGETS) on top of
// its own dedicated vercel.json `0 6 * * *` (once daily) Cloud Scheduler job.
// Unlike run-buyback's burn-only default, a live run here sizes its spend off
// the buyback wallet's CURRENT USDC balance (computeSpend), signs a real
// Jupiter swap, and sweeps to treasury: nothing stops two overlapping real
// runs from both reading the same pre-spend balance and each deploying up to
// maxUsdPerRun(), doubling the per-run spend cap the policy relies on. The
// lease only gates the live path; a dry run never signs, so monitoring/status
// callers with ?dry_run=1 are never blocked by it.
const THREE_BUYBACK_LEASE_KEY = 'cron:run-three-buyback:lease';
const THREE_BUYBACK_LEASE_SECONDS = 23 * 60 * 60;

async function handleRunThreeBuyback(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;
	if (!requireCron(req, res)) return;

	const bb = await import('../_lib/token/buyback.js');
	const dryRunRaw = String(req.query?.dry_run ?? '').toLowerCase();
	const dryRun = dryRunRaw === '1' || dryRunRaw === 'true';

	if (!dryRun && !(await acquireLock(THREE_BUYBACK_LEASE_KEY, THREE_BUYBACK_LEASE_SECONDS))) {
		return json(res, 200, { ok: true, skipped: true, reason: 'lease_held' });
	}

	const slippage = bb.slippageBps();
	const revenueAtomics = await bb.revenueFeeAtomicsToDate();
	const revStr = revenueAtomics.toString();

	// Execution gate: a scheduled run is a recorded no-op until an operator funds
	// the wallet and opts in. A dry run is always allowed (it never signs).
	if (!dryRun && !bb.isEnabled()) {
		const [run] = await sql`
			insert into three_buyback_runs (status, reason, revenue_fee_atomics)
			values ('skipped', 'disabled', ${revStr}) returning id
		`;
		return json(res, 200, { ok: true, status: 'skipped', reason: 'disabled', run_id: run.id });
	}

	const signer = await bb.loadBuybackSigner();
	if (!signer) {
		const [run] = await sql`
			insert into three_buyback_runs (status, reason, revenue_fee_atomics)
			values ('skipped', 'not_configured', ${revStr}) returning id
		`;
		return json(res, 200, {
			ok: true,
			status: 'skipped',
			reason: 'not_configured',
			run_id: run.id,
			message: 'set THREE_BUYBACK_SECRET_KEY_B64 and fund the wallet with USDC to enable buybacks',
		});
	}

	// Self-heal a prior partial run (bought $THREE that never reached the treasury)
	// before sizing a new buy. Non-fatal: the main flow sweeps to treasury anyway.
	let recoverSig = null;
	if (!dryRun) {
		try {
			recoverSig = await bb.sweepStrandedThree(signer);
		} catch {
			recoverSig = null;
		}
	}

	let plan;
	try {
		plan = await bb.planBuyback(signer.publicKey.toBase58());
	} catch (e) {
		const code = e.code || 'plan_failed';
		const [run] = await sql`
			insert into three_buyback_runs (status, reason, revenue_fee_atomics, error)
			values ('failed', ${code}, ${revStr}, ${e.message || String(e)}) returning id
		`;
		return json(res, 200, { ok: false, status: 'failed', reason: code, error: e.message, run_id: run.id });
	}

	if (!plan.ok) {
		const [run] = await sql`
			insert into three_buyback_runs (status, reason, revenue_fee_atomics, usdc_spent_atomics)
			values ('skipped', ${plan.reason}, ${revStr}, 0) returning id
		`;
		return json(res, 200, {
			ok: true,
			status: 'skipped',
			reason: plan.reason,
			run_id: run.id,
			wallet_usdc: bb.usdcAtomicsToUsd(plan.walletUsdcAtomics),
		});
	}

	if (dryRun) {
		const [run] = await sql`
			insert into three_buyback_runs
				(status, revenue_fee_atomics, usdc_spent_atomics, three_bought_atomics, price_usd, slippage_bps)
			values
				('dry_run', ${revStr}, ${plan.spendUsdcAtomics.toString()}, ${plan.expectedThreeAtomics.toString()}, ${plan.priceUsd}, ${slippage})
			returning id
		`;
		return json(res, 200, {
			ok: true,
			status: 'dry_run',
			run_id: run.id,
			usdc_to_spend: bb.usdcAtomicsToUsd(plan.spendUsdcAtomics),
			expected_three: bb.threeAtomicsToTokens(plan.expectedThreeAtomics),
			price_usd: plan.priceUsd,
			slippage_bps: slippage,
		});
	}

	try {
		const receipt = await bb.executeBuyback(signer, plan);
		const [run] = await sql`
			insert into three_buyback_runs
				(status, revenue_fee_atomics, usdc_spent_atomics, three_bought_atomics, price_usd, slippage_bps, buy_signature, sweep_signature, treasury_wallet)
			values
				('confirmed', ${revStr}, ${plan.spendUsdcAtomics.toString()}, ${receipt.boughtAtomics.toString()}, ${receipt.priceUsd}, ${slippage}, ${receipt.buySignature}, ${receipt.sweepSignature}, ${receipt.treasury})
			returning id
		`;
		return json(res, 200, {
			ok: true,
			status: 'confirmed',
			run_id: run.id,
			recover_signature: recoverSig,
			buy_signature: receipt.buySignature,
			sweep_signature: receipt.sweepSignature,
			usdc_spent: bb.usdcAtomicsToUsd(plan.spendUsdcAtomics),
			three_bought: bb.threeAtomicsToTokens(receipt.boughtAtomics),
			price_usd: receipt.priceUsd,
		});
	} catch (e) {
		const code = e.code || 'swap_failed';
		const status = e.status === 'pending' ? 'pending' : 'failed';
		const [run] = await sql`
			insert into three_buyback_runs
				(status, reason, revenue_fee_atomics, usdc_spent_atomics, three_bought_atomics, price_usd, slippage_bps, buy_signature, sweep_signature, error)
			values
				(${status}, ${code}, ${revStr}, ${plan.spendUsdcAtomics.toString()}, ${(e.boughtAtomics ?? 0n).toString()}, ${plan.priceUsd}, ${slippage}, ${e.buySignature ?? null}, ${e.sweepSignature ?? null}, ${e.message || String(e)})
			returning id
		`;
		return json(res, 200, {
			ok: false,
			status,
			reason: code,
			error: e.message,
			run_id: run.id,
			buy_signature: e.buySignature ?? null,
		});
	}
}

// ═══════════════════════════════════════════════════════════════════════════
// run-dca
// ═══════════════════════════════════════════════════════════════════════════

const DCA_CHAIN_CONFIG = {
	84532: {
		chain: baseSepolia,
		swap_router: '0x94cC0AaC535CCDB3C01d6787D6413C739ae12bc4',
		quoter_v2: '0xC5290058841028F1614F3A6F0F5816cAd0df5E27',
	},
	8453: {
		chain: base,
		swap_router: '0x2626664c2603336E57B271c5C0b26F421741e481',
		quoter_v2: '0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a',
	},
};

const QUOTER_V2_ABI = parseAbi([
	'function quoteExactInputSingle((address tokenIn, address tokenOut, uint256 amountIn, uint24 fee, uint160 sqrtPriceLimitX96) params) external returns (uint256 amountOut, uint160 sqrtPriceX96After, uint32 initializedTicksCrossed, uint256 gasEstimate)',
]);

const SWAP_ROUTER_ABI = parseAbi([
	'function exactInputSingle((address tokenIn, address tokenOut, uint24 fee, address recipient, uint256 amountIn, uint256 amountOutMinimum, uint160 sqrtPriceLimitX96) params) external payable returns (uint256 amountOut)',
]);

const ERC20_ABI = parseAbi([
	'function approve(address spender, uint256 amount) external returns (bool)',
]);

// Uniswap V3 standard fee tier — 0.3% pool is the most liquid USDC/WETH tier
const FEE_TIER = 3000;

const DCA_RPC_TIMEOUT_MS = 10_000;
const DCA_RPC_MAX_RETRIES = 2; // total attempts = 1 + retries
const DCA_RELAYER_TIMEOUT_MS = 30_000;
const DCA_RELAYER_MAX_RETRIES = 1;
const DCA_RELAYER_RETRY_BACKOFF_MS = 1_500;

function isTableMissing(err) {
	return String(err?.message || '').includes('does not exist');
}

function dcaLog(level, event, fields = {}) {
	const line = JSON.stringify({
		level,
		event,
		ts: new Date().toISOString(),
		component: 'cron/run-dca',
		...fields,
	});
	if (level === 'error') console.error(line);
	else console.log(line);
}

function dcaIsTransient(err) {
	// Network-level & RPC transport errors
	const code = err?.code;
	const name = err?.name;
	const status = err?.status;
	if (name === 'AbortError' || name === 'TimeoutError') return true;
	if (
		code === 'ETIMEDOUT' ||
		code === 'ECONNRESET' ||
		code === 'ECONNREFUSED' ||
		code === 'ENOTFOUND' ||
		code === 'EAI_AGAIN'
	)
		return true;
	if (typeof status === 'number' && status >= 500 && status < 600) return true;
	// viem transport errors
	const msg = String(err?.message || '');
	if (/HttpRequestError|TimeoutError|fetch failed|network|socket hang up/i.test(msg)) return true;
	return false;
}

async function dcaWithRetry(fn, { retries, backoffMs = 500, label }) {
	let attempt = 0;
	// eslint-disable-next-line no-constant-condition
	while (true) {
		try {
			return await fn();
		} catch (err) {
			attempt++;
			if (attempt > retries || !dcaIsTransient(err)) throw err;
			const delay = backoffMs * 2 ** (attempt - 1);
			dcaLog('warn', 'retry', {
				label,
				attempt,
				delay_ms: delay,
				message: err?.message,
				code: err?.code,
			});
			await new Promise((r) => setTimeout(r, delay));
		}
	}
}

function dcaGetViemClient(chainId) {
	const cfg = DCA_CHAIN_CONFIG[chainId];
	if (!cfg) throw new Error(`Unsupported chainId: ${chainId}`);
	const transport = evmTransport(chainId, {
		primaryUrl: env.getRpcUrl(chainId),
		timeout: DCA_RPC_TIMEOUT_MS,
		retryCount: 0,
	});
	return createPublicClient({ chain: cfg.chain, transport });
}

/**
 * Fetch a quote twice 15s apart; abort if they diverge by more than 0.5%.
 * Returns { amountOut, divergenceBps } or throws if divergence exceeds limit.
 */
async function dcaGetVerifiedQuote(client, quoterAddress, tokenIn, tokenOut, amountIn, logCtx) {
	const params = {
		tokenIn,
		tokenOut,
		amountIn: BigInt(amountIn),
		fee: FEE_TIER,
		sqrtPriceLimitX96: 0n,
	};

	const readQuote = () =>
		client.readContract({
			address: quoterAddress,
			abi: QUOTER_V2_ABI,
			functionName: 'quoteExactInputSingle',
			args: [params],
		});

	// First quote (with retry on transient RPC failures)
	const [q1] = await dcaWithRetry(readQuote, {
		retries: DCA_RPC_MAX_RETRIES,
		backoffMs: 500,
		label: `quote1:${logCtx?.strategy_id ?? ''}`,
	});

	// Wait 15s then quote again
	await new Promise((r) => setTimeout(r, 15_000));

	const [q2] = await dcaWithRetry(readQuote, {
		retries: DCA_RPC_MAX_RETRIES,
		backoffMs: 500,
		label: `quote2:${logCtx?.strategy_id ?? ''}`,
	});

	// Divergence in basis points: |q2-q1| / q1 * 10000
	const divergenceBps = q1 === 0n ? 0 : Number(((q2 > q1 ? q2 - q1 : q1 - q2) * 10000n) / q1);

	if (divergenceBps > 50) {
		throw Object.assign(
			new Error(`Quote divergence ${divergenceBps}bps exceeds 50bps limit — aborting`),
			{ code: 'quote_divergence', divergenceBps },
		);
	}

	// Use the more conservative (lower) of the two quotes
	const amountOut = q1 < q2 ? q1 : q2;
	return { amountOut, divergenceBps };
}

function dcaBuildApproveCalldata(spender, amount) {
	return encodeFunctionData({
		abi: ERC20_ABI,
		functionName: 'approve',
		args: [spender, BigInt(amount)],
	});
}

function dcaBuildSwapCalldata(tokenIn, tokenOut, recipient, amountIn, amountOutMinimum) {
	return encodeFunctionData({
		abi: SWAP_ROUTER_ABI,
		functionName: 'exactInputSingle',
		args: [
			{
				tokenIn,
				tokenOut,
				fee: FEE_TIER,
				recipient,
				amountIn: BigInt(amountIn),
				amountOutMinimum: BigInt(amountOutMinimum),
				sqrtPriceLimitX96: 0n,
			},
		],
	});
}

async function dcaRedeemViaRelayer(delegationId, calls, logCtx) {
	const relayerUrl = `${env.APP_ORIGIN}/api/permissions/redeem`;

	const doFetch = async () => {
		const res = await fetch(relayerUrl, {
			method: 'POST',
			headers: {
				'content-type': 'application/json',
				authorization: `Bearer ${env.CRON_SECRET}`,
			},
			body: JSON.stringify({ id: delegationId, calls }),
			signal: AbortSignal.timeout(DCA_RELAYER_TIMEOUT_MS),
		});

		if (!res.ok) {
			const body = await res.json().catch(() => ({ message: res.statusText }));
			throw Object.assign(
				new Error(body.error_description || body.message || `Relayer ${res.status}`),
				{ code: body.error || 'relayer_error', status: res.status },
			);
		}
		return res.json();
	};

	return dcaWithRetry(doFetch, {
		retries: DCA_RELAYER_MAX_RETRIES,
		backoffMs: DCA_RELAYER_RETRY_BACKOFF_MS,
		label: `relayer:${logCtx?.strategy_id ?? ''}`,
	});
}

async function dcaOnPeriod(strategy) {
	const {
		id: strategyId,
		delegation_id: delegationId,
		chain_id: chainId,
		token_in: tokenIn,
		token_out: tokenOut,
		amount_per_execution: amountIn,
		slippage_bps: slippageBps,
	} = strategy;

	const cfg = DCA_CHAIN_CONFIG[chainId];
	if (!cfg)
		throw Object.assign(new Error(`No config for chainId ${chainId}`), {
			code: 'unsupported_chain',
		});

	const client = dcaGetViemClient(chainId);
	const logCtx = { strategy_id: strategyId, chain_id: chainId };

	// Get verified quote
	const { amountOut, divergenceBps } = await dcaGetVerifiedQuote(
		client,
		cfg.quoter_v2,
		tokenIn,
		tokenOut,
		amountIn,
		logCtx,
	);

	// Apply slippage: amountOutMinimum = amountOut * (10000 - slippageBps) / 10000
	const amountOutMinimum = (amountOut * BigInt(10000 - slippageBps)) / 10000n;

	// Resolve recipient — use the delegator address from the delegation row
	const [delegationRow] = await sql`
		SELECT delegator_address FROM agent_delegations
		WHERE id = ${delegationId} AND status = 'active'
		LIMIT 1
	`;
	if (!delegationRow) {
		throw Object.assign(new Error('Delegation not found or no longer active'), {
			code: 'delegation_gone',
		});
	}
	const recipient = delegationRow.delegator_address;

	// Build calls: [approve USDC → SwapRouter, exactInputSingle]
	const calls = [
		{
			to: tokenIn,
			value: '0',
			data: dcaBuildApproveCalldata(cfg.swap_router, amountIn),
		},
		{
			to: cfg.swap_router,
			value: '0',
			data: dcaBuildSwapCalldata(tokenIn, tokenOut, recipient, amountIn, amountOutMinimum),
		},
	];

	// Submit via relayer
	const result = await dcaRedeemViaRelayer(delegationId, calls, logCtx);

	return { txHash: result.txHash, quoteAmountOut: amountOut.toString(), divergenceBps };
}

async function handleRunDca(req, res) {
	// Vercel cron passes Authorization: Bearer $CRON_SECRET
	if (!requireCron(req, res)) return;

	const runId = globalThis.crypto?.randomUUID?.() ?? `run_${Date.now()}`;
	dcaLog('info', 'tick_start', { run_id: runId });

	// The schedules live in the unified order store (rail 'evm'). Adopt any row
	// an older image wrote to the legacy table first, so a rollout never strands
	// a schedule (api/_lib/dca-unified.js).
	try {
		const adopted = await adoptLegacyDcaStrategies();
		if (adopted.strategies || adopted.executions) dcaLog('info', 'legacy_adopted', { run_id: runId, ...adopted });
	} catch (err) {
		dcaLog('error', 'legacy_adopt_failed', { run_id: runId, message: err?.message });
	}

	let strategies;
	try {
		strategies = await dueEvmDca(50);
	} catch (err) {
		if (isTableMissing(err)) {
			dcaLog('info', 'tick_skip', { run_id: runId, reason: 'orders table not yet migrated' });
			return json(res, 200, { ok: true, skipped: true, reason: 'table_not_ready' });
		}
		dcaLog('error', 'fetch_due_failed', { run_id: runId, message: err?.message });
		throw err;
	}

	const results = [];
	for (const order of strategies) {
		const logCtx = { run_id: runId, strategy_id: order.id, chain_id: order.chain_id };
		const period = Number(order.schedule?.interval_seconds) || 86400;
		const strategy = {
			id: order.id,
			delegation_id: order.delegation_id,
			chain_id: order.chain_id,
			token_in: order.quote_mint,
			token_out: order.mint,
			amount_per_execution: order.amount_in_raw,
			slippage_bps: order.slippage_bps,
		};

		// Check delegation is still alive before spending gas on a quote. The
		// strategy pauses rather than dying: re-granting the permission and
		// resuming is a two-click recovery, and the owner sees the exact reason.
		const expired = order.delegation_expires_at && new Date(order.delegation_expires_at) <= new Date();
		if (order.delegation_status !== 'active' || expired) {
			const code = order.delegation_status === 'revoked' ? 'delegation_revoked' : 'delegation_expired';
			const failure = classifyChargeFailure({
				code,
				message: order.delegation_status !== 'active' ? `delegation is ${order.delegation_status}` : 'delegation expiry has passed',
			});
			await recordEvmDcaFailure(order, {
				code: failure.code,
				reason: failure.reason,
				aborted: true,
				status: order.delegation_status !== 'active' ? 'paused' : 'expired',
			}).catch((e) => dcaLog('error', 'exec_insert_failed', { ...logCtx, message: e?.message }));
			dcaLog('info', 'skipped', { ...logCtx, code: failure.code });
			results.push({ id: order.id, skipped: true, code: failure.code });
			continue;
		}

		// ── Idempotency claim ───────────────────────────────────────────────
		// Atomically advance next_fire_at so a concurrent tick (or a retry of
		// this tick) will not re-pick this row. On failure the classifier decides
		// whether the claim is released for a retry.
		const nowIso = new Date().toISOString();
		const nextIso = new Date(Date.now() + period * 1000).toISOString();
		if (!(await claimEvmDca(order, { nowIso, nextIso }))) {
			dcaLog('info', 'claim_lost', { ...logCtx });
			results.push({ id: order.id, skipped: true, reason: 'claim_lost' });
			continue;
		}

		dcaLog('info', 'execute_start', { ...logCtx });

		try {
			const { txHash, quoteAmountOut, divergenceBps } = await dcaOnPeriod(strategy);
			await recordEvmDcaSuccess(order, { txHash, quoteAmountOut, divergenceBps }).catch((e) =>
				dcaLog('error', 'exec_insert_failed', { ...logCtx, message: e?.message }),
			);
			dcaLog('info', 'execute_success', { ...logCtx, tx_hash: txHash, divergence_bps: divergenceBps });
			results.push({ id: order.id, txHash, quoteAmountOut });
		} catch (err) {
			// One classifier decides what a failure means, shared with the
			// subscription cron and with the API that renders it to the owner
			// (api/_lib/recurring.js).
			const { code, outcome, reason, platform } = classifyChargeFailure({
				code: err.code,
				message: err.message,
			});
			const applied = applyChargeFailure({
				outcome,
				platform,
				consecutiveFailures: Number(order.consecutive_failures ?? 0),
			});

			// Release the idempotency claim only when the swap provably never went
			// out AND another attempt is still allowed. Everything else keeps the
			// advanced next_fire_at, so the period is consumed exactly once.
			await recordEvmDcaFailure(order, {
				code,
				reason,
				aborted: chargeStatusFor(outcome) === 'aborted',
				unconfirmed: chargeStatusFor(outcome) === 'unknown',
				apply: { ...applied, nowIso },
				divergenceBps: err.divergenceBps ?? null,
			}).catch((e) => dcaLog('error', 'note_failure_failed', { ...logCtx, message: e?.message }));

			dcaLog('error', 'execute_failed', {
				...logCtx,
				code,
				outcome,
				message: err.message,
				status: err.status,
				paused: applied.pause,
				will_retry_next_tick: applied.retry,
			});
			results.push({ id: order.id, error: reason, code, outcome });
		}
	}

	dcaLog('info', 'tick_done', { run_id: runId, processed: strategies.length });

	return json(res, 200, {
		ok: true,
		processed: strategies.length,
		results,
	});
}

// ═══════════════════════════════════════════════════════════════════════════
// run-distribute-payments
// ═══════════════════════════════════════════════════════════════════════════

const DISTRIBUTE_CRON_RELAYER_SECRET_KEY_B64 = () =>
	process.env.PUMP_CRON_RELAYER_SECRET_KEY_B64 || null;

async function distributeLoadRelayer() {
	const b64 = DISTRIBUTE_CRON_RELAYER_SECRET_KEY_B64();
	if (!b64) return null;
	const [{ Keypair }] = await Promise.all([import('@solana/web3.js')]);
	return Keypair.fromSecretKey(Buffer.from(b64, 'base64'));
}

async function handleRunDistributePayments(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	// Auth: Vercel cron secret (constant-time, unconditional).
	if (!requireCron(req, res)) return;

	// Pick mints to consider: those with confirmed payments since last
	// distribute run, or never run before.
	const mints = await sql`
		select m.id, m.mint, m.network, m.buyback_bps, m.quote_mint,
		       coalesce(ap.distribute_min_atomics, 0) as distribute_min_atomics
		from pump_agent_mints m
		left join pump_autopilot ap on ap.mint_id = m.id
		where coalesce(ap.enabled, true) = true
		  and coalesce(ap.distribute_enabled, true) = true
		  and exists (
			select 1 from pump_agent_payments p
			where p.mint_id = m.id and p.status = 'confirmed'
			  and (
				p.confirmed_at > coalesce(
					(select max(created_at) from pump_distribute_runs r where r.mint_id = m.id),
					'epoch'::timestamptz
				)
			  )
		)
		limit 200
	`;

	const relayer = await distributeLoadRelayer();
	const results = [];

	for (const m of mints) {
		// Distribute the payment vault in the coin's quote asset so the whole
		// earn → distribute → buyback → burn loop stays in one currency that the
		// curve can swap. USDC coins distribute USDC, SOL coins SOL. Empty vaults
		// record 'skipped' and SDK errors record 'failed' below — never a silent
		// no-op.
		const { currencyStr } = await resolveCoinQuoteCurrency({
			network: m.network,
			mint: m.mint,
			dbQuoteMint: m.quote_mint,
		});
		const currency = solanaPubkey(currencyStr);

		try {
			const { agent } = await getPumpAgent({ network: m.network, mint: m.mint });
			const balancesBefore = await agent.getBalances(currency);
			const paymentBalance = BigInt(balancesBefore.paymentVault.balance ?? 0);
			const minAtomics = BigInt(m.distribute_min_atomics ?? 0);

			if (paymentBalance === 0n || paymentBalance < minAtomics) {
				const [run] = await sql`
					insert into pump_distribute_runs (mint_id, currency_mint, status, balances_before)
					values (${m.id}, ${currencyStr}, 'skipped', ${JSON.stringify({ payment: paymentBalance.toString() })}::jsonb)
					returning id
				`;
				results.push({
					mint: m.mint,
					status: 'skipped',
					run_id: run.id,
					reason: paymentBalance === 0n ? 'empty' : 'below_threshold',
				});
				continue;
			}

			const { offline } = await getPumpAgentOffline({ network: m.network, mint: m.mint });

			if (!relayer) {
				// No relayer: build unsigned tx for an external keeper. Persist run as 'pending'.
				const ixs = await offline.distributePayments({
					user: solanaPubkey(process.env.PUMP_DISTRIBUTE_FALLBACK_PAYER || m.mint),
					currencyMint: currency,
				});
				const txBase64 = await buildUnsignedTxBase64({
					network: m.network,
					payer: solanaPubkey(process.env.PUMP_DISTRIBUTE_FALLBACK_PAYER || m.mint),
					instructions: Array.isArray(ixs) ? ixs : [ixs],
				});
				const [run] = await sql`
					insert into pump_distribute_runs (mint_id, currency_mint, status, balances_before)
					values (${m.id}, ${currencyStr}, 'pending', ${JSON.stringify({ payment: paymentBalance.toString() })}::jsonb)
					returning id
				`;
				results.push({
					mint: m.mint,
					status: 'pending',
					run_id: run.id,
					tx_base64: txBase64,
				});
				continue;
			}

			// Relayer path: sign + send.
			const ixs = await offline.distributePayments({
				user: relayer.publicKey,
				currencyMint: currency,
			});
			const connection = getConnection({ network: m.network });
			// Protected send: priority fee + CU estimate, rebroadcast with blockhash
			// refresh, hard throw on an on-chain revert.
			const { signature: sig } = await submitProtected({ network: m.network, connection, payer: relayer, instructions: Array.isArray(ixs) ? ixs : [ixs] });

			const balancesAfter = await agent.getBalances(currency);
			const [run] = await sql`
				insert into pump_distribute_runs
					(mint_id, currency_mint, tx_signature, status, balances_before, balances_after)
				values
					(${m.id}, ${currencyStr}, ${sig}, 'confirmed',
					 ${JSON.stringify({ payment: paymentBalance.toString() })}::jsonb,
					 ${JSON.stringify({
							buyback: balancesAfter.buybackVault?.balance?.toString?.(),
							withdraw: balancesAfter.withdrawVault?.balance?.toString?.(),
						})}::jsonb)
				returning id
			`;
			results.push({ mint: m.mint, status: 'confirmed', tx_signature: sig, run_id: run.id });
		} catch (err) {
			await sql`
				insert into pump_distribute_runs (mint_id, currency_mint, status, error)
				values (${m.id}, ${currencyStr}, 'failed', ${err.message || String(err)})
			`;
			results.push({ mint: m.mint, status: 'failed', error: err.message });
		}
	}

	return json(res, 200, {
		ok: true,
		processed: results.length,
		relayer: relayer ? relayer.publicKey.toBase58() : null,
		results,
	});
}

// ═══════════════════════════════════════════════════════════════════════════
// run-subscriptions
// ═══════════════════════════════════════════════════════════════════════════

// USDC contract addresses by chain ID.
const USDC_BY_CHAIN = {
	84532: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // Base Sepolia
	11155111: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // Sepolia
};

// Max time we'll wait for the skill's onPeriod (which fetches the relayer).
// Override via SUBSCRIPTION_CHARGE_TIMEOUT_MS.
const ONPERIOD_TIMEOUT_MS = parseInt(process.env.SUBSCRIPTION_CHARGE_TIMEOUT_MS ?? '30000', 10);

// Structured log helper — single-line JSON so Vercel log drains can parse it.
function subLog(event, fields = {}) {
	try {
		console.log(JSON.stringify({ ts: new Date().toISOString(), event, ...fields }));
	} catch {
		// Never let logging throw.
	}
}

function subLogError(event, fields = {}) {
	try {
		console.error(JSON.stringify({ ts: new Date().toISOString(), event, ...fields }));
	} catch {
		// Never let logging throw.
	}
}

// Race a promise against a timeout. Rejects with a tagged error on timeout.
function subWithTimeout(promise, ms, label) {
	return new Promise((resolve, reject) => {
		const t = setTimeout(() => {
			const err = new Error(`${label} timed out after ${ms}ms`);
			err.code = 'timeout';
			reject(err);
		}, ms);
		Promise.resolve(promise).then(
			(v) => {
				clearTimeout(t);
				resolve(v);
			},
			(e) => {
				clearTimeout(t);
				reject(e);
			},
		);
	});
}

async function handleRunSubscriptions(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	// Auth: Vercel cron secret (constant-time, unconditional — the scheduler
	// always sends Authorization: Bearer $CRON_SECRET).
	if (!requireCron(req, res)) return;

	const runId = `sub-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
	const runStart = Date.now();
	subLog('subscription_cron.start', { runId });

	const origin = env.APP_ORIGIN;
	const relayerToken = env.CRON_SECRET ?? '';

	const report = {
		runId,
		processed: 0,
		charged: 0,
		skipped: 0,
		paused: 0,
		// Retryable failures that left the schedule active for the next tick.
		retrying: 0,
		claimLost: 0,
		errors: [],
	};

	// Load the skill's onPeriod handler once per invocation.
	let onPeriod;
	try {
		({ onPeriod } = await import('../../public/skills/subscription/skill.js'));
	} catch (err) {
		subLogError('subscription_cron.skill_load_failed', { runId, message: err.message });
		return error(res, 500, 'internal_error', 'failed to load subscription skill');
	}

	// Select all active subscriptions whose charge window has arrived.
	let rows;
	try {
		rows = await sql`
			SELECT
				s.id,
				s.user_id,
				s.agent_id,
				s.delegation_id,
				s.period_seconds,
				s.amount_per_period,
				s.next_charge_at,
				s.last_charge_at,
				s.consecutive_failures,
				d.status          AS delegation_status,
				d.expires_at      AS delegation_expires_at,
				d.chain_id,
				ai.wallet_address AS owner_address
			FROM agent_subscriptions s
			JOIN agent_delegations d  ON d.id  = s.delegation_id
			JOIN agent_identities  ai ON ai.id = s.agent_id
			WHERE s.status = 'active'
			  AND s.next_charge_at <= NOW()
		`;
	} catch (err) {
		if (isTableMissing(err)) {
			subLog('subscription_cron.skip', {
				runId,
				reason: 'agent_subscriptions table not yet created',
			});
			return json(res, 200, { ok: true, skipped: true, reason: 'table_not_ready' });
		}
		// Rethrow rather than answering 500 here, so the shared cron wrapper applies
		// the same degrade every other cron gets: a transient Neon connection
		// failure becomes a clean `db_unavailable` skip, while a real statement
		// fault (syntax, constraint, missing column) still surfaces as a 500.
		// Returning the 500 directly hid the outage class from that classifier, and
		// because economy-tick fires this engine every minute, a Neon blip read as a
		// per-minute 500 stream and a permanently failed engine on the heartbeat.
		subLogError('subscription_cron.select_failed', { runId, message: err.message });
		throw err;
	}

	subLog('subscription_cron.selected', { runId, count: rows.length });

	for (const row of rows) {
		report.processed++;
		const rowStart = Date.now();
		const ctx = { runId, subscriptionId: row.id, agentId: row.agent_id };

		try {
			// Guard: delegation must still be active. Nothing is attempted
			// on-chain here, but the attempt is still recorded: a creator reading
			// the ledger has to see why a period produced no money.
			if (row.delegation_status !== 'active') {
				const applied = await subApplyFailure(row, ctx, {
					code:
						row.delegation_status === 'revoked'
							? 'delegation_revoked'
							: 'delegation_expired',
					message: `delegation is ${row.delegation_status}`,
				});
				report.paused++;
				report.errors.push({ id: row.id, code: applied.code, reason: applied.reason });
				subLog('subscription_cron.paused', { ...ctx, code: applied.code });
				continue;
			}

			// Guard: delegation must not be expired.
			if (row.delegation_expires_at && new Date(row.delegation_expires_at) <= new Date()) {
				const applied = await subApplyFailure(row, ctx, {
					code: 'delegation_expired',
					message: 'delegation expiry has passed',
				});
				report.paused++;
				report.errors.push({ id: row.id, code: applied.code, reason: applied.reason });
				subLog('subscription_cron.paused', { ...ctx, code: applied.code });
				continue;
			}

			const usdcAddress = USDC_BY_CHAIN[row.chain_id];
			if (!usdcAddress) {
				const applied = await subApplyFailure(row, ctx, {
					code: 'chain_not_supported',
					message: `chain ${row.chain_id} has no USDC address configured`,
				});
				report.skipped++;
				report.errors.push({ id: row.id, code: applied.code, reason: applied.reason });
				subLog('subscription_cron.skipped', { ...ctx, code: applied.code });
				continue;
			}

			// Atomic claim: mark this period as being processed by writing
			// last_charge_at = NOW(). Matches only if:
			//   - the schedule is still active and still due,
			//   - last_charge_at is NULL OR < next_charge_at (not already claimed for this period).
			// If 0 rows returned, another worker claimed this period, so skip.
			//
			// Dueness is re-tested server-side (`next_charge_at <= NOW()`) rather
			// than by comparing against the timestamp we selected. Postgres stores
			// timestamptz to the microsecond and the driver hands it back as a JS
			// Date, which truncates to the millisecond: an equality check against
			// the round-tripped value silently never matches for any row whose
			// next_charge_at carries sub-millisecond digits, and that schedule then
			// never charges again. The last_charge_at guard is what actually makes
			// the claim idempotent per period; the equality added nothing but that
			// failure mode.
			const claim = await sql`
				UPDATE agent_subscriptions
				SET last_charge_at = NOW()
				WHERE id = ${row.id}
				  AND status = 'active'
				  AND next_charge_at <= NOW()
				  AND (last_charge_at IS NULL OR last_charge_at < next_charge_at)
				RETURNING id
			`;
			if (claim.length === 0) {
				report.claimLost++;
				subLog('subscription_cron.claim_lost', ctx);
				continue;
			}

			let result;
			try {
				result = await subWithTimeout(
					onPeriod({
						agent: {
							agentId: row.agent_id,
							chainId: row.chain_id,
							ownerAddress: row.owner_address,
							usdcAddress,
							relayerToken,
							origin,
						},
						subscription: {
							id: row.id,
							delegationId: row.delegation_id,
							amountPerPeriod: row.amount_per_period,
						},
					}),
					ONPERIOD_TIMEOUT_MS,
					'onPeriod',
				);
			} catch (err) {
				const applied = await subApplyFailure(row, ctx, {
					code: err.code ?? 'unknown',
					message: err.message ?? 'unknown',
				});
				if (applied.pause) report.paused++;
				else report.retrying++;
				report.errors.push({ id: row.id, code: applied.code, reason: applied.reason });
				subLogError('subscription_cron.onperiod_threw', {
					...ctx,
					code: applied.code,
					outcome: applied.outcome,
					paused: applied.pause,
					willRetry: applied.retry,
					message: err.message ?? 'unknown',
					durationMs: Date.now() - rowStart,
				});
				continue;
			}

			if (result && result.ok) {
				// Advance next_charge_at by exactly one period to enforce idempotency.
				const nextChargeAt = new Date(
					Date.parse(row.next_charge_at) + row.period_seconds * 1000,
				);
				try {
					await sql`
						UPDATE agent_subscriptions
						SET next_charge_at       = ${nextChargeAt.toISOString()},
						    last_error           = NULL,
						    last_error_code      = NULL,
						    consecutive_failures = 0,
						    last_tx_hash         = ${result.txHash ?? null}
						WHERE id = ${row.id}
					`;
				} catch (err) {
					// Charge succeeded on-chain but we failed to advance — log loudly.
					// Do NOT pause: next run's claim guard will prevent double-charge
					// since last_charge_at >= next_charge_at for this period.
					subLogError('subscription_cron.advance_failed', {
						...ctx,
						message: err.message,
						txHash: result.txHash,
					});
					report.errors.push({
						id: row.id,
						reason: 'advance_failed',
						message: err.message,
					});
					continue;
				}

				// Emit usage event — non-fatal if the table schema differs.
				await sql`
					INSERT INTO usage_events (user_id, kind, tool, status)
					VALUES (${row.user_id}, 'subscription_charge', 'subscription', 'success')
				`.catch((err) =>
					subLogError('subscription_cron.usage_event_failed', {
						...ctx,
						message: err.message,
					}),
				);

				await recordSubscriptionCharge(row, ctx, {
					status: chargeStatusFor(OUTCOME.CHARGED),
					outcome: OUTCOME.CHARGED,
					txHash: result.txHash ?? null,
				});

				report.charged++;
				subLog('subscription_cron.charged', {
					...ctx,
					txHash: result.txHash,
					durationMs: Date.now() - rowStart,
				});
			} else {
				const applied = await subApplyFailure(row, ctx, {
					code: result?.code ?? 'unknown',
					message: result?.message ?? '',
				});
				if (applied.pause) report.paused++;
				else report.retrying++;
				report.errors.push({ id: row.id, code: applied.code, reason: applied.reason });
				subLog('subscription_cron.charge_failed', {
					...ctx,
					code: applied.code,
					outcome: applied.outcome,
					paused: applied.pause,
					willRetry: applied.retry,
					durationMs: Date.now() - rowStart,
				});
			}
		} catch (err) {
			// Catch-all so one bad row can't kill the run.
			subLogError('subscription_cron.row_unhandled', {
				...ctx,
				message: err.message ?? 'unknown',
				stack: err.stack,
			});
			report.errors.push({ id: row.id, reason: 'unhandled', message: err.message });
			// Best-effort pause so we don't loop on the same broken row next hour.
			await subSafePause(
				row.id,
				`unhandled: ${(err.message ?? 'unknown').slice(0, 480)}`,
				ctx,
			);
			report.paused++;
		}
	}

	subLog('subscription_cron.done', {
		runId,
		durationMs: Date.now() - runStart,
		processed: report.processed,
		charged: report.charged,
		paused: report.paused,
		retrying: report.retrying,
		skipped: report.skipped,
		claimLost: report.claimLost,
		errorCount: report.errors.length,
	});

	return json(res, 200, report);
}

async function subPause(id, lastError) {
	await sql`
		UPDATE agent_subscriptions
		SET status = 'paused', last_error = ${lastError}, paused_at = NOW()
		WHERE id = ${id}
	`;
}

/**
 * Append one row to the subscription charge ledger. Best-effort: a ledger write
 * must never turn a successful charge into a failed cron row, so failures are
 * logged and swallowed.
 */
async function recordSubscriptionCharge(row, ctx, { status, outcome, code, error, txHash }) {
	await sql`
		INSERT INTO subscription_charges
			(subscription_id, agent_id, payer_user_id, chain_id, amount, tx_hash,
			 status, code, outcome, error, period_start_at)
		VALUES
			(${row.id}, ${row.agent_id}, ${row.user_id ?? null}, ${row.chain_id ?? null},
			 ${row.amount_per_period}, ${txHash ?? null}, ${status}, ${code ?? null},
			 ${outcome}, ${error ? String(error).slice(0, 500) : null},
			 ${row.next_charge_at ?? null})
		ON CONFLICT DO NOTHING
	`.catch((err) =>
		subLogError('subscription_cron.charge_record_failed', { ...ctx, message: err.message }),
	);
}

/**
 * Apply a failed charge to the schedule: record it in the ledger, then either
 * leave the schedule active for another tick or pause it, per the shared rules
 * in api/_lib/recurring.js.
 *
 * Releasing the period claim means restoring last_charge_at to what it was
 * before this tick claimed the period. That is only safe because the retryable
 * bucket is exactly the set of failures where the transfer provably never
 * reached the chain; a timeout is classified ambiguous and never retried.
 */
async function subApplyFailure(row, ctx, failure) {
	const { code, outcome, reason, platform } = classifyChargeFailure(failure);
	const applied = applyChargeFailure({
		outcome,
		platform,
		consecutiveFailures: Number(row.consecutive_failures ?? 0),
	});

	await recordSubscriptionCharge(row, ctx, {
		status: chargeStatusFor(outcome),
		outcome,
		code,
		error: failure.message,
	});

	try {
		if (applied.pause) {
			await sql`
				UPDATE agent_subscriptions
				SET status               = 'paused',
				    paused_at            = NOW(),
				    last_error           = ${reason.slice(0, 500)},
				    last_error_code      = ${code},
				    consecutive_failures = ${applied.consecutiveFailures}
				WHERE id = ${row.id}
			`;
		} else {
			await sql`
				UPDATE agent_subscriptions
				SET last_charge_at       = ${row.last_charge_at ?? null},
				    last_error           = ${reason.slice(0, 500)},
				    last_error_code      = ${code},
				    consecutive_failures = ${applied.consecutiveFailures}
				WHERE id = ${row.id}
			`;
		}
	} catch (err) {
		subLogError('subscription_cron.apply_failure_failed', {
			...ctx,
			code,
			message: err.message,
		});
	}

	return { ...applied, code, outcome, reason };
}

// Like subPause but swallows its own errors so a DB hiccup during pause doesn't
// propagate out of the per-row handler. Logs the failure for ops visibility.
async function subSafePause(id, lastError, ctx) {
	try {
		await subPause(id, lastError);
	} catch (err) {
		subLogError('subscription_cron.pause_failed', {
			...ctx,
			lastError,
			message: err.message,
		});
	}
}

// ═══════════════════════════════════════════════════════════════════════════
// solana-attest-event-cleanup
// ═══════════════════════════════════════════════════════════════════════════

const STALE_AFTER_SECS = 60 * 60; // 1 hour

async function handleSolanaAttestEventCleanup(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const result = await sql`
		delete from solana_attest_event_claims
		where signature is null
		  and claimed_at < now() - (${STALE_AFTER_SECS} || ' seconds')::interval
		returning agent_asset, network, event_id, claimed_at
	`;

	return json(res, 200, {
		deleted: result.length,
		stale_after_secs: STALE_AFTER_SECS,
		samples: result.slice(0, 10),
	});
}

// ═══════════════════════════════════════════════════════════════════════════
// solana-attestations-crawl
// ═══════════════════════════════════════════════════════════════════════════

const SOL_ATTEST_PER_RUN_MAX = 50; // bound RPC fan-out per cron tick

async function handleSolanaAttestationsCrawl(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	// Pull Solana agents, oldest-cursor first.
	const agents = await sql`
		select
			a.id,
			a.meta->>'sol_mint_address' as agent_asset,
			coalesce(a.meta->>'network', 'mainnet') as network,
			a.wallet_address as owner_wallet,
			c.last_indexed_at
		from agent_identities a
		left join solana_attestations_cursor c
			on c.agent_asset = a.meta->>'sol_mint_address'
		where a.deleted_at is null
		  and a.meta ? 'sol_mint_address'
		order by c.last_indexed_at nulls first
		limit ${SOL_ATTEST_PER_RUN_MAX}
	`;

	const report = { agents: [], errors: [], events: null };
	for (const row of agents) {
		try {
			const r = await crawlAgentAttestations({
				agentAsset: row.agent_asset,
				network: row.network,
				ownerWallet: row.owner_wallet,
			});
			report.agents.push({ asset: row.agent_asset, ...r });
		} catch (err) {
			report.errors.push({ asset: row.agent_asset, error: err.message || String(err) });
		}
	}

	// Second half: the cross-chain event index. Draws its batch from the
	// platform's own agents AND the external Solana registry directory, which
	// had no event coverage at all before this ran.
	report.events = await solanaEventSweep();

	return json(res, 200, report);
}

async function solanaEventSweep() {
	// The pool, the batch and the budget live with the crawl they bound, in
	// api/_lib/solana-agent-events.js, because the freshness sensor derives the
	// index's cycle time from those same constants. Splitting them across the
	// cron and the module is how the sweep spent a year at a batch nobody could
	// tie back to the median lag it produced.
	const { sweepAgentEvents } = await import('../_lib/solana-agent-events.js');
	return sweepAgentEvents();
}

// ═══════════════════════════════════════════════════════════════════════════
// process-subscriptions
// ═══════════════════════════════════════════════════════════════════════════

async function handleProcessSubscriptions(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const runId = `psub-${Date.now()}`;
	const report = {
		runId,
		processed: 0,
		charged: 0, // succeeded outright (instantaneous settlement)
		pendingApproval: 0, // payment intent created; subscriber must approve
		pastDue: 0,
		errors: [],
	};

	// Find subscriptions whose period ends within the next hour (charge a bit
	// early to allow for retry windows before period actually expires).
	const dues = await sql`
		SELECT
			cs.id, cs.subscriber_user_id, cs.plan_id, cs.current_period_end,
			sp.price_usd,
			u.email AS subscriber_email,
			u.display_name AS subscriber_name
		FROM creator_subscriptions cs
		JOIN subscription_plans sp ON sp.id = cs.plan_id
		JOIN users u ON u.id = cs.subscriber_user_id
		WHERE cs.status = 'active'
		  AND cs.current_period_end < now() + interval '1 hour'
		ORDER BY cs.current_period_end ASC
		LIMIT 200
	`;

	for (const row of dues) {
		report.processed++;
		try {
			// Count prior failed payments to decide retry vs. past_due.
			const [{ failCount }] = await sql`
				SELECT count(*)::int AS "failCount"
				FROM subscription_payments
				WHERE subscription_id = ${row.id} AND status = 'failed'
			`;

			if (failCount >= 3) {
				// Mark past_due and notify subscriber.
				await sql`
					UPDATE creator_subscriptions
					SET status = 'past_due'
					WHERE id = ${row.id} AND status = 'active'
				`;
				report.pastDue++;
				console.log(
					JSON.stringify({
						event: 'process_subscriptions.past_due',
						runId,
						subscriptionId: row.id,
						failCount,
					}),
				);
				// Fire-and-forget email notification.
				sendEmail({
					to: row.subscriber_email,
					subject: 'Action required: subscription payment failed',
					html: `<p>Hi ${row.subscriber_name || 'there'},</p>
<p>We were unable to process your subscription payment of $${row.price_usd}. Your subscription has been paused. Please update your payment method to continue.</p>
<p><a href="${env.APP_ORIGIN}/dashboard#subscriptions">Manage subscriptions</a></p>`,
					text: `Your subscription payment of $${row.price_usd} could not be processed. Visit ${env.APP_ORIGIN}/dashboard#subscriptions to manage your subscriptions.`,
				}).catch((e) =>
					console.error(
						JSON.stringify({
							event: 'process_subscriptions.email_failed',
							subscriptionId: row.id,
							error: e.message,
						}),
					),
				);
				continue;
			}

			const result = await chargeSubscription(row.id);
			if (result.success) {
				report.charged++;
			} else if (result.pending) {
				// A payment intent was created and the subscriber was notified
				// in-app. Do not increment `charged` — the subscription has
				// NOT been paid yet. A follow-up email reminder is best-effort
				// and only fires when subscriber_email is present.
				report.pendingApproval++;
				if (row.subscriber_email && result.payUrl) {
					sendEmail({
						to: row.subscriber_email,
						subject: 'Your subscription renewal is due',
						html: `<p>Hi ${row.subscriber_name || 'there'},</p>
<p>Your subscription is up for renewal. The amount is $${result.amount_usd?.toFixed(2) || row.price_usd}.</p>
<p><a href="${result.payUrl}">Approve renewal payment</a></p>`,
						text: `Your subscription renewal of $${result.amount_usd?.toFixed(2) || row.price_usd} is ready. Approve at ${result.payUrl}`,
					}).catch((e) =>
						console.error(
							JSON.stringify({
								event: 'process_subscriptions.email_failed',
								subscriptionId: row.id,
								error: e.message,
							}),
						),
					);
				}
			} else {
				if (result.paymentId) {
					await failPayment(result.paymentId, row.id);
				}
				report.errors.push({ id: row.id, error: result.error || 'charge_failed' });
			}
		} catch (e) {
			report.errors.push({ id: row.id, error: e.message || String(e) });
			console.error(
				JSON.stringify({
					event: 'process_subscriptions.row_error',
					runId,
					subscriptionId: row.id,
					error: e.message,
				}),
			);
		}
	}

	// Page on genuine charge failures so a billing outage doesn't hide behind a
	// green cron. 'charge_in_progress' is the benign idempotency signal (another
	// pass already owns this period) and is intentionally not a failure.
	const realErrors = report.errors.filter((e) => e.error !== 'charge_in_progress');
	if (realErrors.length > 0) {
		const { sendOpsAlert } = await import('../_lib/alerts.js');
		await sendOpsAlert(
			`${realErrors.length} subscription charge(s) failed this run`,
			realErrors.slice(0, 10).map((e) => `• ${e.id}: ${e.error}`).join('\n'),
			{ signature: 'subscriptions-charge-failed' },
		);
	}

	console.log(JSON.stringify({ event: 'process_subscriptions.done', ...report }));
	return json(res, 200, report);
}

// ═══════════════════════════════════════════════════════════════════════════
// settle-royalties
// ═══════════════════════════════════════════════════════════════════════════

async function handleSettleRoyalties(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const { settleAllPendingRoyalties } = await import('../_lib/royalty.js');
	const report = await settleAllPendingRoyalties();
	return json(res, 200, { ok: true, ...report });
}

// ═══════════════════════════════════════════════════════════════════════════
// audit-log-cleanup — retention policy: keep 365 days of audit_log rows.
// Legal acceptance records (Terms of Service and Risk Disclosure clickwrap,
// written by api/legal/tos-ack.js, api/legal/risk-ack.js, and the auth
// endpoints) are exempt: they are the durable evidence that a user agreed,
// and must survive for the life of the account and beyond.
// ═══════════════════════════════════════════════════════════════════════════

const AUDIT_LOG_RETENTION_DAYS = 365;
const AUDIT_LOG_RETENTION_EXEMPT_ACTIONS = ['tos-accept', 'risk-ack-accept'];

async function handleAuditLogCleanup(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const result = await sql`
		delete from audit_log
		where created_at < now() - (${AUDIT_LOG_RETENTION_DAYS} || ' days')::interval
			and action != all(${AUDIT_LOG_RETENTION_EXEMPT_ACTIONS})
		returning id
	`;
	return json(res, 200, { deleted: result.length, retention_days: AUDIT_LOG_RETENTION_DAYS });
}

// ═══════════════════════════════════════════════════════════════════════════
// expire-pending-purchases — fail-close stale pending skill purchases.
// Schedule: every 5 minutes. Marks rows past expires_at as 'expired' so the
// idempotent-create path issues a fresh reference on the buyer's next attempt.
// ═══════════════════════════════════════════════════════════════════════════

async function handleExpirePendingPurchases(req, res) {
	if (!method(req, res, ['GET'])) return;
	if (!requireCron(req, res)) return;
	const result = await sql`
		UPDATE skill_purchases
		SET status = 'expired', updated_at = now()
		WHERE status = 'pending' AND expires_at IS NOT NULL AND expires_at < now()
		RETURNING id
	`;
	return json(res, 200, { expired: result.length });
}

// ═══════════════════════════════════════════════════════════════════════════
// confirm-pending-purchases: server-side settlement sweep for paid skill buys.
// Schedule: every 2 minutes (well inside the 30-minute pending TTL, so a paid
// purchase confirms long before expire-pending-purchases fail-closes it).
//
// Why this exists: a paid purchase is otherwise confirmed ONLY by the buyer's
// browser polling /api/marketplace/purchase/confirm for ~60s after it broadcasts
// the payment. If the tab closes, the network stalls, or a mobile Solana-Pay QR
// buyer pays and walks away, the on-chain payment lands but the row stays
// 'pending': the buyer is charged, gets no skill grant, and the sale never
// reaches the Money Pulse. This sweep locates each pending paid row's payment by
// its Solana-Pay reference and finalizes it exactly like the buyer poll would
// (idempotent: finalizeSkillConfirmation flips the row only from 'pending', and
// re-confirms are no-ops). Solana only; EVM confirm needs the buyer's tx hash.
// ═══════════════════════════════════════════════════════════════════════════

async function handleConfirmPendingPurchases(req, res) {
	if (!method(req, res, ['GET'])) return;
	if (!requireCron(req, res)) return;

	// Only rows that (a) are a real paid purchase, (b) settle on Solana, (c) are
	// still within their pending window, and (d) are recent enough that a payment
	// could plausibly have landed. mint_decimals rides in from the price row so the
	// on-chain amount check matches the quote. LIMIT bounds the per-tick RPC work;
	// the next tick continues any remainder.
	const pending = await sql`
		SELECT sp.id, sp.user_id, sp.agent_id, sp.skill, sp.status, sp.reference,
		       sp.amount, sp.currency_mint, sp.chain, sp.tx_signature,
		       sp.expires_at, sp.referrer_user_id, sp.recipient_user_id,
		       sp.platform_fee_amount, sp.platform_fee_wallet,
		       COALESCE(asp.mint_decimals, 6) AS mint_decimals
		FROM skill_purchases sp
		LEFT JOIN agent_skill_prices asp
		       ON asp.agent_id = sp.agent_id AND asp.skill = sp.skill
		WHERE sp.status = 'pending'
		  AND sp.kind IN ('purchase', 'time_pass')
		  AND sp.chain = 'solana'
		  AND (sp.expires_at IS NULL OR sp.expires_at > now())
		  AND sp.created_at > now() - interval '2 hours'
		ORDER BY sp.created_at ASC
		LIMIT 50
	`;

	let confirmed = 0, tipped = 0, mismatched = 0, stillPending = 0, errors = 0;
	for (const pur of pending) {
		try {
			const r = await confirmSkillPurchase(pur);
			if (r.status === 'confirmed') confirmed++;
			else if (r.status === 'tipped') tipped++;
			else if (r.status === 'mismatch') mismatched++;
			else stillPending++; // 'pending' (no on-chain payment yet) or 'expired'
		} catch (e) {
			errors++;
			console.error('[confirm-pending-purchases] confirm failed', pur.reference, e?.message);
		}
	}

	return json(res, 200, {
		scanned: pending.length,
		confirmed,
		tipped,
		mismatched,
		still_pending: stillPending,
		errors,
	});
}

// ═══════════════════════════════════════════════════════════════════════════
// cleanup-csrf-tokens — drop expired tokens. Run hourly.
// ═══════════════════════════════════════════════════════════════════════════

async function handleCleanupCsrfTokens(req, res) {
	if (!method(req, res, ['GET'])) return;
	if (!requireCron(req, res)) return;
	// RETURNING 1, not RETURNING token: the row count is all this reports, and
	// shipping every expired token value back over the wire puts live-until-a-
	// moment-ago CSRF secrets in the response path for no gain.
	const result = await sql`DELETE FROM csrf_tokens WHERE expires_at < now() RETURNING 1`;
	return json(res, 200, { deleted: result.length });
}

// ═══════════════════════════════════════════════════════════════════════════
// siwx-gc — prune SIWX nonces (replay window) and expired payment grants.
// Daily at 03:00 UTC. Nonce window of 10 min (600s) is well above the 5-min
// SIWX maxAge; payments grace of 7 days avoids cutting off slow clients at
// the boundary.
// ═══════════════════════════════════════════════════════════════════════════

async function handleSiwxGc(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const { pruneOldNonces, pruneExpiredPayments } = await import('../_lib/siwx-storage.js');

	// 10-minute nonce window — well over the 5-minute SIWX message maxAge.
	const noncesDeleted = await pruneOldNonces(10 * 60);

	// 7-day grace on expired payments so a slow client doesn't lose access
	// mid-session right at the boundary.
	const paymentsDeleted = await pruneExpiredPayments(7 * 24 * 3600);

	return json(res, 200, {
		ok: true,
		noncesDeleted,
		paymentsDeleted,
		ranAt: new Date().toISOString(),
	});
}

// ═══════════════════════════════════════════════════════════════════════════
// process-withdrawals — pick up pending Solana USDC withdrawals and execute
// them from the treasury keypair. Runs hourly.
// State machine: pending → processing → completed (with tx_signature) | failed (with error_message)
// ═══════════════════════════════════════════════════════════════════════════

const WITHDRAWALS_BATCH = 20;

async function handleProcessWithdrawals(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	if (!requireCron(req, res)) return;

	const treasuryKeypair = process.env.TREASURY_KEYPAIR || process.env.PLATFORM_TREASURY_KEYPAIR;
	const evmTreasuryKey = process.env.EVM_TREASURY_PRIVATE_KEY;
	if (!treasuryKeypair && !evmTreasuryKey) {
		return json(res, 200, {
			skipped: true,
			reason: 'No treasury key configured (set TREASURY_KEYPAIR or PLATFORM_TREASURY_KEYPAIR for Solana, EVM_TREASURY_PRIVATE_KEY for EVM)',
		});
	}

	const { transferSolanaUSDC } = await import('../_lib/solana-transfer.js');
	const { sendEvmUsdc, resolveEvmChainId } = await import('../_lib/evm-transfer.js');
	const { insertNotification } = await import('../_lib/notify.js');
	const { sendOpsAlert } = await import('../_lib/alerts.js');

	// Reconciliation: a crash between the on-chain send and the 'completed' write
	// strands a row in 'processing'. The main loop only claims 'pending', so it is
	// never retried. We do NOT auto-resend — without an on-chain idempotency
	// reference a blind retry could double-pay — we page an operator to reconcile
	// by hand (confirm the transfer settled, then complete or re-queue the row).
	const stranded = await sql`
		SELECT id, amount, currency_mint, chain, updated_at
		FROM agent_withdrawals
		WHERE status = 'processing' AND updated_at < now() - interval '15 minutes'
		ORDER BY updated_at ASC LIMIT 50
	`;
	if (stranded.length) {
		await sendOpsAlert(
			`${stranded.length} withdrawal(s) stranded in 'processing' >15m`,
			stranded
				.map((s) => `• ${s.id} — ${s.amount} ${s.currency_mint} (${s.chain})`)
				.join('\n') +
				'\nManual reconciliation required: verify whether the on-chain transfer ' +
				'settled BEFORE completing or re-queuing — a blind retry can double-pay.',
			{ signature: 'withdrawals-stranded' },
		);
	}

	// Build the chain filter to match what we can actually process. A row whose
	// chain has no treasury key configured stays 'pending' for the next pass
	// once an operator wires the key.
	const supportedChains = [];
	if (treasuryKeypair) supportedChains.push('solana');
	if (evmTreasuryKey)
		supportedChains.push(
			'ethereum',
			'base',
			'optimism',
			'arbitrum',
			'polygon',
			'sepolia',
			'base-sepolia',
			'1',
			'8453',
			'10',
			'42161',
			'137',
			'11155111',
			'84532',
		);

	// Fetch pending withdrawals across all supported chains, join user earnings
	// to verify available balance.
	const pending = await sql`
		SELECT
			w.id,
			w.user_id,
			w.amount,
			w.currency_mint,
			w.to_address,
			w.chain,
			(
				SELECT coalesce(sum(re.net_amount), 0)::bigint
				FROM agent_revenue_events re
				JOIN agent_identities ai ON ai.id = re.agent_id
				WHERE coalesce(re.owner_user_id, ai.user_id) = w.user_id AND re.currency_mint = w.currency_mint
				  AND NOT re.settled_to_wallet
			) -
			(
				SELECT coalesce(sum(w2.amount), 0)::bigint
				FROM agent_withdrawals w2
				WHERE w2.user_id = w.user_id
				  AND w2.id != w.id
				  AND w2.status IN ('pending', 'processing', 'completed')
				  AND w2.currency_mint = w.currency_mint
			) AS available
		FROM agent_withdrawals w
		WHERE w.status = 'pending' AND w.chain = ANY(${supportedChains})
		ORDER BY w.created_at ASC
		LIMIT ${WITHDRAWALS_BATCH}
	`;

	const report = { processed: 0, completed: 0, failed: 0, skipped: 0, sendFailed: 0, errors: [] };

	for (const w of pending) {
		report.processed++;
		const available = Number(w.available ?? 0);

		// Skip if user doesn't have enough available balance
		if (w.amount > available) {
			await sql`
				UPDATE agent_withdrawals
				SET status = 'failed',
				    error_message = 'Insufficient referral balance at processing time',
				    updated_at = now()
				WHERE id = ${w.id}
			`;
			insertNotification(w.user_id, 'withdrawal_failed', {
				withdrawal_id: w.id,
				amount: w.amount,
				currency_mint: w.currency_mint,
				reason: 'insufficient_balance',
			});
			report.failed++;
			report.errors.push({ id: w.id, error: 'insufficient_balance' });
			continue;
		}

		// Mark as processing atomically — only if still pending
		const [claimed] = await sql`
			UPDATE agent_withdrawals
			SET status = 'processing', updated_at = now()
			WHERE id = ${w.id} AND status = 'pending'
			RETURNING id
		`;
		if (!claimed) {
			report.skipped++;
			continue;
		}

		const EVM_USDC_BASE_LC = EVM_USDC[8453].toLowerCase();
		try {
			let sig;
			// Pay only the chain's USDC against a USDC balance. The EVM leg always
			// sends Base USDC, so a row carrying any other mint would turn a balance
			// in a worthless token into real dollars.
			const solUsdc = w.chain === 'solana' && w.currency_mint === SOLANA_USDC_MINT;
			const evmUsdc = w.chain !== 'solana' && String(w.currency_mint || '').toLowerCase() === EVM_USDC_BASE_LC;
			if (!solUsdc && !evmUsdc) {
				throw new Error(`withdrawal mint ${w.currency_mint} is not USDC on ${w.chain}`);
			}
			if (w.chain === 'solana') {
				if (!treasuryKeypair) {
					throw new Error('TREASURY_KEYPAIR not configured for solana withdrawal');
				}
				sig = await transferSolanaUSDC({
					fromWallet: treasuryKeypair,
					toAddress: w.to_address,
					amount: BigInt(w.amount),
					mint: w.currency_mint,
				});
			} else {
				// EVM dispatch — resolve the chain name/id to a viem chain ID,
				// then send the real USDC transfer.
				const chainId = resolveEvmChainId(w.chain);
				if (!chainId) {
					throw new Error(`unsupported chain for withdrawal: ${w.chain}`);
				}
				const result = await sendEvmUsdc({
					chainId,
					recipient: w.to_address,
					amount: BigInt(w.amount),
				});
				sig = result.hash;
			}

			await sql`
				UPDATE agent_withdrawals
				SET status = 'completed', tx_signature = ${sig}, updated_at = now()
				WHERE id = ${w.id}
			`;

			// Deduct from referral_earnings_total (best-effort; earnings are tracked via revenue_events)
			await sql`
				UPDATE users
				SET referral_earnings_total = greatest(0, coalesce(referral_earnings_total, 0) - ${w.amount})
				WHERE id = ${w.user_id}
			`.catch((e) => console.error('[process-withdrawals] referral deduct failed:', e.message));

			await insertNotification(w.user_id, 'withdrawal_completed', {
				withdrawal_id: w.id,
				amount: w.amount,
				currency_mint: w.currency_mint,
				chain: w.chain,
				tx_signature: sig,
			}).catch((e) => console.error('[process-withdrawals] notify completed failed:', e.message));

			report.completed++;
		} catch (err) {
			const msg = err.message || String(err);
			// The row was already claimed to 'processing'. A failure HERE may mean the
			// on-chain send threw before broadcast (safe to fail) OR after (funds may
			// have moved). Mark failed so the user is told, but record it as a send
			// failure so the batch alert fires and an operator reconciles.
			await sql`
				UPDATE agent_withdrawals
				SET status = 'failed', error_message = ${msg}, updated_at = now()
				WHERE id = ${w.id}
			`;
			await insertNotification(w.user_id, 'withdrawal_failed', {
				withdrawal_id: w.id,
				amount: w.amount,
				currency_mint: w.currency_mint,
				reason: msg,
			}).catch((e) => console.error('[process-withdrawals] notify failed failed:', e.message));
			report.failed++;
			report.sendFailed++;
			report.errors.push({ id: w.id, error: msg });
		}
	}

	// A green cron with failing payouts is invisible — page on real send failures
	// (treasury out of gas/SOL, RPC down, transfer reverted) so a payout outage
	// doesn't sit silently. Balance-rejections above are normal and excluded.
	if (report.sendFailed > 0) {
		await sendOpsAlert(
			`${report.sendFailed} withdrawal payout(s) failed on-chain this run`,
			report.errors.slice(0, 10).map((e) => `• ${e.id}: ${e.error}`).join('\n'),
			{ signature: 'withdrawals-send-failed' },
		);
	}

	return json(res, 200, { ok: true, ...report });
}

// ═══════════════════════════════════════════════════════════════════════════
// run-x-scheduled-posts
//
// Publishes due rows from x_scheduled_posts. Terminal errors (quota, dedup,
// not connected, reauth) are recorded once; transient errors retry up to 3x.
// ═══════════════════════════════════════════════════════════════════════════

async function handleRunXScheduledPosts(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!requireCron(req, res)) return;

	const { publishTweet, XPostError } = await import('../_lib/x-post.js');

	const due = await sql`
		select id, user_id, agent_id, text, thread_parts, reply_to_tweet_id, attempts
		from x_scheduled_posts
		where posted_at is null and error is null
		  and scheduled_at <= now()
		order by scheduled_at asc
		limit 50
	`;

	const report = { processed: 0, posted: 0, errored: 0 };
	const TERMINAL = new Set([
		'quota_exceeded',
		'duplicate',
		'not_connected',
		'validation_error',
		'reauth_required',
	]);

	for (const row of due) {
		report.processed++;
		try {
			const result = await publishTweet({
				userId: row.user_id,
				agentId: row.agent_id,
				text: row.thread_parts ? null : row.text,
				threadParts: Array.isArray(row.thread_parts) ? row.thread_parts : null,
				replyTo: row.reply_to_tweet_id || null,
				appendLink: Boolean(row.agent_id),
			});
			await sql`
				update x_scheduled_posts
				set posted_at = now(), tweet_id = ${result.tweet_id}, attempts = attempts + 1
				where id = ${row.id}
			`;
			report.posted++;
		} catch (err) {
			report.errored++;
			const code = err instanceof XPostError ? err.code : 'internal_error';
			const terminal = TERMINAL.has(code) || row.attempts >= 2;
			await sql`
				update x_scheduled_posts
				set attempts = attempts + 1,
				    error = ${terminal ? `${code}: ${err.message}`.slice(0, 500) : null}
				where id = ${row.id}
			`;
		}
	}

	return json(res, 200, report);
}

// ═══════════════════════════════════════════════════════════════════════════
// run-x-triggers
//
// Evaluates enabled rows in x_triggers. Each kind has its own predicate;
// when it fires, we draft post text (LLM for personas, formatted for
// milestones) and insert into x_scheduled_posts with scheduled_at=now().
// The run-x-scheduled-posts cron picks it up on the next tick.
// ═══════════════════════════════════════════════════════════════════════════

const TRIGGER_BUDGET_MS = 60_000;
const SOL_USD_FALLBACK = 150;

// x-mentions: read new mentions of our X accounts, decide, and answer each once
// (dry run until X_MENTION_BOT_LIVE=1 and the owner flips it). See
// api/_lib/x-mention-poll.js.
async function handleXMentions(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!requireCron(req, res)) return;
	const { runMentionTick } = await import('../_lib/x-mention-poll.js');
	return json(res, 200, await runMentionTick());
}

async function handleRunXTriggers(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!requireCron(req, res)) return;

	const started = Date.now();
	let rows;
	try {
		rows = await sql`
			select id, user_id, agent_id, kind, config, auto_publish, last_fired_at, last_state
			from x_triggers
			where enabled = true
			order by coalesce(last_fired_at, '1970-01-01'::timestamptz) asc
			limit 200
		`;
	} catch (err) {
		if (err.code === '42703') {
			rows = await sql`
				select id, user_id, null::uuid as agent_id, kind, config,
				       coalesce(auto_publish, false) as auto_publish,
				       last_fired_at,
				       null::jsonb as last_state
				from x_triggers
				where enabled = true
				order by coalesce(last_fired_at, '1970-01-01'::timestamptz) asc
				limit 200
			`;
		} else {
			throw err;
		}
	}

	const report = { evaluated: 0, fired: 0, skipped: 0, errors: 0 };
	for (const t of rows) {
		if (Date.now() - started > TRIGGER_BUDGET_MS) break;
		report.evaluated++;
		try {
			const fired = await evalTrigger(t);
			if (fired) report.fired++;
			else report.skipped++;
		} catch (err) {
			report.errors++;
			console.error('[run-x-triggers] error', t.id, t.kind, err.message);
		}
	}
	return json(res, 200, report);
}

async function evalTrigger(t) {
	if (t.kind === 'daily_persona') return await evalDailyPersona(t);
	if (t.kind === 'weekly_digest') return await evalWeeklyDigest(t);
	if (t.kind === 'price_milestone') return await evalPriceMilestone(t);
	if (t.kind === 'payment_received') return await evalPaymentReceived(t);
	return false;
}

function utcHour(d) {
	return d.getUTCHours();
}
function utcDay(d) {
	return d.getUTCDay();
}
function ymdUTC(d) {
	return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}-${String(d.getUTCDate()).padStart(2, '0')}`;
}

// Either enqueue for immediate publish (auto_publish=true) or stash in the
// pending-review queue for the user to approve (auto_publish=false).
async function enqueueTriggerPost(t, text) {
	if (t.auto_publish === false) {
		try {
			await sql`
				insert into x_pending_reviews (user_id, trigger_id, agent_id, text)
				values (${t.user_id}, ${t.id}, ${t.agent_id}, ${text})
			`;
		} catch (err) {
			if (err.code !== '42703') throw err;
			// agent_id column not yet present — insert without it
			await sql`
				insert into x_pending_reviews (user_id, trigger_id, text)
				values (${t.user_id}, ${t.id}, ${text})
			`;
		}
		return;
	}
	try {
		await sql`
			insert into x_scheduled_posts (user_id, agent_id, text, scheduled_at)
			values (${t.user_id}, ${t.agent_id}, ${text}, now())
		`;
	} catch (err) {
		if (err.code !== '42703') throw err;
		await sql`
			insert into x_scheduled_posts (user_id, text, scheduled_at)
			values (${t.user_id}, ${text}, now())
		`;
	}
}

async function setTriggerState(t, state) {
	await sql`update x_triggers set last_state = ${JSON.stringify(state)}::jsonb, last_fired_at = now() where id = ${t.id}`;
}

async function loadAvatarFromAgent(agentId) {
	if (!agentId) return null;
	// avatars has no direct agent_id column — the link is agent_identities.avatar_id.
	// Look up the avatar by joining through agent_identities, or fall back to the
	// case where the caller passes an avatar id directly (legacy behavior).
	const r = await sql`
		select a.id, a.name, a.description, ai.id as agent_id
		from avatars a
		left join agent_identities ai on ai.avatar_id = a.id
		where a.id::text = ${agentId} OR ai.id::text = ${agentId}
		limit 1
	`;
	return r[0] || null;
}

const DRAFT_SYSTEM = `You write tweets for AI agents on three.ws. Tweets must be:
- Under 280 characters (hard limit).
- In the agent's voice (first person, matching the description).
- No hashtag spam. At most 1 hashtag.
- No leading/trailing quotes. Plain text only.
- Avoid em-dashes.
Output ONLY the tweet text, nothing else.`;

// Draft short post text on the platform LLM chain (api/_lib/llm.js): free
// providers first with full failover, paid keys as the automatic last resort.
// The old pick-first-and-die routing meant one Groq 429 dropped the post.
async function llmDraft({ system, user, max = 200 }) {
	const { text: raw } = await llmComplete({
		system,
		user,
		maxTokens: max,
		track: { tool: 'cron.x-trigger-draft' },
	});
	let text = (raw || '').trim();
	if (text.startsWith('"') && text.endsWith('"')) text = text.slice(1, -1).trim();
	if (text.length > 280) text = text.slice(0, 279) + '…';
	return text;
}

async function evalDailyPersona(t) {
	const now = new Date();
	if (utcHour(now) !== Number(t.config.hour_utc)) return false;
	const today = ymdUTC(now);
	if (t.last_state?.fired_ymd === today) return false;

	const avatar = await loadAvatarFromAgent(t.agent_id);
	const ctx = avatar
		? `Agent name: ${avatar.name || 'Unnamed'}\nAgent description: ${avatar.description || '(none)'}`
		: '';
	const topic = t.config.topic
		? `Topic for today: ${t.config.topic}`
		: 'Write something engaging and in-character about being an autonomous AI agent today.';
	const text = await llmDraft({
		system: DRAFT_SYSTEM,
		user: [ctx, topic].filter(Boolean).join('\n\n'),
	});
	await enqueueTriggerPost(t, text);
	await setTriggerState(t, { fired_ymd: today });
	return true;
}

async function evalWeeklyDigest(t) {
	const now = new Date();
	if (utcDay(now) !== Number(t.config.day_of_week) || utcHour(now) !== Number(t.config.hour_utc))
		return false;
	const week = `${now.getUTCFullYear()}-W${Math.floor((now.getUTCDate() + 6) / 7)}`;
	if (t.last_state?.fired_week === week) return false;

	const avatar = await loadAvatarFromAgent(t.agent_id);
	const mint = avatar
		? (
				await sql`
		select m.symbol, m.name, s.recent_tx_count
		from pump_agent_mints m left join pump_agent_stats s on s.mint_id = m.id
		where m.agent_id::text = ${avatar.agent_id ?? null} or m.agent_id::text = ${avatar.id}
		order by m.created_at desc limit 1
	`
			)[0]
		: null;

	const ctx = avatar
		? `Agent name: ${avatar.name || 'Unnamed'}\nDescription: ${avatar.description || '(none)'}`
		: '';
	const stats = mint
		? `\nToken: $${mint.symbol || 'TOKEN'} on pump.fun. Recent transactions: ${mint.recent_tx_count || 0}.`
		: '';
	const text = await llmDraft({
		system: DRAFT_SYSTEM,
		user: `${ctx}${stats}\n\nWrite a weekly recap tweet covering the agent's progress this week. If token stats are present, mention them naturally.`,
	});
	await enqueueTriggerPost(t, text);
	await setTriggerState(t, { fired_week: week });
	return true;
}

async function evalPriceMilestone(t) {
	const thresholds = (t.config.thresholds_usd || []).slice().sort((a, b) => a - b);
	if (!thresholds.length) return false;
	const avatar = await loadAvatarFromAgent(t.agent_id);
	if (!avatar) return false;
	const mintRow = (
		await sql`
		select m.id as mint_id, m.symbol, p.market_cap_lamports
		from pump_agent_mints m
		left join lateral (
			select market_cap_lamports from pump_agent_price_points
			where mint_id = m.id order by ts desc limit 1
		) p on true
		where m.agent_id::text = ${avatar.agent_id ?? null} or m.agent_id::text = ${avatar.id}
		order by m.created_at desc limit 1
	`
	)[0];
	if (!mintRow || !mintRow.market_cap_lamports) return false;

	const solUsd = Number(t.config.sol_usd) || SOL_USD_FALLBACK;
	const mcapUsd = (Number(mintRow.market_cap_lamports) / 1e9) * solUsd;
	const lastFired = Number(t.last_state?.last_threshold_fired_usd || 0);
	const nextThreshold = thresholds.find((th) => mcapUsd >= th && th > lastFired);
	if (!nextThreshold) return false;

	const text = await llmDraft({
		system: DRAFT_SYSTEM,
		user: `Agent name: ${avatar.name || 'Unnamed'}\nDescription: ${avatar.description || '(none)'}\nToken: $${mintRow.symbol || 'TOKEN'} on pump.fun.\nMilestone: market cap just crossed $${nextThreshold.toLocaleString()} (now ≈ $${Math.round(mcapUsd).toLocaleString()}).\n\nWrite a tweet celebrating this milestone in the agent's voice.`,
	});
	await enqueueTriggerPost(t, text);
	await setTriggerState(t, { last_threshold_fired_usd: nextThreshold, mcap_usd: mcapUsd });
	return true;
}

async function evalPaymentReceived(t) {
	const avatar = await loadAvatarFromAgent(t.agent_id);
	if (!avatar) return false;
	const since = t.last_state?.last_payment_id ?? '00000000-0000-0000-0000-000000000000';
	const minUsd = Number(t.config.min_amount_usd || 0);

	const payments = await sql`
		select p.id, p.amount_atomics, p.currency_mint, p.skill_id, p.tool_name, m.symbol
		from pump_agent_payments p
		join pump_agent_mints m on m.id = p.mint_id
		where (m.agent_id::text = ${avatar.agent_id ?? null} or m.agent_id::text = ${avatar.id})
		  and p.status = 'confirmed'
		  and p.id::text > ${since}
		order by p.confirmed_at asc
		limit 3
	`;
	if (!payments.length) return false;

	let lastId = null;
	for (const p of payments) {
		const approxUsd = Number(p.amount_atomics) / 1e6;
		if (approxUsd < minUsd) {
			lastId = p.id;
			continue;
		}
		const label = p.tool_name
			? `for "${p.tool_name}"`
			: p.skill_id
				? `for skill ${p.skill_id}`
				: 'for a paid action';
		const text = await llmDraft({
			system: DRAFT_SYSTEM,
			user: `Agent name: ${avatar.name || 'Unnamed'}\nDescription: ${avatar.description || '(none)'}\nA user just paid ~$${approxUsd.toFixed(2)} ${label}.\n\nWrite a short thank-you tweet in the agent's voice.`,
		});
		await enqueueTriggerPost(t, text);
		lastId = p.id;
	}
	if (lastId) await setTriggerState(t, { last_payment_id: lastId });
	return true;
}

// ═══════════════════════════════════════════════════════════════════════════
// fetch-x-metrics
//
// Pulls public_metrics (likes, retweets, replies, impressions) for posts
// older than ~1h and not refreshed in last 6h. Stored on x_posts.metrics.
// ═══════════════════════════════════════════════════════════════════════════

async function handleFetchXMetrics(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!requireCron(req, res)) return;

	const { decryptToken } = await import('../auth/x/[action].js');

	// Pick distinct users with posts needing refresh.
	const users = await sql`
		select distinct user_id
		from x_posts
		where created_at < now() - interval '1 hour'
		  and (metrics_fetched_at is null or metrics_fetched_at < now() - interval '6 hours')
		limit 50
	`;

	const report = { users: 0, fetched: 0, errors: 0 };
	for (const u of users) {
		report.users++;
		const conn = (
			await sql`
			select access_token, expires_at, refresh_token, id
			from social_connections
			where user_id = ${u.user_id} and provider = 'x' and disconnected_at is null
			limit 1
		`
		)[0];
		if (!conn || !conn.access_token) continue;
		let accessToken;
		try {
			accessToken = decryptToken(conn.access_token);
		} catch {
			continue;
		}

		const posts = await sql`
			select id, tweet_id from x_posts
			where user_id = ${u.user_id}
			  and created_at < now() - interval '1 hour'
			  and (metrics_fetched_at is null or metrics_fetched_at < now() - interval '6 hours')
			order by created_at desc
			limit 100
		`;
		if (!posts.length) continue;

		// X allows up to 100 ids per /2/tweets lookup.
		const ids = posts.map((p) => p.tweet_id).join(',');
		// Unbounded, this held the whole cron invocation open whenever X was slow,
		// and the loop below runs it once per account.
		const r = await fetchUpstream(
			`https://api.twitter.com/2/tweets?ids=${ids}&tweet.fields=public_metrics`,
			{ headers: { authorization: `Bearer ${accessToken}` } },
			{ name: 'x:tweets-lookup', timeoutMs: 15_000, attempts: 2, okWhen: () => true },
		);
		if (!r.ok) {
			report.errors++;
			continue;
		}
		const { data = [] } = await r.json();
		const byId = new Map(data.map((d) => [d.id, d.public_metrics]));

		for (const p of posts) {
			const m = byId.get(p.tweet_id);
			if (!m) continue;
			await sql`
				update x_posts
				set metrics = ${JSON.stringify(m)}::jsonb, metrics_fetched_at = now()
				where id = ${p.id}
			`;
			report.fetched++;
		}
	}

	return json(res, 200, report);
}

// ═══════════════════════════════════════════════════════════════════════════
// run-coin-cycle
// ═══════════════════════════════════════════════════════════════════════════
//
// One unified pass over every active coin_launches row:
//   1. refresh holder snapshot via Helius RPC
//   2. claim creator-vault SOL from pump.fun and split into pots
//   3. commit the next lottery draw (one per draw_interval_seconds)
//   4. resolve any committed draws whose Drand round has been published
//   5. allocate the reflection pot pro-rata to eligible holders
//
// Payouts (SOL transfers) are NOT done here — see run-coin-payouts which
// drains the coin_payouts queue. Splitting these two crons means a slow
// or stuck payout tx can't block the next cycle from being committed.
//
// Scheduled every 5 minutes by Vercel. Each step is idempotent — running
// twice within the same draw/reflection bucket is a no-op.

async function handleRunCoinCycle(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	if (!requireCron(req, res)) return;

	// Demo gate: cron is wired in vercel.json but stays a no-op until the
	// operator opts in by setting COIN_DEMO_ENABLED=true in env. Until then
	// neither Vercel cron nor a manual call can touch any coin_launches row.
	if (process.env.COIN_DEMO_ENABLED !== 'true') {
		return json(res, 200, {
			ok: true,
			disabled: true,
			hint: 'set COIN_DEMO_ENABLED=true to enable',
		});
	}

	const coinLib = await import('../_lib/coin/index.js');
	const coins = await coinLib.listActiveCoins();

	const phaseFilter = (req.query?.phase || '').toString();
	const onlyPhase = phaseFilter
		? new Set(
				phaseFilter
					.split(',')
					.map((s) => s.trim())
					.filter(Boolean),
			)
		: null;
	const wantPhase = (name) => !onlyPhase || onlyPhase.has(name);

	const report = { coins: [], errors: [] };

	for (const coin of coins) {
		const result = { mint: coin.mint, symbol: coin.symbol, steps: {} };
		try {
			if (wantPhase('snapshot')) {
				result.steps.snapshot = await coinLib.snapshotHolders(coin);
			}
		} catch (err) {
			result.steps.snapshot = { error: err.message || String(err) };
			report.errors.push({
				mint: coin.mint,
				step: 'snapshot',
				error: result.steps.snapshot.error,
			});
		}

		// Refresh row after snapshot so we have current last_snapshot_at.
		const refreshed1 = await coinLib.loadCoinById(coin.id);
		const c1 = refreshed1 || coin;

		try {
			if (wantPhase('claim')) {
				result.steps.claim = await coinLib.claimAndSplit(c1);
			}
		} catch (err) {
			result.steps.claim = { error: err.message || String(err) };
			report.errors.push({ mint: coin.mint, step: 'claim', error: result.steps.claim.error });
		}

		const refreshed2 = await coinLib.loadCoinById(coin.id);
		const c2 = refreshed2 || c1;

		try {
			if (wantPhase('commit')) {
				result.steps.commit_lottery = await coinLib.commitLottery(c2);
			}
		} catch (err) {
			result.steps.commit_lottery = { error: err.message || String(err) };
			report.errors.push({
				mint: coin.mint,
				step: 'commit_lottery',
				error: result.steps.commit_lottery.error,
			});
		}

		try {
			if (wantPhase('resolve')) {
				result.steps.resolve_lottery = await coinLib.resolvePendingDraws(c2);
			}
		} catch (err) {
			result.steps.resolve_lottery = { error: err.message || String(err) };
			report.errors.push({
				mint: coin.mint,
				step: 'resolve_lottery',
				error: result.steps.resolve_lottery.error,
			});
		}

		const refreshed3 = await coinLib.loadCoinById(coin.id);
		const c3 = refreshed3 || c2;

		try {
			if (wantPhase('reflection')) {
				result.steps.reflection = await coinLib.allocateReflection(c3);
			}
		} catch (err) {
			result.steps.reflection = { error: err.message || String(err) };
			report.errors.push({
				mint: coin.mint,
				step: 'reflection',
				error: result.steps.reflection.error,
			});
		}

		report.coins.push(result);
	}

	return json(res, 200, { ok: true, processed: report.coins.length, report });
}

// ═══════════════════════════════════════════════════════════════════════════
// run-coin-payouts
// ═══════════════════════════════════════════════════════════════════════════
//
// Drains pending coin_payouts rows for every active coin. Each row already has
// a committed amount + recipient (queued by run-coin-cycle); this cron just
// signs + submits the batched SystemProgram.transfer txs.
//
// Runs on a separate schedule from run-coin-cycle so RPC issues on the
// payout side never block fresh draws/reflection from being committed.

async function handleRunCoinPayouts(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	if (!requireCron(req, res)) return;

	// Demo gate — see handleRunCoinCycle. Until COIN_DEMO_ENABLED=true is set,
	// the payout drainer cannot fire even if rows are pending.
	if (process.env.COIN_DEMO_ENABLED !== 'true') {
		return json(res, 200, {
			ok: true,
			disabled: true,
			hint: 'set COIN_DEMO_ENABLED=true to enable',
		});
	}

	const coinLib = await import('../_lib/coin/index.js');
	const coins = await coinLib.listActiveCoins();

	const report = { coins: [], errors: [] };
	for (const coin of coins) {
		try {
			const result = await coinLib.drainPendingPayouts(coin);
			report.coins.push({ mint: coin.mint, ...result });
		} catch (err) {
			report.errors.push({ mint: coin.mint, error: err.message || String(err) });
		}
	}

	return json(res, 200, { ok: true, processed: report.coins.length, report });
}

// ═══════════════════════════════════════════════════════════════════════════
// club-payouts — sweep unpaid Pole Club tips to each dancer's wallet
// ═══════════════════════════════════════════════════════════════════════════

async function handleClubPayouts(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	if (!requireCron(req, res)) return;

	const { runClubPayoutSweep, expireStaleClaims } = await import('../_lib/club/sweep.js');

	// Pre-pass: any PENDING-* claim older than 10min came from a crashed
	// earlier invocation. Release them so this cycle can retry.
	try {
		await expireStaleClaims();
	} catch (err) {
		console.error('[club-payouts] expireStaleClaims failed', err);
	}

	const summary = await runClubPayoutSweep();
	return json(res, 200, { ok: true, ...summary });
}

// ═══════════════════════════════════════════════════════════════════════════
// unstoppable-tick — autonomous agent lifecycle (sense → think → act → settle)
// ═══════════════════════════════════════════════════════════════════════════

async function handleUnstoppableTick(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	if (!requireCron(req, res)) return;

	try {
		const { tick } = await import('../../agents/unstoppable/src/loop.js');
		const result = await tick();
		return json(res, 200, { ok: true, ...result });
	} catch (err) {
		console.error('[unstoppable-tick]', err?.message || err);
		return json(res, 200, { ok: false, error: err?.message || 'tick failed' });
	}
}

// ═══════════════════════════════════════════════════════════════════════════
// cosmetic-splits-sweep — retry pending/failed cosmetic creator payouts
// ═══════════════════════════════════════════════════════════════════════════
//
// When a cosmetic is sold inside a coin's /play world, the creator's USDC cut
// is paid on-chain immediately (best-effort). Any row that didn't land —
// because the treasury wasn't funded, a transient RPC hiccup, or a slow ATA
// creation — stays 'pending' or 'failed'. This cron retries those rows in
// settlement-time order, bounded per run so a large backlog can't stall the
// function. Runs hourly; each cycle processes at most 25 rows.

async function handleCosmeticSplitsSweep(req, res) {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	if (!requireCron(req, res)) return;

	const { sweepPendingCreatorPayouts } = await import('../_lib/cosmetics-economy.js');
	let result;
	try {
		result = await sweepPendingCreatorPayouts({ limit: 25 });
	} catch (err) {
		console.error('[cosmetic-splits-sweep] sweep failed:', err?.message || err);
		return json(res, 200, { ok: false, swept: 0, error: err?.message || 'sweep failed' });
	}
	return json(res, 200, { ok: true, ...result });
}

// ═══════════════════════════════════════════════════════════════════════════
// treasury-autopilot — run every armed agent's treasury policy on a cadence.
//
// Each armed, non-killed agent gets one autopilot cycle: self-fund compute,
// maintain the buffer, DCA income into $THREE, compound coin fees into buybacks,
// and sweep profit — every action real, idempotent, spend-policy-gated, audited.
// Per-agent failures are isolated; one bad agent never aborts the sweep.
// ═══════════════════════════════════════════════════════════════════════════

async function handleTreasuryAutopilot(req, res) {
	if (!requireCron(req, res)) return;
	const { runAutopilotCycle } = await import('../_lib/treasury-autopilot.js');

	let agents;
	try {
		agents = await sql`
			SELECT id
			FROM agent_identities
			WHERE deleted_at IS NULL
			  AND (meta->'autopilot'->>'armed')::boolean = true
			  AND COALESCE((meta->'autopilot'->>'kill_switch')::boolean, false) = false
			  AND meta->>'solana_address' IS NOT NULL
			ORDER BY (meta->'autopilot'->>'updated_at') ASC NULLS FIRST
			LIMIT 200
		`;
	} catch (err) {
		console.error('[treasury-autopilot] fetch armed agents failed:', err?.message || err);
		return json(res, 200, { ok: false, error: 'fetch_failed' });
	}

	let ran = 0;
	let actions = 0;
	const summary = [];
	for (const a of agents) {
		try {
			const result = await runAutopilotCycle({ agentId: a.id, userId: null, network: 'mainnet', trigger: 'cron' });
			if (result?.ran) {
				ran += 1;
				const did = (result.results || []).filter((r) => r.last_status === 'ok').length;
				actions += did;
				summary.push({ agent: a.id, actions: did, reasons: (result.results || []).map((r) => `${r.kind}:${r.last_status}`) });
			}
		} catch (err) {
			console.error('[treasury-autopilot] agent cycle failed:', a.id, err?.message || err);
		}
	}
	return json(res, 200, { ok: true, agents: agents.length, ran, actions, summary });
}