minimal-agent 0.13.0 → 0.14.0

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

@@ -1,237 +1,346 @@
 /**
- * ============================================================
- *  test/taskIdentity.test.ts —— 任务身份判定单元测试
- * ------------------------------------------------------------
- *  覆盖 taskIdentity.ts 的所有核心功能：
- *    - computeTaskId() hash 计算
- *    - 时间窗口判定（30分钟内视为同任务）
- *    - 任务身份匹配逻辑（hash_match / time_window / expired / different_workflow）
- *    - normalizeGoal() 归一化规则
- *    - extractGoal() 提取策略
+ * plugins/workflow-runner/test/taskIdentity.test.ts —— 任务身份与状态目录布局
  *
- *  设计原则：
- *    - 不依赖文件系统（computeTaskId 在无 workingDir 时返回 no_previous）
- *    - 需要文件系统时用 tmpdir + 手写 current.json
- *    - 纯函数逻辑用大量边界用例覆盖
- * ============================================================
+ * 这组测试的核心是**四级布局的三个并存需求**（见 taskIdentity.ts 头注）：
+ *   同 session 同 goal → 同目录（能 resume）
+ *   同 session 换主题 → 不同目录（不覆盖）
+ *   不同 session      → 不同目录（能并行）
+ *
+ * legacy 曾把这三条压进两级布局，反复顾此失彼：Phase 2 用 taskId 层解决了「不覆盖」，
+ * Phase 3 把那一层**换成** sessionId 换来了「并行」，「不覆盖」就丢了；补偿方案
+ * （宿主没给 session 就自动生成带时间戳的）又让「能 resume」也丢了 —— 时间每次都变，
+ * 于是每次运行都是新 session。下面「三者并存」那一组就是钉这段历史的。
  */
 
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import { buildGoalAnchor } from '../src/goalAnchor.js';
+import {
+  DEFAULT_SESSION_ID,
+  WF_STATE_DIR_ENV,
+  buildTaskArbitrator,
+  computeTaskId,
+  extractGoal,
+  isContinuationPhrase,
+  resolveStateRoot,
+  sanitizeWorkflowDirName,
+  sessionStateDir,
+  taskInstanceDir,
+} from '../src/taskIdentity.js';
 
-import { computeTaskId } from '../src/taskIdentity.js';
+const WD = process.platform === 'win32' ? 'D:\\work' : '/work';
 
-describe('taskIdentity::normalizeGoal (隐式测试 via computeTaskId)', () => {
-  it('相同内容产生相同 hash（确定性）', () => {
-    const r1 = computeTaskId('test-wf', { goal: 'hello world' });
-    const r2 = computeTaskId('test-wf', { goal: 'hello world' });
-    expect(r1.hash).toBe(r2.hash);
-    expect(r1.hash.length).toBe(16);
+describe('状态目录布局', () => {
+  const savedEnv = process.env[WF_STATE_DIR_ENV];
+  afterEach(() => {
+    if (savedEnv === undefined) delete process.env[WF_STATE_DIR_ENV];
+    else process.env[WF_STATE_DIR_ENV] = savedEnv;
   });
 
-  it('不同内容产生不同 hash（碰撞敏感度）', () => {
-    const r1 = computeTaskId('test-wf', { goal: '目标A' });
-    const r2 = computeTaskId('test-wf', { goal: '目标B' });
-    expect(r1.hash).not.toBe(r2.hash);
+  test('默认落在 cwd 下的 .minimal-agent-workflow/', () => {
+    delete process.env[WF_STATE_DIR_ENV];
+    expect(resolveStateRoot(WD)).toContain('.minimal-agent-workflow');
   });
 
-  it('大小写不敏感（归一化转小写）', () => {
-    const r1 = computeTaskId('test-wf', { goal: 'Hello World' });
-    const r2 = computeTaskId('test-wf', { goal: 'hello world' });
-    expect(r1.hash).toBe(r2.hash);
+  test('环境变量指定的全局目录优先', () => {
+    process.env[WF_STATE_DIR_ENV] = WD;
+    expect(resolveStateRoot('/somewhere/else')).toBe(WD);
   });
 
-  it('标点符号被去除', () => {
-    const r1 = computeTaskId('test-wf', { goal: 'Hello, World!' });
-    const r2 = computeTaskId('test-wf', { goal: 'hello world' });
-    expect(r1.hash).toBe(r2.hash);
+  test('目录名清洗：非 [字母数字._-] 一律换成 -', () => {
+    expect(sanitizeWorkflowDirName('my flow/v2:x')).toBe('my-flow-v2-x');
   });
 
-  it('多余空格被压缩', () => {
-    const r1 = computeTaskId('test-wf', { goal: 'hello   world' });
-    const r2 = computeTaskId('test-wf', { goal: 'hello world' });
-    expect(r1.hash).toBe(r2.hash);
+  test('实例目录是四级：workflow / session / taskId', () => {
+    const dir = taskInstanceDir(WD, 'ppt', 'sess-a', 'abc123');
+    expect(dir).toContain('ppt');
+    expect(dir).toContain('sess-a');
+    expect(dir.endsWith('abc123')).toBe(true);
+    // taskId 目录必须在 session 目录之内，不是它的兄弟
+    expect(dir.startsWith(sessionStateDir(WD, 'ppt', 'sess-a'))).toBe(true);
   });
+});
+
+describe('★ 三个需求必须并存（四级布局的存在理由）', () => {
+  const dirFor = (session: string, goal: string): string =>
+    taskInstanceDir(
+      WD,
+      'research',
+      session,
+      computeTaskId('research', { goal }),
+    );
 
-  it('中文保留正常', () => {
-    const r = computeTaskId('test-wf', { goal: '实现用户认证模块' });
-    expect(r.hash.length).toBe(16);
-    // 中文不应被去除
-    expect(r.hash).toMatch(/^[0-9a-f]{16}$/);
+  test('同 session + 同 goal → 同一个目录（resume 才够得着）', () => {
+    expect(dirFor('s1', '调研 A 主题')).toBe(dirFor('s1', '调研 A 主题'));
   });
 
-  it('超长输入被截断到 200 字符', () => {
-    const longGoal = 'a'.repeat(300);
-    const r1 = computeTaskId('test-wf', { goal: longGoal });
-    const r2 = computeTaskId('test-wf', { goal: 'a'.repeat(200) });
-    expect(r1.hash).toBe(r2.hash);
+  test('★ 同 session + 换主题 → 不同目录（连续研究不同内容不互相覆盖）', () => {
+    expect(dirFor('s1', '调研 A 主题')).not.toBe(dirFor('s1', '调研 B 主题'));
   });
 
-  it('首尾空格被 trim', () => {
-    const r1 = computeTaskId('test-wf', { goal: '  hello world  ' });
-    const r2 = computeTaskId('test-wf', { goal: 'hello world' });
-    expect(r1.hash).toBe(r2.hash);
+  test('不同 session + 同 goal → 不同目录（并行隔离）', () => {
+    expect(dirFor('s1', '调研 A 主题')).not.toBe(dirFor('s2', '调研 A 主题'));
+  });
+
+  test('★ default session 也照常工作，不被替换成带时间戳的名字', () => {
+    // legacy 在这里自动生成 `YYYYMMDD-HHmmss-xxxxxx`，导致每次运行都是新 session、
+    // resume/completed 永远够不着。四级布局下没有这个必要，也绝不能加回来。
+    const a = dirFor(DEFAULT_SESSION_ID, '同一个目标');
+    const b = dirFor(DEFAULT_SESSION_ID, '同一个目标');
+    expect(a).toBe(b);
+    expect(a).toContain(DEFAULT_SESSION_ID);
   });
 });
 
-describe('taskIdentity::extractGoal 策略', () => {
-  it('优先级1：直接使用 inputs.goal', () => {
-    const r1 = computeTaskId('wf', { goal: '我的目标', other: '忽略这个' });
-    const r2 = computeTaskId('wf', { goal: '我的目标', other: '不同的值' });
-    expect(r1.hash).toBe(r2.hash); // 只看 goal
+describe('computeTaskId', () => {
+  test('纯函数：同输入恒等，不读盘不看时间', () => {
+    const a = computeTaskId('w', { goal: 'x' });
+    const b = computeTaskId('w', { goal: 'x' });
+    expect(a).toBe(b);
+    expect(a).toHaveLength(16);
+  });
+
+  test('工作流名参与哈希 —— 不同工作流的同一目标不是同一个任务', () => {
+    expect(computeTaskId('a', { goal: 'x' })).not.toBe(
+      computeTaskId('b', { goal: 'x' }),
+    );
   });
 
-  it('优先级2：无 goal 时取第一个 length > 2 的 string 值', () => {
-    const r1 = computeTaskId('wf', { short: 'ab', description: '这是一个较长的描述' });
-    // 应该取 description（length > 2），而不是 short
-    const r2 = computeTaskId('wf', { description: '这是一个较长的描述' });
-    expect(r1.hash).toBe(r2.hash);
+  test.each([
+    ['大小写', '调研 Foo', '调研 foo'],
+    ['尾部标点', '调研 foo！！！', '调研 foo'],
+    ['连续空格', '调研   foo', '调研 foo'],
+    ['首尾空白', '  调研 foo  ', '调研 foo'],
+  ])('归一化消除无意义差异：%s', (_label, a, b) => {
+    expect(computeTaskId('w', { goal: a })).toBe(
+      computeTaskId('w', { goal: b }),
+    );
   });
 
-  it('优先级3：所有 string 都太短时 JSON 序列化整个 inputs', () => {
-    const r1 = computeTaskId('wf', { a: 'x', b: 'y' });
-    const r2 = computeTaskId('wf', { a: 'x', b: 'y' });
-    expect(r1.hash).toBe(r2.hash); // 确定性
-    expect(r1.hash.length).toBe(16);
+  test('标点是被【删除】而不是换成空格 —— 记录真实边界，别想当然', () => {
+    // `调研：foo` 归一化成 `调研foo`（不含空格），因此它与 `调研 foo` **不**同任务。
+    // 对中日韩文本这样处理没问题（本就不用空格分词），但拉丁文本里
+    // `foo,bar` 会并成 `foobar`。这是自 legacy 原样移植的行为，不在本次改动范围内；
+    // 真要改，得先想清楚它会让所有既有 taskId 全部变化。
+    expect(computeTaskId('w', { goal: '调研：foo' })).toBe(
+      computeTaskId('w', { goal: '调研foo' }),
+    );
+    expect(computeTaskId('w', { goal: '调研：foo' })).not.toBe(
+      computeTaskId('w', { goal: '调研 foo' }),
+    );
   });
 
-  it('空 inputs 也能处理', () => {
-    const r = computeTaskId('wf', {});
-    expect(r.hash.length).toBe(16);
+  test('★ 语义不同就是不同任务 —— 时间窗口不得覆盖内容差异', () => {
+    // legacy 早期「30 分钟内视为同一任务」是 bug：半小时内换个完全不同的目标
+    // 重跑，会 resume 旧任务并把旧变量混进新目标。已移除，别加回来。
+    expect(computeTaskId('w', { goal: '写一份 PPT' })).not.toBe(
+      computeTaskId('w', { goal: '修一个 bug' }),
+    );
   });
 
-  it('非 string 值被跳过（number/boolean/null）', () => {
-    const r1 = computeTaskId('wf', { count: 42, flag: true });
-    const r2 = computeTaskId('wf', {});
-    // 没有可用的 string → 都走 JSON.stringify
-    // 但序列化结果不同，所以 hash 不同是正常的
-    expect(r1.hash.length).toBe(16);
-    expect(r2.hash.length).toBe(16);
+  test('★ 同一句请求配不同附件内容必须是不同任务', () => {
+    const defs = [
+      { name: 'source', type: 'resource' as const, required: true },
+    ];
+    const base = {
+      source: '/runtime/paper.jpg',
+      requestText: '帮我整理成 Word',
+    };
+    expect(
+      computeTaskId(
+        'wrong-question-docx',
+        { ...base, __resource_fingerprint: 'source:sha-a' },
+        defs,
+      ),
+    ).not.toBe(
+      computeTaskId(
+        'wrong-question-docx',
+        { ...base, __resource_fingerprint: 'source:sha-b' },
+        defs,
+      ),
+    );
+    expect(
+      buildGoalAnchor(
+        { ...base, __resource_fingerprint: 'source:sha-a' },
+        defs,
+      ),
+    ).toContain('帮我整理成 Word');
   });
-});
 
-describe('taskIdentity::无 workingDir 基础行为', () => {
-  it('无 workingDir → isSameTask=false, reason=no_previous', () => {
-    const r = computeTaskId('test-wf', { goal: 'hello' });
-    expect(r.isSameTask).toBe(false);
-    expect(r.reason).toBe('no_previous');
+  test('超长 goal 截断到 200 字 —— 靠后的细微差异不该分裂同一件事', () => {
+    const base = '主'.repeat(200);
+    expect(computeTaskId('w', { goal: `${base}甲` })).toBe(
+      computeTaskId('w', { goal: `${base}乙` }),
+    );
   });
 
-  it('不同 workflow 名产生不同 hash', () => {
-    const r1 = computeTaskId('wf-a', { goal: 'same goal' });
-    const r2 = computeTaskId('wf-b', { goal: 'same goal' });
-    expect(r1.hash).not.toBe(r2.hash); // workflow 名参与 hash
+  test('资源工作流相同输入不同处理参数不能命中旧completed', () => {
+    const defs = [
+      { name: 'source', type: 'resource' as const, required: true },
+      {
+        name: 'format',
+        type: 'enum' as const,
+        values: ['pdf', 'docx'],
+        default: 'pdf',
+      },
+      { name: 'range' },
+    ];
+    const base = {
+      source: '/runtime/image.png',
+      requestText: '转换文件',
+      __resource_fingerprint: 'same-bytes',
+      format: 'pdf',
+    };
+    expect(computeTaskId('converter', { ...base, range: '1' }, defs)).not.toBe(
+      computeTaskId('converter', { ...base, range: '2' }, defs),
+    );
+    expect(computeTaskId('converter', base, defs)).not.toBe(
+      computeTaskId('converter', { ...base, format: 'docx' }, defs),
+    );
+    expect(computeTaskId('converter', base, defs)).toBe(
+      computeTaskId(
+        'converter',
+        { ...base, source: '/another/staged.png' },
+        [...defs].reverse(),
+      ),
+    );
   });
 });
 
-describe('taskIdentity::文件系统交互（时间窗口 + hash 匹配）', () => {
-  let tmp: string;
+describe('extractGoal', () => {
+  test('显式 goal 优先', () => {
+    expect(extractGoal({ topic: '别的', goal: '真目标' })).toBe('真目标');
+  });
 
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), 'task-id-'));
+  test('无 goal 时优先取作者标了 required 的输入', () => {
+    // 作者用 required 表达了「这是主要输入」，比「第一个碰到的字符串」可靠得多
+    expect(
+      extractGoal({ lang: 'zh', topic: '调研主题' }, [
+        { name: 'lang' },
+        { name: 'topic', required: true },
+      ]),
+    ).toBe('调研主题');
   });
 
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  function writeCurrentState(data: {
-    taskId?: string;
-    name?: string;
-    startedAt?: string;
-    status?: string;
-  }): void {
-    // E6 后状态目录按 workflow 名隔离：computeTaskId('test-wf', …) 读 test-wf/ 子目录
-    const stateDir = join(tmp, '.minimal-agent-workflow', 'test-wf');
-    mkdirSync(stateDir, { recursive: true });
-    writeFileSync(
-      join(stateDir, 'current.json'),
-      JSON.stringify(data, null, 2),
-      'utf8',
-    );
-  }
+  test('没有 required 声明时退到第一个非空字符串', () => {
+    expect(extractGoal({ n: 5, topic: '主题' })).toBe('主题');
+  });
 
-  it('无 current.json → no_previous', () => {
-    const r = computeTaskId('test-wf', { goal: 'hello' }, tmp);
-    expect(r.isSameTask).toBe(false);
-    expect(r.reason).toBe('no_previous');
+  test('★ 两个字的中文目标必须取到 —— 曾被 >2 的长度阈值跳过', () => {
+    // 那条阈值是照拉丁文本想的（跳过 ab、语言代码），对中文直接失效：
+    // `世界`、`调研` 这种目标会被跳过去落到 JSON 兜底，于是 current.json 里
+    // 记的目标变成一坨 JSON、仲裁时喂给 LLM 的也是那坨 JSON。端到端实跑复现过。
+    expect(extractGoal({ name: '世界' })).toBe('世界');
+    expect(extractGoal({ name: '世界', times: 3 })).not.toContain('{');
   });
 
-  it('不同 workflow 名 → different_workflow', () => {
-    writeCurrentState({
-      name: 'other-wf',
-      taskId: 'abc123',
-      startedAt: new Date().toISOString(),
-    });
-    const r = computeTaskId('test-wf', { goal: 'hello' }, tmp);
-    expect(r.isSameTask).toBe(false);
-    expect(r.reason).toBe('different_workflow');
+  test('全是非字符串 → 回退整体 JSON（保证恒有确定值）', () => {
+    expect(extractGoal({ pages: 12 })).toBe('{"pages":12}');
   });
 
-  it('时间窗口内但 goal 不同 → 仍判不同任务（hash 权威，recency 不覆盖）', () => {
-    // 刚刚启动的任务，但这次换了完全不同的 goal
-    writeCurrentState({
-      name: 'test-wf',
-      taskId: 'old-hash',
-      startedAt: new Date().toISOString(),
-    });
-    const r = computeTaskId('test-wf', { goal: '完全不同的新目标' }, tmp);
-    // 30 分钟内换不同 goal 必须当成全新任务（需求 3.2「不相关新任务自动清理重开」），
-    // 而非旧版「时间窗口覆盖 hash」错误 resume 旧任务把旧变量混进新目标。
-    expect(r.isSameTask).toBe(false);
-    expect(r.reason).toBe('hash_diff');
-    expect(r.hash).not.toBe('old-hash');
-  });
-
-  it('时间窗口过期 + hash 匹配 → hash_match', () => {
-    // 31 分钟前启动的任务（超出 30 分钟窗口）
-    const pastDate = new Date(Date.now() - 31 * 60 * 1000);
-    const expectedHash = computeTaskId('test-wf', { goal: 'same goal' }).hash;
-
-    writeCurrentState({
-      name: 'test-wf',
-      taskId: expectedHash,
-      startedAt: pastDate.toISOString(),
+  test('★ 与 buildGoalAnchor 共用同一份规则（两处分家会让身份与锚指向不同目标）', () => {
+    const inputs = { lang: 'zh', topic: '调研主题' };
+    const defs = [{ name: 'lang' }, { name: 'topic', required: true }];
+    expect(buildGoalAnchor(inputs, defs)).toContain(extractGoal(inputs, defs));
+  });
+});
+
+describe('isContinuationPhrase', () => {
+  test.each(['继续', '继续吧', '接着做', 'continue', 'RESUME', '继续  执行'])(
+    '「%s」是延续指令',
+    (s) => {
+      expect(isContinuationPhrase(s)).toBe(true);
+    },
+  );
+
+  test.each(['写一份关于继续教育的报告', '调研 A 主题', ''])(
+    '「%s」不是延续指令',
+    (s) => {
+      expect(isContinuationPhrase(s)).toBe(false);
+    },
+  );
+
+  test('★ 长句里出现「继续」二字不算延续指令（否则会误 resume 掉真正的新任务）', () => {
+    expect(isContinuationPhrase('继续教育政策的调研报告怎么写')).toBe(false);
+  });
+});
+
+describe('任务仲裁链', () => {
+  const actx = {
+    workflowName: 'research',
+    prevGoal: '调研 A 主题',
+    newGoal: '继续',
+    completedCalls: 7,
+    artifacts: ['out/a.md'],
+  };
+  const provider = { name: 'test' } as never;
+
+  /** 造一个只吐固定文本的 chat stub（DI，不用 mock.module）。 */
+  const chatStub = (text: string) =>
+    async function* () {
+      yield { type: 'text_delta' as const, delta: text };
+    };
+
+  test('a. 延续短语走快路径，不花 LLM', async () => {
+    let llmCalled = false;
+    const arb = buildTaskArbitrator({
+      provider,
+      chat: (() => {
+        llmCalled = true;
+        return chatStub('{"verdict":"new"}')();
+      }) as never,
     });
-    const r = computeTaskId('test-wf', { goal: 'same goal' }, tmp);
-    expect(r.isSameTask).toBe(true);
-    expect(r.reason).toBe('hash_match');
+    expect(await arb(actx)).toBe('resume');
+    expect(llmCalled).toBe(false);
   });
 
-  it('hash 不匹配 → 不同任务（hash_diff，与时间无关）', () => {
-    const pastDate = new Date(Date.now() - 31 * 60 * 1000);
-    writeCurrentState({
-      name: 'test-wf',
-      taskId: 'some-old-hash',
-      startedAt: pastDate.toISOString(),
+  test('b. LLM 给出明确判定就采纳', async () => {
+    const arb = buildTaskArbitrator({
+      provider,
+      chat: chatStub('{"verdict":"new","reason":"无关"}') as never,
     });
-    const r = computeTaskId('test-wf', { goal: 'completely new target' }, tmp);
-    expect(r.isSameTask).toBe(false);
-    expect(r.reason).toBe('hash_diff');
+    expect(await arb({ ...actx, newGoal: '换个完全不同的题目' })).toBe('new');
   });
 
-  it('损坏的 current.json → 容错返回 no_previous', () => {
-    const stateDir = join(tmp, '.minimal-agent-workflow', 'test-wf');
-    mkdirSync(stateDir, { recursive: true });
-    writeFileSync(join(stateDir, 'current.json'), '{invalid json', 'utf8');
+  test('LLM 输出被 markdown 代码块包着也能解析', async () => {
+    const arb = buildTaskArbitrator({
+      provider,
+      chat: chatStub('```json\n{"verdict":"resume"}\n```') as never,
+    });
+    expect(await arb({ ...actx, newGoal: '把它做完，另外改成 12 页' })).toBe(
+      'resume',
+    );
+  });
 
-    const r = computeTaskId('test-wf', { goal: 'hello' }, tmp);
-    expect(r.isSameTask).toBe(false);
-    expect(r.reason).toBe('no_previous');
+  test('c. LLM 说 unsure → 降级问用户', async () => {
+    const arb = buildTaskArbitrator({
+      provider,
+      chat: chatStub('{"verdict":"unsure"}') as never,
+      executeTool: (async () => ({
+        ok: true,
+        content: 'A1: 继续上次任务',
+      })) as never,
+    });
+    expect(await arb({ ...actx, newGoal: '别的' })).toBe('resume');
   });
 
-  it('current.json 缺少 startedAt 字段 → 降级为 hash 比较', () => {
-    const expectedHash = computeTaskId('test-wf', { goal: 'target' }).hash;
-    writeCurrentState({
-      name: 'test-wf',
-      taskId: expectedHash,
-      // 没有 startedAt
+  test('★ d. 全都不可用 → 兜底 new，绝不 halt 工作流', async () => {
+    // 仲裁只是个辅助判断。让它有能力中断整条工作流是本末倒置。
+    const boom = () => {
+      throw new Error('不可用');
+    };
+    const arb = buildTaskArbitrator({
+      provider,
+      chat: boom as never,
+      executeTool: boom as never,
     });
-    const r = computeTaskId('test-wf', { goal: 'target' }, tmp);
-    // 无 startedAt 时时间窗口检查不通过，走 hash 匹配
-    expect(r.isSameTask).toBe(true);
-    expect(r.reason).toBe('hash_match');
+    expect(await arb({ ...actx, newGoal: '别的' })).toBe('new');
+  });
+
+  test('仲裁过程留下人话记录（用户要看得见为什么这么判）', async () => {
+    const notes: string[] = [];
+    const arb = buildTaskArbitrator({ provider, notes });
+    await arb(actx);
+    expect(notes.join('\n')).toContain('延续短语');
   });
 });

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

@@ -0,0 +1,106 @@
+import { expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { workflowFingerprint } from '../src/workflowFingerprint.js';
+import { WorkflowState } from '../src/workflowState.js';
+
+test('bundle changes invalidate resume AND completed; output changes do not', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'wf-fingerprint-'));
+  try {
+    await mkdir(join(dir, 'scripts'));
+    await mkdir(join(dir, 'prompts'));
+    await writeFile(join(dir, 'scripts', 'helper.mjs'), 'v1');
+    const source = 'echo("ok")';
+    const before = await workflowFingerprint(source, dir);
+    const state = new WorkflowState(dir, 'test', 'session');
+    await state.init({ goal: 'same' }, before, []);
+    await state.markDone([]);
+    await state.archive();
+    expect(
+      (
+        await new WorkflowState(dir, 'test', 'session').init(
+          { goal: 'same' },
+          before,
+          [],
+        )
+      ).mode,
+    ).toBe('completed');
+    await writeFile(join(dir, 'scripts', 'helper.mjs'), 'v2');
+    const after = await workflowFingerprint(source, dir);
+    expect(after).not.toBe(before);
+    const changed = await new WorkflowState(dir, 'test', 'session').init(
+      { goal: 'same' },
+      after,
+      [],
+    );
+    expect(changed.scriptChanged).toBe(true);
+    await writeFile(join(dir, 'README.md'), 'not an executable dependency');
+    expect(await workflowFingerprint(source, dir)).toBe(after);
+    await writeFile(join(dir, 'prompts', 'qa.md'), 'new acceptance contract');
+    expect(await workflowFingerprint(source, dir)).not.toBe(after);
+    expect(await workflowFingerprint('new source', dir)).not.toBe(
+      await workflowFingerprint(source, dir),
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('bundle symlinks fail visibly instead of reusing untracked external dependencies', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'wf-link-'));
+  try {
+    await mkdir(join(dir, 'scripts'));
+    await writeFile(join(dir, 'external.mjs'), 'v1');
+    await symlink(
+      join(dir, 'external.mjs'),
+      join(dir, 'scripts', 'linked.mjs'),
+    );
+    await expect(workflowFingerprint('source', dir)).rejects.toThrow(
+      '符号链接',
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('import of the host package itself must be rejected — bypasses wf entirely, declaring it does not help', async () => {
+  // package.json::exports 里的 "./src/*"/"./plugins/*" 通配符 + Node/Bun 包
+  // 自引用会让 `minimal-agent/src/xxx` 解析到真实内核文件，完全绕开 wf 分组
+  // 能力对象对调度/记账/心跳/预算的管控——这是 scriptGuard.mjs 同名检查的
+  // 第二道闸，验证即使调用方跳过了 discovery.ts 的静态校验，这里仍然拦得住。
+  const dir = await mkdtemp(join(import.meta.dir, 'wf-selfref-'));
+  try {
+    const source = "import { runQuery } from 'minimal-agent/src/loop.js';\n";
+    await expect(workflowFingerprint(source, dir)).rejects.toThrow('宿主引擎自身');
+    // 声明进 meta.packages 也无法绕过——这不是"没声明"的问题。
+    await expect(
+      workflowFingerprint(source, dir, ['minimal-agent']),
+    ).rejects.toThrow('宿主引擎自身');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('bare packages imported by relative helpers must be declared and versioned', async () => {
+  // ⚠️ 必须落在仓库树内（而不是 OS 系统临时目录）：`workflowFingerprint` 校验
+  // `meta.packages` 时用 `createRequire(entry).resolve(name)`，从 fixture 目录
+  // 向上找 node_modules——系统临时目录（如 Windows 的 %TEMP%）没有任何
+  // node_modules 祖先，会让这里恒定解析失败，与"包名没声明"这个真正要测的
+  // 场景无关。落在 `test/` 下能向上找到仓库根的 node_modules（含 yaml）。
+  const dir = await mkdtemp(join(import.meta.dir, 'wf-package-'));
+  try {
+    await mkdir(join(dir, 'scripts'));
+    await writeFile(
+      join(dir, 'scripts', 'helper.mjs'),
+      "import YAML from 'yaml'; export const parse = YAML.parse;\n",
+    );
+    const source = "import './scripts/helper.mjs';\n";
+    await expect(workflowFingerprint(source, dir)).rejects.toThrow(
+      '必须声明在 meta.packages',
+    );
+    expect(await workflowFingerprint(source, dir, ['yaml'])).toHaveLength(16);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});