@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/agents/external-events.js

@@ -10,7 +10,9 @@
  *                    ④ 用 eventId 去重 ⑤ 写入事件事实 (Goal 证据) ⑥ 唤醒 Goal ⑦ 由 Supervisor 下一轮继续
  *   **事件处理器不直接启动 agent** —— 它只写事实 + 唤醒; 谁来执行由 Supervisor 决定。
  */
-import { readGoal, setContinuation, updateGoal, listGoals, addEvidence, } from './goal-store.js';
+import { readGoal, setContinuation, listGoals, addEvidence, } from './goal-store.js';
+// 2026-09-25 (M0 接线冻结, 规则 ②): Goal 状态变更只有一个漏斗
+import { reduceGoalState } from './goal-state-reducer.js';
 // ── 绑定等待 ────────────────────────────────────────────────────────────────
 export function defaultWaitExpiry(now = Date.now(), ttlMs = 30 * 60_000) {
     return new Date(now + ttlMs).toISOString();
@@ -114,6 +116,13 @@ export async function deliverExternalEvent(event, deps = {}) {
     await addEvidence(goal.goalId, [
         `外部事件 (${event.source}${event.fromDid ? `, ${String(event.fromDid).slice(0, 16)}…` : ''}): ${event.eventName || '结果'} eventId=${event.eventId} requestId=${event.requestId || '-'} payload=${JSON.stringify(event.payload ?? null).slice(0, 300)}`,
     ]).catch(() => { });
+    // ★ 等待类的 continuation.state 也必须一起拉回 `active`:
+    //   飞轮的"等外部"判定读的是 continuation.state (`state=waiting_external` → wait), 而界面
+    //   (`toUserVisibleState`) 也只读 continuation —— 只改 wakeReason 不改 state 会留下
+    //   "wakeReason=active 但 state=awaiting_external" 的自相矛盾 (M5-⑤ 真跑复现: Goal 显示已醒,
+    //   下一轮却仍被判"在等外部", 永远没人跑)。
+    const wasWaiting = ['awaiting_external', 'retry_wait', 'recovering'].includes(String(goal.status))
+        || ['awaiting_external', 'retry_wait', 'recovering'].includes(String(goal.continuation?.state));
     await setContinuation(goal.goalId, {
         deliveredEventIds: [...seen, event.eventId].slice(-20),
         external: undefined,
@@ -122,18 +131,33 @@ export async function deliverExternalEvent(event, deps = {}) {
         needsExternal: undefined,
         autoContinue: true,
         wakeAt: undefined,
+        ...(wasWaiting ? { state: 'active' } : {}),
     });
     // 状态拉回 active (只有还在"等外部"的状态才动它) —— Supervisor 下一轮才会真的执行
+    // 规则 ②: 状态变更经 Goal reducer (单一漏斗; 它自己会跳过终态 Goal)
     try {
         if (['awaiting_external', 'retry_wait', 'recovering'].includes(String(goal.status))) {
-            await updateGoal(goal.goalId, { status: 'active' });
+            await reduceGoalState({
+                goalId: goal.goalId,
+                intent: 'external_event_arrived',
+                now: new Date(now).toISOString(),
+                by: 'external-events',
+            });
         }
     }
     catch { /* 状态写失败 → 下一轮仍会跳过等待; 事件事实已写入, 不丢 */ }
     // 唤醒 (由 Supervisor 下一轮真正执行)
+    // `woke` 的语义跟着**盘上事实**走, 不只看宿主回调的返回值: 上面已经把等待事实清掉、把
+    //   wakeReason/state 拉回 active 了 —— 宿主注入的 wake (= `Supervisor.notifyExternal`) 的
+    //   "还在等外部吗"前置条件此刻已不成立, 它会早退返回 false。若照抄它的返回值, 一次真唤醒会被
+    //   报成"没唤醒" (M5-⑤ 真跑就是这么读到的)。宿主回调仍然要调 (它有清等待/记次数的副作用)。
     let woke = false;
     if (deps.wake)
-        woke = await deps.wake(goal.goalId).catch(() => false);
+        await deps.wake(goal.goalId).catch(() => false);
+    const after = await readGoal(goal.goalId);
+    const stillWaiting = !!after && (['awaiting_external', 'retry_wait', 'recovering'].includes(String(after.status))
+        || after.continuation?.state === 'awaiting_external');
+    woke = !!after && !stillWaiting;
     return { ok: true, reason: 'delivered', goalId: goal.goalId, woke };
 }
 /**
@@ -154,9 +178,14 @@ export async function expireExternalWaits(opts = {}) {
             continue;
         const reason = `外部事件超时 (${w.expectedSource}${w.expectedEvent ? `:${w.expectedEvent}` : ''}, requestId=${w.requestId}, 过期于 ${w.expiresAt}) → 转人工`;
         out.push({ goalId: g.goalId, wait: w, reason });
-        await setContinuation(g.goalId, { external: undefined, wakeReason: 'needs_human', needsExternal: undefined, autoContinue: false, lastExternalTimeout: reason });
-        await updateGoal(g.goalId, { status: 'needs_human' }).catch(() => { });
-        await addEvidence(g.goalId, [`外部事件超时: ${reason}`]).catch(() => { });
+        // 规则 ②: 撤等待 + 转人工 + 证据, 一次走 Goal reducer (旧写法是 setContinuation + updateGoal + addEvidence 三连)
+        await reduceGoalState({
+            goalId: g.goalId,
+            intent: 'external_wait_expired',
+            now: new Date(now).toISOString(),
+            by: 'external-events',
+            reason,
+        }).catch(() => { });
     }
     return out;
 }

package/dist/agents/gateway-group.js

@@ -6,6 +6,14 @@
  *
  * 符合用户习惯: 群组 = 微信式群聊 — 加入链接即进群, 发消息全网同步.
  * 持久化: ~/.bolloon/gateway-groups.json (重启后仍是群成员, 自动重开 store).
+ *
+ * 2026-09-24 跨进程可重开:
+ *   · 群消息 (OrbitDB events store 的 oplog 条目 + manifest) 现在真落盘 ——
+ *     `createBolloonIpfs` 用 FsBlockstore/FsDatastore 写 ~/.bolloon/orbitdb/ipfs/{blocks,datastore},
+ *     所以"建群的那个进程退出后, 新进程用群链接重开还能读到既有消息"。
+ *     (修复前: 区块只在内存, 新进程一开就报 "No block brokers capable of retrieving blocks")
+ *   · 读不到必须报读不到: `groupMessages` 在 store 打不开时**抛 GroupStoreUnreachableError**,
+ *     不再返回 `[]`。把"读不到"显示成"群里没有消息"是骗人, 本条不可回退。
  */
 import * as os from 'os';
 import * as path from 'path';
@@ -19,6 +27,33 @@ function getDb() { return _dbOverride ?? getCIDDatabase(); }
 export function resetGroupState() {
     storeCache.clear();
     onChangeCallbacks.clear();
+    openFailures.clear();
+}
+/**
+ * 群 store 打不开 (区块不在本机 / 地址不可解析)。
+ *
+ * 2026-09-24: 以前打不开 → `groupMessages` 返回 `[]`, 于是 CLI 把"整个群读不到"报成
+ * "群里本期没有过程痕迹 (群里真没有, 不是读失败)" —— 把"读不到"说成了"没有"。
+ * 现在读不到就抛: 上游 (task trail / API) 必须如实报 TRANSPORT_FAILED。
+ */
+export class GroupStoreUnreachableError extends Error {
+    groupId;
+    address;
+    cause;
+    code = 'STORE_UNREACHABLE';
+    constructor(groupId, address, cause) {
+        const why = String(cause?.message ?? cause ?? '未知原因').slice(0, 160);
+        super(`群组 store 不可达 (${groupId}): ${why}`);
+        this.groupId = groupId;
+        this.address = address;
+        this.cause = cause;
+        this.name = 'GroupStoreUnreachableError';
+    }
+}
+/** 打开失败的一句话原因 (给人类输出用; 没有失败记录时返回通用话术) */
+function unreachableReason(err) {
+    const m = String(err?.message ?? err ?? '').trim();
+    return m ? m.slice(0, 160) : '区块不在本机且没有可用的 block broker (跨机同步仍是另一回事, 需 peers)';
 }
 // ============ 持久化 ============
 const groupsFile = () => path.join(os.homedir() || '/tmp', '.bolloon', 'gateway-groups.json');
@@ -71,23 +106,42 @@ export function detectGroupLink(text) {
 const storeCache = new Map();
 /** 订阅回调注册 (server 层挂 SSE 广播) */
 const onChangeCallbacks = new Map();
+/** store 打开失败的原始原因 (按 groupId) —— 用来把"打不开"和"没有消息"分开 */
+const openFailures = new Map();
 function groupIdOf(address) {
     // /orbitdb/zdpu... → zdpu... (地址后 12 位做短 id)
     const m = /\/orbitdb\/(.{8,})/.exec(address);
     return m ? m[1] : address;
 }
-/** 打开群组 store (缓存) — 可写 (replica=false, write:'*') */
+/**
+ * 打开群组 store (缓存) — 可写 (replica=false, write:'*')。
+ * 打不开 → 记下原始原因 + 返回 null (不抛: 调用方各自决定用什么话术报)。
+ * 2026-09-24: 必须 try/catch —— openStoreByAddress 现在抛 OrbitDBStoreUnreachableError。
+ */
 async function openGroupStore(address) {
     const id = groupIdOf(address);
     if (storeCache.has(id))
         return storeCache.get(id);
     const db = getDb();
-    const store = await db.openStoreByAddress(address, 'events', {
-        replica: false,
-        accessController: { write: ['*'] },
-    });
-    if (!store)
+    let store = null;
+    try {
+        // 2026-09-24: 不再传 `replica` —— `@orbitdb/core` 4.0.0 的 open() 没有这个参数
+        // (src/orbitdb.js:118), 传了被丢; 之前那行是"不存在的语义"。
+        // 可写与否由 manifest 里的 ACL 决定, 且**打开既有地址时 ACL 从 manifest 取回、
+        // 入参 accessController 被覆盖** (src/orbitdb.js:129-131) —— 所以这里传什么都不改变权限。
+        store = await db.openStoreByAddress(address, 'events', {
+            accessController: { write: ['*'] },
+        });
+    }
+    catch (e) {
+        openFailures.set(id, e);
+        return null;
+    }
+    if (!store) {
+        openFailures.set(id, new Error('openStoreByAddress 返回 null (没拿到 store, 也没给出原因)'));
         return null;
+    }
+    openFailures.delete(id);
     storeCache.set(id, store);
     // 订阅: 新消息 → 通知回调 (server SSE)
     store.onChange(() => {
@@ -161,7 +215,11 @@ export async function joinGroup(link) {
     }
     const store = await openGroupStore(parsed.address);
     if (!store) {
-        return { ok: false, error: '群组 store 不可达 (群主节点需在线), 稍后重试或让群主分享最新链接' };
+        return {
+            ok: false,
+            code: 'STORE_UNREACHABLE',
+            error: `群组 store 不可达: ${unreachableReason(openFailures.get(id))}`,
+        };
     }
     const name = parsed.name || id.slice(0, 12);
     const info = {
@@ -177,7 +235,36 @@ export async function joinGroup(link) {
 export async function listGroups() {
     return loadGroups();
 }
-/** 获取群组 store 的最新消息 (ts 升序, 取最后 N 条) */
+/**
+ * 退群 (2026-09-24): 从本机群列表里摘掉 (撤销"我是成员"这条本地事实)。
+ *
+ * 只改**本机**记录: 群 store 本身是公共 append-only 的, 别人那边的成员表/消息
+ * 不会因为本机退出而改 (本模块没有"踢人/解散"的权限, 也不假装有)。
+ * 返回 `removed` = 被摘掉的 groupId (按 id 或群名匹配)。
+ *
+ * 注意: 底层 OrbitDB store 已在进程内打开的**不会**在这里关 (适配层没暴露 close);
+ * 对 `bolloon task group leave` 这种一次性进程无影响, 长驻进程里它活到进程结束。
+ */
+export async function leaveGroup(idOrName) {
+    const raw = String(idOrName || '').trim();
+    if (!raw)
+        return { ok: false, error: '缺少 groupId (或群名)' };
+    const groups = await loadGroups();
+    const hit = groups.find((g) => g.id === raw) || groups.find((g) => g.name === raw) || null;
+    if (!hit)
+        return { ok: false, error: `本机没有这个群: ${raw} (既不是已加入群的 groupId, 也不是群名)` };
+    storeCache.delete(hit.id);
+    openFailures.delete(hit.id);
+    await saveGroups(groups.filter((g) => g.id !== hit.id));
+    return { ok: true, removed: hit.id };
+}
+/**
+ * 获取群组 store 的最新消息 (ts 升序, 取最后 N 条)。
+ *
+ * 两个"空"必须分开 (2026-09-24):
+ *   · 本机没这个群 (不在群列表里) → 返回 `[]` (上游 resolveGroupRef 已单独拦成 NOT_FOUND)
+ *   · 群在列表里但 store 打不开 → **抛 GroupStoreUnreachableError** (读不到 ≠ 没有消息)
+ */
 export async function groupMessages(groupId, limit = 50) {
     let store = storeCache.get(groupId) ?? null;
     if (!store) {
@@ -187,9 +274,9 @@ export async function groupMessages(groupId, limit = 50) {
             return [];
         store = await openGroupStore(g.address);
         if (!store)
-            return [];
+            throw new GroupStoreUnreachableError(groupId, g.address, openFailures.get(groupId));
     }
-    const all = await store.all().catch(() => []);
+    const all = await store.all();
     const msgs = [];
     for (const entry of all) {
         const v = entry.value;
@@ -217,8 +304,9 @@ export async function groupSend(groupId, text, from) {
         if (!g)
             return { ok: false, error: '群组不存在 (先 joinGroup)' };
         store = await openGroupStore(g.address);
-        if (!store)
-            return { ok: false, error: '群组 store 不可达' };
+        if (!store) {
+            return { ok: false, error: `群组 store 不可达: ${unreachableReason(openFailures.get(groupId))}` };
+        }
     }
     try {
         await store.add({ from: String(from || 'anonymous'), text: msg, ts: Date.now() });

package/dist/agents/goal-criteria.js

@@ -9,6 +9,8 @@
  *   · 证据跨 Run 汇总 (Run 证据 → Goal 证据, 去重), unresolvedItems 跨 Run 保留。
  */
 import { readGoal, setCriteria, addEvidence, updateGoal, } from './goal-store.js';
+// 2026-09-25 (M0 接线冻结, 规则 ②): Goal 状态变更只有一个漏斗
+import { reduceGoalState } from './goal-state-reducer.js';
 import { readRun } from './run-store.js';
 /** 太模糊的目标: 判据无从谈起 (短且没有可核验的动作词) */
 export function looksVague(objective) {
@@ -54,9 +56,14 @@ export async function proposeForGoal(goalId) {
     }
     const p = proposeCriteria(goal.objective);
     if (!p.ok) {
-        // 太模糊 → 明确交人, 不写假判据
-        await addEvidence(goalId, [`判据生成失败: ${p.reason}`]).catch(() => { });
-        await updateGoal(goalId, { status: 'needs_human' }).catch(() => { });
+        // 太模糊 → 明确交人, 不写假判据 (规则 ②: 状态经 Goal reducer 写; 它同时留一条可追溯证据)
+        await reduceGoalState({
+            goalId,
+            intent: 'criteria_needs_human',
+            now: new Date().toISOString(),
+            by: 'goal-criteria',
+            reason: p.reason,
+        }).catch(() => null);
         return p;
     }
     await setCriteria(goalId, { criteria: p.criteria, source: 'agent_proposed', confirm: false });

package/dist/agents/goal-flywheel/block-executor.js

@@ -0,0 +1,346 @@
+/**
+ * block-executor.ts — P3b: 把 `planBlockHandling` 算出的**处置动作真执行** (2026-09-26)
+ *
+ * 存在的理由 (P5 验收 §2 缺口 4, 原话): 「`applyBlockHandling` 只对 `needs_human` / `escalate_parent` /
+ * `change_plan` 真的改 Goal 状态 (→ needs_human) 或清 `pendingReports` (takeover); 而
+ * `send_adjustment` / `request_report` / **`replace_child`** 只被塞进 `requests` 字符串列表 ——
+ * 没有真的下发调整指令、没有真的换人、没有重派新合同」。
+ * 本模块补上"**真执行**"这一半: 动作 → 具体一次调用 (带正确的对象与参数), 并把
+ * 「做不了」的原因**显式**交人, 而不是静默塞进一个列表。
+ *
+ * ## 纪律 (与 `work-monitor.ts` 同一套, 不许松)
+ *
+ *   - **纯逻辑**: 零 I/O —— 不 import `fs` / 不 import 其它阶段的实现, 只与 `types.ts` +
+ *     `work-monitor.ts` 的**纯函数** (`planBlockHandling`) 耦合。所有副作用走**注入的端口**。
+ *   - **时间注入**: `now` 由调用方给, 本模块不读真实钟。
+ *   - **不越权**: ① 执行权不在手上 (`authority.leaseHeld !== true`) → `takeover` **拒绝执行,
+ *     端口一次都不调**; ② 调用者是子 Agent (`caller === 'child'`) → 一切改别人状态的动作全拒;
+ *     ③ 工具/权限/预算被阻 → 即使记录里写着 `takeover`/`replace_child` 也**硬拒** (纵深防御,
+ *     不靠上游自觉)。
+ *   - **不静默**: 每一项"本该做却做不了"的事 (端口缺失 / 端口抛错 / 越权被拒 / 没有动作可做)
+ *     都必须出现在 `needsHuman[]` 里, 并带人可读原因。`silentRisk` 是这份保证的自检位。
+ *   - **只给结论不动手**: 本模块自己**不写** Goal / Run / 磁盘 —— 那是注入端口 (`record`) 与
+ *     接线层的事; 因此它不会绕过「只有 Goal reducer 能改 Goal 状态」这条冻结规则 (规则 ②)。
+ *
+ * ## 接入点 (接线 = 别人的文件, 本模块只写清"差哪一行")
+ *
+ * 真实 tick 里的接入点是 `src/agents/execution-supervisor.ts` 的 `tick()` 内、
+ * 阻塞巡检那一段 (**当前 L423–L439**「2.5 阻塞巡检」, `applyBlockHandling` 在 **L429**): 现在那里只调
+ * `collectWorkBlocks` + `applyBlockHandling`, 拿到 `handling.actions` 后仅写进 `report.blocks` 与 log
+ * (`handling.takeovers` 也只打了一行"父接管子工作"的日志)。**差的就是一行**:
+ *
+ * ```ts
+ * // execution-supervisor.ts, applyBlockHandling(...) 之后 (同一段 try 内)
+ * const execution = await executeBlockHandling({
+ *   goalId: g.goalId,
+ *   blocks,
+ *   now: nowIso,
+ *   // 执行权: 本 tick 内该 Goal 的 lease **尚未**被本 worker 持有 (认领发生在第 3 步) →
+ *   //   这里如实传 false; 真正的父侧接管应由"已持有 lease 的那条路径"调 (见下)
+ *   authority: { leaseHeld: false, caller: 'supervisor', leaseOwner: null },
+ *   ports: blockExecutorPorts({ home }),   // ← 这个 helper **还没写**: 属接线层的活 (本模块是纯逻辑)
+ * });
+ * for (const a of execution.needsHuman) {
+ *   this.emit({ kind: 'needs_human', goalId: g.goalId, message: `${a.blockId}: ${a.reason}` });
+ * }
+ * ```
+ *
+ * 端口实现落在**接线层** (`goal-flywheel-wiring.ts`, 本模块不 import 它):
+ *   `claimLease` → `goal-store.claimGoal` (抢到再 `heartbeatGoal` 续) ·
+ *   `replaceChild` → `subagent-manager` 停旧 + `dispatchChildWork` 重派新合同 ·
+ *   `sendAdjustment` / `requestReport` → `sendChildInstruction` 一类的下发面 ·
+ *   `changePlan` → 父改计划 (写 Goal 的计划字段, 经 reducer) ·
+ *   `escalate` → Goal reducer 的 `block_escalated_human` (to='parent' 在 Goal 层同样收敛到人) ·
+ *   `record` → `addEvidence` + `recordWorkHeartbeat` 一类的事实记录。
+ * **本模块刻意不做这些事** —— 端口没注入时它只会如实报 `needs_human` (端口缺失), 不会假装做过。
+ *
+ * 阴性对照 (怎么知道这道门不是装饰; 见 `src/test/goal-flywheel-p6-block-executor.test.ts`):
+ *   ① 把手上的 `leaseHeld` 传成 false → `takeover` 必须变成 `refused` 且 `claimLease` **零调用**;
+ *   ② 把 `tool_blocked` 记录的 `suggestedAction` 改成 `replace_child` → 必须被硬拒 (不自动绕过 Harness);
+ *   ③ 把所有端口拿掉 → 每一项都必须是 `needsHuman` (不是空数组、不是静默跳过);
+ *   ④ 把 `escalate` 端口改成抛错 → 那一项必须是 `failed` + 原因里含错误原文 (不吞)。
+ */
+import { planBlockHandling } from './work-monitor.js';
+// ============================================================================
+// 硬规则常量 (导出: 测试与接线层都不许自己编)
+// ============================================================================
+/**
+ * **永不**自动绕过 Harness 的阻塞类型。
+ *
+ * `planBlockHandling` 本身就不会给这些类型 `takeover`/`replace_child`; 本表是**纵深防御** ——
+ * 磁盘/JSON 造出来的记录 (`suggestedAction` 可以被外部写成任意值) 也挡得住。
+ */
+export const NO_AUTO_BYPASS_KINDS = [
+    'tool_blocked',
+    'permission_blocked',
+    'budget_blocked',
+];
+/** 这些动作要动别人的执行状态, 子 Agent 侧一律不许做 (只允许父/调度器/人) */
+export const PARENT_ONLY_ACTIONS = [
+    'takeover',
+    'replace_child',
+    'send_adjustment',
+    'request_report',
+    'change_plan',
+    'escalate_parent',
+];
+/** 没有任何副作用、只表示"继续等"的动作 (执行后记 `deferred`, 不算失败) */
+export const DEFERRED_ACTIONS = ['wait_dependency'];
+/** 动作 → 它需要的端口名 (缺端口 = 做不了 = 必须如实报人) */
+export const PORT_FOR_ACTION = {
+    send_adjustment: 'sendAdjustment',
+    replace_child: 'replaceChild',
+    takeover: 'claimLease',
+    request_report: 'requestReport',
+    escalate_parent: 'escalate',
+    change_plan: 'changePlan',
+    wait_dependency: null, // 无副作用: 不需要端口
+    needs_human: 'escalate', // 有 escalate 就真的上报; 没有也必须在 needsHuman 里留下
+};
+// ============================================================================
+// 纯判定 (导出给接线层/测试复用: "这个动作在我这个处境下能不能做")
+// ============================================================================
+/** 该动作在给定处境下能不能做 (不能做时给出**人可读**的原因; 能做时 reason=null) */
+export function mayExecuteAction(action, kind, authority) {
+    if (NO_AUTO_BYPASS_KINDS.includes(kind) && (action === 'takeover' || action === 'replace_child')) {
+        return {
+            allowed: false,
+            reason: `不自动绕过 Harness: 阻塞类型「${kind}」只允许 改计划/等依赖/转人工, 不得 ${action}`,
+        };
+    }
+    if (authority.caller === 'child' && PARENT_ONLY_ACTIONS.includes(action)) {
+        return { allowed: false, reason: `子 Agent 不得执行「${action}」—— 处置权只在父/调度器/人手上` };
+    }
+    if (action === 'takeover' && authority.leaseHeld !== true) {
+        return {
+            allowed: false,
+            reason: `执行权不在手上 (拿不到互斥执行权${authority.leaseOwner ? `, 现持有者=${authority.leaseOwner}` : ''}) → 拒绝接管, 交人`,
+        };
+    }
+    return { allowed: true, reason: null };
+}
+/** 调整指令原文 (纯函数; 不含时间戳, 同一阻塞得到同一句话 —— 便于幂等比对) */
+export function buildAdjustmentDirective(b) {
+    return `调整指令 (${b.kind}): ${b.note} —— 这是第一档处置 (先给一次调整, 不是立刻换人); `
+        + `请就当前目标给出一次可核验的进展或明确的阻塞回报, 报告须带逐条证据。`;
+}
+/** 催报原文 (纯函数) */
+export function buildReportRequestWhat(b) {
+    return `请补齐报告 (${b.kind}): ${b.note}${b.dependency ? ` [依赖=${b.dependency}]` : ''} —— `
+        + `漂亮但没有逐条证据的回报不接受为完成。`;
+}
+// ============================================================================
+// 执行 (唯一入口)
+// ============================================================================
+function uniq(items) {
+    return [...new Set(items)];
+}
+function errText(e) {
+    return String(e?.message || e).slice(0, 200);
+}
+/**
+ * 执行一次阻塞处置。
+ *
+ * 顺序**固定** (便于复现): 逐条 (按输入顺序, 同 blockId 只做一次) →
+ *   `planBlockHandling` 得动作 → `mayExecuteAction` 判权 → 端口存在性 → 真调用。
+ *
+ * 每一步失败都**显式**落进结果 (`refused` / `failed` + `needsHuman`), 绝不静默 ——
+ * 这是本模块存在的全部理由 (P5 缺口 4)。
+ */
+export async function executeBlockHandling(input) {
+    const out = {
+        executed: [], refused: [], deferred: [], failed: [], needsHuman: [], silentRisk: false, attempts: [],
+    };
+    if (!Array.isArray(input.blocks)) {
+        // 调用方 bug 不许静默: 说清"阻塞清单不是数组", 直接交人
+        out.needsHuman.push({
+            blockId: '(input)', workId: null, action: 'needs_human',
+            reason: '阻塞清单不是数组 (调用方 bug) —— 无法巡检, 不许当成"没有阻塞"',
+        });
+        out.silentRisk = true;
+        return out;
+    }
+    const unresolved = input.blocks.filter((b) => b && b.resolvedAt === null);
+    const seenBlocks = new Set();
+    const now = input.now;
+    const authority = input.authority;
+    for (const b of unresolved) {
+        if (seenBlocks.has(b.blockId))
+            continue;
+        seenBlocks.add(b.blockId);
+        if (input.onlyActions && !input.onlyActions.includes(planBlockHandling(b)))
+            continue;
+        const action = planBlockHandling(b);
+        const attempt = {
+            blockId: b.blockId, workId: b.workId ?? null, childAgentId: b.childAgentId ?? null,
+            kind: b.kind, action, outcome: 'refused', called: [], detail: '', recorded: false,
+        };
+        const base = {
+            goalId: input.goalId, workId: b.workId ?? null, childAgentId: b.childAgentId ?? null,
+            blockId: b.blockId, kind: b.kind, now, reason: b.note,
+        };
+        // 1. 权限 (越权一律不调端口)
+        const verdict = mayExecuteAction(action, b.kind, authority);
+        if (!verdict.allowed) {
+            attempt.outcome = 'refused';
+            attempt.detail = `拒绝执行 (未调任何执行器): ${verdict.reason}`;
+            out.refused.push(attempt);
+            out.attempts.push(attempt);
+            out.needsHuman.push({ blockId: b.blockId, workId: b.workId ?? null, action, reason: attempt.detail });
+            continue;
+        }
+        // 2. 端口存在性 (缺端口 = 做不了 = 交人, 不许静默跳过)
+        const portName = PORT_FOR_ACTION[action];
+        const port = portName ? input.ports[portName] : null;
+        if (portName && typeof port !== 'function') {
+            attempt.outcome = 'refused';
+            attempt.detail = `没有注入执行「${action}」的执行器 (端口 ${portName} 缺失) → 处置无法落地, 交人`;
+            out.refused.push(attempt);
+            out.attempts.push(attempt);
+            out.needsHuman.push({ blockId: b.blockId, workId: b.workId ?? null, action, reason: attempt.detail });
+            continue;
+        }
+        // 3. 真调用 (端口抛错 = failed + 原因原文, 不吞)
+        try {
+            await dispatchAction(action, attempt, b, base, input.ports, authority);
+        }
+        catch (e) {
+            attempt.outcome = 'failed';
+            attempt.detail = `执行器抛错: ${errText(e)}`;
+            out.failed.push(attempt);
+            out.attempts.push(attempt);
+            out.needsHuman.push({ blockId: b.blockId, workId: b.workId ?? null, action, reason: attempt.detail });
+            continue;
+        }
+        if (attempt.outcome === 'executed')
+            out.executed.push(attempt);
+        else if (attempt.outcome === 'deferred')
+            out.deferred.push(attempt);
+        else
+            out.refused.push(attempt);
+        out.attempts.push(attempt);
+        // 4. 显式交人: 动作本身就是转人工, 或端口如实回"没做成"
+        if (action === 'needs_human') {
+            out.needsHuman.push({
+                blockId: b.blockId, workId: b.workId ?? null, action,
+                reason: `${b.note} → 需要人决定 (加预算 / 改权限 / 换目标都属于人)`,
+            });
+        }
+        else if (attempt.outcome === 'refused') {
+            out.needsHuman.push({ blockId: b.blockId, workId: b.workId ?? null, action, reason: attempt.detail });
+        }
+        // 5. 记事实 (可选端口; 不注入会在 attempt.recorded 里如实标 false)
+        if (input.ports.record) {
+            try {
+                await input.ports.record({
+                    goalId: input.goalId, blockId: b.blockId, workId: b.workId ?? null,
+                    action, outcome: attempt.outcome, now, detail: attempt.detail,
+                });
+                attempt.recorded = true;
+            }
+            catch (e) {
+                attempt.recorded = false;
+                attempt.detail = `${attempt.detail} [记事实失败: ${errText(e)}]`;
+            }
+        }
+    }
+    // 自检: 有未解决阻塞却什么都没落地、也没交人 ⇒ 静默 (维护者必须知道)。
+    // 「继续等」(`deferred`) 算**落地过** —— 它是规则表里合法的无副作用处置, 不该被误报成需要人。
+    if (unresolved.length > 0 && out.executed.length === 0 && out.deferred.length === 0 && out.needsHuman.length === 0) {
+        out.silentRisk = true;
+        out.needsHuman.push({
+            blockId: '(self-check)', workId: null, action: 'needs_human',
+            reason: `有 ${unresolved.length} 条未解决阻塞, 但一条处置都没落地、也没有交人理由 —— 静默, 交人`,
+        });
+    }
+    return out;
+}
+/** 按动作把调用派到对应端口, 并把端口返回如实翻成 attempt */
+async function dispatchAction(action, attempt, b, base, ports, authority) {
+    switch (action) {
+        case 'takeover': {
+            const lease = await ports.claimLease(base);
+            attempt.called.push('claimLease');
+            if (lease === true) {
+                attempt.outcome = 'executed';
+                attempt.detail = `真抢到执行权 (此前 leaseHeld=${authority.leaseHeld}) → 接管 ${base.workId ?? '-'}`;
+            }
+            else {
+                attempt.outcome = 'refused';
+                attempt.detail = `抢执行权没成功 (claimLease=false) → 不接管, 交人`;
+            }
+            return;
+        }
+        case 'replace_child': {
+            const res = await ports.replaceChild(base);
+            attempt.called.push('replaceChild');
+            if (res && res.replaced) {
+                attempt.outcome = 'executed';
+                attempt.detail = `真换人: 停掉 ${base.workId ?? '-'}, 新工作=${res.newWorkId ?? '(未重派合同)'}`;
+            }
+            else {
+                attempt.outcome = 'refused';
+                attempt.detail = `换人没做成 (replaceChild.replaced=false) → 交人`;
+            }
+            return;
+        }
+        case 'send_adjustment': {
+            const ok = await ports.sendAdjustment({ ...base, directive: buildAdjustmentDirective(b) });
+            attempt.called.push('sendAdjustment');
+            attempt.outcome = ok === true ? 'executed' : 'refused';
+            attempt.detail = ok === true ? `真下发调整指令给 ${base.childAgentId ?? '(子 Agent)'}` : '调整指令下发失败 → 交人';
+            return;
+        }
+        case 'request_report': {
+            const ok = await ports.requestReport({ ...base, what: buildReportRequestWhat(b) });
+            attempt.called.push('requestReport');
+            attempt.outcome = ok === true ? 'executed' : 'refused';
+            attempt.detail = ok === true ? `真要求补齐报告 (${base.workId ?? '-'})` : '催报下发失败 → 交人';
+            return;
+        }
+        case 'change_plan': {
+            const ok = await ports.changePlan({ ...base, why: base.reason });
+            attempt.called.push('changePlan');
+            attempt.outcome = ok === true ? 'executed' : 'refused';
+            attempt.detail = ok === true ? '真改了计划 (父侧)' : '改计划没做成 → 交人';
+            return;
+        }
+        case 'escalate_parent':
+        case 'needs_human': {
+            const to = action === 'needs_human' ? 'human' : 'parent';
+            const ok = await ports.escalate({ ...base, to, detail: base.reason });
+            attempt.called.push('escalate');
+            attempt.outcome = ok === true ? 'executed' : 'refused';
+            attempt.detail = ok === true
+                ? `真上报给${to === 'human' ? '人' : '父'} (${base.kind})`
+                : `上报给${to === 'human' ? '人' : '父'}没做成 → 仍在 needsHuman 里留痕`;
+            return;
+        }
+        case 'wait_dependency': {
+            attempt.outcome = 'deferred';
+            attempt.detail = `继续等 (无副作用): ${base.reason}`;
+            return;
+        }
+        default: {
+            // 动作集是闭集; 走到这里说明 types.ts 加了新动作而这里没跟上 —— 不静默
+            attempt.outcome = 'refused';
+            attempt.detail = `未知动作「${String(action)}」: 执行器没跟上动作集, 交人`;
+            return;
+        }
+    }
+}
+/** 把结果压成一行摘要 (接线层 log / 界面用; 不含内部词) */
+export function summarizeBlockExecution(out) {
+    return [
+        `已落地 ${out.executed.length}`,
+        `被拒 ${out.refused.length}`,
+        `等依赖 ${out.deferred.length}`,
+        `失败 ${out.failed.length}`,
+        `需人 ${out.needsHuman.length}`,
+        `去重后阻塞 ${out.attempts.length}`,
+    ].join(' · ');
+}
+/** 动作集是否被本执行器完全覆盖 (types.ts 加了动作而这里没跟上 → false, 门来钉) */
+export function coveredActions() {
+    return uniq(Object.keys(PORT_FOR_ACTION));
+}