@mcoda/core 0.1.9 → 0.1.12

package/dist/services/execution/GatewayTrioService.js

@@ -1,30 +1,96 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { WorkspaceRepository } from "@mcoda/db";
-import { PathHelper } from "@mcoda/shared";
+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", "ready_to_review", "ready_to_qa"];
+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 BLOCKED_STATUSES = new Set(["blocked"]);
-const RETRYABLE_BLOCK_REASONS = new Set([
+const GATEWAY_FAILED_REASON = "gateway_failed";
+const ESCALATION_REASONS = new Set([
     "missing_patch",
     "patch_failed",
-    "tests_not_configured",
     "tests_failed",
-    "no_changes",
-    "qa_infra_issue",
-    "review_blocked",
+    "agent_timeout",
+    "review_invalid_output",
+    "work_status_not_ready",
 ]);
-const ESCALATION_REASONS = new Set(["missing_patch", "patch_failed", "tests_failed", "agent_timeout"]);
 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;
@@ -37,6 +103,7 @@ export class GatewayTrioService {
         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 });
@@ -45,6 +112,7 @@ export class GatewayTrioService {
             workspaceRepo,
             jobService,
             gatewayService,
+            routingService,
             workService,
             reviewService,
             qaService,
@@ -63,14 +131,76 @@ export class GatewayTrioService {
         };
         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.workspaceRoot, ".mcoda", "jobs", jobId, "gateway-trio");
+        return path.join(this.workspace.mcodaDir, "jobs", jobId, "gateway-trio");
     }
     statePath(jobId) {
         return path.join(this.trioDir(jobId), "state.json");
@@ -89,7 +219,7 @@ export class GatewayTrioService {
         }
     }
     async readManifest(jobId) {
-        const manifestPath = path.join(this.workspace.workspaceRoot, ".mcoda", "jobs", jobId, "manifest.json");
+        const manifestPath = path.join(this.workspace.mcodaDir, "jobs", jobId, "manifest.json");
         try {
             const raw = await fs.readFile(manifestPath, "utf8");
             return JSON.parse(raw);
@@ -98,6 +228,78 @@ export class GatewayTrioService {
             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) {
@@ -178,6 +380,12 @@ export class GatewayTrioService {
                 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 = {
@@ -186,10 +394,81 @@ export class GatewayTrioService {
             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;
@@ -201,43 +480,102 @@ export class GatewayTrioService {
             return true;
         return progress.attempts < maxIterations;
     }
-    async reopenRetryableBlockedTasks(state, explicitTasks, maxIterations, warnings) {
+    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;
-            if (this.hasReachedMaxIterations(progress, maxIterations))
-                continue;
             const task = await this.deps.workspaceRepo.getTaskByKey(taskKey);
             if (!task)
                 continue;
             const status = this.normalizeStatus(task.status);
-            const metadata = task.metadata ?? {};
-            const blockedReason = typeof metadata.blocked_reason === "string" ? metadata.blocked_reason : undefined;
-            if (status === "blocked") {
-                if (!blockedReason)
-                    continue;
-                const testsFailedCount = this.countFailures(progress, "work", "tests_failed");
-                if (blockedReason === "tests_failed" && testsFailedCount >= 2) {
-                    warnings.push(`Task ${taskKey} remains blocked after repeated tests_failed; skipping reopen.`);
-                    continue;
+            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.`);
                 }
-                if (blockedReason === "dependency_not_ready") {
+                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;
                 }
-                else if (!RETRYABLE_BLOCK_REASONS.has(blockedReason)) {
+                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.blocked_reason;
-            if (status === "blocked") {
+            delete nextMetadata.failed_reason;
+            if (status === "failed") {
                 await this.deps.workspaceRepo.updateTask(task.id, {
                     status: "in_progress",
                     metadata: nextMetadata,
@@ -248,9 +586,7 @@ export class GatewayTrioService {
                 progress.lastError = undefined;
                 state.tasks[taskKey] = progress;
             }
-            warnings.push(status === "blocked"
-                ? `Reopened blocked task ${taskKey} (reason=${blockedReason}) for retry.`
-                : `Reopened failed task ${taskKey} for retry (attempts=${progress?.attempts ?? 0}${maxIterations !== undefined ? `/${maxIterations}` : ""}).`);
+            warnings.push(`Reopened failed task ${taskKey} (reason=${failedReason ?? progress?.lastError ?? "unknown"}) for retry (attempts=${progress?.attempts ?? 0}${maxIterations !== undefined ? `/${maxIterations}` : ""}).`);
         }
     }
     async dependenciesReady(taskId, warnings) {
@@ -278,11 +614,14 @@ export class GatewayTrioService {
         return status ? status.toLowerCase().trim() : undefined;
     }
     resolveRequest(request, payload) {
-        if (!payload)
-            return request;
+        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,
@@ -300,6 +639,7 @@ export class GatewayTrioService {
             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,
@@ -309,11 +649,15 @@ export class GatewayTrioService {
             qaTestCommand: request.qaTestCommand ?? raw.qaTestCommand,
             qaMode: request.qaMode ?? raw.qaMode,
             qaFollowups: request.qaFollowups ?? raw.qaFollowups,
-            qaResult: request.qaResult ?? raw.qaResult,
+            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) {
@@ -351,16 +695,26 @@ export class GatewayTrioService {
         if (!entry) {
             return { step: "work", status: "failed", error: "Task not processed by work-on-tasks" };
         }
+        const guardrail = parseGuardrailReason(entry.notes);
         if (entry.status === "succeeded") {
-            if (entry.notes === "no_changes")
-                return { step: "work", status: "failed", error: "no_changes" };
             return { step: "work", status: "succeeded" };
         }
-        if (entry.status === "blocked")
-            return { step: "work", status: "blocked", error: entry.notes };
-        if (entry.status === "skipped")
-            return { step: "work", status: "skipped", error: entry.notes };
-        return { step: "work", status: "failed", error: entry.notes };
+        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);
@@ -368,13 +722,22 @@ export class GatewayTrioService {
             return { step: "review", status: "failed", error: "Task not processed by code-review" };
         }
         if (entry.error) {
-            return { step: "review", status: "failed", error: 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: "blocked", decision };
+            return { step: "review", status: "failed", decision };
         return { step: "review", status: "failed", decision };
     }
     parseQaResult(taskKey, result) {
@@ -382,17 +745,56 @@ export class GatewayTrioService {
         if (!entry) {
             return { step: "qa", status: "failed", error: "Task not processed by qa-tasks" };
         }
-        if (entry.outcome === "pass")
-            return { step: "qa", status: "succeeded", outcome: entry.outcome };
-        if (entry.outcome === "infra_issue")
-            return { step: "qa", status: "blocked", outcome: entry.outcome };
+        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 };
+            return {
+                step: "qa",
+                status: "failed",
+                outcome: entry.outcome,
+                notes: entry.notes,
+                artifacts: entry.artifacts,
+            };
         }
-        return { step: "qa", status: "failed", outcome: entry.outcome };
+        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 === "blocked" || step.status === "skipped")
+        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";
     }
@@ -402,17 +804,196 @@ export class GatewayTrioService {
             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" && step.status !== "blocked")
+        if (step.status !== "failed")
             return;
-        const reason = step.error ?? step.decision ?? step.outcome;
+        const reason = step.guardrailReason ?? step.error ?? step.decision ?? step.outcome;
         const agent = step.chosenAgent;
-        if (!reason || !agent)
+        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;
@@ -445,17 +1026,16 @@ export class GatewayTrioService {
     }
     buildAgentOptions(progress, step, request) {
         const reasons = this.escalationReasons(request.escalateOnNoChange !== false);
-        const avoid = new Set();
-        const history = progress.failureHistory ?? [];
-        for (const failure of history) {
+        const history = (progress.failureHistory ?? []).filter((failure) => {
             if (failure.step !== step)
-                continue;
-            if (!reasons.has(failure.reason))
-                continue;
-            avoid.add(failure.agent);
-        }
-        const avoidAgents = Array.from(avoid);
-        return { avoidAgents, forceStronger: avoidAgents.length > 0 };
+                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)
@@ -469,7 +1049,7 @@ export class GatewayTrioService {
         if (!jobId)
             return undefined;
         try {
-            const payload = await fs.readFile(path.join(this.workspace.workspaceRoot, ".mcoda", "jobs", jobId, "rating.json"), "utf8");
+            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;
@@ -481,7 +1061,27 @@ export class GatewayTrioService {
             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(),
@@ -491,6 +1091,7 @@ export class GatewayTrioService {
         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(),
@@ -523,7 +1124,16 @@ export class GatewayTrioService {
         }
     }
     async runGateway(job, taskKey, projectKey, request, agentOptions) {
-        return this.deps.gatewayService.run({
+        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,
@@ -531,33 +1141,123 @@ export class GatewayTrioService {
             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, onResolvedAgent) {
+    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);
-            handoff = buildGatewayHandoffContent(gateway);
-            resolvedAgent = request.workAgentName ?? gateway.chosenAgent.agentSlug;
+            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 = [
+            handoff = this.appendFallbackHandoffContext([
                 "# Gateway Handoff",
                 "",
                 `Gateway agent failed; proceeding with override agent ${resolvedAgent}.`,
                 `Error: ${message}`,
                 "",
                 buildGatewayHandoffDocdexUsage(),
-            ].join("\n");
+            ], handoffContext).join("\n");
             warnings.push(`Gateway agent failed for work ${taskKey}; using override ${resolvedAgent}: ${message}`);
         }
         if (!resolvedAgent) {
@@ -566,6 +1266,7 @@ export class GatewayTrioService {
         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,
@@ -577,6 +1278,9 @@ export class GatewayTrioService {
             dryRun: request.dryRun,
             agentName: resolvedAgent,
             agentStream: request.agentStream,
+            workRunner: request.workRunner,
+            useCodali: request.useCodali,
+            agentAdapterOverride: request.agentAdapterOverride,
             rateAgents: request.rateAgents,
             abortSignal,
             maxAgentSeconds: request.maxAgentSeconds,
@@ -585,30 +1289,55 @@ export class GatewayTrioService {
         const ratingSummary = request.rateAgents
             ? await this.loadRatingSummary(result.jobId, "work", resolvedAgent)
             : undefined;
-        return { ...parsed, chosenAgent: resolvedAgent, ratingSummary };
+        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, onResolvedAgent) {
+    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);
-            handoff = buildGatewayHandoffContent(gateway);
-            resolvedAgent = request.reviewAgentName ?? gateway.chosenAgent.agentSlug;
+            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 = [
+            handoff = this.appendFallbackHandoffContext([
                 "# Gateway Handoff",
                 "",
-                `Gateway agent failed; proceeding with override agent ${resolvedAgent}.`,
+                `Routing failed; proceeding with override agent ${resolvedAgent}.`,
                 `Error: ${message}`,
                 "",
                 buildGatewayHandoffDocdexUsage(),
-            ].join("\n");
+            ], handoffContext).join("\n");
             warnings.push(`Gateway agent failed for review ${taskKey}; using override ${resolvedAgent}: ${message}`);
         }
         if (!resolvedAgent) {
@@ -628,36 +1357,60 @@ export class GatewayTrioService {
             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;
-        return { ...parsed, chosenAgent: resolvedAgent, ratingSummary };
+        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, onResolvedAgent) {
+    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);
-            handoff = buildGatewayHandoffContent(gateway);
-            resolvedAgent = request.qaAgentName ?? gateway.chosenAgent.agentSlug;
+            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 = [
+            handoff = this.appendFallbackHandoffContext([
                 "# Gateway Handoff",
                 "",
-                `Gateway agent failed; proceeding with override agent ${resolvedAgent}.`,
+                `Routing failed; proceeding with override agent ${resolvedAgent}.`,
                 `Error: ${message}`,
                 "",
                 buildGatewayHandoffDocdexUsage(),
-            ].join("\n");
+            ], handoffContext).join("\n");
             warnings.push(`Gateway agent failed for QA ${taskKey}; using override ${resolvedAgent}: ${message}`);
         }
         if (!resolvedAgent) {
@@ -691,7 +1444,25 @@ export class GatewayTrioService {
         const ratingSummary = request.rateAgents
             ? await this.loadRatingSummary(result.jobId, "qa", resolvedAgent)
             : undefined;
-        return { ...parsed, chosenAgent: resolvedAgent, ratingSummary };
+        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) => ({
@@ -723,25 +1494,76 @@ export class GatewayTrioService {
         }
         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 commandRun = await this.deps.jobService.startCommandRun("gateway-trio", resolvedRequest.projectKey, {
-            taskIds: resolvedRequest.taskKeys,
-            jobId: request.resumeJobId,
-        });
+        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, {
@@ -750,7 +1572,7 @@ export class GatewayTrioService {
                     projectKey: resolvedRequest.projectKey,
                     epicKey: resolvedRequest.epicKey,
                     storyKey: resolvedRequest.storyKey,
-                    tasks: resolvedRequest.taskKeys,
+                    tasks: taskKeysForRun,
                     statusFilter,
                     maxIterations,
                     maxCycles,
@@ -771,6 +1593,7 @@ export class GatewayTrioService {
                     qaTestCommand: resolvedRequest.qaTestCommand,
                     qaMode: resolvedRequest.qaMode,
                     qaFollowups: resolvedRequest.qaFollowups,
+                    reviewFollowups: resolvedRequest.reviewFollowups,
                     qaResult: resolvedRequest.qaResult,
                     qaNotes: resolvedRequest.qaNotes,
                     qaEvidenceUrl: resolvedRequest.qaEvidenceUrl,
@@ -778,18 +1601,20 @@ export class GatewayTrioService {
                     escalateOnNoChange: resolvedRequest.escalateOnNoChange,
                     resumeSupported: true,
                 },
-                totalItems: 0,
-                processedItems: 0,
             });
             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");
@@ -797,309 +1622,852 @@ export class GatewayTrioService {
         if (resolvedRequest.onJobStart) {
             resolvedRequest.onJobStart(jobId, commandRun.id);
         }
+        await this.runDocdexPreflight(jobId, warnings);
         await this.cleanupExpiredTaskLocks(warnings);
-        const explicitTasks = new Set(resolvedRequest.taskKeys ?? []);
+        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) {
-                await this.reopenRetryableBlockedTasks(state, explicitTasks, maxIterations, warnings);
+            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 = await this.selectionService.selectTasks({
-                    projectKey: resolvedRequest.projectKey,
-                    epicKey: resolvedRequest.epicKey,
-                    storyKey: resolvedRequest.storyKey,
-                    taskKeys: resolvedRequest.taskKeys,
-                    statusFilter,
-                    limit: resolvedRequest.limit,
-                    parallel: resolvedRequest.parallel,
-                });
-                const blockedKeys = new Set(selection.blocked.map((t) => t.task.key));
+                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 ordered = this.prioritizeFeedbackTasks(selection.ordered, state);
-                for (const blocked of selection.blocked) {
-                    const taskKey = blocked.task.key;
-                    if (explicitTasks.has(taskKey))
+                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;
-                    const progress = this.ensureProgress(state, taskKey);
-                    progress.status = "skipped";
-                    progress.lastError = "dependency_blocked";
-                    state.tasks[taskKey] = progress;
+                    }
+                    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) {
-                    const taskKey = entry.task.key;
-                    if (blockedKeys.has(taskKey) && !explicitTasks.has(taskKey)) {
-                        warnings.push(`Task ${taskKey} blocked by dependencies; skipping this cycle.`);
-                        const progress = this.ensureProgress(state, taskKey);
-                        progress.status = "skipped";
-                        progress.lastError = "dependency_blocked";
-                        state.tasks[taskKey] = progress;
-                        await this.writeState(state);
-                        continue;
+                    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;
                     }
-                    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);
-                    if (progress.status === "skipped") {
-                        progress.status = "pending";
-                        progress.lastError = undefined;
-                    }
-                    if (progress.status === "completed" || progress.status === "blocked") {
-                        continue;
+                    if (activeTaskKey && entry.task.key !== activeTaskKey) {
+                        const activeProgress = state.tasks[activeTaskKey];
+                        if (activeProgress && activeProgress.status !== "completed") {
+                            break;
+                        }
+                        activeTaskKey = null;
                     }
-                    if (progress.status === "failed") {
-                        if (this.hasReachedMaxIterations(progress, maxIterations)) {
+                    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;
                         }
-                        progress.status = "pending";
-                        progress.lastError = undefined;
-                        state.tasks[taskKey] = progress;
-                    }
-                    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}).`);
+                        seenThisCycle.add(taskKey);
+                        if (completedKeys.has(taskKey)) {
+                            warnings.push(`Task ${taskKey} already completed earlier in this run; skipping.`);
+                            continue;
                         }
-                        continue;
-                    }
-                    const attemptIndex = progress.attempts + 1;
-                    attemptedThisCycle += 1;
-                    const projectKey = await this.projectKeyForTask(entry.task.projectId);
-                    const statusBefore = this.normalizeStatus(entry.task.status);
-                    const workWasSkipped = statusBefore === "ready_to_review" || statusBefore === "ready_to_qa";
-                    const reviewWasSkipped = statusBefore === "ready_to_qa";
-                    progress.attempts = attemptIndex;
-                    progress.lastError = undefined;
-                    state.tasks[taskKey] = progress;
-                    await this.writeState(state);
-                    if (!workWasSkipped) {
-                        const workAgentOptions = this.buildAgentOptions(progress, "work", resolvedRequest);
-                        progress.lastStep = "work";
+                        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;
-                        await this.writeState(state);
-                        const workOutcome = await this.runStepWithTimeout("work", jobId, taskKey, attemptIndex, maxAgentSeconds, (signal) => this.runWorkStep(jobId, attemptIndex, taskKey, projectKey, statusFilter, resolvedRequest, warnings, workAgentOptions, signal, async (agent) => {
-                            progress.chosenAgents.work = agent;
+                        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;
-                            await this.writeState(state);
-                        }));
-                        progress.lastStep = "work";
-                        progress.lastError = workOutcome.error;
-                        progress.chosenAgents.work = workOutcome.chosenAgent ?? progress.chosenAgents.work;
-                        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 === "tests_failed") {
-                            const testsFailedCount = this.countFailures(progress, "work", "tests_failed");
-                            if (testsFailedCount >= 2) {
-                                progress.status = "blocked";
-                                progress.lastError = "tests_failed";
+                        }
+                        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);
-                                warnings.push(`Task ${taskKey} blocked after repeated tests_failed.`);
+                                completedThisCycle += 1;
+                                taskCompleted = true;
                                 continue;
                             }
-                            warnings.push(`Retrying ${taskKey} after tests_failed with stronger agent.`);
+                            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);
-                            continue;
-                        }
-                        if (workOutcome.status === "blocked") {
-                            progress.status = "blocked";
-                            progress.lastError = workOutcome.error ?? "blocked";
+                            const workAgentOptions = this.buildAgentOptions(progress, "work", resolvedRequest);
+                            progress.lastStep = "work";
                             state.tasks[taskKey] = progress;
                             await this.writeState(state);
-                            continue;
-                        }
-                        if (workOutcome.status === "skipped") {
-                            progress.status = "skipped";
-                            progress.lastError = workOutcome.error ?? "skipped";
+                            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);
-                            continue;
-                        }
-                        if (workOutcome.status !== "succeeded") {
-                            if (this.shouldRetryAfter(workOutcome)) {
+                            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 (!resolvedRequest.dryRun) {
+                            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 && statusAfterWork !== "ready_to_review") {
+                            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;
                             }
-                        }
-                    }
-                    else {
-                        progress.lastStep = "work";
-                        progress.lastError = undefined;
-                        state.tasks[taskKey] = progress;
-                        await this.writeState(state);
-                        await this.deps.jobService.writeCheckpoint(jobId, {
-                            stage: `task:${taskKey}:work:skipped`,
-                            timestamp: new Date().toISOString(),
-                            details: { taskKey, attempt: attemptIndex, reason: statusBefore ?? "ready" },
-                        });
-                    }
-                    if (!reviewWasSkipped) {
-                        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, ["ready_to_review", ...statusFilter], resolvedRequest, warnings, reviewAgentOptions, signal, 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;
-                        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.status === "blocked") {
-                            progress.status = "blocked";
-                            progress.lastError = reviewOutcome.error ?? "blocked";
-                            state.tasks[taskKey] = progress;
-                            await this.writeState(state);
-                            continue;
-                        }
-                        if (this.shouldRetryAfter(reviewOutcome)) {
-                            warnings.push(`Retrying ${taskKey} after review (${reviewOutcome.decision ?? reviewOutcome.status}).`);
-                            state.tasks[taskKey] = progress;
-                            await this.writeState(state);
+                            warnings.push(`Task ${taskKey} status missing after work; retrying work step.`);
                             continue;
                         }
-                        if (!resolvedRequest.dryRun) {
-                            const statusAfterReview = await this.refreshTaskStatus(taskKey, warnings);
-                            if (statusAfterReview && statusAfterReview !== "ready_to_qa") {
-                                warnings.push(`Task ${taskKey} status ${statusAfterReview} after review; 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";
                             }
                         }
                     }
-                    else {
-                        progress.lastStep = "review";
-                        progress.lastDecision = "skipped";
-                        progress.lastError = undefined;
-                        state.tasks[taskKey] = progress;
-                        await this.writeState(state);
-                        await this.deps.jobService.writeCheckpoint(jobId, {
-                            stage: `task:${taskKey}:review:skipped`,
-                            timestamp: new Date().toISOString(),
-                            details: { taskKey, attempt: attemptIndex, reason: statusBefore ?? "ready_to_qa" },
-                        });
-                    }
-                    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", ...statusFilter], resolvedRequest, warnings, this.buildAgentOptions(progress, "qa", resolvedRequest), signal, 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.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.status === "blocked") {
-                        progress.status = "blocked";
-                        progress.lastError = qaOutcome.error ?? "blocked";
-                        state.tasks[taskKey] = progress;
-                        await this.writeState(state);
-                        continue;
-                    }
-                    if (this.shouldRetryAfter(qaOutcome)) {
-                        warnings.push(`Retrying ${taskKey} after QA (${qaOutcome.outcome ?? qaOutcome.status}).`);
-                        state.tasks[taskKey] = progress;
-                        await this.writeState(state);
-                        continue;
-                    }
-                    if (!resolvedRequest.dryRun) {
-                        const statusAfterQa = await this.refreshTaskStatus(taskKey, warnings);
-                        if (statusAfterQa && statusAfterQa !== "completed") {
-                            warnings.push(`Task ${taskKey} status ${statusAfterQa} after QA; retrying work step.`);
-                            state.tasks[taskKey] = progress;
-                            await this.writeState(state);
-                            continue;
+                    finally {
+                        if (attempted) {
+                            processedThisCycle += 1;
+                            await this.deps.jobService.updateJobStatus(jobId, "running", {
+                                processedItems: processedThisCycle,
+                            });
                         }
                     }
-                    progress.status = "completed";
-                    state.tasks[taskKey] = progress;
-                    await this.writeState(state);
-                    completedThisCycle += 1;
-                    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 hasPending = Object.values(state.tasks).some((task) => task.status === "pending" && this.hasIterationsRemaining(task, maxIterations));
-                    if (hasPending) {
-                        if (maxCycles === undefined) {
-                            warnings.push("No tasks attempted in this cycle; pending tasks remain, stopping to avoid infinite loop without max-cycles.");
-                            break;
-                        }
-                        warnings.push("No tasks attempted in this cycle; pending tasks remain, continuing.");
+                    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 to avoid infinite loop.");
+                    warnings.push("No tasks attempted in this cycle; stopping.");
                     break;
                 }
             }
             const summaries = this.toSummary(state);
-            const blocked = summaries.filter((t) => t.status === "blocked").map((t) => t.taskKey);
             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 + blocked.length + skipped.length + pending.length;
-            const endState = failureCount === 0 ? "completed" : "partial";
-            const errorSummary = failureCount ? `${failureCount} task(s) not fully completed` : undefined;
+            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 });
-            await this.deps.jobService.finishCommandRun(commandRun.id, endState === "completed" ? "succeeded" : "failed", 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(),
@@ -1110,7 +2478,6 @@ export class GatewayTrioService {
                 commandRunId: commandRun.id,
                 tasks: summaries,
                 warnings,
-                blocked,
                 failed,
                 skipped,
             };