@tea-agent/loop-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,529 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { buildDagNodePromptEnvelope } from "./prompt.js";
+import { DEFAULT_SKILL_INSTRUCTION_MAX_CHARS, DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS, resolveDagSkillInstructions, } from "./skill-instructions.js";
+import { resolveDagNodeSkills } from "./skills.js";
+export const SKILL_SNAPSHOT_SCHEMA_VERSION = 1;
+export const SKILL_SNAPSHOT_RESOLVER_VERSION = 1;
+export const SKILL_SNAPSHOT_REL_PATH = ".runtime/skill-snapshot.json";
+const skillReferenceSchema = z.object({
+    name: z.string().min(1),
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    bytes: z.number().int().nonnegative(),
+    truncated: z.boolean().optional(),
+}).strict();
+const unresolvedReferenceSchema = z.object({
+    name: z.string().min(1).optional(),
+    path: z.string().min(1),
+    reason: z.enum([
+        "invalid-path",
+        "missing",
+        "budget",
+        "read-error",
+        "cycle",
+        "already-resolved",
+    ]),
+}).strict();
+const resolvedInstructionSchema = z.object({
+    name: z.string().min(1),
+    resolution: z.enum(["resolved", "missing", "error"]),
+    path: z.string().min(1).optional(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    bytes: z.number().int().nonnegative().optional(),
+    truncated: z.boolean().optional(),
+    searchedPaths: z.array(z.string().min(1)).optional(),
+    error: z.string().min(1).optional(),
+    injectionMode: z.enum(["bounded-inline", "name-only"]),
+    references: z.array(skillReferenceSchema).optional(),
+    unresolvedReferences: z.array(unresolvedReferenceSchema).optional(),
+    promptText: z.string(),
+}).strict();
+const skillSnapshotProfileSchema = z.object({
+    id: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    skills: z.array(z.string()),
+    includeLearnedPatterns: z.boolean(),
+    perSkillMaxChars: z.number().int().nonnegative(),
+    totalMaxChars: z.number().int().nonnegative(),
+    resolvedInstructions: z.array(resolvedInstructionSchema),
+}).strict();
+const skillSnapshotBindingSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("task"),
+        taskId: z.string().min(1),
+        profileId: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    }).strict(),
+    z.object({
+        kind: z.literal("dynamic-map-child"),
+        parentTaskId: z.string().min(1),
+        workflowNodeId: z.string().min(1),
+        profileId: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    }).strict(),
+    z.object({
+        kind: z.literal("dynamic-loop-body"),
+        parentTaskId: z.string().min(1),
+        workflowNodeId: z.string().min(1),
+        bodyTaskId: z.string().min(1),
+        profileId: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    }).strict(),
+]);
+const skillSnapshotSchema = z.object({
+    schemaVersion: z.literal(SKILL_SNAPSHOT_SCHEMA_VERSION),
+    resolverVersion: z.literal(SKILL_SNAPSHOT_RESOLVER_VERSION),
+    runId: z.string().min(1),
+    createdAt: z.string().datetime(),
+    mode: z.enum(["run-start", "legacy-resume-backfill"]),
+    initialTaskIds: z.array(z.string().min(1)),
+    bindings: z.array(skillSnapshotBindingSchema),
+    profiles: z.array(skillSnapshotProfileSchema),
+}).strict();
+const skillSnapshotRefSchema = z.object({
+    schemaVersion: z.literal(SKILL_SNAPSHOT_SCHEMA_VERSION),
+    path: z.literal(SKILL_SNAPSHOT_REL_PATH),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    createdAt: z.string().datetime(),
+    mode: z.enum(["run-start", "legacy-resume-backfill"]),
+}).strict();
+export class DagSkillSnapshotIntegrityError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DagSkillSnapshotIntegrityError";
+    }
+}
+export function isDagSkillSnapshotIntegrityError(error) {
+    return error instanceof DagSkillSnapshotIntegrityError;
+}
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function serializeSnapshot(snapshot) {
+    return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+function profileAnchor(input) {
+    return JSON.stringify({
+        resolverVersion: SKILL_SNAPSHOT_RESOLVER_VERSION,
+        skills: [...input.skills],
+        includeLearnedPatterns: input.includeLearnedPatterns,
+        perSkillMaxChars: input.perSkillMaxChars,
+        totalMaxChars: input.totalMaxChars,
+    });
+}
+function profileId(input) {
+    return `sha256:${sha256(profileAnchor(input))}`;
+}
+export function buildDagSkillSnapshotProfileRequest(spec, task) {
+    if (task.executor !== "pi")
+        return undefined;
+    const request = {
+        skills: [...resolveDagNodeSkills(spec, task)],
+        includeLearnedPatterns: task.role === "implementer",
+        perSkillMaxChars: DEFAULT_SKILL_INSTRUCTION_MAX_CHARS,
+        totalMaxChars: DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS,
+    };
+    return { id: profileId(request), ...request };
+}
+function isDynamicRuntimeTask(task) {
+    return Boolean(task.dynamicExpansion
+        || task.dynamicReduction
+        || task.dynamicCondition
+        || task.dynamicLoopUntil);
+}
+function bindingKey(binding) {
+    switch (binding.kind) {
+        case "task":
+            return `task:${binding.taskId}`;
+        case "dynamic-map-child":
+            return `dynamic-map-child:${binding.parentTaskId}:${binding.workflowNodeId}`;
+        case "dynamic-loop-body":
+            return `dynamic-loop-body:${binding.parentTaskId}:${binding.workflowNodeId}:${binding.bodyTaskId}`;
+    }
+}
+function collectDeclaredSkillSnapshotTargets(spec, initialTaskIds) {
+    const tasksById = new Map(spec.tasks.map((task) => [task.id, task]));
+    const targets = [];
+    for (const taskId of initialTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot initial task is missing from run spec: ${taskId}`);
+        }
+        if (!isDynamicRuntimeTask(task)) {
+            targets.push({
+                binding: { kind: "task", taskId: task.id },
+                task,
+            });
+        }
+        if (task.dynamicExpansion) {
+            targets.push({
+                binding: {
+                    kind: "dynamic-map-child",
+                    parentTaskId: task.id,
+                    workflowNodeId: task.dynamicExpansion.workflowNodeId,
+                },
+                task: task.dynamicExpansion.childTask,
+            });
+        }
+        for (const bodyTask of task.dynamicLoopUntil?.bodyTasks ?? []) {
+            targets.push({
+                binding: {
+                    kind: "dynamic-loop-body",
+                    parentTaskId: task.id,
+                    workflowNodeId: task.dynamicLoopUntil.workflowNodeId,
+                    bodyTaskId: bodyTask.id,
+                },
+                task: bodyTask,
+            });
+        }
+    }
+    return targets;
+}
+function matchesExpandedMapChild(taskId, parent) {
+    const expansion = parent.dynamicExpansion;
+    if (!expansion)
+        return false;
+    const prefix = `${expansion.childIdPrefix}-`;
+    if (!taskId.startsWith(prefix))
+        return false;
+    const suffix = taskId.slice(prefix.length);
+    if (!/^\d+$/.test(suffix))
+        return false;
+    const index = Number(suffix);
+    return (Number.isSafeInteger(index)
+        && index >= 1
+        && index <= Math.min(expansion.maxItems, expansion.maxExpandedNodes)
+        && suffix === String(index).padStart(4, "0"));
+}
+function matchesExpandedLoopChild(taskId, parent, bodyTaskId) {
+    const loop = parent.dynamicLoopUntil;
+    if (!loop)
+        return false;
+    const prefix = `${parent.id}-r`;
+    const suffix = `-${bodyTaskId}`;
+    if (!taskId.startsWith(prefix) || !taskId.endsWith(suffix))
+        return false;
+    const iterationText = taskId.slice(prefix.length, -suffix.length);
+    if (!/^\d+$/.test(iterationText))
+        return false;
+    const iteration = Number(iterationText);
+    return (Number.isSafeInteger(iteration)
+        && iteration >= 1
+        && iteration <= loop.maxIterations
+        && iterationText === String(iteration));
+}
+function resolveGeneratedTaskTarget(spec, task, initialTaskIds) {
+    const matches = [];
+    for (const parent of spec.tasks) {
+        if (!initialTaskIds.has(parent.id))
+            continue;
+        if (matchesExpandedMapChild(task.id, parent)) {
+            matches.push({
+                binding: {
+                    kind: "dynamic-map-child",
+                    parentTaskId: parent.id,
+                    workflowNodeId: parent.dynamicExpansion.workflowNodeId,
+                },
+                task,
+            });
+        }
+        for (const bodyTask of parent.dynamicLoopUntil?.bodyTasks ?? []) {
+            if (!matchesExpandedLoopChild(task.id, parent, bodyTask.id))
+                continue;
+            matches.push({
+                binding: {
+                    kind: "dynamic-loop-body",
+                    parentTaskId: parent.id,
+                    workflowNodeId: parent.dynamicLoopUntil.workflowNodeId,
+                    bodyTaskId: bodyTask.id,
+                },
+                task,
+            });
+        }
+    }
+    if (matches.length > 1) {
+        throw new DagSkillSnapshotIntegrityError(`dynamic task ${task.id} matches multiple skill snapshot bindings`);
+    }
+    return matches[0];
+}
+export function collectDagSkillSnapshotBindings(spec, initialTaskIds = spec.tasks.map((task) => task.id)) {
+    const bindings = [];
+    for (const target of collectDeclaredSkillSnapshotTargets(spec, initialTaskIds)) {
+        const request = buildDagSkillSnapshotProfileRequest(spec, target.task);
+        if (!request)
+            continue;
+        bindings.push({ ...target.binding, profileId: request.id });
+    }
+    return bindings;
+}
+export function collectDagSkillSnapshotProfileRequests(spec, initialTaskIds = spec.tasks.map((task) => task.id)) {
+    const profiles = new Map();
+    for (const target of collectDeclaredSkillSnapshotTargets(spec, initialTaskIds)) {
+        const profile = buildDagSkillSnapshotProfileRequest(spec, target.task);
+        if (profile && !profiles.has(profile.id))
+            profiles.set(profile.id, profile);
+    }
+    return [...profiles.values()];
+}
+function validateResolvedInstructionOrder(profile) {
+    const primaryNames = profile.resolvedInstructions
+        .slice(0, profile.skills.length)
+        .map((instruction) => instruction.name);
+    if (JSON.stringify(primaryNames) !== JSON.stringify(profile.skills)) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot profile ${profile.id} resolved instruction order does not match its requested skills`);
+    }
+    const extras = profile.resolvedInstructions.slice(profile.skills.length);
+    if (extras.length > 1
+        || (extras.length === 1
+            && (!profile.includeLearnedPatterns
+                || !profile.skills.includes("loop-agent")
+                || extras[0]?.name !== "loop-agent-learned"))) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot profile ${profile.id} contains unexpected resolved instructions`);
+    }
+}
+function validateSnapshotSemantics(snapshot) {
+    if (new Set(snapshot.initialTaskIds).size !== snapshot.initialTaskIds.length) {
+        throw new DagSkillSnapshotIntegrityError("skill snapshot contains duplicate initial task ids");
+    }
+    const seen = new Set();
+    for (const profile of snapshot.profiles) {
+        if (profile.id !== profileId(profile)) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot profile id mismatch: ${profile.id}`);
+        }
+        if (seen.has(profile.id)) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot contains duplicate profile: ${profile.id}`);
+        }
+        seen.add(profile.id);
+        validateResolvedInstructionOrder(profile);
+    }
+    const bindingKeys = new Set();
+    const referencedProfiles = new Set();
+    for (const binding of snapshot.bindings) {
+        const key = bindingKey(binding);
+        if (bindingKeys.has(key)) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot contains duplicate binding: ${key}`);
+        }
+        if (!seen.has(binding.profileId)) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot binding ${key} references missing profile ${binding.profileId}`);
+        }
+        bindingKeys.add(key);
+        referencedProfiles.add(binding.profileId);
+    }
+    for (const profile of snapshot.profiles) {
+        if (!referencedProfiles.has(profile.id)) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot contains unbound profile: ${profile.id}`);
+        }
+    }
+}
+function parseSnapshot(value) {
+    try {
+        const snapshot = skillSnapshotSchema.parse(value);
+        validateSnapshotSemantics(snapshot);
+        return snapshot;
+    }
+    catch (error) {
+        if (isDagSkillSnapshotIntegrityError(error))
+            throw error;
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot schema validation failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+export async function createSkillSnapshot(input) {
+    const initialTaskIds = input.initialTaskIds
+        ?? input.spec.tasks.map((task) => task.id);
+    const profiles = [];
+    for (const request of collectDagSkillSnapshotProfileRequests(input.spec, initialTaskIds)) {
+        const resolvedInstructions = await resolveDagSkillInstructions(request.skills, {
+            cwd: input.cwd,
+            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 });
+    }
+    return {
+        schemaVersion: SKILL_SNAPSHOT_SCHEMA_VERSION,
+        resolverVersion: SKILL_SNAPSHOT_RESOLVER_VERSION,
+        runId: input.runId,
+        createdAt: (input.now ?? new Date()).toISOString(),
+        mode: input.mode,
+        initialTaskIds,
+        bindings: collectDagSkillSnapshotBindings(input.spec, initialTaskIds),
+        profiles,
+    };
+}
+export async function writeSkillSnapshot(runDir, snapshotValue) {
+    const snapshot = parseSnapshot(snapshotValue);
+    const raw = serializeSnapshot(snapshot);
+    await writeTextAtomic(path.join(runDir, ...SKILL_SNAPSHOT_REL_PATH.split("/")), raw);
+    return {
+        schemaVersion: SKILL_SNAPSHOT_SCHEMA_VERSION,
+        path: SKILL_SNAPSHOT_REL_PATH,
+        sha256: sha256(raw),
+        createdAt: snapshot.createdAt,
+        mode: snapshot.mode,
+    };
+}
+export async function readSkillSnapshot(runDir, refValue, options) {
+    let ref;
+    try {
+        ref = skillSnapshotRefSchema.parse(refValue);
+    }
+    catch (error) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot ref is invalid: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const snapshotPath = path.join(runDir, ...ref.path.split("/"));
+    let raw;
+    try {
+        raw = await readFile(snapshotPath);
+    }
+    catch (error) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot missing or unreadable at ${ref.path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const actualHash = sha256(raw);
+    if (actualHash !== ref.sha256) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot integrity check failed at ${ref.path}: expected sha256 ${ref.sha256}, got ${actualHash}`);
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(raw.toString("utf-8"));
+    }
+    catch (error) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot JSON is invalid: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const snapshot = parseSnapshot(decoded);
+    if (snapshot.createdAt !== ref.createdAt || snapshot.mode !== ref.mode) {
+        throw new DagSkillSnapshotIntegrityError("skill snapshot ref metadata does not match the snapshot artifact");
+    }
+    if (options?.expectedRunId && snapshot.runId !== options.expectedRunId) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot run ownership mismatch: expected ${options.expectedRunId}, got ${snapshot.runId}`);
+    }
+    return snapshot;
+}
+export async function prepareSkillSnapshotForContinuation(input) {
+    if (input.ref) {
+        const snapshot = await readSkillSnapshot(input.runDir, input.ref, {
+            expectedRunId: input.runId,
+        });
+        assertSkillSnapshotCoversSpec(snapshot, input.spec, input.state);
+        return { ref: input.ref, backfilled: false };
+    }
+    const snapshotPath = path.join(input.runDir, ...SKILL_SNAPSHOT_REL_PATH.split("/"));
+    try {
+        await readFile(snapshotPath);
+        throw new DagSkillSnapshotIntegrityError("skill snapshot artifact exists without a state ref; refusing legacy backfill");
+    }
+    catch (error) {
+        if (isDagSkillSnapshotIntegrityError(error))
+            throw error;
+        if (!(error && typeof error === "object" && "code" in error
+            && error.code === "ENOENT")) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot artifact is unreadable during legacy backfill: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    const snapshot = await createSkillSnapshot({
+        runId: input.runId,
+        spec: input.spec,
+        cwd: input.cwd,
+        mode: "legacy-resume-backfill",
+    });
+    assertSkillSnapshotCoversSpec(snapshot, input.spec, input.state);
+    return {
+        ref: await writeSkillSnapshot(input.runDir, snapshot),
+        backfilled: true,
+    };
+}
+export function assertSkillSnapshotCoversSpec(snapshot, spec, state) {
+    const currentInitialIds = spec.tasks
+        .slice(0, snapshot.initialTaskIds.length)
+        .map((task) => task.id);
+    if (JSON.stringify(currentInitialIds) !== JSON.stringify(snapshot.initialTaskIds)) {
+        throw new DagSkillSnapshotIntegrityError("skill snapshot initial task scope does not match the current run spec");
+    }
+    const expectedBindings = collectDagSkillSnapshotBindings(spec, snapshot.initialTaskIds);
+    const actualByKey = new Map(snapshot.bindings.map((binding) => [bindingKey(binding), binding]));
+    const expectedByKey = new Map(expectedBindings.map((binding) => [bindingKey(binding), binding]));
+    for (const [key, expected] of expectedByKey) {
+        const actual = actualByKey.get(key);
+        if (!actual) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot binding mismatch: missing ${key}`);
+        }
+        if (actual.profileId !== expected.profileId) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot binding mismatch for ${key}: expected ${actual.profileId}, got ${expected.profileId}`);
+        }
+    }
+    for (const key of actualByKey.keys()) {
+        if (!expectedByKey.has(key)) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot binding mismatch: unexpected ${key}`);
+        }
+    }
+    const initialIds = new Set(snapshot.initialTaskIds);
+    for (const task of spec.tasks.slice(snapshot.initialTaskIds.length)) {
+        if (!state
+            || !state.nodes[task.id]
+            || !state.ranks.some((rank) => rank.includes(task.id))) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot cannot prove runtime origin for appended task: ${task.id}`);
+        }
+        const generated = resolveGeneratedTaskTarget(spec, task, initialIds);
+        if (!generated) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot run spec contains an unexpected task: ${task.id}`);
+        }
+        const key = bindingKey(generated.binding);
+        const binding = actualByKey.get(key);
+        const request = buildDagSkillSnapshotProfileRequest(spec, generated.task);
+        if (!request) {
+            if (binding) {
+                throw new DagSkillSnapshotIntegrityError(`skill snapshot generated task binding mismatch for ${task.id}`);
+            }
+            continue;
+        }
+        if (!binding || binding.profileId !== request.id) {
+            throw new DagSkillSnapshotIntegrityError(`skill snapshot generated task binding mismatch for ${task.id}`);
+        }
+    }
+}
+export function resolveNodeSkillsFromSnapshot(snapshot, spec, task) {
+    const request = buildDagSkillSnapshotProfileRequest(spec, task);
+    if (!request)
+        return [];
+    const initialIds = new Set(snapshot.initialTaskIds);
+    const generated = initialIds.has(task.id)
+        ? undefined
+        : resolveGeneratedTaskTarget(spec, task, initialIds);
+    const targetBinding = generated?.binding ?? {
+        kind: "task",
+        taskId: task.id,
+    };
+    const key = bindingKey(targetBinding);
+    const binding = snapshot.bindings.find((candidate) => bindingKey(candidate) === key);
+    if (!binding || binding.profileId !== request.id) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot binding mismatch for ${key}`);
+    }
+    const profile = snapshot.profiles.find((candidate) => candidate.id === binding.profileId);
+    if (!profile) {
+        throw new DagSkillSnapshotIntegrityError(`skill snapshot profile mismatch: missing ${binding.profileId}`);
+    }
+    return profile.resolvedInstructions;
+}
+function stripPromptText(instruction) {
+    const { promptText: _promptText, ...metadata } = instruction;
+    return metadata;
+}
+export function buildNodePromptFromSnapshot(input) {
+    const skillNames = resolveDagNodeSkills(input.spec, input.task);
+    const resolvedSkillInstructions = resolveNodeSkillsFromSnapshot(input.snapshot, input.spec, input.task);
+    return {
+        prompt: buildDagNodePromptEnvelope({
+            spec: input.spec,
+            task: input.task,
+            upstream: input.upstream,
+            resolvedSkills: skillNames,
+            resolvedSkillInstructions,
+        }),
+        resolvedSkills: resolvedSkillInstructions.map(stripPromptText),
+    };
+}
+export function hashSkillSnapshot(snapshot) {
+    return sha256(serializeSnapshot(snapshot));
+}

package/dist/workflows/dag/types.js

@@ -1,12 +1,14 @@
 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([
-    "cursor",
     "pi",
     "shell",
     "static",
 ]);
+export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
+export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = 'executorModels.cursor is no longer supported; use executorModels.pi only';
 export const dagToolProfileSchema = z.enum(["read-only", "write"]);
 export const dagShellPresetSchema = z.enum(["loop-agent-standard-verify"]);
 export const dagVerifyQuotaSchema = z.enum(["1", "3", "full"]);
@@ -32,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
@@ -43,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",
@@ -216,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(),
@@ -230,15 +259,16 @@ export const dagModelsSchema = z
     .partial();
 export const dagExecutorModelsSchema = z
     .object({
-    cursor: dagModelsSchema.optional(),
     pi: dagModelsSchema.optional(),
 })
-    .partial();
+    .strict();
 export const dagOutputLanguageSchema = z.enum(["zh-CN", "en"]);
 export const DEFAULT_DAG_OUTPUT_LANGUAGE = "zh-CN";
-export const dagSpecSchema = z.object({
+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(),
@@ -249,13 +279,34 @@ export const dagSpecSchema = z.object({
     skillsByRole: z.record(z.string(), z.array(z.string())).optional(),
     executorModels: dagExecutorModelsSchema.optional(),
     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;
+    if (models && "cursor" in models) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: CURSOR_EXECUTOR_MODELS_REMOVED_ERROR,
+            path: ["executorModels", "cursor"],
+        });
+    }
 });
 export const DEFAULT_DAG_EXECUTOR_MODELS = {
-    cursor: {
-        LOW: "composer-2.5",
-        MED: "composer-2.5",
-        HIGH: "gpt-5.5",
-    },
     pi: {
         LOW: "gpt-5.3-codex-spark",
         MED: "glm-5.2",
@@ -269,6 +320,31 @@ export function parseDagSpec(raw) {
     if (typeof raw === "object" && raw !== null && "models" in raw) {
         throw new Error(LEGACY_TOP_LEVEL_MODELS_ERROR);
     }
+    if (typeof raw === "object" && raw !== null) {
+        const obj = raw;
+        const executorModels = obj.executorModels;
+        if (typeof executorModels === "object" &&
+            executorModels !== null &&
+            "cursor" in executorModels) {
+            throw new Error(CURSOR_EXECUTOR_MODELS_REMOVED_ERROR);
+        }
+        const tasks = obj.tasks;
+        if (Array.isArray(tasks)) {
+            for (const task of tasks) {
+                if (typeof task === "object" &&
+                    task !== null &&
+                    task.executor === "cursor") {
+                    throw new Error(CURSOR_DAG_EXECUTOR_REMOVED_ERROR);
+                }
+            }
+        }
+        const defaults = obj.defaults;
+        if (typeof defaults === "object" &&
+            defaults !== null &&
+            defaults.executor === "cursor") {
+            throw new Error(CURSOR_DAG_EXECUTOR_REMOVED_ERROR);
+        }
+    }
     return dagSpecSchema.parse(raw);
 }
 export function resolveModelForTask(task, executorModels) {