@lsctech/polaris 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const index_js_2 = require("./tools/index.js");
+const server = new index_js_1.Server({ name: "polaris", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: index_js_2.TOOLS }));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => (0, index_js_2.dispatchTool)(req.params.name, (req.params.arguments ?? {})));
+const transport = new stdio_js_1.StdioServerTransport();
+server.connect(transport).catch((err) => {
+    process.stderr.write(`MCP server fatal error: ${String(err)}\n`);
+    process.exit(1);
+});

package/dist/mcp/tools/claim-child.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handlePolarisClaimChild = handlePolarisClaimChild;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const pendingClaims = new Set();
+function parseArgs(args) {
+    const artifactDir = args.artifact_dir ?? "polaris-run";
+    const childId = args.child_id;
+    if (typeof artifactDir !== "string" || !/^[\w][\w.-]*$/.test(artifactDir)) {
+        throw new Error("artifact_dir must be a safe artifact directory name");
+    }
+    if (typeof childId !== "string" || childId.trim() === "") {
+        throw new Error("child_id must be a non-empty string");
+    }
+    return { artifactDir, childId };
+}
+function statePathFor(artifactDir) {
+    return (0, node_path_1.join)(process.cwd(), ".taskchain_artifacts", artifactDir, "current-state.json");
+}
+function telemetryPathFor(artifactDir, runId) {
+    return (0, node_path_1.join)(process.cwd(), ".taskchain_artifacts", artifactDir, "runs", runId, "telemetry.jsonl");
+}
+function writeJsonAtomic(path, value) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(value, null, 2) + "\n", "utf-8");
+    (0, node_fs_1.renameSync)(tmp, path);
+}
+function appendTelemetry(artifactDir, state, childId) {
+    if (typeof state["run_id"] !== "string") {
+        throw new Error("run_id must be a string in state before emitting telemetry");
+    }
+    const runId = state["run_id"];
+    const event = {
+        event: "mcp-claim-child",
+        run_id: runId,
+        child_id: childId,
+        timestamp: new Date().toISOString(),
+    };
+    const telemetryPath = telemetryPathFor(artifactDir, runId);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryPath), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryPath, JSON.stringify(event) + "\n", "utf-8");
+}
+async function handlePolarisClaimChild(args) {
+    let parsed;
+    try {
+        parsed = parseArgs(args);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: "invalid_argument",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const lockKey = parsed.artifactDir;
+    if (pendingClaims.has(lockKey)) {
+        return {
+            ok: false,
+            error: "already_claimed",
+            message: `A claim is already in progress for artifact_dir=${parsed.artifactDir}`,
+        };
+    }
+    pendingClaims.add(lockKey);
+    try {
+        const statePath = statePathFor(parsed.artifactDir);
+        let state;
+        try {
+            state = JSON.parse((0, node_fs_1.readFileSync)(statePath, "utf-8"));
+        }
+        catch {
+            return {
+                ok: false,
+                error: "state_not_found",
+                message: `State file not found or invalid: .taskchain_artifacts/${parsed.artifactDir}/current-state.json`,
+            };
+        }
+        if (typeof state["active_child"] === "string" && state["active_child"].length > 0) {
+            return {
+                ok: false,
+                error: "already_claimed",
+                active_child: state["active_child"],
+            };
+        }
+        const openChildren = Array.isArray(state["open_children"]) ? state["open_children"] : [];
+        if (!openChildren.includes(parsed.childId)) {
+            return {
+                ok: false,
+                error: "child_not_open",
+                child_id: parsed.childId,
+            };
+        }
+        const updated = {
+            ...state,
+            active_child: parsed.childId,
+            updated_at: new Date().toISOString(),
+        };
+        try {
+            writeJsonAtomic(statePath, updated);
+            appendTelemetry(parsed.artifactDir, updated, parsed.childId);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: "telemetry_write_failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        return {
+            ok: true,
+            child_id: parsed.childId,
+            active_child: parsed.childId,
+        };
+    }
+    finally {
+        pendingClaims.delete(lockKey);
+    }
+}

package/dist/mcp/tools/claim-child.test.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const claim_child_js_1 = require("./claim-child.js");
+const originalCwd = process.cwd();
+function makeTempRepo() {
+    return (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-claim-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+}
+function writeState(repoRoot, artifactDir, state) {
+    const dir = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", artifactDir);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, "current-state.json"), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+function readState(repoRoot, artifactDir) {
+    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, ".taskchain_artifacts", artifactDir, "current-state.json"), "utf-8"));
+}
+(0, vitest_1.describe)("handlePolarisClaimChild()", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeTempRepo();
+        (0, node_fs_1.mkdirSync)(repoRoot, { recursive: true });
+        process.chdir(repoRoot);
+    });
+    (0, vitest_1.afterEach)(() => {
+        process.chdir(originalCwd);
+        (0, node_fs_1.rmSync)(repoRoot, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)("sets active_child for an open child and appends telemetry", async () => {
+        writeState(repoRoot, "polaris-run", {
+            schema_version: "1.0",
+            run_id: "run-claim",
+            cluster_id: "POL-105",
+            active_child: null,
+            open_children: ["POL-111"],
+            completed_children: [],
+            context_budget: { children_completed: 0 },
+            status: "running",
+            step_cursor: "03-select-child",
+        });
+        const result = await (0, claim_child_js_1.handlePolarisClaimChild)({ child_id: "POL-111" });
+        (0, vitest_1.expect)(result["ok"]).toBe(true);
+        (0, vitest_1.expect)(result["active_child"]).toBe("POL-111");
+        (0, vitest_1.expect)(readState(repoRoot, "polaris-run")["active_child"]).toBe("POL-111");
+        const telemetry = (0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "runs", "run-claim", "telemetry.jsonl"), "utf-8");
+        (0, vitest_1.expect)(telemetry).toContain("\"event\":\"mcp-claim-child\"");
+        (0, vitest_1.expect)(telemetry).toContain("\"child_id\":\"POL-111\"");
+    });
+    (0, vitest_1.it)("returns already_claimed when active_child is already set", async () => {
+        writeState(repoRoot, "polaris-run", {
+            schema_version: "1.0",
+            run_id: "run-claim",
+            cluster_id: "POL-105",
+            active_child: "POL-110",
+            open_children: ["POL-111"],
+            completed_children: [],
+            context_budget: { children_completed: 0 },
+            status: "running",
+            step_cursor: "03-select-child",
+        });
+        const result = await (0, claim_child_js_1.handlePolarisClaimChild)({ child_id: "POL-111" });
+        (0, vitest_1.expect)(result["ok"]).toBe(false);
+        (0, vitest_1.expect)(result["error"]).toBe("already_claimed");
+        (0, vitest_1.expect)(result["active_child"]).toBe("POL-110");
+        (0, vitest_1.expect)(readState(repoRoot, "polaris-run")["active_child"]).toBe("POL-110");
+    });
+});

package/dist/mcp/tools/current-state.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handlePolarisCurrentState = handlePolarisCurrentState;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const root_js_1 = require("../lib/root.js");
+const redact_js_1 = require("../lib/redact.js");
+function isValidDirName(name) {
+    return /^[\w][\w.-]*$/.test(name) && !name.includes("..");
+}
+async function handlePolarisCurrentState(args) {
+    const repoRoot = (0, root_js_1.resolveRepoRoot)();
+    const artifactDir = args.artifact_dir ?? "polaris-run";
+    if (typeof artifactDir !== "string") {
+        return {
+            ok: false,
+            error: "invalid_argument",
+            message: `artifact_dir must be a string, received ${typeof artifactDir}: ${JSON.stringify(artifactDir)}`,
+        };
+    }
+    if (!isValidDirName(artifactDir)) {
+        return {
+            ok: false,
+            error: "invalid_argument",
+            message: `artifact_dir contains invalid characters: ${artifactDir}`,
+        };
+    }
+    const statePath = (0, node_path_1.resolve)((0, node_path_1.join)(repoRoot, ".taskchain_artifacts", artifactDir, "current-state.json"));
+    if (!statePath.startsWith(repoRoot)) {
+        return {
+            ok: false,
+            error: "invalid_argument",
+            message: "artifact_dir resolved outside repo root",
+        };
+    }
+    let raw;
+    try {
+        const realStatePath = (0, node_fs_1.realpathSync)(statePath);
+        const realRepoRoot = (0, node_fs_1.realpathSync)(repoRoot);
+        if (!realStatePath.startsWith(realRepoRoot + node_path_1.sep)) {
+            return {
+                ok: false,
+                error: "invalid_argument",
+                message: "artifact_dir resolved outside repo root (symlink detected)",
+            };
+        }
+        raw = (0, node_fs_1.readFileSync)(realStatePath, "utf-8");
+    }
+    catch {
+        return {
+            ok: false,
+            error: "state_not_found",
+            message: `State file not found: .taskchain_artifacts/${artifactDir}/current-state.json`,
+            hint: "Run a polaris cluster session first to create current-state.json",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            error: "parse_error",
+            message: "current-state.json is not valid JSON",
+        };
+    }
+    return {
+        ok: true,
+        artifact_dir: artifactDir,
+        state: (0, redact_js_1.redact)(parsed),
+    };
+}

package/dist/mcp/tools/current-state.test.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Integration tests for src/mcp/tools/current-state.ts
+ *
+ * Covers:
+ * - returns {ok:false, error:"state_not_found"} when file does not exist
+ * - returns {ok:true, artifact_dir, state} when file exists with valid JSON
+ * - returns {ok:false, error:"parse_error"} when file contains invalid JSON
+ * - returns {ok:false, error:"invalid_argument"} for artifact_dir with ".." path traversal
+ * - redacts sensitive keys from state
+ * - uses "polaris-run" as default artifact_dir
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+// We mock the root module so resolveRepoRoot() returns our temp dir
+vitest_1.vi.mock("../lib/root.js", () => ({
+    resolveRepoRoot: vitest_1.vi.fn(),
+}));
+const root_js_1 = require("../lib/root.js");
+const current_state_js_1 = require("./current-state.js");
+const mockResolveRepoRoot = vitest_1.vi.mocked(root_js_1.resolveRepoRoot);
+function makeTempDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-cs-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+function writeStateFile(repoRoot, artifactDir, content) {
+    const artifactsDir = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", artifactDir);
+    (0, node_fs_1.mkdirSync)(artifactsDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(artifactsDir, "current-state.json"), content);
+}
+(0, vitest_1.describe)("handlePolarisCurrentState()", () => {
+    let tempDir;
+    (0, vitest_1.beforeEach)(() => {
+        tempDir = makeTempDir();
+        mockResolveRepoRoot.mockReturnValue(tempDir);
+    });
+    (0, vitest_1.afterEach)(() => {
+        (0, node_fs_1.rmSync)(tempDir, { recursive: true, force: true });
+        vitest_1.vi.clearAllMocks();
+    });
+    (0, vitest_1.it)("returns {ok:false, error:'state_not_found'} when the state file does not exist", async () => {
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: "my-run" });
+        (0, vitest_1.expect)(result["ok"]).toBe(false);
+        (0, vitest_1.expect)(result["error"]).toBe("state_not_found");
+    });
+    (0, vitest_1.it)("returns {ok:true, artifact_dir, state} when the file exists with valid JSON", async () => {
+        const state = { status: "running", run_id: "pol-1" };
+        writeStateFile(tempDir, "my-run", JSON.stringify(state));
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: "my-run" });
+        (0, vitest_1.expect)(result["ok"]).toBe(true);
+        (0, vitest_1.expect)(result["artifact_dir"]).toBe("my-run");
+        (0, vitest_1.expect)(result["state"]).toMatchObject({ status: "running", run_id: "pol-1" });
+    });
+    (0, vitest_1.it)("returns {ok:false, error:'parse_error'} when the file contains invalid JSON", async () => {
+        writeStateFile(tempDir, "my-run", "{ this is not valid json }");
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: "my-run" });
+        (0, vitest_1.expect)(result["ok"]).toBe(false);
+        (0, vitest_1.expect)(result["error"]).toBe("parse_error");
+    });
+    (0, vitest_1.it)("returns {ok:false, error:'invalid_argument'} for artifact_dir containing '..'", async () => {
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: "../escape" });
+        (0, vitest_1.expect)(result["ok"]).toBe(false);
+        (0, vitest_1.expect)(result["error"]).toBe("invalid_argument");
+    });
+    (0, vitest_1.it)("returns {ok:false, error:'invalid_argument'} for artifact_dir that is just '..'", async () => {
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: ".." });
+        (0, vitest_1.expect)(result["ok"]).toBe(false);
+        (0, vitest_1.expect)(result["error"]).toBe("invalid_argument");
+    });
+    (0, vitest_1.it)("redacts sensitive keys from the returned state", async () => {
+        const state = {
+            status: "running",
+            token: "super-secret-token",
+            password: "hunter2",
+            accessToken: "bearer-xyz",
+            label: "visible-value",
+        };
+        writeStateFile(tempDir, "my-run", JSON.stringify(state));
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: "my-run" });
+        (0, vitest_1.expect)(result["ok"]).toBe(true);
+        const returnedState = result["state"];
+        (0, vitest_1.expect)(returnedState["token"]).toBe("[redacted]");
+        (0, vitest_1.expect)(returnedState["password"]).toBe("[redacted]");
+        (0, vitest_1.expect)(returnedState["accessToken"]).toBe("[redacted]");
+        (0, vitest_1.expect)(returnedState["label"]).toBe("visible-value");
+        (0, vitest_1.expect)(returnedState["status"]).toBe("running");
+    });
+    (0, vitest_1.it)("uses 'polaris-run' as default artifact_dir when none provided", async () => {
+        // Write the file at the default path
+        const state = { run_id: "default-run" };
+        writeStateFile(tempDir, "polaris-run", JSON.stringify(state));
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({});
+        (0, vitest_1.expect)(result["ok"]).toBe(true);
+        (0, vitest_1.expect)(result["artifact_dir"]).toBe("polaris-run");
+        (0, vitest_1.expect)(result["state"]["run_id"]).toBe("default-run");
+    });
+    (0, vitest_1.it)("uses 'polaris-run' as default when artifact_dir is undefined", async () => {
+        const state = { cluster_id: "C-1" };
+        writeStateFile(tempDir, "polaris-run", JSON.stringify(state));
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: undefined });
+        (0, vitest_1.expect)(result["ok"]).toBe(true);
+        (0, vitest_1.expect)(result["artifact_dir"]).toBe("polaris-run");
+    });
+    (0, vitest_1.it)("returns state_not_found with a hint message", async () => {
+        const result = await (0, current_state_js_1.handlePolarisCurrentState)({ artifact_dir: "nonexistent-run" });
+        (0, vitest_1.expect)(result["ok"]).toBe(false);
+        (0, vitest_1.expect)(result["error"]).toBe("state_not_found");
+        (0, vitest_1.expect)(typeof result["hint"]).toBe("string");
+    });
+});

package/dist/mcp/tools/dispatch-result.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handlePolarisDispatchResult = handlePolarisDispatchResult;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const terminalStatuses = new Set(["done", "complete", "completed", "success", "passed"]);
+function parseArgs(args) {
+    const artifactDir = args.artifact_dir ?? "polaris-run";
+    if (typeof artifactDir !== "string" || !/^[\w][\w.-]*$/.test(artifactDir)) {
+        throw new Error("artifact_dir must be a safe artifact directory name");
+    }
+    if (typeof args.child_id !== "string" || args.child_id.trim() === "") {
+        throw new Error("child_id must be a non-empty string");
+    }
+    if (typeof args.status !== "string" || args.status.trim() === "") {
+        throw new Error("status must be a non-empty string");
+    }
+    if (args.commit !== undefined && typeof args.commit !== "string") {
+        throw new Error("commit must be a string when provided");
+    }
+    const normalizedChildId = args.child_id.trim();
+    const normalizedStatus = args.status.trim();
+    return {
+        artifactDir,
+        childId: normalizedChildId,
+        status: normalizedStatus,
+        commit: args.commit,
+        validation: args.validation ?? null,
+    };
+}
+function statePathFor(artifactDir) {
+    return (0, node_path_1.join)(process.cwd(), ".taskchain_artifacts", artifactDir, "current-state.json");
+}
+function telemetryPathFor(artifactDir, runId) {
+    return (0, node_path_1.join)(process.cwd(), ".taskchain_artifacts", artifactDir, "runs", runId, "telemetry.jsonl");
+}
+function writeJsonAtomic(path, value) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(value, null, 2) + "\n", "utf-8");
+    (0, node_fs_1.renameSync)(tmp, path);
+}
+function appendTelemetry(artifactDir, runId, result) {
+    const event = {
+        event: "mcp-dispatch-result",
+        run_id: runId,
+        child_id: result.childId,
+        status: result.status,
+        commit: result.commit ?? null,
+        validation: result.validation,
+        timestamp: new Date().toISOString(),
+    };
+    const telemetryPath = telemetryPathFor(artifactDir, runId);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryPath), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryPath, JSON.stringify(event) + "\n", "utf-8");
+}
+function withoutChild(values, childId) {
+    if (!Array.isArray(values))
+        return [];
+    return values.filter((value) => typeof value === "string" && value !== childId);
+}
+function withCompletedChild(values, childId) {
+    const completed = Array.isArray(values)
+        ? values.filter((value) => typeof value === "string")
+        : [];
+    return completed.includes(childId) ? completed : [...completed, childId];
+}
+function updateChildMeta(state, childId, status) {
+    const meta = state["open_children_meta"];
+    if (typeof meta !== "object" || meta === null || Array.isArray(meta))
+        return undefined;
+    const child = meta[childId];
+    if (typeof child !== "object" || child === null || Array.isArray(child))
+        return meta;
+    return {
+        ...meta,
+        [childId]: {
+            ...child,
+            status,
+        },
+    };
+}
+async function handlePolarisDispatchResult(args) {
+    let parsed;
+    try {
+        parsed = parseArgs(args);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: "invalid_argument",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const statePath = statePathFor(parsed.artifactDir);
+    let state;
+    try {
+        state = JSON.parse((0, node_fs_1.readFileSync)(statePath, "utf-8"));
+    }
+    catch {
+        return {
+            ok: false,
+            error: "state_not_found",
+            message: `State file not found or invalid: .taskchain_artifacts/${parsed.artifactDir}/current-state.json`,
+        };
+    }
+    if (state["active_child"] !== parsed.childId) {
+        return {
+            ok: false,
+            error: "active_child_mismatch",
+            expected: state["active_child"] ?? null,
+            actual: parsed.childId,
+        };
+    }
+    // Validate run_id strictly before any persistence
+    if (typeof state["run_id"] !== "string" || state["run_id"].trim() === "") {
+        return {
+            ok: false,
+            error: "invalid_run_id",
+            message: "run_id must be a non-empty string in state",
+        };
+    }
+    const runId = state["run_id"].trim();
+    const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(runId);
+    const isRunIdFormat = /^[\w.\-:]+$/.test(runId);
+    if (!isUUID && !isRunIdFormat) {
+        return {
+            ok: false,
+            error: "invalid_run_id",
+            message: "run_id must be a valid UUID format or run-id format",
+        };
+    }
+    const recordedAt = new Date().toISOString();
+    const completed = terminalStatuses.has(parsed.status.toLowerCase());
+    const openChildren = completed ? withoutChild(state["open_children"], parsed.childId) : state["open_children"];
+    const childMeta = completed ? updateChildMeta(state, parsed.childId, "Done") : updateChildMeta(state, parsed.childId, parsed.status);
+    const workerResult = {
+        child_id: parsed.childId,
+        status: parsed.status,
+        commit: parsed.commit ?? null,
+        validation: parsed.validation,
+        recorded_at: recordedAt,
+    };
+    const updated = {
+        ...state,
+        active_child: completed ? null : parsed.childId,
+        completed_children: completed
+            ? withCompletedChild(state["completed_children"], parsed.childId)
+            : state["completed_children"],
+        open_children: openChildren,
+        ...(Array.isArray(openChildren) ? { next_open_child: openChildren[0] ?? null } : {}),
+        ...(childMeta ? { open_children_meta: childMeta } : {}),
+        ...(parsed.commit ? { last_commit: parsed.commit } : {}),
+        validation_status: parsed.status,
+        last_worker_result: workerResult,
+        updated_at: recordedAt,
+    };
+    try {
+        writeJsonAtomic(statePath, updated);
+        appendTelemetry(parsed.artifactDir, runId, {
+            childId: parsed.childId,
+            status: parsed.status,
+            commit: parsed.commit,
+            validation: parsed.validation,
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                message: err instanceof Error ? err.message : String(err),
+                name: err instanceof Error ? err.name : "Error",
+                meta: {
+                    statePath,
+                    childId: parsed.childId,
+                },
+            },
+        };
+    }
+    return {
+        ok: true,
+        child_id: parsed.childId,
+        active_child: updated.active_child,
+        recorded: workerResult,
+    };
+}