minimal-agent 0.13.0 → 0.14.0

package/src/harness/evidenceLedger.ts

@@ -33,6 +33,7 @@ export class EvidenceLedger {
   #failedToolCalls = 0;
 
   record(toolName: string, argsJson: string, result: ToolResult): void {
+    if (!result.ok && result.disposition === 'deferred') return;
     this.#toolCalls += 1;
     if (!result.ok) this.#failedToolCalls += 1;
     const base: RunEvidenceEntry = {

package/src/harness/stallGuard.js

@@ -18,6 +18,8 @@ export class StallGuard {
         for (let index = 0; index < calls.length; index += 1) {
             const call = calls[index];
             const result = results[index];
+            if (!result.ok && result.disposition === 'deferred')
+                continue;
             if (result.ok) {
                 this.#lastFailure = '';
                 this.#lastFailureCall = '';
@@ -41,9 +43,13 @@ export class StallGuard {
                 };
             }
         }
-        const batch = hash(calls
-            .map((call, index) => {
-            const result = results[index];
+        const batchItems = calls
+            .map((call, index) => ({ call, result: results[index] }))
+            .filter(({ result }) => result.ok || result.disposition !== 'deferred');
+        if (batchItems.length === 0)
+            return { stalled: false };
+        const batch = hash(batchItems
+            .map(({ call, result }) => {
             return `${call.function.name}\0${call.function.arguments}\0${result.ok ? result.content : result.error}`;
         })
             .join('\x01'));

package/src/harness/stallGuard.ts

@@ -35,6 +35,7 @@ export class StallGuard {
     for (let index = 0; index < calls.length; index += 1) {
       const call = calls[index]!;
       const result = results[index]!;
+      if (!result.ok && result.disposition === 'deferred') continue;
       if (result.ok) {
         this.#lastFailure = '';
         this.#lastFailureCall = '';
@@ -60,10 +61,13 @@ export class StallGuard {
       }
     }
 
+    const batchItems = calls
+      .map((call, index) => ({ call, result: results[index]! }))
+      .filter(({ result }) => result.ok || result.disposition !== 'deferred');
+    if (batchItems.length === 0) return { stalled: false };
     const batch = hash(
-      calls
-        .map((call, index) => {
-          const result = results[index]!;
+      batchItems
+        .map(({ call, result }) => {
           return `${call.function.name}\0${call.function.arguments}\0${result.ok ? result.content : result.error}`;
         })
         .join('\x01'),

package/src/images/imageResolver.js

@@ -0,0 +1,161 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { agentStateDir } from '../context/agentHome.js';
+export const DEFAULT_MAX_IMAGE_INPUT_BYTES = 25 * 1024 * 1024;
+export const DEFAULT_MAX_MODEL_IMAGE_BYTES = 10 * 1024 * 1024;
+function is(bytes, offset, signature) {
+    return signature.every((value, index) => bytes[offset + index] === value);
+}
+/** Actual bytes are authoritative; names and declared MIME are never trusted. */
+export function detectImageMime(bytes) {
+    if (bytes.length >= 8 && is(bytes, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return 'image/png';
+    if (bytes.length >= 3 && is(bytes, 0, [0xff, 0xd8, 0xff]))
+        return 'image/jpeg';
+    if (bytes.length >= 6 && ['GIF87a', 'GIF89a'].includes(bytes.toString('ascii', 0, 6)))
+        return 'image/gif';
+    if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP')
+        return 'image/webp';
+    if (bytes.length >= 2 && bytes.toString('ascii', 0, 2) === 'BM')
+        return 'image/bmp';
+    if (bytes.length >= 4 && (is(bytes, 0, [0x49, 0x49, 0x2a, 0x00]) || is(bytes, 0, [0x4d, 0x4d, 0x00, 0x2a])))
+        return 'image/tiff';
+    if (bytes.length >= 16 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+        const brands = bytes.subarray(8, Math.min(bytes.length, 64)).toString('ascii');
+        if (/(?:avif|avis)/.test(brands))
+            return 'image/avif';
+        if (/(?:heic|heix|hevc|hevx|heim|heis|mif1|msf1)/.test(brands))
+            return 'image/heic';
+    }
+    const prefix = bytes.subarray(0, Math.min(bytes.length, 4096)).toString('utf8').replace(/^\uFEFF/, '').trimStart();
+    if (/^(?:<\?xml[^>]*>\s*)?<svg\b/i.test(prefix))
+        return 'image/svg+xml';
+    return null;
+}
+function declaredMimeForExtension(path) {
+    return {
+        '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+        '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp',
+        '.tif': 'image/tiff', '.tiff': 'image/tiff', '.avif': 'image/avif',
+        '.heic': 'image/heic', '.heif': 'image/heic', '.svg': 'image/svg+xml',
+    }[extname(path).toLowerCase()];
+}
+async function loadSharp() {
+    return (await import('sharp')).default;
+}
+async function decodeHeic(bytes) {
+    const imported = await import('heic-convert');
+    const convert = imported.default;
+    if (typeof convert !== 'function')
+        throw new Error('HEIC 解码器未正确加载');
+    const output = await convert({ buffer: bytes, format: 'JPEG', quality: 0.92 });
+    return Buffer.from(output);
+}
+async function normalizeForModel(bytes, detected, maxOutputBytes) {
+    const sharp = await loadSharp();
+    const decoded = detected === 'image/heic' ? await decodeHeic(bytes) : bytes;
+    const image = sharp(decoded, { animated: false }).rotate().resize({
+        width: 4096,
+        height: 4096,
+        fit: 'inside',
+        withoutEnlargement: true,
+    });
+    const metadata = await image.metadata();
+    const preserveAlpha = metadata.hasAlpha === true || detected === 'image/svg+xml';
+    let output = preserveAlpha
+        ? await image.clone().png({ compressionLevel: 9 }).toBuffer()
+        : await image.clone().jpeg({ quality: 88, mozjpeg: true }).toBuffer();
+    if (output.length > maxOutputBytes && !preserveAlpha) {
+        output = await image.clone().jpeg({ quality: 75, mozjpeg: true }).toBuffer();
+    }
+    if (output.length > maxOutputBytes) {
+        throw new Error(`规范化后图片仍超过 ${(maxOutputBytes / 1024 / 1024).toFixed(0)}MB 上限`);
+    }
+    return { bytes: output, mime: preserveAlpha ? 'image/png' : 'image/jpeg' };
+}
+function modelMime(detected) {
+    return ['image/jpeg', 'image/png', 'image/gif', 'image/webp'].includes(detected)
+        ? detected
+        : null;
+}
+export async function resolveLocalImage(path, options = {}) {
+    const info = await stat(path).catch((error) => {
+        throw new Error(`无法读取图片：${path}（${error.message}）`);
+    });
+    if (!info.isFile())
+        throw new Error(`图片路径不是文件：${path}`);
+    const maxInputBytes = options.maxInputBytes ?? DEFAULT_MAX_IMAGE_INPUT_BYTES;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_MODEL_IMAGE_BYTES;
+    if (info.size > maxInputBytes)
+        throw new Error(`图片超过 ${(maxInputBytes / 1024 / 1024).toFixed(0)}MB 输入上限：${path}`);
+    const bytes = await readFile(path);
+    const detected = detectImageMime(bytes);
+    if (!detected) {
+        const declared = declaredMimeForExtension(path);
+        throw new Error(declared
+            ? `文件扩展名声明为 ${declared}，但内容不是可解码图片：${path}`
+            : `无法从文件内容识别图片格式：${path}`);
+    }
+    const declared = declaredMimeForExtension(path);
+    const diagnostic = declared && declared !== detected
+        ? `扩展名声明 ${declared}，实际内容为 ${detected}`
+        : undefined;
+    const directMime = modelMime(detected);
+    if (directMime && bytes.length <= maxOutputBytes) {
+        // Decode metadata once so truncated/corrupt files do not masquerade as images.
+        const sharp = await loadSharp();
+        const metadata = await sharp(bytes, { animated: detected === 'image/gif' }).metadata();
+        const needsOrientationFix = detected === 'image/jpeg' && (metadata.orientation ?? 1) > 1;
+        if (!needsOrientationFix) {
+            return {
+                originalPath: path,
+                path,
+                originalMime: detected,
+                mime: directMime,
+                size: bytes.length,
+                transformed: false,
+                ...(diagnostic ? { diagnostic } : {}),
+            };
+        }
+    }
+    const normalized = await normalizeForModel(bytes, detected, maxOutputBytes).catch((error) => {
+        throw new Error(`图片格式 ${detected} 无法规范化：${path}（${error.message}）`);
+    });
+    const hash = createHash('sha256')
+        .update(bytes)
+        .update('\0model-image-v1\0')
+        .update(normalized.mime)
+        .digest('hex');
+    const extension = normalized.mime === 'image/png' ? '.png' : '.jpg';
+    const dir = join(agentStateDir(), 'image-derivatives', hash.slice(0, 2));
+    const target = join(dir, `${hash}${extension}`);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const exists = await stat(target).then((item) => item.isFile()).catch(() => false);
+    if (!exists) {
+        const temp = `${target}.${randomUUID()}.tmp`;
+        await writeFile(temp, normalized.bytes, { mode: 0o600 });
+        await rename(temp, target).catch(async () => {
+            const wonRace = await stat(target).then((item) => item.isFile()).catch(() => false);
+            if (!wonRace)
+                throw new Error(`无法保存图片派生文件：${target}`);
+        });
+    }
+    return {
+        originalPath: path,
+        path: target,
+        originalMime: detected,
+        mime: normalized.mime,
+        size: normalized.bytes.length,
+        transformed: true,
+        diagnostic: [diagnostic, `已规范化为 ${normalized.mime}`].filter(Boolean).join('；'),
+    };
+}
+export async function tryResolveLocalImage(path) {
+    try {
+        return await resolveLocalImage(path);
+    }
+    catch {
+        return null;
+    }
+}

package/src/images/imageResolver.ts

@@ -0,0 +1,189 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+
+import { agentStateDir } from '../context/agentHome.js';
+
+export const DEFAULT_MAX_IMAGE_INPUT_BYTES = 25 * 1024 * 1024;
+export const DEFAULT_MAX_MODEL_IMAGE_BYTES = 10 * 1024 * 1024;
+
+export type DetectedImageMime =
+  | 'image/jpeg'
+  | 'image/png'
+  | 'image/gif'
+  | 'image/webp'
+  | 'image/bmp'
+  | 'image/tiff'
+  | 'image/avif'
+  | 'image/heic'
+  | 'image/svg+xml';
+
+export interface ResolvedLocalImage {
+  originalPath: string;
+  path: string;
+  originalMime: DetectedImageMime;
+  mime: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+  size: number;
+  transformed: boolean;
+  diagnostic?: string;
+}
+
+function is(bytes: Buffer, offset: number, signature: readonly number[]): boolean {
+  return signature.every((value, index) => bytes[offset + index] === value);
+}
+
+/** Actual bytes are authoritative; names and declared MIME are never trusted. */
+export function detectImageMime(bytes: Buffer): DetectedImageMime | null {
+  if (bytes.length >= 8 && is(bytes, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png';
+  if (bytes.length >= 3 && is(bytes, 0, [0xff, 0xd8, 0xff])) return 'image/jpeg';
+  if (bytes.length >= 6 && ['GIF87a', 'GIF89a'].includes(bytes.toString('ascii', 0, 6))) return 'image/gif';
+  if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') return 'image/webp';
+  if (bytes.length >= 2 && bytes.toString('ascii', 0, 2) === 'BM') return 'image/bmp';
+  if (bytes.length >= 4 && (is(bytes, 0, [0x49, 0x49, 0x2a, 0x00]) || is(bytes, 0, [0x4d, 0x4d, 0x00, 0x2a]))) return 'image/tiff';
+  if (bytes.length >= 16 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+    const brands = bytes.subarray(8, Math.min(bytes.length, 64)).toString('ascii');
+    if (/(?:avif|avis)/.test(brands)) return 'image/avif';
+    if (/(?:heic|heix|hevc|hevx|heim|heis|mif1|msf1)/.test(brands)) return 'image/heic';
+  }
+  const prefix = bytes.subarray(0, Math.min(bytes.length, 4096)).toString('utf8').replace(/^\uFEFF/, '').trimStart();
+  if (/^(?:<\?xml[^>]*>\s*)?<svg\b/i.test(prefix)) return 'image/svg+xml';
+  return null;
+}
+
+function declaredMimeForExtension(path: string): string | undefined {
+  return ({
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp',
+    '.tif': 'image/tiff', '.tiff': 'image/tiff', '.avif': 'image/avif',
+    '.heic': 'image/heic', '.heif': 'image/heic', '.svg': 'image/svg+xml',
+  } as Record<string, string | undefined>)[extname(path).toLowerCase()];
+}
+
+async function loadSharp() {
+  return (await import('sharp')).default;
+}
+
+async function decodeHeic(bytes: Buffer): Promise<Buffer> {
+  const imported = await import('heic-convert');
+  const convert = imported.default;
+  if (typeof convert !== 'function') throw new Error('HEIC 解码器未正确加载');
+  const output = await convert({ buffer: bytes, format: 'JPEG', quality: 0.92 });
+  return Buffer.from(output);
+}
+
+async function normalizeForModel(
+  bytes: Buffer,
+  detected: DetectedImageMime,
+  maxOutputBytes: number,
+): Promise<{ bytes: Buffer; mime: 'image/jpeg' | 'image/png' }> {
+  const sharp = await loadSharp();
+  const decoded = detected === 'image/heic' ? await decodeHeic(bytes) : bytes;
+  const image = sharp(decoded, { animated: false }).rotate().resize({
+    width: 4096,
+    height: 4096,
+    fit: 'inside',
+    withoutEnlargement: true,
+  });
+  const metadata = await image.metadata();
+  const preserveAlpha = metadata.hasAlpha === true || detected === 'image/svg+xml';
+  let output = preserveAlpha
+    ? await image.clone().png({ compressionLevel: 9 }).toBuffer()
+    : await image.clone().jpeg({ quality: 88, mozjpeg: true }).toBuffer();
+  if (output.length > maxOutputBytes && !preserveAlpha) {
+    output = await image.clone().jpeg({ quality: 75, mozjpeg: true }).toBuffer();
+  }
+  if (output.length > maxOutputBytes) {
+    throw new Error(`规范化后图片仍超过 ${(maxOutputBytes / 1024 / 1024).toFixed(0)}MB 上限`);
+  }
+  return { bytes: output, mime: preserveAlpha ? 'image/png' : 'image/jpeg' };
+}
+
+function modelMime(detected: DetectedImageMime): ResolvedLocalImage['mime'] | null {
+  return ['image/jpeg', 'image/png', 'image/gif', 'image/webp'].includes(detected)
+    ? detected as ResolvedLocalImage['mime']
+    : null;
+}
+
+export async function resolveLocalImage(
+  path: string,
+  options: { maxInputBytes?: number; maxOutputBytes?: number } = {},
+): Promise<ResolvedLocalImage> {
+  const info = await stat(path).catch((error: Error) => {
+    throw new Error(`无法读取图片：${path}（${error.message}）`);
+  });
+  if (!info.isFile()) throw new Error(`图片路径不是文件：${path}`);
+  const maxInputBytes = options.maxInputBytes ?? DEFAULT_MAX_IMAGE_INPUT_BYTES;
+  const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_MODEL_IMAGE_BYTES;
+  if (info.size > maxInputBytes) throw new Error(`图片超过 ${(maxInputBytes / 1024 / 1024).toFixed(0)}MB 输入上限：${path}`);
+  const bytes = await readFile(path);
+  const detected = detectImageMime(bytes);
+  if (!detected) {
+    const declared = declaredMimeForExtension(path);
+    throw new Error(
+      declared
+        ? `文件扩展名声明为 ${declared}，但内容不是可解码图片：${path}`
+        : `无法从文件内容识别图片格式：${path}`,
+    );
+  }
+  const declared = declaredMimeForExtension(path);
+  const diagnostic = declared && declared !== detected
+    ? `扩展名声明 ${declared}，实际内容为 ${detected}`
+    : undefined;
+  const directMime = modelMime(detected);
+  if (directMime && bytes.length <= maxOutputBytes) {
+    // Decode metadata once so truncated/corrupt files do not masquerade as images.
+    const sharp = await loadSharp();
+    const metadata = await sharp(bytes, { animated: detected === 'image/gif' }).metadata();
+    const needsOrientationFix = detected === 'image/jpeg' && (metadata.orientation ?? 1) > 1;
+    if (!needsOrientationFix) {
+      return {
+        originalPath: path,
+        path,
+        originalMime: detected,
+        mime: directMime,
+        size: bytes.length,
+        transformed: false,
+        ...(diagnostic ? { diagnostic } : {}),
+      };
+    }
+  }
+
+  const normalized = await normalizeForModel(bytes, detected, maxOutputBytes).catch((error) => {
+    throw new Error(`图片格式 ${detected} 无法规范化：${path}（${(error as Error).message}）`);
+  });
+  const hash = createHash('sha256')
+    .update(bytes)
+    .update('\0model-image-v1\0')
+    .update(normalized.mime)
+    .digest('hex');
+  const extension = normalized.mime === 'image/png' ? '.png' : '.jpg';
+  const dir = join(agentStateDir(), 'image-derivatives', hash.slice(0, 2));
+  const target = join(dir, `${hash}${extension}`);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const exists = await stat(target).then((item) => item.isFile()).catch(() => false);
+  if (!exists) {
+    const temp = `${target}.${randomUUID()}.tmp`;
+    await writeFile(temp, normalized.bytes, { mode: 0o600 });
+    await rename(temp, target).catch(async () => {
+      const wonRace = await stat(target).then((item) => item.isFile()).catch(() => false);
+      if (!wonRace) throw new Error(`无法保存图片派生文件：${target}`);
+    });
+  }
+  return {
+    originalPath: path,
+    path: target,
+    originalMime: detected,
+    mime: normalized.mime,
+    size: normalized.bytes.length,
+    transformed: true,
+    diagnostic: [diagnostic, `已规范化为 ${normalized.mime}`].filter(Boolean).join('；'),
+  };
+}
+
+export async function tryResolveLocalImage(path: string): Promise<ResolvedLocalImage | null> {
+  try {
+    return await resolveLocalImage(path);
+  } catch {
+    return null;
+  }
+}

package/src/infra/verification.js

@@ -28,7 +28,19 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { sanitizeCredentialEnv } from '../config/configService.js';
+import { CONFIG_LIMITS, normalizeLimited } from '../config/numericLimits.js';
 import { getWorkingDir } from '../bootstrap/workingDir.js';
+/**
+ * `shell:` 检查的默认超时——**唯一真值**。
+ *
+ * ⚠️ 这个数字此前在本文件里写了两份（`parseCheckString` 的构造处 + `runVerification`
+ * 的 `?? 30_000` 兜底），改一处漏一处就会出现「解析时 30s、执行时 60s」这种谁都看不出
+ * 的分裂。边界见 `config/numericLimits.ts::CONFIG_LIMITS.verifyShellTimeoutMs`。
+ *
+ * 为什么默认值不能太大：`verify()` 是工作流硬门，跑不完就阻塞整条流水线。
+ * 需要跑全量测试套件的场景应当缩到具体文件，或由调用方显式传 `defaultShellTimeoutMs`。
+ */
+export const DEFAULT_SHELL_CHECK_TIMEOUT_MS = 30_000;
 /** 从 "type:value" 字符串解析为 Check 对象。 */
 function parseVerifyArg(arg) {
     const colonIdx = arg.indexOf(':');
@@ -38,7 +50,10 @@ function parseVerifyArg(arg) {
     const value = arg.slice(colonIdx + 1).trim();
     switch (type) {
         case 'shell':
-            return { type: 'shell', command: value, timeout: 30_000 };
+            // ⚠️ 这里**不填** timeout：解析层只管语法，超时是策略、由 runVerification 决定。
+            // 曾经在这里写死 30_000，于是 `check.timeout ?? 默认值` 里的默认值永远走不到 ——
+            // 调用方传的超时被一个「解析时顺手填上的」值静默盖掉。
+            return { type: 'shell', command: value };
         case 'file_exists':
             return { type: 'file_exists', file: value };
         case 'file_contains': {
@@ -102,8 +117,18 @@ function runShell(command, timeout, cwd) {
     return new Promise((resolve) => {
         const isWin = process.platform === 'win32';
         const opts = { timeout, cwd, env: sanitizeCredentialEnv() };
+        // ⚠️ windowsVerbatimArguments: true 是必须的，不是可选优化：Node 给 cmd.exe/
+        // .bat 目标默认加一层它自己的参数转义（CVE-2024-27980 之后的安全加固），
+        // 会把 command 字符串里模型自己写好的转义（比如内嵌 PowerShell 单行脚本里的
+        // `\"..."`）再转义一遍，导致 cmd.exe 转交给子进程的字符串被改写、PowerShell
+        // 解析报 UnexpectedToken——文件内容明明字节级正确，check 却稳定失败。
+        // 已实测：一段合法的 `powershell -Command "...; Write-Host \"x\"; ..."`
+        // 不加这个选项必挂，加了立刻 exitCode 0；简单命令（echo/dir/bun --version）
+        // 行为不受影响。verify() 的 shell: 检查类型专供工作流的 hard_checks 使用，
+        // 命令来自可信的 LLM 契约草稿或用户输入，不是不可信的外部数据，
+        // 关掉这层转义不引入新的注入面。
         const child = isWin
-            ? spawn('cmd', ['/c', command], opts)
+            ? spawn('cmd', ['/c', command], { ...opts, windowsVerbatimArguments: true })
             : spawn('bash', ['-c', command], opts);
         let stdout = '';
         let stderr = '';
@@ -192,7 +217,8 @@ async function verifyTestCount(minCount, cwd = getWorkingDir()) {
  * 执行一组检查，返回聚合结果。
  * 全部通过 → passed=true；任一失败 → passed=false + summary 列出失败项。
  */
-export async function runVerification(checks, cwd = getWorkingDir()) {
+export async function runVerification(checks, cwd = getWorkingDir(), options = {}) {
+    const shellTimeout = normalizeLimited(options.defaultShellTimeoutMs, CONFIG_LIMITS.verifyShellTimeoutMs, DEFAULT_SHELL_CHECK_TIMEOUT_MS);
     if (checks.length === 0) {
         return { passed: true, details: [], summary: '无验证项' };
     }
@@ -201,7 +227,7 @@ export async function runVerification(checks, cwd = getWorkingDir()) {
         let result;
         switch (check.type) {
             case 'shell':
-                result = await verifyShell(check.command ?? '', check.timeout ?? 30_000, cwd);
+                result = await verifyShell(check.command ?? '', check.timeout ?? shellTimeout, cwd);
                 break;
             case 'file_exists':
                 result = verifyFileExists(check.file ?? '', cwd);
@@ -219,7 +245,10 @@ export async function runVerification(checks, cwd = getWorkingDir()) {
                     output: `未知验证类型: ${check.type}`,
                 };
         }
-        results.push(result);
+        // 回填**原始** check：各 verifier 只收散参（command/file/pattern），返回时会
+        // 自己重建一个残缺的 check 对象，把 timeout 这类字段丢掉。details 是给人排障和
+        // 给工作流做卡死指纹用的，它必须如实反映「这一条到底是按什么跑的」。
+        results.push({ ...result, check });
     }
     const allPassed = results.every((r) => r.passed);
     const failedNames = results.filter((r) => !r.passed).map((r) => formatCheckName(r.check));

package/src/infra/verification.ts

@@ -29,9 +29,22 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { sanitizeCredentialEnv } from '../config/configService.js';
+import { CONFIG_LIMITS, normalizeLimited } from '../config/numericLimits.js';
 
 import { getWorkingDir } from '../bootstrap/workingDir.js';
 
+/**
+ * `shell:` 检查的默认超时——**唯一真值**。
+ *
+ * ⚠️ 这个数字此前在本文件里写了两份（`parseCheckString` 的构造处 + `runVerification`
+ * 的 `?? 30_000` 兜底），改一处漏一处就会出现「解析时 30s、执行时 60s」这种谁都看不出
+ * 的分裂。边界见 `config/numericLimits.ts::CONFIG_LIMITS.verifyShellTimeoutMs`。
+ *
+ * 为什么默认值不能太大：`verify()` 是工作流硬门，跑不完就阻塞整条流水线。
+ * 需要跑全量测试套件的场景应当缩到具体文件，或由调用方显式传 `defaultShellTimeoutMs`。
+ */
+export const DEFAULT_SHELL_CHECK_TIMEOUT_MS = 30_000;
+
 export interface Check {
   type: 'shell' | 'file_contains' | 'file_exists' | 'test_count';
   command?: string;
@@ -63,7 +76,10 @@ function parseVerifyArg(arg: string): Check | null {
 
   switch (type) {
     case 'shell':
-      return { type: 'shell', command: value, timeout: 30_000 };
+      // ⚠️ 这里**不填** timeout：解析层只管语法，超时是策略、由 runVerification 决定。
+      // 曾经在这里写死 30_000，于是 `check.timeout ?? 默认值` 里的默认值永远走不到 ——
+      // 调用方传的超时被一个「解析时顺手填上的」值静默盖掉。
+      return { type: 'shell', command: value };
     case 'file_exists':
       return { type: 'file_exists', file: value };
     case 'file_contains': {
@@ -142,8 +158,18 @@ function runShell(
   return new Promise((resolve) => {
     const isWin = process.platform === 'win32';
     const opts = { timeout, cwd, env: sanitizeCredentialEnv() };
+    // ⚠️ windowsVerbatimArguments: true 是必须的，不是可选优化：Node 给 cmd.exe/
+    // .bat 目标默认加一层它自己的参数转义（CVE-2024-27980 之后的安全加固），
+    // 会把 command 字符串里模型自己写好的转义（比如内嵌 PowerShell 单行脚本里的
+    // `\"..."`）再转义一遍，导致 cmd.exe 转交给子进程的字符串被改写、PowerShell
+    // 解析报 UnexpectedToken——文件内容明明字节级正确，check 却稳定失败。
+    // 已实测：一段合法的 `powershell -Command "...; Write-Host \"x\"; ..."`
+    // 不加这个选项必挂，加了立刻 exitCode 0；简单命令（echo/dir/bun --version）
+    // 行为不受影响。verify() 的 shell: 检查类型专供工作流的 hard_checks 使用，
+    // 命令来自可信的 LLM 契约草稿或用户输入，不是不可信的外部数据，
+    // 关掉这层转义不引入新的注入面。
     const child = isWin
-      ? spawn('cmd', ['/c', command], opts)
+      ? spawn('cmd', ['/c', command], { ...opts, windowsVerbatimArguments: true })
       : spawn('bash', ['-c', command], opts);
 
     let stdout = '';
@@ -260,7 +286,13 @@ async function verifyTestCount(
 export async function runVerification(
   checks: Check[],
   cwd: string = getWorkingDir(),
+  options: { defaultShellTimeoutMs?: number } = {},
 ): Promise<VerifyResult> {
+  const shellTimeout = normalizeLimited(
+    options.defaultShellTimeoutMs,
+    CONFIG_LIMITS.verifyShellTimeoutMs,
+    DEFAULT_SHELL_CHECK_TIMEOUT_MS,
+  );
   if (checks.length === 0) {
     return { passed: true, details: [], summary: '无验证项' };
   }
@@ -274,7 +306,7 @@ export async function runVerification(
       case 'shell':
         result = await verifyShell(
           check.command ?? '',
-          check.timeout ?? 30_000,
+          check.timeout ?? shellTimeout,
           cwd,
         );
         break;
@@ -295,7 +327,10 @@ export async function runVerification(
         };
     }
 
-    results.push(result);
+    // 回填**原始** check：各 verifier 只收散参（command/file/pattern），返回时会
+    // 自己重建一个残缺的 check 对象，把 timeout 这类字段丢掉。details 是给人排障和
+    // 给工作流做卡死指纹用的，它必须如实反映「这一条到底是按什么跑的」。
+    results.push({ ...result, check });
   }
 
   const allPassed = results.every((r) => r.passed);