@lsctech/polaris 0.1.0

package/dist/loop/continue.js

@@ -0,0 +1,645 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLoopContinue = runLoopContinue;
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const store_js_1 = require("../cluster-state/store.js");
+const git_custody_js_1 = require("./git-custody.js");
+const checkpoint_js_1 = require("./checkpoint.js");
+const bootstrap_packet_js_1 = require("./bootstrap-packet.js");
+const loader_js_1 = require("../config/loader.js");
+const canon_check_js_1 = require("../smartdocs-engine/canon-check.js");
+const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
+const ledger_js_1 = require("./ledger.js");
+const librarian_dispatch_js_1 = require("../cognition/librarian-dispatch.js");
+/** Resolves the expected sealed result file path for a child from its dispatch metadata. */
+function resolveResultFileForChild(state, childId) {
+    const meta = state.open_children_meta?.[childId];
+    return meta?.result_file ?? meta?.dispatch_record?.expected_result_path ?? null;
+}
+/**
+ * Verifies that a completed child has adequate sealed-result evidence before checkpointing.
+ * When a worker has pre-moved itself into completed_children, falls through to full evidence
+ * check if a result file is present rather than accepting stale state.
+ */
+function verifyCompletionEvidenceForContinue(state, completedChild, repoRoot) {
+    const resultFile = resolveResultFileForChild(state, completedChild);
+    const resolvedResultFile = resultFile
+        ? (0, node_path_1.isAbsolute)(resultFile)
+            ? resultFile
+            : (0, node_path_1.resolve)(repoRoot, resultFile)
+        : null;
+    if (state.completed_children.includes(completedChild)) {
+        // Worker pre-moved itself into completed_children (protocol violation, but tolerated).
+        // Fall through to full evidence check when a result file exists; otherwise accept as-is.
+        if (!resolvedResultFile || !(0, node_fs_1.existsSync)(resolvedResultFile)) {
+            return { ok: true, commit: state.last_commit ?? "", rawValidation: undefined, resultFile: "" };
+        }
+    }
+    if (!resultFile || !resolvedResultFile) {
+        return {
+            ok: false,
+            reason: `cannot checkpoint ${completedChild}: no result_file evidence found in state metadata`,
+        };
+    }
+    if (!(0, node_fs_1.existsSync)(resolvedResultFile)) {
+        return {
+            ok: false,
+            reason: `cannot checkpoint ${completedChild}: expected result file is missing (${resultFile})`,
+        };
+    }
+    let parsed;
+    try {
+        const content = (0, node_fs_1.readFileSync)(resolvedResultFile, "utf-8");
+        const raw = JSON.parse(content);
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return {
+                ok: false,
+                reason: `cannot checkpoint ${completedChild}: result file has invalid JSON shape`,
+            };
+        }
+        parsed = raw;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `cannot checkpoint ${completedChild}: failed to read result file (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    const status = String(parsed["status"] ?? "").trim().toLowerCase();
+    if (!["done", "success"].includes(status)) {
+        return {
+            ok: false,
+            reason: `cannot checkpoint ${completedChild}: result status is "${status || "unknown"}" (expected done/success)`,
+        };
+    }
+    const commit = String(parsed["commit"] ?? parsed["commit_hash"] ?? "").trim();
+    if (!commit) {
+        if (!readPacketFlag(state, completedChild, repoRoot, "artifact_only")) {
+            return {
+                ok: false,
+                reason: `cannot checkpoint ${completedChild}: result file is missing commit evidence`,
+            };
+        }
+        return { ok: true, commit: "", rawValidation: parsed["validation"], resultFile };
+    }
+    // Reject placeholder strings that are not valid git hashes (hex, ≥7 chars)
+    if (!/^[0-9a-f]{7,}$/i.test(commit)) {
+        return {
+            ok: false,
+            reason: `cannot checkpoint ${completedChild}: result commit "${commit}" is not a valid git hash (expected hex string of ≥7 chars)`,
+        };
+    }
+    return { ok: true, commit, rawValidation: parsed["validation"], resultFile };
+}
+function resolvePacketPath(state, childId, repoRoot) {
+    const dispatchRecord = state.open_children_meta?.[childId]?.dispatch_record;
+    const packetPath = dispatchRecord?.packet_path;
+    if (!packetPath)
+        return null;
+    return (0, node_path_1.isAbsolute)(packetPath) ? packetPath : (0, node_path_1.resolve)(repoRoot, packetPath);
+}
+function readPacketFlag(state, childId, repoRoot, flag) {
+    const packetPath = resolvePacketPath(state, childId, repoRoot);
+    if (!packetPath || !(0, node_fs_1.existsSync)(packetPath))
+        return undefined;
+    try {
+        const packet = JSON.parse((0, node_fs_1.readFileSync)(packetPath, "utf-8"));
+        const fromRoot = packet[flag];
+        if (fromRoot !== undefined)
+            return fromRoot;
+        const instructions = packet["instructions"];
+        if (instructions && typeof instructions === "object" && !Array.isArray(instructions)) {
+            return instructions[flag];
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPacketAllowedScope(state, childId, repoRoot) {
+    const packetPath = resolvePacketPath(state, childId, repoRoot);
+    if (!packetPath || !(0, node_fs_1.existsSync)(packetPath))
+        return [];
+    try {
+        const packet = JSON.parse((0, node_fs_1.readFileSync)(packetPath, "utf-8"));
+        const instructions = packet["instructions"];
+        if (!instructions || typeof instructions !== "object" || Array.isArray(instructions))
+            return [];
+        const allowedScope = instructions["allowed_scope"];
+        if (!Array.isArray(allowedScope))
+            return [];
+        return allowedScope.filter((entry) => typeof entry === "string");
+    }
+    catch {
+        return [];
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
+}
+function globPatternToRegExp(pattern) {
+    let re = "^";
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === "*") {
+            if (pattern[i + 1] === "*") {
+                if (pattern[i + 2] === "/") {
+                    re += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    re += ".*";
+                    i++;
+                }
+            }
+            else {
+                re += "[^/]*";
+            }
+            continue;
+        }
+        if (char === "?") {
+            re += "[^/]";
+            continue;
+        }
+        re += escapeRegExp(char);
+    }
+    re += "$";
+    return new RegExp(re);
+}
+function matchesAllowedScope(filePath, allowedScope) {
+    if (allowedScope.length === 0)
+        return false;
+    return allowedScope.some((pattern) => globPatternToRegExp(pattern).test(filePath));
+}
+function getChildCommitFiles(repoRoot, commit) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["show", "--format=", "--name-only", "--no-renames", commit], { cwd: repoRoot, encoding: "utf-8" }).trim();
+        if (!output)
+            return [];
+        return Array.from(new Set(output.split("\n").map((line) => line.trim()).filter(Boolean)));
+    }
+    catch {
+        return [];
+    }
+}
+function countLoopAbortedEvents(telemetryFile, runId) {
+    if (!(0, node_fs_1.existsSync)(telemetryFile))
+        return 0;
+    const content = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+    if (!content)
+        return 0;
+    return content
+        .split("\n")
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((event) => !!event)
+        .filter((event) => event.event === "loop-aborted" && event.run_id === runId)
+        .length;
+}
+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");
+}
+function hasValidationEvidence(validation) {
+    if (validation === undefined || validation === null)
+        return false;
+    if (typeof validation === "boolean")
+        return validation;
+    if (typeof validation === "string") {
+        const n = validation.trim().toLowerCase();
+        return ["passed", "pass", "success", "ok"].includes(n);
+    }
+    if (typeof validation === "object" && !Array.isArray(validation)) {
+        const v = validation;
+        if (Array.isArray(v["passed"]) && v["passed"].length > 0)
+            return true;
+        if (v["passed"] === true)
+            return true;
+        if (typeof v["status"] === "string" && ["passed", "pass", "success", "ok"].includes(v["status"].toLowerCase()))
+            return true;
+    }
+    return false;
+}
+function isValidationWaiver(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return Object.keys(value).length > 0;
+    return false;
+}
+function toValidationResult(rawValidation) {
+    return {
+        passed: hasValidationEvidence(rawValidation),
+        output: typeof rawValidation === "string"
+            ? rawValidation
+            : rawValidation != null ? JSON.stringify(rawValidation) : "",
+    };
+}
+function extractWorkNotePathsFromResult(resultFile, repoRoot) {
+    try {
+        const resolvedPath = (0, node_path_1.isAbsolute)(resultFile) ? resultFile : (0, node_path_1.resolve)(repoRoot, resultFile);
+        if (!(0, node_fs_1.existsSync)(resolvedPath))
+            return [];
+        const content = (0, node_fs_1.readFileSync)(resolvedPath, "utf-8");
+        const parsed = JSON.parse(content);
+        const paths = parsed["work_note_paths"];
+        if (Array.isArray(paths) && paths.every((p) => typeof p === "string")) {
+            return paths;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+function bridgeEvidenceToClusterState(repoRoot, clusterId, childId, commit, rawValidation, resultFile) {
+    const existing = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
+    if (!existing) {
+        throw new Error(`cluster-state.json not found for cluster ${clusterId}; cannot persist evidence for ${childId}`);
+    }
+    const updatedChildStates = existing.child_states.some((cs) => cs.id === childId)
+        ? existing.child_states.map((cs) => cs.id === childId ? { ...cs, status: "done", commit: commit || undefined } : cs)
+        : [...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 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,
+        validation_results: { ...existing.validation_results, [childId]: toValidationResult(rawValidation) },
+    };
+    (0, store_js_1.writeClusterStateSync)(clusterId, updated, repoRoot);
+}
+function readSessionTypeFile(repoRoot) {
+    try {
+        return (0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, ".polaris", "session-type"), "utf-8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function getNextChildType(state, nextChild) {
+    if (!nextChild)
+        return undefined;
+    return state.open_children_meta?.[nextChild]?.type;
+}
+function isAnalyzeImplBoundary(sessionType, nextChildType) {
+    return sessionType === "analyze" && nextChildType === "implement";
+}
+function normalizeRunType(sessionType) {
+    return sessionType === "analyze" ? "analyze" : "implement";
+}
+function ledgerBranch(state) {
+    return state.branch ?? "unknown";
+}
+function ledgerLastCommit(state) {
+    return state.last_commit && state.last_commit.length > 0 ? state.last_commit : null;
+}
+function appendContinueLedgerEvents(repoRoot, state, completedChild) {
+    if (!completedChild)
+        return;
+    const writer = new ledger_js_1.LedgerWriter((0, node_path_1.join)(repoRoot, ledger_js_1.DEFAULT_LEDGER_PATH));
+    const timestamp = new Date().toISOString();
+    const base = {
+        schema_version: 1,
+        event_id: (0, node_crypto_1.randomUUID)(),
+        run_id: state.run_id,
+        run_type: normalizeRunType(state.session_type),
+        cluster_id: state.cluster_id,
+        branch: ledgerBranch(state),
+        completed_children: Array.from(new Set(state.completed_children)),
+        open_children: state.open_children,
+        next_child: state.next_open_child,
+        last_commit: ledgerLastCommit(state),
+        pr_url: null,
+        timestamp,
+    };
+    writer.append({
+        ...base,
+        event: "child-completed",
+        issue_id: completedChild,
+        status: state.status === "cluster-complete" ? "cluster-complete" : "running",
+        last_commit: ledgerLastCommit(state),
+        validation: { status: "complete" },
+    });
+    if (state.open_children.length === 0) {
+        const telemetryFile = resolveTelemetryFilePath(state, repoRoot);
+        writer.append({
+            ...base,
+            event_id: (0, node_crypto_1.randomUUID)(),
+            event: "cluster-complete",
+            issue_id: null,
+            status: "cluster-complete",
+            open_children: [],
+            next_child: null,
+            recovery_count: countLoopAbortedEvents(telemetryFile, state.run_id),
+        });
+    }
+}
+function runLoopContinue(options) {
+    const { stateFile, repoRoot, provider, allowAnalyzeChildren } = options;
+    // Step 1: Read and validate current-state.json
+    let rawState;
+    try {
+        rawState = (0, checkpoint_js_1.readState)(stateFile);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: cannot read state file ${stateFile}: ${msg}`);
+        process.exit(1);
+    }
+    const validationErrors = (0, checkpoint_js_1.validateState)(rawState);
+    if (validationErrors.length > 0) {
+        console.error(`current-state.json is invalid — cannot generate bootstrap packet:\n${validationErrors.join("\n")}`);
+        process.exit(1);
+    }
+    const state = rawState;
+    // ── Dispatch boundary enforcement ─────────────────────────────────────────
+    // continue MUST be preceded by a `polaris loop dispatch` call.
+    // 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");
+    try {
+        (0, dispatch_boundary_js_1.assertContinueRequiresDispatch)(state, telemetryFileForCheck);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+    // Identify the completed child:
+    // - If active_child is set, use it (standard case)
+    // - If dispatch_epoch > continue_epoch but active_child is empty,
+    //   resolve from dispatch_boundary.last_dispatched_child
+    let completedChild = state.active_child;
+    if (!completedChild && state.dispatch_boundary) {
+        const { dispatch_epoch, continue_epoch, last_dispatched_child } = state.dispatch_boundary;
+        if (dispatch_epoch > continue_epoch && last_dispatched_child) {
+            completedChild = last_dispatched_child;
+        }
+    }
+    const remainingOpenChildren = completedChild
+        ? state.open_children.filter((child) => child !== completedChild)
+        : state.open_children;
+    const nextChild = remainingOpenChildren[0] ?? null;
+    let completionCommit = "";
+    let completionResultFile = "";
+    let completionValidation = undefined;
+    if (state.dispatch_boundary && completedChild) {
+        const evidence = verifyCompletionEvidenceForContinue(state, completedChild, repoRoot);
+        if (!evidence.ok) {
+            console.error(`Error: ${evidence.reason}`);
+            process.exit(1);
+        }
+        completionCommit = evidence.commit;
+        completionResultFile = evidence.resultFile;
+        completionValidation = evidence.rawValidation;
+        // ── Branch custody check ──────────────────────────────────────────────────
+        // Reject commits that are already reachable from the base branch.
+        // This catches the case where a worker committed directly to main instead
+        // of to the delivery branch.
+        if (completionCommit) {
+            const custodyState = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+            if (custodyState?.delivery_branch && custodyState?.base_branch) {
+                const custodyError = (0, git_custody_js_1.verifyChildCommitCustody)(repoRoot, completionCommit, custodyState.delivery_branch, custodyState.base_branch);
+                if (custodyError) {
+                    console.error(`Error: branch custody violation for ${completedChild}: ${custodyError}`);
+                    process.exit(1);
+                }
+            }
+        }
+        if (!hasValidationEvidence(completionValidation)) {
+            const waiver = readPacketFlag(state, completedChild, repoRoot, "validation_waiver");
+            if (!isValidationWaiver(waiver)) {
+                console.error(`Error: cannot checkpoint ${completedChild}: result file has no passing validation evidence and no validation_waiver was set in the packet`);
+                process.exit(1);
+            }
+        }
+    }
+    if (completedChild && completionResultFile) {
+        const telemetryFile = resolveTelemetryFilePath(state, repoRoot);
+        try {
+            (0, checkpoint_js_1.appendCompactReturnReceivedEvent)(telemetryFile, {
+                event: "compact-return-received",
+                run_id: state.run_id,
+                child_id: completedChild,
+                size_bytes: (0, node_fs_1.statSync)((0, node_path_1.isAbsolute)(completionResultFile) ? completionResultFile : (0, node_path_1.resolve)(repoRoot, completionResultFile)).size,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch {
+            // Telemetry is best-effort; state progression must continue.
+        }
+        try {
+            const allowedScope = readPacketAllowedScope(state, completedChild, repoRoot);
+            const actualFilesTouched = completionCommit ? getChildCommitFiles(repoRoot, completionCommit) : [];
+            const outOfScopeFiles = actualFilesTouched.filter((file) => !matchesAllowedScope(file, allowedScope));
+            (0, checkpoint_js_1.appendWorkerScopeFidelityEvent)(telemetryFile, {
+                event: "worker-scope-fidelity",
+                run_id: state.run_id,
+                child_id: completedChild,
+                allowed_scope: allowedScope,
+                actual_files_touched: actualFilesTouched,
+                out_of_scope_files: outOfScopeFiles,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch {
+            // Telemetry is best-effort; state progression must continue.
+        }
+    }
+    // Determine session type (state field takes precedence, file is secondary signal)
+    const sessionTypeFile = readSessionTypeFile(repoRoot);
+    const sessionType = state.session_type ?? sessionTypeFile;
+    if (sessionTypeFile && !state.session_type) {
+        console.warn(`Warning: session_type not in state; using .polaris/session-type file: ${sessionTypeFile}`);
+    }
+    // Update state: mark active_child as completed
+    const newCompletedChildren = completedChild
+        ? Array.from(new Set([...state.completed_children, completedChild]))
+        : state.completed_children;
+    const completedSet = new Set(newCompletedChildren);
+    const prunedOpenChildrenMeta = state.open_children_meta
+        ? Object.fromEntries(Object.entries(state.open_children_meta).filter(([id]) => !completedSet.has(id)))
+        : undefined;
+    // Record per-child result summary in loop state (belt-and-suspenders for finalize evidence)
+    const updatedCompletedChildrenResults = {
+        ...(state.completed_children_results ?? {}),
+    };
+    if (completedChild && completionResultFile) {
+        updatedCompletedChildrenResults[completedChild] = {
+            status: "done",
+            validation: hasValidationEvidence(completionValidation) ? "passed" : "skipped",
+            commit: completionCommit || null,
+            next_recommended_action: "continue",
+        };
+    }
+    const updatedState = {
+        ...state,
+        active_child: "",
+        completed_children: newCompletedChildren,
+        completed_children_results: Object.keys(updatedCompletedChildrenResults).length > 0
+            ? updatedCompletedChildrenResults
+            : state.completed_children_results,
+        open_children: remainingOpenChildren,
+        open_children_meta: prunedOpenChildrenMeta,
+        step_cursor: "checkpoint",
+        next_open_child: nextChild,
+        status: nextChild ? "running" : "cluster-complete",
+        context_budget: {
+            ...state.context_budget,
+            children_completed: newCompletedChildren.length,
+        },
+        last_commit: completionCommit || state.last_commit,
+        // Advance continue_epoch to match the consumed dispatch_epoch
+        dispatch_boundary: (0, dispatch_boundary_js_1.advanceContinueEpoch)(state.dispatch_boundary),
+    };
+    // Bridge evidence to cluster-state BEFORE committing the pruned loop state.
+    // Failing here leaves open_children_meta intact so the operator can retry.
+    if (state.dispatch_boundary && completedChild && completionResultFile) {
+        try {
+            bridgeEvidenceToClusterState(repoRoot, state.cluster_id, completedChild, completionCommit, completionValidation, completionResultFile);
+        }
+        catch (error) {
+            console.error(`Error: failed to persist cluster-state evidence for ${completedChild}: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    }
+    // 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);
+    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");
+    (0, checkpoint_js_1.appendCheckpointEvent)(telemetryFile, {
+        event: "loop-checkpoint",
+        run_id: state.run_id,
+        child_id: completedChild,
+        next_child: nextChild,
+        timestamp: new Date().toISOString(),
+    });
+    // Load config early — needed for canon check and adapter selection
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const effectiveConfig = {
+        ...config,
+        execution: provider
+            ? {
+                ...config.execution,
+                rotation: [
+                    provider,
+                    ...(config.execution.rotation ?? []).filter((name) => name !== provider),
+                ],
+            }
+            : config.execution,
+        budget: allowAnalyzeChildren === undefined
+            ? config.budget
+            : {
+                ...config.budget,
+                allow_analyze_children: allowAnalyzeChildren,
+            },
+    };
+    const effectiveExecution = {
+        ...effectiveConfig.execution,
+        allow_analyze_children: effectiveConfig.budget?.allow_analyze_children,
+    };
+    // Map update runs once at session end (step 08 / polaris finalize), not per checkpoint.
+    // Step 3.5: Canon reconciliation check
+    const canonCheckEnabled = effectiveConfig.canon?.checkOnContinue !== false;
+    if (canonCheckEnabled && nextChild) {
+        const changedFiles = updatedState["changed_files"] ?? [];
+        const canonResult = (0, canon_check_js_1.runCanonCheck)({
+            repoRoot,
+            changedFiles,
+            childId: nextChild,
+            runId: state.run_id,
+            telemetryFile,
+        });
+        if (canonResult.outcome === "stale-implementation") {
+            const conflict = canonResult.conflicts.find((c) => c.type === "stale-implementation");
+            process.stderr.write([
+                `Canon conflict halt — cannot generate bootstrap packet.`,
+                `Canon file: ${conflict?.canonFile ?? "unknown"}`,
+                `Statement: ${conflict?.statement ?? ""}`,
+                `Affected file: ${conflict?.changedFile ?? ""}`,
+                `Detail: ${conflict?.detail ?? ""}`,
+                `Resolution: Update the canon file or implement the missing piece before continuing.`,
+            ].join("\n") + "\n");
+            process.exit(1);
+        }
+    }
+    // Step 4: Analyze→implementation boundary check
+    const nextChildType = getNextChildType(state, nextChild);
+    const boundaryTriggered = isAnalyzeImplBoundary(sessionType, nextChildType);
+    if (boundaryTriggered) {
+        (0, checkpoint_js_1.appendBoundaryEvent)(telemetryFile, {
+            event: "analyze-impl-boundary-enforced",
+            run_id: state.run_id,
+            stopped_before: nextChild,
+            reason: "analyze session cannot auto-continue into implementation",
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // Step 4.5: Dispatch cognition librarian (non-blocking — failure does not halt cluster execution)
+    if (completedChild && completionResultFile) {
+        const workNotePaths = extractWorkNotePathsFromResult(completionResultFile, repoRoot);
+        if (workNotePaths.length > 0) {
+            setImmediate(async () => {
+                try {
+                    const adapter = (options.adapter ?? effectiveExecution.adapter);
+                    if (adapter) {
+                        await (0, librarian_dispatch_js_1.dispatchCognitionLibrarian)({
+                            runId: state.run_id,
+                            clusterId: state.cluster_id,
+                            workNotePaths,
+                            repoRoot,
+                            adapter: adapter,
+                            provider: provider ?? effectiveConfig.execution.rotation?.[0] ?? "codex",
+                            telemetryFile,
+                        });
+                    }
+                }
+                catch (err) {
+                    // Non-blocking: log to telemetry but continue execution
+                    try {
+                        (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify({
+                            event: "cognition-librarian-dispatch-error",
+                            run_id: state.run_id,
+                            child_id: completedChild,
+                            error: err instanceof Error ? err.message : String(err),
+                            timestamp: new Date().toISOString(),
+                        }) + "\n", "utf-8");
+                    }
+                    catch {
+                        console.warn(`Warning: failed to dispatch cognition librarian for ${completedChild}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            });
+        }
+    }
+    // Steps 4-5: Generate and write bootstrap packet
+    const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(updatedState, stateFile, sha, repoRoot, completedChild, (options.adapter ?? effectiveExecution.adapter), effectiveExecution);
+    if (boundaryTriggered) {
+        packet.boundary_enforcement =
+            "analyze-session-ended; implementation requires fresh session with explicit impl scope";
+    }
+    const bootstrapDir = (0, node_path_1.join)(repoRoot, ".polaris", "bootstrap");
+    const packetPath = (0, bootstrap_packet_js_1.writeBootstrapPacket)(packet, bootstrapDir);
+    // Step 6: Emit bootstrap packet to stdout, exit 0
+    console.log(JSON.stringify(packet, null, 2));
+    process.stderr.write(`Bootstrap packet written to: ${packetPath}\n`);
+}