@tea-agent/loop-agent 0.22.0 → 0.24.0

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

@@ -9,7 +9,7 @@ import { buildDagNodePromptEnvelope } 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";
-import { buildProtocolRetryInstruction, validateOutputProtocol, } from "./output-protocol.js";
+import { buildProtocolRetryInstruction, normalizeReviewVerdictAfterRetries, validateOutputProtocol, } from "./output-protocol.js";
 import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { buildProjectGovernanceContext, readCompletedWriterChangeManifests, writeProjectGovernanceContext, } from "./project-governance-context.js";
 import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "./skill-snapshot.js";
@@ -483,6 +483,43 @@ export async function executeDagNode(input) {
             await input.persistState();
         }
     }
+    // AC2: after retries are exhausted on a canonical review verdict protocol
+    // node, attempt one deterministic normalization of the full terminal output.
+    // This ONLY re-wraps output so the first non-empty line is the single
+    // supported verdict; it never changes the verdict value, and missing /
+    // duplicated / conflicting / illegal verdicts remain protocol-invalid.
+    // Shell, write-guard, timeout, and model failures are never normalized.
+    if (terminalResult &&
+        !terminalResult.ok &&
+        terminalResult.failureCategory === "protocol-invalid" &&
+        task.outputProtocol) {
+        const fullText = terminalResult.assistantText && terminalResult.assistantText.trim().length > 0
+            ? terminalResult.assistantText
+            : terminalResult.stdout ?? "";
+        const normalized = normalizeReviewVerdictAfterRetries(task.outputProtocol, fullText);
+        if (normalized.ok) {
+            const normalizedText = normalized.normalizedOutput;
+            terminalResult = {
+                ...terminalResult,
+                ok: true,
+                failureCategory: undefined,
+                assistantText: normalizedText,
+                stdout: normalizedText,
+                stderr: [
+                    terminalResult.stderr,
+                    `verdict normalized after retries exhausted: ${normalized.verdictLine}`,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+            };
+            // Sync the observable node fields so downstream gates and reports see the
+            // normalized first-line verdict while the original evidence is preserved.
+            node.assistantText = normalizedText;
+            node.stdout = normalizedText;
+            node.failureCategory = undefined;
+            node.stderr = terminalResult.stderr;
+        }
+    }
     const result = terminalResult;
     const started = Date.now();
     try {

package/dist/workflows/dag/output-protocol.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { normalizeVerdictCandidateLine } from "./dynamic-runtime/shared.js";
 /**
  * Machine-readable output protocol for safe read-only Pi nodes.
  *
@@ -74,3 +75,91 @@ export function buildProtocolRetryInstruction(protocol, reason) {
         "</retry_instruction>",
     ].join("\n");
 }
+/**
+ * AC2: deterministic review-verdict normalization applied ONLY after retries
+ * are exhausted on a review verdict protocol node.
+ *
+ * The canonical review verdict protocol accepts exactly one of
+ * {@link REVIEW_VERDICT_OUTPUT_PROTOCOL}.validLines. This helper scans the
+ * FULL output (assistantText + stdout style text) for verdict lines using the
+ * same whole-line Markdown-emphasis normalization the verdict gate uses.
+ *
+ * Normalization succeeds if and only if the full output contains exactly one
+ * supported, unambiguous verdict line. It produces a normalized output whose
+ * first non-empty line is that verdict, preserving the original evidence text
+ * afterwards. It never changes the verdict value.
+ *
+ * It fails (returns ok:false) for:
+ * - no verdict line anywhere;
+ * - multiple verdict lines, even if identical (duplicated protocol ambiguity);
+ * - conflicting verdict lines;
+ * - any unsupported/illegal verdict value (e.g. `VERDICT: approve`);
+ * - malformed lines that are not a supported verdict after normalization;
+ * - natural-language approval prose without a real verdict token.
+ *
+ * This helper only operates on the canonical review verdict protocol; any
+ * other protocol is left untouched (ok:false) so decision envelopes, shell
+ * output, and structured protocols are never loosely tolerated.
+ */
+export function normalizeReviewVerdictAfterRetries(protocol, text) {
+    const isReviewVerdictProtocol = protocol.type === REVIEW_VERDICT_OUTPUT_PROTOCOL.type &&
+        Array.from(protocol.validLines).every((line, index) => line === REVIEW_VERDICT_OUTPUT_PROTOCOL.validLines[index]) &&
+        protocol.validLines.length ===
+            REVIEW_VERDICT_OUTPUT_PROTOCOL.validLines.length;
+    if (!isReviewVerdictProtocol) {
+        return {
+            ok: false,
+            reason: "deterministic verdict normalization only applies to the canonical review verdict protocol",
+        };
+    }
+    const supported = new Set(REVIEW_VERDICT_OUTPUT_PROTOCOL.validLines);
+    const candidates = [];
+    let seenIllegalVerdictPrefixedLine = false;
+    for (const rawLine of String(text).split(/\r?\n/)) {
+        const normalized = normalizeVerdictCandidateLine(rawLine);
+        if (!normalized)
+            continue;
+        // Detect any line that looks like a verdict token (VERDICT: ...) but is
+        // not a supported value, so a single valid + single illegal line cannot
+        // be silently normalized to the valid one.
+        if (/^VERDICT:/.test(normalized) && !supported.has(normalized)) {
+            seenIllegalVerdictPrefixedLine = true;
+            continue;
+        }
+        if (supported.has(normalized)) {
+            candidates.push(normalized);
+        }
+    }
+    if (seenIllegalVerdictPrefixedLine) {
+        return {
+            ok: false,
+            reason: "output contains an illegal or unsupported VERDICT value; cannot normalize",
+        };
+    }
+    if (candidates.length === 0) {
+        return {
+            ok: false,
+            reason: "no supported verdict line found in full output; cannot normalize",
+        };
+    }
+    const unique = new Set(candidates);
+    if (unique.size !== 1 || candidates.length !== 1) {
+        return {
+            ok: false,
+            reason: "output contains multiple or conflicting verdict lines; normalization requires exactly one supported verdict",
+        };
+    }
+    const verdictLine = candidates[0];
+    const preservedEvidence = String(text)
+        .split(/\r?\n/)
+        .filter((line) => {
+        const normalized = normalizeVerdictCandidateLine(line);
+        return !normalized || !supported.has(normalized);
+    })
+        .join("\n")
+        .trim();
+    const normalizedOutput = preservedEvidence
+        ? `${verdictLine}\n${preservedEvidence}`
+        : verdictLine;
+    return { ok: true, verdictLine, normalizedOutput };
+}

package/dist/workflows/dag/prompt.js

@@ -58,13 +58,47 @@ 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 ?? []);
     for (const depId of task.depends_on) {
         const record = upstream[depId];
         const stdout = record?.stdout?.trim() ? record.stdout : "";
         const assistantText = record?.assistantText?.trim()
             ? record.assistantText
             : "";
-        const upstreamText = stdout || assistantText;
+        const stderr = record?.stderr?.trim() ? record.stderr : "";
+        const upstreamText = stdout || assistantText || stderr;
+        // AC1: a failure-aware recovery/diagnosis/closeout node may consume an
+        // upstream ERROR as settled failure evidence. Surface that evidence
+        // explicitly so the node can read the failure without the upstream being
+        // rewritten to FINISHED.
+        if (record?.status === "ERROR" &&
+            toleratedErrors.has(depId) &&
+            upstreamText) {
+            const { preview, truncated } = formatStdoutPreview(upstreamText, maxChars);
+            let section = `## Upstream failure evidence: ${depId} (status=ERROR${record.failureCategory ? `, failureCategory=${record.failureCategory}` : ""})\n${preview}`;
+            const artifactKind = stdout
+                ? "stdout"
+                : assistantText
+                    ? "assistant"
+                    : "stderr";
+            const artifactPath = artifactKind === "stdout"
+                ? record.stdoutArtifactPath
+                : artifactKind === "assistant"
+                    ? record.assistantArtifactPath
+                    : undefined;
+            if (truncated && artifactPath) {
+                section += formatUpstreamArtifactPointerMap(record, artifactKind === "stdout" ? "stdout" : "assistant");
+            }
+            else if (truncated && record.nodeRecordPath) {
+                section += [
+                    "",
+                    "Full failure record (read-only runner evidence — use read tool to fetch; do not edit):",
+                    `- node record: ${record.nodeRecordPath}`,
+                ].join("\n");
+            }
+            sections.push(section);
+            continue;
+        }
         if (!record || record.status !== "FINISHED" || !upstreamText)
             continue;
         const artifactKind = stdout ? "stdout" : "assistant";

package/dist/workflows/dag/recovery-recommendation.js

@@ -8,6 +8,51 @@ export const DAG_RECOVERY_ACTIONS = [
     "inspect-upstream",
     "unknown",
 ];
+const FOLLOW_UP_BY_RAW_CATEGORY = {
+    "nonzero-exit": {
+        nextStepCategory: "repair",
+        reason: "Deterministic command exited nonzero; inspect stdout/stderr and exit code, then repair code, command, or environment before rerun.",
+    },
+    "decision-envelope-invalid": {
+        nextStepCategory: "revision",
+        reason: "Decision gate output violated the envelope protocol; revise the decision node prompt/output and do not infer approval.",
+    },
+    "protocol-invalid": {
+        nextStepCategory: "revision",
+        reason: "Model output violated the required protocol; if deterministic verdict normalization cannot prove exactly one supported verdict, revise/retry the protocol-producing node rather than inferring approval.",
+    },
+    "write-guard": {
+        nextStepCategory: "repair",
+        reason: "Write boundary was violated; narrow writeSet or revert out-of-bound changes before rerun. Write-guard failures must not be converted to success.",
+    },
+    timeout: {
+        nextStepCategory: "retry",
+        reason: "Execution exceeded its activity/wall-clock budget; inspect readiness/resource diagnostics and scoped timeout budget, then retry once the readiness issue is fixed.",
+    },
+    "controller-interrupted": {
+        nextStepCategory: "restart",
+        reason: "Controller was interrupted; reconcile run state from persisted DAG facts, then restart or resume the run.",
+    },
+};
+const UNKNOWN_FOLLOW_UP = {
+    nextStepCategory: "diagnosis",
+    reason: "Failure category is unavailable or unrecognized; run diagnosis/report before selecting repair/retry/restart.",
+};
+/**
+ * Deterministic mapping from a raw failure category to a stable next-step
+ * category and reason. Unknown/missing categories route to diagnosis.
+ *
+ * This is a routing hint only; callers must not use it to change a DAG run's
+ * terminal status or to convert a genuine failure into success.
+ */
+export function recommendFollowUpForFailureCategory(rawFailureCategory) {
+    if (!rawFailureCategory)
+        return { ...UNKNOWN_FOLLOW_UP };
+    const direct = FOLLOW_UP_BY_RAW_CATEGORY[rawFailureCategory];
+    if (direct)
+        return { ...direct };
+    return { ...UNKNOWN_FOLLOW_UP };
+}
 const REPORT_DERIVED_ONLY = "Derived planning hint only; dag report does not execute retry or resume.";
 const TRANSIENT_EXECUTOR_RAW = new Set([
     "network",

package/dist/workflows/dag/report.js

@@ -8,7 +8,7 @@ import { dagRunDirExists, getDagRunDir, locateDagRun, readDagRunSpec, readDagRun
 export const DAG_CLOSEOUT_DRAFT_DISCLAIMER = "> **Advisory only.** Derived from completed run facts. Canonical source remains `dag report --json` and `.harness/dag-runs/completed/<run-id>/`. Do not treat this draft as authoritative.";
 import { dagNormalizedFailureCategorySchema, normalizeDagFailureCategory, } from "./failure-category.js";
 import { dagProductLineFailureCategoryValues, routeDagFailure, } from "./failure-routing.js";
-import { DAG_RECOVERY_ACTIONS, planDagRecovery, } from "./recovery-recommendation.js";
+import { DAG_RECOVERY_ACTIONS, planDagRecovery, recommendFollowUpForFailureCategory, } from "./recovery-recommendation.js";
 import { dagNodeExecutorSchema, dagNodeStatusSchema, LEGACY_TOP_LEVEL_MODELS_ERROR, parseDagSpec, resolveModelForTask, } from "./types.js";
 import { checkRuntimeContractCompatible, DAG_CONTROLLER_CAPABILITIES, } from "./runtime-contract.js";
 export const DAG_REPORT_SCHEMA_VERSION = 1;
@@ -141,6 +141,10 @@ const dagNodeReportRowSchema = z
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
     productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
     recommendedFollowUp: z.string().optional(),
+    recommendedFollowUpCategory: z
+        .enum(["repair", "revision", "retry", "restart", "diagnosis"])
+        .optional(),
+    recommendedFollowUpReason: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     backend: z.enum(["sdk", "cli"]).optional(),
     sdkAttempted: z.boolean().optional(),
@@ -166,6 +170,10 @@ const dagRunReportEntrySchema = z
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
     productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
     recommendedFollowUp: z.string().optional(),
+    recommendedFollowUpCategory: z
+        .enum(["repair", "revision", "retry", "restart", "diagnosis"])
+        .optional(),
+    recommendedFollowUpReason: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     primaryFailure: dagReportPrimaryFailureSchema,
     primaryRecovery: dagRecoveryRecommendationSchema,
@@ -434,6 +442,9 @@ export async function buildDagRunReportEntry(input) {
                 nodeId,
                 executor: node.executor,
             });
+            const followUp = node.status === "ERROR" || node.status === "SKIPPED"
+                ? recommendFollowUpForFailureCategory(node.failureCategory)
+                : undefined;
             nodes.push({
                 nodeId,
                 rank,
@@ -448,6 +459,12 @@ export async function buildDagRunReportEntry(input) {
                 failureCategory: node.failureCategory,
                 normalizedFailureCategory,
                 ...failureRouting,
+                ...(followUp
+                    ? {
+                        recommendedFollowUpCategory: followUp.nextStepCategory,
+                        recommendedFollowUpReason: followUp.reason,
+                    }
+                    : {}),
                 recoveryRecommendation: planDagRecovery({
                     status: node.status,
                     normalizedFailureCategory,
@@ -513,6 +530,10 @@ export async function buildDagRunReportEntry(input) {
         normalizedFailureCategory: runRecoverySource.normalizedFailureCategory,
         nodeId: "nodeId" in runRecoverySource ? runRecoverySource.nodeId : undefined,
     });
+    const runFollowUp = input.state.status === "failed" ||
+        input.state.status === "partial_failed"
+        ? recommendFollowUpForFailureCategory(input.state.failureCategory)
+        : undefined;
     const partialEntry = {
         runId: input.state.runId,
         title: input.state.title,
@@ -524,6 +545,12 @@ export async function buildDagRunReportEntry(input) {
         failureCategory: input.state.failureCategory,
         normalizedFailureCategory,
         ...runFailureRouting,
+        ...(runFollowUp
+            ? {
+                recommendedFollowUpCategory: runFollowUp.nextStepCategory,
+                recommendedFollowUpReason: runFollowUp.reason,
+            }
+            : {}),
         recoveryRecommendation,
         pausedByNodeId: input.state.pausedByNodeId,
         pauseReason: input.state.pauseReason,

package/dist/workflows/dag/rerun-task.js

@@ -193,7 +193,7 @@ function blockedResult(input) {
     };
 }
 function extractRunSummary(generateResult) {
-    if (generateResult.mode === "generate+validate")
+    if (generateResult.mode === "generate+basic-validate")
         return undefined;
     return generateResult.run;
 }

package/dist/workflows/dag/scheduler.js

@@ -17,6 +17,7 @@ function dependencyReadiness(task, nodes) {
     if (task.depends_on.length === 0)
         return "run";
     const softConditionJoin = task.dependsPolicy === "all-or-condition-skip";
+    const toleratedErrors = new Set(task.failureAwareDependsOn ?? []);
     let hasFinished = false;
     let hasPendingUpstream = false;
     let hasHardBlock = false;
@@ -35,6 +36,14 @@ function dependencyReadiness(task, nodes) {
             continue;
         }
         if (dep.status === "ERROR") {
+            // AC1: an explicit read-only recovery/diagnosis/closeout node may
+            // 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)) {
+                hasFinished = true;
+                continue;
+            }
             hasHardBlock = true;
             continue;
         }

package/dist/workflows/dag/types.js

@@ -27,6 +27,10 @@ export const dagShellVerifyEvidenceSchema = z.object({
     commandCount: z.number().int().nonnegative(),
     commandLabels: z.array(z.string()).default([]),
     commandTexts: z.array(z.string()).default([]),
+    /** Effective timeout applied independently to each shell command. */
+    commandTimeoutMs: z.number().int().positive().optional(),
+    /** Worst-case serial budget: commandCount * commandTimeoutMs. */
+    totalTimeoutBudgetMs: z.number().int().nonnegative().optional(),
     finalFullRequired: z.boolean().optional(),
 });
 export const dagRepairArtifactGateSchema = z.object({
@@ -424,6 +428,14 @@ export const dagTaskSchema = z.object({
      *   every dep is FINISHED or soft condition-skip and at least one is FINISHED (OR-join)
      */
     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
+     * 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.
+     */
+    failureAwareDependsOn: z.array(z.string()).optional(),
     /** Execute only when this fail-closed condition resolves true after dependencies settle. */
     runIf: z.string().min(1).optional(),
     complexity: dagComplexitySchema,

package/dist/workflows/dag/validate.js

@@ -614,6 +614,60 @@ function validateDecisionGateTaskConfig(task, issues) {
         });
     }
 }
+/**
+ * AC1: failure-aware dependencies are an explicit, narrow opt-in. Only
+ * read-only Pi nodes acting as recovery/diagnosis/supervision/closeout
+ * (reviewer, verifier, supervisor, closeout roles) may tolerate an upstream
+ * ERROR. Writers, shell verifiers, hard/decision gates, dynamic nodes, and any
+ * node with write capability must remain fail-closed.
+ */
+const FAILURE_AWARE_SAFE_ROLES = new Set([
+    "reviewer",
+    "verifier",
+    "supervisor",
+    "closeout",
+]);
+function validateFailureAwareDependsOn(task, spec, issues) {
+    const tolerated = task.failureAwareDependsOn;
+    if (!tolerated || tolerated.length === 0)
+        return;
+    const isReadOnlyPiRecoveryNode = task.executor === "pi" &&
+        FAILURE_AWARE_SAFE_ROLES.has(task.role ?? "") &&
+        task.toolProfile !== "write" &&
+        (task.writePolicy === undefined ||
+            task.writePolicy === "read-only" ||
+            task.writePolicy === "none") &&
+        (task.writeSet ?? []).length === 0 &&
+        !task.decisionGate?.enabled &&
+        !task.dynamicExpansion &&
+        !task.dynamicReduction &&
+        !task.dynamicCondition &&
+        !task.dynamicLoopUntil;
+    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`,
+        });
+        return;
+    }
+    const dependsOn = new Set(task.depends_on);
+    const knownIds = new Set(spec.tasks.map((entry) => entry.id));
+    for (const upstreamId of tolerated) {
+        if (!knownIds.has(upstreamId)) {
+            issues.push({
+                type: "invalid-failure-aware-dependency",
+                message: `task ${task.id} failureAwareDependsOn references unknown task id ${upstreamId}`,
+            });
+            continue;
+        }
+        if (!dependsOn.has(upstreamId)) {
+            issues.push({
+                type: "invalid-failure-aware-dependency",
+                message: `task ${task.id} failure-aware dependency ${upstreamId} must be listed in depends_on`,
+            });
+        }
+    }
+}
 export function collectExecutorModelWarnings(spec, expectedMatrices = DEFAULT_DAG_EXECUTOR_MODELS) {
     const warnings = [];
     const executors = Object.keys(DEFAULT_DAG_EXECUTOR_MODELS);
@@ -704,6 +758,7 @@ export function validateDagSpec(spec) {
         validateRetryPolicyTaskConfig(task, issues);
         validateOutputProtocolTaskConfig(task, issues);
         validateProjectGovernanceTaskConfig(task, spec, issues);
+        validateFailureAwareDependsOn(task, spec, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);