minimal-agent 0.12.0 → 0.14.0

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

@@ -1,557 +1,630 @@
 /**
  * ============================================================
- *  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 { computeTaskId, extractGoal, workflowStateDir, } from './taskIdentity.js';
+import { appendFile, mkdir, readFile, readdir, rename, rm, writeFile, } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { computeTaskId, extractGoal, sanitizeWorkflowDirName, sessionStateDir, taskInstanceDir, } from './taskIdentity.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, iteration, stepId) {
-    return `${loopId}${LOOP_CP_SEP}${iteration}${LOOP_CP_SEP}${stepId}`;
-}
-/** 解析复合 checkpoint 文件名；非复合名（普通顶层步）返回 null。 */
-function parseLoopCheckpointName(name) {
-    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) {
-    const skeleton = (list) => (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';
+/** 把 glob 段翻成正则片段（`*` 不跨目录分隔符，`?` 单字符）。 */
+function artifactSegToPattern(seg) {
+    return seg
+        .split(/([*?])/)
+        .map((part) => {
+        if (part === '*')
+            return '[^/]*';
+        if (part === '?')
+            return '[^/]';
+        return part.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+        .join('');
 }
 export class WorkflowState {
-    dir;
+    parentStateDir;
+    /** 任务实例目录（绝对路径）。init 里确定 taskId 后才有值。 */
+    dir = '';
+    /** 当前 session 的目录（其下按 taskId 分实例）。 */
+    sessionDir;
     workingDir;
-    constructor(workingDir, workflowName) {
+    workflowName;
+    taskIdOverride;
+    sessionId;
+    /** init 里算出的任务身份。 */
+    taskId = '';
+    /**
+     * 输入声明。用于让 `extractGoal` 优先取作者标了 `required` 的那个输入 ——
+     * 任务身份与目标锚必须用**同一份**取值规则，否则「拿来算 taskId 的目标」
+     * 和「注入给模型的目标」会指向不同的东西。
+     */
+    defs;
+    progressWrites = Promise.resolve();
+    eventWrites = Promise.resolve();
+    constructor(workingDir, workflowName, sessionId, defs, taskIdOverride, parentStateDir) {
+        this.parentStateDir = parentStateDir;
         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() {
+        return join(this.dir, 'journal.jsonl');
+    }
+    get currentPath() {
+        return join(this.dir, 'current.json');
+    }
+    get supplementsPath() {
+        return join(this.dir, 'supplements.json');
+    }
+    get progressPath() {
+        return join(this.dir, 'progress.md');
+    }
+    get eventsPath() {
+        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, inputs, steps, 
-    // 跨次重跑回退步数（= WorkflowDef.self_heal.backoff），runWorkflow 注入；缺省 1。
-    selfHealBackoff = 1, 
-    // 工作流【声明】的产物路径（相对 cwd，= def.artifacts + step.artifacts），runWorkflow 注入。
-    declaredArtifacts = [], 
-    // 语义仲裁器（hash 不等 + 旧任务未完成时的二审），runWorkflow 注入；缺省直接 new-task。
-    arbitrate) {
-        // 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);
-                await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
-                return {
-                    mode: 'new-task',
-                    startFrom: 0,
-                    cleanedArtifacts: [
-                        ...cleaned,
-                        ...(await this.cleanupStaleDeclared(declaredArtifacts)),
-                    ],
-                };
+    async init(inputs, scriptHash, declaredArtifacts, arbitrate) {
+        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);
+        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。
-            if (arbitrate &&
-                identity.reason === 'hash_diff' &&
-                oldState.name === name &&
-                oldState.status !== 'done' &&
-                // 定义结构已变（或 legacy 无指纹）→ 旧断点不可续，仲裁 resume 无意义，
-                // 跳过仲裁直接走 new-task
-                oldState.defFingerprint === fp) {
-                const prevGoal = extractGoal((await this.readInputs()) ?? {});
-                const newGoal = extractGoal(inputs);
-                let verdict = '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;
-                }
+        // ② 同任务、未完成 → resume（能续多远由 journal 说了算）。
+        if (existsSync(taskDir)) {
+            this.dir = taskDir;
+            const prev = await this.readCurrent();
+            if (prev &&
+                ((prev.scriptHash && prev.scriptHash !== scriptHash) ||
+                    !(await this.treeIntact()))) {
+                // 脚本结构变了：旧 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.
      */
-    async buildResumeInfo(oldState, steps, selfHealBackoff) {
-        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,
-            };
+    async restartChanged(goal, scriptHash, declaredArtifacts, previous, taskDir) {
+        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'));
         }
-        return {
-            mode: 'resume',
-            startFrom: recoveryStart,
-            completedStepIds: completedSteps,
-            failedStep: oldState.lastFailedStep,
-            recoveryStart,
-            lastError: oldState.lastError,
-            capturedVars,
-        };
+        this.dir = taskDir;
+        const info = await this.startFresh(goal, scriptHash, declaredArtifacts);
+        return { ...info, archivedTo: relative(this.workingDir, archiveRoot) };
     }
-    /**
-     * 扫描复合迭代 checkpoint（loopId@@iter@@stepId），产出进行中循环的恢复信息。
-     * 候选条件：顶层 type=loop 步 + 自身无完成 checkpoint（completedTopIds 不含它）。
-     * 多个候选（罕见，前一循环中断后又跑到后一循环）取顶层索引最大者（最远进度）。
-     */
-    async scanLoopResume(steps, completedTopIds, selfHealBackoff) {
-        const cpDir = join(this.dir, CHECKPOINTS_DIR);
-        let files;
+    async startFresh(goal, scriptHash, declaredArtifacts) {
+        // 时间戳只用作回收目录名，不参与任何身份判定 —— 故这里用真实时间是安全的。
+        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 = { mode: 'fresh' };
+        if (cleaned.length > 0)
+            info.cleanedArtifacts = cleaned;
+        if (archivedTo)
+            info.archivedTo = archivedTo;
+        return info;
+    }
+    /** 同 session 下另一个**未完成**任务的目录（有多个时取最近修改的）。 */
+    async findIncompleteSibling() {
+        let entries;
         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();
-        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)
+        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 best = 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;
-            try {
-                const raw = await readFile(join(cpDir, `${loopCheckpointName(loopId, iteration, innerIds[innerIds.length - 1])}.json`), 'utf-8');
-                lastVarsSnapshot = JSON.parse(raw).varsSnapshot;
-            }
-            catch {
-                // 快照读失败不阻断：仍可定位迭代，变量靠顶层 capture 回放兜底
+        // 多个未完成实例时取最近的那个 —— 用户嘴里的「继续」几乎总是指最近一次。
+        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;
             }
-            const candidate = {
-                loopId,
-                loopIndex,
-                iteration,
-                innerStartFrom,
-                completedInnerIds: innerIds,
-                lastVarsSnapshot,
-            };
-            if (!best || candidate.loopIndex > best.loopIndex)
-                best = candidate;
         }
-        return best;
+        return newest;
     }
-    // ---- 公共方法：贯穿补充要求持久化（goalSupplements，runner 写/读） ----
-    /** 追加一条用户补充要求到 supplements.json（resume 跨进程不丢）。 */
-    async appendSupplement(text) {
-        const list = await this.readSupplements();
-        list.push(text);
-        await writeFile(join(this.dir, SUPPLEMENTS_FILE), JSON.stringify(list, null, 2), 'utf-8').catch(() => { });
-    }
-    /** 读取已累积的补充要求列表（无文件 / 解析失败返回 []）。 */
-    async readSupplements() {
+    async countJournalEntries(dir) {
         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') : [];
+            const raw = await readFile(join(dir, 'journal.jsonl'), 'utf8');
+            return raw.split('\n').filter((l) => l.trim() !== '').length;
         }
         catch {
-            return [];
+            return 0;
         }
     }
-    // ---- 公共方法：checkpoint / 失败 / 完成 ----
-    /** 记录单个步骤成功完成（含 capture 变量和 vars 快照） */
-    async recordCheckpoint(stepId, output, captures, varsSnapshot) {
-        const cpDir = join(this.dir, CHECKPOINTS_DIR);
-        await mkdir(cpDir, { recursive: true }).catch(() => { });
-        const data = {
-            stepId,
-            completedAt: new Date().toISOString(),
-            output,
-            captures,
-            varsSnapshot,
-        };
-        await writeFile(join(cpDir, `${stepId}.json`), JSON.stringify(data, null, 2), 'utf-8');
-    }
-    /** 记录步骤失败：更新 current.json 的 lastFailedStep 和 lastError */
-    async recordFailure(stepId, error) {
-        const current = await this.readCurrentState();
-        if (current) {
-            current.lastFailedStep = stepId;
-            current.lastError = error;
-            current.status = 'failed';
-            await this.writeCurrent(current);
-        }
+    // ---- current.json ----
+    async readCurrent() {
+        return this.readCurrentAt(this.dir);
     }
-    /** 标记整个工作流完成 */
-    async markDone() {
-        const current = await this.readCurrentState();
-        if (current) {
-            current.status = 'done';
-            await this.writeCurrent(current);
+    async readCurrentAt(dir) {
+        try {
+            return JSON.parse(await readFile(join(dir, 'current.json'), 'utf8'));
+        }
+        catch {
+            return null;
         }
     }
-    // ---- 公共方法：进度与变量（保持原有签名兼容） ----
-    /** 追加进度日志 */
-    async appendProgress(line) {
-        const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
-        await appendFile(join(this.dir, 'progress.md'), `- ${ts} ${line}\n`, 'utf-8').catch(() => { });
+    async writeCurrent(state) {
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(this.currentPath, JSON.stringify(state, null, 2), 'utf8');
     }
-    /** 写入 vars 快照 */
-    async writeVars(snapshot) {
-        await writeFile(join(this.dir, 'vars.json'), JSON.stringify(snapshot, null, 2), 'utf-8').catch(() => { });
+    /** 记一次失败原因（下次 resume 时报给用户 / 喂给模型）。 */
+    async recordFailure(error, artifacts) {
+        const cur = await this.readCurrent();
+        if (!cur)
+            return;
+        await this.writeCurrent({
+            ...cur,
+            status: 'failed',
+            lastError: error,
+            ...(artifacts ? { artifacts: [...new Set(artifacts)] } : {}),
+        });
     }
     /**
-     * 扫描 checkpoints/ 目录，返回按 steps 数组顺序排列的已完成 step id 列表。
-     * 只返回在 steps[] 中存在的 id（防止 YAML 改动后 orphaned checkpoint 干扰恢复）。
+     * 标记完成（随后 archive() 把目录改名成 `.done`）。
+     *
+     * @param artifacts 本次运行**最终**的声明产物集合。必须传 —— `meta.artifacts`
+     *   只是静态种子，循环体里经 `declareArtifact()` 登记的逐迭代产物只活在内存里。
+     *   不在这里落盘的话，下次 completed 判定会报「本次运行没有声明产物」，
+     *   new-task 清理也会漏掉它们 —— 而且**表现为静默漏档而不是报错**。
+     *   （这条是端到端实跑抓到的：上一轮明明 declareArtifact 了，重跑却报 0 产物。）
      */
-    async scanCheckpoints(steps) {
-        const cpDir = join(this.dir, CHECKPOINTS_DIR);
-        const validIds = new Set(steps.map((s) => s.id));
-        try {
-            const files = await readdir(cpDir);
-            const ids = [];
-            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 markDone(artifacts) {
+        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'))),
+                ],
+            },
+        });
     }
-    /** 加载最近一次成功的 vars 快照 */
-    async loadLastGoodVars() {
+    async writeResult(value) {
+        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() {
         try {
-            const raw = await readFile(join(this.dir, 'vars.json'), 'utf-8');
-            return JSON.parse(raw);
+            return JSON.parse(await readFile(join(this.dir, 'return.json'), 'utf8'));
         }
-        catch {
-            return null;
+        catch (error) {
+            if (!(await this.readCurrent())?.completion)
+                return null; // pre-composition state
+            throw error;
         }
     }
-    /** 加载所有已完成步骤的 capture 变量（用于 resume 时回放到 VarStack） */
-    async loadAllCaptures(stepIds) {
-        const result = {};
-        const cpDir = join(this.dir, CHECKPOINTS_DIR);
-        for (const sid of stepIds) {
+    /** Children live inside the parent's state directory. Moving the parent also
+     * archives all child journals, never another standalone run of the same name. */
+    async treeRecords() {
+        const records = [];
+        const own = await this.readCurrent();
+        if (own)
+            records.push({ dir: this.dir, state: own });
+        const visit = async (dir, depth) => {
+            if (depth > 24)
+                throw new Error('子工作流状态目录嵌套异常');
+            let entries;
             try {
-                const raw = await readFile(join(cpDir, `${sid}.json`), 'utf-8');
-                const cp = JSON.parse(raw);
-                if (cp.captures && Object.keys(cp.captures).length > 0) {
-                    result[sid] = cp.captures;
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (error.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 allArtifacts() {
+        return this.existingArtifacts((await this.treeRecords()).flatMap((r) => r.state.artifacts ?? []));
+    }
+    async treeIntact() {
+        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 {
-                // 单个 checkpoint 读失败不阻断整体
+                return false;
             }
         }
-        return result;
+        return true;
     }
-    // ---- 私有方法：声明式产物生命周期 ----
-    /** 删除工作流【声明】的产物文件（相对 cwd），用于 new-task 清理旧任务残留（如旧 PLAN.md）。
-     *  仅删工作流自己声明的产物、仅 force-rm 文件，scoped 安全。返回清理过的路径列表。 */
-    async cleanupDeclaredArtifacts(paths) {
-        for (const p of paths) {
-            await rm(join(this.workingDir, p), { force: true }).catch(() => { });
+    // ---- 补充要求 ----
+    /**
+     * 追加一条用户补充要求。去重：已有条目的前缀重复不再追加。
+     *
+     * 持久化的理由：补充要求要与原始目标**同等贯穿始终**，跨进程 resume 时不能丢。
+     */
+    async appendSupplement(text) {
+        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');
+    }
+    async readSupplements() {
+        try {
+            const parsed = JSON.parse(await readFile(this.supplementsPath, 'utf8'));
+            return Array.isArray(parsed) ? parsed.map((s) => String(s)) : [];
+        }
+        catch {
+            return [];
         }
-        return paths;
     }
-    /** 从声明产物路径里过滤出 cwd 下【实际存在】的文件（completed 报真实产物用）。 */
-    existingArtifacts(paths) {
-        return paths.filter((p) => existsSync(join(this.workingDir, p)));
+    // ---- 人类可读进度 ----
+    /**
+     * 追加一行进度。
+     *
+     * 存在理由：TUI 的 scrollback 会被刷掉，而排障常常发生在「跑完之后」。
+     * 落盘的 progress.md 是唯一还能回看的现场（provider 的真实报错也写在这里）。
+     */
+    async appendProgress(line) {
+        this.progressWrites = this.progressWrites.then(async () => {
+            try {
+                await mkdir(this.dir, { recursive: true });
+                await appendFile(this.progressPath, `${line}\n`, 'utf8');
+            }
+            catch {
+                // 进度日志写失败不该影响任务本身
+            }
+        });
+        await this.progressWrites;
     }
-    /** 清理【实际存在】的本次声明产物（fresh/new-task 启动时清残留孤儿），返回真正删掉的路径。 */
-    async cleanupStaleDeclared(declaredArtifacts) {
-        return this.cleanupDeclaredArtifacts(this.existingArtifacts(declaredArtifacts));
+    async appendEvent(event) {
+        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;
     }
-    // ---- 公共方法：归档与清理（保持原有签名兼容） ----
     /**
-     * 归档（成功完成时调用）：重命名状态目录为 .done 后缀，保留所有中间产物。
-     * vars.json / progress.md / inputs.json / checkpoints/ 全部保留——供后续对话 Read 回溯。
+     * 等待所有已排队的 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() {
+        await Promise.all([this.progressWrites, this.eventWrites]);
+    }
+    // ---- 归档与清理 ----
+    /** 成功收尾：`<taskId>/` → `<taskId>.done/`。 */
     async archive() {
-        const doneDir = this.dir + DONE_SUFFIX;
+        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 rm(doneDir, { recursive: true, force: true });
+            await rm(dest, { recursive: true, force: true });
+            await rename(this.dir, dest);
+            this.dir = dest;
         }
         catch {
-            // ignore
-        }
-        try {
-            await rename(this.dir, doneDir);
-        }
-        catch {
-            // rename 失败时静默（某些文件系统/权限问题），保留原目录
+            // 归档失败不影响任务结论，下次 init 会按未完成处理
         }
     }
-    /** 强制清理（/new 或新任务 init 时调用）：删除状态目录（含 .done 归档） */
+    /** 删掉本实例的状态目录（不碰 `.trash/`，那是用户的找回通道）。 */
     async cleanup() {
-        await rm(this.dir, { recursive: true, force: true }).catch(() => { });
-        await rm(this.dir + DONE_SUFFIX, { recursive: true, force: true }).catch(() => { });
-    }
-    // ---- 私有方法 ----
-    /** 创建全新的空白状态目录（含 checkpoints/ 子目录），并记录声明产物清单。 */
-    async cleanSlate(name, inputs, taskId, declaredArtifacts = [], defFingerprint) {
-        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');
-    }
-    /** 读取旧任务的 inputs.json（仲裁时取旧 goal 用），失败返回 null */
-    async readInputs() {
+        if (!this.dir)
+            return;
         try {
-            const raw = await readFile(join(this.dir, 'inputs.json'), 'utf-8');
-            return JSON.parse(raw);
+            await rm(this.dir, { recursive: true, force: true });
         }
         catch {
-            return null;
+            /* 忽略 */
+        }
+    }
+    // ---- 声明产物的生命周期 ----
+    /**
+     * 把声明里的 glob（`research/04-*.md`）展开成 cwd 下实际匹配的相对路径；
+     * 非 glob 原样保留。越界路径被过滤（fail-closed）。
+     * 声明里写了 glob 却一个都不匹配 → 该声明被丢弃（不存在的产物不参与清理/报告）。
+     */
+    async expandDeclaredArtifacts(paths) {
+        const out = [];
+        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;
     }
-    /** 读取 current.json，解析失败或文件不存在返回 null */
-    async readCurrentState() {
+    async walkGlob(absDir, segs, fullRe, relPrefix) {
+        const [head, ...rest] = segs;
+        if (!head)
+            return [];
+        let entries;
         try {
-            const raw = await readFile(join(this.dir, 'current.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 = [];
+        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;
     }
-    /** 读取归档目录（.done）的 current.json，用于 completed 检测（成功后 dir 被 archive 改名）。 */
-    async readArchivedState() {
-        try {
-            const raw = await readFile(join(this.dir + DONE_SUFFIX, 'current.json'), 'utf-8');
-            return JSON.parse(raw);
+    /** 声明产物里**实际存在**的那些（completed 报告用；越界的视为不存在）。 */
+    async existingArtifacts(paths) {
+        const expanded = await this.expandDeclaredArtifacts(paths);
+        return [...new Set(expanded)].filter((rel) => existsSync(join(this.workingDir, rel)));
+    }
+    /**
+     * 把实际存在的声明产物移入 `<实例目录>.trash/<stamp>/`，保留相对路径结构。
+     * 一个都没成功移走时返回 undefined —— **绝不谎报归档位置**（见文件头注）。
+     */
+    async archiveDeclaredArtifacts(existingRels, stamp) {
+        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 兜底
+            }
         }
-        catch {
-            return null;
+        if (archived === 0)
+            return undefined;
+        const display = relative(this.workingDir, trashRoot);
+        return display.startsWith('..') ? trashRoot : display;
+    }
+    /** rm 兜底：只删工作流自己声明的产物，且路径强制在 cwd 内。 */
+    async cleanupDeclaredArtifacts(paths) {
+        const done = [];
+        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 */
-    async writeCurrent(data) {
-        await writeFile(join(this.dir, 'current.json'), JSON.stringify(data, null, 2), 'utf-8');
+    /** 「先归档再清理」组合。fresh/new-task 的启动清理统一走这里。 */
+    async archiveThenClean(paths, stamp) {
+        const existing = await this.existingArtifacts(paths);
+        const archivedTo = await this.archiveDeclaredArtifacts(existing, stamp);
+        const cleaned = await this.cleanupDeclaredArtifacts(paths);
+        return { cleaned, archivedTo };
     }
 }