clinkx 0.3.0 → 1.1.0

package/dist/context-builder/storage.js

@@ -1,4 +1,4 @@
-import { link as fsLink, open as fsOpen, mkdir as fsMkdir, 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";
@@ -6,12 +6,15 @@ import { CancellationError, ExecutionError, InvalidParamsError } from "../errors
 import { validateProspectiveChildPath } from "../paths.js";
 import { contextBuilderInternalCapsForManifest, CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS, resolveContextBuilderRunsDir, } from "./config.js";
 import { boundContextBuilderOmissions, boundContextBuilderWarnings, } from "./diagnostics.js";
-import { cloneContextBuilderDelegateReceiptMetadata, CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS, CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_SCHEMA_VERSION, isContextBuilderDelegateReceiptMetadata, } from "./receipt.js";
+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",
+    selected_context_jsonl: "selected-context.jsonl",
     tree_json: "tree.json",
     search_jsonl: "search.jsonl",
     slices_jsonl: "slices.jsonl",
@@ -25,8 +28,10 @@ const DEFAULT_STORAGE_OPS = {
     rename: fsRename,
     rm: fsRm,
     open: fsOpen,
+    lstat: fsLstat,
     link: fsLink,
     stat: fsStat,
+    readdir: fsReaddir,
 };
 const CONTEXT_BUILDER_METRIC_TYPES = Object.freeze({
     files_seen: "number",
@@ -44,10 +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);
@@ -112,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,
@@ -123,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);
@@ -147,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) {
@@ -157,6 +190,7 @@ export async function writeContextBuilderArtifactsAndCommit(storage, contents, m
         }
         throwIfCancelledBeforeManifest(options.signal === undefined ? {} : { signal: options.signal });
         await assertRequiredArtifactsReadable(canonicalStorage, ops);
+        await options.beforeManifestCommit?.();
         const internalCaps = contextBuilderInternalCapsForManifest(manifest.internal_caps);
         const { delegate, ...manifestWithoutDelegate } = manifest;
         const boundedDelegate = normalizeManifestDelegateMetadata(delegate);
@@ -173,13 +207,358 @@ export async function writeContextBuilderArtifactsAndCommit(storage, contents, m
         await writeExclusiveText(canonicalStorage.manifestJson, `${JSON.stringify(completeManifest)}\n`, ops, options.signal === undefined ? {} : { signal: options.signal });
     }, { 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 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}`);
+                }
+                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);
+            }
+            throw error;
+        }
+    }, ops);
+}
+export async function evictWorkflowContextRuns(runsDir, options = {}) {
+    const ops = options.ops ?? DEFAULT_STORAGE_OPS;
+    const readdir = ops.readdir ?? fsReaddir;
+    const resolvedRunsDir = await resolveContextBuilderRunsDir(runsDir);
+    const bounds = resolveWorkflowContextEvictionBounds(options);
+    const nowMs = options.nowMs ?? Date.now();
+    const protectedRunIds = new Set(options.protectedRunIds ?? []);
+    const entries = await readdir(resolvedRunsDir, { withFileTypes: true });
+    const committedCacheEntries = [];
+    const removeSet = new Map();
+    let scanned = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isWorkflowContextRunId(entry.name)) {
+            continue;
+        }
+        scanned += 1;
+        try {
+            const storage = resolveContextBuilderRunPaths(resolvedRunsDir, entry.name);
+            const directoryAdmission = await admitContextBuilderRunDirectory(storage, ops);
+            if (directoryAdmission === undefined) {
+                skipped += 1;
+                continue;
+            }
+            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(candidate);
+                }
+                if (nowMs - mtimeMs > bounds.cacheTtlMs) {
+                    if (isProtected) {
+                        skipped += 1;
+                    }
+                    else {
+                        removeSet.set(storage.runId, candidate);
+                    }
+                }
+                continue;
+            }
+            if (nowMs - mtimeMs > bounds.tempTtlMs) {
+                if (isProtected) {
+                    skipped += 1;
+                }
+                else {
+                    removeSet.set(storage.runId, candidate);
+                }
+            }
+        }
+        catch {
+            failed += 1;
+        }
+    }
+    const cacheSurvivors = committedCacheEntries
+        .filter(({ storage }) => !removeSet.has(storage.runId))
+        .sort((a, b) => a.mtimeMs - b.mtimeMs);
+    cacheSurvivors
+        .slice(0, Math.max(0, cacheSurvivors.length - bounds.maxEntries))
+        .forEach((candidate) => {
+        removeSet.set(candidate.storage.runId, candidate);
+    });
+    let evicted = 0;
+    for (const { storage, admission, directoryAdmission } of removeSet.values()) {
+        try {
+            const didRemove = await removeCommittedWorkflowContextRun(storage, admission, directoryAdmission, ops);
+            if (didRemove) {
+                evicted += 1;
+            }
+            else {
+                skipped += 1;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                skipped += 1;
+            }
+            else {
+                failed += 1;
+            }
+        }
+    }
+    if (evicted > 0) {
+        await syncDirectoryBestEffort(resolvedRunsDir, ops);
+    }
+    return { scanned, evicted, skipped, failed };
+}
 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);
+}
+/**
+ * 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 withCommittedContextBuilderRunMutationLease(storage, callback, ops = DEFAULT_STORAGE_OPS) {
+    const canonicalStorage = canonicalizeContextBuilderStorage(storage);
+    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)) {
         return false;
@@ -202,10 +581,12 @@ export async function isContextBuilderRunCommitted(runDir, ops = DEFAULT_STORAGE
         if (expectedStorage.runDir !== resolvedRunDir) {
             return false;
         }
-        if (!artifactPathsExactlyMatch(parsed.artifacts, expectedStorage.artifacts)) {
+        const artifactKeys = supportedArtifactKeys(parsed.artifacts);
+        if (artifactKeys == null
+            || !artifactPathsExactlyMatch(parsed.artifacts, expectedStorage.artifacts, artifactKeys)) {
             return false;
         }
-        await assertRequiredArtifactsReadable(expectedStorage, ops);
+        await assertRequiredArtifactsReadable(expectedStorage, ops, artifactKeys);
         return true;
     }
     catch {
@@ -218,13 +599,46 @@ function canonicalizeContextBuilderStorage(storage) {
         || storage.artifactDir !== expected.artifactDir
         || storage.buildingJson !== expected.buildingJson
         || storage.manifestJson !== expected.manifestJson
-        || !artifactPathsExactlyMatch(storage.artifacts, expected.artifacts)) {
+        || !artifactPathsExactlyMatch(storage.artifacts, expected.artifacts, CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS)) {
         throw new ExecutionError("context_builder storage paths do not match run_id and runs_dir");
     }
     return storage.ownerNonce === undefined
         ? expected
         : { ...expected, ownerNonce: storage.ownerNonce };
 }
+async function readContextBuilderManifest(manifestPath, ops) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await ops.readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new ExecutionError(`context_builder cannot read manifest for promotion: ${nodeErrorCode(error)}`);
+    }
+    const parsedRunId = parsed !== null && typeof parsed === "object"
+        ? parsed.run_id
+        : undefined;
+    if (typeof parsedRunId !== "string"
+        || !isValidContextBuilderManifest(parsed, parsedRunId)) {
+        throw new ExecutionError("context_builder cannot promote run with an invalid manifest");
+    }
+    return parsed;
+}
+function rewriteContextBuilderSummaryRunId(summaryText, targetRunId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(summaryText);
+    }
+    catch {
+        throw new ExecutionError("context_builder cannot promote run with an invalid summary artifact");
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new ExecutionError("context_builder cannot promote run with an invalid summary artifact");
+    }
+    return `${JSON.stringify({
+        ...parsed,
+        run_id: targetRunId,
+    })}\n`;
+}
 async function mayRemoveIncompleteRunDir(storage, ownerNonce, ops) {
     return (await canRemoveIncompleteRunDir(storage, ownerNonce, ops)).removable;
 }
@@ -274,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;
     }
@@ -302,149 +716,9 @@ 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) {
+async function assertRequiredArtifactsReadable(storage, ops, artifactKeys = CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS) {
     const missing = [];
-    for (const key of CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS) {
+    for (const key of artifactKeys) {
         if (key === "manifest_json") {
             continue;
         }
@@ -471,11 +745,11 @@ async function assertManifestAbsentForMutation(storage, ops) {
     }
     throw new ExecutionError("context_builder cannot mutate committed run: manifest already exists");
 }
-function artifactPathsExactlyMatch(actual, expected) {
-    if (!hasExactArtifactKeys(actual)) {
+function artifactPathsExactlyMatch(actual, expected, artifactKeys) {
+    if (!hasExactArtifactKeys(actual, artifactKeys)) {
         return false;
     }
-    for (const key of CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS) {
+    for (const key of artifactKeys) {
         if (actual[key] !== expected[key]) {
             return false;
         }
@@ -533,12 +807,22 @@ function hasRequiredArtifactPaths(value) {
         return false;
     }
     const artifacts = value;
-    return hasExactArtifactKeys(artifacts) && CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS.every((key) => (typeof artifacts[key] === "string"));
+    const artifactKeys = supportedArtifactKeys(artifacts);
+    return artifactKeys != null && artifactKeys.every((key) => (typeof artifacts[key] === "string"));
 }
-function hasExactArtifactKeys(value) {
-    const expectedKeys = new Set(CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS);
+function supportedArtifactKeys(value) {
+    if (hasExactArtifactKeys(value, CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS)) {
+        return CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS;
+    }
+    if (hasExactArtifactKeys(value, CONTEXT_BUILDER_LEGACY_ARTIFACT_KEYS)) {
+        return CONTEXT_BUILDER_LEGACY_ARTIFACT_KEYS;
+    }
+    return undefined;
+}
+function hasExactArtifactKeys(value, expectedArtifactKeys) {
+    const expectedKeys = new Set(expectedArtifactKeys);
     const actualKeys = Object.keys(value);
-    return (actualKeys.length === CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS.length
+    return (actualKeys.length === expectedArtifactKeys.length
         && actualKeys.every((key) => expectedKeys.has(key)));
 }
 function hasRequiredMetrics(value) {
@@ -660,6 +944,57 @@ async function syncDirectoryBestEffort(path, ops) {
         }
     }
 }
+async function removeCommittedWorkflowContextRun(storage, admission, directoryAdmission, ops) {
+    if (!isWorkflowContextRunId(storage.runId)) {
+        return false;
+    }
+    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;
+        }
+        throw error;
+    }
+}
+function isWorkflowContextRunId(runId) {
+    return runId.startsWith("wfctx-") || runId.startsWith("wfpre-");
+}
+function resolveWorkflowContextEvictionBounds(options) {
+    const env = options.env ?? process.env;
+    const maxEntries = normalizeNonNegativeInteger(options.maxEntries, parseNonNegativeInteger(env[WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES_ENV], DEFAULT_WORKFLOW_CONTEXT_CACHE_MAX_ENTRIES));
+    const cacheTtlSeconds = normalizeNonNegativeInteger(options.cacheTtlSeconds, parseNonNegativeInteger(env[WORKFLOW_CONTEXT_CACHE_TTL_SECONDS_ENV], DEFAULT_WORKFLOW_CONTEXT_CACHE_TTL_SECONDS));
+    const tempTtlSeconds = normalizeNonNegativeInteger(options.tempTtlSeconds, Math.min(cacheTtlSeconds, DEFAULT_WORKFLOW_CONTEXT_TEMP_TTL_SECONDS));
+    return {
+        maxEntries,
+        cacheTtlMs: cacheTtlSeconds * 1_000,
+        // Provenance-only temp runs are useful for debugging recent misses, but they
+        // are not reusable cache entries, so they get a shorter bounded lifetime.
+        tempTtlMs: tempTtlSeconds * 1_000,
+    };
+}
+function parseNonNegativeInteger(value, fallback) {
+    if (value == null || value.trim() === "") {
+        return fallback;
+    }
+    const parsed = Number(value);
+    return normalizeNonNegativeInteger(parsed, fallback);
+}
+function normalizeNonNegativeInteger(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    return Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
 function isNodeError(error) {
     return error instanceof Error && "code" in error;
 }
@@ -736,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);