@mcoda/core 0.1.9 → 0.1.12

package/dist/services/review/CodeReviewService.js

@@ -1,9 +1,10 @@
 import path from "node:path";
 import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { AgentService } from "@mcoda/agents";
 import { DocdexClient, VcsClient } from "@mcoda/integrations";
 import { GlobalRepository, WorkspaceRepository, } from "@mcoda/db";
-import { PathHelper } from "@mcoda/shared";
+import { PathHelper, READY_TO_CODE_REVIEW, REVIEW_ALLOWED_STATUSES, filterTaskStatuses, normalizeReviewStatuses, } from "@mcoda/shared";
 import { JobService } from "../jobs/JobService.js";
 import { TaskSelectionService } from "../execution/TaskSelectionService.js";
 import { TaskStateService } from "../execution/TaskStateService.js";
@@ -12,11 +13,14 @@ import yaml from "yaml";
 import { createTaskKeyGenerator } from "../planning/KeyHelpers.js";
 import { RoutingService } from "../agents/RoutingService.js";
 import { AgentRatingService } from "../agents/AgentRatingService.js";
-import { loadProjectGuidance } from "../shared/ProjectGuidance.js";
+import { isDocContextExcluded, loadProjectGuidance, normalizeDocType } from "../shared/ProjectGuidance.js";
+import { buildDocdexUsageGuidance } from "../shared/DocdexGuidance.js";
 import { createTaskCommentSlug, formatTaskCommentBody } from "../tasks/TaskCommentFormatter.js";
+import { AUTH_ERROR_REASON, isAuthErrorMessage } from "../shared/AuthErrors.js";
+import { normalizeReviewOutput } from "./ReviewNormalizer.js";
 const DEFAULT_BASE_BRANCH = "mcoda-dev";
-const REVIEW_DIR = (workspaceRoot, jobId) => path.join(workspaceRoot, ".mcoda", "jobs", jobId, "review");
-const STATE_PATH = (workspaceRoot, jobId) => path.join(REVIEW_DIR(workspaceRoot, jobId), "state.json");
+const REVIEW_DIR = (mcodaDir, jobId) => path.join(mcodaDir, "jobs", jobId, "review");
+const STATE_PATH = (mcodaDir, jobId) => path.join(REVIEW_DIR(mcodaDir, jobId), "state.json");
 const REVIEW_PROMPT_LIMITS = {
     diff: 12000,
     history: 3000,
@@ -26,63 +30,70 @@ const REVIEW_PROMPT_LIMITS = {
 };
 const DOCDEX_TIMEOUT_MS = 8000;
 const DEFAULT_CODE_REVIEW_PROMPT = [
-    "You are the code-review agent. Before reviewing, query docdex with the task key and feature keywords (MCP `docdex_search` limit 4–8 or CLI `docdexd query --repo <repo> --query \"<term>\" --limit 6 --snippets=false`). If results look stale, reindex (`docdex_index` or `docdexd index --repo <repo>`) then re-run. Fetch snippets via `docdex_open` or `/snippet/:doc_id?text_only=true` only for specific hits.",
+    "You are the code-review agent.",
+    buildDocdexUsageGuidance({ contextLabel: "the review", includeHeading: false, includeFallback: true }),
     "Use docdex snippets to verify contracts (data shapes, offline scope, accessibility/perf guardrails, acceptance criteria). Call out mismatches, missing tests, and undocumented changes.",
+    "When recommending tests, prefer the repo's existing runner (tests/all.js or package manager scripts). Avoid suggesting new Jest configs unless the repo explicitly documents them.",
+    "Do not require docs/qa/<task>.md reports unless the task explicitly asks for one. QA artifacts typically live in mcoda workspace outputs.",
+    "Do not hardcode ports; if a port matters, call out that it must be discovered or configured dynamically.",
 ].join("\n");
+const REPO_PROMPTS_DIR = fileURLToPath(new URL("../../../../../prompts/", import.meta.url));
+const resolveRepoPromptPath = (filename) => path.join(REPO_PROMPTS_DIR, filename);
 const DEFAULT_JOB_PROMPT = "You are an mcoda agent that follows workspace runbooks and responds with actionable, concise output.";
 const DEFAULT_CHARACTER_PROMPT = "Write clearly, avoid hallucinations, cite assumptions, and prioritize risk mitigation for the user.";
-const estimateTokens = (text) => Math.max(1, Math.ceil((text ?? "").length / 4));
-const extractJsonSlice = (candidate) => {
-    const start = candidate.indexOf("{");
-    const end = candidate.lastIndexOf("}");
-    if (start === -1 || end === -1 || end <= start)
+const GATEWAY_PROMPT_MARKERS = [
+    "you are the gateway agent",
+    "return json only",
+    "output json only",
+    "docdexnotes",
+    "fileslikelytouched",
+    "filestocreate",
+    "do not include fields outside the schema",
+];
+const sanitizeNonGatewayPrompt = (value) => {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const lower = trimmed.toLowerCase();
+    if (GATEWAY_PROMPT_MARKERS.some((marker) => lower.includes(marker)))
         return undefined;
-    return candidate.slice(start, end + 1);
+    return trimmed;
 };
-const sanitizeJsonCandidate = (value) => {
-    const cleanedLines = value
-        .split(/\r?\n/)
-        .filter((line) => {
-        const trimmed = line.trim();
-        if (!trimmed)
-            return true;
-        if (trimmed.startsWith("{") ||
-            trimmed.startsWith("}") ||
-            trimmed.startsWith("[") ||
-            trimmed.startsWith("]") ||
-            trimmed.startsWith("\"")) {
-            return true;
-        }
-        return false;
-    })
-        .join("\n");
-    return cleanedLines.replace(/,\s*([}\]])/g, "$1");
+const readPromptFile = async (promptPath, fallback) => {
+    try {
+        const content = await fs.readFile(promptPath, "utf8");
+        const trimmed = content.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    catch {
+        // fall through to fallback
+    }
+    return fallback;
 };
-const parseJsonOutput = (raw) => {
-    const trimmed = raw.trim();
-    const fenced = trimmed.replace(/^```(?:json)?/i, "").replace(/```$/, "").trim();
-    const candidates = [trimmed, fenced];
-    for (const candidate of candidates) {
-        const slice = extractJsonSlice(candidate);
-        if (!slice)
+const filterOpenApiContext = (entries, hasOpenApiSnippet) => {
+    let openApiIncluded = false;
+    const filtered = [];
+    for (const entry of entries) {
+        const isOpenApi = /\[linked:openapi\]|\[openapi\]/i.test(entry);
+        if (!isOpenApi) {
+            filtered.push(entry);
             continue;
-        try {
-            const parsed = JSON.parse(slice);
-            return { ...parsed, raw: raw };
         }
-        catch {
-            const sanitized = sanitizeJsonCandidate(slice);
-            try {
-                const parsed = JSON.parse(sanitized);
-                return { ...parsed, raw: raw };
-            }
-            catch {
-                /* ignore */
-            }
+        if (hasOpenApiSnippet) {
+            continue;
         }
+        if (openApiIncluded) {
+            continue;
+        }
+        openApiIncluded = true;
+        filtered.push(entry);
     }
-    return undefined;
+    return filtered;
 };
+const estimateTokens = (text) => Math.max(1, Math.ceil((text ?? "").length / 4));
 const summarizeComments = (comments) => {
     if (!comments.length)
         return "No prior comments.";
@@ -102,6 +113,17 @@ const truncateSection = (label, text, limit) => {
     const remaining = text.length - limit;
     return `${trimmed}\n...[truncated ${remaining} chars from ${label}]`;
 };
+const isNonBlockingFinding = (finding) => {
+    const severity = (finding.severity ?? "").toLowerCase();
+    if (["info", "low"].includes(severity))
+        return true;
+    return false;
+};
+const isNonBlockingOnly = (findings = []) => {
+    if (!findings.length)
+        return false;
+    return findings.every((finding) => isNonBlockingFinding(finding));
+};
 const withTimeout = async (promise, ms, label) => {
     let timeoutId;
     const timeoutPromise = new Promise((_, reject) => {
@@ -134,6 +156,12 @@ const JSON_CONTRACT = `{
   "resolvedSlugs": ["Optional list of comment slugs that are confirmed fixed"],
   "unresolvedSlugs": ["Optional list of comment slugs still open or reintroduced"]
 }`;
+const JSON_RETRY_RULES = [
+    "Return ONLY valid JSON. No markdown, no prose, no code fences.",
+    "The response must start with '{' and end with '}'.",
+    "Match the schema exactly; use empty arrays when no items apply.",
+].join("\n");
+const isRetryableAgentError = (message) => /unexpected eof|econnreset|etimedout|socket hang up|fetch failed|connection closed/i.test(message.toLowerCase());
 const normalizeSingleLine = (value, fallback) => {
     const trimmed = (value ?? "").replace(/\s+/g, " ").trim();
     return trimmed || fallback;
@@ -155,6 +183,56 @@ const normalizePath = (value) => value
     .replace(/\\/g, "/")
     .replace(/^\.\//, "")
     .replace(/^\/+/, "");
+const normalizeLineNumber = (value) => {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.max(1, Math.round(value));
+    }
+    if (typeof value === "string") {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed))
+            return Math.max(1, parsed);
+    }
+    return undefined;
+};
+const summaryIndicatesNoChanges = (summary) => {
+    const normalized = (summary ?? "").toLowerCase();
+    if (!normalized)
+        return false;
+    const patterns = [
+        "no changes required",
+        "no changes needed",
+        "no change required",
+        "no change needed",
+        "no code changes",
+        "already complete",
+        "already completed",
+        "already satisfied",
+    ];
+    return patterns.some((pattern) => normalized.includes(pattern));
+};
+const validateReviewOutput = (result, options = {}) => {
+    if (!result.decision || !["approve", "changes_requested", "block", "info_only"].includes(result.decision)) {
+        return "Review decision is required.";
+    }
+    if (!result.summary || !result.summary.trim()) {
+        return "Review summary is required.";
+    }
+    if (options.requireCommentSlugs && result.resolvedSlugs === undefined && result.unresolvedSlugs === undefined) {
+        return "resolvedSlugs/unresolvedSlugs required when comment backlog exists.";
+    }
+    for (const finding of result.findings ?? []) {
+        const message = (finding.message ?? "").trim();
+        const file = typeof finding.file === "string" ? finding.file.trim() : "";
+        const line = normalizeLineNumber(finding.line);
+        if (!message || !file || !line) {
+            return "Each review finding must include file, line, and message.";
+        }
+        finding.file = normalizePath(file);
+        finding.line = line;
+        finding.message = message;
+    }
+    return undefined;
+};
 const parseCommentBody = (body) => {
     const trimmed = (body ?? "").trim();
     if (!trimmed)
@@ -189,8 +267,15 @@ const buildCommentBacklog = (comments) => {
     const lines = [];
     const toSingleLine = (value) => value.replace(/\s+/g, " ").trim();
     for (const comment of comments) {
-        const slug = comment.slug?.trim() || undefined;
         const details = parseCommentBody(comment.body);
+        const slug = comment.slug?.trim() ||
+            createTaskCommentSlug({
+                source: comment.sourceCommand ?? "comment",
+                message: details.message || comment.body,
+                file: comment.file,
+                line: comment.line,
+                category: comment.category ?? null,
+            });
         const key = slug ??
             `${comment.sourceCommand}:${comment.file ?? ""}:${comment.line ?? ""}:${details.message || comment.body}`;
         if (seen.has(key))
@@ -256,9 +341,11 @@ export class CodeReviewService {
         const repo = await GlobalRepository.create();
         const agentService = new AgentService(repo);
         const routingService = await RoutingService.create();
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
         const docdex = new DocdexClient({
             workspaceRoot: workspace.workspaceRoot,
             baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+            repoId: docdexRepoId,
         });
         const workspaceRepo = await WorkspaceRepository.create(workspace.workspaceRoot);
         const jobService = new JobService(workspace, workspaceRepo);
@@ -296,6 +383,14 @@ export class CodeReviewService {
         await maybeClose(this.deps.routingService);
         await maybeClose(this.deps.docdex);
     }
+    setDocdexAvailability(available, reason) {
+        if (available)
+            return;
+        const docdex = this.deps.docdex;
+        if (docdex && typeof docdex.disable === "function") {
+            docdex.disable(reason);
+        }
+    }
     async readPromptFiles(paths) {
         const contents = [];
         const seen = new Set();
@@ -316,21 +411,11 @@ export class CodeReviewService {
     }
     async ensureMcoda() {
         await PathHelper.ensureDir(this.workspace.mcodaDir);
-        const gitignorePath = path.join(this.workspace.workspaceRoot, ".gitignore");
-        const entry = ".mcoda/\n";
-        try {
-            const content = await fs.readFile(gitignorePath, "utf8");
-            if (!content.includes(".mcoda/")) {
-                await fs.writeFile(gitignorePath, `${content.trimEnd()}\n${entry}`, "utf8");
-            }
-        }
-        catch {
-            await fs.writeFile(gitignorePath, entry, "utf8");
-        }
     }
     async loadPrompts(agentId) {
-        const mcodaPromptPath = path.join(this.workspace.workspaceRoot, ".mcoda", "prompts", "code-reviewer.md");
+        const mcodaPromptPath = path.join(this.workspace.mcodaDir, "prompts", "code-reviewer.md");
         const workspacePromptPath = path.join(this.workspace.workspaceRoot, "prompts", "code-reviewer.md");
+        const repoPromptPath = resolveRepoPromptPath("code-reviewer.md");
         try {
             await fs.mkdir(path.dirname(mcodaPromptPath), { recursive: true });
             await fs.access(mcodaPromptPath);
@@ -343,30 +428,29 @@ export class CodeReviewService {
                 console.info(`[code-review] copied code-reviewer prompt to ${mcodaPromptPath}`);
             }
             catch {
-                console.info(`[code-review] no code-reviewer prompt found at ${workspacePromptPath}; writing default prompt to ${mcodaPromptPath}`);
-                await fs.writeFile(mcodaPromptPath, DEFAULT_CODE_REVIEW_PROMPT, 'utf8');
+                try {
+                    await fs.access(repoPromptPath);
+                    await fs.copyFile(repoPromptPath, mcodaPromptPath);
+                    console.info(`[code-review] copied repo code-reviewer prompt to ${mcodaPromptPath}`);
+                }
+                catch {
+                    console.info(`[code-review] no code-reviewer prompt found at ${workspacePromptPath} or repo prompts; writing default prompt to ${mcodaPromptPath}`);
+                    await fs.writeFile(mcodaPromptPath, DEFAULT_CODE_REVIEW_PROMPT, "utf8");
+                }
             }
         }
-        const filePrompts = await this.readPromptFiles([mcodaPromptPath, workspacePromptPath]);
         const agentPrompts = "getPrompts" in this.deps.agentService ? await this.deps.agentService.getPrompts(agentId) : undefined;
-        const mergedCommandPrompt = (() => {
-            const parts = [...filePrompts];
-            if (agentPrompts?.commandPrompts?.["code-review"]) {
-                parts.push(agentPrompts.commandPrompts["code-review"]);
-            }
-            if (!parts.length)
-                parts.push(DEFAULT_CODE_REVIEW_PROMPT);
-            return parts.filter(Boolean).join("\n\n");
-        })();
+        const filePrompt = await readPromptFile(mcodaPromptPath, DEFAULT_CODE_REVIEW_PROMPT);
+        const commandPrompt = agentPrompts?.commandPrompts?.["code-review"]?.trim() || filePrompt;
         return {
-            jobPrompt: agentPrompts?.jobPrompt ?? DEFAULT_JOB_PROMPT,
-            characterPrompt: agentPrompts?.characterPrompt ?? DEFAULT_CHARACTER_PROMPT,
-            commandPrompt: mergedCommandPrompt || undefined,
+            jobPrompt: sanitizeNonGatewayPrompt(agentPrompts?.jobPrompt) ?? DEFAULT_JOB_PROMPT,
+            characterPrompt: sanitizeNonGatewayPrompt(agentPrompts?.characterPrompt) ?? DEFAULT_CHARACTER_PROMPT,
+            commandPrompt: commandPrompt || undefined,
         };
     }
     async loadRunbookAndChecklists() {
         const extras = [];
-        const runbookPath = path.join(this.workspace.workspaceRoot, ".mcoda", "prompts", "commands", "code-review.md");
+        const runbookPath = path.join(this.workspace.mcodaDir, "prompts", "commands", "code-review.md");
         try {
             const content = await fs.readFile(runbookPath, "utf8");
             extras.push(content);
@@ -374,7 +458,7 @@ export class CodeReviewService {
         catch {
             /* optional */
         }
-        const checklistDir = path.join(this.workspace.workspaceRoot, ".mcoda", "checklists");
+        const checklistDir = path.join(this.workspace.mcodaDir, "checklists");
         try {
             const entries = await fs.readdir(checklistDir);
             for (const entry of entries) {
@@ -395,7 +479,13 @@ export class CodeReviewService {
             commandName: "code-review",
             overrideAgentSlug: agentName,
         });
-        return resolved.agent;
+        if (agentName) {
+            const matches = agentName === resolved.agent.id || agentName === resolved.agent.slug;
+            if (!matches) {
+                throw new Error(`Review agent override "${agentName}" resolved to "${resolved.agent.slug}" (source: ${resolved.source}).`);
+            }
+        }
+        return resolved;
     }
     ensureRatingService() {
         if (!this.ratingService) {
@@ -425,7 +515,7 @@ export class CodeReviewService {
                 projectKey: filters.projectKey,
                 epicKey: filters.epicKey,
                 storyKey: filters.storyKey,
-                statuses: filters.statusFilter,
+                statuses: filters.statusFilter && filters.statusFilter.length ? filters.statusFilter : undefined,
                 verbose: true,
             });
             let tasks = result.summary.tasks;
@@ -447,13 +537,13 @@ export class CodeReviewService {
         }
     }
     async persistState(jobId, state) {
-        const dir = REVIEW_DIR(this.workspace.workspaceRoot, jobId);
+        const dir = REVIEW_DIR(this.workspace.mcodaDir, jobId);
         await fs.mkdir(dir, { recursive: true });
-        await fs.writeFile(STATE_PATH(this.workspace.workspaceRoot, jobId), JSON.stringify({ schema_version: 1, job_id: jobId, updated_at: new Date().toISOString(), ...state }, null, 2), "utf8");
+        await fs.writeFile(STATE_PATH(this.workspace.mcodaDir, jobId), JSON.stringify({ schema_version: 1, job_id: jobId, updated_at: new Date().toISOString(), ...state }, null, 2), "utf8");
     }
     async loadState(jobId) {
         try {
-            const raw = await fs.readFile(STATE_PATH(this.workspace.workspaceRoot, jobId), "utf8");
+            const raw = await fs.readFile(STATE_PATH(this.workspace.mcodaDir, jobId), "utf8");
             return JSON.parse(raw);
         }
         catch {
@@ -480,21 +570,44 @@ export class CodeReviewService {
         }
         return Array.from(hints).slice(0, 8);
     }
-    async gatherDocContext(taskTitle, paths, acceptance) {
+    async gatherDocContext(taskTitle, paths, acceptance, docLinks = []) {
         const snippets = [];
         const warnings = [];
+        if (typeof this.deps.docdex?.ensureRepoScope === "function") {
+            try {
+                await this.deps.docdex.ensureRepoScope();
+            }
+            catch (error) {
+                warnings.push(`docdex scope missing: ${error.message}`);
+                return { snippets, warnings };
+            }
+        }
         const queries = [...new Set([...(paths.length ? this.componentHintsFromPaths(paths) : []), taskTitle, ...(acceptance ?? [])])].slice(0, 8);
         let reindexed = false;
+        const resolveDocType = (doc, pathOverride) => {
+            const content = doc.segments?.[0]?.content ?? doc.content ?? "";
+            const normalized = normalizeDocType({
+                docType: doc.docType,
+                path: doc.path ?? pathOverride,
+                title: doc.title,
+                content,
+            });
+            if (normalized.downgraded) {
+                warnings.push(`Docdex docType downgraded from SDS to DOC for ${doc.path ?? doc.title ?? doc.docType ?? "unknown"}: ${normalized.reason ?? "not_sds"}`);
+            }
+            return normalized.docType;
+        };
         for (const query of queries) {
             try {
                 const docs = await withTimeout(this.deps.docdex.search({
                     query,
                     profile: "workspace-code",
                 }), DOCDEX_TIMEOUT_MS, `docdex search for "${query}"`);
-                snippets.push(...docs.slice(0, 2).map((doc) => {
+                const filteredDocs = docs.filter((doc) => !isDocContextExcluded(doc.path ?? doc.title ?? doc.id, false));
+                snippets.push(...filteredDocs.slice(0, 2).map((doc) => {
                     const content = (doc.segments?.[0]?.content ?? doc.content ?? "").slice(0, 400);
                     const ref = doc.path ?? doc.id ?? doc.title ?? query;
-                    return `- [${doc.docType ?? "doc"}] ${ref}: ${content}`;
+                    return `- [${resolveDocType(doc)}] ${ref}: ${content}`;
                 }));
             }
             catch (error) {
@@ -506,10 +619,11 @@ export class CodeReviewService {
                             query,
                             profile: "workspace-code",
                         }), DOCDEX_TIMEOUT_MS, `docdex search for "${query}" after reindex`);
-                        snippets.push(...docs.slice(0, 2).map((doc) => {
+                        const filteredDocs = docs.filter((doc) => !isDocContextExcluded(doc.path ?? doc.title ?? doc.id, false));
+                        snippets.push(...filteredDocs.slice(0, 2).map((doc) => {
                             const content = (doc.segments?.[0]?.content ?? doc.content ?? "").slice(0, 400);
                             const ref = doc.path ?? doc.id ?? doc.title ?? query;
-                            return `- [${doc.docType ?? "doc"}] ${ref}: ${content}`;
+                            return `- [${resolveDocType(doc)}] ${ref}: ${content}`;
                         }));
                         continue;
                     }
@@ -521,6 +635,44 @@ export class CodeReviewService {
                 warnings.push(`docdex search failed for ${query}: ${error.message}`);
             }
         }
+        const normalizeDocLink = (value) => {
+            const trimmed = value.trim();
+            const stripped = trimmed.replace(/^docdex:/i, "").replace(/^doc:/i, "");
+            const candidate = stripped || trimmed;
+            const looksLikePath = candidate.includes("/") ||
+                candidate.includes("\\") ||
+                /\.(md|markdown|txt|rst|yaml|yml|json)$/i.test(candidate);
+            return { type: looksLikePath ? "path" : "id", ref: candidate };
+        };
+        for (const link of docLinks) {
+            try {
+                const { type, ref } = normalizeDocLink(link);
+                if (type === "path" && isDocContextExcluded(ref, false)) {
+                    snippets.push(`- [linked:filtered] ${link} — excluded from non-QA context`);
+                    continue;
+                }
+                let doc = undefined;
+                if (type === "path" && "findDocumentByPath" in this.deps.docdex) {
+                    doc = await this.deps.docdex.findDocumentByPath(ref);
+                }
+                if (!doc) {
+                    doc = await this.deps.docdex.fetchDocumentById(ref);
+                }
+                if (!doc) {
+                    warnings.push(`docdex fetch returned no document for ${link}`);
+                    snippets.push(`- [linked:missing] ${link} — no docdex entry found`);
+                    continue;
+                }
+                const content = (doc.segments?.[0]?.content ?? doc.content ?? "").slice(0, 400);
+                const refLabel = doc.path ?? doc.id ?? doc.title ?? link;
+                snippets.push(`- [linked:${resolveDocType(doc, type === "path" ? ref : undefined)}] ${refLabel}: ${content}`);
+            }
+            catch (error) {
+                const message = error.message;
+                warnings.push(`docdex fetch failed for ${link}: ${message}`);
+                snippets.push(`- [linked:missing] ${link} — ${message}`);
+            }
+        }
         return { snippets: Array.from(new Set(snippets)), warnings };
     }
     buildReviewPrompt(params) {
@@ -533,13 +685,24 @@ export class CodeReviewService {
         const commentBacklog = params.commentBacklog
             ? truncateSection("comment backlog", params.commentBacklog, REVIEW_PROMPT_LIMITS.history)
             : "";
-        const docContextText = params.docContext.length ? truncateSection("doc context", params.docContext.join("\n"), REVIEW_PROMPT_LIMITS.docContext) : "";
+        const filteredDocContext = filterOpenApiContext(params.docContext, Boolean(params.openapiSnippet));
+        const docContextText = filteredDocContext.length
+            ? truncateSection("doc context", filteredDocContext.join("\n"), REVIEW_PROMPT_LIMITS.docContext)
+            : "";
         const openapiSnippet = params.openapiSnippet ? truncateSection("openapi", params.openapiSnippet, REVIEW_PROMPT_LIMITS.openapi) : undefined;
         const checklistsText = params.checklists?.length
             ? truncateSection("checklists", params.checklists.join("\n\n"), REVIEW_PROMPT_LIMITS.checklist)
             : "";
         const diffText = truncateSection("diff", params.diff || "(no diff)", REVIEW_PROMPT_LIMITS.diff);
+        const reviewFocus = [
+            "Review focus:",
+            "- First validate the task requirements and the work-on-tasks actions (history/comments) rather than the diff.",
+            "- If the diff is empty, decide whether no code changes are required to satisfy the task.",
+            "- If no changes are required, use decision=approve or info_only and explicitly say no code changes are needed.",
+            "- If changes are required, use decision=changes_requested and explain exactly what is missing and why.",
+        ].join("\n");
         parts.push([
+            reviewFocus,
             `Task ${params.task.key}: ${params.task.title}`,
             `Epic: ${params.task.epicKey ?? ""} ${params.task.epicTitle ?? ""}`.trim(),
             `Epic description: ${params.task.epicDescription ? params.task.epicDescription : "none"}`,
@@ -548,22 +711,24 @@ export class CodeReviewService {
             `Status: ${params.task.status}, Branch: ${params.branch ?? params.task.vcsBranch ?? "n/a"} (base ${params.baseRef})`,
             `Task description: ${params.task.description ? params.task.description : "none"}`,
             `History:\n${historySummary}`,
-            commentBacklog ? `Comment backlog (unresolved slugs):\n${commentBacklog}` : "Comment backlog: none",
-            `Acceptance criteria: ${acceptance}`,
+            commentBacklog
+                ? `Code-review comment backlog (unresolved slugs):\n${commentBacklog}`
+                : "Code-review comment backlog: none",
+            `Task DoD / acceptance criteria: ${acceptance}`,
             docContextText ? `Doc context (docdex excerpts):\n${docContextText}` : "Doc context: none",
             openapiSnippet
                 ? `OpenAPI (authoritative contract; do not invent endpoints outside this):\n${openapiSnippet}`
                 : "OpenAPI: not provided; avoid inventing endpoints.",
             checklistsText ? `Review checklists/runbook:\n${checklistsText}` : "Checklists: none",
-            "Diff:\n" + diffText,
+            params.diffEmpty ? "Diff: (empty — no changes between base and branch)" : "Diff:\n" + diffText,
             "Respond with STRICT JSON only, matching:\n" + JSON_CONTRACT,
-            "Rules: honor OpenAPI contracts; cite doc context where relevant; include resolvedSlugs/unresolvedSlugs for comment backlog items; do not add prose outside JSON.",
+            "Rules: honor OpenAPI contracts; cite doc context where relevant; include resolvedSlugs/unresolvedSlugs for code-review comment backlog items only; do not require docs/qa/* reports; avoid hardcoded ports; do not add prose or markdown fences outside JSON.",
         ].join("\n"));
         return parts.join("\n\n");
     }
     async buildHistorySummary(taskId) {
         const comments = await this.deps.workspaceRepo.listTaskComments(taskId, {
-            sourceCommands: ["work-on-tasks", "code-review", "qa-tasks"],
+            sourceCommands: ["work-on-tasks", "code-review"],
             limit: 10,
         });
         const lastReview = await this.deps.workspaceRepo.getLatestTaskReview(taskId);
@@ -585,12 +750,12 @@ export class CodeReviewService {
             }
         }
         if (!parts.length)
-            return "No prior review or QA history.";
+            return "No prior review history.";
         return parts.join("\n");
     }
     async loadCommentContext(taskId) {
         const comments = await this.deps.workspaceRepo.listTaskComments(taskId, {
-            sourceCommands: ["code-review", "qa-tasks"],
+            sourceCommands: ["code-review"],
             limit: 50,
         });
         const unresolved = comments.filter((comment) => !comment.resolvedAt);
@@ -649,9 +814,10 @@ export class CodeReviewService {
             }
         }
         const reviewSlugIndex = this.buildCommentSlugIndex(params.existingComments.filter((comment) => comment.sourceCommand === "code-review"));
-        const resolvedSlugs = normalizeSlugList(params.resolvedSlugs ?? undefined);
+        const allowedSlugs = new Set(existingBySlug.keys());
+        const resolvedSlugs = normalizeSlugList(params.resolvedSlugs ?? undefined).filter((slug) => allowedSlugs.has(slug));
         const resolvedSet = new Set(resolvedSlugs);
-        const unresolvedSet = new Set(normalizeSlugList(params.unresolvedSlugs ?? undefined));
+        const unresolvedSet = new Set(normalizeSlugList(params.unresolvedSlugs ?? undefined).filter((slug) => allowedSlugs.has(slug)));
         const findingSlugs = [];
         for (const finding of params.findings ?? []) {
             const slug = this.resolveFindingSlug(finding, reviewSlugIndex);
@@ -881,12 +1047,12 @@ export class CodeReviewService {
         });
     }
     async persistContext(jobId, taskId, context) {
-        const dir = path.join(REVIEW_DIR(this.workspace.workspaceRoot, jobId), "context");
+        const dir = path.join(REVIEW_DIR(this.workspace.mcodaDir, jobId), "context");
         await fs.mkdir(dir, { recursive: true });
         await fs.writeFile(path.join(dir, `${taskId}.json`), JSON.stringify({ schema_version: 1, task_id: taskId, created_at: new Date().toISOString(), ...context }, null, 2), "utf8");
     }
     async persistDiff(jobId, taskId, diff) {
-        const dir = path.join(REVIEW_DIR(this.workspace.workspaceRoot, jobId), "diffs");
+        const dir = path.join(REVIEW_DIR(this.workspace.mcodaDir, jobId), "diffs");
         await fs.mkdir(dir, { recursive: true });
         await fs.writeFile(path.join(dir, `${taskId}.diff`), diff, "utf8");
         // structured review diff snapshot
@@ -919,6 +1085,13 @@ export class CodeReviewService {
             files.push(current);
         await fs.writeFile(path.join(dir, `${taskId}.json`), JSON.stringify({ schema_version: 1, task_id: taskId, files }, null, 2), "utf8");
     }
+    async persistReviewOutput(jobId, taskId, payload) {
+        const dir = path.join(REVIEW_DIR(this.workspace.mcodaDir, jobId), "outputs");
+        await fs.mkdir(dir, { recursive: true });
+        const target = path.join(dir, `${taskId}.json`);
+        await fs.writeFile(target, JSON.stringify(payload, null, 2), "utf8");
+        return path.relative(this.workspace.mcodaDir, target);
+    }
     severityToPriority(severity) {
         if (!severity)
             return null;
@@ -926,6 +1099,13 @@ export class CodeReviewService {
         const order = { critical: 1, high: 2, medium: 3, low: 4, info: 5 };
         return order[normalized] ?? null;
     }
+    severityToStoryPoints(severity) {
+        if (!severity)
+            return null;
+        const normalized = severity.toLowerCase();
+        const points = { critical: 8, high: 5, medium: 3, low: 2, info: 1 };
+        return points[normalized] ?? null;
+    }
     shouldCreateFollowupTask(decision, finding) {
         // SDS rule: create follow-ups for blocking/changes_requested decisions or critical/high issues,
         // and for contract/security/bug types at medium+ severity. Do not create for approve+low/info.
@@ -1026,6 +1206,9 @@ export class CodeReviewService {
             const storyId = genericTarget ? genericContainers.story.id : params.task.userStoryId;
             const storyKey = genericTarget ? genericContainers.story.key : params.task.storyKey ?? genericContainers?.story.key ?? "US-AUTO";
             const epicId = genericTarget ? genericContainers.epic.id : params.task.epicId;
+            const fallbackPoints = this.resolveTaskComplexity(params.task) ?? params.task.storyPoints ?? 1;
+            const storyPoints = this.severityToStoryPoints(finding.severity) ?? fallbackPoints;
+            const boundedPoints = Number.isFinite(storyPoints) ? Math.min(10, Math.max(1, Math.round(storyPoints))) : 1;
             const taskKey = await ensureKey(storyId, storyKey);
             inserts.push({
                 projectId: params.task.projectId,
@@ -1036,7 +1219,7 @@ export class CodeReviewService {
                 description: this.buildFollowupDescription(params.task, finding, params.decision),
                 type: finding.type ?? (params.decision === "changes_requested" || params.decision === "block" ? "bug" : "issue"),
                 status: "not_started",
-                storyPoints: null,
+                storyPoints: boundedPoints,
                 priority: this.severityToPriority(finding.severity),
                 metadata: {
                     source: "code-review",
@@ -1052,6 +1235,7 @@ export class CodeReviewService {
                     suggestedFix: finding.suggestedFix,
                     generic: genericTarget ? true : false,
                     decision: params.decision,
+                    complexity: boundedPoints,
                 },
             });
         }
@@ -1074,7 +1258,14 @@ export class CodeReviewService {
         await this.ensureMcoda();
         const agentStream = request.agentStream !== false;
         const baseRef = request.baseRef ?? this.workspace.config?.branch ?? DEFAULT_BASE_BRANCH;
-        const statusFilter = request.statusFilter && request.statusFilter.length ? request.statusFilter : ["ready_to_review"];
+        const ignoreStatusFilter = Boolean(request.taskKeys?.length) || request.ignoreStatusFilter === true;
+        const rawStatusFilter = ignoreStatusFilter
+            ? []
+            : request.statusFilter && request.statusFilter.length
+                ? request.statusFilter
+                : [READY_TO_CODE_REVIEW];
+        const { filtered: allowedStatusFilter, rejected } = filterTaskStatuses(rawStatusFilter, REVIEW_ALLOWED_STATUSES, REVIEW_ALLOWED_STATUSES);
+        const statusFilter = normalizeReviewStatuses(allowedStatusFilter);
         let state;
         const commandRun = await this.deps.jobService.startCommandRun("code-review", request.projectKey, {
             taskIds: request.taskKeys,
@@ -1084,6 +1275,10 @@ export class CodeReviewService {
         let jobId = request.resumeJobId;
         let selectedTaskIds = [];
         let warnings = [];
+        if (rejected.length > 0 && !ignoreStatusFilter) {
+            warnings.push(`code-review ignores unsupported statuses: ${rejected.join(", ")}. Allowed: ${REVIEW_ALLOWED_STATUSES.join(", ")}.`);
+        }
+        let allowFollowups = request.createFollowupTasks === true;
         let selectedTasks = [];
         if (request.resumeJobId) {
             const job = await this.deps.jobService.getJob(request.resumeJobId);
@@ -1092,6 +1287,9 @@ export class CodeReviewService {
             if ((job.commandName ?? job.type) !== "code-review" && job.type !== "review") {
                 throw new Error(`Job ${request.resumeJobId} is not a code-review job`);
             }
+            if (request.createFollowupTasks === undefined) {
+                allowFollowups = Boolean(job.payload?.createFollowupTasks);
+            }
             state = await this.loadState(request.resumeJobId);
             selectedTaskIds = state?.selectedTaskIds ?? (Array.isArray(job.payload?.selection) ? job.payload.selection : []);
             if (!selectedTaskIds.length) {
@@ -1128,7 +1326,7 @@ export class CodeReviewService {
                     epicKey: request.epicKey,
                     storyKey: request.storyKey,
                     taskKeys: request.taskKeys,
-                    statusFilter,
+                    statusFilter: ignoreStatusFilter ? undefined : statusFilter,
                     limit: request.limit,
                 });
             }
@@ -1138,10 +1336,11 @@ export class CodeReviewService {
                     epicKey: request.epicKey,
                     storyKey: request.storyKey,
                     taskKeys: request.taskKeys,
-                    statusFilter,
+                    statusFilter: ignoreStatusFilter ? undefined : statusFilter,
                     limit: request.limit,
+                    ignoreStatusFilter,
                 });
-                warnings = [...selection.warnings];
+                warnings = [...warnings, ...selection.warnings];
                 selectedTasks = selection.ordered.map((t) => t.task);
             }
             selectedTaskIds = selectedTasks.map((t) => t.id);
@@ -1152,12 +1351,13 @@ export class CodeReviewService {
                     epicKey: request.epicKey,
                     storyKey: request.storyKey,
                     tasks: request.taskKeys,
-                    statusFilter,
+                    statusFilter: ignoreStatusFilter ? [] : statusFilter,
                     baseRef,
                     selection: selectedTaskIds,
                     dryRun: request.dryRun ?? false,
                     agent: request.agentName,
                     agentStream,
+                    createFollowupTasks: allowFollowups,
                 },
                 totalItems: selectedTaskIds.length,
                 processedItems: 0,
@@ -1194,10 +1394,38 @@ export class CodeReviewService {
         const tasks = selectedTasks.length && selectedTaskIds.length === selectedTasks.length
             ? selectedTasks
             : await this.deps.workspaceRepo.getTasksWithRelations(selectedTaskIds);
-        const agent = await this.resolveAgent(request.agentName);
+        let resolvedAgent;
+        try {
+            resolvedAgent = await this.resolveAgent(request.agentName);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (request.agentName) {
+                const warning = `Review agent override (${request.agentName}) failed: ${message}`;
+                warnings.push(warning);
+                console.warn(`[code-review] ${warning}`);
+            }
+            throw error;
+        }
+        const agent = resolvedAgent.agent;
+        const reviewJsonAgentOverride = this.workspace.config?.reviewJsonAgent ??
+            process.env.MCODA_REVIEW_JSON_AGENT ??
+            process.env.MCODA_REVIEW_JSON_AGENT_NAME;
+        let reviewJsonAgent;
+        if (reviewJsonAgentOverride &&
+            reviewJsonAgentOverride !== agent.id &&
+            reviewJsonAgentOverride !== agent.slug) {
+            try {
+                reviewJsonAgent = (await this.resolveAgent(reviewJsonAgentOverride)).agent;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                warnings.push(`Review JSON agent override (${reviewJsonAgentOverride}) failed: ${message}`);
+            }
+        }
         const prompts = await this.loadPrompts(agent.id);
         const extras = await this.loadRunbookAndChecklists();
-        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot);
+        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir);
         if (projectGuidance) {
             console.info(`[code-review] loaded project guidance from ${projectGuidance.source}`);
         }
@@ -1232,6 +1460,78 @@ export class CodeReviewService {
             });
         };
         const results = [];
+        const formatSessionId = (iso) => {
+            const date = new Date(iso);
+            const pad = (value) => String(value).padStart(2, "0");
+            return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}_${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+        };
+        const formatDuration = (ms) => {
+            const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+            const seconds = totalSeconds % 60;
+            const minutesTotal = Math.floor(totalSeconds / 60);
+            const minutes = minutesTotal % 60;
+            const hours = Math.floor(minutesTotal / 60);
+            if (hours > 0)
+                return `${hours}H ${minutes}M ${seconds}S`;
+            return `${minutes}M ${seconds}S`;
+        };
+        const resolveProvider = (adapter) => {
+            if (!adapter)
+                return "n/a";
+            const trimmed = adapter.trim();
+            if (!trimmed)
+                return "n/a";
+            if (trimmed.includes("-"))
+                return trimmed.split("-")[0];
+            return trimmed;
+        };
+        const resolveReasoning = (config) => {
+            if (!config)
+                return "n/a";
+            const raw = config.reasoning ?? config.thinking;
+            if (typeof raw === "string")
+                return raw;
+            if (typeof raw === "boolean")
+                return raw ? "enabled" : "disabled";
+            return "n/a";
+        };
+        const emitLine = (line) => {
+            console.info(line);
+        };
+        const emitBlank = () => emitLine("");
+        const emitReviewStart = (details) => {
+            emitLine("╭──────────────────────────────────────────────────────────╮");
+            emitLine("│              START OF CODE REVIEW TASK                   │");
+            emitLine("╰──────────────────────────────────────────────────────────╯");
+            emitLine(`  [🪪] Code Review Task ID: ${details.taskKey}`);
+            emitLine(`  [👹] Alias:          ${details.alias}`);
+            emitLine(`  [ℹ️] Summary:        ${details.summary}`);
+            emitLine(`  [🤖] Model:          ${details.model}`);
+            emitLine(`  [🕹️] Provider:       ${details.provider}`);
+            emitLine(`  [🧩] Step:           ${details.step}`);
+            emitLine(`  [🧠] Reasoning:      ${details.reasoning}`);
+            emitLine(`  [📁] Workdir:        ${details.workdir}`);
+            emitLine(`  [🔑] Session:        ${details.sessionId}`);
+            emitLine(`  [🕒] Started:        ${details.startedAt}`);
+            emitBlank();
+            emitLine("    ░░░░░ START OF CODE REVIEW TASK ░░░░░");
+            emitBlank();
+            emitLine(`    [STEP ${details.step}]  [MODEL ${details.model}]`);
+            emitBlank();
+            emitBlank();
+        };
+        const emitReviewEnd = (details) => {
+            emitLine("╭──────────────────────────────────────────────────────────╮");
+            emitLine("│                END OF CODE REVIEW TASK                   │");
+            emitLine("╰──────────────────────────────────────────────────────────╯");
+            emitLine(`  👀 CODE REVIEW TASK ${details.taskKey} | 📜 STATUS ${details.statusLabel} | ✅ DECISION ${details.decision ?? "n/a"} | 🔎 FINDINGS ${details.findingsCount} | ⌛ TIME ${formatDuration(details.elapsedMs)}`);
+            emitLine(`  [🕒] Started:        ${details.startedAt}`);
+            emitLine(`  [🕒] Ended:          ${details.endedAt}`);
+            emitLine(`  Tokens used:  ${details.tokensTotal.toLocaleString("en-US")}`);
+            emitBlank();
+            emitLine("    ░░░░░ END OF CODE REVIEW TASK ░░░░░");
+            emitBlank();
+        };
         const maybeRateTask = async (task, taskRunId, tokensTotal) => {
             if (!request.rateAgents || tokensTotal <= 0)
                 return;
@@ -1245,7 +1545,7 @@ export class CodeReviewService {
                     commandRunId: commandRun.id,
                     taskId: task.id,
                     taskKey: task.key,
-                    discipline: task.type ?? undefined,
+                    discipline: task.type ?? "review",
                     complexity: this.resolveTaskComplexity(task),
                 });
             }
@@ -1266,8 +1566,36 @@ export class CodeReviewService {
                 }
             }
         };
+        let abortRemainingReason = null;
         for (const task of tasks) {
+            if (abortRemainingReason)
+                break;
             abortIfSignaled();
+            const startedAt = new Date().toISOString();
+            const taskStartMs = Date.now();
+            const sessionId = formatSessionId(startedAt);
+            const taskAlias = `Reviewing task ${task.key}`;
+            const taskSummary = task.title ?? task.description ?? "(none)";
+            const modelLabel = agent.defaultModel ?? "(default)";
+            const providerLabel = resolveProvider(agent.adapter);
+            const reasoningLabel = resolveReasoning(agent.config);
+            const stepLabel = "review";
+            let endEmitted = false;
+            const emitReviewEndOnce = (details) => {
+                if (endEmitted)
+                    return;
+                endEmitted = true;
+                emitReviewEnd({
+                    taskKey: task.key,
+                    statusLabel: details.statusLabel,
+                    decision: details.decision,
+                    findingsCount: details.findingsCount,
+                    elapsedMs: Date.now() - taskStartMs,
+                    tokensTotal: details.tokensTotal,
+                    startedAt,
+                    endedAt: new Date().toISOString(),
+                });
+            };
             const statusBefore = task.status;
             const taskRun = await this.deps.workspaceRepo.createTaskRun({
                 taskId: task.id,
@@ -1276,21 +1604,42 @@ export class CodeReviewService {
                 commandRunId: commandRun.id,
                 agentId: agent.id,
                 status: "running",
-                startedAt: new Date().toISOString(),
+                startedAt,
                 storyPointsAtRun: task.storyPoints ?? null,
                 gitBranch: task.vcsBranch ?? null,
                 gitBaseBranch: task.vcsBaseBranch ?? null,
                 gitCommitSha: task.vcsLastCommitSha ?? null,
             });
+            const statusContext = {
+                commandName: "code-review",
+                jobId,
+                taskRunId: taskRun.id,
+                agentId: agent.id,
+                metadata: { lane: "review" },
+            };
             const findings = [];
             let decision;
             let statusAfter;
+            let reviewErrorCode;
             const followupCreated = [];
             let commentResolution;
             // Debug visibility: show prompts/task details for this run
             const systemPrompt = systemPrompts.join("\n\n");
             let tokensTotal = 0;
+            let agentOutput = "";
             try {
+                emitReviewStart({
+                    taskKey: task.key,
+                    alias: taskAlias,
+                    summary: taskSummary,
+                    model: modelLabel,
+                    provider: providerLabel,
+                    step: stepLabel,
+                    reasoning: reasoningLabel,
+                    workdir: this.workspace.workspaceRoot,
+                    sessionId,
+                    startedAt,
+                });
                 const metadata = task.metadata ?? {};
                 const allowedFiles = Array.isArray(metadata.files) ? metadata.files : [];
                 const diffResult = await this.buildDiff(task, state?.baseRef ?? baseRef, allowedFiles);
@@ -1312,9 +1661,10 @@ export class CodeReviewService {
                         allowedFiles,
                     },
                 });
-                if (!diff.trim()) {
-                    const message = "Review diff is empty; blocking review until changes are produced.";
-                    warnings.push(`Empty diff for ${task.key}; blocking review.`);
+                const diffEmpty = !diff.trim();
+                if (diffEmpty) {
+                    const message = `Empty diff for ${task.key}; reviewing task requirements to confirm whether no changes are acceptable.`;
+                    warnings.push(message);
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
                         sequence: this.sequenceForTask(taskRun.id),
@@ -1322,43 +1672,6 @@ export class CodeReviewService {
                         source: "review_warning",
                         message,
                     });
-                    if (!request.dryRun) {
-                        await this.stateService.markBlocked(task, "review_empty_diff");
-                        statusAfter = "blocked";
-                    }
-                    await this.writeReviewSummaryComment({
-                        task,
-                        taskRunId: taskRun.id,
-                        jobId,
-                        agentId: agent.id,
-                        statusBefore,
-                        statusAfter: statusAfter ?? statusBefore,
-                        decision: "block",
-                        summary: message,
-                        findingsCount: 0,
-                    });
-                    await this.deps.workspaceRepo.updateTaskRun(taskRun.id, {
-                        status: "failed",
-                        finishedAt: new Date().toISOString(),
-                        runContext: { decision: "block", reason: "empty_diff" },
-                    });
-                    state?.reviewed.push({ taskId: task.id, decision: "block" });
-                    await this.persistState(jobId, state);
-                    await this.writeCheckpoint(jobId, "review_applied", { reviewed: state?.reviewed ?? [], schema_version: 1 });
-                    results.push({
-                        taskId: task.id,
-                        taskKey: task.key,
-                        statusBefore,
-                        statusAfter: statusAfter ?? statusBefore,
-                        decision: "block",
-                        findings,
-                        followupTasks: followupCreated,
-                    });
-                    await this.deps.jobService.updateJobStatus(jobId, "running", {
-                        processedItems: state?.reviewed.length ?? 0,
-                    });
-                    await maybeRateTask(task, taskRun.id, tokensTotal);
-                    continue;
                 }
                 const historySummary = await this.buildHistorySummary(task.id);
                 const commentContext = await this.loadCommentContext(task.id);
@@ -1371,7 +1684,8 @@ export class CodeReviewService {
                     message: "Loaded task history",
                 });
                 const changedPaths = this.extractPathsFromDiff(diff);
-                const docLinks = await this.gatherDocContext(task.title, changedPaths.length ? changedPaths : allowedFiles, task.acceptanceCriteria);
+                const diffMeta = { diffEmpty, changedPaths };
+                const docLinks = await this.gatherDocContext(task.title, changedPaths.length ? changedPaths : allowedFiles, task.acceptanceCriteria, Array.isArray(task.metadata?.doc_links) ? task.metadata.doc_links : []);
                 if (docLinks.warnings.length)
                     warnings.push(...docLinks.warnings);
                 await this.deps.workspaceRepo.insertTaskLog({
@@ -1397,6 +1711,7 @@ export class CodeReviewService {
                     systemPrompts,
                     task,
                     diff,
+                    diffEmpty,
                     docContext: docLinks.snippets,
                     openapiSnippet,
                     historySummary,
@@ -1404,6 +1719,7 @@ export class CodeReviewService {
                     baseRef: state?.baseRef ?? baseRef,
                     branch: task.vcsBranch ?? undefined,
                 });
+                const requireCommentSlugs = Boolean(commentBacklog.trim());
                 const separator = "============================================================";
                 const deps = Array.isArray(task.dependencyKeys) && task.dependencyKeys.length
                     ? task.dependencyKeys
@@ -1411,7 +1727,6 @@ export class CodeReviewService {
                         ? task.metadata.depends_on
                         : [];
                 console.info(separator);
-                console.info("[code-review] START OF TASK");
                 console.info(`[code-review] Task key: ${task.key}`);
                 console.info(`[code-review] Title: ${task.title ?? "(none)"}`);
                 console.info(`[code-review] Description: ${task.description ?? "(none)"}`);
@@ -1429,19 +1744,20 @@ export class CodeReviewService {
                     docdex: docLinks.snippets,
                     openapiSnippet,
                     changedPaths,
+                    diffEmpty,
                 });
                 state?.contextBuilt.push(task.id);
                 await this.persistState(jobId, state);
                 await this.writeCheckpoint(jobId, "context_built", { contextBuilt: state?.contextBuilt ?? [], schema_version: 1 });
-                const recordUsage = async (phase, promptText, outputText, durationSeconds, tokenMeta) => {
+                const recordUsage = async (phase, promptText, outputText, durationSeconds, tokenMeta, agentUsed = agent, attempt = 1) => {
                     const tokensPrompt = tokenMeta?.tokensPrompt ?? estimateTokens(promptText);
                     const tokensCompletion = tokenMeta?.tokensCompletion ?? estimateTokens(outputText);
                     const entryTotal = tokenMeta?.tokensTotal ?? tokensPrompt + tokensCompletion;
                     tokensTotal += entryTotal;
                     await this.deps.jobService.recordTokenUsage({
                         workspaceId: this.workspace.workspaceId,
-                        agentId: agent.id,
-                        modelName: tokenMeta?.model ?? agent.defaultModel ?? undefined,
+                        agentId: agentUsed.id,
+                        modelName: tokenMeta?.model ?? agentUsed.defaultModel ?? undefined,
                         jobId,
                         commandRunId: commandRun.id,
                         taskRunId: taskRun.id,
@@ -1452,45 +1768,82 @@ export class CodeReviewService {
                         tokensTotal: entryTotal,
                         durationSeconds,
                         timestamp: new Date().toISOString(),
-                        metadata: { commandName: "code-review", phase, action: phase },
+                        metadata: { commandName: "code-review", phase, action: phase, attempt },
                     });
                 };
-                let agentOutput = "";
+                agentOutput = "";
                 let durationSeconds = 0;
-                const started = Date.now();
                 let lastStreamMeta;
-                if (agentStream && this.deps.agentService.invokeStream) {
-                    const stream = await withAbort(this.deps.agentService.invokeStream(agent.id, { input: prompt, metadata: { taskKey: task.key } }));
-                    while (true) {
-                        abortIfSignaled();
-                        const { value, done } = await withAbort(stream.next());
-                        if (done)
-                            break;
-                        const chunk = value;
-                        agentOutput += chunk.output ?? "";
-                        lastStreamMeta = chunk.metadata ?? lastStreamMeta;
+                let agentUsedForOutput = agent;
+                let outputAttempt = 1;
+                const invokeReviewAgent = async (agentToUse, useStream, logSource) => {
+                    let output = "";
+                    let metadata;
+                    const started = Date.now();
+                    if (useStream && this.deps.agentService.invokeStream) {
+                        const stream = await withAbort(this.deps.agentService.invokeStream(agentToUse.id, {
+                            input: prompt,
+                            metadata: { taskKey: task.key, retry: logSource === "agent_retry" },
+                        }));
+                        while (true) {
+                            abortIfSignaled();
+                            const { value, done } = await withAbort(stream.next());
+                            if (done)
+                                break;
+                            const chunk = value;
+                            output += chunk.output ?? "";
+                            metadata = chunk.metadata ?? metadata;
+                            await this.deps.workspaceRepo.insertTaskLog({
+                                taskRunId: taskRun.id,
+                                sequence: this.sequenceForTask(taskRun.id),
+                                timestamp: new Date().toISOString(),
+                                source: logSource,
+                                message: chunk.output ?? "",
+                            });
+                        }
+                    }
+                    else {
+                        const response = await withAbort(this.deps.agentService.invoke(agentToUse.id, {
+                            input: prompt,
+                            metadata: { taskKey: task.key, retry: logSource === "agent_retry" },
+                        }));
+                        output = response.output ?? "";
+                        metadata = response.metadata;
                         await this.deps.workspaceRepo.insertTaskLog({
                             taskRunId: taskRun.id,
                             sequence: this.sequenceForTask(taskRun.id),
                             timestamp: new Date().toISOString(),
-                            source: "agent",
-                            message: chunk.output ?? "",
+                            source: logSource,
+                            message: output,
                         });
                     }
-                    durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
+                    const durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
+                    return { output, durationSeconds, metadata };
+                };
+                try {
+                    const invocation = await invokeReviewAgent(agent, Boolean(agentStream && this.deps.agentService.invokeStream), "agent");
+                    agentOutput = invocation.output;
+                    durationSeconds = invocation.durationSeconds;
+                    lastStreamMeta = invocation.metadata;
                 }
-                else {
-                    const response = await withAbort(this.deps.agentService.invoke(agent.id, { input: prompt, metadata: { taskKey: task.key } }));
-                    agentOutput = response.output ?? "";
-                    durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (!isRetryableAgentError(message)) {
+                        throw error;
+                    }
+                    outputAttempt = 2;
+                    agentUsedForOutput = reviewJsonAgent ?? agent;
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
                         sequence: this.sequenceForTask(taskRun.id),
                         timestamp: new Date().toISOString(),
-                        source: "agent",
-                        message: agentOutput,
+                        source: "agent_retry",
+                        message: `Transient agent error (${message}); retrying once with ${agentUsedForOutput.slug ?? agentUsedForOutput.id}.`,
                     });
-                    lastStreamMeta = response.metadata;
+                    const invocation = await invokeReviewAgent(agentUsedForOutput, false, "agent_retry");
+                    agentOutput = invocation.output;
+                    durationSeconds = invocation.durationSeconds;
+                    lastStreamMeta = invocation.metadata;
                 }
                 const tokenMetaMain = lastStreamMeta
                     ? {
@@ -1502,21 +1855,60 @@ export class CodeReviewService {
                         model: (lastStreamMeta.model ?? lastStreamMeta.model_name ?? null),
                     }
                     : undefined;
-                await recordUsage("review_main", prompt, agentOutput, durationSeconds, tokenMetaMain);
-                let parsed = parseJsonOutput(agentOutput);
-                let invalidJson = false;
-                if (!parsed) {
+                await recordUsage("review_main", prompt, agentOutput, durationSeconds, tokenMetaMain, agentUsedForOutput, outputAttempt);
+                const primaryOutput = agentOutput;
+                let retryOutput;
+                let retryAgentUsed;
+                let normalization = normalizeReviewOutput(agentOutput);
+                let parsed = normalization.result;
+                let validationError = validateReviewOutput(parsed, { requireCommentSlugs });
+                if (validationError === "resolvedSlugs/unresolvedSlugs required when comment backlog exists.") {
+                    const warning = `Review output missing comment slugs for ${task.key}; assuming no backlog items resolved.`;
+                    warnings.push(warning);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message: warning,
+                    });
+                    validationError = undefined;
+                }
+                const needsRetry = Boolean(validationError) || normalization.usedFallback;
+                if (needsRetry) {
+                    const retryReason = validationError
+                        ? `Invalid review schema (${validationError}); retrying once with stricter instructions.`
+                        : "Unstructured review output; retrying once with stricter instructions.";
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
                         sequence: this.sequenceForTask(taskRun.id),
                         timestamp: new Date().toISOString(),
                         source: "agent",
-                        message: "Invalid JSON from agent; retrying once with stricter instructions.",
+                        message: retryReason,
                     });
-                    const retryPrompt = `${prompt}\n\nRespond ONLY with valid JSON matching the schema above. Do not include prose or fences.`;
+                    const buildRetryPrompt = (raw) => [
+                        "Your previous response was invalid JSON. Reformat it to match the schema below.",
+                        JSON_RETRY_RULES,
+                        JSON_CONTRACT,
+                        "RESPONSE_TO_CONVERT:",
+                        raw,
+                    ].join("\n");
+                    const retryPrompt = agentOutput.trim()
+                        ? buildRetryPrompt(agentOutput)
+                        : `${prompt}\n\n${JSON_RETRY_RULES}\n${JSON_CONTRACT}`;
                     const retryStarted = Date.now();
-                    const retryResp = await withAbort(this.deps.agentService.invoke(agent.id, { input: retryPrompt, metadata: { taskKey: task.key, retry: true } }));
-                    const retryOutput = retryResp.output ?? "";
+                    retryAgentUsed = reviewJsonAgent ?? agent;
+                    if (retryAgentUsed.id !== agent.id) {
+                        await this.deps.workspaceRepo.insertTaskLog({
+                            taskRunId: taskRun.id,
+                            sequence: this.sequenceForTask(taskRun.id),
+                            timestamp: new Date().toISOString(),
+                            source: "agent_retry",
+                            message: `Retrying with JSON-only agent override: ${retryAgentUsed.slug ?? retryAgentUsed.id}`,
+                        });
+                    }
+                    const retryResp = await withAbort(this.deps.agentService.invoke(retryAgentUsed.id, { input: retryPrompt, metadata: { taskKey: task.key, retry: true } }));
+                    retryOutput = retryResp.output ?? "";
                     const retryDuration = Math.round(((Date.now() - retryStarted) / 1000) * 1000) / 1000;
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
@@ -1539,14 +1931,27 @@ export class CodeReviewService {
                             model: (retryResp.metadata.model ?? retryResp.metadata.model_name ?? null),
                         }
                         : undefined;
-                    await recordUsage("review_retry", retryPrompt, retryOutput, retryDuration, retryTokenMeta);
-                    parsed = parseJsonOutput(retryOutput);
+                    await recordUsage("review_retry", retryPrompt, retryOutput, retryDuration, retryTokenMeta, retryAgentUsed, 2);
+                    normalization = normalizeReviewOutput(retryOutput);
+                    parsed = normalization.result;
+                    validationError = validateReviewOutput(parsed, { requireCommentSlugs });
+                    if (validationError === "resolvedSlugs/unresolvedSlugs required when comment backlog exists.") {
+                        const warning = `Review output missing comment slugs for ${task.key} after retry; assuming no backlog items resolved.`;
+                        warnings.push(warning);
+                        await this.deps.workspaceRepo.insertTaskLog({
+                            taskRunId: taskRun.id,
+                            sequence: this.sequenceForTask(taskRun.id),
+                            timestamp: new Date().toISOString(),
+                            source: "review_warning",
+                            message: warning,
+                        });
+                        validationError = undefined;
+                    }
                     agentOutput = retryOutput;
                 }
-                if (!parsed) {
-                    invalidJson = true;
-                    const fallbackSummary = "Review agent returned non-JSON output after retry; block review and re-run with a stricter JSON-only model.";
-                    warnings.push(`Review agent returned non-JSON output for ${task.key}; blocking review.`);
+                if (validationError) {
+                    const fallbackSummary = `Review output missing required fields (${validationError}); treated as informational.`;
+                    warnings.push(`Review output missing required fields for ${task.key}; proceeding with info_only.`);
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
                         sequence: this.sequenceForTask(taskRun.id),
@@ -1555,17 +1960,60 @@ export class CodeReviewService {
                         message: fallbackSummary,
                     });
                     parsed = {
-                        decision: "block",
+                        decision: "info_only",
                         summary: fallbackSummary,
                         findings: [],
                         testRecommendations: [],
-                        raw: agentOutput,
+                        raw: retryOutput ?? agentOutput,
                     };
+                    normalization = { parsedFromJson: false, usedFallback: true, issues: ["validation_error"], result: parsed };
                 }
-                parsed.raw = agentOutput;
+                if (normalization.usedFallback) {
+                    const fallbackMessage = `Review output was not valid JSON for ${task.key}; treated as informational.`;
+                    warnings.push(fallbackMessage);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message: fallbackMessage,
+                    });
+                    try {
+                        const artifactPath = await this.persistReviewOutput(jobId, task.id, {
+                            schema_version: 1,
+                            task_key: task.key,
+                            created_at: new Date().toISOString(),
+                            agent_id: agent.id,
+                            retry_agent_id: retryAgentUsed?.id ?? agent.id,
+                            primary_output: primaryOutput,
+                            retry_output: retryOutput ?? agentOutput,
+                            validation_error: validationError ?? null,
+                        });
+                        warnings.push(`Review output saved to ${artifactPath} for ${task.key}.`);
+                    }
+                    catch (persistError) {
+                        warnings.push(`Failed to persist review output for ${task.key}: ${persistError instanceof Error ? persistError.message : String(persistError)}`);
+                    }
+                }
+                parsed.raw = parsed.raw ?? agentOutput;
                 const originalDecision = parsed.decision;
                 decision = parsed.decision;
                 findings.push(...(parsed.findings ?? []));
+                const historySupportsNoChanges = task.metadata?.completed_reason === "no_changes" ||
+                    historySummary.toLowerCase().includes("no_changes") ||
+                    historySummary.toLowerCase().includes("no changes");
+                const summarySupportsNoChanges = summaryIndicatesNoChanges(parsed.summary);
+                const approveDecision = parsed.decision === "approve" || parsed.decision === "info_only";
+                let finalDecision = parsed.decision;
+                let emptyDiffOverride = false;
+                if (diffEmpty && approveDecision && !(summarySupportsNoChanges && historySupportsNoChanges)) {
+                    finalDecision = "changes_requested";
+                    emptyDiffOverride = true;
+                }
+                if (finalDecision === "changes_requested" && isNonBlockingOnly(parsed.findings ?? []) && !emptyDiffOverride) {
+                    finalDecision = "info_only";
+                    warnings.push(`Review for ${task.key} requested changes but only low/info findings were reported; downgrading to info_only.`);
+                }
                 commentResolution = await this.applyCommentResolutions({
                     task,
                     taskRunId: taskRun.id,
@@ -1574,10 +2022,9 @@ export class CodeReviewService {
                     findings: parsed.findings ?? [],
                     resolvedSlugs: parsed.resolvedSlugs ?? undefined,
                     unresolvedSlugs: parsed.unresolvedSlugs ?? undefined,
-                    decision: parsed.decision,
+                    decision: finalDecision,
                     existingComments: commentContext.comments,
                 });
-                let finalDecision = parsed.decision;
                 if (commentResolution?.open?.length &&
                     (finalDecision === "approve" || finalDecision === "info_only")) {
                     const openSlugs = commentResolution.open;
@@ -1610,47 +2057,106 @@ export class CodeReviewService {
                         createdAt: new Date().toISOString(),
                     });
                 }
+                if (emptyDiffOverride) {
+                    const message = [
+                        "Empty diff detected; approval requires an explicit no-changes justification",
+                        "and task history indicating no changes were needed.",
+                    ].join(" ");
+                    const slug = createTaskCommentSlug({
+                        source: "code-review",
+                        message,
+                        category: "review_empty_diff",
+                    });
+                    const body = formatTaskCommentBody({
+                        slug,
+                        source: "code-review",
+                        message,
+                        status: "open",
+                        category: "review_empty_diff",
+                    });
+                    await this.deps.workspaceRepo.createTaskComment({
+                        taskId: task.id,
+                        taskRunId: taskRun.id,
+                        jobId,
+                        sourceCommand: "code-review",
+                        authorType: "agent",
+                        authorAgentId: agent.id,
+                        category: "review_empty_diff",
+                        slug,
+                        status: "open",
+                        body,
+                        createdAt: new Date().toISOString(),
+                    });
+                    warnings.push(`Empty diff approval rejected for ${task.key}; requesting explicit no-changes justification.`);
+                }
+                const appendSyntheticFinding = (message, suggestedFix) => {
+                    const finding = {
+                        type: "process",
+                        severity: "info",
+                        message,
+                        suggestedFix,
+                    };
+                    if (!parsed.findings) {
+                        parsed.findings = [];
+                    }
+                    parsed.findings.push(finding);
+                    findings.push(finding);
+                };
+                if (finalDecision === "changes_requested" && (parsed.findings?.length ?? 0) === 0) {
+                    if (emptyDiffOverride) {
+                        appendSyntheticFinding("Empty diff lacks explicit no-changes justification; changes requested to confirm no code updates were required.", "Update the review summary to state no changes were required and confirm task history reflects no_changes.");
+                    }
+                    else if (commentResolution?.open?.length) {
+                        appendSyntheticFinding(`Unresolved comment backlog remains (${formatSlugList(commentResolution.open)}); approval requires resolving these items.`, "Resolve or explicitly reopen the listed comment slugs before approving.");
+                    }
+                    else {
+                        finalDecision = "info_only";
+                        warnings.push(`Review requested changes for ${task.key} but provided no findings; downgrading to info_only.`);
+                    }
+                }
                 parsed.decision = finalDecision;
                 decision = finalDecision;
-                const followups = await this.createFollowupTasksForFindings({
-                    task,
-                    findings: parsed.findings ?? [],
-                    decision: originalDecision,
-                    jobId,
-                    commandRunId: commandRun.id,
-                    taskRunId: taskRun.id,
-                });
-                if (followups.length) {
-                    followupCreated.push(...followups.map((t) => ({
-                        taskId: t.id,
-                        taskKey: t.key,
-                        epicId: t.epicId,
-                        userStoryId: t.userStoryId,
-                        generic: t?.metadata?.generic ? true : undefined,
-                    })));
-                    warnings.push(`Created follow-up tasks for ${task.key}: ${followups.map((t) => t.key).join(", ")}`);
+                if (allowFollowups) {
+                    const followups = await this.createFollowupTasksForFindings({
+                        task,
+                        findings: parsed.findings ?? [],
+                        decision: originalDecision,
+                        jobId,
+                        commandRunId: commandRun.id,
+                        taskRunId: taskRun.id,
+                    });
+                    if (followups.length) {
+                        followupCreated.push(...followups.map((t) => ({
+                            taskId: t.id,
+                            taskKey: t.key,
+                            epicId: t.epicId,
+                            userStoryId: t.userStoryId,
+                            generic: t?.metadata?.generic ? true : undefined,
+                        })));
+                        warnings.push(`Created follow-up tasks for ${task.key}: ${followups.map((t) => t.key).join(", ")}`);
+                    }
                 }
                 let taskStatusUpdate = statusBefore;
                 if (!request.dryRun) {
-                    if (invalidJson) {
-                        await this.stateService.markBlocked(task, "review_invalid_output");
-                        taskStatusUpdate = "blocked";
-                    }
-                    else {
-                        const approveDecision = parsed.decision === "approve" || parsed.decision === "info_only";
-                        if (approveDecision) {
-                            await this.stateService.markReadyToQa(task);
-                            taskStatusUpdate = "ready_to_qa";
-                        }
-                        else if (parsed.decision === "changes_requested") {
-                            await this.stateService.returnToInProgress(task);
-                            taskStatusUpdate = "in_progress";
+                    const approveDecision = parsed.decision === "approve" || parsed.decision === "info_only";
+                    if (approveDecision) {
+                        if (diffEmpty) {
+                            await this.stateService.markCompleted(task, { review_no_changes: true }, statusContext);
+                            taskStatusUpdate = "completed";
                         }
-                        else if (parsed.decision === "block") {
-                            await this.stateService.markBlocked(task, "review_blocked");
-                            taskStatusUpdate = "blocked";
+                        else {
+                            await this.stateService.markReadyToQa(task, undefined, statusContext);
+                            taskStatusUpdate = "ready_to_qa";
                         }
                     }
+                    else if (parsed.decision === "changes_requested") {
+                        await this.stateService.markChangesRequested(task, undefined, statusContext);
+                        taskStatusUpdate = "changes_requested";
+                    }
+                    else if (parsed.decision === "block") {
+                        await this.stateService.markFailed(task, "review_blocked", statusContext);
+                        taskStatusUpdate = "failed";
+                    }
                 }
                 else {
                     await this.deps.workspaceRepo.insertTaskLog({
@@ -1678,7 +2184,7 @@ export class CodeReviewService {
                     reopenedCount: commentResolution?.reopened.length,
                     openCount: commentResolution?.open.length,
                 });
-                await this.deps.workspaceRepo.createTaskReview({
+                const review = await this.deps.workspaceRepo.createTaskReview({
                     taskId: task.id,
                     jobId,
                     agentId: agent.id,
@@ -1687,6 +2193,7 @@ export class CodeReviewService {
                     summary: parsed.summary ?? undefined,
                     findingsJson: parsed.findings ?? [],
                     testRecommendationsJson: parsed.testRecommendations ?? [],
+                    metadata: diffMeta,
                     createdAt: new Date().toISOString(),
                 });
                 await this.stateService.recordReviewMetadata(task, {
@@ -1694,6 +2201,9 @@ export class CodeReviewService {
                     agentId: agent.id,
                     modelName: agent.defaultModel ?? null,
                     jobId,
+                    reviewId: review.id,
+                    diffEmpty,
+                    changedPaths,
                 });
                 await this.deps.workspaceRepo.updateTaskRun(taskRun.id, {
                     status: "succeeded",
@@ -1745,7 +2255,18 @@ export class CodeReviewService {
                 await this.deps.jobService.updateJobStatus(jobId, "running", {
                     processedItems: state?.reviewed.length ?? 0,
                 });
+                emitReviewEndOnce({
+                    statusLabel: "FAILED",
+                    decision: "error",
+                    findingsCount: findings.length,
+                    tokensTotal,
+                });
                 await maybeRateTask(task, taskRun.id, tokensTotal);
+                if (isAuthErrorMessage(message)) {
+                    abortRemainingReason = message;
+                    warnings.push(`Auth/rate limit error detected; stopping after ${task.key}. ${message}`);
+                    break;
+                }
                 continue;
             }
             results.push({
@@ -1755,13 +2276,38 @@ export class CodeReviewService {
                 statusAfter,
                 decision,
                 findings,
+                error: reviewErrorCode,
                 followupTasks: followupCreated,
             });
+            const statusLabel = reviewErrorCode
+                ? "FAILED"
+                : decision === "approve" || decision === "info_only"
+                    ? "APPROVED"
+                    : decision === "block"
+                        ? "FAILED"
+                        : decision === "changes_requested"
+                            ? "CHANGES_REQUESTED"
+                            : "FAILED";
+            emitReviewEndOnce({
+                statusLabel,
+                decision,
+                findingsCount: findings.length,
+                tokensTotal,
+            });
             await this.deps.jobService.updateJobStatus(jobId, "running", {
                 processedItems: state?.reviewed.length ?? 0,
             });
             await maybeRateTask(task, taskRun.id, tokensTotal);
         }
+        if (abortRemainingReason) {
+            await this.deps.jobService.updateJobStatus(jobId, "failed", {
+                processedItems: state?.reviewed.length ?? 0,
+                totalItems: selectedTaskIds.length,
+                errorSummary: AUTH_ERROR_REASON,
+            });
+            await this.deps.jobService.finishCommandRun(commandRun.id, "failed", abortRemainingReason);
+            return { jobId, commandRunId: commandRun.id, tasks: results, warnings };
+        }
         await this.deps.jobService.updateJobStatus(jobId, "completed", {
             processedItems: state?.reviewed.length ?? selectedTaskIds.length,
             totalItems: selectedTaskIds.length,