@bolloon/bolloon-agent 0.5.4 → 0.6.0

package/dist/agents/agent-identity-store.js

@@ -162,10 +162,46 @@ export class AgentIdentityStore {
         }));
     }
 }
-let _store = null;
-/** 单例 (CLI / server 共用; 测试可 new AgentIdentityStore(tmpHome)) */
+// 2026-10-01 (数据事故修复): 单例**按 home 分桶**, 不再把 HOME 绑死在一个实例上。
+//
+// 事故经过 (真事, 用户丢了 4 个智能体): 测试 `channel-not-found.test.ts` 设了隔离 HOME
+// (process.env.HOME = TMP_HOME), 但 vitest 复用 worker —— 同 worker 里**别的测试先**碰过
+// getIdentityStore() ⇒ 单例已按**真实** HOME 构造 ⇒ 该测试的夹具 channel
+// ("real test msg"/"test-agent") 直接写进真实的 ~/.bolloon/sessions/channels.json,
+// 而且是**整表覆盖** ⇒ 用户 4 个 channel 只剩 1 条。
+// 根因就是这里: `new AgentIdentityStore()` 的默认参数 `home = HOME()` 只在**构造那一刻**取值,
+// 之后 process.env.HOME 再怎么变都影响不到它。
+const _storesByHome = new Map();
+/** 单例 (CLI / server 共用, **按当前 HOME 分桶**; 改过 HOME 的测试会自然拿到自己的实例) */
 export function getIdentityStore() {
-    if (!_store)
-        _store = new AgentIdentityStore();
-    return _store;
+    const home = HOME();
+    let st = _storesByHome.get(home);
+    if (!st) {
+        st = new AgentIdentityStore(home);
+        _storesByHome.set(home, st);
+    }
+    return st;
+}
+/** 仅供测试: 丢弃所有缓存实例 (改完 HOME 后强制重建) */
+export function resetIdentityStoreSingletons() {
+    _storesByHome.clear();
+}
+/**
+ * 测试期写盘硬保护 (2026-10-01, 数据事故后的第二道闸)。
+ *
+ * 事故: 测试夹具把用户的真实 channels.json 整表覆盖 (4 个智能体只剩 1 条)。
+ * 第一道修的是根因 (单例按 HOME 分桶); 这道是**兜底**: 只要进程带着测试标志,
+ * 就**只允许**写临时目录下的数据 —— 真实 HOME (~/.bolloon) 一律拒绝并抛错。
+ * 宁可让测试红, 也不能再动用户的数据。
+ */
+export function assertTestWriteTarget(home, what = '数据') {
+    const isTest = !!process.env.VITEST || process.env.NODE_ENV === 'test';
+    if (!isTest)
+        return;
+    const h = String(home || '').replace(/\/+$/, '');
+    const tmpLike = h.startsWith('/tmp/') || h.startsWith('/var/folders/') || h.startsWith('/private/var/folders/') || /bolloon[-_].*test/i.test(h);
+    if (!tmpLike) {
+        throw new Error(`[test-guard] 测试进程拒绝写非临时目录的${what}: ${h} —— ` +
+            `真实数据目录只能在正常 CLI/服务进程中写 (这道闸就是为防上次"夹具覆盖真实 channels.json"的事故)`);
+    }
 }

package/dist/agents/background-notices.js

@@ -0,0 +1,124 @@
+/**
+ * 后台委派的结果回灌 (2026-10-01, 用户: 「开展子智能体后，bolloon 没有回归」+「还是卡住了，学 hermes」)。
+ *
+ * 学的是"**起完就走, 结果自己回来**"这个形态:
+ *   起委派 ⇒ 立刻返回(带 session id ✓) ⇒ 父智能体继续干别的 ✓ ⇒ 它跑完后, 结果作为**一行提示**注入下一轮 ✓。
+ * 判据性质: 只对"我起的后台委派"发提示(命令里带标记 ✓) · **同一条只提示一次**(落盘记号 ✓) · 未跑完/已提示过 ⇒ 不提 ✓。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { listSessions } from './process-runner.js';
+/** 起后台委派时在命令前加的环境标记 ⇒ 便于识别"这是我起的委派" */
+export const DELEGATE_ENV_MARK = 'BOLLOON_DELEGATE=1';
+export function noticesPath(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'delegate-notices.json');
+}
+function loadNoticed(home) {
+    try {
+        const raw = fs.readFileSync(noticesPath(home), 'utf-8');
+        const obj = JSON.parse(raw);
+        return obj && typeof obj === 'object' ? obj : {};
+    }
+    catch {
+        return {};
+    }
+}
+function saveNoticed(map, home) {
+    try {
+        const p = noticesPath(home);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(map), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort: 提示记不下来最多重复一次, 不该打断主流程 */
+    }
+}
+/** 收集"已完成、且还没提示过"的后台委派, 每个一条中文提示; 同时落盘记号(只提示一次 ✓) */
+export function collectDelegateNotices(home, 
+/** 便于门注入假 session(默认读真实的 ✓) */
+injected) {
+    let sessions = [];
+    if (injected)
+        sessions = injected;
+    else {
+        try {
+            sessions = listSessions();
+        }
+        catch {
+            return [];
+        }
+    }
+    const noticed = loadNoticed(home);
+    const lines = [];
+    let changed = false;
+    for (const s of sessions) {
+        if (!String(s.cmd || '').includes(DELEGATE_ENV_MARK))
+            continue; // 只认我起的委派
+        if (s.status === 'running')
+            continue; // 还没跑完 ⇒ 不提
+        if (noticed[s.id])
+            continue; // 提过 ⇒ 不提
+        const how = s.status === 'exited' ? `退出码 ${s.exitCode ?? 0}` : `状态 ${s.status}`;
+        lines.push(`[后台委派完成] session ${s.id} · ${how} —— 结果用 \`process poll ${s.id}\` 取; 若已达成目标就继续下一步, 别重发同样的委派。`);
+        noticed[s.id] = Date.now();
+        changed = true;
+    }
+    if (changed)
+        saveNoticed(noticed, home);
+    return lines;
+}
+/** 拼成一段(没有就返回空串 ✓) */
+export function renderDelegateNotices(home) {
+    const lines = collectDelegateNotices(home);
+    return lines.length ? lines.join('\n') : '';
+}
+export function noticesQueuePath(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'notices-queue.jsonl');
+}
+/** 投递一条(后台线程/异步回调都能安全调 ✓; 失败只吞不抛 ✓) */
+export function pushNotice(kind, text, home = os.homedir()) {
+    try {
+        const p = noticesQueuePath(home);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, JSON.stringify({ kind, text, at: Date.now() }) + '\n');
+    }
+    catch { /* 丢一条提示不该打断主流程 */ }
+}
+/** 空闲时排空(读走即清空 ✓): 返回"上一轮之后攒下的"通知, 供本轮开头一次性交代 ✓ */
+export function drainNotices(home = os.homedir()) {
+    const p = noticesQueuePath(home);
+    let raw = '';
+    try {
+        raw = fs.readFileSync(p, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (o && typeof o.text === 'string' && (o.kind === 'delegate' || o.kind === 'review'))
+                out.push(o);
+        }
+        catch { /* 坏行跳过 */ }
+    }
+    try {
+        fs.writeFileSync(p, '', { mode: 0o600 });
+    }
+    catch { /* 清空失败 ⇒ 下轮可能重复一次, 可接受 */ }
+    return out;
+}
+/** 拼成一段"任务源块"(自包含 ✓: 说明是什么 + 现在该做什么 + 别重复) */
+export function renderNoticeBlock(home = os.homedir()) {
+    const items = drainNotices(home);
+    if (!items.length)
+        return '';
+    const lines = items.map((n) => n.kind === 'review'
+        ? `- [复盘产出] ${n.text}\n  ⇒ 若它意味着要**改代码/改技能**, 现在就把这一步做掉(别只记下来); 若只是知识, 说明它已入库即可。`
+        : `- [后台任务完成] ${n.text}`);
+    return `【后台回流 · 这是新一轮】上一轮之后攒下 ${items.length} 条, 请在本轮一并处理:\n${lines.join('\n')}`;
+}

package/dist/agents/channel-identity.js

@@ -0,0 +1,54 @@
+/**
+ * 每个 channel 的**自己的**身份 (2026-10-01)。
+ *
+ * 用户实测: 两个不同 channel (agent_18cece3f / test-agent) 都答「我叫小龙」, 且 get_identity 返回
+ *   `DID: `(空) —— 症状是"读身份的还有问题"。
+ * 根因: index.ts 组装 identityDoc 时, 只有 channel 记录**同时**有 did 和 publicKey 才用它,
+ *   否则落到 `agentIdentity`(进程级**共享**的一个) ⇒ 多个 channel 共用一个身份 ✗;
+ *   而 channel 记录里还可能存着假 DID (`did:local:…`) ✗, 或干脆没 did (测试夹具建的) ✗。
+ * 规矩: 身份归属**以 channel 的 agentId 为准** —— 每个 agent 用自己的真 did:key (落盘密钥),
+ *   名字优先用该 agent 自己的 persona.json, 其次渠道名 (渠道名天然各不相同)。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+/** 假的/垃圾 DID: 不该被当成身份用 (老代码自造过 did:local: / did:pi:) */
+export function isUsableDid(did) {
+    const s = String(did ?? '').trim();
+    if (!s)
+        return false;
+    return !/^did:(local|pi):/i.test(s);
+}
+/** channel 记录里的身份够不够用 (did 真 + 有公钥) */
+export function channelIdentityUsable(ch) {
+    return !!ch && isUsableDid(ch.did) && !!ch.publicKey;
+}
+/** 该 agent 自己的 persona.json 里的名字 (没有就 undefined) */
+export function agentPersonaName(agentId, home = os.homedir()) {
+    const id = String(agentId || '').trim();
+    if (!id)
+        return undefined;
+    const safe = id.replace(/[^a-zA-Z0-9._-]/g, '_');
+    try {
+        const p = path.join(home, '.bolloon', 'persona', safe, 'persona.json');
+        const j = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        const n = String(j?.name ?? '').trim();
+        return n || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * channel 应该显示/使用什么名字。
+ * 顺序: 该 agent 的 persona.json → channel 记录里的 persona.name → channel 名 → agentId
+ * **绝不**回落到"某个全局身份的名字" —— 那正是"两个 channel 一个名"的来源。
+ */
+export function nameForChannel(ch, agentId, home = os.homedir()) {
+    const id = String(agentId || ch?.agentId || '').trim();
+    return ((id ? agentPersonaName(id, home) : undefined) ||
+        String(ch?.persona?.name ?? '').trim() ||
+        String(ch?.name ?? '').trim() ||
+        id ||
+        'agent');
+}

package/dist/agents/code-write-gate.js

@@ -0,0 +1,47 @@
+/**
+ * 代码写改的"类型门" (2026-10-01, 回应「tsc 抓错这个功能 bolloon 有吗」)。
+ *
+ * 查到的事实: bolloon **早就**有类型检查, 而且有三层 —— pre-commit 的 `tsc-check`(lefthook) ·
+ *   `build:main = tsc && …` · 以及**给智能体的工具** `tsc_check`(pi-sdk-tools.ts:1450, 60s timeout)。
+ * 但**循环里没有"编辑后自动检查"** ✗ ⇒ `tsc_check` 是个"模型想得起来才会调"的工具 ✓
+ *   ⇒ 和 #4(写操作读回)同一个病: **规矩写了, 没人执行** ✓。
+ * 这条把它变成机制: 本回合**改过 .ts/.tsx** ⇒ 回合收尾**自动**跑一次类型检查(一轮只跑一次, 不管改了 1 个还是 8 个文件 ✓),
+ *   结果以一行状态进对话流 —— "类型过没过"不再依赖模型自觉 ✓。
+ * 纪律: 每个回合最多一次(tsc 是秒级开销, 但也不该每改一个文件就跑) · 只对 TS 源码生效 · 失败绝不影响回合结果 ✓。
+ */
+/** 写/改类工具里, 会"产出源码"的那些 */
+export const CODE_WRITE_TOOLS = new Set(['write_file', 'edit_file', 'patch', 'move_file', 'copy_file']);
+export function isTypeScriptFile(p) {
+    return /\.(ts|tsx|mts|cts)$/i.test(String(p || '').trim());
+}
+/**
+ * 这次写操作是否**产生了/改动了 TS 源码** ⇒ 返回那个路径(否则 null)。
+ * 只看路径, 不看内容(便宜且够用 ✓)。
+ */
+export function codeWriteTarget(toolName, args) {
+    if (!CODE_WRITE_TOOLS.has(String(toolName)))
+        return null;
+    const rel = String(args?.path ?? args?.to ?? args?.file ?? '').trim();
+    if (!rel)
+        return null;
+    return isTypeScriptFile(rel) ? rel : null;
+}
+/**
+ * 回合收尾要不要跑类型检查: 改过 TS 且本回合还没跑过 ⇒ 跑。
+ * 抽成纯函数是为了**可测**: "一轮只跑一次"这条最容易写错(写成每个文件跑一次就把时间烧光 ✓)。
+ */
+export function decideTypecheck(touched, ranThisTurn) {
+    return !ranThisTurn && touched.length > 0;
+}
+/** 类型检查结果 ⇒ **一行**状态 (给对话流看; 错误多时只给前几条 + 总数) */
+export function formatTypecheckResult(ok, output, maxLines = 6) {
+    const body = String(output || '').split('\n').map((l) => l.trim()).filter(Boolean);
+    if (ok)
+        return '✅ 类型检查通过 (tsc --noEmit, 本回合改过 TS 后自动跑)';
+    const errs = body.filter((l) => /error TS\d+/.test(l));
+    const head = (errs.length ? errs : body).slice(0, maxLines);
+    const more = (errs.length || body.length) - head.length;
+    return `❌ 类型检查没过: ${errs.length || '?'} 个错误\n` + head.map((l) => `   ${l.slice(0, 160)}`).join('\n')
+        + (more > 0 ? `\n   …还有 ${more} 条` : '')
+        + '\n   ⇒ **先修类型再继续**(别在同一轮里叠加更多改动)';
+}

package/dist/agents/deny-pipeline.js

@@ -88,8 +88,17 @@ export class DenyPipeline {
      *   实测日志 "write_file 被权限拦了" → LLM 只能绕道, 任务无法推进.
      */
     static permissionChecker() {
+        /**
+         * 2026-10-01: **default 模式下只禁 `git_push`**(远端/不可逆那一个);
+         *   `git_commit` / `git_branch` 放行 —— 它们本来是"指定安全路径"(有护栏、只提交已暂存的 ✓)。
+         * 为什么改: 用户现场实录里, `git_commit` 被权限拦了 ⇒ 智能体**绕道裸跑 shell**
+         *   (`shell_exec` + **`git add -A`** ✗ —— 正是项目红线禁止的那条, 会卷走别的智能体在写的文件 ✗✗);
+         *   也就是说"拦住它"并没有更安全, 只是把它推去了**更危险**的路 ✗。
+         *   (本文件上面那段注释早就记过同类教训: "被权限拦了 → LLM 只能绕道, 任务无法推进" ✓。)
+         * acceptEdits 模式仍按原样: shell/git 一律受限(那是**显式**收紧, 不是默认 ✗)。
+         */
         const DEFAULT_DENY_TOOLS = new Set([
-            'git_commit', 'git_push', 'git_branch',
+            'git_push',
         ]);
         return (ctx) => {
             if (ctx.permissionMode === 'bypassPermissions') {
@@ -106,7 +115,7 @@ export class DenyPipeline {
                 }
                 return { denied: false, reason: '', source: 'permission' };
             }
-            // default: 危险工具全禁
+            // default: 只禁不可逆的远端操作(见上)
             if (DEFAULT_DENY_TOOLS.has(ctx.toolName)) {
                 return {
                     denied: true,

package/dist/agents/egress-sanitize.js

@@ -0,0 +1,69 @@
+/**
+ * 出口净化 (2026-10-01 落实③)。
+ *
+ * 为什么: 记忆/身份文档/历史片段这些"文本资产"最终都会**拼进给模型的提示**。秘密一旦混进去, 就等于
+ *   通过 API 送出去了 —— 而且会**反复**送(每一轮)。纪律上我们早就规定"凭证只落 0600 文件、绝不回显",
+ *   但那靠的是调用方自觉;出口必须是一道**闸**: 所有要进模型的文本都过同一个函数。
+ * 设计对齐 (只搬约束): **一个 choke point** · 先脱敏再截断 · 中间省略保留头尾 · 短文本原样返回(零成本)。
+ * 取舍: 宁可误伤(把长得像密钥的东西打码), 不可漏放 —— 误伤只是少几个字符, 漏放是事故。
+ */
+/** 常见凭证形态 (按"长得像"判, 不依赖具体厂商) */
+const SECRET_PATTERNS = [
+    // 私钥 hex: 0x + 64 hex, 或裸 64 hex
+    { re: /\b0x[0-9a-fA-F]{64}\b/g, tag: '[REDACTED:hex-key]' },
+    { re: /\b[0-9a-fA-F]{64}\b/g, tag: '[REDACTED:hex64]' },
+    // 助记词: 12+ 个连续小写词 (空格分隔)
+    { re: /\b(?:[a-z]{3,8}\s+){11,23}[a-z]{3,8}\b/g, tag: '[REDACTED:mnemonic]' },
+    // 常见 token 前缀
+    { re: /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/g, tag: '[REDACTED:api-key]' },
+    { re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g, tag: '[REDACTED:github-token]' },
+    { re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, tag: '[REDACTED:slack-token]' },
+    { re: /\bAKIA[0-9A-Z]{16}\b/g, tag: '[REDACTED:aws-key]' },
+    { re: /\bnpm_[A-Za-z0-9]{30,}\b/g, tag: '[REDACTED:npm-token]' },
+    // JWT
+    { re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}\b/g, tag: '[REDACTED:jwt]' },
+    // Authorization: Bearer xxx
+    { re: /\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/gi, tag: 'Bearer [REDACTED]' },
+    // URL 里的用户名:密码
+    { re: /(https?:\/\/)[^\s/@:]+:[^\s/@]+@/gi, tag: '$1[REDACTED]@' },
+    // key: value 形态的敏感字段 (私钥/助记词/密钥/token/password)
+    { re: /((?:privateKey|private_key|mnemonic|seedPhrase|seed_phrase|secret|apiKey|api_key|token|password|passwd|passphrase)"?\s*[:=]\s*)"[^"]{8,}"/gi, tag: '$1"[REDACTED]"' },
+    { re: /((?:privateKey|private_key|mnemonic|seedPhrase|seed_phrase|secret|apiKey|api_key|token|password|passwd|passphrase)"?\s*[:=]\s*)'[^']{8,}'/gi, tag: "$1'[REDACTED]'" },
+    { re: /((?:privateKey|private_key|mnemonic|seedPhrase|seed_phrase|secret|apiKey|api_key|token|password|passwd|passphrase)"?\s*[:=]\s*)[^\s,;"'}\]]{8,}/gi, tag: '$1[REDACTED]' },
+];
+/** 把长得像凭证的东西打码 (纯函数, 幂等 — 已打码的文本再跑不变) */
+export function redactSecrets(text) {
+    let out = String(text ?? '');
+    for (const { re, tag } of SECRET_PATTERNS)
+        out = out.replace(re, tag);
+    return out;
+}
+/** 中间省略: 长度 <= maxChars 原样返回; 否则保留头 head、尾 tail, 中间插省略标记 */
+export function elideMiddle(text, maxChars, headChars = 0, tailChars = 0) {
+    const s = String(text ?? '');
+    const max = Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : 0;
+    if (!max || s.length <= max)
+        return s;
+    // 头/尾各留一部分, **给省略标记留出余量** —— 上一版 head+tail 正好等于 max ⇒ 落到"直接截断"分支,
+    // 省略标记根本不出现(门抓到: 输出里没有 "省略" ✗)。现在按 60%/25% 留, 剩下给标记。
+    const head = headChars > 0 ? Math.min(headChars, Math.floor(max * 0.8)) : Math.floor(max * 0.6);
+    const tail = tailChars > 0 ? Math.min(tailChars, Math.floor(max * 0.3)) : Math.floor(max * 0.25);
+    const marker = (n) => `\n…[省略 ${n} 字符]…\n`;
+    if (head <= 0 && tail <= 0)
+        return s.slice(0, max);
+    const omitted = Math.max(0, s.length - head - tail);
+    const out = `${s.slice(0, head)}${marker(omitted)}${tail > 0 ? s.slice(-tail) : ''}`;
+    return out.length <= max + marker(omitted).length ? out : out.slice(0, max + marker(omitted).length);
+}
+/**
+ * **唯一出口**: 任何要拼进模型的文本都过这里。
+ * 顺序很重要 —— 先脱敏再截断: 否则截断可能把 key 的中间切掉, 让模式匹配失效(半截 key 照样是泄漏)。
+ */
+export function sanitizeForLlm(text, maxChars = 0) {
+    const redacted = redactSecrets(text);
+    return maxChars > 0 ? elideMiddle(redacted, maxChars) : redacted;
+}
+/** 一行内是否含可疑凭证 (给调用方做审计/告警用, 不改变文本) */
+export function hasSuspiciousSecret(text) {
+    return redactSecrets(text) !== String(text ?? '');
+}

package/dist/agents/error-classifier.js

@@ -12,12 +12,18 @@ const ERROR_SIGNATURES = [
     { pattern: /PreToolUse 拒绝|Harness.*拒绝|permission|not allowed|denied/i, cls: 'permission_denied', label: '权限拒绝' },
     { pattern: /ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|network|connect.*fail|fetch.*fail/i, cls: 'network_error', label: '网络错误' },
     { pattern: /timeout|timed out/i, cls: 'timeout', label: '执行超时' },
-    { pattern: /ENOENT|not found|no such file|does not exist|invalid path|bad argument|ERR_INVALID/i, cls: 'bad_input', label: '参数错误' },
+    // 2026-10-01: ENOENT 单独一条 —— 原先和 bad argument 挤在一起 ⇒ 路径不存在被报成"参数错误" ✗
+    //   (用户实测: list_files '~/.bolloon' ⇒ ENOENT, 却被标成"参数错误", 真原因被标签盖住)
+    { pattern: /ENOENT|no such file|does not exist|not exist/i, cls: 'bad_input', label: '路径/文件不存在' },
+    { pattern: /invalid path|bad argument|ERR_INVALID|参数/i, cls: 'bad_input', label: '参数错误' },
+    // 2026-10-01: **策略拒绝**必须单列且排在前面 —— 否则长文本里的无关关键词会把它误判成鉴权类 ⇒ 熔断 ✗
+    //   (现场: 「路径被护栏拒…」被当成"鉴权类错误不重试" ⇒ 停在 needs_human ✗)
+    { pattern: /路径被护栏拒|不在白名单|被护栏拒|denied by policy/i, cls: 'policy', label: '策略拒绝(护栏)' },
     { pattern: /401|403|quota|rate limit|API key|unauthorized|authentication/i, cls: 'api_error', label: 'API 认证错误' },
 ];
 export function classifyError(errorMsg) {
     if (!errorMsg)
-        return { cls: 'unknown', label: '未知错误', severity: 'medium', recoverable: true };
+        return { cls: 'unknown', label: '', severity: 'medium', recoverable: true };
     for (const sig of ERROR_SIGNATURES) {
         if (sig.pattern.test(errorMsg)) {
             const severity = sig.cls === 'api_error' ? 'high'
@@ -30,21 +36,44 @@ export function classifyError(errorMsg) {
             return { cls: sig.cls, label: sig.label, severity, recoverable };
         }
     }
-    return { cls: 'unknown', label: '未知错误', severity: 'medium', recoverable: true };
+    return { cls: 'unknown', label: '', severity: 'medium', recoverable: true };
 }
 export function buildObservation(tool, args, result) {
     const obs = { tool, args, success: result.success, summary: '' };
     if (result.success) {
         const output = result.output || '(无输出)';
         obs.output = output;
-        obs.summary = `✅ ${tool} 成功 (${output.length}B)`;
+        // 2026-10-01 (用户: 「完整看一下这个反思模式，为啥一直出错？」):
+        //   原来只报 **字节数** ✗(`✅ terminal 成功 (1234B)`) ⇒ 模型不知道**发生了什么**, 只能猜 ⇒ 猜错 ✓
+        //   现在附一段**内容预览**(压平换行 ✓ 头部 160 字符 ✓) ⇒ 观察里就有事实 ✓。
+        const preview = output.replace(/\s+/g, ' ').trim().slice(0, 160);
+        obs.summary = `✅ ${tool} 成功 (${output.length}B)${preview ? `: ${preview}` : ''}`;
     }
     else {
         const errMsg = result.error || '未知失败';
         const cls = classifyError(errMsg);
         obs.errorClass = cls.cls;
         obs.errorLabel = cls.label;
-        obs.summary = `❌ ${tool} 失败: ${cls.label} — ${errMsg.slice(0, 120)}`;
+        // ② 2026-10-01: 退出码非零时**先不写"失败"** ✓(钩子/子命令常以非零退出而动作已生效);
+        // ③ 并附**输出尾部** —— 原来只截错误文本前 120 字符 ✗, 而 lefthook 那类"到底干了什么"恰在**尾部** ⇒ 必然误判 ✗
+        const __exit0 = Number((/exit\s+(\d+)/i.exec(result.error || '') || [])[1]);
+        const __tail = String(result.output || '').replace(/\s+/g, ' ').trim().slice(-200);
+        const __head = __exit0 && Number.isFinite(__exit0) && __exit0 !== 0 && tool === 'terminal'
+            ? `⚠️ ${tool} 退出码 ${__exit0}(结果待核, 不等于失败)`
+            : `❌ ${tool} 失败: ${cls.label}`;
+        obs.summary = `${__head} — ${errMsg.slice(0, 160)}${__tail ? ` · 输出尾部: ${__tail}` : ''}`;
+        // 2026-10-01 (用户: 「反思还是有错误」—— 现场实测: git 提交**已经成功**, 但那一行却写着
+        //   `Reflection: ❌ terminal 失败: — exit 1` ✗, 把 lefthook 的钩子退出码当成了任务失败 ✗):
+        //   **退出码非零 ≠ 任务失败** ✓ —— 用命令核一次事实再下结论, 别直接写"失败"。
+        const __exit = Number((/exit\s+(\d+)/i.exec(errMsg) || [])[1]);
+        if (tool === 'terminal' && Number.isFinite(__exit) && __exit !== 0) {
+            obs.summary = `${obs.summary} · ⚠️ 退出码 ${__exit} **不等于任务失败**(钩子/子命令常以非零退出而动作已生效)`
+                + ` —— 先核事实(git status / git log / read_file 看结果)再下结论, 别写成"失败"`;
+        }
+        // 2026-10-01 (优化 #6): 顺手给出"下一步该干什么" —— 光有标签模型会原地重试同一条命令
+        const __advice = suggestNextAction(`${cls.label} ${errMsg}`);
+        if (__advice)
+            obs.summary = `${obs.summary} · ${__advice}`;
     }
     return obs;
 }
@@ -81,10 +110,24 @@ const ERROR_TO_STRATEGIES = {
         { action: 'retry', reason: '错误类型不确定', detail: '换个方式或参数再试一次' },
         { action: 'change_tool', reason: '原方法不可行', detail: '尝试用其他工具组合达成目标' },
     ],
+    // 2026-10-01: 护栏拒绝 ⇒ **别无脑重试同一条路径** ✓: 先改到允许的根下, 或问用户要目标位置 ✓
+    policy: [
+        { action: 'change_params', reason: '策略拒绝(护栏)', detail: '别原样重试: ① 换到白名单内的根(docs/** · src/web/** · *.md · ~/.bolloon/**); ② 或先问用户"这个文件该放哪"; ③ 若是工具/命令不在白名单, 换等价的白名单内工具' },
+        { action: 'change_tool', reason: '换等价工具', detail: '写文件用 write_file 到允许路径; 命令换白名单内的等价命令' },
+    ],
 };
 export function buildReflection(toolName, errorMsg, errorCount, sameToolFailCount) {
     if (!errorMsg)
         return ERROR_TO_STRATEGIES.unknown.slice(0, 1);
+    // ④ 2026-10-01: 退出码非零 ⇒ **先核事实**, 而不是按规则表给重试 ✗
+    //   (实测: git 提交已生效却因钩子退出码非零被判失败 ⇒ 模型又去重试/绕道, 越走越偏 ✗)
+    const __exitCode = Number((/exit\s+(\d+)/i.exec(errorMsg) || [])[1]);
+    if (Number.isFinite(__exitCode) && __exitCode !== 0) {
+        return [
+            { action: 'change_params', reason: `退出码 ${__exitCode} —— 结果待核(不等于失败)`, detail: '先用 git status / git log / read_file 核事实, 确认到底成没成, 再决定下一步; 别直接当失败重试' },
+            { action: 'change_tool', reason: '换法再试', detail: '若确未成功: 换参数/换工具/拆小步再执行' },
+        ];
+    }
     const cls = classifyError(errorMsg);
     // 阶梯升档: 根据连续失败次数选择更激进的策略
     if (sameToolFailCount >= 3) {
@@ -116,3 +159,22 @@ export function formatObservationWithReflection(obs, reflection) {
     }
     return lines.join('\n');
 }
+/**
+ * 错误 ⇒ **下一步动作建议** (2026-10-01 优化 #6)。
+ * 光有标签(路径不存在/参数错误)还不够 —— 模型得知道**接着该干什么**, 否则就原地重试同一条命令。
+ */
+export function suggestNextAction(labelOrMsg) {
+    const s = String(labelOrMsg || '');
+    const rules = [
+        [/路径|不存在|ENOENT/i, '用 list_files / glob_files 看**真实**路径再重试(注意 ~ 展开与工作目录)'],
+        [/超时|timeout/i, '拆小(分成多次/加 limit)或改用后台执行, 别原样重发'],
+        [/权限|EACCES|EPERM/i, '换可写目录(如工作区或 /tmp), 不要动系统目录'],
+        [/参数|invalid|missing|必填/i, '对照工具描述里的必填项补齐参数; 不确定就先 list_tools 看schema'],
+        [/网络|ECONN|fetch failed|不可达/i, '确认本机服务/代理可达; 自家域走 --resolve + --noproxy'],
+        [/缓冲区|maxBuffer|输出过大/i, '加过滤(只取需要的行)或改写到文件再按需读取'],
+    ];
+    for (const [re, advice] of rules)
+        if (re.test(s))
+            return `下一步: ${advice}`;
+    return null;
+}