@lsctech/polaris 0.5.8 → 0.5.10

package/dist/qc/providers/coderabbit.js

@@ -17,18 +17,20 @@ function pickString(...candidates) {
     return undefined;
 }
 const FINDING_LOCATION_KEYS = ["file", "filePath", "path"];
-const FINDING_REVIEW_KEYS = [
-    "severity",
+const FINDING_CONTENT_KEYS = [
     "message",
     "title",
     "summary",
     "description",
     "body",
-    "rule",
-    "category",
     "suggestion",
     "suggestedAction",
     "fix",
+];
+const FINDING_BOOKKEEPING_KEYS = [
+    "severity",
+    "category",
+    "rule",
     "providerFindingId",
     "id",
     "findingId",
@@ -56,8 +58,37 @@ const PROGRESS_STATUS_VALUES = new Set([
 function hasFindingLocation(record) {
     return FINDING_LOCATION_KEYS.some((key) => record[key] !== undefined);
 }
-function hasFindingReviewContent(record) {
-    return FINDING_REVIEW_KEYS.some((key) => record[key] !== undefined);
+function isGenuineTitle(record) {
+    const title = record.title;
+    if (typeof title !== "string" || title.trim().length === 0) {
+        return false;
+    }
+    const trimmedTitle = title.trim().toLowerCase();
+    const fallbackSources = [record.category, record.type, record.rule];
+    for (const source of fallbackSources) {
+        if (typeof source === "string" && source.trim().toLowerCase() === trimmedTitle) {
+            return false;
+        }
+    }
+    return true;
+}
+function hasFindingContent(record) {
+    for (const key of FINDING_CONTENT_KEYS) {
+        if (key === "title") {
+            if (isGenuineTitle(record))
+                return true;
+        }
+        else if (record[key] !== undefined) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasFindingBookkeeping(record) {
+    return FINDING_BOOKKEEPING_KEYS.some((key) => record[key] !== undefined);
+}
+function hasFindingShape(record) {
+    return hasFindingLocation(record) || hasFindingContent(record) || hasFindingBookkeeping(record);
 }
 function isProgressRecord(record) {
     // Check progress/status indicators FIRST before the generic finding-content guard
@@ -73,8 +104,8 @@ function isProgressRecord(record) {
     // Status-only records with category="status" are progress records even if they have message/title fields
     if (typeof record.category === "string" && record.category.toLowerCase() === "status")
         return true;
-    // Only reject as progress if it has both location AND review content (true finding shape)
-    if (hasFindingLocation(record) && hasFindingReviewContent(record)) {
+    // Only reject as progress if it has both location AND content (true finding shape)
+    if (hasFindingLocation(record) && hasFindingContent(record)) {
         return false;
     }
     return false;
@@ -82,7 +113,10 @@ function isProgressRecord(record) {
 function isActionableFinding(record) {
     if (isProgressRecord(record))
         return false;
-    return hasFindingLocation(record) || hasFindingReviewContent(record);
+    return hasFindingLocation(record) || hasFindingContent(record);
+}
+function isUnusableFindingRecord(record) {
+    return !isActionableFinding(record) && (isProgressRecord(record) || hasFindingShape(record));
 }
 function makeUnusableOutputError(message) {
     const err = new Error(message);
@@ -136,6 +170,21 @@ function parseReport(output, format, parser) {
     if (data !== undefined && typeof data === "object" && data !== null) {
         const findings = parseFindingsFromPayload(data);
         const record = data;
+        if (findings.length === 0) {
+            if (isProgressRecord(record)) {
+                throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
+            }
+            if (isUnusableFindingRecord(record)) {
+                throw makeUnusableOutputError("CodeRabbit output contained only bookkeeping records");
+            }
+            const rawFindings = record.findings ?? record.issues ?? record.results;
+            if (Array.isArray(rawFindings) && rawFindings.length > 0) {
+                const unusableCount = rawFindings.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
+                if (unusableCount > 0) {
+                    throw makeUnusableOutputError(`CodeRabbit output contained only bookkeeping/progress records (${unusableCount} items)`);
+                }
+            }
+        }
         return {
             findings,
             ...(typeof record.prUrl === "string" ? { prUrl: record.prUrl } : {}),
@@ -150,16 +199,29 @@ function parseReport(output, format, parser) {
             if (Array.isArray(parsed)) {
                 const findings = parsed.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
                 if (findings.length === 0 && parsed.length > 0) {
-                    const progressCount = parsed.filter((item) => typeof item === "object" && item !== null && isProgressRecord(item)).length;
-                    if (progressCount > 0) {
-                        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat records (${progressCount} items)`);
+                    const unusableCount = parsed.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
+                    if (unusableCount > 0) {
+                        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat and bookkeeping records (${unusableCount} items)`);
                     }
                 }
                 return { findings };
             }
             const findings = parseFindingsFromPayload(parsed);
-            if (findings.length === 0 && isProgressRecord(parsed)) {
-                throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
+            if (findings.length === 0) {
+                const parsedRecord = parsed;
+                if (isProgressRecord(parsedRecord)) {
+                    throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
+                }
+                if (isUnusableFindingRecord(parsedRecord)) {
+                    throw makeUnusableOutputError("CodeRabbit output contained only bookkeeping records");
+                }
+                const rawFindings = parsedRecord.findings ?? parsedRecord.issues ?? parsedRecord.results;
+                if (Array.isArray(rawFindings) && rawFindings.length > 0) {
+                    const unusableCount = rawFindings.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
+                    if (unusableCount > 0) {
+                        throw makeUnusableOutputError(`CodeRabbit output contained only bookkeeping/progress records (${unusableCount} items)`);
+                    }
+                }
             }
             return {
                 findings,
@@ -169,8 +231,14 @@ function parseReport(output, format, parser) {
             };
         }
         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.
+            // Semantic failures (e.g. unusable-output) surfaced during JSON object/array
+            // parsing must not be swallowed; only true JSON parse errors fall through to
+            // JSONL line scanning when the format is not explicitly JSON.
+            if (typeof jsonError === "object" &&
+                jsonError !== null &&
+                "qcFailureReason" in jsonError) {
+                throw jsonError;
+            }
             if (format === "json") {
                 throw jsonError;
             }
@@ -180,6 +248,7 @@ function parseReport(output, format, parser) {
     const lines = text.split("\n").filter((line) => line.trim().length > 0);
     const lineFindings = [];
     let progressLineCount = 0;
+    let unusableLineCount = 0;
     let parsedLineCount = 0;
     for (const line of lines) {
         try {
@@ -196,6 +265,9 @@ function parseReport(output, format, parser) {
             if (isActionableFinding(record)) {
                 lineFindings.push(parsed);
             }
+            else if (isUnusableFindingRecord(record)) {
+                unusableLineCount++;
+            }
         }
         catch {
             // Ignore unparseable lines.
@@ -204,8 +276,8 @@ function parseReport(output, format, parser) {
     if (lineFindings.length > 0) {
         return { findings: lineFindings };
     }
-    if (progressLineCount > 0) {
-        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat records (${progressLineCount} lines)`);
+    if (progressLineCount > 0 || unusableLineCount > 0) {
+        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat and bookkeeping records (${progressLineCount + unusableLineCount} lines)`);
     }
     if (parsedLineCount > 0) {
         throw new Error("CodeRabbit output contained no actionable findings");

package/dist/qc/repair-loop.js

@@ -16,7 +16,7 @@
  * 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.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS = exports.DEFAULT_MAX_REPAIR_ROUNDS = void 0;
 exports.partitionRepairPackets = partitionRepairPackets;
 exports.initRepairLoopState = initRepairLoopState;
 exports.runQcRepairLoop = runQcRepairLoop;
@@ -28,11 +28,71 @@ const store_js_1 = require("../cluster-state/store.js");
 // ── Constants ─────────────────────────────────────────────────────────────────
 /** Default maximum repair rounds when not configured. */
 exports.DEFAULT_MAX_REPAIR_ROUNDS = 2;
+/** Default timeout for a single repair worker dispatch (30 minutes). */
+exports.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS = 1_800_000;
 // ── 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");
 }
+/**
+ * Emit a pre-dispatch telemetry checkpoint and wrap the dispatch call in a
+ * configurable timeout. A timed-out dispatch resolves to a failure/timeout
+ * RepairWorkerResult instead of blocking the loop indefinitely.
+ * On timeout, aborts the dispatch via AbortSignal to terminate the worker process.
+ */
+async function dispatchRepairWorkerWithTimeout(dispatch, packet, round, manifest, timeoutMs, telemetryFile, runId, clusterId) {
+    appendTelemetry(telemetryFile, {
+        event: "qc-repair-worker-dispatch-start",
+        run_id: runId,
+        cluster_id: clusterId,
+        round,
+        packet_id: packet.packetId,
+        medic: packet.medic,
+        parallel_group: packet.parallelGroup,
+        timestamp: new Date().toISOString(),
+    });
+    const controller = new AbortController();
+    let timer;
+    let timedOut = false;
+    try {
+        const result = await Promise.race([
+            dispatch(packet, round, manifest, controller.signal),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort(new Error(`Repair worker dispatch timed out after ${timeoutMs}ms`));
+                    reject(new Error(`Repair worker dispatch timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+        return result;
+    }
+    catch (err) {
+        if (timer)
+            clearTimeout(timer);
+        const msg = err instanceof Error ? err.message : String(err);
+        if (timedOut) {
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-worker-dispatch-timeout",
+                run_id: runId,
+                cluster_id: clusterId,
+                round,
+                packet_id: packet.packetId,
+                timeout_ms: timeoutMs,
+                error: msg,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        return {
+            packetId: packet.packetId,
+            status: "failure",
+            errorMessage: msg,
+        };
+    }
+}
 async function persistQcRepairOutcome(clusterId, repoRoot, outcome) {
     try {
         const clusterState = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
@@ -96,8 +156,8 @@ function rerunPassed(results) {
 }
 /** 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");
+    // Medic packets are always serialized; operator-review packets are never dispatched.
+    const serialized = packets.filter((p) => p.medic);
     const parallelizable = packets.filter((p) => !p.medic && p.routingTarget !== "operator-review");
     // Group by parallelGroup assignment from the compiler.
     const groups = new Map();
@@ -139,6 +199,7 @@ function initRepairLoopState(opts) {
  */
 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;
+    const repairDispatchTimeoutMs = config.repairDispatchTimeoutMs ?? exports.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS;
     if (!config.enabled) {
         const state = initRepairLoopState({
             maxRounds,
@@ -194,25 +255,6 @@ async function runQcRepairLoop(options) {
                 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(),
-            });
-            await persistQcRepairOutcome(clusterId, repoRoot, "operator-review");
-            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).
@@ -261,10 +303,29 @@ async function runQcRepairLoop(options) {
             await persistQcRepairManifest(clusterId, repoRoot, round, existingManifestPath);
         }
         // ── Check for repairable packets ────────────────────────────────────────
-        const repairablePackets = manifest.packets.filter((p) => p.routingTarget === "repair-worker" &&
+        const dispatchablePackets = manifest.packets.filter((p) => p.routingTarget === "repair-worker" &&
             p.status === "pending" &&
             !loopState.completed_packet_ids.includes(p.packetId));
-        if (repairablePackets.length === 0 && !hasRepairableFindings(currentResults)) {
+        if (dispatchablePackets.length === 0 && 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(),
+            });
+            await persistQcRepairOutcome(clusterId, repoRoot, "operator-review");
+            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}`,
+            };
+        }
+        if (dispatchablePackets.length === 0 && !hasRepairableFindings(currentResults)) {
             loopState = { ...loopState, terminal_outcome: "no-repairable", updated_at: new Date().toISOString() };
             onStateUpdate?.(loopState);
             appendTelemetry(telemetryFile, {
@@ -284,7 +345,7 @@ async function runQcRepairLoop(options) {
             };
         }
         // ── Dispatch repair workers (parallel groups, then serialized) ──────────
-        const { parallelGroups, serialized } = partitionRepairPackets(repairablePackets);
+        const { parallelGroups, serialized } = partitionRepairPackets(dispatchablePackets);
         const allWorkerResults = [];
         let hasMedicReferral = false;
         // Dispatch parallel groups.
@@ -298,12 +359,12 @@ async function runQcRepairLoop(options) {
                 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)));
+            const groupResults = await Promise.all(group.map((pkt) => dispatchRepairWorkerWithTimeout(dispatchRepairWorker, pkt, round, manifest, repairDispatchTimeoutMs, telemetryFile, runId, clusterId)));
             allWorkerResults.push(...groupResults);
         }
-        // Dispatch serialized (medic/operator-review) packets sequentially.
+        // Dispatch serialized (medic) packets sequentially.
         for (const pkt of serialized) {
-            const result = await dispatchRepairWorker(pkt, round, manifest);
+            const result = await dispatchRepairWorkerWithTimeout(dispatchRepairWorker, pkt, round, manifest, repairDispatchTimeoutMs, telemetryFile, runId, clusterId);
             allWorkerResults.push(result);
         }
         // Record completed packet IDs.
@@ -438,6 +499,25 @@ async function runQcRepairLoop(options) {
         }
     }
     // ── Max rounds exhausted ──────────────────────────────────────────────────
+    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",
+            rounds_completed: roundsCompleted,
+            timestamp: new Date().toISOString(),
+        });
+        await persistQcRepairOutcome(clusterId, repoRoot, "operator-review");
+        return {
+            outcome: "operator-review",
+            rounds_completed: roundsCompleted,
+            final_qc_results: currentResults,
+            loop_state: loopState,
+            summary: `QC repair loop halted: unresolved operator-review findings after ${roundsCompleted} round(s)`,
+        };
+    }
     loopState = { ...loopState, terminal_outcome: "max-rounds", updated_at: new Date().toISOString() };
     onStateUpdate?.(loopState);
     appendTelemetry(telemetryFile, {

package/dist/qc/runner.js

@@ -76,6 +76,12 @@ function classifyTerminalFailure(error, output) {
     if (execError?.killed && execError?.signal === "SIGTERM") {
         return "timeout";
     }
+    // Exit code 143 is the standard shell convention for a process killed by SIGTERM
+    // (128 + SIGTERM). Some provider CLI wrappers report this directly instead of
+    // allowing Node's execFile to surface the signal, so treat it as a timeout.
+    if (output.exitCode === 143) {
+        return "timeout";
+    }
     if (execError?.code === "ENOENT") {
         return "command-not-found";
     }
@@ -174,8 +180,8 @@ async function runSingleProvider(provider, scope, options, fallbackSource) {
     const startedAt = new Date().toISOString();
     const command = provider.buildReviewCommand(scope);
     const execFn = options.execFileImpl ?? node_child_process_1.execFile;
-    const timeoutMs = options.timeoutMs ?? 300_000; // 5 minutes default
     const providerConfig = getProviderConfig(provider.name, options.config);
+    const timeoutMs = options.timeoutMs ?? providerConfig?.timeoutMs ?? 300_000; // 5 minutes default
     emitProviderAttempted(options.telemetryFile, scope.runId, scope.clusterId, provider.name, fallbackSource);
     if (!isModeSupported(provider, scope)) {
         const output = {

package/dist/run-health/foreman-symptoms.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Foreman-side runtime symptom emission.
+ *
+ * The Foreman appends symptoms ONLY for Polaris-runtime intervention events
+ * (state repair, cluster repair, missing packet/result repair, dispatch
+ * boundary repair, QC/finalize runtime failure, local/global binary mismatch,
+ * and manual intervention).
+ *
+ * Symptoms are NOT emitted for non-Polaris target repositories unless
+ * `run_health.foreman_symptoms.enabled` is explicitly set to true in
+ * polaris.config.json.
+ *
+ * QC providers remain unchanged artifact producers — they never write here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isForemanSymptomEnabled = isForemanSymptomEnabled;
+exports.appendForemanSymptom = appendForemanSymptom;
+const node_crypto_1 = require("node:crypto");
+const index_js_1 = require("./index.js");
+// ── Policy ────────────────────────────────────────────────────────────────────
+/**
+ * Returns true when Foreman-side symptom emission is enabled.
+ *
+ * Emission is enabled when `run_health.foreman_symptoms.enabled === true` in
+ * the project's polaris.config.json. Foreman symptoms are disabled by default
+ * so that non-Polaris target repositories are not automatically marked sick.
+ */
+function isForemanSymptomEnabled(config) {
+    return config?.run_health?.foreman_symptoms?.enabled === true;
+}
+/**
+ * Append a Foreman-side runtime symptom to the run-health report.
+ *
+ * Creates the report when one does not yet exist; appends to it when one does.
+ * When `config` is provided, checks `isForemanSymptomEnabled(config)` and
+ * no-ops when disabled (so the caller does not need to guard).
+ * Never throws — symptom emission is advisory and must not block the run.
+ */
+function appendForemanSymptom(params) {
+    const { runId, clusterId, code, message, evidenceRefs, repoRoot, config } = params;
+    // Policy gate: skip when config is provided but policy is not enabled.
+    if (config !== undefined && !isForemanSymptomEnabled(config)) {
+        return;
+    }
+    const sourceActor = {
+        role: "foreman",
+    };
+    const symptom = {
+        id: `foreman:${code}:${(0, node_crypto_1.randomUUID)()}`,
+        severity: foremanCodeSeverity(code),
+        code,
+        message,
+        source_actor: sourceActor,
+        evidence_refs: evidenceRefs ?? [],
+        occurred_at: new Date().toISOString(),
+    };
+    try {
+        const existing = (0, index_js_1.readRunHealthReport)(runId, repoRoot);
+        if (!existing) {
+            (0, index_js_1.createRunHealthReport)({
+                runId,
+                clusterId,
+                firstSymptom: symptom,
+                sourceActor,
+                repoRoot,
+            });
+        }
+        else {
+            (0, index_js_1.appendSymptom)(runId, symptom, repoRoot);
+        }
+    }
+    catch {
+        // Symptom emission must never block the run — swallow errors silently.
+        // ponytail: surface to telemetry in a future pass
+    }
+}
+/**
+ * Maps a Foreman symptom code to its default severity.
+ */
+function foremanCodeSeverity(code) {
+    switch (code) {
+        case "foreman-dispatch-boundary-repair":
+            return "critical";
+        case "foreman-state-repair":
+        case "foreman-cluster-repair":
+        case "foreman-packet-repair":
+        case "foreman-qc-runtime-failure":
+        case "foreman-medic-runtime-failure":
+        case "foreman-binary-mismatch":
+        case "foreman-wrong-run-telemetry":
+            return "high";
+        case "foreman-finalize-recovery":
+            return "medium";
+        case "foreman-manual-intervention":
+            return "low";
+        default:
+            return "medium";
+    }
+}