@seasonkoh/webaz 0.1.26 → 0.1.28

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

@@ -23,6 +23,13 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSche
 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 { applyWebazRuntimeSchema } from '../../runtime/apply-webaz-runtime-schema.js'; // 与 PWA 同源的纯 schema 桥(防 MCP fresh DB 漂移)
+import { generateCodeVerifier, pkceChallengeS256 } from '../../runtime/agent-pairing.js'; // RFC-020 PR-C1 — PKCE 配对
+import { NETWORK_TOOLS, NETWORK_SELF_AWARE, toolAllowedInNetworkMode } from './network-mode.js'; // RFC-003 网络门(可单测)
+import { homedir } from 'node:os';
+import { join as pathJoin } from 'node:path';
+import { existsSync as fsExists, mkdirSync, writeFileSync, readFileSync, unlinkSync, chmodSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 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';
@@ -63,56 +70,6 @@ const MODE = WEBAZ_MODE_ENV === 'network' ? 'network'
             : (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([
-    'webaz_price_history',
-    'webaz_leaderboard',
-    'webaz_verify_price',
-    'webaz_place_order',
-    'webaz_list_product',
-    'webaz_update_order',
-    'webaz_search',
-    'webaz_get_status',
-    'webaz_feedback',
-    'webaz_contribute',
-    // Batch 1(只读 + 低危自身写):走 webaz.xyz Bearer api_key。
-    'webaz_notifications',
-    'webaz_nearby',
-    'webaz_profile',
-    'webaz_shareables',
-    'webaz_mykey',
-    // Batch 2(低危写,无钱无 escrow):走 webaz.xyz Bearer api_key。
-    // 注:share_link 暂不迁(无对应服务端端点,需新建,留待后续)。
-    'webaz_follows',
-    'webaz_like',
-    'webaz_blocklist',
-    'webaz_default_address',
-    'webaz_chat',
-    'webaz_rfq',
-    'webaz_referral',
-    // Batch 3(商务):secondhand/skill_market/auction 纯 pwaApi(mode-aware 自动走网络);
-    // skill 直连本地引擎,加了显式 apiCall network 分支。
-    'webaz_secondhand',
-    'webaz_skill',
-    'webaz_skill_market',
-    'webaz_auction',
-    // Batch 4(资金/质押,守恒由服务端 RFC-014 保证;wallet 只读,写=Passkey 仅 PWA):
-    'webaz_wallet',
-    'webaz_trial',
-    'webaz_charity',
-    'webaz_bid',
-    'webaz_auto_bid',
-    // Batch 5(铁律/敏感):claim_verify 纯 pwaApi(真人门由服务端 require_human_presence 强制);
-    // dispute view/list_open/respond/add_evidence 走网络,arbitrate 仅返回 Passkey 指引;
-    // rotate_key/revoke_key 仅返回 Passkey 指引(不本地校验)。
-    'webaz_dispute',
-    'webaz_claim_verify',
-    'webaz_rotate_key',
-    'webaz_revoke_key',
-    // #1122:share_link 现有服务端端点 /api/share-link,可走网络。
-    'webaz_share_link',
-]);
 const recentCalls = [];
 function pushRecentCall(c) {
     recentCalls.push(c);
@@ -124,9 +81,8 @@ function pushRecentCall(c) {
 function toolBackend(tool) {
     return (isNetworkMode() && NETWORK_TOOLS.has(tool)) ? 'network' : 'sandbox';
 }
-// 未在 NETWORK_TOOLS 名单、但 NETWORK 模式下仍可本地运行的"自省/引导"工具(非数据操作)。
-// info = 本地自省(并拉 live 网络状态);register = 引导真人去 webaz.xyz。其余未迁工具一律硬失败。
-const NETWORK_SELF_AWARE = new Set(['webaz_info', 'webaz_register']);
+// NETWORK_SELF_AWARE imported from ./network-mode.ts (info = local introspection;
+// register = redirect human to webaz.xyz). Everything else un-migrated hard-fails.
 // RFC-003 Batch 0 安全网:NETWORK 模式下调用【未迁移】工具时的诚实拒绝(而非静默落本地沙盒)。
 // 否则带 key 的用户调未迁工具会被悄悄喂本地结果——写操作=幻影操作(根本没到 webaz.xyz)。
 function networkMigrationPending(tool) {
@@ -180,6 +136,200 @@ async function apiCall(path, opts = {}) {
         return { error: `网络错误:${msg}`, network_error: true };
     }
 }
+// ─────────────────────────── RFC-020 PR-C1: webaz_pair (pairing + local credential storage) ───────────────────────────
+// C1 scope: pairing / consent / retrieval / LOCAL credential storage ONLY. The grant is
+// NOT wired into any business tool (that is PR-C2 — per-request scope enforcement + audit).
+// The raw bearer appears exactly once, in the server→MCP retrieval response; it is written
+// straight to the OS secret store (Keychain → 0600 file fallback) and NEVER returned to the
+// user / chat / tool-response / log. webaz_pair returns only a credential handle + status.
+const WEBAZ_DIR = pathJoin(homedir(), '.webaz');
+const PENDING_PATH = pathJoin(WEBAZ_DIR, 'pairing-pending.json'); // holds the PKCE verifier between start→complete
+const CRED_FALLBACK_PATH = pathJoin(WEBAZ_DIR, 'credentials'); // 0600 fallback when Keychain unavailable
+const KEYCHAIN_SERVICE = 'webaz-grant';
+function ensureWebazDir() { if (!fsExists(WEBAZ_DIR))
+    mkdirSync(WEBAZ_DIR, { recursive: true, mode: 0o700 }); }
+function write0600(path, data) { ensureWebazDir(); writeFileSync(path, data, { mode: 0o600 }); try {
+    chmodSync(path, 0o600);
+}
+catch { /* best effort */ } }
+/** Store the raw bearer in the OS secret store; never log it. Returns an opaque handle. */
+function storeGrantCredential(grantId, token) {
+    // macOS Keychain first (non-interactive upsert). Any failure → strict-perms file fallback.
+    if (process.platform === 'darwin') {
+        try {
+            execFileSync('security', ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', grantId, '-w', token], { stdio: ['ignore', 'ignore', 'ignore'] });
+            return `keychain:${KEYCHAIN_SERVICE}/${grantId}`;
+        }
+        catch { /* fall through to file */ }
+    }
+    let store = {};
+    try {
+        if (fsExists(CRED_FALLBACK_PATH))
+            store = JSON.parse(readFileSync(CRED_FALLBACK_PATH, 'utf8'));
+    }
+    catch {
+        store = {};
+    }
+    store[grantId] = { token, stored_at: new Date().toISOString() };
+    write0600(CRED_FALLBACK_PATH, JSON.stringify(store, null, 2));
+    return `file:~/.webaz/credentials#${grantId}`;
+}
+// Non-secret index of the current grant (grant_id + handle + metadata) so the stored
+// credential can be resolved back without re-pairing. The SECRET (token) lives only in
+// the OS secret store / 0600 file — never in this pointer.
+const CRED_POINTER_PATH = pathJoin(WEBAZ_DIR, 'grant-current.json');
+function saveGrantPointer(grantId, handle, capabilities, expiresAt) {
+    write0600(CRED_POINTER_PATH, JSON.stringify({ grant_id: grantId, handle, capabilities: capabilities ?? null, expires_at: expiresAt ?? null, stored_at: new Date().toISOString() }));
+}
+function readGrantPointer() {
+    try {
+        return fsExists(CRED_POINTER_PATH) ? JSON.parse(readFileSync(CRED_POINTER_PATH, 'utf8')) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the stored grant bearer (reverse of storeGrantCredential). Returns null if not paired.
+ * ⚠️ The returned `token` is the RAW bearer — pass it only as an Authorization header; NEVER log it,
+ * print it, or return it in a tool response.
+ */
+export function resolveGrantCredential() {
+    const ptr = readGrantPointer();
+    if (!ptr?.grant_id)
+        return null;
+    let token = '';
+    if (typeof ptr.handle === 'string' && ptr.handle.startsWith('keychain:') && process.platform === 'darwin') {
+        try {
+            token = execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', ptr.grant_id, '-w'], { encoding: 'utf8' }).trim();
+        }
+        catch {
+            token = '';
+        }
+    }
+    if (!token) { // file fallback (also covers keychain-read failure)
+        try {
+            const store = JSON.parse(readFileSync(CRED_FALLBACK_PATH, 'utf8'));
+            token = store[ptr.grant_id]?.token || '';
+        }
+        catch {
+            token = '';
+        }
+    }
+    if (!token)
+        return null;
+    return { grant_id: ptr.grant_id, token, handle: ptr.handle, capabilities: ptr.capabilities, expires_at: ptr.expires_at };
+}
+function savePending(pairingId, codeVerifier) {
+    write0600(PENDING_PATH, JSON.stringify({ pairing_id: pairingId, code_verifier: codeVerifier, started_at: new Date().toISOString() }));
+}
+function readPending() {
+    try {
+        return fsExists(PENDING_PATH) ? JSON.parse(readFileSync(PENDING_PATH, 'utf8')) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function clearPending() { try {
+    if (fsExists(PENDING_PATH))
+        unlinkSync(PENDING_PATH);
+}
+catch { /* best effort */ } }
+export async function handlePair(args) {
+    // Mode isolation (fail-closed): every webaz_pair action (start / complete / verify) talks to the
+    // LIVE webaz.xyz API. In explicit sandbox mode (local-only) we must NOT touch the live network.
+    if (!isNetworkMode()) {
+        return {
+            _mode: MODE,
+            error: 'webaz_pair requires NETWORK mode — you are in sandbox (local-only, isolated from webaz.xyz). Unset WEBAZ_MODE (or set WEBAZ_MODE=network / network_readonly) to pair with / verify against a real human account.',
+            error_code: 'PAIRING_REQUIRES_NETWORK',
+        };
+    }
+    const action = args.action || 'start';
+    if (action === 'start') {
+        const caps = Array.isArray(args.capabilities) && args.capabilities.length
+            ? args.capabilities.map(c => ({ capability: String(c) }))
+            : [{ capability: 'read_public' }, { capability: 'search' }]; // default: minimal safe scopes
+        const verifier = generateCodeVerifier();
+        const challenge = pkceChallengeS256(verifier);
+        const resp = await apiCall('/api/agent-grants/pair/start', {
+            method: 'POST',
+            body: {
+                code_challenge: challenge,
+                capabilities: caps,
+                agent_label: typeof args.agent_label === 'string' ? args.agent_label : undefined,
+                reason: typeof args.reason === 'string' ? args.reason : undefined, // free-text reason only
+            },
+        });
+        if (resp.error)
+            return resp;
+        savePending(String(resp.pairing_id), verifier); // verifier stays LOCAL; never sent until retrieve
+        return {
+            status: 'awaiting_human_approval',
+            pairing_id: resp.pairing_id,
+            user_code: resp.user_code,
+            approve_url: `${WEBAZ_API_URL}${String(resp.approve_url || '')}`,
+            expires_at: resp.expires_at,
+            next: `Ask the human to open approve_url (logged in at webaz.xyz) and approve. Then call webaz_pair again with action="complete".`,
+            capabilities_requested: caps.map(c => c.capability),
+            note: 'Safe scopes only. The credential is delivered once on completion and stored in your OS secret store — it is never shown here.',
+        };
+    }
+    if (action === 'complete') {
+        const pending = readPending();
+        if (!pending)
+            return { error: 'no pending pairing — run webaz_pair (action="start") first', error_code: 'NO_PENDING_PAIRING' };
+        const resp = await apiCall(`/api/agent-grants/pair/${pending.pairing_id}/retrieve`, {
+            method: 'POST',
+            body: { code_verifier: pending.code_verifier },
+        });
+        if (resp.error) {
+            // not approved yet → keep pending so the human can still approve + a later retry works
+            if (resp.http_status === 409)
+                return { status: 'not_ready', detail: resp.error, hint: 'Human has not approved yet (or it expired). Approve, then call action="complete" again.' };
+            clearPending();
+            return resp;
+        }
+        const token = String(resp.token || '');
+        const grantId = String(resp.grant_id || '');
+        if (!token || !grantId) {
+            clearPending();
+            return { error: 'retrieval returned no credential', error_code: 'RETRIEVE_EMPTY' };
+        }
+        const handle = storeGrantCredential(grantId, token); // raw bearer goes straight to secret store
+        saveGrantPointer(grantId, handle, resp.capabilities, resp.expires_at); // non-secret index for later resolve
+        clearPending();
+        return {
+            status: 'stored',
+            credential_handle: handle, // opaque handle — NOT the token
+            grant_id: grantId,
+            capabilities: resp.capabilities,
+            expires_at: resp.expires_at,
+            note: 'Credential stored in your OS secret store (raw token NOT shown; server keeps only a hash). Use webaz_pair action="verify" to confirm it; the server enforces active/expiry/revoked/scope on every call. Safe scopes only.',
+        };
+    }
+    if (action === 'verify') {
+        // Consume the stored grant against a SAFE grant-gated route (read_public). The SERVER is authoritative:
+        // it re-checks active/expiry/revoked/subject-suspension/scope + audits on EVERY call. We resolve the
+        // bearer from the secret store and attach it; the raw token is never printed. Safe scopes only — no
+        // business tool and no risk scope is wired to grants here.
+        const cred = resolveGrantCredential();
+        if (!cred)
+            return { status: 'not_paired', error_code: 'NO_GRANT_CREDENTIAL', hint: 'No stored grant. Run webaz_pair action="start", have the human approve, then action="complete".' };
+        const resp = await apiCall('/api/agent-grants/whoami', { method: 'GET', apiKey: cred.token });
+        if (resp.error) {
+            return { status: 'grant_invalid', grant_id: cred.grant_id, error: resp.error, error_code: resp.error_code, hint: 'Grant is no longer valid (revoked / expired / suspended). Re-pair with webaz_pair action="start".' };
+        }
+        return {
+            status: 'active',
+            grant: resp.grant, // SERVER-AUTHORITATIVE principal (grant_id/human_id/agent_label/capability)
+            local_cache: { capabilities: cred.capabilities, expires_at: cred.expires_at }, // advisory only, may be stale — NOT authoritative
+            note: 'Grant verified LIVE by the server (per-call: active/expiry/revoked/subject-suspension/scope + audited). `grant` is authoritative; `local_cache` is advisory. Safe scopes only; no business tool or risk scope consumes this grant.',
+        };
+    }
+    return { error: `unknown action "${action}" — use "start" | "complete" | "verify"`, error_code: 'BAD_ACTION' };
+}
 // 启动 banner(stderr)+ status 声明用 —— 让用户/agent 一眼知道现在是真网络还是沙盒
 function modeBanner() {
     if (MODE === 'network') {
@@ -195,6 +345,13 @@ function modeBanner() {
 // ─── 初始化 ──────────────────────────────────────────────────
 const db = initDatabase();
 setSeamDb(db); // RFC-016 Phase 1:注入异步 DB seam(本进程)—— 共享引擎迁 seam 后 MCP 进程也能用,否则 dbOne/dbAll 抛"未初始化"
+// MCP fresh-DB schema bridge: apply the SAME pure schema helpers the PWA boot
+// runs (incl. product_aliases + users.permanent_code/handle/region), so an
+// MCP-initialized DB is schema-complete for the sandbox tool path WITHOUT first
+// booting the PWA server. Pure idempotent DDL only — no business writes, no
+// money/order/status path. (MCP_PRODUCT_COLS below now overlaps the products
+// columns and is redundant-but-harmless; left untouched to avoid scope creep.)
+applyWebazRuntimeSchema(db);
 initSystemUser(db);
 initDisputeSchema(db);
 initNotificationSchema(db);
@@ -325,6 +482,26 @@ No auth required, no parameters needed.
             properties: {},
         },
     },
+    {
+        name: 'webaz_pair',
+        description: `Pair this agent with a human's WebAZ account via a Passkey-approved, scoped, short-lived **delegation grant** (RFC-020) — NOT by pasting a permanent api_key. Two steps:
+1. action="start" → returns an approve_url + short user_code. The human opens it at webaz.xyz (logged in) and approves the server-shown consent (safe scopes only).
+2. action="complete" → retrieves the credential ONCE (PKCE) and stores it in your OS secret store (macOS Keychain → ~/.webaz/credentials 0600 fallback). Returns only a credential_handle + status — the raw token is never shown.
+3. action="verify" → uses the stored grant against a safe read endpoint to confirm it is still valid. The server re-checks active/expiry/revoked/suspension/scope and audits the call every time. Returns the grant principal/status; never the raw token.
+
+Scopes: SAFE only (read_public, profile_read, search, list_product_draft, product_publish_request, draft_order). Risk scopes (place_order/wallet/refund/...) and never-delegable actions (withdraw/key-change/vote/...) are hard-rejected.
+
+NOTE: this consumes the grant only on safe read paths; no business tool and no risk scope is wired to grants. No account is created (registration stays human-only at webaz.xyz).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['start', 'complete', 'verify'], description: 'start a pairing, complete it after the human approves, or verify the stored grant (default: start)' },
+                capabilities: { type: 'array', items: { type: 'string' }, description: 'Requested SAFE scopes (default: read_public, search). Non-safe scopes are rejected.' },
+                agent_label: { type: 'string', description: 'Human-friendly name for this agent (shown in the consent screen)' },
+                reason: { type: 'string', description: 'Free-text reason shown to the human (you cannot relabel the scopes)' },
+            },
+        },
+    },
     {
         name: 'webaz_register',
         // was ~1732 chars, now ~780 chars
@@ -521,7 +698,7 @@ Options:
                 },
                 promoter_api_key: {
                     type: 'string',
-                    description: "Referrer api_key (optional). ⚠️ Only L1 recorded (direct referrer, 70% commission); L2/L3 can't be inferred via MCP, redirects per region rule (singapore-like high max_levels → charity chain_gap; global max_levels=1 → global_fund region cap). Full 7:2:1 three-tier chain requires buyer clicking ?ref= URL from webaz_share_link (creates product_share_attribution).",
+                    description: "Referrer api_key (optional). ⚠️ Only L1 recorded (direct referrer, 70% commission); L2/L3 can't be inferred via MCP, so the undelivered L2/L3 portions go to commission_reserve (protocol reserve, in-only). Full 7:2:1 three-tier chain requires buyer clicking ?ref= URL from webaz_share_link (creates product_share_attribution).",
                 },
                 // B2 隐私购物
                 anonymous_recipient: {
@@ -1444,7 +1621,8 @@ Discovery + suggesting need NO api_key (anyone / any agent can browse and propos
 Actions:
 - 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.
+- 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 (but pass your key to LINK it to your account so you can track it via my_suggestions).
+- my_suggestions: your OWN past proposals + their review status / public_reply / next_action (api_key). Agent-readable 回执 so a proposer-agent can act on the maintainer's decision (needs_info → resubmit; converted → see converted_ref).
 - 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).
@@ -1454,12 +1632,12 @@ Coordinates + records only — NO merge/reward; acceptance (done) = human mainta
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | claim | submit | status | profile' },
+                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'my_suggestions', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | my_suggestions | 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. (or set the WEBAZ_API_KEY env var)' },
                 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' },
+                auto_claimable: { type: 'boolean', description: 'list_open: optional filter — true returns tasks an agent can just do (auto-claimable AND with a real effort estimate; matches the derived claimability=auto_claimable), false returns manual-claim tasks. A task with a placeholder (unknown) estimate is treated as manual_review even if its raw auto_claimable flag is true, so it is excluded from true.' },
                 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)' },
@@ -1518,18 +1696,22 @@ async function handleFeedback(args) {
 }
 // RFC-006 断点1(b)交接:从【可信】canonical 目标(API 响应里,绝不硬编码/不取自 task metadata)构造"怎么真正
 // 动手"。人的编码 agent 做 git/PR;Passkey 真人担责。sandbox 运行 / 本地草稿不算正式参与。
-function buildContributeHandoff(cct, taskId) {
+function buildContributeHandoff(cct, taskId, caseId) {
     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 repoUrl = c.canonical_github_url || 'https://github.com/webaz-protocol/webaz';
+    const baseRepo = c.expected_pr_base_repo || c.canonical_repository_full_name || 'webaz-protocol/webaz';
     const baseBranch = c.base_branch || 'main';
+    // case_id threads proposal → task → PR. = the source proposal id when this task came from a proposal,
+    // else the task id itself. Quote it in the PR so the whole case stays traceable end to end.
+    const cid = caseId || taskId;
     return {
+        case_id: cid,
         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.`,
+        submit_pr: `Open a PR whose BASE repo is ${baseRepo} (${repoUrl}), base branch ${baseBranch}. Reference case ${cid} in the PR title/body so the proposal → task → PR chain stays traceable. 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.',
@@ -1580,7 +1762,7 @@ export async function handleContribute(args) {
             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);
+            r.agent_handoff = buildContributeHandoff(r.canonical_contribution_target, tid, r.task.case_id);
         return r;
     }
     if (action === 'suggest') {
@@ -1592,6 +1774,7 @@ export async function handleContribute(args) {
             return { error: 'summary (the reason) required for action=suggest' };
         const r = await apiCall('/api/public/task-proposals', {
             method: 'POST',
+            apiKey, // optional — when present, links the proposal to the submitter so it shows up in action=my_suggestions (still works anonymously)
             body: {
                 title, summary,
                 suggested_area: args.area ?? args.suggested_area,
@@ -1600,6 +1783,8 @@ export async function handleContribute(args) {
                 proposer_github_login: args.proposer_github_login,
             },
         });
+        if (!r.error && r.linked_to_account)
+            r._next = 'Track this proposal\'s review status + reply: webaz_contribute action=my_suggestions api_key=<key>.';
         // 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;
@@ -1612,6 +1797,13 @@ export async function handleContribute(args) {
         };
     if (action === 'status')
         return apiCall('/api/build-tasks?mine=1', { apiKey });
+    if (action === 'my_suggestions') {
+        // your OWN past proposals + review status/public_reply/next_action (agent-readable 回执). Own rows only (server-enforced).
+        const r = await apiCall('/api/me/task-proposals', { apiKey });
+        if (!r.error)
+            r._next = 'Each item carries status + public_reply + next_action. needs_info → resubmit via action=suggest referencing the id; converted → see converted_ref.';
+        return r;
+    }
     if (action === 'profile')
         return apiCall('/api/build-reputation/me', { apiKey });
     if (action === 'claim') {
@@ -1730,8 +1922,11 @@ async function handleInfo() {
         // 连接两个场景:用协议(本工具) ↔ 改协议(开发协作)。想改 WebAZ 本身的 agent 从这里进。
         for_contributors: {
             note: 'Want to change WebAZ itself (not just use it)? This is an open, agent-native protocol — AI-authored PRs are welcome, with accountability. / 想改 WebAZ 本身(不只是用)?这是开放的 agent 原生协议,欢迎 AI 提 PR,但需问责。',
-            repo: 'https://github.com/seasonsagents-art/webaz',
+            repo: 'https://github.com/webaz-protocol/webaz',
             start_here: 'AGENTS.md (project map + before-you-code + PR flow) → CONTRIBUTING.md (full guide)',
+            // 低门槛路径:无需 api_key、无需 clone 仓库,直接经协议发现任务 / 提建议(对外 well-known 入口也有,见 agent_quickstart)。
+            no_key_path: 'No api_key needed to START contributing: discover open tasks and submit a suggestion via webaz_contribute action=list_open / action=suggest (mirrors GET /api/public/build-tasks + POST /api/public/task-proposals). / 无需 key 即可起步:webaz_contribute action=list_open 发现开放任务、action=suggest 提建议。',
+            contribution_boundary: 'A suggestion is a proposal in the maintainer review inbox — NOT a contribution fact, NOT formal participation, and NOT any economic or redemption right; recorded contribution is facts / evidence / attribution only (RFC-017). / 建议只是进入维护者审阅箱的提议,不是贡献事实、不是正式参与、不构成任何经济或兑现权利;记录的贡献只是事实/证据/归属(RFC-017)。',
             ai_accountability: 'AI-authored PRs: add 🤖🤖🤖 to the PR title; the agent must be triggered by a Passkey-bound human (webazer) who is accountable. / AI 提 PR:标题加 🤖🤖🤖,且须由已绑 Passkey 的真人(webazer)触发并担责。',
         },
         // NETWORK 模式:真网络 live 状态(best-effort 拉自 webaz.xyz);SANDBOX 模式为 null。
@@ -1741,10 +1936,10 @@ async function handleInfo() {
         // 佣金机制 —— 纯功能性描述(怎么运作),不做"自证清白"式辩护。
         commission_model: {
             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).',
+            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 → commission_reserve / protocol reserve).',
             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 /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.',
+            redirect_rules: 'all undelivered commission (chain_gap / no L / invalid sponsor / level beyond the region cap / max_levels=0 / opt-out / escrow expiry) → commission_reserve (protocol reserve, in-only; use decided by governance).',
             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. 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.',
         },
@@ -3438,7 +3633,7 @@ function handleRotateKey(args) {
         },
     };
 }
-// ─── 推广 / 双轨 (Tokenomics) ───────────────────────────────────
+// ─── 推广 / 推荐网络 (Tokenomics) ───────────────────────────────────
 async function handleReferral(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络聚合(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_referral') === 'network') {
@@ -3465,16 +3660,9 @@ async function handleReferral(args) {
     const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
     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);
-    // 原子能双轨
+    // Neutral participation record only — placement position + per-leg PV. Matching-rewards engine excised (#401):
+    // no Score / tier / pair-volume / payout is read or exposed.
     const me = db.prepare("SELECT total_left_pv, total_right_pv, left_child_id, right_child_id, placement_id, placement_side FROM users WHERE id = ?").get(userId);
-    const score = db.prepare(`
-    SELECT COALESCE(SUM(CASE WHEN settled_at IS NULL THEN score ELSE 0 END),0) as pending,
-           COALESCE(SUM(CASE WHEN settled_at IS NOT NULL THEN waz_amount ELSE 0 END),0) as settled_waz
-    FROM binary_score_records WHERE user_id = ?
-  `).get(userId);
-    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 {
@@ -3496,15 +3684,12 @@ async function handleReferral(args) {
             l1: byLevel[1], l2: byLevel[2], l3: byLevel[3],
             grand_total: byLevel[1].total + byLevel[2].total + byLevel[3].total,
         },
-        binary: {
-            // pre-public 去左右码:只暴露唯一的推荐码;放置侧别由系统自动决定(无 left/right 选择)
+        placement: {
+            // Neutral participation/attribution record: a single referral code + per-leg PV. No matching rewards.
             referral_link: permaCode ? `/i/${permaCode}` : null,
             total_left_pv: Number(me?.total_left_pv ?? 0),
             total_right_pv: Number(me?.total_right_pv ?? 0),
-            pair_volume: pair,
-            next_tier: nextTier ? { tier: nextTier.tier, pv_threshold: nextTier.pv_threshold, score_per_hit: nextTier.score_per_hit, pv_needed: nextTier.pv_threshold - pair } : null,
-            score_pending: score.pending,
-            waz_total_earned: score.settled_waz,
+            note: 'total_left_pv / total_right_pv are a participation / attribution record only — not income, not redeemable, no entitlement.',
         },
         rewards_status: (() => {
             // RFC-002 §3.5 — 4 states + pending escrow visibility (PR-4)
@@ -4940,7 +5125,7 @@ export async function startMCPServer() {
             // ─── RFC-003 Batch 0 安全网:NETWORK 模式下未迁移的工具【硬失败】,不静默落本地沙盒 ───
             // 例外:info / register(NETWORK_SELF_AWARE)有专门 network-aware 处理,照常放行。
             let handled = false;
-            if (isNetworkMode() && !NETWORK_TOOLS.has(name) && !NETWORK_SELF_AWARE.has(name)) {
+            if (isNetworkMode() && !toolAllowedInNetworkMode(name)) {
                 result = networkMigrationPending(name);
                 handled = true;
             }
@@ -4949,6 +5134,9 @@ export async function startMCPServer() {
                     case 'webaz_info':
                         result = await handleInfo();
                         break;
+                    case 'webaz_pair':
+                        result = await handlePair(args);
+                        break;
                     case 'webaz_register':
                         result = handleRegister(args);
                         break;