clinkx 0.3.0 → 1.0.0

package/clinkx-workflows/dist/engine.js

@@ -63,28 +63,165 @@
  * workflow engine treats as a transient failure eligible for retry.
  */
 import { stat as fsStat } from "node:fs/promises";
-import { isAbsolute, join, resolve } from "node:path";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { basename, isAbsolute, join, resolve, sep } from "node:path";
 import { callClink } from "./clink-client.js";
-import { getArtifactsDir, getChildMaxConcurrent, getMaxParallel, getMaxPromptBytes, getStateDir, resolveWorkspaceRoot, } from "./config.js";
+import { getArtifactsDir, getChildMaxConcurrent, getWorkflowsContextDefault, getWorkflowsContextDefaultCurator, getMaxParallel, getMaxPromptBytes, getStateDir, resolveWorkspaceRoot, } from "./config.js";
+import { validatePlanReviewCallBindings, validatePlanReviewPreparedInputPolicy, } from "./plan-review/runtime-policy.js";
+import { CouncilPlanReviewErrorSchema, } from "./plan-review/publication.js";
+import { PlanReviewStageError } from "./plan-review/stage-error.js";
 import { CallExecutionError, InvalidCallError, WorkflowCancellationError, WorkflowError, } from "./errors.js";
 import { analyzeOutputFidelity, enforceOutputFidelity } from "./fidelity.js";
 import { validateDynamicPaths } from "./path-validation.js";
 import { estimatePromptBudget, enforcePromptBudget, createPathContributor } from "./prompt-budget.js";
 import { DispatchQueue } from "./queue.js";
 import { renderCallPrompt } from "./template.js";
-import { ArtifactStore } from "./artifacts.js";
+import { ArtifactStore, OutputSizeError, SchemaValidationError } from "./artifacts.js";
+import { projectPlanReviewSemanticBody, renderPlanSnapshotBlock, } from "./plan-review/expander.js";
+import { filterExcludedPlanPaths, foldPlanReviewExcludeGlobs, } from "./plan-review/context-policy.js";
 import { getReducer } from "./reducers/index.js";
+import { getPostProcessor } from "./post-processors/index.js";
+import { addPathWithBasename, buildAllowlistFromDiff } from "./citation-check.js";
 import { logger } from "./logger.js";
+import { resolveWorkflowContextMode, WorkflowContextModeResolverError, } from "./context-mode-resolver.js";
+import { WorkflowDelegateValidationError } from "./delegate-validate.js";
+import { contextSeedSourceValidationError, resolveSeedSource, synthesizeSeedTerms, } from "./seed-terms.js";
+/**
+ * Declarations for variables the ENGINE derives at runtime (not declared in the
+ * workflow YAML or accepted as caller input). These are merged into the
+ * declaration map passed to the template renderer so that templates may
+ * reference them ({{context_available}}) without `template.ts` rejecting them as
+ * "Unknown variable", while genuinely-unknown placeholders are still rejected.
+ *
+ * The VALUES are produced by the engine (e.g. {@link deriveContextAvailable},
+ * which always overwrites any caller-supplied `context_available` before stages
+ * run), so listing them here does NOT widen the public caller-input surface.
+ */
+const ENGINE_DERIVED_VARIABLE_DECLS = {
+    context_available: {
+        type: "string",
+        required: false,
+        description: "Engine-derived: whether repository context is attached to the run",
+    },
+    context_quality: {
+        type: "string",
+        required: false,
+        description: "Engine-derived: effective context coverage quality",
+    },
+};
 /** Default parent-side timeout for a single tools/call RPC (10 minutes). */
 const DEFAULT_PARENT_CALL_TIMEOUT_MS = 600_000;
 /** Buffer added to per-call timeout to account for child-side teardown latency. */
 const CALL_TIMEOUT_BUFFER_MS = 5_000;
+const preflightFallbackAggregate = {
+    curated_count: 0,
+    fallback_count: 0,
+};
+function orderedUnique(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        result.push(value);
+    }
+    return result;
+}
+/**
+ * Maps a runner's {@link PreflightContextResult} to the persisted {@link WorkflowContext}.
+ * Single source of truth for this mapping: the transient `receipt` field is dropped, and
+ * optional `delegate` metadata is spread only when present.
+ */
+export function mapPreflightResultToWorkflowContext(result, contextMode, lightCaller) {
+    // Mirror the engine's bundle-attachment decision exactly: bundle artifacts are
+    // appended to context_bundle_files IFF files_selected > 0 (see ~line 1090). On a
+    // zero-selection run we proceed WITHOUT a bundle, so the reported copied_paths
+    // must be empty too — otherwise the receipt would imply a bundle was attached.
+    const copied_paths = result.metrics.files_selected > 0 ? result.copied_paths : [];
+    return {
+        context_builder: {
+            source_run_id: result.source_run_id,
+            source_artifact_dir: result.source_artifact_dir,
+            cache: result.cache,
+            schema_version: result.schema_version,
+            status: result.status,
+            ...(contextMode !== undefined ? { context_mode: contextMode } : {}),
+            copied_paths,
+            ...(result.coverage !== undefined ? { coverage: result.coverage } : {}),
+            metrics: result.metrics,
+            warning_count: result.warning_count,
+            omission_count: result.omission_count,
+            ...(result.delegate !== undefined ? { delegate: result.delegate } : {}),
+        },
+        ...(lightCaller !== undefined ? { light_caller: lightCaller } : {}),
+    };
+}
+export function classifyPreflightPartial(metrics) {
+    if (metrics.truncated ||
+        metrics.scan_cap_hit ||
+        metrics.search_cap_hit ||
+        metrics.discovery_byte_cap_hit ||
+        metrics.discovery_candidate_cap_hit ||
+        metrics.candidate_cap_hit) {
+        return { severity: "degraded", partial_reason: "cap_or_truncation" };
+    }
+    return { severity: "benign", partial_reason: "omissions_only" };
+}
+function recordPreflightFallbackAggregate(input) {
+    if (input.delegateEnabled) {
+        if (input.fallbackUsed) {
+            preflightFallbackAggregate.fallback_count += 1;
+        }
+        else {
+            preflightFallbackAggregate.curated_count += 1;
+        }
+    }
+    const total = preflightFallbackAggregate.curated_count +
+        preflightFallbackAggregate.fallback_count;
+    return {
+        curated_count: preflightFallbackAggregate.curated_count,
+        fallback_count: preflightFallbackAggregate.fallback_count,
+        total_delegate_count: total,
+        fallback_ratio: total === 0
+            ? 0
+            : preflightFallbackAggregate.fallback_count / total,
+    };
+}
+function firstReceiptWarningCode(result) {
+    const warnings = result.receipt["warnings"];
+    if (!Array.isArray(warnings)) {
+        return null;
+    }
+    for (const warning of warnings) {
+        if (warning !== null && typeof warning === "object") {
+            const code = warning["code"];
+            if (typeof code === "string" && code.trim() !== "") {
+                return code;
+            }
+        }
+    }
+    return null;
+}
+function receiptDelegateFailureReason(result) {
+    const delegate = result.receipt["delegate"];
+    if (delegate === null || typeof delegate !== "object") {
+        return null;
+    }
+    const failureReason = delegate["failure_reason"];
+    return typeof failureReason === "string" && failureReason.trim() !== ""
+        ? failureReason
+        : null;
+}
 export class WorkflowEngine {
     definition;
     session;
     variables;
+    effectiveVariables;
     validatorRegistry;
     runId;
+    sessionLogGeneration;
     runDir;
     signal;
     queueDepth;
@@ -95,14 +232,29 @@ export class WorkflowEngine {
     resumeCompletedCalls;
     resumePreparedInputs;
     resumeFailedCalls;
+    resumeNextRetryCounts;
     contextProducingCalls = new Set();
+    planReviewDeliveredAliases = new Map();
     artifactStore;
+    contextBuilderRunner;
+    contextDefault;
+    defaultCurator;
+    commitPreflightContext;
+    restoredWorkflowContext;
+    requireContextPreflight;
+    initialContextPolicy;
+    planReviewContextPolicy;
+    planReviewCallBindings;
+    commitPlanReviewContextProvenance;
+    terminalResultPolicy;
     constructor(options) {
         this.definition = options.definition;
         this.session = options.session;
         this.variables = options.variables;
+        this.effectiveVariables = { ...options.variables };
         this.validatorRegistry = options.validatorRegistry;
         this.runId = options.runId;
+        this.sessionLogGeneration = options.sessionLogGeneration;
         this.runDir = options.runDir;
         this.signal = options.signal;
         this.queueDepth = Math.min(options.maxParallel ?? getMaxParallel(), options.childMaxConcurrent ?? getChildMaxConcurrent());
@@ -113,7 +265,25 @@ export class WorkflowEngine {
         this.resumeCompletedCalls = options.resume?.completedCalls ?? new Map();
         this.resumePreparedInputs = options.resume?.preparedInputs ?? new Map();
         this.resumeFailedCalls = options.resume?.failedCalls ?? new Map();
+        this.resumeNextRetryCounts = options.resume?.nextRetryCounts ?? new Map();
         this.artifactStore = new ArtifactStore(options.runDir, options.validatorRegistry);
+        this.contextBuilderRunner = options.contextBuilderRunner;
+        this.contextDefault = options.contextDefault ?? getWorkflowsContextDefault();
+        this.defaultCurator = options.defaultCurator ?? getWorkflowsContextDefaultCurator();
+        this.commitPreflightContext = options.commitPreflightContext;
+        this.restoredWorkflowContext = options.restoredWorkflowContext;
+        this.requireContextPreflight = options.requireContextPreflight ?? false;
+        this.initialContextPolicy = options.initialContextPolicy;
+        this.planReviewContextPolicy = options.planReviewContextPolicy;
+        this.planReviewCallBindings = options.planReviewCallBindings === undefined
+            ? new Map()
+            : validatePlanReviewCallBindings(options.definition, options.planReviewCallBindings);
+        validatePlanReviewPreparedInputPolicy(this.resumePreparedInputs, this.planReviewCallBindings, {
+            snapshotText: options.planReviewSnapshotText,
+            contextPolicy: options.planReviewContextPolicy,
+        });
+        this.commitPlanReviewContextProvenance = options.commitPlanReviewContextProvenance;
+        this.terminalResultPolicy = options.terminalResultPolicy ?? { kind: "final_call" };
         this.validateFinalStage();
         this.validateAdvertisedCliNames();
         this.contextProducingCalls = collectContextProducingCalls(this.definition);
@@ -137,7 +307,7 @@ export class WorkflowEngine {
                 state: "running",
                 message: `Workflow ${this.definition.name} is running`,
             });
-            await this.validateInputPathsExist();
+            await this.prepareContextPreflight(deadlineController.signal);
             for (let stageIndex = 0; stageIndex < this.definition.stages.length; stageIndex += 1) {
                 this.throwIfAborted(deadlineController.signal);
                 const stage = this.definition.stages[stageIndex];
@@ -172,11 +342,7 @@ export class WorkflowEngine {
                     throw new WorkflowError(`Stage ${stage.id} failed and on_failure=abort`);
                 }
             }
-            const finalStage = stages[stages.length - 1];
-            const finalCall = finalStage?.calls[0];
-            if (finalCall == null || !finalCall.ok || finalCall.outputText == null) {
-                throw new WorkflowError("Final stage did not produce a successful terminal call result");
-            }
+            const outputText = await this.resolveTerminalResult(stages);
             const completedAt = new Date().toISOString();
             await this.emitRunStateChange({
                 runId: this.runId,
@@ -193,7 +359,7 @@ export class WorkflowEngine {
                 message: `Workflow ${this.definition.name} succeeded`,
             });
             return {
-                outputText: finalCall.outputText,
+                outputText,
                 stages,
                 artifactsDir: this.artifactStore.artifactsDir,
             };
@@ -219,6 +385,18 @@ export class WorkflowEngine {
                 });
             }
             else {
+                const planReviewError = error instanceof PlanReviewStageError
+                    ? CouncilPlanReviewErrorSchema.parse({
+                        schema_version: "council-plan-review-error-v1",
+                        run_id: this.runId,
+                        execution_status: "failed",
+                        stage: error.stage,
+                        error: {
+                            reason: error.reason,
+                            detail: message.slice(0, 2_048),
+                        },
+                    })
+                    : undefined;
                 await this.emitRunStateChange({
                     runId: this.runId,
                     workflowName: this.definition.name,
@@ -227,6 +405,7 @@ export class WorkflowEngine {
                     completedAt,
                     error: message,
                     failureClass: classifyFailureClass(error),
+                    planReviewError,
                 });
                 await this.emitProgress({
                     runId: this.runId,
@@ -242,6 +421,42 @@ export class WorkflowEngine {
             deadlineController.dispose();
         }
     }
+    /**
+     * Complete the workflow context gate without dispatching a provider call.
+     * Resume uses this before backend construction when workflow_context is absent.
+     */
+    async prepareContextPreflight(signal) {
+        // Protect engine-derived variables from caller overrides before every
+        // branch (runner absent, off, zero-selection, or legacy result).
+        if (this.restoredWorkflowContext === undefined) {
+            this.setEffectiveVariable("context_quality", "not_evaluated");
+        }
+        try {
+            await this.runContextBuilderPreflight(signal);
+        }
+        catch (err) {
+            if (this.planReviewContextPolicy !== undefined &&
+                !(err instanceof PlanReviewStageError) &&
+                !(err instanceof WorkflowCancellationError)) {
+                throw new PlanReviewStageError("context_preflight", err instanceof Error ? err.message : String(err), "internal_error");
+            }
+            throw err;
+        }
+        this.enforcePlanReviewContextExclusions();
+        this.deriveContextAvailable();
+        await this.validateInputPathsExist();
+    }
+    async resolveTerminalResult(stages) {
+        if (this.terminalResultPolicy.kind === "plan_review_artifacts") {
+            return await this.terminalResultPolicy.project();
+        }
+        const finalStage = stages[stages.length - 1];
+        const finalCall = finalStage?.calls[0];
+        if (finalCall == null || !finalCall.ok || finalCall.outputText == null) {
+            throw new WorkflowError("Final stage did not produce a successful terminal call result");
+        }
+        return finalCall.outputText;
+    }
     async executeParallelStage(stage, stageIndex, signal) {
         const queue = new DispatchQueue(this.queueDepth);
         const settled = await Promise.allSettled(stage.calls.map((call, callIndex) => queue.run(async () => this.executeSingleCall(stage, call, stageIndex, callIndex, signal))));
@@ -282,6 +497,15 @@ export class WorkflowEngine {
         if (resumedCall != null) {
             return resumedCall;
         }
+        const resumedFailure = this.resumeFailedCalls.get(callKey);
+        if (resumedFailure?.terminal === true) {
+            return {
+                stageId: resumedFailure.stageId,
+                callId: resumedFailure.callId,
+                ok: false,
+                error: resumedFailure.error,
+            };
+        }
         // Handle built-in reducers — no LLM call, no retry loop
         if (call.reducer != null) {
             const reducer = getReducer(call.reducer);
@@ -407,21 +631,29 @@ export class WorkflowEngine {
         const retryMode = stage.retry.mode;
         const backoffSeconds = stage.retry.backoff_seconds;
         const maxBackoffSeconds = stage.retry.max_backoff_seconds;
+        // Resume never replenishes an already-consumed provider attempt.
+        const initialRetryCount = this.resumeNextRetryCounts.get(callKey) ?? 0;
         // Emit call prepared ONCE (input is stable across retries)
         await this.emitCallPrepared({
             runId: this.runId,
             workflowName: this.definition.name,
             stageId: stage.id,
             callId: call.id,
-            attempt: 1,
-            retryCount: 0,
+            attempt: initialRetryCount + 1,
+            retryCount: initialRetryCount,
             contextProducing,
             input: structuredClone(input),
         });
-        let lastError = undefined;
+        let lastError = initialRetryCount > maxRetries
+            ? new Error("Retry budget exhausted before resume")
+            : undefined;
         let lastFailureClass = "permanent";
-        let lastRetryCount = 0;
-        for (let retryCount = 0; retryCount <= maxRetries; retryCount += 1) {
+        let lastRetryCount = initialRetryCount;
+        // F4: set in the catch below for the NEXT attempt only; always derived from
+        // the original `input.prompt`, so it never stacks. In-memory only — a
+        // resumed retry has no lastError and simply gets no suffix.
+        let correctiveSuffix;
+        for (let retryCount = initialRetryCount; retryCount <= maxRetries; retryCount += 1) {
             const attempt = retryCount + 1;
             lastRetryCount = retryCount;
             this.throwIfAborted(signal);
@@ -450,7 +682,13 @@ export class WorkflowEngine {
                     : `Call ${callKey} is retrying (attempt ${String(attempt)})`,
             });
             try {
-                const result = await this.invokeCall(stage, call, input, signal);
+                const attemptInput = correctiveSuffix == null
+                    ? input
+                    : {
+                        ...input,
+                        prompt: `${typeof input["prompt"] === "string" ? input["prompt"] : ""}${correctiveSuffix}`,
+                    };
+                const result = await this.invokeCall(stage, call, attemptInput, signal, attempt);
                 const fidelity = analyzeOutputFidelity(result.outputText, result.debugMetadata);
                 enforceOutputFidelity(fidelity, {
                     stageId: stage.id,
@@ -534,6 +772,10 @@ export class WorkflowEngine {
                 // Determine if this error is retryable
                 const canRetry = retryCount < maxRetries && isRetryable(error, failureClass, retryMode);
                 if (canRetry) {
+                    // F4: corrective suffix rides only on the retry that was already
+                    // decided above — it never changes retry eligibility. Unconditional
+                    // reassignment clears a stale suffix after a non-JSON failure.
+                    correctiveSuffix = this.buildCorrectiveRetrySuffix(stage, call, input, error);
                     // Compute backoff with jitter
                     const delayMs = computeRetryDelay(retryCount, backoffSeconds, maxBackoffSeconds);
                     const message = error instanceof Error ? error.message : String(error);
@@ -608,11 +850,85 @@ export class WorkflowEngine {
             error: message,
         };
     }
-    async invokeCall(stage, call, input, signal) {
+    /**
+     * F4: bounded corrective suffix for the next already-scheduled retry after
+     * a JSON/schema-shaped failure. Returns undefined (no suffix) unless ALL of:
+     * - the call declares a JSON contract (mirrors the expect_json derivation
+     *   in buildCallInput);
+     * - the run is NOT typed plan review (identity: the plan-review-receipts
+     *   workflow name on the
+     *   normalized definition, plus the plan-review runtime signals as
+     *   defense-in-depth — plan-review dispatch bytes are pinned);
+     * - the failure is JSON/schema-shaped (SchemaValidationError,
+     *   OutputSizeError as the second correctable class, or a child
+     *   invalid_json_output rejection);
+     * - appending stays inside the same prompt-budget ceiling the dispatch-time
+     *   gate enforces (best-effort re-estimate; skip with a warn on overflow or
+     *   estimator failure — never a new failure mode).
+     * The suffix is always derived from the ORIGINAL prompt, so it can never
+     * stack across attempts, and it is never persisted to state.
+     */
+    buildCorrectiveRetrySuffix(stage, call, input, error) {
+        if (call.response_contract !== "json" && call.validator_schema_id == null) {
+            return undefined;
+        }
+        if (this.definition.name === "plan-review-receipts" ||
+            this.planReviewContextPolicy !== undefined ||
+            call.plan_review_snapshot_text !== undefined) {
+            return undefined;
+        }
+        const detail = correctiveFailureDetail(error);
+        if (detail == null) {
+            return undefined;
+        }
+        const suffix = buildCorrectiveSuffixText(detail, error instanceof OutputSizeError ? CORRECTIVE_SIZE_SUFFIX_HEADER : CORRECTIVE_SUFFIX_HEADER);
+        try {
+            const basePrompt = typeof input["prompt"] === "string" ? input["prompt"] : "";
+            const files = Array.isArray(input["absolute_file_paths"])
+                ? input["absolute_file_paths"].filter((path) => typeof path === "string")
+                : [];
+            const images = Array.isArray(input["images"])
+                ? input["images"].filter((path) => typeof path === "string")
+                : [];
+            const estimate = estimatePromptBudget({
+                promptText: `${basePrompt}${suffix}`,
+                contextText: typeof input["context"] === "string" ? input["context"] : undefined,
+                fileContributors: files.map((path) => createPathContributor(`absolute_file_paths:${path}`, path, "file")),
+                imageContributors: images.map((path) => createPathContributor(`image:${path}`, path, "image")),
+                maxBytes: this.maxPromptBytes,
+                reserveBytes: this.promptReserveBytes,
+            });
+            if (estimate.exceeded) {
+                logger.warn({ run_id: this.runId, stage_id: stage.id, call_id: call.id }, "corrective retry suffix skipped: appending would exceed the prompt budget");
+                return undefined;
+            }
+        }
+        catch (budgetError) {
+            logger.warn({
+                run_id: this.runId,
+                stage_id: stage.id,
+                call_id: call.id,
+                err: budgetError instanceof Error ? budgetError.message : String(budgetError),
+            }, "corrective retry suffix skipped: prompt budget estimate failed");
+            return undefined;
+        }
+        return suffix;
+    }
+    async invokeCall(stage, call, input, signal, attempt) {
         const timeoutMs = call.timeout_seconds != null
             ? Math.max((call.timeout_seconds * 1000) + CALL_TIMEOUT_BUFFER_MS, DEFAULT_PARENT_CALL_TIMEOUT_MS)
             : undefined;
-        return await callClink(this.session, input, signal, { stageId: stage.id, callId: call.id }, timeoutMs);
+        const sessionLogOwner = this.sessionLogGeneration !== undefined && this.session.supportsSessionLogOwner === true
+            ? {
+                family: "workflow",
+                runId: this.runId,
+                runGeneration: this.sessionLogGeneration,
+                stageId: stage.id,
+                callId: call.id,
+                attempt,
+            }
+            : undefined;
+        return await callClink(this.session, input, signal, { stageId: stage.id, callId: call.id }, timeoutMs, sessionLogOwner);
     }
     maybeWriteArtifact(stage, call, stageIndex, callIndex, outputText) {
         const requiresValidation = call.validator_schema_id != null;
@@ -624,19 +940,78 @@ export class WorkflowEngine {
             throw new WorkflowError(`Validated call ${stage.id}.${call.id} must declare validator_schema_id`);
         }
         const validated = this.artifactStore.validateJsonOutput(stage.id, call.id, validatorSchemaId, outputText);
+        if (call.plan_review_anonymous_aliases != null) {
+            const parsed = validated.parsed;
+            const allowed = this.planReviewDeliveredAliases.get(`${stage.id}.${call.id}`) ?? new Set();
+            const assessmentIds = (parsed.peer_assessments ?? []).map((entry) => entry.candidate_id);
+            const rankingIds = (parsed.ranking ?? []).map((entry) => entry.candidate_id);
+            const exactAliasSet = (ids) => {
+                if (!ids.every((candidate) => typeof candidate === "string" && allowed.has(candidate)))
+                    return false;
+                const unique = new Set(ids);
+                return ids.length === allowed.size && unique.size === allowed.size &&
+                    [...allowed].every((candidate) => unique.has(candidate));
+            };
+            if (!exactAliasSet(assessmentIds) || !exactAliasSet(rankingIds)) {
+                throw new WorkflowError(`Validation failed for ${stage.id}.${call.id}: peer_assessments and ranking must each contain every bound peer alias exactly once`);
+            }
+        }
+        // Optional post-processing: a call may declare `post_processor: <name>` to
+        // transform the validated value before it is persisted. Unknown names are a
+        // load-time validation error (loader.ts:validatePostProcessors); we fail
+        // fast here too as defense-in-depth, since silently writing the
+        // un-transformed output through could ship un-scrubbed data (e.g. an
+        // un-run citation_check). The transform runs on the parsed data; the
+        // artifact is re-serialized so the persisted bytes reflect it.
+        let persisted = validated;
+        const postProcessorName = call.post_processor;
+        if (postProcessorName != null) {
+            const postProcessor = getPostProcessor(postProcessorName);
+            if (postProcessor == null) {
+                throw new WorkflowError(`Call ${stage.id}.${call.id} declares post_processor ` +
+                    `"${postProcessorName}" which is not registered`);
+            }
+            const allowlist = this.buildPostProcessorAllowlist();
+            const processed = postProcessor(validated.parsed, { allowlist, schemaId: validatorSchemaId });
+            const serialized = `${JSON.stringify(processed, null, 2)}\n`;
+            persisted = {
+                parsed: processed,
+                serialized,
+                sizeBytes: Buffer.byteLength(serialized, "utf-8"),
+            };
+        }
         return this.artifactStore.writeCallArtifact({
             stage,
             call,
             stageIndex,
             callIndex,
-            validated,
+            validated: persisted,
         });
     }
-    resolveDynamicPaths(variableName, context) {
-        if (variableName == null) {
+    resolveDynamicPaths(variableNames, context) {
+        if (variableNames == null) {
             return [];
         }
-        const rawValue = this.variables[variableName];
+        if (typeof variableNames === "string") {
+            const values = this.resolveDynamicPathVariable(variableNames, context);
+            validateDynamicPaths(values, this.allowedRoots, context);
+            return values;
+        }
+        const values = [];
+        const seen = new Set();
+        for (const variableName of variableNames) {
+            for (const value of this.resolveDynamicPathVariable(variableName, context)) {
+                if (!seen.has(value)) {
+                    seen.add(value);
+                    values.push(value);
+                }
+            }
+        }
+        validateDynamicPaths(values, this.allowedRoots, context);
+        return values;
+    }
+    resolveDynamicPathVariable(variableName, context) {
+        const rawValue = this.effectiveVariables[variableName];
         if (!Array.isArray(rawValue)) {
             throw new WorkflowError(`Variable "${variableName}" for ${context} must be a string[]`);
         }
@@ -647,16 +1022,390 @@ export class WorkflowEngine {
             }
             return isAbsolute(value) ? value : resolve(workspaceRoot, value);
         });
-        validateDynamicPaths(values, this.allowedRoots, context);
         return values;
     }
+    setEffectiveVariable(name, value) {
+        this.effectiveVariables[name] = value;
+    }
+    /**
+     * Derive the engine-computed `context_available` template variable after
+     * context-builder preflight has had a chance to append to
+     * `context_bundle_files`. True when the union of the effective
+     * `context_files` and `context_bundle_files` path lists is non-empty.
+     * Stored as the STRING "true"/"false" since the template engine stringifies
+     * variable values. Engine-derived; setting it is expected.
+     */
+    deriveContextAvailable() {
+        const contextFiles = this.readStringArrayVariable("context_files");
+        const bundleFiles = this.readStringArrayVariable("context_bundle_files");
+        const available = contextFiles.length > 0 || bundleFiles.length > 0;
+        this.setEffectiveVariable("context_available", available ? "true" : "false");
+    }
+    /**
+     * Build the citation allowlist for a post-processor run: the union of files
+     * parsed from the `diff_context` variable, the resolved `context_files`, and
+     * the resolved `context_bundle_files`. Both full paths and basenames are
+     * stored so citation matching is lenient.
+     */
+    buildPostProcessorAllowlist() {
+        const diffRaw = this.effectiveVariables["diff_context"];
+        const allowlist = buildAllowlistFromDiff(typeof diffRaw === "string" ? diffRaw : "");
+        for (const name of ["context_files", "context_bundle_files"]) {
+            for (const path of this.resolvePathListLenient(name)) {
+                addPathWithBasename(allowlist, path);
+            }
+        }
+        return allowlist;
+    }
+    /**
+     * Resolve a path-list variable to absolute paths without enforcing allowed
+     * roots (the post-processor allowlist is advisory, not a security boundary).
+     * Both the raw and resolved forms are returned so basename matching works
+     * regardless of how a citation spells the file.
+     */
+    resolvePathListLenient(name) {
+        const value = this.effectiveVariables[name];
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        const workspaceRoot = resolveWorkspaceRoot();
+        const out = [];
+        for (const entry of value) {
+            if (typeof entry !== "string") {
+                continue;
+            }
+            out.push(entry);
+            out.push(isAbsolute(entry) ? entry : resolve(workspaceRoot, entry));
+        }
+        return out;
+    }
+    async runContextBuilderPreflight(signal) {
+        if (this.restoredWorkflowContext !== undefined) {
+            return;
+        }
+        const policy = this.resolveContextPolicy();
+        if (policy.effectiveMode === "off" || policy.effectiveMode === "disabled") {
+            return;
+        }
+        const runner = this.contextBuilderRunner;
+        if (runner == null) {
+            if (this.requireContextPreflight) {
+                throw new WorkflowError(`Workflow context preflight is required in ${policy.effectiveMode} mode but no runner is available`);
+            }
+            return;
+        }
+        // A-7(a): strip force-excluded plan anchors from the caller's focus BEFORE
+        // anything reads them, so the curator is never even asked to select the plan.
+        this.enforcePlanReviewContextExclusions();
+        const focusPaths = this.readStringArrayVariable("cb_focus_paths");
+        const callerSearchTerms = this.readStringArrayVariable("cb_search_terms");
+        this.throwIfAborted(signal);
+        // Optional budget overrides: 6 flat number vars folded into a single budget
+        // object containing ONLY the keys actually supplied. When none are present
+        // the object is undefined and omitted via conditional spread, keeping the
+        // no-budget input byte-identical to the historical shape (cache equality).
+        const budgetEntries = [
+            ["max_estimated_tokens", this.readOptionalNumberVariable("cb_budget_max_estimated_tokens")],
+            ["max_files", this.readOptionalNumberVariable("cb_budget_max_files")],
+            ["max_scan_files", this.readOptionalNumberVariable("cb_budget_max_scan_files")],
+            ["max_bytes_per_file", this.readOptionalNumberVariable("cb_budget_max_bytes_per_file")],
+            ["max_total_bytes", this.readOptionalNumberVariable("cb_budget_max_total_bytes")],
+            ["max_search_results", this.readOptionalNumberVariable("cb_budget_max_search_results")],
+        ];
+        const budgetObject = {};
+        for (const [key, value] of budgetEntries) {
+            if (value !== undefined) {
+                budgetObject[key] = value;
+            }
+        }
+        const budget = Object.keys(budgetObject).length > 0 ? budgetObject : undefined;
+        const contextBudgetAdapter = this.readOptionalStringVariable("cb_budget_adapter");
+        const hasCallerSearchTerms = callerSearchTerms.length > 0;
+        const shouldSynthesizeSeedTerms = focusPaths.length === 0 && !hasCallerSearchTerms;
+        // Match mapPreflightContextInput's nonblank rule: a whitespace-only cb_task
+        // must fall through to user_request, else seed synthesis yields no terms and
+        // allowRootWideDiscovery runs a broad scan with no search terms.
+        const cbTaskSeed = this.readOptionalStringVariable("cb_task");
+        const seedText = resolveSeedSource(cbTaskSeed, this.readOptionalStringVariable("user_request"));
+        const seedSourceError = contextSeedSourceValidationError(seedText);
+        if (shouldSynthesizeSeedTerms && seedSourceError != null) {
+            throw new McpError(ErrorCode.InvalidParams, seedSourceError);
+        }
+        const synthesizedSearchTerms = shouldSynthesizeSeedTerms
+            ? synthesizeSeedTerms(seedText)
+            : [];
+        const searchTerms = shouldSynthesizeSeedTerms ? synthesizedSearchTerms : callerSearchTerms;
+        const input = {
+            runId: this.runId,
+            runDir: this.runDir,
+            cb_task: this.readOptionalStringVariable("cb_task") ?? "",
+            user_request: this.readOptionalStringVariable("user_request") ?? "",
+            roots: this.readStringArrayVariable("cb_roots"),
+            focus_paths: focusPaths,
+            include_globs: this.readStringArrayVariable("cb_include_globs"),
+            // A-7(a): the enforced plan exclusions are folded in HERE — before the
+            // delegate packet is built — so the default-on curator+finalizer never
+            // sees the plan as a candidate. Caller `cb_exclude_globs:[]` cannot drop
+            // them; the fold is unconditional.
+            exclude_globs: this.planReviewContextPolicy == null
+                ? this.readStringArrayVariable("cb_exclude_globs")
+                : foldPlanReviewExcludeGlobs(this.planReviewContextPolicy, this.readStringArrayVariable("cb_exclude_globs")),
+            search_terms: searchTerms,
+            profile: this.readOptionalStringVariable("cb_profile"),
+            allow_secrets: this.readOptionalBooleanVariable("cb_allow_secrets"),
+            context_mode: policy.effectiveMode,
+            ...(shouldSynthesizeSeedTerms ? { allowRootWideDiscovery: true } : {}),
+            ...(this.definition.settings.include_selected_context_artifact === true
+                ? { includeSelectedContext: true }
+                : {}),
+            ...(contextBudgetAdapter == null || contextBudgetAdapter.trim() === ""
+                ? {}
+                : { context_budget_adapter: contextBudgetAdapter }),
+            ...(budget == null ? {} : { budget }),
+            ...(policy.effectiveDelegate == null ? {} : { delegate: policy.effectiveDelegate }),
+        };
+        // Light-caller provenance: capture how anchors were derived. `root_wide_used`
+        // records the REALIZED `input.allowRootWideDiscovery` flag actually passed to
+        // the runner, while `anchor_source` reflects whether seed synthesis ran. Today
+        // both flow from the same `shouldSynthesizeSeedTerms` decision.
+        const lightCaller = {
+            anchor_source: shouldSynthesizeSeedTerms ? "synthesized" : "caller",
+            root_wide_used: input.allowRootWideDiscovery === true,
+            synthesized_search_terms: shouldSynthesizeSeedTerms ? synthesizedSearchTerms : [],
+        };
+        let result;
+        try {
+            result = await runner.runOrReuse(input, { signal });
+        }
+        catch (error) {
+            // The injected runner lives in the root package, which clinkx-workflows
+            // must not import. We therefore cannot catch the root CancellationError by
+            // type; instead, normalize at the engine boundary using the signal: if the
+            // signal aborted, surface it as a WorkflowCancellationError (preserving any
+            // existing abort reason). A genuine non-abort failure rethrows unchanged.
+            this.throwIfAborted(signal);
+            throw error;
+        }
+        this.throwIfAborted(signal);
+        const effectiveCoverageStatus = result.metrics.files_selected > 0
+            ? result.coverage?.status ?? "not_evaluated"
+            : "not_evaluated";
+        this.setEffectiveVariable("context_quality", effectiveCoverageStatus);
+        const delegateInput = policy.effectiveDelegate?.enabled === true ? policy.effectiveDelegate : undefined;
+        const fallbackUsed = result.delegate?.fallback_used === true;
+        const fallbackAggregate = recordPreflightFallbackAggregate({
+            delegateEnabled: result.delegate?.enabled === true,
+            fallbackUsed,
+        });
+        logger.info({
+            run_id: this.runId,
+            workflow: this.definition.name,
+            source_run_id: result.source_run_id,
+            mode: policy.effectiveMode,
+            delegate_enabled: delegateInput != null,
+            fallback_used: fallbackUsed,
+            curator_ms: result.observability?.curator_ms ?? null,
+            finalizer_ms: result.observability?.finalizer_ms ?? null,
+            files_seen: result.metrics.files_seen,
+            bytes_read: result.metrics.bytes_read,
+            scan_cap_hit: result.metrics.scan_cap_hit,
+            candidate_pool_size: result.observability?.candidate_pool_size ?? 0,
+            delegate_packet_size: result.observability?.delegate_packet_size ?? 0,
+            files_selected: result.metrics.files_selected,
+            cache: {
+                hit: result.cache.hit,
+                write: result.cache.write,
+                key_prefix: result.cache.key_prefix,
+            },
+            curator: delegateInput == null
+                ? null
+                : {
+                    adapter: delegateInput.curator.cli_name,
+                    role: delegateInput.curator.role,
+                },
+            finalizer: delegateInput == null
+                ? null
+                : {
+                    adapter: delegateInput.finalizer.cli_name,
+                    role: delegateInput.finalizer.role,
+                },
+            failure_reason: receiptDelegateFailureReason(result),
+            warning_code: firstReceiptWarningCode(result),
+            budget_caps: result.observability?.budget_caps ?? null,
+            profile: input.profile ?? null,
+            context_budget_adapter: input.context_budget_adapter ?? null,
+            root_source: input.roots.length > 0 ? "explicit" : "fallback",
+            seed_term_count: searchTerms.length,
+            fallback_aggregate: fallbackAggregate,
+        }, "context-builder preflight summary");
+        if (result.metrics.files_selected === 0) {
+            if (this.definition.settings.fail_on_empty_context_selection === true) {
+                throw new WorkflowError("Context-builder preflight selected no files");
+            }
+            logger.warn({
+                run_id: this.runId,
+                source_run_id: result.source_run_id,
+                files_selected: 0,
+            }, "context-builder preflight selected no files; proceeding without bundle");
+        }
+        if (effectiveCoverageStatus === "degraded") {
+            if (this.definition.settings.fail_on_degraded_context_coverage === true) {
+                throw new WorkflowError("Context-builder preflight coverage is degraded");
+            }
+            logger.warn({
+                run_id: this.runId,
+                source_run_id: result.source_run_id,
+                coverage_status: effectiveCoverageStatus,
+                missing_required: result.coverage?.missing_required ?? [],
+            }, "context-builder preflight coverage degraded; proceeding");
+        }
+        if (result.status === "partial") {
+            const partial = classifyPreflightPartial(result.metrics);
+            const payload = {
+                run_id: this.runId,
+                source_run_id: result.source_run_id,
+                files_selected: result.metrics.files_selected,
+                warning_count: result.warning_count,
+                omission_count: result.omission_count,
+                partial_reason: partial.partial_reason,
+            };
+            if (partial.severity === "degraded") {
+                logger.warn(payload, "context-builder preflight returned partial context; proceeding");
+            }
+            else {
+                logger.info(payload, "context-builder preflight returned partial context; proceeding");
+            }
+        }
+        // Only attach the generated bundle artifacts when the preflight actually
+        // selected files. On a zero-selection run we proceed WITHOUT a bundle
+        // (matching the warn log above): the runner always emits two copied paths
+        // (bundle.md + manifest.json) even for an empty selection, so appending
+        // them would hand downstream seats an empty bundle that looks intentional.
+        if (result.metrics.files_selected > 0) {
+            const existingBundleFiles = this.readStringArrayVariable("context_bundle_files");
+            this.setEffectiveVariable("context_bundle_files", orderedUnique([...existingBundleFiles, ...result.copied_paths]));
+        }
+        // A-7(b): post-filter the FINALIZED selection. This is not redundant with
+        // the pre-dispatch fold — caller `cb_include_globs`/focus anchors can
+        // re-admit exactly what the fold excluded, and this is the point where the
+        // exclusion has to survive them. Runs BEFORE commitPreflightContext so the
+        // persisted inputs snapshot never records an excluded path.
+        const removed = this.enforcePlanReviewContextExclusions();
+        if (this.planReviewContextPolicy != null) {
+            await this.commitPlanReviewContextProvenance?.({
+                enforced: true,
+                ...(policy.effectiveMode != null ? { context_mode: policy.effectiveMode } : {}),
+                copied_paths: [...this.readStringArrayVariable("context_bundle_files")],
+                filtered_out_paths: removed,
+            });
+        }
+        await this.commitPreflightContext?.({
+            variables: { ...this.effectiveVariables },
+            workflow_context: this.buildWorkflowContext(result, policy.effectiveMode, lightCaller),
+        });
+    }
+    /**
+     * Strip every force-excluded plan path from the effective context path
+     * variables (A-7). Idempotent and safe to call on any path — no policy means
+     * no-op, so non-plan-review runs are byte-unchanged.
+     *
+     * Returns the paths that were removed, for provenance.
+     */
+    enforcePlanReviewContextExclusions() {
+        const planPolicy = this.planReviewContextPolicy;
+        if (planPolicy == null) {
+            return [];
+        }
+        const removedAll = [];
+        for (const name of ["context_files", "context_bundle_files", "cb_focus_paths"]) {
+            const values = this.readStringArrayVariable(name);
+            if (values.length === 0)
+                continue;
+            const { kept, removed } = filterExcludedPlanPaths(planPolicy, values, resolveWorkspaceRoot());
+            if (removed.length === 0)
+                continue;
+            removedAll.push(...removed);
+            this.setEffectiveVariable(name, kept);
+            logger.warn({ run_id: this.runId, variable: name, removed }, "plan-review context policy stripped excluded plan paths");
+        }
+        return removedAll;
+    }
+    buildWorkflowContext(result, contextMode, lightCaller) {
+        return mapPreflightResultToWorkflowContext(result, contextMode, lightCaller);
+    }
+    resolveContextPolicy() {
+        if (this.initialContextPolicy !== undefined) {
+            return this.initialContextPolicy;
+        }
+        try {
+            return resolveWorkflowContextMode(this.effectiveVariables["cb_context_mode"], this.contextDefault, true, this.effectiveVariables["cb_delegate"], this.defaultCurator);
+        }
+        catch (error) {
+            if (error instanceof WorkflowContextModeResolverError ||
+                error instanceof WorkflowDelegateValidationError) {
+                throw new WorkflowError(error.message);
+            }
+            throw error;
+        }
+    }
+    readOptionalStringVariable(name) {
+        const value = this.effectiveVariables[name];
+        if (value === undefined) {
+            return undefined;
+        }
+        if (typeof value !== "string") {
+            throw new WorkflowError(`Variable "${name}" for context-builder preflight must be a string`);
+        }
+        return value;
+    }
+    readOptionalNumberVariable(name) {
+        const value = this.effectiveVariables[name];
+        if (value === undefined) {
+            return undefined;
+        }
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw new WorkflowError(`Variable "${name}" for context-builder preflight must be a finite number`);
+        }
+        return value;
+    }
+    readOptionalBooleanVariable(name) {
+        const value = this.effectiveVariables[name];
+        if (value === undefined) {
+            return undefined;
+        }
+        if (typeof value === "boolean") {
+            return value;
+        }
+        if (value === "true" || value === "1") {
+            return true;
+        }
+        if (value === "false" || value === "0") {
+            return false;
+        }
+        throw new WorkflowError(`Variable "${name}" for context-builder preflight must be a boolean`);
+    }
+    readStringArrayVariable(name) {
+        const value = this.effectiveVariables[name];
+        if (value === undefined) {
+            return [];
+        }
+        if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
+            throw new WorkflowError(`Variable "${name}" for context-builder preflight must be a string[]`);
+        }
+        return value;
+    }
     createDeadlineController() {
         const controller = new AbortController();
         const timeout = setTimeout(() => {
             controller.abort(new Error(`Workflow timeout exceeded after ${String(this.definition.settings.timeout_seconds)} seconds`));
         }, this.definition.settings.timeout_seconds * 1000);
         if (this.signal != null) {
-            this.signal.addEventListener("abort", () => controller.abort(new WorkflowCancellationError()), { once: true });
+            if (this.signal.aborted) {
+                controller.abort(new WorkflowCancellationError());
+            }
+            else {
+                this.signal.addEventListener("abort", () => controller.abort(new WorkflowCancellationError()), { once: true });
+            }
         }
         return {
             signal: controller.signal,
@@ -709,18 +1458,67 @@ export class WorkflowEngine {
             join(this.runDir, "artifacts"),
         ];
     }
+    recordPlanReviewDeliveredAliases(callKey, call, absoluteFilePaths) {
+        if (call.plan_review_anonymous_aliases == null)
+            return;
+        const configured = new Set(Object.values(call.plan_review_anonymous_aliases));
+        const delivered = new Set();
+        const anonymousRoot = resolve(this.artifactStore.artifactsDir, "anonymous");
+        if (Array.isArray(absoluteFilePaths)) {
+            for (const path of absoluteFilePaths) {
+                if (typeof path !== "string")
+                    continue;
+                const absolute = resolve(path);
+                if (!absolute.startsWith(anonymousRoot + sep))
+                    continue;
+                const alias = basename(path, ".json");
+                if (configured.has(alias))
+                    delivered.add(alias);
+            }
+        }
+        this.planReviewDeliveredAliases.set(callKey, delivered);
+    }
     buildCallInput(stage, call, callKey, callIndex) {
         const resumedInput = this.resumePreparedInputs.get(callKey);
         if (resumedInput != null) {
-            return structuredClone(resumedInput);
+            const input = structuredClone(resumedInput);
+            this.recordPlanReviewDeliveredAliases(callKey, call, input["absolute_file_paths"]);
+            const binding = this.planReviewCallBindings.get(callKey);
+            if (binding !== undefined) {
+                input["cli_name"] = binding.cli_name;
+            }
+            return input;
         }
-        const prompt = renderCallPrompt(call.prompt, this.definition.variables, this.variables, {
+        const renderedPrompt = renderCallPrompt(call.prompt, { ...this.definition.variables, ...ENGINE_DERIVED_VARIABLE_DECLS }, this.effectiveVariables, {
             workflow: { run_id: this.runId },
             stage: { id: stage.id },
             call: { id: call.id },
         });
+        /**
+         * A-6/D9: append the verified plan snapshot AFTER rendering, never before.
+         *
+         * The snapshot must not be an input to `renderCallPrompt`. A plan is
+         * untrusted text that may legitimately contain `{{...}}` (plans in this
+         * repo do), and `PLACEHOLDER_RE` scans the WHOLE string it is given: a
+         * `{{call.id}}` inside the plan would be silently substituted — handing the
+         * actor bytes that are NOT the verified snapshot, which is a D9 violation
+         * requiring no tampering at all — and an undeclared `{{user_request}}`
+         * would throw and brick an honest run. Appending after rendering is what
+         * makes the snapshot reach the actor VERBATIM.
+         *
+         * This lands before `estimatePromptBudget` below on purpose: the snapshot
+         * is real dispatched bytes (up to 512 KiB) and must be billed as such, or
+         * the authoritative gate would under-count by the largest term in it.
+         */
+        const prompt = call.plan_review_snapshot_text === undefined
+            ? renderedPrompt
+            : `${renderedPrompt}${renderPlanSnapshotBlock(call.plan_review_snapshot_text)}`;
         const contextArtifacts = call.anonymize_context === true
-            ? this.artifactStore.buildAnonymizedContext(this.definition, call.context_from, callIndex)
+            ? this.artifactStore.buildAnonymizedContext(this.definition, call.context_from, callIndex, call.plan_review_semantic_context === true
+                ? projectPlanReviewSemanticBody
+                : undefined, call.plan_review_semantic_context === true
+                ? `${stage.id}-${call.id}`
+                : undefined, call.plan_review_anonymous_aliases)
             : this.artifactStore.buildContext(this.definition, call.context_from);
         const staticFiles = call.absolute_file_paths ?? [];
         const dynamicFiles = this.resolveDynamicPaths(call.absolute_file_paths_from, `${stage.id}.${call.id}.absolute_file_paths_from`);
@@ -731,6 +1529,7 @@ export class WorkflowEngine {
             ...staticFiles,
             ...dynamicFiles,
         ];
+        this.recordPlanReviewDeliveredAliases(callKey, call, contextArtifacts.absoluteFilePaths);
         const images = [...staticImages, ...dynamicImages];
         const estimate = estimatePromptBudget({
             promptText: prompt,
@@ -834,7 +1633,9 @@ export class WorkflowEngine {
             }
         }
         for (const failedCall of this.resumeFailedCalls.values()) {
-            this.artifactStore.seedFailedCall(failedCall.stageId, failedCall.callId, failedCall.error);
+            if (failedCall.terminal) {
+                this.artifactStore.seedFailedCall(failedCall.stageId, failedCall.callId, failedCall.error);
+            }
         }
     }
     /**
@@ -994,8 +1795,61 @@ function classifyFailureClass(error) {
     if (error instanceof WorkflowCancellationError) {
         return "permanent";
     }
+    // Cross-package classification marker: errors thrown by the injected root
+    // package (e.g. a context-builder preflight delegate timeout) cannot be
+    // narrowed by instanceof here, so honor a well-formed `failureClass`
+    // property when present. Anything else keeps the permanent default.
+    const marker = crossPackageFailureClass(error);
+    if (marker != null) {
+        return marker;
+    }
     return "permanent";
 }
+function crossPackageFailureClass(error) {
+    if (error == null || typeof error !== "object") {
+        return undefined;
+    }
+    const value = error.failureClass;
+    return value === "transient" || value === "permanent" ? value : undefined;
+}
+/**
+ * Bounded corrective suffix appended to the NEXT attempt's prompt after a
+ * JSON/schema-shaped failure (SchemaValidationError, or OutputSizeError as
+ * the second correctable class) that is already being retried. Total suffix
+ * length is capped at CORRECTIVE_SUFFIX_MAX_CHARS; the failure detail is
+ * truncated to fit. Never persisted — resume replays the original input.
+ */
+const CORRECTIVE_SUFFIX_MAX_CHARS = 1_500;
+const CORRECTIVE_SUFFIX_HEADER = "\n\n---\nCORRECTION: Your previous response was rejected because it was not schema-valid. Failure: ";
+const CORRECTIVE_SIZE_SUFFIX_HEADER = "\n\n---\nCORRECTION: Your previous response was rejected because the pretty-printed JSON exceeded the validator byte cap. Shrink the deliverable first. Failure: ";
+const CORRECTIVE_SUFFIX_FOOTER = "\nReturn ONLY a single JSON object conforming to the declared contract — no prose, no markdown, " +
+    "no code fences, and nothing before or after the JSON object.";
+/**
+ * Detail text for a JSON/schema-shaped failure, or undefined when the failure
+ * is not one a corrective re-prompt could fix (transport death, timeout, …).
+ */
+function correctiveFailureDetail(error) {
+    if (error instanceof SchemaValidationError) {
+        return error.message;
+    }
+    if (error instanceof OutputSizeError) {
+        return error.message;
+    }
+    if (error instanceof CallExecutionError &&
+        error.childDebugMetadata?.rejection_reason === "invalid_json_output") {
+        return "output did not contain valid JSON";
+    }
+    return undefined;
+}
+function buildCorrectiveSuffixText(detail, header = CORRECTIVE_SUFFIX_HEADER) {
+    const budget = CORRECTIVE_SUFFIX_MAX_CHARS -
+        header.length -
+        CORRECTIVE_SUFFIX_FOOTER.length;
+    const bounded = detail.length > budget
+        ? `${detail.slice(0, Math.max(0, budget - 1))}…`
+        : detail;
+    return `${header}${bounded}${CORRECTIVE_SUFFIX_FOOTER}`;
+}
 /**
  * Determine whether an error is retryable based on the retry mode (5-1, 5-2).
  *