@tea-agent/loop-agent 0.11.0 → 0.12.0

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

@@ -123,6 +123,97 @@ export function validateRepairArtifactScope(input) {
     }
     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) {
     return [
         "Repair artifact:",

package/dist/workflows/dag/report.js

@@ -10,6 +10,7 @@ import { dagNormalizedFailureCategorySchema, normalizeDagFailureCategory, } from
 import { dagProductLineFailureCategoryValues, routeDagFailure, } from "./failure-routing.js";
 import { DAG_RECOVERY_ACTIONS, planDagRecovery, } 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;
 export const DAG_REPORT_SCHEMA_RELATIVE_PATH = "docs/templates/agent-dag-report.schema.json";
 const dagRunLifecycleSchema = z.enum(["active", "paused", "completed"]);
@@ -169,6 +170,22 @@ const dagRunReportEntrySchema = z
     convergence: dagConvergenceReportSchema.optional(),
     pausedByNodeId: z.string().optional(),
     pauseReason: z.string().optional(),
+    controllerIdentity: z
+        .object({
+        status: z.enum(["pinned", "legacy-unpinned"]),
+        capturedAt: z.string().min(1),
+        packageName: z.string().optional(),
+        packageVersion: z.string().optional(),
+        packageFingerprint: z.string().optional(),
+        binarySha256: z.string().optional(),
+        runtimeContractCompatibility: z.enum([
+            "compatible",
+            "incompatible",
+            "legacy-unspecified",
+        ]),
+        runtimeContractReason: z.string().optional(),
+    })
+        .optional(),
     executorJsonl: dagArtifactRefSchema,
     nodes: z.array(dagNodeReportRowSchema),
 })
@@ -291,6 +308,38 @@ function resolvePrimaryRecovery(run, primaryNode) {
         autoRetryEligible: false,
     };
 }
+function summarizeControllerIdentityForReport(ref, spec) {
+    if (!ref)
+        return {};
+    const compatibility = spec.runtimeContract
+        ? checkRuntimeContractCompatible(spec.runtimeContract, {
+            ...DAG_CONTROLLER_CAPABILITIES,
+            ...(ref.packageVersion
+                ? { controllerVersion: ref.packageVersion }
+                : {}),
+        })
+        : { ok: true };
+    return {
+        controllerIdentity: {
+            status: ref.status,
+            capturedAt: ref.capturedAt,
+            ...(ref.packageName ? { packageName: ref.packageName } : {}),
+            ...(ref.packageVersion ? { packageVersion: ref.packageVersion } : {}),
+            ...(ref.packageFingerprint
+                ? { packageFingerprint: ref.packageFingerprint }
+                : {}),
+            ...(ref.binarySha256 ? { binarySha256: ref.binarySha256 } : {}),
+            runtimeContractCompatibility: spec.runtimeContract
+                ? compatibility.ok
+                    ? "compatible"
+                    : "incompatible"
+                : "legacy-unspecified",
+            ...(!compatibility.ok
+                ? { runtimeContractReason: compatibility.reason }
+                : {}),
+        },
+    };
+}
 function collectTransitiveDescendantNodeIds(spec, rootNodeId) {
     const childrenByParent = new Map();
     for (const task of spec.tasks) {
@@ -452,6 +501,7 @@ export async function buildDagRunReportEntry(input) {
         recoveryRecommendation,
         pausedByNodeId: input.state.pausedByNodeId,
         pauseReason: input.state.pauseReason,
+        ...summarizeControllerIdentityForReport(input.state.controllerIdentityRef, input.spec),
         nodes,
     };
     const primaryNode = resolvePrimaryFailureNode(partialEntry);

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

@@ -0,0 +1,138 @@
+import { z } from "zod";
+/**
+ * Failure categories that are safe to auto-retry for read-only Pi nodes.
+ *
+ * These are environmental/transient failures with no repository write
+ * side-effects: model connection interruption, provider rate-limiting,
+ * temporary provider unavailability, or request timeout.
+ *
+ * `quota` is intentionally NOT included: a quota exhaustion is an account
+ * billing/plan state, not a transient rate limit, and retrying immediately
+ * will not help and may waste budget.
+ */
+export const DEFAULT_DAG_RETRY_CATEGORIES = [
+    "timeout",
+    "network",
+    "rate-limit",
+    "unavailable",
+];
+const RETRY_SAFE_PI_ROLES = new Set([
+    "planner",
+    "scout",
+    "reviewer",
+    "verifier",
+    "closeout",
+]);
+export const dagRetryCategorySchema = z.enum(DEFAULT_DAG_RETRY_CATEGORIES);
+export const dagRetryBackoffSchema = z.enum(["exponential"]);
+/**
+ * Opt-in retry policy for a DagTask. Generated only for safe read-only Pi
+ * nodes. Validation (validate.ts) rejects retryPolicy on writers, dynamic,
+ * shell, static, and decision-gate nodes.
+ */
+export const dagRetryPolicySchema = z
+    .object({
+    /**
+     * Total number of attempts (including the first try). Must be 1..5.
+     * A value of 1 disables retry (one attempt, no retry).
+     */
+    maxAttempts: z.number().int().positive().max(5),
+    backoff: dagRetryBackoffSchema.default("exponential"),
+    /** Initial delay before the second attempt, in milliseconds. */
+    initialDelayMs: z.number().int().nonnegative().default(2000),
+    /** Upper bound on a single backoff delay, in milliseconds. */
+    maxDelayMs: z.number().int().nonnegative().default(30000),
+    /**
+     * Explicit set of failure categories eligible for retry. Defaults to
+     * {@link DEFAULT_DAG_RETRY_CATEGORIES}. `quota` and other categories
+     * are never retried.
+     */
+    retryCategories: z
+        .array(dagRetryCategorySchema)
+        .default([...DEFAULT_DAG_RETRY_CATEGORIES]),
+})
+    .superRefine((policy, ctx) => {
+    if (policy.maxDelayMs < policy.initialDelayMs) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "retryPolicy.maxDelayMs must be >= retryPolicy.initialDelayMs",
+            path: ["maxDelayMs"],
+        });
+    }
+});
+/**
+ * The default retry policy applied to safe generated read-only Pi nodes.
+ * Total attempts: 3, exponential backoff with cap.
+ */
+export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
+    maxAttempts: 3,
+    backoff: "exponential",
+    initialDelayMs: 2000,
+    maxDelayMs: 30000,
+    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES],
+};
+/**
+ * Deterministic helper: is this raw failure category eligible for retry under
+ * the given policy? Pure function; executor never decides retry eligibility.
+ */
+export function isRetryablePiFailureCategory(rawFailureCategory, options = {}) {
+    if (!rawFailureCategory)
+        return false;
+    const categories = options.retryCategories ?? DEFAULT_DAG_RETRY_CATEGORIES;
+    return categories.includes(rawFailureCategory);
+}
+/**
+ * Deterministic helper: is this task a safe candidate for read-only Pi retry?
+ *
+ * A safe candidate is:
+ * - executor === "pi"
+ * - role is planner/scout/reviewer/verifier/closeout (never supervisor/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.
+ */
+export function isSafeReadOnlyPiRetryCandidate(task) {
+    if (task.executor !== "pi")
+        return false;
+    if (!task.role || !RETRY_SAFE_PI_ROLES.has(task.role))
+        return false;
+    if (task.toolProfile === "write")
+        return false;
+    if (task.writePolicy !== undefined &&
+        task.writePolicy !== "read-only" &&
+        task.writePolicy !== "none") {
+        return false;
+    }
+    if (task.decisionGate?.enabled)
+        return false;
+    if (task.dynamicExpansion ||
+        task.dynamicReduction ||
+        task.dynamicCondition ||
+        task.dynamicLoopUntil) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Compute the backoff delay (in ms) to wait before the given attempt number.
+ *
+ * attemptNumber is 1-based: the delay returned is the wait BEFORE that attempt
+ * runs (i.e. the wait between attempt N-1 and attempt N). attemptNumber <= 1
+ * returns 0 (no wait before the first try).
+ *
+ * Exponential: initialDelayMs * 2^(attemptNumber - 2), capped at maxDelayMs.
+ */
+export function computeBackoffDelayMs(attemptNumber, policy) {
+    if (attemptNumber <= 1)
+        return 0;
+    if (policy.backoff !== "exponential") {
+        return Math.min(policy.initialDelayMs, policy.maxDelayMs);
+    }
+    const exponent = attemptNumber - 2;
+    const raw = policy.initialDelayMs * Math.pow(2, exponent);
+    return Math.min(raw, policy.maxDelayMs);
+}

package/dist/workflows/dag/runner.js

@@ -7,6 +7,9 @@ import { moveToCompletedRunDir, moveToPausedRunDir, prepareActiveRunDir, writeRu
 import { createDagNodeExecutor } from "./executor-registry.js";
 import { executeDagPiNode } from "../../executors/dag-pi-executor.js";
 import { assertValidDagSpec } from "./validate.js";
+import { assertRuntimeContractCompatible, DAG_CONTROLLER_CAPABILITIES, } from "./runtime-contract.js";
+import { captureControllerIdentity, verifyControllerIdentityForResume, } from "./controller-identity.js";
+import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 import { normalizeDagPromptSources } from "./prompt-source.js";
 import { relocateConvergenceArtifactPaths, relocateRunArtifactPaths, } from "./upstream-artifacts.js";
 import { createSkillSnapshot, prepareSkillSnapshotForContinuation, writeSkillSnapshot, } from "./skill-snapshot.js";
@@ -145,6 +148,15 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
 }
 export async function runDag(spec, opts) {
     assertValidDagSpec(spec);
+    // Capability preflight must fail closed before any run directory or node work.
+    const runningIdentity = resolveRunningControllerIdentity();
+    if (!runningIdentity) {
+        throw new Error("running controller identity could not be resolved; refuse to create an unpinned DAG run");
+    }
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        controllerVersion: runningIdentity.packageVersion,
+    });
     const { ranks } = topoSortToRanks(spec);
     const maxConcurrent = Math.max(1, opts.maxConcurrent ?? 4);
     let runId = opts.runId;
@@ -163,6 +175,12 @@ export async function runDag(spec, opts) {
     const runDir = activeRunDir;
     await prepareActiveRunDir(runDir);
     await writeRunSpec(runDir, spec);
+    // Freeze the running controller identity as a run-owned fact before the
+    // first canonical state write, reusing the identity resolved for preflight.
+    state.controllerIdentityRef = await captureControllerIdentity({
+        runDir,
+        identity: runningIdentity,
+    });
     // Resolve and snapshot all skill profiles before any node executes.
     try {
         const snapshot = await createSkillSnapshot({
@@ -224,6 +242,20 @@ export async function resumeDagRun(opts) {
     if (isTerminalDagRunStatus(state.status)) {
         throw new Error(`dag run ${opts.runId} is already terminal (status=${state.status})`);
     }
+    // Runtime contract + controller identity must be re-verified before executing
+    // any remaining node on resume; drift fails closed.
+    const runningIdentity = resolveRunningControllerIdentity();
+    if (!runningIdentity) {
+        throw new Error("running controller identity could not be resolved; refuse to resume an unpinned DAG run");
+    }
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        controllerVersion: runningIdentity.packageVersion,
+    });
+    await verifyControllerIdentityForResume({
+        runDir,
+        state,
+    });
     const decisionNodeId = state.humanDecisionNodeId;
     if (!decisionNodeId) {
         throw new Error(`dag run ${opts.runId} has no human decision checkpoint; was it approved?`);

package/dist/workflows/dag/runtime-contract.js

@@ -0,0 +1,87 @@
+import { DAG_AGENT_RUNTIME_PI_ONLY, DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1, DAG_RUNTIME_CONTRACT_SCHEMA_VERSION, } from "./types.js";
+export const DAG_CONTROLLER_CAPABILITIES = {
+    schemaVersion: DAG_RUNTIME_CONTRACT_SCHEMA_VERSION,
+    agentRuntime: DAG_AGENT_RUNTIME_PI_ONLY,
+    repairWriterProtocol: DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1,
+};
+function parseSemver(value) {
+    const match = value.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+/** Returns true when `actual` is greater than or equal to `required`. */
+export function semverGte(actual, required) {
+    const a = parseSemver(actual);
+    const r = parseSemver(required);
+    if (!a || !r)
+        return false;
+    if (a.major !== r.major)
+        return a.major > r.major;
+    if (a.minor !== r.minor)
+        return a.minor > r.minor;
+    return a.patch >= r.patch;
+}
+/**
+ * Decide whether a controller can run a DagSpec's declared runtimeContract.
+ *
+ * Capability fields are authoritative: an unsupported agentRuntime or
+ * repairWriterProtocol fails closed regardless of version. minimumControllerVersion
+ * is only consulted for diagnosis when the controller version is known and the
+ * capabilities otherwise match.
+ *
+ * Legacy DagSpecs without a runtimeContract are always compatible (they predate
+ * the capability handshake and rely on runtime-side derivation).
+ */
+export function checkRuntimeContractCompatible(contract, capabilities = DAG_CONTROLLER_CAPABILITIES) {
+    if (!contract)
+        return { ok: true };
+    if (contract.schemaVersion !== capabilities.schemaVersion) {
+        return {
+            ok: false,
+            reason: `runtime contract schemaVersion ${contract.schemaVersion} is not supported by this controller (supports ${capabilities.schemaVersion}); regenerate the DAG or upgrade the controller`,
+        };
+    }
+    if (contract.agentRuntime !== capabilities.agentRuntime) {
+        return {
+            ok: false,
+            reason: `runtime contract requires agentRuntime "${contract.agentRuntime}" but this controller advertises "${capabilities.agentRuntime}"; upgrade the controller or regenerate the DAG`,
+        };
+    }
+    if (contract.repairWriterProtocol !== capabilities.repairWriterProtocol) {
+        return {
+            ok: false,
+            reason: `runtime contract requires repairWriterProtocol "${contract.repairWriterProtocol}" but this controller advertises "${capabilities.repairWriterProtocol}"; upgrade the controller or regenerate the DAG`,
+        };
+    }
+    if (contract.minimumControllerVersion &&
+        !capabilities.controllerVersion) {
+        return {
+            ok: false,
+            reason: `runtime contract requires controller version >= ${contract.minimumControllerVersion} but the running controller version could not be resolved; refuse to continue unpinned`,
+        };
+    }
+    if (contract.minimumControllerVersion &&
+        capabilities.controllerVersion &&
+        !semverGte(capabilities.controllerVersion, contract.minimumControllerVersion)) {
+        return {
+            ok: false,
+            reason: `runtime contract requires controller version >= ${contract.minimumControllerVersion} but this controller reports ${capabilities.controllerVersion}; upgrade the controller`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Fail closed before any node execution when the DagSpec's runtimeContract is
+ * incompatible with this controller.
+ */
+export function assertRuntimeContractCompatible(spec, capabilities = DAG_CONTROLLER_CAPABILITIES) {
+    const result = checkRuntimeContractCompatible(spec.runtimeContract, capabilities);
+    if (!result.ok) {
+        throw new Error(`incompatible DAG runtime contract: ${result.reason}`);
+    }
+}

package/dist/workflows/dag/skill-snapshot.js

@@ -337,6 +337,8 @@ export async function createSkillSnapshot(input) {
             includeLearnedPatterns: request.includeLearnedPatterns,
             perSkillMaxChars: request.perSkillMaxChars,
             totalMaxChars: request.totalMaxChars,
+            ...(input.homeDir !== undefined ? { homeDir: input.homeDir } : {}),
+            ...(input.env !== undefined ? { env: input.env } : {}),
         });
         profiles.push({ ...request, resolvedInstructions });
     }

package/dist/workflows/dag/types.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
+import { dagRetryPolicySchema } from "./retry-policy.js";
 export const dagComplexitySchema = z.enum(["HIGH", "MED", "LOW"]);
 export const dagNodeExecutorSchema = z.enum([
     "pi",
@@ -33,6 +34,32 @@ export const dagRepairArtifactGateSchema = z.object({
     fromNodeId: z
         .string()
         .regex(/^[a-z][a-z0-9-]*$/, "fromNodeId must be kebab-case"),
+    /**
+     * Explicit reference to the governed Pi repair writer this gate feeds.
+     * New generated supervised DAGs must set this. Legacy DAGs without it are
+     * only accepted when a unique safe downstream Pi writer can be derived.
+     */
+    repairNodeId: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "repairNodeId must be kebab-case")
+        .optional(),
+});
+export const DAG_RUNTIME_CONTRACT_SCHEMA_VERSION = 1;
+export const DAG_AGENT_RUNTIME_PI_ONLY = "pi-only";
+export const DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1 = "explicit-node-v1";
+export const dagRuntimeContractSchema = z.object({
+    schemaVersion: z.literal(DAG_RUNTIME_CONTRACT_SCHEMA_VERSION),
+    agentRuntime: z.literal(DAG_AGENT_RUNTIME_PI_ONLY),
+    repairWriterProtocol: z.literal(DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1),
+    /**
+     * Optional minimum controller version for diagnosis / fail-below. Capability
+     * fields above are primary; semver is only used for guidance when the
+     * controller is otherwise compatible.
+     */
+    minimumControllerVersion: z
+        .string()
+        .regex(/^\d+\.\d+\.\d+([-+].+)?$/, "minimumControllerVersion must be semver")
+        .optional(),
 });
 export const dagVerdictGateSchema = z.object({
     fromNodeId: z
@@ -44,7 +71,7 @@ export const dagVerdictGateSchema = z.object({
 });
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
-    .union([z.literal(1), z.literal(2)])
+    .union([z.literal(1), z.literal(2), z.literal(3)])
     .default(1);
 export const dagRoleSchema = z.enum([
     "planner",
@@ -217,6 +244,7 @@ export const dagTaskSchema = z.object({
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),
+    retryPolicy: dagRetryPolicySchema.optional(),
     dynamicExpansion: dagDynamicExpansionSchema.optional(),
     dynamicReduction: dagDynamicReductionSchema.optional(),
     dynamicCondition: dagDynamicConditionSchema.optional(),
@@ -240,6 +268,7 @@ export const dagSpecSchema = z
     .object({
     version: dagVersionSchema,
     title: z.string().min(1),
+    runtimeContract: dagRuntimeContractSchema.optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
     successCriteria: z.array(z.string()).optional(),
@@ -252,6 +281,20 @@ export const dagSpecSchema = z
     tasks: z.array(dagTaskSchema).min(1),
 })
     .superRefine((spec, ctx) => {
+    if (spec.runtimeContract && spec.version !== 3) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "runtimeContract requires DagSpec version 3",
+            path: ["version"],
+        });
+    }
+    if (spec.version === 3 && !spec.runtimeContract) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "DagSpec version 3 requires runtimeContract",
+            path: ["runtimeContract"],
+        });
+    }
     // Catch raw cursor keys that Zod .strict() on nested objects already rejects when parsed
     // via parseDagSpec; this refine covers typed object construction paths.
     const models = spec.executorModels;

package/dist/workflows/dag/validate.js

@@ -1,7 +1,9 @@
 import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, } from "./types.js";
 import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { resolveRepairTaskForGate } from "./repair-artifact.js";
 import { topoSortToRanks } from "./topo.js";
+import { isSafeReadOnlyPiRetryCandidate } from "./retry-policy.js";
 const GOVERNANCE_WARNING_TYPES = new Set([
     "read-only-missing-artifacts-forbidden",
     "read-only-prompt-mentions-artifact-writes",
@@ -176,14 +178,65 @@ function validateRepairArtifactGateConfig(task, spec, issues) {
         });
     }
     const upstream = spec.tasks.find((candidate) => candidate.id === repairArtifactGate.fromNodeId);
-    if (!upstream)
-        return;
-    if (upstream.executor === "shell") {
+    if (upstream && upstream.executor === "shell") {
         issues.push({
             type: "invalid-repair-artifact-gate-config",
             message: `task ${task.id} shell.repairArtifactGate.fromNodeId "${repairArtifactGate.fromNodeId}" must reference a non-shell upstream artifact node`,
         });
     }
+    const resolution = resolveRepairTaskForGate({
+        tasks: spec.tasks,
+        gateTask: task,
+    });
+    if (!resolution.ok) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: `task ${task.id} ${resolution.reason}`,
+        });
+        return;
+    }
+    const hardVerifyCandidates = spec.tasks.filter((candidate) => candidate.depends_on.includes(resolution.repairTask.id) &&
+        candidate.executor === "shell" &&
+        candidate.role === "verifier" &&
+        candidate.shell?.verifyEvidence?.phase === "final" &&
+        candidate.shell.verifyEvidence.quota === "full" &&
+        candidate.shell.verifyEvidence.finalFullRequired === true);
+    if (hardVerifyCandidates.length !== 1) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: hardVerifyCandidates.length === 0
+                ? `task ${task.id} repair node "${resolution.repairTask.id}" must have one direct downstream final/full hard verification shell node with finalFullRequired=true`
+                : `task ${task.id} repair node "${resolution.repairTask.id}" has multiple hard verification shell nodes (${hardVerifyCandidates.map((candidate) => candidate.id).join(", ")})`,
+        });
+        return;
+    }
+    const hardVerify = hardVerifyCandidates[0];
+    const descendantIds = new Set();
+    const queue = [hardVerify.id];
+    while (queue.length > 0) {
+        const parentId = queue.shift();
+        for (const candidate of spec.tasks) {
+            if (candidate.depends_on.includes(parentId) &&
+                !descendantIds.has(candidate.id)) {
+                descendantIds.add(candidate.id);
+                queue.push(candidate.id);
+            }
+        }
+    }
+    const reviewCandidates = spec.tasks.filter((candidate) => descendantIds.has(candidate.id) &&
+        candidate.executor === "pi" &&
+        candidate.role === "reviewer" &&
+        !candidate.decisionGate?.enabled &&
+        candidate.writePolicy === "read-only" &&
+        (candidate.outputContract?.includes("VERDICT:") ?? false));
+    if (reviewCandidates.length !== 1) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: reviewCandidates.length === 0
+                ? `task ${task.id} hard verification node "${hardVerify.id}" must reach one read-only Pi reviewer with a VERDICT output contract`
+                : `task ${task.id} hard verification node "${hardVerify.id}" has multiple Pi reviewer nodes (${reviewCandidates.map((candidate) => candidate.id).join(", ")})`,
+        });
+    }
 }
 function validateShellVerdictGateGovernance(task, commands, issues) {
     if (task.executor !== "shell") {
@@ -229,7 +282,7 @@ function writeSetEntriesOverlap(a, b) {
         pathMatchesPattern(probeB, a)));
 }
 function shouldValidateWritePolicy(spec, task) {
-    return (spec.version === 2 ||
+    return (spec.version >= 2 ||
         task.writePolicy !== undefined ||
         task.writeSet !== undefined);
 }
@@ -414,6 +467,16 @@ function validateStaticTaskConfig(task, issues) {
         });
     }
 }
+function validateRetryPolicyTaskConfig(task, issues) {
+    if (task.retryPolicy === undefined)
+        return;
+    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`,
+        });
+    }
+}
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
         return;
@@ -512,6 +575,7 @@ export function validateDagSpec(spec) {
         validateShellTaskConfig(task, spec, issues);
         validateStaticTaskConfig(task, issues);
         validateDecisionGateTaskConfig(task, issues);
+        validateRetryPolicyTaskConfig(task, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);