@duckcodeailabs/dql-cli 1.14.0 → 1.14.1

package/dist/local-runtime.js

@@ -23,9 +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 { createDqlAgentProviderRunner, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.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 { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { 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, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, assertProviderPayloadAllowed, createProviderDispatchEgressReceipt, prepareProviderWireEnvelopeForDispatch, markProviderMetadataArray, createProviderEgressReceipt, redactProviderResultRows, composeVerifiedAnalyticalNarrative, buildCoverageGap, capResearchBranches, buildResearchEvidenceLedger, buildAnalyticalTurnPlan, 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, buildCoverageGap, capResearchBranches, buildResearchEvidenceLedger, buildAnalyticalTurnPlan, 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';
@@ -328,6 +329,10 @@ const CLIENT_PLAN_AUTHORITY_KEYS = new Set([
     'priorResolvedAnalyticalPlan',
     'resolvedAnalyticalPlan',
     'analyticalFrame',
+    // Only the local compound executor may inject this after it has derived a
+    // canonical parent result binding. A browser-provided lookalike cannot become
+    // a child filter or skip ordinary member validation.
+    'analyticalTaskDependencyBinding',
 ]);
 /**
  * Browser/embedding context is useful retrieval and history input, but it is
@@ -378,6 +383,52 @@ export function agentRunDeadlineMs(request, env = process.env, activeProviderId)
         ? AGENT_RESEARCH_DEADLINE_MS
         : AGENT_LOOKUP_DEADLINE_MS;
 }
+/**
+ * Run ready independent compound clauses concurrently, but wait for a typed
+ * parent result before executing a declared dependent clause. The scheduler
+ * itself has no authority to query or filter; callers supply both execution and
+ * a dependency resolver so immutable-plan and SQL guards remain unchanged.
+ */
+export async function scheduleCompoundAnalyticalTasks(input) {
+    const pending = [...input.tasks];
+    const settled = new Map();
+    while (pending.length > 0) {
+        const ready = pending.filter((task) => task.dependencies.every((dependencyId) => settled.has(dependencyId)));
+        if (ready.length === 0) {
+            for (const task of pending.splice(0)) {
+                settled.set(task.id, {
+                    task,
+                    error: 'The compound task dependency graph could not be resolved.',
+                    dependencyError: {
+                        ok: false,
+                        code: 'RESULT_CONTRACT_MISMATCH',
+                        message: 'The dependent task could not run because its parent dependency was unresolved.',
+                    },
+                });
+            }
+            break;
+        }
+        for (const task of ready)
+            pending.splice(pending.indexOf(task), 1);
+        const batch = await Promise.all(ready.map(async (task) => {
+            if (!task.dependency || task.dependency.kind !== 'top_ranked_region')
+                return input.runTask(task);
+            const parent = settled.get(task.dependency.sourceTaskId);
+            const resolution = input.resolveDependency(task, parent);
+            if (!resolution.ok) {
+                const dependencyError = resolution;
+                return { task, error: dependencyError.message, dependencyError };
+            }
+            return input.runTask(task, resolution.binding);
+        }));
+        for (const result of batch)
+            settled.set(result.task.id, result);
+    }
+    return input.tasks.map((task) => settled.get(task.id) ?? {
+        task,
+        error: 'The compound task did not produce an outcome.',
+    });
+}
 /**
  * Decide how a settled answer gets its business-facing prose.
  *
@@ -420,11 +471,64 @@ export function shouldSynthesizeAgentRunAnswer(governedAnswer, requestedMode = '
         rowEgress: DEFAULT_ASK_ROW_EGRESS_POLICY,
     }).mode !== 'skip';
 }
+/**
+ * A receipt may be rendered in the local inspector and exported into evaluation
+ * output. Keep only stable validation codes there; provider error messages can
+ * contain a prompt excerpt, result value, or connector detail and must not
+ * become user-visible durable data.
+ */
+function narrationIntegrityFailureCodes(failures) {
+    return [...new Set(failures.map((failure) => {
+            const match = failure.trim().match(/^([A-Z][A-Z0-9_]{1,80})/);
+            return match?.[1] ?? 'NARRATION_VALIDATION_FAILED';
+        }).filter(Boolean))].slice(0, 8);
+}
 /**
  * AGT-010 — the semantic route label is descriptive, while the exact
  * route-specific aggregation proof is authoritative for governed trust.
  * Missing proof remains blocked for legacy or malformed results.
  */
+/**
+ * Trust for ONE answer, by the same rule the single-answer path uses: a route
+ * label is not authority, and a semantic route earns `governed` only when its
+ * aggregation proof actually passed.
+ */
+export function trustStateForAgentAnswer(answer) {
+    if (answer.certification === 'certified' || answer.kind === 'certified')
+        return 'certified';
+    return semanticAnswerHasPassedAggregationProof(answer) ? 'governed' : 'review_required';
+}
+const TRUST_RANK = {
+    certified: 3,
+    governed: 2,
+    grounded: 1,
+    review_required: 0,
+};
+/**
+ * A compound answer is exactly as trustworthy as its WEAKEST successful child.
+ *
+ * The previous rule was `every child completed ? 'governed' : 'review_required'`,
+ * which stamped `governed` on a parent whose children were review-required
+ * generated SQL — completion is not proof. That is a governance violation and
+ * the worst possible failure for this product: the reader is told a number
+ * carries governed authority when nothing proved it.
+ *
+ * `certified` is deliberately NOT reachable here. Certified trust is granted
+ * only by executing the exact certified artifact; a parent that merely
+ * assembled certified children did not execute one, so it caps at `governed`.
+ */
+export function compoundTrustState(childTrust) {
+    if (childTrust.length === 0)
+        return 'review_required';
+    const weakest = childTrust.reduce((low, current) => (TRUST_RANK[current] ?? 0) < (TRUST_RANK[low] ?? 0) ? current : low);
+    return weakest === 'certified' ? 'governed' : weakest;
+}
+/** Neutral parent outcome: governed only when every child completed governed. */
+export function compoundStopReason(completedCount, childCount, trustState) {
+    return completedCount === childCount && childCount > 0 && trustState === 'governed'
+        ? 'governed_compound_answer'
+        : 'human_review_required';
+}
 export function semanticAnswerHasPassedAggregationProof(governedAnswer) {
     return governedAnswer.route?.tier === 'semantic_metric'
         && governedAnswer.aggregationSafetyProof?.status === 'safe';
@@ -1039,6 +1143,7 @@ export function conversationTurnInputFromRun(run) {
         sql: agentRunString(payload?.proposedSql) ?? agentRunString(payload?.sql),
         dqlArtifact: agentRunRecord(payload?.dqlArtifact),
         cascade: agentRunRecord(payload?.cascade),
+        narrationIntegrityReceipt: run.narrationIntegrityReceipt,
         result: columns.length > 0 || rows.length > 0
             ? {
                 columns,
@@ -1166,12 +1271,7 @@ export class RunScopedProviderDispatchEvidence {
      * from what it already has.
      */
     expectedDispatchMs() {
-        if (this.observedDispatchDurations.length === 0)
-            return ASSUMED_PROVIDER_DISPATCH_MS;
-        const sorted = [...this.observedDispatchDurations].sort((left, right) => left - right);
-        // The slowest observed call is the honest predictor: an optimistic median
-        // still admits a dispatch that the deadline then kills.
-        return sorted[sorted.length - 1];
+        return predictDispatchMs(this.observedDispatchDurations);
     }
     /** True when the remaining wall clock cannot fit another provider call. */
     cannotFitAnotherDispatch() {
@@ -1364,6 +1464,50 @@ function mergeRunScopedProviderDispatchEvidence(run, evidence) {
         diagnosticReceiptV2,
     };
 }
+/**
+ * Final physical generated-SQL boundary.
+ *
+ * This receives the exact prepared statement immediately before the connector
+ * callback.  It intentionally validates before invoking `execute`: a bad
+ * capability or unproven prepared reference must result in zero warehouse
+ * calls, not a post-execution warning.  It is module-exported only for the
+ * local-runtime boundary harness; it is never an HTTP API or durable artifact.
+ *
+ * @internal
+ */
+export async function executePreparedAgenticSqlBoundary(input) {
+    const capability = input.capability;
+    if (capability) {
+        const authorization = mintFinalSqlAuthorization({
+            sql: input.preparedSql,
+            proven: capability.provenIdentifiers.map((identifier) => ({
+                identifier,
+                evidence: capability.evidence[identifier] ?? 'catalog',
+            })),
+            runId: capability.runId,
+            executionId: capability.executionId,
+            snapshotId: capability.snapshotId,
+            planId: capability.planId,
+            targetFingerprint: capability.targetFingerprint,
+            bindings: input.bindings,
+        });
+        const validation = validateAuthorizedSqlReferences(input.preparedSql, undefined);
+        const verdict = verifyFinalSql(authorization, input.preparedSql, qualifyAuthorizationReferences(input.preparedSql, {
+            relations: validation.referencedRelations ?? [],
+            columns: validation.referencedColumns ?? [],
+        }), {
+            ...input.scope,
+            bindings: input.bindings,
+        });
+        if (process.env.DQL_ORCHESTRATOR_TRACE) {
+            console.warn(`[dql] execution authorization: ${verdict.ok ? 'admitted' : 'REFUSED'} proven=${authorization.provenIdentifiers.length}${verdict.ok ? '' : ` reason=${verdict.reason}`}`);
+        }
+        if (!verdict.ok) {
+            throw analyticalError(verdict.reason ?? 'The statement was not authorized for execution.', { origin: 'governance_gate', stage: 'execute', code: 'unauthorized_sql' });
+        }
+    }
+    return input.execute();
+}
 export async function startLocalServer(opts) {
     const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
     const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
@@ -2061,6 +2205,9 @@ export async function startLocalServer(opts) {
         });
     };
     async function runGovernedAgentAnswerForRun(request, repair, route = 'generated_answer', onProgress, routeDecision) {
+        return runGovernedAgentAnswerForRunInner(request, repair, route, onProgress, routeDecision);
+    }
+    async function runGovernedAgentAnswerForRunInner(request, repair, route = 'generated_answer', onProgress, routeDecision) {
         const governed = resolveGovernedAnswerRunner(projectRoot);
         let resolvedProvider = governed?.provider ?? null;
         let runner = governed?.runner ?? null;
@@ -2163,6 +2310,9 @@ export async function startLocalServer(opts) {
                 snapshotId: runProjectSnapshot.snapshotId,
             })
             : undefined;
+        // 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();
         await runner.run({
             provider: resolvedProvider,
             ...(agentRunProviderEvidenceContext.getStore()
@@ -2187,9 +2337,13 @@ export async function startLocalServer(opts) {
             },
             reasoningEffort,
             ...(analysisDepth ? { analysisDepth } : {}),
+            orchestrationMode: route === 'research' ? 'research' : 'ask',
             allowProviderSemanticMemberSelection: route === 'research',
             researchResultRowsOptIn: route === 'research' && request.researchResultRowsOptIn === true,
             projectRoot,
+            // 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),
             domainContext,
             projectSnapshot: { snapshotId: runProjectSnapshot.snapshotId, manifest: runProjectSnapshot.manifest },
@@ -2357,6 +2511,20 @@ export async function startLocalServer(opts) {
             analyticalReferenceInstant: new Date().toISOString(),
             executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, semanticConnection, semanticConnectionName),
             executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact, semanticConnection, semanticConnectionName),
+            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.', {
+                        origin: 'governance_gate', stage: 'execute', code: 'unauthorized_sql',
+                    });
+                }
+                return executeGeneratedArtifactForAgent(request.question, sql, artifact, semanticConnection, semanticConnectionName, capability, {
+                    runId: request.runId,
+                    executionId: capability.executionId,
+                    snapshotId: runProjectSnapshot.snapshotId,
+                    planId: routeDecision?.resolvedAnalyticalPlan?.planId,
+                    targetFingerprint: generatedProposalTargetIdentity?.identityFingerprint,
+                });
+            },
             executeDqlArtifact: (artifact) => executeArtifactReferenceForAgent(artifact, request.question, semanticConnection, semanticConnectionName),
             getSchemaContext: (question, preparedContextPack) => getSchemaContextForAgent(question, preparedContextPack, semanticConnection, request.executionTarget?.target === 'connection'
                 ? request.executionTarget.connectionName
@@ -2629,6 +2797,7 @@ export async function startLocalServer(opts) {
         const runStartedAtMs = Date.now();
         const turnPlan = buildAnalyticalTurnPlan({
             question: request.question,
+            mode: route === 'research' ? 'research' : 'ask',
             turnId: request.runId,
             candidateIds: routeDecision?.retrievalEvidence?.candidateIds ?? [],
             frozen: routeDecision?.resolvedAnalyticalPlan?.mode === 'authoritative',
@@ -2641,18 +2810,27 @@ export async function startLocalServer(opts) {
         // is copied into several labels. Independent children share the parent's
         // signal/deadline and return truthful partial success.
         if (turnPlan.tasks.length > 1 && !childTurn && (attempt ?? 0) === 0) {
-            const childResults = await Promise.all(turnPlan.tasks.slice(0, 6).map(async (task) => {
+            const runChildTask = async (task, dependencyBinding) => {
                 if (request.signal?.aborted)
                     rethrowIfCancelled(request.signal.reason, request.signal);
                 try {
                     const childRequest = {
                         ...request,
                         question: task.question,
+                        ...(dependencyBinding ? {
+                            conversationContext: {
+                                ...(request.conversationContext ?? {}),
+                                // This is the complete parent-to-child data boundary: no
+                                // parent prose, SQL, or rows cross into a dependent clause.
+                                analyticalTaskDependencyBinding: dependencyBinding,
+                            },
+                        } : {}),
                         workspaceContext: {
                             ...(request.workspaceContext && typeof request.workspaceContext === 'object' ? request.workspaceContext : {}),
                             analyticalTaskChild: true,
                             analyticalParentRunId: request.runId,
                             analyticalTaskId: task.id,
+                            ...(dependencyBinding ? { analyticalTaskDependencyBinding: dependencyBinding } : {}),
                         },
                     };
                     const answer = await runGovernedAgentAnswerForRun(childRequest, { attempt: 0, repairHint }, route, (message) => emit({ type: 'executor.started', message: `Task ${task.id}: ${message}`, route }), undefined);
@@ -2679,6 +2857,42 @@ export async function startLocalServer(opts) {
                     rethrowIfCancelled(error, request.signal);
                     return { task, error: error instanceof Error ? error.message : String(error) };
                 }
+            };
+            const scheduledChildren = await scheduleCompoundAnalyticalTasks({
+                tasks: turnPlan.tasks.slice(0, 6),
+                runTask: async (task, binding) => {
+                    const child = await runChildTask(task, binding);
+                    return { task, value: child.answer, error: child.error };
+                },
+                resolveDependency: (task, parent) => {
+                    const sourceTaskId = task.dependency?.sourceTaskId ?? '';
+                    return resolveTopRankedRegionDependency(sourceTaskId, parent?.value?.result
+                        ? normalizeCanonicalQueryResult({
+                            ...parent.value.result,
+                            resultFingerprint: parent.value.result.resultFingerprint ?? parent.value.result.executionReceipt?.resultFingerprint,
+                            executionReceipt: parent.value.result.executionReceipt,
+                            answerTier: parent.value.route?.tier ?? parent.value.sourceTier,
+                        })
+                        : undefined, parent?.task);
+                },
+            });
+            const childResults = scheduledChildren.map(({ task, value, error, dependencyError }) => ({
+                task,
+                answer: value,
+                error,
+                ...(dependencyError ? {
+                    dependencyGap: buildCoverageGap({
+                        code: dependencyError.code,
+                        phase: 'planning',
+                        message: dependencyError.message,
+                        searchedSources: routeDecision?.retrievalEvidence?.candidateIds ?? [],
+                        attemptedRoutes: ['certified', 'semantic', 'governed_relational', 'generated'],
+                        missing: ['unambiguous_top_region'],
+                        recoverable: true,
+                        planFrozen: turnPlan.frozen,
+                        nextActions: ['Ask for a single top region or review the parent result before retrying the customer task.'],
+                    }),
+                } : {}),
             }));
             const outcomes = childResults.map(({ task, answer, error }) => ({
                 version: 1,
@@ -2687,7 +2901,7 @@ export async function startLocalServer(opts) {
                 ...(answer?.answer || answer?.text ? { summary: answer.answer ?? answer.text } : {}),
                 ...(answer?.result?.resultFingerprint ? { resultFingerprint: answer.result.resultFingerprint } : {}),
                 ...(error || answer?.kind === 'no_answer' ? {
-                    gap: buildCoverageGap({
+                    gap: childResults.find((candidate) => candidate.task.id === task.id)?.dependencyGap ?? buildCoverageGap({
                         code: answer?.refusalCode === 'ambiguous' ? 'AMBIGUOUS_MEANING' : 'EXECUTION_FAILED',
                         phase: answer?.executionError ? 'execution' : 'meaning',
                         message: error ?? answer?.answer ?? answer?.text ?? 'The task did not produce an accepted analytical result.',
@@ -2706,14 +2920,23 @@ export async function startLocalServer(opts) {
                 status: outcomes.find((outcome) => outcome.taskId === task.id)?.status === 'completed' ? 'completed' : 'gap',
             }));
             const answerText = childResults.map(({ task, answer, error }) => `${task.question}: ${error ?? answer?.answer ?? answer?.text ?? 'No accepted result was produced.'}`).join('\n\n');
+            const compoundTrust = compoundTrustState(childResults
+                .filter(({ answer, error }) => !error && answer && answer.kind !== 'no_answer')
+                .map(({ answer }) => trustStateForAgentAnswer(answer)));
             return {
                 summary: completedCount === outcomes.length
-                    ? `Answered ${completedCount} independent analytical clauses.`
+                    ? `Answered ${completedCount} analytical clauses.`
                     : `Answered ${completedCount} of ${outcomes.length} analytical clauses; the remaining clauses need review.`,
                 answer: answerText,
                 status: completedCount === outcomes.length ? 'completed' : completedCount > 0 ? 'needs_review' : 'needs_clarification',
-                trustState: completedCount === outcomes.length ? 'governed' : 'review_required',
-                stopReason: completedCount === outcomes.length ? 'governed_semantic_answer' : 'human_review_required',
+                // The parent is only as trustworthy as its weakest SUCCESSFUL child.
+                // Completion is not proof: the previous rule stamped `governed` on a
+                // parent assembled from review-required generated SQL.
+                trustState: compoundTrust,
+                // The stop reason has to agree with the trust it reports. Claiming a
+                // governed semantic answer over generated/certified children
+                // misrepresents provenance as much as the trust label does.
+                stopReason: compoundStopReason(completedCount, outcomes.length, compoundTrust),
                 artifacts: childResults.map(({ task, answer, error }) => agentRunArtifact('answer', `Task: ${task.question}`, {
                     taskId: task.id,
                     question: task.question,
@@ -3062,7 +3285,34 @@ export async function startLocalServer(opts) {
             ? { ...preview, rows: redactProviderResultRows(preview.rows, narrationMaxRows) }
             : undefined;
         let narrationSource;
-        let narrationValidationFailures = [];
+        // The receipt is the durable source of truth for evaluation and inspector
+        // display. Do not reconstruct this later from rows or the reader-facing
+        // fallback sentence: both are presentation artifacts, not evidence that a
+        // fact-grounded narrator actually ran.
+        const verifiedFactNarration = narrationPlan.mode === 'verified_facts'
+            && Boolean(governedAnswer.analyticalFacts && governedAnswer.resolvedAnalyticalPlan?.analyticalFrame);
+        let narrationIntegrityReceipt = narrationPlan.mode === 'skip'
+            ? {
+                version: 1,
+                mode: 'skip',
+                outcome: 'skipped',
+                attempted: false,
+                factCount: 0,
+                maxRows: 0,
+                validationFailures: [],
+                skipReason: narrationPlan.reason,
+            }
+            : {
+                version: 1,
+                mode: verifiedFactNarration ? 'verified_facts' : 'preview_grounded',
+                // This is deliberately pessimistic until a narration outcome is
+                // observed, so an exception cannot be persisted as a silent skip.
+                outcome: 'error',
+                attempted: true,
+                factCount: verifiedFactNarration ? governedAnswer.analyticalFacts?.facts.length ?? 0 : 0,
+                maxRows: narrationPlan.maxRows,
+                validationFailures: [],
+            };
         if (narrationPlan.mode !== 'skip' && narrationProvider) {
             const narrationStartedAtMs = Date.now();
             const draft = governedAnswer.answer ?? governedAnswer.text;
@@ -3075,8 +3325,16 @@ export async function startLocalServer(opts) {
                     columnCount: providerPreview?.columns.length ?? 0,
                 },
             });
-            const narrationDispatchOptions = () => ({
-                maxTokens: 350,
+            const narrationDispatchOptions = (factCount = 0) => ({
+                // The ceiling has to grow with the result. Every claim must echo the
+                // fact ids it rests on, and a fact id is a long hex string that
+                // tokenizes badly — ten of them consume most of the budget before a
+                // word of prose is written. At a flat 350 a ten-row answer was
+                // truncated mid-sentence ("...Elizabeth Shea (875), and Dyl"), so the
+                // JSON never closed, BOTH attempts failed as UNPARSEABLE_CLAIMS, and
+                // the reader got "Verified narration was unavailable" above a robot
+                // dump of the very rows the model had just described correctly.
+                maxTokens: narrationMaxTokensForFacts(factCount),
                 temperature: 0.3,
                 maxProviderDispatches: 2,
                 ...(agentRunProviderEvidenceContext.getStore()
@@ -3093,10 +3351,19 @@ export async function startLocalServer(opts) {
                         factSet: governedAnswer.analyticalFacts,
                         question: request.question,
                         maxRows: narrationPlan.maxRows,
-                        complete: async ({ system, user }) => streamOrGenerate(narrationProvider, [{ role: 'system', content: system }, { role: 'user', content: user }], narrationDispatchOptions(), () => { }),
+                        complete: async ({ system, user }) => streamOrGenerate(narrationProvider, [{ role: 'system', content: system }, { role: 'user', content: user }], narrationDispatchOptions(governedAnswer.analyticalFacts?.facts.length ?? 0), () => { }),
                     });
                     narrationSource = composed.source;
-                    narrationValidationFailures = composed.validationFailures;
+                    narrationIntegrityReceipt = {
+                        ...narrationIntegrityReceipt,
+                        outcome: composed.source === 'llm' ? 'success' : 'deterministic_fallback',
+                        validationFailures: narrationIntegrityFailureCodes(composed.validationFailures),
+                    };
+                    if (process.env.DQL_ORCHESTRATOR_TRACE) {
+                        console.warn(`[dql] narration: source=${composed.source}${narrationIntegrityReceipt.validationFailures.length > 0
+                            ? ` rejected=${narrationIntegrityReceipt.validationFailures.join(',')}`
+                            : ''}`);
+                    }
                     synthesizedAnswer = composed.source === 'llm'
                         ? composed.narrative.text
                         // A verification failure is not silent: the deterministic join is a
@@ -3126,11 +3393,22 @@ export async function startLocalServer(opts) {
                     narrationSource = result.source;
                     if (result.text)
                         synthesizedAnswer = result.text;
+                    narrationIntegrityReceipt = {
+                        ...narrationIntegrityReceipt,
+                        outcome: result.source === 'llm' ? 'success' : 'deterministic_fallback',
+                        validationFailures: [],
+                    };
                 }
             }
             catch {
                 // Keep the governed draft on any narration failure.
                 synthesizedAnswer = undefined;
+                narrationIntegrityReceipt = {
+                    ...narrationIntegrityReceipt,
+                    outcome: 'error',
+                    validationFailures: [],
+                    errorCode: 'narration_error',
+                };
             }
             finally {
                 narrationDurationMs = Date.now() - narrationStartedAtMs;
@@ -3270,7 +3548,11 @@ export async function startLocalServer(opts) {
             trustState,
             stopReason,
             artifacts: isTerminalFailure
-                ? [agentRunArtifact('answer', 'Failed governed analytical run', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, 'blocked')]
+                ? [agentRunArtifact('answer', 
+                    // Was 'Failed governed analytical run' — internal orchestration state
+                    // used as the card heading a user reads. It names our pipeline, not
+                    // what happened to their question.
+                    terminalFailureTitle(governedAnswer), governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, 'blocked')]
                 : governedAnswer.kind === 'no_answer'
                     // A refusal still keeps the DQL draft the answer loop produced (when any),
                     // so the "Review DQL draft" next-action isn't a dead link and the user can
@@ -3367,20 +3649,38 @@ export async function startLocalServer(opts) {
                 ...(governedAnswer.executionError ? [
                     agentRunEvaluation('execution-error', 'Execution error', false, 'warning', governedAnswer.executionError),
                 ] : []),
-                // A rejected narration must say WHY it was rejected. The failures were
-                // computed and then dropped, so a reader saw "Verified narration was
-                // unavailable" with no way to tell whether the model invented a number,
-                // cited a fact id that does not exist, or the provider simply failed.
-                // The fallback itself stays: this only makes its reason inspectable.
-                ...(narrationSource === 'deterministic' && narrationValidationFailures.length > 0 ? [
-                    agentRunEvaluation('narration-verification', 'Narration verification', false, 'warning', `The drafted narration was rejected against the result fact set, so the deterministic record was shown instead: ${narrationValidationFailures.join('; ')}`, { narrationSource, validationFailures: narrationValidationFailures }),
+                // Keep only the content-free receipt codes in the durable inspection
+                // record. Raw verifier prose can contain a result value, prompt excerpt,
+                // or provider error and is not safe evidence to surface or persist.
+                ...(narrationIntegrityReceipt.outcome === 'deterministic_fallback'
+                    && narrationIntegrityReceipt.validationFailures.length > 0 ? [
+                    agentRunEvaluation('narration-verification', 'Narration verification', false, 'warning', `The drafted narration was rejected against the result fact set, so the deterministic record was shown instead: ${narrationIntegrityReceipt.validationFailures.join(', ')}.`, { narrationSource, validationFailures: narrationIntegrityReceipt.validationFailures }),
                 ] : []),
             ],
             nextActions,
             providerEgressReceipts: finalProviderEgressReceipts,
             telemetry: finalTelemetry,
+            narrationIntegrityReceipt,
         };
     };
+    /**
+     * A heading for a run that ended without an answer, in the user's terms.
+     *
+     * Says WHICH stage stopped, because "it failed" and "it was stopped before
+     * running" call for different next moves: one is worth retrying, the other
+     * needs the question or the model changed.
+     */
+    const terminalFailureTitle = (answer) => {
+        switch (answer.refusalCode) {
+            case 'policy_blocked': return 'Blocked by a governance policy';
+            case 'modeling_gap': return 'Not modeled yet';
+            case 'grounding_gap': return 'Not enough context to answer safely';
+            case 'model_declined': return 'The assistant declined to answer';
+            case 'provider_error': return 'The AI provider did not respond';
+            case 'ambiguous': return 'Needs one detail before running';
+            default: return 'No answer was produced';
+        }
+    };
     const conversationRunExecutor = async ({ request, routeDecision, emitAnswerDelta }) => {
         const kind = routeDecision?.conversationalKind ?? 'smalltalk';
         const isGeneralKnowledge = routeDecision?.category === 'general_knowledge';
@@ -3397,6 +3697,15 @@ export async function startLocalServer(opts) {
         let text = kind === 'answer_explanation'
             ? buildPriorAnswerExplanation(request.question, request.conversationContext)
             : undefined;
+        // A definitional question that NAMES a governed artifact is answerable from
+        // the catalog: the description, domain, and dimensions are already recorded.
+        // Reaching for a provider to paraphrase facts we hold can only add drift, and
+        // the generic conversational reply this replaces used none of them.
+        //
+        // Returns undefined unless the question names something real, so a turn that
+        // does not match keeps today's behaviour exactly.
+        if (!text)
+            text = buildGovernedObjectExplanation(request.question);
         if (text) {
             emitAnswerDelta?.(text);
         }
@@ -3863,10 +4172,18 @@ export async function startLocalServer(opts) {
             const conversationHistory = request.history?.length
                 ? request.history
                 : conversationHistoryFromContext(request.conversationContext);
+            // The provider that will plan the investigation as hypotheses. Absent or
+            // unreachable, `planResearch` keeps its deterministic template, so
+            // research never depends on a model being available.
+            const researchPlanner = resolveGovernedAnswerRunner(projectRoot);
+            const researchPlannerProvider = researchPlanner
+                ? createGovernedTextProvider(researchPlanner.provider, projectRoot)
+                : undefined;
             const plan = await planResearch({
                 question: request.question,
                 metrics,
                 blocks,
+                ...(researchPlannerProvider ? { provider: researchPlannerProvider } : {}),
                 intent: request.intent,
                 isFollowUp: conversationHistory.length > 0,
                 history: conversationHistory,
@@ -3949,10 +4266,32 @@ 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);
+                        // 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
+                        // frozen before any observation. `nextHypothesis` returning
+                        // undefined is how the loop learns to stop — it enforces the hop
+                        // budget and reports when nothing is open.
+                        let researchState = createResearchState(request.question, branches.map((branch, position) => ({
+                            id: `h${position + 1}`,
+                            statement: branch.thought,
+                            priorConfidence: 1 - position / (branches.length + 1),
+                        })));
                         for (let index = 0; index < branches.length; index += 1) {
                             const step = branches[index];
                             if (request.signal?.aborted)
                                 rethrowIfCancelled(request.signal.reason, request.signal);
+                            // A hypothesis an earlier finding already closed is not
+                            // re-investigated, and an exhausted hop budget stops the run.
+                            const stillOpen = nextHypothesis(researchState);
+                            if (!stillOpen) {
+                                emit({
+                                    type: 'executor.started',
+                                    message: `Stopping early: ${researchState.hopsUsed} of ${branches.length} branches settled what could be settled.`,
+                                    route: 'research',
+                                });
+                                break;
+                            }
                             const branchId = `${step.action.kind}:${step.action.target}`;
                             const branchQuestion = `${request.question}\nResearch branch ${index + 1} (${branchId}): ${step.expectation}`;
                             const childId = `${created.id}:research:${index + 1}`;
@@ -4007,7 +4346,27 @@ export async function startLocalServer(opts) {
                                     baselineDqlArtifact: researchSource?.dqlArtifact,
                                     baselineRunId: agentRunString(researchSource?.runId),
                                 });
-                                researchRuns.push(withNotebookResearchChecklist(executed));
+                                const branchRun = withNotebookResearchChecklist(executed);
+                                researchRuns.push(branchRun);
+                                // Observe, then decide. A branch that produced rows is evidence
+                                // for its hypothesis; one that did not is inconclusive, which is
+                                // a real outcome and not a failure.
+                                // Rows are not support. A branch that returned data has been
+                                // OBSERVED, not confirmed — deciding whether the observation
+                                // matches what the hypothesis predicted needs the expectation,
+                                // and nothing available at this layer can judge it. Recording
+                                // rows as `supports` would let the dossier report a driver the
+                                // evidence never established, which is the failure mode the
+                                // whole verified-fact chain exists to prevent.
+                                researchState = applyFinding(researchState, {
+                                    id: `f${index + 1}`,
+                                    hypothesisId: `h${index + 1}`,
+                                    verdict: 'inconclusive',
+                                    summary: branchRun.summary ?? '',
+                                    strength: (branchRun.resultPreview?.rows?.length ?? 0) > 0
+                                        ? 0.5
+                                        : 0.1,
+                                });
                             }
                             catch (error) {
                                 // A child is a real durable run even when cancellation stops the
@@ -4023,6 +4382,13 @@ export async function startLocalServer(opts) {
                                 const stopped = storage.getRun(child.id);
                                 if (stopped)
                                     researchRuns.push(withNotebookResearchChecklist(stopped));
+                                researchState = applyFinding(researchState, {
+                                    id: `f${index + 1}`,
+                                    hypothesisId: `h${index + 1}`,
+                                    verdict: 'inconclusive',
+                                    summary: message,
+                                    strength: 0,
+                                });
                                 rethrowIfCancelled(error, request.signal);
                             }
                         }
@@ -4121,20 +4487,40 @@ export async function startLocalServer(opts) {
                     reviewRequired: true,
                 }, request.researchResultRowsOptIn === true)
                 : undefined;
+            // The cross-branch story. Every branch tested a hypothesis and produced a
+            // 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
+                ? 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 } : {}),
+                    })),
+                })
+                : undefined;
             const summary = needsClarification
                 ? 'Needs clarification before running deeper research.'
-                : narration?.summary
-                    ?? (researchZeroRows
-                        ? 'The query executed cleanly against real data and matched 0 rows.'
-                        : researchRun?.status === 'ready'
-                            ? 'Saved a grounded research dossier with context evidence and next review actions.'
-                            : researchRun?.status === 'error'
-                                ? 'Saved a research dossier, but the preview needs review before promotion.'
-                                : researchWorkspaceError
-                                    ? 'Prepared a grounded research plan; durable research storage is unavailable in this runtime.'
-                                    : plan.done
-                                        ? 'Prepared a direct grounded-answer plan.'
-                                        : 'Prepared a grounded research plan over real DQL assets.');
+                // The story leads; the verified-fact narration follows it, so the
+                // numbers still come from the narrator that checks them.
+                : researchStory
+                    ? `${researchStory}${narration?.summary ? `\n\n${narration.summary}` : ''}`
+                    : narration?.summary
+                        ?? (researchZeroRows
+                            ? 'The query executed cleanly against real data and matched 0 rows.'
+                            : researchRun?.status === 'ready'
+                                ? 'Saved a grounded research dossier with context evidence and next review actions.'
+                                : researchRun?.status === 'error'
+                                    ? 'Saved a research dossier, but the preview needs review before promotion.'
+                                    : researchWorkspaceError
+                                        ? 'Prepared a grounded research plan; durable research storage is unavailable in this runtime.'
+                                        : plan.done
+                                            ? 'Prepared a direct grounded-answer plan.'
+                                            : 'Prepared a grounded research plan over real DQL assets.');
             return {
                 summary,
                 answer: plan.followUp?.question ?? narration?.summary
@@ -4482,6 +4868,22 @@ export async function startLocalServer(opts) {
     // lookup, and governed execution for the lifetime of a request. This removes
     // both positional catalog truncation and the previous duplicate retrieval pass.
     const preparedAgentContextPacks = new WeakMap();
+    /**
+     * Cross-encoder pass over the fused candidates, when a provider is available.
+     * Advisory throughout: it may only reorder ids retrieval returned, and any
+     * failure leaves retrieval's own ordering in place.
+     */
+    const agentRerankCandidates = (() => {
+        const governed = resolveGovernedAnswerRunner(projectRoot);
+        const provider = governed
+            ? createGovernedTextProvider(governed.provider, projectRoot)
+            : undefined;
+        if (!provider)
+            return undefined;
+        return (question, candidates) => rerankCandidates(provider, question, candidates, {
+            timeoutMs: Math.round(2_500 * deadlineScale()),
+        });
+    })();
     const pendingAgentContextPacks = new WeakMap();
     const buildAgentRunContextPack = async (request) => {
         const prepared = preparedAgentContextPacks.get(request);
@@ -4549,6 +4951,10 @@ export async function startLocalServer(opts) {
             },
             strictness: request.analysisDepth === 'deep' ? 'exploratory' : 'balanced',
             limit: request.analysisDepth === 'deep' ? 120 : 80,
+            // The runtime PRE-BUILDS this pack, so wiring the reranker only at the
+            // provider's own `buildLocalContextPack` left it unreachable on the
+            // common path — the prepared pack is used and that call never happens.
+            ...(agentRerankCandidates ? { rerankCandidates: agentRerankCandidates } : {}),
             domainContext: requestedDomain
                 ? resolveUiDomainContext({
                     manifest: snapshot.manifest,
@@ -4604,6 +5010,56 @@ export async function startLocalServer(opts) {
     };
     // Compact fallback used only for plain conversational replies. Analytical
     // turns use the structured, question-ranked evidence path above.
+    /**
+     * Explain a governed artifact the question names, from catalog metadata alone.
+     *
+     * Certified blocks are offered first: when a concept exists both as a
+     * certified block and a raw model, the certified one is the authored
+     * definition and the other is an implementation detail.
+     */
+    const buildGovernedObjectExplanation = (question) => {
+        try {
+            const blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+            const certifiedNames = new Set(blocks.map((block) => block.name));
+            const all = [
+                ...blocks.map((block) => ({ block, status: 'certified' })),
+                ...collectPlanBlocks(projectRoot, { certifiedOnly: false })
+                    .filter((block) => !certifiedNames.has(block.name))
+                    .map((block) => ({ block, status: 'draft' })),
+            ];
+            // Metrics as well as blocks. "How is revenue defined here?" names a
+            // semantic metric, not a block, and answering it from the metric's own
+            // description is the whole point of holding one.
+            const metricObjects = loadSemanticMetrics(projectRoot).map((metric) => ({
+                objectKey: `semantic:metric:${metric.name}`,
+                objectType: 'semantic_metric',
+                name: metric.name,
+                ...(metric.description ? { description: metric.description } : {}),
+                ...(metric.domain ? { domain: metric.domain } : {}),
+                status: 'governed',
+                payload: {},
+            }));
+            const explanation = composeBusinessExplanation(question, [
+                ...all.map(({ block, status }) => ({
+                    objectKey: `dql:block:${block.name}`,
+                    objectType: 'dql_block',
+                    name: block.name,
+                    ...(block.description ? { description: block.description } : {}),
+                    ...(block.domain ? { domain: block.domain } : {}),
+                    status,
+                    payload: {
+                        ...(block.dimensions?.length ? { dimensions: block.dimensions } : {}),
+                    },
+                })),
+                ...metricObjects,
+            ]);
+            return explanation?.text;
+        }
+        catch {
+            // Never let an explanation attempt break a conversational turn.
+            return undefined;
+        }
+    };
     const buildAgentRunCatalogContext = () => {
         try {
             const blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
@@ -5155,12 +5611,43 @@ export async function startLocalServer(opts) {
      * string, so the only remaining reasons to differ are the connection and the
      * governance gates, both of which report themselves honestly.
      */
-    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection, bindings, executionConnectionName) => {
+    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection, bindings, executionConnectionName, agenticCapability, agenticScope) => {
         const activeConnection = requireActiveConnection(executionConnection);
         const rowBound = clampAnalyticalRowBound(seed?.limit ?? 200);
         const trimmed = sql.trim().replace(/;\s*$/, '').trim();
         if (!trimmed)
             throw analyticalError('The generated SQL was empty.', { origin: 'host', stage: 'execute' });
+        const bindingValue = {
+            sqlParams: bindings?.sqlParams ?? [],
+            variables: bindings?.variables ?? {},
+        };
+        if (agenticCapability) {
+            // The proposal itself is immutable. A changed literal, comment, or
+            // whitespace is drift here rather than a benign formatting change.
+            const currentSnapshotId = projectSnapshot().snapshotId;
+            let targetFingerprint;
+            if (agenticCapability.targetFingerprint) {
+                try {
+                    targetFingerprint = (await observeWarehouseTargetIdentity(executor, activeConnection)).identityFingerprint;
+                }
+                catch {
+                    throw analyticalError('DQL could not re-confirm the selected execution target, so the analyst-approved query was not run.', {
+                        origin: 'governance_gate', stage: 'execute', code: 'unauthorized_sql',
+                    });
+                }
+            }
+            const capabilityVerdict = verifyAgenticSqlExecutionCapability(agenticCapability, sql, {
+                ...agenticScope,
+                bindings: bindingValue,
+                snapshotId: currentSnapshotId,
+                ...(targetFingerprint ? { targetFingerprint } : {}),
+            });
+            if (!capabilityVerdict.ok) {
+                throw analyticalError(capabilityVerdict.reason ?? 'The analyst-approved SQL no longer matches this execution.', {
+                    origin: 'governance_gate', stage: 'execute', code: 'unauthorized_sql',
+                });
+            }
+        }
         // RESOLVE FIRST, VALIDATE SECOND. Executing verbatim means executing the
         // statement the notebook would execute — and the notebook resolves
         // `@metric()` / `@dim()` refs and dbt macros before it runs anything.
@@ -5185,8 +5672,6 @@ export async function startLocalServer(opts) {
         // release denied; a governance boundary must not move as a side effect.
         const sourceDomain = seed?.source?.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1] ?? 'uncategorized';
         assertAppAccess({ app, domain: sourceDomain, level: 'execute' });
-        // A semantic query the loop already compiled (MetricFlow / dbt Cloud) must
-        // execute through its pinned target binding, not as loose SQL.
         const semanticExecutionHolder = { value: null };
         const execution = await analyticalExecutionService.execute({
             sql: semantic.sql,
@@ -5198,27 +5683,46 @@ export async function startLocalServer(opts) {
             variables: bindings?.variables,
             semanticRefs: semantic.semanticRefs,
             executePrepared: async (preparation) => {
-                const pinnedSemanticCompile = compiledSemanticQueries.get(executionFingerprint(preparation.preparedSql))
-                    ?? compiledSemanticQueries.get(executionFingerprint(trimmed));
-                if (pinnedSemanticCompile) {
-                    const semanticExecution = await executeTargetBoundSemanticQuery({
-                        executor,
-                        connection: activeConnection,
-                        projectRoot,
-                        plannedAdapter: pinnedSemanticCompile.engine,
-                        metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
-                            ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
-                            : undefined,
-                        compile: async () => pinnedSemanticCompile,
-                        prepareSql: () => ({ sql: preparation.executedSql, connection: preparation.connection }),
-                        rowBound,
-                    });
-                    if (semanticExecution) {
-                        semanticExecutionHolder.value = semanticExecution;
-                        return semanticExecution.result;
+                // Both the native executor and the target-bound semantic adapter can
+                // reach the warehouse from this callback. Admit the exact prepared
+                // bytes before either path so a matching cached semantic compile cannot
+                // bypass the generated proposal's capability.
+                return executePreparedAgenticSqlBoundary({
+                    capability: agenticCapability,
+                    preparedSql: preparation.executedSql,
+                    bindings: bindingValue,
+                    scope: {
+                        ...agenticScope,
+                        snapshotId: projectSnapshot().snapshotId,
+                        ...(agenticCapability ? { targetFingerprint: agenticCapability.targetFingerprint } : {}),
+                    },
+                    execute: async () => {
+                        // A semantic query the loop already compiled (MetricFlow / dbt
+                        // Cloud) must execute through its pinned target binding, not as
+                        // loose SQL.
+                        const pinnedSemanticCompile = compiledSemanticQueries.get(executionFingerprint(preparation.preparedSql))
+                            ?? compiledSemanticQueries.get(executionFingerprint(trimmed));
+                        if (pinnedSemanticCompile) {
+                            const semanticExecution = await executeTargetBoundSemanticQuery({
+                                executor,
+                                connection: activeConnection,
+                                projectRoot,
+                                plannedAdapter: pinnedSemanticCompile.engine,
+                                metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
+                                    ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                                    : undefined,
+                                compile: async () => pinnedSemanticCompile,
+                                prepareSql: () => ({ sql: preparation.executedSql, connection: preparation.connection }),
+                                rowBound,
+                            });
+                            if (semanticExecution) {
+                                semanticExecutionHolder.value = semanticExecution;
+                                return semanticExecution.result;
+                            }
+                        }
+                        return executor.executeQuery(preparation.executedSql, bindings?.sqlParams ?? [], runtimeVariables(bindings?.variables ?? {}), preparation.connection);
                     }
-                }
-                return executor.executeQuery(preparation.executedSql, bindings?.sqlParams ?? [], runtimeVariables(bindings?.variables ?? {}), preparation.connection);
+                });
             },
         });
         const semanticExecution = semanticExecutionHolder.value;
@@ -5276,14 +5780,19 @@ export async function startLocalServer(opts) {
             executableArtifact,
         };
     };
-    const executeGeneratedArtifactForAgent = async (question, sql, seed, executionConnection, executionConnectionName) => {
+    const executeGeneratedArtifactForAgent = async (question, sql, seed, executionConnection, executionConnectionName, agenticCapability, agenticScope) => {
         // A seed that is already a certified/saved artifact keeps the DQL-first
         // path: there the `.dql` source IS the contract, and its parameters and
         // semantic refs must be compiled, not bypassed.
         if (seed && seed.kind !== 'sql_block') {
+            if (agenticCapability) {
+                throw analyticalError('The analyst-approved SQL cannot be redirected through a saved artifact.', {
+                    origin: 'governance_gate', stage: 'execute', code: 'unauthorized_sql',
+                });
+            }
             return executeArtifactReferenceForAgent({ ...seed, limit: seed.limit ?? 200 }, question, executionConnection, executionConnectionName);
         }
-        return executeGeneratedSqlDirect(question, sql, seed, executionConnection, undefined, executionConnectionName);
+        return executeGeneratedSqlDirect(question, sql, seed, executionConnection, undefined, executionConnectionName, agenticCapability, agenticScope);
     };
     /**
      * EXP-001: execution host for the deliberately narrow non-governed lane.
@@ -5891,7 +6400,10 @@ export async function startLocalServer(opts) {
         let invocation;
         let plan;
         try {
-            const program = new Parser(repairedSource, '<bounded-dql-repair>').parse();
+            // The source label is echoed into parse errors, which reach the user.
+            // `<bounded-dql-repair>` is an internal artifact id and tells them nothing;
+            // it appeared verbatim in a reported failure card.
+            const program = new Parser(repairedSource, 'repaired query').parse();
             const blocks = program.statements.filter((statement) => statement.kind === NodeKind.BlockDecl);
             if (blocks.length !== 1 || program.statements.length !== 1) {
                 throw new Error('The repaired source must contain exactly one DQL block.');
@@ -25821,7 +26333,13 @@ async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
         default:
             return null;
     }
-    return await provider.available() ? provider : null;
+    // Route through the eval cassette too. This constructor serves the MEANING
+    // call and narration — the two dispatches that decide routing and wording —
+    // so leaving it unwrapped meant a recorded suite still hit a live model for
+    // 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;
 }
 /** Convert a governed answer's result payload into a bounded synthesis preview. */
 function agentResultToSynthesisPreview(result) {
@@ -28658,7 +29176,45 @@ async function buildAgentSchemaContextFromCatalog(projectRoot, question, prepare
 const RUNTIME_SNAPSHOT_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
 // A resolver compares at most 12 compact cards and never performs tool calls;
 // ten seconds is the full allowance, not the start of another planning loop.
-const AGENT_MEANING_TIMEOUT_MS = 10_000;
+/**
+ * Ceiling on the one bounded meaning-resolution call.
+ *
+ * 10s assumes a hosted model. A local Ollama model needs ~7s for a ONE-WORD
+ * reply, so a 600-token resolution over a dozen candidates never lands: it
+ * aborts, the router falls back to its evidence-only decision, and
+ * `mayAssumeInterpretation` goes false — which sends every ambiguous question to
+ * the clarification gate (AGT-017). The effect is that a local model cannot
+ * answer anything ambiguous, in a product whose whole positioning is local-first.
+ *
+ * Scaled by the same `DQL_AGENT_DEADLINE_SCALE` as the run budget, so one
+ * setting moves the provider's whole time envelope together rather than leaving
+ * an inner bound to silently cap an outer one.
+ */
+/**
+ * Predict how long the next provider call will take, for admission control.
+ *
+ * With fewer than three samples the MAX is the only honest predictor: there is
+ * no distribution yet, and admitting a call the deadline then kills wastes the
+ * whole remaining budget.
+ *
+ * With a real sample, p75 rather than the max. One slow response — a cold model
+ * load, a retried connection — otherwise poisons admission control for the rest
+ * of the run: every later call is refused against a worst case that already
+ * passed. A recorded run tripped RUN_DEADLINE_INSUFFICIENT 6.4s into a 45s
+ * budget for exactly that reason. p75 still errs slow, so a genuinely slow
+ * provider is still respected.
+ */
+export function predictDispatchMs(observed, assumedMs = ASSUMED_PROVIDER_DISPATCH_MS) {
+    if (observed.length === 0)
+        return assumedMs;
+    const sorted = [...observed].sort((left, right) => left - right);
+    if (sorted.length < 3)
+        return sorted[sorted.length - 1];
+    const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.75) - 1));
+    return sorted[index];
+}
+const AGENT_MEANING_TIMEOUT_BASE_MS = 10_000;
+const AGENT_MEANING_TIMEOUT_MS = AGENT_MEANING_TIMEOUT_BASE_MS * deadlineScale();
 export function boundedAgentMeaningSignal(signal, timeoutMs = AGENT_MEANING_TIMEOUT_MS) {
     const timeout = AbortSignal.timeout(Math.max(1, timeoutMs));
     return signal ? AbortSignal.any([signal, timeout]) : timeout;
@@ -30043,49 +30599,9 @@ function scoreAgentValueProbeColumn(table, column) {
     return score;
 }
 export function isAgentValueProbeColumn(column) {
-    const name = column.name.toLowerCase();
-    // Tokenize underscore/camel names before applying the hard deny-list. This is
-    // intentionally independent of an allowlist: secrets and free-text payloads
-    // can never be probed through automatic grounding.
-    const normalizedName = column.name
-        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-        .replace(/[_-]+/g, ' ')
-        .toLowerCase();
-    if (/\b(password|secret|token|credential|hash|salt|notes?|comments?|description|message|body|payload|content)\b/.test(normalizedName))
-        return false;
-    if (/\bemail\b/.test(normalizedName))
-        return false;
-    if (!hasAgentSchemaToken(name, [
-        'account',
-        'category',
-        'channel',
-        'city',
-        'code',
-        'country',
-        'customer',
-        'email',
-        'full',
-        'id',
-        'key',
-        'member',
-        'name',
-        'number',
-        'product',
-        'region',
-        'segment',
-        'sku',
-        'state',
-        'status',
-        'subscriber',
-        'type',
-        'user',
-    ])) {
-        return false;
-    }
-    const type = column.type?.toLowerCase() ?? '';
-    if (!type)
-        return true;
-    return /\b(char|character|clob|email|string|text|uuid|varchar)\b/.test(type);
+    // Delegates to the canonical predicate in dql-agent. Two copies of a security
+    // rule drift, and the one that drifts is the one nobody is looking at.
+    return isProbeSafeColumn({ name: column.name, ...(column.type ? { type: column.type } : {}) });
 }
 export function buildAgentValueProbeSql(table, column, searchTerms, connection) {
     const relation = quoteAgentRelation(table.relation, connection);