@duckcodeailabs/dql-cli 1.14.0 → 1.14.2

package/dist/llm/providers/dql-agent-provider.js

@@ -1,6 +1,11 @@
-import { ClaudeProvider, KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, GeminiProvider, loadAgentSemanticLayer, OllamaProvider, OpenAIProvider, answer, buildAnalysisQuestionPlan, buildLocalContextPack, contextRetrievalBudgetForQuestion, ensureAgentProjectReady, isLikelyClarificationReply, isTrustedConversationTurn, createProviderDispatchEgressReceipt, createProviderEgressReceipt, assertProviderPayloadAllowed, prepareProviderContextForDispatch, prepareProviderWireEnvelopeForDispatch, prepareServerOwnedProviderSchemaContext, } from '@duckcodeailabs/dql-agent';
+import { classifyProviderFailure, deadlineScale, planAnalystTurn, rerankCandidates, } from '@duckcodeailabs/dql-agent';
+import { buildAnalystLoopTools } from '../analyst-loop-tools.js';
+import { ClaudeProvider, KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, GeminiProvider, loadAgentSemanticLayer, OllamaProvider, OpenAIProvider, answer, buildAnalysisQuestionPlan, buildLocalContextPack, contextRetrievalBudgetForQuestion, ensureAgentProjectReady, isLikelyClarificationReply, isTrustedConversationTurn, createProviderDispatchEgressReceipt, createProviderEgressReceipt, assertProviderPayloadAllowed, prepareProviderContextForDispatch, prepareProviderWireEnvelopeForDispatch, prepareServerOwnedProviderSchemaContext, projectEmbeddingProvider, answerAgentic, qualifyAuthorizationReferences, scopeContextPackToExploratoryCandidateClosure, createAnalystLaneHandler, parseProposal, renderContextValidationRefusalForUser, validateSqlAgainstLocalContext, resolveOrchestratorPolicy, } from '@duckcodeailabs/dql-agent';
+import { CassetteStore, evalCassetteCanonicalizationV2, resolveCassetteModeFromEnv, withCassette, } from '../../commands/agent-eval-cassette.js';
 import { buildManifest, normalizeDqlArtifactReference, resolveDbtManifestPath } from '@duckcodeailabs/dql-core';
-import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { buildAnswerLoopTools, createGroundingContextExpander } from '../answer-loop-tools.js';
 import { getSemanticRuntimeStatus } from '../../semantic-runtime.js';
 import { blockProposalDqlMetadata } from '../proposal-metadata.js';
@@ -71,6 +76,39 @@ const SPECS = {
         },
     },
 };
+/**
+ * Capture a content-free provider failure at the closest boundary. Local
+ * runtime may later choose a user-facing headline, but must not need raw
+ * provider errors or URLs to reconstruct the cause.
+ */
+function providerBoundaryDiagnostic(input) {
+    const config = getEffectiveProviderConfig(input.projectRoot, input.providerId);
+    const message = input.error instanceof Error ? input.error.message : String(input.error ?? 'provider readiness failed');
+    const code = input.code
+        ?? (input.error && typeof input.error === 'object' ? String(input.error.code ?? '') : '');
+    const fingerprint = (value) => value?.trim()
+        ? `sha256:${createHash('sha256').update(value.trim()).digest('hex')}`
+        : undefined;
+    let origin;
+    if (config.baseUrl) {
+        try {
+            origin = new URL(config.baseUrl).origin;
+        }
+        catch {
+            // The full malformed URL never leaves this function; its fingerprint is
+            // still a useful support correlation key without disclosing content.
+            origin = config.baseUrl;
+        }
+    }
+    return classifyProviderFailure({
+        code,
+        message,
+        phase: input.phase,
+        providerFingerprint: fingerprint(input.providerId),
+        modelFingerprint: fingerprint(config.model),
+        baseOriginFingerprint: fingerprint(origin),
+    });
+}
 function createCertifiedFitConfirmation(provider, signal) {
     return async ({ question, questionPlan, block, fit }) => {
         const response = await provider.generate([
@@ -224,6 +262,40 @@ function stringArray(value) {
 function stringValue(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
 }
+/**
+ * A precomputed exploratory pack is an optimization/witness only. The runner
+ * independently derives the pack from the immutable router-selected IDs and
+ * accepts the witness only when its snapshot, source fingerprint, physical
+ * relations, and metadata object set are exactly the same. This prevents a
+ * caller from replacing a safe same-snapshot closure with a broader one.
+ */
+function exploratoryClosureMatches(derived, witness) {
+    if (!derived)
+        return false;
+    if (derived.knowledgeLens.snapshotId !== witness.knowledgeLens.snapshotId)
+        return false;
+    if (derived.freshness.fingerprint !== witness.freshness.fingerprint)
+        return false;
+    const normalize = (value) => value
+        .trim()
+        .split('.')
+        .map((part) => part.trim().replace(/^["`\[]|["`\]]$/g, '').toLowerCase())
+        .filter(Boolean)
+        .join('.');
+    const sameSet = (left, right) => {
+        if (left.length !== right.length)
+            return false;
+        const rightSet = new Set(right);
+        return left.every((value) => rightSet.has(value));
+    };
+    const derivedRelations = [...new Set(derived.allowedSqlContext.relations.map((relation) => normalize(relation.relation)))].sort();
+    const witnessRelations = [...new Set(witness.allowedSqlContext.relations.map((relation) => normalize(relation.relation)))].sort();
+    if (!sameSet(derivedRelations, witnessRelations))
+        return false;
+    const derivedObjects = [...new Set(derived.objects.map((object) => object.objectKey))].sort();
+    const witnessObjects = [...new Set(witness.objects.map((object) => object.objectKey))].sort();
+    return sameSet(derivedObjects, witnessObjects);
+}
 function truncateForFitPrompt(value, max) {
     if (!value)
         return undefined;
@@ -257,12 +329,174 @@ function emitProposalFromText(text, emit) {
         // Ignore malformed proposal text. The visible assistant response still streams as text.
     }
 }
+/**
+ * Route the runtime's own provider through an eval cassette when the host asks.
+ *
+ * The client-side cassette in `dql agent eval` only covers `--via loop`: with
+ * `--via runtime` the SERVER owns the provider, so without this hook the one
+ * driver that actually exercises routing and gates could never be made
+ * deterministic — and a suite that cannot be deterministic cannot gate a PR.
+ *
+ * Opt-in through the environment, never through a request field: a caller must
+ * not be able to redirect a production run onto recorded responses.
+ */
+/**
+ * Read `agent.orchestrator` straight from dql.config.json.
+ *
+ * Deliberately NOT `loadProjectConfig` from local-runtime: that module imports
+ * this one (local-runtime.ts:164), so reaching back would close an import cycle
+ * through a 34k-line file. A few lines of JSON reading is the cheaper trade.
+ *
+ * Cached by a lightweight file fingerprint, not forever. Settings writes must
+ * take effect for the next Ask without requiring a notebook-server restart.
+ * A malformed file resolves to `null`, which `resolveOrchestratorPolicy` turns
+ * into `legacy` — a broken config must not route real questions onto an
+ * unproven path.
+ */
+const agentConfigCache = new Map();
+function agentConfigFingerprint(projectRoot) {
+    try {
+        const stats = statSync(join(projectRoot, 'dql.config.json'));
+        return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}`;
+    }
+    catch {
+        return 'missing';
+    }
+}
+function readAgentConfig(projectRoot) {
+    const fingerprint = agentConfigFingerprint(projectRoot);
+    const cached = agentConfigCache.get(projectRoot);
+    if (cached && cached.fingerprint === fingerprint)
+        return cached.value;
+    let resolved = null;
+    try {
+        const raw = readFileSync(join(projectRoot, 'dql.config.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        resolved = parsed?.agent && typeof parsed.agent === 'object'
+            ? parsed.agent
+            : null;
+    }
+    catch {
+        resolved = null;
+    }
+    agentConfigCache.set(projectRoot, { fingerprint, value: resolved });
+    return resolved;
+}
+function readOrchestratorConfig(projectRoot) {
+    const orchestrator = readAgentConfig(projectRoot)?.orchestrator;
+    return orchestrator && typeof orchestrator === 'object' ? orchestrator : null;
+}
+/**
+ * Is on-demand value lookup permitted for this project?
+ *
+ * Mirrors `resolveAgentRuntimeValueGrounding`, read locally rather than imported
+ * — local-runtime imports this module, so reaching back would close a cycle
+ * through a 34k-line file. Anything other than an explicit `safe_automatic`
+ * resolves to disabled: value lookup touches warehouse cell values, so a
+ * malformed setting must fail closed.
+ */
+/**
+ * Structured turn planning is OFF by default.
+ *
+ * It costs one provider dispatch before the loop makes any tool call, and on a
+ * slow provider that dispatch can consume enough of the discovery window that
+ * the loop is then refused admission and falls back to the legacy path —
+ * measured on ollama, where all three agentic dispatches planned successfully
+ * and then died at "soft target elapsed before this provider dispatch could
+ * start". Its payoff is a legible trace, and `onStep` is not wired to SSE yet,
+ * so today it buys nothing a user can see. Opt in with
+ * `agent.orchestrator.turnPlanning: true` once streaming lands.
+ */
+function turnPlanningEnabled(projectRoot) {
+    const orchestrator = readAgentConfig(projectRoot)?.orchestrator;
+    if (!orchestrator || typeof orchestrator !== 'object')
+        return false;
+    return orchestrator.turnPlanning === true;
+}
+function valueLookupEnabled(projectRoot) {
+    const grounding = readAgentConfig(projectRoot)?.runtimeValueGrounding;
+    if (!grounding || typeof grounding !== 'object')
+        return false;
+    return grounding.mode === 'safe_automatic';
+}
+/**
+ * Which migration lane this turn belongs to.
+ *
+ * Research is identified by the server-resolved `orchestrationMode`, not by
+ * `analysisDepth`. A reader can ask Ask AI to think deeply without opting into
+ * the Research workflow, its wider dispatch budget, or any row-bearing tools.
+ *
+ * Deliberately coarse: the seam only needs to know which bucket a turn falls in
+ * so a lane can be enabled independently. The fine-grained triage between
+ * certified, semantic, and generated stays inside the answer path, where the
+ * retrieval evidence lives.
+ */
+function agenticLaneForRequest(req) {
+    return req.orchestrationMode === 'research' ? 'research' : 'generated';
+}
+export function applyEvalCassette(provider, projectRoot) {
+    const dir = process.env.DQL_EVAL_CASSETTE_DIR;
+    if (!dir)
+        return provider;
+    return withCassette(provider, new CassetteStore(dir), resolveCassetteModeFromEnv(process.env), evalCassetteCanonicalizationV2(projectRoot));
+}
+/**
+ * Create a replay-only provider when the runtime is launched for an offline
+ * evaluation. This is intentionally unavailable outside explicit cassette
+ * replay: recording and live modes still require a configured real provider.
+ *
+ * The cassette's recorded provider identity is part of its key. Recover it
+ * from a single-provider cassette directory instead of borrowing a user's
+ * active provider or guessing from an API setting. The base provider cannot
+ * make a network call; replay misses remain CassetteMissError failures.
+ */
+export function createEvalCassetteReplayProvider(projectRoot) {
+    const dir = process.env.DQL_EVAL_CASSETTE_DIR;
+    if (!dir || resolveCassetteModeFromEnv(process.env) !== 'replay')
+        return undefined;
+    const store = new CassetteStore(dir);
+    const providerNames = store.providerNames();
+    const providerName = providerNames.length === 1 ? asAgentProviderName(providerNames[0]) : undefined;
+    if (!providerName)
+        return undefined;
+    return withCassette({
+        name: providerName,
+        available: async () => true,
+        generate: async () => {
+            throw new Error('Eval cassette replay miss: no live provider is available.');
+        },
+    }, store, 'replay', evalCassetteCanonicalizationV2(projectRoot));
+}
+function asAgentProviderName(value) {
+    return value === 'claude' || value === 'openai' || value === 'gemini' || value === 'ollama'
+        ? value
+        : undefined;
+}
+/**
+ * A raw text provider for planning calls that are not the answer itself.
+ *
+ * Research hypothesis planning needs `generate`, not the full agent runner —
+ * and the runner cannot be reused for it, because the runner IS the governed
+ * answer path. Cassettes apply, so a recorded run stays hermetic.
+ */
+export function createGovernedTextProvider(id, projectRoot) {
+    const spec = SPECS[id];
+    if (!spec)
+        return undefined;
+    try {
+        return applyEvalCassette(spec.create(projectRoot), projectRoot);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createDqlAgentProviderRunner(id, providerOverride) {
     return {
         async run(req, emit, signal) {
             const spec = SPECS[id];
-            const rawProvider = providerOverride ?? spec.create(req.projectRoot);
-            const isResearch = req.analysisDepth === 'deep';
+            const rawProvider = applyEvalCassette(providerOverride ?? spec.create(req.projectRoot), req.projectRoot);
+            const isResearch = req.orchestrationMode === 'research';
+            const maxProviderDispatches = isResearch ? 8 : 4;
             const researchRowsOptIn = isResearch && req.researchResultRowsOptIn === true;
             const sharedDispatchEvidence = req.providerDispatchEvidenceSink;
             let providerRoundTrips = 0;
@@ -296,7 +530,7 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                 // A tool-calling loop capped at two physical sends can make exactly one
                 // tool call before it must answer, which is not enough to look something
                 // up and then use it. The run-scoped ledger is the real guardrail.
-                maxProviderDispatches: isResearch ? 8 : 4,
+                maxProviderDispatches,
                 ...(sharedDispatchEvidence?.mayStartToolCall
                     ? { mayStartToolCall: () => sharedDispatchEvidence.mayStartToolCall() }
                     : {}),
@@ -360,15 +594,41 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     return envelope;
                 },
             });
+            // One retry only, on the SAME configured provider and only for failures
+            // that are normally transient. The physical-dispatch observer remains in
+            // the path for both attempts, so a retry cannot exceed the run-wide
+            // dispatch budget or silently fail over to another provider.
+            let transientRetryUsed = false;
+            const mayRetrySameProvider = (error) => {
+                if (signal.aborted || transientRetryUsed)
+                    return false;
+                const code = error && typeof error === 'object' ? String(error.code ?? '') : '';
+                const message = error instanceof Error ? error.message : String(error ?? '');
+                const diagnostic = `${code} ${message}`;
+                return !/PROVIDER_DISPATCH_BUDGET|RUN_SOFT_TARGET|RUN_DEADLINE|PROJECT_SNAPSHOT|abort|cancel/i.test(diagnostic)
+                    && /(?:429|rate limit|too many requests|502|503|504|gateway|econn|network|fetch failed|connection refused|timeout|timed out)/i.test(diagnostic);
+            };
+            const retrySameProviderOnce = async (operation) => {
+                try {
+                    return await operation();
+                }
+                catch (error) {
+                    if (!mayRetrySameProvider(error))
+                        throw error;
+                    transientRetryUsed = true;
+                    emit({ kind: 'thinking', text: 'The configured AI provider had a transient error; retrying it once within this run budget.' });
+                    return operation();
+                }
+            };
             const provider = {
                 name: rawProvider.name,
                 available: () => rawProvider.available(),
                 generate: (...args) => {
-                    return rawProvider.generate(args[0], withPhysicalDispatchObserver(args[1]));
+                    return retrySameProviderOnce(() => rawProvider.generate(args[0], withPhysicalDispatchObserver(args[1])));
                 },
                 ...(rawProvider.generateWithTools ? {
                     generateWithTools: (...args) => {
-                        return rawProvider.generateWithTools(args[0], args[1], withPhysicalDispatchObserver(args[2]));
+                        return retrySameProviderOnce(() => rawProvider.generateWithTools(args[0], args[1], withPhysicalDispatchObserver(args[2])));
                     },
                 } : {}),
                 ...(rawProvider.generateStream ? {
@@ -379,7 +639,20 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
             };
             const available = await provider.available().catch(() => false);
             if (!available) {
-                emit({ kind: 'error', message: `${spec.label} is not configured or reachable. ${spec.setup}` });
+                const message = `${spec.label} is not configured or reachable. ${spec.setup}`;
+                emit({
+                    kind: 'error',
+                    message,
+                    providerDiagnostic: providerBoundaryDiagnostic({
+                        providerId: id,
+                        projectRoot: req.projectRoot,
+                        phase: 'preflight',
+                        error: message,
+                        // Local Ollama readiness is a reachability concern; configured
+                        // remote providers missing credentials are authentication issues.
+                        code: id === 'ollama' ? 'NETWORK_FAILURE' : 'AUTHENTICATION_FAILED',
+                    }),
+                });
                 return;
             }
             try {
@@ -439,6 +712,14 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         strictness: contextBudget.strictness,
                         limit: contextBudget.limit,
                         confirmCertifiedFit: createCertifiedFitConfirmation(provider, signal),
+                        // A cross-encoder pass over the fused candidates. Advisory: it may
+                        // only reorder what retrieval returned, and a failure or timeout
+                        // leaves retrieval's ordering untouched — so it can improve the
+                        // pack and cannot break it.
+                        rerankCandidates: (rerankQuestion, candidates) => rerankCandidates(provider, rerankQuestion, candidates, {
+                            ...(signal ? { signal } : {}),
+                            timeoutMs: Math.round(2_500 * deadlineScale()),
+                        }),
                         // Conversation-aware reuse: same-topic follow-ups seed (or, for
                         // filter-only refinements, re-stamp) the prior turn's context pack.
                         priorContextPackId: priorContextPackIdFromSnapshot(conversationSnapshot),
@@ -502,6 +783,63 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     const schemaContext = req.getSchemaContext && shouldLoadSchemaContext(contextPack, Boolean(semanticLayer))
                         ? await req.getSchemaContext(question, contextPack).catch(() => [])
                         : [];
+                    // The router's exploratory candidate IDs are server-owned execution
+                    // authority. Once that tier is selected, provider prompt/schema
+                    // context must be the candidate closure rather than the broad
+                    // retrieval pack. The latter remains available to the host for
+                    // receipts only and cannot be used to introduce another relation.
+                    const forcedExploratoryTier = req.selectedCascadeTier === 'exploratory_sql';
+                    // Re-derive the closure from the broad immutable pack and the
+                    // router-selected IDs. `preparedExploratoryContextPack` is only a
+                    // server-side consistency witness; it cannot override or widen the
+                    // derivation even if a future caller constructs an AgentRunner
+                    // request directly.
+                    const derivedExploratoryContextPack = forcedExploratoryTier
+                        ? scopeContextPackToExploratoryCandidateClosure(contextPack, req.exploratoryCandidateIds)
+                        : undefined;
+                    const closureWitnessMatches = !req.preparedExploratoryContextPack
+                        || exploratoryClosureMatches(derivedExploratoryContextPack, req.preparedExploratoryContextPack);
+                    const exploratoryContextPack = closureWitnessMatches
+                        ? derivedExploratoryContextPack
+                        : undefined;
+                    if (forcedExploratoryTier && (!exploratoryContextPack || !req.exploratoryCandidateIds?.length)) {
+                        const text = 'The router-selected exploratory path no longer has a complete same-snapshot physical closure, so DQL did not send SQL generation or execute a query.';
+                        emit({
+                            kind: 'tool_result',
+                            id: 'governed_answer',
+                            output: {
+                                kind: 'no_answer',
+                                sourceTier: 'no_answer',
+                                certification: 'analyst_review_required',
+                                reviewStatus: 'none',
+                                confidence: 0,
+                                text,
+                                answer: text,
+                                refusalCode: 'grounding_gap',
+                                refusalDetails: {
+                                    code: closureWitnessMatches ? 'EXPLORATORY_CLOSURE_UNAVAILABLE' : 'EXPLORATORY_CLOSURE_MISMATCH',
+                                    message: text,
+                                },
+                                contextPack,
+                                providerUsed: provider.name,
+                            },
+                        });
+                        return;
+                    }
+                    const answerContextPack = forcedExploratoryTier
+                        ? exploratoryContextPack ?? contextPack
+                        : contextPack;
+                    const normalizeQualifiedRelation = (value) => value
+                        .trim()
+                        .split('.')
+                        .map((part) => part.trim().replace(/^["`\[]|["`\]]$/g, '').toLowerCase())
+                        .filter(Boolean)
+                        .join('.');
+                    const closureRelations = new Set((exploratoryContextPack?.allowedSqlContext.relations ?? [])
+                        .map((relation) => normalizeQualifiedRelation(relation.relation)));
+                    const answerSchemaContext = forcedExploratoryTier && closureRelations.size > 0
+                        ? schemaContext.filter((table) => closureRelations.has(normalizeQualifiedRelation(table.relation)))
+                        : schemaContext;
                     const schemaDurationMs = Date.now() - schemaStartedAt;
                     const selectedBlockHints = shouldUseSelectedBlockHint(req, question, followUp)
                         ? extractSelectedBlockHints(req)
@@ -524,8 +862,8 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         question,
                         ...(conversationSnapshot ? { conversationSnapshot } : {}),
                         ...(memoryContext ? { memoryContext } : {}),
-                        schemaContext: prepareServerOwnedProviderSchemaContext(schemaContext),
-                        ...(contextPack ? { contextPack } : {}),
+                        schemaContext: prepareServerOwnedProviderSchemaContext(answerSchemaContext),
+                        ...(answerContextPack ? { contextPack: answerContextPack } : {}),
                         skills,
                         ...(followUp ? { followUp } : {}),
                     }), {
@@ -533,11 +871,23 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         maxResultRows: 0,
                         purpose: 'answer_generation',
                     });
-                    const result = await answer({
+                    // The strangler seam. `answerAgentic` and `answer` are interchangeable
+                    // here; which runs is a per-lane config decision that defaults to
+                    // legacy, so this is a no-op until a lane is explicitly enabled.
+                    const answerLoopInput = {
                         question,
                         ...(req.resolvedAnalyticalPlan
                             ? { resolvedAnalyticalPlan: req.resolvedAnalyticalPlan }
                             : {}),
+                        ...(req.selectedCascadeTier
+                            ? { selectedCascadeTier: req.selectedCascadeTier }
+                            : {}),
+                        ...(req.exploratoryCandidateIds?.length
+                            ? { exploratoryCandidateIds: [...req.exploratoryCandidateIds] }
+                            : {}),
+                        ...(req.generatedProposalTargetFingerprint
+                            ? { generatedProposalTargetFingerprint: req.generatedProposalTargetFingerprint }
+                            : {}),
                         ...(req.analyticalReferenceInstant
                             ? { analyticalReferenceInstant: req.analyticalReferenceInstant }
                             : {}),
@@ -555,7 +905,7 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         followUp,
                         conversationSnapshot,
                         memoryContext,
-                        schemaContext,
+                        schemaContext: answerSchemaContext,
                         semanticLayer,
                         // Runtime-aware executability for metric SELECTION: with a full
                         // semantic runtime active (dbt Cloud / MetricFlow CLI) every
@@ -567,7 +917,13 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                                 canExecuteSemanticMetric: (metricName) => semanticRuntimeActive !== 'native' || semanticLayer.canComposeMetric(metricName),
                             }
                             : {}),
-                        contextPack,
+                        contextPack: answerContextPack,
+                        // The project's configured embedder (dql.config.json ai.embeddings).
+                        // Without it, matchSemanticMetric falls back to the offline hashed
+                        // provider, whose vectors can never ground a match on similarity
+                        // alone — so a metric named only by synonym or acronym is invisible
+                        // and the router dead-ends on a bare-ranking clarification.
+                        embeddingProvider: projectEmbeddingProvider(req.projectRoot),
                         signal,
                         reasoningEffort: req.reasoningEffort,
                         analysisDepth: contextBudget.analysisDepth,
@@ -583,6 +939,41 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         executeGeneratedSql: req.executeGeneratedSql
                             ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeGeneratedSql(...args); }
                             : undefined,
+                        prepareExploratorySqlExecution: req.prepareExploratorySqlExecution
+                            ? async (sql, ...args) => {
+                                guardSnapshot();
+                                // The execution host repeats this validation immediately
+                                // before capability minting. Keep the same exact-qualified
+                                // closure check here as well, before the provider runner can
+                                // even invoke that host boundary. A provider response cannot
+                                // use another same-snapshot relation merely because it was
+                                // present in broad retrieval diagnostics.
+                                if (forcedExploratoryTier && exploratoryContextPack) {
+                                    const proposalValidation = validateSqlAgainstLocalContext(sql, exploratoryContextPack, {
+                                        runtimeSchema: answerSchemaContext,
+                                    });
+                                    const outsideClosure = !proposalValidation.ok
+                                        || proposalValidation.referencedRelations.some((relation) => !closureRelations.has(normalizeQualifiedRelation(relation)));
+                                    if (outsideClosure) {
+                                        throw Object.assign(new Error('The generated SQL references a relation outside the router-selected physical closure, so it was not executed.'), { code: 'UNAUTHORIZED_SQL' });
+                                    }
+                                }
+                                return req.prepareExploratorySqlExecution(sql, ...args);
+                            }
+                            : undefined,
+                        executeAgenticGeneratedSql: req.executeAgenticGeneratedSql
+                            ? async (capability, sql, artifact) => {
+                                guardSnapshot();
+                                sqlExecutions += 1;
+                                return req.executeAgenticGeneratedSql(capability, sql, artifact);
+                            }
+                            : undefined,
+                        agenticExecutionScope: {
+                            runId: req.agentRunId,
+                            snapshotId: req.projectSnapshot?.snapshotId,
+                            planId: req.resolvedAnalyticalPlan?.planId,
+                            targetFingerprint: req.generatedProposalTargetFingerprint,
+                        },
                         executeDqlArtifact: req.executeDqlArtifact
                             ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeDqlArtifact(...args); }
                             : undefined,
@@ -623,6 +1014,111 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         // NOTE: no captureGeneratedDraft here — a plain answer/research question must NOT
                         // auto-write a draft into the blocks space. A draft is created only when the user
                         // explicitly acts (the "Create DQL draft" action → the dql_block_draft route).
+                    };
+                    const result = await answerAgentic(answerLoopInput, {
+                        policy: resolveOrchestratorPolicy({
+                            config: readOrchestratorConfig(req.projectRoot),
+                        }),
+                        lane: agenticLaneForRequest(req),
+                        legacy: answer,
+                        // The generated lane runs the analyst loop: it verifies every
+                        // identifier against a tool observation before the SQL is executed.
+                        // Certified and semantic lanes are deliberately NOT registered —
+                        // their answers already come from a governed contract, so a
+                        // verification pass would add latency and no safety.
+                        handlers: {
+                            generated: createAnalystLaneHandler({
+                                legacy: answer,
+                                buildDeps: (loopInput) => {
+                                    const execute = loopInput.executeGeneratedSql;
+                                    const valuesEnabled = valueLookupEnabled(req.projectRoot);
+                                    const tools = buildAnalystLoopTools(loopInput, { valuesEnabled });
+                                    if (process.env.DQL_ORCHESTRATOR_TRACE) {
+                                        console.warn(`[dql] analyst loop deps: tools=${tools.length} preview=${Boolean(execute)} values=${valuesEnabled}`);
+                                    }
+                                    if (tools.length === 0)
+                                        return undefined;
+                                    return {
+                                        tools,
+                                        maxIterations: resolveOrchestratorPolicy({
+                                            config: readOrchestratorConfig(req.projectRoot),
+                                        }).maxIterations,
+                                        // Match the physical wrapper cap and reserve the final
+                                        // composition dispatch: an ordinary cap of four permits
+                                        // at most three text-protocol tool observations.
+                                        maxProviderDispatches,
+                                        // Scaled by the same knob as every other agent deadline, so
+                                        // a local model that needs seconds per call is not planned
+                                        // out of existence by a budget calibrated for a hosted one.
+                                        ...(turnPlanningEnabled(req.projectRoot) ? {
+                                            planTurn: async (question, toolNames) => {
+                                                const plan = await planAnalystTurn(loopInput.provider, question, toolNames, {
+                                                    timeoutMs: Math.round(2_500 * deadlineScale()),
+                                                    ...(loopInput.signal ? { signal: loopInput.signal } : {}),
+                                                });
+                                                if (process.env.DQL_ORCHESTRATOR_TRACE) {
+                                                    console.warn(plan
+                                                        ? `[dql] analyst turn plan: "${plan.restatement}" establish=${plan.mustEstablish.length} opening=${plan.openingTool ?? 'unset'}`
+                                                        : '[dql] analyst turn plan: unavailable (loop proceeds unplanned)');
+                                                }
+                                                return plan;
+                                            },
+                                        } : {}),
+                                        // The loop's trace, on the channel the provider already uses
+                                        // for progress. `thinking` turns become `onProgress`, which
+                                        // the run engine emits as `executor.started` over SSE — so
+                                        // this needs no new event type, no contract change, and no
+                                        // UI work. Without it the loop does real work (tool calls,
+                                        // identifier checks, a bounded repair) behind a silent
+                                        // spinner, which reads as a hang rather than as an analyst
+                                        // establishing facts.
+                                        onStep: (step) => {
+                                            emit({
+                                                kind: 'thinking',
+                                                text: step.detail ? `${step.label} — ${step.detail}` : step.label,
+                                            });
+                                        },
+                                        // Reuse the legacy parser and validator rather than forking
+                                        // a second SQL front end that would drift from the first.
+                                        parseSql: (raw) => parseProposal(raw).sql,
+                                        extractReferences: (sql) => {
+                                            const validation = validateSqlAgainstLocalContext(sql, loopInput.contextPack);
+                                            const qualified = qualifyAuthorizationReferences(sql, {
+                                                relations: validation.referencedRelations ?? [],
+                                                columns: validation.referencedColumns ?? [],
+                                            });
+                                            return {
+                                                relations: validation.referencedRelations ?? [],
+                                                columns: qualified.filter((reference) => !validation.referencedRelations?.includes(reference)),
+                                            };
+                                        },
+                                        // The safety verifiers keep their logic; only what happens on
+                                        // failure changes. Instead of ending the turn, the specific
+                                        // check that fired comes back as something the model can act
+                                        // on — "joining those tables multiplies rows" rather than
+                                        // "nothing was executed".
+                                        verifySql: (sql) => {
+                                            const validation = validateSqlAgainstLocalContext(sql, loopInput.contextPack);
+                                            if (validation.ok)
+                                                return undefined;
+                                            return renderContextValidationRefusalForUser(validation.code, validation.error, loopInput.followUp?.memberBindings, validation.aggregationSafetyProof?.issueCodes);
+                                        },
+                                    };
+                                },
+                            }),
+                        },
+                        onDiagnostic: (event) => {
+                            if (event.kind === 'fallback') {
+                                console.warn(`[dql] agentic orchestrator fell back on ${event.lane}: ${event.reason}`);
+                            }
+                            else if (process.env.DQL_ORCHESTRATOR_TRACE) {
+                                // Opt-in dispatch trace. A migration where the new path silently
+                                // never runs looks identical to one where it runs and agrees,
+                                // and that ambiguity costs more to debug than the log costs to
+                                // carry.
+                                console.warn(`[dql] agentic orchestrator dispatched lane=${event.lane} mode=${event.mode}`);
+                            }
+                        },
                     });
                     const answerDurationMs = Date.now() - answerStartedAt;
                     // CTX-002: an answer built from one snapshot must never be published
@@ -652,7 +1148,7 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         sqlExecutions,
                         repairs: result.analysisPlan?.repairAttempts ?? 0,
                     };
-                    if (req.analysisDepth === 'deep' && !providerEgressReceipts.some((receipt) => receipt.purpose === 'research_tool')) {
+                    if (isResearch && !providerEgressReceipts.some((receipt) => receipt.purpose === 'research_tool')) {
                         providerEgressReceipts.push(createProviderEgressReceipt({
                             purpose: 'research_tool',
                             provider: provider.name,
@@ -724,6 +1220,19 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     dispatchEvidence: dispatchEvidence(orchestrationBudgetExhausted ? 'orchestration_budget_exhausted'
                         : snapshotDrift ? 'project_snapshot_mismatch'
                             : 'provider_error'),
+                    providerDiagnostic: providerBoundaryDiagnostic({
+                        providerId: id,
+                        projectRoot: req.projectRoot,
+                        phase: orchestrationBudgetExhausted
+                            ? 'planning'
+                            : 'generation',
+                        error: err,
+                        code: orchestrationBudgetExhausted
+                            ? 'PROVIDER_DISPATCH_BUDGET'
+                            : snapshotDrift
+                                ? 'ADMISSION_DENIED'
+                                : budgetCode,
+                    }),
                 });
             }
         },
@@ -1097,6 +1606,28 @@ function resolveAgentFollowUpContextRaw(rawContext, question) {
     const context = rawContext;
     if (!context)
         return undefined;
+    const taskDependency = analyticalTaskDependencyBindingFromContext(context);
+    // A compound child receives exactly one server-computed parent value plus
+    // result/row proofs. Do not replay parent prose, SQL, or result rows into the
+    // child; its normal governed retrieval and immutable-plan checks still run.
+    if (taskDependency) {
+        return {
+            kind: 'drilldown',
+            sourceTurnId: `task:${taskDependency.sourceTaskId}`,
+            filters: [taskDependency.value],
+            dimensions: [taskDependency.canonicalColumn],
+            priorResultColumns: [taskDependency.canonicalColumn],
+            priorResultValues: { [taskDependency.canonicalColumn]: [taskDependency.value] },
+            memberBindings: [{
+                    dimension: taskDependency.canonicalColumn,
+                    values: [taskDependency.value],
+                    source: 'prior_result',
+                    confidence: 'exact',
+                    sourceTurnId: `task:${taskDependency.sourceTaskId}`,
+                }],
+            resolvedReferences: [`${taskDependency.canonicalColumn}: ${taskDependency.value}`],
+        };
+    }
     const turns = conversationTurnsFromContext(context);
     const activeTurn = activeConversationTurn(context, turns, question);
     const activeResult = activeTurn?.result && typeof activeTurn.result === 'object' && !Array.isArray(activeTurn.result)
@@ -1193,6 +1724,21 @@ function resolveAgentFollowUpContextRaw(rawContext, question) {
         priorResult: relativeComparison ? undefined : priorResultDataFromTurn(activeResult, priorResultColumns),
     };
 }
+function analyticalTaskDependencyBindingFromContext(context) {
+    const raw = cleanRecord(context.analyticalTaskDependencyBinding);
+    if (!raw || raw.version !== 1)
+        return undefined;
+    const sourceTaskId = cleanOptionalString(raw.sourceTaskId);
+    const sourceResultFingerprint = cleanOptionalString(raw.sourceResultFingerprint)?.toLowerCase();
+    const canonicalColumn = cleanOptionalString(raw.canonicalColumn);
+    const value = cleanOptionalString(raw.value);
+    const rowFingerprint = cleanOptionalString(raw.rowFingerprint)?.toLowerCase();
+    if (!sourceTaskId || !canonicalColumn || !value
+        || !/^[a-f0-9]{64}$/.test(sourceResultFingerprint ?? '')
+        || !/^[a-f0-9]{64}$/.test(rowFingerprint ?? ''))
+        return undefined;
+    return { sourceTaskId, sourceResultFingerprint: sourceResultFingerprint, canonicalColumn, value, rowFingerprint: rowFingerprint };
+}
 /** Build the bounded prior-result rows (aligned to columns) for cross-result
  *  follow-up computation, from a turn's persisted result sample. */
 function priorResultDataFromTurn(activeResult, columns) {
@@ -1776,6 +2322,7 @@ function normalizePriorValueDimension(value) {
     return lower.replace(/[_\s-]+name$/, '').replace(/[^a-z0-9_ -]+/g, '').trim();
 }
 export const __test__ = {
+    agenticLaneForRequest,
     applyTopicShiftGuard,
     isDrilldownFollowUp,
     buildAnswerLoopTools,
@@ -1789,6 +2336,8 @@ export const __test__ = {
     shouldSearchProjectFiles,
     renderProjectSourceSearch,
     researchDispatchPurposeForTool,
+    readAgentConfig,
+    providerBoundaryDiagnostic,
 };
 function researchDispatchPurposeForTool(toolName) {
     return toolName === 'execute_local_analysis' ? 'research_tool' : 'research_narration';