@oscharko-dev/keiko 0.2.0-beta.3 → 0.2.0-beta.5

package/node_modules/@oscharko-dev/keiko-server/dist/grounded-orchestrator.js

@@ -8,14 +8,16 @@
 // Pure orchestration: the only IO this module performs is delegated through the workspace
 // package's already-bounded WorkspaceFs port. Path validation is enforced by every composed
 // layer at its own boundary, so this file does not re-validate scope paths.
+import { createHash } from "node:crypto";
 import { isValidScopePath, } from "@oscharko-dev/keiko-contracts/connected-context";
-import { advanceRing, applyUsage, assembleContextPack, canContinue, complete, planAndGovern, rankCandidates, } from "@oscharko-dev/keiko-workflows";
-import { DEFAULT_SEARCH_LIMITS, FileTooLargeError, RepoSearchUnsupportedFileError, detectWorkspaceAt, gitHistoryAdapter, importGraphAdapter, readExcerpt, runStructuralAdapters, searchText, testSourcePairingAdapter, } from "@oscharko-dev/keiko-workspace";
+import { advanceRing, applyUsage, assembleContextPack, canContinue, complete, contextPackIndexKey, planAndGovern, rankCandidates, } from "@oscharko-dev/keiko-workflows";
+import { DEFAULT_SEARCH_LIMITS, FileTooLargeError, RepoSearchUnsupportedFileError, detectWorkspaceAt, gitHistoryAdapter, importGraphAdapter, readExcerpt, resolveWithinWorkspace, runStructuralAdapters, searchText, testSourcePairingAdapter, containedRealPathInfo, evidenceAtomStableId, } from "@oscharko-dev/keiko-workspace";
 import { CancelledError } from "@oscharko-dev/keiko-model-gateway";
 import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
 import { normalizeGroundedAnswerPayload } from "./grounded-answer.js";
 // Raised when the planner asks for clarification (no anchors, too-generic prompt, etc.). The
-// route maps this to a 400 BAD_REQUEST with the planner's clarification reason in the message.
+// route maps this to a 400 BAD_REQUEST via clarificationUserMessage below; the Error message
+// itself keeps the stable machine-ish form for logs and tests.
 export class ClarificationNeededError extends Error {
     clarification;
     constructor(clarification) {
@@ -24,20 +26,24 @@ export class ClarificationNeededError extends Error {
         this.name = "ClarificationNeededError";
     }
 }
-// ─── Default deterministic answerer ───────────────────────────────────────────
-export const echoAnswerer = {
-    answer: (question, pack) => {
-        try {
-            const filePaths = pack.files.map((f) => f.scopePath).join(", ");
-            const summary = `Inspected ${String(pack.files.length)} file(s) for: ${question}. ` +
-                `Findings include: ${filePaths.length === 0 ? "(no evidence)" : filePaths}.`;
-            return Promise.resolve(summary);
-        }
-        catch (error) {
-            return Promise.reject(error instanceof Error ? error : new Error(String(error)));
-        }
-    },
-};
+// Release 0.2.0 — user-facing mapping for a planner clarification. The raw reason string
+// ("clarification needed: too-generic") told the user nothing actionable; the HTTP message now
+// says what the planner needs and folds in the planner's own suggested questions. Static text
+// plus planner-built suggestions only — no user/file content, so nothing to redact.
+export function clarificationUserMessage(error) {
+    const { reason, suggestedQuestions } = error.clarification;
+    const intro = reason === "scope-empty"
+        ? "The connected source contains nothing searchable."
+        : reason === "scope-invalid"
+            ? "The connected source could not be searched."
+            : "Your question is too broad to search the connected sources.";
+    const anchorHint = reason === "no-anchors" || reason === "too-generic"
+        ? " Mention a concrete file name, identifier, or exact phrase so Keiko knows where to look."
+        : "";
+    const examples = suggestedQuestions.slice(0, 2);
+    const exampleText = examples.length > 0 ? ` For example: ${examples.map((q) => `"${q}"`).join(" or ")}` : "";
+    return `${intro}${anchorHint}${exampleText}`;
+}
 const TEXT_ENCODER = new TextEncoder();
 function throwIfCancelled(signal) {
     if (signal?.aborted === true) {
@@ -78,6 +84,14 @@ function budgetClipped(stopReason, nowMs) {
         emittedAtMs: nowMs,
     };
 }
+function answerBudgetClipped(dimensions, nowMs) {
+    return {
+        kind: "budget-clipped",
+        claim: `grounded answer exceeded budget: ${dimensions.join(", ")}`,
+        impactedAtomIds: [],
+        emittedAtMs: nowMs,
+    };
+}
 function noEvidence(nowMs) {
     return {
         kind: "no-evidence",
@@ -86,6 +100,14 @@ function noEvidence(nowMs) {
         emittedAtMs: nowMs,
     };
 }
+function toolUnavailable(claim, nowMs) {
+    return {
+        kind: "tool-unavailable",
+        claim,
+        impactedAtomIds: [],
+        emittedAtMs: nowMs,
+    };
+}
 function readBudgetStopReason(budget) {
     const exhausted = [
         ...(budget.filesReadMax <= 0 ? ["filesRead"] : []),
@@ -113,6 +135,97 @@ function omittedFromSearchCandidates(candidates, nowMs) {
     }
     return omitted;
 }
+function safeAdapterName(name) {
+    const cleaned = name.replace(/[^a-zA-Z0-9._-]/g, "");
+    return cleaned.length === 0 ? "structural-adapter" : cleaned;
+}
+function adapterDiagnostics(result, nowMs) {
+    const markers = [];
+    const seen = new Set();
+    for (const name of result.unavailable) {
+        const safeName = safeAdapterName(name);
+        if (seen.has(`unavailable:${safeName}`)) {
+            continue;
+        }
+        seen.add(`unavailable:${safeName}`);
+        markers.push(toolUnavailable(`structural adapter unavailable: ${safeName}`, nowMs));
+    }
+    for (const error of result.errored) {
+        const safeName = safeAdapterName(error.name);
+        if (seen.has(`errored:${safeName}`)) {
+            continue;
+        }
+        seen.add(`errored:${safeName}`);
+        markers.push(toolUnavailable(`structural adapter failed safely: ${safeName}`, nowMs));
+    }
+    return markers;
+}
+function dedupeUncertainty(markers) {
+    const seen = new Set();
+    const out = [];
+    for (const marker of markers) {
+        const key = `${marker.kind}:${marker.claim}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(marker);
+    }
+    return out;
+}
+function anchorKindForTerm(term, anchors) {
+    return anchors.find((anchor) => anchor.term === term)?.kind;
+}
+function looksPathAnchor(term) {
+    return term.includes("/") || /\.[a-z0-9]+$/i.test(term);
+}
+function queryForStructuralAnchor(term, kind, base) {
+    return {
+        ...base,
+        kind: kind === "identifier" || (!looksPathAnchor(term) && kind !== "path")
+            ? "exact-symbol"
+            : "natural-language",
+        text: term,
+    };
+}
+function structuralQueriesForRing(ring, inputs) {
+    const queries = [];
+    const seen = new Set();
+    for (const term of ring.anchorTerms) {
+        const anchorKind = anchorKindForTerm(term, inputs.anchors);
+        if (anchorKind !== "path" && anchorKind !== "identifier" && anchorKind !== "quoted") {
+            continue;
+        }
+        const query = queryForStructuralAnchor(term, anchorKind, inputs.query);
+        const key = `${query.kind}:${query.text}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        queries.push(query);
+    }
+    return queries.length === 0 ? [inputs.query] : queries;
+}
+function plannedSearchCallsForRing(ring, inputs) {
+    return ring.kind === "structural" ? structuralQueriesForRing(ring, inputs).length : 1;
+}
+function mergeAtomsByStableId(results, cap) {
+    const atoms = [];
+    const seen = new Set();
+    for (const result of results) {
+        for (const atom of result.atoms) {
+            if (atoms.length >= cap) {
+                return atoms;
+            }
+            if (seen.has(atom.stableId)) {
+                continue;
+            }
+            seen.add(atom.stableId);
+            atoms.push(atom);
+        }
+    }
+    return atoms;
+}
 async function runRing(ring, inputs) {
     if (ring.kind === "lexical") {
         const result = await searchText(inputs.searchScope, inputs.query, ring.searchLimits, {
@@ -128,6 +241,7 @@ async function runRing(ring, inputs) {
         return {
             atoms: result.atoms,
             omitted: omittedFromSearchCandidates(result.candidates, inputs.nowMs()),
+            uncertainty: [],
             usage: usageDelta({ elapsedMs: result.elapsedMs }),
         };
     }
@@ -138,11 +252,29 @@ async function runRing(ring, inputs) {
     const registry = ring.kind === "structural"
         ? { adapters: [testSourcePairingAdapter, importGraphAdapter] }
         : { adapters: [gitHistoryAdapter] };
-    const result = await runStructuralAdapters(registry, inputs.searchScope, inputs.query, ring.searchLimits, inputs.fs, { nowMs: inputs.nowMs });
+    const queries = ring.kind === "structural" ? structuralQueriesForRing(ring, inputs) : [inputs.query];
+    const results = await Promise.all(queries.map((query) => runStructuralAdapters(registry, inputs.searchScope, query, ring.searchLimits, inputs.fs, {
+        nowMs: inputs.nowMs,
+    })));
+    const elapsedMs = results.reduce((sum, result) => sum + result.elapsedMs, 0);
+    const cap = Math.min(ring.searchLimits.maxMatchesReturned, inputs.query.maxResults);
+    const atoms = ring.kind === "git-history" ? [] : mergeAtomsByStableId(results, cap);
+    const uncertainty = dedupeUncertainty(results.flatMap((result) => adapterDiagnostics(result, inputs.nowMs())));
     return {
-        atoms: result.atoms,
+        atoms,
         omitted: [],
-        usage: usageDelta({ elapsedMs: result.elapsedMs }),
+        uncertainty,
+        usage: usageDelta({ elapsedMs }),
+    };
+}
+function reserveRingSearchCalls(governor, ring, inputs) {
+    const reserved = applyUsage(governor, usageDelta({ searchCalls: plannedSearchCallsForRing(ring, inputs) }));
+    if (reserved.status !== "budget-exhausted") {
+        return { governor: reserved };
+    }
+    return {
+        governor: reserved,
+        marker: budgetClipped(reserved.stopReason ?? "budget exhausted", inputs.nowMs()),
     };
 }
 async function runAllRings(rings, inputs, initialGovernor) {
@@ -164,19 +296,18 @@ async function runAllRings(rings, inputs, initialGovernor) {
         if (!canContinue(governor)) {
             break;
         }
-        const reservedSearchCall = applyUsage(governor, usageDelta({ searchCalls: 1 }));
-        if (reservedSearchCall.status === "budget-exhausted") {
-            governor = reservedSearchCall;
-            uncertainty.push(budgetClipped(reservedSearchCall.stopReason ?? "budget exhausted", inputs.nowMs()));
+        const reservation = reserveRingSearchCalls(governor, ring, inputs);
+        governor = reservation.governor;
+        if (reservation.marker !== undefined) {
+            uncertainty.push(reservation.marker);
             break;
         }
-        governor = reservedSearchCall;
         const result = await runRing(ring, inputs);
         throwIfCancelled(inputs.signal);
         const afterRing = applyUsage(governor, result.usage);
-        const ringAtoms = result.atoms;
-        atoms.push(...ringAtoms);
+        atoms.push(...result.atoms);
         omitted.push(...result.omitted);
+        uncertainty.push(...result.uncertainty);
         if (afterRing.status === "budget-exhausted") {
             governor = afterRing;
             uncertainty.push(budgetClipped(afterRing.stopReason ?? "budget exhausted", inputs.nowMs()));
@@ -192,6 +323,324 @@ async function runAllRings(rings, inputs, initialGovernor) {
 const DEFAULT_EXCERPT_WINDOW = { startLine: 1, endLine: 200 };
 const EXCERPT_CONTEXT_LINES = 2;
 const MAX_EXCERPT_WINDOWS_PER_FILE = 8;
+const PROJECT_METADATA_QUERY_TERMS = [
+    "abhängigkeit",
+    "abhängigkeiten",
+    "build",
+    "cypress",
+    "dependenc",
+    "framework",
+    "jest",
+    "npm",
+    "package",
+    "playwright",
+    "pnpm",
+    "react",
+    "script",
+    "stack",
+    "tech-stack",
+    "techstack",
+    "test",
+    "testing",
+    "testumgebung",
+    "typescript",
+    "vite",
+    "vitest",
+    "yarn",
+];
+const PROJECT_METADATA_FILENAMES = [
+    "package.json",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "vitest.config.js",
+    "vitest.config.mjs",
+    "vitest.setup.ts",
+    "vite.config.ts",
+    "vite.config.mts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "jest.config.ts",
+    "jest.config.js",
+    "jest.config.mjs",
+    "playwright.config.ts",
+    "playwright.config.js",
+    "cypress.config.ts",
+    "cypress.config.js",
+    "next.config.ts",
+    "next.config.js",
+    "next.config.mjs",
+    "tsconfig.json",
+    "eslint.config.ts",
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "postcss.config.js",
+    "postcss.config.mjs",
+];
+const LOCKFILE_NAMES = new Set([
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+    "cargo.lock",
+    "composer.lock",
+    "gemfile.lock",
+]);
+function basename(scopePath) {
+    const index = scopePath.lastIndexOf("/");
+    return index >= 0 ? scopePath.slice(index + 1) : scopePath;
+}
+function compareByScopePath(a, b) {
+    return a.scopePath.localeCompare(b.scopePath);
+}
+function isKeikoEvidenceArtifact(scopePath) {
+    return scopePath.toLowerCase().startsWith(".keiko/evidence/");
+}
+function isLockfilePath(scopePath) {
+    return LOCKFILE_NAMES.has(basename(scopePath).toLowerCase());
+}
+function dirname(scopePath) {
+    const index = scopePath.lastIndexOf("/");
+    return index <= 0 ? "" : scopePath.slice(0, index);
+}
+function joinScopePath(base, filename) {
+    return base.length === 0 ? filename : `${base}/${filename}`;
+}
+function projectMetadataQueryFingerprint(query) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        kind: "project-metadata",
+        queryKind: query.kind,
+        text: query.text,
+        caseSensitive: query.caseSensitive,
+    }))
+        .digest("hex")
+        .slice(0, 16);
+}
+function selectedFileQueryFingerprint(query) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        kind: "explicit-selected-file",
+        queryKind: query.kind,
+        text: query.text,
+        caseSensitive: query.caseSensitive,
+    }))
+        .digest("hex")
+        .slice(0, 16);
+}
+function wantsProjectMetadata(queryText) {
+    const lowered = queryText.toLowerCase();
+    return PROJECT_METADATA_QUERY_TERMS.some((term) => lowered.includes(term));
+}
+function metadataRootsForScope(scope) {
+    if (scope.relativePaths.length === 0) {
+        return [""];
+    }
+    const roots = new Set();
+    for (const entry of scope.relativePaths) {
+        if (!isValidScopePath(entry, { mustBeRelative: true })) {
+            continue;
+        }
+        roots.add(scope.kind === "files" ? dirname(entry) : entry);
+    }
+    return [...roots].sort();
+}
+function metadataAtom(scope, scopePath, queryFingerprint, nowMs) {
+    return {
+        schemaVersion: scope.schemaVersion,
+        stableId: evidenceAtomStableId({
+            scopeId: scope.scopeId,
+            scopePath,
+            lineRange: undefined,
+            provenanceKind: "file-listing",
+            provenanceTool: "repo.projectMetadata",
+            queryFingerprint,
+        }),
+        scopePath,
+        lineRange: undefined,
+        score: 1,
+        provenance: {
+            kind: "file-listing",
+            tool: "repo.projectMetadata",
+            queryFingerprint,
+        },
+        redactionState: "redacted",
+        emittedAtMs: nowMs(),
+        ledgerRef: undefined,
+    };
+}
+function selectedFileAtom(scope, scopePath, queryFingerprint, nowMs) {
+    return {
+        schemaVersion: scope.schemaVersion,
+        stableId: evidenceAtomStableId({
+            scopeId: scope.scopeId,
+            scopePath,
+            lineRange: undefined,
+            provenanceKind: "file-listing",
+            provenanceTool: "repo.selectedFile",
+            queryFingerprint,
+        }),
+        scopePath,
+        lineRange: undefined,
+        score: 1,
+        provenance: {
+            kind: "file-listing",
+            tool: "repo.selectedFile",
+            queryFingerprint,
+        },
+        redactionState: "redacted",
+        emittedAtMs: nowMs(),
+        ledgerRef: undefined,
+    };
+}
+function fileExistsInSearchScope(searchScope, fs, scopePath) {
+    try {
+        const abs = resolveWithinWorkspace(searchScope.workspace.root, scopePath);
+        const contained = containedRealPathInfo(fs, searchScope.workspace.root, abs);
+        return fs.stat(contained.path).isFile;
+    }
+    catch {
+        return false;
+    }
+}
+function selectedFileScopeAtoms(input, searchScope, fs, nowMs) {
+    if (input.scope.explicitConnection !== true || input.scope.kind !== "files") {
+        return [];
+    }
+    const atoms = [];
+    const seen = new Set();
+    const queryFingerprint = selectedFileQueryFingerprint(input.query);
+    for (const entry of input.scope.relativePaths) {
+        if (!isValidScopePath(entry, { mustBeRelative: true })) {
+            continue;
+        }
+        const scopePath = entry.replace(/\\/gu, "/");
+        if (seen.has(scopePath)) {
+            continue;
+        }
+        seen.add(scopePath);
+        if (fileExistsInSearchScope(searchScope, fs, scopePath)) {
+            atoms.push(selectedFileAtom(input.scope, scopePath, queryFingerprint, nowMs));
+        }
+    }
+    return atoms;
+}
+function projectMetadataAtoms(input, searchScope, fs, nowMs) {
+    if (!wantsProjectMetadata(input.query.text)) {
+        return [];
+    }
+    const atoms = [];
+    const seen = new Set();
+    const queryFingerprint = projectMetadataQueryFingerprint(input.query);
+    for (const root of metadataRootsForScope(input.scope)) {
+        for (const filename of PROJECT_METADATA_FILENAMES) {
+            const scopePath = joinScopePath(root, filename);
+            if (seen.has(scopePath) || !isValidScopePath(scopePath, { mustBeRelative: true })) {
+                continue;
+            }
+            seen.add(scopePath);
+            if (fileExistsInSearchScope(searchScope, fs, scopePath)) {
+                atoms.push(metadataAtom(input.scope, scopePath, queryFingerprint, nowMs));
+            }
+        }
+    }
+    return atoms;
+}
+function withProjectMetadataAtoms(rings, input, searchScope, fs, nowMs) {
+    const metadataAtoms = projectMetadataAtoms(input, searchScope, fs, nowMs);
+    return metadataAtoms.length === 0
+        ? rings
+        : { ...rings, atoms: [...rings.atoms, ...metadataAtoms] };
+}
+function withExplicitScopeAtoms(rings, input, searchScope, fs, nowMs) {
+    const selectedAtoms = selectedFileScopeAtoms(input, searchScope, fs, nowMs);
+    return selectedAtoms.length === 0
+        ? rings
+        : { ...rings, atoms: [...selectedAtoms, ...rings.atoms] };
+}
+function queryTerms(queryText, anchors) {
+    const terms = new Set();
+    const loweredQuery = queryText.toLowerCase();
+    for (const token of loweredQuery.split(/[^a-z0-9._/-]+/)) {
+        if (token.length > 0) {
+            terms.add(token);
+        }
+    }
+    for (const anchor of anchors) {
+        const lowered = anchor.term.toLowerCase();
+        if (lowered.length > 0) {
+            terms.add(lowered);
+        }
+        for (const token of lowered.split(/[^a-z0-9._/-]+/)) {
+            if (token.length > 0) {
+                terms.add(token);
+            }
+        }
+    }
+    return [...terms];
+}
+function explicitlyTargetsRuntimeArtifact(scopePath, queryText, anchors) {
+    if (!isKeikoEvidenceArtifact(scopePath)) {
+        return false;
+    }
+    const loweredQuery = queryText.toLowerCase();
+    if (loweredQuery.includes(".keiko") || loweredQuery.includes("evidence artifact")) {
+        return true;
+    }
+    return queryTerms(queryText, anchors).some((term) => scopePath.toLowerCase().includes(term));
+}
+function explicitlyTargetsLockfile(scopePath, queryText, anchors) {
+    if (!isLockfilePath(scopePath)) {
+        return false;
+    }
+    const loweredQuery = queryText.toLowerCase();
+    if (loweredQuery.includes("lockfile") ||
+        loweredQuery.includes("package manager") ||
+        loweredQuery.includes("packagemanager") ||
+        loweredQuery.includes("dependency version") ||
+        loweredQuery.includes("dependency versions") ||
+        loweredQuery.includes("resolved version") ||
+        loweredQuery.includes("resolved versions")) {
+        return true;
+    }
+    const path = scopePath.toLowerCase();
+    const name = basename(scopePath).toLowerCase();
+    return queryTerms(queryText, anchors).some((term) => path.includes(term) || name === term);
+}
+function refineCandidateOrdering(kept, omitted, queryText, anchors, nowMs) {
+    const preferred = [];
+    const lockfiles = [];
+    const runtimeArtifacts = [];
+    for (const candidate of kept) {
+        const scopePath = candidate.scopePath;
+        if (isKeikoEvidenceArtifact(scopePath) &&
+            !explicitlyTargetsRuntimeArtifact(scopePath, queryText, anchors)) {
+            runtimeArtifacts.push(candidate);
+            continue;
+        }
+        if (isLockfilePath(scopePath) && !explicitlyTargetsLockfile(scopePath, queryText, anchors)) {
+            lockfiles.push(candidate);
+            continue;
+        }
+        preferred.push(candidate);
+    }
+    if (preferred.length === 0) {
+        return { kept, omitted };
+    }
+    const nextOmitted = [...omitted];
+    for (const candidate of runtimeArtifacts) {
+        nextOmitted.push({
+            scopePath: candidate.scopePath,
+            reason: "low-relevance",
+            omittedAtMs: nowMs,
+        });
+    }
+    nextOmitted.sort(compareByScopePath);
+    return {
+        kept: [...preferred, ...lockfiles],
+        omitted: nextOmitted,
+    };
+}
 function groupEvidenceAtomsByPath(atoms) {
     const grouped = new Map();
     for (const atom of atoms) {
@@ -231,11 +680,35 @@ function mergeLineWindows(windows) {
     }
     return merged;
 }
+function windowContainsAtom(window, atom) {
+    const range = atom.lineRange;
+    return (range === undefined || (window.startLine <= range.startLine && window.endLine >= range.endLine));
+}
+function strongestAtomScoreForWindow(window, atomsForPath) {
+    let score = 0;
+    for (const atom of atomsForPath) {
+        if (windowContainsAtom(window, atom) && atom.score > score) {
+            score = atom.score;
+        }
+    }
+    return score;
+}
 function excerptLineWindows(atomsForPath) {
     if (atomsForPath === undefined || atomsForPath.length === 0) {
-        return [DEFAULT_EXCERPT_WINDOW];
+        return { windows: [DEFAULT_EXCERPT_WINDOW], omittedWindowCount: 0 };
     }
-    return mergeLineWindows(atomsForPath.map(lineWindowForAtom)).slice(0, MAX_EXCERPT_WINDOWS_PER_FILE);
+    const merged = mergeLineWindows(atomsForPath.map(lineWindowForAtom));
+    const selected = [...merged]
+        .sort((a, b) => {
+        const scoreDelta = strongestAtomScoreForWindow(b, atomsForPath) - strongestAtomScoreForWindow(a, atomsForPath);
+        return scoreDelta === 0 ? a.startLine - b.startLine : scoreDelta;
+    })
+        .slice(0, MAX_EXCERPT_WINDOWS_PER_FILE)
+        .sort((a, b) => a.startLine === b.startLine ? a.endLine - b.endLine : a.startLine - b.startLine);
+    return {
+        windows: selected,
+        omittedWindowCount: Math.max(0, merged.length - selected.length),
+    };
 }
 function exhaustedDimensions(remainingFiles, remainingBytes) {
     return [
@@ -246,7 +719,8 @@ function exhaustedDimensions(remainingFiles, remainingBytes) {
 async function readPathExcerptWindows(scopePath, inputs, remainingBytes) {
     const windows = [];
     let bytesConsumed = 0;
-    for (const window of excerptLineWindows(inputs.atomsByPath.get(scopePath))) {
+    const selection = excerptLineWindows(inputs.atomsByPath.get(scopePath));
+    for (const window of selection.windows) {
         throwIfCancelled(inputs.signal);
         const availableBytes = remainingBytes - bytesConsumed;
         if (availableBytes <= 0) {
@@ -258,7 +732,7 @@ async function readPathExcerptWindows(scopePath, inputs, remainingBytes) {
         windows.push({ ...window, content: result.content });
         bytesConsumed += utf8ByteLength(result.content);
     }
-    return { windows, bytesConsumed };
+    return { windows, bytesConsumed, omittedWindowCount: selection.omittedWindowCount };
 }
 async function readKeptExcerpts(keptPaths, inputs) {
     const excerpts = new Map();
@@ -277,6 +751,14 @@ async function readKeptExcerpts(keptPaths, inputs) {
             const { windows } = result;
             if (windows.length > 0) {
                 excerpts.set(scopePath, windows);
+                if (result.omittedWindowCount > 0) {
+                    uncertainty.push({
+                        kind: "scope-incomplete",
+                        claim: `excerpt window limit omitted ${String(result.omittedWindowCount)} additional matching range(s) in ${scopePath}`,
+                        impactedAtomIds: [],
+                        emittedAtMs: inputs.nowMs(),
+                    });
+                }
                 remainingFiles -= 1;
                 remainingBytes -= result.bytesConsumed;
             }
@@ -300,6 +782,23 @@ function buildSearchScope(scope, workspace) {
         relativePaths: scope.relativePaths,
     };
 }
+function fileStateCacheIdentity(keptPaths, searchScope, fs) {
+    const identity = [];
+    try {
+        for (const scopePath of keptPaths) {
+            const target = containedRealPathInfo(fs, searchScope.workspace.root, resolveWithinWorkspace(searchScope.workspace.root, scopePath));
+            const stat = fs.stat(target.path);
+            if (!stat.isFile || stat.mtimeMs === undefined) {
+                return undefined;
+            }
+            identity.push(`${scopePath}:${target.realRelative}:${stat.size.toString()}:${stat.mtimeMs.toString()}`);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return identity.sort();
+}
 function createReadyGovernedPlan(input, nowMs) {
     const planned = planAndGovern(input.budget === undefined
         ? { scope: input.scope, query: input.query }
@@ -320,31 +819,114 @@ function createReadyGovernedPlan(input, nowMs) {
     }
     return { plan, governor: planned.governor };
 }
-async function assembleGroundedPack({ input, deps, plan, rings, searchScope, fs, nowMs, }) {
+async function assembleEmptyGroundedPack({ input, deps, plan, governor, nowMs, stopReason, }) {
+    const assembleOptions = deps.microIndex === undefined ? { nowMs } : { nowMs, microIndex: deps.microIndex };
+    const assemble = await assembleContextPack({
+        scope: input.scope,
+        query: input.query,
+        budget: plan.budget,
+        atoms: [],
+        ranked: [],
+        omittedFromRanking: [],
+        excerpts: new Map(),
+        initialUsage: clampUsageToBudget(governor.usage, plan.budget),
+        initialUncertainty: [budgetClipped(stopReason, nowMs())],
+    }, assembleOptions);
+    return assemble.pack;
+}
+function cachedGroundedPack({ input, deps, plan, rings, ordered, cacheIdentity, initialUsage, assembleOptions, }) {
+    if (deps.microIndex === undefined || cacheIdentity === undefined) {
+        return undefined;
+    }
+    const key = contextPackIndexKey({
+        scope: input.scope,
+        query: input.query,
+        budget: plan.budget,
+        atoms: rings.atoms,
+        ranked: ordered.kept,
+        omittedFromRanking: [...rings.omitted, ...ordered.omitted],
+        excerpts: new Map(),
+        cacheIdentity,
+        initialUsage,
+    }, assembleOptions);
+    return deps.microIndex.get(key);
+}
+function preparePackAssembly(input, plan, rings, nowMs) {
     const atoms = rings.atoms;
     const initialUsage = clampUsageToBudget(rings.governor.usage, plan.budget);
     const ranking = rankCandidates({ atoms, anchors: plan.anchors }, { nowMs });
-    const atomsByPath = groupEvidenceAtomsByPath(atoms);
-    const evidenceUncertainty = atoms.length === 0 || ranking.kept.length === 0 ? [noEvidence(nowMs())] : [];
-    const excerptReads = await readKeptExcerpts(ranking.kept.map((c) => c.scopePath), { searchScope, fs, budget: plan.budget, initialUsage, atomsByPath, nowMs, signal: deps.signal });
-    const assembleOptions = deps.microIndex === undefined ? { nowMs } : { nowMs, microIndex: deps.microIndex };
+    const ordered = refineCandidateOrdering(ranking.kept, ranking.omitted, input.query.text, plan.anchors, nowMs());
+    return {
+        atoms,
+        initialUsage,
+        ordered,
+        atomsByPath: groupEvidenceAtomsByPath(atoms),
+        evidenceUncertainty: atoms.length === 0 || ordered.kept.length === 0 ? [noEvidence(nowMs())] : [],
+        keptPaths: ordered.kept.map((c) => c.scopePath),
+    };
+}
+async function assemblePackFromReads({ input, plan, rings, prepared, excerptReads, cacheIdentity, assembleOptions, }) {
+    const needsNoEvidenceMarker = excerptReads.excerpts.size === 0 &&
+        !prepared.evidenceUncertainty.some((marker) => marker.kind === "no-evidence");
     const assemble = await assembleContextPack({
         scope: input.scope,
         query: input.query,
         budget: plan.budget,
-        atoms,
-        ranked: ranking.kept,
-        omittedFromRanking: [...rings.omitted, ...ranking.omitted],
+        atoms: prepared.atoms,
+        ranked: prepared.ordered.kept,
+        omittedFromRanking: [...rings.omitted, ...prepared.ordered.omitted],
         excerpts: excerptReads.excerpts,
-        initialUsage,
+        cacheIdentity,
+        initialUsage: prepared.initialUsage,
         initialUncertainty: [
             ...rings.uncertainty,
             ...excerptReads.uncertainty,
-            ...evidenceUncertainty,
+            ...prepared.evidenceUncertainty,
+            ...(needsNoEvidenceMarker ? [noEvidence(assembleOptions.nowMs())] : []),
         ],
     }, assembleOptions);
     return assemble.pack;
 }
+async function assembleGroundedPack({ input, deps, plan, rings, searchScope, fs, nowMs, }) {
+    const scopedRings = withExplicitScopeAtoms(rings, input, searchScope, fs, nowMs);
+    const augmentedRings = withProjectMetadataAtoms(scopedRings, input, searchScope, fs, nowMs);
+    const prepared = preparePackAssembly(input, plan, augmentedRings, nowMs);
+    const cacheIdentity = deps.microIndex === undefined
+        ? undefined
+        : fileStateCacheIdentity(prepared.keptPaths, searchScope, fs);
+    const assembleOptions = deps.microIndex === undefined ? { nowMs } : { nowMs, microIndex: deps.microIndex };
+    const cached = cachedGroundedPack({
+        input,
+        deps,
+        plan,
+        rings: augmentedRings,
+        ordered: prepared.ordered,
+        cacheIdentity,
+        initialUsage: prepared.initialUsage,
+        assembleOptions,
+    });
+    if (cached !== undefined) {
+        return cached;
+    }
+    const excerptReads = await readKeptExcerpts(prepared.keptPaths, {
+        searchScope,
+        fs,
+        budget: plan.budget,
+        initialUsage: prepared.initialUsage,
+        atomsByPath: prepared.atomsByPath,
+        nowMs,
+        signal: deps.signal,
+    });
+    return await assemblePackFromReads({
+        input,
+        plan,
+        rings: augmentedRings,
+        prepared,
+        excerptReads,
+        cacheIdentity,
+        assembleOptions,
+    });
+}
 // ─── Public entry ─────────────────────────────────────────────────────────────
 // Epic #532 — retrieval-only pipeline: the ready-governed plan, workspace detection, ring run,
 // and pack assembly (the original steps 1–4) WITHOUT the model answer. `deps.answerer` is part of
@@ -359,9 +941,22 @@ export async function retrieveConnectedContextPack(input, deps) {
     const { plan, governor } = createReadyGovernedPlan(input, nowMs);
     deps.recordPlan?.(plan);
     throwIfCancelled(deps.signal);
+    const blockedByReadBudget = readBudgetStopReason(plan.budget);
+    if (blockedByReadBudget !== undefined) {
+        const pack = await assembleEmptyGroundedPack({
+            input,
+            deps,
+            plan,
+            governor,
+            nowMs,
+            stopReason: blockedByReadBudget,
+        });
+        throwIfCancelled(deps.signal);
+        return { pack, elapsedMs: Math.max(0, nowMs() - start), plan };
+    }
     const workspace = detect(input.workspaceRoot, fs);
     const searchScope = buildSearchScope(input.scope, workspace);
-    const rings = await runAllRings(plan.rings, { searchScope, query: input.query, fs, nowMs, signal: deps.signal }, governor);
+    const rings = await runAllRings(plan.rings, { searchScope, query: input.query, anchors: plan.anchors, fs, nowMs, signal: deps.signal }, governor);
     throwIfCancelled(deps.signal);
     const pack = await assembleGroundedPack({ input, deps, plan, rings, searchScope, fs, nowMs });
     throwIfCancelled(deps.signal);
@@ -375,15 +970,26 @@ export async function runGroundedExploration(input, deps) {
     const start = nowMs();
     const { pack, plan } = await retrieveConnectedContextPack(input, deps);
     const answer = normalizeGroundedAnswerPayload(await deps.answerer.answer(input.query.text, pack));
+    const elapsedMs = Math.max(0, nowMs() - start);
+    const exhaustedAnswerDimensions = [
+        ...(answer.usage.promptTokens > pack.budget.modelInputTokensMax ? ["modelInputTokens"] : []),
+        ...(answer.usage.completionTokens > pack.budget.modelOutputTokensMax
+            ? ["modelOutputTokens"]
+            : []),
+        ...(elapsedMs > pack.budget.elapsedMsMax ? ["elapsedMs"] : []),
+    ];
     const groundedPack = {
         ...pack,
         usage: {
             ...pack.usage,
-            modelInputTokens: answer.usage.promptTokens,
-            modelOutputTokens: answer.usage.completionTokens,
+            modelInputTokens: Math.min(answer.usage.promptTokens, pack.budget.modelInputTokensMax),
+            modelOutputTokens: Math.min(answer.usage.completionTokens, pack.budget.modelOutputTokensMax),
+            elapsedMs: Math.min(Math.max(pack.usage.elapsedMs, elapsedMs), pack.budget.elapsedMsMax),
         },
+        uncertainty: exhaustedAnswerDimensions.length === 0
+            ? pack.uncertainty
+            : [...pack.uncertainty, answerBudgetClipped(exhaustedAnswerDimensions, nowMs())],
     };
-    const elapsedMs = Math.max(0, nowMs() - start);
     return { pack: groundedPack, assistantContent: answer.content, elapsedMs, plan };
 }
 // Re-export DEFAULT_SEARCH_LIMITS for parity with #179 callers that import limits via the