@duckcodeailabs/dql-cli 1.14.1 → 1.14.2

package/dist/local-runtime.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { execFileSync, execSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { gzip } from "node:zlib";
 import { createServer } from "node:http";
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
@@ -23,10 +23,10 @@ import { getRunner as getLLMRunner } from './llm/index.js';
 import { rethrowIfCancelled } from './llm/cancellation.js';
 import { fetchLatestPublishedDqlVersion, resolveDqlRuntimeVersionStatus } from './version-status.js';
 import { resolveRetrievalHealthStatus } from './retrieval-health.js';
-import { applyFinding, createResearchState, narrationMaxTokensForFacts, nextHypothesis, rerankCandidates, synthesizeResearchNarrative, AgenticExecutionCapabilityGate, mintFinalSqlAuthorization, verifyAgenticSqlExecutionCapability, qualifyAuthorizationReferences, validateSqlAgainstLocalContext as validateAuthorizedSqlReferences, verifyFinalSql, } from '@duckcodeailabs/dql-agent';
-import { applyEvalCassette, createDqlAgentProviderRunner, createGovernedTextProvider, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.js';
+import { applyFinding, createResearchState, narrationMaxTokensForFacts, nextHypothesis, rerankCandidates, synthesizeResearchNarrative, AgenticExecutionCapabilityGate, createAgenticSqlExecutionCapability, mintFinalSqlAuthorization, verifyAgenticSqlExecutionCapability, qualifyAuthorizationReferences, scopeContextPackToExploratoryCandidateClosure, validateSqlAgainstLocalContext as validateAuthorizedSqlReferences, verifyFinalSql, } from '@duckcodeailabs/dql-agent';
+import { applyEvalCassette, createDqlAgentProviderRunner, createEvalCassetteReplayProvider, createGovernedTextProvider, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { composeBusinessExplanation, ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildAggregationSafetyProof, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, normalizeWarehouseSqlFailure, parseProposal, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, previewSkillChange, buildContextAuthoringProposal, contextAuthoringDependencyClosure, FileContextAuthoringProposalStore, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, createAgentRunBudget, isProbeSafeColumn, deadlineScale, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, assertProviderPayloadAllowed, createProviderDispatchEgressReceipt, prepareProviderWireEnvelopeForDispatch, markProviderMetadataArray, createProviderEgressReceipt, redactProviderResultRows, composeVerifiedAnalyticalNarrative, buildCoverageGap, capResearchBranches, buildResearchEvidenceLedger, buildAnalyticalTurnPlan, resolveTopRankedRegionDependency, DEFAULT_ASK_ROW_EGRESS_POLICY, ZERO_ROW_EGRESS_POLICY, resolveProviderResultRowEgressPolicy, normalizeCanonicalQueryResult, normalizeAnalyticalExecutionFingerprint, normalizeAnalyticalExecutionReceipt, createAgentRunCancellationError, } from '@duckcodeailabs/dql-agent';
+import { composeBusinessExplanation, ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildAggregationSafetyProof, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, normalizeWarehouseSqlFailure, parseProposal, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, previewSkillChange, buildContextAuthoringProposal, contextAuthoringDependencyClosure, FileContextAuthoringProposalStore, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, createAgentRunBudget, isProbeSafeColumn, deadlineScale, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, assertProviderPayloadAllowed, createProviderDispatchEgressReceipt, prepareProviderWireEnvelopeForDispatch, markProviderMetadataArray, createProviderEgressReceipt, redactProviderResultRows, composeVerifiedAnalyticalNarrative, classifyProviderFailure, buildCoverageGap, capResearchBranches, buildResearchEvidenceLedger, buildResearchEvidenceLedgerV2, buildResearchHypothesisPlanV2, inferResearchValidatorKind, buildAnalyticalTurnPlan, buildAnalyticalRequirementSet, resolveTopRankedRegionDependency, DEFAULT_ASK_ROW_EGRESS_POLICY, ZERO_ROW_EGRESS_POLICY, resolveProviderResultRowEgressPolicy, normalizeCanonicalQueryResult, normalizeAnalyticalExecutionFingerprint, normalizeAnalyticalExecutionReceipt, createAgentRunCancellationError, } from '@duckcodeailabs/dql-agent';
 import { addSqlResultFilter, dashboardFilterableResultColumns, filterableResultColumns, replaceBlockStudioSql } from './sql-result-filter.js';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization, } from './apps-api.js';
@@ -314,10 +314,14 @@ export function parseAgentRunRequestBody(body) {
             selectedObject,
             executionTarget,
             workspaceContext,
-            conversationContext: sanitizeClientConversationContext(agentRunRecord(record.conversationContext)),
+            conversationContext: sanitizeClientConversationContext(agentRunRecord(record.conversationContext), {
+                stripStructuredSelectionEnvelope: Boolean(agentRunString(record.selectedEvidenceId)),
+            }),
             history: parseAgentRunHistory(record.history),
             threadId: agentRunString(record.threadId),
-            runId: agentRunString(record.runId),
+            // `runId` is deliberately absent at public ingress. It scopes the
+            // controller, persisted run, SSE operation, and one-shot SQL capability,
+            // so a browser-supplied value must never become execution authority.
             reasoningEffort: parseAgentRunReasoningEffort(record.reasoningEffort),
             analysisDepth: parseAgentRunAnalysisDepth(record.analysisDepth) ?? parseAgentRunAnalysisDepth(record.depth),
             thinkingMode: coerceThinkingMode(record.thinkingMode),
@@ -334,12 +338,21 @@ const CLIENT_PLAN_AUTHORITY_KEYS = new Set([
     // a child filter or skip ordinary member validation.
     'analyticalTaskDependencyBinding',
 ]);
+// A no-thread embedding may retain ordinary conversation context, but a
+// selectedEvidenceId is a structured server continuation—not a client plan
+// hint. Strip this state only for that selection path, while always stripping
+// the host-only authority marker below.
+const CLIENT_STRUCTURED_SELECTION_AUTHORITY_KEYS = new Set([
+    'conversationEnvelope',
+    'serverSnapshot',
+    'serverIssuedClarificationSelection',
+]);
 /**
  * Browser/embedding context is useful retrieval and history input, but it is
  * not a plan-authority channel. Remove plan-shaped fields recursively at HTTP
  * ingress; server-retained thread context is added afterwards from local state.
  */
-function sanitizeClientConversationContext(context) {
+function sanitizeClientConversationContext(context, options = {}) {
     if (!context)
         return undefined;
     const sanitize = (value) => {
@@ -348,7 +361,14 @@ function sanitizeClientConversationContext(context) {
         const record = agentRunRecord(value);
         if (!record)
             return value;
-        return Object.fromEntries(Object.entries(record).flatMap(([key, nested]) => CLIENT_PLAN_AUTHORITY_KEYS.has(key) ? [] : [[key, sanitize(nested)]]));
+        return Object.fromEntries(Object.entries(record).flatMap(([key, nested]) => {
+            const isHostOnlySelectionAuthority = key === 'serverIssuedClarificationSelection';
+            const isUntrustedSelectionEnvelope = options.stripStructuredSelectionEnvelope
+                && CLIENT_STRUCTURED_SELECTION_AUTHORITY_KEYS.has(key);
+            return CLIENT_PLAN_AUTHORITY_KEYS.has(key) || isHostOnlySelectionAuthority || isUntrustedSelectionEnvelope
+                ? []
+                : [[key, sanitize(nested)]];
+        }));
     };
     return sanitize(context);
 }
@@ -537,6 +557,18 @@ export function agentAnswerHasExecutionFailure(governedAnswer) {
     return typeof governedAnswer.executionError === 'string'
         && governedAnswer.executionError.trim().length > 0;
 }
+/**
+ * Return only a router/producer-issued analytical gap witness.
+ *
+ * `terminalOutcome.kind === 'modeling_gap'` is deliberately insufficient to
+ * claim a relationship problem. Older receipts and generic tuple failures
+ * return `undefined`; callers render generic coverage guidance for those.
+ */
+export function persistedAnalyticalGapWitness(routeDecision) {
+    return routeDecision?.terminalOutcome?.kind === 'modeling_gap'
+        ? routeDecision.terminalOutcome.gap
+        : undefined;
+}
 /** Rebuild the immutable failed-run input from the artifact retained by API-007. */
 export function analyticalFailedRunFromAgentRun(run) {
     for (const artifact of run.artifacts) {
@@ -888,7 +920,7 @@ function businessNarrativeGaps(warnings) {
 // When a run carries a threadId, the persisted thread is the authoritative
 // source of prior turns (survives refresh); the client-built context remains
 // the fallback for embedders that never send a threadId.
-async function conversationContextFromThread(store, threadId, clientContext, question) {
+async function conversationContextFromThread(store, threadId, clientContext, question, preservePendingClarification = false) {
     // Token-budget backstop: six verbatim turns with per-field caps. Older turns
     // remain reachable through the rolling summary + semantic recall below —
     // carrying more raw prose mostly slows every provider call on follow-ups.
@@ -936,7 +968,10 @@ async function conversationContextFromThread(store, threadId, clientContext, que
     const thread = store.getThread(threadId);
     // Bounded structured snapshot (working state + rolling summary + topic relation)
     // for the answer loop's conversation-state prompt section.
-    const serverSnapshot = buildConversationSnapshot(store, threadId, { question });
+    const serverSnapshot = buildConversationSnapshot(store, threadId, {
+        question,
+        preservePendingClarification,
+    });
     if (serverSnapshot && question) {
         // Semantic recall over OLDER turns (the recent window is already verbatim).
         serverSnapshot.recalledTurns = await recallRelevantTurns(store, threadId, question, {
@@ -944,12 +979,26 @@ async function conversationContextFromThread(store, threadId, clientContext, que
             excludeTurnIds: serverSnapshot.recentTurns.map((turn) => turn.id),
         });
     }
+    const pendingSelection = serverSnapshot?.pendingClarification?.selection;
+    const pendingSourceTurnId = serverSnapshot?.pendingClarification?.sourceTurnId;
+    // This value never crosses the HTTP boundary from a client. It is rebuilt
+    // only after the local conversation store has resolved the requested thread,
+    // and the router requires it for every selectedEvidenceId continuation.
+    const serverIssuedClarificationSelection = pendingSelection?.snapshotId && pendingSourceTurnId
+        ? {
+            version: 1,
+            threadId,
+            sourceTurnId: pendingSourceTurnId,
+            snapshotId: pendingSelection.snapshotId,
+        }
+        : undefined;
     return {
         ...(sanitizeClientConversationContext(clientContext) ?? {}),
         conversationStateVersion: 1,
         threadId,
         ...(serverSnapshot ? { conversationEnvelope: serverSnapshot } : {}),
         ...(serverSnapshot ? { serverSnapshot } : {}),
+        ...(serverIssuedClarificationSelection ? { serverIssuedClarificationSelection } : {}),
         ...(thread?.rollingSummary ? { conversationSummary: thread.rollingSummary } : {}),
         // `activeTurnId` is the FOLLOW-UP ANCHOR: the turn whose filters, prior DQL
         // artifact, and source SQL the next question builds on. Anchoring it to the
@@ -1119,6 +1168,40 @@ export function conversationTurnInputFromRun(run) {
     const contextPack = agentRunRecord(payload?.contextPack);
     const questionPlan = agentRunRecord(contextPack?.questionPlan);
     const requestedShape = agentRunRecord(questionPlan?.requestedShape);
+    // A structured clarification choice must survive reload/restart with the
+    // exact option IDs and typed requirements that rendered it. This is stored
+    // inside the existing JSON contract envelope so older conversation rows stay
+    // readable; the router treats it as reject-only continuity evidence and
+    // always rechecks the current snapshot before it can freeze a plan.
+    // Most analytical clarifications retain the router-owned cascade requirement
+    // set. Evidence-only ambiguity deliberately has no frozen cascade, however,
+    // and its first rendered options still need a typed, reload-safe contract.
+    // Derive that narrow fallback from the immutable original question and the
+    // already-resolved intent—not from a later click or client context—so the
+    // first valid structured selection can be revalidated without weakening the
+    // server-issued-envelope requirement.
+    const clarificationRequirements = run.diagnosticReceiptV3?.cascade?.requirements
+        ?? run.routeDecision?.analyticalCascadeDecision?.requirements
+        ?? (run.status === 'needs_clarification' && (run.clarificationOptions?.length ?? 0) > 0
+            ? buildAnalyticalRequirementSet({
+                question: run.question,
+                parsedIntent: run.routeDecision?.meaningResolution?.queryIntent,
+            })
+            : undefined);
+    const clarificationSelection = run.status === 'needs_clarification'
+        && (run.clarificationOptions?.length ?? 0) > 0
+        ? {
+            version: 1,
+            optionIds: [...new Set(run.clarificationOptions.map((option) => option.id).filter(Boolean))].slice(0, 16),
+            ambiguityCandidateIds: [...new Set(run.clarificationOptions.map((option) => option.id).filter(Boolean))].slice(0, 16),
+            ...(clarificationRequirements
+                ? { requirements: clarificationRequirements }
+                : {}),
+            ...(run.routeDecision?.retrievalEvidence?.snapshotId
+                ? { snapshotId: run.routeDecision.retrievalEvidence.snapshotId }
+                : {}),
+        }
+        : undefined;
     const rowCountRaw = result?.rowCount;
     const measureColumns = conversationMeasureColumns(columns, requestedShape, rows);
     return {
@@ -1127,7 +1210,13 @@ export function conversationTurnInputFromRun(run) {
         answerSummary: run.answer ?? run.summary,
         answerText: run.answer,
         route: run.route,
-        trustLabel: agentRunString(payload?.trustLabel) ?? run.trustState,
+        // A route/context label is presentation metadata, not the terminal trust
+        // authority. In particular, a certified run can retain a `mixed` context
+        // label from candidates considered before the certified tuple froze. Using
+        // that label here made the persisted conversation contradict the immutable
+        // run. Persist the canonical run state unless the answer itself has
+        // multiple materially different answer sections.
+        trustLabel: conversationTrustLabelFromRun(run, payload),
         runStatus: run.status,
         stopReason: run.stopReason,
         // Persisted so a later turn can tell a refusal from an answer. `runStatus`
@@ -1153,9 +1242,41 @@ export function conversationTurnInputFromRun(run) {
                 rowCount: typeof rowCountRaw === 'number' ? rowCountRaw : rows.length || undefined,
             }
             : undefined,
-        contract: requestedShape,
+        contract: {
+            ...(requestedShape ?? {}),
+            ...(clarificationSelection ? { clarificationSelection } : {}),
+        },
     };
 }
+function conversationTrustLabelFromRun(run, payload) {
+    if (!isCanonicalConversationTrustState(run.trustState)) {
+        return agentRunString(payload?.trustLabel);
+    }
+    return hasMixedAnswerSectionTrust(run.artifacts) ? 'mixed' : run.trustState;
+}
+function isCanonicalConversationTrustState(value) {
+    return value === 'certified'
+        || value === 'governed'
+        || value === 'grounded'
+        || value === 'review_required'
+        || value === 'blocked'
+        || value === 'not_applicable';
+}
+/**
+ * `mixed` is meaningful only when the durable answer contains sections with
+ * materially different trust states. Supporting artifacts such as a DQL draft
+ * or a diagnostics receipt do not turn one certified answer into mixed trust.
+ */
+function hasMixedAnswerSectionTrust(artifacts) {
+    const states = new Set(artifacts
+        .filter((artifact) => artifact.kind === 'answer' || artifact.kind === 'research_run')
+        .map((artifact) => artifact.trustState)
+        .filter((state) => state === 'certified'
+        || state === 'governed'
+        || state === 'grounded'
+        || state === 'review_required'));
+    return states.size > 1;
+}
 function conversationResultColumns(value) {
     if (!Array.isArray(value))
         return [];
@@ -1167,10 +1288,24 @@ function conversationResultColumns(value) {
         .slice(0, 24);
 }
 function conversationMeasureColumns(columns, requestedShape, rows) {
+    // A requested phrase is not evidence that the execution returned that
+    // measure.  In particular, an incomplete certified block used to persist
+    // `revenue` beside its actual `lifetime_spend` output merely because the
+    // request said revenue.  Retain an exact requested column only when it is
+    // actually present in the result contract.
     const requested = conversationStringArray(requestedShape?.measures) ?? [];
+    const canonical = (value) => value.toLowerCase()
+        .replace(/[_./:-]+/g, ' ')
+        .replace(/[^a-z0-9 ]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const actualRequestedColumns = columns.filter((column) => {
+        const identity = canonical(column);
+        return identity.length > 0 && requested.some((measure) => canonical(measure) === identity);
+    });
     const numericColumns = columns.filter((column) => rows.some((row) => typeof row[column] === 'number' && Number.isFinite(row[column])));
     const metricNamedColumns = columns.filter((column) => /\b(revenue|sales|amount|total|count|average|avg|sum|spend|cost|margin|profit|value|points?|score|quantity|units?|rate|volume)\b/i.test(column.replace(/_/g, ' ')));
-    const unique = Array.from(new Set([...requested, ...numericColumns, ...metricNamedColumns]
+    const unique = Array.from(new Set([...actualRequestedColumns, ...numericColumns, ...metricNamedColumns]
         .map((value) => value.trim())
         .filter(Boolean)));
     return unique.length > 0 ? unique.slice(0, 24) : undefined;
@@ -2228,11 +2363,12 @@ export async function startLocalServer(opts) {
             runner = createDqlAgentProviderRunner('ollama', deterministicProvider);
         }
         if (!resolvedProvider || !runner) {
-            throw new Error('No AI provider is configured. Configure a subscription (Claude Code / Codex), OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+            throw Object.assign(new Error('No AI provider is configured. Configure a subscription (Claude Code / Codex), OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.'), { code: 'AUTHENTICATION_FAILED', providerPhase: 'preflight' });
         }
         let governedAnswer;
         let providerError;
         let providerDispatchEvidence;
+        let providerBoundaryDiagnostic;
         const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
         // The chat composer sends a `thinkingMode` (auto/low/medium/high); resolve it
         // into the effort+depth bundle it stands for. An explicit `reasoningEffort` /
@@ -2299,6 +2435,37 @@ export async function startLocalServer(opts) {
         const requestedPurpose = agentRunWorkspaceValue(request, 'purpose');
         const requestedModelAreaId = agentRunWorkspaceValue(request, 'modelAreaId');
         const runProjectSnapshot = projectSnapshot();
+        // Keep the execution callback on the exact ranked context pack that the
+        // router used.  The engine can invoke the executor after the router's
+        // asynchronous evidence phase, so looking the pack up lazily inside the
+        // callback occasionally observed an empty WeakMap entry and sent an
+        // authored leaf relation straight to the connector.  That bypassed the
+        // same-snapshot qualified relation binding despite retrieval having proved
+        // (for example) `jaffle_shop.dev.dim_customers`.
+        //
+        // Building only when this request has no prepared entry retains the normal
+        // single-retrieval path.  A frozen certified plan below rejects a pack whose
+        // snapshot/fingerprint does not match the router decision rather than
+        // borrowing a newer catalog to make an old plan executable.
+        const preparedContextPack = preparedAgentContextPacks.get(request)
+            ?? await buildAgentRunContextPack(request).catch(() => undefined);
+        const preparedQualifiedSchemaContext = preparedContextPack
+            ? buildAgentSchemaContextFromContextPack(request.question, preparedContextPack)
+            : [];
+        const selectedExploratoryAttempt = routeDecision?.analyticalCascadeDecision?.attempts.find((attempt) => attempt.tier === 'exploratory_sql');
+        // The exploratory candidate set belongs to the router's immutable
+        // same-snapshot cascade decision.  Build its physical prompt/execution
+        // closure once here; the broad retrieved pack remains receipt-only and is
+        // never handed to SQL validation for this selected tier.
+        const exploratoryCandidateIds = routeDecision?.analyticalCascadeDecision?.selectedTier === 'exploratory_sql'
+            ? selectedExploratoryAttempt?.candidateIds ?? []
+            : [];
+        const preparedExploratoryContextPack = exploratoryCandidateIds.length > 0
+            ? scopeContextPackToExploratoryCandidateClosure(preparedContextPack, exploratoryCandidateIds)
+            : undefined;
+        const preparedExploratoryQualifiedSchemaContext = preparedExploratoryContextPack
+            ? buildAgentSchemaContextFromContextPack(request.question, preparedExploratoryContextPack, { includeUnscored: true, limit: 80 })
+            : [];
         const domainContext = requestedDomain
             ? resolveUiDomainContext({
                 manifest: runProjectSnapshot.manifest,
@@ -2313,6 +2480,143 @@ export async function startLocalServer(opts) {
         // Local to this exact answer invocation. Compound children each enter this
         // function separately, so no child can consume another child's capability.
         const agenticExecutionCapabilityGate = new AgenticExecutionCapabilityGate();
+        const prepareExploratorySqlExecution = async (sql) => {
+            const cascade = routeDecision?.analyticalCascadeDecision;
+            const selectedAttempt = selectedExploratoryAttempt;
+            if (!cascade
+                || cascade.selectedTier !== 'exploratory_sql'
+                || cascade.planFrozen
+                || !selectedAttempt
+                || selectedAttempt.outcome !== 'executable'
+                || selectedAttempt.candidateIds.length === 0) {
+                throw analyticalError('The generated SQL no longer matches the router-selected exploratory path, so DQL did not authorize execution.', {
+                    origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                });
+            }
+            if (!request.runId || !semanticConnection || !preparedContextPack || !preparedExploratoryContextPack) {
+                throw analyticalError('DQL could not bind the selected exploratory query to this run, target, and metadata snapshot, so it was not executed.', {
+                    origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                });
+            }
+            const retrievalSnapshotId = routeDecision?.retrievalEvidence?.snapshotId;
+            const retrievalSourceFingerprint = routeDecision?.retrievalEvidence?.sourceFingerprint;
+            const retrievalFreezeSnapshotId = retrievalSnapshotId ?? preparedContextPack.knowledgeLens.snapshotId;
+            if ((retrievalSnapshotId && retrievalSnapshotId !== preparedContextPack.knowledgeLens.snapshotId)
+                || (retrievalSourceFingerprint
+                    && preparedContextPack.freshness.fingerprint
+                    && retrievalSourceFingerprint !== preparedContextPack.freshness.fingerprint)) {
+                throw analyticalError('The selected exploratory query no longer matches its retrieval snapshot or source fingerprint, so it was not executed.', {
+                    origin: 'governance_gate', stage: 'validation', code: 'snapshot_drift',
+                });
+            }
+            projectSnapshot();
+            projectSnapshots.assertCurrent(runProjectSnapshot.snapshotId);
+            const target = await observeWarehouseTargetIdentity(executor, semanticConnection);
+            if (generatedProposalTargetIdentity?.identityFingerprint
+                && target.identityFingerprint !== generatedProposalTargetIdentity.identityFingerprint) {
+                throw analyticalError('The selected exploratory query no longer matches the observed execution target, so it was not executed.', {
+                    origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                });
+            }
+            const validation = validateAuthorizedSqlReferences(sql, preparedExploratoryContextPack, {
+                ...(semanticDriver ? { dialect: semanticDriver } : {}),
+                runtimeSchema: preparedExploratoryQualifiedSchemaContext,
+            });
+            if (!validation.ok) {
+                throw analyticalError('The selected exploratory query did not pass the host SQL/context validation, so it was not executed.', {
+                    origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                });
+            }
+            const normalizeIdentifier = (value) => value
+                .trim()
+                .split('.')
+                .map((part) => part.trim().replace(/^["`\[]|["`\]]$/g, '').toLowerCase())
+                .filter(Boolean)
+                .join('.');
+            const allowedExploratoryRelations = new Set(preparedExploratoryQualifiedSchemaContext.map((table) => normalizeIdentifier(table.relation)));
+            const outsideClosure = validation.referencedRelations.filter((relation) => !allowedExploratoryRelations.has(normalizeIdentifier(relation)));
+            if (outsideClosure.length > 0) {
+                throw analyticalError('The generated SQL references a relation outside the router-selected physical closure, so it was not executed.', {
+                    origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                });
+            }
+            const runtimeByRelation = new Map(preparedExploratoryQualifiedSchemaContext.map((table) => [normalizeIdentifier(table.relation), table]));
+            const qualifiedReferences = qualifyAuthorizationReferences(sql, {
+                relations: validation.referencedRelations,
+                columns: validation.referencedColumns,
+            });
+            const proofs = new Map();
+            for (const relation of validation.referencedRelations) {
+                const table = runtimeByRelation.get(normalizeIdentifier(relation));
+                if (!table) {
+                    throw analyticalError('The selected exploratory query references a relation that was not proven by the live runtime schema, so it was not executed.', {
+                        origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                    });
+                }
+                proofs.set(table.relation, 'schema_tool');
+            }
+            for (const reference of qualifiedReferences) {
+                const normalizedReference = normalizeIdentifier(reference);
+                const table = [...runtimeByRelation.entries()].find(([relation]) => normalizedReference.startsWith(`${relation}.`));
+                if (!table)
+                    continue;
+                const [, runtimeTable] = table;
+                const column = normalizedReference.slice(`${table[0]}.`.length);
+                if (!column || !runtimeTable.columns.some((candidate) => normalizeIdentifier(candidate.name) === column)) {
+                    throw analyticalError('The selected exploratory query references a column that was not proven by the live runtime schema, so it was not executed.', {
+                        origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                    });
+                }
+                proofs.set(`${runtimeTable.relation}.${column}`, 'schema_tool');
+            }
+            const candidateIds = [...selectedAttempt.candidateIds];
+            const sqlFingerprint = executionFingerprint(sql);
+            const planFingerprint = executionFingerprint(stableExecutionValue({
+                version: 1,
+                tier: 'exploratory_sql',
+                snapshotId: retrievalFreezeSnapshotId,
+                executionSnapshotId: runProjectSnapshot.snapshotId,
+                sourceFingerprint: preparedContextPack.freshness.fingerprint,
+                targetFingerprint: target.identityFingerprint,
+                candidateIds,
+                sqlFingerprint,
+            }));
+            const planId = `exploratory-${planFingerprint.slice(0, 24)}`;
+            const capability = createAgenticSqlExecutionCapability({
+                sql,
+                proven: [...proofs.entries()].map(([identifier, evidence]) => ({ identifier, evidence })),
+                runId: request.runId,
+                executionId: `${request.runId}:exploratory:${sqlFingerprint.slice(0, 16)}`,
+                snapshotId: runProjectSnapshot.snapshotId,
+                planId,
+                targetFingerprint: target.identityFingerprint,
+                // Keep the capability binding shape identical to the direct execution
+                // boundary below. An omitted generated-artifact binding is represented
+                // there as `{ sqlParams: [], variables: {} }`, not `{}`; minting the
+                // latter made a fully validated immutable proposal fail only after its
+                // exploratory plan had frozen.
+                bindings: { sqlParams: [], variables: {} },
+            });
+            if (!capability) {
+                throw analyticalError('DQL could not mint a request-scoped exploratory execution capability, so it was not executed.', {
+                    origin: 'governance_gate', stage: 'validation', code: 'unauthorized_sql',
+                });
+            }
+            return {
+                capability,
+                freeze: {
+                    version: 1,
+                    selectedTier: 'exploratory_sql',
+                    planId,
+                    planFingerprint,
+                    snapshotId: retrievalFreezeSnapshotId,
+                    targetFingerprint: target.identityFingerprint,
+                    sqlFingerprint: capability.candidateSqlFingerprint,
+                    candidateIds,
+                    authorization: 'capability_minted',
+                },
+            };
+        };
         await runner.run({
             provider: resolvedProvider,
             ...(agentRunProviderEvidenceContext.getStore()
@@ -2344,7 +2648,14 @@ export async function startLocalServer(opts) {
             // Keys the execution authorization, so the proofs the analyst loop
             // gathers can be checked against the statement this run executes.
             ...(request.runId ? { agentRunId: request.runId } : {}),
-            preparedContextPack: preparedAgentContextPacks.get(request),
+            preparedContextPack,
+            // This closure is derived only from the router-owned cascade attempt
+            // above. It is intentionally not sourced from the HTTP request: a
+            // client or provider cannot widen the relations the exploratory prompt
+            // or capability may use.
+            ...(preparedExploratoryContextPack
+                ? { preparedExploratoryContextPack }
+                : {}),
             domainContext,
             projectSnapshot: { snapshotId: runProjectSnapshot.snapshotId, manifest: runProjectSnapshot.manifest },
             assertProjectSnapshot: (snapshotId) => {
@@ -2505,12 +2816,59 @@ export async function startLocalServer(opts) {
             ...(routeDecision?.resolvedAnalyticalPlan
                 ? { resolvedAnalyticalPlan: routeDecision.resolvedAnalyticalPlan }
                 : {}),
+            ...(routeDecision?.analyticalCascadeDecision?.selectedTier
+                ? { selectedCascadeTier: routeDecision.analyticalCascadeDecision.selectedTier }
+                : {}),
+            ...(exploratoryCandidateIds.length > 0
+                ? { exploratoryCandidateIds }
+                : {}),
             ...(generatedProposalTargetIdentity?.identityFingerprint
                 ? { generatedProposalTargetFingerprint: generatedProposalTargetIdentity.identityFingerprint }
                 : {}),
             analyticalReferenceInstant: new Date().toISOString(),
-            executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, semanticConnection, semanticConnectionName),
+            // A frozen certified artifact may use the human-friendly leaf relation
+            // authored in its DQL.  Its execution must still bind to the exact
+            // same-snapshot physical relation that retrieval inspected.  This is
+            // deliberately narrower than exploratory preflight: it only qualifies
+            // an unambiguous FROM/JOIN leaf already present in the artifact and it
+            // never supplies a missing table, join, or column.
+            executeCertifiedBlock: (node, invocation) => {
+                const frozenCertifiedPlan = routeDecision?.analyticalCascadeDecision?.planFrozen === true
+                    && routeDecision.analyticalCascadeDecision.selectedTier === 'certified'
+                    && routeDecision.resolvedAnalyticalPlan?.capability === 'certified_execution';
+                if (frozenCertifiedPlan) {
+                    const plan = routeDecision.resolvedAnalyticalPlan;
+                    const retrievedSourceFingerprint = routeDecision.retrievalEvidence?.sourceFingerprint;
+                    const retrievedSnapshotId = routeDecision.retrievalEvidence?.snapshotId;
+                    // A certified stamp is valid only for the exact router snapshot
+                    // and retrieval source that selected this block. The runner's
+                    // standard guard separately confirms the current host snapshot
+                    // immediately before this callback. Do not re-fingerprint the
+                    // mutable local cache here: cache refresh is not a source edit.
+                    if (retrievedSnapshotId && plan.snapshotId !== retrievedSnapshotId) {
+                        throw analyticalError('The selected certified plan no longer matches the retrieval snapshot that froze it. Refresh the answer before retrying.', { origin: 'governance_gate', stage: 'validation', code: 'snapshot_drift' });
+                    }
+                    if (plan.sourceFingerprint && retrievedSourceFingerprint
+                        && plan.sourceFingerprint !== retrievedSourceFingerprint) {
+                        throw analyticalError('The selected certified plan no longer matches the retrieval source that froze it. Refresh the answer before retrying.', { origin: 'governance_gate', stage: 'validation', code: 'snapshot_drift' });
+                    }
+                    if (!preparedContextPack
+                        || plan.snapshotId !== preparedContextPack.knowledgeLens.snapshotId) {
+                        throw analyticalError('The selected certified plan no longer matches the retrieved metadata snapshot. Refresh the answer before retrying.', { origin: 'governance_gate', stage: 'validation', code: 'snapshot_drift' });
+                    }
+                    const preparedSourceFingerprint = preparedContextPack.freshness.fingerprint;
+                    if (plan.sourceFingerprint && preparedSourceFingerprint
+                        && plan.sourceFingerprint !== preparedSourceFingerprint) {
+                        throw analyticalError('The selected certified plan no longer matches the retrieved metadata source. Refresh the answer before retrying.', { origin: 'governance_gate', stage: 'validation', code: 'snapshot_drift' });
+                    }
+                }
+                const certifiedSchemaContext = frozenCertifiedPlan
+                    ? buildFrozenCertifiedSchemaContext(preparedContextPack, runProjectSnapshot.manifest)
+                    : preparedQualifiedSchemaContext;
+                return executeCertifiedBlockForAgent(node, invocation, semanticConnection, semanticConnectionName, certifiedSchemaContext, frozenCertifiedPlan);
+            },
             executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact, semanticConnection, semanticConnectionName),
+            prepareExploratorySqlExecution,
             executeAgenticGeneratedSql: async (capability, sql, artifact) => {
                 if (!agenticExecutionCapabilityGate.consume(capability)) {
                     throw analyticalError('This analyst execution capability was already consumed; DQL did not retry it with stale proof.', {
@@ -2521,8 +2879,8 @@ export async function startLocalServer(opts) {
                     runId: request.runId,
                     executionId: capability.executionId,
                     snapshotId: runProjectSnapshot.snapshotId,
-                    planId: routeDecision?.resolvedAnalyticalPlan?.planId,
-                    targetFingerprint: generatedProposalTargetIdentity?.identityFingerprint,
+                    planId: capability.planId,
+                    targetFingerprint: capability.targetFingerprint,
                 });
             },
             executeDqlArtifact: (artifact) => executeArtifactReferenceForAgent(artifact, request.question, semanticConnection, semanticConnectionName),
@@ -2539,10 +2897,14 @@ export async function startLocalServer(opts) {
             if (turn.kind === 'error') {
                 providerError = turn.message;
                 providerDispatchEvidence = turn.dispatchEvidence;
+                providerBoundaryDiagnostic = turn.providerDiagnostic;
             }
         }, runSignal);
         if (!governedAnswer) {
-            throw Object.assign(new Error(providerError ?? 'The AI provider did not return a governed answer.'), ...(providerDispatchEvidence ? [{ providerDispatchEvidence }] : []));
+            throw Object.assign(new Error(providerError ?? 'The AI provider did not return a governed answer.'), {
+                ...(providerDispatchEvidence ? { providerDispatchEvidence } : {}),
+                ...(providerBoundaryDiagnostic ? { providerDiagnostic: providerBoundaryDiagnostic } : {}),
+            });
         }
         return governedAnswer;
     }
@@ -2580,6 +2942,68 @@ export async function startLocalServer(opts) {
     function resolvedRunRouteFromAnswer(governedAnswer) {
         return routeForCascadeAnswerTier(governedAnswer.route?.tier);
     }
+    /**
+     * Return the route the router already froze. This is intentionally derived
+     * from the typed cascade/plan, never from an answer-loop route label.
+     */
+    function frozenAnalyticalRoute(routeDecision) {
+        if (!routeDecision)
+            return undefined;
+        const cascade = routeDecision.analyticalCascadeDecision;
+        if (cascade?.planFrozen) {
+            switch (cascade.selectedTier) {
+                case 'certified': return 'certified_answer';
+                case 'semantic': return 'semantic_answer';
+                case 'governed_relational':
+                case 'exploratory_sql': return 'generated_answer';
+                default: return undefined;
+            }
+        }
+        const plan = routeDecision.resolvedAnalyticalPlan;
+        if (plan?.mode !== 'authoritative')
+            return undefined;
+        switch (plan.capability) {
+            case 'certified_execution': return 'certified_answer';
+            case 'semantic_execution': return 'semantic_answer';
+            case 'governed_relational':
+            case 'bounded_exploration': return 'generated_answer';
+            default: return undefined;
+        }
+    }
+    /**
+     * A frozen tier may fail, but cannot silently substitute a result selected by
+     * a different answer-loop lane. The engine repeats this guard so host-injected
+     * executors receive the same protection.
+     */
+    function frozenPlanRouteFailure(route, routeDecision, reportedRoute) {
+        const message = `The frozen ${route.replaceAll('_', ' ')} plan could not execute as selected. DQL did not substitute another analytical tier.`;
+        return {
+            resolvedRoute: route,
+            status: 'blocked',
+            trustState: 'blocked',
+            stopReason: 'blocked',
+            // Keep the public refusal vocabulary stable; the artifact/evaluation
+            // below retains the precise route-integrity diagnostic.
+            answerRefusalCode: 'grounding_gap',
+            summary: message,
+            answer: message,
+            artifacts: [agentRunArtifact('answer', 'Frozen analytical plan could not execute', {
+                    kind: 'no_answer',
+                    refusalCode: 'grounding_gap',
+                    frozenPlanFailureCode: 'frozen_plan_route_mismatch',
+                    text: message,
+                    selectedTier: routeDecision?.analyticalCascadeDecision?.selectedTier,
+                    selectedConceptIds: routeDecision?.meaningResolution?.selectedConceptIds ?? [],
+                    ...(reportedRoute ? { reportedRoute } : {}),
+                }, undefined, 'blocked')],
+            evaluations: [agentRunEvaluation('frozen-plan-route-mismatch', 'Frozen analytical route', false, 'blocking', `The router froze ${route.replaceAll('_', ' ')}, but the answer executor reported ${reportedRoute?.replaceAll('_', ' ') ?? 'no matching route'}.`, {
+                    selectedRoute: route,
+                    reportedRoute,
+                    selectedTier: routeDecision?.analyticalCascadeDecision?.selectedTier,
+                    planId: routeDecision?.resolvedAnalyticalPlan?.planId,
+                })],
+        };
+    }
     function groundingGapRepairHint(governedAnswer) {
         const details = governedAnswer.refusalDetails;
         if (!details)
@@ -2793,7 +3217,16 @@ export async function startLocalServer(opts) {
         if (governedAnswer.result)
             delete governedAnswer.result.dqlArtifact;
     }
-    const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emit }) => {
+    const answerRunExecutor = async ({ runId, request, route, routeDecision, attempt, repairHint, emit }) => {
+        // `AgentRunEngine` owns the canonical run ID when HTTP callers omit one.
+        // Bind that server-issued value to the same request object before the
+        // provider/SQL handoff: the prepared context pack is keyed by this object,
+        // while the exploratory capability must be scoped to the persisted run.
+        // Cloning here would lose the exact retrieval pack; accepting a missing ID
+        // would mint an unbound capability. This is server-side bookkeeping only,
+        // never client-provided execution authority.
+        if (!request.runId)
+            request.runId = runId;
         const runStartedAtMs = Date.now();
         const turnPlan = buildAnalyticalTurnPlan({
             question: request.question,
@@ -2952,6 +3385,15 @@ export async function startLocalServer(opts) {
         let governedAnswer;
         try {
             governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint }, route, (message) => emit({ type: 'executor.started', message, route }), routeDecision);
+            const frozenRoute = frozenAnalyticalRoute(routeDecision);
+            const reportedRoute = resolvedRunRouteFromAnswer(governedAnswer);
+            // Do not let the legacy answer loop reselect meaning and overwrite the
+            // router's immutable tier through `resolvedRunRouteFromAnswer`. A frozen
+            // plan either executes on its selected route or returns a same-tier,
+            // inspectable terminal failure; it never downgrades to generated SQL.
+            if (frozenRoute && (frozenRoute !== route || (reportedRoute && reportedRoute !== frozenRoute))) {
+                return frozenPlanRouteFailure(frozenRoute, routeDecision, reportedRoute);
+            }
             // Keep the canonical result contract on the answer itself, not only on
             // the narration preview. Conversation persistence, follow-up member
             // resolution, Apply, and the notebook table all read this payload; if a
@@ -3126,6 +3568,33 @@ export async function startLocalServer(opts) {
             const message = dispatchBudgetExhausted
                 ? 'Ask reached its internal provider-dispatch limit before it froze one executable analytical plan. Nothing was run. Narrow the metric or dimension and retry; this is an orchestration-budget diagnostic, not a provider outage.'
                 : formatAgentRunInfrastructureError(error, 'AI answer provider');
+            const providerCode = error && typeof error === 'object'
+                ? String(error.code ?? '')
+                : '';
+            const boundaryProviderDiagnostic = error && typeof error === 'object'
+                ? error.providerDiagnostic
+                : undefined;
+            const providerDiagnostic = boundaryProviderDiagnostic
+                && typeof boundaryProviderDiagnostic === 'object'
+                && boundaryProviderDiagnostic.version === 1
+                ? boundaryProviderDiagnostic
+                : classifyProviderFailure({
+                    code: dispatchBudgetExhausted ? 'PROVIDER_DISPATCH_BUDGET' : providerCode,
+                    // Classification happens at the provider boundary before this error is
+                    // coalesced into the friendly headline. Persist the classifier output,
+                    // never this possibly sensitive raw message.
+                    message: error instanceof Error ? error.message : String(error ?? ''),
+                    phase: /no ai provider configured|not configured or reachable/i.test(message) ? 'preflight' : 'generation',
+                    providerFingerprint: agentRunWorkspaceValue(request, 'provider')
+                        ? `sha256:${createHash('sha256').update(agentRunWorkspaceValue(request, 'provider')).digest('hex')}`
+                        : undefined,
+                    modelFingerprint: agentRunWorkspaceValue(request, 'model')
+                        ? `sha256:${createHash('sha256').update(agentRunWorkspaceValue(request, 'model')).digest('hex')}`
+                        : undefined,
+                    baseOriginFingerprint: agentRunWorkspaceValue(request, 'providerBaseOrigin')
+                        ? `sha256:${createHash('sha256').update(agentRunWorkspaceValue(request, 'providerBaseOrigin')).digest('hex')}`
+                        : undefined,
+                });
             return {
                 summary: message,
                 status: 'blocked',
@@ -3143,11 +3612,12 @@ export async function startLocalServer(opts) {
                             code: dispatchBudgetExhausted ? 'orchestration_budget_exhausted' : 'AI_PROVIDER_FAILURE',
                             message,
                             recoverable: !dispatchBudgetExhausted,
+                            diagnostic: providerDiagnostic,
                         },
                     }, undefined, 'blocked')],
                 evaluations: [
                     agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.'),
-                    agentRunEvaluation(dispatchBudgetExhausted ? 'orchestration-budget' : 'ai-provider', dispatchBudgetExhausted ? 'Internal orchestration budget' : 'AI provider', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error }),
+                    agentRunEvaluation(dispatchBudgetExhausted ? 'orchestration-budget' : 'ai-provider', dispatchBudgetExhausted ? 'Internal orchestration budget' : 'AI provider', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error, providerDiagnostic }),
                 ],
                 nextActions: [
                     ...(dispatchBudgetExhausted
@@ -3174,7 +3644,10 @@ export async function startLocalServer(opts) {
                 },
             };
         }
-        const answeredRoute = resolvedRunRouteFromAnswer(governedAnswer) ?? route;
+        // For an unfrozen legacy route, the answer loop can still describe which
+        // tier actually produced the answer. Once the router froze a cascade tier,
+        // that immutable route is the only durable provenance authority.
+        const answeredRoute = frozenAnalyticalRoute(routeDecision) ?? resolvedRunRouteFromAnswer(governedAnswer) ?? route;
         const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
         const semanticRouteClaimed = governedAnswer.route?.tier === 'semantic_metric';
         const semanticAggregationProofPassed = semanticAnswerHasPassedAggregationProof(governedAnswer);
@@ -3213,9 +3686,14 @@ export async function startLocalServer(opts) {
             && route === 'generated_answer'
             && (request.requestedMode === undefined || request.requestedMode === 'auto' || request.requestedMode === 'ask')
             && routeDecision?.resolvedAnalyticalPlan?.mode !== 'authoritative';
+        // A generic `modeling_gap` says only that the complete analytical tuple did
+        // not prove out. Relationship-specific repair language is allowed solely
+        // when the router retained a structured coverage witness.
+        const persistedGapWitness = persistedAnalyticalGapWitness(routeDecision);
+        const relationshipSpecificGap = persistedGapWitness?.code === 'MISSING_RELATIONSHIP';
         const typedCoverageGap = (isGroundingGap || isModelDeclined)
             ? buildCoverageGap({
-                code: governedAnswer.refusalCode === 'modeling_gap' ? 'MISSING_RELATIONSHIP' : 'MISSING_RUNTIME_CAPABILITY',
+                code: persistedGapWitness?.code ?? 'MISSING_RUNTIME_CAPABILITY',
                 phase: 'planning',
                 message: governedAnswer.refusalDetails?.message
                     ?? (isModelDeclined
@@ -3223,17 +3701,21 @@ export async function startLocalServer(opts) {
                         : 'The retrieved context did not prove the metadata required for this analytical question.'),
                 searchedSources: ['certified_blocks', 'semantic_metrics', 'dbt_manifest', 'relationship_graph', 'warehouse_metadata'],
                 attemptedRoutes: ['certified', 'semantic', 'governed_relational', 'generated'],
-                missing: governedAnswer.refusalDetails?.offending
-                    ? [
-                        governedAnswer.refusalDetails.offending.relation,
-                        governedAnswer.refusalDetails.offending.column,
-                    ].filter((value) => Boolean(value))
-                    : ['an executable metric/dimension/relationship tuple'],
+                missing: persistedGapWitness?.missing.length
+                    ? persistedGapWitness.missing
+                    : governedAnswer.refusalDetails?.offending
+                        ? [
+                            governedAnswer.refusalDetails.offending.relation,
+                            governedAnswer.refusalDetails.offending.column,
+                        ].filter((value) => Boolean(value))
+                        : ['the complete requested analytical tuple'],
                 recoverable: canRecoverPreFreezeGap,
                 planFrozen: routeDecision?.resolvedAnalyticalPlan?.mode === 'authoritative',
                 nextActions: canRecoverPreFreezeGap
                     ? ['continue through DBT-grounded relational context', 'run review-required generated SQL', 'start bounded Research if coverage remains incomplete']
-                    : ['review the retained metadata gap', 'select a governed metric or dimension', 'repair modeling if the relationship is missing'],
+                    : relationshipSpecificGap
+                        ? ['review the retained relationship proof', 'repair the certified relationship in Modeling', 'retry after relationship validation']
+                        : ['review the retained metadata gap', 'select a governed metric or dimension', 'repair the missing metric, dimension, or output contract'],
             })
             : undefined;
         // Only a genuinely AMBIGUOUS question is surfaced as "needs clarification".
@@ -3501,12 +3983,15 @@ export async function startLocalServer(opts) {
             : isTerminalFailure
                 ? terminalFailureActions
                 : isGroundingGap
-                    ? governedAnswer.refusalCode === 'modeling_gap'
+                    ? relationshipSpecificGap
                         ? [
-                            { id: 'fix-modeling-gap', label: 'Fix with Modeling AI', route: 'modeling_draft', artifactKind: 'modeling_change_proposal' },
+                            { id: 'repair-relationship-proof', label: 'Repair relationship proof in Modeling', route: 'modeling_draft', artifactKind: 'modeling_change_proposal' },
+                            { id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' },
+                        ]
+                        : [
+                            { id: 'review-metadata-gap', label: 'Review missing metadata coverage', route: 'blocked' },
                             { id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' },
                         ]
-                        : [{ id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' }]
                     : [
                         { id: 'create-block', label: governedAnswer.dqlArtifact ? 'Review DQL draft' : 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
                         { id: 'research-gap', label: 'Research deeper', route: 'research' },
@@ -3661,6 +4146,9 @@ export async function startLocalServer(opts) {
             providerEgressReceipts: finalProviderEgressReceipts,
             telemetry: finalTelemetry,
             narrationIntegrityReceipt,
+            ...(governedAnswer.exploratoryExecutionFreeze
+                ? { analyticalExecutionFreeze: governedAnswer.exploratoryExecutionFreeze }
+                : {}),
         };
     };
     /**
@@ -4198,6 +4686,38 @@ export async function startLocalServer(opts) {
             if (plan.done && !plan.followUp && request.requestedMode !== 'research') {
                 return answerRunExecutor(researchContext);
             }
+            // This is the executable, receipt-bound research plan. It carries the
+            // branch hypothesis/expectation/validator kind into every child rather
+            // than treating V2 as a presentation-only wrapper after the work ends.
+            const typedResearchPlan = buildResearchHypothesisPlanV2({
+                hypotheses: plan.steps.map((step, index) => ({
+                    id: `h${index + 1}`,
+                    statement: step.thought,
+                    expectation: step.expectation,
+                    targetId: step.action.target,
+                    validatorKind: inferResearchValidatorKind(step.thought, step.expectation),
+                })),
+            });
+            // The V2 contract is the executable branch authority: retain its stable
+            // hypothesis ID, wording, expectation, target, and validator kind while
+            // borrowing only the already-grounded action kind from the planner. This
+            // prevents a presentation-only V2 ledger from drifting away from the
+            // child runs that actually produced the receipts.
+            const executableResearchBranches = typedResearchPlan.hypotheses.flatMap((hypothesis) => {
+                const planned = plan.steps.find((step) => step.thought.trim() === hypothesis.statement
+                    && step.action.target === hypothesis.targetId)
+                    ?? plan.steps.find((step) => step.action.target === hypothesis.targetId);
+                if (!planned)
+                    return [];
+                return [{
+                        hypothesisId: hypothesis.id,
+                        validatorKind: hypothesis.validatorKind,
+                        thought: hypothesis.statement,
+                        expectation: hypothesis.expectation,
+                        action: { ...planned.action, target: hypothesis.targetId },
+                    }];
+            });
+            const typedHypothesesById = new Map(typedResearchPlan.hypotheses.map((hypothesis) => [hypothesis.id, hypothesis]));
             const needsClarification = Boolean(plan.followUp);
             const notebookPath = agentRunNotebookPath(request, runId);
             const researchIntent = agentRunResearchIntent(request);
@@ -4258,6 +4778,8 @@ export async function startLocalServer(opts) {
                         // attempt, not a fabricated successful finding; its durable status
                         // and receipt determine the ledger entry.
                         const fallbackBranch = {
+                            hypothesisId: 'fallback:context',
+                            validatorKind: 'counter_evidence',
                             thought: 'Inspect the requested analytical question against the frozen root context.',
                             action: {
                                 kind: 'lookup_metric',
@@ -4265,7 +4787,7 @@ export async function startLocalServer(opts) {
                             },
                             expectation: 'Whether the frozen context contains enough evidence for a bounded answer.',
                         };
-                        const branches = capResearchBranches(plan.steps.length > 0 ? plan.steps : [fallbackBranch], 6);
+                        const branches = capResearchBranches(executableResearchBranches.length > 0 ? executableResearchBranches : [fallbackBranch], 6);
                         // The replan edge. Each branch tests one hypothesis; folding its
                         // outcome back into the state is what lets the investigation stop
                         // when the question is settled instead of grinding through a plan
@@ -4292,7 +4814,7 @@ export async function startLocalServer(opts) {
                                 });
                                 break;
                             }
-                            const branchId = `${step.action.kind}:${step.action.target}`;
+                            const branchId = step.hypothesisId;
                             const branchQuestion = `${request.question}\nResearch branch ${index + 1} (${branchId}): ${step.expectation}`;
                             const childId = `${created.id}:research:${index + 1}`;
                             const child = storage.createRun({
@@ -4313,6 +4835,9 @@ export async function startLocalServer(opts) {
                                     rootPlanId: plan.rootPlanId,
                                     branch: {
                                         id: branchId,
+                                        hypothesisId: step.hypothesisId,
+                                        hypothesis: step.thought,
+                                        validatorKind: step.validatorKind,
                                         index: index + 1,
                                         expectation: step.expectation,
                                         action: step.action,
@@ -4337,7 +4862,15 @@ export async function startLocalServer(opts) {
                                         ...researchContextEnvelope,
                                         rootRunId: created.id,
                                         rootPlanId: plan.rootPlanId,
-                                        branch: { id: branchId, index: index + 1, expectation: step.expectation, action: step.action },
+                                        branch: {
+                                            id: branchId,
+                                            hypothesisId: step.hypothesisId,
+                                            hypothesis: step.thought,
+                                            validatorKind: step.validatorKind,
+                                            index: index + 1,
+                                            expectation: step.expectation,
+                                            action: step.action,
+                                        },
                                     },
                                     executionConnection: researchExecutionConnection,
                                     executionConnectionName: researchExecutionConnectionName,
@@ -4465,10 +4998,50 @@ export async function startLocalServer(opts) {
                     ? 'not_started'
                     : researchRuns.some((run) => run.status === 'error')
                         ? 'insufficient_evidence'
-                        : plan.steps.length > 6
+                        : executableResearchBranches.length > 6
                             ? 'budget'
                             : 'completed',
             });
+            // V2 carries a verdict per bounded hypothesis and makes a deliberately
+            // small investigation visible to the caller. A returned row is still
+            // only an observation: without a deterministic expectation validator it
+            // remains inconclusive rather than being promoted to causal support.
+            const researchLedgerV2 = buildResearchEvidenceLedgerV2({
+                rootQuestion: request.question,
+                planId: plan.rootPlanId,
+                snapshotId: routeDecision?.resolvedAnalyticalPlan?.snapshotId,
+                groundableBranchCount: typedResearchPlan.hypotheses.length,
+                entries: researchLedger.entries.map((entry, index) => ({
+                    ...entry,
+                    hypothesis: typedHypothesesById.get(entry.branchId)?.statement ?? plan.steps[index]?.thought,
+                    verdict: entry.status === 'failed'
+                        ? 'failed'
+                        : entry.status === 'skipped'
+                            ? 'skipped'
+                            : entry.rowCount === 0
+                                ? 'contradicted'
+                                : 'inconclusive',
+                    ...(entry.status === 'observed' && entry.resultFingerprint
+                        ? {
+                            validator: {
+                                version: 1,
+                                kind: typedHypothesesById.get(entry.branchId)?.validatorKind
+                                    ?? inferResearchValidatorKind(plan.steps[index]?.thought ?? '', plan.steps[index]?.expectation ?? ''),
+                                // This proves that the branch completed the deterministic
+                                // receipt-bound observation. It deliberately does not claim
+                                // the hypothesis was true: rows/correlation alone remain
+                                // inconclusive until a stronger domain-specific predicate is
+                                // supplied by a future validator.
+                                evaluated: true,
+                                ...(entry.rowCount === 0 ? { outcome: 'contradicts_observation' } : {}),
+                                receiptFingerprints: [entry.resultFingerprint],
+                            },
+                        }
+                        : {}),
+                    counterEvidenceFactIds: entry.rowCount === 0 ? entry.facts.slice(0, 1) : [],
+                })),
+                stoppingReason: researchLedger.stoppingReason,
+            });
             // A query that ran and matched 0 rows STILL executed — treat it as a clean,
             // grounded execution (not "no result"), so an empty answer is surfaced as
             // "0 rows matched" rather than silently downgraded to review-required.
@@ -4491,15 +5064,16 @@ export async function startLocalServer(opts) {
             // finding; narrating only the one result the executor happened to carry
             // reported a single fact and discarded the rest, which is the visible
             // half of "research answers one question instead of telling a story".
-            const researchStory = !needsClarification && plan.steps.length > 0
+            const researchStory = !needsClarification && researchLedgerV2.entries.length > 0
                 ? synthesizeResearchNarrative({
                     question: request.question,
-                    branches: researchRuns.map((branch, index) => ({
-                        statement: plan.steps[index]?.thought ?? branch.question ?? '',
-                        produced: branch.status === 'ready'
-                            && (branch.resultPreview?.rows?.length ?? 0) > 0,
-                        ...(branch.summary ? { summary: branch.summary } : {}),
-                        ...(branch.status ? { status: branch.status } : {}),
+                    branches: researchLedgerV2.entries.map((entry) => ({
+                        statement: entry.hypothesis ?? entry.question,
+                        produced: entry.status === 'observed',
+                        verdict: entry.verdict,
+                        counterEvidenceFactIds: entry.counterEvidenceFactIds,
+                        ...(entry.error ? { summary: entry.error } : {}),
+                        status: entry.status,
                     })),
                 })
                 : undefined;
@@ -4521,8 +5095,11 @@ export async function startLocalServer(opts) {
                                         : plan.done
                                             ? 'Prepared a direct grounded-answer plan.'
                                             : 'Prepared a grounded research plan over real DQL assets.');
+            const scopedSummary = !needsClarification && researchLedgerV2.limitedScope
+                ? `Limited research scope: fewer than three groundable branches were available. ${summary}`
+                : summary;
             return {
-                summary,
+                summary: scopedSummary,
                 answer: plan.followUp?.question ?? narration?.summary
                     ?? (researchZeroRows ? 'The query executed cleanly and matched 0 rows.' : undefined)
                     ?? researchRun?.summary,
@@ -4533,7 +5110,9 @@ export async function startLocalServer(opts) {
                     ? []
                     : [agentRunArtifact('research_run', 'Research plan', {
                             plan,
+                            typedResearchPlan,
                             researchLedger,
+                            researchLedgerV2,
                             researchRun,
                             researchRuns,
                             researchRunId: researchRun?.id,
@@ -4562,6 +5141,9 @@ export async function startLocalServer(opts) {
                             ? 'The query executed cleanly against real data and matched 0 rows.'
                             : 'The query executed cleanly against real data and returned rows.')
                         : 'No executed result was available; the output stays exploratory pending review.', { rowCount: Array.isArray(researchResultRecord?.rows) ? researchResultRecord.rows.length : 0 }),
+                    agentRunEvaluation('research-scope', 'Research scope', !researchLedgerV2.limitedScope, researchLedgerV2.limitedScope ? 'warning' : 'info', researchLedgerV2.limitedScope
+                        ? `Limited research scope: ${researchLedgerV2.groundableBranchCount} of at least 3 branches produced groundable evidence.`
+                        : `${researchLedgerV2.groundableBranchCount} groundable branches were retained with verdicts and counter-evidence slots.`, { groundableBranchCount: researchLedgerV2.groundableBranchCount, limitedScope: researchLedgerV2.limitedScope }),
                 ],
                 nextActions: needsClarification
                     ? [{ id: 'answer-follow-up', label: 'Answer follow-up', route: 'research' }]
@@ -4999,7 +5581,74 @@ export async function startLocalServer(opts) {
             durationMs: Date.now() - startedAt,
             truncated: pack.retrievalDiagnostics.topRejected.length > 0,
         });
-        return applyContextPackCompatibility(evidence, pack, request.selectedEvidenceId);
+        // Preserve real snapshot/lane outcomes for the router receipt. These are
+        // not reconstructed later from candidate IDs: a source with no selected
+        // card can be empty, stale, errored, or intentionally skipped.
+        const sourceCoverage = [];
+        const fusionLanes = pack.retrievalDiagnostics.fusion?.lanes;
+        const retrievalLaneStates = Object.values(fusionLanes ?? {});
+        const retrievalErrored = retrievalLaneStates.length > 0
+            && retrievalLaneStates.every((item) => item.status === 'error');
+        const retrievalSkipped = retrievalLaneStates.length > 0
+            && retrievalLaneStates.every((item) => item.status === 'skipped');
+        const snapshotStale = /\bstale\b|out[- ]of[- ]date/i.test(pack.warnings.join(' '));
+        const coverageStatus = (hasCandidate) => {
+            if (snapshotStale)
+                return 'stale';
+            if (hasCandidate)
+                return 'available';
+            if (retrievalErrored)
+                return 'errored';
+            if (retrievalSkipped)
+                return 'skipped';
+            return 'empty';
+        };
+        const sourceDescriptors = [
+            { source: 'certified', matches: (candidate) => candidate.kind === 'certified_block' },
+            { source: 'semantic', matches: (candidate) => candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member' || candidate.trustTier === 'semantic' },
+            { source: 'governed_relational', matches: (candidate) => candidate.kind === 'dql_modeling' || (candidate.relationshipEvidence?.length ?? 0) > 0 },
+            { source: 'exploratory', matches: (candidate) => candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source' || candidate.kind === 'sql_table' || candidate.kind === 'sql_column' },
+            { source: 'dbt_manifest', matches: (candidate) => candidate.kind === 'dbt_model' || candidate.kind === 'dbt_source' },
+            { source: 'runtime_schema', matches: (candidate) => candidate.kind === 'sql_table' || candidate.kind === 'sql_column' },
+        ];
+        // `compatible` is declared immediately below. Build IDs from the adapter
+        // output first, then retain them unchanged through compatibility filtering.
+        const compatible = applyContextPackCompatibility(evidence, pack, request.selectedEvidenceId);
+        for (const descriptor of sourceDescriptors) {
+            const ids = compatible.candidates
+                .filter(descriptor.matches)
+                .map((candidate) => candidate.qualifiedId ?? candidate.id)
+                .slice(0, 32);
+            sourceCoverage.push({
+                version: 1,
+                source: descriptor.source,
+                status: coverageStatus(ids.length > 0),
+                candidateIds: ids,
+                ...(snapshotStale ? { reason: 'The snapshot freshness warning marked this source stale.' } : {}),
+            });
+        }
+        const lane = pack.retrievalDiagnostics.fusion?.lanes?.vector;
+        if (lane) {
+            sourceCoverage.push({
+                version: 1,
+                source: 'vector',
+                status: lane.status === 'ok' ? 'available' : lane.status === 'error' ? 'errored' : lane.status === 'empty' ? 'empty' : 'skipped',
+                candidateIds: [],
+                ...(lane.error ? { reason: lane.error } : lane.skippedReason ? { reason: lane.skippedReason } : {}),
+            });
+        }
+        const hasConversation = Boolean(request.conversationContext && Object.keys(request.conversationContext).length > 0);
+        sourceCoverage.push({
+            version: 1,
+            source: 'conversation',
+            status: hasConversation ? 'available' : 'skipped',
+            candidateIds: [],
+            reason: hasConversation ? 'Persisted conversation context was supplied for this turn.' : 'No persisted conversation context was supplied for this turn.',
+        });
+        return {
+            ...compatible,
+            diagnostics: { ...compatible.diagnostics, sourceCoverage },
+        };
     };
     const buildRankedAgentRunCatalogContext = async (request) => {
         const evidence = await buildAgentRunEvidence(request);
@@ -5368,6 +6017,16 @@ export async function startLocalServer(opts) {
             const semanticError = semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message;
             throw analyticalError(semanticError ?? `DQL artifact "${metadata.name ?? 'draft'}" produced no executable SQL.`, { origin: 'dql_compilation', stage: 'compile' });
         }
+        // A certified block is authored as DQL rather than warehouse-specific SQL.
+        // When its source uses an unqualified leaf relation, bind it only if the
+        // immutable context snapshot proves one unique physical relation.  Do not
+        // reuse broad exploratory repairs here: certified execution may not alter
+        // joins, aggregation, aliases, or any other frozen artifact semantics.
+        const compiledSql = semanticCompose?.sql ?? plan.sql;
+        const qualificationRepairs = [];
+        const executableSql = !semanticCompose?.sql && metadata.qualifiedSchemaContext?.length
+            ? qualifyUnambiguousSqlRelationsFromSchema(compiledSql, metadata.qualifiedSchemaContext, qualificationRepairs, activeConnection.driver)
+            : compiledSql;
         const app = loadRuntimeApp(projectRoot, activePersonaAppId());
         const sourceDomain = metadata.domain ?? source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1];
         assertAppAccess({ app, domain: sourceDomain ?? app?.domain, level: 'execute' });
@@ -5376,7 +6035,7 @@ export async function startLocalServer(opts) {
             : undefined;
         const semanticExecutionHolder = { value: null };
         const execution = await analyticalExecutionService.execute({
-            sql: semanticCompose?.sql ?? plan.sql,
+            sql: executableSql,
             subject: 'DQL artifact query',
             connection: activeConnection,
             // Preserve the existing contract: previewed Ask artifacts are explicitly
@@ -5421,7 +6080,7 @@ export async function startLocalServer(opts) {
                 path: metadata.path ?? null,
                 domain: sourceDomain ?? null,
             })),
-            compiledSqlFingerprint: executionFingerprint(semanticCompose?.sql ?? plan?.sql ?? preparation.sourceSql),
+            compiledSqlFingerprint: executionFingerprint(executableSql ?? preparation.sourceSql),
             normalizedSqlFingerprint: executionFingerprint(preparation.decodedSql),
             parameterFingerprint: executionReceipt.parameterFingerprint,
             provenanceFingerprint: executionFingerprint(stableExecutionValue(invocation.resolvedParameters.map((parameter) => ({
@@ -5431,7 +6090,7 @@ export async function startLocalServer(opts) {
             targetFingerprint: targetGenerationFingerprint(activeConnection, executionConnectionName),
             snapshotFingerprint: executionFingerprint(projectSnapshot().snapshotId),
             planFingerprint: executionFingerprint(stableExecutionValue({
-                sqlFingerprint: executionFingerprint(semanticCompose?.sql ?? plan?.sql ?? preparation.sourceSql),
+                sqlFingerprint: executionFingerprint(executableSql ?? preparation.sourceSql),
                 parameterCount: plan?.sqlParams?.length ?? 0,
                 variableNames: Object.keys(plan?.variables ?? {}).sort(),
                 chartConfig: plan?.chartConfig ?? null,
@@ -5463,7 +6122,7 @@ export async function startLocalServer(opts) {
             } : {}),
         };
     };
-    const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false, executionConnection, executionConnectionName) => {
+    const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false, executionConnection, executionConnectionName, qualifiedSchemaContext) => {
         const manifest = buildManifest({ projectRoot });
         const block = manifest.blocks[blockName];
         if (!block) {
@@ -5478,6 +6137,7 @@ export async function startLocalServer(opts) {
             path: block.filePath,
             domain: block.domain,
             chartType: block.chartType,
+            ...(qualifiedSchemaContext?.length ? { qualifiedSchemaContext } : {}),
         }, invocationInput, executionConnection, executionConnectionName);
         return {
             ...result,
@@ -5500,11 +6160,11 @@ export async function startLocalServer(opts) {
             },
         };
     };
-    const executeCertifiedBlockForAgent = async (node, invocationInput, executionConnection, executionConnectionName) => {
+    const executeCertifiedBlockForAgent = async (node, invocationInput, executionConnection, executionConnectionName, qualifiedSchemaContext, requireCertified = false) => {
         if (node.kind !== 'block') {
             throw new Error(`Certified ${node.kind} "${node.name}" is a navigation artifact and cannot be executed as a block.`);
         }
-        return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput, false, executionConnection, executionConnectionName);
+        return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput, requireCertified, executionConnection, executionConnectionName, qualifiedSchemaContext);
     };
     // Secondary agent surfaces use this compatibility callback. Delegate to the
     // same artifact-first path as Ask so research/app/notebook execution cannot
@@ -9638,7 +10298,7 @@ export async function startLocalServer(opts) {
                     // state wins; the client-built context stays the no-threadId fallback).
                     const conversationStore = parsed.request.threadId ? getConversationStore() : null;
                     if (conversationStore && parsed.request.threadId && conversationStore.getThread(parsed.request.threadId)) {
-                        parsed.request.conversationContext = await conversationContextFromThread(conversationStore, parsed.request.threadId, parsed.request.conversationContext, parsed.request.question);
+                        parsed.request.conversationContext = await conversationContextFromThread(conversationStore, parsed.request.threadId, parsed.request.conversationContext, parsed.request.question, Boolean(parsed.request.selectedEvidenceId));
                         // The persisted thread is authoritative for prior turns. Raw client
                         // history would duplicate the same conversation into the prompt a
                         // second time — dropping it keeps follow-up prompts bounded.
@@ -9646,10 +10306,13 @@ export async function startLocalServer(opts) {
                             parsed.request.history = [];
                     }
                     const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
-                    const runId = parsed.request.runId;
+                    // The public body may carry UI correlation data, but the run identity
+                    // is server-owned. Mint it before every controller/SSE/engine handoff
+                    // so no client-provided string can bind a SQL capability or operation.
+                    const runId = randomUUID();
+                    parsed.request.runId = runId;
                     const runController = new AbortController();
-                    if (runId)
-                        activeAgentRunControllers.set(runId, runController);
+                    activeAgentRunControllers.set(runId, runController);
                     let streamConnected = true;
                     res.on('close', () => { streamConnected = false; });
                     const writeStream = (event, data) => {
@@ -9670,13 +10333,13 @@ export async function startLocalServer(opts) {
                             'X-Accel-Buffering': 'no',
                         });
                     }
-                    const operation = runId ? operationCoordinator.create({
+                    const operation = operationCoordinator.create({
                         type: 'agent_run',
                         scope: `agent-run:${runId}`,
                         resourceRevision: parsed.request.threadId,
                         message: 'AI request accepted. You can change pages while it runs.',
                         cancellable: true,
-                    }) : null;
+                    });
                     if (wantsStream)
                         writeStream('agent-run-accepted', { runId, operationId: operation?.id });
                     let completedRun;
@@ -9768,8 +10431,7 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ run: slimAgentRunForTransport(completedRun) }));
                     }
                     finally {
-                        if (runId)
-                            activeAgentRunControllers.delete(runId);
+                        activeAgentRunControllers.delete(runId);
                     }
                 }
                 catch (error) {
@@ -18513,6 +19175,16 @@ export function resolveDefaultLLMProvider(projectRoot) {
  * answer envelope. Everything else uses the Settings-resolved default runner.
  */
 export function resolveGovernedAnswerRunner(projectRoot) {
+    // Runtime eval cassettes are an explicit, offline provider source. Resolve
+    // them before Settings because the CI fixture intentionally has no user
+    // provider configuration; otherwise Ask exits at this earlier gate and never
+    // reaches the cassette-wrapped provider used by the answer loop.
+    const cassetteProvider = createEvalCassetteReplayProvider(projectRoot);
+    if (cassetteProvider) {
+        const provider = governedRunnerProviderForCassette(cassetteProvider.name);
+        if (provider)
+            return { provider, runner: createDqlAgentProviderRunner(provider, cassetteProvider) };
+    }
     const active = getActiveProvider(projectRoot);
     if (isGovernedAnswerProviderId(active)) {
         return { provider: active, runner: createDqlAgentProviderRunner(active) };
@@ -18525,6 +19197,14 @@ export function resolveGovernedAnswerRunner(projectRoot) {
     }
     return null;
 }
+function governedRunnerProviderForCassette(name) {
+    switch (name) {
+        case 'claude': return 'anthropic';
+        case 'openai': return 'openai';
+        case 'gemini': return 'gemini';
+        case 'ollama': return 'ollama';
+    }
+}
 function isGovernedAnswerProviderId(value) {
     return value === 'anthropic'
         || value === 'openai'
@@ -22092,7 +22772,7 @@ export function buildAgentPreviewSql(sql, rowLimit = 200) {
  */
 export function repairExploratorySqlBeforeExecution(sql, schemaContext, question = '', dialect = 'duckdb') {
     const repairs = [];
-    let repairedSql = qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs, dialect);
+    let repairedSql = qualifyUnambiguousSqlRelationsFromSchema(sql, schemaContext, repairs, dialect);
     repairedSql = repairExploratoryRelationQualifiers(repairedSql, repairs, dialect);
     repairedSql = repairExploratoryLifetimeMeasureSelection(repairedSql, schemaContext, question, repairs, dialect);
     repairedSql = repairExploratoryMisleadingPercentAliases(repairedSql, question, repairs);
@@ -22151,7 +22831,13 @@ export function applyRequestedTopNToExploratorySql(sql, requestedTopN) {
     }
     return `${withoutTerminator}\nLIMIT ${requestedTopN}`;
 }
-function qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs, dialect = 'duckdb') {
+/**
+ * Bind an already-authored unqualified relation to a unique inspected physical
+ * relation.  The caller owns whether that binding is permitted (exploratory
+ * preflight or a frozen certified artifact); this helper itself never adds a
+ * relation, key, join, predicate, or column.
+ */
+export function qualifyUnambiguousSqlRelationsFromSchema(sql, schemaContext, repairs, dialect = 'duckdb') {
     const analysis = analyzeSqlReferences(sql, dialect);
     if (!analysis.parsed)
         return sql;
@@ -26290,6 +26976,14 @@ async function buildBlockStudioAiAssistSummary(projectRoot, action, candidate, v
     }
 }
 async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
+    // Runtime-driven evals intentionally start from a clean fixture with no user
+    // provider settings. When replay cassettes are explicitly enabled, their
+    // recorded identity is the authoritative provider and never performs network
+    // readiness checks. Normal product startup has no cassette env and follows
+    // the unchanged configured-provider path below.
+    const cassetteProvider = createEvalCassetteReplayProvider(projectRoot);
+    if (cassetteProvider)
+        return cassetteProvider;
     const settings = listProviderSettings(projectRoot);
     const activeProvider = getActiveProvider(projectRoot);
     // Subscription CLI providers (Claude Code / Codex) carry no API key — they're
@@ -26339,7 +27033,7 @@ async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
     // exactly the calls whose non-determinism it was recorded to remove. A local
     // baseline reproduced that: the same question blocked on one run and answered
     // on the next, and zero cassettes were written.
-    return await provider.available() ? applyEvalCassette(provider) : null;
+    return await provider.available() ? applyEvalCassette(provider, projectRoot) : null;
 }
 /** Convert a governed answer's result payload into a bounded synthesis preview. */
 function agentResultToSynthesisPreview(result) {
@@ -29966,7 +30660,7 @@ function compactSqlForRunHistory(sql) {
     const clean = sql.replace(/\s+/g, ' ').trim();
     return clean.length > 1200 ? `${clean.slice(0, 1197)}...` : clean;
 }
-function buildAgentSchemaContextFromContextPack(question, contextPack) {
+function buildAgentSchemaContextFromContextPack(question, contextPack, options = {}) {
     const byRelation = new Map();
     const objectsByKey = new Map(contextPack.objects.map((object) => [object.objectKey, object]));
     const upsert = (table) => {
@@ -30020,11 +30714,75 @@ function buildAgentSchemaContextFromContextPack(question, contextPack) {
         table,
         score: scoreAgentSchemaTable(table, tokens) + (shouldProbeValues ? scoreAgentValueProbeTable(table) : 0),
     }))
-        .filter((entry) => entry.table.columns.length > 0 && entry.score > 0)
+        .filter((entry) => entry.table.columns.length > 0 && (options.includeUnscored || entry.score > 0))
         .sort((a, b) => b.score - a.score || a.table.relation.localeCompare(b.table.relation))
-        .slice(0, 12)
+        .slice(0, Math.max(1, options.limit ?? 12))
         .map((entry) => entry.table);
 }
+/**
+ * Exact frozen certified execution needs the physical relation closure from
+ * the same source snapshot, not only the twelve tables that happened to rank
+ * for the natural-language prompt.  An artifact may project `category` while
+ * its authored SQL says `FROM order_items`, so prompt relevance alone is not
+ * a safe authority to remove that relation from the execution handoff.
+ *
+ * This remains deliberately narrower than an exploratory repair: it exposes
+ * only snapshot-indexed dbt models plus the already retrieved local objects.
+ * `qualifyUnambiguousSqlRelationsFromSchema` still changes a leaf only when
+ * exactly one physical relation in that closure owns it.  Duplicate leaves
+ * therefore remain a same-tier certified failure rather than a guessed bind.
+ */
+function buildFrozenCertifiedSchemaContext(contextPack, manifest) {
+    const byRelation = new Map();
+    const upsert = (table) => {
+        if (!table.relation || !table.name)
+            return;
+        const key = table.relation.toLowerCase();
+        const existing = byRelation.get(key);
+        if (!existing) {
+            byRelation.set(key, {
+                ...table,
+                columns: dedupeAgentSchemaColumns(table.columns).slice(0, 80),
+            });
+            return;
+        }
+        byRelation.set(key, {
+            ...existing,
+            description: existing.description ?? table.description,
+            source: existing.source === table.source ? existing.source : 'local metadata catalog',
+            columns: dedupeAgentSchemaColumns([...existing.columns, ...table.columns]).slice(0, 80),
+        });
+    };
+    if (contextPack) {
+        for (const object of contextPack.objects) {
+            const table = metadataObjectToAgentSchemaTable(object);
+            if (table)
+                upsert(table);
+        }
+    }
+    for (const model of manifest.dbtImport?.dbtDag?.models ?? []) {
+        const relation = [model.database, model.schema, model.name].filter(Boolean).join('.');
+        // A bare dbt identity does not prove a physical catalog/schema and must
+        // not be promoted into a qualifier. It remains harmless context only.
+        if (!relation || relation === model.name)
+            continue;
+        upsert({
+            relation,
+            schema: model.schema,
+            name: model.name,
+            description: model.description,
+            columns: (model.columns ?? []).map((column) => ({
+                name: column.name,
+                type: column.type,
+                description: column.description,
+            })),
+            source: 'local metadata catalog',
+        });
+    }
+    return Array.from(byRelation.values())
+        .filter((table) => table.columns.length > 0)
+        .sort((left, right) => left.relation.localeCompare(right.relation));
+}
 function metadataObjectToAgentSchemaTable(object) {
     if (object.objectType === 'dbt_column' || object.objectType === 'runtime_column') {
         const relation = metadataPayloadString(object, 'relation');