@lsctech/polaris 0.1.0

package/dist/loop/dispatch.js

@@ -0,0 +1,1236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProviderAndMode = resolveProviderAndMode;
+exports.assertProviderAllowedForRole = assertProviderAllowedForRole;
+exports.runLoopDispatch = runLoopDispatch;
+exports.checkAcknowledgmentTimeout = checkAcknowledgmentTimeout;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const git_custody_js_1 = require("./git-custody.js");
+const node_path_1 = require("node:path");
+const checkpoint_js_1 = require("./checkpoint.js");
+const worker_packet_js_1 = require("./worker-packet.js");
+const body_parser_js_1 = require("./body-parser.js");
+const loader_js_1 = require("../config/loader.js");
+const store_js_1 = require("../cluster-state/store.js");
+const worker_prompt_js_1 = require("./worker-prompt.js");
+const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
+const run_bootstrap_js_1 = require("./run-bootstrap.js");
+const ledger_js_1 = require("./ledger.js");
+const index_js_1 = require("../tracker/index.js");
+const lifecycle_transition_js_1 = require("../tracker/lifecycle-transition.js");
+const CLAIM_TTL_MS = 30 * 60 * 1000;
+/**
+ * Determine the effective provider and dispatch mode using the 4-scenario decision tree:
+ *   1. --provider flag set → direct-worker (no fallback)
+ *   2. Provider in .polaris/config → direct-worker (no fallback)
+ *   3. Internal subagent available → delegated dispatch with fallback chain
+ *   4. Nothing available → pending-escalation (handled in attemptDelegatedAssignment)
+ */
+function roleContextToExecutionRole(role) {
+    switch (role) {
+        case "foreman":
+            return "orchestrator";
+        case "analyst":
+            return "analyst";
+        case "librarian":
+            return "librarian";
+        case "worker":
+        default:
+            return "worker";
+    }
+}
+function resolveProviderAndMode(options, role, config) {
+    const defaultAdapter = "terminal-cli";
+    if (options.provider) {
+        return {
+            provider: options.provider,
+            mode: "direct-worker",
+            adapter: defaultAdapter,
+            selectionReason: "cli-provider-override",
+            overrideSource: "dispatch-flag",
+            providersTried: [options.provider],
+        };
+    }
+    // Only catch config-load failures; policy violations must propagate to the caller.
+    let loaded;
+    let adapter = defaultAdapter;
+    try {
+        loaded = config ?? (0, loader_js_1.loadConfig)(options.repoRoot);
+        adapter = loaded.execution?.adapter ?? defaultAdapter;
+    }
+    catch {
+        return {
+            provider: undefined,
+            mode: "delegated",
+            adapter: defaultAdapter,
+            selectionReason: "delegated-config-unavailable",
+            fallbackFrom: "config",
+            fallbackReason: "config-unavailable",
+            providersTried: [],
+            exhaustedReason: "config-unavailable",
+        };
+    }
+    const exec = loaded.execution;
+    const rolePolicy = exec?.providerPolicy?.[role];
+    const roleProviders = rolePolicy?.providers ?? [];
+    const rotation = exec?.rotation ?? [];
+    if (roleProviders.length > 0) {
+        // When a role policy is configured, filter the rotation to only include
+        // providers that are allowed by the policy.  This ensures that a provider
+        // present in rotation but absent from the policy is never selected.
+        const allowedByPolicy = new Set(roleProviders);
+        const configuredProviders = new Set(Object.keys(exec?.providers ?? {}));
+        const filteredRotation = rotation.filter((p) => allowedByPolicy.has(p));
+        if (filteredRotation.length > 0 && filteredRotation[0]) {
+            return {
+                provider: filteredRotation[0],
+                mode: "direct-worker",
+                adapter,
+                selectionReason: "policy-filtered-rotation",
+                providersTried: [filteredRotation[0]],
+            };
+        }
+        // No rotation entry is in the policy — fall back to first policy provider
+        // that is actually configured.  If none is configured, fail before mutation.
+        const availablePolicyProviders = roleProviders.filter((p) => configuredProviders.has(p));
+        if (availablePolicyProviders.length > 0 && availablePolicyProviders[0]) {
+            return {
+                provider: availablePolicyProviders[0],
+                mode: "direct-worker",
+                adapter,
+                selectionReason: "role-policy",
+                providersTried: [availablePolicyProviders[0]],
+            };
+        }
+        // No configured provider satisfies the policy — fail clearly before dispatch.
+        throw new Error(`provider dispatch forbidden: no configured provider satisfies the "${role}" role policy (policy=${roleProviders.join(",")})`);
+    }
+    const roleProvider = exec?.roles?.[role]?.provider;
+    if (roleProvider) {
+        return {
+            provider: roleProvider,
+            mode: "direct-worker",
+            adapter,
+            selectionReason: "role-config",
+            providersTried: [roleProvider],
+        };
+    }
+    if (rotation.length > 0 && rotation[0]) {
+        return {
+            provider: rotation[0],
+            mode: "direct-worker",
+            adapter,
+            selectionReason: "config-rotation",
+            providersTried: [rotation[0]],
+        };
+    }
+    const providers = Object.keys(exec?.providers ?? {});
+    if (providers.length > 0 && providers[0]) {
+        return {
+            provider: providers[0],
+            mode: "direct-worker",
+            adapter,
+            selectionReason: "config-first-provider",
+            fallbackFrom: "rotation",
+            fallbackReason: "rotation-empty",
+            providersTried: [providers[0]],
+        };
+    }
+    return {
+        provider: undefined,
+        mode: "delegated",
+        adapter,
+        selectionReason: "delegated-no-provider",
+        providersTried: [],
+        exhaustedReason: "no-configured-provider",
+    };
+}
+function fail(message) {
+    process.stderr.write(`Error: ${message}
+`);
+    process.exit(1);
+}
+function probeProviderSync(resolvedProvider, loadedConfig) {
+    try {
+        const providers = loadedConfig?.execution?.providers ?? {};
+        const providerCfg = providers[resolvedProvider];
+        if (!providerCfg) {
+            return { ok: false, error: `Unknown provider "${resolvedProvider}"` };
+        }
+        const expandedCommand = providerCfg.command
+            .replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_, name) => process.env[name] ?? '')
+            .replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, name) => process.env[name] ?? '');
+        const cmd = expandedCommand.split(' ')[0] ?? expandedCommand;
+        if (!cmd) {
+            return { ok: false, error: `Provider "${resolvedProvider}" has no command configured` };
+        }
+        // Check if command is on PATH
+        const isAbs = cmd.startsWith('/');
+        if (isAbs) {
+            return (0, node_fs_1.existsSync)(cmd)
+                ? { ok: true }
+                : { ok: false, error: `Provider command "${providerCfg.command}" not found on PATH` };
+        }
+        try {
+            (0, node_child_process_1.execFileSync)('which', [cmd], { stdio: 'ignore' });
+            return { ok: true };
+        }
+        catch {
+            return { ok: false, error: `Provider command "${providerCfg.command}" not found on PATH` };
+        }
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function hasValidationWaiver(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 isPlaceholderGoalText(goal) {
+    return /^[\s\[(<{'"`-]*(?:tbd|todo|placeholder|to be determined)\b/i.test(goal);
+}
+function detectPacketGenerationFailure(packet) {
+    if (packet.worker_role !== "impl")
+        return null;
+    const childId = packet.active_child || "unknown-child";
+    const allowedScope = Array.isArray(packet.instructions.allowed_scope)
+        ? packet.instructions.allowed_scope
+        : [];
+    if (allowedScope.length === 0) {
+        return {
+            missingField: "allowed_scope",
+            message: `Packet generation failed for ${childId}: missing actionable allowed_scope.`,
+        };
+    }
+    const issueBody = packet.instructions.issue_context?.body?.trim() ?? "";
+    const parsedGoal = issueBody ? (0, body_parser_js_1.parseIssueBody)(issueBody).goal.trim() : "";
+    const issueTitle = packet.instructions.issue_context?.title ?? childId;
+    const fallbackPromptGoal = `## Goal\nImplement ${childId}: "${issueTitle}".`;
+    const missingGoalFromBody = issueBody.length > 0 && parsedGoal.length === 0;
+    const placeholderGoal = packet.instructions.primary_goal.includes(fallbackPromptGoal) ||
+        missingGoalFromBody ||
+        isPlaceholderGoalText(parsedGoal);
+    if (placeholderGoal) {
+        return {
+            missingField: "primary_goal",
+            message: `Packet generation failed for ${childId}: primary_goal is placeholder or missing.`,
+        };
+    }
+    const validationCommands = Array.isArray(packet.instructions.validation_commands)
+        ? packet.instructions.validation_commands
+        : [];
+    const packetWithFlags = packet;
+    const validationWaiver = packetWithFlags.validation_waiver
+        ?? packetWithFlags.instructions?.validation_waiver;
+    if (validationCommands.length === 0 && !hasValidationWaiver(validationWaiver)) {
+        return {
+            missingField: "validation_commands",
+            message: `Packet generation failed for ${childId}: validation_commands is empty and validation_waiver is missing.`,
+        };
+    }
+    return null;
+}
+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");
+}
+function canonicalPath(path) {
+    try {
+        return (0, node_fs_1.realpathSync)(path);
+    }
+    catch {
+        return path;
+    }
+}
+function absoluteResultFile(repoRoot, filePath) {
+    return (0, node_path_1.isAbsolute)(filePath) ? filePath : (0, node_path_1.resolve)(repoRoot, filePath);
+}
+function getCurrentBranch(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["branch", "--show-current"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return process.env["POLARIS_BRANCH"] ?? "unknown";
+    }
+}
+/**
+ * Get cluster-scoped packet directory path.
+ * Format: .polaris/clusters/<cluster-id>/packets/
+ */
+function getClusterPacketDir(repoRoot, clusterId) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "packets");
+}
+/**
+ * Get cluster-scoped results directory path.
+ * Format: .polaris/clusters/<cluster-id>/results/
+ */
+function getClusterResultDir(repoRoot, clusterId) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "results");
+}
+/**
+ * Build dispatch artifact paths in cluster-scoped layout.
+ * Returns packet path and expected result path.
+ */
+function buildClusterArtifactPaths(repoRoot, clusterId, childId, dispatchId) {
+    const packetDir = getClusterPacketDir(repoRoot, clusterId);
+    const resultDir = getClusterResultDir(repoRoot, clusterId);
+    const filename = `${childId}-${dispatchId}.json`;
+    const packetPath = (0, node_path_1.join)(packetDir, filename);
+    const resultPath = (0, node_path_1.join)(resultDir, filename);
+    return {
+        packetPath,
+        resultPath,
+        relativePacketPath: (0, node_path_1.relative)(repoRoot, packetPath),
+        relativeResultPath: (0, node_path_1.relative)(repoRoot, resultPath),
+    };
+}
+/**
+ * Write packet artifact to cluster-scoped layout.
+ * Creates directories if needed.
+ */
+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");
+}
+/**
+ * Determine dispatch mode based on provider presence.
+ */
+function determineDispatchMode(provider) {
+    return provider ? "direct-worker" : "delegated";
+}
+/**
+ * Determine initial runtime state based on dispatch mode.
+ */
+function determineRuntimeState(mode) {
+    return mode === "delegated" ? "delegated" : "packet-created";
+}
+function emitProviderSelected(telemetryFile, dispatchId, runId, childId, decision) {
+    appendTelemetry(telemetryFile, {
+        event: "provider-selected",
+        event_id: (0, node_crypto_1.randomUUID)(),
+        dispatch_id: dispatchId,
+        run_id: runId,
+        child_id: childId,
+        requested_role: "worker",
+        selected_provider: decision.provider ?? null,
+        selected_adapter: decision.adapter,
+        selection_reason: decision.selectionReason,
+        ...(decision.overrideSource ? { override_source: decision.overrideSource } : {}),
+        ...(decision.fallbackFrom ? { fallback_from: decision.fallbackFrom } : {}),
+        ...(decision.fallbackReason ? { fallback_reason: decision.fallbackReason } : {}),
+        ...(decision.providersTried.length > 0 ? { providers_tried: decision.providersTried } : {}),
+        timestamp: new Date().toISOString(),
+    });
+}
+function emitProviderFallbackAttempted(telemetryFile, dispatchId, runId, childId, decision) {
+    if (!decision.fallbackFrom || !decision.fallbackReason)
+        return;
+    appendTelemetry(telemetryFile, {
+        event: "provider-fallback-attempted",
+        event_id: (0, node_crypto_1.randomUUID)(),
+        dispatch_id: dispatchId,
+        run_id: runId,
+        child_id: childId,
+        requested_role: "worker",
+        fallback_from: decision.fallbackFrom,
+        fallback_reason: decision.fallbackReason,
+        ...(decision.providersTried.length > 0 ? { providers_tried: decision.providersTried } : {}),
+        timestamp: new Date().toISOString(),
+    });
+}
+function emitProviderExhausted(telemetryFile, dispatchId, runId, childId, decision) {
+    if (decision.provider)
+        return;
+    appendTelemetry(telemetryFile, {
+        event: "provider-exhausted",
+        event_id: (0, node_crypto_1.randomUUID)(),
+        dispatch_id: dispatchId,
+        run_id: runId,
+        child_id: childId,
+        requested_role: "worker",
+        selected_adapter: decision.adapter,
+        reason: decision.exhaustedReason ?? "no-provider-selected",
+        ...(decision.providersTried.length > 0 ? { providers_tried: decision.providersTried } : {}),
+        timestamp: new Date().toISOString(),
+    });
+}
+function getProviderPolicy(repoRoot) {
+    try {
+        const config = (0, loader_js_1.loadConfig)(repoRoot);
+        return config.execution.providerPolicy;
+    }
+    catch {
+        return undefined;
+    }
+}
+function assertProviderAllowedForRole(role, provider, policy, telemetryFile, dispatchId, runId, childId) {
+    const rolePolicy = policy?.[role];
+    if (!rolePolicy)
+        return;
+    if (rolePolicy.providers.length === 0) {
+        appendTelemetry(telemetryFile, {
+            event: "provider-forbidden",
+            event_id: (0, node_crypto_1.randomUUID)(),
+            dispatch_id: dispatchId,
+            run_id: runId,
+            child_id: childId,
+            requested_role: "worker",
+            selected_provider: provider ?? null,
+            reason: "role-disabled",
+            policy_providers: [],
+            timestamp: new Date().toISOString(),
+        });
+        throw new Error(`provider dispatch forbidden: role "${role}" is disabled by provider policy`);
+    }
+    if (!provider || !rolePolicy.providers.includes(provider)) {
+        appendTelemetry(telemetryFile, {
+            event: "provider-forbidden",
+            event_id: (0, node_crypto_1.randomUUID)(),
+            dispatch_id: dispatchId,
+            run_id: runId,
+            child_id: childId,
+            requested_role: "worker",
+            selected_provider: provider ?? null,
+            reason: "not-in-policy",
+            policy_providers: rolePolicy.providers,
+            timestamp: new Date().toISOString(),
+        });
+        throw new Error(`provider dispatch forbidden: provider "${provider ?? "none"}" is not allowed for role "${role}"`);
+    }
+}
+/**
+ * Create a dispatch record with all required evidence.
+ */
+function createDispatchRecord(runId, clusterId, childId, packetPath, resultPath, roleContext, provider, providerSelectionReason, providerOverrideSource, providersTried) {
+    const dispatchMode = determineDispatchMode(provider);
+    const runtimeState = determineRuntimeState(dispatchMode);
+    return {
+        dispatch_id: (0, node_crypto_1.randomUUID)(),
+        child_id: childId,
+        run_id: runId,
+        cluster_id: clusterId,
+        packet_path: packetPath,
+        expected_result_path: resultPath,
+        provider,
+        provider_selection_reason: providerSelectionReason,
+        provider_override_source: providerOverrideSource,
+        providers_tried: providersTried && providersTried.length > 0 ? providersTried : undefined,
+        dispatched_at: new Date().toISOString(),
+        status: "dispatched",
+        dispatch_mode: dispatchMode,
+        runtime_state: runtimeState,
+        worker_id: (0, node_crypto_1.randomUUID)(),
+        session_id: null,
+        attachment_capable: false,
+        role: roleContext?.role,
+        role_authority: roleContext?.role_authority,
+        may_implement: roleContext?.may_implement,
+        session_type: roleContext ? (roleContext.role === 'worker' ? 'implementation' :
+            roleContext.role === 'foreman' ? 'coordination' :
+                roleContext.role === 'analyst' ? 'analysis' :
+                    roleContext.role === 'librarian' ? 'documentation' : undefined) : undefined,
+    };
+}
+function getSubagentDispatcher() {
+    const host = globalThis;
+    return host.__POLARIS_AGENT_SUBTASK_DISPATCH__;
+}
+/**
+ * Emit a worker-assignment-attempted event (before each spawn attempt).
+ */
+function emitAssignmentAttempted(telemetryFile, dispatchId, runId, childId, assignmentType) {
+    appendTelemetry(telemetryFile, {
+        event: "worker-assignment-attempted",
+        event_id: (0, node_crypto_1.randomUUID)(),
+        dispatch_id: dispatchId,
+        run_id: runId,
+        child_id: childId,
+        assignment_type: assignmentType,
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Emit a worker-assigned event on success.
+ */
+function emitAssigned(telemetryFile, dispatchId, runId, childId, assignmentType, subagentSessionId, processPid, handoffToken) {
+    appendTelemetry(telemetryFile, {
+        event: "worker-assigned",
+        event_id: (0, node_crypto_1.randomUUID)(),
+        dispatch_id: dispatchId,
+        run_id: runId,
+        child_id: childId,
+        assignment_type: assignmentType,
+        ...(subagentSessionId !== undefined ? { subagent_session_id: subagentSessionId } : {}),
+        ...(processPid !== undefined ? { process_pid: processPid } : {}),
+        ...(handoffToken !== undefined ? { handoff_token: handoffToken } : {}),
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Emit a worker-assignment-failed event on each mechanism failure.
+ */
+function emitAssignmentFailed(telemetryFile, dispatchId, runId, childId, reason) {
+    appendTelemetry(telemetryFile, {
+        event: "worker-assignment-failed",
+        event_id: (0, node_crypto_1.randomUUID)(),
+        dispatch_id: dispatchId,
+        run_id: runId,
+        child_id: childId,
+        reason,
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Emit an escalation-initiated event when all mechanisms are exhausted.
+ */
+function emitEscalationInitiated(telemetryFile, dispatchId, runId, childId, reason) {
+    appendTelemetry(telemetryFile, {
+        event: "escalation-initiated",
+        event_id: (0, node_crypto_1.randomUUID)(),
+        dispatch_id: dispatchId,
+        run_id: runId,
+        child_id: childId,
+        reason,
+        recommended_action: "manual-dispatch",
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Attempt the delegated assignment fallback chain:
+ *   1. subagent spawn attempt
+ *   2. external-process fallback
+ *   3. human-handoff fallback
+ *   4. pending-escalation (all mechanisms exhausted)
+ *
+ * Emits telemetry events at each decision point (before state transitions).
+ * Returns the assignment outcome with evidence.
+ */
+function attemptDelegatedAssignment(telemetryFile, dispatchId, runId, childId, packet, providerPolicy) {
+    const now = new Date().toISOString();
+    const governedRole = roleContextToExecutionRole(packet.role_context.role);
+    const rolePolicy = providerPolicy?.[governedRole];
+    const allowNativeSubagent = rolePolicy?.allowNativeSubagent !== false;
+    // Step 1: Try subagent spawn (unless policy disables native subagents for this role)
+    if (!allowNativeSubagent) {
+        emitAssignmentFailed(telemetryFile, dispatchId, runId, childId, "native-subagent-not-allowed-for-role");
+    }
+    else {
+        emitAssignmentAttempted(telemetryFile, dispatchId, runId, childId, "subagent");
+        const dispatcher = getSubagentDispatcher();
+        if (dispatcher) {
+            // Subagent available - attempt dispatch
+            const sessionId = (0, node_crypto_1.randomUUID)();
+            try {
+                void dispatcher(packet, { dispatchId, runId, childId, sessionId });
+                emitAssigned(telemetryFile, dispatchId, runId, childId, "subagent", sessionId);
+                return {
+                    assignment: {
+                        assigned_at: now,
+                        assignment_type: "subagent",
+                        subagent_session_id: sessionId,
+                    },
+                    session_id: sessionId,
+                    attachment_capable: false,
+                    runtime_state: "delegated",
+                };
+            }
+            catch (err) {
+                // Dispatcher invocation failed, fall through to next mechanism
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                emitAssignmentFailed(telemetryFile, dispatchId, runId, childId, "no-subagent-support");
+                appendTelemetry(telemetryFile, {
+                    event: "subagent-spawn-error",
+                    event_id: (0, node_crypto_1.randomUUID)(),
+                    dispatch_id: dispatchId,
+                    run_id: runId,
+                    child_id: childId,
+                    error: errorMsg,
+                    timestamp: new Date().toISOString(),
+                });
+                // Continue to external-process fallback below
+            }
+        }
+        else {
+            // Subagent unavailable
+            emitAssignmentFailed(telemetryFile, dispatchId, runId, childId, "no-subagent-support");
+        }
+    }
+    // Step 2: Try external-process fallback (not available in this wave)
+    emitAssignmentAttempted(telemetryFile, dispatchId, runId, childId, "external-process");
+    emitAssignmentFailed(telemetryFile, dispatchId, runId, childId, "provider-unavailable");
+    // Step 3: Try human-handoff fallback (not available in this wave)
+    emitAssignmentAttempted(telemetryFile, dispatchId, runId, childId, "human-handoff");
+    emitAssignmentFailed(telemetryFile, dispatchId, runId, childId, "provider-unavailable");
+    // Step 4: All mechanisms exhausted — pending-escalation
+    const escalationReason = "No assignment mechanism available: subagent not supported, no external-process or human-handoff configured";
+    emitEscalationInitiated(telemetryFile, dispatchId, runId, childId, escalationReason);
+    return {
+        assignment: {
+            assigned_at: now,
+            assignment_type: "pending-escalation",
+            escalation_reason: escalationReason,
+        },
+        session_id: null,
+        attachment_capable: false,
+        runtime_state: "delegated",
+    };
+}
+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 appendDispatchLedgerEvent(repoRoot, state, childId) {
+    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: "child-dispatched",
+        run_id: state.run_id,
+        run_type: normalizeRunType(state.session_type),
+        cluster_id: state.cluster_id,
+        issue_id: childId,
+        branch: state.branch ?? getCurrentBranch(repoRoot),
+        status: "child-dispatched",
+        completed_children: state.completed_children,
+        open_children: state.open_children,
+        next_child: childId,
+        last_commit: ledgerLastCommit(state),
+        pr_url: null,
+        timestamp: new Date().toISOString(),
+        dispatch_epoch: state.dispatch_boundary?.dispatch_epoch ?? 0,
+    });
+}
+function selectChild(state, requestedChild) {
+    // Note: active_child check now handled by assertNoActiveChildBeforeDispatch
+    // before this function is called
+    if (state.status === "blocked") {
+        fail("current-state.json status is blocked");
+    }
+    if (state.status === "cluster-complete") {
+        fail("current-state.json status is cluster-complete");
+    }
+    if (state.open_children.length === 0) {
+        fail("no open children exist");
+    }
+    if (requestedChild) {
+        if (!state.open_children.includes(requestedChild)) {
+            fail(`child ${requestedChild} is not open`);
+        }
+        // Validate all open (non-completed) dependencies are satisfied
+        const childMeta = state.open_children_meta?.[requestedChild];
+        const deps = childMeta?.dependencies ?? [];
+        const unmetDeps = deps.filter((dep) => state.open_children.includes(dep) && !state.completed_children.includes(dep));
+        if (unmetDeps.length > 0) {
+            fail(`child ${requestedChild} has unmet dependencies that must complete first: ${unmetDeps.join(", ")}`);
+        }
+        return requestedChild;
+    }
+    return state.open_children[0];
+}
+/**
+ * Constructs a WorkerPacket for dispatching a specific child using the current loop state and repository context.
+ *
+ * The packet includes run/cluster/child identifiers, branch (derived from state or git), canonicalized paths for
+ * state and optional result files, prompt mode, and an `allowedScope` resolved from the child's issue body with a
+ * fallback to the cluster/root issue body when present.
+ *
+ * @param state - The current LoopState used to populate packet metadata
+ * @param childId - The target child identifier to include in the packet
+ * @param stateFile - Path to the loop state file to embed in the packet (will be canonicalized)
+ * @param telemetryFile - Path to the telemetry file to include in the packet
+ * @param repoRoot - Repository root used to determine branch and resolve non-absolute result paths
+ * @param resultFile - Optional path for the expected result file; non-absolute paths are resolved against `repoRoot`
+ * @returns The constructed WorkerPacket ready for dispatch
+ */
+function buildPacket(state, childId, stateFile, telemetryFile, repoRoot, resultFile) {
+    const childMeta = state.open_children_meta?.[childId];
+    // 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, childId, repoRoot);
+    const issueContext = (childMeta || resolvedChildBody)
+        ? {
+            id: childId,
+            title: childMeta?.title ?? childId,
+            key_requirements: [],
+            body: resolvedChildBody,
+        }
+        : undefined;
+    // Scope precedence: child body → parent/cluster-root body fallback.
+    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;
+    return (0, worker_packet_js_1.compileImplPacket)({
+        runId: state.run_id,
+        clusterId: state.cluster_id,
+        childId,
+        branch: state.branch || getCurrentBranch(repoRoot),
+        stateFile: canonicalPath(stateFile),
+        telemetryFile,
+        issueContext,
+        allowedScope: resolvedScope.length > 0 ? resolvedScope : undefined,
+        maxConcurrentWorkers: 1,
+        promptMode: (0, worker_prompt_js_1.selectPromptMode)(childId, state),
+        resultFile: canonicalPath(absoluteResultFile(repoRoot, resultFile)),
+    });
+}
+function buildClusterStateFromLoopState(state, previousGeneration) {
+    const childOrder = [
+        ...state.completed_children,
+        ...state.open_children,
+        ...(state.active_child ? [state.active_child] : []),
+    ];
+    const seen = new Set();
+    const child_states = [];
+    for (const childId of childOrder) {
+        if (!childId || seen.has(childId))
+            continue;
+        seen.add(childId);
+        let status;
+        if (state.completed_children.includes(childId)) {
+            status = "done";
+        }
+        else if (childId === state.active_child) {
+            status = "dispatched";
+        }
+        else {
+            status = "ready";
+        }
+        child_states.push({
+            id: childId,
+            status,
+        });
+    }
+    return {
+        schema_version: "1.0",
+        cluster_id: state.cluster_id,
+        state_generation: previousGeneration !== undefined ? previousGeneration + 1 : 1,
+        child_states,
+        claim_metadata: {},
+        packet_pointers: {},
+        result_pointers: {},
+        validation_results: {},
+        commits: {},
+        tracker_mutations: {},
+        blockers: [],
+    };
+}
+function syncClusterDispatchState(state, childId, dispatchRecord, packetPath, repoRoot, custodyRecord) {
+    const existingState = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+    const previousGeneration = existingState?.state_generation;
+    const clusterState = existingState ?? buildClusterStateFromLoopState(state, previousGeneration);
+    const claimedAt = dispatchRecord.dispatched_at;
+    const claimedAtMs = new Date(claimedAt).getTime();
+    const expiresAt = new Date(Number.isFinite(claimedAtMs) ? claimedAtMs + CLAIM_TTL_MS : Date.now() + CLAIM_TTL_MS).toISOString();
+    const knownChild = clusterState.child_states.some((child) => child.id === childId);
+    const child_states = knownChild
+        ? clusterState.child_states.map((child) => child.id === childId
+            ? {
+                ...child,
+                status: "dispatched",
+            }
+            : child)
+        : [...clusterState.child_states, { id: childId, status: "dispatched" }];
+    // Record delivery branch custody on first dispatch; never overwrite an existing record.
+    const custodyFields = custodyRecord && !existingState?.delivery_branch
+        ? {
+            base_branch: custodyRecord.base_branch,
+            base_sha: custodyRecord.base_sha,
+            delivery_branch: custodyRecord.delivery_branch,
+        }
+        : {};
+    (0, store_js_1.writeClusterStateSync)(state.cluster_id, {
+        ...clusterState,
+        ...custodyFields,
+        state_generation: clusterState.state_generation + 1,
+        child_states,
+        claim_metadata: {
+            ...clusterState.claim_metadata,
+            [childId]: {
+                worker_id: dispatchRecord.worker_id ?? dispatchRecord.dispatch_id,
+                claimed_at: claimedAt,
+                expires_at: expiresAt,
+            },
+        },
+        packet_pointers: {
+            ...clusterState.packet_pointers,
+            [childId]: packetPath,
+        },
+    }, repoRoot);
+}
+/**
+ * Dispatches one child task from the loop state: prepares a worker packet, persists artifacts, updates state, and emits telemetry.
+ *
+ * Performs child selection (or uses the provided childId), builds the packet, resolves provider and dispatch mode, writes cluster-scoped packet/result artifacts, creates and persists a dispatch record, attempts delegated assignment when required, synchronizes cluster dispatch state, appends ledger and telemetry events, and writes the packet JSON to stdout.
+ *
+ * @param options - DispatchOptions controlling where to read/write state and artifacts (includes `stateFile`, `repoRoot`, optional `childId`, optional `resultFile`, and an optional `provider` override)
+ */
+function runLoopDispatch(options) {
+    let state;
+    try {
+        const rawState = (0, checkpoint_js_1.readState)(options.stateFile);
+        const errors = (0, checkpoint_js_1.validateState)(rawState);
+        if (errors.length > 0) {
+            fail(`current-state.json is invalid:\n${errors.join("\n")}`);
+        }
+        state = rawState;
+    }
+    catch (err) {
+        fail(`cannot read state file ${options.stateFile}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const telemetryFile = resolveTelemetryFile(state, options.repoRoot);
+    // Load config once up front so it is available for both custody and provider selection.
+    let loadedConfig;
+    try {
+        loadedConfig = (0, loader_js_1.loadConfig)(options.repoRoot);
+    }
+    catch {
+        loadedConfig = undefined;
+    }
+    // ── Bootstrap seal enforcement ─────────────────────────────────────────────
+    // The run MUST have been initialized through `polaris loop bootstrap`.
+    // Hand-crafted state (no seal) is refused before any child is dispatched.
+    try {
+        (0, run_bootstrap_js_1.assertBootstrapSeal)(state, telemetryFile);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    // ── Dispatch boundary enforcement ─────────────────────────────────────────
+    // Halt immediately if active_child is already set (orphaned dispatch).
+    // The parent/orchestrator MUST NOT re-dispatch or complete inline.
+    // Single-emission guard: check if this invalid-inline condition was already recorded
+    const invalidInlineAlreadyRecorded = state.step_cursor === "invalid-inline-attempt";
+    try {
+        (0, dispatch_boundary_js_1.assertNoActiveChildBeforeDispatch)(state, telemetryFile);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Only emit telemetry once per invalid-inline condition
+        if (!invalidInlineAlreadyRecorded) {
+            const event = {
+                event: "invalid-inline-attempt",
+                run_id: state.run_id,
+                child_id: state.active_child,
+                reason: msg,
+                timestamp: new Date().toISOString(),
+            };
+            appendTelemetry(telemetryFile, event);
+            const defaultTelemetryFile = (0, node_path_1.join)(options.repoRoot, ".taskchain_artifacts", "polaris-run", "runs", state.run_id, "telemetry.jsonl");
+            if (defaultTelemetryFile !== telemetryFile) {
+                appendTelemetry(defaultTelemetryFile, event);
+            }
+        }
+        fail(msg);
+    }
+    // ── Branch custody enforcement ─────────────────────────────────────────────
+    // Implementation workers must never run on a protected base branch (main,
+    // master, etc.).  The delivery branch is recorded in cluster-state on first
+    // dispatch and every subsequent dispatch is verified against it.
+    //
+    // direct-main mode (loop.allowBranchDivergence: true) skips custody checks
+    // to support repositories that intentionally commit straight to their default
+    // branch.
+    let custodyRecord;
+    {
+        let dispatchCurrentBranch = getCurrentBranch(options.repoRoot);
+        const directMainMode = loadedConfig?.loop?.allowBranchDivergence === true;
+        if (!directMainMode) {
+            const existingForCustody = (0, store_js_1.readClusterStateSync)(state.cluster_id, options.repoRoot);
+            if (existingForCustody?.delivery_branch) {
+                // Custody already recorded — current branch must match.
+                try {
+                    (0, git_custody_js_1.assertDeliveryBranchMatch)(dispatchCurrentBranch, existingForCustody.delivery_branch);
+                }
+                catch (err) {
+                    fail(err instanceof Error ? err.message : String(err));
+                }
+            }
+            else {
+                // First dispatch — ensure we are on a delivery (non-base) branch.
+                if ((0, git_custody_js_1.isProtectedBranch)(dispatchCurrentBranch)) {
+                    // Auto-create and switch to the cluster's delivery branch.
+                    const deliveryBranchName = (0, git_custody_js_1.buildDeliveryBranchName)(state.cluster_id);
+                    try {
+                        (0, git_custody_js_1.ensureDeliveryBranch)(options.repoRoot, deliveryBranchName);
+                        dispatchCurrentBranch = deliveryBranchName;
+                    }
+                    catch (err) {
+                        fail(`Cannot create delivery branch "${deliveryBranchName}": ` +
+                            `${err instanceof Error ? err.message : String(err)}. ` +
+                            `Switch to a delivery branch before dispatching.`);
+                    }
+                }
+                // Record custody for this cluster.
+                const configBaseBranch = loadedConfig?.finalize?.targetBranch ?? "main";
+                custodyRecord = (0, git_custody_js_1.buildCustodyRecord)(options.repoRoot, dispatchCurrentBranch, configBaseBranch);
+            }
+        }
+    }
+    const childId = selectChild(state, options.childId);
+    const dispatchId = (0, node_crypto_1.randomUUID)();
+    // Compute canonical artifact paths before building the packet so that
+    // result_file_contract is always present in the saved JSON.
+    // options.resultFile acts as an override; the cluster-scoped path is the default.
+    const { packetPath, resultPath, relativePacketPath, relativeResultPath } = buildClusterArtifactPaths(options.repoRoot, state.cluster_id, childId, dispatchId);
+    const canonicalResultFile = options.resultFile
+        ? canonicalPath(absoluteResultFile(options.repoRoot, options.resultFile))
+        : resultPath;
+    // Use canonicalResultFile as the effective result path when options.resultFile is provided
+    const effectiveResultPath = canonicalResultFile;
+    const relativeEffectiveResultPath = (0, node_path_1.relative)(options.repoRoot, effectiveResultPath);
+    // ── Build packet before writing state ───────────────────────────────────────
+    // We need to build the packet first to know its content for the artifact.
+    // Use a preliminary state to build the packet (we'll update state after).
+    const preliminaryState = {
+        ...state,
+        active_child: childId,
+        next_open_child: childId,
+        step_cursor: "dispatch",
+        dispatch_boundary: (0, dispatch_boundary_js_1.advanceDispatchEpoch)(state.dispatch_boundary, childId),
+    };
+    const packet = buildPacket(preliminaryState, childId, options.stateFile, telemetryFile, options.repoRoot, canonicalResultFile);
+    const packetFailure = detectPacketGenerationFailure(packet);
+    if (packetFailure) {
+        appendTelemetry(telemetryFile, {
+            event: "packet-generation-failed",
+            run_id: state.run_id,
+            child_id: childId,
+            missing_field: packetFailure.missingField,
+            error: packetFailure.message,
+            timestamp: new Date().toISOString(),
+        });
+        fail(`${packetFailure.message} (missing_field=${packetFailure.missingField}, child_id=${childId})`);
+    }
+    const targetRole = roleContextToExecutionRole(packet.role_context.role);
+    // ── Resolve provider and dispatch mode ─────────────────────────────────────
+    // loadedConfig was loaded earlier (above bootstrap seal check)
+    let providerDecision;
+    try {
+        providerDecision = resolveProviderAndMode(options, targetRole, loadedConfig);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    const { provider: resolvedProvider } = providerDecision;
+    const providerPolicy = loadedConfig?.execution.providerPolicy ?? getProviderPolicy(options.repoRoot);
+    try {
+        assertProviderAllowedForRole(targetRole, resolvedProvider, providerPolicy, telemetryFile, dispatchId, state.run_id, childId);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    // ── Provider probe on first dispatch ──────────────────────────────────────
+    // Catches provider configuration failures before packet commit. Only runs on
+    // the first dispatch for this run (no completed children) in direct-worker
+    // mode. Best-effort — never blocks dispatch if probe infrastructure fails.
+    if (resolvedProvider && providerDecision.mode === "direct-worker" && state.completed_children.length === 0) {
+        try {
+            const probeResult = probeProviderSync(resolvedProvider, loadedConfig);
+            if (!probeResult.ok) {
+                appendTelemetry(telemetryFile, {
+                    event: "provider-probe-failed",
+                    run_id: state.run_id,
+                    child_id: childId,
+                    provider: resolvedProvider,
+                    error: probeResult.error,
+                    timestamp: new Date().toISOString(),
+                });
+                // Only hard-fail when the provider is explicitly unknown (not just missing from PATH)
+                if (probeResult.error?.startsWith(`Unknown provider`)) {
+                    fail(`Provider probe failed for "${resolvedProvider}": ${probeResult.error}. Resolve the provider configuration before dispatching.`);
+                }
+                // Command not on PATH — emit warning to stderr but allow dispatch to proceed
+                process.stderr.write(`Warning: provider command for "${resolvedProvider}" not found on PATH. ` +
+                    `Dispatch will proceed but execution may fail.\n`);
+            }
+            else {
+                appendTelemetry(telemetryFile, {
+                    event: "provider-probe-passed",
+                    run_id: state.run_id,
+                    child_id: childId,
+                    provider: resolvedProvider,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+        catch (err) {
+            // Probe infrastructure unavailable — log and continue
+            appendTelemetry(telemetryFile, {
+                event: "provider-probe-skipped",
+                run_id: state.run_id,
+                child_id: childId,
+                provider: resolvedProvider,
+                reason: err instanceof Error ? err.message : String(err),
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    // ── Write durable dispatch evidence ────────────────────────────────────────
+    // Create cluster-scoped packet artifact BEFORE updating state.
+    // This ensures "dispatched" only means a durable record exists.
+    // (packetPath / resultPath etc. were already computed above before packet build)
+    // Write packet artifact - this MUST succeed before we report dispatch success
+    try {
+        writePacketArtifact(packetPath, packet);
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        // Record the failure in telemetry
+        appendTelemetry(telemetryFile, {
+            event: "dispatch-failed",
+            run_id: state.run_id,
+            child_id: childId,
+            error: `Failed to write packet artifact: ${errorMsg}`,
+            timestamp: new Date().toISOString(),
+        });
+        fail(`Failed to write packet artifact to ${packetPath}: ${errorMsg}`);
+    }
+    // Create dispatch record with all evidence
+    const dispatchRecord = createDispatchRecord(state.run_id, state.cluster_id, childId, relativePacketPath, relativeEffectiveResultPath, packet.role_context, resolvedProvider, providerDecision.selectionReason, providerDecision.overrideSource, providerDecision.providersTried);
+    emitProviderFallbackAttempted(telemetryFile, dispatchRecord.dispatch_id, state.run_id, childId, providerDecision);
+    emitProviderExhausted(telemetryFile, dispatchRecord.dispatch_id, state.run_id, childId, providerDecision);
+    emitProviderSelected(telemetryFile, dispatchRecord.dispatch_id, state.run_id, childId, providerDecision);
+    // ── Delegated assignment: attempt spawn with fallback chain ────────────────
+    // For delegated mode (no provider), attempt subagent spawn now.
+    // Emit all telemetry events BEFORE updating dispatch state.
+    // Write complete assignment evidence BEFORE worker begins executing.
+    if (dispatchRecord.dispatch_mode === "delegated") {
+        const assignmentOutcome = attemptDelegatedAssignment(telemetryFile, dispatchRecord.dispatch_id, state.run_id, childId, packet, providerPolicy);
+        dispatchRecord.worker_assignment = assignmentOutcome.assignment;
+        dispatchRecord.session_id = assignmentOutcome.session_id;
+        dispatchRecord.attachment_capable = assignmentOutcome.attachment_capable;
+        dispatchRecord.runtime_state = assignmentOutcome.runtime_state;
+    }
+    // ── Update state atomically with dispatch record ───────────────────────────
+    // Assignment evidence is populated in dispatchRecord BEFORE this write.
+    // This upholds the evidence-before-execution invariant.
+    const updatedState = {
+        ...preliminaryState,
+        // Store the dispatch record in open_children_meta for the child
+        open_children_meta: {
+            ...state.open_children_meta,
+            [childId]: {
+                ...state.open_children_meta?.[childId],
+                dispatch_record: dispatchRecord,
+            },
+        },
+    };
+    try {
+        syncClusterDispatchState(state, childId, dispatchRecord, relativePacketPath, options.repoRoot, custodyRecord);
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        appendTelemetry(telemetryFile, {
+            event: "dispatch-failed",
+            run_id: state.run_id,
+            child_id: childId,
+            error: `Failed to sync cluster-state: ${errorMsg}`,
+            timestamp: new Date().toISOString(),
+        });
+        fail(`Failed to sync cluster-state for ${childId}: ${errorMsg}`);
+    }
+    (0, checkpoint_js_1.writeStateAtomic)(options.stateFile, updatedState);
+    appendDispatchLedgerEvent(options.repoRoot, updatedState, childId);
+    appendTelemetry(telemetryFile, {
+        event: "child-dispatched",
+        run_id: updatedState.run_id,
+        child_id: childId,
+        prompt_mode: packet.prompt_mode,
+        prompt_estimated_tokens: packet.prompt_metrics.estimated_tokens,
+        packet_path: packetPath,
+        expected_result_path: effectiveResultPath,
+        dispatch_mode: dispatchRecord.dispatch_mode,
+        runtime_state: dispatchRecord.runtime_state,
+        provider: dispatchRecord.provider ?? null,
+        timestamp: new Date().toISOString(),
+    });
+    // ── Apply lifecycle transition for child-dispatch event ────────────────────
+    // This is fire-and-forget: dispatch must not block on tracker mutations.
+    // Errors are logged to telemetry but do not fail the dispatch.
+    if (loadedConfig) {
+        let adapter;
+        try {
+            adapter = (0, index_js_1.loadTrackerAdapter)(loadedConfig);
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            appendTelemetry(telemetryFile, {
+                event: "lifecycle-transition-error",
+                run_id: updatedState.run_id,
+                child_id: childId,
+                transition_event: "child-dispatch",
+                error: `Failed to load tracker adapter: ${errorMsg}`,
+                timestamp: new Date().toISOString(),
+            });
+            adapter = null;
+        }
+        const lifecyclePolicy = loadedConfig.tracker?.lifecyclePolicy;
+        if (adapter || lifecyclePolicy) {
+            try {
+                const transitionService = new lifecycle_transition_js_1.LifecycleTransitionService();
+                transitionService
+                    .applyTransitionSafe({
+                    adapter,
+                    policy: lifecyclePolicy,
+                    taskId: childId,
+                    event: "child-dispatch",
+                    evidence: {
+                        packetFile: packetPath,
+                    },
+                    timestamp: new Date().toISOString(),
+                })
+                    .then((result) => {
+                    appendTelemetry(telemetryFile, {
+                        event: "lifecycle-transition-attempt",
+                        run_id: updatedState.run_id,
+                        child_id: childId,
+                        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: updatedState.run_id,
+                        child_id: childId,
+                        transition_event: "child-dispatch",
+                        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: updatedState.run_id,
+                    child_id: childId,
+                    transition_event: "child-dispatch",
+                    error: `Failed to create lifecycle transition service: ${errorMsg}`,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+    }
+    process.stdout.write(`${JSON.stringify(packet, null, 2)}\n`);
+}
+/**
+ * Check if the active child's dispatch has exceeded the acknowledgment timeout.
+ * Returns the result of the check and emits recovery telemetry if timeout exceeded.
+ *
+ * Scenario B: worker_id present, acknowledged_at null, >launch_to_first_heartbeat_ms elapsed.
+ * Scenario E: dispatched_at present, state handoff-pending, >stale_dispatch_timeout elapsed.
+ */
+function checkAcknowledgmentTimeout(options) {
+    const launchTimeout = options.launchToFirstHeartbeatMs ?? 30_000;
+    const staleTimeout = options.staleDispatchTimeoutMs ?? 1_800_000; // 30 min
+    let state;
+    try {
+        state = (0, checkpoint_js_1.readState)(options.stateFile);
+    }
+    catch {
+        return null;
+    }
+    if (!state.active_child)
+        return null;
+    const childMeta = state.open_children_meta?.[state.active_child];
+    const dr = childMeta?.dispatch_record;
+    if (!dr)
+        return null;
+    const now = Date.now();
+    const dispatchedAt = new Date(dr.dispatched_at).getTime();
+    const elapsed = now - dispatchedAt;
+    const telemetryFile = resolveTelemetryFile(state, options.repoRoot);
+    // Scenario B: worker dispatched but not acknowledged within launch timeout
+    if (dr.worker_id && !dr.first_heartbeat_at && elapsed > launchTimeout && dr.runtime_state !== "orphaned") {
+        const recoveryEvent = {
+            event: "child-recovery-initiated",
+            event_id: (0, node_crypto_1.randomUUID)(),
+            child_id: state.active_child,
+            dispatch_id: dr.dispatch_id,
+            recovery_reason: "no-acknowledgment",
+            detected_at: new Date().toISOString(),
+        };
+        appendTelemetry(telemetryFile, recoveryEvent);
+        const orphanEvent = {
+            event: "child-orphaned",
+            event_id: (0, node_crypto_1.randomUUID)(),
+            child_id: state.active_child,
+            dispatch_id: dr.dispatch_id,
+            last_heartbeat_at: dr.last_heartbeat_at ?? null,
+            orphaned_at: new Date().toISOString(),
+        };
+        appendTelemetry(telemetryFile, orphanEvent);
+        // Update runtime_state to orphaned
+        const updatedMeta = {
+            ...state.open_children_meta,
+            [state.active_child]: {
+                ...childMeta,
+                dispatch_record: { ...dr, runtime_state: "orphaned" },
+            },
+        };
+        (0, checkpoint_js_1.writeStateAtomic)(options.stateFile, { ...state, open_children_meta: updatedMeta });
+        return { childId: state.active_child, dispatchId: dr.dispatch_id, orphaned: true, reason: "no-acknowledgment" };
+    }
+    // Scenario E: stale dispatch — dispatched but state hasn't progressed
+    if (dr.runtime_state === "packet-created" && elapsed > staleTimeout) {
+        const recoveryEvent = {
+            event: "child-recovery-initiated",
+            event_id: (0, node_crypto_1.randomUUID)(),
+            child_id: state.active_child,
+            dispatch_id: dr.dispatch_id,
+            recovery_reason: "stale-dispatch",
+            detected_at: new Date().toISOString(),
+        };
+        appendTelemetry(telemetryFile, recoveryEvent);
+        const orphanEvent = {
+            event: "child-orphaned",
+            event_id: (0, node_crypto_1.randomUUID)(),
+            child_id: state.active_child,
+            dispatch_id: dr.dispatch_id,
+            last_heartbeat_at: null,
+            orphaned_at: new Date().toISOString(),
+        };
+        appendTelemetry(telemetryFile, orphanEvent);
+        const updatedMeta = {
+            ...state.open_children_meta,
+            [state.active_child]: {
+                ...childMeta,
+                dispatch_record: { ...dr, runtime_state: "orphaned" },
+            },
+        };
+        (0, checkpoint_js_1.writeStateAtomic)(options.stateFile, { ...state, open_children_meta: updatedMeta });
+        return { childId: state.active_child, dispatchId: dr.dispatch_id, orphaned: true, reason: "stale-dispatch" };
+    }
+    return { childId: state.active_child, dispatchId: dr.dispatch_id, orphaned: false };
+}