@tea-agent/loop-agent 0.24.11-beta.0 → 0.25.1

package/CHANGELOG.md

@@ -2,15 +2,64 @@
 
 ## [Unreleased]
 
+## [0.25.1] - 2026-07-30
+
+### 重点更新
+
+- 后端测试 DAG 节点新增 JaCoCo 覆盖率收集能力，支持在 L-5 dashboard 展示 Java 后端的代码行与分支覆盖率
+- 规范任务 DAG 草稿的默认输出路径，统一指向 `.harness/tasks/<task-id>/dag.json`
+- 修复 loop-agent 技能条目因注入预算超限被截断的问题，确保默认 DAG 下技能完整解析
+
+### 新增
+
+- backend-test DAG 节点 7 支持可选的 JaCoCo 覆盖率收集：通过跨网络 TCP dump JaCoCo tcpserver 数据，经 jacococli.jar 转换并解析为 code-coverage-v1 合约，供 L-5 dashboard 使用
+- task shell 配置新增 `jacocoCoverage` 字段，支持配置 endpoint、cliJarPath、includes 和 connectTimeoutMs
+- 新增面向开发与运维的 JaCoCo 覆盖率部署指南，涵盖 tcpserver agent 挂载、端口放行、cli 预装及安全提醒
+
 ### 改进
 
-- Feature Delivery 在省略 `--qa-evidence` / `--final-verification` 时默认使用 `feature verify-final` 写入的 evidence 路径（ADR 0007）
+- `dag run-task` 与 `dag init-hybrid` 的默认输出路径改为 `.harness/tasks/<task-id>/dag.json`，不再写入系统临时目录
+- agent-worker 在 strict validate 成功后，将校验通过的草稿原子同步到 task 根 `dag.json`
+- task read-model、delegate worktree 提示及各文档示例统一指向规范化的任务草稿路径
+- skills 补充 `source-and-plan-practice.md`，明确 `import-prd` 与 `plan create` 的决策表与推荐顺序，不强制微小任务
+
+### 修复
+
+- 压缩 SKILL.md 及 required-reference 体积，修复默认 DAG 技能注入预算超限导致 loop-agent 条目被截断的问题
 
-### 文档
+## [0.25.0] - 2026-07-30
 
-- ADR 0007：Final Verification 唯一权威为 `agent-worker feature verify-final`；packet FINAL-VERIFY 仅 local smoke
-- F-2026-005 design / FINAL-VERIFY TaskSpec 与发布列车状态对齐 I39 Delivery + 收口下一步 I40
+### 重点更新
+
+- 新增确定性 Feature Packet 脚手架，支持后端、前端及含 API 前端模板，并具备原子批量写入与预检能力
+- 新增 Feature 交付编排命令，自动串联最终验证、交付与收口流程
+- 显著提升 DAG 执行稳定性，修复超时残留子进程、重复验证及耗时记录不完整等问题
+- 新增任务级 Maven 验证规划，自动定位并仅针对相关模块执行验证
+- 后端测试节点现可自动生成指标机器计算的自包含 L-5 可视化报告
+
+### 新增
+
+- backend-test DAG 节点 7 支持可选的 JaCoCo 覆盖率收集（Java 服务）：task shell 配置新增 `jacocoCoverage`（endpoint + cliJarPath + includes + connectTimeoutMs）；节点 7 在 pytest 后跨网络 TCP dump JaCoCo tcpserver 执行数据，用 jacococli.jar 转为 jacoco.xml，确定性解析为 `contracts/code-coverage-v1.json` 并喂给 L-5 dashboard 的 line/branch 指标；全程失败安全（endpoint 不通 / cli 缺失 / 解析失败 → 覆盖率降级 unavailable，不阻断测试与 L-5）
+- 提供 agent-worker Feature Packet 脚手架，内置 backend-only、frontend-only 和 fe-with-api 模板，支持原子批量写入与 validate-feature 预检
+- 新增 agent-worker feature advance 命令，编排 verify-final、delivery 到 closeout 的完整交付路径
+- 新增 agent-worker feature doctor 命令，提供只读的交付就绪诊断（覆盖证据、Pool 状态与工作区改动）
+- Maven 验证现支持任务级范围规划，根据任务涉及的目录自动定位并验证正确的 POM 模块
+- 后端测试 DAG 节点 7 现可确定性生成美观的自包含 L-5 可视化报告，指标完全由机器计算
+
+### 改进
+
+- Feature Delivery 在省略特定参数时，默认使用 feature verify-final 写入的标准证据路径
+- TaskConfig 持久化入口在写入前执行 schema 校验，拒绝不符合规范的数据格式
+- Dogfood 前端测试服务器在检测到旧缓存导致接口数据异常时，现会自动强制重启恢复
+
+### 修复
 
+- 显著加固 DAG 执行可靠性，修复超时或中断后子进程残留问题，降低文件占用与测试干扰概率
+- 修复受监督流程可能重复执行完整验证的问题，避免高成本检查在不同阶段反复运行
+- 修复 DAG 被放弃或替换时，运行中节点实际耗时记录不完整的问题
+- 修复 Windows 环境下因提示内容过长导致 DAG 无法启动的问题，现安全采用受控临时文件传输
+- 修复前端实现 DAG 在未确认项目 Mock 能力时误报缺失 Mock 文件的问题
+- 修复结构化任务配置中数组类型校验不严格的问题
 
 ## [0.24.10] - 2026-07-29
 

package/README.md

@@ -64,19 +64,19 @@ loop-agent new-task example-task "实现一个有明确验收标准的小功能"
 loop-agent dag run-task example-task \
   --profile auto \
   --strict-models \
-  --output <temp-dir>/example-task-dag.json
+  --output .harness/tasks/example-task/dag.json
 
 loop-agent dag validate \
-  --dag <temp-dir>/example-task-dag.json \
+  --dag .harness/tasks/example-task/dag.json \
   --strict-models \
   --strict-governance
 
 loop-agent run-dag \
-  --dag <temp-dir>/example-task-dag.json \
+  --dag .harness/tasks/example-task/dag.json \
   --cwd .
 ```
 
-`<temp-dir>` 应使用当前平台的原生临时目录。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
+省略 `--output` 时默认写入 `.harness/tasks/<task-id>/dag.json`。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
 
 ## 查看执行状态
 

package/dist/application/dag/generate-task-dag.js

@@ -7,10 +7,10 @@ import { parseDagSpec } from "../../workflows/dag/types.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
 import { assertExecPlanIndexConsistent } from "../../governance/exec-plans.js";
-import { defaultHybridDagOutputPath, initHybridDagFromTask, } from "../../workflows/dag/init-hybrid.js";
+import { initHybridDagFromTask, } from "../../workflows/dag/init-hybrid.js";
 import { validateDagUseCase } from "./validate-dag.js";
 import { runDagUseCase } from "./run-dag.js";
-import { loadTaskConfig } from "../../task/runtime.js";
+import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { writeTaskConfig } from "../../infrastructure/harness/task-store.js";
 const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
 function buildValidateInput(repoRoot, dagPath, parsed) {
@@ -41,7 +41,15 @@ function isUnsafeWriteSetEntry(entry) {
     return normalized.includes(PLACEHOLDER_WRITESET_MARKER);
 }
 export async function assertSafeForExecution(dagPath) {
-    const raw = JSON.parse(await readFile(dagPath, "utf-8"));
+    let raw;
+    try {
+        const content = await readFile(dagPath, "utf-8");
+        raw = JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to read valid DAG JSON at ${dagPath}: ${message}`);
+    }
     const unsafe = [];
     for (const task of raw.tasks ?? []) {
         if (task.writePolicy !== "exclusive")
@@ -126,7 +134,16 @@ function resolveReviewPacketShellCommands(task) {
     return resolveShellCommands(task.shell);
 }
 async function buildReviewPacket(input) {
-    const spec = parseDagSpec(JSON.parse(await readFile(input.dagPath, "utf-8")));
+    let raw;
+    try {
+        const content = await readFile(input.dagPath, "utf-8");
+        raw = JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to read valid DAG JSON at ${input.dagPath}: ${message}`);
+    }
+    const spec = parseDagSpec(raw);
     const writers = collectWriterTasksForPacket(spec).map((task) => {
         const writeSet = task.writeSet ?? [];
         return {
@@ -247,8 +264,7 @@ export async function generateTaskDagUseCase(input) {
             : "task-source";
         profileRouting.routingReasons = candidateResult.templateSelection.reasons;
         if (parsed.profile === "auto") {
-            profileRouting.selectedByProfile =
-                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+            profileRouting.selectedByProfile = resolveAutoRoutingProfile(profileRouting.candidateProfile);
         }
         else if (parsed.profileExplicit) {
             profileRouting.selectedByProfile = parsed.profile;
@@ -256,7 +272,8 @@ export async function generateTaskDagUseCase(input) {
     }
     // Persist the automatic business workflow route while preserving the
     // governance profile as a separate routing dimension.
-    if (hasAutomaticTaskSourceRoute && candidateResult.template === "frontend-implementation") {
+    if (hasAutomaticTaskSourceRoute &&
+        candidateResult.template === "frontend-implementation") {
         const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
         if (!taskConfig.taskKind || taskConfig.taskKind === "standard") {
             await writeTaskConfig(repoRoot, parsed.taskId, {
@@ -297,7 +314,7 @@ export async function generateTaskDagUseCase(input) {
             ok: true,
             taskId: initResult.taskId,
             outputPath,
-            defaultOutputPath: defaultHybridDagOutputPath(parsed.taskId),
+            defaultOutputPath: getTaskPaths(repoRoot, parsed.taskId).dagDraftPath,
             taskCount: initResult.taskCount,
             nodeIds: initResult.nodeIds,
             title: validateSummary.title,

package/dist/commands/dag-init-hybrid.js

@@ -1,5 +1,6 @@
 import path from "node:path";
-import { defaultHybridDagOutputPath, initHybridDagFromTask, } from "../workflows/dag/init-hybrid.js";
+import { initHybridDagFromTask } from "../workflows/dag/init-hybrid.js";
+import { getTaskPaths } from "../task/runtime.js";
 export function parseDagInitHybridArgs(args) {
     if (args.length === 0) {
         throw new Error("usage: dag init-hybrid <task-id> [--output <path>]");
@@ -44,7 +45,7 @@ export async function runDagInitHybrid(repoRoot, rawArgs) {
         ok: true,
         taskId: result.taskId,
         outputPath: result.outputPath,
-        defaultOutputPath: defaultHybridDagOutputPath(parsed.taskId),
+        defaultOutputPath: getTaskPaths(repoRoot, parsed.taskId).dagDraftPath,
         taskCount: result.taskCount,
         nodeIds: result.nodeIds,
         next: [

package/dist/commands/delegate.js

@@ -1,10 +1,9 @@
-import os from "node:os";
-import path from "node:path";
 import { delegateTask } from "../task/delegate.js";
 import { loadHarnessManifest } from "../governance/harness.js";
 import { generateTaskDagUseCase } from "../application/dag/generate-task-dag.js";
 import { validateDagUseCase } from "../application/dag/validate-dag.js";
 import { runDagUseCase } from "../application/dag/run-dag.js";
+import { getTaskPaths } from "../task/runtime.js";
 const DELEGATE_USAGE = "usage: delegate <taskId> [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run]";
 export function parseDelegateArgs(args) {
     if (args.length === 0) {
@@ -59,12 +58,13 @@ export function parseDelegateArgs(args) {
     return { taskId, base, branch, symlinkNodeModules, autoRun };
 }
 export function printDelegateNextSteps(taskId, result) {
-    const dagPath = path.join(os.tmpdir(), `${taskId}-dag.json`);
+    const dagPath = getTaskPaths(result.worktreePath, taskId).dagDraftPath;
     const lines = [
         `[delegate] worktree ready (Pi-only).`,
         `  worktree: ${result.worktreePath}`,
         `  Next — generate, validate, and run DAG in the worktree:`,
-        `    loop-agent dag run-task ${taskId} --profile auto --strict-models --output ${JSON.stringify(dagPath)}`,
+        `    cd ${JSON.stringify(result.worktreePath)}`,
+        `    loop-agent --repo-root ${JSON.stringify(result.worktreePath)} dag run-task ${taskId} --profile auto --strict-models`,
         `    loop-agent dag validate --dag ${JSON.stringify(dagPath)} --strict-models --strict-governance`,
         `    loop-agent run-dag --dag ${JSON.stringify(dagPath)} --cwd ${JSON.stringify(result.worktreePath)}`,
         `  Or: loop-agent delegate ${taskId} --auto-run`,
@@ -89,30 +89,30 @@ export async function runDelegate(repoRoot, rawArgs, dependencies = DEFAULT_RUN_
         symlinkNodeModules: parsed.symlinkNodeModules,
     });
     if (parsed.autoRun) {
-        const dagPath = path.join(os.tmpdir(), `${parsed.taskId}-delegate-dag.json`);
+        const worktreeRoot = result.worktreePath;
+        const dagPath = getTaskPaths(worktreeRoot, parsed.taskId).dagDraftPath;
         await dependencies.generateTaskDag({
-            repoRoot,
+            repoRoot: worktreeRoot,
             taskId: parsed.taskId,
-            outputPath: dagPath,
             strictModels: true,
             execute: false,
             initOnly: false,
             dryRun: false,
-            cwd: result.worktreePath,
+            cwd: worktreeRoot,
             profile: "auto",
             profileExplicit: false,
         });
         await dependencies.validateDag({
-            repoRoot,
+            repoRoot: worktreeRoot,
             dagPath,
             strictModelMatrix: true,
             strictGovernance: true,
             forbidExecutors: [],
         });
         const runSummary = await dependencies.runDag({
-            repoRoot,
+            repoRoot: worktreeRoot,
             dagPath,
-            cwd: result.worktreePath,
+            cwd: worktreeRoot,
             initOnly: false,
             dryRun: false,
         });

package/dist/commands/init.js

@@ -345,7 +345,7 @@ check_ts_import_boundary() {
   local label="$3"
   [[ -d "\${from_dir}" && -d "\${forbidden_dir}" ]] || return 0
   while IFS= read -r -d '' file; do
-    if grep -Eq "from ['\\\"][^'\\\"]*\${forbidden_dir}/|import\\(['\\\"][^'\\\"]*\${forbidden_dir}/|require\\(['\\\"][^'\\\"]*\${forbidden_dir}/" "\${file}"; then
+    if grep -Eq "from ['\\"][^'\\"]*\${forbidden_dir}/|import\\(['\\"][^'\\"]*\${forbidden_dir}/|require\\(['\\"][^'\\"]*\${forbidden_dir}/" "\${file}"; then
       violations+=("\${label}: \${file} imports \${forbidden_dir}")
     fi
   done < <(find "\${from_dir}" -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' -o -name '*.cjs' \\) -print0)
@@ -412,9 +412,22 @@ check_skill "loop-agent" \\
   "references/harness-policy.md" \\
   "references/hybrid-dag.md" \\
   "references/verification-and-failure-handling.md" \\
-  "references/command-reference.md"
+  "references/command-reference.md" \\
+  "references/source-and-plan-practice.md"
 check_skill "agent-worker" "references/agent-worker-operator.md"
 
+# loop-agent description is a YAML folded block (>-); grep ^description: only
+# captures the indicator line. Validate the general-demand trigger terms
+# against the whole skill file so host auto-discovery phrasing cannot drift.
+loop_agent_skill=".agents/skills/loop-agent/SKILL.md"
+loop_agent_text="$(tr '[:upper:]' '[:lower:]' < "\${loop_agent_skill}")"
+for term in "loop-agent 帮我完成" "帮我实现" "帮我修复" "帮我开发" "agent dag" "new-task" "dag run-task" "dag validate" "run-dag"; do
+  if [[ "\${loop_agent_text}" != *"\${term}"* ]]; then
+    echo "skill entry 检查失败（loop-agent）：description 缺少触发/路由词 \${term}" >&2
+    exit 1
+  fi
+done
+
 description_line="$(grep -E '^description:' .agents/skills/agent-worker/SKILL.md | head -n 1 | tr '[:upper:]' '[:lower:]')"
 for term in "agent-worker" "feature packet" "taskspec" "task pool" "self-host" "candidate" "loop-agent"; do
   if [[ "\${description_line}" != *"\${term}"* ]]; then
@@ -802,6 +815,7 @@ function buildManagedAgentsBlock(input) {
         "| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |",
         "| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；活跃 DAG/Worker 或人工决策时零写入 |",
         "| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | 先 check-update，再只执行确定性安全动作 |",
+        "| loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 通用需求实现 | 先建任务源与 `task.json.allowedPaths` / `forbiddenPaths`，再 `new-task` → `dag run-task` → `dag validate` → `run-dag`；主会话不得直接修改业务实现 |",
         "",
         "**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe` 或模型合并。",
         "",
@@ -843,9 +857,9 @@ function buildManagedAgentsBlock(input) {
         "loop-agent new-task <task-id> \"任务标题\"",
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
-        "loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json",
-        "loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance",
-        "loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .",
+        "loop-agent dag run-task <task-id> --profile auto --strict-models",
+        "loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance",
+        "loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd .",
         "```",
         "",
         "`source/需求.md` 与 `source/执行约束.md` 必需；写入前同步 `task.json.allowedPaths` / `task.json.forbiddenPaths` 并审查 writer `writeSet`。",
@@ -861,10 +875,11 @@ function buildManagedAgentsBlock(input) {
         "### 运行看板（只读）",
         "",
         "```bash",
-        "agent-worker console serve --repo . --port 8790",
+        "agent-worker console                       # 默认 repo=当前目录，port=8790",
+        "agent-worker console serve --repo . --port 8790   # 兼容入口，等价于上面裸入口",
         "```",
         "",
-        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；不要直接暴露到公开网络。`agent-worker observe serve` 仅为兼容入口。",
+        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；不要直接暴露到公开网络。端口被占用时不会自动更换，请用 `--port <port>` 显式指定。`agent-worker observe serve` 仅为兼容入口。",
         "",
         "### DAG 诊断与收口",
         "",
@@ -1804,9 +1819,9 @@ function buildManagedReadmeBlock(input) {
         "loop-agent new-task <task-id> \"任务标题\"",
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
-        "loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json",
-        "loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance",
-        "loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .",
+        "loop-agent dag run-task <task-id> --profile auto --strict-models",
+        "loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance",
+        "loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd .",
         "```",
         "",
         `详细工作流见 \`${input.governanceRoot}/feature-workflow.md\`；验证矩阵见 \`${input.governanceRoot}/verification-matrix.md\`。任务 source 是必需项：\`source/需求.md\` 写目标、范围、非目标、验收标准和相关链接，\`source/执行约束.md\` 写允许路径、禁止路径、受保护变更、不变量、预期验证和失败条件。`,
@@ -2036,9 +2051,9 @@ function buildTargetFeatureWorkflow(input) {
         "loop-agent new-task <task-id> \"Task title\"",
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
-        "loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json",
-        "loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance",
-        "loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .",
+        "loop-agent dag run-task <task-id> --profile auto --strict-models",
+        "loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance",
+        "loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd .",
         "```",
         "",
         DAG_HARD_GATE_TRIGGER,
@@ -2660,7 +2675,7 @@ async function applySafeAction(input) {
         if (!isRecord(harness) || !isRecord(harness.executors) || !isRecord(harness.executors.pi)) {
             return false;
         }
-        if (!Object.prototype.hasOwnProperty.call(harness.executors.pi, "requiresApiKey")) {
+        if (!Object.hasOwn(harness.executors.pi, "requiresApiKey")) {
             return false;
         }
         const nextPi = { ...harness.executors.pi };

package/dist/commands/instructions.js

@@ -1,7 +1,6 @@
 import { access, readdir } from "node:fs/promises";
 import path from "node:path";
 import { getArtifactPath, getArtifactRelativePath, } from "../shared/artifacts-core.js";
-import { defaultHybridDagOutputPath } from "../workflows/dag/init-hybrid.js";
 import { getTaskDir, getTaskPaths, loadTaskConfig } from "../task/runtime.js";
 const STAGES = new Set([
     "source",
@@ -96,7 +95,7 @@ export async function buildInstructions(repoRoot, stage, taskId) {
     if (stage === "dag-draft") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
-            outputPath: defaultHybridDagOutputPath(taskId),
+            outputPath: paths.dagDraftPath,
             dependencies: [
                 paths.taskConfigPath,
                 path.join(paths.sourceDir, "需求.md"),

package/dist/executors/dag-pi-executor.js

@@ -130,17 +130,23 @@ export function buildDagPiUserMessage(task, persona, step) {
     const role = task.role ?? "unspecified";
     const writePolicy = task.writePolicy ?? "read-only (default)";
     if (isDagPiWriteTask(task)) {
+        const outcomeInstruction = task.writerOutcomePolicy
+            ? "The first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked. Use changed only after producing a non-empty bounded diff; use already-satisfied only when the contract is already met and no file changed; use blocked when implementation cannot proceed."
+            : undefined;
         return [
             `You are executing hybrid DAG node "${task.id}" (role=${role}, piStep=${step}, writePolicy=${writePolicy}).`,
             "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
             "Use write tools only for the bounded implementation requested by this node.",
+            outcomeInstruction,
             `Allowed paths: ${(task.allowedPaths ?? []).join(", ") || "(none declared)"}.`,
             `Write set: ${(task.writeSet ?? []).join(", ") || "(none declared)"}.`,
             `Forbidden paths: ${(task.forbiddenPaths ?? []).join(", ") || "(none declared)"}.`,
             "Preserve unrelated files. Do not edit outside allowedPaths/writeSet. Never write forbiddenPaths, .harness/dag-runs/**, or undeclared root artifacts/**.",
             "Return concise Markdown with changed files, verification performed or still required, and residual risks.",
             "Do not wrap the output in code fences and do not add conversational preamble.",
-        ].join(" ");
+        ]
+            .filter((value) => Boolean(value))
+            .join(" ");
     }
     // Decision Gate nodes must emit a mandatory DECISION_ENVELOPE_JSON fenced block;
     // do not inject the global no-fence instruction that would conflict with outputContract.
@@ -344,21 +350,39 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
             ];
         }
     }
-    if (writeGuardOk) {
-        if (beforeStatus !== undefined && changeManifestChangedFiles !== undefined) {
-            await persistWriterChangeManifest({
-                runDir: meta.runDir,
-                nodeId: input.task.id,
-                writerNodeId: input.task.id,
-                changedFiles: changeManifestChangedFiles,
-                beforeStatus,
-                afterStatus: changeManifestAfterStatus ?? "",
-            });
+    let writerOutcomeViolation;
+    if (mapped.ok && input.task.writerOutcomePolicy) {
+        if (changeManifestChangedFiles === undefined) {
+            writerOutcomeViolation =
+                "writer outcome validation failed: actual diff is unavailable";
+        }
+        else {
+            const outcomeValidation = validateWriterImplementationOutcome(mapped.assistantText || mapped.stdout, changeManifestChangedFiles);
+            if (!outcomeValidation.ok) {
+                writerOutcomeViolation = outcomeValidation.reason;
+            }
         }
+    }
+    if (writeGuardOk && beforeStatus !== undefined && changeManifestChangedFiles !== undefined) {
+        await persistWriterChangeManifest({
+            runDir: meta.runDir,
+            nodeId: input.task.id,
+            writerNodeId: input.task.id,
+            changedFiles: changeManifestChangedFiles,
+            beforeStatus,
+            afterStatus: changeManifestAfterStatus ?? "",
+        });
+    }
+    if (writeGuardOk && !writerOutcomeViolation) {
         return mapped;
     }
     const stderrParts = [mapped.stderr];
-    stderrParts.push(`write guard failed: ${writeGuardViolations.join(", ")}`);
+    if (!writeGuardOk) {
+        stderrParts.push(`write guard failed: ${writeGuardViolations.join(", ")}`);
+    }
+    if (writerOutcomeViolation) {
+        stderrParts.push(writerOutcomeViolation);
+    }
     if (meta.writeGuardAttribution === "best-effort") {
         stderrParts.push("write guard note: concurrent rank writers use best-effort per-node attribution; keep same-rank writeSet entries disjoint");
     }
@@ -366,10 +390,47 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
         ...mapped,
         ok: false,
         stderr: stderrParts.filter(Boolean).join("\n\n"),
-        failureCategory: mapped.ok ? "write-guard" : mapped.failureCategory,
+        failureCategory: mapped.ok
+            ? writeGuardOk
+                ? "invalid-output"
+                : "write-guard"
+            : mapped.failureCategory,
         durationMs: mapped.durationMs || Date.now() - started,
     };
 }
+export function validateWriterImplementationOutcome(text, changedFiles) {
+    const firstLine = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean);
+    const match = firstLine?.match(/^IMPLEMENTATION_OUTCOME: (changed|already-satisfied|blocked)$/);
+    if (!match) {
+        return {
+            ok: false,
+            reason: "writer outcome validation failed: missing or invalid first line; expected IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked",
+        };
+    }
+    const outcome = match[1];
+    if (outcome === "blocked") {
+        return {
+            ok: false,
+            reason: "writer outcome validation failed: IMPLEMENTATION_OUTCOME: blocked cannot complete successfully",
+        };
+    }
+    if (outcome === "changed" && changedFiles.length === 0) {
+        return {
+            ok: false,
+            reason: "writer outcome validation failed: changed outcome has an empty diff",
+        };
+    }
+    if (outcome === "already-satisfied" && changedFiles.length > 0) {
+        return {
+            ok: false,
+            reason: "writer outcome validation failed: already-satisfied outcome has a non-empty diff",
+        };
+    }
+    return { ok: true, outcome };
+}
 export function mapPiResultToDagNodeResult(result, firstProtocolLine) {
     const assistantText = canonicalizeProtocolFirstLine(result.assistantText, firstProtocolLine);
     return {

package/dist/executors/pi-executor.js

@@ -3,6 +3,8 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { PI_REUSE_RUNTIME_ENV, isPiReuseRuntimeEffective, resolvePiReuseRuntimeMode as resolveConfiguredPiReuseRuntimeMode, } from './pi-runtime-reuse.js';
+import { cleanupPiPromptTransport, createPiPromptTransport, } from './pi-prompt-transport.js';
+import { processTreeSpawnOptions, terminateProcessTree } from './process-tree.js';
 export function extractSubagentStats(stdout) {
     let totalCalls = 0;
     let failedCalls = 0;
@@ -507,12 +509,24 @@ function withCliBackend(result) {
 }
 /** CLI-only orchestration: primary attempt + optional fallback model retry. */
 async function runCliOrchestration(options, meta) {
+    const promptTransport = createPiPromptTransport(options.prompt);
+    try {
+        return await runCliOrchestrationWithPromptFile(options, promptTransport.filePath, meta);
+    }
+    finally {
+        const cleanup = cleanupPiPromptTransport(promptTransport);
+        for (const warning of cleanup.warnings) {
+            process.stderr.write(`${warning}\n`);
+        }
+    }
+}
+async function runCliOrchestrationWithPromptFile(options, promptFilePath, meta) {
     const primary = options.modelConfig ?? {};
     const attemptedModels = [];
     if (meta?.prependAttemptedModel) {
         attemptedModels.push(meta.prependAttemptedModel);
     }
-    const primaryResult = await executeSingleCliAttempt(options, primary);
+    const primaryResult = await executeSingleCliAttempt(options, primary, promptFilePath);
     attemptedModels.push(primaryResult.modelDisplay);
     let primaryIssues = [];
     if (primaryResult.ok && options.validateOutput) {
@@ -525,7 +539,7 @@ async function runCliOrchestration(options, meta) {
         && shouldRetryWithFallback(primaryResult.stderr, primaryResult.stdout))
         || primaryInvalidOutput);
     if (shouldFallback) {
-        const fallbackResult = await executeSingleCliAttempt(options, primary.fallback);
+        const fallbackResult = await executeSingleCliAttempt(options, primary.fallback, promptFilePath);
         attemptedModels.push(fallbackResult.modelDisplay);
         const combinedStderr = [primaryResult.stderr, fallbackResult.stderr].filter(Boolean).join('\n--- fallback ---\n');
         const combinedStdout = [primaryResult.stdout, fallbackResult.stdout].filter(Boolean).join('\n--- fallback ---\n');
@@ -659,7 +673,7 @@ export async function executePiStep(options) {
     });
     return { ...cliResult, reuseRuntimeActive };
 }
-async function executeSingleCliAttempt(options, modelConfig) {
+async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
     const modelDisplay = modelConfig.provider && modelConfig.model
         ? `${modelConfig.provider}/${modelConfig.model}`
         : modelConfig.model ?? 'default';
@@ -687,13 +701,17 @@ async function executeSingleCliAttempt(options, modelConfig) {
         piArgs.push('--thinking', modelConfig.thinking);
     }
     piArgs.push('--tools', options.toolNames.join(','));
-    piArgs.push('--append-system-prompt', options.prompt);
+    piArgs.push('--append-system-prompt', promptFilePath);
     piArgs.push(...options.attachedFiles.map((file) => `@${file}`));
     piArgs.push(options.userMessage);
+    const recordedPiArgs = piArgs.map((arg, index) => index > 0 && piArgs[index - 1] === '--append-system-prompt'
+        ? '<system-prompt-file>'
+        : arg);
     const startedAt = Date.now();
     return await new Promise((resolve, reject) => {
         const child = spawn(process.execPath, [getPiCliPath(), ...piArgs], {
             cwd: options.repoRoot,
+            ...processTreeSpawnOptions(),
             env: {
                 ...process.env,
                 // Explicitly propagate API keys that pi needs to recognise providers.
@@ -748,7 +766,7 @@ async function executeSingleCliAttempt(options, modelConfig) {
                 });
             resolve({
                 assistantText: collected.assistantText,
-                command: ['pi', ...piArgs],
+                command: ['pi', ...recordedPiArgs],
                 durationMs,
                 exitCode: code,
                 failureCategory,
@@ -771,7 +789,7 @@ async function executeSingleCliAttempt(options, modelConfig) {
                 return;
             timedOut = true;
             supervisionStderr = reason;
-            child.kill('SIGTERM');
+            terminateProcessTree(child, 'SIGTERM');
             sigkillHandle = setTimeout(() => {
                 if (settled)
                     return;
@@ -779,7 +797,7 @@ async function executeSingleCliAttempt(options, modelConfig) {
                     finish(child.exitCode);
                     return;
                 }
-                child.kill('SIGKILL');
+                terminateProcessTree(child, 'SIGKILL');
                 exitConfirmationHandle = setTimeout(() => {
                     if (settled)
                         return;