@lsctech/polaris 0.5.11 → 0.5.13

package/dist/loop/continue.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTelemetryFilePath = resolveTelemetryFilePath;
 exports.runLoopContinue = runLoopContinue;
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
@@ -214,7 +215,7 @@ function appendTelemetryEvent(telemetryFile, event) {
 }
 function resolveTelemetryFilePath(state, repoRoot) {
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
-    return (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    return (0, node_path_1.resolve)(repoRoot, artifactDir, "runs", state.run_id, "telemetry.jsonl");
 }
 function hasValidationEvidence(validation) {
     if (validation === undefined || validation === null)
@@ -280,12 +281,15 @@ function bridgeEvidenceToClusterState(repoRoot, clusterId, childId, commit, rawV
         : [...existing.child_states, { id: childId, status: "done", commit: commit || undefined }];
     // Evict any stale commit entry for this child before conditionally re-adding
     const { [childId]: _staleCommit, ...remainingCommits } = existing.commits;
+    const relativeResultFile = resultFile
+        ? (0, node_path_1.relative)(repoRoot, (0, node_path_1.isAbsolute)(resultFile) ? resultFile : (0, node_path_1.resolve)(repoRoot, resultFile))
+        : resultFile;
     const updated = {
         ...existing,
         state_generation: existing.state_generation + 1,
         child_states: updatedChildStates,
         commits: commit ? { ...remainingCommits, [childId]: commit } : remainingCommits,
-        result_pointers: resultFile ? { ...existing.result_pointers, [childId]: resultFile } : existing.result_pointers,
+        result_pointers: relativeResultFile ? { ...existing.result_pointers, [childId]: relativeResultFile } : existing.result_pointers,
         validation_results: { ...existing.validation_results, [childId]: toValidationResult(rawValidation) },
     };
     (0, store_js_1.writeClusterStateSync)(clusterId, updated, repoRoot);
@@ -379,7 +383,7 @@ function runLoopContinue(options) {
     // If no dispatch was recorded (dispatch_epoch === continue_epoch),
     // reject immediately and do NOT mutate any state.
     const artifactDirForTelemetry = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
-    const telemetryFileForCheck = (0, node_path_1.join)(artifactDirForTelemetry, "runs", state.run_id, "telemetry.jsonl");
+    const telemetryFileForCheck = (0, node_path_1.resolve)(repoRoot, artifactDirForTelemetry, "runs", state.run_id, "telemetry.jsonl");
     try {
         (0, dispatch_boundary_js_1.assertContinueRequiresDispatch)(state, telemetryFileForCheck);
     }
@@ -601,10 +605,24 @@ function runLoopContinue(options) {
     }
     // Step 1 (cont): Atomic write of updated current-state.json (open_children_meta pruned after bridge)
     const sha = (0, checkpoint_js_1.writeStateAtomic)(stateFile, updatedState);
+    // Also keep the canonical cluster state snapshot in sync so finalize and
+    // direct cluster-state reads see the same completed children.
+    const canonicalStatePath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", updatedState.cluster_id, "state.json");
+    if ((0, node_path_1.resolve)(stateFile) !== (0, node_path_1.resolve)(canonicalStatePath)) {
+        try {
+            (0, checkpoint_js_1.writeStateAtomic)(canonicalStatePath, updatedState);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(`Error: primary state for cluster ${updatedState.cluster_id} was persisted, but the canonical ` +
+                `cluster state snapshot at ${canonicalStatePath} failed to update and remains stale: ${msg}`);
+            process.exit(1);
+        }
+    }
     appendContinueLedgerEvents(repoRoot, updatedState, completedChild);
     // Step 2: Append JSONL checkpoint event
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
-    const telemetryFile = (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    const telemetryFile = (0, node_path_1.resolve)(repoRoot, artifactDir, "runs", state.run_id, "telemetry.jsonl");
     (0, checkpoint_js_1.appendCheckpointEvent)(telemetryFile, {
         event: "loop-checkpoint",
         run_id: state.run_id,

package/dist/loop/dispatch.js

@@ -139,6 +139,18 @@ function resolveProviderAndMode(options, role, config, routerContext) {
         },
         compatibilityMode: false,
     });
+    const workerPolicy = exec?.providerPolicy?.[role];
+    const noFallback = workerPolicy?.noFallback === true;
+    const fallbackEligible = !noFallback && decision.providersTried.length > 1;
+    const routingSummary = {
+        selected_provider: decision.selectedProvider ?? null,
+        selected_adapter: adapter,
+        selection_reason: decision.selectionReason,
+        effective_policy_order: decision.providersTried,
+        compatibility_mode: false,
+        registry_present: true,
+        fallback_eligible: fallbackEligible,
+    };
     return {
         provider: decision.selectedProvider,
         mode: decision.mode,
@@ -157,91 +169,108 @@ function resolveProviderAndMode(options, role, config, routerContext) {
             activeSlotsByProvider: routerContext?.activeSlotsByProvider,
             quotaAvailableByProvider: routerContext?.quotaAvailableByProvider,
         },
+        routingSummary,
     };
 }
 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 noFallback = rolePolicy?.noFallback === true;
     const rotation = exec?.rotation ?? [];
-    if (roleProviders.length > 0) {
+    const configuredProviders = new Set(Object.keys(exec?.providers ?? {}));
+    let provider;
+    let selectionReason;
+    let overrideSource;
+    let fallbackFrom;
+    let fallbackReason;
+    let exhaustedReason;
+    let effectivePolicyOrder;
+    if (options.provider) {
+        provider = options.provider;
+        selectionReason = "cli-provider-override";
+        overrideSource = "dispatch-flag";
+        effectivePolicyOrder = [options.provider];
+    }
+    else if (roleProviders.length > 0) {
         // When a role policy is configured, filter the rotation to only include
         // providers that are allowed by the policy.  This ensures that a provider
         // present in rotation but absent from the policy is never selected.
         const allowedByPolicy = new Set(roleProviders);
-        const configuredProviders = new Set(Object.keys(exec?.providers ?? {}));
         const filteredRotation = rotation.filter((p) => allowedByPolicy.has(p));
+        const availablePolicyProviders = roleProviders.filter((p) => configuredProviders.has(p));
         if (filteredRotation.length > 0 && filteredRotation[0]) {
-            return {
-                provider: filteredRotation[0],
-                mode: "direct-worker",
-                adapter,
-                selectionReason: "policy-filtered-rotation",
-                providersTried: [filteredRotation[0]],
-            };
+            provider = filteredRotation[0];
+            selectionReason = "policy-filtered-rotation";
+            effectivePolicyOrder = filteredRotation.slice();
+            // Surface remaining configured policy providers as fallback alternatives
+            for (const p of availablePolicyProviders) {
+                if (!effectivePolicyOrder.includes(p)) {
+                    effectivePolicyOrder.push(p);
+                }
+            }
         }
-        // No rotation entry is in the policy — fall back to first policy provider
-        // that is actually configured.  If none is configured, fail before mutation.
-        const availablePolicyProviders = roleProviders.filter((p) => configuredProviders.has(p));
-        if (availablePolicyProviders.length > 0 && availablePolicyProviders[0]) {
-            return {
-                provider: availablePolicyProviders[0],
-                mode: "direct-worker",
-                adapter,
-                selectionReason: "role-policy",
-                providersTried: [availablePolicyProviders[0]],
-            };
+        else if (availablePolicyProviders.length > 0 && availablePolicyProviders[0]) {
+            provider = availablePolicyProviders[0];
+            selectionReason = "role-policy";
+            effectivePolicyOrder = availablePolicyProviders.slice();
+        }
+        else {
+            // No configured provider satisfies the policy — fail clearly before dispatch.
+            throw new Error(`provider dispatch forbidden: no configured provider satisfies the "${role}" role policy (policy=${roleProviders.join(",")})`);
         }
-        // No configured provider satisfies the policy — fail clearly before dispatch.
-        throw new Error(`provider dispatch forbidden: no configured provider satisfies the "${role}" role policy (policy=${roleProviders.join(",")})`);
     }
-    const roleProvider = exec?.roles?.[role]?.provider;
-    if (roleProvider) {
-        return {
-            provider: roleProvider,
-            mode: "direct-worker",
-            adapter,
-            selectionReason: "role-config",
-            providersTried: [roleProvider],
-        };
+    else if (exec?.roles?.[role]?.provider) {
+        provider = exec.roles[role].provider;
+        selectionReason = "role-config";
+        effectivePolicyOrder = [provider];
+        // If a role policy exists for this role, include its other providers as alternatives
+        for (const p of roleProviders) {
+            if (p !== provider && !effectivePolicyOrder.includes(p)) {
+                effectivePolicyOrder.push(p);
+            }
+        }
     }
-    if (rotation.length > 0 && rotation[0]) {
-        return {
-            provider: rotation[0],
-            mode: "direct-worker",
-            adapter,
-            selectionReason: "config-rotation",
-            providersTried: [rotation[0]],
-        };
+    else if (rotation.length > 0 && rotation[0]) {
+        provider = rotation[0];
+        selectionReason = "config-rotation";
+        effectivePolicyOrder = rotation.slice();
     }
-    const providers = Object.keys(exec?.providers ?? {});
-    if (providers.length > 0 && providers[0]) {
-        return {
-            provider: providers[0],
-            mode: "direct-worker",
-            adapter,
-            selectionReason: "config-first-provider",
-            fallbackFrom: "rotation",
-            fallbackReason: "rotation-empty",
-            providersTried: [providers[0]],
-        };
+    else {
+        const providers = Object.keys(exec?.providers ?? {});
+        if (providers.length > 0 && providers[0]) {
+            provider = providers[0];
+            selectionReason = "config-first-provider";
+            fallbackFrom = "rotation";
+            fallbackReason = "rotation-empty";
+            effectivePolicyOrder = providers.slice();
+        }
+        else {
+            selectionReason = "delegated-no-provider";
+            exhaustedReason = "no-configured-provider";
+            effectivePolicyOrder = [];
+        }
     }
+    const fallbackEligible = !noFallback && effectivePolicyOrder.length > 1;
+    const routingSummary = {
+        selected_provider: provider ?? null,
+        selected_adapter: adapter,
+        selection_reason: selectionReason,
+        effective_policy_order: effectivePolicyOrder,
+        compatibility_mode: true,
+        registry_present: false,
+        fallback_eligible: fallbackEligible,
+    };
     return {
-        provider: undefined,
-        mode: "delegated",
+        provider,
+        mode: provider ? "direct-worker" : "delegated",
         adapter,
-        selectionReason: "delegated-no-provider",
-        providersTried: [],
-        exhaustedReason: "no-configured-provider",
+        selectionReason,
+        overrideSource,
+        fallbackFrom,
+        fallbackReason,
+        providersTried: provider ? [provider] : [],
+        exhaustedReason,
+        routingSummary,
     };
 }
 function fail(message) {
@@ -344,7 +373,7 @@ function appendTelemetry(telemetryFile, event) {
 }
 function resolveTelemetryFile(state, repoRoot) {
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
-    return (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    return (0, node_path_1.resolve)(repoRoot, artifactDir, "runs", state.run_id, "telemetry.jsonl");
 }
 function canonicalPath(path) {
     try {
@@ -464,6 +493,7 @@ function emitProviderSelected(telemetryFile, dispatchId, runId, childId, decisio
         ...(decision.fallbackReason ? { fallback_reason: decision.fallbackReason } : {}),
         ...(decision.providersTried.length > 0 ? { providers_tried: decision.providersTried } : {}),
         ...(decision.exhaustedReason ? { router_exhausted_reason: decision.exhaustedReason } : {}),
+        ...(decision.routingSummary ? { routing_summary: decision.routingSummary } : {}),
         ...(decision.routerEvidence?.candidates?.length
             ? {
                 router_candidates: decision.routerEvidence.candidates.map((candidate) => ({
@@ -484,6 +514,7 @@ function emitProviderSelected(telemetryFile, dispatchId, runId, childId, decisio
                         active_slots: candidate.evidence.activeSlots,
                         slot_limit: candidate.evidence.slotLimit,
                         policy_matched: candidate.evidence.policyMatched,
+                        fallback_eligible: candidate.evidence.fallbackEligible,
                     },
                 })),
             }
@@ -574,7 +605,7 @@ function assertProviderAllowedForRole(role, provider, policy, telemetryFile, dis
 /**
  * Create a dispatch record with all required evidence.
  */
-function createDispatchRecord(runId, clusterId, childId, packetPath, resultPath, roleContext, provider, providerSelectionReason, providerOverrideSource, providersTried) {
+function createDispatchRecord(runId, clusterId, childId, packetPath, resultPath, roleContext, provider, providerSelectionReason, providerOverrideSource, providersTried, routingSummary) {
     const dispatchMode = determineDispatchMode(provider);
     const runtimeState = determineRuntimeState(dispatchMode);
     return {
@@ -588,6 +619,7 @@ function createDispatchRecord(runId, clusterId, childId, packetPath, resultPath,
         provider_selection_reason: providerSelectionReason,
         provider_override_source: providerOverrideSource,
         providers_tried: providersTried && providersTried.length > 0 ? providersTried : undefined,
+        routing_summary: routingSummary,
         dispatched_at: new Date().toISOString(),
         status: "dispatched",
         dispatch_mode: dispatchMode,
@@ -755,6 +787,7 @@ function ledgerLastCommit(state) {
     return state.last_commit && state.last_commit.length > 0 ? state.last_commit : null;
 }
 function appendDispatchLedgerEvent(repoRoot, state, childId) {
+    const routingSummary = state.open_children_meta?.[childId]?.dispatch_record?.routing_summary;
     new ledger_js_1.LedgerWriter((0, node_path_1.join)(repoRoot, ledger_js_1.DEFAULT_LEDGER_PATH)).append({
         schema_version: 1,
         event_id: (0, node_crypto_1.randomUUID)(),
@@ -772,6 +805,7 @@ function appendDispatchLedgerEvent(repoRoot, state, childId) {
         pr_url: null,
         timestamp: new Date().toISOString(),
         dispatch_epoch: state.dispatch_boundary?.dispatch_epoch ?? 0,
+        ...(routingSummary ? { routing_summary: routingSummary } : {}),
     });
 }
 function selectChild(state, requestedChild) {
@@ -1189,7 +1223,7 @@ function runLoopDispatch(options) {
         fail(`Failed to write packet artifact to ${packetPath}: ${errorMsg}`);
     }
     // Create dispatch record with all evidence
-    const dispatchRecord = createDispatchRecord(state.run_id, state.cluster_id, childId, relativePacketPath, relativeEffectiveResultPath, packet.role_context, resolvedProvider, providerDecision.selectionReason, providerDecision.overrideSource, providerDecision.providersTried);
+    const dispatchRecord = createDispatchRecord(state.run_id, state.cluster_id, childId, relativePacketPath, relativeEffectiveResultPath, packet.role_context, resolvedProvider, providerDecision.selectionReason, providerDecision.overrideSource, providerDecision.providersTried, providerDecision.routingSummary);
     emitProviderFallbackAttempted(telemetryFile, dispatchRecord.dispatch_id, state.run_id, childId, providerDecision);
     emitProviderExhausted(telemetryFile, dispatchRecord.dispatch_id, state.run_id, childId, providerDecision);
     emitProviderSelected(telemetryFile, dispatchRecord.dispatch_id, state.run_id, childId, providerDecision);
@@ -1245,6 +1279,7 @@ function runLoopDispatch(options) {
         dispatch_mode: dispatchRecord.dispatch_mode,
         runtime_state: dispatchRecord.runtime_state,
         provider: dispatchRecord.provider ?? null,
+        routing_summary: dispatchRecord.routing_summary ?? null,
         timestamp: new Date().toISOString(),
     });
     // ── Apply lifecycle transition for child-dispatch event ────────────────────

package/dist/loop/orphan-recovery.js

@@ -177,12 +177,13 @@ function resetForRedispatch(stateFile, state, childId) {
     if (!childMeta?.dispatch_record)
         return (0, node_crypto_1.randomUUID)();
     const newDispatchId = (0, node_crypto_1.randomUUID)();
-    // Clear dispatch record but retain audit trail via telemetry
+    // Clear dispatch record and result_file to prevent stale artifact reads
     const updatedMeta = {
         ...state.open_children_meta,
         [childId]: {
             ...childMeta,
             dispatch_record: undefined,
+            result_file: undefined,
         },
     };
     // Reset active_child so a new dispatch can proceed

package/dist/loop/parent.js

@@ -120,7 +120,7 @@ function appendTelemetry(telemetryFile, event) {
 }
 function resolveTelemetryFile(state, repoRoot) {
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
-    return (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    return (0, node_path_1.resolve)(repoRoot, artifactDir, "runs", state.run_id, "telemetry.jsonl");
 }
 function estimateTokensFromBytes(bytes) {
     return Math.round(bytes / 4);
@@ -254,6 +254,7 @@ function appendChildCompletedLedgerEvent(repoRoot, state, completedChild, lastCo
         ...(completion?.providersTried?.length
             ? { providers_tried: completion.providersTried }
             : {}),
+        ...(completion?.routingSummary ? { routing_summary: completion.routingSummary } : {}),
     });
 }
 function appendClusterCompletedLedgerEvent(repoRoot, state) {
@@ -435,6 +436,7 @@ function buildParentDispatchRecord(args) {
         provider: args.provider,
         provider_selection_reason: args.providerSelectionReason,
         providers_tried: args.providersTried,
+        routing_summary: args.routingSummary,
         dispatched_at: args.dispatchedAt,
         status: "dispatched",
         dispatch_mode: "direct-worker",
@@ -557,15 +559,16 @@ async function syncClusterCompletion(args) {
                 output: String(args.validationSummary),
             },
         };
+    const relativeResultFile = args.resultFile ? (0, node_path_1.relative)(args.repoRoot, args.resultFile) : args.resultFile;
     await (0, store_js_1.writeClusterState)(args.clusterId, {
         ...clusterState,
         state_generation: clusterState.state_generation + 1,
         child_states: childStates,
         claim_metadata: Object.fromEntries(Object.entries(clusterState.claim_metadata).filter(([childId]) => childId !== args.childId)),
-        result_pointers: args.resultFile
+        result_pointers: relativeResultFile
             ? {
                 ...clusterState.result_pointers,
-                [args.childId]: args.resultFile,
+                [args.childId]: relativeResultFile,
             }
             : clusterState.result_pointers,
         validation_results: nextValidationResults,
@@ -594,6 +597,7 @@ async function syncClusterDispatch(args) {
             }
             : child)
         : [...clusterState.child_states, { id: args.childId, status: "dispatched" }];
+    const relativePacketPath = (0, node_path_1.relative)(args.repoRoot, args.packetPath);
     await (0, store_js_1.writeClusterState)(args.clusterId, {
         ...clusterState,
         state_generation: clusterState.state_generation + 1,
@@ -608,7 +612,7 @@ async function syncClusterDispatch(args) {
         },
         packet_pointers: {
             ...clusterState.packet_pointers,
-            [args.childId]: args.packetPath,
+            [args.childId]: relativePacketPath,
         },
     }, args.repoRoot);
     return true;
@@ -681,6 +685,23 @@ async function runParentLoop(options) {
     if (!dryRun) {
         appendRunStartedLedgerEvent(repoRoot, state);
     }
+    // Keep the canonical cluster snapshot in sync with the taskchain state so
+    // `polaris status`, `polaris continue`, and `polaris finalize` always see
+    // the freshest state, even if the parent loop is interrupted before it
+    // reaches the final cluster-complete write.
+    const canonicalStatePath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "state.json");
+    const writeStateAtomic = (filePath, stateToWrite) => {
+        (0, checkpoint_js_1.writeStateAtomic)(filePath, stateToWrite);
+        if ((0, node_path_1.resolve)(filePath) !== (0, node_path_1.resolve)(canonicalStatePath)) {
+            try {
+                (0, checkpoint_js_1.writeStateAtomic)(canonicalStatePath, stateToWrite);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[polaris] canonical cluster state snapshot at ${canonicalStatePath} failed to update and remains stale: ${msg}\n`);
+            }
+        }
+    };
     // Load config for adapter and provider resolution
     const config = (0, loader_js_1.loadConfig)(repoRoot);
     const legacyOrchestrationMode = state["orchestration_mode"];
@@ -692,10 +713,20 @@ async function runParentLoop(options) {
     let providerName;
     let providerSelectionReason;
     let providersTried;
+    let routingSummary;
     if (adapterName === "agent-subtask") {
         providerName = "agent-subtask";
         providerSelectionReason = "agent-subtask-adapter";
         providersTried = ["agent-subtask"];
+        routingSummary = {
+            selected_provider: "agent-subtask",
+            selected_adapter: "agent-subtask",
+            selection_reason: "agent-subtask-adapter",
+            effective_policy_order: ["agent-subtask"],
+            compatibility_mode: false,
+            registry_present: false,
+            fallback_eligible: false,
+        };
     }
     else {
         let evidence;
@@ -713,6 +744,7 @@ async function runParentLoop(options) {
         providerName = evidence.provider ?? "default";
         providerSelectionReason = evidence.selectionReason;
         providersTried = evidence.providersTried;
+        routingSummary = evidence.routingSummary;
     }
     const executionConfig = adapterName === "agent-subtask"
         ? { ...(config.execution ?? { providers: {} }), adapter: "agent-subtask" }
@@ -1038,11 +1070,11 @@ async function runParentLoop(options) {
                             onStateUpdate: (loopState) => {
                                 // Persist loop state to the state file on each mutation.
                                 const stateWithLoop = { ...state, qc_repair_loop: loopState };
-                                (0, checkpoint_js_1.writeStateAtomic)(stateFile, stateWithLoop);
+                                writeStateAtomic(stateFile, stateWithLoop);
                             },
                         });
                         state = { ...state, qc_repair_loop: repairLoopResult.loop_state };
-                        (0, checkpoint_js_1.writeStateAtomic)(stateFile, state);
+                        writeStateAtomic(stateFile, state);
                         appendTelemetry(telemetryFile, {
                             event: "qc-repair-loop-finished",
                             run_id: state.run_id,
@@ -1164,8 +1196,7 @@ async function runParentLoop(options) {
             if (!dryRun) {
                 logStatus(notificationFormat, "COMPLETE");
                 const clusterCompleteState = { ...state, status: "cluster-complete" };
-                (0, checkpoint_js_1.writeStateAtomic)(stateFile, clusterCompleteState);
-                (0, checkpoint_js_1.writeStateAtomic)((0, node_path_1.join)(repoRoot, '.polaris', 'clusters', state.cluster_id, 'state.json'), clusterCompleteState);
+                writeStateAtomic(stateFile, clusterCompleteState);
                 appendTelemetry(telemetryFile, {
                     event: "cluster-complete",
                     run_id: state.run_id,
@@ -1225,7 +1256,7 @@ async function runParentLoop(options) {
         if (budgetCheck.status === 'exhausted') {
             // Write checkpoint before halting
             if (!dryRun) {
-                (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                writeStateAtomic(stateFile, {
                     ...state,
                     status: "budget-exhausted",
                     step_cursor: "budget-check",
@@ -1489,6 +1520,7 @@ async function runParentLoop(options) {
                 provider: providerName,
                 providerSelectionReason,
                 providersTried,
+                routingSummary,
                 workerId,
                 dispatchedAt,
             });
@@ -1498,7 +1530,7 @@ async function runParentLoop(options) {
                 step_cursor: "dispatch",
                 dispatch_boundary: (0, dispatch_boundary_js_1.advanceDispatchEpoch)(state.dispatch_boundary, nextChild),
             };
-            (0, checkpoint_js_1.writeStateAtomic)(stateFile, stateWithDispatch);
+            writeStateAtomic(stateFile, stateWithDispatch);
             state = stateWithDispatch;
             stateBeforeDispatch = stateWithDispatch;
             try {
@@ -1563,6 +1595,7 @@ async function runParentLoop(options) {
                 dry_run: dryRun,
                 selected_slot_claim: selectedSlotClaim ?? null,
                 slot_claims: nextSlotClaims,
+                routing_summary: routingSummary ?? null,
                 timestamp: new Date().toISOString(),
             });
             emitBootstrapContextSize(telemetryFile, state.run_id, nextChild, stateFile, packet);
@@ -1600,7 +1633,7 @@ async function runParentLoop(options) {
         // No result file was written. Roll back dispatch state so the run is
         // cleanly resumable without manual `loop abort` intervention.
         if (dispatchResult.pre_dispatch_failure && !dryRun) {
-            (0, checkpoint_js_1.writeStateAtomic)(stateFile, statePreDispatch);
+            writeStateAtomic(stateFile, statePreDispatch);
             appendTelemetry(telemetryFile, {
                 event: "pre-dispatch-failure",
                 run_id: state.run_id,
@@ -1751,7 +1784,7 @@ async function runParentLoop(options) {
                     timestamp: new Date().toISOString(),
                 });
                 // Write checkpoint with blocker information
-                (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                writeStateAtomic(stateFile, {
                     ...state,
                     status: "blocked",
                     step_cursor: "blocked",
@@ -2136,7 +2169,7 @@ async function runParentLoop(options) {
             childrenDispatched += 1;
             // Worker did not write its own completion — orchestrator fills the gap.
             if (!dryRun) {
-                (0, checkpoint_js_1.writeStateAtomic)(stateFile, state);
+                writeStateAtomic(stateFile, state);
             }
         }
         else {
@@ -2152,7 +2185,7 @@ async function runParentLoop(options) {
             }, nextChild);
             childrenDispatched += 1;
             if (!dryRun) {
-                (0, checkpoint_js_1.writeStateAtomic)(stateFile, state);
+                writeStateAtomic(stateFile, state);
             }
         }
         // Orchestrator checkpoint event — always emitted after a successful child.
@@ -2213,6 +2246,7 @@ async function runParentLoop(options) {
                 model: modelUsed,
                 router_selection_reason: dispatchRecord?.provider_selection_reason,
                 providers_tried: dispatchRecord?.providers_tried,
+                routing_summary: dispatchRecord?.routing_summary ?? null,
                 timestamp: new Date().toISOString(),
             };
             if (elapsedSeconds !== undefined) {
@@ -2228,6 +2262,7 @@ async function runParentLoop(options) {
                 completionStatus: workerStatus,
                 routerSelectionReason: dispatchRecord?.provider_selection_reason,
                 providersTried: dispatchRecord?.providers_tried,
+                routingSummary: dispatchRecord?.routing_summary,
             });
         }
         if (orchestrationMode === 'supervised') {
@@ -2250,7 +2285,7 @@ async function runParentLoop(options) {
             if (postBudgetCheck.status === 'exhausted') {
                 const nextPending = state.open_children[0] ?? null;
                 if (!dryRun) {
-                    (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                    writeStateAtomic(stateFile, {
                         ...state,
                         status: "budget-exhausted",
                         step_cursor: "budget-check",

package/dist/loop/router/engine.js

@@ -188,6 +188,7 @@ function decideWorkerRoute(input) {
                 activeSlots,
                 slotLimit: providerSlotLimit ?? globalSlotLimit,
                 policyMatched,
+                fallbackEligible: policy?.fallbackEligible,
             },
         });
     }

package/dist/loop/run-bootstrap.js

@@ -141,6 +141,8 @@ function runLoopBootstrapInit(options) {
     const runId = options.runId ?? deriveRunId(clusterId);
     const seal = createBootstrapSeal(runId, clusterId, openChildren);
     const deliveryBranch = branch ?? (0, git_custody_js_1.buildDeliveryBranchName)(clusterId);
+    const resolvedArtifactDir = (0, node_path_1.resolve)(repoRoot, artifactDir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run"));
+    const artifactDirValue = (0, node_path_1.relative)(repoRoot, resolvedArtifactDir);
     const initialState = {
         schema_version: "1.0",
         run_id: runId,
@@ -159,7 +161,7 @@ function runLoopBootstrapInit(options) {
         },
         status: "running",
         next_open_child: openChildren[0] ?? null,
-        artifact_dir: artifactDir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run"),
+        artifact_dir: artifactDirValue,
         dispatch_boundary: (0, dispatch_boundary_js_2.initialDispatchBoundary)(),
         run_bootstrap_seal: seal,
     };

package/dist/loop/run-preflight.js

@@ -220,7 +220,10 @@ async function ensureClusterRunState(options) {
             }
         }
     }
-    const { openChildren, openChildrenMeta } = buildBootstrapPlan(clusterId, await loadOrSyncGraph(clusterId, repoRoot), repoRoot);
+    const graph = await loadOrSyncGraph(clusterId, repoRoot);
+    const { openChildren, openChildrenMeta } = buildBootstrapPlan(clusterId, graph, repoRoot);
+    // Persist canonical child ordering and any body-derived ordering dependencies.
+    await graph.save(clusterId, repoRoot);
     await bootstrapHandler({
         clusterId,
         openChildren,