@lsctech/polaris 0.1.0

package/dist/cli/version.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVersion = getVersion;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function getVersion() {
+    const packageJsonPath = (0, node_path_1.resolve)(__dirname, "../../package.json");
+    const packageJson = JSON.parse((0, node_fs_1.readFileSync)(packageJsonPath, "utf-8"));
+    return packageJson.version;
+}

package/dist/cli/version.test.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const version_js_1 = require("./version.js");
+(0, vitest_1.describe)("getVersion", () => {
+    (0, vitest_1.it)("returns a version string", () => {
+        const version = (0, version_js_1.getVersion)();
+        (0, vitest_1.expect)(typeof version).toBe("string");
+        (0, vitest_1.expect)(version.length).toBeGreaterThan(0);
+    });
+});

package/dist/cli/worker.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkerCommand = createWorkerCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const commander_1 = require("commander");
+const worker_js_1 = require("../loop/worker.js");
+const worker_packet_js_1 = require("../loop/worker-packet.js");
+const git_custody_js_1 = require("../loop/git-custody.js");
+const checkpoint_js_1 = require("../loop/checkpoint.js");
+const store_js_1 = require("../cluster-state/store.js");
+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 failWithHelp(command, commandName) {
+    const subcommand = command.args[0];
+    const message = subcommand
+        ? `error: unknown command '${subcommand}' for '${commandName}'. Run '${commandName} --help'.`
+        : `error: missing command for '${commandName}'. Run '${commandName} --help'.`;
+    command.error(message, {
+        code: "commander.missingCommand",
+        exitCode: 1,
+    });
+}
+function readActiveWorkerPacket() {
+    const packet = (0, worker_js_1.readBootstrapPacket)(process.argv);
+    if (!(0, worker_packet_js_1.isWorkerPacket)(packet)) {
+        throw new Error("Active worker packet is missing or invalid");
+    }
+    return packet;
+}
+function getCommitHash(repoRoot) {
+    return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], {
+        cwd: repoRoot,
+        encoding: "utf-8",
+    }).trim();
+}
+function resolveRepoPath(repoRoot, path) {
+    return (0, node_path_1.isAbsolute)(path) ? path : (0, node_path_1.resolve)(repoRoot, path);
+}
+function validateWorkerCompletionResult(repoRoot, packet, resultFile) {
+    if (!resultFile) {
+        return { ok: false, reason: "missing result file path" };
+    }
+    if (!packet.active_child) {
+        return { ok: false, reason: "active worker packet has no active_child" };
+    }
+    const resolvedResultFile = resolveRepoPath(repoRoot, resultFile);
+    let parsed;
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)(resolvedResultFile, "utf-8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return { ok: false, reason: "sealed result is not a JSON object" };
+        }
+        parsed = raw;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `failed to read sealed result (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    const runId = String(parsed["run_id"] ?? "").trim();
+    if (runId !== packet.run_id) {
+        return { ok: false, reason: `sealed result run_id "${runId || "missing"}" does not match active packet` };
+    }
+    const childId = String(parsed["child_id"] ?? "").trim();
+    if (childId !== packet.active_child) {
+        return { ok: false, reason: `sealed result child_id "${childId || "missing"}" does not match active child "${packet.active_child}"` };
+    }
+    const status = String(parsed["status"] ?? "").trim().toLowerCase();
+    if (!["success", "done"].includes(status)) {
+        return { ok: false, reason: `sealed result status is "${status || "missing"}" (expected success)` };
+    }
+    const commit = String(parsed["commit"] ?? parsed["commit_hash"] ?? parsed["commit_sha"] ?? "").trim();
+    if (!commit) {
+        return { ok: false, reason: "sealed result is missing commit evidence" };
+    }
+    if (!/^[0-9a-f]{7,40}$/i.test(commit)) {
+        return { ok: false, reason: `sealed result commit "${commit}" is not a valid git hash` };
+    }
+    try {
+        (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--verify", "--quiet", `${commit}^{commit}`], {
+            cwd: repoRoot,
+            stdio: "ignore",
+        });
+    }
+    catch {
+        return { ok: false, reason: `sealed result commit "${commit}" could not be verified in git` };
+    }
+    return {
+        ok: true,
+        result: {
+            ...parsed,
+            run_id: packet.run_id,
+            child_id: packet.active_child,
+            status: status === "done" ? "done" : "success",
+            commit,
+        },
+    };
+}
+function updateCompletionState(state, childId, commit) {
+    const completedChildren = Array.from(new Set([...state.completed_children, childId]));
+    const remainingOpenChildren = state.open_children.filter((child) => child !== childId);
+    const completedChildrenResults = {
+        ...(state.completed_children_results ?? {}),
+        [childId]: {
+            status: "done",
+            validation: "passed",
+            commit,
+            next_recommended_action: "continue",
+        },
+    };
+    return {
+        ...state,
+        active_child: "",
+        open_children: remainingOpenChildren,
+        completed_children: completedChildren,
+        completed_children_results: completedChildrenResults,
+        next_open_child: remainingOpenChildren[0] ?? null,
+        step_cursor: "checkpoint",
+        status: remainingOpenChildren.length > 0 ? "running" : "cluster-complete",
+        last_commit: commit,
+        context_budget: {
+            ...state.context_budget,
+            children_completed: completedChildren.length,
+        },
+        updated_at: new Date().toISOString(),
+    };
+}
+function emitWorkerCompletionTelemetry(telemetryFile, event) {
+    try {
+        appendTelemetry(telemetryFile, event);
+    }
+    catch (error) {
+        process.stderr.write(`[polaris-worker] telemetry write failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function createWorkerCommand(options) {
+    const worker = new commander_1.Command("worker")
+        .description("mutating: worker-owned commit operations")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    worker.action(() => failWithHelp(worker, "polaris worker"));
+    worker
+        .command("commit")
+        .description("mutating: validate the staged git index against the active worker packet and create one commit")
+        .action(() => {
+        try {
+            const packet = readActiveWorkerPacket();
+            const { allowedScope, prohibitedWritePaths } = (0, worker_packet_js_1.getWorkerCommitPolicy)(packet);
+            const validation = (0, git_custody_js_1.validateWorkerCommitScope)(options.repoRoot, allowedScope, prohibitedWritePaths);
+            if (validation.staged_files.length === 0) {
+                appendTelemetry(packet.telemetry_file, {
+                    event: "worker-commit-rejected",
+                    event_id: (0, node_crypto_1.randomUUID)(),
+                    run_id: packet.run_id,
+                    child_id: packet.active_child,
+                    reason: "no-staged-files",
+                    allowed_scope: allowedScope,
+                    prohibited_write_paths: prohibitedWritePaths,
+                    staged_files: [],
+                    violations: [],
+                    timestamp: new Date().toISOString(),
+                });
+                process.stderr.write("worker commit rejected: no staged files\n");
+                process.exit(1);
+            }
+            if (validation.violations.length > 0) {
+                appendTelemetry(packet.telemetry_file, {
+                    event: "worker-commit-rejected",
+                    event_id: (0, node_crypto_1.randomUUID)(),
+                    run_id: packet.run_id,
+                    child_id: packet.active_child,
+                    reason: "scope-violation",
+                    allowed_scope: allowedScope,
+                    prohibited_write_paths: prohibitedWritePaths,
+                    staged_files: validation.staged_files,
+                    violations: validation.violations,
+                    timestamp: new Date().toISOString(),
+                });
+                const summary = validation.violations
+                    .map((violation) => `${violation.kind}:${violation.path}`)
+                    .join(", ");
+                process.stderr.write(`worker commit rejected: ${summary}\n`);
+                process.exit(1);
+            }
+            (0, node_child_process_1.execFileSync)("git", ["commit", "-m", `polaris worker commit: ${packet.active_child || packet.run_id}`], {
+                cwd: options.repoRoot,
+                stdio: "ignore",
+            });
+            process.stdout.write(`${getCommitHash(options.repoRoot)}\n`);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith("process.exit(")) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`worker commit failed: ${message}\n`);
+            process.exit(1);
+        }
+    });
+    worker
+        .command("complete")
+        .description("mutating: validate a sealed worker result and update current-state.json")
+        .argument("<result-file>", "Path to the sealed worker result JSON")
+        .action((resultFile) => {
+        let packet;
+        try {
+            packet = readActiveWorkerPacket();
+        }
+        catch (error) {
+            process.stderr.write(`worker complete failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+            return;
+        }
+        try {
+            const stateFile = resolveRepoPath(options.repoRoot, packet.state_file);
+            const telemetryFile = resolveRepoPath(options.repoRoot, packet.telemetry_file);
+            const validation = validateWorkerCompletionResult(options.repoRoot, packet, resultFile);
+            if (!validation.ok) {
+                emitWorkerCompletionTelemetry(telemetryFile, {
+                    event: "worker-complete-failed",
+                    event_id: (0, node_crypto_1.randomUUID)(),
+                    run_id: packet.run_id,
+                    child_id: packet.active_child,
+                    result_file: resolveRepoPath(options.repoRoot, resultFile),
+                    reason: validation.reason,
+                    timestamp: new Date().toISOString(),
+                });
+                process.stderr.write(`worker complete rejected: ${validation.reason}\n`);
+                process.exit(1);
+                return;
+            }
+            const state = (0, checkpoint_js_1.readState)(stateFile);
+            const updatedState = updateCompletionState(state, packet.active_child, validation.result.commit);
+            (0, checkpoint_js_1.writeStateAtomic)(stateFile, updatedState);
+            // Sync cluster-state.json so finalize and the parent loop see a consistent view.
+            try {
+                const clusterState = (0, store_js_1.readClusterStateSync)(packet.cluster_id, options.repoRoot);
+                if (clusterState) {
+                    const childExists = clusterState.child_states.some((c) => c.id === packet.active_child);
+                    const childStates = childExists
+                        ? clusterState.child_states.map((c) => c.id === packet.active_child ? { ...c, status: "done", commit: validation.result.commit } : c)
+                        : [...clusterState.child_states, { id: packet.active_child, status: "done", commit: validation.result.commit }];
+                    (0, store_js_1.writeClusterStateSync)(packet.cluster_id, {
+                        ...clusterState,
+                        state_generation: clusterState.state_generation + 1,
+                        child_states: childStates,
+                        commits: { ...clusterState.commits, [packet.active_child]: validation.result.commit },
+                    }, options.repoRoot);
+                }
+            }
+            catch (error) {
+                process.stderr.write(`[polaris-worker] cluster-state sync failed for ${packet.cluster_id} / ${packet.active_child}: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+            emitWorkerCompletionTelemetry(telemetryFile, {
+                event: "worker-complete",
+                event_id: (0, node_crypto_1.randomUUID)(),
+                run_id: packet.run_id,
+                child_id: packet.active_child,
+                result_file: resolveRepoPath(options.repoRoot, resultFile),
+                status: validation.result.status,
+                commit: validation.result.commit,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const telemetryFile = resolveRepoPath(options.repoRoot, packet.telemetry_file);
+            emitWorkerCompletionTelemetry(telemetryFile, {
+                event: "worker-complete-failed",
+                event_id: (0, node_crypto_1.randomUUID)(),
+                run_id: packet.run_id,
+                child_id: packet.active_child,
+                result_file: resolveRepoPath(options.repoRoot, resultFile),
+                reason: error instanceof Error ? error.message : String(error),
+                timestamp: new Date().toISOString(),
+            });
+            process.stderr.write(`worker complete failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+    });
+    return worker;
+}

package/dist/cluster-state/fixtures/test-clusters.json

@@ -0,0 +1,19 @@
+{
+    "schemaVersion": "2.0",
+    "activeCluster": "POL-TEST-1",
+    "clusters": {
+        "POL-TEST-1": {
+            "id": "POL-TEST-1",
+            "title": "Test Cluster",
+            "children": ["CHILD-1", "CHILD-2"]
+        }
+    },
+    "nodes": {
+        "POL-TEST-1": { "id": "POL-TEST-1", "type": "cluster" },
+        "CHILD-1": { "id": "CHILD-1", "type": "issue" },
+        "CHILD-2": { "id": "CHILD-2", "type": "issue" }
+    },
+    "dependencies": {
+        "CHILD-2": ["CHILD-1"]
+    }
+}

package/dist/cluster-state/store.js

@@ -0,0 +1,302 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeClusterState = exports.writeClusterStateSync = exports.writeClusterState = exports.readClusterStateSync = exports.readClusterState = void 0;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const local_graph_1 = require("../tracker/local-graph");
+const getClusterStatePath = (clusterId, repoRoot) => {
+    return path.join(repoRoot || process.cwd(), '.polaris', 'clusters', clusterId, 'cluster-state.json');
+};
+const normalizeClusterState = (state) => ({
+    ...state,
+    tracker_mutations: state.tracker_mutations ?? {},
+});
+const readClusterState = async (clusterId, repoRoot) => {
+    const filePath = getClusterStatePath(clusterId, repoRoot);
+    try {
+        const data = await fs_1.promises.readFile(filePath, 'utf-8');
+        if (!data) {
+            return null;
+        }
+        return normalizeClusterState(JSON.parse(data));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+};
+exports.readClusterState = readClusterState;
+const readClusterStateSync = (clusterId, repoRoot) => {
+    const filePath = getClusterStatePath(clusterId, repoRoot);
+    try {
+        const data = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        if (!data) {
+            return null;
+        }
+        return normalizeClusterState(JSON.parse(data));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+};
+exports.readClusterStateSync = readClusterStateSync;
+const writeClusterState = async (clusterId, state, repoRoot) => {
+    const filePath = getClusterStatePath(clusterId, repoRoot);
+    const lockFilePath = filePath + '.lock';
+    const tempFilePath = `${filePath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    // Acquire lock (simple lock file approach with retry)
+    let lockAcquired = false;
+    const maxRetries = 50;
+    const retryDelayMs = 100;
+    const staleLockThresholdMs = 30000; // 30 seconds
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            // Try to create lock file exclusively (fails if it already exists)
+            await fs_1.promises.writeFile(lockFilePath, String(process.pid), { flag: 'wx' });
+            lockAcquired = true;
+            break;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                // Lock file exists, check if it's stale before retrying
+                try {
+                    const lockStat = await fs_1.promises.stat(lockFilePath);
+                    const lockAge = Date.now() - lockStat.mtimeMs;
+                    if (lockAge > staleLockThresholdMs) {
+                        // Lock is stale, try to read the PID
+                        let isStale = true;
+                        try {
+                            const lockContent = await fs_1.promises.readFile(lockFilePath, 'utf-8');
+                            const lockPid = parseInt(lockContent.trim(), 10);
+                            // Check if the process is still running
+                            if (!isNaN(lockPid)) {
+                                try {
+                                    // process.kill with signal 0 checks existence without killing
+                                    process.kill(lockPid, 0);
+                                    // Process exists, lock is not stale
+                                    isStale = false;
+                                }
+                                catch (pidError) {
+                                    // Process doesn't exist (ESRCH) or no permission (EPERM)
+                                    // If EPERM, process exists but we can't signal it, so not stale
+                                    if (pidError.code === 'EPERM') {
+                                        isStale = false;
+                                    }
+                                    // Otherwise (ESRCH), process doesn't exist, lock is stale
+                                }
+                            }
+                        }
+                        catch {
+                            // If we can't read the lock file or parse PID, consider it stale based on age
+                        }
+                        if (isStale) {
+                            console.warn(`Removing stale lock file for cluster ${clusterId} (age: ${lockAge}ms)`);
+                            try {
+                                await fs_1.promises.unlink(lockFilePath);
+                                // Retry immediately after removing stale lock
+                                continue;
+                            }
+                            catch (unlinkError) {
+                                // Race condition: another process may have removed it
+                                if (unlinkError.code !== 'ENOENT') {
+                                    throw unlinkError;
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (statError) {
+                    // If lock file disappeared between EEXIST and stat, retry
+                    if (statError.code === 'ENOENT') {
+                        continue;
+                    }
+                    // Other errors during stat, just retry with delay
+                }
+                // Lock file exists and is not stale, wait and retry
+                await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    if (!lockAcquired) {
+        throw new Error(`Failed to acquire lock for cluster state ${clusterId} after ${maxRetries} attempts`);
+    }
+    try {
+        // Re-read current state under lock
+        const currentState = await (0, exports.readClusterState)(clusterId, repoRoot);
+        if (currentState && currentState.state_generation >= state.state_generation) {
+            throw new Error('Stale state: state_generation is not greater than current state.');
+        }
+        // Write to unique temp file and atomically rename
+        await fs_1.promises.writeFile(tempFilePath, JSON.stringify(state, null, 2));
+        await fs_1.promises.rename(tempFilePath, filePath);
+    }
+    finally {
+        // Release lock
+        try {
+            await fs_1.promises.unlink(lockFilePath);
+        }
+        catch {
+            // Ignore errors during lock cleanup
+        }
+    }
+};
+exports.writeClusterState = writeClusterState;
+const writeClusterStateSync = (clusterId, state, repoRoot) => {
+    const filePath = getClusterStatePath(clusterId, repoRoot);
+    const lockFilePath = filePath + '.lock';
+    const tempFilePath = `${filePath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    let lockAcquired = false;
+    const maxRetries = 50;
+    const retryDelayMs = 100;
+    const staleLockThresholdMs = 30000;
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            (0, fs_1.mkdirSync)(path.dirname(lockFilePath), { recursive: true });
+            (0, fs_1.writeFileSync)(lockFilePath, String(process.pid), { flag: 'wx' });
+            lockAcquired = true;
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+            try {
+                const lockStat = (0, fs_1.statSync)(lockFilePath);
+                const lockAge = Date.now() - lockStat.mtimeMs;
+                if (lockAge > staleLockThresholdMs) {
+                    let isStale = true;
+                    try {
+                        const lockContent = (0, fs_1.readFileSync)(lockFilePath, 'utf-8');
+                        const lockPid = parseInt(lockContent.trim(), 10);
+                        if (!isNaN(lockPid)) {
+                            try {
+                                process.kill(lockPid, 0);
+                                isStale = false;
+                            }
+                            catch (pidError) {
+                                if (pidError.code === 'EPERM') {
+                                    isStale = false;
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Ignore parse/read failure and fall back to age-based stale handling.
+                    }
+                    if (isStale) {
+                        try {
+                            (0, fs_1.unlinkSync)(lockFilePath);
+                            continue;
+                        }
+                        catch (unlinkError) {
+                            if (unlinkError.code !== 'ENOENT') {
+                                throw unlinkError;
+                            }
+                        }
+                    }
+                }
+            }
+            catch (statError) {
+                if (statError.code === 'ENOENT') {
+                    continue;
+                }
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, retryDelayMs);
+        }
+    }
+    if (!lockAcquired) {
+        throw new Error(`Failed to acquire lock for cluster state ${clusterId} after ${maxRetries} attempts`);
+    }
+    try {
+        const currentState = (0, exports.readClusterStateSync)(clusterId, repoRoot);
+        if (currentState && currentState.state_generation >= state.state_generation) {
+            throw new Error('Stale state: state_generation is not greater than current state.');
+        }
+        (0, fs_1.mkdirSync)(path.dirname(filePath), { recursive: true });
+        (0, fs_1.writeFileSync)(tempFilePath, JSON.stringify(state, null, 2));
+        (0, fs_1.renameSync)(tempFilePath, filePath);
+    }
+    finally {
+        try {
+            (0, fs_1.unlinkSync)(lockFilePath);
+        }
+        catch {
+            // Ignore errors during lock cleanup.
+        }
+    }
+};
+exports.writeClusterStateSync = writeClusterStateSync;
+const initializeClusterState = async (clusterId, repoRoot) => {
+    const graph = await local_graph_1.LocalGraph.load(clusterId, repoRoot);
+    const activeCluster = graph.getActiveCluster();
+    if (!activeCluster) {
+        throw new Error(`Cluster ${clusterId} not found in graph.`);
+    }
+    // Exclude cluster root from child states — mirrors buildBootstrapPlan logic.
+    const clusterRoot = activeCluster.cluster_root;
+    const runnableChildren = clusterRoot
+        ? activeCluster.children.filter((id) => id !== clusterRoot)
+        : activeCluster.children;
+    const childrenToInitialize = runnableChildren.length > 0 ? runnableChildren : [clusterId];
+    const childStates = childrenToInitialize.map(childId => ({
+        id: childId,
+        status: 'ready',
+    }));
+    const initialState = {
+        schema_version: '1.0',
+        cluster_id: clusterId,
+        state_generation: 1,
+        child_states: childStates,
+        claim_metadata: {},
+        packet_pointers: {},
+        result_pointers: {},
+        validation_results: {},
+        commits: {},
+        tracker_mutations: {},
+        blockers: [],
+    };
+    await (0, exports.writeClusterState)(clusterId, initialState, repoRoot);
+    return initialState;
+};
+exports.initializeClusterState = initializeClusterState;