@tea-agent/loop-agent 0.40.0-next.1 → 0.40.0-next.11

package/dist/workflows/dag/node-execution.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
 import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
 import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, FRONTEND_WRITER_NODE_IDS, isFrontendWriterAuthorized, readFrontendPrewriteResult, } from "./scheduler.js";
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
@@ -306,6 +307,35 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
         "</retry_instruction>",
     ].join("\n");
 }
+const PROMPT_RESTART_CANDIDATE_MAX_BYTES = 64 * 1024;
+function promptRestartCandidateForAttempt(input) {
+    if (input.attemptPrompt === input.baseRuntimePrompt) {
+        return input.taskPrompt;
+    }
+    const appendedPrefix = `${input.baseRuntimePrompt}\n\n`;
+    if (input.attemptPrompt.startsWith(appendedPrefix)) {
+        return [
+            input.taskPrompt,
+            input.attemptPrompt.slice(appendedPrefix.length),
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+    }
+    return input.attemptPrompt;
+}
+async function persistFailedPromptRestartCandidate(input) {
+    const redacted = redactSecrets(input.prompt);
+    const preview = truncateUtf8Preview(redacted, PROMPT_RESTART_CANDIDATE_MAX_BYTES);
+    await writeDagNodeJsonArtifact(input.runDir, input.nodeId, `prompt-candidate-attempt-${input.attempt}.json`, {
+        schemaVersion: 1,
+        attempt: input.attempt,
+        failureCategory: input.failureCategory ?? "unknown",
+        prompt: preview,
+        truncated: preview !== redacted,
+        maxBytes: PROMPT_RESTART_CANDIDATE_MAX_BYTES,
+        sha256: createHash("sha256").update(redacted).digest("hex"),
+    });
+}
 export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd, options) {
     const policy = resolveContextPolicy(spec);
     const skillNames = policy.resolveSkills(spec, task);
@@ -770,6 +800,7 @@ export async function executeDagNode(input) {
         // exactly this attempt's segment (B1: earlier attempts legitimately use
         // ls/find and must not be attributed to the repair attempt).
         const attemptSessionEventsOffset = await sessionEventsByteLength(runDir, nodeId);
+        let promptRestartCandidate = task.subtask_prompt;
         let result;
         try {
             validateRepairArtifactGateBeforeShell({
@@ -833,6 +864,11 @@ export async function executeDagNode(input) {
                     previousReason: previousProtocolReason,
                 });
             }
+            promptRestartCandidate = promptRestartCandidateForAttempt({
+                taskPrompt: task.subtask_prompt,
+                baseRuntimePrompt: prompt,
+                attemptPrompt,
+            });
             result = await executeNode({
                 task,
                 cwd,
@@ -960,6 +996,15 @@ export async function executeDagNode(input) {
         const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
         totalAttemptWallDurationMs += attemptWallDurationMs;
         const rawFailureCategory = result.rawFailureCategory ?? result.failureCategory;
+        if (task.executor === "pi" && !result.ok) {
+            await persistFailedPromptRestartCandidate({
+                runDir,
+                nodeId,
+                attempt: attemptNumber,
+                failureCategory: result.failureCategory,
+                prompt: promptRestartCandidate,
+            });
+        }
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,

package/dist/workflows/dag/types.js

@@ -382,7 +382,7 @@ export const dagWritePolicySchema = z.enum([
     "none",
 ]);
 /** Git/post-diff write guard intensity for exclusive Pi writers. */
-export const dagWriteGuardPolicySchema = z.enum(["full", "tools-only"]);
+export const dagWriteGuardPolicySchema = z.enum(["full", "tools-only", "filesystem-only"]);
 /**
  * Fail-closed outcome/diff consistency contract for bounded Pi writers.
  * The writer must begin with IMPLEMENTATION_OUTCOME: changed,
@@ -589,6 +589,8 @@ export const dagDynamicExpansionChildTaskSchema = z.object({
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     writeSet: z.array(z.string()).optional(),
+    /** Template-rendered strict repository-relative read allowlist. */
+    readSet: z.array(z.string()).optional(),
     /**
      * Materialized-child pass-through fields for bounded Pi writer children
      * (backend-test md/pytest case sharding). All optional so legacy
@@ -776,6 +778,21 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
     commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     writeSet: z.array(z.string()).optional(),
+    /** Strict repository-relative read allowlist for bounded Pi nodes. */
+    readSet: z.array(z.string()).optional(),
+    /**
+     * Online per-attempt Pi context guard. Unlike run/map cost budgets, this
+     * aborts the active SDK session before an oversized conversation reaches
+     * the provider's context rejection boundary.
+     */
+    contextBudget: z
+        .object({
+        maxTurns: z.number().int().positive().optional(),
+        maxTokens: z.number().int().positive().optional(),
+    })
+        .strict()
+        .refine((value) => value.maxTurns !== undefined || value.maxTokens !== undefined, "contextBudget requires maxTurns or maxTokens")
+        .optional(),
     piStep: z.string().optional(),
     shell: dagShellConfigSchema.optional(),
     static: dagStaticConfigSchema.optional(),
@@ -890,20 +907,51 @@ export const dagEvaluationBindingSchema = z
     .strict();
 /** Eval Lab Campaign Budget (W3.4); enforced by runner ledger when mode=hard. */
 export const dagBudgetSchema = campaignBudgetSchema;
-export const dagSourceBindingSchema = z.object({
+export const dagSourceBindingSourceSchema = z.object({
+    kind: z.enum(["requirement", "constraint", "reference"]),
+    path: z.string().min(1),
+    sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
+});
+/**
+ * DagSourceBinding v1：无 ledger 字段（schemaVersion=1，.strict() 拒绝 ledger
+ * 字段混入，不得以 v1+optional 冒充 v2）。非 frontend task / 无可解析引用时使用。
+ */
+export const dagSourceBindingV1Schema = z
+    .object({
     schemaVersion: z.literal(1),
     taskId: z.string().min(1),
-    sources: z
-        .array(z.object({
-        kind: z.enum(["requirement", "constraint", "reference"]),
-        path: z.string().min(1),
-        sha256: z
-            .string()
-            .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
-    }))
-        .min(1),
+    sources: z.array(dagSourceBindingSourceSchema).min(1),
     requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
-});
+})
+    .strict();
+/**
+ * DagSourceBinding v2（20260824-frontend-source-fidelity-ledger-v1）：仅
+ * frontend-implementation 且存在可解析 requirement/acceptance 引用时产出；
+ * ledgerPath/ledgerSha256/inputDigest/requirementToFragments 全部必填且完整，
+ * 伪造或缺失任一字段被 schema/prewrite 拒绝（AC-002 / AC-FIDELITY-REPAIR-002）。
+ */
+export const dagSourceBindingV2Schema = z
+    .object({
+    schemaVersion: z.literal(2),
+    taskId: z.string().min(1),
+    sources: z.array(dagSourceBindingSourceSchema).min(1),
+    requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
+    /** 受管 requirement-ledger.json 的 DAG 可解析路径（.harness/tasks/…/source/…）。 */
+    ledgerPath: z.string().min(1),
+    ledgerSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    inputDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    requirementToFragments: z.record(z.string(), z.array(z.string())),
+})
+    .strict();
+export const dagSourceBindingSchema = z.discriminatedUnion("schemaVersion", [
+    dagSourceBindingV1Schema,
+    dagSourceBindingV2Schema,
+]);
+export function isDagSourceBindingV2(binding) {
+    return binding.schemaVersion === 2;
+}
 const dagRerunFeedbackEvidencePathSchema = z
     .string()
     .min(1)
@@ -966,6 +1014,8 @@ export const dagSpecSchema = z
     taskContractBinding: dagTaskContractBindingSchema.optional(),
     /** Optional unresolved parent-run feedback for a full task rerun. */
     rerunFeedback: dagRerunFeedbackSchema.optional(),
+    /** Backend-test-only workspace mutation control; absent means Git. */
+    backendTestWorkspaceControl: z.enum(["git", "filesystem-only"]).optional(),
     /** Frozen backend-test artifact layout (plan A); absent = historical default testcase/ layout. */
     backendTestLayout: z
         .object({

package/docs/README.md

@@ -27,6 +27,7 @@
 | 选择快速、标准或完整验证命令 | `governance/verification-matrix.md` |
 | 理解 CLI、runtime 和初始化能力边界 | `runtime/loop-agent-harness.md` |
 | 运行 DAG、查看报告或处理失败 | `runtime/agent-dag-runner.md`、`runtime/agent-dag-recovery-playbook.md`；Operator Chat P0 closeout 见 `reports/feature/2026-08-14-operator-chat-dag-recovery-p0.md` |
+| 理解前端实现 DAG 与需求保真账本 | `runtime/frontend-implementation-workflow.md`（含 source fidelity ledger v2 绑定、顺序 reconciliation、独立 reviewer、human resolution 与 prewrite fail-closed）；init-evolution 审查见 `reports/init-evolution/2026-08-24-frontend-source-fidelity-ledger-init-evolution-review.md` |
 | 按 TDD、验证和调试纪律推进修复 | `governance/harness-methodology-tdd.md`、`governance/harness-methodology-verification.md`、`governance/harness-methodology-debugging.md` |
 | 执行真实 backend-test provider 验证 | `runtime/backend-test-live-campaign.md` |
 | 判断单任务 loop-agent Production Readiness | `operations/production-readiness.md` |
@@ -72,6 +73,7 @@
 | `design/active/` | 仍会影响后续决策的设计输入、路线与契约 |
 | `design/visual-references/` | 长期视觉参考，不表达实现状态 |
 | `design/archive/` | 历史设计和已被实现/替代的阶段性设计 |
+| `superpowers/specs/` | Superpowers 工作流产出的阶段性实现设计输入 |
 | `exec-plans/active/` | 仍需推进或明确保持 open 的任务合同 |
 | `exec-plans/completed/` | 已完成任务合同归档 |
 | `progress/` | 仍需下一次会话接手的当前 handoff 入口 |

package/docs/architecture/evolution.md

@@ -33,6 +33,7 @@ loop-agent CLI
 | Worker readiness baseline | Attempt identity、immutable owner、lineage/revision、task-scoped lease、controller protocol、acceptance、reconcile | Agent Worker PR v1 Phase 1–7 / `0.32.0` |
 | Operator Surface | 裸 `agent-worker console`；Operate、`/inspect/`、Operator Chat、recovery CTA、intake bridge | ADR 0005、0011–0013 |
 | 自举与验证 | controller identity、skill snapshot、deterministic/live canary、verified tarball、`verify:tree` receipt | `runtime-boundaries.md`、verification matrix |
+| Source fidelity ledger | 原始 requirement/acceptance 文档保持语义权威，派生 `source/需求.md` 仅作导航视图；确定性 fragment inventory、受管 `requirement-ledger.json`（进入 Task Contract transaction 与 canonical hash）、source binding v2（仅 frontend taskKind，schemaVersion=2 必填字段）、prewrite fail-closed 门禁（`SOURCE_FIDELITY_*`/`source-*` 稳定错误码）、顺序 reconciliation 与独立 reviewer、human resolution 生效、有界提示词与最终 reviewer 核对清单 | `20260824-frontend-source-fidelity-ledger-v1` + `2026-08-24-frontend-source-fidelity-repair-v2`（本页面下方 init-evolution 审查）、`CHANGELOG.md [Unreleased]` |
 
 ### 当前不变量
 
@@ -106,3 +107,47 @@ Evidence & Trust Plane
 2. 证明成立后更新 current capability summary 和本页“当前架构”。
 3. 未证明部分只保留在 active design/exec-plan，不能通过修改措辞升级状态。
 4. 使用者短索引同步到 `website/docs/overview/roadmap.md`，避免复制长版本流水账。
+
+## Init Evolution Review — 2026-08-24 frontend source fidelity ledger
+
+Base/Head：见 `docs/reports/init-evolution/` 中对应 `*-init-evolution-review.md`（若已提交则含 Base/Head 字段；未提交工作区由 CI 非严格模式放行）。
+
+### Changed Surface
+
+- `src/task/source-prepare/**`：新增 `fragment-inventory.ts`、`ledger.ts`；扩展 `types.ts`、`prepare.ts`、`completeness.ts`、`parse-intent.ts`（无外部 API 变化）。
+- `src/task/contract/**`：`requirement-ledger.json` 进入受管 transaction 与 canonical hash；`TaskContractSourceHashesV1` 新增可选 `requirementLedgerSha256`（legacy ref 向后兼容）。
+- `src/workflows/dag/**`：`dagSourceBindingSchema` 拆为 v1/v2 discriminated union（v2 schemaVersion=2，四个 ledger 字段全部必填；v1 strict 拒绝 ledger 字段）；`init-hybrid` 改读已持久化 ledger（缺失/漂移 fail closed）；prewrite 门禁新增 ledger 检查与失败码。
+- `src/task/source-prepare/**`：新增 `ledger-reconciliation.ts`（顺序 reconciliation）、`ledger-review.ts`（独立 reviewer）；fragment inventory 表格行切分、跨文档稳定 REQ-SRC ID、V4 显式 AC 标题；human resolution 生效。
+- `src/worker/observe/**`：新增只读 `GET /api/tasks/:id/ledger` 与展示（安全摘要，不泄漏原文）。
+- `src/worker/console/**`：Draft/ContractPanel/InspectSplitPanel 安全摘要展示。
+- `docs/templates/frontend-implementation-contract.schema.json`：requirements 增加可选 `sourceFragmentIds`/`sourceRefs`，sourceBinding 增加可选 ledger 字段（all-or-none）。
+
+### Decision
+
+**No init impact / Surface check only**。
+
+Rationale：
+
+- 新增均为模块内部实现；不新增 CLI 命令、不改 init 入口、不改变 target-project 初始化行为。
+- `docs/templates/frontend-implementation-contract.schema.json` 已随 `docs/templates/` 目录 glob 打包（`package.json files`），无需新增 manifest 条目。
+- 运行时加载 schema 的 `loadFrontendImplementationContractJsonSchema` 仅做结构性校验（$id/required/properties/const），新增可选字段不破坏既有契约。
+- 不新增任何运行时或开发依赖（node:crypto、既有 zod/Vitest/Vite/React 19）。
+
+### Updates Made
+
+- `docs/architecture/evolution.md`：本条目。
+- `CHANGELOG.md [Unreleased]`、`CONTEXT.md`：glossary 术语。
+- `docs/templates/frontend-implementation-contract.schema.json`：可选字段同步。
+
+### Verification
+
+```bash
+npm run typecheck && npm run console:typecheck
+npx vitest run test/task-source-prepare.test.ts test/task-contract-canonicalize.test.ts test/task-contract-observe.test.ts test/dag-init-hybrid.test.ts test/frontend-implementation-contract.test.ts test/frontend-prewrite-gate.test.ts test/frontend-writer-admission.test.ts test/worker/observe/dag-inspector-node-input.test.ts test/worker/console/inspect-split-panel.test.ts
+```
+
+### Residual Risk
+
+- 长尾 24K 截断遗漏回归：以确定性分片 inventory + ledger 覆盖统计断言固定（AC-FIDELITY-001/007）。
+- 账本漂移/篡改：inputDigest 复用失效 + prewrite fail closed（AC-FIDELITY-003/006）。
+- 既有带引用 frontend task 重建路径变化：ledger 纳入 canonical hash 改变 `observeTaskContractState` 判定，legacy ref 向后兼容覆盖（AC-FIDELITY-004）。

package/docs/init-surface.manifest.json

@@ -30,6 +30,7 @@
     "docs/templates/frontend-task-requirement.md",
     "docs/templates/frontend-task-constraints.md",
     "docs/templates/frontend-design-contract.md",
+    "docs/templates/frontend-implementation-contract.schema.json",
     "docs/templates/worker-dogfood-setup.md",
     "docs/templates/worker-dogfood-evidence.md",
     "docs/templates/harness.schema.json",

package/docs/operations/local-development-environment.md

@@ -2,6 +2,27 @@
 
 本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](../governance/verification-matrix.md) 为准。
 
+## Operator Console 前端快速迭代
+
+对 `src/worker/console/static-src/` 内的对话样式和前端交互做高频调整时，使用固定 8790 的开发入口：
+
+```bash
+npm run console:dev
+```
+
+它从当前源码启动真实 Console 后端，并在内部 `8791` 常驻 Vite dev server。浏览器始终访问 `http://127.0.0.1:8790/`：API、HttpOnly Cookie、确认令牌和 Origin 校验仍由真实 Console 处理，前端 HTML/模块请求才由 8790 转发给 Vite。CSS 保存后原地热替换，TSX 保存后自动整页刷新；不生成 `static-dev` bundle，也不重复运行生产 build。
+
+常用参数：
+
+```bash
+npm run console:dev -- --no-open
+npm run console:dev -- --port 8792 --reload-port 8793 --no-open
+```
+
+默认端口是 Console `8790`、内部 Vite/HMR `8791`；两者都只允许 loopback。端口已占用时命令会失败并报告端口，不会停止或接管已有进程。前端类型检查在后台持续输出诊断，但不阻塞 HMR；后端源码变化时只重启 Console 子进程，Vite 保持常驻。
+
+该命令只优化编辑反馈，不构成验收。独立交互修复完成后仍需运行定向 Vitest；交付前按验证矩阵运行 typecheck、正式 `npm run console:build` / `npm run build`。正式构建继续写入 `dist/worker/console/static/`，不会包含 `/@vite/client`、8791 或开发代理代码。
+
 ## Git hooks（本仓库）
 
 每个 clone 安装一次：

package/docs/templates/README.md

@@ -37,7 +37,7 @@
 ## Frontend
 
 - `frontend-task-requirement.md`、`frontend-task-constraints.md`、`frontend-design-contract.md` — 前端任务输入与设计合同。
-- `frontend-implementation-contract.schema.json` — 前端实现合同 schema。
+- `frontend-implementation-contract.schema.json` — 前端实现合同 schema（sourceBinding v2 ledger 字段 all-or-none：任一出现则四项齐全，禁止 v1+optional 冒充 v2）。`requirements[].sourceRefs[].items` 使用合法 `$ref: #/$defs/path`（相对路径、无 `..` 逃逸、无反斜杠），模板 JSON 无非法键，运行时加载器可直接编译（AC-003）。
 - `frontend-test-dag.json` — frontend-test DAG 模板；其 deterministic checklist 会拒绝 alternative executable instructions，仅允许 allowlisted `playwright-cli` command。Pi generator/reviser 的 runtime writeSet 仅授权下列目标项目生成路径（不是本仓库文档索引目标）：
 
   ~~~text

package/docs/templates/agent-dag.schema.json

@@ -538,6 +538,24 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
+        "readSet": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Strict repository-relative read allowlist for bounded Pi nodes."
+        },
+        "contextBudget": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Online per-attempt Pi SDK conversation guard. At least one threshold is required; exhaustion aborts the active session with context-budget-exhausted partial evidence.",
+          "properties": {
+            "maxTurns": { "type": "integer", "minimum": 1 },
+            "maxTokens": { "type": "integer", "minimum": 1 }
+          },
+          "anyOf": [
+            { "required": ["maxTurns"] },
+            { "required": ["maxTokens"] }
+          ]
+        },
         "piStep": {
           "type": "string",
           "minLength": 1