@seasonkoh/webaz 0.1.31 → 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.',
         };
@@ -548,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)' },
             },
@@ -1714,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 能送达)
@@ -1892,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;
@@ -1944,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 自己判断如何处理。
@@ -2448,6 +2522,57 @@ async function handleVerifyPrice(args) {
         next: `调用 webaz_place_order 时传入 session_token="${token}" 确保以此价格成交`,
     };
 }
+// 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';
@@ -5277,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();
+}

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

@@ -15,6 +15,8 @@
 import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
 import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 seam(纯读)
 import { transition } from '../../layer0-foundation/L0-2-state-machine/engine.js';
+import { resolveDeclineContestDispute } from './decline-contest-resolve.js'; // PR3 唯一裁决器(超时硬兜底入口)
+import { notifyDeclineContestEscalated } from '../../layer2-business/L2-6-notifications/notification-engine.js'; // 四段式升级通知
 // RFC-014 PR5 — 争议资金处置走整数 base-units + 绝对值落库 + allocate 精确拆分。
 import { toUnits, toDecimal, mulRate, allocate } from '../../money.js';
 import { applyWalletDelta, debitStakeThenBalance, walletUnits } from '../../ledger.js';
@@ -41,6 +43,9 @@ export function initDisputeSchema(db) {
         `ALTER TABLE disputes ADD COLUMN auto_judge_paused_until INTEGER`,
         `ALTER TABLE disputes ADD COLUMN auto_judge_pause_reason TEXT`,
         `ALTER TABLE disputes ADD COLUMN audit_log TEXT DEFAULT '[]'`,
+        // 2026-07 统一仲裁台:案子类型标签。默认 'buyer_dispute'(既有买家/直付/退货争议);
+        //   'decline_contest' = RFC-007 卖家客观拒单举证并入 disputes(UI 显示"拒单举证仲裁",裁决走专用两选 + settleFault/settleDeclinedNoFault)。
+        `ALTER TABLE disputes ADD COLUMN dispute_type TEXT DEFAULT 'buyer_dispute'`,
     ];
     for (const stmt of newColumns) {
         try {
@@ -48,6 +53,11 @@ export function initDisputeSchema(db) {
         }
         catch { /* 列已存在，跳过 */ }
     }
+    // 幂等硬约束:一个订单最多一条 decline_contest dispute(防重复建行/重复结算)。部分唯一索引 —— 仅约束该类型行。
+    try {
+        db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS ux_disputes_decline_contest_order ON disputes(order_id) WHERE dispute_type = 'decline_contest'`);
+    }
+    catch { /* 已存在，跳过 */ }
 }
 /** 任意参与方（非被告）主动提交证据 */
 export function addPartyEvidence(db, disputeId, submitterId, description, evidenceType = 'text', fileHash) {
@@ -121,6 +131,56 @@ export function createDispute(db, orderId, initiatorId, reason, evidenceIds) {
         message: `争议已记录（${disputeId}）。被诉方有 48 小时提交反驳证据，超时协议自动判你胜诉。`,
     };
 }
+/**
+ * RFC-007 → 统一仲裁台:为【已举证的客观拒单】订单建一条 decline_contest dispute 行。
+ *
+ * 单一真相源:contest_decline 路由(新单)与 backfill 脚本(历史 stuck 单,如 ord_54fa)都调此函数。
+ * 设计约束:
+ *   - 不改 order.status(订单仍 fault_seller + 标志位);dispute 行只是并入统一仲裁台的把手。
+ *   - initiator = 卖家(发起举证、承担"客观无责"举证责任);defendant = 买家(受影响方)。COI 由 arbitratorHasConflict
+ *     统一覆盖(买/卖/物流/发起/被告均不可裁,PR3 复用)。
+ *   - 幂等:一个订单至多一条 decline_contest dispute —— 存在性检查 + 部分唯一索引(ux_disputes_decline_contest_order)
+ *     双保险;并发建行由唯一索引兜底,重复调用返回既有行(existing=true),绝不建第二条。
+ *   - PR1 fail-closed:此行建好后【不可被通用自动裁决结算、不可被通用 arbitrate 误裁】(见 checkDisputeTimeouts /
+ *     arbitrate 路由的 decline_contest 分支),直到 PR3 打通专用两选裁决 + settleFault/settleDeclinedNoFault。
+ */
+export function createDeclineContestDispute(db, orderId) {
+    const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
+    if (!order)
+        return { success: false, error: `订单不存在：${orderId}` };
+    // 仅【已举证的临时判责】合格:fault_seller + provisional pending + contested + 未结算。
+    if (order.status !== 'fault_seller' || Number(order.decline_objective_pending) !== 1 || Number(order.decline_contested) !== 1 || order.settled_fault_at) {
+        return { success: false, error: '订单不是【已举证的客观拒单临时判责】状态,不建仲裁行' };
+    }
+    // 幂等①:存在性检查。
+    const existing = db.prepare("SELECT id FROM disputes WHERE order_id = ? AND dispute_type = 'decline_contest'").get(orderId);
+    if (existing)
+        return { success: true, disputeId: existing.id, existing: true };
+    const sellerId = order.seller_id;
+    const buyerId = order.buyer_id;
+    const now = new Date();
+    const disputeId = generateId('dsp');
+    const respondDeadline = addHours(now, 48); // 买家反驳窗口(PR3 定义超时四段式;PR1 仅建行,不驱动自动裁决)
+    const arbitrateDeadline = addHours(now, 120); // 仲裁窗口
+    const reasonCode = String(order.decline_reason_code || 'objective_decline');
+    const reason = `卖家客观拒单举证仲裁(${reasonCode}):卖家主张客观无责,请仲裁维持(免责·全退买家+退卖家质押)或驳回(判卖家违约)。`;
+    try {
+        db.prepare(`
+      INSERT INTO disputes (
+        id, order_id, initiator_id, defendant_id, reason, status, dispute_type,
+        defendant_evidence_ids, respond_deadline, arbitrate_deadline, assigned_arbitrators
+      ) VALUES (?, ?, ?, ?, ?, 'open', 'decline_contest', '[]', ?, ?, '[]')
+    `).run(disputeId, orderId, sellerId, buyerId, reason, respondDeadline, arbitrateDeadline);
+    }
+    catch (e) {
+        // 幂等②:并发建行撞唯一索引 → 返回既有行,不报错、不建第二条。
+        const race = db.prepare("SELECT id FROM disputes WHERE order_id = ? AND dispute_type = 'decline_contest'").get(orderId);
+        if (race)
+            return { success: true, disputeId: race.id, existing: true };
+        return { success: false, error: e.message };
+    }
+    return { success: true, disputeId };
+}
 // ─── L3-2 证据收集 ────────────────────────────────────────────
 /**
  * 被诉方提交反驳证据
@@ -616,6 +676,33 @@ export function checkDisputeTimeouts(db) {
     const openDisputes = db.prepare(`SELECT * FROM disputes WHERE status IN ('open', 'in_review')`).all();
     const sysUser = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
     for (const dispute of openDisputes) {
+        // PR3 四段式超时:decline_contest 不走通用自动裁决,走专用兜底。
+        //   仲裁窗口(arbitrate_deadline)内 → 不动;过窗口且 ≤+48h → 升级通知(去重,只发一次),等仲裁员/admin;
+        //   过 +48h admin fallback → 硬兜底判卖家违约(resolver 强制 decline_fault_confirmed + auto_resolved_by_timeout)。
+        if (dispute.dispute_type === 'decline_contest') {
+            const ad = dispute.arbitrate_deadline;
+            if (!ad || now <= ad)
+                continue; // 仲裁窗口内
+            const fallbackDeadline = addHours(new Date(ad), 48); // admin fallback 截止 = arbitrate_deadline + 48h
+            if (now <= fallbackDeadline) { // 段3:升级通知(去重),等人裁
+                try {
+                    notifyDeclineContestEscalated(db, dispute.order_id);
+                }
+                catch (e) {
+                    console.warn('[dc-escalate]', e.message);
+                }
+                continue;
+            }
+            // 段4:硬兜底 —— 判卖家违约。走与仲裁员完全相同的 resolver(dispute CAS + 终态 completed + 结算,单事务)。
+            try {
+                resolveDeclineContestDispute(db, dispute.id, 'sys_protocol', 'decline_fault_confirmed', '仲裁窗口 + admin 兜底窗口均超时,协议自动判卖家违约(卖家担客观无责举证责任)', 'timeout_auto');
+                details.push({ disputeId: dispute.id, action: 'decline_contest 超时自动判违约', orderId: dispute.order_id });
+            }
+            catch (e) {
+                console.warn('[dc-timeout-auto]', e.message);
+            }
+            continue;
+        }
         // task #1093 stage 6: skip auto-judge if arbitrator paused the clock (playbook §2.1)
         // Pause expires automatically when auto_judge_paused_until passes; no resume needed
         // for the clock to thaw — explicit resume just clears the field eagerly + audit log.
@@ -804,6 +891,28 @@ export async function getOpenDisputes(_db) {
     ORDER BY d.created_at ASC
   `);
 }
+/* PR2:decline_contest 现已进入统一仲裁员队列(SELECT d.* 带出 dispute_type,前端渲染"拒单举证仲裁"标签)。
+   裁决仍 fail-closed(checkDisputeTimeouts 跳过 + arbitrate 路由 409),PR3 打通专用两选裁决。 */
+/**
+ * 仲裁员历史裁决:近期已结(resolved/dismissed)争议。与 [[getOpenDisputes]] 同 DTO 形状(前端 compactRow 通用)。
+ *   `/api/disputes` 路由把它拼在 open+in_review 之后 → 前端"已结"sub-tab + todayDone KPI 有数据(此前恒空)。
+ *   getOpenDisputes 语义(仅 open)不变(MCP 也用它);历史用本函数,按 resolved_at 倒序,LIMIT 防拉全表。
+ */
+export async function getRecentResolvedDisputes(_db, limit = 50) {
+    return await dbAll(`
+    SELECT d.*,
+      u1.name as initiator_name, u1.role as initiator_role,
+      u2.name as defendant_name, u2.role as defendant_role,
+      o.total_amount, o.status as order_status, o.payment_rail
+    FROM disputes d
+    LEFT JOIN users u1 ON d.initiator_id = u1.id
+    LEFT JOIN users u2 ON d.defendant_id = u2.id
+    LEFT JOIN orders o ON d.order_id = o.id
+    WHERE d.status IN ('resolved', 'dismissed')
+    ORDER BY d.resolved_at DESC, d.created_at DESC
+    LIMIT ?
+  `, [limit]);
+}
 // ─── 工具函数 ─────────────────────────────────────────────────
 function addHours(date, hours) {
     return new Date(date.getTime() + hours * 3_600_000).toISOString();

package/dist/pwa/agent-order-minimal-view.js

@@ -0,0 +1,29 @@
+import { getActiveDeadline } from '../layer0-foundation/L0-2-state-machine/engine.js';
+import { CURRENT_RESPONSIBLE, CURRENT_RESPONSIBLE_SELF_FULFILL } from '../layer0-foundation/L0-2-state-machine/transitions.js';
+/** 调用方须只 SELECT 非 PII 列:id, status, total_amount, product_id, logistics_id, 及各 *_deadline 列。 */
+export function minimalSellerOrderView(order, db) {
+    const status = String(order.status ?? '');
+    const isSelfFulfill = !order.logistics_id;
+    const table = (isSelfFulfill ? CURRENT_RESPONSIBLE_SELF_FULFILL : CURRENT_RESPONSIBLE);
+    let deadline = null;
+    try {
+        deadline = getActiveDeadline(order, db)?.deadline ?? null;
+    }
+    catch {
+        deadline = null;
+    }
+    return {
+        order_id: String(order.id ?? ''),
+        status,
+        next_actor: table[status] ?? null,
+        deadline,
+        amount: order.total_amount == null ? null : Number(order.total_amount),
+        item_ref: order.product_id == null ? null : String(order.product_id),
+    };
+}
+/** 最小化读只取这些【非 PII】列(供路由 SELECT + 测试断言 SELECT 不含 PII)。 */
+export const MINIMAL_ORDER_COLUMNS = [
+    'id', 'status', 'total_amount', 'product_id', 'logistics_id',
+    'pending_accept_deadline', 'pay_deadline', 'accept_deadline', 'ship_deadline',
+    'pickup_deadline', 'delivery_deadline', 'confirm_deadline',
+];