@lsctech/polaris 0.4.9 → 0.5.2

package/dist/loop/checkpoint.js

@@ -269,6 +269,46 @@ function validateState(state) {
             }
         }
     }
+    if ("worker_pool_state" in s && s["worker_pool_state"] !== undefined) {
+        if (typeof s["worker_pool_state"] !== "object" || s["worker_pool_state"] === null || Array.isArray(s["worker_pool_state"])) {
+            errors.push("worker_pool_state must be an object");
+        }
+        else {
+            const pool = s["worker_pool_state"];
+            if (typeof pool["max_concurrent"] !== "number" ||
+                !Number.isInteger(pool["max_concurrent"]) ||
+                pool["max_concurrent"] < 1) {
+                errors.push("worker_pool_state.max_concurrent must be a positive integer");
+            }
+            if (!Array.isArray(pool["slot_claims"])) {
+                errors.push("worker_pool_state.slot_claims must be an array");
+            }
+            else {
+                for (const [index, claim] of pool["slot_claims"].entries()) {
+                    if (typeof claim !== "object" || claim === null || Array.isArray(claim)) {
+                        errors.push(`worker_pool_state.slot_claims[${index}] must be an object`);
+                        continue;
+                    }
+                    const typed = claim;
+                    if (typeof typed["child_id"] !== "string" || typed["child_id"].trim().length === 0) {
+                        errors.push(`worker_pool_state.slot_claims[${index}].child_id must be a non-empty string`);
+                    }
+                    if (typed["provider"] !== null && typeof typed["provider"] !== "string") {
+                        errors.push(`worker_pool_state.slot_claims[${index}].provider must be a string or null`);
+                    }
+                    if (typeof typed["claimed_at"] !== "string") {
+                        errors.push(`worker_pool_state.slot_claims[${index}].claimed_at must be a string`);
+                    }
+                    if (typeof typed["expires_at"] !== "string") {
+                        errors.push(`worker_pool_state.slot_claims[${index}].expires_at must be a string`);
+                    }
+                    if (typeof typed["selection_reason"] !== "string") {
+                        errors.push(`worker_pool_state.slot_claims[${index}].selection_reason must be a string`);
+                    }
+                }
+            }
+        }
+    }
     return errors;
 }
 function writeStateAtomic(stateFile, state) {

package/dist/loop/dispatch-boundary.js

@@ -40,8 +40,10 @@ exports.validateTransition = validateTransition;
 exports.initialDispatchBoundary = initialDispatchBoundary;
 exports.advanceDispatchEpoch = advanceDispatchEpoch;
 exports.advanceContinueEpoch = advanceContinueEpoch;
+exports.assertChildQcSelectionAllowed = assertChildQcSelectionAllowed;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const triggers_js_1 = require("../qc/triggers.js");
 // ──────────────────────────────────────────────────────────────────────────────
 // Error constants
 // ──────────────────────────────────────────────────────────────────────────────
@@ -333,3 +335,30 @@ function advanceContinueEpoch(current) {
         last_dispatched_child: current.last_dispatched_child,
     };
 }
+/**
+ * Validate that a child-level QC trigger is only selected when permitted.
+ *
+ * Child-level QC is opt-in: high-risk scope, route policy, or explicit operator
+ * request. If a packet carries child-level QC without meeting one of those
+ * conditions, the dispatch boundary is violated.
+ */
+function assertChildQcSelectionAllowed(state, childId, config, allowedScope, labels, telemetryFile) {
+    const meta = state.open_children_meta?.[childId];
+    if (meta?.qc_trigger !== "child")
+        return;
+    const routeName = childId; // route-specific overrides are keyed by child/route identifier
+    if ((0, triggers_js_1.isChildQcSelected)(config, childId, allowedScope, labels, routeName)) {
+        return;
+    }
+    const reason = `Child-level QC selected for ${childId} but no opt-in condition is met (high-risk scope, route policy, or "qc-child" label)`;
+    appendDispatchViolationEvent(telemetryFile, {
+        event: "illegal-state-transition",
+        run_id: state.run_id,
+        child_id: childId,
+        from_state: getMachineState(state),
+        to_state: "dispatched",
+        reason,
+        timestamp: new Date().toISOString(),
+    });
+    throw new Error(reason);
+}

package/dist/loop/dispatch.js

@@ -15,6 +15,7 @@ const body_parser_js_1 = require("./body-parser.js");
 const loader_js_1 = require("../config/loader.js");
 const store_js_1 = require("../cluster-state/store.js");
 const worker_prompt_js_1 = require("./worker-prompt.js");
+const index_js_1 = require("./router/index.js");
 function resolveSimplicityMode(state, config) {
     if (state.simplicity_bypass)
         return "off";
@@ -23,7 +24,7 @@ function resolveSimplicityMode(state, config) {
 const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
 const run_bootstrap_js_1 = require("./run-bootstrap.js");
 const ledger_js_1 = require("./ledger.js");
-const index_js_1 = require("../tracker/index.js");
+const index_js_2 = require("../tracker/index.js");
 const lifecycle_transition_js_1 = require("../tracker/lifecycle-transition.js");
 const CLAIM_TTL_MS = 30 * 60 * 1000;
 /**
@@ -46,18 +47,51 @@ function roleContextToExecutionRole(role) {
             return "worker";
     }
 }
-function resolveProviderAndMode(options, role, config) {
-    const defaultAdapter = "terminal-cli";
-    if (options.provider) {
-        return {
-            provider: options.provider,
-            mode: "direct-worker",
-            adapter: defaultAdapter,
-            selectionReason: "cli-provider-override",
-            overrideSource: "dispatch-flag",
-            providersTried: [options.provider],
-        };
+function roleContextToTaskType(roleContext) {
+    switch (roleContext?.role) {
+        case "analyst":
+            return "analyze";
+        case "librarian":
+            return "docs";
+        case "foreman":
+            return "startup";
+        case "worker":
+        default:
+            return "impl";
     }
+}
+function requiredCapabilitiesForTask(taskType) {
+    switch (taskType) {
+        case "startup":
+            return ["orchestration"];
+        case "analyze":
+            return ["analysis"];
+        case "impl":
+            return ["implementation"];
+        case "repair":
+            return ["repair"];
+        case "docs":
+            return ["docs"];
+        case "finalize":
+            return ["finalization"];
+        default:
+            return [];
+    }
+}
+function collectActiveProviderSlots(state) {
+    const counts = {};
+    for (const meta of Object.values(state.open_children_meta ?? {})) {
+        const dispatch = meta?.dispatch_record;
+        if (!dispatch?.provider)
+            continue;
+        if (dispatch.status !== "dispatched")
+            continue;
+        counts[dispatch.provider] = (counts[dispatch.provider] ?? 0) + 1;
+    }
+    return counts;
+}
+function resolveProviderAndMode(options, role, config, routerContext) {
+    const defaultAdapter = "terminal-cli";
     // Only catch config-load failures; policy violations must propagate to the caller.
     let loaded;
     let adapter = defaultAdapter;
@@ -78,6 +112,64 @@ function resolveProviderAndMode(options, role, config) {
         };
     }
     const exec = loaded.execution;
+    const providerRegistry = exec?.routerPolicy?.providerRegistry ?? {};
+    const compatibilityMode = Object.keys(providerRegistry).length === 0;
+    if (compatibilityMode) {
+        return resolveProviderAndModeLegacy(options, role, adapter, exec);
+    }
+    const decision = (0, index_js_1.decideWorkerRoute)({
+        role,
+        taskType: routerContext?.taskType ?? "impl",
+        adapter,
+        providerOverride: options.provider,
+        providers: Object.keys(exec?.providers ?? {}),
+        rotation: exec?.rotation ?? [],
+        rolePolicy: exec?.providerPolicy?.[role],
+        roleConfiguredProvider: exec?.roles?.[role]?.provider,
+        routerPolicy: exec?.routerPolicy,
+        constraints: {
+            minTrustTier: routerContext?.minTrustTier,
+            maxCostTier: routerContext?.maxCostTier,
+            disallowedQuotaPolicies: routerContext?.disallowedQuotaPolicies,
+            requiredCapabilities: routerContext?.requiredCapabilities,
+        },
+        runtime: {
+            activeSlotsByProvider: routerContext?.activeSlotsByProvider,
+            quotaAvailableByProvider: routerContext?.quotaAvailableByProvider,
+        },
+        compatibilityMode: false,
+    });
+    return {
+        provider: decision.selectedProvider,
+        mode: decision.mode,
+        adapter,
+        selectionReason: decision.selectionReason,
+        overrideSource: options.provider ? "dispatch-flag" : undefined,
+        providersTried: decision.providersTried,
+        exhaustedReason: decision.exhaustedReason,
+        routerEvidence: decision,
+        routerContextSnapshot: {
+            taskType: routerContext?.taskType ?? "impl",
+            requiredCapabilities: routerContext?.requiredCapabilities,
+            minTrustTier: routerContext?.minTrustTier,
+            maxCostTier: routerContext?.maxCostTier,
+            disallowedQuotaPolicies: routerContext?.disallowedQuotaPolicies,
+            activeSlotsByProvider: routerContext?.activeSlotsByProvider,
+            quotaAvailableByProvider: routerContext?.quotaAvailableByProvider,
+        },
+    };
+}
+function resolveProviderAndModeLegacy(options, role, adapter, exec) {
+    if (options.provider) {
+        return {
+            provider: options.provider,
+            mode: "direct-worker",
+            adapter,
+            selectionReason: "cli-provider-override",
+            overrideSource: "dispatch-flag",
+            providersTried: [options.provider],
+        };
+    }
     const rolePolicy = exec?.providerPolicy?.[role];
     const roleProviders = rolePolicy?.providers ?? [];
     const rotation = exec?.rotation ?? [];
@@ -326,6 +418,15 @@ function determineRuntimeState(mode) {
     return mode === "delegated" ? "delegated" : "packet-created";
 }
 function emitProviderSelected(telemetryFile, dispatchId, runId, childId, decision) {
+    const fallbackAttempts = decision.providersTried.map((provider, index) => {
+        const candidate = decision.routerEvidence?.candidates.find((entry) => entry.provider === provider);
+        return {
+            provider,
+            attempt_index: index + 1,
+            outcome: decision.provider === provider ? "selected" : "rejected",
+            rejection_reasons: candidate?.rejectionReasons ?? [],
+        };
+    });
     appendTelemetry(telemetryFile, {
         event: "provider-selected",
         event_id: (0, node_crypto_1.randomUUID)(),
@@ -336,10 +437,55 @@ function emitProviderSelected(telemetryFile, dispatchId, runId, childId, decisio
         selected_provider: decision.provider ?? null,
         selected_adapter: decision.adapter,
         selection_reason: decision.selectionReason,
+        ...(decision.routerEvidence
+            ? {
+                router_mode: decision.routerEvidence.mode,
+                router_task_type: decision.routerEvidence.selectedWorker.taskType,
+                router_compatibility_mode: decision.routerEvidence.compatibilityMode,
+            }
+            : {}),
+        ...(decision.routerContextSnapshot
+            ? {
+                router_score_inputs: {
+                    required_capabilities: decision.routerContextSnapshot.requiredCapabilities,
+                    min_trust_tier: decision.routerContextSnapshot.minTrustTier,
+                    max_cost_tier: decision.routerContextSnapshot.maxCostTier,
+                    disallowed_quota_policies: decision.routerContextSnapshot.disallowedQuotaPolicies,
+                    active_slots_by_provider: decision.routerContextSnapshot.activeSlotsByProvider,
+                    quota_available_by_provider: decision.routerContextSnapshot.quotaAvailableByProvider,
+                },
+            }
+            : {}),
+        ...(fallbackAttempts.length > 0 ? { fallback_attempts: fallbackAttempts } : {}),
         ...(decision.overrideSource ? { override_source: decision.overrideSource } : {}),
         ...(decision.fallbackFrom ? { fallback_from: decision.fallbackFrom } : {}),
         ...(decision.fallbackReason ? { fallback_reason: decision.fallbackReason } : {}),
         ...(decision.providersTried.length > 0 ? { providers_tried: decision.providersTried } : {}),
+        ...(decision.exhaustedReason ? { router_exhausted_reason: decision.exhaustedReason } : {}),
+        ...(decision.routerEvidence?.candidates?.length
+            ? {
+                router_candidates: decision.routerEvidence.candidates.map((candidate) => ({
+                    provider: candidate.provider,
+                    eligible: candidate.eligible,
+                    rejection_reasons: candidate.rejectionReasons,
+                    score: {
+                        order: candidate.score.orderScore,
+                        trust: candidate.score.trustScore,
+                        cost: candidate.score.costScore,
+                        total: candidate.score.total,
+                    },
+                    inputs: {
+                        order_index: candidate.evidence.orderIndex,
+                        trust_tier: candidate.evidence.trustTier,
+                        cost_tier: candidate.evidence.costTier,
+                        quota_policy: candidate.evidence.quotaPolicy,
+                        active_slots: candidate.evidence.activeSlots,
+                        slot_limit: candidate.evidence.slotLimit,
+                        policy_matched: candidate.evidence.policyMatched,
+                    },
+                })),
+            }
+            : {}),
         timestamp: new Date().toISOString(),
     });
 }
@@ -355,6 +501,10 @@ function emitProviderFallbackAttempted(telemetryFile, dispatchId, runId, childId
         requested_role: "worker",
         fallback_from: decision.fallbackFrom,
         fallback_reason: decision.fallbackReason,
+        ...(decision.provider ? { fallback_to: decision.provider } : {}),
+        ...(decision.providersTried.length > 0
+            ? { fallback_attempt_index: decision.providersTried.length }
+            : {}),
         ...(decision.providersTried.length > 0 ? { providers_tried: decision.providersTried } : {}),
         timestamp: new Date().toISOString(),
     });
@@ -664,7 +814,7 @@ function selectChild(state, requestedChild) {
  * @param resultFile - Optional path for the expected result file; non-absolute paths are resolved against `repoRoot`
  * @returns The constructed WorkerPacket ready for dispatch
  */
-function buildPacket(state, childId, stateFile, telemetryFile, repoRoot, resultFile, config) {
+function buildPacket(state, childId, stateFile, telemetryFile, repoRoot, resultFile, maxConcurrentWorkers, config) {
     const childMeta = state.open_children_meta?.[childId];
     // Hydrate body from cluster snapshot when runtime state lacks it.
     const cachedBody = childMeta?.body;
@@ -697,7 +847,7 @@ function buildPacket(state, childId, stateFile, telemetryFile, repoRoot, resultF
         telemetryFile,
         issueContext,
         allowedScope: resolvedScope.length > 0 ? resolvedScope : undefined,
-        maxConcurrentWorkers: 1,
+        maxConcurrentWorkers,
         promptMode: (0, worker_prompt_js_1.selectPromptMode)(childId, state),
         simplicityMode: resolveSimplicityMode(state, config),
         resultFile: canonicalPath(absoluteResultFile(repoRoot, resultFile)),
@@ -918,7 +1068,7 @@ function runLoopDispatch(options) {
         step_cursor: "dispatch",
         dispatch_boundary: (0, dispatch_boundary_js_1.advanceDispatchEpoch)(state.dispatch_boundary, childId),
     };
-    const packet = buildPacket(preliminaryState, childId, options.stateFile, telemetryFile, options.repoRoot, canonicalResultFile, loadedConfig);
+    const packet = buildPacket(preliminaryState, childId, options.stateFile, telemetryFile, options.repoRoot, canonicalResultFile, loadedConfig?.execution?.routerPolicy?.defaultWorkerPool?.maxActiveWorkers ?? 1, loadedConfig);
     const packetFailure = detectPacketGenerationFailure(packet);
     if (packetFailure) {
         appendTelemetry(telemetryFile, {
@@ -932,22 +1082,38 @@ function runLoopDispatch(options) {
         fail(`${packetFailure.message} (missing_field=${packetFailure.missingField}, child_id=${childId})`);
     }
     const targetRole = roleContextToExecutionRole(packet.role_context.role);
+    const taskType = roleContextToTaskType(packet.role_context);
+    const activeSlotsByProvider = collectActiveProviderSlots(state);
     // ── Resolve provider and dispatch mode ─────────────────────────────────────
     // loadedConfig was loaded earlier (above bootstrap seal check)
     let providerDecision;
     try {
-        providerDecision = resolveProviderAndMode(options, targetRole, loadedConfig);
+        providerDecision = resolveProviderAndMode(options, targetRole, loadedConfig, {
+            taskType,
+            requiredCapabilities: requiredCapabilitiesForTask(taskType),
+            activeSlotsByProvider,
+        });
     }
     catch (err) {
         fail(err instanceof Error ? err.message : String(err));
     }
+    // ── Handle hard-exhaustion: emit telemetry before failing ──────────────────
+    // resolveProviderAndMode returns (not throws) when all providers are rejected so
+    // emitProviderExhausted/emitProviderSelected can record the candidate breakdown.
+    if (!providerDecision.provider && providerDecision.exhaustedReason && providerDecision.routerEvidence) {
+        emitProviderExhausted(telemetryFile, dispatchId, state.run_id, childId, providerDecision);
+        emitProviderSelected(telemetryFile, dispatchId, state.run_id, childId, providerDecision);
+        fail(`provider dispatch forbidden: router rejected all providers (reason=${providerDecision.exhaustedReason})`);
+    }
     const { provider: resolvedProvider } = providerDecision;
     const providerPolicy = loadedConfig?.execution.providerPolicy ?? getProviderPolicy(options.repoRoot);
-    try {
-        assertProviderAllowedForRole(targetRole, resolvedProvider, providerPolicy, telemetryFile, dispatchId, state.run_id, childId);
-    }
-    catch (err) {
-        fail(err instanceof Error ? err.message : String(err));
+    if (!providerDecision.routerEvidence) {
+        try {
+            assertProviderAllowedForRole(targetRole, resolvedProvider, providerPolicy, telemetryFile, dispatchId, state.run_id, childId);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
     }
     // ── Provider probe on first dispatch ──────────────────────────────────────
     // Catches provider configuration failures before packet commit. Only runs on
@@ -962,6 +1128,11 @@ function runLoopDispatch(options) {
                     run_id: state.run_id,
                     child_id: childId,
                     provider: resolvedProvider,
+                    failure_origin: "provider-launch",
+                    failure_category: "provider-unavailable",
+                    pre_dispatch_failure: true,
+                    fallback_eligible: true,
+                    providers_tried: providerDecision.providersTried,
                     error: probeResult.error,
                     timestamp: new Date().toISOString(),
                 });
@@ -1080,7 +1251,7 @@ function runLoopDispatch(options) {
     if (loadedConfig) {
         let adapter;
         try {
-            adapter = (0, index_js_1.loadTrackerAdapter)(loadedConfig);
+            adapter = (0, index_js_2.loadTrackerAdapter)(loadedConfig);
         }
         catch (err) {
             const errorMsg = err instanceof Error ? err.message : String(err);

package/dist/loop/orphan-recovery.js

@@ -64,6 +64,42 @@ function hasTelemetryEvent(telemetryFile, eventName, childId) {
     catch { /* ignore */ }
     return false;
 }
+function latestProviderFailureReason(telemetryFile, childId, dispatchId) {
+    if (!(0, node_fs_1.existsSync)(telemetryFile))
+        return null;
+    try {
+        const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim().split("\n").filter(Boolean);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (!line)
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event.child_id !== childId)
+                    continue;
+                if (event.dispatch_id && event.dispatch_id !== dispatchId)
+                    continue;
+                const category = typeof event.failure_category === "string" ? event.failure_category : undefined;
+                const reason = typeof event.reason === "string" ? event.reason : undefined;
+                if (category === "quota-exhausted" || reason === "quota-exhausted") {
+                    return "quota-exhausted";
+                }
+                if (category === "provider-unavailable" ||
+                    reason === "provider-unavailable" ||
+                    event.event === "provider-probe-failed") {
+                    return "provider-unavailable";
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
 // ── Emit recovery telemetry events ───────────────────────────────────────────
 function emitRecoveryInitiated(telemetryFile, childId, dispatchId, reason) {
     appendTelemetry(telemetryFile, {
@@ -187,6 +223,26 @@ function checkOrphans(options) {
         if (dr && dr.runtime_state !== "completed" && dr.runtime_state !== "failed") {
             const dispatchedAt = new Date(dr.dispatched_at).getTime();
             const elapsed = now - dispatchedAt;
+            const providerFailure = latestProviderFailureReason(telemetryFile, state.active_child, dr.dispatch_id);
+            // Provider launch failure detected before worker-start evidence.
+            // Safe to requeue because no worker result artifact exists and there is
+            // no heartbeat/acknowledgment evidence that execution started.
+            if (providerFailure &&
+                !safeResultExists(dr.expected_result_path) &&
+                !dr.first_heartbeat_at) {
+                const detection = {
+                    childId: state.active_child,
+                    dispatchId: dr.dispatch_id,
+                    reason: providerFailure,
+                    requiresApproval: false,
+                };
+                detected.push(detection);
+                emitRecoveryInitiated(telemetryFile, state.active_child, dr.dispatch_id, providerFailure);
+                emitChildOrphaned(telemetryFile, state.active_child, dr.dispatch_id, null);
+                const newId = resetForRedispatch(options.stateFile, state, state.active_child);
+                emitChildRequeued(telemetryFile, state.active_child, newId, dr.dispatch_id);
+                return { detected, checked };
+            }
             // Scenario A: packet written, no worker_id after launch_timeout
             if (!dr.worker_id && elapsed > timeouts.launchTimeoutMs) {
                 const detection = {