@tea-agent/loop-agent 0.39.0-beta.5 → 0.39.0-beta.7

package/CHANGELOG.md

@@ -2,11 +2,22 @@
 
 ## [Unreleased]
 
+- 前端 review `request_review_changes` 不再被静默当作成功（方向 A）：`frontend-review-pi` 提交 typed `request_review_changes` 时，run 终态判定为「未通过」（`partial_failed` + `terminalReason=review-request-changes`，即使全部节点 FINISHED 也不显示成功），committed findings 自动渲染为 run-owned 下游任务 PRD 草稿 `contracts/frontend-review-findings-prd.md`（含 issueCategory/evidenceRefs/findings/restartPhase 指引），并生成 recovery trigger（issueCategory→failureOwner 映射，new-dag）。`deriveDagRerunFeedback` 新增 typed-fact 通道：无文本 verdict、无 convergence 的 frontend 场景也能把 committed `request_review_changes` findings 注入下一轮 `<rerun_feedback>`，问题不再丢失、下一轮从 restartPhase 定点修复而非重复流程。
+- 前端 review findings PRD 草稿携带修复范围路由信号（方向 A 补充）：`deriveFrontendReviewFixScope` 从 committed findings 确定性推导建议 shape（单文件无远程 API→micro、同目录集中多文件→small、跨目录/API 信号→standard）与建议 complexity、目标文件、建议 allowedPaths；PRD 标题改为「修复 review 发现（<shape>）：<目标文件>」，正文新增「修复范围（供下一轮任务生成路由）」段（含 small 信号词，如「单文件局部修复」「无远程接口」），下一轮任务以该 PRD 生成 DAG 时，`resolveFrontendTaskShape` 能把小修复路由到 micro=7/small=10 节点拓扑，而非默认 11 节点 standard 全流程。
+- 前端 shape 分类 API 否定词覆盖中文空格形式（冒烟暴露边界）：`无 API/网络调用`、`无 API` 等表述不再被误判为远程 API 信号（原 `\b(...)\b` 对 CJK 开头无词边界），`resolveFrontendTaskShape` 与 `deriveFrontendReviewFixScope` 的 hasApiSignal 判定同步修正——带「无 API/无接口」声明的单文件小修复正确路由 micro/small，而非误升级 standard。
+- 前端实现契约对 `decision=new` 的退化空 `specReference` 归一化兜底（冒烟暴露 plan invalid-output）：模型偶发把 new 组件输出成 `specReference:{path:"",section:"",line:null}`（空对象而非 prompt 要求的 null），原校验直接判 `invalid-output` 触发完整 plan 重试；`frontendImplementationContractSchema` preprocess 新增 `normalizeNewComponentSpecReference`——new 选择携带空 path 的退化 specReference 时按 null 意图归一化为缺省（非空 path 的 `specified` 命中原样保留，真实 new+specReference 仍拒绝），一次格式滑动不再烧掉整个 plan attempt。
 - 深度合入 origin/main（source e68dfbe1）：以 frontend-node typed-tools 拓扑为基底移植 main 硬化——canonical artifact 消费、fail-closed 无验证 marker、风险分级细化（DEPENDENCY_INSTALL_LANGUAGE）、`HARNESS_DAG_RERUN_PROMPT_OVERRIDE` prompt override、Pi SDK 运行时依赖 0.83.0 与 `engines node>=22.19.0`、next-release scripts 入包；废弃节点（verify-assess/reverify/repair-pi/plan-revision/final-design-review/lint-baseline shell）能力确认被当前流程覆盖后裁剪对应实现（repair-gate 机制、lint-baseline shell 类型），plan retry 文案对齐 committed ledger；affected 392 + M2-M9 303 测试全绿，fast 3909/3910、integration 397/398（各 1 个 fn 既有失败）。
 
 ### 重点更新
 
-- Console「设置」页新增「模型配置（models.json）」区块：以弹框形式增/改/删 Pi 的模型条目，支持 6 个定义字段（id、name、contextWindow、maxTokens、input、reasoning）。新增时 Provider 用下拉选择、其余字段自动补默认值；编辑时 Provider 只读且仅在原位置就地替换，只改表单内字段、不覆盖配置里页面未展示的其它字段（如 cost/compat）；不读写 API key（凭据走 Pi CLI）。编辑已存在的模型不再被移到最后。
+- 修复 Console 四处评审缺陷（合并前收口）：① 向导「运行」进度块接通——`runDag` 只返回 operationId，原实现读的 `recovery.dagRunId` 在向导路径永远为空；现在确认页先快照基线 run、进入运行页后轮询 `observeLink`，以 (taskId, operationId) 任一变化为失效信号（operationId 覆盖「重新运行」按钮——它不改变向导步骤；taskId 覆盖运行步骤中手动改任务 ID 的场景，失效时基线一并重置，避免沿用上一任务的 run）：新派发/切任务会清掉旧选中 run 并重新解析，**只接受与当前任务基线不同的新 run**；从 Recovery 带回的共享选中 run 先做归属校验——`GET /api/dag-runs/:id` 详情响应新增 `taskId` 投影（源自 run.json 的 `taskContractBinding`→`sourceBinding`→Hybrid 标题，与 observeLink/candidates 同一绑定真源，不受候选列表 limit 截断影响；404 视为失效选中、无绑定视为不可判定），非本任务的 run 不展示；校验全程由 effect 生命周期栅栏保护——任务/运行/选中在异步校验期间变化时，旧响应直接丢弃、不会改写新状态；校验暂不可用时按有界退避（2s→30s，约 2 分钟）自动重试而非被动等待状态变化，重试计划为纯函数并有行为测试；**展示层另有闸门**——进度面板与运行操作只消费「本解析器已采纳/已验证」的 run（组件 state），未验证期间（校验中、重试中、give-up 后）进度面板保持空缺，不会即时或永久显示其他任务的 DAG；「打开检视」「侧栏预览」两个入口同样双重门禁（按钮无已验证 run 即禁用 + 处理器复核 verifiedRunId），共享的 openInspectSplit 解析器不再能带出未验证的外来 run。解析决策本身抽取为纯状态机 `pages/tasks/run-id-resolution.ts`（首跑/重跑/切任务/外来选中/基线门控五类迁移），Effects 只做薄适配，主流程「确认页基线快照 → runDag 派发 → observeLink 轮询 → 新 run 采纳」有完整行为测试。基线快照为三态（成功/权威无运行/暂不可查），**查询失败不会被当成「没有历史运行」**——快照重试期间基线保持未知、探测轮询等待，不会把旧运行误判为新运行；新 run 创建失败或注册较慢时进度面板宁可空缺也不把上一次已终止的 DAG 当作当前运行（轮询上限 5 分钟后安静停止）。② 失败建议数据契约修正——旅程卡原先把原始 run 级 `failureCategory` 直接查归一化建议表（`missing-api-key`/`nonzero-exit` 等永远查不中，节点分类又在安全投影中被丢弃）；现在纯分类核心下沉 `src/shared/dag-failure-category.ts`（console↔workflows 双向共享叶，不破坏 console 禁止 import workflows 的边界测试），服务端投影把 run 级与节点级分类都归一化输出（success/skipped 不出），卡片按「失败节点分类优先、run 级兜底」取值，失败卡始终有可操作建议。③ Recovery interrupt 资格轮询在运行中档位同步刷新 run 状态——原先状态只在选中时读一次，运行中的 run 结束后仍永久保持 4 秒快轮询；现在 4 秒档附带轻量 `GET /api/dag-runs/:id` 刷新 `effectiveStatus`，终态后自动退到 30 秒。④ Inspect 紧凑检视一次瞬时刷新失败不再永久显示错误——成功刷新回合会清除上一轮 error 横幅。
+- Operator Chat 输入框两项交互增强：① **↑/↓ 历史输入召回**——每次发送的文本进入输入历史（连续重复折叠、上限 100 条），光标在首行按 ↑ 逐条向旧回溯、按 ↓ 向新前进，越过最新一条时恢复回溯前**未发送的草稿**（草稿不会被历史浏览冲掉）；多行文本中部的方向键仍是普通光标移动，IME 组词与 @文件/命令面板打开时不抢占。② **运行中排队下一轮指令**——当前回合运行中 Enter 不再被吞掉，消息作为「排队消息」绑定当前 Turn（服务端 `PUT deferred-turn` 从仅限 stopping 放开为 running/stopping，错误码 `TURN_NOT_STOPPING`→`TURN_NOT_ACTIVE`），当前回合结束（正常完成或停止）后自动发送；排队条提供「立即发送」（停止当前回复并立即发出）、「编辑」（移回输入框改写后再排）、「删除」三种操作，运行中输入框右侧提供排队发送按钮（与停止按钮并列）；排队条单行展示（状态 + 省略号预览 + 操作按钮一行），输入框默认一行高（自动增高上限 280px 不变）。
+- 向导「运行」面板结构化与预期管理（A2/C9）：新增实时运行进度块——节点完成计数与百分比进度条（含 progressbar 无障碍语义）、当前运行节点名称与已运行时长、失败节点与错误摘要，数据来自 `/api/dag-runs/:id` 每 5 秒轮询并在终态自动停止；`effectiveStatus=running-suspected-stall` 时显示橙色「疑似停滞」提示条（建议打开检视查看节点活动或到恢复页协作中止/诊断），把 20–40 分钟长跑的「日志噪音等待」变为有阶段感、可判断的等待。原始 SSE 事件日志默认折叠为「原始事件日志（最近 80 条）」，需要排查时再展开。
+- Console 前端三项体验优化（P0/P2）：① Recovery 页 DAG 紧凑检视侧栏（InspectSplitPanel）从一次性快照改为实时刷新——运行中每 5 秒自动拉取节点/事件并新增「进行中/已结束」刷新状态行，到达终态（finished/failed/partial_failed/superseded/abandoned）自动停止轮询，刷新轮不清空既有内容避免闪烁；② Chat 任务旅程卡失败态新增按归一化 failureCategory 的可操作「建议」行（validation/executor/write-guard/timeout/auth/human-required/human-rejected/shell-command/static-error/decision-envelope/unknown 各映射到具体下一步：从失败节点重跑、修正契约后重新生成、跳「模型与认证」页等），不再只报「原因分类为 X」；③ Recovery 页 interrupt 资格轮询退避：选中 run 已终态（含 interrupted）时从 4 秒降到 30 秒，运行中保持 4 秒。
+- Console 对话页 Models 面板的模型管理增强：以弹框形式增/改/删 Pi 的模型条目，支持 6 个定义字段（id、name、contextWindow、maxTokens、input、reasoning）。新增时 Provider 用下拉选择、其余字段自动补默认值；编辑时 Provider 只读且仅在原位置就地替换，只改表单内字段、不覆盖配置里页面未展示的其它字段（如 cost/compat）；不读写 API key（凭据走 Pi CLI）。编辑已存在的模型不再被移到最后。（该能力仅在对话页提供，设置页不再重复入口。）
+- 修复 `markdown-traceability` pipeline 未将冻结 `backendLayout` 传给 `validateBackendMarkdownTraceability`，自定义 layout 下不再回落默认 `testcase/md` ENOENT；新增回归用例以非默认 nested layout（`testRoot=testcase/elb/remote`、`markdownRel=md`）执行真实 shell pipeline，traceability 从自定义 Markdown 目录读取并 PASS，默认 layout 行为不变。（验证：`npm run typecheck`、`npx vitest run test/backend-test-markdown-workflow.test.ts test/backend-test-layout.test.ts`、`npm run build`、`git diff --check`。）
+- backend-test 快速补强（backend-test-fast-failclosed-attribution）：两处 fail-open 缺口已 fail-closed。① 当前轮次 Markdown 作用域严格依赖唯一有效 `## Module Index`——README 缺失 / 不可读 / `## Module Index` 重复（或缺标题）/ 唯一但空或不可解析任一状态，`markdownFiles` 与 coverage `markdownModuleFiles` 均返回空作用域而非回退全目录扫描，历史 `.md` 不再渗入 Case/coverage/partition facts，`resolveBackendTestManifestModules` 新增可区分 `manifestStatus`（valid/missing/unreadable/duplicate/empty-unparsable）与 `moduleIndexHeadingCount`，`validateBackendMarkdownCases` 与 `analyzeBackendTestCaseCoverage` 为非法状态各推 FAIL finding，默认与自定义 `backendTest` 布局一致。② collection 分类器不再凭 `__NNN_*` 裸 import 名称单独判 REPAIRABLE：inventory 构建时预计算每个 mapped script 的裸本地 helper import 证据（`scriptBareImports`），只有「存在同名 generated-local helper asset 且 mapped script 源码确实 import 该裸模块」才判 REPAIRABLE 并给精确 repairPaths；无 helper asset / mapped script 无对应 import / 无法精确归因一律 `BLOCKED`（`missing-generated-local-helper-without-evidence`。真第三方模块缺失保持 BLOCKED，不通过 PYTHONPATH/sys.path/conftest/ImportError fallback 绕行。（验证：`npm run typecheck`、backend-test 四聚焦 vitest、`npm run build`、`git diff --check`。）
+- backend-test 后续修复（backend-test-fast-manifest-import-fix）：Markdown 用例校验与 coverage 分析改为按 README `## Module Index` 清单限定本轮有效模块资产——未声明旧 `.md`（如 legacy.md）不再进入 Case/coverage/partition 统计，报告改为显式非静默 unmanifested advisory；“清单声明但文件缺失” fail-closed 明确失败，默认与自定义 `backendTest` 布局统一生效。generated pytest 裸本地 helper import（`from __551_manager_helpers import ...`）在 writer completeness gate 判为 recoverable 并给出精确 mapped 脚本 target path；collection 分类器对可归因到 mapped 资产的裸本地 helper `ModuleNotFoundError` 判 REPAIRABLE 并提供精确 repairPaths，真正第三方依赖缺失仍保持 BLOCKED。不放宽 self-contained、writeSet、forbiddenPaths、skip/xfail、断言与单次业务执行约束（验证：`npm run typecheck`、backend-test 聚焦 vitest、`npm run build`、`git diff --check`）。
 - 前端风险分级细分 manifest 触及语义：`allowedPaths` 含 `package.json`/lockfile 或需求文本提到 package.json 不再单独触发 `new-dependency` high-risk（改一行 script、调构建参数的任务不再被顶到强制全门禁并误标高风险），只有任务文本同时出现安装语言（npm install / yarn add / pnpm add / 新增依赖等）才升级；仅路径触及时记 `new-dependency:manifest-path-without-install-language` 拒绝信号，审计可溯。
 - 前端验证 fallback 生成期诚实化：真实项目无可读取的 `package.json` scripts 且未探测到本地 tsc 时，不再注入必然失败的 `npm run typecheck` / `npm run build` / `npm test`（纯静态 / vanilla JS 站点原会在 verify 阶段假失败），改为执行显式 no-op 标记命令（`No frontend verification command configured`，进入冻结命令集可被 contract 引用，trace 如实记录 not-run），并写生成期 advisory 提示用 `--verify` 或执行约束显式声明验证命令后重新生成 DAG。无 repoRoot 的单测 fixture 保留历史 generic fallback。**标记不构成验证证据（fail-closed）**：verification trace 将绑定标记的 target 判为失败、只含标记的 static 证据判为 unavailable，repair 分类归为 non-repairable `contract`，verify 节点以 `frontend verification unavailable` 硬失败阻断 review/closeout——无真实验证命令的 run 无法走完绿灯链。
 - frontend-test `passed` 回执链改按 dispatch 序号判序（B-HASH-01）：`summarizePlaywrightCliReceipts` 先按 `sequence` 排序再判 open→find→cleanup 连续链；并行 `find`/`screenshot` 按完成时间落盘导致的乱序不再误杀执行已通过的 case（Wave 1 实测 4 条 passed 被改判 `browser-command-evidence-missing`）。真 gap / 重复序号仍 fail-closed。
@@ -31,6 +42,7 @@
 ### 新增
 
 - Operator Chat 时间线左缘新增「用户消息锚点栏」：每个用户输入一枚横向小条（12×3px 微圆角），紧凑等距排列并在时间线高度内垂直居中；条数超出栏高时相邻锚点自动聚合为稍宽的聚合条（悬停展开「N 条聚合输入」逐条列表，时间 + 单行预览，逐条点击定位）。悬停时小条向对话一侧平滑伸长（12→18px）并变橙，浮窗右侧弹出（白底圆角，正文最多 3 行、超出省略号，附序号与时间）；单击平滑滚动定位到对应消息（精确停靠在视口顶部偏移 8px）；覆盖视口顶部的锚点保持高亮。空会话自动隐藏；历史分页/流式更新/窗口缩放时自动重算（rAF 节流）。
+- frontend-test 产物根可配置：`task.json.frontendTest.testRoot` 缺省仍为 `testcase/frontend`，省略时生成的 DAG 路径与历史默认根一致；自定义根（如 `qa/frontend-test`）在编译期冻结并驱动 writer、gate、playwright 围栏与 `allowedPaths`。`.harness/**` 等隐藏/治理树在生成期拒绝。
 - 实验能力「编辑失败节点提示词后从节点重跑」（默认关闭）：内部开关 `HARNESS_DAG_RERUN_PROMPT_OVERRIDE=1` 启用后，`dag rerun` 支持 `--prompt-override <nodeId>@<file>`（全文替换）与 `--prompt-override-append <nodeId>@<file>`（追加指令：保留冻结原提示词，末尾追加 `<operator_addendum>` 块）。仅限 ERROR 且位于 reset closure 内的节点；mode + base/最终 prompt sha256 计入 planHash（execute 漂移即 `PLAN_DRIFT`），父 run spec 冻结、provenance（含 mode）落 `continuation.promptOverrides`。Console 新增 `dagPromptOverrideConfig` 开关探测 action，`dagRerunPlan`/`dagRerun` 接受 `promptOverrides`（`{nodeId, prompt, mode?}`）；Inspect DAG 节点 inspector 新增「提示词重启」tab——默认「追加指令」模式（只读底稿 + 追加编辑器），可切换「全文替换（高级）」，预检通过展示执行估算，提交后续跑并跳转新 run，全程不离开图页；开关开启时 `/inspect` 只注入 **scoped** 变体凭据（独立 cookie + `__INSPECT_MUTATION_TOKEN__`，与 Console 通用 token 互不可重放），mutations 路由对 inspect 凭据仅放行 `dagRerunPlan`/`dagRerun`（其余 action 403 `ACTION_NOT_IN_INSPECT_SCOPE`），Inspect 不获得通用写能力；开关关闭时不注入任何 token、tab 不出现，检视面保持严格只读。
 - 观察面 DAG Inspector 节点详情适配 Pi 扩展：执行器输入摘要展示节点声明的 `piExtensions` 短 id；新增「Pi 扩展运行事实」展示 `pi-extensions.json` 的 resolved（包名@版本）与 missing 降级原因（缺包降级不再静默）；产物未生成/损坏时降级提示不阻断接口，绝对路径不外泄。
 - 后端实现 DAG（standard / review-gated / supervised）的 Pi 节点支持按桶显式加载本机 Pi 导航扩展：读侧节点（除 closeout）加载 `pi-codegraph` + `pi-lens`，写侧节点只加载 `pi-codegraph`（pi-lens 的 `ast_grep_replace` 可绕过 writeSet，不加载）；前端/测试模板与省略字段节点保持扩展全关。扩展发现始终关闭，只经白名单解析 `~/.pi/agent` 与项目 `.pi` settings 的已装包（缺包降级不失败，产物 `pi-extensions.json` 记录 requested/resolved/missing）；session 后 pin 工具面剔 builtin 同名、deny 面与写工具，writer 的 `edit`/`write` 仍为 policy-wrapped；`.codegraph/**` index 同步不再计入 write-guard 越界。

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.39.0-beta.5",
-  "gitSha": "0981b80311d973603a870fd80693331cb5e48335",
-  "builtAt": "2026-08-23T11:38:56.113Z"
+  "version": "0.39.0-beta.7",
+  "gitSha": "7f2b8f56e95923c3bde69fffa0575cfeae065c42",
+  "builtAt": "2026-08-24T02:16:38.537Z"
 }

package/dist/commands/client-recovery.js

@@ -1356,12 +1356,15 @@ export async function runClientRecovery(input) {
     }
     const plugin = await installProjectOpenCodePlugin({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const overflowPlugin = await installProjectOpenCodeOverflowCompactPlugin({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const piExtension = await installProjectPiContextOverflowExtension({
         repoRoot: input.repoRoot,
+        onlyIfMissing: true,
     });
     const pi = await applyProjectPiSettingsMerge({ repoRoot: input.repoRoot });
     if (mode !== "user") {

package/dist/commands/task-advance.js

@@ -355,6 +355,25 @@ export async function runTaskAdvance(repoRoot, args) {
                 intervalMs: options.progressIntervalMs,
             });
         }
+        // Idempotent client-recovery surface install before any DAG run: the Pi
+        // context-overflow extension / OpenCode plugins / project .pi settings
+        // are normally installed by `loop-agent init`, but an upgraded or
+        // non-init-created project may lack them. Installing here (missing-only)
+        // ensures the overflow compact+retry recovery path is always present,
+        // independent of how the project was created. Best-effort: a failure to
+        // install never blocks the run.
+        if (options.approveGate && !options.dryRun) {
+            try {
+                const { runClientRecovery } = await import("./client-recovery.js");
+                // mode "project" installs only project-owned surfaces
+                // (.pi/extensions + .opencode/plugins + .pi/settings.json),
+                // never the user home; installs are missing-only.
+                await runClientRecovery({ repoRoot, mode: "project" });
+            }
+            catch {
+                // best-effort; do not fail the run over a recovery-surface install
+            }
+        }
         const result = await advanceTaskLifecycle(toUseCaseInput(repoRoot, taskId, options, progress?.observer));
         const outcome = mapOutcome(result);
         const gateStop = result.lifecycleState === "awaiting-write-set-approval" &&

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

@@ -15,6 +15,7 @@ import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelai
 import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
+import { frontendTestLayoutFromSpec, } from "../workflows/dag/frontend-test-layout.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
 /**
  * Writer classification for a length-stopped thinking-only attempt: the model
@@ -25,6 +26,15 @@ import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
  * recoverable partial-write-set (incomplete-write-set) upgrade.
  */
 export const WRITER_THINKING_EXHAUSTED_CATEGORY = "writer-thinking-exhausted";
+/**
+ * The writer session burned an excessive token budget (a read-edit-test loop
+ * that never converged) and still failed. Distinct from empty-output so the
+ * report shows the real cause and recovery recommends a fresh compacted run.
+ * Not auto-retried by default; operators may rerun after a model switch.
+ */
+export const WRITER_BUDGET_EXHAUSTED_CATEGORY = "writer-budget-exhausted";
+/** Token ceiling for a single writer node before it is judged budget-exhausted. */
+export const WRITER_TOKEN_BUDGET = 2_000_000;
 function readWriterThinkingExhaustionEvidence(result) {
     const wider = result;
     return {
@@ -324,6 +334,49 @@ export function scanReviewTerminalKindsFromSessionEvents(content) {
     }
     return kinds;
 }
+/** Read-only discovery tool budget for frontend-plan-pi. Exceeding it means
+ * the plan re-read upstream outputs/sources instead of trusting typed facts,
+ * which blows up the context window (400 request-too-large). */
+const PLAN_READ_TOOL_BUDGET = 40;
+/** Deterministic read-burst guard for frontend-plan-pi: count read-only
+ * discovery tool calls (read/grep/ls/find) from the session log. Over budget →
+ * read-burst, retried with a reduced-reading instruction. Pure scan; a
+ * successful plan under budget is never blocked. */
+export async function detectPlanReadBurst(input) {
+    const sessionEventsPath = path.join(input.runDir, input.nodeId, "session-events.jsonl");
+    let count = 0;
+    try {
+        const content = await readFile(sessionEventsPath, "utf8");
+        for (const line of content.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event.type === "tool_execution_start" &&
+                    typeof event.toolName === "string" &&
+                    (event.toolName === "read" ||
+                        event.toolName === "grep" ||
+                        event.toolName === "ls" ||
+                        event.toolName === "find")) {
+                    count += 1;
+                }
+            }
+            catch {
+                // skip unparseable line
+            }
+        }
+    }
+    catch {
+        // Missing/unreadable session log → no burst detection
+        return [];
+    }
+    if (count > PLAN_READ_TOOL_BUDGET) {
+        return [
+            `frontend plan read-burst: ${count} read-only tool calls (budget ${PLAN_READ_TOOL_BUDGET}). Trust the upstream contract/scout typed facts; do not re-read contract/scout outputs or source files already captured. Minimize discovery reads, commit record_* facts directly, then finalize_plan.`,
+        ];
+    }
+    return [];
+}
 export const FRONTEND_DESIGN_TERMINAL_TOOL_NAMES = new Set([
     "approve_design",
     "request_design_changes",
@@ -654,7 +707,9 @@ export async function createFrontendPlanLedgerTools(input) {
     const optionalStringArray = Type.Optional(stringArray);
     const requirementSchema = Type.Object({
         id: Type.String({}),
-        expectedOutcome: Type.String({}),
+        expectedOutcome: Type.Optional(Type.String({
+            description: "Optional. When omitted, the runtime derives it from the contract requirement. Prefer omitting it to keep this tool call small.",
+        })),
         implementationTargets: stringArray,
         verificationTargetIds: stringArray,
         evidenceGap: Type.Optional(Type.Object({
@@ -706,7 +761,7 @@ export async function createFrontendPlanLedgerTools(input) {
         commandLabel: Type.String({}),
         file: Type.String({}),
         symbol: Type.Optional(Type.String({
-            description: "Real exported identifier or describe/it title in the target file. Forbidden for type=static (runtime strips it); required for non-static targets.",
+            description: "Optional. Real exported identifier or describe/it title in the target file. Omit it to keep the call small — the trace gate then only verifies the file exists and the command ran. Forbidden for type=static (runtime strips it).",
         })),
         requirementIds: stringArray,
         uiStates: stringArray,
@@ -795,9 +850,9 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordTargetSurfaceTool = defineTool({
         name: "record_target_surface",
         label: "record_target_surface",
-        description: "Record the plan target surface (routes + files) as an origin=plan target-surface fact.",
-        promptSnippet: "Record the plan target surface fact.",
-        parameters: Type.Object({ targets: Type.Optional(targetsSchema), files: stringArray }, { additionalProperties: false }),
+        description: "Record the plan target surface (routes only) as an origin=plan target-surface fact. files are owned by the runtime skeleton / scout — omit them.",
+        promptSnippet: "Record the plan target surface (routes) fact.",
+        parameters: Type.Object({ targets: Type.Optional(targetsSchema), files: optionalStringArray }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
             const routes = stringList(params?.targets?.routes);
             const files = stringList(params?.files);
@@ -808,24 +863,28 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordComponentChoiceTool = defineTool({
         name: "record_component_choice",
         label: "record_component_choice",
-        description: "Record component choices and styling strategy as an origin=plan component-choice fact.",
-        promptSnippet: "Record the plan component-choice fact.",
+        description: "Record ONE component choice (origin=plan component-choice fact). Only declare components you add or replace; reuse of existing components needs no entry. Omit rationale for reuse-existing; it is optional. Call once per component — one tool call per message. Optionally include stylingStrategy (set it once, on the first call).",
+        promptSnippet: "Record one component choice (one tool call per message).",
         parameters: Type.Object({
-            uiComponentChoices: Type.Optional(Type.Array(uiComponentChoiceSchema)),
+            choice: uiComponentChoiceSchema,
             stylingStrategy: optionalString,
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
-            const uiComponentChoices = Array.isArray(params?.uiComponentChoices)
-                ? params.uiComponentChoices
-                : [];
-            const components = uiComponentChoices
-                .map((choice) => typeof choice?.component === "string" ? choice.component : "")
-                .filter(Boolean);
+            const rawChoice = params?.choice;
+            if (!isRecordObject(rawChoice)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "component-choice",
+                    error: "record_component_choice requires a non-empty choice object",
+                });
+            }
+            const choice = rawChoice;
+            const components = typeof choice.component === "string" ? [choice.component] : [];
             const result = await adoptPlanFact("component-choice", `${attemptId}:record_component_choice:${randomUUID()}`, {
                 kind: "component-choice",
                 origin: "plan",
                 components,
-                uiComponentChoices,
+                uiComponentChoices: [choice],
                 ...(params?.stylingStrategy
                     ? { stylingStrategy: params.stylingStrategy }
                     : {}),
@@ -934,8 +993,8 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordPlanRequirementTool = defineTool({
         name: "record_plan_requirement",
         label: "record_plan_requirement",
-        description: "Commit one plan requirement entry (origin=plan plan-requirement fact). Call once per requirement; each entry carries id, expectedOutcome, implementationTargets, verificationTargetIds, and optional evidenceGap.",
-        promptSnippet: "Commit one plan requirement entry.",
+        description: "Commit one plan requirement entry (origin=plan plan-requirement fact). Call once per requirement; entry carries id, implementationTargets, verificationTargetIds, and optional expectedOutcome (omit it — the runtime derives the outcome text from the contract requirement). IMPORTANT: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
+        promptSnippet: "Commit one plan requirement entry (one tool call per message).",
         parameters: Type.Object({
             entry: requirementSchema,
         }, { additionalProperties: false }),
@@ -956,8 +1015,8 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordPlanVerificationTargetTool = defineTool({
         name: "record_plan_verification_target",
         label: "record_plan_verification_target",
-        description: "Commit one plan verification target entry (origin=plan plan-verification-target fact). Call once per target; entry carries id, type, commandLabel, file, symbol, requirementIds, uiStates.",
-        promptSnippet: "Commit one plan verification target entry.",
+        description: "Commit one plan verification target entry (origin=plan plan-verification-target fact). Call once per target; entry carries id, type, commandLabel, file, requirementIds, uiStates, and optional symbol (omit it — the trace gate verifies the file and command, not a symbol). IMPORTANT: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
+        promptSnippet: "Commit one plan verification target entry (one tool call per message).",
         parameters: Type.Object({
             entry: verificationTargetSchema,
         }, { additionalProperties: false }),
@@ -978,8 +1037,8 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordPlanEvidenceGapTool = defineTool({
         name: "record_plan_evidence_gap",
         label: "record_plan_evidence_gap",
-        description: "Commit one plan evidence gap entry (origin=plan plan-evidence-gap fact). Call once per gap; entry carries requirementId, description, blocking.",
-        promptSnippet: "Commit one plan evidence gap entry.",
+        description: "Commit one plan evidence gap entry (origin=plan plan-evidence-gap fact). Call once per gap; entry carries requirementId, description, blocking. IMPORTANT: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
+        promptSnippet: "Commit one plan evidence gap entry (one tool call per message).",
         parameters: Type.Object({
             entry: evidenceGapSchema,
         }, { additionalProperties: false }),
@@ -1949,10 +2008,11 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                         throw new Error(`unknown command capability: ${capability}`);
                     }
                     if (capability === "playwright-cli") {
-                        const caseId = resolveCaseIdFromWriteSet(input.task.writeSet) ??
+                        const layout = frontendTestLayoutFromSpec(meta.spec);
+                        const caseId = resolveCaseIdFromWriteSet(input.task.writeSet, layout) ??
                             input.task.id;
-                        const evidenceDir = resolveEvidenceDirFromWriteSet(input.task.writeSet) ??
-                            `testcase/frontend/evidence/${caseId}`;
+                        const evidenceDir = resolveEvidenceDirFromWriteSet(input.task.writeSet, layout) ??
+                            `${layout.evidenceDir}/${caseId}`;
                         playwrightToolContext = {
                             repoRoot: input.cwd,
                             runDir: meta.runDir,
@@ -1960,7 +2020,8 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                             caseId,
                             evidenceDir,
                             baseUrl: await resolveValidatedFrontendBaseUrlFromContext(input.cwd, meta.runDir),
-                            inputRoot: "testcase/frontend/fixtures",
+                            inputRoot: layout.fixturesDir,
+                            layout,
                         };
                         // Cleanup must be confirmed before a new case; otherwise default-session
                         // isolation is unknown and no Pi invocation is permitted.
@@ -2272,6 +2333,23 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         catch {
             // best-effort flush; missing ledger still fails at the node validator
         }
+        // Read-burst guard: a plan that burned dozens of read/grep/ls/find
+        // calls (re-reading upstream outputs and source files it should trust
+        // from typed facts) blows up the context window and eventually fails
+        // with 400 request-too-large. Detect it deterministically from the
+        // session log and retry with a reduced-reading instruction.
+        const readBurstIssues = await detectPlanReadBurst({
+            runDir: meta.runDir,
+            nodeId: input.task.id,
+        });
+        if (readBurstIssues.length > 0) {
+            return {
+                ...mapped,
+                ok: false,
+                failureCategory: "read-burst",
+                stderr: [mapped.stderr, ...readBurstIssues].filter(Boolean).join("\n\n"),
+            };
+        }
     }
     if (!isWriteTask) {
         return mapped;
@@ -2612,6 +2690,12 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         changeManifestChangedFiles !== undefined &&
         changeManifestChangedFiles.length === 0 &&
         writeToolCallCount === 0;
+    // Budget-exhausted: the provider session consumed an extreme amount of
+    // tokens (e.g. an unresolved read-edit-test loop) and still failed. Only
+    // applies on a non-ok writer result; a successful write is never re-labeled.
+    const writerBudgetExhausted = !mapped.ok &&
+        typeof mapped.tokensUsed === "number" &&
+        mapped.tokensUsed > WRITER_TOKEN_BUDGET;
     const targetCleanTransport = !mapped.ok &&
         isTargetTemplateTransientRetryNode(input.task) &&
         rawFailureCategory !== undefined &&
@@ -2655,17 +2739,35 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                         mapped.failureCategory === "invalid-output" ||
                         mapped.failureCategory === WRITER_EMPTY_DIFF_RETRY_CATEGORY)
                     ? INCOMPLETE_WRITE_SET_RETRY_CATEGORY
-                    : // writer-thinking-exhausted: a length-stopped thinking-only attempt with
-                        // zero write tool calls and zero attributed diff is terminal and
-                        // non-retryable; recommend a model switch + fresh run. Only applies on
-                        // the empty-output base category so provider/transport failures keep
-                        // their original category, and only when the completeness gate did not
-                        // upgrade to incomplete-write-set above.
-                        writerThinkingExhausted
-                            ? WRITER_THINKING_EXHAUSTED_CATEGORY
-                            : writerCleanTimeout
-                                ? WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY
-                                : mapped.failureCategory,
+                    : // partial-success-with-context-overflow: the writer hit a context
+                        // overflow on its final provider call but had already persisted
+                        // real file changes (change-manifest non-empty). Classify it
+                        // distinctly so the report shows "code largely done, verification
+                        // incomplete" instead of a misleading empty-output / spec issue,
+                        // and recovery can rerun from verify/implement with a compacted
+                        // session rather than asking the operator for spec clarification.
+                        rawFailureCategory === "context-overflow" &&
+                            (changeManifestChangedFiles?.length ?? 0) > 0
+                            ? "partial-success-with-context-overflow"
+                            : // writer-thinking-exhausted: a length-stopped thinking-only attempt with
+                                // zero write tool calls and zero attributed diff is terminal and
+                                // non-retryable; recommend a model switch + fresh run. Only applies on
+                                // the empty-output base category so provider/transport failures keep
+                                // their original category, and only when the completeness gate did not
+                                // upgrade to incomplete-write-set above.
+                                writerThinkingExhausted
+                                    ? WRITER_THINKING_EXHAUSTED_CATEGORY
+                                    : writerCleanTimeout
+                                        ? WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY
+                                        : // writer-budget-exhausted: the provider session consumed an
+                                            // excessive amount of tokens (a read-edit-test loop that never
+                                            // converged) and still failed. Classify distinctly so the
+                                            // report says the run burned its budget instead of a generic
+                                            // empty-output, and recovery recommends a fresh compacted
+                                            // run rather than spec-clarification.
+                                            writerBudgetExhausted
+                                                ? WRITER_BUDGET_EXHAUSTED_CATEGORY
+                                                : mapped.failureCategory,
         durationMs: mapped.durationMs || Date.now() - started,
     };
 }

package/dist/executors/pi-executor.js

@@ -1012,6 +1012,13 @@ export function classifyPiFailure(input) {
     if (input.exitCode === 0 && input.assistantText.trim())
         return "success";
     const combined = `${input.stderr}\n${input.stdout}`.toLowerCase();
+    // Context overflow (400 request-too-large / context window exceeded).
+    // Must be detected BEFORE the generic rate-limit/quota phrases: an overflow
+    // error often contains "too many tokens" / "maximum context" which would
+    // otherwise be misread as rate-limit or quota. Kept in sync with
+    // CONTEXT_OVERFLOW_PHRASES in commands/client-recovery.ts.
+    if (/请求上下文过大|context_length_exceeded|context overflow|context length overflow|too many tokens|maximum context|prompt is too long|request_too_large|context window/.test(combined))
+        return "context-overflow";
     // Prefer explicit rate-limit / HTTP 429 before generic "limit" quota phrases.
     // Chinese gateways often say "请求频率已达到限制" without English "rate limit".
     if (/rate.?limit|too many requests|\b429\b|请求频率|频率.*限制|rpm|tpm/.test(combined))

package/dist/executors/pi-playwright-cli-tool.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { processTreeSpawnOptions, terminateProcessTree, } from "./process-tree.js";
 import { resolvePlaywrightCliLauncher } from "./playwright-cli-launcher.js";
 import { PLAYWRIGHT_CLI_ALLOWED_COMMANDS, isPlaywrightCliCommand, parsePlaywrightCliFindMatchCount, } from "../shared/playwright-cli-command-policy.js";
+import { defaultFrontendTestLayout, escapeRegexLiteral, } from "../workflows/dag/frontend-test-layout.js";
 export { PLAYWRIGHT_CLI_ALLOWED_COMMANDS, isPlaywrightCliCommand, };
 /** Logical capability name only; execution always uses the verified JS launcher. */
 export const PLAYWRIGHT_CLI_EXECUTABLE = "playwright-cli";
@@ -267,7 +268,8 @@ function validateOpenArgs(args, baseUrl) {
 }
 function resolveEvidenceRelative(rawPath, ctx) {
     const evidenceDir = normalizePosix(ctx.evidenceDir).replace(/\/$/, "");
-    const evidencePrefix = `testcase/frontend/evidence/${ctx.caseId}`;
+    const layout = ctx.layout ?? defaultFrontendTestLayout();
+    const evidencePrefix = `${layout.evidenceDir}/${ctx.caseId}`;
     if (!(evidenceDir === evidencePrefix ||
         evidenceDir.startsWith(`${evidencePrefix}/`))) {
         throw new PlaywrightCliPolicyError("evidence-dir-invalid", `evidenceDir must be under ${evidencePrefix}`);
@@ -291,7 +293,7 @@ function resolveEvidenceRelative(rawPath, ctx) {
     if (candidate.startsWith(`${evidenceDir}/`) || candidate === evidenceDir) {
         return candidate;
     }
-    if (candidate.startsWith("testcase/frontend/evidence/") &&
+    if (candidate.startsWith(`${layout.evidenceDir}/`) &&
         !candidate.startsWith(`${evidencePrefix}/`)) {
         throw new PlaywrightCliPolicyError("path-cross-case", "output path escapes current case evidenceDir");
     }
@@ -472,11 +474,12 @@ function assertInputPathAllowed(rawPath, ctx) {
     if (!isSafeRelativePosix(candidate)) {
         throw new PlaywrightCliPolicyError("input-path-unsafe", `unsafe input path: ${rawPath}`);
     }
+    const layout = ctx.layout ?? defaultFrontendTestLayout();
     const allowedPrefixes = [
-        `testcase/frontend/evidence/${ctx.caseId}/`,
-        "testcase/frontend/cases/",
-        "testcase/frontend/rag/",
-        "testcase/frontend/fixtures/",
+        `${layout.evidenceDir}/${ctx.caseId}/`,
+        `${layout.casesDir}/`,
+        `${layout.ragDir}/`,
+        `${layout.fixturesDir}/`,
     ];
     if (!allowedPrefixes.some((prefix) => candidate === prefix.slice(0, -1) || candidate.startsWith(prefix)) &&
         !candidate.startsWith(normalizePosix(ctx.evidenceDir) + "/")) {
@@ -629,8 +632,8 @@ async function validatePlaywrightCliOutputPath(command, args, ctx) {
     if (!outputFilename)
         return;
     const repoRoot = path.resolve(ctx.repoRoot);
-    const caseEvidenceRoot = path.resolve(repoRoot, "testcase", "frontend", "evidence", ctx.caseId);
-    const evidenceDir = path.resolve(repoRoot, ctx.evidenceDir);
+    const caseEvidenceRoot = path.resolve(repoRoot, ctx.evidenceDir);
+    const evidenceDir = caseEvidenceRoot;
     const target = path.resolve(repoRoot, outputFilename);
     if (!pathIsContained(repoRoot, caseEvidenceRoot) ||
         !pathIsContained(caseEvidenceRoot, evidenceDir) ||
@@ -1024,22 +1027,26 @@ export async function createPlaywrightCliTool(ctx) {
 export const PI_COMMAND_CAPABILITY_REGISTRY = {
     "playwright-cli": createPlaywrightCliTool,
 };
-export function resolveCaseIdFromWriteSet(writeSet) {
+export function resolveCaseIdFromWriteSet(writeSet, layout = defaultFrontendTestLayout()) {
+    const prefix = layout.evidenceDir.replace(/\/$/, "");
+    const escaped = escapeRegexLiteral(prefix);
+    const exact = new RegExp(`^${escaped}/([^/]+)(?:/\\*\\*)?$`);
+    const nested = new RegExp(`^${escaped}/([^/]+)/`);
     for (const entry of writeSet ?? []) {
         const normalized = normalizePosix(entry);
-        const match = normalized.match(/^testcase\/frontend\/evidence\/([^/]+)(?:\/\*\*)?$/);
+        const match = normalized.match(exact);
         if (match?.[1] && match[1] !== "**" && match[1] !== "*") {
             return match[1];
         }
-        const nested = normalized.match(/^testcase\/frontend\/evidence\/([^/]+)\//);
-        if (nested?.[1])
-            return nested[1];
+        const nestedMatch = normalized.match(nested);
+        if (nestedMatch?.[1])
+            return nestedMatch[1];
     }
     return undefined;
 }
-export function resolveEvidenceDirFromWriteSet(writeSet) {
-    const caseId = resolveCaseIdFromWriteSet(writeSet);
+export function resolveEvidenceDirFromWriteSet(writeSet, layout = defaultFrontendTestLayout()) {
+    const caseId = resolveCaseIdFromWriteSet(writeSet, layout);
     if (!caseId)
         return undefined;
-    return `testcase/frontend/evidence/${caseId}`;
+    return `${layout.evidenceDir}/${caseId}`;
 }