@tea-agent/loop-agent 0.25.4 → 0.25.6

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

@@ -5,7 +5,7 @@ import path from "node:path";
 import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
 import { resolveContextPolicy } from "./context-policy.js";
-import { buildDagNodePromptEnvelope } from "./prompt.js";
+import { buildDagNodePromptEnvelope, formatConvergenceFeedbackBlock, } from "./prompt.js";
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
 import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, } from "./retry-policy.js";
 import { applyNodeActivity, evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
@@ -25,6 +25,7 @@ export function buildNodePrompt(spec, task, upstream, options) {
         resolvedSkills: policy.resolveSkills(spec, task),
         maxUpstreamChars: policy.resolveMaxUpstreamChars(task),
         projectGovernanceContext: options?.projectGovernanceContext,
+        convergenceFeedback: options?.convergenceFeedback,
     });
 }
 function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason) {
@@ -75,6 +76,7 @@ export async function buildNodePromptWithResolvedSkillInstructions(spec, task, u
             resolvedSkillInstructions,
             maxUpstreamChars: policy.resolveMaxUpstreamChars(task),
             projectGovernanceContext: options?.projectGovernanceContext,
+            convergenceFeedback: options?.convergenceFeedback,
         }),
         resolvedSkills: skillInstructionMetadata(resolvedSkillInstructions),
     };
@@ -90,6 +92,41 @@ export function parseProcessVerdict(node) {
     }
     return "unknown";
 }
+/**
+ * Derive a bounded convergence feedback block for the next-round
+ * supervisor/repair node from `state.convergence`. Deterministic: reads the
+ * last passHistory entry and its preservedNodeRecordPath pointers; never
+ * searches the run directory. Returns undefined on pass 1 (no prior evidence).
+ */
+export function deriveConvergenceFeedback(state) {
+    const convergence = state.convergence;
+    if (!convergence?.enabled || convergence.currentPass <= 1)
+        return undefined;
+    const last = convergence.passHistory.at(-1);
+    if (!last)
+        return undefined;
+    return {
+        pass: last.pass,
+        reason: last.reason,
+        hardVerifyFailureCategory: last.hardVerifyFailureCategory,
+        processVerdict: last.processVerdict,
+        reviewVerdict: last.reviewVerdict,
+        reviewFailureCategory: last.reviewFailureCategory,
+        shellSuccessCount: last.shellSuccessCount,
+        repairArtifact: last.repairArtifact
+            ? {
+                failureClass: last.repairArtifact.failureClass,
+                rootCause: last.repairArtifact.rootCause,
+                fixScope: last.repairArtifact.fixScope,
+                invariant: last.repairArtifact.invariant,
+            }
+            : undefined,
+        evidenceRefs: last.artifactRefs.map((ref) => ({
+            nodeId: ref.nodeId,
+            preservedNodeRecordPath: ref.preservedNodeRecordPath,
+        })),
+    };
+}
 function assertRepairArtifactVerdictMatchesSupervisor(input) {
     const supervisorVerdict = parseProcessVerdict(input.node);
     if (supervisorVerdict === "unknown")
@@ -207,10 +244,10 @@ export async function executeDagNode(input) {
             return;
         }
     }
-    const isDynamicTask = Boolean(task.dynamicExpansion
-        || task.dynamicReduction
-        || task.dynamicCondition
-        || task.dynamicLoopUntil);
+    const isDynamicTask = Boolean(task.dynamicExpansion ||
+        task.dynamicReduction ||
+        task.dynamicCondition ||
+        task.dynamicLoopUntil);
     let snapshotPrompt;
     if (state.skillSnapshotRef) {
         try {
@@ -226,6 +263,17 @@ export async function executeDagNode(input) {
                     snapshot: skillSnapshot,
                     projectGovernanceContext,
                 });
+                const feedbackBlock = formatConvergenceFeedbackBlock(deriveConvergenceFeedback(state));
+                if (feedbackBlock &&
+                    (task.role === "supervisor" ||
+                        task.role === "implementer" ||
+                        task.id === "process-supervisor-pi" ||
+                        task.id === "repair-pi")) {
+                    snapshotPrompt = {
+                        ...snapshotPrompt,
+                        prompt: `${snapshotPrompt.prompt}\n\n<convergence_feedback>\n${feedbackBlock}\n</convergence_feedback>`,
+                    };
+                }
             }
         }
         catch (error) {
@@ -296,7 +344,10 @@ export async function executeDagNode(input) {
         }
         else {
             ({ prompt, resolvedSkills } =
-                await buildNodePromptWithResolvedSkillInstructions(spec, task, state.nodes, cwd, { projectGovernanceContext }));
+                await buildNodePromptWithResolvedSkillInstructions(spec, task, state.nodes, cwd, {
+                    projectGovernanceContext,
+                    convergenceFeedback: deriveConvergenceFeedback(state),
+                }));
         }
     }
     catch (error) {
@@ -433,8 +484,7 @@ export async function executeDagNode(input) {
         node.durationMs =
             retryPolicy === undefined
                 ? attemptRecord.durationMs
-                : attempts.reduce((sum, attempt) => sum + (attempt.durationMs ?? 0), 0) +
-                    totalBackoffMs;
+                : attempts.reduce((sum, attempt) => sum + (attempt.durationMs ?? 0), 0) + totalBackoffMs;
         node.stdout = result.stdout;
         node.stderr = result.stderr;
         node.failureCategory = result.failureCategory;
@@ -493,9 +543,10 @@ export async function executeDagNode(input) {
         !terminalResult.ok &&
         terminalResult.failureCategory === "protocol-invalid" &&
         task.outputProtocol) {
-        const fullText = terminalResult.assistantText && terminalResult.assistantText.trim().length > 0
+        const fullText = terminalResult.assistantText &&
+            terminalResult.assistantText.trim().length > 0
             ? terminalResult.assistantText
-            : terminalResult.stdout ?? "";
+            : (terminalResult.stdout ?? "");
         const normalized = normalizeReviewVerdictAfterRetries(task.outputProtocol, fullText);
         if (normalized.ok) {
             const normalizedText = normalized.normalizedOutput;
@@ -590,7 +641,9 @@ export async function executeDagNode(input) {
             const artifactPath = path.join(runDir, task.shell.jsonArtifactGate.outputDir, task.shell.jsonArtifactGate.artifactName);
             const bytes = await readFile(artifactPath);
             node.structuredArtifactPath = artifactPath;
-            node.structuredArtifactSha256 = createHash("sha256").update(bytes).digest("hex");
+            node.structuredArtifactSha256 = createHash("sha256")
+                .update(bytes)
+                .digest("hex");
             node.structuredArtifactSchemaId = task.shell.jsonArtifactGate.schemaId;
         }
         else if (task.shell?.backendTestPipeline === "classification-result-context" ||

package/dist/workflows/dag/prompt.js

@@ -58,7 +58,7 @@ export function formatOutputLanguageBlock(language = DEFAULT_DAG_OUTPUT_LANGUAGE
 }
 export function buildUpstreamContext(task, upstream, maxChars = MAX_UPSTREAM_CHARS) {
     const sections = [];
-    const toleratedErrors = new Set(task.failureAwareDependsOn ?? []);
+    const toleratedFailures = new Set(task.failureAwareDependsOn ?? []);
     for (const depId of task.depends_on) {
         const record = upstream[depId];
         const stdout = record?.stdout?.trim() ? record.stdout : "";
@@ -72,10 +72,12 @@ export function buildUpstreamContext(task, upstream, maxChars = MAX_UPSTREAM_CHA
         // explicitly so the node can read the failure without the upstream being
         // rewritten to FINISHED.
         if (record?.status === "ERROR" &&
-            toleratedErrors.has(depId) &&
+            toleratedFailures.has(depId) &&
             upstreamText) {
             const { preview, truncated } = formatStdoutPreview(upstreamText, maxChars);
-            let section = `## Upstream failure evidence: ${depId} (status=ERROR${record.failureCategory ? `, failureCategory=${record.failureCategory}` : ""})\n${preview}`;
+            let section = `## Upstream failure evidence: ${depId} (status=ERROR${record.failureCategory
+                ? `, failureCategory=${record.failureCategory}`
+                : ""})\n${preview}`;
             const artifactKind = stdout
                 ? "stdout"
                 : assistantText
@@ -99,6 +101,15 @@ export function buildUpstreamContext(task, upstream, maxChars = MAX_UPSTREAM_CHA
             sections.push(section);
             continue;
         }
+        if (record?.status === "SKIPPED" && toleratedFailures.has(depId)) {
+            const reason = record.skippedReason ?? "unknown";
+            sections.push([
+                `## Upstream failure evidence: ${depId} (status=SKIPPED)`,
+                `Skipped reason: ${reason}`,
+                "This dependency was skipped after an upstream failure. Preserve the failed/partial_failed outcome and do not infer success.",
+            ].join("\n"));
+            continue;
+        }
         if (!record || record.status !== "FINISHED" || !upstreamText)
             continue;
         const artifactKind = stdout ? "stdout" : "assistant";
@@ -132,6 +143,97 @@ function buildReadOnlyBoundary(writePolicy) {
         "Return findings in the assistant response/stdout only; the DAG runner persists node artifacts under .harness/dag-runs/<state>/<run-id>/<node-id>/.",
     ];
 }
+/** Max chars for each text field in the convergence feedback block. */
+const CONVERGENCE_FEEDBACK_FIELD_MAX_CHARS = 600;
+/** Max chars for one list item/path in convergence feedback. */
+const CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS = 240;
+/** Max items retained from an untrusted list-shaped feedback field. */
+const CONVERGENCE_FEEDBACK_LIST_MAX_ITEMS = 8;
+/** Hard cap for the complete rendered feedback block. */
+const CONVERGENCE_FEEDBACK_BLOCK_MAX_CHARS = 4_000;
+const CONVERGENCE_FEEDBACK_TRUNCATION_MARKER = "\n- [convergence feedback truncated]";
+function boundFeedbackText(value, maxChars = CONVERGENCE_FEEDBACK_FIELD_MAX_CHARS) {
+    if (!value)
+        return undefined;
+    if (value.length <= maxChars)
+        return value;
+    return `${value.slice(0, maxChars - 1)}…`;
+}
+function boundFeedbackList(values) {
+    const items = values
+        .slice(0, CONVERGENCE_FEEDBACK_LIST_MAX_ITEMS)
+        .map((value) => boundFeedbackText(value, CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS) ?? "");
+    return {
+        items,
+        omitted: Math.max(0, values.length - items.length),
+    };
+}
+function capConvergenceFeedbackBlock(block) {
+    if (block.length <= CONVERGENCE_FEEDBACK_BLOCK_MAX_CHARS)
+        return block;
+    const prefixLength = Math.max(0, CONVERGENCE_FEEDBACK_BLOCK_MAX_CHARS -
+        CONVERGENCE_FEEDBACK_TRUNCATION_MARKER.length);
+    return `${block.slice(0, prefixLength)}${CONVERGENCE_FEEDBACK_TRUNCATION_MARKER}`;
+}
+/**
+ * Format the prior supervised convergence pass as a bounded, structured block
+ * for the next-round supervisor/repair node. Deterministic: uses
+ * preservedNodeRecordPath pointers written by the convergence controller, never
+ * run-directory guessing. Returns undefined when there is no prior pass.
+ */
+export function formatConvergenceFeedbackBlock(feedback) {
+    if (!feedback)
+        return undefined;
+    const lines = [];
+    lines.push(`## Previous convergence pass ${feedback.pass} (reason=${boundFeedbackText(feedback.reason)})`);
+    lines.push("This is the prior bounded-recovery pass that failed. Use it as authoritative evidence for this round; do not repeat a no-op or infer success.");
+    if (feedback.hardVerifyFailureCategory) {
+        lines.push(`- hardVerifyFailureCategory: ${boundFeedbackText(feedback.hardVerifyFailureCategory)}`);
+    }
+    if (feedback.processVerdict) {
+        lines.push(`- processVerdict: ${feedback.processVerdict}`);
+    }
+    if (feedback.reviewVerdict) {
+        lines.push(`- reviewVerdict: ${feedback.reviewVerdict}`);
+    }
+    if (feedback.reviewFailureCategory) {
+        lines.push(`- reviewFailureCategory: ${boundFeedbackText(feedback.reviewFailureCategory)}`);
+    }
+    if (feedback.shellSuccessCount !== undefined) {
+        lines.push(`- shellSuccessCount: ${feedback.shellSuccessCount}`);
+    }
+    const repair = feedback.repairArtifact;
+    if (repair) {
+        const parts = [];
+        if (repair.failureClass)
+            parts.push(`failureClass=${boundFeedbackText(repair.failureClass)}`);
+        if (repair.rootCause)
+            parts.push(`rootCause=${boundFeedbackText(repair.rootCause)}`);
+        if (repair.invariant)
+            parts.push(`invariant=${boundFeedbackText(repair.invariant)}`);
+        if (repair.fixScope && repair.fixScope.length > 0) {
+            const boundedScope = boundFeedbackList(repair.fixScope);
+            const omitted = boundedScope.omitted > 0
+                ? `, … (+${boundedScope.omitted} more)`
+                : "";
+            parts.push(`fixScope=${boundedScope.items.join(", ")}${omitted}`);
+        }
+        if (parts.length > 0)
+            lines.push(`- priorRepairArtifact: ${parts.join("; ")}`);
+    }
+    const refs = feedback.evidenceRefs.filter((ref) => ref.preservedNodeRecordPath);
+    if (refs.length > 0) {
+        lines.push("- previous failure evidence (read-only runner evidence — use read tool to fetch; do not edit):");
+        const boundedRefs = refs.slice(0, CONVERGENCE_FEEDBACK_LIST_MAX_ITEMS);
+        for (const ref of boundedRefs) {
+            lines.push(`  - ${boundFeedbackText(ref.nodeId, CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS)}: ${boundFeedbackText(ref.preservedNodeRecordPath, CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS)}`);
+        }
+        if (refs.length > boundedRefs.length) {
+            lines.push(`  - … (+${refs.length - boundedRefs.length} more)`);
+        }
+    }
+    return capConvergenceFeedbackBlock(lines.join("\n"));
+}
 function formatProjectGovernanceContext(ctx) {
     if (!ctx || !ctx.applicable)
         return undefined;
@@ -174,7 +276,7 @@ function formatProjectGovernanceContext(ctx) {
     return lines.join("\n");
 }
 export function buildDagNodePromptEnvelope(input) {
-    const { spec, task, upstream, resolvedSkills = [], resolvedSkillInstructions = [], maxUpstreamChars = MAX_UPSTREAM_CHARS, projectGovernanceContext, } = input;
+    const { spec, task, upstream, resolvedSkills = [], resolvedSkillInstructions = [], maxUpstreamChars = MAX_UPSTREAM_CHARS, projectGovernanceContext, convergenceFeedback, } = input;
     const objective = spec.objective ?? spec.title;
     const successCriteria = formatBulletList(spec.successCriteria, "(none specified)");
     const globalConstraints = formatBulletList(spec.globalConstraints, "(none specified)");
@@ -229,6 +331,18 @@ export function buildDagNodePromptEnvelope(input) {
     if (governanceSection) {
         sections.push(`<project_governance_context>\n${governanceSection}\n</project_governance_context>`);
     }
+    // Only supervisor/repair nodes consume the prior convergence pass evidence.
+    // This keeps the bounded-recovery loop from repeating no-ops on round 2+.
+    if (convergenceFeedback &&
+        (task.role === "supervisor" ||
+            task.role === "implementer" ||
+            task.id === "process-supervisor-pi" ||
+            task.id === "repair-pi")) {
+        const feedbackSection = formatConvergenceFeedbackBlock(convergenceFeedback);
+        if (feedbackSection) {
+            sections.push(`<convergence_feedback>\n${feedbackSection}\n</convergence_feedback>`);
+        }
+    }
     sections.push(`<task>\n${task.subtask_prompt}\n</task>`);
     return sections.join("\n\n");
 }

package/dist/workflows/dag/retry-policy.js

@@ -37,6 +37,7 @@ const RETRY_SAFE_PI_ROLES = new Set([
     "scout",
     "reviewer",
     "verifier",
+    "supervisor",
     "closeout",
 ]);
 export const dagRetryCategorySchema = z.enum(ALL_DAG_RETRY_CATEGORIES);
@@ -120,14 +121,14 @@ export function isRetryablePiFailureCategory(rawFailureCategory, options = {}) {
  *
  * A safe candidate is:
  * - executor === "pi"
- * - role is planner/scout/reviewer/verifier/closeout (never supervisor/implementer)
+ * - role is planner/scout/reviewer/verifier/supervisor/closeout (never implementer)
  * - writePolicy is read-only/none/default and toolProfile is not write
  * - NOT dynamic (no dynamicExpansion/Reduction/Condition/LoopUntil)
  * - NOT a decision gate
  *
- * Writers and source supervisors can have non-idempotent side effects or
- * control-flow meaning and must not auto-retry. Dynamic nodes expand into
- * children and must not retry at the controller level.
+ * Writers can have non-idempotent side effects and must not auto-retry.
+ * Read-only, non-dynamic supervisors are safe because they only classify
+ * settled evidence; dynamic nodes still do not retry at the controller level.
  */
 export function isSafeReadOnlyPiRetryCandidate(task) {
     if (task.executor !== "pi")

package/dist/workflows/dag/scheduler.js

@@ -13,11 +13,11 @@ export function isConditionSkippedReason(reason) {
  * soft; the node runs when every dep is FINISHED or soft condition-skip and at
  * least one is FINISHED (OR-join after condition). Opt-in only — never default.
  */
-function dependencyReadiness(task, nodes) {
+function dependencyReadiness(task, nodes, tasksById) {
     if (task.depends_on.length === 0)
         return "run";
     const softConditionJoin = task.dependsPolicy === "all-or-condition-skip";
-    const toleratedErrors = new Set(task.failureAwareDependsOn ?? []);
+    const toleratedFailures = new Set(task.failureAwareDependsOn ?? []);
     let hasFinished = false;
     let hasPendingUpstream = false;
     let hasHardBlock = false;
@@ -40,7 +40,7 @@ function dependencyReadiness(task, nodes) {
             // consume a declared upstream ERROR as settled failure evidence. This
             // does not rewrite the upstream status; it only allows the recovery
             // node to become runnable so it can read the failure evidence.
-            if (toleratedErrors.has(depId)) {
+            if (toleratedFailures.has(depId)) {
                 hasFinished = true;
                 continue;
             }
@@ -48,6 +48,15 @@ function dependencyReadiness(task, nodes) {
             continue;
         }
         if (dep.status === "SKIPPED") {
+            // A failure-aware closeout may also consume an explicitly declared
+            // dependency that was skipped only because one of its ancestors failed.
+            // Follow the settled dependency chain to an actual ERROR; condition or
+            // manually skipped branches remain fail-closed.
+            if (toleratedFailures.has(depId) &&
+                isFailureDerivedSkipped(depId, nodes, tasksById)) {
+                hasFinished = true;
+                continue;
+            }
             if (softConditionJoin &&
                 isConditionSkippedReason(dep.skippedReason)) {
                 continue;
@@ -63,6 +72,24 @@ function dependencyReadiness(task, nodes) {
         return "run";
     return "skip";
 }
+function isFailureDerivedSkipped(nodeId, nodes, tasksById, visiting = new Set()) {
+    const node = nodes[nodeId];
+    if (node?.status !== "SKIPPED" ||
+        node.skippedReason !== "upstream dependency failed or was skipped" ||
+        visiting.has(nodeId)) {
+        return false;
+    }
+    const task = tasksById.get(nodeId);
+    if (!task)
+        return false;
+    const nextVisiting = new Set(visiting).add(nodeId);
+    return task.depends_on.some((upstreamId) => {
+        const upstream = nodes[upstreamId];
+        return (upstream?.status === "ERROR" ||
+            (upstream?.status === "SKIPPED" &&
+                isFailureDerivedSkipped(upstreamId, nodes, tasksById, nextVisiting)));
+    });
+}
 function conditionSkippedByAncestor(task, nodes) {
     return task.depends_on.some((depId) => isConditionSkippedReason(nodes[depId]?.skippedReason));
 }
@@ -86,7 +113,7 @@ export async function executeDagRanksOnce(input) {
         });
         const runnable = pending.filter((id) => {
             const task = input.tasksById.get(id);
-            return dependencyReadiness(task, input.state.nodes) === "run";
+            return (dependencyReadiness(task, input.state.nodes, input.tasksById) === "run");
         });
         const conditionSettled = [];
         for (const id of runnable) {
@@ -117,7 +144,7 @@ export async function executeDagRanksOnce(input) {
         const actuallyRunnable = runnable.filter((id) => !conditionSkippedSet.has(id));
         const blocked = pending.filter((id) => {
             const task = input.tasksById.get(id);
-            return dependencyReadiness(task, input.state.nodes) === "skip";
+            return (dependencyReadiness(task, input.state.nodes, input.tasksById) === "skip");
         });
         for (const id of blocked) {
             const node = input.state.nodes[id];

package/dist/workflows/dag/types.js

@@ -279,6 +279,7 @@ export const dagBackendTestPipelineSchema = z.enum([
     "markdown-cases",
     "markdown-traceability",
     "markdown-execute-html",
+    "markdown-manifest",
 ]);
 export const dagFrontendTestEvidenceValidationSchema = z.object({}).strict();
 export const dagFrontendTestCaseChecklistSchema = z.object({}).strict();
@@ -326,8 +327,9 @@ export const dagShellConfigSchema = z.object({
     frontendLintBaseline: dagFrontendLintBaselineSchema.optional(),
     frontendVerificationBundle: dagFrontendVerificationBundleSchema.optional(),
     frontendReviewContext: dagFrontendReviewContextSchema.optional(),
-    frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
     frontendTestCaseChecklist: dagFrontendTestCaseChecklistSchema.optional(),
+    frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
+    frontendTestL5Report: z.object({}).strict().optional(),
     frontendTestHtmlReport: dagFrontendTestHtmlReportSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
     /** JaCoCo coverage collection for backend-test (Java services). When set, node 7 dumps coverage over TCP from a JaCoCo tcpserver agent and feeds it to the L-5 dashboard. */
@@ -483,8 +485,9 @@ export const dagTaskSchema = z.object({
      */
     dependsPolicy: z.enum(["all", "all-or-condition-skip"]).optional(),
     /**
-     * Explicit opt-in: upstream node ids whose ERROR terminal state this
-     * read-only node may consume as settled failure evidence. Validation
+     * Explicit opt-in: upstream node ids whose ERROR terminal state, or whose
+     * failure-derived SKIPPED state, this read-only node may consume as settled
+     * failure evidence. Validation
      * restricts this to read-only Pi recovery/diagnosis/closeout nodes; writers,
      * shell verifiers, hard gates, and dynamic/decision nodes remain fail-closed.
      * Every id must also appear in depends_on.
@@ -680,7 +683,7 @@ export const dagSpecSchema = z
 export const DEFAULT_DAG_EXECUTOR_MODELS = {
     pi: {
         LOW: "gpt-5.3-codex-spark",
-        MED: "glm-5.2",
+        MED: "gpt-5.5",
         HIGH: "gpt-5.5",
     },
 };

package/dist/workflows/dag/validate.js

@@ -464,6 +464,7 @@ function validateShellTaskConfig(task, spec, issues) {
         !shell.frontendReviewContext &&
         !shell.frontendTestCaseChecklist &&
         !shell.frontendTestEvidenceValidation &&
+        !shell.frontendTestL5Report &&
         !shell.frontendTestHtmlReport) {
         issues.push({
             type: "missing-shell-commands",
@@ -592,7 +593,7 @@ function validateRetryPolicyTaskConfig(task, issues) {
     if (!isSafeReadOnlyPiRetryCandidate(task)) {
         issues.push({
             type: "invalid-retry-policy",
-            message: `task ${task.id} declares retryPolicy but is not a safe read-only non-dynamic Pi node; retry is only allowed for read-only/none Pi planner/scout/reviewer/verifier/closeout nodes without write, supervisor, or dynamic capabilities`,
+            message: `task ${task.id} declares retryPolicy but is not a safe read-only non-dynamic Pi node; retry is only allowed for read-only/none Pi planner/scout/reviewer/verifier/supervisor/closeout nodes without write or dynamic capabilities`,
         });
     }
 }
@@ -664,7 +665,7 @@ function validateFailureAwareDependsOn(task, spec, issues) {
     if (!isReadOnlyPiRecoveryNode) {
         issues.push({
             type: "invalid-failure-aware-dependency",
-            message: `task ${task.id} declares failureAwareDependsOn but failure-aware dependencies are allowed only for read-only recovery/diagnosis/supervision/closeout-equivalent Pi nodes (reviewer, verifier, supervisor, closeout); writer and shell verification nodes may not tolerate upstream ERROR`,
+            message: `task ${task.id} declares failureAwareDependsOn but failure-aware dependencies are allowed only for read-only recovery/diagnosis/supervision/closeout-equivalent Pi nodes (reviewer, verifier, supervisor, closeout); writer and shell verification nodes may not tolerate upstream ERROR or failure-derived SKIPPED`,
         });
         return;
     }

package/docs/architecture/dag-execution.md

@@ -131,12 +131,15 @@ decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析
 - **显式 recovery mutation**：`dag reconcile-run`（`src/commands/dag-reconcile-run.ts`，命令层）默认仅检查；只有给出 `--action supersede|abandon` + reason，且 liveness 证明 runner 已停止时，才在原 lifecycle 写 reconciliation/state 并迁移到 `completed/`。仍为 `RUNNING` 的节点保持失败语义，但以 `reconciledAt - startedAt` 补齐节点和当前 attempt 的耗时，原始状态继续冻结在 `reconciliation.json`。它不是修改既有 completed history 的通用入口。Observe / status / doctor 始终只读。
 - **status 枚举**：`DagRunState.status`；`TERMINAL_RUN_STATUSES` 判终态；`isTerminalDagRunStatus` 工具函数。
 
-## convergence（可选、supervised）
+## convergence（supervised 默认启用、有界自愈）
 
 - 控制器：`src/workflows/dag/convergence/controller.ts` `runConvergencePassController`，在 runner rank 间被调用。
-- 特性默认 **off**（`task/config-types.ts` `convergence` 默认 `{ enabled: false }`）。
-- 启用后按 `maxPasses`（默认 3）做多轮 repair，回归时可 `pauseOnRegression`。
-- 产物落在 `<runDir>/convergence/pass-<n>/`。
+- supervised 路径的 convergence 由 task `maxFixLoops` 派生（`init-hybrid.ts` `resolveSupervisedConvergence`）：`maxFixLoops > 0` ⇒ `enabled: true`、`maxPasses = maxFixLoops + 1`（初次执行 + 修复预算）、`chainNodeIds` 覆盖 `process-supervisor-pi → process-gate-shell → repair-pi → hard-verify-shell → review-pi → review-verdict-recovery-pi → review-gate-shell`；`maxFixLoops === 0` ⇒ `enabled: false`。task-level `convergence` config 仍默认 `{ enabled: false }`（opt-in），不会被 supervised 路径以外的模板启用。
+- 触发源：hard verify 可恢复失败（`nonzero-exit` 等）与 review 合法 `request-revision`（`review-gate-shell` ERROR）进入同一有界恢复链；两者都套用 non-retry / regression / max-passes 守卫。
+- 重算边界：进入下一轮时重置 convergence chain，以及 `hard-verify-shell` 的完整后代闭包（包括已 `FINISHED` 的 authority/governance 节点与 failure-aware closeout），防止修复后复用首轮陈旧治理或交接证据。
+- 证据回灌：每轮 pass 记录写入 `state.convergence.passHistory`，并归档到 `<runDir>/convergence/pass-<n>/`；下一轮 supervisor/repair 的 prompt 确定性注入上一轮失败类别、review verdict、repairArtifact 摘要与 `convergence/pass-<n>/<node>.json` 证据指针（`prompt.ts` `formatConvergenceFeedbackBlock`），并对列表项数、单项长度和完整 block（4000 字符）设置硬上限，不依赖搜索 run 目录。
+- 安全失败不重试：`write-guard` / `auth` / `missing-api-key` / `human-rejected` / `decision-gate-requires-human` / `timeout` / `spawn-error` 继续 fail-closed。
+- 非 supervised 模板（未声明 `chainNodeIds` 且无 `review-gate-shell`）保持原 hard-verify-only 行为。
 
 ## 完成权威 = shell verification
 

package/docs/architecture/runtime-boundaries.md

@@ -196,7 +196,7 @@ Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec pl
 
 | 面 | 路径 / 入口 | 边界 |
 |---|---|---|
-| OpenCode 项目插件 | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 直接返回真实 `Hooks.event`，分发 `session.error` / `session.status` / `message.updated`；从 `client.session.status()` 的 session map 判断内置 retry，以 `client.session.promptAsync()` 续接同一 session；只有成功完成的 assistant message 清零连续失败计数。认证/权限/配额/上下文溢出/取消/业务错误走 `plugin-ignore-permanent-error` |
+| OpenCode 项目插件 | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 直接返回真实 `Hooks.event`，分发 `session.error` / `session.status` / `session.idle` / `message.updated`；每个 session 保存 pending error，busy/retry/unknown/status API 失败只暂停恢复，后续 idle 事件重新驱动单一 worker。`client.session.status({ throwOnError: true })` 在退避前后确认 idle，`client.session.promptAsync(..., throwOnError: true)` 仅在 1.18.9 的 204 响应明确返回对象型 `data` 时计入一次 attempt 并续接同一 session；只有成功完成的 assistant message 清零连续失败计数。认证/权限/配额/上下文溢出/取消/业务错误走 `plugin-ignore-permanent-error` |
 | Pi 用户配置 | `~/.pi/agent/settings.json` | **不**进入项目 `.harness/init-surface.json` hash；仅 `--client-recovery=user` 可字段级补缺并原子写；`auto`/`project`/`off` 与 `check-update` 默认零写 home；读取时只有 `ENOENT` 视为缺文件，其他 I/O 错误 fail closed |
 | CLI mode | `--client-recovery=auto\|project\|user\|off`（默认 `auto`） | `auto`/`project` 只装项目插件；`user` = 项目插件 + 显式 Pi 合并；`off` 全跳过 |
 | Ownership | recorded sha256 + apply-safe | 插件缺失可补、与 recorded hash 一致可升级；用户改过 → model merge / human decision，禁止静默覆盖 |

package/docs/init-surface.manifest.json

@@ -23,6 +23,7 @@
     "docs/skills/README.md",
     "docs/skills/vetted-skill-registry.md",
     "docs/templates/README.md",
+    "docs/templates/init-managed-agents.md",
     "docs/templates/init-evolution-review.md",
     "docs/templates/exec-plan.md",
     "docs/templates/production-readiness-checklist.md",
@@ -257,7 +258,8 @@
   ],
   "initExcluded": [
     "examples/example-dag.json",
-    "docs/skills/vetted-skill-registry.md"
+    "docs/skills/vetted-skill-registry.md",
+    "docs/templates/init-managed-agents.md"
   ],
   "reviewTriggers": [
     "AGENTS.md",

package/docs/templates/README.md

@@ -6,6 +6,7 @@
 
 ## 通用任务、报告与治理
 
+- `init-managed-agents.md` — **package-only**：目标项目 `AGENTS.md` managed block 的可编辑正文真源（`__LOOP_AGENT_PROJECT_NAME__` / `__LOOP_AGENT_GOVERNANCE_ROOT__` 占位符；由 `init` 渲染注入，**不**复制到目标治理 `templates/`）。
 - `project-start-checklist.md` — 开工检查。
 - `feature-spec.md`、`sprint-contract.md` — 功能规格与短周期合同。
 - `exec-plan.md`、`progress-log.md`、`qa-report.md` — 执行计划、交接与验证报告。

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

@@ -59,7 +59,7 @@
   "executorModels": {
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
+      "MED": "gpt-5.5",
       "HIGH": "gpt-5.5"
     }
   },

package/docs/templates/agent-dag.final-verification.json

@@ -27,7 +27,7 @@
   "executorModels": {
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
+      "MED": "gpt-5.5",
       "HIGH": "gpt-5.5"
     }
   },

package/docs/templates/agent-dag.supervised-implementation.json

@@ -84,7 +84,7 @@
   "executorModels": {
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
+      "MED": "gpt-5.5",
       "HIGH": "gpt-5.5"
     }
   },