clinkx 1.0.0 → 1.1.1

package/dist/context-builder/storage.js

@@ -1,4 +1,4 @@
-import { link as fsLink, open as fsOpen, mkdir as fsMkdir, readdir as fsReaddir, readFile as fsReadFile, rename as fsRename, rm as fsRm, stat as fsStat, writeFile as fsWriteFile, } from "node:fs/promises";
+import { link as fsLink, lstat as fsLstat, open as fsOpen, mkdir as fsMkdir, readdir as fsReaddir, readFile as fsReadFile, rename as fsRename, rm as fsRm, stat as fsStat, writeFile as fsWriteFile, } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
@@ -9,6 +9,8 @@ import { boundContextBuilderOmissions, boundContextBuilderWarnings, } from "./di
 import { cloneContextBuilderDelegateReceiptMetadata, CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_LEGACY_ARTIFACT_KEYS, CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS, CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_SCHEMA_VERSION, isContextBuilderDelegateReceiptMetadata, } from "./receipt.js";
 import { validateCallerRunId } from "./run-id.js";
 import { scanSecretPath } from "./secrets.js";
+import { CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME, readContextBuilderInvocationAuditSidecar, } from "./invocation-sidecar.js";
+import { withContextBuilderMutationLock, } from "./mutation-lock.js";
 export const CONTEXT_BUILDER_ARTIFACT_FILE_NAMES = Object.freeze({
     manifest_json: "manifest.json",
     bundle_md: "bundle.md",
@@ -26,6 +28,7 @@ const DEFAULT_STORAGE_OPS = {
     rename: fsRename,
     rm: fsRm,
     open: fsOpen,
+    lstat: fsLstat,
     link: fsLink,
     stat: fsStat,
     readdir: fsReaddir,
@@ -46,15 +49,38 @@ const CONTEXT_BUILDER_METRIC_TYPES = Object.freeze({
     truncated: "boolean",
 });
 const CONTEXT_BUILDER_INTERNAL_CAP_KEYS = Object.keys(CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS);
-const CONTEXT_BUILDER_MUTATION_LOCK_SUFFIX = ".mutation.lock";
-const CONTEXT_BUILDER_MUTATION_LOCK_ATTEMPTS = 1_000;
-const CONTEXT_BUILDER_MUTATION_LOCK_RETRY_MS = 10;
-const CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS = 10 * 60 * 1_000;
 export const WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES_ENV = "CLINKX_WORKFLOWS_CONTEXT_CACHE_MAX_ENTRIES";
 export const WORKFLOW_CONTEXT_CACHE_TTL_SECONDS_ENV = "CLINKX_WORKFLOWS_CONTEXT_CACHE_TTL_SECONDS";
 export const DEFAULT_WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES = 50;
 export const DEFAULT_WORKFLOW_CONTEXT_CACHE_TTL_SECONDS = 86_400;
 const DEFAULT_WORKFLOW_CONTEXT_TEMP_TTL_SECONDS = 3_600;
+export class ContextBuilderAncillaryPromotionError extends ExecutionError {
+    reasonCode;
+    constructor(reasonCode) {
+        super("context_builder invocation audit ancillary promotion failed");
+        this.name = "ContextBuilderAncillaryPromotionError";
+        this.reasonCode = reasonCode;
+    }
+}
+export class ContextBuilderRunClaimConflictError extends InvalidParamsError {
+    constructor(runId) {
+        super(`context_builder run_id already exists: ${runId}`);
+        this.name = "ContextBuilderRunClaimConflictError";
+    }
+}
+export class ContextBuilderActiveRunClaimConflictError extends ExecutionError {
+    constructor(runId) {
+        super(`context_builder run_id conflicts with an incomplete or active run: ${runId}`);
+        this.name = "ContextBuilderActiveRunClaimConflictError";
+    }
+}
+export class ContextBuilderCommittedRunChangedError extends ExecutionError {
+    constructor(runId) {
+        super(`context_builder committed run changed before lease admission: ${runId}`);
+        this.name = "ContextBuilderCommittedRunChangedError";
+    }
+}
+const HELD_CONTEXT_BUILDER_MUTATION_LOCKS = Symbol("heldContextBuilderMutationLocks");
 export function resolveContextBuilderRunPaths(runsDir, runId) {
     validateCallerRunId(runId);
     const resolvedRunsDir = resolve(runsDir);
@@ -119,7 +145,7 @@ export async function createContextBuilderRun(input, ops = DEFAULT_STORAGE_OPS)
 }
 export async function writeContextBuilderArtifact(storage, key, content, ops = DEFAULT_STORAGE_OPS) {
     const canonicalStorage = canonicalizeContextBuilderStorage(storage);
-    await withContextBuilderMutationLock(canonicalStorage, ops, async () => {
+    await withContextBuilderStorageMutationLock(canonicalStorage, ops, async () => {
         await assertManifestAbsentForMutation(canonicalStorage, ops);
         await writeAtomicText(canonicalStorage.artifacts[key], content, ops, {
             mustNotExistPath: canonicalStorage.manifestJson,
@@ -130,7 +156,7 @@ export async function commitContextBuilderRun(storage, manifest, optionsOrOps =
     const { options, ops } = normalizeCommitArguments(optionsOrOps, maybeOps);
     const canonicalStorage = canonicalizeContextBuilderStorage(storage);
     const ownerNonce = options.ownerNonce ?? canonicalStorage.ownerNonce;
-    await withContextBuilderMutationLock(canonicalStorage, ops, async () => {
+    await withContextBuilderStorageMutationLock(canonicalStorage, ops, async () => {
         await assertManifestAbsentForMutation(canonicalStorage, ops);
         await assertRequiredArtifactsReadable(canonicalStorage, ops);
         throwIfCancelledBeforeManifest(options);
@@ -154,7 +180,7 @@ export async function writeContextBuilderArtifactsAndCommit(storage, contents, m
     const ops = options.ops ?? DEFAULT_STORAGE_OPS;
     const canonicalStorage = canonicalizeContextBuilderStorage(storage);
     const ownerNonce = options.ownerNonce ?? canonicalStorage.ownerNonce;
-    await withContextBuilderMutationLock(canonicalStorage, ops, async () => {
+    await withContextBuilderStorageMutationLock(canonicalStorage, ops, async () => {
         await assertManifestAbsentForMutation(canonicalStorage, ops);
         for (const [key, content] of Object.entries(contents)) {
             if (options.signal?.aborted === true) {
@@ -182,66 +208,92 @@ export async function writeContextBuilderArtifactsAndCommit(storage, contents, m
     }, { ownerNonce });
 }
 export async function promoteContextBuilderRun(tempRunDir, targetRunId, ops = DEFAULT_STORAGE_OPS) {
+    return await withPromotedContextBuilderRun(tempRunDir, targetRunId, async (storage) => storage, ops);
+}
+/**
+ * Acquire source before target, then retain the target lease through its
+ * caller's manifest re-read and materialization callback.
+ */
+export async function withPromotedContextBuilderRun(tempRunDir, targetRunId, callback, ops = DEFAULT_STORAGE_OPS) {
     const resolvedTempRunDir = resolve(tempRunDir);
-    const tempManifest = await readContextBuilderManifest(join(resolvedTempRunDir, "manifest.json"), ops);
-    const tempStorage = resolveContextBuilderRunPaths(dirname(resolvedTempRunDir), tempManifest.run_id);
-    if (tempStorage.runDir !== resolvedTempRunDir
-        || !await isContextBuilderRunCommitted(resolvedTempRunDir, ops)) {
-        throw new ExecutionError("context_builder cannot promote an uncommitted or mismatched temp run");
-    }
-    const targetStorage = resolveContextBuilderRunPaths(tempStorage.runsDir, targetRunId);
-    await claimContextBuilderRunDir(targetStorage, ops);
-    try {
-        await ops.mkdir(targetStorage.artifactDir, { recursive: false, mode: 0o700 });
-        await withContextBuilderMutationLock(targetStorage, ops, async () => {
-            await assertManifestAbsentForMutation(targetStorage, ops);
-            const artifactEntries = Object.entries(tempManifest.artifacts);
-            for (const [key, sourcePath] of artifactEntries) {
-                if (key === "manifest_json") {
-                    continue;
+    const tempStorage = resolveContextBuilderRunPaths(dirname(resolvedTempRunDir), basename(resolvedTempRunDir));
+    return await withCommittedContextBuilderRunMutationLease(tempStorage, async (sourceOps) => {
+        const tempManifest = await readContextBuilderManifest(tempStorage.manifestJson, sourceOps);
+        if (tempStorage.runDir !== resolvedTempRunDir
+            || tempManifest.run_id !== tempStorage.runId) {
+            throw new ExecutionError("context_builder cannot promote an uncommitted or mismatched temp run");
+        }
+        let invocationAudit;
+        try {
+            invocationAudit = await readContextBuilderInvocationAuditSidecar(tempStorage.runDir);
+        }
+        catch {
+            throw new ContextBuilderAncillaryPromotionError("invalid_source");
+        }
+        const targetStorage = resolveContextBuilderRunPaths(tempStorage.runsDir, targetRunId);
+        await claimContextBuilderRunDir(targetStorage, sourceOps);
+        let targetCommitted = false;
+        try {
+            await sourceOps.mkdir(targetStorage.artifactDir, { recursive: false, mode: 0o700 });
+            return await withContextBuilderStorageMutationLock(targetStorage, sourceOps, async (targetOps) => {
+                await assertManifestAbsentForMutation(targetStorage, targetOps);
+                const artifactEntries = Object.entries(tempManifest.artifacts);
+                for (const [key, sourcePath] of artifactEntries) {
+                    if (key === "manifest_json") {
+                        continue;
+                    }
+                    const targetPath = targetStorage.artifacts[key];
+                    const sourceContent = await targetOps.readFile(sourcePath, "utf8");
+                    const targetContent = key === "summary_json"
+                        ? rewriteContextBuilderSummaryRunId(sourceContent, targetRunId)
+                        : sourceContent;
+                    await writeAtomicText(targetPath, targetContent, targetOps, {
+                        mustNotExistPath: targetStorage.manifestJson,
+                    });
+                }
+                if (invocationAudit !== undefined) {
+                    try {
+                        await writeAtomicText(join(targetStorage.runDir, CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME), invocationAudit.serialized, targetOps, { mustNotExistPath: targetStorage.manifestJson });
+                    }
+                    catch {
+                        throw new ContextBuilderAncillaryPromotionError("copy_failed");
+                    }
+                }
+                const targetArtifacts = Object.fromEntries(Object.keys(tempManifest.artifacts).map((key) => [
+                    key,
+                    targetStorage.artifacts[key],
+                ]));
+                const targetManifest = {
+                    ...tempManifest,
+                    run_id: targetRunId,
+                    artifacts: targetArtifacts,
+                };
+                await writeExclusiveText(targetStorage.manifestJson, `${JSON.stringify(targetManifest)}\n`, targetOps);
+                if (!await isContextBuilderRunCommitted(targetStorage.runDir, targetOps)) {
+                    throw new ExecutionError(`context_builder promoted run failed validation: ${targetRunId}`);
                 }
-                const targetPath = targetStorage.artifacts[key];
-                const sourceContent = await ops.readFile(sourcePath, "utf8");
-                const targetContent = key === "summary_json"
-                    ? rewriteContextBuilderSummaryRunId(sourceContent, targetRunId)
-                    : sourceContent;
-                await writeAtomicText(targetPath, targetContent, ops, {
-                    mustNotExistPath: targetStorage.manifestJson,
-                });
+                targetCommitted = true;
+                await (targetOps.rm ?? fsRm)(resolvedTempRunDir, { recursive: true, force: true }).catch(() => { });
+                await syncDirectoryBestEffort(tempStorage.runsDir, targetOps);
+                return await callback(targetStorage, targetOps);
+            });
+        }
+        catch (error) {
+            if (!targetCommitted) {
+                // This call claimed the uncommitted target, so it owns cleanup.
+                await (sourceOps.rm ?? fsRm)(targetStorage.runDir, {
+                    recursive: true,
+                    force: true,
+                }).catch(() => { });
+                await syncDirectoryBestEffort(targetStorage.runsDir, sourceOps);
             }
-            const targetArtifacts = Object.fromEntries(Object.keys(tempManifest.artifacts).map((key) => [
-                key,
-                targetStorage.artifacts[key],
-            ]));
-            const targetManifest = {
-                ...tempManifest,
-                run_id: targetRunId,
-                artifacts: targetArtifacts,
-            };
-            await writeExclusiveText(targetStorage.manifestJson, `${JSON.stringify(targetManifest)}\n`, ops);
-        });
-        if (!await isContextBuilderRunCommitted(targetStorage.runDir, ops)) {
-            throw new ExecutionError(`context_builder promoted run failed validation: ${targetRunId}`);
+            throw error;
         }
-    }
-    catch (error) {
-        // The target dir was claimed above, so always clean it up on failure.
-        await (ops.rm ?? fsRm)(targetStorage.runDir, {
-            recursive: true,
-            force: true,
-        }).catch(() => { });
-        await syncDirectoryBestEffort(targetStorage.runsDir, ops);
-        throw error;
-    }
-    await (ops.rm ?? fsRm)(resolvedTempRunDir, { recursive: true, force: true })
-        .catch(() => { });
-    await syncDirectoryBestEffort(tempStorage.runsDir, ops);
-    return targetStorage;
+    }, ops);
 }
 export async function evictWorkflowContextRuns(runsDir, options = {}) {
     const ops = options.ops ?? DEFAULT_STORAGE_OPS;
     const readdir = ops.readdir ?? fsReaddir;
-    const stat = ops.stat ?? fsStat;
     const resolvedRunsDir = await resolveContextBuilderRunsDir(runsDir);
     const bounds = resolveWorkflowContextEvictionBounds(options);
     const nowMs = options.nowMs ?? Date.now();
@@ -259,43 +311,52 @@ export async function evictWorkflowContextRuns(runsDir, options = {}) {
         scanned += 1;
         try {
             const storage = resolveContextBuilderRunPaths(resolvedRunsDir, entry.name);
-            const runStat = await stat(storage.runDir).catch((error) => {
-                if (isNodeError(error) && error.code === "ENOENT") {
-                    return undefined;
-                }
-                throw error;
-            });
-            if (runStat === undefined) {
+            const directoryAdmission = await admitContextBuilderRunDirectory(storage, ops);
+            if (directoryAdmission === undefined) {
                 skipped += 1;
                 continue;
             }
-            if (!await isContextBuilderRunCommitted(storage.runDir, ops)) {
+            const admission = await admitCommittedContextBuilderRun(storage, ops);
+            if (admission === undefined) {
                 skipped += 1;
                 continue;
             }
+            const currentDirectoryAdmission = await admitContextBuilderRunDirectory(storage, ops);
+            if (currentDirectoryAdmission === undefined
+                || !contextBuilderRunDirectoryAdmissionsEqual(directoryAdmission, currentDirectoryAdmission)) {
+                skipped += 1;
+                continue;
+            }
+            const mtimeMs = Number(directoryAdmission.mtimeNs) / 1_000_000;
+            const candidate = {
+                storage,
+                mtimeMs,
+                admission,
+                directoryAdmission,
+            };
             const isProtected = protectedRunIds.has(storage.runId);
             if (entry.name.startsWith("wfctx-")) {
                 // Protected cache entries are excluded from LRU survivor accounting so
                 // they can never be selected for the max-entries trim below either.
                 if (!isProtected) {
-                    committedCacheEntries.push({ storage, mtimeMs: runStat.mtimeMs });
+                    committedCacheEntries.push(candidate);
                 }
-                if (nowMs - runStat.mtimeMs > bounds.cacheTtlMs) {
+                if (nowMs - mtimeMs > bounds.cacheTtlMs) {
                     if (isProtected) {
                         skipped += 1;
                     }
                     else {
-                        removeSet.set(storage.runId, storage);
+                        removeSet.set(storage.runId, candidate);
                     }
                 }
                 continue;
             }
-            if (nowMs - runStat.mtimeMs > bounds.tempTtlMs) {
+            if (nowMs - mtimeMs > bounds.tempTtlMs) {
                 if (isProtected) {
                     skipped += 1;
                 }
                 else {
-                    removeSet.set(storage.runId, storage);
+                    removeSet.set(storage.runId, candidate);
                 }
             }
         }
@@ -305,15 +366,16 @@ export async function evictWorkflowContextRuns(runsDir, options = {}) {
     }
     const cacheSurvivors = committedCacheEntries
         .filter(({ storage }) => !removeSet.has(storage.runId))
-        .sort((a, b) => a.mtimeMs - b.mtimeMs)
-        .map(({ storage }) => storage);
+        .sort((a, b) => a.mtimeMs - b.mtimeMs);
     cacheSurvivors
         .slice(0, Math.max(0, cacheSurvivors.length - bounds.maxEntries))
-        .forEach((storage) => removeSet.set(storage.runId, storage));
+        .forEach((candidate) => {
+        removeSet.set(candidate.storage.runId, candidate);
+    });
     let evicted = 0;
-    for (const storage of removeSet.values()) {
+    for (const { storage, admission, directoryAdmission } of removeSet.values()) {
         try {
-            const didRemove = await removeCommittedWorkflowContextRun(storage, ops);
+            const didRemove = await removeCommittedWorkflowContextRun(storage, admission, directoryAdmission, ops);
             if (didRemove) {
                 evicted += 1;
             }
@@ -337,19 +399,165 @@ export async function evictWorkflowContextRuns(runsDir, options = {}) {
 }
 export async function cleanupContextBuilderIncompleteRun(storage, ownerNonce, ops = DEFAULT_STORAGE_OPS) {
     const canonicalStorage = canonicalizeContextBuilderStorage(storage);
-    return withContextBuilderMutationLock(canonicalStorage, ops, async () => cleanupContextBuilderIncompleteRunLocked(canonicalStorage, ownerNonce, ops), {
+    return withContextBuilderStorageMutationLock(canonicalStorage, ops, async () => cleanupContextBuilderIncompleteRunLocked(canonicalStorage, ownerNonce, ops), {
         ownerNonce,
-        recoverStaleForCleanup: true,
+        canRecoverStale: async () => (await canRemoveIncompleteRunDir(canonicalStorage, ownerNonce, ops)).removable,
     });
 }
+/** Hold one run's mutation lock, reusing it for nested storage operations. */
+export async function withContextBuilderRunMutationLease(storage, callback, ops = DEFAULT_STORAGE_OPS, options = {}) {
+    const canonicalStorage = canonicalizeContextBuilderStorage(storage);
+    const effectiveOps = ops ?? DEFAULT_STORAGE_OPS;
+    return await withContextBuilderStorageMutationLock(canonicalStorage, effectiveOps, callback, options);
+}
 /**
- * Hold the existing per-run mutation lock while a committed run is consumed.
- * Writers and pruning use the same lock, so the callback may safely materialize
- * artifact paths without the run directory disappearing underneath it.
+ * Admit one exact committed-run incarnation, recover only a stale lock bound to
+ * that admission, and recheck the manifest after acquiring the lease.
  */
-export async function withContextBuilderRunMutationLease(storage, callback, ops = DEFAULT_STORAGE_OPS) {
+export async function withCommittedContextBuilderRunMutationLease(storage, callback, ops = DEFAULT_STORAGE_OPS) {
     const canonicalStorage = canonicalizeContextBuilderStorage(storage);
-    return await withContextBuilderMutationLock(canonicalStorage, ops, callback);
+    const admitted = await admitCommittedContextBuilderRun(canonicalStorage, ops);
+    if (admitted === undefined) {
+        throw new ContextBuilderCommittedRunChangedError(canonicalStorage.runId);
+    }
+    return await withAdmittedCommittedContextBuilderRunMutationLease(canonicalStorage, admitted, callback, ops);
+}
+async function withAdmittedCommittedContextBuilderRunMutationLease(storage, admitted, callback, ops) {
+    return await withContextBuilderStorageMutationLock(storage, ops, async (leasedOps) => {
+        const current = await admitCommittedContextBuilderRun(storage, leasedOps);
+        if (current === undefined
+            || !committedRunAdmissionsEqual(admitted, current)) {
+            throw new ContextBuilderCommittedRunChangedError(storage.runId);
+        }
+        return await callback(leasedOps);
+    }, {
+        canRecoverStale: async () => {
+            const current = await admitCommittedContextBuilderRun(storage, ops);
+            return current !== undefined
+                && committedRunAdmissionsEqual(admitted, current);
+        },
+    });
+}
+async function withContextBuilderStorageMutationLock(storage, ops, callback, options = {}) {
+    const heldLocks = ops[HELD_CONTEXT_BUILDER_MUTATION_LOCKS];
+    if (heldLocks?.has(storage.runDir) === true) {
+        return await callback(ops);
+    }
+    return await withContextBuilderMutationLock(storage, ops, async () => await callback(markContextBuilderMutationLockHeld(ops, storage.runDir)), options);
+}
+function markContextBuilderMutationLockHeld(ops, runDir) {
+    const inherited = ops[HELD_CONTEXT_BUILDER_MUTATION_LOCKS];
+    const heldLocks = new Set(inherited ?? []);
+    heldLocks.add(runDir);
+    const leasedOps = Object.create(ops);
+    Object.defineProperty(leasedOps, HELD_CONTEXT_BUILDER_MUTATION_LOCKS, {
+        value: heldLocks,
+    });
+    return leasedOps;
+}
+async function admitCommittedContextBuilderRun(storage, ops) {
+    const lstat = ops.lstat ?? fsLstat;
+    const open = ops.open ?? fsOpen;
+    let handle;
+    try {
+        const pathStats = await lstat(storage.manifestJson, { bigint: true });
+        if (!pathStats.isFile()) {
+            return undefined;
+        }
+        handle = await open(storage.manifestJson, "r");
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile()
+            || before.nlink === 0n
+            || !sameCommittedRunIncarnation(committedRunFingerprintFromStats(pathStats), committedRunFingerprintFromStats(before))) {
+            return undefined;
+        }
+        const serializedManifest = await handle.readFile({ encoding: "utf8" });
+        const afterRead = await handle.stat({ bigint: true });
+        const beforeFingerprint = committedRunFingerprintFromStats(before);
+        const afterReadFingerprint = committedRunFingerprintFromStats(afterRead);
+        if (afterRead.nlink === 0n
+            || !committedRunFingerprintsEqual(beforeFingerprint, afterReadFingerprint)) {
+            return undefined;
+        }
+        const parsed = JSON.parse(serializedManifest);
+        if (!isValidContextBuilderManifest(parsed, storage.runId)) {
+            return undefined;
+        }
+        const artifactKeys = supportedArtifactKeys(parsed.artifacts);
+        if (artifactKeys == null
+            || !artifactPathsExactlyMatch(parsed.artifacts, storage.artifacts, artifactKeys)) {
+            return undefined;
+        }
+        await assertRequiredArtifactsReadable(storage, ops, artifactKeys);
+        const afterArtifacts = await handle.stat({ bigint: true });
+        const finalFingerprint = committedRunFingerprintFromStats(afterArtifacts);
+        if (afterArtifacts.nlink === 0n
+            || !committedRunFingerprintsEqual(afterReadFingerprint, finalFingerprint)) {
+            return undefined;
+        }
+        return { serializedManifest, fingerprint: finalFingerprint };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+function committedRunFingerprintFromStats(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+        size: stats.size,
+        nlink: stats.nlink,
+    };
+}
+function sameCommittedRunIncarnation(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function committedRunFingerprintsEqual(left, right) {
+    return sameCommittedRunIncarnation(left, right)
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs
+        && left.size === right.size
+        && left.nlink === right.nlink;
+}
+function committedRunAdmissionsEqual(left, right) {
+    return left.serializedManifest === right.serializedManifest
+        && committedRunFingerprintsEqual(left.fingerprint, right.fingerprint);
+}
+async function admitContextBuilderRunDirectory(storage, ops) {
+    const lstat = ops.lstat ?? fsLstat;
+    try {
+        const stats = await lstat(storage.runDir, { bigint: true });
+        if (!stats.isDirectory() || stats.nlink === 0n) {
+            return undefined;
+        }
+        return {
+            dev: stats.dev,
+            ino: stats.ino,
+            mtimeNs: stats.mtimeNs,
+            ctimeNs: stats.ctimeNs,
+            size: stats.size,
+            nlink: stats.nlink,
+        };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function contextBuilderRunDirectoryAdmissionsEqual(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs
+        && left.size === right.size
+        && left.nlink === right.nlink;
 }
 async function cleanupContextBuilderIncompleteRunLocked(storage, ownerNonce, ops) {
     if (!await mayRemoveIncompleteRunDir(storage, ownerNonce, ops)) {
@@ -480,9 +688,9 @@ async function claimContextBuilderRunDir(paths, ops) {
     catch (error) {
         if (isNodeError(error) && error.code === "EEXIST") {
             if (await isContextBuilderRunCommitted(paths.runDir, ops)) {
-                throw new InvalidParamsError(`context_builder run_id already exists: ${paths.runId}`);
+                throw new ContextBuilderRunClaimConflictError(paths.runId);
             }
-            throw new ExecutionError(`context_builder run_id conflicts with an incomplete or active run: ${paths.runId}`);
+            throw new ContextBuilderActiveRunClaimConflictError(paths.runId);
         }
         throw error;
     }
@@ -508,146 +716,6 @@ function isStorageOps(value) {
         || "open" in value
         || "link" in value);
 }
-async function withContextBuilderMutationLock(storage, ops, callback, options = {}) {
-    const lockPath = mutationLockPathForStorage(storage);
-    const lockHandle = await acquireContextBuilderMutationLock(storage, lockPath, ops, options);
-    try {
-        return await callback();
-    }
-    finally {
-        await lockHandle.close().catch(() => { });
-        await (ops.rm ?? fsRm)(lockPath, { force: true }).catch(() => { });
-    }
-}
-async function acquireContextBuilderMutationLock(storage, lockPath, ops, options) {
-    const open = ops.open ?? fsOpen;
-    for (let attempt = 0; attempt < CONTEXT_BUILDER_MUTATION_LOCK_ATTEMPTS; attempt += 1) {
-        try {
-            const handle = await open(lockPath, "wx", 0o600);
-            try {
-                await writeMutationLockMetadata(handle, options.ownerNonce);
-                return handle;
-            }
-            catch (error) {
-                await handle.close().catch(() => { });
-                await (ops.rm ?? fsRm)(lockPath, { force: true }).catch(() => { });
-                throw error;
-            }
-        }
-        catch (error) {
-            if (isNodeError(error) && error.code === "EEXIST") {
-                if (options.recoverStaleForCleanup === true
-                    && await breakStaleCleanupMutationLock(storage, lockPath, options.ownerNonce, ops)) {
-                    continue;
-                }
-                await delay(CONTEXT_BUILDER_MUTATION_LOCK_RETRY_MS);
-                continue;
-            }
-            throw error;
-        }
-    }
-    throw new ExecutionError("context_builder timed out waiting for the run mutation lock");
-}
-function mutationLockPathForStorage(storage) {
-    validateCallerRunId(storage.runId);
-    const resolvedRunsDir = resolve(storage.runsDir);
-    const resolvedRunDir = resolve(storage.runDir);
-    if (!isPathInsideDirectory(resolvedRunDir, resolvedRunsDir)) {
-        throw new ExecutionError("context_builder refused mutation lock outside runs directory");
-    }
-    return join(resolvedRunsDir, `.${storage.runId}${CONTEXT_BUILDER_MUTATION_LOCK_SUFFIX}`);
-}
-async function writeMutationLockMetadata(handle, ownerNonce) {
-    const metadata = {
-        pid: process.pid,
-        hostname: hostname(),
-        created_at: new Date().toISOString(),
-        ...(ownerNonce == null ? {} : { owner_nonce: ownerNonce }),
-    };
-    await handle.writeFile(`${JSON.stringify(metadata)}\n`, { encoding: "utf8" });
-}
-async function breakStaleCleanupMutationLock(storage, lockPath, ownerNonce, ops) {
-    if (ownerNonce == null) {
-        return false;
-    }
-    const cleanupDecision = await canRemoveIncompleteRunDir(storage, ownerNonce, ops);
-    if (!cleanupDecision.removable) {
-        return false;
-    }
-    if (!await isMutationLockOldEnough(lockPath, ops)) {
-        return false;
-    }
-    const metadata = await readMutationLockMetadata(lockPath, ops);
-    if (metadata !== "invalid" && !isStaleMutationLockMetadata(metadata)) {
-        return false;
-    }
-    await (ops.rm ?? fsRm)(lockPath, { force: true }).catch(() => { });
-    return true;
-}
-async function isMutationLockOldEnough(lockPath, ops) {
-    const stat = ops.stat ?? fsStat;
-    try {
-        const lockStat = await stat(lockPath);
-        return Date.now() - lockStat.mtimeMs >= CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS;
-    }
-    catch {
-        return false;
-    }
-}
-async function readMutationLockMetadata(lockPath, ops) {
-    let parsed;
-    try {
-        parsed = JSON.parse(await ops.readFile(lockPath, "utf8"));
-    }
-    catch {
-        return "invalid";
-    }
-    if (parsed === null || typeof parsed !== "object") {
-        return "invalid";
-    }
-    const metadata = parsed;
-    if (typeof metadata.pid !== "number"
-        || !Number.isInteger(metadata.pid)
-        || typeof metadata.hostname !== "string"
-        || typeof metadata.created_at !== "string") {
-        return "invalid";
-    }
-    if (metadata.owner_nonce !== undefined
-        && typeof metadata.owner_nonce !== "string") {
-        return "invalid";
-    }
-    return {
-        pid: metadata.pid,
-        hostname: metadata.hostname,
-        created_at: metadata.created_at,
-        ...(metadata.owner_nonce === undefined
-            ? {}
-            : { owner_nonce: metadata.owner_nonce }),
-    };
-}
-function isStaleMutationLockMetadata(metadata) {
-    const createdAtMs = Date.parse(metadata.created_at);
-    if (!Number.isFinite(createdAtMs)
-        || Date.now() - createdAtMs < CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS) {
-        return false;
-    }
-    if (metadata.hostname !== hostname()) {
-        return false;
-    }
-    return !isProcessAlive(metadata.pid);
-}
-function isProcessAlive(pid) {
-    if (pid <= 0) {
-        return false;
-    }
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return !(isNodeError(error) && error.code === "ESRCH");
-    }
-}
 async function assertRequiredArtifactsReadable(storage, ops, artifactKeys = CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS) {
     const missing = [];
     for (const key of artifactKeys) {
@@ -876,17 +944,27 @@ async function syncDirectoryBestEffort(path, ops) {
         }
     }
 }
-async function removeCommittedWorkflowContextRun(storage, ops) {
+async function removeCommittedWorkflowContextRun(storage, admission, directoryAdmission, ops) {
     if (!isWorkflowContextRunId(storage.runId)) {
         return false;
     }
-    return await withContextBuilderMutationLock(storage, ops, async () => {
-        if (!await isContextBuilderRunCommitted(storage.runDir, ops)) {
+    try {
+        return await withAdmittedCommittedContextBuilderRunMutationLease(storage, admission, async (leasedOps) => {
+            const currentDirectoryAdmission = await admitContextBuilderRunDirectory(storage, leasedOps);
+            if (currentDirectoryAdmission === undefined
+                || !contextBuilderRunDirectoryAdmissionsEqual(directoryAdmission, currentDirectoryAdmission)) {
+                return false;
+            }
+            await (leasedOps.rm ?? fsRm)(storage.runDir, { recursive: true, force: true });
+            return true;
+        }, ops);
+    }
+    catch (error) {
+        if (error instanceof ContextBuilderCommittedRunChangedError) {
             return false;
         }
-        await (ops.rm ?? fsRm)(storage.runDir, { recursive: true, force: true });
-        return true;
-    });
+        throw error;
+    }
 }
 function isWorkflowContextRunId(runId) {
     return runId.startsWith("wfctx-") || runId.startsWith("wfpre-");
@@ -993,9 +1071,6 @@ function diagnosticText(value, fallback) {
 function isRecord(value) {
     return value !== null && typeof value === "object";
 }
-async function delay(ms) {
-    await new Promise((resolve) => setTimeout(resolve, ms));
-}
 function isPathInsideDirectory(candidate, directory) {
     const relation = relative(directory, candidate);
     return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);