@tea-agent/loop-agent 0.34.0 → 0.34.1

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [0.34.1] - 2026-08-11
+
+### 重点更新
+
+- Console PRD Intake Bridge：统一粘贴、单文件与多文件 PRD 导入流程，复用确定性解析与 Semantic Intake，并回写真实 Console Draft
+- 引入工程边界表单，工程路径与验证命令仅接受人工输入，杜绝使用模板内容冒充需求事实
+- DAG 中断恢复增强：支持协作式 abortSignal，未启动节点明确标记为 controller-interrupted，避免粗暴终止
+- Console Recovery 提供直观的 reconcile CTA，按运行状态精准展示恢复入口，破坏性操作需经浏览器 Human Gate 确认
+
+### 新增
+
+- Console PRD 导入桥接：支持将粘贴、单文件与多文件导入统一接入 task advance 的确定性解析，并映射产物至 DraftStore
+- Console 工程边界表单：在 PRD 导入时支持可选的 allowed/forbidden/verify 字段，并作为标志传递至 bootstrap intake
+- Console Recovery CTA：基于 effective status 与 liveness 展示 dag reconcile-run（supersede/abandon）入口
+- DAG runner 协作式 abortSignal：主控停止时允许已运行节点按 checkpoint 收尾，未启动节点标记 controller-interrupted
+
+### 改进
+
+- dag reconcile-run 增加 --json 与 --action 参数，避免 operation runner 因期待 JSON 失败，并明确拒绝非法 action
+- task advance 生命周期优化：PRD 导入后默认进入仅导入阶段，确保多文件 bootstrap 完成后再执行 Semantic Intake
+- Console Recovery 状态映射细化：将 interrupted/orphaned 等状态映射为 needs-reconcile，suspected-stall 映射为 observe/doctor
+- task advance writeSet gate 输出附确定性 delta，清晰展示边界扩张来源，且不破坏既有 approve 流程
+
+### 修复
+
+- 修复追加 PRD 后两阶段 intake 未重新投影契约、Console 可能回读旧 Semantic Intake artifact 的问题
+- 修复 implement-pi 在 provider clean timeout 且明确零写入时直接终止的问题，现对标准 bounded writer 自动重试一次
+- 修复 grill-me 模板被误当作已解析需求的问题
+- 修复窄屏（<1100px）下 CHANGELOG 文档中尖括号导致的 MDX JSX 解析错误
+
 ## [0.34.0] - 2026-08-11
 
 ### 重点更新

package/dist/application/task-lifecycle/advance.js

@@ -42,7 +42,8 @@ function hasEngineeringBoundary(input) {
 }
 /** Inputs that must produce a new managed-contract revision when explicit. */
 function hasContractChangingInput(input) {
-    return Boolean(hasEngineeringBoundary(input) ||
+    return Boolean((input.prdPaths?.length ?? 0) > 0 ||
+        hasEngineeringBoundary(input) ||
         input.title ||
         input.taskKind ||
         input.featureId);
@@ -339,7 +340,7 @@ export async function advanceTaskLifecycle(input) {
         verifyCommands: applied.verifyCommands ?? input.verifyCommands,
     };
     const hasBoundary = hasEngineeringBoundary(effectiveInput);
-    let refreshManagedContractThisCall = Boolean(hasContractChangingInput(effectiveInput) &&
+    let refreshManagedContractThisCall = Boolean((hasContractChangingInput(effectiveInput) || record.pendingPrdRefresh) &&
         (snapshot.contract?.effectiveStatus === "managed" ||
             Boolean(snapshot.contract?.revision && snapshot.contract.revision > 0)));
     if (applied.accepted) {
@@ -515,6 +516,7 @@ export async function advanceTaskLifecycle(input) {
             continue;
         }
         if (action.type === "import-prd") {
+            const importedMaterializedPaths = [];
             for (const prd of input.prdPaths ?? []) {
                 let markdown;
                 try {
@@ -528,7 +530,7 @@ export async function advanceTaskLifecycle(input) {
                     explicitRole: prd.role,
                     markdown,
                 });
-                await importPrdDocument({
+                const imported = await importPrdDocument({
                     repoRoot: input.repoRoot,
                     taskId: input.taskId,
                     filePath: prd.filePath,
@@ -536,15 +538,48 @@ export async function advanceTaskLifecycle(input) {
                     // Prefer basename-aligned names for multi-file product suites.
                     name: path.basename(prd.filePath).replace(/\.(md|markdown|txt)$/iu, "") || undefined,
                 });
+                importedMaterializedPaths.push(imported.materializedRelativePath);
             }
             // Latch even when prdPaths is empty so a mis-planned import cannot loop.
             importedPrdThisCall = true;
             if ((input.prdPaths?.length ?? 0) > 0) {
-                record = appendTransition(record, "prd-imported");
+                record = {
+                    ...appendTransition(record, "prd-imported"),
+                    pendingPrdRefresh: true,
+                    pendingPrdRefreshPaths: Array.from(new Set([
+                        ...(record.pendingPrdRefreshPaths ?? []),
+                        ...importedMaterializedPaths,
+                    ])),
+                };
                 completed.push("prd-imported");
                 await saveLifecycleRecord(input.repoRoot, record);
             }
             snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            // Two-phase Console bridge: when this call only had --prd and no
+            // engineering boundary, stop after archive. Re-plan would otherwise
+            // immediately prepare (hasPrdInput latched false + alreadyImported)
+            // and burn one-shot Semantic Intake before multi-file imports finish.
+            if (!hasBoundary && (input.prdPaths?.length ?? 0) > 0) {
+                return {
+                    taskId: input.taskId,
+                    lifecycleState: "intake-incomplete",
+                    completedTransitions: uniqueTransitions(record.completedTransitions, completed),
+                    gate: null,
+                    blockers: [],
+                    warnings: [
+                        ...warnings,
+                        {
+                            code: "BOUNDARY_REQUIRED",
+                            message: "PRD imported; re-run task advance (optionally with --allowed-path / --verify) to prepare contract / semantic intake",
+                        },
+                    ],
+                    next: {
+                        kind: "advance",
+                        command: `loop-agent task advance ${input.taskId} --json`,
+                    },
+                    recommendations,
+                };
+            }
             continue;
         }
         if (action.type === "prepare-contract") {
@@ -580,6 +615,8 @@ export async function advanceTaskLifecycle(input) {
                     : {
                         kind: "facts",
                         useImportedPrd: hasPrd || (snapshot.source?.importedPrdCount ?? 0) > 0,
+                        replaceManagedRequirement: record.pendingPrdRefresh === true,
+                        importedPrdPaths: record.pendingPrdRefreshPaths,
                         text: input.fromText,
                         textLabel: input.fromText ? "from-text" : undefined,
                     },
@@ -675,7 +712,11 @@ export async function advanceTaskLifecycle(input) {
                                     refreshManagedContractThisCall = false;
                                     regenerateDagThisCall = true;
                                 }
-                                record = appendTransition(record, "contract-managed");
+                                record = {
+                                    ...appendTransition(record, "contract-managed"),
+                                    pendingPrdRefresh: false,
+                                    pendingPrdRefreshPaths: [],
+                                };
                                 completed.push("contract-managed");
                                 await saveLifecycleRecord(input.repoRoot, record);
                                 snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
@@ -706,7 +747,12 @@ export async function advanceTaskLifecycle(input) {
                 const softIntakeAfter = Boolean(prepareResult.error?.details?.softIntake) ||
                     (gapCodesAfter.length > 0 &&
                         gapCodesAfter.every((code) => isIntakeSoftGapCode(code)));
-                if (softIntakeAfter && completed.includes("prd-imported")) {
+                // Soft-stop when PRD is on disk (this call or prior import).
+                // Console two-phase bootstrap: import first, then advance intake
+                // without re-passing --prd — still must soft-stop, not hard-fail.
+                const hasImportedPrdOnDisk = completed.includes("prd-imported") ||
+                    (snapshot.source?.importedPrdCount ?? 0) > 0;
+                if (softIntakeAfter && hasImportedPrdOnDisk) {
                     warnings.push({
                         code: "INTAKE_INCOMPLETE",
                         message: prepareResult.error?.message ??
@@ -750,7 +796,11 @@ export async function advanceTaskLifecycle(input) {
                 refreshManagedContractThisCall = false;
                 regenerateDagThisCall = true;
             }
-            record = appendTransition(record, "contract-managed");
+            record = {
+                ...appendTransition(record, "contract-managed"),
+                pendingPrdRefresh: false,
+                pendingPrdRefreshPaths: [],
+            };
             completed.push("contract-managed");
             await saveLifecycleRecord(input.repoRoot, record);
             snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);

package/dist/application/task-lifecycle/plan-transitions.js

@@ -62,17 +62,21 @@ export function planTransitions(input) {
         expectedTransitions.push("contract-managed");
     }
     else if (!sourceReady || !contractManaged) {
-        if ((shouldImportPrd || alreadyImportedPrd) &&
-            !input.hasEngineeringBoundary) {
-            // Console bootstrap / import-only: archive PRD(s), do not prepare contract yet.
-            if (shouldImportPrd) {
-                actions.push({ type: "import-prd" });
-                expectedTransitions.push("prd-imported");
-            }
+        // Console PRD Intake Bridge (2026-08-11), two-phase:
+        // 1) hasPrdInput without engineering boundary → import only (archive
+        //    references). Do NOT prepare yet so multi-file bootstrap can finish
+        //    all imports before the one-shot Semantic Intake burns.
+        // 2) alreadyImportedPrd without new --prd (and/or with boundary) →
+        //    prepare-contract so deterministic parse + Semantic Intake run.
+        // prepare soft-stops on EMPTY_ALLOWED_PATHS etc. and never opens the
+        // writeSet gate without a complete managed contract.
+        if (shouldImportPrd && !input.hasEngineeringBoundary) {
+            actions.push({ type: "import-prd" });
+            expectedTransitions.push("prd-imported");
             actions.push({ type: "stop", reason: "blocker" });
             blockers.push({
                 code: "BOUNDARY_REQUIRED",
-                message: "PRD imported; provide --allowed-path / --verify (or --from-text with boundaries) to prepare contract and open writeSet gate",
+                message: "PRD imported; re-run task advance (optionally with --allowed-path / --verify) to prepare contract / semantic intake",
             });
             return {
                 actions,
@@ -80,7 +84,7 @@ export function planTransitions(input) {
                 blockers,
                 next: {
                     kind: "advance",
-                    command: `loop-agent task advance ${snapshot.taskId} --allowed-path <glob> --verify <label:command> --json`,
+                    command: `loop-agent task advance ${snapshot.taskId} --json`,
                 },
                 expectedTransitions,
             };
@@ -218,18 +222,6 @@ export function planTransitions(input) {
         expectedTransitions,
     };
 }
-function stopWith(actions, expectedTransitions, blockers, snapshot, reason) {
-    return {
-        actions: [...actions, { type: "stop", reason }],
-        gate: snapshot.gate ?? null,
-        blockers,
-        next: {
-            kind: "advance",
-            command: `loop-agent task advance ${snapshot.taskId} --json`,
-        },
-        expectedTransitions,
-    };
-}
 function deriveNext(snapshot, gate, approveGate) {
     if (gate && !approveGate) {
         return { kind: "approve-gate", command: gate.approveCommand };

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

@@ -8,7 +8,7 @@ import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
 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 { 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 { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
 /**
@@ -831,6 +831,18 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     if (meta.writeGuardAttribution === "best-effort") {
         stderrParts.push("write guard note: concurrent rank writers use best-effort per-node attribution; keep same-rank writeSet entries disjoint");
     }
+    // Pure provider stall/timeout with zero workspace side effects is eligible
+    // for a single writer transport retry (implement-pi flake resilience).
+    // Partial writes, tool calls, or write-guard failures keep raw `timeout`.
+    const writerCleanTimeout = !mapped.ok &&
+        mapped.failureCategory === "timeout" &&
+        writeGuardOk &&
+        !completenessFailure &&
+        !writerThinkingExhausted &&
+        isWriterTransportRetryCandidate(input.task) &&
+        changeManifestChangedFiles !== undefined &&
+        changeManifestChangedFiles.length === 0 &&
+        readWriterThinkingExhaustionEvidence(result).writeToolCallCount === 0;
     return {
         ...mapped,
         ok: false,
@@ -851,7 +863,8 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 // the continuation is retryable and carries the embedded target paths.
                 // Provider/transport failures (quota, auth, network, timeout,
                 // rate-limit, unavailable) keep their original category so a provider
-                // outage is never masked as a recoverable local write problem.
+                // outage is never masked as a recoverable local write problem — except
+                // clean timeouts with zero attributed writes, remapped below.
                 writeGuardOk &&
                     completenessFailure?.failureCategory ===
                         INCOMPLETE_WRITE_SET_RETRY_CATEGORY &&
@@ -867,7 +880,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                         // upgrade to incomplete-write-set above.
                         writerThinkingExhausted
                             ? WRITER_THINKING_EXHAUSTED_CATEGORY
-                            : mapped.failureCategory,
+                            : writerCleanTimeout
+                                ? WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY
+                                : mapped.failureCategory,
         durationMs: mapped.durationMs || Date.now() - started,
     };
 }

package/dist/shared/operator/capabilities.js

@@ -586,13 +586,13 @@ export function buildOperatorCapabilitiesDocument() {
         },
         {
             action: "importPrd",
-            cli: "loop-agent task advance <id> --prd <server-staged-path> --json",
+            cli: "loop-agent task advance <id> --prd <server-staged-path> --json (+ intake bridge)",
             kind: "mutation",
             inputSchemaVersion: 1,
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "PATH_OUTSIDE_REPO"],
-            description: "Archive immutable PRD via task advance (server-staged file).",
+            description: "Archive PRD via task advance, run intake bridge (deterministic/semantic), rewrite Console draft.",
             inputParams: [
                 {
                     name: "taskId",
@@ -606,6 +606,30 @@ export function buildOperatorCapabilitiesDocument() {
                     required: true,
                     description: "PRD markdown content",
                 },
+                {
+                    name: "taskKind",
+                    type: "string",
+                    required: false,
+                    description: "workflow kind (human-selected)",
+                },
+                {
+                    name: "allowedPaths",
+                    type: "array",
+                    required: false,
+                    description: "optional engineering allowedPaths (human-confirmed)",
+                },
+                {
+                    name: "forbiddenPaths",
+                    type: "array",
+                    required: false,
+                    description: "optional engineering forbiddenPaths",
+                },
+                {
+                    name: "verifyCommands",
+                    type: "array",
+                    required: false,
+                    description: "optional verify commands (label:command or shell)",
+                },
             ],
             modelCallable: "always",
             humanConfirmation: "none",

package/dist/task/source-prepare/prepare.js

@@ -331,7 +331,19 @@ export async function prepareTaskSource(input) {
             constraintsPath: contractPaths.constraintsPath,
         });
         if (projection.ok) {
-            baseDraft = projection.draft;
+            baseDraft = input.intent.replaceManagedRequirement
+                ? {
+                    ...projection.draft,
+                    requirement: {
+                        objective: "",
+                        scope: [],
+                        nonGoals: [],
+                        acceptanceCriteria: [],
+                    },
+                    openQuestions: [],
+                    assumptions: [],
+                }
+                : projection.draft;
         }
         else {
             managedProjectionError = projection.message;
@@ -396,7 +408,30 @@ export async function prepareTaskSource(input) {
                 taskId,
                 requireParseableRequirement: false,
             });
-            hasImportedPrd = true;
+            const requestedPaths = new Set((input.intent.importedPrdPaths ?? [])
+                .map((value) => value.replace(/\\/g, "/").trim())
+                .filter(Boolean));
+            if (requestedPaths.size > 0) {
+                const selectedDocuments = sourceIntegrity.documents.filter((document) => requestedPaths.has(document.materializedPath.replace(/\\/g, "/")));
+                const selectedPaths = new Set(selectedDocuments.map((document) => document.materializedPath.replace(/\\/g, "/")));
+                for (const requestedPath of requestedPaths) {
+                    if (selectedPaths.has(requestedPath))
+                        continue;
+                    sourceIntegrity.issues.push({
+                        code: "REFERENCE_NOT_IN_MANIFEST",
+                        level: "blocking",
+                        message: `current import batch reference not found in source-manifest: ${requestedPath}`,
+                        path: requestedPath,
+                    });
+                    sourceIntegrity.ok = false;
+                }
+                sourceIntegrity = {
+                    ...sourceIntegrity,
+                    documents: selectedDocuments,
+                    parseableDocuments: selectedDocuments.filter((document) => document.parseable),
+                };
+            }
+            hasImportedPrd = sourceIntegrity.documents.length > 0;
             if (sourceIntegrity.ok) {
                 references = draftReferencesFromManifest(sourceIntegrity.documents);
                 let acStart = 1;
@@ -517,6 +552,7 @@ export async function prepareTaskSource(input) {
             "PRODUCT_CLARIFICATION_NOT_EXECUTABLE",
             "PRODUCT_REQUIREMENT_PENDING",
         ].includes(gap.code));
+        const hasEmptyAcceptance = gaps.some((gap) => gap.code === "EMPTY_ACCEPTANCE");
         for (const message of validation.errors) {
             const isAcceptanceSchema = /acceptance criterion|acceptanceCriteria/i.test(message);
             // Prefer product-artifact diagnostics over generic schema AC errors.
@@ -528,6 +564,17 @@ export async function prepareTaskSource(input) {
                 });
                 continue;
             }
+            // Soft-intake path: completeness already has EMPTY_ACCEPTANCE (soft).
+            // Do not add a hard DRAFT_VALIDATION twin that flips softIntake=false
+            // and blocks one-shot Semantic Intake for free-form PRDs.
+            if (hasEmptyAcceptance && isAcceptanceSchema) {
+                gaps.push({
+                    code: "DRAFT_VALIDATION",
+                    level: "warning",
+                    message: `${message} (soft intake; EMPTY_ACCEPTANCE primary)`,
+                });
+                continue;
+            }
             gaps.push({
                 code: "DRAFT_VALIDATION",
                 level: "blocking",

package/dist/worker/console/interview/grill-me.js

@@ -82,7 +82,8 @@ export function buildQuestionForGap(gapId, draft, context = {}) {
             id: `q-${gapId}`,
             gapId,
             text: "本轮允许改动的范围（scope）是哪些路径/模块？用逗号或换行列出。",
-            recommendation: "src/worker/console/**",
+            // No product-template default — must come from PRD intake or human override.
+            recommendation: "（请按 PRD / 仓库结构填写；勿套用 Console 模板路径）",
             affectsFields: ["requirement.scope"],
             risk: "high",
         },
@@ -90,7 +91,7 @@ export function buildQuestionForGap(gapId, draft, context = {}) {
             id: `q-${gapId}`,
             gapId,
             text: "明确非目标（non-goals）是什么？本轮刻意不做哪些事？",
-            recommendation: "Phase 4 General Operator Chat；合并 Console/Observe",
+            recommendation: "（本轮明确不做的事项；可写「暂无」）",
             affectsFields: ["requirement.nonGoals"],
             risk: "medium",
         },
@@ -98,7 +99,7 @@ export function buildQuestionForGap(gapId, draft, context = {}) {
             id: `q-${gapId}`,
             gapId,
             text: "验收标准有哪些？可用分号或换行列出（将编号为 AC-1…）。",
-            recommendation: "Happy Path 可走通 Interview→validate→apply；无 Cancel；无直接改代码 CTA",
+            recommendation: "（请写可观测验收标准；勿套用产品模板 AC）",
             affectsFields: ["requirement.acceptanceCriteria"],
             risk: "high",
         },
@@ -114,7 +115,7 @@ export function buildQuestionForGap(gapId, draft, context = {}) {
             id: `q-${gapId}`,
             gapId,
             text: "结构化 allowedPaths（写入白名单）？逗号/换行分隔 glob。",
-            recommendation: "src/worker/console/**, test/worker/console/**",
+            recommendation: "（工程边界须人类确认；示例：src/**, test/**）",
             affectsFields: ["constraints.allowedPaths"],
             risk: "high",
         },
@@ -122,7 +123,7 @@ export function buildQuestionForGap(gapId, draft, context = {}) {
             id: `q-${gapId}`,
             gapId,
             text: "forbiddenPaths（禁止写入）？逗号/换行分隔。",
-            recommendation: "src/cli/**, bin/**, package.json",
+            recommendation: ".harness/**, node_modules/**, package.json",
             affectsFields: ["constraints.forbiddenPaths"],
             risk: "high",
         },
@@ -130,7 +131,7 @@ export function buildQuestionForGap(gapId, draft, context = {}) {
             id: `q-${gapId}`,
             gapId,
             text: "验证命令（verifyCommands）？可给一条或多条 shell（换行分隔）。",
-            recommendation: "npx vitest run test/worker/console",
+            recommendation: "npm run typecheck",
             affectsFields: ["verification.commands"],
             risk: "medium",
         },