@seasonkoh/webaz 0.1.31 → 0.1.32

package/dist/pwa/public/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "WebAZ Protocol API",
     "version": "0.4.14",
-    "description": "Auto-generated endpoint inventory (777 endpoints, 17 with full schema). See docs/ for design context."
+    "description": "Auto-generated endpoint inventory (780 endpoints, 17 with full schema). See docs/ for design context."
   },
   "servers": [
     {
@@ -648,28 +648,6 @@
         ]
       }
     },
-    "/api/admin/decline-contests": {
-      "get": {
-        "summary": "仲裁员待办:列出所有被举证的临时判责拒单",
-        "tags": [],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ]
-      }
-    },
-    "/api/admin/decline-contests/:orderId/resolve": {
-      "post": {
-        "summary": "仲裁员裁决",
-        "tags": [],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ]
-      }
-    },
     "/api/admin/direct-receive/aml-flags": {
       "post": {
         "summary": "POST /api/admin/direct-receive/aml-flags",
@@ -1035,6 +1013,20 @@
         ]
       }
     },
+    "/api/admin/disputes/:id/decline-contest-resolve": {
+      "post": {
+        "summary": "(dispute CAS + COI + 终态 completed + 结算 + 审计,单事务全回滚)。admin override 不占用 assigned_arbitrators。",
+        "tags": [
+          "admin",
+          "dispute"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/admin/economic-summary": {
       "get": {
         "summary": "隐私第一：运营财务，仅 protocol admin 可见。",
@@ -2764,6 +2756,48 @@
         "security": []
       }
     },
+    "/api/agent/orders": {
+      "get": {
+        "summary": "买家地址/联系/gift_recipient 连取都不取(I6)。纯只读,无任何执行(order_action_request 在 PR2/PR3 才有提交/执行)。",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "grantBearer": []
+          }
+        ],
+        "x-webaz-grant-scope": "seller_orders_read_minimal"
+      }
+    },
+    "/api/agent/orders/:id": {
+      "get": {
+        "summary": "GET /api/agent/orders/:id",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "grantBearer": []
+          }
+        ],
+        "x-webaz-grant-scope": "seller_orders_read_minimal"
+      }
+    },
+    "/api/agent/orders/:orderId/action-request": {
+      "post": {
+        "summary": "同 (order_id,action) 双 pending 被唯一索引拒。执行(accept/ship)在 PR3 经人 Passkey 批准后由服务端跑。",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "grantBearer": []
+          }
+        ],
+        "x-webaz-grant-scope": "order_action_request"
+      }
+    },
     "/api/agent/seller/products": {
       "get": {
         "summary": "The consumption (allow AND the permission_required deny) is audited by the middleware.",
@@ -3027,6 +3061,17 @@
         ]
       }
     },
+    "/api/arbitrator/pending-count": {
+      "get": {
+        "summary": "非仲裁员返回 0(不报错,前端 badge 拉取对所有人无害)。",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/arbitrator/status": {
       "get": {
         "summary": "GET /api/arbitrator/status",

package/dist/pwa/routes/admin-reports.js

@@ -1,7 +1,9 @@
 import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { resolveDeclineContestDispute } from '../../layer3-trust/L3-1-dispute-engine/decline-contest-resolve.js'; // PR3 唯一裁决器(admin fallback 入口)
+import { notifyDeclineContestResolved } from '../../layer2-business/L2-6-notifications/notification-engine.js';
 export function registerAdminReportsRoutes(app, deps) {
-    // db 已全量走 RFC-016 异步 seam(dbOne/dbAll),不再直接用 deps.db
-    const { requireContentAdmin, requireArbitrationAdmin, requireProtocolAdmin } = deps;
+    // 读表盘走 RFC-016 异步 seam(dbOne/dbAll);唯一例外 = decline-contest 裁决器需 sync db.transaction(domain 层),用 deps.db。
+    const { db, requireContentAdmin, requireArbitrationAdmin, requireProtocolAdmin, requireHumanPresence } = deps;
     app.get('/api/admin/orders', async (req, res) => {
         const admin = requireContentAdmin(req, res);
         if (!admin)
@@ -42,6 +44,7 @@ export function registerAdminReportsRoutes(app, deps) {
         const rail = typeof req.query.rail === 'string' ? req.query.rail.trim() : '';
         const where = [];
         const params = [];
+        // PR2:decline_contest 现进入 admin 监督台(前端按 dispute_type 打"拒单举证仲裁"标签)。
         if (status) {
             where.push('d.status = ?');
             params.push(status);
@@ -51,7 +54,7 @@ export function registerAdminReportsRoutes(app, deps) {
             params.push(rail);
         }
         const rows = await dbAll(`
-      SELECT d.id, d.order_id, d.initiator_id, d.defendant_id, d.reason, d.status,
+      SELECT d.id, d.order_id, d.initiator_id, d.defendant_id, d.reason, d.status, d.dispute_type,
              d.created_at, d.respond_deadline, d.arbitrate_deadline, d.resolved_at,
              d.verdict, d.ruling_type, d.assigned_arbitrators,
              u1.name as initiator_name, u2.name as defendant_name,
@@ -68,6 +71,40 @@ export function registerAdminReportsRoutes(app, deps) {
         const counts = await dbAll('SELECT status, COUNT(*) n FROM disputes GROUP BY status');
         res.json({ disputes: rows, counts: Object.fromEntries(counts.map(c => [c.status, c.n])), total: counts.reduce((s, c) => s + c.n, 0) });
     });
+    // PR3 admin fallback:仲裁窗口(arbitrate_deadline)过后,仲裁 admin 可 override 裁决卡住的拒单举证仲裁。
+    //   §3 仲裁员优先(窗口未过 → resolver 抛 FALLBACK_TOO_EARLY);走【与仲裁员完全相同】的唯一 resolver
+    //   (dispute CAS + COI + 终态 completed + 结算 + 审计,单事务全回滚)。admin override 不占用 assigned_arbitrators。
+    app.post('/api/admin/disputes/:id/decline-contest-resolve', async (req, res) => {
+        const admin = requireArbitrationAdmin(req, res);
+        if (!admin)
+            return;
+        const { decision, reason } = (req.body ?? {});
+        if (decision !== 'decline_no_fault_upheld' && decision !== 'decline_fault_confirmed')
+            return void res.status(400).json({ error: "decision 必须为 'decline_no_fault_upheld' / 'decline_fault_confirmed'", error_code: 'BAD_DECISION' });
+        if (!reason || !String(reason).trim())
+            return void res.status(400).json({ error: '请提供裁决理由', error_code: 'REASON_REQUIRED' });
+        // Passkey purpose_data 绑 dispute_id + action + decision —— 钱路/状态闭环动作,fail-closed:
+        //   token 必须【显式绑定】本案 + 本动作 + 本结果。绝不允许 null(未绑定 token)或缺字段通过,否则一个泛化的
+        //   arbitrate token 就能对任意过期 decline-contest 触发退款/罚没/completed。
+        const hp = requireHumanPresence(admin.id, 'arbitrate', req.body?.webauthn_token, 'require_human_presence_for_arbitrate', (data) => {
+            const d = data;
+            return d != null && typeof d === 'object' && d.dispute_id === req.params.id && d.action === 'decline_contest_resolve' && d.decision === decision;
+        });
+        if (!hp.ok)
+            return void res.status(412).json({ error: hp.reason || '此操作需真实人工 WebAuthn 验证', error_code: hp.error_code || 'HUMAN_PRESENCE_REQUIRED' });
+        try {
+            const r = resolveDeclineContestDispute(db, req.params.id, admin.id, decision, reason, 'admin_fallback');
+            try {
+                notifyDeclineContestResolved(db, r.orderId, r.decision);
+            }
+            catch { /* 通知失败不影响已完成结算 */ }
+            return void res.json({ success: true, outcome: r.decision, order_status: 'completed', source: 'admin_fallback' });
+        }
+        catch (e) {
+            const err = e;
+            return void res.status(err.http || 400).json({ error: err.message || '裁决失败', error_code: err.code || 'DC_RESOLVE_FAILED' });
+        }
+    });
     app.get('/api/admin/verify-tasks', async (req, res) => {
         const admin = requireArbitrationAdmin(req, res);
         if (!admin)

package/dist/pwa/routes/agent-grants.js

@@ -1,9 +1,13 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
 import { initAgentDelegationGrantsSchema, initAgentPairingSchema, initAgentGrantAuthLogSchema, initAgentPermissionRequestsSchema } from '../../runtime/webaz-schema-helpers.js';
-import { validateRequestedCapabilities, clampTtlSeconds, grantIsActive, resolveBundle, durationAllowedForScopes, suggestedDurationForScopes, durationToSeconds, riskLevelForScopes } from '../../runtime/agent-grant-scopes.js';
+import { validateRequestedCapabilities, grantIsActive, resolveBundle, durationAllowedForScopes, suggestedDurationForScopes, allowedDurationsForScopes, durationToSeconds, riskLevelForScopes } from '../../runtime/agent-grant-scopes.js';
 import { generateUserCode, verifyPkceS256, clampPairingTtlSeconds, pairingApprovable, pairingRetrievable } from '../../runtime/agent-pairing.js';
 import { verifyGrantToken } from '../../runtime/agent-grant-verifier.js';
+import { minimalSellerOrderView, MINIMAL_ORDER_COLUMNS } from '../agent-order-minimal-view.js'; // RFC-021 §6a 最小化订单读投影
+import { createOrderActionRequest } from '../order-action-request.js'; // RFC-021 PR2 order-action 请求 domain(sync tx 在 domain 层,不增 route seam)
+import { approveAndExecuteOrderAction } from '../order-action-exec.js'; // RFC-021 PR3 approve→执行(CAS approved + 执行 + executed_at CAS,domain 层)
+import { notifyTransition } from '../../layer2-business/L2-6-notifications/notification-engine.js'; // 执行后通知买卖双方
 // Bounds on a pairing request (anti-bloat for the anonymous start endpoint).
 const MAX_CAPABILITIES = 12;
 const MAX_CONSTRAINTS_JSON = 2000;
@@ -28,7 +32,10 @@ function consentView(p) {
         capabilities: safeParseCaps(p.capabilities), // server-validated safe scopes
         status: p.status,
         expires_at: p.expires_at,
-        notice: 'Approving issues a scoped, short-lived, revocable delegation grant — NOT your api_key, NOT your funds. Safe (read/draft) scopes only; it can never move money, vote, arbitrate, or change keys.',
+        // Duration-choice: agent's suggested lifetime + the durations the human may pick (safe scopes → up to 30d).
+        suggested_duration: p.grant_duration || suggestedDurationForScopes(safeParseCaps(p.capabilities).map(c => String(c?.capability || '')).filter(Boolean)),
+        allowed_durations: allowedDurationsForScopes(safeParseCaps(p.capabilities).map(c => String(c?.capability || '')).filter(Boolean)),
+        notice: 'Approving issues a scoped, revocable delegation grant — NOT your api_key, NOT your funds. Safe (read/draft) scopes only; it can never move money, vote, arbitrate, or change keys. You choose how long it lasts.',
     };
 }
 export function registerAgentGrantsRoutes(app, deps) {
@@ -117,6 +124,33 @@ export function registerAgentGrantsRoutes(app, deps) {
         const rows = await dbAll("SELECT id, title, status, price, currency, stock, category, created_at, updated_at FROM products WHERE seller_id = ? AND status != 'deleted' ORDER BY created_at DESC LIMIT 200", [p.human_id]);
         res.json({ seller_id: p.human_id, agent_label: p.agent_label, count: rows.length, products: rows, note: 'Seller-owned catalog read via delegation grant (safe scope seller_products_read). Read-only; no money/commission fields.' });
     });
+    // RFC-021 §6a — 最小化订单读(safe scope seller_orders_read_minimal)。仅读该 agent 之人(卖家)的订单;
+    //   ALLOWLIST 投影(minimalSellerOrderView)只产出 6 字段,SELECT 只取非 PII 列(MINIMAL_ORDER_COLUMNS) ——
+    //   买家地址/联系/gift_recipient 连取都不取(I6)。纯只读,无任何执行(order_action_request 在 PR2/PR3 才有提交/执行)。
+    app.get('/api/agent/orders', requireAgentGrantScope('seller_orders_read_minimal'), async (req, res) => {
+        const p = req.agentGrant;
+        const rows = await dbAll(`SELECT ${MINIMAL_ORDER_COLUMNS.join(', ')} FROM orders WHERE seller_id = ? ORDER BY created_at DESC LIMIT 200`, [p.human_id]);
+        res.json({ seller_id: p.human_id, agent_label: p.agent_label, count: rows.length, orders: rows.map(o => minimalSellerOrderView(o, db)), note: 'RFC-021 minimal order read (safe scope seller_orders_read_minimal). No buyer address/contact; no execution.' });
+    });
+    app.get('/api/agent/orders/:id', requireAgentGrantScope('seller_orders_read_minimal'), async (req, res) => {
+        const p = req.agentGrant;
+        const o = await dbOne(`SELECT ${MINIMAL_ORDER_COLUMNS.join(', ')} FROM orders WHERE id = ? AND seller_id = ?`, [req.params.id, p.human_id]);
+        if (!o)
+            return void res.status(404).json({ error: '订单不存在或不属于你', error_code: 'ORDER_NOT_FOUND' });
+        res.json({ order: minimalSellerOrderView(o, db) });
+    });
+    // RFC-021 PR2 — order-action 请求提交(safe scope order_action_request)。SUBMIT-only:写 pending,【绝不执行】。
+    //   D2 拒 decline;归属校验 seller 本人;ship 须带 tracking+evidence_ref(I4 提交侧);地址永不入参/入 audit(I6);
+    //   同 (order_id,action) 双 pending 被唯一索引拒。执行(accept/ship)在 PR3 经人 Passkey 批准后由服务端跑。
+    app.post('/api/agent/orders/:orderId/action-request', requireAgentGrantScope('order_action_request'), async (req, res) => {
+        const p = req.agentGrant;
+        const b = (req.body ?? {});
+        const orderId = String(req.params.orderId);
+        const r = createOrderActionRequest(db, { orderId, action: String(b.action ?? ''), rawParams: b.action_params, grantId: p.grant_id, humanId: p.human_id, agentLabel: p.agent_label, generateId });
+        if (!r.ok)
+            return void res.status(r.http || 400).json({ error: r.error, error_code: r.error_code });
+        res.json({ success: true, request_id: r.request_id, order_id: orderId, action: b.action, params_hash: r.params_hash, approval_url: '/#agent-approvals', note: 'Pending human Passkey approval. NOT executed — execution (accept/ship) lands in RFC-021 PR3.' });
+    });
     // POST create a DRAFT product via a delegation grant (Catalog Agent, safe scope seller_product_draft). The
     //   draft is FORCED to status='warehouse' (not public/sellable). PUBLISHING STAYS HUMAN-ONLY — the human
     //   flips warehouse→active in the existing 我的商品→仓库 UI (publish is never delegated to a grant, matching
@@ -129,6 +163,19 @@ export function registerAgentGrantsRoutes(app, deps) {
             const human = await dbOne('SELECT id, role FROM users WHERE id = ?', [p.human_id]);
             if (!human || human.role !== 'seller')
                 return void res.status(403).json({ error: 'the grant owner is not a seller — product drafts need a seller account', error_code: 'NOT_A_SELLER' });
+            // Accurate error codes for the GRANT path WITHOUT touching the shared handler / human path: the create
+            //   handler emits legacy validation errors as `200 + {error}` (no success). For a grant caller that's
+            //   misleading, so translate exactly those to `400 VALIDATION_ERROR`. Explicit res.status(400/429/500…)
+            //   and the success ({product_id}) response pass through unchanged.
+            const origJson = res.json.bind(res);
+            res.json = (body) => {
+                const b = body;
+                if (res.statusCode === 200 && b && typeof b === 'object' && b.error && !b.success) {
+                    res.status(400);
+                    return origJson({ error: b.error, error_code: 'VALIDATION_ERROR' });
+                }
+                return origJson(body);
+            };
             await createProductDraftHandler(req, res, human, {
                 forceStatus: 'warehouse',
                 skipExternalLinkEffects: true, // a SAFE draft grant must never trigger wallet debit / verify_tasks / auto-verified links (source_url stays inert metadata)
@@ -211,8 +258,21 @@ export function registerAgentGrantsRoutes(app, deps) {
         const user = auth(req, res);
         if (!user)
             return;
-        const rows = await dbAll("SELECT id, agent_label, requested_scopes, permission_bundle, reason, task_context, risk_level, duration, created_at, expires_at FROM agent_permission_requests WHERE human_id = ? AND status = 'pending' AND expires_at > ? ORDER BY created_at DESC LIMIT 100", [user.id, new Date().toISOString()]);
-        res.json({ requests: rows.map(r => ({ ...r, requested_scopes: scopeNames(String(r.requested_scopes)), human_summary: bundleSummary(r.permission_bundle) })) });
+        const rows = await dbAll("SELECT id, agent_label, requested_scopes, permission_bundle, reason, task_context, risk_level, duration, created_at, expires_at, kind, order_id, order_action, params_hash, action_params FROM agent_permission_requests WHERE human_id = ? AND status = 'pending' AND expires_at > ? ORDER BY created_at DESC LIMIT 100", [user.id, new Date().toISOString()]);
+        // order_action:额外返回 kind/order_id/order_action/params_hash/action_params(action_params 经 PR2 sanitize,
+        //   只含 tracking/evidence_ref,【无地址/PII】)。前端据此绑 Passkey purpose_data {request_id, order_id, action, params_hash}。
+        res.json({ requests: rows.map(r => {
+                const base = { ...r, requested_scopes: scopeNames(String(r.requested_scopes)), human_summary: bundleSummary(r.permission_bundle) };
+                if (r.kind === 'order_action') {
+                    try {
+                        base.action_params = r.action_params ? JSON.parse(String(r.action_params)) : {};
+                    }
+                    catch {
+                        base.action_params = {};
+                    }
+                }
+                return base;
+            }) });
     });
     // GET list the requests THIS grant created — GRANT-authed (the agent, via webaz_pair), so an agent can poll
     //   its own request status (pending/approved/rejected/expired) without hitting the target surface. Bound to
@@ -238,11 +298,34 @@ export function registerAgentGrantsRoutes(app, deps) {
         if (!user)
             return;
         const now = new Date().toISOString();
-        const r = await dbOne('SELECT human_id, grant_id, requested_scopes, permission_bundle, duration, status, expires_at FROM agent_permission_requests WHERE id = ?', [req.params.id]);
+        const r = await dbOne('SELECT human_id, grant_id, requested_scopes, permission_bundle, duration, status, expires_at, kind, order_id, order_action, params_hash FROM agent_permission_requests WHERE id = ?', [req.params.id]);
         if (!r)
             return void res.status(404).json({ error: 'permission_request_not_found' });
         if (r.human_id !== user.id)
             return void res.status(403).json({ error: 'not your permission request' });
+        // RFC-021 PR2:order-action 请求分流。Passkey 绑三元组 (order_id, action, params_hash)(对齐 admin fallback 严格绑定);
+        //   过期/pending 判定【原子在 domain 的 CAS 里】(P1-b,含 expires_at > now),不做两步式预检查。
+        //   批到 approved 就【停】—— 绝不执行、不改订单、不碰钱路(execute 在 PR3)。
+        if ((r.kind ?? 'scope_grant') === 'order_action') {
+            const hp = requireHumanPresence(user.id, 'agent_permission_approve', (req.body || {}).webauthn_token, 'require_human_presence_for_agent_permission_approve', (data) => { const d = data; return d != null && typeof d === 'object' && d.request_id === req.params.id && d.order_id === r.order_id && d.action === r.order_action && d.params_hash === r.params_hash; });
+            if (!hp.ok)
+                return void res.status(412).json({ error: hp.reason, error_code: hp.error_code });
+            // PR3:CAS→approved 后【由服务端在 seller 本人授权下执行】accept/ship(strictTracking=true,守卫全在执行器内)。
+            //   执行成功写 executed_at(I5 幂等);执行失败请求保持 approved 可重试。执行器对 agent-bearer 不可达(/approve 需人类 session)。
+            const ar = approveAndExecuteOrderAction(db, req.params.id, user.id, r.grant_id, now, generateId);
+            if (!ar.ok)
+                return void res.status(ar.http || 409).json({ error: ar.error, error_code: ar.error_code });
+            // 执行成功后通知买卖双方(事务外;通知失败不回滚已完成的状态跃迁)
+            if (!ar.already_executed && ar.order_status) {
+                try {
+                    const fromS = ar.order_status === 'accepted' ? 'paid' : 'accepted';
+                    notifyTransition(db, r.order_id, fromS, ar.order_status);
+                }
+                catch { /* */ }
+            }
+            return void res.json({ success: true, kind: 'order_action', status: 'executed', order_id: r.order_id, action: r.order_action, order_status: ar.order_status, already_executed: ar.already_executed || false });
+        }
+        // scope_grant:保留既有两步(下方还有 grant-active 复检 + 原子 tx;非 order-action)。
         if (r.status !== 'pending' || r.expires_at <= now)
             return void res.status(409).json({ error: 'permission_request_not_pending', status: r.status });
         // Live Passkey, bound to THIS request (a token minted for request A can't approve B).
@@ -264,9 +347,17 @@ export function registerAgentGrantsRoutes(app, deps) {
         const grant = await dbOne('SELECT grant_id, capabilities, status, expires_at, revoked_at FROM agent_delegation_grants WHERE grant_id = ?', [r.grant_id]);
         if (!grant || !grantIsActive(grant, now))
             return void res.status(409).json({ error: 'grant_inactive', error_code: 'GRANT_INACTIVE', note: 'the agent grant expired or was revoked; re-pair (this request stays pending)' });
-        // Union new scopes into the grant; set bundle; extend expiry (never shorten). 'once' → short 1h window.
+        // Duration: the HUMAN's submitted value is authoritative. If body.duration is PRESENT but not allowed →
+        //   400 (no silent fallback; nothing claimed/expanded below). Only when ABSENT do we fall back to the
+        //   agent's requested duration. Checked BEFORE the tx so an invalid value never claims/extends anything.
+        const bodyDur = (req.body || {}).duration;
+        if (bodyDur !== undefined && bodyDur !== null && !durationAllowedForScopes(reqScopes, bodyDur)) {
+            return void res.status(400).json({ error: 'invalid grant duration', error_code: 'INVALID_GRANT_DURATION', allowed_durations: allowedDurationsForScopes(reqScopes) });
+        }
+        // Union new scopes into the grant; set bundle; extend expiry (never shorten).
         const union = [...new Set([...scopeNames(grant.capabilities), ...reqScopes])].map(s => ({ capability: s, constraints: {} }));
-        const secs = durationToSeconds(r.duration) || 3600;
+        const effDuration = (bodyDur !== undefined && bodyDur !== null) ? bodyDur : r.duration;
+        const secs = durationToSeconds(effDuration) || 3600;
         const newExpiry = new Date(Date.now() + secs * 1000).toISOString();
         const expiresAt = newExpiry > grant.expires_at ? newExpiry : grant.expires_at;
         // ATOMIC (RFC-020 invariant: a grant expansion is audited-or-it-does-not-happen; parity with arbitrator
@@ -294,7 +385,7 @@ export function registerAgentGrantsRoutes(app, deps) {
         }
         if (outcome === 'not_pending')
             return void res.status(409).json({ error: 'permission_request_not_pending' });
-        res.json({ success: true, grant_id: grant.grant_id, scopes: union.map(u => u.capability), permission_bundle: r.permission_bundle, expires_at: expiresAt });
+        res.json({ success: true, grant_id: grant.grant_id, scopes: union.map(u => u.capability), permission_bundle: r.permission_bundle, duration: effDuration, expires_at: expiresAt });
     });
     // POST reject — human-authed. Terminal 'rejected'; nothing is granted.
     app.post('/api/agent-grants/permission-requests/:id/reject', async (req, res) => {
@@ -341,13 +432,17 @@ export function registerAgentGrantsRoutes(app, deps) {
         const capsJson = JSON.stringify(v.safe.map(c => ({ capability: c, constraints: (caps.find(x => x?.capability === c)?.constraints) || {} })));
         if (capsJson.length > MAX_CONSTRAINTS_JSON)
             return void res.status(400).json({ error: 'capabilities_too_large', max_bytes: MAX_CONSTRAINTS_JSON });
-        await dbRun('INSERT INTO agent_pairing_sessions (pairing_id, user_code, code_challenge, agent_label, agent_pubkey, reason, capabilities, status, expires_at) VALUES (?,?,?,?,?,?,?,?,?)', [pairingId, userCode, codeChallenge, label, pubkey, reason, capsJson, 'pending', expiresAt]);
+        // Agent SUGGESTS a grant lifetime; the human accepts or overrides it at approve. Safe-scope only → up to 30d.
+        const reqDuration = durationAllowedForScopes(v.safe, body.duration) ? body.duration : suggestedDurationForScopes(v.safe);
+        await dbRun('INSERT INTO agent_pairing_sessions (pairing_id, user_code, code_challenge, agent_label, agent_pubkey, reason, capabilities, grant_duration, status, expires_at) VALUES (?,?,?,?,?,?,?,?,?,?)', [pairingId, userCode, codeChallenge, label, pubkey, reason, capsJson, reqDuration, 'pending', expiresAt]);
         res.status(201).json({
             pairing_id: pairingId,
             user_code: userCode,
             approve_url: `/#pair?code=${userCode}`,
             expires_at: expiresAt,
-            note: 'Ask the human to open approve_url at webaz.xyz (logged in) and approve. Then retrieve the credential with the PKCE verifier.',
+            suggested_duration: reqDuration,
+            allowed_durations: allowedDurationsForScopes(v.safe),
+            note: 'Ask the human to open approve_url at webaz.xyz (logged in) and approve. The human picks the grant duration (your suggested_duration is pre-selected; they can change it). Then retrieve the credential with the PKCE verifier.',
         });
     });
     // (pair 2) Human reviews the server-generated consent — human-authenticated.
@@ -390,7 +485,17 @@ export function registerAgentGrantsRoutes(app, deps) {
         if (!v.ok)
             return void res.status(403).json({ error: 'pairing_rejected', rejected: v.rejected });
         const grantId = generateId('grt');
-        const expiresAt = new Date(Date.now() + clampTtlSeconds(undefined) * 1000).toISOString();
+        // Duration: the HUMAN's submitted value is authoritative. If body.duration is PRESENT but not in the
+        //   safe-scope matrix → 400 (no silent fallback; nothing claimed/issued below). Only when ABSENT do we
+        //   fall back to the agent's suggestion (grant_duration) then the safe default.
+        const bodyDur = (req.body || {}).duration;
+        if (bodyDur !== undefined && bodyDur !== null && !durationAllowedForScopes(v.safe, bodyDur)) {
+            return void res.status(400).json({ error: 'invalid grant duration', error_code: 'INVALID_GRANT_DURATION', allowed_durations: allowedDurationsForScopes(v.safe) });
+        }
+        const chosenDuration = (bodyDur !== undefined && bodyDur !== null)
+            ? bodyDur
+            : (durationAllowedForScopes(v.safe, p.grant_duration) ? p.grant_duration : suggestedDurationForScopes(v.safe));
+        const expiresAt = new Date(Date.now() + (durationToSeconds(chosenDuration) || 3600) * 1000).toISOString();
         // 先【CAS 抢占】pending 配对(唯一赢家),再插 grant —— 竞态下输家 changes!==1 直接 409、不插任何 grant,
         //   杜绝"插了 grant 但配对更新失败"留下 token_hash NULL 的 orphan grant(污染连接记录)。
         const claimed = await dbRun("UPDATE agent_pairing_sessions SET status='approved', human_id=?, grant_id=?, approved_at=? WHERE user_code=? AND status='pending'", [user.id, grantId, now, req.params.user_code]);
@@ -398,7 +503,7 @@ export function registerAgentGrantsRoutes(app, deps) {
             return void res.status(409).json({ error: 'pairing_not_pending_or_expired' });
         // Grant created WITHOUT a token (token_hash NULL) — the bearer is minted only at retrieval.
         await dbRun('INSERT INTO agent_delegation_grants (grant_id, human_id, agent_label, capabilities, token_hash, human_confirm_required, status, expires_at) VALUES (?,?,?,?,?,?,?,?)', [grantId, user.id, p.agent_label || null, JSON.stringify(caps), null, 0, 'active', expiresAt]);
-        res.json({ success: true, grant_id: grantId, capabilities: caps });
+        res.json({ success: true, grant_id: grantId, capabilities: caps, duration: chosenDuration, expires_at: expiresAt });
     });
     // (pair 3b) Human rejects — human-authenticated. Terminal 'rejected' → agent's retrieve fails clearly (no silent lingering).
     //   拒绝是保护性动作,无需 Passkey(不签发任何凭证)。幂等:仅 pending 可拒。

package/dist/pwa/routes/disputes-read.js

@@ -1,4 +1,5 @@
 import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { getRecentResolvedDisputes } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js'; // 历史裁决(已结)供仲裁员"已结"tab
 export function registerDisputesReadRoutes(app, deps) {
     const { db, auth, errorRes, getOpenDisputes, getDisputeDetails, getEvidenceRequests, listEvidenceFiles, isEligibleArbitrator, isArbitrationAdmin } = deps;
     // 仲裁员：查看所有开放争议
@@ -9,7 +10,22 @@ export function registerDisputesReadRoutes(app, deps) {
         const elig = isEligibleArbitrator(user.id);
         if (!elig.ok)
             return void errorRes(res, 403, 'NOT_ARBITRATOR', elig.reason || '仅限仲裁员访问');
-        res.json(await getOpenDisputes(db));
+        // 待裁(open+in_review)+ 近期已结(resolved/dismissed)—— 前端"待裁/已结"sub-tab 客户端切分;
+        //   getOpenDisputes 语义不变(MCP 复用),历史走 getRecentResolvedDisputes(LIMIT 50)。
+        const open = await getOpenDisputes(db);
+        const resolved = await getRecentResolvedDisputes(db, 50);
+        res.json([...open, ...resolved]);
+    });
+    // PR2 统一仲裁台待办角标:仲裁员待处理案数(open+in_review,含并入的 decline_contest)。轻量 count,喂前端 badge。
+    //   非仲裁员返回 0(不报错,前端 badge 拉取对所有人无害)。
+    app.get('/api/arbitrator/pending-count', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (!isEligibleArbitrator(user.id).ok)
+            return void res.json({ count: 0 });
+        const row = await dbOne("SELECT COUNT(*) n FROM disputes WHERE status IN ('open','in_review')");
+        res.json({ count: row?.n ?? 0 });
     });
     // A2 同类判例推荐
     app.get('/api/disputes/:id/similar-cases', async (req, res) => {

package/dist/pwa/routes/disputes-write.js

@@ -1,14 +1,14 @@
 import express from 'express';
-// RFC-007 stage 5：客观拒单仲裁翻案直接复用 L0 状态机/结算(纯 db 函数,无副作用)
-import { transition, settleFault, settleDeclinedNoFault } from '../../layer0-foundation/L0-2-state-machine/engine.js';
 // RFC-014 PR5 — 争议后佣金/基金 clawback 走整数 base-units + 绝对值落库。
 import { toUnits, toDecimal, mulRate } from '../../money.js';
 import { applyWalletDelta } from '../../ledger.js';
 // RFC-016 Phase 1 — 纯只读端点/校验读/SNF 分发读/标记写 → async seam;arbitrate 仲裁核心(原子领取 +
 //   2 settlement db.transaction + reputation/strike/publish)与 tx 内 appendAuditLog 保持同步(Phase 3 迁 pg)。
-import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
+import { dbOne, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
 import { arbitratorHasConflict } from '../arbitrator-lifecycle.js'; // PR-B COI 硬门
 import { dismissDisputeToNegotiation } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js'; // 仲裁员驳回仲裁,退回协商(非胜负裁决)
+import { resolveDeclineContestDispute } from '../../layer3-trust/L3-1-dispute-engine/decline-contest-resolve.js'; // PR3 拒单举证唯一裁决器
+import { notifyDeclineContestResolved } from '../../layer2-business/L2-6-notifications/notification-engine.js'; // 裁决落定通知买卖双方
 export function registerDisputesWriteRoutes(app, deps) {
     const { db, auth, generateId, detectFraud, errorRes, isEligibleArbitrator, requireHumanPresence, getDisputeDetails, respondToDispute, arbitrateDispute, addPartyEvidence, requestEvidence, markEvidenceExpiry, uploadEvidence, EVIDENCE_MAX_BYTES, EVIDENCE_ALLOWED_MIME, appendOrderEvent, FUND_BASE_RATE, settleCommission, depositToFund, calculatePv, recordDisputeReputation, issueAgentStrike, publishDisputeCase, logAdminAction, snfSend, getProtocolParam, notifyTransition } = deps;
     // PR-E:案件级仲裁操作(裁定 / 补证)统一的【原子领取或校验指派】。assigned 为空 → CAS 首位领取;
@@ -34,72 +34,10 @@ export function registerDisputesWriteRoutes(app, deps) {
         }
         return assigned.includes(userId) ? { ok: true } : { ok: false, error_code: 'NOT_ASSIGNED_ARBITRATOR' };
     };
-    // ── RFC-007 stage 5：客观拒单【临时判责】的仲裁翻案 ─────────────────────────────
-    //   卖家 contest_decline 后,订单 = fault_seller + decline_objective_pending=1 + decline_contested=1(未结算)。
-    //   仲裁员(真实人工 + WebAuthn)裁决:uphold → declined_nofault(免责全退+退质押);reject → 违约结算。
-    const SYS = 'sys_protocol';
-    // 仲裁员待办:列出所有被举证的临时判责拒单
-    app.get('/api/admin/decline-contests', async (req, res) => {
-        const user = auth(req, res);
-        if (!user)
-            return;
-        const elig = isEligibleArbitrator(user.id);
-        if (!elig.ok)
-            return void errorRes(res, 403, 'NOT_ARBITRATOR', elig.reason || '仅限仲裁员');
-        const rows = await dbAll(`
-      SELECT id AS order_id, buyer_id, seller_id, product_id, total_amount, decline_reason_code, declined_at, decline_contest_deadline
-      FROM orders
-      WHERE status = 'fault_seller' AND COALESCE(decline_objective_pending,0)=1 AND COALESCE(decline_contested,0)=1 AND settled_fault_at IS NULL
-      ORDER BY declined_at ASC
-    `);
-        res.json({ contests: rows });
-    });
-    // 仲裁员裁决
-    app.post('/api/admin/decline-contests/:orderId/resolve', async (req, res) => {
-        const user = auth(req, res);
-        if (!user)
-            return;
-        const elig = isEligibleArbitrator(user.id);
-        if (!elig.ok)
-            return void errorRes(res, 403, 'NOT_ARBITRATOR', elig.reason || '仅限仲裁员');
-        // 铁律:仲裁需真实人工 WebAuthn
-        const hp = requireHumanPresence(user.id, 'arbitrate', req.body?.webauthn_token, 'require_human_presence_for_arbitrate');
-        if (!hp.ok)
-            return void errorRes(res, 412, hp.error_code || 'HUMAN_PRESENCE_REQUIRED', hp.reason || '此操作需真实人工 WebAuthn 验证');
-        const { decision, reason } = req.body ?? {};
-        if (!['uphold', 'reject'].includes(decision))
-            return void errorRes(res, 400, 'BAD_DECISION', "decision 必须为 'uphold'(认定无责) 或 'reject'(驳回,判违约)");
-        if (!reason || !String(reason).trim())
-            return void errorRes(res, 400, 'REASON_REQUIRED', '请提供裁决理由');
-        const order = await dbOne('SELECT * FROM orders WHERE id = ?', [req.params.orderId]);
-        if (!order)
-            return void res.status(404).json({ error: '订单不存在' });
-        if (order.status !== 'fault_seller' || Number(order.decline_objective_pending) !== 1 || Number(order.decline_contested) !== 1 || order.settled_fault_at) {
-            return void errorRes(res, 400, 'NOT_CONTESTED_PROVISIONAL', '本订单不是【已举证·待裁决】的临时判责拒单');
-        }
-        try {
-            appendOrderEvent(db, { orderId: req.params.orderId, eventType: 'transition', fromStatus: 'fault_seller', toStatus: 'fault_seller', actorId: user.id, actorRole: 'arbitrator', extra: { action: 'decline_contest_ruling', decision, reason } });
-        }
-        catch (e) {
-            console.warn('[order-chain] decline ruling event:', e.message);
-        }
-        if (decision === 'uphold') {
-            // 认定客观无责 → declined_nofault：全退买家 + 退卖家质押,零罚没
-            const r1 = transition(db, req.params.orderId, 'declined_nofault', user.id, [], `客观拒单仲裁维持(无责)：${reason}`);
-            if (!r1.success)
-                return void res.json({ error: r1.error });
-            settleDeclinedNoFault(db, req.params.orderId);
-            transition(db, req.params.orderId, 'completed', SYS, [], '无责拒单结算完成');
-            logAdminAction(user.id, 'decline_contest_uphold', 'order', req.params.orderId, { reason });
-            return void res.json({ success: true, outcome: 'declined_nofault', note: '裁决:客观无责。买家已全额退款,卖家质押已退回,无罚没。' });
-        }
-        // reject → 违约结算(终结临时判责)
-        settleFault(db, req.params.orderId, 'fault_seller');
-        transition(db, req.params.orderId, 'completed', SYS, [], `客观拒单仲裁驳回 → 违约结算：${reason}`);
-        db.prepare('UPDATE orders SET decline_objective_pending = 0, decline_contested = 0 WHERE id = ?').run(req.params.orderId);
-        logAdminAction(user.id, 'decline_contest_reject', 'order', req.params.orderId, { reason });
-        res.json({ success: true, outcome: 'fault_seller', note: '裁决:驳回。按违约结算,买家已全额退款,卖家质押按规则罚没。' });
-    });
+    // RFC-007 客观拒单举证仲裁已并入统一 disputes 仲裁台(PR1-3,#279-#281):dispute_type='decline_contest'。
+    //   旧订单级 GET /api/admin/decline-contests 列表 + POST .../:orderId/resolve 裁决端点【已物理移除】(PR4)。
+    //   现统一走:仲裁员 POST /api/disputes/:id/arbitrate(ruling=decline_no_fault_upheld|decline_fault_confirmed);
+    //   admin 兜底 POST /api/admin/disputes/:id/decline-contest-resolve;两者都经唯一 resolveDeclineContestDispute。
     // 被诉方反驳
     app.post('/api/disputes/:id/respond', async (req, res) => {
         const user = auth(req, res);
@@ -132,9 +70,15 @@ export function registerDisputesWriteRoutes(app, deps) {
         const elig = isEligibleArbitrator(user.id);
         if (!elig.ok)
             return void errorRes(res, 403, 'NOT_ARBITRATOR', elig.reason || '仅限仲裁员');
-        // 2026-05-23 Agent 治理铁律：仲裁需真实人工
+        // 2026-05-23 Agent 治理铁律：仲裁需真实人工。
+        //   decline_contest 两选裁决 = 钱路/状态闭环(退款/罚没/completed)→ 与 admin fallback 一致 fail-closed:
+        //   token 必须【显式绑定】本案 dispute_id + 本结果 decision,绝不允许 null/未绑定的泛化 arbitrate token 跨案裁决。
+        //   通用争议维持既有(d==null 允许);resolver 只对两选 ruling 执行,故钱路仅在严格绑定时可达。
+        const _dcRuling = req.body?.ruling === 'decline_no_fault_upheld' || req.body?.ruling === 'decline_fault_confirmed';
         const hpCheck = requireHumanPresence(user.id, 'arbitrate', req.body?.webauthn_token, 'require_human_presence_for_arbitrate', (data) => {
             const d = data;
+            if (_dcRuling)
+                return d != null && typeof d === 'object' && d.dispute_id === req.params.id && d.decision === req.body?.ruling;
             return d == null || d.dispute_id === req.params.id;
         });
         if (!hpCheck.ok)
@@ -142,6 +86,34 @@ export function registerDisputesWriteRoutes(app, deps) {
         const { ruling, reason, refund_amount, liable_party_id, liability_parties } = req.body;
         if (!ruling || !reason)
             return void res.json({ error: '请提供裁定结果（ruling）和理由（reason）' });
+        // P1-1:先读 dispute,再按 dispute_type 选 ruling allowlist —— 否则 decline_contest 的专用枚举会被通用校验提前 400。
+        const dispute = await getDisputeDetails(db, req.params.id);
+        if (!dispute)
+            return void res.status(404).json({ error: '争议不存在' });
+        // PR3:decline_contest → 唯一 domain resolver(两选;dispute CAS + COI + assignment + 终态 completed + 结算 + 审计,单事务失败全回滚)。
+        if (dispute.dispute_type === 'decline_contest') {
+            const dcAllow = ['decline_no_fault_upheld', 'decline_fault_confirmed'];
+            if (!dcAllow.includes(ruling))
+                return void errorRes(res, 400, 'BAD_DECISION', `拒单举证仲裁的 ruling 必须是 ${dcAllow.join(' / ')} 之一`);
+            try {
+                const r = resolveDeclineContestDispute(db, req.params.id, user.id, ruling, reason, 'arbitrator');
+                try {
+                    notifyDeclineContestResolved(db, r.orderId, r.decision);
+                }
+                catch (e) {
+                    console.warn('[notify] dc-resolve:', e.message);
+                }
+                try {
+                    logAdminAction(user.id, `decline_contest_${r.decision}`, 'order', r.orderId, { source: 'arbitrator', dispute_id: req.params.id, reason });
+                }
+                catch { /* */ }
+                return void res.json({ success: true, outcome: r.decision, order_status: 'completed' });
+            }
+            catch (e) {
+                const err = e;
+                return void errorRes(res, err.http || 400, err.code || 'DC_RESOLVE_FAILED', err.message || '裁决失败');
+            }
+        }
         const validRulings = ['refund_buyer', 'release_seller', 'partial_refund', 'liability_split', 'dismiss_to_negotiation'];
         if (!validRulings.includes(ruling)) {
             return void res.json({ error: `ruling 必须是 ${validRulings.join(' / ')} 之一` });
@@ -156,9 +128,6 @@ export function registerDisputesWriteRoutes(app, deps) {
                 }
             }
         }
-        const dispute = await getDisputeDetails(db, req.params.id);
-        if (!dispute)
-            return void res.status(404).json({ error: '争议不存在' });
         // PR-B COI 硬门:当事方(买家/卖家/物流/发起人/被诉人)不得仲裁本案。在领取/裁定前拦截。
         if (arbitratorHasConflict(db, dispute.order_id, dispute.initiator_id ?? null, dispute.defendant_id ?? null, user.id)) {
             return void res.status(403).json({ error: '你是本案当事方,不可仲裁(利益冲突)', error_code: 'ARBITRATOR_CONFLICT_OF_INTEREST' });