@lsctech/polaris 0.1.0

package/dist/loop/parent.js

@@ -0,0 +1,1566 @@
+"use strict";
+/**
+ * Scheduler-only parent loop.
+ *
+ * The parent loop is a pure scheduler: it reads cluster state, selects the
+ * next open child, dispatches a worker via the configured execution adapter,
+ * receives a compact return JSON, checks the budget, and loops or halts.
+ *
+ * The parent MUST NOT inline-execute child work. Every child is dispatched
+ * to an external worker. "ADAPTER HANDOFF" means dispatch + continue the loop;
+ * it is NOT a signal to halt the parent session.
+ *
+ * Loop steps:
+ *   01 – Load cluster / read current-state.json
+ *   02 – Select next open child (lowest-numbered, not Done/blocked)
+ *   03 – Dispatch worker via configured adapter
+ *   04 – Receive and validate compact worker return JSON
+ *   05 – Check budget policy
+ *   06 – CONTINUE (back to step 02) or halt (STOP / CLUSTER COMPLETE)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runParentLoop = runParentLoop;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const git_custody_js_1 = require("./git-custody.js");
+const checkpoint_js_1 = require("./checkpoint.js");
+const registry_js_1 = require("./adapters/registry.js");
+const budget_js_1 = require("./budget.js");
+const loader_js_1 = require("../config/loader.js");
+const store_js_1 = require("../cluster-state/store.js");
+const lifecycle_js_1 = require("./lifecycle.js");
+const worker_packet_js_1 = require("./worker-packet.js");
+const worker_prompt_js_1 = require("./worker-prompt.js");
+const body_parser_js_1 = require("./body-parser.js");
+const node_child_process_1 = require("node:child_process");
+const artifact_policy_js_1 = require("../finalize/artifact-policy.js");
+const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
+const run_bootstrap_js_1 = require("./run-bootstrap.js");
+const ledger_js_1 = require("./ledger.js");
+const dispatch_js_1 = require("./dispatch.js");
+const index_js_1 = require("../tracker/index.js");
+const lifecycle_transition_js_1 = require("../tracker/lifecycle-transition.js");
+const CLAIM_TTL_MS = 30 * 60 * 1000;
+/**
+ * Returns the list of files touched by a git commit, or null when the commit
+ * cannot be resolved (short hash in a non-repo context, or non-existent object).
+ * Returns null (fail-open) for short/non-hex hashes so test environments using
+ * synthetic commit strings like "abc1234" are not blocked by the artifact gate.
+ * For full 40-char SHAs, resolves via git and returns null on any git failure.
+ */
+function defaultGetCommitFiles(commit, repoRoot) {
+    if (!/^[0-9a-f]{40}$/i.test(commit)) {
+        // Short or non-hex hash — cannot verify without git resolution; skip check.
+        return null;
+    }
+    try {
+        // Resolve the ref to a commit OID, rejecting non-commit refs.
+        const resolvedCommit = (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--verify", `${commit}^{commit}`], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+        const output = (0, node_child_process_1.execFileSync)("git", ["show", "--name-only", "--format=", resolvedCommit], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        });
+        return output.trim().split("\n").filter(Boolean);
+    }
+    catch {
+        // Cannot resolve even a full-looking SHA — skip check rather than block.
+        return null;
+    }
+}
+/**
+ * Returns true when a parsed `## Goal` section text looks like placeholder
+ * or template content that has not been filled in.
+ * Impl-only gate — analyze children are exempted by their caller.
+ */
+function isPlaceholderGoal(goal) {
+    const t = goal.trim().toLowerCase();
+    if (t.length === 0)
+        return true;
+    if (t === 'tbd')
+        return true;
+    if (t.startsWith('tbd ') || t.startsWith('tbd—') || t.startsWith('tbd -') || t.startsWith('tbd:'))
+        return true;
+    if (t === 'todo')
+        return true;
+    if (t.startsWith('todo:') || t.startsWith('todo '))
+        return true;
+    if (t === 'placeholder')
+        return true;
+    if (t.startsWith('[placeholder]') || t.startsWith('<<') || t.startsWith('<placeholder'))
+        return true;
+    return false;
+}
+function logStatus(format, message) {
+    if (format === "terse") {
+        process.stdout.write(`[POLARIS] ${message}\n`);
+    }
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ────────────────────────────────────────────────────────────────────────────
+function appendTelemetry(telemetryFile, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+}
+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");
+}
+/**
+ * Select the next open child that is not Done/blocked.
+ * Returns null when all children are completed.
+ */
+function selectNextChild(state) {
+    return state.open_children[0] ?? null;
+}
+/**
+ * Returns true when the given child is detected as an analyze issue.
+ * Detection is intentionally conservative: title prefix or label match only.
+ */
+function isAnalyzeChild(childId, state) {
+    const meta = state.open_children_meta?.[childId];
+    if (!meta)
+        return false;
+    const title = meta.title ?? "";
+    if (title.startsWith("Analyze:") || title.startsWith("polaris-analyze"))
+        return true;
+    if (meta.labels?.includes("analyze"))
+        return true;
+    return false;
+}
+/**
+ * Returns true when the cluster root is an ANALYZE issue.
+ */
+function isAnalyzeParent(state) {
+    const meta = state.open_children_meta?.[state.cluster_id];
+    if (!meta)
+        return false;
+    const title = meta.title ?? "";
+    if (title.startsWith("ANALYZE:"))
+        return true;
+    if (meta.labels?.includes("analyze"))
+        return true;
+    return false;
+}
+/** Normalise a file path to its canonical realpath (resolves macOS /var → /private/var symlinks). */
+function canonicalPath(p) {
+    try {
+        return (0, node_fs_1.realpathSync)(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Returns the current git branch, or "unknown" on failure. */
+function getCurrentBranch(cwd) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["branch", "--show-current"], {
+            cwd,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return process.env["POLARIS_BRANCH"] ?? "unknown";
+    }
+}
+function normalizeRunType(sessionType) {
+    return sessionType === "analyze" ? "analyze" : "implement";
+}
+function ledgerLastCommit(state) {
+    return state.last_commit && state.last_commit.length > 0 ? state.last_commit : null;
+}
+function appendRunStartedLedgerEvent(repoRoot, state) {
+    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)(),
+        event: "run-started",
+        run_id: state.run_id,
+        run_type: normalizeRunType(state.session_type),
+        cluster_id: state.cluster_id,
+        issue_id: state.active_child || null,
+        branch: state.branch ?? getCurrentBranch(repoRoot),
+        status: "running",
+        completed_children: state.completed_children,
+        open_children: state.open_children,
+        next_child: state.next_open_child,
+        last_commit: ledgerLastCommit(state),
+        pr_url: null,
+        timestamp: new Date().toISOString(),
+    });
+}
+function appendChildCompletedLedgerEvent(repoRoot, state, completedChild, lastCommit, validation) {
+    const writer = new ledger_js_1.LedgerWriter((0, node_path_1.join)(repoRoot, ledger_js_1.DEFAULT_LEDGER_PATH));
+    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: state.branch ?? getCurrentBranch(repoRoot),
+        completed_children: state.completed_children,
+        open_children: state.open_children,
+        next_child: state.next_open_child,
+        last_commit: ledgerLastCommit(state),
+        pr_url: null,
+        timestamp: new Date().toISOString(),
+    };
+    writer.append({
+        ...base,
+        event: "child-completed",
+        issue_id: completedChild,
+        status: state.status === "cluster-complete" ? "cluster-complete" : "running",
+        last_commit: lastCommit,
+        validation: typeof validation === "object" && validation !== null
+            ? { status: "complete", ...validation }
+            : { status: "complete" },
+    });
+}
+function appendClusterCompletedLedgerEvent(repoRoot, state) {
+    const writer = new ledger_js_1.LedgerWriter((0, node_path_1.join)(repoRoot, ledger_js_1.DEFAULT_LEDGER_PATH));
+    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: state.branch ?? getCurrentBranch(repoRoot),
+        completed_children: state.completed_children,
+        open_children: state.open_children,
+        next_child: state.next_open_child,
+        last_commit: ledgerLastCommit(state),
+        pr_url: null,
+        timestamp: new Date().toISOString(),
+    };
+    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: 0,
+    });
+}
+/**
+ * Builds the compiled WorkerPacket used to dispatch an implementation (impl) child.
+ *
+ * @param stateFile - Absolute path to the current-state.json file used by the worker
+ * @param telemetryFile - Path to the telemetry JSONL file the worker should append to
+ * @param repoRoot - Repository root used to resolve branch and paths
+ * @param resultFile - Optional override path where the worker should write its result
+ * @returns The compiled WorkerPacket configured for `activeChild`
+ */
+function buildPacket(state, activeChild, stateFile, telemetryFile, repoRoot, resultFile) {
+    const branch = state.branch ?? getCurrentBranch(repoRoot);
+    const childMeta = state.open_children_meta?.[activeChild];
+    // Hydrate body from cluster snapshot when runtime state lacks it.
+    const cachedBody = childMeta?.body;
+    const resolvedChildBody = (cachedBody && cachedBody.trim().length > 0)
+        ? cachedBody
+        : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, activeChild, repoRoot);
+    const issueContext = (childMeta || resolvedChildBody)
+        ? {
+            id: activeChild,
+            title: childMeta?.title ?? activeChild,
+            key_requirements: [],
+            body: resolvedChildBody,
+        }
+        : undefined;
+    // Scope precedence: child body → parent/cluster-root body fallback.
+    // Derive here so compileImplPacket receives an authoritative scope list
+    // rather than falling back to [] when the child body has no scope section.
+    const childScope = resolvedChildBody ? (0, body_parser_js_1.parseIssueBody)(resolvedChildBody).scope : [];
+    const cachedParentBody = state.open_children_meta?.[state.cluster_id]?.body;
+    const parentBodyForScope = (cachedParentBody && cachedParentBody.trim().length > 0)
+        ? cachedParentBody
+        : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, state.cluster_id, repoRoot) ?? '';
+    const resolvedScope = childScope.length > 0
+        ? childScope
+        : (0, body_parser_js_1.parseIssueBody)(parentBodyForScope).scope;
+    const promptMode = (0, worker_prompt_js_1.selectPromptMode)(activeChild, state);
+    return (0, worker_packet_js_1.compileImplPacket)({
+        runId: state.run_id,
+        clusterId: state.cluster_id,
+        childId: activeChild,
+        branch,
+        stateFile: canonicalPath(stateFile),
+        telemetryFile,
+        issueContext,
+        allowedScope: resolvedScope.length > 0 ? resolvedScope : undefined,
+        maxConcurrentWorkers: 1,
+        promptMode,
+        resultFile,
+    });
+}
+function absoluteResultFile(repoRoot, filePath) {
+    return (0, node_path_1.isAbsolute)(filePath) ? filePath : (0, node_path_1.resolve)(repoRoot, filePath);
+}
+function buildClusterArtifactPaths(repoRoot, clusterId, childId, dispatchId) {
+    const clusterDir = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId);
+    const filename = `${childId}-${dispatchId}.json`;
+    return {
+        packetPath: (0, node_path_1.join)(clusterDir, "packets", filename),
+        resultPath: (0, node_path_1.join)(clusterDir, "results", filename),
+    };
+}
+function writePacketArtifact(packetPath, packet) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(packetPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(packetPath, JSON.stringify(packet, null, 2), "utf-8");
+}
+function childResultFilePath(state, childId, repoRoot, dispatchId) {
+    const configured = state.open_children_meta?.[childId]?.result_file;
+    if (configured && configured.trim().length > 0) {
+        return absoluteResultFile(repoRoot, configured);
+    }
+    return buildClusterArtifactPaths(repoRoot, state.cluster_id, childId, dispatchId).resultPath;
+}
+function buildParentDispatchRecord(args) {
+    return {
+        dispatch_id: args.dispatchId,
+        child_id: args.childId,
+        run_id: args.runId,
+        cluster_id: args.clusterId,
+        packet_path: args.packetPath,
+        expected_result_path: args.resultPath,
+        provider: args.provider,
+        dispatched_at: args.dispatchedAt,
+        status: "dispatched",
+        dispatch_mode: "direct-worker",
+        runtime_state: "packet-created",
+        worker_id: args.workerId,
+        session_id: null,
+        attachment_capable: false,
+        role: "worker",
+        role_authority: "implementation",
+        may_implement: true,
+        session_type: "implementation",
+    };
+}
+function withChildDispatchMetadata(state, childId, resultFile, dispatchRecord) {
+    const current = state.open_children_meta?.[childId];
+    if (current?.result_file === resultFile &&
+        current.dispatch_record?.dispatch_id === dispatchRecord.dispatch_id) {
+        return state;
+    }
+    return {
+        ...state,
+        open_children_meta: {
+            ...(state.open_children_meta ?? {}),
+            [childId]: {
+                ...(current ?? {}),
+                result_file: resultFile,
+                dispatch_record: dispatchRecord,
+            },
+        },
+    };
+}
+/**
+ * Parse a compact worker return JSON from the dispatch result summary.
+ * Returns null if parsing fails.
+ */
+function parseWorkerSummary(summary) {
+    if (!summary)
+        return null;
+    try {
+        const parsed = JSON.parse(summary);
+        if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Update state after a child completes successfully.
+ * Moves the child from open_children to completed_children.
+ */
+function advanceState(state, completedChild, lastCommit) {
+    const remaining = state.open_children.filter((c) => c !== completedChild);
+    const completed = [...state.completed_children, completedChild];
+    return {
+        ...state,
+        active_child: "",
+        open_children: remaining,
+        completed_children: completed,
+        next_open_child: remaining[0] ?? null,
+        step_cursor: "checkpoint",
+        status: remaining.length > 0 ? "running" : "cluster-complete",
+        last_commit: lastCommit ?? state.last_commit,
+        context_budget: {
+            ...state.context_budget,
+            children_completed: completed.length,
+        },
+    };
+}
+async function syncClusterCompletion(args) {
+    const clusterState = await (0, store_js_1.readClusterState)(args.clusterId, args.repoRoot);
+    if (!clusterState) {
+        console.warn(`[polaris] syncClusterCompletion: no cluster state found for clusterId=${args.clusterId}; skipping sync`);
+        return false;
+    }
+    const childStates = clusterState.child_states.some((child) => child.id === args.childId)
+        ? clusterState.child_states.map((child) => child.id === args.childId
+            ? {
+                ...child,
+                status: "done",
+                commit: args.lastCommit ?? child.commit,
+            }
+            : child)
+        : [
+            ...clusterState.child_states,
+            {
+                id: args.childId,
+                status: "done",
+                ...(args.lastCommit ? { commit: args.lastCommit } : {}),
+            },
+        ];
+    const nextValidationResults = args.validationSummary === undefined
+        ? clusterState.validation_results
+        : {
+            ...clusterState.validation_results,
+            [args.childId]: {
+                passed: true,
+                output: String(args.validationSummary),
+            },
+        };
+    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
+            ? {
+                ...clusterState.result_pointers,
+                [args.childId]: args.resultFile,
+            }
+            : clusterState.result_pointers,
+        validation_results: nextValidationResults,
+        commits: args.lastCommit
+            ? {
+                ...clusterState.commits,
+                [args.childId]: args.lastCommit,
+            }
+            : clusterState.commits,
+    }, args.repoRoot);
+    return true;
+}
+async function syncClusterDispatch(args) {
+    const clusterState = await (0, store_js_1.readClusterState)(args.clusterId, args.repoRoot);
+    if (!clusterState) {
+        console.warn(`[polaris] syncClusterDispatch: no cluster state found for clusterId=${args.clusterId}; skipping sync`);
+        return false;
+    }
+    const dispatchedAtMs = new Date(args.dispatchedAt).getTime();
+    const expiresAt = new Date(Number.isFinite(dispatchedAtMs) ? dispatchedAtMs + CLAIM_TTL_MS : Date.now() + CLAIM_TTL_MS).toISOString();
+    const childStates = clusterState.child_states.some((child) => child.id === args.childId)
+        ? clusterState.child_states.map((child) => child.id === args.childId
+            ? {
+                ...child,
+                status: "dispatched",
+            }
+            : child)
+        : [...clusterState.child_states, { id: args.childId, status: "dispatched" }];
+    await (0, store_js_1.writeClusterState)(args.clusterId, {
+        ...clusterState,
+        state_generation: clusterState.state_generation + 1,
+        child_states: childStates,
+        claim_metadata: {
+            ...clusterState.claim_metadata,
+            [args.childId]: {
+                worker_id: args.workerId,
+                claimed_at: args.dispatchedAt,
+                expires_at: expiresAt,
+            },
+        },
+        packet_pointers: {
+            ...clusterState.packet_pointers,
+            [args.childId]: args.packetPath,
+        },
+    }, args.repoRoot);
+    return true;
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Main parent loop
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Run the scheduler-only parent loop.
+ *
+ * This function is the entry point for the `polaris loop run` command and
+ * for programmatic use. It loops until a halt condition is reached, then
+ * returns a structured result describing why it halted.
+ */
+async function runParentLoop(options) {
+    const { stateFile, repoRoot, dryRun = false, allowAnalyzeChildren: allowAnalyzeChildrenFlag = false } = options;
+    // getCommitFiles intentionally read via options.getCommitFiles in the gate below
+    // ── Step 01: Load cluster / read current-state.json ─────────────────────
+    let state;
+    try {
+        const rawState = (0, checkpoint_js_1.readState)(stateFile);
+        const errors = (0, checkpoint_js_1.validateState)(rawState);
+        if (errors.length > 0) {
+            return {
+                haltReason: 'state-invalid',
+                childrenDispatched: 0,
+                message: `current-state.json is invalid:\n${errors.join("\n")}`,
+            };
+        }
+        state = rawState;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            haltReason: 'state-invalid',
+            childrenDispatched: 0,
+            message: `Cannot read state file ${stateFile}: ${msg}`,
+        };
+    }
+    if (isAnalyzeParent(state)) {
+        return {
+            haltReason: 'analyze-parent',
+            childrenDispatched: 0,
+            message: "polaris-run targets IMPLEMENT parents, not ANALYZE issues. Run polaris-analyze first to create an IMPLEMENT parent.",
+        };
+    }
+    // ── Bootstrap seal enforcement ─────────────────────────────────────────────
+    // The run MUST have been initialized through `polaris loop bootstrap`.
+    // Refuse to enter the dispatch loop if the state was hand-crafted.
+    const earlyTelemetry = resolveTelemetryFile(state, repoRoot);
+    try {
+        (0, run_bootstrap_js_1.assertBootstrapSeal)(state, earlyTelemetry);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!dryRun) {
+            appendTelemetry(earlyTelemetry, {
+                event: "bootstrap-seal-missing",
+                run_id: state.run_id,
+                error: msg,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        return {
+            haltReason: 'state-invalid',
+            childrenDispatched: 0,
+            message: msg,
+        };
+    }
+    if (!dryRun) {
+        appendRunStartedLedgerEvent(repoRoot, state);
+    }
+    // Load config for adapter and provider resolution
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const legacyOrchestrationMode = state["orchestration_mode"];
+    const legacyEphemeralMode = options.adapter === undefined && legacyOrchestrationMode === "ephemeral";
+    const orchestrationMode = config.orchestration?.mode ?? (legacyOrchestrationMode === "ephemeral" ? "auto" : "supervised");
+    const telemetryOrchestrationMode = legacyOrchestrationMode === "ephemeral" ? "ephemeral" : orchestrationMode;
+    const notificationFormat = config.orchestration?.notification_format ?? (orchestrationMode === 'auto' ? 'terse' : 'verbose');
+    const adapterName = legacyEphemeralMode ? "agent-subtask" : (options.adapter ?? config.execution?.adapter ?? "terminal-cli");
+    let providerName;
+    if (adapterName === "agent-subtask") {
+        providerName = "agent-subtask";
+    }
+    else {
+        let evidence;
+        try {
+            evidence = (0, dispatch_js_1.resolveProviderAndMode)({ stateFile, repoRoot, provider: options.provider }, "worker", config);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                haltReason: "worker-error",
+                childrenDispatched: 0,
+                message: msg,
+            };
+        }
+        providerName = evidence.provider ?? "default";
+    }
+    const executionConfig = adapterName === "agent-subtask"
+        ? { ...(config.execution ?? { providers: {} }), adapter: "agent-subtask" }
+        : config.execution ?? { adapter: adapterName, providers: {} };
+    const adapter = (0, registry_js_1.createAdapter)(adapterName, executionConfig);
+    const budgetPolicy = (0, budget_js_1.policyFromConfig)(state.context_budget, config.budget);
+    const allowAnalyzeChildren = allowAnalyzeChildrenFlag || (config.budget?.allow_analyze_children === true);
+    const telemetryFile = resolveTelemetryFile(state, repoRoot);
+    // Enforce provider policy for explicit --provider flag before entering the loop.
+    // resolveProviderAndMode handles policy-filtered rotation; this gate blocks an
+    // explicit provider that the rotation resolution would not have chosen.
+    if (options.provider && adapterName !== "agent-subtask") {
+        try {
+            (0, dispatch_js_1.assertProviderAllowedForRole)("worker", options.provider, config.execution?.providerPolicy, telemetryFile, "parent-preflight", state.run_id, "pre-loop");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                haltReason: "worker-error",
+                childrenDispatched: 0,
+                message: msg,
+            };
+        }
+    }
+    // ── Branch pre-flight ──────────────────────────────────────────────────────
+    // Ensure the working tree is on the cluster's delivery branch before any
+    // worker is dispatched. Without this, workers commit to whatever branch the
+    // operator left HEAD on (often main), bypassing delivery-branch custody and
+    // making PR creation impossible for those commits.
+    if (!dryRun && adapterName !== "agent-subtask") {
+        const deliveryBranch = state.branch;
+        if (deliveryBranch && deliveryBranch.trim().length > 0) {
+            const currentBranch = getCurrentBranch(repoRoot);
+            if (currentBranch !== "unknown" && currentBranch !== deliveryBranch) {
+                try {
+                    (0, git_custody_js_1.ensureDeliveryBranch)(repoRoot, deliveryBranch);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        haltReason: 'worker-error',
+                        childrenDispatched: 0,
+                        message: `Branch pre-flight: cannot switch to delivery branch "${deliveryBranch}" (current: "${currentBranch}"): ${msg}`,
+                    };
+                }
+            }
+        }
+    }
+    let childrenDispatched = 0;
+    // ── 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
+    // persisted to disk, so a fresh loop start always begins clean.
+    const lifecycle = new lifecycle_js_1.WorkerLifecycleManager(1);
+    lifecycle.forceReleaseAll();
+    // ── Main dispatch loop ───────────────────────────────────────────────────
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        // ── Step 02: Select next open child ─────────────────────────────────
+        const nextChild = selectNextChild(state);
+        if (nextChild === null) {
+            const autoFinalizeRequested = orchestrationMode === "auto" && config.orchestration?.auto_finalize === true;
+            // All children completed — write final state and halt
+            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);
+                appendTelemetry(telemetryFile, {
+                    event: "cluster-complete",
+                    run_id: state.run_id,
+                    children_completed: state.completed_children.length,
+                    timestamp: new Date().toISOString(),
+                });
+                appendClusterCompletedLedgerEvent(repoRoot, { ...state, status: "cluster-complete" });
+                if (autoFinalizeRequested) {
+                    appendTelemetry(telemetryFile, {
+                        event: "auto-finalize-requested",
+                        run_id: state.run_id,
+                        next_action: "polaris finalize run",
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+            }
+            const messageSuffix = autoFinalizeRequested
+                ? " Auto-finalize handoff requested; run `polaris finalize run` to complete delivery."
+                : "";
+            return {
+                haltReason: 'cluster-complete',
+                childrenDispatched,
+                message: `Cluster complete. All ${state.completed_children.length} children dispatched.${messageSuffix}`,
+            };
+        }
+        // ── Step 02 (post-select): Analyze-drift guardrail ───────────────────
+        if (!allowAnalyzeChildren && isAnalyzeChild(nextChild, state)) {
+            const errMsg = [
+                `ERROR: Next child ${nextChild} is an analyze issue.`,
+                `Loop halted to prevent recursive analysis drift.`,
+                ``,
+                `To override:`,
+                `  polaris.config.json → budget.allow_analyze_children: true`,
+                `  or: polaris loop continue --allow-analyze-children`,
+            ].join("\n");
+            process.stderr.write(errMsg + "\n");
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "analyze-drift-halt",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'analyze-drift',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: errMsg,
+            };
+        }
+        // ── Step 05 (pre-dispatch): Check budget before dispatching ─────────
+        const budgetCheck = (0, budget_js_1.checkBudget)({
+            childrenCompleted: state.context_budget.children_completed,
+            policy: budgetPolicy,
+        });
+        if (budgetCheck.status === 'exhausted') {
+            // Write checkpoint before halting
+            if (!dryRun) {
+                (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                    ...state,
+                    status: "budget-exhausted",
+                    step_cursor: "budget-check",
+                    next_open_child: nextChild,
+                });
+                appendTelemetry(telemetryFile, {
+                    event: "budget-exhausted",
+                    run_id: state.run_id,
+                    children_completed: state.context_budget.children_completed,
+                    next_child: nextChild,
+                    reason: budgetCheck.reason,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'budget-exhausted',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: budgetCheck.reason,
+            };
+        }
+        // ── Dispatch boundary guard ──────────────────────────────────────────────
+        //
+        // HARD CONSTRAINT: The parent/orchestrator MUST NOT execute child work
+        // inline. If active_child is already set, a previous dispatch was not
+        // properly completed — halt and require manual resolution.
+        //
+        // This guard also fires if the runtime somehow reached a child-execution
+        // state without a dispatch event (e.g. state corruption or inline attempt).
+        try {
+            (0, dispatch_boundary_js_1.assertNoActiveChildBeforeDispatch)(state, telemetryFile);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "invalid-inline-attempt",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    reason: msg,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: msg,
+            };
+        }
+        // ── Child body preflight gate ────────────────────────────────────────────
+        //
+        // HARD GATE: Every child MUST have a resolvable body/description before
+        // dispatch. Runtime state is checked first (cache); if absent, the durable
+        // cluster snapshot (.polaris/clusters/<id>/clusters.json) is the fallback.
+        // If neither source has a body, tell the operator to run tracker sync-in.
+        {
+            const cachedChildBody = state.open_children_meta?.[nextChild]?.body;
+            const childBody = (cachedChildBody && cachedChildBody.trim().length > 0)
+                ? cachedChildBody
+                : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, nextChild, repoRoot);
+            if (!dryRun && (!childBody || childBody.trim().length === 0)) {
+                const errMsg = `Child ${nextChild} has no body/description; cannot generate actionable packet. ` +
+                    `Run 'tracker sync-in ${state.cluster_id}' to populate issue body data from Linear.`;
+                appendTelemetry(telemetryFile, {
+                    event: "preflight-body-missing",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    haltReason: 'preflight-failed',
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: errMsg,
+                };
+            }
+        }
+        // ── Child scope preflight gate ───────────────────────────────────────────
+        //
+        // HARD GATE: Every impl child MUST have a derivable allowed_scope before
+        // dispatch. Scope is parsed from the child's body "## Scope" / "## Expected
+        // code areas" section, with fallback to the cluster-root (parent) body.
+        // Both sources check runtime state first, then the cluster snapshot.
+        // A packet with empty allowed_scope would block the worker immediately —
+        // fail here with a clear error instead.
+        // Analyze children are exempt since they don't produce impl packets.
+        {
+            const cachedChildBody = state.open_children_meta?.[nextChild]?.body;
+            const childBody = (cachedChildBody && cachedChildBody.trim().length > 0)
+                ? cachedChildBody
+                : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, nextChild, repoRoot) ?? '';
+            if (!dryRun && childBody.trim().length > 0 && !isAnalyzeChild(nextChild, state)) {
+                const { scope: childScope } = (0, body_parser_js_1.parseIssueBody)(childBody);
+                if (childScope.length === 0) {
+                    // Fallback: check the cluster-root (parent) body for scope
+                    const cachedParentBody = state.open_children_meta?.[state.cluster_id]?.body;
+                    const parentBody = (cachedParentBody && cachedParentBody.trim().length > 0)
+                        ? cachedParentBody
+                        : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, state.cluster_id, repoRoot) ?? '';
+                    const { scope: parentScope } = (0, body_parser_js_1.parseIssueBody)(parentBody);
+                    if (parentScope.length === 0) {
+                        const errMsg = `Child ${nextChild} body has no scope section; cannot generate actionable packet. ` +
+                            `Add a "## Scope" section with explicit repo paths or globs. ` +
+                            `If scope is unknown, write "- TBD — BLOCKED: scope missing" and mark the issue as Blocked in Linear.`;
+                        appendTelemetry(telemetryFile, {
+                            event: "preflight-scope-missing",
+                            run_id: state.run_id,
+                            child_id: nextChild,
+                            timestamp: new Date().toISOString(),
+                        });
+                        return {
+                            haltReason: 'preflight-failed',
+                            childrenDispatched,
+                            haltingChild: nextChild,
+                            message: errMsg,
+                        };
+                    }
+                }
+            }
+        }
+        // ── Placeholder primary goal gate ───────────────────────────────────────
+        //
+        // HARD GATE (impl only): The child's ## Goal section must not be empty or
+        // placeholder text. A placeholder goal means the issue was never properly
+        // authored — dispatching would produce meaningless or incorrect work.
+        // Analyze children are exempt since they are not implementation issues.
+        {
+            const cachedChildBodyForGoal = state.open_children_meta?.[nextChild]?.body;
+            const childBody = (cachedChildBodyForGoal && cachedChildBodyForGoal.trim().length > 0)
+                ? cachedChildBodyForGoal
+                : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, nextChild, repoRoot) ?? '';
+            if (!dryRun && childBody.trim().length > 0 && !isAnalyzeChild(nextChild, state)) {
+                const { goal } = (0, body_parser_js_1.parseIssueBody)(childBody);
+                if (isPlaceholderGoal(goal)) {
+                    const errMsg = `Child ${nextChild} body has a placeholder primary goal; cannot generate actionable packet. ` +
+                        `Fill in the "## Goal" section with a specific, actionable objective.`;
+                    appendTelemetry(telemetryFile, {
+                        event: "preflight-placeholder-goal",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        timestamp: new Date().toISOString(),
+                    });
+                    return {
+                        haltReason: 'preflight-failed',
+                        childrenDispatched,
+                        haltingChild: nextChild,
+                        message: errMsg,
+                    };
+                }
+            }
+        }
+        // ── Step 03: Dispatch worker via configured adapter ──────────────────
+        //
+        // ADAPTER HANDOFF semantics: dispatching the worker and then continuing
+        // the loop is the correct behaviour. The parent does NOT halt here.
+        // The worker runs the child in an external process/subtask, writes its
+        // result to current-state.json and telemetry.jsonl, then returns a
+        // compact JSON summary via stdout.
+        //
+        // Lifecycle: register before dispatch, release after result.
+        // Only one worker may be active at a time (maxConcurrentWorkers = 1).
+        //
+        // Record the dispatch in state BEFORE calling the adapter so that
+        // dispatch_boundary.dispatch_epoch is always incremented before any
+        // worker execution occurs. This ensures the "dispatched → completed"
+        // transition is always verifiable from state alone.
+        const dispatchId = (0, node_crypto_1.randomUUID)();
+        const workerId = `${state.run_id}:${nextChild}:${Date.now()}`;
+        const dispatchedAt = new Date().toISOString();
+        const resultFile = childResultFilePath(state, nextChild, repoRoot, dispatchId);
+        const packetPath = buildClusterArtifactPaths(repoRoot, state.cluster_id, nextChild, dispatchId).packetPath;
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(resultFile), { recursive: true });
+        const statePreDispatch = state;
+        let stateBeforeDispatch = state;
+        const packet = buildPacket(state, nextChild, stateFile, telemetryFile, repoRoot, resultFile);
+        if (!dryRun) {
+            try {
+                writePacketArtifact(packetPath, packet);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                appendTelemetry(telemetryFile, {
+                    event: "child-dispatched-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    worker_id: workerId,
+                    error: `Failed to write packet artifact: ${msg}`,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    haltReason: 'worker-error',
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: `Failed to write packet artifact for ${nextChild}: ${msg}`,
+                };
+            }
+            const dispatchRecord = buildParentDispatchRecord({
+                dispatchId,
+                runId: state.run_id,
+                clusterId: state.cluster_id,
+                childId: nextChild,
+                packetPath,
+                resultPath: resultFile,
+                provider: providerName,
+                workerId,
+                dispatchedAt,
+            });
+            const stateWithDispatch = {
+                ...withChildDispatchMetadata(state, nextChild, resultFile, dispatchRecord),
+                active_child: nextChild,
+                step_cursor: "dispatch",
+                dispatch_boundary: (0, dispatch_boundary_js_1.advanceDispatchEpoch)(state.dispatch_boundary, nextChild),
+            };
+            (0, checkpoint_js_1.writeStateAtomic)(stateFile, stateWithDispatch);
+            state = stateWithDispatch;
+            stateBeforeDispatch = stateWithDispatch;
+            try {
+                await syncClusterDispatch({
+                    clusterId: state.cluster_id,
+                    childId: nextChild,
+                    repoRoot,
+                    packetPath,
+                    workerId,
+                    dispatchedAt,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                appendTelemetry(telemetryFile, {
+                    event: "child-dispatched-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    worker_id: workerId,
+                    error: `Failed to sync cluster dispatch state: ${msg}`,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    haltReason: 'worker-error',
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: `Failed to sync cluster dispatch state for ${nextChild}: ${msg}`,
+                };
+            }
+        }
+        const childrenCompletedBeforeDispatch = state.context_budget.children_completed;
+        // Register the worker slot before dispatch.
+        try {
+            lifecycle.register(workerId, nextChild, 'impl');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: `Lifecycle slot unavailable for ${nextChild}: ${msg}`,
+            };
+        }
+        if (!dryRun) {
+            const totalChildren = state.open_children.length + state.completed_children.length;
+            const childIndex = state.completed_children.length + 1;
+            logStatus(notificationFormat, `RUNNING ${nextChild} (${childIndex}/${totalChildren})`);
+            appendTelemetry(telemetryFile, {
+                event: "child-dispatched",
+                run_id: state.run_id,
+                child_id: nextChild,
+                worker_id: workerId,
+                adapter: adapterName,
+                orchestration_mode: telemetryOrchestrationMode,
+                provider: providerName,
+                prompt_mode: packet.prompt_mode,
+                prompt_estimated_tokens: packet.prompt_metrics.estimated_tokens,
+                packet_path: packetPath,
+                expected_result_path: resultFile,
+                dry_run: dryRun,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        let dispatchResult;
+        try {
+            dispatchResult = await adapter.dispatch(packet, { provider: providerName, dryRun });
+        }
+        catch (err) {
+            // Release slot on dispatch failure so the parent can retry or halt cleanly.
+            lifecycle.release(workerId);
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "child-dispatched-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    worker_id: workerId,
+                    error: msg,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: `Adapter "${adapterName}" threw during dispatch of ${nextChild}: ${msg}`,
+            };
+        }
+        // Release the lifecycle slot — worker has returned its result.
+        lifecycle.release(workerId);
+        // ── Step 04: Receive and validate compact worker return JSON ─────────
+        let finalWorkerSummary = null;
+        // Pre-dispatch failure: adapter returned before launching any worker.
+        // 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);
+            appendTelemetry(telemetryFile, {
+                event: "pre-dispatch-failure",
+                run_id: state.run_id,
+                child_id: nextChild,
+                adapter: adapterName,
+                error: dispatchResult.summary ?? "adapter returned pre-dispatch failure",
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: `Adapter "${adapterName}" cannot dispatch ${nextChild}: ${dispatchResult.summary ?? "no dispatcher available"}`,
+            };
+        }
+        // Only read the sealed result file when the adapter reports success.
+        // A non-zero exit_code means the worker never produced a sealed result —
+        // attempting readFileSync would cause ENOENT.
+        if (dispatchResult.exit_code === 0 && !dryRun) {
+            try {
+                const sealedFileContent = (0, node_fs_1.readFileSync)(packet.result_file_contract.result_file, 'utf-8');
+                const parsed = JSON.parse(sealedFileContent);
+                if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                    throw new Error(`Sealed result file has unexpected shape (expected object, got ${Array.isArray(parsed) ? 'array' : typeof parsed})`);
+                }
+                const sealedResult = parsed;
+                // Translate SealedWorkerResult status values to WorkerSummary status values.
+                // SealedWorkerResult uses "success"/"failure"; WorkerSummary uses "done"/"failed".
+                if (sealedResult['status'] === 'success') {
+                    sealedResult['status'] = 'done';
+                }
+                else if (sealedResult['status'] === 'failure') {
+                    sealedResult['status'] = 'failed';
+                }
+                finalWorkerSummary = sealedResult;
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                if (!dryRun) {
+                    appendTelemetry(telemetryFile, {
+                        event: "sealed-result-read-error",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        error: msg,
+                        result_file: packet.result_file_contract.result_file,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                return {
+                    haltReason: 'worker-error',
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: `Failed to read sealed result file for ${nextChild}: ${msg}`,
+                };
+            }
+        }
+        else {
+            finalWorkerSummary = parseWorkerSummary(dispatchResult.summary);
+        }
+        const workerStatus = finalWorkerSummary?.status ?? (dispatchResult.exit_code === 0 ? 'done' : 'error');
+        // Verify active_child or child_id matches if present in worker summary
+        const summaryAsRecord = finalWorkerSummary;
+        const summaryChild = summaryAsRecord?.['active_child'] ?? summaryAsRecord?.['child_id'];
+        if (summaryChild !== undefined && summaryChild !== nextChild) {
+            const errMsg = `Worker returned mismatched child identifier: expected ${nextChild}, got ${String(summaryChild)}`;
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "child-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    error: errMsg,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: errMsg,
+            };
+        }
+        if (workerStatus === 'blocked') {
+            const blockerMsg = finalWorkerSummary?.['blocker'] ??
+                dispatchResult.summary ??
+                `Worker reported blocked for ${nextChild}`;
+            if (!dryRun) {
+                logStatus(notificationFormat, `BLOCKED ${nextChild}: ${blockerMsg.replace(/\n/g, ' ')}`);
+                appendTelemetry(telemetryFile, {
+                    event: "child-blocked",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    blocker: blockerMsg.replace(/\n/g, ' '),
+                    timestamp: new Date().toISOString(),
+                });
+                // Write checkpoint with blocker information
+                (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                    ...state,
+                    status: "blocked",
+                    step_cursor: "blocked",
+                    blocker: {
+                        reason: typeof blockerMsg === 'string' ? blockerMsg : String(blockerMsg),
+                        child_id: nextChild,
+                        timestamp: new Date().toISOString(),
+                        resolved: false,
+                    },
+                });
+                // ── Apply lifecycle transition for child-triage-required event ─────────
+                // This is fire-and-forget: must not block on tracker mutations.
+                // Errors are logged to telemetry but do not fail the halt.
+                let adapter;
+                try {
+                    adapter = (0, index_js_1.loadTrackerAdapter)(config);
+                }
+                catch (err) {
+                    const errorMsg = err instanceof Error ? err.message : String(err);
+                    appendTelemetry(telemetryFile, {
+                        event: "lifecycle-transition-error",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        transition_event: "child-triage-required",
+                        error: `Failed to load tracker adapter: ${errorMsg}`,
+                        timestamp: new Date().toISOString(),
+                    });
+                    adapter = null;
+                }
+                const lifecyclePolicy = config.tracker?.lifecyclePolicy;
+                if (adapter || lifecyclePolicy) {
+                    try {
+                        const transitionService = new lifecycle_transition_js_1.LifecycleTransitionService();
+                        transitionService
+                            .applyTransitionSafe({
+                            adapter,
+                            policy: lifecyclePolicy,
+                            taskId: nextChild,
+                            event: "child-triage-required",
+                            evidence: {
+                                error: blockerMsg,
+                            },
+                            timestamp: new Date().toISOString(),
+                        })
+                            .then((result) => {
+                            appendTelemetry(telemetryFile, {
+                                event: "lifecycle-transition-attempt",
+                                run_id: state.run_id,
+                                child_id: nextChild,
+                                transition_event: result.event,
+                                target_state: result.targetState,
+                                applied: result.applied,
+                                skipped: result.skipped,
+                                skip_reason: result.skipReason,
+                                error: result.error,
+                                timestamp: result.timestamp,
+                            });
+                        })
+                            .catch((err) => {
+                            const errorMsg = err instanceof Error ? err.message : String(err);
+                            appendTelemetry(telemetryFile, {
+                                event: "lifecycle-transition-error",
+                                run_id: state.run_id,
+                                child_id: nextChild,
+                                transition_event: "child-triage-required",
+                                error: errorMsg,
+                                timestamp: new Date().toISOString(),
+                            });
+                        });
+                    }
+                    catch (err) {
+                        const errorMsg = err instanceof Error ? err.message : String(err);
+                        appendTelemetry(telemetryFile, {
+                            event: "lifecycle-transition-error",
+                            run_id: state.run_id,
+                            child_id: nextChild,
+                            transition_event: "child-triage-required",
+                            error: `Failed to create lifecycle transition service: ${errorMsg}`,
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                }
+            }
+            return {
+                haltReason: 'blocked',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: `Child ${nextChild} is blocked: ${typeof blockerMsg === 'string' ? blockerMsg : String(blockerMsg)}`,
+            };
+        }
+        // 'failed' is the CompactReturn terminal failure status; 'error' is the adapter-level status.
+        // Both map to worker-error halt — the exit_code check catches exit=1 from runWorker().
+        if (workerStatus === 'error' || workerStatus === 'failed' || dispatchResult.exit_code !== 0) {
+            const errMsg = dispatchResult.summary ?? `Worker exited with code ${dispatchResult.exit_code}`;
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "child-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    exit_code: dispatchResult.exit_code,
+                    summary: errMsg,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: `Worker for ${nextChild} failed (exit ${dispatchResult.exit_code}): ${errMsg}`,
+            };
+        }
+        // Only treat 'done' as successful completion; treat unknown statuses as errors
+        if (workerStatus !== 'done') {
+            const errMsg = `Worker returned unexpected status: ${workerStatus}`;
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "child-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    error: errMsg,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: `Worker for ${nextChild} returned unexpected status: ${workerStatus}`,
+            };
+        }
+        // Worker completed successfully — reload state from disk before advancing
+        // The worker may have updated current-state.json; reload to avoid clobbering
+        let reloadedStateValid = false;
+        try {
+            const reloadedState = (0, checkpoint_js_1.readState)(stateFile);
+            const reloadErrors = (0, checkpoint_js_1.validateState)(reloadedState);
+            if (reloadErrors.length > 0) {
+                const errMsg = `State file corrupted after worker execution:\n${reloadErrors.join("\n")}`;
+                if (!dryRun && adapterName === "terminal-cli") {
+                    appendTelemetry(telemetryFile, {
+                        event: "state-reload-fallback",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        error: errMsg,
+                        timestamp: new Date().toISOString(),
+                    });
+                    state = stateBeforeDispatch;
+                }
+                else if (!dryRun) {
+                    appendTelemetry(telemetryFile, {
+                        event: "state-reload-error",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        error: errMsg,
+                        timestamp: new Date().toISOString(),
+                    });
+                    return {
+                        haltReason: 'state-invalid',
+                        childrenDispatched,
+                        haltingChild: nextChild,
+                        message: errMsg,
+                    };
+                }
+            }
+            else {
+                state = reloadedState;
+                reloadedStateValid = true;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const errMsg = `Failed to reload state after worker execution: ${msg}`;
+            if (!dryRun && adapterName === "terminal-cli") {
+                appendTelemetry(telemetryFile, {
+                    event: "state-reload-fallback",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    error: errMsg,
+                    timestamp: new Date().toISOString(),
+                });
+                state = stateBeforeDispatch;
+            }
+            else if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "state-reload-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    error: errMsg,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    haltReason: 'state-invalid',
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: errMsg,
+                };
+            }
+        }
+        const workerWroteCompletion = reloadedStateValid &&
+            (state.completed_children.includes(nextChild) ||
+                state.context_budget.children_completed > childrenCompletedBeforeDispatch);
+        const lastCommit = finalWorkerSummary?.['commit'] ??
+            finalWorkerSummary?.['commit_hash'];
+        const validationSummary = finalWorkerSummary?.['validation'] ??
+            finalWorkerSummary?.['validation_summary'];
+        if (!dryRun && workerStatus === 'done' && (!lastCommit || lastCommit.trim().length === 0)) {
+            const errMsg = `Worker reported done for ${nextChild} without commit evidence`;
+            appendTelemetry(telemetryFile, {
+                event: "child-error",
+                run_id: state.run_id,
+                child_id: nextChild,
+                error: errMsg,
+                result_file: packet.result_file_contract.result_file,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                haltReason: 'worker-error',
+                childrenDispatched,
+                haltingChild: nextChild,
+                message: errMsg,
+            };
+        }
+        // ── Artifact-only commit gate ────────────────────────────────────────────
+        //
+        // HARD GATE: A worker commit that touches only Polaris artifact files
+        // (.polaris/**, .taskchain_artifacts/**) indicates no real implementation
+        // work was done — reject it to prevent phantom completions.
+        // Uses getCommitFiles from options for testability; defaults to a git-backed
+        // implementation that throws when the commit cannot be resolved (fail closed).
+        let commitFiles = null;
+        if (!dryRun && workerStatus === 'done' && lastCommit && lastCommit.trim().length > 0) {
+            const getFiles = options.getCommitFiles ?? defaultGetCommitFiles;
+            try {
+                commitFiles = getFiles(lastCommit, repoRoot);
+                if (workerWroteCompletion && commitFiles === null) {
+                    const errMsg = `Cannot verify worker commit ${lastCommit} for ${nextChild}: commit does not resolve to a git object`;
+                    appendTelemetry(telemetryFile, {
+                        event: "child-error",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        error: errMsg,
+                        commit: lastCommit,
+                        timestamp: new Date().toISOString(),
+                    });
+                    return {
+                        haltReason: 'worker-error',
+                        childrenDispatched,
+                        haltingChild: nextChild,
+                        message: errMsg,
+                    };
+                }
+                if (commitFiles !== null) {
+                    const nonArtifact = commitFiles.filter((f) => (0, artifact_policy_js_1.classifyArtifactPath)(f, state.cluster_id) === 'non-artifact');
+                    if (nonArtifact.length === 0) {
+                        const errMsg = `Worker commit ${lastCommit} for ${nextChild} contains only artifact files; no implementation evidence found`;
+                        appendTelemetry(telemetryFile, {
+                            event: "child-error",
+                            run_id: state.run_id,
+                            child_id: nextChild,
+                            error: errMsg,
+                            commit: lastCommit,
+                            timestamp: new Date().toISOString(),
+                        });
+                        return {
+                            haltReason: 'worker-error',
+                            childrenDispatched,
+                            haltingChild: nextChild,
+                            message: errMsg,
+                        };
+                    }
+                }
+                // null → skip check (fail-open for unresolvable commits)
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                const errMsg = `Cannot verify worker commit ${lastCommit} for ${nextChild}: ${msg}`;
+                appendTelemetry(telemetryFile, {
+                    event: "child-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    error: errMsg,
+                    commit: lastCommit,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    haltReason: 'worker-error',
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: errMsg,
+                };
+            }
+        }
+        // workerStatus === "done" has already been validated upstream.
+        // If the reloaded state already reflects the completed child,
+        // the worker owns the completion checkpoint and the parent
+        // must not rewrite it.
+        if (!workerWroteCompletion) {
+            // ── Dispatch boundary: verify dispatch happened before advancing ──────
+            // The parent dispatched via adapter, so dispatch_boundary should show
+            // dispatch_epoch > continue_epoch. If not, the state is inconsistent
+            // and we must not complete the child (it would be inline completion).
+            if (!dryRun) {
+                try {
+                    (0, dispatch_boundary_js_1.assertDispatchedBeforeCompletion)(state, nextChild, telemetryFile);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    appendTelemetry(telemetryFile, {
+                        event: "illegal-state-transition",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        error: msg,
+                        timestamp: new Date().toISOString(),
+                    });
+                    return {
+                        haltReason: 'worker-error',
+                        childrenDispatched,
+                        haltingChild: nextChild,
+                        message: msg,
+                    };
+                }
+            }
+            // Advance state, including continue_epoch to match the consumed dispatch
+            const advanced = advanceState(state, nextChild, lastCommit);
+            state = {
+                ...advanced,
+                dispatch_boundary: (0, dispatch_boundary_js_1.advanceContinueEpoch)(state.dispatch_boundary),
+            };
+            childrenDispatched += 1;
+            // Worker did not write its own completion — orchestrator fills the gap.
+            if (!dryRun) {
+                (0, checkpoint_js_1.writeStateAtomic)(stateFile, state);
+            }
+        }
+        else {
+            // Worker wrote its own completion — advance continue_epoch to stay in sync.
+            // The worker does not manage dispatch_boundary, so the parent must do it.
+            state = {
+                ...state,
+                dispatch_boundary: (0, dispatch_boundary_js_1.advanceContinueEpoch)(state.dispatch_boundary),
+            };
+            childrenDispatched += 1;
+            if (!dryRun) {
+                (0, checkpoint_js_1.writeStateAtomic)(stateFile, state);
+            }
+        }
+        // Orchestrator checkpoint event — always emitted after a successful child.
+        if (!dryRun) {
+            const commitSuffix = lastCommit && lastCommit.length > 0 ? ` (commit: ${lastCommit})` : "";
+            try {
+                const synced = await syncClusterCompletion({
+                    clusterId: state.cluster_id,
+                    childId: nextChild,
+                    repoRoot,
+                    resultFile: packet.result_file_contract.result_file,
+                    validationSummary,
+                    lastCommit,
+                });
+                if (!synced) {
+                    appendTelemetry(telemetryFile, {
+                        event: "cluster-state-sync-skipped",
+                        run_id: state.run_id,
+                        child_id: nextChild,
+                        reason: "no cluster state found",
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                appendTelemetry(telemetryFile, {
+                    event: "cluster-state-sync-error",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    error: message,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    haltReason: "state-invalid",
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: `Failed to sync cluster-state.json for ${nextChild}: ${message}`,
+                };
+            }
+            logStatus(notificationFormat, `COMPLETE ${nextChild}${commitSuffix}`);
+            // Compute elapsed_seconds from dispatch_record.dispatched_at if available
+            const dispatchedAt = state.open_children_meta?.[nextChild]?.dispatch_record?.dispatched_at;
+            const elapsedSeconds = dispatchedAt
+                ? Math.floor((Date.now() - new Date(dispatchedAt).getTime()) / 1000)
+                : undefined;
+            const telemetryEvent = {
+                event: "child-complete",
+                run_id: state.run_id,
+                child_id: nextChild,
+                children_completed: state.context_budget.children_completed,
+                validation_summary: validationSummary,
+                commit_hash: lastCommit,
+                commit_files: commitFiles,
+                timestamp: new Date().toISOString(),
+            };
+            if (elapsedSeconds !== undefined) {
+                telemetryEvent.elapsed_seconds = elapsedSeconds;
+            }
+            appendTelemetry(telemetryFile, telemetryEvent);
+            appendChildCompletedLedgerEvent(repoRoot, state, nextChild, lastCommit ?? null, validationSummary);
+        }
+        if (orchestrationMode === 'supervised') {
+            return {
+                haltReason: 'supervised-mode-child-complete',
+                childrenDispatched,
+                message: `Child ${nextChild} complete. Re-run to continue.`,
+            };
+        }
+        // ── Step 05 (post-dispatch): Re-check budget before next iteration ───
+        const postBudgetCheck = (0, budget_js_1.checkBudget)({
+            childrenCompleted: state.context_budget.children_completed,
+            lastChildStatus: workerStatus,
+            policy: budgetPolicy,
+        });
+        if (postBudgetCheck.status === 'exhausted') {
+            const nextPending = state.open_children[0] ?? null;
+            if (!dryRun) {
+                (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                    ...state,
+                    status: "budget-exhausted",
+                    step_cursor: "budget-check",
+                    next_open_child: nextPending,
+                });
+                appendTelemetry(telemetryFile, {
+                    event: "budget-exhausted",
+                    run_id: state.run_id,
+                    children_completed: state.context_budget.children_completed,
+                    next_child: nextPending,
+                    reason: postBudgetCheck.reason,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                haltReason: 'budget-exhausted',
+                childrenDispatched,
+                haltingChild: nextPending ?? undefined,
+                message: postBudgetCheck.reason,
+            };
+        }
+        // ── Step 06: CONTINUE (back to step 02) ─────────────────────────────
+    }
+}