@tea-agent/loop-agent 0.1.0-fe-test.0

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

@@ -0,0 +1,329 @@
+export const DAG_RECOVERY_ACTIONS = [
+    "none",
+    "monitor",
+    "retry-node",
+    "rerun-after-fix",
+    "resume-or-reject",
+    "manual-review",
+    "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",
+    "quota",
+    "rate-limit",
+    "unavailable",
+]);
+function isInProgressStatus(status) {
+    return (status === "PENDING" ||
+        status === "RUNNING" ||
+        status === "pending" ||
+        status === "running");
+}
+function isPausedRunStatus(status) {
+    return status === "paused";
+}
+function executorAction(raw) {
+    if (raw !== undefined && TRANSIENT_EXECUTOR_RAW.has(raw)) {
+        return "retry-node";
+    }
+    return "rerun-after-fix";
+}
+function writeGuardAction(raw) {
+    if (raw === "write-guard") {
+        return "manual-review";
+    }
+    return "manual-review";
+}
+function isPausedContext(status, lifecycle, runStatus) {
+    return (isPausedRunStatus(status) ||
+        runStatus === "paused" ||
+        lifecycle === "paused");
+}
+function decisionEnvelopeAction(status, lifecycle, runStatus) {
+    if (isPausedContext(status, lifecycle, runStatus)) {
+        return "resume-or-reject";
+    }
+    return "manual-review";
+}
+function planByNormalizedCategory(input) {
+    const { status, normalizedFailureCategory: category, failureCategory: raw, nodeId, runId, lifecycle, runStatus, } = input;
+    const target = nodeId ?? runId ?? "run";
+    switch (category) {
+        case "success":
+            return {
+                action: "none",
+                summary: "No recovery needed.",
+                reason: `${target} finished successfully.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "skipped":
+            return {
+                action: "inspect-upstream",
+                summary: "Inspect upstream failures before retrying downstream nodes.",
+                reason: `${target} was skipped because an upstream dependency failed or was rejected.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Resolve upstream ERROR/SKIPPED nodes first; do not auto-retry skipped nodes until upstream is fixed.",
+            };
+        case "timeout":
+            return {
+                action: "retry-node",
+                summary: `Retry ${target} after confirming the timeout was transient.`,
+                reason: `${target} exceeded its execution time limit${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: true,
+                commandHint: `Investigate logs/artifacts, then re-run ${target}. ${REPORT_DERIVED_ONLY}`,
+            };
+        case "executor":
+            return {
+                action: executorAction(raw),
+                summary: executorAction(raw) === "retry-node"
+                    ? `Retry ${target} if the executor/backend error looks transient.`
+                    : `Fix executor/backend conditions, then re-run ${target}.`,
+                reason: `${target} failed in the executor layer${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: executorAction(raw) === "retry-node",
+                commandHint: executorAction(raw) === "retry-node"
+                    ? `Retry ${target} once transient network/quota/rate-limit issues clear. ${REPORT_DERIVED_ONLY}`
+                    : `Inspect backend logs and node artifacts before re-running ${target}. ${REPORT_DERIVED_ONLY}`,
+            };
+        case "auth":
+            return {
+                action: "rerun-after-fix",
+                summary: "Fix credentials/API keys, then re-run the affected node or DAG.",
+                reason: `${target} failed due to missing or invalid auth${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Update API keys/credentials in the environment or repo config, then re-run.",
+            };
+        case "write-guard":
+            return {
+                action: writeGuardAction(raw),
+                summary: "Review writeSet/writePolicy and approve or adjust writes before re-run.",
+                reason: `${target} was blocked by the write guard${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Inspect writeSet/writePolicy, node prompt, and result.summary.md; revise policy or scope before re-run.",
+            };
+        case "validation":
+            return {
+                action: "rerun-after-fix",
+                summary: "Fix schema/output/test validation issues, then re-run the node.",
+                reason: `${target} produced invalid or unverifiable output${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Inspect schema/output/tests and node artifacts; correct the underlying issue before re-run.",
+            };
+        case "shell-command":
+            return {
+                action: "rerun-after-fix",
+                summary: "Inspect shell output/result.summary.md, fix the command, then re-run.",
+                reason: `${target} shell command failed${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Review shell stdout/stderr and result.summary.md; adjust shell config or repo state before re-run.",
+            };
+        case "static-error":
+            return {
+                action: "rerun-after-fix",
+                summary: "Inspect static executor config/output, then re-run the node.",
+                reason: `${target} static executor reported an error${raw ? ` (${raw})` : ""}.`,
+                humanRequired: false,
+                autoRetryEligible: false,
+                commandHint: "Review static executor configuration and emitted markdown before re-run.",
+            };
+        case "decision-envelope":
+            return {
+                action: decisionEnvelopeAction(status, lifecycle, runStatus),
+                summary: decisionEnvelopeAction(status, lifecycle, runStatus) ===
+                    "resume-or-reject"
+                    ? "Resume after human approval or reject the paused run."
+                    : "Manually review the decision envelope before continuing.",
+                reason: `${target} requires decision-gate review${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: decisionEnvelopeAction(status, lifecycle, runStatus) ===
+                    "resume-or-reject"
+                    ? "Use dag approve / dag reject, then dag resume when approved."
+                    : "Inspect decision.envelope.json and human-escalation artifacts.",
+            };
+        case "human-required": {
+            const action = isPausedContext(status, lifecycle, runStatus)
+                ? "resume-or-reject"
+                : "manual-review";
+            return {
+                action,
+                summary: action === "resume-or-reject"
+                    ? "Provide human input, then resume or reject the paused run."
+                    : "Provide human input before choosing the next recovery action.",
+                reason: `${target} is waiting for human escalation${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: action === "resume-or-reject"
+                    ? "Use dag approve / dag reject, then dag resume when approved."
+                    : "Inspect human-escalation artifacts and update the run/task contract before continuing.",
+            };
+        }
+        case "human-rejected":
+            return {
+                action: "manual-review",
+                summary: "Revise contract/source or escalation options before any retry.",
+                reason: `${target} was human-rejected${raw ? ` (${raw})` : ""}; automatic retry is not recommended.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Review human-rejection.json and update the DAG/task contract before starting a new run.",
+            };
+        case "unknown":
+            return {
+                action: "manual-review",
+                summary: "Manually inspect failure artifacts; no automatic retry recommended.",
+                reason: `${target} failed with an unclassified category${raw ? ` (${raw})` : ""}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Inspect node artifacts, executor.jsonl, and state.json before choosing a recovery path.",
+            };
+        default: {
+            const exhaustive = category;
+            return {
+                action: "unknown",
+                summary: "Unknown recovery path.",
+                reason: `Unhandled normalized category: ${exhaustive}.`,
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        }
+    }
+}
+export function planDagRecovery(input) {
+    if (isInProgressStatus(input.status)) {
+        return {
+            action: "monitor",
+            summary: "Monitor the in-progress run; no recovery action yet.",
+            reason: `${input.nodeId ?? input.runId ?? "Run"} is still ${input.status.toLowerCase()}.`,
+            humanRequired: false,
+            autoRetryEligible: false,
+            commandHint: "Wait for the node/run to finish or pause before planning recovery.",
+        };
+    }
+    if (isPausedRunStatus(input.status)) {
+        const pausedRecommendation = planByNormalizedCategory(input);
+        if (pausedRecommendation.action === "none") {
+            return {
+                action: "resume-or-reject",
+                summary: "Resume after review or reject the paused run.",
+                reason: "Run is paused and awaiting human decision.",
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "Use dag approve / dag reject, then dag resume when approved.",
+            };
+        }
+        return pausedRecommendation;
+    }
+    return planByNormalizedCategory(input);
+}
+/**
+ * Phase 6: route a frontend recovery outcome to a recovery CTA (read-only; never
+ * mutates a run's status). The six outcomes map to the existing recovery actions
+ * so the Console recovery page reuses the current CTA surface.
+ */
+export function recommendFrontendRecoveryOutcome(outcome) {
+    switch (outcome) {
+        case "none":
+            return {
+                action: "none",
+                summary: "未发生前端恢复；按普通终态展示。",
+                reason: "该 frontend-implementation 根没有触发自动恢复。",
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "recovered":
+            return {
+                action: "none",
+                summary: "自动恢复成功；child 已重新实现并通过验证。",
+                reason: "parent 的 transient 失败已由 child 恢复，全链按 root 计一次成功。",
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "candidate-contract-invalid":
+            return {
+                action: "manual-review",
+                summary: "方案输出无效：candidate JSON 无法解析/推导，重试用尽。",
+                reason: "建议人工检查需求或重新生成方案后再跑。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        case "prewrite-blocked":
+            return {
+                action: "manual-review",
+                summary: "治理门禁阻断：source stale / writeSet 越界 / Mock policy / contract 违规。",
+                reason: "需人工修正任务边界/事实后重跑，不自动重试。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        case "repair-exhausted":
+            return {
+                action: "rerun-after-fix",
+                summary: "自动修复未通过：verify 失败，1 次 repair 后 reverify 仍失败。",
+                reason: "建议 `dag rerun` 或人工排查。",
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "loop-agent dag rerun --run-id <runId>",
+            };
+        case "auto-recovery-blocked":
+            return {
+                action: "manual-review",
+                summary: "自动恢复被阻止：rollback 无法证明完整或存在外部/越界修改。",
+                reason: "必须人工介入，禁止自动覆盖用户文件。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+    }
+}

package/dist/workflows/dag/repair-artifact.js

@@ -0,0 +1,363 @@
+import { z } from "zod";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
+export const repairFailureClassSchema = z.enum([
+    "syntax",
+    "runtime",
+    "logic",
+    "boundary",
+    "environment",
+    "governance",
+    "unknown",
+]);
+export const repairDispositionSchema = z.enum([
+    "repairable",
+    "blocked-boundary",
+    "no-op-pass",
+]);
+export const repairArtifactSchema = z.object({
+    schemaVersion: z.literal(1),
+    verdict: z.enum(["pass", "request-revision"]),
+    failureClass: repairFailureClassSchema,
+    rootCause: z.string().min(1, {
+        message: 'repair artifact field "rootCause" must be a non-empty string',
+    }),
+    fixScope: z.array(z.string().min(1)).default([]),
+    invariant: z.string().min(1),
+    evidenceRefs: z.array(z.string().min(1)).default([]),
+    rawLogFallbackAllowed: z.boolean().default(false),
+    /**
+     * Optional disposition for convergence routing. Omitted values are treated as
+     * `repairable` for backward compatibility with older artifacts.
+     */
+    disposition: repairDispositionSchema.optional(),
+    /**
+     * Report-only out-of-boundary paths. Never expands write authority.
+     */
+    requiredScope: z.array(z.string().min(1)).optional(),
+});
+/**
+ * Canonical rootCause substituted when a `verdict: "pass"` repair artifact
+ * arrives with an empty or whitespace-only rootCause. Keeps the persisted
+ * RepairArtifact schema-valid without weakening request-revision diagnostics.
+ */
+export const PASS_VERDICT_DEFAULT_ROOT_CAUSE = "No repair required.";
+/**
+ * Normalize model-emitted repair artifacts deterministically at the parser
+ * boundary: a `verdict: "pass"` artifact with an empty/whitespace-only
+ * rootCause is rewritten to the canonical default so it still satisfies the
+ * strict schema. request-revision and other fields are left untouched so the
+ * strict diagnostics and write boundaries remain fail-closed.
+ */
+function normalizePassArtifactRootCause(parsed) {
+    if (parsed &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed) &&
+        parsed.verdict === "pass") {
+        const record = parsed;
+        const rootCause = record.rootCause;
+        if (typeof rootCause === "string" && rootCause.trim().length === 0) {
+            return { ...record, rootCause: PASS_VERDICT_DEFAULT_ROOT_CAUSE };
+        }
+    }
+    return parsed;
+}
+/**
+ * Render a single Zod issue as a field-path-aware message so callers can locate
+ * invalid repair-artifact fields instead of seeing bare min-length text.
+ */
+function describeZodIssue(issue) {
+    const path = issue.path && issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    if (issue.message && !/^String must contain/.test(issue.message)) {
+        return `field "${path}": ${issue.message} (code ${issue.code})`;
+    }
+    return `field "${path}" is invalid (code ${issue.code})`;
+}
+const REPAIR_ARTIFACT_FENCE = /```(?:REPAIR_ARTIFACT_JSON|json)\s*([\s\S]*?)```/gi;
+function extractCandidateJsonBlocks(text) {
+    const blocks = [];
+    for (const match of text.matchAll(REPAIR_ARTIFACT_FENCE)) {
+        const candidate = match[1]?.trim();
+        if (candidate)
+            blocks.push(candidate);
+    }
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        blocks.push(trimmed);
+    }
+    return blocks;
+}
+export function parseRepairArtifactFromText(text) {
+    const candidates = extractCandidateJsonBlocks(text);
+    if (candidates.length === 0) {
+        return { ok: false, reason: "missing REPAIR_ARTIFACT_JSON fenced block" };
+    }
+    const errors = [];
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            const normalized = normalizePassArtifactRootCause(parsed);
+            const result = repairArtifactSchema.safeParse(normalized);
+            if (result.success) {
+                return { ok: true, artifact: result.data };
+            }
+            errors.push(result.error.issues.map((issue) => describeZodIssue(issue)).join(", "));
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return {
+        ok: false,
+        reason: `invalid repair artifact JSON: ${errors.join("; ")}`,
+    };
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isPathLikeScope(scope) {
+    const normalized = normalizePath(scope);
+    if (normalized === "none")
+        return false;
+    if (normalized === "." || normalized === "**" || normalized === "/*")
+        return false;
+    return (normalized.includes("/") ||
+        /\.(ts|tsx|js|jsx|mjs|cjs|json|md|sh|yml|yaml)$/.test(normalized));
+}
+function scopeWithinPatterns(scope, patterns) {
+    if (patterns.length === 0)
+        return true;
+    const normalized = normalizePath(scope);
+    return patterns.some((pattern) => pathMatchesPattern(normalized, pattern));
+}
+export function validateRepairArtifactScope(input) {
+    const { artifact, repairTask } = input;
+    const disposition = artifact.disposition ?? "repairable";
+    const requiredScope = artifact.requiredScope ?? [];
+    for (const scope of requiredScope) {
+        if (!isPathLikeScope(scope)) {
+            return {
+                ok: false,
+                reason: `requiredScope "${scope}" must be a concrete path or glob (report-only; does not expand write authority)`,
+            };
+        }
+    }
+    if (artifact.verdict === "pass") {
+        if (disposition === "blocked-boundary") {
+            return {
+                ok: false,
+                reason: "pass repair artifact cannot use blocked-boundary disposition",
+            };
+        }
+        if (artifact.fixScope.length > 0) {
+            return {
+                ok: false,
+                reason: "pass repair artifact requires empty fixScope",
+            };
+        }
+        return { ok: true, artifact };
+    }
+    if (disposition === "no-op-pass") {
+        return {
+            ok: false,
+            reason: "request-revision repair artifact cannot use no-op-pass disposition",
+        };
+    }
+    // blocked-boundary may report empty fixScope (nothing in-boundary to fix)
+    // while requiredScope describes the out-of-boundary need.
+    if (disposition === "blocked-boundary") {
+        if (requiredScope.length === 0) {
+            return {
+                ok: false,
+                reason: "blocked-boundary request-revision requires non-empty requiredScope (report-only)",
+            };
+        }
+        if (!repairTask) {
+            return {
+                ok: false,
+                reason: "repair artifact gate cannot find downstream repair task",
+            };
+        }
+        const allowed = repairTask.allowedPaths ?? [];
+        const writeSet = repairTask.writeSet ?? [];
+        const forbidden = repairTask.forbiddenPaths ?? [];
+        const hasOutOfBoundaryRequiredScope = requiredScope.some((scope) => {
+            const normalized = normalizePath(scope);
+            return (!scopeWithinPatterns(scope, allowed) ||
+                !scopeWithinPatterns(scope, writeSet) ||
+                forbidden.some((pattern) => pathMatchesPattern(normalized, pattern)));
+        });
+        if (!hasOutOfBoundaryRequiredScope) {
+            return {
+                ok: false,
+                reason: "blocked-boundary requiredScope must include a path outside repair task allowedPaths/writeSet",
+            };
+        }
+        if (artifact.fixScope.length > 0) {
+            for (const scope of artifact.fixScope) {
+                if (!isPathLikeScope(scope)) {
+                    return {
+                        ok: false,
+                        reason: `fixScope "${scope}" must be a concrete path or glob inside repair task allowedPaths/writeSet`,
+                    };
+                }
+                if (!scopeWithinPatterns(scope, allowed) ||
+                    !scopeWithinPatterns(scope, writeSet)) {
+                    return {
+                        ok: false,
+                        reason: `fixScope "${scope}" is outside repair task allowedPaths/writeSet`,
+                    };
+                }
+                if (forbidden.some((pattern) => pathMatchesPattern(normalizePath(scope), pattern))) {
+                    return {
+                        ok: false,
+                        reason: `fixScope "${scope}" matches repair task forbiddenPaths`,
+                    };
+                }
+            }
+        }
+        return { ok: true, artifact };
+    }
+    if (artifact.fixScope.length === 0) {
+        return {
+            ok: false,
+            reason: "request-revision repair artifact requires non-empty fixScope",
+        };
+    }
+    if (!repairTask) {
+        return {
+            ok: false,
+            reason: "repair artifact gate cannot find downstream repair task",
+        };
+    }
+    const allowed = repairTask.allowedPaths ?? [];
+    const writeSet = repairTask.writeSet ?? [];
+    const forbidden = repairTask.forbiddenPaths ?? [];
+    for (const scope of artifact.fixScope) {
+        if (!isPathLikeScope(scope)) {
+            return {
+                ok: false,
+                reason: `fixScope "${scope}" must be a concrete path or glob inside repair task allowedPaths/writeSet`,
+            };
+        }
+        if (!scopeWithinPatterns(scope, allowed) ||
+            !scopeWithinPatterns(scope, writeSet)) {
+            return {
+                ok: false,
+                reason: `fixScope "${scope}" is outside repair task allowedPaths/writeSet`,
+            };
+        }
+        if (forbidden.some((pattern) => pathMatchesPattern(normalizePath(scope), pattern))) {
+            return {
+                ok: false,
+                reason: `fixScope "${scope}" matches repair task forbiddenPaths`,
+            };
+        }
+    }
+    return { ok: true, artifact };
+}
+/**
+ * Return the list of governed-writer contract violations for a candidate repair
+ * node. An empty array means the node is a governed Pi writer eligible to
+ * receive a structured repair artifact.
+ */
+export function repairWriterContractIssues(task) {
+    const issues = [];
+    if (task.executor !== "pi") {
+        issues.push(`executor must be pi (got ${task.executor ?? "unset"})`);
+    }
+    if (task.toolProfile !== "write") {
+        issues.push(`toolProfile must be write (got ${task.toolProfile ?? "unset"})`);
+    }
+    if (task.writePolicy !== "exclusive") {
+        issues.push(`writePolicy must be exclusive (got ${task.writePolicy ?? "unset"})`);
+    }
+    const allowed = task.allowedPaths ?? [];
+    const writeSet = task.writeSet ?? [];
+    const forbidden = task.forbiddenPaths ?? [];
+    if (allowed.length === 0) {
+        issues.push("allowedPaths must be non-empty");
+    }
+    if (writeSet.length === 0) {
+        issues.push("writeSet must be non-empty");
+    }
+    for (const entry of writeSet) {
+        const normalized = normalizePath(entry);
+        if (forbidden.some((pattern) => pathMatchesPattern(normalized, pattern))) {
+            issues.push(`writeSet entry "${entry}" conflicts with forbiddenPaths`);
+        }
+    }
+    return issues;
+}
+export function isGovernedRepairWriter(task) {
+    return repairWriterContractIssues(task).length === 0;
+}
+/**
+ * Resolve the repair writer a repair-artifact gate feeds, using the explicit
+ * `repairNodeId` reference when present and otherwise deriving a unique safe
+ * downstream Pi writer. Never guesses by node name.
+ */
+export function resolveRepairTaskForGate(input) {
+    const gate = input.gateTask.shell?.repairArtifactGate;
+    if (!gate) {
+        return {
+            ok: false,
+            reason: `task ${input.gateTask.id} has no repairArtifactGate`,
+        };
+    }
+    const directDownstream = input.tasks.filter((task) => task.depends_on.includes(input.gateTask.id));
+    if (gate.repairNodeId) {
+        const declared = input.tasks.find((task) => task.id === gate.repairNodeId);
+        if (!declared) {
+            return {
+                ok: false,
+                reason: `repair artifact gate "${input.gateTask.id}" declares repairNodeId "${gate.repairNodeId}" but no task with that id exists`,
+            };
+        }
+        if (!declared.depends_on.includes(input.gateTask.id)) {
+            return {
+                ok: false,
+                reason: `repair node "${declared.id}" declared by gate "${input.gateTask.id}" must depend_on the gate`,
+            };
+        }
+        const issues = repairWriterContractIssues(declared);
+        if (issues.length > 0) {
+            return {
+                ok: false,
+                reason: `repair node "${declared.id}" declared by gate "${input.gateTask.id}" is not a governed Pi writer: ${issues.join("; ")}`,
+            };
+        }
+        return { ok: true, repairTask: declared };
+    }
+    const candidates = directDownstream.filter(isGovernedRepairWriter);
+    if (candidates.length === 1) {
+        return { ok: true, repairTask: candidates[0] };
+    }
+    const candidateIds = directDownstream.map((task) => task.id).join(", ") || "none";
+    if (candidates.length === 0) {
+        return {
+            ok: false,
+            reason: `repair artifact gate "${input.gateTask.id}" has no repairNodeId and no unique governed Pi writer among direct downstream nodes (${candidateIds}); regenerate the DAG with an explicit repairNodeId`,
+        };
+    }
+    return {
+        ok: false,
+        reason: `repair artifact gate "${input.gateTask.id}" has no repairNodeId and multiple governed Pi writer candidates downstream (${candidates
+            .map((task) => task.id)
+            .join(", ")}); declare repairNodeId to disambiguate`,
+    };
+}
+export function formatRepairArtifactForPrompt(artifact) {
+    const disposition = artifact.disposition ?? "repairable";
+    const requiredScope = artifact.requiredScope ?? [];
+    return [
+        "Repair artifact:",
+        `- verdict: ${artifact.verdict}`,
+        `- failureClass: ${artifact.failureClass}`,
+        `- rootCause: ${artifact.rootCause}`,
+        `- disposition: ${disposition}`,
+        `- fixScope: ${artifact.fixScope.length > 0 ? artifact.fixScope.join(", ") : "(none)"}`,
+        `- requiredScope: ${requiredScope.length > 0 ? requiredScope.join(", ") : "(none)"}`,
+        `- invariant: ${artifact.invariant}`,
+        `- evidenceRefs: ${artifact.evidenceRefs.length > 0 ? artifact.evidenceRefs.join(", ") : "(none)"}`,
+    ].join("\n");
+}