clinkx 1.0.0 → 1.1.0

package/dist/context-builder/workflow-runner.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { realpathSync, statSync } from "node:fs";
-import { copyFile, mkdir, readFile, realpath, rename, rm, utimes, } from "node:fs/promises";
+import { copyFile, link, lstat, mkdir, open, readFile, realpath, rename, rm, utimes, } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 // ---------------------------------------------------------------------------
 // Deep `clinkx-workflows/dist` imports (one-way dependency, build-order coupled)
@@ -36,11 +36,12 @@ import { CONTEXT_BUILDER_RENDERER_VERSION } from "./bundle.js";
 import { CONTEXT_DELEGATE_PROMPT_VERSION, CONTEXT_DISCOVERY_ALGORITHM_VERSION, } from "./versions.js";
 import { getSharedContextBuilderSemaphore, resolveContextBuilderRunsDir, } from "./config.js";
 import { handleContextBuilder } from "./handler.js";
+import { CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME, isContextBuilderInvocationAuditSidecarProvenInvalid, readContextBuilderInvocationAuditSidecar, } from "./invocation-sidecar.js";
 import { CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS, CONTEXT_BUILDER_INTENT_PROFILES, resolveContextBuilderAdapterBudgetInput, } from "./schema.js";
 import { assertNoHighConfidenceSecretsInTask, resolveAllowSecrets, } from "./secrets.js";
 import { CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION, CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION, createContextBuilderReceipt, } from "./receipt.js";
 import { notEvaluatedCoverageReport, } from "./review-coverage.js";
-import { isContextBuilderRunCommitted, evictWorkflowContextRuns, promoteContextBuilderRun, resolveContextBuilderRunPaths, withContextBuilderRunMutationLease, } from "./storage.js";
+import { ContextBuilderActiveRunClaimConflictError, ContextBuilderAncillaryPromotionError, ContextBuilderCommittedRunChangedError, ContextBuilderRunClaimConflictError, evictWorkflowContextRuns, isContextBuilderRunCommitted, resolveContextBuilderRunPaths, withCommittedContextBuilderRunMutationLease, withPromotedContextBuilderRun, } from "./storage.js";
 import { ContextBuilderLifecycleController, ContextBuilderLifecycleObserverError, } from "./lifecycle-observer.js";
 export function createWorkflowContextBuilderRunner(options = {}) {
     const cb = options.handleContextBuilder ?? handleContextBuilder;
@@ -57,6 +58,7 @@ export function createWorkflowContextBuilderRunner(options = {}) {
     const discoveryAlgorithmVersion = options.discoveryAlgorithmVersion ?? CONTEXT_DISCOVERY_ALGORITHM_VERSION;
     const delegatePromptVersion = options.delegatePromptVersion ?? CONTEXT_DELEGATE_PROMPT_VERSION;
     const registry = options.registry;
+    const syncInvocationSnapshotDirectory = options.syncInvocationSnapshotDirectory ?? syncDirectoryEntry;
     return {
         assertRootsAllowed(roots) {
             assertExplicitRootsWithinAllowed(roots);
@@ -138,31 +140,34 @@ export function createWorkflowContextBuilderRunner(options = {}) {
                     const postSig = await workspaceSignature(mapped.roots);
                     throwIfAborted(opts.signal);
                     if (postSig === preSig) {
-                        const hit = await withContextBuilderRunMutationLease(cache.targetStorage, async () => {
-                            // The unleased probe above is only an optimization. Pruning may
-                            // win before this lease is acquired, so re-check under the lock
-                            // before reading the manifest or materializing any artifact.
-                            if (!await isContextBuilderRunCommitted(cache.targetStorage.runDir)) {
-                                return undefined;
-                            }
-                            // Refresh directory mtime so LRU eviction treats this as recently used.
-                            try {
-                                const now = new Date();
-                                await utimes(cache.targetStorage.runDir, now, now);
-                            }
-                            catch {
-                                // best-effort — a hit must not fail because utimes failed
-                            }
-                            return await synthesizePreflightResultFromCommittedRun({
-                                storage: cache.targetStorage,
-                                runDir: input.runDir,
-                                keyPrefix: cache.keyPrefix,
-                                schemaVersion: effectiveSchemaVersion,
-                                budgetCaps: mapped.budget,
-                                includeSelectedContext,
-                                ...(lifecycle == null ? {} : { lifecycle }),
+                        let hit;
+                        try {
+                            hit = await withCommittedContextBuilderRunMutationLease(cache.targetStorage, async () => {
+                                // Refresh directory mtime so LRU eviction treats this as recently used.
+                                try {
+                                    const now = new Date();
+                                    await utimes(cache.targetStorage.runDir, now, now);
+                                }
+                                catch {
+                                    // best-effort — a hit must not fail because utimes failed
+                                }
+                                return await synthesizePreflightResultFromCommittedRun({
+                                    storage: cache.targetStorage,
+                                    runDir: input.runDir,
+                                    keyPrefix: cache.keyPrefix,
+                                    schemaVersion: effectiveSchemaVersion,
+                                    budgetCaps: mapped.budget,
+                                    includeSelectedContext,
+                                    syncInvocationSnapshotDirectory,
+                                    ...(lifecycle == null ? {} : { lifecycle }),
+                                });
                             });
-                        });
+                        }
+                        catch (error) {
+                            if (!(error instanceof ContextBuilderCommittedRunChangedError)) {
+                                throw error;
+                            }
+                        }
                         if (hit !== undefined) {
                             await lifecycle?.complete(workflowLifecycleTerminalStatus(hit), {
                                 artifactRunId: hit.source_run_id,
@@ -193,152 +198,188 @@ export function createWorkflowContextBuilderRunner(options = {}) {
                 });
                 const tempId = runIdFactory();
                 const tempInput = { ...mapped, run_id: tempId };
-                const response = await cb(tempInput, {
-                    runsDir,
-                    semaphore,
-                    ...(registry == null ? {} : { registry }),
-                    ...(input.allowRootWideDiscovery == null
-                        ? {}
-                        : { allowRootWideDiscovery: input.allowRootWideDiscovery }),
-                    ...(opts.signal == null ? {} : { signal: opts.signal }),
-                    ...(lifecycle == null ? {} : { lifecycleController: lifecycle }),
-                    ...(preflightSessionLogContext == null
-                        ? {}
-                        : { sessionLogContext: preflightSessionLogContext }),
-                });
-                throwIfAborted(opts.signal);
-                const receipt = parseReceiptResponse(response);
                 const tempStorage = resolveContextBuilderRunPaths(runsDir, tempId);
                 // The id of the run this call will return as its live source. Eviction in
                 // the finally must protect it so small/zero retention bounds cannot delete
                 // the run whose source_artifact_dir we are about to hand back.
                 let liveSourceRunId = tempId;
-                try {
-                    const tempManifest = await readManifest(tempStorage.manifestJson);
-                    // Degraded fallback selections (delegate failure_policy:"fallback") must
-                    // NEVER enter the shared wfctx cache: a cached fallback would be replayed
-                    // for a later fail-closed failure_policy:"fail" request (silently
-                    // succeeding instead of failing) and would mask genuine delegated
-                    // successes. Not caching also lets a later identical request retry
-                    // delegation rather than reusing a stale degraded bundle. The manifest
-                    // is the authoritative persisted source; fall back to the receipt.
-                    const fallbackUsed = tempManifest.delegate?.fallback_used === true ||
-                        receipt.delegate?.fallback_used === true;
-                    const selectedPaths = await resolveSelectedContextPaths(tempManifest, mapped.roots);
-                    const gate = await evaluatePostCbPromotionGate({
-                        roots: mapped.roots,
-                        selectedPaths,
-                        workspaceSignature,
-                        signatureCoveredPaths,
-                    });
+                const consumeCommittedRun = async (response, storageOps) => {
                     throwIfAborted(opts.signal);
-                    if (!fallbackUsed && gate?.selectedFilesCovered === true && gate.postSig === preSig) {
-                        try {
-                            await lifecycle?.transition("materializing");
-                            const promoted = await promoteContextBuilderRun(tempStorage.runDir, cache.wfctxId);
-                            // Promote succeeded and renamed temp → wfctx: protect the wfctx run
-                            // immediately so a later throw (e.g. copyBundleArtifactsIntoRun) can
-                            // never leave the freshly-promoted run unprotected against zero/small
-                            // retention eviction in the finally.
-                            liveSourceRunId = cache.wfctxId;
-                            // Copy from the PROMOTED wfctx run (the temp dir is now deleted) so
-                            // the fanned manifest's run_id matches the returned source_run_id and
-                            // its artifact paths point at live files.
-                            const promotedManifest = await readManifest(promoted.manifestJson);
-                            const resultBeforeMaterialization = buildPreflightResult({
-                                receipt: createReceiptFromManifest(promotedManifest, promoted),
-                                sourceRunId: cache.wfctxId,
-                                sourceArtifactDir: promoted.runDir,
-                                cache: {
-                                    hit: false,
-                                    write: true,
-                                    target_id: cache.wfctxId,
-                                    key_prefix: cache.keyPrefix,
-                                },
-                                copiedPaths: [],
-                                schemaVersion: effectiveSchemaVersion,
-                                observability: preflightObservabilityFromManifest(tempManifest, mapped.budget),
-                                coverage: coverageFromManifest(tempManifest),
-                            });
-                            const copiedPaths = await copyBundleArtifactsIntoRun(promotedManifest.artifacts, input.runDir, {
-                                includeSelectedContext,
-                                ...(lifecycle == null
-                                    ? {}
-                                    : {
-                                        beforeManifestCommit: async () => {
-                                            await lifecycle?.transition("committing", {
-                                                artifactRunId: resultBeforeMaterialization.source_run_id,
-                                                cache: {
-                                                    lookup: "miss",
-                                                    write: "written",
-                                                    reason_code: cacheReason,
-                                                },
-                                                ...workflowResultLifecyclePatch(resultBeforeMaterialization, lifecycle),
-                                            });
+                    const receipt = parseReceiptResponse(response);
+                    return await withCommittedContextBuilderRunMutationLease(tempStorage, async (sourceOps) => {
+                        const tempManifest = await readManifest(tempStorage.manifestJson, sourceOps);
+                        // Degraded fallback selections (delegate failure_policy:"fallback") must
+                        // NEVER enter the shared wfctx cache: a cached fallback would be replayed
+                        // for a later fail-closed failure_policy:"fail" request (silently
+                        // succeeding instead of failing) and would mask genuine delegated
+                        // successes. Not caching also lets a later identical request retry
+                        // delegation rather than reusing a stale degraded bundle. The same
+                        // holds for a delegated selection that proceeded with external
+                        // evidence gaps (isDelegateDegradedForCache). The manifest is the
+                        // authoritative persisted source; fall back to the receipt.
+                        const delegateDegraded = isDelegateDegradedForCache(tempManifest.delegate) ||
+                            isDelegateDegradedForCache(receipt.delegate);
+                        const selectedPaths = await resolveSelectedContextPaths(tempManifest, mapped.roots);
+                        const gate = await evaluatePostCbPromotionGate({
+                            roots: mapped.roots,
+                            selectedPaths,
+                            workspaceSignature,
+                            signatureCoveredPaths,
+                        });
+                        throwIfAborted(opts.signal);
+                        if (!delegateDegraded
+                            && gate?.selectedFilesCovered === true
+                            && gate.postSig === preSig) {
+                            try {
+                                await lifecycle?.transition("materializing");
+                                return await withPromotedContextBuilderRun(tempStorage.runDir, cache.wfctxId, async (promoted, targetOps) => {
+                                    // Promotion completed under source→target locks. Keep the target
+                                    // lease through this authoritative manifest read and final copy.
+                                    liveSourceRunId = cache.wfctxId;
+                                    const promotedManifest = await readManifest(promoted.manifestJson, targetOps);
+                                    const resultBeforeMaterialization = buildPreflightResult({
+                                        receipt: createReceiptFromManifest(promotedManifest, promoted),
+                                        sourceRunId: cache.wfctxId,
+                                        sourceArtifactDir: promoted.runDir,
+                                        cache: {
+                                            hit: false,
+                                            write: true,
+                                            target_id: cache.wfctxId,
+                                            key_prefix: cache.keyPrefix,
                                         },
-                                    }),
-                            });
-                            const result = {
-                                ...resultBeforeMaterialization,
-                                copied_paths: copiedPaths,
-                            };
-                            await lifecycle?.complete(workflowLifecycleTerminalStatus(result), {
-                                artifactRunId: result.source_run_id,
-                                ...workflowResultLifecyclePatch(result, lifecycle),
-                            });
-                            return result;
-                        }
-                        catch (error) {
-                            if (!isPromoteClaimConflict(error)) {
-                                throw error;
+                                        copiedPaths: [],
+                                        schemaVersion: effectiveSchemaVersion,
+                                        observability: preflightObservabilityFromManifest(tempManifest, mapped.budget),
+                                        coverage: coverageFromManifest(tempManifest),
+                                    });
+                                    const copiedPaths = await materializeWorkflowContext({
+                                        artifacts: promotedManifest.artifacts,
+                                        sourceRunDir: promoted.runDir,
+                                        workflowRunDir: input.runDir,
+                                        includeSelectedContext,
+                                        syncInvocationSnapshotDirectory,
+                                        ...(lifecycle == null
+                                            ? {}
+                                            : { contextRunId: lifecycle.contextRunId }),
+                                        ...(lifecycle == null
+                                            ? {}
+                                            : {
+                                                beforeManifestCommit: async () => {
+                                                    await lifecycle?.transition("committing", {
+                                                        artifactRunId: resultBeforeMaterialization.source_run_id,
+                                                        cache: {
+                                                            lookup: "miss",
+                                                            write: "written",
+                                                            reason_code: cacheReason,
+                                                        },
+                                                        ...workflowResultLifecyclePatch(resultBeforeMaterialization, lifecycle),
+                                                    });
+                                                },
+                                            }),
+                                    });
+                                    const result = {
+                                        ...resultBeforeMaterialization,
+                                        copied_paths: copiedPaths,
+                                    };
+                                    await lifecycle?.complete(workflowLifecycleTerminalStatus(result), {
+                                        artifactRunId: result.source_run_id,
+                                        ...workflowResultLifecyclePatch(result, lifecycle),
+                                    });
+                                    return result;
+                                }, sourceOps);
+                            }
+                            catch (error) {
+                                if (error instanceof ContextBuilderAncillaryPromotionError) {
+                                    logger.warn({
+                                        reason_code: error.reasonCode,
+                                        source_run_id: tempId,
+                                    }, "workflow context_builder cache promotion skipped because invocation audit ancillary promotion failed");
+                                }
+                                else if (!isPromoteClaimConflict(error)) {
+                                    throw error;
+                                }
                             }
                         }
-                    }
-                    // Non-promote (or promote-claim-conflict) path: copy from the surviving
-                    // temp run, which is the authoritative source for the returned id.
-                    await lifecycle?.transition("materializing");
-                    const resultBeforeMaterialization = buildPreflightResult({
-                        receipt: createReceiptFromManifest(tempManifest, tempStorage),
-                        sourceRunId: tempId,
-                        sourceArtifactDir: tempStorage.runDir,
-                        cache: {
-                            hit: false,
-                            write: false,
-                            target_id: null,
-                            key_prefix: cache.keyPrefix,
-                        },
-                        copiedPaths: [],
-                        schemaVersion: effectiveSchemaVersion,
-                        observability: preflightObservabilityFromManifest(tempManifest, mapped.budget),
-                        coverage: coverageFromManifest(tempManifest),
-                    });
-                    const copiedPaths = await copyBundleArtifactsIntoRun(tempManifest.artifacts, input.runDir, {
-                        includeSelectedContext,
-                        ...(lifecycle == null
+                        // Non-promote (or promote-claim-conflict) path: copy from the surviving
+                        // temp run, which is the authoritative source for the returned id.
+                        await lifecycle?.transition("materializing");
+                        const resultBeforeMaterialization = buildPreflightResult({
+                            receipt: createReceiptFromManifest(tempManifest, tempStorage),
+                            sourceRunId: tempId,
+                            sourceArtifactDir: tempStorage.runDir,
+                            cache: {
+                                hit: false,
+                                write: false,
+                                target_id: null,
+                                key_prefix: cache.keyPrefix,
+                            },
+                            copiedPaths: [],
+                            schemaVersion: effectiveSchemaVersion,
+                            observability: preflightObservabilityFromManifest(tempManifest, mapped.budget),
+                            coverage: coverageFromManifest(tempManifest),
+                        });
+                        const copiedPaths = await materializeWorkflowContext({
+                            artifacts: tempManifest.artifacts,
+                            sourceRunDir: tempStorage.runDir,
+                            workflowRunDir: input.runDir,
+                            includeSelectedContext,
+                            syncInvocationSnapshotDirectory,
+                            ...(lifecycle == null
+                                ? {}
+                                : { contextRunId: lifecycle.contextRunId }),
+                            ...(lifecycle == null
+                                ? {}
+                                : {
+                                    beforeManifestCommit: async () => {
+                                        await lifecycle?.transition("committing", {
+                                            artifactRunId: resultBeforeMaterialization.source_run_id,
+                                            cache: {
+                                                lookup: "miss",
+                                                write: "skipped",
+                                                reason_code: cacheReason,
+                                            },
+                                            ...workflowResultLifecyclePatch(resultBeforeMaterialization, lifecycle),
+                                        });
+                                    },
+                                }),
+                        });
+                        const result = {
+                            ...resultBeforeMaterialization,
+                            copied_paths: copiedPaths,
+                        };
+                        await lifecycle?.complete(workflowLifecycleTerminalStatus(result), {
+                            artifactRunId: result.source_run_id,
+                            ...workflowResultLifecyclePatch(result, lifecycle),
+                        });
+                        return result;
+                    }, storageOps);
+                };
+                let retainedResult;
+                try {
+                    const response = await cb(tempInput, {
+                        runsDir,
+                        semaphore,
+                        ...(registry == null ? {} : { registry }),
+                        ...(input.allowRootWideDiscovery == null
                             ? {}
-                            : {
-                                beforeManifestCommit: async () => {
-                                    await lifecycle?.transition("committing", {
-                                        artifactRunId: resultBeforeMaterialization.source_run_id,
-                                        cache: {
-                                            lookup: "miss",
-                                            write: "skipped",
-                                            reason_code: cacheReason,
-                                        },
-                                        ...workflowResultLifecyclePatch(resultBeforeMaterialization, lifecycle),
-                                    });
-                                },
-                            }),
-                    });
-                    const result = {
-                        ...resultBeforeMaterialization,
-                        copied_paths: copiedPaths,
-                    };
-                    await lifecycle?.complete(workflowLifecycleTerminalStatus(result), {
-                        artifactRunId: result.source_run_id,
-                        ...workflowResultLifecyclePatch(result, lifecycle),
+                            : { allowRootWideDiscovery: input.allowRootWideDiscovery }),
+                        ...(opts.signal == null ? {} : { signal: opts.signal }),
+                        ...(lifecycle == null ? {} : { lifecycleController: lifecycle }),
+                        ...(preflightSessionLogContext == null
+                            ? {}
+                            : { sessionLogContext: preflightSessionLogContext }),
+                        retainCommittedRun: async (committedResponse, committedStorage, leasedOps) => {
+                            if (committedStorage.runId !== tempStorage.runId
+                                || committedStorage.runDir !== tempStorage.runDir) {
+                                throw new ExecutionError("context_builder retained an unexpected workflow temp run");
+                            }
+                            retainedResult = await consumeCommittedRun(committedResponse, leasedOps);
+                        },
                     });
-                    return result;
+                    if (retainedResult !== undefined) {
+                        return retainedResult;
+                    }
+                    return await consumeCommittedRun(response);
                 }
                 finally {
                     // Best-effort, prefix-scoped/TTL-guarded eviction on every completed
@@ -391,11 +432,141 @@ export function createWorkflowContextBuilderRunner(options = {}) {
     };
 }
 /**
- * Subdirectory of the workflow run dir holding the preflight session-log
- * generation sidecar. The dashboard reads this back to locate the preflight's
- * session-log subtree and to pair it with the persisted lifecycle context_run_id.
+ * Subdirectory of the workflow run dir holding operation-scoped preflight
+ * metadata: the session-log generation and immutable invocation snapshots.
  */
 const PREFLIGHT_SESSION_LOG_DIR = ".context-preflight";
+async function materializeWorkflowContext(input) {
+    const copiedPaths = await copyBundleArtifactsIntoRun(input.artifacts, input.workflowRunDir, {
+        includeSelectedContext: input.includeSelectedContext,
+        ...(input.beforeManifestCommit == null
+            ? {}
+            : { beforeManifestCommit: input.beforeManifestCommit }),
+    });
+    if (input.contextRunId !== undefined) {
+        await snapshotWorkflowInvocationAudit({
+            sourceRunDir: input.sourceRunDir,
+            workflowRunDir: input.workflowRunDir,
+            contextRunId: input.contextRunId,
+            syncInvocationSnapshotDirectory: input.syncInvocationSnapshotDirectory,
+        });
+    }
+    return copiedPaths;
+}
+async function snapshotWorkflowInvocationAudit(input) {
+    let source;
+    try {
+        source = await readContextBuilderInvocationAuditSidecar(input.sourceRunDir);
+    }
+    catch (error) {
+        logger.warn({ err: error, source_artifact_dir: input.sourceRunDir }, "workflow context_builder invocation audit snapshot source rejected");
+        return;
+    }
+    if (source === undefined)
+        return;
+    const workflowRunRoot = await realpath(input.workflowRunDir);
+    const preflightDir = await admitExactWorkflowDirectory(workflowRunRoot, PREFLIGHT_SESSION_LOG_DIR, "workflow context_builder invocation audit snapshot directory");
+    const admittedSnapshotDir = await admitExactWorkflowDirectory(preflightDir, input.contextRunId, "workflow context_builder invocation audit snapshot directory");
+    assertContainedPath(workflowRunRoot, admittedSnapshotDir, "workflow context_builder invocation audit snapshot escaped the workflow run");
+    const target = join(admittedSnapshotDir, CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME);
+    const temp = join(admittedSnapshotDir, `.${CONTEXT_BUILDER_INVOCATION_AUDIT_FILENAME}.${process.pid}.${randomUUID()}.tmp`);
+    let ownsTemp = false;
+    let publicationAccepted = false;
+    try {
+        let handle;
+        try {
+            handle = await open(temp, "wx", 0o600);
+            ownsTemp = true;
+            await handle.writeFile(source.serialized, "utf8");
+            await handle.chmod(0o600);
+            await handle.sync();
+        }
+        finally {
+            await handle?.close();
+        }
+        try {
+            await link(temp, target);
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "EEXIST")
+                throw error;
+            let incumbent;
+            try {
+                incumbent = await readContextBuilderInvocationAuditSidecar(admittedSnapshotDir);
+            }
+            catch (error) {
+                if (!isContextBuilderInvocationAuditSidecarProvenInvalid(error)) {
+                    throw error;
+                }
+                logger.warn({ err: error, incumbent_path: target }, "workflow context_builder invocation audit snapshot incumbent rejected; preserving existing entry");
+                return;
+            }
+            if (incumbent?.serialized !== source.serialized) {
+                throw new ExecutionError("workflow context_builder invocation audit snapshot conflicts with existing bytes");
+            }
+        }
+        publicationAccepted = true;
+    }
+    finally {
+        if (ownsTemp) {
+            try {
+                await rm(temp, { force: true });
+            }
+            catch (error) {
+                logger.warn({ err: error, temporary_path: temp }, "workflow context_builder invocation audit snapshot temp cleanup failed");
+            }
+        }
+        if (publicationAccepted) {
+            await syncSnapshotDirectoriesBestEffort([admittedSnapshotDir, preflightDir, workflowRunRoot], input.syncInvocationSnapshotDirectory);
+        }
+    }
+}
+async function syncDirectoryEntry(path) {
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function syncSnapshotDirectoriesBestEffort(directories, syncDirectory) {
+    for (const directory of directories) {
+        try {
+            await syncDirectory(directory);
+        }
+        catch (error) {
+            logger.warn({ err: error, directory }, "workflow context_builder invocation audit snapshot directory sync failed");
+        }
+    }
+}
+async function admitExactWorkflowDirectory(parent, name, label) {
+    const path = join(parent, name);
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "EEXIST")
+            throw error;
+    }
+    try {
+        const [stats, canonicalPath] = await Promise.all([
+            lstat(path),
+            realpath(path),
+        ]);
+        if (stats.isSymbolicLink() ||
+            !stats.isDirectory() ||
+            canonicalPath !== path) {
+            throw new ExecutionError(`${label} is unsafe`);
+        }
+        return path;
+    }
+    catch (error) {
+        if (error instanceof ExecutionError)
+            throw error;
+        throw new ExecutionError(`${label} is unsafe`);
+    }
+}
 /**
  * Create-or-read the preflight session-log generation sidecar under the workflow
  * run dir, then pair it with the controller-minted operation id. Create-or-read
@@ -405,8 +576,8 @@ const PREFLIGHT_SESSION_LOG_DIR = ".context-preflight";
  */
 async function resolvePreflightSessionLogContext(runDir, contextRunId) {
     try {
-        const sidecarDir = join(runDir, PREFLIGHT_SESSION_LOG_DIR);
-        await mkdir(sidecarDir, { recursive: true, mode: 0o700 });
+        const workflowRunRoot = await realpath(runDir);
+        const sidecarDir = await admitExactWorkflowDirectory(workflowRunRoot, PREFLIGHT_SESSION_LOG_DIR, "workflow context_builder preflight metadata directory");
         const existing = await readSessionLogGeneration(sidecarDir);
         const contextGeneration = existing.kind === "available"
             ? existing.sessionLogGeneration
@@ -433,6 +604,17 @@ function workflowLifecycleExecutionConfig(input) {
         finalizer: { configured: true, enabled: finalizerEnabled },
     };
 }
+/**
+ * A delegate bundle that is degraded — a deterministic fallback, or a
+ * delegated selection that proceeded with known external evidence gaps
+ * (status "partial", fallback_used false, external_gap_policy "degrade") — is
+ * never promoted into or served from the wfctx cache. The gap policy is not
+ * in the cache key, so a cached degraded bundle could otherwise satisfy a later
+ * fail-closed request.
+ */
+function isDelegateDegradedForCache(delegate) {
+    return delegate?.fallback_used === true || delegate?.status === "partial";
+}
 function workflowLifecycleTerminalStatus(result) {
     return result.delegate?.fallback_used === true || result.status === "partial"
         ? "partial"
@@ -624,7 +806,9 @@ async function synthesizePreflightResultFromCommittedRun(input) {
         // artifact, or a future code path. Treat it as a cache MISS (return undefined,
         // the same value the ENOENT/not-usable case returns) so runOrReuse falls
         // through and re-runs the builder; a real "fail" policy then fails closed.
-        if (manifest.delegate?.fallback_used === true) {
+        // A degraded external-gap bundle (status "partial" without fallback) is
+        // refused the same way.
+        if (isDelegateDegradedForCache(manifest.delegate)) {
             return undefined;
         }
         const receipt = createReceiptFromManifest(manifest, input.storage);
@@ -649,8 +833,15 @@ async function synthesizePreflightResultFromCommittedRun(input) {
             ...workflowResultLifecyclePatch(resultBeforeMaterialization, input.lifecycle, true),
         });
         await input.lifecycle?.transition("materializing");
-        const copiedPaths = await copyBundleArtifactsIntoRun(manifest.artifacts, input.runDir, {
+        const copiedPaths = await materializeWorkflowContext({
+            artifacts: manifest.artifacts,
+            sourceRunDir: input.storage.runDir,
+            workflowRunDir: input.runDir,
             includeSelectedContext: input.includeSelectedContext,
+            syncInvocationSnapshotDirectory: input.syncInvocationSnapshotDirectory,
+            ...(input.lifecycle == null
+                ? {}
+                : { contextRunId: input.lifecycle.contextRunId }),
             ...(input.lifecycle == null
                 ? {}
                 : {
@@ -853,8 +1044,8 @@ function nonNegativeInteger(value) {
         ? value
         : 0;
 }
-async function readManifest(manifestPath) {
-    return JSON.parse(await readFile(manifestPath, "utf8"));
+async function readManifest(manifestPath, ops) {
+    return JSON.parse(await (ops?.readFile ?? readFile)(manifestPath, "utf8"));
 }
 async function resolveSelectedContextPaths(manifest, roots) {
     const selected = Array.isArray(manifest["selected_context"])
@@ -917,9 +1108,8 @@ async function normalizeExistingPath(path) {
     }
 }
 function isPromoteClaimConflict(error) {
-    return (error instanceof InvalidParamsError
-        && error.message.startsWith("context_builder run_id already exists:")) || (error instanceof ExecutionError
-        && error.message.startsWith("context_builder run_id conflicts with an incomplete or active run:"));
+    return error instanceof ContextBuilderRunClaimConflictError
+        || error instanceof ContextBuilderActiveRunClaimConflictError;
 }
 function throwIfAborted(signal) {
     if (signal?.aborted === true) {