@seasonkoh/webaz 0.1.30 → 0.1.32

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,11 +32,14 @@ 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) {
-    const { db, auth, generateId, rateLimitOk, requireHumanPresence } = deps;
+    const { db, auth, generateId, rateLimitOk, requireHumanPresence, createProductDraftHandler } = deps;
     // PWA runtime self-init (MCP gets the tables via applyWebazRuntimeSchema). Idempotent.
     initAgentDelegationGrantsSchema(db);
     initAgentPairingSchema(db);
@@ -86,7 +93,9 @@ export function registerAgentGrantsRoutes(app, deps) {
                     error: `this action needs the "${scope}" permission, which your grant does not carry`,
                     error_code: 'PERMISSION_REQUIRED',
                     required_scope: scope,
+                    missing_scopes: [scope],
                     approval_url: '/#agent-approvals',
+                    retry_after_approval: true,
                     request_permission: { method: 'POST', endpoint: '/api/agent-grants/permission-requests', body: { scopes: [scope] } },
                     note: 'Ask the human to approve at approval_url; on approval your existing grant is expanded — then retry this request.',
                 });
@@ -115,6 +124,72 @@ 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
+    //   the taxonomy). Reuses the SAME product-create validation as the human POST /api/products
+    //   (createProductDraftHandler) so the agent path can't drift. Audited by the middleware. Lightweight signal:
+    //   a notification tells the human a draft is waiting to review + publish.
+    if (createProductDraftHandler) {
+        app.post('/api/agent/seller/products', requireAgentGrantScope('seller_product_draft'), async (req, res) => {
+            const p = req.agentGrant;
+            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)
+                onCreated: async (productId) => {
+                    try {
+                        await dbRun("INSERT INTO notifications (id, user_id, type, title, body) VALUES (?,?,?,?,?)", [generateId('ntf'), p.human_id, 'agent_product_draft', 'AI 助手起草了商品草稿', `${p.agent_label || 'An agent'} 起草了商品草稿 ${productId}，请到「我的商品 → 仓库」审核并发布。`]);
+                    }
+                    catch (e) {
+                        console.error('[agent-grant draft notify]', e.message);
+                    }
+                },
+            });
+        });
+    }
     // helpers for the permission-request flow ----------------------------------------------------------------
     const parseCapList = (json) => { try {
         const a = JSON.parse(json);
@@ -149,7 +224,7 @@ export function registerAgentGrantsRoutes(app, deps) {
         // Fail closed: a grant-authorized read is audited or it does not proceed (parity with requireAgentGrantScope).
         if (!(await auditGrant(g.grant_id, g.human_id, 'grant:verify', 'allow')))
             return void res.status(503).json({ error: 'authorization audit unavailable; refusing to proceed unaudited', error_code: 'GRANT_AUDIT_FAILED' });
-        res.json({ grant: { grant_id: full.grant_id, agent_label: full.agent_label, scopes: scopeNames(full.capabilities), permission_bundle: full.permission_bundle, expires_at: full.expires_at, status: full.status }, note: 'Full grant principal — scopes/bundle/expiry/status. Not a human session; never authorizes risk/never-delegable actions.' });
+        res.json({ grant: { grant_id: full.grant_id, human_id: full.human_id, agent_label: full.agent_label, scopes: scopeNames(full.capabilities), permission_bundle: full.permission_bundle, expires_at: full.expires_at, status: full.status }, note: 'Full grant principal — all authorized scopes/bundle/expiry/status. Not a human session; never authorizes risk/never-delegable actions.' });
     });
     // POST create a permission request — the AGENT (holding its current grant) asks for MORE scope / a bundle.
     //   Bound to (human_id, grant_id) from the grant bearer. Rate-limited. Safe-only: risk/never-delegable are
@@ -183,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
@@ -210,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).
@@ -236,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
@@ -266,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) => {
@@ -313,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.
@@ -362,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]);
@@ -370,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' });

package/dist/pwa/routes/orders-action.js

@@ -1,11 +1,12 @@
 import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
-import { createNotification } from '../../layer2-business/L2-6-notifications/notification-engine.js';
+import { createNotification, notifyDeclineContestCase } from '../../layer2-business/L2-6-notifications/notification-engine.js';
+import { executeSellerOrderAction } from '../order-action-exec.js'; // RFC-021 PR3 共享执行器(api_key 路径 strictTracking=false)
 import { releaseFeeStake } from '../../direct-pay-ledger.js'; // Rail1 直付:取消/超时释放任何遗留模拟质押(AR 订单无 stake → no-op)
 import { restorePreShipDirectPayStock } from '../../direct-pay-stock.js'; // D3 库存回补唯一入口(pre-ship 放行;已出库拒绝)
 import { requireBothDisclosuresAcked } from '../../direct-pay-disclosures.js'; // PR-4e: D1/D2 披露契约门
 import { requireDirectPayHumanPasskey } from '../direct-pay-guards.js'; // PR-4e: 现场真人 Passkey/gate-token 门
 export function registerOrdersActionRoutes(app, deps) {
-    const { db, auth, isTrustedRole, generateId, transition, notifyTransition, settleOrder, settleFault, detectFraud, createDispute, checkTimeouts, recordViolationReputation, broadcastSystemEvent, consumeGateToken } = deps;
+    const { db, auth, isTrustedRole, generateId, transition, notifyTransition, settleOrder, settleFault, detectFraud, createDispute, createDeclineContestDispute, checkTimeouts, recordViolationReputation, broadcastSystemEvent, consumeGateToken } = deps;
     // PR-4e: direct_p2p 风险动作门 —— ① D1/D2 两次披露都 ack(缺则 DISCLOSURE_NOT_ACKED);② 现场真人 Passkey + 一次性
     //   WebAuthn gate token(purpose 固定 direct_pay_order_action,order+action 走 purpose_data + validate)。
     //   纯前置门:返回 ok 才允许后续写入。【先 disclosure(只读)再 Passkey(消费 token)】→ 缺 ack 不浪费 token。
@@ -378,8 +379,22 @@ export function registerOrdersActionRoutes(app, deps) {
                 evIds.push(eid);
             }
             db.prepare("UPDATE orders SET decline_contested = 1 WHERE id = ?").run(req.params.id);
+            // 统一仲裁台:并入 disputes(不改 order.status)。幂等——重复举证不会建第二条。失败不阻断举证本身
+            //   (标志位已置;backfill 脚本可事后补建),但记录以便排查。
+            const dc = createDeclineContestDispute(db, req.params.id);
+            if (!dc.success)
+                console.error(`[contest_decline] createDeclineContestDispute failed for ${req.params.id}: ${dc.error}`);
+            // PR2:通知全体 active 仲裁员 + admin 有新案(去重,只对新建行发;既有行不重复轰炸)。
+            else if (!dc.existing && dc.disputeId) {
+                try {
+                    notifyDeclineContestCase(db, req.params.id, dc.disputeId);
+                }
+                catch (e) {
+                    console.error(`[contest_decline] notify failed: ${e.message}`);
+                }
+            }
             return void res.json({
-                success: true, outcome: 'contested', evidence_ids: evIds,
+                success: true, outcome: 'contested', evidence_ids: evIds, dispute_id: dc.disputeId,
                 note: '已就客观无责拒单发起人工仲裁举证。自动终结已暂停,等待仲裁员裁决:维持→免责全退+退质押,驳回→违约结算。',
             });
         }
@@ -456,6 +471,21 @@ export function registerOrdersActionRoutes(app, deps) {
             catch { }
             return void res.json({ success: true, status: 'completed', dispute_dismissed: true });
         }
+        // RFC-021 PR3:accept/ship 经【共享执行器】(与 Passkey-approve 路径同一真相源;守卫全内置)。
+        //   api_key 路径 = seller 本人直发 → strictTracking=false(保持现状:无单号/占位单号发货不破坏;tracking 仍为 hint)。
+        //   evidence_description 现状语义保留(缺则执行器内 transition 因证据空而拒);logistics 绑定已在上方完成。
+        if (action === 'accept' || action === 'ship') {
+            const exec = executeSellerOrderAction(db, { orderId: req.params.id, action, actorId: user.id, nowIso: new Date().toISOString(), strictTracking: false, tracking: req.body?.tracking, evidenceDescription: evidence_description, generateId, path: 'api_key' });
+            if (!exec.ok)
+                return void res.status(exec.http || 409).json({ error: exec.error, error_code: exec.error_code });
+            try {
+                notifyTransition(db, req.params.id, exec.fromStatus, exec.toStatus);
+            }
+            catch (e) {
+                console.warn('[order-action notify]', e.message);
+            }
+            return void res.json({ success: true, status: exec.toStatus });
+        }
         const actionMap = {
             accept: 'accepted', ship: 'shipped', pickup: 'picked_up',
             transit: 'in_transit', deliver: 'delivered', confirm: 'confirmed', dispute: 'disputed',
@@ -530,6 +560,19 @@ export function registerOrdersActionRoutes(app, deps) {
         const result = transition(db, req.params.id, toStatus, user.id, evidenceIds, notes);
         if (!result.success)
             return void res.json({ error: result.error });
+        // P1-c(b):direct_p2p 首次进 accepted(mark_paid / confirm_received)才生成 ship_deadline —— direct-pay-create 建单不设该列,
+        //   缺 ship_deadline 会被共享执行器 SLA【fail-closed】卡住发货。WHERE ship_deadline IS NULL 兜死:仅 null→值 那一次写,
+        //   绝不覆盖已有值(守 I3:deadline 绝对列不重写)。判责钟从付款确认(now)起。
+        if (toStatus === 'accepted' && order.payment_rail === 'direct_p2p') {
+            let sh = 72;
+            try {
+                const p = await dbOne("SELECT value FROM protocol_params WHERE key = 'direct_pay.ship_window_hours'");
+                if (p)
+                    sh = Math.max(1, Number(p.value) || 72);
+            }
+            catch { /* 用默认 72h */ }
+            await dbRun("UPDATE orders SET ship_deadline = datetime('now', ?) WHERE id = ? AND ship_deadline IS NULL", [`+${sh} hours`, req.params.id]);
+        }
         notifyTransition(db, req.params.id, fromStatus, toStatus);
         // 审计项 B(N2):买家标记付款 → 通知卖家核款发货(direct_pay_window→accepted 不在 notifyTransition RULES,
         //   此前卖家全程收不到"已付款"信号只能手动刷)。notes 即 D1/D2/E 的权威对账串(参考号+应付+多单预警),直接复用。