clinkx 0.3.0 → 1.1.0

package/dist/context-builder/delegate-packet.js

@@ -1,6 +1,7 @@
 import { boundContextBuilderOmissions, isRequestedEvidenceOmission, requestedEvidenceOmission, } from "./diagnostics.js";
 import { normalizeContextBuilderRootRelativePath, } from "./paths.js";
-import { scanHighConfidenceSecretContent, scanSecretPath } from "./secrets.js";
+import { orderEvidenceClasses, } from "./review-coverage.js";
+import { hasConservativeResidualSecret, scanSecretPath } from "./secrets.js";
 import { estimateContextBuilderTokensFromUtf8Bytes } from "./token-estimate.js";
 export const CONTEXT_BUILDER_DELEGATE_PACKET_CAP_DEFAULTS = Object.freeze({
     max_candidates: 300,
@@ -48,6 +49,11 @@ const MAX_CURATOR_PROPOSAL_RANGES_PER_SELECTION = 20;
 const MAX_CURATOR_PROPOSAL_WARNINGS = 50;
 const MAX_CURATOR_PROPOSAL_OPEN_QUESTIONS = 50;
 const MAX_DELEGATE_PACKET_JSON_BYTES = 92_000;
+// Neither packet bound is caller-tunable, so the only real lever is less
+// focused material.
+const PACKET_CAP_LEVER = "reduce or split focus_paths (workflow: cb_focus_paths)";
+const PACKET_JSON_BYTE_CAP_OMISSION_MESSAGE = `focused or selected coverage exceeded the fixed delegate packet size (${MAX_DELEGATE_PACKET_JSON_BYTES} JSON bytes, not configurable); ${PACKET_CAP_LEVER}`;
+const PACKET_TOKEN_CAP_OMISSION_MESSAGE = `focused or selected coverage was pruned from the delegate packet token budget; ${PACKET_CAP_LEVER}`;
 export function buildContextBuilderCuratorPacket(input) {
     return buildContextBuilderDelegatePacket("curator", input);
 }
@@ -62,8 +68,15 @@ export function contextBuilderRangeId(candidateId, startLine, endLine) {
 }
 function buildContextBuilderDelegatePacket(purpose, input) {
     const caps = normalizeCaps(input.caps, input.budget);
+    // Packet BUILD defaults allow-secrets ON to match the feature's global
+    // default (resolveAllowSecrets → true); the delegate VALIDATOR defaults
+    // fail-closed (?? false) as a conservative validation boundary. These never
+    // diverge on the live path — the handler always passes the resolved boolean
+    // to both. The asymmetry is intentional, not a missed seam.
+    const allowSecrets = input.allowSecrets ?? true;
     const state = {
         caps,
+        allowSecrets,
         evidenceBytes: 0,
         evidenceByteCapHit: false,
         searchIncluded: 0,
@@ -76,11 +89,13 @@ function buildContextBuilderDelegatePacket(purpose, input) {
         contextBuilderCandidateId(selected.root_index, selected.path),
         index,
     ]));
-    const selectedRanges = buildSelectedRangeIndex(input.selection.selected);
-    const evidence = buildCandidateEvidenceIndex(input);
-    const seeds = buildCandidateSeeds(input, selectedIds, selectedRanks, evidence).filter(shouldIncludeDelegateCandidateSeed);
+    const selectedRanges = buildSelectedRangeIndex(input.selection.selected, allowSecrets);
+    const evidence = buildCandidateEvidenceIndex(input, allowSecrets);
+    const coveragePolicy = normalizeCoveragePolicy(input.coveragePolicy, input.discovery.review_obligations, caps);
+    const seeds = orderCandidateSeedsForCoverage(buildCandidateSeeds(input, selectedIds, selectedRanks, evidence).filter(shouldIncludeDelegateCandidateSeed), coveragePolicy);
     const requestedCoverage = buildRequestedPacketCoverage(input, selectedRanges);
     const requestedCoverageIndex = buildRequestedCoverageIndex(requestedCoverage);
+    const protection = buildPacketProtectionIndex(input, allowSecrets);
     const candidates = seeds
         .map((seed) => buildPacketCandidate(seed, input, selectedRanges, requestedCoverageIndex, state))
         .filter((candidate) => candidate.ranges.length > 0)
@@ -88,11 +103,11 @@ function buildContextBuilderDelegatePacket(purpose, input) {
     const candidatesOmittedByCountCap = Math.max(0, seeds.length - candidates.length);
     const candidateLineCounts = new Map(candidates.map((candidate) => [candidate.id, candidate.line_count]));
     const candidateIds = new Set(candidateLineCounts.keys());
-    const deterministicSelection = buildDeterministicSelection(input.selection.selected, candidateIds);
+    const deterministicSelection = buildDeterministicSelection(input.selection.selected, candidateIds, allowSecrets);
     const packet = {
         version: "context-builder.delegate-packet.v1",
         purpose,
-        task: sanitizePacketText(input.task, caps.max_task_chars).text,
+        task: sanitizePacketText(input.task, caps.max_task_chars, allowSecrets).text,
         rules: {
             local_candidate_universe_only: true,
             provider_must_not_discover_paths: true,
@@ -101,12 +116,13 @@ function buildContextBuilderDelegatePacket(purpose, input) {
             raw_full_content_included: false,
         },
         budget: input.budget,
+        coverage_policy: coveragePolicy,
         candidates,
         deterministic_selection: {
             metrics: input.selection.metrics,
             selected: deterministicSelection,
         },
-        omissions: buildPacketOmissions(input.discovery.omissions, input.selection.omissions, caps),
+        omissions: buildPacketOmissions(input.discovery.omissions, input.selection.omissions, caps, allowSecrets),
         metrics: {
             discovery: input.discovery.metrics,
             selection: input.selection.metrics,
@@ -120,10 +136,23 @@ function buildContextBuilderDelegatePacket(purpose, input) {
             evidence_byte_cap_hit: state.evidenceByteCapHit,
             packet_estimated_tokens: 0,
             packet_token_cap_hit: false,
+            packet_json_byte_cap_hit: false,
+            compaction: {
+                candidates_before_compaction: candidates.length,
+                candidates_after_compaction: candidates.length,
+                candidates_evicted_by_compaction: 0,
+                evidence_bytes_before_compaction: 0,
+                evidence_bytes_after_compaction: 0,
+                search_records_before_compaction: 0,
+                search_records_after_compaction: 0,
+                slice_records_before_compaction: 0,
+                slice_records_after_compaction: 0,
+                all_non_focus_candidates_evidence_free: false,
+            },
         },
         ...(purpose === "finalizer" && "curator_proposal" in input
             ? {
-                curator_proposal: sanitizeCuratorProposal(input.curator_proposal, candidateLineCounts, caps),
+                curator_proposal: sanitizeCuratorProposal(input.curator_proposal, candidateLineCounts, caps, allowSecrets),
                 local_selection_summary: {
                     selected: deterministicSelection,
                 },
@@ -131,16 +160,17 @@ function buildContextBuilderDelegatePacket(purpose, input) {
             : {}),
     };
     syncSelectionSummariesToCandidateRanges(packet);
-    enforcePacketTokenCap(packet, caps, requestedCoverageIndex);
+    enforcePacketTokenCap(packet, caps, requestedCoverageIndex, protection);
     syncCandidateCoverageToPacketRanges(packet);
     syncSelectionSummariesToCandidateRanges(packet);
     appendMissingRequestedCoverageOmissions(packet, requestedCoverage);
     return packet;
 }
 function buildCandidateSeeds(input, selectedIds, selectedRanks, evidence) {
+    const allowSecrets = input.allowSecrets ?? true;
     const eligibleTree = new Map();
     for (const file of input.discovery.tree) {
-        const normalized = normalizePacketPath(file.path);
+        const normalized = normalizePacketPath(file.path, allowSecrets);
         if (normalized == null ||
             !file.eligible ||
             !file.content_eligible ||
@@ -154,7 +184,7 @@ function buildCandidateSeeds(input, selectedIds, selectedRanks, evidence) {
     }
     const seeds = [];
     for (const candidate of input.discovery.content_candidates) {
-        const normalized = normalizePacketPath(candidate.path);
+        const normalized = normalizePacketPath(candidate.path, allowSecrets);
         if (normalized == null) {
             continue;
         }
@@ -163,6 +193,7 @@ function buildCandidateSeeds(input, selectedIds, selectedRanks, evidence) {
             continue;
         }
         const id = contextBuilderCandidateId(candidate.root_index, normalized);
+        const classifiedCandidate = candidate;
         seeds.push({
             id,
             root_index: candidate.root_index,
@@ -175,6 +206,7 @@ function buildCandidateSeeds(input, selectedIds, selectedRanks, evidence) {
             has_focus_evidence: evidence.focusIds.has(id),
             has_slice_evidence: evidence.sliceIds.has(id),
             has_search_evidence: evidence.searchIds.has(id),
+            evidence_classes: orderEvidenceClasses(classifiedCandidate.evidence_classes ?? []),
         });
     }
     return seeds.sort(compareCandidateSeeds);
@@ -188,12 +220,12 @@ function shouldIncludeDelegateCandidateSeed(seed) {
 function isWorkbenchArtifactPath(path) {
     return path.startsWith(".ai/") || path.includes("/.ai/");
 }
-function buildCandidateEvidenceIndex(input) {
+function buildCandidateEvidenceIndex(input, allowSecrets) {
     const focusIds = new Set(input.discovery.slices
         .filter((slice) => slice.source === "focus")
         .map((slice) => contextBuilderCandidateId(slice.root_index, slice.path)));
     for (const candidate of input.discovery.content_candidates) {
-        const normalized = normalizePacketPath(candidate.path);
+        const normalized = normalizePacketPath(candidate.path, allowSecrets);
         if (normalized != null &&
             candidateMatchesFocusPath(candidate.root_index, normalized, input.focus_paths ?? [])) {
             focusIds.add(contextBuilderCandidateId(candidate.root_index, normalized));
@@ -232,6 +264,7 @@ function buildPacketCandidate(seed, input, selectedRanges, requestedCoverage, st
         size_bytes: seed.size_bytes,
         estimated_tokens: seed.estimated_tokens,
         discovery_reason: discoveryReason(ranges, searchHits),
+        evidence_classes: [...seed.evidence_classes],
         focus_requested: seed.has_focus_evidence,
         ...(requiredFocusRanges.length === 0
             ? {}
@@ -244,10 +277,10 @@ function buildPacketCandidate(seed, input, selectedRanges, requestedCoverage, st
         search_hits: searchHits,
     };
 }
-function buildSelectedRangeIndex(selected) {
+function buildSelectedRangeIndex(selected, allowSecrets) {
     const byCandidate = new Map();
     for (const file of selected) {
-        const normalized = normalizePacketPath(file.path);
+        const normalized = normalizePacketPath(file.path, allowSecrets);
         if (normalized == null) {
             continue;
         }
@@ -279,14 +312,14 @@ function buildRequestedPacketCoverage(input, selectedRanges) {
     };
     for (const [candidateId, ranges] of selectedRanges) {
         const selection = input.selection.selected.find((file) => {
-            const normalized = normalizePacketPath(file.path);
+            const normalized = normalizePacketPath(file.path, input.allowSecrets ?? true);
             return (normalized != null &&
                 contextBuilderCandidateId(file.root_index, normalized) === candidateId);
         });
         if (selection == null) {
             continue;
         }
-        const normalized = normalizePacketPath(selection.path);
+        const normalized = normalizePacketPath(selection.path, input.allowSecrets ?? true);
         if (normalized == null) {
             continue;
         }
@@ -298,7 +331,7 @@ function buildRequestedPacketCoverage(input, selectedRanges) {
         }
     }
     for (const slice of input.discovery.slices) {
-        const normalized = normalizePacketPath(slice.path);
+        const normalized = normalizePacketPath(slice.path, input.allowSecrets ?? true);
         if (normalized == null) {
             continue;
         }
@@ -314,6 +347,24 @@ function buildRequestedPacketCoverage(input, selectedRanges) {
             end_line: slice.end_line,
         });
     }
+    for (const target of input.discovery.review_obligations?.targets ?? []) {
+        for (const range of target.ranges) {
+            appendRange(target.root_index, target.path, {
+                id: contextBuilderRangeId(target.candidate_id, range.start_line, range.end_line),
+                start_line: range.start_line,
+                end_line: range.end_line,
+            });
+        }
+        for (const link of target.regression_links) {
+            for (const range of link.ranges) {
+                appendRange(link.root_index, link.path, {
+                    id: contextBuilderRangeId(link.candidate_id, range.start_line, range.end_line),
+                    start_line: range.start_line,
+                    end_line: range.end_line,
+                });
+            }
+        }
+    }
     return [...requestedByCandidate.values()].map((coverage) => ({
         ...coverage,
         ranges: coverage.ranges.sort((left, right) => left.start_line - right.start_line || left.end_line - right.end_line),
@@ -397,10 +448,10 @@ function buildSearchHits(seed, search, state) {
     }
     return hits;
 }
-function buildDeterministicSelection(selected, candidateIds) {
+function buildDeterministicSelection(selected, candidateIds, allowSecrets) {
     return selected
         .map((file) => {
-        const normalized = normalizePacketPath(file.path);
+        const normalized = normalizePacketPath(file.path, allowSecrets);
         if (normalized == null) {
             return undefined;
         }
@@ -424,7 +475,7 @@ function buildDeterministicSelection(selected, candidateIds) {
     })
         .filter((item) => item != null);
 }
-function sanitizeCuratorProposal(proposal, candidateLineCounts, caps) {
+function sanitizeCuratorProposal(proposal, candidateLineCounts, caps, allowSecrets) {
     const maxSelected = Math.min(caps.max_candidates, MAX_CURATOR_PROPOSAL_SELECTED);
     const maxRangesPerSelection = Math.min(caps.max_paths_per_omission, MAX_CURATOR_PROPOSAL_RANGES_PER_SELECTION);
     const maxWarnings = Math.min(caps.max_omissions, MAX_CURATOR_PROPOSAL_WARNINGS);
@@ -444,9 +495,9 @@ function sanitizeCuratorProposal(proposal, candidateLineCounts, caps) {
                     .map((range) => ({
                     start_line: range.start_line,
                     end_line: range.end_line,
-                    reason: sanitizePacketText(range.reason, caps.max_preview_bytes).text,
+                    reason: sanitizePacketText(range.reason, caps.max_preview_bytes, allowSecrets).text,
                 })),
-                reason: sanitizePacketText(selection.reason, caps.max_preview_bytes).text,
+                reason: sanitizePacketText(selection.reason, caps.max_preview_bytes, allowSecrets).text,
             };
         })
             .filter((selection) => selection != null && selection.ranges.length > 0)
@@ -454,13 +505,13 @@ function sanitizeCuratorProposal(proposal, candidateLineCounts, caps) {
             .slice(0, maxSelected),
         warnings: proposal.warnings
             .slice(0, maxWarnings)
-            .map((warning) => sanitizePacketText(warning, caps.max_preview_bytes).text),
+            .map((warning) => sanitizePacketText(warning, caps.max_preview_bytes, allowSecrets).text),
         open_questions: proposal.open_questions
             .slice(0, maxOpenQuestions)
-            .map((question) => sanitizePacketText(question, caps.max_preview_bytes).text),
+            .map((question) => sanitizePacketText(question, caps.max_preview_bytes, allowSecrets).text),
     };
 }
-function buildPacketOmissions(discoveryOmissions, selectionOmissions, caps) {
+function buildPacketOmissions(discoveryOmissions, selectionOmissions, caps, allowSecrets) {
     return boundContextBuilderOmissions([...discoveryOmissions, ...selectionOmissions].map((omission) => ({
         ...(omission.root_index == null ? {} : { root_index: omission.root_index }),
         reason: omission.reason,
@@ -469,7 +520,7 @@ function buildPacketOmissions(discoveryOmissions, selectionOmissions, caps) {
             ? {}
             : {
                 paths: omission.paths
-                    .map(normalizePacketPath)
+                    .map((path) => normalizePacketPath(path, allowSecrets))
                     .filter((item) => item != null),
             }),
     })), {
@@ -477,48 +528,212 @@ function buildPacketOmissions(discoveryOmissions, selectionOmissions, caps) {
         max_paths_per_omission: caps.max_paths_per_omission,
     });
 }
-function enforcePacketTokenCap(packet, caps, requestedCoverage) {
+function enforcePacketTokenCap(packet, caps, requestedCoverage, protection) {
     const maxTokens = Math.max(1, caps.max_packet_estimated_tokens);
+    const before = countPacketEvidence(packet);
+    const compaction = packet.metrics.compaction;
+    compaction.candidates_before_compaction = packet.candidates.length;
+    compaction.evidence_bytes_before_compaction = before.evidenceBytes;
+    compaction.search_records_before_compaction = before.searchRecords;
+    compaction.slice_records_before_compaction = before.sliceRecords;
+    refreshPacketCompactionState(packet);
     packet.metrics.packet_estimated_tokens = estimatePacketTokens(packet);
-    while (packet.metrics.packet_estimated_tokens > maxTokens ||
-        estimatePacketJsonBytes(packet) > MAX_DELEGATE_PACKET_JSON_BYTES) {
-        if (dropOneEvidence(packet)) {
-            packet.metrics.packet_token_cap_hit = true;
-            packet.metrics.packet_estimated_tokens = estimatePacketTokens(packet);
-            continue;
+    // Attribute pruning to the bound that actually binds. An oversized packet
+    // usually exceeds both at first, but only the tighter one decides where
+    // reduction stops; the fixed JSON-byte bound binds before the token bound
+    // at the default caps, and naming the wrong one sends callers after a lever
+    // that does not exist.
+    const jsonBytesTighter = estimateContextBuilderTokensFromUtf8Bytes(MAX_DELEGATE_PACKET_JSON_BYTES) <=
+        maxTokens;
+    const markBindingBound = (overTokens, overJsonBytes) => {
+        if (overJsonBytes && (!overTokens || jsonBytesTighter)) {
+            packet.metrics.packet_json_byte_cap_hit = true;
         }
-        if (dropOneCuratorProposalMetadata(packet)) {
+        else if (overTokens) {
             packet.metrics.packet_token_cap_hit = true;
-            packet.metrics.packet_estimated_tokens = estimatePacketTokens(packet);
+        }
+    };
+    while (true) {
+        const overTokens = packet.metrics.packet_estimated_tokens > maxTokens;
+        const overJsonBytes = estimatePacketJsonBytes(packet) > MAX_DELEGATE_PACKET_JSON_BYTES;
+        if (!overTokens && !overJsonBytes) {
+            return;
+        }
+        // Reduction ladder: evict low-value candidates before touching evidence,
+        // preserve one discriminative evidence item on protected candidates
+        // (focus, deterministic-baseline, exact-caller-hit) for as long as they
+        // remain in the packet, and only fall back to unrestricted stripping when
+        // nothing else can shrink the packet — caps stay hard.
+        const reduced = evictOneCompactionCandidate(packet, requestedCoverage, protection, "no_evidence") ||
+            evictOneCompactionCandidate(packet, requestedCoverage, protection, "unprotected") ||
+            dropOneCuratorProposalMetadata(packet) ||
+            dropOneEvidence(packet, protection) ||
+            dropOneCandidateRecord(packet, requestedCoverage, protection) ||
+            dropOneCandidate(packet, requestedCoverage) ||
+            dropOneEvidence(packet, null) ||
+            dropOneCandidateRecord(packet, requestedCoverage, null);
+        markBindingBound(overTokens, overJsonBytes);
+        refreshPacketCompactionState(packet);
+        packet.metrics.packet_estimated_tokens = estimatePacketTokens(packet);
+        if (!reduced) {
+            return;
+        }
+    }
+}
+function countPacketEvidence(packet) {
+    let evidenceBytes = 0;
+    let searchRecords = 0;
+    let sliceRecords = 0;
+    for (const candidate of packet.candidates) {
+        sliceRecords += candidate.ranges.length;
+        searchRecords += candidate.search_hits.length;
+        for (const range of candidate.ranges) {
+            evidenceBytes += Buffer.byteLength(range.excerpt, "utf8");
+        }
+        for (const hit of candidate.search_hits) {
+            evidenceBytes += Buffer.byteLength(hit.preview, "utf8");
+        }
+    }
+    return { evidenceBytes, searchRecords, sliceRecords };
+}
+function refreshPacketCompactionState(packet) {
+    const counts = countPacketEvidence(packet);
+    const compaction = packet.metrics.compaction;
+    compaction.candidates_after_compaction = packet.candidates.length;
+    compaction.candidates_evicted_by_compaction = Math.max(0, compaction.candidates_before_compaction - packet.candidates.length);
+    compaction.evidence_bytes_after_compaction = counts.evidenceBytes;
+    compaction.search_records_after_compaction = counts.searchRecords;
+    compaction.slice_records_after_compaction = counts.sliceRecords;
+    const nonFocusCandidates = packet.candidates.filter((candidate) => candidate.focus_requested !== true);
+    const evidenceFree = nonFocusCandidates.length > 0 &&
+        nonFocusCandidates.every((candidate) => !candidateHasEvidence(candidate));
+    compaction.all_non_focus_candidates_evidence_free = evidenceFree;
+    if (evidenceFree) {
+        packet.evidence_warning = {
+            code: "all_non_focus_candidates_evidence_free",
+            message: "packet compaction left every non-focus candidate without a search-hit preview or slice excerpt; non-focus candidates carry path metadata only",
+            non_focus_candidate_count: nonFocusCandidates.length,
+        };
+    }
+    else {
+        delete packet.evidence_warning;
+    }
+}
+function buildPacketProtectionIndex(input, allowSecrets) {
+    const callerTerms = new Set((input.caller_search_terms ?? [])
+        .map((term) => term.trim())
+        .filter((term) => term.length > 0));
+    const callerHitIds = new Set();
+    const callerTermIndexes = new Set();
+    if (callerTerms.size > 0) {
+        for (const record of input.discovery.search) {
+            if (!callerTerms.has(record.search_term.trim())) {
+                continue;
+            }
+            callerTermIndexes.add(record.search_term_index);
+            const normalized = normalizePacketPath(record.path, allowSecrets);
+            if (normalized != null) {
+                callerHitIds.add(contextBuilderCandidateId(record.root_index, normalized));
+            }
+        }
+    }
+    return { callerHitIds, callerTermIndexes };
+}
+function isProtectedPacketCandidate(candidate, protection) {
+    return (candidate.focus_requested === true ||
+        candidate.deterministic_selected ||
+        protection.callerHitIds.has(candidate.id));
+}
+function candidateHasEvidence(candidate) {
+    return (candidate.ranges.some((range) => range.excerpt.length > 0) ||
+        candidate.search_hits.some((hit) => hit.preview.length > 0));
+}
+function reservedEvidenceFor(candidate, protection) {
+    if (!isProtectedPacketCandidate(candidate, protection)) {
+        return null;
+    }
+    if (protection.callerHitIds.has(candidate.id)) {
+        const callerHitIndex = candidate.search_hits.findIndex((hit) => hit.preview.length > 0 &&
+            protection.callerTermIndexes.has(hit.search_term_index));
+        if (callerHitIndex >= 0) {
+            return { kind: "hit", index: callerHitIndex };
+        }
+    }
+    const rangeIndex = candidate.ranges.findIndex((range) => range.excerpt.length > 0);
+    if (rangeIndex >= 0) {
+        return { kind: "range", index: rangeIndex };
+    }
+    const hitIndex = candidate.search_hits.findIndex((hit) => hit.preview.length > 0);
+    if (hitIndex >= 0) {
+        return { kind: "hit", index: hitIndex };
+    }
+    return null;
+}
+function evictOneCompactionCandidate(packet, requestedCoverage, protection, mode) {
+    if (packet.candidates.length <= 1) {
+        return false;
+    }
+    for (let index = packet.candidates.length - 1; index >= 0; index -= 1) {
+        const candidate = packet.candidates[index];
+        if (candidate == null || isProtectedPacketCandidate(candidate, protection)) {
             continue;
         }
-        if (dropOneCandidateRecord(packet, requestedCoverage)) {
-            packet.metrics.packet_token_cap_hit = true;
-            packet.metrics.packet_estimated_tokens = estimatePacketTokens(packet);
+        if (mode === "no_evidence" && candidateHasEvidence(candidate)) {
             continue;
         }
-        if (dropOneCandidate(packet, requestedCoverage)) {
-            packet.metrics.packet_token_cap_hit = true;
-            packet.metrics.packet_estimated_tokens = estimatePacketTokens(packet);
+        if (requestedCoverage.has(candidate.id) ||
+            wouldRemoveCuratorProposalSelection(packet, candidate.id) ||
+            wouldRemoveRequiredEvidenceClass(packet, candidate)) {
             continue;
         }
-        packet.metrics.packet_token_cap_hit = true;
-        packet.metrics.packet_estimated_tokens = estimatePacketTokens(packet);
+        evictPacketCandidateAt(packet, index);
+        return true;
+    }
+    return false;
+}
+function evictPacketCandidateAt(packet, index) {
+    const candidate = packet.candidates[index];
+    if (candidate == null) {
         return;
     }
+    packet.candidates.splice(index, 1);
+    packet.metrics.candidates_included = packet.candidates.length;
+    packet.metrics.candidates_omitted_by_packet_cap += 1;
+    for (const range of candidate.ranges) {
+        packet.metrics.evidence_bytes -= Buffer.byteLength(range.excerpt, "utf8");
+    }
+    for (const hit of candidate.search_hits) {
+        packet.metrics.evidence_bytes -= Buffer.byteLength(hit.preview, "utf8");
+    }
+    packet.metrics.search_records_omitted_by_packet_cap += candidate.search_hits.length;
+    packet.metrics.slice_records_omitted_by_packet_cap += candidate.ranges.length;
+    pruneReferencesToCandidate(packet, candidate.id);
 }
-function dropOneEvidence(packet) {
+function dropOneEvidence(packet, protection) {
     for (const candidate of [...packet.candidates].reverse()) {
-        const range = candidate.ranges.at(-1);
-        if (range != null && range.excerpt.length > 0) {
+        const reserved = protection == null ? null : reservedEvidenceFor(candidate, protection);
+        for (let index = candidate.ranges.length - 1; index >= 0; index -= 1) {
+            if (reserved?.kind === "range" && reserved.index === index) {
+                continue;
+            }
+            const range = candidate.ranges[index];
+            if (range == null || range.excerpt.length === 0) {
+                continue;
+            }
             packet.metrics.evidence_bytes -= Buffer.byteLength(range.excerpt, "utf8");
             range.excerpt = "";
             range.excerpt_truncated = true;
             packet.metrics.evidence_byte_cap_hit = true;
             return true;
         }
-        const hit = candidate.search_hits.at(-1);
-        if (hit != null && hit.preview.length > 0) {
+        for (let index = candidate.search_hits.length - 1; index >= 0; index -= 1) {
+            if (reserved?.kind === "hit" && reserved.index === index) {
+                continue;
+            }
+            const hit = candidate.search_hits[index];
+            if (hit == null || hit.preview.length === 0) {
+                continue;
+            }
             packet.metrics.evidence_bytes -= Buffer.byteLength(hit.preview, "utf8");
             hit.preview = "";
             hit.preview_truncated = true;
@@ -553,22 +768,37 @@ function dropOneCuratorProposalMetadata(packet) {
     }
     return false;
 }
-function dropOneCandidateRecord(packet, requestedCoverage) {
+function dropOneCandidateRecord(packet, requestedCoverage, protection) {
     for (const candidate of [...packet.candidates].reverse()) {
-        const hit = candidate.search_hits.pop();
-        if (hit != null) {
+        const reserved = protection == null ? null : reservedEvidenceFor(candidate, protection);
+        for (let index = candidate.search_hits.length - 1; index >= 0; index -= 1) {
+            if (reserved?.kind === "hit" && reserved.index === index) {
+                continue;
+            }
+            const hit = candidate.search_hits[index];
+            if (hit == null) {
+                continue;
+            }
+            candidate.search_hits.splice(index, 1);
             packet.metrics.evidence_bytes -= Buffer.byteLength(hit.preview, "utf8");
             packet.metrics.search_records_omitted_by_packet_cap += 1;
             return true;
         }
         if (candidate.ranges.length > 1) {
-            const range = candidate.ranges.pop();
-            if (range != null) {
-                if (!curatorProposalStillCovered(packet, candidate.id, candidate.ranges) ||
-                    !requestedCoverageStillCovered(requestedCoverage, candidate.id, candidate.ranges)) {
-                    candidate.ranges.push(range);
+            for (let index = candidate.ranges.length - 1; index >= 0; index -= 1) {
+                if (reserved?.kind === "range" && reserved.index === index) {
+                    continue;
+                }
+                const range = candidate.ranges[index];
+                if (range == null) {
+                    continue;
+                }
+                const remaining = candidate.ranges.filter((_, rangeIndex) => rangeIndex !== index);
+                if (!curatorProposalStillCovered(packet, candidate.id, remaining) ||
+                    !requestedCoverageStillCovered(requestedCoverage, candidate.id, remaining)) {
                     continue;
                 }
+                candidate.ranges.splice(index, 1);
                 packet.metrics.evidence_bytes -= Buffer.byteLength(range.excerpt, "utf8");
                 packet.metrics.slice_records_omitted_by_packet_cap += 1;
                 pruneReferencesToRange(packet, candidate.id, range.id);
@@ -586,17 +816,21 @@ function dropOneCandidate(packet, requestedCoverage) {
         const candidate = packet.candidates[index];
         if (candidate == null ||
             requestedCoverage.has(candidate.id) ||
-            wouldRemoveCuratorProposalSelection(packet, candidate.id)) {
+            wouldRemoveCuratorProposalSelection(packet, candidate.id) ||
+            wouldRemoveRequiredEvidenceClass(packet, candidate)) {
             continue;
         }
-        packet.candidates.splice(index, 1);
-        packet.metrics.candidates_included = packet.candidates.length;
-        packet.metrics.candidates_omitted_by_packet_cap += 1;
-        pruneReferencesToCandidate(packet, candidate.id);
+        evictPacketCandidateAt(packet, index);
         return true;
     }
     return false;
 }
+function wouldRemoveRequiredEvidenceClass(packet, candidate) {
+    const required = new Set(packet.coverage_policy.required_when_available);
+    return candidate.evidence_classes.some((evidenceClass) => required.has(evidenceClass) &&
+        !packet.candidates.some((other) => other.id !== candidate.id &&
+            other.evidence_classes.includes(evidenceClass)));
+}
 function buildRequestedCoverageIndex(requestedCoverage) {
     return new Map(requestedCoverage.map((coverage) => [coverage.candidate_id, coverage.ranges]));
 }
@@ -662,12 +896,16 @@ function appendMissingRequestedCoverageOmissions(packet, requestedCoverage) {
         }
         packet.omissions.push(requestedEvidenceOmission({
             root_index: coverage.root_index,
-            kind: packet.metrics.packet_token_cap_hit
-                ? "packet_token_cap"
-                : "candidate_cap",
-            message: packet.metrics.packet_token_cap_hit
-                ? "focused or selected coverage was pruned from the delegate packet token budget"
-                : "focused or selected coverage could not be represented within delegate packet candidate caps",
+            kind: packet.metrics.packet_json_byte_cap_hit
+                ? "packet_json_byte_cap"
+                : packet.metrics.packet_token_cap_hit
+                    ? "packet_token_cap"
+                    : "candidate_cap",
+            message: packet.metrics.packet_json_byte_cap_hit
+                ? PACKET_JSON_BYTE_CAP_OMISSION_MESSAGE
+                : packet.metrics.packet_token_cap_hit
+                    ? PACKET_TOKEN_CAP_OMISSION_MESSAGE
+                    : "focused or selected coverage could not be represented within delegate packet candidate caps",
             paths: [coverage.path],
         }));
         existingRequestedOmissionPaths.add(coverage.path);
@@ -764,15 +1002,15 @@ function takeEvidenceText(text, maxBytes, state) {
         return { text: "", truncated: true };
     }
     const remaining = state.caps.max_total_evidence_bytes - state.evidenceBytes;
-    const bounded = sanitizePacketText(text, Math.min(maxBytes, remaining));
+    const bounded = sanitizePacketText(text, Math.min(maxBytes, remaining), state.allowSecrets);
     state.evidenceBytes += Buffer.byteLength(bounded.text, "utf8");
     if (bounded.truncated || state.evidenceBytes >= state.caps.max_total_evidence_bytes) {
         state.evidenceByteCapHit = true;
     }
     return bounded;
 }
-function sanitizePacketText(text, maxBytes) {
-    const secretSafe = scanHighConfidenceSecretContent(text).length > 0
+function sanitizePacketText(text, maxBytes, allowSecrets) {
+    const secretSafe = !allowSecrets && hasConservativeResidualSecret(text)
         ? "[redacted-sensitive]"
         : redactAbsolutePaths(text);
     return boundUtf8(secretSafe.replace(/\u0000/g, "?"), maxBytes);
@@ -791,7 +1029,7 @@ function boundUtf8(text, maxBytes) {
     }
     return { text: output, truncated: false };
 }
-function normalizePacketPath(input) {
+function normalizePacketPath(input, allowSecrets) {
     if (input.includes("\u0000") ||
         input.startsWith("/") ||
         input.startsWith("\\") ||
@@ -800,7 +1038,8 @@ function normalizePacketPath(input) {
     }
     try {
         const normalized = normalizeContextBuilderRootRelativePath(input);
-        if (normalized === "" || scanSecretPath(normalized).length > 0) {
+        if (normalized === "" ||
+            (!allowSecrets && scanSecretPath(normalized).length > 0)) {
             return undefined;
         }
         return normalized;
@@ -828,6 +1067,101 @@ function normalizeCaps(caps, budget) {
         max_packet_estimated_tokens: positiveInteger(merged.max_packet_estimated_tokens),
     };
 }
+/**
+ * Observability-only count of what normalizeCoveragePolicy sliced off the
+ * review obligations it serializes into the packet. Terminal coverage
+ * evaluation (review-coverage.ts) always uses the FULL discovery obligation
+ * set, so a delegate can satisfy every packet obligation and the run can still
+ * report degraded coverage. Returns undefined when nothing was sliced.
+ * "ranges" counts target ranges plus regression-link ranges.
+ */
+export function countDelegatePacketObligationTruncation(fullObligations, packetPolicy) {
+    if (fullObligations == null || packetPolicy.obligations == null) {
+        return undefined;
+    }
+    const tally = (model) => ({
+        targets: model.targets.length,
+        ranges: model.targets.reduce((total, target) => total +
+            target.ranges.length +
+            target.regression_links.reduce((linkTotal, link) => linkTotal + link.ranges.length, 0), 0),
+        links: model.targets.reduce((total, target) => total + target.regression_links.length, 0),
+    });
+    const full = tally(fullObligations);
+    const included = tally(packetPolicy.obligations);
+    if (full.targets === included.targets &&
+        full.ranges === included.ranges &&
+        full.links === included.links) {
+        return undefined;
+    }
+    return {
+        targets_total: full.targets,
+        targets_included: included.targets,
+        ranges_total: full.ranges,
+        ranges_included: included.ranges,
+        regression_links_total: full.links,
+        regression_links_included: included.links,
+    };
+}
+function normalizeCoveragePolicy(policy, obligations, caps) {
+    if (policy?.id !== "review_deep_v1") {
+        return { policy_id: null, required_when_available: [] };
+    }
+    return {
+        policy_id: policy.id,
+        required_when_available: orderEvidenceClasses(policy.required_when_available),
+        ...(obligations == null
+            ? {}
+            : {
+                obligations: {
+                    targets: obligations.targets.slice(0, caps.max_candidates).map((target) => ({
+                        ...target,
+                        ranges: target.ranges.slice(0, caps.max_paths_per_omission),
+                        regression_links: target.regression_links
+                            .slice(0, caps.max_candidates)
+                            .map((link) => ({
+                            ...link,
+                            ranges: link.ranges.slice(0, caps.max_paths_per_omission),
+                        })),
+                    })),
+                },
+            }),
+    };
+}
+function orderCandidateSeedsForCoverage(seeds, policy) {
+    if (policy.policy_id === null || policy.required_when_available.length === 0) {
+        return [...seeds];
+    }
+    const ordered = [];
+    const included = new Set();
+    for (const target of policy.obligations?.targets ?? []) {
+        for (const candidateId of [
+            target.candidate_id,
+            ...target.regression_links.map((link) => link.candidate_id),
+        ]) {
+            const seed = seeds.find((candidate) => candidate.id === candidateId);
+            if (seed != null && !included.has(seed.id)) {
+                ordered.push(seed);
+                included.add(seed.id);
+            }
+        }
+    }
+    for (const evidenceClass of policy.required_when_available) {
+        if (ordered.some((seed) => seed.evidence_classes.includes(evidenceClass))) {
+            continue;
+        }
+        const representative = seeds.find((seed) => seed.evidence_classes.includes(evidenceClass));
+        if (representative != null && !included.has(representative.id)) {
+            ordered.push(representative);
+            included.add(representative.id);
+        }
+    }
+    for (const seed of seeds) {
+        if (!included.has(seed.id)) {
+            ordered.push(seed);
+        }
+    }
+    return ordered;
+}
 function positiveInteger(value) {
     return Number.isSafeInteger(value) && value > 0 ? value : 1;
 }
@@ -858,7 +1192,29 @@ function estimatePacketJsonBytes(packet) {
 function redactAbsolutePaths(text) {
     return text
         .replace(/\b[A-Za-z]:[\\/][^\s"'`)]+/g, "[redacted-absolute-path]")
-        .replace(/(^|[\s"'(])\/[^\s"'`)]+/g, "$1[redacted-absolute-path]");
+        .replace(/(^|[\s"'(])(\/[^\s"'`)]+)/g, (_match, boundary, token) => {
+        // Compact comments and slash-led paths share the same token shape, so
+        // classify the complete token instead of inferring intent via lookahead.
+        if (token === "/*") {
+            return `${boundary}${token}`;
+        }
+        if (token.startsWith("/*") && token[2] !== "/") {
+            const closeIndex = token.indexOf("*/", 2);
+            if (closeIndex >= 0) {
+                const commentEnd = closeIndex + 2;
+                const suffix = token.slice(commentEnd);
+                return /^[\\/]/.test(suffix)
+                    ? `${boundary}${token.slice(0, commentEnd)}[redacted-absolute-path]`
+                    : `${boundary}${token}`;
+            }
+        }
+        // A bare //host is indistinguishable from //comment; preserving it is
+        // an accepted residual limitation needed for compact comment fidelity.
+        if (/^\/\/[^/\\]*$/.test(token)) {
+            return `${boundary}${token}`;
+        }
+        return `${boundary}[redacted-absolute-path]`;
+    });
 }
 function compareCandidateSeeds(left, right) {
     return (booleanRank(right.has_focus_evidence) - booleanRank(left.has_focus_evidence) ||