@bolloon/bolloon-agent 0.4.5 → 0.4.6

package/dist/llm/tool-manifest/index.js

@@ -48,65 +48,6 @@ export function getToolsByLayer(layerId) {
  *
  * 不包含: 完整 parameters schema (那是 PiAI 客户端在调用时读)
  */
-/**
- * 把 ToolManifest 转成 OpenAI function calling 格式 (tools 数组)
- * 用于 native tool_choice: "auto" 模式, 让 LLM 选择调用.
- *
- * 注意: 递归处理嵌套参数 (type='object' 的 properties / type='array' 的 items)
- */
-export function formatForOpenAI(tools) {
-    const list = tools ?? ALL;
-    return list.map((t) => {
-        const properties = {};
-        const required = [];
-        for (const p of t.parameters) {
-            properties[p.name] = convertParameter(p);
-            if (p.required)
-                required.push(p.name);
-        }
-        return {
-            type: 'function',
-            function: {
-                name: t.id,
-                description: t.oneLine,
-                parameters: {
-                    type: 'object',
-                    properties,
-                    required,
-                },
-            },
-        };
-    });
-}
-function convertParameter(p) {
-    const schema = { type: p.type === 'enum' ? 'string' : p.type };
-    if (p.description)
-        schema.description = p.description;
-    if (p.enumValues)
-        schema.enum = p.enumValues;
-    if (p.default !== undefined)
-        schema.default = p.default;
-    if (p.minimum !== undefined)
-        schema.minimum = p.minimum;
-    if (p.maximum !== undefined)
-        schema.maximum = p.maximum;
-    if (p.format)
-        schema.format = p.format;
-    if (p.type === 'object' && p.properties) {
-        schema.properties = {};
-        for (const sub of p.properties) {
-            schema.properties[sub.name] = convertParameter(sub);
-        }
-    }
-    if (p.type === 'array' && p.items) {
-        schema.items = convertParameter(p.items);
-        if (p.minItems !== undefined)
-            schema.minItems = p.minItems;
-        if (p.maxItems !== undefined)
-            schema.maxItems = p.maxItems;
-    }
-    return schema;
-}
 export function formatForPrompt(tools) {
     const list = tools ?? ALL;
     const lines = [

package/dist/llm/tool-manifest/mcp.js

@@ -15,7 +15,7 @@ export const search_mcp_registry = {
     parameters: [
         { name: 'keywords', type: 'array', required: true, description: '搜索关键词', minItems: 1, items: { name: 'kw', type: 'string', required: true, description: '关键词' } }
     ],
-    callExample: `[TOOL:search_mcp_registry]
+    callExample: `[TOOL:search_mcp_registry]
 [P:keywords]${'${'}JSON.stringify(["calendar","schedule"])[ENDTOOL]`,
     layerId: 'tool.mcp_apps',
 };
@@ -37,7 +37,7 @@ export const suggest_connectors = {
     parameters: [
         { name: 'uuids', type: 'array', required: true, description: '从 search_mcp_registry 结果的 directoryUuid 复制', minItems: 1, items: { name: 'u', type: 'string', required: true, description: 'uuid' } }
     ],
-    callExample: `[TOOL:suggest_connectors]
+    callExample: `[TOOL:suggest_connectors]
 [P:uuids]${'${'}JSON.stringify(["uuid-from-search-result"])[ENDTOOL]`,
     layerId: 'tool.mcp_apps',
 };

package/dist/llm/tool-manifest/message_compose.js

@@ -23,9 +23,9 @@ export const message_compose_v1 = {
                 ],
             } },
     ],
-    callExample: `[TOOL:message_compose_v1]
-[P:kind]email
-[P:summary_title]Follow-up on Q3 review
+    callExample: `[TOOL:message_compose_v1]
+[P:kind]email
+[P:summary_title]Follow-up on Q3 review
 [P:variants]${'${'}JSON.stringify([{"label":"direct","subject":"Quick follow-up","body":"..."}])[ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/llm/tool-manifest/places.js

@@ -23,7 +23,7 @@ export const places_search = {
         { name: 'location_bias_lng', type: 'number', required: false, description: '可选经度' },
         { name: 'location_bias_radius', type: 'number', required: false, description: '米 (默认 5000)', default: 5000 }
     ],
-    callExample: `[TOOL:places_search]
+    callExample: `[TOOL:places_search]
 [P:queries]${'${'}JSON.stringify([{"query":"ramen restaurants Tokyo"}])[ENDTOOL]`,
     layerId: 'tool.manifest',
 };
@@ -77,7 +77,7 @@ export const places_map_display_v0 = {
         { name: 'title', type: 'string', required: false, description: '行程标题' },
         { name: 'narrative', type: 'string', required: false, description: '行程叙述' },
     ],
-    callExample: `[TOOL:places_map_display_v0]
+    callExample: `[TOOL:places_map_display_v0]
 [P:locations]${'${'}JSON.stringify([{"name":"Senso-ji","latitude":35.7148,"longitude":139.7967,"place_id":"ChIJ..."}])[ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/llm/tool-manifest/present_files.js

@@ -15,7 +15,7 @@ export const present_files = {
     parameters: [
         { name: 'filepaths', type: 'array', required: true, description: '至少 1 个文件路径', minItems: 1, items: { name: 'path', type: 'string', required: true, description: '容器内路径' } },
     ],
-    callExample: `[TOOL:present_files]
+    callExample: `[TOOL:present_files]
 [P:filepaths]${'${'}JSON.stringify(["/home/bolloon/report.md"])[ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/llm/tool-manifest/recipe.js

@@ -33,8 +33,8 @@ export const recipe_display_v0 = {
             } },
         { name: 'notes', type: 'string', required: false, description: '附加说明' },
     ],
-    callExample: `[TOOL:recipe_display_v0]
-[P:title]Pasta
+    callExample: `[TOOL:recipe_display_v0]
+[P:title]Pasta
 [P:ingredients]${'${'}JSON.stringify([{"id":"a1","amount":500,"name":"pasta"}])[ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/llm/tool-manifest/str_replace.js

@@ -17,11 +17,11 @@ export const str_replace = {
         { name: 'new_str', type: 'string', required: true, description: '新字符串 (空字符串 = 删除)', default: '' },
         { name: 'path', type: 'string', required: true, description: '文件路径' },
     ],
-    callExample: `[TOOL:str_replace]
-[P:description]修复 typo
-[P:old_str]recieve
-[P:new_str]receive
-[P:path]/home/bolloon/main.py
+    callExample: `[TOOL:str_replace]
+[P:description]修复 typo
+[P:old_str]recieve
+[P:new_str]receive
+[P:path]/home/bolloon/main.py
 [ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/llm/tool-manifest/view.js

@@ -16,9 +16,9 @@ export const view = {
         { name: 'path', type: 'string', required: true, description: '绝对路径' },
         { name: 'view_range', type: 'array', required: false, description: '[start, end] 1-indexed, end=-1 表示到末尾', minItems: 2, maxItems: 2, items: { name: 'r', type: 'integer', required: true, description: '行号' } }
     ],
-    callExample: `[TOOL:view]
-[P:description]读 README
-[P:path]/home/bolloon/README.md
+    callExample: `[TOOL:view]
+[P:description]读 README
+[P:path]/home/bolloon/README.md
 [ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/llm/tool-manifest/weather.js

@@ -18,10 +18,10 @@ export const weather_fetch = {
         { name: 'latitude', type: 'number', required: true, description: '纬度' },
         { name: 'longitude', type: 'number', required: true, description: '经度' },
     ],
-    callExample: `[TOOL:weather_fetch]
-[P:location_name]San Francisco, CA
-[P:latitude]37.78
-[P:longitude]-122.41
+    callExample: `[TOOL:weather_fetch]
+[P:location_name]San Francisco, CA
+[P:latitude]37.78
+[P:longitude]-122.41
 [ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/llm/tool-manifest/web.js

@@ -15,8 +15,8 @@ export const web_search = {
     parameters: [
         { name: 'query', type: 'string', required: true, description: '搜索查询 (1-6 词最佳)' },
     ],
-    callExample: `[TOOL:web_search]
-[P:query]S&P 500 current price
+    callExample: `[TOOL:web_search]
+[P:query]S&P 500 current price
 [ENDTOOL]`,
     layerId: 'tool.web_search',
 };
@@ -44,8 +44,8 @@ export const web_fetch = {
         { name: 'web_fetch_rate_limit_key', type: 'string', required: false, description: '速率限制键' },
         { name: 'web_fetch_rate_limit_dark_launch', type: 'boolean', required: false, description: '速率限制暗启动模式' },
     ],
-    callExample: `[TOOL:web_fetch]
-[P:url]https://example.com/article
+    callExample: `[TOOL:web_fetch]
+[P:url]https://example.com/article
 [ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/orbitdb/agent-tools.js

@@ -24,6 +24,138 @@ async function uiStore() {
     return getUICidStore();
 }
 const fmt = (o) => JSON.stringify(o, null, 2).slice(0, 3000);
+/** 2026-08-12 (Task5): Kanban 看板工具 (Hermes kanban_db → OrbitDB). 见 kanban-store.ts. */
+async function kanbanBoard(boardId) {
+    const { openKanbanBoard } = await import('./kanban-store.js');
+    return openKanbanBoard(boardId);
+}
+const fmtRows = (tasks) => tasks.length === 0 ? '📭 无任务' : tasks.map(t => `  [${t.status}] ${t.id} ${t.title}${t.assignee ? ` (${t.assignee})` : ''}`).join('\n');
+export function registerKanbanTools(ctx) {
+    ctx.tools.set('kanban_create', {
+        name: 'kanban_create',
+        description: '在看板上创建任务 (OrbitDB 持久化, 跨设备同步). 状态从 triage 开始.',
+        parameters: { boardId: '看板 id (必填, 默认用 agentId)', title: '任务标题 (必填)', body: '任务详情 (可选)', parentIds: '父任务 id 数组 (可选, 全部 done 才可执行)', createdBy: '创建者 (可选)', dueAt: '计划时间戳 (可选)' },
+        execute: async (args) => {
+            try {
+                const boardId = String(args.boardId || args.agentId || '').trim() || 'default';
+                const title = String(args.title || '').trim();
+                if (!title)
+                    return { success: false, error: 'title 必填' };
+                const parentIds = Array.isArray(args.parentIds) ? args.parentIds.map(String) : [];
+                const dueAt = typeof args.dueAt === 'number' ? args.dueAt : null;
+                const task = await (await kanbanBoard(boardId)).createTask({ boardId, title, body: String(args.body || '').trim(), parentIds, createdBy: String(args.createdBy || '').trim() || undefined, dueAt });
+                return { success: true, output: `📌 已创建任务 (${boardId}):\n  id: ${task.id}\n  状态: ${task.status}\n  推进: kanban_claim(id="${task.id}") → kanban_complete(...)` };
+            }
+            catch (e) {
+                return { success: false, error: `kanban_create 失败: ${String(e.message || e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('kanban_list', {
+        name: 'kanban_list',
+        description: '列出看板任务 (可按状态过滤). 状态: triage/todo/scheduled/ready/running/blocked/review/done/archived.',
+        parameters: { boardId: '看板 id (必填)', status: '可选: 按状态过滤' },
+        execute: async (args) => {
+            try {
+                const boardId = String(args.boardId || '').trim() || 'default';
+                const status = String(args.status || '').trim() || undefined;
+                const tasks = await (await kanbanBoard(boardId)).listTasks(status);
+                return { success: true, output: `🗂 ${boardId} ${status ? `[${status}]` : '全部'} ${tasks.length} 个任务:\n${fmtRows(tasks)}` };
+            }
+            catch (e) {
+                return { success: false, error: `kanban_list 失败: ${String(e.message || e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('kanban_get', {
+        name: 'kanban_get',
+        description: '查看单个任务详情 (含 parentIds/认领人/失败计数/createdRefs).',
+        parameters: { boardId: '看板 id (必填)', id: '任务 id (必填)' },
+        execute: async (args) => {
+            try {
+                const boardId = String(args.boardId || '').trim() || 'default';
+                const id = String(args.id || '').trim();
+                if (!id)
+                    return { success: false, error: 'id 必填' };
+                const t = await (await kanbanBoard(boardId)).getTask(id);
+                if (!t)
+                    return { success: false, error: `任务不存在: ${id}` };
+                return { success: true, output: `📄 ${t.id} [${t.status}]\n  标题: ${t.title}\n  详情: ${t.body || '—'}\n  父任务: ${t.parentIds.length ? t.parentIds.join(', ') : '无'}\n  认领人: ${t.assignee || t.claimLock || '未认领'}\n  失败计数: ${t.consecutiveFailures}\n  引用: ${t.createdRefs.length ? t.createdRefs.join(', ') : '无'}\n  备注: ${t.reason || '—'}` };
+            }
+            catch (e) {
+                return { success: false, error: `kanban_get 失败: ${String(e.message || e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('kanban_claim', {
+        name: 'kanban_claim',
+        description: '原子认领一个 ready 任务 (CAS, 至多一个 worker 成功). 认领后状态 → running.',
+        parameters: { boardId: '看板 id (必填)', id: '任务 id (必填)', worker: '认领者标识 (默认当前 agentId)' },
+        execute: async (args) => {
+            try {
+                const boardId = String(args.boardId || '').trim() || 'default';
+                const id = String(args.id || '').trim();
+                const worker = String(args.worker || '').trim() || 'agent';
+                if (!id)
+                    return { success: false, error: 'id 必填' };
+                const r = await (await kanbanBoard(boardId)).claimTask(id, worker);
+                if (!r.ok)
+                    return { success: false, error: `认领失败: ${r.reason}` };
+                return { success: true, output: `✅ 已认领 ${id} (worker=${worker})\n  完成: kanban_complete(id="${id}", worker="${worker}")` };
+            }
+            catch (e) {
+                return { success: false, error: `kanban_claim 失败: ${String(e.message || e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('kanban_complete', {
+        name: 'kanban_complete',
+        description: '完成一个 running 任务 → done (自动释放认领锁, 父任务完成时自动解子任务). createdRefs 声称的引用会做防幻觉校验.',
+        parameters: { boardId: '看板 id (必填)', id: '任务 id (必填)', worker: '认领者 (默认当前 agentId)', createdRefs: '可选: 声称创建的任务/资源引用数组' },
+        execute: async (args) => {
+            try {
+                const boardId = String(args.boardId || '').trim() || 'default';
+                const id = String(args.id || '').trim();
+                const worker = String(args.worker || '').trim() || 'agent';
+                if (!id)
+                    return { success: false, error: 'id 必填' };
+                const refs = Array.isArray(args.createdRefs) ? args.createdRefs.map(String) : [];
+                const t = await (await kanbanBoard(boardId)).completeTask(id, worker, refs);
+                if (!t)
+                    return { success: false, error: `无法完成 ${id} (不存在 或 非本 worker 认领)` };
+                return { success: true, output: `🏁 已完成 ${id} [done]${t.reason ? `\n  提醒: ${t.reason}` : ''}` };
+            }
+            catch (e) {
+                return { success: false, error: `kanban_complete 失败: ${String(e.message || e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('kanban_status', {
+        name: 'kanban_status',
+        description: '手动推进任务状态 (review/done/blocked/archived/ready 等合法迁移). blocked 需带 reason; archived 为终态.',
+        parameters: { boardId: '看板 id (必填)', id: '任务 id (必填)', status: '目标状态 (必填)', reason: 'blocked/review 时必填备注' },
+        execute: async (args) => {
+            try {
+                const boardId = String(args.boardId || '').trim() || 'default';
+                const id = String(args.id || '').trim();
+                const status = String(args.status || '').trim();
+                if (!id || !status)
+                    return { success: false, error: 'id 和 status 必填' };
+                let t = null;
+                if (status === 'review')
+                    t = await (await kanbanBoard(boardId)).requestReview(id, String(args.reason || '').trim());
+                else
+                    t = await (await kanbanBoard(boardId)).setStatus(id, status, String(args.reason || '').trim());
+                if (!t)
+                    return { success: false, error: `状态迁移失败 (非法迁移或任务不存在): ${id} → ${status}` };
+                return { success: true, output: `↻ ${id} → [${t.status}]${t.reason ? ` (${t.reason})` : ''}` };
+            }
+            catch (e) {
+                return { success: false, error: `kanban_status 失败: ${String(e.message || e).slice(0, 200)}` };
+            }
+        }
+    });
+}
 export function registerOrbitdbTools(ctx) {
     ctx.tools.set('cid_save', {
         name: 'cid_save',
@@ -222,4 +354,11 @@ export function registerOrbitdbTools(ctx) {
             }
         }
     });
+    // 2026-08-12 (Task5): Kanban 看板工具 (Hermes kanban_db → OrbitDB)
+    try {
+        registerKanbanTools(ctx);
+    }
+    catch (odbErr) {
+        console.warn('[registerTools] Kanban 工具注册失败 (非致命):', odbErr);
+    }
 }

package/dist/orbitdb/kanban-store.js

@@ -0,0 +1,259 @@
+/**
+ * kanban-store.ts — Hermes kanban 的 OrbitDB 落地 (2026-08-12, Task5)
+ *
+ * 借鉴 hermes_cli/kanban_db.py 的 9 态任务看板 + 原子认领 (CAS), 存到 OrbitDB
+ * keyvalue store (去中心化, DID 复制可跨设备同步). 每个 board 一个 store:
+ *   bolloon-kanban-<boardId>
+ *
+ * 任务 9 态 (VALID_STATUSES):
+ *   triage → todo → (父全部 done) → ready → running → done / archived
+ *   - scheduled:  定时任务 (本次简化为状态 + dueAt, 到时可 promote)
+ *   - blocked:    主动 block (sticky, 需显式 unblock) 或父依赖未完成 (自动解)
+ *   - review:     request_review 挂起等人工审批, approve → done
+ *   - archived:   终态归档
+ *
+ * 原子认领 (CAS, 至多一个 worker 认领成功): claim_task 只在
+ *   status === 'ready' && claimLock 为空 时置 running + claimLock + claimExpires,
+ *   否则返回输家 (不重试, 无分布式锁).
+ *
+ * 安全:
+ *   - 依赖的 KV store (put/get/all) 可注入 → 单测用内存 map, 生产用 OrbitDB store.
+ *   - 任务字段全部有默认值 (dag-cbor 不支持 undefined).
+ */
+export const KANBAN_STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
+const now = () => Date.now();
+function fresh(id, boardId, title, base = {}) {
+    return {
+        id, boardId, title,
+        body: base.body ?? '',
+        status: base.status ?? 'triage',
+        parentIds: base.parentIds ?? [],
+        createdBy: base.createdBy ?? '',
+        assignee: base.assignee ?? '',
+        dueAt: base.dueAt ?? null,
+        claimLock: base.claimLock ?? '',
+        claimExpires: base.claimExpires ?? 0,
+        consecutiveFailures: base.consecutiveFailures ?? 0,
+        createdRefs: base.createdRefs ?? [],
+        reason: base.reason ?? '',
+        review: base.review ?? '',
+        createdAt: base.createdAt ?? now(),
+        updatedAt: base.updatedAt ?? now(),
+        completedAt: base.completedAt ?? null,
+        archivedAt: base.archivedAt ?? null,
+    };
+}
+export function taskKey(id) {
+    return `task:${id}`;
+}
+/**
+ * KanbanBoard — 绑定一个 KV store 的看板.
+ * 所有写都经 readTask→改→put 的 CAS 语义; claim 在内核判赢家.
+ */
+export class KanbanBoard {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    st(s) {
+        return JSON.parse(JSON.stringify(s));
+    }
+    async createTask(input) {
+        const id = `t_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+        const task = fresh(id, input.boardId, input.title, {
+            body: input.body ?? '',
+            parentIds: input.parentIds ?? [],
+            createdBy: input.createdBy ?? '',
+            dueAt: input.dueAt ?? null,
+            status: 'triage',
+        });
+        await this.kv.put(taskKey(id), JSON.parse(JSON.stringify(task)));
+        return this.st(task);
+    }
+    async getTask(id) {
+        const v = await this.kv.get(taskKey(id));
+        return v || null;
+    }
+    async listTasks(status) {
+        const all = await this.kv.all();
+        const tasks = [];
+        for (const e of all) {
+            const t = e.value;
+            if (t && typeof t === 'object' && t.title !== undefined) {
+                if (!status || t.status === status)
+                    tasks.push(this.st(t));
+            }
+        }
+        return tasks.sort((a, b) => a.createdAt - b.createdAt);
+    }
+    /** 保存变更 (校验合法) */
+    async persist(task) {
+        task.updatedAt = now();
+        await this.kv.put(taskKey(task.id), JSON.parse(JSON.stringify(task)));
+        return this.st(task);
+    }
+    /**
+     * 状态推进 gate: 只允许合法迁移 (防乱跳). 返回 null 表示禁止.
+     */
+    trans(from, to) {
+        if (from === to)
+            return true;
+        if (from === 'done' || from === 'archived')
+            return false; // 终态不可再动
+        const allowed = {
+            triage: ['todo', 'scheduled', 'blocked', 'archived'],
+            todo: ['scheduled', 'ready', 'blocked', 'archived'],
+            scheduled: ['todo', 'ready', 'blocked', 'archived'],
+            ready: ['running', 'blocked', 'archived'],
+            running: ['review', 'done', 'blocked', 'ready'],
+            blocked: ['todo', 'ready', 'archived'],
+            review: ['done', 'blocked', 'todo'],
+        };
+        const ok = (allowed[from] || []).includes(to);
+        return ok;
+    }
+    /** checking parents status from KV */
+    async allParentsDone(task) {
+        if (!task.parentIds || task.parentIds.length === 0)
+            return true;
+        for (const pid of task.parentIds) {
+            const p = await this.getTask(pid);
+            if (p && p.status !== 'done' && p.status !== 'archived')
+                return false;
+        }
+        return true;
+    }
+    /** 把 todo/scheduled/blocked(父依赖未完成) 任务晋升为 ready (父依赖满足时) — recompute Ready */
+    async promoteReady(taskId) {
+        const t = await this.getTask(taskId);
+        if (!t)
+            return null;
+        // 自动可清 blocked = 因父依赖未完成; sticky blocked (用户主动) 不自动解
+        const autoClearable = t.status === 'blocked' && t.reason === 'parents_not_done';
+        if (!autoClearable && t.status !== 'todo' && t.status !== 'scheduled')
+            return null;
+        if (!(await this.allParentsDone(t))) {
+            if (t.status === 'blocked')
+                return this.st(t);
+            return { ...this.st(t), status: 'blocked', reason: 'parents_not_done' };
+        }
+        return this.persist({ ...t, status: 'ready', reason: '' });
+    }
+    /** 认领 (CAS): 只有 ready 且未被认领的才能成功 → running + claimLock */
+    async claimTask(taskId, worker, ttlMs = 15 * 60 * 1000) {
+        const t = await this.getTask(taskId);
+        if (!t)
+            return { ok: false, reason: `任务不存在: ${taskId}` };
+        if (t.claimLock)
+            return { ok: false, reason: '已被其他 worker 认领' };
+        if (t.status !== 'ready') {
+            // 父依赖不变式: 认领点再强校验一次 (任何写路径把任务置 ready 都可能被这里纠正)
+            if (!(await this.allParentsDone(t))) {
+                await this.persist({ ...t, status: 'blocked', reason: 'parents_not_done' });
+                return { ok: false, reason: '父任务未完成 (降级 blocked)' };
+            }
+            return { ok: false, reason: `状态为 ${t.status}, 只有 ready 可认领` };
+        }
+        const run = fresh(t.id, t.boardId, t.title, { ...t, status: 'running', claimLock: worker, claimExpires: now() + ttlMs, consecutiveFailures: 0 });
+        await this.kv.put(taskKey(taskId), JSON.parse(JSON.stringify(run)));
+        return { ok: true, task: this.st(run) };
+    }
+    /** 认领 TTL 过期释放 — 防崩溃锁泄漏 (重启后旧 claimLock 残留) */
+    async releaseStaleClaims(nowTs = now()) {
+        const tasks = await this.listTasks('running');
+        let freed = 0;
+        for (const t of tasks) {
+            if (t.claimLock && t.claimExpires < nowTs) {
+                await this.persist({ ...t, status: 'ready', claimLock: '', claimExpires: 0 });
+                freed++;
+            }
+        }
+        return freed;
+    }
+    /** 记一次失败 (熔断): 连续失败 > limit → blocked */
+    async registerFailure(taskId, failureLimit = 3) {
+        const t = await this.getTask(taskId);
+        if (!t)
+            return null;
+        let next = t.claimLock ? { ...t, status: 'ready', claimLock: '', claimExpires: 0 } : { ...t };
+        next.consecutiveFailures = (next.consecutiveFailures || 0) + 1;
+        if (next.consecutiveFailures >= failureLimit) {
+            next.status = 'blocked';
+            next.reason = `circuit_break (连续失败 ${next.consecutiveFailures})`;
+        }
+        return this.persist(next);
+    }
+    /** 完成: 校验声称创建的引用 (防幻觉 — 幽灵引用 advisory), 父任务完成则解子依赖 */
+    async completeTask(taskId, worker, createdRefs = []) {
+        const t = await this.getTask(taskId);
+        if (!t)
+            return null;
+        if (t.claimLock && t.claimLock !== worker)
+            return null;
+        // 防幻觉 (advisory): 声称创建的引用逐一验证存在 → 不存在记为 advisory (不阻塞, 但可审计)
+        const missing = [];
+        for (const ref of createdRefs) {
+            const existing = await this.getTask(ref.replace(/^task:/, ''));
+            if (!existing)
+                missing.push(ref);
+        }
+        const task = fresh(t.id, t.boardId, t.title, {
+            ...t, status: 'done', claimLock: '', claimExpires: 0,
+            createdRefs, reason: missing.length ? `advisory_missing_refs: ${missing.join(',')}` : t.reason,
+            completedAt: now(),
+        });
+        await this.kv.put(taskKey(taskId), JSON.parse(JSON.stringify(task)));
+        // 子任务受父完成影响 → 尝试晋升 ready
+        const all = await this.listTasks();
+        for (const c of all) {
+            if (c.parentIds.includes(taskId) && (c.status === 'todo' || c.status === 'blocked')) {
+                await this.promoteReady(c.id);
+            }
+        }
+        return this.st(task);
+    }
+    async requestReview(taskId, note) {
+        const t = await this.getTask(taskId);
+        if (!t || t.status !== 'running')
+            return null;
+        return this.persist({ ...t, status: 'review', claimLock: '', claimExpires: 0, review: note });
+    }
+    async approveReview(taskId) {
+        const t = await this.getTask(taskId);
+        if (!t || t.status !== 'review')
+            return null;
+        return this.persist({ ...t, status: 'done', reason: 'review_approved', completedAt: now() });
+    }
+    async rejectReview(taskId, reason) {
+        const t = await this.getTask(taskId);
+        if (!t || t.status !== 'review')
+            return null;
+        return this.persist({ ...t, status: 'blocked', review: '', reason: `review_rejected: ${reason}` });
+    }
+    async setStatus(taskId, to, reason = '') {
+        const t = await this.getTask(taskId);
+        if (!t || !this.trans(t.status, to))
+            return null;
+        if (to === 'blocked' && !reason && !t.reason)
+            return null; // blocked 需带 reason
+        const next = { ...t, status: to, reason: to === 'blocked' ? (reason || t.reason) : reason || t.reason };
+        if (to === 'archived')
+            next.archivedAt = now();
+        if (to === 'ready') {
+            if (!(await this.allParentsDone(next)))
+                return this.persist({ ...next, status: 'blocked', reason: 'parents_not_done' });
+        }
+        return this.persist(next);
+    }
+}
+/** 打开/缓存指定 board 的 OrbitDB KV store, 返回绑定的 KanbanBoard. 失败抛错. */
+const _boardCache = new Map();
+export async function openKanbanBoard(boardId) {
+    if (_boardCache.has(boardId))
+        return _boardCache.get(boardId);
+    const { getCIDDatabase } = await import('./cid-database.js');
+    const store = await (await getCIDDatabase()).openStore(`bolloon-kanban-${boardId}`, 'keyvalue');
+    const board = new KanbanBoard(store);
+    _boardCache.set(boardId, board);
+    return board;
+}