@tea-agent/loop-agent 0.39.0-beta.4 → 0.39.0-beta.6

package/CHANGELOG.md

@@ -6,6 +6,10 @@
 
 ### 重点更新
 
+- 修复 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.json）」区块：以弹框形式增/改/删 Pi 的模型条目，支持 6 个定义字段（id、name、contextWindow、maxTokens、input、reasoning）。新增时 Provider 用下拉选择、其余字段自动补默认值；编辑时 Provider 只读且仅在原位置就地替换，只改表单内字段、不覆盖配置里页面未展示的其它字段（如 cost/compat）；不读写 API key（凭据走 Pi CLI）。编辑已存在的模型不再被移到最后。
 - 前端风险分级细分 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 无法走完绿灯链。
@@ -31,6 +35,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.4",
-  "gitSha": "c2dcaef179cd0526f8f5779e866d0e1103451baa",
-  "builtAt": "2026-08-23T07:52:07.528Z"
+  "version": "0.39.0-beta.6",
+  "gitSha": "740f411873839c25833d8d41d0ee74d0285f7082",
+  "builtAt": "2026-08-23T14:01:39.565Z"
 }

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
@@ -216,6 +217,9 @@ export const FRONTEND_PLAN_RECORD_TOOL_NAMES = [
     "record_mock_api",
     "record_design_deviation",
     "record_dependency",
+    "record_plan_requirement",
+    "record_plan_verification_target",
+    "record_plan_evidence_gap",
 ];
 export const FRONTEND_PLAN_TERMINAL_TOOL_NAMES = ["finalize_plan"];
 export const FRONTEND_PLAN_ADOPT_TOOL_NAMES = ["adopt_staged_fact"];
@@ -321,6 +325,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",
@@ -651,7 +698,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({
@@ -703,7 +752,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,
@@ -792,9 +841,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);
@@ -805,24 +854,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 }
                     : {}),
@@ -923,16 +976,83 @@ export async function createFrontendPlanLedgerTools(input) {
             return planToolReceipt(result);
         },
     });
+    // Incremental plan payload records (one entry per call) so requirements,
+    // verification targets, evidence gaps, and implementation steps never have
+    // to be emitted as one large array inside a single finalize_plan call —
+    // they aggregate from the ledger in commit order. Mirrors the contract
+    // node's record_requirement pattern to stay within any model output budget.
+    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; 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 }),
+        async execute(_toolCallId, params) {
+            const rawEntry = params?.entry;
+            if (!isRecordObject(rawEntry)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-requirement",
+                    error: "record_plan_requirement requires a non-empty entry object",
+                });
+            }
+            const entry = rawEntry;
+            const result = await adoptPlanFact("plan-requirement", `${attemptId}:record_plan_requirement:${randomUUID()}`, { kind: "plan-requirement", origin: "plan", entry });
+            return planToolReceipt(result);
+        },
+    });
+    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, 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 }),
+        async execute(_toolCallId, params) {
+            const rawEntry = params?.entry;
+            if (!isRecordObject(rawEntry)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: "record_plan_verification_target requires a non-empty entry object",
+                });
+            }
+            const entry = rawEntry;
+            const result = await adoptPlanFact("plan-verification-target", `${attemptId}:record_plan_verification_target:${randomUUID()}`, { kind: "plan-verification-target", origin: "plan", entry });
+            return planToolReceipt(result);
+        },
+    });
+    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. 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 }),
+        async execute(_toolCallId, params) {
+            const rawEntry = params?.entry;
+            if (!isRecordObject(rawEntry)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-evidence-gap",
+                    error: "record_plan_evidence_gap requires a non-empty entry object",
+                });
+            }
+            const entry = rawEntry;
+            const result = await adoptPlanFact("plan-evidence-gap", `${attemptId}:record_plan_evidence_gap:${randomUUID()}`, { kind: "plan-evidence-gap", origin: "plan", entry });
+            return planToolReceipt(result);
+        },
+    });
     const finalizePlanTool = defineTool({
         name: "finalize_plan",
         label: "finalize_plan",
-        description: "Assemble the canonical editable plan patch from committed record facts plus these remaining fields, publish it on a target-surface fact, and commit the finalize_plan terminal. Call exactly once.",
-        promptSnippet: "Assemble and commit the finalize_plan terminal (requirements + verificationTargets + evidenceGaps + optional fields).",
+        description: "Commit the finalize_plan terminal. Requirements, verification targets, and evidence gaps (optional) were already committed incrementally through record_plan_requirement / record_plan_verification_target / record_plan_evidence_gap; finalize_plan assembles them from the ledger together with these optional remaining fields, publishes the canonical editable patch on a target-surface fact, and commits the terminal. Call exactly once.",
+        promptSnippet: "Commit the finalize_plan terminal (ledger fields + optional residualRisks / realIntegrationGap).",
         parameters: Type.Object({
-            requirements: Type.Array(requirementSchema),
-            verificationTargets: Type.Array(verificationTargetSchema),
-            evidenceGaps: Type.Array(evidenceGapSchema),
-            implementationSteps: optionalStringArray,
             residualRisks: optionalStringArray,
             realIntegrationGap: optionalString,
         }, { additionalProperties: false }),
@@ -942,12 +1062,6 @@ export async function createFrontendPlanLedgerTools(input) {
                 const fragment = assemblePlanPatchFromCommittedFacts(committed) ?? {};
                 const patch = {
                     ...fragment,
-                    requirements: params?.requirements ?? [],
-                    verificationTargets: params?.verificationTargets ?? [],
-                    evidenceGaps: params?.evidenceGaps ?? [],
-                    ...(params?.implementationSteps
-                        ? { implementationSteps: params.implementationSteps }
-                        : {}),
                     ...(params?.residualRisks
                         ? { residualRisks: params.residualRisks }
                         : {}),
@@ -1024,6 +1138,9 @@ export async function createFrontendPlanLedgerTools(input) {
             recordMockApiTool,
             recordDesignDeviationTool,
             recordDependencyTool,
+            recordPlanRequirementTool,
+            recordPlanVerificationTargetTool,
+            recordPlanEvidenceGapTool,
             adoptStagedFactTool,
             finalizePlanTool,
         ],
@@ -1882,10 +1999,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,
@@ -1893,7 +2011,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.
@@ -2205,6 +2324,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;

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}`;
 }

package/dist/executors/shell-executor.js

@@ -39,6 +39,7 @@ import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } f
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
+import { frontendTestLayoutFromSpec, } from "../workflows/dag/frontend-test-layout.js";
 import { backendTestGapDocSchema, ingestBackendTestGap, } from "../workflows/dag/backend-test-gap-fill.js";
 import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
 import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport, } from "../workflows/dag/backend-test-result-contract.js";
@@ -2800,10 +2801,12 @@ async function executeFrontendCloseout(input, meta) {
 async function executeFrontendTestCaseChecklist(input, meta) {
     const started = Date.now();
     try {
+        const layout = frontendTestLayoutFromSpec(meta.spec);
         const declaredAcIds = (meta.spec.sourceBinding?.requirementIds ?? []).filter((id) => /^AC(?:-[A-Z0-9]+)+$/i.test(id));
         const result = await validateFrontendCaseChecklist({
             workspaceRoot: input.cwd,
             declaredAcIds,
+            layout,
         });
         if (result.issues.length) {
             return {
@@ -2838,6 +2841,7 @@ async function executeFrontendTestL5Report(input, meta) {
         const output = await renderFrontendTestL5Report({
             workspaceRoot: input.cwd,
             runDir: meta.runDir,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         return {
             ok: true,
@@ -2863,6 +2867,7 @@ async function executeFrontendTestHtmlReport(input, meta) {
         const output = await renderFrontendTestHtmlReport({
             workspaceRoot: input.cwd,
             runDir: meta.runDir,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         return {
             ok: true,
@@ -2882,11 +2887,12 @@ async function executeFrontendTestHtmlReport(input, meta) {
         };
     }
 }
-async function executeFrontendTestStandardScenarios(input) {
+async function executeFrontendTestStandardScenarios(input, meta) {
     const started = Date.now();
     try {
         const result = await copyFrontendTestStandardScenarios({
             workspaceRoot: input.cwd,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         return {
             ok: true,
@@ -2906,10 +2912,11 @@ async function executeFrontendTestStandardScenarios(input) {
         };
     }
 }
-async function executeFrontendTestEnvironmentProbe(input) {
+async function executeFrontendTestEnvironmentProbe(input, meta) {
     const started = Date.now();
     const result = await probeFrontendTestEnvironment({
         workspaceRoot: input.cwd,
+        layout: frontendTestLayoutFromSpec(meta.spec),
     });
     if (result.ok) {
         return {
@@ -2928,11 +2935,12 @@ async function executeFrontendTestEnvironmentProbe(input) {
         durationMs: Date.now() - started,
     };
 }
-async function executeFrontendTestEvidenceValidation(input) {
+async function executeFrontendTestEvidenceValidation(input, meta) {
     const started = Date.now();
     try {
         const result = await validateFrontendCaseEvidence({
             workspaceRoot: input.cwd,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         const output = `frontend case evidence validation cases=${result.cases} findings=${result.issues.length}${result.issues.length ? ` issues=${JSON.stringify(result.issues)}` : ""}`;
         if (result.hardFail) {
@@ -2971,6 +2979,7 @@ async function executeFrontendTestCaseManifest(input, meta) {
         const checklist = await validateFrontendCaseChecklist({
             workspaceRoot: input.cwd,
             declaredAcIds,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         if (checklist.issues.length) {
             return {
@@ -2985,6 +2994,7 @@ async function executeFrontendTestCaseManifest(input, meta) {
             workspaceRoot: input.cwd,
             maxCases: gate.maxCases,
             declaredAcIds,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         return {
             ok: true,
@@ -3023,6 +3033,7 @@ async function executeFrontendTestResultFinalize(input, meta) {
     try {
         const evidence = await validateFrontendCaseEvidence({
             workspaceRoot: input.cwd,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         advisoryStdout = `frontend case evidence validation cases=${evidence.cases} findings=${evidence.issues.length}${evidence.issues.length ? ` issues=${JSON.stringify(evidence.issues)}` : ""}`;
         // Advisory findings must not block materialize; only hardFail (path escape) does.
@@ -3041,6 +3052,7 @@ async function executeFrontendTestResultFinalize(input, meta) {
             artifactName: "frontend-test-result.json",
             outputDir: "contracts",
             sourceBinding: meta.spec.sourceBinding,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         return {
             ok: true,
@@ -3079,12 +3091,14 @@ async function executeFrontendTestReports(input, meta) {
             const l5 = await renderFrontendTestL5Report({
                 workspaceRoot: input.cwd,
                 runDir: meta.runDir,
+                layout: frontendTestLayoutFromSpec(meta.spec),
             });
             lines.push(`Frontend L-5 report: ${l5.htmlPath}\nMarkdown: ${l5.markdownPath}\nStatus: ${l5.metrics.status}`);
         }
         const report = await renderFrontendTestHtmlReport({
             workspaceRoot: input.cwd,
             runDir: meta.runDir,
+            layout: frontendTestLayoutFromSpec(meta.spec),
         });
         lines.push(`Frontend test report: ${report.htmlPath}\nMarkdown: ${report.markdownPath}\nOutcome: ${report.outcome}\nCases: ${report.caseCount}`);
         return {
@@ -3214,10 +3228,10 @@ async function executeDagShellNodeInner(input, meta) {
         }
     }
     if (shell?.frontendTestStandardScenarios) {
-        return executeFrontendTestStandardScenarios(input);
+        return executeFrontendTestStandardScenarios(input, meta);
     }
     if (shell?.frontendTestEnvironmentProbe) {
-        return executeFrontendTestEnvironmentProbe(input);
+        return executeFrontendTestEnvironmentProbe(input, meta);
     }
     if (shell?.frontendBrowserToolPreflight) {
         const started = Date.now();
@@ -3273,14 +3287,16 @@ async function executeDagShellNodeInner(input, meta) {
                 label: "Pi SDK custom-tool 能力",
                 ok: true,
             });
+            const layout = frontendTestLayoutFromSpec(meta.spec);
             const toolProbe = await createPlaywrightCliTool({
                 repoRoot: input.cwd,
                 runDir: meta.runDir,
                 nodeId: input.task.id,
                 caseId: "frontend-browser-preflight",
-                evidenceDir: "testcase/frontend/evidence/frontend-browser-preflight",
+                evidenceDir: `${layout.evidenceDir}/frontend-browser-preflight`,
                 baseUrl: "http://localhost:5173/",
-                inputRoot: "testcase/frontend/fixtures",
+                inputRoot: layout.fixturesDir,
+                layout,
             });
             if (toolProbe.name !== "playwright_cli") {
                 steps.push({
@@ -3431,7 +3447,7 @@ async function executeDagShellNodeInner(input, meta) {
         return executeFrontendTestCaseManifest(input, meta);
     }
     if (shell?.frontendTestEvidenceValidation) {
-        return executeFrontendTestEvidenceValidation(input);
+        return executeFrontendTestEvidenceValidation(input, meta);
     }
     if (shell?.frontendTestResultFinalize) {
         return executeFrontendTestResultFinalize(input, meta);
@@ -3538,6 +3554,7 @@ async function executeDagShellNodeInner(input, meta) {
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                         sourceBinding: meta.spec.sourceBinding,
+                        layout: frontendTestLayoutFromSpec(meta.spec),
                     });
                     break;
                 default: