@tea-agent/loop-agent 0.25.3 → 0.25.5

package/AGENTS.md

@@ -46,6 +46,12 @@
 
 这不是 DAG 节点序列。复杂实现默认 Agent DAG；主 agent 拆任务、写 contract、结构化路径、审查 DAG/writeSet/profile/shell verification。微小任务可用 one-shot escape hatch 并记录边界与验证证据。
 
+启动 loop-agent DAG 流程后，主 agent 应自主推进到整个流程结束，不要中途请求无谓的人工确认（如“要我现在执行 DAG 吗？”）。只要 dry-run / validate / writeSet 审查通过就应直接执行并跑完全部 ranks；遇到真问题（契约不一致、writeSet 越界、verify 失败且超出 maxFixLoops、用户明显未授权的高风险动作）才停。即便 profile 是 supervised/reviewed，也不默认在 review-gate 主动停下等人——控制器会在需要人工 approve 时自行提示，主 agent 的职责是推动流程跑完。
+
+DAG 执行期间主 agent 必须持续轮询监视直到 run 结束（FINISHED / FAILED / 需要 approve），不能轮询一次就停下等用户；轮询间隔应合理（避免频繁唤醒浪费 token，也不得住一个节点上赌一次就走）。判活必须用可靠方式：看 `state.json` 的 `runner.heartbeatAt` 是否持续刷新 + `session-events.jsonl` 是否在增长 + `dag doctor` 的 `liveness` 字段，不要只用 `tasklist /FI "PID eq X"` 这类过滤语法在 Git Bash 下会误报 DEAD，从而错判一个正常工作的 run 为 orphaned。遇到疑似 stall 先按 `docs/runtime/agent-dag-runner.md` 查 `lastMeaningfulProgressAt` / provider 活动，有真实进展就继续等，绝不盲目 supersede。
+
+DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件（包括 AGENTS.md、docs、根配置等）。bounded writer 节点的 write guard 用「节点运行期间的工作区 diff」作为越界证据，不区分改动来自 pi 还是主会话——主会话在 pi 节点跑的时候改了 writeSet 外文件，会让 write guard 把账算到 pi 头上、判节点 ERROR、下游 cascade skip。需要改文档/约束时，要么在 DAG 启动前改完，要么等 run 结束后改；务必与 DAG 写入节点在时间上互斥。排查任务路由问题时优先用 `resolveTaskDagTemplateSelection` / `classifyTaskDemand` 等纯函数探针或 `--output` 指定临时路径，不要反复 `dag run-task`——每次调用（含 `--dry-run`）都会在 `.harness/dag-runs/active/` 新建一个 run 目录，dry-run 不执行节点但目录残留，堆积成「一堆 active run」的假象。
+
 ## 项目地图
 
 - `CONTEXT.md`：术语表

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 ## [Unreleased]
 
+## [0.25.5] - 2026-07-31
+
+### 重点更新
+
+- 后端测试 DAG 新增确定性场景覆盖分析与 Markdown 到 pytest 的精准对应，显著提升测试质量度量的准确性与透明度
+- 受监督的 DAG 默认启用有界自愈闭环，能够自动处理可恢复的执行失败并安全重算后续节点
+- 全面加固客户端会话恢复机制，精准识别并补偿由模型服务瞬时异常引发的结构校验错误
+- 大幅增强 DAG 执行的确定性收尾能力，确保在模型输出不稳定或前置快照失败时安全降级
+
+### 新增
+
+- 后端测试固定 9 节点 DAG 新增可审计的场景覆盖与 Markdown→pytest 一一对应事实：节点 4 从严格 Coverage Matrix、Case Rule/Test Point 绑定及 OpenAPI required/enum/boundary/pattern/format 规则生成覆盖报告，节点 6 生成 1:1/1:0/1:N/0:1 对应报告，节点 7 校验一致性后物化 canonical manifest
+- 受监督的 DAG 默认启用有界自愈闭环：通过 maxFixLoops 派生收敛预算，将可恢复失败与合法的审查修订请求统一纳入恢复链，并确定性注入上一轮失败证据指针，同时保持对安全失败的不自动重试
+- 后端测试用例生成与独立 Review 改为产品需求优先，并穷举文档化 API 规则，涵盖生命周期、枚举等价类、长度数值边界及业务状态迁移等场景
+- 后端测试 HTML/facts 新增可展开的“用例场景覆盖分析”和“Markdown → pytest 一一对应”质量详情
+
+### 改进
+
+- 减少全量测试中的重复 CLI 冷启动和 self-host canary 二次打包安装场景，收敛低价值重复用例并保留关键端到端主路径
+- DAG 执行期间的主会话行为约束得到增补：启动后自主推进至结束、持续可靠判活、严格限制工作区文件修改，并优先使用纯函数探针排查路由
+
+### 修复
+
+- 修复后端测试节点 4/6 的确定性覆盖与对应分析在自身崩溃时被静默吞掉的问题，现会写入诊断信息并按基础设施故障安全停止
+- 修复后端测试节点 4、6、7 在缺失 spec.sourceBinding 时未统一停止的问题，避免上游回退导致下游 manifest 突发报错
+- 修复成功执行路径下 HTTP 请求/响应日志解析不规范的问题，现统一规范化大小写不敏感的日志前缀并完整解析 JSON，恢复报告中的请求参数与大响应正文
+- 修复 Pi writer 已输出合法结果却因前置说明、Markdown 装饰或中文标点被误判失败的问题，现确定性规范化唯一 outcome 且不影响无副作用操作
+- 修复 Pi writer 前置 Git 快照失败被延后处理的问题，现调用模型前即安全停止，并在失败信息中保留完整的尝试次数与错误上下文
+- 修复不稳定模型输出导致受监督 DAG 无法可信收尾的问题，现使用精确判定协议和有限重试，确保最终状态准确且保持安全关闭
+- 修复合并后 canonical DAG Pi MED 路由错误回退到旧模型的问题，统一恢复为正确配置
+- 修复脚手架样例漂移检查误判当前 worktree 目录名的问题，避免附加 worktree 触发稳定测试失败
+- 修复 Windows 8.3 短路径与长路径指向同一仓库时生成不同指纹的问题，避免应用数据命名空间冲突
+- 修复生成的 OpenCode 恢复插件在 busy→idle 竞态下丢失续接的问题，现保留待处理错误并在明确空闲后安全重试
+- 修复 Pi retry 配置读取将权限或 I/O 错误误判为缺文件的问题，现仅缺失文件时允许新建配置
+- 修复客户端瞬态恢复无法正确处理 TypeValidation 瞬时错误的问题，现能准确识别携带瞬时信号的错误并安全重试，纯 schema 校验失败仍被拒绝
+
+## [0.25.4] - 2026-07-31
+
+### 新增
+
+- stream run progress heartbeats
+
+### 新增
+
+- stream run progress heartbeats
+- improve HTML failure triage
+- add native checklist and HTML report gates
+
+### 修复
+
+- tighten production URL detection
+- preserve supported Pi default model
+- sync packaged prompt contract
+- normalize drifted case ids and decode nested HTML entities
+
 ## [0.25.3] - 2026-07-30
 
 ### 重点更新

package/dist/application/dag/args.js

@@ -247,12 +247,14 @@ export function parseDagValidateArgs(args) {
 }
 export function parseRunDagArgs(args, defaultCwd) {
     if (args.length === 0) {
-        throw new Error("usage: run-dag --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]] [--events-jsonl <path>] [--json]");
+        throw new Error("usage: run-dag --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--quiet] [--progress-interval-ms N] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]] [--events-jsonl <path>] [--json]");
     }
     let dagPath;
     let cwd;
     let initOnly = false;
     let dryRun = false;
+    let quiet = false;
+    let progressIntervalMs = 30_000;
     let maxConcurrent;
     let runId;
     let canvasPath;
@@ -280,6 +282,15 @@ export function parseRunDagArgs(args, defaultCwd) {
         else if (arg === "--dry-run") {
             dryRun = true;
         }
+        else if (arg === "--quiet") {
+            quiet = true;
+        }
+        else if (arg === "--progress-interval-ms") {
+            progressIntervalMs = parseProgressIntervalMs(args[++i]);
+        }
+        else if (arg.startsWith("--progress-interval-ms=")) {
+            progressIntervalMs = parseProgressIntervalMs(arg.slice("--progress-interval-ms=".length));
+        }
         else if (arg === "--max-concurrent") {
             maxConcurrent = parseMaxConcurrent(args[++i]);
         }
@@ -337,6 +348,8 @@ export function parseRunDagArgs(args, defaultCwd) {
         cwd: path.resolve(cwd ?? defaultCwd ?? process.cwd()),
         initOnly,
         dryRun,
+        quiet,
+        progressIntervalMs,
         maxConcurrent,
         runId,
         canvasPath,
@@ -346,6 +359,13 @@ export function parseRunDagArgs(args, defaultCwd) {
         ...(workerAssociation ? { workerAssociation } : {}),
     };
 }
+function parseProgressIntervalMs(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1_000) {
+        throw new Error("progress-interval-ms must be an integer >= 1000");
+    }
+    return parsed;
+}
 function parseWorkerAssociation(raw) {
     if (!raw?.trim()) {
         throw new Error("run-dag --worker-association requires JSON");

package/dist/application/dag/run-dag.js

@@ -55,6 +55,7 @@ export async function runDagUseCase(input) {
         })
         : undefined;
     const observer = composeDagRunObservers([
+        input.observer,
         canvas?.observer,
         eventObserver?.observer,
     ]);

package/dist/cli/command-definitions.js

@@ -662,7 +662,7 @@ export const COMMAND_DEFINITIONS = [
         adapter: "required",
         tier: "primary",
         intent: "Execute a reviewed Agent DAG spec.",
-        usage: "run-dag --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]] [--events-jsonl <path>] [--worker-association <json>]",
+        usage: "run-dag --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--quiet] [--progress-interval-ms N] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]] [--events-jsonl <path>] [--worker-association <json>]",
         handler: async ({ repoRoot, subcommand, rest }) => {
             const runDagArgs = [subcommand, ...rest].filter((arg) => Boolean(arg));
             await runRunDag(repoRoot, runDagArgs);

package/dist/cli/program.js

@@ -124,18 +124,8 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
             await runDoctor(ctx.adapter, ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
         case "docs":
-            if (subcommand === "audit") {
-                await runDocsAudit(ctx.repoRoot);
-                return;
-            }
-            if (subcommand === "archive") {
-                const [planPath] = rest;
-                if (!planPath)
-                    throw new Error("usage: docs archive <active-plan-path>");
-                await runDocsArchive(ctx.repoRoot, planPath);
-                return;
-            }
-            throw new Error("usage: docs <audit|archive> ...");
+            await runDocsCommand(ctx.repoRoot, subcommand, rest);
+            return;
         case "new-task": {
             const [taskId, ...titleParts] = [subcommand, ...rest];
             if (!taskId)
@@ -189,53 +179,14 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
             await runStats(ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
         case "plan":
-            if (subcommand === "list" || subcommand === undefined) {
-                await runPlanList(ctx.repoRoot);
-                return;
-            }
-            if (subcommand === "create") {
-                const [planId, ...titleParts] = rest;
-                if (!planId)
-                    throw new Error('usage: plan create <plan-id> "<title>"');
-                await runPlanCreate(ctx.repoRoot, planId, titleParts.join(" "));
-                return;
-            }
-            if (subcommand === "complete") {
-                const [planId, ...summaryParts] = rest;
-                if (!planId)
-                    throw new Error('usage: plan complete <plan-id> --summary "<summary>"');
-                const summary = parsePlanSummaryFlag(summaryParts);
-                if (!summary)
-                    throw new Error('usage: plan complete <plan-id> --summary "<summary>"');
-                await runPlanComplete(ctx.repoRoot, planId, { summary });
-                return;
-            }
-            if (subcommand === "check") {
-                await runPlanCheck(ctx.repoRoot);
-                return;
-            }
-            throw new Error("usage: plan <list|create|complete|check> ...");
+            await runPlanCommand(ctx.repoRoot, subcommand, rest);
+            return;
         case "spine":
             await runSpine(ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
         case "handoff":
-            if (subcommand === "check") {
-                await runHandoffCheck(ctx.repoRoot, rest[0]);
-                return;
-            }
-            if (subcommand === "coverage") {
-                const [taskId, ...flags] = rest;
-                if (!taskId) {
-                    throw new Error("usage: handoff coverage <taskId> [--json|--markdown]");
-                }
-                const exitCode = await runCoverageAudit(ctx.repoRoot, taskId, {
-                    json: flags.includes("--json"),
-                    markdown: flags.includes("--markdown"),
-                });
-                process.exitCode = exitCode;
-                return;
-            }
-            throw new Error("usage: handoff <check|coverage> [taskId]");
+            await runHandoffCommand(ctx.repoRoot, subcommand, rest);
+            return;
         case "coverage":
             await runCoverageReport(ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
@@ -243,14 +194,8 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
             await runGoal(ctx.repoRoot, subcommand, rest);
             return;
         case "reference":
-            if (subcommand === "index") {
-                const [taskId] = rest;
-                if (!taskId)
-                    throw new Error("usage: reference index <task-id>");
-                await runReferenceIndex(ctx.repoRoot, taskId);
-                return;
-            }
-            throw new Error("usage: reference <index> <task-id>");
+            await runReferenceCommand(ctx.repoRoot, subcommand, rest);
+            return;
         case "study":
             if (subcommand === "init") {
                 await runStudyInit(ctx.repoRoot, rest);
@@ -305,6 +250,78 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
             throw new Error(`commander command is not wired to an action: ${command}`);
     }
 }
+async function runDocsCommand(repoRoot, subcommand, rest) {
+    if (subcommand === "audit") {
+        await runDocsAudit(repoRoot);
+        return;
+    }
+    if (subcommand === "archive") {
+        const [planPath] = rest;
+        if (!planPath)
+            throw new Error("usage: docs archive <active-plan-path>");
+        await runDocsArchive(repoRoot, planPath);
+        return;
+    }
+    throw new Error("usage: docs <audit|archive> ...");
+}
+async function runPlanCommand(repoRoot, subcommand, rest) {
+    if (subcommand === "list" || subcommand === undefined) {
+        await runPlanList(repoRoot);
+        return;
+    }
+    if (subcommand === "create") {
+        const [planId, ...titleParts] = rest;
+        if (!planId)
+            throw new Error('usage: plan create <plan-id> "<title>"');
+        await runPlanCreate(repoRoot, planId, titleParts.join(" "));
+        return;
+    }
+    if (subcommand === "complete") {
+        const [planId, ...summaryParts] = rest;
+        if (!planId) {
+            throw new Error('usage: plan complete <plan-id> --summary "<summary>"');
+        }
+        const summary = parsePlanSummaryFlag(summaryParts);
+        if (!summary) {
+            throw new Error('usage: plan complete <plan-id> --summary "<summary>"');
+        }
+        await runPlanComplete(repoRoot, planId, { summary });
+        return;
+    }
+    if (subcommand === "check") {
+        await runPlanCheck(repoRoot);
+        return;
+    }
+    throw new Error("usage: plan <list|create|complete|check> ...");
+}
+async function runHandoffCommand(repoRoot, subcommand, rest) {
+    if (subcommand === "check") {
+        await runHandoffCheck(repoRoot, rest[0]);
+        return;
+    }
+    if (subcommand === "coverage") {
+        const [taskId, ...flags] = rest;
+        if (!taskId) {
+            throw new Error("usage: handoff coverage <taskId> [--json|--markdown]");
+        }
+        process.exitCode = await runCoverageAudit(repoRoot, taskId, {
+            json: flags.includes("--json"),
+            markdown: flags.includes("--markdown"),
+        });
+        return;
+    }
+    throw new Error("usage: handoff <check|coverage> [taskId]");
+}
+async function runReferenceCommand(repoRoot, subcommand, rest) {
+    if (subcommand === "index") {
+        const [taskId] = rest;
+        if (!taskId)
+            throw new Error("usage: reference index <task-id>");
+        await runReferenceIndex(repoRoot, taskId);
+        return;
+    }
+    throw new Error("usage: reference <index> <task-id>");
+}
 async function runDagAction(repoRoot, subcommand, rest) {
     const args = compactArgs(rest);
     switch (subcommand) {
@@ -439,6 +456,8 @@ function configureRunDag(command) {
         .option("--dry-run", "validate and plan without executing")
         .option("--max-concurrent <n>", "maximum concurrent nodes")
         .option("--run-id <id>", "run id")
+        .option("--quiet", "disable run/node progress on stderr")
+        .option("--progress-interval-ms <n>", "stderr heartbeat interval in milliseconds (minimum 1000)")
         .option("--canvas-path <path>", "absolute canvas output path")
         .option("--canvas <name>", "canvas name")
         .option("--canvases-dir <dir>", "canvas output directory")