ralphy-spec 0.2.0 → 0.3.1

package/dist/core/engine/loop.js

@@ -12,8 +12,18 @@ const runner_1 = require("../validators/runner");
 const signatures_1 = require("../validators/signatures");
 const manager_1 = require("../budgets/manager");
 const state_1 = require("../budgets/state");
+const errors_1 = require("../budgets/errors");
 const context_pack_1 = require("./context-pack");
 const repair_1 = require("./repair");
+const failure_summary_1 = require("../reporting/failure-summary");
+const status_writer_1 = require("../artifacts/status-writer");
+const tasks_writer_1 = require("../artifacts/tasks-writer");
+const budget_writer_1 = require("../artifacts/budget-writer");
+const task_artifacts_1 = require("../artifacts/task-artifacts");
+const run_log_writer_1 = require("../artifacts/run-log-writer");
+const constraints_1 = require("./constraints");
+const scope_detector_1 = require("../workspace/scope-detector");
+const sprint_defaults_1 = require("../spec/sprint-defaults");
 function createRunId() {
     return `run_${new Date().toISOString().replace(/[:.]/g, "-")}_${node_crypto_1.default
         .randomBytes(4)
@@ -24,6 +34,9 @@ class EngineLoop {
         const runId = createRunId();
         const persistence = await persistence_1.PersistenceLayer.openForRepo(opts.repoRoot);
         const ledger = new ledger_1.LedgerLogger(persistence, runId);
+        let artifactsEnabled = Boolean(opts.spec.artifacts?.enabled);
+        const artifactsRootDir = opts.spec.artifacts?.rootDir;
+        const artifactsStatusIcons = opts.spec.artifacts?.statusIcons ?? "emoji";
         const runBudget = opts.spec.budgets?.run;
         const budgetState = new state_1.BudgetState({
             usd: runBudget?.moneyUsd,
@@ -33,7 +46,7 @@ class EngineLoop {
                 : undefined,
             maxIterations: runBudget?.maxIterationsTotal,
         });
-        const budgetManager = new manager_1.BudgetManager(budgetState);
+        const runBudgetManager = new manager_1.BudgetManager(budgetState);
         persistence.createRun({
             runId,
             repoRoot: opts.repoRoot,
@@ -41,6 +54,70 @@ class EngineLoop {
             workspaceMode: opts.workspace.mode,
         });
         ledger.event({ kind: "run_started", message: "Run started", data: { runId } });
+        const safeArtifact = async (fn) => {
+            if (!artifactsEnabled)
+                return;
+            try {
+                await fn();
+            }
+            catch (e) {
+                artifactsEnabled = false;
+                ledger.event({
+                    kind: "artifact_error",
+                    message: `Artifact write failed; disabling artifacts for this run: ${e?.message ? String(e.message) : String(e)}`,
+                });
+            }
+        };
+        await safeArtifact(async () => {
+            await (0, status_writer_1.writeStatus)({
+                repoRoot: opts.repoRoot,
+                rootDir: artifactsRootDir,
+                runId,
+                backendId: opts.backend.id,
+                workspaceMode: opts.workspace.mode,
+                phase: "RUN",
+                message: "Run started",
+            });
+        });
+        const finalizeArtifacts = async (outcome) => {
+            if (!artifactsEnabled)
+                return;
+            const ledgerEvents = persistence.listLedger({ runId, limit: 5000 });
+            await safeArtifact(async () => {
+                await (0, tasks_writer_1.writeTasksBoard)({
+                    repoRoot: opts.repoRoot,
+                    rootDir: artifactsRootDir,
+                    runId,
+                    statusIcons: artifactsStatusIcons,
+                    specTasks: opts.spec.tasks ?? [],
+                    rows: persistence.listTasksForRun({ runId }),
+                });
+            });
+            await safeArtifact(async () => {
+                await (0, budget_writer_1.writeBudgetReport)({
+                    repoRoot: opts.repoRoot,
+                    rootDir: artifactsRootDir,
+                    runId,
+                    ledgerEvents,
+                });
+            });
+            await safeArtifact(async () => {
+                await (0, run_log_writer_1.writeRunLogOnce)({
+                    repoRoot: opts.repoRoot,
+                    rootDir: artifactsRootDir,
+                    runId,
+                    outcome: outcome.ok
+                        ? { ok: true }
+                        : { ok: false, exitCode: outcome.exitCode, reason: outcome.reason },
+                    ledgerEvents: ledgerEvents.map((e) => ({
+                        ts: e.ts,
+                        kind: e.kind,
+                        message: e.message,
+                        taskId: e.taskId,
+                    })),
+                });
+            });
+        };
         try {
             const tasks = opts.spec.tasks ?? [];
             const dag = (0, dag_1.buildTaskDAG)(tasks);
@@ -52,18 +129,21 @@ class EngineLoop {
                     data: { tasks: planOrder },
                 });
                 persistence.finishRun({ runId, status: "success" });
+                await finalizeArtifacts({ ok: true, runId });
                 return { ok: true, runId };
             }
             for (const taskId of planOrder) {
                 const task = dag.tasksById.get(taskId) ?? tasks.find((t) => t.id === taskId);
                 if (!task) {
                     persistence.finishRun({ runId, status: "error" });
-                    return {
+                    const outcome = {
                         ok: false,
                         runId,
                         exitCode: 4,
                         reason: `Unknown task id: ${taskId}`,
                     };
+                    await finalizeArtifacts(outcome);
+                    return outcome;
                 }
                 const outcome = await this.runOneTask({
                     runId,
@@ -74,19 +154,23 @@ class EngineLoop {
                     workspace: opts.workspace,
                     persistence,
                     ledger,
-                    budgetManager,
+                    runBudgetManager,
+                    artifacts: artifactsEnabled ? { rootDir: artifactsRootDir } : null,
                 });
                 if (!outcome.ok) {
                     persistence.finishRun({
                         runId,
                         status: outcome.exitCode === 2 || outcome.exitCode === 3 ? "stopped" : "error",
                     });
+                    await finalizeArtifacts(outcome);
                     return outcome;
                 }
             }
             ledger.event({ kind: "run_done", message: "All tasks done" });
             persistence.finishRun({ runId, status: "success" });
-            return { ok: true, runId };
+            const okOutcome = { ok: true, runId };
+            await finalizeArtifacts(okOutcome);
+            return okOutcome;
         }
         catch (err) {
             ledger.event({
@@ -94,22 +178,78 @@ class EngineLoop {
                 message: err?.message ? String(err.message) : String(err),
             });
             persistence.finishRun({ runId, status: "error" });
-            return {
+            const outcome = {
                 ok: false,
                 runId,
                 exitCode: 4,
                 reason: err?.message ? String(err.message) : String(err),
             };
+            await finalizeArtifacts(outcome);
+            return outcome;
         }
         finally {
             persistence.close();
         }
     }
     async runOneTask(args) {
-        const { task, runId, persistence, ledger, budgetManager } = args;
+        const { task, runId, persistence, ledger, runBudgetManager } = args;
+        let artifacts = args.artifacts;
         let phase = "PLAN";
         persistence.upsertTaskState({ runId, taskId: task.id, status: "running", phase });
         ledger.event({ taskId: task.id, kind: "task_started", message: "Task started" });
+        const refreshArtifacts = async () => {
+            if (!artifacts)
+                return;
+            const ledgerEvents = persistence.listLedger({ runId, limit: 5000 });
+            try {
+                await (0, tasks_writer_1.writeTasksBoard)({
+                    repoRoot: args.repoRoot,
+                    rootDir: artifacts.rootDir,
+                    runId,
+                    statusIcons: args.spec.artifacts?.statusIcons ?? "emoji",
+                    specTasks: args.spec.tasks ?? [],
+                    rows: persistence.listTasksForRun({ runId }),
+                });
+                await (0, budget_writer_1.writeBudgetReport)({
+                    repoRoot: args.repoRoot,
+                    rootDir: artifacts.rootDir,
+                    runId,
+                    ledgerEvents,
+                });
+            }
+            catch (e) {
+                artifacts = null;
+                ledger.event({
+                    taskId: task.id,
+                    kind: "artifact_error",
+                    message: `Artifact write failed; disabling artifacts for this task: ${e?.message ? String(e.message) : String(e)}`,
+                });
+            }
+        };
+        await refreshArtifacts();
+        if (artifacts) {
+            try {
+                await (0, status_writer_1.writeStatus)({
+                    repoRoot: args.repoRoot,
+                    rootDir: artifacts.rootDir,
+                    runId,
+                    backendId: args.backend.id,
+                    workspaceMode: args.workspace.mode,
+                    taskId: task.id,
+                    phase,
+                    iteration: 0,
+                    message: "Task started",
+                });
+            }
+            catch (e) {
+                artifacts = null;
+                ledger.event({
+                    taskId: task.id,
+                    kind: "artifact_error",
+                    message: `STATUS.md write failed; disabling artifacts: ${e?.message ? String(e.message) : String(e)}`,
+                });
+            }
+        }
         const maxIter = task.budget?.hard?.maxIterations ??
             args.spec.budgets?.run?.maxIterationsTotal ??
             12;
@@ -117,15 +257,96 @@ class EngineLoop {
         await args.workspace.prepare(task.id);
         const cwd = args.workspace.getWorkingDir(task.id);
         const taskBudgetConfig = this.toTaskBudgetConfig(task) ?? null;
+        const taskBudgetState = new state_1.BudgetState({
+            usd: taskBudgetConfig?.hard.usd,
+            tokens: taskBudgetConfig?.hard.tokens,
+            wallTimeMs: taskBudgetConfig?.hard.timeMinutes !== undefined
+                ? taskBudgetConfig.hard.timeMinutes * 60_000
+                : undefined,
+            maxIterations: taskBudgetConfig?.hard.maxIterations ?? maxIter,
+        });
+        const taskBudgetManager = new manager_1.BudgetManager(taskBudgetState);
+        const checkpointEvery = task.sprint?.intent ? sprint_defaults_1.SPRINT_INTENT_CONSTRAINTS[task.sprint.intent]?.checkpointEveryIterations : undefined;
         let pendingRepairNotes;
         let lastValidatorResults = null;
         let lastIssues = null;
+        const blockHardCap = async (iter, reason) => {
+            const status = taskBudgetConfig ? taskBudgetManager.getStatus(taskBudgetConfig) : null;
+            ledger.event({
+                taskId: task.id,
+                kind: "hard_cap",
+                message: `HARD cap reached: blocking task (preserving workspace)`,
+                data: status ?? undefined,
+            });
+            persistence.upsertTaskState({
+                runId,
+                taskId: task.id,
+                status: "blocked",
+                phase: "DIAGNOSE",
+                iteration: iter,
+                lastError: reason,
+            });
+            if (artifacts) {
+                try {
+                    await (0, status_writer_1.writeStatus)({
+                        repoRoot: args.repoRoot,
+                        rootDir: artifacts.rootDir,
+                        runId,
+                        backendId: args.backend.id,
+                        workspaceMode: args.workspace.mode,
+                        taskId: task.id,
+                        phase: "DIAGNOSE",
+                        iteration: iter,
+                        tier: "hard",
+                        budgetStatus: status,
+                        message: `Blocked: ${reason} (workspace preserved)`,
+                    });
+                }
+                catch {
+                    artifacts = null;
+                }
+            }
+            ledger.event({
+                taskId: task.id,
+                kind: "failure_summary",
+                message: "Failure summary (hard cap)",
+                data: {
+                    markdown: (0, failure_summary_1.buildFailureSummary)({
+                        runId,
+                        taskId: task.id,
+                        reason,
+                        tier: "hard",
+                        budgetStatus: status,
+                        lastIssues: lastIssues?.map((i) => ({
+                            level: i.level,
+                            kind: i.kind,
+                            message: i.message,
+                            file: i.file,
+                        })),
+                        ledgerEvents: persistence.listLedger({ runId, limit: 200 }),
+                    }),
+                },
+            });
+            await refreshArtifacts();
+            return { ok: false, runId, exitCode: 2, reason: "Hard cap" };
+        };
         for (let iter = 1; iter <= maxIter; iter++) {
             const iterStarted = Date.now();
             try {
-                budgetManager.preflightOrThrow({ estimatedUsd: 0, estimatedTokens: 0 });
+                // Run-level hard limits
+                runBudgetManager.preflightOrThrow({ estimatedUsd: 0, estimatedTokens: 0 });
+                // Task-level hard limits (best-effort)
+                taskBudgetManager.preflightOrThrow({ estimatedUsd: 0, estimatedTokens: 0 });
+                // Hard-cap: do not attempt another backend call once at cap.
+                if (taskBudgetConfig && taskBudgetManager.isAtHardCap(taskBudgetConfig)) {
+                    // Spec requires that "starting another iteration" throws BudgetExhaustedError.
+                    throw new errors_1.BudgetExhaustedError("Hard cap reached");
+                }
             }
             catch (e) {
+                if (e instanceof errors_1.BudgetExhaustedError) {
+                    return await blockHardCap(iter, "Hard cap reached");
+                }
                 ledger.event({
                     taskId: task.id,
                     kind: "budget_exceeded",
@@ -139,11 +360,33 @@ class EngineLoop {
                     iteration: iter,
                     lastError: "Budget exceeded",
                 });
+                ledger.event({
+                    taskId: task.id,
+                    kind: "failure_summary",
+                    message: "Failure summary (budget exceeded)",
+                    data: {
+                        markdown: (0, failure_summary_1.buildFailureSummary)({
+                            runId,
+                            taskId: task.id,
+                            reason: "Budget exceeded",
+                            tier: taskBudgetConfig ? taskBudgetManager.getTier(taskBudgetConfig) : "hard",
+                            budgetStatus: taskBudgetConfig ? taskBudgetManager.getStatus(taskBudgetConfig) : null,
+                            lastIssues: lastIssues?.map((i) => ({
+                                level: i.level,
+                                kind: i.kind,
+                                message: i.message,
+                                file: i.file,
+                            })),
+                            ledgerEvents: persistence.listLedger({ runId, limit: 200 }),
+                        }),
+                    },
+                });
+                await refreshArtifacts();
                 return { ok: false, runId, exitCode: 2, reason: "Budget limit" };
             }
-            const tier = taskBudgetConfig ? budgetManager.getTier(taskBudgetConfig) : "optimal";
+            const tier = taskBudgetConfig ? taskBudgetManager.getTier(taskBudgetConfig) : "optimal";
             const shouldDegrade = taskBudgetConfig
-                ? budgetManager.shouldApplyDegrade(taskBudgetConfig)
+                ? taskBudgetManager.shouldApplyDegrade(taskBudgetConfig)
                 : false;
             if (shouldDegrade) {
                 ledger.event({
@@ -180,6 +423,59 @@ class EngineLoop {
                 iteration: iter,
             });
             ledger.event({ taskId: task.id, kind: "exec", message: `EXEC iteration ${iter}` });
+            if (artifacts) {
+                try {
+                    await (0, status_writer_1.writeStatus)({
+                        repoRoot: args.repoRoot,
+                        rootDir: artifacts.rootDir,
+                        runId,
+                        backendId: args.backend.id,
+                        workspaceMode: args.workspace.mode,
+                        taskId: task.id,
+                        phase,
+                        iteration: iter,
+                        tier,
+                        budgetStatus: taskBudgetConfig ? taskBudgetManager.getStatus(taskBudgetConfig) : null,
+                        message: `Executing iteration ${iter}`,
+                    });
+                }
+                catch {
+                    artifacts = null;
+                }
+            }
+            if (artifacts) {
+                // Write task artifacts before backend call (best-effort).
+                const ctx = lastValidatorResults && lastIssues
+                    ? (0, context_pack_1.buildContextPack)({
+                        tier: shouldDegrade ? "warning" : "optimal",
+                        taskId: task.id,
+                        validatorResults: lastValidatorResults,
+                        issues: lastIssues,
+                    })
+                    : {
+                        size: "full",
+                        text: [`# Context`, ``, `Task: ${task.id}`, `Iteration: ${iter}`, ``].join("\n"),
+                    };
+                try {
+                    await (0, task_artifacts_1.writeTaskContext)({
+                        repoRoot: args.repoRoot,
+                        rootDir: artifacts.rootDir,
+                        taskId: task.id,
+                        markdown: ctx.text,
+                    });
+                    if (pendingRepairNotes) {
+                        await (0, task_artifacts_1.writeTaskRepair)({
+                            repoRoot: args.repoRoot,
+                            rootDir: artifacts.rootDir,
+                            taskId: task.id,
+                            markdown: pendingRepairNotes,
+                        });
+                    }
+                }
+                catch {
+                    artifacts = null;
+                }
+            }
             const backendRes = await args.backend.implement({ cwd, backendId: args.backend.id }, {
                 task,
                 iteration: iter,
@@ -202,9 +498,52 @@ class EngineLoop {
                     kind: "backend_error",
                     message: backendRes.message,
                 });
+                await refreshArtifacts();
                 return { ok: false, runId, exitCode: 5, reason: "Backend invocation error" };
             }
+            // Record backend usage if provided (best-effort; some backends may not estimate).
+            if (backendRes.estimatedUsd !== undefined || backendRes.estimatedTokens !== undefined) {
+                runBudgetManager.recordBackendUsage({
+                    usd: backendRes.estimatedUsd,
+                    tokens: backendRes.estimatedTokens,
+                });
+                taskBudgetManager.recordBackendUsage({
+                    usd: backendRes.estimatedUsd,
+                    tokens: backendRes.estimatedTokens,
+                });
+                ledger.event({
+                    taskId: task.id,
+                    kind: "backend_usage",
+                    message: "Backend usage recorded",
+                    data: {
+                        usd: backendRes.estimatedUsd ?? 0,
+                        tokens: backendRes.estimatedTokens ?? 0,
+                        backendId: args.backend.id,
+                        phase: "EXEC",
+                    },
+                });
+            }
             phase = "VALIDATE";
+            if (artifacts) {
+                try {
+                    await (0, status_writer_1.writeStatus)({
+                        repoRoot: args.repoRoot,
+                        rootDir: artifacts.rootDir,
+                        runId,
+                        backendId: args.backend.id,
+                        workspaceMode: args.workspace.mode,
+                        taskId: task.id,
+                        phase,
+                        iteration: iter,
+                        tier,
+                        budgetStatus: taskBudgetConfig ? taskBudgetManager.getStatus(taskBudgetConfig) : null,
+                        message: "Running validators",
+                    });
+                }
+                catch {
+                    artifacts = null;
+                }
+            }
             const validators = this.resolveValidators(args.spec, task).map((v) => ({
                 ...v,
                 timeoutMs: v.timeoutMs ?? (args.spec.budgets?.limits?.commandTimeoutSeconds ?? 900) * 1000,
@@ -228,7 +567,7 @@ class EngineLoop {
                     : r.issues;
                 return issues.map((i) => ({
                     ...i,
-                    raw: i.raw ?? { validatorId: id },
+                    raw: (i.raw ?? { validatorId: id }),
                 }));
             });
             // Contract enforcement after EXEC
@@ -244,6 +583,30 @@ class EngineLoop {
                     })));
                 }
             }
+            // Sprint constraints & scope detection (best-effort heuristics).
+            const changedFiles = await args.workspace.getChangedFiles(task.id);
+            const scopePolicy = args.spec.policies?.scopeGuard ?? "warn";
+            const scopeLevel = scopePolicy === "block" ? "error" : scopePolicy === "warn" ? "warning" : "warning";
+            if (scopePolicy !== "off") {
+                for (const v of (0, constraints_1.enforceSprintConstraints)({ task, changedFiles })) {
+                    allIssues.push({
+                        kind: "scope_violation",
+                        level: scopeLevel,
+                        message: v.message,
+                        file: v.file,
+                        raw: v.raw,
+                    });
+                }
+                for (const v of (0, scope_detector_1.detectScopeViolations)({ task, changedFiles })) {
+                    allIssues.push({
+                        kind: "scope_violation",
+                        level: scopeLevel,
+                        message: v.message,
+                        file: v.file,
+                        raw: v,
+                    });
+                }
+            }
             const ok = Object.values(results).every((r) => r.ok) && allIssues.every((i) => i.level !== "error");
             ledger.event({
                 taskId: task.id,
@@ -263,6 +626,8 @@ class EngineLoop {
             if (ok) {
                 phase = "CHECKPOINT";
                 await args.workspace.checkpoint(task.id, "Task completed");
+                await args.workspace.merge(task.id);
+                await args.workspace.cleanup(task.id);
                 persistence.upsertTaskState({
                     runId,
                     taskId: task.id,
@@ -271,7 +636,36 @@ class EngineLoop {
                     iteration: iter,
                 });
                 ledger.event({ taskId: task.id, kind: "task_done", message: "Task done" });
-                budgetManager.recordIteration(Date.now() - iterStarted);
+                if (artifacts) {
+                    try {
+                        await (0, status_writer_1.writeStatus)({
+                            repoRoot: args.repoRoot,
+                            rootDir: artifacts.rootDir,
+                            runId,
+                            backendId: args.backend.id,
+                            workspaceMode: args.workspace.mode,
+                            taskId: task.id,
+                            phase: "DONE",
+                            iteration: iter,
+                            tier,
+                            budgetStatus: taskBudgetConfig ? taskBudgetManager.getStatus(taskBudgetConfig) : null,
+                            message: "Task done",
+                        });
+                    }
+                    catch {
+                        artifacts = null;
+                    }
+                }
+                const wallTimeMs = Date.now() - iterStarted;
+                runBudgetManager.recordIteration(wallTimeMs);
+                taskBudgetManager.recordIteration(wallTimeMs);
+                ledger.event({
+                    taskId: task.id,
+                    kind: "iteration_complete",
+                    message: "Iteration complete",
+                    data: { wallTimeMs, phase: "DONE" },
+                });
+                await refreshArtifacts();
                 return { ok: true, runId };
             }
             // Save failure context for next iteration.
@@ -287,29 +681,132 @@ class EngineLoop {
                 iteration: iter,
                 lastError: "Validation failed",
             });
+            if (artifacts) {
+                try {
+                    await (0, status_writer_1.writeStatus)({
+                        repoRoot: args.repoRoot,
+                        rootDir: artifacts.rootDir,
+                        runId,
+                        backendId: args.backend.id,
+                        workspaceMode: args.workspace.mode,
+                        taskId: task.id,
+                        phase,
+                        iteration: iter,
+                        tier,
+                        budgetStatus: taskBudgetConfig ? taskBudgetManager.getStatus(taskBudgetConfig) : null,
+                        message: "Validation failed",
+                    });
+                }
+                catch {
+                    artifacts = null;
+                }
+            }
             if (stuck) {
                 ledger.event({
                     taskId: task.id,
                     kind: "stuck",
                     message: "Stuck detected (same issues repeated)",
                 });
+                await refreshArtifacts();
                 return { ok: false, runId, exitCode: 3, reason: "Stuck / max iterations" };
             }
             phase = "REPAIR";
-            const tierAfter = taskBudgetConfig ? budgetManager.getTier(taskBudgetConfig) : "optimal";
+            const tierAfter = taskBudgetConfig ? taskBudgetManager.getTier(taskBudgetConfig) : "optimal";
             const repairNotes = (0, repair_1.buildRepairNotes)({
                 tier: tierAfter === "warning" ? "warning" : "optimal",
                 issues: allIssues,
             });
             ledger.event({ taskId: task.id, kind: "repair", message: "Retrying (repair loop)" });
+            if (artifacts) {
+                try {
+                    await (0, status_writer_1.writeStatus)({
+                        repoRoot: args.repoRoot,
+                        rootDir: artifacts.rootDir,
+                        runId,
+                        backendId: args.backend.id,
+                        workspaceMode: args.workspace.mode,
+                        taskId: task.id,
+                        phase,
+                        iteration: iter,
+                        tier: tierAfter === "warning" ? "warning" : "optimal",
+                        budgetStatus: taskBudgetConfig ? taskBudgetManager.getStatus(taskBudgetConfig) : null,
+                        message: "Repair loop",
+                    });
+                }
+                catch {
+                    artifacts = null;
+                }
+            }
             pendingRepairNotes = repairNotes;
-            budgetManager.recordIteration(Date.now() - iterStarted);
+            const wallTimeMs = Date.now() - iterStarted;
+            runBudgetManager.recordIteration(wallTimeMs);
+            taskBudgetManager.recordIteration(wallTimeMs);
+            ledger.event({
+                taskId: task.id,
+                kind: "iteration_complete",
+                message: "Iteration complete",
+                data: { wallTimeMs, phase },
+            });
+            // Intent-based checkpointing (best-effort). Only enabled for worktree mode to avoid committing
+            // partial changes directly to the main working directory.
+            if (checkpointEvery &&
+                args.workspace.mode === "worktree" &&
+                iter % checkpointEvery === 0) {
+                await args.workspace.checkpoint(task.id, `Checkpoint iteration ${iter}`);
+                ledger.event({
+                    taskId: task.id,
+                    kind: "checkpoint",
+                    message: `Checkpoint created (every ${checkpointEvery} iterations)`,
+                });
+            }
+            await refreshArtifacts();
         }
         ledger.event({
             taskId: task.id,
             kind: "max_iterations",
             message: `Max iterations reached (${maxIter})`,
         });
+        const treatAsHardCap = Boolean(taskBudgetConfig) && Boolean(taskBudgetManager.isAtHardCap(taskBudgetConfig));
+        if (treatAsHardCap) {
+            const status = taskBudgetManager.getStatus(taskBudgetConfig);
+            persistence.upsertTaskState({
+                runId,
+                taskId: task.id,
+                status: "blocked",
+                phase: "DIAGNOSE",
+                iteration: maxIter,
+                lastError: "Hard cap reached",
+            });
+            ledger.event({
+                taskId: task.id,
+                kind: "hard_cap",
+                message: "HARD cap reached (max iterations): blocking task (preserving workspace)",
+                data: status,
+            });
+            ledger.event({
+                taskId: task.id,
+                kind: "failure_summary",
+                message: "Failure summary (hard cap / max iterations)",
+                data: {
+                    markdown: (0, failure_summary_1.buildFailureSummary)({
+                        runId,
+                        taskId: task.id,
+                        reason: "Hard cap reached (max iterations)",
+                        tier: "hard",
+                        budgetStatus: status,
+                        lastIssues: lastIssues?.map((i) => ({
+                            level: i.level,
+                            kind: i.kind,
+                            message: i.message,
+                            file: i.file,
+                        })),
+                        ledgerEvents: persistence.listLedger({ runId, limit: 200 }),
+                    }),
+                },
+            });
+            await refreshArtifacts();
+            return { ok: false, runId, exitCode: 2, reason: "Hard cap" };
+        }
         persistence.upsertTaskState({
             runId,
             taskId: task.id,
@@ -318,6 +815,7 @@ class EngineLoop {
             iteration: maxIter,
             lastError: "Max iterations reached",
         });
+        await refreshArtifacts();
         return { ok: false, runId, exitCode: 3, reason: "Max iterations reached" };
     }
     toTaskBudgetConfig(task) {