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

package/node_modules/@oscharko-dev/keiko-server/dist/grounded-qa-multi-source.js

@@ -8,17 +8,18 @@
 // gateway messages, citations, and evidence from the exact same primitives.
 import { basename } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { resolveCostClass, } from "@oscharko-dev/keiko-model-gateway";
+import { ContextOverflowError, resolveCostClass, } from "@oscharko-dev/keiko-model-gateway";
 import { persistConnectedContextEvidence } from "@oscharko-dev/keiko-evidence";
 import { CANDIDATE_OMISSION_REASONS, DEFAULT_EXPLORATION_BUDGET, } from "@oscharko-dev/keiko-contracts/connected-context";
 import { buildGroundedAnswerContextPackSummary, } from "@oscharko-dev/keiko-contracts/bff-wire";
 import { currentRedactionSecrets } from "./deps.js";
-import { ClarificationNeededError, retrieveConnectedContextPack, } from "./grounded-orchestrator.js";
+import { ClarificationNeededError, clarificationUserMessage, retrieveConnectedContextPack, } from "./grounded-orchestrator.js";
 import { microIndexForGroundedScope } from "./grounded-context-index.js";
 import { GROUNDED_SYSTEM_PROMPT } from "./grounded-prompt.js";
 import { rememberGroundedTurn } from "./grounded-turn-registry.js";
+import { assertUsableAssistantContent } from "./assistant-response.js";
 import { normalizeGroundedAnswerPayload, } from "./grounded-answer.js";
-import { badRequest, buildCitations, buildQuery, buildSelectedScopeFrom, deriveScopeIdFrom, ensureNotCancelled, evidenceLines, internalError, isValidGroundedPack, mappedGatewayError, packBudgetSummary, persistGroundedExchange, redactString, uncertaintyLines, } from "./grounded-qa.js";
+import { badRequest, buildCitations, buildQuery, buildSelectedScopeFrom, deriveScopeIdFrom, ensureNotCancelled, evidenceLines, internalError, isValidGroundedPack, mappedGatewayError, mappedWorkspaceError, modelInputPromptByteLimit, packBudgetSummary, persistGroundedExchange, promptByteLength, redactString, uncertaintyLines, withPromptExcerptByteLimit, } from "./grounded-qa.js";
 // ─── Canonical reader + label/budget helpers ──────────────────────────────────
 // Canonical reader rule (Epic #532 contract): `connectedScopes` supersedes the legacy single
 // `connectedScope`. Readers must NOT mix the two — the list, when present, is authoritative.
@@ -170,6 +171,9 @@ function sourceSection(entry, index, redactor) {
 // Same system message as the single-source path; the user message lists each source under its own
 // header so the model can attribute every claim to a source label in addition to the file ref.
 export function buildMultiSourceGatewayMessages(question, labeledPacks, redactor) {
+    return budgetedMultiSourceGatewayMessages(question, labeledPacks, redactor);
+}
+function buildRawMultiSourceGatewayMessages(question, labeledPacks, redactor) {
     const sections = labeledPacks.flatMap((entry, index) => sourceSection(entry, index, redactor));
     const userContent = [
         "User question:",
@@ -185,6 +189,41 @@ export function buildMultiSourceGatewayMessages(question, labeledPacks, redactor
         { role: "user", content: userContent },
     ];
 }
+function multiSourceExcerptCount(labeledPacks) {
+    return labeledPacks.reduce((count, entry) => count + entry.pack.files.reduce((fileCount, file) => fileCount + file.excerpts.length, 0), 0);
+}
+function withMultiSourcePromptExcerptByteLimit(labeledPacks, maxExcerptBytes) {
+    return labeledPacks.map((entry) => ({
+        ...entry,
+        pack: withPromptExcerptByteLimit(entry.pack, maxExcerptBytes),
+    }));
+}
+function budgetedMultiSourceGatewayMessages(question, labeledPacks, redactor) {
+    const limit = modelInputPromptByteLimit(labeledPacks.reduce((sum, entry) => sum + entry.pack.budget.modelInputTokensMax, 0));
+    let messages = buildRawMultiSourceGatewayMessages(question, labeledPacks, redactor);
+    if (limit === 0 || promptByteLength(messages) <= limit)
+        return messages;
+    const excerptCount = multiSourceExcerptCount(labeledPacks);
+    if (excerptCount === 0)
+        return messages;
+    const emptyPacks = withMultiSourcePromptExcerptByteLimit(labeledPacks, 0);
+    const overheadBytes = promptByteLength(buildRawMultiSourceGatewayMessages(question, emptyPacks, redactor));
+    // When overhead alone (system prompt + question + framing for all sources) exceeds the limit,
+    // no amount of excerpt trimming can bring the prompt within budget. Throw instead of sending
+    // an over-limit prompt to the provider which would result in an opaque 400 context-window error.
+    if (overheadBytes > limit) {
+        throw new ContextOverflowError(`Multi-source grounded prompt overhead (${String(overheadBytes)} bytes) exceeds model input limit (${String(limit)} bytes).`);
+    }
+    let maxExcerptBytes = Math.max(0, Math.floor((limit - overheadBytes) / excerptCount));
+    while (maxExcerptBytes >= 0) {
+        messages = buildRawMultiSourceGatewayMessages(question, withMultiSourcePromptExcerptByteLimit(labeledPacks, maxExcerptBytes), redactor);
+        if (promptByteLength(messages) <= limit || maxExcerptBytes === 0) {
+            return messages;
+        }
+        maxExcerptBytes = Math.max(0, Math.floor(maxExcerptBytes * 0.8));
+    }
+    return buildRawMultiSourceGatewayMessages(question, emptyPacks, redactor);
+}
 // Production retriever: retrieval-only orchestrator pass with a per-scope micro-index cache. No
 // modelId is needed — retrieval performs no model call.
 export function defaultRetriever(signal) {
@@ -207,8 +246,9 @@ export function createMultiSourceAnswerer(model, modelId, redactor, signal) {
             stream: false,
         }, signal);
         const content = response.content.trim();
+        assertUsableAssistantContent(content, modelId);
         return {
-            content: content.length > 0 ? content : "The model returned an empty response.",
+            content,
             usage: {
                 promptTokens: response.usage.promptTokens,
                 completionTokens: response.usage.completionTokens,
@@ -216,14 +256,19 @@ export function createMultiSourceAnswerer(model, modelId, redactor, signal) {
         };
     };
 }
+// ─── Retrieved-source record + worker ─────────────────────────────────────────
+const MAX_RETRIEVAL_CONCURRENCY = 4;
 async function retrieveAllSources(ctx, query, perScopeBudget, labels) {
-    const retrieved = [];
-    for (let i = 0; i < ctx.scopes.length; i += 1) {
+    const retrieved = new Array(ctx.scopes.length);
+    const skipped = [];
+    let nextIndex = 0;
+    let firstError;
+    async function retrieveOne(i) {
         ensureNotCancelled(ctx.signal);
         const cs = ctx.scopes[i];
         const label = labels[i];
         if (cs === undefined || label === undefined)
-            continue;
+            return;
         const scope = buildSelectedScopeFrom(ctx.chat, cs, deriveScopeIdFrom(ctx.chat, cs, i));
         const out = await ctx.retriever({
             scope,
@@ -232,24 +277,50 @@ async function retrieveAllSources(ctx, query, perScopeBudget, labels) {
             budget: perScopeBudget,
         });
         if (!isValidGroundedPack(out.pack)) {
-            return internalError("Grounded answer context pack failed validation.");
+            skipped.push({ label, message: "Pack validation failed." });
+            firstError ??= internalError("Grounded answer context pack failed validation.");
+            return;
+        }
+        retrieved[i] = { label, pack: out.pack, elapsedMs: out.elapsedMs, scope, plan: out.plan };
+    }
+    async function worker() {
+        for (;;) {
+            const i = nextIndex;
+            nextIndex += 1;
+            if (i >= ctx.scopes.length)
+                return;
+            await retrieveOne(i);
         }
-        retrieved.push({ label, pack: out.pack, elapsedMs: out.elapsedMs, scope });
     }
-    return retrieved;
+    const workerCount = Math.min(MAX_RETRIEVAL_CONCURRENCY, Math.max(1, ctx.scopes.length));
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    const sources = retrieved.filter((source) => source !== undefined);
+    if (sources.length === 0 && firstError !== undefined)
+        return firstError;
+    return { retrieved: sources, skipped, firstError };
 }
 function mergedCitations(sources, redactor) {
     const citations = sources.flatMap((src) => buildCitations(src.pack, redactor).map((c) => ({ ...c, source: src.label })));
     return [...citations].sort((a, b) => b.score - a.score);
 }
-function mergedUncertainty(sources, redactor) {
-    return sources.flatMap((src) => src.pack.uncertainty.map((u) => ({ kind: u.kind, claim: redactString(redactor, u.claim) })));
+function mergedUncertainty(sources, skipped, preSkipped, redactor) {
+    const fromPacks = sources.flatMap((src) => src.pack.uncertainty.map((u) => ({ kind: u.kind, claim: redactString(redactor, u.claim) })));
+    const allSkipped = [
+        ...preSkipped.map((s) => ({ label: s.label, message: s.message })),
+        ...skipped,
+    ];
+    const fromSkipped = allSkipped.map((entry) => ({
+        kind: "source-skipped",
+        claim: redactString(redactor, `Source ${entry.label} skipped: ${entry.message}`),
+    }));
+    return [...fromPacks, ...fromSkipped];
 }
 // Persists ONE evidence run per source, each naming the root that source actually searched (L1
 // honesty rule, mirrored from the single path). Returns the FIRST source's run id, which the
-// answer surfaces as its primary evidenceRunId.
+// answer surfaces as its primary evidenceRunId, plus the full set for audit discovery.
 function persistPerSourceEvidence(ctx, sources) {
     let firstRunId;
+    const runIds = [];
     for (const src of sources) {
         const finishedAt = Date.now();
         const startedAt = Math.max(0, finishedAt - src.elapsedMs);
@@ -259,6 +330,7 @@ function persistPerSourceEvidence(ctx, sources) {
             modelId: ctx.modelId,
             workspaceRoot: src.scope.workspaceRoot,
             chatId: ctx.chat.id,
+            plan: src.plan,
             pack: src.pack,
             citationCount: buildCitations(src.pack, ctx.deps.redactor).length,
             elapsedMs: src.elapsedMs,
@@ -271,23 +343,25 @@ function persistPerSourceEvidence(ctx, sources) {
             costClassResolver: resolveCostClass,
         });
         firstRunId ??= runId;
+        runIds.push(runId);
     }
-    return { firstRunId };
+    return { firstRunId, runIds };
 }
-function assembleMultiSourceAnswer(ctx, sources, assistant, ids) {
+function assembleMultiSourceAnswer(ctx, sources, skipped, assistant, ids) {
     const { redactor } = ctx.deps;
     const citations = mergedCitations(sources, redactor);
     const summaries = sources.map((src) => buildGroundedAnswerContextPackSummary(src.pack, buildCitations(src.pack, redactor).length, src.elapsedMs));
     const mergedSummary = mergeContextPackSummaries(summaries);
-    const { firstRunId } = persistPerSourceEvidence(ctx, sources);
+    const { firstRunId, runIds } = persistPerSourceEvidence(ctx, sources);
     return {
         groundingKind: "connected-context",
         userMessageId: ids.userMessageId,
         assistantMessageId: ids.assistantMessageId,
         evidenceRunId: firstRunId,
+        evidenceRunIds: runIds,
         content: redactString(redactor, assistant.content),
         citations,
-        uncertainty: mergedUncertainty(sources, redactor),
+        uncertainty: mergedUncertainty(sources, skipped, ctx.preSkipped ?? [], redactor),
         omittedCount: sources.reduce((acc, src) => acc + src.pack.omitted.length, 0),
         elapsedMs: sources.reduce((acc, src) => acc + src.elapsedMs, 0),
         contextPack: {
@@ -304,26 +378,27 @@ export async function runMultiSourceAsk(ctx) {
     const query = buildQuery(ctx.content, () => Date.now());
     const labels = sourceLabels(ctx.scopes);
     const perScopeBudget = splitExplorationBudget(DEFAULT_EXPLORATION_BUDGET, ctx.scopes.length);
-    let sources;
+    let outcome;
     try {
-        sources = await retrieveAllSources(ctx, query, perScopeBudget, labels);
+        outcome = await retrieveAllSources(ctx, query, perScopeBudget, labels);
     }
     catch (error) {
         return mapMultiSourceError(error, ctx.deps);
     }
-    if (isRouteResult(sources)) {
-        return sources;
+    if (isRouteResult(outcome)) {
+        return outcome;
     }
-    const retrieved = sources;
+    const { retrieved, skipped } = outcome;
     let assistant;
     try {
         assistant = normalizeGroundedAnswerPayload(await ctx.answerer(ctx.content, retrieved.map((s) => ({ label: s.label, pack: s.pack }))));
+        ensureNotCancelled(ctx.signal);
     }
     catch (error) {
         return mapMultiSourceError(error, ctx.deps);
     }
     const [userMessage, assistantMessage] = persistGroundedExchange(ctx.deps, ctx.chat.id, redactString(ctx.deps.redactor, ctx.content), redactString(ctx.deps.redactor, assistant.content));
-    const answer = assembleMultiSourceAnswer(ctx, retrieved, assistant, {
+    const answer = assembleMultiSourceAnswer(ctx, retrieved, skipped, assistant, {
         userMessageId: userMessage.id,
         assistantMessageId: assistantMessage.id,
     });
@@ -337,11 +412,14 @@ export async function runMultiSourceAsk(ctx) {
     return { status: 200, body: answer };
 }
 function isRouteResult(value) {
-    return !Array.isArray(value);
+    return "status" in value;
 }
 function mapMultiSourceError(error, deps) {
     if (error instanceof ClarificationNeededError)
-        return badRequest(error.message);
+        return badRequest(clarificationUserMessage(error));
+    const workspaceResult = mappedWorkspaceError(error);
+    if (workspaceResult !== undefined)
+        return workspaceResult;
     const gatewayResult = mappedGatewayError(error, deps);
     if (gatewayResult !== undefined)
         return gatewayResult;

package/node_modules/@oscharko-dev/keiko-server/dist/grounded-qa.d.ts

@@ -1,3 +1,4 @@
+import { type ChatMessage as GatewayChatMessage } from "@oscharko-dev/keiko-model-gateway";
 import { type ConnectedContextPack, type RetrievalQuery, type SelectedScope } from "@oscharko-dev/keiko-contracts/connected-context";
 import { type GroundedEvidenceCitation, type GroundedUncertainty } from "@oscharko-dev/keiko-contracts/bff-wire";
 import type { RouteContext, RouteResult } from "./routes.js";
@@ -10,15 +11,21 @@ import { GROUNDED_SYSTEM_PROMPT } from "./grounded-prompt.js";
 export declare function badRequest(message: string): RouteResult;
 export declare function internalError(message: string): RouteResult;
 export declare function mappedGatewayError(error: unknown, deps: UiHandlerDeps): RouteResult | undefined;
+export declare function mappedWorkspaceError(error: unknown): RouteResult | undefined;
 export declare function isValidGroundedPack(pack: ConnectedContextPack): boolean;
 export declare function deriveScopeIdFrom(chat: Chat, cs: ChatConnectedScope, index: number): string;
 export declare function buildSelectedScopeFrom(chat: Chat, cs: ChatConnectedScope, scopeId: string): SelectedScope;
 export declare function buildQuery(content: string, nowMs: () => number): RetrievalQuery;
 export declare function ensureNotCancelled(signal: AbortSignal): void;
+export declare function promptSafeExcerptText(value: string): string;
+export declare function promptByteLength(messages: readonly GatewayChatMessage[]): number;
+export declare function modelInputPromptByteLimit(modelInputTokensMax: number): number;
+export declare function withPromptExcerptByteLimit(pack: ConnectedContextPack, maxExcerptBytes: number): ConnectedContextPack;
 export declare function packBudgetSummary(pack: ConnectedContextPack): string;
 export declare function evidenceLines(pack: ConnectedContextPack, redactor: Redactor): readonly string[];
 export declare function uncertaintyLines(pack: ConnectedContextPack, redactor: Redactor): readonly string[];
 export { GROUNDED_SYSTEM_PROMPT };
+export declare function buildGroundedGatewayMessages(question: string, pack: ConnectedContextPack, redactor: Redactor): readonly GatewayChatMessage[];
 export declare function redactString(redactor: Redactor, value: string): string;
 export declare function buildCitations(pack: ConnectedContextPack, redactor: Redactor): readonly GroundedEvidenceCitation[];
 export declare function buildUncertainty(pack: ConnectedContextPack, redactor: Redactor): readonly GroundedUncertainty[];

package/node_modules/@oscharko-dev/keiko-server/dist/grounded-qa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grounded-qa.d.ts","sourceRoot":"","sources":["../src/grounded-qa.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grounded-qa.d.ts","sourceRoot":"","sources":["../src/grounded-qa.ts"],"names":[],"mappings":"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"}

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

@@ -4,20 +4,25 @@
 // All path validation runs in the composed layers; this module only validates wire-shape
 // inputs (chatId + content) and enforces that the chat carries a connected scope.
 import { createHash, randomUUID } from "node:crypto";
-import { CancelledError, GatewayError, findCapability, findConfiguredCapability, resolveCostClass, } from "@oscharko-dev/keiko-model-gateway";
+import { realpathSync } from "node:fs";
+import { basename } from "node:path";
+import { CancelledError, ContextOverflowError, GatewayError, findCapability, findConfiguredCapability, resolveCostClass, } from "@oscharko-dev/keiko-model-gateway";
 import { persistConnectedContextEvidence } from "@oscharko-dev/keiko-evidence";
 import { redact } from "@oscharko-dev/keiko-security";
+import { RepoSearchInvalidQueryError, RepoSearchInvalidRangeError, RepoSearchUnsupportedFileError, } from "@oscharko-dev/keiko-workspace";
 import { CONNECTED_CONTEXT_SCHEMA_VERSION, validateConnectedContextPack, } from "@oscharko-dev/keiko-contracts/connected-context";
 import { buildGroundedAnswerContextPackSummary, } from "@oscharko-dev/keiko-contracts/bff-wire";
 import { errorBody } from "./routes.js";
-import { currentGatewayConfig, currentRedactionSecrets } from "./deps.js";
-import { ClarificationNeededError, runGroundedExploration, } from "./grounded-orchestrator.js";
+import { currentGatewayConfig, currentGroundingLimits, currentRedactionSecrets } from "./deps.js";
+import { ClarificationNeededError, clarificationUserMessage, runGroundedExploration, } from "./grounded-orchestrator.js";
 import { microIndexForGroundedScope } from "./grounded-context-index.js";
+import { pathIsDenied } from "./files-deny.js";
 import { handleLocalKnowledgeGroundedAsk } from "./local-knowledge-grounded-qa.js";
 import { buildConnectedScopes, createMultiSourceAnswerer, defaultRetriever, runMultiSourceAsk, } from "./grounded-qa-multi-source.js";
 import { buildLocalKnowledgeScopes, runHybridGroundedAsk, } from "./grounded-qa-hybrid.js";
 import { GROUNDED_SYSTEM_PROMPT } from "./grounded-prompt.js";
 import { rememberGroundedTurn } from "./grounded-turn-registry.js";
+import { assertUsableAssistantContent } from "./assistant-response.js";
 // ─── Body parsing (mirrors store-handlers' bounded reader) ────────────────────
 const MAX_BODY_BYTES = 128_000;
 const MAX_CONTENT_CHARS = 16_000;
@@ -85,6 +90,14 @@ function gatewayErrorResult(error, deps) {
 export function mappedGatewayError(error, deps) {
     return error instanceof GatewayError ? gatewayErrorResult(error, deps) : undefined;
 }
+export function mappedWorkspaceError(error) {
+    if (error instanceof RepoSearchInvalidQueryError ||
+        error instanceof RepoSearchInvalidRangeError ||
+        error instanceof RepoSearchUnsupportedFileError) {
+        return badRequest(error.message);
+    }
+    return undefined;
+}
 export function isValidGroundedPack(pack) {
     try {
         return validateConnectedContextPack(pack).ok;
@@ -182,6 +195,52 @@ function buildSelectedScope(chat) {
         return undefined;
     return buildSelectedScopeFrom(chat, cs, deriveScopeId(chat));
 }
+function canonicalGroundedRoot(rootInput, deps) {
+    if (pathIsDenied(rootInput)) {
+        return badRequest("Connected scope is excluded from Keiko's safe read surface.");
+    }
+    let realRoot;
+    try {
+        realRoot = realpathSync(rootInput);
+    }
+    catch {
+        return badRequest("Connected scope root is not accessible.");
+    }
+    if (pathIsDenied(realRoot)) {
+        return badRequest("Connected scope is excluded from Keiko's safe read surface.");
+    }
+    const redacted = deps.redactor(realRoot);
+    if (typeof redacted === "string" && redacted !== realRoot) {
+        return badRequest("Connected scope root contains credential-shaped metadata.");
+    }
+    return realRoot;
+}
+function skippedFolderMessage(result) {
+    const body = result.body;
+    return body.error?.message ?? "not accessible";
+}
+// Fail-soft canonicalization: inaccessible/denied scopes are collected in `skipped` instead of
+// aborting the entire request. Callers apply the hard-400 only when NO healthy scope remains.
+function canonicalizeGroundedFolderScopes(chat, deps, scopes) {
+    const canonical = [];
+    const skipped = [];
+    for (const scope of scopes) {
+        const rootInput = scope.root ?? chat.projectPath;
+        const realRoot = canonicalGroundedRoot(rootInput, deps);
+        if (typeof realRoot !== "string") {
+            const label = scope.root !== undefined ? basename(scope.root) : "project";
+            skipped.push({ label, message: skippedFolderMessage(realRoot), reason: realRoot });
+            continue;
+        }
+        canonical.push({ ...scope, root: realRoot });
+    }
+    return { canonical, skipped };
+}
+function withCanonicalFolderScopes(chat, scopes) {
+    if (scopes.length === 0)
+        return chat;
+    return { ...chat, connectedScopes: scopes, connectedScope: scopes[0] };
+}
 export function buildQuery(content, nowMs) {
     return {
         kind: "natural-language",
@@ -235,6 +294,76 @@ function redactedString(redactor, value) {
     const redacted = redactor(value);
     return typeof redacted === "string" ? redacted : value;
 }
+export function promptSafeExcerptText(value) {
+    return value.split("```").join("` ` `");
+}
+const APPROX_BYTES_PER_TOKEN = 4;
+export function promptByteLength(messages) {
+    return Buffer.byteLength(messages.map((message) => message.content).join("\n"), "utf8");
+}
+export function modelInputPromptByteLimit(modelInputTokensMax) {
+    return Math.max(0, Math.floor(modelInputTokensMax) * APPROX_BYTES_PER_TOKEN);
+}
+function clampUtf8Bytes(value, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(value.slice(0, mid), "utf8") <= maxBytes) {
+            low = mid;
+        }
+        else {
+            high = mid - 1;
+        }
+    }
+    return value.slice(0, low);
+}
+function packExcerptCount(pack) {
+    return pack.files.reduce((count, file) => count + file.excerpts.length, 0);
+}
+export function withPromptExcerptByteLimit(pack, maxExcerptBytes) {
+    return {
+        ...pack,
+        files: pack.files.map((file) => ({
+            ...file,
+            excerpts: file.excerpts.map((excerpt) => ({
+                ...excerpt,
+                content: clampUtf8Bytes(excerpt.content, maxExcerptBytes),
+            })),
+        })),
+    };
+}
+function promptBudgetedMessages(question, pack, redactor, build) {
+    const limit = modelInputPromptByteLimit(pack.budget.modelInputTokensMax);
+    let messages = build(question, pack, redactor);
+    if (limit === 0 || promptByteLength(messages) <= limit)
+        return messages;
+    const excerptCount = packExcerptCount(pack);
+    if (excerptCount === 0)
+        return messages;
+    const emptyPack = withPromptExcerptByteLimit(pack, 0);
+    const emptyMessages = build(question, emptyPack, redactor);
+    const overheadBytes = promptByteLength(emptyMessages);
+    // When overhead alone (system prompt + question + framing) exceeds the limit, no amount of
+    // excerpt trimming can bring the prompt within budget. Throw instead of sending an over-limit
+    // prompt to the provider which would result in an opaque 400 context-window error.
+    if (overheadBytes > limit) {
+        throw new ContextOverflowError(`Grounded prompt overhead (${String(overheadBytes)} bytes) exceeds model input limit (${String(limit)} bytes).`);
+    }
+    let maxExcerptBytes = Math.max(0, Math.floor((limit - overheadBytes) / excerptCount));
+    while (maxExcerptBytes >= 0) {
+        messages = build(question, withPromptExcerptByteLimit(pack, maxExcerptBytes), redactor);
+        if (promptByteLength(messages) <= limit || maxExcerptBytes === 0) {
+            return messages;
+        }
+        maxExcerptBytes = Math.max(0, Math.floor(maxExcerptBytes * 0.8));
+    }
+    return emptyMessages;
+}
 export function packBudgetSummary(pack) {
     const { usage, budget } = pack;
     return [
@@ -264,7 +393,7 @@ export function evidenceLines(pack, redactor) {
             });
             lines.push(`- Evidence ${redactedString(redactor, citation)} (score ${excerpt.atom.score.toFixed(2)}):`);
             lines.push("```");
-            lines.push(redactedString(redactor, excerpt.content));
+            lines.push(promptSafeExcerptText(redactedString(redactor, excerpt.content)));
             lines.push("```");
         }
     }
@@ -284,7 +413,7 @@ export function uncertaintyLines(pack, redactor) {
 // GROUNDED_SYSTEM_PROMPT now lives in the dependency-free ./grounded-prompt.js leaf (re-exported
 // here for back-compat) so the hybrid path can interpolate it without a circular-import TDZ.
 export { GROUNDED_SYSTEM_PROMPT };
-function buildGroundedGatewayMessages(question, pack, redactor) {
+function buildRawGroundedGatewayMessages(question, pack, redactor) {
     const safeQuestion = redactedString(redactor, question);
     const userContent = [
         "User question:",
@@ -309,6 +438,9 @@ function buildGroundedGatewayMessages(question, pack, redactor) {
         { role: "user", content: userContent },
     ];
 }
+export function buildGroundedGatewayMessages(question, pack, redactor) {
+    return promptBudgetedMessages(question, pack, redactor, buildRawGroundedGatewayMessages);
+}
 function createGatewayAnswerer(model, modelId, redactor, signal) {
     return {
         answer: async (question, pack) => {
@@ -319,8 +451,9 @@ function createGatewayAnswerer(model, modelId, redactor, signal) {
                 stream: false,
             }, signal);
             const content = response.content.trim();
+            assertUsableAssistantContent(content, modelId);
             return {
-                content: content.length > 0 ? content : "The model returned an empty response.",
+                content,
                 usage: {
                     promptTokens: response.usage.promptTokens,
                     completionTokens: response.usage.completionTokens,
@@ -416,6 +549,7 @@ function persistGroundedAuditEvidence(workerCtx, output, citationCount) {
         // the real grounding root so the audit trail is honest about which tree produced the answer.
         workspaceRoot: workerCtx.scope.workspaceRoot,
         chatId: workerCtx.chat.id,
+        plan: output.plan,
         pack: output.pack,
         citationCount,
         elapsedMs: output.elapsedMs,
@@ -472,7 +606,7 @@ async function runAsk(workerCtx) {
     return { status: 200, body: answer };
 }
 function isRouteResult(value) {
-    return "status" in value;
+    return typeof value === "object" && value !== null && "status" in value;
 }
 function ensureRouteNotCancelled(signal, deps) {
     try {
@@ -499,8 +633,11 @@ async function runGroundedRunner(workerCtx, query) {
     }
     catch (error) {
         if (error instanceof ClarificationNeededError) {
-            return badRequest(error.message);
+            return badRequest(clarificationUserMessage(error));
         }
+        const workspaceResult = mappedWorkspaceError(error);
+        if (workspaceResult !== undefined)
+            return workspaceResult;
         const gatewayResult = mappedGatewayError(error, workerCtx.deps);
         if (gatewayResult !== undefined)
             return gatewayResult;
@@ -553,7 +690,7 @@ function resolveMultiSourceSeam(deps, modelId, signal, override) {
         answerer: createMultiSourceAnswerer(model, modelId, deps.redactor, signal),
     };
 }
-async function dispatchMultiSourceAsk(args, deps, scopes, seamOverride) {
+async function dispatchMultiSourceAsk(args, deps, scopes, skippedFolders, seamOverride) {
     const { chat, input, signal } = args;
     // An injected seam (tests) bypasses model-capability resolution exactly as the single-source path
     // does for an injected runner: there is no real model port to validate against. Production (no
@@ -575,6 +712,7 @@ async function dispatchMultiSourceAsk(args, deps, scopes, seamOverride) {
         retriever: seam.retriever,
         answerer: seam.answerer,
         signal,
+        preSkipped: skippedFolders.map((s) => ({ label: s.label, message: s.message })),
     });
 }
 // Epic #532 — builds the single-source SelectedScope from the canonical list when the legacy
@@ -586,18 +724,43 @@ function singleScopeFromList(chat, scopes) {
         return undefined;
     return buildSelectedScopeFrom(chat, cs, deriveScopeIdFrom(chat, cs, 0));
 }
-// Epic #532 — the folder-only branch (0 → bad request; 1 → the byte-identical legacy single-source
-// runner; 2+ → the multi-source merge). Extracted so handleGroundedAsk stays the thin count-based
-// dispatcher.
-async function dispatchFolderAsk(prepared, deps, scopes, runner, multiSource) {
+// Epic #532 — the folder-only branch (0 handled by caller; 1 → single-source runner unless
+// there are pre-skipped folders, in which case multi-source carries the skip notice; 2+ → the
+// multi-source merge). Extracted so handleGroundedAsk stays the thin count-based dispatcher.
+// Release 0.2.0 — ask-path defense-in-depth (mirror of the hybrid path's capSourcesToLimits):
+// a stored over-cap chat (legacy rows, or an operator who later lowered the limits) must not
+// fan out unboundedly at ask time. The first `cap` folders (connection order) stay live; the
+// rest surface as source-skipped notices (basename label only — no path leak).
+function capFolderScopesForAsk(deps, scopes, skippedFolders) {
+    const cap = currentGroundingLimits(deps).maxConnectedSources;
+    if (scopes.length <= cap)
+        return { scopes, skipped: skippedFolders };
+    const overCap = scopes.slice(cap).map((scope) => {
+        const label = scope.root !== undefined ? basename(scope.root) : "project";
+        const message = "skipped: over the connected-source limit";
+        return { label, message, reason: badRequest(`Source "${label}" ${message}.`) };
+    });
+    return { scopes: scopes.slice(0, cap), skipped: [...skippedFolders, ...overCap] };
+}
+async function dispatchFolderAsk(prepared, deps, allScopes, allSkippedFolders, runner, multiSource) {
     const { chat, input, signal } = prepared;
-    if (scopes.length >= 2) {
-        return dispatchMultiSourceAsk(prepared, deps, scopes, multiSource);
+    const { scopes, skipped: skippedFolders } = capFolderScopesForAsk(deps, allScopes, allSkippedFolders);
+    // 2+ healthy folders or 1 healthy + some skipped → multi-source (carries skip-notice).
+    if (scopes.length >= 2 || (scopes.length === 1 && skippedFolders.length > 0)) {
+        return dispatchMultiSourceAsk(prepared, deps, scopes, skippedFolders, multiSource);
     }
     const scope = buildSelectedScope(chat) ?? singleScopeFromList(chat, scopes);
     if (scope === undefined) {
         return badRequest("Chat has no connected scope.");
     }
+    // Epic #177 audit (GAP-B) — mirror the PATCH-route deny-list check for the grounded-ask hot
+    // path. The PATCH route validates via validateFallbackProjectRoot before persisting a scope;
+    // a chat whose projectPath was created before the deny-list was added (or via the test store)
+    // could otherwise reach the orchestrator with a credential-dir workspaceRoot. Reject before
+    // calling the runner so no filesystem access occurs against a denied path.
+    if (pathIsDenied(scope.workspaceRoot)) {
+        return badRequest("Connected scope is excluded from Keiko's safe read surface.");
+    }
     const resolved = resolveGroundedRunner(deps, chat, input.modelId, signal, runner);
     if ("status" in resolved)
         return resolved;
@@ -620,7 +783,7 @@ function hybridSeamFields(seam) {
         ...(seam.answer !== undefined ? { answer: seam.answer } : {}),
     };
 }
-async function dispatchHybridAsk(prepared, deps, seam) {
+async function dispatchHybridAsk(prepared, deps, skippedFolders, seam) {
     const { chat, input, signal } = prepared;
     // An injected answerer (tests) bypasses model-capability resolution exactly as the multi-source
     // path does: there is no real model port to validate. Production resolves the guardrails once.
@@ -635,6 +798,11 @@ async function dispatchHybridAsk(prepared, deps, seam) {
         modelId,
         deps,
         signal,
+        preSkippedFolders: skippedFolders.map((s) => ({
+            label: s.label,
+            reason: "not-accessible",
+            message: s.message,
+        })),
         ...hybridSeamFields(seam),
     });
 }
@@ -648,16 +816,26 @@ export async function handleGroundedAsk(ctx, deps, runner, multiSource, hybrid)
     // keep the EXISTING folder path (#532, byte-identical). A lone connector with no folders keeps the
     // EXISTING single-connector path (#189, byte-identical). Everything else (folders+connector, or
     // 2+ connectors) is the hybrid merge.
+    // Fail-soft: inaccessible/denied folders are skipped; only effective (canonical) counts drive
+    // dispatch. A chat with ONLY denied/inaccessible sources still returns the original 400 so the
+    // user sees a clear rejection (security preserved).
     const folderScopes = buildConnectedScopes(chat);
+    const { canonical: canonicalFolderScopes, skipped: skippedFolders } = canonicalizeGroundedFolderScopes(chat, deps, folderScopes);
+    const preparedWithCanonicalFolders = {
+        ...prepared,
+        chat: withCanonicalFolderScopes(chat, canonicalFolderScopes),
+    };
     const connectorCount = buildLocalKnowledgeScopes(chat).length;
-    if (folderScopes.length === 0 && connectorCount === 0) {
-        return badRequest("Chat has no connected scope.");
+    const effectiveFolders = canonicalFolderScopes.length;
+    if (effectiveFolders === 0 && connectorCount === 0) {
+        // Hard-fail: return the first skipped reason (preserves exact 400 message) or the generic guard.
+        return skippedFolders[0]?.reason ?? badRequest("Chat has no connected scope.");
     }
     if (connectorCount === 0) {
-        return dispatchFolderAsk(prepared, deps, folderScopes, runner, multiSource);
+        return dispatchFolderAsk(preparedWithCanonicalFolders, deps, canonicalFolderScopes, skippedFolders, runner, multiSource);
     }
-    if (folderScopes.length === 0 && connectorCount === 1) {
+    if (effectiveFolders === 0 && connectorCount === 1) {
         return handleLocalKnowledgeGroundedAsk(chat, prepared.input, deps, prepared.signal);
     }
-    return dispatchHybridAsk(prepared, deps, hybrid);
+    return dispatchHybridAsk(preparedWithCanonicalFolders, deps, skippedFolders, hybrid);
 }