@lsctech/polaris 0.3.29 → 0.4.1

package/dist/cli/setup-interview/store.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadInterview = loadInterview;
+exports.saveInterview = saveInterview;
+exports.loadOrCreate = loadOrCreate;
+exports.applyAnswers = applyAnswers;
+exports.markApproved = markApproved;
+exports.nextUnansweredQuestion = nextUnansweredQuestion;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const schema_js_1 = require("./schema.js");
+function interviewPath(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "setup", "interview.json");
+}
+/**
+ * Load an existing interview record from disk.
+ * Returns null if the file does not exist or cannot be parsed.
+ */
+function loadInterview(repoRoot) {
+    const path = interviewPath(repoRoot);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist an interview record to .polaris/setup/interview.json. */
+function saveInterview(repoRoot, record) {
+    const path = interviewPath(repoRoot);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+}
+/**
+ * Load an existing record or create a fresh one.
+ * Supports --resume: caller passes the return value to continueInterview.
+ */
+function loadOrCreate(repoRoot, now = new Date()) {
+    return loadInterview(repoRoot) ?? (0, schema_js_1.createInterviewRecord)(now);
+}
+/** Merge new answers into the record and transition status to "answered" if appropriate. */
+function applyAnswers(record, answers) {
+    return {
+        ...record,
+        answers: { ...record.answers, ...answers },
+        status: record.status === "approved" ? "approved" : "answered",
+    };
+}
+/** Transition record to "approved" status, recording the approval timestamp. */
+function markApproved(record, now = new Date()) {
+    return {
+        ...record,
+        status: "approved",
+        approved_at: now.toISOString(),
+    };
+}
+/**
+ * Return the next unanswered required question key, or null if all are answered.
+ * Used to resume at the right question after a partial run.
+ */
+function nextUnansweredQuestion(record) {
+    const required = [
+        "project_purpose",
+        "source_roots",
+        "languages",
+        "canonical_doc_folders",
+        "never_touch",
+        "providers_by_role",
+    ];
+    return required.find((key) => record.answers[key] === undefined) ?? null;
+}

package/dist/cli/worker.js

@@ -102,17 +102,27 @@ function validateWorkerCompletionResult(repoRoot, packet, resultFile) {
         },
     };
 }
-function updateCompletionState(state, childId, commit) {
+function updateCompletionState(state, childId, commit, packet, repoRoot) {
     const completedChildren = Array.from(new Set([...state.completed_children, childId]));
     const remainingOpenChildren = state.open_children.filter((child) => child !== childId);
+    const dispatchRecord = state.open_children_meta?.[childId]?.dispatch_record;
+    const resultFile = packet.result_file_contract.result_file;
+    const telemetryFile = resolveRepoPath(repoRoot, packet.telemetry_file);
+    const packetPath = dispatchRecord?.packet_path ?? "";
+    const workerResult = (0, checkpoint_js_1.buildWorkerResultContract)({
+        state,
+        childId,
+        resultFile,
+        telemetryFile,
+        lastCommit: commit,
+        validation: "passed",
+        packetHash: packetPath ? (0, checkpoint_js_1.computePacketHashFromPath)(packetPath) : "",
+        status: "done",
+        nextRecommendedAction: "continue",
+    });
     const completedChildrenResults = {
         ...(state.completed_children_results ?? {}),
-        [childId]: {
-            status: "done",
-            validation: "passed",
-            commit,
-            next_recommended_action: "continue",
-        },
+        [childId]: workerResult,
     };
     return {
         ...state,
@@ -236,7 +246,7 @@ function createWorkerCommand(options) {
                 return;
             }
             const state = (0, checkpoint_js_1.readState)(stateFile);
-            const updatedState = updateCompletionState(state, packet.active_child, validation.result.commit);
+            const updatedState = updateCompletionState(state, packet.active_child, validation.result.commit, packet, options.repoRoot);
             (0, checkpoint_js_1.writeStateAtomic)(stateFile, updatedState);
             // Sync cluster-state.json so finalize and the parent loop see a consistent view.
             try {

package/dist/finalize/index.js

@@ -42,7 +42,7 @@ function getBranch(repoRoot) {
     }
 }
 function normalizeBranchName(branch) {
-    return branch.toLowerCase().replace(/_/g, "-");
+    return branch.toLowerCase().replace(/[_/]/g, "-");
 }
 function extractClusterSlug(clusterId) {
     const match = clusterId.match(/([A-Z]+-\d+)/);
@@ -161,13 +161,14 @@ function checkLibrarianGate(repoRoot, clusterId) {
     const filesCommitted = result.files_committed ?? [];
     for (const file of filesCommitted) {
         const absFile = (0, node_path_1.resolve)(repoRoot, file);
+        // Allowed takes precedence over prohibited — a specific allowed path wins over a broad prohibition.
+        const allowedMatch = allowedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, absFile));
+        if (allowedMatch)
+            continue;
         const prohibitedMatch = prohibitedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, absFile));
         if (prohibitedMatch) {
             return `Librarian wrote to prohibited path: ${file} (matched pattern: ${prohibitedMatch})`;
         }
-        const allowedMatch = allowedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, absFile));
-        if (allowedMatch)
-            continue; // explicitly allowed
         return `Librarian wrote to out-of-scope path: ${file} (not in allowed_write_paths)`;
     }
     try {

package/dist/loop/adapters/foreman-dispatch.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Foreman dispatch — launches the assigned Foreman with a setup-bootstrap
+ * packet through the configured execution adapter.
+ *
+ * Provider selection comes from config (`execution.providerPolicy.foreman`);
+ * no provider-specific logic lives here — the adapter handles that.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchForeman = dispatchForeman;
+const terminal_cli_js_1 = require("./terminal-cli.js");
+/**
+ * Validate that the setup-bootstrap packet has checkpoint gate enforcement.
+ *
+ * This is the "by construction" guard: a packet without a valid checkpoint_gate
+ * (or with self_approval_prohibited !== true) cannot be dispatched. Because
+ * `generateSetupBootstrapPacket` always sets self_approval_prohibited to true,
+ * any packet that fails this check was manually constructed — and is rejected.
+ *
+ * @throws {Error} if checkpoint_gate is absent or self_approval_prohibited is not true.
+ */
+function assertCheckpointGateEnforced(packet) {
+    if (!packet.checkpoint_gate || packet.checkpoint_gate.self_approval_prohibited !== true) {
+        throw new Error(`Cannot dispatch setup-bootstrap packet "${packet.packet_id}": ` +
+            `checkpoint_gate.self_approval_prohibited must be true. ` +
+            `Use generateSetupBootstrapPacket() to produce a valid packet.`);
+    }
+}
+/**
+ * Wraps a SetupBootstrapPacket into a BootstrapPacket-compatible shape
+ * that existing adapters can dispatch. The setup-bootstrap fields are
+ * carried as context so the foreman receives the full packet.
+ */
+function toBootstrapPacket(packet) {
+    return {
+        schema_version: "1.0",
+        run_id: `setup-${packet.mode}-${packet.packet_id}`,
+        cluster_id: `setup-${packet.mode}`,
+        active_child: "",
+        state_file: "",
+        telemetry_file: "",
+        context: {
+            setup_bootstrap: packet,
+        },
+    };
+}
+/**
+ * Dispatch the Foreman with the setup-bootstrap packet.
+ *
+ * Enforces checkpoint gate presence before dispatch — a packet without
+ * self_approval_prohibited: true is rejected, making self-approval
+ * impossible by construction.
+ *
+ * Uses the existing TerminalCliAdapter so provider-specific logic stays
+ * in provider configs — this function is provider-neutral.
+ */
+async function dispatchForeman(input) {
+    assertCheckpointGateEnforced(input.packet);
+    const adapter = new terminal_cli_js_1.TerminalCliAdapter(input.executionConfig);
+    const bootstrapPacket = toBootstrapPacket(input.packet);
+    return adapter.dispatch(bootstrapPacket, {
+        provider: input.provider,
+        dryRun: input.dryRun,
+    });
+}

package/dist/loop/adapters/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAdapter = exports.AgentSubtaskAdapter = exports.TerminalCliAdapter = void 0;
+exports.dispatchForeman = exports.createAdapter = exports.AgentSubtaskAdapter = exports.TerminalCliAdapter = void 0;
 var terminal_cli_js_1 = require("./terminal-cli.js");
 Object.defineProperty(exports, "TerminalCliAdapter", { enumerable: true, get: function () { return terminal_cli_js_1.TerminalCliAdapter; } });
 var agent_subtask_js_1 = require("./agent-subtask.js");
 Object.defineProperty(exports, "AgentSubtaskAdapter", { enumerable: true, get: function () { return agent_subtask_js_1.AgentSubtaskAdapter; } });
 var registry_js_1 = require("./registry.js");
 Object.defineProperty(exports, "createAdapter", { enumerable: true, get: function () { return registry_js_1.createAdapter; } });
+var foreman_dispatch_js_1 = require("./foreman-dispatch.js");
+Object.defineProperty(exports, "dispatchForeman", { enumerable: true, get: function () { return foreman_dispatch_js_1.dispatchForeman; } });

package/dist/loop/bootstrap-packet.js

@@ -71,7 +71,7 @@ function buildBootstrapPacket(state, stateFile, currentStateSha, repoRoot, compl
         last_completed_step: state.step_cursor,
         last_completed_child: completedChild,
         next_step: nextChild ? "03-execute-child" : "CLUSTER-COMPLETE",
-        open_children: state.open_children,
+        open_children: { next_child: state.open_children[0] ?? null, remaining_count: state.open_children.length },
         artifact_pointers: {
             current_state: relStateFile,
             telemetry: relTelemetryFile,

package/dist/loop/checkpoint.js

@@ -9,6 +9,10 @@ exports.appendWorkerScopeFidelityEvent = appendWorkerScopeFidelityEvent;
 exports.appendBoundaryEvent = appendBoundaryEvent;
 exports.appendAbortEvent = appendAbortEvent;
 exports.appendStaleDispatchAbortedEvent = appendStaleDispatchAbortedEvent;
+exports.toValidationStatus = toValidationStatus;
+exports.countTelemetryEvents = countTelemetryEvents;
+exports.computePacketHashFromPath = computePacketHashFromPath;
+exports.buildWorkerResultContract = buildWorkerResultContract;
 exports.readBodyFromClusterSnapshot = readBodyFromClusterSnapshot;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
@@ -268,7 +272,16 @@ function validateState(state) {
     return errors;
 }
 function writeStateAtomic(stateFile, state) {
-    const content = JSON.stringify(state, null, 2);
+    const nextChild = state.open_children[0];
+    const slimmedState = state.open_children_meta
+        ? {
+            ...state,
+            open_children_meta: Object.fromEntries(Object.entries(state.open_children_meta).map(([id, meta]) => id === nextChild
+                ? [id, meta]
+                : [id, (({ body: _b, ...rest }) => rest)(meta)])),
+        }
+        : state;
+    const content = JSON.stringify(slimmedState, null, 2);
     const tmp = `${stateFile}.tmp`;
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(stateFile), { recursive: true });
     (0, node_fs_1.writeFileSync)(tmp, content, "utf-8");
@@ -305,6 +318,112 @@ function appendStaleDispatchAbortedEvent(telemetryFile, event) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
     (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
 }
+/**
+ * Normalize a raw validation value to one of the canonical result states.
+ */
+function toValidationStatus(validation) {
+    if (typeof validation === "string") {
+        const v = validation.trim().toLowerCase();
+        if (v === "passed" || v === "failed" || v === "skipped")
+            return v;
+        if (["pass", "success", "ok"].includes(v))
+            return "passed";
+    }
+    if (validation === true)
+        return "passed";
+    if (validation === false)
+        return "failed";
+    if (typeof validation === "object" && validation !== null && !Array.isArray(validation)) {
+        const r = validation;
+        if (Array.isArray(r["passed"]) && r["passed"].length > 0)
+            return "passed";
+        if (Array.isArray(r["failed"]) && r["failed"].length > 0)
+            return "failed";
+    }
+    return "skipped";
+}
+/**
+ * Count telemetry events of a specific name for a given child.
+ * Returns 0 when the telemetry file is missing or unreadable.
+ */
+function countTelemetryEvents(telemetryFile, eventName, childId) {
+    if (!(0, node_fs_1.existsSync)(telemetryFile))
+        return 0;
+    try {
+        const content = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+        if (!content)
+            return 0;
+        let count = 0;
+        for (const line of content.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event["event"] === eventName && event["child_id"] === childId) {
+                    count += 1;
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Compute the SHA-256 hash of a packet file. Returns an empty string when
+ * the file is missing or unreadable so evidence never blocks completion.
+ */
+function computePacketHashFromPath(packetPath) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)(packetPath, "utf-8");
+        return (0, node_crypto_1.createHash)("sha256").update(raw, "utf-8").digest("hex");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Build a WorkerResultContract from the durable dispatch state and telemetry.
+ * Missing optional values are filled with safe defaults so the record is always
+ * complete enough for retroactive scoring.
+ */
+function buildWorkerResultContract(args) {
+    const dispatchRecord = args.state.open_children_meta?.[args.childId]?.dispatch_record;
+    const role = dispatchRecord?.role ?? "worker";
+    const provider = dispatchRecord?.provider ?? "unknown";
+    const workerId = dispatchRecord?.worker_id ?? dispatchRecord?.dispatch_id ?? "unknown";
+    const packetPath = dispatchRecord?.packet_path ?? "";
+    const heartbeatCount = countTelemetryEvents(args.telemetryFile, "worker-heartbeat", args.childId);
+    const escalationCount = countTelemetryEvents(args.telemetryFile, "worker-blocked", args.childId);
+    return {
+        child_id: args.childId,
+        status: args.status ?? "done",
+        validation: toValidationStatus(args.validation),
+        commit: args.lastCommit,
+        next_recommended_action: args.nextRecommendedAction ?? "continue",
+        run_id: args.state.run_id,
+        cluster_id: args.state.cluster_id,
+        skill_name: args.state.skill ?? null,
+        role,
+        provider,
+        packet_hash: args.packetHash,
+        worker_id: workerId,
+        escalation_count: escalationCount,
+        heartbeat_count: heartbeatCount,
+        result_artifact_path: args.resultFile,
+        packet_path: packetPath,
+        telemetry_path: args.telemetryFile,
+        user_intervened: null,
+        foreman_intervened: null,
+        dispatch_epoch: args.state.dispatch_boundary?.dispatch_epoch,
+        session_pointer: null,
+        result_data: args.resultData,
+    };
+}
 /**
  * Reads the issue body for a node from the durable cluster snapshot at
  * `.polaris/clusters/<clusterId>/clusters.json`. Returns undefined when the

package/dist/loop/continue.js

@@ -482,12 +482,20 @@ function runLoopContinue(options) {
         ...(state.completed_children_results ?? {}),
     };
     if (completedChild && completionResultFile) {
-        updatedCompletedChildrenResults[completedChild] = {
+        const telemetryFile = resolveTelemetryFilePath(state, repoRoot);
+        const dispatchRecord = state.open_children_meta?.[completedChild]?.dispatch_record;
+        const packetPath = dispatchRecord?.packet_path ?? "";
+        updatedCompletedChildrenResults[completedChild] = (0, checkpoint_js_1.buildWorkerResultContract)({
+            state,
+            childId: completedChild,
+            resultFile: completionResultFile,
+            telemetryFile,
+            lastCommit: completionCommit || null,
+            validation: completionValidation,
+            packetHash: packetPath ? (0, checkpoint_js_1.computePacketHashFromPath)(packetPath) : "",
             status: "done",
-            validation: hasValidationEvidence(completionValidation) ? "passed" : "skipped",
-            commit: completionCommit || null,
-            next_recommended_action: "continue",
-        };
+            nextRecommendedAction: "continue",
+        });
     }
     const updatedState = {
         ...state,

package/dist/loop/parent.js

@@ -110,6 +110,26 @@ 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");
 }
+function estimateTokensFromBytes(bytes) {
+    return Math.round(bytes / 4);
+}
+function emitBootstrapContextSize(telemetryFile, runId, childId, stateFile, packet) {
+    const stateFileBytes = (0, node_fs_1.statSync)(stateFile).size;
+    const bootstrapPacketBytes = Buffer.byteLength(JSON.stringify(packet), "utf-8");
+    const stateEstimatedTokens = estimateTokensFromBytes(stateFileBytes);
+    const bootstrapEstimatedTokens = estimateTokensFromBytes(bootstrapPacketBytes);
+    appendTelemetry(telemetryFile, {
+        event: "bootstrap-context-size",
+        run_id: runId,
+        child_id: childId,
+        state_file_bytes: stateFileBytes,
+        state_estimated_tokens: stateEstimatedTokens,
+        bootstrap_packet_bytes: bootstrapPacketBytes,
+        bootstrap_estimated_tokens: bootstrapEstimatedTokens,
+        combined_estimated_tokens: stateEstimatedTokens + bootstrapEstimatedTokens,
+        timestamp: new Date().toISOString(),
+    });
+}
 /**
  * Select the next open child that is not Done/blocked.
  * Returns null when all children are completed.
@@ -300,6 +320,74 @@ function buildPacket(state, activeChild, stateFile, telemetryFile, repoRoot, res
 function absoluteResultFile(repoRoot, filePath) {
     return (0, node_path_1.isAbsolute)(filePath) ? filePath : (0, node_path_1.resolve)(repoRoot, filePath);
 }
+/**
+ * Flush bodies from open_children_meta to the durable clusters.json snapshot.
+ * Called once before the dispatch loop so that writeStateAtomic (which strips
+ * body from non-next children) does not cause data loss when the loop reloads
+ * state from disk between dispatches.
+ *
+ * Only writes nodes that have a body in open_children_meta but lack one in the
+ * existing snapshot. Never removes or overwrites existing body data.
+ * Never throws.
+ */
+function flushBodiesToClusterSnapshot(state, repoRoot) {
+    const meta = state.open_children_meta;
+    if (!meta)
+        return;
+    const snapshotPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "clusters.json");
+    let snapshot = {};
+    try {
+        const raw = (0, node_fs_1.readFileSync)(snapshotPath, "utf-8");
+        snapshot = JSON.parse(raw);
+    }
+    catch (err) {
+        // Distinguish "file not found" from "present but corrupted"
+        if (err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT') {
+            // File absent — start fresh
+            snapshot = {
+                schemaVersion: "v2",
+                source: { id: state.cluster_id, type: "local" },
+                nodes: {},
+                dependencies: {},
+                clusters: { [state.cluster_id]: { id: state.cluster_id, title: state.cluster_id, children: state.open_children } },
+                activeCluster: state.cluster_id,
+            };
+        }
+        else {
+            // File present but corrupted — do not overwrite
+            return;
+        }
+    }
+    if (typeof snapshot.nodes !== "object" || snapshot.nodes === null) {
+        snapshot.nodes = {};
+    }
+    let changed = false;
+    for (const [id, childMeta] of Object.entries(meta)) {
+        const body = childMeta?.body;
+        if (!body || body.trim().length === 0)
+            continue;
+        const existing = snapshot.nodes[id];
+        if (existing && existing.body && existing.body.trim().length > 0)
+            continue;
+        snapshot.nodes[id] = {
+            ...(existing ?? {}),
+            id,
+            title: childMeta.title ?? existing?.title ?? id,
+            body,
+            status: existing?.status ?? "Todo",
+        };
+        changed = true;
+    }
+    if (!changed)
+        return;
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(snapshotPath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
+    }
+    catch {
+        // Best-effort — do not fail the loop if snapshot write fails
+    }
+}
 function buildClusterArtifactPaths(repoRoot, clusterId, childId, dispatchId) {
     const clusterDir = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId);
     const filename = `${childId}-${dispatchId}.json`;
@@ -629,6 +717,14 @@ async function runParentLoop(options) {
         }
     }
     let childrenDispatched = 0;
+    // ── Flush bodies to clusters.json before stripping begins ──────────────
+    // writeStateAtomic strips body from all open_children_meta entries except
+    // open_children[0]. Flush any bodies present in open_children_meta to the
+    // durable cluster snapshot so readBodyFromClusterSnapshot can hydrate them
+    // on subsequent iterations after reload from disk.
+    if (!dryRun) {
+        flushBodiesToClusterSnapshot(state, repoRoot);
+    }
     // ── Lifecycle manager: enforce one-active-worker policy ─────────────────
     // forceReleaseAll() clears any orphaned registrations from a previous
     // crashed session. Registrations are session-memory only; they are not
@@ -986,6 +1082,7 @@ async function runParentLoop(options) {
                 dry_run: dryRun,
                 timestamp: new Date().toISOString(),
             });
+            emitBootstrapContextSize(telemetryFile, state.run_id, nextChild, stateFile, packet);
         }
         let dispatchResult;
         try {
@@ -1284,6 +1381,10 @@ async function runParentLoop(options) {
             else {
                 state = reloadedState;
                 reloadedStateValid = true;
+                // Flush bodies from worker-updated state to clusters.json before any stripping
+                if (!dryRun) {
+                    flushBodiesToClusterSnapshot(state, repoRoot);
+                }
             }
         }
         catch (err) {
@@ -1410,9 +1511,28 @@ async function runParentLoop(options) {
             }
         }
         // workerStatus === "done" has already been validated upstream.
+        // Build the durable Role Evidence Contract for this completed child.
+        const nextRecommendedAction = summaryAsRecord?.['next_recommended_action'] === 'continue' ||
+            summaryAsRecord?.['next_recommended_action'] === 'stop' ||
+            summaryAsRecord?.['next_recommended_action'] === 'investigate'
+            ? summaryAsRecord['next_recommended_action']
+            : 'continue';
+        const workerResult = (0, checkpoint_js_1.buildWorkerResultContract)({
+            state,
+            childId: nextChild,
+            resultFile: packet.result_file_contract.result_file,
+            telemetryFile,
+            lastCommit: lastCommit ?? null,
+            validation: validationSummary,
+            packetHash: (0, checkpoint_js_1.computePacketHashFromPath)(packetPath),
+            status: 'done',
+            nextRecommendedAction,
+            resultData: summaryAsRecord?.['result_data'],
+        });
         // If the reloaded state already reflects the completed child,
         // the worker owns the completion checkpoint and the parent
-        // must not rewrite it.
+        // must not rewrite the open/closed lists, but it still records the
+        // Role Evidence Contract so scoring can consume it later.
         if (!workerWroteCompletion) {
             // ── Dispatch boundary: verify dispatch happened before advancing ──────
             // The parent dispatched via adapter, so dispatch_boundary should show
@@ -1444,6 +1564,10 @@ async function runParentLoop(options) {
             state = {
                 ...advanced,
                 dispatch_boundary: (0, dispatch_boundary_js_1.advanceContinueEpoch)(state.dispatch_boundary),
+                completed_children_results: {
+                    ...advanced.completed_children_results,
+                    [nextChild]: workerResult,
+                },
             };
             childrenDispatched += 1;
             // Worker did not write its own completion — orchestrator fills the gap.
@@ -1457,6 +1581,10 @@ async function runParentLoop(options) {
             state = {
                 ...state,
                 dispatch_boundary: (0, dispatch_boundary_js_1.advanceContinueEpoch)(state.dispatch_boundary),
+                completed_children_results: {
+                    ...state.completed_children_results,
+                    [nextChild]: workerResult,
+                },
             };
             childrenDispatched += 1;
             if (!dryRun) {

package/dist/loop/resume.js

@@ -61,7 +61,7 @@ const OPEN_CHILD_STATUSES = new Set([
 ]);
 function findClusterStateForPacket(repoRoot, packet) {
     const clustersDir = (0, node_path_1.resolve)(repoRoot, ".polaris", "clusters");
-    const hints = new Set([packet.last_completed_child, ...packet.open_children].filter((value) => typeof value === "string" && value.length > 0));
+    const hints = new Set([packet.last_completed_child, packet.open_children.next_child].filter((value) => typeof value === "string" && value.length > 0));
     let entries;
     try {
         entries = (0, node_fs_1.readdirSync)(clustersDir, { withFileTypes: true })
@@ -96,12 +96,16 @@ function rebuildLoopStateFromClusterState(packet, clusterState, repoRoot) {
     const completedChildren = clusterState.child_states
         .filter((child) => COMPLETED_CHILD_STATUSES.has(child.status))
         .map((child) => child.id);
-    const openChildren = packet.open_children.filter((childId) => clusterChildren.has(childId));
-    const fallbackOpenChildren = openChildren.length > 0
-        ? openChildren
-        : clusterState.child_states
-            .filter((child) => OPEN_CHILD_STATUSES.has(child.status))
-            .map((child) => child.id);
+    // Reconstruct full open queue from all open child_states
+    const allOpenChildren = clusterState.child_states
+        .filter((child) => OPEN_CHILD_STATUSES.has(child.status))
+        .map((child) => child.id);
+    // Place next_child first if present, then append remaining open children
+    const nextChild = packet.open_children.next_child;
+    const openChildren = nextChild && clusterChildren.has(nextChild)
+        ? [nextChild, ...allOpenChildren.filter((id) => id !== nextChild)]
+        : allOpenChildren;
+    const fallbackOpenChildren = openChildren;
     const activeChild = fallbackOpenChildren.find((childId) => {
         const status = clusterState.child_states.find((child) => child.id === childId)?.status;
         return status === "claimed" || status === "dispatched" || status === "running";
@@ -177,7 +181,9 @@ function appendResumedLedgerEvent(repoRoot, packet, state) {
         : [];
     const openChildren = Array.isArray(state.open_children)
         ? state.open_children
-        : packet.open_children;
+        : packet.open_children.next_child
+            ? [packet.open_children.next_child]
+            : [];
     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)(),

package/dist/loop/worker-packet.js

@@ -250,7 +250,7 @@ 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}.`,
-        `Write compact return JSON to stdout (fields: ${exports.IMPL_RETURN_CONTRACT.join(', ')}).`,
+        `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.`,
     ];
     // Build compact or full prompt; primary_goal uses the structured template.