@voybio/ace-swarm 2.4.4 → 2.4.7

package/dist/goal-engine.js

@@ -0,0 +1,795 @@
+/**
+ * ACE Goal Engine (WS-F).
+ *
+ * `startGoal("<objective>")` compiles a plan with ACE's own planner, then a
+ * self-paced driver loop (`runGoal`) executes it step-by-step under evidence-
+ * gated completion. A goal can leave `executing` only through one of four
+ * control-flow paths — evidence-gated success, budget exhaustion, operator
+ * stop, or an escalated blocker — so "declaring success by prose" is
+ * structurally impossible (there is no code path from a model message to
+ * `status: "done"`).
+ *
+ * That guarantee rests on the success contract carrying at least one
+ * machine-checkable obligation. A contract with none is refused at `startGoal`
+ * and again at verify time with `contract_uncheckable`, never satisfied
+ * vacuously — see {@link enforceableObligationCount}.
+ *
+ * This composes existing organs rather than forking a second orchestrator:
+ *   - planning:   proposePlan → validatePlan (blocking) → createTaskPlan
+ *   - execution:  getReadyTaskSteps / applyBridgeResultToStep / amendTaskPlan
+ *                 (the supervisor's own step primitives), one step per tick
+ *   - completion: the same artifact-existence check the ModelBridge false-
+ *                 completion gate uses, run against the compiled success contract
+ *
+ * The single new mechanism is the goal record + tick/budget policy. All side
+ * effects (spawning a step, running a verification command, checking an
+ * artifact, sleeping, posting) are injectable so the engine is driven
+ * hermetically in tests with a stub bridge.
+ */
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { amendTaskPlan, applyBridgeResultToStep, createTaskPlan, deriveTaskPlanStatus, getReadyTaskSteps, markTaskStepStatus, } from "./orchestrator-supervisor.js";
+import { proposePlan, validatePlan } from "./plan-proposal.js";
+import { resolveWorkspaceRoot } from "./helpers.js";
+import { appendVericifyProcessPostSafe } from "./vericify-bridge.js";
+import { appendStatusEventSafe } from "./status-events.js";
+import { GoalRepository, defaultGoalBudgets, newGoalId, } from "./store/repositories/goal-repository.js";
+import { PlaybookRepository } from "./store/repositories/playbook-repository.js";
+// ── Defaults for the injectable seams ────────────────────────────────────────
+function defaultArtifactExists(path, workspaceRoot) {
+    if (!path || path.trim().length === 0)
+        return false;
+    const clean = path.split("#")[0].trim();
+    const abs = isAbsolute(clean) ? clean : join(workspaceRoot, clean);
+    return existsSync(abs);
+}
+async function defaultRunVerification(command, workspaceRoot) {
+    const { exec } = await import("node:child_process");
+    return await new Promise((resolve) => {
+        exec(command, { cwd: workspaceRoot, timeout: 10 * 60 * 1000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({
+                ok: !error,
+                output: `${stdout ?? ""}${stderr ? `\n${stderr}` : ""}`.trim(),
+            });
+        });
+    });
+}
+async function defaultSpawnStep(step, _plan, _goal) {
+    const { runLocalModelTask } = await import("./local-model-runtime.js");
+    const outcome = await runLocalModelTask({
+        task: step.task,
+        role: step.role,
+        toolScope: step.tool_scope,
+    });
+    return outcome.result;
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveDeps(deps = {}) {
+    const workspaceRoot = deps.workspaceRoot ?? resolveWorkspaceRoot();
+    const repo = new GoalRepository(workspaceRoot);
+    return {
+        workspaceRoot,
+        repo,
+        now: deps.now ?? (() => Date.now()),
+        spawnStep: deps.spawnStep ?? defaultSpawnStep,
+        compilePlan: deps.compilePlan ??
+            (async (objective) => {
+                const proposal = await proposePlan(objective);
+                const verdict = await validatePlan({ proposal });
+                return { proposal, verdict };
+            }),
+        runVerification: deps.runVerification ?? defaultRunVerification,
+        artifactExists: deps.artifactExists ?? defaultArtifactExists,
+        sleep: deps.sleep ?? defaultSleep,
+        emitStatusEvent: deps.emitStatusEvent ??
+            (async (input) => {
+                await appendStatusEventSafe({
+                    source_module: "goal-engine",
+                    event_type: `GOAL_${input.status.toUpperCase()}`,
+                    status: "in_progress",
+                    summary: input.summary,
+                    payload: input.payload,
+                });
+            }),
+        appendProcessPost: deps.appendProcessPost ??
+            (async (input) => {
+                const kind = input.kind === "progress" || input.kind === "completion" || input.kind === "blocker"
+                    ? input.kind
+                    : "blocker";
+                await appendVericifyProcessPostSafe({
+                    run_id: "workspace:current",
+                    agent_id: "ace-goal-engine",
+                    kind: kind === "completion" ? "completion" : kind === "progress" ? "progress" : "blocker",
+                    summary: input.summary,
+                    blocker_category: kind === "blocker" ? input.reason_code : undefined,
+                    evidence_refs: input.evidence_refs,
+                });
+            }),
+    };
+}
+// ── Success-contract compilation ─────────────────────────────────────────────
+const CRITERION_VERIFICATION_HINT = /^\s*verify\s*:\s*(.+)$/i;
+const OBJECTIVE_VERIFICATION_HINT = /(?:^|[.!?]\s+)verify\s*:\s*(.+)$/i;
+/**
+ * Extract explicitly delimited shell directives. Planner-authored criteria must
+ * devote the whole line to `verify:`. Objectives additionally support the
+ * documented trailing sentence form, `Ship it. verify: npm test`. In particular,
+ * ordinary prose containing `verification:` is never executable.
+ */
+function extractVerificationCommands(text, mode) {
+    const found = [];
+    const hint = mode === "criterion" ? CRITERION_VERIFICATION_HINT : OBJECTIVE_VERIFICATION_HINT;
+    for (const line of text.split(/\r?\n/)) {
+        const match = hint.exec(line);
+        const command = match?.[1]?.trim().replace(/\.$/, "").trim();
+        if (command)
+            found.push(command);
+    }
+    return found;
+}
+/**
+ * An evidence ref is only machine-checkable when it names a filesystem path, and
+ * only a path separator proves that. A bare `foo.patch` or `v1.2` matches an
+ * "ends in an extension" test but names a hash or a version, so requiring it to
+ * exist yields a contract that `startGoal` accepts and `checkSuccessContract` can
+ * never satisfy. Those route to `uncompilable_criteria` for the qa step instead.
+ *
+ * Note the rest of the codebase treats `required_evidence_refs` as *substrings*
+ * matched against emitted evidence (tools-agent.ts `missingEvidence`); this engine
+ * is the only consumer that resolves them against the filesystem.
+ */
+function isPathLikeEvidenceRef(ref) {
+    const clean = (ref.split("#")[0] ?? "").trim();
+    return clean.length > 0 && clean.includes("/");
+}
+/**
+ * The number of machine-checkable obligations in a contract. Zero means the
+ * only thing standing between the model and `status: "done"` is the model's own
+ * assertion — which is exactly what this engine exists to prevent.
+ *
+ * `gate_ids` is excluded: nothing populates it yet (see goal-repository.ts).
+ */
+export function enforceableObligationCount(contract) {
+    return (contract.expected_artifacts.filter((a) => a.required !== false).length +
+        contract.required_evidence_refs.length +
+        contract.verification_commands.length);
+}
+function compileSuccessContract(proposal, input = {}) {
+    const expected = new Map();
+    const evidence = new Set();
+    const commands = new Set();
+    const uncompilable = [];
+    for (const step of proposal.steps) {
+        for (const artifact of step.expected_artifacts ?? []) {
+            if (!artifact.path)
+                continue;
+            // Scaffolded paths were invented by the deterministic planner to satisfy
+            // validatePlan, not promised by anyone. `agent-state/SPEC_CONTRACT.json` is
+            // shared across every goal in a workspace, so admitting it as an obligation
+            // lets one goal's leftover file certify the next goal's prose. Keep it in
+            // the plan, keep it out of the contract.
+            if (artifact.scaffolded)
+                continue;
+            expected.set(artifact.path, {
+                path: artifact.path,
+                required: artifact.required !== false,
+            });
+        }
+        for (const ref of step.required_evidence_refs ?? []) {
+            if (!ref)
+                continue;
+            // A ref like "reviewer sign-off" is not a path; enforcing it via
+            // artifactExists would fail forever. Adjudicate it in the qa step instead.
+            if (isPathLikeEvidenceRef(ref))
+                evidence.add(ref);
+            else
+                uncompilable.push(`evidence: ${ref}`);
+        }
+    }
+    // Success criteria and the objective both carry `verify: <cmd>` directives;
+    // everything else is uncompilable and routed to a qa step. The objective is the
+    // only channel a CLI user has, so it must be read: `ace goal start "Ship it.
+    // verify: npm test"`.
+    for (const criterion of proposal.success_criteria ?? []) {
+        const found = extractVerificationCommands(criterion, "criterion");
+        if (found.length > 0)
+            for (const command of found)
+                commands.add(command);
+        else
+            uncompilable.push(criterion);
+    }
+    for (const command of extractVerificationCommands(input.objective ?? "", "objective")) {
+        commands.add(command);
+    }
+    for (const command of input.verify_commands ?? []) {
+        const trimmed = command.trim();
+        if (trimmed)
+            commands.add(trimmed);
+    }
+    return {
+        expected_artifacts: Array.from(expected.values()),
+        required_evidence_refs: Array.from(evidence),
+        verification_commands: Array.from(commands),
+        gate_ids: [],
+        uncompilable_criteria: uncompilable,
+    };
+}
+function proposalToPlanSteps(proposal) {
+    return proposal.steps.map((s) => ({
+        role: s.role,
+        task: s.task,
+        depends_on: s.depends_on && s.depends_on.length > 0 ? s.depends_on : undefined,
+        tool_scope: s.tool_scope && s.tool_scope.length > 0 ? s.tool_scope : undefined,
+        expected_output_class: s.expected_output_class,
+        expected_artifacts: s.expected_artifacts,
+        allowed_tools: s.allowed_tools,
+        forbidden_patterns: s.forbidden_patterns,
+        required_evidence_refs: s.required_evidence_refs,
+        structural_edit_plan_required: s.structural_edit_plan_required,
+        structural_edit_waiver: s.structural_edit_waiver,
+    }));
+}
+// ── Escalation helper ────────────────────────────────────────────────────────
+async function escalate(d, goal, kind, reasonCode, summary) {
+    const escalation = {
+        at: new Date(d.now()).toISOString(),
+        kind,
+        reason_code: reasonCode,
+        summary,
+    };
+    goal.escalations.push(escalation);
+    await d.emitStatusEvent({
+        status: kind === "run_complete" ? "done" : "blocked",
+        summary: `[${goal.goal_id}] ${summary}`,
+        payload: { goal_id: goal.goal_id, kind, reason_code: reasonCode },
+    });
+    await d.appendProcessPost({
+        kind: kind === "run_complete" ? "completion" : "blocker",
+        summary: `Goal ${goal.goal_id}: ${summary}`,
+        reason_code: reasonCode,
+    });
+}
+export async function startGoal(objective, options = {}, deps = {}) {
+    const d = resolveDeps(deps);
+    const trimmed = objective.trim();
+    // `typeof NaN === "number"`, and NaN silently disables a budget in memory
+    // (`elapsed >= NaN` is false) while serialising to `null`, which makes the same
+    // budget fire immediately after the record is reloaded. Neither is a budget.
+    const budgets = {
+        ...defaultGoalBudgets(),
+        ...(Number.isFinite(options.budget_hours)
+            ? { max_wall_clock_ms: Math.max(1, options.budget_hours) * 60 * 60 * 1000 }
+            : {}),
+        ...(Number.isFinite(options.max_ticks) ? { max_ticks: options.max_ticks } : {}),
+        ...(Number.isFinite(options.max_replans) ? { max_replans: options.max_replans } : {}),
+    };
+    const iso = new Date(d.now()).toISOString();
+    let goal = {
+        goal_id: options.goal_id ?? newGoalId(),
+        objective: trimmed,
+        status: "planning",
+        success_contract: {
+            expected_artifacts: [],
+            required_evidence_refs: [],
+            verification_commands: [],
+            gate_ids: [],
+            uncompilable_criteria: [],
+        },
+        budgets,
+        created_at: iso,
+        updated_at: iso,
+        tick_count: 0,
+        replan_count: 0,
+        stop_requested: false,
+        escalations: [],
+    };
+    if (trimmed.length === 0) {
+        goal.status = "failed";
+        goal.reason_code = "empty_objective";
+        goal = d.repo.saveGoal(goal);
+        return { ok: false, goal, reason_code: "empty_objective" };
+    }
+    goal = d.repo.saveGoal(goal);
+    // Compile + validate the plan. A plan that fails the quality gate never starts.
+    const { proposal, verdict } = await d.compilePlan(trimmed);
+    if (!verdict.ok) {
+        goal.status = "blocked";
+        goal.reason_code = "plan_rejected";
+        goal = d.repo.saveGoal(goal);
+        await escalate(d, goal, "approval_required", "plan_rejected", `plan rejected by quality gate: ${verdict.blocking_findings.join("; ")}`);
+        d.repo.saveGoal(goal);
+        return {
+            ok: false,
+            goal,
+            reason_code: "plan_rejected",
+            blocking_findings: verdict.blocking_findings,
+        };
+    }
+    const contract = compileSuccessContract(proposal, {
+        objective: trimmed,
+        verify_commands: options.verify_commands,
+    });
+    // Fail fast: a goal that could only ever be completed by model assertion must
+    // never reach `executing`. Blocking here beats burning ten steps of model
+    // budget first.
+    if (enforceableObligationCount(contract) === 0) {
+        goal.status = "blocked";
+        goal.reason_code = "contract_uncheckable";
+        goal.success_contract = contract;
+        goal = d.repo.saveGoal(goal);
+        await escalate(d, goal, "approval_required", "contract_uncheckable", "compiled plan declares no required artifacts, no path-like evidence refs, and no " +
+            "`verify: <command>` success criteria — the goal could only ever be completed by " +
+            "model assertion. Append `verify: <shell command>` to the objective, or pass " +
+            "`--verify <shell command>`.");
+        d.repo.saveGoal(goal);
+        return { ok: false, goal, reason_code: "contract_uncheckable" };
+    }
+    let plan = createTaskPlan({
+        task: trimmed,
+        steps: proposalToPlanSteps(proposal),
+        execution_mode: "sequential",
+    });
+    // L3: uncompilable success criteria are never silently dropped — append a
+    // terminal qa review step that adjudicates them, gated after all other work.
+    if (contract.uncompilable_criteria.length > 0) {
+        const priorIds = plan.steps.map((s) => s.step_id);
+        plan = amendTaskPlan(plan, {
+            append_steps: [
+                {
+                    role: "qa",
+                    task: "Review and confirm the following success criteria that could not be " +
+                        `machine-verified:\n- ${contract.uncompilable_criteria.join("\n- ")}`,
+                    depends_on: priorIds,
+                    expected_output_class: "qa_verdict",
+                },
+            ],
+        });
+    }
+    goal.plan_id = plan.plan_id;
+    goal.success_contract = contract;
+    d.repo.savePlan(goal.goal_id, plan);
+    if (options.plan_only) {
+        goal.status = "planning";
+        goal.result_summary = `Plan compiled (${plan.steps.length} steps); execution deferred (plan_only).`;
+        goal = d.repo.saveGoal(goal);
+        return { ok: true, goal };
+    }
+    goal.status = "executing";
+    goal.started_at = iso;
+    goal.last_heartbeat_at = iso;
+    goal = d.repo.saveGoal(goal);
+    return { ok: true, goal };
+}
+export async function tickGoal(goalId, deps = {}) {
+    const d = resolveDeps(deps);
+    const goal = requireGoal(d, goalId);
+    const plan = requirePlan(d, goal);
+    const ready = getReadyTaskSteps(plan);
+    if (ready.length === 0) {
+        return { goal, plan, progressed: false };
+    }
+    const step = ready[0];
+    // Mark running and persist *before* the spawn so a crash mid-step leaves a
+    // `running` step that resumeGoal can detect and reset.
+    let nextPlan = markTaskStepStatus(plan, step.step_id, "running");
+    goal.current_step_id = step.step_id;
+    goal.tick_count += 1;
+    goal.last_heartbeat_at = new Date(d.now()).toISOString();
+    d.repo.savePlan(goalId, nextPlan);
+    d.repo.saveGoal(goal);
+    await d.emitStatusEvent({
+        status: "step_started",
+        summary: `tick ${goal.tick_count}: running ${step.step_id} (${step.role})`,
+        payload: { goal_id: goalId, step_id: step.step_id, role: step.role },
+    });
+    let result;
+    try {
+        result = await d.spawnStep(step, nextPlan, goal);
+    }
+    catch (err) {
+        result = {
+            bridge_id: `goal-${goalId}`,
+            role: step.role,
+            status: "failed",
+            summary: err instanceof Error ? err.message : String(err),
+            turns: 0,
+            tool_calls: [],
+            child_results: [],
+            reason_code: "spawn_threw",
+        };
+    }
+    nextPlan = applyBridgeResultToStep(nextPlan, step.step_id, result);
+    const finalStep = nextPlan.steps.find((s) => s.step_id === step.step_id);
+    // Re-hydrate so any field mutated *during* the spawn (e.g. an operator
+    // stop_requested via stopGoal) is preserved rather than clobbered by this
+    // tick's stale in-memory snapshot.
+    const latestGoal = d.repo.getGoal(goalId) ?? goal;
+    latestGoal.current_step_id = step.step_id;
+    latestGoal.last_heartbeat_at = new Date(d.now()).toISOString();
+    d.repo.savePlan(goalId, nextPlan);
+    d.repo.saveGoal(latestGoal);
+    await d.appendProcessPost({
+        kind: "progress",
+        summary: `Goal ${goalId} tick ${latestGoal.tick_count}: ${step.step_id} → ${finalStep?.status ?? "unknown"} (${result.summary})`,
+        evidence_refs: finalStep?.evidence_refs,
+    });
+    return {
+        goal: latestGoal,
+        plan: nextPlan,
+        progressed: true,
+        step_id: step.step_id,
+        step_status: finalStep?.status,
+    };
+}
+export async function checkSuccessContract(d, goal) {
+    const contract = goal.success_contract;
+    // A contract with nothing to check cannot certify anything. Refuse rather
+    // than pass vacuously — the whole point of the engine (see module docstring).
+    if (enforceableObligationCount(contract) === 0) {
+        return {
+            ok: false,
+            missing_artifacts: [],
+            missing_evidence_refs: [],
+            failed_commands: [],
+            uncheckable: true,
+        };
+    }
+    const missing = [];
+    for (const artifact of contract.expected_artifacts) {
+        if (artifact.required === false)
+            continue;
+        if (!d.artifactExists(artifact.path, d.workspaceRoot)) {
+            missing.push(artifact.path);
+        }
+    }
+    const missingEvidence = [];
+    for (const ref of contract.required_evidence_refs) {
+        if (!d.artifactExists(ref, d.workspaceRoot))
+            missingEvidence.push(ref);
+    }
+    const failed = [];
+    for (const command of contract.verification_commands) {
+        const outcome = await d.runVerification(command, d.workspaceRoot);
+        if (!outcome.ok)
+            failed.push(command);
+    }
+    return {
+        ok: missing.length === 0 && missingEvidence.length === 0 && failed.length === 0,
+        missing_artifacts: missing,
+        missing_evidence_refs: missingEvidence,
+        failed_commands: failed,
+        uncheckable: false,
+    };
+}
+const BACKOFF_START_MS = 5_000;
+const BACKOFF_CAP_MS = 60_000;
+function playbookEnabled() {
+    const raw = String(process.env.ACE_PLAYBOOK ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+function playbookRetryNote(workspaceRoot, reasonCode) {
+    if (!playbookEnabled() || !reasonCode)
+        return undefined;
+    try {
+        const count = new PlaybookRepository(workspaceRoot)
+            .listBullets({ status: "active" })
+            .filter((bullet) => bullet.scope.reason_code === reasonCode).length;
+        if (count === 0)
+            return undefined;
+        return `Playbook: ${count} lessons for reason ${reasonCode} are active in your context`;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function runGoal(goalId, deps = {}) {
+    const d = resolveDeps(deps);
+    let goal = requireGoal(d, goalId);
+    if (goal.status !== "executing" && goal.status !== "verifying") {
+        return { goal, plan: d.repo.getPlan(goalId) };
+    }
+    let backoff = BACKOFF_START_MS;
+    // Bounded by max_ticks; the loop can only exit through an explicit terminal
+    // transition below, never by a model asserting completion.
+    for (;;) {
+        goal = requireGoal(d, goalId);
+        // 1. Operator stop.
+        if (goal.stop_requested) {
+            goal.status = "stopped";
+            goal.result_summary = "Stopped by operator.";
+            goal = d.repo.saveGoal(goal);
+            await escalate(d, goal, "run_error", "operator_stop", "stopped by operator");
+            d.repo.saveGoal(goal);
+            break;
+        }
+        // 2. Budget enforcement.
+        const budgetReason = budgetExhausted(d, goal);
+        if (budgetReason) {
+            const budgetCode = `goal_budget_exhausted:${budgetReason}`;
+            goal.status = "blocked";
+            goal.reason_code = budgetCode;
+            goal = d.repo.saveGoal(goal);
+            await escalate(d, goal, "budget_blocked", budgetCode, `budget exhausted (${budgetReason})`);
+            d.repo.saveGoal(goal);
+            break;
+        }
+        const plan = requirePlan(d, goal);
+        const status = deriveTaskPlanStatus(plan);
+        // 3. Plan finished all steps → verify against the success contract.
+        if (status === "done") {
+            goal.status = "verifying";
+            goal = d.repo.saveGoal(goal);
+            const check = await checkSuccessContract(d, goal);
+            // Defense in depth: a hand-edited or pre-fix goal record can carry a
+            // vacuous contract past startGoal. Never certify it on prose alone.
+            if (check.uncheckable) {
+                goal.status = "blocked";
+                goal.reason_code = "contract_uncheckable";
+                goal = d.repo.saveGoal(goal);
+                await escalate(d, goal, "approval_required", "contract_uncheckable", `all plan steps completed but the success contract has zero enforceable obligations ` +
+                    `(${goal.success_contract.uncompilable_criteria.length} uncompilable criteria); ` +
+                    `refusing to mark done on model assertion alone`);
+                d.repo.saveGoal(goal);
+                break;
+            }
+            if (check.ok) {
+                const doneSummary = `Success contract satisfied (${goal.success_contract.expected_artifacts.length} artifacts, ${goal.success_contract.verification_commands.length} commands).`;
+                goal.status = "done";
+                goal.result_summary = doneSummary;
+                goal = d.repo.saveGoal(goal);
+                await escalate(d, goal, "run_complete", "success", doneSummary);
+                d.repo.saveGoal(goal);
+                break;
+            }
+            // Missing evidence → synthesize a remediation step (counts as a replan).
+            if (goal.replan_count >= goal.budgets.max_replans) {
+                const replanCode = "goal_budget_exhausted:max_replans";
+                goal.status = "blocked";
+                goal.reason_code = replanCode;
+                goal = d.repo.saveGoal(goal);
+                await escalate(d, goal, "gate_failed", replanCode, `success contract unmet and replans exhausted (missing: ${[
+                    ...check.missing_artifacts,
+                    ...check.missing_evidence_refs,
+                    ...check.failed_commands,
+                ].join(", ")})`);
+                d.repo.saveGoal(goal);
+                break;
+            }
+            const remediated = amendTaskPlan(plan, {
+                append_steps: [
+                    {
+                        role: "coders",
+                        task: "The goal success contract is unmet. Produce the missing evidence.\n" +
+                            (check.missing_artifacts.length > 0
+                                ? `Missing artifacts: ${check.missing_artifacts.join(", ")}\n`
+                                : "") +
+                            (check.missing_evidence_refs.length > 0
+                                ? `Missing evidence refs: ${check.missing_evidence_refs.join(", ")}\n`
+                                : "") +
+                            (check.failed_commands.length > 0
+                                ? `Failing verification commands: ${check.failed_commands.join("; ")}`
+                                : ""),
+                        expected_artifacts: [
+                            ...check.missing_artifacts,
+                            ...check.missing_evidence_refs,
+                        ].map((path) => ({ path, required: true })),
+                    },
+                ],
+            });
+            goal.replan_count += 1;
+            goal.status = "executing";
+            d.repo.savePlan(goalId, remediated);
+            goal = d.repo.saveGoal(goal);
+            await d.appendProcessPost({
+                kind: "progress",
+                summary: `Goal ${goalId}: success contract unmet, synthesized remediation step (replan ${goal.replan_count}/${goal.budgets.max_replans}).`,
+            });
+            backoff = BACKOFF_START_MS;
+            continue;
+        }
+        // 4. Plan blocked/failed → classify and either replan or park.
+        if (status === "blocked" || status === "failed") {
+            if (goal.replan_count >= goal.budgets.max_replans) {
+                goal.status = "blocked";
+                goal.reason_code = "plan_blocked";
+                goal = d.repo.saveGoal(goal);
+                await escalate(d, goal, "blocker", "plan_blocked", `plan ${status}; replans exhausted (${blockedReasons(plan)})`);
+                d.repo.saveGoal(goal);
+                break;
+            }
+            // Reset blocked/failed steps to planned for one more attempt (a replan).
+            const retryNoteByStep = new Map(plan.steps
+                .filter((s) => s.status === "blocked" || s.status === "failed")
+                .map((s) => [
+                s.step_id,
+                playbookRetryNote(d.workspaceRoot, s.blocked_reason ?? s.result_summary ?? undefined),
+            ]));
+            const retried = amendTaskPlan(plan, {
+                update_steps: plan.steps
+                    .filter((s) => s.status === "blocked" || s.status === "failed")
+                    .map((s) => ({
+                    step_id: s.step_id,
+                    patch: {
+                        status: "planned",
+                        blocked_reason: undefined,
+                        upstream_outputs: [
+                            ...(s.upstream_outputs ?? []),
+                            {
+                                step_id: s.step_id,
+                                result_summary: `retry after ${s.status}: ${s.blocked_reason ?? s.result_summary ?? ""}`,
+                                evidence_refs: [],
+                            },
+                            ...(retryNoteByStep.get(s.step_id)
+                                ? [{
+                                        step_id: s.step_id,
+                                        result_summary: retryNoteByStep.get(s.step_id),
+                                        evidence_refs: [],
+                                    }]
+                                : []),
+                        ],
+                    },
+                })),
+            });
+            goal.replan_count += 1;
+            goal = d.repo.saveGoal(goal);
+            d.repo.savePlan(goalId, retried);
+            await d.appendProcessPost({
+                kind: "progress",
+                summary: `Goal ${goalId}: plan ${status}, retrying blocked steps (replan ${goal.replan_count}/${goal.budgets.max_replans}).`,
+            });
+            backoff = BACKOFF_START_MS;
+            continue;
+        }
+        // 5. Ready work exists → execute one step.
+        const tick = await tickGoal(goalId, deps);
+        if (tick.progressed) {
+            backoff = BACKOFF_START_MS;
+            continue;
+        }
+        // 6. No ready step and not terminal. If nothing is in flight either, no future
+        //    event can make a step ready — the plan's dependency graph is unsatisfiable
+        //    and backing off would spin until the wall-clock budget expires (or forever,
+        //    since `tickGoal` does not advance `tick_count` when it cannot progress).
+        if (!plan.steps.some((step) => step.status === "running")) {
+            goal.status = "blocked";
+            goal.reason_code = "plan_deadlocked";
+            goal = d.repo.saveGoal(goal);
+            await escalate(d, goal, "blocker", "plan_deadlocked", `no step is ready and none is running; the plan cannot progress ` +
+                `(unresolved: ${plan.steps.filter((s) => s.status === "planned").map((s) => s.step_id).join(", ") || "none"})`);
+            d.repo.saveGoal(goal);
+            break;
+        }
+        // A step is still running (an engine restarted mid-step). Back off, but charge
+        // the wait against max_ticks so an in-flight step cannot stall the goal forever.
+        goal.tick_count += 1;
+        goal = d.repo.saveGoal(goal);
+        await d.sleep(backoff);
+        backoff = Math.min(backoff * 2, BACKOFF_CAP_MS);
+    }
+    return { goal, plan: d.repo.getPlan(goalId) };
+}
+// ── resumeGoal / stopGoal / status ───────────────────────────────────────────
+export async function resumeGoal(goalId, deps = {}) {
+    const d = resolveDeps(deps);
+    const goal = requireGoal(d, goalId);
+    const plan = d.repo.getPlan(goalId);
+    if (plan) {
+        // A step left `running` means the engine died mid-step — reset it to planned
+        // (the supervisor's own revisit pattern) so it re-executes on resume.
+        const stuck = plan.steps.filter((s) => s.status === "running");
+        if (stuck.length > 0) {
+            const reset = amendTaskPlan(plan, {
+                update_steps: stuck.map((s) => ({
+                    step_id: s.step_id,
+                    patch: {
+                        status: "planned",
+                        upstream_outputs: [
+                            ...(s.upstream_outputs ?? []),
+                            { step_id: s.step_id, result_summary: "reset after engine restart mid-step", evidence_refs: [] },
+                        ],
+                    },
+                })),
+            });
+            d.repo.savePlan(goalId, reset);
+        }
+    }
+    if (goal.status === "blocked" || goal.status === "stopped") {
+        // A `contract_uncheckable` block is not a transient failure — nothing about
+        // re-running changes the contract. Force the operator to restart the goal.
+        if (goal.reason_code === "contract_uncheckable") {
+            throw new GoalNotResumableError(goalId, `Goal ${goalId} is blocked on an uncheckable success contract and cannot be resumed. ` +
+                `Start a new goal whose objective declares an artifact or a \`verify: <command>\` criterion.`);
+        }
+        goal.status = "executing";
+        goal.stop_requested = false;
+        goal.reason_code = undefined;
+        d.repo.saveGoal(goal);
+    }
+    // `--plan-only` parks at `planning` with a compiled plan. Resuming is the
+    // documented way to execute it later; without this, the plan is unreachable.
+    if (goal.status === "planning") {
+        if (!plan)
+            throw new Error(`Goal ${goalId} has no compiled plan to resume.`);
+        const iso = new Date(d.now()).toISOString();
+        goal.status = "executing";
+        goal.stop_requested = false;
+        goal.started_at = goal.started_at ?? iso;
+        goal.last_heartbeat_at = iso;
+        d.repo.saveGoal(goal);
+    }
+    return runGoal(goalId, deps);
+}
+export function stopGoal(goalId, deps = {}) {
+    const d = resolveDeps(deps);
+    const goal = requireGoal(d, goalId);
+    goal.stop_requested = true;
+    return d.repo.saveGoal(goal);
+}
+export function getGoalStatus(goalId, deps = {}) {
+    const d = resolveDeps(deps);
+    const goal = d.repo.getGoal(goalId);
+    if (!goal)
+        return undefined;
+    const plan = d.repo.getPlan(goalId);
+    return {
+        goal,
+        plan,
+        ready_steps: plan ? getReadyTaskSteps(plan).map((s) => s.step_id) : [],
+        plan_status: plan ? deriveTaskPlanStatus(plan) : undefined,
+    };
+}
+export function listGoals(filter = {}, deps = {}) {
+    const d = resolveDeps(deps);
+    return d.repo.listGoals(filter);
+}
+// ── internal helpers ─────────────────────────────────────────────────────────
+export class UnknownGoalError extends Error {
+    goal_id;
+    name = "UnknownGoalError";
+    constructor(goal_id) {
+        super(`Unknown goal_id: ${goal_id}`);
+        this.goal_id = goal_id;
+    }
+}
+/** A goal whose state cannot be revived by re-running it. Reported, not thrown, at the CLI. */
+export class GoalNotResumableError extends Error {
+    goal_id;
+    message;
+    name = "GoalNotResumableError";
+    constructor(goal_id, message) {
+        super(message);
+        this.goal_id = goal_id;
+        this.message = message;
+    }
+}
+function requireGoal(d, goalId) {
+    const goal = d.repo.getGoal(goalId);
+    if (!goal)
+        throw new UnknownGoalError(goalId);
+    return goal;
+}
+function requirePlan(d, goal) {
+    const plan = goal.plan_id ? d.repo.getPlan(goal.goal_id) : undefined;
+    if (!plan)
+        throw new Error(`Goal ${goal.goal_id} has no persisted plan.`);
+    return plan;
+}
+function budgetExhausted(d, goal) {
+    if (goal.tick_count >= goal.budgets.max_ticks)
+        return "max_ticks";
+    if (goal.started_at) {
+        const elapsed = d.now() - Date.parse(goal.started_at);
+        if (elapsed >= goal.budgets.max_wall_clock_ms)
+            return "max_wall_clock";
+    }
+    return undefined;
+}
+function blockedReasons(plan) {
+    return plan.steps
+        .filter((s) => s.status === "blocked" || s.status === "failed")
+        .map((s) => `${s.step_id}:${s.blocked_reason ?? s.result_summary ?? s.status}`)
+        .join(", ");
+}
+//# sourceMappingURL=goal-engine.js.map