clinkx 1.0.0 → 1.1.1

package/dist/context-builder/handler.js

@@ -1,18 +1,25 @@
 import { appendArtifactOnlyRootsToEnv, isArtifactOnlyAllowedRootEntry, isSamePathOrDescendant, parseAllowedRootsEnv, stripArtifactOnlyMarker, } from "../allowed-roots.js";
 import { CancellationError, ExecutionError, InvalidParamsError, } from "../errors.js";
+import { deriveInvocationAudit, resolveInvocationOverrides } from "../safety.js";
 import { realpathSync } from "node:fs";
 import { realpath as fsRealpath } from "node:fs/promises";
 import path from "node:path";
 import { AdapterRegistry as RuntimeAdapterRegistry } from "../registry.js";
 import { logger } from "../logger.js";
+import { invocationAuditV2PersistenceEnabled } from "../../clinkx-workflows/dist/config.js";
 import { assertContextBuilderAnchorSufficiency } from "./anchors.js";
 import { writeContextBuilderFinalArtifacts, } from "./bundle.js";
 import { CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS, getSharedContextBuilderSemaphore, resolveContextBuilderRunsDir, } from "./config.js";
-import { buildContextBuilderCuratorPacket, buildContextBuilderFinalizerPacket, CONTEXT_BUILDER_DELEGATE_PACKET_CAP_PROFILE_DEFAULTS, contextBuilderCandidateId, } from "./delegate-packet.js";
-import { reconstructContextBuilderDelegateSelection } from "./delegate-reconstruction.js";
+import { buildContextBuilderCuratorPacket, buildContextBuilderFinalizerPacket, CONTEXT_BUILDER_DELEGATE_PACKET_CAP_PROFILE_DEFAULTS, contextBuilderCandidateId, countDelegatePacketObligationTruncation, } from "./delegate-packet.js";
+import { reconstructContextBuilderDelegateSelection, reconstructContextBuilderDelegateSelectionWithReport, } from "./delegate-reconstruction.js";
+import { assertNoDisabledFinalizerInvocationOverrides, resolveContextBuilderFinalizerEffectiveEnabled, } from "./delegate-finalizer-effective.js";
 import { runContextBuilderDelegateCall, } from "./delegate.js";
-import { validateContextBuilderCuratorOutput, validateContextBuilderDelegateCoverageSelection, validateContextBuilderFinalizerOutput, } from "./delegate-validation.js";
+import { recordContextInvocationAudit } from "./invocation-sidecar.js";
+import { classifyFinalizerExternalGaps, } from "./external-gaps.js";
+import { ContextBuilderFinalizerRejectionError, MAX_FINALIZER_EXTERNAL_GAPS, validateContextBuilderCuratorOutput, validateContextBuilderDelegateCoverageSelection, validateContextBuilderFinalizerOutput, } from "./delegate-validation.js";
 import { discoverContextBuilderCandidates, mergeLineRanges, } from "./discovery.js";
+import { createScanProgressPublisher } from "./discovery-progress.js";
+import { withContextBuilderDiscoveryWatchdog } from "./discovery-watchdog.js";
 import { evaluateSearchCapMateriality } from "./status.js";
 import { boundContextBuilderPathList, isRequestedEvidenceOmission, sanitizeDelegateFailureText, sanitizeDiagnosticText, } from "./diagnostics.js";
 import { compileContextBuilderGlobs, CONTEXT_BUILDER_DEFAULT_EXCLUDE_GLOBS, validateContextBuilderGlobs, } from "./globs.js";
@@ -25,18 +32,23 @@ import { appendLifecycleCompletionWarning } from "./lifecycle-recovery.js";
 import { withContextBuilderWriteWatchdog } from "./write-watchdog.js";
 import { createContextBuilderReceiptTextResponse, } from "./receipt.js";
 import { generateContextBuilderRunId } from "./run-id.js";
-import { CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS, parseContextBuilderInput, } from "./schema.js";
+import { CONTEXT_BUILDER_PUBLIC_BUDGET_HARD_LIMITS, parseContextBuilderInput, } from "./schema.js";
 import { evaluateContextCoverage, resolveContextCoveragePolicy, } from "./review-coverage.js";
 import { selectContextBuilderFinalContext, } from "./selection.js";
-import { cleanupContextBuilderIncompleteRun, createContextBuilderRun, } from "./storage.js";
+import { cleanupContextBuilderIncompleteRun, createContextBuilderRun, withContextBuilderRunMutationLease, } from "./storage.js";
 import { admitJournalContextGeneration } from "./session-log-identity.js";
 import { estimateContextBuilderTokensFromUtf8Bytes } from "./token-estimate.js";
 let defaultAdapterRegistry;
 const artifactOnlyAllowedRoots = new Set();
-const CONTEXT_BUILDER_DELEGATE_PROMPT_VERSION = "cb-delegate-v3-scored-obligations";
+const CONTEXT_BUILDER_DELEGATE_PROMPT_VERSION = "cb-delegate-v6-gap-ancestors";
 const MAX_DELEGATE_MINIMUM_OUTPUT_SELECTIONS = 24;
 export async function handleContextBuilder(args, options = {}) {
     const input = parseContextBuilderInput(args);
+    if (input.delegate.enabled) {
+        validateDelegateInvocationOverrides(input, options.registry, {
+            minScoreExplicit: options.standaloneMinScoreExplicit === true,
+        });
+    }
     const coveragePolicy = resolveContextCoveragePolicy(input.profile);
     const semaphore = options.semaphore ?? getDefaultContextBuilderSemaphore();
     const progress = createContextBuilderProgressReporter(options.progress);
@@ -150,7 +162,8 @@ export async function handleContextBuilder(args, options = {}) {
                 : { contextRunId: lifecycle.contextRunId, contextGeneration: injected.contextGeneration };
         }
         await lifecycle?.transition("scanning");
-        const discovery = await discoverContextBuilderCandidates({
+        const scanProgressPublisher = createScanProgressPublisher(lifecycle);
+        const discovery = await withContextBuilderDiscoveryWatchdog((signal) => discoverContextBuilderCandidates({
             roots: rootResolution.roots,
             task: input.task,
             allowSecrets: input.allow_secrets,
@@ -162,8 +175,9 @@ export async function handleContextBuilder(args, options = {}) {
             budget: input.budget,
             internal_caps: internalCaps,
             excluded_real_roots: excludedArtifactRoots,
-            ...(options.signal == null ? {} : { signal: options.signal }),
-        });
+            ...(signal == null ? {} : { signal }),
+            onProgress: scanProgressPublisher,
+        }), { signal: options.signal });
         await lifecycle?.transition("searching", {
             counts: lifecycleCountsFromDiscovery(discovery),
         });
@@ -189,6 +203,8 @@ export async function handleContextBuilder(args, options = {}) {
                 focusPaths,
                 baselineOmissions: rootResolution.omissions,
                 sourceRoots: rootResolution.roots,
+                excludedRealRoots: excludedArtifactRoots,
+                artifactRunDir: writingStorage.runDir,
                 registry: options.registry ?? getDefaultAdapterRegistry(),
                 coveragePolicy,
                 ...(effectiveDelegatePacketCaps == null
@@ -234,9 +250,14 @@ export async function handleContextBuilder(args, options = {}) {
         // cap event (built from metrics + search_coverage in the status reducer)
         // carries the partial classification.
         const searchCapWarning = searchCapCoverageWarning(metrics.search_cap_hit, discovery.search_coverage);
-        const warnings = searchCapWarning == null
-            ? reconciledWarnings
-            : [...reconciledWarnings, searchCapWarning];
+        const coverageAfterDelegateWarning = coverageDegradedAfterDelegateWarning(coverage, effectiveDelegateResult?.delegate);
+        const warnings = [
+            ...reconciledWarnings,
+            ...(searchCapWarning == null ? [] : [searchCapWarning]),
+            ...(coverageAfterDelegateWarning == null
+                ? []
+                : [coverageAfterDelegateWarning]),
+        ];
         const delegateMetadata = effectiveDelegateResult?.delegate == null
             ? undefined
             : {
@@ -291,6 +312,15 @@ export async function handleContextBuilder(args, options = {}) {
             metrics,
             search_coverage: discovery.search_coverage,
             open_questions: openQuestions,
+            ...(effectiveDelegateResult?.knownMissingEvidence == null
+                ? {}
+                : {
+                    known_missing_evidence: effectiveDelegateResult.knownMissingEvidence.map((gap) => ({
+                        path: gap.path,
+                        provenance: gap.provenance,
+                        reason: gap.reason,
+                    })),
+                }),
             ...(delegateMetadata == null ? {} : { delegate: delegateMetadata }),
             observability,
             coverage,
@@ -314,14 +344,28 @@ export async function handleContextBuilder(args, options = {}) {
         // Capture into a const so the beforeManifestCommit closure keeps the
         // narrowed non-undefined type (the outer binding is a reassignable let).
         const committingLifecycle = lifecycle;
-        const receipt = await withContextBuilderWriteWatchdog((signal) => writeContextBuilderFinalArtifacts(writingStorage, renderInput, {
-            signal,
-            ...(writingStorage.ownerNonce == null ? {} : { ownerNonce: writingStorage.ownerNonce }),
-            ...(!ownsLifecycle || committingLifecycle == null
+        const writeCommittedRun = async (leasedOps) => {
+            const receipt = await withContextBuilderWriteWatchdog((signal) => writeContextBuilderFinalArtifacts(writingStorage, renderInput, {
+                signal,
+                ...(writingStorage.ownerNonce == null
+                    ? {}
+                    : { ownerNonce: writingStorage.ownerNonce }),
+                ...(leasedOps == null ? {} : { ops: leasedOps }),
+                ...(!ownsLifecycle || committingLifecycle == null
+                    ? {}
+                    : { beforeManifestCommit: () => committingLifecycle.transition("committing") }),
+            }), options.signal == null ? {} : { signal: options.signal });
+            committed = true;
+            if (options.retainCommittedRun !== undefined && leasedOps !== undefined) {
+                await options.retainCommittedRun(createContextBuilderReceiptTextResponse(receipt), writingStorage, leasedOps);
+            }
+            return receipt;
+        };
+        const receipt = options.retainCommittedRun == null
+            ? await writeCommittedRun()
+            : await withContextBuilderRunMutationLease(writingStorage, writeCommittedRun, undefined, writingStorage.ownerNonce == null
                 ? {}
-                : { beforeManifestCommit: () => committingLifecycle.transition("committing") }),
-        }), options.signal == null ? {} : { signal: options.signal });
-        committed = true;
+                : { ownerNonce: writingStorage.ownerNonce });
         if (ownsLifecycle) {
             await recordContextRunCatalogMarker({
                 runsDir,
@@ -570,12 +614,19 @@ function assertNoContextBuilderFocusGlobConflicts(input) {
         if (focus.kind === "directory") {
             if (matcher.excludes(relative) ||
                 matcher.excludes(`${relative}/__dir__`)) {
-                conflicts.push(`focus directory "${relative}" (root_index ${focus.root_index}) is pruned by exclude_globs`);
+                const defaultGlob = matchingDefaultExcludeGlob(relative) ??
+                    matchingDefaultExcludeGlob(`${relative}/__dir__`);
+                conflicts.push(defaultGlob == null
+                    ? `focus directory "${relative}" (root_index ${focus.root_index}) is pruned by exclude_globs`
+                    : `focus directory "${relative}" (root_index ${focus.root_index}) matched default exclude ${defaultGlob} (not overridable)`);
             }
             continue;
         }
         if (matcher.excludes(relative)) {
-            conflicts.push(`focus path "${relative}" (root_index ${focus.root_index}) is omitted by exclude_globs`);
+            const defaultGlob = matchingDefaultExcludeGlob(relative);
+            conflicts.push(defaultGlob == null
+                ? `focus path "${relative}" (root_index ${focus.root_index}) is omitted by exclude_globs`
+                : `focus path "${relative}" (root_index ${focus.root_index}) matched default exclude ${defaultGlob} (not overridable)`);
             continue;
         }
         if (!matcher.includes(relative)) {
@@ -586,6 +637,17 @@ function assertNoContextBuilderFocusGlobConflicts(input) {
         throw new InvalidParamsError(`context_builder focus_paths conflict with the effective include/exclude globs (${conflicts.length} conflict${conflicts.length === 1 ? "" : "s"}): ${conflicts.join("; ")}`);
     }
 }
+// Default excludes are always prepended and cannot be removed by callers, so a
+// conflict against one needs to say so — "omitted by exclude_globs" sends the
+// caller hunting through globs they never passed.
+let defaultExcludeGlobMatchers;
+function matchingDefaultExcludeGlob(relative) {
+    defaultExcludeGlobMatchers ??= CONTEXT_BUILDER_DEFAULT_EXCLUDE_GLOBS.map((glob) => ({
+        glob,
+        matcher: compileContextBuilderGlobs({ include: [], exclude: [glob] }),
+    }));
+    return defaultExcludeGlobMatchers.find(({ matcher }) => matcher.excludes(relative))?.glob;
+}
 function getExactlyConfiguredArtifactRoots() {
     const rawEntries = rawAllowedRootEntries();
     const configured = new Set();
@@ -635,6 +697,38 @@ function getDefaultAdapterRegistry() {
     }
     return defaultAdapterRegistry;
 }
+function validateDelegateInvocationOverrides(input, registry, overrides = {}) {
+    if (!input.delegate.enabled) {
+        return;
+    }
+    assertNoDisabledFinalizerInvocationOverrides(input.delegate.finalizer.enabled, input.profile, input.delegate.finalizer.model, input.delegate.finalizer.effort, overrides.minScoreExplicit === true
+        ? input.delegate.finalizer.min_score
+        : undefined);
+    const finalizerEnabled = contextBuilderFinalizerEnabled(input);
+    const curatorHasOverrides = delegateProviderHasInvocationOverrides(input.delegate.curator);
+    const finalizerHasOverrides = finalizerEnabled &&
+        delegateProviderHasInvocationOverrides(input.delegate.finalizer);
+    if (!curatorHasOverrides && !finalizerHasOverrides) {
+        return;
+    }
+    const resolvedRegistry = registry ?? getDefaultAdapterRegistry();
+    if (curatorHasOverrides) {
+        validateDelegateProviderInvocationOverrides(input.delegate.curator, resolvedRegistry);
+    }
+    if (finalizerHasOverrides) {
+        validateDelegateProviderInvocationOverrides(input.delegate.finalizer, resolvedRegistry);
+    }
+}
+function delegateProviderHasInvocationOverrides(provider) {
+    return provider.model !== undefined || provider.effort !== undefined;
+}
+function validateDelegateProviderInvocationOverrides(provider, registry) {
+    const adapter = registry.resolveAdapter(provider.cli_name);
+    resolveInvocationOverrides(adapter, adapter.args, {
+        ...(provider.model === undefined ? {} : { model: provider.model }),
+        ...(provider.effort === undefined ? {} : { effort: provider.effort }),
+    });
+}
 function resolveEffectiveDelegatePacketCaps(profile, explicitCaps) {
     const profileCaps = profile == null
         ? undefined
@@ -651,15 +745,7 @@ function contextBuilderFinalizerEnabled(input) {
     if (!input.delegate.enabled) {
         return false;
     }
-    const explicit = input.delegate.finalizer.enabled;
-    if (explicit != null) {
-        return explicit;
-    }
-    if (input.profile != null) {
-        return CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS[input.profile]
-            .finalizer_enabled;
-    }
-    return true;
+    return resolveContextBuilderFinalizerEffectiveEnabled(input.delegate.finalizer.enabled, input.profile);
 }
 function delegateFinalizerReceiptMetadata(finalizer) {
     return {
@@ -668,6 +754,41 @@ function delegateFinalizerReceiptMetadata(finalizer) {
         min_score: finalizer.min_score,
     };
 }
+function delegateProviderReceiptMetadata(provider) {
+    return {
+        cli_name: provider.cli_name,
+        role: provider.role,
+    };
+}
+async function recordDelegateSeatInvocationAudit(artifactRunDir, seat, provider, registry) {
+    if (!invocationAuditV2PersistenceEnabled())
+        return;
+    try {
+        const adapter = registry.resolveAdapter(provider.cli_name);
+        const extraArgs = adapter.roles[provider.role]?.extra_args;
+        const mergedArgs = extraArgs == null
+            ? adapter.args
+            : [...adapter.args, ...extraArgs];
+        const audit = deriveInvocationAudit(adapter, mergedArgs, {
+            model: provider.model,
+            effort: provider.effort,
+        });
+        await recordContextInvocationAudit(artifactRunDir, seat, audit);
+    }
+    catch (err) {
+        // Adapter resolution failures are raised by the subsequent delegate
+        // call; do not recast them as sidecar problems.
+        if (err instanceof InvalidParamsError) {
+            return;
+        }
+        try {
+            logger.warn({ err, seat }, "failed to record context_builder invocation audit sidecar");
+        }
+        catch {
+            // Sidecar diagnostics must not fail the delegate.
+        }
+    }
+}
 async function resolveDelegateSelection(input) {
     const delegate = input.input.delegate;
     if (!delegate.enabled) {
@@ -737,6 +858,7 @@ async function resolveDelegateSelection(input) {
     if (requestedFocusOmissions.length > 0) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: `requested local evidence omitted: ${formatOmissionsForDelegateFailure(requestedFocusOmissions)}`,
             deterministicSelection: input.deterministicSelection,
             omissionCount: input.baselineOmissions.length +
@@ -751,10 +873,12 @@ async function resolveDelegateSelection(input) {
     delegatePacketSize = curatorPacket.metrics.packet_estimated_tokens;
     delegatePacketCompaction = curatorPacket.metrics.compaction;
     recordPacketEvidenceWarning(curatorPacket.evidence_warning);
+    recordPacketEvidenceWarning(packetObligationTruncationWarning(input.discovery.review_obligations, curatorPacket.coverage_policy));
     const curatorPacketRequestedOmissions = curatorPacket.omissions.filter(isRequestedEvidenceOmission);
     if (curatorPacketRequestedOmissions.length > 0) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: `requested local evidence omitted: ${formatOmissionsForDelegateFailure(curatorPacketRequestedOmissions)}`,
             deterministicSelection: input.deterministicSelection,
             omissions: curatorPacketRequestedOmissions,
@@ -769,6 +893,7 @@ async function resolveDelegateSelection(input) {
     if (curatorPacket.candidates.length === 0) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: `curator packet contained no selectable candidates; ${delegatePromptDiagnostic(curatorPacket)}`,
             deterministicSelection: input.deterministicSelection,
             omissionCount: input.baselineOmissions.length +
@@ -778,8 +903,35 @@ async function resolveDelegateSelection(input) {
             observability: currentDelegateObservability(),
         });
     }
+    // Required focus is admitted first after the finalizer, so if it cannot fit
+    // the local reconstruction budget ON ITS OWN no curator/finalizer answer can
+    // rescue the run. Dry-run the same reconstruction now and fail in ~1s
+    // instead of after minutes of provider time. Finalizer mode only: curator-
+    // only mode may legitimately compact required ranges under budget pressure.
+    if (finalizerEnabled) {
+        const preDispatchFailure = requiredFocusPreDispatchFailure({
+            focusPaths: input.focusPaths,
+            candidates: curatorPacket.candidates,
+            discovery: input.discovery,
+            budget: input.input.budget,
+        });
+        if (preDispatchFailure != null) {
+            return handleDelegateRuntimeFailure({
+                delegate,
+                discoveryMetrics: input.discovery.metrics,
+                reason: preDispatchFailure,
+                deterministicSelection: input.deterministicSelection,
+                omissionCount: input.baselineOmissions.length +
+                    input.discovery.omissions.length +
+                    input.deterministicSelection.omissions.length,
+                candidateFallbackCount,
+                observability: currentDelegateObservability(),
+            });
+        }
+    }
     const curatorStartMs = Date.now();
     const curatorSessionLogOwner = sessionLogOwner("curator");
+    await recordDelegateSeatInvocationAudit(input.artifactRunDir, "curator", delegate.curator, input.registry);
     const curatorCall = await runContextBuilderDelegateCall({
         prompt: renderDelegatePrompt("curator", curatorPacket),
         provider: delegate.curator,
@@ -795,6 +947,7 @@ async function resolveDelegateSelection(input) {
     if (!curatorCall.ok) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: failureReasonFromCall("curator", curatorCall),
             failureKind: curatorCall.reason,
             deterministicSelection: input.deterministicSelection,
@@ -856,6 +1009,7 @@ async function resolveDelegateSelection(input) {
         }
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: failureReasonFromError("curator_validation", err, delegatePromptDiagnostic(curatorPacket)),
             deterministicSelection: input.deterministicSelection,
             omissionCount: input.baselineOmissions.length +
@@ -868,6 +1022,7 @@ async function resolveDelegateSelection(input) {
     if (curatorSelection.selected.length === 0) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: "curator produced empty local selection",
             deterministicSelection: input.deterministicSelection,
             omissionCount: input.baselineOmissions.length +
@@ -886,6 +1041,7 @@ async function resolveDelegateSelection(input) {
             expandSelectedFiles: true,
         });
         const warnings = curatorProposal.warnings.map((message) => delegateWarning("delegate_curator_warning", message));
+        warnings.push(...correctiveRetryWarnings("curator", curatorCall));
         warnings.push(...packetEvidenceWarnings);
         appendDelegateRepairWarnings(warnings, repairedSelection);
         const openQuestions = curatorProposal.open_questions.map((question) => sanitizeDiagnosticText(question));
@@ -901,6 +1057,7 @@ async function resolveDelegateSelection(input) {
         if (delegateEvidenceCoverageFailure != null) {
             return handleDelegateRuntimeFailure({
                 delegate,
+                discoveryMetrics: input.discovery.metrics,
                 reason: `post-repair evidence coverage failed: ${delegateEvidenceCoverageFailure}`,
                 deterministicSelection: input.deterministicSelection,
                 omissionCount,
@@ -921,6 +1078,7 @@ async function resolveDelegateSelection(input) {
         if (curatorOnlyCoverageFailure != null) {
             return handleDelegateRuntimeFailure({
                 delegate,
+                discoveryMetrics: input.discovery.metrics,
                 reason: `post-repair required-focus coverage failed: ${curatorOnlyCoverageFailure}`,
                 deterministicSelection: input.deterministicSelection,
                 omissionCount: input.baselineOmissions.length +
@@ -940,7 +1098,7 @@ async function resolveDelegateSelection(input) {
                 status: "succeeded",
                 failure_policy: delegate.failure_policy,
                 fallback_used: false,
-                curator: { ...delegate.curator },
+                curator: delegateProviderReceiptMetadata(delegate.curator),
                 finalizer: delegateFinalizerReceiptMetadata(delegate.finalizer),
                 selected_count: repairedSelection.selection.selected.length,
                 warning_count: warnings.length,
@@ -961,10 +1119,12 @@ async function resolveDelegateSelection(input) {
     delegatePacketSize = finalizerPacket.metrics.packet_estimated_tokens;
     delegatePacketCompaction = finalizerPacket.metrics.compaction;
     recordPacketEvidenceWarning(finalizerPacket.evidence_warning);
+    recordPacketEvidenceWarning(packetObligationTruncationWarning(input.discovery.review_obligations, finalizerPacket.coverage_policy));
     const finalizerPacketRequestedOmissions = finalizerPacket.omissions.filter(isRequestedEvidenceOmission);
     if (finalizerPacketRequestedOmissions.length > 0) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: `requested local evidence omitted: ${formatOmissionsForDelegateFailure(finalizerPacketRequestedOmissions)}`,
             deterministicSelection: input.deterministicSelection,
             omissions: finalizerPacketRequestedOmissions,
@@ -979,6 +1139,7 @@ async function resolveDelegateSelection(input) {
     if ((finalizerPacket.curator_proposal?.selected.length ?? 0) === 0) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: `finalizer packet lost curator proposal selection; ${delegatePromptDiagnostic(finalizerPacket)}`,
             deterministicSelection: input.deterministicSelection,
             omissionCount: input.baselineOmissions.length +
@@ -990,9 +1151,11 @@ async function resolveDelegateSelection(input) {
     }
     const finalizerStartMs = Date.now();
     const finalizerSessionLogOwner = sessionLogOwner("finalizer");
+    await recordDelegateSeatInvocationAudit(input.artifactRunDir, "finalizer", delegate.finalizer, input.registry);
     const finalizerCall = await runContextBuilderDelegateCall({
         prompt: renderDelegatePrompt("finalizer", finalizerPacket, {
             minScore: delegate.finalizer.min_score,
+            externalGapPolicy: delegate.external_gap_policy,
         }),
         provider: delegate.finalizer,
         registry: input.registry,
@@ -1007,6 +1170,7 @@ async function resolveDelegateSelection(input) {
     if (!finalizerCall.ok) {
         return handleDelegateRuntimeFailure({
             delegate,
+            discoveryMetrics: input.discovery.metrics,
             reason: failureReasonFromCall("finalizer", finalizerCall),
             failureKind: finalizerCall.reason,
             deterministicSelection: input.deterministicSelection,
@@ -1025,43 +1189,64 @@ async function resolveDelegateSelection(input) {
             allowSecrets: input.input.allow_secrets,
             coveragePolicy: finalizerPacket.coverage_policy,
         });
-        if (finalizerProposal.omissions.length > 0) {
+        const externalGaps = classifyFinalizerExternalGaps({
+            gaps: finalizerProposal.external_gaps,
+            sourceRoots: input.sourceRoots,
+            focusPaths: input.focusPaths,
+            packetCandidates: finalizerPacket.candidates,
+            discovery: input.discovery,
+            includeGlobs: input.input.include_globs,
+            excludeGlobs: input.input.exclude_globs,
+            ...(input.excludedRealRoots == null
+                ? {}
+                : { excludedRealRoots: input.excludedRealRoots }),
+        });
+        // A rejected gap means the finalizer mis-described the packet (it named
+        // in-packet or focused evidence, or a path that is not local at all);
+        // that is invalid output under either gap policy.
+        const externalGapFailure = externalGaps.rejected.length > 0
+            ? formatExternalGapRejectionFailure(externalGaps.rejected)
+            : externalGaps.external.length > 0 &&
+                delegate.external_gap_policy === "fail"
+                ? formatExternalGapPolicyFailure(externalGaps.external)
+                : null;
+        if (externalGapFailure != null) {
             return handleDelegateRuntimeFailure({
                 delegate,
-                reason: `finalizer reported omissions: ${finalizerProposal.omissions.join("; ")}`,
+                discoveryMetrics: input.discovery.metrics,
+                reason: externalGapFailure,
                 deterministicSelection: input.deterministicSelection,
                 omissionCount: input.baselineOmissions.length +
                     input.discovery.omissions.length +
-                    input.deterministicSelection.omissions.length +
-                    finalizerProposal.omissions.length,
+                    input.deterministicSelection.omissions.length,
                 candidateFallbackCount,
                 observability: currentDelegateObservability(),
             });
         }
-        const foldedFinalizerSelection = foldRequiredFocusEvidenceIntoSelection(finalizerProposal.selected, requiredFocusEvidenceSelections({
+        const requiredFocus = requiredFocusEvidenceSelections({
             focusPaths: input.focusPaths,
             candidates: finalizerPacket.candidates,
-        }));
-        const finalSelection = reconstructContextBuilderDelegateSelection({
+        });
+        const foldedFinalizerSelection = foldRequiredFocusEvidenceIntoSelection(finalizerProposal.selected, requiredFocus);
+        // Required-first admission: the fold appends finalizer-dropped required
+        // focus at the END of selection order, so a preference-free first-fit
+        // prune would evict exactly that evidence under cap pressure. Admitting
+        // required candidates first means a required-focus file can only be
+        // missing here when required focus ALONE exceeds the budget.
+        const finalReconstruction = reconstructContextBuilderDelegateSelectionWithReport({
             selected: foldedFinalizerSelection.selected,
             candidates: finalizerPacket.candidates,
             slices: input.discovery.slices,
             tree: input.discovery.tree,
             search: input.discovery.search,
             budget: input.input.budget,
+            ...(requiredFocus.length === 0
+                ? {}
+                : {
+                    requiredFocus: new Map(requiredFocus.map((required) => [required.candidate_id, required.ranges])),
+                }),
         });
-        if (finalSelection.selected.length === 0) {
-            return handleDelegateRuntimeFailure({
-                delegate,
-                reason: "finalizer produced empty local selection",
-                deterministicSelection: input.deterministicSelection,
-                omissionCount: input.baselineOmissions.length +
-                    input.discovery.omissions.length +
-                    input.deterministicSelection.omissions.length,
-                candidateFallbackCount,
-                observability: currentDelegateObservability(),
-            });
-        }
+        const finalSelection = finalReconstruction.selection;
         // A per-file reconstruction-budget overrun no longer fails the entire
         // delegate selection. Over-budget candidates (e.g. large generated/i18n
         // catalogs the finalizer over-selected) are dropped while the rest of the
@@ -1078,10 +1263,16 @@ async function resolveDelegateSelection(input) {
             finalizerSelected: materializeFinalizerSelection(finalSelection.selected, finalizerPacket.candidates),
             curatorWarnings: curatorProposal.warnings,
             finalizerWarnings: finalizerProposal.warnings,
+            budgetDiagnostics: {
+                omissions: finalSelection.omissions,
+                foldedPaths: foldedFinalizerSelection.foldedPaths,
+                budget: input.input.budget,
+            },
         });
         if (completenessFailure != null) {
             return handleDelegateRuntimeFailure({
                 delegate,
+                discoveryMetrics: input.discovery.metrics,
                 reason: completenessFailure,
                 deterministicSelection: input.deterministicSelection,
                 omissionCount: input.baselineOmissions.length +
@@ -1091,6 +1282,24 @@ async function resolveDelegateSelection(input) {
                 observability: currentDelegateObservability(),
             });
         }
+        // Ordered after the completeness gate: when a binding cap prunes every
+        // candidate — including required focus — the lever-bearing diagnostic
+        // above must win over this generic catch. An empty selection without
+        // focus paths (or with only non-material delegate warnings) still lands
+        // here as the terminal catch.
+        if (finalSelection.selected.length === 0) {
+            return handleDelegateRuntimeFailure({
+                delegate,
+                discoveryMetrics: input.discovery.metrics,
+                reason: "finalizer produced empty local selection",
+                deterministicSelection: input.deterministicSelection,
+                omissionCount: input.baselineOmissions.length +
+                    input.discovery.omissions.length +
+                    input.deterministicSelection.omissions.length,
+                candidateFallbackCount,
+                observability: currentDelegateObservability(),
+            });
+        }
         const repairedSelection = repairDelegateSelection({
             curatorSelection: finalSelection,
             contentCandidates: input.discovery.content_candidates,
@@ -1102,6 +1311,7 @@ async function resolveDelegateSelection(input) {
         if (delegateEvidenceCoverageFailure != null) {
             return handleDelegateRuntimeFailure({
                 delegate,
+                discoveryMetrics: input.discovery.metrics,
                 reason: `post-repair evidence coverage failed: ${delegateEvidenceCoverageFailure}`,
                 deterministicSelection: input.deterministicSelection,
                 omissionCount: input.baselineOmissions.length +
@@ -1111,6 +1321,29 @@ async function resolveDelegateSelection(input) {
                 observability: currentDelegateObservability(),
             });
         }
+        // D1 backstop: required-first reconstruction plus the completeness gate
+        // above should make this unreachable. It fails closed if a server-side
+        // change ever lets a non-degenerate required-focus file vanish while
+        // non-required evidence stays selected.
+        const finalizerEvictionFailure = finalizerRequiredFocusEvictionFailure({
+            focusPaths: input.focusPaths,
+            candidates: finalizerPacket.candidates,
+            contentCandidates: input.discovery.content_candidates,
+            selected: repairedSelection.selection.selected,
+        });
+        if (finalizerEvictionFailure != null) {
+            return handleDelegateRuntimeFailure({
+                delegate,
+                discoveryMetrics: input.discovery.metrics,
+                reason: `post-repair required-focus coverage failed: ${finalizerEvictionFailure}`,
+                deterministicSelection: input.deterministicSelection,
+                omissionCount: input.baselineOmissions.length +
+                    input.discovery.omissions.length +
+                    input.deterministicSelection.omissions.length,
+                candidateFallbackCount,
+                observability: currentDelegateObservability(),
+            });
+        }
         // Re-verify required-focus completeness against the actual returned
         // selection. This keeps the fallback contract tied to the final materialized
         // packet rather than the delegate's requested selection.
@@ -1122,6 +1355,7 @@ async function resolveDelegateSelection(input) {
         if (postRepairCoverageFailure != null) {
             return handleDelegateRuntimeFailure({
                 delegate,
+                discoveryMetrics: input.discovery.metrics,
                 reason: `post-repair required-focus coverage failed: ${postRepairCoverageFailure}`,
                 deterministicSelection: input.deterministicSelection,
                 omissionCount: input.baselineOmissions.length +
@@ -1134,6 +1368,8 @@ async function resolveDelegateSelection(input) {
         const warnings = [
             ...curatorProposal.warnings.map((message) => delegateWarning("delegate_curator_warning", message)),
             ...finalizerProposal.warnings.map((message) => delegateWarning("delegate_finalizer_warning", message)),
+            ...correctiveRetryWarnings("curator", curatorCall),
+            ...correctiveRetryWarnings("finalizer", finalizerCall),
         ];
         if (foldedFinalizerSelection.foldedPaths.length > 0) {
             warnings.push(delegateWarning("delegate_finalizer_warning", `finalizer omitted requested local evidence; server folded it back into the selection: ${boundContextBuilderPathList(foldedFinalizerSelection.foldedPaths).join(", ")}`));
@@ -1143,8 +1379,15 @@ async function resolveDelegateSelection(input) {
                 .map(formatOmissionForDelegateFailure)
                 .join("; ")}`));
         }
+        warnings.push(...finalizerDropProvenanceWarnings({
+            finalizerSelected: finalizerProposal.selected,
+            requiredFocus,
+            foldedPaths: foldedFinalizerSelection.foldedPaths,
+            reconstruction: finalReconstruction,
+        }));
         warnings.push(...packetEvidenceWarnings);
         appendDelegateRepairWarnings(warnings, repairedSelection);
+        warnings.push(...externalGapWarnings(externalGaps.external));
         const openQuestions = curatorProposal.open_questions.map((question) => sanitizeDiagnosticText(question));
         const omissionCount = input.baselineOmissions.length +
             input.discovery.omissions.length +
@@ -1154,12 +1397,18 @@ async function resolveDelegateSelection(input) {
             warnings,
             omissions: [],
             openQuestions,
+            ...(externalGaps.external.length === 0
+                ? {}
+                : { knownMissingEvidence: externalGaps.external }),
             delegate: {
                 enabled: true,
-                status: "succeeded",
+                // partial WITHOUT fallback is the degrade signature: the curated
+                // selection is used as-is, but conclusions resting on the reported
+                // external gaps are conditional.
+                status: externalGaps.external.length === 0 ? "succeeded" : "partial",
                 failure_policy: delegate.failure_policy,
                 fallback_used: false,
-                curator: { ...delegate.curator },
+                curator: delegateProviderReceiptMetadata(delegate.curator),
                 finalizer: delegateFinalizerReceiptMetadata(delegate.finalizer),
                 finalizer_score: finalizerProposal.score,
                 selected_count: repairedSelection.selection.selected.length,
@@ -1178,7 +1427,10 @@ async function resolveDelegateSelection(input) {
         }
         return handleDelegateRuntimeFailure({
             delegate,
-            reason: failureReasonFromError("finalizer_validation", err, `${delegatePromptDiagnostic(finalizerPacket)}${finalizerScoreDiagnostic(finalizerCall.json, delegate.finalizer.min_score)}`),
+            discoveryMetrics: input.discovery.metrics,
+            reason: err instanceof ContextBuilderFinalizerRejectionError
+                ? formatFinalizerRejectionFailure(err, delegatePromptDiagnostic(finalizerPacket))
+                : failureReasonFromError("finalizer_validation", err, `${delegatePromptDiagnostic(finalizerPacket)}${finalizerScoreDiagnostic(finalizerCall.json, delegate.finalizer.min_score)}`),
             deterministicSelection: input.deterministicSelection,
             omissionCount: input.baselineOmissions.length +
                 input.discovery.omissions.length +
@@ -1391,11 +1643,14 @@ function fileCoversCandidate(file, candidate) {
     return file.ranges.some((range) => range.start_line <= 1 &&
         range.end_line >= Math.max(1, candidate.line_count));
 }
+const DISCOVERY_BYTE_CAP_FAILURE_SUFFIX = "; discovery_byte_cap_hit=true (discovery read cap reached; narrow roots/focus or add exclude_globs (workflow: cb_exclude_globs))";
 function handleDelegateRuntimeFailure(input) {
     // Delegate-failure reasons aggregate many per-entry details (each already
     // individually sanitized/redacted where assembled); the wider marked-
     // truncation bound keeps the tail from being silently dropped.
-    const failureReason = sanitizeDelegateFailureText(input.reason);
+    const failureReason = sanitizeDelegateFailureText(input.discoveryMetrics?.discovery_byte_cap_hit === true
+        ? `${input.reason}${DISCOVERY_BYTE_CAP_FAILURE_SUFFIX}`
+        : input.reason);
     if (input.delegate.failure_policy === "fail") {
         const error = new ExecutionError(`context_builder delegate failed: ${failureReason}`);
         if (input.failureKind === "timeout") {
@@ -1416,7 +1671,7 @@ function handleDelegateRuntimeFailure(input) {
             status: "partial",
             failure_policy: input.delegate.failure_policy,
             fallback_used: true,
-            curator: { ...input.delegate.curator },
+            curator: delegateProviderReceiptMetadata(input.delegate.curator),
             finalizer: delegateFinalizerReceiptMetadata(input.delegate.finalizer),
             selected_count: input.candidateFallbackCount,
             warning_count: warnings.length,
@@ -1527,6 +1782,45 @@ function delegateCompletenessFailure(input) {
     }
     return requiredFocusCoverageFailure(input);
 }
+// Feasibility dry-run with the exact post-finalizer reconstruction call (same
+// required-first admission and estimator), fed only the required ranges. Only
+// a BUDGET-explained miss fails here; anything else is left to the normal
+// post-finalizer gates so this check can never be stricter than they are.
+function requiredFocusPreDispatchFailure(input) {
+    const requiredFocus = requiredFocusEvidenceSelections(input);
+    if (requiredFocus.length === 0) {
+        return undefined;
+    }
+    const dryRun = reconstructContextBuilderDelegateSelectionWithReport({
+        selected: foldRequiredFocusEvidenceIntoSelection([], requiredFocus).selected,
+        candidates: input.candidates,
+        slices: input.discovery.slices,
+        tree: input.discovery.tree,
+        search: input.discovery.search,
+        budget: input.budget,
+        requiredFocus: new Map(requiredFocus.map((required) => [required.candidate_id, required.ranges])),
+    });
+    const selectedByCandidate = new Map();
+    for (const selection of materializeFinalizerSelection(dryRun.selection.selected, input.candidates)) {
+        selectedByCandidate.set(selection.candidate_id, [
+            ...(selectedByCandidate.get(selection.candidate_id) ?? []),
+            ...selection.ranges,
+        ]);
+    }
+    const missing = requiredFocus.filter((required) => {
+        const selectedRanges = selectedByCandidate.get(required.candidate_id) ?? [];
+        return required.ranges.some((range) => !rangeCoveredByRanges(range, selectedRanges));
+    });
+    if (missing.length === 0) {
+        return undefined;
+    }
+    return formatRequiredFocusBudgetFailure(missing, input.candidates, {
+        omissions: dryRun.selection.omissions,
+        foldedPaths: [],
+        budget: input.budget,
+        preDispatch: true,
+    });
+}
 function requiredFocusCoverageFailure(input) {
     const required = requiredFocusEvidenceSelections(input);
     if (required.length === 0) {
@@ -1546,12 +1840,163 @@ function requiredFocusCoverageFailure(input) {
     if (missing.length === 0) {
         return undefined;
     }
+    const budgetFailure = input.budgetDiagnostics == null
+        ? undefined
+        : formatRequiredFocusBudgetFailure(missing, input.candidates, input.budgetDiagnostics);
+    if (budgetFailure != null) {
+        return budgetFailure;
+    }
     return `delegate finalizer omitted requested local evidence: ${missing
         .map((selection) => `${selection.path}#${selection.ranges
         .map((range) => `${range.start_line}-${range.end_line}`)
         .join(",")}`)
         .join("; ")}`;
 }
+// Public budget key a caller raises for each local reconstruction cap.
+// target_estimated_tokens is derived (0.9 x max_estimated_tokens), so its
+// lever is the max key.
+const REQUIRED_FOCUS_BUDGET_LEVER_KEYS = {
+    max_files: "max_files",
+    max_bytes_per_file: "max_bytes_per_file",
+    max_total_bytes: "max_total_bytes",
+    target_estimated_tokens: "max_estimated_tokens",
+};
+// Lever-first failure text for required focus that does not fit the local
+// reconstruction budget on its own. The grep-stable prefix leads, the binding
+// cap(s) and levers follow immediately (sanitizeDelegateFailureText keeps the
+// head), and the per-path causes trail with marked truncation. Returns
+// undefined when no missing path is explained by a budget omission, so the
+// caller keeps the legacy range-coverage message.
+function formatRequiredFocusBudgetFailure(missing, candidates, diagnostics) {
+    const rootByCandidate = new Map(candidates.map((candidate) => [candidate.id, candidate.root_index]));
+    const omissionReasonByKey = new Map();
+    for (const omission of diagnostics.omissions) {
+        for (const path of omission.paths ?? []) {
+            const key = `${omission.root_index ?? 0}:${path}`;
+            if (!omissionReasonByKey.has(key)) {
+                omissionReasonByKey.set(key, omission.reason);
+            }
+        }
+    }
+    const folded = new Set(diagnostics.foldedPaths);
+    const bindingCaps = [];
+    const entries = missing.map((selection) => {
+        const reason = omissionReasonByKey.get(`${rootByCandidate.get(selection.candidate_id) ?? 0}:${selection.path}`);
+        if (reason != null && !bindingCaps.includes(reason)) {
+            bindingCaps.push(reason);
+        }
+        const ranges = selection.ranges
+            .map((range) => `${range.start_line}-${range.end_line}`)
+            .join(",");
+        const provenance = diagnostics.preDispatch === true
+            ? "required focus"
+            : folded.has(selection.path)
+                ? "omitted by finalizer, server-folded"
+                : "selected by finalizer";
+        const cause = reason == null
+            ? `${provenance}; required ranges uncovered`
+            : `${provenance}; pruned by ${reason}`;
+        return `${selection.path}#${ranges} (${cause})`;
+    });
+    if (bindingCaps.length === 0) {
+        return undefined;
+    }
+    // Advising "raise" for a key already at its public hard maximum sends the
+    // caller into a guaranteed -32602; only focus reduction can help there.
+    const raisable = [];
+    const atHardMax = [];
+    for (const cap of bindingCaps) {
+        const key = REQUIRED_FOCUS_BUDGET_LEVER_KEYS[cap] ?? cap;
+        const current = budgetValue(diagnostics.budget, key);
+        const hardMax = hardLimitValue(key);
+        if (current != null && hardMax != null && current >= hardMax) {
+            atHardMax.push(`budget.${key} is already at its hard maximum (${current})`);
+        }
+        else {
+            // " / " would read as an absolute path to the diagnostic redactor.
+            raisable.push(`budget.${key} (workflow: cb_budget_${key})`);
+        }
+    }
+    const leverText = atHardMax.length === 0
+        ? `raise ${raisable.join(" and ")} or remove the path from focus_paths (workflow: cb_focus_paths)`
+        : `${raisable.length === 0 ? "" : `raise ${raisable.join(" and ")}; `}${atHardMax.join("; ")}; reduce or split focus_paths (workflow: cb_focus_paths)`;
+    const shown = entries.slice(0, DELEGATE_FAILURE_MAX_OMISSION_ENTRIES);
+    const droppedSuffix = entries.length > shown.length
+        ? ` (+${entries.length - shown.length} more)`
+        : "";
+    return `delegate finalizer omitted requested local evidence: required focus alone exceeds the local reconstruction budget${diagnostics.preDispatch === true ? " (pre-dispatch)" : ""} (binding cap: ${bindingCaps.join(", ")}); ${leverText}. ${entries.length} required path(s) not retained: ${shown.join("; ")}${droppedSuffix}`;
+}
+function budgetValue(budget, key) {
+    const value = budget?.[key];
+    return typeof value === "number" ? value : undefined;
+}
+function hardLimitValue(key) {
+    const value = CONTEXT_BUILDER_PUBLIC_BUDGET_HARD_LIMITS[key];
+    return typeof value === "number" ? value : undefined;
+}
+// Bounded per-path provenance for the finalizer success path. Warnings are
+// capped at the diagnostic text length, so each path gets its own entry. The
+// wording deliberately avoids the omission/range vocabulary that
+// reconcileContextBuilderWarnings treats as stale for selected paths.
+const FINALIZER_DROP_PROVENANCE_MAX_WARNINGS = 12;
+function finalizerDropProvenanceWarnings(input) {
+    const finalizerSelectedIds = new Set(input.finalizerSelected.map((selection) => selection.candidate_id));
+    const folded = new Set(input.foldedPaths);
+    const entries = [];
+    for (const required of input.requiredFocus) {
+        if (!folded.has(required.path)) {
+            continue;
+        }
+        entries.push(`${required.path} = ${finalizerSelectedIds.has(required.candidate_id)
+            ? "finalizer_range_narrowed"
+            : "finalizer_unselected"} (server-folded)`);
+    }
+    for (const omission of input.reconstruction.selection.omissions) {
+        for (const path of omission.paths ?? []) {
+            entries.push(`${path} = budget:${omission.reason}`);
+        }
+    }
+    for (const item of input.reconstruction.compacted) {
+        entries.push(`${item.path} = compacted_to_required_ranges`);
+    }
+    const shown = entries.slice(0, FINALIZER_DROP_PROVENANCE_MAX_WARNINGS);
+    const warnings = shown.map((entry) => delegateWarning("delegate_finalizer_warning", `finalizer drop provenance: ${entry}`));
+    if (entries.length > shown.length) {
+        warnings.push(delegateWarning("delegate_finalizer_warning", `finalizer drop provenance: +${entries.length - shown.length} more path(s) not itemized`));
+    }
+    return warnings;
+}
+// Finalizer-path D1 backstop, mirroring postRepairRequiredFocusEvictionFailure
+// for the curator-only branch: a non-degenerate required-focus file must never
+// be absent from the returned selection while any non-required candidate is
+// still selected. A whitespace-only required file is exempt (repair drops
+// degenerate slices; the range re-verify still reports it).
+function finalizerRequiredFocusEvictionFailure(input) {
+    const requiredKeys = new Set(requiredFocusEvidenceSelections(input).flatMap((required) => {
+        const candidate = input.candidates.find((item) => item.id === required.candidate_id);
+        return candidate == null ? [] : [`${candidate.root_index}:${candidate.path}`];
+    }));
+    if (requiredKeys.size === 0) {
+        return undefined;
+    }
+    const fileKey = (file) => `${file.root_index}:${file.path}`;
+    const selectedKeys = new Set(input.selected.filter((file) => file.ranges.length > 0).map(fileKey));
+    if (![...selectedKeys].some((key) => !requiredKeys.has(key))) {
+        return undefined;
+    }
+    const contentByKey = new Map(input.contentCandidates.map((candidate) => [fileKey(candidate), candidate.content]));
+    const evicted = [...requiredKeys].filter((key) => !selectedKeys.has(key) && (contentByKey.get(key) ?? "x").trim().length > 0);
+    if (evicted.length === 0) {
+        return undefined;
+    }
+    return `finalizer selection evicted required-focus evidence while non-required evidence remained selected: ${evicted
+        .map((key) => {
+        const separator = key.indexOf(":");
+        return `root ${key.slice(0, separator)}: ${key.slice(separator + 1)}`;
+    })
+        .join("; ")}`;
+}
+export const finalizerRequiredFocusEvictionFailureForTest = finalizerRequiredFocusEvictionFailure;
 // Curator-only post-repair guard. Unlike the finalizer branch, the curator-only
 // path does not fold required-focus ranges, so its baseline is the curator's
 // own pre-repair selection. Repair is allowed to:
@@ -1722,6 +2167,9 @@ function isSameRootRelativePathOrDescendant(candidatePath, parentPath) {
     }
     return candidatePath === parentPath || candidatePath.startsWith(`${parentPath}/`);
 }
+export function isMaterialDelegateEvidenceWarningForTest(message) {
+    return isMaterialDelegateEvidenceWarning(message);
+}
 function isMaterialDelegateEvidenceWarning(message) {
     const text = message.toLowerCase();
     if (isNonBlockingDelegateWarning(text)) {
@@ -1881,6 +2329,53 @@ function packetCoverageObligationRules(packet) {
         "- For every listed class that ANY packet candidate carries in its evidence_classes, selected MUST include at least one candidate carrying that class. Server validation rejects your output otherwise.",
     ];
 }
+/**
+ * Renders the caller-anchored required-focus contract.
+ *
+ * Rendered only when the packet carries a candidate with focus_requested:true
+ * and non-empty required_focus_ranges, i.e. exactly the candidates
+ * requiredFocusEvidenceSelections enforces. Without it the finalizer had no
+ * signal that anchored files are mandatory and deduplicated near-duplicate
+ * anchors as a quality judgment.
+ *
+ * Phrasing guard: the finalizer may echo these lines into `warnings`, which
+ * isMaterialDelegateEvidenceWarning scans with a negation-blind proximity
+ * match. Keep gap vocabulary (missing, omitted, unavailable, not selected, ...)
+ * out of these lines; tests/context-builder/delegate-prompt.test.ts runs every
+ * rendered line through that matcher.
+ */
+export function packetRequiredFocusRules(stage, packet) {
+    if (packet == null || typeof packet !== "object") {
+        return [];
+    }
+    const candidates = packet["candidates"];
+    const hasRequiredFocus = Array.isArray(candidates) &&
+        candidates.some((candidate) => {
+            if (candidate == null || typeof candidate !== "object") {
+                return false;
+            }
+            const record = candidate;
+            const ranges = record["required_focus_ranges"];
+            return (record["focus_requested"] === true &&
+                Array.isArray(ranges) &&
+                ranges.length > 0);
+        });
+    if (!hasRequiredFocus) {
+        return [];
+    }
+    if (stage === "curator") {
+        return [
+            "- Candidates with focus_requested:true and a non-empty required_focus_ranges are caller-anchored: include each one in selected with ranges covering its required_focus_ranges, and do not deduplicate them.",
+        ];
+    }
+    return [
+        "Caller-anchored focus (mandatory, server-enforced):",
+        "- Every packet.candidates entry with focus_requested:true and a non-empty required_focus_ranges MUST appear in selected, with ranges that cover every one of its required_focus_ranges entries.",
+        "- You may add ranges to those candidates. Never drop one of them and never narrow its ranges below its required_focus_ranges.",
+        "- Do not deduplicate those candidates, even when two of them look like near-duplicates (for example the same document at two paths). Keep all of them.",
+        "- The server folds a dropped anchored candidate back into selected and admits anchored candidates before any other candidate, so dropping one never removes it; it only displaces lower-priority evidence from the local budget.",
+    ];
+}
 /**
  * Renders the finalizer scoring contract.
  *
@@ -1947,6 +2442,23 @@ function finalizerExampleScore(minScore) {
     // `finalizer_score` observability. A higher exemplar always clears a lower gate.
     return minScore == null || minScore <= 0 ? 9 : minScore;
 }
+// Role prompts (conf/prompts) tell a reviewer to inspect files and to reject
+// work lacking regression tests; a finalizer obeying that either stalls on
+// tool use or vetoes a bounded packet for evidence it was never meant to hold.
+// Rendered for the finalizer only — the curator has no veto to misuse.
+const FINALIZER_ROLE_OVERLAY = "These finalizer rules override any role instruction to read or inspect files or to reject packets missing regression tests: do not read files; the packet is the only evidence. Report task-relevant evidence absent from packet.candidates in external_gaps, not as grounds for rejection.";
+function finalizerExternalGapRules(policy) {
+    return [
+        "External gaps:",
+        `- Evidence the task needs that is ABSENT from packet.candidates goes in external_gaps as [{"path":"<root-relative path>","reason":"<why the task needs it>"}] (at most ${MAX_FINALIZER_EXTERNAL_GAPS} entries). Never lower score for it.`,
+        "- Never list a path that is in packet.candidates or under a focus path in external_gaps; the server verifies every entry and rejects the whole answer if one is wrong.",
+        "- Never list a directory that contains a packet.candidates path or a focus path; name the specific missing file instead.",
+        "- If evidence present in packet.candidates is insufficient, that is still approved:false with concrete omissions, not an external gap.",
+        policy === "degrade"
+            ? "- Absent evidence reported in external_gaps is NOT grounds for approved:false; the server delivers the selection with those gaps marked as conditional."
+            : "- The server will fail this request if external_gaps is non-empty; report absent evidence there honestly anyway rather than hiding it.",
+    ];
+}
 export function renderDelegatePrompt(stage, packet, options) {
     // Diagnostic-array exemplars are non-empty on purpose: empty arrays cannot
     // communicate element types, and a live finalizer failure returned
@@ -1954,7 +2466,7 @@ export function renderDelegatePrompt(stage, packet, options) {
     // show each element is one plain string.
     const outputShape = stage === "curator"
         ? '{"selected":[{"candidate_id":"c:0:path","ranges":[{"start_line":1,"end_line":1,"reason":"why this range"}],"reason":"why this file"}],"warnings":["<short plain-string caveat>"],"open_questions":["<short plain-string follow-up question>"]}'
-        : `{"score":${finalizerExampleScore(options?.minScore)},"approved":true,"selected":[{"candidate_id":"c:0:path","ranges":[{"start_line":1,"end_line":1,"reason":"why this range"}],"reason":"why this file"}],"warnings":["<short plain-string caveat>"],"omissions":["<short plain string describing an omitted file or range; must be [] when approving>"]}`;
+        : `{"score":${finalizerExampleScore(options?.minScore)},"approved":true,"selected":[{"candidate_id":"c:0:path","ranges":[{"start_line":1,"end_line":1,"reason":"why this range"}],"reason":"why this file"}],"warnings":["<short plain-string caveat>"],"omissions":["<short plain string describing an omitted file or range; must be [] when approving>"],"external_gaps":[]}`;
     const stageRules = stage === "curator"
         ? [
             "Curator-specific rules:",
@@ -1978,12 +2490,10 @@ export function renderDelegatePrompt(stage, packet, options) {
             "- Treat packet.deterministic_selection.selected as server-ranked required baseline evidence. If the curator underselected or warned about sparse evidence, add relevant deterministic candidates/ranges that are present in packet.candidates instead of lowering the score for evidence the packet already provides.",
             "- Do not reject solely because the curator warning says broader implementation may exist when deterministic_selection and packet.candidates contain concrete task-critical ranges for that concern.",
             "- If the selected packet evidence is insufficient for the bounded task, set approved:false and explain concrete omissions; the server will treat that as delegate failure according to failure_policy.",
-            // "'may contain more detail' caveats" invited exactly the phrasing
-            // isMaterialEvidenceGapWarning rejects outright
-            // (/\boutside (?:the )?selected ranges?\b/), so obeying this rule got
-            // the finalizer hard-failed. Steer the caveat at evidence absent from
-            // the packet instead of at the selected ranges.
-            "- If approving with score at or above the requested minimum, omissions MUST be []. Put speculative concerns about evidence absent from this packet in warnings instead.",
+            // Evidence absent from the packet is routed to external_gaps (see
+            // finalizerExternalGapRules), not warnings: warnings are scanned by
+            // isMaterialEvidenceGapWarning and a gap phrased there hard-fails.
+            "- If approving with score at or above the requested minimum, omissions MUST be [].",
             // The observed live schema failure was object-shaped `omissions`;
             // state the element type explicitly instead of relying on exemplars.
             // (No open_questions here: the finalizer schema is strict and would
@@ -1994,6 +2504,7 @@ export function renderDelegatePrompt(stage, packet, options) {
     return [
         `You are the context_builder ${stage}.`,
         `Prompt version: ${CONTEXT_BUILDER_DELEGATE_PROMPT_VERSION}.`,
+        ...(stage === "finalizer" ? [FINALIZER_ROLE_OVERLAY] : []),
         "Return exactly one strict JSON object and no prose.",
         "For this tool call, the JSON packet below is the only source of truth.",
         stage === "curator"
@@ -2005,7 +2516,11 @@ export function renderDelegatePrompt(stage, packet, options) {
             ? "Use the excerpt, search_hits, deterministic_selection, omissions, and task fields as evidence; the packet intentionally omits full source content."
             : "Use the excerpt, search_hits, curator_proposal, deterministic_selection, omissions, and task fields as evidence; the packet intentionally omits full source content.",
         ...stageRules,
+        ...packetRequiredFocusRules(stage, packet),
         ...(stage === "finalizer" ? finalizerScoringRules(options?.minScore) : []),
+        ...(stage === "finalizer"
+            ? finalizerExternalGapRules(options?.externalGapPolicy ?? "fail")
+            : []),
         ...packetCoverageObligationRules(packet),
         ...(minimumOutput == null
             ? []
@@ -2200,6 +2715,7 @@ function buildMinimumDelegateOutput(stage, packet, minScore) {
                 "minimum curator proposal selection used; review packet evidence for more context",
             ],
             omissions: [],
+            external_gaps: [],
         };
     return JSON.stringify(output);
 }
@@ -2362,12 +2878,115 @@ function finalizerScoreDiagnostic(json, minScore) {
         ? `; finalizer_score=${rawScore}; min_score=${minScore}`
         : `; min_score=${minScore}`;
 }
+const FINALIZER_REJECTION_LEVERS = 'levers: add missing path(s) to focus_paths (workflow: cb_focus_paths); exclude vendor/generated dirs via exclude_globs (workflow: cb_exclude_globs); or set external_gap_policy:"degrade" (workflow: cb_delegate.external_gap_policy)';
+// Verdict-first text for a finalizer veto: what the finalizer said (approval,
+// its own omission list) leads, because that is what the caller acts on; the
+// score and packet diagnostics trail. Each omission is provider text, so it is
+// redacted on its own before joining — the whole-string redactor would
+// otherwise blank the entire reason when any single entry carries a secret.
+function formatFinalizerRejectionFailure(err, packetDiagnostic) {
+    const lead = err.reasonKind === "score"
+        ? `score=${err.score} below min_score=${err.minScore}`
+        : `approved=${err.approved}`;
+    const entries = err.reasonKind === "material_warning"
+        ? { label: "material_warnings", values: err.materialWarnings }
+        : { label: "omissions", values: err.omissions };
+    const shown = entries.values
+        .slice(0, DELEGATE_FAILURE_MAX_OMISSION_ENTRIES)
+        .map((entry) => sanitizeDelegateFailureText(entry, DELEGATE_FAILURE_MAX_ENTRY_TEXT_LENGTH));
+    const dropped = entries.values.length - shown.length;
+    const entryText = shown.length === 0
+        ? `${entries.label}=0`
+        : `${entries.label}=${entries.values.length}: ${shown.join("; ")}${dropped > 0 ? ` (+${dropped} more omissions)` : ""}`;
+    return [
+        `finalizer_validation: ${lead}`,
+        entryText,
+        `finalizer_score=${err.score}`,
+        `min_score=${err.minScore}`,
+        FINALIZER_REJECTION_LEVERS,
+        packetDiagnostic,
+        err.message,
+    ].join("; ");
+}
+const EXTERNAL_GAP_POLICY_LEVERS = 'levers: add path(s) to focus_paths (workflow: cb_focus_paths) or set external_gap_policy:"degrade" (workflow: cb_delegate.external_gap_policy)';
+function formatExternalGapEntries(entries) {
+    const shown = entries
+        .slice(0, DELEGATE_FAILURE_MAX_OMISSION_ENTRIES)
+        .map((entry) => sanitizeDelegateFailureText(`${entry.path} (${entry.detail})`, DELEGATE_FAILURE_MAX_ENTRY_TEXT_LENGTH));
+    const dropped = entries.length - shown.length;
+    return `${entries.length}: ${shown.join("; ")}${dropped > 0 ? ` (+${dropped} more external gaps)` : ""}`;
+}
+function formatExternalGapRejectionFailure(rejected) {
+    return [
+        `finalizer_validation: external_gaps rejected=${formatExternalGapEntries(rejected.map((gap) => ({ path: gap.path, detail: gap.why })))}`,
+        FINALIZER_REJECTION_LEVERS,
+    ].join("; ");
+}
+function formatExternalGapPolicyFailure(external) {
+    return [
+        `finalizer_validation: external_gap_policy=fail; external_gaps=${formatExternalGapEntries(external.map((gap) => ({ path: gap.path, detail: gap.provenance })))}`,
+        EXTERNAL_GAP_POLICY_LEVERS,
+    ].join("; ");
+}
+// Wording deliberately avoids the truncation/omission vocabulary that
+// reconcileContextBuilderWarnings filters as stale; the codes are also
+// exempted there because the per-gap reason is provider prose.
+function externalGapWarnings(external) {
+    if (external.length === 0) {
+        return [];
+    }
+    return [
+        delegateWarning("delegate_external_gaps", `finalizer reported ${external.length} evidence gap(s) outside the delegate packet; conclusions depending on them are conditional`),
+        ...external.map((gap) => delegateWarning("delegate_external_gap", `external evidence gap: ${gap.path} (${gap.provenance}): ${gap.reason}`)),
+    ];
+}
 function failureReasonFromError(stage, err, diagnostic) {
     const message = err instanceof Error ? err.message : "unknown delegate error";
     return diagnostic == null
         ? `${stage}: ${message}`
         : `${stage}: ${diagnostic}; ${message}`;
 }
+// P1b observability. The packet serializes a sliced obligation set while
+// terminal coverage evaluates the full one; name the gap so a succeeded
+// delegate next to degraded coverage is explainable. Wording avoids the
+// truncation/omission vocabulary reconcileContextBuilderWarnings filters.
+function packetObligationTruncationWarning(fullObligations, packetPolicy) {
+    const counts = countDelegatePacketObligationTruncation(fullObligations, packetPolicy);
+    if (counts == null) {
+        return undefined;
+    }
+    return {
+        code: "delegate_packet_obligations_truncated",
+        message: `delegate packet carried ${counts.targets_included} of ${counts.targets_total} review obligation targets (${counts.ranges_included} of ${counts.ranges_total} ranges, ${counts.regression_links_included} of ${counts.regression_links_total} regression links); final coverage evaluates the full set`,
+    };
+}
+export const packetObligationTruncationWarningForTest = packetObligationTruncationWarning;
+function coverageDegradedAfterDelegateWarning(coverage, delegate) {
+    if (coverage.status !== "degraded" ||
+        delegate?.status !== "succeeded" ||
+        delegate.fallback_used) {
+        return undefined;
+    }
+    const unclassifiableRegression = coverage.missing_required.includes("regression_test") &&
+        coverage.unclassifiable.includes("regression_test");
+    return {
+        code: "coverage_degraded_after_delegate",
+        message: `delegate succeeded but final coverage is degraded; unmet required classes: ${coverage.missing_required.join(", ") || "none"}; unclassifiable regression: ${unclassifiableRegression
+            ? "yes (no confident regression link, so no selection could satisfy it)"
+            : "no"}`,
+    };
+}
+const DELEGATE_JSON_CORRECTIVE_RETRY_WARNING_CODE = "delegate_json_corrective_retry";
+// Informational only: the retried call produced valid JSON, so the run is not
+// degraded; the warning keeps the recovered formatting failure observable.
+function correctiveRetryWarnings(stage, call) {
+    if (call.corrective_retry?.outcome !== "succeeded") {
+        return [];
+    }
+    return [
+        delegateWarning(DELEGATE_JSON_CORRECTIVE_RETRY_WARNING_CODE, `${stage} returned malformed JSON once; one corrective retry succeeded`),
+    ];
+}
 function delegateWarning(code, message) {
     return {
         code: sanitizeDiagnosticText(code),
@@ -2423,6 +3042,15 @@ function reconcileContextBuilderWarnings(input) {
         return [];
     }
     return input.warnings.filter((warning) => {
+        // External-gap warnings name paths the packet never carried, so they can
+        // never be stale against the selection; their reason text is provider
+        // prose and may happen to use omission vocabulary. The corrective-retry
+        // notice names no evidence at all, so it is never stale either.
+        if (warning.code === "delegate_external_gaps" ||
+            warning.code === "delegate_external_gap" ||
+            warning.code === DELEGATE_JSON_CORRECTIVE_RETRY_WARNING_CODE) {
+            return true;
+        }
         const text = warning.message.toLowerCase();
         if (isStaleTruncationWarning(text, input)) {
             return false;