@tea-agent/loop-agent 0.16.1-beta.2 → 0.16.2

package/dist/worker/pool/reconcile.js

@@ -0,0 +1,285 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { executeDagReconcileRun } from "../../workflows/dag/reconcile-run.js";
+import { assessDagRunLiveness, assessDagRunRecoveryEligibility, locateDagRun, readDagRunState, } from "../../workflows/dag/lifecycle.js";
+import { appendTaskPoolEvent, findRunByWorkerRunId, getTaskPoolRoot, readTaskPoolState, writeTaskPoolState, } from "./run-store.js";
+const RECOVERABLE_LIVENESS = new Set([
+    "active",
+    "node-quiet",
+    "stale",
+]);
+export async function reconcileTaskPoolAbandon(input) {
+    const reason = input.reason.trim();
+    if (!reason)
+        throw new Error("task reconcile abandon requires --reason <text>");
+    const ref = { featureId: input.featureId, taskId: input.taskId };
+    const current = await readTaskPoolState(input.repoRoot, ref);
+    if (!current) {
+        throw new Error(`cannot reconcile ${input.taskId}: Task Pool state does not exist for ${input.featureId}/${input.taskId}`);
+    }
+    if (current.status === "Done") {
+        throw new Error(`cannot reconcile ${input.taskId}: Task Pool status is Done`);
+    }
+    const { run, dagLocated } = await validateWorkerDagAssociation({
+        repoRoot: input.repoRoot,
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        dagRunId: input.dagRunId,
+    });
+    const dagState = await readDagRunState(dagLocated.runDir);
+    const liveness = assessDagRunLiveness({ state: dagState });
+    const eligibility = assessDagRunRecoveryEligibility({
+        lifecycle: dagLocated.lifecycle,
+        state: dagState,
+        liveness: liveness.status,
+    });
+    const alreadyAbandoned = dagLocated.lifecycle === "completed" &&
+        (dagState.status === "abandoned" || dagState.reconciliation?.action === "abandon");
+    const poolAlreadyFailed = current.status === "Failed" &&
+        current.workerRunId === input.workerRunId &&
+        current.operatorRecovery?.action === "task-reconcile-abandon";
+    if (poolAlreadyFailed && alreadyAbandoned) {
+        const evidencePath = current.operatorRecovery?.evidencePath ??
+            recoveryEvidencePath(input.repoRoot, input.featureId, input.taskId, input.workerRunId);
+        return {
+            schemaVersion: 1,
+            status: "Failed",
+            taskId: input.taskId,
+            featureId: input.featureId,
+            workerRunId: input.workerRunId,
+            dagRunId: input.dagRunId,
+            idempotent: true,
+            evidencePath,
+        };
+    }
+    assertAbandonAllowed({
+        eligibility,
+        liveness: liveness.status,
+        forceAbandonRecoverable: input.forceAbandonRecoverable === true,
+        dagRunId: input.dagRunId,
+    });
+    let dagReconcile;
+    if (!alreadyAbandoned) {
+        dagReconcile = await executeDagReconcileRun(input.repoRoot, [
+            "--run-id",
+            input.dagRunId,
+            "--action",
+            "abandon",
+            "--reason",
+            reason,
+        ]);
+    }
+    const at = (input.now ?? new Date()).toISOString();
+    const evidencePath = await writeRecoveryEvidence(input.repoRoot, {
+        kind: "task-reconcile-abandon",
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        dagRunId: input.dagRunId,
+        reason,
+        at,
+        runRecordPath: run.runRecordPath,
+        dagReconcile,
+    });
+    const operatorRecovery = {
+        action: "task-reconcile-abandon",
+        reason,
+        workerRunId: input.workerRunId,
+        dagRunId: input.dagRunId,
+        abandonedWorkerRunId: input.workerRunId,
+        at,
+        evidencePath: path.relative(input.repoRoot, evidencePath).split(path.sep).join("/"),
+    };
+    await projectTaskPoolFailed(input.repoRoot, current, {
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        updatedAt: at,
+        operatorRecovery,
+    });
+    await appendTaskPoolEvent(input.repoRoot, {
+        schemaVersion: 1,
+        at,
+        type: "task-reconcile-abandon",
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        dagRunId: input.dagRunId,
+        reason,
+        idempotent: false,
+        evidencePath: operatorRecovery.evidencePath,
+    });
+    return {
+        schemaVersion: 1,
+        status: "Failed",
+        taskId: input.taskId,
+        featureId: input.featureId,
+        workerRunId: input.workerRunId,
+        dagRunId: input.dagRunId,
+        idempotent: false,
+        ...(dagReconcile ? { dagReconcile } : {}),
+        evidencePath: operatorRecovery.evidencePath,
+    };
+}
+export async function markTaskPoolFailed(input) {
+    const reason = input.reason.trim();
+    if (!reason)
+        throw new Error("pool mark-failed requires --reason <text>");
+    await validateWorkerRunOwnership({
+        repoRoot: input.repoRoot,
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+    });
+    const ref = { featureId: input.featureId, taskId: input.taskId };
+    const current = await readTaskPoolState(input.repoRoot, ref);
+    if (!current) {
+        throw new Error(`cannot mark-failed ${input.taskId}: Task Pool state does not exist for ${input.featureId}/${input.taskId}`);
+    }
+    if (current.status === "Done") {
+        throw new Error(`cannot mark-failed ${input.taskId}: Task Pool status is Done`);
+    }
+    const at = (input.now ?? new Date()).toISOString();
+    const evidencePath = recoveryEvidencePath(input.repoRoot, input.featureId, input.taskId, input.workerRunId);
+    const relativeEvidencePath = path.relative(input.repoRoot, evidencePath).split(path.sep).join("/");
+    if (current.status === "Failed" &&
+        current.workerRunId === input.workerRunId &&
+        current.operatorRecovery?.action === "pool-mark-failed") {
+        return {
+            schemaVersion: 1,
+            status: "Failed",
+            taskId: input.taskId,
+            featureId: input.featureId,
+            workerRunId: input.workerRunId,
+            idempotent: true,
+            evidencePath: current.operatorRecovery.evidencePath ?? relativeEvidencePath,
+        };
+    }
+    await writeRecoveryEvidence(input.repoRoot, {
+        kind: "pool-mark-failed",
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        reason,
+        at,
+    });
+    const operatorRecovery = {
+        action: "pool-mark-failed",
+        reason,
+        workerRunId: input.workerRunId,
+        at,
+        evidencePath: relativeEvidencePath,
+        note: "emergency Task Pool projection; does not mutate DAG lifecycle",
+    };
+    await projectTaskPoolFailed(input.repoRoot, current, {
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        updatedAt: at,
+        operatorRecovery,
+    });
+    await appendTaskPoolEvent(input.repoRoot, {
+        schemaVersion: 1,
+        at,
+        type: "task-pool-mark-failed",
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        reason,
+        idempotent: false,
+        evidencePath: relativeEvidencePath,
+    });
+    return {
+        schemaVersion: 1,
+        status: "Failed",
+        taskId: input.taskId,
+        featureId: input.featureId,
+        workerRunId: input.workerRunId,
+        idempotent: false,
+        evidencePath: relativeEvidencePath,
+    };
+}
+async function validateWorkerDagAssociation(input) {
+    const run = await validateWorkerRunOwnership(input);
+    const dagLocated = await locateDagRun(input.repoRoot, input.dagRunId);
+    if (!dagLocated) {
+        throw new Error(`dag run not found: ${input.dagRunId}`);
+    }
+    const dagState = await readDagRunState(dagLocated.runDir);
+    if (dagState.runId !== input.dagRunId) {
+        throw new Error(`dag run identity mismatch: expected ${input.dagRunId}, found ${dagState.runId}`);
+    }
+    const linked = await proveWorkerDagLink(input.repoRoot, run, input.workerRunId, input.dagRunId);
+    if (!linked) {
+        throw new Error(`worker run ${input.workerRunId} is not associated with dag run ${input.dagRunId}`);
+    }
+    return { run, dagLocated: { ...dagLocated, runId: input.dagRunId } };
+}
+async function validateWorkerRunOwnership(input) {
+    const run = await findRunByWorkerRunId(input.repoRoot, input.workerRunId);
+    if (!run) {
+        throw new Error(`worker run not found: ${input.workerRunId}`);
+    }
+    if (run.featureId !== input.featureId || run.taskId !== input.taskId) {
+        throw new Error(`worker run ownership mismatch: expected ${input.featureId}/${input.taskId}, found ${run.featureId}/${run.taskId}`);
+    }
+    return run;
+}
+async function proveWorkerDagLink(repoRoot, run, workerRunId, dagRunId) {
+    if (dagRunId === workerRunId)
+        return true;
+    if (!run.runRecordPath)
+        return false;
+    try {
+        const absolutePath = path.isAbsolute(run.runRecordPath)
+            ? run.runRecordPath
+            : path.join(repoRoot, run.runRecordPath);
+        const record = JSON.parse(await readFile(absolutePath, "utf-8"));
+        for (const command of record.commands ?? []) {
+            const args = command.args ?? [];
+            const runIdIndex = args.indexOf("--run-id");
+            if (runIdIndex >= 0 && args[runIdIndex + 1] === dagRunId)
+                return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+function assertAbandonAllowed(input) {
+    if (input.forceAbandonRecoverable)
+        return;
+    if (input.eligibility.canResume) {
+        throw new Error(`dag run ${input.dagRunId} is recoverable via resume; refuse abandon or pass --force-abandon-recoverable with documented operator intent`);
+    }
+    if (RECOVERABLE_LIVENESS.has(input.liveness)) {
+        throw new Error(`dag run ${input.dagRunId} liveness is ${input.liveness}; refuse abandon or pass --force-abandon-recoverable with documented operator intent`);
+    }
+}
+async function projectTaskPoolFailed(repoRoot, current, next) {
+    await writeTaskPoolState(repoRoot, {
+        schemaVersion: 2,
+        featureId: next.featureId,
+        taskId: next.taskId,
+        status: "Failed",
+        updatedAt: next.updatedAt,
+        workerRunId: next.workerRunId,
+        ...(current.lastRunRecordPath ? { lastRunRecordPath: current.lastRunRecordPath } : {}),
+        ...(current.failure ? { failure: current.failure } : {}),
+        ...(current.retryOfWorkerRunId ? { retryOfWorkerRunId: current.retryOfWorkerRunId } : {}),
+        ...(current.retryRequestedAt ? { retryRequestedAt: current.retryRequestedAt } : {}),
+        ...(current.retryReason ? { retryReason: current.retryReason } : {}),
+        operatorRecovery: next.operatorRecovery,
+    });
+}
+function recoveryEvidencePath(repoRoot, featureId, taskId, workerRunId) {
+    return path.join(getTaskPoolRoot(repoRoot), "artifacts", "recovery", featureId, taskId, `${workerRunId}.json`);
+}
+async function writeRecoveryEvidence(repoRoot, payload) {
+    const evidencePath = recoveryEvidencePath(repoRoot, payload.featureId, payload.taskId, payload.workerRunId);
+    await mkdir(path.dirname(evidencePath), { recursive: true });
+    await writeFile(evidencePath, `${JSON.stringify({ schemaVersion: 1, ...payload }, null, 2)}\n`, "utf-8");
+    return evidencePath;
+}

package/dist/worker/run-task/run-task.js

@@ -124,6 +124,7 @@ export async function runTaskSpec(options) {
     });
     progress.step(`run-dag finished in ${formatDuration(Date.now() - runDagStartedAt)}`);
     const reportStep = "report-decision";
+    let capturedReportJson;
     const reportDecision = await runObservedStep(eventCtx, reportStep, async () => {
         const reportJson = await client.run([
             "dag",
@@ -138,6 +139,7 @@ export async function runTaskSpec(options) {
             artifactName: "dag-report-json",
             expectJson: true,
         });
+        capturedReportJson = reportJson;
         const decision = decideFromReport(workerRunId, reportJson);
         await client.run([
             "dag",
@@ -153,6 +155,14 @@ export async function runTaskSpec(options) {
         });
         return decision;
     }, { statusForResult: (decision) => decision.succeeded ? "succeeded" : "failed" });
+    const dagReportRun = extractDagReportRun(workerRunId, capturedReportJson);
+    const declaredArtifacts = options.declaredArtifacts
+        ? options.declaredArtifacts.map((entry) => ({
+            kind: entry.kind,
+            ...(entry.schemaId ? { schemaId: entry.schemaId } : {}),
+            ...(entry.path ? { path: entry.path } : {}),
+        }))
+        : undefined;
     let status = reportDecision.succeeded ? "succeeded" : "failed";
     progress.step(`report decision: ${status} (${reportDecision.reason}${reportDecision.runStatus ? `, status=${reportDecision.runStatus}` : ""})`);
     const failureArtifacts = reportDecision.succeeded
@@ -180,6 +190,7 @@ export async function runTaskSpec(options) {
         materializeManifest,
         reportDecision,
         commands,
+        ...(declaredArtifacts ? { declaredArtifacts } : {}),
         ...(failureArtifacts ? { failureArtifacts } : {}),
         ...(controllerIdentity ? { controllerIdentity } : {}),
     };
@@ -202,6 +213,8 @@ export async function runTaskSpec(options) {
         reportDecision,
         runRecordPath,
         dagPath,
+        ...(dagReportRun ? { dagReportRun } : {}),
+        ...(declaredArtifacts ? { declaredArtifacts } : {}),
         acceptanceRefs: options.taskSpec.acceptance_refs,
         now,
     });
@@ -211,15 +224,34 @@ export async function runTaskSpec(options) {
         progress.step(`outcome projection failed: ${projection.category} (${projection.reason})`);
     }
     else {
-        const gate = checkRequiredOutputs(projection.envelope, options.taskSpec.outputs.required);
+        let envelope = projection.envelope;
+        const gate = checkRequiredOutputs(envelope, options.taskSpec.outputs.required);
         if (reportDecision.succeeded && !gate.passed) {
             status = "failed";
-            outcomeFailure = { category: "ContractMismatch", reason: `missing required outputs: ${gate.missing.join(", ")}` };
+            outcomeFailure = {
+                category: "ContractMismatch",
+                reason: `missing required outputs: ${gate.missing.join(", ")}`,
+            };
+            envelope = {
+                ...envelope,
+                outcomeStatus: "failed",
+                outcomeFailure: {
+                    category: "ContractMismatch",
+                    reason: `missing required outputs: ${gate.missing.join(", ")}`,
+                    missingOutputs: [...gate.missing],
+                },
+            };
             progress.step(`required output gate failed: ${gate.missing.join(", ")}`);
         }
-        else {
-            outcome = await writeOutcome(options.repoRoot, projection.envelope);
+        else if (envelope.outcomeFailure) {
+            outcomeFailure = {
+                category: envelope.outcomeFailure.category,
+                reason: envelope.outcomeFailure.reason,
+            };
         }
+        // Persist succeeded and failed envelopes so read models can inspect
+        // outcomeFailure without re-parsing run-record / report decision.
+        outcome = await writeOutcome(options.repoRoot, envelope);
     }
     if (status === "succeeded" && !options.skipSuccessFinalization) {
         await runObservedStep(eventCtx, "promote-run", async () => {
@@ -245,6 +277,7 @@ export async function runTaskSpec(options) {
         materializeManifest,
         reportDecision,
         commands,
+        ...(declaredArtifacts ? { declaredArtifacts } : {}),
         ...(failureArtifacts ? { failureArtifacts } : {}),
         ...(controllerIdentity ? { controllerIdentity } : {}),
     };
@@ -470,6 +503,50 @@ function decideFromReport(workerRunId, result) {
         primaryFailure: readProperty(run, "primaryFailure"),
     };
 }
+/**
+ * Extract the canonical DAG report run fact used by Outcome adapters for
+ * structured artifact projection. Returns undefined when the report is missing
+ * or does not contain the worker run — adapters then project only canonical
+ * runtime artifacts (fail-closed for domain structured kinds).
+ */
+function extractDagReportRun(workerRunId, result) {
+    if (!result?.ok || !result.json)
+        return undefined;
+    const runs = readObjectArray(result.json, "runs");
+    const run = runs.find((candidate) => readString(candidate, "runId") === workerRunId) ??
+        runs[0];
+    if (!run)
+        return undefined;
+    const nodes = readObjectArray(run, "nodes").map((node) => ({
+        ...(readString(node, "nodeId") || readString(node, "id")
+            ? { id: readString(node, "nodeId") ?? readString(node, "id") }
+            : {}),
+        ...(readString(node, "status") ? { status: readString(node, "status") } : {}),
+        ...(readString(node, "failureCategory")
+            ? { failureCategory: readString(node, "failureCategory") }
+            : {}),
+        ...(readString(node, "stdoutArtifactPath")
+            ? { stdoutArtifactPath: readString(node, "stdoutArtifactPath") }
+            : {}),
+        ...(readString(node, "assistantArtifactPath")
+            ? { assistantArtifactPath: readString(node, "assistantArtifactPath") }
+            : {}),
+        ...(readString(node, "structuredArtifactPath")
+            ? { structuredArtifactPath: readString(node, "structuredArtifactPath") }
+            : {}),
+        ...(readString(node, "structuredArtifactSha256")
+            ? { structuredArtifactSha256: readString(node, "structuredArtifactSha256") }
+            : {}),
+        ...(readString(node, "structuredArtifactSchemaId")
+            ? { structuredArtifactSchemaId: readString(node, "structuredArtifactSchemaId") }
+            : {}),
+    }));
+    return {
+        ...(readString(run, "runId") ? { runId: readString(run, "runId") } : {}),
+        ...(readString(run, "status") ? { status: readString(run, "status") } : {}),
+        nodes,
+    };
+}
 class RecordingRunTaskClient {
     delegate;
     records;

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

@@ -158,6 +158,15 @@ export async function runReadyTasks(options) {
                 ...(options.piModel ? { piModel: options.piModel } : {}),
                 ...(controllerIdentity ? { controllerIdentity } : {}),
                 ...(options.controllerExpectation ? { controllerExpectation: options.controllerExpectation } : {}),
+                ...(node?.produces && node.produces.length > 0
+                    ? {
+                        declaredArtifacts: node.produces.map((entry) => ({
+                            kind: entry.kind,
+                            ...(entry.schemaId ? { schemaId: entry.schemaId } : {}),
+                            ...(entry.path ? { path: entry.path } : {}),
+                        })),
+                    }
+                    : {}),
             });
         }
         catch (error) {
@@ -271,6 +280,17 @@ export async function runReadyTasks(options) {
         };
         let recorded = false;
         try {
+            // Checkpoint (onTaskFinalized) must succeed before Task Pool Done for
+            // successful runs. Recording Done first left Pool Done with no Git
+            // checkpoint when promote/closeout wrote outside allowed_paths.
+            if (result.status === "succeeded" && options.onTaskFinalized) {
+                await options.onTaskFinalized({
+                    status: result.status,
+                    taskSpec,
+                    workerRunId: result.workerRunId,
+                    runRecordPath: result.runRecordPath,
+                });
+            }
             await recordTaskPoolRun({ repoRoot: options.repoRoot, run });
             recorded = true;
             tasks.push({
@@ -281,7 +301,9 @@ export async function runReadyTasks(options) {
             });
         }
         catch (error) {
-            await options.onTaskFinalized?.({ status: result.status, taskSpec, workerRunId: result.workerRunId, runRecordPath: result.runRecordPath });
+            if (result.status !== "succeeded") {
+                await options.onTaskFinalized?.({ status: result.status, taskSpec, workerRunId: result.workerRunId, runRecordPath: result.runRecordPath });
+            }
             tasks.push({
                 taskId,
                 workerRunId: result.workerRunId,
@@ -291,8 +313,9 @@ export async function runReadyTasks(options) {
             });
             break;
         }
-        if (recorded)
+        if (recorded && result.status !== "succeeded") {
             await options.onTaskFinalized?.({ status: result.status, taskSpec, workerRunId: result.workerRunId, runRecordPath: result.runRecordPath });
+        }
     }
     const summary = summarize(tasks);
     const batchRunPath = path.join(getTaskPoolRoot(options.repoRoot), "artifacts", batchRunId, "batch-run.json");

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

@@ -155,12 +155,15 @@ export function planReadyTasks(input) {
  * Evaluate artifact-gate eligibility for a node whose dependencies are all
  * `Done`. Returns the first blocking projection, or `undefined` when eligible.
  *
- * Fail-closed: any unverified producer path/hash/schema/feature/producer/source
- * binding blocks the consumer as `required-artifact-missing` and never becomes
- * Ready. When `outcomes` is not provided, eligibility is skipped (M3 keeps
- * callers that have not wired disk injection unchanged). Hash byte-level
- * verification is the caller's responsibility before injecting an envelope;
- * the planner trusts `envelope.artifacts[].sha256` as a literal.
+ * Envelope-level binding only: Feature / producer task / kind / optional
+ * schemaId / optional sourceBinding must match the injected Outcome. The
+ * planner is pure and synchronous — it does **not** re-read artifact files or
+ * recompute sha256. Callers must inject envelopes via `readVerifiedOutcome`
+ * (path/hash of the outcome JSON). File-level artifact sha256 is enforced at
+ * `projectOutcome` and again at Feature Verification Bundle / verify-final /
+ * Delivery / Closeout (`verifyArtifactRefs`).
+ *
+ * When `outcomes` is omitted, this gate is skipped (legacy callers unchanged).
  */
 function evaluateArtifactGate(consumes, featureId, states, outcomes, producerKinds) {
     if (!outcomes || !consumes || consumes.length === 0)
@@ -230,8 +233,11 @@ function evaluateArtifactRef(ref, featureId, states, outcomes) {
     if (!artifact) {
         return projection("artifact-kind-absent", `no artifact with kind ${ref.kind}`);
     }
-    if (ref.schemaId !== undefined && artifact.kind !== ref.schemaId) {
-        return projection("schema-mismatch", `artifact kind ${String(artifact.kind)} != schemaId ${ref.schemaId}`);
+    if (ref.schemaId !== undefined) {
+        const artifactSchemaId = artifact.schemaId ?? artifact.kind;
+        if (artifactSchemaId !== ref.schemaId) {
+            return projection("schema-mismatch", `artifact schemaId ${String(artifactSchemaId)} != ${ref.schemaId}`);
+        }
     }
     if (ref.sourceBinding) {
         const envBinding = envelope.sourceBinding;

package/dist/worker/task-graph/task-graph-schema.js

@@ -9,9 +9,11 @@ export const artifactDeclSchema = z
 })
     .strict();
 /**
- * Consumer-side artifact reference. A node may only trust an upstream Task
- * Outcome artifact after deterministic path, hash, schema, feature,
- * producer-task and source-binding validation (see ready-planner gate).
+ * Consumer-side artifact reference. Ready Planner validates envelope-level
+ * Feature / producer / kind / optional schemaId / optional sourceBinding.
+ * File-level path+sha256 of artifact bytes is enforced at Outcome projection
+ * and Feature Verification Bundle / Delivery / Closeout — not inside the
+ * synchronous Ready Planner.
  */
 export const artifactRefSchema = z
     .object({