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

package/dist/worker/pool/validation.js

@@ -1,20 +1,42 @@
 import { z } from "zod";
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
-import { getRunsJsonlPath, getTaskPoolRoot } from "./run-store.js";
+import { getRunsJsonlPath, getStatesRoot, } from "./run-store.js";
+import { TASK_POOL_STATE_ERROR_CODES, } from "./types.js";
 export const taskPoolRunFactSchema = z.object({
-    schemaVersion: z.literal(1), batchRunId: z.string().min(1), workerRunId: z.string().min(1), taskId: z.string().min(1), featureId: z.string().min(1),
-    status: z.enum(["succeeded", "failed", "run-error"]), recordedAt: z.string().datetime(),
+    schemaVersion: z.literal(1),
+    batchRunId: z.string().min(1),
+    workerRunId: z.string().min(1),
+    taskId: z.string().min(1),
+    featureId: z.string().min(1),
+    status: z.enum(["succeeded", "failed", "run-error"]),
+    recordedAt: z.string().datetime(),
 }).passthrough();
 export const taskPoolStateFactSchema = z.object({
-    taskId: z.string().min(1), status: z.enum(["Draft", "Ready", "Queued", "Running", "AgentCompleted", "VerificationRunning", "HumanReview", "Done", "Failed", "Blocked", "Abandoned"]), updatedAt: z.string().datetime(),
+    taskId: z.string().min(1),
+    status: z.enum([
+        "Draft",
+        "Ready",
+        "Queued",
+        "Running",
+        "AgentCompleted",
+        "VerificationRunning",
+        "HumanReview",
+        "Done",
+        "Failed",
+        "Blocked",
+        "Abandoned",
+    ]),
+    updatedAt: z.string().datetime(),
+    schemaVersion: z.union([z.literal(1), z.literal(2)]).optional(),
+    featureId: z.string().min(1).optional(),
 }).passthrough();
 export async function readValidTaskPoolRuns(repoRoot) {
     const records = [];
     const warnings = [];
     try {
         const raw = await readFile(getRunsJsonlPath(repoRoot), "utf-8");
-        for (const [index, line] of raw.split(/\r?\n/).filter(Boolean).entries())
+        for (const [index, line] of raw.split(/\r?\n/).filter(Boolean).entries()) {
             try {
                 const parsed = taskPoolRunFactSchema.safeParse(JSON.parse(line));
                 if (parsed.success)
@@ -25,6 +47,7 @@ export async function readValidTaskPoolRuns(repoRoot) {
             catch {
                 warnings.push(`Task Pool runs.jsonl line ${index + 1} is corrupt`);
             }
+        }
     }
     catch (error) {
         if (!isNotFound(error))
@@ -32,23 +55,80 @@ export async function readValidTaskPoolRuns(repoRoot) {
     }
     return { records, warnings };
 }
+/**
+ * Valid state reader for morning-report and similar consumers.
+ * - v2 feature-scoped states: included when path/content identity match.
+ * - bare taskId collisions among v2: warning, do not overwrite records.
+ * - legacy flat states: warning with migration-required code; never treated as Ready facts.
+ */
 export async function readValidTaskPoolStates(repoRoot) {
     const records = {};
     const warnings = [];
-    const stateDir = path.join(getTaskPoolRoot(repoRoot), "states");
+    const stateDir = getStatesRoot(repoRoot);
     try {
-        for (const entry of await readdir(stateDir))
-            if (entry.endsWith(".json"))
+        const entries = await readdir(stateDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith(".json")) {
+                const entryPath = path.join(stateDir, entry.name);
                 try {
-                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(path.join(stateDir, entry), "utf-8")));
-                    if (parsed.success && parsed.data.taskId === entry.slice(0, -5))
-                        records[parsed.data.taskId] = parsed.data;
-                    else
-                        warnings.push(`Task Pool state is semantically invalid: ${entry}`);
+                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(entryPath, "utf-8")));
+                    if (!parsed.success) {
+                        warnings.push(`Task Pool state is semantically invalid: ${entry.name}`);
+                        continue;
+                    }
+                    const expectedTaskId = entry.name.slice(0, -5);
+                    if (parsed.data.taskId !== expectedTaskId) {
+                        warnings.push(`Task Pool state is semantically invalid: ${entry.name}`);
+                        continue;
+                    }
+                    warnings.push(`${TASK_POOL_STATE_ERROR_CODES.MIGRATION_REQUIRED}: legacy state ${entry.name}`);
                 }
                 catch {
-                    warnings.push(`Task Pool state is corrupt: ${entry}`);
+                    warnings.push(`Task Pool state is corrupt: ${entry.name}`);
                 }
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+            const featureId = entry.name;
+            const featureDir = path.join(stateDir, featureId);
+            let featureEntries;
+            try {
+                featureEntries = await readdir(featureDir);
+            }
+            catch {
+                warnings.push(`Task Pool feature state directory is unreadable: ${featureId}`);
+                continue;
+            }
+            for (const fileName of featureEntries) {
+                if (!fileName.endsWith(".json"))
+                    continue;
+                const relative = `${featureId}/${fileName}`;
+                try {
+                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(path.join(featureDir, fileName), "utf-8")));
+                    if (!parsed.success) {
+                        warnings.push(`Task Pool state is semantically invalid: ${relative}`);
+                        continue;
+                    }
+                    const expectedTaskId = fileName.slice(0, -5);
+                    const data = parsed.data;
+                    if (data.taskId !== expectedTaskId ||
+                        data.featureId !== featureId ||
+                        data.schemaVersion !== 2) {
+                        warnings.push(`${TASK_POOL_STATE_ERROR_CODES.PATH_MISMATCH}: ${relative}`);
+                        continue;
+                    }
+                    if (records[data.taskId]) {
+                        warnings.push(`${TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS}: multiple features share taskId ${data.taskId}`);
+                        continue;
+                    }
+                    records[data.taskId] = data;
+                }
+                catch {
+                    warnings.push(`Task Pool state is corrupt: ${relative}`);
+                }
+            }
+        }
     }
     catch (error) {
         if (!isNotFound(error))
@@ -56,4 +136,9 @@ export async function readValidTaskPoolStates(repoRoot) {
     }
     return { records, warnings };
 }
-function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }
+function isNotFound(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/worker/report/morning-report.js

@@ -23,7 +23,16 @@ export async function renderMorningReport(options) {
         ...(features.length === 0 ? ["- Status: no Feature Packet discovered", "- Next Action: add or locate a Feature Packet", "- Why: no shared Feature read model is available", "- Evidence: none"] : features.flatMap((feature) => {
             const why = feature.blockingItems[0]?.message ?? `${feature.summary.tasksSucceeded}/${feature.summary.tasksTotal} tasks; ${feature.summary.requiredAcCovered}/${feature.summary.requiredAcTotal} required AC`;
             const evidence = [feature.evidence.delivery, feature.evidence.closeout, feature.evidence.morningReport, feature.evidence.observeSnapshot, ...feature.blockingItems.flatMap((item) => item.evidence)].find(Boolean) ?? "none";
-            return [`### ${feature.featureId}`, "", `- Status: ${feature.status}`, `- Next Action: ${feature.nextAction?.command ?? feature.nextAction?.label ?? "none"}`, `- Why: ${why}`, `- Evidence: ${evidence}`, ""];
+            const selected = feature.planning?.selected[0];
+            const deferred = feature.planning?.deferred ?? [];
+            const blocked = feature.planning?.blocked ?? [];
+            const deferredText = deferred.length > 0
+                ? deferred.map((item) => `${item.taskId} (${item.reasonCode})`).join(", ")
+                : "none";
+            const blockedText = blocked.length > 0
+                ? blocked.map((item) => `${item.taskId} (${item.reasonCode}${item.blockedBy.length ? `; blockedBy ${item.blockedBy.join(",")}` : ""})`).join(", ")
+                : "none";
+            return [`### ${feature.featureId}`, "", `- Status: ${feature.status}`, `- Next Task: ${selected ? `${selected.taskId} (${selected.priority})` : "none"}`, `- Deferred: ${deferredText}`, `- Blocked: ${blockedText}`, `- Next Action: ${feature.nextAction?.command ?? feature.nextAction?.label ?? "none"}`, `- Why: ${why}`, `- Evidence: ${evidence}`, ""];
         })),
         "## Summary",
         "",
@@ -40,7 +49,8 @@ export async function renderMorningReport(options) {
     ];
     for (const run of runs) {
         const followUp = await followUpSummary(run, options.repoRoot);
-        lines.push(`| ${run.taskId} | ${run.status} | ${run.workerRunId} | ${run.failure?.category ?? "-"} | ${followUp ?? run.failure?.derivedFollowUpTaskId ?? "-"} | ${await artifactSummary(run)} |`);
+        const identity = `${run.featureId}/${run.taskId}`;
+        lines.push(`| ${identity} | ${run.status} | ${run.workerRunId} | ${run.failure?.category ?? "-"} | ${followUp ?? run.failure?.derivedFollowUpTaskId ?? "-"} | ${await artifactSummary(run)} |`);
     }
     if (followUps > 0) {
         lines.push("", "## Human Actions", "");

package/dist/worker/runner/run-ready.js

@@ -4,10 +4,10 @@ import path from "node:path";
 import YAML from "yaml";
 import { controllerIdentitiesMatch, controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
 import { deriveFailureRoute, deriveFailureRouteFromError, } from "../pool/failure-routing.js";
-import { findRunByWorkerRunId, getTaskPoolRoot, readAllTaskPoolStates, recordTaskPoolRun, writeTaskPoolState, } from "../pool/run-store.js";
+import { findRunByWorkerRunId, getTaskPoolRoot, readFeatureTaskPoolStates, recordTaskPoolRun, writeTaskPoolState, } from "../pool/run-store.js";
 import { runTaskSpec, } from "../run-task/run-task.js";
 import { formatDuration, noopProgressReporter, } from "../progress-reporter.js";
-import { computeReadyQueue } from "../task-graph/ready-queue.js";
+import { planReadyTasks } from "../task-graph/ready-planner.js";
 import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
 import { taskSpecSchema } from "../task-spec/schema.js";
 import { preflightTargetRepo } from "../preflight.js";
@@ -34,15 +34,26 @@ export async function runReadyTasks(options) {
     const startedAt = now.toISOString();
     const batchRunId = options.batchRunId ?? buildBatchRunId(now);
     const graph = await loadTaskGraph(options.featureDir);
-    const states = await readAllTaskPoolStates(options.repoRoot);
-    const readyTaskIds = computeReadyQueue(graph, toGraphState(states)).filter((taskId) => isPoolReady(states[taskId]));
-    const limitedTaskIds = readyTaskIds.slice(0, options.limit ?? readyTaskIds.length);
+    const featureId = graph.feature_id;
+    const states = await readFeatureTaskPoolStates(options.repoRoot, featureId);
+    const taskSpecs = await loadFeatureTaskSpecs(options.featureDir, graph);
+    const plan = planReadyTasks({
+        featureId,
+        graph,
+        taskSpecs,
+        states,
+        selectionLimit: options.limit ?? graph.nodes.length,
+    });
+    const limitedTaskIds = plan.selected.map((candidate) => candidate.taskId);
     const tasks = [];
     const runner = options.runTask ?? runTaskSpec;
     const progress = options.progress ?? noopProgressReporter;
     const total = limitedTaskIds.length;
     let index = 0;
     const batchStartedAt = Date.now();
+    const readyPlanPath = path.join(getTaskPoolRoot(options.repoRoot), "artifacts", batchRunId, "ready-plan.json");
+    await mkdir(path.dirname(readyPlanPath), { recursive: true });
+    await writeFile(readyPlanPath, `${JSON.stringify(plan, null, 2)}\n`, "utf-8");
     emit(progress, {
         type: "readyQueue.computed",
         source: "worker",
@@ -61,7 +72,10 @@ export async function runReadyTasks(options) {
         index += 1;
         const node = graph.nodes.find((candidate) => candidate.id === taskId);
         const taskSpecPath = path.join(options.featureDir, "tasks", node?.task ?? `${taskId}.yaml`);
-        const taskSpec = await loadTaskSpec(taskSpecPath);
+        const taskSpec = taskSpecs.get(taskId) ?? await loadTaskSpec(taskSpecPath);
+        if (taskSpec.feature_id !== featureId) {
+            throw new Error(`task ${taskId} feature_id ${taskSpec.feature_id} does not match graph feature_id ${featureId}`);
+        }
         const retryOfWorkerRunId = states[taskId]?.retryOfWorkerRunId;
         let workerRunId = retryOfWorkerRunId
             ? buildRetryWorkerRunId(taskId, retryOfWorkerRunId, now)
@@ -69,14 +83,14 @@ export async function runReadyTasks(options) {
                 buildStableWorkerRunId(taskId, taskSpec, now, controllerIdentity);
         if (workerRunId) {
             let existing = await findRunByWorkerRunId(options.repoRoot, workerRunId);
-            if (existing && !controllerRunCanBeReused(existing, controllerIdentity)) {
+            if (existing && !runCanBeReused(existing, featureId, taskId, controllerIdentity)) {
                 workerRunId = buildControllerScopedWorkerRunId(workerRunId, controllerIdentity);
                 existing = await findRunByWorkerRunId(options.repoRoot, workerRunId);
-                if (existing && !controllerRunCanBeReused(existing, controllerIdentity)) {
-                    throw new Error(`workerRunId collision has incompatible controller identity: ${workerRunId}`);
+                if (existing && !runCanBeReused(existing, featureId, taskId, controllerIdentity)) {
+                    throw new Error(`workerRunId collision has incompatible feature/controller identity: ${workerRunId}`);
                 }
             }
-            if (existing) {
+            if (existing && runCanBeReused(existing, featureId, taskId, controllerIdentity)) {
                 progress.task(`task ${index}/${total} ${taskId}: reuse existing run ${workerRunId}`);
                 emit(progress, {
                     type: "task.reused",
@@ -112,6 +126,8 @@ export async function runReadyTasks(options) {
         let result;
         try {
             await writeTaskPoolState(options.repoRoot, {
+                schemaVersion: 2,
+                featureId,
                 taskId,
                 status: "Running",
                 updatedAt: new Date().toISOString(),
@@ -277,6 +293,12 @@ export async function runReadyTasks(options) {
         summary,
         tasks,
         batchRunPath,
+        readyPlanPath,
+        selectedTaskIds: limitedTaskIds,
+        deferredTaskIds: plan.deferred.map((candidate) => candidate.taskId),
+        orderingPolicy: plan.orderingPolicy,
+        selectionLimit: plan.selectionLimit,
+        effectiveConcurrency: plan.effectiveConcurrency,
         ...(controllerIdentity ? { controllerIdentity } : {}),
     };
     await mkdir(path.dirname(batchRunPath), { recursive: true });
@@ -345,7 +367,9 @@ function buildControllerScopedWorkerRunId(baseWorkerRunId, controllerIdentity) {
         .slice(0, 10);
     return `${baseWorkerRunId}-controller-${hash}`;
 }
-function controllerRunCanBeReused(existing, controllerIdentity) {
+function runCanBeReused(existing, featureId, taskId, controllerIdentity) {
+    if (existing.featureId !== featureId || existing.taskId !== taskId)
+        return false;
     if (!existing.controllerIdentity && !controllerIdentity)
         return true;
     return controllerIdentitiesMatch(existing.controllerIdentity, controllerIdentity);
@@ -370,22 +394,13 @@ async function loadTaskGraph(featureDir) {
 async function loadTaskSpec(taskSpecPath) {
     return taskSpecSchema.parse(YAML.parse(await readFile(taskSpecPath, "utf-8")));
 }
-function toGraphState(states) {
-    const graphState = {};
-    for (const [taskId, state] of Object.entries(states)) {
-        if (state.status === "Done")
-            graphState[taskId] = "completed";
-        if (state.status === "Running" || state.status === "Queued")
-            graphState[taskId] = "running";
-        if (state.status === "Failed")
-            graphState[taskId] = "failed";
-        if (state.status === "Blocked")
-            graphState[taskId] = "blocked";
+async function loadFeatureTaskSpecs(featureDir, graph) {
+    const specs = new Map();
+    for (const node of graph.nodes) {
+        const taskSpec = await loadTaskSpec(path.join(featureDir, "tasks", node.task ?? `${node.id}.yaml`));
+        specs.set(node.id, taskSpec);
     }
-    return graphState;
-}
-function isPoolReady(state) {
-    return !state || state.status === "Ready";
+    return specs;
 }
 function summarize(tasks) {
     return {

package/dist/worker/task-graph/ready-planner.js

@@ -0,0 +1,136 @@
+const OWN_STATUS_REASON = {
+    Draft: "task-draft",
+    Queued: "task-queued",
+    Running: "task-running",
+    AgentCompleted: "task-agent-completed",
+    VerificationRunning: "task-verification-running",
+    HumanReview: "task-human-review",
+    Done: "task-done",
+    Failed: "task-failed",
+    Blocked: "task-blocked",
+    Abandoned: "task-abandoned",
+};
+/** Contract severity: failed > blocked > not-completed > missing-state. */
+function dependencyReason(unmet) {
+    if (unmet.some((item) => item.state === "Failed"))
+        return "dependency-failed";
+    if (unmet.some((item) => item.state === "Blocked"))
+        return "dependency-blocked";
+    if (unmet.some((item) => item.state !== undefined))
+        return "dependency-not-completed";
+    return "dependency-missing-state";
+}
+function ownReason(status) {
+    if (status === "Ready")
+        return undefined;
+    return OWN_STATUS_REASON[status] ?? "task-state-invalid";
+}
+export function planReadyTasks(input) {
+    if (!Number.isInteger(input.selectionLimit) || input.selectionLimit < 1) {
+        throw new Error("selectionLimit must be a positive integer");
+    }
+    const eligible = [];
+    const blocked = [];
+    for (const [graphIndex, node] of input.graph.nodes.entries()) {
+        const spec = input.taskSpecs.get(node.id);
+        if (!spec) {
+            blocked.push({
+                featureId: input.featureId,
+                taskId: node.id,
+                reasonCode: "task-spec-missing",
+                reason: "TaskSpec is missing",
+                blockedBy: [],
+            });
+            continue;
+        }
+        if (spec.id !== node.id || spec.type !== node.type || !same(spec.depends_on, node.depends_on)) {
+            blocked.push({
+                featureId: input.featureId,
+                taskId: node.id,
+                priority: spec.priority,
+                reasonCode: "task-spec-mismatch",
+                reason: "TaskSpec does not match task graph",
+                blockedBy: [],
+            });
+            continue;
+        }
+        const state = input.states[node.id];
+        if (state) {
+            const own = ownReason(state.status);
+            if (own) {
+                blocked.push({
+                    featureId: input.featureId,
+                    taskId: node.id,
+                    priority: spec.priority,
+                    reasonCode: own,
+                    reason: own === "task-state-invalid"
+                        ? `task status is invalid: ${String(state.status)}`
+                        : `task status is ${state.status}`,
+                    blockedBy: [],
+                    currentStatus: state.status,
+                });
+                continue;
+            }
+        }
+        const deps = node.depends_on.map((id) => ({ id, state: input.states[id]?.status }));
+        const unmet = deps.filter(({ state: depState }) => depState !== "Done");
+        if (unmet.length) {
+            blocked.push({
+                featureId: input.featureId,
+                taskId: node.id,
+                priority: spec.priority,
+                reasonCode: dependencyReason(unmet),
+                reason: "dependencies are not completed",
+                blockedBy: unmet.map((item) => item.id),
+            });
+            continue;
+        }
+        eligible.push({
+            featureId: input.featureId,
+            taskId: node.id,
+            title: spec.title,
+            type: spec.type,
+            priority: spec.priority,
+            riskLevel: spec.risk_level,
+            graphIndex,
+            reason: "dependencies-satisfied",
+        });
+    }
+    eligible.sort((a, b) => priority(a.priority) - priority(b.priority) ||
+        a.graphIndex - b.graphIndex ||
+        ascii(a.taskId, b.taskId));
+    const selected = eligible.slice(0, input.selectionLimit);
+    const deferred = eligible.slice(input.selectionLimit).map((candidate) => ({
+        ...candidate,
+        reasonCode: "selection-limit",
+        selectedAhead: selected.map((item) => item.taskId),
+    }));
+    return {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        executionMode: "serial",
+        effectiveConcurrency: 1,
+        selectionLimit: input.selectionLimit,
+        orderingPolicy: ["priority:P0>P1>P2>P3", "graph-order", "task-id"],
+        eligible,
+        blocked,
+        selected,
+        deferred,
+        summary: {
+            total: input.graph.nodes.length,
+            eligible: eligible.length,
+            blocked: blocked.length,
+            selected: selected.length,
+            deferred: deferred.length,
+        },
+    };
+}
+function priority(value) {
+    return { P0: 0, P1: 1, P2: 2, P3: 3 }[value];
+}
+function ascii(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function same(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}

package/dist/workflows/dag/controller-identity.js

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { controllerIdentitiesMatch, resolveRunningControllerIdentity, } from "../../shared/package-metadata.js";
+export const CONTROLLER_IDENTITY_ARTIFACT_NAME = "controller-identity.json";
+function hashArtifact(artifact) {
+    return createHash("sha256")
+        .update(`${JSON.stringify(artifact, null, 2)}\n`)
+        .digest("hex");
+}
+function summaryFields(identity) {
+    if (!identity)
+        return {};
+    return {
+        packageName: identity.packageName,
+        packageVersion: identity.packageVersion,
+        packageFingerprint: identity.packageFingerprint.value,
+        binarySha256: identity.binarySha256,
+    };
+}
+/**
+ * Capture the running controller identity as a run-owned fact and persist it
+ * under `runDir/controller-identity.json`. Returns the ref (with content hash)
+ * to store on DagRunState. When the identity cannot be resolved, records a
+ * `legacy-unpinned` artifact instead of fabricating an identity.
+ */
+export async function captureControllerIdentity(input) {
+    const capturedAt = (input.now ?? new Date()).toISOString();
+    const identity = input.identity !== undefined
+        ? input.identity
+        : (resolveRunningControllerIdentity({
+            ...(input.argv ? { argv: input.argv } : {}),
+            ...(input.now ? { now: input.now } : {}),
+        }) ?? null);
+    const artifact = identity
+        ? { schemaVersion: 1, status: "pinned", capturedAt, identity }
+        : {
+            schemaVersion: 1,
+            status: "legacy-unpinned",
+            capturedAt,
+            identity: null,
+            reason: "running controller identity could not be resolved at run creation",
+        };
+    await writeJsonAtomic(path.join(input.runDir, CONTROLLER_IDENTITY_ARTIFACT_NAME), artifact);
+    return {
+        schemaVersion: 1,
+        path: CONTROLLER_IDENTITY_ARTIFACT_NAME,
+        sha256: hashArtifact(artifact),
+        capturedAt,
+        status: artifact.status,
+        ...summaryFields(identity),
+    };
+}
+export async function readControllerIdentityArtifact(runDir) {
+    try {
+        const raw = await readFile(path.join(runDir, CONTROLLER_IDENTITY_ARTIFACT_NAME), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function shortIdentity(identity) {
+    return `${identity.packageName}@${identity.packageVersion} (fingerprint ${identity.packageFingerprint.value}, binary ${identity.binarySha256.slice(0, 12)})`;
+}
+/**
+ * Recompute the current controller identity and compare it to the pinned run
+ * fact before resuming. Fails closed on drift; reports (without inventing an
+ * identity). Legacy/unpinned runs remain readable but cannot be resumed.
+ */
+export async function verifyControllerIdentityForResume(input) {
+    const ref = input.state.controllerIdentityRef;
+    if (!ref || ref.status === "legacy-unpinned") {
+        throw new Error(`dag run ${input.state.runId} has no pinned controller identity; legacy/unpinned runs remain readable but cannot be resumed safely`);
+    }
+    const artifact = await readControllerIdentityArtifact(input.runDir);
+    if (!artifact) {
+        throw new Error(`dag run ${input.state.runId} is pinned but ${CONTROLLER_IDENTITY_ARTIFACT_NAME} is missing; refuse to resume`);
+    }
+    const persistedHash = createHash("sha256")
+        .update(`${JSON.stringify(artifact, null, 2)}\n`)
+        .digest("hex");
+    if (persistedHash !== ref.sha256) {
+        throw new Error(`dag run ${input.state.runId} controller identity artifact was tampered with (hash mismatch); refuse to resume`);
+    }
+    const pinned = artifact.identity;
+    if (!pinned) {
+        throw new Error(`dag run ${input.state.runId} is pinned but the identity artifact has no identity payload; refuse to resume`);
+    }
+    const current = input.currentIdentity !== undefined
+        ? input.currentIdentity
+        : (resolveRunningControllerIdentity({
+            ...(input.argv ? { argv: input.argv } : {}),
+            ...(input.now ? { now: input.now } : {}),
+        }) ?? null);
+    if (!current) {
+        throw new Error(`dag run ${input.state.runId} was pinned to ${shortIdentity(pinned)} but the current controller identity could not be resolved; refuse to resume`);
+    }
+    if (!controllerIdentitiesMatch(pinned, current)) {
+        throw new Error(`dag run ${input.state.runId} controller identity drifted; pinned=${shortIdentity(pinned)} current=${shortIdentity(current)}; start a new run instead of resuming`);
+    }
+    return { status: "pinned-match", identity: current };
+}

package/dist/workflows/dag/convergence/controller.js

@@ -2,7 +2,7 @@ import { access, appendFile, cp, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { parseProcessVerdict } from "../node-execution.js";
 import { freshNodeRecord } from "../dynamic-runtime/shared.js";
-const CONVERGENCE_CHAIN_NODE_IDS = [
+const DEFAULT_CONVERGENCE_CHAIN_NODE_IDS = [
     "process-supervisor-pi",
     "process-gate-shell",
     "repair-pi",
@@ -29,7 +29,7 @@ export async function runConvergencePassController(input) {
         convergence.terminalReason = "feature-flag-off";
         return { retry: false };
     }
-    if (!hasConvergenceChain(input.tasksById)) {
+    if (!hasConvergenceChain(input.tasksById, input.spec)) {
         convergence.terminalReason = "unsupported-dag-shape";
         return { retry: false };
     }
@@ -54,6 +54,7 @@ export async function runConvergencePassController(input) {
         reason: "hard-verify-failed",
         state: input.state,
         runDir: input.runDir,
+        spec: input.spec,
     });
     if (CONVERGENCE_NON_RETRY_FAILURES.has(hardFailure)) {
         passRecord.status = "terminal";
@@ -96,8 +97,12 @@ export async function runConvergencePassController(input) {
     await input.persistState();
     return { retry: true };
 }
-function hasConvergenceChain(tasksById) {
-    return CONVERGENCE_CHAIN_NODE_IDS.every((id) => tasksById.has(id));
+function getConvergenceChain(spec) {
+    return spec.convergence?.chainNodeIds ?? DEFAULT_CONVERGENCE_CHAIN_NODE_IDS;
+}
+function hasConvergenceChain(tasksById, spec) {
+    const chain = getConvergenceChain(spec);
+    return chain.every((id) => tasksById.has(id));
 }
 async function buildConvergencePassRecord(input) {
     const hardVerify = input.state.nodes["hard-verify-shell"];
@@ -122,13 +127,14 @@ async function buildConvergencePassRecord(input) {
             pass: input.pass,
             state: input.state,
             runDir: input.runDir,
+            spec: input.spec,
         }),
     };
 }
 async function preserveConvergencePassArtifacts(input) {
     const passDir = path.join(input.runDir, "convergence", `pass-${input.pass}`);
     await mkdir(passDir, { recursive: true });
-    const nodeIds = nodesToPreserveForConvergence(input.state);
+    const nodeIds = nodesToPreserveForConvergence(input.state, input.spec);
     const refs = [];
     for (const nodeId of nodeIds) {
         const node = input.state.nodes[nodeId];
@@ -151,8 +157,9 @@ async function preserveConvergencePassArtifacts(input) {
     }
     return refs;
 }
-function nodesToPreserveForConvergence(state) {
-    return CONVERGENCE_CHAIN_NODE_IDS.filter((nodeId) => state.nodes[nodeId]);
+function nodesToPreserveForConvergence(state, spec) {
+    const chain = getConvergenceChain(spec);
+    return chain.filter((nodeId) => state.nodes[nodeId]);
 }
 async function copyIfExists(from, to) {
     try {
@@ -242,7 +249,8 @@ function extractSupervisorStructuredBlock(node) {
     return block;
 }
 async function resetConvergenceNodesForNextPass(input) {
-    const resetIds = new Set(CONVERGENCE_CHAIN_NODE_IDS);
+    const chain = getConvergenceChain(input.spec);
+    const resetIds = new Set(chain);
     for (const id of collectTransitiveDescendantTaskIds(input.spec, "hard-verify-shell")) {
         const node = input.state.nodes[id];
         if (node?.status === "SKIPPED")