@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/layer0-foundation/L0-2-state-machine/engine.js

@@ -478,6 +478,7 @@ function getActiveDeadline(order, db) {
     // 修：picked_up 状态视为"已揽收，等运输/投递"，下一个 deadline 是 delivery_deadline
     // QA 轮 7 P1（另一条）：disputed 状态下没读 dispute_cases 的 arbitrate_deadline → agent 不知道仲裁还有多久
     const deadlineMapMarket = {
+        pending_accept: 'pending_accept_deadline', // 手动接单(v16):等卖家确认,超时无责取消
         created: 'pay_deadline',
         paid: 'accept_deadline',
         accepted: 'ship_deadline',

package/dist/layer0-foundation/L0-2-state-machine/genuine-sale.js

@@ -6,16 +6,26 @@
  * 这些**退款 / 违约 / 争议**处置终态。所以裸 `status='completed'` ≠ 有效成交 —— 被退款的失败交易也是
  * completed。任何「有效成交」语义的资格门 / 信任信号都不能裸用 status。
  *
- * 真实成交 = 该订单曾进入过 `confirmed`(买家确认收货,或送达 72h 自动确认)。仅 happy path 经过 confirmed;
- * 所有 fault/退款/争议终态都不经过。据 `order_state_history`(transition() 每次状态变更写入)判定。
+ * 真实成交 = 该订单曾进入过 `confirmed`(买家确认收货,或送达 72h 自动确认)**且未被全额退货**。仅 happy path
+ * 经过 confirmed;所有 fault/退款/争议终态都不经过。据 `order_state_history`(transition() 每次状态变更写入)判定。
+ *
+ * RFC-018 PR4:退货发生在 `confirmed→completed` **之后**(returns 只作用于 completed 单),所以仅靠 confirmed
+ * 判据会把【已全额退货】的单仍算成真实成交 —— 退货虚增资格门 / completion_count / sales_count。故再排除
+ * 【累计退款达到订单总额】的单:`SUM(return_requests.refund_amount WHERE status='refunded') >= 订单总额`。
+ * 用累计 SUM 而非单行 `refund_amount >= total` —— 同一单可先后多次退货(已退款的旧 return 不挡新 return),
+ * 多次部分退款累计到全额也应排除。累计 < total 仍算真实成交(确曾成交,只是部分退款)。
  *
  * 用法:把查询里的 `status='completed'` 条件替换为本谓词。
  *   单表:`... WHERE buyer_id = ? AND ${genuineSalePredicate()}`           // 默认别名 orders
  *   相关子查询:`... FROM orders o WHERE ... AND ${genuineSalePredicate('o')}`
  *
- * 注:这是纯 SQL 片段(无 DB 依赖),保证所有消费方用同一定义。若将来规模下相关子查询成性能瓶颈,
- * 再升级为 settleOrder 写入的 `orders.settled_ok_at` 列(届时只改本文件的实现)。
+ * Direct Pay (Rail 1) 排除:`payment_rail='direct_p2p'` 是场外直付,付款不可观测、本档无资金保障,
+ * 不计真实成交/佣金/PV(设计稿 §3「Commission/PV/genuine-sale on Rail 1」)。escrow 及将来可观测的
+ * Rail 2(链上全额质押)仍计入。NULL → 视为 escrow(老行)。
+ *
+ * 注:这是纯 SQL 片段(无 DB 依赖),保证所有消费方用同一定义。整体加括号防 OR 上下文优先级。
+ * 若将来规模下相关子查询成性能瓶颈,再升级为 settleOrder 写入的 `orders.settled_ok_at` 列(届时只改本文件)。
  */
 export function genuineSalePredicate(ordersAlias = 'orders') {
-    return `EXISTS (SELECT 1 FROM order_state_history osh WHERE osh.order_id = ${ordersAlias}.id AND osh.to_status = 'confirmed')`;
+    return `(EXISTS (SELECT 1 FROM order_state_history osh WHERE osh.order_id = ${ordersAlias}.id AND osh.to_status = 'confirmed') AND (SELECT COALESCE(SUM(rr.refund_amount), 0) FROM return_requests rr WHERE rr.order_id = ${ordersAlias}.id AND rr.status = 'refunded') < ${ordersAlias}.total_amount AND COALESCE(${ordersAlias}.payment_rail, 'escrow') != 'direct_p2p')`;
 }

package/dist/layer0-foundation/L0-2-state-machine/transitions.js

@@ -20,6 +20,112 @@ export const VALID_TRANSITIONS = {
         requiresEvidence: false,
         description: '下单后付款前取消订单'
     },
+    // ── Direct Pay (Rail 1) 直付:只"支付"这一步变,之后汇入既有流程 ──────────────
+    //   设计稿 docs/modules/DIRECT-PAYMENT-MODULE-DESIGN.INTERNAL.md §4。
+    //   本金(货款)不经协议;协议不验证付款;买家声明已付款 → 汇入 accepted(卖家发货)。
+    'created→direct_pay_window': {
+        allowedRoles: ['system'], // 直付下单路由锁定卖家费用质押后,以 system 显式推进(非超时驱动)
+        requiresEvidence: false,
+        description: 'Rail1 直付:卖家已质押平台费、展示收款方式,进入付款窗口'
+    },
+    // ── 手动接单模式(accept_mode='manual',v16):付款前先等卖家确认接单 ──────────
+    //   直付轨:created→pending_accept(替代 created→direct_pay_window),卖家接单才进付款窗口 ——
+    //   非托管无 hold 可言,时序门(接单前不出示收款信息)是唯一正确的付款风控。
+    //   escrow 轨不用本状态:escrow 本身就是条件中间态(付款进托管,接单才继续,超时自动全额退回)。
+    'created→pending_accept': {
+        allowedRoles: ['system'], // 建单路由按 accept_mode 快照以 system 推进(与 created→direct_pay_window 同模式)
+        requiresEvidence: false,
+        description: '手动接单:订单等待卖家确认接单(付款前,不展示收款信息)'
+    },
+    'pending_accept→direct_pay_window': {
+        allowedRoles: ['seller', 'system'],
+        requiresEvidence: false,
+        description: '卖家确认接单 → 进入直付付款窗口(此刻起买家方可见收款信息)'
+    },
+    'pending_accept→cancelled': {
+        // deadlineField 供专属 cron(direct-pay-timeouts.ts)读取;故意不设 autoFaultState →
+        // 通用 engine.checkTimeouts 绝不触发本转移(会漏库存回补等副作用)。超时=无责取消(没人付过钱)。
+        allowedRoles: ['seller', 'buyer', 'system'],
+        deadlineField: 'pending_accept_deadline',
+        requiresEvidence: false,
+        description: '接单前取消:卖家谢绝 / 买家撤单 / 超时未接单(system) → 无责取消 + 回补库存'
+    },
+    'direct_pay_window→accepted': {
+        allowedRoles: ['buyer'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:买家声明"我已付款" → 汇入既有流程(卖家发货);协议不验证付款,谎报则卖家不发货(零损失自纠正)'
+    },
+    'direct_pay_window→cancelled': {
+        allowedRoles: ['buyer', 'system'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:付款前买家取消(或卖家请求取消经买家确认)→ 释放费用质押'
+    },
+    'direct_pay_window→direct_expired_unconfirmed': {
+        // deadlineField 供【专属 cron(direct-pay-timeouts.ts)】读取;故意【不设 autoFaultState】→
+        // 通用 engine.checkTimeouts(需 deadlineField+autoFaultState 两者)绝不触发本转移,避免漏掉释放质押等副作用。
+        allowedRoles: ['system'],
+        deadlineField: 'direct_pay_window_deadline',
+        requiresEvidence: false,
+        description: 'Rail1 直付:付款窗口超时未标记 → 不静默关单,转可争议态(专属 cron 释放费用质押 + 停用收款指令)'
+    },
+    'direct_expired_unconfirmed→disputed': {
+        allowedRoles: ['buyer'],
+        requiresEvidence: true,
+        evidenceHint: '上传付款凭证(证据分级:链上 tx / 银行回执 / 截图)',
+        description: 'Rail1 直付:买家"我确实付了" → 升级争议(证据级信誉裁决,本档无资金赔付)'
+    },
+    'direct_expired_unconfirmed→cancelled': {
+        allowedRoles: ['buyer', 'system'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:买家确认未付 / 宽限期后系统关单(终态)'
+    },
+    // ── Direct Pay (Rail 1) 取消退款握手(审计项 C):买家已付款、卖家未发货 → 三步握手无责关单 ──────────
+    //   request(买家)→ mark_refunded(卖家声明已场外退款)→ confirm(买家确认收到,Passkey)→ 本边(system 执行)。
+    //   仅 system:买家不能单方取消已付款订单,必须经握手(域模块 src/direct-pay-cancel-refund.ts 收口,非托管零资金)。
+    'accepted→cancelled': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:取消退款握手完成(卖家已场外退款+买家确认收到)→ 系统无责关单,恢复库存'
+    },
+    // ── Direct Pay (Rail 1) 货款协商(争议≠仲裁):卖家报未收款 → 双方先协商,谈不拢才升举证仲裁 ──────────
+    'accepted→payment_query': {
+        allowedRoles: ['seller'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:卖家报告未收到货款 → 进入协商(非仲裁),暂停履约。买家可取消/主张已付,卖家可确认已收/(宽限后)取消'
+    },
+    'payment_query→accepted': {
+        allowedRoles: ['seller'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:卖家确认已收到货款 → 恢复原订单继续履约'
+    },
+    'payment_query→cancelled': {
+        // buyer=主动取消(承认未付);seller=买家静默宽限后请求取消;system=cron 在 7 天买家申诉窗口后终结。时序/窗口由路由+cron 守。
+        allowedRoles: ['buyer', 'seller', 'system'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:协商关单(买家承认未付 / 卖家宽限后取消 / 系统申诉窗口后终结)'
+    },
+    'payment_query→disputed': {
+        allowedRoles: ['buyer', 'seller'],
+        requiresEvidence: true,
+        evidenceHint: '上传付款/未收款凭证(链上 tx / 银行回执 / 截图)',
+        description: 'Rail1 直付:协商未果(买家主张已付 + 卖家否认)→ 升级举证仲裁(证据制信誉裁决,不涉资金)'
+    },
+    'disputed→payment_query': {
+        // 裁定前回到协商的两条路径:①买卖任一方【撤回仲裁申请】(pq_withdraw);②仲裁员【驳回仲裁,退回协商】——
+        //   协议(sys_protocol)在仲裁员现场 Passkey 授权后代执行,故加 'system'。均仅裁定前有效(裁定后 disputed 已终结),时序/授权由路由守。
+        allowedRoles: ['buyer', 'seller', 'system'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:回到协商(裁定前)—— 买卖双方撤回仲裁,或仲裁员驳回仲裁退回协商(system 代执行)'
+    },
+    'disputed→confirmed': {
+        // 争议协商收口(买家侧):买家撤诉并确认收货 —— 包裹晚到/放代收点后来找到等场景,不必只剩仲裁一条收口。
+        //   限定【delivered 来源的履约争议 + 争议发起人本人 + 裁定前】,来源/发起人/时序由路由权威门守
+        //   (orders-action dispute_withdraw_confirm,与 disputed→payment_query 的 pq_withdraw 同模式);
+        //   同一事务内争议 dismissed + confirmed→completed + settleOrder(与既有 confirm 结算完全同链)。
+        allowedRoles: ['buyer'],
+        requiresEvidence: false,
+        description: '买家撤诉并确认收货(裁定前,限履约争议):争议无责关闭,订单正常完成结算'
+    },
     // ── 卖家接单 ──────────────────────────────────────────────
     'paid→accepted': {
         allowedRoles: ['seller'],
@@ -243,6 +349,10 @@ export const CURRENT_RESPONSIBLE = {
     in_transit: 'logistics', // 等物流投递
     delivered: 'buyer', // 等买家确认
     disputed: 'arbitrator', // 等仲裁处理
+    direct_pay_window: 'buyer', // Rail1: 等买家付款并标记
+    direct_expired_unconfirmed: 'buyer', // Rail1: 等买家确认未付 或 升级争议
+    payment_query: 'buyer', // Rail1: 卖家报未收款,等买家协商响应(取消/主张已付)
+    pending_accept: 'seller', // 手动接单:等卖家确认接单(超时无责取消)
 };
 /** Phase 1 self-fulfill 覆盖表：seller 一人承担 shipped/picked_up/in_transit 全程 */
 export const CURRENT_RESPONSIBLE_SELF_FULFILL = {
@@ -275,6 +385,10 @@ export const ORDER_STATE_MEANINGS = {
     refunded_full: { zh: '仲裁裁全额退款,订单作废(终态)', en: 'arbitration full refund, order voided (terminal)' },
     dispute_dismissed: { zh: '争议被驳回(无效,终态)', en: 'dispute dismissed (terminal)' },
     expired: { zh: '订单超时自动失败(通用兜底,终态)', en: 'order expired (generic timeout, terminal)' },
+    direct_pay_window: { zh: 'Rail1 直付:已质押平台费,等买家付款(协议不持货款)', en: 'Rail1 direct-pay: fee-staked, awaiting buyer off-protocol payment (protocol holds no funds)' },
+    direct_expired_unconfirmed: { zh: 'Rail1 直付:付款窗口超时未标记(不静默关单,留争议/确认窗口)', en: 'Rail1 direct-pay: payment window expired unmarked (not silently closed; dispute/confirm window open)' },
+    payment_query: { zh: 'Rail1 直付:卖家报未收货款,双方协商中(非仲裁;暂停履约)', en: 'Rail1 direct-pay: seller reported non-receipt, buyer↔seller negotiating (not arbitration; fulfillment paused)' },
+    pending_accept: { zh: '手动接单:等待卖家确认接单(付款前;直付轨此阶段不展示收款信息,超时无责取消)', en: 'manual accept: awaiting seller acceptance (pre-payment; direct-pay hides payment info at this stage; times out to no-fault cancel)' },
 };
 /** 订单/争议生命周期契约 —— 集成方 agent 读它即懂"订单怎么流转 + 每步谁驱动 + 何时 + 含义"。 */
 export function orderLifecycleContract() {

package/dist/layer0-foundation/L0-5-manifest/manifest.js

@@ -303,7 +303,7 @@ async function getLiveStats() {
         const disputes = await n('SELECT COUNT(*) as n FROM disputes');
         const skills = await n("SELECT COUNT(*) as n FROM skills WHERE active = 1");
         const totalVolume = ((await dbOne("SELECT COALESCE(SUM(total_amount),0) as v FROM orders WHERE status = 'completed'"))?.v ?? 0);
-        return { users, active_products: products, total_orders: orders, completed_orders: completed, total_disputes: disputes, active_skills: skills, total_volume_dcp: totalVolume };
+        return { users, active_products: products, total_orders: orders, completed_orders: completed, total_disputes: disputes, active_skills: skills, total_volume_waz: totalVolume };
     }
     catch {
         return null;

package/dist/layer1-agent/L1-1-mcp-server/cli.js

@@ -0,0 +1,64 @@
+/**
+ * MCP 命令行标志(--version / --help / --mode / --doctor)。
+ *
+ * 目的:让人 / 陌生 agent 在【不启动 stdio server】的前提下验证安装、看清运行模式与真网络可达性。
+ * 无标志 → cliQuickResponse 返回 null,mcp.ts 照常启动 server(既有 MCP 客户端从不传 argv → 零破坏)。
+ * 模式判定复用 resolveMode(network-mode.ts)—— 与 server.ts 同一真相源,--mode/--doctor 报的就是 server 实际用的。
+ */
+import { SOFTWARE_VERSION } from '../../version.js';
+import { resolveMode } from './network-mode.js';
+const HELP = `webaz — WebAZ MCP server (@seasonkoh/webaz)
+
+Usage:
+  npx @seasonkoh/webaz            start the MCP stdio server (what MCP clients invoke)
+  npx @seasonkoh/webaz --version  print version and exit
+  npx @seasonkoh/webaz --mode     print the resolved run mode and exit
+  npx @seasonkoh/webaz --doctor   print mode + config + live-network reachability, then exit
+  npx @seasonkoh/webaz --help     show this help
+
+Modes (RFC-003):
+  network            WEBAZ_API_KEY set — can transact on the live webaz.xyz network
+  network_readonly   no key (DEFAULT) — public reads hit live webaz.xyz; transactions need a key
+  sandbox            explicit WEBAZ_MODE=sandbox — local SQLite, isolated from the live network
+
+Env:
+  WEBAZ_API_KEY   your api_key (get one at https://webaz.xyz/#welcome). Set → network mode.
+  WEBAZ_MODE      force a mode: network | network_readonly | sandbox (sandbox is opt-in only)
+  WEBAZ_API_URL   network endpoint (default https://webaz.xyz)`;
+/** 同步、纯:处理 --version/-v · --help/-h · --mode。命中 → 返回要打印的字符串;无这些标志 → null(mcp.ts 照常启动 server)。 */
+export function cliQuickResponse(argv, env) {
+    const has = (...names) => names.some(n => argv.includes(n));
+    if (has('--version', '-v'))
+        return SOFTWARE_VERSION;
+    if (has('--help', '-h'))
+        return HELP;
+    if (has('--mode'))
+        return resolveMode(env);
+    return null;
+}
+/** --doctor:模式 + 配置 + 真网络可达性。fetch 可注入便于测试;5s 超时保护,绝不 hang。sandbox 不探网络。 */
+export async function runDoctor(env, fetchImpl = fetch) {
+    const mode = resolveMode(env);
+    const url = (env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
+    const hasKey = !!(env.WEBAZ_API_KEY ?? '');
+    const lines = [
+        `webaz doctor — @seasonkoh/webaz v${SOFTWARE_VERSION}`,
+        `  mode:          ${mode}`,
+        `  api_key:       ${hasKey ? 'set (network transactions enabled)' : 'not set (network read-only; set WEBAZ_API_KEY to transact)'}`,
+        `  api_url:       ${url}`,
+    ];
+    if (mode === 'sandbox') {
+        lines.push('  reachability:  skipped (sandbox = local SQLite, isolated from the live network)');
+        return lines.join('\n');
+    }
+    let reach;
+    try {
+        const r = await fetchImpl(`${url}/api/protocol-status`, { signal: AbortSignal.timeout(5000) });
+        reach = r.ok ? `ok (${url} reachable, HTTP ${r.status})` : `degraded (HTTP ${r.status})`;
+    }
+    catch (e) {
+        reach = `unreachable (${e.message})`;
+    }
+    lines.push(`  reachability:  ${reach}`);
+    return lines.join('\n');
+}

package/dist/layer1-agent/L1-1-mcp-server/network-mode.js

@@ -7,6 +7,17 @@
  * the predicate so the gate decision is unit-testable without booting the stdio
  * server. (Extracted from server.ts; behavior unchanged except adding webaz_pair.)
  */
+/**
+ * 解析运行模式(纯函数,单一真相源 —— server.ts 的 MODE + CLI 的 --mode/--doctor 都用它,杜绝漂移)。
+ * 显式 WEBAZ_MODE(network|network_readonly|sandbox)优先;否则有 api_key → network,无 key → network_readonly。
+ * sandbox 只能显式设置(无 key 【不】回落 sandbox)。key 的真伪判定与 server.ts 一致(WEBAZ_API_KEY ?? '' 的真值性)。
+ */
+export function resolveMode(env) {
+    const m = (env.WEBAZ_MODE ?? '').toLowerCase();
+    if (m === 'network' || m === 'sandbox' || m === 'network_readonly')
+        return m;
+    return (env.WEBAZ_API_KEY ?? '') ? 'network' : 'network_readonly';
+}
 // Tools that talk to the live webaz.xyz network (Bearer api_key where needed).
 // Un-listed tools run sandbox (local). `_mode` annotation = network for these.
 export const NETWORK_TOOLS = new Set([

package/dist/layer1-agent/L1-1-mcp-server/server.js

@@ -13,8 +13,8 @@
  *   webaz_wallet        查看钱包余额
  *   …（39 工具,完整定义见下方 TOOLS 数组;数量以 TOOLS.length 为准）
  *
- * 双模(RFC-003):NETWORK(WEBAZ_API_KEY → 调 webaz.xyz)/ SANDBOX(本机库);见 NETWORK_TOOLS / apiCall / toolBackend。
- * 关联 / Related: AGENTS.md · RFC-003(双模) · RFC-004(webaz_feedback) · 元规则 #4 不撒谎(_mode 戳) /
+ * 三态(RFC-003):NETWORK(WEBAZ_API_KEY → 调 webaz.xyz)/ NETWORK 只读(无 key,公共读走 webaz.xyz)/ SANDBOX(仅 WEBAZ_MODE=sandbox,本机库);见 NETWORK_TOOLS / apiCall / toolBackend。
+ * 关联 / Related: AGENTS.md · RFC-003(三态:network / network_readonly / sandbox) · RFC-004(webaz_feedback) · 元规则 #4 不撒谎(_mode 戳) /
  *   #6 不滥用(agent 责任制 + Iron-Rule 真人动作)· 生产端点在 src/pwa(NETWORK 共用)
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -25,13 +25,14 @@ import { initDatabase, generateId } from '../../layer0-foundation/L0-1-database/
 import { setSeamDb } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam(本进程注入)
 import { applyWebazRuntimeSchema } from '../../runtime/apply-webaz-runtime-schema.js'; // 与 PWA 同源的纯 schema 桥(防 MCP fresh DB 漂移)
 import { generateCodeVerifier, pkceChallengeS256 } from '../../runtime/agent-pairing.js'; // RFC-020 PR-C1 — PKCE 配对
-import { NETWORK_TOOLS, NETWORK_SELF_AWARE, toolAllowedInNetworkMode } from './network-mode.js'; // RFC-003 网络门(可单测)
+import { NETWORK_TOOLS, NETWORK_SELF_AWARE, toolAllowedInNetworkMode, resolveMode } from './network-mode.js'; // RFC-003 网络门(可单测)+ 模式解析(单一真相源)
 import { homedir } from 'node:os';
 import { join as pathJoin } from 'node:path';
 import { existsSync as fsExists, mkdirSync, writeFileSync, readFileSync, unlinkSync, chmodSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { transition, getOrderStatus, initSystemUser, } from '../../layer0-foundation/L0-2-state-machine/engine.js';
-import { initDisputeSchema, createDispute, respondToDispute, getDisputeDetails, getOrderDispute, getOpenDisputes, } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js';
+import { initDisputeSchema, createDispute, respondToDispute, getDisputeDetails, getOrderDispute, getOpenDisputes, isActiveWhitelistArbitrator, // 仲裁能力唯一源=active 白名单;legacy user.role==='arbitrator' 旁路已移除
+ } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js';
 import { initNotificationSchema, notifyTransition, getNotifications, getUnreadCount, markRead, } from '../../layer2-business/L2-6-notifications/notification-engine.js';
 import { initSkillSchema, publishSkill, listSkills, getMySkills, subscribeSkill, unsubscribeSkill, getMySubscriptions, formatSkillForAgent, shouldAutoAccept, SKILL_TYPE_META, } from '../../layer4-economics/L4-4-skill-market/skill-engine.js';
 import { initReputationSchema, recordOrderReputation, getReputation, getSearchBoost, getStakeDiscount, } from '../../layer4-economics/L4-3-reputation/reputation-engine.js';
@@ -45,7 +46,7 @@ const TELEMETRY_URL = process.env.WEBAZ_TELEMETRY_URL ?? 'https://webaz.xyz/api/
 // 2026-06-01: phase A pre-launch 默认 OFF(opt-in)— W8 public launch 时翻回 default ON + 加 README 披露段
 // Phase A pre-launch: telemetry default OFF (opt-in). Flip to default ON at W8 launch + add README disclosure section.
 const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'off').toLowerCase() === 'on';
-// ─── RFC-003 P0: 双模(NETWORK / SANDBOX)骨架 ─────────────────────
+// ─── RFC-003 P0: 三态(network_readonly / network / sandbox)骨架 ─────────────────────
 // NETWORK = 带 api_key 调 webaz.xyz/api(加入共享生产网络);SANDBOX = 本地 SQLite(离线试玩,与全网隔离)。
 // P0 不迁移任何工具(NETWORK_TOOLS 为空)→ 一切仍走本地 = 零行为变化;P1/P2 逐个把工具名加入集合切到网络。
 const WEBAZ_API_URL = (process.env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
@@ -59,15 +60,12 @@ export function resolveMcpApiKey(args, envKey = WEBAZ_API_KEY) {
     const explicit = typeof args?.api_key === 'string' ? args.api_key.trim() : '';
     return explicit || envKey;
 }
-const WEBAZ_MODE_ENV = (process.env.WEBAZ_MODE ?? '').toLowerCase();
 // 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 key → network_readonly(装完即见真网络)。
 // network_readonly(L1 onboarding,2026-06-08):无 key 默认。公共读匿名打 webaz.xyz(真 catalog/协议),
 //   需身份的写/读返回"设 WEBAZ_API_KEY(到 #welcome 申请邀请)"。离线本地 playground 改为【显式】 WEBAZ_MODE=sandbox。
 //   —— 治"装完=空沙盒劝退"的死首体验;route/guard 与 network 同路(见 isNetworkMode),只是无 Bearer + 文案不同。
-const MODE = WEBAZ_MODE_ENV === 'network' ? 'network'
-    : WEBAZ_MODE_ENV === 'sandbox' ? 'sandbox'
-        : WEBAZ_MODE_ENV === 'network_readonly' ? 'network_readonly'
-            : (WEBAZ_API_KEY ? 'network' : 'network_readonly');
+// 单一真相源:resolveMode(见 network-mode.ts),CLI 的 --mode/--doctor 用同一函数,杜绝漂移。
+const MODE = resolveMode(process.env);
 // network 或 network_readonly 都"走真网络"(后者无 Bearer)。sandbox 才是本地。
 const isNetworkMode = () => MODE === 'network' || MODE === 'network_readonly';
 const recentCalls = [];
@@ -328,7 +326,51 @@ export async function handlePair(args) {
             note: 'Grant verified LIVE by the server (per-call: active/expiry/revoked/subject-suspension/scope + audited). `grant` is authoritative; `local_cache` is advisory. Safe scopes only; no business tool or risk scope consumes this grant.',
         };
     }
-    return { error: `unknown action "${action}" — use "start" | "complete" | "verify"`, error_code: 'BAD_ACTION' };
+    if (action === 'request') {
+        // The agent asks the human to EXPAND this grant with more SAFE scope / a permission bundle. Uses the
+        // stored grant bearer; the server binds the request to (human, grant). Approval is Passkey-gated on the
+        // human's side. Only SAFE scopes — risk/never-delegable are structurally rejected.
+        const cred = resolveGrantCredential();
+        if (!cred)
+            return { status: 'not_paired', error_code: 'NO_GRANT_CREDENTIAL', hint: 'No stored grant. Pair first: webaz_pair action="start" → human approves → action="complete".' };
+        const bundle = typeof args.bundle === 'string' ? args.bundle : undefined;
+        const scopes = Array.isArray(args.scopes) ? args.scopes.map(String).filter(Boolean) : undefined;
+        if (!bundle && (!scopes || !scopes.length))
+            return { error: 'provide a bundle (e.g. "catalog_agent") OR a scopes[] array of SAFE scopes', error_code: 'NO_SCOPES' };
+        const resp = await apiCall('/api/agent-grants/permission-requests', {
+            method: 'POST', apiKey: cred.token,
+            body: { bundle, scopes, reason: typeof args.reason === 'string' ? args.reason : undefined, duration: typeof args.duration === 'string' ? args.duration : undefined },
+        });
+        if (resp.error)
+            return resp;
+        return {
+            status: 'requested',
+            approval_id: resp.approval_id,
+            approval_url: `${WEBAZ_API_URL}${String(resp.approval_url || '')}`,
+            requested_scopes: resp.requested_scopes,
+            permission_bundle: resp.permission_bundle,
+            risk_level: resp.risk_level,
+            suggested_duration: resp.suggested_duration,
+            next: 'Ask the human to open approval_url (logged in at webaz.xyz) and approve with their Passkey. Then simply RETRY your original call — on approval your grant carries the new scope. Use action="requests" to poll status.',
+            note: 'Only SAFE (read/draft) scopes can be requested; risk actions are never delegated to a persistent grant.',
+        };
+    }
+    if (action === 'requests') {
+        // Poll THIS grant's own permission requests + their status (pending/approved/rejected) without hitting the
+        // target surface. Grant-authed, grant-scoped (you see only your own requests). Server audits every call.
+        const cred = resolveGrantCredential();
+        if (!cred)
+            return { status: 'not_paired', error_code: 'NO_GRANT_CREDENTIAL', hint: 'No stored grant. Pair first: webaz_pair action="start" → human approves → action="complete".' };
+        const resp = await apiCall('/api/agent-grants/my-permission-requests', { method: 'GET', apiKey: cred.token });
+        if (resp.error)
+            return resp;
+        return {
+            status: 'ok',
+            requests: resp.requests,
+            note: 'Your grant\'s own permission requests + status. On "approved", just retry your original call — the grant now carries the scope. "pending" → the human has not approved yet.',
+        };
+    }
+    return { error: `unknown action "${action}" — use "start" | "complete" | "verify" | "request" | "requests"`, error_code: 'BAD_ACTION' };
 }
 // 启动 banner(stderr)+ status 声明用 —— 让用户/agent 一眼知道现在是真网络还是沙盒
 function modeBanner() {
@@ -401,8 +443,12 @@ db.exec(`
     error_msg  TEXT
   )
 `);
-db.exec(`CREATE INDEX IF NOT EXISTS idx_mcp_tool_calls_ts   ON mcp_tool_calls(ts)`);
-db.exec(`CREATE INDEX IF NOT EXISTS idx_mcp_tool_calls_tool ON mcp_tool_calls(tool_name, ts)`);
+// 索引命名与 runtime bridge(apply-webaz-runtime-schema)统一 —— 两组合根曾各自命名(idx_mcp_tool_calls_* vs idx_mcp_tc_*)
+//   → 同库跑过两根就出现同列重复索引,且 pg 产物逐列/索引 parity 因根不同而漂移。老名幂等清除。
+db.exec(`DROP INDEX IF EXISTS idx_mcp_tool_calls_ts`);
+db.exec(`DROP INDEX IF EXISTS idx_mcp_tool_calls_tool`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_mcp_tc_ts   ON mcp_tool_calls(ts)`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_mcp_tc_tool ON mcp_tool_calls(tool_name, ts)`);
 // ─── 4 层身份模型 helpers（与 PWA server 同源逻辑）───────────────
 const PERMA_ALPHABET_MCP = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
 function mcpGeneratePermanentCode() {
@@ -489,14 +535,21 @@ No auth required, no parameters needed.
 2. action="complete" → retrieves the credential ONCE (PKCE) and stores it in your OS secret store (macOS Keychain → ~/.webaz/credentials 0600 fallback). Returns only a credential_handle + status — the raw token is never shown.
 3. action="verify" → uses the stored grant against a safe read endpoint to confirm it is still valid. The server re-checks active/expiry/revoked/suspension/scope and audits the call every time. Returns the grant principal/status; never the raw token.
 
-Scopes: SAFE only (read_public, profile_read, search, list_product_draft, product_publish_request, draft_order). Risk scopes (place_order/wallet/refund/...) and never-delegable actions (withdraw/key-change/vote/...) are hard-rejected.
+Need MORE scope later? If a call returns error_code="PERMISSION_REQUIRED", do NOT re-pair:
+4. action="request" (bundle="catalog_agent" OR scopes=[...]) → asks the human to expand THIS grant. Returns an approval_id + approval_url; the human approves with a Passkey, then you simply RETRY your original call.
+5. action="requests" → lists your grant's own requests + status (pending/approved/rejected) so you can poll instead of hitting the target surface.
+
+Scopes: SAFE only (read_public, profile_read, search, list_product_draft, product_publish_request, draft_order + seller_*_read / seller_product_draft / seller_pricing_suggestion; bundle "catalog_agent"). Risk scopes (place_order/wallet/refund/...) and never-delegable actions (withdraw/key-change/vote/...) are hard-rejected.
 
 NOTE: this consumes the grant only on safe read paths; no business tool and no risk scope is wired to grants. No account is created (registration stays human-only at webaz.xyz).`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['start', 'complete', 'verify'], description: 'start a pairing, complete it after the human approves, or verify the stored grant (default: start)' },
-                capabilities: { type: 'array', items: { type: 'string' }, description: 'Requested SAFE scopes (default: read_public, search). Non-safe scopes are rejected.' },
+                action: { type: 'string', enum: ['start', 'complete', 'verify', 'request', 'requests'], description: 'start a pairing, complete it after the human approves, verify the stored grant, request MORE scope (bundle/scopes), or list your requests (default: start)' },
+                capabilities: { type: 'array', items: { type: 'string' }, description: 'action="start": requested SAFE scopes (default: read_public, search). Non-safe scopes are rejected.' },
+                bundle: { type: 'string', description: 'action="request": a permission bundle key (e.g. "catalog_agent") — a named all-safe scope set the human approves as one thing.' },
+                scopes: { type: 'array', items: { type: 'string' }, description: 'action="request": individual SAFE scopes to request (alternative to bundle).' },
+                duration: { type: 'string', enum: ['once', '1h', '24h', '7d', '30d'], description: 'action="request": how long the expanded grant should last (safe scopes may be long-term; the server caps by risk).' },
                 agent_label: { type: 'string', description: 'Human-friendly name for this agent (shown in the consent screen)' },
                 reason: { type: 'string', description: 'Free-text reason shown to the human (you cannot relabel the scopes)' },
             },
@@ -813,9 +866,9 @@ Actions:
 - list_open     pending disputes (arbitrators only)
 - respond       respondent rebuttal (before 48h deadline)
 - add_evidence  any participant supplements
-- arbitrate     ruling + fund disposition (assigned arbitrator only)
+- arbitrate     ruling (assigned arbitrator only). ESCROW: fund disposition. DIRECT PAY (payment_rail=direct_p2p, non-custodial): reputation-only ruling — NO refund/release/arbitration-fee, NO amounts.
 
-Ruling options: refund_buyer | release_seller | partial_refund (needs refund_amount; optional liable_party → 3rd-party fault, seller settled full + deducted from liable) | liability_split (needs liability_parties[]={user_id,amount}).
+Ruling options — ESCROW: refund_buyer | release_seller | partial_refund (needs refund_amount; optional liable_party → 3rd-party fault, seller settled full + deducted from liable) | liability_split (needs liability_parties[]={user_id,amount}). DIRECT PAY: refund_buyer=买家胜诉 | release_seller=卖家胜诉 | partial_refund=部分责任 — reputation verdict only, do NOT pass refund_amount/liability_parties (protocol holds no funds). Check \`view\`→payment_rail/ruling_options first.
 
 Protocol auto-judges (no human): respondent silent 48h → favor initiator; arbitrator silent 120h → refund_buyer. Executed rulings are instant + irreversible.
 
@@ -1899,10 +1952,10 @@ async function handleInfo() {
                     ? '🟢 NETWORK（只读）：无 api_key。公共读（搜索/榜单/价格史/浏览）打 webaz.xyz 真网络（见 network_live）。要交易（注册/下单/上架等）请设 WEBAZ_API_KEY —— 到 ' + WEBAZ_API_URL + '/#welcome 申请邀请。'
                     : '🟡 SANDBOX：所有工具都在本机本地 SQLite 运行，与 webaz.xyz 全网隔离（显式 dev/demo 模式）。任何计数 / 账号 / 订单仅本机有效。不设 WEBAZ_MODE 则默认走真网络只读。',
             phase: 'pre_launch',
-            real_users_on_canonical: 0,
+            // 真实用户/规模【不在此硬编码】—— 网络模式下 network_live(上方,实时拉 /api/protocol-status)带有 real_users_on_canonical 真值。
             canonical_endpoint: 'https://webaz.xyz',
             economic_flow: 'simulated WAZ (test currency, 1 WAZ ≈ 1 USDC peg is a模拟基准, not a real exchange rate). No fiat/crypto settles yet.',
-            disclaimer: '本协议尚未公开上线,prod 真实用户≈0,无真实经济流转。下方 live_stats / 工具示例所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
+            disclaimer: '本协议尚未公开上线(pre-launch),无真实经济流转。真实用户/规模请以 network_live(本次从 webaz.xyz 实时拉取的 /api/protocol-status,含 real_users_on_canonical)为准;下方 live_stats / 工具示例的所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
         },
         description: 'WebAZ is a decentralized commerce protocol. Every transaction flows through a state machine; each state transition needs proof-of-action from the responsible party. Any timeout-without-action: protocol auto-rules default + executes remedy. / WebAZ 是去中心化商业协议;每笔交易通过状态机流转,每次状态转移需对应责任方的操作证明;超时未操作则协议自动判违约并执行处置。',
         // 给【终端用户/买家】的价值主张 —— 陌生 agent / 普通买家先要知道"对我有什么用",而非只读抽象 tagline + 技术 description。
@@ -1996,7 +2049,7 @@ function handleRegister(args) {
             ],
             register_url: WEBAZ_API_URL,
             why_not_agent_self_register: 'agent 自助注册会绕过邀请 / captcha / 真人 Passkey 责任制，破坏协议的可问责性（#6 不滥用 / CHARTER §4 I-5）。',
-            want_to_try_offline_first: '只想离线试玩、暂不连网络？设环境变量 WEBAZ_MODE=sandbox（或清空 WEBAZ_API_KEY），webaz_register 会在本机沙盒建一个测试账号（仅本机有效）。',
+            want_to_try_offline_first: '只想离线试玩、暂不连网络？设环境变量 WEBAZ_MODE=sandbox（本机沙盒需显式开启；无 key 仍是 NETWORK 只读，不会进沙盒），webaz_register 会在本机沙盒建一个测试账号（仅本机有效）。',
         };
     }
     // ─── SANDBOX 模式：本机建测试账号（显著标注，仅本机有效，与 webaz.xyz 全网隔离）──
@@ -2524,8 +2577,8 @@ async function handleListProduct(args) {
       id, seller_id, title, description, price, stock, category, stake_amount,
       specs, brand, model, source_price,
       ship_regions, handling_hours, estimated_days, fragile,
-      return_days, return_condition, warranty_days
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?)
+      return_days, return_condition, warranty_days, currency
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, 'WAZ')
   `).run(id, user.id, args.title, args.description, price, args.stock ?? 1, args.category ?? null, stakeAmount, specsJson, args.brand ?? null, args.model ?? null, args.source_price != null ? Number(args.source_price) : null, args.ship_regions ?? '全国', args.handling_hours != null ? Number(args.handling_hours) : 24, estJson, args.fragile ? 1 : 0, args.return_days != null ? Number(args.return_days) : 7, args.return_condition ?? '', args.warranty_days != null ? Number(args.warranty_days) : 0);
     // 注：per-order stake 模型不在此 lock — 移到 place_order 时按订单总额锁
     // S2/S3/S4 新字段：通过 HTTP PUT 走标准校验路径（i18n 语言白名单 / origin_claims 4KB+sha256 / 库存阈值）
@@ -2788,7 +2841,7 @@ async function handleUpdateOrder(args) {
     const isParticipant = order.buyer_id === user.id ||
         order.seller_id === user.id ||
         order.logistics_id === user.id;
-    if (!isParticipant && user.role !== 'arbitrator') {
+    if (!isParticipant && !isActiveWhitelistArbitrator(db, user.id)) { // 白名单(非 legacy role):role-only/已吊销不可越权;下游 transition 仍按 actor.role 守边
         return { error: '你不是这笔订单的参与方，无法操作' };
     }
     // action → 状态映射
@@ -3091,10 +3144,13 @@ async function handleDispute(args) {
         WHERE e.order_id = ? AND u.role = ?
         ORDER BY e.created_at ASC
       `).all(orderId, uploaderRole);
+        const dpNonCustodial = dispute.payment_rail === 'direct_p2p'; // 直付=非托管:仅信誉裁决,无退款/放款/仲裁费/金额
         return {
             dispute_id: dispute.id,
             order_id: dispute.order_id,
             status: dispute.status,
+            payment_rail: dispute.payment_rail || 'escrow',
+            non_custodial: dpNonCustodial,
             initiator: `${dispute.initiator_name}（${dispute.initiator_role}）`,
             defendant: `${dispute.defendant_name}（${dispute.defendant_role}）`,
             reason: dispute.reason,
@@ -3104,21 +3160,27 @@ async function handleDispute(args) {
             defendant_notes: dispute.defendant_notes ?? '（被诉方尚未提交回应）',
             defendant_evidence: JSON.parse(dispute.defendant_evidence_ids || '[]'),
             ruling: dispute.ruling_type
-                ? { type: dispute.ruling_type, refund_amount: dispute.refund_amount, reason: dispute.verdict_reason }
+                ? (dpNonCustodial
+                    ? { type: dispute.ruling_type, reason: dispute.verdict_reason, note: '非托管信誉裁决:无退款/放款金额' }
+                    : { type: dispute.ruling_type, refund_amount: dispute.refund_amount, reason: dispute.verdict_reason })
                 : null,
-            // QA 轮 15 P1：未裁定时暴露可选 ruling 列表（与 PWA disputes-write.ts validRulings 对齐）
-            ruling_options: dispute.ruling_type ? undefined : [
+            // 未裁定时暴露可选 ruling 列表。direct_p2p:仅信誉裁决(胜负/责任,无金额);escrow:含金额/责任分配。
+            ruling_options: dispute.ruling_type ? undefined : (dpNonCustodial ? [
+                { type: 'refund_buyer', desc: '判买家胜诉（信誉裁决;非托管:无退款/放款/仲裁费）' },
+                { type: 'release_seller', desc: '判卖家胜诉（信誉裁决;无退款/放款）' },
+                { type: 'partial_refund', desc: '判部分责任（信誉裁决;无金额）' },
+            ] : [
                 { type: 'refund_buyer', desc: '全额退款给买家（卖家败诉）' },
                 { type: 'release_seller', desc: '放款给卖家（买家败诉）' },
                 { type: 'partial_refund', desc: '部分退款（需传 refund_amount）' },
                 { type: 'liability_split', desc: '按责任分配（需传 liability_parties 数组）' },
-            ],
+            ]),
             resolved_at: dispute.resolved_at,
         };
     }
     // ── 仲裁员查看所有待处理争议 ───────────────────────────────
     if (action === 'list_open') {
-        if (user.role !== 'arbitrator') {
+        if (!isActiveWhitelistArbitrator(db, user.id)) { // 白名单(非 legacy role):whitelist-only 真人可用,role-only/已吊销 403
             return { error: '只有仲裁员可以查看所有待处理争议' };
         }
         const disputes = await getOpenDisputes(db);
@@ -3131,7 +3193,7 @@ async function handleDispute(args) {
                 initiator: `${d.initiator_name}（${d.initiator_role}）`,
                 defendant: `${d.defendant_name}（${d.defendant_role}）`,
                 reason: d.reason,
-                amount: `${d.total_amount} WAZ`,
+                amount: d.payment_rail === 'direct_p2p' ? `${d.total_amount} USDC（非托管·信誉裁决）` : `${d.total_amount} WAZ`,
                 respond_deadline: d.respond_deadline,
                 arbitrate_deadline: d.arbitrate_deadline,
                 created_at: d.created_at,
@@ -3713,13 +3775,18 @@ async function handleReferral(args) {
                 state = 'never_activated';
                 note = 'Rewards inactive — attributions recorded; commissions held in pending_commission_escrow (30d window per protocol_params.rewards_opt_in.escrow_days) until you activate via PWA #me.';
             }
-            const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending'").get(userId);
-            const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired'").get(userId);
+            // RFC-018: matures_at IS NULL = opt-out escrow only (clearing rows auto-mature; surfaced separately in PR3).
+            const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NULL").get(userId);
+            const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired' AND matures_at IS NULL").get(userId);
+            // RFC-018 clearing window: opted-in commission accrued but not yet matured into the wallet
+            // (matures_at NOT NULL). Distinct from opt-out escrow above — pure read, surfaced for the agent.
+            const clearing = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NOT NULL").get(userId);
             return {
                 state,
                 opted_in: optIn === 1,
                 note,
                 pending_escrow: { count: pending.n, total_amount: pending.total },
+                clearing: { count: clearing.n, total_amount: clearing.total }, // RFC-018: accrued, maturing after the return window (not yet paid)
                 expired_to_charity: { count: expired.n, total_amount: expired.total },
                 spec: 'RFC-002 §3.5 — rewards / share-commission opt-in (RFC-002)',
             };