@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.3

package/dist/workflows/dag/frontend-recovery-controller.js

@@ -0,0 +1,201 @@
+import { isTerminalOperationState, } from "../../worker/console/operation-store.js";
+import { runOperation, } from "../../worker/console/operation-runner.js";
+import { buildFailureCapsule, classifyFailureOwner, projectProtocolFailureReason, } from "./frontend-recovery-capsule.js";
+import { computeNormalizedFailureFingerprint, evaluateNonConvergence, foldOperationBudgets, } from "./frontend-recovery-lineage.js";
+import { projectedInterruptStatus, } from "./interrupt-request.js";
+import { evaluateNodeLiveness, } from "./liveness-policy.js";
+/**
+ * Deterministic legacy Console operation-state → canonical frontend
+ * operation-state/terminal projection. This is the single adapter-layer
+ * projection at the controller boundary; the generic Console operation schema
+ * is not changed (AC-001).
+ */
+export function projectLegacyOperationState(state) {
+    switch (state) {
+        case "queued":
+        case "starting":
+        case "running":
+            return { operationState: "active" };
+        case "succeeded":
+            return { operationState: "success", operationTerminal: "success" };
+        case "failed":
+        case "timed-out":
+        case "needs-reconcile":
+            return {
+                operationState: "failed-internal",
+                operationTerminal: "failed-internal",
+            };
+    }
+}
+/**
+ * Conservative default recovery mode by owner. Non-writer owners restart as a
+ * new DAG; environment issues wait for the external dependency; unknown never
+ * auto-selects writer recovery (AC-003).
+ */
+export function projectDefaultRecoveryMode(owner) {
+    switch (owner) {
+        case "contract":
+        case "scout":
+        case "plan":
+        case "implementation":
+        case "verification-config":
+        case "scope":
+            return "new-dag";
+        case "environment":
+            return "wait-external";
+        case "unknown":
+            return "none";
+    }
+}
+function buildCapsuleOnTerminal(input) {
+    const protocolFailureReason = projectProtocolFailureReason(input.protocolFailureReason);
+    if (input.terminalReason === "non-converging") {
+        return buildFailureCapsule({
+            parentRunId: input.parentRunId,
+            operationState: "non-converging",
+            recoveryMode: "none",
+            protocolFailureReason,
+            failureOwner: input.owner,
+            evidenceRefs: [],
+        });
+    }
+    return buildFailureCapsule({
+        parentRunId: input.parentRunId,
+        operationState: "recoverable",
+        recoveryMode: input.deps.recoveryMode ?? projectDefaultRecoveryMode(input.owner),
+        protocolFailureReason,
+        failureOwner: input.owner,
+        evidenceRefs: [],
+    });
+}
+export async function runRecoveryOperationController(input) {
+    const { operationId, parentRunId, deps } = input;
+    const maxAttempts = Math.max(1, deps.maxAttempts ?? 5);
+    const now = deps.now ?? (() => new Date());
+    const readInterrupt = deps.readInterrupt ?? (async () => undefined);
+    const readLedgers = deps.readLedgers ?? (async () => []);
+    const readChangedFiles = deps.readChangedFiles ?? (async () => []);
+    const fingerprints = [...(deps.previousFingerprints ?? [])];
+    let budgetAggregate;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const operation = await deps.store.get(operationId);
+        if (!operation) {
+            return {
+                terminalReason: "operation-not-found",
+                attempts: attempt,
+                fingerprints,
+                detail: `operation not found: ${operationId}`,
+            };
+        }
+        // Total budget fold + hard stop (resource protection, fail-closed).
+        const ledgers = await readLedgers();
+        if (deps.budget) {
+            budgetAggregate = foldOperationBudgets({
+                ledgers,
+                budget: deps.budget,
+                now,
+            });
+        }
+        if (budgetAggregate?.status === "breached") {
+            return {
+                terminalReason: "budget-exhausted",
+                attempts: attempt,
+                budgetAggregate,
+                fingerprints,
+                detail: "operation total budget breached",
+            };
+        }
+        const owner = deps.failureOwner ??
+            classifyFailureOwner({
+                rawFailureCategory: operation.errorCode,
+                nodeId: operationId,
+            });
+        const protocolFailureReason = deps.protocolFailureReason ??
+            operation.errorMessage ??
+            operation.errorCode ??
+            "unknown failure";
+        if (isTerminalOperationState(operation.state)) {
+            if (operation.state === "succeeded") {
+                return {
+                    terminalReason: "succeeded",
+                    attempts: attempt,
+                    budgetAggregate,
+                    fingerprints,
+                };
+            }
+            // Failed/timed-out: fingerprint the failure and stop if it repeats.
+            fingerprints.push(computeNormalizedFailureFingerprint({
+                failureOwner: owner,
+                protocolFailureReason,
+                invalidatedFactIds: [],
+            }));
+            const nonConvergence = evaluateNonConvergence({
+                fingerprints,
+                changedFiles: await readChangedFiles(),
+                // Budget breach already short-circuited above; fail-closed here.
+                budgetBreached: false,
+            });
+            if (nonConvergence.terminal) {
+                return {
+                    terminalReason: nonConvergence.terminalReason,
+                    attempts: attempt,
+                    budgetAggregate,
+                    fingerprints,
+                    capsule: buildCapsuleOnTerminal({
+                        parentRunId,
+                        deps,
+                        owner,
+                        protocolFailureReason,
+                        terminalReason: "non-converging",
+                    }),
+                    detail: nonConvergence.reason,
+                };
+            }
+            return {
+                terminalReason: "failed",
+                attempts: attempt,
+                budgetAggregate,
+                fingerprints,
+                capsule: buildCapsuleOnTerminal({
+                    parentRunId,
+                    deps,
+                    owner,
+                    protocolFailureReason,
+                    terminalReason: "failed",
+                }),
+            };
+        }
+        // Non-terminal: gate on liveness + interrupt before advancing.
+        const liveness = evaluateNodeLiveness({ node: deps.node ?? {}, now: now() });
+        if (liveness.status === "needs-attention") {
+            return {
+                terminalReason: "needs-attention",
+                attempts: attempt,
+                budgetAggregate,
+                fingerprints,
+                detail: "node liveness requires attention; abort recovery loop",
+            };
+        }
+        const interrupt = await readInterrupt();
+        const projected = projectedInterruptStatus(interrupt);
+        if (projected === "requested" ||
+            projected === "acknowledged" ||
+            projected === "needs-reconcile") {
+            return {
+                terminalReason: "interrupted",
+                attempts: attempt,
+                budgetAggregate,
+                fingerprints,
+                detail: `interrupt projection: ${projected}`,
+            };
+        }
+        await runOperation(operationId, deps.operationRunnerDeps);
+    }
+    return {
+        terminalReason: "max-attempts",
+        attempts: maxAttempts,
+        budgetAggregate,
+        fingerprints,
+        detail: `recovery loop exceeded maxAttempts=${maxAttempts}`,
+    };
+}

package/dist/workflows/dag/frontend-recovery-lineage.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { assembleCumulativeDiffContext, } from "./frontend-review-context.js";
+import { deterministicSha256 } from "./frontend-implementation-contract.js";
+/**
+ * M6 candidate lineage + operation budget primitives (pure functions).
+ *
+ * Self-contained types only: this module never extends `DagRunState`/`DagSpec`
+ * and never mutates the legacy operation/budget modules — it only imports them.
+ * Candidate lineage distinguishes a committed parent candidate (retained into
+ * lineage) from an uncommitted partial write (CAS-rolled back, never retained).
+ */
+const hash64 = z.string().regex(/^[a-f0-9]{64}$/);
+/* ------------------------------------------------------------------ *
+ * Commit state (AC-002).                                              *
+ * ------------------------------------------------------------------ */
+export const commitStateSchema = z.enum([
+    "uncommitted-partial",
+    "committed-candidate",
+]);
+/**
+ * Deterministic commit-state classifier. A journal that reached `completed`
+ * (or a restore result that did) means the parent candidate was committed and
+ * must be retained into lineage. Anything else — `blocked`, an uncommitted
+ * half-write, or a rollback that could not be proven — is fail-closed to
+ * `uncommitted-partial` and is never retained.
+ */
+export function classifyCommitState(input) {
+    if (input.journalState === "completed") {
+        return "committed-candidate";
+    }
+    if (input.restoreResult?.state === "completed") {
+        return "committed-candidate";
+    }
+    return "uncommitted-partial";
+}
+/* ------------------------------------------------------------------ *
+ * Candidate lineage (AC-002).                                         *
+ * ------------------------------------------------------------------ */
+export const candidateLineageV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    taskBaselineHash: hash64,
+    parentRunId: z.string().min(1),
+    parentCandidateHash: hash64,
+    runBaselineHash: hash64,
+    runDeltaHash: hash64,
+    cumulativeDiffHash: hash64,
+    commitState: commitStateSchema,
+})
+    .strict();
+/**
+ * taskBaseline → candidate cumulative diff digest (AC-004). Reuses the
+ * deterministic `assembleCumulativeDiffContext` and returns only its
+ * `cumulativeDigest`, so the lineage hash is stable regardless of input order.
+ */
+export function computeCumulativeDiffHash(input) {
+    return assembleCumulativeDiffContext(input).cumulativeDigest;
+}
+function pushAggregateBreach(aggregate, dimension, consumed, limit, now) {
+    if (limit === undefined || consumed <= limit)
+        return;
+    const duplicate = aggregate.breaches.some((existing) => existing.dimension === dimension && existing.limit === limit);
+    if (!duplicate) {
+        aggregate.breaches.push({
+            dimension,
+            limit,
+            consumed,
+            at: now().toISOString(),
+        });
+    }
+    if (aggregate.mode === "hard") {
+        aggregate.status = "breached";
+    }
+}
+/**
+ * Fold parent + all continuation/recovery run ledgers into a single operation
+ * budget aggregate and evaluate it against the operation total `CampaignBudget`
+ * limits. Missing token samples never count as zero (aligned with the ledger
+ * contract): if any ledger lacks a token total, the aggregate token total is
+ * `null` and no token breach is derived.
+ */
+export function foldOperationBudgets(input) {
+    const now = input.now ?? (() => new Date());
+    const aggregate = {
+        schemaVersion: 1,
+        mode: input.budget.mode,
+        limits: { ...input.budget.limits },
+        consumed: {
+            executorCalls: 0,
+            wallTimeMs: 0,
+            tokens: null,
+            repairPasses: 0,
+            peakContextChars: 0,
+            missingTokenNodeIds: [],
+        },
+        breaches: [],
+        status: input.budget.mode === "record-only" ? "record-only" : "ok",
+    };
+    let anyUnknownTokens = false;
+    let knownTokenSum = 0;
+    const missing = new Set();
+    for (const ledger of input.ledgers) {
+        aggregate.consumed.executorCalls += ledger.consumed.executorCalls;
+        aggregate.consumed.wallTimeMs += ledger.consumed.wallTimeMs;
+        aggregate.consumed.repairPasses += ledger.consumed.repairPasses;
+        aggregate.consumed.peakContextChars = Math.max(aggregate.consumed.peakContextChars, ledger.consumed.peakContextChars);
+        if (ledger.consumed.tokens === null) {
+            anyUnknownTokens = true;
+        }
+        else {
+            knownTokenSum += ledger.consumed.tokens;
+        }
+        for (const nodeId of ledger.consumed.missingTokenNodeIds) {
+            missing.add(nodeId);
+        }
+        aggregate.breaches.push(...ledger.breaches);
+    }
+    aggregate.consumed.tokens = anyUnknownTokens ? null : knownTokenSum;
+    aggregate.consumed.missingTokenNodeIds = [...missing].sort((a, b) => a.localeCompare(b));
+    if (aggregate.mode === "hard") {
+        const limits = aggregate.limits;
+        pushAggregateBreach(aggregate, "executorCalls", aggregate.consumed.executorCalls, limits.maxExecutorCalls, now);
+        pushAggregateBreach(aggregate, "wallTimeMs", aggregate.consumed.wallTimeMs, limits.maxWallTimeMs, now);
+        pushAggregateBreach(aggregate, "repairPasses", aggregate.consumed.repairPasses, limits.maxRepairPasses, now);
+        pushAggregateBreach(aggregate, "contextChars", aggregate.consumed.peakContextChars, limits.maxContextChars, now);
+        if (aggregate.consumed.tokens !== null) {
+            pushAggregateBreach(aggregate, "tokens", aggregate.consumed.tokens, limits.maxTokens, now);
+        }
+    }
+    return aggregate;
+}
+/**
+ * Stable, pure failure fingerprint. No wall clock, no random bytes: identical
+ * inputs always produce the same digest, so repeated failures across recovery
+ * runs can be compared for non-convergence detection.
+ */
+export function computeNormalizedFailureFingerprint(input) {
+    const payload = {
+        failureOwner: input.failureOwner ?? "unknown",
+        protocolFailureReason: input.protocolFailureReason ?? "",
+        restartPhase: input.restartPhase ?? "unknown",
+        invalidatedFactIds: [...(input.invalidatedFactIds ?? [])].sort(),
+        commitState: input.commitState ?? "uncommitted-partial",
+    };
+    return deterministicSha256(payload);
+}
+/**
+ * Bounded-loop stop decision. A repeated failure fingerprint with an empty
+ * change manifest proves no workspace progress → `non-converging`. An exceeded
+ * operation total budget → `budget-exhausted`. Otherwise continue (but never
+ * unbounded: the controller still caps attempts).
+ */
+export function evaluateNonConvergence(input) {
+    if (input.budgetBreached) {
+        return {
+            terminal: true,
+            terminalReason: "budget-exhausted",
+            reason: "operation total budget breached; stop before exhausting resources",
+        };
+    }
+    const counts = new Map();
+    for (const fingerprint of input.fingerprints) {
+        counts.set(fingerprint, (counts.get(fingerprint) ?? 0) + 1);
+    }
+    const repeated = [...counts.values()].some((count) => count >= 2);
+    if (repeated && input.changedFiles.length === 0) {
+        return {
+            terminal: true,
+            terminalReason: "non-converging",
+            reason: "repeated failure fingerprint with an empty change manifest; recovery would loop forever",
+        };
+    }
+    return {
+        terminal: false,
+        terminalReason: "continue",
+        reason: "progress observable or fingerprint changed; continue bounded recovery",
+    };
+}

package/dist/workflows/dag/frontend-recovery-plan.js

@@ -14,19 +14,19 @@ export const FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH = ".runtime/import-manif
 /** Staging directory prefix under `active/` for in-flight child materialization. */
 export const FRONTEND_RECOVERY_STAGING_PREFIX = ".frontend-recovery-staging-";
 export function deriveFrontendRecoveryFailureSource(result) {
-    if (result.selectedPlanNodeId === "frontend-plan-revision-pi") {
-        return "frontend-plan-revision-pi";
+    if (result.failureSource === "frontend-plan-pi" ||
+        result.failureSource === "frontend-design-policy-shell" ||
+        result.failureSource === "frontend-implement-pi" ||
+        result.failureSource === "frontend-verify-shell") {
+        return result.failureSource;
     }
-    if (result.selectedPlanNodeId === "frontend-plan-pi") {
-        return "frontend-plan-pi";
-    }
-    return "frontend-prewrite-gate-shell";
+    return "frontend-writer-admission-shell";
 }
 /**
  * Compute the frontend candidate-continuation reset partition:
- * - `frontend-plan-pi` failure → reset plan + design-review + prewrite (+ descendants);
- * - `frontend-plan-revision-pi` failure → reset revision + final-review + prewrite (+ descendants);
- * - prewrite-only materialization → reset prewrite (+ descendants), reuse verified plan/review.
+ * - `frontend-plan-pi` failure → reset plan + design-review + policy/admission (+ descendants);
+ * - `frontend-design-policy-shell` failure → reset policy/admission (+ descendants);
+ * - admission/design-review failure → reset writer admission (+ descendants);
  *
  * Everything upstream of the failure source is imported as verified parent facts.
  */
@@ -55,7 +55,14 @@ export function computeFrontendWriterRecoveryPlan(input) {
     });
 }
 function computeFrontendRecoveryPlanForSource(input) {
-    const resetNodeIds = computeResetClosure(input.spec, input.failureSource);
+    // Verification failure means the implementation did not pass the frozen
+    // verification commands / trace. Resetting only verify + its descendants
+    // would re-run the same failing checks against the same implementation, so
+    // reset from implement: the recovery re-implements and re-verifies.
+    const resetRoot = input.failureSource === "frontend-verify-shell"
+        ? "frontend-implement-pi"
+        : input.failureSource;
+    const resetNodeIds = computeResetClosure(input.spec, resetRoot);
     const resetSet = new Set(resetNodeIds);
     const importedNodeIds = input.spec.tasks
         .map((task) => task.id)

package/dist/workflows/dag/frontend-recovery-run.js

@@ -6,7 +6,7 @@ import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_RE
 import { dagRunDirExists, getDagRunDir, readDagRunSpec, readDagRunState, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
 import { buildDagRunId } from "./runner.js";
 import { prepareRunDir, writeNodeRecord } from "./run-store.js";
-import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, readFrontendPrewriteResult, } from "./scheduler.js";
+import { FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT, readFrontendWriterAdmissionResult, } from "./scheduler.js";
 import { topoSortToRanks } from "./topo.js";
 /**
  * Candidate-continuation child creation kernel (phase 3b).
@@ -19,8 +19,8 @@ import { topoSortToRanks } from "./topo.js";
  * phase=child-running. Scheduling/execution of the child is phase 3c and out
  * of scope here.
  */
-/** Canonical contract artifact default location; overridden by the prewrite
- * gate's configured outputDir/artifactName when present. */
+/** Canonical contract artifact default location; overridden by the design
+ * policy shell's configured outputDir/artifactName when present. */
 const FRONTEND_CANONICAL_CONTRACT_DEFAULT_REL_PATH = "contracts/frontend-implementation-contract.json";
 function resolveDeps(deps) {
     return {
@@ -62,6 +62,9 @@ function isValidFrontendRecoveryMarker(raw) {
  * Read + validate the activation marker. Missing or invalid markers return
  * `undefined` so the phase-3c gate and tests can treat an unmarked active
  * child as not executable (AC-2 / AC-5d).
+ *
+ * @deprecated Read-only/scheduler compatibility only; the runner no longer
+ * uses activation markers as the authoritative recovery entry point.
  */
 export async function readFrontendRecoveryMarker(parentRunDir, requestId) {
     let raw;
@@ -79,8 +82,8 @@ export async function readFrontendRecoveryMarker(parentRunDir, requestId) {
     return raw;
 }
 function classifyFrontendFactKind(nodeId) {
-    if (/prewrite/i.test(nodeId))
-        return "prewrite";
+    if (/admission|design-policy|verify|policy/i.test(nodeId))
+        return "gate";
     if (/scout/i.test(nodeId))
         return "scout";
     if (/contract/i.test(nodeId))
@@ -91,9 +94,9 @@ function classifyFrontendFactKind(nodeId) {
 }
 function resolveCanonicalContractRelPath(spec) {
     for (const task of spec.tasks) {
-        const gate = task.shell?.frontendPrewriteGate;
-        if (gate) {
-            return path.posix.join(gate.outputDir, gate.artifactName);
+        const policy = task.shell?.frontendDesignPolicy;
+        if (policy) {
+            return path.posix.join(policy.outputDir, policy.artifactName);
         }
     }
     return FRONTEND_CANONICAL_CONTRACT_DEFAULT_REL_PATH;
@@ -286,15 +289,15 @@ async function materializeChildStaging(input) {
         });
     }
     else {
-        const prewriteRead = await readFrontendPrewriteResult(parentRunDir);
-        if (!prewriteRead.ok) {
-            throw new Error(prewriteRead.reason);
+        const admissionRead = await readFrontendWriterAdmissionResult(parentRunDir);
+        if (!admissionRead.ok) {
+            throw new Error(admissionRead.reason);
         }
         plan = computeFrontendRecoveryPlan({
             spec: parentSpec,
             parentRunId,
             requestId,
-            result: prewriteRead.result,
+            result: admissionRead.result,
         });
     }
     const { ranks } = topoSortToRanks(parentSpec);
@@ -330,17 +333,17 @@ async function materializeChildStaging(input) {
             throw new Error(`node ${task.id} missing from frontend recovery plan partition`);
         }
     }
-    // Canonical contract + prewrite-result identity facts are copied alongside
+    // Canonical contract + writer-admission identity facts are copied alongside
     // the per-node facts so reset nodes can re-read them (AC-4).
     const canonicalContract = await copyArtifactVerified({
         parentRunDir,
         newRunDir: stagingDir,
         relativePath: resolveCanonicalContractRelPath(parentSpec),
     });
-    const prewriteResult = await copyArtifactVerified({
+    const writerAdmissionResult = await copyArtifactVerified({
         parentRunDir,
         newRunDir: stagingDir,
-        relativePath: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+        relativePath: FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT,
     });
     const childState = {
         version: 1,
@@ -377,9 +380,9 @@ async function materializeChildStaging(input) {
             relativePath: canonicalContract.destinationRelativePath,
             sha256: canonicalContract.sha256,
         },
-        prewriteResult: {
-            relativePath: prewriteResult.destinationRelativePath,
-            sha256: prewriteResult.sha256,
+        writerAdmissionResult: {
+            relativePath: writerAdmissionResult.destinationRelativePath,
+            sha256: writerAdmissionResult.sha256,
         },
         importedFacts,
     };
@@ -417,6 +420,9 @@ async function verifyThreeWayConsistency(input) {
  * intent. Single-writer: the recovery coordinator is the only caller.
  * Fail-closed on revision drift, missing intent, unreadable prewrite result,
  * hash mismatch, marker-write failure, or consistency failure.
+ *
+ * @deprecated The M6 operation controller is the authoritative recovery loop;
+ * this kernel is retained only for read-only/scheduler compatibility.
  */
 export async function stageRecoveryChild(options) {
     const { cwd, parentRunId } = options;
@@ -452,8 +458,15 @@ export async function stageRecoveryChild(options) {
         }
     }
     // Derive the childRunId exactly once; replay always reuses a reserved id.
-    const childRunId = recovery.childRunId ??
-        (await (options.buildChildRunId ?? buildDagRunId)(parentSpec, cwd));
+    // buildDagRunId is deterministic for the same task title on the same day. A
+    // recovery child must never reuse its still-active parent directory, or the
+    // staging path aliases the parent and the required import manifest is absent.
+    const childRunId = recovery.childRunId ?? await (async () => {
+        const generatedChildRunId = await (options.buildChildRunId ?? buildDagRunId)(parentSpec, cwd);
+        return generatedChildRunId === parentRunId
+            ? `${generatedChildRunId}-recovery-${requestId.slice(0, 8)}`
+            : generatedChildRunId;
+    })();
     // Orphan staging cleanup (D4.3): remove any in-flight staging dir for this id.
     const activeRootDir = getDagRunDir(cwd, "active", "");
     const stagingDir = path.join(activeRootDir, `${FRONTEND_RECOVERY_STAGING_PREFIX}${childRunId}`);