minimal-agent 0.12.0 → 0.14.0

package/plugins/workflow-runner/src/workflowState.ts

@@ -1,733 +1,783 @@
 /**
  * ============================================================
- *  plugins/workflow-runner/src/workflowState.ts —— 工作流状态持久化
+ *  plugins/workflow-runner/src/workflowState.ts —— 任务状态持久化
  * ------------------------------------------------------------
- *  Phase 1 升级：支持断点续执行、任务身份判定、capture 回放、产物管理。
+ *  自 legacy 移植**持久化那一半**。legacy 版 1178 行里另一半是按「步骤索引 /
+ *  循环迭代 / VarStack 快照 / capture 变量」做的断点定位 —— 那些概念在代码
+ *  编排里不存在，由 `journal.ts` 的「调用序号 + 内容指纹」整体取代。
  *
- *  核心变更：
- *    - init() 不再无条件清空，而是先读旧状态 → 判定任务身份 → 分发 4 种模式
- *    - 新增 checkpoints/ 目录记录每步完成状态和 capture 变量
- *    - 产物生命周期：current.json.artifacts 记录工作流【声明】的产物路径（相对 cwd，
- *      来自 yaml 的 def.artifacts / step.artifacts）；new-task 时据此清旧产物（如旧 PLAN.md），
- *      completed 时据此报实际存在的产物。不再用从不写入的 artifacts/ 子目录。
- *    - resume 模式时回放已完成步骤的 capture 到 vars 中
- *    - completed 检测：成功后 archive() 把目录改名 .done，故 init() 在活动目录缺失时
- *      回退读 .done/current.json（status=done + taskId 匹配 → completed），修活「completed 死代码」。
+ *  本文件负责的是**跨进程活得下来的东西**：
+ *    - 目录布局与四态判定（fresh / new-task / completed / resume）
+ *    - 声明产物的「先归档再清理」（含 glob 展开）
+ *    - 用户补充要求（supplements）的持久化
+ *    - 人类可读的 progress 日志
  *
- *  目录结构（E6：按 workflow 名隔离，跨工作流互不可见/互不干扰）：
- *    <cwd>/.minimal-agent-workflow/<name>/   （成功后改名为 <name>.done/）
- *      ├── current.json     # { name, taskId, status, startedAt, artifacts?, lastFailedStep?, lastError? }
- *      ├── inputs.json      # 用户传入的 inputs 快照
- *      ├── vars.json        # 最后一次成功 step 后的 VarStack.snapshot()
- *      ├── progress.md      # 时间戳追加的 step 完成日志
- *      ├── supplements.json # 贯穿补充要求（pause 反馈/澄清结论，resume 恢复进锚定）
- *      └── checkpoints/     # 每步一个 JSON：{ stepId, completedAt, output, captures, varsSnapshot }
- *                           #   顶层步用原名；顶层 loop 内步用复合名 loopId@@迭代号@@stepId
- *                           #   （resume 可恢复到迭代中间，见 scanLoopResume）
- *    /new 按 .minimal-agent 前缀清理父目录，行为不变。
+ *  ------------------------------------------------------------
+ *  ⚠️ **清理必须先归档，不能直接 rm** —— 这条是实战事故换来的：
+ *  同主题重跑时 LLM 仲裁误判成 new-task，11 个声明产物被静默直接删除、不可找回。
+ *  现在一律先 `rename` 进 `<实例目录>.trash/<stamp>/`（保留相对路径结构），
+ *  rm 只作为 rename 失败的兜底。`.trash/` 是状态目录的 sibling，跨任务留存
+ *  （淘汰策略暂未实现，需要时由用户手动清）。
+ *
+ *  ⚠️ 归档失败时**绝不谎报归档位置** —— 一个文件都没成功移走就返回 undefined。
+ *  报了位置用户会去回收站找，找不到比一开始就说「已删除」更糟。
  * ============================================================
  */
 
-import { createHash } from 'node:crypto';
-import { mkdir, writeFile, appendFile, rm, rename, readFile, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { type Dirent, existsSync } from 'node:fs';
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+
 import {
+  type TaskArbitrator,
   computeTaskId,
   extractGoal,
-  workflowStateDir,
-  type TaskArbitrator,
+  sanitizeWorkflowDirName,
+  sessionStateDir,
+  taskInstanceDir,
 } from './taskIdentity.js';
-import type { StepDef } from './types.js';
+import type { InputDef } from './types.js';
+import { safeArtifactPath } from './util.js';
 
 const DONE_SUFFIX = '.done';
-const CHECKPOINTS_DIR = 'checkpoints';
-const SUPPLEMENTS_FILE = 'supplements.json';
-
-/**
- * 顶层 loop 内步的复合 checkpoint 文件名分隔符。
- * 选 '@@'：yaml step id 习惯用 [a-z0-9_]，不会撞；且对文件系统安全。
- */
-export const LOOP_CP_SEP = '@@';
-
-/** 复合 checkpoint 名：<loopId>@@<迭代号>@@<stepId>（runner 的 CpScope 与本模块扫描共用）。 */
-export function loopCheckpointName(loopId: string, iteration: number, stepId: string): string {
-  return `${loopId}${LOOP_CP_SEP}${iteration}${LOOP_CP_SEP}${stepId}`;
-}
-
-/** 解析复合 checkpoint 文件名；非复合名（普通顶层步）返回 null。 */
-function parseLoopCheckpointName(
-  name: string,
-): { loopId: string; iteration: number; stepId: string } | null {
-  const parts = name.split(LOOP_CP_SEP);
-  if (parts.length !== 3) return null;
-  const iteration = Number(parts[1]);
-  if (!Number.isInteger(iteration) || iteration < 0) return null;
-  return { loopId: parts[0], iteration, stepId: parts[2] };
-}
-
-/**
- * 工作流定义的**结构指纹**：步骤 id + 执行形态 + 嵌套块（then/else/do）骨架的 hash。
- * prompt 文案、args、condition 等内容字段不参与——改提示词/参数不应作废断点；
- * 改结构（增删步/换 id/换类型/调嵌套）才作废：resume 的恢复点是**索引**、循环断点是
- * 复合名（loopId@@迭代@@stepId），结构一变旧 checkpoint 就对不上，按旧断点续跑会错跳步
- * （曾真实发生：plan.yaml v3→v4 重构后同 goal 重跑提示「从第 2 步续跑」，跳过的步与
- * 新结构毫无对应关系）。current.json 记录运行时的指纹，init 同任务重跑时比对。
- */
-export function computeDefFingerprint(steps: StepDef[]): string {
-  const skeleton = (list: StepDef[] | undefined): unknown[] =>
-    (list ?? []).map((s) => ({
-      id: s.id,
-      kind:
-        s.type ??
-        (s.tool ? 'tool' : s.skill ? 'skill' : s.agent ? 'agent' : s.llm ? 'llm' : '?'),
-      then: s.then ? skeleton(s.then) : undefined,
-      else: s.else ? skeleton(s.else) : undefined,
-      do: s.do ? skeleton(s.do) : undefined,
-    }));
-  return createHash('sha1')
-    .update(JSON.stringify(skeleton(steps)))
-    .digest('hex')
-    .slice(0, 16);
-}
+const TRASH_SUFFIX = '.trash';
 
-/** 进行中循环的恢复信息（buildResumeInfo 产出，runner 的 loop 处理器消费）。 */
-export interface LoopResumeInfo {
-  /** 中断时正在执行的顶层 loop 步 id */
-  loopId: string;
-  /** 该 loop 在顶层 steps[] 中的索引（= resume 的顶层 startFrom） */
-  loopIndex: number;
-  /** 恢复到第几轮迭代（0-based，= 中断时的迭代号） */
-  iteration: number;
-  /** 该迭代内从第几个 do[] 步起跑（已含 backoff 回退） */
-  innerStartFrom: number;
-  /** 该迭代内已完成的 do[] 步 id（按 do[] 顺序） */
-  completedInnerIds: string[];
-  /** 中断时刻最近一个 checkpoint 的 vars 快照（runner 回放为全局变量，不含 inputs） */
-  lastVarsSnapshot?: Record<string, unknown>;
-}
-
-// ---- 导出类型 ----
-
-/** 任务恢复模式 */
+/** 四态：首次 / 换了任务 / 同任务已完成 / 同任务未完成可续跑。 */
 export type TaskResumeMode = 'fresh' | 'new-task' | 'completed' | 'resume';
 
-/** init() 返回的恢复信息 */
 export interface TaskResumeInfo {
   mode: TaskResumeMode;
-  /** fresh/new-task/resume: 从第几个 step 索引开始执行 */
-  startFrom?: number;
-  /** new-task: 被清理的旧产物文件路径列表 */
+  /** fresh/new-task：旧产物归档到哪（相对 cwd）。归档一个都没成功时**不填**。 */
+  archivedTo?: string;
+  /** fresh/new-task：归档失败后被 rm 兜底删掉的路径。非空通常意味着归档出了问题。 */
   cleanedArtifacts?: string[];
   /**
-   * new-task: 同任务但工作流定义结构已变更（或 legacy 状态无指纹无从验证）
-   * → 旧断点作废、全新开始。runner 据此向用户明示原因（不是静默重头跑）。
+   * new-task：同一个 taskId，但**脚本内容变了**（指纹不匹配）→ 旧断点作废。
+   * 调用方据此向用户明示原因，而不是静默从头跑。
    */
-  defChanged?: boolean;
-  /** completed: 已完成的产物列表 */
+  scriptChanged?: boolean;
+  /** completed：磁盘上**实际存在**的产物（不是声明了就报）。 */
   artifacts?: string[];
-  /** resume: 已完成的 step id 列表（按顺序） */
-  completedStepIds?: string[];
-  /** resume: 失败的 step id */
-  failedStep?: string;
-  /** resume: 自愈回退到的起始索引 */
-  recoveryStart?: number;
-  /** resume: 上次错误信息 */
+  /** resume：上次失败的原因。 */
   lastError?: string;
-  /** resume: 已完成步骤的 capture 变量快照 { stepId: { captureKey: value } } */
-  capturedVars?: Record<string, Record<string, unknown>>;
   /**
-   * resume（仲裁判定的延续）: 旧任务的原始 goal。runner 据此重建 goalAnchor——
-   * 本次 inputs 里的 goal 是「继续」这类延续指令，不能拿它当锚（会让每步 LLM
-   * 把「继续」当成目标）；锚应是旧任务的真实目标。
+   * resume（仲裁判定的延续）：旧任务的原始 goal。
+   *
+   * 本次输入是「继续」这类延续指令，**不能拿它当目标锚** —— 那会让后续每次
+   * 调用都把「继续」当成要达成的事。锚必须是旧任务的真实目标。
    */
   prevGoal?: string;
-  /**
-   * resume（仲裁判定的延续）: 本次的新输入文本，作为旧目标的补充指令
-   * 并入 goalAnchor（如「继续，但 PPT 改成 12 页」中的修改意见不丢失）。
-   */
+  /** resume（仲裁判定的延续）：本次新输入，作为旧目标的补充要求并入锚。 */
   supplementaryGoal?: string;
-  /**
-   * resume: 中断发生在某顶层 loop 的迭代中间时的恢复信息。
-   * 存在时 startFrom = loopIndex（顶层直接定位到该 loop），迭代号与迭代内
-   * 起点由 runner 的 loop 处理器消费；backoff 作用在迭代内而非顶层。
-   */
-  loopResume?: LoopResumeInfo;
-}
-
-// ---- 内部类型 ----
-
-/** 单个 checkpoint 的数据结构 */
-interface CheckpointData {
-  stepId: string;
-  completedAt: string; // ISO timestamp
-  output: string; // step result preview
-  captures: Record<string, unknown>; // 该步绑定的 capture 变量
-  varsSnapshot: Record<string, unknown>; // 当时的全局 vars 快照
 }
 
-// ---- current.json 结构 ----
-
+/** `current.json` 的形状。 */
 interface CurrentState {
   name: string;
   taskId: string;
-  status: string;
+  status: 'running' | 'failed' | 'done';
   startedAt: string;
-  lastFailedStep?: string;
+  goal: string;
   lastError?: string;
-  /** 工作流声明的产物路径（相对 cwd），new-task 清理 + completed 报告用 */
+  /** 声明产物（相对 cwd）：new-task 清理与 completed 报告用。 */
   artifacts?: string[];
-  /** 运行时工作流定义的结构指纹（computeDefFingerprint），resume 兼容性比对用 */
-  defFingerprint?: string;
+  /** Exact successful outputs, including owned descendants; declarations may include failed optional outputs. */
+  completion?: { artifacts: string[]; stateFiles: string[] };
+  /**
+   * 编排脚本全文的哈希。取代 legacy 的 `defFingerprint`（那是按步骤骨架算的）。
+   *
+   * 作用相同：同一个 taskId 但脚本改过 → 旧 journal 的调用序号对不上新脚本的
+   * 控制流 → 断点作废、明示原因、全新开始。legacy 曾因索引断点在 yaml 重构后
+   * 错跳步，被误读成 bug（真实发生过）。
+   */
+  scriptHash?: string;
+}
+
+/** 把 glob 段翻成正则片段（`*` 不跨目录分隔符，`?` 单字符）。 */
+function artifactSegToPattern(seg: string): string {
+  return seg
+    .split(/([*?])/)
+    .map((part) => {
+      if (part === '*') return '[^/]*';
+      if (part === '?') return '[^/]';
+      return part.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+    .join('');
 }
 
 export class WorkflowState {
-  readonly dir: string;
+  /** 任务实例目录（绝对路径）。init 里确定 taskId 后才有值。 */
+  dir = '';
+  /** 当前 session 的目录（其下按 taskId 分实例）。 */
+  readonly sessionDir: string;
   readonly workingDir: string;
-
-  constructor(workingDir: string, workflowName: string) {
+  readonly workflowName: string;
+  private readonly taskIdOverride?: string;
+  readonly sessionId: string;
+  /** init 里算出的任务身份。 */
+  taskId = '';
+  /**
+   * 输入声明。用于让 `extractGoal` 优先取作者标了 `required` 的那个输入 ——
+   * 任务身份与目标锚必须用**同一份**取值规则，否则「拿来算 taskId 的目标」
+   * 和「注入给模型的目标」会指向不同的东西。
+   */
+  private readonly defs?: InputDef[];
+  private progressWrites: Promise<void> = Promise.resolve();
+  private eventWrites: Promise<void> = Promise.resolve();
+
+  constructor(
+    workingDir: string,
+    workflowName: string,
+    sessionId: string,
+    defs?: InputDef[],
+    taskIdOverride?: string,
+    private readonly parentStateDir?: string,
+  ) {
     this.workingDir = workingDir;
-    // 按 workflow 名隔离（与 taskIdentity.computeTaskId 读的是同一权威路径）
-    this.dir = workflowStateDir(workingDir, workflowName);
+    this.workflowName = workflowName;
+    this.sessionId = sanitizeWorkflowDirName(sessionId);
+    this.sessionDir = parentStateDir
+      ? join(parentStateDir, 'children', workflowName)
+      : sessionStateDir(workingDir, workflowName, sessionId);
+    this.defs = defs;
+    this.taskIdOverride = taskIdOverride;
+  }
+
+  /** journal 落盘位置（由 journal.ts 消费，见任务 5）。 */
+  get journalPath(): string {
+    return join(this.dir, 'journal.jsonl');
+  }
+
+  private get currentPath(): string {
+    return join(this.dir, 'current.json');
+  }
+
+  private get supplementsPath(): string {
+    return join(this.dir, 'supplements.json');
+  }
+
+  private get progressPath(): string {
+    return join(this.dir, 'progress.md');
+  }
+
+  private get eventsPath(): string {
+    return join(this.dir, 'events.jsonl');
   }
 
   /**
-   * 初始化工作流状态 —— 核心入口，返回恢复信息。
+   * 判定本次运行属于四态里的哪一种，并把实例目录准备好。
    *
-   * 4 种模式：
-   *   1. fresh      — 首次运行此工作流（无旧状态）
-   *   2. new-task  — 不同任务 → 清理旧产物后全新开始
-   *   3. completed — 同一任务已完成 → 返回产物列表
-   *   4. resume    — 同一任务未完成 → 扫描 checkpoint 决定恢复点
-   *
-   * hash 相等 = 同任务（权威信号，与时间无关）。hash 不等且旧任务【未完成】时
-   * 不再一票否决 new-task：若提供了 arbitrate（语义仲裁器，见 taskIdentity.ts），
-   * 由它判定新输入是「旧任务的延续指令（如"继续"）→ resume」还是「全新任务 → new-task」。
+   * @param inputs             本次调用的输入（用于算 taskId 与 goal）
+   * @param scriptHash         编排脚本全文哈希（脚本改了 → 断点作废）
+   * @param declaredArtifacts  meta.artifacts 种子（运行时还会经 declareArtifact 增长）
+   * @param arbitrate          可选的语义仲裁器；不传则 hash 不等一律 new-task
    */
   async init(
-    name: string,
     inputs: Record<string, unknown>,
-    steps: StepDef[],
-    // 跨次重跑回退步数（= WorkflowDef.self_heal.backoff），runWorkflow 注入；缺省 1。
-    selfHealBackoff = 1,
-    // 工作流【声明】的产物路径（相对 cwd，= def.artifacts + step.artifacts），runWorkflow 注入。
-    declaredArtifacts: string[] = [],
-    // 语义仲裁器（hash 不等 + 旧任务未完成时的二审），runWorkflow 注入；缺省直接 new-task。
+    scriptHash: string,
+    declaredArtifacts: string[],
     arbitrate?: TaskArbitrator,
   ): Promise<TaskResumeInfo> {
-    // 1. 计算当前任务的 identity（goal 内容 hash 是唯一权威信号）
-    // 与本次定义的结构指纹（resume 兼容性信号：yaml 结构变了旧断点即作废）
-    const identity = computeTaskId(name, inputs, this.workingDir);
-    const fp = computeDefFingerprint(steps);
-
-    // 2. 尝试读取活动目录的 current.json
-    const oldState = await this.readCurrentState();
-
-    if (!oldState) {
-      // 活动目录无状态 —— 可能是「上次成功已归档到 .done」。读归档判定 completed / 不同 goal 新任务。
-      const archived = await this.readArchivedState();
-      if (archived && archived.name === name) {
-        if (archived.taskId === identity.hash) {
-          // 模式 3: completed —— 同任务此前已成功（报实际存在的声明产物）
-          return {
-            mode: 'completed',
-            artifacts: this.existingArtifacts(archived.artifacts ?? declaredArtifacts),
-          };
-        }
-        // 同名 workflow 但 goal 不同 → 全新任务：清旧归档声明产物后 fresh
-        // （legacy 归档无 artifacts 字段时用本次声明清单兜底——同名 workflow 的声明产物
-        //   语义稳定，旧任务的产物路径与本次一致的概率极高，残留比误删危害大）
-        const cleaned = await this.cleanupDeclaredArtifacts(
-          archived.artifacts ?? declaredArtifacts,
+    const goal = extractGoal(inputs, this.defs);
+    this.taskId = this.taskIdOverride
+      ? sanitizeWorkflowDirName(this.taskIdOverride)
+      : computeTaskId(this.workflowName, inputs, this.defs);
+    const taskDir = this.parentStateDir
+      ? join(this.sessionDir, this.taskId)
+      : taskInstanceDir(
+          this.workingDir,
+          this.workflowName,
+          this.sessionId,
+          this.taskId,
         );
-        await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
-        return {
-          mode: 'new-task',
-          startFrom: 0,
-          cleanedArtifacts: [
-            ...cleaned,
-            ...(await this.cleanupStaleDeclared(declaredArtifacts)),
-          ],
-        };
+    const doneDir = taskDir + DONE_SUFFIX;
+
+    // ① 同任务、已完成 → 报实际存在的产物，不重跑。
+    if (existsSync(doneDir)) {
+      this.dir = doneDir;
+      const prev = await this.readCurrent();
+      // ⚠️ **脚本改过就不算已完成**。上次那份结论是**另一份脚本**产出的 ——
+      // 作者刚改完工作流重跑同一个目标，最想要的恰恰是「按新逻辑再来一遍」，
+      // 这时回一句「此前已完成」并甩出旧产物，是**静默给错答案**。
+      // （这条是端到端实跑抓到的：改完脚本重跑，1 秒返回旧结果。）
+      if (
+        prev &&
+        ((prev.scriptHash && prev.scriptHash !== scriptHash) ||
+          !(await this.treeIntact()))
+      ) {
+        const info = await this.restartChanged(
+          goal,
+          scriptHash,
+          declaredArtifacts,
+          prev,
+          taskDir,
+        );
+        return { ...info, mode: 'new-task', scriptChanged: true };
       }
-      // 模式 1: fresh —— 活动 + 归档都没有，首次运行。
-      // 声明产物若已存在于磁盘 = 残留孤儿（如 /new 删状态目录后的旧 PLAN.md，
-      // artifacts 清单随 current.json 一起被删，引擎无从知道它属于谁）。
-      // 用户约定：全新任务开始时清理残留与中间文件——删除范围**仅限本工作流
-      // 声明的产物**（与运行自身对它们的覆盖写权限一致，不碰用户其他文件）。
-      await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
-      return {
-        mode: 'fresh',
-        startFrom: 0,
-        cleanedArtifacts: await this.cleanupStaleDeclared(declaredArtifacts),
-      };
+      const artifacts = await this.allArtifacts();
+      return { mode: 'completed', artifacts };
     }
 
-    // 3. 有活动状态（上次中断 / 失败 / 进行中，未归档）—— 用 hash 判同/异任务
-    if (!identity.isSameTask) {
-      // hash 不等 + 同名 workflow + 旧任务未完成 → 语义仲裁二审：
-      // 新输入可能是「继续」这类延续指令（goal 文本必然与旧任务不同，按旧规则
-      // 会被误判 new-task 把没做完的产物清掉重开）。不同名 workflow / 旧任务已
-      // 完成 / 未提供仲裁器 → 维持 new-task。仲裁器自身抛错也兜底 new-task。
+    // ② 同任务、未完成 → resume（能续多远由 journal 说了算）。
+    if (existsSync(taskDir)) {
+      this.dir = taskDir;
+      const prev = await this.readCurrent();
       if (
-        arbitrate &&
-        identity.reason === 'hash_diff' &&
-        oldState.name === name &&
-        oldState.status !== 'done' &&
-        // 定义结构已变（或 legacy 无指纹）→ 旧断点不可续，仲裁 resume 无意义，
-        // 跳过仲裁直接走 new-task
-        oldState.defFingerprint === fp
+        prev &&
+        ((prev.scriptHash && prev.scriptHash !== scriptHash) ||
+          !(await this.treeIntact()))
       ) {
-        const prevGoal = extractGoal((await this.readInputs()) ?? {});
-        const newGoal = extractGoal(inputs);
-        let verdict: 'resume' | 'new' = 'new';
-        try {
-          verdict = await arbitrate({
-            workflowName: name,
-            prevGoal,
-            newGoal,
-            completedStepIds: await this.scanCheckpoints(steps),
-            totalSteps: steps.length,
-            artifacts: oldState.artifacts ?? [],
-          });
-        } catch {
-          verdict = 'new';
-        }
-        if (verdict === 'resume') {
-          // 延续旧任务：状态目录原样保留（taskId 仍是旧 goal 的 hash——
-          // 下次再输「继续」依然 hash 不等 → 再次仲裁快路径命中，语义自洽）。
-          const info = await this.buildResumeInfo(oldState, steps, selfHealBackoff);
-          info.prevGoal = prevGoal;
-          info.supplementaryGoal = newGoal;
-          return info;
-        }
+        // 脚本结构变了：旧 journal 的调用序号对不上新控制流，断点必须作废。
+        const info = await this.restartChanged(
+          goal,
+          scriptHash,
+          declaredArtifacts,
+          prev,
+          taskDir,
+        );
+        return { ...info, mode: 'new-task', scriptChanged: true };
       }
-
-      // 模式 2: new-task —— 不同任务，清旧声明产物 + 旧状态后全新开始。
-      // legacy 状态文件无 artifacts 字段时：仅当同名 workflow 用本次声明清单兜底
-      //（不同名 workflow 的产物不是我们的，不能殃及）。
-      const cleaned = await this.cleanupDeclaredArtifacts(
-        oldState.artifacts ?? (oldState.name === name ? declaredArtifacts : []),
-      );
-      await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
-      return {
-        mode: 'new-task',
-        startFrom: 0,
-        cleanedArtifacts: [
-          ...cleaned,
-          ...(await this.cleanupStaleDeclared(declaredArtifacts)),
+      await this.writeCurrent({
+        name: this.workflowName,
+        taskId: this.taskId,
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        goal: prev?.goal ?? goal,
+        artifacts: [
+          ...new Set([...(prev?.artifacts ?? []), ...declaredArtifacts]),
         ],
-      };
-    }
-
-    // 4. 同一任务 —— 检查完成状态（兜底：正常成功会 archive，故活动目录 done 少见）
-    if (oldState.status === 'done') {
-      return {
-        mode: 'completed',
-        artifacts: this.existingArtifacts(oldState.artifacts ?? declaredArtifacts),
-      };
+        scriptHash,
+      });
+      return { mode: 'resume', lastError: prev?.lastError };
     }
 
-    // 4.5 定义结构变更守卫：同任务但 yaml 结构改过（增删步/换 id/调嵌套）——
-    // resume 恢复点是索引、循环断点是复合名，结构一变旧 checkpoint 全对不上，
-    // 按旧断点续跑会错跳步（曾真实发生：plan v3→v4 重构后同 goal 重跑
-    // 「从第 2 步续跑」，用户困惑是 bug 还是残留）。旧现场作废、全新开始，
-    // runner 经 defChanged 旗标向用户明示。legacy 状态（无 defFingerprint
-    // 字段）无从验证兼容性，同样按变更处理（一次性升级成本，安全优先）。
-    if (oldState.defFingerprint !== fp) {
-      const cleaned = await this.cleanupDeclaredArtifacts(
-        oldState.artifacts ?? declaredArtifacts,
-      );
-      await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
-      return {
-        mode: 'new-task',
-        startFrom: 0,
-        defChanged: true,
-        cleanedArtifacts: [
-          ...cleaned,
-          ...(await this.cleanupStaleDeclared(declaredArtifacts)),
-        ],
-      };
+    // ③ 本 taskId 没有目录。看看同 session 下有没有**未完成的兄弟任务**可以仲裁延续。
+    const sibling = await this.findIncompleteSibling();
+    // Bound resources and their declared parameters are an exact contract.
+    // A different task hash must not be overridden by a semantic guess based
+    // only on the (possibly identical) human-readable goal.
+    if (sibling && arbitrate && !inputs.__resource_fingerprint) {
+      const prev = await this.readCurrentAt(sibling);
+      const verdict = await arbitrate({
+        workflowName: this.workflowName,
+        prevGoal: prev?.goal ?? '',
+        newGoal: goal,
+        completedCalls: await this.countJournalEntries(sibling),
+        artifacts: await this.existingArtifacts(prev?.artifacts ?? []),
+      });
+      if (verdict === 'resume') {
+        // 采纳旧实例目录继续跑：本次输入降级成补充要求，目标锚仍指向旧目标。
+        this.dir = sibling;
+        this.taskId = prev?.taskId ?? this.taskId;
+        return {
+          mode: 'resume',
+          prevGoal: prev?.goal,
+          supplementaryGoal: goal,
+          lastError: prev?.lastError,
+        };
+      }
     }
 
-    // 5. 模式 4: resume —— 同一任务未完成，扫描 checkpoint 决定恢复点。
-    return this.buildResumeInfo(oldState, steps, selfHealBackoff);
+    // ④ 全新任务（或首次运行）。
+    this.dir = taskDir;
+    const info = await this.startFresh(goal, scriptHash, declaredArtifacts);
+    return { ...info, mode: sibling ? 'new-task' : 'fresh' };
   }
 
-  /**
-   * 构建 resume 信息：扫描 checkpoint 决定恢复点 + 加载 capture 回放数据。
-   * 回退步数由 WorkflowDef.self_heal.backoff 经 runWorkflow 传入（缺省 1）。
-   * 同 goal resume（hash 相等）与仲裁延续 resume（hash 不等但判定延续）共用。
+  /** 建实例目录、归档并清理旧产物残留、写 current.json。 */
+  /** Retire the actual old journal AND dynamic outputs, not only the status flag.
+   * A completed directory must also be retired, otherwise it shadows the fresh
+   * incomplete attempt on the next resume. Nothing is deleted on this path.
    */
-  private async buildResumeInfo(
-    oldState: CurrentState,
-    steps: StepDef[],
-    selfHealBackoff: number,
+  private async restartChanged(
+    goal: string,
+    scriptHash: string,
+    declaredArtifacts: string[],
+    previous: CurrentState,
+    taskDir: string,
   ): Promise<TaskResumeInfo> {
-    const completedSteps = await this.scanCheckpoints(steps);
-
-    // 恢复点 = 最后一个已完成步在 steps[] 中的【索引】+1 - backoff。
-    // 不能用 checkpoint【计数】当索引：when=false 跳过步 / pause 步不记 checkpoint，
-    // 计数会低估位置 → resume 重复执行已跑过的步（对非幂等 tool 步有实害）。
-    // 已完成步是连续前缀时索引法与计数法等价（向后兼容）。
-    const lastCompletedId = completedSteps[completedSteps.length - 1];
-    const lastIdx =
-      lastCompletedId !== undefined
-        ? steps.findIndex((s) => s.id === lastCompletedId)
-        : -1;
-    const recoveryStart = Math.max(0, lastIdx + 1 - selfHealBackoff);
-
-    // 加载 capturedVars 用于回放
-    const capturedVars = await this.loadAllCaptures(completedSteps);
-
-    // 循环级恢复：中断发生在某顶层 loop 的迭代中间（该 loop 自身无完成 checkpoint、
-    // 但有复合迭代 checkpoint）→ 顶层直接定位到该 loop、迭代内续跑，
-    // 不再整条循环从头重来（plan.yaml 95% 的工作都在一个 loop 里，此前粒度形同虚设）。
-    const loopResume = await this.scanLoopResume(steps, completedSteps, selfHealBackoff);
-    if (loopResume) {
-      return {
-        mode: 'resume',
-        startFrom: loopResume.loopIndex,
-        completedStepIds: completedSteps,
-        failedStep: oldState.lastFailedStep,
-        recoveryStart: loopResume.loopIndex,
-        lastError: oldState.lastError,
-        capturedVars,
-        loopResume,
-      };
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const archiveRoot = join(this.dir + TRASH_SUFFIX, stamp);
+    const existing = [
+      ...new Set([
+        ...(await this.allArtifacts()),
+        ...(await this.existingArtifacts(declaredArtifacts)),
+      ]),
+    ];
+    await this.archiveDeclaredArtifacts(existing, stamp);
+    const remaining = existing.filter((path) =>
+      existsSync(join(this.workingDir, path)),
+    );
+    if (remaining.length)
+      throw new Error(`旧产物归档失败，停止覆盖：${remaining.join('、')}`);
+    await mkdir(archiveRoot, { recursive: true });
+    const oldDir = this.dir;
+    await rename(oldDir, join(archiveRoot, 'state'));
+    // Older versions could leave both .done and an incomplete directory.
+    if (oldDir !== taskDir && existsSync(taskDir)) {
+      await rename(taskDir, join(archiveRoot, 'incomplete-state'));
     }
+    this.dir = taskDir;
+    const info = await this.startFresh(goal, scriptHash, declaredArtifacts);
+    return { ...info, archivedTo: relative(this.workingDir, archiveRoot) };
+  }
 
-    return {
-      mode: 'resume',
-      startFrom: recoveryStart,
-      completedStepIds: completedSteps,
-      failedStep: oldState.lastFailedStep,
-      recoveryStart,
-      lastError: oldState.lastError,
-      capturedVars,
-    };
+  private async startFresh(
+    goal: string,
+    scriptHash: string,
+    declaredArtifacts: string[],
+  ): Promise<TaskResumeInfo> {
+    // 时间戳只用作回收目录名，不参与任何身份判定 —— 故这里用真实时间是安全的。
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const { cleaned, archivedTo } = await this.archiveThenClean(
+      declaredArtifacts,
+      stamp,
+    );
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(this.supplementsPath, '[]', 'utf8');
+    await this.writeCurrent({
+      name: this.workflowName,
+      taskId: this.taskId,
+      status: 'running',
+      startedAt: new Date().toISOString(),
+      goal,
+      artifacts: declaredArtifacts,
+      scriptHash,
+    });
+    const info: TaskResumeInfo = { mode: 'fresh' };
+    if (cleaned.length > 0) info.cleanedArtifacts = cleaned;
+    if (archivedTo) info.archivedTo = archivedTo;
+    return info;
   }
 
-  /**
-   * 扫描复合迭代 checkpoint（loopId@@iter@@stepId），产出进行中循环的恢复信息。
-   * 候选条件：顶层 type=loop 步 + 自身无完成 checkpoint（completedTopIds 不含它）。
-   * 多个候选（罕见，前一循环中断后又跑到后一循环）取顶层索引最大者（最远进度）。
-   */
-  private async scanLoopResume(
-    steps: StepDef[],
-    completedTopIds: string[],
-    selfHealBackoff: number,
-  ): Promise<LoopResumeInfo | null> {
-    const cpDir = join(this.dir, CHECKPOINTS_DIR);
-    let files: string[];
+  /** 同 session 下另一个**未完成**任务的目录（有多个时取最近修改的）。 */
+  private async findIncompleteSibling(): Promise<string | null> {
+    let entries: Dirent[];
     try {
-      files = await readdir(cpDir);
+      entries = await readdir(this.sessionDir, { withFileTypes: true });
     } catch {
       return null;
     }
-    const completedTop = new Set(completedTopIds);
-    // loopId → iteration → stepId 集合
-    const byLoop = new Map<string, Map<number, Set<string>>>();
-    for (const f of files) {
-      if (!f.endsWith('.json')) continue;
-      const parsed = parseLoopCheckpointName(f.replace(/\.json$/, ''));
-      if (!parsed) continue;
-      let iters = byLoop.get(parsed.loopId);
-      if (!iters) byLoop.set(parsed.loopId, (iters = new Map()));
-      let ids = iters.get(parsed.iteration);
-      if (!ids) iters.set(parsed.iteration, (ids = new Set()));
-      ids.add(parsed.stepId);
-    }
-    if (byLoop.size === 0) return null;
-
-    let best: LoopResumeInfo | null = null;
-    for (const [loopId, iters] of byLoop) {
-      const loopIndex = steps.findIndex((s) => s.id === loopId && s.type === 'loop');
-      if (loopIndex === -1) continue; // yaml 改动后的孤儿 checkpoint，忽略
-      if (completedTop.has(loopId)) continue; // 该循环已整体完成
-      const loopDef = steps[loopIndex];
-      const doSteps = loopDef.do ?? [];
-      const validInner = new Set(doSteps.map((s) => s.id));
-
-      const iteration = Math.max(...iters.keys());
-      const innerIds = [...(iters.get(iteration) ?? [])]
-        .filter((id) => validInner.has(id))
-        .sort(
-          (a, b) =>
-            doSteps.findIndex((s) => s.id === a) - doSteps.findIndex((s) => s.id === b),
-        );
-      if (innerIds.length === 0) continue;
-
-      const lastInnerIdx = doSteps.findIndex(
-        (s) => s.id === innerIds[innerIds.length - 1],
-      );
-      const innerStartFrom = Math.max(0, lastInnerIdx + 1 - selfHealBackoff);
-
-      // 中断时刻最近的 vars 快照（迭代内最后一个完成步的 checkpoint）
-      let lastVarsSnapshot: Record<string, unknown> | undefined;
-      try {
-        const raw = await readFile(
-          join(cpDir, `${loopCheckpointName(loopId, iteration, innerIds[innerIds.length - 1])}.json`),
-          'utf-8',
-        );
-        lastVarsSnapshot = (JSON.parse(raw) as CheckpointData).varsSnapshot;
-      } catch {
-        // 快照读失败不阻断：仍可定位迭代，变量靠顶层 capture 回放兜底
+    const candidates = entries
+      .filter(
+        (e) =>
+          e.isDirectory() &&
+          !e.name.endsWith(DONE_SUFFIX) &&
+          !e.name.endsWith(TRASH_SUFFIX) &&
+          e.name !== this.taskId,
+      )
+      .map((e) => join(this.sessionDir, e.name))
+      .filter((d) => existsSync(join(d, 'current.json')));
+    if (candidates.length === 0) return null;
+    // 多个未完成实例时取最近的那个 —— 用户嘴里的「继续」几乎总是指最近一次。
+    let newest = candidates[0];
+    let newestAt = '';
+    for (const dir of candidates) {
+      const cur = await this.readCurrentAt(dir);
+      const at = cur?.startedAt ?? '';
+      if (at >= newestAt) {
+        newestAt = at;
+        newest = dir;
       }
+    }
+    return newest;
+  }
 
-      const candidate: LoopResumeInfo = {
-        loopId,
-        loopIndex,
-        iteration,
-        innerStartFrom,
-        completedInnerIds: innerIds,
-        lastVarsSnapshot,
-      };
-      if (!best || candidate.loopIndex > best.loopIndex) best = candidate;
+  private async countJournalEntries(dir: string): Promise<number> {
+    try {
+      const raw = await readFile(join(dir, 'journal.jsonl'), 'utf8');
+      return raw.split('\n').filter((l) => l.trim() !== '').length;
+    } catch {
+      return 0;
     }
-    return best;
   }
 
-  // ---- 公共方法：贯穿补充要求持久化（goalSupplements，runner 写/读） ----
+  // ---- current.json ----
 
-  /** 追加一条用户补充要求到 supplements.json（resume 跨进程不丢）。 */
-  async appendSupplement(text: string): Promise<void> {
-    const list = await this.readSupplements();
-    list.push(text);
-    await writeFile(
-      join(this.dir, SUPPLEMENTS_FILE),
-      JSON.stringify(list, null, 2),
-      'utf-8',
-    ).catch(() => {});
+  private async readCurrent(): Promise<CurrentState | null> {
+    return this.readCurrentAt(this.dir);
   }
 
-  /** 读取已累积的补充要求列表（无文件 / 解析失败返回 []）。 */
-  async readSupplements(): Promise<string[]> {
+  private async readCurrentAt(dir: string): Promise<CurrentState | null> {
     try {
-      const raw = await readFile(join(this.dir, SUPPLEMENTS_FILE), 'utf-8');
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed.filter((x) => typeof x === 'string') : [];
+      return JSON.parse(
+        await readFile(join(dir, 'current.json'), 'utf8'),
+      ) as CurrentState;
     } catch {
-      return [];
+      return null;
     }
   }
 
-  // ---- 公共方法：checkpoint / 失败 / 完成 ----
-
-  /** 记录单个步骤成功完成（含 capture 变量和 vars 快照） */
-  async recordCheckpoint(
-    stepId: string,
-    output: string,
-    captures: Record<string, unknown>,
-    varsSnapshot: Record<string, unknown>,
-  ): Promise<void> {
-    const cpDir = join(this.dir, CHECKPOINTS_DIR);
-    await mkdir(cpDir, { recursive: true }).catch(() => {});
-
-    const data: CheckpointData = {
-      stepId,
-      completedAt: new Date().toISOString(),
-      output,
-      captures,
-      varsSnapshot,
-    };
+  private async writeCurrent(state: CurrentState): Promise<void> {
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(this.currentPath, JSON.stringify(state, null, 2), 'utf8');
+  }
 
-    await writeFile(join(cpDir, `${stepId}.json`), JSON.stringify(data, null, 2), 'utf-8');
+  /** 记一次失败原因（下次 resume 时报给用户 / 喂给模型）。 */
+  async recordFailure(error: string, artifacts?: string[]): Promise<void> {
+    const cur = await this.readCurrent();
+    if (!cur) return;
+    await this.writeCurrent({
+      ...cur,
+      status: 'failed',
+      lastError: error,
+      ...(artifacts ? { artifacts: [...new Set(artifacts)] } : {}),
+    });
   }
 
-  /** 记录步骤失败：更新 current.json 的 lastFailedStep 和 lastError */
-  async recordFailure(stepId: string, error: string): Promise<void> {
-    const current = await this.readCurrentState();
-    if (current) {
-      current.lastFailedStep = stepId;
-      current.lastError = error;
-      current.status = 'failed';
-      await this.writeCurrent(current);
-    }
+  /**
+   * 标记完成（随后 archive() 把目录改名成 `.done`）。
+   *
+   * @param artifacts 本次运行**最终**的声明产物集合。必须传 —— `meta.artifacts`
+   *   只是静态种子，循环体里经 `declareArtifact()` 登记的逐迭代产物只活在内存里。
+   *   不在这里落盘的话，下次 completed 判定会报「本次运行没有声明产物」，
+   *   new-task 清理也会漏掉它们 —— 而且**表现为静默漏档而不是报错**。
+   *   （这条是端到端实跑抓到的：上一轮明明 declareArtifact 了，重跑却报 0 产物。）
+   */
+  async markDone(artifacts?: string[]): Promise<void> {
+    const cur = await this.readCurrent();
+    if (!cur) return;
+    if (!existsSync(join(this.dir, 'return.json')))
+      await this.writeResult(null);
+    const owned = artifacts ?? cur.artifacts ?? [];
+    const records = await this.treeRecords();
+    const treeArtifacts = [
+      ...owned,
+      ...records
+        .filter((r) => r.dir !== this.dir)
+        .flatMap((r) => r.state.artifacts ?? []),
+    ];
+    await this.writeCurrent({
+      ...cur,
+      status: 'done',
+      ...(artifacts ? { artifacts: [...new Set(artifacts)] } : {}),
+      completion: {
+        artifacts: await this.existingArtifacts(treeArtifacts),
+        stateFiles: [
+          'return.json',
+          ...records
+            .filter((r) => r.dir !== this.dir)
+            .map((r) => relative(this.dir, join(r.dir, 'current.json'))),
+        ],
+      },
+    });
   }
 
-  /** 标记整个工作流完成 */
-  async markDone(): Promise<void> {
-    const current = await this.readCurrentState();
-    if (current) {
-      current.status = 'done';
-      await this.writeCurrent(current);
+  async writeResult(value: unknown): Promise<unknown> {
+    const json = JSON.stringify(value ?? null, (_key, v) => {
+      if (
+        typeof v === 'function' ||
+        typeof v === 'symbol' ||
+        typeof v === 'bigint' ||
+        (typeof v === 'number' && !Number.isFinite(v))
+      )
+        throw new Error('工作流返回值必须为JSON数据');
+      return v;
+    });
+    await writeFile(join(this.dir, 'return.json'), json, 'utf8');
+    return JSON.parse(json);
+  }
+
+  async readResult(): Promise<unknown> {
+    try {
+      return JSON.parse(await readFile(join(this.dir, 'return.json'), 'utf8'));
+    } catch (error) {
+      if (!(await this.readCurrent())?.completion) return null; // pre-composition state
+      throw error;
     }
   }
 
-  // ---- 公共方法：进度与变量（保持原有签名兼容） ----
+  /** Children live inside the parent's state directory. Moving the parent also
+   * archives all child journals, never another standalone run of the same name. */
+  private async treeRecords(): Promise<{ dir: string; state: CurrentState }[]> {
+    const records: { dir: string; state: CurrentState }[] = [];
+    const own = await this.readCurrent();
+    if (own) records.push({ dir: this.dir, state: own });
+    const visit = async (dir: string, depth: number): Promise<void> => {
+      if (depth > 24) throw new Error('子工作流状态目录嵌套异常');
+      let entries: Dirent[];
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+        throw error;
+      }
+      for (const e of entries) {
+        if (!e.isDirectory() || e.name.endsWith(TRASH_SUFFIX)) continue;
+        const childDir = join(dir, e.name);
+        const current = await this.readCurrentAt(childDir);
+        if (current) {
+          records.push({ dir: childDir, state: current });
+          await visit(join(childDir, 'children'), depth + 1);
+        } else await visit(childDir, depth + 1);
+      }
+    };
+    await visit(join(this.dir, 'children'), 0);
+    return records;
+  }
 
-  /** 追加进度日志 */
-  async appendProgress(line: string): Promise<void> {
-    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
-    await appendFile(join(this.dir, 'progress.md'), `- ${ts} ${line}\n`, 'utf-8').catch(() => {});
+  async allArtifacts(): Promise<string[]> {
+    return this.existingArtifacts(
+      (await this.treeRecords()).flatMap((r) => r.state.artifacts ?? []),
+    );
   }
 
-  /** 写入 vars 快照 */
-  async writeVars(snapshot: Record<string, unknown>): Promise<void> {
-    await writeFile(join(this.dir, 'vars.json'), JSON.stringify(snapshot, null, 2), 'utf-8').catch(() => {});
+  private async treeIntact(): Promise<boolean> {
+    for (const { dir, state } of await this.treeRecords()) {
+      if (!state.completion) continue;
+      if (
+        state.completion.artifacts.some((p) => {
+          const safe = safeArtifactPath(this.workingDir, p);
+          return !safe || !existsSync(join(this.workingDir, safe));
+        })
+      )
+        return false;
+      if (
+        state.completion.stateFiles.some((p) => {
+          const safe = safeArtifactPath(dir, p);
+          return !safe || !existsSync(join(dir, safe));
+        })
+      )
+        return false;
+      try {
+        JSON.parse(await readFile(join(dir, 'return.json'), 'utf8'));
+      } catch {
+        return false;
+      }
+    }
+    return true;
   }
 
+  // ---- 补充要求 ----
+
   /**
-   * 扫描 checkpoints/ 目录，返回按 steps 数组顺序排列的已完成 step id 列表。
-   * 只返回在 steps[] 中存在的 id（防止 YAML 改动后 orphaned checkpoint 干扰恢复）。
+   * 追加一条用户补充要求。去重：已有条目的前缀重复不再追加。
+   *
+   * 持久化的理由：补充要求要与原始目标**同等贯穿始终**，跨进程 resume 时不能丢。
    */
-  async scanCheckpoints(steps: StepDef[]): Promise<string[]> {
-    const cpDir = join(this.dir, CHECKPOINTS_DIR);
-    const validIds = new Set(steps.map((s) => s.id));
-    try {
-      const files = await readdir(cpDir);
-      const ids: string[] = [];
-      for (const f of files) {
-        if (!f.endsWith('.json')) continue;
-        const stepId = f.replace(/\.json$/, '');
-        if (validIds.has(stepId)) ids.push(stepId);
-      }
-      // 按 steps 数组中的原始顺序排列（非文件系统顺序）
-      return ids.sort((a, b) => {
-        const ai = steps.findIndex((s) => s.id === a);
-        const bi = steps.findIndex((s) => s.id === b);
-        return ai - bi;
-      });
-    } catch {
-      return [];
-    }
+  async appendSupplement(text: string): Promise<void> {
+    const t = text.trim();
+    if (!t) return;
+    const list = await this.readSupplements();
+    if (list.some((s) => s.startsWith(t.slice(0, 240)))) return;
+    list.push(t);
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(
+      this.supplementsPath,
+      JSON.stringify(list, null, 2),
+      'utf8',
+    );
   }
 
-  /** 加载最近一次成功的 vars 快照 */
-  async loadLastGoodVars(): Promise<Record<string, unknown> | null> {
+  async readSupplements(): Promise<string[]> {
     try {
-      const raw = await readFile(join(this.dir, 'vars.json'), 'utf-8');
-      return JSON.parse(raw);
+      const parsed = JSON.parse(await readFile(this.supplementsPath, 'utf8'));
+      return Array.isArray(parsed) ? parsed.map((s) => String(s)) : [];
     } catch {
-      return null;
+      return [];
     }
   }
 
-  /** 加载所有已完成步骤的 capture 变量（用于 resume 时回放到 VarStack） */
-  async loadAllCaptures(stepIds: string[]): Promise<Record<string, Record<string, unknown>>> {
-    const result: Record<string, Record<string, unknown>> = {};
-    const cpDir = join(this.dir, CHECKPOINTS_DIR);
-    for (const sid of stepIds) {
+  // ---- 人类可读进度 ----
+
+  /**
+   * 追加一行进度。
+   *
+   * 存在理由：TUI 的 scrollback 会被刷掉，而排障常常发生在「跑完之后」。
+   * 落盘的 progress.md 是唯一还能回看的现场（provider 的真实报错也写在这里）。
+   */
+  async appendProgress(line: string): Promise<void> {
+    this.progressWrites = this.progressWrites.then(async () => {
       try {
-        const raw = await readFile(join(cpDir, `${sid}.json`), 'utf-8');
-        const cp: CheckpointData = JSON.parse(raw);
-        if (cp.captures && Object.keys(cp.captures).length > 0) {
-          result[sid] = cp.captures;
-        }
+        await mkdir(this.dir, { recursive: true });
+        await appendFile(this.progressPath, `${line}\n`, 'utf8');
       } catch {
-        // 单个 checkpoint 读失败不阻断整体
+        // 进度日志写失败不该影响任务本身
       }
-    }
-    return result;
-  }
-
-  // ---- 私有方法：声明式产物生命周期 ----
-
-  /** 删除工作流【声明】的产物文件（相对 cwd），用于 new-task 清理旧任务残留（如旧 PLAN.md）。
-   *  仅删工作流自己声明的产物、仅 force-rm 文件，scoped 安全。返回清理过的路径列表。 */
-  private async cleanupDeclaredArtifacts(paths: string[]): Promise<string[]> {
-    for (const p of paths) {
-      await rm(join(this.workingDir, p), { force: true }).catch(() => {});
-    }
-    return paths;
+    });
+    await this.progressWrites;
   }
 
-  /** 从声明产物路径里过滤出 cwd 下【实际存在】的文件（completed 报真实产物用）。 */
-  private existingArtifacts(paths: string[]): string[] {
-    return paths.filter((p) => existsSync(join(this.workingDir, p)));
+  async appendEvent(event: unknown): Promise<void> {
+    this.eventWrites = this.eventWrites.then(async () => {
+      try {
+        await mkdir(this.dir, { recursive: true });
+        await appendFile(this.eventsPath, `${JSON.stringify(event)}\n`, 'utf8');
+      } catch {
+        // Structured diagnostics must never fail the workflow itself.
+      }
+    });
+    await this.eventWrites;
   }
 
-  /** 清理【实际存在】的本次声明产物（fresh/new-task 启动时清残留孤儿），返回真正删掉的路径。 */
-  private async cleanupStaleDeclared(declaredArtifacts: string[]): Promise<string[]> {
-    return this.cleanupDeclaredArtifacts(this.existingArtifacts(declaredArtifacts));
+  /**
+   * 等待所有已排队的 progress/event 写入落盘（不做归档，无其它副作用）。
+   *
+   * `journaled()`（`runtime/context.ts`）里的 appendProgress 调用是 fire-and-forget
+   * ——生产路径的落盘保证来自 `archive()` 在 `runner.ts` 终止路径上对同一条
+   * `progressWrites`/`eventWrites` 链的 await。**绕开 `runner.ts` 直接调用能力对象
+   * 的测试**（例如只起 `createWorkflowContext()` 就调 `wf.model.generate()`）没有
+   * 这条终态保证，读 `progress.md`/`events.jsonl` 前必须显式调用这个方法。
+   */
+  async flush(): Promise<void> {
+    await Promise.all([this.progressWrites, this.eventWrites]);
   }
 
-  // ---- 公共方法：归档与清理（保持原有签名兼容） ----
+  // ---- 归档与清理 ----
 
-  /**
-   * 归档（成功完成时调用）：重命名状态目录为 .done 后缀，保留所有中间产物。
-   * vars.json / progress.md / inputs.json / checkpoints/ 全部保留——供后续对话 Read 回溯。
-   */
+  /** 成功收尾：`<taskId>/` → `<taskId>.done/`。 */
   async archive(): Promise<void> {
-    const doneDir = this.dir + DONE_SUFFIX;
-    try {
-      await rm(doneDir, { recursive: true, force: true });
-    } catch {
-      // ignore
-    }
+    await this.flush();
+    if (!this.dir || !existsSync(this.dir)) return;
+    const dest = this.dir.endsWith(DONE_SUFFIX)
+      ? this.dir
+      : this.dir + DONE_SUFFIX;
+    if (dest === this.dir) return;
     try {
-      await rename(this.dir, doneDir);
+      await rm(dest, { recursive: true, force: true });
+      await rename(this.dir, dest);
+      this.dir = dest;
     } catch {
-      // rename 失败时静默（某些文件系统/权限问题），保留原目录
+      // 归档失败不影响任务结论，下次 init 会按未完成处理
     }
   }
 
-  /** 强制清理（/new 或新任务 init 时调用）：删除状态目录（含 .done 归档） */
+  /** 删掉本实例的状态目录（不碰 `.trash/`，那是用户的找回通道）。 */
   async cleanup(): Promise<void> {
-    await rm(this.dir, { recursive: true, force: true }).catch(() => {});
-    await rm(this.dir + DONE_SUFFIX, { recursive: true, force: true }).catch(() => {});
+    if (!this.dir) return;
+    try {
+      await rm(this.dir, { recursive: true, force: true });
+    } catch {
+      /* 忽略 */
+    }
   }
 
-  // ---- 私有方法 ----
-
-  /** 创建全新的空白状态目录（含 checkpoints/ 子目录），并记录声明产物清单。 */
-  private async cleanSlate(
-    name: string,
-    inputs: Record<string, unknown>,
-    taskId: string,
-    declaredArtifacts: string[] = [],
-    defFingerprint?: string,
-  ): Promise<void> {
-    await this.cleanup();
-    await mkdir(this.dir, { recursive: true });
-    await mkdir(join(this.dir, CHECKPOINTS_DIR), { recursive: true });
+  // ---- 声明产物的生命周期 ----
 
-    await this.writeCurrent({
-      name,
-      taskId,
-      status: 'running',
-      startedAt: new Date().toISOString(),
-      artifacts: declaredArtifacts,
-      defFingerprint,
-    });
-
-    await writeFile(join(this.dir, 'inputs.json'), JSON.stringify(inputs, null, 2), 'utf-8');
-    await writeFile(join(this.dir, 'progress.md'), `# ${name}\n\n`, 'utf-8');
+  /**
+   * 把声明里的 glob（`research/04-*.md`）展开成 cwd 下实际匹配的相对路径；
+   * 非 glob 原样保留。越界路径被过滤（fail-closed）。
+   * 声明里写了 glob 却一个都不匹配 → 该声明被丢弃（不存在的产物不参与清理/报告）。
+   */
+  private async expandDeclaredArtifacts(paths: string[]): Promise<string[]> {
+    const out: string[] = [];
+    for (const p of paths) {
+      const safe = safeArtifactPath(this.workingDir, p);
+      if (safe === null) continue;
+      if (!/[*?]/.test(safe)) {
+        // ⚠️ 必须归一成 `/`：`safeArtifactPath` 返回的是**平台分隔符**，而下面
+        // glob 分支里 walkGlob 拼出来的一律是 `/`。两个分支不统一的话，同一份
+        // 声明列表在 Windows 上会同时产出 `out\a.md` 与 `out/b.md` —— 去重
+        // （new Set）失效、与 current.json 里存的旧值比不上、报给用户的路径
+        // 时而斜杠时而反斜杠。`join()` 吃 `/` 没问题，所以统一到 `/` 是安全的。
+        out.push(safe.replace(/\\/g, '/'));
+        continue;
+      }
+      const segs = safe.replace(/\\/g, '/').split('/');
+      const fullRe = new RegExp(
+        `^${segs.map(artifactSegToPattern).join('/')}$`,
+      );
+      out.push(...(await this.walkGlob(this.workingDir, segs, fullRe, '')));
+    }
+    return out;
   }
 
-  /** 读取旧任务的 inputs.json（仲裁时取旧 goal 用），失败返回 null */
-  private async readInputs(): Promise<Record<string, unknown> | null> {
+  private async walkGlob(
+    absDir: string,
+    segs: string[],
+    fullRe: RegExp,
+    relPrefix: string,
+  ): Promise<string[]> {
+    const [head, ...rest] = segs;
+    if (!head) return [];
+    let entries: Dirent[];
     try {
-      const raw = await readFile(join(this.dir, 'inputs.json'), 'utf-8');
-      return JSON.parse(raw);
+      entries = await readdir(absDir, { withFileTypes: true });
     } catch {
-      return null;
+      return [];
     }
+    const headRe = new RegExp(`^${artifactSegToPattern(head)}$`);
+    const results: string[] = [];
+    for (const e of entries) {
+      if (!headRe.test(e.name)) continue;
+      const rel = relPrefix ? `${relPrefix}/${e.name}` : e.name;
+      if (rest.length === 0) {
+        if (e.isFile() && fullRe.test(rel)) results.push(rel);
+      } else if (e.isDirectory()) {
+        results.push(
+          ...(await this.walkGlob(join(absDir, e.name), rest, fullRe, rel)),
+        );
+      }
+    }
+    return results;
   }
 
-  /** 读取 current.json，解析失败或文件不存在返回 null */
-  private async readCurrentState(): Promise<CurrentState | null> {
-    try {
-      const raw = await readFile(join(this.dir, 'current.json'), 'utf-8');
-      return JSON.parse(raw);
-    } catch {
-      return null;
+  /** 声明产物里**实际存在**的那些（completed 报告用；越界的视为不存在）。 */
+  private async existingArtifacts(paths: string[]): Promise<string[]> {
+    const expanded = await this.expandDeclaredArtifacts(paths);
+    return [...new Set(expanded)].filter((rel) =>
+      existsSync(join(this.workingDir, rel)),
+    );
+  }
+
+  /**
+   * 把实际存在的声明产物移入 `<实例目录>.trash/<stamp>/`，保留相对路径结构。
+   * 一个都没成功移走时返回 undefined —— **绝不谎报归档位置**（见文件头注）。
+   */
+  private async archiveDeclaredArtifacts(
+    existingRels: string[],
+    stamp: string,
+  ): Promise<string | undefined> {
+    if (existingRels.length === 0) return undefined;
+    const trashRoot = join(this.dir + TRASH_SUFFIX, stamp);
+    let archived = 0;
+    for (const rel of existingRels) {
+      const dest = join(trashRoot, rel);
+      try {
+        await mkdir(dirname(dest), { recursive: true });
+        await rename(join(this.workingDir, rel), dest);
+        archived++;
+      } catch {
+        // 单个失败不阻断，残留交给后续 rm 兜底
+      }
     }
+    if (archived === 0) return undefined;
+    const display = relative(this.workingDir, trashRoot);
+    return display.startsWith('..') ? trashRoot : display;
   }
 
-  /** 读取归档目录（.done）的 current.json，用于 completed 检测（成功后 dir 被 archive 改名）。 */
-  private async readArchivedState(): Promise<CurrentState | null> {
-    try {
-      const raw = await readFile(join(this.dir + DONE_SUFFIX, 'current.json'), 'utf-8');
-      return JSON.parse(raw);
-    } catch {
-      return null;
+  /** rm 兜底：只删工作流自己声明的产物，且路径强制在 cwd 内。 */
+  private async cleanupDeclaredArtifacts(paths: string[]): Promise<string[]> {
+    const done: string[] = [];
+    for (const rel of await this.expandDeclaredArtifacts(paths)) {
+      const abs = join(this.workingDir, rel);
+      if (!existsSync(abs)) continue;
+      try {
+        await rm(abs, { force: true });
+        done.push(rel);
+      } catch {
+        /* 单个失败不影响整体 */
+      }
     }
+    return done;
   }
 
-  /** 写入 current.json */
-  private async writeCurrent(data: CurrentState): Promise<void> {
-    await writeFile(join(this.dir, 'current.json'), JSON.stringify(data, null, 2), 'utf-8');
+  /** 「先归档再清理」组合。fresh/new-task 的启动清理统一走这里。 */
+  private async archiveThenClean(
+    paths: string[],
+    stamp: string,
+  ): Promise<{ cleaned: string[]; archivedTo?: string }> {
+    const existing = await this.existingArtifacts(paths);
+    const archivedTo = await this.archiveDeclaredArtifacts(existing, stamp);
+    const cleaned = await this.cleanupDeclaredArtifacts(paths);
+    return { cleaned, archivedTo };
   }
 }