@tea-agent/loop-agent 0.20.1-beta.0 → 0.21.0

package/dist/workflows/dag/lifecycle.js

@@ -187,10 +187,38 @@ export function assessDagRunLiveness(input) {
         return { status: "stale", runnerAlive: true };
     }
     const activeNode = Object.values(input.state.nodes).find((node) => node.status === "RUNNING");
-    const nodeActivityMs = Date.parse(activeNode?.lastActivityAt ?? activeNode?.startedAt ?? "");
-    if (!Number.isNaN(nodeActivityMs) && nowMs - nodeActivityMs > (input.nodeQuietThresholdMs ?? 300_000)) {
+    if (!activeNode)
+        return { status: "active", runnerAlive: true };
+    // Prefer persisted adaptive projection when present.
+    if (activeNode.livenessStatus === "needs-attention") {
+        return { status: "needs-attention", runnerAlive: true };
+    }
+    if (activeNode.livenessStatus === "suspected-stall"
+        || activeNode.livenessStatus === "probing") {
+        return { status: "suspected-stall", runnerAlive: true };
+    }
+    if (activeNode.livenessStatus === "quiet") {
         return { status: "node-quiet", runnerAlive: true };
     }
+    // Fall back to meaningful progress clocks (never use runner lease as progress).
+    const meaningfulAt = activeNode.lastMeaningfulProgressAt
+        ?? activeNode.lastProviderActivityAt
+        ?? activeNode.lastToolActivityAt
+        ?? activeNode.lastOutputActivityAt
+        ?? activeNode.lastActivityAt
+        ?? activeNode.startedAt;
+    const nodeActivityMs = Date.parse(meaningfulAt ?? "");
+    if (!Number.isNaN(nodeActivityMs)) {
+        const idleMs = nowMs - nodeActivityMs;
+        const stallMs = input.nodeStallThresholdMs ?? 900_000;
+        const quietMs = input.nodeQuietThresholdMs ?? 300_000;
+        if (idleMs > stallMs) {
+            return { status: "suspected-stall", runnerAlive: true };
+        }
+        if (idleMs > quietMs) {
+            return { status: "node-quiet", runnerAlive: true };
+        }
+    }
     return { status: "active", runnerAlive: true };
 }
 export function deriveDagRunEffectiveStatus(input) {
@@ -210,6 +238,10 @@ export function deriveDagRunEffectiveStatus(input) {
     }
     if (input.liveness === "orphaned" || input.liveness === "stale")
         return "interrupted";
+    if (input.liveness === "needs-attention")
+        return "needs-attention";
+    if (input.liveness === "suspected-stall")
+        return "running-suspected-stall";
     if (input.liveness === "node-quiet")
         return "running-quiet";
     if (input.liveness === "unknown-host")
@@ -232,7 +264,15 @@ export function assessDagRunRecoveryEligibility(input) {
         reasons.push("run-already-terminal");
     }
     if (input.lifecycle === "active"
-        && ["active", "node-quiet", "stale", "unknown-host", "unknown"].includes(input.liveness)) {
+        && [
+            "active",
+            "node-quiet",
+            "suspected-stall",
+            "needs-attention",
+            "stale",
+            "unknown-host",
+            "unknown",
+        ].includes(input.liveness)) {
         canReconcile = false;
         reasons.push("runner-not-proven-dead-or-stopped");
     }
@@ -358,10 +398,26 @@ export async function detectDagRunHealthIssues(input) {
         issues.push({
             code: "node-activity-quiet",
             severity: "warning",
-            message: "Runner heartbeat is fresh but the current RUNNING node has produced no state activity for more than 5 minutes",
+            message: "Runner heartbeat is fresh but the current RUNNING node has produced no meaningful activity for more than 5 minutes",
             advisoryAction: "Inspect the node session events and executor logs before deciding whether to wait or abort.",
         });
     }
+    else if (liveness.status === "suspected-stall") {
+        issues.push({
+            code: "node-activity-suspected-stall",
+            severity: "warning",
+            message: "Runner heartbeat is fresh but the current RUNNING node has no meaningful Provider/tool/output activity for more than 15 minutes",
+            advisoryAction: "Treat as suspected network/provider stall; only retry read-only nodes after the attempt is proven finished. Writers must fail closed to reconcile.",
+        });
+    }
+    else if (liveness.status === "needs-attention") {
+        issues.push({
+            code: "node-needs-attention",
+            severity: "error",
+            message: "Runner or node process identity cannot be proven healthy, or absolute max wall clock was exceeded",
+            advisoryAction: "Do not forge timed-out/cancelled. Inspect process identity and artifacts; reconcile only when exit is proven.",
+        });
+    }
     if (lifecycle === "active" &&
         state.status === "running" &&
         state.humanDecisionNodeId) {

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

@@ -0,0 +1,250 @@
+import { z } from "zod";
+/**
+ * Adaptive liveness policy for DAG/Pi supervision.
+ *
+ * Four clocks must not be mixed:
+ * - runner lease (synthetic heartbeat) — not meaningful progress
+ * - provider/transport activity
+ * - tool activity
+ * - output / meaningful progress
+ */
+export const DEFAULT_LIVENESS_POLICY = {
+    heartbeatIntervalMs: 15_000,
+    runnerStaleMs: 90_000,
+    quietMs: 300_000,
+    stallProbeMs: 900_000,
+    abortGraceMs: 30_000,
+    /** 4h absolute max wall clock — cannot be renewed by empty heartbeats. */
+    absoluteMaxWallClockMs: 14_400_000,
+};
+export const dagLivenessPolicySchema = z
+    .object({
+    heartbeatIntervalMs: z.number().int().min(1_000).optional(),
+    runnerStaleMs: z.number().int().positive().optional(),
+    quietMs: z.number().int().positive().optional(),
+    stallProbeMs: z.number().int().positive().optional(),
+    abortGraceMs: z.number().int().positive().optional(),
+    absoluteMaxWallClockMs: z.number().int().positive().optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const resolved = { ...DEFAULT_LIVENESS_POLICY, ...value };
+    if (resolved.runnerStaleMs <= resolved.heartbeatIntervalMs) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["runnerStaleMs"],
+            message: "runnerStaleMs must be greater than heartbeatIntervalMs",
+        });
+    }
+    if (resolved.stallProbeMs <= resolved.quietMs) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["stallProbeMs"],
+            message: "stallProbeMs must be greater than quietMs",
+        });
+    }
+    if (resolved.absoluteMaxWallClockMs <= resolved.stallProbeMs) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["absoluteMaxWallClockMs"],
+            message: "absoluteMaxWallClockMs must be greater than stallProbeMs",
+        });
+    }
+})
+    .optional();
+/**
+ * Resolve policy from node/defaults partials. Missing fields use conservative defaults.
+ */
+export function resolveLivenessPolicy(...sources) {
+    const merged = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const key of Object.keys(DEFAULT_LIVENESS_POLICY)) {
+            const value = source[key];
+            if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+                merged[key] = Math.trunc(value);
+            }
+        }
+    }
+    return {
+        heartbeatIntervalMs: merged.heartbeatIntervalMs ?? DEFAULT_LIVENESS_POLICY.heartbeatIntervalMs,
+        runnerStaleMs: merged.runnerStaleMs ?? DEFAULT_LIVENESS_POLICY.runnerStaleMs,
+        quietMs: merged.quietMs ?? DEFAULT_LIVENESS_POLICY.quietMs,
+        stallProbeMs: merged.stallProbeMs ?? DEFAULT_LIVENESS_POLICY.stallProbeMs,
+        abortGraceMs: merged.abortGraceMs ?? DEFAULT_LIVENESS_POLICY.abortGraceMs,
+        absoluteMaxWallClockMs: merged.absoluteMaxWallClockMs ??
+            DEFAULT_LIVENESS_POLICY.absoluteMaxWallClockMs,
+    };
+}
+/**
+ * Synthetic timer heartbeats never count as meaningful Pi progress.
+ */
+export function isMeaningfulActivityKind(kind) {
+    return kind === "provider" || kind === "tool" || kind === "output";
+}
+/**
+ * Attempt fence: late activity from a previous attempt must not overwrite the current one.
+ */
+export function shouldAcceptActivity(currentAttempt, activityAttempt) {
+    if (!Number.isInteger(currentAttempt) || currentAttempt < 1)
+        return false;
+    if (!Number.isInteger(activityAttempt) || activityAttempt < 1)
+        return false;
+    return activityAttempt === currentAttempt;
+}
+export function classifySessionEventActivity(event) {
+    if (!event || typeof event !== "object")
+        return "provider";
+    const type = typeof event.type === "string"
+        ? String(event.type)
+        : "";
+    if (type === "tool_start" ||
+        type === "tool_end" ||
+        type === "tool_execution_start" ||
+        type === "tool_execution_end") {
+        return "tool";
+    }
+    if (type === "thinking_delta" || type === "message_update") {
+        // Noise — do not treat as progress when callers filter via shouldPersistSessionEvent.
+        return null;
+    }
+    return "provider";
+}
+function parseMs(value) {
+    if (!value)
+        return NaN;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : NaN;
+}
+function latestMeaningfulActivityMs(snapshot) {
+    const candidates = [
+        parseMs(snapshot.lastMeaningfulProgressAt),
+        parseMs(snapshot.lastProviderActivityAt),
+        parseMs(snapshot.lastToolActivityAt),
+        parseMs(snapshot.lastOutputActivityAt),
+        // Compatibility: lastActivityAt is treated as meaningful when richer clocks absent.
+        parseMs(snapshot.lastActivityAt),
+        parseMs(snapshot.startedAt),
+    ].filter((value) => !Number.isNaN(value));
+    if (candidates.length === 0)
+        return NaN;
+    return Math.max(...candidates);
+}
+/**
+ * Pure node liveness evaluator. No I/O.
+ *
+ * Transitions:
+ * - real provider/tool/output activity → active
+ * - no activity ≥ quietMs and runner lease fresh → quiet
+ * - no activity ≥ stallProbeMs → suspected-stall
+ * - probing flag → probing
+ * - identity mismatch / unprovable survival → needs-attention
+ * - wall clock ≥ absoluteMax → needs-attention (controlled abort path upstream)
+ */
+export function evaluateNodeLiveness(input) {
+    const policy = resolveLivenessPolicy(input.policy);
+    const nowMs = typeof input.now === "number"
+        ? input.now
+        : (input.now ?? new Date()).getTime();
+    const startedMs = parseMs(input.node.startedAt);
+    const wallClockMs = !Number.isNaN(startedMs)
+        ? Math.max(0, nowMs - startedMs)
+        : 0;
+    const exceededAbsoluteMax = wallClockMs >= policy.absoluteMaxWallClockMs;
+    if (input.node.needsAttentionReason || exceededAbsoluteMax) {
+        return {
+            status: "needs-attention",
+            lastMeaningfulProgressAt: input.node.lastMeaningfulProgressAt ?? input.node.lastActivityAt,
+            idleMs: 0,
+            wallClockMs,
+            exceededAbsoluteMax,
+        };
+    }
+    if (input.node.probing) {
+        return {
+            status: "probing",
+            lastMeaningfulProgressAt: input.node.lastMeaningfulProgressAt ?? input.node.lastActivityAt,
+            idleMs: 0,
+            wallClockMs,
+            exceededAbsoluteMax,
+        };
+    }
+    const meaningfulMs = latestMeaningfulActivityMs(input.node);
+    const idleMs = !Number.isNaN(meaningfulMs)
+        ? Math.max(0, nowMs - meaningfulMs)
+        : wallClockMs;
+    const leaseFresh = input.runnerLeaseFresh ??
+        (() => {
+            const heartbeatMs = parseMs(input.runnerHeartbeatAt);
+            if (Number.isNaN(heartbeatMs))
+                return true;
+            return nowMs - heartbeatMs <= policy.runnerStaleMs;
+        })();
+    if (idleMs >= policy.stallProbeMs) {
+        return {
+            status: "suspected-stall",
+            lastMeaningfulProgressAt: input.node.lastMeaningfulProgressAt ?? input.node.lastActivityAt,
+            idleMs,
+            wallClockMs,
+            exceededAbsoluteMax,
+        };
+    }
+    if (idleMs >= policy.quietMs && leaseFresh) {
+        return {
+            status: "quiet",
+            lastMeaningfulProgressAt: input.node.lastMeaningfulProgressAt ?? input.node.lastActivityAt,
+            idleMs,
+            wallClockMs,
+            exceededAbsoluteMax,
+        };
+    }
+    // Active tool presence keeps us from escalating beyond quiet solely on idle output.
+    if ((input.node.activeToolCount ?? 0) > 0 && idleMs < policy.stallProbeMs) {
+        return {
+            status: idleMs >= policy.quietMs ? "quiet" : "active",
+            lastMeaningfulProgressAt: input.node.lastMeaningfulProgressAt ?? input.node.lastActivityAt,
+            idleMs,
+            wallClockMs,
+            exceededAbsoluteMax,
+        };
+    }
+    return {
+        status: "active",
+        lastMeaningfulProgressAt: input.node.lastMeaningfulProgressAt ?? input.node.lastActivityAt,
+        idleMs,
+        wallClockMs,
+        exceededAbsoluteMax,
+    };
+}
+/**
+ * Apply a fenced activity event onto a mutable node snapshot (pure field updates).
+ * Returns whether the write was accepted.
+ */
+export function applyNodeActivity(input) {
+    if (!shouldAcceptActivity(input.currentAttempt, input.activityAttempt)) {
+        return false;
+    }
+    const at = input.at ?? new Date().toISOString();
+    if (input.kind === "lease" || input.kind === "synthetic-heartbeat") {
+        input.node.lastLeaseAt = at;
+        // Never treat synthetic lease as meaningful progress.
+        return true;
+    }
+    if (!isMeaningfulActivityKind(input.kind)) {
+        return false;
+    }
+    if (input.kind === "provider") {
+        input.node.lastProviderActivityAt = at;
+    }
+    else if (input.kind === "tool") {
+        input.node.lastToolActivityAt = at;
+    }
+    else if (input.kind === "output") {
+        input.node.lastOutputActivityAt = at;
+    }
+    input.node.lastMeaningfulProgressAt = at;
+    input.node.lastActivityAt = at;
+    input.node.livenessStatus = "active";
+    return true;
+}

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

@@ -8,6 +8,8 @@ import { resolveContextPolicy } from "./context-policy.js";
 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 { 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";
@@ -25,9 +27,19 @@ export function buildNodePrompt(spec, task, upstream, options) {
         projectGovernanceContext: options?.projectGovernanceContext,
     });
 }
-function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory) {
-    if (attemptNumber <= 1 ||
-        task.outputMode !== "structured-required" ||
+function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason) {
+    if (attemptNumber <= 1)
+        return basePrompt;
+    if (previousFailureCategory === "protocol-invalid" &&
+        task.outputProtocol &&
+        previousProtocolReason) {
+        return [
+            basePrompt,
+            "",
+            buildProtocolRetryInstruction(task.outputProtocol, previousProtocolReason),
+        ].join("\n");
+    }
+    if (task.outputMode !== "structured-required" ||
         previousFailureCategory !== "output-too-large") {
         return basePrompt;
     }
@@ -224,6 +236,9 @@ export async function executeDagNode(input) {
     node.status = "RUNNING";
     node.startedAt = new Date().toISOString();
     node.lastActivityAt = node.startedAt;
+    node.lastMeaningfulProgressAt = node.startedAt;
+    node.livenessStatus = "active";
+    node.currentAttempt = 1;
     if (task.shell?.verifyEvidence) {
         node.verifyEvidence = task.shell.verifyEvidence;
     }
@@ -299,11 +314,48 @@ export async function executeDagNode(input) {
     const maxAttempts = retryPolicy?.maxAttempts ?? 1;
     const attempts = [];
     let totalBackoffMs = 0;
+    const livenessPolicy = resolveLivenessPolicy(spec.defaults?.livenessPolicy, task.livenessPolicy);
+    /**
+     * Attempt-fenced, throttled activity sink. Late events from a previous
+     * attempt are no-ops. Persistence is best-effort and never throws to the
+     * executor path.
+     */
+    const ACTIVITY_PERSIST_MIN_INTERVAL_MS = 2_000;
+    let lastActivityPersistMs = 0;
+    const reportActivity = (activity) => {
+        const accepted = applyNodeActivity({
+            node,
+            currentAttempt: node.currentAttempt ?? 1,
+            activityAttempt: activity.attempt,
+            kind: activity.kind,
+            at: activity.at,
+        });
+        if (!accepted)
+            return;
+        const evaluation = evaluateNodeLiveness({
+            node,
+            policy: livenessPolicy,
+            runnerHeartbeatAt: state.runner?.heartbeatAt,
+        });
+        node.livenessStatus = evaluation.status;
+        const nowMs = Date.now();
+        if (nowMs - lastActivityPersistMs < ACTIVITY_PERSIST_MIN_INTERVAL_MS) {
+            return;
+        }
+        lastActivityPersistMs = nowMs;
+        // Canonical mid-call activity lives in active state.json. Queue through the
+        // runner's serialized state writer; per-node records remain terminal/attempt
+        // evidence so a late best-effort write cannot recreate an archived run dir.
+        void input.persistState().catch(() => { });
+    };
     let terminalResult;
     let previousFailureCategory;
+    let previousProtocolReason;
     for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
         const attemptStartedAt = new Date().toISOString();
         const attemptStarted = Date.now();
+        node.currentAttempt = attemptNumber;
+        node.livenessStatus = "active";
         let result;
         try {
             validateRepairArtifactGateBeforeShell({
@@ -315,7 +367,12 @@ export async function executeDagNode(input) {
                 task,
                 cwd,
                 model,
-                prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory),
+                prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason),
+                attempt: attemptNumber,
+                reportActivity,
+                timeoutMs: livenessPolicy.absoluteMaxWallClockMs,
+                stallTimeoutMs: livenessPolicy.stallProbeMs,
+                abortGraceMs: livenessPolicy.abortGraceMs,
             });
         }
         catch (error) {
@@ -326,6 +383,26 @@ export async function executeDagNode(input) {
                 durationMs: Date.now() - attemptStarted,
             };
         }
+        // R0: executor ok=true still fails closed when outputProtocol is violated.
+        // Valid semantic results (e.g. VERDICT: request-revision) pass validation.
+        if (result.ok && task.outputProtocol) {
+            const protocolText = `${result.assistantText ?? ""}\n${result.stdout ?? ""}`;
+            const protocolCheck = validateOutputProtocol(task.outputProtocol, protocolText);
+            if (!protocolCheck.ok) {
+                result = {
+                    ...result,
+                    ok: false,
+                    failureCategory: protocolCheck.failureCategory,
+                    stderr: [result.stderr, protocolCheck.reason]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+                previousProtocolReason = protocolCheck.reason;
+            }
+            else {
+                previousProtocolReason = undefined;
+            }
+        }
         const attemptFinishedAt = new Date().toISOString();
         const attemptRecord = {
             attempt: attemptNumber,
@@ -373,6 +450,10 @@ export async function executeDagNode(input) {
                 ? result.parsedEvents
                 : sumAttemptMetric(attempts, (attempt) => attempt.parsedEvents);
         node.lastActivityAt = attemptFinishedAt;
+        if (result.failureCategory === "termination-unconfirmed") {
+            node.needsAttentionReason = "attempt-termination-unconfirmed";
+            node.livenessStatus = "needs-attention";
+        }
         if (retryPolicy !== undefined) {
             state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
             await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
@@ -384,9 +465,11 @@ export async function executeDagNode(input) {
             break;
         const canRetry = retryPolicy !== undefined && attemptNumber < maxAttempts;
         const retryable = retryPolicy !== undefined &&
-            isRetryablePiFailureCategory(result.failureCategory, {
+            (isRetryablePiFailureCategory(result.failureCategory, {
                 retryCategories: retryPolicy.retryCategories,
-            });
+            }) ||
+                (result.failureCategory === "protocol-invalid" &&
+                    task.outputProtocol?.retryOnInvalid === true));
         if (!canRetry || !retryable)
             break;
         const delayMs = computeBackoffDelayMs(attemptNumber + 1, retryPolicy);

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

@@ -0,0 +1,76 @@
+import { z } from "zod";
+/**
+ * Machine-readable output protocol for safe read-only Pi nodes.
+ *
+ * Phase 1 only supports first-line-enum (e.g. VERDICT lines). Structured JSON
+ * continues to use existing structured-required / deterministic gates.
+ */
+export const dagOutputProtocolSchema = z
+    .object({
+    type: z.literal("first-line-enum"),
+    validLines: z.array(z.string().min(1)).min(1),
+    retryOnInvalid: z.boolean().default(true),
+})
+    .strict();
+/** Reviewer VERDICT protocol used by reviewed/supervised DAGs. */
+export const REVIEW_VERDICT_OUTPUT_PROTOCOL = {
+    type: "first-line-enum",
+    validLines: ["VERDICT: pass", "VERDICT: request-revision"],
+    retryOnInvalid: true,
+};
+/**
+ * Extract the first non-empty line from assistant/stdout text.
+ */
+export function firstNonEmptyLine(text) {
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+/**
+ * Validate node output against an explicit outputProtocol.
+ * Pure function — does not mutate run facts.
+ */
+export function validateOutputProtocol(protocol, text) {
+    if (protocol.type !== "first-line-enum") {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `unsupported outputProtocol.type: ${protocol.type ?? "unknown"}`,
+        };
+    }
+    const first = firstNonEmptyLine(text);
+    if (!first) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `missing first non-empty line; expected one of: ${protocol.validLines.map((l) => JSON.stringify(l)).join(" or ")}`,
+        };
+    }
+    if (!protocol.validLines.includes(first)) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `first non-empty line ${JSON.stringify(first)} is not a valid protocol line; expected one of: ${protocol.validLines.map((l) => JSON.stringify(l)).join(" or ")}`,
+            firstNonEmptyLine: first,
+        };
+    }
+    return { ok: true, matchedLine: first };
+}
+/**
+ * Correction instruction appended on protocol-invalid retry attempts.
+ */
+export function buildProtocolRetryInstruction(protocol, reason) {
+    const expected = protocol.validLines
+        .map((line) => JSON.stringify(line))
+        .join(" or ");
+    return [
+        "<retry_instruction>",
+        "Previous attempt violated the output protocol:",
+        reason,
+        `Return one valid protocol line before any explanation. Expected first non-empty line: ${expected}.`,
+        "</retry_instruction>",
+    ].join("\n");
+}