clinkx 0.3.0 → 1.1.0

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

@@ -0,0 +1,1241 @@
+import { randomUUID } from "node:crypto";
+import { realpathSync, statSync } from "node:fs";
+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)
+//
+// The next four imports pull cache-key, preflight-contract, config, and
+// workspace-signature helpers from the COMPILED output of the sibling
+// `clinkx-workflows` package rather than from a published entry point. This is
+// deliberate and safe:
+//
+//   - The dependency arrow points one way: root -> clinkx-workflows. The
+//     workflows package defines only the `ContextBuilderRunner` callback
+//     interface and never statically imports the root `context-builder/`
+//     modules, so there is no import cycle. See docs/architecture.md, "Module
+//     boundary (no dependency cycle)".
+//   - `clinkx-workflows` is a separate tsc project with no package `exports`
+//     map; its public runtime surface is its `dist/*.js` files. Importing its
+//     source `.ts` would violate the NodeNext + `.js`-extension ESM contract.
+//
+// BUILD ORDER: `clinkx-workflows/dist` MUST be built before the root package is
+// built or run. `npm run build:all` enforces this (clinkx-workflows first, then
+// root). A bare `npm run build` assumes dist already exists; a missing dist
+// surfaces as ERR_MODULE_NOT_FOUND at import time, not a compile error.
+// ---------------------------------------------------------------------------
+import { computeCacheKey, computeInputsHash, deriveWfctxId, } from "../../clinkx-workflows/dist/context-cache-key.js";
+import { resolveWorkspaceRoot as resolveWorkflowWorkspaceRoot } from "../../clinkx-workflows/dist/config.js";
+import { createSessionLogGeneration, readSessionLogGeneration, } from "../../clinkx-workflows/dist/dashboard/session-log-identity.js";
+import { getSignatureCoveredPaths, workspaceSignature as computeWorkspaceSignature, } from "../../clinkx-workflows/dist/workspace-signature.js";
+import { isArtifactOnlyAllowedRootEntry, isPathWithinAllowedRoots, } from "../allowed-roots.js";
+import { CancellationError, ExecutionError, InvalidParamsError } from "../errors.js";
+import { logger } from "../logger.js";
+import { getCurrentAllowedRoots } from "../paths.js";
+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 { 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;
+    // Default to the SHARED process-wide context_builder gate so workflow
+    // preflight, standalone context_builder, and refine_context_run all contend
+    // for one CLINKX_CONTEXT_BUILDER_MAX_CONCURRENT permit pool. Tests may inject
+    // their own semaphore for isolation.
+    const semaphore = options.semaphore ?? getSharedContextBuilderSemaphore();
+    const runIdFactory = options.runIdFactory ?? generateWorkflowPreflightRunId;
+    const workspaceRootResolver = options.resolveWorkspaceRoot ?? resolveWorkflowWorkspaceRoot;
+    const workspaceSignature = options.workspaceSignature ?? computeWorkspaceSignature;
+    const signatureCoveredPaths = options.getSignatureCoveredPaths ?? getSignatureCoveredPaths;
+    const rendererVersion = options.rendererVersion ?? CONTEXT_BUILDER_RENDERER_VERSION;
+    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);
+        },
+        assertTaskSecretsAllowed(variables) {
+            const rawFlag = variables["cb_allow_secrets"];
+            const explicit = typeof rawFlag === "boolean" ? rawFlag : undefined;
+            if (resolveAllowSecrets(explicit)) {
+                return;
+            }
+            for (const key of ["cb_task", "user_request"]) {
+                const value = variables[key];
+                if (typeof value === "string" && value.length > 0) {
+                    assertNoHighConfidenceSecretsInTask(value);
+                }
+            }
+        },
+        async runOrReuse(input, opts) {
+            let lifecycle;
+            try {
+                throwIfAborted(opts.signal);
+                const mappedInput = await mapPreflightContextInput(input, {
+                    resolveWorkspaceRoot: workspaceRootResolver,
+                });
+                const mapped = input.context_budget_adapter == null ||
+                    input.context_budget_adapter.trim() === ""
+                    ? mappedInput
+                    : {
+                        ...mappedInput,
+                        budget: resolveContextBuilderAdapterBudgetInput({
+                            adapterDefaults: resolveAdapterBudgetDefaults(registry, input.context_budget_adapter),
+                            profile: mappedInput.profile,
+                            explicit: mappedInput.budget,
+                        }),
+                    };
+                const lifecycleInjection = options.lifecycleFactory?.(input);
+                lifecycle = lifecycleInjection == null
+                    ? undefined
+                    : new ContextBuilderLifecycleController({
+                        operationKind: "workflow_preflight",
+                        execution: workflowLifecycleExecutionConfig(mapped),
+                        observer: lifecycleInjection.observer,
+                        ...(lifecycleInjection.origin == null
+                            ? {}
+                            : { origin: lifecycleInjection.origin }),
+                        ...(options.lifecycleNow == null
+                            ? {}
+                            : { now: options.lifecycleNow }),
+                    });
+                await lifecycle?.transition("resolving");
+                // The controller has now minted the preflight operation id
+                // (lifecycle.contextRunId). Pair it with a generation sidecar created under
+                // the workflow run dir so the dashboard can later locate the preflight's
+                // session-log subtree. Only the injected-lifecycle (workflow) path builds
+                // this; the standalone path derives its own identity from its journal.
+                const preflightSessionLogContext = lifecycle == null
+                    ? undefined
+                    : await resolvePreflightSessionLogContext(input.runDir, lifecycle.contextRunId);
+                const cacheInput = {
+                    ...mapped,
+                    roots: await normalizeCacheRoots(mapped.roots),
+                };
+                const includeSelectedContext = input.includeSelectedContext === true;
+                const effectiveSchemaVersion = mapped.delegate.enabled === true
+                    ? CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION
+                    : CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION;
+                const cacheSchemaVersion = options.cbSchemaVersion ?? effectiveSchemaVersion;
+                const runsDir = await resolveContextBuilderRunsDir(options.runsDir);
+                let preSig = await workspaceSignature(mapped.roots);
+                throwIfAborted(opts.signal);
+                let cache = deriveCacheCoordinates(cacheInput, preSig, runsDir, {
+                    rendererVersion,
+                    cbSchemaVersion: cacheSchemaVersion,
+                    discoveryAlgorithmVersion,
+                    delegatePromptVersion,
+                });
+                let cacheReason = "cache_miss";
+                if (await isContextBuilderRunCommitted(cache.targetStorage.runDir)) {
+                    const postSig = await workspaceSignature(mapped.roots);
+                    throwIfAborted(opts.signal);
+                    if (postSig === preSig) {
+                        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,
+                                ...workflowResultLifecyclePatch(hit, lifecycle, true),
+                            });
+                            return hit;
+                        }
+                        cacheReason = "cache_stale";
+                    }
+                    else {
+                        cacheReason = "cache_stale";
+                        preSig = postSig;
+                        cache = deriveCacheCoordinates(cacheInput, preSig, runsDir, {
+                            rendererVersion,
+                            cbSchemaVersion: cacheSchemaVersion,
+                            discoveryAlgorithmVersion,
+                            delegatePromptVersion,
+                        });
+                    }
+                }
+                await lifecycle?.transition("cache_lookup", {
+                    cache: {
+                        lookup: "miss",
+                        write: "not_attempted",
+                        reason_code: cacheReason,
+                    },
+                    reasonCodes: [cacheReason],
+                });
+                const tempId = runIdFactory();
+                const tempInput = { ...mapped, run_id: tempId };
+                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;
+                const consumeCommittedRun = async (response, storageOps) => {
+                    throwIfAborted(opts.signal);
+                    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,
+                                        },
+                                        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 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
+                            ? {}
+                            : { 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);
+                        },
+                    });
+                    if (retainedResult !== undefined) {
+                        return retainedResult;
+                    }
+                    return await consumeCommittedRun(response);
+                }
+                finally {
+                    // Best-effort, prefix-scoped/TTL-guarded eviction on every completed
+                    // MISS path (promote and non-promote). The active source run of this
+                    // call is protected so zero/small retention bounds cannot self-delete
+                    // the run whose source_artifact_dir we just returned.
+                    await evictWorkflowContextRuns(runsDir, {
+                        protectedRunIds: [liveSourceRunId],
+                    })
+                        .then((eviction) => {
+                        if (eviction.failed > 0) {
+                            logger.warn({ runsDir, eviction }, "workflow context_builder cache eviction had delete failures");
+                        }
+                    })
+                        .catch((err) => {
+                        logger.warn({ err, runsDir }, "workflow context_builder cache eviction failed");
+                    });
+                }
+            }
+            catch (error) {
+                if (lifecycle != null && !(error instanceof ContextBuilderLifecycleObserverError)) {
+                    const cancelled = error instanceof CancellationError || opts.signal?.aborted === true;
+                    const delegateFailed = workflowDelegateExecutionActive(lifecycle);
+                    await lifecycle.fail(cancelled ? "cancelled" : "failed", {
+                        ...workflowTerminalExecutionPatch(lifecycle, cancelled),
+                        reasonCodes: [
+                            cancelled
+                                ? "operation_cancelled"
+                                : delegateFailed
+                                    ? "delegate_failed"
+                                    : "internal_failure",
+                        ],
+                        ...(!cancelled && delegateFailed
+                            ? {
+                                fallback: {
+                                    status: "failed",
+                                    reason_code: "delegate_failed",
+                                },
+                            }
+                            : {}),
+                    });
+                }
+                // Rethrow the ORIGINAL error object, never a wrapper: markers set by
+                // the handler (e.g. ExecutionError.failureClass:"transient" on a
+                // delegate timeout) must reach the workflow engine's failure
+                // classifier intact.
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * 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
+ * (rather than exclusive-create) keeps the generation stable across retries of
+ * the same run. Best-effort: any failure resolves to undefined, and the preflight
+ * renders without a `[ log ]` affordance (the prior telemetry-only contract).
+ */
+async function resolvePreflightSessionLogContext(runDir, contextRunId) {
+    try {
+        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
+            : await createSessionLogGeneration(sidecarDir);
+        return { contextRunId, contextGeneration };
+    }
+    catch {
+        return undefined;
+    }
+}
+function workflowLifecycleExecutionConfig(input) {
+    if (input.delegate.enabled !== true) {
+        return {
+            curator: { configured: false, enabled: false },
+            finalizer: { configured: false, enabled: false },
+        };
+    }
+    const finalizerEnabled = input.delegate.finalizer.enabled ??
+        (input.profile == null
+            ? true
+            : CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS[input.profile].finalizer_enabled);
+    return {
+        curator: { configured: true, enabled: true },
+        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"
+        : "succeeded";
+}
+function workflowResultLifecyclePatch(result, lifecycle, cacheHit = false) {
+    const coverage = result.coverage ?? notEvaluatedCoverageReport();
+    const required = coverage.required_when_available.length;
+    const missing = coverage.missing_required.length;
+    const snapshot = lifecycle?.snapshot;
+    const executionPatch = cacheHit
+        ? {
+            ...(snapshot?.curator.effective_enabled === true
+                ? { curatorStatus: "skipped" }
+                : {}),
+            ...(snapshot?.finalizer.effective_enabled === true
+                ? { finalizerStatus: "skipped" }
+                : {}),
+        }
+        : result.delegate?.fallback_used === true
+            ? {
+                ...(snapshot?.curator.effective_enabled === true
+                    ? { curatorStatus: "failed" }
+                    : {}),
+                ...(snapshot?.finalizer.effective_enabled === true
+                    ? { finalizerStatus: "skipped" }
+                    : {}),
+                fallback: {
+                    status: "used",
+                    reason_code: "delegate_fallback",
+                },
+                reasonCodes: ["delegate_fallback"],
+            }
+            : {
+                ...(snapshot?.curator.effective_enabled === true &&
+                    snapshot.curator.execution_status === "pending"
+                    ? { curatorStatus: "succeeded" }
+                    : {}),
+                ...(snapshot?.finalizer.effective_enabled === true &&
+                    snapshot.finalizer.execution_status === "pending"
+                    ? { finalizerStatus: "succeeded" }
+                    : {}),
+            };
+    return {
+        ...executionPatch,
+        counts: {
+            files_seen: cacheHit ? 0 : result.metrics.files_seen,
+            files_considered: cacheHit ? 0 : result.metrics.files_considered,
+            files_selected: result.metrics.files_selected,
+            files_omitted: cacheHit ? 0 : result.metrics.files_omitted,
+            search_results: cacheHit ? 0 : snapshot?.counts.search_results ?? 0,
+            bytes_read: cacheHit ? 0 : result.metrics.bytes_read,
+            bytes_written: result.metrics.bytes_written,
+        },
+        coverage: {
+            policy: coverage.policy_id,
+            status: coverage.status,
+            required,
+            selected: Math.max(0, required - missing),
+            missing,
+        },
+        ...(coverage.status === "degraded"
+            ? { reasonCodes: [...(executionPatch.reasonCodes ?? []), "coverage_degraded"] }
+            : {}),
+    };
+}
+function workflowTerminalExecutionPatch(lifecycle, cancelled) {
+    const snapshot = lifecycle.snapshot;
+    if (snapshot == null)
+        return {};
+    const terminalStatus = cancelled ? "cancelled" : "failed";
+    return {
+        ...(snapshot.curator.execution_status === "running"
+            ? { curatorStatus: terminalStatus }
+            : snapshot.curator.execution_status === "pending"
+                ? { curatorStatus: "skipped" }
+                : {}),
+        ...(snapshot.finalizer.execution_status === "running"
+            ? { finalizerStatus: terminalStatus }
+            : snapshot.finalizer.execution_status === "pending"
+                ? { finalizerStatus: "skipped" }
+                : {}),
+    };
+}
+function workflowDelegateExecutionActive(lifecycle) {
+    const snapshot = lifecycle.snapshot;
+    return snapshot?.curator.execution_status === "running" ||
+        snapshot?.finalizer.execution_status === "running";
+}
+export async function copyBundleIntoRun(receipt, runDir, options = {}) {
+    return copyBundleArtifactsIntoRun(receipt.artifacts, runDir, options);
+}
+export async function copyBundleArtifactsIntoRun(artifacts, runDir, options = {}) {
+    const runRoot = await realpath(runDir);
+    const contextDir = join(runRoot, "artifacts", "context");
+    await mkdir(contextDir, { recursive: true });
+    const realContextDir = await realpath(contextDir);
+    const bundleDest = await copyArtifactIntoContextDir(await resolveArtifactPath(artifacts, "bundle_md", "bundle.md"), realContextDir, "bundle.md");
+    const selectedContextDest = options.includeSelectedContext === true
+        ? await copyArtifactIntoContextDir(await resolveArtifactPath(artifacts, "selected_context_jsonl", "selected-context.jsonl"), realContextDir, "selected-context.jsonl")
+        : undefined;
+    const manifestSource = await resolveArtifactPath(artifacts, "manifest_json", "manifest.json");
+    await options.beforeManifestCommit?.();
+    const manifestDest = await copyArtifactIntoContextDir(manifestSource, realContextDir, "manifest.json");
+    return selectedContextDest == null
+        ? [bundleDest, manifestDest]
+        : [bundleDest, selectedContextDest, manifestDest];
+}
+export async function mapPreflightContextInput(input, options) {
+    assertExplicitRootsWithinAllowed(input.roots);
+    const task = input.cb_task.trim() === "" ? input.user_request : input.cb_task;
+    const roots = input.roots.length > 0
+        ? [...input.roots]
+        : [await resolveFallbackRoot(options.resolveWorkspaceRoot)];
+    const profile = validateProfile(input.profile);
+    return {
+        task,
+        roots,
+        focus_paths: [...input.focus_paths],
+        include_globs: [...input.include_globs],
+        exclude_globs: [...input.exclude_globs],
+        search_terms: [...input.search_terms],
+        allow_secrets: resolveAllowSecrets(input.allow_secrets),
+        budget: input.budget ?? {},
+        delegate: input.delegate ?? { enabled: false },
+        ...(options.run_id == null ? {} : { run_id: options.run_id }),
+        ...(profile == null ? {} : { profile }),
+    };
+}
+// cb_budget_adapter is intentionally backend-agnostic: this only reads numeric
+// context_builder.budget_defaults and NEVER executes the adapter, so app_server
+// adapters are permitted here even though they are rejected for execution.
+function resolveAdapterBudgetDefaults(registry, name) {
+    const trimmed = name?.trim();
+    if (trimmed == null || trimmed === "") {
+        return {};
+    }
+    if (registry == null) {
+        throw new InvalidParamsError(`cb_budget_adapter "${trimmed}" set but no adapter registry is available`);
+    }
+    const budgetDefaults = registry.resolveAdapter(trimmed).context_builder?.budget_defaults ?? {};
+    return {
+        ...(budgetDefaults.max_estimated_tokens == null
+            ? {}
+            : { max_estimated_tokens: budgetDefaults.max_estimated_tokens }),
+        ...(budgetDefaults.max_files == null
+            ? {}
+            : { max_files: budgetDefaults.max_files }),
+        ...(budgetDefaults.max_scan_files == null
+            ? {}
+            : { max_scan_files: budgetDefaults.max_scan_files }),
+        ...(budgetDefaults.max_bytes_per_file == null
+            ? {}
+            : { max_bytes_per_file: budgetDefaults.max_bytes_per_file }),
+        ...(budgetDefaults.max_total_bytes == null
+            ? {}
+            : { max_total_bytes: budgetDefaults.max_total_bytes }),
+        ...(budgetDefaults.max_search_results == null
+            ? {}
+            : { max_search_results: budgetDefaults.max_search_results }),
+    };
+}
+function deriveCacheCoordinates(mappedInput, workspaceSig, runsDir, versions) {
+    const inputsHash = computeInputsHash(mappedInput);
+    const cacheKey = computeCacheKey({
+        inputsHash,
+        workspaceSig,
+        rendererVersion: versions.rendererVersion,
+        cbSchemaVersion: versions.cbSchemaVersion,
+        discoveryAlgorithmVersion: versions.discoveryAlgorithmVersion,
+        delegatePromptVersion: versions.delegatePromptVersion,
+    });
+    const wfctxId = deriveWfctxId(cacheKey);
+    return {
+        workspaceSig,
+        cacheKey,
+        wfctxId,
+        keyPrefix: cacheKey.slice(0, 16),
+        targetStorage: resolveContextBuilderRunPaths(runsDir, wfctxId),
+    };
+}
+async function synthesizePreflightResultFromCommittedRun(input) {
+    try {
+        const manifest = await readManifest(input.storage.manifestJson);
+        // A committed fallback bundle is degraded (delegate failure_policy:"fallback")
+        // and must NEVER be served, especially to a fail-closed failure_policy:"fail"
+        // request (failure_policy is intentionally not in the cache key). A poisoned
+        // wfctx entry can exist from a mixed-version/older writer, an external/manual
+        // 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.
+        // 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);
+        const resultBeforeMaterialization = buildPreflightResult({
+            receipt,
+            sourceRunId: input.storage.runId,
+            sourceArtifactDir: input.storage.runDir,
+            cache: {
+                hit: true,
+                write: false,
+                target_id: input.storage.runId,
+                key_prefix: input.keyPrefix,
+            },
+            copiedPaths: [],
+            schemaVersion: input.schemaVersion,
+            observability: preflightObservabilityFromManifest(manifest, input.budgetCaps),
+            coverage: coverageFromManifest(manifest),
+        });
+        await input.lifecycle?.transition("cache_lookup", {
+            artifactRunId: resultBeforeMaterialization.source_run_id,
+            cache: { lookup: "hit", write: "skipped" },
+            ...workflowResultLifecyclePatch(resultBeforeMaterialization, input.lifecycle, true),
+        });
+        await input.lifecycle?.transition("materializing");
+        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
+                ? {}
+                : {
+                    beforeManifestCommit: async () => {
+                        await input.lifecycle?.transition("committing");
+                    },
+                }),
+        });
+        return buildPreflightResult({
+            receipt,
+            sourceRunId: input.storage.runId,
+            sourceArtifactDir: input.storage.runDir,
+            cache: {
+                hit: true,
+                write: false,
+                target_id: input.storage.runId,
+                key_prefix: input.keyPrefix,
+            },
+            copiedPaths,
+            schemaVersion: input.schemaVersion,
+            observability: preflightObservabilityFromManifest(manifest, input.budgetCaps),
+            coverage: coverageFromManifest(manifest),
+        });
+    }
+    catch (error) {
+        if (isNodeError(error)
+            && error.code === "ENOENT"
+            && input.lifecycle?.snapshot?.cache.lookup !== "hit") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function createReceiptFromManifest(manifest, storage) {
+    return createContextBuilderReceipt({
+        run_id: storage.runId,
+        status: manifest.status,
+        artifact_dir: storage.artifactDir,
+        artifacts: { ...manifest.artifacts },
+        metrics: manifest.metrics,
+        warnings: [...manifest.warnings],
+        omissions: [...manifest.omissions],
+        ...(manifest.delegate == null ? {} : { delegate: manifest.delegate }),
+    });
+}
+function buildPreflightResult(input) {
+    // The request-derived effective schema (input.schemaVersion) must match the
+    // receipt's own schema. A divergence means a handler-contract violation (e.g.
+    // a delegate-enabled request whose handler returned a no-delegate v1 receipt),
+    // which would otherwise emit schema_version:2 with no delegate metadata. Fail
+    // loudly rather than emit a contradictory result.
+    if (input.schemaVersion !== input.receipt.schema_version) {
+        throw new ExecutionError("context_builder schema mismatch: request-derived schema_version " +
+            `${input.schemaVersion} does not match receipt schema_version ` +
+            `${input.receipt.schema_version}`);
+    }
+    // A delegate schema_version that carries no delegate metadata is contradictory
+    // (a delegated build that lost its delegate provenance). Fail loudly rather
+    // than silently emitting delegate: undefined, which would erase fallback_used.
+    if (input.receipt.schema_version === CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION
+        && input.receipt.delegate == null) {
+        throw new ExecutionError("context_builder receipt has delegate schema_version but no delegate metadata");
+    }
+    const delegate = input.receipt.schema_version === CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION
+        && input.receipt.delegate != null
+        ? {
+            enabled: true,
+            status: input.receipt.delegate.status,
+            fallback_used: input.receipt.delegate.fallback_used,
+        }
+        : undefined;
+    return {
+        receipt: input.receipt,
+        source_run_id: input.sourceRunId,
+        source_artifact_dir: input.sourceArtifactDir,
+        cache: input.cache,
+        schema_version: input.schemaVersion,
+        status: input.receipt.status,
+        copied_paths: input.copiedPaths,
+        coverage: input.coverage,
+        metrics: input.receipt.metrics,
+        warning_count: input.receipt.warnings.length,
+        omission_count: input.receipt.omissions.length,
+        ...(delegate == null ? {} : { delegate }),
+        ...(input.observability == null
+            ? {}
+            : { observability: input.observability }),
+    };
+}
+function preflightObservabilityFromManifest(manifest, budgetCaps) {
+    const raw = manifest["observability"];
+    const record = raw !== null && typeof raw === "object"
+        ? raw
+        : {};
+    return {
+        curator_ms: nullableNonNegativeNumber(record["curator_ms"]),
+        finalizer_ms: nullableNonNegativeNumber(record["finalizer_ms"]),
+        candidate_pool_size: nonNegativeInteger(record["candidate_pool_size"]),
+        delegate_packet_size: nonNegativeInteger(record["delegate_packet_size"]),
+        budget_caps: budgetCapsFromManifest(manifest["budget"], budgetCaps),
+    };
+}
+function coverageFromManifest(manifest) {
+    const value = manifest["coverage"];
+    if (value === null || typeof value !== "object") {
+        return notEvaluatedCoverageReport();
+    }
+    const coverage = value;
+    if (!isCoveragePolicyId(coverage["policy_id"])
+        || !isCoverageStatus(coverage["status"])
+        || !isEvidenceClassArray(coverage["required_when_available"])
+        || !isEvidenceClassArray(coverage["available"])
+        || !isEvidenceClassArray(coverage["selected"])
+        || !isEvidenceClassArray(coverage["missing_required"])
+        || !isEvidenceClassArray(coverage["advisory_missing"])
+        || !isEvidenceClassArray(coverage["unclassifiable"])) {
+        return notEvaluatedCoverageReport();
+    }
+    if (!isSemanticallyConsistentCoverage(coverage)) {
+        return notEvaluatedCoverageReport();
+    }
+    return {
+        policy_id: coverage["policy_id"],
+        status: coverage["status"],
+        required_when_available: [...coverage["required_when_available"]],
+        available: [...coverage["available"]],
+        selected: [...coverage["selected"]],
+        missing_required: [...coverage["missing_required"]],
+        advisory_missing: [...coverage["advisory_missing"]],
+        unclassifiable: [...coverage["unclassifiable"]],
+    };
+}
+function isSemanticallyConsistentCoverage(coverage) {
+    const policyId = coverage["policy_id"];
+    const status = coverage["status"];
+    const available = new Set(coverage["available"]);
+    const selected = coverage["selected"];
+    const missing = coverage["missing_required"];
+    if (policyId === null) {
+        return (status === "not_evaluated" &&
+            available.size === 0 &&
+            selected.length === 0 &&
+            missing.length === 0);
+    }
+    if (status === "not_evaluated") {
+        return false;
+    }
+    if (selected.some((evidenceClass) => !available.has(evidenceClass))) {
+        return false;
+    }
+    if (status === "satisfied") {
+        return missing.length === 0 && available.has("review_target");
+    }
+    return missing.length > 0;
+}
+function isCoveragePolicyId(value) {
+    return value === null || value === "review_deep_v1";
+}
+function isCoverageStatus(value) {
+    return value === "satisfied" || value === "degraded" || value === "not_evaluated";
+}
+function isEvidenceClassArray(value) {
+    return Array.isArray(value) && value.every(isEvidenceClass);
+}
+function isEvidenceClass(value) {
+    return value === "review_target"
+        || value === "public_entrypoint"
+        || value === "reverse_consumer"
+        || value === "configuration"
+        || value === "dependency"
+        || value === "regression_test";
+}
+function budgetCapsFromManifest(value, fallback) {
+    if (value === null || typeof value !== "object") {
+        return { ...fallback };
+    }
+    const record = value;
+    return {
+        ...optionalPositiveIntegerCap(record, "max_estimated_tokens"),
+        ...optionalPositiveIntegerCap(record, "max_files"),
+        ...optionalPositiveIntegerCap(record, "max_scan_files"),
+        ...optionalPositiveIntegerCap(record, "max_bytes_per_file"),
+        ...optionalPositiveIntegerCap(record, "max_total_bytes"),
+        ...optionalPositiveIntegerCap(record, "max_search_results"),
+    };
+}
+function optionalPositiveIntegerCap(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? { [key]: value }
+        : {};
+}
+function nullableNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0
+        ? value
+        : 0;
+}
+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"])
+        ? manifest["selected_context"]
+        : [];
+    const absolutePaths = [];
+    for (const entry of selected) {
+        if (entry === null || typeof entry !== "object") {
+            throw new ExecutionError("context_builder manifest selected_context entry is invalid");
+        }
+        const rootIndex = entry.root_index;
+        const selectedPath = entry.path;
+        if (typeof rootIndex !== "number"
+            || !Number.isInteger(rootIndex)
+            || rootIndex < 0
+            || rootIndex >= roots.length
+            || typeof selectedPath !== "string"
+            || selectedPath.trim() === "") {
+            throw new ExecutionError("context_builder manifest selected_context entry is invalid");
+        }
+        const logicalPath = resolve(roots[rootIndex], selectedPath);
+        const realPath = await normalizeExistingPath(logicalPath);
+        absolutePaths.push({
+            logicalPath,
+            realPath,
+            traversedSymlink: realPath !== logicalPath,
+        });
+    }
+    return absolutePaths;
+}
+async function evaluatePostCbPromotionGate(input) {
+    try {
+        const coveredPaths = await input.signatureCoveredPaths(input.roots);
+        const selectedFilesCovered = 
+        // Empty selections carry no realized-file evidence, so they are not promotable.
+        input.selectedPaths.length > 0 &&
+            input.selectedPaths.every((path) => !path.traversedSymlink && coveredPaths.has(path.realPath));
+        const postSig = await input.workspaceSignature(input.roots);
+        return { selectedFilesCovered, postSig };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function normalizeCacheRoots(roots) {
+    const normalized = [];
+    for (const root of roots.length === 0 ? [process.cwd()] : roots) {
+        const absolute = resolve(root);
+        normalized.push(await normalizeExistingPath(absolute));
+    }
+    return Array.from(new Set(normalized)).sort();
+}
+async function normalizeExistingPath(path) {
+    const absolute = resolve(path);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function isPromoteClaimConflict(error) {
+    return error instanceof ContextBuilderRunClaimConflictError
+        || error instanceof ContextBuilderActiveRunClaimConflictError;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new CancellationError();
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function generateWorkflowPreflightRunId() {
+    return `wfpre-${randomUUID()}`;
+}
+async function resolveFallbackRoot(resolveWorkspaceRoot) {
+    const workspaceRoot = resolveWorkspaceRoot?.() ?? resolveWorkflowWorkspaceRoot();
+    const resolvedWorkspaceRoot = await realpath(workspaceRoot).catch(() => resolve(workspaceRoot));
+    const sourceAllowedRoots = getContextBuilderSourceAllowedRoots();
+    if (!isPathWithinAllowedRoots(resolvedWorkspaceRoot, sourceAllowedRoots)) {
+        throw new InvalidParamsError(`context_builder fallback root is outside source allowed roots: ${resolvedWorkspaceRoot}. ` +
+            `Allowed: ${sourceAllowedRoots.join(", ")}`);
+    }
+    return resolvedWorkspaceRoot;
+}
+function assertExplicitRootsWithinAllowed(roots) {
+    if (roots.length === 0)
+        return;
+    const allowed = getContextBuilderSourceAllowedRoots();
+    for (const root of roots) {
+        const resolved = realpathSyncBestEffort(resolve(process.cwd(), root));
+        if (!isPathWithinAllowedRoots(resolved, allowed)) {
+            throw new InvalidParamsError(`context_builder root is outside allowed roots: ${root}`);
+        }
+        let stat;
+        try {
+            stat = statSync(resolved);
+        }
+        catch {
+            throw new InvalidParamsError(`context_builder root does not exist: ${root}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new InvalidParamsError(`context_builder root is not a directory: ${root}`);
+        }
+    }
+}
+function getContextBuilderSourceAllowedRoots() {
+    const raw = process.env["CLINKX_ALLOWED_ROOTS"];
+    if (raw == null || raw.trim() === "") {
+        return getCurrentAllowedRoots();
+    }
+    const cwd = resolve(process.cwd());
+    const roots = [];
+    const seen = new Set();
+    for (const entry of raw
+        .split(",")
+        .map((root) => root.trim())
+        .filter((root) => root.length > 0)) {
+        if (isArtifactOnlyAllowedRootEntry(entry)) {
+            continue;
+        }
+        const resolved = resolve(cwd, entry);
+        const canonical = realpathSyncBestEffort(resolved);
+        if (!seen.has(canonical)) {
+            seen.add(canonical);
+            roots.push(canonical);
+        }
+    }
+    return roots;
+}
+function realpathSyncBestEffort(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function validateProfile(profile) {
+    if (profile == null || profile.trim() === "") {
+        return undefined;
+    }
+    if (isContextBuilderProfile(profile)) {
+        return profile;
+    }
+    throw new InvalidParamsError(`Unknown context_builder profile "${profile}". ` +
+        `Allowed: ${CONTEXT_BUILDER_INTENT_PROFILES.join(", ")}`);
+}
+function isContextBuilderProfile(profile) {
+    return CONTEXT_BUILDER_INTENT_PROFILES.includes(profile);
+}
+async function resolveArtifactPath(artifacts, key, label) {
+    const artifactPath = artifacts[key];
+    if (typeof artifactPath !== "string" || artifactPath.trim() === "") {
+        throw new ExecutionError(`context_builder receipt is missing ${label}`);
+    }
+    return realpath(artifactPath);
+}
+async function copyArtifactIntoContextDir(source, contextDir, fileName) {
+    const target = resolve(contextDir, fileName);
+    assertContainedPath(contextDir, target, `context_builder copy target escaped: ${target}`);
+    const tempTarget = resolve(contextDir, `.${fileName}.${process.pid}.${randomUUID()}.tmp`);
+    assertContainedPath(contextDir, tempTarget, `context_builder temp copy target escaped: ${tempTarget}`);
+    try {
+        await copyFile(source, tempTarget);
+        await rename(tempTarget, target);
+    }
+    catch (error) {
+        await rm(tempTarget, { force: true }).catch(() => { });
+        throw error;
+    }
+    const realTarget = await realpath(target);
+    assertContainedPath(contextDir, realTarget, `context_builder copied artifact escaped context directory: ${realTarget}`);
+    return realTarget;
+}
+function assertContainedPath(parent, child, message) {
+    if (!isAbsolute(child)) {
+        throw new ExecutionError(message);
+    }
+    const rel = relative(parent, child);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new ExecutionError(message);
+    }
+}
+function parseReceiptResponse(response) {
+    const receiptText = response.content[0]?.text;
+    if (typeof receiptText !== "string") {
+        throw new ExecutionError("context_builder returned no receipt text");
+    }
+    return JSON.parse(receiptText);
+}
+//# sourceMappingURL=workflow-runner.js.map