@seasonkoh/webaz 0.1.23 → 0.1.25

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';
@@ -43,10 +44,16 @@ const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'off').toLowerCase() =
 const WEBAZ_API_URL = (process.env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
 const WEBAZ_API_KEY = process.env.WEBAZ_API_KEY ?? '';
 const WEBAZ_MODE_ENV = (process.env.WEBAZ_MODE ?? '').toLowerCase();
-// 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 → sandbox
+// 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 key → network_readonly(装完即见真网络)。
+// network_readonly(L1 onboarding,2026-06-08):无 key 默认。公共读匿名打 webaz.xyz(真 catalog/协议),
+//   需身份的写/读返回"设 WEBAZ_API_KEY(到 #welcome 申请邀请)"。离线本地 playground 改为【显式】 WEBAZ_MODE=sandbox。
+//   —— 治"装完=空沙盒劝退"的死首体验;route/guard 与 network 同路(见 isNetworkMode),只是无 Bearer + 文案不同。
 const MODE = WEBAZ_MODE_ENV === 'network' ? 'network'
     : WEBAZ_MODE_ENV === 'sandbox' ? 'sandbox'
-        : (WEBAZ_API_KEY ? 'network' : 'sandbox');
+        : WEBAZ_MODE_ENV === 'network_readonly' ? 'network_readonly'
+            : (WEBAZ_API_KEY ? 'network' : 'network_readonly');
+// network 或 network_readonly 都"走真网络"(后者无 Bearer)。sandbox 才是本地。
+const isNetworkMode = () => MODE === 'network' || MODE === 'network_readonly';
 // 已迁移到 NETWORK 的工具名。P1/P2 逐个加入;未在集合里的工具仍走 sandbox(本地)。
 // P1(读工具): 纯公开读,无写无 Passkey,作"MCP 连得上生产网络"的首验证。
 const NETWORK_TOOLS = new Set([
@@ -103,9 +110,10 @@ function pushRecentCall(c) {
     if (recentCalls.length > 8)
         recentCalls.shift(); // 只留最近 8 条
 }
-// 单个工具实际后端:仅当全局 network 且该工具已迁移,才走网络;否则 sandbox。
+// 单个工具实际后端:network 或 network_readonly 下、且该工具已迁移,才走网络;否则 sandbox。
+// readonly 无 Bearer:公共读拿真数据,需身份的端点服务端返 401(诚实)→ 不会静默落本地。
 function toolBackend(tool) {
-    return (MODE === 'network' && NETWORK_TOOLS.has(tool)) ? 'network' : 'sandbox';
+    return (isNetworkMode() && NETWORK_TOOLS.has(tool)) ? 'network' : 'sandbox';
 }
 // 未在 NETWORK_TOOLS 名单、但 NETWORK 模式下仍可本地运行的"自省/引导"工具(非数据操作)。
 // info = 本地自省(并拉 live 网络状态);register = 引导真人去 webaz.xyz。其余未迁工具一律硬失败。
@@ -166,14 +174,18 @@ async function apiCall(path, opts = {}) {
 // 启动 banner(stderr)+ status 声明用 —— 让用户/agent 一眼知道现在是真网络还是沙盒
 function modeBanner() {
     if (MODE === 'network') {
-        return `🟢 NETWORK mode — webaz.xyz (${WEBAZ_API_URL}). Migrated tools: ${NETWORK_TOOLS.size}/${TOOLS.length}`
-            + (NETWORK_TOOLS.size === 0 ? ' ⚠️ network client not active yet (P0 scaffold) — all tools still SANDBOX/local.' : '');
+        return `🟢 NETWORK mode — webaz.xyz (${WEBAZ_API_URL}), authenticated. Migrated tools: ${NETWORK_TOOLS.size}/${TOOLS.length}`;
     }
-    return `🟡 SANDBOX mode — local-only (~/.webaz/webaz.db), NOT the live network. Data is private to this machine.`
-        + (WEBAZ_API_KEY ? '' : ' Set WEBAZ_API_KEY (register at webaz.xyz) to join the network.');
+    if (MODE === 'network_readonly') {
+        return `🟢 NETWORK (read-only) — no api_key: public reads (search / leaderboard / price history / browse) hit the LIVE webaz.xyz network. `
+            + `To transact (register/order/list/etc.), set WEBAZ_API_KEY — request an invite at ${WEBAZ_API_URL}/#welcome.`;
+    }
+    return `🟡 SANDBOX mode — local-only (~/.webaz/webaz.db), NOT the live network. Data is private to this machine. `
+        + `(Explicit dev/demo mode; unset WEBAZ_MODE to use the live network read-only by default.)`;
 }
 // ─── 初始化 ──────────────────────────────────────────────────
 const db = initDatabase();
+setSeamDb(db); // RFC-016 Phase 1:注入异步 DB seam(本进程)—— 共享引擎迁 seam 后 MCP 进程也能用,否则 dbOne/dbAll 抛"未初始化"
 initSystemUser(db);
 initDisputeSchema(db);
 initNotificationSchema(db);
@@ -313,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: {
@@ -854,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: {
@@ -869,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: {
@@ -1416,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'],
         },
     },
 ];
@@ -1479,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')
@@ -1503,38 +1612,32 @@ 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();
     // RFC-003 Batch 0:NETWORK 模式下,best-effort 拉 webaz.xyz 的 live 协议状态,
     // 让带 key 的 agent 拿到【真网络】数字,而非只看本机本地 live_stats(下方仍保留并标注为本地)。
     let network_live = null;
-    if (MODE === 'network') {
+    if (isNetworkMode()) {
         try {
             const ps = await apiCall('/api/protocol-status');
             network_live = { source: `${WEBAZ_API_URL}/api/protocol-status (live, fetched this call)`, ...ps };
@@ -1587,11 +1690,13 @@ async function handleInfo() {
         // 佣金按【功能】中性描述(commission_model),不做"自证不是X"的辩护——正常机制无需自证。
         network_state: {
             // RFC-003 P3：显式声明当前客户端模式，让 agent 一眼分清"真网络 vs 本机沙盒"
-            mode: MODE, // 'network' | 'sandbox'
+            mode: MODE, // 'network' | 'network_readonly' | 'sandbox'
             mode_banner: modeBanner(),
             mode_meaning: MODE === 'network'
                 ? '🟢 NETWORK：核心交易工具（下单/上架/履约/比价等）走 webaz.xyz 共享生产网络。真网络规模见下方 network_live（本次实时拉取）；live_stats 仍是本机本地缓存，仅供参考。'
-                : '🟡 SANDBOX：所有工具都在本机本地 SQLite 运行，与 webaz.xyz 全网隔离。任何计数 / 账号 / 订单仅本机有效，不是真实网络状态。设 WEBAZ_API_KEY 可切到 NETWORK。',
+                : MODE === 'network_readonly'
+                    ? '🟢 NETWORK（只读）：无 api_key。公共读（搜索/榜单/价格史/浏览）打 webaz.xyz 真网络（见 network_live）。要交易（注册/下单/上架等）请设 WEBAZ_API_KEY —— 到 ' + WEBAZ_API_URL + '/#welcome 申请邀请。'
+                    : '🟡 SANDBOX：所有工具都在本机本地 SQLite 运行，与 webaz.xyz 全网隔离（显式 dev/demo 模式）。任何计数 / 账号 / 订单仅本机有效。不设 WEBAZ_MODE 则默认走真网络只读。',
             phase: 'pre_launch',
             real_users_on_canonical: 0,
             canonical_endpoint: 'https://webaz.xyz',
@@ -1629,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: {
@@ -1674,10 +1779,10 @@ async function handleInfo() {
 function handleRegister(args) {
     // ─── RFC-003 P3：NETWORK 模式不自助建号 ────────────────────────
     // 自助注册会绕过邀请码 / captcha / 责任制；且 CHARTER §4 I-5 要求账号必须由已绑 Passkey
-    // 的真人创建（"每个 agent 背后有可问责的真人"）。NETWORK 模式下改为引导真人去 webaz.xyz 拿 key。
-    if (MODE === 'network') {
+    // 的真人创建（"每个 agent 背后有可问责的真人"）。NETWORK / 无 key 只读模式下都引导真人去 webaz.xyz 拿 key。
+    if (isNetworkMode()) {
         return {
-            _mode: 'network',
+            _mode: MODE,
             registration: 'must_be_done_by_human_at_webaz_xyz',
             message: '🟢 NETWORK 模式下不支持 agent 自助注册。开放协议的信任来自"每个 agent 背后有可问责的真人"，所以注册这一步刻意留给真人在 webaz.xyz 完成。请按三步加入共享网络：',
             steps: [
@@ -1945,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;
@@ -1971,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);
@@ -2200,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');
@@ -2682,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);
     }
@@ -2770,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' };
@@ -2812,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 => ({
@@ -2836,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(`
@@ -2994,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,
@@ -3052,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),
@@ -3061,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),
@@ -3361,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,
@@ -3379,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,
@@ -3402,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';
@@ -3420,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
@@ -3468,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',
             ],
@@ -3510,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,
@@ -3919,9 +4032,9 @@ async function readEndpoint(tool, subpath) {
     }
 }
 async function pwaApi(method, path, apiKey, body) {
-    // RFC-003:NETWORK 模式 → 走 webaz.xyz 共享网络(Bearer api_key)。仅 NETWORK_TOOLS 里的工具会到这里
-    // (其余未迁工具在 dispatch 被 Batch 0 守卫拦下);SANDBOX 模式仍转发本地 PWA(localhost)。
-    if (MODE === 'network') {
+    // RFC-003:NETWORK / network_readonly → 走 webaz.xyz(Bearer 可空)。仅 NETWORK_TOOLS 里的工具会到这里
+    // (其余未迁工具在 dispatch 被 Batch 0 守卫拦下);SANDBOX 才转发本地 PWA(localhost)。
+    if (isNetworkMode()) {
         return apiCall(path.startsWith('/api') ? path : '/api' + path, { method, apiKey, body });
     }
     const opts = {
@@ -4694,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: [
                 {
@@ -4848,7 +4961,7 @@ export async function startMCPServer() {
             // ─── RFC-003 Batch 0 安全网:NETWORK 模式下未迁移的工具【硬失败】,不静默落本地沙盒 ───
             // 例外:info / register(NETWORK_SELF_AWARE)有专门 network-aware 处理,照常放行。
             let handled = false;
-            if (MODE === 'network' && !NETWORK_TOOLS.has(name) && !NETWORK_SELF_AWARE.has(name)) {
+            if (isNetworkMode() && !NETWORK_TOOLS.has(name) && !NETWORK_SELF_AWARE.has(name)) {
                 result = networkMigrationPending(name);
                 handled = true;
             }
@@ -4991,7 +5104,9 @@ export async function startMCPServer() {
         }
         // RFC-003 P0: 给每个工具结果盖模式戳(诚实可见,防把 sandbox 当 live 网络)
         // P3: handler 可自行预设 _mode(如 register 在 network 模式返回引导,不是 sandbox 结果)→ 不覆盖。
-        const backend = toolBackend(name);
+        // self-aware 工具(info/register)按全局 MODE 盖戳,不按 toolBackend(它们不在 NETWORK_TOOLS 但本就网络感知),
+        // 否则 network_readonly/network 下 info 会被误盖 sandbox 戳,与其自身 network_state 矛盾。
+        const backend = NETWORK_SELF_AWARE.has(name) ? (isNetworkMode() ? 'network' : 'sandbox') : toolBackend(name);
         if (result && typeof result === 'object' && !Array.isArray(result)) {
             const r = result;
             if (!('_mode' in r))