cool-workflow 0.1.78

package/dist/state-node.js

@@ -0,0 +1,301 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PipelineContractError = exports.PIPELINE_CONTRACT_SCHEMA_VERSION = exports.STATE_NODE_SCHEMA_VERSION = void 0;
+exports.createStateNode = createStateNode;
+exports.transitionStateNode = transitionStateNode;
+exports.validatePipelineContract = validatePipelineContract;
+exports.assertNodeSatisfiesContract = assertNodeSatisfiesContract;
+exports.recordNodeError = recordNodeError;
+exports.linkStateNodes = linkStateNodes;
+exports.appendRunNode = appendRunNode;
+exports.upsertRunContract = upsertRunContract;
+exports.writeRunNode = writeRunNode;
+exports.artifactExists = artifactExists;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const state_1 = require("./state");
+exports.STATE_NODE_SCHEMA_VERSION = 1;
+exports.PIPELINE_CONTRACT_SCHEMA_VERSION = 1;
+class PipelineContractError extends Error {
+    structured;
+    constructor(error) {
+        super(error.message);
+        this.name = "PipelineContractError";
+        this.structured = {
+            ...error,
+            at: error.at || new Date().toISOString()
+        };
+    }
+}
+exports.PipelineContractError = PipelineContractError;
+function createStateNode(input) {
+    const now = new Date().toISOString();
+    return {
+        schemaVersion: exports.STATE_NODE_SCHEMA_VERSION,
+        id: input.id || createNodeId(input.kind),
+        kind: input.kind,
+        status: input.status || "pending",
+        loopStage: input.loopStage,
+        createdAt: now,
+        updatedAt: now,
+        inputs: input.inputs || {},
+        outputs: input.outputs || {},
+        artifacts: input.artifacts || [],
+        evidence: input.evidence || [],
+        errors: input.errors || [],
+        parents: input.parents || [],
+        children: input.children || [],
+        contractId: input.contractId,
+        metadata: input.metadata
+    };
+}
+function transitionStateNode(node, input) {
+    if (!isLegalTransition(node.status, input.status)) {
+        throw contractError("illegal-transition", `State node ${node.id} cannot transition from ${node.status} to ${input.status}`, {
+            nodeId: node.id,
+            details: {
+                from: node.status,
+                to: input.status
+            }
+        });
+    }
+    if (input.status === "committed" && node.status !== "verified") {
+        throw contractError("commit-without-verifier", `State node ${node.id} cannot be committed before it is verified`, {
+            nodeId: node.id,
+            details: {
+                from: node.status,
+                to: input.status
+            }
+        });
+    }
+    return {
+        ...node,
+        status: input.status,
+        loopStage: input.loopStage || node.loopStage,
+        updatedAt: new Date().toISOString(),
+        outputs: input.outputs ? { ...node.outputs, ...input.outputs } : node.outputs,
+        artifacts: input.artifacts ? mergeById(node.artifacts, input.artifacts) : node.artifacts,
+        evidence: input.evidence ? mergeById(node.evidence, input.evidence) : node.evidence,
+        metadata: input.metadata ? { ...(node.metadata || {}), ...input.metadata } : node.metadata
+    };
+}
+function validatePipelineContract(contract) {
+    if (contract.schemaVersion !== exports.PIPELINE_CONTRACT_SCHEMA_VERSION) {
+        throw contractError("invalid-contract-schema", `Pipeline contract ${contract.id || "(missing id)"} has unsupported schemaVersion`, {
+            details: { schemaVersion: contract.schemaVersion }
+        });
+    }
+    if (!contract.id)
+        throw contractError("invalid-contract-id", "Pipeline contract id is required");
+    if (!contract.title)
+        throw contractError("invalid-contract-title", `Pipeline contract ${contract.id} title is required`);
+    if (!Array.isArray(contract.stages) || !contract.stages.length) {
+        throw contractError("invalid-contract-stages", `Pipeline contract ${contract.id} must include at least one stage`);
+    }
+    const seen = new Set();
+    for (const stage of contract.stages) {
+        validateStage(contract, stage, seen);
+    }
+    if (!contract.compatibility) {
+        throw contractError("invalid-contract-compatibility", `Pipeline contract ${contract.id} compatibility is required`);
+    }
+    if (contract.compatibility.minSchemaVersion > exports.STATE_NODE_SCHEMA_VERSION) {
+        throw contractError("incompatible-contract", `Pipeline contract ${contract.id} requires newer StateNode schema`, {
+            details: contract.compatibility
+        });
+    }
+}
+function assertNodeSatisfiesContract(node, contract, stageId) {
+    validatePipelineContract(contract);
+    const stage = contract.stages.find((candidate) => candidate.id === stageId);
+    if (!stage) {
+        throw contractError("unknown-contract-stage", `Pipeline contract ${contract.id} has no stage ${stageId}`, {
+            nodeId: node.id
+        });
+    }
+    if (!stage.acceptedInputKinds.includes(node.kind)) {
+        throw contractError("unexpected-node-kind", `Stage ${stage.id} does not accept node kind ${node.kind}`, {
+            nodeId: node.id,
+            details: { expected: stage.acceptedInputKinds, actual: node.kind }
+        });
+    }
+    if (!stage.acceptedInputStatuses.includes(node.status)) {
+        throw contractError("unexpected-node-status", `Stage ${stage.id} does not accept node status ${node.status}`, {
+            nodeId: node.id,
+            details: { expected: stage.acceptedInputStatuses, actual: node.status }
+        });
+    }
+    assertRequiredArtifacts(node, stage);
+    assertRequiredEvidence(node, stage, contract);
+    assertVerifierGate(node, stage, contract);
+}
+function recordNodeError(node, error) {
+    return {
+        ...node,
+        status: "failed",
+        updatedAt: new Date().toISOString(),
+        errors: [
+            ...node.errors,
+            {
+                ...error,
+                at: error.at || new Date().toISOString(),
+                nodeId: error.nodeId || node.id
+            }
+        ]
+    };
+}
+function linkStateNodes(parent, child) {
+    return [
+        {
+            ...parent,
+            updatedAt: new Date().toISOString(),
+            children: unique([...parent.children, child.id])
+        },
+        {
+            ...child,
+            updatedAt: new Date().toISOString(),
+            parents: unique([...child.parents, parent.id])
+        }
+    ];
+}
+function appendRunNode(run, node) {
+    const nodes = run.nodes || [];
+    const index = nodes.findIndex((candidate) => candidate.id === node.id);
+    const nextNodes = index >= 0 ? nodes.map((candidate) => (candidate.id === node.id ? node : candidate)) : [...nodes, node];
+    run.nodes = nextNodes;
+    writeRunNode(run, node);
+    return node;
+}
+function upsertRunContract(run, contract) {
+    validatePipelineContract(contract);
+    const contracts = run.contracts || [];
+    const index = contracts.findIndex((candidate) => candidate.id === contract.id);
+    run.contracts =
+        index >= 0 ? contracts.map((candidate) => (candidate.id === contract.id ? contract : candidate)) : [...contracts, contract];
+    return contract;
+}
+function writeRunNode(run, node) {
+    const dir = run.paths.stateNodesDir || node_path_1.default.join(run.paths.runDir, "nodes");
+    const file = node_path_1.default.join(dir, `${(0, state_1.safeFileName)(node.id)}.json`);
+    (0, state_1.writeJson)(file, node);
+    return file;
+}
+function artifactExists(artifact) {
+    return Boolean(artifact.path && node_fs_1.default.existsSync(artifact.path));
+}
+function validateStage(contract, stage, seen) {
+    if (!stage.id)
+        throw contractError("invalid-contract-stage-id", `Pipeline contract ${contract.id} has a stage without id`);
+    if (seen.has(stage.id))
+        throw contractError("duplicate-contract-stage", `Pipeline contract ${contract.id} repeats stage ${stage.id}`);
+    seen.add(stage.id);
+    if (!stage.name)
+        throw contractError("invalid-contract-stage-name", `Stage ${stage.id} name is required`);
+    if (!Array.isArray(stage.acceptedInputKinds) || !stage.acceptedInputKinds.length) {
+        throw contractError("invalid-contract-stage-kinds", `Stage ${stage.id} must accept at least one input kind`);
+    }
+    if (!Array.isArray(stage.acceptedInputStatuses) || !stage.acceptedInputStatuses.length) {
+        throw contractError("invalid-contract-stage-statuses", `Stage ${stage.id} must accept at least one input status`);
+    }
+    if (!stage.producedOutputKind) {
+        throw contractError("invalid-contract-stage-output", `Stage ${stage.id} producedOutputKind is required`);
+    }
+}
+function assertRequiredArtifacts(node, stage) {
+    for (const required of stage.requiredArtifacts || []) {
+        const artifact = node.artifacts.find((candidate) => candidate.id === required || candidate.kind === required);
+        if (!artifact) {
+            throw contractError("missing-required-artifact", `Node ${node.id} is missing required artifact ${required}`, {
+                nodeId: node.id,
+                details: { requiredArtifact: required }
+            });
+        }
+        if (!artifactExists(artifact)) {
+            throw contractError("missing-artifact-path", `Node ${node.id} artifact ${artifact.id} path does not exist`, {
+                nodeId: node.id,
+                path: artifact.path,
+                details: { artifactId: artifact.id }
+            });
+        }
+    }
+}
+function assertRequiredEvidence(node, stage, contract) {
+    const requiredEvidence = stage.requiredEvidence || [];
+    const contractRequiresEvidence = Boolean(contract.evidencePolicy?.requireEvidence);
+    if ((requiredEvidence.length || contractRequiresEvidence) && !node.evidence.length) {
+        throw contractError("missing-required-evidence", `Node ${node.id} is missing required evidence`, {
+            nodeId: node.id,
+            details: { requiredEvidence }
+        });
+    }
+    for (const required of requiredEvidence) {
+        const evidence = node.evidence.find((candidate) => candidate.id === required || candidate.source === required);
+        if (!evidence) {
+            throw contractError("missing-required-evidence", `Node ${node.id} is missing required evidence ${required}`, {
+                nodeId: node.id,
+                details: { requiredEvidence: required }
+            });
+        }
+    }
+}
+function assertVerifierGate(node, stage, contract) {
+    const gate = stage.verifierGate;
+    const commitRequiresGate = contract.commitPolicy?.requiresVerifierGate && stage.producedOutputKind === "commit";
+    if (!gate?.required && !commitRequiresGate)
+        return;
+    const acceptedStatuses = gate?.acceptedStatuses || contract.commitPolicy?.acceptedVerifierStatuses || ["verified"];
+    if (!acceptedStatuses.includes(node.status)) {
+        throw contractError("verifier-gate-blocked", `Stage ${stage.id} requires verifier status ${acceptedStatuses.join(", ")}`, {
+            nodeId: node.id,
+            details: { actual: node.status, accepted: acceptedStatuses }
+        });
+    }
+    if ((gate?.requiredEvidence || contract.evidencePolicy?.requireEvidence) && !node.evidence.length) {
+        throw contractError("verifier-gate-missing-evidence", `Stage ${stage.id} requires evidence before commit`, {
+            nodeId: node.id
+        });
+    }
+}
+function isLegalTransition(from, to) {
+    if (from === to)
+        return true;
+    const allowed = {
+        pending: ["running", "blocked", "failed", "completed", "verified", "rejected"],
+        running: ["completed", "failed", "blocked"],
+        completed: ["verified", "rejected", "failed"],
+        failed: ["pending", "blocked"],
+        blocked: ["pending", "failed"],
+        verified: ["committed", "rejected"],
+        rejected: ["pending", "failed"],
+        committed: []
+    };
+    return allowed[from].includes(to);
+}
+function contractError(code, message, options = {}) {
+    return new PipelineContractError({
+        code,
+        message,
+        ...options
+    });
+}
+function createNodeId(kind) {
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
+    return `${kind}-${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function mergeById(existing, next) {
+    const values = [...existing];
+    for (const item of next) {
+        const index = values.findIndex((candidate) => candidate.id === item.id);
+        if (index >= 0)
+            values[index] = item;
+        else
+            values.push(item);
+    }
+    return values;
+}
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/state.js

@@ -0,0 +1,308 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_RUN_STATE_SCHEMA_VERSION = void 0;
+exports.createRunPaths = createRunPaths;
+exports.ensureRunDirs = ensureRunDirs;
+exports.loadRunFromCwd = loadRunFromCwd;
+exports.loadRunStateFile = loadRunStateFile;
+exports.checkRunStateFile = checkRunStateFile;
+exports.migrateRunStateFile = migrateRunStateFile;
+exports.saveCheckpoint = saveCheckpoint;
+exports.compactCheckpoint = compactCheckpoint;
+exports.readJson = readJson;
+exports.writeJson = writeJson;
+exports.durableAppendFileSync = durableAppendFileSync;
+exports.realResolve = realResolve;
+exports.isContainedPath = isContainedPath;
+exports.withFileLock = withFileLock;
+exports.safeFileName = safeFileName;
+exports.hashArtifactFile = hashArtifactFile;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const state_migrations_1 = require("./state-migrations");
+const version_1 = require("./version");
+Object.defineProperty(exports, "CURRENT_RUN_STATE_SCHEMA_VERSION", { enumerable: true, get: function () { return version_1.CURRENT_RUN_STATE_SCHEMA_VERSION; } });
+const execution_backend_1 = require("./execution-backend");
+function createRunPaths(runDir) {
+    return {
+        runDir,
+        state: node_path_1.default.join(runDir, "state.json"),
+        report: node_path_1.default.join(runDir, "report.md"),
+        tasksDir: node_path_1.default.join(runDir, "tasks"),
+        resultsDir: node_path_1.default.join(runDir, "results"),
+        dispatchesDir: node_path_1.default.join(runDir, "dispatches"),
+        artifactsDir: node_path_1.default.join(runDir, "artifacts"),
+        commitsDir: node_path_1.default.join(runDir, "commits"),
+        stateNodesDir: node_path_1.default.join(runDir, "nodes"),
+        feedbackDir: node_path_1.default.join(runDir, "feedback"),
+        auditDir: node_path_1.default.join(runDir, "audit"),
+        workersDir: node_path_1.default.join(runDir, "workers"),
+        candidatesDir: node_path_1.default.join(runDir, "candidates"),
+        multiAgentDir: node_path_1.default.join(runDir, "multi-agent"),
+        blackboardDir: node_path_1.default.join(runDir, "blackboard"),
+        topologiesDir: node_path_1.default.join(runDir, "topologies")
+    };
+}
+function ensureRunDirs(paths) {
+    for (const dir of [
+        paths.runDir,
+        paths.tasksDir,
+        paths.resultsDir,
+        paths.dispatchesDir,
+        paths.artifactsDir,
+        paths.commitsDir,
+        paths.stateNodesDir,
+        paths.feedbackDir,
+        paths.auditDir || node_path_1.default.join(paths.runDir, "audit"),
+        paths.workersDir || node_path_1.default.join(paths.runDir, "workers"),
+        paths.candidatesDir || node_path_1.default.join(paths.runDir, "candidates"),
+        paths.multiAgentDir || node_path_1.default.join(paths.runDir, "multi-agent"),
+        paths.blackboardDir || node_path_1.default.join(paths.runDir, "blackboard"),
+        paths.topologiesDir || node_path_1.default.join(paths.runDir, "topologies")
+    ]) {
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+}
+function loadRunFromCwd(runId, cwd = process.cwd()) {
+    if (!runId)
+        throw new Error("Missing run id");
+    const statePath = node_path_1.default.join(cwd, ".cw", "runs", runId, "state.json");
+    const result = loadRunStateFile(statePath, { dryRun: true });
+    if (result.report.status === "unsupported") {
+        throw new Error(`Unsupported CW run state: ${result.report.errors.join("; ")}`);
+    }
+    return result.run;
+}
+function loadRunStateFile(statePath, options = {}) {
+    const result = (0, state_migrations_1.migrateRunState)(readJson(statePath), {
+        statePath,
+        dryRun: options.dryRun === undefined ? true : options.dryRun
+    });
+    if (result.report.status === "unsupported")
+        return result;
+    return result;
+}
+function checkRunStateFile(statePath) {
+    return loadRunStateFile(statePath, { dryRun: true });
+}
+function migrateRunStateFile(statePath, options = {}) {
+    const result = loadRunStateFile(statePath, { dryRun: !options.write });
+    if (result.report.status !== "unsupported" && options.write && result.report.writeRequired) {
+        writeJson(statePath, result.run);
+    }
+    return result;
+}
+function saveCheckpoint(run) {
+    run.updatedAt = new Date().toISOString();
+    // state.json is the single source of truth — write it DURABLY (v0.1.40).
+    writeJson(run.paths.state, run, { durable: true });
+}
+/** Compact a run checkpoint by stripping empty optional arrays and null values
+ *  that don't carry semantic meaning (v0.1.60). The normalization layer
+ *  (normalizeRunState) backfills these on load, so stripping them saves disk
+ *  without losing information. Returns the number of keys stripped. */
+function compactCheckpoint(run) {
+    const optionalArrays = [
+        "nodes", "contracts", "feedback", "workers", "sandboxProfiles",
+        "candidates", "candidateSelections"
+    ];
+    let stripped = 0;
+    const state = run;
+    for (const key of optionalArrays) {
+        if (Array.isArray(state[key]) && state[key].length === 0) {
+            delete state[key];
+            stripped++;
+        }
+    }
+    if (stripped > 0)
+        saveCheckpoint(run);
+    return stripped;
+}
+function readJson(file) {
+    if (!node_fs_1.default.existsSync(file))
+        throw new Error(`File not found: ${file}`);
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON in ${file}: ${message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Atomic, optionally-durable JSON write (v0.1.40, closes the prior P1).
+//
+// ORDER IS THE SAFETY PROPERTY: write to a unique temp file, then rename over the
+// target. `rename(2)` is atomic on POSIX, so a crash/`ENOSPC` mid-write can never
+// leave a truncated `state.json` that throws `Invalid JSON` on reload — a reader
+// always sees EITHER the old bytes OR the new bytes, never a torn file. With
+// `{ durable: true }` we additionally fsync the file (and best-effort the dir)
+// before/after the rename so the bytes survive power loss — used for AUTHORITATIVE
+// state (state.json, registry overlays, the scheduler store, reclaimed.json). The
+// fsync is skipped for high-frequency derived/rebuildable writes so the atomic
+// rename (the actual torn-write fix) stays cheap everywhere.
+// ---------------------------------------------------------------------------
+let atomicWriteCounter = 0;
+function writeJson(file, value, options = {}) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp.${process.pid}.${atomicWriteCounter++}`;
+    const fd = node_fs_1.default.openSync(tmp, "w");
+    try {
+        node_fs_1.default.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        if (options.durable)
+            node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+    try {
+        node_fs_1.default.renameSync(tmp, file);
+    }
+    catch (error) {
+        try {
+            node_fs_1.default.rmSync(tmp, { force: true });
+        }
+        catch {
+            /* best-effort temp cleanup */
+        }
+        throw error;
+    }
+    if (options.durable) {
+        try {
+            const dirFd = node_fs_1.default.openSync(node_path_1.default.dirname(file), "r");
+            try {
+                node_fs_1.default.fsyncSync(dirFd);
+            }
+            finally {
+                node_fs_1.default.closeSync(dirFd);
+            }
+        }
+        catch {
+            /* directory fsync is best-effort (not supported on every platform) */
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Durable append (v0.1.40 self-audit P1) — append a line and fsync it before
+// returning. The trust-audit event log is the ONE artifact whose loss breaks
+// audit-completeness/non-repudiation, so unlike high-frequency derived writes it
+// must survive power loss. `appendFileSync` alone does NOT fsync, so a crash
+// after it returns could drop the most recent event while durable state.json
+// advanced past it. We open O_APPEND, write, fsync the fd, then close.
+// ---------------------------------------------------------------------------
+function durableAppendFileSync(file, data) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const fd = node_fs_1.default.openSync(file, "a");
+    try {
+        node_fs_1.default.writeFileSync(fd, data, "utf8");
+        node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+// ---------------------------------------------------------------------------
+// Symlink-hardened path containment (v0.1.40 self-audit P1) — `path.resolve()`
+// only normalizes `.`/`..` textually; it does NOT follow symlinks, so a planted
+// symlink whose textual path sits "inside" an allowed root but whose real target
+// escapes it would pass a `startsWith` containment check. `realResolve` resolves
+// the deepest EXISTING ancestor with `realpathSync` (which follows symlinks) and
+// re-joins the not-yet-created remainder, so a not-yet-created file is still
+// pinned to its real parent. `isContainedPath` realpaths BOTH sides so the
+// comparison stays consistent on platforms where the temp root itself is a
+// symlink (e.g. macOS /tmp -> /private/tmp).
+// ---------------------------------------------------------------------------
+function realResolve(target) {
+    let current = node_path_1.default.resolve(target);
+    const tail = [];
+    // Walk up to the deepest existing ancestor, realpath it, then re-append the tail.
+    for (;;) {
+        try {
+            const real = node_fs_1.default.realpathSync.native ? node_fs_1.default.realpathSync.native(current) : node_fs_1.default.realpathSync(current);
+            return tail.length ? node_path_1.default.join(real, ...tail.reverse()) : real;
+        }
+        catch {
+            const parent = node_path_1.default.dirname(current);
+            if (parent === current)
+                return node_path_1.default.resolve(target); // reached root; nothing existed
+            tail.push(node_path_1.default.basename(current));
+            current = parent;
+        }
+    }
+}
+function isContainedPath(candidate, allowed) {
+    const realCandidate = realResolve(candidate);
+    const realAllowed = realResolve(allowed);
+    return realCandidate === realAllowed || realCandidate.startsWith(realAllowed + node_path_1.default.sep);
+}
+// ---------------------------------------------------------------------------
+// Portable advisory file lock (v0.1.40) — serialize cross-process read-modify-
+// write on shared stores (home queue, scheduler store, archive overlay, the
+// per-run reclamation chain) so a concurrent writer can never lose a record.
+// O_EXCL (`wx`) is portable (no native flock); a stale holder is stolen so a
+// crashed process can never wedge the store forever.
+// ---------------------------------------------------------------------------
+const FILE_LOCK_STALE_MS = 30_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Run `fn` while holding an advisory lock for `targetPath`; always released. */
+function withFileLock(targetPath, fn) {
+    const lock = `${targetPath}.lock`;
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(lock), { recursive: true });
+    let acquired = false;
+    for (let attempt = 0; attempt < 240 && !acquired; attempt++) {
+        try {
+            const fd = node_fs_1.default.openSync(lock, "wx");
+            node_fs_1.default.writeFileSync(fd, `${process.pid}@${new Date().toISOString()}\n`, "utf8");
+            node_fs_1.default.closeSync(fd);
+            acquired = true;
+        }
+        catch (error) {
+            if (!(error && typeof error === "object" && error.code === "EEXIST"))
+                throw error;
+            try {
+                if (Date.now() - node_fs_1.default.statSync(lock).mtimeMs > FILE_LOCK_STALE_MS) {
+                    node_fs_1.default.rmSync(lock, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue; // lock vanished between open and stat — retry immediately
+            }
+            sleepSync(25);
+        }
+    }
+    if (!acquired)
+        throw new Error(`could not acquire file lock for ${targetPath}`);
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            node_fs_1.default.rmSync(lock, { force: true });
+        }
+        catch {
+            /* releasing a missing lock is fine */
+        }
+    }
+}
+function safeFileName(value) {
+    return String(value).replace(/[^a-zA-Z0-9_.:-]+/g, "_");
+}
+/** Compute and set SHA256 + sizeBytes on a StateArtifact from its file path
+ *  (v0.1.73). Fails silently when the file doesn't exist — does not throw. */
+function hashArtifactFile(artifact) {
+    try {
+        const content = node_fs_1.default.readFileSync(artifact.path, "utf8");
+        artifact.sha256 = (0, execution_backend_1.sha256)(content);
+        artifact.sizeBytes = Buffer.byteLength(content, "utf8");
+    }
+    catch {
+        /* file missing — silently skip */
+    }
+    return artifact;
+}