@tea-agent/loop-agent 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-07-24
+
+### 重点更新
+
+- 前端规范读取范围扩展，新增 ai_workspace 作为并列来源，并独立展示各类规范证据
+- 前端实现 DAG 引入 lint 债务基线机制，精准区分存量与新增代码问题，减少误阻断
+- 前端预写门禁增强，强制校验真实的规范读取事件，避免遗漏关键上下文
+- 后端测试报告结构优化，新增 Markdown 报告并改进 HTML 报告的分层展示
+
+### 新增
+
+- 前端规范读取将 ai_workspace 目录与 openspec 相关目录作为并列来源，即使缺少 package.json 也能发现本地规范候选
+- Dashboard 规范证据 API 与界面独立展示知识库查询、openspec 检索和成功读取三类证据
+- 后端测试在同目录下新增生成 backend-test.md 报告，便于查阅测试结论与明细
+
+### 改进
+
+- 前端实现 DAG 允许未修改文件中的已知 lint 诊断作为基线债务继续，但对修改文件的新问题严格阻断
+- 后端测试 HTML 报告采用更清晰的分层展示，新增稳定结论图标与可折叠的质量校验明细，移除了原稳定性指标
+- 前端测试用例的内容完整性与证据检查降级为建议性反馈，不再因个别物料缺失阻断最终复盘
+- 设计文档与研发 DAG 拓扑说明同步更新，澄清了 profile/workflow/type 三套正交概念与当前实现状态
+
+### 修复
+
+- 修复前端技能指令可能超出预算限制的问题
+- 修复 DAG 未正确注册 DeepSeek Pi 模型提供者的问题
+- 修复前端目标项目验证路由不够健壮的问题
+- 修复后端测试中无法跨环境便携解析 Python 运行时的问题
+
+## [0.21.0] - 2026-07-24
+
+### 重点更新
+
+- DAG/Pi 自适应活跃度监管：精准区分传输活动与真实执行进展，受控处置静默卡死，避免误杀。
+- 后端测试执行范围收窄：仅运行最终 Markdown 明确映射且通过安全校验的脚本，杜绝无关测试混入。
+- 后端测试 HTML 报告全面升级：采用清晰的用例卡片，直观展示脱敏的请求与响应详情。
+
+### 新增
+
+- DAG/Pi 自适应 liveness 与非误杀监管：区分 runner lease、transport 活动与 Provider/tool/output 真实进展；节点可投影 active/quiet/suspected-stall/probing/needs-attention；静默 stall 会受控终止，退出无法确认时禁止自动重试；Pi absolute max 对齐 4h；Worker 默认不再给 `run-dag` 设置外层 wall-clock，显式 `worker.timeout_ms` 仍为 hard timeout。
+
+### 改进
+
+- backend-test 第 7 节点现在只执行最终 Markdown `自动化映射` 明确声明且安全校验通过的 pytest 脚本，避免历史或无关 `test_*.py` 混入本轮 JUnit/HTML；空映射、缺失脚本或越界路径会 fail-closed。
+- backend-test HTML 报告升级为更清晰的用例卡片：保留测试结论、质量状态和失败概览，直接展示简洁测试场景、自动化用例名称、结果与耗时，并为通过/失败用例都展示同次执行中脱敏且有界的接口请求参数与响应结果；HTML 不再附带技术证据章节，审计路径与哈希继续保留在 facts/JUnit。
+- frontend-test 第四节点不再扫描或阻断 pytest、原生 Playwright、`npx playwright`、`@playwright/test` 或 Node Playwright API 等可执行工具指令；该节点只保留 manifest、Case/AC/path、非生产 URL 和标准 `playwright-cli open` 前缀等结构与安全门禁，并强烈建议浏览器执行优先使用 `playwright-cli`。
+- frontend-test 用例内容、Case ID、AC 关联与 evidence 完整性检查改为 advisory：缺失或损坏的执行物料不再被自动改写为 blocked，也不阻断最终复盘；finding 汇入结构化结果，并在 Markdown retrospective 后生成中文 HTML 建议报告。路径越界、跨用例 evidence 引用、writeSet、生产环境与凭据安全仍保持硬门禁。
+- frontend-test checklist JavaScript 通过 Base64 参数交给 Node 解码执行，并修正变量声明顺序与重复语句，避免 Git Bash 将 `\s` / `\d`、反引号或引号破坏后再交给 Node。
+- 新初始化项目的 harness 指南同步 adaptive liveness、4h absolute max、stall 状态与 `termination-unconfirmed` 处置；旧项目可由 `init check-update` 识别未修改的受管指南，并通过 `init update --apply-safe` 安全刷新。
+
 ## [0.20.1] - 2026-07-24
 
 ### 新增
@@ -17,6 +67,9 @@
 
 ### 改进
 
+- backend-test 第 4 个 Markdown 校验节点只将前置条件、操作步骤和预期结果作为必需章节；需求来源引用有效性不再阻断后续测试。普通质量问题保持 advisory，但 secret-shaped 值会先生成脱敏安全报告再 fail-closed，避免进入 pytest、HTML/facts 和最终报告。
+- backend-test 生成的真实 HTTP pytest 现在必须输出脱敏且有界的请求/响应日志，包含 method、URL/path、请求参数摘要、响应状态和响应 body 摘要；追溯节点会在 Markdown 映射脚本范围内把日志合同缺口记录为 advisory。
+- backend-test 第 7 节点的 HTML/facts 按测试概览、质量校验、失败概览、用例执行明细和技术证据分层展示；第 8 节点使用固定简洁的中文收口结构，减少重复原文并优先展示结论和风险。
 - Operator Console「恢复」面板自动拉取 DAG 运行与节点候选，优先展示失败项并以选择器填入，仍可手动输入
 - 从节点重跑预检失败时展示真实安全资格阻断原因，不再误报为「无法获取 planHash」
 - 恢复页长操作（完整重跑等）会回写终态成功/失败；不再只提示「已接受」后无下文
@@ -33,10 +86,28 @@
 - frontend-test 环境预检：在生成用例前对冻结的非生产 `baseUrl` 做 curl 可达性探测；不可达或缺少 curl 时以 `frontend-base-url-unreachable` / `curl-unavailable` 阻断 generate/map，并写入 `environmentProbe` 事实。节点 5 manifest 物化改为 ruleId 失败分类、map 配额预检与 temp+rename 原子写入；生成/清单/执行强制 playwright-cli-only，U/D 场景要求当前用户数据归属或 create/Mock/blocked。
 - 前端测试 DAG 的证据自检改为按用例降级：个别缺失、空白或格式错误的证据会如实标为 blocked 并继续生成复盘报告；只有全部用例都未产生任何证据内容或证据路径不安全时才失败。
 
+### 修复
+
+- Observe 总览 KPI 问号提示框宽度与窄卡片解耦：提示框使用稳定的 240–280px 视口安全宽度，并在五列、三列和两列布局的右侧列向内对齐，避免宽屏下被压缩成约 78px 的窄条；hover 与键盘焦点行为保持不变。
+- 节点检查器的规范证据文件预览会渲染 Markdown 标题、列表、表格与代码块，不再把正文作为带语法标记的纯文本显示。
+
 ## [0.20.0] - 2026-07-23
 
 ### 新增
 
+- 继续收紧前端实现证据门禁：禁止空 verification contract，校验验证目标与 requirement/UI state/授权路径绑定；新版 review context 缺失 writer baseline 时直接阻断，非 `not-needed` Mock 策略必须提供 endpoint 与 consumer 证据。
+- 前端写入前重新校验 DAG 绑定源文件的 SHA-256；Mock endpoint 现在必须声明 fixture 与 consumer，且验证 trace 必须记录成功的 Mock 命令。
+- 前端验证 bundle 现在冻结实际命令文本，并将实现契约 targets 限制在 writer writeSet 内，避免验证证据与可写范围漂移。
+- 同步前端 prewrite/review context 的 DAG JSON Schema，避免生成 DAG 因 freshness、writeSet 或 baseline 字段漂移而被错误拒绝。
+- 前端 prewrite 现在强制校验需求源新鲜度，验证 Schema 也要求声明实际命令文本，减少旧 DAG 和证据配置的隐式降级。
+- 前端实现 DAG 的验证命令与侦察范围改为从目标项目自身的 package scripts、包管理器和允许路径推导，不再假设目标项目沿用 loop-agent 的目录与命令布局。
+
+### 改进
+
+- 前端实现 DAG 的验证命令与侦察范围改为从目标项目自身的 package scripts、包管理器和允许路径推导，不再假设目标项目沿用 loop-agent 的目录与命令布局。
+- 后端测试用例默认生成中文 README 索引与模块用例卡片，步骤、预期、需求依据和自动化映射更便于测试、研发与评审人员阅读。
+- 后端测试 HTML 主报告现在逐条展示用例编号、中文名称与场景、脚本、测试函数、结果、耗时和失败原因，完整技术详情可折叠查看。
+
 - streamline implementation DAG (#61)
 - improve human-readable artifacts
 
@@ -60,6 +131,7 @@
 ### 改进
 
 - `frontend-implementation` 保留独立 contract/scout，并把 Mock 策略与 implementation contract 合入 plan，把写前授权、验证/失败评估、复验和 review context 分别收敛为组合 shell 节点。standard/high-risk 固定 15 个顶层节点、small-risk 13 个；绿色路径执行 11 个节点、7 次 Pi，同时保留唯一 prewrite 写入授权、同 writeSet repair、真实 diff review 与 fail-closed closeout。
+- 加强前端实现节点的证据链：Trace 只绑定本次实际成功执行的验证命令，契约兼容转换不再补入占位文件或默认验证目标，Prewrite 要求上游节点明确完成，review context 校验 artifact 绑定，并以 writer 前工作区快照隔离既有用户改动。
 - 优化操作与观测统一界面的导航与布局，合并确认与运行为「开始运行」，DAG 详情跳转路径更加准确
 
 ### 修复

package/dist/adapters/loop-agent.js

@@ -63,6 +63,11 @@ function getVerifyCommands(repoRoot, options) {
     if (manifestCommands) {
         return applyQuota(manifestCommands, options);
     }
+    if (options.taskConfig?.taskKind === 'frontend-implementation') {
+        const frontendCommands = getFrontendProjectVerifyCommands(repoRoot, options);
+        if (frontendCommands)
+            return frontendCommands;
+    }
     const quickCommands = [
         {
             args: ['bash', 'scripts/check-repo.sh'],
@@ -91,6 +96,53 @@ function getVerifyCommands(repoRoot, options) {
             : [...quickCommands, ...standardCommands, ...fullCommands];
     return applyQuota(selectedCommands, options);
 }
+function getFrontendProjectVerifyCommands(repoRoot, options) {
+    let scripts;
+    try {
+        const packageJson = JSON.parse(readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+        if (!packageJson.scripts || typeof packageJson.scripts !== 'object')
+            return undefined;
+        scripts = packageJson.scripts;
+    }
+    catch {
+        return undefined;
+    }
+    let packageManager = 'npm';
+    for (const [lockfile, manager] of [
+        ['pnpm-lock.yaml', 'pnpm'],
+        ['yarn.lock', 'yarn'],
+        ['bun.lockb', 'bun'],
+        ['bun.lock', 'bun'],
+    ]) {
+        try {
+            readFileSync(path.join(repoRoot, lockfile));
+            packageManager = manager;
+            break;
+        }
+        catch {
+            // Try the next package-manager marker.
+        }
+    }
+    const hasScript = (name) => typeof scripts[name] === 'string' && String(scripts[name]).trim().length > 0;
+    const commandFor = (name) => ({
+        args: name === 'test'
+            ? [packageManager, 'test']
+            : [packageManager, 'run', name],
+        cwd: repoRoot,
+        label: `${packageManager} ${name === 'test' ? 'test' : `run ${name}`}`,
+    });
+    const collect = (names) => names.filter(hasScript).map(commandFor);
+    const staticCommands = collect(['typecheck', 'check-types', 'lint', 'check', 'build']);
+    const behaviorCommands = collect(['test:unit', 'test:frontend', 'test:component', 'test', 'test:e2e', 'e2e']);
+    if (staticCommands.length === 0 && behaviorCommands.length === 0)
+        return undefined;
+    const selected = options.phase === 'final'
+        ? [...staticCommands, ...behaviorCommands]
+        : staticCommands;
+    if (selected.length === 0)
+        return behaviorCommands;
+    return applyQuota(selected, options);
+}
 function applyQuota(commands, options) {
     if (options.phase === 'final' || !options.quota || options.quota === 'full') {
         return commands;

package/dist/commands/init.js

@@ -522,10 +522,107 @@ has_npm_script() {
   node -e "const fs=require('fs'); const p=JSON.parse(fs.readFileSync('package.json','utf8')); process.exit(p.scripts && p.scripts[process.argv[1]] ? 0 : 1)" "\${script}" >/dev/null 2>&1
 }
 
+dag_lint_assessment_allows_skip() {
+  [[ -n "\${HARNESS_DAG_RUN_DIR:-}" ]] || return 1
+  command -v node >/dev/null 2>&1 || return 1
+  node - "\${HARNESS_DAG_RUN_DIR}" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const runDir = path.resolve(process.argv[2]);
+const assessmentPath = path.join(runDir, "contracts", "frontend-lint-assessment.json");
+const fail = () => process.exit(1);
+const sha256 = (value) => crypto.createHash("sha256").update(value).digest("hex");
+const readContained = (relative) => {
+  if (typeof relative !== "string" || path.isAbsolute(relative)) fail();
+  const absolute = path.resolve(runDir, relative);
+  if (absolute !== runDir && !absolute.startsWith(runDir + path.sep)) fail();
+  return fs.readFileSync(absolute);
+};
+let assessment;
+try {
+  assessment = JSON.parse(fs.readFileSync(assessmentPath, "utf8"));
+} catch {
+  fail();
+}
+if (
+  assessment.schemaVersion !== 1 ||
+  assessment.schemaId !== "frontend-lint-assessment-v1" ||
+  !["passed", "baseline-debt"].includes(assessment.status) ||
+  !assessment.commandIdentity ||
+  !Array.isArray(assessment.commandIdentity.commands) ||
+  assessment.commandIdentity.commands.length === 0 ||
+  !Array.isArray(assessment.writerChangedFiles) ||
+  !Array.isArray(assessment.blockingDiagnostics) ||
+  assessment.blockingDiagnostics.length !== 0 ||
+  !Array.isArray(assessment.blockingReasons) ||
+  assessment.blockingReasons.length !== 0
+) fail();
+const commandHash = sha256(JSON.stringify(assessment.commandIdentity.commands));
+if (commandHash !== assessment.commandIdentity.sha256) fail();
+if (!assessment.commandIdentity.commands.every((command) =>
+  /(?:^|[\\s'"])npm(?:['"])?\\s+(?:['"])?run(?:['"])?\\s+(?:['"])?lint(?:['"])?(?:\\s|$)/.test(command)
+)) fail();
+if (
+  (assessment.status === "passed" && assessment.currentExitCode !== 0) ||
+  (assessment.status === "baseline-debt" && assessment.currentExitCode === 0)
+) fail();
+if (!assessment.baselineRef || assessment.baselineRef.nodeId !== "frontend-lint-baseline-shell") fail();
+const baselineRaw = readContained(assessment.baselineRef.path);
+if (sha256(baselineRaw) !== assessment.baselineRef.sha256) fail();
+let baseline;
+try {
+  baseline = JSON.parse(baselineRaw);
+} catch {
+  fail();
+}
+if (
+  baseline.schemaVersion !== 1 ||
+  baseline.schemaId !== "frontend-lint-baseline-v1" ||
+  baseline.status !== "available" ||
+  baseline.commandIdentity?.sha256 !== assessment.commandIdentity.sha256
+) fail();
+if (assessment.status === "baseline-debt") {
+  if (
+    !Array.isArray(assessment.currentDiagnostics) ||
+    assessment.currentDiagnostics.length === 0 ||
+    assessment.currentDiagnostics.length !== assessment.toleratedDiagnosticCount ||
+    !Array.isArray(baseline.diagnostics)
+  ) fail();
+  const key = (item) => JSON.stringify([
+    item.file, item.line, item.column, item.severity, item.message, item.ruleId ?? null,
+  ]);
+  const baselineCounts = new Map();
+  for (const item of baseline.diagnostics) {
+    const value = key(item);
+    baselineCounts.set(value, (baselineCounts.get(value) || 0) + 1);
+  }
+  const changed = new Set(assessment.writerChangedFiles);
+  for (const item of assessment.currentDiagnostics) {
+    if (changed.has(item.file)) fail();
+    const value = key(item);
+    const count = baselineCounts.get(value) || 0;
+    if (count === 0) fail();
+    baselineCounts.set(value, count - 1);
+  }
+}
+if (!Array.isArray(assessment.rawEvidenceRefs) || assessment.rawEvidenceRefs.length === 0) fail();
+for (const ref of assessment.rawEvidenceRefs) {
+  if (sha256(readContained(ref.path)) !== ref.sha256) fail();
+}
+process.exit(0);
+NODE
+}
+
 if [[ -f package.json ]]; then
   if command -v npm >/dev/null 2>&1; then
     for script in lint typecheck test build; do
       if has_npm_script "\${script}"; then
+        if [[ "\${script}" == "lint" ]] && dag_lint_assessment_allows_skip; then
+          echo "==> lint handled by frontend DAG assessment (status: passed or baseline-debt)"
+          ran=1
+          continue
+        fi
         run_cmd npm run "\${script}"
       fi
     done
@@ -2057,6 +2154,13 @@ function buildTargetLoopAgentHarness(input) {
         "",
         "Use `loop-agent new-task`, `loop-agent dag run-task`, `loop-agent dag validate`, and `loop-agent run-dag` for non-trivial implementation work.",
         "",
+        "## Adaptive Liveness",
+        "",
+        "- Healthy Pi nodes are no longer stopped by a fixed 30-minute deadline. The default 4h absolute max is a final safety bound and cannot be extended by synthetic heartbeats.",
+        "- Runner heartbeat proves only the runner lease. Provider, tool, or output activity records meaningful progress; prolonged inactivity can surface as `quiet`, `suspected-stall`, `probing`, or `needs-attention` in `dag status`, `dag doctor`, and Observe.",
+        "- A silent transport is aborted in a controlled way. `termination-unconfirmed` means the old attempt may still exist, so loop-agent fails closed and does not start an automatic retry; inspect the run before any operator recovery.",
+        "- `agent-worker` does not set an outer `run-dag` wall-clock by default. An explicit `worker.timeout_ms` remains a hard timeout.",
+        "",
         "## Operator Recovery",
         "",
         "After a run, use `loop-agent dag report --run-id <run-id> --markdown` to read canonical run facts and `loop-agent dag doctor --run-id <run-id> --markdown` to diagnose failed or paused runs. Failed DAG runs should produce a failure handoff via `loop-agent dag closeout-draft --run-id <run-id>` instead of a successful closeout.",

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

@@ -19,6 +19,8 @@ export const DAG_PI_MODEL_PROVIDERS = {
     "gpt-5.3-codex-spark": "wizard-local",
     "gpt-5.5": "wizard-local",
     "glm-5.2": "wizard-local",
+    "deepseek-v4-flash": "deepseek",
+    "deepseek-v4-pro": "deepseek",
 };
 const SAFE_PI_STEPS = new Set([
     "analyze",
@@ -263,6 +265,17 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
             beforePathFingerprints = undefined;
         }
     }
+    const reportActivity = input.reportActivity;
+    const attempt = input.attempt ?? 1;
+    const bridgeActivity = reportActivity
+        ? (kind, at) => {
+            reportActivity({
+                attempt,
+                kind,
+                at: at ?? new Date().toISOString(),
+            });
+        }
+        : undefined;
     const result = await piStepFn({
         attachedFiles: [],
         modelConfig: resolveDagPiModelConfig(input.model),
@@ -272,6 +285,19 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
         toolNames: resolveDagPiToolNames(input.task),
         userMessage: buildDagPiUserMessage(input.task, persona, step),
         sessionEventsPath: path.join(meta.runDir, input.task.id, "session-events.jsonl"),
+        // Absolute max wall clock from adaptive liveness policy (defaults to 4h).
+        timeoutMs: input.timeoutMs,
+        stallTimeoutMs: input.stallTimeoutMs,
+        abortGraceMs: input.abortGraceMs,
+        onActivity: bridgeActivity
+            ? (activity) => {
+                if (activity.kind === "lease"
+                    || activity.kind === "synthetic-heartbeat") {
+                    return;
+                }
+                bridgeActivity(activity.kind, activity.at);
+            }
+            : undefined,
     });
     const context = {
         channel: "dag",

package/dist/executors/pi-executor.js

@@ -47,8 +47,13 @@ export function extractSubagentStats(stdout) {
         parts.push(`agents=[${Array.from(agents).sort().join(',')}]`);
     return parts.join(' | ');
 }
-export const DEFAULT_TIMEOUT_MS = 1_800_000;
-export const MAX_ALLOWED_TIMEOUT_MS = 1_800_000;
+/** Absolute max wall clock for a single Pi attempt (4h). Not renewed by empty heartbeats. */
+export const DEFAULT_TIMEOUT_MS = 14_400_000;
+export const MAX_ALLOWED_TIMEOUT_MS = 14_400_000;
+/** Max provider/CLI transport silence before initiating a controlled abort (15m). */
+export const DEFAULT_STALL_TIMEOUT_MS = 900_000;
+/** Grace after SIGTERM before SIGKILL on absolute max. */
+export const DEFAULT_ABORT_GRACE_MS = 30_000;
 const PI_BACKEND_ENV = 'CODE_AGENT_PI_BACKEND';
 const OUTPUT_PREVIEW_HEAD_CHARS = 64_000;
 const OUTPUT_PREVIEW_TAIL_CHARS = 64_000;
@@ -515,7 +520,9 @@ async function runCliOrchestration(options, meta) {
     }
     const primaryHardFail = !primaryResult.ok;
     const primaryInvalidOutput = primaryResult.ok && primaryIssues.length > 0;
-    const shouldFallback = primary.fallback && ((primaryHardFail && shouldRetryWithFallback(primaryResult.stderr, primaryResult.stdout))
+    const shouldFallback = primary.fallback && ((primaryHardFail
+        && primaryResult.failureCategory !== 'termination-unconfirmed'
+        && shouldRetryWithFallback(primaryResult.stderr, primaryResult.stdout))
         || primaryInvalidOutput);
     if (shouldFallback) {
         const fallbackResult = await executeSingleCliAttempt(options, primary.fallback);
@@ -590,7 +597,9 @@ async function runCliOrchestration(options, meta) {
 function shouldFallbackSdkToCli(sdkResult, validationIssues) {
     if (sdkResult.ok && validationIssues.length > 0)
         return true;
-    if (!sdkResult.ok && (sdkResult.failureCategory === 'auth' || sdkResult.failureCategory === 'timeout')) {
+    if (!sdkResult.ok && (sdkResult.failureCategory === 'auth'
+        || sdkResult.failureCategory === 'timeout'
+        || sdkResult.failureCategory === 'termination-unconfirmed')) {
         return false;
     }
     if (!sdkResult.ok && shouldRetryWithFallback(sdkResult.stderr, sdkResult.stdout))
@@ -655,9 +664,15 @@ async function executeSingleCliAttempt(options, modelConfig) {
         ? `${modelConfig.provider}/${modelConfig.model}`
         : modelConfig.model ?? 'default';
     const timeoutMs = options.timeoutMs ?? modelConfig.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+    const abortGraceMs = options.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS;
     let timedOut = false;
+    let terminationUnconfirmed = false;
+    let supervisionStderr = '';
     let timeoutHandle;
+    let stallHandle;
     let sigkillHandle;
+    let exitConfirmationHandle;
     // Build pi CLI arguments (same as before).
     // We invoke pi via `node <pi-cli-path>` instead of relying on `#!/usr/bin/env node`
     // to avoid provider resolution issues when spawned from tsx-managed processes.
@@ -698,39 +713,39 @@ async function executeSingleCliAttempt(options, modelConfig) {
         const stdoutPreview = new BoundedTextPreview('stdout');
         const stderrPreview = new BoundedTextPreview('stderr', 16_000, 16_000);
         const stdoutCollector = new PiJsonlStreamCollector();
+        let settled = false;
         child.stdout.setEncoding('utf-8');
         child.stderr.setEncoding('utf-8');
-        child.stdout.on('data', (chunk) => {
-            stdoutPreview.append(chunk);
-            stdoutCollector.append(chunk);
-        });
-        child.stderr.on('data', (chunk) => {
-            stderrPreview.append(chunk);
-        });
-        child.on('error', (err) => {
-            if (timeoutHandle)
-                clearTimeout(timeoutHandle);
-            if (sigkillHandle)
-                clearTimeout(sigkillHandle);
-            reject(err);
-        });
-        child.on('close', (code) => {
+        const clearSupervisionTimers = () => {
             if (timeoutHandle)
                 clearTimeout(timeoutHandle);
+            if (stallHandle)
+                clearTimeout(stallHandle);
             if (sigkillHandle)
                 clearTimeout(sigkillHandle);
+            if (exitConfirmationHandle)
+                clearTimeout(exitConfirmationHandle);
+        };
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearSupervisionTimers();
             const durationMs = Date.now() - startedAt;
             const stdout = stdoutPreview.text();
-            const stderr = stderrPreview.text();
+            const capturedStderr = stderrPreview.text();
+            const stderr = [supervisionStderr, capturedStderr].filter(Boolean).join('\n');
             const collected = stdoutCollector.finish();
-            const failureCategory = classifyPiFailure({
-                assistantText: collected.assistantText,
-                exitCode: code,
-                stderr,
-                stdout,
-                timedOut,
-                outputTooLarge: collected.outputTooLarge,
-            });
+            const failureCategory = terminationUnconfirmed
+                ? 'termination-unconfirmed'
+                : classifyPiFailure({
+                    assistantText: collected.assistantText,
+                    exitCode: code,
+                    stderr,
+                    stdout,
+                    timedOut,
+                    outputTooLarge: collected.outputTooLarge,
+                });
             resolve({
                 assistantText: collected.assistantText,
                 command: ['pi', ...piArgs],
@@ -738,7 +753,7 @@ async function executeSingleCliAttempt(options, modelConfig) {
                 exitCode: code,
                 failureCategory,
                 modelDisplay,
-                ok: code === 0 && collected.assistantText.length > 0 && !collected.outputTooLarge,
+                ok: !timedOut && code === 0 && collected.assistantText.length > 0 && !collected.outputTooLarge,
                 parsedEvents: collected.parsedEvents,
                 stderr,
                 stdout,
@@ -749,16 +764,76 @@ async function executeSingleCliAttempt(options, modelConfig) {
                 tokensUsed: collected.tokensUsed,
                 subagentStats: collected.subagentStats,
             });
+        };
+        const hasConfirmedExitCode = () => child.exitCode !== null && child.exitCode !== undefined;
+        const beginControlledTermination = (reason) => {
+            if (timedOut || settled)
+                return;
+            timedOut = true;
+            supervisionStderr = reason;
+            child.kill('SIGTERM');
+            sigkillHandle = setTimeout(() => {
+                if (settled)
+                    return;
+                if (hasConfirmedExitCode()) {
+                    finish(child.exitCode);
+                    return;
+                }
+                child.kill('SIGKILL');
+                exitConfirmationHandle = setTimeout(() => {
+                    if (settled)
+                        return;
+                    if (hasConfirmedExitCode()) {
+                        finish(child.exitCode);
+                        return;
+                    }
+                    terminationUnconfirmed = true;
+                    supervisionStderr += `\npi CLI exit was not confirmed within ${abortGraceMs}ms after SIGKILL`;
+                    finish(null);
+                }, abortGraceMs);
+            }, abortGraceMs);
+        };
+        const armStallWatchdog = () => {
+            if (stallTimeoutMs <= 0 || timedOut || settled)
+                return;
+            if (stallHandle)
+                clearTimeout(stallHandle);
+            stallHandle = setTimeout(() => {
+                beginControlledTermination(`pi CLI step stalled after ${stallTimeoutMs}ms with no stdout/stderr activity`);
+            }, stallTimeoutMs);
+        };
+        const reportOutputActivity = () => {
+            armStallWatchdog();
+            try {
+                options.onActivity?.({ kind: 'output', at: new Date().toISOString() });
+            }
+            catch {
+                // best-effort: never fail the pi step
+            }
+        };
+        child.stdout.on('data', (chunk) => {
+            stdoutPreview.append(chunk);
+            stdoutCollector.append(chunk);
+            if (chunk.length > 0)
+                reportOutputActivity();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrPreview.append(chunk);
+            if (chunk.length > 0)
+                reportOutputActivity();
         });
+        child.on('error', (err) => {
+            clearSupervisionTimers();
+            settled = true;
+            reject(err);
+        });
+        child.on('close', (code) => {
+            finish(code);
+        });
+        armStallWatchdog();
         if (timeoutMs > 0) {
             timeoutHandle = setTimeout(() => {
-                timedOut = true;
-                child.kill('SIGTERM');
-                sigkillHandle = setTimeout(() => {
-                    if (child.exitCode === null) {
-                        child.kill('SIGKILL');
-                    }
-                }, 5_000);
+                beginControlledTermination(`pi CLI step timed out after ${timeoutMs}ms`);
             }, timeoutMs);
         }
     });