@tea-agent/loop-agent 0.29.2 → 0.30.0

package/CHANGELOG.md

@@ -2,52 +2,84 @@
 
 ## [Unreleased]
 
-## [0.29.2] - 2026-08-07
+## [0.30.0] - 2026-08-08
 
 ### 重点更新
 
-- 优化后端测试生成 writer 的续写重试机制，直接内嵌具体目标路径以恢复输出，不再依赖读取受限路径
-- 修复三处完整性门禁（Completeness Gate）误报，避免将正确的测试生成误判为残缺写集
+- 后端测试生成引入 map-shard 拓扑，将大型单节点拆分为 plan + manifest-shell + map_agent，每个模块用例获得独立的 16K 输出预算，消除大文件多轮写入被截断或完整性误报的风险
+- 修复 map_agent 单个子节点超出 token 限制导致后续所有子节点被错误级联跳过的问题，确保各模块测试用例独立生成互不干扰
+- Completeness Gate 升级为返回结构化缺陷原因，帮助模型精准定位并修复格式问题，有效结束续写死循环
+- 后端测试用例生成全面转向需求驱动覆盖，以产品需求为基准，API 契约作为场景补充，提升测试覆盖的精准度
+
+### 新增
+
+- 新增 plan 节点专属完整性评估器，仅校验 README 覆盖范围和模块索引，不再错误要求下游 map 子节点产出的文件
+- 新增 `scripts/regen-backend-test-dag.mjs` 脚本，用于从 runtime builder 重建打包镜像，保持 runtime 与 packaged template 字节对齐
+- Completeness Gate 的 `moduleStructurallyComplete` 新增结构化原因输出，明确指出空文件、标题层级错误、ID 格式非法或缺失必选章节等具体缺陷
+- 新增 `looksLikeValidPythonModule` 校验逻辑，用于准确识别共享辅助代码和工厂函数，兼容包含合法不平衡分隔符的 fixture 字符串
 
 ### 改进
 
-- 后端测试生成 writer（N2 MD / N5 pytest）在输出截断或残缺写集后，续写重试直接内嵌具体目标路径清单，不再依赖读取 `.harness/**` 路径
-- 即使遇到结果为空或输出失败的异常，也会评估完整性门禁，将可恢复的部分写入升格为不完整写集，避免重试空转
+- N2/N3 提示词改为需求驱动覆盖：Coverage Scope 固定为 new-operation/full-contract，以产品需求为基准全覆盖，API 契约补充场景维度，并禁止使用导致用例降级的 `## 测试类` 分组
+- dagDynamicExpansionChildTaskSchema 扩展 `writerOutcomePolicy` 和 `retryPolicy`，使 map_agent 子节点能正确声明实现产出并受 Completeness Gate 保护
+- Completeness Gate 白名单泛化，通过识别子节点 ID 前缀准确匹配 map 分片子节点
+- DAG 执行器模型矩阵统一路由至当前环境实际可用的 wizard-local 模型，避免因 API Key 缺失导致节点大面积失败
 
 ### 修复
 
-- 修复 README 正文提及的编号式文件名被误判为缺失模块的问题
-- 修复覆盖率矩阵（Coverage Matrix）表头识别被覆盖率范围（Coverage Scope）数据行遮蔽的问题
-- 修复合法多行 `def` 的 pytest 脚本被误判为截断的问题（真正截断现仍由括号配平计数准确捕获）
+- 修复 map_agent 中单个子节点超出 `maxTokensPerCase` 被误当作全局预算耗尽，导致后续兄弟子节点全部被跳过（SKIPPED）的问题
+- 修复 plan 节点 Completeness Gate 错误要求下游 map 子节点产出文件齐全，导致计划节点始终判定为不完整并陷入重试死循环的问题
+- 修复 manifest shell 命令因正则反引号和转义符在多层 shell 解析中被破坏，导致确定性 manifest 节点执行报错的问题，现采用 base64 编码彻底规避 bash 转义干扰
+- 修复 pytest-plan 资源检查因严格括号配平启发式算法，误判包含合法不平衡分隔符的 fixture 字符串为不完整的问题
 
-## [0.29.1] - 2026-08-07
+## [0.29.3] - 2026-08-07
 
 ### 重点更新
 
-- 前端测试默认执行流程大幅精简，收敛至约 11 个静态节点，合并了多项检查与报告步骤
-- 前端测试浏览器默认改为无头（headless）模式，减少环境干扰
-- 优化证据缺失处理逻辑，非路径逃逸的异常不再强制阻断报告生成
-- 修复文档说明被误判为可执行命令的问题，提升执行稳定性
+- 夜间任务控制台升级为引导式工作台，支持点选预约、审阅写入集与任务看板，并保留人工审批门禁
+- 失败 DAG 默认改为从失败节点安全续跑，避免因服务波动无理由新建任务
+- Operator Chat 支持内联展示工具执行过程，并改进 Pi 用量统计的准确解析与状态栏展示
+- 增强 Pi 网关限流容错，遇到 429 状态码时自动按 60 秒间隔退避重试
 
 ### 新增
 
-- 新增前端测试标准场景物化节点，支持执行后针对阻塞或缺失证据进行最多两轮有界重跑
-- 新增前端测试标准场景规范模板（frontend-test-standard-scenarios.v1.json）
-- 前端测试独占节点支持 tools-only 写保护策略，在保留工具级写沙箱的同时跳过 Git 基线的硬失败限制
+- 控制台新增前台辅助夜间任务调度开关，在控制台开启时可按间隔触发调度（仅前台有效，过夜仍需系统定时器）
 
 ### 改进
 
-- 前端测试默认 DAG 结构精简至约 11 个静态节点：合并双重重跑、检查清单与清单文件、证据与结果、L5 与 HTML 报告
-- 前端测试主 HTML 报告不再依赖回顾（retrospect）节点，回顾功能改为可选开启
-- 权威清单文件（manifest.json）仅记录规范化后的测试用例，并在未配置重试时省略相关静态节点
-- 强化运营 HTML 报告的状态过滤功能，并优化失败与阻塞原因的展示
+- 失败 DAG 恢复策略改为先诊断再从失败节点续跑，统一对齐系统提示、恢复入口与工具说明
+- Operator Chat 将工具执行过程内联至消息时间线，支持折叠查看，切会话后可恢复工具记录
+- Operator Chat 用量栏改进 Pi 用量解析，准确展示输入、输出、缓存读取与费用信息
+- 注入上下文面板升级为更大可读面板，展示脱敏后的完整系统提示、技能正文与激活工具列表
 
 ### 修复
 
-- 修复前端测试检查清单将不可用或阻塞状态的说明文字误判为非法可执行命令的问题
-- 修复前端测试收尾阶段因证据缺失或格式错误导致强制失败的问题，现仅对路径逃逸强制报错，其余降级为建议性提示
-- 修复前端测试合并后清单文件物化异常的问题，确保仅写入规范化用例并恢复负向测试用例
-- 回退误改的全局默认 Pi 模型（DEFAULT_PI_MODEL），将其恢复为 glm-5.2，模型路由统一交由 harness 复杂度矩阵处理
+- 修复 Windows 计划任务因 /TR 参数超过 261 字符限制导致创建失败的问题，改用短 .cmd 路径绕过
+- 修复 package-lock 中硬编码的镜像源地址导致发布链路 npm ci 失败的问题，统一指向官方源
+- 修复 playwright-cli open 传入不支持的 --headless/--headed 参数报错的问题
+- 修复 Pi 网关返回 429 限流时重试过快导致任务失败的问题，现自动识别并按 60 秒间隔退避
+- 修复标准 DAG 节点将任务相对路径误当作仓库根路径读取，导致找文件超时的问题
+- 修复 Operator Chat 重开会话时因 JSONL 丢失而静默新建会话 ID 导致会话不匹配的问题
+- 修复夜间任务异步执行结果丢失及 agent-worker 可执行文件权限的问题
+
+## [0.29.2] - 2026-08-07
+
+### 重点更新
+
+- 优化后端测试生成 writer 的续写重试机制，直接内嵌具体目标路径以恢复输出，不再依赖读取受限路径
+- 修复三处完整性门禁（Completeness Gate）误报，避免将正确的测试生成误判为残缺写集
+- 修复标准 Happy Path / `contract-pi` 等节点 source prompt：只暴露仓库相对可读路径（`.harness/tasks/<taskId>/source/...`），并明确禁止把 task-relative 的 `source/需求.md` 当工具读路径
+
+### 改进
+
+- 后端测试生成 writer（N2 MD / N5 pytest）在输出截断或残缺写集后，续写重试直接内嵌具体目标路径清单，不再依赖读取 `.harness/**` 路径
+- 即使遇到结果为空或输出失败的异常，也会评估完整性门禁，将可恢复的部分写入升格为不完整写集，避免重试空转
+
+### 修复
+
+- 修复 README 正文提及的编号式文件名被误判为缺失模块的问题
+- 修复覆盖率矩阵（Coverage Matrix）表头识别被覆盖率范围（Coverage Scope）数据行遮蔽的问题
+- 修复合法多行 `def` 的 pytest 脚本被误判为截断的问题（真正截断现仍由括号配平计数准确捕获）
 
 ## [0.29.0] - 2026-08-07
 

package/dist/commands/client-recovery.js

@@ -18,16 +18,8 @@ export const BACKOFF_MS = [2000, 4000, 8000, 16000, 30000];
 export const MAX_SESSION_RETRIES = 5;
 /** Hard cap for OpenCode overflow compact+resume recoveries (≤ 2). */
 export const MAX_OVERFLOW_RECOVERIES = 1;
-export const PI_RECOMMENDED_RETRY = {
-    enabled: true,
-    maxRetries: 5,
-    baseDelayMs: 3000,
-    provider: {
-        maxRetries: 0,
-        maxRetryDelayMs: 60000,
-    },
-};
-export const PI_RECOMMENDED_COMPACTION = { enabled: true };
+import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
+export { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY };
 /**
  * Shared overflow phrase sources used by isContextOverflow and generated plugins.
  * Keep English + Chinese intranet gateway messages in one place to avoid drift.

package/dist/commands/init.js

@@ -2217,7 +2217,7 @@ function buildTargetFeatureWorkflow(input) {
         '- `taskKind: "backend-test"` selects the dedicated backend test DAG. Its Pi nodes analyze requirements, generate and review backend cases, generate pytest, and retrospect on results; shell gate/execution nodes enforce the review verdict and run the target project\'s pytest. The backend test templates (`backend-test-dag.json` and the `backend-test-dag.*.prompt.md` files) ship inside the loop-agent package as static references and are projected to target projects under the governance `templates/` directory.',
         '- `taskKind: "knowledge-sync"` selects the Feature-scoped test-knowledge write-back DAG (collect → draft → validate → apply → pointer). Bind `featureId` in `task.json` (or hardConstraints / requirement text). It writes only under `features/<featureId>/…` after final verification evidence exists.',
         '- `taskKind: "knowledge-graph-bootstrap"` selects the business knowledge-graph bootstrap DAG (preflight → inventory → propose → validate → review → gate → promote → materialize). AI writes only `knowledge/bootstrap/staging/**`; promote is merge-new-only.',
-        '- `taskKind: "frontend-test"` selects the FE-test RAG DAG. It writes a traceable frontend RAG package and Markdown case manifest, then executes manifest cases serially with `playwright-cli` in isolated test environments and retains per-case evidence. It never generates pytest or Playwright source code. `frontendTest.maxCasesPerBatch` defaults to 20 (maximum 50); optional `maxTokensPerCase` and `maxTotalTokens` stop only later cases after a completed case\'s token usage is recorded, marking them `blocked: token-budget-exhausted`. Generated browser startup uses `playwright-cli open --browser=chrome --headless <base-url>`; the generic playwright-cli skill is unchanged.',
+        '- `taskKind: "frontend-test"` selects the FE-test RAG DAG. It writes a traceable frontend RAG package and Markdown case manifest, then executes manifest cases serially with `playwright-cli` in isolated test environments and retains per-case evidence. It never generates pytest or Playwright source code. `frontendTest.maxCasesPerBatch` defaults to 20 (maximum 50); optional `maxTokensPerCase` and `maxTotalTokens` stop only later cases after a completed case\'s token usage is recorded, marking them `blocked: token-budget-exhausted`. Generated browser startup uses `playwright-cli open --browser=chrome <base-url>`; the generic playwright-cli skill is unchanged.',
         "- Only eligible read-only Pi nodes (planner, scout, reviewer, verifier, closeout with no write-capable tool profile) receive the conservative automatic retry policy. Supervisor, implementer, writer, docs-only, dynamic, shell, static, and decision-gate nodes are not retried automatically. Eligible nodes cannot write repository files; the controller only records immutable attempt evidence under `.harness/dag-runs/<state>/<run-id>/<node-id>/attempt-<n>.json`.",
         "",
         "Use the package-backed public knowledge CLI for graph operations. Do not require target projects to run package-only kb runtime scripts:",

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

@@ -9,7 +9,7 @@ import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/d
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { isWriterEmptyDiffRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
-import { assessBackendTestMdWriterCompleteness, assessBackendTestPytestWriterCompleteness, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
+import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
 export const DAG_PI_READONLY_TOOLS = ["read", "grep", "find", "ls"];
 /** Bounded writer tools: no unrestricted bash; edit/write are policy-wrapped via SDK customTools. */
@@ -688,9 +688,20 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     if (writeGuardOk &&
         isBackendTestCompletenessRetryCandidate(input.task)) {
         try {
-            const progress = input.task.id === "generate-backend-pytest-pi"
-                ? await assessBackendTestPytestWriterCompleteness(input.cwd)
-                : await assessBackendTestMdWriterCompleteness(input.cwd);
+            const writerRole = backendTestWriterProgressRoleForTask(input.task.id);
+            const progress = isBackendTestShardChildTask(input.task)
+                ? await assessBackendTestShardChildCompleteness({
+                    workspaceRoot: input.cwd,
+                    role: writerRole === "pytest-generate" ? "pytest-generate" : "md-generate",
+                    writeSet: input.task.writeSet ?? [],
+                })
+                : isBackendTestMdPlanTask(input.task)
+                    ? await assessBackendTestMdPlanCompleteness(input.cwd)
+                    : isBackendTestPytestPlanTask(input.task)
+                        ? await assessBackendTestPytestPlanCompleteness(input.cwd)
+                        : writerRole === "pytest-generate"
+                            ? await assessBackendTestPytestWriterCompleteness(input.cwd)
+                            : await assessBackendTestMdWriterCompleteness(input.cwd);
             await writeBackendTestWriterProgressArtifacts({
                 runDir: meta.runDir,
                 progress,

package/dist/executors/pi-executor.js

@@ -961,10 +961,12 @@ export function classifyPiFailure(input) {
     if (input.exitCode === 0 && input.assistantText.trim())
         return "success";
     const combined = `${input.stderr}\n${input.stdout}`.toLowerCase();
-    if (/quota|usage limit|reached.*limit|5\s*小时|5小时/.test(combined))
-        return "quota";
-    if (/rate.?limit/.test(combined))
+    // 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))
         return "rate-limit";
+    if (/quota|usage limit|reached.*limit|5\s*小时|5小时|insufficient_quota|billing/.test(combined))
+        return "quota";
     if (/\bunauthorized\b|\bhttp\s*40[13]\b|invalid api key|authentication (?:failed|required|error)|auth(?:entication)? failed/.test(combined))
         return "auth";
     if (/unknown provider|unknown model|model.*unavailable|provider.*unavailable|\bunavailable\b|overloaded|capacity|temporarily unavailable/.test(combined))

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

@@ -197,21 +197,19 @@ function validateOpenArgs(args, baseUrl) {
     for (const arg of args) {
         assertNoControlMeta(arg);
         assertNoSessionFlag(arg);
-        if (arg === "--browser=chrome" || arg === "--headless") {
+        if (arg === "--browser=chrome") {
             flags.add(arg);
             normalized.push(arg);
             continue;
         }
-        // Accept legacy --headed but normalize to headless for frontend-test CI/dogfood.
-        if (arg === "--headed") {
-            flags.add("--headless");
-            if (!normalized.includes("--headless"))
-                normalized.push("--headless");
+        // playwright-cli defaults to headless and does not accept --headless/--headed.
+        // Strip legacy flags so model/docs remnants never reach the binary.
+        if (arg === "--headless" || arg === "--headed") {
             continue;
         }
         if (arg.startsWith("--browser=") ||
             arg === "--browser") {
-            throw new PlaywrightCliPolicyError("open-browser-flags", "open must use --browser=chrome --headless only");
+            throw new PlaywrightCliPolicyError("open-browser-flags", "open must use --browser=chrome only (default headless; do not pass --headless/--headed)");
         }
         if (/^[a-z][a-z0-9+.-]*:/i.test(arg) || arg.startsWith("http")) {
             url = arg;
@@ -219,12 +217,9 @@ function validateOpenArgs(args, baseUrl) {
         }
         throw new PlaywrightCliPolicyError("open-args", `unsupported open argument: ${arg}`);
     }
-    if (!flags.has("--browser=chrome") || !flags.has("--headless")) {
-        // controller injects required flags when missing from model args
-        if (!flags.has("--browser=chrome"))
-            normalized.unshift("--browser=chrome");
-        if (!flags.has("--headless"))
-            normalized.push("--headless");
+    if (!flags.has("--browser=chrome")) {
+        // controller injects required browser flag when missing from model args
+        normalized.unshift("--browser=chrome");
     }
     if (!url) {
         throw new PlaywrightCliPolicyError("open-url-required", "open requires an absolute http(s) URL");
@@ -515,7 +510,7 @@ export function preparePlaywrightCliArgv(input, ctx) {
             catch {
                 throw new PlaywrightCliPolicyError("goto-url-invalid", "goto requires a URL relative to the controller baseUrl");
             }
-            const openLike = validateOpenArgs(["--browser=chrome", "--headless", target], ctx.baseUrl);
+            const openLike = validateOpenArgs(["--browser=chrome", target], ctx.baseUrl);
             return openLike[openLike.length - 1];
         });
         if (args.length !== 1) {

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

@@ -2,6 +2,7 @@ import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractAssistantTextFromPiJson, } from "./pi-executor.js";
 import { serializeSessionEvent } from "./pi-event-serializer.js";
+import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
 let sdkSessionFactoryOverride;
 let sdkImportOverrideForTests;
 let sdkModuleOverrideForTests;
@@ -154,6 +155,7 @@ async function createSdkSession(sdk, input, shared) {
     const createAgentSession = sdk.createAgentSession;
     const SessionManager = sdk.SessionManager;
     const DefaultResourceLoader = sdk.DefaultResourceLoader;
+    const SettingsManager = sdk.SettingsManager;
     const getAgentDir = sdk.getAgentDir;
     const ModelRuntime = sdk.ModelRuntime;
     const agentDir = shared?.agentDir ?? getAgentDir();
@@ -168,12 +170,25 @@ async function createSdkSession(sdk, input, shared) {
     const model = input.provider && input.model
         ? await resolveModel(modelRuntime, input.provider, input.model)
         : undefined;
+    // Inject rate-limit-tolerant auto-retry settings for the session lifecycle.
+    // Prefer SettingsManager.inMemory so harness runs do not depend on ~/.pi or
+    // project .pi/settings.json being present/trusted.
+    const settingsManager = typeof SettingsManager?.inMemory === "function"
+        ? SettingsManager.inMemory({
+            retry: {
+                ...PI_RECOMMENDED_RETRY,
+                provider: { ...PI_RECOMMENDED_RETRY.provider },
+            },
+            compaction: { ...PI_RECOMMENDED_COMPACTION },
+        }, { projectTrusted: true })
+        : undefined;
     const loader = new DefaultResourceLoader({
         cwd: input.cwd,
         agentDir,
         noContextFiles: true,
         noSkills: true,
         noExtensions: true,
+        ...(settingsManager ? { settingsManager } : {}),
         appendSystemPromptOverride: (base) => [
             ...base,
             input.appendSystemPrompt,
@@ -191,6 +206,7 @@ async function createSdkSession(sdk, input, shared) {
         resourceLoader: loader,
         tools: input.toolNames,
         modelRuntime,
+        ...(settingsManager ? { settingsManager } : {}),
         ...(model ? { model } : {}),
         ...(input.thinking ? { thinkingLevel: input.thinking } : {}),
         ...(Array.isArray(input.customTools) && input.customTools.length > 0

package/dist/shared/operator/capabilities.js

@@ -776,7 +776,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
-            description: "DAG run handoff report by run id.",
+            description: "DAG run handoff report by run id. On failure, read primaryFailure.nodeId + primaryRecovery first; prefer dagRerunPlan from that node before standaloneTaskRerun or a new task.",
             inputParams: [
                 {
                     name: "runId",
@@ -919,19 +919,19 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
-            description: "Read-only subgraph rerun plan for confirmation (no mutation).",
+            description: "Read-only R1 subgraph plan (no mutation). Call before dagRerun. Prefer primaryFailure.nodeId from dagReport. If eligible=false (writer/decision/fingerprint), do not force execute — fall back to standaloneTaskRerun or same-task advance. Returns planHash required by execute.",
             inputParams: [
                 {
                     name: "runId",
                     type: "string",
                     required: true,
-                    description: "dag run id",
+                    description: "completed failed|partial_failed parent dag run id",
                 },
                 {
                     name: "fromNode",
                     type: "string",
                     required: true,
-                    description: "node id to rerun from",
+                    description: "node id to rerun from (prefer failed/attention node from dagReport primaryFailure.nodeId)",
                 },
             ],
             modelCallable: "always",
@@ -949,31 +949,31 @@ export function buildOperatorCapabilitiesDocument() {
                 "BINDING_DRIFT",
                 "INVALID_INPUT",
             ],
-            description: "Execute continuation run from effective node with confirmed plan hash.",
+            description: "Execute R1 continuation from effective node. Requires planHash from a fresh dagRerunPlan (eligible=true). Prefer this over new task / standaloneTaskRerun for provider flake and safe downstream failures. Human Gate required.",
             inputParams: [
                 {
                     name: "runId",
                     type: "string",
                     required: true,
-                    description: "dag run id",
+                    description: "parent dag run id (same as dagRerunPlan)",
                 },
                 {
                     name: "fromNode",
                     type: "string",
                     required: true,
-                    description: "node id to rerun from",
+                    description: "node id matching the planned dagRerunPlan",
                 },
                 {
                     name: "planHash",
                     type: "string",
                     required: true,
-                    description: "rerun plan hash",
+                    description: "sha256 plan hash from dagRerunPlan (must match exactly)",
                 },
                 {
                     name: "reason",
                     type: "string",
                     required: true,
-                    description: "rerun reason",
+                    description: "why continue from this node (e.g. provider flake; resume from review-pi)",
                 },
             ],
             modelCallable: "prepare-only",

package/dist/shared/pi-retry-settings.js

@@ -0,0 +1,23 @@
+/**
+ * Recommended Pi auto-retry settings for gateway rate limits.
+ *
+ * Work-hours gateways often enforce rolling windows (e.g. 100 req / 10 min).
+ * Pi's built-in default (2s / 4s / 8s) exhausts before the window recovers;
+ * a 60s base delay yields 1m → 2m → 4m … and tolerates transient 429s.
+ *
+ * Used by:
+ * - project / user `.pi` settings merge (`client-recovery`)
+ * - loop-agent Pi SDK executor (injected SettingsManager, independent of ~/.pi)
+ */
+export const PI_RECOMMENDED_RETRY = {
+    enabled: true,
+    maxRetries: 5,
+    /** First retry wait; subsequent attempts use exponential backoff. */
+    baseDelayMs: 60_000,
+    provider: {
+        /** Disable nested SDK provider retries; outer auto-retry owns the budget. */
+        maxRetries: 0,
+        maxRetryDelayMs: 60_000,
+    },
+};
+export const PI_RECOMMENDED_COMPACTION = { enabled: true };