@tea-agent/loop-agent 0.1.0

package/dist/workflows/loop/events.js

@@ -0,0 +1,25 @@
+import { appendFile, readFile } from "node:fs/promises";
+import { getLoopPaths } from "./paths.js";
+export async function appendLoopEvent(repoRoot, taskId, input) {
+    const now = new Date().toISOString();
+    const entry = {
+        schemaVersion: 1,
+        id: `${now}-${input.type}`,
+        type: input.type,
+        taskId,
+        round: input.round ?? 0,
+        message: input.message,
+        refs: input.refs ?? [],
+        recordedAt: now,
+    };
+    await appendFile(getLoopPaths(repoRoot, taskId).eventsPath, `${JSON.stringify(entry)}\n`, "utf-8");
+    return entry;
+}
+export async function readLoopEvents(repoRoot, taskId) {
+    const raw = await readFile(getLoopPaths(repoRoot, taskId).eventsPath, "utf-8").catch(() => "");
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}

package/dist/workflows/loop/hash.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { listTaskSourceFiles } from "../../task/runtime.js";
+export function sha256Text(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+export async function hashFileIfPresent(filePath) {
+    try {
+        return sha256Text(await readFile(filePath, "utf-8"));
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return "";
+        }
+        throw error;
+    }
+}
+export async function hashTaskSource(repoRoot, taskId) {
+    const files = await listTaskSourceFiles(repoRoot, taskId);
+    const sourceDir = path.join(repoRoot, ".harness", "tasks", taskId, "source");
+    const chunks = [];
+    for (const file of files.sort()) {
+        const abs = path.isAbsolute(file) ? file : path.join(sourceDir, file);
+        const relative = path.relative(sourceDir, abs);
+        chunks.push(`${relative}\n${await readFile(abs, "utf-8")}`);
+    }
+    return sha256Text(chunks.join("\n--- source file ---\n"));
+}

package/dist/workflows/loop/index.js

@@ -0,0 +1,8 @@
+export { getLoopPaths } from "./paths.js";
+export { initializeLoop, loadLoopState, refreshLoopState, saveLoopState, } from "./state.js";
+export { appendLoopRound, readLoopRounds } from "./rounds.js";
+export { rewriteLoopContext } from "./context.js";
+export { appendLoopSignal, drainLoopSignals, parseLoopSignalType, pendingLoopSignals, readLoopSignals, } from "./signals.js";
+export { appendLoopEvent, readLoopEvents } from "./events.js";
+export { generateLoopCloseout } from "./closeout.js";
+export { buildLoopPiReviewPrompt, buildLoopCursorFixPrompt, decideNextLoopAutoAction, resolveLoopShellVerifyCommands, runLoopAuto, runLoopCursorFix, runLoopDagAction, runLoopPiReview, runLoopShellVerification, runLoopWorkflowGateSignalAction, runLoopWorkflowAction, validateLoopCursorFixPolicy, } from "./actions.js";

package/dist/workflows/loop/paths.js

@@ -0,0 +1,17 @@
+import path from "node:path";
+import { getTaskDir } from "../../task/runtime.js";
+export function getLoopPaths(repoRoot, taskId) {
+    const loopDir = path.join(getTaskDir(repoRoot, taskId), "loop");
+    return {
+        loopDir,
+        objectivePath: path.join(loopDir, "objective.md"),
+        contextPath: path.join(loopDir, "context.md"),
+        statePath: path.join(loopDir, "state.json"),
+        roundsPath: path.join(loopDir, "rounds.jsonl"),
+        signalsPath: path.join(loopDir, "signals.jsonl"),
+        closeoutPath: path.join(loopDir, "closeout.md"),
+        eventsPath: path.join(loopDir, "events.jsonl"),
+        verificationDir: path.join(loopDir, "verification"),
+        reviewDir: path.join(loopDir, "reviews"),
+    };
+}

package/dist/workflows/loop/rounds.js

@@ -0,0 +1,81 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { getLoopPaths } from "./paths.js";
+import { refreshLoopState } from "./state.js";
+import { appendLoopEvent } from "./events.js";
+function statusForDecision(decision) {
+    if (decision === "continue")
+        return "running";
+    if (decision === "pause")
+        return "paused";
+    return decision;
+}
+export async function readLoopRounds(repoRoot, taskId) {
+    const raw = await readFile(getLoopPaths(repoRoot, taskId).roundsPath, "utf-8");
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export async function appendLoopRound(repoRoot, taskId, input) {
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const entry = {
+        schemaVersion: 1,
+        round: rounds.length + 1,
+        recordedAt: new Date().toISOString(),
+        action: input.action,
+        refs: input.refs ?? [],
+        result: input.result,
+        verification: input.verification ?? "",
+        lesson: input.lesson,
+        next: input.next,
+        decision: input.decision,
+        failureCategory: input.failureCategory ?? "",
+        completedCriteria: input.completedCriteria ?? [],
+    };
+    const paths = getLoopPaths(repoRoot, taskId);
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "round_start",
+        round: entry.round,
+        message: `recording round ${entry.round} action ${entry.action}`,
+        refs: entry.refs,
+    });
+    await writeFile(paths.roundsPath, `${rounds.map((round) => JSON.stringify(round)).join("\n")}${rounds.length > 0 ? "\n" : ""}${JSON.stringify(entry)}\n`, "utf-8");
+    const previousState = await refreshLoopState(repoRoot, taskId, {
+        status: statusForDecision(entry.decision),
+        round: entry.round,
+        lastDecision: entry.decision,
+        lastAction: entry.action,
+        lastExecutorRef: entry.refs[0] ?? "",
+        openFrontier: entry.next ? [entry.next] : [],
+        completedCriteria: entry.completedCriteria,
+    });
+    if (entry.failureCategory) {
+        await refreshLoopState(repoRoot, taskId, {
+            failureStreak: {
+                category: entry.failureCategory,
+                count: previousState.failureStreak.category === entry.failureCategory
+                    ? previousState.failureStreak.count + 1
+                    : 1,
+            },
+        });
+    }
+    else if (previousState.failureStreak.category) {
+        await refreshLoopState(repoRoot, taskId, {
+            failureStreak: { category: "", count: 0 },
+        });
+    }
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "action_finish",
+        round: entry.round,
+        message: `${entry.action}: ${entry.result}`,
+        refs: entry.refs,
+    });
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "decision",
+        round: entry.round,
+        message: `decision=${entry.decision}; next=${entry.next}`,
+        refs: entry.refs,
+    });
+    return entry;
+}

package/dist/workflows/loop/signals.js

@@ -0,0 +1,55 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { getLoopPaths } from "./paths.js";
+import { LOOP_SIGNAL_TYPES, } from "./types.js";
+export function parseLoopSignalType(value) {
+    if (LOOP_SIGNAL_TYPES.includes(value)) {
+        return value;
+    }
+    throw new Error(`invalid loop signal type: ${value} (expected ${LOOP_SIGNAL_TYPES.join("|")})`);
+}
+export async function readLoopSignals(repoRoot, taskId) {
+    const raw = await readFile(getLoopPaths(repoRoot, taskId).signalsPath, "utf-8").catch(() => "");
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export async function appendLoopSignal(repoRoot, taskId, input) {
+    const signals = await readLoopSignals(repoRoot, taskId);
+    const now = new Date().toISOString();
+    const entry = {
+        schemaVersion: 1,
+        id: `${now}-${signals.length + 1}`,
+        type: input.type,
+        message: input.message.trim(),
+        urgent: input.urgent ?? false,
+        refs: input.refs ?? [],
+        createdAt: now,
+        drainedAt: "",
+    };
+    if (!entry.message) {
+        throw new Error("loop signal message cannot be empty");
+    }
+    await writeLoopSignals(repoRoot, taskId, [...signals, entry]);
+    return entry;
+}
+export function pendingLoopSignals(signals) {
+    return signals.filter((signal) => !signal.drainedAt);
+}
+export async function drainLoopSignals(repoRoot, taskId, ids) {
+    if (ids.length === 0)
+        return readLoopSignals(repoRoot, taskId);
+    const idSet = new Set(ids);
+    const now = new Date().toISOString();
+    const signals = await readLoopSignals(repoRoot, taskId);
+    const drained = signals.map((signal) => idSet.has(signal.id) && !signal.drainedAt
+        ? { ...signal, drainedAt: now }
+        : signal);
+    await writeLoopSignals(repoRoot, taskId, drained);
+    return drained;
+}
+async function writeLoopSignals(repoRoot, taskId, signals) {
+    await writeFile(getLoopPaths(repoRoot, taskId).signalsPath, signals.map((signal) => JSON.stringify(signal)).join("\n") +
+        (signals.length > 0 ? "\n" : ""), "utf-8");
+}

package/dist/workflows/loop/state.js

@@ -0,0 +1,116 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { getTaskDir } from "../../task/runtime.js";
+import { repoRelativePath } from "../../shared/path-refs.js";
+import { hashFileIfPresent, hashTaskSource } from "./hash.js";
+import { getLoopPaths } from "./paths.js";
+import { defaultContext, defaultObjective } from "./templates.js";
+import { appendLoopEvent } from "./events.js";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+function rel(repoRoot, filePath) {
+    return repoRelativePath(repoRoot, filePath);
+}
+export async function buildLoopState(repoRoot, taskId, paths = getLoopPaths(repoRoot, taskId), previous) {
+    const now = new Date().toISOString();
+    const objectiveHash = await hashFileIfPresent(paths.objectivePath);
+    const contextHash = await hashFileIfPresent(paths.contextPath);
+    const sourceHash = await hashTaskSource(repoRoot, taskId);
+    const previousSourceHash = previous?.sourceHash ?? sourceHash;
+    return {
+        schemaVersion: 1,
+        taskId,
+        status: previous?.status ?? "draft",
+        round: previous?.round ?? 0,
+        maxRounds: previous?.maxRounds ?? 8,
+        objectivePath: rel(repoRoot, paths.objectivePath),
+        contextPath: rel(repoRoot, paths.contextPath),
+        roundsPath: rel(repoRoot, paths.roundsPath),
+        objectiveHash,
+        contextHash,
+        sourceHash,
+        freshness: {
+            objectiveHash,
+            contextHash,
+            sourceHash,
+            sourceStale: sourceHash !== previousSourceHash,
+            lastCheckedAt: now,
+        },
+        lastDecision: previous?.lastDecision ?? "init",
+        lastAction: previous?.lastAction ?? "init",
+        lastExecutorRef: previous?.lastExecutorRef ?? "",
+        openFrontier: previous?.openFrontier ?? ["choose the next bounded action"],
+        completedCriteria: previous?.completedCriteria ?? [],
+        failureStreak: previous?.failureStreak ?? { category: "", count: 0 },
+        createdAt: previous?.createdAt ?? now,
+        updatedAt: now,
+    };
+}
+export async function saveLoopState(repoRoot, taskId, state) {
+    const paths = getLoopPaths(repoRoot, taskId);
+    await writeFile(paths.statePath, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+}
+export async function loadLoopState(repoRoot, taskId) {
+    const paths = getLoopPaths(repoRoot, taskId);
+    const raw = await readFile(paths.statePath, "utf-8");
+    return JSON.parse(raw);
+}
+export async function refreshLoopState(repoRoot, taskId, patch = {}) {
+    const previous = await loadLoopState(repoRoot, taskId);
+    const state = await buildLoopState(repoRoot, taskId, undefined, {
+        ...previous,
+        ...patch,
+    });
+    await saveLoopState(repoRoot, taskId, state);
+    return state;
+}
+export async function initializeLoop(repoRoot, taskId, options = {}) {
+    const taskDir = getTaskDir(repoRoot, taskId);
+    if (!(await exists(taskDir))) {
+        throw new Error(`task does not exist: ${taskId}`);
+    }
+    const paths = getLoopPaths(repoRoot, taskId);
+    const stateExists = await exists(paths.statePath);
+    if (stateExists && !options.recover) {
+        throw new Error(`loop already initialized for task: ${taskId}`);
+    }
+    await mkdir(paths.loopDir, { recursive: true });
+    if (!(await exists(paths.objectivePath))) {
+        await writeFile(paths.objectivePath, defaultObjective(taskId), "utf-8");
+    }
+    if (!(await exists(paths.contextPath))) {
+        await writeFile(paths.contextPath, defaultContext(), "utf-8");
+    }
+    if (!(await exists(paths.roundsPath))) {
+        await writeFile(paths.roundsPath, "", "utf-8");
+    }
+    if (!(await exists(paths.signalsPath))) {
+        await writeFile(paths.signalsPath, "", "utf-8");
+    }
+    if (!(await exists(paths.eventsPath))) {
+        await writeFile(paths.eventsPath, "", "utf-8");
+    }
+    const previous = stateExists ? await loadLoopState(repoRoot, taskId) : undefined;
+    const state = await buildLoopState(repoRoot, taskId, paths, {
+        ...previous,
+        maxRounds: options.maxRounds ?? previous?.maxRounds ?? 8,
+    });
+    await saveLoopState(repoRoot, taskId, state);
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "loop_start",
+        message: stateExists ? "loop recovered" : "loop initialized",
+    });
+    return { created: !stateExists, paths, state };
+}

package/dist/workflows/loop/templates.js

@@ -0,0 +1,54 @@
+export function defaultObjective(taskId) {
+    return [
+        "# Objective",
+        "",
+        "## Goal",
+        `- Complete the long-running task ${taskId}.`,
+        "",
+        "## Success Criteria",
+        "- Loop success criteria are copied or summarized from source/需求.md.",
+        "- Completion requires current shell verification evidence.",
+        "",
+        "## Scope",
+        "- In: work described by the task source materials.",
+        "- Out: unrelated repository changes.",
+        "",
+        "## Constraints",
+        "- Allowed paths: see source/执行约束.md.",
+        "- Forbidden paths: see source/执行约束.md.",
+        "- Verification: see source/执行约束.md.",
+        "",
+        "## Completion Policy",
+        "- Required evidence: shell verification output and referenced executor facts.",
+        "- Required review: as specified by the task source or DAG gates.",
+        "- Stop conditions: complete, paused, blocked, or max rounds reached.",
+        "",
+    ].join("\n");
+}
+export function defaultContext() {
+    return [
+        "# Loop Context",
+        "",
+        "## Current State",
+        "- Completed: none recorded yet.",
+        "- Open frontier: initialize loop and choose the next bounded action.",
+        "- Current hypothesis: storage state must be established before executor integration.",
+        "",
+        "## Verified Facts",
+        "- No loop rounds have been recorded yet.",
+        "",
+        "## Last Round Lessons",
+        "- What worked: none yet.",
+        "- What failed: none yet.",
+        "- Avoid next round: do not treat chat history as durable state.",
+        "",
+        "## Next Suggested Action",
+        "- Action: record a bounded round with canonical evidence refs.",
+        "- Why: loop context should be derived from durable facts.",
+        "- Expected evidence: rounds.jsonl entry and rewritten context.md.",
+        "",
+        "## Risk Notes",
+        "- Completion still requires deterministic verification.",
+        "",
+    ].join("\n");
+}

package/dist/workflows/loop/types.js

@@ -0,0 +1,28 @@
+export const LOOP_STATUSES = [
+    "draft",
+    "running",
+    "paused",
+    "blocked",
+    "complete",
+];
+export const LOOP_DECISIONS = [
+    "continue",
+    "pause",
+    "blocked",
+    "complete",
+];
+export const LOOP_EVENT_TYPES = [
+    "loop_start",
+    "round_start",
+    "action_start",
+    "action_finish",
+    "context_rewrite",
+    "decision",
+    "loop_finish",
+];
+export const LOOP_SIGNAL_TYPES = [
+    "human_followup",
+    "approval",
+    "scope_changed",
+    "review_feedback",
+];

package/docs/README.md

@@ -0,0 +1,62 @@
+# Documentation Index
+
+`docs/` is the governance root for loop-agent. It contains workflow rules, methodology, verification rules, execution plans, reports, progress logs, decisions, and reusable templates.
+
+Top-level `AGENTS.md` is the operating map. Durable knowledge belongs here: decisions, contracts, plans, verification evidence, debugging notes, and reusable process rules should be recorded under `docs/` instead of staying only in chat.
+
+## Core Documents
+
+- `development-principles.md` — repository development principles
+- `feature-workflow.md` — bounded feature workflow
+- `verification-matrix.md` — verification command selection
+- `loop-agent-harness.md` — runtime and command surface overview
+- `agent-dag-runner.md` — Agent DAG runner guide
+- `cursor-executor-usage.md` — Cursor executor usage
+- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine roadmap and fit analysis
+
+## Methodology
+
+- `harness-methodology-tdd.md` — TDD discipline for behavior changes and bug fixes
+- `harness-methodology-verification.md` — verification discipline before completion claims
+- `harness-methodology-debugging.md` — systematic debugging workflow before fixes
+
+## Artifacts
+
+- `design/README.md` — draft design notes and implementation contracts
+- `exec-plans/active/README.md` — active execution plans
+- `exec-plans/completed/README.md` — completed execution plans
+- `progress/README.md` — progress handoff logs
+- `reports/README.md` — verification and audit reports
+- `decisions/README.md` — architecture decisions
+- `templates/` — reusable planning, reporting, and DAG templates
+
+## Repository Skills
+
+- `../skills/loop-agent/` — loop-agent's own skill instructions and references.
+- Each additional skill uses its own subdirectory under repository-root `../skills/`; these local copies are referenced by DAG templates so maintenance does not depend on external agent skill directories.
+
+## Templates
+
+- `templates/project-start-checklist.md` — pre-work checklist
+- `templates/feature-spec.md` — bounded feature specification
+- `templates/sprint-contract.md` — implementation contract and acceptance criteria
+- `templates/exec-plan.md` — execution plan for non-trivial work
+- `templates/progress-log.md` — progress and handoff log
+- `templates/qa-report.md` — verification and QA evidence
+- `templates/adr.md` — architecture decision record
+
+## Maintenance
+
+After docs changes, run:
+
+```bash
+bash scripts/check-repo.sh
+```
+
+On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Use platform-native paths for actual file operations; reserve `/` for repo refs, JSON/Markdown evidence refs, and glob conventions.
+
+For a full local gate, run:
+
+```bash
+bash scripts/ci.sh
+```

package/docs/agent-dag-recovery-playbook.md

@@ -0,0 +1,158 @@
+# Agent DAG Recovery Playbook
+
+> **关联**：[`agent-dag-runner.md`](agent-dag-runner.md)（CLI 与 run 语义）· [`templates/agent-dag-decision-gate.prompt.md`](templates/agent-dag-decision-gate.prompt.md)（Decision Gate 消费 recovery 证据）
+
+## 定位
+
+Agent DAG **recovery planning 是只读、派生、advisory** 的。`dag report` 与 `buildDagDecisionGateEvidence()` 从 `.harness/dag-runs/` 的 canonical facts 聚合 `normalizedFailureCategory` → `recoveryRecommendation`，供人工或 Decision Gate prompt 消费。
+
+**非目标（本 playbook 不覆盖、runner 不实现）：**
+
+- 自动 retry / resume 节点执行
+- 修改 `completed/` 或 `paused/` 下的历史 run facts
+- 把 `autoRetryEligible` 当作 runtime 触发器
+- 仅凭 recovery 派生字段自动 approve Decision Gate
+
+## 快速命令
+
+```bash
+cd .
+
+# 全局 runtime 健康（active/paused/completed 摘要 + healthIssues；advisoryOnly）
+npm run dev -- dag doctor
+
+# 单 run 生命周期（approvalFlow、hasHumanApproval、nextRecommendedAction）
+npm run dev -- dag status --run-id <run-id>
+
+# 聚焦最新 paused run（--paused-latest ≡ --lifecycle paused --latest）
+npm run dev -- dag report --paused-latest [--json|--markdown]
+
+# 默认 compact Markdown 表格
+npm run dev -- dag report --run-id <run-id>
+
+# 机器可读 JSON（含 primaryFailure / primaryRecovery / downstreamSkippedNodes）
+npm run dev -- dag report --run-id <run-id> --json
+
+# 人类交接 Recovery Plan（四段结构化 Markdown）
+npm run dev -- dag report --run-id <run-id> --markdown
+
+# 过滤器
+npm run dev -- dag report --failed-only                              # 仅失败/需恢复
+npm run dev -- dag report --latest --failed-only                    # 最新一条需恢复 run
+npm run dev -- dag report --action retry-node                       # 按 primaryRecovery.action 筛选
+npm run dev -- dag report --lifecycle paused --action resume-or-reject
+
+# Decision Gate envelope dry-run（不 resume/retry；validate 无效时 exit 1）
+npm run dev -- dag decision inspect --run-id <run-id> [--node-id <node-id>]
+npm run dev -- dag decision validate --run-id <run-id> [--node-id <node-id>]
+```
+
+### Paused run 操作员路径
+
+1. `dag report --paused-latest --json` 或 `dag doctor` — 定位最新 paused run 与 `primaryRecovery`
+2. `dag status --run-id <id>` — 读 `approvalFlow`、`escalationArtifactPath`、`pendingNodes`
+3. （可选）`dag decision validate --run-id <id>` — envelope preflight
+4. `dag approve --run-id <id> --option <option-id>` → `dag resume --run-id <id>`；或 `dag reject --run-id <id> --reason "..."`
+
+精确 approval 顺序见 [`agent-dag-runner.md`](agent-dag-runner.md) §Paused lifecycle。
+
+Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-decision-evidence.ts`）从 `DagRunReportEntry` 生成 prompt-friendly 摘要，字段与 JSON report 对齐，**不**写回 run state。
+
+## `dag report --json` schema 锁定
+
+- **Schema 文件**：`docs/templates/agent-dag-report.schema.json`
+- **Envelope**：`{ schemaVersion: 1, runs: DagRunReportEntry[] }`
+- **稳定消费字段**（Decision Gate / tooling 应依赖）：`primaryFailure`、`primaryRecovery`、`downstreamSkippedNodes`、`recoveryRecommendation`、`normalizedFailureCategory`；node 级 `decisionEnvelope`、`artifacts`；paused 级 `pausedByNodeId`、`pauseReason`
+- **测试**：`./test/dag-report.test.ts` §`dag report JSON schema contract` 对 fixture run 做 schema 校验
+- **变更策略**：breaking 字段变更须 bump `schemaVersion` 并同步 schema 文件与测试
+
+## Recovery Action 枚举
+
+| Action | 含义 | 典型触发 |
+|--------|------|----------|
+| `none` | 无需恢复 | 成功完成 |
+| `monitor` | 进行中，等待结束 | `PENDING` / `RUNNING` |
+| `retry-node` | 修复瞬态条件后可重跑节点 | timeout；executor 瞬态（network/quota/rate-limit/unavailable） |
+| `rerun-after-fix` | 先修根因再重跑 | auth、validation、shell-command、static-error、非瞬态 executor |
+| `resume-or-reject` | 人工审批后继续或拒绝 | paused + decision-envelope / human-required |
+| `manual-review` | 人工审查后再定路径 | write-guard、human-rejected、unknown、非 paused 的 decision-envelope |
+| `inspect-upstream` | 先查上游失败 | SKIPPED 下游节点 |
+| `unknown` | 未映射类别（不应出现在正常派生路径） | 内部兜底 |
+
+## 类别 → 动作 → 操作员指引
+
+| Normalized category | Recovery action | Operator guidance | Anti-patterns |
+|---------------------|-----------------|-------------------|---------------|
+| `success` | `none` | 归档验收；按需 review artifacts | 对成功 run 发起 retry |
+| `timeout` | `retry-node` | 查日志/artifacts 确认瞬态；人工重跑节点 | 未查根因就循环重试；指望 runner 自动 retry |
+| `executor`（network/quota/rate-limit/unavailable） | `retry-node` | 等后端/配额恢复后重跑 | 把 auth/validation 误判为瞬态 executor |
+| `executor`（其他 raw） | `rerun-after-fix` | 查 executor.jsonl、node result | 盲目 retry 非瞬态 backend 错误 |
+| `auth` | `rerun-after-fix` | 更新 API key/凭证后重跑 | 在凭证未修复时 retry |
+| `write-guard` | `manual-review` | 审 writeSet/writePolicy、prompt、result.summary | read-only 节点写根 `artifacts/`；扩大 writeSet 掩盖违规 |
+| `validation` | `rerun-after-fix` | 修 schema/output/test 后再跑 | 跳过验证直接 approve |
+| `shell-command` | `rerun-after-fix` | 读 stdout/stderr、修命令或 repo 状态 | 只重跑 shell 不改命令 |
+| `static-error` | `rerun-after-fix` | 查 static config 与 emitted markdown | 当 LLM 节点 retry |
+| `decision-envelope`（paused） | `resume-or-reject` | `dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` → `dag resume --run-id <id>` | 未读 envelope 就 approve；用 recovery 字段单独 auto-approve |
+| `decision-envelope`（非 paused） | `manual-review` | 读 decision.envelope.json / validation artifact | 绕过 Decision Gate schema |
+| `human-required`（paused） | `resume-or-reject` | 提供人工输入 → approve/resume | 在 escalation 未解决时 resume |
+| `human-required`（非 paused） | `manual-review` | 读 human-escalation artifacts | 忽略 `requiresHuman` |
+| `human-rejected` | `manual-review` | 修订 contract/source；**新 run** | 对同一 contract 自动 retry |
+| `skipped` | `inspect-upstream` | 修上游 ERROR/SKIPPED 再考虑下游 | 直接 retry SKIPPED 节点 |
+| `unknown` | `manual-review` | 读 state.json、executor.jsonl、node artifacts | 假设 `autoRetryEligible` 会触发执行 |
+
+## Handoff Recovery Plan 结构
+
+`dag report --markdown` 的 **Recovery Plan** 含四段（与 JSON 稳定字段一一对应）：
+
+1. **Primary Failure** — `primaryFailure`（node 或 run scope）
+2. **Recovery Action** — `primaryRecovery`（action、summary、reason、flags、commandHint）
+3. **Blocked Downstream / Skipped Nodes** — `downstreamSkippedNodes`
+4. **Recommended Operator Action** — 面向操作员的步骤摘要
+
+保存 handoff 时重定向到平台临时目录或 `docs/reports/`，不要写入 `.harness/dag-runs/`。
+
+## Decision Gate 消费约定
+
+1. 优先 `dag report --json` 或 `buildDagDecisionGateEvidence()` 的 **verified** 派生摘要。
+2. 映射到 `decision` / `nextAction` 须保守；recovery 证据是 **advisory only, not an execution directive**。
+3. `autoRetryEligible: true` 仅表示「规划上可人工重试」，**不**触发 runner。
+4. paused run 的人类路径仍是 M5 CLI：`dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` / `dag resume --run-id <id>`（见 [`agent-dag-runner.md`](agent-dag-runner.md) §Decision Gate）。
+5. Envelope 干跑：`dag decision inspect|validate` 重解析 run facts；`validate` 无效时 exit 1；**不**写 artifact、**不** resume。
+
+## Active stale run recovery（advisory detection）
+
+`dag doctor` 与 `dag status` 通过 `detectDagRunHealthIssues()` 检测 lifecycle 不一致，**不** mutate run facts。
+
+| Code | 典型场景 | 操作员指引 |
+|------|----------|------------|
+| `terminal-in-active` | run 已完成但 `active/<run-id>/` 残留 | 对照 `completed/` canonical facts；手动 archive 或删除 stale 目录 |
+| `paused-in-active` | pause 后目录未迁至 `paused/` | `dag doctor` 诊断；修复 facts 后再 approve/resume |
+| `lifecycle-status-mismatch` | `paused/` 下 status 非 paused | 同上 |
+| `missing-approval-artifact` | approve 后 artifact 缺失 | 勿 resume；re-approve 或 restore artifact |
+| `non-terminal-in-completed` | completed 目录 status 异常 | manual-review only |
+| `run-id-mismatch` / `missing-state-json` | 目录损坏或命名错误 | Inspect；勿 auto-mutate completed facts |
+
+**Deferred runtime**：无 `dag recover apply` 或自动 cleanup；未来可能增加只读 `dag recover plan`（设计占位，未实现）。
+
+## 事实源与边界
+
+| 类型 | 位置 | 规则 |
+|------|------|------|
+| Canonical run facts | `.harness/dag-runs/{active\|paused\|completed}/<run-id>/` | **只读**；report 不写回 |
+| 派生 report | stdout / 重定向文件 | 可随时再生 |
+| 工作块摘要 | 根 `artifacts/` | 非 per-run 历史；read-only DAG 节点不得写 |
+
+## 验证
+
+```bash
+cd . && npx vitest run \
+  test/dag-report.test.ts \
+  test/dag-recovery-recommendation.test.ts \
+  test/dag-decision-gate-recovery-dogfood.test.ts \
+  test/dag-decision-evidence.test.ts \
+  test/dag-decision-envelope.test.ts \
+  test/dag-approve-resume.test.ts \
+  test/cli-contract.test.ts
+```
+
+实现细节与映射逻辑：`./src/core/dag-recovery-recommendation.ts`、`dag-report.ts`、`dag-decision-evidence.ts`。