@bolloon/bolloon-agent 0.3.1 → 0.3.3

package/dist/judgeness/store.js

@@ -0,0 +1,481 @@
+/**
+ * judgeness · store.ts
+ *
+ * 落盘布局 (与 plan §5.1 一致):
+ *   ~/.bolloon/judgeness/
+ *     descriptions/<jd-id>.md        # 单 description 可读版 (frontmatter v2 + body)
+ *     tags.yaml                       # 全局 tags 聚合
+ *     visibility.yaml                 # 隐私策略
+ *     allowlist.yaml                  # 白名单
+ *     hearth-cache/<remote-pk>/       # 远端用户缓存
+ *       manifest.json
+ *       descriptions/<jd-id>.md
+ *       last-seen.txt
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+// ---------------------------------------------------------------------------
+// 路径常量 (每次重读 env, 支持测试隔离)
+// ---------------------------------------------------------------------------
+export function homeDir() {
+    return process.env.BOLLOON_HOME || path.join(os.homedir(), '.bolloon');
+}
+export function JUDGENESS_ROOT() {
+    return path.join(homeDir(), 'judgeness');
+}
+function DESCRIPTIONS_DIR() { return path.join(JUDGENESS_ROOT(), 'descriptions'); }
+function TAGS_FILE() { return path.join(JUDGENESS_ROOT(), 'tags.yaml'); }
+function VISIBILITY_FILE() { return path.join(JUDGENESS_ROOT(), 'visibility.yaml'); }
+function ALLOWLIST_FILE() { return path.join(JUDGENESS_ROOT(), 'allowlist.yaml'); }
+function HEARTH_CACHE_ROOT() { return path.join(JUDGENESS_ROOT(), 'hearth-cache'); }
+// ---------------------------------------------------------------------------
+// id 生成
+// ---------------------------------------------------------------------------
+export function newDescriptionId() {
+    const ts = Date.now();
+    const rand = crypto.randomBytes(3).toString('hex');
+    return `jd-${ts}-${rand}`;
+}
+// ---------------------------------------------------------------------------
+// ensureDirs
+// ---------------------------------------------------------------------------
+export async function ensureJudgenessDirs() {
+    await fs.mkdir(JUDGENESS_ROOT(), { recursive: true });
+    await fs.mkdir(DESCRIPTIONS_DIR(), { recursive: true });
+    await fs.mkdir(HEARTH_CACHE_ROOT(), { recursive: true });
+}
+// ---------------------------------------------------------------------------
+// description 落盘 / 读回 (md with frontmatter v2)
+// ---------------------------------------------------------------------------
+function descriptionMdPath(id) {
+    return path.join(DESCRIPTIONS_DIR(), `${id}.md`);
+}
+function escapeYamlString(s) {
+    // 单行安全: 包裹单引号 + 转义单引号. 避免依赖 js-yaml.
+    return `'${s.replace(/'/g, "''")}'`;
+}
+function safeVer(v) {
+    return v === 1 ? 1 : 0;
+}
+function descriptionToMarkdown(desc) {
+    const fm = [
+        '---',
+        `descriptionId: ${desc.descriptionId}`,
+        `judgmentRef: ${desc.judgmentRef}`,
+        `description_version: ${safeVer(desc.description_version)}`,
+        'facets:',
+        desc.facets.judgment !== undefined ? `  judgment: ${desc.facets.judgment}` : '  judgment: null',
+        desc.facets.taste_aesthetic !== undefined ? `  taste_aesthetic: ${desc.facets.taste_aesthetic}` : '  taste_aesthetic: null',
+        desc.facets.novelty_score !== undefined ? `  novelty_score: ${desc.facets.novelty_score}` : '  novelty_score: null',
+        desc.facets.imaginative_score !== undefined ? `  imaginative_score: ${desc.facets.imaginative_score}` : '  imaginative_score: null',
+        desc.facets.curiosity_vector !== undefined ? `  curiosity_vector: ${desc.facets.curiosity_vector}` : '  curiosity_vector: null',
+        'basis:',
+        desc.basis.taste_basis ? `  taste_basis: ${escapeYamlString(desc.basis.taste_basis)}` : '  taste_basis: null',
+        desc.basis.novelty_basis ? `  novelty_basis: ${escapeYamlString(desc.basis.novelty_basis)}` : '  novelty_basis: null',
+        desc.basis.imagination_basis ? `  imagination_basis: ${escapeYamlString(desc.basis.imagination_basis)}` : '  imagination_basis: null',
+        'scope:',
+        desc.scope.domains && desc.scope.domains.length > 0
+            ? `  domains: [${desc.scope.domains.map((d) => escapeYamlString(d)).join(', ')}]`
+            : '  domains: []',
+        desc.scope.topics && desc.scope.topics.length > 0
+            ? `  topics: [${desc.scope.topics.map((d) => escapeYamlString(d)).join(', ')}]`
+            : '  topics: []',
+        `visibility: ${desc.visibility}`,
+        `openState: ${desc.openState}`,
+        `by: ${desc.by}`,
+        desc.byAgentId ? `byAgentId: ${escapeYamlString(desc.byAgentId)}` : 'byAgentId: null',
+        `createdAt: ${escapeYamlString(desc.createdAt)}`,
+        `updatedAt: ${escapeYamlString(desc.updatedAt)}`,
+        desc.lastTransitionAt ? `lastTransitionAt: ${escapeYamlString(desc.lastTransitionAt)}` : 'lastTransitionAt: null',
+        'schema_version: 2',
+        'audience: self',
+        'stage: current',
+        'status: current',
+        `entity_type: concept`,
+        `tags: [judgeness, judgment-ref=${desc.judgmentRef}, visibility=${desc.visibility}, state=${desc.openState}]`,
+        '---',
+        '',
+        `# Judgeness Description ${desc.descriptionId}`,
+        '',
+        `## Judgment Reference`,
+        `- judgmentRef: ${desc.judgmentRef}`,
+        '',
+        `## Facets`,
+        `- judgment: ${desc.facets.judgment ?? 'n/a'}`,
+        `- taste_aesthetic: ${desc.facets.taste_aesthetic ?? 'n/a'}${desc.basis.taste_basis ? ' — ' + desc.basis.taste_basis : ''}`,
+        `- novelty_score: ${desc.facets.novelty_score ?? 'n/a'}${desc.basis.novelty_basis ? ' — ' + desc.basis.novelty_basis : ''}`,
+        `- imaginative_score: ${desc.facets.imaginative_score ?? 'n/a'}${desc.basis.imagination_basis ? ' — ' + desc.basis.imagination_basis : ''}`,
+        `- curiosity_vector: ${desc.facets.curiosity_vector ?? 'n/a'}`,
+        '',
+        `## Scope`,
+        `- domains: ${(desc.scope.domains ?? []).join(', ') || '(any)'}`,
+        `- topics: ${(desc.scope.topics ?? []).join(', ') || '(any)'}`,
+        '',
+        `## Privacy`,
+        `- visibility: ${desc.visibility}`,
+        `- openState: ${desc.openState}`,
+        `- by: ${desc.by}${desc.byAgentId ? ' (' + desc.byAgentId + ')' : ''}`,
+        '',
+    ];
+    return fm.join('\n');
+}
+// (旧 declare-module hack 已移除 — types.ts 已允许 description_version: 1 | 0)
+function parseMarkdownToDescription(raw) {
+    // 极简 frontmatter 解析 (匹配 key: value; facets/scope 走单行)
+    const m = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!m)
+        return null;
+    const fm = m[1];
+    const get = (key) => {
+        // ^[ ]* 让缩进子键 (如 `  judgment: 0.7`) 也能匹配
+        const re = new RegExp(`^[ ]*${key}:\\s*(.*)$`, 'm');
+        const x = fm.match(re);
+        if (!x)
+            return undefined;
+        let v = x[1].trim();
+        if (v === 'null' || v === '~')
+            return undefined;
+        if (v.startsWith("'") && v.endsWith("'"))
+            v = v.slice(1, -1).replace(/''/g, "'");
+        return v;
+    };
+    const getNum = (key) => {
+        const v = get(key);
+        if (v === undefined)
+            return undefined;
+        const n = Number(v);
+        return Number.isFinite(n) ? n : undefined;
+    };
+    const getList = (key) => {
+        const v = get(key);
+        if (v === undefined)
+            return undefined;
+        if (!v.startsWith('['))
+            return undefined;
+        const inner = v.slice(1, -1).trim();
+        if (!inner)
+            return [];
+        return inner.split(',').map((s) => s.trim().replace(/^'|'$/g, '').replace(/''/g, "'"));
+    };
+    const descriptionId = get('descriptionId');
+    const judgmentRef = get('judgmentRef');
+    if (!descriptionId || !judgmentRef)
+        return null;
+    return {
+        descriptionId,
+        judgmentRef,
+        description_version: (getNum('description_version') ?? 1),
+        facets: {
+            judgment: getNum('judgment'),
+            taste_aesthetic: getNum('taste_aesthetic'),
+            novelty_score: getNum('novelty_score'),
+            imaginative_score: getNum('imaginative_score'),
+            curiosity_vector: getNum('curiosity_vector'),
+        },
+        basis: {
+            taste_basis: get('taste_basis'),
+            novelty_basis: get('novelty_basis'),
+            imagination_basis: get('imagination_basis'),
+        },
+        scope: {
+            domains: getList('domains') ?? [],
+            topics: getList('topics') ?? [],
+        },
+        visibility: (get('visibility') ?? 'private'),
+        openState: (get('openState') ?? 'locked'),
+        by: (get('by') ?? 'human'),
+        byAgentId: get('byAgentId'),
+        createdAt: get('createdAt') ?? new Date().toISOString(),
+        updatedAt: get('updatedAt') ?? new Date().toISOString(),
+        lastTransitionAt: get('lastTransitionAt'),
+    };
+}
+export async function saveDescription(desc) {
+    await ensureJudgenessDirs();
+    const md = descriptionToMarkdown(desc);
+    const tmp = descriptionMdPath(desc.descriptionId) + '.tmp';
+    await fs.writeFile(tmp, md, 'utf-8');
+    await fs.rename(tmp, descriptionMdPath(desc.descriptionId));
+}
+export async function loadDescription(id) {
+    try {
+        const raw = await fs.readFile(descriptionMdPath(id), 'utf-8');
+        return parseMarkdownToDescription(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function listDescriptions() {
+    await ensureJudgenessDirs();
+    const files = await fs.readdir(DESCRIPTIONS_DIR()).catch(() => []);
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.md'))
+            continue;
+        const id = f.slice(0, -3);
+        const d = await loadDescription(id);
+        if (d)
+            out.push(d);
+    }
+    return out;
+}
+export async function findDescriptionByJudgmentRef(ref) {
+    const all = await listDescriptions();
+    return all.find((d) => d.judgmentRef === ref) ?? null;
+}
+// ---------------------------------------------------------------------------
+// visibility.yaml
+// ---------------------------------------------------------------------------
+function visFileToYaml(f) {
+    const lines = ['# judgeness/visibility.yaml', `version: ${f.version}`, 'defaults:'];
+    lines.push(`  visibility: ${f.defaults.visibility}`);
+    lines.push(`  openState: ${f.defaults.openState}`);
+    lines.push('channels:');
+    for (const c of f.channels) {
+        lines.push(`  - channelId: ${c.channelId}`);
+        lines.push(`    visibility: ${c.visibility}`);
+        lines.push(`    openState: ${c.openState}`);
+        lines.push(`    humanOverride: ${c.humanOverride}`);
+    }
+    lines.push('cards:');
+    if (f.cards.length === 0)
+        lines.push('  []');
+    else
+        for (const c of f.cards) {
+            lines.push(`  - descriptionId: ${c.descriptionId}`);
+            lines.push(`    visibility: ${c.visibility}`);
+            lines.push(`    openState: ${c.openState}`);
+            lines.push(`    humanOverride: ${c.humanOverride}`);
+        }
+    return lines.join('\n') + '\n';
+}
+function parseVisYaml(raw) {
+    // 极简行解析 — 不引依赖
+    const lines = raw.split('\n');
+    const f = {
+        version: 1,
+        defaults: { visibility: 'private', openState: 'locked' },
+        channels: [],
+        cards: [],
+    };
+    let section = 'root';
+    let curChannel = null;
+    let curCard = null;
+    for (const line of lines) {
+        const t = line.trim();
+        if (!t || t.startsWith('#'))
+            continue;
+        if (t === 'defaults:') {
+            section = 'defaults';
+            continue;
+        }
+        if (t === 'channels:') {
+            section = 'channels';
+            continue;
+        }
+        if (t === 'cards:') {
+            section = 'cards';
+            continue;
+        }
+        if (t.startsWith('- ')) {
+            const kv = t.slice(2).split(':').map((s) => s.trim());
+            const k = kv[0];
+            const v = kv.slice(1).join(':');
+            if (section === 'channels') {
+                curChannel = { [k]: v };
+                f.channels.push(curChannel);
+                section = 'channelItem';
+                continue;
+            }
+            if (section === 'cards') {
+                curCard = { [k]: v };
+                f.cards.push(curCard);
+                section = 'cardItem';
+                continue;
+            }
+        }
+        if (section === 'defaults' || section === 'channelItem' || section === 'cardItem') {
+            const kv = t.split(':').map((s) => s.trim());
+            const k = kv[0];
+            const v = kv.slice(1).join(':');
+            if (section === 'defaults') {
+                if (k === 'visibility')
+                    f.defaults.visibility = v;
+                if (k === 'openState')
+                    f.defaults.openState = v;
+            }
+            else if (section === 'channelItem' && curChannel) {
+                if (k === 'visibility')
+                    curChannel.visibility = v;
+                if (k === 'openState')
+                    curChannel.openState = v;
+                if (k === 'humanOverride')
+                    curChannel.humanOverride = v === 'true';
+            }
+            else if (section === 'cardItem' && curCard) {
+                if (k === 'visibility')
+                    curCard.visibility = v;
+                if (k === 'openState')
+                    curCard.openState = v;
+                if (k === 'humanOverride')
+                    curCard.humanOverride = v === 'true';
+            }
+        }
+    }
+    return f;
+}
+export async function loadVisibility() {
+    try {
+        const raw = await fs.readFile(VISIBILITY_FILE(), 'utf-8');
+        return parseVisYaml(raw);
+    }
+    catch {
+        return {
+            version: 1,
+            defaults: { visibility: 'private', openState: 'locked' },
+            channels: [],
+            cards: [],
+        };
+    }
+}
+export async function saveVisibility(f) {
+    await ensureJudgenessDirs();
+    const tmp = VISIBILITY_FILE() + '.tmp';
+    await fs.writeFile(tmp, visFileToYaml(f), 'utf-8');
+    await fs.rename(tmp, VISIBILITY_FILE());
+}
+// ---------------------------------------------------------------------------
+// allowlist.yaml
+// ---------------------------------------------------------------------------
+function allowlistToYaml(f) {
+    const lines = ['# judgeness/allowlist.yaml', `version: ${f.version}`, 'peers:'];
+    if (f.peers.length === 0) {
+        lines.push('  []');
+    }
+    else {
+        for (const p of f.peers) {
+            lines.push(`  - pubkey: ${p.pubkey}`);
+            if (p.alias)
+                lines.push(`    alias: ${escapeYamlString(p.alias)}`);
+            if (p.note)
+                lines.push(`    note: ${escapeYamlString(p.note)}`);
+            lines.push(`    addedAt: ${escapeYamlString(p.addedAt)}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+function parseAllowlistYaml(raw) {
+    const f = { version: 1, peers: [] };
+    const lines = raw.split('\n');
+    let cur = null;
+    for (const line of lines) {
+        const t = line.trim();
+        if (!t || t.startsWith('#'))
+            continue;
+        if (t.startsWith('- ')) {
+            if (cur && cur.pubkey)
+                f.peers.push(cur);
+            const kv = t.slice(2).split(':').map((s) => s.trim());
+            cur = { pubkey: kv.slice(1).join(':').trim() };
+            continue;
+        }
+        if (cur) {
+            const idx = t.indexOf(':');
+            if (idx === -1)
+                continue;
+            const k = t.slice(0, idx).trim();
+            let v = t.slice(idx + 1).trim();
+            if (v.startsWith("'") && v.endsWith("'"))
+                v = v.slice(1, -1).replace(/''/g, "'");
+            cur[k] = v;
+        }
+    }
+    if (cur && cur.pubkey)
+        f.peers.push(cur);
+    return f;
+}
+export async function loadAllowlist() {
+    try {
+        const raw = await fs.readFile(ALLOWLIST_FILE(), 'utf-8');
+        return parseAllowlistYaml(raw);
+    }
+    catch {
+        return { version: 1, peers: [] };
+    }
+}
+export async function saveAllowlist(f) {
+    await ensureJudgenessDirs();
+    const tmp = ALLOWLIST_FILE() + '.tmp';
+    await fs.writeFile(tmp, allowlistToYaml(f), 'utf-8');
+    await fs.rename(tmp, ALLOWLIST_FILE());
+}
+export async function isPubkeyAllowed(targetPubkey) {
+    const f = await loadAllowlist();
+    return f.peers.some((p) => p.pubkey === targetPubkey);
+}
+export async function addAllowlistPeer(entry) {
+    const f = await loadAllowlist();
+    const existing = f.peers.findIndex((p) => p.pubkey === entry.pubkey);
+    if (existing >= 0)
+        f.peers[existing] = entry;
+    else
+        f.peers.push(entry);
+    await saveAllowlist(f);
+}
+export async function removeAllowlistPeer(pubkey) {
+    const f = await loadAllowlist();
+    f.peers = f.peers.filter((p) => p.pubkey !== pubkey);
+    await saveAllowlist(f);
+}
+// ---------------------------------------------------------------------------
+// hearth-cache/<remote-pk>/
+// ---------------------------------------------------------------------------
+function cacheDir(remotePubkey) {
+    const sub = remotePubkey.slice(0, 16) + '__' + remotePubkey.slice(0, 8);
+    return path.join(HEARTH_CACHE_ROOT(), sub);
+}
+export async function writeHearthCache(remotePubkey, manifest, descriptions) {
+    await ensureJudgenessDirs();
+    const dir = cacheDir(remotePubkey);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.mkdir(path.join(dir, 'descriptions'), { recursive: true });
+    await fs.writeFile(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+    await fs.writeFile(path.join(dir, 'last-seen.txt'), new Date().toISOString(), 'utf-8');
+    for (const d of descriptions) {
+        await fs.writeFile(path.join(dir, 'descriptions', `${d.descriptionId}.md`), descriptionToMarkdown(d), 'utf-8');
+    }
+}
+export async function readHearthCache(remotePubkey) {
+    try {
+        const raw = await fs.readFile(path.join(cacheDir(remotePubkey), 'manifest.json'), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// tags.yaml (聚合器, 反攻期主用; 防御期写空壳)
+// ---------------------------------------------------------------------------
+export async function aggregateTags() {
+    const descs = await listDescriptions();
+    const set = new Set();
+    for (const d of descs) {
+        (d.scope.topics ?? []).forEach((t) => set.add(t));
+        (d.scope.domains ?? []).forEach((t) => set.add(t));
+    }
+    return Array.from(set).sort();
+}
+export async function writeTagsAggregate() {
+    await ensureJudgenessDirs();
+    const tags = await aggregateTags();
+    const yaml = ['# judgeness/tags.yaml', `version: 1`, `count: ${tags.length}`, 'tags:'];
+    for (const t of tags)
+        yaml.push(`  - ${escapeYamlString(t)}`);
+    const tmp = TAGS_FILE() + '.tmp';
+    await fs.writeFile(tmp, yaml.join('\n') + '\n', 'utf-8');
+    await fs.rename(tmp, TAGS_FILE());
+}

package/dist/judgeness/types.js

@@ -0,0 +1,19 @@
+/**
+ * judgeness · types.ts
+ *
+ * 重要设计决策 (2026-07-15 user rev):
+ *   judgeness 是对 judgement 的"描述统称", 不组块.
+ *   即: 不扩展 HumanJudgment 的 schema, 而是用一套独立 description vocabulary,
+ *        通过 judgmentRef 外键引用 HumanJudgment.id, 0 迁移成本.
+ *
+ * 核心 5 维 (与传播裂变 / 乔布斯 A 方向对应):
+ *   judgment / taste_aesthetic / novelty_score / imaginative_score / curiosity_vector
+ * basis_* 是品味 / 创新 / 想象的依据描述 (D1 第三反转).
+ *
+ * 4 层隐私:
+ *   public / allowlist / peers / private
+ *
+ * 状态机:
+ *   open (agent 可 publish) | locked (默认, agent 不可) | human-only (仅人类写入)
+ */
+export {};

package/dist/judgeness/visibility.js

@@ -0,0 +1,118 @@
+/**
+ * judgeness · visibility.ts
+ *
+ * 三道授权闸的核心实现:
+ *   闸 1: id-visibility scrubber     出站前按 audience 字段过滤
+ *   闸 2: channel-allowlist gate     joinPeer / joinTopic 前的白名单
+ *   闸 3: human-override handler     任何写入由人类 override 优先
+ *
+ * 复用了现有 sanitizeChannelForPeer 模式 (src/web/server-v3-p2p.ts:54) 的思路:
+ *   不引额外依赖; 默认 fail-closed (闸 1/2); 闸 3 fail-人类优先.
+ */
+import { loadVisibility, isPubkeyAllowed } from './store.js';
+/** 三态映射:
+ *  - locked + agent 写入 → 拒
+ *  - locked + human 写入 → 允许
+ *  - open + 任意 → 允许 (但要过闸 2 allowlist)
+ *  - human-only + agent 写入 → 拒
+ *  - visibility.yaml.humanOverride=true → 完全优先于 agent openState
+ */
+export function resolveGate3(desc, ctx, visFile) {
+    // 闸 3 先看 visibility.yaml.humanOverride (强制)
+    const visCard = visFile.cards.find((c) => c.descriptionId === desc.descriptionId);
+    const visChan = ctx.channelTopic
+        ? visFile.channels.find((c) => c.channelId === ctx.channelTopic)
+        : undefined;
+    const humanOverride = visCard?.humanOverride ?? visChan?.humanOverride ?? false;
+    const effectiveOpenState = visCard?.openState ?? visChan?.openState ?? desc.openState;
+    // humanOverride=true 时, agent 永不能写, 即使 openState=open
+    if (humanOverride && ctx.role !== 'human') {
+        return { allow: false, reason: 'humanOverride=true and writer is not human' };
+    }
+    // human-only 状态: 仅 human
+    if (effectiveOpenState === 'human-only' && ctx.role !== 'human') {
+        return { allow: false, reason: 'openState=human-only rejects agent' };
+    }
+    // locked 状态: agent 不能自动 share / publish (但可写入本地 draft)
+    if (effectiveOpenState === 'locked' && ctx.role === 'agent') {
+        return { allow: false, reason: 'openState=locked rejects agent auto-write' };
+    }
+    return { allow: true, reason: 'ok' };
+}
+/** 给 audience 一份 description 的可见版本. */
+export async function scrubForAudience(desc, audience) {
+    const vis = await loadVisibility();
+    const visCard = vis.cards.find((c) => c.descriptionId === desc.descriptionId);
+    const visChan = audience.channelTopic
+        ? vis.channels.find((c) => c.channelId === audience.channelTopic)
+        : undefined;
+    const effectiveVis = visCard?.visibility ?? visChan?.visibility ?? desc.visibility;
+    const base = {
+        descriptionId: desc.descriptionId,
+        judgmentRef: desc.judgmentRef,
+        visibility: effectiveVis,
+        openState: visCard?.openState ?? visChan?.openState ?? desc.openState,
+    };
+    // private 仅 self 可见
+    if (effectiveVis === 'private' && audience.pubkey !== '__self__') {
+        return base;
+    }
+    // peers 仅已 join 的 peer (这里简化为: 任何非 self 都视为 peer-by-default)
+    if (effectiveVis === 'peers' && audience.pubkey === '__self__') {
+        return { ...base, facets: desc.facets, basis: desc.basis, scope: desc.scope, by: desc.by, createdAt: desc.createdAt };
+    }
+    // allowlist
+    if (effectiveVis === 'allowlist') {
+        if (audience.pubkey === '__self__') {
+            return { ...base, facets: desc.facets, basis: desc.basis, scope: desc.scope, by: desc.by, createdAt: desc.createdAt };
+        }
+        const allowed = await isPubkeyAllowed(audience.pubkey);
+        if (!allowed)
+            return base;
+    }
+    // public
+    return {
+        ...base,
+        facets: desc.facets,
+        basis: desc.basis,
+        scope: desc.scope,
+        by: desc.by,
+        createdAt: desc.createdAt,
+    };
+}
+/** 批量. 顺序: scrub → 过滤 private (self-only). */
+export async function scrubListForAudience(descs, audience) {
+    const out = [];
+    for (const d of descs) {
+        const s = await scrubForAudience(d, audience);
+        out.push(s);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// 闸 2 — allowlist gate (joinPeer / joinTopic 前)
+// ---------------------------------------------------------------------------
+/** resolveGate2: true = 允许 join. */
+export async function resolveGate2(audiencePubkey, targetChannel, visFile) {
+    // 自我永远放行
+    if (audiencePubkey === '__self__')
+        return { allow: true, reason: 'self' };
+    const f = visFile ?? (await loadVisibility());
+    const chan = f.channels.find((c) => c.channelId === targetChannel);
+    if (!chan) {
+        // channel 没登记 = 默认 allowlist 模式 (闸 2 fail-closed)
+        const allowed = await isPubkeyAllowed(audiencePubkey);
+        return allowed
+            ? { allow: true, reason: 'default allowlist: pk in list' }
+            : { allow: false, reason: 'default allowlist: pk not in list' };
+    }
+    if (chan.visibility === 'public')
+        return { allow: true, reason: 'channel=public' };
+    if (chan.visibility === 'private')
+        return { allow: false, reason: 'channel=private' };
+    // allowlist / peers 都要求在白名单
+    const allowed = await isPubkeyAllowed(audiencePubkey);
+    return allowed
+        ? { allow: true, reason: 'allowlist match' }
+        : { allow: false, reason: 'allowlist miss' };
+}

package/dist/scripts/dedup-session-messages.js

@@ -0,0 +1,68 @@
+/**
+ * 历史 session.messages 清理脚本 (2026-07-15 Bug 4 修复配套)
+ * 一次性扫描 ~/.bolloon/sessions/cache/ 下所有 session 文件, 相邻去重 (同 type+content),
+ * 写回原文件. 老数据有此 bug (client PATCH + server /message 各 push 一份 user msg)
+ * 会导致重启后"每个 user 气泡显示 2 个".
+ *
+ * 跑法:
+ *   npx tsx src/scripts/dedup-session-messages.ts [--dry-run] [--only channelId]
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+const SESSIONS_DIR = path.join(process.env.HOME || '/tmp', '.bolloon', 'sessions', 'cache');
+async function main() {
+    const args = process.argv.slice(2);
+    const dryRun = args.includes('--dry-run');
+    const onlyId = args.includes('--only') ? args[args.indexOf('--only') + 1] : null;
+    let files;
+    try {
+        files = await fs.readdir(SESSIONS_DIR);
+    }
+    catch (e) {
+        console.log(`无法读 ${SESSIONS_DIR}: ${e.message}`);
+        return;
+    }
+    console.log(`扫描 ${SESSIONS_DIR}/ (${files.length} 文件), dry-run=${dryRun}${onlyId ? `, only=${onlyId}` : ''}`);
+    let totalScanned = 0;
+    let totalFixed = 0;
+    let totalDupes = 0;
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        if (onlyId && !f.startsWith(onlyId))
+            continue;
+        const fp = path.join(SESSIONS_DIR, f);
+        totalScanned++;
+        try {
+            const raw = await fs.readFile(fp, 'utf8');
+            const session = JSON.parse(raw);
+            const msgs = Array.isArray(session.messages) ? session.messages : [];
+            if (msgs.length === 0)
+                continue;
+            let lastType = null;
+            let lastContent = null;
+            const deduped = msgs.filter((m) => {
+                const same = lastType === m.type && lastContent === m.content;
+                lastType = m.type;
+                lastContent = m.content;
+                return !same;
+            });
+            const dupes = msgs.length - deduped.length;
+            if (dupes === 0)
+                continue;
+            totalFixed++;
+            totalDupes += dupes;
+            console.log(`  ${f}: ${msgs.length} → ${deduped.length} (去重 ${dupes} 条)`);
+            if (!dryRun) {
+                session.messages = deduped;
+                session.lastUpdated = new Date().toISOString();
+                await fs.writeFile(fp, JSON.stringify(session, null, 2));
+            }
+        }
+        catch (e) {
+            console.warn(`  ${f} 解析失败: ${e.message?.slice(0, 100)}`);
+        }
+    }
+    console.log(`\n扫描 ${totalScanned} 文件, 修复 ${totalFixed} 个, 共去重 ${totalDupes} 条${dryRun ? ' (dry-run, 未写入)' : ''}`);
+}
+main().catch(e => { console.error('ERR:', e); process.exit(1); });