@lsctech/polaris 0.5.8 → 0.5.10

package/dist/config/defaults.js

@@ -55,6 +55,9 @@ exports.DEFAULT_CONFIG = {
         requireMapValidation: true,
         requireSchemaValidation: true,
         archiveRunSnapshot: true,
+        medic: {
+            bypassPolicy: "none",
+        },
     },
     tracker: {
         lifecyclePolicy: {
@@ -120,5 +123,6 @@ exports.DEFAULT_CONFIG = {
         },
         routes: {},
         maxRepairRounds: 2,
+        repairDispatchTimeoutMs: 1_800_000,
     },
 };

package/dist/config/validator.js

@@ -548,6 +548,20 @@ function validateConfig(config) {
                     result.errors.push("finalize.archiveRunSnapshot must be a boolean");
                 }
             }
+            if ("medic" in config.finalize && config.finalize.medic !== undefined) {
+                if (!isPlainObject(config.finalize.medic)) {
+                    result.valid = false;
+                    result.errors.push("finalize.medic must be an object");
+                }
+                else {
+                    if ("bypassPolicy" in config.finalize.medic && config.finalize.medic.bypassPolicy !== undefined) {
+                        if (!isString(config.finalize.medic.bypassPolicy) || !["none", "cli"].includes(config.finalize.medic.bypassPolicy)) {
+                            result.valid = false;
+                            result.errors.push('finalize.medic.bypassPolicy must be one of "none" or "cli"');
+                        }
+                    }
+                }
+            }
         }
     }
     // tracker
@@ -1197,6 +1211,128 @@ function validateConfig(config) {
             }
         }
     }
+    // run_health
+    if ("run_health" in config && config.run_health !== undefined) {
+        if (!isPlainObject(config.run_health)) {
+            result.valid = false;
+            result.errors.push("run_health must be an object");
+        }
+        else {
+            if ("foreman_symptoms" in config.run_health && config.run_health.foreman_symptoms !== undefined) {
+                if (!isPlainObject(config.run_health.foreman_symptoms)) {
+                    result.valid = false;
+                    result.errors.push("run_health.foreman_symptoms must be an object");
+                }
+                else {
+                    if ("enabled" in config.run_health.foreman_symptoms && config.run_health.foreman_symptoms.enabled !== undefined) {
+                        if (!isBoolean(config.run_health.foreman_symptoms.enabled)) {
+                            result.valid = false;
+                            result.errors.push("run_health.foreman_symptoms.enabled must be a boolean");
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // sol
+    if ("sol" in config && config.sol !== undefined) {
+        if (!isPlainObject(config.sol)) {
+            result.valid = false;
+            result.errors.push("sol must be an object");
+        }
+        else {
+            if ("history" in config.sol && config.sol.history !== undefined) {
+                if (!isPlainObject(config.sol.history)) {
+                    result.valid = false;
+                    result.errors.push("sol.history must be an object");
+                }
+                else {
+                    if ("enabled" in config.sol.history && config.sol.history.enabled !== undefined) {
+                        if (!isBoolean(config.sol.history.enabled)) {
+                            result.valid = false;
+                            result.errors.push("sol.history.enabled must be a boolean");
+                        }
+                    }
+                    if ("path" in config.sol.history && config.sol.history.path !== undefined) {
+                        if (!isString(config.sol.history.path)) {
+                            result.valid = false;
+                            result.errors.push("sol.history.path must be a string");
+                        }
+                    }
+                }
+            }
+            if ("thresholds" in config.sol && config.sol.thresholds !== undefined) {
+                if (!isPlainObject(config.sol.thresholds)) {
+                    result.valid = false;
+                    result.errors.push("sol.thresholds must be an object");
+                }
+                else {
+                    if ("enabled" in config.sol.thresholds && config.sol.thresholds.enabled !== undefined) {
+                        if (!isBoolean(config.sol.thresholds.enabled)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.enabled must be a boolean");
+                        }
+                    }
+                    if ("policy" in config.sol.thresholds && config.sol.thresholds.policy !== undefined) {
+                        if (!isPlainObject(config.sol.thresholds.policy)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.policy must be an object");
+                        }
+                        else {
+                            if ("createRunHealthReport" in config.sol.thresholds.policy && config.sol.thresholds.policy.createRunHealthReport !== undefined) {
+                                if (!isBoolean(config.sol.thresholds.policy.createRunHealthReport)) {
+                                    result.valid = false;
+                                    result.errors.push("sol.thresholds.policy.createRunHealthReport must be a boolean");
+                                }
+                            }
+                            if ("requireMedic" in config.sol.thresholds.policy && config.sol.thresholds.policy.requireMedic !== undefined) {
+                                if (!isBoolean(config.sol.thresholds.policy.requireMedic)) {
+                                    result.valid = false;
+                                    result.errors.push("sol.thresholds.policy.requireMedic must be a boolean");
+                                }
+                            }
+                        }
+                    }
+                    if ("low_composite_score" in config.sol.thresholds && config.sol.thresholds.low_composite_score !== undefined) {
+                        if (!isNumber(config.sol.thresholds.low_composite_score) || !inRange(config.sol.thresholds.low_composite_score, 0, 1)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.low_composite_score must be a number between 0 and 1");
+                        }
+                    }
+                    if ("qc_repair_loop_failure_statuses" in config.sol.thresholds && config.sol.thresholds.qc_repair_loop_failure_statuses !== undefined) {
+                        if (!isStringArray(config.sol.thresholds.qc_repair_loop_failure_statuses)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.qc_repair_loop_failure_statuses must be an array of strings");
+                        }
+                    }
+                    if ("repeated_provider_failures" in config.sol.thresholds && config.sol.thresholds.repeated_provider_failures !== undefined) {
+                        if (!isPositiveInteger(config.sol.thresholds.repeated_provider_failures)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.repeated_provider_failures must be a positive integer");
+                        }
+                    }
+                    if ("foreman_intervention_count" in config.sol.thresholds && config.sol.thresholds.foreman_intervention_count !== undefined) {
+                        if (!isNonNegativeInteger(config.sol.thresholds.foreman_intervention_count)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.foreman_intervention_count must be a non-negative integer");
+                        }
+                    }
+                    if ("stale_wrong_run_telemetry" in config.sol.thresholds && config.sol.thresholds.stale_wrong_run_telemetry !== undefined) {
+                        if (!isBoolean(config.sol.thresholds.stale_wrong_run_telemetry)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.stale_wrong_run_telemetry must be a boolean");
+                        }
+                    }
+                    if ("validation_failures" in config.sol.thresholds && config.sol.thresholds.validation_failures !== undefined) {
+                        if (!isNonNegativeInteger(config.sol.thresholds.validation_failures)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.validation_failures must be a non-negative integer");
+                        }
+                    }
+                }
+            }
+        }
+    }
     // unknown top-level fields -> warnings
     const knownKeys = new Set([
         "version",
@@ -1213,6 +1349,11 @@ function validateConfig(config) {
         "budget",
         "compact",
         "qc",
+        "sol",
+        "run_health",
+        "orchestration",
+        "skill_packet",
+        "simplicity",
     ]);
     for (const key of Object.keys(config)) {
         if (!knownKeys.has(key)) {

package/dist/finalize/index.js

@@ -7,6 +7,7 @@ exports.validateAuthoritativeChildState = validateAuthoritativeChildState;
 exports.runFinalize = runFinalize;
 exports.createFinalizeCommand = createFinalizeCommand;
 const commander_1 = require("commander");
+const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
@@ -34,7 +35,12 @@ const local_graph_js_1 = require("../tracker/local-graph.js");
 const index_js_1 = require("../tracker/sync/index.js");
 const finalize_evidence_js_1 = require("../loop/finalize-evidence.js");
 const delivery_integrity_js_1 = require("./delivery-integrity.js");
+const medic_gate_js_1 = require("./medic-gate.js");
+const qc_escalation_js_1 = require("../run-health/qc-escalation.js");
 const index_js_2 = require("../qc/index.js");
+const worker_packet_js_1 = require("../loop/worker-packet.js");
+const registry_js_1 = require("../loop/adapters/registry.js");
+const dispatch_js_1 = require("../loop/dispatch.js");
 function getBranch(repoRoot) {
     try {
         return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
@@ -367,8 +373,190 @@ async function runQcGate(options) {
     process.stderr.write(`${stepLabel} QC ${trigger} blocked finalize: ${result.summary}\n`);
     process.exit(1);
 }
+function parseWorkerSummary(summary) {
+    if (!summary)
+        return null;
+    try {
+        const parsed = JSON.parse(summary);
+        if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function runCompletedClusterQcWithRepair(options) {
+    const { config, state, stateFile, repoRoot, branch, baseRef, stepLabel } = options;
+    const registry = (0, index_js_2.createQcRegistry)(config.qc);
+    const qcResult = await (0, index_js_2.runQcAtTrigger)({
+        config: config.qc,
+        registry,
+        trigger: "completed-cluster",
+        repoRoot,
+        runId: state.run_id,
+        clusterId: state.cluster_id,
+        branch,
+        baseRef,
+        telemetryFile: resolveQcTelemetryFile(state, repoRoot),
+        state,
+    });
+    if (qcResult.action === "pass") {
+        const maxRounds = config.qc.maxRepairRounds ?? index_js_2.DEFAULT_MAX_REPAIR_ROUNDS;
+        const sourceQcRunIds = qcResult.results.map((r) => r.qcRunId).filter(Boolean);
+        const existingLoop = state.qc_repair_loop;
+        const now = new Date().toISOString();
+        const passLoopState = existingLoop
+            ? {
+                ...existingLoop,
+                terminal_outcome: existingLoop.terminal_outcome ?? "pass",
+                updated_at: existingLoop.terminal_outcome == null ? now : (existingLoop.updated_at ?? now),
+            }
+            : {
+                ...(0, index_js_2.initRepairLoopState)({ maxRounds, sourceQcRunIds }),
+                terminal_outcome: "pass",
+                updated_at: now,
+            };
+        const passedState = { ...state, qc_repair_loop: passLoopState };
+        (0, checkpoint_js_1.writeStateAtomic)(stateFile, passedState);
+        console.log(`${stepLabel} QC completed-cluster passed: ${qcResult.summary}`);
+        return passedState;
+    }
+    // Append QC escalation symptoms for the initial non-passing completed-cluster QC result.
+    if (qcResult.results.length > 0) {
+        (0, qc_escalation_js_1.appendQcEscalationSymptoms)({
+            runId: state.run_id,
+            clusterId: state.cluster_id,
+            qcResults: qcResult.results,
+            afterRepair: false,
+            repoRoot,
+        });
+    }
+    const repairRouting = config.qc.repairRouting ?? "route";
+    if (repairRouting !== "route" && repairRouting !== "follow-up") {
+        process.stderr.write(`${stepLabel} QC completed-cluster blocked finalize: ${qcResult.summary}\n`);
+        process.exit(1);
+    }
+    const adapterName = config.execution?.adapter ?? "terminal-cli";
+    let providerName;
+    if (adapterName === "agent-subtask") {
+        providerName = "agent-subtask";
+    }
+    else {
+        try {
+            const providerEvidence = (0, dispatch_js_1.resolveProviderAndMode)({ stateFile, repoRoot }, "worker", config);
+            providerName = providerEvidence.provider ?? "default";
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`${stepLabel} QC repair loop provider resolution failed: ${msg}\n`);
+            process.exit(1);
+        }
+    }
+    const executionConfig = adapterName === "agent-subtask"
+        ? { ...(config.execution ?? { providers: {} }), adapter: "agent-subtask" }
+        : config.execution ?? { adapter: adapterName, providers: {} };
+    const adapter = (0, registry_js_1.createAdapter)(adapterName, executionConfig);
+    const maxConcurrentWorkers = config.execution?.routerPolicy?.defaultWorkerPool?.maxActiveWorkers ?? 1;
+    const telemetryFile = resolveQcTelemetryFile(state, repoRoot);
+    let nextState = state;
+    const repairDispatcher = async (packet, round, manifest, signal) => {
+        const dispatchId = (0, node_crypto_1.randomUUID)();
+        const repairResultPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", nextState.cluster_id, "results", `repair-${packet.packetId}-${dispatchId}.json`);
+        const workerPacket = (0, worker_packet_js_1.compileRepairWorkerPacket)({
+            runId: nextState.run_id,
+            clusterId: nextState.cluster_id,
+            packetId: packet.packetId,
+            branch,
+            stateFile,
+            telemetryFile,
+            round,
+            allowedScope: packet.allowedScope,
+            prohibitedScope: packet.prohibitedScope,
+            validationCommands: packet.validationCommands,
+            rootCauseHint: packet.rootCauseHint,
+            resultFile: repairResultPath,
+            maxConcurrentWorkers,
+        });
+        try {
+            // TODO: Propagate AbortSignal to adapter.dispatch() once ExecutionAdapter
+            // interface supports cancellation. Current limitation: timeout abandons the
+            // Promise but doesn't terminate the spawned worker process.
+            if (signal?.aborted) {
+                throw signal.reason || new Error("Repair dispatch aborted");
+            }
+            const dispatchResult = await adapter.dispatch(workerPacket, { provider: providerName });
+            const workerSummary = parseWorkerSummary(dispatchResult.summary);
+            const success = workerSummary?.status === "done";
+            const commitSha = workerSummary && typeof workerSummary["commit"] === "string"
+                ? workerSummary["commit"]
+                : undefined;
+            const errorMessage = workerSummary && typeof workerSummary["error_message"] === "string"
+                ? workerSummary["error_message"]
+                : "repair worker failed";
+            return {
+                packetId: packet.packetId,
+                status: success ? "success" : "failure",
+                commitSha,
+                errorMessage: success ? undefined : errorMessage,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                packetId: packet.packetId,
+                status: "failure",
+                errorMessage: msg,
+            };
+        }
+    };
+    const repairLoopResult = await (0, index_js_2.runQcRepairLoop)({
+        clusterId: nextState.cluster_id,
+        runId: nextState.run_id,
+        branch,
+        repoRoot,
+        telemetryFile,
+        config: config.qc,
+        registry,
+        initialQcResults: qcResult.results,
+        dispatchRepairWorker: repairDispatcher,
+        maxRounds: config.qc.maxRepairRounds ?? index_js_2.DEFAULT_MAX_REPAIR_ROUNDS,
+        priorLoopState: nextState.qc_repair_loop ?? null,
+        onStateUpdate: (loopState) => {
+            nextState = { ...nextState, qc_repair_loop: loopState };
+            (0, checkpoint_js_1.writeStateAtomic)(stateFile, nextState);
+        },
+    });
+    nextState = { ...nextState, qc_repair_loop: repairLoopResult.loop_state };
+    (0, checkpoint_js_1.writeStateAtomic)(stateFile, nextState);
+    // Append QC escalation symptoms for non-passing repair-loop outcomes and post-repair findings.
+    (0, qc_escalation_js_1.appendRepairLoopOutcomeSymptom)({
+        runId: nextState.run_id,
+        clusterId: nextState.cluster_id,
+        repairResult: repairLoopResult,
+        repoRoot,
+    });
+    if (repairLoopResult.final_qc_results.length > 0 && repairLoopResult.rounds_completed > 0) {
+        (0, qc_escalation_js_1.appendQcEscalationSymptoms)({
+            runId: nextState.run_id,
+            clusterId: nextState.cluster_id,
+            qcResults: repairLoopResult.final_qc_results,
+            afterRepair: true,
+            repoRoot,
+        });
+    }
+    const repairLoopBlocker = validateQcRepairLoopGate(nextState, config.qc);
+    if (repairLoopBlocker) {
+        process.stderr.write(`${stepLabel} QC completed-cluster blocked finalize: ${qcResult.summary}\n` +
+            `${repairLoopBlocker}\n`);
+        process.exit(1);
+    }
+    console.log(`${stepLabel} QC completed-cluster repaired: ${repairLoopResult.summary}`);
+    return nextState;
+}
 async function runFinalize(options) {
-    const { repoRoot, stateFile, dryRun, skipDelivery, skipLibrarian } = options;
+    const { repoRoot, stateFile, dryRun, skipDelivery, skipLibrarian, bypassMedicReason } = options;
     const config = (0, loader_js_1.loadConfig)(repoRoot);
     // Step 1: polaris map update --changed
     console.log("[1/14] Updating map..."); // Step count updated
@@ -553,13 +741,13 @@ async function runFinalize(options) {
     const qcBaseRef = clusterStateForQc?.base_branch ??
         config.finalize?.targetBranch ??
         "main";
-    await runQcGate({
-        config: config.qc,
+    state = await runCompletedClusterQcWithRepair({
+        config,
         state,
+        stateFile: (0, node_path_1.resolve)(stateFile),
         repoRoot,
         branch,
         baseRef: qcBaseRef,
-        trigger: "completed-cluster",
         stepLabel: "[5.8/14]",
     });
     // Step 5.9: QC repair-loop terminal state gate
@@ -580,6 +768,29 @@ async function runFinalize(options) {
         process.stderr.write(`finalize aborted: authoritative child state mismatch.\n${authChildResult.reason}\n`);
         process.exit(1);
     }
+    // Step 5.11: Run-health Medic gate
+    // After all worker/QC evidence is available and before any final commit, push,
+    // PR creation, or tracker update, require a Medic consultation decision for any
+    // run that recorded health symptoms.
+    {
+        console.log("[5.11/14] Checking run-health Medic gate...");
+        const bypassPolicy = config.finalize?.medic?.bypassPolicy ?? "none";
+        if (dryRun && bypassMedicReason && bypassPolicy === "cli") {
+            console.warn(`Dry run: would write Medic bypass to run-health report for run "${state.run_id}" (reason: ${bypassMedicReason}).`);
+        }
+        const medicBlocker = (0, medic_gate_js_1.validateMedicGate)({
+            runId: state.run_id,
+            repoRoot,
+            bypassReason: bypassMedicReason,
+            bypassPolicy,
+            dryRun,
+        });
+        if (medicBlocker) {
+            process.stderr.write(`finalize aborted: run-health Medic gate failed.\n${medicBlocker}\n`);
+            process.exit(1);
+        }
+        console.log("[5.11/14] Run-health Medic gate passed.");
+    }
     // Step 6: Tracker Reconciliation
     // LinearAdapter is sync-in only; only McpBridgeAdapter supports full reconciliation.
     const trackerType = config.tracker?.adapter;
@@ -715,11 +926,19 @@ function createFinalizeCommand(handlers = {}) {
         .option("--dry-run", "non-mutating preview: validate and generate report without committing or pushing")
         .option("--skip-delivery", "perform local finalize steps only; skip push/PR/Linear/archive")
         .option("--skip-librarian", "skip the Closeout Librarian gate (backward compatibility only)")
+        .option("--bypass-medic <reason>", "bypass the run-health Medic gate (requires finalize.medic.bypassPolicy=cli)")
         .action((options) => {
         const repoRoot = options.repoRoot;
         const stateFile = options.stateFile ??
             (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
-        finalizeHandler({ repoRoot, stateFile, dryRun: options.dryRun, skipDelivery: options.skipDelivery, skipLibrarian: options.skipLibrarian })
+        finalizeHandler({
+            repoRoot,
+            stateFile,
+            dryRun: options.dryRun,
+            skipDelivery: options.skipDelivery,
+            skipLibrarian: options.skipLibrarian,
+            bypassMedicReason: options.bypassMedic,
+        })
             .catch((err) => {
             process.stderr.write(`finalize error: ${err instanceof Error ? err.message : String(err)}\n`);
             process.exit(1);

package/dist/finalize/medic-gate.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMedicGate = validateMedicGate;
+const index_js_1 = require("../run-health/index.js");
+/**
+ * Validates that a run with a run-health report either has a Medic decision or
+ * an explicit, allowed policy bypass. Returns `null` when finalize may proceed;
+ * returns a human-readable blocker string otherwise.
+ *
+ * Fails closed: a report that exists but lacks a Medic decision/bypass blocks
+ * final commit, push, PR creation, and tracker update.
+ */
+function validateMedicGate(options) {
+    const { runId, repoRoot, bypassReason, bypassPolicy = "none", dryRun = false } = options;
+    const reportPath = (0, index_js_1.getRunHealthReportPath)(runId, repoRoot);
+    const report = (0, index_js_1.readRunHealthReport)(runId, repoRoot);
+    // No report means no symptoms were recorded — gate does not apply.
+    if (!report)
+        return null;
+    if ((0, index_js_1.isMedicGateSatisfied)(report))
+        return null;
+    if (bypassReason) {
+        if (bypassPolicy !== "cli") {
+            return (`Run-health report at ${reportPath} requires Medic consultation, but a CLI bypass is not allowed ` +
+                `by finalize.medic.bypassPolicy (current: "${bypassPolicy}").`);
+        }
+        if (!dryRun) {
+            (0, index_js_1.markBypassed)(runId, {
+                reason: bypassReason,
+                bypassed_by: process.env.USER ?? process.env.LOGNAME ?? "operator",
+                bypassed_at: new Date().toISOString(),
+            }, repoRoot);
+        }
+        return null;
+    }
+    const bypassHint = bypassPolicy === "cli"
+        ? `To bypass this gate, use --bypass-medic "<reason>".`
+        : `Bypass is not enabled by finalize.medic.bypassPolicy (current: "${bypassPolicy}").`;
+    return (`Run-health report at ${reportPath} has recorded symptoms and requires a Medic consultation decision ` +
+        `(medic_consult.status "resolved" or "bypassed", or an explicit policy_bypass) before finalize can commit, push, ` +
+        `create a PR, or update the tracker.\n${bypassHint}`);
+}

package/dist/loop/adapters/terminal-cli.js

@@ -169,10 +169,11 @@ class TerminalCliAdapter {
         const primaryProvider = options.provider || "terminal-cli";
         const routerEvidence = options.routerDecision;
         const providerAttempts = [];
-        if ((0, worker_packet_js_1.isWorkerPacket)(packet) && packet.worker_role === "impl") {
+        if ((0, worker_packet_js_1.isWorkerPacket)(packet) &&
+            (packet.worker_role === "impl" || packet.worker_role === "repair")) {
             const allowed = Array.isArray(packet.instructions?.allowed_scope) ? packet.instructions.allowed_scope : [];
             if (allowed.length === 0) {
-                const blockedMsg = `Worker blocked: impl packet for ${packet.active_child} has empty allowed_scope. Foreman must provide scope or approve override.`;
+                const blockedMsg = `Worker blocked: ${packet.worker_role} packet for ${packet.active_child} has empty allowed_scope. Foreman must provide scope or approve override.`;
                 return {
                     exit_code: 1,
                     provider_used: primaryProvider,