@tea-agent/loop-agent 0.39.0-beta.10 → 0.39.0-beta.11

package/CHANGELOG.md

@@ -29,6 +29,8 @@
 
 ### 重点更新
 
+- backend-test 的 pytest repair 现在继续使用 run-owned plan，不再搜索测试目录 README；correspondence finding 会直接指向 docstring、参数 ID、符号、脚本或 payload 的修复位置，collection/scenario repair 与 generated-local Python 写边界保持一致，并在单次 Pi 会话达到 24 轮或 80K 最大 usage snapshot 前受控返回 partial failure。
+
 - Operator Chat 多次输入排队对齐 DSH Web：运行中的连续输入改为持久化 FIFO 队列，不再用后一条覆盖前一条；单条直接展示，多条默认折叠为数量栏，展开后逐行提供内联编辑、删除和插话发送。队列 Dock 使用与 DSH 一致的外层定位与内层面板结构，标题固定、仅消息列表滚动，并在编辑或请求期间锁定折叠操作。编辑/删除以消息 ID + revision 做并发保护，插话复用 Pi `steer` 注入当前回合，其余消息继续按顺序在回合结束后自动发送；队列通过会话快照与 SSE 权威数组恢复，刷新或 Console 重启不丢失。
 - Operator Chat 右侧辅助栏统一上下文与调用记录：输入框的上下文环、调用记录入口现在复用文件/DAG 侧栏；「文件」常驻，「上下文 / 调用记录」按入口临时添加并支持独立 `×` 关闭，关闭后回到文件 Tab；点击已选入口可收起侧栏，切换到上下文时同步开启注入状态，收起时仅关闭注入而保留上下文数据。上下文与工具调用内容改为内嵌布局，不再叠加独立弹窗、遮罩、焦点陷阱或重复关闭按钮，并补充 Tab 切换与侧栏开合动画；修复折叠态右侧展开按钮无法恢复侧栏的问题。
 - Operator Chat 手动 compact 消息流对齐 DSH Web：压缩中在时间线显示状态行，完成后显示默认折叠的 `compact` 摘要边界，点击可展开完整 Markdown 压缩结果；compact 事件通过 SSE 与 session 详情快照双路径恢复，使用事件 ID 去重，刷新/重新进入会话不丢失。Pi compaction 会把摘要写入 session context，后续模型请求继续使用压缩后的上下文。
@@ -109,6 +111,10 @@
 - `src/shared/openspec-spec.ts` 新增 `extractTaskSourceOpenspecPaths` 纯函数（反引号内联、markdown 链接目标、裸路径 token → 归一化 → spec 过滤 → 治理子树排除 → 去重排序）
 - 生成期把 `openspecPolicy` 与候选来源元数据（`openspecCandidateSources.declared` / `taskSourceCited` / `scanStrict`）冻结进 prewrite gate 配置；`task advance` 的 advisories 说明当前模式与候选来源
 
+- 右侧辅助栏统一承载文件、上下文、调用记录、运行活动和当前 DAG；点击消息流中的运行状态即可在同一侧栏查看运行、门禁与产物，并可自由调整侧栏宽度。
+- 新增任务清单与结构化提问卡片，让长任务的进度和需要用户选择的内容更容易理解。
+- 「对话 / 操作 / 观测」使用统一导航；操作和观测页面可以切换工作区查看对应数据。
+
 ### 改进
 
 - Windows 上读取运行中的 DAG `state.json` / `run.json` / `interrupt.json` 时，对原子替换窗口内的短暂文件占用与半成品 JSON 做有界重试；Console 协作中止不再因杀毒软件或文件系统竞争偶发误报输入非法。I/O preflight 测试同步采用与该资源分组一致的 60 秒上限，避免进程启动压力造成假失败。
@@ -158,6 +164,14 @@
 - Operator Chat 的命令说明和参数提示与实际能力保持一致，减少选错恢复入口或误用占位参数。
 - 测试套件按 CPU、内存、平台和当前 DAG 压力动态分配资源，并减少重复启动进程，完整验证耗时更稳定。
 
+- 后端测试的计划与生成阶段只读取任务明确绑定的需求、环境报告和本轮产物，减少无关仓库内容干扰结果，并让后续步骤继续使用同一份已确认计划。
+- Operator Chat 的任务清单工具描述补齐多步骤与 DAG 使用纪律：开始前按具体步骤规划、保持进行中约束、完成后立即更新完整列表，并用面向用户的阶段呈现 DAG 进度，简单任务自动跳过。
+- 正式发布会自动同步更新版本日志和文档站摘要；发布说明优先生成简洁自然的中文，生成服务不可用时也能安全完成发布。
+- 输入框整合模型与推理等级选择，并只展示有真实数据的轮次、耗时、速度和缓存统计。
+- 工作区、会话列表、文件标签和侧栏交互更加紧凑自然，折叠、切换和页面过渡更加流畅。
+- 设置页改用自然中文展示当前工作区的模型状态，减少内部状态和重复信息。
+- DAG 检查器简化节点说明、执行记录和提示词重启面板，长内容更容易阅读和定位。
+
 ### 修复
 
 - backend-test 用例覆盖分析的 payload 形状提取在无 `python` 可执行文件的环境（现代 macOS 只有 `python3`）静默降级为空结果，导致 payload 观测路径全空、`PAYLOAD_SHAPE_MISMATCH` 误报；解释器解析改为 POSIX 优先 `python3`、Windows 优先 `python`（与 scenario-param 语法校验一致），仅在解释器缺失时尝试下一候选，分析输入自身的失败不再重试。
@@ -172,11 +186,96 @@
 - Windows 上执行后端测试场景参数的 Python 语法检查时，会跳过不可用的 Microsoft Store 占位程序，避免错误回滚合法改动。
 - 旧版前端 DAG 也能识别增量计划修订，不再因契约格式差异反复重试；无法合并的修订会提示重新生成 DAG。
 
+- 修复重命名会话时输入框没有回显当前标题的问题。
+- 修复停止回复后输入区恢复迟缓、排队消息偶发丢失，以及切换会话后旧状态残留的问题。
+- 修复宽表格、文件预览、滚动条和窄屏布局中的多处显示异常。
+- 修复部分 Windows 环境读取运行状态时的偶发失败，并提高前后端任务验证的可靠性。
+
 ### 文档
 
 - 整理 `0.36.0` 以来的更新日志，改为面向用户描述结果，并补齐 `0.38.0`、`0.38.1` 的正式发布记录。
 - 新增检查以阻止纯英文条目、重复版本、版本倒序和非标准 `Unreleased` 标题。
 
+## [0.39.1] - 2026-08-25
+
+### 重点更新
+
+- 前端实现流程会逐项核对原始需求与验收标准，减少长需求被遗漏、误解或静默排除的情况。
+- Console 新增可选择稳定版或预发布版的更新入口，更新前会检查正在运行的任务，完成后自动恢复当前页面。
+
+### 新增
+
+- DAG 检查器可以查看失败节点的提示词版本，并在确认后从选定内容重新执行。
+- 后端测试会核对本轮文件清单与实际引用关系，避免历史文件或错误依赖混入测试结果。
+
+### 改进
+
+- 设置页移除重复的模型配置入口，模型管理继续集中在对话页。
+- 关键治理文档完成复核，当前能力、限制和操作方式保持一致。
+
+## [0.39.0] - 2026-08-23
+
+### 重点更新
+
+- Operator Chat 支持通过方向键找回历史输入，并可在当前回复进行时预先排队下一条消息。
+- 任务向导新增实时进度、当前节点、运行时长和失败摘要，长时间任务更容易判断是否正常推进。
+
+### 新增
+
+- 前端测试支持自定义测试目录和文件布局，适配不同项目结构。
+
+### 改进
+
+- 运行结束后会自动降低刷新频率，并为失败状态提供更直接的处理建议。
+- npm 预发布包会记录准确版本，安装后显示的版本与实际发布制品保持一致。
+
+## [0.38.4] - 2026-08-23
+
+### 重点更新
+
+- 初始化与升级流程更好地支持企业 npm 镜像、已有模型配置和一次性安全更新。
+- Console 与 DAG 检查器补充了运行状态、失败节点和提示词重启等诊断能力。
+
+### 新增
+
+- 新增 `inspect next`，可以查看当前 npm 预发布版本对应的源码和本地尚未发布的变化。
+- 前端测试可以从项目治理目录和初始化模板读取标准场景，并提供更完整的执行报告。
+
+### 修复
+
+- 修复 npm 包缺少运行文件、macOS Python 命令差异、Windows 场景检查和部分滚动显示问题。
+- 修复前端计划引用、失败恢复和测试回执在复杂项目中的多处误判。
+
+## [0.38.3] - 2026-08-22
+
+### 重点更新
+
+- Operator Chat 的文件预览可以在新窗口打开，并能在排版预览与原始内容之间切换。
+- 长时间模型任务遇到输出截断或暂时停滞时，恢复过程更加可靠。
+
+### 新增
+
+- 安装 loop-agent 时会默认包含 Pi 运行能力，减少额外配置步骤。
+- DAG 检查器可以查看不同执行器的运行过程和更清晰的节点输出。
+
+### 改进
+
+- 后端测试增强了自定义目录、场景分区和生成文件的校验。
+- 文件浏览、结束原因和前端计划恢复信息更容易查看和诊断。
+
+## [0.38.2] - 2026-08-20
+
+### 重点更新
+
+- 后端测试支持自定义输出目录、公共前置说明、查询场景分区和增量补缺模式。
+- Operator Chat 的停止与后续发送更加可靠，停止过程中提交的下一条消息不会因刷新或重启丢失。
+
+### 改进
+
+- DAG 重新执行时会继承上一轮尚未解决的验证和评审反馈，减少重复失败。
+- 恢复入口会根据失败原因选择从节点继续或完整重跑，并给出更明确的操作建议。
+- npm 预发布改为按提交数量节流，减少没有必要的重复发布。
+
 ## [0.38.1] - 2026-08-18
 
 ### 重点更新

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.39.0-beta.10",
-  "gitSha": "f6ea22730a28e6556983394e41560c0d8d18a852",
-  "builtAt": "2026-08-27T07:03:53.753Z"
+  "version": "0.39.0-beta.11",
+  "gitSha": "5614959a483efbdc1f3a598246fee5cee57595d4",
+  "builtAt": "2026-08-28T03:23:49.173Z"
 }

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

@@ -7,10 +7,11 @@ import { mapContractBlockedOwner } from "../workflows/dag/frontend-human-decisio
 import { routeFrontendProviderCapability } from "../workflows/dag/frontend-provider-capability-matrix.js";
 import { executePiStep, resolvePiBackend, } from "./pi-executor.js";
 import { resolveDagPiExtensions, } from "./pi-extension-resolver.js";
-import { buildPiWriterToolPolicyContext, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
+import { buildPiWriterToolPolicyContext, createPiReaderCustomTools, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
 import { createPiReadBudgetCustomTools, } from "./pi-read-budget-policy.js";
 import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND_CAPABILITY_REGISTRY, resolveCaseIdFromWriteSet, resolveEvidenceDirFromWriteSet, } from "./pi-playwright-cli-tool.js";
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
+import { parseLedgerJson } from "../task/source-prepare/ledger.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
@@ -287,14 +288,17 @@ export function resolveDagPiToolNames(task) {
     }
     if (isFrontendPlanLedgerNode(task)) {
         return [
-            // Plan consumes typed contract/scout facts. It may inspect an explicitly
-            // named file, but repository-wide search belongs to the scout node.
-            "read",
+            // Plan is a decision-only node. Contract/scout own source and repository
+            // discovery; omitting read tools prevents a planner from spending its
+            // output budget reconstructing already-frozen evidence.
             ...FRONTEND_PLAN_RECORD_TOOL_NAMES,
             ...FRONTEND_PLAN_TERMINAL_TOOL_NAMES,
             ...FRONTEND_PLAN_ADOPT_TOOL_NAMES,
         ];
     }
+    if ((task.readSet?.length ?? 0) > 0) {
+        return isDagPiWriteTask(task) ? ["read", "edit", "write"] : ["read"];
+    }
     if (!isDagPiWriteTask(task))
         return [...DAG_PI_READONLY_TOOLS];
     const tools = [...DAG_PI_WRITE_TOOLS];
@@ -823,6 +827,44 @@ async function loadContractRequirementInheritance(runDir) {
     }
     return byId;
 }
+/**
+ * Resolve task-source citations from the source-fidelity ledger before the
+ * planner starts. The planner names a frozen requirement id; it never needs
+ * to re-read a PRD merely to recover a path/section/line triple.
+ */
+async function resolveFrontendPlanNewComponentSourceReferences(input) {
+    const binding = input.sourceBinding;
+    if (!binding || binding.schemaVersion !== 2)
+        return new Map();
+    const ledgerPath = binding.ledgerPath;
+    const absolutePath = path.resolve(input.cwd, ledgerPath);
+    const workspaceRoot = path.resolve(input.cwd);
+    if (absolutePath !== workspaceRoot &&
+        !absolutePath.startsWith(`${workspaceRoot}${path.sep}`)) {
+        return new Map();
+    }
+    try {
+        const ledger = parseLedgerJson(await readFile(absolutePath, "utf8"));
+        const fragmentsById = new Map(ledger.fragments.map((fragment) => [fragment.id, fragment]));
+        const references = new Map();
+        for (const requirement of ledger.canonicalRequirements) {
+            const fragment = requirement.sourceFragmentIds
+                .map((fragmentId) => fragmentsById.get(fragmentId))
+                .find((candidate) => candidate !== undefined);
+            if (!fragment)
+                continue;
+            references.set(requirement.id, {
+                path: fragment.path,
+                section: fragment.headingPath,
+                line: fragment.lineRange.start,
+            });
+        }
+        return references;
+    }
+    catch {
+        return new Map();
+    }
+}
 /**
  * A+B: `frontend-plan-pi` now records its decision ledger through seven
  * incremental `record_*` tools (origin=plan) and closes with exactly one
@@ -1003,10 +1045,11 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordComponentChoiceTool = defineTool({
         name: "record_component_choice",
         label: "record_component_choice",
-        description: "Record ONE component choice (origin=plan component-choice fact). Declare every UI purpose's component selection. A component the task source/PRD mandates adding (not present in the repo) MUST be decision=new with a specReference pointing at the PRD section that defines it; decision=reuse-existing is only for components that already exist in the repo (e.g. reusing ActiveRunBadge's styling convention). 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).",
+        description: "Record ONE component choice (origin=plan component-choice fact). Declare every UI purpose's component selection. For decision=new, pass sourceRequirementIds containing the frozen requirement ID(s) that mandate the component; the runtime derives its exact PRD specReference from the source-fidelity ledger. Do not read the PRD or invent a path/line. decision=reuse-existing is only for components that already exist in the repo (e.g. reusing ActiveRunBadge's styling convention). 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({
             choice: uiComponentChoiceSchema,
+            sourceRequirementIds: Type.Optional(stringArray),
             stylingStrategy: optionalString,
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -1018,7 +1061,28 @@ export async function createFrontendPlanLedgerTools(input) {
                     error: "record_component_choice requires a non-empty choice object",
                 });
             }
-            const choice = rawChoice;
+            const sourceRequirementIds = stringList(params?.sourceRequirementIds);
+            const choice = { ...rawChoice };
+            if (choice.decision === "new") {
+                if (sourceRequirementIds.length === 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: "decision=new requires sourceRequirementIds so runtime can materialize the task-source specReference",
+                    });
+                }
+                const specReference = sourceRequirementIds
+                    .map((id) => input.componentNewSourceReferences?.get(id))
+                    .find((reference) => reference !== undefined);
+                if (!specReference) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: `decision=new sourceRequirementIds have no frozen task-source citation: ${sourceRequirementIds.join(", ")}`,
+                    });
+                }
+                choice.specReference = specReference;
+            }
             const components = typeof choice.component === "string" ? [choice.component] : [];
             const result = await adoptPlanFact("component-choice", `${attemptId}:record_component_choice:${randomUUID()}`, {
                 kind: "component-choice",
@@ -1803,23 +1867,6 @@ export async function createFrontendScoutEvidenceTools(input) {
         },
     };
 }
-async function resolveFrontendPlanReadAccess(input) {
-    const { readCommittedOriginFacts, scoutConfirmedReadPaths } = await import("../workflows/dag/frontend-shadow-dual-write.js");
-    const scoutFacts = await readCommittedOriginFacts(input.runDir, "frontend-scout-pi", "scout-typed-facts.jsonl");
-    const workspaceRoot = path.resolve(input.cwd);
-    const allowedReadPaths = scoutConfirmedReadPaths(scoutFacts)
-        .map((relativePath) => path.resolve(workspaceRoot, relativePath))
-        .filter((absolutePath) => absolutePath === workspaceRoot ||
-        absolutePath.startsWith(`${workspaceRoot}${path.sep}`));
-    return {
-        allowedReadPaths,
-        // Upstream artifacts are runner-owned evidence, not repository discovery.
-        allowedReadRoots: [
-            path.join(input.runDir, "frontend-contract-pi"),
-            path.join(input.runDir, "frontend-scout-pi"),
-        ],
-    };
-}
 export function buildDagPiUserMessage(task, persona, step) {
     const role = task.role ?? "unspecified";
     const writePolicy = task.writePolicy ?? "read-only (default)";
@@ -1872,6 +1919,9 @@ export function buildDagPiUserMessage(task, persona, step) {
         `You are executing hybrid DAG node "${task.id}" (role=${role}, piPersona=${persona}, piStep=${step}, writePolicy=${writePolicy}).`,
         "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
         "Use read-only tools only. Do not edit, write, or commit repository files.",
+        (task.readSet?.length ?? 0) > 0
+            ? `Strict read set: ${task.readSet.join(", ")}. The read tool rejects every other repository path; do not search for substitutes.`
+            : undefined,
         "Return your conclusion as plain Markdown text suitable for downstream DAG nodes.",
         "Do not wrap the output in code fences and do not add conversational preamble.",
     ].join(" ");
@@ -2292,9 +2342,17 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             ok: false, stdout: "", stderr: "pi command capability requires an explicit bounded write tool profile", failureCategory: "tool-policy", durationMs: Date.now() - started,
         };
     }
-    if (isWriteTask || allowsPlaywrightCli) {
+    const strictReadSet = (input.task.readSet?.length ?? 0) > 0;
+    if (isWriteTask || allowsPlaywrightCli || strictReadSet) {
         try {
             const customTools = [];
+            if (strictReadSet) {
+                const readContext = buildPiWriterToolPolicyContext({
+                    repoRoot: input.cwd,
+                    readSet: input.task.readSet,
+                });
+                customTools.push(...(await createPiReaderCustomTools(readContext)));
+            }
             if (isWriteTask) {
                 const policyContext = buildPiWriterToolPolicyContext({
                     repoRoot: input.cwd,
@@ -2302,6 +2360,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     writeSet: input.task.writeSet,
                     forbiddenPaths: input.task.forbiddenPaths,
                     writePolicy: input.task.writePolicy,
+                    readSet: input.task.readSet,
                 });
                 customTools.push(...(await createPiWriterCustomTools(policyContext)));
             }
@@ -2465,6 +2524,10 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 runDir: meta.runDir,
                 nodeId: input.task.id,
                 skeleton: input.task.structuredContractOutput?.skeleton,
+                componentNewSourceReferences: await resolveFrontendPlanNewComponentSourceReferences({
+                    cwd: input.cwd,
+                    sourceBinding: meta.spec.sourceBinding,
+                }),
             });
             writerToolPolicy = {
                 requireSdk: true,
@@ -2486,14 +2549,6 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             readBudgetTools = await createPiReadBudgetCustomTools({
                 repoRoot: input.cwd,
                 budget: input.task.readBudget,
-                ...(isFrontendPlanLedgerNode(input.task)
-                    ? {
-                        readAccess: await resolveFrontendPlanReadAccess({
-                            cwd: input.cwd,
-                            runDir: meta.runDir,
-                        }),
-                    }
-                    : {}),
             });
             writerToolPolicy = {
                 requireSdk: true,
@@ -2577,6 +2632,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             timeoutMs: input.timeoutMs,
             stallTimeoutMs: input.stallTimeoutMs,
             abortGraceMs: input.abortGraceMs,
+            ...(input.task.contextBudget
+                ? { contextBudget: input.task.contextBudget }
+                : {}),
             ...(writerToolPolicy ? { writerToolPolicy } : {}),
             ...(piExtensionPaths && piExtensionPaths.length > 0
                 ? { piExtensionPaths }
@@ -2625,6 +2683,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         persona,
         step,
     });
+    if (input.task.id === "generate-backend-md-plan-pi" && result.assistantText?.trim()) {
+        await writeTextArtifactFile(path.join(meta.runDir, input.task.id, "plan.md"), result.assistantText.trim() + "\n");
+    }
     const mapped = mapPiResultToDagNodeResult(result, isFrontendFactsWriter(input.task)
         ? undefined
         : input.task.writerOutcomePolicy

package/dist/executors/pi-executor.js

@@ -1005,12 +1005,14 @@ export function shouldRetryWithFallback(stderr, stdout) {
     return ["quota", "rate-limit", "unavailable", "network"].includes(category);
 }
 export function classifyPiFailure(input) {
+    if (input.exitCode === 0 && input.assistantText.trim())
+        return "success";
+    if (input.stderr.toLowerCase().includes("context-budget-exhausted:"))
+        return "context-budget-exhausted";
     if (input.timedOut)
         return "timeout";
     if (input.outputTooLarge)
         return "output-too-large";
-    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

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

@@ -485,6 +485,9 @@ function extractSdkUsageSample(event) {
     const responseKey = responseKeyCandidates.find((value) => typeof value === "string" && value.length > 0);
     return responseKey ? { responseKey, tokens } : { tokens };
 }
+function maxSdkContextTokens(samples) {
+    return samples.reduce((maximum, sample) => Math.max(maximum, sample.tokens), 0);
+}
 function aggregateSdkTokenUsage(samples) {
     const identified = new Map();
     let anonymousMaximum = 0;
@@ -537,6 +540,9 @@ export async function executeSingleSdkAttempt(options) {
     const stdoutPreview = new BoundedTextPreview("stdout");
     const stdoutCollector = createPiJsonlStreamCollector();
     const usageSamples = [];
+    let observedTurns = 0;
+    let contextBudgetExhausted = false;
+    let contextBudgetDetail = "";
     // Writer-thinking-exhausted diagnosis evidence (AC-002). Collected in the
     // subscribe callback regardless of shouldPersistSessionEvent filtering, so a
     // length-stopped thinking-only attempt with no persisted write tool calls is
@@ -625,6 +631,7 @@ export async function executeSingleSdkAttempt(options) {
         });
         let resolveStall;
         let resolveSettlement;
+        let resolveContextBudget;
         let settled = false;
         let abortConfirmed = true;
         const persistRuntimeNote = (event) => {
@@ -655,6 +662,30 @@ export async function executeSingleSdkAttempt(options) {
                 clearTimeout(stallHandle);
             stallHandle = setTimeout(() => resolveStall?.("stall"), stallTimeoutMs);
         };
+        const checkContextBudget = () => {
+            if (contextBudgetExhausted || !options.contextBudget)
+                return;
+            // Context protection follows the largest provider-reported response
+            // snapshot, not cumulative billing usage across turns. Summing repeated
+            // input contexts would abort healthy multi-turn sessions far below the
+            // model's actual context window.
+            const observedTokens = maxSdkContextTokens(usageSamples);
+            const turnExceeded = options.contextBudget.maxTurns !== undefined &&
+                observedTurns >= options.contextBudget.maxTurns;
+            const tokenExceeded = options.contextBudget.maxTokens !== undefined &&
+                observedTokens >= options.contextBudget.maxTokens;
+            if (!turnExceeded && !tokenExceeded)
+                return;
+            contextBudgetExhausted = true;
+            contextBudgetDetail = [
+                "context-budget-exhausted:",
+                `observedTurns=${observedTurns}`,
+                `observedTokens=${observedTokens}`,
+                `maxTurns=${options.contextBudget.maxTurns ?? "unbounded"}`,
+                `maxTokens=${options.contextBudget.maxTokens ?? "unbounded"}`,
+            ].join(" ");
+            resolveContextBudget?.("context-budget");
+        };
         unsubscribe = session.subscribe((event) => {
             if (event.type === "agent_settled" && !settled) {
                 settled = true;
@@ -678,6 +709,9 @@ export async function executeSingleSdkAttempt(options) {
             const usageSample = extractSdkUsageSample(event);
             if (usageSample)
                 usageSamples.push(usageSample);
+            if (event.type === "turn_end")
+                observedTurns += 1;
+            checkContextBudget();
             // Capture writer-thinking-exhausted evidence BEFORE the
             // shouldPersistSessionEvent filter: thinking_delta is intentionally
             // excluded from persisted JSONL, but must still count toward the
@@ -700,6 +734,11 @@ export async function executeSingleSdkAttempt(options) {
         const runTurn = async (userMessage) => {
             const settlementPromise = resetSettlement();
             const stallPromise = resetStallPromise();
+            const contextBudgetPromise = options.contextBudget
+                ? new Promise((resolve) => {
+                    resolveContextBudget = resolve;
+                })
+                : null;
             const promptPromise = session.prompt(userMessage);
             // A settlement event is permitted to win the race while prompt() remains
             // pending. Observe a later rejection so it never becomes unhandled.
@@ -710,6 +749,7 @@ export async function executeSingleSdkAttempt(options) {
                 settlementPromise,
                 ...(timeoutPromise ? [timeoutPromise] : []),
                 ...(stallPromise ? [stallPromise] : []),
+                ...(contextBudgetPromise ? [contextBudgetPromise] : []),
             ]);
         };
         const disposeSession = async () => {
@@ -737,7 +777,12 @@ export async function executeSingleSdkAttempt(options) {
             : options.userMessage;
         let continuesSent = 0;
         let raced = await runTurn(promptMessage);
-        if (raced === "stall") {
+        if (raced === "context-budget") {
+            appendStderr(contextBudgetDetail);
+            abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
+            await disposeSession();
+        }
+        else if (raced === "stall") {
             abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
             const withinAbsoluteTimeout = timeoutMs <= 0 || Date.now() - startedAt < timeoutMs;
             const canContinue = abortConfirmed &&

package/dist/executors/pi-writer-tool-policy.js

@@ -154,6 +154,28 @@ function assertMkdirRelative(relative, ctx) {
         throw new PiWriterPathDeniedError("forbidden", relative || ".");
     }
 }
+export async function assertReadablePath(targetPath, ctx) {
+    const raw = String(targetPath ?? "").trim();
+    if (!raw)
+        throw new PiWriterPathDeniedError("empty-path", targetPath ?? "");
+    const repoRoot = path.resolve(ctx.repoRoot);
+    const absoluteTarget = path.isAbsolute(raw)
+        ? path.resolve(raw)
+        : path.resolve(repoRoot, raw);
+    if (!isPathInside(repoRoot, absoluteTarget)) {
+        throw new PiWriterPathDeniedError("outside-repo", raw);
+    }
+    const effective = await resolveEffectiveMutationTarget(repoRoot, absoluteTarget);
+    const relative = repoRelativePath(repoRoot, absoluteTarget, raw, false);
+    const effectiveRelative = repoRelativePath(effective.realRoot, effective.absoluteTarget, raw, false);
+    const readSet = ctx.readSet ?? [];
+    for (const candidate of [relative, effectiveRelative]) {
+        if (readSet.length === 0 || !matchesAnyPattern(candidate, readSet)) {
+            throw new PiWriterPathDeniedError("read-outside-read-set", candidate, "path is outside the node readSet");
+        }
+    }
+    return relative;
+}
 /**
  * Assert a mutation target is writable under the DAG writer policy.
  * Returns the normalized lexical repo-relative path on success.
@@ -201,11 +223,30 @@ export async function assertMkdirPath(dirPath, ctx) {
     assertMkdirRelative(effectiveRelative, ctx);
     return lexicalRelative;
 }
+export function createPiReaderFsOperations(ctx) {
+    return {
+        readFile: async (absolutePath) => {
+            await assertReadablePath(absolutePath, ctx);
+            return fsReadFile(absolutePath);
+        },
+        access: async (absolutePath) => {
+            await assertReadablePath(absolutePath, ctx);
+            await fsAccess(absolutePath);
+        },
+    };
+}
 /** Build FS operations that enforce writer policy before mutations. */
 export function createPiWriterFsOperations(ctx) {
+    const strictReadSet = (ctx.readSet?.length ?? 0) > 0;
     return {
-        readFile: (absolutePath) => fsReadFile(absolutePath),
+        readFile: async (absolutePath) => {
+            if (strictReadSet)
+                await assertReadablePath(absolutePath, ctx);
+            return fsReadFile(absolutePath);
+        },
         access: async (absolutePath) => {
+            if (strictReadSet)
+                await assertReadablePath(absolutePath, ctx);
             await fsAccess(absolutePath);
         },
         writeFile: async (absolutePath, content) => {
@@ -218,6 +259,20 @@ export function createPiWriterFsOperations(ctx) {
         },
     };
 }
+export async function createPiReaderCustomTools(ctx) {
+    const sdk = (await import("@earendil-works/pi-coding-agent"));
+    const createReadToolDefinition = sdk.createReadToolDefinition;
+    if (typeof createReadToolDefinition !== "function") {
+        throw new Error("pi read tool policy unavailable: createReadToolDefinition missing from SDK");
+    }
+    const read = createReadToolDefinition(path.resolve(ctx.repoRoot), {
+        operations: createPiReaderFsOperations(ctx),
+    });
+    if (read?.name !== "read") {
+        throw new Error("pi read tool policy unavailable: SDK tool must be named read");
+    }
+    return [read];
+}
 /**
  * Create same-name custom edit/write tool definitions that override built-ins
  * via Pi SDK customTools registration. Fails closed when SDK factories are missing.
@@ -262,5 +317,6 @@ export function buildPiWriterToolPolicyContext(input) {
         writeSet: input.writeSet ?? [],
         forbiddenPaths: input.forbiddenPaths ?? [],
         writePolicy: input.writePolicy ?? "exclusive",
+        readSet: input.readSet ?? [],
     };
 }

package/dist/executors/shell-executor.js

@@ -550,13 +550,22 @@ async function executeBackendTestPipeline(input, meta) {
     const started = Date.now();
     // Plan A: prefer the frozen layout carried by the compiled spec; fall back
     // to the historical default for hand-written legacy DAGs.
-    const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
+    const baseBackendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
         ? {
             testRoot: meta.spec.backendTestLayout.testRoot,
             markdownRel: meta.spec.backendTestLayout.markdownRel,
             scriptRel: meta.spec.backendTestLayout.scriptRel,
         }
         : undefined);
+    const markdownPlanArtifact = path.join(meta.runDir, "generate-backend-md-plan-pi", "plan.md");
+    const backendLayout = existsSync(markdownPlanArtifact)
+        ? {
+            ...baseBackendLayout,
+            readmePath: path
+                .relative(input.cwd, markdownPlanArtifact)
+                .replaceAll(path.sep, "/"),
+        }
+        : baseBackendLayout;
     try {
         if (!pipeline)
             throw new Error("missing backend-test pipeline id");

package/dist/worker/console/chat/chat-event-store.js

@@ -231,6 +231,10 @@ export function projectCompactSnapshot(value) {
         Number.isFinite(record.tokensBefore)
         ? Math.max(0, Math.floor(record.tokensBefore))
         : undefined;
+    const estimatedTokensAfter = typeof record.estimatedTokensAfter === "number" &&
+        Number.isFinite(record.estimatedTokensAfter)
+        ? Math.max(0, Math.floor(record.estimatedTokensAfter))
+        : undefined;
     const details = record.details === undefined
         ? undefined
         : boundedRedactedJson(record.details).preview;
@@ -239,9 +243,16 @@ export function projectCompactSnapshot(value) {
         summary,
         ...(firstKeptEntryId ? { firstKeptEntryId } : {}),
         ...(tokensBefore !== undefined ? { tokensBefore } : {}),
+        ...(estimatedTokensAfter !== undefined ? { estimatedTokensAfter } : {}),
         ...(details ? { details } : {}),
         previewHash: createHash("sha256")
-            .update(JSON.stringify({ summary, firstKeptEntryId, tokensBefore, details }))
+            .update(JSON.stringify({
+            summary,
+            firstKeptEntryId,
+            tokensBefore,
+            estimatedTokensAfter,
+            details,
+        }))
             .digest("hex"),
     };
 }
@@ -785,6 +796,7 @@ export function createChatEventStore(options) {
                 "assessment",
                 "taskKind-confirmed",
                 "human-gate-card",
+                "compaction_end",
                 "compact",
                 "artifact-ref",
             ]);