@mcoda/core 0.1.8 → 0.1.11

package/dist/services/execution/GatewayTrioService.js

@@ -0,0 +1,2492 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { WorkspaceRepository } from "@mcoda/db";
+import { PathHelper, READY_TO_CODE_REVIEW, isReadyToReviewStatus, normalizeReviewStatuses, } from "@mcoda/shared";
+import { readDocdexCheck, summarizeDocdexCheck } from "@mcoda/integrations";
+import { GatewayAgentService } from "../agents/GatewayAgentService.js";
+import { RoutingService } from "../agents/RoutingService.js";
+import { buildGatewayHandoffContent, buildGatewayHandoffDocdexUsage, withGatewayHandoff, writeGatewayHandoffFile, } from "../agents/GatewayHandoff.js";
+import { JobService } from "../jobs/JobService.js";
+import { TaskSelectionService } from "./TaskSelectionService.js";
+import { WorkOnTasksService } from "./WorkOnTasksService.js";
+import { CodeReviewService } from "../review/CodeReviewService.js";
+import { QaTasksService } from "./QaTasksService.js";
+const DEFAULT_STATUS_FILTER = ["not_started", "in_progress", "changes_requested", READY_TO_CODE_REVIEW, "ready_to_qa"];
+const TERMINAL_STATUSES = new Set(["completed", "cancelled", "failed"]);
+const GATEWAY_FAILED_REASON = "gateway_failed";
+const ESCALATION_REASONS = new Set([
+    "missing_patch",
+    "patch_failed",
+    "tests_failed",
+    "agent_timeout",
+    "review_invalid_output",
+    "work_status_not_ready",
+]);
+const NO_CHANGE_REASON = "no_changes";
+const STRONG_TIER_MIN_COMPLEXITY = 5;
+const SPECIALIST_TIER_MIN_COMPLEXITY = 8;
+const DONE_DEPENDENCY_STATUSES = new Set(["completed", "cancelled"]);
+const HEARTBEAT_INTERVAL_MS = 30000;
+const ZERO_TOKEN_BACKOFF_MS = 750;
+const PSEUDO_TASK_PREFIX = "[RUN]";
+const ZERO_TOKEN_ERROR = "zero_tokens";
+const FAILED_REOPEN_COOLDOWN_MS = 2 * 60 * 1000;
+const MAX_FAILURE_REOPENS_PER_REASON = 2;
+const AUTH_ERROR_REASON = "auth_error";
+const AUTH_ERROR_PATTERNS = [
+    /auth_error/i,
+    /usage_limit_reached/i,
+    /too many requests/i,
+    /http\s*429/i,
+    /rate limit/i,
+    /usage limit/i,
+];
+const NON_RETRYABLE_FAILURE_REASONS = new Set([
+    "patch_failed",
+    "scope_violation",
+    "doc_edit_guard",
+    "merge_conflict",
+    "vcs_failed",
+    "task_lock_lost",
+    "missing_context",
+    "missing_docdex",
+    "review_invalid_output",
+    "gateway_invalid_output",
+    GATEWAY_FAILED_REASON,
+    AUTH_ERROR_REASON,
+]);
+const DOCDEX_SKIP_PATTERN = /\b(?:not executed|would run|not run|skipped)\b/i;
+const DOCDEX_MISSING_PATTERN = /\b(?:docdex unavailable|docdex missing|no matching docs?|no matching documents?|no results|not provided)\b/i;
+const MISSING_TASK_PATTERN = /\b(?:no concrete task|no task provided|task details are missing|task details missing|need the specific change request|no specific change request|no task context|task details are missing so no file paths can be named)\b/i;
+const GUARDRAIL_REASON_PATTERN = /^guardrail:(retryable|non_retryable):([a-z0-9._-]+)$/i;
+const GUARDRAIL_REASON_ALT_PATTERN = /^guardrail_(retryable|non_retryable):([a-z0-9._-]+)$/i;
+const GOLDEN_EXAMPLES_REL_PATH = ".mcoda/codali/golden-examples.jsonl";
+const GOLDEN_EXAMPLES_MAX = 50;
+const DECISION_HISTORY_MAX = 30;
+const normalizeFailureReason = (value) => {
+    if (!value)
+        return undefined;
+    const lower = value.toLowerCase();
+    if (lower === GATEWAY_FAILED_REASON || lower.startsWith(`${GATEWAY_FAILED_REASON}:`)) {
+        return GATEWAY_FAILED_REASON;
+    }
+    if (AUTH_ERROR_PATTERNS.some((pattern) => pattern.test(lower))) {
+        return AUTH_ERROR_REASON;
+    }
+    return lower.trim();
+};
+const parseGuardrailReason = (value) => {
+    const raw = value?.trim();
+    if (!raw)
+        return undefined;
+    const match = GUARDRAIL_REASON_PATTERN.exec(raw) ?? GUARDRAIL_REASON_ALT_PATTERN.exec(raw);
+    if (!match)
+        return undefined;
+    const disposition = match[1].toLowerCase();
+    const reason = normalizeFailureReason(match[2]) ?? match[2].toLowerCase();
+    if (!reason)
+        return undefined;
+    return {
+        retryable: disposition === "retryable",
+        reason,
+    };
+};
+export class GatewayTrioService {
+    constructor(workspace, deps) {
+        this.workspace = workspace;
+        this.deps = deps;
+        this.projectKeyCache = new Map();
+        this.selectionService =
+            deps.selectionService ?? new TaskSelectionService(workspace, deps.workspaceRepo);
+    }
+    static async create(workspace, options = {}) {
+        const workspaceRepo = await WorkspaceRepository.create(workspace.workspaceRoot);
+        const jobService = new JobService(workspace, workspaceRepo);
+        const gatewayService = await GatewayAgentService.create(workspace);
+        const routingService = await RoutingService.create();
+        const workService = await WorkOnTasksService.create(workspace);
+        const reviewService = await CodeReviewService.create(workspace);
+        const qaService = await QaTasksService.create(workspace, { noTelemetry: options.noTelemetry ?? false });
+        const selectionService = new TaskSelectionService(workspace, workspaceRepo);
+        return new GatewayTrioService(workspace, {
+            workspaceRepo,
+            jobService,
+            gatewayService,
+            routingService,
+            workService,
+            reviewService,
+            qaService,
+            selectionService,
+        });
+    }
+    async close() {
+        const maybeClose = async (target) => {
+            try {
+                if (target?.close)
+                    await target.close();
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        await maybeClose(this.selectionService);
+        await maybeClose(this.deps.gatewayService);
+        await maybeClose(this.deps.routingService);
+        await maybeClose(this.deps.workService);
+        await maybeClose(this.deps.reviewService);
+        await maybeClose(this.deps.qaService);
+        await maybeClose(this.deps.jobService);
+        await maybeClose(this.deps.workspaceRepo);
+    }
+    disableDocdex(reason) {
+        this.deps.gatewayService.setDocdexAvailability(false, reason);
+        this.deps.workService.setDocdexAvailability(false, reason);
+        this.deps.reviewService.setDocdexAvailability(false, reason);
+        this.deps.qaService.setDocdexAvailability(false, reason);
+    }
+    async writeDocdexCheckArtifact(jobId, payload) {
+        const dir = path.join(this.trioDir(jobId), "docdex");
+        await PathHelper.ensureDir(dir);
+        const target = path.join(dir, "docdex-check.json");
+        await fs.writeFile(target, JSON.stringify(payload, null, 2), "utf8");
+        return path.relative(this.workspace.mcodaDir, target);
+    }
+    async runDocdexPreflight(jobId, warnings) {
+        const usingCustomCheck = Boolean(this.deps.docdexCheck);
+        if (!usingCustomCheck &&
+            (process.env.MCODA_SKIP_DOCDEX_CHECKS === "1" || process.env.MCODA_SKIP_DOCDEX_RUNTIME_CHECKS === "1")) {
+            return;
+        }
+        const configuredUrl = this.workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL ?? process.env.DOCDEX_URL;
+        if (configuredUrl && !usingCustomCheck) {
+            return;
+        }
+        const checkFn = this.deps.docdexCheck ?? readDocdexCheck;
+        let summary;
+        let artifactPath;
+        try {
+            const check = await checkFn({ cwd: this.workspace.workspaceRoot });
+            summary = summarizeDocdexCheck(check);
+            artifactPath = await this.writeDocdexCheckArtifact(jobId, {
+                ok: summary.ok,
+                summary,
+                check,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            summary = { ok: false, message };
+            artifactPath = await this.writeDocdexCheckArtifact(jobId, {
+                ok: false,
+                error: message,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        await this.deps.jobService.writeCheckpoint(jobId, {
+            stage: "docdex:check",
+            timestamp: new Date().toISOString(),
+            details: {
+                ok: summary?.ok ?? false,
+                message: summary?.message,
+                artifactPath,
+            },
+        });
+        if (!summary?.ok) {
+            const hint = "Run `docdex check` to diagnose; ensure docdexd and ollama are running.";
+            const detail = summary?.message ? `Docdex unavailable: ${summary.message}.` : "Docdex unavailable.";
+            warnings.push(artifactPath ? `${detail} ${hint} (artifact: ${artifactPath})` : `${detail} ${hint}`);
+            this.disableDocdex(summary?.message ?? "docdex unavailable");
+        }
+    }
+    trioDir(jobId) {
+        return path.join(this.workspace.mcodaDir, "jobs", jobId, "gateway-trio");
+    }
+    statePath(jobId) {
+        return path.join(this.trioDir(jobId), "state.json");
+    }
+    async writeState(state) {
+        await PathHelper.ensureDir(this.trioDir(state.job_id));
+        await fs.writeFile(this.statePath(state.job_id), JSON.stringify(state, null, 2), "utf8");
+    }
+    async loadState(jobId) {
+        try {
+            const raw = await fs.readFile(this.statePath(jobId), "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async readManifest(jobId) {
+        const manifestPath = path.join(this.workspace.mcodaDir, "jobs", jobId, "manifest.json");
+        try {
+            const raw = await fs.readFile(manifestPath, "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    isPseudoTaskKey(key) {
+        return key.trim().toUpperCase().startsWith(PSEUDO_TASK_PREFIX);
+    }
+    skipPseudoTask(state, taskKey, warnings) {
+        const progress = this.ensureProgress(state, taskKey);
+        progress.status = "skipped";
+        progress.lastError = "pseudo_task";
+        state.tasks[taskKey] = progress;
+        warnings.push(`Skipping pseudo task ${taskKey}.`);
+    }
+    async isTokenUsageCheckEnabled() {
+        if (this.tokenUsageCheckEnabled !== undefined)
+            return this.tokenUsageCheckEnabled;
+        const configPath = path.join(this.workspace.mcodaDir, "config.json");
+        try {
+            const raw = await fs.readFile(configPath, "utf8");
+            const parsed = JSON.parse(raw);
+            this.tokenUsageCheckEnabled = !parsed?.telemetry?.strict;
+        }
+        catch {
+            this.tokenUsageCheckEnabled = true;
+        }
+        return this.tokenUsageCheckEnabled;
+    }
+    async isZeroTokenRun(jobId, commandRunId) {
+        if (!jobId)
+            return undefined;
+        const enabled = await this.isTokenUsageCheckEnabled();
+        if (!enabled)
+            return undefined;
+        const tokenPath = path.join(this.workspace.mcodaDir, "token_usage.json");
+        let raw;
+        try {
+            raw = await fs.readFile(tokenPath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        let entries;
+        try {
+            const parsed = JSON.parse(raw);
+            entries = Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return undefined;
+        }
+        if (!entries.length)
+            return undefined;
+        const relevant = entries.filter((entry) => {
+            if (!entry)
+                return false;
+            if (entry.jobId === jobId)
+                return true;
+            if (commandRunId && entry.commandRunId === commandRunId)
+                return true;
+            return false;
+        });
+        if (relevant.length === 0)
+            return undefined;
+        const total = relevant.reduce((sum, entry) => {
+            const prompt = Number(entry.tokensPrompt ?? entry.tokens_prompt ?? 0);
+            const completion = Number(entry.tokensCompletion ?? entry.tokens_completion ?? 0);
+            const rawTotal = entry.tokensTotal ?? entry.tokens_total;
+            const entryTotal = Number.isFinite(rawTotal) ? Number(rawTotal) : prompt + completion;
+            return sum + (Number.isFinite(entryTotal) ? entryTotal : 0);
+        }, 0);
+        return total <= 0;
+    }
+    async backoffZeroTokens(attempts) {
+        const backoffMs = ZERO_TOKEN_BACKOFF_MS * Math.max(1, Math.min(attempts, 2));
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+    }
+    async cleanupExpiredTaskLocks(warnings) {
+        const cleared = await this.deps.workspaceRepo.cleanupExpiredTaskLocks();
+        if (cleared.length > 0) {
+            warnings.push(`Cleared ${cleared.length} expired task lock(s): ${cleared.join(", ")}`);
+        }
+    }
+    assertResumeAllowed(job, manifest) {
+        const state = job.jobState ?? job.state ?? job.status ?? "unknown";
+        if (["completed", "cancelled"].includes(state)) {
+            throw new Error(`Job ${job.id} is ${state}; cannot resume.`);
+        }
+        if (["running", "queued", "checkpointing"].includes(state)) {
+            throw new Error(`Job ${job.id} is ${state}; wait for it to finish or cancel before resuming.`);
+        }
+        const supported = job.resumeSupported ?? job.resume_supported ?? job.payload?.resumeSupported ?? job.payload?.resume_supported;
+        if (supported === 0 || supported === false) {
+            throw new Error(`Job ${job.id} does not support resume.`);
+        }
+        if (!manifest) {
+            throw new Error(`Missing manifest for job ${job.id}; cannot resume safely.`);
+        }
+        const manifestJobId = manifest.job_id ?? manifest.id;
+        if (manifestJobId && manifestJobId !== job.id) {
+            throw new Error(`Checkpoint manifest for ${job.id} does not match job id (${manifestJobId}); aborting resume.`);
+        }
+        const manifestType = manifest.type ?? manifest.job_type;
+        if (manifestType && manifestType !== job.type) {
+            throw new Error(`Checkpoint manifest type (${manifestType}) does not match job type (${job.type}); cannot resume.`);
+        }
+        const manifestCommand = manifest.command ?? manifest.command_name ?? manifest.commandName;
+        if (manifestCommand && job.commandName && manifestCommand !== job.commandName) {
+            throw new Error(`Checkpoint manifest command (${manifestCommand}) does not match job command (${job.commandName}); cannot resume.`);
+        }
+    }
+    async writeHandoffArtifact(jobId, taskKey, step, attempt, content) {
+        const dir = path.join(this.trioDir(jobId), "handoffs");
+        await PathHelper.ensureDir(dir);
+        const safeKey = taskKey.replace(/[^a-z0-9_-]+/gi, "_");
+        const filename = `${String(attempt).padStart(2, "0")}-${safeKey}-${step}.md`;
+        const target = path.join(dir, filename);
+        await fs.writeFile(target, content, "utf8");
+        return target;
+    }
+    async prepareHandoff(jobId, taskKey, step, attempt, content) {
+        const safeKey = taskKey.replace(/[^a-z0-9_-]+/gi, "_");
+        const handoffId = `${safeKey}-${step}-${String(attempt).padStart(2, "0")}`;
+        const handoffPath = await writeGatewayHandoffFile(this.workspace.workspaceRoot, handoffId, content, "gateway-trio");
+        await this.writeHandoffArtifact(jobId, taskKey, step, attempt, content);
+        return handoffPath;
+    }
+    async projectKeyForTask(projectId) {
+        if (!projectId)
+            return undefined;
+        if (this.projectKeyCache.has(projectId))
+            return this.projectKeyCache.get(projectId);
+        const project = await this.deps.workspaceRepo.getProjectById(projectId);
+        if (!project)
+            return undefined;
+        this.projectKeyCache.set(projectId, project.key);
+        return project.key;
+    }
+    async seedExplicitTasks(state, explicitTasks, warnings) {
+        for (const taskKey of explicitTasks) {
+            if (state.tasks[taskKey])
+                continue;
+            const task = await this.deps.workspaceRepo.getTaskByKey(taskKey);
+            if (!task) {
+                warnings.push(`Explicit task ${taskKey} not found; skipping.`);
+                continue;
+            }
+            this.ensureProgress(state, taskKey);
+        }
+    }
+    ensureProgress(state, taskKey) {
+        const existing = state.tasks[taskKey];
+        if (existing) {
+            if (!existing.chosenAgents)
+                existing.chosenAgents = {};
+            if (!existing.failureHistory)
+                existing.failureHistory = [];
+            if (!existing.escalationAttempts)
+                existing.escalationAttempts = {};
+            if (!existing.stepOutcomes)
+                existing.stepOutcomes = {};
+            if (!existing.decisionHistory)
+                existing.decisionHistory = [];
+            return existing;
+        }
+        const created = {
+            taskKey,
+            attempts: 0,
+            status: "pending",
+            chosenAgents: {},
+            failureHistory: [],
+            escalationAttempts: {},
+            stepOutcomes: {},
+            decisionHistory: [],
+        };
+        state.tasks[taskKey] = created;
+        return created;
+    }
+    dedupeTaskKeys(keys) {
+        const seen = new Set();
+        const result = [];
+        for (const key of keys) {
+            const trimmed = key.trim();
+            if (!trimmed || seen.has(trimmed))
+                continue;
+            seen.add(trimmed);
+            result.push(trimmed);
+        }
+        return result;
+    }
+    buildRunListFromExplicit(taskKeys, limit, warnings) {
+        const filtered = taskKeys.filter((key) => !this.isPseudoTaskKey(key));
+        let deduped = this.dedupeTaskKeys(filtered);
+        if (typeof limit === "number" && limit > 0 && deduped.length > limit) {
+            warnings.push(`Run list limited to ${limit} explicit tasks; skipping ${deduped.length - limit} task(s).`);
+            deduped = deduped.slice(0, limit);
+        }
+        return deduped;
+    }
+    async buildRunListFromSelection(filters, limit, warnings) {
+        const selection = await this.selectionService.selectTasks(filters);
+        if (selection.warnings.length)
+            warnings.push(...selection.warnings);
+        const orderedKeys = selection.ordered.map((entry) => entry.task.key).filter((key) => !this.isPseudoTaskKey(key));
+        let deduped = this.dedupeTaskKeys(orderedKeys);
+        if (typeof limit === "number" && limit > 0 && deduped.length > limit) {
+            warnings.push(`Run list limited to ${limit} tasks; skipping ${deduped.length - limit} task(s).`);
+            deduped = deduped.slice(0, limit);
+        }
+        return deduped;
+    }
+    async guardMissingContext(step, jobId, taskKey, gateway, warnings, resolvedAgent) {
+        const filesMissing = gateway.analysis.filesLikelyTouched.length === 0 && gateway.analysis.filesToCreate.length === 0;
+        const docdexMissing = gateway.docdex.length === 0;
+        const docdexNotesText = gateway.analysis.docdexNotes.join(" ").toLowerCase();
+        const docdexSkipped = DOCDEX_SKIP_PATTERN.test(docdexNotesText);
+        const docdexExplicitMissing = DOCDEX_MISSING_PATTERN.test(docdexNotesText);
+        const missingTaskSignal = this.hasMissingTaskSignal(gateway.analysis);
+        if (!missingTaskSignal && (!filesMissing || !docdexMissing) && !(docdexSkipped && !docdexExplicitMissing)) {
+            return undefined;
+        }
+        const messageLines = [
+            missingTaskSignal
+                ? "Gateway analysis indicates the task details are missing; proceeding with execution anyway."
+                : docdexSkipped && !docdexExplicitMissing
+                    ? "Gateway analysis reported docdex work as not executed; proceeding without docdex context."
+                    : "Gateway analysis returned no file paths and no docdex context; proceeding.",
+            gateway.analysis.docdexNotes.length ? `Docdex notes: ${gateway.analysis.docdexNotes.join(" | ")}` : "Docdex notes: (none)",
+            gateway.analysis.assumptions.length ? `Assumptions: ${gateway.analysis.assumptions.join(" | ")}` : undefined,
+        ].filter(Boolean);
+        warnings.push(`Task ${taskKey} (${step}) gateway context incomplete.\n${messageLines.join("\n")}`);
+        return undefined;
+    }
+    hasMissingTaskSignal(analysis) {
+        const fields = [
+            analysis.summary,
+            analysis.currentState,
+            analysis.todo,
+            analysis.understanding,
+            ...(analysis.assumptions ?? []),
+            ...(analysis.docdexNotes ?? []),
+        ]
+            .filter(Boolean)
+            .join(" ");
+        return MISSING_TASK_PATTERN.test(fields);
+    }
+    hasReachedMaxIterations(progress, maxIterations) {
+        if (maxIterations === undefined)
+            return false;
+        const attempts = progress?.attempts ?? 0;
+        return attempts >= maxIterations;
+    }
+    hasIterationsRemaining(progress, maxIterations) {
+        if (maxIterations === undefined)
+            return true;
+        return progress.attempts < maxIterations;
+    }
+    shouldReopenFailedTask(progress, taskKey, warnings, continuousMode) {
+        if (!progress)
+            return true;
+        if (continuousMode)
+            return true;
+        if (progress.lastGuardrailRetryable === false) {
+            const lastFailure = progress.failureHistory?.[progress.failureHistory.length - 1];
+            const lastReasonRaw = progress.lastError ?? lastFailure?.reason ?? "guardrail_non_retryable";
+            warnings.push(`Task ${taskKey} failed with non-retryable reason ${lastReasonRaw}; skipping reopen.`);
+            return false;
+        }
+        const lastFailure = progress.failureHistory?.[progress.failureHistory.length - 1];
+        const lastReasonRaw = progress.lastError ?? lastFailure?.reason ?? "";
+        const lastReason = normalizeFailureReason(lastReasonRaw);
+        if (lastReason) {
+            if (NON_RETRYABLE_FAILURE_REASONS.has(lastReason)) {
+                warnings.push(`Task ${taskKey} failed with non-retryable reason ${lastReason}; skipping reopen.`);
+                return false;
+            }
+            if (/no eligible agents|missing required capabilities|agent .* missing required capabilities/i.test(lastReasonRaw)) {
+                warnings.push(`Task ${taskKey} failed due to agent selection; skipping reopen.`);
+                return false;
+            }
+            const sameReasonCount = progress.failureHistory?.filter((failure) => failure.reason === lastReason).length ?? 0;
+            if (sameReasonCount >= MAX_FAILURE_REOPENS_PER_REASON) {
+                warnings.push(`Task ${taskKey} hit retry cap for ${lastReason}; skipping reopen.`);
+                return false;
+            }
+            const lastTimestamp = lastFailure?.timestamp ? Date.parse(lastFailure.timestamp) : undefined;
+            if (Number.isFinite(lastTimestamp) && Date.now() - lastTimestamp < FAILED_REOPEN_COOLDOWN_MS) {
+                warnings.push(`Task ${taskKey} failed recently (${lastReason}); cooling down before reopen.`);
+                return false;
+            }
+        }
+        return true;
+    }
+    async reopenRetryableFailedTasks(state, explicitTasks, maxIterations, warnings) {
+        const continuousMode = maxIterations === undefined;
+        const keys = new Set([...explicitTasks, ...Object.keys(state.tasks)]);
+        for (const taskKey of keys) {
+            const progress = state.tasks[taskKey];
+            if (progress?.status === "completed")
+                continue;
+            const task = await this.deps.workspaceRepo.getTaskByKey(taskKey);
+            if (!task)
+                continue;
+            const status = this.normalizeStatus(task.status);
+            if (status === "completed" || status === "cancelled") {
+                const terminalProgress = progress ?? this.ensureProgress(state, taskKey);
+                terminalProgress.status = status === "completed" ? "completed" : "skipped";
+                terminalProgress.lastError = status === "completed" ? "completed_in_db" : "cancelled_in_db";
+                state.tasks[taskKey] = terminalProgress;
+                warnings.push(`Task ${taskKey} is ${status}; skipping reopen.`);
+                continue;
+            }
+            if (this.hasReachedMaxIterations(progress, maxIterations)) {
+                if (progress) {
+                    progress.status = "failed";
+                    if (!progress.lastError) {
+                        progress.lastError = "max_iterations_reached";
+                    }
+                    state.tasks[taskKey] = progress;
+                }
+                if (maxIterations !== undefined) {
+                    warnings.push(`Task ${taskKey} hit max iterations (${maxIterations}); skipping reopen.`);
+                }
+                continue;
+            }
+            const metadata = task.metadata ?? {};
+            const failedReason = typeof metadata.failed_reason === "string" ? metadata.failed_reason : undefined;
+            if (status === "failed") {
+                if (failedReason === "dependency_not_ready") {
+                    const depsReady = await this.dependenciesReady(task.id, warnings);
+                    if (!depsReady)
+                        continue;
+                }
+                if (!continuousMode &&
+                    (progress?.lastGuardrailRetryable === false ||
+                        (failedReason && NON_RETRYABLE_FAILURE_REASONS.has(failedReason)))) {
+                    const reasonLabel = failedReason ?? progress?.lastError ?? progress?.lastEscalationReason ?? "guardrail_non_retryable";
+                    warnings.push(`Task ${taskKey} failed with non-retryable reason ${reasonLabel}; skipping reopen.`);
+                    continue;
+                }
+                if (!continuousMode && progress && !this.shouldReopenFailedTask(progress, taskKey, warnings, continuousMode)) {
+                    continue;
+                }
+            }
+            else if (progress?.status !== "failed") {
+                continue;
+            }
+            else if (!continuousMode && !this.shouldReopenFailedTask(progress, taskKey, warnings, continuousMode)) {
+                continue;
+            }
+            const nextMetadata = { ...metadata };
+            delete nextMetadata.failed_reason;
+            if (status === "failed") {
+                await this.deps.workspaceRepo.updateTask(task.id, {
+                    status: "in_progress",
+                    metadata: nextMetadata,
+                });
+            }
+            if (progress) {
+                progress.status = "pending";
+                progress.lastError = undefined;
+                state.tasks[taskKey] = progress;
+            }
+            warnings.push(`Reopened failed task ${taskKey} (reason=${failedReason ?? progress?.lastError ?? "unknown"}) for retry (attempts=${progress?.attempts ?? 0}${maxIterations !== undefined ? `/${maxIterations}` : ""}).`);
+        }
+    }
+    async dependenciesReady(taskId, warnings) {
+        const deps = await this.deps.workspaceRepo.getTaskDependencies([taskId]);
+        if (!deps.length)
+            return true;
+        const depIds = deps.map((dep) => dep.dependsOnTaskId).filter((id) => Boolean(id));
+        if (!depIds.length)
+            return true;
+        const depTasks = await this.deps.workspaceRepo.getTasksByIds(depIds);
+        const depMap = new Map(depTasks.map((task) => [task.id, task]));
+        for (const depId of depIds) {
+            const depTask = depMap.get(depId);
+            if (!depTask) {
+                warnings.push(`Dependency ${depId} not found for task ${taskId}; treating as not ready.`);
+                return false;
+            }
+            const status = this.normalizeStatus(depTask.status);
+            if (!status || !DONE_DEPENDENCY_STATUSES.has(status))
+                return false;
+        }
+        return true;
+    }
+    normalizeStatus(status) {
+        return status ? status.toLowerCase().trim() : undefined;
+    }
+    resolveRequest(request, payload) {
+        if (!payload) {
+            return { ...request, rateAgents: request.rateAgents ?? true };
+        }
+        const raw = payload;
+        const payloadTasks = Array.isArray(raw.tasks) ? raw.tasks : undefined;
+        const payloadStatuses = Array.isArray(raw.statusFilter) ? raw.statusFilter : undefined;
+        const resolvedQaResult = (request.qaResult ?? raw.qaResult);
+        const normalizedQaResult = resolvedQaResult === "blocked" ? "fail" : resolvedQaResult;
+        return {
+            ...request,
+            projectKey: request.projectKey ?? raw.projectKey,
+            epicKey: request.epicKey ?? raw.epicKey,
+            storyKey: request.storyKey ?? raw.storyKey,
+            taskKeys: request.taskKeys && request.taskKeys.length ? request.taskKeys : payloadTasks,
+            statusFilter: request.statusFilter && request.statusFilter.length ? request.statusFilter : payloadStatuses,
+            limit: request.limit ?? raw.limit,
+            parallel: request.parallel ?? raw.parallel,
+            maxIterations: request.maxIterations ?? raw.maxIterations,
+            maxCycles: request.maxCycles ?? raw.maxCycles,
+            gatewayAgentName: request.gatewayAgentName ?? raw.gatewayAgentName,
+            workAgentName: request.workAgentName ?? raw.workAgentName,
+            reviewAgentName: request.reviewAgentName ?? raw.reviewAgentName,
+            qaAgentName: request.qaAgentName ?? raw.qaAgentName,
+            maxDocs: request.maxDocs ?? raw.maxDocs,
+            agentStream: request.agentStream ?? raw.agentStream,
+            rateAgents: request.rateAgents ?? raw.rateAgents ?? true,
+            noCommit: request.noCommit ?? raw.noCommit,
+            dryRun: request.dryRun ?? raw.dryRun,
+            reviewBase: request.reviewBase ?? raw.reviewBase,
+            maxAgentSeconds: request.maxAgentSeconds ?? raw.maxAgentSeconds,
+            qaProfileName: request.qaProfileName ?? raw.qaProfileName,
+            qaLevel: request.qaLevel ?? raw.qaLevel,
+            qaTestCommand: request.qaTestCommand ?? raw.qaTestCommand,
+            qaMode: request.qaMode ?? raw.qaMode,
+            qaFollowups: request.qaFollowups ?? raw.qaFollowups,
+            reviewFollowups: request.reviewFollowups ?? raw.reviewFollowups,
+            qaResult: normalizedQaResult,
+            qaNotes: request.qaNotes ?? raw.qaNotes,
+            qaEvidenceUrl: request.qaEvidenceUrl ?? raw.qaEvidenceUrl,
+            qaAllowDirty: request.qaAllowDirty ?? raw.qaAllowDirty,
+            escalateOnNoChange: request.escalateOnNoChange ?? raw.escalateOnNoChange,
+            workRunner: request.workRunner ?? raw.workRunner,
+            useCodali: request.useCodali ?? raw.useCodali,
+            agentAdapterOverride: request.agentAdapterOverride ?? raw.agentAdapterOverride,
+        };
+    }
+    async buildStatusFilter(request, warnings) {
+        const base = request.statusFilter && request.statusFilter.length ? request.statusFilter : DEFAULT_STATUS_FILTER;
+        const normalized = new Set(base.map((s) => this.normalizeStatus(s)).filter(Boolean));
+        const explicit = request.taskKeys ?? [];
+        for (const key of explicit) {
+            const task = await this.deps.workspaceRepo.getTaskByKey(key);
+            if (!task) {
+                warnings.push(`Task not found: ${key}`);
+                continue;
+            }
+            const status = this.normalizeStatus(task.status);
+            if (!status)
+                continue;
+            if (TERMINAL_STATUSES.has(status)) {
+                warnings.push(`Skipping terminal task ${key} (${status}).`);
+                continue;
+            }
+            if (!normalized.has(status))
+                normalized.add(status);
+        }
+        return Array.from(normalized);
+    }
+    async refreshTaskStatus(taskKey, warnings) {
+        const task = await this.deps.workspaceRepo.getTaskByKey(taskKey);
+        if (!task) {
+            warnings.push(`Task ${taskKey} not found while refreshing status.`);
+            return undefined;
+        }
+        return this.normalizeStatus(task.status);
+    }
+    parseWorkResult(taskKey, result) {
+        const entry = result.results.find((r) => r.taskKey === taskKey);
+        if (!entry) {
+            return { step: "work", status: "failed", error: "Task not processed by work-on-tasks" };
+        }
+        const guardrail = parseGuardrailReason(entry.notes);
+        if (entry.status === "succeeded") {
+            return { step: "work", status: "succeeded" };
+        }
+        if (entry.status === "skipped") {
+            return {
+                step: "work",
+                status: "skipped",
+                error: guardrail?.reason ?? entry.notes,
+                guardrailReason: guardrail?.reason,
+                guardrailRetryable: guardrail?.retryable,
+            };
+        }
+        return {
+            step: "work",
+            status: "failed",
+            error: guardrail?.reason ?? entry.notes,
+            guardrailReason: guardrail?.reason,
+            guardrailRetryable: guardrail?.retryable,
+        };
+    }
+    parseReviewResult(taskKey, result) {
+        const entry = result.tasks.find((t) => t.taskKey === taskKey);
+        if (!entry) {
+            return { step: "review", status: "failed", error: "Task not processed by code-review" };
+        }
+        if (entry.error) {
+            const guardrail = parseGuardrailReason(entry.error);
+            return {
+                step: "review",
+                status: "failed",
+                error: guardrail?.reason ?? entry.error,
+                guardrailReason: guardrail?.reason,
+                guardrailRetryable: guardrail?.retryable,
+            };
+        }
+        const decision = entry.decision ?? "error";
+        if (decision === "approve" || decision === "info_only")
+            return { step: "review", status: "succeeded", decision };
+        if (decision === "changes_requested")
+            return { step: "review", status: "succeeded", decision };
+        if (decision === "block")
+            return { step: "review", status: "failed", decision };
+        return { step: "review", status: "failed", decision };
+    }
+    parseQaResult(taskKey, result) {
+        const entry = result.results.find((r) => r.taskKey === taskKey);
+        if (!entry) {
+            return { step: "qa", status: "failed", error: "Task not processed by qa-tasks" };
+        }
+        const guardrail = parseGuardrailReason(entry.outcome);
+        if (entry.outcome === "pass") {
+            return {
+                step: "qa",
+                status: "succeeded",
+                outcome: entry.outcome,
+                notes: entry.notes,
+                artifacts: entry.artifacts,
+            };
+        }
+        if (entry.outcome === "infra_issue") {
+            return {
+                step: "qa",
+                status: "failed",
+                outcome: entry.outcome,
+                notes: entry.notes,
+                artifacts: entry.artifacts,
+            };
+        }
+        if (entry.outcome === "fix_required" || entry.outcome === "unclear") {
+            return {
+                step: "qa",
+                status: "failed",
+                outcome: entry.outcome,
+                notes: entry.notes,
+                artifacts: entry.artifacts,
+            };
+        }
+        return {
+            step: "qa",
+            status: "failed",
+            outcome: guardrail?.reason ?? entry.outcome,
+            notes: entry.notes,
+            artifacts: entry.artifacts,
+            guardrailReason: guardrail?.reason,
+            guardrailRetryable: guardrail?.retryable,
+        };
+    }
+    isAuthFailure(reason) {
+        return normalizeFailureReason(reason) === AUTH_ERROR_REASON;
+    }
+    shouldRetryAfter(step) {
+        if (step.status === "skipped")
+            return false;
+        if (typeof step.guardrailRetryable === "boolean")
+            return step.guardrailRetryable;
+        const reason = normalizeFailureReason(step.error ?? step.decision ?? step.outcome ?? "");
+        if (reason === "infra_issue" || reason === "block")
+            return false;
+        if (reason && NON_RETRYABLE_FAILURE_REASONS.has(reason))
+            return false;
+        return step.status !== "succeeded";
+    }
+    escalationReasons(escalateOnNoChange) {
+        const reasons = new Set(ESCALATION_REASONS);
+        if (escalateOnNoChange)
+            reasons.add(NO_CHANGE_REASON);
+        return reasons;
+    }
+    resolveTierFromComplexity(complexity) {
+        if (typeof complexity !== "number" || !Number.isFinite(complexity))
+            return "unknown";
+        const normalized = Math.round(complexity);
+        if (normalized >= SPECIALIST_TIER_MIN_COMPLEXITY)
+            return "specialist";
+        if (normalized >= STRONG_TIER_MIN_COMPLEXITY)
+            return "strong";
+        return "cheap";
+    }
+    nextTier(current) {
+        if (current === "strong")
+            return "specialist";
+        if (current === "specialist")
+            return undefined;
+        return "strong";
+    }
+    recordFailure(progress, step, attempt) {
+        if (step.status !== "failed")
+            return;
+        const reason = step.guardrailReason ?? step.error ?? step.decision ?? step.outcome;
+        const agent = step.chosenAgent;
+        if (typeof step.guardrailRetryable === "boolean") {
+            progress.lastGuardrailRetryable = step.guardrailRetryable;
+        }
+        if (!reason)
+            return;
+        const normalized = normalizeFailureReason(reason) ?? reason;
+        progress.lastEscalationReason = normalized;
+        const attempts = progress.escalationAttempts ?? {};
+        attempts[normalized] = (attempts[normalized] ?? 0) + 1;
+        progress.escalationAttempts = attempts;
+        if (!agent)
+            return;
+        const history = progress.failureHistory ?? [];
+        history.push({ step: step.step, agent, reason, attempt, timestamp: new Date().toISOString() });
+        progress.failureHistory = history;
+    }
+    mergeGatewayFiles(outcome) {
+        const values = [...(outcome.gatewayFiles ?? [])];
+        const unique = new Set();
+        const merged = [];
+        for (const value of values) {
+            const trimmed = value.trim();
+            if (!trimmed || unique.has(trimmed))
+                continue;
+            unique.add(trimmed);
+            merged.push(trimmed);
+        }
+        return merged;
+    }
+    handoffContextForProgress(progress) {
+        const qaFailureSummary = progress.lastQaFailureSummary?.trim();
+        const learningSummary = progress.pendingLearningSummary?.trim();
+        if (!qaFailureSummary && !learningSummary)
+            return undefined;
+        return {
+            qaFailureSummary,
+            learningSummary,
+        };
+    }
+    appendFallbackHandoffContext(baseLines, context) {
+        if (!context?.qaFailureSummary?.trim() && !context?.learningSummary?.trim()) {
+            return baseLines;
+        }
+        const lines = [...baseLines];
+        if (context.qaFailureSummary?.trim()) {
+            lines.push("", "## QA Failure Summary", context.qaFailureSummary.trim());
+        }
+        if (context.learningSummary?.trim()) {
+            lines.push("", "## Revert Learning", context.learningSummary.trim());
+        }
+        return lines;
+    }
+    recordDecision(progress, step, attempt, kind, status, detail) {
+        const stepOutcomes = progress.stepOutcomes ?? {};
+        stepOutcomes[step] = detail ? `${status}:${detail}` : status;
+        progress.stepOutcomes = stepOutcomes;
+        const history = progress.decisionHistory ?? [];
+        history.push({
+            step,
+            kind,
+            status,
+            detail,
+            attempt,
+            timestamp: new Date().toISOString(),
+        });
+        progress.decisionHistory = history.slice(Math.max(0, history.length - DECISION_HISTORY_MAX));
+    }
+    buildQaFailureSummary(taskKey, outcome) {
+        const fragments = [];
+        fragments.push(`Task ${taskKey} QA outcome: ${outcome.outcome ?? outcome.status}.`);
+        if (outcome.error) {
+            fragments.push(`Error: ${outcome.error}.`);
+        }
+        if (outcome.notes) {
+            fragments.push(`Notes: ${outcome.notes}.`);
+        }
+        if (outcome.artifacts?.length) {
+            fragments.push(`Artifacts: ${outcome.artifacts.join(", ")}.`);
+        }
+        return fragments.join(" ").trim();
+    }
+    extractRevertLearning(taskKey, metadata) {
+        if (!metadata || typeof metadata !== "object")
+            return undefined;
+        const pending = metadata.revert_event_pending === true;
+        const rawEvent = metadata.last_revert_event;
+        if (!pending || !rawEvent || typeof rawEvent !== "object")
+            return undefined;
+        const reason = typeof rawEvent.reason === "string" && rawEvent.reason.trim().length > 0
+            ? rawEvent.reason.trim()
+            : "No explicit reason provided.";
+        const from = typeof rawEvent.from_status === "string" ? rawEvent.from_status : "completed";
+        const to = typeof rawEvent.to_status === "string" ? rawEvent.to_status : "changes_requested";
+        const timestamp = typeof rawEvent.timestamp === "string" ? rawEvent.timestamp : undefined;
+        const summary = `Revert detected for ${taskKey}: status moved ${from} -> ${to}. Feedback: ${reason}`;
+        return { summary, eventAt: timestamp };
+    }
+    shouldSavePreference(summary) {
+        const lower = summary.toLowerCase();
+        return /\b(always|never|prefer|do not|don't|must)\b/.test(lower);
+    }
+    async persistRevertLearning(taskId, taskKey, metadata, progress, warnings) {
+        const learning = this.extractRevertLearning(taskKey, metadata);
+        if (!learning)
+            return;
+        progress.pendingLearningSummary = learning.summary;
+        progress.lastRevertEventAt = learning.eventAt ?? new Date().toISOString();
+        const gatewayWithLearning = this.deps.gatewayService;
+        try {
+            if (typeof gatewayWithLearning.saveRepoMemory === "function") {
+                await gatewayWithLearning.saveRepoMemory(learning.summary);
+            }
+            if (this.shouldSavePreference(learning.summary) && typeof gatewayWithLearning.savePreference === "function") {
+                await gatewayWithLearning.savePreference("constraint", learning.summary, "codex");
+            }
+        }
+        catch (error) {
+            warnings.push(`Revert learning persistence failed for ${taskKey}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (metadata) {
+            const nextMetadata = { ...metadata, revert_event_pending: false };
+            await this.deps.workspaceRepo.updateTask(taskId, { metadata: nextMetadata });
+        }
+    }
+    sanitizeGoldenText(value) {
+        return value
+            .replace(/AKIA[0-9A-Z]{16}/g, "[REDACTED_AWS_KEY]")
+            .replace(/\bsk-[A-Za-z0-9]{20,}\b/g, "[REDACTED_TOKEN]")
+            .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, "Bearer [REDACTED]")
+            .trim();
+    }
+    async appendGoldenExample(entry) {
+        const targetPath = path.join(this.workspace.workspaceRoot, GOLDEN_EXAMPLES_REL_PATH);
+        await PathHelper.ensureDir(path.dirname(targetPath));
+        let existing = [];
+        try {
+            const raw = await fs.readFile(targetPath, "utf8");
+            existing = raw
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .map((line) => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    return undefined;
+                }
+            })
+                .filter((item) => Boolean(item));
+        }
+        catch (error) {
+            if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) {
+                throw error;
+            }
+        }
+        const next = {
+            intent: this.sanitizeGoldenText(entry.title ? `${entry.taskKey}: ${entry.title}` : entry.taskKey),
+            plan_summary: this.sanitizeGoldenText(entry.planSummary),
+            touched_files: entry.touchedFiles.map((file) => file.trim()).filter(Boolean),
+            review_notes: entry.reviewNotes ? this.sanitizeGoldenText(entry.reviewNotes) : undefined,
+            qa_notes: entry.qaNotes ? this.sanitizeGoldenText(entry.qaNotes) : undefined,
+            created_at: new Date().toISOString(),
+        };
+        const bounded = [...existing, next].slice(Math.max(0, existing.length + 1 - GOLDEN_EXAMPLES_MAX));
+        const payload = bounded.map((item) => JSON.stringify(item)).join("\n");
+        await fs.writeFile(targetPath, payload.length > 0 ? `${payload}\n` : "", "utf8");
+    }
+    countFailures(progress, step, reason) {
+        if (!progress?.failureHistory?.length)
+            return 0;
+        return progress.failureHistory.filter((failure) => failure.step === step && failure.reason === reason).length;
+    }
+    prioritizeFeedbackTasks(ordered, state) {
+        const feedback = new Set();
+        for (const progress of Object.values(state.tasks)) {
+            if (progress.lastDecision === "changes_requested") {
+                feedback.add(progress.taskKey);
+                continue;
+            }
+            if (progress.lastOutcome === "fix_required" || progress.lastOutcome === "unclear") {
+                feedback.add(progress.taskKey);
+            }
+        }
+        if (feedback.size === 0)
+            return ordered;
+        const prioritized = [];
+        const remaining = [];
+        for (const entry of ordered) {
+            if (feedback.has(entry.task.key)) {
+                prioritized.push(entry);
+            }
+            else {
+                remaining.push(entry);
+            }
+        }
+        return [...prioritized, ...remaining];
+    }
+    buildAgentOptions(progress, step, request) {
+        const reasons = this.escalationReasons(request.escalateOnNoChange !== false);
+        const history = (progress.failureHistory ?? []).filter((failure) => {
+            if (failure.step !== step)
+                return false;
+            const normalized = normalizeFailureReason(failure.reason) ?? failure.reason;
+            return reasons.has(normalized);
+        });
+        const forceStronger = history.length > 0;
+        const forceTier = step === "work" && forceStronger ? this.nextTier(progress.lastWorkAgentTier) : undefined;
+        const avoidAgents = history.length > 1 ? Array.from(new Set(history.map((failure) => failure.agent))) : [];
+        return { avoidAgents, forceStronger, forceTier };
+    }
+    recordRating(progress, summary) {
+        if (!summary)
+            return;
+        const existing = progress.ratings ?? [];
+        const next = existing.filter((entry) => entry.step !== summary.step);
+        next.push(summary);
+        progress.ratings = next;
+    }
+    async loadRatingSummary(jobId, step, agent) {
+        if (!jobId)
+            return undefined;
+        try {
+            const payload = await fs.readFile(path.join(this.workspace.mcodaDir, "jobs", jobId, "rating.json"), "utf8");
+            const parsed = JSON.parse(payload);
+            const rating = typeof parsed.rating === "number" ? parsed.rating : undefined;
+            const maxComplexity = typeof parsed.maxComplexity === "number" ? parsed.maxComplexity : undefined;
+            const runScore = typeof parsed.runScore === "number" ? parsed.runScore : undefined;
+            const qualityScore = typeof parsed.qualityScore === "number" ? parsed.qualityScore : undefined;
+            return { step, agent, rating, maxComplexity, runScore, qualityScore };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async updateJobHeartbeat(params) {
+        const timestamp = new Date().toISOString();
+        const detail = `task:${params.taskKey} step:${params.step} attempt:${params.attempt} last:${timestamp}`;
+        try {
+            await this.deps.jobService.updateJobStatus(params.jobId, "running", {
+                job_state_detail: detail,
+                payload: {
+                    current_task: params.taskKey,
+                    current_step: params.step,
+                    attempt: params.attempt,
+                    last_activity: timestamp,
+                    activity: params.activity ?? "heartbeat",
+                },
+            });
+        }
+        catch {
+            // Avoid failing the run if heartbeat updates cannot be persisted.
+        }
+    }
+    async runStepWithTimeout(step, jobId, taskKey, attempt, maxAgentSeconds, fn) {
+        await this.updateJobHeartbeat({ jobId, taskKey, step, attempt, activity: "start" });
+        await this.deps.jobService.writeCheckpoint(jobId, {
+            stage: `task:${taskKey}:${step}:start`,
+            timestamp: new Date().toISOString(),
+            details: { taskKey, attempt, step },
+        });
+        const timeoutMs = typeof maxAgentSeconds === "number" && maxAgentSeconds > 0 ? maxAgentSeconds * 1000 : undefined;
+        let timeoutHandle;
+        const controller = new AbortController();
+        const heartbeat = setInterval(() => {
+            void this.updateJobHeartbeat({ jobId, taskKey, step, attempt, activity: "heartbeat" }).catch(() => { });
+            void this.deps.jobService.writeCheckpoint(jobId, {
+                stage: `task:${taskKey}:${step}:heartbeat`,
+                timestamp: new Date().toISOString(),
+                details: { taskKey, attempt, step },
+            });
+        }, HEARTBEAT_INTERVAL_MS);
+        if (typeof heartbeat.unref === "function") {
+            heartbeat.unref();
+        }
+        try {
+            if (timeoutMs) {
+                const timeoutPromise = new Promise((_, reject) => {
+                    timeoutHandle = setTimeout(() => {
+                        controller.abort("agent_timeout");
+                        reject(new Error("agent_timeout"));
+                    }, timeoutMs);
+                });
+                return await Promise.race([fn(controller.signal), timeoutPromise]);
+            }
+            return await fn(controller.signal);
+        }
+        catch (error) {
+            const message = error?.message ?? String(error);
+            return { step, status: "failed", error: message === "agent_timeout" ? "agent_timeout" : message };
+        }
+        finally {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            clearInterval(heartbeat);
+        }
+    }
+    async runGateway(job, taskKey, projectKey, request, agentOptions) {
+        const startedAt = new Date().toISOString();
+        const shouldSuppressIo = Boolean(request.onGatewayStart || request.onGatewayEnd || request.onGatewayChunk);
+        let gatewaySlug = request.gatewayAgentName ?? "auto";
+        let chosenSlug;
+        let chosenModel;
+        let chosenAdapter;
+        let status = "failed";
+        let errorMessage;
+        let startEmitted = false;
+        const invoke = () => this.deps.gatewayService.run({
+            workspace: this.workspace,
+            job,
+            projectKey,
+            taskKeys: [taskKey],
+            gatewayAgentName: request.gatewayAgentName,
+            maxDocs: request.maxDocs,
+            agentStream: request.agentStream,
+            onStreamChunk: request.onGatewayChunk,
+            rateAgents: request.rateAgents,
+            avoidAgents: agentOptions?.avoidAgents,
+            forceStronger: agentOptions?.forceStronger,
+            forceTier: agentOptions?.forceTier,
+        });
+        try {
+            startEmitted = true;
+            request.onGatewayStart?.({
+                taskKey,
+                job,
+                gatewayAgent: gatewaySlug,
+                startedAt,
+            });
+            const result = shouldSuppressIo ? await this.withGatewayIoSuppressed(invoke) : await invoke();
+            gatewaySlug = result.gatewayAgent.slug ?? result.gatewayAgent.id;
+            chosenSlug = result.chosenAgent.agentSlug ?? result.chosenAgent.agentId;
+            try {
+                const resolved = await this.deps.routingService.resolveAgentForCommand({
+                    workspace: this.workspace,
+                    commandName: job,
+                    overrideAgentSlug: chosenSlug,
+                });
+                chosenModel = resolved.model ?? resolved.agent.defaultModel;
+                chosenAdapter = resolved.agent.adapter;
+            }
+            catch {
+                chosenModel = undefined;
+                chosenAdapter = undefined;
+            }
+            request.onGatewaySelection?.({
+                taskKey,
+                job,
+                gatewayAgent: gatewaySlug,
+                chosenAgent: chosenSlug,
+                chosenModel,
+                chosenAdapter,
+                startedAt,
+            });
+            status = "completed";
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errorMessage = message;
+            const wrapped = message ? `${GATEWAY_FAILED_REASON}:${message}` : GATEWAY_FAILED_REASON;
+            throw new Error(wrapped);
+        }
+        finally {
+            if (startEmitted) {
+                request.onGatewayEnd?.({
+                    taskKey,
+                    job,
+                    gatewayAgent: gatewaySlug,
+                    chosenAgent: chosenSlug,
+                    chosenModel,
+                    chosenAdapter,
+                    startedAt,
+                    endedAt: new Date().toISOString(),
+                    status,
+                    error: errorMessage,
+                });
+            }
+        }
+    }
+    async withGatewayIoSuppressed(fn) {
+        const ioEnv = "MCODA_STREAM_IO";
+        const promptEnv = "MCODA_STREAM_IO_PROMPT";
+        const prevIo = process.env[ioEnv];
+        const prevPrompt = process.env[promptEnv];
+        process.env[ioEnv] = "0";
+        process.env[promptEnv] = "0";
+        try {
+            return await fn();
+        }
+        finally {
+            if (prevIo === undefined) {
+                delete process.env[ioEnv];
+            }
+            else {
+                process.env[ioEnv] = prevIo;
+            }
+            if (prevPrompt === undefined) {
+                delete process.env[promptEnv];
+            }
+            else {
+                process.env[promptEnv] = prevPrompt;
+            }
+        }
+    }
+    async runWorkStep(jobId, attempt, taskKey, projectKey, statusFilter, request, warnings, agentOptions, abortSignal, handoffContext, onResolvedAgent) {
+        let gateway;
+        let handoff;
+        let resolvedAgent;
+        await this.deps.gatewayService.preflightExecutionAgents("work-on-tasks", request.workAgentName);
+        try {
+            gateway = await this.runGateway("work-on-tasks", taskKey, projectKey, request, agentOptions);
+            resolvedAgent = request.workAgentName ?? gateway.chosenAgent.agentSlug ?? gateway.chosenAgent.agentId;
+            const missingContext = await this.guardMissingContext("work", jobId, taskKey, gateway, warnings, resolvedAgent);
+            if (missingContext) {
+                return missingContext;
+            }
+            handoff = buildGatewayHandoffContent(gateway, handoffContext);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!request.workAgentName)
+                throw error;
+            resolvedAgent = request.workAgentName;
+            handoff = this.appendFallbackHandoffContext([
+                "# Gateway Handoff",
+                "",
+                `Gateway agent failed; proceeding with override agent ${resolvedAgent}.`,
+                `Error: ${message}`,
+                "",
+                buildGatewayHandoffDocdexUsage(),
+            ], handoffContext).join("\n");
+            warnings.push(`Gateway agent failed for work ${taskKey}; using override ${resolvedAgent}: ${message}`);
+        }
+        if (!resolvedAgent) {
+            throw new Error(`No agent resolved for work step on ${taskKey}`);
+        }
+        if (onResolvedAgent) {
+            await onResolvedAgent(resolvedAgent);
+        }
+        const selectedTier = this.resolveTierFromComplexity(gateway?.analysis?.complexity);
+        const handoffPath = await this.prepareHandoff(jobId, taskKey, "work", attempt, handoff);
+        const result = await withGatewayHandoff(handoffPath, async () => this.deps.workService.workOnTasks({
+            workspace: this.workspace,
+            projectKey,
+            taskKeys: [taskKey],
+            statusFilter,
+            limit: 1,
+            noCommit: request.noCommit,
+            dryRun: request.dryRun,
+            agentName: resolvedAgent,
+            agentStream: request.agentStream,
+            workRunner: request.workRunner,
+            useCodali: request.useCodali,
+            agentAdapterOverride: request.agentAdapterOverride,
+            rateAgents: request.rateAgents,
+            abortSignal,
+            maxAgentSeconds: request.maxAgentSeconds,
+        }));
+        const parsed = this.parseWorkResult(taskKey, result);
+        const ratingSummary = request.rateAgents
+            ? await this.loadRatingSummary(result.jobId, "work", resolvedAgent)
+            : undefined;
+        const zeroTokens = await this.isZeroTokenRun(result.jobId, result.commandRunId);
+        if (zeroTokens) {
+            return {
+                step: "work",
+                status: "failed",
+                error: ZERO_TOKEN_ERROR,
+                chosenAgent: resolvedAgent,
+                ratingSummary,
+                tier: selectedTier,
+                gatewayPlan: gateway?.analysis?.plan ?? [],
+                gatewayFiles: [...(gateway?.analysis?.filesLikelyTouched ?? []), ...(gateway?.analysis?.filesToCreate ?? [])],
+            };
+        }
+        return {
+            ...parsed,
+            chosenAgent: resolvedAgent,
+            ratingSummary,
+            tier: selectedTier,
+            gatewayPlan: gateway?.analysis?.plan ?? [],
+            gatewayFiles: [...(gateway?.analysis?.filesLikelyTouched ?? []), ...(gateway?.analysis?.filesToCreate ?? [])],
+        };
+    }
+    async runReviewStep(jobId, attempt, taskKey, projectKey, statusFilter, request, warnings, agentOptions, abortSignal, handoffContext, onResolvedAgent) {
+        let gateway;
+        let handoff;
+        let resolvedAgent;
+        await this.deps.gatewayService.preflightExecutionAgents("code-review", request.reviewAgentName);
+        try {
+            gateway = await this.runGateway("code-review", taskKey, projectKey, request, agentOptions);
+            resolvedAgent = request.reviewAgentName ?? gateway.chosenAgent.agentSlug ?? gateway.chosenAgent.agentId;
+            const missingContext = await this.guardMissingContext("review", jobId, taskKey, gateway, warnings, resolvedAgent);
+            if (missingContext) {
+                return missingContext;
+            }
+            handoff = buildGatewayHandoffContent(gateway, handoffContext);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!request.reviewAgentName)
+                throw error;
+            resolvedAgent = request.reviewAgentName;
+            handoff = this.appendFallbackHandoffContext([
+                "# Gateway Handoff",
+                "",
+                `Routing failed; proceeding with override agent ${resolvedAgent}.`,
+                `Error: ${message}`,
+                "",
+                buildGatewayHandoffDocdexUsage(),
+            ], handoffContext).join("\n");
+            warnings.push(`Gateway agent failed for review ${taskKey}; using override ${resolvedAgent}: ${message}`);
+        }
+        if (!resolvedAgent) {
+            throw new Error(`No agent resolved for review step on ${taskKey}`);
+        }
+        if (onResolvedAgent) {
+            await onResolvedAgent(resolvedAgent);
+        }
+        const handoffPath = await this.prepareHandoff(jobId, taskKey, "review", attempt, handoff);
+        const result = await withGatewayHandoff(handoffPath, async () => this.deps.reviewService.reviewTasks({
+            workspace: this.workspace,
+            projectKey,
+            taskKeys: [taskKey],
+            statusFilter,
+            baseRef: request.reviewBase,
+            dryRun: request.dryRun,
+            agentName: resolvedAgent,
+            agentStream: request.agentStream,
+            rateAgents: request.rateAgents,
+            createFollowupTasks: request.reviewFollowups === true,
+            abortSignal,
+        }));
+        const parsed = this.parseReviewResult(taskKey, result);
+        const ratingSummary = request.rateAgents
+            ? await this.loadRatingSummary(result.jobId, "review", resolvedAgent)
+            : undefined;
+        const zeroTokens = await this.isZeroTokenRun(result.jobId, result.commandRunId);
+        if (zeroTokens) {
+            return {
+                step: "review",
+                status: "failed",
+                error: ZERO_TOKEN_ERROR,
+                chosenAgent: resolvedAgent,
+                ratingSummary,
+                gatewayPlan: gateway?.analysis?.plan ?? [],
+                gatewayFiles: [...(gateway?.analysis?.filesLikelyTouched ?? []), ...(gateway?.analysis?.filesToCreate ?? [])],
+            };
+        }
+        return {
+            ...parsed,
+            chosenAgent: resolvedAgent,
+            ratingSummary,
+            gatewayPlan: gateway?.analysis?.plan ?? [],
+            gatewayFiles: [...(gateway?.analysis?.filesLikelyTouched ?? []), ...(gateway?.analysis?.filesToCreate ?? [])],
+        };
+    }
+    async runQaStep(jobId, attempt, taskKey, projectKey, statusFilter, request, warnings, agentOptions, abortSignal, handoffContext, onResolvedAgent) {
+        let gateway;
+        let handoff;
+        let resolvedAgent;
+        await this.deps.gatewayService.preflightExecutionAgents("qa-tasks", request.qaAgentName);
+        try {
+            gateway = await this.runGateway("qa-tasks", taskKey, projectKey, request, agentOptions);
+            resolvedAgent = request.qaAgentName ?? gateway.chosenAgent.agentSlug ?? gateway.chosenAgent.agentId;
+            const missingContext = await this.guardMissingContext("qa", jobId, taskKey, gateway, warnings, resolvedAgent);
+            if (missingContext) {
+                return missingContext;
+            }
+            handoff = buildGatewayHandoffContent(gateway, handoffContext);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!request.qaAgentName)
+                throw error;
+            resolvedAgent = request.qaAgentName;
+            handoff = this.appendFallbackHandoffContext([
+                "# Gateway Handoff",
+                "",
+                `Routing failed; proceeding with override agent ${resolvedAgent}.`,
+                `Error: ${message}`,
+                "",
+                buildGatewayHandoffDocdexUsage(),
+            ], handoffContext).join("\n");
+            warnings.push(`Gateway agent failed for QA ${taskKey}; using override ${resolvedAgent}: ${message}`);
+        }
+        if (!resolvedAgent) {
+            throw new Error(`No agent resolved for QA step on ${taskKey}`);
+        }
+        if (onResolvedAgent) {
+            await onResolvedAgent(resolvedAgent);
+        }
+        const handoffPath = await this.prepareHandoff(jobId, taskKey, "qa", attempt, handoff);
+        const result = await withGatewayHandoff(handoffPath, async () => this.deps.qaService.run({
+            workspace: this.workspace,
+            projectKey,
+            taskKeys: [taskKey],
+            statusFilter,
+            mode: request.qaMode ?? "auto",
+            profileName: request.qaProfileName,
+            level: request.qaLevel,
+            testCommand: request.qaTestCommand,
+            agentName: resolvedAgent,
+            agentStream: request.agentStream,
+            rateAgents: request.rateAgents,
+            createFollowupTasks: request.qaFollowups ?? "auto",
+            dryRun: request.dryRun,
+            result: request.qaResult,
+            notes: request.qaNotes,
+            evidenceUrl: request.qaEvidenceUrl,
+            allowDirty: request.qaAllowDirty,
+            abortSignal,
+        }));
+        const parsed = this.parseQaResult(taskKey, result);
+        const ratingSummary = request.rateAgents
+            ? await this.loadRatingSummary(result.jobId, "qa", resolvedAgent)
+            : undefined;
+        const zeroTokens = await this.isZeroTokenRun(result.jobId, result.commandRunId);
+        if (zeroTokens) {
+            return {
+                step: "qa",
+                status: "failed",
+                error: ZERO_TOKEN_ERROR,
+                chosenAgent: resolvedAgent,
+                ratingSummary,
+                gatewayPlan: gateway?.analysis?.plan ?? [],
+                gatewayFiles: [...(gateway?.analysis?.filesLikelyTouched ?? []), ...(gateway?.analysis?.filesToCreate ?? [])],
+            };
+        }
+        return {
+            ...parsed,
+            chosenAgent: resolvedAgent,
+            ratingSummary,
+            gatewayPlan: gateway?.analysis?.plan ?? [],
+            gatewayFiles: [...(gateway?.analysis?.filesLikelyTouched ?? []), ...(gateway?.analysis?.filesToCreate ?? [])],
+        };
+    }
+    toSummary(state) {
+        return Object.values(state.tasks).map((task) => ({
+            taskKey: task.taskKey,
+            attempts: task.attempts,
+            status: task.status,
+            lastStep: task.lastStep,
+            lastDecision: task.lastDecision,
+            lastOutcome: task.lastOutcome,
+            lastError: task.lastError,
+            chosenAgents: task.chosenAgents,
+            ratings: task.ratings,
+        }));
+    }
+    async run(request) {
+        const warnings = [];
+        let resumeJob;
+        if (request.resumeJobId) {
+            const job = await this.deps.jobService.getJob(request.resumeJobId);
+            if (!job)
+                throw new Error(`Job not found: ${request.resumeJobId}`);
+            const manifest = await this.readManifest(job.id);
+            this.assertResumeAllowed(job, manifest);
+            const command = (job.commandName ?? job.type ?? "").toLowerCase();
+            if (command !== "gateway-trio") {
+                throw new Error(`Job ${request.resumeJobId} is not a gateway-trio job`);
+            }
+            resumeJob = job;
+        }
+        const resolvedRequest = this.resolveRequest(request, resumeJob?.payload);
+        const maxIterations = resolvedRequest.maxIterations;
+        const continuousMode = maxIterations === undefined;
+        const maxCycles = resolvedRequest.maxCycles;
+        const maxAgentSeconds = resolvedRequest.maxAgentSeconds;
+        if (!resolvedRequest.rateAgents) {
+            warnings.push("Agent rating disabled; use --rate-agents to track rating/complexity updates.");
+        }
+        const statusFilter = await this.buildStatusFilter(resolvedRequest, warnings);
+        const explicitTaskKeys = resolvedRequest.taskKeys ? this.dedupeTaskKeys(resolvedRequest.taskKeys) : [];
+        const pseudoTaskKeys = explicitTaskKeys.filter((key) => this.isPseudoTaskKey(key));
+        const filteredTaskKeys = explicitTaskKeys.filter((key) => !this.isPseudoTaskKey(key));
+        const explicitTaskKeysProvided = explicitTaskKeys.length > 0;
+        const includeTypes = resolvedRequest.includeTypes?.length ? resolvedRequest.includeTypes : undefined;
+        let excludeTypes = resolvedRequest.excludeTypes;
+        if (!excludeTypes && !includeTypes?.length) {
+            excludeTypes = ["qa_followup"];
+        }
+        const explicitTaskFilterEmpty = explicitTaskKeysProvided && filteredTaskKeys.length === 0;
+        if (pseudoTaskKeys.length) {
+            warnings.push(`Skipping pseudo tasks: ${pseudoTaskKeys.join(", ")}.`);
+        }
+        if (explicitTaskFilterEmpty) {
+            warnings.push("All requested tasks were pseudo entries; nothing to run.");
+        }
+        const baseTaskKeys = explicitTaskKeysProvided ? filteredTaskKeys : resolvedRequest.taskKeys;
+        const shouldFixRunList = explicitTaskKeysProvided || (typeof resolvedRequest.limit === "number" && resolvedRequest.limit > 0);
+        let jobId = request.resumeJobId;
+        let state;
+        let runList;
+        if (request.resumeJobId) {
+            state = await this.loadState(request.resumeJobId);
+            if (!state)
+                throw new Error(`Missing gateway-trio state for job ${request.resumeJobId}`);
+            if (shouldFixRunList) {
+                runList = state.run_list;
+            }
+        }
+        if (shouldFixRunList && !runList) {
+            if (explicitTaskFilterEmpty) {
+                runList = [];
+            }
+            else if (explicitTaskKeysProvided) {
+                runList = this.buildRunListFromExplicit(filteredTaskKeys, resolvedRequest.limit, warnings);
+            }
+            else {
+                runList = await this.buildRunListFromSelection({
+                    projectKey: resolvedRequest.projectKey,
+                    epicKey: resolvedRequest.epicKey,
+                    storyKey: resolvedRequest.storyKey,
+                    taskKeys: baseTaskKeys,
+                    statusFilter,
+                    includeTypes,
+                    excludeTypes,
+                    limit: resolvedRequest.limit,
+                    parallel: resolvedRequest.parallel,
+                }, resolvedRequest.limit, warnings);
+            }
+        }
+        const taskKeysForRun = runList ?? baseTaskKeys;
+        const commandRun = await this.deps.jobService.startCommandRun("gateway-trio", resolvedRequest.projectKey, {
+            taskIds: taskKeysForRun,
+            jobId: request.resumeJobId,
+        });
+        if (request.resumeJobId) {
+            await this.deps.jobService.updateJobStatus(request.resumeJobId, "running", {
+                job_state_detail: "resuming",
+            });
+            if (shouldFixRunList && runList && state && !state.run_list) {
+                state.run_list = runList;
+                await this.writeState(state);
+            }
+        }
+        else {
+            const job = await this.deps.jobService.startJob("gateway-trio", commandRun.id, resolvedRequest.projectKey, {
+                commandName: "gateway-trio",
+                payload: {
+                    projectKey: resolvedRequest.projectKey,
+                    epicKey: resolvedRequest.epicKey,
+                    storyKey: resolvedRequest.storyKey,
+                    tasks: taskKeysForRun,
+                    statusFilter,
+                    maxIterations,
+                    maxCycles,
+                    limit: resolvedRequest.limit,
+                    parallel: resolvedRequest.parallel,
+                    gatewayAgentName: resolvedRequest.gatewayAgentName,
+                    workAgentName: resolvedRequest.workAgentName,
+                    reviewAgentName: resolvedRequest.reviewAgentName,
+                    qaAgentName: resolvedRequest.qaAgentName,
+                    maxDocs: resolvedRequest.maxDocs,
+                    agentStream: resolvedRequest.agentStream,
+                    noCommit: resolvedRequest.noCommit,
+                    dryRun: resolvedRequest.dryRun,
+                    reviewBase: resolvedRequest.reviewBase,
+                    maxAgentSeconds,
+                    qaProfileName: resolvedRequest.qaProfileName,
+                    qaLevel: resolvedRequest.qaLevel,
+                    qaTestCommand: resolvedRequest.qaTestCommand,
+                    qaMode: resolvedRequest.qaMode,
+                    qaFollowups: resolvedRequest.qaFollowups,
+                    reviewFollowups: resolvedRequest.reviewFollowups,
+                    qaResult: resolvedRequest.qaResult,
+                    qaNotes: resolvedRequest.qaNotes,
+                    qaEvidenceUrl: resolvedRequest.qaEvidenceUrl,
+                    qaAllowDirty: resolvedRequest.qaAllowDirty,
+                    escalateOnNoChange: resolvedRequest.escalateOnNoChange,
+                    resumeSupported: true,
+                },
+            });
+            jobId = job.id;
+            state = {
+                schema_version: 1,
+                job_id: job.id,
+                command_run_id: commandRun.id,
+                run_list: runList,
+                cycle: 0,
+                tasks: {},
+            };
+            await this.writeState(state);
+            await this.deps.jobService.updateJobStatus(jobId, "running", {
+                job_state_detail: "loading_tasks",
+            });
+        }
+        if (!jobId || !state) {
+            throw new Error("gateway-trio job initialization failed");
+        }
+        if (resolvedRequest.onJobStart) {
+            resolvedRequest.onJobStart(jobId, commandRun.id);
+        }
+        await this.runDocdexPreflight(jobId, warnings);
+        await this.cleanupExpiredTaskLocks(warnings);
+        const explicitTasks = new Set(explicitTaskKeysProvided ? (runList ?? filteredTaskKeys) : []);
+        if (pseudoTaskKeys.length) {
+            for (const key of pseudoTaskKeys) {
+                this.skipPseudoTask(state, key, warnings);
+            }
+        }
+        await this.seedExplicitTasks(state, explicitTasks, warnings);
+        await this.writeState(state);
+        let cycle = state.cycle ?? 0;
+        const taskLimit = resolvedRequest.limit;
+        let activeTaskKey = null;
+        let abortRemainingReason = null;
+        const resolveJobState = (job) => job?.jobState ?? job?.state;
+        const checkCancellation = async (label) => {
+            const job = await this.deps.jobService.getJob(jobId);
+            const stateNow = resolveJobState(job);
+            if (stateNow === "cancelled") {
+                abortRemainingReason = "cancelled";
+                warnings.push(`Job ${jobId} cancelled${label ? ` (${label})` : ""}; stopping.`);
+                return true;
+            }
+            return false;
+        };
+        try {
+            while ((maxCycles === undefined || cycle < maxCycles) && !abortRemainingReason) {
+                if (await checkCancellation("cycle_start"))
+                    break;
+                await this.reopenRetryableFailedTasks(state, explicitTasks, maxIterations, warnings);
+                await this.writeState(state);
+                const selection = explicitTaskFilterEmpty || (Array.isArray(runList) && runList.length === 0)
+                    ? {
+                        ordered: [],
+                        warnings: [],
+                        filters: { effectiveStatuses: [] },
+                    }
+                    : await this.selectionService.selectTasks({
+                        projectKey: resolvedRequest.projectKey,
+                        epicKey: resolvedRequest.epicKey,
+                        storyKey: resolvedRequest.storyKey,
+                        taskKeys: Array.isArray(runList) ? runList : taskKeysForRun,
+                        statusFilter,
+                        limit: resolvedRequest.limit,
+                        parallel: resolvedRequest.parallel,
+                    });
+                if (selection.warnings.length)
+                    warnings.push(...selection.warnings);
+                const completedKeys = new Set(Object.values(state.tasks)
+                    .filter((task) => task.status === "completed")
+                    .map((task) => task.taskKey));
+                let orderedCandidates = this.prioritizeFeedbackTasks(selection.ordered, state);
+                if (activeTaskKey) {
+                    const activeIndex = orderedCandidates.findIndex((entry) => entry.task.key === activeTaskKey);
+                    if (activeIndex >= 0) {
+                        const activeEntry = orderedCandidates[activeIndex];
+                        orderedCandidates = [
+                            activeEntry,
+                            ...orderedCandidates.slice(0, activeIndex),
+                            ...orderedCandidates.slice(activeIndex + 1),
+                        ];
+                    }
+                    else {
+                        const activeSelection = await this.selectionService.selectTasks({
+                            taskKeys: [activeTaskKey],
+                            ignoreStatusFilter: true,
+                            limit: 1,
+                            parallel: resolvedRequest.parallel,
+                        });
+                        const activeEntry = activeSelection.ordered[0];
+                        if (activeEntry) {
+                            orderedCandidates = [activeEntry, ...orderedCandidates];
+                        }
+                        else {
+                            activeTaskKey = null;
+                        }
+                    }
+                }
+                const ordered = [];
+                const seenOrdered = new Set();
+                for (const entry of orderedCandidates) {
+                    const taskKey = entry.task.key;
+                    if (seenOrdered.has(taskKey)) {
+                        warnings.push(`Task ${taskKey} appears multiple times in this cycle; skipping duplicate entry.`);
+                        continue;
+                    }
+                    seenOrdered.add(taskKey);
+                    const statusNow = this.normalizeStatus(entry.task.status);
+                    if (statusNow === "cancelled") {
+                        const progress = this.ensureProgress(state, taskKey);
+                        progress.status = "skipped";
+                        progress.lastError = "cancelled_in_db";
+                        state.tasks[taskKey] = progress;
+                        warnings.push(`Task ${taskKey} is cancelled; skipping.`);
+                        if (activeTaskKey === taskKey) {
+                            activeTaskKey = null;
+                        }
+                        continue;
+                    }
+                    if (completedKeys.has(taskKey)) {
+                        warnings.push(`Task ${taskKey} already completed earlier in this run; skipping.`);
+                        if (activeTaskKey === taskKey) {
+                            activeTaskKey = null;
+                        }
+                        continue;
+                    }
+                    if (this.isPseudoTaskKey(taskKey)) {
+                        this.skipPseudoTask(state, taskKey, warnings);
+                        if (activeTaskKey === taskKey) {
+                            activeTaskKey = null;
+                        }
+                        continue;
+                    }
+                    ordered.push(entry);
+                }
+                await this.writeState(state);
+                await this.deps.jobService.updateJobStatus(jobId, "running", {
+                    totalItems: ordered.length,
+                    processedItems: 0,
+                    job_state_detail: ordered.length === 0 ? "no_tasks" : "processing",
+                });
+                let completedThisCycle = 0;
+                let processedThisCycle = 0;
+                let attemptedThisCycle = 0;
+                const seenThisCycle = new Set();
+                for (const entry of ordered) {
+                    if (abortRemainingReason)
+                        break;
+                    if (await checkCancellation(`task:${entry.task.key}`))
+                        break;
+                    if (typeof taskLimit === "number" && taskLimit > 0 && completedKeys.size >= taskLimit) {
+                        warnings.push(`Completed task limit ${taskLimit} reached; stopping run.`);
+                        abortRemainingReason = "limit_reached";
+                        break;
+                    }
+                    if (activeTaskKey && entry.task.key !== activeTaskKey) {
+                        const activeProgress = state.tasks[activeTaskKey];
+                        if (activeProgress && activeProgress.status !== "completed") {
+                            break;
+                        }
+                        activeTaskKey = null;
+                    }
+                    let attempted = false;
+                    let holdAfterTask = false;
+                    let currentTaskKey;
+                    try {
+                        const taskKey = entry.task.key;
+                        currentTaskKey = taskKey;
+                        if (seenThisCycle.has(taskKey)) {
+                            warnings.push(`Task ${taskKey} appears multiple times in this cycle; skipping duplicate entry.`);
+                            continue;
+                        }
+                        seenThisCycle.add(taskKey);
+                        if (completedKeys.has(taskKey)) {
+                            warnings.push(`Task ${taskKey} already completed earlier in this run; skipping.`);
+                            continue;
+                        }
+                        if (typeof taskLimit === "number" && taskLimit > 0 && completedKeys.size >= taskLimit) {
+                            warnings.push(`Completed task limit ${taskLimit} reached; stopping run.`);
+                            abortRemainingReason = "limit_reached";
+                            break;
+                        }
+                        const normalizedStatus = this.normalizeStatus(entry.task.status);
+                        if (normalizedStatus && TERMINAL_STATUSES.has(normalizedStatus)) {
+                            warnings.push(`Skipping terminal task ${taskKey} (${normalizedStatus}).`);
+                            continue;
+                        }
+                        const progress = this.ensureProgress(state, taskKey);
+                        await this.persistRevertLearning(entry.task.id, taskKey, entry.task.metadata ?? undefined, progress, warnings);
+                        state.tasks[taskKey] = progress;
+                        if (progress.status === "skipped") {
+                            progress.status = "pending";
+                            progress.lastError = undefined;
+                        }
+                        if (progress.status === "completed") {
+                            continue;
+                        }
+                        if (progress.status === "failed") {
+                            if (progress.lastError === ZERO_TOKEN_ERROR && !continuousMode) {
+                                warnings.push(`Task ${taskKey} failed after repeated zero-token runs.`);
+                                continue;
+                            }
+                            const normalizedReason = normalizeFailureReason(progress.lastError ?? progress.failureHistory?.[progress.failureHistory.length - 1]?.reason ?? "");
+                            if (!continuousMode &&
+                                (progress.lastGuardrailRetryable === false ||
+                                    (normalizedReason && NON_RETRYABLE_FAILURE_REASONS.has(normalizedReason)))) {
+                                const reasonLabel = normalizedReason ?? progress.lastError ?? progress.lastEscalationReason ?? "guardrail_non_retryable";
+                                warnings.push(`Task ${taskKey} failed with non-retryable reason ${reasonLabel}; skipping.`);
+                                continue;
+                            }
+                            if (this.hasReachedMaxIterations(progress, maxIterations)) {
+                                continue;
+                            }
+                            if (!this.shouldReopenFailedTask(progress, taskKey, warnings, continuousMode)) {
+                                continue;
+                            }
+                            progress.status = "pending";
+                            progress.lastError = undefined;
+                            progress.lastGuardrailRetryable = undefined;
+                            state.tasks[taskKey] = progress;
+                        }
+                        const projectKey = await this.projectKeyForTask(entry.task.projectId);
+                        let currentStatus = this.normalizeStatus(entry.task.status);
+                        const readStatus = async () => {
+                            if (resolvedRequest.dryRun)
+                                return currentStatus;
+                            return await this.refreshTaskStatus(taskKey, warnings);
+                        };
+                        const setDryRunStatus = (next) => {
+                            if (resolvedRequest.dryRun) {
+                                currentStatus = next;
+                            }
+                        };
+                        let taskCompleted = false;
+                        while (!taskCompleted) {
+                            const statusNow = await readStatus();
+                            if (!statusNow) {
+                                progress.status = "failed";
+                                progress.lastError = "status_unknown";
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                warnings.push(`Task ${taskKey} status unknown; skipping.`);
+                                break;
+                            }
+                            if (TERMINAL_STATUSES.has(statusNow)) {
+                                progress.status = statusNow === "completed" ? "completed" : "skipped";
+                                progress.lastError = statusNow === "completed" ? "completed_in_db" : "cancelled_in_db";
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                if (statusNow === "completed") {
+                                    completedKeys.add(taskKey);
+                                    completedThisCycle += 1;
+                                }
+                                break;
+                            }
+                            if (statusNow === "blocked") {
+                                progress.status = "failed";
+                                progress.lastError = "legacy_blocked";
+                                state.tasks[taskKey] = progress;
+                                if (!resolvedRequest.dryRun) {
+                                    await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                        status: "failed",
+                                        metadata: {
+                                            ...entry.task.metadata,
+                                            failed_reason: "legacy_blocked",
+                                        },
+                                    });
+                                }
+                                await this.writeState(state);
+                                warnings.push(`Task ${taskKey} had legacy blocked status; marked failed.`);
+                                break;
+                            }
+                            if (!attempted) {
+                                attemptedThisCycle += 1;
+                                attempted = true;
+                            }
+                            if (isReadyToReviewStatus(statusNow)) {
+                                const attemptIndex = Math.max(progress.attempts, 1);
+                                const reviewAgentOptions = this.buildAgentOptions(progress, "review", resolvedRequest);
+                                progress.lastStep = "review";
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                const reviewOutcome = await this.runStepWithTimeout("review", jobId, taskKey, attemptIndex, maxAgentSeconds, (signal) => this.runReviewStep(jobId, attemptIndex, taskKey, projectKey, normalizeReviewStatuses([READY_TO_CODE_REVIEW]), resolvedRequest, warnings, reviewAgentOptions, signal, this.handoffContextForProgress(progress), async (agent) => {
+                                    progress.chosenAgents.review = agent;
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                }));
+                                progress.lastStep = "review";
+                                progress.lastDecision = reviewOutcome.decision;
+                                progress.lastError = reviewOutcome.error;
+                                progress.chosenAgents.review = reviewOutcome.chosenAgent ?? progress.chosenAgents.review;
+                                if (reviewOutcome.gatewayPlan?.length) {
+                                    progress.lastOutcome = reviewOutcome.gatewayPlan.join(" | ");
+                                }
+                                this.recordDecision(progress, "review", attemptIndex, "result", reviewOutcome.status, reviewOutcome.decision ?? reviewOutcome.error ?? reviewOutcome.outcome);
+                                if (this.isAuthFailure(reviewOutcome.error)) {
+                                    const message = reviewOutcome.error ?? AUTH_ERROR_REASON;
+                                    reviewOutcome.error = AUTH_ERROR_REASON;
+                                    progress.lastError = AUTH_ERROR_REASON;
+                                    this.recordFailure(progress, reviewOutcome, attemptIndex);
+                                    progress.status = "failed";
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                            status: "failed",
+                                            metadata: {
+                                                ...entry.task.metadata,
+                                                failed_reason: AUTH_ERROR_REASON,
+                                            },
+                                        });
+                                    }
+                                    warnings.push(`Task ${taskKey} failed due to auth/rate limit during review; continuing run. ${message}`);
+                                    break;
+                                }
+                                this.recordFailure(progress, reviewOutcome, attemptIndex);
+                                this.recordRating(progress, reviewOutcome.ratingSummary);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                await this.deps.jobService.writeCheckpoint(jobId, {
+                                    stage: `task:${taskKey}:review`,
+                                    timestamp: new Date().toISOString(),
+                                    details: { taskKey, attempt: attemptIndex, outcome: reviewOutcome },
+                                });
+                                if (reviewOutcome.error === ZERO_TOKEN_ERROR) {
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, { status: READY_TO_CODE_REVIEW });
+                                    }
+                                    const zeroTokenCount = this.countFailures(progress, "review", ZERO_TOKEN_ERROR);
+                                    if (zeroTokenCount >= 2) {
+                                        progress.status = "failed";
+                                        progress.lastError = ZERO_TOKEN_ERROR;
+                                        state.tasks[taskKey] = progress;
+                                        await this.writeState(state);
+                                        warnings.push(`Task ${taskKey} failed after repeated zero-token review runs.`);
+                                        break;
+                                    }
+                                    warnings.push(`Retrying ${taskKey} after zero-token review run.`);
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    await this.backoffZeroTokens(zeroTokenCount);
+                                    continue;
+                                }
+                                const reviewGatewayFailure = reviewOutcome.status === "failed" &&
+                                    normalizeFailureReason(reviewOutcome.error ?? reviewOutcome.decision) === GATEWAY_FAILED_REASON;
+                                if (reviewGatewayFailure) {
+                                    progress.status = "failed";
+                                    progress.lastError = GATEWAY_FAILED_REASON;
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                            status: "failed",
+                                            metadata: {
+                                                ...entry.task.metadata,
+                                                failed_reason: GATEWAY_FAILED_REASON,
+                                            },
+                                        });
+                                    }
+                                    warnings.push(`Task ${taskKey} failed due to gateway failure during review.`);
+                                    break;
+                                }
+                                const retryReview = this.shouldRetryAfter(reviewOutcome);
+                                if (retryReview) {
+                                    this.recordDecision(progress, "review", attemptIndex, "retry", "retry", reviewOutcome.decision ?? reviewOutcome.status);
+                                    warnings.push(`Retrying ${taskKey} after review (${reviewOutcome.decision ?? reviewOutcome.status}).`);
+                                    setDryRunStatus("in_progress");
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    continue;
+                                }
+                                if (reviewOutcome.status === "failed" && reviewOutcome.guardrailRetryable === false) {
+                                    const reason = normalizeFailureReason(reviewOutcome.guardrailReason ?? reviewOutcome.error ?? reviewOutcome.decision ?? "failed") ??
+                                        reviewOutcome.guardrailReason ??
+                                        reviewOutcome.error ??
+                                        reviewOutcome.decision ??
+                                        "failed";
+                                    progress.status = "failed";
+                                    progress.lastError = reason;
+                                    this.recordDecision(progress, "review", attemptIndex, "terminal", "failed", reason);
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                            status: "failed",
+                                            metadata: {
+                                                ...entry.task.metadata,
+                                                failed_reason: reason,
+                                            },
+                                        });
+                                    }
+                                    warnings.push(`Task ${taskKey} failed with non-retryable review reason ${reason}.`);
+                                    break;
+                                }
+                                if (resolvedRequest.dryRun) {
+                                    if (reviewOutcome.decision === "changes_requested") {
+                                        setDryRunStatus("changes_requested");
+                                    }
+                                    else {
+                                        setDryRunStatus(reviewOutcome.status === "succeeded" ? "ready_to_qa" : "in_progress");
+                                    }
+                                    continue;
+                                }
+                                const statusAfterReview = await this.refreshTaskStatus(taskKey, warnings);
+                                if (statusAfterReview && statusAfterReview === "completed") {
+                                    progress.status = "completed";
+                                    state.tasks[taskKey] = progress;
+                                    completedKeys.add(taskKey);
+                                    completedThisCycle += 1;
+                                    await this.writeState(state);
+                                    break;
+                                }
+                                if (statusAfterReview && statusAfterReview === "failed") {
+                                    progress.status = "failed";
+                                    progress.lastError = progress.lastError ?? "failed";
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    break;
+                                }
+                                if (statusAfterReview && statusAfterReview === "changes_requested") {
+                                    continue;
+                                }
+                                if (statusAfterReview && !["ready_to_qa"].includes(statusAfterReview)) {
+                                    warnings.push(`Task ${taskKey} status ${statusAfterReview} after review; retrying work step.`);
+                                    continue;
+                                }
+                                continue;
+                            }
+                            if (statusNow === "ready_to_qa") {
+                                const attemptIndex = Math.max(progress.attempts, 1);
+                                progress.lastStep = "qa";
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                const qaOutcome = await this.runStepWithTimeout("qa", jobId, taskKey, attemptIndex, maxAgentSeconds, (signal) => this.runQaStep(jobId, attemptIndex, taskKey, projectKey, ["ready_to_qa"], resolvedRequest, warnings, this.buildAgentOptions(progress, "qa", resolvedRequest), signal, this.handoffContextForProgress(progress), async (agent) => {
+                                    progress.chosenAgents.qa = agent;
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                }));
+                                progress.lastStep = "qa";
+                                progress.lastOutcome = qaOutcome.outcome;
+                                progress.lastError = qaOutcome.error;
+                                progress.chosenAgents.qa = qaOutcome.chosenAgent ?? progress.chosenAgents.qa;
+                                this.recordDecision(progress, "qa", attemptIndex, "result", qaOutcome.status, qaOutcome.outcome ?? qaOutcome.error ?? qaOutcome.notes);
+                                if (this.isAuthFailure(qaOutcome.error)) {
+                                    const message = qaOutcome.error ?? AUTH_ERROR_REASON;
+                                    qaOutcome.error = AUTH_ERROR_REASON;
+                                    progress.lastError = AUTH_ERROR_REASON;
+                                    this.recordFailure(progress, qaOutcome, attemptIndex);
+                                    progress.status = "failed";
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                            status: "failed",
+                                            metadata: {
+                                                ...entry.task.metadata,
+                                                failed_reason: AUTH_ERROR_REASON,
+                                            },
+                                        });
+                                    }
+                                    warnings.push(`Task ${taskKey} failed due to auth/rate limit during QA; continuing run. ${message}`);
+                                    break;
+                                }
+                                this.recordFailure(progress, qaOutcome, attemptIndex);
+                                this.recordRating(progress, qaOutcome.ratingSummary);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                await this.deps.jobService.writeCheckpoint(jobId, {
+                                    stage: `task:${taskKey}:qa`,
+                                    timestamp: new Date().toISOString(),
+                                    details: { taskKey, attempt: attemptIndex, outcome: qaOutcome },
+                                });
+                                if (qaOutcome.error === ZERO_TOKEN_ERROR) {
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, { status: "ready_to_qa" });
+                                    }
+                                    const zeroTokenCount = this.countFailures(progress, "qa", ZERO_TOKEN_ERROR);
+                                    if (zeroTokenCount >= 2) {
+                                        progress.status = "failed";
+                                        progress.lastError = ZERO_TOKEN_ERROR;
+                                        state.tasks[taskKey] = progress;
+                                        await this.writeState(state);
+                                        warnings.push(`Task ${taskKey} failed after repeated zero-token QA runs.`);
+                                        break;
+                                    }
+                                    warnings.push(`Retrying ${taskKey} after zero-token QA run.`);
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    await this.backoffZeroTokens(zeroTokenCount);
+                                    continue;
+                                }
+                                const qaGatewayFailure = qaOutcome.status === "failed" &&
+                                    normalizeFailureReason(qaOutcome.error ?? qaOutcome.outcome) === GATEWAY_FAILED_REASON;
+                                if (qaGatewayFailure) {
+                                    progress.status = "failed";
+                                    progress.lastError = GATEWAY_FAILED_REASON;
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                            status: "failed",
+                                            metadata: {
+                                                ...entry.task.metadata,
+                                                failed_reason: GATEWAY_FAILED_REASON,
+                                            },
+                                        });
+                                    }
+                                    warnings.push(`Task ${taskKey} failed due to gateway failure during QA.`);
+                                    break;
+                                }
+                                const retryQa = this.shouldRetryAfter(qaOutcome);
+                                if (retryQa) {
+                                    progress.lastQaFailureSummary = this.buildQaFailureSummary(taskKey, qaOutcome);
+                                    this.recordDecision(progress, "qa", attemptIndex, "retry", "retry", qaOutcome.outcome ?? qaOutcome.status);
+                                    warnings.push(`Retrying ${taskKey} after QA (${qaOutcome.outcome ?? qaOutcome.status}).`);
+                                    warnings.push(`Task ${taskKey} queued for gateway re-analysis after QA failure.`);
+                                    setDryRunStatus("in_progress");
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    continue;
+                                }
+                                if (qaOutcome.status === "failed" && qaOutcome.guardrailRetryable === false) {
+                                    const reason = normalizeFailureReason(qaOutcome.guardrailReason ?? qaOutcome.error ?? qaOutcome.outcome ?? "failed") ??
+                                        qaOutcome.guardrailReason ??
+                                        qaOutcome.error ??
+                                        qaOutcome.outcome ??
+                                        "failed";
+                                    progress.status = "failed";
+                                    progress.lastError = reason;
+                                    progress.lastQaFailureSummary = this.buildQaFailureSummary(taskKey, qaOutcome);
+                                    this.recordDecision(progress, "qa", attemptIndex, "terminal", "failed", reason);
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                            status: "failed",
+                                            metadata: {
+                                                ...entry.task.metadata,
+                                                failed_reason: reason,
+                                            },
+                                        });
+                                    }
+                                    warnings.push(`Task ${taskKey} failed with non-retryable QA reason ${reason}.`);
+                                    break;
+                                }
+                                if (resolvedRequest.dryRun) {
+                                    setDryRunStatus(qaOutcome.status === "succeeded" ? "completed" : "in_progress");
+                                }
+                                else {
+                                    const statusAfterQa = await this.refreshTaskStatus(taskKey, warnings);
+                                    if (statusAfterQa && statusAfterQa === "failed") {
+                                        progress.status = "failed";
+                                        progress.lastError = progress.lastError ?? "failed";
+                                        state.tasks[taskKey] = progress;
+                                        await this.writeState(state);
+                                        break;
+                                    }
+                                    if (statusAfterQa && statusAfterQa !== "completed") {
+                                        warnings.push(`Task ${taskKey} status ${statusAfterQa} after QA; retrying work step.`);
+                                        continue;
+                                    }
+                                }
+                                progress.status = "completed";
+                                progress.lastQaFailureSummary = undefined;
+                                const touchedFiles = this.mergeGatewayFiles(qaOutcome).length > 0
+                                    ? this.mergeGatewayFiles(qaOutcome)
+                                    : Array.isArray(entry.task.metadata?.last_review_changed_paths)
+                                        ? (entry.task.metadata.last_review_changed_paths || [])
+                                            .filter((item) => typeof item === "string" && item.trim().length > 0)
+                                            .map((item) => item.trim())
+                                        : [];
+                                const planSummary = (qaOutcome.gatewayPlan ?? []).join(" | ") ||
+                                    progress.stepOutcomes?.work ||
+                                    "Work-review-QA loop completed";
+                                try {
+                                    await this.appendGoldenExample({
+                                        taskKey,
+                                        title: entry.task.title,
+                                        planSummary,
+                                        touchedFiles,
+                                        reviewNotes: progress.lastDecision,
+                                        qaNotes: qaOutcome.notes ?? qaOutcome.outcome ?? qaOutcome.status,
+                                    });
+                                }
+                                catch (error) {
+                                    warnings.push(`Golden example capture failed for ${taskKey}: ${error instanceof Error ? error.message : String(error)}`);
+                                }
+                                state.tasks[taskKey] = progress;
+                                completedKeys.add(taskKey);
+                                await this.writeState(state);
+                                completedThisCycle += 1;
+                                taskCompleted = true;
+                                continue;
+                            }
+                            if (this.hasReachedMaxIterations(progress, maxIterations)) {
+                                progress.status = "failed";
+                                progress.lastError = "max_iterations_reached";
+                                state.tasks[taskKey] = progress;
+                                if (maxIterations !== undefined) {
+                                    warnings.push(`Task ${taskKey} hit max iterations (${maxIterations}).`);
+                                }
+                                await this.writeState(state);
+                                break;
+                            }
+                            const attemptIndex = progress.attempts + 1;
+                            progress.attempts = attemptIndex;
+                            progress.lastError = undefined;
+                            progress.lastGuardrailRetryable = undefined;
+                            state.tasks[taskKey] = progress;
+                            await this.writeState(state);
+                            const workAgentOptions = this.buildAgentOptions(progress, "work", resolvedRequest);
+                            progress.lastStep = "work";
+                            state.tasks[taskKey] = progress;
+                            await this.writeState(state);
+                            const workOutcome = await this.runStepWithTimeout("work", jobId, taskKey, attemptIndex, maxAgentSeconds, (signal) => this.runWorkStep(jobId, attemptIndex, taskKey, projectKey, ["not_started", "in_progress", "changes_requested"], resolvedRequest, warnings, workAgentOptions, signal, this.handoffContextForProgress(progress), async (agent) => {
+                                progress.chosenAgents.work = agent;
+                                if (!progress.lastWorkAgentTier) {
+                                    progress.lastWorkAgentTier = "unknown";
+                                }
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                            }));
+                            progress.lastStep = "work";
+                            progress.lastError = workOutcome.error;
+                            progress.chosenAgents.work = workOutcome.chosenAgent ?? progress.chosenAgents.work;
+                            if (workOutcome.tier) {
+                                progress.lastWorkAgentTier = workOutcome.tier;
+                            }
+                            else if (!progress.lastWorkAgentTier) {
+                                progress.lastWorkAgentTier = "unknown";
+                            }
+                            this.recordDecision(progress, "work", attemptIndex, "result", workOutcome.status, workOutcome.error ?? workOutcome.outcome ?? workOutcome.decision);
+                            if (this.isAuthFailure(workOutcome.error)) {
+                                const message = workOutcome.error ?? AUTH_ERROR_REASON;
+                                workOutcome.error = AUTH_ERROR_REASON;
+                                progress.lastError = AUTH_ERROR_REASON;
+                                this.recordFailure(progress, workOutcome, attemptIndex);
+                                progress.status = "failed";
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                if (!resolvedRequest.dryRun) {
+                                    await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                        status: "failed",
+                                        metadata: {
+                                            ...entry.task.metadata,
+                                            failed_reason: AUTH_ERROR_REASON,
+                                        },
+                                    });
+                                }
+                                warnings.push(`Task ${taskKey} failed due to auth/rate limit during work; continuing run. ${message}`);
+                                break;
+                            }
+                            this.recordFailure(progress, workOutcome, attemptIndex);
+                            this.recordRating(progress, workOutcome.ratingSummary);
+                            state.tasks[taskKey] = progress;
+                            await this.writeState(state);
+                            await this.deps.jobService.writeCheckpoint(jobId, {
+                                stage: `task:${taskKey}:work`,
+                                timestamp: new Date().toISOString(),
+                                details: { taskKey, attempt: attemptIndex, outcome: workOutcome },
+                            });
+                            if (workOutcome.error === ZERO_TOKEN_ERROR) {
+                                if (!resolvedRequest.dryRun) {
+                                    await this.deps.workspaceRepo.updateTask(entry.task.id, { status: "in_progress" });
+                                }
+                                const zeroTokenCount = this.countFailures(progress, "work", ZERO_TOKEN_ERROR);
+                                if (zeroTokenCount >= 2) {
+                                    progress.status = "failed";
+                                    progress.lastError = ZERO_TOKEN_ERROR;
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    warnings.push(`Task ${taskKey} failed after repeated zero-token work runs.`);
+                                    break;
+                                }
+                                warnings.push(`Retrying ${taskKey} after zero-token work run.`);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                await this.backoffZeroTokens(zeroTokenCount);
+                                continue;
+                            }
+                            if (workOutcome.error === "tests_failed") {
+                                const testsFailedCount = this.countFailures(progress, "work", "tests_failed");
+                                if (testsFailedCount >= 2) {
+                                    progress.status = "failed";
+                                    progress.lastError = "tests_failed";
+                                    state.tasks[taskKey] = progress;
+                                    await this.writeState(state);
+                                    if (!resolvedRequest.dryRun) {
+                                        await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                            status: "failed",
+                                            metadata: {
+                                                ...entry.task.metadata,
+                                                failed_reason: "tests_failed",
+                                            },
+                                        });
+                                    }
+                                    warnings.push(`Task ${taskKey} failed after repeated tests_failed.`);
+                                    break;
+                                }
+                                warnings.push(`Retrying ${taskKey} after tests_failed with stronger agent.`);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                continue;
+                            }
+                            const workGatewayFailure = workOutcome.status === "failed" &&
+                                normalizeFailureReason(workOutcome.error ?? workOutcome.status) === GATEWAY_FAILED_REASON;
+                            if (workGatewayFailure) {
+                                progress.status = "failed";
+                                progress.lastError = GATEWAY_FAILED_REASON;
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                if (!resolvedRequest.dryRun) {
+                                    await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                        status: "failed",
+                                        metadata: {
+                                            ...entry.task.metadata,
+                                            failed_reason: GATEWAY_FAILED_REASON,
+                                        },
+                                    });
+                                }
+                                warnings.push(`Task ${taskKey} failed due to gateway failure during work.`);
+                                break;
+                            }
+                            if (workOutcome.status === "skipped") {
+                                progress.status = "skipped";
+                                progress.lastError = workOutcome.error ?? "skipped";
+                                this.recordDecision(progress, "work", attemptIndex, "terminal", "skipped", progress.lastError);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                break;
+                            }
+                            const retryWork = this.shouldRetryAfter(workOutcome);
+                            if (workOutcome.status !== "succeeded" && retryWork) {
+                                this.recordDecision(progress, "work", attemptIndex, "retry", "retry", workOutcome.error ?? workOutcome.status);
+                                warnings.push(`Retrying ${taskKey} after work step (${workOutcome.status}).`);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                continue;
+                            }
+                            if (workOutcome.status === "failed" && workOutcome.guardrailRetryable === false) {
+                                const reason = normalizeFailureReason(workOutcome.guardrailReason ?? workOutcome.error ?? workOutcome.status) ??
+                                    workOutcome.guardrailReason ??
+                                    workOutcome.error ??
+                                    "failed";
+                                progress.status = "failed";
+                                progress.lastError = reason;
+                                this.recordDecision(progress, "work", attemptIndex, "terminal", "failed", reason);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                if (!resolvedRequest.dryRun) {
+                                    await this.deps.workspaceRepo.updateTask(entry.task.id, {
+                                        status: "failed",
+                                        metadata: {
+                                            ...entry.task.metadata,
+                                            failed_reason: reason,
+                                        },
+                                    });
+                                }
+                                warnings.push(`Task ${taskKey} failed with non-retryable work reason ${reason}.`);
+                                break;
+                            }
+                            if (resolvedRequest.dryRun) {
+                                setDryRunStatus(READY_TO_CODE_REVIEW);
+                                continue;
+                            }
+                            const statusAfterWork = await this.refreshTaskStatus(taskKey, warnings);
+                            if (statusAfterWork &&
+                                (isReadyToReviewStatus(statusAfterWork) || ["ready_to_qa", "completed"].includes(statusAfterWork))) {
+                                currentStatus = statusAfterWork;
+                                continue;
+                            }
+                            if (statusAfterWork && statusAfterWork === "failed") {
+                                progress.status = "failed";
+                                progress.lastError = "failed";
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                break;
+                            }
+                            if (statusAfterWork && statusAfterWork === "blocked") {
+                                progress.status = "failed";
+                                progress.lastError = "legacy_blocked";
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                warnings.push(`Task ${taskKey} had legacy blocked status after work; marked failed.`);
+                                break;
+                            }
+                            if (statusAfterWork) {
+                                warnings.push(`Task ${taskKey} status ${statusAfterWork} after work; retrying work step.`);
+                                progress.lastError = "work_status_not_ready";
+                                const statusFailure = {
+                                    step: "work",
+                                    status: "failed",
+                                    error: "work_status_not_ready",
+                                    chosenAgent: progress.chosenAgents.work,
+                                };
+                                this.recordFailure(progress, statusFailure, attemptIndex);
+                                state.tasks[taskKey] = progress;
+                                await this.writeState(state);
+                                continue;
+                            }
+                            warnings.push(`Task ${taskKey} status missing after work; retrying work step.`);
+                            continue;
+                        }
+                        if (attempted && !abortRemainingReason) {
+                            const finalProgress = currentTaskKey ? state.tasks[currentTaskKey] : undefined;
+                            if (finalProgress) {
+                                if (finalProgress.status === "completed") {
+                                    activeTaskKey = null;
+                                }
+                                else {
+                                    activeTaskKey = currentTaskKey ?? activeTaskKey;
+                                    holdAfterTask = true;
+                                }
+                            }
+                            if (typeof taskLimit === "number" && taskLimit > 0 && completedKeys.size >= taskLimit) {
+                                warnings.push(`Completed task limit ${taskLimit} reached; stopping run.`);
+                                abortRemainingReason = "limit_reached";
+                            }
+                        }
+                    }
+                    finally {
+                        if (attempted) {
+                            processedThisCycle += 1;
+                            await this.deps.jobService.updateJobStatus(jobId, "running", {
+                                processedItems: processedThisCycle,
+                            });
+                        }
+                    }
+                    if (abortRemainingReason || holdAfterTask)
+                        break;
+                }
+                if (abortRemainingReason)
+                    break;
+                cycle += 1;
+                state.cycle = cycle;
+                await this.writeState(state);
+                if (attemptedThisCycle === 0) {
+                    const hasRemaining = Object.values(state.tasks).some((task) => {
+                        if (task.status === "completed" || task.status === "skipped")
+                            return false;
+                        if (maxIterations !== undefined && task.attempts >= maxIterations)
+                            return false;
+                        return true;
+                    });
+                    if (hasRemaining) {
+                        warnings.push("No tasks attempted in this cycle; tasks remain, continuing.");
+                        await new Promise((resolve) => setTimeout(resolve, 1000));
+                        continue;
+                    }
+                    warnings.push("No tasks attempted in this cycle; stopping.");
+                    break;
+                }
+            }
+            const summaries = this.toSummary(state);
+            const failed = summaries.filter((t) => t.status === "failed").map((t) => t.taskKey);
+            const skipped = summaries.filter((t) => t.status === "skipped").map((t) => t.taskKey);
+            const pending = summaries.filter((t) => t.status === "pending").map((t) => t.taskKey);
+            const failureCount = failed.length + skipped.length + pending.length;
+            const jobSnapshot = await this.deps.jobService.getJob(jobId);
+            const jobStateNow = resolveJobState(jobSnapshot);
+            const cancelled = jobStateNow === "cancelled" || abortRemainingReason === "cancelled";
+            const endState = cancelled ? "cancelled" : failureCount === 0 ? "completed" : "partial";
+            const errorSummary = cancelled ? "Job cancelled by user" : failureCount ? `${failureCount} task(s) not fully completed` : undefined;
+            await this.deps.jobService.updateJobStatus(jobId, endState, { errorSummary });
+            const commandStatus = endState === "completed" ? "succeeded" : endState === "cancelled" ? "cancelled" : "failed";
+            await this.deps.jobService.finishCommandRun(commandRun.id, commandStatus, errorSummary);
+            await this.deps.jobService.writeCheckpoint(jobId, {
+                stage: "completed",
+                timestamp: new Date().toISOString(),
+                details: { cycle, tasks: summaries },
+            });
+            return {
+                jobId,
+                commandRunId: commandRun.id,
+                tasks: summaries,
+                warnings,
+                failed,
+                skipped,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await this.deps.jobService.updateJobStatus(jobId, "failed", { errorSummary: message });
+            await this.deps.jobService.finishCommandRun(commandRun.id, "failed", message);
+            throw error;
+        }
+    }
+}