@seasonkoh/webaz 0.1.29 → 0.1.31

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

@@ -31,7 +31,8 @@ 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';
@@ -307,25 +308,68 @@ export async function handlePair(args) {
         };
     }
     if (action === 'verify') {
-        // Consume the stored grant against a SAFE grant-gated route (read_public). The SERVER is authoritative:
-        // it re-checks active/expiry/revoked/subject-suspension/scope + audits on EVERY call. We resolve the
-        // bearer from the secret store and attach it; the raw token is never printed. Safe scopes only — no
-        // business tool and no risk scope is wired to grants here.
+        // Ask the server for the FULL grant (all authorized scopes/bundle/expiry/status), not just one capability.
+        // The SERVER is authoritative: it re-checks active/expiry/revoked/subject-suspension + audits on EVERY call.
+        // We resolve the bearer from the secret store and attach it; the raw token is never printed.
         const cred = resolveGrantCredential();
         if (!cred)
             return { status: 'not_paired', error_code: 'NO_GRANT_CREDENTIAL', hint: 'No stored grant. Run webaz_pair action="start", have the human approve, then action="complete".' };
-        const resp = await apiCall('/api/agent-grants/whoami', { method: 'GET', apiKey: cred.token });
+        const resp = await apiCall('/api/agent-grants/verify', { method: 'GET', apiKey: cred.token });
         if (resp.error) {
             return { status: 'grant_invalid', grant_id: cred.grant_id, error: resp.error, error_code: resp.error_code, hint: 'Grant is no longer valid (revoked / expired / suspended). Re-pair with webaz_pair action="start".' };
         }
         return {
             status: 'active',
-            grant: resp.grant, // SERVER-AUTHORITATIVE principal (grant_id/human_id/agent_label/capability)
+            grant: resp.grant, // SERVER-AUTHORITATIVE principal: grant_id/human_id/agent_label + ALL scopes[]/permission_bundle/expiry/status
             local_cache: { capabilities: cred.capabilities, expires_at: cred.expires_at }, // advisory only, may be stale — NOT authoritative
-            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.',
+            note: 'Grant verified LIVE by the server (per-call: active/expiry/revoked/subject-suspension + audited). `grant.scopes` is the authoritative full scope list; `local_cache` is advisory. Safe scopes only.',
         };
     }
-    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() {
@@ -398,8 +442,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() {
@@ -486,14 +534,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)' },
             },
@@ -598,7 +653,7 @@ Skipping is allowed but agent then carries price/stock-race risk itself.`,
         // was ~1336 chars, now ~650 chars
         description: `⚠️ **"list" = PUBLISH** (verb), NOT "list out". Seller-only catalog publish + manage.
 
-USE THIS when seller wants to publish / update / delist / relist / trash / delete own product, OR view own listings (action=mine). NOT for browsing marketplace — use webaz_search (anyone, no auth). Requires seller api_key. On create: system auto-suggests stake ~15% of price (buyer protection).
+USE THIS when seller wants to publish / update / delist / relist / trash / delete own product, OR view own listings (action=mine). NOT for browsing marketplace — use webaz_search (anyone, no auth). A paired delegation grant (webaz_pair — Catalog Agent) can **read** (action=mine, seller_products_read) and **create DRAFTS** (action=create, seller_product_draft → the product lands in your warehouse as status=warehouse, NOT public); **publishing (going active), updating, delisting and deleting stay human/api_key only** — a grant can never publish. A grant that lacks the scope gets a structured PERMISSION_REQUIRED (request it via webaz_pair action="request", then retry). On create: system auto-suggests stake ~15% of price (buyer protection).
 
 Fill agent_summary fields completely (brand/return/handling/warranty) — helps buyer agents compare. For "exclusive-price vs external-link" listing → PWA Web only (link claim needs crowd-verify).
 
@@ -615,7 +670,7 @@ Actions: create (title/description/price) | mine | update (product_id + changed
                 product_id: { type: 'string', description: 'Product ID (required for update/delist/relist/trash/delete)' },
                 title: { type: 'string', description: 'Product name (required for create; optional for update)' },
                 description: { type: 'string', description: 'Product description (required for create; optional for update)' },
-                price: { type: 'number', description: 'Price in WAZ (required for create; optional for update)' },
+                price: { type: 'number', description: 'Listing amount = the protocol/base amount (waz_usdc_rate 1.0). No currency is set at listing time. On the direct_p2p rail the actual payable DISPLAY follows the seller\'s declared receiving-account currency/instruction — USDC only when that account is USDC/USD, otherwise the seller\'s currency ("以收款说明为准"); WebAZ does not custody, route, validate, or restrict the payment method/currency. USDC is only the base/reference amount when applicable. Legacy escrow uses WAZ. Required for create; optional for update.' },
                 stock: { type: 'number', description: 'Stock, default 1' },
                 category: { type: 'string', description: 'Category (optional)' },
                 specs: {
@@ -668,9 +723,14 @@ Actions: create (title/description/price) | mine | update (product_id + changed
     {
         name: 'webaz_place_order',
         // was ~1117 chars, now ~580 chars
-        description: `Buyer places order. Buyer api_key required. Funds auto-enter protocol escrow.
+        description: `Buyer places order. Buyer api_key required.
 
-Order deadlines (absolute ISO timestamps in response):
+Payment rail (chosen here, at purchase — default: escrow):
+- **escrow** (default, legacy): funds auto-enter protocol escrow; the amount is the WAZ/protocol-unit price. The deadlines/auto-judge below apply.
+- **direct_p2p** (live, non-custodial direct pay): buyer pays the seller directly OFF-platform via the seller's chosen receiving account. The order amount is the protocol/base amount; the actual payable DISPLAY follows that account's declared currency/instruction (USDC only when the account is USDC/USD — otherwise the seller's currency, "以收款说明为准"). WebAZ does NOT custody, route, validate, or restrict the method/currency. Pass \`direct_receive_account_id\` (seller's receiving account). Eligibility — product/store verification, per-tx caps, valid account — is enforced by the SERVER; you do not decide it. Ineligible → the route's own gate error (e.g. DIRECT_PAY_PRODUCT_NOT_VERIFIED → use escrow).
+- onchain_full_stake / psp: PLANNED, not enabled → passing them returns PAYMENT_RAIL_DISABLED.
+
+Order deadlines (escrow rail; absolute ISO timestamps in response):
 - accept    T+48h  | ship  T+120h (72h after accept)
 - pickup    T+168h (48h after ship) | delivery T+336h (7d after pickup)
 - confirm   T+408h (72h after delivery)
@@ -687,6 +747,8 @@ Options:
                 api_key: { type: 'string', description: "Buyer's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 product_id: { type: 'string', description: 'Product ID to buy (from webaz_search)' },
                 quantity: { type: 'number', description: 'Quantity, default 1' },
+                payment_rail: { type: 'string', enum: ['escrow', 'direct_p2p'], description: 'Payment rail (default: escrow). "direct_p2p" = live non-custodial direct pay, off-platform; the payable display follows the seller\'s receiving-account currency/instruction (USDC only as the base/reference amount, WebAZ doesn\'t custody/route/validate/restrict currency) — requires direct_receive_account_id; the server runs the direct-pay eligibility gates (you do not). Other rails (onchain_full_stake / psp) are planned but disabled → PAYMENT_RAIL_DISABLED.' },
+                direct_receive_account_id: { type: 'string', description: 'For payment_rail="direct_p2p": the seller\'s direct-receive account id to pay. Ignored on escrow.' },
                 shipping_address: { type: 'string', description: 'Shipping address' },
                 notes: { type: 'string', description: 'Note to seller (optional)' },
                 session_token: {
@@ -810,9 +872,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.
 
@@ -1528,7 +1590,7 @@ Enums: **category** phone/computer/appliance/furniture/clothing/book/toy/sports/
                 description: { type: 'string', description: 'Description (≤1000 chars, optional)' },
                 category: { type: 'string', enum: ['phone', 'computer', 'appliance', 'furniture', 'clothing', 'book', 'toy', 'sports', 'other'], description: 'Category (required for publish)' },
                 condition_grade: { type: 'string', enum: ['brand_new', 'like_new', 'lightly_used', 'well_used', 'heavily_used'], description: 'Condition grade (required for publish)' },
-                price: { type: 'number', description: 'Price in WAZ 0-100000 (required for publish)' },
+                price: { type: 'number', description: 'Listing amount 0-100000 = protocol/base amount (waz_usdc_rate 1.0). On direct_p2p the payable display follows the seller\'s receiving-account currency/instruction (USDC only as the base/reference; WebAZ doesn\'t custody/route/validate/restrict currency); WAZ on legacy escrow. Rail chosen at purchase. Required for publish.' },
                 negotiable: { type: 'boolean', description: 'Negotiable flag (optional)' },
                 images: { type: 'array', items: { type: 'string' }, description: 'Images dataURL/URL array, ≥1 ≤9 (required for publish)' },
                 region: { type: 'string', description: 'Region (≤40 chars, optional)' },
@@ -2386,12 +2448,43 @@ async function handleVerifyPrice(args) {
         next: `调用 webaz_place_order 时传入 session_token="${token}" 确保以此价格成交`,
     };
 }
-async function handleListProduct(args) {
+export async function handleListProduct(args) {
     // Wave 3 audit P0: 加 action 分发 — agent 卖家能完整管理目录（不止 create）
     const action = args.action || 'create';
     const apiKey = resolveMcpApiKey(args);
-    if (!apiKey)
-        return { error: 'api_key required' };
+    if (!apiKey) {
+        // No human api_key — fall back to a delegation grant (Catalog Agent). A grant can READ the catalog
+        //   (action="mine", seller_products_read) and create DRAFTS (action="create"|"draft", seller_product_draft
+        //   → status=warehouse, NOT public). Publishing (active) + all other writes stay human/api_key only.
+        //   Missing scope → structured PERMISSION_REQUIRED (agent can request it, then retry).
+        if (!isNetworkMode())
+            return { error: 'a delegation grant requires NETWORK mode (grants live on webaz.xyz)', error_code: 'GRANT_REQUIRES_NETWORK' };
+        const cred = resolveGrantCredential();
+        if (!cred)
+            return { error: 'api_key required — or pair a delegation grant: webaz_pair action="start", have the human approve the catalog_agent bundle, then retry.', error_code: 'AUTH_REQUIRED' };
+        if (action === 'mine') {
+            const r = await apiCall('/api/agent/seller/products', { method: 'GET', apiKey: cred.token });
+            if (r.error_code === 'PERMISSION_REQUIRED')
+                return { ...r, retry_after_approval: true, hint: 'Your grant lacks seller_products_read. Run webaz_pair action="request" bundle="catalog_agent", have the human approve, then retry.' };
+            if (r.error)
+                return r;
+            return { found: r.count, products: r.products, seller_id: r.seller_id, via: 'delegation_grant', note: 'Read via your delegation grant (safe scope seller_products_read). Creating a DRAFT: action="create" (goes to your warehouse for you to review + publish).' };
+        }
+        if (action === 'create' || action === 'draft') {
+            const createFields = ['title', 'description', 'price', 'stock', 'category', 'specs', 'brand', 'model', 'source_url', 'source_price', 'external_title', 'weight_kg', 'ship_regions', 'handling_hours', 'estimated_days', 'fragile', 'return_days', 'return_condition', 'warranty_days', 'commission_rate', 'product_type', 'aliases', 'image_hashes', 'additional_links'];
+            const body = {};
+            for (const k of createFields)
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            const r = await apiCall('/api/agent/seller/products', { method: 'POST', apiKey: cred.token, body });
+            if (r.error_code === 'PERMISSION_REQUIRED')
+                return { ...r, retry_after_approval: true, hint: 'Your grant lacks seller_product_draft. Run webaz_pair action="request" bundle="catalog_agent", have the human approve, then retry.' };
+            if (r.error)
+                return r;
+            return { ...r, via: 'delegation_grant', note: 'Created as a DRAFT (status=warehouse — NOT public/sellable). Publishing stays with the human: they review it in 我的商品 → 仓库 and publish (a notification was sent). A grant can never publish.' };
+        }
+        return { error_code: 'GRANT_WRITE_NOT_ENABLED', note: `action="${action}" is not available via a delegation grant — a grant can READ (action="mine") and create DRAFTS (action="create" → warehouse). Publishing, updating, delisting, and deleting stay human/api_key only. Provide a seller api_key for those.` };
+    }
     // RFC-003 P2b: NETWORK 模式 — 卖家目录管理全部转发生产端点（单一真相源）
     if (toolBackend('webaz_list_product') === 'network') {
         const pid = args.product_id;
@@ -2554,9 +2647,20 @@ async function handleListProduct(args) {
         ...(extraResult ? { extra_fields_applied: !('error' in extraResult), extra_result: extraResult } : {}),
     };
 }
-async function handlePlaceOrder(args) {
+export async function handlePlaceOrder(args) {
+    // Payment rail (PWA-aligned). Only escrow (legacy) + direct_p2p (live, non-custodial) are enabled; the
+    //   other declared rails (onchain_full_stake / psp) are PLANNED placeholders — refuse them here, never
+    //   silently downgrade. The MCP does NOT judge direct-pay eligibility: it forwards payment_rail +
+    //   direct_receive_account_id to the SAME /api/orders route, which runs all the PWA gates.
+    const rail = args.payment_rail;
+    if (rail != null && rail !== 'escrow' && rail !== 'direct_p2p') {
+        return { error: `payment rail "${String(rail)}" is planned but not enabled — only "direct_p2p" (live, non-custodial direct pay) and "escrow" (legacy) are available.`, error_code: 'PAYMENT_RAIL_DISABLED' };
+    }
+    if (rail === 'direct_p2p' && !isNetworkMode()) {
+        return { error: 'direct_p2p (direct pay) requires NETWORK mode — it settles against a real seller receiving account on webaz.xyz.', error_code: 'DIRECT_PAY_REQUIRES_NETWORK' };
+    }
     // RFC-003 P2: network 模式转发到生产 POST /api/orders(前置,绕过本地 db)。
-    // 生产端做完整鉴权/库存/session/spend-cap/结算。
+    // 生产端做完整鉴权/库存/session/spend-cap/结算 + direct-pay gate(createDirectPayResponse)。
     if (toolBackend('webaz_place_order') === 'network') {
         const body = { product_id: args.product_id, quantity: Number(args.quantity ?? 1) };
         if (args.session_token != null)
@@ -2567,6 +2671,10 @@ async function handlePlaceOrder(args) {
             body.shipping_address = args.shipping_address;
         if (args.donation_pct != null)
             body.donation_pct = args.donation_pct;
+        if (args.payment_rail != null)
+            body.payment_rail = args.payment_rail; // escrow | direct_p2p (route forks + gates)
+        if (args.direct_receive_account_id != null)
+            body.direct_receive_account_id = args.direct_receive_account_id; // seller receiving acct (direct_p2p)
         return apiCall('/api/orders', { method: 'POST', apiKey: resolveMcpApiKey(args), body });
     }
     const auth = requireAuth(db, resolveMcpApiKey(args));
@@ -2785,7 +2893,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 → 状态映射
@@ -3088,10 +3196,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,
@@ -3101,21 +3212,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);
@@ -3128,7 +3245,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,