minimal-agent 0.8.2 → 0.10.0

package/src/tools/agent/coordinator.js

@@ -0,0 +1,93 @@
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+const active = [];
+const waiters = [];
+let running = 0;
+function overlaps(a, b) {
+    return a === b || a.startsWith(`${b}${sep}`) || b.startsWith(`${a}${sep}`);
+}
+function conflicts(cwd, scopes) {
+    return active.some((lease) => lease.cwd === cwd && lease.scopes.some((left) => scopes.some((right) => overlaps(left, right))));
+}
+function publishQueue() {
+    waiters.forEach((waiter, index) => waiter.onStatus?.({
+        phase: 'queued',
+        queuePosition: index + 1,
+        activeCount: running,
+        maxConcurrent: waiter.maxConcurrent,
+    }));
+}
+function drain() {
+    for (let i = 0; i < waiters.length;) {
+        const waiter = waiters[i];
+        if (running >= waiter.maxConcurrent) {
+            i++;
+            continue;
+        }
+        if (conflicts(waiter.cwd, waiter.scopes)) {
+            i++;
+            continue;
+        }
+        waiters.splice(i, 1);
+        if (waiter.onAbort)
+            waiter.signal?.removeEventListener('abort', waiter.onAbort);
+        running++;
+        const lease = { cwd: waiter.cwd, scopes: waiter.scopes };
+        active.push(lease);
+        waiter.onStatus?.({ phase: 'acquired', activeCount: running, maxConcurrent: waiter.maxConcurrent });
+        waiter.resolve(() => {
+            const index = active.indexOf(lease);
+            if (index >= 0)
+                active.splice(index, 1);
+            running = Math.max(0, running - 1);
+            drain();
+        });
+    }
+    publishQueue();
+}
+export async function normalizeWriteScopes(cwd, rawScopes) {
+    const lexicalRoot = resolve(cwd);
+    const physicalRoot = await realpath(lexicalRoot).catch(() => lexicalRoot);
+    if (!rawScopes?.length)
+        return [physicalRoot];
+    const normalized = new Set();
+    for (const raw of rawScopes) {
+        const value = raw.trim();
+        if (!value || isAbsolute(value))
+            throw new Error(`write_scopes 必须是工作目录内的相对路径：${raw}`);
+        const lexical = resolve(lexicalRoot, value);
+        const rel = relative(lexicalRoot, lexical);
+        if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+            throw new Error(`write_scopes 越过工作目录：${raw}`);
+        const physical = await realpath(lexical).catch(async () => {
+            const parent = await realpath(resolve(lexical, '..')).catch(() => physicalRoot);
+            return resolve(parent, lexical.split(sep).at(-1) ?? '');
+        });
+        const physicalRel = relative(physicalRoot, physical);
+        if (physicalRel === '..' || physicalRel.startsWith(`..${sep}`) || isAbsolute(physicalRel))
+            throw new Error(`write_scopes 经过符号链接越过工作目录：${raw}`);
+        normalized.add(physical);
+    }
+    return [...normalized].sort();
+}
+export async function acquireSubagentLease(cwd, scopes, maxConcurrent = 3, options = {}) {
+    const safeMax = Math.max(1, Math.min(8, maxConcurrent));
+    return new Promise((resolveLease, reject) => {
+        if (options.signal?.aborted)
+            return reject(new DOMException('Aborted', 'AbortError'));
+        const waiter = { cwd, scopes, maxConcurrent: safeMax, onStatus: options.onStatus, signal: options.signal, resolve: resolveLease, reject };
+        waiter.onAbort = () => {
+            const index = waiters.indexOf(waiter);
+            if (index >= 0)
+                waiters.splice(index, 1);
+            publishQueue();
+            reject(new DOMException('Aborted', 'AbortError'));
+        };
+        options.signal?.addEventListener('abort', waiter.onAbort, { once: true });
+        waiters.push(waiter);
+        // 不在这里 publishQueue：立即拿到租约的 waiter 会被 drain 直接报 'acquired'，
+        // 抢先报一次 'queued' 会让每个子任务都闪一下幻影「排队中」；真排队者由 drain
+        // 结尾的 publishQueue 覆盖。
+        drain();
+    });
+}

package/src/tools/agent/worktree.js

@@ -0,0 +1,270 @@
+/**
+ * ============================================================
+ *  src/tools/agent/worktree.ts —— 子 agent 的 git worktree 隔离助手
+ * ------------------------------------------------------------
+ *  搬自 Claude Code 官方 utils/worktree.ts 的核心路径（createAgentWorktree
+ *  那条**无全局状态**的路径——并行子 agent 不能共享单例 session 状态），
+ *  砍掉 settings/hooks/tmux/sparse-checkout/symlink 等锦上添花件。
+ *
+ *  保留的官方实战经验（每条都对应真实事故教训）：
+ *    - slug 白名单校验：slug 会被拼进目录路径与分支名，防路径穿越。
+ *    - `git worktree add -B`（大写 B）：上次目录被删但分支残留时强制重置，
+ *      免去额外的 git branch -D 前置清理。
+ *    - fail-closed 改动判定：任何 git 命令失败一律视为「有改动」，宁可多留
+ *      一个 worktree，绝不误删并行子 agent 的工作成果。
+ *    - 清理序列：worktree remove --force → 等 100ms 锁释放 → branch -D；
+ *      清理失败只记日志不抛——绝不让清理问题卡死主流程。
+ *    - GIT_TERMINAL_PROMPT=0 + stdin ignore：防 git/ssh 弹交互式凭证输入挂死。
+ *
+ *  目录选址 `<gitRoot>/.agent-worktrees/`：刻意避开 `.minimal-agent*` 保留前缀
+ *  （/new 会按前缀整目录 rm -rf，直接删 worktree 目录会留下悬空的 git 注册项）；
+ *  首次创建时追加进 `<gitdir>/info/exclude`（仓库本地 ignore，不污染共享 .gitignore）。
+ * ============================================================
+ */
+import { spawn } from 'node:child_process';
+import { appendFile, readFile, writeFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { dlog } from '../../utils/debugLog.js';
+const WORKTREES_DIR = '.agent-worktrees';
+/** 跑一条 git 命令（防挂死 env + stdin ignore），spawn 失败也归一成 ok:false。 */
+async function runGit(args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn('git', args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '' },
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
+        child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
+        child.on('error', (e) => resolve({ ok: false, stdout, stderr: String(e) }));
+        child.on('close', (code) => resolve({ ok: code === 0, stdout: stdout.trim(), stderr: stderr.trim() }));
+    });
+}
+/** slug 白名单（官方同款语义）：会拼进路径和分支名，只放行安全字符。 */
+export function validateSlug(slug) {
+    return /^[a-zA-Z0-9._-]{1,64}$/.test(slug) && slug !== '.' && slug !== '..';
+}
+/** 把 worktree 目录加进仓库本地 ignore（best-effort，失败静默——只是降噪）。 */
+async function ensureLocalExclude(cwd) {
+    try {
+        const r = await runGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+        if (!r.ok || !r.stdout)
+            return;
+        const excludePath = join(r.stdout, 'info', 'exclude');
+        const line = `${WORKTREES_DIR}/`;
+        const existing = await readFile(excludePath, 'utf8').catch(() => '');
+        if (existing.split(/\r?\n/).includes(line))
+            return;
+        await appendFile(excludePath, `${existing.endsWith('\n') || existing === '' ? '' : '\n'}${line}\n`);
+    }
+    catch {
+        /* ignore 失败只影响 git status 观感，不影响功能 */
+    }
+}
+/**
+ * 在当前仓库创建一个子 agent 专用 worktree（基于 HEAD 的独立分支）。
+ * 非 git 仓库 / 无提交仓库返回 ok:false——把决策权交回主 agent（降级无隔离或串行）。
+ */
+export async function createAgentWorktree(slug, fromCwd = getWorkingDir()) {
+    if (!validateSlug(slug)) {
+        return { ok: false, error: `非法的 worktree 名称「${slug}」（只允许字母数字._-，≤64 字符）` };
+    }
+    const root = await runGit(['rev-parse', '--show-toplevel'], fromCwd);
+    if (!root.ok || !root.stdout) {
+        return { ok: false, error: '当前目录不是 git 仓库，无法创建 worktree 隔离' };
+    }
+    const gitRoot = root.stdout;
+    const head = await runGit(['rev-parse', 'HEAD'], gitRoot);
+    if (!head.ok || !head.stdout) {
+        return { ok: false, error: '仓库还没有任何提交（HEAD 不存在），无法创建 worktree——先 git commit 一次' };
+    }
+    const baseSha = head.stdout;
+    const path = join(gitRoot, WORKTREES_DIR, slug);
+    const branch = `agent/${slug}`;
+    await ensureLocalExclude(gitRoot);
+    const add = await runGit(['worktree', 'add', '-B', branch, path, 'HEAD'], gitRoot);
+    if (!add.ok) {
+        return { ok: false, error: `git worktree add 失败：${add.stderr || add.stdout}` };
+    }
+    return { ok: true, path, branch, baseSha, gitRoot };
+}
+/**
+ * worktree 相对基线是否有改动（未提交文件 或 新增提交）。
+ * fail-closed：任何 git 命令失败一律返回 true（有改动）——宁多留不误删。
+ */
+export async function hasWorktreeChanges(path, baseSha) {
+    const status = await runGit(['status', '--porcelain'], path);
+    if (!status.ok)
+        return true;
+    if (status.stdout.length > 0)
+        return true;
+    const revList = await runGit(['rev-list', '--count', `${baseSha}..HEAD`], path);
+    if (!revList.ok)
+        return true;
+    return Number.parseInt(revList.stdout, 10) > 0;
+}
+/** 相对基线的 diff 摘要（best-effort，失败返回空串）——给主 agent 收口审阅用。 */
+export async function worktreeDiffStat(path, baseSha) {
+    const diff = await runGit(['diff', '--stat', baseSha], path);
+    const parts = [];
+    if (diff.ok && diff.stdout)
+        parts.push(diff.stdout);
+    // diff --stat 看不到未跟踪的新文件，用 status 补上
+    const status = await runGit(['status', '--porcelain'], path);
+    if (status.ok && status.stdout) {
+        const untracked = status.stdout
+            .split('\n')
+            .filter((l) => l.startsWith('??'))
+            .map((l) => `  新文件（未跟踪）: ${l.slice(3)}`);
+        if (untracked.length > 0)
+            parts.push(untracked.join('\n'));
+    }
+    return parts.join('\n');
+}
+/**
+ * 把 worktree 里的未提交改动确定性提交到临时分支（幂等：无改动直接 ok）。
+ * 为什么需要：子 agent 用 Edit/Write 改文件后通常**不会** git commit——
+ * 分支上没有提交的话，主 agent 收口时 `git merge` 合不到任何东西（改动只活在
+ * worktree 工作区里）。收尾时由引擎代提交，不依赖模型自觉。
+ * -c 内联身份兜底：机器没配 user.name/email 也能提交（squash 合并时最终
+ * 提交人仍是用户自己，临时分支上的作者名无所谓）。
+ */
+export async function commitWorktreeChanges(path, message) {
+    const status = await runGit(['status', '--porcelain'], path);
+    if (status.ok && status.stdout.length === 0)
+        return { ok: true };
+    if (status.ok) {
+        const sensitive = status.stdout.split('\n').map((line) => line.slice(3).trim()).filter(isSensitiveWorktreePath);
+        if (sensitive.length > 0) {
+            return { ok: false, error: `拒绝自动提交敏感文件：${sensitive.join(', ')}` };
+        }
+    }
+    const add = await runGit(['add', '-A'], path);
+    if (!add.ok)
+        return { ok: false, error: add.stderr || add.stdout };
+    const commit = await runGit([
+        '-c', 'user.name=minimal-agent',
+        '-c', 'user.email=agent@minimal-agent.local',
+        'commit', '-m', message,
+    ], path);
+    if (!commit.ok)
+        return { ok: false, error: commit.stderr || commit.stdout };
+    return { ok: true };
+}
+function isSensitiveWorktreePath(path) {
+    const normalized = path.replaceAll('\\', '/').toLowerCase();
+    const base = normalized.split('/').at(-1) ?? normalized;
+    return base === '.env' || base.startsWith('.env.') || normalized.includes('/.ssh/') ||
+        /(^|\/)(credentials?|secrets?)(\.|\/|$)/.test(normalized) ||
+        /\.(pem|key|p12|pfx|jks|keystore)$/.test(base) || base === 'id_rsa' || base === 'id_ed25519';
+}
+export async function worktreeChangedFiles(path, baseSha) {
+    const result = await runGit(['diff', '--name-only', baseSha], path);
+    const status = await runGit(['status', '--porcelain'], path);
+    const files = new Set();
+    if (result.ok)
+        for (const row of result.stdout.split('\n'))
+            if (row.trim())
+                files.add(row.trim());
+    if (status.ok)
+        for (const row of status.stdout.split('\n'))
+            if (row.length > 3)
+                files.add(row.slice(3).trim());
+    return [...files].sort();
+}
+/**
+ * 清理 worktree 目录 + 临时分支。尽力而为：失败只记 debug 日志，不抛——
+ * 清理残留可由用户随时 `git worktree remove` / `git branch -D` 手动处理。
+ */
+export async function removeAgentWorktree(path, branch, gitRoot) {
+    const rm = await runGit(['worktree', 'remove', '--force', path], gitRoot);
+    if (!rm.ok)
+        dlog('agent', 'worktree remove 失败', { path, err: rm.stderr });
+    // 官方经验：remove 后立即 branch -D 偶发撞锁，等 100ms 释放
+    await new Promise((r) => setTimeout(r, 100));
+    const del = await runGit(['branch', '-D', branch], gitRoot);
+    if (!del.ok)
+        dlog('agent', 'worktree 分支删除失败', { branch, err: del.stderr });
+}
+async function resolveManagedWorktree(cwd, id) {
+    if (!validateSlug(id))
+        return { ok: false, error: '非法的子任务 ID' };
+    const root = await runGit(['rev-parse', '--show-toplevel'], cwd);
+    if (!root.ok || !root.stdout)
+        return { ok: false, error: '当前目录不是 Git 仓库' };
+    const path = join(root.stdout, WORKTREES_DIR, id);
+    const branch = `agent/${id}`;
+    const base = await runGit(['merge-base', branch, 'HEAD'], root.stdout);
+    if (!base.ok || !base.stdout)
+        return { ok: false, error: '未找到该隔离子任务' };
+    return { ok: true, path, branch, baseSha: base.stdout, gitRoot: root.stdout };
+}
+export async function inspectAgentWorktree(cwd, id) {
+    const wt = await resolveManagedWorktree(cwd, id);
+    if (!wt.ok)
+        return { error: wt.error };
+    const diff = await runGit(['diff', '--binary', wt.baseSha, wt.branch], wt.gitRoot);
+    if (!diff.ok)
+        return { error: diff.stderr || '读取差异失败' };
+    const status = await runGit(['status', '--short'], wt.path);
+    const pending = status.ok && status.stdout
+        ? `\n\n尚未提交的隔离工作区改动（不会自动应用）：\n${status.stdout}`
+        : '';
+    return {
+        id,
+        branch: wt.branch,
+        baseSha: wt.baseSha,
+        diff: `${diff.stdout}${pending}`.trim(),
+        changedFiles: await worktreeChangedFiles(wt.path, wt.baseSha),
+    };
+}
+export async function applyAgentWorktree(cwd, id) {
+    const wt = await resolveManagedWorktree(cwd, id);
+    if (!wt.ok)
+        return wt;
+    const worktreeStatus = await runGit(['status', '--porcelain'], wt.path);
+    if (!worktreeStatus.ok)
+        return { ok: false, error: '无法确认隔离工作区状态，已停止自动应用' };
+    if (worktreeStatus.stdout) {
+        return {
+            ok: false,
+            error: '隔离工作区仍有未提交改动（可能包含被安全策略拒绝提交的文件），为防止丢失，不能自动应用或清理',
+        };
+    }
+    const head = await runGit(['rev-parse', 'HEAD'], wt.gitRoot);
+    if (!head.ok || head.stdout !== wt.baseSha)
+        return { ok: false, error: '当前 HEAD 已变化，不能安全应用；请先人工审阅和同步分支' };
+    const diff = await runGit(['diff', '--binary', wt.baseSha, wt.branch], wt.gitRoot);
+    if (!diff.ok)
+        return { ok: false, error: diff.stderr || '生成差异失败' };
+    if (!diff.stdout) {
+        await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+        return { ok: true };
+    }
+    const patchFile = join(wt.gitRoot, '.git', `minimal-agent-${process.pid}-${Date.now()}.patch`);
+    try {
+        // runGit 会 trim 文本输出；git apply 要求补丁保留终止换行。
+        await writeFile(patchFile, `${diff.stdout}\n`, { mode: 0o600 });
+        const check = await runGit(['apply', '--check', patchFile], wt.gitRoot);
+        if (!check.ok)
+            return { ok: false, error: `变更检查失败：${check.stderr || check.stdout}` };
+        const apply = await runGit(['apply', patchFile], wt.gitRoot);
+        if (!apply.ok)
+            return { ok: false, error: `应用变更失败：${apply.stderr || apply.stdout}` };
+        await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+        return { ok: true };
+    }
+    finally {
+        await unlink(patchFile).catch(() => { });
+    }
+}
+export async function discardAgentWorktree(cwd, id) {
+    const wt = await resolveManagedWorktree(cwd, id);
+    if (!wt.ok)
+        return wt;
+    await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+    return { ok: true };
+}

package/src/tools/ask/ask.js

@@ -46,6 +46,8 @@ const inputSchema = z.object({
     questions: z
         .array(questionSchema)
         .min(1)
+        .max(4) // 与工具描述/UI 上限硬对齐：超发在参数校验层被拒（模型拿 Zod 错误自纠），
+        // 避免「TUI 静默截断到 4 题 vs 非交互全部自动作答」的行为分叉
         .describe('1-4 个问题（通常 1 个；确需一次问多件事时才多个）'),
 });
 // ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
@@ -72,8 +74,10 @@ async function call(input, signal) {
         return { ok: true, content: lines.join('\n').trimEnd() };
     }
     catch (e) {
-        // 用户 ESC / Ctrl+C 取消提问 → 当普通工具失败喂回（主循环让模型换思路；
-        // workflow tool 步骤则按 onError 处理）。
+        // 提问被 reject → 当普通工具失败喂回。注意：TUI 里 ESC 经 App 的
+        // onCancel={chat.abort} 中断**整轮**（喂回后 loop 见 signal.aborted 收口
+        // interrupted，模型不会继续）；「让模型换思路」只在宿主 reject 单个提问
+        // 而不中断整轮时成立（workflow onError / 非 TUI 宿主自定义 handler）。
         return { ok: false, error: `提问被取消 / 中断：${e.message}` };
     }
 }
@@ -86,5 +90,6 @@ export const askUserQuestionTool = {
     isReadOnly: true,
     isConcurrencySafe: false,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'cancel',
     call,
 };

package/src/tools/bash/bash.js

@@ -41,15 +41,63 @@
  * ============================================================
  */
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { z } from 'zod';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { sanitizeCredentialEnv } from '../../config/configService.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { killTree } from '../shared/killTree.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { interpretCommandResult } from './semantics.js';
 import { scanDestructiveCommand } from './warnings.js';
 // ---------------- 0. 常量 ----------------
 const DEFAULT_TIMEOUT_MS = 120_000; // 2 min
 const MAX_TIMEOUT_MS = 600_000; // 10 min
+// ---------------- 0b. Windows shell 探测（模块加载时一次性） ----------------
+//
+// 根因（2026-06-12 实跑事故）：本工具 description 宣称 bash，但 win32 下
+// spawn({shell:true}) 实际是 cmd.exe —— 模型写的 `mkdir -p doc/scripts`（完全正确的
+// bash 语法）被 cmd 直接报语法错误；且中文 Windows 下 cmd 错误输出是 GBK 编码、
+// 被 setEncoding('utf8') 解码成乱码，模型既看不懂错误也换不对路，瞎试几轮后停摆，
+// 工作流执行步因此在第一条命令上整体卡死。
+//
+// 对策（三层）：
+//   ① 优先探测真 bash（Git Bash）——POSIX 语法直接成立，description 不再撒谎；
+//      排除 System32\bash.exe（WSL：跑在 Linux 环境，cwd/路径语义完全不同，不可用）。
+//   ② 找不到才回落 cmd，命令前缀 `chcp 65001 >nul & ` 强制 UTF-8 输出（根治乱码）。
+//   ③ description 运行时声明实际 shell（见下），模型按真实语法写命令。
+// 可用 MINIMAL_AGENT_BASH_PATH 显式指定（绿色版 U 盘机器上 Git 安装位置不可预知）。
+function detectWindowsBash() {
+    if (process.platform !== 'win32')
+        return null;
+    const explicit = process.env.MINIMAL_AGENT_BASH_PATH;
+    if (explicit && existsSync(explicit))
+        return explicit;
+    const pf = process.env.ProgramFiles ?? 'C:\\Program Files';
+    const pf86 = process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
+    const local = process.env.LOCALAPPDATA ?? '';
+    const candidates = [
+        join(pf, 'Git', 'bin', 'bash.exe'),
+        join(pf, 'Git', 'usr', 'bin', 'bash.exe'),
+        join(pf86, 'Git', 'bin', 'bash.exe'),
+        local ? join(local, 'Programs', 'Git', 'bin', 'bash.exe') : '',
+    ].filter(Boolean);
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    // PATH 兜底扫描（跳过 System32 的 WSL bash）
+    for (const dir of (process.env.PATH ?? '').split(';')) {
+        if (!dir || /\\system32\\?/i.test(dir))
+            continue;
+        const p = join(dir, 'bash.exe');
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+const WIN_BASH = detectWindowsBash();
 /**
  * G1：stdout / stderr 即时缓冲上限（各自）。命令狂输出（如 cat 大文件 / yes）时，
  * 在最终统一截断之前先把内存封顶，防 OOM。取最终展示截断阈值的 2 倍 —— 正常输出不受影响，
@@ -99,8 +147,15 @@ const FORBIDDEN_PATTERNS = [
         reason: '禁止重定向到裸磁盘设备',
     },
     // ---- 关机 / 重启 ----
+    // 只匹配「命令位置」的关机词：串首 / 换行 / ; & | ` ( { / $( / sudo·doas·exec·nohup / systemctl 之后。
+    // 事故（2026-07-02）：此前 /\b(?:shutdown|…)\b/ 对整段命令裸词扫描（注释也算），
+    // ppt.yaml stage_export 的 bash 注释「硬门 halt」被误杀 → 整步执行前被拒 →
+    // onError:halt → 确定性死端（resume 原样命令原样再拒，永久卡死）。
+    // "halt" 是工作流引擎自身词汇（onError: halt），注释/echo 文案里出现属正常写作。
+    // 已知窄化（防猪队友层可接受）：env/timeout 等间接调用不再拦；注释里 ASCII "; halt" 仍会误伤
+    // （workflows 全库有 bashBlacklist.sweep.test.ts 兜底扫描）。
     {
-        pattern: /\b(?:shutdown|reboot|halt|poweroff)\b/i,
+        pattern: /(?:^|[\n;&|`({]|\$\(|\b(?:sudo|doas|exec|nohup)\s+|\bsystemctl\s+)\s*(?:shutdown|reboot|halt|poweroff)\b/i,
         reason: '禁止关机/重启命令',
     },
     {
@@ -161,12 +216,21 @@ export function checkForbidden(command) {
  * 导出供测试断言。
  */
 export function sanitizedChildEnv(base = process.env) {
-    const env = { ...base };
+    const env = sanitizeCredentialEnv(base);
     for (const key of Object.keys(env)) {
         if (key.startsWith('MINIMAL_AGENT_') || key.startsWith('TAVILY_')) {
             delete env[key];
         }
     }
+    // 保证子进程里的 Python 用 UTF-8 解码（PEP 540 UTF-8 Mode）。否则中文 Windows 上
+    // locale.getpreferredencoding() = cp936/GBK，`subprocess.run(text=True)` / `open()`
+    // 默认就用 GBK 解码子进程的 UTF-8 输出 → 撞非法字节必崩（曾致 ppt 工作流 build_probe
+    // `UnicodeDecodeError: 'gbk' codec can't decode byte 0xa8` 直接 halt 整条工作流）。
+    // 这是 Bash 工具「保证 UTF-8 世界」既有立场（cmd 回落已 chcp 65001）的加性延伸：
+    // 一处覆盖所有 bash 步 spawn 的 python（内联 heredoc + 技能脚本），现在与将来。
+    // 跨平台安全：类 Unix 本就 UTF-8 → no-op；顺带治 POSIX/C locale(ASCII) 同类坑。
+    env.PYTHONUTF8 = '1';
+    env.PYTHONIOENCODING = 'utf-8';
     return env;
 }
 // ---------------- 1. Zod 输入 schema ----------------
@@ -245,7 +309,21 @@ The following command patterns are blocked at the tool level and will fail befor
 
 If you have a legitimate use case that requires one of the above patterns, ask the user to run the command themselves in their terminal — do not try to bypass the check.
 
-Separately, Bash scans for common destructive-but-recoverable patterns (\`git reset --hard\`, \`git push -f\` / \`--force\` / \`--force-with-lease\`, \`git checkout .\`, \`git restore .\`, \`git clean -f\`, \`git stash drop/clear\`, \`git branch -D\`, \`git commit --amend\` / \`--no-verify\`, \`rm -rf <path>\`, \`DROP TABLE\`, \`TRUNCATE\`, \`DELETE FROM\`, \`kubectl delete\`, \`terraform destroy\`, etc.) and prepends a \`⚠️ 警告:\` line to the output. These commands are NOT blocked — the warning is informational. Treat it as a signal to double-check intent and surface the warning to the user when relevant.`;
+Separately, Bash scans for common destructive-but-recoverable patterns (\`git reset --hard\`, \`git push -f\` / \`--force\` / \`--force-with-lease\`, \`git checkout .\`, \`git restore .\`, \`git clean -f\`, \`git stash drop/clear\`, \`git branch -D\`, \`git commit --amend\` / \`--no-verify\`, \`rm -rf <path>\`, \`DROP TABLE\`, \`TRUNCATE\`, \`DELETE FROM\`, \`kubectl delete\`, \`terraform destroy\`, etc.) and prepends a \`⚠️ 警告:\` line to the output. These commands are NOT blocked — the warning is informational. Treat it as a signal to double-check intent and surface the warning to the user when relevant.${process.platform !== 'win32'
+    ? ''
+    : WIN_BASH
+        ? `
+
+# Shell (this machine)
+Commands run in a real bash (Git Bash at ${WIN_BASH}). POSIX syntax works: \`mkdir -p\`, \`$VAR\`, \`$(...)\`, \`&&\`, \`[ -f x ]\` are all fine. Note the working directory is a Windows path — both \`D:\\path\` and \`/d/path\` forms work in this bash.`
+        : `
+
+# Shell (this machine) — IMPORTANT
+No bash found on this Windows machine: commands run in cmd.exe (UTF-8 enforced). POSIX syntax does NOT work here:
+ - NO \`mkdir -p\` — cmd's \`mkdir a\\b\\c\` creates intermediate directories by default; better: the Write tool auto-creates parent directories
+ - NO \`$VAR\` / \`$(...)\` / \`[ -f x ]\` / \`export\` — use \`%VAR%\`, \`if exist\`, \`set\`
+ - Use \`dir\` / \`copy\` / \`del\` / \`type\` instead of \`ls\` / \`cp\` / \`rm\` / \`cat\`
+\`&&\` and \`;\`-style chaining: \`&&\` works in cmd; \`;\` does not (use \`&\`).`}`;
 // ---------------- 4. call() —— 真正干活 ----------------
 async function call(input, signal) {
     const command = input.command;
@@ -261,9 +339,10 @@ async function call(input, signal) {
     // 4a-2. 破坏性命令告警扫描（仅警告，不阻塞）
     //       命中后把警告挂到结果输出顶部，让模型/用户看见苗头。
     const destructiveWarning = scanDestructiveCommand(command);
-    // 4b. spawn —— shell:true 让平台自己挑 shell
-    //     Unix:    /bin/sh -c <command>
-    //     Windows: cmd.exe /d /s /c "<command>"
+    // 4b. spawn —— 平台分派（见 0b 探测注释）：
+    //     Unix:               /bin/sh -c <command>（shell:true）
+    //     Windows + Git Bash: bash.exe -c <command>（POSIX 语法成立）
+    //     Windows 无 bash:    cmd.exe，命令前缀 chcp 65001 强制 UTF-8 输出
     let stdout = '';
     let stderr = '';
     let exitCode = null;
@@ -279,13 +358,32 @@ async function call(input, signal) {
     }, timeoutMs);
     try {
         await new Promise((resolveP, rejectP) => {
-            const child = spawn(command, {
-                shell: true,
+            const spawnOpts = {
                 cwd: getWorkingDir(),
-                signal: ac.signal,
                 env: sanitizedChildEnv(),
                 windowsHide: true,
-            });
+                // POSIX：detached 自成进程组，中断时 killTree 的 kill(-pid) 才能掀整组；win32 不 detached（taskkill /T 掀树）。
+                detached: process.platform !== 'win32',
+            };
+            const child = WIN_BASH
+                ? spawn(WIN_BASH, ['-c', command], spawnOpts)
+                : spawn(process.platform === 'win32'
+                    ? `chcp 65001 >nul & ${command}`
+                    : command, { ...spawnOpts, shell: true });
+            // 中断/超时收尾：杀**整棵进程树**（不是只杀直接 shell）。否则 win32 上 shell 被杀后，在飞的
+            // 孙进程（bun test / 构建 / 起服务…）变孤儿继续跑、还占着 stdout 管道让 'close' 永不触发 ——
+            // 表现为「点了停止、agent 停了、活儿还在后台跑」的"停不下来"（与 2026-07-02 生图事故同源）。
+            // 不再把 signal 交给 spawn 自己 kill（那只杀直接子进程，还会抢在 killTree 前把 shell 杀掉、
+            // 让 taskkill /T 够不到已成孤儿的孙进程）；改由这里统一 killTree + 立即 resolve，不空等 'close'。
+            const onKill = () => {
+                killedBySignal = true;
+                killTree(child);
+                resolveP();
+            };
+            if (ac.signal.aborted)
+                onKill();
+            else
+                ac.signal.addEventListener('abort', onKill, { once: true });
             child.stdout?.setEncoding('utf8');
             child.stderr?.setEncoding('utf8');
             child.stdout?.on('data', (chunk) => {
@@ -299,16 +397,11 @@ async function call(input, signal) {
                     stderr += chunk;
             });
             child.on('error', (e) => {
-                // signal abort 会先触发 error('AbortError')；把这种 case 转成正常分支
-                if (e.code === 'ABORT_ERR') {
-                    killedBySignal = true;
-                    resolveP();
-                }
-                else {
-                    rejectP(e);
-                }
+                ac.signal.removeEventListener('abort', onKill);
+                rejectP(e);
             });
             child.on('close', (code, sig) => {
+                ac.signal.removeEventListener('abort', onKill);
                 exitCode = code;
                 if (sig)
                     killedBySignal = true;
@@ -378,5 +471,6 @@ export const bashTool = {
     isReadOnly: false,
     isConcurrencySafe: false, // 默认按"会改状态"算；保守不并发
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'block',
     call,
 };