@seasonkoh/webaz 0.1.30 → 0.1.32

package/README.md

@@ -47,9 +47,11 @@ Open the PWA, register a local account, and walk a full order → ship → confi
 WebAZ ships an **MCP server**. MCP is an open standard, so it works with **any MCP-capable client** — Claude Desktop, Claude Code, Codex, Cursor, or your own agent. Add the server to your client's MCP config:
 
 ```json
-{ "mcpServers": { "webaz": { "command": "npx", "args": ["-y", "@seasonkoh/webaz"] } } }
+{ "mcpServers": { "webaz": { "command": "npx", "args": ["-y", "@seasonkoh/webaz@latest"] } } }
 ```
 
+> **Updating:** MCP clients don't auto-update servers, and `npx` caches by version — so a client restart alone may keep running an older cached build. To pick up a new release: clear the cache (`rm -rf ~/.npm/_npx`) and restart the client. To pin a specific version instead of tracking latest, use `@seasonkoh/webaz@0.1.32`.
+
 - 🟢 **Network read-only (default, zero-config):** with no `WEBAZ_API_KEY`, public reads (`webaz_search` / leaderboard / price history / browse) hit the **live shared network** at [webaz.xyz](https://webaz.xyz) — nothing local. Transactional tools (register / order / list / fulfill) need a key.
 - 🟢 **Network (full):** register at [webaz.xyz](https://webaz.xyz) (invite + Passkey = an accountable human), copy your `api_key`, and set it as `env.WEBAZ_API_KEY` → the agent can transact on the **live shared network**. (`webaz_register` never self-creates an account — accounts require a real human + Passkey, by protocol.)
 - 🟡 **Sandbox (explicit, dev/demo):** set `WEBAZ_MODE=sandbox` → a **private local SQLite playground, isolated from the live network** — safe to try the whole order flow offline. (Opt-in; the default with no key is Network read-only, not sandbox.)

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

@@ -473,7 +473,7 @@ function findActiveDeadlineTransition(order, now) {
     return null;
 }
 /** 获取当前有效的截止时间 */
-function getActiveDeadline(order, db) {
+export function getActiveDeadline(order, db) {
     // QA 轮 7 P1：旧表 picked_up 状态没 deadline → agent 不知道下一步多久前要做完
     // 修：picked_up 状态视为"已揽收，等运输/投递"，下一个 deadline 是 delivery_deadline
     // QA 轮 7 P1（另一条）：disputed 状态下没读 dispute_cases 的 arbitrate_deadline → agent 不知道仲裁还有多久

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

@@ -34,6 +34,10 @@ export const NETWORK_TOOLS = new Set([
     'webaz_get_status',
     'webaz_feedback',
     'webaz_contribute',
+    // RFC-021 fulfillment-agent grant-wired order tools (read minimal + submit action-request).
+    //   Grant-only (no api_key path); grants live on webaz.xyz so they must be network-reachable.
+    'webaz_get_agent_order',
+    'webaz_order_action_request',
     // Batch 1(只读 + 低危自身写):走 webaz.xyz Bearer api_key。
     'webaz_notifications',
     'webaz_nearby',

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

@@ -258,6 +258,7 @@ export async function handlePair(args) {
                 capabilities: caps,
                 agent_label: typeof args.agent_label === 'string' ? args.agent_label : undefined,
                 reason: typeof args.reason === 'string' ? args.reason : undefined, // free-text reason only
+                duration: typeof args.duration === 'string' ? args.duration : undefined, // SUGGESTED grant lifetime; the human picks/overrides at approve
             },
         });
         if (resp.error)
@@ -269,7 +270,9 @@ export async function handlePair(args) {
             user_code: resp.user_code,
             approve_url: `${WEBAZ_API_URL}${String(resp.approve_url || '')}`,
             expires_at: resp.expires_at,
-            next: `Ask the human to open approve_url (logged in at webaz.xyz) and approve. Then call webaz_pair again with action="complete".`,
+            suggested_duration: resp.suggested_duration,
+            allowed_durations: resp.allowed_durations,
+            next: `Ask the human to open approve_url (logged in at webaz.xyz) and approve — they choose the grant duration (your suggested_duration is pre-selected; allowed: ${Array.isArray(resp.allowed_durations) ? resp.allowed_durations.join('/') : 'once/1h/24h/7d/30d'}). Then call webaz_pair again with action="complete".`,
             capabilities_requested: caps.map(c => c.capability),
             note: 'Safe scopes only. The credential is delivered once on completion and stored in your OS secret store — it is never shown here.',
         };
@@ -308,22 +311,21 @@ 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.',
         };
     }
     if (action === 'request') {
@@ -549,7 +551,7 @@ NOTE: this consumes the grant only on safe read paths; no business tool and no r
                 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).' },
+                duration: { type: 'string', enum: ['1h', '24h', '7d', '30d'], description: 'SUGGESTED grant lifetime for action="start" (initial pairing) or action="request" (expansion). Safe scopes may be long-term (up to 30d); the human PICKS/overrides it at approve time and their choice wins. (No single-use "once" yet.)' },
                 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)' },
             },
@@ -654,7 +656,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).
 
@@ -671,7 +673,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: {
@@ -724,9 +726,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.
+
+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 (absolute ISO timestamps in response):
+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)
@@ -743,6 +750,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: {
@@ -1584,7 +1593,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)' },
@@ -1708,6 +1717,39 @@ Coordinates + records only — NO merge/reward; acceptance (done) = human mainta
             },
         },
     },
+    {
+        name: 'webaz_get_agent_order',
+        description: `Grant-wired MINIMAL order read for a fulfillment agent (safe scope seller_orders_read_minimal). Reads the seller's OWN orders via a paired delegation grant (webaz_pair — fulfillment_agent bundle), NOT an api_key. Returns a minimal projection only — order_id / status / next_actor / deadline / amount / item_ref — with NO buyer address / contact / PII and no execution.
+
+- order_id given → that one order; omitted → the seller's order list.
+- No grant paired → GRANT_REQUIRED (run webaz_pair action="start"). Missing scope → structured PERMISSION_REQUIRED (request via webaz_pair action="request" bundle="fulfillment_agent", have the human approve, then retry).
+- To ACT on an order (accept/ship), use webaz_order_action_request (submit → human Passkey approves → server executes).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                order_id: { type: 'string', description: "Order ID. Omit to list the seller's orders (minimal projection)." },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'webaz_order_action_request',
+        description: `Grant-wired order-action SUBMIT for a fulfillment agent (safe scope order_action_request). Submits an accept/ship request into the seller's HUMAN approval queue — it does NOT execute. The order action runs only after the human approves with their Passkey. Uses a paired delegation grant (webaz_pair — fulfillment_agent), NOT an api_key.
+
+- action="accept" (a paid order) | action="ship" (an accepted order; action_params needs { tracking, evidence_ref }).
+- Returns request_id + approval_url — tell the human to open it and approve with their Passkey; only then does the server execute the action.
+- decline is NOT delegable — the backend returns DECLINE_NOT_DELEGATED; a human must decline in the PWA.
+- No grant → GRANT_REQUIRED. Missing scope → structured PERMISSION_REQUIRED (request via webaz_pair action="request" bundle="fulfillment_agent"). No buyer address/PII in params.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                order_id: { type: 'string', description: 'Order ID' },
+                action: { type: 'string', enum: ['accept', 'ship'], description: 'accept a paid order, or ship an accepted order' },
+                action_params: { type: 'object', description: 'ship needs { tracking, evidence_ref }; accept needs none. Never put buyer address/PII here.' },
+            },
+            required: ['order_id', 'action'],
+        },
+    },
 ];
 // ─── 工具处理函数 ─────────────────────────────────────────────
 // RFC-004: webaz_feedback — agent-native "use → build" 反馈(双模;仅 NETWORK 能送达)
@@ -1886,8 +1928,45 @@ export async function handleContribute(args) {
     }
     return { error: 'unknown action: ' + action };
 }
+/** Minimal semver "a < b" for plain x.y.z release strings (our versions carry no pre-release tags).
+ *  NUMERIC per-part — must not string-compare (else '0.1.9' > '0.1.10' is wrong). */
+export function isOlderVersion(a, b) {
+    const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
+    const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] || 0, y = pb[i] || 0;
+        if (x !== y)
+            return x < y;
+    }
+    return false;
+}
+/** Best-effort "is a newer MCP published?" nudge for webaz_info. npm is the source of truth (the live server
+ *  version can LAG a publish), so we ask the registry directly. Network-gated + short timeout + never throws —
+ *  a missing/slow check must never break webaz_info. */
+async function checkMcpVersion() {
+    const current = SOFTWARE_VERSION;
+    if (!isNetworkMode())
+        return { mcp_version: current, update_check: 'skipped (sandbox mode — no external calls)' };
+    try {
+        const r = await fetch('https://registry.npmjs.org/@seasonkoh/webaz/latest', { signal: AbortSignal.timeout(2500) });
+        if (!r.ok)
+            return { mcp_version: current, update_check: `unavailable (npm ${r.status})` };
+        const latest = String((await r.json()).version || '');
+        const stale = !!latest && isOlderVersion(current, latest);
+        return {
+            mcp_version: current,
+            latest_version: latest || undefined,
+            update_available: stale,
+            ...(stale ? { update_note: `A newer WebAZ MCP is published (${latest} > your ${current}). Update your connector to "@seasonkoh/webaz@latest" (or @${latest}), then FULLY restart the client (Cmd+Q) and open a NEW conversation — a conversation's MCP tool set is fixed at connect time, so an in-place refresh will NOT pick up new tools like webaz_pair.` } : {}),
+        };
+    }
+    catch (e) {
+        return { mcp_version: current, update_check: `unavailable (${e.message})` };
+    }
+}
 async function handleInfo() {
     const summary = getManifestSummary();
+    const mcp = await checkMcpVersion();
     // RFC-003 Batch 0:NETWORK 模式下,best-effort 拉 webaz.xyz 的 live 协议状态,
     // 让带 key 的 agent 拿到【真网络】数字,而非只看本机本地 live_stats(下方仍保留并标注为本地)。
     let network_live = null;
@@ -1938,6 +2017,7 @@ async function handleInfo() {
     })();
     return {
         ...summary,
+        mcp, // client MCP version + best-effort npm update check (mcp_version / latest_version / update_available / update_note)
         // 诚实化披露 — 排在 stats / quick_start 之前,让 agent 先建立正确预期。
         // 第三方尽调 agent 抓到过的破绽:live_stats 是本地库数字、引导词推 agent 拉新。
         // 此处主动披露真实状态(pre-launch / 数据来源),不抗辩;agent 自己判断如何处理。
@@ -2442,12 +2522,94 @@ async function handleVerifyPrice(args) {
         next: `调用 webaz_place_order 时传入 session_token="${token}" 确保以此价格成交`,
     };
 }
-async function handleListProduct(args) {
+// RFC-021 fulfillment-agent grant-wired order tools. PURE WRAPPERS over already-live endpoints —
+//   no backend/executor/projection/money change. Grant-only (these endpoints require a gtk_ grant
+//   bearer via requireAgentGrantScope; an api_key does not resolve them). Replicates the
+//   resolveGrantCredential → apiCall pattern (samizdat of handleListProduct's grant path).
+export async function handleGetAgentOrder(args) {
+    // Wraps GET /api/agent/orders(/:id) (safe scope seller_orders_read_minimal). Passes the minimal
+    //   projection through UNCHANGED — no field reshaped/added, nothing persisted; PII never enters here.
+    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: 'a delegation grant is required — run webaz_pair action="start", have the human approve the fulfillment_agent bundle, then retry.', error_code: 'GRANT_REQUIRED' };
+    const orderId = (typeof args.order_id === 'string' && args.order_id) ? args.order_id : '';
+    const path = orderId ? `/api/agent/orders/${encodeURIComponent(orderId)}` : '/api/agent/orders';
+    const r = await apiCall(path, { method: 'GET', apiKey: cred.token });
+    if (r.error_code === 'PERMISSION_REQUIRED')
+        return { ...r, retry_after_approval: true, hint: 'Your grant lacks seller_orders_read_minimal. Run webaz_pair action="request" bundle="fulfillment_agent", have the human approve, then retry.' };
+    return r;
+}
+export async function handleOrderActionRequest(args) {
+    // Wraps POST /api/agent/orders/:id/action-request (safe scope order_action_request). SUBMIT-ONLY:
+    //   writes a pending request to the human approval queue; NEVER executes (execution needs a human
+    //   Passkey approval). decline is not delegable — the backend returns DECLINE_NOT_DELEGATED and we
+    //   pass it through untouched. Client-side forward-allowlist keeps PII off the wire (see below).
+    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: 'a delegation grant is required — run webaz_pair action="start", have the human approve the fulfillment_agent bundle, then retry.', error_code: 'GRANT_REQUIRED' };
+    const orderId = (typeof args.order_id === 'string' && args.order_id) ? args.order_id : '';
+    if (!orderId)
+        return { error: 'order_id is required', error_code: 'ORDER_ID_REQUIRED' };
+    const body = { action: args.action };
+    // Client-side forward-allowlist (defense-in-depth): only `ship` carries params, and only
+    //   {tracking, evidence_ref} — so PII (address/recipient/phone) NEVER leaves the agent, not even
+    //   in the outbound request body. `accept` forwards no params. Canonical allowlist = the backend's
+    //   sanitizeOrderActionParams (order-action-request.ts) — keep these two fields in sync.
+    if (args.action === 'ship' && args.action_params && typeof args.action_params === 'object') {
+        const p = args.action_params;
+        const clean = {};
+        if (p.tracking != null)
+            clean.tracking = p.tracking;
+        if (p.evidence_ref != null)
+            clean.evidence_ref = p.evidence_ref;
+        body.action_params = clean;
+    }
+    const r = await apiCall(`/api/agent/orders/${encodeURIComponent(orderId)}/action-request`, { method: 'POST', apiKey: cred.token, body });
+    if (r.error_code === 'PERMISSION_REQUIRED')
+        return { ...r, retry_after_approval: true, hint: 'Your grant lacks order_action_request. Run webaz_pair action="request" bundle="fulfillment_agent", have the human approve, then retry.' };
+    return r;
+}
+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;
@@ -2610,9 +2772,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)
@@ -2623,6 +2796,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));
@@ -5225,6 +5402,12 @@ export async function startMCPServer() {
                     case 'webaz_get_status':
                         result = await handleGetStatus(args);
                         break;
+                    case 'webaz_get_agent_order':
+                        result = await handleGetAgentOrder(args);
+                        break;
+                    case 'webaz_order_action_request':
+                        result = await handleOrderActionRequest(args);
+                        break;
                     case 'webaz_feedback':
                         result = await handleFeedback(args);
                         break;

package/dist/layer2-business/L2-6-notifications/notification-engine.js

@@ -275,6 +275,102 @@ opts) {
     pushCallback?.(userId, notif);
     return notif;
 }
+/**
+ * 仲裁 admin 收件人:root(admin_type='root' → 隐含 ['all'])或 admin_permissions 含 'all'/'arbitration' 的 admin。
+ *   与争议读写授权边界(requireAdminPermission(...,'arbitration'))一致 —— content/support 等无 arbitration 权限的
+ *   admin【不】收到争议通知。复刻 hasAdminPermission 逻辑,不 import server 层。列缺失(fresh-DB)→ 空集。
+ */
+export function resolveArbitrationAdminIds(db) {
+    const ids = [];
+    try {
+        const rows = db.prepare("SELECT id, admin_type, admin_permissions FROM users WHERE role = 'admin'").all();
+        for (const r of rows) {
+            if (r.admin_type === 'root') {
+                ids.push(r.id);
+                continue;
+            }
+            let perms = [];
+            try {
+                perms = JSON.parse(r.admin_permissions || '[]');
+            }
+            catch {
+                perms = [];
+            }
+            if (Array.isArray(perms) && (perms.includes('all') || perms.includes('arbitration')))
+                ids.push(r.id);
+        }
+    }
+    catch { /* fresh-DB 无 admin_type/permissions 列 → 空集 */ }
+    return ids;
+}
+/**
+ * 统一仲裁台:一笔卖家客观拒单举证并入 disputes 后,通知全体 active 仲裁员 + 仲裁 admin(管理面)有新案待处理。
+ *   幂等去重:按 (order_id, type='arb:decline_contest_new', user_id) 存在性探测 —— 新建行、backfill 补建、
+ *   重复调用皆只对每个收件人发一次,不重复轰炸(镜像 scanDeadlineReminders 的 (order_id,type) 去重)。
+ *   收件人为 active arbitrator_whitelist(唯一仲裁能力源)+ users.role='admin'(监督/兜底)。
+ * 同步 better-sqlite3(engine 层);调用方(contest 路由 / backfill 脚本)传入同一个 db 句柄。
+ */
+export function notifyDeclineContestCase(db, orderId, disputeId) {
+    const TYPE = 'arb:decline_contest_new';
+    const ids = new Set();
+    try {
+        db.prepare("SELECT user_id AS id FROM arbitrator_whitelist WHERE status IS NULL OR status = 'active'").all().forEach(r => ids.add(r.id));
+    }
+    catch { /* fresh-DB 无表 */ }
+    resolveArbitrationAdminIds(db).forEach(id => ids.add(id)); // 仅仲裁 admin(root / all / arbitration),不含 content/support
+    let notified = 0, skipped = 0;
+    for (const uid of ids) {
+        const exists = db.prepare('SELECT 1 FROM notifications WHERE order_id = ? AND type = ? AND user_id = ? LIMIT 1').get(orderId, TYPE, uid);
+        if (exists) {
+            skipped++;
+            continue;
+        }
+        createNotification(db, uid, orderId, TYPE, '新的拒单举证仲裁待处理', '一笔卖家客观拒单举证已进入统一仲裁台,等待仲裁员裁决。', { templateKey: 'arb_decline_contest_new', params: { order_id: orderId, dispute_id: disputeId } });
+        notified++;
+    }
+    return { notified, skipped };
+}
+/**
+ * 四段式超时升级:仲裁窗口过后仍无裁决 → 通知 active 仲裁员 + 仲裁 admin 尽快处理(admin 可 override)。
+ *   与 [[notifyDeclineContestCase]] 同一收件人 + 同一 (order_id, type, user_id) 去重键,type='arb:decline_contest_escalated' 只发一次。
+ */
+export function notifyDeclineContestEscalated(db, orderId) {
+    const TYPE = 'arb:decline_contest_escalated';
+    const ids = new Set();
+    try {
+        db.prepare("SELECT user_id AS id FROM arbitrator_whitelist WHERE status IS NULL OR status = 'active'").all().forEach(r => ids.add(r.id));
+    }
+    catch { /* */ }
+    resolveArbitrationAdminIds(db).forEach(id => ids.add(id));
+    let notified = 0, skipped = 0;
+    for (const uid of ids) {
+        if (db.prepare('SELECT 1 FROM notifications WHERE order_id = ? AND type = ? AND user_id = ? LIMIT 1').get(orderId, TYPE, uid)) {
+            skipped++;
+            continue;
+        }
+        createNotification(db, uid, orderId, TYPE, '拒单举证仲裁已超时,请尽快裁决', '一笔拒单举证仲裁已过仲裁窗口仍未裁决,已进入 admin 兜底窗口 —— 请仲裁员或管理员尽快处理,否则将自动判卖家违约。', { templateKey: 'arb_decline_contest_escalated', params: { order_id: orderId } });
+        notified++;
+    }
+    return { notified, skipped };
+}
+/**
+ * 裁决落定后通知买卖双方结果(维持无责 / 驳回判违约)。非去重(每案只落定一次);买卖各一条。
+ */
+export function notifyDeclineContestResolved(db, orderId, decision) {
+    const o = db.prepare('SELECT buyer_id, seller_id FROM orders WHERE id = ?').get(orderId);
+    if (!o)
+        return;
+    const upheld = decision === 'decline_no_fault_upheld';
+    const title = upheld ? '拒单举证仲裁:维持无责' : '拒单举证仲裁:驳回,判卖家违约';
+    const body = upheld
+        ? '仲裁认定卖家客观无责:买家已全额退款,卖家质押已退回,无罚没。订单已结。'
+        : '仲裁驳回卖家举证,判卖家违约:买家已退款,卖家质押按违约处置。订单已结。';
+    for (const uid of [o.buyer_id, o.seller_id]) {
+        if (!uid)
+            continue;
+        createNotification(db, uid, orderId, 'arb:decline_contest_resolved', title, body, { templateKey: 'arb_decline_contest_resolved', params: { order_id: orderId, decision } });
+    }
+}
 // ─── 查询 ─────────────────────────────────────────────────────
 // RFC-016 Phase 1:纯读 → 异步 seam。db 参数保留(签名兼容),内部走 dbAll/dbOne(同实例,setSeamDb)。
 // 调用点全部已确认不在 db.transaction 内(notifications.ts:43/60/61 + mcp server.ts:2770/2771)。

package/dist/layer3-trust/L3-1-dispute-engine/decline-contest-resolve.js

@@ -0,0 +1,110 @@
+import { transition, settleFault, settleDeclinedNoFault } from '../../layer0-foundation/L0-2-state-machine/engine.js';
+import { arbitratorHasConflict } from '../../pwa/arbitrator-lifecycle.js';
+const SYS = 'sys_protocol'; // 终态转移执行者(role=system);真实裁决人记在 dispute
+export class DcResolveError extends Error {
+    code;
+    http;
+    constructor(code, message, http = 400) { super(message); this.code = code; this.http = http; }
+}
+function appendAudit(existing, entry) {
+    let log = [];
+    try {
+        const p = JSON.parse(existing || '[]');
+        if (Array.isArray(p))
+            log = p;
+    }
+    catch { /* 破损 → 重置为空,不丢新条目 */ }
+    log.push(entry);
+    return JSON.stringify(log);
+}
+/**
+ * 唯一裁决器。decision 对 timeout_auto 会被强制为 decline_fault_confirmed(硬兜底判卖家违约)。
+ * @throws DcResolveError(.http 供路由映射状态码);事务整体回滚。
+ */
+export function resolveDeclineContestDispute(db, disputeId, actorId, decision, reason, source) {
+    if (decision !== 'decline_no_fault_upheld' && decision !== 'decline_fault_confirmed') {
+        throw new DcResolveError('BAD_DECISION', "decision 必须为 'decline_no_fault_upheld'(维持无责) 或 'decline_fault_confirmed'(驳回判违约)", 400);
+    }
+    if (!reason || !String(reason).trim())
+        throw new DcResolveError('REASON_REQUIRED', '必须提供裁决理由', 400);
+    const run = db.transaction(() => {
+        const dispute = db.prepare('SELECT id, order_id, initiator_id, defendant_id, status, dispute_type, arbitrate_deadline, assigned_arbitrators, audit_log FROM disputes WHERE id = ?').get(disputeId);
+        if (!dispute)
+            throw new DcResolveError('DISPUTE_NOT_FOUND', '争议不存在', 404);
+        if (dispute.dispute_type !== 'decline_contest')
+            throw new DcResolveError('NOT_DECLINE_CONTEST', '本争议不是拒单举证仲裁', 400);
+        if (dispute.status !== 'open' && dispute.status !== 'in_review')
+            throw new DcResolveError('ALREADY_RULED', '本案已裁决', 409);
+        const order = db.prepare('SELECT id, buyer_id, seller_id, status, decline_objective_pending, decline_contested, settled_fault_at FROM orders WHERE id = ?').get(dispute.order_id);
+        if (!order)
+            throw new DcResolveError('ORDER_NOT_FOUND', '订单不存在', 404);
+        if (order.status !== 'fault_seller' || Number(order.decline_objective_pending) !== 1 || Number(order.decline_contested) !== 1 || order.settled_fault_at) {
+            throw new DcResolveError('ORDER_NOT_RESOLVABLE', '订单不是可裁决的【已举证客观拒单临时判责】状态', 409);
+        }
+        // ── ② 按 source 授权 ──
+        let effectiveDecision = decision;
+        const audit = { at: new Date().toISOString(), source, actor: actorId, decision };
+        if (source === 'arbitrator') {
+            if (arbitratorHasConflict(db, order.id, dispute.initiator_id, dispute.defendant_id, actorId))
+                throw new DcResolveError('ARBITRATOR_CONFLICT_OF_INTEREST', '你是本案当事方,不可仲裁(利益冲突)', 403);
+            // assignment CAS:首个仲裁员抢占;已分配他人 → 拒
+            let assigned = [];
+            try {
+                assigned = JSON.parse(dispute.assigned_arbitrators || '[]');
+            }
+            catch { /* */ }
+            if (assigned.length === 0) {
+                const claim = db.prepare("UPDATE disputes SET assigned_arbitrators = ? WHERE id = ? AND (assigned_arbitrators IS NULL OR assigned_arbitrators = '[]')").run(JSON.stringify([actorId]), disputeId);
+                if (claim.changes === 0) {
+                    const fresh = db.prepare('SELECT assigned_arbitrators FROM disputes WHERE id = ?').get(disputeId);
+                    try {
+                        assigned = JSON.parse(fresh?.assigned_arbitrators || '[]');
+                    }
+                    catch { /* */ }
+                }
+                else
+                    assigned = [actorId];
+            }
+            if (!assigned.includes(actorId))
+                throw new DcResolveError('NOT_ASSIGNED_ARBITRATOR', '本案已分配给其他仲裁员', 409);
+        }
+        else if (source === 'admin_fallback') {
+            if (arbitratorHasConflict(db, order.id, dispute.initiator_id, dispute.defendant_id, actorId))
+                throw new DcResolveError('ARBITRATOR_CONFLICT_OF_INTEREST', '你是本案当事方,不可裁决(利益冲突)', 403);
+            // §3 仲裁员优先:仅仲裁窗口(arbitrate_deadline)过后 admin 才可 override
+            if (!dispute.arbitrate_deadline || new Date().toISOString() <= dispute.arbitrate_deadline)
+                throw new DcResolveError('FALLBACK_TOO_EARLY', '仲裁窗口未过,admin 兜底裁决尚不可用(仲裁员优先)', 409);
+            audit.resolved_by_admin_override = actorId; // 不占用 assigned_arbitrators,以 override 记录
+        }
+        else { // timeout_auto
+            effectiveDecision = 'decline_fault_confirmed'; // 硬兜底:一律判卖家违约(卖家担客观无责举证责任)
+            audit.decision = effectiveDecision;
+            audit.auto_resolved_by_timeout = true;
+        }
+        // ── ① dispute CAS:抢占裁决权(并发第二人 → 0 行 → throw,不结算)──
+        const cas = db.prepare("UPDATE disputes SET status='resolved', ruling_type=?, verdict_reason=?, resolved_at=datetime('now'), audit_log=? WHERE id=? AND status IN ('open','in_review')")
+            .run(effectiveDecision, reason, appendAudit(dispute.audit_log, audit), disputeId);
+        if (cas.changes === 0)
+            throw new DcResolveError('ALREADY_RULED', '本案已被裁决(并发抢占)', 409);
+        // ── ③④ 终态转移 + 结算(用 SYS 执行状态机移动;每步失败即 throw 回滚)──
+        const orderId = order.id;
+        if (effectiveDecision === 'decline_no_fault_upheld') {
+            const t1 = transition(db, orderId, 'declined_nofault', SYS, [], `拒单举证仲裁维持无责:${reason}`);
+            if (!t1.success)
+                throw new DcResolveError('TRANSITION_FAILED', `转 declined_nofault 失败:${t1.error}`, 500);
+            settleDeclinedNoFault(db, orderId); // 全退买家 + 退卖家质押 + 回补库存(settled_fault_at 幂等)
+            const t2 = transition(db, orderId, 'completed', SYS, [], '客观无责裁定结算完成');
+            if (!t2.success)
+                throw new DcResolveError('TRANSITION_FAILED', `转 completed 失败:${t2.error}`, 500);
+        }
+        else {
+            settleFault(db, orderId, 'fault_seller'); // 退款买家 + 罚没卖家质押(settled_fault_at 幂等)
+            const t = transition(db, orderId, 'completed', SYS, [], `拒单举证仲裁驳回·判卖家违约:${reason}`);
+            if (!t.success)
+                throw new DcResolveError('TRANSITION_FAILED', `转 completed 失败:${t.error}`, 500);
+        }
+        db.prepare('UPDATE orders SET decline_objective_pending=0, decline_contested=0 WHERE id=?').run(orderId);
+        return { orderId, decision: effectiveDecision, source, buyerId: order.buyer_id, sellerId: order.seller_id };
+    });
+    return run();
+}