minimal-agent 0.11.0 → 0.13.0

package/plugins/workflow-runner/test/multimodal.test.ts

@@ -5,6 +5,7 @@
 
 import { describe, expect, it } from 'bun:test';
 
+import { ALL_TOOLS } from '../../../src/tools/index.js';
 import type {
   ChatContentPart,
   LlmStreamEvent,
@@ -16,7 +17,6 @@ import { execAgentStep } from '../src/stepExecutors/agent.js';
 import { execLlmStep } from '../src/stepExecutors/llm.js';
 import { VarStack } from '../src/types.js';
 import type { RunContext, StepDef } from '../src/types.js';
-import { ALL_TOOLS } from '../../../src/tools/index.js';
 
 const provider: Provider = {
   name: 'test',
@@ -72,7 +72,11 @@ describe('workflow-runner multimodal images', () => {
     const chat = async function* (): AsyncGenerator<LlmStreamEvent> {
       if (round++ === 0) {
         yield { type: 'tool_call_delta', index: 0, id: 'hidden', name: 'Bash' };
-        yield { type: 'tool_call_delta', index: 0, argumentsDelta: '{"command":"echo no"}' };
+        yield {
+          type: 'tool_call_delta',
+          index: 0,
+          argumentsDelta: '{"command":"echo no"}',
+        };
         yield { type: 'done', stopReason: 'tool_calls' };
         return;
       }
@@ -90,15 +94,58 @@ describe('workflow-runner multimodal images', () => {
         return { ok: true, content: 'unexpected' };
       },
     };
-    const result = await drain(execAgentStep(
-      { id: 'bounded', agent: '完成任务', allowed_tools: ['Bash'] },
-      new VarStack(),
-      ctx,
-    ));
+    const result = await drain(
+      execAgentStep(
+        { id: 'bounded', agent: '完成任务', allowed_tools: ['Bash'] },
+        new VarStack(),
+        ctx,
+      ),
+    );
     expect(executed).toBe(0);
     expect(result.raw.text).toBe('已改道。');
   });
 
+  it('an empty host tool catalog remains empty instead of restoring global tools', async () => {
+    let round = 0;
+    let executed = 0;
+    const chat = async function* (): AsyncGenerator<LlmStreamEvent> {
+      if (round++ === 0) {
+        yield { type: 'tool_call_delta', index: 0, id: 'hidden', name: 'Read' };
+        yield {
+          type: 'tool_call_delta',
+          index: 0,
+          argumentsDelta: '{"file_path":"README.md"}',
+        };
+        yield { type: 'done', stopReason: 'tool_calls' };
+        return;
+      }
+      yield { type: 'text_delta', delta: '没有可用工具。' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+    const ctx: RunContext = {
+      provider,
+      history: [{ role: 'system', content: 'stable' }],
+      cwd: process.cwd(),
+      tools: [],
+      chat,
+      executeTool: async () => {
+        executed += 1;
+        return { ok: true, content: 'unexpected' };
+      },
+    };
+
+    const result = await drain(
+      execAgentStep(
+        { id: 'empty-bound', agent: '完成任务', allowed_tools: ['Read'] },
+        new VarStack(),
+        ctx,
+      ),
+    );
+
+    expect(executed).toBe(0);
+    expect(result.raw.text).toBe('没有可用工具。');
+  });
+
   it('execLlmStep 把 images 传成 image_url content block，并支持变量插值', async () => {
     const captured: Message[][] = [];
     const ctx = createContext(captured);
@@ -195,7 +242,9 @@ describe('workflow-runner multimodal images', () => {
 
     expect(result.raw.text).toBe('图片可用');
     expect(messagesContainImage(captured[0])).toBe(true);
-    expect(ctx.history).toEqual([{ role: 'system', content: 'workflow system prompt' }]);
+    expect(ctx.history).toEqual([
+      { role: 'system', content: 'workflow system prompt' },
+    ]);
   });
 
   it('isolated 多模态步骤之后的普通 agent 不会收到前一步 image_url', async () => {
@@ -262,7 +311,7 @@ describe('workflow-runner multimodal images', () => {
       provider,
       history: [{ role: 'system', content: 'workflow system prompt' }],
       cwd: process.cwd(),
-      tools: [],
+      tools: ALL_TOOLS.filter((tool) => tool.name === 'Write'),
       chat,
       executeTool: async () => {
         toolCalled = true;
@@ -285,7 +334,9 @@ describe('workflow-runner multimodal images', () => {
 
     expect(toolCalled).toBe(true);
     expect(result.raw.text).toBe('文件已写好。');
-    expect(ctx.history).toEqual([{ role: 'system', content: 'workflow system prompt' }]);
+    expect(ctx.history).toEqual([
+      { role: 'system', content: 'workflow system prompt' },
+    ]);
     expect(captured.length).toBe(2);
   });
 });

package/plugins/workflow-runner/test/parseWorkflowArgs.test.ts

@@ -61,6 +61,25 @@ describe('parseWorkflowArgs / tokenizeArgs 边界行为冻结', () => {
     expect(r.inputs).toEqual({ topic: 'AI 教程' });
   });
 
+  test('引号在 = 后的 KV：value 含空格也完整捕获（回归：曾按空白硬切+引号残留）', () => {
+    // 用户 shell 习惯 `--input topic="带空格 的值"` —— 引号在 token 内部（= 之后），
+    // 曾被 tokenizeArgs 按空白切分 → 值截断 + 引号残留 + 散落 positional。
+    const r = parseWorkflowArgs(
+      'hello --input topic="比特币量化 长线 短线策略" --input depth=standard',
+    );
+    expect(r.inputs).toEqual({
+      topic: '比特币量化 长线 短线策略',
+      depth: 'standard',
+    });
+    expect(r.positional).toEqual([]);
+  });
+
+  test('单引号在 = 后同理支持', () => {
+    const r = parseWorkflowArgs("hello --input topic='AI 教程 入门'");
+    expect(r.inputs).toEqual({ topic: 'AI 教程 入门' });
+    expect(r.positional).toEqual([]);
+  });
+
   test('未知 -- flag 跳过其后一个 token（保守解析）', () => {
     const r = parseWorkflowArgs('hello --foo bar alice');
     // --foo bar 被吃掉，alice 进 positional

package/plugins/workflow-runner/test/ppt.load.test.ts

@@ -93,11 +93,11 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
       expect(String(s.title)).toContain('/22');
     }
 
-    // 收尾 echo；artifacts 只列最终交付物、不在被 rm 的 ./build 下
+    // 收尾 echo；artifacts 只列最终交付物、不在被 rm 的 out/ppt/${session}/build 下
     expect(def.steps.find((s) => s.id === 'final_report')?.type).toBe('echo');
     const declared = def.artifacts ?? [];
-    expect(declared).toContain('./out/deck.pptx');
-    for (const a of declared) expect(a.startsWith('./build')).toBe(false);
+    expect(declared).toContain('out/ppt/${session}/deck.pptx');
+    for (const a of declared) expect(a.startsWith('out/ppt/${session}/build')).toBe(false);
   });
 
   it('stage0_clarify：样式推荐按配色感知、覆盖全部 13 个 VI（不再只露 6 个）', async () => {
@@ -205,7 +205,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
 
     const repair = def.steps.find((s) => s.id === 'stage_draft_coverage_repair');
     expect(String(repair?.when)).toContain('draft_coverage_report.json');
-    expect(String(repair?.when)).toContain("readJson('./build/draft_coverage_report.json', 'ok') == false");
+    expect(String(repair?.when)).toContain("readJson('out/ppt/${session}/build/draft_coverage_report.json', 'ok') == false");
     // 用户点名最高优先级问题：fast/best 都要跑，when 不能限死 quality=='best'。
     expect(String(repair?.when)).not.toContain("quality == 'best'");
     expect(String(repair?.agent)).toContain('draft_coverage_report.md');
@@ -482,7 +482,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     // ① 摄取后跑确定性规划（在 design 之前，data 已齐）
     const ids = def.steps.map((s) => s.id);
     const am = def.steps.find((s) => s.id === 'stage_assemble_material');
-    expect(String(am?.args?.command)).toContain('plan_source_layout.py --build ./build');
+    expect(String(am?.args?.command)).toContain('plan_source_layout.py --build out/ppt/${session}/build');
     expect(ids.indexOf('stage_assemble_material')).toBeLessThan(ids.indexOf('stage_design_doc'));
 
     // ② 设计步「读规划、照它执行」——逐图心算被收成确定性
@@ -516,7 +516,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     expect(ga).toContain('--ensure-page-backgrounds');
     expect(ga).toContain('image_prompt_rewrite.py');
     expect(ga).toContain('image_plan_lint.py');
-    expect(ga).toContain('touch ./build/img_route_ok');
+    expect(ga).toContain('touch out/ppt/${session}/build/img_route_ok');
     // when 放宽：img_plan 存在 或 规划里有待增强图 —— 表达式可被引擎求值（不抛、不畸形）
     const whenExpr = String(gate?.when);
     expect(whenExpr).toContain('enhance_entries');
@@ -664,8 +664,8 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     expect(gen?.agent).toBeUndefined();
     expect(gen?.tool).toBe('GenerateImage');
     expect(gen?.tool).not.toBe('Bash');
-    expect(String(gen?.args?.plan)).toBe('./build/img_plan.json');
-    expect(String(gen?.args?.assets)).toBe('./build/assets');
+    expect(String(gen?.args?.plan)).toBe('out/ppt/${session}/build/img_plan.json');
+    expect(String(gen?.args?.assets)).toBe('out/ppt/${session}/build/assets');
     expect(String(gen?.args?.timeout_ms)).toBe('300000');
     expect(String(gen?.args?.wall_budget_ms)).toBe('3600000');
     expect(gen?.onError).toBe('continue');
@@ -673,7 +673,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     const quality = def.steps.find((s) => s.id === 'stage_image_quality_gate');
     expect(quality?.tool).toBe('GenerateImage');
     expect(String(quality?.when)).toContain('image_generation_report.json');
-    expect(String(quality?.args?.retry_degraded_report)).toBe('./build/image_generation_report.json');
+    expect(String(quality?.args?.retry_degraded_report)).toBe('out/ppt/${session}/build/image_generation_report.json');
     expect(String(quality?.title)).toContain('fast一轮');
     expect(quality?.args?.max_rounds).toBe(1);
 
@@ -705,7 +705,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     const imageRetry = def.steps.find((s) => s.id === 'stage_generated_image_retry');
     expect(imageRetry?.tool).toBe('GenerateImage');
     expect(String(imageRetry?.when)).toBe('false');
-    expect(String(imageRetry?.args?.retry_degraded_report)).toBe('./build/generated_image_semantic_retry_report.json');
+    expect(String(imageRetry?.args?.retry_degraded_report)).toBe('out/ppt/${session}/build/generated_image_semantic_retry_report.json');
     expect(String(imageRetry?.args?.max_rounds)).toBe('3');
 
     const visualGate = def.steps.find((s) => s.id === 'stage_visual_quality_gate');
@@ -753,7 +753,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     // 完全同参双跑、且视觉门达轮数已带残留放行）——style 检查唯一跑点在
     // stage_visual_quality_gate（fast/best 统一 2 轮修复），导出只验哨兵。
     expect(String(exp?.args?.command)).not.toContain('deck_visual_style_check.py');
-    expect(String(exp?.args?.command)).toContain('test -f ./build/visual_quality_ok');
+    expect(String(exp?.args?.command)).toContain('test -f out/ppt/${session}/build/visual_quality_ok');
     expect(exp?.done_when).toBeUndefined();
 
     const design = def.steps.find((s) => s.id === 'stage_design_doc');
@@ -829,7 +829,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     expect(String(probe?.args?.command)).toContain('build_probe.json');
     expect(String(probe?.args?.command)).toContain('build_complete');
     const batchStep = dos.find((s) => s.id === 'build_batch');
-    expect(String(batchStep?.when)).toContain("!fileExists('./build/build_complete')");
+    expect(String(batchStep?.when)).toContain("!fileExists('out/ppt/${session}/build/build_complete')");
     expect(batchStep?.maxTurns).toBeLessThanOrEqual(24);
     expect(batchStep?.max_retries).toBe(1);
     const batch = String(batchStep?.agent);
@@ -840,7 +840,7 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     expect(batch).toContain('次顶层'); // 插图图层：文本之下、背景之上
     expect(batch).toContain('遮挡');
     const done = dos.find((s) => s.id === 'build_done');
-    expect(String(done?.when)).toContain("fileExists('./build/build_complete')");
+    expect(String(done?.when)).toContain("fileExists('out/ppt/${session}/build/build_complete')");
   });
 
   it('fast 链路清理旧运行哨兵，且说明/报告顺序为先生图后构建', async () => {
@@ -866,12 +866,12 @@ describe('workflows/ppt.yaml（统一素材摄取·素材驱动）', () => {
     ]) {
       expect(cmd).toContain(marker);
     }
-    expect(cmd).toContain('rm -rf ./build/export ./build/generated-image-reviews');
+    expect(cmd).toContain('rm -rf out/ppt/${session}/build/export out/ppt/${session}/build/generated-image-reviews');
 
     const cleanup = def.steps.find((s) => s.id === 'cleanup_intermediates');
     const cleanupCmd = String(cleanup?.args?.command);
     expect(cleanupCmd).toContain('inputs.debug_keep_build');
-    expect(cleanupCmd).toContain('rm -rf ./build');
+    expect(cleanupCmd).toContain('rm -rf out/ppt/${session}/build');
     expect(cleanupCmd).toContain('debug_keep_build=true');
     expect(cleanupCmd).not.toContain('[TEMP]');
     expect(cleanupCmd).not.toContain('上线前');

package/plugins/workflow-runner/test/ralphLoop.e2e.test.ts

@@ -128,11 +128,12 @@ describe('ralph-loop.yaml 端到端（while + fresh_context + 哨兵协议）',
     expect(p2).not.toContain('我做了规划');
 
     // 教训档案恰好一条、不重复（iter1 无 learning 标签时 extract → '' 不得重复累积）
-    // 注意成功后状态目录被归档为 ralph-loop.done
+    // learnings 是 workflow 级共享存档，写在 ralph-loop/ 下（Phase 2 父目录不参与归档改名；
+    // 状态实例归档为 ralph-loop/<taskId>.done/）
     const learningsPath = join(
       tmp,
       '.minimal-agent-workflow',
-      'ralph-loop.done',
+      'ralph-loop',
       'learnings.md',
     );
     expect(existsSync(learningsPath)).toBe(true);

package/plugins/workflow-runner/test/research.load.test.ts

@@ -0,0 +1,328 @@
+/**
+ * test/research.load.test.ts
+ * ------------------------------------------------------------
+ * 锁定 workflows/research.yaml（技术研究工作流：定义问题→测绘地图→方案对比→
+ * 深度调研→动手验证→综合升华→补洞→报告拼装）的「可解析 + 关键骨架 + 所有表达式合法」。
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { join } from 'node:path';
+
+import { evalExpr, interpolate } from '../src/expressions.js';
+import { parseWorkflowFile } from '../src/loader.js';
+import { VarStack } from '../src/types.js';
+import type { StepDef } from '../src/types.js';
+
+const wfPath = join(
+  import.meta.dir.replace(/[/\\]test$/, ''),
+  '..',
+  '..',
+  'workflows',
+  'research.yaml',
+);
+
+function allStrings(def: unknown): string[] {
+  const out: string[] = [];
+  const walk = (v: unknown): void => {
+    if (typeof v === 'string') out.push(v);
+    else if (Array.isArray(v)) for (const x of v) walk(x);
+    else if (v && typeof v === 'object')
+      for (const x of Object.values(v as Record<string, unknown>)) walk(x);
+  };
+  walk(def);
+  return out;
+}
+
+function allStepsRec(steps: StepDef[]): StepDef[] {
+  const out: StepDef[] = [];
+  const go = (s: StepDef) => {
+    out.push(s);
+    if (Array.isArray(s.do)) s.do.forEach(go);
+    if (Array.isArray(s.then)) s.then.forEach(go);
+    if (Array.isArray(s.else)) s.else.forEach(go);
+  };
+  steps.forEach(go);
+  return out;
+}
+
+describe('workflows/research.yaml（技术研究工作流）', () => {
+  it('解析通过、name=research、inputs 正确', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    expect(def.name).toBe('research');
+    expect(typeof def.description).toBe('string');
+    expect(def.description.length).toBeGreaterThan(10);
+
+    const inputs = def.inputs ?? [];
+    const names = inputs.map((i) => i.name);
+    expect(names).toEqual(['topic', 'depth', 'max_iterations']);
+    expect(inputs[0].greedy).toBe(true);
+    expect(inputs[0].required).toBe(true);
+    expect(inputs[1].default).toBe('standard');
+    expect(inputs[2].default).toBe(2);
+  });
+
+  it('骨架齐全：init -> s0(goal) -> s0_pause -> s1(map) -> [early-exit 判定] -> s2(options) -> s3(per-branch 深挖 loop) -> s4(verify) -> s5(synthesis) -> s5b(补洞 loop) -> s6(拼装) -> done', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const ids = def.steps.map((s) => s.id);
+    const expectOrder = [
+      'init',
+      's0_goal',
+      's0_pause',
+      's1_map',
+      's1_load_exit',
+      's1_exit_report',
+      's2_options',
+      's2_load_branches',
+      's2_assert_branches',
+      's3_deep_dive',
+      's4_verify',
+      's5_synthesis',
+      's5b_loop',
+      's5c_check_synthesis',
+      's5c_assert_synthesis',
+      's6_build_report',
+      's6_package',
+      's6_assert_report',
+      'done',
+    ];
+    for (const id of expectOrder) expect(ids).toContain(id);
+    // 顺序
+    for (let i = 1; i < expectOrder.length; i++) {
+      expect(ids.indexOf(expectOrder[i - 1])).toBeLessThan(ids.indexOf(expectOrder[i]));
+    }
+  });
+
+  it('early-exit 双路径：s1_exit_report 在 _early_exit==true 时补齐全套文件；主阶段以 when=_early_exit != true 守卫跳过', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const byId = new Map(def.steps.map((s) => [s.id, s]));
+
+    const exitReport = byId.get('s1_exit_report');
+    expect(exitReport?.when).toBe('_early_exit == true');
+    // 简化路径必须补齐 s6 拼装所需的全部文件（done_when 锁定）
+    const dw = String(exitReport?.done_when);
+    for (const f of ['03-options.md', 'branches.json', '05-verification.md', '06-synthesis.md', '07-learning-debt.md', 'gaps.json']) {
+      expect(dw).toContain(f);
+    }
+
+    // 主阶段守卫：s2 / s4 / s5 / s5b 在 early-exit 时跳过
+    for (const id of ['s2_options', 's4_verify', 's5_synthesis', 's5b_loop']) {
+      expect(byId.get(id)?.when).toBe('_early_exit != true');
+    }
+    // assert 只在正常路径执行（early 路径 branches=[] 天然放行，无需弱化条件）
+    expect(byId.get('s2_assert_branches')?.when).toBe('_early_exit != true');
+    expect(String(byId.get('s2_assert_branches')?.condition)).toBe('length(branches) > 0');
+    // s1_map 的完成闸门包含 early-exit.json
+    expect(String(byId.get('s1_map')?.done_when)).toContain('early-exit.json');
+  });
+
+  it('阶段0 零搜索（设计文档红线）：allowed_tools 不含 WebSearch/WebFetch', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const s0 = def.steps.find((s) => s.id === 's0_goal');
+    const tools = (s0?.allowed_tools ?? []) as string[];
+    expect(tools).not.toContain('WebSearch');
+    expect(tools).not.toContain('WebFetch');
+    expect(tools).toEqual(['Read', 'Write']);
+  });
+
+  it('s5c 形式校验：确定性检查综合报告含必备章节（不依赖 agent 自觉）', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const check = def.steps.find((s) => s.id === 's5c_check_synthesis');
+    expect(check?.tool).toBe('Bash');
+    expect(String((check?.args as any)?.command)).toContain('grep');
+
+    const gate = def.steps.find((s) => s.id === 's5c_assert_synthesis');
+    expect(gate?.type).toBe('assert');
+    expect(String(gate?.condition)).toContain('核心结论');
+    expect(String(gate?.condition)).toContain('推荐方案');
+  });
+
+  it('s3_deep_dive：for-each loop over branches、fresh_context、done_when 用 + 拼路径', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const loop = def.steps.find((s) => s.id === 's3_deep_dive');
+    expect(loop?.type).toBe('loop');
+    expect(String(loop?.over)).toContain('branches');
+    expect(loop?.as).toBe('branch');
+    expect(loop?.fresh_context).toBe(true);
+
+    const dive = ((loop?.do ?? []) as StepDef[]).find((s) => s.id === 's3_dive_one');
+    expect(dive?.type).toBeUndefined(); // 不是控制流，是 agent 步
+    expect(typeof dive?.agent).toBe('string');
+    // allowed_tools 必须限制为只读调研工具
+    expect(dive?.allowed_tools).toEqual(
+      expect.arrayContaining(['WebSearch', 'WebFetch', 'Read', 'Write']),
+    );
+    // done_when 用 + 拼接路径
+    expect(String(dive?.done_when)).toContain('branch.safe_name');
+    expect(String(dive?.done_when)).toContain('+');
+  });
+
+  it('s5b_loop：while 模式（无 over）+ max_iterations=${inputs.max_iterations} + branch condition 判定缺口', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const loop = def.steps.find((s) => s.id === 's5b_loop');
+    expect(loop?.type).toBe('loop');
+    expect(loop?.over).toBeUndefined(); // while 模式
+    expect(String(loop?.max_iterations)).toContain('inputs.max_iterations');
+
+    const inner = (loop?.do ?? []) as StepDef[];
+    const brk = inner.find((s) => s.id === 's5b_break_if_empty');
+    expect(brk?.type).toBe('branch');
+    expect(String(brk?.condition)).toContain('length(_gaps)');
+    // then 里有 break
+    expect(((brk?.then ?? []) as StepDef[]).some((s) => s.type === 'break')).toBe(true);
+  });
+
+  it('s0_pause：真 HITL 闸门（free_text=approve，用户输入作为补充要求贯穿）', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const pause = def.steps.find((s) => s.id === 's0_pause');
+    expect(pause?.type).toBe('pause');
+    expect(pause?.free_text).toBe('approve');
+    expect(typeof pause?.prompt).toBe('string');
+  });
+
+  it('s6_build_report：确定性 Bash 拼装 out/research/${session}/deliverable/report.md（不烧 LLM），sec 降级标题，s6_package 精选脚本', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const build = def.steps.find((s) => s.id === 's6_build_report');
+    expect(build?.tool).toBe('Bash');
+    const cmd = String((build?.args as any)?.command);
+    // Phase 3：产物路径按 session 隔离（${session} 占位符由引擎展开）
+    expect(cmd).toContain('out/research/${session}/deliverable/report.md');
+    expect(cmd).toContain('sec out/research/${session}/01-goal.md');
+    expect(cmd).toContain('04-deep-dive');
+    expect(cmd).toContain("sed -E 's/^(#+) /\\1## /'");
+    expect((build?.artifacts ?? [])?.length).toBeGreaterThan(0);
+
+    const pkg = def.steps.find((s) => s.id === 's6_package');
+    expect(typeof pkg?.agent).toBe('string');
+    expect(String(pkg?.done_when)).toContain('deliverable/scripts/README.md');
+
+    const gate = def.steps.find((s) => s.id === 's6_assert_report');
+    expect(String(gate?.condition)).toContain('out/research/${session}/deliverable/report.md');
+  });
+
+  it('s6 Bash 转义与注入防线：\\$ 经引擎插值还原为 $（Bash 变量可展开）；自由文本 topic 不进命令体', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const build = def.steps.find((s) => s.id === 's6_build_report');
+    const rawCmd = String((build?.args as any)?.command);
+
+    // 注入防线：自由文本 inputs.topic 不得出现在任何 Bash 命令体里（enum 白名单的 depth 可以）
+    expect(rawCmd).not.toContain('${inputs.topic}');
+    const initCmd = String(
+      ((def.steps.find((s) => s.id === 'init')?.args as any) ?? {}).command,
+    );
+    expect(initCmd).not.toContain('${inputs.topic}');
+
+    // 转义还原：引擎 interpolate 把 \$ 还原为 $ 后再交给 Bash --
+    // \$f/\$OUT 必须被还原（否则 Bash 拿到字面 $f 文件名，deep-dive 拼装会静默空白）
+    const vars = new VarStack();
+    vars.setGlobal('inputs', { topic: 'T', depth: 'standard', max_iterations: 2 });
+    const out = interpolate(rawCmd, vars);
+    expect(out).not.toContain('\\$');
+    expect(out).toContain('$OUT');
+    expect(out).toContain('$f');
+  });
+
+  it('所有 tool: Bash 步骤的命令体都不触发 permanentDeleteGuard（包括注释里的示例代码）', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const bashSteps = def.steps.filter(
+      (s) => (s as any).tool === 'Bash',
+    );
+    expect(bashSteps.length).toBeGreaterThan(0);
+
+    // 逐行匹配 permanentDeleteGuard 的 BASH_DELETE 正则：
+    //   /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i
+    //   /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\b/i
+    const delPatterns = [
+      /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i,
+      /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\b/i,
+    ];
+    for (const step of bashSteps) {
+      const cmd = String(((step as any).args as any).command ?? '');
+      for (const pat of delPatterns) {
+        if (pat.test(cmd)) {
+          throw new Error(
+            `步骤 ${step.id} 的 Bash 命令体命中了 permanentDeleteGuard 正则 ${pat.toString()}`,
+          );
+        }
+      }
+    }
+  });
+
+  it('所有 ${} 模板插值和裸表达式都能被引擎求值（不抛错）', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const vars = new VarStack();
+    vars.setGlobal('inputs', {
+      topic: 'Rust 异步运行时',
+      depth: 'standard',
+      max_iterations: 2,
+    });
+    vars.setGlobal('branches', [
+      { name: 'Tokio', safe_name: 'tokio', description: '主流' },
+      { name: 'async-std', safe_name: 'async-std', description: '另一个' },
+    ]);
+    vars.setGlobal('_gaps', []);
+    vars.setGlobal('_init_out', 'init_ok');
+    vars.setGlobal('session', 'default');
+    vars.setGlobal('_report_out', 'ok:out/research/${session}/deliverable/report.md');
+    vars.setIteration('branch', { name: 'Tokio', safe_name: 'tokio', description: '主流' });
+    vars.setIteration('branch_idx', 0);
+    vars.setIteration('_iter', 0);
+    vars.setIteration('_iter_idx', 0);
+
+    // 模板插值
+    for (const s of allStrings(def)) {
+      if (!s.includes('${')) continue;
+      expect(() => interpolate(s, vars)).not.toThrow(
+        `字符串插值失败: ${s.slice(0, 200)}`,
+      );
+    }
+
+    // 裸表达式：when / condition / over / done_when / set 值 / max_iterations
+    const naked: Array<[string, string]> = [];
+    for (const s of allStepsRec(def.steps)) {
+      if (s.when) naked.push([`${s.id}.when`, s.when]);
+      if (s.condition) naked.push([`${s.id}.condition`, s.condition]);
+      if (typeof s.over === 'string') naked.push([`${s.id}.over`, s.over]);
+      if (s.done_when) naked.push([`${s.id}.done_when`, s.done_when]);
+      if (typeof s.max_iterations === 'string')
+        naked.push([`${s.id}.max_iterations`, s.max_iterations]);
+      for (const [k, v] of Object.entries(s.set ?? {})) {
+        if (typeof v === 'string' && v.startsWith('${') && v.endsWith('}')) {
+          naked.push([`${s.id}.set.${k}`, v.slice(2, -1)]);
+        }
+      }
+    }
+    for (const [loc, expr] of naked) {
+      expect(() => evalExpr(expr, vars)).not.toThrow(
+        `表达式失败 [${loc}]: ${expr}`,
+      );
+    }
+  });
+
+  it('补洞收敛可见化：s5b_final_gaps 恒执行（无 when），done 按剩余缺口数分流提示', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const steps = allStepsRec(def.steps);
+
+    // s5b_final_gaps 无 when 守卫：early-exit 路径也执行（gaps.json=[] 由 s1_exit_report 补齐），
+    // 保证 done 引用的 _remaining_gaps 恒有定义
+    const fg = steps.find((s) => s.id === 's5b_final_gaps');
+    expect(fg).toBeDefined();
+    expect(fg?.when).toBeUndefined();
+    expect(String(fg?.set?._remaining_gaps)).toContain("readJson('out/research/${session}/gaps.json')");
+
+    // done 消息按 _remaining_gaps 分流：>0 警告剩余缺口，=0 报告收敛
+    const done = steps.find((s) => s.id === 'done');
+    const msg = String(done?.message);
+    expect(msg).toContain('_remaining_gaps > 0');
+    expect(msg).toContain('缺口未补全');
+    expect(msg).toContain('已全部收敛');
+
+    // 三元插值在两种取值下都能求值（模拟 done 执行）
+    const vars = new VarStack();
+    vars.setGlobal('inputs', { topic: 'T', depth: 'light', max_iterations: 1 });
+    const ternary = '_remaining_gaps > 0 ? \'⚠️ 仍有 \' + _remaining_gaps + \' 条缺口\' : \'✅ 收敛\'';
+    vars.setGlobal('_remaining_gaps', 3);
+    expect(evalExpr(ternary, vars)).toContain('3 条缺口');
+    vars.setGlobal('_remaining_gaps', 0);
+    expect(evalExpr(ternary, vars)).toContain('收敛');
+  });
+});