@lsctech/polaris 0.5.10 → 0.5.12

package/dist/autoresearch/proposal.js

@@ -86,6 +86,28 @@ const ROUTER_FAILURE_FIX_ZONE_MAP = {
         hint: "Worker role is repeatedly disabled by policy. Update providerPolicy.worker and role routing defaults.",
     },
 };
+const ROUTER_ANOMALY_FIX_ZONE_MAP = {
+    "provider-monopoly": {
+        artifact_type: "provider-role-recommendation",
+        hint: "Repeated same-provider selection when policy evidence shows multiple providers were eligible. Review provider role assignment and policy ordering to avoid routing concentration.",
+    },
+    "missing-evidence": {
+        artifact_type: "runtime-config",
+        hint: "Routing evidence gaps detected (missing exhausted reason, router candidates, or child completion). Improve telemetry and dispatch evidence capture.",
+    },
+    "missing-sealed-result": {
+        artifact_type: "medic-template",
+        hint: "Missing sealed result file indicates a state-repair review signal. Investigate worker result writing and dispatch boundary.",
+    },
+    "stale-dispatch-abort": {
+        artifact_type: "medic-template",
+        hint: "Stale dispatch abort indicates a state-repair review signal. Investigate dispatch lifecycle and orphan recovery.",
+    },
+    "invalid-inline-attempt": {
+        artifact_type: "medic-template",
+        hint: "Invalid inline attempt indicates a state-repair review signal. Investigate dispatch boundary enforcement.",
+    },
+};
 // ──────────────────────────────────────────────
 // Build proposals from a DiagnosisReport
 // ──────────────────────────────────────────────
@@ -202,6 +224,33 @@ function buildProposals(report) {
             fix_zone: `${entry.artifact_type}/router-failure-${failure.reason}`,
         });
     }
+    // Routing anomaly signals (provider monopoly, evidence gaps, state-repair).
+    const routerOutcomes = report.router_outcomes;
+    const anomalySignals = [
+        ...(routerOutcomes?.provider_monopoly_signals ?? []),
+        ...(routerOutcomes?.evidence_gap_signals ?? []),
+        ...(routerOutcomes?.state_repair_signals ?? []),
+    ];
+    for (const signal of anomalySignals) {
+        // Evidence gaps and provider monopoly must be recurring to be worth a proposal.
+        if (signal.signal === "missing-evidence" && signal.occurrences < 2)
+            continue;
+        if (signal.signal === "provider-monopoly" && signal.occurrences < 2)
+            continue;
+        const entry = ROUTER_ANOMALY_FIX_ZONE_MAP[signal.signal] ?? {
+            artifact_type: "runtime-config",
+            hint: "Recurring routing anomaly detected. Review dispatch telemetry and routing policy.",
+        };
+        proposals.push({
+            gate_id: `router-anomaly:${signal.signal}:${signal.reason}`,
+            artifact_type: entry.artifact_type,
+            hint: `${entry.hint} Observed ${signal.occurrences} times across children: ${signal.child_ids.join(", ") || "unknown"}.`,
+            run_id: report.run_id,
+            evidence_run_ids: [report.run_id],
+            confidence: report.score,
+            fix_zone: `${entry.artifact_type}/router-anomaly-${signal.signal}`,
+        });
+    }
     return proposals;
 }
 // ──────────────────────────────────────────────
@@ -291,6 +340,15 @@ function validateDiagnosisReport(raw) {
             recurring_failures: Array.isArray(routerOutcomesRaw["recurring_failures"])
                 ? routerOutcomesRaw["recurring_failures"]
                 : [],
+            provider_monopoly_signals: Array.isArray(routerOutcomesRaw["provider_monopoly_signals"])
+                ? routerOutcomesRaw["provider_monopoly_signals"]
+                : [],
+            evidence_gap_signals: Array.isArray(routerOutcomesRaw["evidence_gap_signals"])
+                ? routerOutcomesRaw["evidence_gap_signals"]
+                : [],
+            state_repair_signals: Array.isArray(routerOutcomesRaw["state_repair_signals"])
+                ? routerOutcomesRaw["state_repair_signals"]
+                : [],
         }
         : {
             total_decisions: 0,
@@ -298,6 +356,9 @@ function validateDiagnosisReport(raw) {
             fallback_attempts: 0,
             successful_fallbacks: 0,
             recurring_failures: [],
+            provider_monopoly_signals: [],
+            evidence_gap_signals: [],
+            state_repair_signals: [],
         };
     const normalizedQcSummary = normalizeQcScoreSummary(r["qc_summary"]);
     return {

package/dist/autoresearch/score.js

@@ -24,6 +24,7 @@ exports.summarizeRouterOutcomes = summarizeRouterOutcomes;
 exports.scoreRun = scoreRun;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const routing_signals_js_1 = require("../medic/routing-signals.js");
 const artifacts_js_1 = require("../qc/artifacts.js");
 const store_js_1 = require("../cluster-state/store.js");
 const gates_js_1 = require("./gates.js");
@@ -639,12 +640,135 @@ function summarizeRouterOutcomes(artifacts) {
         child_ids: Array.from(value.childIds).sort(),
     }))
         .sort((a, b) => b.occurrences - a.occurrences || a.reason.localeCompare(b.reason));
+    // ── Provider monopoly detection ─────────────────────────────────────────────
+    // Repeated same-provider selection when policy evidence shows multiple
+    // providers were eligible or configured.
+    const hasMultiProviderEvidence = (event) => {
+        const candidates = Array.isArray(event["router_candidates"]) ? event["router_candidates"] : [];
+        const eligibleCount = candidates.filter((candidate) => asRecord(candidate)?.["eligible"] === true).length;
+        const routingSummary = asRecord(event["routing_summary"]);
+        const effectivePolicyOrder = asStringArray(routingSummary?.["effective_policy_order"]);
+        const providersTried = asStringArray(event["providers_tried"]);
+        const fallbackAttempts = Array.isArray(event["fallback_attempts"]) ? event["fallback_attempts"] : [];
+        return (eligibleCount > 1 ||
+            effectivePolicyOrder.length > 1 ||
+            providersTried.length > 1 ||
+            fallbackAttempts.length > 0 ||
+            routingSummary?.["fallback_eligible"] === true);
+    };
+    const providerSelections = new Map();
+    for (const event of selectedEvents) {
+        const selectedProvider = asString(event["selected_provider"]);
+        if (!selectedProvider || !hasMultiProviderEvidence(event))
+            continue;
+        const childId = asString(event["child_id"]) ?? undefined;
+        const existing = providerSelections.get(selectedProvider);
+        if (existing) {
+            existing.occurrences += 1;
+            if (childId)
+                existing.child_ids.push(childId);
+        }
+        else {
+            providerSelections.set(selectedProvider, {
+                signal: "provider-monopoly",
+                reason: selectedProvider,
+                occurrences: 1,
+                child_ids: childId ? [childId] : [],
+            });
+        }
+    }
+    const providerMonopolySignals = Array.from(providerSelections.values())
+        .filter((signal) => signal.occurrences >= 2)
+        .map((signal) => ({
+        ...signal,
+        child_ids: [...new Set(signal.child_ids)].sort(),
+    }))
+        .sort((a, b) => b.occurrences - a.occurrences || a.reason.localeCompare(b.reason));
+    // ── Evidence gap detection ──────────────────────────────────────────────────
+    // Missing evidence that prevents distinguishing true provider failures from
+    // routing/telemetry gaps.
+    const evidenceGapMap = new Map();
+    const countEvidenceGap = (reason, childId) => {
+        const existing = evidenceGapMap.get(reason);
+        if (existing) {
+            existing.occurrences += 1;
+            if (childId)
+                existing.child_ids.push(childId);
+        }
+        else {
+            evidenceGapMap.set(reason, {
+                signal: "missing-evidence",
+                reason,
+                occurrences: 1,
+                child_ids: childId ? [childId] : [],
+            });
+        }
+    };
+    for (const event of selectedEvents) {
+        const selectedProvider = asString(event["selected_provider"]);
+        const childId = asString(event["child_id"]) ?? undefined;
+        const candidates = Array.isArray(event["router_candidates"]) ? event["router_candidates"] : [];
+        const routingSummary = asRecord(event["routing_summary"]);
+        const fallbackAttempts = Array.isArray(event["fallback_attempts"]) ? event["fallback_attempts"] : [];
+        if (selectedProvider === null) {
+            const exhaustedReason = asString(event["router_exhausted_reason"]);
+            if (!exhaustedReason && candidates.length === 0) {
+                countEvidenceGap("missing-exhausted-reason", childId);
+            }
+        }
+        else if (selectedProvider !== null) {
+            const registryPresent = routingSummary?.["registry_present"] === true;
+            if (registryPresent && candidates.length === 0) {
+                countEvidenceGap("missing-router-candidates", childId);
+            }
+            if (fallbackAttempts.length > 0 && childId && !childCompletionStatus.has(childId)) {
+                countEvidenceGap("missing-child-completion", childId);
+            }
+        }
+    }
+    for (const event of exhaustedEvents) {
+        const childId = asString(event["child_id"]) ?? undefined;
+        const reason = asString(event["reason"]);
+        if (!reason && childId) {
+            countEvidenceGap("missing-exhausted-reason", childId);
+        }
+    }
+    const evidenceGapSignals = Array.from(evidenceGapMap.values())
+        .map((signal) => ({
+        ...signal,
+        child_ids: [...new Set(signal.child_ids)].sort(),
+    }))
+        .sort((a, b) => b.occurrences - a.occurrences || a.reason.localeCompare(b.reason));
+    // ── State-repair / Medic review signal classification ───────────────────────
+    const stateRepairMap = new Map();
+    for (const event of telemetry) {
+        const classified = (0, routing_signals_js_1.classifyRoutingTelemetryEvent)(event);
+        if (!classified)
+            continue;
+        const existing = stateRepairMap.get(classified.signal);
+        if (existing) {
+            existing.occurrences += classified.occurrences;
+            existing.child_ids.push(...classified.child_ids);
+        }
+        else {
+            stateRepairMap.set(classified.signal, { ...classified });
+        }
+    }
+    const stateRepairSignals = Array.from(stateRepairMap.values())
+        .map((signal) => ({
+        ...signal,
+        child_ids: [...new Set(signal.child_ids)].sort(),
+    }))
+        .sort((a, b) => b.occurrences - a.occurrences || a.signal.localeCompare(b.signal));
     return {
         total_decisions: selectedEvents.length,
         exhausted_decisions: exhaustedEvents.length,
         fallback_attempts: fallbackEvents.length,
         successful_fallbacks: successfulFallbacks,
         recurring_failures: recurringFailures,
+        provider_monopoly_signals: providerMonopolySignals,
+        evidence_gap_signals: evidenceGapSignals,
+        state_repair_signals: stateRepairSignals,
     };
 }
 // ──────────────────────────────────────────────

package/dist/cli/index.js

@@ -25,6 +25,7 @@ const graph_js_1 = require("./graph.js");
 const index_js_7 = require("../skill-packet/index.js");
 const librarian_js_1 = require("./librarian.js");
 const medic_js_1 = require("./medic.js");
+const qc_js_1 = require("./qc.js");
 const welfare_js_1 = require("../map/welfare.js");
 const adopt_command_js_1 = require("./adopt-command.js");
 const upgrade_command_js_1 = require("./upgrade-command.js");
@@ -127,6 +128,9 @@ function createPolarisCommand(options = {}) {
     program.addCommand((0, medic_js_1.createMedicCommand)({
         repoRoot,
     }));
+    program.addCommand((0, qc_js_1.createQcCommand)({
+        repoRoot,
+    }));
     program.addCommand((0, adopt_command_js_1.createAdoptCommand)({ repoRoot }));
     program.addCommand((0, upgrade_command_js_1.createUpgradeCommand)({ repoRoot }));
     program.addCommand((0, autoresearch_js_1.createSolCommand)({ repoRoot }));

package/dist/cli/qc.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createQcCommand = createQcCommand;
+const commander_1 = require("commander");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const types_js_1 = require("../qc/types.js");
+const repair_loop_js_1 = require("../qc/repair-loop.js");
+const repair_packets_js_1 = require("../qc/repair-packets.js");
+function createQcCommand(options = {}) {
+    const repoRootDefault = options.repoRoot ?? (0, node_path_1.resolve)(process.cwd());
+    const qc = new commander_1.Command("qc")
+        .description("QC role tools")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    qc
+        .command("resolve")
+        .description("Record a formal operator resolution for a QC repair-loop terminal state")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .requiredOption("--cluster-id <id>", "Cluster ID to resolve")
+        .requiredOption("--outcome <outcome>", "Resolved outcome (pass or no-repairable)")
+        .requiredOption("--reason <text>", "Reason for the resolution")
+        .option("--findings <ids>", "Comma-separated finding IDs covered by this resolution (defaults to all in the round manifest)")
+        .action((cmdOptions) => {
+        try {
+            resolveQcRepairLoop({
+                repoRoot: cmdOptions.repoRoot,
+                clusterId: cmdOptions.clusterId,
+                outcome: cmdOptions.outcome,
+                reason: cmdOptions.reason,
+                findings: cmdOptions.findings,
+            });
+        }
+        catch (err) {
+            process.stderr.write(`qc resolve error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    return qc;
+}
+function resolveQcRepairLoop(options) {
+    const { repoRoot, clusterId, outcome, reason, findings } = options;
+    const allowedOutcomes = new Set(types_js_1.QC_RESOLUTION_OUTCOMES);
+    if (!allowedOutcomes.has(outcome)) {
+        throw new Error(`Invalid outcome "${outcome}". Must be one of: ${types_js_1.QC_RESOLUTION_OUTCOMES.join(", ")}.`);
+    }
+    const resolvedReason = reason.trim();
+    if (resolvedReason === "") {
+        throw new Error("A non-empty --reason is required to record a resolution.");
+    }
+    const round = findCurrentRepairRound(repoRoot, clusterId);
+    if (round === null) {
+        throw new Error(`No repair-round manifest found for cluster ${clusterId}. Run the QC repair loop first.`);
+    }
+    const manifest = (0, repair_packets_js_1.readRepairPacketManifest)(clusterId, round, repoRoot);
+    if (!manifest) {
+        throw new Error(`Repair packet manifest for cluster ${clusterId} round ${round} is missing or invalid.`);
+    }
+    const explicitFindings = findings
+        ? findings
+            .split(",")
+            .map((id) => id.trim())
+            .filter(Boolean)
+        : undefined;
+    const resolvedFindings = (0, repair_loop_js_1.resolveQcResolutionFindings)(manifest, explicitFindings);
+    const resolver = (0, repair_loop_js_1.getResolverIdentity)(repoRoot);
+    const artifactPath = (0, repair_loop_js_1.writeQcResolutionArtifact)({
+        clusterId,
+        round,
+        resolver,
+        resolvedOutcome: outcome,
+        reason: resolvedReason,
+        findings: resolvedFindings,
+        repoRoot,
+    });
+    process.stdout.write(`Created resolution artifact: ${artifactPath}\n` +
+        `Resolved outcome: ${outcome}\n` +
+        `Resolved findings: ${resolvedFindings.join(", ") || "none"}\n`);
+}
+function findCurrentRepairRound(repoRoot, clusterId) {
+    const roundsDir = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "qc", "repair-rounds");
+    if (!(0, node_fs_1.existsSync)(roundsDir)) {
+        return null;
+    }
+    const entries = (0, node_fs_1.readdirSync)(roundsDir, { withFileTypes: true });
+    const rounds = entries
+        .filter((e) => e.isDirectory() && /^\d+$/.test(e.name))
+        .map((e) => Number(e.name))
+        .sort((a, b) => b - a);
+    for (const round of rounds) {
+        const manifestPath = (0, node_path_1.join)(roundsDir, String(round), "repair-packets.json");
+        if ((0, node_fs_1.existsSync)(manifestPath)) {
+            return round;
+        }
+    }
+    return null;
+}

package/dist/config/validator.js

@@ -364,13 +364,23 @@ function validateConfig(config) {
                             result.valid = false;
                             result.errors.push(`execution.providerPolicy.${roleName}.providers must be an array of strings`);
                         }
-                        else if (providerKeys) {
-                            for (const providerName of rolePolicy.providers) {
-                                if (!providerKeys.has(providerName)) {
-                                    result.valid = false;
-                                    result.errors.push(`execution.providerPolicy.${roleName}.providers contains unknown provider: ${providerName}`);
+                        else {
+                            if (providerKeys) {
+                                for (const providerName of rolePolicy.providers) {
+                                    if (!providerKeys.has(providerName)) {
+                                        result.valid = false;
+                                        result.errors.push(`execution.providerPolicy.${roleName}.providers contains unknown provider: ${providerName}`);
+                                    }
                                 }
                             }
+                            const routerPolicyObj = isPlainObject(config.execution.routerPolicy)
+                                ? config.execution.routerPolicy
+                                : undefined;
+                            const providerRegistry = routerPolicyObj?.providerRegistry;
+                            const hasRegistry = isPlainObject(providerRegistry) && Object.keys(providerRegistry).length > 0;
+                            if (!hasRegistry && rolePolicy.providers.length > 1) {
+                                result.warnings.push(`execution.providerPolicy.${roleName}.providers lists multiple providers but execution.routerPolicy.providerRegistry is missing or empty; dispatch will use compatibility mode and only the selected provider will appear in providers_tried`);
+                            }
                         }
                         if ("allowNativeSubagent" in rolePolicy && rolePolicy.allowNativeSubagent !== undefined && !isBoolean(rolePolicy.allowNativeSubagent)) {
                             result.valid = false;
@@ -993,7 +1003,7 @@ function validateConfig(config) {
                                 result.errors.push(`qc.providers.${providerName}.failurePolicy must be a plain object`);
                             }
                             else {
-                                for (const key of ["timeout", "parseFailure", "allProvidersFailed"]) {
+                                for (const key of ["timeout", "parseFailure", "rateLimited", "allProvidersFailed"]) {
                                     const value = providerConfig.failurePolicy[key];
                                     if (value !== undefined && (!isString(value) || !SUPPORTED_QC_FAILURE_ACTIONS.includes(value))) {
                                         result.valid = false;

package/dist/finalize/artifact-policy.js

@@ -20,8 +20,27 @@ const PROMOTED_MAP_PREFIX = ".polaris/map/";
 const WORKSPACE_SCRATCH_PREFIX = ".taskchain_artifacts/";
 const LEGACY_RUN_ARTIFACTS = new Set([
     ".polaris/runs/mutation-queue.json",
+    ".polaris/runs/current-state.json",
+    ".polaris/runs/run-report.md",
     ".polaris/runs/current-state.pre-pol-198.json",
 ]);
+function isPromotedRunArchivePath(relativePath) {
+    if (!relativePath.startsWith(".polaris/runs/")) {
+        return false;
+    }
+    const rest = relativePath.slice(".polaris/runs/".length);
+    if (rest === "" || rest === "evo-run-archive") {
+        return false;
+    }
+    const slashIndex = rest.indexOf("/");
+    if (slashIndex === -1) {
+        // The path is a directory-style run archive path (e.g. `.polaris/runs/<run-id>`),
+        // not a top-level file like `ledger.jsonl`.
+        return !rest.includes(".") && !rest.startsWith(".");
+    }
+    const firstSegment = rest.slice(0, slashIndex);
+    return firstSegment !== "evo-run-archive";
+}
 function normalizeArtifactPath(filePath) {
     const normalized = node_path_1.default.posix.normalize(filePath.replace(/\\/g, "/"));
     return normalized.startsWith("./") ? normalized.slice(2) : normalized;
@@ -59,6 +78,9 @@ function classifyArtifactPath(filePath, activeClusterId) {
     if (relativePath === PROMOTED_RUN_LEDGER) {
         return "promoted-run-ledger";
     }
+    if (isPromotedRunArchivePath(relativePath)) {
+        return "promoted-run-archive";
+    }
     if (relativePath.startsWith(PROMOTED_COGNITION_ARCHIVE_PREFIX)) {
         return "promoted-cognition-archive";
     }
@@ -80,6 +102,7 @@ function isPromotedArtifactPath(filePath, activeClusterId) {
     const classification = classifyArtifactPath(filePath, activeClusterId);
     return (classification === "promoted-cluster-artifact"
         || classification === "promoted-run-ledger"
+        || classification === "promoted-run-archive"
         || classification === "promoted-cognition-archive"
         || classification === "promoted-map-artifact");
 }
@@ -91,6 +114,8 @@ function explainArtifactPolicy(filePath, activeClusterId) {
             return "active cluster evidence is eligible for promotion into finalize commits";
         case "promoted-run-ledger":
             return "the run ledger is durable audit evidence and stays commit-eligible";
+        case "promoted-run-archive":
+            return "archived run snapshots under .polaris/runs/<run-id>/ are durable audit evidence and stay commit-eligible";
         case "promoted-cognition-archive":
             return "archived cognition reconciliation notes are durable provenance and stay commit-eligible";
         case "promoted-map-artifact":
@@ -114,6 +139,7 @@ function findArtifactPromotionViolations(stagedPaths, activeClusterId) {
         if (classification === "non-artifact"
             || classification === "promoted-cluster-artifact"
             || classification === "promoted-run-ledger"
+            || classification === "promoted-run-archive"
             || classification === "promoted-cognition-archive"
             || classification === "promoted-map-artifact") {
             continue;
@@ -143,9 +169,11 @@ function getArtifactPromotionPolicy(activeClusterId) {
         blocked: [
             `${WORKSPACE_SCRATCH_PREFIX}**`,
             "*.bak",
-            ".polaris/runs/mutation-queue.json",
-            ".polaris/runs/current-state.pre-pol-198.json",
+            ...LEGACY_RUN_ARTIFACTS,
             ".polaris/runs/evo-run-archive/**",
+            ".polaris/bootstrap/**",
+            ".polaris/session-type",
+            ".polaris/tmp/**",
             ".polaris/clusters/<other-cluster>/**",
         ],
     };
@@ -163,10 +191,13 @@ function getGitignorePatterns() {
         ".taskchain_artifacts/**",
         "*.bak",
         ".polaris/runs/mutation-queue.json",
+        ".polaris/runs/current-state.json",
+        ".polaris/runs/run-report.md",
         ".polaris/runs/current-state.pre-pol-198.json",
         ".polaris/runs/evo-run-archive/**",
         ".polaris/bootstrap/**",
         ".polaris/session-type",
+        ".polaris/tmp/**",
         "# Cognition staging — ephemeral, not committed",
         ".polaris/cognition/pending/**",
     ];
@@ -200,7 +231,8 @@ function isPathBlockedFromStaging(filePath) {
     if (relativePath === ".polaris/runs/mutation-queue.json" ||
         relativePath === ".polaris/runs/current-state.pre-pol-198.json" ||
         relativePath.startsWith(".polaris/bootstrap/") ||
-        relativePath === ".polaris/session-type") {
+        relativePath === ".polaris/session-type" ||
+        relativePath.startsWith(".polaris/tmp/")) {
         return true;
     }
     // Block cognition pending staging

package/dist/finalize/index.js

@@ -259,8 +259,12 @@ const TRUSTED_QC_REPAIR_OUTCOMES = new Set(["pass", "qc-disabled", "no-repairabl
  * Validate QC repair-loop terminal state when QC is enabled and repair routing
  * is active. Returns null when finalize may proceed; returns a human-readable
  * blocker string otherwise.
+ *
+ * A valid operator resolution artifact for the current repair round is accepted
+ * as equivalent to a trusted terminal_outcome; finalize does not mutate the
+ * loop state.
  */
-function validateQcRepairLoopGate(state, config) {
+function validateQcRepairLoopGate(state, config, repoRoot) {
     // Gate only applies when QC is enabled
     if (!config.enabled)
         return null;
@@ -283,9 +287,24 @@ function validateQcRepairLoopGate(state, config) {
     }
     if (TRUSTED_QC_REPAIR_OUTCOMES.has(outcome))
         return null;
+    // A valid operator resolution artifact for the current round overrides the
+    // untrusted terminal_outcome without mutating state.qc_repair_loop.
+    if (repoRoot &&
+        repairLoop.current_round &&
+        repairLoop.current_round > 0) {
+        const resolution = (0, index_js_2.readQcResolutionArtifact)(state.cluster_id, repairLoop.current_round, repoRoot);
+        if (resolution &&
+            TRUSTED_QC_REPAIR_OUTCOMES.has(resolution.resolvedOutcome)) {
+            return null;
+        }
+    }
+    const resolutionHint = outcome === "operator-review" || outcome === "medic-referral"
+        ? ` Resolve with: polaris qc resolve --cluster-id ${state.cluster_id} --outcome <pass|no-repairable> --reason "<text>" [--findings <id1,id2,...>].`
+        : "";
     return (`QC repair loop terminated with untrusted outcome: "${outcome}". ` +
         `Only ${Array.from(TRUSTED_QC_REPAIR_OUTCOMES).join(", ")} outcomes allow finalize to proceed. ` +
-        `Resolve the repair loop before re-running finalize.`);
+        `A valid resolution artifact for the current round is also accepted.` +
+        resolutionHint);
 }
 // ── Authoritative completed-child state cross-check ───────────────────────────
 function warnOnMissingQcArtifacts(clusterState, repoRoot) {
@@ -546,7 +565,7 @@ async function runCompletedClusterQcWithRepair(options) {
             repoRoot,
         });
     }
-    const repairLoopBlocker = validateQcRepairLoopGate(nextState, config.qc);
+    const repairLoopBlocker = validateQcRepairLoopGate(nextState, config.qc, repoRoot);
     if (repairLoopBlocker) {
         process.stderr.write(`${stepLabel} QC completed-cluster blocked finalize: ${qcResult.summary}\n` +
             `${repairLoopBlocker}\n`);
@@ -754,7 +773,7 @@ async function runFinalize(options) {
     // When QC is enabled and repair routing is active, require a trusted
     // terminal outcome from the QC repair loop before allowing PR creation.
     {
-        const repairLoopBlocker = validateQcRepairLoopGate(state, config.qc);
+        const repairLoopBlocker = validateQcRepairLoopGate(state, config.qc, repoRoot);
         if (repairLoopBlocker) {
             process.stderr.write(`finalize aborted: QC repair-loop gate failed.\n${repairLoopBlocker}\n`);
             process.exit(1);