@bolloon/bolloon-agent 0.3.52 → 0.4.2

package/dist/web/loop-noise.js

@@ -0,0 +1,86 @@
+/**
+ * loop-noise.ts — 良性连接拆除噪音抑制 (借鉴 Hermes tui_gateway/loop_noise.py)
+ *
+ * Hermes 问题: Desktop 客户端强关 WebSocket 时, gateway 还有 pending socket 操作,
+ *   asyncio transport teardown 对每个 _call_connection_lost 回调打一条完整 traceback,
+ *   单次断开可刷 50+ 条相同 ConnectionResetError/WinError 10054 进 errors.log (#50005).
+ *
+ * Bolloon 等价: SSE/HTTP 客户端断开后, 服务端向已关闭的 res 写消息 → 每次广播抛
+ *   "write EPIPE / write after end / 连接被重置"。这不是可行动的错误 — 是对端在
+ *   写 drain 前挂线的预期副作用。这里对"拆除期写失败"这类良性错误做一次过滤,
+ *   把同类错误折叠成一行 debug, 其余错误原样交给默认逻辑, 真实的循环 bug 仍会暴露。
+ *
+ * 设计要点 (对齐 hermes):
+ *   - 同时看错误类型 AND 写路径标记 (broadcast 的 res.write) 才吞 — 其它地方抛同样错误
+ *     不被误吞 (对应 hermes 的 _call_connection_lost gating)。
+ *   - 同类错误窗口节流 (channel_directory 模式): 同一 (类别, 摘要) 窗口内只 warn 一次,
+ *     复用 delivery-ledger 已有的 shouldWarn 心智。
+ */
+/** 良性拆除期写失败: 对端挂线 / 写已结束的流。等价 hermes 的 ConnectionReset/Aborted/BrokenPipe。 */
+const BENIGN_WRITE_PATTERNS = [
+    /write EPIPE/i,
+    /write after end/i,
+    /ECONNRESET|connection (reset|aborted)|10054|10053/i,
+    /Cannot (write|set headers) after (the client|they) (are |is |has )?(closed|ended)/i,
+    /socket hang up/i,
+    /broken pipe/i,
+];
+/**
+ * 一条错误是否属于"写给已断开客户端"的良性噪音。
+ * 双重判定等价 hermes 的 (错误类型 + _call_connection_lost 回调 gating):
+ *   - 类型/消息命中拆除类写失败 (ConnectionReset/BrokenPipe/写已结束)
+ *   - 且调用点本来就是"写路径" — 由 guardClientWriteNoise 只在 res.write 处调用保证
+ */
+export function isBenignClientWriteNoise(err) {
+    const msg = String(err?.message || err || '');
+    return BENIGN_WRITE_PATTERNS.some((re) => re.test(msg));
+}
+/** 同类错误节流器: 同 (类别, 摘要) 窗口内返回 false (不重复 warn), 窗口外返回 true 并刷新。 */
+export class NoiseThrottle {
+    windowMs;
+    last = new Map();
+    constructor(windowMs = 5 * 60 * 1000) {
+        this.windowMs = windowMs;
+    }
+    shouldWarn(category, detail) {
+        const key = `${category}|${detail.slice(0, 80)}`;
+        const now = Date.now();
+        const last = this.last.get(key) ?? 0;
+        if (now - last < this.windowMs)
+            return false;
+        this.last.set(key, now);
+        return true;
+    }
+    reset() {
+        this.last.clear();
+    }
+}
+/**
+ * 包装一个"可能抛拆除期写失败"的写操作:
+ *   - 良性噪音 → 静默吞一次 (不抛出, 不打印), 仅按节流器偶尔 debug 一行
+ *   - 其它错误 → 原样抛出 / 转交 onError, 不掩盖真实问题
+ *
+ * @param fn 实际写操作 (抛异常或 reject)
+ * @param opts 诊断标签 + 可选节流器 (默认全局单例) + 可选 onError 回调 (捕获真实错误)
+ */
+export async function guardClientWriteNoise(fn, opts = { label: 'write' }) {
+    const throttle = opts.throttle ?? globalNoiseThrottle;
+    try {
+        await fn();
+    }
+    catch (e) {
+        if (isBenignClientWriteNoise(e)) {
+            // 良性: 折叠成一行 (节流), 不抛出
+            if (throttle.shouldWarn(opts.label, String(e?.message || e))) {
+                console.debug(`[loop-noise] 已抑制良性客户端断开写失败 (${opts.label}): ${String(e?.message || '').slice(0, 120)}`);
+            }
+            return;
+        }
+        if (opts.onError)
+            opts.onError(e);
+        else
+            throw e;
+    }
+}
+/** 全局默认节流器 (server 生命期复用, 跨连接共享告警窗口)。 */
+export const globalNoiseThrottle = new NoiseThrottle();

package/dist/web/manifest.json

@@ -1,21 +1,21 @@
-{
-  "name": "Bolloon Agent",
-  "short_name": "Bolloon",
-  "description": "AI Agent with Claude API integration",
-  "start_url": "/",
-  "display": "standalone",
-  "background_color": "#1a1a2e",
-  "theme_color": "#1a1a2e",
-  "icons": [
-    {
-      "src": "/icons/favicon-192x192.png",
-      "sizes": "192x192",
-      "type": "image/png"
-    },
-    {
-      "src": "/icons/favicon-512x512.png",
-      "sizes": "512x512",
-      "type": "image/png"
-    }
-  ]
+{
+  "name": "Bolloon Agent",
+  "short_name": "Bolloon",
+  "description": "AI Agent with Claude API integration",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#1a1a2e",
+  "theme_color": "#1a1a2e",
+  "icons": [
+    {
+      "src": "/icons/favicon-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/favicon-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ]
 }

package/dist/web/routes-tasks.js

@@ -4,8 +4,10 @@
  * 从 src/web/server.ts 抽出 (~160 行).
  * 包含 /api/tasks/* (GET, POST, PATCH, DELETE, execute, execute-next)
  */
-import { loadTaskQueue, saveTaskQueue, isTaskExecuting } from './server-storage.js';
+import { loadTaskQueue, saveTaskQueue } from './server-storage.js';
 import { documentReader } from '../documents/reader.js';
+import { applyCancelRequest, shouldFinalizeAsCancelled } from './task-cancel.js';
+import { applyReviewRequest, applyReviewApprove, applyReviewReject } from './task-review.js';
 export function registerTaskRoutes(app, opts) {
     const { broadcast, getAgentForChannel } = opts;
     // 获取所有任务
@@ -21,10 +23,19 @@ export function registerTaskRoutes(app, opts) {
     // 创建新任务
     app.post('/api/tasks', async (req, res) => {
         try {
-            const { type, title, description, steps } = req.body;
+            const { type, title, description, steps, parentIds } = req.body;
             if (!type || !title) {
                 return res.status(400).json({ error: 'type and title required' });
             }
+            // 2026-08-11 (Hermes 父依赖): parentIds 必须是已存在的任务 id
+            if (parentIds !== undefined) {
+                const tasks0 = await loadTaskQueue();
+                const known = new Set(tasks0.map((t) => t.id));
+                const unknown = (Array.isArray(parentIds) ? parentIds : []).filter((id) => !known.has(id));
+                if (unknown.length > 0) {
+                    return res.status(400).json({ error: `Unknown parent task ids: ${unknown.join(', ')}` });
+                }
+            }
             const tasks = await loadTaskQueue();
             const task = {
                 id: `task_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`,
@@ -35,6 +46,7 @@ export function registerTaskRoutes(app, opts) {
                 progress: 0,
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
+                parentIds: Array.isArray(parentIds) && parentIds.length > 0 ? parentIds : undefined,
                 steps: steps?.map((s, i) => ({
                     id: `step_${i}`,
                     name: s,
@@ -109,14 +121,24 @@ export function registerTaskRoutes(app, opts) {
             if (!channelId) {
                 return res.status(400).json({ error: 'channelId required' });
             }
-            const tasks = await loadTaskQueue();
-            const task = tasks.find(t => t.id === taskId);
-            if (!task) {
-                return res.status(404).json({ error: 'Task not found' });
-            }
-            if (isTaskExecuting()) {
+            // 2026-08-11: CAS 认领 — 只有 pending 能认领成功, 输家不重试
+            const { claimTaskForExecution } = await import('./server-storage.js');
+            const claim = await claimTaskForExecution(taskId);
+            if (claim === 'busy') {
                 return res.status(409).json({ error: 'Another task is currently executing' });
             }
+            if (claim === 'not-pending') {
+                const tasks = await loadTaskQueue();
+                const task = tasks.find(t => t.id === taskId);
+                return res.status(409).json({ error: `Task not claimable (status=${task?.status ?? 'missing'})` });
+            }
+            if (claim === 'parents-undone') {
+                const tasks = await loadTaskQueue();
+                const task = tasks.find(t => t.id === taskId);
+                return res.status(409).json({ error: `Task parents not done (${(task?.parentIds || []).join(', ')}) — 父任务完成后才能执行` });
+            }
+            const tasks = await loadTaskQueue();
+            const task = tasks.find(t => t.id === taskId);
             // 异步执行任务
             executeTask(task, channelId, getAgentForChannel, broadcast);
             res.json({ ok: true, taskId: task.id });
@@ -132,13 +154,11 @@ export function registerTaskRoutes(app, opts) {
             if (!channelId) {
                 return res.status(400).json({ error: 'channelId required' });
             }
-            const tasks = await loadTaskQueue();
-            const nextTask = tasks.find(t => t.status === 'pending');
+            // 2026-08-11: CAS 认领下一个 pending — 输家 (无任务/已被认领/忙) 返回, 不重试
+            const { claimNextPendingTask } = await import('./server-storage.js');
+            const nextTask = await claimNextPendingTask();
             if (!nextTask) {
-                return res.json({ ok: false, message: 'No pending tasks' });
-            }
-            if (isTaskExecuting()) {
-                return res.status(409).json({ error: 'Another task is currently executing' });
+                return res.json({ ok: false, message: 'No pending tasks or another task is executing' });
             }
             // 异步执行任务
             executeTask(nextTask, channelId, getAgentForChannel, broadcast);
@@ -148,13 +168,132 @@ export function registerTaskRoutes(app, opts) {
             res.status(500).json({ error: err.message });
         }
     });
+    // 取消任务 (2026-08-11, Hermes 两段式: cancel-requested → cancelled)
+    //   - pending 任务: 从未开始, 直接终态 cancelled (请求即完成, 不会卡在中间态)
+    //   - running 任务: 先置 cancel-requested (第一段: 请求已受理), executor 观测到后置 cancelled (第二段: 实际停止)
+    app.post('/api/tasks/:taskId/cancel', async (req, res) => {
+        try {
+            const { taskId } = req.params;
+            const { channelId } = req.body || {};
+            const tasks = await loadTaskQueue();
+            const task = tasks.find(t => t.id === taskId);
+            if (!task) {
+                return res.status(404).json({ error: 'Task not found' });
+            }
+            switch (task.status) {
+                case 'pending': {
+                    const t = applyCancelRequest(task.status);
+                    task.status = t.status;
+                    task.updatedAt = new Date().toISOString();
+                    await saveTaskQueue(tasks);
+                    broadcast({ type: 'task_status', taskId: task.id, status: t.status, progress: task.progress }, channelId);
+                    return res.json({ ok: true, taskId: task.id, status: t.status, phase: t.phase });
+                }
+                case 'running': {
+                    const t = applyCancelRequest(task.status);
+                    task.status = t.status;
+                    task.updatedAt = new Date().toISOString();
+                    await saveTaskQueue(tasks);
+                    broadcast({ type: 'task_status', taskId: task.id, status: t.status }, channelId);
+                    return res.json({ ok: true, taskId: task.id, status: t.status, phase: t.phase });
+                }
+                case 'cancel-requested':
+                    return res.json({ ok: true, taskId: task.id, status: 'cancel-requested', phase: 'already-requested' });
+                default:
+                    return res.status(409).json({ error: `Task already terminal (${task.status})` });
+            }
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // ==================== review 审批通道 (2026-08-11, Hermes request_review 模式) ====================
+    // running/pending → review (挂起等人工/审查者) → approve (review→completed) / reject (review→pending 退回队列)
+    // 请求审批
+    app.post('/api/tasks/:taskId/review', async (req, res) => {
+        try {
+            const { taskId } = req.params;
+            const { channelId } = req.body || {};
+            const tasks = await loadTaskQueue();
+            const task = tasks.find(t => t.id === taskId);
+            if (!task) {
+                return res.status(404).json({ error: 'Task not found' });
+            }
+            const t = applyReviewRequest(task.status);
+            if (t.phase === 'not-reviewable') {
+                return res.status(409).json({ error: `Task not reviewable (status=${task.status})` });
+            }
+            task.status = t.status;
+            task.updatedAt = new Date().toISOString();
+            await saveTaskQueue(tasks);
+            broadcast({ type: 'task_status', taskId: task.id, status: t.status }, channelId);
+            return res.json({ ok: true, taskId: task.id, status: t.status, phase: t.phase });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // 审批通过 (放行完成)
+    app.post('/api/tasks/:taskId/approve', async (req, res) => {
+        try {
+            const { taskId } = req.params;
+            const { channelId } = req.body || {};
+            const tasks = await loadTaskQueue();
+            const task = tasks.find(t => t.id === taskId);
+            if (!task) {
+                return res.status(404).json({ error: 'Task not found' });
+            }
+            const t = applyReviewApprove(task.status);
+            if (t.phase === 'not-reviewable') {
+                return res.status(409).json({ error: `Task not in review (status=${task.status})` });
+            }
+            task.status = t.status;
+            task.progress = 100;
+            task.updatedAt = new Date().toISOString();
+            await saveTaskQueue(tasks);
+            broadcast({ type: 'task_status', taskId: task.id, status: t.status, progress: 100 }, channelId);
+            broadcast({ type: 'status', content: `任务审批通过: ${task.title}` }, channelId);
+            return res.json({ ok: true, taskId: task.id, status: t.status, phase: t.phase });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // 审批驳回 (退回队列)
+    app.post('/api/tasks/:taskId/reject', async (req, res) => {
+        try {
+            const { taskId } = req.params;
+            const { channelId } = req.body || {};
+            const tasks = await loadTaskQueue();
+            const task = tasks.find(t => t.id === taskId);
+            if (!task) {
+                return res.status(404).json({ error: 'Task not found' });
+            }
+            const t = applyReviewReject(task.status);
+            if (t.phase === 'not-reviewable') {
+                return res.status(409).json({ error: `Task not in review (status=${task.status})` });
+            }
+            task.status = t.status;
+            task.progress = 0;
+            task.result = undefined;
+            task.updatedAt = new Date().toISOString();
+            await saveTaskQueue(tasks);
+            broadcast({ type: 'task_status', taskId: task.id, status: t.status, progress: 0 }, channelId);
+            broadcast({ type: 'status', content: `任务审批驳回, 退回队列: ${task.title}` }, channelId);
+            return res.json({ ok: true, taskId: task.id, status: t.status, phase: t.phase });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
 }
 // ==================== Task Execution ====================
 async function executeTask(task, channelId, getAgentForChannel, broadcast) {
-    // 使用 server-storage 的 startTaskExecution 做锁
-    const { startTaskExecution, endTaskExecution } = await import('./server-storage.js');
-    if (!startTaskExecution(task.id))
-        return;
+    // 2026-08-11: 认领已由 claimTaskForExecution/claimNextPendingTask (CAS) 完成并持锁,
+    //   这里不再重复 startTaskExecution (会因 isExecutingTask=true 返回 false 导致提前 return).
+    const { endTaskExecution, heartbeatTaskExecution } = await import('./server-storage.js');
+    // 2026-08-11 (Hermes 心跳): 开始执行先续期一次 — 认领后到首个 await 之间有调度延迟
+    await heartbeatTaskExecution(task.id).catch(() => { });
     const agent = await getAgentForChannel(channelId);
     const tasks = await loadTaskQueue();
     const taskIndex = tasks.findIndex(t => t.id === task.id);
@@ -193,6 +332,29 @@ async function executeTask(task, channelId, getAgentForChannel, broadcast) {
             default:
                 result = '未知任务类型';
         }
+        // 2026-08-11 (Hermes 两段式): executor 观测到 cancel-requested → 落终态 cancelled (第二段)
+        // 运行中被请求取消 → 不执行正常完成路径, 直接标记取消
+        const tasksAfter = await loadTaskQueue();
+        const idxAfter = tasksAfter.findIndex(t => t.id === task.id);
+        if (idxAfter >= 0 && shouldFinalizeAsCancelled(tasksAfter[idxAfter].status)) {
+            tasksAfter[idxAfter].status = 'cancelled';
+            tasksAfter[idxAfter].result = '任务已取消';
+            tasksAfter[idxAfter].updatedAt = new Date().toISOString();
+            await saveTaskQueue(tasksAfter);
+            broadcast({ type: 'task_status', taskId: task.id, status: 'cancelled', progress: tasksAfter[idxAfter].progress }, channelId);
+            broadcast({ type: 'status', content: `任务已取消: ${task.title}` }, channelId);
+            return;
+        }
+        // 2026-08-11 (Hermes request_review 模式): 执行完成但任务已挂入 review 审批通道 →
+        //   只落结果, 不覆盖成 completed; 等 approve 路由放行 (review → completed)
+        if (idxAfter >= 0 && tasksAfter[idxAfter].status === 'review') {
+            tasksAfter[idxAfter].result = result;
+            tasksAfter[idxAfter].updatedAt = new Date().toISOString();
+            await saveTaskQueue(tasksAfter);
+            broadcast({ type: 'task_status', taskId: task.id, status: 'review', progress: tasksAfter[idxAfter].progress }, channelId);
+            broadcast({ type: 'status', content: `任务执行完成, 待审批: ${task.title}` }, channelId);
+            return;
+        }
         // 更新任务状态
         const tasks = await loadTaskQueue();
         const idx = tasks.findIndex(t => t.id === task.id);
@@ -200,23 +362,79 @@ async function executeTask(task, channelId, getAgentForChannel, broadcast) {
             tasks[idx].status = 'completed';
             tasks[idx].progress = 100;
             tasks[idx].result = result;
+            // 2026-08-11 (熔断器): 成功完成 → 连续失败计数清零
+            tasks[idx].consecutiveFailures = 0;
+            tasks[idx].lastFailureError = undefined;
+            tasks[idx].claimExpires = undefined;
             tasks[idx].updatedAt = new Date().toISOString();
             await saveTaskQueue(tasks);
         }
         broadcast({ type: 'task_status', taskId: task.id, status: 'completed', progress: 100, result }, channelId);
         broadcast({ type: 'ai', content: result }, channelId);
+        // 2026-08-11 (Hermes 完成防幻觉, advisory): 异步校验 result 里的任务/文件引用,
+        //   幽灵引用 → 存 task.warnings + broadcast warning (不阻塞完成 — 单次同步执行无法返工)
+        void (async () => {
+            try {
+                const { verifyTaskResult } = await import('./task-verify.js');
+                const allTasks = await loadTaskQueue();
+                const v = await verifyTaskResult(result, { knownTaskIds: allTasks.map((t) => t.id) });
+                if (v.warnings.length > 0) {
+                    const q = await loadTaskQueue();
+                    const vi = q.findIndex((t) => t.id === task.id);
+                    if (vi >= 0) {
+                        q[vi].warnings = v.warnings;
+                        await saveTaskQueue(q);
+                    }
+                    for (const w of v.warnings) {
+                        broadcast({ type: 'error', content: `⚠ ${w}` }, channelId);
+                    }
+                }
+            }
+            catch {
+                // 校验失败不阻塞完成
+            }
+        })();
     }
     catch (error) {
         const tasks = await loadTaskQueue();
         const idx = tasks.findIndex(t => t.id === task.id);
         if (idx >= 0) {
-            tasks[idx].status = 'failed';
-            tasks[idx].error = error.message;
-            tasks[idx].updatedAt = new Date().toISOString();
-            await saveTaskQueue(tasks);
+            const t = tasks[idx];
+            // 取消请求在先 → 异常属于取消副作用, 落 cancelled 而非 failed (Hermes 两段式)
+            if (t.status === 'cancel-requested') {
+                t.status = 'cancelled';
+                t.error = error.message;
+                t.updatedAt = new Date().toISOString();
+                await saveTaskQueue(tasks);
+            }
+            else {
+                // 2026-08-11 (Hermes consecutive_failures 熔断器): 失败计数 +1;
+                //   达到阈值 → failed 终态 (熔断, 不再自动重试)
+                //   未达阈值 → 回 pending 可重新认领 (execute-next 自动重试), 防一次性小错卡死队列
+                const { recordTaskFailure } = await import('./task-breaker.js');
+                const envLimit = Number(process.env.BOLLOON_FAILURE_LIMIT || '');
+                const f = recordTaskFailure(t, envLimit > 0 ? envLimit : undefined);
+                t.consecutiveFailures = f.consecutiveFailures;
+                t.lastFailureError = String(error.message || error).slice(0, 300);
+                t.claimExpires = undefined;
+                if (f.tripped) {
+                    t.status = 'failed';
+                    t.error = `连续失败 ${f.consecutiveFailures} 次, 熔断 (不再自动重试): ${String(error.message || error).slice(0, 200)}`;
+                }
+                else {
+                    t.status = 'pending';
+                    t.error = `失败 ${f.consecutiveFailures} 次 (自动重试): ${String(error.message || error).slice(0, 200)}`;
+                }
+                t.updatedAt = new Date().toISOString();
+                await saveTaskQueue(tasks);
+            }
         }
-        broadcast({ type: 'task_status', taskId: task.id, status: 'failed', error: error.message }, channelId);
-        broadcast({ type: 'error', content: `任务执行失败: ${error.message}` }, channelId);
+        // 读取实际落态 (failed 熔断 / pending 自动重试 / cancelled)
+        const tasksNow = await loadTaskQueue();
+        const taskNow = tasksNow.find(t => t.id === task.id);
+        const finalStatus = taskNow?.status ?? 'failed';
+        broadcast({ type: 'task_status', taskId: task.id, status: finalStatus, error: error.message }, channelId);
+        broadcast({ type: 'error', content: `任务执行失败: ${error.message}${finalStatus === 'pending' ? ' (自动重试)' : ''}` }, channelId);
     }
     endTaskExecution();
 }

package/dist/web/server-sse.js

@@ -11,6 +11,7 @@
  * SSEClient type 来自 ./server-types.ts.
  */
 import * as crypto from 'crypto';
+import { guardClientWriteNoise } from './loop-noise.js';
 const sseClients = new Set();
 export function getSseClients() {
     return sseClients;
@@ -57,12 +58,16 @@ export function broadcast(data, channelId) {
     console.log(`[broadcast] type=${data.type}, channelId=${channelId}, seq=${seq}, msgId=${msgId}, clients=${sseClients.size}`);
     for (const client of sseClients) {
         if (!channelId || client.channelId === channelId) {
-            try {
+            // 2026-08-11 (Hermes loop_noise): 客户端在写 drain 前断开 → 每次广播对已关闭 res
+            //   write 都会抛 "write EPIPE / write after end / 连接已关闭"。这是预期副作用, 不是
+            //   bug — guardClientWriteNoise 把同类错误折叠成一行 (节流), 不打印每条刷屏。
+            void guardClientWriteNoise(() => {
                 client.res.write(message);
-            }
-            catch (e) {
-                console.error(`[broadcast] 写入失败:`, e.message);
-            }
+                return Promise.resolve();
+            }, {
+                label: `sse-broadcast:${data.type}`,
+                onError: (e) => console.error(`[broadcast] 写入失败 (非良性): ${e.message}`),
+            });
         }
     }
 }

package/dist/web/server-storage.js

@@ -13,6 +13,7 @@
 import * as fs from 'fs/promises';
 import { CHANNELS_PATH, SESSION_CACHE_PATH, TASK_QUEUE_PATH, THEME_PATH, } from './server-types.js';
 import { saveWindow as saveSessionWindow, loadWindow as loadSessionWindow } from '../bootstrap/session-window.js';
+import { parentsSatisfied } from './task-deps.js';
 // 写盘去重: 上次写盘内容, 用于跳过幂等调用
 let lastChannelsJson = '';
 // 写盘保护: 任何调用 saveChannels 后更新
@@ -179,6 +180,116 @@ export async function loadTaskQueue() {
 export async function saveTaskQueue(tasks) {
     await fs.writeFile(TASK_QUEUE_PATH, JSON.stringify(tasks, null, 2));
 }
+// ==================== 任务认领 CAS (2026-08-11, Hermes kanban 模式) ====================
+// kanban_db.py: "WAL + BEGIN IMMEDIATE + compare-and-swap on tasks.status/claim_lock —
+//   至多一个 worker 能认领任务, 输家看到 0 行受影响就退出, 无重试循环, 无分布式锁."
+// Bolloon 对应: 任务队列是 JSON 文件, 用进程内互斥链 (withTaskQueueLock) 序列化
+//   load→CAS(status==='pending'→'running')→save, 输家返回 null/not-pending, 不重试.
+let taskQueueLock = Promise.resolve();
+function withTaskQueueLock(fn) {
+    const run = taskQueueLock.then(fn);
+    taskQueueLock = run.then(() => undefined, () => undefined);
+    return run;
+}
+/** 认领 TTL 默认 15min (BOLLOON_CLAIM_TTL_SECONDS 可调) — Hermes DEFAULT_CLAIM_TTL_SECONDS=15*60 */
+export function claimTtlSeconds() {
+    const v = Number(process.env.BOLLOON_CLAIM_TTL_SECONDS || '');
+    return v > 0 ? v : 15 * 60;
+}
+/**
+ * CAS 认领指定任务: 只有 status==='pending' 才能认领成功 (原子翻成 running).
+ * 认领点强制父依赖不变式 (Hermes kanban): 任一父未 completed/cancelled → 不认领, 返回 'parents-undone'.
+ * 认领写 claim_expires (TTL) — 崩溃/卡死后由 releaseStaleClaims 释放, 锁不泄漏.
+ */
+export async function claimTaskForExecution(taskId) {
+    if (isExecutingTask)
+        return 'busy';
+    return withTaskQueueLock(async () => {
+        if (isExecutingTask)
+            return 'busy';
+        const tasks = await loadTaskQueue();
+        const t = tasks.find((x) => x.id === taskId);
+        if (!t || t.status !== 'pending')
+            return 'not-pending';
+        // 父依赖不变式: 父未完成 → 拒绝认领 (依赖悬空时任务不可执行)
+        if (!parentsSatisfied(t, tasks))
+            return 'parents-undone';
+        t.status = 'running';
+        t.claimExpires = Date.now() + claimTtlSeconds() * 1000;
+        t.updatedAt = new Date().toISOString();
+        await saveTaskQueue(tasks);
+        isExecutingTask = true;
+        executionTaskId = taskId;
+        return 'claimed';
+    });
+}
+/**
+ * CAS 认领下一个 pending 任务; 无任务/已被认领 → null (输家不重试).
+ * 只认领父依赖满足的 pending — 父未完成的任务跳过 (等父 done 后可被认领), 不阻塞队列.
+ */
+export async function claimNextPendingTask() {
+    if (isExecutingTask)
+        return null;
+    return withTaskQueueLock(async () => {
+        if (isExecutingTask)
+            return null;
+        const tasks = await loadTaskQueue();
+        const t = tasks.find((x) => x.status === 'pending' && parentsSatisfied(x, tasks));
+        if (!t)
+            return null;
+        t.status = 'running';
+        t.claimExpires = Date.now() + claimTtlSeconds() * 1000;
+        t.updatedAt = new Date().toISOString();
+        await saveTaskQueue(tasks);
+        isExecutingTask = true;
+        executionTaskId = t.id;
+        return t;
+    });
+}
+/**
+ * 心跳续期 (Hermes kanban_heartbeat): 执行中有实质进展时调用, 把 claim_expires 推到 now+TTL.
+ * CAS: 只续期当前执行中的任务 (executionTaskId 匹配 + status==='running').
+ */
+export async function heartbeatTaskExecution(taskId) {
+    return withTaskQueueLock(async () => {
+        if (executionTaskId !== taskId)
+            return false;
+        const tasks = await loadTaskQueue();
+        const t = tasks.find((x) => x.id === taskId);
+        if (!t || t.status !== 'running')
+            return false;
+        t.claimExpires = Date.now() + claimTtlSeconds() * 1000;
+        t.updatedAt = new Date().toISOString();
+        await saveTaskQueue(tasks);
+        return true;
+    });
+}
+/**
+ * 释放过期认领 (Hermes release_stale_claims): 扫所有 running 且 claim_expires 已过期的任务
+ * → 释放 in-memory 锁 + 任务回 pending (可重新认领执行). 防 executeTask 卡死/崩溃后锁泄漏.
+ * 返回释放数量. 安全可频繁调用.
+ */
+export async function releaseStaleClaims() {
+    return withTaskQueueLock(async () => {
+        const now = Date.now();
+        const tasks = await loadTaskQueue();
+        const stale = tasks.filter((t) => t.status === 'running' && t.claimExpires !== undefined && t.claimExpires < now);
+        if (stale.length === 0)
+            return 0;
+        for (const t of stale) {
+            t.status = 'pending';
+            t.claimExpires = undefined;
+            t.updatedAt = new Date().toISOString();
+        }
+        await saveTaskQueue(tasks);
+        // 当前执行锁指向过期任务 → 一并释放 (卡死的 executeTask 其锁也失效)
+        if (executionTaskId && stale.some((t) => t.id === executionTaskId)) {
+            isExecutingTask = false;
+            executionTaskId = null;
+        }
+        return stale.length;
+    });
+}
 /** 执行 task 的 helper 标记 (server.ts 内部 still 持有 lock) */
 export function startTaskExecution(taskId) {
     if (isExecutingTask)