@seasonkoh/webaz 0.1.24 → 0.1.25

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

@@ -14,6 +14,7 @@
  */
 import crypto from 'crypto';
 import { generateId } from '../L0-1-database/schema.js';
+import { dbOne, dbAll } from '../L0-1-database/db.js'; // RFC-016 异步 seam(纯读)
 export function initOrderChainSchema(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS order_events (
@@ -42,10 +43,11 @@ export function initOrderChainSchema(db) {
     }
     catch { }
 }
-export function listOrderEventsSince(db, userId, since, limit) {
+// RFC-016 Phase 1:纯读 → 异步 seam(db 参数保留签名兼容;调用点 orders-read.ts 均 inTx=false,非状态机写路径)。
+export async function listOrderEventsSince(_db, userId, since, limit) {
     const lim = Math.min(200, Math.max(1, Math.floor(limit) || 50));
     const sinceRid = since && /^\d+$/.test(since) ? Number(since) : 0;
-    const rows = db.prepare(`
+    const rows = await dbAll(`
     SELECT e.rowid AS rid, e.order_id, e.seq, e.event_type, e.from_status, e.to_status, e.actor_role,
            e.event_hash, e.prev_event_hash, e.signed_at, e.created_at
     FROM order_events e
@@ -54,7 +56,7 @@ export function listOrderEventsSince(db, userId, since, limit) {
       AND e.rowid > ?
     ORDER BY e.rowid ASC
     LIMIT ?
-  `).all(userId, userId, userId, sinceRid, lim);
+  `, [userId, userId, userId, sinceRid, lim]);
     const events = rows.map(r => ({
         cursor: String(r.rid),
         order_id: r.order_id, seq: r.seq, event_type: r.event_type,
@@ -118,16 +120,16 @@ export function appendOrderEvent(db, args) {
     return { id, seq, event_hash: eventHash };
 }
 // 验证整条链 — 仲裁时或任何审计场景可调
-export function verifyOrderChain(db, orderId) {
-    const rows = db.prepare(`SELECT seq, prev_event_hash, event_hash, payload_json, signature, actor_id
-       FROM order_events WHERE order_id = ? ORDER BY seq ASC`).all(orderId);
+export async function verifyOrderChain(_db, orderId) {
+    const rows = await dbAll(`SELECT seq, prev_event_hash, event_hash, payload_json, signature, actor_id
+       FROM order_events WHERE order_id = ? ORDER BY seq ASC`, [orderId]);
     if (rows.length === 0)
         return { ok: false, total: 0, verified: 0, reason: 'empty_chain' };
     // 修复 ultrareview bug_007：transition() 的 appendOrderEvent 是 try-catch 软失败
     // （legacy actor 缺 api_key 等场景），但 order_state_history 仍会 commit。
     // 检测：chain 行数应该至少等于 history 行数（chain ≥ history，因为可能有 open genesis 事件无 history）
     // 不等就说明有 silent drop，链不完整 — UI 不应再显示"验证通过"
-    const histCount = db.prepare(`SELECT COUNT(*) as n FROM order_state_history WHERE order_id = ?`).get(orderId);
+    const histCount = await dbOne(`SELECT COUNT(*) as n FROM order_state_history WHERE order_id = ?`, [orderId]);
     if (histCount && rows.length < histCount.n) {
         return { ok: false, total: rows.length, verified: 0, reason: 'chain_incomplete', history_count: histCount.n };
     }
@@ -143,7 +145,7 @@ export function verifyOrderChain(db, orderId) {
             return { ok: false, total: rows.length, verified: r.seq, firstBrokenSeq: r.seq, reason: 'event_hash_mismatch' };
         }
         // 3. signature 用 actor api_key 验
-        const actor = db.prepare('SELECT api_key FROM users WHERE id = ?').get(r.actor_id);
+        const actor = await dbOne('SELECT api_key FROM users WHERE id = ?', [r.actor_id]);
         if (!actor)
             return { ok: false, total: rows.length, verified: r.seq, firstBrokenSeq: r.seq, reason: 'actor_not_found' };
         const reSig = computeEventSignature(r.payload_json, actor.api_key);
@@ -154,10 +156,10 @@ export function verifyOrderChain(db, orderId) {
     }
     return { ok: true, total: rows.length, verified: rows.length };
 }
-export function getOrderChain(db, orderId) {
-    const rows = db.prepare(`SELECT seq, event_type, from_status, to_status, actor_id, actor_role, signed_at,
+export async function getOrderChain(_db, orderId) {
+    const rows = await dbAll(`SELECT seq, event_type, from_status, to_status, actor_id, actor_role, signed_at,
             event_hash, prev_event_hash, signature, payload_json
-       FROM order_events WHERE order_id = ? ORDER BY seq ASC`).all(orderId);
+       FROM order_events WHERE order_id = ? ORDER BY seq ASC`, [orderId]);
     return rows.map(r => ({
         seq: r.seq,
         event_type: r.event_type,

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

@@ -269,7 +269,7 @@ export const ORDER_STATE_MEANINGS = {
     fault_buyer: { zh: '买家违约(超时未付,终态)', en: 'buyer fault (payment timeout, terminal)' },
     fault_seller: { zh: '卖家违约(超时未接/发 或 主动拒单)', en: 'seller fault (accept/ship timeout or active decline)' },
     fault_logistics: { zh: '物流违约', en: 'logistics fault' },
-    declined_nofault: { zh: '卖家无责拒单(仲裁认定客观)→ 全退买家+退卖家质押,零罚没(终态)', en: 'seller no-fault decline (arbitration-cleared) → full refund + stake returned, no forfeit (terminal)' },
+    declined_nofault: { zh: '卖家无责拒单裁定(仲裁认定客观),待系统结算 → completed;全退买家+退卖家质押,零罚没', en: 'seller no-fault decline (arbitration-cleared), pending system settlement → completed; full refund + stake returned, no forfeit' },
     resolved_for_seller: { zh: '仲裁裁卖家胜诉,资金释放(终态)', en: 'arbitration ruled for seller, funds released (terminal)' },
     refunded_partial: { zh: '仲裁裁部分退款(终态)', en: 'arbitration partial refund (terminal)' },
     refunded_full: { zh: '仲裁裁全额退款,订单作废(终态)', en: 'arbitration full refund, order voided (terminal)' },

package/dist/layer0-foundation/L0-5-manifest/manifest.js

@@ -10,6 +10,7 @@
  *   2. HTTP GET：<server>/api/manifest
  *   3. webaz_info 工具返回值中的 manifest 字段
  */
+import { dbOne } from '../L0-1-database/db.js'; // RFC-016 异步 seam
 export const MANIFEST_VERSION = '0.1.0';
 export const MANIFEST_URI = 'webaz://protocol/manifest';
 // ─── 协议常量（与状态机保持同步）────────────────────────────
@@ -256,9 +257,9 @@ const AGENT_GUIDE = {
     },
 };
 // ─── 生成 Manifest ────────────────────────────────────────────
-export function generateManifest(db) {
-    // 如果传入 db，可以附加实时统计数据
-    const stats = db ? getLiveStats(db) : null;
+export async function generateManifest(db) {
+    // 如果传入 db（=要求附加实时统计），走异步 seam 读取。db 仅作"是否含 live_stats"开关，实际连接来自 setSeamDb。
+    const stats = db ? await getLiveStats() : null;
     return {
         $schema: 'https://dcp-protocol.io/schema/manifest/v1',
         $uri: MANIFEST_URI,
@@ -288,15 +289,16 @@ export function generateManifest(db) {
         live_stats: stats,
     };
 }
-function getLiveStats(db) {
+async function getLiveStats() {
     try {
-        const users = db.prepare('SELECT COUNT(*) as n FROM users WHERE role != ?').get('system').n;
-        const products = db.prepare("SELECT COUNT(*) as n FROM products WHERE status = 'active'").get().n;
-        const orders = db.prepare('SELECT COUNT(*) as n FROM orders').get().n;
-        const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE status = 'completed'").get().n;
-        const disputes = db.prepare('SELECT COUNT(*) as n FROM disputes').get().n;
-        const skills = db.prepare("SELECT COUNT(*) as n FROM skills WHERE active = 1").get().n;
-        const totalVolume = db.prepare("SELECT COALESCE(SUM(total_amount),0) as v FROM orders WHERE status = 'completed'").get().v;
+        const n = async (sql, params = []) => ((await dbOne(sql, params))?.n ?? 0);
+        const users = await n('SELECT COUNT(*) as n FROM users WHERE role != ?', ['system']);
+        const products = await n("SELECT COUNT(*) as n FROM products WHERE status = 'active'");
+        const orders = await n('SELECT COUNT(*) as n FROM orders');
+        const completed = await n("SELECT COUNT(*) as n FROM orders WHERE status = 'completed'");
+        const disputes = await n('SELECT COUNT(*) as n FROM disputes');
+        const skills = await n("SELECT COUNT(*) as n FROM skills WHERE active = 1");
+        const totalVolume = ((await dbOne("SELECT COALESCE(SUM(total_amount),0) as v FROM orders WHERE status = 'completed'"))?.v ?? 0);
         return { users, active_products: products, total_orders: orders, completed_orders: completed, total_disputes: disputes, active_skills: skills, total_volume_dcp: totalVolume };
     }
     catch {

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

@@ -22,6 +22,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, // #B.1 a — MCP 三大原语之 Prompts
 GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initDatabase, generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { setSeamDb } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam(本进程注入)
 import { transition, getOrderStatus, initSystemUser, } from '../../layer0-foundation/L0-2-state-machine/engine.js';
 import { initDisputeSchema, createDispute, respondToDispute, getDisputeDetails, getOrderDispute, getOpenDisputes, } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js';
 import { initNotificationSchema, notifyTransition, getNotifications, getUnreadCount, markRead, } from '../../layer2-business/L2-6-notifications/notification-engine.js';
@@ -184,6 +185,7 @@ function modeBanner() {
 }
 // ─── 初始化 ──────────────────────────────────────────────────
 const db = initDatabase();
+setSeamDb(db); // RFC-016 Phase 1:注入异步 DB seam(本进程)—— 共享引擎迁 seam 后 MCP 进程也能用,否则 dbOne/dbAll 抛"未初始化"
 initSystemUser(db);
 initDisputeSchema(db);
 initNotificationSchema(db);
@@ -323,7 +325,7 @@ No auth required, no parameters needed.
 
 Roles: buyer (browse/order/confirm) | seller (list/accept/ship) | logistics (pickup/transit/deliver) | reviewer (reviews) | arbitrator (disputes/rulings).
 
-⚠️ **MCP register limitations (anti-bot, by design)**: does NOT set placement_id/sponsor_id — referral/PV chain NOT built via MCP. To build chain: user must arrive via webaz_share_link \`?ref=<uid>\` URL clicked in browser (PWA flow). region defaults 'global'; valid: singapore/china/usa/malaysia/indonesia/thailand/vietnam/taiwan/hk/global.`,
+⚠️ **MCP register limitations (anti-bot, by design)**: does NOT set placement_id/sponsor_id — referral/PV chain NOT built via MCP. To build chain: user must arrive via webaz_share_link \`/i/<permanent_code>\` (or \`?ref=<permanent_code>\`) URL clicked in browser (PWA flow). region defaults 'global'; valid: singapore/china/usa/malaysia/indonesia/thailand/vietnam/taiwan/hk/global.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -864,7 +866,7 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
         name: 'webaz_referral',
         description: `View your referral status: 3-tier commission team + earnings + invite links + points-matching tier progress + L1 share permission gate + **rewards_status (RFC-002 §3.5 opt-in state + pending escrow)**.
 
-⚠️ **Opt-in required (RFC-002)**: rewards default = off. \`rewards_status\` field returns 4-state {opted_in | never_activated | auto_downgraded | deactivated} + pending_escrow tally. Opted-out users still see attribution + tree, but commission held in escrow until activation via PWA #me.
+⚠️ **Opt-in required (RFC-002)**: rewards default = off. \`rewards_status\` field returns 4-state {opted_in | never_activated | auto_downgraded | deactivated} + pending_escrow tally. Opted-out users still see attribution + tree. Commission destination differs by state: **never_activated / auto_downgraded** → held in pending_commission_escrow, recoverable by (re-)activating within the window via PWA #me; **deactivated** (active opt-out) → future L1/L2/L3 commission goes to commission_reserve / protocol reserve, NOT escrow and NOT recoverable (re-applying only affects future commission).
 
 ⚠️ **Consent required**: generating referral links / promoting on a human user's behalf needs the user's explicit authorization. Agent **MUST get explicit consent** before generating referral links / promoting. Do NOT auto-recruit.`,
         inputSchema: {
@@ -879,7 +881,7 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
         name: 'webaz_share_link',
         description: `Generate product share link with your referral attached. Open in any social platform (TikTok/WeChat/Telegram). Clicker registers/buys → counts toward your 3-tier commission (if verified buyer) + points-matching.
 
-⚠️ **Opt-in required (RFC-002 §3.5)**: this is a valuation-layer action. Caller must have \`rewards_opted_in=1\` (builder-identity opt-in). Opted-out users get \`{error: 'rewards_opt_in_required', missing_requirements, next_steps}\` — direct user to PWA #me to apply.
+⚠️ **Opt-in required (RFC-002 §3.5)**: this is a valuation-layer (rewards) action, not a contribution gate. Caller must have \`rewards_opted_in=1\` (rewards / share-commission opt-in). Opted-out users get \`{error: 'rewards_opt_in_required', missing_requirements, next_steps}\` — direct user to PWA #me to apply.
 
 ⚠️ **Consent required**: this builds a referral chain on the user's behalf. Agent acting for a human user **MUST get explicit consent**. Do NOT auto-generate. See webaz_info.commission_model.`,
         inputSchema: {
@@ -1426,28 +1428,44 @@ Gate by type: ux_issue/bug (reporting = using) → login only, NO Passkey, anyon
     },
     {
         name: 'webaz_contribute',
-        description: `Coordinate building WebAZ itself (RFC-006) — a claim board so contributors don't collide. Check BEFORE starting work on an area. Day-to-day small changes; large ones go via RFC. 协调"谁在做什么"防撞车.
+        description: `Coordinate building WebAZ itself (RFC-006 / RFC-017) — a public task board so contributors don't collide. Check BEFORE starting work on an area. 协调"谁在做什么"防撞车.
+
+Discovery + suggesting need NO api_key (anyone / any agent can browse and propose). Claiming + submitting need an api_key (a real, accountable identity).
 
 Actions:
-- list_open (default): open tasks (opt. area filter)
-- claim: take an open task; provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted. Returns a **handoff** (repo + AGENTS.md + PR flow) — point a coding agent at it to actually do the work; the human needn't know git.
-- submit: mark in_review with pr_ref
-- status: tasks you hold (claimed/in_review)
-- profile: your build dashboard — KPI/tier/restrictions+appeal, self-view (private, no public leaderboard)
+- list_open (default): open public tasks (opt. filters: area / risk_level / auto_claimable / required_capabilities / agent_capabilities / max_duration_minutes / estimated_context_size / estimated_agent_budget — estimated_agent_budget is a resource/effort estimate, NOT a payment). Each task carries its execution boundary + the trusted canonical contribution target. NO api_key needed.
+- detail: one task's full execution boundary (allowed/forbidden paths, prohibited actions, acceptance criteria, verification commands, deliverables, definition_of_done) + the canonical repo to PR to + a copy-ready agent_handoff. NO api_key needed.
+- suggest: propose a NEW task (title + summary/reason; opt. area/expected_outcome/source_ref/github_login). It enters the maintainer inbox — it is a suggestion, NOT a contribution fact / reward / participation, and never auto-becomes a task. NO api_key needed.
+- claim: take an open task (api_key); provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted. Returns a handoff — point a coding agent at it; the human needn't know git but stays accountable (Passkey).
+- submit: mark in_review with pr_ref + verification_summary (api_key). The PR's base repo MUST be the canonical WebAZ repo, and a verification_summary (what you ran/verified) is REQUIRED — both server-enforced. A human maintainer reviews next; done ≠ merge.
+- status: tasks you hold (api_key).
+- profile: your build dashboard — KPI/tier/restrictions+appeal, private self-view (api_key).
 
-Coordinates + records only — NO merge/reward; acceptance (done) = human maintainer. build_reputation is a SEPARATE pool, never gates verifier/arbitrator. Login required; NETWORK only.`,
+Coordinates + records only — NO merge/reward; acceptance (done) = human maintainer. Contribution value is uncommitted (RFC-017 I-12). build_reputation is a SEPARATE pool, never gates verifier/arbitrator. NETWORK only (contribution is a real-network act; sandbox has nothing to coordinate with).`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_open', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | claim | submit | status | profile' },
-                api_key: { type: 'string', description: "User's api_key (accountable identity)" },
-                task_id: { type: 'string', description: 'claim / submit: the task id' },
-                area: { type: 'string', description: 'list_open: optional area filter (e.g. search / docs / mcp)' },
+                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | claim | submit | status | profile' },
+                api_key: { type: 'string', description: 'claim/submit/status/profile: your api_key (accountable identity). NOT needed for list_open/detail/suggest.' },
+                task_id: { type: 'string', description: 'detail / claim / submit: the task id' },
+                area: { type: 'string', description: 'list_open: area filter / suggest: suggested area (e.g. search / docs / mcp)' },
+                risk_level: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], description: 'list_open: optional risk filter' },
+                auto_claimable: { type: 'boolean', description: 'list_open: optional filter — only auto-claimable (true) or manual-claim (false) tasks' },
+                required_capabilities: { type: 'string', description: 'list_open: optional filter — comma-separated; matches tasks that REQUIRE ALL of the listed capabilities (superset/AND match on the task requirement). For "tasks my agent can do", use agent_capabilities instead.' },
+                agent_capabilities: { type: 'string', description: 'list_open: optional filter — capabilities your agent HAS (comma-separated); matches tasks whose required_capabilities are a SUBSET of these, i.e. tasks your agent can actually do' },
+                max_duration_minutes: { type: 'number', description: 'list_open: optional filter — only tasks whose estimated max duration fits within this many minutes (your idle time)' },
+                estimated_context_size: { type: 'string', enum: ['small', 'medium', 'large'], description: 'list_open: optional filter — task estimated context size' },
+                estimated_agent_budget: { type: 'string', enum: ['minimal', 'small', 'moderate', 'large', 'xlarge'], description: 'list_open: optional filter — task estimated agent budget (resource/effort estimate, not a payment)' },
                 provenance: { type: 'string', enum: ['human', 'ai_assisted', 'ai_authored'], description: 'claim: self-declared authorship (default human)' },
-                pr_ref: { type: 'string', description: 'submit: your PR link or number' },
+                pr_ref: { type: 'string', description: 'submit: your PR link or number (must target the canonical repo)' },
+                verification_summary: { type: 'string', description: 'submit (REQUIRED): summarize what you ran/verified — the task verification_commands you ran and their results' },
                 note: { type: 'string', description: 'submit: optional note' },
+                title: { type: 'string', description: 'suggest: task title (≥3 chars)' },
+                summary: { type: 'string', description: 'suggest: why it is worth doing / what it solves (the reason)' },
+                expected_outcome: { type: 'string', description: 'suggest: optional — what should be true when done' },
+                source_ref: { type: 'string', description: 'suggest: optional reference link (reference only; does NOT set the target repo)' },
+                proposer_github_login: { type: 'string', description: 'suggest: optional — your GitHub login' },
             },
-            required: ['api_key'],
         },
     },
 ];
@@ -1489,19 +1507,100 @@ async function handleFeedback(args) {
         },
     });
 }
-// RFC-006 Gap 1: webaz_contribute — 协调"谁在做什么"(双模;仅 NETWORK)
-async function handleContribute(args) {
+// RFC-006 断点1(b)交接:从【可信】canonical 目标(API 响应里,绝不硬编码/不取自 task metadata)构造"怎么真正
+// 动手"。人的编码 agent 做 git/PR;Passkey 真人担责。sandbox 运行 / 本地草稿不算正式参与。
+function buildContributeHandoff(cct, taskId) {
+    const c = (cct ?? {});
+    const repoUrl = c.canonical_github_url || 'https://github.com/seasonsagents-art/webaz';
+    const baseRepo = c.expected_pr_base_repo || c.canonical_repository_full_name || 'seasonsagents-art/webaz';
+    const baseBranch = c.base_branch || 'main';
+    return {
+        canonical_repo: baseRepo,
+        repo: repoUrl,
+        base_branch: baseBranch,
+        start_here: 'Read AGENTS.md (project map + before-you-code + PR flow), then CONTRIBUTING.md.',
+        do_the_work: 'Point a coding agent (e.g. Claude Code) at the repo on a single-topic branch. The buyer/shopping agent is not the coding agent — hand off to one.',
+        submit_pr: `Open a PR whose BASE repo is ${baseRepo} (${repoUrl}), base branch ${baseBranch}. If any target repo differs from this canonical repo, STOP and ask the human — never contribute to a non-canonical repository.`,
+        pr_flow: 'Commit with DCO sign-off (git commit -s). If AI-authored, mark the PR per the meta-rule. Humans merge — no auto-merge.',
+        then: `When the PR is open, report it back: webaz_contribute action=submit task_id=${taskId} pr_ref=#<N> verification_summary="<the verification_commands you ran + their results>". Both pr_ref and verification_summary are required.`,
+        not_participation: 'A sandbox run or a local-only draft is NOT participation and is NOT a contribution; only a merged PR (or recognized issue/task/RFC) on the canonical repo enters the contribution record.',
+        human_note: "You don't need to know git — your coding agent does it; you (the Passkey-bound human) stay accountable.",
+    };
+}
+// RFC-006/RFC-017: webaz_contribute — 协调"谁在做什么"。NETWORK only. Discovery + suggest 无需 key(打公开
+// 端口 #329/#331);claim/submit/status/profile 需 key(真实可问责身份,走受 #330 守卫的 member 端口)。
+export async function handleContribute(args) {
     const action = args.action || 'list_open';
     const apiKey = args.api_key;
-    if (!apiKey)
-        return { error: 'api_key required' };
     if (toolBackend('webaz_contribute') !== 'network') {
         return {
             _mode: 'sandbox',
-            error: 'SANDBOX 模式无协调对象 —— 协调要在真实项目上才有意义。请设 WEBAZ_API_KEY 切到 NETWORK 模式。 / Coordination needs NETWORK mode; set WEBAZ_API_KEY.',
+            error: 'SANDBOX 模式无协调对象 —— 协调要在真实项目上才有意义。请设 WEBAZ_API_KEY 切到 NETWORK 模式(或不设 key 默认 network_readonly 也可浏览/建议)。 / Coordination needs the live network; sandbox has nothing to coordinate with.',
             error_code: 'CONTRIBUTE_NEEDS_NETWORK',
         };
     }
+    // ── keyless discovery + suggest (public surface; same trusted canonical target as the PWA) ──
+    if (action === 'list_open') {
+        // public endpoint already restricts to audience=public + status=open; only pass the optional filters.
+        const qs = new URLSearchParams();
+        if (args.area)
+            qs.set('area', String(args.area));
+        if (args.risk_level)
+            qs.set('risk_level', String(args.risk_level));
+        if (args.auto_claimable !== undefined)
+            qs.set('auto_claimable', String(Boolean(args.auto_claimable)));
+        if (args.required_capabilities)
+            qs.set('required_capabilities', String(args.required_capabilities));
+        if (args.agent_capabilities !== undefined)
+            qs.set('agent_capabilities', String(args.agent_capabilities)); // forward even '' so the route fail-closes (typed 400), never silently returns the full list
+        if (args.max_duration_minutes !== undefined)
+            qs.set('max_duration_minutes', String(args.max_duration_minutes));
+        if (args.estimated_context_size)
+            qs.set('estimated_context_size', String(args.estimated_context_size));
+        if (args.estimated_agent_budget)
+            qs.set('estimated_agent_budget', String(args.estimated_agent_budget));
+        const q = qs.toString();
+        const r = await apiCall('/api/public/build-tasks' + (q ? '?' + q : ''));
+        if (!r.error)
+            r._next = 'Pick a task, then: webaz_contribute action=detail task_id=<id> for its full execution boundary + the canonical repo to PR to; then action=claim task_id=<id> api_key=<key> to take it (claiming needs an account).';
+        return r;
+    }
+    if (action === 'detail') {
+        const tid = args.task_id;
+        if (!tid)
+            return { error: 'task_id required for action=detail' };
+        const r = await apiCall('/api/public/build-tasks/' + encodeURIComponent(tid));
+        if (!r.error && r.task)
+            r.agent_handoff = buildContributeHandoff(r.canonical_contribution_target, tid);
+        return r;
+    }
+    if (action === 'suggest') {
+        const title = (args.title ?? '').trim();
+        const summary = (args.summary ?? args.note ?? '').trim();
+        if (title.length < 3)
+            return { error: 'title required (≥3 chars) for action=suggest' };
+        if (summary.length < 1)
+            return { error: 'summary (the reason) required for action=suggest' };
+        const r = await apiCall('/api/public/task-proposals', {
+            method: 'POST',
+            body: {
+                title, summary,
+                suggested_area: args.area ?? args.suggested_area,
+                expected_outcome: args.expected_outcome,
+                source_ref: args.source_ref,
+                proposer_github_login: args.proposer_github_login,
+            },
+        });
+        // typed errors (RATE_LIMITED / DUPLICATE_PROPOSAL / validation) are already mapped by apiCall; the
+        // success response already carries the route-level `proposal_notice` (suggestion ≠ contribution/reward).
+        return r;
+    }
+    // ── participation: a real, accountable identity is required ──
+    if (!apiKey)
+        return {
+            error: `api_key required for action=${action} — set WEBAZ_API_KEY (request an invite at ${WEBAZ_API_URL}/#welcome). Discovery (list_open / detail) and suggest work WITHOUT a key.`,
+            error_code: 'API_KEY_REQUIRED',
+        };
     if (action === 'status')
         return apiCall('/api/build-tasks?mine=1', { apiKey });
     if (action === 'profile')
@@ -1513,31 +1612,25 @@ async function handleContribute(args) {
         const r = await apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/claim', {
             method: 'POST', apiKey, body: { provenance: args.provenance },
         });
-        // RFC-006 断点1(b)交接:认领成功后直接下发"怎么真正动手",让贡献者的【编码 agent】接手 git/PR。
-        //   关键:人不必会 git——人的编码 agent(如 Claude Code)做;人(Passkey 真人)担责。
-        if (!r.error) {
-            r.handoff = {
-                repo: 'https://github.com/seasonsagents-art/webaz',
-                start_here: 'Read AGENTS.md (project map + before-you-code + PR flow), then CONTRIBUTING.md.',
-                do_the_work: 'Point a coding agent (e.g. Claude Code) at the repo; work on a single-topic branch. The buyer/shopping agent is not the coding agent — hand off to one.',
-                pr_flow: 'Commit with DCO sign-off (git commit -s). If AI-authored, add 🤖🤖🤖 to the PR title + a meta-rule trace. Humans merge — no auto-merge.',
-                then: `When the PR is open, report it back: webaz_contribute action=submit task_id=${tid} pr_ref=#<N>.`,
-                human_note: "You don't need to know git — your coding agent does it; you (the Passkey-bound human) stay accountable.",
-            };
-        }
+        if (!r.error)
+            r.handoff = buildContributeHandoff(r.canonical_contribution_target, tid);
         return r;
     }
     if (action === 'submit') {
         const tid = args.task_id;
         if (!tid)
             return { error: 'task_id required for action=submit' };
-        return apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/submit', {
-            method: 'POST', apiKey, body: { pr_ref: args.pr_ref, note: args.note },
+        const vs = (args.verification_summary ?? '').trim();
+        if (vs.length < 1)
+            return { error: 'verification_summary required for action=submit — summarize what you ran/verified (the task verification_commands and their results)', error_code: 'VERIFICATION_SUMMARY_REQUIRED' };
+        const r = await apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/submit', {
+            method: 'POST', apiKey, body: { pr_ref: args.pr_ref, note: args.note, verification_summary: vs },
         });
+        if (!r.error)
+            r._next = 'A human maintainer reviews next — acceptance (done) is manual and done ≠ merge. Track it with webaz_contribute action=status.';
+        return r;
     }
-    // list_open(默认)
-    const q = args.area ? '?status=open&area=' + encodeURIComponent(String(args.area)) : '?status=open';
-    return apiCall('/api/build-tasks' + q, { apiKey });
+    return { error: 'unknown action: ' + action };
 }
 async function handleInfo() {
     const summary = getManifestSummary();
@@ -1641,10 +1734,10 @@ async function handleInfo() {
             split: '7:2:1 — L1 70% / L2 20% / L3 10% of an order\'s commission_pool',
             jurisdiction_tiers: 'Tiers are graded by the order region\'s max_levels — NOT a uniform 3 tiers everywhere. e.g. global region max_levels=1 → L1 only; singapore (etc.) max_levels=3 → up to L3. A region may also be 0 (no commission tiers; pool → community fund).',
             attribution: 'EXPLICIT per-order — commission goes to the promoter attributed at purchase time, not derived from the buyer\'s sponsor chain.',
-            how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records the direct promoter. Full L2/L3 chain requires the buyer to arrive via a webaz_share_link ?ref= URL clicked in a browser (builds product_share_attribution).',
+            how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records the direct promoter. Full L2/L3 chain requires the buyer to arrive via a webaz_share_link /i/<permanent_code> (?ref=<permanent_code>) URL clicked in a browser (builds product_share_attribution).',
             redirect_rules: 'chain_gap (no L / invalid sponsor) → charity_fund; level beyond the region cap → global_fund.',
             l1_gate: 'the promoter must be a verified buyer (≥1 completed order) to receive commission, otherwise that share redirects.',
-            opt_in: 'Participation is opt-in (RFC-002): default = off. A user applies (Passkey + ≥1 completed order); attribution is always recorded, but commission settlement is gated until opt-in (pending held in pending_commission_escrow, 30d grace). See docs/rfcs/RFC-002-rewards-opt-in.md.',
+            opt_in: 'Participation is opt-in (RFC-002): default = off. A user applies (Passkey + ≥1 completed order); attribution is always recorded. Commission destination is state-dependent: never_activated / auto_downgraded → held in pending_commission_escrow (30d grace), recoverable by (re-)activating within the window, else swept to commission_reserve; deactivated (active opt-out) → future commission goes directly to commission_reserve, NOT escrow and NOT recoverable. Never to charity_fund. See docs/rfcs/RFC-002-rewards-opt-in.md.',
         },
         // QA 轮 3 FAIL：roles 漏 reviewer。register 工具支持 5 个角色，info 必须列全。
         roles: {
@@ -1957,8 +2050,8 @@ async function handleSearch(args) {
             : '没有找到匹配的商品';
         return { found: 0, message: hint, products: [], matched_by: 'strict_no_match' };
     }
-    const enriched = products.map((p) => {
-        const boost = getSearchBoost(db, p.seller_id);
+    const enriched = await Promise.all(products.map(async (p) => {
+        const boost = await getSearchBoost(db, p.seller_id);
         const rep_level = p.rep_level || 'new';
         const rep_points = Number(p.rep_points) || 0;
         const completion = Number(p.completion_count) || 0;
@@ -1983,7 +2076,7 @@ async function handleSearch(args) {
         const firstSaleBoost = firstSold && (Date.now() - new Date(firstSold.replace(' ', 'T') + 'Z').getTime()) < 14 * 86400_000 ? 5 : 0;
         const score = completion * 0.5 + rep_points * 0.1 + sharer * 2.0 + freshness + firstSaleBoost - dispute * 5.0;
         return { ...p, _boost: boost, _rep_level: rep_level, _rep_points: rep_points, _score: score, _freshness: freshness, _first_sale_boost: firstSaleBoost };
-    });
+    }));
     const sorted = sortMode === 'trending'
         ? enriched.sort((a, b) => b._score - a._score || b._boost - a._boost).slice(0, limit)
         : enriched.slice(0, limit);
@@ -2212,7 +2305,7 @@ async function handleListProduct(args) {
     // stake 在 place_order 那一刻按"该订单总额 × stake_rate"现锁，订单结算时退该笔，违约时扣该笔。
     // 这样每个 active 订单都有独立 stake 担保，多 stock 商品也不会被空头薅。
     // product.stake_amount 字段保留为"indicative rate × price"（前端展示用），不强制 lock。
-    const stakeDiscount = getStakeDiscount(db, user.id);
+    const stakeDiscount = await getStakeDiscount(db, user.id);
     const stakeRate = Math.max(0.05, 0.15 - stakeDiscount); // 最低 5%，声誉越高折扣越大
     const stakeAmount = Math.round(price * stakeRate * 100) / 100; // indicative only; actual lock per-order
     const id = generateId('prd');
@@ -2694,8 +2787,8 @@ async function handleNotifications(args) {
         return auth;
     const { user } = auth;
     const onlyUnread = args.unread === true;
-    const notifs = getNotifications(db, user.id, onlyUnread, 30);
-    const unread = getUnreadCount(db, user.id);
+    const notifs = await getNotifications(db, user.id, onlyUnread, 30);
+    const unread = await getUnreadCount(db, user.id);
     if (args.mark_read) {
         markRead(db, user.id);
     }
@@ -2782,9 +2875,9 @@ async function handleDispute(args) {
     // ── 查看争议详情 ────────────────────────────────────────────
     if (action === 'view') {
         let dispute = args.dispute_id
-            ? getDisputeDetails(db, args.dispute_id)
+            ? await getDisputeDetails(db, args.dispute_id)
             : args.order_id
-                ? getOrderDispute(db, args.order_id)
+                ? await getOrderDispute(db, args.order_id)
                 : null;
         if (!dispute)
             return { error: '找不到争议记录，请提供 dispute_id 或 order_id' };
@@ -2824,7 +2917,7 @@ async function handleDispute(args) {
         if (user.role !== 'arbitrator') {
             return { error: '只有仲裁员可以查看所有待处理争议' };
         }
-        const disputes = getOpenDisputes(db);
+        const disputes = await getOpenDisputes(db);
         return {
             open_count: disputes.length,
             disputes: disputes.map(d => ({
@@ -2848,7 +2941,7 @@ async function handleDispute(args) {
         // 如有证据描述，先创建证据记录
         const evidenceIds = [];
         if (args.evidence_description) {
-            const dispute = getDisputeDetails(db, args.dispute_id);
+            const dispute = await getDisputeDetails(db, args.dispute_id);
             if (dispute) {
                 const eid = generateId('evt');
                 db.prepare(`
@@ -3006,7 +3099,7 @@ async function handleSkill(args) {
             if (!('error' in a))
                 userId = a.user.id;
         }
-        const skills = listSkills(db, {
+        const skills = await listSkills(db, {
             skillType: args.skill_type,
             query: args.query,
             subscriberId: userId,
@@ -3064,7 +3157,7 @@ async function handleSkill(args) {
     }
     // ── 我发布的 Skill ────────────────────────────────────────
     if (action === 'my_skills') {
-        const skills = getMySkills(db, user.id);
+        const skills = await getMySkills(db, user.id);
         return {
             total: skills.length,
             skills: skills.map(formatSkillForAgent),
@@ -3073,7 +3166,7 @@ async function handleSkill(args) {
     }
     // ── 我订阅的 Skill ────────────────────────────────────────
     if (action === 'my_subs') {
-        const skills = getMySubscriptions(db, user.id);
+        const skills = await getMySubscriptions(db, user.id);
         return {
             total: skills.length,
             subscriptions: skills.map(formatSkillForAgent),
@@ -3373,10 +3466,14 @@ async function handleReferral(args) {
     const tiers = db.prepare("SELECT tier, pv_threshold, score_per_hit FROM binary_tier_config WHERE active=1 ORDER BY tier ASC").all();
     const pair = Math.min(Number(me?.total_left_pv ?? 0), Number(me?.total_right_pv ?? 0));
     const nextTier = tiers.find(t => t.pv_threshold > pair);
+    // invite / share links use permanent_code ONLY — never usr_xxx. (sandbox users have one from register.)
+    const permaCode = db.prepare("SELECT permanent_code FROM users WHERE id = ?").get(userId)?.permanent_code || null;
     return {
         user_id: userId,
         name: user.name,
-        base_referral_link: `/?ref=${userId}`, // 仅推土机
+        invite_code: permaCode,
+        invite_unavailable_reason: permaCode ? null : 'permanent_code_missing — re-register or contact support',
+        base_referral_link: permaCode ? `/i/${permaCode}` : null, // 仅推土机
         region: user.region ?? 'global',
         permissions: {
             can_earn_l1_commission: canL1,
@@ -3391,10 +3488,10 @@ async function handleReferral(args) {
             grand_total: byLevel[1].total + byLevel[2].total + byLevel[3].total,
         },
         binary: {
-            left_invite_link: `/?ref=${userId}&side=left`,
-            right_invite_link: `/?ref=${userId}&side=right`,
-            platform_left: `/?placement=${userId}&side=left`, // 仅 PV 条线
-            platform_right: `/?placement=${userId}&side=right`,
+            left_invite_link: permaCode ? `/i/${permaCode}-L` : null,
+            right_invite_link: permaCode ? `/i/${permaCode}-R` : null,
+            platform_left: permaCode ? `/?placement=${permaCode}&side=left` : null, // 仅 PV 条线
+            platform_right: permaCode ? `/?placement=${permaCode}&side=right` : null,
             total_left_pv: Number(me?.total_left_pv ?? 0),
             total_right_pv: Number(me?.total_right_pv ?? 0),
             pair_volume: pair,
@@ -3414,7 +3511,7 @@ async function handleReferral(args) {
             }
             else if (lastAction === 'deactivate') {
                 state = 'deactivated';
-                note = 'You actively deactivated rewards. Future commissions redirect directly to charity_fund (no escrow). You can re-apply via PWA #me.';
+                note = 'You actively deactivated rewards. Future L1/L2/L3 commissions go to commission_reserve / protocol reserve, not charity_fund and not pending escrow. Re-applying only affects future commissions.';
             }
             else if (lastAction === 'auto_downgrade') {
                 state = 'auto_downgraded';
@@ -3432,7 +3529,7 @@ async function handleReferral(args) {
                 note,
                 pending_escrow: { count: pending.n, total_amount: pending.total },
                 expired_to_charity: { count: expired.n, total_amount: expired.total },
-                spec: 'RFC-002 §3.5 — rewards opt-in / 共建身份申请制',
+                spec: 'RFC-002 §3.5 — rewards / share-commission opt-in (RFC-002)',
             };
         })(),
         tip: canL1
@@ -3480,10 +3577,10 @@ async function handleShareLink(args) {
             missing.push('application_not_submitted');
         return {
             error: 'rewards_opt_in_required',
-            message: 'Share-link generation is a valuation-layer action — requires builder-identity opt-in (RFC-002 §3.5)',
+            message: 'Share-link generation is a valuation-layer (rewards / share-link) action, NOT a contribution gate — requires rewards / share-commission opt-in (RFC-002 §3.5)',
             missing_requirements: missing,
             next_steps: [
-                'Open PWA #me → tap "申请共建身份 / Apply for builder identity"',
+                'Open PWA #me → tap "申请分享分润 / Enable share-commission opt-in"',
                 'Read the 8-second disclosure (cannot skip)',
                 'Submit application — pre-checks run server-side',
             ],
@@ -3522,7 +3619,11 @@ async function handleShareLink(args) {
     const override = db.prepare("SELECT l1_share_override FROM users WHERE id = ?").get(userId)?.l1_share_override ?? 0;
     const canL1 = override === 1 || (override === 0 && completed > 0);
     const rate = Number(product.commission_rate ?? 0);
-    const link = `/?ref=${userId}&side=${side}#order-product/${productId}`;
+    // share ref uses permanent_code ONLY — never usr_xxx
+    const permaCode = db.prepare("SELECT permanent_code FROM users WHERE id = ?").get(userId)?.permanent_code || null;
+    if (!permaCode)
+        return { error: 'permanent_code_missing — cannot build a share link; re-register or contact support', error_code: 'PERMANENT_CODE_MISSING' };
+    const link = `/?ref=${permaCode}&side=${side}#order-product/${productId}`;
     return {
         product: { id: product.id, title: product.title, price: product.price, commission_rate: rate },
         share_link: link,
@@ -4706,7 +4807,7 @@ export async function startMCPServer() {
         if (request.params.uri !== MANIFEST_URI) {
             throw new Error(`未知资源：${request.params.uri}`);
         }
-        const manifest = generateManifest(db);
+        const manifest = await generateManifest(db);
         return {
             contents: [
                 {