@bolloon/bolloon-agent 0.1.41 → 0.1.42

package/dist/llm/pi-ai.js

@@ -20,21 +20,78 @@ export function getSystemPrependProvider() {
 export class PiAIModel {
     config;
     provider;
+    /** 单次 LLM HTTP 请求硬上限 (ms), 防止上游卡住挂死整个 loop. 可通过 BOLLOON_LLM_TIMEOUT 覆盖. */
+    requestTimeoutMs;
     constructor(config) {
         this.config = config;
         this.provider = config.provider;
+        const envTimeout = Number(process.env.BOLLOON_LLM_TIMEOUT);
+        this.requestTimeoutMs = Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : 120_000;
     }
-    async chat(message, context, signal) {
-        const systemPrompt = await this.buildSystemPromptAsync(context);
-        const messages = [
-            { role: 'system', content: systemPrompt },
-            { role: 'user', content: message }
-        ];
+    /**
+     * 把外部 signal 和内部 timeout 合并: 任一触发都 abort.
+     * - 外部 signal 优先 (用户主动 abort)
+     * - 否则套 120s timeout
+     * - 任一不合法 (非 AbortSignal 实例) 时退到无 signal
+     */
+    combinedSignal(external) {
+        const valid = external instanceof AbortSignal ? external : undefined;
+        // Node 18+ 支持 AbortSignal.timeout, 旧版本兜底用 setTimeout 构造
+        if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') {
+            const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs);
+            if (!valid)
+                return timeoutSignal;
+            // 合并两个 signal
+            const ctrl = new AbortController();
+            const onAbort = () => ctrl.abort();
+            valid.addEventListener('abort', onAbort, { once: true });
+            timeoutSignal.addEventListener('abort', onAbort, { once: true });
+            if (valid.aborted || timeoutSignal.aborted)
+                ctrl.abort();
+            return ctrl.signal;
+        }
+        return valid;
+    }
+    /**
+     * 与 LLM 对话.
+     *
+     * 支持三种调用形式:
+     *   - 旧: chat(message: string, context?: string, signal?)
+     *       单一 user message + 附加 system context. 简单场景用.
+     *   - 新: chat(messages: ChatMessage[], context?: string, signal?)
+     *       完整 messages 数组, 含 user/assistant/tool/system role.
+     *       工具调用场景必用 — 否则 LLM 看不到工具结果.
+     *   - pivot loop 兼容: chat(context: string, systemPrompt: string, signal?)
+     *       第二参超过 2K 时视为 system prompt 覆盖, 避免把 46K context 当 user message 发送.
+     *
+     * 2026-06-17 (M3.5 调试): buildContext() 之前把所有 history 序列化成单字符串,
+     *   LLM 看不到 tool 调用的真实结果,导致 CLI loop 卡死.
+     *   现在 messages 数组版本保留 role 语义, LLM 能正确看到工具返回.
+     */
+    async chat(messageOrMessages, contextOrSystemPrompt, signal) {
+        const systemPrompt = await this.buildSystemPromptAsync(contextOrSystemPrompt);
+        let messages;
+        if (Array.isArray(messageOrMessages)) {
+            messages = [{ role: 'system', content: systemPrompt }, ...messageOrMessages];
+        }
+        else if (contextOrSystemPrompt && contextOrSystemPrompt.length > 2000) {
+            const baseSystem = await this.buildSystemPromptAsync(undefined);
+            messages = [
+                { role: 'system', content: baseSystem + '\n\n' + contextOrSystemPrompt },
+                { role: 'user', content: messageOrMessages }
+            ];
+        }
+        else {
+            messages = [
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: messageOrMessages }
+            ];
+        }
         try {
             const response = await this.generateText({
                 messages,
                 temperature: 0.8,
-                maxTokens: 8192, // 2026-06-15: 提到 8192, 避免长回答 (含表格/代码块) 被截断
+                maxTokens: 16384, // 2026-06-17: 提到 16384 — agent 注入 16K+ system prompt + 8K tool defs 时, 8K 撞上限返回空 content (见 memory: bolloon-llm-empty-large-prompt)
                 signal,
             });
             return { reply: response };
@@ -215,23 +272,42 @@ export class PiAIModel {
             temperature,
             max_tokens: maxTokens
         };
-        const response = await fetch(`${this.getBaseUrl()}/chat/completions`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${apiKey}`
-            },
-            body: JSON.stringify(requestBody),
-            // 2026-06-15: signal 字段防御 — Node 22+ undici 强类型 AbortSignal, 非 AbortSignal 实例
-            //   (e.g. 误传的 { maxTokens: 1 } 对象) 会 throw "Expected signal to be AbortSignal".
-            //   若不是 AbortSignal, 退到无 signal 调用, fetch 自然支持 timeout 由外层控制.
-            signal: signal instanceof AbortSignal ? signal : undefined,
-        });
-        if (!response.ok) {
-            throw new Error(`OpenAI API error: ${response.status}`);
+        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
+        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
+        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
+        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
+        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
+        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
+        let lastFinishReason = '';
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const response = await fetch(`${this.getBaseUrl()}/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${apiKey}`
+                },
+                body: JSON.stringify(requestBody),
+                signal: this.combinedSignal(signal),
+            });
+            if (!response.ok) {
+                throw new Error(`OpenAI API error: ${response.status}`);
+            }
+            const data = await response.json();
+            const choice = data.choices?.[0];
+            const content = choice?.message?.content || '';
+            lastFinishReason = choice?.finish_reason || '';
+            if (content) {
+                if (lastFinishReason === 'length') {
+                    console.warn(`[pi-ai] hit max_tokens ceiling (model=${this.mapModel()}, max_tokens=${maxTokens}) — caller should trim prompt or raise cap`);
+                }
+                return content;
+            }
+            // 空 content: 200 但 content="" → minimax 上游偶发, 退避后重试
+            console.warn(`[pi-ai] attempt ${attempt + 1}/3: 空 content (finish_reason=${lastFinishReason}), 退避 1.5s 重试`);
+            await new Promise(resolve => setTimeout(resolve, 1500));
         }
-        const data = await response.json();
-        return data.choices?.[0]?.message?.content || '';
+        console.warn(`[pi-ai] 3 次重试都返回空 content (finish_reason=${lastFinishReason})`);
+        return ''; // 返回空让上层看到 [AI 服务调用失败]
     }
     async callAnthropic(messages, temperature, maxTokens, signal) {
         const apiKey = this.getApiKey();
@@ -255,7 +331,7 @@ export class PiAIModel {
                 temperature,
                 max_tokens: maxTokens
             }),
-            signal,
+            signal: this.combinedSignal(signal),
         });
         if (!response.ok) {
             throw new Error(`Anthropic API error: ${response.status}`);
@@ -275,7 +351,7 @@ export class PiAIModel {
                 temperature,
                 stream: false
             }),
-            signal,
+            signal: this.combinedSignal(signal),
         });
         if (!response.ok) {
             throw new Error(`Ollama API error: ${response.status}`);
@@ -302,7 +378,7 @@ export class PiAIModel {
                 temperature,
                 max_tokens: maxTokens
             }),
-            signal,
+            signal: this.combinedSignal(signal),
         });
         if (!response.ok) {
             throw new Error(`OpenRouter API error: ${response.status}`);
@@ -335,7 +411,7 @@ export class PiAIModel {
                     maxOutputTokens: maxTokens
                 }
             }),
-            signal,
+            signal: this.combinedSignal(signal),
         });
         if (!response.ok) {
             throw new Error(`Gemini API error: ${response.status}`);

package/dist/network/local-inbox-bus.js

@@ -0,0 +1,73 @@
+/**
+ * local-inbox-bus.ts — 进程内 Agent 通信总线 (2026-06-19)
+ *
+ * 解决 bolloon "和另一个智能体发消息" 的本地场景:
+ *   - 同进程内多个 PiAgentSession 实例 (例如 nodeA / nodeB 测试) 互发消息
+ *   - 走 in-process EventEmitter, 不依赖 P2P 网络/Hyperswarm
+ *   - 远端通信仍走 p2pNetwork.sendMessage + onMessage
+ *
+ * 用法:
+ *   const bus = LocalInboxBus.getInstance();
+ *   bus.subscribe('nodeA', (msg) => console.log('nodeA got:', msg));
+ *   bus.deliver('nodeB', { from: 'nodeA', type: 'agent-message', payload: 'hi' });
+ *
+ * 角色标识: 默认从 process.env.BOLLOON_ROLE 读, 也可显式传
+ */
+import { EventEmitter } from 'events';
+class LocalInboxBus {
+    static _instance = null;
+    emitter;
+    /** 记录已注册的角色, deliver 时找不到会返回 false (避免 silent drop) */
+    registeredRoles = new Set();
+    constructor() {
+        this.emitter = new EventEmitter();
+        // 防止 listener 太多导致 memory leak
+        this.emitter.setMaxListeners(1000);
+    }
+    static getInstance() {
+        if (!LocalInboxBus._instance) {
+            LocalInboxBus._instance = new LocalInboxBus();
+        }
+        return LocalInboxBus._instance;
+    }
+    /**
+     * 订阅角色 inbox — 投递到该角色的消息会回调 fn
+     * 返回 unsubscribe 函数
+     */
+    subscribe(role, fn) {
+        this.registeredRoles.add(role);
+        this.emitter.on(`role:${role}`, fn);
+        return () => {
+            this.emitter.off(`role:${role}`, fn);
+            // 如果没人订阅, 移除 role (避免泄漏)
+            if (this.emitter.listenerCount(`role:${role}`) === 0) {
+                this.registeredRoles.delete(role);
+            }
+        };
+    }
+    /**
+     * 投递消息到指定角色
+     * 返回 true=已投递, false=角色未注册
+     */
+    deliver(role, msg) {
+        if (!this.registeredRoles.has(role)) {
+            return false;
+        }
+        this.emitter.emit(`role:${role}`, msg);
+        return true;
+    }
+    /**
+     * 列出当前进程所有已注册的角色
+     */
+    listRoles() {
+        return Array.from(this.registeredRoles);
+    }
+    /**
+     * 检查某角色是否已订阅
+     */
+    hasRole(role) {
+        return this.registeredRoles.has(role);
+    }
+}
+export { LocalInboxBus };
+export default LocalInboxBus;

package/dist/network/p2p-direct.js

@@ -18,6 +18,8 @@ import { EventEmitter } from 'events';
 // @ts-ignore — b4a 没官方 .d.ts
 import b4a from 'b4a';
 import { loadOrCreateKeyPair, writebackPublicKey } from './p2p-secret.js';
+// 静态 import input-scanner (ESM, 替代 require 避免 "require is not defined" 报错)
+import * as inputScanner from '../security/input-scanner.js';
 export class P2PDirect extends EventEmitter {
     swarm = null;
     name;
@@ -67,10 +69,7 @@ export class P2PDirect extends EventEmitter {
                 // P-Action 3: untrusted-input scanner (默认 silence-on-fail + log-only)
                 // 包装层 跨机器 @-mention 代发 (已 WORKING) 不能 block-on-suspicion
                 try {
-                    // 动态 import 避免循环依赖 + 启动时加载
-                    // (lazy require to keep cold-start fast)
-                    // eslint-disable-next-line @typescript-eslint/no-var-requires
-                    const { scanInput, writeScanAudit, shouldHardBlock } = require('../security/input-scanner.js');
+                    const { scanInput, writeScanAudit, shouldHardBlock } = inputScanner;
                     const result = scanInput(buf, { source: 'p2p' });
                     if (shouldHardBlock(result)) {
                         console.warn(`[P2PDirect:${this.name}] 阻断恶意消息 from ${remotePubKeyHex.substring(0, 12)}... (verdict=${result.verdict}, threats=${result.threats.length})`);

package/dist/pi-ecosystem-judgment/adaptive-scan.js

@@ -21,11 +21,15 @@ import * as path from 'path';
 import { loadAllJudgments } from './human-value-store.js';
 // 用 getter 函数而非模块顶层 const: process.env.HOME 在测试 beforeAll 才设,
 // 模块顶层求值时还是真 home. 运行时求值才能正确响应测试 fixture.
+// 跨平台: 优先 process.env.HOME (测试可控), 然后 os.homedir() (Windows 上读 USERPROFILE).
+// 用 path.join 而不是字符串拼接, 保证 Windows 上用 \ 分隔.
 function getUsageLogPath() {
-    return (os.homedir() || process.env.HOME || '/tmp') + '/.bolloon/human-values/usage.jsonl';
+    const home = process.env.HOME || os.homedir() || '/tmp';
+    return path.join(home, '.bolloon', 'human-values', 'usage.jsonl');
 }
 function getEvolutionLogPath() {
-    return (os.homedir() || process.env.HOME || '/tmp') + '/.bolloon/human-values/evolution.jsonl';
+    const home = process.env.HOME || os.homedir() || '/tmp';
+    return path.join(home, '.bolloon', 'human-values', 'evolution.jsonl');
 }
 /**
  * P-Action 1: next-action hint (4 仓库都强调的错误信息 = 修复指令 思想)

package/dist/pi-ecosystem-judgment/causal-judge.js

@@ -22,9 +22,9 @@ import * as os from 'os';
 import * as path from 'path';
 import { getModel } from '../llm/pi-ai.js';
 import { loadAllJudgments } from './human-value-store.js';
-const EVOLUTION_LOG = (process.env.HOME || os.homedir() || '/tmp') + '/.bolloon/human-values/evolution.jsonl';
-const COUNTERFACTUAL_LOG = (process.env.HOME || os.homedir() || '/tmp') + '/.bolloon/human-values/counterfactual-audit.jsonl';
-const USAGE_LOG = (process.env.HOME || os.homedir() || '/tmp') + '/.bolloon/human-values/usage.jsonl';
+const EVOLUTION_LOG = path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'human-values', 'evolution.jsonl');
+const COUNTERFACTUAL_LOG = path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'human-values', 'counterfactual-audit.jsonl');
+const USAGE_LOG = path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'human-values', 'usage.jsonl');
 async function readUsageLog() {
     try {
         const content = await fs.readFile(USAGE_LOG, 'utf-8');

package/dist/pi-ecosystem-judgment/index.js

@@ -266,7 +266,7 @@ export async function extractFromFragment(fragmentPath) {
                 type: 'rule',
                 content: ruleContent,
                 source: 'human',
-                confidence: 0.8,
+                confidence: 0.9,
                 context,
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString(),

package/dist/security/tool-gate.js

@@ -21,6 +21,17 @@ const TOOL_WHITELIST = new Set([
     'read', 'write', 'edit_file', 'list_files',
     'list_sessions', 'get_session_state', 'list_messages',
     'send_to_channel', 'create_channel',
+    // M2.1 (2026-06-17): 新增的 10 个 agent 工具 (跟 pi-sdk registerTools 同步)
+    'write_file', 'git_diff', 'git_commit', 'git_push', 'git_branch',
+    'create_task', 'update_task', 'get_task', 'list_tasks',
+    'use_skill', 'self_improve',
+    // 2026-06-19: M4 新增 (跟 pi-sdk.ts registerTools 同步)
+    'read_file', 'delete_file', 'mkdir', 'move_file',
+    'grep_files', 'glob_files',
+    'git_log', 'git_show', 'git_stash',
+    'vitest_run', 'tsc_check',
+    // 2026-06-19: Agent Mesh 通信工具 (跟 pi-sdk.ts registerTools 同步)
+    'check_inbox', 'send_to_peer', 'p2p_broadcast', 'send_to_local_agent', 'list_local_agents', 'agent_call',
     // MCP 注册的工具
     'mcp_tool',
 ]);

package/dist/web/server.js

@@ -769,6 +769,50 @@ async function handleV3P2PMessage(parsed, conn, comm) {
         }
         return;
     }
+    // v3 新增: --collab CLI 派任务过来, 对方 web 收到后跑 LLM 干活, 回结果
+    if (op === 'agent.collab.run') {
+        const { requestId, task, fromPublicKey, fromRole, timeoutMs } = parsed.payload || {};
+        if (!requestId || !task) {
+            console.warn(`[v3-collab] agent.collab.run 缺少 requestId/task`);
+            return;
+        }
+        const senderKey = fromPublicKey || peerKey;
+        console.log(`[v3-collab] 收到 ${senderKey.substring(0, 12)}... (${fromRole}) 的协作任务: "${task.substring(0, 60)}..."`);
+        const startTs = Date.now();
+        try {
+            // 调 LLM: 走 getAgentForChannel 拿 agent, 用 prompt() 拿 string 结果
+            const visitorHint = `[系统上下文] 协作任务来源: 远端 peer (P2P, publicKey=${senderKey.substring(0, 12)}..., role=${fromRole || 'unknown'}). 这是通过 P2P 派过来的协作任务, 回答后会自动回到对方那里. 简洁完成, 不需要反问.\n\n`;
+            const fullPrompt = `【本轮协作任务】\n${task}\n【任务结束】\n\n${visitorHint}`;
+            // 临时用 channelId = "__collab__" 拿个一次性 agent
+            const collabChannelId = `__collab_${senderKey.substring(0, 8)}__`;
+            const agent = await getAgentForChannel(collabChannelId, '', `collab-${senderKey.substring(0, 8)}`, undefined);
+            const resultText = await agent.prompt(fullPrompt);
+            const reply = JSON.stringify({
+                v: 3,
+                op: 'agent.collab.reply',
+                payload: {
+                    requestId,
+                    fromPublicKey: v3P2PRef?.getPublicKey() || '',
+                    result: resultText || '(empty)',
+                    durationMs: Date.now() - startTs,
+                },
+            });
+            await comm.sendToConnection(conn.id, reply);
+            console.log(`[v3-collab] 已回 reply (${Date.now() - startTs}ms, ${(resultText || '').length} chars)`);
+        }
+        catch (e) {
+            console.error(`[v3-collab] 处理失败:`, e.message);
+            try {
+                const errReply = JSON.stringify({
+                    v: 3, op: 'agent.collab.reply',
+                    payload: { requestId, fromPublicKey: v3P2PRef?.getPublicKey() || '', error: e.message, result: '' }
+                });
+                await comm.sendToConnection(conn.id, errReply);
+            }
+            catch { }
+        }
+        return;
+    }
     // v3 新增: 收到远端发来的 @-mention 跨渠道消息, 存到本地 target channel
     if (op === 'agent.cross.post') {
         const { targetChannelId, targetChannelName, originChannelId, originChannelName, text, fromPublicKey } = parsed.payload || {};
@@ -936,7 +980,14 @@ async function getAgentForChannel(channelId, channelDid, channelName, channelDid
     const session = await createAgentSession({
         cwd: process.cwd(),
         peerId: `channel-${channelId}:${currentSessionId}`,
-        identityDoc
+        identityDoc,
+        // M2.3 (2026-06-17): 构造时从 session JSON 回灌历史 — 服务重启后 LLM 仍记得前面对话
+        //   key 跟 server.ts:240 写入路径保持一致: ~/.bolloon/sessions/cache/<key>.json
+        loadSessionKey: sessionKey,
+        // M3.1 (2026-06-17): 默认启用 WorkflowPivotLoop — web 路径以前死代码, 现在用
+        //   pivot loop 自带 quality scoring + task complexity analysis + 30 iters cap
+        //   (老 ReAct 10000 iter cap 容易跑飞)
+        usePivotLoop: true,
     }, true); // forceNew: true 强制创建新实例
     channelSessions.set(sessionKey, session);
     if (channelDid) {
@@ -1665,13 +1716,19 @@ export async function createWebServer(port = 3000, options = {}) {
                     console.log(`[chat] aborted channel=${channelId}`);
                 }
                 else {
-                    throw err;
+                    // M1.2 (2026-06-17): 不再 rethrow — 把错误塞到 fullResponse 让 broadcast 出来, 后续 session 仍保存
+                    // 旧行为: 抛到外层 catch, 触发 500 + 用户消息丢失 (session 不保存)
+                    console.error(`[chat] LLM 调用失败 channel=${channelId}:`, err);
+                    fullResponse = `[错误: LLM 调用失败] ${String(err?.message || err).slice(0, 300)}`;
+                    broadcast({ type: 'error', content: fullResponse }, channelId);
                 }
             }
             // abort 模式: 给 partial 拼后缀
             if (runState.abortController?.signal.aborted && fullResponse.trim().length > 0) {
                 fullResponse = fullResponse + '\n\n_[生成已中断]_';
             }
+            // 2026-06-18: 修 lastFinalReply 没设 → /api/loop/inspect 永远返回空
+            runState.lastFinalReply = fullResponse;
             // v3 新增: 解析 LLM 回复里的 @-mentions, 转发到目标 channel
             await routeMentionsInReply(channelId, fullResponse, localChannels, remoteChannels);
             broadcast({ type: 'ai', content: fullResponse }, channelId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli.js",
@@ -17,7 +17,7 @@
     "build:all": "npm run build:main && npm run build:web && npm run build:electron && npm run build:cli",
     "start": "node dist/index.js",
     "dev": "tsx -r dotenv/config src/index.ts",
-    "dev:web": "npm run build:web && npm run dev",
+    "dev:web": "npm run build:web && tsx -r dotenv/config src/index.ts --web",
     "dev:electron": "npm run build:electron && npm run electron:start",
     "electron:start": "NODE_ENV=development electron dist/electron.js",
     "electron:dev": "concurrently \"npm run dev:web\" \"npm run electron:start\"",

package/scripts/lefthook-helper.sh

@@ -0,0 +1,69 @@
+#!/bin/sh
+# 2026-06-17: lefthook helper — agent auto-evolve branch detection
+# 写在独立文件里避免 lefthook 嵌套引号 + Windows bash 解析问题
+# 用法: lefthook.yml 里 run: sh scripts/lefthook-helper.sh <command>
+#   <command> = commit | vitest-full | build-check | tag-baseline
+
+CMD="$1"
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo none)
+AUTO_EVOLVE_MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1 | grep -c ^auto-evolve: || echo 0)
+
+is_master_main() {
+  [ "$BRANCH" = "master" ] || [ "$BRANCH" = "main" ]
+}
+
+is_auto_evolve() {
+  if [ "$BOLLOON_AUTO_EVOLVE" = "1" ]; then return 0; fi
+  if [ "$AUTO_EVOLVE_MSG" -gt 0 ] 2>/dev/null; then return 0; fi
+  return 1
+}
+
+case "$CMD" in
+  commit-vitest-bail)
+    if is_auto_evolve; then
+      echo "[skip] vitest-bail (auto-evolve mode, branch=$BRANCH)"
+      exit 0
+    fi
+    npx vitest run --bail=1 --reporter=dot
+    ;;
+  commit-tsc-check)
+    if is_auto_evolve; then
+      echo "[skip] tsc-check (auto-evolve mode, branch=$BRANCH)"
+      exit 0
+    fi
+    npx tsc --noEmit
+    ;;
+  push-vitest-full)
+    if is_master_main; then
+      npx vitest run --reporter=dot
+    else
+      echo "[skip] vitest-full (branch=$BRANCH, not master/main)"
+      exit 0
+    fi
+    ;;
+  push-build-check)
+    if is_master_main; then
+      npm run build:main
+    else
+      echo "[skip] build-check (branch=$BRANCH, not master/main)"
+      exit 0
+    fi
+    ;;
+  push-tag-baseline)
+    if is_master_main; then
+      if git tag -l 'auto-evolve-baseline-*' | grep -q .; then
+        exit 0
+      else
+        echo "[ERROR] push to master/main requires auto-evolve-baseline-* tag. Run: bash scripts/auto-evolve-snapshot.sh"
+        exit 1
+      fi
+    else
+      echo "[skip] tag-baseline (branch=$BRANCH, not master/main)"
+      exit 0
+    fi
+    ;;
+  *)
+    echo "Unknown command: $CMD"
+    exit 1
+    ;;
+esac