@tea-agent/loop-agent 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,11 +2,42 @@
 
 这里记录每个版本对使用者有影响的变化。命令名和配置字段保持原样，其余内容尽量用日常语言说明。
 
-## [Unreleased]
-
-## [0.9.0] - 2026-07-12
-
-### 修复
+## [Unreleased]
+
+### 新增
+
+- 严格初始化演化检查现在接受 `Head` 为当前 `HEAD` 可解析祖先提交的报告：只要 `Base` 精确匹配 `--base`、`Head` 是 `HEAD` 或其祖先，且 `reportHead..HEAD` 区间没有新的 `model-review` 高影响路径即可通过。仅 `advisory` 或 `surface-check` 的后续变化不会让已完成的高影响审查失效；`working tree` 等不可解析 Head 与无关历史报告仍被拒绝。
+
+- 新增只读的 `agent-worker feature review`。用户无需翻查原始日志，即可查看 Feature 当前状态、主要阻塞、required AC 覆盖、证据位置和下一条建议命令；`--json` 可供脚本稳定消费。
+- 新增 `agent-worker feature run`。它会先校验 Feature 和目标仓库，再复用现有 Worker pipeline 推进一个 Ready Task，随后刷新晨报、Observe snapshot 和 Feature review；`--dry-run` 可在零写入下预览步骤与产物。
+- 新增 ProductBug Follow-up 人工接续流程。`agent-worker task draft-followup` 生成可审查、可去重的修复草稿；`agent-worker feature approve-followup --dry-run` 可先检查变更计划，批准后再新增 FIX Task、重连下游依赖并进入 Ready，同时保留原失败证据。
+- Follow-up 现已覆盖全部失败分类：可执行类生成严格 TaskSpec，Spec/Risk/Human 类生成行动卡，EnvFailure 只有连续两次失败后才建议环境检查任务；审批事务增加多阶段回滚验证，避免 Packet、Ready state、approval 或 index 半写。
+- `agent-worker feature run --git-mode checkpoint` 新增显式授权的本地 Feature 分支事务。成功任务形成带 Feature/Task/AC/run 信息的 checkpoint commit；失败任务保存 patch 与 untracked 证据后恢复 clean。默认仍不 commit，也不会 push、stash、merge 或创建远程 PR。
+- 新增 `agent-worker feature verify-final`、`feature delivery` 与 Feature Closeout。用户可在 clean Delivery HEAD 上生成 canonical QA/最终验证证据，再从 checkpoint、成功 run 和 required AC 形成带 hash 的 Delivery Package、Acceptance Coverage 与 PR 草稿；Closeout 默认预览，只有显式 `--apply --owner` 才原子写回并保留幂等、stale facts 与回滚保护。
+- Morning report 与 Observe 首页新增共享的 Feature Decision Summary，优先显示状态、下一步、原因、证据和 required AC。新增 `agent-worker report metrics --month YYYY-MM`，同时输出带分母、样本量、时间窗口和缺失数据说明的 JSON/Markdown。
+- Observe 总览新增仓库横幅，显示仓库名与绝对路径；KPI 按主要执行链路排列为“Worker 执行”在前、“DAG 运行”在后，DAG 组明确展示活跃运行、执行中/等待节点、暂停和需处理运行，“活跃 Task”更名为“活跃 Worker Task”，每张卡片新增可键盘聚焦的问号帮助，解释数据来源与统计口径。
+- Observe 总览的 Feature 决策仅在存在“运行中”或“需处理”的 Feature 时显示；只有可执行、待验收、已交付或已关闭记录时不再占用总览空间。
+
+### 修改
+
+- 根目录 `design/` 已并入 `docs/design/`，视觉参考与产品线设计笔记现在统一从治理文档目录查找，相关索引和引用已同步更新。
+- Agent DAG 的 Pi/Cursor 节点现在默认使用简体中文输出说明、分析、报告和文档；可通过 `workflowPolicy.dag.outputLanguage: "en"` 切换英文，代码、命令、路径、JSON 字段和固定协议 token 不会被翻译。
+- Dashboard 将“运行活性”调整为更直观的“执行器状态”，并明确区分执行器正常、心跳中断、已经退出、其他主机运行以及旧记录没有心跳等情况。
+- 修复 Dashboard 综合 DAG 状态使用中文文案后丢失徽章颜色的问题；完成、失败、暂停、中断和任务已另行完成现在恢复对应的语义颜色。
+- Dashboard 节点耗时达到 60 秒后改为按“分钟 + 秒”显示，例如 `2min 5s`，长任务更容易快速阅读。
+- Dashboard 的 DAG 节点模型列现在会显示 Pi/Cursor 节点实际路由到的模型；历史运行从 `run.json` 模型矩阵推导，新运行会直接把解析后的模型写入节点状态，Shell/Static 节点仍显示 `-`。
+- Dashboard 现在优先展示由生命周期、原始状态和运行活性共同判定的 DAG 当前状态，并单独保留原始记录；新增 `dag reconcile-run`，可在确认执行器已停止后将历史失联 DAG 显式标记为“任务已另行完成”或“已放弃”，同时保存收口前证据。
+- Observe DAG 详情页主信息区精简为单一“状态”，已结束 DAG 不再展示执行器心跳等无意义内部维度，状态一致或不允许恢复/收口时也不再显示“一致”或“否”；不一致、可恢复或可收口的警告与操作能力仍在主视图可见，原始状态、生命周期、活性、状态一致性与恢复资格折叠在“诊断信息”中保留。
+- DAG 运行现在记录本机执行器 PID、主机和持续心跳；`dag status` / `dag doctor` 可区分活跃、节点长时间无活动、心跳停滞、执行器已退出和远端状态未知，Observe 也不会再把已知孤儿或 paused 运行计为活跃 DAG。
+- 节点检查器支持拖动左边缘调整宽度，长 Markdown 表格和输出更容易查看；点击外部空白区域可平滑收起面板。
+- 执行过程改为更清晰的事件轨道：工具调用、AI 回复和 Agent 生命周期更容易区分；没有时间记录时会按采集顺序展示，连续协议事件会自动合并，减少无关噪声。
+- Observe 风险区拆为“需处理 DAG”与“Worker 风险”两个子块；DAG 按运行去重，不会因同一运行同时存在多个异常信号而重复计数，也不会让历史失败记录长期占用当前风险；Snapshot 投影失败不再静默显示为全零健康状态，而是返回安全错误摘要并在总览提示“指标暂不可用”，不含堆栈或敏感信息。
+- 修复旧版（未写 runner 心跳元数据）的运行中 DAG 被 Observe 误判为不活跃的问题：`effectiveStatus=unknown` 只表示活性证据不足，不再覆盖 `lifecycle=active` 且原始 `status` 为 `running`/`pending` 的运行事实，也不再掩盖存在 RUNNING/PENDING 节点的运行。服务端健康计数（活跃运行、执行中节点、等待节点）与前端进行中 DAG 列表现在使用一致的判定语义；`paused`、`terminal`、`stale`、`orphaned` 等明确非活跃事实仍优先于原始 `running`。
+- `npm test` 会先运行可并行的纯测试，再串行运行会启动 CLI 或子进程的集成测试。纯测试会根据机器可用并行度自动选择 1 至 4 个 Worker，低配和高配环境都能在稳定性与速度之间取得更合适的平衡。
+
+## [0.9.0] - 2026-07-12
+
+### 修复
 
 - 修复 Observe 总览误把已结束、但仍保留未执行节点的 DAG 显示为“活跃 DAG”的问题。
 - DAG 详情页中的节点输出、错误输出、依赖图和执行过程会在轮询更新时保留当前查看位置，不再把页面拉回默认位置。
@@ -18,12 +49,12 @@
 - DAG shell 命令和 Worker 调用遇到大量输出时，只在内存中保留最近一段内容并标明截断；完整 stdout/stderr 仍会写入运行产物，避免长日志拖慢本机。
 - 建立 reference index 时会跳过依赖、构建产物、虚拟环境和版本控制目录，并在遍历规模过大时提前停止，减少误扫大型仓库。
 
-### 修改
-
-- Observe 看板改为暖白运行控制台：总览、批次、Task、DAG 和异常页面使用统一的信息层级；DAG 详情中的依赖图和节点表各自完整展示，选择节点后可从右侧检查器查看输出和执行过程。
-- 统一整理运行看板的总览、批次详情、运行详情、DAG 详情和异常 Task 页面：先展示当前状态和风险，再呈现运行记录、输出与产物，桌面端查看信息更集中。
-- 最近 DAG 运行改为按时间排列的状态时间线，标题过长时不会再挤压状态；DAG 详情仍可从每条记录直接进入。
-- 优化节点表格和宽屏布局：节点 ID、模型、状态、耗时和备注更容易扫读；节点输出支持 Markdown 阅读，完成节点在依赖图中以绿色状态提示。
+### 修改
+
+- Observe 看板改为暖白运行控制台：总览、批次、Task、DAG 和异常页面使用统一的信息层级；DAG 详情中的依赖图和节点表各自完整展示，选择节点后可从右侧检查器查看输出和执行过程。
+- 统一整理运行看板的总览、批次详情、运行详情、DAG 详情和异常 Task 页面：先展示当前状态和风险，再呈现运行记录、输出与产物，桌面端查看信息更集中。
+- 最近 DAG 运行改为按时间排列的状态时间线，标题过长时不会再挤压状态；DAG 详情仍可从每条记录直接进入。
+- 优化节点表格和宽屏布局：节点 ID、模型、状态、耗时和备注更容易扫读；节点输出支持 Markdown 阅读，完成节点在依赖图中以绿色状态提示。
 
 ## [0.8.0] - 2026-07-11
 

package/README.md

@@ -92,9 +92,29 @@ loop-agent pi-prompt --cwd . --tools read,bash,edit,write,grep,find,ls "<包含
 
 ```bash
 agent-worker task validate-feature <feature-dir>
+agent-worker feature review --feature-dir <feature-dir> --repo <target-repo>
+agent-worker feature run --feature-dir <feature-dir> --repo <target-repo> --dry-run [--git-mode checkpoint]
+agent-worker feature verify-final --feature-dir <feature-dir> --repo <target-repo> --task-id <qa-execute-id>
+agent-worker feature delivery --feature-dir <feature-dir> --repo <target-repo> --qa-evidence <path> --final-verification <path> [--dry-run]
+agent-worker feature closeout --feature-dir <feature-dir> --repo <target-repo> [--apply --owner <owner>]
+agent-worker report metrics --repo <target-repo> --month <YYYY-MM>
+agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <target-repo>
+agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id <id> --repo <target-repo> --owner <owner> --dry-run
 bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>
 ```
 
+`feature review` 是只读的 Feature 级入口。它从 Feature Packet 和现有 Task Pool 事实派生状态、required AC 覆盖、阻塞、证据和唯一主行动；默认输出简洁人类摘要，`--json` 输出稳定的 schemaVersion 1 读模型。它不会写入 Feature Packet 或 Task Pool。
+
+`feature verify-final` 在 clean Delivery HEAD 上复用已完成的 `qa-execute` TaskSpec，执行独立、不会 promote/closeout 或移动 HEAD 的最终验证，并原子投影 canonical QA aggregate 与 HEAD-bound final-verification evidence。`feature delivery` 复用 checkpoint transaction，校验 branch/HEAD/clean、commit trailers、changed files、成功 run、QA、最终验证和 required AC 后，在 `.harness/task-pool/` 原子生成 Delivery manifest、Acceptance Coverage 与 `PR.md`；`--dry-run` 零写入。`feature closeout` 默认只预览 gates；显式 `--apply --owner <owner>` 才会在前后校验与整体回滚保护下写入 Feature Closeout，重复相同 facts 会幂等复用。
+
+Morning report 和 Observe snapshot/UI 复用同一 Feature reducer，优先展示 Status、Next Action、Why、Evidence。`report metrics` 同时生成 monthly JSON/Markdown，所有比例都包含分子、分母、样本量、UTC 窗口和缺失数据说明。
+
+`feature run` 把 validation、目标仓库 preflight、Ready Queue、现有 `run-ready`、晨报、Observe snapshot 和最终 review 串成一次 Feature 意图。默认不写 Git 且每次最多推进一个 Ready 写任务。显式 `--git-mode checkpoint` 才允许创建本地 `agent/<feature-id>` 分支：每个成功任务通过 write-boundary/sensitive-file audit 后提交 checkpoint；失败任务先保存 binary patch、changed/untracked inventory 与内容，再恢复到最近 checkpoint 并验证 clean。它从不授权 push、远程 PR、merge 或 stash。`--keep-failed-diff` 会保留失败 diff、返回 NeedsAction 并立即停止后续任务。
+
+如果 Task 产生业务失败，`feature run` 仍会完成晨报、snapshot 和最终 review，但结果为 `needs-action`、进程退出非零，并保留 batch 与失败证据；无 Ready 时正常退出，并通过 `noReadyReason` 区分已关闭、可交付、待 QA、需人工处理、依赖阻塞或空 Feature。
+
+失败可通过显式 Follow-up 决策闭环接续：ProductBug、TestBug、FlakyTest、DependencyFailure 会生成可批准 Task 草稿；EnvFailure 最近两次连续失败后才生成 `ENV-CHECK-*`，否则优先给出 retry；SpecUnclear、ContractMismatch、RiskyChange、NeedsHuman、Unknown 只生成人工行动卡，绝不进入 Ready。人工用 `feature approve-followup --dry-run` 复核 baseline、证据 hash、ID 冲突和事务计划，再带 `--owner` 批准。批准后新增 TaskSpec、重连下游依赖并进入 Ready；原失败 run/state/handoff 保持不变，重复 run 的新草稿会 supersede 旧 unresolved 草稿但保留历史。
+
 nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 morning report、Observe snapshot 和 controller 版本 artifacts。
 
 自 0.8.0 起，`.harness/task-pool/` 是唯一受支持的 Task Pool runtime root，其中包含根级 `runs.jsonl`、`events.jsonl`、`states/`、`artifacts/`、`failure-handoffs/`、`observability/` 和 `reports/`。这是 hard cutover：旧路径不读取、不迁移、不合并、不重映射；升级意味着本地 Worker Task Pool 历史重置。

package/dist/cli/command-definitions.js

@@ -29,6 +29,7 @@ import { runDagWorkflowPlan } from "../commands/dag-workflow-plan.js";
 import { runDagApprove } from "../commands/dag-approve.js";
 import { runDagReject } from "../commands/dag-reject.js";
 import { runDagReconcileTasks } from "../commands/dag-reconcile-tasks.js";
+import { runDagReconcileRun } from "../commands/dag-reconcile-run.js";
 import { runDagResume } from "../commands/dag-resume.js";
 import { runDagDecisionInspect, runDagDecisionValidate, } from "../workflows/dag/decision-envelope.js";
 import { runDagDoctor, runDagStatus } from "../workflows/dag/lifecycle.js";
@@ -81,6 +82,7 @@ const DAG_SUBCOMMANDS = [
     "doctor",
     "report",
     "closeout-draft",
+    "reconcile-run",
     "reconcile-tasks",
     "final-verification",
     "decision",
@@ -485,6 +487,11 @@ export const COMMAND_DEFINITIONS = [
                 await runDagCloseoutDraft(repoRoot, closeoutArgs);
                 return;
             }
+            if (subcommand === "reconcile-run") {
+                const reconcileRunArgs = rest.filter((arg) => Boolean(arg));
+                await runDagReconcileRun(repoRoot, reconcileRunArgs);
+                return;
+            }
             if (subcommand === "reconcile-tasks") {
                 const reconcileArgs = rest.filter((arg) => Boolean(arg));
                 await runDagReconcileTasks(repoRoot, reconcileArgs);

package/dist/cli/program.js

@@ -10,6 +10,7 @@ import { runDagApprove } from "../commands/dag-approve.js";
 import { runDagFinalVerification } from "../commands/dag-final-verification.js";
 import { runDagInitHybrid } from "../commands/dag-init-hybrid.js";
 import { runDagReconcileTasks } from "../commands/dag-reconcile-tasks.js";
+import { runDagReconcileRun } from "../commands/dag-reconcile-run.js";
 import { runDagReject } from "../commands/dag-reject.js";
 import { runDagCloseoutDraft, runDagReport } from "../commands/dag-report.js";
 import { runDagResume } from "../commands/dag-resume.js";
@@ -300,6 +301,9 @@ async function runDagAction(repoRoot, subcommand, rest) {
         case "closeout-draft":
             await runDagCloseoutDraft(repoRoot, args);
             return;
+        case "reconcile-run":
+            await runDagReconcileRun(repoRoot, args);
+            return;
         case "reconcile-tasks":
             await runDagReconcileTasks(repoRoot, args);
             return;
@@ -319,7 +323,7 @@ async function runDagAction(repoRoot, subcommand, rest) {
             throw new Error("usage: dag decision <inspect|validate> --run-id <id> [--node-id <node-id>]");
         }
         default:
-            throw new Error("usage: dag <init-hybrid|run-task|validate|workflow-plan|workflow-validate|workflow-compile|approve|reject|resume|status|doctor|report|closeout-draft|reconcile-tasks|final-verification|decision> ...");
+            throw new Error("usage: dag <init-hybrid|run-task|validate|workflow-plan|workflow-validate|workflow-compile|approve|reject|resume|status|doctor|report|closeout-draft|reconcile-run|reconcile-tasks|final-verification|decision> ...");
     }
 }
 function compactArgs(args) {
@@ -450,6 +454,7 @@ function addDagCommand(program, defaultRepoRoot) {
         "doctor",
         "report",
         "closeout-draft",
+        "reconcile-run",
         "reconcile-tasks",
         "final-verification",
     ], defaultRepoRoot);

package/dist/commands/dag-reconcile-run.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { writeJsonAtomic } from "../infrastructure/harness/atomic-write.js";
+import { assessDagRunLiveness, assessDagRunRecoveryEligibility, assertDagRunTransferTargetAvailable, getDagRunDir, locateDagRun, readDagRunState, transferDagRunDir, writeDagRunState, } from "../workflows/dag/lifecycle.js";
+export function parseDagReconcileRunArgs(args) {
+    let runId;
+    let action;
+    let reason;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--run-id")
+            runId = args[++index];
+        else if (arg.startsWith("--run-id="))
+            runId = arg.slice("--run-id=".length);
+        else if (arg === "--action")
+            action = parseAction(args[++index]);
+        else if (arg.startsWith("--action="))
+            action = parseAction(arg.slice("--action=".length));
+        else if (arg === "--reason")
+            reason = args[++index];
+        else if (arg.startsWith("--reason="))
+            reason = arg.slice("--reason=".length);
+        else if (arg.startsWith("-"))
+            throw new Error(`unknown dag reconcile-run flag: ${arg}`);
+        else
+            throw new Error(`unexpected positional argument: ${arg}`);
+    }
+    if (!runId)
+        throw new Error("dag reconcile-run requires --run-id <id>");
+    if (action && !reason?.trim()) {
+        throw new Error("dag reconcile-run mutation requires --reason <text>");
+    }
+    return { runId, action, ...(reason?.trim() ? { reason: reason.trim() } : {}) };
+}
+function parseAction(value) {
+    if (value === "supersede" || value === "abandon")
+        return value;
+    throw new Error("dag reconcile-run --action must be supersede or abandon");
+}
+export async function runDagReconcileRun(repoRoot, rawArgs) {
+    const parsed = parseDagReconcileRunArgs(rawArgs);
+    const located = await locateDagRun(repoRoot, parsed.runId);
+    if (!located)
+        throw new Error(`dag run not found: ${parsed.runId}`);
+    const state = await readDagRunState(located.runDir);
+    const liveness = assessDagRunLiveness({ state });
+    const eligibility = assessDagRunRecoveryEligibility({
+        lifecycle: located.lifecycle,
+        state,
+        liveness: liveness.status,
+    });
+    if (!parsed.action) {
+        console.log(JSON.stringify({
+            action: "inspect",
+            runId: state.runId,
+            lifecycle: located.lifecycle,
+            status: state.status,
+            liveness: liveness.status,
+            eligibility,
+            nextRecommendedAction: eligibility.canReconcile
+                ? "Re-run with --action supersede|abandon and --reason <text>."
+                : "Do not reconcile this run; inspect runner and lifecycle evidence first.",
+        }, null, 2));
+        return;
+    }
+    if (!eligibility.canReconcile || !eligibility.allowedActions.includes(parsed.action)) {
+        throw new Error(`dag run ${state.runId} is not eligible for reconciliation: ${eligibility.reasons.join(", ") || "unknown reason"}`);
+    }
+    const reconciledAt = new Date().toISOString();
+    const completedRunDir = getDagRunDir(repoRoot, "completed", state.runId);
+    if (located.lifecycle !== "completed") {
+        await assertDagRunTransferTargetAvailable(completedRunDir);
+    }
+    const artifactRelativePath = path.join(".harness", "dag-runs", "completed", state.runId, "reconciliation.json").replace(/\\/g, "/");
+    await writeJsonAtomic(path.join(located.runDir, "reconciliation.json"), {
+        schemaVersion: 1,
+        runId: state.runId,
+        action: parsed.action,
+        reason: parsed.reason,
+        reconciledAt,
+        previousLifecycle: located.lifecycle,
+        previousStatus: state.status,
+        liveness: liveness.status,
+        originalState: state,
+    });
+    const previousStatus = state.status;
+    for (const node of Object.values(state.nodes)) {
+        if (node.status !== "RUNNING")
+            continue;
+        node.status = "ERROR";
+        node.finishedAt = reconciledAt;
+        node.failureCategory = `operator-${parsed.action}`;
+    }
+    state.status = parsed.action === "supersede" ? "superseded" : "abandoned";
+    state.finishedAt = reconciledAt;
+    state.failureCategory = `operator-${parsed.action}`;
+    state.reconciliation = {
+        action: parsed.action,
+        reason: parsed.reason,
+        reconciledAt,
+        previousStatus,
+        previousLifecycle: located.lifecycle,
+        liveness: liveness.status,
+        artifactPath: artifactRelativePath,
+    };
+    await writeDagRunState(located.runDir, state);
+    const runDir = located.lifecycle === "completed"
+        ? located.runDir
+        : await transferDagRunDir(located.runDir, completedRunDir);
+    console.log(JSON.stringify({
+        action: parsed.action,
+        runId: state.runId,
+        status: state.status,
+        lifecycle: "completed",
+        reason: parsed.reason,
+        reconciliationArtifactPath: artifactRelativePath,
+        runDir,
+    }, null, 2));
+}

package/dist/commands/init.js

@@ -443,11 +443,20 @@ fi
 feature_dirs=()
 for root in features product/features dogfood/features; do
   [[ -d "\${root}" ]] || continue
-  while IFS= read -r acceptance; do
-    feature_dirs+=("$(dirname "\${acceptance}")")
-  done < <(find "\${root}" -mindepth 2 -maxdepth 2 -name acceptance.yaml -type f | sort)
+  while IFS= read -r feature_dir; do
+    if [[ ! -f "\${feature_dir}/acceptance.yaml" ]]; then
+      echo "product-line docs check failed: incomplete feature packet missing acceptance.yaml: \${feature_dir}" >&2
+      exit 1
+    fi
+    feature_dirs+=("\${feature_dir}")
+  done < <(find "\${root}" -mindepth 1 -maxdepth 1 -type d | sort)
 done
 
+if [[ \${#feature_dirs[@]} -eq 0 ]]; then
+  echo "product-line docs check skipped: no feature packets found"
+  exit 0
+fi
+
 for feature_dir in "\${feature_dirs[@]}"; do
   echo "==> validate product-line feature: \${feature_dir}"
   agent-worker task validate-feature "\${feature_dir}"

package/dist/governance/manifest-types.js

@@ -42,6 +42,7 @@ export const workflowPolicyDagTemplateSchema = z.enum([
     "review-gated-dag",
     "supervised-implementation",
 ]);
+export const workflowPolicyOutputLanguageSchema = z.enum(["zh-CN", "en"]);
 export const workflowPolicySchema = z
     .object({
     /** Preferred implementation workflow for recoverable loop-agent work. Declarative policy; callers may still require explicit CLI flags. */
@@ -51,6 +52,9 @@ export const workflowPolicySchema = z
         .default("agent-dag"),
     dag: z
         .object({
+        outputLanguage: workflowPolicyOutputLanguageSchema
+            .optional()
+            .default("zh-CN"),
         defaultEntry: z
             .enum(["dag run-task", "run-dag"])
             .optional()

package/dist/worker/cli.js

@@ -17,6 +17,15 @@ import { getTaskPoolRoot, prepareTaskPoolRetry } from "./pool/run-store.js";
 import { taskSpecSchema } from "./task-spec/schema.js";
 import { validateTaskSpec } from "./task-spec/validate.js";
 import { validateFeatureTaskGraph } from "./task-graph/validate.js";
+import { renderFeatureReview, reviewFeature } from "./feature/review.js";
+import { renderFeatureRun, runFeature } from "./feature/run.js";
+import { draftFollowUpDecision } from "./follow-up/factory.js";
+import { approveFollowUp } from "./follow-up/approve.js";
+import { prepareFeatureDelivery } from "./delivery/package.js";
+import { previewFeatureCloseout, renderCloseoutPreview } from "./closeout/preview.js";
+import { applyFeatureCloseout } from "./closeout/apply.js";
+import { projectMonthlyMetrics } from "./metrics/projector.js";
+import { runFeatureFinalVerification } from "./delivery/final-verification.js";
 export function buildAgentWorkerProgram() {
     const program = new Command();
     program
@@ -28,6 +37,129 @@ export function buildAgentWorkerProgram() {
     const batch = program.command("batch").description("Task Pool batch utilities");
     const report = program.command("report").description("Task Pool reporting utilities");
     const observe = program.command("observe").description("Observe UI server and snapshot utilities");
+    const feature = program.command("feature").description("Feature-level review and delivery workflow");
+    feature
+        .command("review")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .description("Derive Feature status, blockers, acceptance coverage, and next action")
+        .action(async (options) => {
+        const result = await reviewFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot: path.resolve(options.repo),
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureReview(result));
+    });
+    feature
+        .command("run")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--dry-run", "Show validation, Ready tasks, steps, and expected artifacts without writes")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .option("--limit <count>", "Maximum Ready tasks (without checkpoint mode capped at 1)", "1")
+        .option("--git-mode <mode>", "Git mode: none or checkpoint", "none")
+        .option("--keep-failed-diff", "Keep a failed task diff and stop instead of restoring")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--batch-run-id <id>", "Batch run id")
+        .option("--check-repo", "Run bash scripts/check-repo.sh during target repo preflight")
+        .option("--check-repo-command <command...>", "Override the check-repo preflight command")
+        .option("--quiet", "Suppress human-readable progress on stderr")
+        .option("--pi-model <model>", "Smoke override for pi executor nodes")
+        .description("Validate and advance one Ready Feature task through the existing Worker pipeline")
+        .action(async (options) => {
+        if (options.gitMode !== "none" && options.gitMode !== "checkpoint")
+            throw new Error("feature run --git-mode must be none or checkpoint");
+        if (options.keepFailedDiff && options.gitMode !== "checkpoint")
+            throw new Error("--keep-failed-diff requires --git-mode checkpoint");
+        const repoRoot = path.resolve(options.repo);
+        const batchRunId = options.batchRunId ?? buildBatchRunId(new Date());
+        const client = new LoopAgentClient({
+            loopAgentBin: options.loopAgentBin,
+            artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", batchRunId),
+        });
+        let progress;
+        try {
+            progress = createCompositeProgressReporter({
+                quiet: options.quiet ?? options.dryRun ?? false,
+                eventStore: createRoutedWorkerEventStore(repoRoot),
+                context: { batchRunId },
+            });
+        }
+        catch {
+            progress = createProgressReporter({ quiet: options.quiet ?? options.dryRun ?? false });
+        }
+        const result = await runFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot,
+            client,
+            dryRun: options.dryRun ?? false,
+            limit: Number.parseInt(options.limit, 10),
+            batchRunId,
+            runCheckRepo: options.checkRepo ?? false,
+            ...(options.checkRepoCommand ? { checkRepoCommand: options.checkRepoCommand } : {}),
+            progress,
+            ...(options.piModel ? { piModel: options.piModel } : {}),
+            gitMode: options.gitMode === "checkpoint" ? "checkpoint" : "none",
+            keepFailedDiff: options.keepFailedDiff ?? false,
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureRun(result));
+        if (result.status === "failed" || result.status === "needs-action")
+            process.exitCode = 1;
+    });
+    feature
+        .command("verify-final")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--task-id <id>", "Completed qa-execute TaskSpec to rerun as dedicated final verification")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--json", "Emit stable JSON")
+        .description("Run an independent HEAD-bound final QA verification and project Delivery evidence")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        const client = new LoopAgentClient({ loopAgentBin: options.loopAgentBin, artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", `final-verification-${Date.now()}`) });
+        const result = await runFeatureFinalVerification({ featureDir: path.resolve(options.featureDir), repoRoot, taskId: options.taskId, client });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nFinal verification: ${result.workerRunId}\nQA evidence: ${result.qaEvidencePath}\nFinal evidence: ${result.finalVerificationPath}\n`);
+    });
+    feature
+        .command("delivery")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--qa-evidence <path>", "Repo-local QA pass evidence")
+        .requiredOption("--final-verification <path>", "Repo-local fresh final verification evidence")
+        .option("--waivers <path>", "Repo-local acceptance waiver decisions JSON")
+        .option("--dry-run", "Validate and show the Delivery Package plan without writes")
+        .option("--json", "Emit stable JSON")
+        .description("Validate checkpointed Feature evidence and prepare a local Delivery Package")
+        .action(async (options) => {
+        const result = await prepareFeatureDelivery({
+            featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo),
+            qaEvidencePath: options.qaEvidence, finalVerificationPath: options.finalVerification,
+            ...(options.waivers ? { waiverPath: options.waivers } : {}), dryRun: options.dryRun ?? false,
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nDelivery: ${result.status}\nArtifacts: ${Object.values(result.artifacts).join(", ")}\nBlockers: ${result.blockers.join("; ") || "none"}\n`);
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
+    feature
+        .command("closeout")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--apply", "Apply Feature Closeout (reserved for M2-08)")
+        .option("--owner <owner>", "Closeout owner for apply")
+        .option("--json", "Emit stable JSON")
+        .description("Preview Feature Closeout gates without modifying the Feature Packet")
+        .action(async (options) => {
+        if (options.apply) {
+            const result = await applyFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo), owner: options.owner ?? "" });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
+        const result = await previewFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo) });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderCloseoutPreview(result));
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
     task
         .command("validate")
         .argument("<task-yaml>", "TaskSpec YAML file")
@@ -74,6 +206,58 @@ export function buildAgentWorkerProgram() {
         });
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     });
+    task
+        .command("draft-followup")
+        .argument("<task-id>", "Failed parent Task id")
+        .requiredOption("--worker-run-id <id>", "Failed Worker run id")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--feature-dir <dir>", "Feature Packet directory")
+        .option("--json", "Emit JSON instead of the human summary")
+        .description("Create or reuse a classified Follow-up Task draft or human action card")
+        .action(async (taskId, options) => {
+        try {
+            const result = await draftFollowUpDecision({
+                repoRoot: path.resolve(options.repo),
+                featureDir: path.resolve(options.featureDir),
+                taskId,
+                workerRunId: options.workerRunId,
+            });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : result.kind === "TaskDraft"
+                    ? `Follow-up: ${result.followUpId}\n结果: ${result.created ? "已生成任务草稿" : "复用现有任务草稿"}\n下一步: agent-worker feature approve-followup --feature-dir ${JSON.stringify(path.resolve(options.featureDir))} --followup-id ${result.followUpId} --repo ${JSON.stringify(path.resolve(options.repo))} --owner <owner>\n证据: ${result.draftPath}\n`
+                    : `Follow-up: ${result.followUpId}\n结果: ${result.created ? "已生成人工行动卡" : "复用现有行动卡"}\n下一步: ${result.actionCard.command ?? result.actionCard.label}\n证据: ${result.draftPath}\n`);
+        }
+        catch (error) {
+            handleFollowUpCliError(error, options.json ?? false, "draft-followup");
+        }
+    });
+    feature
+        .command("approve-followup")
+        .requiredOption("--feature-dir <dir>", "Feature Packet directory")
+        .requiredOption("--followup-id <id>", "Follow-up approval id")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--owner <name>", "Human owner approving the Follow-up")
+        .option("--dry-run", "Validate baseline and show the transaction plan without writes")
+        .option("--json", "Emit JSON instead of the human summary")
+        .description("Approve a Follow-up and atomically add its TaskSpec to the Feature")
+        .action(async (options) => {
+        try {
+            const result = await approveFollowUp({
+                repoRoot: path.resolve(options.repo),
+                featureDir: path.resolve(options.featureDir),
+                followUpId: options.followupId,
+                owner: options.owner,
+                dryRun: options.dryRun ?? false,
+            });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : `Follow-up: ${result.followUpId}\n结果: ${result.status === "planned" ? "批准事务预览通过" : result.idempotent ? "已批准（幂等复用）" : "已批准并进入 Ready"}\n下一步: agent-worker feature review --feature-dir ${JSON.stringify(path.resolve(options.featureDir))} --repo ${JSON.stringify(path.resolve(options.repo))}\n证据: ${result.approvalPath}\n`);
+        }
+        catch (error) {
+            handleFollowUpCliError(error, options.json ?? false, "approve-followup");
+        }
+    });
     batch
         .command("run-ready")
         .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
@@ -169,6 +353,16 @@ export function buildAgentWorkerProgram() {
         });
         process.stdout.write(`${JSON.stringify({ ok: true, outputPath }, null, 2)}\n`);
     });
+    report
+        .command("metrics")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--month <yyyy-mm>", "UTC reporting month")
+        .option("--json", "Emit the metrics JSON on stdout")
+        .description("Project monthly Feature delivery metrics to JSON and Markdown")
+        .action(async (options) => {
+        const result = await projectMonthlyMetrics({ repoRoot: path.resolve(options.repo), month: options.month });
+        process.stdout.write(options.json ? `${JSON.stringify(result.metrics, null, 2)}\n` : `${JSON.stringify({ ok: true, jsonPath: result.jsonPath, markdownPath: result.markdownPath }, null, 2)}\n`);
+    });
     return program;
 }
 export async function main(argv = process.argv) {
@@ -177,6 +371,28 @@ export async function main(argv = process.argv) {
 async function readTaskYaml(taskSpecPath) {
     return YAML.parse(await readFile(taskSpecPath, "utf-8"));
 }
+function handleFollowUpCliError(error, json, action) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (!json)
+        throw error;
+    const code = detail.includes("only supports ProductBug")
+        ? "unsupported-failure-category"
+        : detail.includes("baseline changed")
+            ? "stale-feature-baseline"
+            : detail.includes("already exists") || detail.includes("collision")
+                ? "follow-up-conflict"
+                : detail.includes("evidence") || detail.includes("draft hash")
+                    ? "follow-up-evidence-invalid"
+                    : "follow-up-failed";
+    process.stdout.write(`${JSON.stringify({
+        schemaVersion: 1,
+        status: "failed",
+        action,
+        error: { code, message: detail },
+        nextAction: action === "draft-followup" ? "Inspect the failed Worker run and failure category." : "Regenerate and review the Follow-up draft before approving.",
+    }, null, 2)}\n`);
+    process.exitCode = 1;
+}
 function isDirectRun() {
     const entry = process.argv[1];
     if (!entry)