@bolloon/bolloon-agent 0.4.32 → 0.5.0

package/dist/cli/commands/tasks.js

@@ -40,9 +40,49 @@ ${title('bolloon task')}
   bolloon task reject <requestId|taskId> --reason "<原因>"
   bolloon task complete|cancel              仍未实现 → 如实报 C_NOT_IMPLEMENTED
 
+  ── 任务对外发布 + 接单 (C1/C2, 2026-09-23: 公告板) ──
+  bolloon task publish --capability research --instruction "调研 X" --budget 0.05 \\
+      [--currency USDC] [--network base-sepolia] [--deadline +24h] [--reply-to http://me:port]
+      发布一条**待接单**任务: 落盘 ~/.bolloon/tasks/board/<announcementId>.json +
+      向 agent-registry 公告 (service.name = task.announce) + 记脉冲事件 task_announced;
+      输出稳定 announcementId (同一 能力+正文+买方+预算 → 同一个 id, 重发幂等)
+  bolloon task board [--json] [--capability <名>] [--open] [--local]
+      板上可接单的任务: **本地公告 + 注册表发现的远端公告**, 按 announcementId 去重
+  bolloon task claim <announcementId> [--price 0.02] [--group <群链接|groupId>]
+      provider 接单: 记认领者 DID + 时间 + 声明价格 (不执行、不付款、不标 verified);
+      重复认领 / 已取消 / 不存在的 id → 一律拒绝并给原因;
+      带 --group 时: 往群里发一条极短接单声明 (群非法 → 整条命令拒绝, 不静默降级)
+
+  ── 群聊通道 (C7, 2026-09-23: 过程留痕) ──
+  bolloon task announce --group <群链接|groupId> [--announcement-id <id>] [--capability <名>]
+      [--round <期号>] [--criteria "<验收判据摘要>"] [--from <短显示名>] [--json]
+      把板上**一条待接单公告**压成一行极短事实 (期号 · capability · 预算 · 判据摘要 · 公告 id) 发进群;
+      正文不进群; 缺 --group / 群非法 / 本机没这个群 → 拒绝执行 (绝不降级为只写本地)
+  bolloon task trail --group <群链接|groupId> [--announcement-id <id>] [--limit 300] [--json]
+      从群消息读回本期过程留痕 (公告/接单/交付/初筛/终审) → 按时间排序的时间线, 每条带时间 + 发送者标记
+  bolloon task post --kind deliver|screen|final --group <群链接|groupId> --announcement-id <id> \\
+      [--hash sha256:<hex>] [--bytes <n>] [--checks "渠道结构=pass,价格带=fail"] [--verdict accept|reject|unknown]
+      [--round <期号>] [--from <短显示名>] [--json]
+      交付只贴哈希 · 初筛逐条结果 · 终审结论; 群消息一律无钱包地址/DID/peerId/multiaddr/IP/私钥形态
+      (命中任一条 → 拒发并报出命中的规则)
+
+  ── 群管理 (2026-09-24: 外部接单者的自助入群入口) ──
+  bolloon task group create --name <群名> [--from <短显示名>] [--json]
+      建群 → 打印**邀请链接** (发给要入群的人) + groupId; 落 ~/.bolloon/gateway-groups.json
+      (ACL write:['*'] = 成员可广播, 建群时写进 store manifest)
+  bolloon task group join <群链接|groupId> [--json]
+      用**链接**自助入群 (幂等: 已在群里 → already=true, 仍 exit 0);
+      store 拿不到区块 → 大声失败 (TRANSPORT_FAILED + storeCode=STORE_UNREACHABLE), 绝不显示成空群
+  bolloon task group list [--json]         本机已加入的群 (groupId · 群名 · 加入时间); 没有群 → 空列表
+  bolloon task group link <groupId|群名>   显式取回邀请链接 (list 里不放链接)
+  bolloon task group leave <groupId|群名>  退群 (只摘本机记录)
+      群管理输出不含原始 DID/钱包地址/peerId/节点 multiaddr/IP (脱敏口径与群消息同源)
+
 选项: --json · --quiet · --request-id <id> · --timeout <ms> · --resume <goalId> (同 bolloon task)
 说明: 收件箱落盘 ~/.bolloon/tasks/inbox/; 本机发出的任务台账 ~/.bolloon/tasks/local/;
-      结果 ~/.bolloon/tasks/results/, 交付正文 ~/.bolloon/tasks/bodies/ (私有层, 不进 stdout)。
+      结果 ~/.bolloon/tasks/results/, 交付正文 ~/.bolloon/tasks/bodies/ (私有层, 不进 stdout);
+      任务公告 ~/.bolloon/tasks/board/ (正文只在本地, 注册表里只有 sha256 摘要 + 60 字预览);
+      群里的过程痕迹**只在群里** (群消息就是留痕本体, 本机不留影子副本); 结算仍只在链上。
 `;
 /** 交易记录判定 (P1 §5.1 红线: local-dev 永不 verified; 成功判据见 §7.1) */
 function judge(rec) {
@@ -135,6 +175,14 @@ export async function taskCommand(flags) {
         case 'reject': return taskReject(flags);
         case 'complete': return taskComplete(flags);
         case 'cancel': return taskCancel(flags);
+        case 'publish': return taskPublish(flags);
+        case 'board': return taskBoard(flags);
+        case 'claim': return taskClaim(flags);
+        case 'announce': return taskAnnounce(flags);
+        case 'trail': return taskTrail(flags);
+        case 'post': return taskPost(flags);
+        // 2026-09-24: 群管理 (create/join/list/link/leave) —— 外部接单者的自助入群入口
+        case 'group': return taskGroup(flags);
         default:
             return {
                 envelope: failEnvelope('INVALID_ARGUMENT', sub ? `未知 task 子命令: ${sub}` : '缺少 task 子命令', { usage: plain(TASK_USAGE.trim()) }, [], 'needs_human'),
@@ -641,7 +689,7 @@ function parseInput(raw) {
 }
 // ── bolloon-task/1 真收发: send / inbox / accept / reject ────────────────────
 /** 人类单位 → 原子单位正整数串 (拒绝 0 / 负 / 超精度; 浮点模糊一律拒) */
-function toAtomic(human, decimals) {
+export function toAtomic(human, decimals) {
     const s = String(human ?? '').trim();
     if (!/^[0-9]+(\.[0-9]+)?$/.test(s))
         return null;
@@ -652,7 +700,7 @@ function toAtomic(human, decimals) {
     return n > 0n ? n.toString() : null;
 }
 /** `--deadline +2h` / `+30m` / `+45s` / `+1d`, 或未来毫秒时间戳 */
-function parseDeadline(v, now = Date.now()) {
+export function parseDeadline(v, now = Date.now()) {
     if (v === undefined)
         return now + 24 * 60 * 60 * 1000;
     const m = /^\+(\d+)(s|m|h|d)$/.exec(String(v).trim());
@@ -735,6 +783,32 @@ function transferView(t) {
     return t ? { kind: t.kind, target: t.target, ok: t.ok, elapsedMs: t.elapsedMs, duplicate: t.duplicate === true, error: t.error || null, detail: t.detail || null } : null;
 }
 // ── send ────────────────────────────────────────────────────────────────────
+/**
+ * 没有匹配的 provider 时: 板上若有**可接单**的公告 → 给可操作提示 (指向 board/claim)。
+ * 拿不到板上的事实 → `hint:null` + 如实带 `boardError` (不猜、不假装有公告)。
+ */
+async function boardHintForCapability(capability) {
+    try {
+        const { findOpenAnnouncementsForCapability } = await import('../../agents/task-board.js');
+        const open = await findOpenAnnouncementsForCapability(capability);
+        if (!open.length)
+            return { count: 0, announcements: [], hint: null, boardError: null };
+        const first = open[0];
+        return {
+            count: open.length,
+            announcements: open.slice(0, 5).map((a) => ({
+                announcementId: a.announcementId, capability: a.capability, status: a.status,
+                budget: a.budget, deadline: a.deadline, buyer: a.buyerShort, remote: a.remote,
+                signatureVerified: a.signatureVerified,
+            })),
+            hint: `板上有 ${open.length} 条可接单的 '${capability}' 任务: 先 bolloon task board 看全, 或直接 bolloon task claim ${first.announcementId}`,
+            boardError: null,
+        };
+    }
+    catch (e) {
+        return { count: 0, announcements: [], hint: null, boardError: String(e?.message || e).slice(0, 160) };
+    }
+}
 async function taskSend(flags) {
     const instruction = opt(flags, '--instruction') || flags.positionals.slice(1).join(' ').trim();
     const capability = opt(flags, '--capability');
@@ -810,18 +884,29 @@ async function taskSend(flags) {
             providerDid = providerDid || resolved.target.providerDid || '';
         }
         else if (via === 'gateway') {
+            const boardHint = await boardHintForCapability(capability);
             return {
-                envelope: failEnvelope('CAPABILITY_NOT_FOUND', `注册表里没有能力 '${capability}' 的 provider (registry ${resolved.registryReady ? '就绪' : '未就绪'}, ${resolved.candidates} 条候选)`, { capability, registryReady: resolved.registryReady, candidates: resolved.candidates, via: 'gateway' }, [], 'redefine_capability'),
-                human: `${title('bolloon task send')}\n  注册表里没有这个能力的 provider, gateway 传输没有目标`,
+                envelope: failEnvelope('CAPABILITY_NOT_FOUND', `注册表里没有能力 '${capability}' 的 provider (registry ${resolved.registryReady ? '就绪' : '未就绪'}, ${resolved.candidates} 条候选)${boardHint.hint ? `；${boardHint.hint}` : ''}`, { capability, registryReady: resolved.registryReady, candidates: resolved.candidates, via: 'gateway', board: boardHint }, [], 'redefine_capability'),
+                human: [
+                    `${title('bolloon task send')}`,
+                    `  注册表里没有这个能力的 provider, gateway 传输没有目标`,
+                    ...(boardHint.hint ? [`\n  ${hint(boardHint.hint)}`] : []),
+                ].join('\n'),
             };
         }
         else {
             const joined = resolved.registryReady;
+            const boardHint = await boardHintForCapability(capability);
             return {
                 envelope: failEnvelope(joined ? 'CAPABILITY_NOT_FOUND' : 'NETWORK_NOT_JOINED', joined
-                    ? `注册表里没有能力 '${capability}' 的 provider (${resolved.candidates} 条候选, 且都没有 endpoint)`
-                    : '本机 registry 未就绪 (没有入网/没拉过任何服务声明), 无法解析目标', { capability, registryReady: joined, candidates: resolved.candidates, howTo: '用 --endpoint http://host:port 显式给目标, 或先 bolloon network join / bolloon agent register' }, [], joined ? 'redefine_capability' : 'rejoin_network'),
-                human: `${title('bolloon task send')}\n  ${joined ? '注册表里没有这个能力' : '本机还没入网, 也没有显式 --endpoint'}\n\n${hint('示例: bolloon task send --capability research --instruction "…" --endpoint http://127.0.0.1:54901')}`,
+                    ? `注册表里没有能力 '${capability}' 的 provider (${resolved.candidates} 条候选, 且都没有 endpoint)${boardHint.hint ? `；${boardHint.hint}` : ''}`
+                    : `本机 registry 未就绪 (没有入网/没拉过任何服务声明), 无法解析目标`, { capability, registryReady: joined, candidates: resolved.candidates, board: boardHint, howTo: '用 --endpoint http://host:port 显式给目标, 或先 bolloon network join / bolloon agent register' }, [], joined ? 'redefine_capability' : 'rejoin_network'),
+                human: [
+                    `${title('bolloon task send')}`,
+                    `  ${joined ? '注册表里没有这个能力' : '本机还没入网, 也没有显式 --endpoint'}`,
+                    ...(boardHint.hint ? [`\n  ${hint(boardHint.hint)}`] : []),
+                    `\n${hint('示例: bolloon task send --capability research --instruction "…" --endpoint http://127.0.0.1:54901')}`,
+                ].join('\n'),
             };
         }
     }
@@ -1216,6 +1301,890 @@ async function taskReject(flags) {
         ].join('\n'),
     };
 }
+// ── publish / board / claim (C1/C2 任务对外发布 + 接单, 2026-09-23) ──────────
+/** 板上一行的对外投影 (不含正文; 远端认领数的诚实标注) */
+function boardEntryView(e) {
+    return {
+        announcementId: e.announcementId,
+        capability: e.capability,
+        buyer: e.buyerShort,
+        status: e.status,
+        budget: e.budget,
+        deadline: e.deadline,
+        deadlineInMs: e.deadlineInMs,
+        claimCount: e.claimCount,
+        claimedBy: e.claimedBy,
+        claimedAt: e.claimedAt,
+        remote: e.remote,
+        source: e.source,
+        signatureVerified: e.signatureVerified,
+        claimable: e.claimable,
+        instructionDigest: e.instructionDigest,
+        instructionPreview: e.instructionPreview,
+    };
+}
+async function taskPublish(flags) {
+    const capability = opt(flags, '--capability');
+    const instruction = opt(flags, '--instruction') || flags.positionals.slice(1).join(' ').trim();
+    const budgetHuman = opt(flags, '--budget');
+    if (!capability || !instruction) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 --capability 或 --instruction (公告必须有能力和任务正文)', { usage: plain(TASK_USAGE.trim()), got: { capability: capability || null, instruction: !!instruction } }, [], 'needs_human'),
+            human: `${TASK_USAGE}\n${hint('示例: bolloon task publish --capability research --instruction "调研某类厨房用品的日本市场" --budget 0.05')}`,
+        };
+    }
+    const currency = String(opt(flags, '--currency') || 'USDC').toUpperCase();
+    if (currency !== 'USDC' && currency !== 'ETH') {
+        return { envelope: failEnvelope('INVALID_ARGUMENT', `--currency 只支持 USDC/ETH (收到 ${currency})`, { currency }, [], 'needs_human'), human: TASK_USAGE };
+    }
+    const network = opt(flags, '--network') || 'base-sepolia';
+    if (budgetHuman === undefined) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 --budget (待接单的公告必须带预算: 没有预算就没有可核验的委托口径)', { usage: plain(TASK_USAGE.trim()), accepted: ['--budget 0.05'] }, [], 'needs_human'),
+            human: `${TASK_USAGE}\n${hint('示例: bolloon task publish --capability research --instruction "…" --budget 0.05')}`,
+        };
+    }
+    const atomic = toAtomic(budgetHuman, currency === 'USDC' ? 6 : 18);
+    if (!atomic) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', `--budget 必须是正数 (收到 ${budgetHuman}); 原子单位串由本命令换算, 不接受 0/负/超精度`, { budget: budgetHuman, currency, accepted: ['--budget 0.05'] }, [], 'needs_human'),
+            human: TASK_USAGE,
+        };
+    }
+    const modeRaw = opt(flags, '--mode') || 'policy';
+    const { isPaymentMode } = await import('../../agents/task-contract.js');
+    if (!isPaymentMode(modeRaw)) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', `--mode 非法: ${modeRaw} (要 manual|policy|autonomous|agent-authorized)`, { mode: modeRaw }, [], 'needs_human'),
+            human: TASK_USAGE,
+        };
+    }
+    const dl = parseDeadline(opt(flags, '--deadline'));
+    if (typeof dl === 'string') {
+        return { envelope: failEnvelope('INVALID_ARGUMENT', dl, { deadline: opt(flags, '--deadline') }, [], 'needs_human'), human: TASK_USAGE };
+    }
+    const s = await requireSigner('bolloon task publish');
+    if ('fail' in s)
+        return s.fail;
+    const signer = s.signer;
+    const { publishAnnouncement } = await import('../../agents/task-board.js');
+    const r = await publishAnnouncement({
+        capability, instruction,
+        buyerDid: signer.did,
+        buyerPublicKeyHex: signer.publicKeyHex,
+        budget: { maxAmount: atomic, currency, network },
+        deadline: dl,
+        paymentMode: modeRaw,
+        replyTo: opt(flags, '--reply-to') || null,
+        signerKeypair: signer.keypair,
+    });
+    if (!r.ok || !r.announcement) {
+        return {
+            envelope: failEnvelope('INTERNAL_ERROR', `公告没发布成功: ${r.error || '未知原因'}`, { capability, announcementId: null, paid: false, fundsMoved: false }, [], 'needs_human'),
+            human: `${title('bolloon task publish')}\n  没发布成功: ${r.error || '未知原因'}`,
+        };
+    }
+    const a = r.announcement;
+    const data = {
+        announcementId: a.announcementId,
+        capability: a.capability,
+        buyerDid: a.buyerDid,
+        status: a.status,
+        budget: a.budget,
+        deadline: a.deadline,
+        paymentMode: a.paymentMode,
+        instructionDigest: a.instructionDigest,
+        instructionPreview: a.instructionPreview,
+        signed: r.signed,
+        duplicate: r.dup,
+        registry: r.registry,
+        pulse: r.pulse,
+        file: r.file || `~/.bolloon/tasks/board/${a.announcementId}.json`,
+        registryService: 'task.announce (agent-registry; description 里只有摘要+预览, 没有正文)',
+        paid: false,
+        fundsMoved: false,
+        note: '公告只是"把待接单的任务放出去": 不执行、不付款、不产生交易; 接单: bolloon task claim <announcementId>',
+    };
+    const human = [
+        title('bolloon task publish'),
+        line('公告号', a.announcementId),
+        line('capability', a.capability),
+        line('预算', a.budget ? `≤ ${a.budget.maxAmount} 原子 (${a.budget.currency} @ ${a.budget.network})` : '(无)'),
+        line('截止时间', new Date(a.deadline).toISOString()),
+        line('签名', r.signed ? '已签名 (覆盖公开载荷: 能力/预算/截止/正文摘要)' : '**没有签名** (没有本机身份 → 接单会被拒)'),
+        line('注册表', r.registry.attempted ? (r.registry.announced ? `已公告 (${r.registry.entries} 条 capability)` : `没公告: ${r.registry.error || '未知'}`) : '没有尝试 (离线)'),
+        line('脉冲事件', r.pulse.attempted ? (r.pulse.ok ? 'task_announced 已记' : `没记: ${r.pulse.reason || '未知'}`) : '没有尝试 (离线)'),
+        r.dup ? line('重复发布', '同一 (能力+正文+买方+预算) → 复用既有公告 (幂等), 没覆盖既有认领') : '',
+        line('本次付款', '没有 (发布公告不付款)'),
+        `\n  ${hint('下一步: 别人看板 bolloon task board · 接单 bolloon task claim ' + a.announcementId)}`,
+    ].filter(Boolean).join('\n');
+    return {
+        envelope: okEnvelope('OK', `已发布待接单任务 ${a.announcementId} (${a.capability})${r.dup ? ' — 复用既有公告 (幂等)' : ''}`, data, [a.announcementId], null),
+        human,
+    };
+}
+async function taskBoard(flags) {
+    const { listBoard } = await import('../../agents/task-board.js');
+    const capFilter = opt(flags, '--capability');
+    const openOnly = has(flags, '--open');
+    const localOnly = has(flags, '--local');
+    const view = await listBoard({ openOnly, localOnly });
+    const capLower = String(capFilter || '').trim().toLowerCase();
+    const entries = capLower ? view.entries.filter((e) => String(e.capability).trim().toLowerCase() === capLower) : view.entries;
+    const data = {
+        count: entries.length,
+        local: view.localCount,
+        remote: view.remoteCount,
+        duplicatesDeduped: view.duplicates,
+        filter: { capability: capFilter || null, openOnly, localOnly },
+        registryReady: view.registryReady,
+        registryError: view.registryError,
+        dir: '~/.bolloon/tasks/board',
+        entries: entries.map(boardEntryView),
+        notes: view.notes,
+        note: '板上只有摘要/预览: 任务正文只在买方本地; 接单: bolloon task claim <announcementId>',
+        next: entries.some((e) => e.claimable) ? `bolloon task claim ${entries.find((e) => e.claimable).announcementId}` : null,
+    };
+    const human = entries.length
+        ? entries.map((e) => [
+            `\n  ${e.announcementId}${e.remote ? ' (远端公告)' : ''}`,
+            `    capability ${e.capability}`,
+            `    买方       ${e.buyerShort || '(无)'}`,
+            `    状态       ${e.status}${e.claimable ? ' · 可接单' : e.status === 'open' ? ' · 已过期' : ''}`,
+            `    预算       ${e.budget ? `≤ ${e.budget.maxAmount} 原子 ${e.budget.currency} @ ${e.budget.network}` : '(无)'}`,
+            `    截止时间   ${e.deadline ? `${new Date(e.deadline).toISOString()}${e.deadlineInMs !== null ? ` (${e.deadlineInMs > 0 ? `还剩 ${Math.round(e.deadlineInMs / 1000)}s` : '已过期'})` : ''}` : '(无)'}`,
+            `    认领       ${e.claimCount === 0 ? '还没有人接' : `${e.claimCount} 人 (最近: ${String(e.claimedBy).slice(0, 24)})`}${e.remote ? ' · 远端的认领数本机看不到' : ''}`,
+            `    签名       ${e.signatureVerified === true ? '验签通过' : e.signatureVerified === false ? '**验签不过** (接不了单)' : '未验签(如实)'}`,
+            `    预览       ${e.instructionPreview || '(无)'}`,
+        ].join('\n')).join('')
+        : '\n  (板上没有可接单的任务)';
+    return {
+        envelope: okEnvelope('OK', `板上 ${entries.length} 条${openOnly ? '可接单' : ''}公告 (本地 ${view.localCount} · 远端 ${view.remoteCount})${capFilter ? ` [capability=${capFilter}]` : ''}`, data, entries.map((e) => e.announcementId), null),
+        human: [
+            `${title('bolloon task board')}${human}`,
+            '',
+            `  ${String(data.note)}`,
+            view.registryError ? `  ${hint(`注册表读取失败 (远端公告可能不全): ${view.registryError}`)}` : '',
+            data.next ? `\n  ${hint('下一步: ' + data.next)}` : '',
+        ].filter(Boolean).join('\n'),
+    };
+}
+async function taskClaim(flags) {
+    const id = flags.positionals[1] || opt(flags, '--announcement-id') || flags.requestId;
+    if (!id) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 announcementId (bolloon task claim <announcementId>)', { usage: plain(TASK_USAGE.trim()) }, [], 'needs_human'),
+            human: `${TASK_USAGE}\n${hint('先看板: bolloon task board')}`,
+        };
+    }
+    const s = await requireSigner('bolloon task claim');
+    if ('fail' in s)
+        return s.fail;
+    const signer = s.signer;
+    // ★ C7: 带 --group 时**在认领之前**把群定死 —— 群非法/没加入 → 整条命令拒绝 (绝不"认领落本地 + 悄悄不发群")
+    const wantsGroup = opt(flags, '--group') !== undefined;
+    const gctx = wantsGroup ? await requireGroup('bolloon task claim ' + id, flags) : null;
+    if (gctx && !gctx.ok)
+        return gctx.result;
+    // 声明价格 (可选): 不声明 → null, 不替它猜
+    const priceHuman = opt(flags, '--price');
+    const currency = String(opt(flags, '--currency') || 'USDC').toUpperCase();
+    let priceAtomic = null;
+    if (priceHuman !== undefined) {
+        priceAtomic = toAtomic(priceHuman, currency === 'USDC' ? 6 : 18);
+        if (!priceAtomic) {
+            return {
+                envelope: failEnvelope('INVALID_ARGUMENT', `--price 必须是正数 (收到 ${priceHuman})`, { price: priceHuman, currency, accepted: ['--price 0.02'] }, [], 'needs_human'),
+                human: TASK_USAGE,
+            };
+        }
+    }
+    const { claimAnnouncement } = await import('../../agents/task-board.js');
+    const r = await claimAnnouncement(id, {
+        providerDid: signer.did,
+        providerPublicKeyHex: signer.publicKeyHex,
+        priceAmountAtomic: priceAtomic,
+        currency,
+        network: opt(flags, '--network') || '',
+        signerKeypair: signer.keypair,
+    });
+    const baseData = {
+        announcementId: id,
+        reason: r.reason,
+        remote: r.remote,
+        // ★ 本命令任何路径都不动钱、不执行、不标 verified
+        executed: false,
+        paid: r.paid,
+        fundsMoved: r.fundsMoved,
+        verified: r.verified,
+        deliveredToBuyer: r.deliveredToBuyer,
+    };
+    if (!r.ok) {
+        const code = r.reason === 'not_found' ? 'NOT_FOUND'
+            : r.reason === 'already_claimed' ? 'DUPLICATE_REQUEST'
+                : r.reason === 'cancelled' ? 'TASK_CANCELLED'
+                    : r.reason === 'signature_invalid' || r.reason === 'instruction_digest_mismatch' ? 'SIGNATURE_INVALID'
+                        : r.reason === 'deadline_expired' ? 'DEADLINE_EXPIRED'
+                            : 'INVALID_ARGUMENT';
+        return {
+            envelope: failEnvelope(code, `没接成单: ${r.message}`, { ...baseData, status: r.status ?? null, existingClaim: r.existingClaim ?? null }, [id], 'needs_human'),
+            human: `${title('bolloon task claim ' + id)}\n  ${r.message}\n${line('本次付款', '没有')}\n\n${hint('看板: bolloon task board')}`,
+        };
+    }
+    const c = r.claim;
+    // ★ C7: 认领成功 → 往群里发一条极短接单声明 (群已在认领**之前**定死; 这里最坏也只是"发失败")
+    let groupPost = null;
+    if (gctx && gctx.ok) {
+        const TG = await import('../../agents/task-group.js');
+        const priceTok = c.priceAmountAtomic ? `${c.priceAmountAtomic}${String(c.currency || '').toUpperCase()}` : null;
+        const built = TG.buildPostMessage({ kind: 'claim', announcementId: id, price: priceTok });
+        const sent = built.ok
+            ? await TG.sendTrailMessage(gctx.group.groupId, built.text, gctx.fromTag)
+            : { ok: false, sent: false, error: built.message, violations: null };
+        groupPost = {
+            requested: true,
+            posted: sent.sent === true,
+            error: sent.sent ? null : (sent.error || '未知原因'),
+            message: built.ok ? built.text : null,
+            group: gctx.group.groupId,
+            senderTag: gctx.fromTag,
+            localFallback: false,
+            /** 群消息没发出去**不等于**认领没发生: 认领事实已写进本地账 (上面那步真写过了) */
+            claimStillRecorded: true,
+        };
+    }
+    else if (!wantsGroup) {
+        groupPost = { requested: false, posted: false, reason: '没有 --group: 本命令原有语义不变 (只记本地认领账); 群里留痕要显式给 --group' };
+    }
+    const data = {
+        ...baseData,
+        claim: {
+            providerDid: c.providerDid,
+            providerPublicKeyHex: c.providerPublicKeyHex ? `${String(c.providerPublicKeyHex).slice(0, 16)}…` : null,
+            claimedAt: c.claimedAt,
+            priceAmountAtomic: c.priceAmountAtomic,
+            currency: c.currency,
+            network: c.network,
+            signed: !!c.signature,
+        },
+        status: r.status ?? null,
+        file: r.file,
+        priceNote: r.priceNote ?? null,
+        /** C7 群聊侧: 认领有没有在群里留下接单声明 (发失败也如实标; 认领事实不受影响) */
+        group: groupPost,
+        honestyNote: r.remote
+            ? '远端公告的认领只落本机台账 (**没有投递给买方**); 真交接走 bolloon task send → 对方 task accept'
+            : '认领只是"我来做"的本地事实: 不执行任务、不付款、不标 verified (释放/验真另走裁决函数)',
+    };
+    const groupNext = groupPost && groupPost.requested === true && groupPost.posted !== true ? 'needs_human' : null;
+    return {
+        envelope: okEnvelope('OK', `${r.message}${groupPost && groupPost.requested === true ? (groupPost.posted === true ? ' (接单声明已进群)' : ' (接单声明没发进群)') : ''}`, data, [id], groupNext ?? (r.remote ? 'needs_human' : null)),
+        human: [
+            title('bolloon task claim ' + id),
+            line('认领者', c.providerDid),
+            line('认领时间', new Date(c.claimedAt).toISOString()),
+            line('声明价格', c.priceAmountAtomic ? `${c.priceAmountAtomic} 原子 ${c.currency}` : '(没声明价)'),
+            line('公告来源', r.remote ? '注册表 (远端)' : '本地公告文件'),
+            line('投递给买方', r.deliveredToBuyer ? '已投递' : '**没有** (本版没有远端认领投递通道; 真交接走 task send/accept)'),
+            ...(groupPost ? [line('群聊留痕', groupPost.requested === true
+                    ? (groupPost.posted === true ? `接单声明已进群 (发送者标记 ${String(groupPost.senderTag)})` : `**没发进群**: ${String(groupPost.error)} — 认领事实已记账, 但群里没有这条痕迹`)
+                    : `没有 --group: 只记本地账 (${String(groupPost.reason)})`)] : []),
+            line('本次执行', '没有 (接单不执行任务)'),
+            line('本次付款', '没有 (接单不付款)'),
+            r.remote ? `\n  ${hint('下一步: 让买方把任务发过来 (bolloon task send); 对方 accept 后才有执行/交付')}` : `\n  ${hint('下一步: 等买方的 task send/accept; 交付后用 decideAnnouncementRelease 判是否可释放 (未交付不得释放)')}`,
+        ].join('\n'),
+    };
+}
+// ── 群聊通道 (C7: announce / trail / post, 2026-09-23) ───────────────────────
+/** C7 群上下文: 群必须先定下来 (缺/非法/没加入 → 拒跑); 发送者标记只用短假名 */
+async function requireGroup(head, flags) {
+    const TG = await import('../../agents/task-group.js');
+    const ref = opt(flags, '--group');
+    const g = await TG.resolveGroupRef(ref);
+    if (!g.ok) {
+        return {
+            ok: false,
+            result: {
+                envelope: failEnvelope(g.code, `${g.message}`, { group: ref ?? null, ...g.detail, sent: false, localFallback: false, why: '缺群/群非法/群没加入一律拒绝执行: 本命令不做"只写本地"的降级' }, [], 'needs_human'),
+                human: [
+                    title(head),
+                    `  群没定下来: ${g.message}`,
+                    '',
+                    hint('群聊通道就是留痕的地方: 没有群就没有留痕 —— 这里不会静默降级成只写本地'),
+                    ...(Array.isArray(g.detail.joined) && g.detail.joined.length
+                        ? [line('本机已加入的群', g.detail.joined.map((x) => `${x.id}${x.name ? ` (${x.name})` : ''}`).join(' · '))]
+                        : [line('本机已加入的群', '(没有)')]),
+                ].join('\n'),
+            },
+        };
+    }
+    const s = await TG.resolveSenderTag(opt(flags, '--from'));
+    if (!s.ok) {
+        return {
+            ok: false,
+            result: {
+                envelope: failEnvelope(s.code, `${s.message}`, { ...s.detail, group: g.group, sent: false, localFallback: false }, [], 'needs_human'),
+                human: `${title(head)}\n  发送者标记定不下来: ${s.message}\n\n${hint('群里只出现短假名 (agent-xxxxxxxx) 或 --from 给的短显示名; 原始 DID 永不进群')}`,
+            },
+        };
+    }
+    return { ok: true, group: g.group, fromTag: s.tag, fromSource: s.source };
+}
+/** 时间线条目 → 对外投影 (不含原消息文本; 字段已被遮蔽过) */
+function trailEntryView(e) {
+    return { kind: e.kind, at: e.at, atIso: e.at ? new Date(e.at).toISOString() : null, sender: e.sender, announcementId: e.announcementId, fields: e.fields };
+}
+/**
+ * `bolloon task announce --group <群链接|groupId>` —— 把板上一条待接单公告压成一行极短事实发进群。
+ * 内容只有: 期号 · capability · 预算 · 验收判据摘要 · 公告 id (任务正文不进群)。
+ */
+async function taskAnnounce(flags) {
+    const head = 'bolloon task announce';
+    const ctx = await requireGroup(head, flags);
+    if (!ctx.ok)
+        return ctx.result;
+    const TG = await import('../../agents/task-group.js');
+    const picked = TG.pickAnnouncement({ announcementId: opt(flags, '--announcement-id'), capability: opt(flags, '--capability') });
+    if (!picked.ok) {
+        return {
+            envelope: failEnvelope(picked.code, picked.message, { ...picked.detail, group: ctx.group, sent: false, localFallback: false }, [], 'needs_human'),
+            human: `${title(head)}\n  没得可发: ${picked.message}\n\n${hint('先看板: bolloon task board; 发公告: bolloon task publish --capability … --instruction "…" --budget 0.05')}`,
+        };
+    }
+    const a = picked.announcement;
+    const text = TG.buildAnnounceMessage(a, { round: opt(flags, '--round'), criteria: opt(flags, '--criteria') });
+    const sent = await TG.sendTrailMessage(ctx.group.groupId, text, ctx.fromTag);
+    if (!sent.ok) {
+        const violations = sent.violations || null;
+        return {
+            envelope: failEnvelope(violations ? 'POLICY_DENIED' : 'TRANSPORT_FAILED', violations ? `公告命中隐私红线, 拒绝发进群: ${violations.map((v) => v.rule).join(', ')}` : `群消息没发出去: ${sent.error}`, { announcementId: a.announcementId, group: ctx.group.groupId, message: text, sent: false, violations, localFallback: false, paid: false }, [a.announcementId], 'needs_human'),
+            human: [
+                title(head),
+                `  ${violations ? '命中隐私红线, 拒发' : '没发出去'}: ${sent.error}`,
+                ...(violations ? violations.map((v) => `    · ${v.rule} — ${v.why} (${v.masked}, ${v.chars} 字符)`) : []),
+                '',
+                hint(violations ? '把公告的预览/判据摘要改成不含标识符的短事实后重发 (本命令不静默脱敏: 脱敏后的公告不是你要发的那条)' : '群 store 不可达时不会落本地: 就是没发出去'),
+            ].join('\n'),
+        };
+    }
+    const data = {
+        announcementId: a.announcementId,
+        capability: a.capability,
+        budget: a.budget,
+        deadline: a.deadline,
+        round: opt(flags, '--round') || null,
+        judgeStated: !!opt(flags, '--criteria'),
+        message: sent.text,
+        group: { id: ctx.group.groupId, name: ctx.group.name, via: ctx.group.via },
+        sender: { tag: ctx.fromTag, source: ctx.fromSource, didPrinted: false },
+        /** 群里只有过程事实: 不执行、不付款、不标 verified */
+        executed: false,
+        paid: false,
+        fundsMoved: false,
+        localFallback: false,
+        note: '公告入群只发极短事实 (期号/capability/预算/判据摘要/公告 id): 任务正文不进群; 群里的话不替代链上 releaseV2',
+    };
+    return {
+        envelope: okEnvelope('OK', `已把公告 ${a.announcementId} 发进群 (${a.capability})`, data, [a.announcementId], null),
+        human: [
+            title(head),
+            line('公告号', a.announcementId),
+            line('capability', a.capability),
+            line('预算', a.budget ? `≤ ${a.budget.maxAmount} 原子 (${a.budget.currency} @ ${a.budget.network})` : '(无)'),
+            line('期号', opt(flags, '--round') || '(未标)'),
+            line('判据摘要', opt(flags, '--criteria') || `未声明 (只放任务书摘要 sha256:${String(a.instructionDigest || '').slice(0, 16)}…)`),
+            line('群', `${ctx.group.name || '(无名)'} · ${ctx.group.groupId}`),
+            line('发送者标记', `${ctx.fromTag} (${ctx.fromSource === 'identity' ? '本机身份派生假名' : '--from 显式'}; 原始 DID 未进群)`),
+            line('本次执行/付款', '没有 (公告入群只是过程留痕)'),
+            '',
+            hint(`下一步: 别人 bolloon task claim ${a.announcementId} --group <群链接>; 回看留痕: bolloon task trail --group <群链接>`),
+        ].join('\n'),
+    };
+}
+/** `bolloon task trail --group <群链接|groupId>` —— 从群消息读回本期过程痕迹并汇总成时间线 */
+async function taskTrail(flags) {
+    const head = 'bolloon task trail';
+    const ctx = await requireGroup(head, flags);
+    if (!ctx.ok)
+        return ctx.result;
+    const TG = await import('../../agents/task-group.js');
+    const limitRaw = opt(flags, '--limit');
+    const limit = limitRaw === undefined ? 300 : Number(limitRaw);
+    if (limitRaw !== undefined && (!Number.isFinite(limit) || limit < 1)) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', `--limit 必须是正数 (收到 ${limitRaw})`, { limit: limitRaw }, [], 'needs_human'),
+            human: TASK_USAGE,
+        };
+    }
+    let summary;
+    try {
+        summary = await TG.readTrail(ctx.group.groupId, { limit, announcementId: opt(flags, '--announcement-id') });
+    }
+    catch (e) {
+        return {
+            envelope: failEnvelope('TRANSPORT_FAILED', `群消息读不出来: ${String(e?.message || e).slice(0, 160)}`, { group: ctx.group.groupId, read: false, localFallback: false }, [], 'needs_human'),
+            human: `${title(head)}\n  群消息读不出来: ${String(e?.message || e).slice(0, 160)}\n\n${hint('群不可达时如实报错: 不用本地缓存假装读过群')}`,
+        };
+    }
+    const data = {
+        group: { id: ctx.group.groupId, name: ctx.group.name, via: ctx.group.via },
+        count: summary.count,
+        byKind: summary.byKind,
+        announcements: summary.announcements,
+        flags: summary.flags,
+        inconsistencies: summary.inconsistencies,
+        redacted: summary.redacted,
+        ignoredMessages: summary.ignoredMessages,
+        timeline: summary.entries.map(trailEntryView),
+        limit,
+        announcementFilter: opt(flags, '--announcement-id') || null,
+        readOnly: true,
+        localFallback: false,
+        note: '时间线只汇总群里真发过的事实 (公告/接单/交付/初筛/终审); 没发过的环节不会凭空出现; 发送者只显示短标记 (原始 DID 不在输出里)',
+    };
+    const label = (k) => `${TG.TRAIL_KIND_LABEL[k]}=${summary.byKind[k]}`;
+    const human = [
+        title(`${head} (${ctx.group.name || ctx.group.groupId})`),
+        line('条目', `${summary.count} 条 (${TG.TRAIL_KINDS.map(label).join(' · ')})`),
+        ...(summary.announcements.length ? [line('涉及公告', summary.announcements.join(' · '))] : []),
+        ...(summary.inconsistencies.length ? [line('事实矛盾/遮蔽', summary.inconsistencies.join(' · '))] : []),
+        ...(summary.redacted.length ? [line('被遮蔽的字段', summary.redacted.join(' · ') + ' (别人发的消息里含标识符形态, 读回时已遮蔽)')] : []),
+        '',
+        ...(summary.entries.length
+            ? summary.entries.map((e) => `  ${TG.formatTrailLine(e)}`)
+            : ['  (群里还没有本期的过程痕迹: 先用 bolloon task announce --group … 发公告)']),
+        '',
+        `  ${String(data.note)}`,
+    ].join('\n');
+    return {
+        envelope: okEnvelope('OK', summary.count
+            ? `群里本期 ${summary.count} 条过程痕迹 (${summary.announcements.length} 个公告)`
+            : '群里本期没有过程痕迹 (群里真没有, 不是读失败)', data, summary.announcements, null),
+        human,
+    };
+}
+/** `bolloon task post --kind deliver|screen|final --group <…> --announcement-id <id>` —— 交付/初筛/终审的群消息 */
+async function taskPost(flags) {
+    const head = 'bolloon task post';
+    const kind = String(opt(flags, '--kind') || '').trim().toLowerCase();
+    if (!['deliver', 'screen', 'final'].includes(kind)) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', `--kind 必须是 deliver|screen|final (收到 ${kind || '(空)'})`, {
+                accepted: ['--kind deliver --hash sha256:<hex>', '--kind screen --checks "渠道结构=pass,价格带=fail"', '--kind final --verdict accept'],
+                claimKindNote: kind === 'claim'
+                    ? '接单痕迹不用 task post 发: 用 `bolloon task claim <announcementId> --group <群>` —— 这样"接单痕迹"必定对应一笔真认领账, 不会出现没有认领者却挂在群里的接单声明 (反过来也不会有认领了却没有任何群痕迹的静默)'
+                    : null,
+                why: '群里只认这四种过程事实: 公告 / 交付 / 初筛 / 终审 (接单走 task claim)',
+            }, [], 'needs_human'),
+            human: TASK_USAGE,
+        };
+    }
+    const ctx = await requireGroup(head, flags);
+    if (!ctx.ok)
+        return ctx.result;
+    const TG = await import('../../agents/task-group.js');
+    const bytesRaw = opt(flags, '--bytes');
+    const built = TG.buildPostMessage({
+        kind,
+        announcementId: opt(flags, '--announcement-id'),
+        round: opt(flags, '--round'),
+        price: opt(flags, '--price'),
+        hash: opt(flags, '--hash'),
+        bytes: bytesRaw === undefined ? null : Number(bytesRaw),
+        checksRaw: opt(flags, '--checks'),
+        verdict: opt(flags, '--verdict'),
+    });
+    if (!built.ok) {
+        return {
+            envelope: failEnvelope(built.code, built.message, { ...built.detail, kind, group: ctx.group, sent: false, localFallback: false }, [], 'needs_human'),
+            human: `${title(head)}\n  ${built.message}\n\n${TASK_USAGE.split('选项:')[0].trim().split('\n').slice(-6).join('\n')}`,
+        };
+    }
+    const sent = await TG.sendTrailMessage(ctx.group.groupId, built.text, ctx.fromTag);
+    if (!sent.ok) {
+        const violations = sent.violations || null;
+        return {
+            envelope: failEnvelope(violations ? 'POLICY_DENIED' : 'TRANSPORT_FAILED', violations ? `过程痕迹命中隐私红线, 拒绝发进群: ${violations.map((v) => v.rule).join(', ')}` : `群消息没发出去: ${sent.error}`, { kind, group: ctx.group.groupId, message: built.text, sent: false, violations, localFallback: false }, [], 'needs_human'),
+            human: [
+                title(head),
+                `  ${violations ? '命中隐私红线, 拒发' : '没发出去'}: ${sent.error}`,
+                ...(violations ? violations.map((v) => `    · ${v.rule} — ${v.why} (${v.masked}, ${v.chars} 字符)`) : []),
+                '',
+                hint('群里不放钱包地址/DID/peerId/multiaddr/IP/私钥形态; 换个不含标识符的短事实重发'),
+            ].join('\n'),
+        };
+    }
+    const onBoard = !!TG.readBoardAnnouncement(String(opt(flags, '--announcement-id') || ''));
+    const data = {
+        kind,
+        announcementId: opt(flags, '--announcement-id'),
+        message: sent.text,
+        checks: built.checks ? built.checks : null,
+        group: { id: ctx.group.groupId, name: ctx.group.name, via: ctx.group.via },
+        sender: { tag: ctx.fromTag, source: ctx.fromSource, didPrinted: false },
+        announcementOnLocalBoard: onBoard,
+        /** 群里只是留痕: 不执行、不付款、也不标 verified (终审结论不替代链上 release) */
+        executed: false,
+        paid: false,
+        fundsMoved: false,
+        verified: false,
+        localFallback: false,
+        note: kind === 'deliver'
+            ? '交付痕迹只贴内容哈希 (群里没有正文); 真交接仍走 bolloon task send → 对方 task accept'
+            : kind === 'screen'
+                ? '初筛通过 ≠ 已验收: 终审结论另发 (--kind final); 线上一分钱都没动'
+                : '终审结论只是过程事实: 结算仍只在链上 (群里的话不替代 releaseV2; 争议期不自动重付/不标 verified)',
+    };
+    return {
+        envelope: okEnvelope('OK', `已把${TG.TRAIL_KIND_LABEL[kind]}发进群 (${opt(flags, '--announcement-id')})`, data, [String(opt(flags, '--announcement-id'))], null),
+        human: [
+            title(`${head} --kind ${kind}`),
+            line('公告号', String(opt(flags, '--announcement-id'))),
+            line('群消息', sent.text),
+            ...(built.checks ? [line('初筛逐条', built.checks.map((c) => `${c.name}=${c.result}`).join(' · '))] : []),
+            line('群', `${ctx.group.name || '(无名)'} · ${ctx.group.groupId}`),
+            line('发送者标记', `${ctx.fromTag} (原始 DID 未进群)`),
+            line('本地板上有这条公告吗', onBoard ? '有' : '没有 (本机不是买方; 只发痕迹不假装认识这条公告)'),
+            line('本次执行/付款/验真', '都没有 (群消息只是过程留痕)'),
+            '',
+            `  ${data.note}`,
+        ].join('\n'),
+    };
+}
+// ── 群管理 (group create|join|list|link|leave, 2026-09-24) ────────────────────
+//
+// 为什么补这一段 (真缺口): `createGroup` / `joinGroup` / `listGroups` 一直只存在于
+// `src/agents/gateway-group.ts`, **CLI 里没有任何入口** —— 外部接单者拿到群链接后
+// 无法自助入群, 只能等对方把话转达。这里把它们接出来 (薄包装, 不重实现密钥学/存储),
+// 并补 `link` (取回邀请链接) 与 `leave` (退群)。
+//
+// 脱敏口径 (与群消息同一张表, 只去掉 orbitdb 那一档 —— 见 `TG.NODE_IDENTITY_RULES`):
+//   · 原始 DID · 钱包地址 · peerId · 节点 multiaddr (`/ip4` `/p2p` …) · IPv4/IPv6 · URL · 邮箱
+//     —— 一律不出现在群管理输出里;
+//   · 群 store 地址 (`/orbitdb/zdpu…`) 是**群自己的公开标识**, 邀请链接必须能打印
+//     → `list` 只出短事实 (groupId/群名/时间), 要链接就显式 `bolloon task group link <groupId>`。
+//   · `create` 的 `--name` 与 `list` 的**输出**都再过一遍 `scanNodeIdentity`: 命中 → 拒 (不静默脱敏)。
+const GROUP_ACTIONS = ['create', 'join', 'list', 'link', 'leave'];
+const GROUP_USAGE = `
+${title('bolloon task group')}
+  bolloon task group create --name <群名> [--from <短显示名>] [--json]
+      建一个可被邀请的群 (OrbitDB events store, ACL write:['*'] = 成员可广播);
+      打印**邀请链接** (把它发给要入群的人) 与 groupId; 落 ~/.bolloon/gateway-groups.json (重启不忘)
+  bolloon task group join <群链接|groupId> [--json]
+      用链接自助入群 (幂等: 已在群里 → already=true, 仍然 exit 0);
+      拿不到区块时**大声失败** (TRANSPORT_FAILED + storeCode=STORE_UNREACHABLE), 绝不把"读不到"说成"群里没东西"
+  bolloon task group list [--json]
+      本机已加入的群 (groupId · 群名 · 加入时间); 没有群 → 空列表 (不是错误)
+  bolloon task group link <groupId|群名> [--json]
+      显式取回邀请链接 (list 里不放链接: 群 store 地址只在你要分享时打印)
+  bolloon task group leave <groupId|群名> [--json]
+      退群 (只摘本机记录; 群 store 是公共 append-only, 别人那边不会因为你退出而改)
+
+选项: --json · --quiet; --name/--from 见上
+说明: 群管理输出不含原始 DID / 钱包地址 / peerId / multiaddr / IP (脱敏口径与群消息同源);
+      跨机**互相看见消息**仍需区块/日志复制 (bitswap + block broker, 不在本命令范围);
+      本机跨进程重开同一群链接读回既有消息已支持。
+`;
+/**
+ * 群管理输出过一遍节点身份闸 (命中 → 拒输出并如实报, 不静默脱敏后再当成没事)。
+ *
+ * `allow` = 本命令**故意打印**的群自身标识 (store 地址 / 邀请链接): 扫之前按**精确串**摘掉。
+ * 为什么要摘 (2026-09-24 想清楚的一个真坑): 群 store 地址是 base58 的 CID (`zdpu…`), 而 base58
+ * 字母表里**同时有 `Q` 和 `m`** —— 几十位里偶然出现 `Qm`, 后面又跟够 30 个 base58 字符时,
+ * 就会撞上 `Qm…` 这个 peerId 形状 → 建群**随机**被判成"输出泄漏了 peerId"。
+ * 摘掉的是"我们自己刚给出的那一个串", **规则一个字没放宽**: 别处再出现任何
+ * DID / 钱包 / peerId / 节点 multiaddr / IP 形状, 照样命中。
+ */
+async function guardGroupOutput(payload, allow = []) {
+    const TG = await import('../../agents/task-group.js');
+    let text = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    const tokens = allow.filter((t) => typeof t === 'string' && t.length > 0);
+    for (const t of tokens)
+        text = text.split(t).join('');
+    const hits = TG.scanNodeIdentity(text);
+    return hits.length ? { ok: false, hits } : { ok: true, exempted: tokens.length };
+}
+/** 群管理输出命中节点身份闸时的统一失败 (如实列出命中规则, 不回显被命中的原文) */
+function groupGuardFail(head, hits, extra = {}) {
+    return {
+        envelope: failEnvelope('POLICY_DENIED', `本机群列表里含节点身份形态, 拒绝输出 (${hits.map((h) => h.rule).join(', ')}) —— 已遮住原文, 不把标识符打出来`, { violations: hits, ...extra }, [], 'needs_human'),
+        human: [
+            title(head),
+            `  拒绝输出: 本机群记录里含 ${hits.map((h) => h.rule).join(', ')}`,
+            ...hits.map((h) => `    · ${h.rule} — ${h.why} (${h.masked}, ${h.chars} 字符)`),
+            '',
+            hint('群名/记录里被写进了标识符 → 改成不含标识符的名字 (本命令不静默脱敏: 脱敏后的群名不是你要看的那个)'),
+        ].join('\n'),
+    };
+}
+/** 群上下文解析: groupId 或群名 → 本机已加入的群 (都没有 → NOT_FOUND, 不猜) */
+async function resolveLocalGroup(raw) {
+    const GG = await import('../../agents/gateway-group.js');
+    const groups = await GG.listGroups();
+    const s = String(raw || '').trim();
+    const hit = groups.find((g) => g.id === s) || groups.find((g) => g.name === s) || null;
+    if (hit)
+        return { ok: true, group: hit };
+    return {
+        ok: false,
+        result: {
+            envelope: failEnvelope('NOT_FOUND', `本机没有这个群: ${s ? `${s.slice(0, 24)}${s.length > 24 ? '…' : ''}` : '(空)'} (既不是已加入群的 groupId, 也不是群名)`, {
+                joinedCount: groups.length,
+                howTo: '入群: bolloon task group join <群链接>; 看已加入的群: bolloon task group list',
+            }, [], 'needs_human'),
+            human: '',
+        },
+    };
+}
+async function taskGroup(flags) {
+    const action = String(flags.positionals[1] ?? '').trim();
+    // 用查表而不是 switch: `case 'create':` 这种字面量不属于 task 的**顶层**子命令,
+    // 免得将来有人把这段挪到 taskCommand 前面时被源级一致性门 (task-subcommands.test.ts) 误认。
+    const table = {
+        create: taskGroupCreate,
+        join: taskGroupJoin,
+        list: taskGroupList,
+        link: taskGroupLink,
+        leave: taskGroupLeave,
+    };
+    const fn = table[action];
+    if (fn)
+        return fn(flags);
+    return {
+        envelope: failEnvelope('INVALID_ARGUMENT', action ? `未知 group 动作: ${action}` : '缺少 group 动作 (create | join | list | link | leave)', { usage: plain(GROUP_USAGE.trim()), accepted: [...GROUP_ACTIONS] }, [], 'needs_human'),
+        human: GROUP_USAGE,
+    };
+}
+/** `task group create --name <群名>` —— 建群 + 打印邀请链接 */
+async function taskGroupCreate(flags) {
+    const head = 'bolloon task group create';
+    const TG = await import('../../agents/task-group.js');
+    const GG = await import('../../agents/gateway-group.js');
+    const name = String(opt(flags, '--name') ?? '').trim();
+    if (!name) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 --name (群名)', { accepted: ['--name 测试群'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    // 群名会进群消息与 list 输出 → 先过节点身份闸 (标识符形状的名字一律拒, 不静默改名)
+    const nameHits = TG.scanNodeIdentity(name);
+    if (nameHits.length) {
+        return {
+            envelope: failEnvelope('POLICY_DENIED', `群名含节点身份形态, 拒绝建群 (${nameHits.map((h) => h.rule).join(', ')})`, { violations: nameHits, accepted: ['--name 测试群'] }, [], 'needs_human'),
+            human: `${title(head)}\n  群名不能含 ${nameHits.map((h) => h.rule).join(', ')}\n\n${hint('群名是公开事实 (会进群消息与 list): 换个不含标识符的名字')}`,
+        };
+    }
+    const s = await TG.resolveSenderTag(opt(flags, '--from'));
+    if (!s.ok) {
+        return {
+            envelope: failEnvelope(s.code, s.message, { ...s.detail, group: { name }, created: false }, [], 'needs_human'),
+            human: `${title(head)}\n  群主标记定不下来: ${s.message}\n\n${hint('建群会写一条欢迎消息 (要一个诚实的发送者标记): 先 bolloon identity init 或 --from <短显示名>')}`,
+        };
+    }
+    const r = await GG.createGroup(name, { from: s.tag });
+    if (!r.ok || !r.group) {
+        return {
+            envelope: failEnvelope('TRANSPORT_FAILED', `建群失败: ${r.error ?? '未知原因'}`, { group: { name }, created: false, storeReachable: false }, [], 'needs_human'),
+            human: `${title(head)}\n  建群失败: ${r.error ?? '未知原因'}\n\n${hint('建群要写 OrbitDB store: 落盘目录不可写 / store 打不开都会在这里如实失败')}`,
+        };
+    }
+    const data = {
+        group: { id: r.group.id, name: r.group.name, link: r.group.link, createdAt: r.group.createdAt },
+        sender: { tag: s.tag, source: s.source, didPrinted: false },
+        file: '~/.bolloon/gateway-groups.json',
+        acl: { write: ['*'], note: '成员可广播: 入群的人都能往群里发消息 (建群时写进 store manifest)' },
+        created: true,
+        executed: false,
+        paid: false,
+        localFallback: false,
+    };
+    const guard = await guardGroupOutput(data, [r.group.id, r.group.link]);
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { group: { name }, created: true });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', `已建群「${r.group.name}」(${r.group.id.slice(0, 12)}…)`, data, [r.group.id], null),
+        human: [
+            title(head),
+            line('群名', r.group.name),
+            line('groupId', r.group.id),
+            line('邀请链接', r.group.link),
+            line('群主标记', `${s.tag} (${s.source === 'identity' ? '本机身份派生假名' : '--from 显式'}; 原始 DID 未进群)`),
+            line('本机记录', '~/.bolloon/gateway-groups.json (重启后仍记得这个群)'),
+            '',
+            hint(`把链接发给要入群的人: bolloon task group join "<链接>"`),
+            hint(`回看过程痕迹: bolloon task trail --group <链接>  ·  取回链接: bolloon task group link ${r.group.id.slice(0, 12)}…`),
+            '',
+            '  跨机**互相看见消息**仍需区块/日志复制 (bitswap + block broker, 不在本命令范围);',
+            '  本机跨进程用同一链接重开读回既有消息已支持。',
+        ].join('\n'),
+    };
+}
+/** `task group join <群链接|groupId>` —— 自助入群 (幂等) */
+async function taskGroupJoin(flags) {
+    const head = 'bolloon task group join';
+    const GG = await import('../../agents/gateway-group.js');
+    const raw = String(flags.positionals[2] ?? '').trim() || String(opt(flags, '--group') ?? '').trim();
+    if (!raw) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少群链接或 groupId', { accepted: ['bolloon task group join orbitdb:///orbitdb/<store>?type=group&name=<群名>', 'bolloon task group join <groupId>'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    // 链接 → 真入群 (打开 store); groupId/群名 → 必须已经在本地列表里 (不能凭 id 凭空入群)
+    if (!/^orbitdb:\/\//i.test(raw)) {
+        // 别的 scheme (`https://…` / `ipfs://…`): 这是**不是群链接**, 不是"本机没有这个群" —— 分开报
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+            return {
+                envelope: failEnvelope('INVALID_ARGUMENT', `这不是群链接 (${raw.split(':')[0]}://…) —— 群链接形如 orbitdb:///orbitdb/<store>?type=group&name=<群名>`, { scheme: raw.split(':')[0], accepted: ['bolloon task group join orbitdb:///orbitdb/<store>?type=group&name=<群名>'] }, [], 'needs_human'),
+                human: `${title(head)}\n  这不是群链接: ${raw.slice(0, 12)}…\n\n${hint('群邀请链接形如 orbitdb:///orbitdb/<store>?type=group&name=<群名> (bolloon task group create 会打印它)')}`,
+            };
+        }
+        const loc = await resolveLocalGroup(raw);
+        if (!loc.ok) {
+            return {
+                envelope: failEnvelope('NOT_FOUND', `本机没有这个群: ${raw} —— 用 id/群名**不能**入群, 只有群链接才能入群`, { accepted: 'bolloon task group join <群链接>', howTo: '拿到群链接后再试; 看已加入的群: bolloon task group list' }, [], 'needs_human'),
+                human: `${title(head)}\n  本机没有这个群: ${raw}\n\n${hint('id/群名只能引用**已加入**的群; 要入群请用邀请链接')}`,
+            };
+        }
+        const data = { group: { id: loc.group.id, name: loc.group.name }, already: true, joined: true, storeOpened: false };
+        return {
+            envelope: okEnvelope('OK', `已在群里「${loc.group.name}」(${loc.group.id.slice(0, 12)}…)`, data, [loc.group.id], null),
+            human: [title(head), line('群名', loc.group.name), line('groupId', loc.group.id), line('状态', 'already=true (早就加入过, 没有重复入群)')].join('\n'),
+        };
+    }
+    const r = await GG.joinGroup(raw);
+    if (!r.ok || !r.group) {
+        const unreachable = r.code === 'STORE_UNREACHABLE';
+        return {
+            envelope: failEnvelope(unreachable ? 'TRANSPORT_FAILED' : 'INVALID_ARGUMENT', unreachable ? `群 store 不可达: ${r.error ?? '未知原因'}` : `不是有效的群链接: ${r.error ?? '未知原因'}`, {
+                storeCode: r.code ?? null,
+                joined: false,
+                storeOpened: false,
+                localFallback: false,
+                why: unreachable
+                    ? '链接能解析但区块不在本机且没有 block broker → 如实失败 (绝不把"读不到"说成"群里没东西")'
+                    : '链接不是 orbitdb://…?type=group&name=… 形状 → 拒绝 (不猜你想进哪个群)',
+            }, [], 'needs_human'),
+            human: [
+                title(head),
+                `  ${unreachable ? '群 store 不可达' : '链接非法'}: ${r.error ?? ''}`,
+                '',
+                hint(unreachable
+                    ? '区块不在本机: 跨机同步 (bitswap/block broker) 还没接; 同机请确认对方的区块目录可读'
+                    : '群链接形如 orbitdb:///orbitdb/<store>?type=group&name=<群名>'),
+            ].join('\n'),
+        };
+    }
+    const data = {
+        group: { id: r.group.id, name: r.group.name },
+        already: !!r.already,
+        joined: true,
+        storeOpened: true,
+        linkKeptLocally: true,
+        note: '入群只改本机群列表 + 打开群 store: 不执行任务、不付款',
+    };
+    const guard = await guardGroupOutput(data, [r.group.id]);
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { joined: true });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', r.already ? `已在群里「${r.group.name}」(${r.group.id.slice(0, 12)}…)` : `已入群「${r.group.name}」(${r.group.id.slice(0, 12)}…)`, data, [r.group.id], null),
+        human: [
+            title(head),
+            line('群名', r.group.name),
+            line('groupId', r.group.id),
+            line('状态', r.already ? 'already=true (幂等: 早就加入过)' : '新加入'),
+            '',
+            hint(`现在可以: bolloon task trail --group ${r.group.id.slice(0, 12)}…  /  bolloon task claim <announcementId> --group <链接>`),
+        ].join('\n'),
+    };
+}
+/** `task group list [--json]` —— 本机已加入的群 (脱敏: 不出链接/地址/DID/peerId/IP) */
+async function taskGroupList(flags) {
+    const head = 'bolloon task group list';
+    const GG = await import('../../agents/gateway-group.js');
+    const groups = await GG.listGroups();
+    const rows = groups.map((g) => ({ id: g.id, name: g.name, createdAt: g.createdAt ?? null }));
+    const data = {
+        count: rows.length,
+        groups: rows,
+        note: '只出群标识/群名/加入时间: 邀请链接与 store 地址不进 list (要链接用 bolloon task group link <groupId>); '
+            + '本输出不含原始 DID/钱包地址/peerId/节点 multiaddr/IP',
+    };
+    const guard = await guardGroupOutput(data, rows.map((r) => r.id));
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { count: rows.length });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', rows.length ? `本机已加入 ${rows.length} 个群` : '本机还没有加入任何群 (空列表, 不是错误)', data, rows.map((r) => r.id), null),
+        human: [
+            title(head),
+            ...(rows.length
+                ? rows.map((r) => `  ${String(r.id).slice(0, 12)}…  ${String(r.name ?? '(无名)').padEnd(20)}  ${r.createdAt ?? '(无时间)'}`)
+                : ['  (本机还没有加入任何群)']),
+            '',
+            hint('建群: bolloon task group create --name <群名>  ·  入群: bolloon task group join <群链接>  ·  取链接: bolloon task group link <groupId>'),
+        ].join('\n'),
+    };
+}
+/** `task group link <groupId|群名>` —— 显式取回邀请链接 */
+async function taskGroupLink(flags) {
+    const head = 'bolloon task group link';
+    const raw = String(flags.positionals[2] ?? '').trim() || String(opt(flags, '--group') ?? '').trim();
+    if (!raw) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 groupId (或群名)', { accepted: ['bolloon task group link <groupId>'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    const loc = await resolveLocalGroup(raw);
+    if (!loc.ok) {
+        return {
+            envelope: failEnvelope('NOT_FOUND', `本机没有这个群: ${raw} (取不到链接)`, { howTo: '看已加入的群: bolloon task group list' }, [], 'needs_human'),
+            human: `${title(head)}\n  本机没有这个群: ${raw}\n\n${hint('先 bolloon task group list 看有哪些群 (或 join 入群)')}`,
+        };
+    }
+    const data = { group: { id: loc.group.id, name: loc.group.name, link: loc.group.link } };
+    const guard = await guardGroupOutput(data, [loc.group.id, loc.group.link]);
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { group: { name: loc.group.name } });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', `群「${loc.group.name}」的邀请链接已取出`, data, [loc.group.id], null),
+        human: [title(head), line('群名', loc.group.name), line('groupId', loc.group.id), line('邀请链接', loc.group.link)].join('\n'),
+    };
+}
+/** `task group leave <groupId|群名>` —— 退群 (只摘本机记录) */
+async function taskGroupLeave(flags) {
+    const head = 'bolloon task group leave';
+    const GG = await import('../../agents/gateway-group.js');
+    const raw = String(flags.positionals[2] ?? '').trim() || String(opt(flags, '--group') ?? '').trim();
+    if (!raw) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 groupId (或群名)', { accepted: ['bolloon task group leave <groupId>'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    const r = await GG.leaveGroup(raw);
+    if (!r.ok) {
+        return {
+            envelope: failEnvelope('NOT_FOUND', `退群失败: ${r.error ?? '未知原因'}`, { removed: false }, [], 'needs_human'),
+            human: `${title(head)}\n  ${r.error ?? '未知原因'}\n\n${hint('看已加入的群: bolloon task group list')}`,
+        };
+    }
+    return {
+        envelope: okEnvelope('OK', `已退出群 ${String(r.removed).slice(0, 12)}… (只摘本机记录)`, { removed: true, groupId: r.removed, localOnly: true, note: '群 store 是公共 append-only: 别人那边不会因为你退出而改 (本命令没有踢人/解散权限, 也不假装有)' }, [String(r.removed)], null),
+        human: [
+            title(head),
+            line('已退出', `${String(r.removed).slice(0, 12)}…`),
+            line('范围', '只摘本机记录 (~/.bolloon/gateway-groups.json)'),
+            '',
+            `  群 store 是公共 append-only: 别人那边不会因为你退出而改 (本命令没有踢人/解散权限, 也不假装有)`,
+        ].join('\n'),
+    };
+}
 // ── 仍未实现的两个 (任务书没点名; 如实报, 不假装) ────────────────────────────
 async function taskComplete(_flags) {
     const env = notImplemented('task complete 还没实现: 没有任务状态存储可写 (交易层有非法迁移保护, 不许绕过)', {