@lsctech/polaris 0.5.6 → 0.5.8

package/dist/finalize/index.js

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateStateFileAuthority = validateStateFileAuthority;
+exports.validateQcRepairLoopGate = validateQcRepairLoopGate;
+exports.warnOnMissingQcArtifacts = warnOnMissingQcArtifacts;
+exports.validateAuthoritativeChildState = validateAuthoritativeChildState;
 exports.runFinalize = runFinalize;
 exports.createFinalizeCommand = createFinalizeCommand;
 const commander_1 = require("commander");
@@ -12,6 +16,7 @@ const checkpoint_js_1 = require("../loop/checkpoint.js");
 const artifact_policy_js_1 = require("./artifact-policy.js");
 const git_custody_js_1 = require("../loop/git-custody.js");
 const store_js_1 = require("../cluster-state/store.js");
+const artifacts_js_1 = require("../qc/artifacts.js");
 const canon_check_js_1 = require("../smartdocs-engine/canon-check.js");
 const _01_map_update_js_1 = require("./steps/01-map-update.js");
 const _02_map_validate_js_1 = require("./steps/02-map-validate.js");
@@ -85,6 +90,60 @@ function validateStateBranchMatchesGitBranch(stateBranch, branch) {
         process.exit(1);
     }
 }
+const CLUSTER_STATE_FILE_PATTERN = /[\\/]\.polaris[\\/]clusters[\\/][^\\/]+[\\/]state\.json$/;
+function isClusterStateSnapshotFile(filePath) {
+    return CLUSTER_STATE_FILE_PATTERN.test(filePath.replace(/\\/g, "/"));
+}
+function computeRunStateFreshness(state) {
+    const s = state;
+    let score = 0;
+    score += (s.completed_children?.length ?? 0) * 10;
+    if (s.status === "complete")
+        score += 50;
+    if (s.pr_url)
+        score += 30;
+    if (s.qc_repair_loop?.terminal_outcome)
+        score += 40;
+    score += (s.dispatch_boundary?.dispatch_epoch ?? 0) * 5;
+    score += (s.context_budget?.children_completed ?? 0) * 2;
+    return score;
+}
+/**
+ * Refuse to use a promoted cluster state snapshot when the authoritative
+ * taskchain current-state.json is newer. Cluster snapshots under
+ * `.polaris/clusters/<id>/state.json` are secondary; the taskchain state
+ * owned by the parent loop is authoritative.
+ */
+function validateStateFileAuthority(stateFile, state, repoRoot) {
+    if (!isClusterStateSnapshotFile(stateFile)) {
+        return;
+    }
+    const taskchainStateFile = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+    if (!(0, node_fs_1.existsSync)(taskchainStateFile)) {
+        return;
+    }
+    let taskchainState;
+    try {
+        taskchainState = (0, checkpoint_js_1.readState)(taskchainStateFile);
+    }
+    catch {
+        return;
+    }
+    if (taskchainState.run_id !== state.run_id ||
+        taskchainState.cluster_id !== state.cluster_id) {
+        return;
+    }
+    const taskchainFreshness = computeRunStateFreshness(taskchainState);
+    const snapshotFreshness = computeRunStateFreshness(state);
+    if (taskchainFreshness > snapshotFreshness) {
+        process.stderr.write(`finalize aborted: cluster state snapshot is stale.\n` +
+            `  Snapshot: ${stateFile}\n` +
+            `  Authoritative taskchain state: ${taskchainStateFile}\n` +
+            `The taskchain current-state.json is newer; use it instead, or ` +
+            `update the cluster snapshot before finalizing.\n`);
+        process.exit(1);
+    }
+}
 /**
  * Check that the Closeout Librarian has run and its result passes the gate.
  * Returns null if finalize may proceed; returns a human-readable blocker string if not.
@@ -183,9 +242,107 @@ function resolveQcTelemetryFile(state, repoRoot) {
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
     return (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
 }
+// ── QC repair-loop terminal state gate ────────────────────────────────────────
+/**
+ * Trusted QC repair-loop terminal outcomes that allow finalize to proceed.
+ * "pass" = QC rerun passed; "qc-disabled" = QC was off; "no-repairable" = no
+ * findings routable to repair workers (follow-up-only or already resolved).
+ */
+const TRUSTED_QC_REPAIR_OUTCOMES = new Set(["pass", "qc-disabled", "no-repairable"]);
+/**
+ * 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.
+ */
+function validateQcRepairLoopGate(state, config) {
+    // Gate only applies when QC is enabled
+    if (!config.enabled)
+        return null;
+    // Gate only applies when repair routing is active (not "log" or "block")
+    const repairRouting = config.repairRouting ?? "route";
+    if (repairRouting !== "route" && repairRouting !== "follow-up")
+        return null;
+    const repairLoop = state.qc_repair_loop;
+    // No repair-loop state at all — the completed-cluster QC trigger ran but
+    // never entered the repair loop. This is a gap: finalize should not proceed.
+    if (!repairLoop) {
+        return ("QC is enabled with repair routing active, but no qc_repair_loop state " +
+            "was found in the run state. The parent loop must run the QC repair loop " +
+            "before finalize can proceed.");
+    }
+    const outcome = repairLoop.terminal_outcome;
+    if (outcome === null || outcome === undefined) {
+        return ("QC repair loop is still in-flight (terminal_outcome is null). " +
+            "Finalize cannot proceed until the repair loop reaches a terminal state.");
+    }
+    if (TRUSTED_QC_REPAIR_OUTCOMES.has(outcome))
+        return null;
+    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.`);
+}
+// ── Authoritative completed-child state cross-check ───────────────────────────
+function warnOnMissingQcArtifacts(clusterState, repoRoot) {
+    if (!clusterState)
+        return;
+    const validation = (0, artifacts_js_1.validateQcArtifactPointers)(clusterState.qc_runs);
+    if (validation.ok)
+        return;
+    for (const missing of validation.missing) {
+        console.warn(`finalize warning: cluster-state QC pointer references missing artifact: ${missing}`);
+    }
+    for (const unavailable of validation.unavailable) {
+        console.warn(`finalize warning: QC audit artifact unavailable: ${unavailable}`);
+    }
+}
+/**
+ * Cross-check completed children in the loop state against the cluster-state
+ * child_states. Returns a diagnostic result — when `ok` is false, finalize
+ * should refuse PR creation.
+ */
+function validateAuthoritativeChildState(state, repoRoot) {
+    const clusterState = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+    const stateCount = state.completed_children.length;
+    // No cluster state available — backward-compat: trust the loop state.
+    if (!clusterState) {
+        return { ok: true, authoritativeCount: stateCount, stateCount };
+    }
+    const childStates = clusterState.child_states;
+    // No child_states array in cluster state — backward-compat: trust the loop state.
+    // This covers legacy cluster-state files that don't track individual child lifecycle.
+    if (!childStates || childStates.length === 0) {
+        return { ok: true, authoritativeCount: stateCount, stateCount };
+    }
+    const doneChildren = childStates.filter((c) => c.status === "done" || c.status === "reviewed" || c.status === "finalized");
+    const authoritativeCount = doneChildren.length;
+    // When cluster-state has tracked children but zero are done while loop state
+    // claims completions, the cluster state file is stale or was never updated.
+    if (authoritativeCount === 0 && stateCount > 0) {
+        return {
+            ok: false,
+            authoritativeCount,
+            stateCount,
+            reason: `Stale cluster state: cluster-state.json has 0 done children but ` +
+                `loop state claims ${stateCount} completed. ` +
+                `The cluster state file was never updated by worker completions.`,
+        };
+    }
+    // Significant mismatch: cluster-state has fewer done children than loop state
+    if (authoritativeCount < stateCount) {
+        return {
+            ok: false,
+            authoritativeCount,
+            stateCount,
+            reason: `Completed-child count mismatch: cluster-state has ${authoritativeCount} done ` +
+                `children but loop state has ${stateCount}. ` +
+                `The cluster state may be stale or child completions were not recorded properly.`,
+        };
+    }
+    return { ok: true, authoritativeCount, stateCount };
+}
 async function runQcGate(options) {
-    const { config, state, repoRoot, branch, trigger, prUrl, stepLabel } = options;
-    const registry = (0, index_js_2.createDefaultQcRegistry)();
+    const { config, state, repoRoot, branch, baseRef, trigger, prUrl, stepLabel } = options;
+    const registry = (0, index_js_2.createQcRegistry)(config);
     const result = await (0, index_js_2.runQcAtTrigger)({
         config,
         registry,
@@ -195,6 +352,7 @@ async function runQcGate(options) {
         runId: state.run_id,
         clusterId: state.cluster_id,
         branch,
+        baseRef,
         telemetryFile: resolveQcTelemetryFile(state, repoRoot),
         state,
     });
@@ -236,6 +394,7 @@ async function runFinalize(options) {
     validateStateFilePath(stateFile);
     validateClusterIdMatchesBranch(state.cluster_id, branch);
     validateStateBranchMatchesGitBranch(state.branch, branch);
+    validateStateFileAuthority(stateFile, state, repoRoot);
     // Step 4: Run configured checks
     const checks = config.finalize?.runChecks ?? [];
     if (checks.length > 0) {
@@ -322,6 +481,7 @@ async function runFinalize(options) {
     // loop.allowBranchDivergence is true (direct-main mode).
     {
         const clusterState = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+        warnOnMissingQcArtifacts(clusterState, repoRoot);
         const baseBranch = clusterState?.base_branch;
         const deliveryBranch = clusterState?.delivery_branch;
         const directMainMode = config.loop?.allowBranchDivergence === true;
@@ -389,14 +549,37 @@ async function runFinalize(options) {
     }
     // Step 5.8: Completed-cluster QC trigger (when configured)
     // Runs after all authoritative gates and before final commit/delivery.
+    const clusterStateForQc = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+    const qcBaseRef = clusterStateForQc?.base_branch ??
+        config.finalize?.targetBranch ??
+        "main";
     await runQcGate({
         config: config.qc,
         state,
         repoRoot,
         branch,
+        baseRef: qcBaseRef,
         trigger: "completed-cluster",
         stepLabel: "[5.8/14]",
     });
+    // Step 5.9: QC repair-loop terminal state gate
+    // 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);
+        if (repairLoopBlocker) {
+            process.stderr.write(`finalize aborted: QC repair-loop gate failed.\n${repairLoopBlocker}\n`);
+            process.exit(1);
+        }
+    }
+    // Step 5.10: Authoritative completed-child state cross-check
+    // Verify that the completed children claimed by the loop state match
+    // the cluster-state child_states. Blocks on stale or inconsistent state.
+    const authChildResult = validateAuthoritativeChildState(state, repoRoot);
+    if (!authChildResult.ok) {
+        process.stderr.write(`finalize aborted: authoritative child state mismatch.\n${authChildResult.reason}\n`);
+        process.exit(1);
+    }
     // Step 6: Tracker Reconciliation
     // LinearAdapter is sync-in only; only McpBridgeAdapter supports full reconciliation.
     const trackerType = config.tracker?.adapter;
@@ -465,7 +648,7 @@ async function runFinalize(options) {
     // Step 10: Create draft PR
     const prDraft = config.finalize?.prDraft ?? true;
     console.log("[10/14] Creating draft PR...");
-    const prUrl = (0, _08_create_pr_js_1.stepCreatePr)(repoRoot, branch, state, prDraft);
+    const prUrl = (0, _08_create_pr_js_1.stepCreatePr)(repoRoot, branch, state, prDraft, authChildResult.authoritativeCount);
     // Step 10.5: PR-required QC trigger (when configured)
     // Providers that require a PR URL run here after the PR is created.
     await runQcGate({
@@ -480,6 +663,17 @@ async function runFinalize(options) {
     // Step 11: Write PR URL to current-state.json
     console.log("[11/14] Writing PR URL to state...");
     state = (0, _09_update_state_js_1.stepUpdateState)(resolvedStateFile, state, prUrl);
+    // Promote the authoritative run state into the cluster snapshot so that
+    // `.polaris/clusters/<id>/state.json` preserves completed children, the
+    // dispatch boundary, QC repair-loop terminal state, and the PR URL.
+    try {
+        const clusterStateSnapshotPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "state.json");
+        (0, checkpoint_js_1.writeStateAtomic)(clusterStateSnapshotPath, state);
+    }
+    catch (snapshotError) {
+        process.stderr.write(`[11/14] WARNING: Failed to write cluster state snapshot: ${snapshotError instanceof Error ? snapshotError.message : String(snapshotError)}\n`);
+        process.stderr.write(`Delivery will proceed, but cluster state snapshot at .polaris/clusters/${state.cluster_id}/state.json may be incomplete.\n`);
+    }
     // Step 12: Append JSONL events
     console.log("[12/14] Appending JSONL events...");
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
@@ -489,7 +683,7 @@ async function runFinalize(options) {
     console.log("[13/14] Updating Linear...");
     const linearEnabled = config.tracker?.linear?.enabled ?? false;
     const lifecyclePolicy = config.tracker?.lifecyclePolicy;
-    await (0, _11_update_linear_js_1.stepUpdateLinear)(state, branch, prUrl, true, linearEnabled, state.cluster_id, lifecyclePolicy);
+    await (0, _11_update_linear_js_1.stepUpdateLinear)(state, branch, prUrl, true, linearEnabled, state.cluster_id, lifecyclePolicy, authChildResult.authoritativeCount);
     // Step 14: Archive run snapshot
     console.log("[14/14] Archiving run snapshot...");
     (0, _12_archive_js_1.stepArchive)(repoRoot, state, resolvedStateFile, reportPath);

package/dist/finalize/linear.js

@@ -97,6 +97,7 @@ async function findReviewState(issueId, apiKey) {
 // Comment body builder
 // ──────────────────────────────────────────────────────────────────────────────
 function buildCommentBody(opts) {
+    const childCount = opts.authoritativeChildCount ?? opts.state.completed_children.length;
     const lines = [
         `**polaris finalize complete** — run \`${opts.state.run_id}\``,
         ``,
@@ -104,7 +105,7 @@ function buildCommentBody(opts) {
         `|---|---|`,
         `| Branch | \`${opts.branch}\` |`,
         `| PR | ${opts.prUrl} |`,
-        `| Children completed | ${opts.state.completed_children.length} |`,
+        `| Children completed | ${childCount} |`,
         `| Map validation | ${opts.validationPassed ? "✓ passed" : "✗ failed"} |`,
     ];
     if (opts.reviewStateMissing) {
@@ -117,8 +118,8 @@ function buildCommentBody(opts) {
 // ──────────────────────────────────────────────────────────────────────────────
 /** Posts a finalize-complete comment without attempting a state transition. */
 async function postLinearComment(options) {
-    const { issueId, state, branch, prUrl, validationPassed, apiKey } = options;
-    const body = buildCommentBody({ state, branch, prUrl, validationPassed, reviewStateMissing: false });
+    const { issueId, state, branch, prUrl, validationPassed, apiKey, authoritativeChildCount } = options;
+    const body = buildCommentBody({ state, branch, prUrl, validationPassed, reviewStateMissing: false, authoritativeChildCount });
     const data = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
       commentCreate(input: { issueId: $issueId, body: $body }) { success }
     }`, { issueId, body }, apiKey);
@@ -140,7 +141,7 @@ async function postLinearComment(options) {
  * state ID. The assertNotDoneState guard enforces this at runtime.
  */
 async function updateLinearIssueAfterFinalize(options) {
-    const { issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy } = options;
+    const { issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy, authoritativeChildCount } = options;
     // Resolve lifecycle transition from policy
     const lifecycleTransition = (0, lifecycle_policy_js_1.resolveLifecycleTransition)("parent-all-children-complete", lifecyclePolicy);
     // If policy says skip, skip the state transition entirely
@@ -152,6 +153,7 @@ async function updateLinearIssueAfterFinalize(options) {
             prUrl,
             validationPassed,
             reviewStateMissing: false,
+            authoritativeChildCount,
         });
         const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
         commentCreate(input: { issueId: $issueId, body: $body }) { success }
@@ -172,6 +174,7 @@ async function updateLinearIssueAfterFinalize(options) {
             prUrl,
             validationPassed,
             reviewStateMissing: false,
+            authoritativeChildCount,
         });
         const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
         commentCreate(input: { issueId: $issueId, body: $body }) { success }
@@ -205,6 +208,7 @@ async function updateLinearIssueAfterFinalize(options) {
         prUrl,
         validationPassed,
         reviewStateMissing: reviewState === null,
+        authoritativeChildCount,
     });
     const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
       commentCreate(input: { issueId: $issueId, body: $body }) { success }

package/dist/finalize/steps/08-create-pr.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stepCreatePr = stepCreatePr;
 const github_js_1 = require("../github.js");
-function stepCreatePr(repoRoot, branch, state, draft) {
-    const prUrl = (0, github_js_1.createDraftPr)({ repoRoot, branch, state, draft });
+function stepCreatePr(repoRoot, branch, state, draft, authoritativeChildCount) {
+    const prUrl = (0, github_js_1.createDraftPr)({ repoRoot, branch, state, draft, authoritativeChildCount });
     console.log(`PR created: ${prUrl}`);
     return prUrl;
 }

package/dist/finalize/steps/11-update-linear.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stepUpdateLinear = stepUpdateLinear;
 const linear_js_1 = require("../linear.js");
-async function stepUpdateLinear(state, branch, prUrl, validationPassed, linearEnabled, parentIssueId, lifecyclePolicy) {
+async function stepUpdateLinear(state, branch, prUrl, validationPassed, linearEnabled, parentIssueId, lifecyclePolicy, authoritativeChildCount) {
     if (!linearEnabled) {
         console.log("[11/12] Linear integration disabled — skipping.");
         return;
@@ -17,6 +17,6 @@ async function stepUpdateLinear(state, branch, prUrl, validationPassed, linearEn
         process.stderr.write("Warning: no Linear parent issue ID — skipping Linear update.\n");
         return;
     }
-    await (0, linear_js_1.updateLinearIssueAfterFinalize)({ issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy });
+    await (0, linear_js_1.updateLinearIssueAfterFinalize)({ issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy, authoritativeChildCount });
     console.log(`Linear parent ${issueId} updated.`);
 }

package/dist/loop/parent.js

@@ -37,12 +37,15 @@ const node_child_process_1 = require("node:child_process");
 const artifact_policy_js_1 = require("../finalize/artifact-policy.js");
 const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
 const triggers_js_1 = require("../qc/triggers.js");
+const index_js_1 = require("../qc/index.js");
+const repair_loop_js_1 = require("../qc/repair-loop.js");
+const worker_packet_js_2 = require("./worker-packet.js");
 const run_bootstrap_js_1 = require("./run-bootstrap.js");
 const ledger_js_1 = require("./ledger.js");
 const dispatch_js_1 = require("./dispatch.js");
-const index_js_1 = require("./router/index.js");
+const index_js_2 = require("./router/index.js");
 const child_selector_js_1 = require("../runtime/scheduling/child-selector.js");
-const index_js_2 = require("../tracker/index.js");
+const index_js_3 = require("../tracker/index.js");
 const lifecycle_transition_js_1 = require("../tracker/lifecycle-transition.js");
 const local_graph_js_1 = require("../tracker/local-graph.js");
 const CLAIM_TTL_MS = 30 * 60 * 1000;
@@ -813,7 +816,7 @@ async function runParentLoop(options) {
         if (openChildrenNeedingScope.length > 0) {
             process.stderr.write(`[polaris] ${openChildrenNeedingScope.length} children missing scope — attempting tracker sync-in...\n`);
             try {
-                await (0, index_js_2.loadTrackerGraph)(config, state.cluster_id);
+                await (0, index_js_3.loadTrackerGraph)(config, state.cluster_id);
                 process.stderr.write(`[polaris] sync-in complete.\n`);
             }
             catch (syncErr) {
@@ -844,7 +847,7 @@ async function runParentLoop(options) {
             max_concurrent: maxConcurrentWorkers,
             claim_ttl_ms: CLAIM_TTL_MS,
             get_dependencies: (childId) => localGraph?.getDependencies(childId) ?? [],
-            decide_route: ({ activeSlotsByProvider }) => (0, index_js_1.decideWorkerRoute)({
+            decide_route: ({ activeSlotsByProvider }) => (0, index_js_2.decideWorkerRoute)({
                 role: "worker",
                 taskType: "impl",
                 adapter: adapterName,
@@ -884,6 +887,154 @@ async function runParentLoop(options) {
                 };
             }
             const autoFinalizeRequested = orchestrationMode === "auto" && config.orchestration?.auto_finalize === true;
+            // ── QC repair loop (post-completion gate) ─────────────────────────────
+            // When QC is enabled, run the completed-cluster QC trigger and, if
+            // findings are produced, run the bounded repair loop before halting.
+            // The repair loop is Foreman-owned: it dispatches repair workers via the
+            // same adapter and NEVER implements repairs inline.
+            if (!dryRun && config.qc?.enabled) {
+                const qcRegistry = (0, index_js_1.createQcRegistry)(config.qc);
+                let initialQcResult;
+                try {
+                    initialQcResult = await (0, index_js_1.runQcAtTrigger)({
+                        config: config.qc,
+                        registry: qcRegistry,
+                        trigger: "completed-cluster",
+                        repoRoot,
+                        runId: state.run_id,
+                        clusterId: state.cluster_id,
+                        branch: state.branch ?? getCurrentBranch(repoRoot),
+                        telemetryFile,
+                        state,
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    appendTelemetry(telemetryFile, {
+                        event: "qc-repair-loop-qc-run-error",
+                        run_id: state.run_id,
+                        error: msg,
+                        timestamp: new Date().toISOString(),
+                    });
+                    // Non-fatal: proceed to cluster-complete without repair loop.
+                    initialQcResult = null;
+                }
+                const hasFindings = initialQcResult !== null &&
+                    initialQcResult.results.some((r) => r.findings.length > 0 && r.status !== "passed" && r.status !== "skipped");
+                if (initialQcResult !== null && hasFindings) {
+                    const maxRepairRounds = config.qc.maxRepairRounds ?? repair_loop_js_1.DEFAULT_MAX_REPAIR_ROUNDS;
+                    const priorLoopState = state.qc_repair_loop ?? null;
+                    // Build the repair worker dispatcher using the existing adapter + provider.
+                    const repairDispatcher = async (packet, round, manifest) => {
+                        const repairPacketId = packet.packetId;
+                        const dispatchId = (0, node_crypto_1.randomUUID)();
+                        const repairWorkerId = `${state.run_id}:repair-${repairPacketId}:${Date.now()}`;
+                        const repairResultPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "results", `repair-${repairPacketId}-${dispatchId}.json`);
+                        const workerPacket = (0, worker_packet_js_2.compileRepairWorkerPacket)({
+                            runId: state.run_id,
+                            clusterId: state.cluster_id,
+                            packetId: repairPacketId,
+                            branch: state.branch ?? getCurrentBranch(repoRoot),
+                            stateFile,
+                            telemetryFile,
+                            round,
+                            allowedScope: packet.allowedScope,
+                            prohibitedScope: packet.prohibitedScope,
+                            validationCommands: packet.validationCommands,
+                            rootCauseHint: packet.rootCauseHint,
+                            resultFile: repairResultPath,
+                            maxConcurrentWorkers,
+                        });
+                        appendTelemetry(telemetryFile, {
+                            event: "repair-worker-dispatched",
+                            run_id: state.run_id,
+                            cluster_id: state.cluster_id,
+                            packet_id: repairPacketId,
+                            worker_id: repairWorkerId,
+                            round,
+                            timestamp: new Date().toISOString(),
+                        });
+                        try {
+                            const dispatchResult = await adapter.dispatch(workerPacket, { provider: providerName, dryRun });
+                            const workerSummary = parseWorkerSummary(dispatchResult.summary);
+                            const success = workerSummary?.status === "done";
+                            appendTelemetry(telemetryFile, {
+                                event: "repair-worker-completed",
+                                run_id: state.run_id,
+                                packet_id: repairPacketId,
+                                worker_id: repairWorkerId,
+                                round,
+                                status: success ? "success" : "failure",
+                                timestamp: new Date().toISOString(),
+                            });
+                            return {
+                                packetId: repairPacketId,
+                                status: success ? "success" : "failure",
+                                commitSha: workerSummary?.commit,
+                                errorMessage: success ? undefined : String(workerSummary?.error_message ?? "repair worker failed"),
+                            };
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            appendTelemetry(telemetryFile, {
+                                event: "repair-worker-error",
+                                run_id: state.run_id,
+                                packet_id: repairPacketId,
+                                worker_id: repairWorkerId,
+                                round,
+                                error: msg,
+                                timestamp: new Date().toISOString(),
+                            });
+                            return {
+                                packetId: repairPacketId,
+                                status: "failure",
+                                errorMessage: msg,
+                            };
+                        }
+                    };
+                    try {
+                        const repairLoopResult = await (0, repair_loop_js_1.runQcRepairLoop)({
+                            clusterId: state.cluster_id,
+                            runId: state.run_id,
+                            branch: state.branch ?? getCurrentBranch(repoRoot),
+                            repoRoot,
+                            telemetryFile,
+                            config: config.qc,
+                            registry: qcRegistry,
+                            initialQcResults: initialQcResult.results,
+                            dispatchRepairWorker: repairDispatcher,
+                            maxRounds: maxRepairRounds,
+                            priorLoopState,
+                            onStateUpdate: (loopState) => {
+                                // Persist loop state to the state file on each mutation.
+                                const stateWithLoop = { ...state, qc_repair_loop: loopState };
+                                (0, checkpoint_js_1.writeStateAtomic)(stateFile, stateWithLoop);
+                            },
+                        });
+                        state = { ...state, qc_repair_loop: repairLoopResult.loop_state };
+                        (0, checkpoint_js_1.writeStateAtomic)(stateFile, state);
+                        appendTelemetry(telemetryFile, {
+                            event: "qc-repair-loop-finished",
+                            run_id: state.run_id,
+                            outcome: repairLoopResult.outcome,
+                            rounds_completed: repairLoopResult.rounds_completed,
+                            summary: repairLoopResult.summary,
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        appendTelemetry(telemetryFile, {
+                            event: "qc-repair-loop-error",
+                            run_id: state.run_id,
+                            error: msg,
+                            timestamp: new Date().toISOString(),
+                        });
+                        // Non-fatal: proceed to cluster-complete.
+                    }
+                }
+            }
+            // ── End QC repair loop ─────────────────────────────────────────────────
             // All children completed — write final state and halt
             if (!dryRun) {
                 logStatus(notificationFormat, "COMPLETE");
@@ -1427,7 +1578,7 @@ async function runParentLoop(options) {
                 // Errors are logged to telemetry but do not fail the halt.
                 let adapter;
                 try {
-                    adapter = (0, index_js_2.loadTrackerAdapter)(config);
+                    adapter = (0, index_js_3.loadTrackerAdapter)(config);
                 }
                 catch (err) {
                     const errorMsg = err instanceof Error ? err.message : String(err);
@@ -1880,35 +2031,40 @@ async function runParentLoop(options) {
             };
         }
         // ── Step 05 (post-dispatch): Re-check budget before next iteration ───
-        const postBudgetCheck = (0, budget_js_1.checkBudget)({
-            childrenCompleted: state.context_budget.children_completed,
-            lastChildStatus: workerStatus,
-            policy: budgetPolicy,
-        });
-        if (postBudgetCheck.status === 'exhausted') {
-            const nextPending = state.open_children[0] ?? null;
-            if (!dryRun) {
-                (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
-                    ...state,
-                    status: "budget-exhausted",
-                    step_cursor: "budget-check",
-                    next_open_child: nextPending,
-                });
-                appendTelemetry(telemetryFile, {
-                    event: "budget-exhausted",
-                    run_id: state.run_id,
-                    children_completed: state.context_budget.children_completed,
-                    next_child: nextPending,
-                    reason: postBudgetCheck.reason,
-                    timestamp: new Date().toISOString(),
-                });
+        // Skip when open_children is empty: the cluster is complete and the
+        // top-of-loop nextChild === null path handles cluster-complete and QC
+        // repair-loop. Halting here would bypass QC repair on final-child completion.
+        if (state.open_children.length > 0) {
+            const postBudgetCheck = (0, budget_js_1.checkBudget)({
+                childrenCompleted: state.context_budget.children_completed,
+                lastChildStatus: workerStatus,
+                policy: budgetPolicy,
+            });
+            if (postBudgetCheck.status === 'exhausted') {
+                const nextPending = state.open_children[0] ?? null;
+                if (!dryRun) {
+                    (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                        ...state,
+                        status: "budget-exhausted",
+                        step_cursor: "budget-check",
+                        next_open_child: nextPending,
+                    });
+                    appendTelemetry(telemetryFile, {
+                        event: "budget-exhausted",
+                        run_id: state.run_id,
+                        children_completed: state.context_budget.children_completed,
+                        next_child: nextPending,
+                        reason: postBudgetCheck.reason,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                return {
+                    haltReason: 'budget-exhausted',
+                    childrenDispatched,
+                    haltingChild: nextPending ?? undefined,
+                    message: postBudgetCheck.reason,
+                };
             }
-            return {
-                haltReason: 'budget-exhausted',
-                childrenDispatched,
-                haltingChild: nextPending ?? undefined,
-                message: postBudgetCheck.reason,
-            };
         }
         // ── Step 06: CONTINUE (back to step 02) ─────────────────────────────
     }