@lsctech/polaris 0.5.6 → 0.5.7

package/dist/qc/policy.js

@@ -9,6 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decideQcAction = decideQcAction;
+exports.decideProviderFailureAction = decideProviderFailureAction;
 exports.computeQcPolicyDecision = computeQcPolicyDecision;
 const severity_js_1 = require("./severity.js");
 /**
@@ -16,6 +17,7 @@ const severity_js_1 = require("./severity.js");
  *
  * Rules:
  *   - passed / skipped  -> pass (no effect on delivery)
+ *   - allProvidersFailed -> block
  *   - repairRouting: "block"  -> block finalize/delivery
  *   - repairRouting: "log"    -> pass (passive report only)
  *   - repairRouting: "route" / "follow-up" -> create follow-up work, but high/critical
@@ -27,6 +29,9 @@ function decideQcAction(result, config) {
     if (result.status === "passed" || result.status === "skipped") {
         return "pass";
     }
+    if (result.allProvidersFailed) {
+        return "block";
+    }
     const routing = config.repairRouting ?? "route";
     if (routing === "block") {
         return "block";
@@ -41,19 +46,41 @@ function decideQcAction(result, config) {
     }
     return "follow-up";
 }
+/**
+ * Decide what the runtime should do with a classified provider failure.
+ *
+ * Maps a failure reason to the per-provider failure policy from configuration.
+ * Reasons without a dedicated policy key default to "fail" so behavior is
+ * deterministic even for newly-classified failures.
+ */
+function decideProviderFailureAction(reason, policy) {
+    switch (reason) {
+        case "timeout":
+            return policy?.timeout ?? "fail";
+        case "parse-failed":
+            return policy?.parseFailure ?? "fail";
+        default:
+            return "fail";
+    }
+}
 /**
  * Compute the detailed policy decision for a QC result after attribution and
  * repair routing have been applied.
  */
 function computeQcPolicyDecision(result, config) {
     const blockThreshold = config.severityThresholds?.block ?? "high";
-    const blocksDelivery = result.findings.some((f) => (0, severity_js_1.compareSeverity)(f.severity, blockThreshold) >= 0 &&
-        (f.routingDecision === "operator-review" || f.routingDecision === undefined));
-    const requiresOperatorReview = result.status === "failed" ||
+    const blocksDelivery = result.allProvidersFailed ||
+        result.findings.some((f) => (0, severity_js_1.compareSeverity)(f.severity, blockThreshold) >= 0 &&
+            (f.routingDecision === "operator-review" || f.routingDecision === undefined));
+    const requiresOperatorReview = result.allProvidersFailed ||
+        result.status === "failed" ||
         result.status === "blocked" ||
         result.findings.some((f) => f.routingDecision === "operator-review");
     const routedToRepair = result.findings.some((f) => f.routingDecision === "original-worker" || f.routingDecision === "repair-worker");
     const summaryParts = [];
+    if (result.allProvidersFailed) {
+        summaryParts.push("all providers failed");
+    }
     summaryParts.push(`${result.findings.length} findings`);
     if (requiresOperatorReview) {
         summaryParts.push("operator review required");

package/dist/qc/providers/coderabbit.js

@@ -53,7 +53,13 @@ function parseFindingsFromPayload(payload) {
     }
     return [];
 }
-function parseReport(output) {
+function parseReport(output, format, parser) {
+    if (parser && parser !== "coderabbit") {
+        throw new Error(`Unsupported parser for CodeRabbit provider: ${parser}`);
+    }
+    if (format === "sarif") {
+        throw new Error("SARIF output format is not supported by the CodeRabbit provider");
+    }
     const text = "stdout" in output && typeof output.stdout === "string" ? output.stdout : "";
     const data = "data" in output ? output.data : undefined;
     if (data !== undefined && typeof data === "object" && data !== null) {
@@ -64,7 +70,10 @@ function parseReport(output) {
             ...(typeof record.prUrl === "string" ? { prUrl: record.prUrl } : {}),
         };
     }
-    if (text.trim().startsWith("{") || text.trim().startsWith("[")) {
+    if (text.trim().length === 0) {
+        return null;
+    }
+    if (format === "json" || text.trim().startsWith("{") || text.trim().startsWith("[")) {
         try {
             const parsed = JSON.parse(text);
             if (Array.isArray(parsed)) {
@@ -77,11 +86,15 @@ function parseReport(output) {
                     : {}),
             };
         }
-        catch {
-            // Fall through to line scanning.
+        catch (jsonError) {
+            // When the format is explicitly JSON, a parse error is a real failure.
+            // Otherwise, treat the text as JSONL and fall through to line scanning.
+            if (format === "json") {
+                throw jsonError;
+            }
         }
     }
-    // Try JSONL: one finding per line
+    // JSONL or generic line scanning: one finding per line
     const lines = text.split("\n").filter((line) => line.trim().length > 0);
     const lineFindings = [];
     for (const line of lines) {
@@ -96,7 +109,7 @@ function parseReport(output) {
     if (lineFindings.length > 0) {
         return { findings: lineFindings };
     }
-    return null;
+    throw new Error("CodeRabbit output could not be parsed as JSON, JSONL, or metrics payload");
 }
 function normalizeFinding(raw, index) {
     const severityLabel = pickString(raw.severity, raw.level) ?? "info";
@@ -179,6 +192,7 @@ function buildResultFromReport(report, output, mode, providerFailed = false) {
  * No external network calls are made here.
  */
 class CodeRabbitQcProvider {
+    config;
     name = "coderabbit";
     supportedModes = ["local", "pr", "metrics-import"];
     capabilities = [
@@ -188,12 +202,29 @@ class CodeRabbitQcProvider {
         "auto-fix",
         "metrics-import",
     ];
+    constructor(config) {
+        this.config = config;
+    }
     canReview(scope) {
         if (scope.prUrl)
             return true;
         return Boolean(scope.branch);
     }
     buildReviewCommand(scope) {
+        const execution = this.config?.execution;
+        if (execution) {
+            const args = execution.args ? [...execution.args] : [];
+            if (execution.configPath) {
+                args.push("--config", execution.configPath);
+            }
+            if (scope.prUrl) {
+                args.push("--pr-url", scope.prUrl);
+            }
+            else {
+                args.push("--branch", scope.branch ?? "HEAD");
+            }
+            return { command: execution.command, args };
+        }
         if (scope.prUrl) {
             return { command: "coderabbit", args: ["review", "--agent", "--pr-url", scope.prUrl] };
         }
@@ -203,7 +234,8 @@ class CodeRabbitQcProvider {
         };
     }
     parse(output) {
-        const report = parseReport(output);
+        const outputConfig = this.config?.execution?.output;
+        const report = parseReport(output, outputConfig?.format, outputConfig?.parser);
         return buildResultFromReport(report, output, "local", output.exitCode !== 0);
     }
     importMetrics(payload) {

package/dist/qc/registry.js

@@ -1,16 +1,49 @@
 "use strict";
 /**
- * Default QC provider registry.
+ * QC provider registry builders.
  *
- * Registers all built-in QC adapters. In the future this can be extended to
- * discover providers from configuration or installed plugins.
+ * `createDefaultQcRegistry` returns the static built-in registry for backward
+ * compatibility. `createQcRegistry` builds a registry from polaris.config.json
+ * qc.providers, wiring provider-agnostic command/output config into the
+ * matching built-in adapters.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDefaultQcRegistry = createDefaultQcRegistry;
+exports.createQcRegistry = createQcRegistry;
 const provider_js_1 = require("./provider.js");
 const coderabbit_js_1 = require("./providers/coderabbit.js");
+function createProvider(name, config) {
+    // Only CodeRabbit is supported as a concrete provider in this child.
+    // Future providers can be registered here by name.
+    if (name === "coderabbit") {
+        return new coderabbit_js_1.CodeRabbitQcProvider(config);
+    }
+    return undefined;
+}
 function createDefaultQcRegistry() {
     const registry = new provider_js_1.QcProviderRegistry();
     registry.register(new coderabbit_js_1.CodeRabbitQcProvider());
     return registry;
 }
+/**
+ * Build a registry from configured QC providers.
+ *
+ * Disabled providers (enabled: false) are skipped. Unknown provider names are
+ * skipped; callers should validate config before dispatch and may report
+ * unknown providers as blockers at runtime.
+ */
+function createQcRegistry(config) {
+    const registry = new provider_js_1.QcProviderRegistry();
+    if (!config?.enabled) {
+        return registry;
+    }
+    for (const [name, providerConfig] of Object.entries(config.providers ?? {})) {
+        if (providerConfig.enabled === false)
+            continue;
+        const provider = createProvider(name, providerConfig);
+        if (provider) {
+            registry.register(provider);
+        }
+    }
+    return registry;
+}

package/dist/qc/repair-loop.js

@@ -0,0 +1,423 @@
+"use strict";
+/**
+ * QC repair loop orchestration.
+ *
+ * The Foreman calls `runQcRepairLoop` after a completed-cluster QC run produces
+ * findings. This module:
+ *
+ *   1. Discovers a compiled repair packet manifest for the current round.
+ *   2. Converts eligible repair packets into Foreman-dispatched repair workers.
+ *   3. Awaits repair worker completion (via sealed result files / adapter).
+ *   4. Reruns QC after all repair workers in a round have completed.
+ *   5. Loops until: pass, no repairable packets, max rounds reached,
+ *      all providers failed, operator review required, or Medic referral.
+ *
+ * Dispatch boundary: the parent/orchestrator NEVER implements repair code.
+ * Each repair packet becomes a sealed WorkerPacket with worker_role: "repair".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_REPAIR_ROUNDS = void 0;
+exports.partitionRepairPackets = partitionRepairPackets;
+exports.initRepairLoopState = initRepairLoopState;
+exports.runQcRepairLoop = runQcRepairLoop;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const repair_packets_js_1 = require("./repair-packets.js");
+const orchestration_js_1 = require("./orchestration.js");
+const store_js_1 = require("../cluster-state/store.js");
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Default maximum repair rounds when not configured. */
+exports.DEFAULT_MAX_REPAIR_ROUNDS = 2;
+// ── Helpers ────────────────────────────────────────────────────────────────────
+function appendTelemetry(telemetryFile, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+}
+/** Returns true when any finding in the results routes to repair-worker. */
+function hasRepairableFindings(results) {
+    return results.some((r) => r.findings.some((f) => (f.routingDecision === "repair-worker" || f.routingDecision === "original-worker") &&
+        f.status !== "waived" &&
+        f.status !== "autofixed" &&
+        f.status !== "repaired"));
+}
+/** Returns true when all QC providers failed in every result. */
+function allProvidersFailed(results) {
+    return (results.length > 0 &&
+        results.every((r) => r.allProvidersFailed || r.status === "failed"));
+}
+/** Returns true when any finding requires operator review. */
+function requiresOperatorReview(results) {
+    return results.some((r) => r.findings.some((f) => f.routingDecision === "operator-review" &&
+        f.status !== "waived" &&
+        f.status !== "repaired"));
+}
+/** Returns true when the QC rerun passed (no open/blocking findings). */
+function rerunPassed(results) {
+    if (results.length === 0)
+        return false;
+    return results.every((r) => r.status === "passed" || r.status === "skipped");
+}
+/** Partition packets into safe-to-parallel and must-serialize groups. */
+function partitionRepairPackets(packets) {
+    // Medic (operator-review) packets are always serialized.
+    const serialized = packets.filter((p) => p.medic || p.routingTarget === "operator-review");
+    const parallelizable = packets.filter((p) => !p.medic && p.routingTarget !== "operator-review");
+    // Group by parallelGroup assignment from the compiler.
+    const groups = new Map();
+    for (const pkt of parallelizable) {
+        const key = pkt.parallelGroup ?? `solo-${pkt.packetId}`;
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(pkt);
+    }
+    return {
+        parallelGroups: Array.from(groups.values()),
+        serialized,
+    };
+}
+/** Initialize a fresh QcRepairLoopState. */
+function initRepairLoopState(opts) {
+    const now = new Date().toISOString();
+    return {
+        current_round: 0,
+        max_rounds: opts.maxRounds,
+        source_qc_run_ids: opts.sourceQcRunIds,
+        manifest_path: null,
+        pending_packet_ids: [],
+        completed_packet_ids: [],
+        rerun_requested: false,
+        rerun_qc_run_ids: {},
+        terminal_outcome: null,
+        initiated_at: now,
+        updated_at: now,
+    };
+}
+// ── Main repair loop ───────────────────────────────────────────────────────────
+/**
+ * Run the bounded QC repair loop.
+ *
+ * The loop is Foreman-owned: it coordinates dispatch, never implements repairs.
+ * Returns deterministically on pass, no-repairable, max-rounds, all-providers-failed,
+ * operator-review, or medic-referral.
+ */
+async function runQcRepairLoop(options) {
+    const { clusterId, runId, branch, repoRoot, telemetryFile, config, registry, initialQcResults, dispatchRepairWorker, validationCommands = [], timeoutMs, maxRounds = exports.DEFAULT_MAX_REPAIR_ROUNDS, priorLoopState, onStateUpdate, } = options;
+    if (!config.enabled) {
+        const state = initRepairLoopState({
+            maxRounds,
+            sourceQcRunIds: initialQcResults.map((r) => r.qcRunId),
+        });
+        state.terminal_outcome = "qc-disabled";
+        state.updated_at = new Date().toISOString();
+        return {
+            outcome: "qc-disabled",
+            rounds_completed: 0,
+            final_qc_results: initialQcResults,
+            loop_state: state,
+            summary: "QC repair loop skipped — QC disabled by configuration",
+        };
+    }
+    const sourceRunIds = initialQcResults.map((r) => r.qcRunId);
+    let loopState = priorLoopState ?? initRepairLoopState({ maxRounds, sourceQcRunIds: sourceRunIds });
+    let currentResults = initialQcResults;
+    let roundsCompleted = loopState.current_round;
+    appendTelemetry(telemetryFile, {
+        event: "qc-repair-loop-started",
+        run_id: runId,
+        cluster_id: clusterId,
+        max_rounds: maxRounds,
+        source_qc_run_ids: sourceRunIds,
+        timestamp: new Date().toISOString(),
+    });
+    // ── Main loop ──────────────────────────────────────────────────────────────
+    while (roundsCompleted < maxRounds) {
+        const round = roundsCompleted + 1;
+        // Check exit conditions at the top of each round.
+        if (rerunPassed(currentResults) && round > 1) {
+            // A rerun already passed in this call frame — exit.
+            break;
+        }
+        if (allProvidersFailed(currentResults)) {
+            loopState = { ...loopState, terminal_outcome: "all-providers-failed", updated_at: new Date().toISOString() };
+            onStateUpdate?.(loopState);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-loop-terminal",
+                run_id: runId,
+                outcome: "all-providers-failed",
+                round,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                outcome: "all-providers-failed",
+                rounds_completed: roundsCompleted,
+                final_qc_results: currentResults,
+                loop_state: loopState,
+                summary: `QC repair loop halted: all QC providers failed at round ${round}`,
+            };
+        }
+        if (requiresOperatorReview(currentResults)) {
+            loopState = { ...loopState, terminal_outcome: "operator-review", updated_at: new Date().toISOString() };
+            onStateUpdate?.(loopState);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-loop-terminal",
+                run_id: runId,
+                outcome: "operator-review",
+                round,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                outcome: "operator-review",
+                rounds_completed: roundsCompleted,
+                final_qc_results: currentResults,
+                loop_state: loopState,
+                summary: `QC repair loop halted: unresolved operator-review findings at round ${round}`,
+            };
+        }
+        // ── Compile / discover repair packets ──────────────────────────────────
+        let manifest = null;
+        // Try to read an existing manifest for this round first (idempotent re-entry).
+        manifest = (0, repair_packets_js_1.readRepairPacketManifest)(clusterId, round, repoRoot);
+        if (!manifest) {
+            // Compile fresh repair packets from current QC results.
+            const compiled = (0, repair_packets_js_1.compileAndWriteRepairPackets)({
+                clusterId,
+                round,
+                qcResults: currentResults,
+                config,
+                validationCommands,
+                repoRoot,
+            });
+            manifest = compiled.manifest;
+            // Update cluster state with manifest path.
+            try {
+                const clusterState = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
+                if (clusterState) {
+                    const repairManifests = {
+                        ...(clusterState.qc_repair_manifests ?? {}),
+                        [round]: compiled.manifestPath,
+                    };
+                    await (0, store_js_1.writeClusterState)(clusterId, { ...clusterState, state_generation: clusterState.state_generation + 1, qc_repair_manifests: repairManifests }, repoRoot);
+                }
+            }
+            catch {
+                // Non-fatal: cluster state update is best-effort.
+            }
+            loopState = {
+                ...loopState,
+                current_round: round,
+                manifest_path: compiled.manifestPath,
+                pending_packet_ids: compiled.packets.map((p) => p.packetId),
+                updated_at: new Date().toISOString(),
+            };
+            onStateUpdate?.(loopState);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-manifest-compiled",
+                run_id: runId,
+                cluster_id: clusterId,
+                round,
+                packet_count: compiled.packets.length,
+                manifest_path: compiled.manifestPath,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        else {
+            loopState = {
+                ...loopState,
+                current_round: round,
+                manifest_path: loopState.manifest_path ?? (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "qc", "repair-rounds", String(round), "repair-packets.json"),
+                updated_at: new Date().toISOString(),
+            };
+            onStateUpdate?.(loopState);
+        }
+        // ── Check for repairable packets ────────────────────────────────────────
+        const repairablePackets = manifest.packets.filter((p) => p.routingTarget === "repair-worker" &&
+            p.status === "pending" &&
+            !loopState.completed_packet_ids.includes(p.packetId));
+        if (repairablePackets.length === 0 && !hasRepairableFindings(currentResults)) {
+            loopState = { ...loopState, terminal_outcome: "no-repairable", updated_at: new Date().toISOString() };
+            onStateUpdate?.(loopState);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-loop-terminal",
+                run_id: runId,
+                outcome: "no-repairable",
+                round,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                outcome: "no-repairable",
+                rounds_completed: roundsCompleted,
+                final_qc_results: currentResults,
+                loop_state: loopState,
+                summary: `QC repair loop: no repairable packets at round ${round}`,
+            };
+        }
+        // ── Dispatch repair workers (parallel groups, then serialized) ──────────
+        const { parallelGroups, serialized } = partitionRepairPackets(repairablePackets);
+        const allWorkerResults = [];
+        let hasMedicReferral = false;
+        // Dispatch parallel groups.
+        for (const group of parallelGroups) {
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-worker-group-start",
+                run_id: runId,
+                round,
+                parallel_group: group[0]?.parallelGroup ?? null,
+                packet_ids: group.map((p) => p.packetId),
+                timestamp: new Date().toISOString(),
+            });
+            // Within a group, packets are non-conflicting and can run concurrently.
+            const groupResults = await Promise.all(group.map((pkt) => dispatchRepairWorker(pkt, round, manifest)));
+            allWorkerResults.push(...groupResults);
+        }
+        // Dispatch serialized (medic/operator-review) packets sequentially.
+        for (const pkt of serialized) {
+            const result = await dispatchRepairWorker(pkt, round, manifest);
+            allWorkerResults.push(result);
+        }
+        // Record completed packet IDs.
+        const completedIds = allWorkerResults
+            .filter((r) => r.status !== "skipped")
+            .map((r) => r.packetId);
+        loopState = {
+            ...loopState,
+            completed_packet_ids: [...loopState.completed_packet_ids, ...completedIds],
+            pending_packet_ids: loopState.pending_packet_ids.filter((id) => !completedIds.includes(id)),
+            updated_at: new Date().toISOString(),
+        };
+        onStateUpdate?.(loopState);
+        // Check for failed repair workers → Medic referral.
+        const failedWorkers = allWorkerResults.filter((r) => r.status === "failure");
+        if (failedWorkers.length > 0) {
+            hasMedicReferral = true;
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-worker-failures",
+                run_id: runId,
+                round,
+                failed_packet_ids: failedWorkers.map((r) => r.packetId),
+                errors: failedWorkers.map((r) => r.errorMessage ?? "unknown"),
+                timestamp: new Date().toISOString(),
+            });
+        }
+        if (hasMedicReferral) {
+            loopState = { ...loopState, terminal_outcome: "medic-referral", updated_at: new Date().toISOString() };
+            onStateUpdate?.(loopState);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-loop-terminal",
+                run_id: runId,
+                outcome: "medic-referral",
+                round,
+                failed_count: failedWorkers.length,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                outcome: "medic-referral",
+                rounds_completed: roundsCompleted + 1,
+                final_qc_results: currentResults,
+                loop_state: loopState,
+                summary: `QC repair loop: ${failedWorkers.length} repair worker(s) failed at round ${round} — Medic referral triggered`,
+            };
+        }
+        roundsCompleted += 1;
+        // ── QC rerun after successful repairs ───────────────────────────────────
+        loopState = { ...loopState, rerun_requested: true, updated_at: new Date().toISOString() };
+        onStateUpdate?.(loopState);
+        appendTelemetry(telemetryFile, {
+            event: "qc-repair-rerun-start",
+            run_id: runId,
+            cluster_id: clusterId,
+            round,
+            timestamp: new Date().toISOString(),
+        });
+        const rerunOptions = {
+            config,
+            registry,
+            trigger: "completed-cluster",
+            repoRoot,
+            runId,
+            clusterId,
+            branch,
+            telemetryFile,
+            timeoutMs,
+        };
+        let rerunResult;
+        try {
+            rerunResult = await (0, orchestration_js_1.runQcAtTrigger)(rerunOptions);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-rerun-error",
+                run_id: runId,
+                round,
+                error: msg,
+                timestamp: new Date().toISOString(),
+            });
+            // Treat rerun error as all-providers-failed.
+            loopState = { ...loopState, terminal_outcome: "all-providers-failed", updated_at: new Date().toISOString() };
+            onStateUpdate?.(loopState);
+            return {
+                outcome: "all-providers-failed",
+                rounds_completed: roundsCompleted,
+                final_qc_results: currentResults,
+                loop_state: loopState,
+                summary: `QC repair loop: rerun at round ${round} threw an error: ${msg}`,
+            };
+        }
+        // Record rerun QC run IDs.
+        const rerunIds = rerunResult.results.map((r) => r.qcRunId).filter(Boolean);
+        loopState = {
+            ...loopState,
+            rerun_requested: false,
+            rerun_qc_run_ids: { ...loopState.rerun_qc_run_ids, [round]: rerunIds },
+            updated_at: new Date().toISOString(),
+        };
+        onStateUpdate?.(loopState);
+        appendTelemetry(telemetryFile, {
+            event: "qc-repair-rerun-complete",
+            run_id: runId,
+            cluster_id: clusterId,
+            round,
+            action: rerunResult.action,
+            summary: rerunResult.summary,
+            rerun_qc_run_ids: rerunIds,
+            timestamp: new Date().toISOString(),
+        });
+        currentResults = rerunResult.results;
+        // Pass condition: rerun returned no blocking findings.
+        if (rerunResult.action === "pass") {
+            loopState = { ...loopState, terminal_outcome: "pass", updated_at: new Date().toISOString() };
+            onStateUpdate?.(loopState);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-loop-terminal",
+                run_id: runId,
+                outcome: "pass",
+                round,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                outcome: "pass",
+                rounds_completed: roundsCompleted,
+                final_qc_results: currentResults,
+                loop_state: loopState,
+                summary: `QC repair loop passed after ${roundsCompleted} round(s)`,
+            };
+        }
+    }
+    // ── Max rounds exhausted ──────────────────────────────────────────────────
+    loopState = { ...loopState, terminal_outcome: "max-rounds", updated_at: new Date().toISOString() };
+    onStateUpdate?.(loopState);
+    appendTelemetry(telemetryFile, {
+        event: "qc-repair-loop-terminal",
+        run_id: runId,
+        outcome: "max-rounds",
+        rounds_completed: roundsCompleted,
+        timestamp: new Date().toISOString(),
+    });
+    return {
+        outcome: "max-rounds",
+        rounds_completed: roundsCompleted,
+        final_qc_results: currentResults,
+        loop_state: loopState,
+        summary: `QC repair loop exhausted max rounds (${maxRounds}) without passing`,
+    };
+}