@tea-agent/loop-agent 0.11.0 → 0.13.0-alpha.0

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

@@ -3,10 +3,12 @@ import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHuman
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
 import { buildDagNodePromptEnvelope } from "./prompt.js";
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
+import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, } from "./retry-policy.js";
+import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "./skill-snapshot.js";
 import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
 import { resolveDagNodeSkills } from "./skills.js";
-import { parseRepairArtifactFromText, validateRepairArtifactScope, } from "./repair-artifact.js";
+import { parseRepairArtifactFromText, resolveRepairTaskForGate, validateRepairArtifactScope, } from "./repair-artifact.js";
 import { resolveModelForTask, } from "./types.js";
 export function buildNodePrompt(spec, task, upstream) {
     return buildDagNodePromptEnvelope({
@@ -54,10 +56,6 @@ function assertRepairArtifactVerdictMatchesSupervisor(input) {
         throw new Error(`repair artifact gate failed: verdict mismatch between supervisor ${supervisorVerdict} and REPAIR_ARTIFACT_JSON ${input.artifactVerdict}`);
     }
 }
-function findRepairTaskForGate(input) {
-    return Array.from(input.tasksById.values()).find((candidate) => candidate.depends_on.includes(input.gateTask.id) &&
-        candidate.id === "repair-pi");
-}
 function parseSupervisorRepairArtifact(node) {
     const text = `${node?.assistantText ?? ""}\n${node?.stdout ?? ""}`;
     return parseRepairArtifactFromText(text);
@@ -76,12 +74,21 @@ function validateRepairArtifactGateBeforeShell(input) {
         artifactVerdict: parsed.artifact.verdict,
     });
     upstream.repairArtifact = parsed.artifact;
+    const resolution = resolveRepairTaskForGate({
+        tasks: Array.from(input.tasksById.values()),
+        gateTask: input.task,
+    });
+    if (!resolution.ok) {
+        // A pass verdict does not need a repair writer; only fail closed when the
+        // supervisor requested a revision that must be routed to a repair node.
+        if (parsed.artifact.verdict === "request-revision") {
+            throw new Error(`repair artifact gate failed: ${resolution.reason}`);
+        }
+        return;
+    }
     const scoped = validateRepairArtifactScope({
         artifact: parsed.artifact,
-        repairTask: findRepairTaskForGate({
-            tasksById: input.tasksById,
-            gateTask: input.task,
-        }),
+        repairTask: resolution.repairTask,
     });
     if (!scoped.ok) {
         throw new Error(`repair artifact gate failed: ${scoped.reason}`);
@@ -96,6 +103,15 @@ function recordRepairArtifactForSupervisorNode(input) {
         input.node.repairArtifact = parsed.artifact;
     }
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function sumAttemptMetric(attempts, select) {
+    const values = attempts.map(select).filter((value) => value !== undefined);
+    return values.length > 0
+        ? values.reduce((sum, value) => sum + value, 0)
+        : undefined;
+}
 async function notifyNodeObserver(observer, event, nodeId, state, chunk) {
     try {
         if (event === "onNodeOutput") {
@@ -223,31 +239,109 @@ export async function executeDagNode(input) {
     node.resolvedSkills = resolvedSkills;
     await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
     const model = resolveModelForTask(task, spec.executorModels);
-    const started = Date.now();
-    try {
-        validateRepairArtifactGateBeforeShell({
-            task,
-            tasksById,
-            state,
-        });
-        const result = await executeNode({ task, cwd, model, prompt });
-        node.durationMs = result.durationMs ?? Date.now() - started;
+    const retryPolicy = task.retryPolicy && isSafeReadOnlyPiRetryCandidate(task)
+        ? task.retryPolicy
+        : undefined;
+    const maxAttempts = retryPolicy?.maxAttempts ?? 1;
+    const attempts = [];
+    let totalBackoffMs = 0;
+    let terminalResult;
+    for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
+        const attemptStartedAt = new Date().toISOString();
+        const attemptStarted = Date.now();
+        let result;
+        try {
+            validateRepairArtifactGateBeforeShell({
+                task,
+                tasksById,
+                state,
+            });
+            result = await executeNode({ task, cwd, model, prompt });
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - attemptStarted,
+            };
+        }
+        const attemptFinishedAt = new Date().toISOString();
+        const attemptRecord = {
+            attempt: attemptNumber,
+            startedAt: attemptStartedAt,
+            finishedAt: attemptFinishedAt,
+            durationMs: result.durationMs ?? Date.now() - attemptStarted,
+            ok: result.ok,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            assistantText: result.assistantText,
+            failureCategory: result.failureCategory,
+            backend: result.backend,
+            sdkAttempted: result.sdkAttempted,
+            tokensUsed: result.tokensUsed,
+            parsedEvents: result.parsedEvents,
+            artifactPath: `${nodeId}/attempt-${attemptNumber}.json`,
+        };
+        if (retryPolicy !== undefined) {
+            attempts.push(attemptRecord);
+            // Persist immutable attempt evidence BEFORE waiting for the next attempt
+            // and before applying the result to the node record, so a later success
+            // never overwrites prior failure evidence.
+            await writeDagNodeJsonArtifact(runDir, nodeId, `attempt-${attemptNumber}.json`, attemptRecord);
+            node.attempts = attempts;
+        }
+        // Reflect the latest attempt on the node so progress is observable,
+        // but keep node.status RUNNING while retry is still possible.
+        node.durationMs =
+            retryPolicy === undefined
+                ? attemptRecord.durationMs
+                : attempts.reduce((sum, attempt) => sum + (attempt.durationMs ?? 0), 0) +
+                    totalBackoffMs;
         node.stdout = result.stdout;
         node.stderr = result.stderr;
         node.failureCategory = result.failureCategory;
-        if (result.assistantText !== undefined) {
-            node.assistantText = result.assistantText;
-        }
-        if (result.backend !== undefined)
-            node.backend = result.backend;
-        if (result.sdkAttempted !== undefined) {
-            node.sdkAttempted = result.sdkAttempted;
+        node.assistantText = result.assistantText;
+        node.backend = result.backend;
+        node.sdkAttempted = result.sdkAttempted;
+        node.tokensUsed =
+            retryPolicy === undefined
+                ? result.tokensUsed
+                : sumAttemptMetric(attempts, (attempt) => attempt.tokensUsed);
+        node.parsedEvents =
+            retryPolicy === undefined
+                ? result.parsedEvents
+                : sumAttemptMetric(attempts, (attempt) => attempt.parsedEvents);
+        node.lastActivityAt = attemptFinishedAt;
+        if (retryPolicy !== undefined) {
+            state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+            await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+            await input.persistState();
         }
-        if (result.tokensUsed !== undefined)
-            node.tokensUsed = result.tokensUsed;
-        if (result.parsedEvents !== undefined) {
-            node.parsedEvents = result.parsedEvents;
+        terminalResult = result;
+        if (result.ok)
+            break;
+        const canRetry = retryPolicy !== undefined && attemptNumber < maxAttempts;
+        const retryable = retryPolicy !== undefined &&
+            isRetryablePiFailureCategory(result.failureCategory, {
+                retryCategories: retryPolicy.retryCategories,
+            });
+        if (!canRetry || !retryable)
+            break;
+        const delayMs = computeBackoffDelayMs(attemptNumber + 1, retryPolicy);
+        if (delayMs > 0) {
+            totalBackoffMs += delayMs;
+            await sleep(delayMs);
+            // Keep lastActivityAt fresh so backoff wait is not misread as node-quiet.
+            node.lastActivityAt = new Date().toISOString();
+            state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+            await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+            await input.persistState();
         }
+    }
+    const result = terminalResult;
+    const started = Date.now();
+    try {
         recordRepairArtifactForSupervisorNode({
             task,
             node,

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 });
     }