ushman-characterize 0.4.0

package/dist/tracer-runtime.js

@@ -0,0 +1,291 @@
+import { DEFAULT_PER_FUNCTION_SHAPE_CAP, DEFAULT_TRACE_DEPTH_LIMIT, TRACE_RUNTIME_VERSION } from "./constants.js";
+import { toTraceDeduplicationPayload } from "./dedupe-contract.js";
+import { buildTraceRuntimeSupportSource } from "./trace-serializer.js";
+const buildSideEffectPatchesSource = (captureSideEffects) => `
+  const installDomMutationObserver = () => {
+    if (!globalThis.MutationObserver) return;
+    const start = () => {
+      if (!document.documentElement || globalThis.__USHMAN_TRACER_DOM_OBSERVER__) return;
+      const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          recordSideEffect({
+            attributeName: mutation.attributeName ?? null,
+            target: mutation.target?.nodeName ?? null,
+            type: mutation.type,
+          });
+        }
+      });
+      observer.observe(document.documentElement, { attributes: true, childList: true, subtree: true });
+      globalThis.__USHMAN_TRACER_DOM_OBSERVER__ = observer;
+    };
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', start, { once: true });
+      return;
+    }
+    start();
+  };
+
+  const wrapAudioContext = (key) => {
+    const Original = globalThis[key];
+    if (!Original || Original.__ushmanWrapped) return;
+    function WrappedAudioContext(...args) {
+      recordSideEffect({ type: key + '.construct' });
+      return Reflect.construct(Original, args, new.target || WrappedAudioContext);
+    }
+    WrappedAudioContext.prototype = Original.prototype;
+    Object.setPrototypeOf(WrappedAudioContext, Original);
+    WrappedAudioContext.__ushmanWrapped = true;
+    globalThis[key] = WrappedAudioContext;
+  };
+
+  const patchSceneGraphIfAvailable = () => {
+    const object3DPrototype = globalThis.THREE?.Object3D?.prototype;
+    if (!object3DPrototype || object3DPrototype.__ushmanWrapped) return;
+    const originalAdd = object3DPrototype.add;
+    const originalRemove = object3DPrototype.remove;
+    object3DPrototype.add = function (...children) {
+      recordSideEffect({
+        childNames: children.map((child) => child?.name ?? null),
+        childTypes: children.map((child) => child?.type ?? null),
+        count: children.length,
+        type: 'THREE.Object3D.add',
+      });
+      return originalAdd.apply(this, children);
+    };
+    object3DPrototype.remove = function (...children) {
+      recordSideEffect({
+        childNames: children.map((child) => child?.name ?? null),
+        childTypes: children.map((child) => child?.type ?? null),
+        count: children.length,
+        type: 'THREE.Object3D.remove',
+      });
+      return originalRemove.apply(this, children);
+    };
+    object3DPrototype.__ushmanWrapped = true;
+  };
+
+  const maybePatchSideEffects = () => {
+    patchPromisePrototype();
+    patchAsyncCallbackRegistrar('queueMicrotask');
+    patchAsyncCallbackRegistrar('requestAnimationFrame');
+    patchAsyncCallbackRegistrar('setInterval');
+    patchAsyncCallbackRegistrar('setTimeout');
+    if (!${captureSideEffects ? 'true' : 'false'}) return;
+    if (globalThis.fetch && !globalThis.fetch.__ushmanWrapped) {
+      const originalFetch = globalThis.fetch.bind(globalThis);
+      const wrappedFetch = (...args) => {
+        recordSideEffect({ type: 'fetch', url: String(args[0]), method: args[1]?.method ?? 'GET' });
+        return originalFetch(...args);
+      };
+      wrappedFetch.__ushmanWrapped = true;
+      globalThis.fetch = wrappedFetch;
+    }
+    if (globalThis.localStorage && !globalThis.localStorage.__ushmanWrapped) {
+      const setItem = globalThis.localStorage.setItem.bind(globalThis.localStorage);
+      const removeItem = globalThis.localStorage.removeItem.bind(globalThis.localStorage);
+      globalThis.localStorage.setItem = (key, value) => {
+        recordSideEffect({ type: 'localStorage.setItem', key, value });
+        return setItem(key, value);
+      };
+      globalThis.localStorage.removeItem = (key) => {
+        recordSideEffect({ type: 'localStorage.removeItem', key });
+        return removeItem(key);
+      };
+      globalThis.localStorage.__ushmanWrapped = true;
+    }
+    wrapAudioContext('AudioContext');
+    wrapAudioContext('webkitAudioContext');
+    installDomMutationObserver();
+    patchSceneGraphIfAvailable();
+  };
+`;
+const DEDUPE_PAYLOAD_SOURCE = `const toTraceDeduplicationPayload = ${toTraceDeduplicationPayload.toString()};`;
+export const buildTracerRuntimeSource = ({ captureSideEffects, perFunctionShapeCap = DEFAULT_PER_FUNCTION_SHAPE_CAP, }) => `(() => {
+  if (globalThis.__USHMAN_TRACER__ && globalThis.__USHMAN_TRACER__.version === ${TRACE_RUNTIME_VERSION}) {
+    return;
+  }
+
+  ${buildTraceRuntimeSupportSource()}
+  ${DEDUPE_PAYLOAD_SOURCE}
+
+  const recordsByKey = new Map();
+  const dirtyKeys = new Set();
+  const active = new Map();
+  const activeStack = [];
+  const invocationCallIds = [];
+  const uniqueCountsByFunction = new Map();
+  const stats = {
+    droppedUniqueCalls: 0,
+    rawCalls: 0,
+    uniqueCalls: 0,
+  };
+  let disabled = false;
+  let nextId = 1;
+
+  // Sync chunks must unwind in stack order. Duplicate leave calls are tolerated
+  // as a no-op so the await helper and outer wrapper can share the same call id.
+  const leaveSyncFrame = (id) => {
+    if (activeStack[activeStack.length - 1] === id) {
+      activeStack.pop();
+    }
+  };
+
+  const currentCallId = () => activeStack[activeStack.length - 1] ?? null;
+  const peekInvocationCallId = () => invocationCallIds[invocationCallIds.length - 1] ?? null;
+
+  const pushInvocationCallId = (id) => {
+    invocationCallIds.push(id);
+  };
+
+  const popInvocationCallId = (id) => {
+    const index = invocationCallIds.lastIndexOf(id);
+    if (index >= 0) {
+      invocationCallIds.splice(index, 1);
+    }
+  };
+
+  const currentCall = () => {
+    const id = currentCallId();
+    return id ? active.get(id) ?? null : null;
+  };
+
+  const enterAsyncFrame = (id) => {
+    if (!active.has(id) || activeStack[activeStack.length - 1] === id) {
+      return;
+    }
+    activeStack.push(id);
+  };
+
+  const runWithCallContext = (id, callback, thisArg, args) => {
+    if (!id || !active.has(id) || typeof callback !== 'function') {
+      return callback?.apply?.(thisArg, args);
+    }
+    activeStack.push(id);
+    try {
+      return callback.apply(thisArg, args);
+    } finally {
+      leaveSyncFrame(id);
+    }
+  };
+
+  const wrapAsyncCallback = (callback, callId) => {
+    if (typeof callback !== 'function' || !callId) {
+      return callback;
+    }
+    return function (...args) {
+      return runWithCallContext(callId, callback, this, args);
+    };
+  };
+
+  const patchPromisePrototype = () => {
+    const promisePrototype = globalThis.Promise?.prototype;
+    if (!promisePrototype || promisePrototype.__ushmanWrapped) {
+      return;
+    }
+    const originalThen = promisePrototype.then;
+    promisePrototype.then = function (onFulfilled, onRejected) {
+      const callId = currentCallId();
+      return originalThen.call(this, wrapAsyncCallback(onFulfilled, callId), wrapAsyncCallback(onRejected, callId));
+    };
+    promisePrototype.__ushmanWrapped = true;
+  };
+
+  const patchAsyncCallbackRegistrar = (key) => {
+    const original = globalThis[key];
+    if (typeof original !== 'function' || original.__ushmanWrapped) {
+      return;
+    }
+    const wrapped = (callback, ...args) => {
+      const callId = currentCallId();
+      return original.call(globalThis, wrapAsyncCallback(callback, callId), ...args);
+    };
+    wrapped.__ushmanWrapped = true;
+    globalThis[key] = wrapped;
+  };
+
+  const recordSideEffect = (effect) => {
+    const call = currentCall();
+    if (!call || disabled) return;
+    call.sideEffects.push(canonicalizeTraceValue(effect, { depthLimit: ${DEFAULT_TRACE_DEPTH_LIMIT} }));
+  };
+
+  ${buildSideEffectPatchesSource(captureSideEffects)}
+  maybePatchSideEffects();
+
+  const createDedupKey = (record) =>
+    buildStableHash(
+      JSON.stringify(toTraceDeduplicationPayload(record)),
+    );
+
+  globalThis.__USHMAN_TRACER__ = {
+    version: ${TRACE_RUNTIME_VERSION},
+    disable() {
+      disabled = true;
+    },
+    drain() {
+      const records = [...dirtyKeys].map((key) => recordsByKey.get(key)).filter(Boolean);
+      dirtyKeys.clear();
+      return {
+        records,
+        stats: { ...stats },
+      };
+    },
+    enter(meta, args, thisArg) {
+      maybePatchSideEffects();
+      const id = nextId++;
+      active.set(id, {
+        args: canonicalizeTraceValue(args, { depthLimit: ${DEFAULT_TRACE_DEPTH_LIMIT} }),
+        meta,
+        sideEffects: [],
+        thisArg: canonicalizeTraceValue(thisArg, { depthLimit: ${DEFAULT_TRACE_DEPTH_LIMIT} }),
+      });
+      activeStack.push(id);
+      return id;
+    },
+    enterAsyncFrame,
+    leaveSyncFrame,
+    peekInvocationCallId,
+    popInvocationCallId,
+    pushInvocationCallId,
+    exit(id, result, threw) {
+      const entry = active.get(id);
+      leaveSyncFrame(id);
+      if (!entry) return result;
+      active.delete(id);
+      stats.rawCalls += 1;
+      if (disabled) {
+        return result;
+      }
+      const record = {
+        args: entry.args,
+        bindingName: entry.meta.bindingName,
+        className: entry.meta.className,
+        count: 1,
+        expected: canonicalizeTraceValue(result, { depthLimit: ${DEFAULT_TRACE_DEPTH_LIMIT} }),
+        functionName: entry.meta.functionName,
+        memberKind: entry.meta.memberKind,
+        methodName: entry.meta.methodName,
+        sideEffects: entry.sideEffects,
+        thisArg: entry.thisArg,
+        threw: threw === undefined ? null : canonicalizeTraceValue(threw, { depthLimit: ${DEFAULT_TRACE_DEPTH_LIMIT} }),
+      };
+      const dedupeKey = createDedupKey(record);
+      const existing = recordsByKey.get(dedupeKey);
+      if (existing) {
+        existing.count += 1;
+        dirtyKeys.add(dedupeKey);
+        return result;
+      }
+      const uniqueCount = uniqueCountsByFunction.get(entry.meta.functionName) ?? 0;
+      if (uniqueCount >= ${perFunctionShapeCap}) {
+        stats.droppedUniqueCalls += 1;
+        return result;
+      }
+      uniqueCountsByFunction.set(entry.meta.functionName, uniqueCount + 1);
+      stats.uniqueCalls += 1;
+      recordsByKey.set(dedupeKey, record);
+      dirtyKeys.add(dedupeKey);
+      return result;
+    },
+  };
+})();`;

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+import type { BrowserPage } from './puppeteer-harness.ts';
+export type CaptureServerHandle = {
+    readonly close: () => Promise<void>;
+    readonly url: string;
+};
+export type CaptureServerHost = {
+    readonly serve: (rootDir: string, port: number) => Promise<CaptureServerHandle>;
+};
+export type SceneInspectorDriver = {
+    readonly captureSceneTree: (page: BrowserPage) => Promise<unknown>;
+    readonly installPreboot?: (page: BrowserPage) => Promise<void>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnF,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE,CAAC"}

package/dist/workspace-paths.d.ts

@@ -0,0 +1,64 @@
+import * as v from 'valibot';
+export type WorkspaceLayout = 'unknown' | 'v3' | 'v4';
+export type V4WorkspacePaths = {
+    readonly agentSkill: string;
+    readonly asl: string;
+    readonly aslDonor: string;
+    readonly candidateIndex: string;
+    readonly candidatePackageJson: string;
+    readonly candidatePublic: string;
+    readonly candidateSrc: string;
+    readonly candidateViteConfig: string;
+    readonly capture: string;
+    readonly characterize: string;
+    readonly lab: string;
+    readonly labManifest: string;
+    readonly ledger: string;
+    readonly parity: string;
+    readonly pipelineLockFile: string;
+    readonly stripDecisions: string;
+};
+export type V3WorkspaceMarkers = {
+    readonly handoffFile: string;
+    readonly stages: string;
+    readonly ushmanState: string;
+    readonly workspaceIdFile: string;
+};
+export type WorkspacePaths = {
+    readonly layout: WorkspaceLayout;
+    readonly pipelineLockFile: string;
+    readonly root: string;
+    readonly screenshotsDir: string;
+    readonly screenshotsIndexFile: string;
+    readonly stateDagFile: string;
+    readonly v3: V3WorkspaceMarkers;
+    readonly v4: V4WorkspacePaths;
+};
+export declare class WorkspaceLayoutError extends Error {
+    readonly exitCode: number;
+    readonly layout: WorkspaceLayout;
+    readonly workspaceRoot: string;
+    constructor({ exitCode, layout, message, workspaceRoot, }: {
+        readonly exitCode: number;
+        readonly layout: WorkspaceLayout;
+        readonly message: string;
+        readonly workspaceRoot: string;
+    });
+}
+export declare const resolveWorkspacePaths: (root: string) => WorkspacePaths;
+export declare const pathExists: (filePath: string) => Promise<boolean>;
+export declare const detectWorkspaceLayout: (root: string) => Promise<WorkspaceLayout>;
+export declare const buildV3MigrationMessage: (workspaceRoot: string) => string;
+export declare const assertV4Workspace: (root: string) => Promise<WorkspacePaths>;
+export declare const atomicWriteJson: (filePath: string, payload: unknown) => Promise<void>;
+export declare const atomicWriteText: (filePath: string, text: string) => Promise<void>;
+export declare const readVersionedDocument: <TSchema extends v.GenericSchema>(filePath: string, schema: TSchema) => Promise<v.InferOutput<TSchema> | null>;
+export declare const resolveDeterminismSeed: (workspaceRoot: string) => Promise<string>;
+export declare const resolveStateDagFile: (workspaceRoot: string) => Promise<string>;
+export declare const withPipelineLock: <T>({ command, disabled, workspaceRoot, work, }: {
+    readonly command: string;
+    readonly disabled?: boolean;
+    readonly workspaceRoot: string;
+    readonly work: () => Promise<T>;
+}) => Promise<T>;
+//# sourceMappingURL=workspace-paths.d.ts.map

package/dist/workspace-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-paths.d.ts","sourceRoot":"","sources":["../src/workspace-paths.ts"],"names":[],"mappings":"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"}

package/dist/workspace-paths.js

@@ -0,0 +1,288 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import * as v from 'valibot';
+import { V3WorkspaceIdDocumentSchema } from "./schema-types.js";
+import { nowIso } from "./time.js";
+const LAB_DIR = '.lab';
+const USHMAN_DIR = '.ushman';
+const V4_SCHEMA_VERSION = 'ushman-lab/v4.0';
+const V4_MIGRATION_EXIT_CODE = 3;
+export class WorkspaceLayoutError extends Error {
+    exitCode;
+    layout;
+    workspaceRoot;
+    constructor({ exitCode, layout, message, workspaceRoot, }) {
+        super(message);
+        this.exitCode = exitCode;
+        this.layout = layout;
+        this.workspaceRoot = workspaceRoot;
+    }
+}
+const buildV4Paths = (root) => ({
+    agentSkill: path.join(root, LAB_DIR, 'AGENT_SKILL.md'),
+    asl: path.join(root, 'asl'),
+    aslDonor: path.join(root, 'asl', 'donor'),
+    candidateIndex: path.join(root, 'index.html'),
+    candidatePackageJson: path.join(root, 'package.json'),
+    candidatePublic: path.join(root, 'public'),
+    candidateSrc: path.join(root, 'src'),
+    candidateViteConfig: path.join(root, 'vite.config.ts'),
+    capture: path.join(root, LAB_DIR, 'capture'),
+    characterize: path.join(root, LAB_DIR, 'characterize'),
+    lab: path.join(root, LAB_DIR),
+    labManifest: path.join(root, LAB_DIR, 'lab.json'),
+    ledger: path.join(root, LAB_DIR, 'ledger'),
+    parity: path.join(root, LAB_DIR, 'parity'),
+    pipelineLockFile: path.join(root, LAB_DIR, '.lock'),
+    stripDecisions: path.join(root, LAB_DIR, 'capture', 'strip-decisions.json'),
+});
+const buildV3Markers = (root) => ({
+    handoffFile: path.join(root, 'handoff.json'),
+    stages: path.join(root, 'stages'),
+    ushmanState: path.join(root, USHMAN_DIR, 'state.json'),
+    workspaceIdFile: path.join(root, USHMAN_DIR, 'workspace-id.json'),
+});
+const detectWorkspaceLayoutSync = (root) => {
+    const v4 = buildV4Paths(root);
+    const v3 = buildV3Markers(root);
+    if (existsSync(v4.labManifest)) {
+        return 'v4';
+    }
+    if (existsSync(v3.stages) || existsSync(v3.ushmanState) || existsSync(v3.handoffFile)) {
+        return 'v3';
+    }
+    return 'unknown';
+};
+export const resolveWorkspacePaths = (root) => {
+    const v4 = buildV4Paths(root);
+    const v3 = buildV3Markers(root);
+    const layout = detectWorkspaceLayoutSync(root);
+    const pipelineLockFile = layout === 'v3' ? path.join(root, USHMAN_DIR, 'pipeline.lock') : v4.pipelineLockFile;
+    return {
+        layout,
+        pipelineLockFile,
+        root,
+        screenshotsDir: path.join(root, 'screenshots'),
+        screenshotsIndexFile: path.join(root, 'screenshots', 'index.json'),
+        stateDagFile: path.join(root, LAB_DIR, 'state-dag.json'),
+        v3,
+        v4,
+    };
+};
+export const pathExists = async (filePath) => {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+};
+export const detectWorkspaceLayout = async (root) => {
+    const paths = resolveWorkspacePaths(root);
+    const labFile = Bun.file(paths.v4.labManifest);
+    if (await labFile.exists()) {
+        try {
+            const parsed = (await labFile.json());
+            if (parsed.schemaVersion === V4_SCHEMA_VERSION) {
+                return 'v4';
+            }
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    const [stagesExists, stateExists, handoffExists] = await Promise.all([
+        pathExists(paths.v3.stages),
+        Bun.file(paths.v3.ushmanState).exists(),
+        Bun.file(paths.v3.handoffFile).exists(),
+    ]);
+    if (stagesExists || stateExists || handoffExists) {
+        return 'v3';
+    }
+    return 'unknown';
+};
+export const buildV3MigrationMessage = (workspaceRoot) => [
+    'This workspace is in v3 layout (legacy stages/, .ushman/, handoff.json at root).',
+    'ushman v4 no longer ships the v3 layout readers or the live migrator.',
+    '`ushman migrate-v3-v4` is retained only as a diagnostic stub.',
+    'All known v3 workspaces were migrated during the v4 cutover.',
+    'If this workspace was not on that migration list, restore shibuk v2.x + ushman v3.x to migrate it first.',
+    `Workspace: ${workspaceRoot}`,
+].join('\n');
+const createWorkspaceLayoutError = ({ layout, workspaceRoot, }) => {
+    if (layout === 'v3') {
+        return new WorkspaceLayoutError({
+            exitCode: V4_MIGRATION_EXIT_CODE,
+            layout,
+            message: buildV3MigrationMessage(workspaceRoot),
+            workspaceRoot,
+        });
+    }
+    return new WorkspaceLayoutError({
+        exitCode: 1,
+        layout,
+        message: `Workspace at ${workspaceRoot} has layout "${layout}", not v4. Expected ${path.join(workspaceRoot, '.lab', 'lab.json')} with schemaVersion "${V4_SCHEMA_VERSION}".`,
+        workspaceRoot,
+    });
+};
+export const assertV4Workspace = async (root) => {
+    const layout = await detectWorkspaceLayout(root);
+    if (layout !== 'v4') {
+        throw createWorkspaceLayoutError({
+            layout,
+            workspaceRoot: root,
+        });
+    }
+    return {
+        ...resolveWorkspacePaths(root),
+        layout,
+    };
+};
+export const atomicWriteJson = async (filePath, payload) => {
+    const dir = path.dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(filePath)}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`);
+    await Bun.write(tmp, `${JSON.stringify(payload, null, 2)}\n`);
+    await rename(tmp, filePath);
+};
+export const atomicWriteText = async (filePath, text) => {
+    const dir = path.dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(filePath)}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`);
+    await Bun.write(tmp, text);
+    await rename(tmp, filePath);
+};
+export const readVersionedDocument = async (filePath, schema) => {
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+        return null;
+    }
+    return v.parse(schema, (await file.json()));
+};
+export const resolveDeterminismSeed = async (workspaceRoot) => {
+    const layout = await detectWorkspaceLayout(workspaceRoot);
+    if (layout === 'v4') {
+        const file = Bun.file(resolveWorkspacePaths(workspaceRoot).v4.labManifest);
+        if (await file.exists()) {
+            try {
+                const manifest = (await file.json());
+                if (typeof manifest.workspaceId === 'string' && manifest.workspaceId.length > 0) {
+                    return manifest.workspaceId;
+                }
+            }
+            catch {
+                return workspaceRoot;
+            }
+        }
+        return workspaceRoot;
+    }
+    const workspaceId = await readVersionedDocument(resolveWorkspacePaths(workspaceRoot).v3.workspaceIdFile, V3WorkspaceIdDocumentSchema);
+    return workspaceId?.packageHash ?? workspaceRoot;
+};
+export const resolveStateDagFile = async (workspaceRoot) => {
+    return resolveWorkspacePaths(workspaceRoot).stateDagFile;
+};
+const readPipelineLock = async (filePath) => {
+    if (!(await pathExists(filePath))) {
+        return null;
+    }
+    return (await Bun.file(filePath).json());
+};
+const pipelineLockPayload = (command) => ({
+    command,
+    hostname: os.hostname(),
+    pid: process.pid,
+    startedAt: nowIso(),
+});
+const tryWriteLockfile = async (filePath, payload) => {
+    const handle = await open(filePath, 'wx');
+    let writeError = null;
+    let closeError = null;
+    try {
+        await handle.writeFile(`${JSON.stringify(payload, null, 2)}\n`);
+    }
+    catch (error) {
+        writeError = error;
+    }
+    finally {
+        try {
+            await handle.close();
+        }
+        catch (error) {
+            closeError = error;
+        }
+    }
+    if (writeError) {
+        throw writeError;
+    }
+    if (closeError) {
+        throw closeError;
+    }
+};
+const reclaimStaleLockOrThrowBusy = async (filePath) => {
+    const existing = await readPipelineLock(filePath);
+    const existingPid = typeof existing?.pid === 'number' ? existing.pid : null;
+    if (existingPid !== null) {
+        try {
+            process.kill(existingPid, 0);
+            throw new Error(`EBUSY: pipeline lock held by PID ${existingPid}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.startsWith('EBUSY:')) {
+                throw error;
+            }
+        }
+    }
+    await rm(filePath, { force: true });
+};
+const acquirePipelineLock = async ({ command, workspaceRoot, }) => {
+    const { pipelineLockFile } = resolveWorkspacePaths(workspaceRoot);
+    await mkdir(path.dirname(pipelineLockFile), { recursive: true });
+    const payload = pipelineLockPayload(command);
+    try {
+        await tryWriteLockfile(pipelineLockFile, payload);
+    }
+    catch (error) {
+        const errno = error;
+        if (errno.code !== 'EEXIST') {
+            throw error;
+        }
+        await reclaimStaleLockOrThrowBusy(pipelineLockFile);
+        try {
+            await tryWriteLockfile(pipelineLockFile, payload);
+        }
+        catch (reclaimError) {
+            const reclaimedErrno = reclaimError;
+            if (reclaimedErrno.code === 'EEXIST') {
+                throw new Error('EBUSY: pipeline lock was reacquired by another process');
+            }
+            throw reclaimError;
+        }
+    }
+    return async () => {
+        await rm(pipelineLockFile, { force: true });
+    };
+};
+export const withPipelineLock = async ({ command, disabled = false, workspaceRoot, work, }) => {
+    if (disabled) {
+        return work();
+    }
+    const release = await acquirePipelineLock({
+        command,
+        workspaceRoot,
+    });
+    try {
+        return await work();
+    }
+    finally {
+        await release();
+    }
+};