@bolloon/bolloon-agent 0.5.2 → 0.5.3

package/dist/agents/network-pulse.js

@@ -36,6 +36,8 @@ import * as crypto from 'crypto';
 import { DEFAULT_CONFIRMATIONS, LOCAL_DEV_CHAIN_ID } from './chain/chain-config.js';
 // 区块浏览器映射 (chainId → 公网浏览器); 认不出的链没有链接 —— 宁缺勿错, 不编死链
 import { ADDRESS_RE, EXPLORER_URL_RE, TX_HASH_RE, explorerTxUrl } from './chain/explorer.js';
+// 纯分类/折算 (零依赖: 不拖 ethers 进网页进程) —— 付款行的分类与折算都来自这里
+import { classifyTransfer, formatUnits } from './chain/transfer-classify.js';
 // 「待接单任务」的数据源 = 本机公告板目录 (~/.bolloon/tasks/board)。只借**路径常量**,
 // 公告的解析/发布/接单一律留在 task-board.ts (这里不做第二套实现)。
 import { boardDir, REMOTE_CLAIMS_FILE } from './task-board.js';
@@ -386,6 +388,45 @@ export async function emitTradePulse(before, after, h) {
 //   `observed`, **绝不冒充** confirmed/finalized。
 /** 冻结形状: 活动行上限 */
 export const CONFIRMED_ACTIVITY_LIMIT = PULSE_LIMITS.maxConfirmedActivity;
+/** 对外口径用的协议名与来源 (**唯一字面量**; 页面/快照/门都读它) */
+export const PAYER_IDENTITY_METHOD = 'diap-address-binding/1';
+export const PAYER_IDENTITY_SOURCE = 'off-chain-signed';
+/** 名字短写允许的形状 (与 address-binding 的 NAME_SHORT_RE 同规则: 不含 0x / did: / 空格) */
+export const PAYER_NAME_SHORT_RE = /^[A-Za-z0-9._\-\u4e00-\u9fff]{1,24}$/;
+/** DID 短写形状 (`did:key:` 之后的前 12 字符; **不含 did: 前缀**) */
+export const PAYER_DID_SHORT_RE = /^[1-9A-HJ-NP-Za-km-z]{4,16}$/;
+/**
+ * 一条身份短写**能不能用** (**硬闸**, 三关缺一不可):
+ *   ① 必须自称 `verified === true` (未验签的一律作废 —— 不静默降级为"可信");
+ *   ② `method`/`source` 必须是本协议与 `off-chain-signed` (别的来源不许冒充这一路);
+ *   ③ `name_short` / `did_short` 的形状必须精确 (含 0x / did: / 空格 → 直接丢掉, 宁可不出名字)。
+ * 返回 null = **这一行不出身份** (不是"出个空名字")。
+ */
+export function usablePayerIdentity(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const o = v;
+    if (o.verified !== true)
+        return null;
+    if (o.method !== PAYER_IDENTITY_METHOD)
+        return null;
+    if (o.source !== PAYER_IDENTITY_SOURCE)
+        return null;
+    const name = typeof o.name_short === 'string' ? o.name_short.trim() : '';
+    const did = typeof o.did_short === 'string' ? o.did_short.trim() : '';
+    if (!PAYER_NAME_SHORT_RE.test(name))
+        return null;
+    if (!PAYER_DID_SHORT_RE.test(did))
+        return null;
+    if (/0x/i.test(name) || /did:/i.test(name) || /0x/i.test(did) || /did:/i.test(did))
+        return null;
+    return { name_short: name, did_short: did, verified: true, method: PAYER_IDENTITY_METHOD, source: PAYER_IDENTITY_SOURCE };
+}
+/** 地址小写化 (只认 0x+40 的形状; 别的形状 → 空串 = 不匹配任何绑定) */
+function normalizeLookupAddress(a) {
+    const s = String(a || '').trim().toLowerCase();
+    return /^0x[0-9a-f]{40}$/.test(s) ? s : '';
+}
 /**
  * 链上 escrow 事件名 → (kind, state) 的**唯一**映射表 (改这里才对, 别在别处写 switch)。
  *
@@ -475,6 +516,9 @@ export function buildConfirmedActivityFromIndex(entries, opts = {}) {
     // escrow 合约地址白名单 (唯一权威): 只有索引文件自己记的这个地址算数, 别的地址一律不当合约
     const escrow = typeof opts.escrowAddress === 'string' ? opts.escrowAddress.toLowerCase() : '';
     const escrowOk = ADDRESS_RE.test(escrow) ? escrow : '';
+    const token = typeof opts.tokenAddress === 'string' ? opts.tokenAddress.toLowerCase() : '';
+    const tokenOk = ADDRESS_RE.test(token) ? token : '';
+    const decimals = Number.isInteger(Number(opts.tokenDecimals)) && Number(opts.tokenDecimals) >= 0 ? Number(opts.tokenDecimals) : 6;
     const out = [];
     for (const e of Array.isArray(entries) ? entries : []) {
         if (!e || e.suspect === true)
@@ -501,6 +545,11 @@ export function buildConfirmedActivityFromIndex(entries, opts = {}) {
         // 浏览器链接: 该链没有已知公网浏览器 → 返回 null → 键整个不出现 (不编 href="#")
         // 只有**交易**链接 (explorer_tx); 合约地址只在数据里 (contract), 不生成链接 (2026-09-23 收窄)
         const explorerTx = explorerTxUrl(chainId, txHash);
+        // 金额 (2026-09-29): 只从 args.amount 取 (链上事实); 计价地址先折成**符号**再出行 —— 地址不进快照
+        const argsAmt = String(e.args?.amount ?? '');
+        const assetAddr = String(e.args?.paymentAsset ?? '').toLowerCase();
+        const currency = tokenOk && assetAddr === tokenOk ? 'USDC' : '';
+        const amountAtomic = /^[0-9]+$/.test(argsAmt) ? argsAmt : '';
         out.push({
             block, logIndex,
             row: {
@@ -517,6 +566,8 @@ export function buildConfirmedActivityFromIndex(entries, opts = {}) {
                 tx_hash: txHash,
                 ...(contract ? { contract } : {}),
                 ...(explorerTx ? { explorer_tx: explorerTx } : {}),
+                ...(amountAtomic ? { amount_atomic: amountAtomic, amount_display: formatUnits(amountAtomic, decimals) } : {}),
+                ...(amountAtomic && currency ? { currency } : {}),
             },
         });
     }
@@ -576,6 +627,71 @@ export function buildConfirmedActivityFromEvents(events, opts = {}) {
     }
     return rows;
 }
+/**
+ * 转账索引条目 → 付款行 (**纯函数**)。
+ *   · 只出**转入**行 (to ∈ 关注地址集); 出账行不进「链上转入」计数
+ *   · 分类走 classifyTransfer (from == escrow → escrow 退款/释放; from ∈ 自己地址集 → 转入(非销售); 其余 → 外部付款)
+ *   · x402 标记只在**台账拿得到**时才写 (true/false); 台账拿不到 → 键整个不出现 (口径未知)
+ *   · task 恒为空串: 一笔 ERC-20 转账链上**不带** taskKey ⇒ 不猜是哪个任务 (页面/表格靠 tx 定位)
+ *   · tx_hash / explorer_tx 照旧 (公开可核验); from/to 地址一律不出行 (隐私门也不放行)
+ */
+export function buildPaymentRowsFromTransfers(entries, opts = {}) {
+    const gates = normalizeActivityGates(opts.gates);
+    const limit = activityLimit(opts.limit);
+    const chainId = Number.isInteger(Number(opts.chainId)) && Number(opts.chainId) >= 0 ? Number(opts.chainId) : 0;
+    const head = Number.isInteger(Number(opts.headBlock)) && Number(opts.headBlock) >= 0 ? Number(opts.headBlock) : null;
+    const decimals = Number.isInteger(Number(opts.tokenDecimals)) && Number(opts.tokenDecimals) >= 0 ? Number(opts.tokenDecimals) : 6;
+    const symbol = String(opts.tokenSymbol || '');
+    const cfg = { watchAddresses: opts.watchAddresses || [], ownAddresses: opts.ownAddresses || [], escrowAddress: opts.escrowAddress || '' };
+    const out = [];
+    for (const e of Array.isArray(entries) ? entries : []) {
+        if (!e || e.suspect === true)
+            continue;
+        const txHash = String(e.txHash || '').toLowerCase();
+        if (!/^0x[0-9a-f]{64}$/.test(txHash))
+            continue;
+        const block = Number(e.blockNumber);
+        const logIndex = Number(e.logIndex);
+        if (!Number.isInteger(block) || block < 0 || !Number.isInteger(logIndex) || logIndex < 0)
+            continue;
+        const at = isoSeconds(Number(e.firstSeenAt));
+        if (!at)
+            continue;
+        const cls = classifyTransfer({ from: String(e.from || ''), to: String(e.to || ''), direction: e.direction }, cfg);
+        if (cls === 'outbound')
+            continue; // 出账不进「链上转入」
+        // ★ 付款方智能体身份 (链下登记): **只认已验签**的短写; 没匹配 = 这个键整个不出现
+        //   (分类为 outbound 的行上面就 continue 了 ⇒ 「付款方」只会出现在真正的转入行上)
+        const payerIdentity = usablePayerIdentity(opts.payerIdentities ? opts.payerIdentities[normalizeLookupAddress(e.from)] : null);
+        const confirmations = head == null ? Math.max(0, Number(e.confirmations) || 0) : Math.max(0, head - block + 1);
+        const explorerTx = explorerTxUrl(chainId, txHash);
+        const value = /^[0-9]+$/.test(String(e.value || '')) ? String(e.value) : '';
+        const x402Known = !!opts.x402Txs && typeof opts.x402Txs === 'object';
+        out.push({
+            block, logIndex,
+            row: {
+                task: '', // ERC-20 转账不带 taskKey → 不猜
+                kind: 'payment_in',
+                state: 'paid',
+                chain_id: chainId,
+                block,
+                tx: anonShortRef(txHash, 'tx'),
+                confirmations,
+                finality: finalityFromConfirmations(confirmations, gates), // suspect 行在上面就 continue 了
+                at,
+                tx_hash: txHash,
+                ...(explorerTx ? { explorer_tx: explorerTx } : {}),
+                class: cls,
+                ...(value ? { amount_atomic: value, amount_display: formatUnits(value, decimals) } : {}),
+                ...(value && symbol ? { currency: symbol } : {}),
+                ...(x402Known ? { x402: Object.prototype.hasOwnProperty.call(opts.x402Txs, txHash) } : {}),
+                ...(payerIdentity ? { payer_identity: payerIdentity } : {}),
+            },
+        });
+    }
+    out.sort((a, b) => b.block - a.block || b.logIndex - a.logIndex);
+    return out.slice(0, limit).map((x) => x.row);
+}
 /** 纯函数降级: 直接从脉冲事件算活动行 (没有索引时用, source 如实写 pulse-events / none) */
 export function confirmedActivityFromEvents(events, limit) {
     const rows = buildConfirmedActivityFromEvents(events, { limit });
@@ -593,8 +709,54 @@ async function readChainIndex(home) {
         return null;
     }
 }
+/** 惰性加载转账索引 (fs + RPC provider; 只读已落盘索引, 不发 RPC) */
+let transferQueryModule = null;
+async function readTransferIndexFile(home) {
+    try {
+        if (!transferQueryModule)
+            transferQueryModule = (await import('./chain/transfer-index.js'));
+        const m = transferQueryModule;
+        const cfg = m.readTransferWatchConfig(home);
+        const state = m.readTransferIndex(home);
+        return { state, cfg, summary: m.summarizeTransfers(state, cfg) };
+    }
+    catch {
+        return null;
+    }
+}
+/** 卖方端点只读汇总的**缓存** (由 scripts/x402-seller-summary.ts 取数落盘; 这里只读盘, 不发网络) */
+export function readSellerSummaryCacheFile(home) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(home || os.homedir(), '.bolloon', 'x402-seller-summary.json'), 'utf8'));
+        return raw && typeof raw === 'object' ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 惰性加载**付款方身份表** (地址↔DID 绑定库)。
+ * 为什么惰性: `address-binding.ts` 要 ethers (验 EIP-191) 与文件系统 —— 本文件在主站快照/网页
+ * 路径上被静态引入, 加载代价敏感; 而且这一块**失败必须能降级**(没有绑定库 ≠ 快照不可用)。
+ * **重验发生在 address-binding 内部** (`loadPayerIdentityIndex` 每条都当场验一遍),
+ * 本文件拿到的 `byAddress` 只含**已验签**的短写。
+ */
+let payerIdentityModule = null;
+async function readPayerIdentityIndexFile(home) {
+    try {
+        if (!payerIdentityModule)
+            payerIdentityModule = (await import('./identity/address-binding.js'));
+        return await payerIdentityModule.loadPayerIdentityIndex({ home });
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * 解析活动行 (唯一入口): **先链上索引, 再脉冲降级**, 并如实报出来源。
+ * 解析活动行 (唯一入口): **先链上索引 (escrow 事件 + 关注地址集转账), 再脉冲降级**,
+ * 并如实报出来源。
+ *   2026-09-29: 表里现在有**两类行** —— 任务行 (escrow 事件) 与付款行 (USDC 转账),
+ *   同一张表、同一套排序 (块号/时间 新→旧), 不拆成两块。
  * 索引文件不存在/读不出/没有任何可用行 → 退回脉冲事件; 两边都没有 → none (不编行)。
  */
 export async function resolveConfirmedActivity(q) {
@@ -607,17 +769,101 @@ export async function resolveConfirmedActivity(q) {
     try {
         const file = await reader(q.home);
         const entries = Array.isArray(file?.entries) ? file.entries : [];
-        if (entries.length > 0) {
+        // ①b 转账索引 (关注地址集内收款) + 卖方端点汇总缓存 (x402 交叉核)
+        const tReader = q.readTransfers ?? readTransferIndexFile;
+        let transfers = null;
+        try {
+            transfers = await tReader(q.home);
+        }
+        catch {
+            transfers = null;
+        }
+        const sellerCache = (q.readSellerSummary ?? readSellerSummaryCacheFile)(q.home);
+        const sellerOk = !!sellerCache && sellerCache.available === true && sellerCache.txs && typeof sellerCache.txs === 'object';
+        const x402Txs = sellerOk ? sellerCache.txs : null;
+        // ★ 付款方身份 (链下登记, 2026-09-29): 只有**已验签**的绑定才会让付款行多出 `payer_identity`。
+        //   读不到/没有绑定库 ⇒ 空表 (行里没有这个键), 快照的 payer_identity_scope 如实说原因。
+        const tPayer = q.readPayerIdentities ?? readPayerIdentityIndexFile;
+        let payer = null;
+        try {
+            payer = await tPayer(q.home);
+        }
+        catch {
+            payer = null;
+        }
+        if (entries.length > 0 || (transfers && transfers.state?.entries?.length > 0)) {
             const gates = normalizeActivityGates(file?.confirmations);
-            const rows = buildConfirmedActivityFromIndex(entries, {
-                gates,
-                headBlock: file?.headBlock,
-                chainId: file?.chainId,
-                limit,
-                escrowAddress: file?.escrowAddress, // 合约地址白名单 = 索引文件自己的部署身份
-            });
-            if (rows.length > 0)
-                return { source: 'chain-index', rows, gates };
+            const taskRows = entries.length > 0
+                ? buildConfirmedActivityFromIndex(entries, {
+                    gates,
+                    headBlock: file?.headBlock,
+                    chainId: file?.chainId,
+                    limit,
+                    escrowAddress: file?.escrowAddress, // 合约地址白名单 = 索引文件自己的部署身份
+                    tokenAddress: (file?.tokenAddress ?? transfers?.cfg?.tokenAddress) || null,
+                    tokenDecimals: (file?.tokenDecimals ?? transfers?.cfg?.tokenDecimals) ?? null,
+                })
+                : [];
+            const paymentRows = transfers && transfers.state?.entries?.length > 0
+                ? buildPaymentRowsFromTransfers(transfers.state.entries, {
+                    gates,
+                    headBlock: transfers.state.headBlock ?? file?.headBlock,
+                    chainId: transfers.state.chainId ?? file?.chainId,
+                    limit,
+                    watchAddresses: transfers.state.watchAddresses,
+                    ownAddresses: transfers.cfg.ownAddresses,
+                    escrowAddress: transfers.state.chainId ? (transfers.cfg.escrowAddress || file?.escrowAddress) : transfers.cfg.escrowAddress,
+                    tokenSymbol: transfers.state.tokenSymbol,
+                    tokenDecimals: transfers.state.tokenDecimals,
+                    x402Txs, // null = 台账拿不到 → 行里不写 x402 键 (口径未知)
+                    payerIdentities: payer && payer.byAddress && typeof payer.byAddress === 'object' ? payer.byAddress : null,
+                })
+                : [];
+            // 两类行合并: 同一张表、同一套排序 (块号 desc, logIndex desc); 上限就是冻结的 25 行
+            const merged = [...taskRows, ...paymentRows]
+                .sort((a, b) => (Number(b.block) - Number(a.block)) || (String(b.tx).localeCompare(String(a.tx))))
+                .slice(0, limit);
+            if (merged.length > 0) {
+                return {
+                    source: 'chain-index',
+                    rows: merged,
+                    gates,
+                    transfers: transfers ? transfers.summary : null,
+                    payer_identity: payer
+                        ? {
+                            loaded: Number(payer.loaded) || 0,
+                            verified: Number(payer.verified) || 0,
+                            rejected: Array.isArray(payer.rejected) ? payer.rejected : [],
+                            byAddress: payer.byAddress && typeof payer.byAddress === 'object' ? payer.byAddress : {},
+                            reason: String(payer.reason || ''),
+                            dir: String(payer.dir || ''),
+                            label: payer.label || { zh: '链下登记(可离线验签)', en: 'off-chain registration (verifiable offline)' },
+                            note: payer.note || { zh: '', en: '' },
+                        }
+                        : null,
+                    index_info: entries.length > 0
+                        ? {
+                            chainId: Number(file?.chainId) || 0,
+                            networkName: String(file?.networkName || 'unknown'),
+                            escrowAddress: String(file?.escrowAddress || ''),
+                            deploymentBlock: Number(file?.deploymentBlock) || 0,
+                            lastSyncedBlock: Number(file?.lastSyncedBlock) || 0,
+                            headBlock: Number.isInteger(Number(file?.headBlock)) ? Number(file.headBlock) : null,
+                            rows: entries.length,
+                            pageSize: Number(file?.pageSize) || 2000,
+                        }
+                        : null,
+                    seller_summary: sellerCache
+                        ? {
+                            available: sellerOk,
+                            reason: String(sellerCache.reason || ''),
+                            fetched_at: Number.isFinite(Number(sellerCache.fetched_at)) ? Number(sellerCache.fetched_at) : null,
+                            endpoint: sellerCache.endpoint ? String(sellerCache.endpoint) : null,
+                            count: sellerOk ? Number(sellerCache.count) : null,
+                        }
+                        : { available: false, reason: '本机没有卖方端点汇总缓存 (~/.bolloon/x402-seller-summary.json 不存在) → 「经 x402 流程」口径未知', fetched_at: null, endpoint: null, count: null },
+                };
+            }
         }
     }
     catch { /* 索引不可用 → 降级 (来源会在快照里标明) */ }
@@ -664,16 +910,50 @@ export function summarizeActivityRows(rows, opts) {
     const list = (Array.isArray(rows) ? rows : []).filter((r) => !!r);
     const tasks = new Set();
     const completed = new Set();
-    const settled = new Set();
+    const settled = new Set(); // 只有 released (钱真释放给卖方)
+    const refunded = new Set();
+    const disputed = new Set();
+    const expired = new Set();
     const by_finality = { observed: 0, confirmed: 0, finalized: 0 };
+    let paymentsIn = 0, paymentsExternal = 0, paymentsSelf = 0, paymentsEscrow = 0;
+    let paidAtomic = 0n, x402Atomic = 0n;
+    let x402Count = 0, x402Known = 0;
     for (const r of list) {
         const t = String(r.task || '');
         if (t)
             tasks.add(t);
         if (t && r.kind === 'task_completed')
             completed.add(t);
-        if (t && r.kind === 'trade_settled')
-            settled.add(t);
+        if (t && r.kind === 'trade_settled') {
+            // ★ 2026-09-29: 按 **state** 分桶 —— 只有 released 才是"已结算(释放给卖方)";
+            //   退款/争议/过期各算各的 (旧实现把四类并成一个 5 ⇒ 出现「已结算 5 > 已完成 3」的假读数)
+            if (r.state === 'released')
+                settled.add(t);
+            else if (r.state === 'refunded')
+                refunded.add(t);
+            else if (r.state === 'disputed')
+                disputed.add(t);
+            else if (r.state === 'expired')
+                expired.add(t);
+        }
+        if (r.kind === 'payment_in') {
+            paymentsIn++;
+            const v = /^[0-9]+$/.test(String(r.amount_atomic ?? '')) ? BigInt(r.amount_atomic) : 0n;
+            paidAtomic += v;
+            if (r.class === 'external_payment')
+                paymentsExternal++;
+            else if (r.class === 'self_transfer')
+                paymentsSelf++;
+            else if (r.class === 'escrow_settlement')
+                paymentsEscrow++;
+            if (Object.prototype.hasOwnProperty.call(r, 'x402')) {
+                x402Known++;
+                if (r.x402 === true) {
+                    x402Count++;
+                    x402Atomic += v;
+                }
+            }
+        }
         if (r.finality === 'observed' || r.finality === 'confirmed' || r.finality === 'finalized') {
             by_finality[r.finality] += 1;
         }
@@ -684,10 +964,83 @@ export function summarizeActivityRows(rows, opts) {
         tasks: tasks.size,
         tasks_completed: completed.size,
         tasks_settled: settled.size,
+        tasks_refunded: refunded.size,
+        tasks_disputed: disputed.size,
+        tasks_expired: expired.size,
+        payments_in: paymentsIn,
+        payments_in_total_atomic: paidAtomic.toString(),
+        payments_in_external: paymentsExternal,
+        payments_in_self: paymentsSelf,
+        payments_in_escrow: paymentsEscrow,
+        // x402 口径: **所有**付款行都带 x402 键才算"知道"; 否则 null (未知 ≠ 0)
+        payments_in_x402: x402Known === paymentsIn ? x402Count : null,
+        payments_in_x402_total_atomic: x402Known === paymentsIn ? x402Atomic.toString() : null,
         by_finality,
         gates: normalizeActivityGates(opts.gates),
     };
 }
+/** 覆盖口径 (纯函数; 不发网络: liveHeadBlock 由调用方(导出脚本)读好传入) */
+export function buildIndexScope(input) {
+    const srcs = [];
+    if (input.escrow && Number.isFinite(Number(input.escrow.deploymentBlock))) {
+        srcs.push({
+            kind: 'escrow-contract',
+            label: { zh: 'AgentEscrow 合约事件 (创建/提交证明/释放/争议/退款/到期)', en: 'AgentEscrow contract events (created / proof / released / disputed / refunded / expired)' },
+            from_block: Number(input.escrow.deploymentBlock),
+            last_scanned_block: Number(input.escrow.lastSyncedBlock),
+            rows: Number(input.escrow.rows) || 0,
+            scan_chunk_blocks: Number(input.escrow.pageSize) || 2000,
+        });
+    }
+    const t = input.transfers || null;
+    // 只有**真同步过**的转账索引才算一个源: 从未同步 (from_block 0 / last_synced_block -1) 时不列它
+    // —— 列出来会出现「扫到哪 (-1) 比起块 (0) 还早」这种说不出覆盖范围的源 (导出前的自检就该判红)。
+    if (t && t.configured && Number(t.from_block) > 0 && Number(t.last_synced_block) >= Number(t.from_block)) {
+        srcs.push({
+            kind: 'erc20-transfers',
+            label: { zh: `关注地址集内的 ${t.token_symbol || 'ERC20'} 转账 (转入/转出)`, en: `${t.token_symbol || 'ERC20'} transfers in/out of the watched address set` },
+            from_block: t.from_block,
+            last_scanned_block: t.last_synced_block,
+            rows: t.entries,
+            token_symbol: t.token_symbol,
+            token_decimals: t.token_decimals,
+            watch_addresses_count: t.watch_addresses_count,
+        });
+    }
+    if (!srcs.length)
+        return null;
+    const fromBlock = Math.min(...srcs.map((s) => s.from_block));
+    const lastScanned = Math.min(...srcs.map((s) => s.last_scanned_block));
+    const live = Number.isFinite(Number(input.liveHeadBlock)) && Number(input.liveHeadBlock) > 0 ? Number(input.liveHeadBlock) : null;
+    const lag = live == null ? null : Math.max(0, live - lastScanned);
+    const networkName = String(input.networkName || 'unknown');
+    const label = chainLabelOf(Number(input.chainId)) || null;
+    const netZh = label?.zh || networkName;
+    return {
+        source: 'chain-index',
+        chain_id: Number(input.chainId) || 0,
+        network_name: networkName,
+        network_label: label ? { zh: label.zh, en: label.en } : null,
+        coverage: {
+            zh: `本索引覆盖 ${netZh}上该合约 (AgentEscrow 事件) 与该地址集内 (USDC 转账) 的全部交互 —— 消息/心跳/任务报文不上链, 不在本口径内`,
+            en: `This index covers all interactions on ${label?.en || networkName} for that contract (AgentEscrow events) and within the watched address set (USDC transfers). Messages/heartbeats/task envelopes are not on-chain and are outside this scope.`,
+        },
+        sources: srcs,
+        from_block: fromBlock,
+        last_scanned_block: lastScanned,
+        head_block_at_sync: input.escrow && Number.isFinite(Number(input.escrow.headBlock)) ? Number(input.escrow.headBlock) : (t?.head_block ?? null),
+        head_block_live: live,
+        lag_blocks: lag,
+        note: {
+            zh: live == null
+                ? `索引起止: ${fromBlock} → ${lastScanned}; 真链 head **未读到** (RPC 不可达) ⇒ 落后多少块未知 (不拿同步时的高度冒充)`
+                : `索引起止: ${fromBlock} → ${lastScanned}; 真链 head ${live} (读于导出时刻) ⇒ 落后 ${lag} 块 —— 这不是"实时全网"`,
+            en: live == null
+                ? `Index range: ${fromBlock} → ${lastScanned}; live chain head NOT read (RPC unreachable) so the lag is unknown (we do not pass off the sync-time height as the live head)`
+                : `Index range: ${fromBlock} → ${lastScanned}; live chain head ${live} (read at export time) ⇒ ${lag} blocks behind — this is not a real-time view of the whole chain`,
+        },
+    };
+}
 /** 活动行 → 链归属 (**纯函数**)。所有结论都从行本身推, 不引用外部状态 → 不可能与行数打架。 */
 export function buildChainIdScope(rows) {
     const list = (Array.isArray(rows) ? rows : []).filter((r) => !!r);
@@ -786,14 +1139,180 @@ export function snapshotConsistencyIssues(snap) {
     issues.push(...auditPublicHexLeaks(snap)); // ⑥ 0x 长 hex 越界 → 拒绝导出 (不静默放行)
     issues.push(...openTasksIssues(snap)); // ⑦ 待接单任务的字段白名单与「只含未认领」不变式
     issues.push(...totalsScopeIssues(snap)); // ⑧ ★ 同一概念不得并排两个数 (顶部 vs 表格)
+    issues.push(...transferTotalsIssues(snap)); // ⑨ ★ 转入分桶必须与同行数算出来的一致
+    issues.push(...indexScopeIssues(snap)); // ⑩ ★ 覆盖口径/起止块/落后块数必须自洽
+    issues.push(...payerIdentityIssues(snap)); // ⑪ ★ 付款方身份只许是**已验签**的短写 (链下登记)
     return issues;
 }
+/**
+ * ⑨ 链上转入分桶自检 (2026-09-29): `transfer_totals` 与 `activity_totals` 是**同一批行**的两种投影,
+ * 对不上就是有人手改了其中一个 (页面上会出现"合计 4 笔 / 分桶 3 笔"这种读不通的数)。
+ * 另外: 未配置关注地址集时**不许**出现一个 0 —— 那会被读成"一笔都没有"。
+ */
+export function transferTotalsIssues(snap) {
+    const out = [];
+    const tt = snap?.transfer_totals;
+    const at = snap?.activity_totals || {};
+    const t = snap?.totals || {};
+    if (tt == null)
+        return out; // 没有转账源 → 这一块不出现 (合法)
+    if (typeof tt !== 'object')
+        return ['transfer_totals 必须是对象或 null'];
+    if (tt.configured !== true) {
+        // 未配置/没同步: 不许拿 0 冒充 —— 注意判据是「**有没有值**」而不是「值是不是数字 0」:
+        // null 才是"没有源"的正确写法 (Number(null)===0 会把"没源"误判成"报了 0")。
+        const hasVal = (v) => v !== null && v !== undefined;
+        // 只看**页面上真要显示**的那两个字段 (totals.payments_in / _total_atomic) 与分桶笔数:
+        // activity_totals.payments_in 是「这一批行里有几笔 payment_in」的**同源行数**, 它天生是数字
+        // (没有付款行时就是 0), 页面不显示它 —— 拿它来判「报了 0」是判错了对象。
+        if (hasVal(t.payments_in) || hasVal(t.payments_in_total_atomic) || Number(tt.inbound) > 0) {
+            out.push('transfer_totals.configured=false 却报出了转入笔数/金额 —— 未配置不是「一笔都没有」, 必须是 null (页面写「未接入」)');
+        }
+        return out;
+    }
+    if (Number(tt.inbound) !== Number(at.payments_in)) {
+        out.push(`transfer_totals.inbound=${tt.inbound} ≠ activity_totals.payments_in=${at.payments_in} (同一批行必须相等)`);
+    }
+    const cls = ['escrow_settlement', 'self_transfer', 'external_payment'];
+    const sumCls = cls.reduce((n, k) => n + (Number(tt.by_class?.[k]) || 0), 0);
+    if (sumCls !== Number(tt.inbound)) {
+        out.push(`transfer_totals.by_class 三桶之和=${sumCls} ≠ inbound=${tt.inbound} (每一笔转入都必须落进恰好一个桶)`);
+    }
+    let sumAtomic = 0n;
+    for (const k of cls)
+        sumAtomic += BigInt(String(tt.by_class_atomic?.[k] ?? '0'));
+    if (sumAtomic.toString() !== String(tt.inbound_total_atomic)) {
+        out.push(`transfer_totals.by_class_atomic 之和=${sumAtomic} ≠ inbound_total_atomic=${tt.inbound_total_atomic}`);
+    }
+    if (String(tt.inbound_total_atomic) !== String(at.payments_in_total_atomic)) {
+        out.push(`transfer_totals.inbound_total_atomic=${tt.inbound_total_atomic} ≠ activity_totals.payments_in_total_atomic=${at.payments_in_total_atomic}`);
+    }
+    return out;
+}
+/**
+ * ⑩ 覆盖口径自检 (2026-09-29): 「本索引覆盖…起止块…落后多少块」这句话必须能被数字复算 ——
+ *   · 每个源 from_block ≤ last_scanned_block;
+ *   · 顶层 last_scanned_block = 各源的最小值 (覆盖到哪以**最落后**的那个源为准);
+ *   · lag_blocks = head_block_live − last_scanned_block; 真链 head 读不到 ⇒ lag **必须是 null**
+ *     (拿同步时的高度冒充真链 head 就是"暗示实时")。
+ */
+export function indexScopeIssues(snap) {
+    const out = [];
+    const is = snap?.index_scope;
+    if (is == null)
+        return out; // 没有链上源 → 不出现 (合法)
+    if (typeof is !== 'object')
+        return ['index_scope 必须是对象或 null'];
+    const srcs = Array.isArray(is.sources) ? is.sources : [];
+    if (!srcs.length)
+        out.push('index_scope.sources 不能是空数组 (要么整块不出现, 要么至少一个源)');
+    for (const [i, s] of srcs.entries()) {
+        const f = Number(s?.from_block), l = Number(s?.last_scanned_block);
+        if (!Number.isFinite(f) || !Number.isFinite(l)) {
+            out.push(`index_scope.sources[${i}] 缺 from_block/last_scanned_block`);
+            continue;
+        }
+        if (l < f)
+            out.push(`index_scope.sources[${i}].last_scanned_block=${l} < from_block=${f} (扫到哪不能比起块还早)`);
+        if (l > Number(is.head_block_live ?? l))
+            out.push(`index_scope.sources[${i}].last_scanned_block=${l} 比真链 head=${is.head_block_live} 还高`);
+    }
+    if (srcs.length) {
+        const minFrom = Math.min(...srcs.map((s) => Number(s.from_block)));
+        const minLast = Math.min(...srcs.map((s) => Number(s.last_scanned_block)));
+        if (Number(is.from_block) !== minFrom)
+            out.push(`index_scope.from_block=${is.from_block} ≠ 各源最小起块=${minFrom}`);
+        if (Number(is.last_scanned_block) !== minLast)
+            out.push(`index_scope.last_scanned_block=${is.last_scanned_block} ≠ 各源最小 last_scanned_block=${minLast} (覆盖到哪以最落后的源为准)`);
+    }
+    const live = is.head_block_live;
+    if (live == null) {
+        if (is.lag_blocks != null)
+            out.push('index_scope.head_block_live 读不到 (null) 却给了 lag_blocks —— 落后块数必须未知, 不许拿同步时的高度顶替');
+    }
+    else {
+        const expect = Math.max(0, Number(live) - Number(is.last_scanned_block));
+        if (Number(is.lag_blocks) !== expect)
+            out.push(`index_scope.lag_blocks=${is.lag_blocks} ≠ head_block_live−last_scanned_block=${expect}`);
+    }
+    if (!is.coverage?.zh || !is.coverage?.en)
+        out.push('index_scope.coverage 必须双语都给 (口径句是这一块的核心)');
+    return out;
+}
+/**
+ * ⑪ 付款方身份自检 (2026-09-29, `diap-address-binding/1`) —— **只收紧不放松**:
+ *   · 行里出现 `payer_identity` 就必须有 `payer_identity_scope` (口径不能缺);
+ *   · 每条身份必须是**已验签**的短写: `verified===true` · `method`/`source` 逐字对 · 键集恰好 5 个 ·
+ *     `name_short`/`did_short` 形状精确且**不含** `0x` / `did:` / 空格 (出了就是泄漏形态);
+ *   · `payer_identity` 只许出现在 `payment_in` 行上 (别的行没有"付款方"这一说);
+ *   · `rows_with_identity` 必须等于行里**真数出来**的条数 (同一批行, 同一时刻);
+ *   · 口径说 `verified=0` 却行里有身份 ⇒ 自相矛盾。
+ * 过了这道门, 快照里"出名字"这件事就只剩一种可能: 本机有一份**加载时重验通过**的绑定。
+ */
+export function payerIdentityIssues(snap) {
+    const out = [];
+    const rows = Array.isArray(snap?.confirmed_activity) ? snap.confirmed_activity : [];
+    const withId = rows.filter((r) => r && r.payer_identity);
+    const scope = snap?.payer_identity_scope;
+    if (withId.length > 0 && (!scope || typeof scope !== 'object')) {
+        out.push(`有 ${withId.length} 行带 payer_identity 却没有 payer_identity_scope —— 口径不能缺`);
+    }
+    if (scope != null && typeof scope !== 'object')
+        out.push('payer_identity_scope 必须是对象或 null');
+    const KEYS = ['did_short', 'method', 'name_short', 'source', 'verified'];
+    for (const [i, r] of rows.entries()) {
+        const id = r?.payer_identity;
+        if (!id)
+            continue;
+        if (id.verified !== true)
+            out.push(`confirmed_activity[${i}].payer_identity.verified=${String(id.verified)} —— 只有已验签的绑定才许出行`);
+        if (id.method !== PAYER_IDENTITY_METHOD)
+            out.push(`confirmed_activity[${i}].payer_identity.method=${String(id.method)} ≠ ${PAYER_IDENTITY_METHOD}`);
+        if (id.source !== PAYER_IDENTITY_SOURCE)
+            out.push(`confirmed_activity[${i}].payer_identity.source=${String(id.source)} ≠ ${PAYER_IDENTITY_SOURCE}`);
+        const keys = Object.keys(id).sort();
+        if (JSON.stringify(keys) !== JSON.stringify(KEYS))
+            out.push(`confirmed_activity[${i}].payer_identity 键集=${JSON.stringify(keys)} ≠ ${JSON.stringify(KEYS)}`);
+        if (!PAYER_NAME_SHORT_RE.test(String(id.name_short || '')))
+            out.push(`confirmed_activity[${i}].payer_identity.name_short 形状非法: ${JSON.stringify(id.name_short)}`);
+        if (!PAYER_DID_SHORT_RE.test(String(id.did_short || '')))
+            out.push(`confirmed_activity[${i}].payer_identity.did_short 形状非法: ${JSON.stringify(id.did_short)}`);
+        for (const [k, v] of Object.entries(id)) {
+            if (typeof v === 'string' && (/0x/i.test(v) || /did:/i.test(v))) {
+                out.push(`confirmed_activity[${i}].payer_identity.${k} 含 0x/did: 形态 —— 短写里不许出现`);
+            }
+        }
+        if (String(r.kind || '') !== 'payment_in') {
+            out.push(`confirmed_activity[${i}] kind=${String(r.kind)} 却带 payer_identity —— 只有付款行才有"付款方"`);
+        }
+    }
+    if (scope && typeof scope === 'object') {
+        if (!scope.label?.zh || !scope.label?.en)
+            out.push('payer_identity_scope.label 必须双语 (口径句不能只写一种语言)');
+        if (Number(scope.rows_with_identity) !== withId.length) {
+            out.push(`payer_identity_scope.rows_with_identity=${scope.rows_with_identity} ≠ 行里真数出来的 ${withId.length} (同一批行必须相等)`);
+        }
+        if (Number(scope.verified) === 0 && withId.length > 0) {
+            out.push('payer_identity_scope.verified=0 却行里有身份 —— 自相矛盾');
+        }
+        if (Number(scope.rejected) !== (Array.isArray(scope.rejected_reasons) ? scope.rejected_reasons.length : 0)) {
+            out.push(`payer_identity_scope.rejected=${scope.rejected} ≠ rejected_reasons 条数=${Array.isArray(scope.rejected_reasons) ? scope.rejected_reasons.length : 0}`);
+        }
+        if (scope.method !== PAYER_IDENTITY_METHOD || scope.source !== PAYER_IDENTITY_SOURCE) {
+            out.push(`payer_identity_scope.method/source 必须是 ${PAYER_IDENTITY_METHOD} / ${PAYER_IDENTITY_SOURCE}`);
+        }
+    }
+    return out;
+}
 /** 顶部逐字段口径的键 (与 `TotalsFieldKey` 逐字一致; 少一个 = 那个数没有来源说明) */
 export const TOTALS_FIELD_KEYS = [
     'nodes', 'agents', 'active_agents', 'seen_last_24h',
-    'tasks', 'tasks_completed', 'tasks_verified', 'tasks_settled', 'signatures',
+    'tasks', 'tasks_completed', 'tasks_verified', 'tasks_settled',
+    'tasks_refunded', 'tasks_disputed',
+    'payments_in', 'payments_in_total_atomic', 'payments_in_x402', 'payments_in_x402_total_atomic',
+    'signatures',
 ];
-const TOTALS_FIELD_SOURCES = ['pulse-events', 'chain-index', 'signature-audit', 'none'];
+const TOTALS_FIELD_SOURCES = ['pulse-events', 'chain-index', 'signature-audit', 'x402-ledger', 'none'];
 const TOTALS_FIELD_WINDOWS = ['window-24h', 'full', 'unknown'];
 /** 「未接入」类措辞 (无源时必须出现, 否则等于没说清为什么没有数) */
 const UNAVAILABLE_WORDS = /未接入|not connected|无可用源|no available source/;
@@ -870,6 +1389,10 @@ export function totalsScopeIssues(snap) {
             ['tasks', t.tasks, at.tasks],
             ['tasks_completed', t.tasks_completed, at.tasks_completed],
             ['tasks_settled', t.tasks_settled, at.tasks_settled],
+            ['tasks_refunded', t.tasks_refunded, at.tasks_refunded],
+            ['tasks_disputed', t.tasks_disputed, at.tasks_disputed],
+            ['payments_in', t.payments_in, at.payments_in],
+            ['payments_in_total_atomic', t.payments_in_total_atomic, at.payments_in_total_atomic],
         ];
         const tableRows = Number(at.rows) || rows.length;
         const sameSourceChain = String(at.source) === 'chain-index';
@@ -1005,6 +1528,22 @@ function noneField(why) {
         unavailable: true,
     };
 }
+/**
+ * 「卖方端点只读汇总」口径 (2026-09-29): 链上**没有** x402 事件 —— 付款就是一笔普通 ERC-20
+ * USDC 转账, 所以单看链分不出「走 x402 下单流程的付款」与「别人随手转来的账」。这一格的口径 =
+ * 拿卖方端点台账里的 txHash 列表与链上扫到的收款**交叉核** (对上的才加标「经 x402 流程」)。
+ */
+function x402LedgerField(what) {
+    return {
+        source: 'x402-ledger',
+        window: 'full',
+        short: { zh: '经 x402 台账', en: 'via x402 ledger' },
+        label: {
+            zh: `卖方端点只读汇总的 txHash 列表与链上收款交叉核 (链上没有 x402 事件, 只能这样判) · ${what.zh}`,
+            en: `cross-checked against the seller endpoint's read-only txHash list (there is no x402 event on chain, this is the only way) · ${what.en}`,
+        },
+    };
+}
 export function computeSnapshot(events, opts) {
     const now = opts.now;
     const fresh_until = now + PULSE_LIMITS.snapshotTtlMs;
@@ -1022,6 +1561,11 @@ export function computeSnapshot(events, opts) {
             totals: {
                 nodes: 0, agents: 0, active_agents: 0, seen_last_24h: 0,
                 tasks: null, tasks_completed: null, tasks_verified: null, signatures: null, tasks_settled: null,
+                // 2026-09-29: 不可用态下这些链上计数一律 null (未接入), 不给 0
+                tasks_refunded: null, tasks_disputed: null,
+                payments_in: null, payments_in_total_atomic: null,
+                payments_in_x402: null, payments_in_x402_total_atomic: null,
+                payments_in_total_usdc: null, payments_in_x402_total_usdc: null, payments_in_currency: null,
             },
             totals_scope: {
                 source: 'pulse-events', window_ms: PULSE_LIMITS.windowMs,
@@ -1034,8 +1578,15 @@ export function computeSnapshot(events, opts) {
                     nodes: downField, agents: downField, active_agents: downField, seen_last_24h: downField,
                     tasks: downField, tasks_completed: downField, tasks_verified: downField,
                     tasks_settled: downField, signatures: downField,
+                    tasks_refunded: downField, tasks_disputed: downField,
+                    payments_in: downField, payments_in_total_atomic: downField,
+                    payments_in_x402: downField, payments_in_x402_total_atomic: downField,
                 },
             },
+            transfer_totals: null,
+            x402_ledger: null,
+            index_scope: null,
+            payer_identity_scope: null,
             capabilities: [],
             recent_activity: [],
             confirmed_activity: emptyRows,
@@ -1125,8 +1676,35 @@ export function computeSnapshot(events, opts) {
     const totalsTasks = chainAuthoritative ? activity_totals.tasks : tasks.size;
     const totalsCompleted = chainAuthoritative ? activity_totals.tasks_completed : tasksCompleted.size;
     const totalsSettled = chainAuthoritative ? activity_totals.tasks_settled : tasksSettledPulse.size;
+    // ★ 2026-09-29: 退款 / 争议**单列** —— 旧实现把它们并进 tasks_settled, 页面上就出现
+    //   「已结算 5 > 已完成 3」这种假读数 (5 = Released 3 + Refunded 2, 而退款根本不是成交)。
+    const totalsRefunded = chainAuthoritative ? activity_totals.tasks_refunded : null;
+    const totalsDisputed = chainAuthoritative ? activity_totals.tasks_disputed : null;
     // 「验真」在链上索引里**没有**对应事件 → 链上口径下这个数没有源 (null + 未接入), 不拿结算数冒充已验证
     const totalsVerified = chainAuthoritative ? null : tasksVerified.size;
+    // ★ 链上转入 (关注地址集内的 USDC 转账): 只有**关注地址集配好 且 索引可用**才算"有源";
+    //   没配/没读到 → null + 未接入 (0 的意思是"一笔都没有", 那是另一句话)。
+    const transferSummary = activity.transfers ?? null;
+    // 「有源」的判据 (2026-09-29 收紧): 关注地址集配好 **且** 转账索引真同步过 —— 只配了地址集、
+    // 索引却从没同步成功 (from_block 0 / last_synced_block -1) 时, 报 0 笔会把"没读到"说成"一笔都没有"。
+    const transferSynced = !!transferSummary && transferSummary.configured === true &&
+        Number(transferSummary.from_block) > 0 && Number(transferSummary.last_synced_block) >= Number(transferSummary.from_block);
+    const paymentsKnown = chainAuthoritative && transferSynced;
+    const totalsPaymentsIn = paymentsKnown ? activity_totals.payments_in : null;
+    const totalsPaymentsInAtomic = paymentsKnown && activity_totals.payments_in !== null
+        ? Number(activity_totals.payments_in_total_atomic)
+        : null;
+    // 其中经 x402 流程: 口径来自**卖方端点只读汇总**的交叉核 (链上只有普通 ERC-20 转账, 单看链分不出)。
+    //   台账拿不到 → null + 未接入 (原因写清楚), **绝不当 0**。
+    const seller = activity.seller_summary ?? null;
+    const x402Known = paymentsKnown && !!seller && seller.available === true && activity_totals.payments_in_x402 !== null;
+    const totalsPaymentsX402 = x402Known ? activity_totals.payments_in_x402 : null;
+    const totalsPaymentsX402Atomic = x402Known && activity_totals.payments_in_x402_total_atomic !== null
+        ? Number(activity_totals.payments_in_x402_total_atomic)
+        : null;
+    const x402UnknownWhy = !paymentsKnown
+        ? { zh: '链上转入这一格没有源 (关注地址集未配置/索引不可用)', en: 'no source for chain receipts (watched address set not configured / index unavailable)' }
+        : { zh: `卖方端点只读汇总取不到 → 「经 x402 流程」口径未知${seller?.reason ? ` (原因: ${seller.reason})` : ''}`, en: `seller read-only summary unavailable → the "via x402 flow" figure is unknown${seller?.reason ? ` (reason: ${seller.reason})` : ''}` };
     // 钱包签名: 真源 = 本机签名审计账 (窗口内条数, 只计数); 没有审计账 → 退回脉冲事件上报数;
     // 两个都没有 → null (未接入)。**绝不**在没有源的时候报 0 (那是「没发生过」, 是另一句话)。
     const sigTally = opts.signatureAudit ?? null;
@@ -1146,8 +1724,26 @@ export function computeSnapshot(events, opts) {
             ? chainField({ zh: '交付完成 (ProofSubmittedV2) 的不同任务', en: 'distinct tasks with ProofSubmittedV2' })
             : pulseField({ zh: '交付完成的任务', en: 'tasks observed as completed' }),
         tasks_settled: chainAuthoritative
-            ? chainField({ zh: '托管结算 (Released/Refunded/Expired/Disputed) 的不同任务', en: 'distinct tasks with an on-chain escrow settlement' })
+            ? chainField({ zh: '托管**释放给卖方** (ReleasedV2) 的不同任务 —— 只有钱真从合约出给卖方才算', en: 'distinct tasks whose escrow was RELEASED to the seller (ReleasedV2)' })
             : pulseField({ zh: '链上口径结算的任务', en: 'tasks with on-chain settlement' }),
+        tasks_refunded: chainAuthoritative
+            ? chainField({ zh: '争议后退款 (RefundedV2) 的不同任务 —— **不是成交**', en: 'distinct tasks refunded after a dispute (RefundedV2) — NOT a sale' })
+            : noneField({ zh: '脉冲口径没有退款事件', en: 'the pulse scope has no refund event' }),
+        tasks_disputed: chainAuthoritative
+            ? chainField({ zh: '争议中 (DisputedV2, 资金冻结) 的不同任务', en: 'distinct tasks under dispute (DisputedV2, funds frozen)' })
+            : noneField({ zh: '脉冲口径没有争议事件', en: 'the pulse scope has no dispute event' }),
+        payments_in: paymentsKnown
+            ? chainField({ zh: '关注地址集内收到的 USDC 转账笔数 (含退款与自有转入, 逐行可核验)', en: 'incoming USDC transfers to the watched address set (refunds and self top-ups included; every row verifiable)' })
+            : noneField({ zh: '关注地址集未配置 / 转账索引不可用', en: 'watched address set not configured / transfer index unavailable' }),
+        payments_in_total_atomic: paymentsKnown
+            ? chainField({ zh: '上面这些转入的金额合计 (原子单位, 6 位小数)', en: 'total of the incoming transfers above (atomic units, 6 decimals)' })
+            : noneField({ zh: '关注地址集未配置 / 转账索引不可用', en: 'watched address set not configured / transfer index unavailable' }),
+        payments_in_x402: x402Known
+            ? x402LedgerField({ zh: 'txHash 出现在卖方端点台账里的转入笔数', en: 'incoming transfers whose txHash appears in the seller endpoint ledger' })
+            : noneField(x402UnknownWhy),
+        payments_in_x402_total_atomic: x402Known
+            ? x402LedgerField({ zh: '其中经 x402 流程的金额合计 (原子单位)', en: 'total of the transfers attributed to the x402 flow (atomic units)' })
+            : noneField(x402UnknownWhy),
         tasks_verified: chainAuthoritative
             ? noneField({ zh: '链上索引没有「验真」事件', en: 'the chain index has no verification event' })
             : pulseField({ zh: '真验真 (trade_verified) 的任务', en: 'tasks truly verified (trade_verified)' }),
@@ -1162,10 +1758,10 @@ export function computeSnapshot(events, opts) {
         window_ms: PULSE_LIMITS.windowMs,
         label: {
             zh: chainAuthoritative
-                ? `节点/智能体 = 本节点 ${WINDOW_HOURS}h 脉冲事件; 任务/已完成/已结算 = 链上索引全量 (与下表同源); 钱包签名 = 本机签名审计`
+                ? `任务/已完成/已释放/已退款/争议中/链上转入 = 链上索引全量 (与下表同源); 「其中经 x402 流程」= 卖方端点台账交叉核; 节点/智能体 = 本节点 ${WINDOW_HOURS}h 脉冲事件 (非链上); 钱包签名 = 本机签名审计`
                 : `只统计本节点 ${WINDOW_HOURS}h 观察窗口内收到的脉冲事件 (本节点自己上报的)`,
             en: chainAuthoritative
-                ? `nodes/agents = this node's ${WINDOW_HOURS}h pulse events; tasks/completed/settled = chain index, whole (same source as the table below); wallet signatures = this node's signature audit log`
+                ? `tasks/completed/released/refunded/disputed/chain-receipts = chain index, whole (same source as the table below); "via x402 flow" = cross-checked against the seller endpoint ledger; nodes/agents = this node's ${WINDOW_HOURS}h pulse events (not on-chain); wallet signatures = this node's signature audit log`
                 : `Only pulse events received by this node within the ${WINDOW_HOURS}h observation window (reported by this node itself)`,
         },
         differs_from_activity: activity_totals.rows > 0 &&
@@ -1191,9 +1787,15 @@ export function computeSnapshot(events, opts) {
             `不是链上索引全量) —— 每个数的来源见 totals_scope.fields`);
     }
     if (chainAuthoritative) {
-        notes.push(`顶部「任务/已完成/已结算」= 链上索引的**同源计数** (= activity_totals, 与下表同源, 同源即恒等): ` +
-            `tasks=${totalsTasks} · tasks_completed=${totalsCompleted} · tasks_settled=${totalsSettled}; ` +
-            `「节点/智能体」= 本节点 ${WINDOW_HOURS}h 脉冲事件; 「已验证」在链上索引里没有对应事件 → ` +
+        const x402Note = x402Known
+            ? `「其中经 x402 流程」= ${totalsPaymentsX402} 笔 (卖方端点台账交叉核: ${seller?.endpoint || ''} · 取于 ${seller?.fetched_at ? new Date(Number(seller.fetched_at)).toISOString() : '未知时刻'})`
+            : `「其中经 x402 流程」= **未知** (不是 0): ${x402UnknownWhy.zh}`;
+        notes.push(`顶部链上计数 = 链上索引的**同源计数** (= activity_totals, 与下表同源, 同源即恒等): ` +
+            `tasks=${totalsTasks} · tasks_completed=${totalsCompleted} · tasks_settled(释放给卖方)=${totalsSettled} · ` +
+            `tasks_refunded=${totalsRefunded === null ? '未接入' : totalsRefunded} · tasks_disputed=${totalsDisputed === null ? '未接入' : totalsDisputed} · ` +
+            `链上转入=${totalsPaymentsIn === null ? '没有源 → 不下发该字段 (不是 0)' : `${totalsPaymentsIn} 笔 (合计 ${activity_totals.payments_in_total_atomic} 原子)`}; ` +
+            `${x402Note}; ` +
+            `「节点/智能体」= 本节点 ${WINDOW_HOURS}h 脉冲事件 (**非链上**, 页面计数区不列); 「已验证」在链上索引里没有对应事件 → ` +
             `该口径无对应事件源, 不下发该字段 (不是 0); 「钱包签名」= ${auditWired
                 ? `本机签名审计账 ${totalsSignatures} 条 (${WINDOW_HOURS}h 窗口, 只计数)`
                 : (totalsSignatures === null
@@ -1221,13 +1823,77 @@ export function computeSnapshot(events, opts) {
             tasks_completed: totalsCompleted,
             tasks_verified: totalsVerified, // 链上口径下 = null (未接入), 不冒充 0
             signatures: totalsSignatures, // 真源 = 本机签名审计账; 无源 = null (未接入)
-            tasks_settled: totalsSettled, // 新增字段一律排最后 (老 8 个字段顺序逐字不变)
+            tasks_settled: totalsSettled, // 只算 Released (钱真释放给卖方)
+            // ★ 2026-09-29 追加 (新增字段一律排最后; 老字段的顺序逐字不变)
+            tasks_refunded: totalsRefunded, // 争议后退款 (不是成交); 无源 = null
+            tasks_disputed: totalsDisputed, // 争议中; 无源 = null
+            payments_in: totalsPaymentsIn, // 关注地址集内转入笔数; 未配置/不可用 = null
+            payments_in_total_atomic: totalsPaymentsInAtomic, // 转入合计 (原子单位); 同上
+            payments_in_x402: totalsPaymentsX402, // 其中经 x402 流程 (卖方台账交叉核); 未知 = null
+            payments_in_x402_total_atomic: totalsPaymentsX402Atomic,
+            // 展示用折算 (非门禁字段: 门只看原子值, 避免浮点参与判定)
+            payments_in_total_usdc: paymentsKnown ? formatUnits(activity_totals.payments_in_total_atomic, transferSummary?.token_decimals ?? 6) : null,
+            payments_in_x402_total_usdc: x402Known ? formatUnits(activity_totals.payments_in_x402_total_atomic || '0', transferSummary?.token_decimals ?? 6) : null,
+            payments_in_currency: paymentsKnown ? (transferSummary?.token_symbol || null) : null,
         },
         totals_scope,
+        /** 链上转入的**分桶明细** (纯数据: 页面/机器清单都能用; 数字全部来自同一批行) */
+        transfer_totals: transferSummary
+            ? {
+                configured: transferSynced,
+                reason: transferSummary.reason,
+                token_symbol: transferSummary.token_symbol,
+                token_decimals: transferSummary.token_decimals,
+                inbound: transferSummary.inbound,
+                inbound_display: transferSummary.inbound_display,
+                inbound_total_atomic: transferSummary.inbound_atomic,
+                by_class: transferSummary.by_class,
+                by_class_atomic: transferSummary.by_class_atomic,
+                outbound: transferSummary.outbound,
+                from_block: transferSummary.from_block,
+                last_synced_block: transferSummary.last_synced_block,
+                pending_observation: transferSummary.pending_observation,
+            }
+            : null,
+        /** 卖方端点只读汇总的取数状态 (available=false ⇒ 「经 x402 流程」是**未知**, 不是 0) */
+        x402_ledger: seller
+            ? { available: seller.available === true, reason: seller.reason, endpoint: seller.endpoint, fetched_at: seller.fetched_at, count: seller.available === true ? seller.count : null }
+            : null,
+        /** 链上索引的覆盖口径 (覆盖什么 / 起止块 / 落后多少块) */
+        index_scope: buildIndexScope({
+            chainId: activity.index_info?.chainId ?? null,
+            networkName: activity.index_info?.networkName ?? null,
+            escrow: activity.index_info
+                ? {
+                    deploymentBlock: activity.index_info.deploymentBlock,
+                    lastSyncedBlock: activity.index_info.lastSyncedBlock,
+                    headBlock: activity.index_info.headBlock,
+                    rows: activity.index_info.rows,
+                    pageSize: activity.index_info.pageSize,
+                }
+                : null,
+            transfers: transferSummary,
+            liveHeadBlock: opts.liveHeadBlock ?? null,
+        }),
         capabilities,
         recent_activity: recent,
         confirmed_activity: activity.rows,
         confirmed_activity_source: activity.source,
+        /** ★ 付款方智能体的**链下登记**取数口径 (2026-09-29): 只有已验签的绑定才让行里多出 payer_identity */
+        payer_identity_scope: activity.payer_identity
+            ? {
+                loaded: activity.payer_identity.loaded,
+                verified: activity.payer_identity.verified,
+                rejected: activity.payer_identity.rejected.length,
+                rejected_reasons: activity.payer_identity.rejected,
+                rows_with_identity: activity.rows.filter((r) => !!r.payer_identity).length,
+                reason: activity.payer_identity.reason,
+                label: activity.payer_identity.label,
+                note: activity.payer_identity.note,
+                method: PAYER_IDENTITY_METHOD,
+                source: PAYER_IDENTITY_SOURCE,
+            }
+            : null,
         activity_totals,
         chain_id_scope,
         open_tasks: Array.isArray(opts.openTasks) ? opts.openTasks : [],
@@ -1251,7 +1917,11 @@ export async function getNetworkPulse(opts = {}) {
                 && !!cached?.totals_scope?.fields // 老缓存没有逐字段口径 → 过期形状, 重算
                 && !!cached?.activity_totals
                 && !!cached?.chain_id_scope
-                && Array.isArray(cached?.open_tasks); // 老缓存没有待接单任务 → 过期形状, 重算
+                && Array.isArray(cached?.open_tasks) // 老缓存没有待接单任务 → 过期形状, 重算
+                && 'index_scope' in cached // 2026-09-29: 老缓存没有覆盖口径 → 重算
+                && 'transfer_totals' in cached // 2026-09-29: 老缓存没有转入分桶 → 重算
+                && 'payer_identity_scope' in cached // 2026-09-29: 老缓存没有付款方身份口径 → 重算
+                && typeof cached?.totals?.tasks_refunded !== 'undefined';
             if (shapeOk && cached && Number.isFinite(cached.generated_at) && cached.generated_at + PULSE_LIMITS.snapshotTtlMs > now)
                 return cached;
         }
@@ -1264,13 +1934,22 @@ export async function getNetworkPulse(opts = {}) {
     catch (e) {
         return computeSnapshot([], { now, unavailable: true });
     }
-    // 活动行优先取 P5 链上索引 (真链上事实); 索引不可用 → 退回脉冲事件, 并在快照里标出来源
-    const confirmedActivity = await resolveConfirmedActivity({ home: opts.home, events, now });
+    // 活动行优先取 P5 链上索引 (真链上事实) + 关注地址集转账索引 (链上收款); 索引不可用 → 退回脉冲事件
+    const confirmedActivity = await resolveConfirmedActivity({
+        home: opts.home, events, now,
+        readIndex: opts.readIndex,
+        readTransfers: opts.readTransfers,
+        readSellerSummary: opts.readSellerSummary,
+        readPayerIdentities: opts.readPayerIdentities,
+    });
     // 钱包签名的**真源**: 本机签名审计账 (窗口内条数)。没有账 → 注入 available:false → 快照标「未接入」
     // (不拿 0 冒充「没发生过」: 本机明明签过而脉冲事件丢了的那次真事故就是这么来的)
     const signatureAudit = tallySignatureAudit(opts.home, { now, windowMs: PULSE_LIMITS.windowMs });
     // 待接单任务: 只读本机公告板目录 (未认领且未过期), 投影成白名单 7 字段 —— 与脉冲事件层无关
-    const snap = computeSnapshot(events, { now, confirmedActivity, openTasks: readOpenTasks(opts.home, now), signatureAudit });
+    const snap = computeSnapshot(events, {
+        now, confirmedActivity, openTasks: readOpenTasks(opts.home, now), signatureAudit,
+        liveHeadBlock: opts.liveHeadBlock ?? null,
+    });
     try {
         fs.mkdirSync(pulseDir(opts.home), { recursive: true });
         fs.writeFileSync(snapshotFile(opts.home), JSON.stringify(snap), 'utf8');