@bolloon/bolloon-agent 0.4.25 → 0.4.27

package/dist/agents/x402/milestone-settlement.js

@@ -0,0 +1,150 @@
+/**
+ * milestone-settlement.ts — 里程碑结算 / 争议 / 责任落地 (Phase 4, 2026-09-18)
+ *
+ * leo 的 Phase 4:
+ *   4.1 **PartiallySettled**: 分阶段服务按里程碑结算 (第一版只支持明确里程碑)
+ *       每里程碑: milestoneId / amount / paymentStatus / deliveryStatus / verificationStatus / evidence
+ *       规则: 部分成功 → partially_settled; 全部支付且全部交付验证 → verified; 任一交付失败 → disputed 或 delivery_failed
+ *       ★ `partially_settled` **不许**直接进 Goal 成功证据
+ *   4.2 **争议**: disputed / refund_pending / refunded; 争议必须绑定
+ *       原始报价 · Payment Header · facilitator response · txHash · 内容哈希 · 签名信封 · Run step · Goal evidence · 失败时点 · 责任候选
+ *       三条禁令: 不能自动重付 · 不能标 verified · **不能静默关闭**
+ *   4.3 **责任判定**: 机器只给候选 (Phase 0 的 deriveResponsibility), 候选连同证据进交易记录 + Run/Goal 证据
+ */
+import { deriveResponsibility } from './settlement-state.js';
+/** 里程碑的不变式: 金额必须是正整数原子单位字符串 (不许浮点/负数/空) */
+export function validateMilestoneSpec(m) {
+    if (!m.milestoneId)
+        return { ok: false, reason: 'milestoneId 不能为空' };
+    if (!/^\d+$/.test(String(m.amount)))
+        return { ok: false, reason: `amount 必须是正整数原子单位字符串, 实际: ${m.amount}` };
+    if (Number(m.amount) <= 0)
+        return { ok: false, reason: 'amount 必须大于 0' };
+    return { ok: true };
+}
+export function makeMilestone(m) {
+    const chk = validateMilestoneSpec(m);
+    if (!chk.ok)
+        throw new Error(chk.reason);
+    return {
+        milestoneId: m.milestoneId, title: m.title, amount: String(m.amount),
+        paymentStatus: 'unpaid', deliveryStatus: 'pending', verificationStatus: 'pending',
+        evidence: [], updatedAt: new Date().toISOString(),
+    };
+}
+/** 里程碑总金额必须等于交易金额 (否则就是账不平) */
+export function milestonesMatchAmount(ms, amount) {
+    const sum = ms.reduce((a, m) => a + BigInt(m.amount || '0'), 0n).toString();
+    if (amount && String(amount) !== sum)
+        return { ok: false, sum, reason: `里程碑金额合计 ${sum} ≠ 交易金额 ${amount}` };
+    return { ok: true, sum };
+}
+export function aggregateMilestones(ms) {
+    const list = ms || [];
+    const paid = list.filter((m) => m.paymentStatus === 'paid').length;
+    const delivered = list.filter((m) => m.deliveryStatus === 'delivered').length;
+    const verified = list.filter((m) => m.verificationStatus === 'verified').length;
+    const failed = list.filter((m) => m.deliveryStatus === 'failed' || m.verificationStatus === 'failed').length;
+    const allComplete = list.length > 0 && verified === list.length;
+    const anyProgress = paid > 0 || delivered > 0 || verified > 0;
+    const partiallyComplete = anyProgress && !allComplete && failed === 0;
+    const next = list.find((m) => m.verificationStatus !== 'verified' && m.deliveryStatus !== 'failed');
+    let settlementFact = 'unpaid';
+    if (allComplete)
+        settlementFact = 'fully_settled';
+    else if (partiallyComplete)
+        settlementFact = 'partially_settled';
+    else if (paid > 0 || delivered > 0)
+        settlementFact = 'payment_submitted';
+    const shouldDispute = failed > 0;
+    const reason = shouldDispute
+        ? `${failed} 个里程碑交付/验真失败 → 进争议 (不许静默关闭)`
+        : allComplete ? '全部里程碑支付+交付+验真完成'
+            : partiallyComplete ? `${verified}/${list.length} 个里程碑完成 → partially_settled (不算完成, 也不进 Goal 成功证据)`
+                : list.length === 0 ? '没有里程碑 (单笔交易)' : '还没有里程碑完成';
+    return { total: list.length, paid, delivered, verified, failed, allComplete, partiallyComplete, nextMilestoneId: next?.milestoneId, settlementFact, shouldDispute, reason };
+}
+/** 应用一个里程碑结果并给出应落的结算事实 (纯函数; 落盘由调用方做, 保证可测) */
+export function applyMilestoneResult(ms, milestoneId, result) {
+    const list = (ms || []).map((m) => ({ ...m, evidence: [...(m.evidence || [])] }));
+    const target = list.find((m) => m.milestoneId === milestoneId);
+    if (!target)
+        return { milestones: list, aggregate: aggregateMilestones(list), ok: false, reason: `没有这个里程碑: ${milestoneId}` };
+    if (result.paymentStatus)
+        target.paymentStatus = result.paymentStatus;
+    if (result.deliveryStatus)
+        target.deliveryStatus = result.deliveryStatus;
+    if (result.verificationStatus)
+        target.verificationStatus = result.verificationStatus;
+    if (result.evidence?.length)
+        target.evidence.push(...result.evidence);
+    target.updatedAt = new Date().toISOString();
+    return { milestones: list, aggregate: aggregateMilestones(list), ok: true };
+}
+const REQUIRED_EVIDENCE_FIELDS = [
+    'quote', 'txHash', 'contentHash', 'envelopeDigest', 'failurePoint',
+];
+/** 开争议: 记录绑定的证据 + 缺口; 生命周期进 disputed (自动化到此为止) */
+export function buildDispute(opts) {
+    const missing = REQUIRED_EVIDENCE_FIELDS.filter((f) => {
+        const v = opts.evidence[f];
+        if (v === undefined || v === null)
+            return true;
+        if (typeof v === 'string')
+            return v.trim().length === 0;
+        if (Array.isArray(v))
+            return v.length === 0;
+        if (typeof v === 'object')
+            return Object.values(v).every((x) => x === undefined || x === null || x === '');
+        return false;
+    });
+    const responsibility = opts.evidence.responsibility
+        || (opts.responsibilityEvidence ? deriveResponsibility(opts.responsibilityEvidence) : undefined);
+    return {
+        openedAt: new Date().toISOString(),
+        reason: opts.reason,
+        evidence: { ...opts.evidence, responsibility },
+        missingEvidence: missing,
+        mustNotRepay: true,
+    };
+}
+/** 争议禁令的唯一实现在 settlement-state (`disputeForbids`), 这里只做转发, 避免两份判断漂移 */
+export { disputeForbids } from './settlement-state.js';
+/** 争议收尾: 必须带决定 + 依据 + 证据 (退款走结算层 refund_pending → refunded) */
+export function resolveDispute(rec, opts) {
+    if (!rec.dispute)
+        throw new Error('这笔交易没有争议记录');
+    if (!opts.evidence?.length)
+        throw new Error('争议收尾必须带证据 (不许无凭据关闭)');
+    return {
+        ...rec.dispute,
+        resolution: { decision: opts.decision, at: new Date().toISOString(), by: opts.by, reason: opts.reason, evidence: [...opts.evidence] },
+    };
+}
+/**
+ * 里程碑/争议叠加后的 Goal 成功证据门槛:
+ *   交易 verified 或 (全部里程碑完成 + 结算 fully_settled) ∧ 无争议 ∧ 执行成功 ∧ 命中判据
+ *   —— `partially_settled` 一律不算 (leo: 不要让 partially_settled 直接进 Goal 成功证据)
+ */
+export function milestoneGoalEligibility(rec, opts = {}) {
+    if (rec.dispute && !rec.dispute.resolution)
+        return { eligible: false, reason: '交易在争议中 (未收尾) → 不计入 Goal 成功证据' };
+    const agg = aggregateMilestones(rec.milestones);
+    if (agg.total > 0) {
+        if (agg.shouldDispute)
+            return { eligible: false, reason: '里程碑有失败项 → 需争议处理, 不计入成功证据' };
+        if (!agg.allComplete)
+            return { eligible: false, reason: `里程碑未全部完成 (${agg.verified}/${agg.total}) → partially_settled 不计入成功证据` };
+    }
+    if (rec.settlementFact === 'partially_settled')
+        return { eligible: false, reason: '结算事实是 partially_settled → 不计入成功证据' };
+    if (rec.status !== 'verified')
+        return { eligible: false, reason: `交易状态是 ${rec.status}, 不是 verified` };
+    if (rec.chainSettled !== true)
+        return { eligible: false, reason: '链上没有真实结算' };
+    if (opts.executionOk !== true)
+        return { eligible: false, reason: '资源执行没成功 (买到 ≠ 用上)' };
+    if (opts.goalCriteriaHit !== true)
+        return { eligible: false, reason: '没有命中 Goal 判据' };
+    return { eligible: true, reason: '链上结算 + 全部里程碑完成 + 无争议 + 执行成功 + 命中判据' };
+}

package/dist/agents/x402/paid-info-store.js

@@ -166,12 +166,23 @@ export async function checkAndSettlePayment(opts) {
     const req = opts.requirements.accepts[0];
     const network = String(req.network);
     if (!opts.paymentHeader)
-        return { ok: false, mode: 'none', error: '缺少 X-PAYMENT 头 (未付款)' };
+        return { ok: false, mode: 'none', error: '缺少 X-PAYMENT 头 (未付款)', attempted: false };
     const payload = decodePaymentHeader(opts.paymentHeader);
     if (!payload)
-        return { ok: false, mode: 'none', error: 'X-PAYMENT 不是合法 base64 JSON' };
+        return { ok: false, mode: 'none', error: 'X-PAYMENT 不是合法 base64 JSON', attempted: false };
     const facilitatorUrl = opts.facilitatorUrl ?? process.env.BOLLOON_X402_FACILITATOR ?? '';
     const allowLocalDev = opts.allowLocalDev ?? (process.env.BOLLOON_X402_LOCAL_VERIFY === '1');
+    // ★ 凭据绑定校验必须在**分模式之前** (两种模式都查): 拿旧回执去换另一条资源 → 一律拒绝。
+    //   真跑抓到过: 这段原来只对 local-dev 生效, facilitator 模式提前 return → 跨资源复用没被拦。
+    const boundItem = payload?.accepted?.extra?.itemId || payload?.accepted?.itemId || payload?.itemId;
+    if (opts.expectedItemId) {
+        if (!boundItem) {
+            return { ok: false, mode: 'none', attempted: false, error: '支付凭据没有绑定 itemId: 无法证明这笔钱是为这条资源付的' };
+        }
+        if (String(boundItem) !== String(opts.expectedItemId)) {
+            return { ok: false, mode: 'none', attempted: false, error: `支付凭据绑定的资源 (${boundItem}) 与本次请求 (${opts.expectedItemId}) 不一致 — 回执不能跨资源复用` };
+        }
+    }
     if (facilitatorUrl) {
         const f = opts.fetchImpl ?? fetch;
         const body = { x402Version: 2, paymentPayload: payload, paymentRequirements: req };
@@ -181,26 +192,28 @@ export async function checkAndSettlePayment(opts) {
             });
             const v = await vres.json();
             if (!v?.isValid) {
-                return { ok: false, mode: 'facilitator', error: `facilitator 校验未通过: ${v?.invalidReason || v?.invalidMessage || 'unknown'}` };
+                return { ok: false, mode: 'facilitator', attempted: true, verifyRejected: true, settlementUncertain: false, error: `facilitator 校验未通过: ${v?.invalidReason || v?.invalidMessage || 'unknown'}` };
             }
             const sres = await f(`${facilitatorUrl.replace(/\/$/, '')}/settle`, {
                 method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
             });
             const s = await sres.json();
             if (!s?.success) {
-                return { ok: false, mode: 'facilitator', error: `结算失败: ${s?.errorReason || s?.errorMessage || 'unknown'}` };
+                // settle 失败: 链上可能已经动了钱 → 不确定 (不是"没付过")
+                return { ok: false, mode: 'facilitator', attempted: true, verifyRejected: false, settlementUncertain: true, error: `结算失败: ${s?.errorReason || s?.errorMessage || 'unknown'}` };
             }
             const receipt = encodePaymentResponse(s);
-            return { ok: true, mode: 'facilitator', receipt, txHash: s.transaction, payer: s.payer || v.payer, network };
+            return { ok: true, mode: 'facilitator', receipt, txHash: s.transaction, payer: s.payer || v.payer, network, attempted: true };
         }
         catch (e) {
-            return { ok: false, mode: 'facilitator', error: `facilitator 不可达: ${String(e?.message || e).slice(0, 160)}` };
+            return { ok: false, mode: 'facilitator', attempted: true, verifyRejected: false, settlementUncertain: true, error: `facilitator 不可达: ${String(e?.message || e).slice(0, 160)}` };
         }
     }
     if (!allowLocalDev) {
         return {
             ok: false,
             mode: 'none',
+            attempted: false,
             error: '未配置 facilitator (BOLLOON_X402_FACILITATOR), 也未开启本机联调模式 (BOLLOON_X402_LOCAL_VERIFY=1) — 无法校验真实付款',
         };
     }
@@ -227,9 +240,14 @@ export async function checkAndSettlePayment(opts) {
  * 购买一条信息: 未付款时服务端回 402, 这里用标准 x402 客户端 (402→签名→重试) 完成支付。
  * 无钱包私钥时, 只有显式 allowLocalDev 才走本机联调头。
  */
+function makeTracker(onEvent) {
+    return async (e) => { if (onEvent)
+        await onEvent(e).catch(() => null); };
+}
 export async function buyInfo(params) {
     const { verifyEnvelope } = await import('./paid-info-protocol.js');
     const doFetch = params.fetchImpl ?? fetch;
+    const trackEvent = makeTracker(params.onEvent);
     // ① 先探一次: 判断是否 402 (以及免费信息直接返回)
     let res;
     try {
@@ -248,11 +266,22 @@ export async function buyInfo(params) {
         }
         return { ok: false, status: res.status, error: `服务端返回 ${res.status}: ${text.slice(0, 200)}` };
     }
-    // ② 402 → 支付 → 重试
+    // ② 402 → (策略门) → 支付 → 重试
     const requirementBody = safeJson(await res.text());
     const requirements = requirementBody?.accepts?.[0];
     if (!requirements)
         return { ok: false, status: 402, error: '402 响应缺少 accepts' };
+    const metadata = requirementBody?.metadata || requirementBody?.item || null;
+    await trackEvent({ kind: 'payment_required', detail: `amount=${requirements.amount} network=${requirements.network}` });
+    // Phase 2: 策略门 —— 必须在解密钱包/签名/付款之前 (顺序不可颠倒)
+    if (params.prePayGuard) {
+        const gate = await params.prePayGuard({ requirements, url: params.url });
+        if (!gate.ok) {
+            await trackEvent({ kind: 'policy_denied', detail: gate.reason });
+            return { ok: false, status: 402, policyDenied: true, error: gate.reason || '策略拒绝', metadata, raw: JSON.stringify(requirementBody) };
+        }
+        await trackEvent({ kind: 'policy_allowed', detail: '策略通过, 允许进入付款' });
+    }
     let paymentHeader = '';
     let mode = '';
     if (params.privateKey) {
@@ -264,16 +293,32 @@ export async function buyInfo(params) {
             maxPaymentAmount: params.maxPaymentAmount,
             rpcUrl: params.rpcUrl,
         });
+        // ★ 真把付款凭据发出去了 → 结算事实 payment_submitted (这一步之后失败都不能当"没付过钱")
+        await trackEvent({ kind: 'payment_sending', detail: 'facilitator 模式: 已发出 x402 付款请求', patch: { settlementFact: 'payment_submitted' } });
         const retry = await paymentFetch(params.url, { method: 'GET' });
         const text = await retry.text();
         const parsed = safeJson(text);
         const receipt = retry.headers.get('x-payment-response') || parsed?.payment?.receipt || '';
         if (retry.status < 200 || retry.status >= 300) {
-            return { ok: false, status: retry.status, error: `付款后重试失败 ${retry.status}: ${text.slice(0, 200)}` };
+            // 付款这一步已经发出去了 (可能已上链), 只是拿资源失败 → 绝不许当"没付过钱"
+            return {
+                ok: false, status: retry.status,
+                payment: { mode: 'facilitator', receipt: receipt || undefined, attempted: true, settled: true, settlementUncertain: !receipt },
+                error: `付款后重试失败 ${retry.status}: ${text.slice(0, 200)}`,
+            };
         }
         mode = 'facilitator';
+        // ★ 链上事实需要 txHash: facilitator 说成功但没有 txHash → 不能标 chainSettled (真跑抓到过这类"假结算")
+        const txHash = parsed?.payment?.txHash || retry.headers.get('x-payment-txhash') || parsed?.txHash || '';
+        await trackEvent({
+            kind: 'settled',
+            detail: `mode=facilitator receipt=${receipt.slice(0, 24)}… txHash=${txHash ? `${String(txHash).slice(0, 16)}…` : '(缺失: 不能认定链上结算完成)'}`,
+            patch: { paymentMode: 'facilitator', paymentReceipt: receipt, chainSettled: !!txHash, ...(txHash ? { txHash: String(txHash) } : {}) },
+        });
         const report = parsed?.proof ? await verifyEnvelope(parsed, { resolveDid: params.resolveDid, expectItemId: params.expectItemId }) : undefined;
-        return { ok: true, status: retry.status, envelope: parsed, verify: report, payment: { mode, receipt }, raw: text };
+        if (report)
+            await trackEvent({ kind: 'delivered', detail: `trust=${report.trust}`, patch: { verificationTrust: report.trust, contentHash: parsed?.contentHash, protocolVerified: report.trust === 'verified' } });
+        return { ok: true, status: retry.status, envelope: parsed, verify: report, payment: { mode, receipt }, metadata, raw: text };
     }
     if (!params.allowLocalDev) {
         return { ok: false, status: 402, error: '需要钱包私钥才能支付 (未提供 privateKey; 本机联调请显式 allowLocalDev)' };
@@ -284,17 +329,26 @@ export async function buyInfo(params) {
         payload: { localDev: true, at: new Date().toISOString() },
         payer: 'local-dev',
     }), 'utf-8').toString('base64');
+    await trackEvent({ kind: 'payment_sending', detail: 'local-dev 模式: 已发出 X-PAYMENT 请求 (非链上)', patch: { settlementFact: 'payment_submitted' } });
     const retry = await doFetch(params.url, { method: 'GET', headers: { 'X-PAYMENT': paymentHeader } });
     const text = await retry.text();
     const parsed = safeJson(text);
     if (retry.status < 200 || retry.status >= 300) {
-        return { ok: false, status: retry.status, error: `本机联调付款被拒 ${retry.status}: ${text.slice(0, 200)}` };
+        return {
+            ok: false, status: retry.status,
+            payment: { mode: 'local-dev', attempted: true, settled: false, settlementUncertain: false },
+            error: `本机联调付款被拒 ${retry.status}: ${text.slice(0, 200)}`,
+        };
     }
     mode = 'local-dev';
+    const receiptLd = retry.headers.get('x-payment-response') || parsed?.payment?.receipt || '';
+    await trackEvent({ kind: 'settled', detail: 'mode=local-dev (非链上)', patch: { paymentMode: 'local-dev', paymentReceipt: receiptLd, chainSettled: false } });
     const report = parsed?.proof ? await verifyEnvelope(parsed, { resolveDid: params.resolveDid, expectItemId: params.expectItemId }) : undefined;
+    if (report)
+        await trackEvent({ kind: 'delivered', detail: `trust=${report.trust} (本机联调)`, patch: { verificationTrust: report.trust, contentHash: parsed?.contentHash, protocolVerified: report.trust !== 'unverified' } });
     return {
-        ok: true, status: retry.status, envelope: parsed, verify: report,
-        payment: { mode, receipt: retry.headers.get('x-payment-response') || parsed?.payment?.receipt }, raw: text,
+        ok: true, status: retry.status, envelope: parsed, verify: report, metadata,
+        payment: { mode, receipt: receiptLd, attempted: true }, raw: text,
     };
 }
 function safeJson(text) {

package/dist/agents/x402/payment-recovery.js

@@ -0,0 +1,290 @@
+/**
+ * payment-recovery.ts — 支付中断恢复 (Phase 3, 2026-09-18)
+ *
+ * leo 的硬规则, 决定了这一层的全部逻辑:
+ *   `payment uncertain ≠ payment failed`   —— 不确定时不许当失败处理
+ *   `payment failed ≠ safe to retry`       —— 失败也不等于可以重付
+ *   先 reconcile, 再决定 retry
+ *
+ * 五个 SIGKILL 时点 (恢复后必须各自走对路):
+ *   ① 付款前               → 状态仍是 quoted/payment_required, 可安全付款, 不重复付
+ *   ② 拿到付款权后         → 旧 claim 因进程死亡可回收, 新 worker 接管, 不会两个 worker 同时付
+ *   ③ facilitator settle 后→ 重启用**真实 txHash/结算事实**续上, 禁止重付, 继续交付与验真
+ *   ④ 支付成功、交付前     → 只执行 delivery; 正文缺失 → delivery_failed, 不重付
+ *   ⑤ 交付后、验真前       → 只执行 verification; 成功 → verified, 失败 → verification_failed, 不重付
+ *
+ * 两个附加场景:
+ *   · 支付状态未知 → 先进 unknown, 先对账, **不自动重付**
+ *   · facilitator 返回成功但**没有 txHash** → 不能认定链上结算完成 (链上事实需要 txHash)
+ */
+import { deriveSettlementFact, hasPaymentEvidence, isSettlementFact } from './settlement-state.js';
+/** 只有这些状态才允许自动重试付款 */
+const RETRYABLE_STATUSES = ['quoted', 'payment_required'];
+/**
+ * 纯函数: 从交易记录的两层状态推出"下一步该干什么"。
+ * 这是整个恢复逻辑的唯一决策点 —— Supervisor / CLI / 恢复脚本都走它, 不许各自 if-else。
+ */
+export function planTransactionRecovery(rec, opts = {}) {
+    const fact = isSettlementFact(rec.settlementFact) ? rec.settlementFact : deriveSettlementFact(rec);
+    const status = String(rec.status);
+    const evidence = hasPaymentEvidence({ ...rec, settlementFact: fact });
+    const base = { transactionId: rec.transactionId, settlementFact: fact };
+    // 终态: 不再动手 (钱的事已经定了)
+    if (['verified', 'policy_denied', 'failed'].includes(status)) {
+        return { ...base, action: status === 'verified' ? 'complete' : 'closed', mustNotRepay: evidence, needsResponsibility: false, reason: `终态 ${status}, 不再变化` };
+    }
+    if (status === 'delivery_failed' || status === 'verification_failed') {
+        return {
+            ...base, action: 'closed', mustNotRepay: true, needsResponsibility: true,
+            reason: `${status}: 钱 ${fact === 'unpaid' ? '可能没付' : '已付/待确认'} 但交付/验真失败 → 不自动重付, 进追责/人工处理`,
+        };
+    }
+    // 有别的 worker 拿着付款权 → 等 (同一个 requestId 只能有一个付款者)
+    if (opts.claimHeldByOther) {
+        return { ...base, action: 'wait', mustNotRepay: true, needsResponsibility: false, reason: '付款权被另一个进程持有 → 复用同一交易, 等它走完' };
+    }
+    // 支付状态未知 / 付款中但没有证据 → 先对账
+    if (fact === 'unknown' || (status === 'paying' && !evidence)) {
+        if (!evidence && status === 'paying') {
+            // 付款中没有**任何**支付凭据 → 判定"没真发出去", 允许安全重试 (由 reconcile 落结论)
+            return { ...base, action: 'reconcile', mustNotRepay: false, needsResponsibility: false, reason: '付款中但没有任何支付凭据 → 先对账确认(可安全重试)' };
+        }
+        return { ...base, action: 'reconcile', mustNotRepay: true, needsResponsibility: false, reason: `结算事实 ${fact} → 先对账, 绝不自动重付` };
+    }
+    // 明确没付过 + 还没走完 → 可以安全付款
+    if (!evidence && RETRYABLE_STATUSES.includes(status)) {
+        return { ...base, action: 'retry_payment', mustNotRepay: false, needsResponsibility: false, reason: `状态 ${status} 且结算事实 unpaid (确认没付过) → 可安全付款` };
+    }
+    // 有支付证据 → 继续推进交付/验真, 绝不重付
+    if (evidence) {
+        if (status === 'delivered') {
+            return { ...base, action: 'verify', mustNotRepay: true, needsResponsibility: false, reason: '已交付 → 继续验真' };
+        }
+        if (['paying', 'settled', 'payment_required'].includes(status)) {
+            return { ...base, action: 'deliver', mustNotRepay: true, needsResponsibility: false, reason: `结算事实 ${fact} → 付款事实在手, 继续交付 (不重付)` };
+        }
+    }
+    return { ...base, action: 'closed', mustNotRepay: evidence, needsResponsibility: false, reason: `状态 ${status} + 结算事实 ${fact}: 没有可自动推进的动作 → 交人` };
+}
+/**
+ * 按计划执行一步恢复。**幂等**: 任何一步重复执行都不会造成第二次付款
+ * (付款只有 plan.action === 'retry_payment' 时才可能发生)。
+ */
+export async function runTransactionRecovery(rec, deps) {
+    const plan = planTransactionRecovery(rec);
+    const steps = [];
+    let paid = false;
+    if (plan.action === 'retry_payment') {
+        const res = await deps.pay(rec);
+        paid = true;
+        if (res.ok) {
+            await deps.persist(rec.transactionId, { settlementFact: 'payment_submitted', paymentReceipt: res.receipt, ...(res.txHash ? { txHash: res.txHash } : {}) }, {
+                kind: 'recovery_paid', detail: `恢复后重新付款 (对账结论: 没付过) receipt=${String(res.receipt || '').slice(0, 20)}…`,
+            });
+            steps.push('retry_payment:已付');
+        }
+        else {
+            await deps.persist(rec.transactionId, { failureReason: res.error }, { kind: 'recovery_pay_failed', detail: String(res.error || '').slice(0, 120) });
+            steps.push('retry_payment:失败');
+        }
+        return { action: plan.action, plan, paid, steps };
+    }
+    if (plan.action === 'reconcile') {
+        const r = await deps.reconcile(rec);
+        const patch = { settlementFact: r.fact };
+        if (r.txHash) {
+            patch.txHash = r.txHash;
+            patch.chainSettled = true;
+        }
+        // 对账确认"没付过"时, 状态也要从 paying 退回 payment_required —— 否则下一步永远还是"先对账", 推不动
+        const backToRetry = r.fact === 'unpaid' && String(rec.status) === 'paying';
+        if (backToRetry)
+            patch.status = 'payment_required';
+        await deps.persist(rec.transactionId, patch, { kind: 'recovery_reconciled', detail: r.note || `对账结论: ${r.fact}${r.txHash ? ` (txHash=${r.txHash.slice(0, 12)}…)` : ''}${backToRetry ? ' → 状态退回 payment_required (可安全重试)' : ''}` });
+        steps.push(`reconcile:${r.fact}`);
+        // 对账结论若是"明确没付过" → 下一步可以安全付款; 若是链上事实 → 继续交付
+        // 本地视图必须与刚落盘的一致 (少带字段会让下一步判断回到旧状态 —— 真跑抓到过)
+        const after = { ...rec, ...patch };
+        const nextPlan = planTransactionRecovery(after);
+        if (nextPlan.action === 'deliver') {
+            const d = await deps.deliver(after);
+            steps.push(`deliver:${d.ok ? 'ok' : 'fail'}`);
+            if (!d.ok) {
+                await deps.persist(rec.transactionId, {}, { kind: 'recovery_delivery_failed', detail: String(d.reason || '').slice(0, 120) });
+            }
+            else {
+                const persisted = (deps.read ? await deps.read(rec.transactionId) : null) ?? after;
+                const v = await deps.verify(persisted);
+                steps.push(`verify:${v.ok ? 'ok' : 'fail'}`);
+            }
+        }
+        else if (nextPlan.action === 'retry_payment' && r.fact === 'unpaid') {
+            const pay = await deps.pay(after);
+            paid = true;
+            if (pay.ok)
+                await deps.persist(rec.transactionId, { settlementFact: 'payment_submitted', paymentReceipt: pay.receipt }, { kind: 'recovery_paid_after_reconcile', detail: '对账确认没付过 → 重新付款' });
+            steps.push(`retry_after_reconcile:${pay.ok ? '已付' : '失败'}`);
+        }
+        return { action: plan.action, plan, paid, steps };
+    }
+    if (plan.action === 'deliver') {
+        // ★ 先对账: 结算事实还停在 payment_submitted/unknown 时, 不许直接往下走 (要拿到 txHash 或确认无链上事实)
+        if (!['payment_verified', 'partially_settled', 'fully_settled'].includes(plan.settlementFact)) {
+            const r = await deps.reconcile(rec);
+            const patch = { settlementFact: r.fact };
+            if (r.txHash) {
+                patch.txHash = r.txHash;
+                patch.chainSettled = true;
+            }
+            await deps.persist(rec.transactionId, patch, { kind: 'recovery_reconciled', detail: `交付前对账: ${r.note || r.fact}${r.txHash ? ` (txHash=${r.txHash.slice(0, 12)}…)` : ' (无 txHash: 不能认定链上结算)'}` });
+            steps.push(`reconcile:${r.fact}`);
+            rec = { ...rec, ...patch };
+            const recheck = planTransactionRecovery(rec);
+            if (recheck.mustNotRepay)
+                plan.mustNotRepay = true;
+        }
+        const d = await deps.deliver(rec);
+        steps.push(`deliver:${d.ok ? 'ok' : 'fail'}`);
+        if (d.ok) {
+            const persisted = (deps.read ? await deps.read(rec.transactionId) : null) ?? { ...rec, status: 'delivered' };
+            const v = await deps.verify(persisted);
+            steps.push(`verify:${v.ok ? 'ok' : 'fail'}`);
+        }
+        else {
+            await deps.persist(rec.transactionId, {}, { kind: 'recovery_delivery_failed', detail: String(d.reason || '').slice(0, 120) });
+        }
+        return { action: plan.action, plan, paid, steps };
+    }
+    if (plan.action === 'verify') {
+        const v = await deps.verify(rec);
+        steps.push(`verify:${v.ok ? 'ok' : 'fail'}`);
+        return { action: plan.action, plan, paid, steps };
+    }
+    // complete / closed / wait: 什么都不做 (尤其是绝不付款)
+    steps.push(`${plan.action}:noop`);
+    return { action: plan.action, plan, paid, steps };
+}
+/** 对账结论是否可以升级为链上事实 (必须有 txHash —— facilitator 说成功不算) */
+export function reconciliationIsChainBacked(r) {
+    if (!r.txHash)
+        return false;
+    return ['payment_verified', 'partially_settled', 'fully_settled'].includes(r.fact);
+}
+/**
+ * 供 Supervisor 的 tick 调用: 扫描未完结交易, **只做对账** (安全、无副作用),
+ * 把结论钉在结算事实上, 并把"该继续做的事"交回**对应的 Goal** (挂在 `rec.goalId` 上的长期目标)。
+ *
+ * 为什么这里**不付款**: Supervisor 不持有钱包/私钥。让它替人花钱是把"恢复"变成"自己决定花第二笔钱",
+ * 违反 `payment failed ≠ safe to retry` 的边界 —— 付款必须由能对账、能签名的那一方显式执行。
+ *
+ * 2026-09-18 补: `awaitingPayment` 不再只是"列出来", 而是**唤醒对应的 Goal** (写 continuation.nextAction +
+ * 立即可跑), 由 Goal 的执行器 (持有钱包/上下文的那一方) 去走幂等付款路径; 有争议或必须人等的, 一律不唤醒。
+ */
+export async function reconcileInterruptedPayments(opts) {
+    const report = { scanned: 0, reconciled: [], awaitingPayment: [], mustNotRepay: [], closed: [], errors: [], goalsWoken: [], goalsFlagged: [] };
+    const { pendingTransactions, listTransactions } = await import('./transaction-store.js');
+    let all = [];
+    try {
+        const pending = await pendingTransactions(opts.home);
+        // 中途被杀的交易可能停在**任何非终态**: discovered(刚建) / quoted(拿到报价还没付) / delivered(该验真)…
+        // 只扫 pending 会漏掉场景 ①(付款前被杀) 与 ⑤ 之后的推进 (真跑抓到过: quoted 的交易根本没被扫到)
+        const IN_FLIGHT = ['discovered', 'quoted', 'payment_required', 'paying', 'settled', 'delivered', 'disputed'];
+        const inFlight = (await listTransactions(opts.home)).filter((t) => IN_FLIGHT.includes(String(t.status)) || t.settlementFact === 'unknown');
+        const seen = new Set();
+        all = [...pending, ...inFlight].filter((t) => { if (seen.has(t.transactionId))
+            return false; seen.add(t.transactionId); return true; });
+    }
+    catch (err) {
+        report.errors.push(`读取未完结交易失败: ${String(err?.message || err).slice(0, 120)}`);
+        return report;
+    }
+    const wakeGoal = opts.wakeGoal || (async (goalId, nextAction, why) => {
+        const { setContinuation } = await import('../goal-store.js');
+        await setContinuation(goalId, { nextAction, wakeReason: 'active', autoContinue: true, wakeAt: undefined, needsExternal: undefined });
+        return why;
+    });
+    const humanNeeded = opts.needsHuman || (async (goalId, why) => {
+        const { setContinuation } = await import('../goal-store.js');
+        await setContinuation(goalId, { nextAction: undefined, wakeReason: 'needs_human', autoContinue: false, needsExternal: why });
+        return why;
+    });
+    /** 有 Goal 且允许自动继续 → 唤醒它; 否则 (无 Goal / 已终态) 只报告 */
+    const wakeOrFlag = async (before, after, plan) => {
+        const goalId = before.goalId || after.goalId;
+        if (!goalId)
+            return;
+        if (after.dispute && !after.dispute.resolution) {
+            report.goalsFlagged.push({ goalId, why: `交易 ${before.transactionId} 在争议中 → 交人` });
+            try {
+                await humanNeeded(goalId, `交易争议待处理: ${before.transactionId}`);
+            }
+            catch (e) {
+                report.errors.push(`唤醒 Goal 失败: ${String(e?.message || e).slice(0, 100)}`);
+            }
+            return;
+        }
+        const nextAction = plan.action === 'retry_payment'
+            ? `x402_payment_retry:${before.transactionId} (对账确认可安全付款, 走同一 requestId 的幂等路径)`
+            : `x402_continue:${before.transactionId} (${plan.action}: ${plan.reason})`;
+        try {
+            await wakeGoal(goalId, nextAction, plan.reason);
+            report.goalsWoken.push({ goalId, transactionId: before.transactionId, action: plan.action, nextAction });
+        }
+        catch (e) {
+            report.errors.push(`唤醒 Goal ${goalId} 失败: ${String(e?.message || e).slice(0, 100)}`);
+        }
+    };
+    for (const rec of all.slice(0, opts.limit ?? 50)) {
+        report.scanned++;
+        const plan = planTransactionRecovery(rec);
+        try {
+            if (plan.action === 'reconcile') {
+                const r = await opts.reconcile(rec);
+                const patch = { settlementFact: r.fact };
+                if (r.txHash) {
+                    patch.txHash = r.txHash;
+                    patch.chainSettled = true;
+                }
+                const backToRetry = r.fact === 'unpaid' && String(rec.status) === 'paying';
+                if (backToRetry)
+                    patch.status = 'payment_required';
+                await opts.persist(rec.transactionId, patch, {
+                    kind: 'supervisor_payment_reconciled',
+                    detail: `${r.note || r.fact}${r.txHash ? ` (txHash=${r.txHash.slice(0, 12)}…)` : ''}${backToRetry ? ' → payment_required (可安全重试)' : ''}`,
+                });
+                report.reconciled.push(rec.transactionId);
+                const after = { ...rec, ...patch };
+                const nextPlan = planTransactionRecovery(after);
+                if (nextPlan.action === 'retry_payment') {
+                    report.awaitingPayment.push({ transactionId: rec.transactionId, reason: nextPlan.reason });
+                    await wakeOrFlag(rec, after, nextPlan);
+                }
+                else if (nextPlan.mustNotRepay)
+                    report.mustNotRepay.push(rec.transactionId);
+                continue;
+            }
+            if (plan.action === 'retry_payment') {
+                // 不需要对账就能确认"没付过" → 列出来 + 唤醒对应 Goal 去走幂等付款路径 (这里不动钱)
+                report.awaitingPayment.push({ transactionId: rec.transactionId, reason: plan.reason });
+                await wakeOrFlag(rec, rec, plan);
+                continue;
+            }
+            if (plan.action === 'deliver' || plan.action === 'verify') {
+                // 付款事实在手 → 唤醒 Goal 继续推进交付/验真 (同样不在这里动钱)
+                await wakeOrFlag(rec, rec, plan);
+                continue;
+            }
+            if (plan.mustNotRepay)
+                report.mustNotRepay.push(rec.transactionId);
+            if (plan.action === 'closed' || plan.action === 'complete' || plan.action === 'wait') {
+                report.closed.push({ transactionId: rec.transactionId, reason: plan.reason });
+                // 争议中的交易也要让对应 Goal **转人工** (不是让它继续跑, 而是明确交人)
+                await wakeOrFlag(rec, rec, plan);
+            }
+        }
+        catch (err) {
+            report.errors.push(`${rec.transactionId}: ${String(err?.reason || err?.message || err).slice(0, 120)}`);
+        }
+    }
+    return report;
+}