clinkx 1.0.0 → 1.1.0

package/clinkx-workflows/dist/engine.js

@@ -62,18 +62,21 @@
  * isError: true with termination_reason: "wall" or "idle", which the
  * workflow engine treats as a transient failure eligible for retry.
  */
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import { stat as fsStat } from "node:fs/promises";
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { basename, isAbsolute, join, resolve, sep } from "node:path";
-import { callClink } from "./clink-client.js";
+import { callClink, extractObservedInvocation } from "./clink-client.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 { CallExecutionError, InvalidCallError, WorkflowDispatchDeadlineError, WorkflowCancellationError, WorkflowError, } from "./errors.js";
+import { analyzeOutputFidelity, enforceOutputFidelity, enforceTypedResultFidelity, TypedResultFidelityError, } from "./fidelity.js";
+import { monotonicNowMs } from "./monotonic-clock.js";
 import { validateDynamicPaths } from "./path-validation.js";
-import { estimatePromptBudget, enforcePromptBudget, createPathContributor } from "./prompt-budget.js";
+import { DEFAULT_RESERVE_BYTES, estimatePromptBudget, enforcePromptBudget, createPathContributor, } from "./prompt-budget.js";
+import { buildCouncilDeadlineGuidance, COUNCIL_DEADLINE_GUIDANCE_RESERVE_BYTES, isCouncilExecutionWorkflow, shouldVetoWallTimeoutRetry, } from "./council-execution-policy.js";
 import { DispatchQueue } from "./queue.js";
 import { renderCallPrompt } from "./template.js";
 import { ArtifactStore, OutputSizeError, SchemaValidationError } from "./artifacts.js";
@@ -85,6 +88,7 @@ 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 { isDelegateExternalGapDegrade } from "./delegate-signature.js";
 import { contextSeedSourceValidationError, resolveSeedSource, synthesizeSeedTerms, } from "./seed-terms.js";
 /**
  * Declarations for variables the ENGINE derives at runtime (not declared in the
@@ -214,6 +218,26 @@ function receiptDelegateFailureReason(result) {
         ? failureReason
         : null;
 }
+/**
+ * The allowed roots a workflow engine derives for itself when the caller supplies
+ * none. Exported so admission-time path checks can validate against the SAME set
+ * the engine will enforce at dispatch, rather than re-deriving a near-copy.
+ *
+ * Note this set is engine-owned: `CLINKX_ALLOWED_ROOTS` is not consulted and
+ * cannot widen it.
+ */
+export function defaultWorkflowAllowedRoots(runDir) {
+    const workspaceRoot = resolveWorkspaceRoot();
+    const stateDir = getStateDir();
+    const configuredArtifactsDir = getArtifactsDir();
+    return [
+        workspaceRoot,
+        stateDir,
+        configuredArtifactsDir,
+        runDir,
+        join(runDir, "artifacts"),
+    ];
+}
 export class WorkflowEngine {
     definition;
     session;
@@ -247,6 +271,21 @@ export class WorkflowEngine {
     planReviewCallBindings;
     commitPlanReviewContextProvenance;
     terminalResultPolicy;
+    deriveInvocationAudit;
+    /**
+     * Workflow budget expiry on the MONOTONIC clock (`monotonicNowMs()`), not on
+     * the wall clock. Never compare it to `Date.now()`; read it only through
+     * `workflowRemainingMs()`.
+     */
+    workflowDeadlineAtMonoMs;
+    /**
+     * `stage.id`.`call.id` keys already written to a terminal state by
+     * `emitTerminalCallAbort`. A parallel stage still surfaces that throw through
+     * `materializeUnexpectedFailure`, whose emit carries no startedAt/durationMs
+     * and attempt 1 / retryCount 0 — persisted unconditionally, it would erase the
+     * terminal entry's timing. Bounded by the run's call count.
+     */
+    terminalizedCallKeys = new Set();
     constructor(options) {
         this.definition = options.definition;
         this.session = options.session;
@@ -284,13 +323,16 @@ export class WorkflowEngine {
         });
         this.commitPlanReviewContextProvenance = options.commitPlanReviewContextProvenance;
         this.terminalResultPolicy = options.terminalResultPolicy ?? { kind: "final_call" };
+        this.deriveInvocationAudit = options.deriveInvocationAudit;
         this.validateFinalStage();
         this.validateAdvertisedCliNames();
         this.contextProducingCalls = collectContextProducingCalls(this.definition);
         this.seedResumedArtifacts();
     }
     async execute() {
-        const deadlineController = this.createDeadlineController();
+        this.workflowDeadlineAtMonoMs =
+            monotonicNowMs() + this.definition.settings.timeout_seconds * 1000;
+        const deadlineController = this.createDeadlineController(this.definition.settings.timeout_seconds * 1000);
         const stages = [];
         const startedAt = new Date().toISOString();
         try {
@@ -339,7 +381,14 @@ export class WorkflowEngine {
                     message: `Stage ${stage.id} ${executedStage.ok ? "succeeded" : "failed"}`,
                 });
                 if (!executedStage.ok && stage.on_failure === "abort") {
-                    throw new WorkflowError(`Stage ${stage.id} failed and on_failure=abort`);
+                    // Generic boundary for ALL stage aborts, so it must stay permanent by
+                    // default — a stage that aborts on an ordinary permanent call failure
+                    // is not a replayable run. The one exception is a genuinely exhausted
+                    // wall clock: a parallel stage funnels the deadline throw through
+                    // materializeUnexpectedFailure, which drops the class, so without this
+                    // the environmental deadline would persist permanent and re-arm the
+                    // spurious duplicate_of_failed_run warning on an honest replay.
+                    throw new WorkflowError(`Stage ${stage.id} failed and on_failure=abort`, this.isWorkflowDeadlineExhausted() ? "transient" : undefined);
                 }
             }
             const outputText = await this.resolveTerminalResult(stages);
@@ -419,6 +468,26 @@ export class WorkflowEngine {
         }
         finally {
             deadlineController.dispose();
+            this.workflowDeadlineAtMonoMs = undefined;
+        }
+    }
+    /**
+     * Resume-path entry point. `execute()` is never called on the resume preflight
+     * engine, so without this the deadline is never installed and the
+     * curator/finalizer delegate runs unbounded. Installs the SAME fresh full
+     * `timeout_seconds` budget a resumed run gets (D1), runs preflight under it,
+     * and always tears it down.
+     */
+    async prepareContextPreflightWithDeadline() {
+        this.workflowDeadlineAtMonoMs =
+            monotonicNowMs() + this.definition.settings.timeout_seconds * 1000;
+        const deadlineController = this.createDeadlineController(this.definition.settings.timeout_seconds * 1000);
+        try {
+            await this.prepareContextPreflight(deadlineController.signal);
+        }
+        finally {
+            deadlineController.dispose();
+            this.workflowDeadlineAtMonoMs = undefined;
         }
     }
     /**
@@ -633,7 +702,9 @@ export class WorkflowEngine {
         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)
+        // Emit call prepared ONCE (input is stable across retries).
+        // Invocation audit rides the event, never ClinkInput / input.json.
+        const invocation = this.maybeInvocationAudit(input);
         await this.emitCallPrepared({
             runId: this.runId,
             workflowName: this.definition.name,
@@ -643,6 +714,7 @@ export class WorkflowEngine {
             retryCount: initialRetryCount,
             contextProducing,
             input: structuredClone(input),
+            ...(invocation === undefined ? {} : { invocation }),
         });
         let lastError = initialRetryCount > maxRetries
             ? new Error("Retry budget exhausted before resume")
@@ -653,10 +725,23 @@ export class WorkflowEngine {
         // the original `input.prompt`, so it never stacks. In-memory only — a
         // resumed retry has no lastError and simply gets no suffix.
         let correctiveSuffix;
+        // D7: at most ONE extra JSON-corrective attempt per call under
+        // transport_only, whatever max_retries allows. Loop-local, so a resumed
+        // call can earn it again — bounded by the persisted retry count anyway.
+        let correctiveRetryUsed = false;
         for (let retryCount = initialRetryCount; retryCount <= maxRetries; retryCount += 1) {
             const attempt = retryCount + 1;
             lastRetryCount = retryCount;
-            this.throwIfAborted(signal);
+            // Deliberately guarded HERE rather than moved inside the attempt `try`:
+            // inside it, a bare deadline WorkflowError would become retryable under
+            // retry.mode:"all". Record the terminal outcome, then rethrow unchanged.
+            try {
+                this.throwIfAborted(signal);
+            }
+            catch (error) {
+                await this.emitTerminalCallAbort(stage, call, attempt, retryCount, startedAt, startedAtMs, error, error instanceof WorkflowCancellationError ? "cancelled" : "failed");
+                throw error;
+            }
             await this.emitCallStateChange({
                 runId: this.runId,
                 workflowName: this.definition.name,
@@ -689,6 +774,11 @@ export class WorkflowEngine {
                         prompt: `${typeof input["prompt"] === "string" ? input["prompt"] : ""}${correctiveSuffix}`,
                     };
                 const result = await this.invokeCall(stage, call, attemptInput, signal, attempt);
+                enforceTypedResultFidelity(result.debugMetadata, {
+                    stageId: stage.id,
+                    callId: call.id,
+                    typedOutput: call.response_contract === "json" || call.validator_schema_id != null,
+                });
                 const fidelity = analyzeOutputFidelity(result.outputText, result.debugMetadata);
                 enforceOutputFidelity(fidelity, {
                     stageId: stage.id,
@@ -698,6 +788,7 @@ export class WorkflowEngine {
                 const artifact = this.maybeWriteArtifact(stage, call, stageIndex, callIndex, result.outputText);
                 const completedAt = new Date().toISOString();
                 const durationMs = Date.now() - startedAtMs;
+                const observedInvocation = extractObservedInvocation(result.debugMetadata);
                 await this.emitCallStateChange({
                     runId: this.runId,
                     workflowName: this.definition.name,
@@ -712,6 +803,7 @@ export class WorkflowEngine {
                     outputText: result.outputText,
                     fidelity,
                     artifact,
+                    ...(observedInvocation === undefined ? {} : { observedInvocation }),
                 });
                 await this.emitProgress({
                     runId: this.runId,
@@ -735,42 +827,32 @@ export class WorkflowEngine {
                 };
             }
             catch (error) {
+                // The deadline is never retryable, but the call still has to land in a
+                // terminal state before the throw leaves the loop.
+                if (error instanceof WorkflowDispatchDeadlineError) {
+                    await this.emitTerminalCallAbort(stage, call, attempt, retryCount, startedAt, startedAtMs, error, "failed");
+                    throw error;
+                }
                 // Cancellation is never retryable
                 if (error instanceof WorkflowCancellationError) {
-                    const completedAt = new Date().toISOString();
-                    const durationMs = Date.now() - startedAtMs;
-                    await this.emitCallStateChange({
-                        runId: this.runId,
-                        workflowName: this.definition.name,
-                        stageId: stage.id,
-                        callId: call.id,
-                        state: "cancelled",
-                        attempt,
-                        retryCount,
-                        startedAt,
-                        completedAt,
-                        durationMs,
-                        error: error.message,
-                    });
-                    await this.emitProgress({
-                        runId: this.runId,
-                        workflowName: this.definition.name,
-                        scope: "call",
-                        stageId: stage.id,
-                        stageDescription: stage.description,
-                        callId: call.id,
-                        state: "cancelled",
-                        attempt,
-                        retryCount,
-                        message: `Call ${callKey} cancelled`,
-                    });
+                    await this.emitTerminalCallAbort(stage, call, attempt, retryCount, startedAt, startedAtMs, error, "cancelled");
                     throw error;
                 }
                 const failureClass = classifyFailureClass(error);
                 lastError = error;
                 lastFailureClass = failureClass;
                 // Determine if this error is retryable
-                const canRetry = retryCount < maxRetries && isRetryable(error, failureClass, retryMode);
+                const ordinaryRetry = retryCount < maxRetries &&
+                    isRetryable(error, failureClass, retryMode) &&
+                    !shouldVetoWallTimeoutRetry(this.definition.name, error instanceof CallExecutionError ? error.terminationReason : undefined);
+                const correctiveRetry = !ordinaryRetry &&
+                    !correctiveRetryUsed &&
+                    retryCount < maxRetries &&
+                    this.isCorrectiveRetryEligible(stage, call, error);
+                if (correctiveRetry) {
+                    correctiveRetryUsed = true;
+                }
+                const canRetry = ordinaryRetry || correctiveRetry;
                 if (canRetry) {
                     // F4: corrective suffix rides only on the retry that was already
                     // decided above — it never changes retry eligibility. Unconditional
@@ -850,6 +932,51 @@ export class WorkflowEngine {
             error: message,
         };
     }
+    /**
+     * Terminalize a call that is about to be abandoned by a throw rather than
+     * by the retry loop's own failure path.
+     *
+     * Both abort/deadline exits from executeSingleCall leave the loop OUTSIDE
+     * the attempt `try`, so without this the persisted entry is stranded as
+     * "running" with no completedAt — a durable lie that resume, the dashboard
+     * and run health all read. The caller still rethrows: this only records the
+     * outcome, it never swallows it.
+     */
+    async emitTerminalCallAbort(stage, call, attempt, retryCount, startedAt, startedAtMs, error, state) {
+        const callKey = `${stage.id}.${call.id}`;
+        this.terminalizedCallKeys.add(callKey);
+        const message = error instanceof Error ? error.message : String(error);
+        const completedAt = new Date().toISOString();
+        const durationMs = Date.now() - startedAtMs;
+        await this.emitCallStateChange({
+            runId: this.runId,
+            workflowName: this.definition.name,
+            stageId: stage.id,
+            callId: call.id,
+            state,
+            attempt,
+            retryCount,
+            startedAt,
+            completedAt,
+            durationMs,
+            error: message,
+            failureClass: classifyFailureClass(error),
+        });
+        await this.emitProgress({
+            runId: this.runId,
+            workflowName: this.definition.name,
+            scope: "call",
+            stageId: stage.id,
+            stageDescription: stage.description,
+            callId: call.id,
+            state,
+            attempt,
+            retryCount,
+            message: state === "cancelled"
+                ? `Call ${callKey} cancelled`
+                : `Call ${callKey} failed: ${message}`,
+        });
+    }
     /**
      * F4: bounded corrective suffix for the next already-scheduled retry after
      * a JSON/schema-shaped failure. Returns undefined (no suffix) unless ALL of:
@@ -868,13 +995,40 @@ export class WorkflowEngine {
      * The suffix is always derived from the ORIGINAL prompt, so it can never
      * stack across attempts, and it is never persisted to state.
      */
+    /**
+     * Typed plan review (identity: the plan-review-receipts workflow name, plus
+     * the plan-review runtime signals as defense-in-depth). Its dispatch bytes
+     * and retry behavior are pinned, so no corrective machinery may touch it.
+     */
+    isTypedPlanReviewCall(call) {
+        return (this.definition.name === "plan-review-receipts" ||
+            this.planReviewContextPolicy !== undefined ||
+            call.plan_review_snapshot_text !== undefined);
+    }
+    /**
+     * D7: under retry.mode "transport_only" a malformed-JSON answer is a
+     * permanent failure, so it would never be retried. A JSON-contract call gets
+     * ONE corrective attempt when the failure is primarily JSON-shaped; a
+     * secondary-only invalid_json_output reason never creates eligibility.
+     * failureClass is not reclassified.
+     */
+    isCorrectiveRetryEligible(stage, call, error) {
+        if (stage.retry.mode !== "transport_only") {
+            return false;
+        }
+        if (!declaresJsonContract(call) || this.isTypedPlanReviewCall(call)) {
+            return false;
+        }
+        return (error instanceof SchemaValidationError ||
+            error instanceof OutputSizeError ||
+            (error instanceof CallExecutionError &&
+                error.childDebugMetadata?.semantic_failure_reason === "invalid_json_output"));
+    }
     buildCorrectiveRetrySuffix(stage, call, input, error) {
-        if (call.response_contract !== "json" && call.validator_schema_id == null) {
+        if (!declaresJsonContract(call)) {
             return undefined;
         }
-        if (this.definition.name === "plan-review-receipts" ||
-            this.planReviewContextPolicy !== undefined ||
-            call.plan_review_snapshot_text !== undefined) {
+        if (this.isTypedPlanReviewCall(call)) {
             return undefined;
         }
         const detail = correctiveFailureDetail(error);
@@ -896,7 +1050,9 @@ export class WorkflowEngine {
                 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,
+                reserveBytes: isCouncilExecutionWorkflow(this.definition.name)
+                    ? (this.promptReserveBytes ?? DEFAULT_RESERVE_BYTES) + COUNCIL_DEADLINE_GUIDANCE_RESERVE_BYTES
+                    : 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");
@@ -915,9 +1071,8 @@ export class WorkflowEngine {
         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;
+        const dispatchDeadline = this.computeDispatchDeadline(call);
+        const dispatchInput = this.prepareDispatchInput(input, dispatchDeadline.callRemainingMs);
         const sessionLogOwner = this.sessionLogGeneration !== undefined && this.session.supportsSessionLogOwner === true
             ? {
                 family: "workflow",
@@ -928,7 +1083,69 @@ export class WorkflowEngine {
                 attempt,
             }
             : undefined;
-        return await callClink(this.session, input, signal, { stageId: stage.id, callId: call.id }, timeoutMs, sessionLogOwner);
+        // Prompt sizing above performs synchronous filesystem work, during which
+        // the deadline timer cannot run. Recheck at dispatch; the already-rendered
+        // guidance remains a conservative completion target if preparation took time.
+        const finalDispatchDeadline = this.computeDispatchDeadline(call);
+        this.throwIfAborted(signal);
+        return await callClink(this.session, dispatchInput, signal, { stageId: stage.id, callId: call.id }, finalDispatchDeadline.timeoutMs, sessionLogOwner);
+    }
+    computeDispatchDeadline(call) {
+        const configuredCallTimeoutMs = call.timeout_seconds != null
+            ? Math.max((call.timeout_seconds * 1000) + CALL_TIMEOUT_BUFFER_MS, DEFAULT_PARENT_CALL_TIMEOUT_MS)
+            : undefined;
+        const workflowRemainingMs = this.workflowRemainingMs();
+        if (workflowRemainingMs != null && workflowRemainingMs <= 0) {
+            throw new WorkflowDispatchDeadlineError();
+        }
+        // Keep the existing backend timeout contract for generic and excluded
+        // workflows. The workflow AbortSignal still enforces the outer deadline;
+        // only admitted councils with an explicit call cap receive the tighter
+        // per-dispatch timeout when the workflow is closer to expiry.
+        const timeoutMs = !isCouncilExecutionWorkflow(this.definition.name) ||
+            configuredCallTimeoutMs == null || workflowRemainingMs == null
+            ? configuredCallTimeoutMs
+            : Math.min(configuredCallTimeoutMs, workflowRemainingMs);
+        const callRemainingMs = configuredCallTimeoutMs == null
+            ? workflowRemainingMs
+            : (isCouncilExecutionWorkflow(this.definition.name) && workflowRemainingMs != null
+                ? Math.min(configuredCallTimeoutMs, workflowRemainingMs)
+                : configuredCallTimeoutMs);
+        return {
+            timeoutMs,
+            callRemainingMs,
+        };
+    }
+    prepareDispatchInput(input, callRemainingMs) {
+        if (!isCouncilExecutionWorkflow(this.definition.name) ||
+            this.workflowDeadlineAtMonoMs == null ||
+            callRemainingMs == null ||
+            typeof input["prompt"] !== "string") {
+            return input;
+        }
+        const guidedInput = {
+            ...input,
+            prompt: `${input["prompt"]}${buildCouncilDeadlineGuidance({
+                workflowRemainingMs: this.workflowRemainingMs() ?? 0,
+                callRemainingMs,
+            })}`,
+        };
+        const filePaths = Array.isArray(input["absolute_file_paths"])
+            ? input["absolute_file_paths"].filter((path) => typeof path === "string")
+            : [];
+        const imagePaths = Array.isArray(input["images"])
+            ? input["images"].filter((path) => typeof path === "string")
+            : [];
+        const estimate = estimatePromptBudget({
+            promptText: guidedInput["prompt"],
+            contextText: typeof input["context"] === "string" ? input["context"] : undefined,
+            fileContributors: filePaths.map((path) => createPathContributor(`absolute_file_paths:${path}`, path, "file")),
+            imageContributors: imagePaths.map((path) => createPathContributor(`image:${path}`, path, "image")),
+            maxBytes: this.maxPromptBytes,
+            reserveBytes: this.promptReserveBytes,
+        });
+        enforcePromptBudget(estimate);
+        return guidedInput;
     }
     maybeWriteArtifact(stage, call, stageIndex, callIndex, outputText) {
         const requiresValidation = call.validator_schema_id != null;
@@ -1043,9 +1260,15 @@ export class WorkflowEngine {
     }
     /**
      * 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.
+     * parsed from the `diff_context` variable, the resolved `context_files`, the
+     * resolved `context_bundle_files`, and the source files selected by any
+     * curated context-builder bundle among them. Both full paths and basenames
+     * are stored so citation matching is lenient.
+     *
+     * A curated preflight copies only `bundle.md` and `manifest.json` into
+     * `context_bundle_files`, so without the manifest's `selected_context`
+     * every citation to a real source file would be stripped. Reading from the
+     * (persisted) variable keeps this working on resume.
      */
     buildPostProcessorAllowlist() {
         const diffRaw = this.effectiveVariables["diff_context"];
@@ -1055,8 +1278,92 @@ export class WorkflowEngine {
                 addPathWithBasename(allowlist, path);
             }
         }
+        const manifestPaths = new Set(this.resolvePathListLenient("context_bundle_files").filter((path) => isAbsolute(path) && basename(path) === "manifest.json"));
+        for (const manifestPath of manifestPaths) {
+            this.addCuratedBundleSelections(allowlist, manifestPath);
+        }
         return allowlist;
     }
+    /**
+     * Add each `selected_context` entry of a context-builder manifest to the
+     * allowlist: its root-relative `path` and, when its root resolves, the
+     * absolute form. The allowlist is advisory, so an unreadable, oversized
+     * (> 8 MiB), non-JSON, or non-context-builder manifest is skipped silently
+     * and malformed entries are ignored.
+     */
+    addCuratedBundleSelections(allowlist, manifestPath) {
+        const maxBytes = 8 * 1024 * 1024;
+        let text;
+        let fd;
+        try {
+            fd = openSync(manifestPath, "r");
+            const stats = fstatSync(fd);
+            if (!stats.isFile() || stats.size > maxBytes) {
+                return;
+            }
+            // One spare byte detects a file that grew after fstat; skip it rather
+            // than parse a torn read.
+            const buffer = Buffer.alloc(stats.size + 1);
+            let length = 0;
+            while (length < buffer.length) {
+                const read = readSync(fd, buffer, length, buffer.length - length, null);
+                if (read === 0) {
+                    break;
+                }
+                length += read;
+            }
+            if (length > stats.size) {
+                return;
+            }
+            text = buffer.toString("utf-8", 0, length);
+        }
+        catch {
+            return;
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // Advisory read; a close failure must not fail the call.
+                }
+            }
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+            return;
+        }
+        const { selected_context: selected, roots } = manifest;
+        if (!Array.isArray(selected) || !Array.isArray(roots)) {
+            return;
+        }
+        for (const entry of selected) {
+            if (typeof entry !== "object" || entry === null) {
+                continue;
+            }
+            const { path, root_index: rootIndex } = entry;
+            if (typeof path !== "string" || path.length === 0) {
+                continue;
+            }
+            addPathWithBasename(allowlist, path);
+            const root = typeof rootIndex === "number" && Number.isInteger(rootIndex) && rootIndex >= 0
+                ? roots[rootIndex]
+                : undefined;
+            if (typeof root === "object" && root !== null) {
+                const rootPath = root["path"];
+                if (typeof rootPath === "string" && rootPath.length > 0) {
+                    addPathWithBasename(allowlist, join(rootPath, path));
+                }
+            }
+        }
+    }
     /**
      * Resolve a path-list variable to absolute paths without enforcing allowed
      * roots (the post-processor allowlist is advisory, not a security boundary).
@@ -1162,7 +1469,11 @@ export class WorkflowEngine {
                 ? {}
                 : { context_budget_adapter: contextBudgetAdapter }),
             ...(budget == null ? {} : { budget }),
-            ...(policy.effectiveDelegate == null ? {} : { delegate: policy.effectiveDelegate }),
+            ...(policy.effectiveDelegate == null
+                ? {}
+                : {
+                    delegate: foldExternalGapPolicy(policy.effectiveDelegate, this.definition.settings.context_external_gap_policy),
+                }),
         };
         // Light-caller provenance: capture how anchors were derived. `root_wide_used`
         // records the REALIZED `input.allowRootWideDiscovery` flag actually passed to
@@ -1190,7 +1501,12 @@ export class WorkflowEngine {
         const effectiveCoverageStatus = result.metrics.files_selected > 0
             ? result.coverage?.status ?? "not_evaluated"
             : "not_evaluated";
-        this.setEffectiveVariable("context_quality", effectiveCoverageStatus);
+        // External gaps under external_gap_policy:"degrade" are the only producer of
+        // a partial delegate without fallback; the coverage report itself is left
+        // untouched so persisted coverage stays the policy's own verdict.
+        const externalGapsDegraded = isDelegateExternalGapDegrade(result.delegate);
+        const contextQuality = externalGapsDegraded ? "degraded" : effectiveCoverageStatus;
+        this.setEffectiveVariable("context_quality", contextQuality);
         const delegateInput = policy.effectiveDelegate?.enabled === true ? policy.effectiveDelegate : undefined;
         const fallbackUsed = result.delegate?.fallback_used === true;
         const fallbackAggregate = recordPreflightFallbackAggregate({
@@ -1248,6 +1564,12 @@ export class WorkflowEngine {
                 files_selected: 0,
             }, "context-builder preflight selected no files; proceeding without bundle");
         }
+        if (externalGapsDegraded && effectiveCoverageStatus !== "degraded") {
+            if (this.definition.settings.fail_on_degraded_context_coverage === true) {
+                throw new WorkflowError("Context-builder preflight is degraded: the finalizer reported evidence gaps outside the delegate packet");
+            }
+            logger.warn({ run_id: this.runId, source_run_id: result.source_run_id }, "context-builder preflight reported external evidence gaps; proceeding degraded");
+        }
         if (effectiveCoverageStatus === "degraded") {
             if (this.definition.settings.fail_on_degraded_context_coverage === true) {
                 throw new WorkflowError("Context-builder preflight coverage is degraded");
@@ -1394,11 +1716,11 @@ export class WorkflowEngine {
         }
         return value;
     }
-    createDeadlineController() {
+    createDeadlineController(delayMs) {
         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);
+        }, Math.max(0, delayMs));
         if (this.signal != null) {
             if (this.signal.aborted) {
                 controller.abort(new WorkflowCancellationError());
@@ -1412,6 +1734,24 @@ export class WorkflowEngine {
             dispose: () => clearTimeout(timeout),
         };
     }
+    /** Remaining workflow budget in ms; undefined when no deadline is installed. */
+    workflowRemainingMs() {
+        return this.workflowDeadlineAtMonoMs == null
+            ? undefined
+            : Math.floor(this.workflowDeadlineAtMonoMs - monotonicNowMs());
+    }
+    /**
+     * True only while a workflow deadline is set AND already past. Pure: reads
+     * the deadline the running `execute()` installed and the clock, nothing else.
+     * `execute()` clears `workflowDeadlineAtMonoMs` in its `finally`, so this can
+     * never report a stale deadline from a prior run. The reading is monotonic:
+     * a wall-clock step (NTP correction, suspend/resume, manual change) can
+     * neither manufacture nor erase an exhausted budget.
+     */
+    isWorkflowDeadlineExhausted() {
+        const remainingMs = this.workflowRemainingMs();
+        return remainingMs != null && remainingMs <= 0;
+    }
     throwIfAborted(signal) {
         if (!signal.aborted) {
             return;
@@ -1421,7 +1761,11 @@ export class WorkflowEngine {
             throw reason;
         }
         if (reason instanceof Error && reason.message.includes("Workflow timeout exceeded")) {
-            throw new WorkflowError(reason.message);
+            // Same environmental cause as WorkflowDispatchDeadlineError, so it
+            // carries the same class. Kept as a bare WorkflowError: the two are now
+            // handled identically by materializeUnexpectedFailure (both materialize
+            // rather than rethrow), so the distinction buys nothing here.
+            throw new WorkflowError(reason.message, "transient");
         }
         throw new WorkflowCancellationError();
     }
@@ -1447,16 +1791,7 @@ export class WorkflowEngine {
             `Known cli_name values: ${knownCliNames.join(", ")}`);
     }
     defaultAllowedRoots() {
-        const workspaceRoot = resolveWorkspaceRoot();
-        const stateDir = getStateDir();
-        const configuredArtifactsDir = getArtifactsDir();
-        return [
-            workspaceRoot,
-            stateDir,
-            configuredArtifactsDir,
-            this.runDir,
-            join(this.runDir, "artifacts"),
-        ];
+        return defaultWorkflowAllowedRoots(this.runDir);
     }
     recordPlanReviewDeliveredAliases(callKey, call, absoluteFilePaths) {
         if (call.plan_review_anonymous_aliases == null)
@@ -1531,6 +1866,9 @@ export class WorkflowEngine {
         ];
         this.recordPlanReviewDeliveredAliases(callKey, call, contextArtifacts.absoluteFilePaths);
         const images = [...staticImages, ...dynamicImages];
+        const reserveBytes = isCouncilExecutionWorkflow(this.definition.name)
+            ? (this.promptReserveBytes ?? DEFAULT_RESERVE_BYTES) + COUNCIL_DEADLINE_GUIDANCE_RESERVE_BYTES
+            : this.promptReserveBytes;
         const estimate = estimatePromptBudget({
             promptText: prompt,
             contextText: contextArtifacts.context,
@@ -1541,13 +1879,15 @@ export class WorkflowEngine {
             ],
             imageContributors: images.map((path) => createPathContributor(`image:${path}`, path, "image")),
             maxBytes: this.maxPromptBytes,
-            reserveBytes: this.promptReserveBytes,
+            reserveBytes,
         });
         enforcePromptBudget(estimate);
         const input = {
             cli_name: call.cli_name,
             role: call.role,
             prompt,
+            ...(call.model !== undefined ? { model: call.model } : {}),
+            ...(call.effort !== undefined ? { effort: call.effort } : {}),
         };
         if (absoluteFilePaths.length > 0) {
             input["absolute_file_paths"] = absoluteFilePaths;
@@ -1572,26 +1912,59 @@ export class WorkflowEngine {
         }
         return input;
     }
+    /**
+     * Derive a per-call invocation audit from the materialized input.
+     * Uses the dispatched cli_name/role (plan-review bindings may rewrite
+     * cli_name on resume) and never mutates `input`.
+     */
+    maybeInvocationAudit(input) {
+        const derive = this.deriveInvocationAudit;
+        if (derive == null) {
+            return undefined;
+        }
+        const cliName = input["cli_name"];
+        const role = input["role"];
+        if (typeof cliName !== "string" || typeof role !== "string") {
+            return undefined;
+        }
+        const model = input["model"];
+        const effort = input["effort"];
+        return derive(cliName, role, {
+            ...(typeof model === "string" ? { model } : {}),
+            ...(typeof effort === "string" ? { effort } : {}),
+        });
+    }
     async materializeUnexpectedFailure(stage, call, error) {
+        // Only cancellation escapes a parallel stage. Every other failure —
+        // environmental (an exhausted dispatch deadline) as much as a child
+        // failure — materializes into an ExecutedCall{ok:false} so already-settled
+        // sibling results survive Promise.allSettled instead of being discarded by
+        // a rethrow.
         if (error instanceof WorkflowCancellationError) {
             throw error;
         }
         const message = error instanceof Error ? error.message : String(error);
         this.artifactStore.noteFailedCall(stage.id, call.id, message);
         logger.error({ run_id: this.runId, stage_id: stage.id, call_id: call.id, err: message }, "parallel stage call rejected unexpectedly");
-        await this.emitCallStateChange({
-            runId: this.runId,
-            workflowName: this.definition.name,
-            stageId: stage.id,
-            callId: call.id,
-            state: "failed",
-            attempt: 1,
-            retryCount: 0,
-            completedAt: new Date().toISOString(),
-            error: message,
-            failureClass: classifyFailureClass(error),
-            childDebugMetadata: error instanceof CallExecutionError ? error.childDebugMetadata : undefined,
-        });
+        // Only the genuinely un-terminalized failures need a state emit here.
+        // `emitTerminalCallAbort` already wrote the real attempt/retryCount and
+        // startedAt/durationMs, and onCallStateChange assigns those fields
+        // unconditionally, so re-emitting would overwrite them with placeholders.
+        if (!this.terminalizedCallKeys.has(`${stage.id}.${call.id}`)) {
+            await this.emitCallStateChange({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                stageId: stage.id,
+                callId: call.id,
+                state: "failed",
+                attempt: 1,
+                retryCount: 0,
+                completedAt: new Date().toISOString(),
+                error: message,
+                failureClass: classifyFailureClass(error),
+                childDebugMetadata: error instanceof CallExecutionError ? error.childDebugMetadata : undefined,
+            });
+        }
         await this.emitProgress({
             runId: this.runId,
             workflowName: this.definition.name,
@@ -1829,18 +2202,41 @@ const CORRECTIVE_SUFFIX_FOOTER = "\nReturn ONLY a single JSON object conforming
  * is not one a corrective re-prompt could fix (transport death, timeout, …).
  */
 function correctiveFailureDetail(error) {
+    if (error instanceof TypedResultFidelityError) {
+        return error.message;
+    }
     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";
+    if (error instanceof CallExecutionError) {
+        const debug = error.childDebugMetadata;
+        if (debug?.rejection_reason === "invalid_json_output" ||
+            debug?.semantic_failure_reason === "invalid_json_output" ||
+            debug?.secondary_failure_reason === "invalid_json_output") {
+            return "output did not contain valid JSON";
+        }
     }
     return undefined;
 }
+/** Mirrors the expect_json derivation in buildCallInput. */
+function declaresJsonContract(call) {
+    return call.response_contract === "json" || call.validator_schema_id != null;
+}
+/**
+ * D1b: fold the workflow's `context_external_gap_policy` into an ENABLED
+ * preflight delegate that does not choose one itself. Runtime-only: the
+ * caller's `cb_delegate` variable (and so the inputs snapshot) is untouched,
+ * and an explicit delegate `external_gap_policy` always wins.
+ */
+function foldExternalGapPolicy(delegate, policy) {
+    if (policy === undefined || delegate.enabled !== true || delegate.external_gap_policy !== undefined) {
+        return delegate;
+    }
+    return { ...delegate, external_gap_policy: policy };
+}
 function buildCorrectiveSuffixText(detail, header = CORRECTIVE_SUFFIX_HEADER) {
     const budget = CORRECTIVE_SUFFIX_MAX_CHARS -
         header.length -