@lsctech/polaris 0.5.7 → 0.5.9

package/dist/loop/parent.js

@@ -48,6 +48,11 @@ const child_selector_js_1 = require("../runtime/scheduling/child-selector.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 index_js_4 = require("../run-health/index.js");
+const foreman_symptoms_js_1 = require("../run-health/foreman-symptoms.js");
+const qc_escalation_js_1 = require("../run-health/qc-escalation.js");
+const run_health_consult_js_1 = require("../medic/run-health-consult.js");
+const treatment_packets_js_1 = require("../medic/treatment-packets.js");
 const CLAIM_TTL_MS = 30 * 60 * 1000;
 /**
  * Returns the list of files touched by a git commit, or null when the commit
@@ -916,11 +921,30 @@ async function runParentLoop(options) {
                         error: msg,
                         timestamp: new Date().toISOString(),
                     });
+                    (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                        runId: state.run_id,
+                        clusterId: state.cluster_id,
+                        code: "foreman-qc-runtime-failure",
+                        message: `QC run at completed-cluster trigger threw a runtime error: ${msg}`,
+                        evidenceRefs: [telemetryFile],
+                        repoRoot,
+                        config,
+                    });
                     // 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");
+                // Append QC escalation symptoms for initial findings (blocking / parse failures / etc.)
+                if (initialQcResult !== null && initialQcResult.results.length > 0) {
+                    (0, qc_escalation_js_1.appendQcEscalationSymptoms)({
+                        runId: state.run_id,
+                        clusterId: state.cluster_id,
+                        qcResults: initialQcResult.results,
+                        afterRepair: false,
+                        repoRoot,
+                    });
+                }
                 if (initialQcResult !== null && hasFindings) {
                     const maxRepairRounds = config.qc.maxRepairRounds ?? repair_loop_js_1.DEFAULT_MAX_REPAIR_ROUNDS;
                     const priorLoopState = state.qc_repair_loop ?? null;
@@ -1021,6 +1045,22 @@ async function runParentLoop(options) {
                             summary: repairLoopResult.summary,
                             timestamp: new Date().toISOString(),
                         });
+                        // Append QC escalation symptoms for non-passing outcomes and post-repair findings.
+                        (0, qc_escalation_js_1.appendRepairLoopOutcomeSymptom)({
+                            runId: state.run_id,
+                            clusterId: state.cluster_id,
+                            repairResult: repairLoopResult,
+                            repoRoot,
+                        });
+                        if (repairLoopResult.final_qc_results.length > 0 && repairLoopResult.rounds_completed > 0) {
+                            (0, qc_escalation_js_1.appendQcEscalationSymptoms)({
+                                runId: state.run_id,
+                                clusterId: state.cluster_id,
+                                qcResults: repairLoopResult.final_qc_results,
+                                afterRepair: true,
+                                repoRoot,
+                            });
+                        }
                     }
                     catch (err) {
                         const msg = err instanceof Error ? err.message : String(err);
@@ -1030,11 +1070,90 @@ async function runParentLoop(options) {
                             error: msg,
                             timestamp: new Date().toISOString(),
                         });
+                        (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                            runId: state.run_id,
+                            clusterId: state.cluster_id,
+                            code: "foreman-qc-runtime-failure",
+                            message: `QC repair loop threw a runtime error: ${msg}`,
+                            evidenceRefs: [telemetryFile],
+                            repoRoot,
+                            config,
+                        });
                         // Non-fatal: proceed to cluster-complete.
                     }
                 }
             }
             // ── End QC repair loop ─────────────────────────────────────────────────
+            // ── Run-health Medic consult ────────────────────────────────────────────
+            // If the run recorded health symptoms and no Medic decision exists yet,
+            // dispatch Medic to diagnose and optionally emit bounded treatment packets.
+            if (!dryRun) {
+                const runHealthReport = (0, index_js_4.readRunHealthReport)(state.run_id, repoRoot);
+                if (runHealthReport && !(0, index_js_4.isMedicGateSatisfied)(runHealthReport)) {
+                    const maxTreatmentRounds = config.qc?.maxRepairRounds ?? repair_loop_js_1.DEFAULT_MAX_REPAIR_ROUNDS;
+                    const medicDispatchId = (0, node_crypto_1.randomUUID)();
+                    const medicResultPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "results", `medic-run-health-${medicDispatchId}.json`);
+                    const medicPacket = {
+                        role: "medic-run-health",
+                        run_id: state.run_id,
+                        dispatch_id: medicDispatchId,
+                        cluster_id: state.cluster_id,
+                        run_health_report_path: (0, index_js_4.getRunHealthReportPath)(state.run_id, repoRoot),
+                        qc_artifact_refs: Array.from(new Set([
+                            ...runHealthReport.evidence_refs,
+                            ...runHealthReport.symptoms.flatMap((s) => s.evidence_refs),
+                        ])),
+                        telemetry_path: telemetryFile,
+                        cluster_state_path: (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "state.json"),
+                        policy_limits: { max_treatment_rounds: maxTreatmentRounds },
+                        result_path: medicResultPath,
+                        allowed_write_paths: [
+                            "smartdocs/medic/charts",
+                            ".polaris/runs",
+                            ".polaris/clusters",
+                            ".taskchain_artifacts",
+                        ],
+                        prohibited_write_paths: [],
+                    };
+                    try {
+                        await (0, run_health_consult_js_1.runMedicRunHealthConsult)({
+                            packet: medicPacket,
+                            repoRoot,
+                            stateFile,
+                            telemetryFile,
+                            branch: state.branch ?? getCurrentBranch(repoRoot),
+                            validationCommands: ["npm run build", "npm test"],
+                            maxConcurrentWorkers,
+                            dryRun,
+                            dispatchTreatmentWorkerFn: (input) => (0, treatment_packets_js_1.dispatchTreatmentWorker)({
+                                ...input,
+                                repoRoot,
+                                dispatch: (workerPacket) => adapter.dispatch(workerPacket, { provider: providerName }),
+                            }),
+                        });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        appendTelemetry(telemetryFile, {
+                            event: "medic-run-health-consult-error",
+                            run_id: state.run_id,
+                            cluster_id: state.cluster_id,
+                            error: msg,
+                            timestamp: new Date().toISOString(),
+                        });
+                        (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                            runId: state.run_id,
+                            clusterId: state.cluster_id,
+                            code: "foreman-medic-runtime-failure",
+                            message: `Medic run-health consult threw a runtime error: ${msg}`,
+                            evidenceRefs: [telemetryFile],
+                            repoRoot,
+                            config,
+                        });
+                    }
+                }
+            }
+            // ── End run-health Medic consult ───────────────────────────────────────
             // All children completed — write final state and halt
             if (!dryRun) {
                 logStatus(notificationFormat, "COMPLETE");
@@ -1143,6 +1262,15 @@ async function runParentLoop(options) {
                     reason: msg,
                     timestamp: new Date().toISOString(),
                 });
+                (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                    runId: state.run_id,
+                    clusterId: state.cluster_id,
+                    code: "foreman-dispatch-boundary-repair",
+                    message: `Dispatch boundary violation: ${msg}`,
+                    evidenceRefs: [telemetryFile],
+                    repoRoot,
+                    config,
+                });
             }
             return {
                 haltReason: 'worker-error',
@@ -1502,6 +1630,43 @@ async function runParentLoop(options) {
                     sealedResult['status'] = 'failed';
                 }
                 finalWorkerSummary = sealedResult;
+                // ── Ingest worker-reported run-health symptoms ────────────────────────
+                // Only process when worker reports at least one symptom. Errors are
+                // logged to telemetry but never block the run — symptom reporting is
+                // advisory, not a gate.
+                const rawSymptoms = sealedResult['run_health_symptoms'];
+                if (!dryRun && Array.isArray(rawSymptoms) && rawSymptoms.length > 0) {
+                    const dispatchRecord = state.open_children_meta?.[nextChild]?.dispatch_record;
+                    try {
+                        (0, index_js_4.upsertWorkerSymptoms)({
+                            runId: state.run_id,
+                            clusterId: state.cluster_id,
+                            childId: nextChild,
+                            workerId: dispatchRecord?.worker_id,
+                            provider: dispatchRecord?.provider,
+                            symptoms: rawSymptoms,
+                            repoRoot,
+                        });
+                        appendTelemetry(telemetryFile, {
+                            event: "run-health-symptoms-ingested",
+                            run_id: state.run_id,
+                            child_id: nextChild,
+                            symptom_count: rawSymptoms.length,
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                    catch (symptomErr) {
+                        const symptomMsg = symptomErr instanceof Error ? symptomErr.message : String(symptomErr);
+                        appendTelemetry(telemetryFile, {
+                            event: "run-health-ingest-error",
+                            run_id: state.run_id,
+                            child_id: nextChild,
+                            error: symptomMsg,
+                            timestamp: new Date().toISOString(),
+                        });
+                        // ponytail: consider surfacing ingest errors to operator via logStatus in a future pass
+                    }
+                }
             }
             catch (error) {
                 const msg = error instanceof Error ? error.message : String(error);
@@ -1514,6 +1679,15 @@ async function runParentLoop(options) {
                         result_file: packet.result_file_contract.result_file,
                         timestamp: new Date().toISOString(),
                     });
+                    (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                        runId: state.run_id,
+                        clusterId: state.cluster_id,
+                        code: "foreman-packet-repair",
+                        message: `Failed to read sealed result file for ${nextChild}: ${msg}`,
+                        evidenceRefs: [telemetryFile],
+                        repoRoot,
+                        config,
+                    });
                 }
                 return {
                     haltReason: 'worker-error',
@@ -1540,6 +1714,15 @@ async function runParentLoop(options) {
                     error: errMsg,
                     timestamp: new Date().toISOString(),
                 });
+                (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                    runId: state.run_id,
+                    clusterId: state.cluster_id,
+                    code: "foreman-wrong-run-telemetry",
+                    message: errMsg,
+                    evidenceRefs: [telemetryFile],
+                    repoRoot,
+                    config,
+                });
             }
             return {
                 haltReason: 'worker-error',
@@ -1709,6 +1892,15 @@ async function runParentLoop(options) {
                         error: errMsg,
                         timestamp: new Date().toISOString(),
                     });
+                    (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                        runId: state.run_id,
+                        clusterId: state.cluster_id,
+                        code: "foreman-state-repair",
+                        message: `State file validation failed after worker execution; using pre-dispatch fallback: ${errMsg}`,
+                        evidenceRefs: [telemetryFile],
+                        repoRoot,
+                        config,
+                    });
                     state = stateBeforeDispatch;
                 }
                 else if (!dryRun) {
@@ -1747,6 +1939,15 @@ async function runParentLoop(options) {
                     error: errMsg,
                     timestamp: new Date().toISOString(),
                 });
+                (0, foreman_symptoms_js_1.appendForemanSymptom)({
+                    runId: state.run_id,
+                    clusterId: state.cluster_id,
+                    code: "foreman-state-repair",
+                    message: `State reload threw after worker execution; using pre-dispatch fallback: ${errMsg}`,
+                    evidenceRefs: [telemetryFile],
+                    repoRoot,
+                    config,
+                });
                 state = stateBeforeDispatch;
             }
             else if (!dryRun) {
@@ -2031,35 +2232,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) ─────────────────────────────
     }

package/dist/loop/worker-packet.js

@@ -11,7 +11,7 @@
  * accept BootstrapPacket transparently accept WorkerPacket.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REPAIR_RETURN_CONTRACT = exports.STARTUP_RETURN_CONTRACT = exports.PREFLIGHT_RETURN_CONTRACT = exports.WORKER_PROHIBITED_WRITE_PATHS = exports.FINALIZE_RETURN_CONTRACT = exports.IMPL_RETURN_CONTRACT = void 0;
+exports.REPAIR_RETURN_CONTRACT = exports.STARTUP_RETURN_CONTRACT = exports.PREFLIGHT_RETURN_CONTRACT = exports.WORKER_SYMPTOM_CATEGORIES = exports.WORKER_PROHIBITED_WRITE_PATHS = exports.FINALIZE_RETURN_CONTRACT = exports.IMPL_RETURN_CONTRACT = void 0;
 exports.roleContextForWorkerRole = roleContextForWorkerRole;
 exports.isWorkerPacket = isWorkerPacket;
 exports.getWorkerCommitPolicy = getWorkerCommitPolicy;
@@ -130,6 +130,21 @@ exports.WORKER_PROHIBITED_WRITE_PATHS = [
     ".polaris/runs/",
     "**/telemetry.jsonl",
 ];
+// ── Worker symptom reporting ──────────────────────────────────────────────────
+/**
+ * Canonical symptom categories workers may use in their sealed result.
+ * Workers observe and report — they do NOT diagnose root cause.
+ *
+ * Include run_health_symptoms in the sealed result only when at least one
+ * symptom occurred. When no symptoms occurred, omit the field entirely.
+ */
+exports.WORKER_SYMPTOM_CATEGORIES = [
+    "worker-blocked", // Could not proceed (missing info, approval needed, out-of-scope)
+    "validation-failed", // Build / test / lint validation commands failed
+    "repeated-rework", // Same fix attempted multiple times without success
+    "unclear-requirements", // Requirements are contradictory or too ambiguous to act on
+    "unusual-assumption", // Had to assume something outside normal scope to proceed
+];
 function getWorkerCommitPolicy(packet) {
     return {
         allowedScope: [...packet.instructions.allowed_scope],
@@ -255,6 +270,9 @@ function compileImplPacket(input) {
         `Create exactly ONE git commit: [${input.childId}] ${childTitle}.`,
         `Do NOT modify open_children or completed_children in ${input.stateFile}. The parent runtime (loop continue) owns that state transition.`,
         `Append a telemetry event to ${input.telemetryFile}.`,
+        `If you encountered any struggle signals during execution, include a "run_health_symptoms" array in your sealed result. ` +
+            `Use one of these categories: ${exports.WORKER_SYMPTOM_CATEGORIES.join(', ')}. ` +
+            `Report what you observed — do NOT diagnose root cause. Omit the field if no symptoms occurred.`,
         `Write compact return JSON to stdout (fields: ${exports.IMPL_RETURN_CONTRACT.join(', ')}). next_recommended_action MUST be exactly "continue" on success, "stop" on unresolvable blocker, or "investigate" if manual review is needed.`,
         `TERMINATE SESSION IMMEDIATELY. Do not select or execute the next child.`,
     ];